@bugmole/cli 0.4.0

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

@@ -0,0 +1,780 @@
+// Paid plans: checkout, upgrades and downgrades, renewals, failed payments,
+// cancellation, and billing usage above the allowance after each month.
+//
+// Rules carried over from realistiz-dd's billing:
+// - The provider is the source of truth. A return page or webhook only says
+//   which subscription to look at; its status, owner (the checkout id we
+//   stamp as its reference) and payment are read back from the provider.
+// - A payment is recorded once: invoices are unique per provider reference,
+//   so the return page, a webhook and the daily sync can race safely.
+// - Upgrades are immediate. The replaced subscription is cancelled at the
+//   provider first (so it can't charge again), then its unused part is
+//   refunded pro-rata. Every step is recorded as it completes and retried by
+//   the daily job if the worker dies half-way.
+// Bugmole-specific rules:
+// - Downgrades and cancellations take effect when the paid period ends.
+// - A failed payment gives 7 days of grace, then pauses cloud usage (local
+//   and CI runs never stop); 14 days after that the workspace moves to Free.
+// - Nothing is deleted on a downgrade: projects over the new limit become
+//   read-only until the workspace upgrades again.
+import { PLANS, entitlementsFor, formatUsd, type BillingInterval, type Entitlements, type PlanId, type UsageKind } from "../../billing/plan-catalog.js";
+import type { Env, Principal } from "../core.js";
+import { newId } from "../core.js";
+import { emailSender, escapeHtml } from "../email/sender.js";
+import { planChangedHooks } from "../hooks.js";
+import { actorOf, recordAudit } from "../org/audit.js";
+import { getWorkspacePlan, type WorkspacePlan } from "./entitlements.js";
+import { periodAnchor, summarize, usagePeriod, usedInPeriod } from "./ledger.js";
+import {
+  BillingUnavailableError,
+  billingProvider,
+  defaultBillingProvider,
+  proRataCents,
+  type BillingProvider,
+  type PaidPlan,
+  type ProviderPayment,
+  type ProviderSubscription,
+  type UsageChargeLine,
+} from "./provider.js";
+import { billingRecipients } from "./thresholds.js";
+import { PayPalBusinessError } from "./paypal/client.js";
+import "./paypal/provider.js";
+
+const DAY = 86_400_000;
+export const GRACE_DAYS = 7;
+/** After grace runs out, how long an unpaid workspace keeps its plan before moving to Free. */
+export const LAPSE_DAYS = 14;
+const PAYMENT_LOOKBACK_MS = 40 * DAY;
+
+/** Reasons we give the provider when we end a subscription ourselves; a webhook echoing one is not the customer leaving. */
+export const CANCEL_REASON = "Cancelled on Bugmole";
+export const UPGRADE_REASON = "Replaced by an upgrade on Bugmole";
+export const SCHEDULED_REASON = "Replaced by a plan change at period end";
+const OUR_REASONS = new Set([CANCEL_REASON, UPGRADE_REASON, SCHEDULED_REASON]);
+
+export class BillingError extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message);
+  }
+}
+
+// --- Plans and prices ------------------------------------------------------------------------
+
+const TIER: Record<PaidPlan, number> = { team: 1, business: 2 };
+
+export function isPaidPlan(value: unknown): value is PaidPlan {
+  return value === "team" || value === "business";
+}
+
+/** What one period of a plan costs, in cents. */
+export function periodPriceCents(plan: PaidPlan, interval: BillingInterval): number {
+  const def = PLANS[plan];
+  return interval === "year" ? (def.priceYearlyMonthlyCents ?? 0) * 12 : def.priceMonthlyCents ?? 0;
+}
+
+/** "upgrade" starts now; "downgrade" starts when the current period ends. */
+export function changeKind(from: WorkspacePlan, plan: PaidPlan, interval: BillingInterval): "new" | "same" | "upgrade" | "downgrade" {
+  if (!isPaidPlan(from.plan) || !from.interval) return "new";
+  if (from.plan === plan && from.interval === interval) return "same";
+  if (TIER[plan] !== TIER[from.plan]) return TIER[plan] > TIER[from.plan] ? "upgrade" : "downgrade";
+  return interval === "year" ? "upgrade" : "downgrade";
+}
+
+// --- Stored state ----------------------------------------------------------------------------
+
+export type StoredPayment = ProviderPayment & { periodStart: string; periodEnd: string };
+
+type CheckoutRow = {
+  id: string;
+  workspace_id: string;
+  plan: PaidPlan;
+  billing_interval: BillingInterval;
+  provider: string;
+  provider_subscription_id: string | null;
+  status: "pending" | "scheduled" | "completed" | "abandoned";
+  replaces_subscription_id: string | null;
+  replaced_payment_json: string | null;
+  replaced_cancelled_at: string | null;
+  refund_json: string | null;
+  settled_at: string | null;
+  created_by: string;
+  created_at: string;
+  completed_at: string | null;
+};
+
+type PlanRow = {
+  workspace_id: string;
+  plan: string;
+  billing_interval: string | null;
+  status: string;
+  current_period_start: string | null;
+  current_period_end: string | null;
+  provider: string | null;
+  provider_subscription_id: string | null;
+  pending_plan: string | null;
+  grace_until: string | null;
+  last_payment_json: string | null;
+  cancel_at_period_end: number;
+  billing_email: string | null;
+  billing_name: string | null;
+};
+
+function parse<T>(value: string | null): T | null {
+  if (!value) return null;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function planRow(env: Env, workspaceId: string): Promise<PlanRow | null> {
+  return env.DB.prepare("SELECT * FROM workspace_plans WHERE workspace_id = ?").bind(workspaceId).first<PlanRow>();
+}
+
+async function checkoutById(env: Env, id: string): Promise<CheckoutRow | null> {
+  return env.DB.prepare("SELECT * FROM billing_checkouts WHERE id = ?").bind(id).first<CheckoutRow>();
+}
+
+function sqlIso(value: string): string {
+  return /[zZ]|[+-]\d\d:\d\d$/.test(value) ? value : `${value.replace(" ", "T")}Z`;
+}
+
+async function notifyPlanChange(env: Env, workspaceId: string, from: string, to: string): Promise<void> {
+  if (from === to) return;
+  for (const hook of planChangedHooks) {
+    try {
+      await hook(env, { workspaceId, from, to });
+    } catch (error) {
+      console.error("[billing] plan change hook failed", error);
+    }
+  }
+}
+
+async function sendBillingEmail(env: Env, workspaceId: string, subject: string, lines: string[], tag: string): Promise<void> {
+  const row = await planRow(env, workspaceId);
+  const recipients = await billingRecipients(env, workspaceId);
+  if (row?.billing_email && !recipients.some((r) => r.email === row.billing_email)) recipients.push({ email: row.billing_email });
+  if (!recipients.length) return;
+  const link = `${(env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/$/, "")}/billing`;
+  try {
+    await emailSender(env).send({
+      to: recipients,
+      subject,
+      text: `${lines.join("\n\n")}\n\nBilling: ${link}`,
+      html: `${lines.map((line) => `<p>${escapeHtml(line)}</p>`).join("")}<p><a href="${escapeHtml(link)}">Open billing</a></p>`,
+      tag,
+    });
+  } catch (error) {
+    console.error(`[billing] couldn't email ${workspaceId}: ${subject}`, error);
+  }
+}
+
+// --- Projects over the limit -----------------------------------------------------------------
+
+/** Locks the newest projects beyond the plan's limit and unlocks what fits again. */
+export async function applyProjectLimit(env: Env, workspaceId: string, entitlements: Entitlements): Promise<{ locked: number }> {
+  const rows = await env.DB.prepare(`
+    SELECT id, locked_at AS lockedAt FROM projects
+    WHERE workspace_id = ? AND deleted_at IS NULL ORDER BY created_at ASC, rowid ASC
+  `).bind(workspaceId).all<{ id: string; lockedAt: string | null }>();
+  const limit = entitlements.projects ?? Number.POSITIVE_INFINITY;
+  const now = new Date().toISOString();
+  let locked = 0;
+  for (const [index, project] of rows.results.entries()) {
+    const shouldLock = index >= limit;
+    if (shouldLock) locked += 1;
+    if (shouldLock && !project.lockedAt) {
+      await env.DB.prepare("UPDATE projects SET locked_at = ? WHERE id = ?").bind(now, project.id).run();
+    } else if (!shouldLock && project.lockedAt) {
+      await env.DB.prepare("UPDATE projects SET locked_at = NULL WHERE id = ?").bind(project.id).run();
+    }
+  }
+  return { locked };
+}
+
+// --- Invoices --------------------------------------------------------------------------------
+
+async function nextInvoiceNumber(env: Env, workspaceId: string, at: Date): Promise<string> {
+  const prefix = `VQ-${at.getUTCFullYear()}${String(at.getUTCMonth() + 1).padStart(2, "0")}`;
+  const row = await env.DB.prepare("SELECT COUNT(*) AS count FROM invoices WHERE number LIKE ?").bind(`${prefix}-%`).first<{ count: number }>();
+  // The random tail keeps two workers numbering at once from colliding.
+  return `${prefix}-${String(Number(row?.count ?? 0) + 1).padStart(4, "0")}-${newId("n").slice(-4).toUpperCase()}`;
+}
+
+/** Records a plan payment the provider already took. Returns false when it was already recorded. */
+async function recordSubscriptionPayment(env: Env, workspaceId: string, provider: string, plan: PaidPlan, interval: BillingInterval, payment: StoredPayment): Promise<boolean> {
+  const at = new Date(payment.paidAt);
+  const lines = [{ name: `${PLANS[plan].name} plan (${interval === "year" ? "yearly" : "monthly"})`, quantity: 1, unitCents: payment.amountCents }];
+  const result = await env.DB.prepare(`
+    INSERT INTO invoices (id, workspace_id, number, kind, status, plan, period_start, period_end, currency, total_cents, lines_json, provider, provider_ref, paid_at)
+    VALUES (?, ?, ?, 'subscription', 'paid', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(provider, provider_ref) DO NOTHING
+  `).bind(
+    newId("inv"), workspaceId, await nextInvoiceNumber(env, workspaceId, at), plan,
+    payment.periodStart, payment.periodEnd, payment.currency, payment.amountCents, JSON.stringify(lines),
+    provider, payment.reference, payment.paidAt,
+  ).run();
+  return (result.meta?.changes ?? 0) > 0;
+}
+
+const USAGE_NAMES: Record<UsageKind, string> = {
+  browser_minute: "Cloud minutes beyond the allowance",
+  device_minute: "Real device minutes",
+  ai_credit: "AI credits beyond the allowance",
+};
+
+export function usageLines(summary: ReturnType<typeof summarize>): UsageChargeLine[] {
+  return (Object.values(summary.lines))
+    .filter((line) => line.overageCents > 0 && line.unitCents !== null)
+    .map((line) => ({ name: USAGE_NAMES[line.kind], quantity: line.overageQuantity, unitCents: line.unitCents! }));
+}
+
+/**
+ * Bills one closed usage period. Safe to repeat: a period is billed once
+ * (unique per workspace and period), and a charge the provider couldn't take
+ * yet is retried on the next run.
+ */
+export async function billUsagePeriod(
+  env: Env,
+  workspaceId: string,
+  period: { start: string; end: string },
+  entitlements: Entitlements,
+  spendingLimitCents: number | null,
+  now = new Date(),
+): Promise<{ invoiceId: string; totalCents: number } | null> {
+  const existing = await env.DB.prepare("SELECT id, status, provider_ref AS ref, total_cents AS total FROM invoices WHERE workspace_id = ? AND kind = 'usage' AND period_start = ?")
+    .bind(workspaceId, period.start).first<{ id: string; status: string; ref: string | null; total: number }>();
+  if (existing && (existing.ref || existing.status === "none")) return existing.status === "none" ? null : { invoiceId: existing.id, totalCents: existing.total };
+
+  const summary = summarize(entitlements, await usedInPeriod(env, workspaceId, period.start), period, spendingLimitCents);
+  const lines = usageLines(summary);
+  const total = lines.reduce((sum, line) => sum + line.quantity * line.unitCents, 0);
+  let invoiceId = existing?.id;
+  if (!invoiceId) {
+    invoiceId = newId("inv");
+    const inserted = await env.DB.prepare(`
+      INSERT INTO invoices (id, workspace_id, number, kind, status, period_start, period_end, currency, total_cents, lines_json)
+      VALUES (?, ?, ?, 'usage', ?, ?, ?, 'USD', ?, ?)
+      ON CONFLICT(workspace_id, kind, period_start) DO NOTHING
+    `).bind(invoiceId, workspaceId, await nextInvoiceNumber(env, workspaceId, now), total > 0 ? "open" : "none", period.start, period.end, total, JSON.stringify(lines)).run();
+    if ((inserted.meta?.changes ?? 0) === 0) return null; // another run got here first
+  }
+  if (total <= 0) return null;
+
+  const row = await planRow(env, workspaceId);
+  const provider = billingProvider(row?.provider || defaultBillingProvider(env).id);
+  const email = row?.billing_email ?? (await billingRecipients(env, workspaceId))[0]?.email;
+  if (!email) {
+    console.error(`[billing] usage invoice ${invoiceId} for ${workspaceId} has nobody to send it to`);
+    return { invoiceId, totalCents: total };
+  }
+  const number = (await env.DB.prepare("SELECT number FROM invoices WHERE id = ?").bind(invoiceId).first<{ number: string }>())!.number;
+  try {
+    const charge = await provider.chargeUsage(env, {
+      invoiceNumber: number,
+      email,
+      name: row?.billing_name ?? undefined,
+      note: `Usage beyond your plan's allowance, ${period.start.slice(0, 10)} to ${period.end.slice(0, 10)}.`,
+      lines,
+      requestId: `usage-${invoiceId}`,
+    });
+    await env.DB.prepare("UPDATE invoices SET provider = ?, provider_ref = ?, provider_url = ?, due_at = ? WHERE id = ?")
+      .bind(provider.id, charge.reference, charge.url, new Date(now.getTime() + 15 * DAY).toISOString(), invoiceId).run();
+  } catch (error) {
+    console.error(`[billing] couldn't send usage invoice ${number} for ${workspaceId}; the daily run retries`, error);
+  }
+  return { invoiceId, totalCents: total };
+}
+
+// --- Checkout --------------------------------------------------------------------------------
+
+function dashboardUrl(env: Env): string {
+  return (env.DASHBOARD_URL || "https://app.bugmole.com").replace(/\/$/, "");
+}
+
+export type CheckoutStart = { checkoutId: string; approveUrl: string; effective: "now" | "period_end" };
+
+export async function startCheckout(
+  env: Env,
+  principal: Principal,
+  workspaceId: string,
+  plan: PaidPlan,
+  interval: BillingInterval,
+  request?: Request,
+): Promise<CheckoutStart> {
+  const provider = defaultBillingProvider(env);
+  if (!provider.canSell(env, plan, interval)) {
+    throw new BillingError(503, "billing_unavailable", "Online checkout isn't available right now. Contact us to upgrade.");
+  }
+  const current = await getWorkspacePlan(env, workspaceId);
+  const row = await planRow(env, workspaceId);
+  const kind = changeKind(current, plan, interval);
+  if (kind === "same" && !row?.cancel_at_period_end) {
+    throw new BillingError(409, "already_subscribed", `This workspace is already on ${PLANS[plan].name}.`);
+  }
+  const replacing = kind === "upgrade" || kind === "downgrade" || kind === "same" ? row?.provider_subscription_id ?? null : null;
+  const scheduled = kind === "downgrade" || kind === "same";
+  const startAt = scheduled && current.periodEnd ? new Date(Math.max(Date.parse(current.periodEnd), Date.now() + DAY)).toISOString() : undefined;
+  const checkoutId = newId("chk");
+  const email = principal.email ?? row?.billing_email ?? undefined;
+  const created = await provider.createSubscription(env, {
+    reference: checkoutId,
+    plan,
+    interval,
+    email,
+    returnUrl: `${dashboardUrl(env)}/billing/return?${new URLSearchParams({ workspace: workspaceId, checkout: checkoutId })}`,
+    cancelUrl: `${dashboardUrl(env)}/billing?${new URLSearchParams({ workspace: workspaceId, checkout: "cancelled" })}`,
+    requestId: checkoutId,
+    ...(startAt ? { startAt } : {}),
+  });
+  await env.DB.prepare(`
+    INSERT INTO billing_checkouts (id, workspace_id, plan, billing_interval, provider, provider_subscription_id, replaces_subscription_id, replaced_payment_json, created_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    checkoutId, workspaceId, plan, interval, provider.id, created.subscriptionId,
+    replacing, replacing ? row?.last_payment_json ?? null : null, principal.aegisId,
+  ).run();
+  await recordAudit(env, actorOf(principal), {
+    workspaceId, action: "billing.checkout_started", targetType: "checkout", targetId: checkoutId, data: { plan, interval, kind },
+  }, request);
+  return { checkoutId, approveUrl: created.approveUrl, effective: scheduled ? "period_end" : "now" };
+}
+
+/** Everything that decides the outcome is read from the provider; the browser only names the checkout. */
+export async function completeCheckout(env: Env, workspaceId: string, checkoutId: string, now = new Date()): Promise<{ status: "active" | "scheduled"; plan: WorkspacePlan }> {
+  const checkout = await checkoutById(env, checkoutId);
+  if (!checkout || checkout.workspace_id !== workspaceId || !checkout.provider_subscription_id) {
+    throw new BillingError(404, "checkout_not_found", "That checkout wasn't found.");
+  }
+  if (checkout.status === "completed") return { status: "active", plan: await getWorkspacePlan(env, workspaceId) };
+  if (checkout.status === "scheduled") return { status: "scheduled", plan: await getWorkspacePlan(env, workspaceId) };
+  const provider = billingProvider(checkout.provider);
+  const remote = await provider.getSubscription(env, checkout.provider_subscription_id);
+  if (!remote || remote.reference !== checkout.id) throw new BillingError(402, "payment_not_completed", "The payment wasn't completed.");
+  if (remote.status !== "active") throw new BillingError(402, "payment_not_completed", "The payment wasn't completed.");
+  if (!remote.plan || remote.plan.plan !== checkout.plan || remote.plan.interval !== checkout.billing_interval) {
+    console.error(`[billing] checkout ${checkout.id} subscription ${remote.id} is on an unexpected plan`, remote.plan);
+    throw new BillingError(402, "payment_not_completed", "The payment wasn't completed.");
+  }
+  const startsLater = remote.startedAt !== null && Date.parse(remote.startedAt) > now.getTime() + 60_000;
+  if (startsLater) return { status: "scheduled", plan: await scheduleChange(env, checkout, remote, now) };
+  await activateSubscription(env, checkout, remote, provider, now);
+  return { status: "active", plan: await getWorkspacePlan(env, workspaceId) };
+}
+
+/** A downgrade approved now, billed from the end of the current period. */
+async function scheduleChange(env: Env, checkout: CheckoutRow, remote: ProviderSubscription, now: Date): Promise<WorkspacePlan> {
+  const provider = billingProvider(checkout.provider);
+  if (checkout.replaces_subscription_id && !checkout.replaced_cancelled_at) {
+    // The current subscription is paid up to the period end; stop it renewing, since the new one takes over then.
+    await provider.cancelSubscription(env, checkout.replaces_subscription_id, SCHEDULED_REASON);
+    await env.DB.prepare("UPDATE billing_checkouts SET replaced_cancelled_at = ? WHERE id = ?").bind(now.toISOString(), checkout.id).run();
+  }
+  // Any earlier scheduled change is replaced by this one.
+  const earlier = await env.DB.prepare("SELECT id, provider, provider_subscription_id AS sub FROM billing_checkouts WHERE workspace_id = ? AND status = 'scheduled' AND id != ?")
+    .bind(checkout.workspace_id, checkout.id).all<{ id: string; provider: string; sub: string | null }>();
+  for (const old of earlier.results) {
+    if (old.sub) await billingProvider(old.provider).cancelSubscription(env, old.sub, SCHEDULED_REASON).catch(() => undefined);
+    await env.DB.prepare("UPDATE billing_checkouts SET status = 'abandoned' WHERE id = ?").bind(old.id).run();
+  }
+  await env.DB.batch([
+    env.DB.prepare("UPDATE billing_checkouts SET status = 'scheduled', completed_at = ? WHERE id = ?").bind(now.toISOString(), checkout.id),
+    env.DB.prepare("UPDATE workspace_plans SET pending_plan = ?, cancel_at_period_end = 1, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+      .bind(checkout.plan, checkout.workspace_id),
+  ]);
+  await sendBillingEmail(env, checkout.workspace_id, `Your plan changes to ${PLANS[checkout.plan].name} at the end of this period`, [
+    `Your workspace moves to ${PLANS[checkout.plan].name} (${checkout.billing_interval === "year" ? "yearly" : "monthly"}) on ${remote.startedAt?.slice(0, 10)}.`,
+    "Until then, everything in your current plan keeps working.",
+  ], "billing-scheduled");
+  return getWorkspacePlan(env, checkout.workspace_id);
+}
+
+/** Starts the plan a paid subscription is for: records the payment, sets the period, settles what it replaced. */
+async function activateSubscription(env: Env, checkout: CheckoutRow, remote: ProviderSubscription, provider: BillingProvider, now: Date): Promise<void> {
+  const payment = await provider.latestPayment(env, remote.id, new Date(Math.min(Date.parse(sqlIso(checkout.created_at)), now.getTime()) - PAYMENT_LOOKBACK_MS), now);
+  if (!payment || !remote.paidThrough) {
+    // The provider posts the first payment a few seconds after activation; the webhook finishes the job.
+    throw new BillingError(402, "payment_pending", "Your payment is still processing. This page updates when it's done.");
+  }
+  const expected = periodPriceCents(checkout.plan, checkout.billing_interval);
+  if (payment.currency !== "USD" || payment.amountCents < expected) {
+    console.error(`[billing] payment ${payment.reference} on ${remote.id} is ${payment.amountCents} ${payment.currency}, expected ${expected} USD`);
+    throw new BillingError(402, "unexpected_amount", "The payment amount didn't match the plan. Contact support.");
+  }
+  const before = await getWorkspacePlan(env, checkout.workspace_id);
+  const periodStart = payment.paidAt;
+  const stored: StoredPayment = { ...payment, periodStart, periodEnd: remote.paidThrough };
+  const anchor = remote.startedAt && Date.parse(remote.startedAt) <= now.getTime() ? remote.startedAt : periodStart;
+
+  // Bill the old plan's usage so far before the period anchor moves.
+  if (isPaidPlan(before.plan) && before.status !== "canceled") {
+    const oldPeriod = usagePeriod(periodAnchor(before), now);
+    await billUsagePeriod(env, checkout.workspace_id, { start: oldPeriod.start, end: now.toISOString() }, entitlementsFor(before.plan, before.overrides), before.spendingLimitCents, now);
+  }
+
+  await env.DB.prepare(`
+    INSERT INTO workspace_plans (workspace_id, plan, billing_interval, status, current_period_start, current_period_end, provider, provider_subscription_id, last_payment_json, pending_plan, grace_until, cancel_at_period_end, updated_at)
+    VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, NULL, NULL, 0, CURRENT_TIMESTAMP)
+    ON CONFLICT(workspace_id) DO UPDATE SET plan = excluded.plan, billing_interval = excluded.billing_interval, status = 'active',
+      current_period_start = excluded.current_period_start, current_period_end = excluded.current_period_end,
+      provider = excluded.provider, provider_subscription_id = excluded.provider_subscription_id,
+      last_payment_json = excluded.last_payment_json, pending_plan = NULL, grace_until = NULL, cancel_at_period_end = 0,
+      updated_at = CURRENT_TIMESTAMP
+  `).bind(checkout.workspace_id, checkout.plan, checkout.billing_interval, anchor, remote.paidThrough, provider.id, remote.id, JSON.stringify(stored)).run();
+  const recorded = await recordSubscriptionPayment(env, checkout.workspace_id, provider.id, checkout.plan, checkout.billing_interval, stored);
+  await env.DB.prepare("UPDATE billing_checkouts SET status = 'completed', completed_at = COALESCE(completed_at, ?) WHERE id = ?").bind(now.toISOString(), checkout.id).run();
+  await applyProjectLimit(env, checkout.workspace_id, entitlementsFor(checkout.plan));
+  await recordAudit(env, { type: "system", id: `billing:${provider.id}` }, {
+    workspaceId: checkout.workspace_id, action: "billing.plan_changed", targetType: "workspace", targetId: checkout.workspace_id,
+    data: { from: before.plan, to: checkout.plan, interval: checkout.billing_interval, payment: payment.reference },
+  });
+  await notifyPlanChange(env, checkout.workspace_id, before.plan, checkout.plan);
+  if (checkout.replaces_subscription_id) await settleReplaced(env, checkout.id, now);
+  if (recorded) {
+    await sendBillingEmail(env, checkout.workspace_id, `Receipt: ${PLANS[checkout.plan].name} plan, ${formatUsd(payment.amountCents)}`, [
+      `Thanks — your workspace is on ${PLANS[checkout.plan].name} (${checkout.billing_interval === "year" ? "yearly" : "monthly"}).`,
+      `Paid ${formatUsd(payment.amountCents)} for ${periodStart.slice(0, 10)} to ${remote.paidThrough.slice(0, 10)}.`,
+    ], "billing-receipt");
+  }
+}
+
+export type Refund = { amountCents: number; status: "none" | "refunded" | "failed"; reference?: string };
+
+/**
+ * Settles the subscription an upgrade replaced: cancel it at the provider,
+ * then refund its unused part as of the upgrade. Each step is recorded when
+ * it completes; a provider outage leaves the rest for the daily retry, and a
+ * refused refund is final and logged for a person to handle.
+ */
+export async function settleReplaced(env: Env, checkoutId: string, now = new Date()): Promise<void> {
+  const checkout = await checkoutById(env, checkoutId);
+  if (!checkout || checkout.status !== "completed" || !checkout.replaces_subscription_id || checkout.settled_at) return;
+  const provider = billingProvider(checkout.provider);
+  if (!checkout.replaced_cancelled_at) {
+    try {
+      await provider.cancelSubscription(env, checkout.replaces_subscription_id, UPGRADE_REASON);
+      await env.DB.prepare("UPDATE billing_checkouts SET replaced_cancelled_at = ? WHERE id = ?").bind(now.toISOString(), checkout.id).run();
+    } catch (error) {
+      console.error(`[billing] couldn't cancel replaced subscription ${checkout.replaces_subscription_id}; the daily run retries`, error);
+      return;
+    }
+  }
+  const replaced = parse<StoredPayment>(checkout.replaced_payment_json);
+  const upgradedAt = new Date(sqlIso(checkout.completed_at ?? now.toISOString()));
+  const due = replaced ? proRataCents(replaced.amountCents, replaced.periodStart, replaced.periodEnd, upgradedAt) : 0;
+  let refund: Refund = { amountCents: due, status: "none" };
+  if (replaced && due >= 1) {
+    try {
+      const result = await provider.refund(env, replaced, due, `upgrade-refund-${checkout.id}`, "Unused part of the previous Bugmole plan");
+      refund = { amountCents: due, status: "refunded", reference: result.reference };
+      await env.DB.prepare("UPDATE invoices SET refunded_cents = refunded_cents + ? WHERE provider = ? AND provider_ref = ?")
+        .bind(due, provider.id, replaced.reference).run();
+    } catch (error) {
+      if (!(error instanceof PayPalBusinessError)) {
+        console.error(`[billing] refund for upgrade ${checkout.id} unavailable; the daily run retries`, error);
+        return;
+      }
+      refund = { amountCents: due, status: "failed" };
+      console.error(`[billing] refund refused for upgrade ${checkout.id}: ${due} cents on ${replaced.reference} — refund manually`, error);
+    }
+  }
+  const settled = await env.DB.prepare("UPDATE billing_checkouts SET refund_json = ?, settled_at = ? WHERE id = ? AND settled_at IS NULL")
+    .bind(JSON.stringify(refund), now.toISOString(), checkout.id).run();
+  if ((settled.meta?.changes ?? 0) > 0 && refund.status === "refunded") {
+    await sendBillingEmail(env, checkout.workspace_id, `Refund: ${formatUsd(refund.amountCents)} for your previous plan`, [
+      `We refunded ${formatUsd(refund.amountCents)}, the unused part of your previous plan, to your PayPal account.`,
+    ], "billing-refund");
+  }
+}
+
+// --- Cancellation ----------------------------------------------------------------------------
+
+/** Stops renewal now; the plan keeps working until the paid period ends. */
+export async function cancelAtPeriodEnd(env: Env, principal: Principal, workspaceId: string, request?: Request): Promise<WorkspacePlan> {
+  const row = await planRow(env, workspaceId);
+  if (!row || !isPaidPlan(row.plan) || row.status === "canceled") throw new BillingError(409, "not_subscribed", "This workspace isn't on a paid plan.");
+  if (row.provider && row.provider_subscription_id) {
+    await billingProvider(row.provider).cancelSubscription(env, row.provider_subscription_id, CANCEL_REASON);
+  }
+  const scheduled = await env.DB.prepare("SELECT id, provider, provider_subscription_id AS sub FROM billing_checkouts WHERE workspace_id = ? AND status = 'scheduled'")
+    .bind(workspaceId).all<{ id: string; provider: string; sub: string | null }>();
+  for (const change of scheduled.results) {
+    if (change.sub) await billingProvider(change.provider).cancelSubscription(env, change.sub, CANCEL_REASON).catch(() => undefined);
+    await env.DB.prepare("UPDATE billing_checkouts SET status = 'abandoned' WHERE id = ?").bind(change.id).run();
+  }
+  await env.DB.prepare("UPDATE workspace_plans SET cancel_at_period_end = 1, pending_plan = 'free', updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+    .bind(workspaceId).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "billing.cancelled", targetType: "workspace", targetId: workspaceId }, request);
+  await sendBillingEmail(env, workspaceId, "Your Bugmole plan won't renew", [
+    `Your ${PLANS[row.plan as PaidPlan].name} plan stays active until ${row.current_period_end?.slice(0, 10) ?? "the end of the period"}, then the workspace moves to Free.`,
+    "Nothing is deleted. Projects beyond Free's limit become read-only until you upgrade again.",
+  ], "billing-cancelled");
+  return getWorkspacePlan(env, workspaceId);
+}
+
+// --- Keeping in step with the provider -------------------------------------------------------
+
+async function moveToFree(env: Env, workspaceId: string, reason: string): Promise<void> {
+  const before = await getWorkspacePlan(env, workspaceId);
+  await env.DB.prepare(`
+    UPDATE workspace_plans SET status = 'canceled', pending_plan = NULL, cancel_at_period_end = 0,
+      provider_subscription_id = NULL, updated_at = CURRENT_TIMESTAMP
+    WHERE workspace_id = ?
+  `).bind(workspaceId).run();
+  const { locked } = await applyProjectLimit(env, workspaceId, entitlementsFor("free"));
+  await recordAudit(env, { type: "system", id: "billing" }, {
+    workspaceId, action: "billing.moved_to_free", targetType: "workspace", targetId: workspaceId, data: { reason, lockedProjects: locked },
+  });
+  await notifyPlanChange(env, workspaceId, before.plan, "free");
+  await sendBillingEmail(env, workspaceId, "Your workspace is now on Free", [
+    reason === "unpaid"
+      ? "We couldn't collect payment, so your workspace moved to the Free plan."
+      : "Your paid plan has ended and your workspace is on the Free plan.",
+    locked ? `${locked} project${locked === 1 ? " is" : "s are"} read-only until you upgrade. Nothing was deleted.` : "Nothing was deleted.",
+  ], "billing-free");
+}
+
+/**
+ * Brings one workspace in line with its provider and the calendar. Called by
+ * webhooks and by the daily job. Safe to repeat.
+ */
+export async function syncWorkspaceBilling(env: Env, workspaceId: string, now = new Date()): Promise<void> {
+  const row = await planRow(env, workspaceId);
+  if (!row || !isPaidPlan(row.plan) || row.status === "canceled") return;
+  const provider = row.provider ? billingProvider(row.provider) : null;
+
+  if (provider && row.provider_subscription_id) {
+    const remote = await provider.getSubscription(env, row.provider_subscription_id);
+    const checkout = remote?.reference ? await checkoutById(env, remote.reference) : null;
+    if (remote && checkout?.workspace_id === workspaceId) {
+      if (remote.status === "active") await applyRenewal(env, row, remote, provider, now);
+      if (remote.status === "past_due" && row.status === "active") {
+        await env.DB.prepare("UPDATE workspace_plans SET status = 'past_due', grace_until = ?, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+          .bind(new Date(now.getTime() + GRACE_DAYS * DAY).toISOString(), workspaceId).run();
+        await sendBillingEmail(env, workspaceId, "Your Bugmole payment didn't go through", [
+          `PayPal couldn't collect your renewal. Update your payment method in PayPal within ${GRACE_DAYS} days to keep using Bugmole Cloud.`,
+          "Runs on your own machines and CI keep working either way.",
+        ], "billing-payment-failed");
+      }
+      if (remote.status === "ended" && !(remote.endNote && OUR_REASONS.has(remote.endNote)) && !row.cancel_at_period_end) {
+        // Cancelled inside PayPal: honor it at the end of the paid period.
+        await env.DB.prepare("UPDATE workspace_plans SET cancel_at_period_end = 1, pending_plan = 'free', updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+          .bind(workspaceId).run();
+        row.cancel_at_period_end = 1;
+      }
+    }
+  }
+
+  const current = await planRow(env, workspaceId);
+  if (!current) return;
+  const ended = current.current_period_end !== null && Date.parse(current.current_period_end) <= now.getTime();
+  if (ended && current.cancel_at_period_end) {
+    const scheduled = await env.DB.prepare("SELECT * FROM billing_checkouts WHERE workspace_id = ? AND status = 'scheduled' ORDER BY completed_at DESC LIMIT 1")
+      .bind(workspaceId).first<CheckoutRow>();
+    if (scheduled?.provider_subscription_id) {
+      const next = await billingProvider(scheduled.provider).getSubscription(env, scheduled.provider_subscription_id);
+      if (next?.status === "active") {
+        try {
+          await env.DB.prepare("UPDATE billing_checkouts SET status = 'pending' WHERE id = ?").bind(scheduled.id).run();
+          await activateSubscription(env, { ...scheduled, status: "pending" }, next, billingProvider(scheduled.provider), now);
+          return;
+        } catch (error) {
+          await env.DB.prepare("UPDATE billing_checkouts SET status = 'scheduled' WHERE id = ?").bind(scheduled.id).run();
+          // The first payment of the new plan isn't in yet; give it a day before giving up on it.
+          if (Date.parse(current.current_period_end!) > now.getTime() - DAY) return;
+          console.error(`[billing] scheduled plan for ${workspaceId} never got paid`, error);
+        }
+      }
+    }
+    await moveToFree(env, workspaceId, "ended");
+    return;
+  }
+  if (current.status === "past_due" && current.grace_until && Date.parse(current.grace_until) + LAPSE_DAYS * DAY <= now.getTime()) {
+    if (current.provider && current.provider_subscription_id) {
+      await billingProvider(current.provider).cancelSubscription(env, current.provider_subscription_id, CANCEL_REASON).catch(() => undefined);
+    }
+    await moveToFree(env, workspaceId, "unpaid");
+  }
+}
+
+/** A renewal the provider already charged: record it and move the period on. */
+async function applyRenewal(env: Env, row: PlanRow, remote: ProviderSubscription, provider: BillingProvider, now: Date): Promise<void> {
+  if (!remote.paidThrough || !isPaidPlan(row.plan) || !row.billing_interval) return;
+  const known = row.current_period_end ? Date.parse(row.current_period_end) : 0;
+  const recovered = row.status === "past_due";
+  if (Date.parse(remote.paidThrough) <= known && !recovered) return;
+  const payment = await provider.latestPayment(env, remote.id, new Date(now.getTime() - PAYMENT_LOOKBACK_MS), now);
+  const last = parse<StoredPayment>(row.last_payment_json);
+  if (!payment || payment.reference === last?.reference) {
+    // Only the date moved (or the payment isn't posted yet): keep the later end.
+    if (Date.parse(remote.paidThrough) > known) {
+      await env.DB.prepare("UPDATE workspace_plans SET current_period_end = ?, updated_at = CURRENT_TIMESTAMP WHERE workspace_id = ?")
+        .bind(remote.paidThrough, row.workspace_id).run();
+    }
+    return;
+  }
+  const stored: StoredPayment = { ...payment, periodStart: row.current_period_end ?? payment.paidAt, periodEnd: remote.paidThrough };
+  await env.DB.prepare(`
+    UPDATE workspace_plans SET current_period_end = ?, last_payment_json = ?, status = 'active', grace_until = NULL, updated_at = CURRENT_TIMESTAMP
+    WHERE workspace_id = ?
+  `).bind(remote.paidThrough, JSON.stringify(stored), row.workspace_id).run();
+  const recorded = await recordSubscriptionPayment(env, row.workspace_id, provider.id, row.plan, row.billing_interval as BillingInterval, stored);
+  if (recorded) {
+    await sendBillingEmail(env, row.workspace_id, `Receipt: ${PLANS[row.plan].name} plan, ${formatUsd(payment.amountCents)}`, [
+      `Your ${PLANS[row.plan].name} plan renewed: ${formatUsd(payment.amountCents)} for ${stored.periodStart.slice(0, 10)} to ${stored.periodEnd.slice(0, 10)}.`,
+    ], "billing-receipt");
+  }
+}
+
+// --- Webhooks --------------------------------------------------------------------------------
+
+export async function handleProviderWebhook(env: Env, providerId: string, request: Request): Promise<Response> {
+  let provider: BillingProvider;
+  try {
+    provider = billingProvider(providerId);
+  } catch {
+    return Response.json({ error: "Unknown provider" }, { status: 404 });
+  }
+  const rawBody = await request.text();
+  let event;
+  try {
+    event = await provider.verifyWebhook(env, request, rawBody);
+  } catch (error) {
+    // The provider's verification API is down: let it retry the event.
+    console.error("[billing] webhook verification unavailable", error);
+    return Response.json({ error: "Verification unavailable" }, { status: 503 });
+  }
+  if (!event) return Response.json({ error: "Invalid webhook" }, { status: 400 });
+
+  const first = event.id
+    ? await env.DB.prepare("INSERT INTO billing_events (provider, event_id, event_type) VALUES (?, ?, ?) ON CONFLICT DO NOTHING")
+      .bind(provider.id, event.id, event.type).run()
+    : null;
+  try {
+    if (event.subscriptionId) await onSubscriptionEvent(env, provider, event.subscriptionId);
+    if (event.usageChargeId) await refreshUsageCharge(env, provider, event.usageChargeId);
+    return Response.json({ ok: true, duplicate: first !== null && (first.meta?.changes ?? 0) === 0 });
+  } catch (error) {
+    // Forget the event so the provider's retry is processed.
+    if (event.id) await env.DB.prepare("DELETE FROM billing_events WHERE provider = ? AND event_id = ?").bind(provider.id, event.id).run();
+    console.error(`[billing] webhook ${event.type} failed`, error);
+    return Response.json({ error: "Processing failed" }, { status: 500 });
+  }
+}
+
+async function onSubscriptionEvent(env: Env, provider: BillingProvider, subscriptionId: string): Promise<void> {
+  const checkout = await env.DB.prepare("SELECT * FROM billing_checkouts WHERE provider = ? AND provider_subscription_id = ?")
+    .bind(provider.id, subscriptionId).first<CheckoutRow>();
+  if (!checkout) return;
+  if (checkout.status === "pending") {
+    try {
+      await completeCheckout(env, checkout.workspace_id, checkout.id);
+    } catch (error) {
+      if (!(error instanceof BillingError)) throw error;
+    }
+    return;
+  }
+  const row = await planRow(env, checkout.workspace_id);
+  if (row?.provider_subscription_id === subscriptionId) await syncWorkspaceBilling(env, checkout.workspace_id);
+}
+
+async function refreshUsageCharge(env: Env, provider: BillingProvider, reference: string): Promise<void> {
+  const invoice = await env.DB.prepare("SELECT id, workspace_id AS workspaceId, status FROM invoices WHERE provider = ? AND provider_ref = ?")
+    .bind(provider.id, reference).first<{ id: string; workspaceId: string; status: string }>();
+  if (!invoice || invoice.status !== "open") return;
+  const status = await provider.usageChargeStatus(env, reference);
+  if (status === "paid") {
+    await env.DB.prepare("UPDATE invoices SET status = 'paid', paid_at = ? WHERE id = ?").bind(new Date().toISOString(), invoice.id).run();
+    await clearOverdueIfSettled(env, invoice.workspaceId);
+  } else if (status === "void") {
+    await env.DB.prepare("UPDATE invoices SET status = 'void' WHERE id = ?").bind(invoice.id).run();
+    await clearOverdueIfSettled(env, invoice.workspaceId);
+  }
+}
+
+async function clearOverdueIfSettled(env: Env, workspaceId: string): Promise<void> {
+  const overdue = await env.DB.prepare("SELECT COUNT(*) AS count FROM invoices WHERE workspace_id = ? AND status = 'open' AND due_at < ?")
+    .bind(workspaceId, new Date().toISOString()).first<{ count: number }>();
+  const row = await planRow(env, workspaceId);
+  if (!overdue?.count && row?.status === "past_due" && row.provider_subscription_id) {
+    const remote = row.provider ? await billingProvider(row.provider).getSubscription(env, row.provider_subscription_id) : null;
+    if (remote?.status === "active") {
+      await env.DB.prepare("UPDATE workspace_plans SET status = 'active', grace_until = NULL WHERE workspace_id = ?").bind(workspaceId).run();
+    }
+  }
+}
+
+// --- Daily jobs ------------------------------------------------------------------------------
+
+/** Closes last month's usage for every paid workspace and bills anything over the allowance. */
+export async function closeUsagePeriods(env: Env, now = new Date()): Promise<number> {
+  const rows = await env.DB.prepare("SELECT workspace_id AS id FROM workspace_plans WHERE plan IN ('team', 'business') AND status != 'canceled'")
+    .all<{ id: string }>();
+  let billed = 0;
+  for (const { id } of rows.results) {
+    const plan = await getWorkspacePlan(env, id);
+    if (!isPaidPlan(plan.plan)) continue;
+    const current = usagePeriod(periodAnchor(plan), now);
+    const previous = usagePeriod(periodAnchor(plan), new Date(Date.parse(current.start) - 1));
+    // Nothing to close before the plan started.
+    if (plan.periodStart && Date.parse(previous.start) < Date.parse(plan.periodStart) - 1000) continue;
+    const result = await billUsagePeriod(env, id, previous, entitlementsFor(plan.plan, plan.overrides), plan.spendingLimitCents, now);
+    if (result) billed += 1;
+  }
+  return billed;
+}
+
+/** Usage invoices unpaid a week past due pause cloud usage the same way a failed renewal does. */
+export async function chaseOverdueInvoices(env: Env, now = new Date()): Promise<void> {
+  const open = await env.DB.prepare("SELECT id, workspace_id AS workspaceId, provider, provider_ref AS ref, due_at AS dueAt FROM invoices WHERE kind = 'usage' AND status = 'open'")
+    .all<{ id: string; workspaceId: string; provider: string | null; ref: string | null; dueAt: string | null }>();
+  for (const invoice of open.results) {
+    if (invoice.provider && invoice.ref) {
+      await refreshUsageCharge(env, billingProvider(invoice.provider), invoice.ref).catch((error) => console.error("[billing] invoice status check failed", error));
+    }
+    const still = await env.DB.prepare("SELECT status FROM invoices WHERE id = ?").bind(invoice.id).first<{ status: string }>();
+    if (still?.status !== "open" || !invoice.dueAt) continue;
+    if (Date.parse(invoice.dueAt) + GRACE_DAYS * DAY <= now.getTime()) {
+      const changed = await env.DB.prepare(`
+        UPDATE workspace_plans SET status = 'past_due', grace_until = ?, updated_at = CURRENT_TIMESTAMP
+        WHERE workspace_id = ? AND status = 'active'
+      `).bind(now.toISOString(), invoice.workspaceId).run();
+      if ((changed.meta?.changes ?? 0) > 0) {
+        await sendBillingEmail(env, invoice.workspaceId, "Bugmole Cloud is paused until an invoice is paid", [
+          "A usage invoice is more than a week overdue, so cloud runs and AI work are paused. Pay it from the PayPal email, or from Billing.",
+          "Runs on your own machines and CI keep working.",
+        ], "billing-overdue");
+      }
+    }
+  }
+}
+
+export async function syncAllBilling(env: Env, now = new Date()): Promise<void> {
+  const rows = await env.DB.prepare("SELECT workspace_id AS id FROM workspace_plans WHERE plan IN ('team', 'business') AND status != 'canceled'")
+    .all<{ id: string }>();
+  for (const { id } of rows.results) {
+    try {
+      await syncWorkspaceBilling(env, id, now);
+    } catch (error) {
+      console.error(`[billing] sync failed for ${id}`, error);
+    }
+  }
+  // Checkouts whose return page never came back (closed tab) and upgrades left half-settled.
+  const pending = await env.DB.prepare(`
+    SELECT id, workspace_id AS workspaceId, status FROM billing_checkouts
+    WHERE (status = 'pending' AND created_at > ?) OR (status = 'completed' AND replaces_subscription_id IS NOT NULL AND settled_at IS NULL)
+  `).bind(new Date(now.getTime() - 3 * DAY).toISOString().replace("T", " ").slice(0, 19)).all<{ id: string; workspaceId: string; status: string }>();
+  for (const checkout of pending.results) {
+    try {
+      if (checkout.status === "pending") await completeCheckout(env, checkout.workspaceId, checkout.id, now);
+      else await settleReplaced(env, checkout.id, now);
+    } catch (error) {
+      if (!(error instanceof BillingError)) console.error(`[billing] checkout ${checkout.id} retry failed`, error);
+    }
+  }
+  await env.DB.prepare("UPDATE billing_checkouts SET status = 'abandoned' WHERE status = 'pending' AND created_at <= ?")
+    .bind(new Date(now.getTime() - 3 * DAY).toISOString().replace("T", " ").slice(0, 19)).run();
+}
+
+export { BillingUnavailableError, type PlanId };