Files
sigcal/README.md
T
kawaiipunk 234c990e84 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
2026-11-18 15:44:56 +00:00

127 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.