diff --git a/AGENTS.md b/AGENTS.md index e3c7f73..aee991b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,10 +99,22 @@ signal-cal-bot --config config.toml --once # one tick - **Schema change**: append to `SCHEMA` in `store.py`. There is no migration framework; deleting `data/signal-cal-bot.sqlite3` re-seeds silently. +## Changelog + +`CHANGELOG.md` is Keep-a-Changelog format. For anything a user of the bot would +notice — behaviour, configuration, CLI, operational requirements — add a bullet +under `## [Unreleased]` in the right group (`Added`, `Changed`, `Fixed`, +`Removed`). Internal refactors and test-only changes do not need entries. + +Never create version headings. No stable release exists yet; versions are cut +only when a release is actually deployed, by renaming Unreleased to +`## [x.y.z] - YYYY-MM-DD`. + ## Before you finish - `pytest` green, `python -m pyflakes src tests` clean. - New behaviour covered by a test (especially failure paths). +- User-visible changes have a `CHANGELOG.md` entry under `## [Unreleased]`. - `config.example.toml`, README and AGENTS.md still accurate. - `git status` shows no `.ics`, `config.toml`, `data/`, `cache/` or `signal-data/` files. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c558327 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,52 @@ +# Changelog + +All notable changes to this project are documented in this file. The format +follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the +project will use [Semantic Versioning](https://semver.org/) once it starts +releasing. + +No stable release has been made yet: every change accumulates under +Unreleased. To make the first release, rename that section to +`## [0.1.0] - YYYY-MM-DD` and start a fresh Unreleased above it. + +## [Unreleased] + +### Added + +- iCalendar feed polling with conditional requests (ETag/Last-Modified); + validators are only committed after a successful parse. +- Event parsing and expansion, including The Events Calendar series detection: + announcements are deduplicated per series, not per occurrence. +- Two posts per event: an announcement when it is first seen, and a reminder + three days before it starts, with a morning-of fallback for events added + less than three days ahead. +- Preferred posting windows with an urgent guard that posts early rather than + after the event has started. +- Batched sending: everything due in a window becomes one message. +- Poster images from the feed's `ATTACH` property, falling back to the event + page's `og:image` / JSON-LD; images are downscaled, cached and attached as + base64 data URIs. +- Event-page scraping for venue name and postcode, cached per URL. +- Watchdog alerts to the operator's own number when the feed or sending fails. +- CLI with run loop, `--once`, `--dump` and `--check`. +- Docker Compose setup pairing the bot with `signal-cli-rest-api`, including + headless device-linking and dedicated-number registration instructions. +- Offline test suite; AGENTS.md; GPL-3.0-or-later licensing; provenance + disclaimer. + +### Changed + +- Renamed from `calbot` to `signal-cal-bot`: Python package + `signal_cal_bot`, CLI `signal-cal-bot`, environment variables + `SIGNAL_CAL_BOT_*`, database `data/signal-cal-bot.sqlite3`. + +### Fixed + +- Connection errors while sending no longer bypass the watchdog. +- Image decoding failures, including decompression bombs, can no longer block + the text post or wedge the outbox. +- Reminders are dropped for events removed from the feed, using the feed's + coverage horizon so the 30-event export cap does not cancel future events. +- Transparent images are composited onto white instead of turning black. +- `--dump` uses a temporary database and no longer touches real state. +- Duplicate postcode no longer appears when the venue name already contains it. diff --git a/README.md b/README.md index cb1c661..9a79a9e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,18 @@ # sigcal-bot — iCal → Signal +> **Alpha software.** This project is alpha quality and has never had a stable +> release. Behaviour, configuration keys and defaults may change without +> notice between commits, and it has not run in a real group for long. Watch +> the first weeks of posts closely. +> > **Disclaimer:** this code was generated by LLMs (several different models) > and has not been audited by a human security professional. Review it before > relying on it, especially before exposing the Signal API, and treat it as > provided without warranty. See [Provenance](#provenance). > -> In general, we reccomend using a fresh Signal identity that is only used for Sigcal bot. +> In general, we recommend using a fresh Signal identity that is only used for sigcal-bot. > -> This project is independant of and not accosiated with Signal, the 501c3 nonprofit. +> This project is independent of and not associated with Signal, the 501(c)(3) nonprofit. Polls an iCalendar feed and posts events to a Signal group, with the event's poster image attached. Built for [Commons Calendar ical feed](https://commonscalendar.uk) (The @@ -78,27 +83,108 @@ committing can duplicate exactly one post. Requirements: Docker (and Docker Compose). A Signal account to link. -### 1. Start signal-cli-rest-api and link a device +### 1. Start signal-cli-rest-api and give the bot an identity ```bash mkdir -p signal-data data cache docker compose up -d signal-api ``` -Open and scan it from -**Signal → Settings → Linked devices**. +The API listens on `127.0.0.1:8080` only (see `docker-compose.yml`), so it is +reachable from the server itself or through an SSH tunnel — not the network. +Keep it that way: anyone who can reach it can send messages as the account. -> Linking as a secondary device means the bot posts **as your own number**. -> For a separate identity, register a dedicated number instead (see the -> `signal-cli-rest-api` docs on `/v1/register`). +There are two ways to give the bot a Signal identity. -Fetch the linked number and the group ID: +#### A. Link to your own account (default, quickest) + +The bot becomes a linked device of your phone, like Signal Desktop, and every +post appears **as your number**. There is nothing to register — you scan a QR +code once. + +**Linking on a headless server.** `/v1/qrcodelink` returns a QR *image* that +the phone must scan, and the server has no browser. Either: + +- **SSH tunnel (easiest).** From your laptop: + + ```bash + ssh -L 8080:localhost:8080 you@server + ``` + + Then open + in your local browser and scan it from + **Signal → Settings → Linked devices → +**. + +- **Fetch the QR as a file.** On the server: + + ```bash + curl -s "http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot" \ + -o /tmp/link-qr.png + ``` + + Copy it somewhere with a screen (`scp server:/tmp/link-qr.png .`, or + `ssh server cat /tmp/link-qr.png > link-qr.png`), display it, and scan it + with the phone. The QR rotates on every request and the link session is + short-lived: if the scan fails, request a fresh one. Delete the file + afterwards. + +Then read back the number and the group ID: ```bash curl -s http://localhost:8080/v1/accounts curl -s http://localhost:8080/v1/groups/+447700900000 | jq -r '.[].internal_id' ``` +#### B. Register a dedicated number (separate bot identity) + +Linking means every post looks like *you* wrote it. For a community group it is +often better to give the bot its own Signal account — its own name and avatar, +not tied to any member, so people do not mistake reminders for a person +speaking, and the bot can be handed over without touching anyone's phone. + +You need a number that can receive an SMS or voice call. A spare SIM or +pay-as-you-go eSIM works; Signal blocks most VoIP providers (Twilio and +similar), so do not plan around one. + +1. Signal requires a captcha for registrations made from a server. Open + in a browser, open + the developer console, and find the blocked navigation to + `signalcaptcha://{value}` — copy everything after `signalcaptcha://`. +2. Register the number with that captcha: + + ```bash + curl -X POST -H "Content-Type: application/json" \ + -d '{"captcha":""}' \ + 'http://localhost:8080/v1/register/+447700900123' + ``` + + Add `"use_voice": true` to receive the code by voice call instead of SMS. +3. Enter the code you receive: + + ```bash + curl -X POST 'http://localhost:8080/v1/register/+447700900123/verify/123-456' + ``` + +4. Give the account a recognisable name and avatar through the profile endpoint + (see the [API docs](https://bbernhard.github.io/signal-cli-rest-api/)). +5. Have a group admin **add the bot's number to the group like a normal + contact** (do not try to link it as a device). Then fetch the group ID with + the bot's number: + + ```bash + curl -s http://localhost:8080/v1/groups/+447700900123 | jq -r '.[].internal_id' + ``` + +Caveats for the dedicated-number route: + +- The registration lives in `signal-data/`. Losing it **loses the account**: + there is no phone to re-link from, and re-registering needs a new captcha and + sometimes a cooldown. +- Signal reclaims numbers that go unused for a long time. If the calendar might + be quiet for months, enable `watchdog.daily_heartbeat` so the account keeps + some activity. +- The bot's number is visible to every member of the group. + ### 2. Configure ```bash @@ -205,6 +291,8 @@ an audited library: particularly around network failure modes. - Treat the defaults, comments and claims here as best effort. Verify behaviour against your own feed and Signal setup before relying on it in production. +- The project is **alpha** and unreleased: expect breaking changes, and do not + treat any config key or default as stable until a version is tagged. ## Limitations