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:
@@ -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.
|
||||
Reference in New Issue
Block a user