create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/billing/__tests__/read.test.ts

@@ -0,0 +1,262 @@
+// oss: false
+/**
+ * @file read.test.ts
+ *
+ * GET /v1/billing — org-scoped read (spec §5.1 AC-1, AC-2).
+ *
+ * Fixture: two orgs. ORG_A has an active Stripe customer (billed, pro tier,
+ * 3 seats); ORG_B has never billed (no billingCustomerId, free tier). alice
+ * owns ORG_A (active workspace WS_A); bob owns ORG_B (active workspace WS_B);
+ * dave has a cookie session pointing at WS_A but NO membership row (revoked).
+ *
+ * Registration mirrors server.ts's tenantScope exactly: auth preHandler →
+ * nested scope { tenant guard → billingRoutes }.
+ */
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    workspace: { findUnique: jest.fn(), count: jest.fn() },
+    membership: { findUnique: jest.fn() },
+    organization: { findUnique: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../../lib/prisma.js";
+import { authPreHandlerPlugin } from "../../../middleware/auth.js";
+import { tenantPreHandlerPlugin } from "../../../middleware/tenant.js";
+import { billingRoutes } from "../index.js";
+
+const FRONTEND = "https://app.example.com";
+const FUTURE = new Date(Date.now() + 60 * 60 * 1000);
+
+const WS_A = "wksp_00000000-0000-7000-8000-0000000000aa";
+const WS_B = "wksp_00000000-0000-7000-8000-0000000000bb";
+const ORG_A = "org_00000000-0000-7000-8000-000000000aaa";
+const ORG_B = "org_00000000-0000-7000-8000-000000000bbb";
+const CUS_A = "cus_test_00000000000000aaaa";
+
+// ── Fixture data ────────────────────────────────────────────────────────────
+
+const WORKSPACES = [
+  { id: WS_A, organizationId: ORG_A },
+  { id: WS_B, organizationId: ORG_B },
+];
+
+const MEMBERSHIPS = [
+  { organizationId: ORG_A, userId: "alice", role: "owner" },
+  { organizationId: ORG_B, userId: "bob", role: "owner" },
+];
+
+const ORGANIZATIONS: Record<
+  string,
+  { tier: string; seatCount: number; billingCustomerId: string | null }
+> = {
+  [ORG_A]: { tier: "pro", seatCount: 3, billingCustomerId: CUS_A },
+  [ORG_B]: { tier: "free", seatCount: 1, billingCustomerId: null },
+};
+
+const SESSION_ROWS: Record<string, Record<string, unknown>> = {
+  cookie_alice: {
+    id: "sess_alice",
+    userId: "alice",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+  cookie_bob: {
+    id: "sess_bob",
+    userId: "bob",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_B,
+    activeWorkspaceId: WS_B,
+  },
+  cookie_dave: {
+    id: "sess_dave",
+    userId: "dave",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+};
+
+function installFixtureMocks(): void {
+  (prisma.session.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { token?: string } }) =>
+      Promise.resolve(where.token ? (SESSION_ROWS[where.token] ?? null) : null),
+  );
+
+  (prisma.workspace.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { id?: string } }) =>
+      Promise.resolve(WORKSPACES.find((w) => w.id === where.id) ?? null),
+  );
+  // Genuinely multi-tenant (2 workspaces) — the single-tenant default-resolution
+  // branch (count() === 1) must never fire.
+  (prisma.workspace.count as jest.Mock).mockResolvedValue(WORKSPACES.length);
+
+  (prisma.membership.findUnique as jest.Mock).mockImplementation(
+    ({
+      where,
+    }: {
+      where: {
+        organizationId_userId?: { organizationId: string; userId: string };
+      };
+    }) => {
+      const key = where.organizationId_userId;
+      if (!key) return Promise.resolve(null);
+      return Promise.resolve(
+        MEMBERSHIPS.find(
+          (m) =>
+            m.organizationId === key.organizationId && m.userId === key.userId,
+        ) ?? null,
+      );
+    },
+  );
+
+  (prisma.organization.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { id?: string } }) =>
+      Promise.resolve(
+        where.id && ORGANIZATIONS[where.id] ? ORGANIZATIONS[where.id] : null,
+      ),
+  );
+}
+
+// ── App assembly (mirrors server.ts registration order) ─────────────────────
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify();
+  app.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+  app.register(async (scope) => {
+    await scope.register(tenantPreHandlerPlugin);
+    await scope.register(billingRoutes);
+  });
+  await app.ready();
+  return app;
+}
+
+function cookieHeaders(token: string): Record<string, string> {
+  return { cookie: `better-auth.session_token=${token}` };
+}
+
+describe("GET /v1/billing", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    installFixtureMocks();
+    app = await buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  // AC-1 — read shape; hasBillingCustomer === (billingCustomerId != null).
+  it("returns the caller's own org billing shape for a billed org", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.ok).toBe(true);
+    expect(body.data).toEqual({
+      tier: "pro",
+      seatCount: 3,
+      hasBillingCustomer: true,
+      entitlements: {
+        features: expect.any(Array),
+        limits: {
+          static: { seats: 3, tier: "pro" },
+          metered: {},
+        },
+      },
+    });
+  });
+
+  // AC-1 — an un-billed org resolves hasBillingCustomer: false.
+  it("returns hasBillingCustomer: false for an org with no Stripe customer", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_bob"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.hasBillingCustomer).toBe(false);
+    expect(body.data.tier).toBe("free");
+    expect(body.data.seatCount).toBe(1);
+  });
+
+  // AC-1 / 5.2 — the raw Stripe customer id NEVER crosses the API boundary.
+  it("never returns the raw billingCustomerId in the response body", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.body).not.toContain(CUS_A);
+    expect(res.json().data).not.toHaveProperty("billingCustomerId");
+  });
+
+  // AC-2 — org scope is derived from request.tenant ONLY (never a body/query/
+  // param org id); the org queried is exactly the caller's own resolved org.
+  it("reads the org from request.tenant only — never any other org", async () => {
+    await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(prisma.organization.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: ORG_A } }),
+    );
+    expect(prisma.organization.findUnique).not.toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: ORG_B } }),
+    );
+  });
+
+  // AC-2 — a caller with no resolvable org membership is denied by the
+  // preHandler; the handler (and the org query) never runs.
+  it("denies a caller with revoked membership before any billing query runs", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_dave"),
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+  });
+
+  // AC-2 — unauthenticated → 401, no billing query runs.
+  it("returns 401 without a session, no billing query runs", async () => {
+    const res = await app.inject({ method: "GET", url: "/v1/billing" });
+
+    expect(res.statusCode).toBe(401);
+    expect(prisma.organization.findUnique).not.toHaveBeenCalled();
+  });
+
+  // Grant path works for the other tenant too — each caller sees only its
+  // own org's data.
+  it("the other org's owner reads its own org, not the first org's", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing",
+      headers: cookieHeaders("cookie_bob"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.tier).toBe("free");
+    expect(prisma.organization.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: ORG_B } }),
+    );
+  });
+});

package/templates/apps/api/src/routes/billing/__tests__/usage.test.ts

@@ -0,0 +1,436 @@
+// oss: false
+/**
+ * @file usage.test.ts
+ *
+ * GET /v1/billing/usage — org-scoped usage read (#3717, spec §5.1).
+ *
+ * The two P2/P3.S1 read services (`aggregateUsagePeriod`, `getCreditStatus`)
+ * are mocked at the module boundary — this route test proves ORG SCOPE,
+ * CLIENT-SAFE SHAPE, and ERROR MAPPING, not the aggregation math (that is
+ * #3714's / P3.S1's own tests). The prisma mock feeds only the auth + tenant
+ * preHandlers, whose fixture mirrors read.test.ts exactly (two orgs; alice
+ * owns ORG_A, bob owns ORG_B, dave has a revoked membership).
+ */
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    workspace: { findUnique: jest.fn(), count: jest.fn() },
+    membership: { findUnique: jest.fn() },
+    organization: { findUnique: jest.fn() },
+  },
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/usage-aggregation.js", () => ({
+  aggregateUsagePeriod: jest.fn(),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/usage-credits.js", () => ({
+  getCreditStatus: jest.fn(),
+}));
+
+import { prisma } from "../../../lib/prisma.js";
+import { authPreHandlerPlugin } from "../../../middleware/auth.js";
+import { tenantPreHandlerPlugin } from "../../../middleware/tenant.js";
+import { aggregateUsagePeriod } from "../../../services/usage-aggregation.js";
+import { getCreditStatus } from "../../../services/usage-credits.js";
+import { billingRoutes } from "../index.js";
+
+const FRONTEND = "https://app.example.com";
+const FUTURE = new Date(Date.now() + 60 * 60 * 1000);
+
+const WS_A = "wksp_00000000-0000-7000-8000-0000000000aa";
+const WS_B = "wksp_00000000-0000-7000-8000-0000000000bb";
+const ORG_A = "org_00000000-0000-7000-8000-000000000aaa";
+const ORG_B = "org_00000000-0000-7000-8000-000000000bbb";
+// A Stripe-shaped id that must NEVER appear in a usage response body.
+const CUS_A = "cus_test_00000000000000aaaa";
+
+// ── Fixture data (mirrors read.test.ts's auth fixture) ──────────────────────
+
+const WORKSPACES = [
+  { id: WS_A, organizationId: ORG_A },
+  { id: WS_B, organizationId: ORG_B },
+];
+
+const MEMBERSHIPS = [
+  { organizationId: ORG_A, userId: "alice", role: "owner" },
+  // erin is an ADMIN of ORG_A and carol is a plain MEMBER of ORG_A — the role
+  // fixtures for the #3819 role gate (mirrors portal.test.ts's #3766 fixtures).
+  { organizationId: ORG_A, userId: "erin", role: "admin" },
+  { organizationId: ORG_A, userId: "carol", role: "member" },
+  { organizationId: ORG_B, userId: "bob", role: "owner" },
+];
+
+const SESSION_ROWS: Record<string, Record<string, unknown>> = {
+  cookie_alice: {
+    id: "sess_alice",
+    userId: "alice",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+  cookie_bob: {
+    id: "sess_bob",
+    userId: "bob",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_B,
+    activeWorkspaceId: WS_B,
+  },
+  cookie_dave: {
+    id: "sess_dave",
+    userId: "dave",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+  cookie_erin: {
+    id: "sess_erin",
+    userId: "erin",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+  cookie_carol: {
+    id: "sess_carol",
+    userId: "carol",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_A,
+    activeWorkspaceId: WS_A,
+  },
+};
+
+// Client-safe totals (never a Stripe id) — the aggregation math itself is
+// #3714's concern; here the mock returns a fixed, safe shape.
+const TOTALS_A = {
+  totalProviderCost: 120,
+  totalMarkupAmount: 40,
+  totalBilledAmount: 160,
+  totalTokens: 5000,
+  eventCount: 12,
+  includedCents: 0,
+  creditBalanceCents: 0,
+  onDemandCents: 0,
+};
+
+const CREDIT_A = {
+  ok: true as const,
+  includedRemaining: 8000,
+  creditBalance: 2500,
+  effectiveRemaining: 10500,
+};
+
+function installFixtureMocks(): void {
+  (prisma.session.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { token?: string } }) =>
+      Promise.resolve(where.token ? (SESSION_ROWS[where.token] ?? null) : null),
+  );
+
+  (prisma.workspace.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { id?: string } }) =>
+      Promise.resolve(WORKSPACES.find((w) => w.id === where.id) ?? null),
+  );
+  // Genuinely multi-tenant (2 workspaces) — the single-tenant default branch
+  // (count() === 1) must never fire.
+  (prisma.workspace.count as jest.Mock).mockResolvedValue(WORKSPACES.length);
+
+  (prisma.membership.findUnique as jest.Mock).mockImplementation(
+    ({
+      where,
+    }: {
+      where: {
+        organizationId_userId?: { organizationId: string; userId: string };
+      };
+    }) => {
+      const key = where.organizationId_userId;
+      if (!key) return Promise.resolve(null);
+      return Promise.resolve(
+        MEMBERSHIPS.find(
+          (m) =>
+            m.organizationId === key.organizationId && m.userId === key.userId,
+        ) ?? null,
+      );
+    },
+  );
+
+  // Default service returns — a resolved-org success. Individual tests override.
+  (aggregateUsagePeriod as jest.Mock).mockResolvedValue({
+    ok: true,
+    reportId: "rpt_test",
+    totals: TOTALS_A,
+  });
+  (getCreditStatus as jest.Mock).mockResolvedValue(CREDIT_A);
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify();
+  app.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+  app.register(async (scope) => {
+    await scope.register(tenantPreHandlerPlugin);
+    await scope.register(billingRoutes);
+  });
+  await app.ready();
+  return app;
+}
+
+function cookieHeaders(token: string): Record<string, string> {
+  return { cookie: `better-auth.session_token=${token}` };
+}
+
+describe("GET /v1/billing/usage", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    installFixtureMocks();
+    app = await buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  // AC-1 — returns the caller-org report summary + credit status.
+  it("returns the usage report summary + credit status for the caller's org", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.ok).toBe(true);
+    expect(body.data.usage).toEqual(TOTALS_A);
+    expect(body.data.credit).toEqual({
+      includedRemaining: 8000,
+      creditBalance: 2500,
+      effectiveRemaining: 10500,
+    });
+  });
+
+  // AC-1 / D3 — no Stripe id / billingCustomerId ever crosses the boundary.
+  it("never returns a Stripe id or billingCustomerId in the body", async () => {
+    // Even if the credit service somehow returned an id-shaped extra, the
+    // route projects an explicit client-safe shape.
+    (getCreditStatus as jest.Mock).mockResolvedValue({
+      ...CREDIT_A,
+      billingCustomerId: CUS_A,
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body).not.toContain(CUS_A);
+    expect(res.body).not.toContain("billingCustomerId");
+    expect(res.json().data).not.toHaveProperty("billingCustomerId");
+    expect(res.json().data.credit).not.toHaveProperty("billingCustomerId");
+  });
+
+  // AC-2 (AC-UB-10) — org derived from request.tenant ONLY; the caller's own
+  // org is the only one queried; never any other org.
+  it("reads the org from request.tenant only — never any other org", async () => {
+    await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(aggregateUsagePeriod).toHaveBeenCalledWith(ORG_A, expect.any(Date));
+    expect(getCreditStatus).toHaveBeenCalledWith(ORG_A);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalledWith(
+      ORG_B,
+      expect.anything(),
+    );
+    expect(getCreditStatus).not.toHaveBeenCalledWith(ORG_B);
+  });
+
+  // AC-2 — a caller with revoked membership is denied by the preHandler; no
+  // usage/credit read runs.
+  it("denies a caller with revoked membership before any usage read runs", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_dave"),
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalled();
+    expect(getCreditStatus).not.toHaveBeenCalled();
+  });
+
+  // ── #3819 role gate ─────────────────────────────────────────────────────
+
+  // A plain org MEMBER must be refused: the usage read exposes the org's actual
+  // spend + credit balance, and membership alone is not authorization (same
+  // defect class as #3766). The load-bearing assertions are on the MOCKS — the
+  // aggregation/credit services were never exercised — not just the 403.
+  it("returns 403 for a plain member, before any usage/credit read runs", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_carol"),
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().error.code).toBe("forbidden");
+    // The capability was never exercised — the financial detail was never read.
+    expect(aggregateUsagePeriod).not.toHaveBeenCalled();
+    expect(getCreditStatus).not.toHaveBeenCalled();
+  });
+
+  // The refusal must not leak any org spend / credit detail in any form.
+  it("leaks no usage or credit detail in the member refusal", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_carol"),
+    });
+
+    expect(res.body).not.toContain(String(TOTALS_A.totalBilledAmount));
+    expect(res.body).not.toContain(String(CREDIT_A.creditBalance));
+    expect(res.json().data).toBeUndefined();
+  });
+
+  // owner (alice) is covered by the happy path above; admin must also pass.
+  it("allows an admin to read the usage projection", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_erin"),
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().ok).toBe(true);
+    expect(res.json().data.usage).toEqual(TOTALS_A);
+    expect(aggregateUsagePeriod).toHaveBeenCalledWith(ORG_A, expect.any(Date));
+  });
+
+  // Fail-closed: an unrecognized role is refused rather than falling through
+  // into the privileged read. Proves the allow-list is default-deny, so a role
+  // added to `MembershipRole` later cannot silently gain usage access.
+  it("denies an unrecognized role (default-deny allow-list)", async () => {
+    (prisma.membership.findUnique as jest.Mock).mockResolvedValue({
+      role: "billing_viewer",
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalled();
+    expect(getCreditStatus).not.toHaveBeenCalled();
+  });
+
+  // AC-2 — unauthenticated → 401, no read runs.
+  it("returns 401 without a session, no usage read runs", async () => {
+    const res = await app.inject({ method: "GET", url: "/v1/billing/usage" });
+
+    expect(res.statusCode).toBe(401);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalled();
+    expect(getCreditStatus).not.toHaveBeenCalled();
+  });
+
+  // AC-2 — the other org's owner reads only its own org.
+  it("the other org's owner reads its own org, not the first org's", async () => {
+    await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_bob"),
+    });
+
+    expect(aggregateUsagePeriod).toHaveBeenCalledWith(ORG_B, expect.any(Date));
+    expect(getCreditStatus).toHaveBeenCalledWith(ORG_B);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalledWith(
+      ORG_A,
+      expect.anything(),
+    );
+  });
+
+  // AC-4 — the optional ?period= selector reads that period, org-scoped.
+  it("passes the ?period= selector through to the aggregation read, org-scoped", async () => {
+    await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage?period=2026-05-01T00:00:00.000Z",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    const call = (aggregateUsagePeriod as jest.Mock).mock.calls[0];
+    expect(call[0]).toBe(ORG_A);
+    expect(call[1]).toBeInstanceOf(Date);
+    expect((call[1] as Date).toISOString()).toBe("2026-05-01T00:00:00.000Z");
+  });
+
+  // AC-4 — no ?period= defaults to the current period (a valid Date).
+  it("defaults to the current period when no ?period= is given", async () => {
+    await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    const call = (aggregateUsagePeriod as jest.Mock).mock.calls[0];
+    expect(call[1]).toBeInstanceOf(Date);
+    expect(Number.isFinite((call[1] as Date).getTime())).toBe(true);
+  });
+
+  // AC-4 — a malformed ?period= is a 400, before any read runs.
+  it("returns 400 for a malformed ?period= and does not read usage", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage?period=not-a-date",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(aggregateUsagePeriod).not.toHaveBeenCalled();
+  });
+
+  // Error mapping — a usage-read failure is a 500 with NO org id / detail leak.
+  it("maps a usage read failure to 500 without leaking any id or detail", async () => {
+    (aggregateUsagePeriod as jest.Mock).mockResolvedValue({
+      ok: false,
+      error: { kind: "read_failed", message: "usage event read failed" },
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.body).not.toContain(ORG_A);
+    expect(res.json().ok).toBe(false);
+  });
+
+  // Error mapping — a credit-status failure is a 500 with no id / detail leak.
+  it("maps a credit-status failure to 500 without leaking any id or detail", async () => {
+    (getCreditStatus as jest.Mock).mockResolvedValue({
+      ok: false,
+      error: { kind: "db_error", message: "credit operation failed" },
+    });
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/billing/usage",
+      headers: cookieHeaders("cookie_alice"),
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.body).not.toContain(ORG_A);
+    expect(res.json().ok).toBe(false);
+  });
+});