@bugmole/cli 0.4.0

package/src/registry-worker/billing/paypal.test.ts

@@ -0,0 +1,466 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Env } from "../core.js";
+import { call, createTestEnv, seedPlan, seedProject } from "../testing/harness.js";
+import { recordUsage } from "./ledger.js";
+import { changeKind, closeUsagePeriods, chaseOverdueInvoices, syncWorkspaceBilling, CANCEL_REASON, SCHEDULED_REASON, UPGRADE_REASON } from "./subscriptions.js";
+import { freePlan } from "./entitlements.js";
+import { proRataCents, toCents } from "./provider.js";
+import { canSpend } from "./ledger.js";
+
+const DAY = 86_400_000;
+const PLAN_IDS = { PAYPAL_PLAN_TEAM_MONTH: "P-TEAM-M", PAYPAL_PLAN_TEAM_YEAR: "P-TEAM-Y", PAYPAL_PLAN_BUSINESS_MONTH: "P-BIZ-M", PAYPAL_PLAN_BUSINESS_YEAR: "P-BIZ-Y" };
+const PRICES: Record<string, string> = { "P-TEAM-M": "249.00", "P-TEAM-Y": "2388.00", "P-BIZ-M": "899.00", "P-BIZ-Y": "8628.00" };
+
+// --- A scripted PayPal ---------------------------------------------------------------------------
+
+type Sub = Record<string, any>;
+
+function fakePayPal() {
+  const state = {
+    subscriptions: new Map<string, Sub>(),
+    sales: new Map<string, Array<{ id: string; status: string; time: string; amount: string }>>(),
+    invoices: new Map<string, { status: string; number: string; body: any }>(),
+    verification: "SUCCESS" as string,
+    verifyDown: false,
+    refundFails: false,
+    calls: [] as Array<{ method: string; path: string; body: any }>,
+    next: 1,
+  };
+  const doFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = new Request(input, init);
+    const url = new URL(request.url);
+    const path = url.pathname;
+    const raw = request.method === "GET" || path === "/v1/oauth2/token" ? "" : await request.text();
+    const body = raw ? JSON.parse(raw) : null;
+    state.calls.push({ method: request.method, path, body });
+    if (path === "/v1/oauth2/token") return Response.json({ access_token: "token" });
+    if (path === "/v1/notifications/verify-webhook-signature") {
+      if (state.verifyDown) return new Response("down", { status: 500 });
+      return Response.json({ verification_status: state.verification });
+    }
+    if (path === "/v1/billing/subscriptions" && request.method === "POST") {
+      const id = `I-${state.next++}`;
+      state.subscriptions.set(id, { id, status: "APPROVAL_PENDING", custom_id: body.custom_id, plan_id: body.plan_id, start_time: body.start_time ?? new Date().toISOString() });
+      return Response.json({ id, links: [{ rel: "approve", href: `https://paypal.test/approve/${id}` }] }, { status: 201 });
+    }
+    let match = path.match(/^\/v1\/billing\/subscriptions\/([^/]+)\/transactions$/);
+    if (match) return Response.json({ transactions: (state.sales.get(match[1]) ?? []).map((sale) => ({ ...sale, amount_with_breakdown: { gross_amount: { value: sale.amount, currency_code: "USD" } } })) });
+    match = path.match(/^\/v1\/billing\/subscriptions\/([^/]+)\/cancel$/);
+    if (match) {
+      const sub = state.subscriptions.get(match[1]);
+      if (sub) Object.assign(sub, { status: "CANCELLED", status_change_note: body.reason, status_update_time: new Date().toISOString() });
+      return new Response(null, { status: 204 });
+    }
+    match = path.match(/^\/v1\/billing\/subscriptions\/([^/]+)$/);
+    if (match) {
+      const sub = state.subscriptions.get(match[1]);
+      return sub ? Response.json(sub) : Response.json({ name: "RESOURCE_NOT_FOUND" }, { status: 404 });
+    }
+    match = path.match(/^\/v1\/payments\/sale\/([^/]+)\/refund$/);
+    if (match) {
+      if (state.refundFails) return Response.json({ name: "UNPROCESSABLE_ENTITY", details: [{ issue: "TRANSACTION_REFUSED" }] }, { status: 422 });
+      return Response.json({ id: `REFUND-${match[1]}`, state: "completed" }, { status: 201 });
+    }
+    if (path === "/v2/invoicing/invoices" && request.method === "POST") {
+      const id = `INV2-${state.next++}`;
+      state.invoices.set(id, { status: "DRAFT", number: body.detail.invoice_number, body });
+      return Response.json({ id }, { status: 201 });
+    }
+    match = path.match(/^\/v2\/invoicing\/invoices\/([^/]+)\/send$/);
+    if (match) {
+      state.invoices.get(match[1])!.status = "SENT";
+      return Response.json({ href: `https://paypal.test/invoice/${match[1]}` });
+    }
+    match = path.match(/^\/v2\/invoicing\/invoices\/([^/]+)$/);
+    if (match) {
+      const invoice = state.invoices.get(match[1]);
+      return invoice ? Response.json({ id: match[1], status: invoice.status }) : new Response("", { status: 404 });
+    }
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+
+  /** The subscriber approves; PayPal activates and (unless it starts later) takes the first payment. */
+  const approve = (id: string, { at = Date.now(), pay = true, customId }: { at?: number; pay?: boolean; customId?: string } = {}) => {
+    const sub = state.subscriptions.get(id)!;
+    // A subscription that starts right away starts when it's approved; a scheduled one keeps its start.
+    const scheduled = Date.parse(sub.start_time) > Date.now() + 1000;
+    const start = scheduled ? Date.parse(sub.start_time) : at;
+    sub.start_time = new Date(start).toISOString();
+    const yearly = String(sub.plan_id).endsWith("-Y");
+    const next = new Date(start);
+    if (yearly) next.setUTCFullYear(next.getUTCFullYear() + 1); else next.setUTCMonth(next.getUTCMonth() + 1);
+    Object.assign(sub, { status: "ACTIVE", ...(customId ? { custom_id: customId } : {}), billing_info: { next_billing_time: next.toISOString() } });
+    if (pay && start <= Date.now() + 1000) paySale(id, new Date(at).toISOString());
+  };
+  const paySale = (id: string, time: string, amount = PRICES[state.subscriptions.get(id)!.plan_id]) => {
+    const list = state.sales.get(id) ?? [];
+    const saleId = `SALE-${id}-${list.length + 1}`;
+    list.push({ id: saleId, status: "COMPLETED", time, amount });
+    state.sales.set(id, list);
+    return saleId;
+  };
+  return { state, doFetch, approve, paySale };
+}
+
+function billingEnv(paypal: ReturnType<typeof fakePayPal>, extra: Record<string, unknown> = {}) {
+  return createTestEnv({
+    FEATURE_BILLING: "on",
+    FEATURE_ENTITLEMENTS: "on",
+    PAYPAL_CLIENT_ID: "client",
+    PAYPAL_CLIENT_SECRET: "secret",
+    PAYPAL_WEBHOOK_ID: "WH-1",
+    PAYPAL_FETCH: paypal.doFetch,
+    DASHBOARD_URL: "https://dash.test",
+    ...PLAN_IDS,
+    ...extra,
+  } as Partial<Env>);
+}
+
+const ownerHeaders = { "x-aegis-email": "owner@acme.test", "x-aegis-email-verified": "true" };
+
+async function paidWorkspace(paypal: ReturnType<typeof fakePayPal>, plan = "team", interval = "month") {
+  const setup = billingEnv(paypal);
+  const project = await seedProject(setup.env);
+  // Remember the owner's email for receipts.
+  await call(setup.env, "GET", "/api/workspaces", { as: project.owner, headers: ownerHeaders });
+  const started = await call(setup.env, "POST", `/api/workspaces/${project.workspaceId}/billing/checkout`, { as: project.owner, body: { plan, interval } });
+  assert.equal(started.status, 201, JSON.stringify(started.json));
+  const subscriptionId = started.json.approveUrl.split("/").pop();
+  return { ...setup, ...project, checkoutId: started.json.checkoutId as string, subscriptionId: subscriptionId as string };
+}
+
+function webhook(env: Env, type: string, resource: Record<string, unknown>, id = `WH-${crypto.randomUUID()}`) {
+  return call(env, "POST", "/api/billing/webhooks/paypal", {
+    body: { id, event_type: type, resource },
+    headers: {
+      "paypal-transmission-id": "t", "paypal-transmission-time": "now", "paypal-cert-url": "https://paypal.test/cert",
+      "paypal-auth-algo": "SHA256withRSA", "paypal-transmission-sig": "sig",
+    },
+  });
+}
+
+// --- Pure helpers --------------------------------------------------------------------------------
+
+test("money and plan-change arithmetic", () => {
+  assert.equal(toCents("249.00"), 24900);
+  assert.equal(toCents("0.5"), 50);
+  assert.equal(toCents("12"), 1200);
+  assert.ok(Number.isNaN(toCents("1e3")));
+  const start = "2026-09-01T00:00:00.000Z";
+  const end = "2026-10-01T00:00:00.000Z";
+  assert.equal(proRataCents(24900, start, end, new Date("2026-09-11T00:00:00.000Z")), 16600);
+  assert.equal(proRataCents(24900, start, end, new Date("2026-10-02T00:00:00.000Z")), 0);
+  const team = { ...freePlan("w"), plan: "team" as const, interval: "month" as const };
+  assert.equal(changeKind(freePlan("w"), "team", "month"), "new");
+  assert.equal(changeKind(team, "team", "month"), "same");
+  assert.equal(changeKind(team, "business", "month"), "upgrade");
+  assert.equal(changeKind(team, "team", "year"), "upgrade");
+  assert.equal(changeKind({ ...team, plan: "business" }, "team", "year"), "downgrade");
+  assert.equal(changeKind({ ...team, interval: "year" }, "team", "month"), "downgrade");
+});
+
+// --- Checkout ------------------------------------------------------------------------------------
+
+test("a checkout activates the plan only once PayPal says it's paid, and records the payment once", async () => {
+  const paypal = fakePayPal();
+  const { env, workspaceId, owner, checkoutId, subscriptionId, email } = await paidWorkspace(paypal);
+  const created = paypal.state.subscriptions.get(subscriptionId)!;
+  assert.equal(created.custom_id, checkoutId);
+  assert.equal(created.plan_id, "P-TEAM-M");
+  const complete = () => call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/${checkoutId}/complete`, { as: owner });
+
+  assert.equal((await complete()).json.code, "payment_not_completed", "not approved yet");
+  paypal.approve(subscriptionId, { pay: false });
+  assert.equal((await complete()).json.code, "payment_pending", "approved, but PayPal hasn't posted the payment");
+  paypal.paySale(subscriptionId, new Date().toISOString());
+  const done = await complete();
+  assert.equal(done.status, 200, JSON.stringify(done.json));
+  assert.equal(done.json.plan.id, "team");
+  assert.equal((await complete()).status, 200, "repeatable");
+
+  const billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.equal(billing.json.subscription.plan, "team");
+  assert.equal(billing.json.subscription.renews, true);
+  assert.equal(billing.json.invoices.length, 1);
+  assert.equal(billing.json.invoices[0].totalCents, 24900);
+  const usage = await call(env, "GET", `/api/workspaces/${workspaceId}/usage`, { as: owner });
+  assert.equal(usage.json.limits.cloudMinutes, 3000);
+  assert.equal(email.sent.filter((message) => /Receipt/.test(message.subject)).length, 1);
+  assert.equal(email.sent[0].to[0].email, "owner@acme.test");
+});
+
+test("someone else's subscription can't pay for a checkout, and only billing managers can buy", async () => {
+  const paypal = fakePayPal();
+  const { env, workspaceId, owner, checkoutId, subscriptionId } = await paidWorkspace(paypal);
+  paypal.approve(subscriptionId, { customId: "chk_someone_else" });
+  const attempt = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/${checkoutId}/complete`, { as: owner });
+  assert.equal(attempt.status, 402);
+  assert.equal((await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/chk_nope/complete`, { as: owner })).status, 404);
+
+  const invited = await call(env, "POST", `/api/workspaces/${workspaceId}/invitations`, { as: owner, body: { email: "dev@acme.test", role: "member" } });
+  const token = invited.json.invitation.acceptUrl.split("/invite/")[1];
+  await call(env, "POST", `/api/invitations/${token}/accept`, { as: "user_dev", headers: { "x-aegis-email": "dev@acme.test", "x-aegis-email-verified": "true" } });
+  const member = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout`, { as: "user_dev", body: { plan: "team", interval: "month" } });
+  assert.equal(member.status, 403);
+  const view = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: "user_dev" });
+  assert.equal(view.json.canManage, false);
+  assert.deepEqual(view.json.invoices, [], "members don't see invoices");
+});
+
+test("checkout is closed until billing is switched on and PayPal is configured", async () => {
+  const paypal = fakePayPal();
+  const off = billingEnv(paypal, { FEATURE_BILLING: "off" });
+  const project = await seedProject(off.env);
+  const blocked = await call(off.env, "POST", `/api/workspaces/${project.workspaceId}/billing/checkout`, { as: project.owner, body: { plan: "team", interval: "month" } });
+  assert.equal(blocked.status, 503);
+  const unconfigured = billingEnv(paypal, { PAYPAL_PLAN_BUSINESS_YEAR: "" });
+  const other = await seedProject(unconfigured.env);
+  const offers = await call(unconfigured.env, "GET", `/api/workspaces/${other.workspaceId}/billing`, { as: other.owner });
+  const businessYear = offers.json.offers.find((offer: { plan: string; interval: string }) => offer.plan === "business" && offer.interval === "year");
+  assert.equal(businessYear.available, false);
+  assert.equal(businessYear.priceCents, 862800);
+  const refused = await call(unconfigured.env, "POST", `/api/workspaces/${other.workspaceId}/billing/checkout`, { as: other.owner, body: { plan: "business", interval: "year" } });
+  assert.equal(refused.json.code, "billing_unavailable");
+});
+
+// --- Webhooks ------------------------------------------------------------------------------------
+
+test("a webhook finishes a checkout whose return page never came back, once", async () => {
+  const paypal = fakePayPal();
+  const { env, workspaceId, owner, subscriptionId } = await paidWorkspace(paypal);
+  paypal.approve(subscriptionId);
+  const sale = paypal.state.sales.get(subscriptionId)![0].id;
+  const first = await webhook(env, "PAYMENT.SALE.COMPLETED", { id: sale, billing_agreement_id: subscriptionId }, "WH-A");
+  assert.equal(first.status, 200);
+  const again = await webhook(env, "PAYMENT.SALE.COMPLETED", { id: sale, billing_agreement_id: subscriptionId }, "WH-A");
+  assert.equal(again.json.duplicate, true);
+  const billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.equal(billing.json.subscription.plan, "team");
+  assert.equal(billing.json.invoices.length, 1);
+
+  paypal.state.verification = "FAILURE";
+  assert.equal((await webhook(env, "BILLING.SUBSCRIPTION.CANCELLED", { id: subscriptionId })).status, 400);
+  paypal.state.verifyDown = true;
+  assert.equal((await webhook(env, "BILLING.SUBSCRIPTION.CANCELLED", { id: subscriptionId })).status, 503, "PayPal retries");
+  assert.equal((await call(env, "POST", "/api/billing/webhooks/stripe", { body: {} })).status, 404);
+});
+
+// --- Upgrades and downgrades ---------------------------------------------------------------------
+
+async function activeTeam(paypal: ReturnType<typeof fakePayPal>, paidDaysAgo = 10) {
+  const setup = await paidWorkspace(paypal);
+  paypal.approve(setup.subscriptionId, { at: Date.now() - paidDaysAgo * DAY });
+  const done = await call(setup.env, "POST", `/api/workspaces/${setup.workspaceId}/billing/checkout/${setup.checkoutId}/complete`, { as: setup.owner });
+  assert.equal(done.status, 200, JSON.stringify(done.json));
+  return setup;
+}
+
+test("an upgrade starts now, bills the old plan's usage, cancels the old subscription and refunds its unused part", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, owner, subscriptionId: teamSub, email } = await activeTeam(paypal);
+  const team = JSON.parse((db.db.prepare("SELECT last_payment_json AS payment FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).payment);
+  team.start = team.periodStart;
+  team.end = team.periodEnd;
+  await recordUsage(env, { workspaceId, kind: "browser_minute", quantity: 3_100, source: "cloud_run", idempotencyKey: "big-run" });
+
+  const started = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout`, { as: owner, body: { plan: "business", interval: "month" } });
+  assert.equal(started.json.effective, "now");
+  const bizSub = started.json.approveUrl.split("/").pop();
+  paypal.approve(bizSub);
+  const done = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/${started.json.checkoutId}/complete`, { as: owner });
+  assert.equal(done.json.plan.id, "business");
+
+  assert.equal(paypal.state.subscriptions.get(teamSub)!.status, "CANCELLED");
+  assert.equal(paypal.state.subscriptions.get(teamSub)!.status_change_note, UPGRADE_REASON);
+  const refund = paypal.state.calls.find((c) => c.path.endsWith("/refund"))!;
+  const expected = Math.floor((24900 * (Date.parse(team.end) - Date.now())) / (Date.parse(team.end) - Date.parse(team.start)));
+  assert.ok(Math.abs(Math.round(Number(refund.body.amount.total) * 100) - expected) <= 1, `refund ${refund.body.amount.total} ≈ ${expected / 100}`);
+  assert.ok(email.sent.some((message) => /Refund/.test(message.subject)));
+
+  const invoice = [...paypal.state.invoices.values()][0];
+  assert.ok(invoice, "the Team period's extra minutes were invoiced");
+  assert.equal(invoice.body.items[0].quantity, "100");
+  assert.equal(invoice.body.items[0].unit_amount.value, "0.04");
+  assert.equal(invoice.status, "SENT");
+
+  // The daily retry finds nothing left to do.
+  const refunds = paypal.state.calls.filter((c) => c.path.endsWith("/refund")).length;
+  await syncWorkspaceBilling(env, workspaceId);
+  assert.equal(paypal.state.calls.filter((c) => c.path.endsWith("/refund")).length, refunds);
+});
+
+test("a refused refund is recorded for a person to handle; the upgrade still goes through", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, owner } = await activeTeam(paypal);
+  paypal.state.refundFails = true;
+  const started = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout`, { as: owner, body: { plan: "team", interval: "year" } });
+  paypal.approve(started.json.approveUrl.split("/").pop());
+  const done = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/${started.json.checkoutId}/complete`, { as: owner });
+  assert.equal(done.json.plan.interval, "year");
+  const checkout = db.db.prepare("SELECT refund_json AS refund, settled_at AS settled FROM billing_checkouts WHERE id = ?").get(started.json.checkoutId) as any;
+  assert.equal(JSON.parse(checkout.refund).status, "failed");
+  assert.ok(checkout.settled);
+});
+
+test("a downgrade waits for the end of the paid period, then the new plan takes over", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, owner, subscriptionId: bizSub } = await (async () => {
+    const setup = await paidWorkspace(paypal, "business", "month");
+    paypal.approve(setup.subscriptionId, { at: Date.now() - 20 * DAY });
+    await call(setup.env, "POST", `/api/workspaces/${setup.workspaceId}/billing/checkout/${setup.checkoutId}/complete`, { as: setup.owner });
+    return setup;
+  })();
+  const periodEnd = (db.db.prepare("SELECT current_period_end AS end FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).end;
+
+  const started = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout`, { as: owner, body: { plan: "team", interval: "month" } });
+  assert.equal(started.json.effective, "period_end");
+  const teamSub = started.json.approveUrl.split("/").pop();
+  assert.equal(paypal.state.subscriptions.get(teamSub)!.start_time, new Date(Date.parse(periodEnd)).toISOString());
+  paypal.approve(teamSub);
+  const done = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/checkout/${started.json.checkoutId}/complete`, { as: owner });
+  assert.equal(done.json.status, "scheduled");
+  assert.equal(done.json.plan.id, "business", "still Business until the period ends");
+  assert.equal(paypal.state.subscriptions.get(bizSub)!.status_change_note, SCHEDULED_REASON);
+  const billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.deepEqual(billing.json.subscription.changesTo, { plan: "team", interval: "month" });
+
+  // The period ends and PayPal takes Team's first payment.
+  const after = new Date(Date.parse(periodEnd) + 60_000);
+  paypal.paySale(teamSub, after.toISOString());
+  await syncWorkspaceBilling(env, workspaceId, after);
+  const plan = db.db.prepare("SELECT plan, provider_subscription_id AS sub, status FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any;
+  assert.deepEqual({ ...plan }, { plan: "team", sub: teamSub, status: "active" });
+});
+
+// --- Cancellation, failed payments, read-only projects -------------------------------------------
+
+test("a cancelled plan runs to the end of its period, then extra projects become read-only", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, owner, subscriptionId, projectId } = await activeTeam(paypal);
+  for (const id of ["second", "third"]) {
+    const created = await call(env, "POST", "/api/projects/register", { as: owner, body: { id, name: id, workspaceId, environment: "staging", storageProvider: "r2" } });
+    assert.equal(created.status, 201);
+  }
+  const cancelled = await call(env, "POST", `/api/workspaces/${workspaceId}/billing/cancel`, { as: owner });
+  assert.equal(cancelled.status, 200);
+  assert.equal(paypal.state.subscriptions.get(subscriptionId)!.status_change_note, CANCEL_REASON);
+  // PayPal's own cancellation event for it changes nothing.
+  await webhook(env, "BILLING.SUBSCRIPTION.CANCELLED", { id: subscriptionId });
+  let billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.equal(billing.json.subscription.plan, "team");
+  assert.equal(billing.json.subscription.renews, false);
+
+  const end = (db.db.prepare("SELECT current_period_end AS end FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).end;
+  await syncWorkspaceBilling(env, workspaceId, new Date(Date.parse(end) + 1000));
+  billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.equal(billing.json.subscription, null);
+  const projects = await call(env, "GET", "/api/projects", { as: owner });
+  const locked = projects.json.projects.filter((project: { lockedAt: string | null }) => project.lockedAt).map((project: { id: string }) => project.id).sort();
+  assert.deepEqual(locked, ["second", "third"], "the oldest project stays writable");
+  await seedPlan(env, projectId, owner);
+  assert.equal((await call(env, "POST", "/api/projects/third/runs", { as: owner, body: { planId: "checkout", idempotencyKey: "x" } })).status, 403);
+  assert.equal((await call(env, "GET", "/api/projects/third/runs", { as: owner })).status, 200, "still readable");
+  assert.equal((await call(env, "POST", `/api/projects/${projectId}/runs`, { as: owner, body: { planId: "checkout", idempotencyKey: "y" } })).status, 201);
+});
+
+test("a failed renewal gives a week of grace, then pauses the cloud, then moves to Free", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, subscriptionId, email } = await activeTeam(paypal);
+  paypal.state.subscriptions.get(subscriptionId)!.status = "SUSPENDED";
+  const now = Date.now();
+  await syncWorkspaceBilling(env, workspaceId, new Date(now));
+  const row = db.db.prepare("SELECT status, grace_until AS grace FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any;
+  assert.equal(row.status, "past_due");
+  assert.ok(email.sent.some((message) => /didn't go through/.test(message.subject)));
+  assert.equal((await canSpend(env, workspaceId, "browser_minute", 1, new Date(now + DAY))).allowed, true, "grace");
+  const paused = await canSpend(env, workspaceId, "browser_minute", 1, new Date(now + 8 * DAY));
+  assert.equal(!paused.allowed && paused.reason, "suspended");
+
+  await syncWorkspaceBilling(env, workspaceId, new Date(now + 22 * DAY));
+  const after = db.db.prepare("SELECT status FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any;
+  assert.equal(after.status, "canceled");
+  assert.equal(paypal.state.subscriptions.get(subscriptionId)!.status, "CANCELLED");
+});
+
+test("paying the failed renewal restores the plan", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, subscriptionId } = await activeTeam(paypal, 31);
+  const sub = paypal.state.subscriptions.get(subscriptionId)!;
+  sub.status = "SUSPENDED";
+  await syncWorkspaceBilling(env, workspaceId);
+  sub.status = "ACTIVE";
+  const next = new Date(Date.parse(sub.billing_info.next_billing_time));
+  next.setUTCMonth(next.getUTCMonth() + 1);
+  sub.billing_info.next_billing_time = next.toISOString();
+  paypal.paySale(subscriptionId, new Date().toISOString());
+  await syncWorkspaceBilling(env, workspaceId);
+  const row = db.db.prepare("SELECT status, current_period_end AS end FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any;
+  assert.equal(row.status, "active");
+  assert.equal(row.end, next.toISOString());
+  assert.equal((db.db.prepare("SELECT COUNT(*) AS c FROM invoices WHERE workspace_id = ? AND kind = 'subscription'").get(workspaceId) as any).c, 2);
+});
+
+// --- Usage invoices ------------------------------------------------------------------------------
+
+test("each month's extra usage is invoiced once through PayPal, and an unpaid invoice pauses the cloud", async () => {
+  const paypal = fakePayPal();
+  const { env, db, workspaceId, owner } = await activeTeam(paypal, 40);
+  const anchor = (db.db.prepare("SELECT current_period_start AS start FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).start;
+  // Usage in the first (now closed) month.
+  const firstMonth = new Date(Date.parse(anchor) + DAY);
+  await recordUsage(env, { workspaceId, kind: "browser_minute", quantity: 3_250, source: "cloud_run", idempotencyKey: "m1", now: firstMonth });
+  await recordUsage(env, { workspaceId, kind: "ai_credit", quantity: 1_600, source: "ai", idempotencyKey: "a1", now: firstMonth });
+
+  assert.equal(await closeUsagePeriods(env), 1);
+  assert.equal(await closeUsagePeriods(env), 1, "found again, not sent again");
+  assert.equal(paypal.state.invoices.size, 1);
+  const sent = [...paypal.state.invoices.values()][0];
+  assert.deepEqual(sent.body.items.map((item: any) => [item.quantity, item.unit_amount.value]), [["250", "0.04"], ["100", "0.01"]]);
+  assert.equal(sent.body.primary_recipients[0].billing_info.email_address, "owner@acme.test");
+
+  const billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  const usageInvoice = billing.json.invoices.find((invoice: { kind: string }) => invoice.kind === "usage");
+  assert.equal(usageInvoice.totalCents, 1100);
+  assert.equal(usageInvoice.status, "open");
+  assert.match(usageInvoice.payUrl, /paypal\.test\/invoice/);
+
+  // Unpaid three weeks later: the cloud pauses.
+  await chaseOverdueInvoices(env, new Date(Date.now() + 23 * DAY));
+  assert.equal((db.db.prepare("SELECT status FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).status, "past_due");
+
+  // Paid: PayPal tells us, and the pause lifts.
+  const [invoiceId] = [...paypal.state.invoices.keys()];
+  paypal.state.invoices.get(invoiceId)!.status = "PAID";
+  db.db.prepare("UPDATE invoices SET due_at = ? WHERE id = ?").run(new Date(Date.now() + DAY).toISOString(), usageInvoice.id);
+  await webhook(env, "INVOICING.INVOICE.PAID", { invoice: { id: invoiceId } });
+  const paid = await call(env, "GET", `/api/workspaces/${workspaceId}/invoices/${usageInvoice.id}`, { as: owner });
+  assert.equal(paid.json.invoice.status, "paid");
+  assert.equal(paid.json.seller.name, "The AI Inc.");
+  assert.equal(paid.json.invoice.lines.length, 2);
+  assert.equal((db.db.prepare("SELECT status FROM workspace_plans WHERE workspace_id = ?").get(workspaceId) as any).status, "active");
+});
+
+test("a month within the allowance isn't invoiced", async () => {
+  const paypal = fakePayPal();
+  const { env, workspaceId } = await activeTeam(paypal, 40);
+  assert.equal(await closeUsagePeriods(env), 0);
+  assert.equal(paypal.state.invoices.size, 0);
+  const listed = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: "user_owner" });
+  assert.equal(listed.json.invoices.filter((invoice: { kind: string }) => invoice.kind === "usage").length, 0);
+});
+
+test("the billing contact is saved for receipts and validated", async () => {
+  const paypal = fakePayPal();
+  const { env, workspaceId, owner } = await activeTeam(paypal);
+  assert.equal((await call(env, "PUT", `/api/workspaces/${workspaceId}/billing/contact`, { as: owner, body: { email: "not-an-email" } })).status, 422);
+  const saved = await call(env, "PUT", `/api/workspaces/${workspaceId}/billing/contact`, {
+    as: owner, body: { name: "Acme Ltd", email: "ap@acme.test", address: "1 Main St\nSpringfield", taxId: "VAT123" },
+  });
+  assert.equal(saved.status, 200);
+  const billing = await call(env, "GET", `/api/workspaces/${workspaceId}/billing`, { as: owner });
+  assert.deepEqual(billing.json.contact, { name: "Acme Ltd", email: "ap@acme.test", address: "1 Main St\nSpringfield", taxId: "VAT123" });
+  const receipt = await call(env, "GET", `/api/workspaces/${workspaceId}/invoices/${billing.json.invoices[0].id}`, { as: owner });
+  assert.equal(receipt.json.invoice.billingName, "Acme Ltd");
+  assert.equal(receipt.json.invoice.kind, "subscription");
+});

package/src/registry-worker/billing/provider.ts

@@ -0,0 +1,114 @@
+// The payment provider behind paid plans. PayPal is the first; another
+// (WorldFirst Global Checkout, Stripe) implements this same interface and
+// nothing else in billing changes. Bugmole keeps its own usage ledger,
+// invoices and spending limits; a provider only moves money.
+import type { BillingInterval } from "../../billing/plan-catalog.js";
+import type { Env } from "../core.js";
+
+export type PaidPlan = "team" | "business";
+
+export type ProviderSubscription = {
+  id: string;
+  /** pending: not approved yet. active: paid up. past_due: a renewal failed. ended: cancelled or expired. */
+  status: "pending" | "active" | "past_due" | "ended";
+  /** Our reference stamped at creation (the checkout id). Trusted only because we set it. */
+  reference: string | null;
+  plan: { plan: PaidPlan; interval: BillingInterval } | null;
+  startedAt: string | null;
+  /** End of the paid period: the next charge. */
+  paidThrough: string | null;
+  /** Why it ended, as the provider recorded it (our own cancellation reason, if it was us). */
+  endNote: string | null;
+  endedAt: string | null;
+};
+
+export type ProviderPayment = { reference: string; amountCents: number; currency: string; paidAt: string };
+
+export type UsageChargeLine = { name: string; description?: string; quantity: number; unitCents: number };
+
+export type WebhookEvent = {
+  id: string;
+  type: string;
+  /** The subscription the event is about, when it's about one. */
+  subscriptionId?: string;
+  /** The usage charge (invoice) the event is about, when it's about one. */
+  usageChargeId?: string;
+};
+
+export interface BillingProvider {
+  readonly id: string;
+  /** Credentials and a price for this plan and interval exist. */
+  canSell(env: Env, plan: PaidPlan, interval: BillingInterval): boolean;
+  createSubscription(env: Env, params: {
+    reference: string;
+    plan: PaidPlan;
+    interval: BillingInterval;
+    email?: string;
+    returnUrl: string;
+    cancelUrl: string;
+    requestId: string;
+    /** Starts billing later (a downgrade that takes effect when the current period ends). */
+    startAt?: string;
+  }): Promise<{ subscriptionId: string; approveUrl: string }>;
+  getSubscription(env: Env, id: string): Promise<ProviderSubscription | null>;
+  /** The payment for the current period (made on or after `since`), once the provider has posted it. */
+  latestPayment(env: Env, subscriptionId: string, since: Date, until: Date): Promise<ProviderPayment | null>;
+  cancelSubscription(env: Env, id: string, reason: string): Promise<void>;
+  refund(env: Env, payment: ProviderPayment, amountCents: number, requestId: string, description: string): Promise<{ reference: string }>;
+  /** Bills usage after the month; the payer receives the provider's pay link. */
+  chargeUsage(env: Env, params: {
+    invoiceNumber: string;
+    email: string;
+    name?: string;
+    note: string;
+    lines: UsageChargeLine[];
+    requestId: string;
+  }): Promise<{ reference: string; url: string | null }>;
+  usageChargeStatus(env: Env, reference: string): Promise<"open" | "paid" | "void" | null>;
+  /** Null when the request isn't a genuine event; throws when the check itself is unavailable. */
+  verifyWebhook(env: Env, request: Request, rawBody: string): Promise<WebhookEvent | null>;
+}
+
+export class BillingUnavailableError extends Error {}
+
+const providers = new Map<string, BillingProvider>();
+
+export function registerBillingProvider(provider: BillingProvider): void {
+  providers.set(provider.id, provider);
+}
+
+export function billingProvider(id: string): BillingProvider {
+  const provider = providers.get(id);
+  if (!provider) throw new BillingUnavailableError(`No billing provider "${id}"`);
+  return provider;
+}
+
+/** The provider new checkouts use. */
+export function defaultBillingProvider(env: Env): BillingProvider {
+  return billingProvider((env as Env & { BILLING_PROVIDER?: string }).BILLING_PROVIDER || "paypal");
+}
+
+/** Whole cents from a decimal amount string, without float drift. */
+export function toCents(amount: string): number {
+  const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(amount.trim());
+  if (!match) return NaN;
+  const cents = Number(match[2]) * 100 + Number(((match[3] ?? "") + "00").slice(0, 2));
+  return match[1] ? -cents : cents;
+}
+
+export function fromCents(cents: number): string {
+  return (cents / 100).toFixed(2);
+}
+
+/**
+ * The unused part of a paid period, rounded down to the cent, in integer
+ * arithmetic (ported from realistiz-dd's proRataRefund).
+ */
+export function proRataCents(paidCents: number, periodStart: string, periodEnd: string, now: Date): number {
+  const start = Date.parse(periodStart);
+  const end = Date.parse(periodEnd);
+  const total = end - start;
+  if (!(total > 0)) return 0;
+  const remaining = Math.min(Math.max(end - now.getTime(), 0), total);
+  return Math.floor((paidCents * remaining) / total);
+}

package/src/registry-worker/billing/routes.ts

@@ -0,0 +1,66 @@
+// Plan and usage for the dashboard's Billing page.
+import { PLANS } from "../../billing/plan-catalog.js";
+import { memberOfWorkspace, requestJson, response } from "../core.js";
+import { actorOf, recordAudit } from "../org/audit.js";
+import { type AuthedRouteContext, matchPath, registerRoutes } from "../routes/index.js";
+import { cloudUsageSuspended } from "./entitlements.js";
+import { usageSummary } from "./ledger.js";
+
+const MAX_SPENDING_LIMIT_CENTS = 10_000_000;
+
+async function getUsage({ env, principal }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const { entitlements, summary } = await usageSummary(env, workspaceId);
+  const { plan, ...limits } = entitlements;
+  const projects = await env.DB.prepare("SELECT COUNT(*) AS count FROM projects WHERE workspace_id = ? AND deleted_at IS NULL")
+    .bind(workspaceId).first<{ count: number }>();
+  return response({
+    plan: {
+      id: plan.plan,
+      name: PLANS[plan.plan].name,
+      interval: plan.interval,
+      status: plan.status,
+      periodStart: plan.periodStart,
+      periodEnd: plan.periodEnd,
+      pendingPlan: plan.pendingPlan,
+      graceUntil: plan.graceUntil,
+      cloudSuspended: cloudUsageSuspended(plan),
+      managedByProvider: Boolean(plan.provider),
+    },
+    limits,
+    usage: summary,
+    projects: projects?.count ?? 0,
+  });
+}
+
+async function setSpendingLimit({ env, principal, request }: AuthedRouteContext, workspaceId: string): Promise<Response> {
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "billing.manage"))) {
+    return response({ error: "Only owners and billing managers can change the spending limit" }, 403);
+  }
+  const body = await requestJson(request);
+  const raw = body?.limitCents;
+  const limitCents = raw === null ? null : Number(raw);
+  if (limitCents !== null && (!Number.isInteger(limitCents) || limitCents < 0 || limitCents > MAX_SPENDING_LIMIT_CENTS)) {
+    return response({ error: "limitCents must be a whole number of cents, or null for no limit" }, 422);
+  }
+  const current = await env.DB.prepare("SELECT plan, spending_limit_cents AS limitCents FROM workspace_plans WHERE workspace_id = ?")
+    .bind(workspaceId).first<{ plan: string; limitCents: number | null }>();
+  if (!current || current.plan === "free") {
+    return response({ error: "The Free plan has no additional usage to limit", code: "plan_feature" }, 409);
+  }
+  await env.DB.prepare("UPDATE workspace_plans SET spending_limit_cents = ?, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+    .bind(limitCents, workspaceId).run();
+  await recordAudit(env, actorOf(principal), {
+    workspaceId, action: "billing.spending_limit_changed", data: { from: current.limitCents, to: limitCents },
+  }, request);
+  return response({ spendingLimitCents: limitCents });
+}
+
+registerRoutes(async (context) => {
+  const { request, url } = context;
+  let params = matchPath(url.pathname, "/api/workspaces/:workspaceId/usage");
+  if (params && request.method === "GET") return getUsage(context, params.workspaceId);
+  params = matchPath(url.pathname, "/api/workspaces/:workspaceId/billing/spending-limit");
+  if (params && request.method === "PUT") return setSpendingLimit(context, params.workspaceId);
+  return null;
+});