Compare commits

...
2 Commits
Author SHA1 Message Date
kawaiipunk add77f6cb8 Rename to sigcal-bot
- package src/sigcal_bot, distribution and CLI sigcal-bot
- environment variables SIGCAL_BOT_*
- database file, container names, user agents, logs and QR device name
- docs and changelog updated
2026-11-18 17:06:40 +00:00
kawaiipunk f6d0db664e Document headless linking, dedicated identity and alpha status
- README: SSH-tunnel and QR-as-file linking for headless servers
- README: dedicated-number registration path for a separate bot identity
- README: alpha-quality notice, provenance caveat, non-affiliation
- add CHANGELOG.md (Keep a Changelog, everything under Unreleased)
- AGENTS.md: require Unreleased changelog entries
2026-11-18 17:06:18 +00:00
23 changed files with 212 additions and 60 deletions
+17 -5
View File
@@ -13,7 +13,7 @@ Read `README.md` for the user-facing behaviour and setup.
## Layout
```
src/signal_cal_bot/
src/sigcal_bot/
config.py TOML loading, defaults, duration/time parsers
feed.py conditional GET; validators committed only after parse
expand.py iCalendar -> Event; series-ID heuristics; recurrence expansion
@@ -34,9 +34,9 @@ python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest # must pass, no network
signal-cal-bot --config config.toml --dump # render the feed without sending
signal-cal-bot --config config.toml --check # config + Signal account check
signal-cal-bot --config config.toml --once # one tick
sigcal-bot --config config.toml --dump # render the feed without sending
sigcal-bot --config config.toml --check # config + Signal account check
sigcal-bot --config config.toml --once # one tick
```
`--dump` uses a throwaway database and never sends; keep it that way.
@@ -97,12 +97,24 @@ signal-cal-bot --config config.toml --once # one tick
default, parse it in `load_config`, document it in `config.example.toml` and
the README table.
- **Schema change**: append to `SCHEMA` in `store.py`. There is no migration
framework; deleting `data/signal-cal-bot.sqlite3` re-seeds silently.
framework; deleting `data/sigcal-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.
+52
View File
@@ -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 `sigcal-bot`: Python package
`sigcal_bot`, CLI `sigcal-bot`, environment variables
`SIGCAL_BOT_*`, database `data/sigcal-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.
+1 -1
View File
@@ -13,4 +13,4 @@ RUN pip install .
# The compose file runs the bot as uid/gid 1000; these must be writable.
RUN mkdir -p /app/data /app/cache && chown -R 1000:1000 /app/data /app/cache
CMD ["python", "-m", "signal_cal_bot", "--config", "/app/config.toml"]
CMD ["python", "-m", "sigcal_bot", "--config", "/app/config.toml"]
+104 -16
View File
@@ -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 <http://localhost:8080/v1/qrcodelink?device_name=signal-cal-bot> 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 <http://localhost:8080/v1/qrcodelink?device_name=sigcal-bot>
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=sigcal-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
<https://signalcaptchas.org/registration/generate.html> 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":"<captcha value>"}' \
'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
@@ -113,8 +199,8 @@ https.
### 3. Verify, preview, run
```bash
docker compose run --rm bot python -m signal_cal_bot --check # config + account
docker compose run --rm bot python -m signal_cal_bot --dump # rendered posts, no sending
docker compose run --rm bot python -m sigcal_bot --check # config + account
docker compose run --rm bot python -m sigcal_bot --dump # rendered posts, no sending
docker compose up -d bot
docker compose logs -f bot
```
@@ -123,10 +209,10 @@ docker compose logs -f bot
| Command | Purpose |
|---|---|
| `signal-cal-bot --config config.toml` | Run the loop |
| `signal-cal-bot --once` | Run a single tick and exit |
| `signal-cal-bot --dump` | Print rendered posts for the feed; uses a temporary DB, sends nothing |
| `signal-cal-bot --check` | Validate config and confirm the Signal account is linked |
| `sigcal-bot --config config.toml` | Run the loop |
| `sigcal-bot --once` | Run a single tick and exit |
| `sigcal-bot --dump` | Print rendered posts for the feed; uses a temporary DB, sends nothing |
| `sigcal-bot --check` | Validate config and confirm the Signal account is linked |
All commands accept `--log-level` (or `LOG_LEVEL`).
@@ -172,7 +258,7 @@ All commands accept `--log-level` (or `LOG_LEVEL`).
| Follow logs | `docker compose logs -f bot` |
| Apply config changes | edit `config.toml`, then `docker compose restart bot` |
| Update code | `git pull && docker compose up -d --build` |
| Reset duplicate/seen state | stop bot, delete `data/signal-cal-bot.sqlite3`, start (re-seeds silently) |
| Reset duplicate/seen state | stop bot, delete `data/sigcal-bot.sqlite3`, start (re-seeds silently) |
| Clear image cache | `rm -rf cache/images` |
| Back up | `signal-data/` (linked-device keys) and `config.toml` |
@@ -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
+1 -1
View File
@@ -59,5 +59,5 @@ alert_cooldown_hours = 6
daily_heartbeat = false
[storage]
db = "data/signal-cal-bot.sqlite3"
db = "data/sigcal-bot.sqlite3"
cache = "cache"
+3 -3
View File
@@ -2,7 +2,7 @@
services:
signal-api:
image: bbernhard/signal-cli-rest-api:latest
container_name: signal-cal-bot-signal
container_name: sigcal-bot-signal
restart: unless-stopped
environment:
- MODE=json-rpc-native
@@ -17,13 +17,13 @@ services:
bot:
build: .
container_name: signal-cal-bot
container_name: sigcal-bot
restart: unless-stopped
depends_on:
- signal-api
user: "1000:1000"
environment:
- SIGNAL_CAL_BOT_CONFIG=/app/config.toml
- SIGCAL_BOT_CONFIG=/app/config.toml
- LOG_LEVEL=info
- TZ=Europe/London
volumes:
+2 -2
View File
@@ -1,5 +1,5 @@
[project]
name = "signal-cal-bot"
name = "sigcal-bot"
version = "0.1.0"
description = "Announce iCalendar events to a Signal group"
requires-python = ">=3.11"
@@ -18,7 +18,7 @@ dependencies = [
dev = ["pytest>=8.0", "ruff>=0.6"]
[project.scripts]
signal-cal-bot = "signal_cal_bot.__main__:main"
sigcal-bot = "sigcal_bot.__main__:main"
[build-system]
requires = ["setuptools>=77"]
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (C) 2026 kawaiipunk
"""signal-cal-bot: announce iCalendar events to a Signal group."""
"""sigcal-bot: announce iCalendar events to a Signal group."""
__version__ = "0.1.0"
@@ -28,7 +28,7 @@ from .signal_client import SignalClient
from .store import Store
from .watchdog import Watchdog
log = logging.getLogger("signal_cal_bot")
log = logging.getLogger("sigcal_bot")
TICK_SECONDS = 30
@@ -43,7 +43,7 @@ def _logging(level: str) -> None:
def _http_client() -> httpx.Client:
return httpx.Client(
follow_redirects=True,
headers={"User-Agent": "signal-cal-bot/0.1 (iCalendar to Signal bridge)"},
headers={"User-Agent": "sigcal-bot/0.1 (iCalendar to Signal bridge)"},
limits=httpx.Limits(max_connections=8, max_keepalive_connections=4),
)
@@ -102,11 +102,11 @@ def dump(config: Config) -> int:
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="signal-cal-bot", description=__doc__)
parser = argparse.ArgumentParser(prog="sigcal-bot", description=__doc__)
parser.add_argument(
"--config",
default=os.environ.get("SIGNAL_CAL_BOT_CONFIG", "config.toml"),
help="path to config.toml (default: $SIGNAL_CAL_BOT_CONFIG or ./config.toml)",
default=os.environ.get("SIGCAL_BOT_CONFIG", "config.toml"),
help="path to config.toml (default: $SIGCAL_BOT_CONFIG or ./config.toml)",
)
parser.add_argument("--once", action="store_true", help="run a single tick and exit")
parser.add_argument("--dump", action="store_true", help="print posts for upcoming events")
@@ -142,7 +142,7 @@ def main(argv: list[str] | None = None) -> int:
else:
log.error(
"Signal account %s not found at %s. Link it first: "
"open %s/v1/qrcodelink?device_name=signal-cal-bot and scan the QR code.",
"open %s/v1/qrcodelink?device_name=sigcal-bot and scan the QR code.",
config.signal.number,
config.signal.api_url,
config.signal.api_url,
@@ -175,10 +175,10 @@ def main(argv: list[str] | None = None) -> int:
signal.signal(signal.SIGTERM, stop)
signal.signal(signal.SIGINT, stop)
log.info("signal-cal-bot started (feed=%s, group=%s)", config.calendar.url, config.signal.group_id)
log.info("sigcal-bot started (feed=%s, group=%s)", config.calendar.url, config.signal.group_id)
if not sender.account_exists():
log.warning(
"Signal account not linked yet. Open %s/v1/qrcodelink?device_name=signal-cal-bot",
"Signal account not linked yet. Open %s/v1/qrcodelink?device_name=sigcal-bot",
config.signal.api_url,
)
@@ -191,7 +191,7 @@ def main(argv: list[str] | None = None) -> int:
while not stopping and time.monotonic() < deadline:
time.sleep(0.5)
log.info("signal-cal-bot stopped")
log.info("sigcal-bot stopped")
store.close()
http.close()
sender.close()
@@ -142,7 +142,7 @@ class Config:
images: ImagesConfig = field(default_factory=ImagesConfig)
format: FormatConfig = field(default_factory=FormatConfig)
watchdog: WatchdogConfig = field(default_factory=WatchdogConfig)
db_path: Path = Path("data/signal-cal-bot.sqlite3")
db_path: Path = Path("data/sigcal-bot.sqlite3")
cache_dir: Path = Path("cache")
config_path: Path | None = None
base_dir: Path = Path(".")
@@ -194,8 +194,8 @@ def load_config(path: str | Path) -> Config:
for lead in lead_times:
parse_duration(lead)
db_path = Path(os.environ.get("SIGNAL_CAL_BOT_DB", storage.get("db", "data/signal-cal-bot.sqlite3")))
cache_dir = Path(os.environ.get("SIGNAL_CAL_BOT_CACHE", storage.get("cache", "cache")))
db_path = Path(os.environ.get("SIGCAL_BOT_DB", storage.get("db", "data/sigcal-bot.sqlite3")))
cache_dir = Path(os.environ.get("SIGCAL_BOT_CACHE", storage.get("cache", "cache")))
if not db_path.is_absolute():
db_path = base_dir / db_path
if not cache_dir.is_absolute():
@@ -15,7 +15,7 @@ from .store import Store, from_iso, iso
log = logging.getLogger(__name__)
USER_AGENT = "signal-cal-bot/0.1 (iCalendar to Signal bridge)"
USER_AGENT = "sigcal-bot/0.1 (iCalendar to Signal bridge)"
def normalize_feed_url(url: str) -> str:
@@ -28,7 +28,7 @@ Image.MAX_IMAGE_PIXELS = 50_000_000
MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024
DOWNLOAD_TIMEOUT = 20.0
USER_AGENT = "signal-cal-bot/0.1 (iCalendar to Signal bridge)"
USER_AGENT = "sigcal-bot/0.1 (iCalendar to Signal bridge)"
@dataclass(frozen=True)
@@ -451,7 +451,7 @@ class Bot:
"https://tinyurl.com/api-create.php",
params={"url": url},
timeout=8,
headers={"User-Agent": "signal-cal-bot/0.1"},
headers={"User-Agent": "sigcal-bot/0.1"},
)
if response.status_code == 200 and response.text.strip().startswith("http"):
short = response.text.strip()
@@ -472,7 +472,7 @@ class Bot:
return
try:
self.sender.send(
f"signal-cal-bot alive \u2014 {self.store.count_events()} events in the window",
f"sigcal-bot alive \u2014 {self.store.count_events()} events in the window",
[self.watchdog.recipient],
text_mode=self.config.signal.text_mode,
)
@@ -63,7 +63,7 @@ class Watchdog:
self._last_alert[key] = now
try:
self.sender.send(
f"\u26a0\ufe0f signal-cal-bot\n{text}",
f"\u26a0\ufe0f sigcal-bot\n{text}",
[self.recipient],
text_mode=self.text_mode,
)
+1 -1
View File
@@ -6,7 +6,7 @@ from __future__ import annotations
from datetime import datetime, timezone
from pathlib import Path
from signal_cal_bot.expand import parse_events
from sigcal_bot.expand import parse_events
FIXTURE = Path(__file__).parent / "fixtures" / "tec-like.ics.txt"
+2 -2
View File
@@ -8,8 +8,8 @@ from pathlib import Path
import httpx
from signal_cal_bot.feed import Feed, FeedResponse, normalize_feed_url
from signal_cal_bot.store import Store
from sigcal_bot.feed import Feed, FeedResponse, normalize_feed_url
from sigcal_bot.store import Store
NOW = datetime(2026, 11, 18, 12, 0, tzinfo=timezone.utc)
EMPTY_FEED = b"BEGIN:VCALENDAR\r\nVERSION:2.0\r\nPRODID:-//test//EN\r\nEND:VCALENDAR\r\n"
+3 -3
View File
@@ -6,9 +6,9 @@ from __future__ import annotations
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
from signal_cal_bot.config import FormatConfig
from signal_cal_bot.expand import Event
from signal_cal_bot.format import (
from sigcal_bot.config import FormatConfig
from sigcal_bot.expand import Event
from sigcal_bot.format import (
find_postcode,
format_hashtags,
format_time_range,
+2 -2
View File
@@ -8,8 +8,8 @@ import io
import httpx
from PIL import Image
from signal_cal_bot.config import ImagesConfig
from signal_cal_bot.images import ImageService
from sigcal_bot.config import ImagesConfig
from sigcal_bot.images import ImageService
def make_service(tmp_path, **overrides) -> ImageService:
+6 -6
View File
@@ -9,7 +9,7 @@ from zoneinfo import ZoneInfo
import httpx
from signal_cal_bot.config import (
from sigcal_bot.config import (
AnnounceConfig,
CalendarConfig,
Config,
@@ -20,17 +20,17 @@ from signal_cal_bot.config import (
SignalConfig,
WatchdogConfig,
)
from signal_cal_bot.expand import Event
from signal_cal_bot.feed import Feed, FeedResponse, normalize_feed_url
from signal_cal_bot.scheduler import (
from sigcal_bot.expand import Event
from sigcal_bot.feed import Feed, FeedResponse, normalize_feed_url
from sigcal_bot.scheduler import (
Bot,
clamp_send_at,
in_window,
next_window_start,
reminder_time,
)
from signal_cal_bot.store import PageInfo, Store
from signal_cal_bot.watchdog import Watchdog
from sigcal_bot.store import PageInfo, Store
from sigcal_bot.watchdog import Watchdog
LONDON = ZoneInfo("Europe/London")
UTC = timezone.utc