create-ailk 0.22.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/deliverable-fulfillment.ts

@@ -387,7 +387,7 @@ export async function sendCompletionEmail(
 
 export async function fulfillDeliverable(
   input: FulfillDeliverableInput,
-): Promise<void> {
+): Promise<{ grantId: string } | undefined> {
   const {
     siteId,
     flowSlug,
@@ -403,7 +403,7 @@ export async function fulfillDeliverable(
   // the call on this being present; re-checking here is defense in depth,
   // never load-bearing for the "no block → no call" AC4 regression floor.
   const block = configSnapshot.deliverables;
-  if (!block) return;
+  if (!block) return undefined;
 
   const logCtx = { siteId, flowSlug, sessionId };
 
@@ -412,7 +412,7 @@ export async function fulfillDeliverable(
   const entry = resolveEntry(block.assets, segment);
   if (!entry) {
     logOutcome(logCtx, "no_entry");
-    return;
+    return undefined;
   }
 
   // FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset: a per-lead
@@ -439,7 +439,7 @@ export async function fulfillDeliverable(
     });
     if (!instance) {
       logOutcome(logCtx, "playbook_missing");
-      return;
+      return undefined;
     }
     assetId = entry.assetKey;
   } else {
@@ -464,6 +464,13 @@ export async function fulfillDeliverable(
       assetId = resolvedAssetId;
       grantWorkspaceId = workspaceId;
     } else {
+      // #8848 D3 (SEC-8848-B) — a `deliverable` flow resolves against the
+      // Asset store only: it is new, so it has no legacy key to keep, and the
+      // legacy store also holds the founders' signup CSVs.
+      if (configSnapshot.deliverable !== undefined) {
+        logOutcome(logCtx, "asset_missing");
+        return undefined;
+      }
       // #6310 D2/D3 — legacy fallback. A missing row (config references an
       // un-uploaded key) → same skip-and-log posture as before.
       // #6257 — the LEGACY store's read, scoped by the same resolved
@@ -476,7 +483,7 @@ export async function fulfillDeliverable(
 
       if (!asset) {
         logOutcome(logCtx, "asset_missing");
-        return;
+        return undefined;
       }
       assetId = asset.id;
     }
@@ -527,6 +534,7 @@ export async function fulfillDeliverable(
     defaultLocale: configSnapshot.defaultLocale,
     copy: block.copy,
   });
+  return { grantId: grant.id };
 }
 
 // ─── #3998 D3 — resend: reuses the existing grant id, never mints ───────────────

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

@@ -15,15 +15,24 @@
  * foundation fills `features` + `limits.static` (tier + seat count) and returns
  * `limits.metered` as the reserved empty shape FEAT-047 (#3679) fills — this
  * spec builds NO metering engine (spec D5).
+ *
+ * #9067 D5 — the Billing tab's plan card also reads here: the licence expiry,
+ * the Organization's one open plan Checkout, and the customer's billing
+ * summary. That summary is the one Stripe read this resolver makes, through
+ * `lib/stripe.ts`.
  */
-import type { Entitlements } from "@working-theory/license";
+import { checkLicense, type Entitlements } from "@working-theory/license";
+import { logger } from "@working-theory/observability";
 import {
   MAGNET_KIND_MIN_RANK,
+  orgBillingDetailsSchema,
   planRank,
   type FlowConfig,
+  type OrgBillingDetails,
 } from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
+import { readCustomerBillingSummary } from "../lib/stripe.js";
 
 /**
  * Feature flags unlocked per tier. Free unlocks none; every paid tier unlocks
@@ -180,3 +189,150 @@ export async function isBillingCustomerAnOrganization(
   });
   return org !== null;
 }
+
+/**
+ * #9067 D5 — the deployment licence's expiry, as an ISO string, or `null`
+ * for a keyless, expired or invalid licence. The trial state's date
+ * (C2). Never throws: a failed read is `null`.
+ */
+export async function resolveLicenseExpiresAt(): Promise<string | null> {
+  try {
+    const license = await checkLicense();
+    return license.expiresAt?.toISOString() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #9067 D13 — the one plan Checkout this Organization has open, or `null`.
+ * Server-side only: the session id is never served. An unknown
+ * Organization reads `null`.
+ */
+export async function readOrgPlanCheckoutSession(
+  organizationId: string,
+): Promise<string | null> {
+  const org = await prisma.organization.findUnique({
+    where: { id: organizationId },
+    select: { planCheckoutSessionId: true },
+  });
+  return org?.planCheckoutSessionId ?? null;
+}
+
+/**
+ * #9067 D3 step 9b — record the plan Checkout the route just opened, as one
+ * compare-and-set: only while the column still holds `expected` and no
+ * customer is bound. Answers whether one row moved; throws on a database
+ * error.
+ */
+export async function setOrgPlanCheckoutSession(
+  organizationId: string,
+  expected: string | null,
+  next: string,
+): Promise<boolean> {
+  const { count } = await prisma.organization.updateMany({
+    where: { id: organizationId, planCheckoutSessionId: expected, billingCustomerId: null },
+    data: { planCheckoutSessionId: next },
+  });
+  return count === 1;
+}
+
+/**
+ * #9067 7b (code review) — bind the Organization to the customer a COMPLETED
+ * plan Checkout created, when the webhook's bind never landed (a lost event,
+ * a database error the webhook swallowed). The same guarded compare-and-set
+ * the webhook runs: only while the column still holds `sessionId` and no
+ * customer is bound, and it clears the session. Answers whether one row
+ * moved; throws on a database error.
+ */
+export async function bindOrgPlanCheckout(
+  organizationId: string,
+  sessionId: string,
+  customerId: string,
+): Promise<boolean> {
+  const { count } = await prisma.organization.updateMany({
+    where: { id: organizationId, planCheckoutSessionId: sessionId, billingCustomerId: null },
+    data: { billingProvider: "stripe", billingCustomerId: customerId, planCheckoutSessionId: null },
+  });
+  return count === 1;
+}
+
+/** How long one customer's summary is reused, a failure included (#9067 NFR-1). */
+export const ORG_BILLING_SUMMARY_TTL_MS = 60_000;
+/** The most customers held at once; the oldest entry is evicted at the cap. */
+export const ORG_BILLING_SUMMARY_CACHE_MAX = 2_000;
+/** The longest one summary read may take before the keys are left absent (NFR-2). */
+export const ORG_BILLING_SUMMARY_TIMEOUT_MS = 3_000;
+
+type OrgBillingSummaryKeys = Partial<Pick<OrgBillingDetails, "renewsAt" | "sites" | "paymentMethod">>;
+
+/** Per customer: the settled keys and when they expire. Insertion order is age. */
+const orgBillingSummaryCache = new Map<string, { keys: OrgBillingSummaryKeys; expiresAt: number }>();
+/** Per customer: the one read in flight, joined by every concurrent miss. */
+const orgBillingSummaryInFlight = new Map<string, Promise<OrgBillingSummaryKeys>>();
+
+/**
+ * #9067 D5 — the Organization customer's renewal date, site count and card,
+ * from the cache when fresh, else one read shared by every concurrent caller
+ * of the same customer. The member read's wrapper (`services/subscription.ts`),
+ * rebuilt here because importing it would be a cycle. A throw or a timeout
+ * answers `{}` (every key absent) and is cached like a success; a value
+ * outside `orgBillingDetailsSchema`'s bounds is `null`.
+ */
+export async function readOrgBillingSummary(customerId: string): Promise<OrgBillingSummaryKeys> {
+  const cached = orgBillingSummaryCache.get(customerId);
+  if (cached && cached.expiresAt > Date.now()) return cached.keys;
+  const pending = orgBillingSummaryInFlight.get(customerId);
+  if (pending) return pending;
+
+  const read = settleOrgBillingSummary(customerId).then((keys) => {
+    orgBillingSummaryCache.delete(customerId);
+    if (orgBillingSummaryCache.size >= ORG_BILLING_SUMMARY_CACHE_MAX) {
+      const oldest = orgBillingSummaryCache.keys().next().value;
+      if (oldest !== undefined) orgBillingSummaryCache.delete(oldest);
+    }
+    orgBillingSummaryCache.set(customerId, {
+      keys,
+      expiresAt: Date.now() + ORG_BILLING_SUMMARY_TTL_MS,
+    });
+    return keys;
+  });
+  // Cleared however the read ends, so a rejection is never served forever.
+  void read.finally(() => orgBillingSummaryInFlight.delete(customerId)).catch(() => undefined);
+  orgBillingSummaryInFlight.set(customerId, read);
+  return read;
+}
+
+async function settleOrgBillingSummary(customerId: string): Promise<OrgBillingSummaryKeys> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timedOut = new Promise<"timeout">((resolve) => {
+      timer = setTimeout(() => resolve("timeout"), ORG_BILLING_SUMMARY_TIMEOUT_MS);
+    });
+    const summary = await Promise.race([readCustomerBillingSummary(customerId), timedOut]);
+    if (summary === "timeout") throw new Error("timeout");
+    const { shape } = orgBillingDetailsSchema;
+    const renewsAt = shape.renewsAt.safeParse(summary.renewsAt);
+    const sites = shape.sites.safeParse(summary.sites);
+    const paymentMethod = shape.paymentMethod.safeParse(summary.paymentMethod);
+    return {
+      renewsAt: renewsAt.success ? (renewsAt.data ?? null) : null,
+      sites: sites.success ? (sites.data ?? null) : null,
+      paymentMethod: paymentMethod.success ? (paymentMethod.data ?? null) : null,
+    };
+  } catch {
+    logger.warn(
+      { route: "billing", outcome: "summary_unavailable" },
+      "[billing] organization billing summary unavailable",
+    );
+    return {};
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Test seam: forget every cached and in-flight Organization summary. */
+export function __resetOrgBillingSummaryCache(): void {
+  orgBillingSummaryCache.clear();
+  orgBillingSummaryInFlight.clear();
+}