@bugmole/cli 0.4.0

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

@@ -0,0 +1,186 @@
+// Usage metering. Each billable thing (a cloud run's minutes, an AI action,
+// a real-device session) is one idempotent row in usage_events; totals are
+// summed per usage period on read.
+import {
+  type Entitlements,
+  type UsageKind,
+  includedQuantity,
+  overageCents,
+} from "../../billing/plan-catalog.js";
+import { type Env, newId } from "../core.js";
+import { cloudUsageSuspended, getEntitlements, type WorkspacePlan } from "./entitlements.js";
+
+export const USAGE_KINDS: UsageKind[] = ["browser_minute", "device_minute", "ai_credit"];
+
+function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+
+function anchored(year: number, month: number, anchor: Date): Date {
+  const day = Math.min(anchor.getUTCDate(), daysInMonth(year, month));
+  return new Date(Date.UTC(year, month, day, anchor.getUTCHours(), anchor.getUTCMinutes(), anchor.getUTCSeconds()));
+}
+
+/**
+ * The monthly usage window containing `now`. Paid plans count from their
+ * subscription start (a yearly plan still closes usage monthly); Free counts
+ * calendar months (UTC).
+ */
+export function usagePeriod(anchorIso: string | null, now = new Date()): { start: string; end: string } {
+  const anchor = anchorIso ? new Date(anchorIso) : new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+  if (Number.isNaN(anchor.getTime()) || anchor > now) {
+    const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    return { start: start.toISOString(), end: new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1)).toISOString() };
+  }
+  let year = now.getUTCFullYear();
+  let month = now.getUTCMonth();
+  let start = anchored(year, month, anchor);
+  if (start > now) {
+    month -= 1;
+    if (month < 0) { month = 11; year -= 1; }
+    start = anchored(year, month, anchor);
+  }
+  const endMonth = (month + 1) % 12;
+  const endYear = month === 11 ? year + 1 : year;
+  return { start: start.toISOString(), end: anchored(endYear, endMonth, anchor).toISOString() };
+}
+
+export function periodAnchor(plan: WorkspacePlan): string | null {
+  return plan.plan === "free" ? null : plan.periodStart;
+}
+
+export type UsageLine = {
+  kind: UsageKind;
+  included: number | null;
+  used: number;
+  remaining: number | null;
+  overageQuantity: number;
+  unitCents: number | null;
+  overageCents: number;
+};
+
+export type UsageSummary = {
+  period: { start: string; end: string };
+  lines: Record<UsageKind, UsageLine>;
+  overageCents: number;
+  spendingLimitCents: number | null;
+};
+
+export function summarize(entitlements: Entitlements, used: Record<UsageKind, number>, period: UsageSummary["period"], spendingLimitCents: number | null): UsageSummary {
+  const lines = {} as Record<UsageKind, UsageLine>;
+  let total = 0;
+  for (const kind of USAGE_KINDS) {
+    const included = includedQuantity(entitlements, kind);
+    const unitCents = overageCents(entitlements, kind);
+    const quantity = used[kind] ?? 0;
+    const overageQuantity = included === null ? 0 : Math.max(0, quantity - included);
+    const cents = unitCents === null ? 0 : overageQuantity * unitCents;
+    total += cents;
+    lines[kind] = {
+      kind,
+      included,
+      used: quantity,
+      remaining: included === null ? null : Math.max(0, included - quantity),
+      overageQuantity,
+      unitCents,
+      overageCents: cents,
+    };
+  }
+  return { period, lines, overageCents: total, spendingLimitCents };
+}
+
+export async function usedInPeriod(env: Env, workspaceId: string, periodStart: string): Promise<Record<UsageKind, number>> {
+  const rows = await env.DB.prepare(`
+    SELECT kind, COALESCE(SUM(quantity), 0) AS used
+    FROM usage_events WHERE workspace_id = ? AND period_start = ?
+    GROUP BY kind
+  `).bind(workspaceId, periodStart).all<{ kind: UsageKind; used: number }>();
+  const used = { browser_minute: 0, device_minute: 0, ai_credit: 0 } as Record<UsageKind, number>;
+  for (const row of rows.results) used[row.kind] = Number(row.used);
+  return used;
+}
+
+export async function usageSummary(env: Env, workspaceId: string, now = new Date()) {
+  const entitlements = await getEntitlements(env, workspaceId);
+  const period = usagePeriod(periodAnchor(entitlements.plan), now);
+  const used = await usedInPeriod(env, workspaceId, period.start);
+  return { entitlements, summary: summarize(entitlements, used, period, entitlements.plan.spendingLimitCents) };
+}
+
+export type SpendDecision =
+  | { allowed: true }
+  | { allowed: false; reason: "quota" | "spending_limit" | "plan" | "suspended"; message: string };
+
+/**
+ * Whether a workspace may use `quantity` more of `kind` now. Free stops at its
+ * allowance; paid plans may go over it until the spending limit (if set).
+ */
+export async function canSpend(env: Env, workspaceId: string, kind: UsageKind, quantity: number, now = new Date()): Promise<SpendDecision> {
+  const { entitlements, summary } = await usageSummary(env, workspaceId, now);
+  const plan = entitlements.plan;
+  if (cloudUsageSuspended(plan, now)) {
+    return { allowed: false, reason: "suspended", message: "Cloud usage is paused until the overdue payment is settled. Local and CI runs keep working." };
+  }
+  const line = summary.lines[kind];
+  if (kind === "device_minute" && (plan.plan === "free" || !entitlements.features.deviceClouds)) {
+    return { allowed: false, reason: "plan", message: "Real devices are available on the Business plan." };
+  }
+  const projectedUsed = line.used + quantity;
+  if (line.unitCents === null) {
+    if (line.included !== null && projectedUsed > line.included) {
+      return {
+        allowed: false,
+        reason: "quota",
+        message: kind === "ai_credit"
+          ? "This month's AI credits are used up. Upgrade for more, or connect your own model key."
+          : "This month's cloud minutes are used up. Upgrade for more, or run on your own machine or CI for free.",
+      };
+    }
+    return { allowed: true };
+  }
+  if (summary.spendingLimitCents !== null) {
+    const projectedOverage = line.included === null ? 0 : Math.max(0, projectedUsed - line.included) * line.unitCents;
+    const otherOverage = summary.overageCents - line.overageCents;
+    if (otherOverage + projectedOverage > summary.spendingLimitCents) {
+      return { allowed: false, reason: "spending_limit", message: "Your monthly spending limit has been reached. Raise it in Billing to keep using the cloud." };
+    }
+  }
+  return { allowed: true };
+}
+
+export type UsageRecord = {
+  workspaceId: string;
+  projectId?: string | null;
+  runId?: string | null;
+  kind: UsageKind;
+  quantity: number;
+  source: "cloud_run" | "ai" | "device_farm" | "adjustment";
+  idempotencyKey: string;
+  meta?: Record<string, unknown>;
+  now?: Date;
+};
+
+/** Records usage once per idempotency key. Returns false if it was already recorded. */
+export async function recordUsage(env: Env, record: UsageRecord): Promise<boolean> {
+  const now = record.now ?? new Date();
+  const entitlements = await getEntitlements(env, record.workspaceId);
+  const period = usagePeriod(periodAnchor(entitlements.plan), now);
+  const result = await env.DB.prepare(`
+    INSERT INTO usage_events (id, workspace_id, project_id, run_id, kind, quantity, source, idempotency_key, period_start, occurred_at, meta_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(idempotency_key) DO NOTHING
+  `).bind(
+    newId("use"),
+    record.workspaceId,
+    record.projectId ?? null,
+    record.runId ?? null,
+    record.kind,
+    Math.round(record.quantity),
+    record.source,
+    record.idempotencyKey,
+    period.start,
+    now.toISOString(),
+    record.meta ? JSON.stringify(record.meta) : null,
+  ).run();
+  return (result.meta?.changes ?? 0) > 0;
+}

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

@@ -0,0 +1,259 @@
+// PayPal Subscriptions v1, sale refunds, webhook verification, and Invoicing
+// v2. Subscriptions, refunds and verification are ported from realistiz-dd
+// (src/worker/newsletter/paypalSubscriptions.ts); invoicing is new, for
+// billing usage above a plan's allowance after the month closes.
+//
+// Most of this is reads on purpose: whether a subscription is active, whose
+// it is (custom_id, stamped by us) and which sale paid all come from PayPal,
+// never from a browser or a webhook body.
+import { PayPalBusinessError, fail, issueOf, payPalApiFetch, type PayPalEnv } from "./client.js";
+
+export type PayPalSubscriptionState = {
+  id: string;
+  /** APPROVAL_PENDING | APPROVED | ACTIVE | SUSPENDED | CANCELLED | EXPIRED. */
+  status: string;
+  customId: string | null;
+  planId: string | null;
+  startTime: string | null;
+  /** When PayPal will next charge: the end of the paid period. */
+  nextBillingTime: string | null;
+  lastPayment: { amount: string; currency: string; time: string } | null;
+  failedPayments: number;
+  statusChangeNote: string | null;
+  statusUpdateTime: string | null;
+};
+
+export type PayPalSale = { id: string; amount: string; currency: string; time: string };
+
+/** PayPal's ids are short alphanumerics; anything else never reaches a URL path. */
+const PAYPAL_ID = /^[A-Za-z0-9-]{1,64}$/;
+
+function subscriptionPath(id: string, suffix = ""): string {
+  if (!PAYPAL_ID.test(id)) throw new PayPalBusinessError(400, "INVALID_RESOURCE_ID");
+  return `/v1/billing/subscriptions/${encodeURIComponent(id)}${suffix}`;
+}
+
+export async function createPayPalSubscription(
+  env: PayPalEnv,
+  params: { planId: string; customId: string; email?: string; returnUrl: string; cancelUrl: string; requestId: string; startTime?: string },
+): Promise<{ id: string; approveUrl: string }> {
+  const res = await payPalApiFetch(env, "/v1/billing/subscriptions", {
+    method: "POST",
+    headers: { "content-type": "application/json", "PayPal-Request-Id": params.requestId, Prefer: "return=representation" },
+    body: JSON.stringify({
+      plan_id: params.planId,
+      custom_id: params.customId,
+      ...(params.startTime ? { start_time: params.startTime } : {}),
+      ...(params.email ? { subscriber: { email_address: params.email } } : {}),
+      application_context: {
+        brand_name: "Bugmole",
+        shipping_preference: "NO_SHIPPING",
+        user_action: "SUBSCRIBE_NOW",
+        return_url: params.returnUrl,
+        cancel_url: params.cancelUrl,
+      },
+    }),
+  });
+  if (!res.ok) return fail(res, "create subscription");
+  const body = (await res.json()) as { id: string; links?: Array<{ href: string; rel: string }> };
+  const approveUrl = body.links?.find((link) => link.rel === "approve")?.href;
+  if (!approveUrl) throw new Error(`PayPal subscription ${body.id} came back without an approve link`);
+  return { id: body.id, approveUrl };
+}
+
+/** Null when PayPal has no such subscription. */
+export async function getPayPalSubscription(env: PayPalEnv, id: string): Promise<PayPalSubscriptionState | null> {
+  if (!PAYPAL_ID.test(id)) return null;
+  const res = await payPalApiFetch(env, subscriptionPath(id));
+  if (res.status === 404) return null;
+  if (!res.ok) return fail(res, "get subscription");
+  const body = (await res.json()) as {
+    id: string;
+    status: string;
+    custom_id?: string;
+    plan_id?: string;
+    start_time?: string;
+    status_change_note?: string;
+    status_update_time?: string;
+    billing_info?: {
+      next_billing_time?: string;
+      failed_payments_count?: number;
+      last_payment?: { amount?: { value: string; currency_code: string }; time?: string };
+    };
+  };
+  const last = body.billing_info?.last_payment;
+  return {
+    id: body.id,
+    status: body.status,
+    customId: body.custom_id ?? null,
+    planId: body.plan_id ?? null,
+    startTime: body.start_time ?? null,
+    nextBillingTime: body.billing_info?.next_billing_time ?? null,
+    lastPayment: last?.amount ? { amount: last.amount.value, currency: last.amount.currency_code, time: last.time ?? "" } : null,
+    failedPayments: body.billing_info?.failed_payments_count ?? 0,
+    statusChangeNote: body.status_change_note ?? null,
+    statusUpdateTime: body.status_update_time ?? null,
+  };
+}
+
+/** The most recent COMPLETED sale on a subscription in [since, until], or null. */
+export async function latestCompletedSale(env: PayPalEnv, id: string, since: Date, until: Date): Promise<PayPalSale | null> {
+  const query = new URLSearchParams({ start_time: since.toISOString(), end_time: until.toISOString() });
+  const res = await payPalApiFetch(env, subscriptionPath(id, `/transactions?${query}`));
+  // Some PayPal environments report "no transactions yet" as 404.
+  if (res.status === 404) return null;
+  if (!res.ok) return fail(res, "list subscription transactions");
+  const body = (await res.json()) as {
+    transactions?: Array<{ id: string; status: string; time: string; amount_with_breakdown?: { gross_amount?: { value: string; currency_code: string } } }>;
+  };
+  const latest = (body.transactions ?? [])
+    .filter((t) => t.status === "COMPLETED" && t.amount_with_breakdown?.gross_amount)
+    .sort((a, b) => Date.parse(b.time) - Date.parse(a.time))[0];
+  if (!latest) return null;
+  const gross = latest.amount_with_breakdown!.gross_amount!;
+  return { id: latest.id, amount: gross.value, currency: gross.currency_code, time: latest.time };
+}
+
+/** Already cancelled counts as done: the outcome we wanted (no more charges) is already true. */
+export async function cancelPayPalSubscription(env: PayPalEnv, id: string, reason: string): Promise<void> {
+  const res = await payPalApiFetch(env, subscriptionPath(id, "/cancel"), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ reason: reason.slice(0, 128) }),
+  });
+  if (res.ok) return;
+  if (res.status === 422 && issueOf(await res.clone().text()) === "SUBSCRIPTION_STATUS_INVALID") return;
+  return fail(res, "cancel subscription");
+}
+
+/**
+ * Refunds part of a subscription payment. Subscription payments are sales,
+ * refunded through /v1/payments/sale/{id}/refund (v2 only refunds captures).
+ * `requestId` makes a retry refund once, not twice.
+ */
+export async function refundPayPalSale(
+  env: PayPalEnv,
+  saleId: string,
+  amount: { total: string; currency: string },
+  requestId: string,
+  description: string,
+): Promise<{ id: string; state: string }> {
+  if (!PAYPAL_ID.test(saleId)) throw new PayPalBusinessError(400, "INVALID_RESOURCE_ID");
+  const res = await payPalApiFetch(env, `/v1/payments/sale/${encodeURIComponent(saleId)}/refund`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "PayPal-Request-Id": requestId },
+    body: JSON.stringify({ amount, description: description.slice(0, 255) }),
+  });
+  if (!res.ok) return fail(res, "refund sale");
+  const body = (await res.json()) as { id: string; state: string };
+  if (body.state === "failed") throw new PayPalBusinessError(res.status, "REFUND_FAILED");
+  return { id: body.id, state: body.state };
+}
+
+/**
+ * True only when PayPal says SUCCESS. The event goes back as the exact bytes
+ * it arrived as: the signature covers the original body.
+ */
+export async function verifyPayPalWebhookSignature(env: PayPalEnv, headers: Headers, rawBody: string): Promise<boolean> {
+  const fields = {
+    transmission_id: headers.get("paypal-transmission-id"),
+    transmission_time: headers.get("paypal-transmission-time"),
+    cert_url: headers.get("paypal-cert-url"),
+    auth_algo: headers.get("paypal-auth-algo"),
+    transmission_sig: headers.get("paypal-transmission-sig"),
+    webhook_id: env.PAYPAL_WEBHOOK_ID ?? null,
+  };
+  if (Object.values(fields).some((value) => !value)) return false;
+  const res = await payPalApiFetch(env, "/v1/notifications/verify-webhook-signature", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: `${JSON.stringify(fields).slice(0, -1)},"webhook_event":${rawBody}}`,
+  });
+  if (res.status >= 400 && res.status < 500) {
+    console.error(`[billing] PayPal webhook verification refused: ${res.status} ${await res.text()}`);
+    return false;
+  }
+  if (!res.ok) return fail(res, "verify webhook signature");
+  return ((await res.json()) as { verification_status?: string }).verification_status === "SUCCESS";
+}
+
+export type InvoiceLine = { name: string; description?: string; quantity: number; unitCents: number };
+
+function money(cents: number): string {
+  return (cents / 100).toFixed(2);
+}
+
+/**
+ * Creates and sends a PayPal invoice for usage above the plan's allowance.
+ * The payer gets PayPal's email with a pay link. `invoiceNumber` is ours and
+ * unique, so a retry that already created the invoice is found, not doubled.
+ */
+export async function sendPayPalInvoice(
+  env: PayPalEnv,
+  params: { invoiceNumber: string; email: string; name?: string; note: string; lines: InvoiceLine[]; netDays: 10 | 15 | 30; requestId: string },
+): Promise<{ id: string; url: string | null }> {
+  const res = await payPalApiFetch(env, "/v2/invoicing/invoices", {
+    method: "POST",
+    headers: { "content-type": "application/json", "PayPal-Request-Id": params.requestId, Prefer: "return=representation" },
+    body: JSON.stringify({
+      detail: {
+        invoice_number: params.invoiceNumber,
+        currency_code: "USD",
+        note: params.note,
+        payment_term: { term_type: `NET_${params.netDays}` },
+      },
+      invoicer: { business_name: "Bugmole" },
+      primary_recipients: [{ billing_info: { email_address: params.email, ...(params.name ? { name: { full_name: params.name } } : {}) } }],
+      items: params.lines.map((line) => ({
+        name: line.name.slice(0, 200),
+        ...(line.description ? { description: line.description.slice(0, 1000) } : {}),
+        quantity: String(line.quantity),
+        unit_amount: { currency_code: "USD", value: money(line.unitCents) },
+        unit_of_measure: "QUANTITY",
+      })),
+      configuration: { allow_tip: false, tax_calculated_after_discount: true, tax_inclusive: false },
+    }),
+  });
+  let id: string;
+  if (res.ok) {
+    id = ((await res.json()) as { id: string }).id;
+  } else {
+    // A retry after a created-but-unsent invoice: PayPal rejects the duplicate number; find the original.
+    const text = await res.clone().text();
+    if (res.status !== 422 || issueOf(text) !== "DUPLICATE_INVOICE_NUMBER") return fail(res, "create invoice");
+    const found = await findPayPalInvoice(env, params.invoiceNumber);
+    if (!found) return fail(res, "create invoice");
+    id = found;
+  }
+  const sent = await payPalApiFetch(env, `/v2/invoicing/invoices/${encodeURIComponent(id)}/send`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "PayPal-Request-Id": `${params.requestId}:send` },
+    body: JSON.stringify({ send_to_invoicer: false, send_to_recipient: true }),
+  });
+  // Already sent counts as sent.
+  if (!sent.ok && !(sent.status === 422 && issueOf(await sent.clone().text()) === "INVALID_INVOICE_STATUS")) {
+    return fail(sent, "send invoice");
+  }
+  const payload = sent.ok ? await sent.json().catch(() => ({})) as { href?: string } : {};
+  return { id, url: payload.href ?? null };
+}
+
+async function findPayPalInvoice(env: PayPalEnv, invoiceNumber: string): Promise<string | null> {
+  const res = await payPalApiFetch(env, "/v2/invoicing/search-invoices?page_size=1", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ invoice_number: invoiceNumber }),
+  });
+  if (!res.ok) return null;
+  const body = (await res.json()) as { items?: Array<{ id: string }> };
+  return body.items?.[0]?.id ?? null;
+}
+
+/** PAID, MARKED_AS_PAID, PARTIALLY_PAID, SENT, UNPAID, CANCELLED, REFUNDED… or null when unknown. */
+export async function getPayPalInvoiceStatus(env: PayPalEnv, id: string): Promise<string | null> {
+  if (!PAYPAL_ID.test(id)) return null;
+  const res = await payPalApiFetch(env, `/v2/invoicing/invoices/${encodeURIComponent(id)}`);
+  if (res.status === 404) return null;
+  if (!res.ok) return fail(res, "get invoice");
+  return ((await res.json()) as { status?: string }).status ?? null;
+}

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

@@ -0,0 +1,91 @@
+// PayPal REST client: credentials, the live/sandbox switch, and error
+// classification. Ported from realistiz-dd (src/worker/paypal.ts).
+//
+// Live and sandbox credentials live side by side under different names and
+// PAYPAL_ENV picks the pair, so testing never means re-uploading the live
+// secrets, and a sandbox deploy can't quietly charge real cards.
+
+const LIVE_BASE = "https://api-m.paypal.com";
+const SANDBOX_BASE = "https://api-m.sandbox.paypal.com";
+
+export type PayPalEnv = {
+  PAYPAL_ENV?: string;
+  PAYPAL_CLIENT_ID?: string;
+  PAYPAL_CLIENT_SECRET?: string;
+  PAYPAL_SANDBOX_CLIENT_ID?: string;
+  PAYPAL_SANDBOX_CLIENT_SECRET?: string;
+  PAYPAL_WEBHOOK_ID?: string;
+  /** Billing plan ids created by scripts/billing/paypal-setup.mjs. Not secret. */
+  PAYPAL_PLAN_TEAM_MONTH?: string;
+  PAYPAL_PLAN_TEAM_YEAR?: string;
+  PAYPAL_PLAN_BUSINESS_MONTH?: string;
+  PAYPAL_PLAN_BUSINESS_YEAR?: string;
+  /** Test seam: replaces fetch for every PayPal call. */
+  PAYPAL_FETCH?: typeof fetch;
+};
+
+/**
+ * A refusal from PayPal about the request itself (not approved, already
+ * cancelled, declined). A 5xx is PayPal being unwell and is a plain Error,
+ * worth retrying.
+ */
+export class PayPalBusinessError extends Error {
+  constructor(readonly httpStatus: number, readonly issue: string) {
+    super(`PayPal refused the request: ${httpStatus} ${issue}`);
+  }
+}
+
+type Credentials = { clientId: string; clientSecret: string; apiBase: string };
+
+export function payPalCredentials(env: PayPalEnv): Credentials | null {
+  const sandbox = env.PAYPAL_ENV === "sandbox";
+  const clientId = sandbox ? env.PAYPAL_SANDBOX_CLIENT_ID : env.PAYPAL_CLIENT_ID;
+  const clientSecret = sandbox ? env.PAYPAL_SANDBOX_CLIENT_SECRET : env.PAYPAL_CLIENT_SECRET;
+  if (!clientId || !clientSecret) return null;
+  return { clientId, clientSecret, apiBase: sandbox ? SANDBOX_BASE : LIVE_BASE };
+}
+
+export function isPayPalConfigured(env: PayPalEnv): boolean {
+  return payPalCredentials(env) !== null;
+}
+
+function requireCredentials(env: PayPalEnv): Credentials {
+  const credentials = payPalCredentials(env);
+  if (!credentials) throw new Error(`PayPal credentials missing for env "${env.PAYPAL_ENV ?? "live"}"`);
+  return credentials;
+}
+
+/** Not cached: one extra round trip per billing action is nothing, and a stale token is a class of bug. */
+async function accessToken(env: PayPalEnv): Promise<string> {
+  const { clientId, clientSecret, apiBase } = requireCredentials(env);
+  const res = await (env.PAYPAL_FETCH ?? fetch)(`${apiBase}/v1/oauth2/token`, {
+    method: "POST",
+    headers: { Authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`, "content-type": "application/x-www-form-urlencoded" },
+    body: "grant_type=client_credentials",
+  });
+  if (!res.ok) throw new Error(`PayPal auth failed: ${res.status} ${await res.text()}`);
+  return ((await res.json()) as { access_token: string }).access_token;
+}
+
+/** An authenticated call to a PayPal REST path in the active environment. */
+export async function payPalApiFetch(env: PayPalEnv, path: string, init: RequestInit = {}): Promise<Response> {
+  const headers = new Headers(init.headers);
+  headers.set("Authorization", `Bearer ${await accessToken(env)}`);
+  return (env.PAYPAL_FETCH ?? fetch)(`${requireCredentials(env).apiBase}${path}`, { ...init, headers });
+}
+
+/** PayPal nests the useful part as details[0].issue, e.g. SUBSCRIPTION_STATUS_INVALID. */
+export function issueOf(body: string): string {
+  try {
+    const parsed = JSON.parse(body) as { name?: string; details?: Array<{ issue?: string }> };
+    return parsed.details?.[0]?.issue ?? parsed.name ?? "UNKNOWN";
+  } catch {
+    return "UNPARSEABLE";
+  }
+}
+
+export async function fail(res: Response, what: string): Promise<never> {
+  const text = await res.text();
+  if (res.status >= 400 && res.status < 500) throw new PayPalBusinessError(res.status, issueOf(text));
+  throw new Error(`PayPal ${what} failed: ${res.status} ${text}`);
+}

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

@@ -0,0 +1,143 @@
+// PayPal as a billing provider: Subscriptions for plan fees, Invoicing for
+// usage above the allowance, sale refunds for upgrades.
+import type { BillingInterval } from "../../../billing/plan-catalog.js";
+import type { Env } from "../../core.js";
+import { registerBillingProvider, toCents, fromCents, type BillingProvider, type PaidPlan, type ProviderSubscription } from "../provider.js";
+import { isPayPalConfigured, type PayPalEnv } from "./client.js";
+import {
+  cancelPayPalSubscription,
+  createPayPalSubscription,
+  getPayPalInvoiceStatus,
+  getPayPalSubscription,
+  latestCompletedSale,
+  refundPayPalSale,
+  sendPayPalInvoice,
+  verifyPayPalWebhookSignature,
+} from "./api.js";
+
+const PLAN_VARS: Record<`${PaidPlan}:${BillingInterval}`, keyof PayPalEnv> = {
+  "team:month": "PAYPAL_PLAN_TEAM_MONTH",
+  "team:year": "PAYPAL_PLAN_TEAM_YEAR",
+  "business:month": "PAYPAL_PLAN_BUSINESS_MONTH",
+  "business:year": "PAYPAL_PLAN_BUSINESS_YEAR",
+};
+
+function payPal(env: Env): PayPalEnv {
+  return env as Env & PayPalEnv;
+}
+
+function planIdFor(env: Env, plan: PaidPlan, interval: BillingInterval): string | undefined {
+  return (payPal(env)[PLAN_VARS[`${plan}:${interval}`]] as string | undefined) || undefined;
+}
+
+function planOfId(env: Env, planId: string | null): ProviderSubscription["plan"] {
+  if (!planId) return null;
+  for (const [key, variable] of Object.entries(PLAN_VARS)) {
+    if (payPal(env)[variable] === planId) {
+      const [plan, interval] = key.split(":") as [PaidPlan, BillingInterval];
+      return { plan, interval };
+    }
+  }
+  return null;
+}
+
+const STATUS: Record<string, ProviderSubscription["status"]> = {
+  APPROVAL_PENDING: "pending",
+  APPROVED: "pending",
+  ACTIVE: "active",
+  SUSPENDED: "past_due",
+  CANCELLED: "ended",
+  EXPIRED: "ended",
+};
+
+const INVOICE_STATUS: Record<string, "open" | "paid" | "void"> = {
+  PAID: "paid",
+  MARKED_AS_PAID: "paid",
+  CANCELLED: "void",
+  REFUNDED: "void",
+  MARKED_AS_REFUNDED: "void",
+};
+
+export const payPalProvider: BillingProvider = {
+  id: "paypal",
+
+  canSell(env, plan, interval) {
+    return isPayPalConfigured(payPal(env)) && Boolean(planIdFor(env, plan, interval));
+  },
+
+  async createSubscription(env, params) {
+    const planId = planIdFor(env, params.plan, params.interval);
+    if (!planId) throw new Error(`PayPal has no billing plan for ${params.plan} (${params.interval})`);
+    const created = await createPayPalSubscription(payPal(env), {
+      planId,
+      customId: params.reference,
+      email: params.email,
+      returnUrl: params.returnUrl,
+      cancelUrl: params.cancelUrl,
+      requestId: params.requestId,
+      startTime: params.startAt,
+    });
+    return { subscriptionId: created.id, approveUrl: created.approveUrl };
+  },
+
+  async getSubscription(env, id) {
+    const remote = await getPayPalSubscription(payPal(env), id);
+    if (!remote) return null;
+    const ended = STATUS[remote.status] === "ended";
+    return {
+      id: remote.id,
+      status: STATUS[remote.status] ?? "pending",
+      reference: remote.customId,
+      plan: planOfId(env, remote.planId),
+      startedAt: remote.startTime,
+      paidThrough: remote.nextBillingTime,
+      endNote: ended ? remote.statusChangeNote : null,
+      endedAt: ended ? remote.statusUpdateTime : null,
+    };
+  },
+
+  async latestPayment(env, subscriptionId, since, until) {
+    const sale = await latestCompletedSale(payPal(env), subscriptionId, since, until);
+    return sale ? { reference: sale.id, amountCents: toCents(sale.amount), currency: sale.currency, paidAt: sale.time } : null;
+  },
+
+  cancelSubscription(env, id, reason) {
+    return cancelPayPalSubscription(payPal(env), id, reason);
+  },
+
+  async refund(env, payment, amountCents, requestId, description) {
+    const result = await refundPayPalSale(payPal(env), payment.reference, { total: fromCents(amountCents), currency: payment.currency }, requestId, description);
+    return { reference: result.id };
+  },
+
+  async chargeUsage(env, params) {
+    const sent = await sendPayPalInvoice(payPal(env), { ...params, netDays: 15 });
+    return { reference: sent.id, url: sent.url };
+  },
+
+  async usageChargeStatus(env, reference) {
+    const status = await getPayPalInvoiceStatus(payPal(env), reference);
+    return status === null ? null : INVOICE_STATUS[status] ?? "open";
+  },
+
+  async verifyWebhook(env, request, rawBody) {
+    if (!payPal(env).PAYPAL_WEBHOOK_ID || !isPayPalConfigured(payPal(env))) return null;
+    let event: { id?: string; event_type?: string; resource?: { id?: string; billing_agreement_id?: string; invoice?: { id?: string } } };
+    try {
+      event = JSON.parse(rawBody);
+    } catch {
+      return null;
+    }
+    if (!(await verifyPayPalWebhookSignature(payPal(env), request.headers, rawBody))) return null;
+    const type = event.event_type ?? "";
+    return {
+      id: event.id ?? "",
+      type,
+      ...(type.startsWith("BILLING.SUBSCRIPTION.") && event.resource?.id ? { subscriptionId: event.resource.id } : {}),
+      ...(type.startsWith("PAYMENT.SALE.") && event.resource?.billing_agreement_id ? { subscriptionId: event.resource.billing_agreement_id } : {}),
+      ...(type.startsWith("INVOICING.INVOICE.") ? { usageChargeId: event.resource?.invoice?.id ?? event.resource?.id } : {}),
+    };
+  },
+};
+
+registerBillingProvider(payPalProvider);