feat: initial commit

README.md

@@ -0,0 +1,87 @@
+# ntfy → Matrix bridge
+
+A small daemon that watches a set of [ntfy](https://ntfy.sh) topics and forwards
+every notification to a Matrix room. Define which topics go where in a simple
+YAML config.
+
+It is built to run unattended:
+
+- one streaming connection per mapping, with exponential-backoff reconnect
+- resume via ntfy's `since=<message_id>`, so nothing is lost across reconnects
+  or restarts (the last-forwarded id is persisted to `state.json`)
+- a single Matrix sender that retries on failure; the resume cursor only
+  advances once the homeserver has accepted the message (at-least-once delivery)
+
+> **Unencrypted rooms only.** The target Matrix room must not be end-to-end
+> encrypted. Supporting E2EE would require a persistent crypto store, a stable
+> device id, and a sync loop — deliberately out of scope here.
+
+## Setup
+
+### 1. Create a bot account and get an access token
+
+Create a normal user on your homeserver for the bot (e.g. `@ntfybot:example.org`),
+then run the helper to log in and print an access token:
+
+```bash
+python login.py
+```
+
+Copy the printed `access_token` (and optionally `device_id`) for the next step.
+
+### 2. Configure
+
+```bash
+cp config.example.yaml config.yaml
+```
+
+Edit `config.yaml`. The token is best supplied via the environment rather than
+written into the file — `${VAR}` in any value is expanded from the environment:
+
+```bash
+export MATRIX_ACCESS_TOKEN="syt_...."
+```
+
+Each entry under `mappings` ties a set of topics on one ntfy server to one
+Matrix room. Use the room's **internal id** (`!abcd...:example.org`, found under
+room settings → Advanced), not its human alias. Make sure the bot has **joined**
+each target room.
+
+### 3. Run
+
+```bash
+python bridge.py --config config.yaml
+```
+
+You should see a `subscribed` line per mapping. Publish a test message:
+
+```bash
+curl -d "hello from ntfy" https://ntfy.sh/your-topic
+```
+
+## Running as a service (systemd)
+
+```bash
+sudo useradd --system --home /opt/ntfy-matrix-bridge ntfybridge
+sudo cp -r . /opt/ntfy-matrix-bridge
+sudo python3 -m venv /opt/ntfy-matrix-bridge/venv
+sudo /opt/ntfy-matrix-bridge/venv/bin/pip install -r /opt/ntfy-matrix-bridge/requirements.txt
+sudo cp ntfy-matrix-bridge.service /etc/systemd/system/
+# edit the unit to set MATRIX_ACCESS_TOKEN (or point EnvironmentFile at a secrets file)
+sudo systemctl daemon-reload
+sudo systemctl enable --now ntfy-matrix-bridge
+journalctl -u ntfy-matrix-bridge -f
+```
+
+## Notes
+
+- **Formatting.** Title is bold, the body follows, recognised ntfy tags become
+  emoji (others are listed as text), and `click`/attachment URLs become links.
+  Priority 4/5 get a coloured marker.
+- **`msgtype`.** `m.text` (default) triggers notifications in clients; switch a
+  mapping to `m.notice` if you want it quieter.
+- **`priority_min`.** Optionally drop low-priority messages per mapping.
+- **State.** Delete `state.json` to forget the resume position; on the next
+  start each mapping begins live (no historical replay).
+- ntfy.sh caches messages for a few hours, so short outages are recoverable; a
+  self-hosted server needs caching enabled for resume to work across restarts.