Merge S7 (a1): newsletter — THE VYNDR REPORT

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> # Conflicts: # BUILD-STATE.md # CLAUDE.md
2026-07-11 14:32:18 -04:00
parent 48eb420f9e 32d7200571
commit fc0c7bfd18
14 changed files with 1297 additions and 0 deletions
@@ -0,0 +1,112 @@
+# THE VYNDR REPORT — Listmonk runbook (Session S7, a1)
+
+The daily newsletter: the slate, the signals, the settle. Assembly is code
+(`src/services/newsletterService.js` — numbers only from the pipeline, VOICE
+v1.1, RG footer baked in). Delivery is Listmonk, self-hosted on the same
+Hetzner box — zero out-of-pocket. Without the env vars below, every
+newsletter path is a graceful no-op: the subscribe endpoint answers
+`{ ok: false, reason: 'not configured' }` and the capture UI says
+"Signups open soon."
+
+Nothing is scheduled. The send is operator-triggered via the internal route
+until Kev arms a cron.
+
+## 1. Deploy Listmonk on the box (Coolify)
+
+Listmonk is a single Go binary + Postgres. In Coolify: new service →
+Docker image `listmonk/listmonk:latest` + a Postgres 16 resource
+(or reuse an existing Postgres with a fresh `listmonk` database).
+
+Minimum container env:
+
+```
+LISTMONK_app__address=0.0.0.0:9000
+LISTMONK_db__host=<postgres host>
+LISTMONK_db__port=5432
+LISTMONK_db__user=listmonk
+LISTMONK_db__password=<generate>
+LISTMONK_db__database=listmonk
+```
+
+First boot needs the schema install: run `./listmonk --install` once
+(Coolify: one-off command on the container), then start normally. Log in at
+the service URL, change the default `listmonk` admin password immediately.
+
+Configure SMTP under Settings → SMTP (any relay you already have; without a
+working SMTP block the double-opt-in confirmations never leave the box —
+test this first).
+
+## 2. Create the list
+
+Admin UI → Lists → New:
+- Name: `THE VYNDR REPORT`
+- Type: **private**
+- Opt-in: **double** ← required. The API subscribe call sends
+  `preconfirm_subscriptions: false`; Listmonk then emails the confirmation.
+  Nothing lands on the list until the reader clicks it.
+
+Note the numeric list id shown in the UI/URL — that is `LISTMONK_LIST_ID`.
+
+## 3. Create an API user (never use the admin login for the app)
+
+Admin UI → Settings → Users → New:
+- Username: `vyndr-api`
+- Type: API user → Listmonk generates a token. Copy it once; it is not shown again.
+- Role: needs `subscribers:manage` + `campaigns:manage` + `campaigns:get`
+  (or a role scoped to exactly those).
+
+The app authenticates with `Authorization: token vyndr-api:<token>`.
+
+## 4. Env vars for the VYNDR backend (Coolify → the Express app)
+
+```
+LISTMONK_URL=http://<listmonk container name>:9000   # same box — use the internal network, not the public URL
+LISTMONK_USER=vyndr-api
+LISTMONK_TOKEN=<the API token from step 3>
+LISTMONK_LIST_ID=<numeric id from step 2>
+```
+
+All four are required; any missing → the whole layer no-ops (deploy-safe).
+
+## 5. Template note — one-click unsubscribe
+
+The assembled email embeds the literal `{{ UnsubscribeURL }}` placeholder in
+its RG footer. Listmonk substitutes it per-recipient at send time — do not
+"fix" it in the service. The RG footer (21+, 1-800-GAMBLER, unsubscribe note)
+is baked into `newsletterService` and asserted by
+`tests/unit/newsletterService.test.js`; every send carries it.
+
+## 6. Test-send steps
+
+1. Subscribe yourself through the product: the landing-page capture (or
+   `curl -X POST https://vyndr.app/api/newsletter/subscribe -H 'Content-Type: application/json' -d '{"email":"kevdevelops@gmail.com"}'`).
+2. Confirm the double-opt-in email arrives and click it — you should show as
+   `confirmed` on the list in the Listmonk UI.
+3. Fire a real send (internal key, operator-triggered):
+
+```
+curl -X POST https://<backend>/api/internal/newsletter/send \
+  -H "x-internal-key: $VYNDR_INTERNAL_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"sports":["mlb","wnba"]}'
+```
+
+Responses:
+- `{ ok: true, campaignId, subject, counts }` — sent; check the inbox +
+  Listmonk → Campaigns for delivery stats.
+- `{ ok: false, reason: 'empty report' }` — zero signals AND zero streaks at
+  send time (off-hours / cold caches). Deliberate: an empty email never sends.
+  Run after the morning snapshot (14:00 UTC) so the slate is graded.
+- `{ ok: false, reason: 'not configured' }` — env missing on the backend.
+
+4. Verify the received email: mono layout, signals match `/api/snapshot/mlb`,
+   the record line matches `/api/ledger/accuracy` gating (a percentage only at
+   n≥20, otherwise `RECORD BUILDING · N pending`), RG footer present, and the
+   unsubscribe link is a working per-recipient Listmonk URL.
+
+## 7. Scheduling (NOT armed)
+
+When Kev decides to arm the daily send, point an n8n cron (or the box
+crontab) at the internal route above — e.g. daily at 15:30 UTC, after the
+14:00 UTC snapshot has graded the slate. There is deliberately no in-process
+scheduler for this; email to subscribers stays operator-controlled until then.