cm_whatsapp_bot_v1/README.md

# 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

**v1 production-ready.** The web app at `wabot.04080616.xyz` is the
primary control surface; the Telegram bot has been removed.

What's working today:

- **Username + password auth** with role-based access (admin / user).
  HttpOnly + Secure session cookies, encrypted with AES-256-GCM (so a
  leaked cookie reveals nothing about userId / role) and bound to the
  `OPERATOR_TOKEN_VERSION` env so a single env bump kills every
  outstanding session.
- **Three-layer login rate limit** — per-IP + per-username (lower-cased
  so case-rotation doesn't help) + a global backstop, so a residential-
  proxy attacker can't brute one account by hopping IPs.
- **Self-hosted Next.js 16 PWA** — installable on a phone home screen.
  Mobile-first single-row header with a slide-out drawer; desktop
  sidebar. Login lives outside the shell on a bare-header surface.
- **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.
- **Duplicate-pair detection** — scanning a QR with a phone already
  linked to another account row surfaces a clear "already paired as
  <label>" message instead of fighting Baileys for the device.
- **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. 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. Optional "Pause sending by" deadline that
  defaults OFF — operators have to opt in explicitly.
- **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 `.mov` videos
  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. Click vs drag is disambiguated by a 6-px tap threshold so a
  swipe doesn't accidentally trigger the row's link.
- **Activity tab** — last 200 runs with status filters (Success /
  Paused / Failed / Archived). Partial runs surface under both Paused
  and Failed; Skipped runs collapse into Archived. Hard-delete and
  archive both 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. Logout-on-delete cleans the operator's
  linked-devices list on the WhatsApp side too.
- **Hardened pg-boss scheduling** — three-tier dedupe so a triple-
  click Save or microsecond-spaced enqueue doesn't fire a reminder
  multiple times. Reschedule cancels stale jobs by singletonKey first
  so a recurring next-fire never gets silently dropped.
- **Drizzle journal monotonicity guard** — `pnpm migrate` refuses to
  run if the `_journal.json` `when` timestamps aren't strictly
  increasing (a recurring foot-gun where drizzle would silently skip
  a freshly-generated migration). CI tests + the migrate runner both
  enforce.
- **All actions audited.** Per-run target results (sent / failed /
  skipped) preserved even when the underlying group is removed.

Test count: **482 web + 88 bot = 570** 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/next` for the PWA shell. `tools` is 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 at `192.168.0.210` in a `wabot` database. All cross-service
communication goes through Postgres (`LISTEN/NOTIFY` for events,
table writes for state).

Full design spec:
[`docs/superpowers/specs/2026-05-09-web-app-design.md`](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`).

```bash
# 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       # writes AUTH_SECRET to .env.development

# 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 the bootstrap operator row
NO_SUDO=1 scripts/db.sh migrate
NO_SUDO=1 scripts/db.sh seed

# 4. Set the bootstrap admin password (NO password is set by seed)
echo 'change-me-now' | scripts/set-password.sh admin

# 5. Open the web app and sign in as `admin` with the password above
#    Local:  http://localhost:9000
#    LAN:    http://<host-ip>:9000
#    Public: https://wabot.04080616.xyz
```

Inside the app: `/settings/users` → Add user → invite teammates with
`user` role; promote / demote / reset password / delete from the same
page. The "Admin" nav entry is admin-only.

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/runbook.md`](docs/runbook.md).

The earlier wizard-only checklist still lives at
[`docs/superpowers/specs/manual-test-web.md`](docs/superpowers/specs/manual-test-web.md).

## Layout

- `apps/bot/` — Baileys WhatsApp + pg-boss scheduler + LISTEN/NOTIFY
  command consumer
- `apps/web/` — Next.js 16 App Router PWA
- `packages/db/` — Drizzle schema and migrations
- `packages/shared/` — cross-app helpers (rrule, media paths,
  timezones, WhatsApp media classifier)
- `docs/runbook.md` — manual end-to-end smoke checklist
- `docs/superpowers/specs/` — design specs and earlier manual test
  runbooks
- `docs/superpowers/plans/` — implementation plans
- `docker/` — Dockerfiles (`tools.Dockerfile`, `bot.Dockerfile`,
  `web.Dockerfile`)
- `scripts/` — `dev.sh`, `db.sh`, `gen_auth_secret.sh`,
  `set-password.sh`, `create-user.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) |
| `scripts/set-password.sh <username>` | Set / reset a user's password (reads stdin) |
| `scripts/create-user.sh <username> <role>` | Create a user from CLI (admin / user) |

Set `NO_SUDO=1` if your user is in the docker group (recommended).

## Auth + admin model

- One bootstrap operator (`admin`) is created by the seed; its
  password is set via `scripts/set-password.sh admin` on first launch.
- Two roles: `admin` (full access including user management) and
  `user` (everything except `/settings/users`). Role-based nav
  filtering is enforced in middleware + the AppShell + every server
  action that mutates user state.
- Every user gets an isolated workspace — accounts, reminders,
  groups, and run history all scope by `operator_id`. The admin
  panel is the only cross-tenant surface.
- Sessions: AES-256-GCM-encrypted cookie keyed off `AUTH_SECRET`,
  HttpOnly + Secure-in-prod + SameSite=Lax, 30-day TTL. The
  `OPERATOR_TOKEN_VERSION` env (defaults to `"1"`) is the kill switch
  — bumping it invalidates every outstanding cookie globally on the
  next request.
- Login rate limits: 10 / 5 min per-IP + 5 / 15 min per-username + a
  100 / min global backstop. The error message is identical for all
  three so the limit-which-tripped isn't leaked.

## Deferred

- **Standalone media library** browser (currently media is uploaded
  per-reminder).
- **E2E browser tests** (Playwright) on the swipe and pairing flows.
- **Search-as-you-type in the wizard's groups picker** — at 3 000+
  groups per account the picker still loads the alphabetical
  top-200; operators with >200 groups need to use the list page's
  search to find anything past 'L'.
- **Self-service password reset** (email link, etc.) — out of scope
  for v1; admins use the Users page.