rss-thread-watcher/README.org

#+OPTIONS: toc:nil
* RSS based thread watcher

Get notifications from your feed reader when your favourite thread is about to die

** Usage

1) Open your RSS feed reader (you have one right?)
2) Add your custom URL (see getting custom URL)
3) Enable notifications in your feed reader and set update interval to 5minutes or more (you can set less but the feed is updated
   only every 5 minutes)
4) Profit! RSS feed will include only the threads matching your querry so every notification your feed reader will send means your
   watched thread is about to die

*NOTE THAT THIS IS AN BETA RELEASE, IF YOUR THREAD DIES BECAUSE OF RSS-WATCHER MALLFUNCTION DO NOT BLAME ME* pls

** Getting custom URL

URL without any params (just ~/feed~) won't work. You must specify at least one ~q~ or ~Q~. See bellow.

*** Crafting URL by hand

Right now there is no automated way to generate your feed url but making one by hand is fairly simple.

**** URL parameters

Please note that default values may vary depending on which instance/host/board you use, these are the defaults that come with
this software but anyone running instance of RSS thread watcher can change them

| Param name | Values [default]        | Can have multiple? | Mandatory?              | Short description                                                                                |
|------------+-------------------------+--------------------+-------------------------+--------------------------------------------------------------------------------------------------|
| board      | "mlp"                   | No                 | No                      | Which board to generate feed for, only boards enabled by host will work                          |
| q          | nil                     | Yes                | Yes (1 or more)         | This string is used to filter threads according to their titles, *REGEX NOT supported* yet       |
| Q          | nil                     | Yes                | No if ~q~ is present    | This string is used to filter threads according to their titles, but is CaseSensitive            |
| chod       | 60-99 [94]              | No                 | No                      | CHanceOfDeath - will include thread in the feed if it's chance to death is > chod                |
| repeat     | true, paranoid, [false] | No                 | No (partly implemented) | Whether to make new notification on every server update even when thread doesnt have higher chod |
| recreate   | ~bool~                  | Not implemented    | Not implemented         | Whether to notify when creation of new thread matching querry is detected (uses 4chans RSS)      |

**** How to create URL

Standart rules of URLs apply, if you know how to pass params in URL to any website, you don't even have to read this

- Open some text editor
- Paste in default URL: ~https://tools.treebrary.org/thread-watcher/feed?~ (you can use plain HTTP if you want to)
- Now you can append any of the supported parameters (which you can find in the above table):
- For example if we want to be informed about threads with "cute" in their title
  - ~q=cute~ which would make ~https://tools.treebrary.org/thread-watcher/feed?q=cute~
- If you want more than one param, separate with ~&~, for example:
  - ~q=cute~ and ~q=pretty~ would be ~https://tools.treebrary.org/thread-watcher/feed?q=cute&q=pretty~
- Same is true for when you also want to specify ChoD
  - ~https://tools.treebrary.org/thread-watcher/feed?q=cute&q=pretty&chod=98~
  - This will only notify you about threads that:
    - Have ~cute~ or ~pretty~ in their title
    - Are in the lowest 98% part of catalog (it's on position ~147/150 e.g. 3 threads before being bumped off)
- Note that ~//~ are not special characters ~q=/general/~ will work as expected and match thread with "​/general​/" in it's title
- Also note that regex is *NOT* supported for now, so something like ~q=rainbow*~ will only match threads with "rainbow" followed
  immedidatelly by ~*~ in their title

*** Generating URL interactively

Coming soon (not really)

** Bugs

See [[https://git.treebrary.org/Treebrary.org/rss-thread-watcher/issues?q=&type=all&state=open&labels=1&milestone=0&assignee=0&poster=0][issues]]

** Feature set

- Planned/finnished features [38%]
  - [X] [DONE] Super basic features done (feed, query, repeat)
  - [X] Have proper sorting - The most likely to die threads first
  - [X] No params request should redirect to url generator or (for now) documentation
  - [X] Config file instead of hardcoding config values
  - [ ] Include time of latest data fetch
  - [ ] Make threads have preview images taken from the actuall thread OP
  - [ ] Show which query matched the thread you were notified of
  - [ ] Option to include advanced HTML formating of text (different color text for ChoD etc)
  - [ ] Support notification on watched thread re-creation after it died
  - [ ] Support notification for thread death
  - [X] Support multiple boards at once
  - [ ] Support async responses
  - [ ] Graal VM support for native compilation

For more up to date and complete list of features, check [[https://git.treebrary.org/Treebrary.org/rss-thread-watcher/projects][open projects]].

** Self hosting

As of first Beta release, self hosting is supported, please refer to [[file:res/ExampleConfig-documented.edn][documented example config]] for infomration on configuration
options.

*** Prebuilt

Download newest release from [[https://git.treebrary.org/Treebrary.org/rss-thread-watcher/releases][releases]] and run them like you would any other java executable (example bellow). There are two JARs,
first requires you to have Clojure installed (~rss-thread-watch-[version]~), second one doesn't (the one with ~standalone~ in
name).

~$ java -jar whatEverNameTheReleaseHas.jar~

Default port is ~6969~ so either change it or allow it in your firewall. HTTPS is not supported, so using some reverse proxy like
Nginx could be the easiest solution for that.

*** From source
Not officially supported, if you'll attempt this, please, use source from release tarball or checkout ~release~ or ~stable~
branch. ~dev~ branch is unstable and untested, may not even build. ~stable~ branch should always build, may contain newer version
than is released.

If you know Clojure, then just clone and build with lein. If you don't either RTFM for lein or wait before instructions will be
avaiabile here.

*** Configuring

All documentation is for now included in [[file:res/ExampleConfig-documented.edn][documented exmample config]].

*** Contributing

[[https://treebrary.org/about-the-git-server.html][See]]

** License - AGPL3

Copyright © 2023  Felisp

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.