create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/__tests__/plan-offerings.test.ts

@@ -0,0 +1,444 @@
+/**
+ * @file plan-offerings.test.ts
+ *
+ * The plan offerings re-sourced from the Offerings shown set (#8934, spec
+ * docs/specs/8934-re-source-the-plan-offerings-spec.md D1–D6; AC-1, AC-3,
+ * AC-4, AC-5): a connected, claimed workspace lists one item per sellable
+ * Price in its shown set, keyed by the Price's full lookup key; an unconnected
+ * or unclaimed workspace keeps the page list; a licence or snapshot that
+ * cannot be read answers `{ failed }`; and the three consumers accept a
+ * listed key with no change to their own code.
+ *
+ * Runs over `createInMemoryPrisma()` and #8876's `seedOfferings`. External
+ * dependency boundaries mocked:
+ *   - apps/api/src/lib/prisma — the in-memory, where-clause-honouring double.
+ *     Its `lead.count` is arranged per test: the purchase email's cap reads
+ *     with `mode: "insensitive"`, a filter the double does not model.
+ *   - @working-theory/license — `checkLicense` per case; a keyless storage
+ *     file (`absent`).
+ *   - @working-theory/stripe-client — touching any export throws.
+ *   - @working-theory/email — the operator notification and purchase email.
+ *   - public-site-resolver's `workspaceContentAdapter` — a fixture adapter
+ *     stands in for the workspace's content store.
+ */
+import { inspect } from "node:util";
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); the in-memory double is the repo-standard where-honouring test double for it.
+jest.mock("../../lib/prisma.js", () =>
+  jest
+    .requireActual<typeof import("../../__tests__/factories/in-memory-prisma")>(
+      "../../__tests__/factories/in-memory-prisma",
+    )
+    .createInMemoryPrisma(),
+);
+
+const mockCheckLicense = jest.fn();
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+  readStoredJwtState: () => Promise.resolve({ state: "absent" }),
+}));
+
+jest.mock(
+  "@working-theory/stripe-client",
+  () =>
+    new Proxy(
+      {},
+      {
+        get: (_target, key) => {
+          if (key === "__esModule") return true;
+          throw new Error(`@working-theory/stripe-client.${String(key)} was touched`);
+        },
+      },
+    ),
+);
+
+const mockSendLeadNotification = jest.fn();
+const mockSendPurchaseConfirmationEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: (...args: unknown[]) => mockSendLeadNotification(...args),
+  sendPurchaseConfirmationEmail: (...args: unknown[]) =>
+    mockSendPurchaseConfirmationEmail(...args),
+}));
+
+const mockWorkspaceContentAdapter = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the content adapter seam: a fixture adapter stands in for the workspace's content store
+jest.mock("../public-site-resolver.js", () => ({
+  ...jest.requireActual("../public-site-resolver.js"),
+  workspaceContentAdapter: (...args: unknown[]) => mockWorkspaceContentAdapter(...args),
+}));
+
+import { logger } from "@working-theory/observability";
+import {
+  parseLookupKey,
+  planOfferingItemSchema,
+  planOfferingSchema,
+  planOfferingsResponseSchema,
+} from "@working-theory/validation";
+
+import { prisma } from "../../lib/prisma.js";
+import { routeLead } from "../lead-routing";
+import { magnetCompletionFor } from "../magnet-completion";
+import {
+  FIXTURE_ORG,
+  FIXTURE_ORG_2_WS,
+  FIXTURE_WS,
+  FIXTURE_WS_2,
+  OFFERINGS_FIXTURE_CATALOG,
+  seedOfferings,
+} from "../offerings/__tests__/fixtures.js";
+import { normalizeCatalog, type CatalogPrice, type CatalogProduct } from "../offerings/index.js";
+import { resolveMemberPersonId } from "../person";
+import { listPlanOfferings } from "../plan-offerings";
+
+type Row = Record<string, unknown>;
+// The in-memory double's own surface (`__db`, `__calls`) and its recorded
+// delegates are not on the PrismaClient type the import carries, so it is
+// named here once.
+// eslint-disable-next-line no-restricted-syntax -- justified above
+const store = prisma as unknown as {
+  __db: Record<string, Row[]>;
+  __calls: Array<{ model: string; op: string }>;
+  lead: Record<string, jest.Mock>;
+  workspaceOfferings: Record<string, jest.Mock>;
+};
+
+const CLAIMED = { tier: "pro", plan: null, features: ["commerce"], expiresAt: null, revoked: false };
+const FREE = { tier: "free", plan: null, features: [], expiresAt: null, revoked: false };
+const HOUR_MS = 60 * 60 * 1000;
+
+/** D1's table for the seed. */
+const SHOWN_SET_ITEMS = [
+  { key: "basic_once", name: "Basic (One-time)", type: "plan" },
+  { key: "growth_monthly", name: "Growth (Monthly)", type: "plan" },
+  { key: "growth_yearly", name: "Growth (Annual)", type: "plan" },
+  { key: "seo-audit_monthly", name: "SEO audit (Monthly)", type: "addon" },
+];
+
+// The route suite's fixture pages and their keying (#8514 D9).
+const page = (slug: string, title: string) => ({ slug, title });
+const SERVICES = [
+  page("services/retainer", "Monthly retainer"),
+  page("services/Bad Key!", "Not a key"),
+  page("audit", "Brand audit"),
+];
+const PRODUCTS = [page("products/starter-kit", "Starter kit"), page("retainer", "Duplicate retainer")];
+const PAGE_ITEMS = [
+  { key: "retainer", name: "Monthly retainer", type: "service" },
+  { key: "audit", name: "Brand audit", type: "service" },
+  { key: "starter-kit", name: "Starter kit", type: "product" },
+];
+const fixtureAdapter = () => ({
+  listPages: jest.fn(async (type: string) =>
+    type === "Service" ? SERVICES : type === "Product" ? PRODUCTS : [],
+  ),
+});
+
+const OFFERINGS_MODELS = ["stripeConnection", "organizationOfferings", "workspaceOfferings"];
+const offeringsReads = () => store.__calls.filter((c) => OFFERINGS_MODELS.includes(c.model));
+
+const enabledRow = () =>
+  store.__db["organizationOfferings"]!.find((r) => r["organizationId"] === FIXTURE_ORG)!;
+const offeringsRow = () =>
+  store.__db["workspaceOfferings"]!.find((r) => r["workspaceId"] === FIXTURE_WS)!;
+const interactions = () => (store.__db["interaction"] ??= []);
+const people = () => (store.__db["person"] ??= []);
+
+// ─── Logs: no line carries Stripe text (AC-5) ───────────────────────────────
+
+const EMOJI_NAME = "\u{1F600}".repeat(200);
+const FORBIDDEN_LOG_TEXT = [
+  ...OFFERINGS_FIXTURE_CATALOG.products.flatMap((p) => [
+    p.name,
+    ...(p.description ? [p.description] : []),
+    ...(p.marketing_features ?? []).map((f) => f.name),
+  ]),
+  EMOJI_NAME.slice(0, 20),
+  "prod_",
+  "price_",
+];
+const LOGGER_METHODS = ["error", "warn", "info", "debug"] as const;
+const CONSOLE_METHODS = ["log", "info", "warn", "error", "debug"] as const;
+let spies: jest.SpyInstance[] = [];
+
+function leakedLines(): string[] {
+  return spies
+    .flatMap((spy) => spy.mock.calls.map((args) => inspect(args, { depth: 8 })))
+    .filter((line) => FORBIDDEN_LOG_TEXT.some((text) => line.includes(text)));
+}
+
+// ─── The lead route (AC-3) ───────────────────────────────────────────────────
+
+const BUYER = "buyer@x.io";
+const U = "user_00000000-0000-7000-8000-000000008934";
+let keySeq = 0;
+const sourceMeta = { ip: "127.0.0.1", userAgent: "jest", receivedAt: new Date().toISOString(), viaSpoke: true };
+
+/** A marked spoke checkout lead (#8793's shape) for `offering`, from slug site `wendi`. */
+async function checkoutLead(offering: string): Promise<void> {
+  keySeq += 1;
+  await routeLead(
+    {
+      kind: "submit",
+      siteId: FIXTURE_WS,
+      source: "web",
+      email: BUYER,
+      payload: { site: "wendi", page: "checkout", offering, amountTotal: 900, currency: "usd" },
+    },
+    sourceMeta,
+    { idempotencyKey: `cs_live_h8934Plan${keySeq}` }, // gitleaks:allow -- a synthetic Checkout Session id shape, not a credential
+  );
+}
+
+/** The newest purchase message's body. */
+const lastPurchaseBody = () => String(interactions().at(-1)?.["body"]);
+const GENERIC = /^Thanks for your purchase\./;
+
+const ENV_KEYS = [
+  "DATABASE_URL",
+  "NODE_ENV",
+  "AILK_LICENSE_KEY",
+  "AILK_LEAD_NOTIFICATION_TO",
+  "AILK_LEAD_NOTIFICATION_FROM",
+  "AILK_DELIVERABLE_EMAIL_FROM",
+] as const;
+let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+
+beforeEach(async () => {
+  for (const key of Object.keys(store.__db)) delete store.__db[key];
+  saved = {};
+  for (const k of ENV_KEYS) saved[k] = process.env[k];
+  process.env.DATABASE_URL = "postgres://stub";
+  delete process.env.NODE_ENV;
+  delete process.env.AILK_LICENSE_KEY;
+  process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+  process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+  process.env.AILK_DELIVERABLE_EMAIL_FROM = "orders@example.com";
+  mockCheckLicense.mockReset().mockResolvedValue(CLAIMED);
+  mockWorkspaceContentAdapter.mockReset().mockImplementation(async () => fixtureAdapter());
+  mockSendLeadNotification.mockReset().mockResolvedValue({ ok: true, messageId: "m" });
+  mockSendPurchaseConfirmationEmail.mockReset().mockResolvedValue({ ok: true, messageId: "m2" });
+  store.lead["count"]!.mockReset().mockResolvedValue(1);
+  await seedOfferings(prisma);
+  store.__calls.length = 0;
+  spies = [
+    ...LOGGER_METHODS.map((m) => jest.spyOn(logger, m).mockImplementation(() => undefined as never)),
+    ...CONSOLE_METHODS.map((m) => jest.spyOn(console, m).mockImplementation(() => undefined)),
+  ];
+});
+
+afterEach(() => {
+  const leaked = leakedLines();
+  for (const spy of spies) spy.mockRestore();
+  for (const k of ENV_KEYS) {
+    if (saved[k] === undefined) delete process.env[k];
+    else process.env[k] = saved[k];
+  }
+  // AC-5: across every case, no log or console line carries a product name,
+  // description, feature string, or a `prod_` or `price_` id.
+  expect(leaked).toEqual([]);
+});
+
+describe("a connected workspace lists its shown set's lookup keys, and only those (AC-1)", () => {
+  it("one item per sellable Price, keyed by its full lookup key, with no page and no Stripe call", async () => {
+    const offerings = await listPlanOfferings(FIXTURE_WS);
+    expect(offerings).toEqual(SHOWN_SET_ITEMS);
+    if (!Array.isArray(offerings)) throw new Error("expected a list");
+    for (const { key } of offerings) {
+      expect(parseLookupKey(key)).not.toBeNull();
+      expect(planOfferingSchema.safeParse(key).success).toBe(true);
+    }
+    expect(() => planOfferingsResponseSchema.parse({ offerings })).not.toThrow();
+    expect(mockWorkspaceContentAdapter).not.toHaveBeenCalled();
+    // The bidi add-on is in the catalog but neither enabled nor shown.
+    expect(offerings.map((o) => o.key)).not.toContain("audit-plus_monthly");
+  });
+
+  it("a product switched off in the Organization's enabled set is absent on the next call", async () => {
+    const { snapshot, snapshotAt } = offeringsRow();
+    enabledRow()["enabledProductIds"] = (enabledRow()["enabledProductIds"] as string[]).filter(
+      (id) => id !== "prod_fixture_seo_audit",
+    );
+    expect(await listPlanOfferings(FIXTURE_WS)).toEqual(
+      SHOWN_SET_ITEMS.filter((item) => item.key !== "seo-audit_monthly"),
+    );
+    expect(offeringsRow()["snapshot"]).toBe(snapshot);
+    expect(offeringsRow()["snapshotAt"]).toBe(snapshotAt);
+  });
+
+  it("a product switched off in the workspace's shown set is absent on the next call", async () => {
+    const { snapshot, snapshotAt } = offeringsRow();
+    offeringsRow()["shownProductIds"] = (offeringsRow()["shownProductIds"] as string[]).filter(
+      (id) => id !== "prod_fixture_growth",
+    );
+    expect(await listPlanOfferings(FIXTURE_WS)).toEqual(
+      SHOWN_SET_ITEMS.filter((item) => !item.key.startsWith("growth_")),
+    );
+    expect(offeringsRow()["snapshot"]).toBe(snapshot);
+    expect(offeringsRow()["snapshotAt"]).toBe(snapshotAt);
+  });
+
+  it("an empty shown set lists none: a fact, not a failure", async () => {
+    offeringsRow()["shownProductIds"] = [];
+    expect(await listPlanOfferings(FIXTURE_WS)).toEqual([]);
+  });
+});
+
+describe("the consumers accept a listed key with no change to their own code (AC-3)", () => {
+  it("(a) the purchase message names a listed lookup key, and only a listed one", async () => {
+    await checkoutLead("growth_monthly");
+    expect(interactions()).toHaveLength(1);
+    expect(lastPurchaseBody()).toContain("Growth (Monthly)");
+
+    await checkoutLead("growth_quarterly");
+    expect(lastPurchaseBody()).toMatch(GENERIC);
+    // A page the adapter lists is not a connected workspace's offering.
+    await checkoutLead("retainer");
+    expect(lastPurchaseBody()).toMatch(GENERIC);
+    expect(interactions()).toHaveLength(3);
+  });
+
+  it("(b) the held plan released at the verified first link is a key the list names", async () => {
+    await checkoutLead("growth_monthly");
+    (store.__db["user"] ??= []).push({ id: U, email: BUYER, emailVerified: true });
+    const personId = await resolveMemberPersonId(FIXTURE_WS, U, BUYER);
+    const buyer = people().find((p) => p["id"] === personId)!;
+    expect(buyer["planOffering"]).toBe("growth_monthly");
+    const offerings = await listPlanOfferings(FIXTURE_WS);
+    if (!Array.isArray(offerings)) throw new Error("expected a list");
+    expect(offerings.find((o) => o.key === buyer["planOffering"])?.name).toBe("Growth (Monthly)");
+  });
+
+  it("(c) a checkout magnet completes on an unconnected workspace's page key, and degrades to lead on a connected one", async () => {
+    const magnet = (workspaceId: string, checkoutOffering: string): Row => ({
+      id: `flow_${workspaceId.slice(-4)}`,
+      workspaceId,
+      siteId: workspaceId,
+      slug: "buy",
+      status: "live",
+      title: "Buy",
+      config: {},
+      completion: "checkout",
+      checkoutOffering,
+    });
+    store.__db["flowDefinition"] = [magnet(FIXTURE_ORG_2_WS, "retainer"), magnet(FIXTURE_WS, "growth")];
+    const noTarget = () => Promise.resolve(null);
+    expect(await magnetCompletionFor(FIXTURE_ORG_2_WS, "buy", noTarget)).toMatchObject({
+      next: { completion: "checkout", checkoutOffering: "retainer" },
+    });
+    expect(await magnetCompletionFor(FIXTURE_WS, "buy", noTarget)).toBeNull();
+  });
+
+  describe("(d) a licence or snapshot that cannot be read is { failed }, never a pass", () => {
+    const failures: Array<[string, () => Promise<void>, string]> = [
+      [
+        "an undetermined licence",
+        async () => {
+          mockCheckLicense.mockReset().mockRejectedValue(new Error("licence read failed"));
+        },
+        "LicenseUndetermined",
+      ],
+      [
+        "a snapshot 25 hours old",
+        async () => {
+          for (const key of Object.keys(store.__db)) delete store.__db[key];
+          await seedOfferings(prisma, { now: new Date(Date.now() - 25 * HOUR_MS) });
+        },
+        "OfferingsSnapshotExpired",
+      ],
+      [
+        "an unreadable connection",
+        async () => {
+          store.__db["stripeConnection"]![0]!["mode"] = "prod";
+        },
+        "OfferingsSnapshotEmpty",
+      ],
+      [
+        "a selection read that rejects",
+        async () => {
+          store.workspaceOfferings["findUnique"]!.mockRejectedValueOnce(new Error("db down"));
+        },
+        "Error",
+      ],
+    ];
+
+    it.each(failures)("%s", async (_label, arm, failed) => {
+      await arm();
+      expect(await listPlanOfferings(FIXTURE_WS)).toEqual({ failed });
+      await arm();
+      await checkoutLead("growth_monthly");
+      expect(lastPurchaseBody()).toMatch(GENERIC);
+    });
+
+    it("an undetermined licence reads no Offerings or workspace row", async () => {
+      mockCheckLicense.mockReset().mockRejectedValue(new Error("licence read failed"));
+      store.__calls.length = 0;
+      expect(await listPlanOfferings(FIXTURE_WS)).toEqual({ failed: "LicenseUndetermined" });
+      expect(store.__calls.filter((c) => [...OFFERINGS_MODELS, "workspace"].includes(c.model))).toEqual([]);
+    });
+  });
+});
+
+describe("an unconnected or unclaimed workspace keeps the page list (AC-4)", () => {
+  it.each([
+    ["a selection with no connection", FIXTURE_ORG_2_WS],
+    ["a connection with no selection", FIXTURE_WS_2],
+    ["an unknown workspace", "wksp_01920000-8934-7000-8000-0000000000ff"],
+  ])("%s answers the page list", async (_label, workspaceId) => {
+    expect(await listPlanOfferings(workspaceId)).toEqual(PAGE_ITEMS);
+    expect(mockWorkspaceContentAdapter).toHaveBeenCalledWith(workspaceId);
+  });
+
+  it("an unclaimed, connected workspace answers the page list and reads no Offerings row", async () => {
+    mockCheckLicense.mockReset().mockResolvedValue(FREE);
+    expect(await listPlanOfferings(FIXTURE_WS)).toEqual(PAGE_ITEMS);
+    expect(mockWorkspaceContentAdapter).toHaveBeenCalledWith(FIXTURE_WS);
+    expect(offeringsReads()).toEqual([]);
+  });
+});
+
+describe("names and the item schema (AC-5)", () => {
+  it("a 200-code-point emoji name keeps its billing word, fits 200 units and splits no surrogate", async () => {
+    const product = {
+      id: "prod_fixture_emoji",
+      active: true,
+      name: EMOJI_NAME,
+      description: null,
+      marketing_features: [],
+      unit_label: null,
+      metadata: { ailk_group: "plan" },
+    } as CatalogProduct;
+    const price = {
+      id: "price_fixture_emoji_monthly",
+      active: true,
+      product: "prod_fixture_emoji",
+      lookup_key: "emoji_monthly",
+      type: "recurring",
+      recurring: { interval: "month", interval_count: 1, usage_type: "licensed" },
+      billing_scheme: "per_unit",
+      unit_amount: 100,
+      currency: "usd",
+    } as CatalogPrice;
+    const [emoji] = normalizeCatalog({ products: [product], prices: [price] }).offerings;
+    expect(emoji?.name).toBe(EMOJI_NAME);
+    enabledRow()["enabledProductIds"] = ["prod_fixture_emoji"];
+    offeringsRow()["shownProductIds"] = ["prod_fixture_emoji"];
+    offeringsRow()["snapshot"] = { v: 1, offerings: [emoji] };
+
+    const offerings = await listPlanOfferings(FIXTURE_WS);
+    if (!Array.isArray(offerings)) throw new Error(`expected a list, got ${offerings.failed}`);
+    const [item] = offerings;
+    expect(item?.key).toBe("emoji_monthly");
+    expect(item?.name.endsWith(" (Monthly)")).toBe(true);
+    expect(item!.name.length).toBeLessThanOrEqual(200);
+    expect(item!.name).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/);
+    expect(planOfferingItemSchema.safeParse(item).success).toBe(true);
+  });
+
+  it("the item schema takes the Offerings groups beside the page types", () => {
+    const item = (type: string) => ({ key: "growth_monthly", name: "Growth (Monthly)", type });
+    for (const type of ["service", "product", "plan", "addon"]) {
+      expect(planOfferingItemSchema.safeParse(item(type)).success).toBe(true);
+    }
+    expect(planOfferingItemSchema.safeParse(item("offering")).success).toBe(false);
+  });
+});

package/templates/apps/api/src/services/checkout-buyer.ts

@@ -1,7 +1,10 @@
 /**
  * @file checkout-buyer.ts
  * @description Resolves a signed-in user into the Checkout buyer
- * `POST /v1/checkout/sessions` pins and stamps (#6866 D3).
+ * `POST /v1/checkout/sessions` pins and stamps (#6866 D3), and — the other
+ * way round — a completed Checkout Session into its buyer's Person, the
+ * subject of the terms grant the hub webhook records (#8765 D14,
+ * `checkoutBuyerPerson`).
  *
  * A buyer is a user whose email is VERIFIED — the customer created for them
  * carries the account email, and it must never carry an unproven one — and
@@ -11,13 +14,18 @@
  * never re-points a non-null `billingCustomerId` (#6113), so a new stamped
  * customer could only be an orphan.
  *
- * Base tree (N4): imports only `verified-email.ts` and `lib/prisma.ts`, never
- * the commerce overlay's `services/subscription.ts`. The billing read selects
- * no email, so `tools/lint-email-authz.ts` has nothing to flag.
+ * Base tree (N4): imports only `verified-email.ts`, `person.ts`,
+ * `lib/site.ts`, `lib/proposal-paid-store.ts` and `lib/prisma.ts` — all base
+ * tree — never the commerce
+ * overlay's `services/subscription.ts`. The billing read selects no email, so
+ * `tools/lint-email-authz.ts` has nothing to flag.
  */
 
 import { prisma } from "../lib/prisma.js";
+import { proposalPersonId } from "../lib/proposal-paid-store.js";
+import { resolveSiteWorkspaceId } from "../lib/site.js";
 
+import { findOrCreatePerson } from "./person.js";
 import { findVerifiedEmail } from "./verified-email.js";
 
 export type CheckoutBuyer = {
@@ -70,3 +78,91 @@ export async function resolveCheckoutBuyer(
     },
   };
 }
+
+// ─── The buyer's Person (#8765 D14) ──────────────────────────────────────────
+
+/** What `checkoutBuyerPerson` reads of a signed `checkout.session.completed`. */
+export type CheckoutBuyerSession = {
+  payment_status?: string | null;
+  customer_details?: { email?: string | null } | null;
+  metadata?: Record<string, string> | null;
+};
+
+export type CheckoutBuyerPerson = { workspaceId: string; personId: string };
+
+function metadataString(
+  metadata: Record<string, string> | null | undefined,
+  key: string,
+): string | null {
+  const value: unknown = metadata?.[key];
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+/**
+ * The Person a completed Checkout Session's terms grant belongs to, or
+ * `null` (the webhook's `person_unresolved`). In order:
+ *
+ *   - a proposal session (`metadata.ailk_proposal` + `ailk_workspace`): that
+ *     piece's Person, when the proposal exists in that workspace;
+ *   - a flow checkout (`metadata.flowCheckoutId`): `flowPerson`, the Person
+ *     the webhook's Person step found or created for it — read, never
+ *     created here.
+ *     Neither falls through to the payer's typed email below;
+ *   - a signed-in buyer (`metadata.ailk_user_id`, which
+ *     `POST /v1/checkout/sessions` stamps only for a verified buyer, #6866):
+ *     the Person of that user's VERIFIED email in the site workspace, found
+ *     or created — in test mode too, since a verified email is the user's
+ *     own; a user with no verified email is `null`, never the payer's typed
+ *     email (SEC-8765-F);
+ *   - any other paid LIVE-mode session with `customer_details.email`: that
+ *     email's Person in the site workspace, found or created. A test-mode
+ *     session never takes this branch, so a sandbox cannot mint a Person
+ *     from a typed email.
+ *
+ * The site workspace is `resolveSiteWorkspaceId()`; `null` there is `null`
+ * here. Never throws — a store failure is `null`.
+ *
+ * @param session the signature-verified event's session object.
+ * @param livemode the signed event's `livemode`.
+ * @param flowPerson a flow checkout's Person, from `resolveCheckoutPerson`.
+ */
+export async function checkoutBuyerPerson(
+  session: CheckoutBuyerSession,
+  livemode: boolean,
+  flowPerson: CheckoutBuyerPerson | null = null,
+): Promise<CheckoutBuyerPerson | null> {
+  const metadata = session.metadata;
+  try {
+    const pieceId = metadataString(metadata, "ailk_proposal");
+    const proposalWorkspaceId = metadataString(metadata, "ailk_workspace");
+    if (pieceId !== null && proposalWorkspaceId !== null) {
+      const personId = await proposalPersonId(proposalWorkspaceId, pieceId);
+      return personId === null
+        ? null
+        : { workspaceId: proposalWorkspaceId, personId };
+    }
+    if (metadataString(metadata, "flowCheckoutId") !== null) return flowPerson;
+
+    const buyerUserId = metadataString(metadata, "ailk_user_id");
+    let email: string;
+    if (buyerUserId !== null) {
+      const verified = await findVerifiedEmail(buyerUserId);
+      if (!verified.ok) return null;
+      email = verified.value.email;
+    } else {
+      const payerEmail = session.customer_details?.email;
+      const paid =
+        session.payment_status === "paid" ||
+        session.payment_status === "no_payment_required";
+      if (!livemode || !paid || typeof payerEmail !== "string") return null;
+      email = payerEmail;
+    }
+
+    const workspaceId = await resolveSiteWorkspaceId();
+    if (workspaceId === null) return null;
+    const person = await findOrCreatePerson(workspaceId, { email });
+    return person.ok ? { workspaceId, personId: person.value.personId } : null;
+  } catch {
+    return null;
+  }
+}

package/templates/apps/api/src/services/consent.ts

@@ -34,6 +34,7 @@ import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { Prisma } from "@working-theory/database";
 import { logger } from "@working-theory/observability";
 import {
+  ACCOUNT_TERMS_PURPOSE_ID,
   consentPolicyHref,
   consentPurposeById,
   consentPurposeKind,
@@ -52,6 +53,7 @@ import {
   effectiveConsent,
   latestVisitorChoice,
   ownConsentRows,
+  personHasCheckoutGrant,
   userPlatformRows,
   type PurposeConsentState,
 } from "../lib/consent-store.js";
@@ -507,6 +509,99 @@ export async function recordPersonConsent(
   });
 }
 
+export type RecordCheckoutConsentOutcome =
+  "recorded" | "unchanged" | "purpose_unknown" | "version_changed";
+
+/**
+ * `<purposeId>@<policyVersion>` of the account terms as the registry reads
+ * them now, and that version — the only stamp a checkout grant is recorded
+ * for (SEC-8765-E). A spoke purchase's lead names the stamp it accepted
+ * (#8778); derived, never written down, so a version bump retires every
+ * older stamp.
+ */
+export function currentAccountTermsStamp(): {
+  stamp: string;
+  policyVersion: number;
+} | null {
+  const purpose = consentPurposeById(
+    SITE_CONSENT_CONFIG_DEFAULTS,
+    ACCOUNT_TERMS_PURPOSE_ID,
+  );
+  return purpose
+    ? {
+        stamp: `${purpose.id}@${purpose.policyVersion}`,
+        policyVersion: purpose.policyVersion,
+      }
+    : null;
+}
+
+/**
+ * The buyer's grant from a completed Stripe Checkout whose terms box was
+ * accepted (#8765 D14): ONE `account_terms` row, subject `person` /
+ * `personId`, source `checkout`, `sourceRef` the Checkout Session id, locale
+ * `en`, and the registry's current statement, hash and policy version — the
+ * statement the box showed once its link keys were resolved (D12).
+ *
+ * One transaction whose first statement is an advisory lock on
+ * `ailk:consent:<workspaceId>:checkout:<sessionId>`; then, when this Person
+ * already holds this session's `checkout` row, nothing is written (NFR7) — so
+ * a webhook redelivery, even after a restart, adds no row. The row goes
+ * through `recordConsent` on the transaction client. A `checkout` row is
+ * unverified (D13): it reaches only the operator's any-source reading.
+ * When the site registry's `account_terms` version is not the version the
+ * session was stamped with, nothing is written (`version_changed`): the row
+ * would otherwise record terms the box never showed.
+ *
+ * @param input.workspaceId the server-resolved workspace of the buyer's Person.
+ * @param input.personId the buyer's Person, resolved by `checkoutBuyerPerson`.
+ * @param input.sessionId the signed event's Checkout Session id.
+ * @param input.policyVersion the version the session's `ailk_terms` stamp names.
+ */
+export async function recordCheckoutConsent(input: {
+  workspaceId: string;
+  personId: string;
+  sessionId: string;
+  policyVersion: number;
+}): Promise<RecordCheckoutConsentOutcome> {
+  const config = await consentConfigForSite(input.workspaceId);
+  const purpose = consentPurposeById(config, ACCOUNT_TERMS_PURPOSE_ID);
+  if (!purpose) return "purpose_unknown";
+  if (purpose.policyVersion !== input.policyVersion) return "version_changed";
+
+  return prisma.$transaction(async (tx) => {
+    await lockConsent(
+      tx,
+      `ailk:consent:${input.workspaceId}:checkout:${input.sessionId}`,
+    );
+    if (
+      await personHasCheckoutGrant(
+        input.workspaceId,
+        input.personId,
+        purpose.id,
+        input.sessionId,
+        tx,
+      )
+    ) {
+      return "unchanged" as const;
+    }
+    await recordConsent(
+      {
+        siteId: input.workspaceId,
+        subjectType: "person",
+        subjectId: input.personId,
+        personId: input.personId,
+        source: "checkout",
+        sourceRef: input.sessionId,
+        locale: "en",
+        config,
+        consents: { [purpose.id]: true },
+      },
+      tx,
+    );
+    return "recorded" as const;
+  });
+}
+
 /**
  * One registry purpose as a settings screen reads it (D6): the wording in
  * `locale`, the policy link, and the caller's OWN state. `state` is `null`