@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/newsletter/digest.ts

@@ -0,0 +1,117 @@
+/**
+ * Hand-rolled newsletter digest HTML builder — the email analogue of
+ * `renderRssFeed` (src/lib/blog/rss.ts): pure string concatenation, no
+ * templating dependency. Fed the engine's live-visible post list, so drafts /
+ * unlisted / not-yet-scheduled posts can never reach an inbox.
+ *
+ * The digest is built ONCE per send and carries a per-recipient unsubscribe
+ * token PLACEHOLDER ({@link UNSUBSCRIBE_TOKEN_PLACEHOLDER}); the send pipeline
+ * interpolates each subscriber's real token before handing the message to the
+ * ESP (see send.ts). The RFC 8058 `List-Unsubscribe` headers are set on the
+ * SEND call, not in this HTML body.
+ */
+import type { BlogPostSummary } from "../blog/types.js";
+
+/** Replaced per-recipient with the subscriber's opaque token at send time. */
+export const UNSUBSCRIBE_TOKEN_PLACEHOLDER = "{{unsubscribe_token}}";
+
+/** The unsubscribe endpoint path (N3 owns the route); shared with the send headers. */
+export const UNSUBSCRIBE_PATH = "/api/newsletter/unsubscribe";
+
+export interface DigestConfig {
+  /** CAN-SPAM physical postal address, rendered in the footer (per-tenant config). */
+  postalAddress: string;
+  /** Sender display name; used only for the digest heading here. */
+  fromName?: string;
+  /** Resolved canonical base, e.g. `https://x.com` — post links + unsubscribe URL. */
+  canonicalBase: string;
+}
+
+/** Build the one-click unsubscribe URL for a given token (or placeholder). */
+export function unsubscribeUrl(canonicalBase: string, token: string): string {
+  const base = canonicalBase.replace(/\/$/, "");
+  return `${base}${UNSUBSCRIBE_PATH}?token=${token}`;
+}
+
+/** HTML-escape text placed in element content or a quoted attribute. */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const MONTHS = [
+  "January", "February", "March", "April", "May", "June",
+  "July", "August", "September", "October", "November", "December",
+];
+
+/** Deterministic UTC "Month D, YYYY" (no locale/timezone drift in tests). */
+function formatDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}
+
+/**
+ * Render the digest email body. `collection` fixes the route base (`/<collection>`,
+ * mirroring the RSS renderer's `collectionBase`) so post links resolve to the
+ * live article. Every message carries an unsubscribe link (placeholder token)
+ * and the CAN-SPAM postal address in the footer.
+ */
+export function buildDigestHtml(
+  tenantId: string,
+  collection: string,
+  posts: BlogPostSummary[],
+  config: DigestConfig,
+): string {
+  const base = config.canonicalBase.replace(/\/$/, "");
+  const collectionBase = `/${collection.replace(/^\/+|\/+$/g, "")}`;
+  const heading = escapeHtml(config.fromName ?? "The latest");
+
+  const items = posts
+    .map((post) => {
+      const link = `${base}${collectionBase}/${post.slug}/`;
+      const date = formatDate(post.publishedAt);
+      const image = post.featuredImage
+        ? `      <p><a href="${escapeHtml(link)}"><img src="${escapeHtml(post.featuredImage.src)}" alt="${escapeHtml(post.featuredImage.alt)}" style="max-width:100%;height:auto;border-radius:8px;" /></a></p>`
+        : "";
+      return [
+        `    <article style="margin:0 0 2rem;">`,
+        image,
+        `      <h2 style="margin:0 0 .35rem;font-size:1.25rem;"><a href="${escapeHtml(link)}" style="color:#2f3a34;text-decoration:none;">${escapeHtml(post.title)}</a></h2>`,
+        date ? `      <p style="margin:0 0 .5rem;color:#8a938c;font-size:.85rem;">${escapeHtml(date)}</p>` : "",
+        `      <p style="margin:0 0 .5rem;color:#5a655e;line-height:1.6;">${escapeHtml(post.excerpt)}</p>`,
+        `      <p style="margin:0;"><a href="${escapeHtml(link)}" style="color:#2f3a34;font-weight:600;">Read more &rarr;</a></p>`,
+        `    </article>`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    })
+    .join("\n");
+
+  const unsubUrl = unsubscribeUrl(config.canonicalBase, UNSUBSCRIBE_TOKEN_PLACEHOLDER);
+  const postalHtml = escapeHtml(config.postalAddress).replace(/\n/g, "<br />");
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body style="margin:0;background:#f4f1ea;color:#2f3a34;font-family:ui-serif,Georgia,serif;">
+    <div style="max-width:37.5rem;margin:0 auto;padding:2rem 1.5rem;">
+      <h1 style="font-size:1.5rem;margin:0 0 1.5rem;">${heading}</h1>
+${items}
+      <hr style="border:none;border-top:1px solid #d8d3c6;margin:2rem 0 1rem;" />
+      <p style="color:#8a938c;font-size:.8rem;line-height:1.6;margin:0 0 .5rem;">
+        You're receiving this because you subscribed. <a href="${escapeHtml(unsubUrl)}" style="color:#8a938c;">Unsubscribe</a>.
+      </p>
+      <p style="color:#8a938c;font-size:.8rem;line-height:1.6;margin:0;">${postalHtml}</p>
+    </div>
+  </body>
+</html>
+`;
+}

package/apps/storefront/src/lib/newsletter/resendClient.ts

@@ -0,0 +1,79 @@
+/**
+ * Thin `fetch`-based Resend client — no SDK, no npm dependency (the newsletter
+ * spike's Workers-native rationale, docs/plans/2026-08-22-newsletter-send-spike.md
+ * §1). We use Resend purely as an SMTP-over-HTTPS sender via its batch endpoint
+ * (`POST /emails/batch`, up to 100 messages/call); audience/consent/unsubscribe
+ * state stays first-party in our D1, never in a vendor list.
+ */
+import { readEnv } from "../env.js";
+
+/** Resend's batch limit: at most 100 messages per `/emails/batch` call. */
+export const RESEND_BATCH_LIMIT = 100;
+
+const RESEND_BATCH_URL = "https://api.resend.com/emails/batch";
+
+/** One message in a batch. `reply_to`/`headers` use Resend's wire field names. */
+export interface ResendEmail {
+  from: string;
+  to: string | string[];
+  subject: string;
+  html: string;
+  reply_to?: string;
+  headers?: Record<string, string>;
+}
+
+export interface SendBatchResult {
+  ok: boolean;
+  status: number;
+  /** Provider message ids (`data[].id`), one per accepted message. */
+  ids: string[];
+  /** Present when `ok` is false — the provider error text, for logging. */
+  error?: string;
+}
+
+/** The send seam — real impl below; injected as a fake in tests. */
+export type SendBatchFn = (apiKey: string, emails: ResendEmail[]) => Promise<SendBatchResult>;
+
+/** The `RESEND_API_KEY` secret, read via the runtime env accessor (undefined if unset). */
+export function readResendApiKey(): Promise<string | undefined> {
+  return readEnv("RESEND_API_KEY");
+}
+
+/**
+ * Send up to {@link RESEND_BATCH_LIMIT} messages in one call. An empty list is a
+ * no-op success (nothing to send). Never throws for a transport/HTTP error —
+ * returns `{ ok:false }` so the caller decides whether a partial send should
+ * still record its ledger row.
+ */
+export const sendBatch: SendBatchFn = async (apiKey, emails) => {
+  if (emails.length === 0) return { ok: true, status: 200, ids: [] };
+  if (emails.length > RESEND_BATCH_LIMIT) {
+    throw new Error(`sendBatch received ${emails.length} messages; max is ${RESEND_BATCH_LIMIT}`);
+  }
+  let res: Response;
+  try {
+    res = await fetch(RESEND_BATCH_URL, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(emails),
+    });
+  } catch (err) {
+    return { ok: false, status: 0, ids: [], error: String(err) };
+  }
+
+  const bodyText = await res.text();
+  if (!res.ok) {
+    return { ok: false, status: res.status, ids: [], error: bodyText };
+  }
+  let ids: string[] = [];
+  try {
+    const parsed = JSON.parse(bodyText) as { data?: Array<{ id?: string }> };
+    ids = (parsed.data ?? []).map((d) => d.id ?? "").filter(Boolean);
+  } catch {
+    // Accepted (2xx) but unparseable body — treat as sent, no ids surfaced.
+  }
+  return { ok: true, status: res.status, ids };
+};

package/apps/storefront/src/lib/newsletter/send.ts

@@ -0,0 +1,265 @@
+/**
+ * Weekly-digest send orchestration (newsletter-send epic, N4). A single callable
+ * `sendWeeklyDigest` that N5's admin trigger endpoint invokes; this unit builds
+ * NO HTTP route. Flow (docs/plans/2026-08-22-newsletter-send-spike.md §5–6):
+ *
+ *   1. Compute this period's `digestId` (`<collection>-<ISO-week>`) and short-
+ *      circuit if a `newsletter_sends` row already exists for it — the
+ *      idempotency guard that stops a re-triggered send from double-sending.
+ *   2. Collect posts published SINCE the last send (all live posts on the first
+ *      ever send). Empty → skip, no ledger row burned.
+ *   3. Query `confirmed` subscribers; none → skip.
+ *   4. Build the digest ONCE, personalize the unsubscribe token per recipient,
+ *      batch-send via Resend (≤100/call), then record the ledger row and stamp
+ *      each recipient's `last_sent_at`.
+ *
+ * Idempotency design (the spike offered two; this is the simpler): scope is the
+ * whole SEND, keyed by ISO-week `digestId` in `newsletter_sends` — NOT a
+ * per-subscriber diff. "New since last send" is computed once from the previous
+ * ledger row's `sent_at`, not per-subscriber.
+ */
+import type { Queryable } from "../d1/catalog.js";
+import type { BlogPostSummary } from "../blog/types.js";
+import {
+  sendBatch as realSendBatch,
+  RESEND_BATCH_LIMIT,
+  type ResendEmail,
+  type SendBatchFn,
+} from "./resendClient.js";
+import {
+  buildDigestHtml,
+  unsubscribeUrl,
+  UNSUBSCRIBE_TOKEN_PLACEHOLDER,
+  type DigestConfig,
+} from "./digest.js";
+
+export interface SendDeps {
+  db: Queryable;
+  /** Live-visible post source (the engine's `listPosts`); drafts never leak. */
+  listPosts: (tenantId: string, collection: string) => Promise<BlogPostSummary[]>;
+  resendApiKey: string;
+  config: DigestConfig & {
+    /** Verified sending address, e.g. `the-build@mail.tokenoftrust.store`. */
+    fromAddress: string;
+    /** `Reply-To:`; falls back to `fromAddress`. */
+    replyTo?: string;
+  };
+  /** Send seam — tests inject a fake; defaults to the real Resend client. */
+  sendBatch?: SendBatchFn;
+  /** Clock injection for deterministic digest ids + timestamps. */
+  now?: () => Date;
+}
+
+export type SendResult =
+  | { sent: number; digestId: string }
+  | { skipped: true; reason: string };
+
+/** The reasons a send would perform NO work — shared by preview and send. */
+export type DigestSkipReason = "already-sent-this-period" | "no-new-posts" | "no-subscribers";
+
+/** The shared verified sending domain (SPF/DKIM/DMARC configured with Resend). */
+export const NEWSLETTER_SENDING_DOMAIN = "mail.tokenoftrust.store";
+
+/**
+ * Resolve the digest's `From:` address. An explicit per-tenant `fromAddress`
+ * wins; otherwise derive `<collection>@mail.tokenoftrust.store` on the shared
+ * verified domain. Deliberately NEVER derives from the tenant's own store domain
+ * — that domain is not a verified sending domain, so a send from it would fail
+ * SPF/DKIM alignment at the ESP.
+ */
+export function resolveFromAddress(collection: string, configured?: string): string {
+  const explicit = configured?.trim();
+  if (explicit) return explicit;
+  const localPart =
+    collection.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "newsletter";
+  return `${localPart}@${NEWSLETTER_SENDING_DOMAIN}`;
+}
+
+interface SubscriberRow {
+  email: string;
+  token: string;
+}
+
+/** The read-only shape a dry-run preview needs (no send seam / api key). */
+export interface PreviewDeps {
+  db: Queryable;
+  listPosts: (tenantId: string, collection: string) => Promise<BlogPostSummary[]>;
+  now?: () => Date;
+}
+
+/** What a send WOULD do this period, computed without sending anything. */
+export interface DigestPreview {
+  digestId: string;
+  /** Posts published since the last send (empty when nothing new). */
+  postCount: number;
+  postSlugs: string[];
+  /** Confirmed recipients that would receive the digest. */
+  recipientCount: number;
+  /** Set when a real send would skip; absent when a send would go out. */
+  skip?: DigestSkipReason;
+}
+
+async function countConfirmed(db: Queryable, tenantId: string, collection: string): Promise<number> {
+  const row = await db.first<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM newsletter_subscribers
+      WHERE tenant_id = ? AND collection = ? AND status = 'confirmed'`,
+    tenantId, collection,
+  );
+  return Number(row?.n ?? 0);
+}
+
+/**
+ * Steps (1)+(2) of the send flow, read-only: whether this period was already
+ * sent, and the posts published since the last send. Shared verbatim by
+ * {@link previewWeeklyDigest} and {@link sendWeeklyDigest} so the dry-run preview
+ * can never diverge from what the real send computes.
+ */
+async function selectNewPosts(
+  deps: PreviewDeps,
+  tenantId: string,
+  collection: string,
+  digestId: string,
+): Promise<{ alreadySent: boolean; newPosts: BlogPostSummary[] }> {
+  const existing = await deps.db.first<{ digest_id: string }>(
+    `SELECT digest_id FROM newsletter_sends
+      WHERE tenant_id = ? AND collection = ? AND digest_id = ?`,
+    tenantId, collection, digestId,
+  );
+  if (existing) return { alreadySent: true, newPosts: [] };
+
+  const lastSend = await deps.db.first<{ sent_at: string }>(
+    `SELECT sent_at FROM newsletter_sends
+      WHERE tenant_id = ? AND collection = ?
+      ORDER BY sent_at DESC LIMIT 1`,
+    tenantId, collection,
+  );
+  const sinceMs = lastSend ? new Date(lastSend.sent_at).getTime() : null;
+  const posts = await deps.listPosts(tenantId, collection);
+  const newPosts = posts.filter(
+    (p) => sinceMs === null || new Date(p.publishedAt).getTime() > sinceMs,
+  );
+  return { alreadySent: false, newPosts };
+}
+
+/**
+ * Compute what a weekly digest WOULD send this period — post count, post slugs,
+ * and confirmed-recipient count — WITHOUT calling the ESP or writing any ledger
+ * row. Backs the admin "Send digest" dry-run/confirm dialog (N5).
+ */
+export async function previewWeeklyDigest(
+  tenantId: string,
+  collection: string,
+  deps: PreviewDeps,
+): Promise<DigestPreview> {
+  const now = deps.now?.() ?? new Date();
+  const digestId = `${collection}-${isoWeekId(now)}`;
+  const { alreadySent, newPosts } = await selectNewPosts(deps, tenantId, collection, digestId);
+  const recipientCount = await countConfirmed(deps.db, tenantId, collection);
+
+  let skip: DigestSkipReason | undefined;
+  if (alreadySent) skip = "already-sent-this-period";
+  else if (newPosts.length === 0) skip = "no-new-posts";
+  else if (recipientCount === 0) skip = "no-subscribers";
+
+  return {
+    digestId,
+    postCount: newPosts.length,
+    postSlugs: newPosts.map((p) => p.slug),
+    recipientCount,
+    skip,
+  };
+}
+
+/** ISO-8601 week-numbering id (`YYYY-Www`), Thursday-anchored. */
+export function isoWeekId(d: Date): string {
+  const date = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const dayNum = (date.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+  date.setUTCDate(date.getUTCDate() - dayNum + 3); // Thursday of this week
+  const firstThursday = new Date(Date.UTC(date.getUTCFullYear(), 0, 4));
+  const ftDayNum = (firstThursday.getUTCDay() + 6) % 7;
+  firstThursday.setUTCDate(firstThursday.getUTCDate() - ftDayNum + 3);
+  const week = 1 + Math.round((date.getTime() - firstThursday.getTime()) / (7 * 86400000));
+  return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+export async function sendWeeklyDigest(
+  tenantId: string,
+  collection: string,
+  deps: SendDeps,
+): Promise<SendResult> {
+  const now = deps.now?.() ?? new Date();
+  const nowIso = now.toISOString();
+  const send = deps.sendBatch ?? realSendBatch;
+  const digestId = `${collection}-${isoWeekId(now)}`;
+
+  // (1)+(2) Idempotency + posts published since the last send (shared with the
+  // dry-run preview so the two can never diverge).
+  const { alreadySent, newPosts } = await selectNewPosts(deps, tenantId, collection, digestId);
+  if (alreadySent) return { skipped: true, reason: "already-sent-this-period" };
+  if (newPosts.length === 0) return { skipped: true, reason: "no-new-posts" };
+
+  // (3) Confirmed recipients only.
+  const subscribers = await deps.db.all<SubscriberRow>(
+    `SELECT email, token FROM newsletter_subscribers
+      WHERE tenant_id = ? AND collection = ? AND status = 'confirmed'`,
+    tenantId, collection,
+  );
+  if (subscribers.length === 0) return { skipped: true, reason: "no-subscribers" };
+
+  // (4) Build once, personalize the unsubscribe token per recipient, batch-send.
+  const digestHtml = buildDigestHtml(tenantId, collection, newPosts, deps.config);
+  const from = deps.config.fromName
+    ? `${deps.config.fromName} <${deps.config.fromAddress}>`
+    : deps.config.fromAddress;
+  const subject = deps.config.fromName ? `${deps.config.fromName} — new this week` : "New this week";
+
+  const emails: ResendEmail[] = subscribers.map((s) => {
+    const unsubUrl = unsubscribeUrl(deps.config.canonicalBase, s.token);
+    return {
+      from,
+      to: s.email,
+      subject,
+      html: digestHtml.split(UNSUBSCRIBE_TOKEN_PLACEHOLDER).join(s.token),
+      reply_to: deps.config.replyTo ?? deps.config.fromAddress,
+      headers: {
+        // RFC 8058 one-click unsubscribe (Gmail/Yahoo bulk-sender requirement).
+        "List-Unsubscribe": `<${unsubUrl}>`,
+        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+      },
+    };
+  });
+
+  let sent = 0;
+  const sentEmails: string[] = [];
+  for (const batch of chunk(emails, RESEND_BATCH_LIMIT)) {
+    const result = await send(deps.resendApiKey, batch);
+    if (result.ok) {
+      sent += batch.length;
+      for (const e of batch) sentEmails.push(e.to as string);
+    }
+  }
+
+  // (5) Record the ledger row (idempotency key) + stamp recipients.
+  await deps.db.run(
+    `INSERT OR IGNORE INTO newsletter_sends
+       (tenant_id, collection, digest_id, post_slugs, recipient_count, sent_at)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    tenantId, collection, digestId,
+    JSON.stringify(newPosts.map((p) => p.slug)), sent, nowIso,
+  );
+  for (const email of sentEmails) {
+    await deps.db.run(
+      `UPDATE newsletter_subscribers SET last_sent_at = ?
+        WHERE tenant_id = ? AND collection = ? AND email = ?`,
+      nowIso, tenantId, collection, email,
+    );
+  }
+
+  return { sent, digestId };
+}

package/apps/storefront/src/lib/newsletter/subscribers.ts

@@ -0,0 +1,156 @@
+/**
+ * `newsletter_subscribers` store — the first-party audience for the blog digest
+ * (newsletter-send epic, N2). Kept in OUR `STOREFRONT_APPS_DB` (not a vendor
+ * list) so the per-tenant isolation + GDPR data-control invariants stay under
+ * our control (docs/plans/2026-08-22-newsletter-send-spike.md §2).
+ *
+ * Pure over the `Queryable` seam (see `../d1/catalog.ts`), so the same code runs
+ * against real D1 in the Worker and an in-memory `node:sqlite` in tests. The
+ * caller is responsible for resolving `tenantId` from the request host/session
+ * (NEVER a client body) — that is the multi-tenant isolation boundary.
+ */
+import type { Queryable } from "../d1/catalog.js";
+
+export type SubscriberStatus = "pending" | "confirmed" | "unsubscribed" | "bounced";
+
+export interface SubscribeInput {
+  tenantId: string;
+  collection: string;
+  /** Already lowercased + trimmed by the caller. */
+  email: string;
+  token: string;
+  consentSource?: string | null;
+  consentIpHash?: string | null;
+}
+
+export interface SubscribeResult {
+  /** True when this call inserted a new pending row (vs. hitting an existing one). */
+  created: boolean;
+  status: SubscriberStatus;
+  /** The row's live token — the new one when created, the stored one otherwise. */
+  token: string;
+}
+
+export type ConfirmResult = "confirmed" | "already" | "not_found";
+
+interface SubscriberRow {
+  status: string;
+  token: string;
+  collection?: string;
+  email?: string;
+}
+
+export class NewsletterSubscribersStore {
+  constructor(
+    private readonly db: Queryable,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {}
+
+  /**
+   * Enrol an email as `pending`, keyed `(tenant_id, collection, email)`. A
+   * repeat subscribe is idempotent (`INSERT OR IGNORE`): the existing row is
+   * returned untouched, so a still-pending signer can be re-sent their confirm
+   * mail while a confirmed/unsubscribed one is never silently resurrected.
+   */
+  async subscribe(input: SubscribeInput): Promise<SubscribeResult> {
+    const existing = await this.db.first<SubscriberRow>(
+      `SELECT status, token FROM newsletter_subscribers
+        WHERE tenant_id = ? AND collection = ? AND email = ?`,
+      input.tenantId,
+      input.collection,
+      input.email,
+    );
+    if (existing) {
+      return { created: false, status: existing.status as SubscriberStatus, token: existing.token };
+    }
+    await this.db.run(
+      `INSERT OR IGNORE INTO newsletter_subscribers
+         (tenant_id, collection, email, status, token, consent_source, consent_ip_hash, subscribed_at)
+       VALUES (?, ?, ?, 'pending', ?, ?, ?, ?)`,
+      input.tenantId,
+      input.collection,
+      input.email,
+      input.token,
+      input.consentSource ?? null,
+      input.consentIpHash ?? null,
+      this.now(),
+    );
+    return { created: true, status: "pending", token: input.token };
+  }
+
+  /**
+   * Flip a `pending` subscriber to `confirmed` by its opaque token, scoped to
+   * the caller's tenant. Idempotent: re-confirming an already-`confirmed` token
+   * is a no-op success, not an error. An unknown token — or one whose row is
+   * `unsubscribed`/`bounced` (the confirm link is no longer valid) — is
+   * `not_found`.
+   */
+  async confirmByToken(input: { tenantId: string; token: string }): Promise<ConfirmResult> {
+    const row = await this.db.first<SubscriberRow>(
+      `SELECT status FROM newsletter_subscribers WHERE tenant_id = ? AND token = ?`,
+      input.tenantId,
+      input.token,
+    );
+    if (!row) return "not_found";
+    if (row.status === "confirmed") return "already";
+    if (row.status !== "pending") return "not_found";
+    await this.db.run(
+      `UPDATE newsletter_subscribers
+          SET status = 'confirmed', confirmed_at = ?
+        WHERE tenant_id = ? AND token = ? AND status = 'pending'`,
+      this.now(),
+      input.tenantId,
+      input.token,
+    );
+    return "confirmed";
+  }
+}
+
+/**
+ * Outcome of an unsubscribe attempt. INTERNAL only — the HTTP layer MUST map every
+ * variant to the SAME response so an observer can't tell whether a token ever existed
+ * (`unknown` vs the others). Distinguished here purely so callers/telemetry can reason
+ * about it.
+ */
+export type UnsubscribeOutcome = "unsubscribed" | "already-unsubscribed" | "unknown-token";
+
+interface StatusRow {
+  status: string;
+}
+
+/**
+ * Flip the subscriber addressed by `token` to `unsubscribed`, stamping `unsubscribed_at`
+ * on the FIRST transition only. Idempotent: re-unsubscribing an already-unsubscribed
+ * token is a no-op success that preserves the original `unsubscribed_at`. An unknown
+ * token is a clean no-op (`unknown-token`) — never an error, never distinguishable to
+ * the caller at the HTTP layer.
+ *
+ * The `token` column is an opaque, per-subscriber random (unique across the table): it
+ * is the unsubscribe capability. A link/one-click header carries it and identifies
+ * exactly one row without ever putting the email in the URL (which would leak PII into
+ * access logs). Lookup is by token alone — no tenant/collection needed — and every
+ * write is scoped to that single token, so it can only ever touch the one row it names.
+ */
+export async function unsubscribeByToken(
+  db: Queryable,
+  token: string,
+  now: string,
+): Promise<UnsubscribeOutcome> {
+  if (!token) return "unknown-token";
+
+  const row = await db.first<StatusRow>(
+    "SELECT status FROM newsletter_subscribers WHERE token = ?",
+    token,
+  );
+  if (!row) return "unknown-token";
+  if (row.status === "unsubscribed") return "already-unsubscribed";
+
+  // Guard the UPDATE on the current status too, so a concurrent double-submit can't
+  // overwrite the first `unsubscribed_at`.
+  await db.run(
+    "UPDATE newsletter_subscribers SET status = 'unsubscribed', unsubscribed_at = ? WHERE token = ? AND status != 'unsubscribed'",
+    now,
+    token,
+  );
+  return "unsubscribed";
+}