create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/lead-routing.ts

@@ -59,27 +59,84 @@
  * as `personId`; a callback with no email makes no Person call and writes no
  * `personId`. Every one of these steps is best-effort exactly like the lead's.
  *
- * CHECKOUT PLAN (#7877 D10). A spoke's checkout fulfilment posts one
- * `submit` with the Checkout Session id as its `Idempotency-Key`. When that
- * lead is written (never on a replay) with a Person, and it is a LIVE,
- * paid checkout lead from a registered spoke's server — `viaSpoke`, a
+ * CHECKOUT PLAN (#7877 D10, #8793 D1). A spoke's checkout fulfilment posts
+ * one `submit` with the Checkout Session id as its `Idempotency-Key`. A
+ * LIVE, paid checkout lead from a registered spoke's server — `viaSpoke`, a
  * `cs_live_` key, `source: "web"`, `payload.page: "checkout"`, a string
  * `payload.offering` and `payload.site`, and an `amountTotal` that is
- * absent, `null` or a positive integer — the Person's plan becomes the
- * offering minus a leading `<site>_` (`setPersonPlanOffering`, the plan's
- * only writer). No spoke file changes. The step never throws, never changes
- * `routeLead`'s result, and logs one bare `checkout-plan` line — never the
- * offering, the email or the key. A lead that does not qualify makes no
- * Person call at all.
+ * absent, `null` or a positive integer — names a plan: the offering minus a
+ * leading `<site>_` (`person.ts`'s `checkoutPlanKey`). Its email is what
+ * the buyer typed at Stripe Checkout, which nobody verified, so the lead
+ * never writes any Person's plan (SEC-8748-D). It HOLDS it: on the first
+ * write of a marked lead (below) with a Person, the step logs one bare
+ * `{ event: "checkout-plan", outcome, siteId }` line at `info` — `held` for
+ * a plan key, `skipped` for none — and makes no Person call; the marked lead
+ * itself is the hold. `person.ts`'s `releaseHeldCheckoutPlan` writes it
+ * later, once, at the Person's first member-path link to the user whose
+ * verified email is the Person's own. No spoke file changes. The step never
+ * throws, never changes `routeLead`'s result, and never logs the offering,
+ * the email or the key.
  *
- * SPOKE CHECKOUT MARKER (#8185 D2). The same predicate, plus "not relayed
- * for a visitor" (`SourceMeta.relayed`), is evaluated once BEFORE the lead's
- * create and stored as `Lead.spokeCheckout` — the hub's conclusion at write
+ * THE OFFERINGS TWIN (#8932 D7). The per-Organization Stripe webhook
+ * (`routes/webhooks/stripe-offerings.ts`) is the predicate's second source:
+ * `options.offeringsCheckout`, which it sets only after W3–W6 (its own
+ * signature, the hub's session record for that Organization and workspace,
+ * the recorded Price paid) and no request can set, a key
+ * `"stripe-offerings " + <cs_live_ session id>` (a space no `Idempotency-Key`
+ * header can carry), `source: "web"`, `payload.page: "checkout"`, a
+ * `payload.offering` `parseLookupKey` admits and a `payload.site` equal to
+ * the lead's workspace. Its plan key is the FULL lookup key (no `<site>_`
+ * prefix can match a workspace id), and its consent grant's `sourceRef` is
+ * the bare session id. A test-mode session's key fails the twin, so its lead
+ * is unmarked (#8932 C9).
+ *
+ * SPOKE CHECKOUT MARKER (#8185 D2). The same predicate — or its Offerings
+ * twin (#8932 D7) — plus "not relayed for a visitor" (`SourceMeta.relayed`),
+ * is evaluated once BEFORE the lead's create and stored as
+ * `Lead.spokeCheckout` — the hub's conclusion at write
  * time, which `GET /v1/member/purchases` serves as a purchase
  * (`lib/member-store.ts`). Written only in the submit create below, never by
  * an update; an unmarked create carries no `spokeCheckout` key at all and
- * relies on the column default. The plan rule above is unchanged: it still
- * runs after the write, from the same candidate.
+ * relies on the column default. The plan step above runs only for a marked
+ * lead, after the write, and holds (#8793 D1), so a request relayed for a
+ * visitor never reaches it.
+ *
+ * PURCHASE EMAIL AND INBOX MESSAGE (#8757 D14). After this request's own
+ * write of a lead marked `spokeCheckout` with a Person — so never on a
+ * replay, a test-mode or relayed checkout, or a lead with no Person — the
+ * buyer gets one outbound `member` `Interaction` on that Person
+ * (`createdBy: "system:checkout"`, subject "Your purchase", no link, payload
+ * or attachment) and, fired with `void`, one `sendPurchaseConfirmationEmail`.
+ * Both name the offering only when its stripped key is one
+ * `listPlanOfferings` lists for the workspace, else "your purchase" — never
+ * the spoke-supplied `payload.offering` (SEC-8757-G) — and both bodies are
+ * stripped of control and bidi characters. The email's "Open your account"
+ * link is `options.accountOrigin` (the route resolves it, as for the invite
+ * email) plus the hub sign-in path: a marked lead is always a registered
+ * spoke's. With no origin the email goes without the link. The email is
+ * capped per recipient: more than `PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY`
+ * marked leads of this workspace for the address (any case) in the last 24
+ * hours, this one included, skips it; and per workspace: more than
+ * `PURCHASE_EMAILS_PER_SITE_PER_HOUR` marked leads in the last hour skips
+ * it. The message is still written. Neither
+ * step ever throws or changes the lead's result, and their one log line,
+ * `{ event: "checkout-purchase", step, outcome }`, names no address or
+ * offering.
+ *
+ * CHECKOUT CONSENT GRANT (#8778). After the same first write of a marked
+ * lead with a Person, a lead whose `payload.termsAccepted` equals the current
+ * `account_terms@<version>` stamp (`currentAccountTermsStamp`) — the spoke's
+ * fulfilment sends the stamp of the terms the buyer ticked in Stripe's box,
+ * else `null` — records the buyer's checkout `ConsentGrant` through #8765's
+ * `recordCheckoutConsent`: one `account_terms` row for that Person, source
+ * `checkout`, `sourceRef` the Checkout Session id (the lead's
+ * `Idempotency-Key`), at most once per Person and session. A `null` or absent
+ * value writes nothing (`consent_absent`), as does any other value
+ * (`terms_unstamped`). A replay never reaches it, and the key is left out of
+ * the replay comparison (`comparablePayload`). Never throws and never
+ * changes the lead's result; its one log line,
+ * `{ event: "checkout-consent", outcome, siteId }` (plus `errName` on
+ * `failed`), names no address or Person.
  *
  * VISITOR LINK (#8438 D11). When the request carried a valid consent visitor
  * id (`SourceMeta.consentVisitorId`, set by the leads and flows routes from
@@ -95,12 +152,17 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 
 import type { Prisma } from "@working-theory/database";
-import { sendLeadNotification } from "@working-theory/email";
+import { sendLeadNotification, sendPurchaseConfirmationEmail } from "@working-theory/email";
 import { logger } from "@working-theory/observability";
 import {
+  accountInvitePath,
+  isConsentLeadSource,
   LEAD_SITE_MARKER_KEY,
   leadInputSchema,
-  planOfferingSchema,
+  parseLookupKey,
+  PURCHASE_EMAIL_DEFAULTS,
+  PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY,
+  stripPlainText,
 } from "@working-theory/validation";
 
 import { writeLeadFallback } from "../lib/file-fallback.js";
@@ -108,15 +170,21 @@ import { appendLeadRecord } from "../lib/lead-capture-store.js";
 import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
-import { linkConsentVisitor } from "./consent.js";
+import {
+  currentAccountTermsStamp,
+  linkConsentVisitor,
+  recordCheckoutConsent,
+  type RecordCheckoutConsentOutcome,
+} from "./consent.js";
 import { enrichLead } from "./enrichment-shim.js";
 import {
+  checkoutPlanKey,
   findOrCreatePerson,
   normalizeCapturedContact,
   normalizeTelephone,
-  setPersonPlanOffering,
 } from "./person.js";
 import type { LeadContact, PersonContact } from "./person.js";
+import { listPlanOfferings } from "./plan-offerings.js";
 import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -178,6 +246,20 @@ export type RouteLeadOptions = {
    * `payload` stays the raw answers.
    */
   contact?: LeadContact;
+  /**
+   * Where the buyer's account lives (#8757 D14): the origin the purchase
+   * email's "Open your account" link starts sign-in on, resolved by the route
+   * from the caller, never the body. Read for a marked checkout lead only.
+   */
+  accountOrigin?: string;
+  /**
+   * Set only by the per-Organization Stripe webhook after W5 and W6 (#8932
+   * D7) — a signature from the Organization's own secret, the hub's own
+   * session record for that Organization and workspace, and the recorded
+   * Price paid; never from a request. Admits the Offerings twin of the
+   * checkout plan predicate (`offeringsCheckoutCandidate`).
+   */
+  offeringsCheckout?: true;
 };
 
 export type RouteLeadResult =
@@ -252,15 +334,48 @@ async function findLeadByKey(
   })) as KeyedRow | null;
 }
 
+/**
+ * A consent-bearing lead's `payload.consent` — a contact lead's (#8730 D3) or,
+ * since #9130, a job application's — is written by the route on every request,
+ * its `acceptedAt` that request's receive time, so it is left out of the replay
+ * comparison for every `isConsentLeadSource` source; every key the client sent
+ * still counts.
+ *
+ * A checkout lead's `payload.termsAccepted` (#8778) is left out too: a spoke
+ * updated between a stored attempt and Stripe's redelivery sends the key the
+ * stored body lacks, and a conflict there would fail every retry. A replay
+ * writes no grant, so the key decides nothing on one.
+ */
+function comparablePayload(payload: unknown, source: string): unknown {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return payload;
+  }
+  const record = payload as Record<string, unknown>;
+  if (isConsentLeadSource(source)) {
+    const { consent: _serverWritten, ...rest } = record;
+    return rest;
+  }
+  if (record["page"] === "checkout") {
+    const { termsAccepted: _addedByUpdate, ...rest } = record;
+    return rest;
+  }
+  return payload;
+}
+
 /**
  * A stored row is a replay only when it carries this request's exact `email`
  * and `source` and a deep-equal `payload` (key order ignored, SEC-7869-3);
- * any other row is a conflict (#7869 D4).
+ * any other row is a conflict (#7869 D4). A consent-bearing lead's
+ * server-written `payload.consent` is not compared (#8730, #9130), nor a
+ * checkout lead's `payload.termsAccepted` (#8778).
  */
 function classifyKeyedRow(row: KeyedRow, input: SubmitInput): KeyedOutcome {
   return row.email === input.email &&
     row.source === input.source &&
-    isDeepStrictEqual(row.payload, input.payload)
+    isDeepStrictEqual(
+      comparablePayload(row.payload, row.source),
+      comparablePayload(input.payload, input.source),
+    )
     ? { kind: "replay", id: row.id }
     : { kind: "conflict" };
 }
@@ -346,6 +461,9 @@ async function resolveLeadPersonId(input: SubmitInput, contact?: LeadContact): P
   });
 }
 
+/** A marked checkout lead's offering and site; `sessionId` is the Offerings twin's bare session id. */
+type CheckoutCandidate = { offering: string; site: string; sessionId?: string };
+
 /** A LIVE-mode Checkout Session id (#7877 D10, SEC-7877-C). */
 const LIVE_CHECKOUT_SESSION_KEY = /^cs_live_[A-Za-z0-9]{1,250}$/;
 const SITE_SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -358,7 +476,7 @@ function checkoutPlanCandidate(
   input: SubmitInput,
   idempotencyKey: string | undefined,
   viaSpoke: boolean,
-): { offering: string; site: string } | null {
+): CheckoutCandidate | null {
   if (viaSpoke !== true) return null;
   if (idempotencyKey === undefined || !LIVE_CHECKOUT_SESSION_KEY.test(idempotencyKey)) {
     return null;
@@ -381,35 +499,283 @@ function checkoutPlanCandidate(
   return { offering, site };
 }
 
+/** The Offerings webhook's key: a space no `Idempotency-Key` header can carry, then a LIVE session id. */
+const OFFERINGS_CHECKOUT_KEY = /^stripe-offerings (cs_live_[A-Za-z0-9]{1,250})$/;
+
 /**
- * Set the Person's plan from a qualifying checkout lead (#7877 D10). Never
- * throws and never changes the lead's result; logs the outcome kind and the
- * site only.
+ * The Offerings twin of `checkoutPlanCandidate` (#8932 D7): a lead the
+ * per-Organization Stripe webhook wrote after W5 and W6, for a LIVE session
+ * only (C9, SEC-7877-C) — a test-mode session's lead is written unmarked.
+ * Reads no amount: W6 already proved the session paid. `checkoutPlanCandidate`
+ * is not edited, so a spoke lead is marked exactly as before.
  */
-async function applyCheckoutPlan(
+function offeringsCheckoutCandidate(
   input: SubmitInput,
-  personId: string,
-  candidate: { offering: string; site: string },
-): Promise<void> {
+  idempotencyKey: string | undefined,
+  offeringsCheckout: boolean,
+): CheckoutCandidate | null {
+  if (offeringsCheckout !== true || idempotencyKey === undefined) return null;
+  const sessionId = OFFERINGS_CHECKOUT_KEY.exec(idempotencyKey)?.[1];
+  if (sessionId === undefined) return null;
+  const { payload } = input;
+  if (input.source !== "web" || payload["page"] !== "checkout") return null;
+  const offering = payload["offering"];
+  if (typeof offering !== "string" || parseLookupKey(offering) === null) return null;
+  const site = payload[LEAD_SITE_MARKER_KEY];
+  if (typeof site !== "string" || site !== input.siteId) return null;
+  return { offering, site, sessionId };
+}
+
+/** The candidate's offering minus a leading `<site>_` (#7877 D10). */
+function stripSitePrefix(candidate: CheckoutCandidate): string {
   const prefix = `${candidate.site}_`;
-  const offering = candidate.offering.startsWith(prefix)
+  return candidate.offering.startsWith(prefix)
     ? candidate.offering.slice(prefix.length)
     : candidate.offering;
-  let outcome: "set" | "skipped" | "failed";
-  // The operator's PUT accepts the same keys (`planOfferingSchema`).
-  if (!planOfferingSchema.safeParse(offering).success) {
-    outcome = "skipped";
-  } else {
-    try {
-      const result = await setPersonPlanOffering(input.siteId, personId, offering);
-      outcome = result === "set" ? "set" : "failed";
-    } catch {
-      outcome = "failed";
+}
+
+/**
+ * Hold the plan of a marked checkout lead (#7877 D10, #8793 D1): no Person
+ * call — the marked lead itself is the hold, released only at the Person's
+ * verified first link (`person.ts`'s `releaseHeldCheckoutPlan`). Logs
+ * `held` for an offering that is a plan key, else `skipped`, and the site
+ * only.
+ */
+function applyCheckoutPlan(
+  input: SubmitInput,
+  candidate: CheckoutCandidate,
+): void {
+  const outcome = checkoutPlanKey(candidate.offering, candidate.site) === null ? "skipped" : "held";
+  logger.info({ event: "checkout-plan", outcome, siteId: input.siteId }, "checkout plan");
+}
+
+// ─── Purchase email and Inbox message (#8757 D14) ────────────────────────────
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+/**
+ * A workspace's purchase emails per hour, whatever the address (SEC review of
+ * #8770, M1): a marked lead's inputs are all the spoke's own, so the
+ * per-recipient cap alone would let a spoke key mail any number of distinct
+ * addresses. The invite email's per-site cap
+ * (`INVITE_EMAILS_PER_SITE_PER_HOUR`) has the same value.
+ */
+const PURCHASE_EMAILS_PER_SITE_PER_HOUR = 50;
+const GENERIC_PURCHASE_BODY = "Thanks for your purchase.";
+/** How long the lead write waits on the offering's name before it says "your purchase". */
+const OFFERING_NAME_BUDGET_MS = 1500;
+/**
+ * Stripe's special-case currencies, whose minor units differ from the ISO
+ * decimals `Intl` formats with: the amount is left out rather than misstated.
+ */
+const AMOUNT_UNSTATED_CURRENCIES = new Set(["HUF", "ISK", "TWD", "UGX"]);
+
+/**
+ * The purchase email's sender: every completion email's rule
+ * (`AILK_DELIVERABLE_EMAIL_FROM`, else `AILK_LEAD_NOTIFICATION_FROM`; `||`, so
+ * "" names none), the same as `magnet-completion.ts`'s `inviteSenderAddress`,
+ * kept here so the lead path does not load that module's graph.
+ */
+function purchaseSenderAddress(): string | undefined {
+  return (
+    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
+    process.env.AILK_LEAD_NOTIFICATION_FROM ||
+    undefined
+  );
+}
+
+type PurchaseStep = "message" | "email";
+
+function logPurchase(siteId: string, step: PurchaseStep, outcome: string): void {
+  const line = { event: "checkout-purchase", step, outcome, siteId };
+  if (outcome === "failed") logger.error(line, "checkout purchase step failed");
+  else logger.info(line, "checkout purchase step");
+}
+
+/**
+ * The offering's listed name, or `null` when its stripped key is not listed,
+ * the read fails, or it outlasts `OFFERING_NAME_BUDGET_MS`.
+ */
+async function listedOfferingName(siteId: string, offering: string): Promise<string | null> {
+  let timer: NodeJS.Timeout | undefined;
+  const budget = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), OFFERING_NAME_BUDGET_MS);
+  });
+  try {
+    const listed = await Promise.race([listPlanOfferings(siteId), budget]);
+    if (!Array.isArray(listed)) return null;
+    const name = listed.find((item) => item.key === offering)?.name;
+    const clean = name === undefined ? "" : stripPlainText(name).trim();
+    return clean === "" ? null : clean;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** `amountTotal` (minor units) in `currency`, formatted, or `null` when either is unusable. */
+function formattedAmount(amountTotal: unknown, currency: unknown): string | null {
+  if (typeof amountTotal !== "number" || !Number.isInteger(amountTotal) || amountTotal <= 0) {
+    return null;
+  }
+  if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) return null;
+  const code = currency.toUpperCase();
+  if (AMOUNT_UNSTATED_CURRENCIES.has(code)) return null;
+  try {
+    const format = new Intl.NumberFormat("en", { style: "currency", currency: code });
+    const digits = format.resolvedOptions().maximumFractionDigits ?? 2;
+    return format.format(amountTotal / 10 ** digits);
+  } catch {
+    return null;
+  }
+}
+
+/** The one plain-text body the email and the message share. */
+function purchaseBody(name: string | null, amount: string | null): string {
+  const sentence =
+    name === null ? GENERIC_PURCHASE_BODY : PURCHASE_EMAIL_DEFAULTS.body.replaceAll("{offering}", name);
+  return stripPlainText(amount === null ? sentence : `${sentence} Total: ${amount}.`);
+}
+
+/** The purchase email, capped per recipient (D14). Never throws; fired with `void`. */
+async function sendPurchaseEmail(
+  input: SubmitInput,
+  body: string,
+  accountOrigin: string | undefined,
+): Promise<void> {
+  let outcome: string;
+  try {
+    const recent = await prisma.lead.count({
+      where: {
+        workspaceId: input.siteId,
+        spokeCheckout: true,
+        email: { equals: input.email, mode: "insensitive" },
+        createdAt: { gte: new Date(Date.now() - DAY_MS) },
+      },
+    });
+    const siteHour = await prisma.lead.count({
+      where: {
+        workspaceId: input.siteId,
+        spokeCheckout: true,
+        createdAt: { gte: new Date(Date.now() - HOUR_MS) },
+      },
+    });
+    const fromAddress = purchaseSenderAddress();
+    if (recent > PURCHASE_EMAILS_PER_RECIPIENT_PER_DAY) {
+      outcome = "capped_recipient";
+    } else if (siteHour > PURCHASE_EMAILS_PER_SITE_PER_HOUR) {
+      outcome = "capped_site";
+    } else if (!fromAddress) {
+      outcome = "sender_unconfigured";
+    } else {
+      let accountLink: string | undefined;
+      if (accountOrigin !== undefined) {
+        try {
+          accountLink = accountOrigin + accountInvitePath("hub", input.email);
+        } catch {
+          // An address the sign-in hint refuses: the email goes without the link.
+        }
+      }
+      const result = await sendPurchaseConfirmationEmail({
+        to: input.email,
+        fromAddress,
+        subject: PURCHASE_EMAIL_DEFAULTS.subject,
+        body,
+        cta: PURCHASE_EMAIL_DEFAULTS.cta,
+        ...(accountLink !== undefined && { accountLink }),
+      });
+      outcome = result.ok ? "sent" : "failed";
+    }
+  } catch {
+    outcome = "failed";
+  }
+  logPurchase(input.siteId, "email", outcome);
+}
+
+/**
+ * The buyer's Inbox message and purchase email for a marked checkout lead
+ * just written (D14). Never throws and never changes the lead's result.
+ */
+async function recordPurchase(
+  input: SubmitInput,
+  personId: string,
+  candidate: CheckoutCandidate,
+  accountOrigin: string | undefined,
+): Promise<void> {
+  // One guard around the whole step: it runs inside `routeLead`'s persist
+  // `try`, where a throw after the row is written would be read as a failed
+  // write and the lead captured a second time.
+  let body: string;
+  try {
+    const name = await listedOfferingName(input.siteId, stripSitePrefix(candidate));
+    body = purchaseBody(name, formattedAmount(input.payload["amountTotal"], input.payload["currency"]));
+  } catch {
+    logPurchase(input.siteId, "message", "failed");
+    return;
+  }
+  try {
+    await prisma.interaction.create({
+      data: {
+        workspaceId: input.siteId,
+        personId,
+        channel: "member",
+        direction: "outbound",
+        subject: PURCHASE_EMAIL_DEFAULTS.subject,
+        body,
+        createdBy: "system:checkout",
+      },
+    });
+    logPurchase(input.siteId, "message", "written");
+  } catch {
+    logPurchase(input.siteId, "message", "failed");
+  }
+  void sendPurchaseEmail(input, body, accountOrigin);
+}
+
+/**
+ * The buyer's checkout consent grant for a marked checkout lead just written
+ * (#8778). Never throws and never changes the lead's result.
+ */
+async function recordSpokeCheckoutConsent(
+  input: SubmitInput,
+  personId: string,
+  sessionId: string,
+): Promise<void> {
+  const accepted = input.payload["termsAccepted"];
+  let outcome:
+    | RecordCheckoutConsentOutcome
+    | "consent_absent"
+    | "terms_unstamped"
+    | "failed";
+  let errName: string | undefined;
+  try {
+    const expected = currentAccountTermsStamp();
+    if (accepted === undefined || accepted === null) {
+      outcome = "consent_absent";
+    } else if (expected === null || accepted !== expected.stamp) {
+      outcome = "terms_unstamped";
+    } else {
+      outcome = await recordCheckoutConsent({
+        workspaceId: input.siteId,
+        personId,
+        sessionId,
+        policyVersion: expected.policyVersion,
+      });
     }
+  } catch (err) {
+    // The error's class only (a Prisma error's message can carry values).
+    outcome = "failed";
+    errName = err instanceof Error ? err.name : "UnknownError";
   }
-  const line = { event: "checkout-plan", outcome, siteId: input.siteId };
-  if (outcome === "failed") logger.error(line, "checkout plan failed");
-  else logger.info(line, "checkout plan");
+  const line = {
+    event: "checkout-consent",
+    outcome,
+    siteId: input.siteId,
+    ...(errName !== undefined && { errName }),
+  };
+  if (outcome === "failed") logger.error(line, "checkout terms grant failed");
+  else logger.info(line, "checkout terms grant");
 }
 
 async function persistToDb(
@@ -418,13 +784,18 @@ async function persistToDb(
   viaSpoke = false,
   relayed = false,
   contact?: LeadContact,
+  accountOrigin?: string,
+  offeringsCheckout = false,
 ): Promise<PersistResult> {
   if (input.kind === "submit") {
     const personId = await resolveLeadPersonId(input, contact);
     // #8185 D2 — the plan rule's own predicate (pure: input, key, flag),
     // evaluated before the create so its result can be stored. A relayed
-    // request is never a spoke's server call (D3).
-    const candidate = checkoutPlanCandidate(input, idempotencyKey, viaSpoke);
+    // request is never a spoke's server call (D3). #8932 D7 — or its
+    // Offerings twin, set only by the per-Organization Stripe webhook.
+    const candidate =
+      checkoutPlanCandidate(input, idempotencyKey, viaSpoke) ??
+      offeringsCheckoutCandidate(input, idempotencyKey, offeringsCheckout);
     const spokeCheckout = candidate !== null && relayed !== true;
     let row: DbRow;
     try {
@@ -470,9 +841,20 @@ async function persistToDb(
       if (!winner) throw err;
       return { ok: "keyed", outcome: classifyKeyedRow(winner, input) };
     }
-    // #7877 D10 — only after THIS request's own write, so a replay sets nothing.
+    // #7877 D10 — only after THIS request's own write, so a replay holds nothing.
     if (candidate !== null && personId !== null) {
-      await applyCheckoutPlan(input, personId, candidate);
+      // #8757 D14 — the marked lead only: live, unrelayed, this write.
+      if (spokeCheckout) {
+        // #8793 D1 — the plan is held, never written here.
+        applyCheckoutPlan(input, candidate);
+        await recordPurchase(input, personId, candidate, accountOrigin);
+        // #8778 — a marked lead's key is its live Checkout Session id;
+        // #8932 D7 — the Offerings twin's key is prefixed, so its bare id.
+        const sessionId = candidate.sessionId ?? idempotencyKey;
+        if (sessionId !== undefined) {
+          await recordSpokeCheckoutConsent(input, personId, sessionId);
+        }
+      }
     }
     return { ok: true, id: row.id, source: "db", skipEmail: false, personId };
   }
@@ -836,6 +1218,8 @@ export async function routeLead(
       sourceMeta.viaSpoke === true,
       sourceMeta.relayed === true,
       input.kind === "submit" ? options.contact : undefined,
+      input.kind === "submit" ? options.accountOrigin : undefined,
+      input.kind === "submit" && options.offeringsCheckout === true,
     );
     // #7869 D5 — a lost race answers like the lookup above: no capture
     // record, no notification.