yiekheng
8f2ee5df9e
In-tab notification bridge so the operator gets a system notification
when a reminder fires successfully (or partly / fails) and when a
send-test message lands. Foundation for true background push later
(VAPID + service-worker subscription); this lands the wiring so
behaviour is testable today.
Pieces
------
- `lib/notifications.ts` — pure helper module:
* notificationSupport / getPermission — feature detection that
treats the SSR / unsupported-browser case as "denied" so callers
don't have to handle a third state.
* isOptedIn / setOptedIn — localStorage-backed opt-in flag
(key `cmbot.notifications.optedIn`). Survives gracefully when
window is missing or storage throws (private mode / quota).
* showNotification(opts) — gated dispatch returning a discriminated
result ({ ok: true, tag } | { ok: false, reason }) so callers
can fall back to a UI toast on opt-out / unsupported / error.
* reminderFiredToNotification + sendTestDoneToNotification —
pure mappers from the bot's SSE events into notification args.
Skips bookkeeping noise (status === "skipped") and failures
that the in-page toast already shows verbatim.
- `components/notification-manager.tsx` — client component mounted
once at the app shell. Subscribes to `reminder.fired` and
`send_test.done` via useEvents and forwards each through the pure
mappers. Renders no DOM.
- `components/notifications-toggle.tsx` — settings-page card with
three states (unsupported / not-granted / granted+opted-in).
"Send test" button fires a sample notification so the operator
can verify the wiring without waiting for a real reminder. The
blocked-by-browser path points them at site settings instead of
silently doing nothing.
- `app/settings/page.tsx` — new "Notifications" card sits above
the Appearance card.
- `app/layout.tsx` — `<NotificationManager />` rendered alongside
`<Toaster />` inside ThemeProvider so the SSE subscription is
active across all routes.
Bot side
--------
- `apps/bot/src/scheduler/fire-reminder.ts` — emits
`pgNotifyWeb({ type: "reminder.fired", reminderId, runId, status })`
after every run regardless of success/partial/failed. The web
side decides whether to surface it as a notification (skipped is
filtered out client-side).
- send_test.done was already emitted by `ipc/send-test-handler.ts`.
PWA service-worker tests (the original ask before this thread)
--------------------------------------------------------------
- Extracted the Serwist config into `pwa/config.ts` so the choices
(skipWaiting, clientsClaim, navigationPreload, runtimeCaching,
precacheEntries) are pinnable without booting a worker scope.
- 6 tests in `pwa/config.test.ts` lock the surface (no extra keys
appear silently, the manifest passes through unchanged, the
pinned booleans stay where production expects them).
- 6 tests in `app/manifest.webmanifest/route.test.ts` cover the
manifest contract (display=standalone, start_url=/, dark theme
colors match the OS, both icons are PNG + maskable, paths
match committed PNGs in public/).
Test counts
-----------
281 web + 31 shared + 26 bot = 338 total (was 306).
- +6 pwa/config (service-worker config pinning)
- +6 app/manifest.webmanifest (PWA manifest contract)
- +20 lib/notifications (full coverage of mappers + dispatch
gates + SSR / unsupported / blocked / opted-out paths)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cm WhatsApp Reminder Bot
Self-hosted WhatsApp reminder bot. Pair multiple WhatsApp accounts via a browser-based PWA, schedule recurring reminders to groups, and watch the run history all from a phone home-screen icon.
Status
Plans 1, 2, and 3 complete. The web app at wabot.04080616.xyz is
the primary control surface; the Telegram bot has been removed.
What's working today:
- Self-hosted Next.js 16 PWA — installable on a phone home screen. Mobile-first single-row header with a slide-out drawer; desktop sidebar.
- Live QR pairing — server-side Baileys session feeds the QR payload directly into the browser via Server-Sent Events. Scan, see "✅ Connected" within seconds, auto-redirect.
- Multi-account, multi-group reminders — 5-step wizard (Account → Message → When → Groups → Review) plus per-section edit pages so you don't have to walk the wizard end-to-end to fix one field. Active recurrence picker covers Daily / Weekly / Monthly / Yearly with multi-rule support and per-rule fire-time pickers; the rendered description reads as plain English ("Every week on Mon, Wed, Fri at 09:00") not raw cron.
- Multi-message stacks — a reminder can carry multiple ordered parts (text + media), fired in sequence with a 1.5 s gap. Media files swap at any time from the Edit Message page.
- Smart media handling — per-kind WhatsApp size caps (5 MB image,
16 MB video/audio, 100 MB document). HEIC photos and
.movvideos fall back to the document delivery path so they reach the recipient as a downloadable file instead of failing silently. - Swipe-to-act rows — on mobile, swipe a reminder or activity row left for Delete or right for Pause/Restart/Archive. iOS-Mail style.
- Activity tab — last 200 runs with status filters (Success / Partial / Failed / Skipped) plus an Archived tab. Archive a noisy run to keep the main list readable; restore later. Hard-delete always available. Run history survives a reminder deletion.
- Auto-reconnect on transient drops; restart-survival via Baileys session persistence. Pair once, the device stays linked across container restarts.
- All actions audited. Reminder run history queryable from the UI; per-run target results (sent / failed / skipped) preserved even when the underlying group is removed.
Test count: 249 web + 31 shared + 26 bot = 306 passing.
Host requirements
Only Docker. No host Node, pnpm, or any other language toolchain —
everything runs in containers via the long-lived tools sidecar.
Architecture in one paragraph
Two app containers and one external dependency. bot (Node.js) holds
the live Baileys WhatsApp sessions, the pg-boss scheduler, and a
Postgres LISTEN bot.command consumer. web (Next.js 16 App Router
- React 19) is stateless UI: Server Components for reads, Server
Actions for mutations, an SSE endpoint for live updates,
@serwist/nextfor the PWA shell.toolsis a long-running Node 22 + pnpm sidecar used for installs / tests / typechecks / migrations so the host doesn't need a Node toolchain. Postgres lives external at192.168.0.210in awabotdatabase. All cross-service communication goes through Postgres (LISTEN/NOTIFYfor events, table writes for state).
Full design spec:
docs/superpowers/specs/2026-05-09-web-app-design.md
Quick start (dev)
Prerequisites: Docker, the wabot database + waBot role on
192.168.0.210 (with a pg_hba.conf line permitting
192.168.0.0/24).
# 1. Configure env
cp envs/.env.example .env.development
# edit .env.development: real DATABASE_URL, plus the LAN host to expose
scripts/gen_auth_secret.sh --write
# 2. Bring up the stack, install deps
NO_SUDO=1 scripts/dev.sh up
NO_SUDO=1 scripts/dev.sh pnpm install
# 3. Apply migrations and seed your operator row
NO_SUDO=1 scripts/db.sh migrate
NO_SUDO=1 scripts/db.sh seed
# 4. Open the web app
# Local: http://localhost:9000
# LAN: http://<host-ip>:9000 (e.g. http://192.168.0.253:9000)
# Public: https://wabot.04080616.xyz (whatever your reverse proxy serves)
Pair an account: /accounts → "New Account" → enter a label →
"Pair WhatsApp" → scan the QR with WhatsApp's "Linked Devices".
PWA install: phone Chrome → menu → "Install App" / "Add to Home Screen". Launches fullscreen.
NO_SUDO=1 is the right setting if your user is in the docker
group (the default for this repo). Drop it if you need sudo docker.
Manual test runbook
End-to-end checks that unit tests can't cover (live Baileys,
WhatsApp delivery, swipe gestures):
docs/superpowers/specs/manual-test-web.md.
Layout
apps/bot/— Baileys WhatsApp + pg-boss scheduler + LISTEN/NOTIFY command consumerapps/web/— Next.js 16 App Router PWApackages/db/— Drizzle schema and migrationspackages/shared/— cross-app helpers (rrule, media paths, timezones, WhatsApp media classifier)docs/superpowers/specs/— design specs and manual test runbooksdocs/superpowers/plans/— implementation plansdocker/— Dockerfiles (tools.Dockerfile,bot.Dockerfile,web.Dockerfile)scripts/—dev.sh,db.sh,gen_auth_secret.sh
Scripts
All pnpm/tsx/drizzle-kit invocations run inside the tools
container, so no host Node is needed.
| Script | Purpose |
|---|---|
scripts/dev.sh up|down|logs|status|build|exec|pnpm|shell|restart-bot |
Stack lifecycle and tools-container shell |
scripts/db.sh migrate|generate|studio|seed|reset |
Drizzle migration helper |
scripts/gen_auth_secret.sh [--write] |
Generate AUTH_SECRET (host-only, no Node needed) |
Set NO_SUDO=1 if your user is in the docker group (recommended).
Deferred
- Standalone media library browser (currently media is uploaded per-reminder).
- E2E browser tests (Playwright) on the swipe and pairing flows.
- Auth (passkeys / email-password) — bring back if URL exposure becomes a concern. Today the app trusts whatever's in front of the reverse proxy.
- Multi-operator — schema supports
operator_idon every row, but the seed runs as a single operator and there's no /signup or invite flow yet.