create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/webhooks/README.md

@@ -2,7 +2,9 @@
 
 Stripe webhook receiver at `POST /v1/webhooks/stripe`. Verifies
 signatures, dispatches events via a `switch`, and fires server-side
-telemetry. v1 handles `checkout.session.completed` only.
+telemetry. Handles `customer.created`, `checkout.session.completed`, and
+`checkout.session.expired` (the last two also stamp the recommender's
+buyer row — below).
 
 ## How to add a new event handler
 
@@ -19,25 +21,46 @@ case "invoice.payment_succeeded": {
 Customer forks edit `stripe.ts` directly. v1 ships no pluggable handler
 registry — if multiple forks request one, file an issue.
 
+## Recommender purchase stamp (#4838)
+
+A Checkout Session the recommender opened (`POST /v1/flows/:slug/checkout`,
+#4841) carries `metadata.flowCheckoutId` — the `FlowCheckout` buyer row's
+id. On `checkout.session.completed` the handler stamps that row
+`status: "completed"` (+ `completedAt`, `stripeSessionId`,
+`stripeCustomerId`); on `checkout.session.expired` it stamps
+`status: "expired"`. Both are ONE guarded update —
+`updateMany({ where: { id, status: "created" } })` — so the stamp is
+at-most-once regardless of the in-memory store below: a replay, a restart
+between deliveries, or a late `expired` after a `completed` matches zero
+rows and logs `outcome: "stale_or_unknown"`. A charged `amount_total` that
+differs from the quoted `amountMinor` is logged (`expected` / `received`)
+and the row is still stamped — the quote is never overwritten. The stamp
+runs beside the telemetry + billing tasks, never instead of them, and an
+event without the key never touches `flowCheckout`. Always 200.
+
 ## Idempotency caveat (load-bearing)
 
 Stripe uses **at-least-once delivery semantics** and occasionally
-double-delivers events. v1 has no idempotency store. Telemetry-only side
-effects make this an acceptable counting drift.
-
-**The day a side effect with write semantics is added** (DB persistence,
-confirmation email, refund processing), an idempotency layer must be added
-first. Suggested pattern: a `webhook_events` table keyed on `event.id`
-with an early-return for already-seen IDs.
+double-delivers events. The in-memory store (`lib/webhook-idempotency.ts`)
+short-circuits a replayed `event.id` within one process; it is not durable
+across a restart or a second API instance. Telemetry-only side effects make
+that an acceptable counting drift.
+
+**A side effect with write semantics carries its own durable layer.** The
+recommender stamp above uses a guarded conditional update (the row's
+`status: "created"` is the key). A future write that cannot be expressed as
+a guarded update (confirmation email, refund processing) needs a
+`webhook_events` table keyed on `event.id` with an early-return for
+already-seen IDs — add it first.
 
 ## Env contract
 
 Both vars are **server-only** — never use a `NEXT_PUBLIC_` prefix.
 
-| Var                     | Required                     | Notes                                                                                               |
-| ----------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
-| `STRIPE_WEBHOOK_SECRET` | For the route to do anything | `whsec_*` from Stripe Dashboard                                                                     |
-| `STRIPE_SECRET_KEY`     | For checkout + sandbox check | Must be `sk_test_*`; live keys are hook-blocked at commit and runtime-blocked by `assertSandboxKey` |
+| Var                     | Required                     | Notes                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STRIPE_WEBHOOK_SECRET` | For the route to do anything | `whsec_*` from Stripe Dashboard                                                                                                                                                                                                                                                                                                                                                                |
+| `STRIPE_SECRET_KEY`     | For checkout + sandbox check | Must match an allow-listed test-mode prefix (`sk_test_*` / `pk_test_*` / `rk_test_*`); anything else — including live and restricted-live keys — is runtime-blocked by `assertSandboxKey`. The commit-time hook is a partial backstop only: it greps for `sk_live_` / `pk_live_` and does **not** catch restricted-live (`rk_live_`) keys, so the runtime allow-list is the load-bearing guard |
 
 Without `STRIPE_WEBHOOK_SECRET`, the route returns 503 on every request.
 

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-flow-checkout.test.ts

@@ -0,0 +1,315 @@
+/**
+ * POST /api/webhooks/stripe — the recommender FlowCheckout stamp (#4838).
+ *
+ * The stripe.test.ts mock shape: `@working-theory/analytics/server` `track`,
+ * the prisma auto-mock, `@working-theory/stripe-client`'s
+ * `verifyWebhookSignature` at the package boundary. AC-1 … AC-5. The four
+ * pre-existing webhook suites are the regression floor and are not edited.
+ * AC-6 (#4862) adds the `no_payment_required` (zero-due) case.
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+jest.mock("@working-theory/analytics/server", () => ({
+  track: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => ({
+  verifyWebhookSignature: (...args: unknown[]) => mockVerifyWebhookSignature(...args),
+  StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  assertSandboxKey: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  getStripeClient: jest.fn(),
+  STRIPE_API_VERSION: "2024-06-20",
+  StripeConfigError: class StripeConfigError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+}));
+
+import * as configModule from "../../../config/index.js";
+import { stripeWebhookHandler } from "../stripe.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { prisma } from "../../../lib/prisma.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+const FLOW_CHECKOUT_ID = "flchk_test_1";
+const SESSION_ID = "cs_test_session_12345678901234567890";
+const CUSTOMER_ID = "cus_test_12345678901234567890";
+const EMAIL = "alice@example.com";
+const PERMALINK = "eyJ2ZXJzaW9uIjoxLCJmbG93U2x1ZyI6ImFpbGstcmVjbyJ9";
+
+function sessionEvent(type: "checkout.session.completed" | "checkout.session.expired", object: Record<string, unknown> = {}) {
+  return {
+    id: "evt_test_12345678abcdef",
+    type,
+    data: {
+      object: {
+        id: SESSION_ID,
+        payment_status: "paid",
+        amount_total: 24900,
+        currency: "usd",
+        customer: CUSTOMER_ID,
+        customer_details: { email: EMAIL },
+        metadata: { flowCheckoutId: FLOW_CHECKOUT_ID, flowSlug: "ailk-reco", offerKey: "pro", permalink: PERMALINK },
+        ...object,
+      },
+    },
+  };
+}
+
+type LogCall = [unknown, string?];
+const logCalls: LogCall[] = [];
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (webhooksScope) => {
+    webhooksScope.addContentTypeParser("application/json", { parseAs: "buffer" }, (_req, body, done) => {
+      done(null, body);
+    });
+    webhooksScope.addHook("onRequest", async (request) => {
+      for (const level of ["info", "warn", "error"] as const) {
+        const original = request.log[level].bind(request.log);
+        request.log[level] = ((...args: unknown[]) => {
+          logCalls.push(args as LogCall);
+          return (original as (...a: unknown[]) => void)(...args);
+        }) as typeof request.log.info;
+      }
+    });
+    webhooksScope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const HEADERS = { "content-type": "application/json", "stripe-signature": "t=1234,v1=abc" };
+
+let server: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  logCalls.length = 0;
+  __resetIdempotencyStore();
+  jest.replaceProperty(configModule, "config", {
+    ...configModule.config,
+    STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+  });
+  (prisma.flowCheckout.findUnique as jest.Mock).mockResolvedValue({ amountMinor: 24900 });
+  (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.user.findFirst as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+  server = await buildTestServer();
+});
+
+afterEach(async () => {
+  await server.close();
+  jest.restoreAllMocks();
+});
+
+async function post() {
+  return server.inject({ method: "POST", url: "/v1/webhooks/stripe", payload: VALID_BODY, headers: HEADERS });
+}
+
+function stampCall() {
+  expect(prisma.flowCheckout.updateMany).toHaveBeenCalledTimes(1);
+  return (prisma.flowCheckout.updateMany as jest.Mock).mock.calls[0][0];
+}
+
+// ── AC-1 — completed stamps the row once, guarded, beside the legacy tasks ──
+
+describe("AC-1 — completed stamps the row once, guarded, beside the legacy tasks", () => {
+  it("stamps completed with the guard, the session id and the customer; telemetry + billing still run", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed"));
+    const res = await post();
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+
+    const call = stampCall();
+    expect(call.where).toEqual({ id: FLOW_CHECKOUT_ID, status: "created" });
+    expect(call.data.status).toBe("completed");
+    expect(call.data.completedAt).toBeInstanceOf(Date);
+    expect(call.data.stripeSessionId).toBe(SESSION_ID);
+    expect(call.data.stripeCustomerId).toBe(CUSTOMER_ID);
+
+    // The legacy tasks, exactly as stripe.test.ts asserts them.
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    expect(mockTrack).toHaveBeenCalledWith("purchase-completed", {
+      amount: 24900,
+      currency: "usd",
+      productId: undefined,
+      eventType: "checkout.session.completed",
+      eventIdPrefix: "evt_test",
+    });
+    expect(prisma.user.findFirst).toHaveBeenCalledWith({
+      where: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+    });
+    expect(prisma.user.findUnique).toHaveBeenCalledWith({ where: { email: EMAIL } });
+  });
+});
+
+// ── AC-2 — expired stamps expired ───────────────────────────────────────────
+
+describe("AC-2 — expired stamps expired", () => {
+  it("stamps status expired under the same guard, with no completedAt", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.expired"));
+    const res = await post();
+    expect(res.statusCode).toBe(200);
+    const call = stampCall();
+    expect(call.where.status).toBe("created");
+    expect(call.where.id).toBe(FLOW_CHECKOUT_ID);
+    expect(call.data).toEqual({ status: "expired" });
+    expect(call.data).not.toHaveProperty("completedAt");
+    expect(prisma.flowCheckout.findUnique).not.toHaveBeenCalled();
+    expect(mockTrack).not.toHaveBeenCalled();
+  });
+});
+
+// ── AC-3 — the legacy paths are byte-unchanged ──────────────────────────────
+
+describe("AC-3 — the legacy paths are byte-unchanged", () => {
+  it("an event without flowCheckoutId never touches prisma.flowCheckout", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { metadata: { productId: "starter" } }),
+    );
+    const res = await post();
+    expect(res.statusCode).toBe(200);
+    expect(prisma.flowCheckout.findUnique).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+  });
+
+  it("an expired event without the key is a no-op 200 that logs the unhandled-event line", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.expired", { metadata: null }));
+    expect((await post()).statusCode).toBe(200);
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    const unhandled = logCalls.find((c) => c[1] === "unhandled webhook event");
+    expect(unhandled?.[0]).toEqual({ eventType: "checkout.session.expired", eventIdPrefix: "evt_test" });
+  });
+
+  it("a completed session that is not paid logs `unpaid` and does NOT stamp — the row stays created", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { payment_status: "unpaid" }),
+    );
+    expect((await post()).statusCode).toBe(200);
+    expect(prisma.flowCheckout.findUnique).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.updateMany).not.toHaveBeenCalled();
+    const unpaid = logCalls.find((c) => (c[0] as { outcome?: string })?.outcome === "unpaid");
+    expect(unpaid?.[0]).toEqual({
+      eventIdPrefix: "evt_test",
+      flowCheckoutIdPrefix: FLOW_CHECKOUT_ID.substring(0, 8),
+      outcome: "unpaid",
+    });
+    // The legacy tasks still ran for the event.
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ── AC-6 — a zero-due (no_payment_required) session stamps completed ───────
+
+describe("AC-6 — no_payment_required stamps completed exactly as paid (#4862)", () => {
+  it("stamps completed with the guard, the session id and the customer; telemetry + billing still run", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      sessionEvent("checkout.session.completed", { payment_status: "no_payment_required" }),
+    );
+    const res = await post();
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+
+    const call = stampCall();
+    expect(call.where).toEqual({ id: FLOW_CHECKOUT_ID, status: "created" });
+    expect(call.data.status).toBe("completed");
+    expect(call.data.completedAt).toBeInstanceOf(Date);
+    expect(call.data.stripeSessionId).toBe(SESSION_ID);
+    expect(call.data.stripeCustomerId).toBe(CUSTOMER_ID);
+
+    expect(mockTrack).toHaveBeenCalledTimes(1);
+    const unpaid = logCalls.find((c) => (c[0] as { outcome?: string })?.outcome === "unpaid");
+    expect(unpaid).toBeUndefined();
+  });
+});
+
+// ── AC-4 — never a retry storm ──────────────────────────────────────────────
+
+describe("AC-4 — never a retry storm", () => {
+  it("count 0 logs stale_or_unknown and still 200s", async () => {
+    (prisma.flowCheckout.updateMany as jest.Mock).mockResolvedValue({ count: 0 });
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed"));
+    expect((await post()).statusCode).toBe(200);
+    const stale = logCalls.find((c) => (c[0] as { outcome?: string })?.outcome === "stale_or_unknown");
+    expect(stale).toBeDefined();
+  });
+
+  it("an updateMany rejection logs an error and still 200s", async () => {
+    (prisma.flowCheckout.updateMany as jest.Mock).mockRejectedValue(new Error("db down"));
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed"));
+    expect((await post()).statusCode).toBe(200);
+    const failed = logCalls.find((c) => (c[0] as { outcome?: string })?.outcome === "stamp_failed");
+    expect(failed).toBeDefined();
+  });
+
+  it("a charged amount that differs from the quote logs both integers and STILL stamps completed", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(sessionEvent("checkout.session.completed", { amount_total: 25000 }));
+    expect((await post()).statusCode).toBe(200);
+    const mismatch = logCalls.find((c) => (c[0] as { outcome?: string })?.outcome === "amount_mismatch");
+    expect(mismatch?.[0]).toEqual({
+      eventIdPrefix: "evt_test",
+      flowCheckoutIdPrefix: FLOW_CHECKOUT_ID.substring(0, 8),
+      outcome: "amount_mismatch",
+      expected: 24900,
+      received: 25000,
+    });
+    expect(stampCall().data.status).toBe("completed");
+  });
+});
+
+// ── AC-5 — PII boundary ─────────────────────────────────────────────────────
+
+describe("AC-5 — PII boundary", () => {
+  it.each([
+    ["the AC-1 event", sessionEvent("checkout.session.completed"), null],
+    ["the AC-4 mismatch event", sessionEvent("checkout.session.completed", { amount_total: 25000 }), null],
+    [
+      "the stamp_failed branch",
+      sessionEvent("checkout.session.completed"),
+      new Error(`connection refused for ${EMAIL} at ${CUSTOMER_ID}`),
+    ],
+  ])("every log line for %s carries no email, customer_details, permalink, or a full cus_/cs_ id", async (_name, event, rejection) => {
+    if (rejection) (prisma.flowCheckout.updateMany as jest.Mock).mockRejectedValue(rejection);
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    expect((await post()).statusCode).toBe(200);
+    const ALLOWED = new Set(["eventIdPrefix", "flowCheckoutIdPrefix", "outcome", "expected", "received", "errName"]);
+    const stampLines = logCalls.filter((c) => typeof c[0] === "object" && c[0] !== null && "flowCheckoutIdPrefix" in c[0]);
+    expect(stampLines.length).toBeGreaterThan(0);
+    for (const line of stampLines) {
+      for (const key of Object.keys(line[0] as object)) expect(ALLOWED.has(key)).toBe(true);
+    }
+    if (rejection) {
+      const failed = stampLines.find((c) => (c[0] as { outcome?: string }).outcome === "stamp_failed");
+      expect(failed?.[0]).toEqual({
+        eventIdPrefix: "evt_test",
+        flowCheckoutIdPrefix: FLOW_CHECKOUT_ID.substring(0, 8),
+        outcome: "stamp_failed",
+        errName: "Error",
+      });
+    }
+    for (const line of logCalls) {
+      const text = JSON.stringify(line);
+      expect(text).not.toContain(EMAIL);
+      expect(text).not.toContain("customer_details");
+      expect(text).not.toContain(PERMALINK);
+      for (const token of text.match(/\b(?:cus|cs)_[A-Za-z0-9_]+/g) ?? []) expect(token.length).toBeLessThanOrEqual(8);
+    }
+  });
+});

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-org-billing.test.ts

@@ -0,0 +1,270 @@
+/**
+ * POST /api/webhooks/stripe — org-scoped billing path (#3601, spec AC2/AC4)
+ *
+ * Covers the Organization billing-link branch keyed on
+ * metadata.organizationId (spec D2): a checkout with organizationId links the
+ * Organization (real org AND individual-as-default-org), idempotently; a
+ * checkout WITHOUT organizationId takes the User path and never touches the
+ * Organization (single-tenant, degrade-clean regression floor).
+ *
+ * Companion to stripe.test.ts (the User-path tests, which stay unmodified —
+ * AC4 regression floor).
+ */
+import type { FastifyInstance } from "fastify";
+import Fastify from "fastify";
+
+// ── Mocks (mirror stripe.test.ts) ────────────────────────────────────────────
+
+const mockTrack = jest.fn().mockResolvedValue(undefined);
+jest.mock("@working-theory/analytics/server", () => ({
+  track: (...args: unknown[]) => mockTrack(...args),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../../lib/prisma.js");
+
+const mockVerifyWebhookSignature = jest.fn();
+class MockStripeWebhookSignatureError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StripeWebhookSignatureError";
+  }
+}
+jest.mock("@working-theory/stripe-client", () => ({
+  verifyWebhookSignature: (...args: unknown[]) =>
+    mockVerifyWebhookSignature(...args),
+  StripeWebhookSignatureError: MockStripeWebhookSignatureError,
+  assertSandboxKey: jest.fn(),
+  createCheckoutSession: jest.fn(),
+  getStripeClient: jest.fn(),
+  STRIPE_API_VERSION: "2024-06-20",
+  StripeConfigError: class StripeConfigError extends Error {},
+  UnknownProductCodeError: class UnknownProductCodeError extends Error {},
+  WEBHOOK_TOLERANCE_SECONDS: 300,
+}));
+
+import * as configModule from "../../../config/index.js";
+import { prisma } from "../../../lib/prisma.js";
+import { __resetIdempotencyStore } from "../../../lib/webhook-idempotency.js";
+import { stripeWebhookHandler } from "../stripe.js";
+
+// The sentinel default Organization id (orgs-of-one billing anchor).
+const DEFAULT_ORG_ID = "org_00000000-0000-7000-8000-000000000001";
+const REAL_ORG_ID = "org_00000000-0000-7000-8000-0000000000ab";
+
+const VALID_BODY = Buffer.from(JSON.stringify({ type: "test" }));
+const VALID_SIGNATURE = "t=1234,v1=abc";
+
+async function buildTestServer(): Promise<FastifyInstance> {
+  const server = Fastify({ logger: false });
+  await server.register(async (scope) => {
+    scope.addContentTypeParser(
+      "application/json",
+      { parseAs: "buffer" },
+      (_req, body, done) => done(null, body),
+    );
+    scope.post("/v1/webhooks/stripe", stripeWebhookHandler);
+  });
+  await server.ready();
+  return server;
+}
+
+function checkoutEvent(
+  id: string,
+  metadata: Record<string, string> | null,
+  customer = "cus_test_org_123",
+) {
+  return {
+    id,
+    type: "checkout.session.completed",
+    data: {
+      object: {
+        id: "cs_test_org",
+        amount_total: 9900,
+        currency: "usd",
+        customer,
+        customer_details: { email: "org-admin@example.com" },
+        metadata,
+      },
+    },
+  };
+}
+
+async function fire(server: FastifyInstance) {
+  return server.inject({
+    method: "POST",
+    url: "/v1/webhooks/stripe",
+    payload: VALID_BODY,
+    headers: {
+      "content-type": "application/json",
+      "stripe-signature": VALID_SIGNATURE,
+    },
+  });
+}
+
+describe("POST /api/webhooks/stripe — org-scoped billing (#3601)", () => {
+  let server: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    __resetIdempotencyStore();
+    jest.replaceProperty(configModule, "config", {
+      ...configModule.config,
+      STRIPE_WEBHOOK_SECRET: "whsec_test_secret",
+    });
+    server = await buildTestServer();
+  });
+
+  afterEach(async () => {
+    await server.close();
+    jest.restoreAllMocks();
+  });
+
+  // AC2 — a real org checkout links the Organization by id; replay is a no-op.
+  it("links the Organization on checkout with metadata.organizationId, idempotent on replay", async () => {
+    const customerId = "cus_test_org_123";
+
+    // First fire: no prior composite link → update the target org.
+    (prisma.organization.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    (prisma.organization.update as jest.Mock).mockResolvedValueOnce({
+      id: REAL_ORG_ID,
+      billingProvider: "stripe",
+      billingCustomerId: customerId,
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent("evt_org_001", { organizationId: REAL_ORG_ID }, customerId),
+    );
+    const r1 = await fire(server);
+    expect(r1.statusCode).toBe(200);
+    expect(prisma.organization.update).toHaveBeenCalledTimes(1);
+    expect(prisma.organization.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: REAL_ORG_ID },
+        data: expect.objectContaining({
+          billingProvider: "stripe",
+          billingCustomerId: customerId,
+        }),
+      }),
+    );
+    // The User path is never taken for an org checkout.
+    expect(prisma.user.update).not.toHaveBeenCalled();
+
+    // Replay the SAME event id → idempotency store short-circuits, no 2nd write.
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent("evt_org_001", { organizationId: REAL_ORG_ID }, customerId),
+    );
+    const r2 = await fire(server);
+    expect(r2.statusCode).toBe(200);
+    expect(prisma.organization.update).toHaveBeenCalledTimes(1);
+  });
+
+  // AC2 — typed-composite match already pointing at this org → no-op (a fresh
+  // event id, but the customer is already linked to the target org).
+  it("is a no-op when the org is already linked to this customer (typed-composite match)", async () => {
+    const customerId = "cus_already_linked";
+    (prisma.organization.findFirst as jest.Mock).mockResolvedValueOnce({
+      id: REAL_ORG_ID,
+      billingProvider: "stripe",
+      billingCustomerId: customerId,
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent("evt_org_002", { organizationId: REAL_ORG_ID }, customerId),
+    );
+    const r = await fire(server);
+    expect(r.statusCode).toBe(200);
+    expect(prisma.organization.update).not.toHaveBeenCalled();
+  });
+
+  // AC2 — an individual is billed on their sentinel default Organization
+  // (orgs-of-one): the SAME org path, targeting DEFAULT_ORG_ID.
+  it("bills an individual on their sentinel default Organization (orgs-of-one)", async () => {
+    const customerId = "cus_individual_xyz";
+    (prisma.organization.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    (prisma.organization.update as jest.Mock).mockResolvedValueOnce({
+      id: DEFAULT_ORG_ID,
+      billingProvider: "stripe",
+      billingCustomerId: customerId,
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent(
+        "evt_org_003",
+        { organizationId: DEFAULT_ORG_ID },
+        customerId,
+      ),
+    );
+    const r = await fire(server);
+    expect(r.statusCode).toBe(200);
+    expect(prisma.organization.update).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: DEFAULT_ORG_ID } }),
+    );
+    expect(prisma.user.update).not.toHaveBeenCalled();
+  });
+
+  // AC4 — a checkout WITHOUT organizationId takes the User path unchanged; the
+  // Organization is never touched (single-tenant degrade-clean regression).
+  it("takes the User path (never touches Organization) when no organizationId is present", async () => {
+    const customerId = "cus_single_tenant";
+    (prisma.user.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    (prisma.user.findUnique as jest.Mock).mockResolvedValueOnce({
+      id: "usr_st",
+      email: "org-admin@example.com",
+      billingProvider: null,
+      billingCustomerId: null,
+    });
+    (prisma.user.update as jest.Mock).mockResolvedValueOnce({ id: "usr_st" });
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent("evt_st_004", { productId: "pro" }, customerId),
+    );
+    const r = await fire(server);
+    expect(r.statusCode).toBe(200);
+    expect(prisma.user.update).toHaveBeenCalledTimes(1);
+    expect(prisma.organization.findFirst).not.toHaveBeenCalled();
+    expect(prisma.organization.update).not.toHaveBeenCalled();
+  });
+
+  // customer.created also routes on metadata.organizationId.
+  it("links the Organization on customer.created with metadata.organizationId", async () => {
+    const customerId = "cus_created_org";
+    (prisma.organization.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    (prisma.organization.update as jest.Mock).mockResolvedValueOnce({
+      id: REAL_ORG_ID,
+    });
+
+    mockVerifyWebhookSignature.mockReturnValue({
+      id: "evt_cust_005",
+      type: "customer.created",
+      data: {
+        object: {
+          id: customerId,
+          email: "org-admin@example.com",
+          metadata: { organizationId: REAL_ORG_ID },
+        },
+      },
+    });
+    const r = await fire(server);
+    expect(r.statusCode).toBe(200);
+    expect(prisma.organization.update).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: REAL_ORG_ID } }),
+    );
+    expect(prisma.user.update).not.toHaveBeenCalled();
+  });
+
+  // A DB failure on the org link never throws (200 still returned).
+  it("returns 200 even when the org billing update throws", async () => {
+    (prisma.organization.findFirst as jest.Mock).mockResolvedValueOnce(null);
+    (prisma.organization.update as jest.Mock).mockRejectedValueOnce(
+      new Error("db unreachable"),
+    );
+
+    mockVerifyWebhookSignature.mockReturnValue(
+      checkoutEvent("evt_org_006", { organizationId: REAL_ORG_ID }),
+    );
+    const r = await fire(server);
+    expect(r.statusCode).toBe(200);
+    expect(JSON.parse(r.body)).toEqual({ received: true });
+  });
+});