create-ailk 0.19.1 → 0.20.0

package/templates/apps/api/src/routes/webhooks/__tests__/stripe-site-filter.test.ts

@@ -7,6 +7,13 @@
  * session, an empty stamp, and the hub's own stamp are handled exactly as
  * today (roadmap D4). Spec D3/D7, AC-2 … AC-4.
  *
+ * Cases 9–17 (#8024, spec D4): the same filter over the billing families —
+ * `customer.*`, `customer.subscription.*` and `invoice.*` — read from the
+ * object's own metadata and, for an invoice, from the subscription snapshot
+ * at both API-version locations. A foreign event answers 200 and touches no
+ * prisma mock at all; an unstamped, empty or own stamp reaches its arm as
+ * today.
+ *
  * The stripe-flow-checkout.test.ts harness: the commerce claim mocked present,
  * the prisma manual mock, `verifyWebhookSignature` mocked at the package
  * boundary, the idempotency store reset per test. The seven existing
@@ -50,6 +57,10 @@ jest.mock("@working-theory/stripe-client", () => ({
   StripeConfigError: class StripeConfigError extends Error {},
   UnknownProductCodeError: class UnknownProductCodeError extends Error {},
   WEBHOOK_TOLERANCE_SECONDS: 300,
+  // Real, as in stripe-dunning.test.ts — the #8024 cases drive the
+  // `customer.subscription.updated` arm, which narrows the status with it.
+  toSubscriptionLifecycleStatus: jest.requireActual("@working-theory/stripe-client")
+    .toSubscriptionLifecycleStatus,
 }));
 
 import * as configModule from "../../../config/index.js";
@@ -364,3 +375,434 @@ describe("case 8 — a foreign event delivered twice", () => {
     expectNoHubSideEffect();
   });
 });
+
+// ── #8024 — the billing families ────────────────────────────────────────────
+
+const SUBSCRIPTION_ID = "sub_test_12345678901234567890";
+const INVOICE_ID = "in_test_12345678901234567890";
+const FOREIGN = { site: "samhenry" };
+
+/** Every fixture carries `data.object.object`, as Stripe sends it. */
+function billingEvent(type: string, object: Record<string, unknown>, extra: Record<string, unknown> = {}) {
+  return { id: "evt_test_12345678abcdef", type, created: 1_760_000_000, data: { object }, ...extra };
+}
+
+function customerEvent(type: string, metadata: unknown) {
+  return billingEvent(type, { object: "customer", id: CUSTOMER_ID, email: EMAIL, metadata });
+}
+
+function subscriptionEvent(type: string, metadata: unknown) {
+  return billingEvent(type, {
+    object: "subscription",
+    id: SUBSCRIPTION_ID,
+    customer: CUSTOMER_ID,
+    status: "past_due",
+    metadata,
+  });
+}
+
+type InvoiceStamps = { metadata?: unknown; snapshot?: unknown };
+
+/** The pinned API version's shape: the subscription snapshot under `parent`, no top-level `subscription`. */
+function dahliaInvoice(type: string, { metadata = {}, snapshot = {} }: InvoiceStamps = {}) {
+  return billingEvent(type, {
+    object: "invoice",
+    id: INVOICE_ID,
+    customer: CUSTOMER_ID,
+    customer_email: EMAIL,
+    metadata,
+    parent: {
+      type: "subscription_details",
+      subscription_details: { subscription: SUBSCRIPTION_ID, metadata: snapshot },
+    },
+  });
+}
+
+/** A pre-`basil` endpoint's shape: top-level `subscription` and `subscription_details`. */
+function preBasilInvoice(type: string, { metadata = {}, snapshot = {} }: InvoiceStamps = {}) {
+  return billingEvent(type, {
+    object: "invoice",
+    id: INVOICE_ID,
+    customer: CUSTOMER_ID,
+    customer_email: EMAIL,
+    metadata,
+    subscription: SUBSCRIPTION_ID,
+    subscription_details: { metadata: snapshot },
+  });
+}
+
+/** Arms every billing arm so that, unfiltered, it reaches a read or a write. */
+function armEveryWrite() {
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+    id: USER_ID,
+    billingProvider: null,
+    billingCustomerId: null,
+  });
+  (prisma.user.update as jest.Mock).mockResolvedValue({});
+  (prisma.userData.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.userData.create as jest.Mock).mockResolvedValue({});
+  (prisma.userData.updateMany as jest.Mock).mockResolvedValue({ count: 1 });
+  (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({ value: { graceDays: 14 } });
+}
+
+/**
+ * No call on ANY method of the prisma manual mock — every delegate's every
+ * `jest.fn`, and the client-level ones (`$transaction`, `$queryRaw`, …) —
+ * and no telemetry. A walk, not a fixed list, so a write outside the arms
+ * this file knows about cannot pass (§ 9 SEC-8024-5).
+ */
+function expectNoPrismaCall() {
+  const called: string[] = [];
+  for (const [name, member] of Object.entries(prisma)) {
+    if (jest.isMockFunction(member)) {
+      if (member.mock.calls.length > 0) called.push(name);
+      continue;
+    }
+    if (typeof member !== "object" || member === null) continue;
+    for (const [method, fn] of Object.entries(member as Record<string, unknown>)) {
+      if (jest.isMockFunction(fn) && fn.mock.calls.length > 0) called.push(`${name}.${method}`);
+    }
+  }
+  expect(called).toEqual([]);
+  expect(mockTrack).not.toHaveBeenCalled();
+}
+
+function logMessages() {
+  return logCalls.map(([, msg]) => msg);
+}
+
+function outcomeLogs(outcome: string) {
+  return logCalls.filter(
+    ([obj]) => typeof obj === "object" && obj !== null && (obj as Record<string, unknown>)["outcome"] === outcome,
+  );
+}
+
+function expectForeignSkip(eventType: string, stamp = "samhenry", ownSite = "default") {
+  const lines = foreignSiteLogs();
+  expect(lines).toHaveLength(1);
+  expect(lines[0]![0]).toEqual({
+    eventType,
+    eventIdPrefix: "evt_test",
+    outcome: "foreign_site",
+    stamp,
+    ownSite,
+  });
+}
+
+function expectDunningWritten() {
+  expect(prisma.user.findUnique).toHaveBeenCalledWith({
+    where: {
+      billingProvider_billingCustomerId: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+    },
+    select: { id: true },
+  });
+  expect(prisma.userData.create).toHaveBeenCalledTimes(1);
+}
+
+// ── Case 9 — a foreign event on every handled arm writes nothing (AC-1) ────
+
+describe("case 9 — a billing event stamped for another site, on every handled arm", () => {
+  it.each([
+    ["customer.created (ailk_user_id)", customerEvent("customer.created", { ...FOREIGN, ailk_user_id: USER_ID })],
+    ["customer.created (organizationId)", customerEvent("customer.created", { ...FOREIGN, organizationId: ORG_ID })],
+    ["customer.subscription.updated", subscriptionEvent("customer.subscription.updated", FOREIGN)],
+    ["invoice.payment_failed (dahlia)", dahliaInvoice("invoice.payment_failed", { snapshot: FOREIGN })],
+    ["invoice.payment_failed (pre-basil)", preBasilInvoice("invoice.payment_failed", { snapshot: FOREIGN })],
+    ["invoice.paid (dahlia)", dahliaInvoice("invoice.paid", { snapshot: FOREIGN })],
+    ["invoice.paid (pre-basil)", preBasilInvoice("invoice.paid", { snapshot: FOREIGN })],
+  ])("%s answers 200, logs one foreign_site line and touches no prisma mock", async (_label, event) => {
+    armEveryWrite();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expectNoPrismaCall();
+    expectForeignSkip(event.type);
+    expect(outcomeLogs("not_a_subscription_invoice")).toHaveLength(0);
+
+    const logged = JSON.stringify(logCalls);
+    expect(logged).not.toContain(CUSTOMER_ID);
+    expect(logged).not.toContain(USER_ID);
+    expect(logged).not.toContain(EMAIL);
+  });
+});
+
+// ── Case 10 — the gate is family-wide, not per arm (AC-1) ───────────────────
+
+describe("case 10 — a foreign event of an unhandled type in each family", () => {
+  it.each([
+    ["customer.updated", customerEvent("customer.updated", FOREIGN)],
+    ["customer.subscription.deleted", subscriptionEvent("customer.subscription.deleted", FOREIGN)],
+    ["invoice.finalized", dahliaInvoice("invoice.finalized", { snapshot: FOREIGN })],
+  ])("%s logs foreign_site and never reaches the default arm", async (_label, event) => {
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectNoPrismaCall();
+    expectForeignSkip(event.type);
+    expect(logMessages()).not.toContain("unhandled webhook event");
+  });
+});
+
+// ── Case 11 — every invoice source counts, and any foreign one wins (AC-1) ──
+
+describe("case 11 — an invoice stamped at each of its three sources", () => {
+  it.each([
+    ["its own metadata", preBasilInvoice("invoice.payment_failed", { metadata: FOREIGN })],
+    ["the dahlia snapshot only", dahliaInvoice("invoice.payment_failed", { snapshot: FOREIGN })],
+    ["the pre-basil snapshot only", preBasilInvoice("invoice.payment_failed", { snapshot: FOREIGN })],
+  ])("a stamp in %s is foreign", async (_label, event) => {
+    armEveryWrite();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    await post();
+
+    expectNoPrismaCall();
+    expectForeignSkip("invoice.payment_failed");
+  });
+
+  it.each([
+    ["dahlia", dahliaInvoice("invoice.payment_failed", { metadata: { site: "default" }, snapshot: FOREIGN })],
+    ["pre-basil", preBasilInvoice("invoice.payment_failed", { metadata: { site: "default" }, snapshot: FOREIGN })],
+  ])("an own invoice stamp over a foreign snapshot is foreign, and logs the foreign stamp (%s)", async (_label, event) => {
+    armEveryWrite();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    await post();
+
+    expectNoPrismaCall();
+    expectForeignSkip("invoice.payment_failed", "samhenry");
+  });
+});
+
+// ── Case 12 — a foreign billing event is marked seen (F3) ───────────────────
+
+describe("case 12 — a foreign subscription event delivered twice", () => {
+  it("takes the duplicate short-circuit on the redelivery", async () => {
+    armEveryWrite();
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionEvent("customer.subscription.updated", FOREIGN),
+    );
+    await post();
+    expect(foreignSiteLogs()).toHaveLength(1);
+
+    logCalls.length = 0;
+    const second = await post();
+
+    expect(second.statusCode).toBe(200);
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expect(logMessages()).toContain("duplicate stripe webhook event — idempotent short-circuit");
+    expectNoPrismaCall();
+  });
+});
+
+// ── Case 13 — unstamped, empty and own stamps keep today's behavior (AC-2) ──
+
+const HUB_STAMPS: Array<[string, Record<string, string>]> = [
+  ["no stamp", {}],
+  ["an empty stamp", { site: "" }],
+  ["the own stamp", { site: "default" }],
+];
+
+describe.each(HUB_STAMPS)("case 13 — a billing event with %s", (_label, stamp) => {
+  beforeEach(() => armEveryWrite());
+
+  afterEach(() => {
+    expect(foreignSiteLogs()).toHaveLength(0);
+  });
+
+  it("customer.created with ailk_user_id binds the User's billing customer", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      customerEvent("customer.created", { ...stamp, ailk_user_id: USER_ID }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.user.update).toHaveBeenCalledWith({
+      where: { id: USER_ID, billingCustomerId: null },
+      data: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+    });
+  });
+
+  it("customer.created with organizationId binds the Organization's billing customer", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      customerEvent("customer.created", { ...stamp, organizationId: ORG_ID }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.organization.update).toHaveBeenCalledWith({
+      where: { id: ORG_ID },
+      data: { billingProvider: "stripe", billingCustomerId: CUSTOMER_ID },
+    });
+  });
+
+  it("customer.subscription.updated writes the subscriber's dunning record", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(subscriptionEvent("customer.subscription.updated", stamp));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectDunningWritten();
+  });
+
+  it("a pre-basil invoice.payment_failed writes the subscriber's dunning record", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(preBasilInvoice("invoice.payment_failed", { snapshot: stamp }));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expectDunningWritten();
+  });
+
+  it("a dahlia invoice.payment_failed logs not_a_subscription_invoice, as today", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(dahliaInvoice("invoice.payment_failed", { snapshot: stamp }));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(outcomeLogs("not_a_subscription_invoice")).toHaveLength(1);
+    expect(prisma.userData.create).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["dahlia", dahliaInvoice],
+    ["pre-basil", preBasilInvoice],
+  ])("a %s invoice.paid runs the request-paid stamp", async (_shape, invoice) => {
+    mockVerifyWebhookSignature.mockReturnValue(invoice("invoice.paid", { snapshot: stamp }));
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(prisma.callback.updateMany).toHaveBeenCalledWith({
+      where: { stripeInvoiceId: INVOICE_ID, paidAt: null },
+      data: { paidAt: expect.any(Date) },
+    });
+  });
+});
+
+// ── Case 14 — the alias is read per call (AC-2) ─────────────────────────────
+
+describe("case 14 — under AILK_SITE_ID=wksp_hub", () => {
+  beforeEach(() => {
+    process.env.AILK_SITE_ID = "wksp_hub";
+    armEveryWrite();
+  });
+
+  it("a subscription stamped wksp_hub is own, and writes its dunning record", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionEvent("customer.subscription.updated", { site: "wksp_hub" }),
+    );
+    await post();
+
+    expectDunningWritten();
+    expect(foreignSiteLogs()).toHaveLength(0);
+  });
+
+  it("a subscription stamped default is foreign", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      subscriptionEvent("customer.subscription.updated", { site: "default" }),
+    );
+    await post();
+
+    expectNoPrismaCall();
+    expectForeignSkip("customer.subscription.updated", "default", "wksp_hub");
+  });
+});
+
+// ── Case 15 — malformed shapes never throw (NF1) ────────────────────────────
+
+describe("case 15 — malformed payload shapes are unstamped and answer 200", () => {
+  const noObject: Array<[string, Record<string, unknown>]> = [
+    ["event.data null", { data: null }],
+    ["event.data absent", { data: undefined }],
+    ["data.object null", { data: { object: null } }],
+    ["data.object absent", { data: {} }],
+  ];
+
+  it.each(
+    ["customer.updated", "customer.subscription.deleted", "invoice.finalized"].flatMap((type) =>
+      noObject.map(([label, shape]) => [type, label, shape] as const),
+    ),
+  )("%s with %s reaches the default arm", async (type, _label, shape) => {
+    mockVerifyWebhookSignature.mockReturnValue({ id: "evt_test_12345678abcdef", type, ...shape });
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ received: true });
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expect(logMessages()).toContain("unhandled webhook event");
+  });
+
+  function withObject(event: ReturnType<typeof billingEvent>, patch: Record<string, unknown>) {
+    return { ...event, data: { object: { ...event.data.object, ...patch } } };
+  }
+
+  const subscription = subscriptionEvent("customer.subscription.updated", FOREIGN);
+  const invoice = preBasilInvoice("invoice.payment_failed");
+
+  it.each([
+    ["data.object.object absent on a stamped subscription", withObject(subscription, { object: undefined })],
+    ["metadata null", withObject(subscription, { metadata: null })],
+    ["metadata a string", withObject(subscription, { metadata: "samhenry" })],
+    ["metadata an array", withObject(subscription, { metadata: ["samhenry"] })],
+    ["a non-string stamp", withObject(subscription, { metadata: { site: 42 } })],
+    ["an invoice with parent null", withObject(invoice, { parent: null })],
+    ["an invoice with parent a string", withObject(invoice, { parent: "subscription_details" })],
+    ["an invoice with parent.subscription_details null", withObject(invoice, { parent: { subscription_details: null } })],
+    ["an invoice with parent.subscription_details a string", withObject(invoice, { parent: { subscription_details: "sub" } })],
+    ["an invoice with top-level subscription_details a string", withObject(invoice, { subscription_details: "sub" })],
+  ])("%s reaches its arm as today", async (_label, event) => {
+    armEveryWrite();
+    mockVerifyWebhookSignature.mockReturnValue(event);
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expectDunningWritten();
+  });
+});
+
+// ── Case 16 — the family boundary (F4) ──────────────────────────────────────
+
+describe("case 16 — stamped events outside the three families", () => {
+  it.each([
+    ["payment_intent.succeeded", "payment_intent"],
+    ["invoiceitem.created", "invoiceitem"],
+    ["invoice_payment.paid", "invoice_payment"],
+    ["customer_cash_balance_transaction.created", "customer_cash_balance_transaction"],
+    ["customer.source.created", "card"],
+  ])("%s is not filtered", async (type, objectType) => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      billingEvent(type, { object: objectType, id: "obj_test_1", customer: CUSTOMER_ID, metadata: FOREIGN }),
+    );
+    const res = await post();
+
+    expect(res.statusCode).toBe(200);
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expect(logMessages()).toContain("unhandled webhook event");
+  });
+});
+
+// ── Case 17 — the livemode drop still runs first (#8450 D10) ────────────────
+
+describe("case 17 — a foreign live-mode event under the test key", () => {
+  it("is dropped as livemode_mismatch, never marked seen, and never reaches the site filter", async () => {
+    mockVerifyWebhookSignature.mockReturnValue(
+      billingEvent(
+        "customer.subscription.updated",
+        { object: "subscription", id: SUBSCRIPTION_ID, customer: CUSTOMER_ID, status: "past_due", metadata: FOREIGN },
+        { livemode: true },
+      ),
+    );
+    const first = await post();
+
+    expect(first.statusCode).toBe(200);
+    expect(outcomeLogs("livemode_mismatch")).toHaveLength(1);
+    expect(foreignSiteLogs()).toHaveLength(0);
+
+    logCalls.length = 0;
+    await post();
+
+    expect(outcomeLogs("livemode_mismatch").length).toBeGreaterThan(0);
+    expect(logMessages()).not.toContain("duplicate stripe webhook event — idempotent short-circuit");
+    expect(foreignSiteLogs()).toHaveLength(0);
+    expectNoPrismaCall();
+  });
+});