- 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
127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# 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.
|