yiekheng/cm_whatsapp_bot_v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cm_whatsapp_bot_v1/docs/superpowers/plans/2026-05-03-foundation-and-pairing.md
yiekheng 2122182c56 docs(plan): refactor plan 1 to Docker-first 
Reorganize plan 1 so a long-lived `tools` container running Node 22 + pnpm
is the entry point for every install/test/typecheck/migration command. The
host only needs Docker — no Node or pnpm install required. Tasks reordered
so the tools container exists before any pnpm operation; new tasks added
for the bootstrap install and env-file population.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-09 15:05:49 +08:00

3249 lines
91 KiB
Markdown
Raw Blame History

# Foundation & WhatsApp Pairing MVP — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Stand up the monorepo, database schema, dev tooling, and a working `bot` service that lets the operator pair a WhatsApp account through Telegram (QR delivered, scanned, account marked connected, groups synced). End-to-end manual test passes against the dev mock account.
**Architecture:** pnpm workspace + Turbo. `apps/bot` Node service uses Baileys for WhatsApp, grammy for Telegram, Drizzle for Postgres. Two shared packages: `packages/db` (schema + migrations) and `packages/shared` (types + helpers). Postgres lives external at `192.168.0.210`. **Everything runs in Docker — there is no host requirement beyond Docker itself.** A long-running `tools` container holds Node 22 + pnpm and is the entry point for every install/test/typecheck/migration command. Web app and reminder scheduling are deferred to later plans.
**Tech Stack:** TypeScript, Node 22 (in containers only), pnpm 9 (in containers only), Turbo, Drizzle ORM, Postgres, Baileys (`@whiskeysockets/baileys`), grammy, qrcode, pino, zod, Vitest, Docker Compose.
**Pre-flight checks before starting:**
- Docker reachable on the dev machine (sudo or docker group).
- Postgres at `192.168.0.210` reachable from this machine *and* from the Docker bridge (`172.16.0.0/12`). `pg_hba.conf` permits both.
- Two databases exist on that Postgres instance: `whatsapp_bot_dev` and `whatsapp_bot_prod`. Two roles with passwords. (`whatsapp_bot_prod` is unused in this plan but creating it now keeps schemas aligned.)
- Two Telegram bots created via `@BotFather`: one for dev (e.g. `@cm_wabot_dev_bot`), one for prod. Save both tokens.
- One WhatsApp account dedicated as the dev mock — a spare phone or secondary number, NOT your brother's real account.
- Your Telegram user ID known (DM `@userinfobot` to see it).
**Spec reference:** `docs/superpowers/specs/2026-05-03-whatsapp-bot-design.md`
---
## File structure produced by this plan
```
cm_whatsapp_bot_v1/
├── .gitignore
├── .nvmrc Node 22 (informational only)
├── package.json workspace root
├── pnpm-workspace.yaml
├── turbo.json
├── tsconfig.base.json
├── README.md
│
├── apps/
│ └── bot/
│ ├── package.json
│ ├── tsconfig.json
│ ├── vitest.config.ts
│ └── src/
│ ├── index.ts bootstrap, graceful shutdown
│ ├── env.ts zod env validation
│ ├── env.test.ts
│ ├── logger.ts
│ ├── db.ts drizzle client
│ ├── health.ts internal HTTP server
│ ├── audit.ts
│ ├── audit.test.ts
│ ├── telegram/
│ │ ├── bot.ts
│ │ ├── middleware/
│ │ │ ├── whitelist.ts
│ │ │ ├── whitelist.test.ts
│ │ │ └── audit.ts
│ │ └── commands/
│ │ ├── start.ts
│ │ ├── help.ts
│ │ ├── pair.ts
│ │ ├── unpair.ts
│ │ ├── accounts.ts
│ │ └── groups.ts
│ └── whatsapp/
│ ├── session-manager.ts
│ ├── session-manager.test.ts
│ ├── session.ts
│ ├── qr-renderer.ts
│ ├── qr-renderer.test.ts
│ └── group-sync.ts
│
├── packages/
│ ├── db/
│ │ ├── package.json
│ │ ├── tsconfig.json
│ │ ├── drizzle.config.ts
│ │ ├── src/
│ │ │ ├── index.ts
│ │ │ ├── schema.ts
│ │ │ ├── migrate.ts
│ │ │ └── seed.ts
│ │ └── migrations/
│ └── shared/
│ ├── package.json
│ ├── tsconfig.json
│ ├── vitest.config.ts
│ └── src/
│ ├── index.ts
│ ├── rrule.ts
│ ├── rrule.test.ts
│ ├── media-paths.ts
│ └── timezones.ts
│
├── docker/
│ ├── tools.Dockerfile Node 22 + pnpm sidecar (long-lived)
│ ├── bot.Dockerfile
│ └── web.Dockerfile placeholder for plan 3
│
├── docker-compose.base.yml
├── docker-compose.dev.yml
│
├── envs/
│ └── .env.example
├── .env.development
│
├── scripts/
│ ├── dev.sh up | down | logs | status | exec | pnpm | shell
│ ├── db.sh
│ ├── gen_auth_secret.sh
│ ├── link-account.sh stub for plan 2
│ └── publish.sh stub for plan 4
│
└── docs/
└── superpowers/
├── plans/
│ └── 2026-05-03-foundation-and-pairing.md
└── specs/
├── 2026-05-03-whatsapp-bot-design.md
└── manual-test-pairing.md
```
---
## Task 1: Git remote and .gitignore
**Files:**
- Create: `.gitignore`
- [ ] **Step 1: Add the Gitea remote**
```bash
cd /home/yiekheng/projects/cm_whatsapp_bot_v1
git remote add origin http://192.168.0.215:3000/yiekheng/cm_whatsapp_bot_v1.git
git remote -v
```
Expected: prints `origin http://192.168.0.215:3000/yiekheng/cm_whatsapp_bot_v1.git (fetch)` and `(push)`.
- [ ] **Step 2: Create `.gitignore`**
```gitignore
# deps
node_modules/
.pnpm-store/
# build outputs
dist/
.next/
.turbo/
*.tsbuildinfo
# env files: per project decision, .env.development and .env.production
# ARE committed to this private Gitea. Only ignore example overrides:
.env.local
.env.*.local
# logs
*.log
npm-debug.log*
pnpm-debug.log*
# editor
.vscode/
.idea/
*.swp
.DS_Store
# runtime data (mounted volumes from compose)
dev-data/
data/
# test coverage
coverage/
.vitest-cache/
```
- [ ] **Step 3: Commit**
```bash
git add .gitignore
git -c commit.gpgsign=false commit -m "chore: add .gitignore and configure remote"
```
---
## Task 2: Root workspace files (no install yet)
**Files:**
- Create: `package.json`
- Create: `pnpm-workspace.yaml`
- Create: `turbo.json`
- Create: `tsconfig.base.json`
- Create: `.nvmrc`
These files only define the workspace shape; `pnpm install` is not run until the tools container exists in Task 6.
- [ ] **Step 1: Create `.nvmrc`** (informational; the tools container is the source of truth)
```
22
```
- [ ] **Step 2: Create `pnpm-workspace.yaml`**
```yaml
packages:
- "apps/*"
- "packages/*"
```
- [ ] **Step 3: Create `package.json`**
```json
{
"name": "cm-whatsapp-bot",
"version": "0.1.0",
"private": true,
"packageManager": "pnpm@9.12.0",
"engines": {
"node": ">=22"
},
"scripts": {
"build": "turbo run build",
"dev": "turbo run dev --parallel",
"test": "turbo run test",
"lint": "turbo run lint",
"typecheck": "turbo run typecheck"
},
"devDependencies": {
"turbo": "^2.1.0",
"typescript": "^5.5.0"
}
}
```
- [ ] **Step 4: Create `turbo.json`**
```json
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"dev": {
"cache": false,
"persistent": true
},
"test": {
"dependsOn": ["^build"],
"outputs": ["coverage/**"]
},
"lint": {},
"typecheck": {
"dependsOn": ["^build"]
}
}
}
```
- [ ] **Step 5: Create `tsconfig.base.json`**
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022"],
"strict": true,
"noUncheckedIndexedAccess": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"skipLibCheck": true,
"resolveJsonModule": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"isolatedModules": true,
"verbatimModuleSyntax": true
},
"exclude": ["node_modules", "dist", ".next", ".turbo"]
}
```
- [ ] **Step 6: Commit**
```bash
git add package.json pnpm-workspace.yaml turbo.json tsconfig.base.json .nvmrc
git -c commit.gpgsign=false commit -m "chore: initialize pnpm workspace + Turbo config"
```
---
## Task 3: Tools image and minimal compose
**Files:**
- Create: `docker/tools.Dockerfile`
- Create: `docker-compose.base.yml`
- Create: `docker-compose.dev.yml`
- [ ] **Step 1: Create `docker/tools.Dockerfile`**
```dockerfile
FROM node:22-alpine
# Lightweight build deps for any future native modules (qrcode is pure JS;
# baileys uses precompiled libsignal). git is needed by some pnpm workflows.
RUN apk add --no-cache git python3 make g++ \
&& corepack enable \
&& corepack prepare pnpm@9.12.0 --activate
WORKDIR /workspace
ENV PNPM_HOME=/workspace/.pnpm-store
CMD ["tail", "-f", "/dev/null"]
```
- [ ] **Step 2: Create `docker-compose.base.yml`**
```yaml
services:
tools:
build:
context: .
dockerfile: docker/tools.Dockerfile
image: cm-whatsapp-tools:dev
container_name: cmbot-tools
user: "${HOST_UID:-1000}:${HOST_GID:-1000}"
working_dir: /workspace
command: ["tail", "-f", "/dev/null"]
volumes:
- .:/workspace
environment:
HOME: /tmp
PNPM_HOME: /workspace/.pnpm-store
DATABASE_URL: ${DATABASE_URL}
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-unset}
TELEGRAM_OPERATOR_WHITELIST: ${TELEGRAM_OPERATOR_WHITELIST:-0}
TELEGRAM_QR_CHAT_ID: ${TELEGRAM_QR_CHAT_ID:-0}
DATA_DIR: ${DATA_DIR:-/data}
SESSIONS_DIR: ${SESSIONS_DIR:-/data/sessions}
MEDIA_DIR: ${MEDIA_DIR:-/data/media}
BOT_HEALTH_PORT: ${BOT_HEALTH_PORT:-8081}
BOT_LOG_LEVEL: ${BOT_LOG_LEVEL:-info}
SEED_OPERATOR_TELEGRAM_ID: ${SEED_OPERATOR_TELEGRAM_ID:-0}
SEED_OPERATOR_NAME: ${SEED_OPERATOR_NAME:-Operator}
networks:
- cmbot
networks:
cmbot:
driver: bridge
```
- [ ] **Step 3: Create `docker-compose.dev.yml`** (initially with only the tools service; bot is added in Task 12)
```yaml
services:
tools:
image: cm-whatsapp-tools:dev
build:
context: .
dockerfile: docker/tools.Dockerfile
```
- [ ] **Step 4: Commit**
```bash
git add docker/tools.Dockerfile docker-compose.base.yml docker-compose.dev.yml
git -c commit.gpgsign=false commit -m "chore: add tools container + base/dev compose"
```
---
## Task 4: scripts/dev.sh with exec / pnpm subcommands
**Files:**
- Create: `scripts/dev.sh`
- [ ] **Step 1: Create `scripts/dev.sh`**
```bash
#!/usr/bin/env bash
# Lifecycle for the local dev stack. All language tooling (pnpm, tests,
# typecheck, drizzle-kit) runs in the long-running `tools` container.
set -euo pipefail
usage() {
cat <<'EOF'
Lifecycle for the local dev stack.
Usage:
scripts/dev.sh up Start all dev services in the background.
scripts/dev.sh down Stop the stack.
scripts/dev.sh logs [service] Tail logs (all services, or one).
scripts/dev.sh status Print 'OK' if tools is running, else exit 1.
scripts/dev.sh build [service] Build images without starting.
scripts/dev.sh exec <cmd...> Run a command inside the tools container.
scripts/dev.sh pnpm <args...> Shortcut for: exec pnpm <args>
scripts/dev.sh shell Open an interactive shell in tools.
scripts/dev.sh restart-bot Recreate the bot container only.
Environment:
NO_SUDO=1 Skip the 'sudo' prefix (use if your user is in the docker group).
EOF
}
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "${ROOT_DIR}"
# Export host UID/GID so the tools container can write files owned by you.
export HOST_UID="$(id -u)"
export HOST_GID="$(id -g)"
SUDO="sudo"
[[ "${NO_SUDO:-0}" == "1" ]] && SUDO=""
COMPOSE=(${SUDO} docker compose --env-file .env.development -f docker-compose.base.yml -f docker-compose.dev.yml)
case "${1:-}" in
-h|--help|help) usage; exit 0 ;;
"") usage >&2; exit 1 ;;
esac
if [[ ! -f .env.development ]]; then
echo "ERROR: .env.development not found at repo root." >&2
echo " Copy envs/.env.example and fill in real values." >&2
exit 2
fi
cmd="${1}"
shift || true
case "${cmd}" in
up)
"${COMPOSE[@]}" up -d --build
"${COMPOSE[@]}" ps
;;
down)
"${COMPOSE[@]}" down --remove-orphans
;;
logs)
if [[ $# -ge 1 ]]; then
"${COMPOSE[@]}" logs -f "$1"
else
"${COMPOSE[@]}" logs -f
fi
;;
status)
if "${COMPOSE[@]}" ps --status running --services 2>/dev/null | grep -q '^tools$'; then
echo OK
else
echo "ERROR: tools container not running. Run 'scripts/dev.sh up' first." >&2
exit 1
fi
;;
build)
"${COMPOSE[@]}" build "$@"
;;
exec)
if [[ $# -lt 1 ]]; then
echo "ERROR: exec requires a command" >&2
exit 2
fi
"${COMPOSE[@]}" exec -T tools "$@"
;;
pnpm)
"${COMPOSE[@]}" exec -T tools pnpm "$@"
;;
shell)
"${COMPOSE[@]}" exec tools sh
;;
restart-bot)
"${COMPOSE[@]}" up -d --force-recreate --no-deps bot
;;
*)
echo "unknown command: ${cmd}" >&2
usage >&2
exit 1
;;
esac
```
- [ ] **Step 2: Make executable**
```bash
chmod +x scripts/dev.sh
```
- [ ] **Step 3: Commit**
```bash
git add scripts/dev.sh
git -c commit.gpgsign=false commit -m "feat(scripts): add dev.sh with exec/pnpm/shell subcommands"
```
---
## Task 5: scripts/gen_auth_secret.sh and minimal .env.development for bootstrap
**Files:**
- Create: `scripts/gen_auth_secret.sh`
- Create: `envs/.env.example`
- Create: `.env.development` (with bootstrap-only values; full values come in Task 9)
- [ ] **Step 1: Create `scripts/gen_auth_secret.sh`**
```bash
#!/usr/bin/env bash
# Generate a 32-byte (64 hex chars) AUTH_SECRET for web session signing.
set -euo pipefail
usage() {
cat <<'EOF'
Generate AUTH_SECRET.
Usage:
scripts/gen_auth_secret.sh Print a fresh secret to stdout.
scripts/gen_auth_secret.sh --write Set AUTH_SECRET= in ./.env.development
(creates if missing, replaces if present).
scripts/gen_auth_secret.sh --write PATH Same, against an explicit env path.
EOF
}
generate() {
if command -v openssl >/dev/null 2>&1; then
openssl rand -hex 32
else
head -c 32 /dev/urandom | xxd -p -c 64
fi
}
write_into() {
local target="$1"
local secret
secret="$(generate)"
if [[ -f "${target}" ]] && grep -q '^AUTH_SECRET=' "${target}"; then
local tmp
tmp="$(mktemp)"
awk -v s="${secret}" '
/^AUTH_SECRET=/ { print "AUTH_SECRET=" s; next }
{ print }
' "${target}" > "${tmp}"
mv "${tmp}" "${target}"
echo "Replaced AUTH_SECRET in ${target}"
else
[[ -f "${target}" ]] || touch "${target}"
if [[ -s "${target}" && -n "$(tail -c 1 "${target}")" ]]; then
printf '\n' >> "${target}"
fi
printf 'AUTH_SECRET=%s\n' "${secret}" >> "${target}"
echo "Appended AUTH_SECRET to ${target}"
fi
}
case "${1:-}" in
-h|--help) usage ;;
--write)
target="${2:-.env.development}"
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
[[ "${target}" = /* ]] || target="${ROOT_DIR}/${target}"
write_into "${target}"
;;
"") generate ;;
*) echo "Unknown option: $1" >&2; usage >&2; exit 2 ;;
esac
```
- [ ] **Step 2: Create `envs/.env.example`**
```bash
# === Postgres ===
DATABASE_URL=postgres://USER:PASS@192.168.0.210:5432/whatsapp_bot_dev
# === Telegram ===
TELEGRAM_BOT_TOKEN=
TELEGRAM_OPERATOR_WHITELIST=
TELEGRAM_QR_CHAT_ID=
# === App data paths (inside containers) ===
DATA_DIR=/data
SESSIONS_DIR=/data/sessions
MEDIA_DIR=/data/media
# === Bot service ===
BOT_HEALTH_PORT=8081
BOT_LOG_LEVEL=info
# === Seed (used by scripts/db.sh seed) ===
SEED_OPERATOR_TELEGRAM_ID=
SEED_OPERATOR_NAME=Operator
# === Web (placeholder for plan 3) ===
WEB_PORT=3000
AUTH_SECRET=
```
- [ ] **Step 3: Create initial `.env.development` (just enough to bring up tools)**
```bash
DATABASE_URL=postgres://placeholder:placeholder@192.168.0.210:5432/whatsapp_bot_dev
TELEGRAM_BOT_TOKEN=placeholder
TELEGRAM_OPERATOR_WHITELIST=0
TELEGRAM_QR_CHAT_ID=0
DATA_DIR=/data
SESSIONS_DIR=/data/sessions
MEDIA_DIR=/data/media
BOT_HEALTH_PORT=8081
BOT_LOG_LEVEL=debug
SEED_OPERATOR_TELEGRAM_ID=0
SEED_OPERATOR_NAME=Dev
WEB_PORT=3000
AUTH_SECRET=
```
This file will be filled with real values in Task 9. The placeholder values let the tools container come up so we can run `pnpm install`.
- [ ] **Step 4: Make script executable and generate the AUTH_SECRET**
```bash
chmod +x scripts/gen_auth_secret.sh
scripts/gen_auth_secret.sh --write
```
- [ ] **Step 5: Commit**
```bash
git add scripts/gen_auth_secret.sh envs/.env.example .env.development
git -c commit.gpgsign=false commit -m "chore: add gen_auth_secret + bootstrap env files"
```
---
## Task 6: Bootstrap — start tools and run pnpm install
This task is verification only — it produces `pnpm-lock.yaml` and `node_modules/` via the tools container, no source code changes.
- [ ] **Step 1: Build and start the tools container**
```bash
scripts/dev.sh up
```
Expected: builds `cm-whatsapp-tools:dev` (first run pulls node:22-alpine, installs build deps, activates pnpm), then `tools` shows as running. `scripts/dev.sh status` prints `OK`.
- [ ] **Step 2: Verify pnpm version inside the container**
```bash
scripts/dev.sh pnpm --version
```
Expected: `9.12.0` (or close — corepack chose this).
- [ ] **Step 3: Run pnpm install**
```bash
scripts/dev.sh pnpm install
```
Expected: pnpm completes without errors. Files appear on the host (because of the bind-mount): `pnpm-lock.yaml` at the repo root, `node_modules/` at the root, plus the per-workspace `node_modules/` once we add packages in later tasks.
- [ ] **Step 4: Verify file ownership on host**
```bash
ls -la pnpm-lock.yaml node_modules
```
Expected: files are owned by your host user, not root. (If they're root, your `HOST_UID/HOST_GID` aren't being passed through — fix `scripts/dev.sh` and reinstall.)
- [ ] **Step 5: Commit lockfile**
```bash
git add pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "chore: bootstrap pnpm install via tools container"
```
---
## Task 7: packages/shared with rrule, paths, timezone helpers (TDD)
**Files:**
- Create: `packages/shared/package.json`
- Create: `packages/shared/tsconfig.json`
- Create: `packages/shared/vitest.config.ts`
- Create: `packages/shared/src/index.ts`
- Create: `packages/shared/src/rrule.ts`
- Create: `packages/shared/src/rrule.test.ts`
- Create: `packages/shared/src/media-paths.ts`
- Create: `packages/shared/src/timezones.ts`
- [ ] **Step 1: Create `packages/shared/package.json`**
```json
{
"name": "@cmbot/shared",
"version": "0.1.0",
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts"
},
"scripts": {
"build": "tsc -p tsconfig.json",
"test": "vitest run",
"test:watch": "vitest",
"lint": "echo 'lint placeholder'",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"rrule": "^2.8.1",
"luxon": "^3.5.0"
},
"devDependencies": {
"@types/luxon": "^3.4.2",
"typescript": "^5.5.0",
"vitest": "^2.1.0"
}
}
```
- [ ] **Step 2: Create `packages/shared/tsconfig.json`**
```json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
```
- [ ] **Step 3: Create `packages/shared/vitest.config.ts`**
```typescript
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "node",
include: ["src/**/*.test.ts"],
},
});
```
- [ ] **Step 4: Write the failing test for rrule helpers**
Create `packages/shared/src/rrule.test.ts`:
```typescript
import { describe, expect, it } from "vitest";
import { parseRRule, nextOccurrence, validateMinInterval, MIN_INTERVAL_MS } from "./rrule.js";
describe("parseRRule", () => {
it("accepts a daily rule", () => {
expect(() => parseRRule("FREQ=DAILY;BYHOUR=9;BYMINUTE=0")).not.toThrow();
});
it("rejects invalid syntax", () => {
expect(() => parseRRule("not-a-rule")).toThrow();
});
});
describe("nextOccurrence", () => {
it("returns the next firing time after `after`", () => {
const rule = "FREQ=DAILY;BYHOUR=9;BYMINUTE=0";
const after = new Date("2026-05-03T08:00:00Z");
const next = nextOccurrence(rule, "Asia/Kuala_Lumpur", after);
expect(next).toBeInstanceOf(Date);
expect(next!.getTime()).toBeGreaterThan(after.getTime());
});
it("returns null when the rule has no further occurrences", () => {
const past = "DTSTART:20200101T000000Z\nRRULE:FREQ=DAILY;COUNT=1";
expect(nextOccurrence(past, "Asia/Kuala_Lumpur", new Date())).toBeNull();
});
});
describe("validateMinInterval", () => {
it("accepts a daily rule (interval > 5 min)", () => {
expect(validateMinInterval("FREQ=DAILY;BYHOUR=9;BYMINUTE=0", "Asia/Kuala_Lumpur"))
.toEqual({ ok: true });
});
it("rejects a rule firing every minute", () => {
const result = validateMinInterval("FREQ=MINUTELY", "Asia/Kuala_Lumpur");
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.reason).toMatch(/minimum interval/i);
}
});
});
describe("MIN_INTERVAL_MS", () => {
it("equals 5 minutes", () => {
expect(MIN_INTERVAL_MS).toBe(5 * 60 * 1000);
});
});
```
- [ ] **Step 5: Install workspace deps**
```bash
scripts/dev.sh pnpm install
```
- [ ] **Step 6: Run the failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/shared test
```
Expected: fails (modules not found).
- [ ] **Step 7: Implement `packages/shared/src/rrule.ts`**
```typescript
import { RRule, rrulestr } from "rrule";
import { DateTime } from "luxon";
export const MIN_INTERVAL_MS = 5 * 60 * 1000;
export function parseRRule(rule: string): RRule {
const parsed = rrulestr(rule);
if (!(parsed instanceof RRule)) {
throw new Error("Compound RRULE/RRSET not supported");
}
return parsed;
}
export function nextOccurrence(rule: string, timezone: string, after: Date): Date | null {
const parsed = parseRRule(rule);
const afterInZone = DateTime.fromJSDate(after).setZone(timezone).toJSDate();
const next = parsed.after(afterInZone, false);
return next ?? null;
}
export type IntervalCheck = { ok: true } | { ok: false; reason: string };
export function validateMinInterval(rule: string, timezone: string): IntervalCheck {
const parsed = parseRRule(rule);
const now = new Date();
const first = parsed.after(now, false);
if (!first) return { ok: true };
const second = parsed.after(first, false);
if (!second) return { ok: true };
const gap = second.getTime() - first.getTime();
if (gap < MIN_INTERVAL_MS) {
return {
ok: false,
reason: `Recurrence fires every ${Math.round(gap / 1000)}s; minimum interval is ${MIN_INTERVAL_MS / 1000}s.`,
};
}
return { ok: true };
}
```
- [ ] **Step 8: Implement `packages/shared/src/media-paths.ts`**
```typescript
import { randomUUID } from "node:crypto";
export const MEDIA_ROOT = "/data/media";
export function newMediaPath(originalFilename: string, now: Date = new Date()): string {
const ext = (originalFilename.match(/\.[a-zA-Z0-9]{1,8}$/)?.[0] ?? "").toLowerCase();
const yyyy = now.getUTCFullYear();
const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
return `${yyyy}/${mm}/${randomUUID()}${ext}`;
}
export function absoluteMediaPath(storagePath: string, root: string = MEDIA_ROOT): string {
if (storagePath.includes("..")) throw new Error("Invalid storage path");
return `${root}/${storagePath}`;
}
```
- [ ] **Step 9: Implement `packages/shared/src/timezones.ts`**
```typescript
import { DateTime } from "luxon";
export const DEFAULT_TIMEZONE = "Asia/Kuala_Lumpur";
export function isValidTimezone(tz: string): boolean {
return DateTime.local().setZone(tz).isValid;
}
```
- [ ] **Step 10: Implement `packages/shared/src/index.ts`**
```typescript
export * from "./rrule.js";
export * from "./media-paths.js";
export * from "./timezones.js";
```
- [ ] **Step 11: Run tests (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/shared test
```
Expected: 7 tests pass.
- [ ] **Step 12: Commit**
```bash
git add packages/shared pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(shared): add rrule, media-path, timezone helpers"
```
---
## Task 8: packages/db with Drizzle schema for all tables
**Files:**
- Create: `packages/db/package.json`
- Create: `packages/db/tsconfig.json`
- Create: `packages/db/drizzle.config.ts`
- Create: `packages/db/src/schema.ts`
- Create: `packages/db/src/index.ts`
- Create: `packages/db/src/migrate.ts`
- Create: `packages/db/src/seed.ts`
- [ ] **Step 1: Create `packages/db/package.json`**
```json
{
"name": "@cmbot/db",
"version": "0.1.0",
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts",
"./schema": "./src/schema.ts"
},
"scripts": {
"build": "tsc -p tsconfig.json",
"test": "echo 'no unit tests'",
"lint": "echo 'lint placeholder'",
"typecheck": "tsc -p tsconfig.json --noEmit",
"generate": "drizzle-kit generate",
"migrate": "tsx src/migrate.ts",
"studio": "drizzle-kit studio --host 0.0.0.0",
"seed": "tsx src/seed.ts"
},
"dependencies": {
"drizzle-orm": "^0.36.0",
"pg": "^8.13.0"
},
"devDependencies": {
"@types/pg": "^8.11.10",
"drizzle-kit": "^0.28.0",
"tsx": "^4.19.0",
"typescript": "^5.5.0"
}
}
```
- [ ] **Step 2: Create `packages/db/tsconfig.json`**
```json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
```
- [ ] **Step 3: Create `packages/db/drizzle.config.ts`**
```typescript
import { defineConfig } from "drizzle-kit";
const databaseUrl = process.env.DATABASE_URL;
if (!databaseUrl) {
throw new Error("DATABASE_URL must be set when running drizzle-kit");
}
export default defineConfig({
schema: "./src/schema.ts",
out: "./migrations",
dialect: "postgresql",
dbCredentials: { url: databaseUrl },
strict: true,
verbose: true,
});
```
- [ ] **Step 4: Create `packages/db/src/schema.ts`** (all 11 tables from spec §9)
```typescript
import {
pgTable,
uuid,
text,
bigint,
integer,
boolean,
timestamp,
jsonb,
primaryKey,
uniqueIndex,
inet,
} from "drizzle-orm/pg-core";
export const operators = pgTable(
"operators",
{
id: uuid("id").primaryKey().defaultRandom(),
telegramUserId: bigint("telegram_user_id", { mode: "number" }).notNull(),
displayName: text("display_name").notNull(),
role: text("role").notNull().default("admin"),
defaultTimezone: text("default_timezone").notNull().default("Asia/Kuala_Lumpur"),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
},
(t) => ({
telegramUserIdUnique: uniqueIndex("operators_telegram_user_id_uq").on(t.telegramUserId),
}),
);
export const whatsappAccounts = pgTable(
"whatsapp_accounts",
{
id: uuid("id").primaryKey().defaultRandom(),
operatorId: uuid("operator_id").notNull().references(() => operators.id),
label: text("label").notNull(),
phoneNumber: text("phone_number"),
status: text("status").notNull().default("pending"),
lastConnectedAt: timestamp("last_connected_at", { withTimezone: true }),
lastQrAt: timestamp("last_qr_at", { withTimezone: true }),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
},
(t) => ({
operatorLabelUnique: uniqueIndex("whatsapp_accounts_operator_label_uq").on(t.operatorId, t.label),
}),
);
export const whatsappGroups = pgTable(
"whatsapp_groups",
{
id: uuid("id").primaryKey().defaultRandom(),
accountId: uuid("account_id").notNull().references(() => whatsappAccounts.id),
waGroupJid: text("wa_group_jid").notNull(),
name: text("name").notNull(),
participantCount: integer("participant_count").notNull().default(0),
isArchived: boolean("is_archived").notNull().default(false),
lastSyncedAt: timestamp("last_synced_at", { withTimezone: true }).notNull().defaultNow(),
},
(t) => ({
accountJidUnique: uniqueIndex("whatsapp_groups_account_jid_uq").on(t.accountId, t.waGroupJid),
}),
);
export const mediaFiles = pgTable("media_files", {
id: uuid("id").primaryKey().defaultRandom(),
operatorId: uuid("operator_id").notNull().references(() => operators.id),
filenameOriginal: text("filename_original").notNull(),
mimeType: text("mime_type").notNull(),
sizeBytes: bigint("size_bytes", { mode: "number" }).notNull(),
sha256: text("sha256").notNull(),
storagePath: text("storage_path").notNull(),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
});
export const reminders = pgTable("reminders", {
id: uuid("id").primaryKey().defaultRandom(),
accountId: uuid("account_id").notNull().references(() => whatsappAccounts.id),
name: text("name").notNull(),
scheduleKind: text("schedule_kind").notNull(),
scheduledAt: timestamp("scheduled_at", { withTimezone: true }),
rrule: text("rrule"),
timezone: text("timezone").notNull(),
endsAt: timestamp("ends_at", { withTimezone: true }),
maxRuns: integer("max_runs"),
status: text("status").notNull().default("active"),
createdBy: uuid("created_by").notNull().references(() => operators.id),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
});
export const reminderTargets = pgTable(
"reminder_targets",
{
reminderId: uuid("reminder_id").notNull().references(() => reminders.id, { onDelete: "cascade" }),
groupId: uuid("group_id").notNull().references(() => whatsappGroups.id),
position: integer("position").notNull().default(0),
},
(t) => ({
pk: primaryKey({ columns: [t.reminderId, t.groupId] }),
}),
);
export const reminderMessages = pgTable("reminder_messages", {
id: uuid("id").primaryKey().defaultRandom(),
reminderId: uuid("reminder_id").notNull().references(() => reminders.id, { onDelete: "cascade" }),
position: integer("position").notNull(),
kind: text("kind").notNull(),
textContent: text("text_content"),
mediaId: uuid("media_id").references(() => mediaFiles.id),
});
export const reminderRuns = pgTable("reminder_runs", {
id: uuid("id").primaryKey().defaultRandom(),
reminderId: uuid("reminder_id").notNull().references(() => reminders.id),
firedAt: timestamp("fired_at", { withTimezone: true }).notNull().defaultNow(),
status: text("status").notNull(),
errorSummary: text("error_summary"),
});
export const reminderRunTargets = pgTable(
"reminder_run_targets",
{
runId: uuid("run_id").notNull().references(() => reminderRuns.id, { onDelete: "cascade" }),
groupId: uuid("group_id").notNull().references(() => whatsappGroups.id),
status: text("status").notNull(),
waMessageId: text("wa_message_id"),
error: text("error"),
latencyMs: integer("latency_ms"),
},
(t) => ({
pk: primaryKey({ columns: [t.runId, t.groupId] }),
}),
);
export const auditLog = pgTable("audit_log", {
id: uuid("id").primaryKey().defaultRandom(),
operatorId: uuid("operator_id").references(() => operators.id),
source: text("source").notNull(),
action: text("action").notNull(),
targetType: text("target_type"),
targetId: uuid("target_id"),
payload: jsonb("payload").notNull().default({}),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
});
export const authSessions = pgTable("auth_sessions", {
id: uuid("id").primaryKey().defaultRandom(),
operatorId: uuid("operator_id").notNull().references(() => operators.id),
tokenHash: text("token_hash").notNull().unique(),
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
lastUsedAt: timestamp("last_used_at", { withTimezone: true }).notNull().defaultNow(),
ipAddress: inet("ip_address"),
userAgent: text("user_agent"),
});
export type Operator = typeof operators.$inferSelect;
export type NewOperator = typeof operators.$inferInsert;
export type WhatsappAccount = typeof whatsappAccounts.$inferSelect;
export type NewWhatsappAccount = typeof whatsappAccounts.$inferInsert;
export type WhatsappGroup = typeof whatsappGroups.$inferSelect;
export type NewWhatsappGroup = typeof whatsappGroups.$inferInsert;
export type AuditLogEntry = typeof auditLog.$inferSelect;
export type NewAuditLogEntry = typeof auditLog.$inferInsert;
```
- [ ] **Step 5: Implement `packages/db/src/index.ts`**
```typescript
import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import * as schema from "./schema.js";
export * from "./schema.js";
export type DB = NodePgDatabase<typeof schema>;
export function createClient(databaseUrl: string): { db: DB; pool: Pool } {
const pool = new Pool({ connectionString: databaseUrl });
const db = drizzle(pool, { schema });
return { db, pool };
}
```
- [ ] **Step 6: Implement `packages/db/src/migrate.ts`**
```typescript
import { migrate } from "drizzle-orm/node-postgres/migrator";
import { createClient } from "./index.js";
const databaseUrl = process.env.DATABASE_URL;
if (!databaseUrl) {
console.error("DATABASE_URL not set");
process.exit(1);
}
const { db, pool } = createClient(databaseUrl);
console.log("Applying migrations...");
await migrate(db, { migrationsFolder: "./migrations" });
console.log("Migrations applied.");
await pool.end();
```
- [ ] **Step 7: Implement `packages/db/src/seed.ts`**
```typescript
import { createClient, operators } from "./index.js";
const databaseUrl = process.env.DATABASE_URL;
const operatorTelegramId = process.env.SEED_OPERATOR_TELEGRAM_ID;
const operatorName = process.env.SEED_OPERATOR_NAME ?? "Operator";
if (!databaseUrl) {
console.error("DATABASE_URL not set");
process.exit(1);
}
if (!operatorTelegramId || operatorTelegramId === "0") {
console.error("SEED_OPERATOR_TELEGRAM_ID not set");
process.exit(1);
}
const { db, pool } = createClient(databaseUrl);
await db
.insert(operators)
.values({
telegramUserId: Number(operatorTelegramId),
displayName: operatorName,
role: "admin",
defaultTimezone: "Asia/Kuala_Lumpur",
})
.onConflictDoNothing();
console.log(`Seeded operator with telegram_user_id=${operatorTelegramId}`);
await pool.end();
```
- [ ] **Step 8: Install deps and generate the initial migration**
```bash
scripts/dev.sh pnpm install
scripts/dev.sh pnpm --filter @cmbot/db generate
```
Expected: a single `0000_*.sql` file appears under `packages/db/migrations/`.
- [ ] **Step 9: Commit**
```bash
git add packages/db pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(db): add drizzle schema for all tables + initial migration"
```
---
## Task 9: Fill in the real `.env.development` values
The file already exists from Task 5 with placeholders. Now substitute real values for the dev environment.
- [ ] **Step 1: Edit `.env.development`** with the real dev values you provisioned in the pre-flight checks
Example (replace with your actuals):
```bash
DATABASE_URL=postgres://wabotdev:YOUR_DEV_PASSWORD@192.168.0.210:5432/whatsapp_bot_dev
TELEGRAM_BOT_TOKEN=1234567890:YOUR_DEV_BOT_TOKEN_FROM_BOTFATHER
TELEGRAM_OPERATOR_WHITELIST=YOUR_TELEGRAM_USER_ID
TELEGRAM_QR_CHAT_ID=YOUR_TELEGRAM_USER_ID
DATA_DIR=/data
SESSIONS_DIR=/data/sessions
MEDIA_DIR=/data/media
BOT_HEALTH_PORT=8081
BOT_LOG_LEVEL=debug
SEED_OPERATOR_TELEGRAM_ID=YOUR_TELEGRAM_USER_ID
SEED_OPERATOR_NAME=Yiekheng (dev)
WEB_PORT=3000
AUTH_SECRET=<keep the value generated by gen_auth_secret.sh>
```
- [ ] **Step 2: Restart tools so the new env values are picked up**
```bash
scripts/dev.sh down
scripts/dev.sh up
```
- [ ] **Step 3: Verify env propagation**
```bash
scripts/dev.sh exec sh -c 'echo "DB=$DATABASE_URL"; echo "TG=$TELEGRAM_BOT_TOKEN" | head -c 30'
```
Expected: prints your real DATABASE_URL and the first 30 chars of the TG token.
- [ ] **Step 4: Commit the populated env file**
```bash
git add .env.development
git -c commit.gpgsign=false commit -m "chore: populate .env.development with real dev values"
```
---
## Task 10: scripts/db.sh wrapping pnpm via tools
**Files:**
- Create: `scripts/db.sh`
- Create: `scripts/link-account.sh` (stub for plan 2)
- Create: `scripts/publish.sh` (stub for plan 4)
- [ ] **Step 1: Create `scripts/db.sh`**
```bash
#!/usr/bin/env bash
# Drizzle migration helper. Always runs inside the tools container.
set -euo pipefail
usage() {
cat <<'EOF'
Drizzle migration helper.
Usage:
scripts/db.sh migrate Apply pending migrations to DATABASE_URL.
scripts/db.sh generate Generate a new migration from schema changes.
scripts/db.sh studio Open drizzle-kit studio (port 4983 in container, exposed on host).
scripts/db.sh seed Seed dev data (operator row).
scripts/db.sh reset Drop and recreate ALL tables (dev only).
Environment:
ENV_FILE Override env file (default: .env.development).
EOF
}
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "${ROOT_DIR}"
ENV_FILE="${ENV_FILE:-.env.development}"
if [[ ! -f "${ENV_FILE}" ]]; then
echo "ERROR: ${ENV_FILE} not found." >&2
exit 2
fi
# Load env locally just to read DATABASE_URL for the prod-DB safety check.
set -a
# shellcheck disable=SC1090
source "${ENV_FILE}"
set +a
case "${1:-}" in
-h|--help) usage ;;
migrate)
exec scripts/dev.sh pnpm --filter @cmbot/db migrate
;;
generate)
exec scripts/dev.sh pnpm --filter @cmbot/db generate
;;
studio)
exec scripts/dev.sh pnpm --filter @cmbot/db studio
;;
seed)
exec scripts/dev.sh pnpm --filter @cmbot/db seed
;;
reset)
if [[ "${DATABASE_URL}" == *whatsapp_bot_prod* ]]; then
echo "ERROR: refusing to reset prod database." >&2
exit 2
fi
read -r -p "About to DROP all tables in ${DATABASE_URL}. Type 'yes' to continue: " confirm
[[ "${confirm}" == "yes" ]] || { echo "Aborted."; exit 1; }
scripts/dev.sh exec sh -c "pnpm exec tsx -e \"
import { Pool } from 'pg';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await pool.query(\\\"DROP SCHEMA public CASCADE; CREATE SCHEMA public;\\\");
await pool.query(\\\"DROP SCHEMA IF EXISTS pgboss CASCADE;\\\");
await pool.end();
console.log('Schema reset.');
\""
exec scripts/dev.sh pnpm --filter @cmbot/db migrate
;;
"") usage >&2; exit 1 ;;
*) echo "Unknown command: $1" >&2; usage >&2; exit 1 ;;
esac
```
- [ ] **Step 2: Create `scripts/link-account.sh` (stub for plan 2)**
```bash
#!/usr/bin/env bash
echo "scripts/link-account.sh: not yet implemented (see plan 2)" >&2
exit 1
```
- [ ] **Step 3: Create `scripts/publish.sh` (stub for plan 4)**
```bash
#!/usr/bin/env bash
echo "scripts/publish.sh: not yet implemented (see plan 4)" >&2
exit 1
```
- [ ] **Step 4: Make all scripts executable**
```bash
chmod +x scripts/*.sh
```
- [ ] **Step 5: Commit**
```bash
git add scripts/
git -c commit.gpgsign=false commit -m "feat(scripts): add db.sh wrapper and stubs for plans 2/4"
```
---
## Task 11: Apply migrations and seed (verification step)
This task has no source changes. It verifies that DB connectivity works end-to-end through the tools container.
- [ ] **Step 1: Apply migrations**
```bash
scripts/db.sh migrate
```
Expected: "Migrations applied." If you get a connection error, check `DATABASE_URL` and `pg_hba.conf` on `192.168.0.210`.
- [ ] **Step 2: Seed the operator row**
```bash
scripts/db.sh seed
```
Expected: "Seeded operator with telegram_user_id=YOUR_ID".
- [ ] **Step 3: Verify rows exist**
```bash
scripts/dev.sh exec sh -c 'pnpm exec tsx -e "
import { Pool } from \"pg\";
const p = new Pool({ connectionString: process.env.DATABASE_URL });
const r = await p.query(\"SELECT count(*) FROM operators\");
console.log(\"operators rows:\", r.rows[0].count);
await p.end();
"'
```
Expected: `operators rows: 1`.
(No commit — this task is verification only.)
---
## Task 12: Bot Dockerfile and add bot service to compose
**Files:**
- Create: `docker/bot.Dockerfile`
- Create: `docker/web.Dockerfile` (placeholder)
- Modify: `docker-compose.dev.yml`
- [ ] **Step 1: Create `docker/bot.Dockerfile`**
```dockerfile
FROM node:22-alpine AS base
RUN corepack enable && corepack prepare pnpm@9.12.0 --activate
WORKDIR /app
FROM base AS deps
COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
COPY apps/bot/package.json apps/bot/
COPY packages/db/package.json packages/db/
COPY packages/shared/package.json packages/shared/
RUN pnpm install --frozen-lockfile
FROM base AS build
COPY --from=deps /app/node_modules /app/node_modules
COPY --from=deps /app/apps/bot/node_modules /app/apps/bot/node_modules
COPY --from=deps /app/packages/db/node_modules /app/packages/db/node_modules
COPY --from=deps /app/packages/shared/node_modules /app/packages/shared/node_modules
COPY tsconfig.base.json turbo.json ./
COPY apps/bot apps/bot
COPY packages/db packages/db
COPY packages/shared packages/shared
RUN pnpm --filter @cmbot/shared build && pnpm --filter @cmbot/db build && pnpm --filter @cmbot/bot build
FROM base AS runtime
ENV NODE_ENV=production
COPY --from=build /app/node_modules /app/node_modules
COPY --from=build /app/apps/bot /app/apps/bot
COPY --from=build /app/packages/db /app/packages/db
COPY --from=build /app/packages/shared /app/packages/shared
EXPOSE 8081
CMD ["node", "apps/bot/dist/index.js"]
```
- [ ] **Step 2: Create `docker/web.Dockerfile`** (placeholder, fleshed out in plan 3)
```dockerfile
FROM node:22-alpine
WORKDIR /app
CMD ["echo", "web service: not yet implemented (see plan 3)"]
```
- [ ] **Step 3: Replace `docker-compose.dev.yml`** with the bot service added
```yaml
services:
tools:
image: cm-whatsapp-tools:dev
build:
context: .
dockerfile: docker/tools.Dockerfile
bot:
build:
context: .
dockerfile: docker/bot.Dockerfile
target: build
image: cm-whatsapp-bot:dev
container_name: cmbot-bot
user: "${HOST_UID:-1000}:${HOST_GID:-1000}"
working_dir: /app
command: ["pnpm", "--filter", "@cmbot/bot", "dev"]
restart: unless-stopped
volumes:
- .:/app
- ./dev-data:/data
ports:
- "127.0.0.1:8081:8081"
environment:
NODE_ENV: development
DATABASE_URL: ${DATABASE_URL}
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
TELEGRAM_OPERATOR_WHITELIST: ${TELEGRAM_OPERATOR_WHITELIST}
TELEGRAM_QR_CHAT_ID: ${TELEGRAM_QR_CHAT_ID}
DATA_DIR: ${DATA_DIR}
SESSIONS_DIR: ${SESSIONS_DIR}
MEDIA_DIR: ${MEDIA_DIR}
BOT_HEALTH_PORT: ${BOT_HEALTH_PORT}
BOT_LOG_LEVEL: ${BOT_LOG_LEVEL}
networks:
- cmbot
depends_on:
- tools
```
- [ ] **Step 4: Pre-create the dev-data directory so bind mount has correct ownership**
```bash
mkdir -p dev-data/sessions dev-data/media
```
- [ ] **Step 5: Commit**
```bash
git add docker/ docker-compose.dev.yml
git -c commit.gpgsign=false commit -m "chore: add bot Dockerfile and bot service in dev compose"
```
---
## Task 13: apps/bot skeleton (env, logger, db, health, index) — TDD on env
**Files:**
- Create: `apps/bot/package.json`
- Create: `apps/bot/tsconfig.json`
- Create: `apps/bot/vitest.config.ts`
- Create: `apps/bot/src/env.ts`
- Create: `apps/bot/src/env.test.ts`
- Create: `apps/bot/src/logger.ts`
- Create: `apps/bot/src/db.ts`
- Create: `apps/bot/src/health.ts`
- Create: `apps/bot/src/index.ts`
- [ ] **Step 1: Create `apps/bot/package.json`**
```json
{
"name": "@cmbot/bot",
"version": "0.1.0",
"private": true,
"type": "module",
"main": "./dist/index.js",
"scripts": {
"build": "tsc -p tsconfig.json",
"dev": "tsx watch src/index.ts",
"start": "node dist/index.js",
"test": "vitest run",
"lint": "echo 'lint placeholder'",
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"@cmbot/db": "workspace:*",
"@cmbot/shared": "workspace:*",
"@whiskeysockets/baileys": "^6.7.7",
"grammy": "^1.31.0",
"pino": "^9.5.0",
"pino-pretty": "^11.3.0",
"qrcode": "^1.5.4",
"zod": "^3.23.8"
},
"devDependencies": {
"@types/node": "^22.7.0",
"@types/qrcode": "^1.5.5",
"tsx": "^4.19.0",
"typescript": "^5.5.0",
"vitest": "^2.1.0"
}
}
```
- [ ] **Step 2: Create `apps/bot/tsconfig.json`**
```json
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"]
}
```
- [ ] **Step 3: Create `apps/bot/vitest.config.ts`**
```typescript
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
environment: "node",
include: ["src/**/*.test.ts"],
},
});
```
- [ ] **Step 4: Write the failing test for env validation**
Create `apps/bot/src/env.test.ts`:
```typescript
import { describe, expect, it } from "vitest";
import { parseEnv } from "./env.js";
const valid = {
DATABASE_URL: "postgres://u:p@h:5432/db",
TELEGRAM_BOT_TOKEN: "123:abc",
TELEGRAM_OPERATOR_WHITELIST: "111,222",
TELEGRAM_QR_CHAT_ID: "111",
DATA_DIR: "/data",
SESSIONS_DIR: "/data/sessions",
MEDIA_DIR: "/data/media",
BOT_HEALTH_PORT: "8081",
BOT_LOG_LEVEL: "info",
};
describe("parseEnv", () => {
it("parses a valid env", () => {
const env = parseEnv(valid);
expect(env.TELEGRAM_OPERATOR_WHITELIST).toEqual([111, 222]);
expect(env.TELEGRAM_QR_CHAT_ID).toBe(111);
expect(env.BOT_HEALTH_PORT).toBe(8081);
});
it("rejects missing DATABASE_URL", () => {
const { DATABASE_URL: _, ...rest } = valid;
expect(() => parseEnv(rest)).toThrow();
});
it("rejects empty whitelist", () => {
expect(() => parseEnv({ ...valid, TELEGRAM_OPERATOR_WHITELIST: "" })).toThrow();
});
it("rejects malformed port", () => {
expect(() => parseEnv({ ...valid, BOT_HEALTH_PORT: "notanumber" })).toThrow();
});
});
```
- [ ] **Step 5: Install workspace deps**
```bash
scripts/dev.sh pnpm install
```
- [ ] **Step 6: Run failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
Expected: fails with module not found.
- [ ] **Step 7: Implement `apps/bot/src/env.ts`**
```typescript
import { z } from "zod";
const numberFromString = z.string().regex(/^\d+$/).transform((s) => Number(s));
const envSchema = z.object({
DATABASE_URL: z.string().url(),
TELEGRAM_BOT_TOKEN: z.string().min(1),
TELEGRAM_OPERATOR_WHITELIST: z
.string()
.min(1)
.transform((s) => s.split(",").map((x) => Number(x.trim())))
.pipe(z.array(z.number().int().positive()).min(1)),
TELEGRAM_QR_CHAT_ID: numberFromString,
DATA_DIR: z.string().min(1),
SESSIONS_DIR: z.string().min(1),
MEDIA_DIR: z.string().min(1),
BOT_HEALTH_PORT: numberFromString,
BOT_LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
});
export type Env = z.infer<typeof envSchema>;
export function parseEnv(input: Record<string, string | undefined>): Env {
return envSchema.parse(input);
}
export const env = parseEnv(process.env);
```
- [ ] **Step 8: Run test (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
Expected: 4 tests pass.
- [ ] **Step 9: Implement `apps/bot/src/logger.ts`**
```typescript
import pino from "pino";
import { env } from "./env.js";
export const logger = pino({
level: env.BOT_LOG_LEVEL,
...(process.env.NODE_ENV !== "production"
? { transport: { target: "pino-pretty", options: { colorize: true } } }
: {}),
});
```
- [ ] **Step 10: Implement `apps/bot/src/db.ts`**
```typescript
import { createClient, type DB } from "@cmbot/db";
import { env } from "./env.js";
const { db, pool } = createClient(env.DATABASE_URL);
export { db, pool };
export type { DB };
```
- [ ] **Step 11: Implement `apps/bot/src/health.ts`**
```typescript
import { createServer, type Server } from "node:http";
import { sql } from "drizzle-orm";
import { db } from "./db.js";
import { env } from "./env.js";
import { logger } from "./logger.js";
export type HealthStatus = {
ok: boolean;
uptimeSec: number;
db: "ok" | "error";
sessions?: Record<string, number>;
};
const started = Date.now();
let getSessionCounts: () => Record<string, number> = () => ({});
export function setSessionCountsProvider(fn: () => Record<string, number>): void {
getSessionCounts = fn;
}
export async function buildHealth(): Promise<HealthStatus> {
let dbStatus: "ok" | "error" = "ok";
try {
await db.execute(sql`select 1`);
} catch (err) {
logger.warn({ err }, "health: db ping failed");
dbStatus = "error";
}
return {
ok: dbStatus === "ok",
uptimeSec: Math.round((Date.now() - started) / 1000),
db: dbStatus,
sessions: getSessionCounts(),
};
}
export function startHealthServer(): Server {
const server = createServer(async (req, res) => {
if (req.url !== "/health") {
res.writeHead(404).end("not found");
return;
}
const status = await buildHealth();
res.writeHead(status.ok ? 200 : 503, { "content-type": "application/json" });
res.end(JSON.stringify(status));
});
server.listen(env.BOT_HEALTH_PORT, () => {
logger.info({ port: env.BOT_HEALTH_PORT }, "health server listening");
});
return server;
}
```
- [ ] **Step 12: Implement `apps/bot/src/index.ts`**
```typescript
import { logger } from "./logger.js";
import { pool } from "./db.js";
import { startHealthServer } from "./health.js";
async function main(): Promise<void> {
logger.info("bot starting");
const health = startHealthServer();
const shutdown = async (signal: string): Promise<void> => {
logger.info({ signal }, "shutting down");
health.close();
await pool.end();
process.exit(0);
};
process.on("SIGINT", () => void shutdown("SIGINT"));
process.on("SIGTERM", () => void shutdown("SIGTERM"));
logger.info("bot ready");
}
main().catch((err) => {
logger.fatal({ err }, "bot failed to start");
process.exit(1);
});
```
- [ ] **Step 13: Typecheck**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```
Expected: no errors.
- [ ] **Step 14: Commit**
```bash
git add apps/bot pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(bot): scaffold env, logger, db, health, shutdown"
```
---
## Task 14: Verify bot service runs and health is green
This task has no source changes — it verifies the bot wires up correctly.
- [ ] **Step 1: Bring up the bot service**
```bash
scripts/dev.sh up
scripts/dev.sh logs bot
```
Expected log lines:
```
{"msg":"bot starting"}
{"port":8081,"msg":"health server listening"}
{"msg":"bot ready"}
```
- [ ] **Step 2: Verify health from host**
```bash
curl -s http://localhost:8081/health | tee /dev/null
```
Expected: `{"ok":true,"uptimeSec":<n>,"db":"ok","sessions":{}}`. If `db: "error"`, fix DB connectivity from the bot container (it uses the same `DATABASE_URL` as tools, so should work).
- [ ] **Step 3: Verify graceful shutdown**
```bash
scripts/dev.sh down
```
Expected: in `scripts/dev.sh logs bot` (run before down) you'll see "shutting down" log line just before container exits. `scripts/dev.sh status` exits non-zero with "tools container not running".
- [ ] **Step 4: Bring it back up for the next tasks**
```bash
scripts/dev.sh up
```
(No commit — verification only.)
---
## Task 15: Audit log writer (TDD)
**Files:**
- Create: `apps/bot/src/audit.ts`
- Create: `apps/bot/src/audit.test.ts`
- [ ] **Step 1: Write the failing test**
Create `apps/bot/src/audit.test.ts`:
```typescript
import { describe, expect, it } from "vitest";
import type { DB } from "./db.js";
import { writeAuditLog } from "./audit.js";
describe("writeAuditLog", () => {
it("inserts a row with normalized fields", async () => {
const inserted: unknown[] = [];
const fakeDb = {
insert: () => ({
values: (v: unknown) => {
inserted.push(v);
return Promise.resolve();
},
}),
} as unknown as DB;
await writeAuditLog(fakeDb, {
operatorId: null,
source: "telegram",
action: "test.event",
payload: { foo: "bar" },
});
expect(inserted).toHaveLength(1);
expect(inserted[0]).toMatchObject({
operatorId: null,
source: "telegram",
action: "test.event",
payload: { foo: "bar" },
});
});
});
```
- [ ] **Step 2: Run failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 3: Implement `apps/bot/src/audit.ts`**
```typescript
import { auditLog, type DB, type NewAuditLogEntry } from "@cmbot/db";
export type AuditInput = {
operatorId: string | null;
source: "web" | "telegram" | "system";
action: string;
targetType?: string | null;
targetId?: string | null;
payload?: Record<string, unknown>;
};
export async function writeAuditLog(db: DB, input: AuditInput): Promise<void> {
const row: NewAuditLogEntry = {
operatorId: input.operatorId,
source: input.source,
action: input.action,
targetType: input.targetType ?? null,
targetId: input.targetId ?? null,
payload: input.payload ?? {},
};
await db.insert(auditLog).values(row);
}
```
- [ ] **Step 4: Run test (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 5: Commit**
```bash
git add apps/bot/src/audit.ts apps/bot/src/audit.test.ts
git -c commit.gpgsign=false commit -m "feat(bot): add audit log writer"
```
---
## Task 16: Telegram bot foundation (whitelist, /start, /help, audit middleware)
**Files:**
- Create: `apps/bot/src/telegram/bot.ts`
- Create: `apps/bot/src/telegram/middleware/whitelist.ts`
- Create: `apps/bot/src/telegram/middleware/whitelist.test.ts`
- Create: `apps/bot/src/telegram/middleware/audit.ts`
- Create: `apps/bot/src/telegram/commands/start.ts`
- Create: `apps/bot/src/telegram/commands/help.ts`
- Modify: `apps/bot/src/index.ts` (start the Telegram bot)
- [ ] **Step 1: Write the failing test for whitelist middleware**
Create `apps/bot/src/telegram/middleware/whitelist.test.ts`:
```typescript
import { describe, expect, it, vi } from "vitest";
import { makeWhitelistMiddleware } from "./whitelist.js";
function ctx(userId: number | undefined) {
return {
from: userId === undefined ? undefined : { id: userId },
reply: vi.fn().mockResolvedValue(undefined),
} as unknown as { from?: { id: number }; reply: ReturnType<typeof vi.fn> };
}
describe("makeWhitelistMiddleware", () => {
it("calls next for whitelisted user", async () => {
const mw = makeWhitelistMiddleware([42]);
const c = ctx(42);
const next = vi.fn().mockResolvedValue(undefined);
await mw(c as never, next);
expect(next).toHaveBeenCalledOnce();
expect(c.reply).not.toHaveBeenCalled();
});
it("rejects non-whitelisted user with reply", async () => {
const mw = makeWhitelistMiddleware([42]);
const c = ctx(99);
const next = vi.fn();
await mw(c as never, next);
expect(next).not.toHaveBeenCalled();
expect(c.reply).toHaveBeenCalledWith(expect.stringMatching(/private/i));
});
it("rejects user-less updates silently", async () => {
const mw = makeWhitelistMiddleware([42]);
const c = ctx(undefined);
const next = vi.fn();
await mw(c as never, next);
expect(next).not.toHaveBeenCalled();
});
});
```
- [ ] **Step 2: Run failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 3: Implement `apps/bot/src/telegram/middleware/whitelist.ts`**
```typescript
import type { Context, MiddlewareFn } from "grammy";
export function makeWhitelistMiddleware(allowedUserIds: number[]): MiddlewareFn<Context> {
const allowed = new Set(allowedUserIds);
return async (ctx, next) => {
const userId = ctx.from?.id;
if (userId === undefined) return;
if (!allowed.has(userId)) {
await ctx.reply("Sorry, this bot is private.");
return;
}
await next();
};
}
```
- [ ] **Step 4: Run test (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 5: Implement `apps/bot/src/telegram/middleware/audit.ts`**
```typescript
import type { Context, MiddlewareFn } from "grammy";
import { db } from "../../db.js";
import { writeAuditLog } from "../../audit.js";
import { logger } from "../../logger.js";
export const auditMiddleware: MiddlewareFn<Context> = async (ctx, next) => {
const text = ctx.message?.text;
if (text?.startsWith("/")) {
try {
await writeAuditLog(db, {
operatorId: null,
source: "telegram",
action: `tg.command.${text.split(" ")[0]?.slice(1) ?? "unknown"}`,
payload: { from: ctx.from?.id, text },
});
} catch (err) {
logger.warn({ err }, "audit middleware: failed to write");
}
}
await next();
};
```
- [ ] **Step 6: Implement `apps/bot/src/telegram/commands/start.ts`**
```typescript
import type { Context } from "grammy";
export async function handleStart(ctx: Context): Promise<void> {
await ctx.reply(
"👋 cm WhatsApp Reminder Bot is online.\n\n" +
"Type /help to see available commands.",
);
}
```
- [ ] **Step 7: Implement `apps/bot/src/telegram/commands/help.ts`**
```typescript
import type { Context } from "grammy";
export async function handleHelp(ctx: Context): Promise<void> {
await ctx.reply(
"Available commands:\n\n" +
"/start — show the welcome message\n" +
"/help — show this help\n" +
"/pair <label> — pair a new WhatsApp account\n" +
"/unpair <label> — disconnect and forget a paired account\n" +
"/accounts — list paired accounts and connection status\n" +
"/groups <label> — list groups for a given account",
);
}
```
- [ ] **Step 8: Implement `apps/bot/src/telegram/bot.ts`**
```typescript
import { Bot } from "grammy";
import { env } from "../env.js";
import { logger } from "../logger.js";
import { makeWhitelistMiddleware } from "./middleware/whitelist.js";
import { auditMiddleware } from "./middleware/audit.js";
import { handleStart } from "./commands/start.js";
import { handleHelp } from "./commands/help.js";
export function createTelegramBot(): Bot {
const bot = new Bot(env.TELEGRAM_BOT_TOKEN);
bot.use(makeWhitelistMiddleware(env.TELEGRAM_OPERATOR_WHITELIST));
bot.use(auditMiddleware);
bot.command("start", handleStart);
bot.command("help", handleHelp);
bot.catch((err) => {
logger.error({ err }, "telegram error");
});
return bot;
}
```
- [ ] **Step 9: Wire bot into `apps/bot/src/index.ts`**
Replace the file:
```typescript
import { logger } from "./logger.js";
import { pool } from "./db.js";
import { startHealthServer } from "./health.js";
import { createTelegramBot } from "./telegram/bot.js";
async function main(): Promise<void> {
logger.info("bot starting");
const health = startHealthServer();
const tg = createTelegramBot();
void tg.start({
onStart: (info) => logger.info({ username: info.username }, "telegram polling started"),
drop_pending_updates: true,
});
const shutdown = async (signal: string): Promise<void> => {
logger.info({ signal }, "shutting down");
await tg.stop();
health.close();
await pool.end();
process.exit(0);
};
process.on("SIGINT", () => void shutdown("SIGINT"));
process.on("SIGTERM", () => void shutdown("SIGTERM"));
logger.info("bot ready");
}
main().catch((err) => {
logger.fatal({ err }, "bot failed to start");
process.exit(1);
});
```
- [ ] **Step 10: Restart the bot service to pick up the new code**
```bash
scripts/dev.sh restart-bot
scripts/dev.sh logs bot
```
Expected log line: `{"username":"<your_dev_bot_username>","msg":"telegram polling started"}`.
- [ ] **Step 11: Send `/start` and `/help` from your Telegram** to the dev bot
Expected: welcome and help replies. As a non-whitelisted user (use a different account) sending `/start` should reply "Sorry, this bot is private."
Verify in Postgres:
```bash
scripts/dev.sh exec sh -c 'pnpm exec tsx -e "
import { Pool } from \"pg\";
const p = new Pool({ connectionString: process.env.DATABASE_URL });
const r = await p.query(\"SELECT action FROM audit_log ORDER BY created_at DESC LIMIT 5\");
console.log(r.rows);
await p.end();
"'
```
Expected: includes `tg.command.start` and `tg.command.help`.
- [ ] **Step 12: Commit**
```bash
git add apps/bot
git -c commit.gpgsign=false commit -m "feat(bot): add telegram bot with whitelist, /start, /help, audit"
```
---
## Task 17: QR PNG renderer (TDD)
**Files:**
- Create: `apps/bot/src/whatsapp/qr-renderer.ts`
- Create: `apps/bot/src/whatsapp/qr-renderer.test.ts`
- [ ] **Step 1: Write the failing test**
Create `apps/bot/src/whatsapp/qr-renderer.test.ts`:
```typescript
import { describe, expect, it } from "vitest";
import { renderQrPng } from "./qr-renderer.js";
describe("renderQrPng", () => {
it("returns a PNG buffer for a non-empty string", async () => {
const png = await renderQrPng("test-qr-payload");
expect(png).toBeInstanceOf(Buffer);
expect(png[0]).toBe(0x89);
expect(png.subarray(1, 4).toString("ascii")).toBe("PNG");
});
it("rejects empty input", async () => {
await expect(renderQrPng("")).rejects.toThrow();
});
});
```
- [ ] **Step 2: Run failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 3: Implement `apps/bot/src/whatsapp/qr-renderer.ts`**
```typescript
import QRCode from "qrcode";
export async function renderQrPng(payload: string): Promise<Buffer> {
if (!payload) throw new Error("renderQrPng: payload is empty");
return await QRCode.toBuffer(payload, { type: "png", width: 512, margin: 2 });
}
```
- [ ] **Step 4: Run test (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 5: Commit**
```bash
git add apps/bot/src/whatsapp/qr-renderer.ts apps/bot/src/whatsapp/qr-renderer.test.ts
git -c commit.gpgsign=false commit -m "feat(bot): add QR PNG renderer"
```
---
## Task 18: Single-account Baileys session wrapper
**Files:**
- Create: `apps/bot/src/whatsapp/session.ts`
This file isn't unit-tested directly — its value is the live WhatsApp connection, which the manual runbook covers in Task 22.
- [ ] **Step 1: Implement `apps/bot/src/whatsapp/session.ts`**
```typescript
import { mkdir } from "node:fs/promises";
import { join } from "node:path";
import {
default as makeWASocket,
useMultiFileAuthState,
type WASocket,
type ConnectionState,
DisconnectReason,
Browsers,
} from "@whiskeysockets/baileys";
import type { Boom } from "@hapi/boom";
import { logger } from "../logger.js";
import { env } from "../env.js";
export type SessionEvent =
| { type: "qr"; payload: string }
| { type: "open"; phoneNumber: string | undefined }
| { type: "close"; reason: number; loggedOut: boolean };
export type SessionEventHandler = (event: SessionEvent) => void | Promise<void>;
export type Session = {
accountId: string;
socket: WASocket;
close: () => Promise<void>;
};
export async function startSession(params: {
accountId: string;
onEvent: SessionEventHandler;
}): Promise<Session> {
const { accountId, onEvent } = params;
const sessionDir = join(env.SESSIONS_DIR, accountId);
await mkdir(sessionDir, { recursive: true });
const { state, saveCreds } = await useMultiFileAuthState(sessionDir);
const socket = makeWASocket({
auth: state,
printQRInTerminal: false,
browser: Browsers.macOS("Safari"),
syncFullHistory: false,
logger: logger.child({ accountId, component: "baileys" }) as never,
});
socket.ev.on("creds.update", () => void saveCreds());
socket.ev.on("connection.update", (update: Partial<ConnectionState>) => {
if (update.qr) {
void onEvent({ type: "qr", payload: update.qr });
}
if (update.connection === "open") {
const phoneNumber = socket.user?.id?.split(":")[0];
void onEvent({ type: "open", phoneNumber });
}
if (update.connection === "close") {
const reason =
(update.lastDisconnect?.error as Boom | undefined)?.output?.statusCode ?? 0;
const loggedOut = reason === DisconnectReason.loggedOut;
void onEvent({ type: "close", reason, loggedOut });
}
});
return {
accountId,
socket,
close: async () => {
try {
socket.end(undefined);
} catch (err) {
logger.warn({ err, accountId }, "session.close: error closing socket");
}
},
};
}
```
- [ ] **Step 2: Typecheck**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```
- [ ] **Step 3: Commit**
```bash
git add apps/bot/src/whatsapp/session.ts
git -c commit.gpgsign=false commit -m "feat(bot): add Baileys session wrapper"
```
---
## Task 19: Session manager (state machine + reconnect + DB sync)
**Files:**
- Create: `apps/bot/src/whatsapp/session-manager.ts`
- Create: `apps/bot/src/whatsapp/session-manager.test.ts`
- Modify: `apps/bot/src/index.ts` (resume sessions on startup, expose counts to health)
- [ ] **Step 1: Write the failing test for state transitions**
Create `apps/bot/src/whatsapp/session-manager.test.ts`:
```typescript
import { describe, expect, it } from "vitest";
import { reduceState, type SessionState } from "./session-manager.js";
describe("reduceState", () => {
it("pending → connecting on starting", () => {
expect(reduceState("pending", { kind: "starting" })).toBe<SessionState>("connecting");
});
it("connecting → connected on open", () => {
expect(reduceState("connecting", { kind: "open" })).toBe<SessionState>("connected");
});
it("connected → disconnected on close (not logged out)", () => {
expect(reduceState("connected", { kind: "close", loggedOut: false })).toBe<SessionState>(
"disconnected",
);
});
it("any → logged_out on logged-out close", () => {
expect(reduceState("connected", { kind: "close", loggedOut: true })).toBe<SessionState>(
"logged_out",
);
expect(reduceState("connecting", { kind: "close", loggedOut: true })).toBe<SessionState>(
"logged_out",
);
});
it("ignores stray events that don't match transitions", () => {
expect(reduceState("connected", { kind: "starting" })).toBe<SessionState>("connected");
});
});
```
- [ ] **Step 2: Run failing test**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 3: Implement `apps/bot/src/whatsapp/session-manager.ts`**
```typescript
import { eq } from "drizzle-orm";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../db.js";
import { logger } from "../logger.js";
import { startSession, type Session, type SessionEvent } from "./session.js";
export type SessionState =
| "pending"
| "connecting"
| "connected"
| "disconnected"
| "logged_out"
| "banned";
export type StateEvent =
| { kind: "starting" }
| { kind: "open" }
| { kind: "close"; loggedOut: boolean };
export function reduceState(current: SessionState, event: StateEvent): SessionState {
if (event.kind === "starting" && current === "pending") return "connecting";
if (event.kind === "open" && (current === "connecting" || current === "disconnected")) {
return "connected";
}
if (event.kind === "close") {
if (event.loggedOut) return "logged_out";
return "disconnected";
}
return current;
}
export type SessionListener = (
accountId: string,
state: SessionState,
event: SessionEvent,
) => void | Promise<void>;
class SessionManager {
private sessions = new Map<string, Session>();
private states = new Map<string, SessionState>();
private listeners = new Set<SessionListener>();
private reconnectTimers = new Map<string, NodeJS.Timeout>();
on(listener: SessionListener): () => void {
this.listeners.add(listener);
return () => {
this.listeners.delete(listener);
};
}
getState(accountId: string): SessionState {
return this.states.get(accountId) ?? "pending";
}
getCounts(): Record<SessionState, number> {
const counts: Record<SessionState, number> = {
pending: 0,
connecting: 0,
connected: 0,
disconnected: 0,
logged_out: 0,
banned: 0,
};
for (const state of this.states.values()) counts[state]++;
return counts;
}
hasSession(accountId: string): boolean {
return this.sessions.has(accountId);
}
getSession(accountId: string): Session | undefined {
return this.sessions.get(accountId);
}
async start(accountId: string): Promise<void> {
if (this.sessions.has(accountId)) {
logger.debug({ accountId }, "session-manager: already running, ignoring start");
return;
}
const existingTimer = this.reconnectTimers.get(accountId);
if (existingTimer) {
clearTimeout(existingTimer);
this.reconnectTimers.delete(accountId);
}
this.transition(accountId, { kind: "starting" });
const session = await startSession({
accountId,
onEvent: (event) => this.handleEvent(accountId, event),
});
this.sessions.set(accountId, session);
}
async stop(accountId: string): Promise<void> {
const timer = this.reconnectTimers.get(accountId);
if (timer) {
clearTimeout(timer);
this.reconnectTimers.delete(accountId);
}
const session = this.sessions.get(accountId);
if (!session) return;
await session.close();
this.sessions.delete(accountId);
}
async stopAll(): Promise<void> {
await Promise.all([...this.sessions.keys()].map((id) => this.stop(id)));
}
async resumeFromDb(): Promise<void> {
const rows = await db
.select({ id: whatsappAccounts.id, status: whatsappAccounts.status })
.from(whatsappAccounts);
for (const row of rows) {
if (row.status === "connected" || row.status === "disconnected") {
try {
await this.start(row.id);
} catch (err) {
logger.warn({ err, accountId: row.id }, "resumeFromDb: failed to start");
}
}
}
}
private async handleEvent(accountId: string, event: SessionEvent): Promise<void> {
if (event.type === "open") {
this.transition(accountId, { kind: "open" });
await db
.update(whatsappAccounts)
.set({
status: "connected",
phoneNumber: event.phoneNumber ?? null,
lastConnectedAt: new Date(),
})
.where(eq(whatsappAccounts.id, accountId));
} else if (event.type === "close") {
this.transition(accountId, { kind: "close", loggedOut: event.loggedOut });
await db
.update(whatsappAccounts)
.set({ status: event.loggedOut ? "logged_out" : "disconnected" })
.where(eq(whatsappAccounts.id, accountId));
if (!event.loggedOut) {
const timer = setTimeout(() => {
this.reconnectTimers.delete(accountId);
void this.stop(accountId).then(() => this.start(accountId));
}, 5000);
this.reconnectTimers.set(accountId, timer);
} else {
await this.stop(accountId);
}
} else if (event.type === "qr") {
await db
.update(whatsappAccounts)
.set({ lastQrAt: new Date() })
.where(eq(whatsappAccounts.id, accountId));
}
for (const listener of this.listeners) {
try {
await listener(accountId, this.getState(accountId), event);
} catch (err) {
logger.warn({ err, accountId }, "session-manager: listener error");
}
}
}
private transition(accountId: string, event: StateEvent): void {
const current = this.states.get(accountId) ?? "pending";
const next = reduceState(current, event);
if (current !== next) {
logger.info({ accountId, from: current, to: next }, "session-manager: state change");
}
this.states.set(accountId, next);
}
}
export const sessionManager = new SessionManager();
```
- [ ] **Step 4: Run test (expect pass)**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot test
```
- [ ] **Step 5: Wire session-manager into `apps/bot/src/index.ts`**
Replace the file:
```typescript
import { logger } from "./logger.js";
import { pool } from "./db.js";
import { startHealthServer, setSessionCountsProvider } from "./health.js";
import { createTelegramBot } from "./telegram/bot.js";
import { sessionManager } from "./whatsapp/session-manager.js";
async function main(): Promise<void> {
logger.info("bot starting");
const health = startHealthServer();
setSessionCountsProvider(() => sessionManager.getCounts());
const tg = createTelegramBot();
void tg.start({
onStart: (info) => logger.info({ username: info.username }, "telegram polling started"),
drop_pending_updates: true,
});
await sessionManager.resumeFromDb();
const shutdown = async (signal: string): Promise<void> => {
logger.info({ signal }, "shutting down");
await tg.stop();
await sessionManager.stopAll();
health.close();
await pool.end();
process.exit(0);
};
process.on("SIGINT", () => void shutdown("SIGINT"));
process.on("SIGTERM", () => void shutdown("SIGTERM"));
logger.info("bot ready");
}
main().catch((err) => {
logger.fatal({ err }, "bot failed to start");
process.exit(1);
});
```
- [ ] **Step 6: Typecheck**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```
- [ ] **Step 7: Commit**
```bash
git add apps/bot
git -c commit.gpgsign=false commit -m "feat(bot): add session manager with state machine + reconnect"
```
---
## Task 20: Group sync (pull WA groups → upsert DB)
**Files:**
- Create: `apps/bot/src/whatsapp/group-sync.ts`
- [ ] **Step 1: Implement `apps/bot/src/whatsapp/group-sync.ts`**
```typescript
import { sql } from "drizzle-orm";
import type { WASocket } from "@whiskeysockets/baileys";
import { whatsappGroups } from "@cmbot/db";
import { db } from "../db.js";
import { logger } from "../logger.js";
export async function syncGroupsForAccount(
accountId: string,
socket: WASocket,
): Promise<{ synced: number }> {
const meta = await socket.groupFetchAllParticipating();
const entries = Object.values(meta);
if (entries.length === 0) {
logger.info({ accountId }, "group-sync: no groups");
return { synced: 0 };
}
const rows = entries.map((g) => ({
accountId,
waGroupJid: g.id,
name: g.subject ?? "(no subject)",
participantCount: g.participants?.length ?? 0,
isArchived: false,
lastSyncedAt: new Date(),
}));
await db
.insert(whatsappGroups)
.values(rows)
.onConflictDoUpdate({
target: [whatsappGroups.accountId, whatsappGroups.waGroupJid],
set: {
name: sql`excluded.name`,
participantCount: sql`excluded.participant_count`,
lastSyncedAt: sql`excluded.last_synced_at`,
},
});
logger.info({ accountId, count: rows.length }, "group-sync: synced");
return { synced: rows.length };
}
```
- [ ] **Step 2: Typecheck**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```
- [ ] **Step 3: Commit**
```bash
git add apps/bot/src/whatsapp/group-sync.ts
git -c commit.gpgsign=false commit -m "feat(bot): add group sync upsert"
```
---
## Task 21: /pair, /unpair, /accounts, /groups commands
**Files:**
- Create: `apps/bot/src/telegram/commands/pair.ts`
- Create: `apps/bot/src/telegram/commands/unpair.ts`
- Create: `apps/bot/src/telegram/commands/accounts.ts`
- Create: `apps/bot/src/telegram/commands/groups.ts`
- Modify: `apps/bot/src/telegram/bot.ts`
- [ ] **Step 1: Implement `apps/bot/src/telegram/commands/pair.ts`**
```typescript
import type { Context } from "grammy";
import { InputFile } from "grammy";
import { eq } from "drizzle-orm";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../../db.js";
import { logger } from "../../logger.js";
import { sessionManager } from "../../whatsapp/session-manager.js";
import { renderQrPng } from "../../whatsapp/qr-renderer.js";
import { syncGroupsForAccount } from "../../whatsapp/group-sync.js";
import { writeAuditLog } from "../../audit.js";
const qrMessageIdByAccount = new Map<string, number>();
export async function handlePair(ctx: Context): Promise<void> {
const text = ctx.message?.text ?? "";
const label = text.replace(/^\/pair\s*/, "").trim().replace(/^["']|["']$/g, "");
if (!label) {
await ctx.reply('Usage: /pair "Account Label"');
return;
}
const operatorId = ctx.from?.id;
if (!operatorId) return;
const operatorRow = await db.query.operators.findFirst({
where: (o, { eq }) => eq(o.telegramUserId, operatorId),
});
if (!operatorRow) {
await ctx.reply("Your Telegram ID is whitelisted but no operator row exists. Run scripts/db.sh seed.");
return;
}
const existing = await db.query.whatsappAccounts.findFirst({
where: (a, { eq, and }) => and(eq(a.operatorId, operatorRow.id), eq(a.label, label)),
});
if (existing && existing.status === "connected") {
await ctx.reply(`Account "${label}" is already connected. Use /unpair first.`);
return;
}
let accountId = existing?.id;
if (!accountId) {
const [created] = await db
.insert(whatsappAccounts)
.values({ operatorId: operatorRow.id, label, status: "pending" })
.returning({ id: whatsappAccounts.id });
accountId = created!.id;
}
await ctx.reply(`📡 Starting pairing for "${label}". A QR code will arrive shortly.`);
const off = sessionManager.on(async (id, _state, event) => {
if (id !== accountId) return;
try {
if (event.type === "qr") {
const png = await renderQrPng(event.payload);
const file = new InputFile(png, `pair-${id}.png`);
const caption = `📱 Scan with WhatsApp → Linked Devices.\nLabel: "${label}". Expires in ~30s.`;
const existingMsg = qrMessageIdByAccount.get(id);
if (existingMsg) {
await ctx.api.editMessageMedia(ctx.chat!.id, existingMsg, {
type: "photo",
media: file,
caption,
});
} else {
const sent = await ctx.replyWithPhoto(file, { caption });
qrMessageIdByAccount.set(id, sent.message_id);
}
} else if (event.type === "open") {
qrMessageIdByAccount.delete(id);
await ctx.reply(
`✅ "${label}" connected${event.phoneNumber ? ` as +${event.phoneNumber}` : ""}.`,
);
await writeAuditLog(db, {
operatorId: operatorRow.id,
source: "telegram",
action: "account.paired",
targetType: "whatsapp_account",
targetId: id,
payload: { label },
});
const session = sessionManager.getSession(id);
if (session) {
const result = await syncGroupsForAccount(id, session.socket);
await ctx.reply(`Synced ${result.synced} groups. Ready to send reminders.`);
}
off();
} else if (event.type === "close" && event.loggedOut) {
qrMessageIdByAccount.delete(id);
await ctx.reply(`⚠️ Pairing failed (logged out).`);
off();
}
} catch (err) {
logger.error({ err, accountId: id }, "pair handler error");
}
});
try {
await sessionManager.start(accountId);
} catch (err) {
logger.error({ err, accountId }, "pair: start failed");
await ctx.reply(`Pairing failed to start: ${(err as Error).message}`);
off();
}
}
```
- [ ] **Step 2: Implement `apps/bot/src/telegram/commands/unpair.ts`**
```typescript
import type { Context } from "grammy";
import { rm } from "node:fs/promises";
import { join } from "node:path";
import { eq } from "drizzle-orm";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../../db.js";
import { env } from "../../env.js";
import { sessionManager } from "../../whatsapp/session-manager.js";
import { writeAuditLog } from "../../audit.js";
export async function handleUnpair(ctx: Context): Promise<void> {
const text = ctx.message?.text ?? "";
const label = text.replace(/^\/unpair\s*/, "").trim().replace(/^["']|["']$/g, "");
if (!label) {
await ctx.reply('Usage: /unpair "Account Label"');
return;
}
const operatorId = ctx.from?.id;
if (!operatorId) return;
const operatorRow = await db.query.operators.findFirst({
where: (o, { eq }) => eq(o.telegramUserId, operatorId),
});
if (!operatorRow) return;
const account = await db.query.whatsappAccounts.findFirst({
where: (a, { eq, and }) => and(eq(a.operatorId, operatorRow.id), eq(a.label, label)),
});
if (!account) {
await ctx.reply(`No account labelled "${label}".`);
return;
}
await sessionManager.stop(account.id);
await rm(join(env.SESSIONS_DIR, account.id), { recursive: true, force: true });
await db
.update(whatsappAccounts)
.set({ status: "logged_out", phoneNumber: null })
.where(eq(whatsappAccounts.id, account.id));
await writeAuditLog(db, {
operatorId: operatorRow.id,
source: "telegram",
action: "account.unpaired",
targetType: "whatsapp_account",
targetId: account.id,
payload: { label },
});
await ctx.reply(`🗑 "${label}" unpaired. Session files deleted.`);
}
```
- [ ] **Step 3: Implement `apps/bot/src/telegram/commands/accounts.ts`**
```typescript
import type { Context } from "grammy";
import { db } from "../../db.js";
import { sessionManager } from "../../whatsapp/session-manager.js";
export async function handleAccounts(ctx: Context): Promise<void> {
const operatorId = ctx.from?.id;
if (!operatorId) return;
const operatorRow = await db.query.operators.findFirst({
where: (o, { eq }) => eq(o.telegramUserId, operatorId),
});
if (!operatorRow) return;
const accounts = await db.query.whatsappAccounts.findMany({
where: (a, { eq }) => eq(a.operatorId, operatorRow.id),
orderBy: (a, { asc }) => [asc(a.label)],
});
if (accounts.length === 0) {
await ctx.reply('No accounts paired yet. Use /pair "Label" to add one.');
return;
}
const lines = accounts.map((a) => {
const live = sessionManager.getState(a.id);
const phone = a.phoneNumber ? ` (+${a.phoneNumber})` : "";
return `• ${a.label}${phone} — db:${a.status} live:${live}`;
});
await ctx.reply(`📒 Paired accounts:\n${lines.join("\n")}`);
}
```
- [ ] **Step 4: Implement `apps/bot/src/telegram/commands/groups.ts`**
```typescript
import type { Context } from "grammy";
import { db } from "../../db.js";
export async function handleGroups(ctx: Context): Promise<void> {
const text = ctx.message?.text ?? "";
const label = text.replace(/^\/groups\s*/, "").trim().replace(/^["']|["']$/g, "");
if (!label) {
await ctx.reply('Usage: /groups "Account Label"');
return;
}
const operatorId = ctx.from?.id;
if (!operatorId) return;
const operatorRow = await db.query.operators.findFirst({
where: (o, { eq }) => eq(o.telegramUserId, operatorId),
});
if (!operatorRow) return;
const account = await db.query.whatsappAccounts.findFirst({
where: (a, { eq, and }) => and(eq(a.operatorId, operatorRow.id), eq(a.label, label)),
});
if (!account) {
await ctx.reply(`No account labelled "${label}".`);
return;
}
const groups = await db.query.whatsappGroups.findMany({
where: (g, { eq }) => eq(g.accountId, account.id),
orderBy: (g, { asc }) => [asc(g.name)],
});
if (groups.length === 0) {
await ctx.reply(`No groups synced for "${label}" yet.`);
return;
}
const lines = groups.slice(0, 50).map((g) => `• ${g.name} (${g.participantCount})`);
const overflow = groups.length > 50 ? `\n…and ${groups.length - 50} more` : "";
await ctx.reply(`👥 Groups in "${label}":\n${lines.join("\n")}${overflow}`);
}
```
- [ ] **Step 5: Wire commands into `apps/bot/src/telegram/bot.ts`**
Replace the file:
```typescript
import { Bot } from "grammy";
import { env } from "../env.js";
import { logger } from "../logger.js";
import { makeWhitelistMiddleware } from "./middleware/whitelist.js";
import { auditMiddleware } from "./middleware/audit.js";
import { handleStart } from "./commands/start.js";
import { handleHelp } from "./commands/help.js";
import { handlePair } from "./commands/pair.js";
import { handleUnpair } from "./commands/unpair.js";
import { handleAccounts } from "./commands/accounts.js";
import { handleGroups } from "./commands/groups.js";
export function createTelegramBot(): Bot {
const bot = new Bot(env.TELEGRAM_BOT_TOKEN);
bot.use(makeWhitelistMiddleware(env.TELEGRAM_OPERATOR_WHITELIST));
bot.use(auditMiddleware);
bot.command("start", handleStart);
bot.command("help", handleHelp);
bot.command("pair", handlePair);
bot.command("unpair", handleUnpair);
bot.command("accounts", handleAccounts);
bot.command("groups", handleGroups);
bot.catch((err) => {
logger.error({ err }, "telegram error");
});
return bot;
}
```
- [ ] **Step 6: Restart bot and typecheck**
```bash
scripts/dev.sh pnpm --filter @cmbot/bot typecheck
scripts/dev.sh restart-bot
```
- [ ] **Step 7: Commit**
```bash
git add apps/bot
git -c commit.gpgsign=false commit -m "feat(bot): add /pair /unpair /accounts /groups commands"
```
---
## Task 22: Manual end-to-end pairing test
**Files:**
- Create: `docs/superpowers/specs/manual-test-pairing.md`
- [ ] **Step 1: Create the manual test runbook**
```markdown
# Manual test: WhatsApp pairing end-to-end
Run this checklist on every release that touches the pairing flow. It can't be
automated — pairing requires a real phone scanning a QR.
## Prerequisites
- `.env.development` filled in with real values.
- `scripts/db.sh migrate && scripts/db.sh seed` ran clean.
- `scripts/dev.sh up` is running; `scripts/dev.sh logs bot` is tailing.
- Dev WhatsApp mock account installed on a test phone (NOT brother's prod accounts).
- Dev Telegram bot opened in Telegram.
## Steps
1. Send `/start` to the dev bot. Expected: welcome message.
2. Send `/help`. Expected: command list including `/pair`.
3. Send `/pair "Test Account 1"`. Expected:
- Reply: "📡 Starting pairing for 'Test Account 1'..."
- Within ~5 seconds, a QR PNG arrives.
4. On the test phone: WhatsApp → Settings → Linked Devices → Link a Device → scan the QR.
5. Within ~5 seconds expect Telegram replies:
- "✅ 'Test Account 1' connected as +60xxxxxxx" (your test phone number).
- "Synced N groups. Ready to send reminders." (N = number of WA groups).
6. Send `/accounts`. Expected: "• Test Account 1 (+60xxx) — db:connected live:connected".
7. Send `/groups "Test Account 1"`. Expected: bulleted list of groups.
8. Verify in Postgres:
```bash
scripts/dev.sh exec sh -c 'pnpm exec tsx -e "
import { Pool } from \"pg\";
const p = new Pool({ connectionString: process.env.DATABASE_URL });
console.log(\"accounts:\", (await p.query(\"SELECT label, status, phone_number FROM whatsapp_accounts\")).rows);
console.log(\"groups:\", (await p.query(\"SELECT count(*) FROM whatsapp_groups\")).rows);
console.log(\"audit:\", (await p.query(\"SELECT action FROM audit_log ORDER BY created_at DESC LIMIT 5\")).rows);
await p.end();
"'
```
Expected: account connected, groups present, audit shows `account.paired`.
9. Restart the bot: `scripts/dev.sh restart-bot`. Expected: in logs, "session-manager: state change connecting → connected" for the test account, no QR re-prompt.
10. Send `/unpair "Test Account 1"`. Expected:
- Reply: "🗑 'Test Account 1' unpaired. Session files deleted."
- `whatsapp_accounts.status` is `logged_out`.
- Directory `dev-data/sessions/<account-id>/` is gone.
## Failure modes to verify
- **QR expiry:** ignore the QR for 30s. Bot edits the same Telegram message with a new QR (no second photo). Repeat 3-5 times to verify edits keep working.
- **Wrong-account `/pair`:** as a non-whitelisted Telegram user, send `/pair "X"`. Expected: "Sorry, this bot is private."
- **Re-pair while connected:** send `/pair "Test Account 1"` again immediately after step 5. Expected: "already connected. Use /unpair first."
## Sign-off
- [ ] All steps passed
- [ ] Postgres rows match expectations
- [ ] No errors in `scripts/dev.sh logs bot`
- [ ] Tester: ____________ Date: ____________
```
- [ ] **Step 2: Run the manual test against your dev mock account**
Follow each step in `docs/superpowers/specs/manual-test-pairing.md`. If any step fails, fix the relevant task before continuing.
- [ ] **Step 3: Commit**
```bash
git add docs/superpowers/specs/manual-test-pairing.md
git -c commit.gpgsign=false commit -m "docs: add manual end-to-end pairing test runbook"
```
---
## Task 23: README and final push
**Files:**
- Create: `README.md`
- [ ] **Step 1: Create `README.md`**
```markdown
# cm WhatsApp Reminder Bot
Self-hosted WhatsApp reminder bot. Pairs multiple WhatsApp accounts via Telegram-delivered QR codes and sends scheduled reminders to groups.
## Status
**Plan 1 complete.** Foundation, DB schema, and Telegram-driven WhatsApp pairing are working end-to-end. Reminder scheduling, the web dashboard, and production deploy are upcoming plans (`docs/superpowers/plans/`).
## Host requirements
Only Docker. No host Node, pnpm, or any other language toolchain — everything runs in containers via the long-lived `tools` service.
## Quick start (dev)
```bash
# 1. Configure env (after creating dev DB on 192.168.0.210 and a dev Telegram bot)
cp envs/.env.example .env.development
# edit .env.development with real values
scripts/gen_auth_secret.sh --write
# 2. Bring up the tools container, install deps, run migrations
scripts/dev.sh up
scripts/dev.sh pnpm install
scripts/db.sh migrate
scripts/db.sh seed
# 3. Watch the bot service
scripts/dev.sh logs bot
```
In Telegram, message your dev bot `/start`, then `/pair "Test"`.
## Layout
- `apps/bot/` — Node service: Baileys WhatsApp + grammy Telegram + (later) pg-boss scheduler
- `apps/web/` — Next.js dashboard (plan 3)
- `packages/db/` — Drizzle schema and migrations
- `packages/shared/` — cross-app helpers
- `docs/superpowers/specs/` — design specs and manual test runbooks
- `docs/superpowers/plans/` — implementation plans
## Scripts
All scripts run in the tools container (no host Node required).
- `scripts/dev.sh up|down|logs|status|build|exec|pnpm|shell|restart-bot` — local stack lifecycle
- `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/publish.sh` — push to Gitea registry (plan 4)
- `scripts/link-account.sh` — CLI pairing for dev (plan 2)
## Design
See `docs/superpowers/specs/2026-05-03-whatsapp-bot-design.md`.
```
- [ ] **Step 2: Commit and push**
```bash
git add README.md
git -c commit.gpgsign=false commit -m "docs: add top-level README"
git push -u origin master
```
Expected: push succeeds to `http://192.168.0.215:3000/yiekheng/cm_whatsapp_bot_v1.git`.
---
## Plan 1 done — what's working
After all 23 tasks:
- Repo skeleton on Gitea with Docker-only dev tooling.
- All 11 DB tables migrated to `whatsapp_bot_dev` on `192.168.0.210`.
- `tools` container provides Node 22 + pnpm 9 for all install/test/typecheck operations — host needs only Docker.
- `bot` service runs in Docker with structured logging and a health endpoint.
- Telegram bot accepts `/start`, `/help`, `/pair`, `/unpair`, `/accounts`, `/groups` from whitelisted users only; every command is audited.
- WhatsApp pairing: `/pair "label"` → QR delivered to Telegram → scan → connected → groups synced → confirmation back. Auto-reconnect on disconnect; logout detected; restart-survival via `useMultiFileAuthState`.
- Manual test runbook documents the verification steps.
## Next plan
`docs/superpowers/plans/<next-date>-reminder-scheduling.md` — adds pg-boss, reminder CRUD via Telegram, fire-reminder handler, sender (text/image/video), retry policy, run history. End state: brother can create one-off and recurring reminders by chatting with the bot, and they fire on time to the right groups.
Reference in New Issue View Git Blame Copy Permalink