Initial signal-cal-bot skeleton: iCalendar feed to Signal group

- feed fetch with ETag/Last-Modified caching
- iCalendar parsing/expansion with TEC series detection
- posting-window scheduler with 3-day reminders and day-of fallback
- image attachments from ATTACH, downscaled via Pillow
- SQLite outbox with idempotent deliveries
- watchdog alerts to Note to Self
- Docker Compose with signal-cli-rest-api
This commit is contained in:
2026-11-18 15:44:56 +00:00
commit 234c990e84
21 changed files with 2629 additions and 0 deletions
+126
View File
@@ -0,0 +1,126 @@
# calbot — iCalendar → Signal
Watches an iCalendar feed (built for The Events Calendar / MCR Commons) and posts
events to a Signal group, with the event's poster image attached.
Posts look like this:
```
Folk Night
#November #November14
4.30-6.30pm
Old Print Works B12 9AH
https://commonscalendar.uk/event/folk-night/
```
## How it behaves
- **Announcements** — a newly seen event is posted within one refresh interval,
deferred to the next posting window (`08:00–10:00` or `18:00–21:00` by default).
- **Reminders** — every event is posted again 3 days before it starts. If the
event was added less than 3 days ahead, the reminder goes out on the morning
of the event instead. An imminent event breaks the posting window rather than
arriving late.
- **Images** — taken from the feed's `ATTACH` property (The Events Calendar
emits the featured image), falling back to the event page's JSON-LD / `og:image`.
Every post carries an image.
- **Recurring events** — the feed pre-expands occurrences, but announcements are
deduplicated per series, so adding a weekly event produces one announcement.
- **First run** — seeds silently (`announce.backfill = false`); reminders still
work for everything already in the feed.
- **Watchdog** — messages you on Signal if the feed stops working, parses to
nothing, or sending keeps failing.
## Setup
### 1. Link a Signal account
Linking as a secondary device is the quickest route: the bot posts **as your own
number**. For a separate bot identity you must register a dedicated number
instead (see `signal-cli-rest-api` docs).
```bash
mkdir -p signal-data data cache
docker compose up -d signal-api
```
Open <http://localhost:8080/v1/qrcodelink?device_name=calbot> and scan the QR
code from **Signal → Settings → Linked devices**.
```bash
# the linked number:
curl -s http://localhost:8080/v1/accounts
# groups for that number — copy the internal_id (starts with "group."):
curl -s http://localhost:8080/v1/groups/+447700900000 | jq
```
### 2. Configure
```bash
cp config.example.toml config.toml
chmod 600 config.toml
$EDITOR config.toml
```
Fill in `signal.number`, `signal.group_id`, and `calendar.url`. `webcal://`
URLs are accepted and fetched over https.
### 3. Check, preview, run
```bash
# is the account linked and the config valid?
docker compose run --rm bot python -m calbot --check
# print the rendered posts for the feed without sending anything
docker compose run --rm bot python -m calbot --dump
# start the bot
docker compose up -d bot
docker compose logs -f bot
```
`--once` runs a single tick and exits.
## Install by hand
```bash
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
calbot --config config.toml --dump
calbot --config config.toml
```
## Files that matter
| Path | Purpose |
|---|---|
| `config.toml` | numbers, group, feed, behaviour (never committed) |
| `signal-data/` | linked-device keys — **back this up**, losing it means re-linking |
| `data/calbot.sqlite3` | event/outbox/delivery state (safe to delete to re-seed) |
| `cache/images/` | downscaled posters |
Deleting `data/calbot.sqlite3` resets dedupe state: on the next run everything
is seeded silently again, so you will not get a flood, but new-series detection
restarts from that moment.
## Notes and limits
- Signal has no bot API; this uses [`signal-cli`](https://github.com/AsamK/signal-cli)
via [`signal-cli-rest-api`](https://github.com/bbernhard/signal-cli-rest-api).
- Delivery is **at-least-once**. A crash between sending and recording can
duplicate one post.
- The feed is capped by The Events Calendar (30 events by default) and may omit
past events; the bot only knows what the feed contains.
- Venue/postcode come from the ICS `LOCATION` when present (this feed often has
none), then from the event page's structured data, then from the description.
## Tests
```bash
pip install -e '.[dev]'
pytest
```
Fixtures are stored as `tests/fixtures/*.ics.txt` so that `*.ics` can stay
gitignored.