@volter/twin-stripe 0.1.2 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 # @volter/twin-stripe
 
 The **Stripe twin** — a local, spec-correct replica of the Stripe REST API on the
-shared [`@volter/twin`](../control-plane) kernel. The real `stripe` SDK works against it
+shared [`@volter/world-core`](../../world-core) kernel. The real `stripe` SDK works against it
 unmodified; it's the QA stack's authoritative local Stripe (it replaced the old
 hand-made in-process mock).
 
@@ -12,7 +12,18 @@ hand-made in-process mock).
   payment_intents, setup_intents, payment_methods, products, prices, invoices,
   invoiceitems, subscriptions, refunds, coupons, promotion_codes, identity
   verification sessions, ephemeral_keys, checkout sessions, billing/customer-portal
-  sessions + configurations.
+  sessions + configurations, and the legacy **Plans** API (`semantics/plans.ts`: a plan is the recurring
+  price it is; plan writes send `plan.created`/`plan.updated`/`plan.deleted`; a deleted plan's price stays
+  readable, inactive, for its existing subscribers).
+- **Hosted pages** (`src/screens/`): Stripe's own pages an application sends a person to, served at their
+  vendor urls — Checkout's payment page (`checkout.stripe.com/c/pay/{id}`: the customer pays, the session
+  completes and `checkout.session.completed` fires), the Customer Portal (`billing.stripe.com/p/session/{id}`),
+  Connect hosted onboarding (`connect.stripe.com/setup/…`), Identity (`verify.stripe.com/start/{id}`) and the
+  Financial Connections bank-linking flow Stripe.js opens.
+- **Stripe.js** (`stripe-js.ts`): `js.stripe.com` serves the client library at `/v3`, `/v3/`, `/v3/stripe.js` and
+  `/<release train>/stripe.js` — the paths the `@stripe/stripe-js` loader loads or accepts — with
+  `redirectToCheckout({ sessionId })` sending the page to the hosted Checkout page; any other member throws,
+  naming itself (`stripe.js.loader`).
 - **Writes** are local transactions (action log); reads are the projection (R3/R5/R18).
 - **Card declines** (`stripe-twin.ts`): Stripe's documented test cards get vendor-faithful
   outcomes on charge create / PaymentIntent confirm — `4242…4242` (and `pm_card_visa`/`tok_visa`)
@@ -20,10 +31,35 @@ hand-made in-process mock).
   `pm_card_*`/`tok_*` tokens) return the real `card_error` envelope (HTTP 402) and leave a
   confirmed PaymentIntent at `requires_payment_method`. Unknown cards succeed. See
   `_card.declines-test-set-only` in `stripe-known-deviations.json`.
+- **Manual capture** (`semantics/payment-intents.ts`, `semantics/charges.ts`): confirming a `capture_method=manual`
+  intent authorizes an uncaptured charge (`captured: false`, nothing on the balance); capture takes that charge
+  (`charge.captured`; a partial capture releases the rest with no Refund, Stripe's basil change), and an incremental
+  authorization grows its amount. An uncaptured charge is never refunded out of the balance: cancelling a
+  `requires_capture` intent releases the authorization (no Refund; `amount_captured` 0, `refunded` false) and its
+  charge's capture is then refused with `payment_intent_unexpected_state`, a refund of a PaymentIntent's uncaptured
+  charge is refused (cancel the intent, as Stripe's refunds guide says), and a `capture=false` charge's refund releases
+  it, after which its capture is refused with `charge_already_refunded`. An uncaptured charge is refused as a transfer's
+  `source_transaction` (the twin's rule; the docs are silent).
 - **Idempotency keys**: the `Idempotency-Key` header is honored on POST — a replay with the
   same key returns the stored response without re-applying the write (`_idempotency.stored-per-root`).
 - **Events** (`stripe-events.ts`): fires Stripe `event` objects on write
-  (`payment_intent.succeeded`, `customer.subscription.created`, `invoice.paid`, …).
+  (`payment_intent.succeeded`, `customer.subscription.created`, `invoice.paid`, …). A charge fires the event
+  Stripe sends for it — `charge.succeeded` (made, or authorized under manual capture), `charge.failed` (a declined
+  attempt), `charge.captured` (an authorization captured) — never an invented `charge.created`.
+- **Connect webhooks**: an event of a connected account (a write made with its `Stripe-Account` header, its own
+  `account.updated`, or a row kept on its books such as the automatic payout time makes for it) carries the
+  top-level `account` and reaches only endpoints created with `connect=true`; the platform's reach only the others
+  (`stripe.connect.webhook_scope`, `stripe.connect.event_scope`). `GET /v1/events` and `/v1/events/{id}` answer the
+  acting account's events: with the header that account's, without it the platform's. An event's id is minted once
+  per World (`evt_twin_<n>`) and is the delivered webhook's id and the stored event's alike (`stripe.events.ids`).
+  `world-stripe emit` re-fires a connected account's object with its `account`; it does not yet route it to Connect
+  endpoints only (the kernel's emit seam has no endpoint scope).
+- **Signing secrets in a World**: Stripe mints an endpoint's `secret`; in a World the app's env is the World's, so an
+  endpoint is given the World's value, which the app already verifies with: `STRIPE_WEBHOOK_SECRET` (or
+  `STRIPE_WEBHOOK_SIGNING_SECRET`, `STRIPE_ENDPOINT_SECRET`, `STRIPE_WEBHOOK_SECRET_KEY`,
+  `NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET`), and for a `connect=true` endpoint `STRIPE_CONNECT_WEBHOOK_SECRET` (or
+  `STRIPE_WEBHOOK_SECRET_CONNECT`, `STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET`) first. With none set the twin mints
+  `whsec_twin_<id>`. Where Stripe stops and the twin decides: Stripe lets no one choose a secret.
 - **Conformance** (`stripe-conformance.ts`): field name + type checked vs Stripe's
   real OpenAPI (standing gate).
 - **UI mirror** (`stripe-mirror-ui.ts`): a Stripe-dashboard-style React app over the
@@ -42,10 +78,15 @@ Point the real `stripe` SDK at it with `{ host, port, protocol: 'http' }`.
 
 ## Interaction surfaces
 
-1. **SDK/API** — *zero edits (preferred):* `STRIPE_TWIN_URL=http://127.0.0.1:PORT node --require @volter/twin/inject your-app` redirects the real `stripe` SDK from `api.stripe.com` to the twin (`cookbook/zero-edit-inject`). For the browser too: `volter-twin proxy --target <app> --map stripe=http://127.0.0.1:PORT` (browser + backend share one twin). *Or* override directly: `new Stripe(key, { host: '127.0.0.1', port: PORT, protocol: 'http' })`.
-2. **API + CLI** — `world-stripe serve` (writable) + drive with `volter-twin status|plan|refs stripe`, then push.
+1. **SDK/API** — *zero edits (preferred):* `STRIPE_TWIN_URL=http://127.0.0.1:PORT node --require @volter/world-core/inject your-app` redirects the real `stripe` SDK from `api.stripe.com` to the twin (`cookbook/zero-edit-inject`). For browser routing, follow [run a full stack](../../../docs/guides/run-a-full-stack.md). *Or* override directly: `new Stripe(key, { host: '127.0.0.1', port: PORT, protocol: 'http' })`.
+2. **API + CLI** — run the twin in a World and inspect it with `volter world log` and `diff`. Use the [deployment guide](../../../docs/guides/deploy-from-a-shared-world.md) for changeset review and deployment.
 3. **Read-only** — `world-stripe serve --read-only`: unlimited local reads, no rate limits; writes refuse like Stripe (4xx).
 4. **UI mirror** — `world-stripe mirror` renders a Stripe-dashboard-style view of the twin's state.
+5. **Time's events** — `POST /_twin/drain` sends what World time produced since the last drain: `balance.available`
+   to each account whose settled funds added to its balance (never for negative transactions alone), `payout.paid` for
+   each payout that arrived, a connected account's with its `account` to its Connect endpoints
+   (`stripe.events.time_drain`). A read sees time's moves without it; a runner's drainer calls it so the events
+   arrive, as the qstash and vercel twins' drain doors do.
 
 (See Getting Started → "Twin interaction surfaces".)
 
@@ -53,9 +94,8 @@ Stable on the twin rubric: fidelity, read/write/fork, sync, observability, event
 
 ## Coverage
 
-Goal: **honest, explicitly tracked coverage of Stripe's core feature surface.** The only
-accepted carve-outs are the explicit **out-of-scope** items listed below. Anything not done
-or carved out is a gap to close.
+Goal: **honest, explicitly tracked coverage of Stripe's core feature surface.** Every capability
+is either done or a tracked todo; anything not done is a gap to close.
 
 **Done** — core resources: **customers**, **charges**, **payment_intents** (+ confirm),
 **setup_intents** (+ confirm), **payment_methods** (+ detach), **subscriptions** (create/
@@ -68,7 +108,10 @@ line_items), **Customer Portal** (`billing_portal` sessions + configurations cre
 list/update), **Connect** (connected **accounts** create/retrieve/list/update/delete +
 `login_links`, and **transfers** platform→connected-account create/retrieve/list filtered by
 destination; a new account starts un-onboarded with charges/payouts disabled + a `requirements`
-hash), plus **ephemeral_keys**, **identity verification_sessions**, **file_links**
+hash; a transfer's `source_transaction` waives the balance check only while its charge is unsettled,
+takes the charge's `transfer_group` or writes `group_<payment intent>` onto both, and counts reversals
+back as room; connected-account balances, payouts (manual and automatic) and payout reversal, top-ups,
+account sessions, persons, external accounts, application fees and hosted onboarding), plus **ephemeral_keys**, **identity verification_sessions**, **file_links**
 (synthesized) and **coupons**/**promotion_codes** (retrieve/list, seed-only). Cursor pagination
 (`limit`/`starting_after`/`ending_before` + `has_more`); per-resource list filters; `expand[]`
 on the modeled paths; vendor-faithful **test-card declines** (`4242…` succeeds; documented
@@ -107,21 +150,15 @@ helpers) are tracked todos in `stripe-capabilities.ts`. **Terminal**
 (locations/readers/connection tokens + process_payment_intent) is likewise modeled — the old
 "Planned" listing for both families was stale.
 
-**Planned** (known-missing, will do) — **Treasury**
-(financial accounts), **Climate**, **Financial Connections**, **Entitlements**, **Billing**
-credit grants + usage alerts, **Connect** remaining surfaces (account sessions, connected-account
-payouts, top-ups, payout reverse), **Reporting/Sigma**, the legacy **Sources** API, and
-additional list endpoints/filters as needed. (See `stripe-capabilities.ts` for the full honest
-todo list — every entry not explicitly out-of-scope is a tracked gap.)
-
-**Out of scope** (deliberately not modeled, with reason) —
-- Pixel-rendering Stripe-**hosted** Checkout / Customer Portal *pages*: the hosted HTML is
-  Stripe's, not an API object — the twin models the **Session/API object + redirect `url`**
-  instead (now **Done**; the page pixels stay out of scope). See
-  `_checkout.hosted-page-pixels` in `stripe-known-deviations.json`.
-- Real **money settlement / bank movement** (proposed — pending owner approval): actually moving
-  funds is real-world infra, not the API — the payout/balance_transaction/balance *objects* and
-  their lifecycle are modeled.
+Also modelled: **Treasury** financial accounts and money movement, **Climate** orders,
+**Financial Connections** sessions/accounts/transactions, **Entitlements**, **Billing** meters,
+credit grants and usage alerts, **Reporting** report runs, and the legacy **Sources** API.
+
+**Planned** (known-missing, will do) — **Sigma scheduled query runs** (`GET /v1/sigma/scheduled_query_runs`
+list + retrieve, with the run object's status/result-file lifecycle), Treasury financial addresses and
+reversals, Financial Connections refresh, the Issuing gaps above, connector pulls of payment methods and
+setup intents, and additional list endpoints/filters as needed. (See `stripe-capabilities.ts` for the full
+honest todo list — every entry is a tracked gap.)
 
 ## Rate budget — the fail-closed backstop on live calls
 
@@ -136,9 +173,9 @@ validated by *method identity*, so a subclass or a `Proxy` that replaces `checkB
 
 The declared numbers: **120 weighted units / 60s** = 2 requests/second — 2% of Stripe's documented 100/s live mode and 8% of the 25/s a sandbox key or any single endpoint gets. `POST`/`DELETE` cost 2 (not a published ratio — a judgement call about blast radius: a write creates a charge, refund or receipt e-mail and cannot be taken back) and `POST /v1/payouts` costs 5 (documented at 15 creates/second). Stripe's own window is a **second** while this one is a minute, so an intra-second burst reaches Stripe's limiter first; the 429 cooldown is the backstop for that shape.
 
-The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/twin` →
-`control-plane/src/rateBudget.ts`); what lives here in [`src/stripe-budget.ts`](src/stripe-budget.ts) is this vendor's
+The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
+`packages/world-core/src/rateBudget.ts`); what lives here in [`src/stripe-budget.ts`](src/stripe-budget.ts) is this vendor's
 **declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
 the vendor-bound `StripeBudget`. The rule is ratified as
-[ARCHITECTURE.md](../../../ARCHITECTURE.md) **D8**, and the kernel module's header documents what the
+[../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and the kernel module's header documents what the
 guard does *not* guarantee — read that before trusting it.

package/client/dashboard-api.ts

@@ -0,0 +1,286 @@
+// The Stripe Dashboard's reads and writes, through Stripe's own API on this origin (docs/contributing/
+// architecture.md, "Screens": a workspace reads and writes only through the pack's operations). The calls
+// the Dashboard makes for the pages it shows: the balance, payments (PaymentIntents and the Charges they
+// made), refunds, customers and their saved payment methods, subscriptions, invoices, products and prices,
+// and events for a detail page's timeline. The writes a person makes here: refund a payment
+// (POST /v1/refunds), cancel a subscription (DELETE /v1/subscriptions/{id}, or schedule it with
+// cancel_at_period_end), create a customer or a product. Bodies are form-encoded as Stripe's API takes them;
+// an `error` envelope, never the HTTP status alone, is what refuses.
+
+type Json = any;
+export type StripeObject = Record<string, any>;
+
+export function wireBaseFrom(hasBaseElement: boolean, baseURI: string): string {
+  return hasBaseElement ? new URL('.', baseURI).pathname.replace(/\/$/, '') : '';
+}
+// Served at the origin root the base is ''; served under a path prefix (an embedder's earlier <base>) every
+// call resolves inside that prefix.
+export const API_BASE = typeof document === 'undefined' ? '' : wireBaseFrom(document.querySelector('base[href]') !== null, document.baseURI);
+
+export class StripeApiError extends Error {
+  constructor(message: string, readonly code?: string) { super(message); }
+}
+
+async function call(method: string, path: string, body?: Record<string, string | number | boolean | undefined>): Promise<Json> {
+  const init: RequestInit = { method, headers: { accept: 'application/json' } };
+  if (body) {
+    const form = Object.entries(body).filter(([, v]) => v !== undefined && v !== '').map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&');
+    init.body = form;
+    (init.headers as Record<string, string>)['content-type'] = 'application/x-www-form-urlencoded';
+  }
+  const res = await fetch(`${API_BASE}${path}`, init);
+  const json = await res.json().catch(() => ({ error: { message: `${res.status} ${res.statusText}` } }));
+  if (json && json.error) throw new StripeApiError(String(json.error.message ?? 'Request failed'), json.error.code);
+  return json;
+}
+
+export const retrieve = (path: string): Promise<StripeObject> => call('GET', path);
+/** A list endpoint's `data`, newest first as Stripe returns it (one page of up to 100). */
+export async function list(path: string): Promise<StripeObject[]> {
+  const sep = path.includes('?') ? '&' : '?';
+  const body = await call('GET', `${path}${sep}limit=100`);
+  return Array.isArray(body?.data) ? body.data : [];
+}
+const optional = <T>(p: Promise<T>, fallback: T): Promise<T> => p.catch(() => fallback);
+
+// ── what a payment row is ────────────────────────────────────────────────────
+/** One row of the Payments list: a PaymentIntent (or a Charge made without one) with what the Dashboard
+ *  shows beside it — its charge, refunds, card and customer. */
+export type Payment = {
+  id: string;
+  amount: number;
+  currency: string;
+  status: PaymentStatus;
+  description?: string;
+  created: number;
+  customer?: StripeObject;
+  charge?: StripeObject;
+  intent?: StripeObject;
+  paymentMethod?: StripeObject;
+  amountRefunded: number;
+  refundedAt?: number;
+  declineReason?: string;
+  declineMessage?: string;
+};
+export type PaymentStatus = 'succeeded' | 'refunded' | 'partially_refunded' | 'failed' | 'incomplete' | 'uncaptured' | 'canceled' | 'disputed' | 'processing';
+
+export function paymentStatusOf(intent: StripeObject | undefined, charge: StripeObject | undefined): PaymentStatus {
+  if (charge?.disputed) return 'disputed';
+  if (charge?.refunded) return 'refunded';
+  if (charge && Number(charge.amount_refunded) > 0) return 'partially_refunded';
+  if (charge?.status === 'failed') return 'failed';
+  if (intent) {
+    if (intent.status === 'succeeded') return 'succeeded';
+    if (intent.status === 'canceled') return 'canceled';
+    if (intent.status === 'requires_capture') return 'uncaptured';
+    if (intent.status === 'processing') return 'processing';
+    if (intent.last_payment_error) return 'failed';
+    return 'incomplete';
+  }
+  return charge?.status === 'succeeded' ? 'succeeded' : charge?.status === 'pending' ? 'processing' : 'failed';
+}
+
+const DECLINE_REASONS: Record<string, string> = {
+  generic_decline: 'Generic decline', insufficient_funds: 'Insufficient funds', lost_card: 'Lost card', stolen_card: 'Stolen card',
+  expired_card: 'Expired card', incorrect_cvc: 'Incorrect CVC', processing_error: 'Processing error', card_declined: 'Card declined',
+};
+export const declineReasonText = (code: string | undefined): string | undefined => (code ? DECLINE_REASONS[code] ?? code.replace(/_/g, ' ') : undefined);
+
+type Directory = { customers: Map<string, StripeObject>; paymentMethods: Map<string, StripeObject> };
+
+async function paymentMethodsById(ids: Iterable<string>): Promise<Map<string, StripeObject>> {
+  const unique = [...new Set([...ids].filter((id) => typeof id === 'string' && id.startsWith('pm_')))];
+  const found = await Promise.all(unique.map((id) => optional(retrieve(`/v1/payment_methods/${id}`), undefined as StripeObject | undefined)));
+  return new Map(found.filter((pm): pm is StripeObject => Boolean(pm?.id)).map((pm) => [pm.id, pm]));
+}
+
+function paymentOf(intent: StripeObject | undefined, charge: StripeObject | undefined, refunds: StripeObject[], dir: Directory): Payment {
+  const base = intent ?? charge!;
+  const customerId = typeof base.customer === 'string' ? base.customer : base.customer?.id;
+  const pmId = typeof base.payment_method === 'string' ? base.payment_method : charge?.payment_method;
+  const error = intent?.last_payment_error;
+  const refundsOf = refunds.filter((r) => (intent && r.payment_intent === intent.id) || (charge && r.charge === charge.id));
+  return {
+    id: String(base.id),
+    amount: Number(base.amount) || 0,
+    currency: String(base.currency ?? 'usd'),
+    status: paymentStatusOf(intent, charge),
+    description: base.description ?? charge?.description ?? undefined,
+    created: Number(base.created) || 0,
+    customer: customerId ? dir.customers.get(customerId) ?? { id: customerId } : undefined,
+    charge, intent,
+    paymentMethod: pmId ? dir.paymentMethods.get(pmId) : undefined,
+    amountRefunded: Number(charge?.amount_refunded) || refundsOf.reduce((n, r) => n + (r.status === 'failed' ? 0 : Number(r.amount) || 0), 0),
+    refundedAt: refundsOf.length ? Math.max(...refundsOf.map((r) => Number(r.created) || 0)) : undefined,
+    declineReason: declineReasonText(error?.decline_code ?? error?.code ?? charge?.failure_code),
+    declineMessage: error?.message ?? charge?.failure_message ?? undefined,
+  };
+}
+
+/** The Payments list: every PaymentIntent, and every Charge made without one. */
+export async function loadPayments(): Promise<Payment[]> {
+  const [intents, charges, refunds, customers] = await Promise.all([
+    list('/v1/payment_intents'), list('/v1/charges'), optional(list('/v1/refunds'), []), list('/v1/customers'),
+  ]);
+  const chargeById = new Map(charges.map((c) => [c.id, c]));
+  const pmIds = [...intents.map((i) => i.payment_method), ...charges.map((c) => c.payment_method)];
+  const dir: Directory = { customers: new Map(customers.map((c) => [c.id, c])), paymentMethods: await paymentMethodsById(pmIds) };
+  const rows = intents.map((pi) => {
+    const charge = (typeof pi.latest_charge === 'string' ? chargeById.get(pi.latest_charge) : pi.latest_charge) ?? charges.find((c) => c.payment_intent === pi.id);
+    return paymentOf(pi, charge, refunds, dir);
+  });
+  for (const ch of charges) if (!ch.payment_intent) rows.push(paymentOf(undefined, ch, refunds, dir));
+  return rows.sort((a, b) => b.created - a.created);
+}
+
+export type PaymentDetail = Payment & { refunds: StripeObject[]; events: StripeObject[]; invoice?: StripeObject };
+
+/** One payment's page: the intent (or charge), its charge, refunds, card, customer and the events about it. */
+export async function loadPayment(id: string): Promise<PaymentDetail> {
+  let intent: StripeObject | undefined;
+  let charge: StripeObject | undefined;
+  if (id.startsWith('ch_') || id.startsWith('py_')) {
+    charge = await retrieve(`/v1/charges/${id}`);
+    if (typeof charge.payment_intent === 'string') intent = await optional(retrieve(`/v1/payment_intents/${charge.payment_intent}`), undefined);
+  } else {
+    intent = await retrieve(`/v1/payment_intents/${id}`);
+    const chargeId = typeof intent.latest_charge === 'string' ? intent.latest_charge : intent.latest_charge?.id;
+    if (chargeId) charge = await optional(retrieve(`/v1/charges/${chargeId}`), undefined);
+  }
+  const base = intent ?? charge!;
+  const customerId = typeof base.customer === 'string' ? base.customer : undefined;
+  const pmId = typeof base.payment_method === 'string' ? base.payment_method : charge?.payment_method;
+  const refundPath = intent ? `/v1/refunds?payment_intent=${intent.id}` : `/v1/refunds?charge=${charge!.id}`;
+  const [customer, pms, refunds, events, invoice] = await Promise.all([
+    customerId ? optional(retrieve(`/v1/customers/${customerId}`), { id: customerId }) : Promise.resolve(undefined),
+    paymentMethodsById(pmId ? [pmId] : []),
+    optional(list(refundPath), []),
+    optional(list('/v1/events'), []),
+    typeof base.invoice === 'string' ? optional(retrieve(`/v1/invoices/${base.invoice}`), undefined) : Promise.resolve(undefined),
+  ]);
+  const dir: Directory = { customers: new Map(customer ? [[customer.id, customer]] : []), paymentMethods: pms };
+  const related = new Set<string>([base.id, charge?.id, intent?.id, ...refunds.map((r) => r.id)].filter(Boolean) as string[]);
+  return {
+    ...paymentOf(intent, charge, refunds, dir),
+    refunds,
+    events: events.filter((e) => related.has(e?.data?.object?.id)).sort((a, b) => b.created - a.created),
+    invoice,
+  };
+}
+
+// ── customers ────────────────────────────────────────────────────────────────
+export type CustomerRow = StripeObject & { defaultCard?: StripeObject; totalSpend: number; payments: number; refunds: number; currency: string };
+
+export async function loadCustomers(): Promise<CustomerRow[]> {
+  const [customers, charges, intents] = await Promise.all([list('/v1/customers'), list('/v1/charges'), list('/v1/payment_intents')]);
+  const pmIds = customers.map((c) => c.invoice_settings?.default_payment_method).filter((x) => typeof x === 'string');
+  const pms = await paymentMethodsById(pmIds);
+  return customers.map((c) => {
+    const mine = charges.filter((ch) => ch.customer === c.id && ch.status === 'succeeded');
+    const pmId = c.invoice_settings?.default_payment_method;
+    return {
+      ...c,
+      defaultCard: typeof pmId === 'string' ? pms.get(pmId) : undefined,
+      totalSpend: mine.reduce((n, ch) => n + (Number(ch.amount_captured ?? ch.amount) || 0) - (Number(ch.amount_refunded) || 0), 0),
+      payments: intents.filter((i) => i.customer === c.id && i.status === 'succeeded').length || mine.length,
+      refunds: mine.reduce((n, ch) => n + (Number(ch.amount_refunded) || 0), 0),
+      currency: String(mine[0]?.currency ?? c.currency ?? 'usd'),
+    };
+  });
+}
+
+export type CustomerDetail = {
+  customer: StripeObject;
+  paymentMethods: StripeObject[];
+  subscriptions: StripeObject[];
+  invoices: StripeObject[];
+  payments: Payment[];
+  products: Map<string, StripeObject>;
+  events: StripeObject[];
+};
+
+export async function loadCustomer(id: string): Promise<CustomerDetail> {
+  const customer = await retrieve(`/v1/customers/${id}`);
+  const [paymentMethods, subscriptions, invoices, payments, products, events] = await Promise.all([
+    optional(list(`/v1/customers/${id}/payment_methods`), []),
+    optional(list(`/v1/subscriptions?customer=${id}&status=all`), []),
+    optional(list(`/v1/invoices?customer=${id}`), []),
+    loadPayments().then((all) => all.filter((p) => p.customer?.id === id)),
+    optional(list('/v1/products'), []),
+    optional(list('/v1/events'), []),
+  ]);
+  const mine = new Set([id, ...subscriptions.map((s) => s.id), ...invoices.map((i) => i.id), ...payments.map((p) => p.id)]);
+  return {
+    customer, paymentMethods, subscriptions, invoices, payments,
+    products: new Map(products.map((p) => [p.id, p])),
+    events: events.filter((e) => mine.has(e?.data?.object?.id)).sort((a, b) => b.created - a.created),
+  };
+}
+
+// ── billing ──────────────────────────────────────────────────────────────────
+export type Billing = { subscriptions: StripeObject[]; customers: Map<string, StripeObject>; products: Map<string, StripeObject> };
+
+export async function loadSubscriptions(): Promise<Billing> {
+  const [subscriptions, customers, products] = await Promise.all([list('/v1/subscriptions?status=all'), list('/v1/customers'), list('/v1/products')]);
+  return { subscriptions, customers: new Map(customers.map((c) => [c.id, c])), products: new Map(products.map((p) => [p.id, p])) };
+}
+
+export type SubscriptionDetail = { subscription: StripeObject; customer?: StripeObject; invoices: StripeObject[]; products: Map<string, StripeObject>; events: StripeObject[]; paymentMethod?: StripeObject };
+
+export async function loadSubscription(id: string): Promise<SubscriptionDetail> {
+  const subscription = await retrieve(`/v1/subscriptions/${id}`);
+  const customerId = typeof subscription.customer === 'string' ? subscription.customer : subscription.customer?.id;
+  const [customer, invoices, products, events] = await Promise.all([
+    customerId ? optional(retrieve(`/v1/customers/${customerId}`), undefined) : Promise.resolve(undefined),
+    optional(list(`/v1/invoices?subscription=${id}`), []),
+    optional(list('/v1/products'), []),
+    optional(list('/v1/events'), []),
+  ]);
+  const pmId = subscription.default_payment_method ?? customer?.invoice_settings?.default_payment_method;
+  const pms = await paymentMethodsById(typeof pmId === 'string' ? [pmId] : []);
+  return {
+    subscription, customer, invoices, products: new Map(products.map((p) => [p.id, p])),
+    events: events.filter((e) => e?.data?.object?.id === id).sort((a, b) => b.created - a.created),
+    paymentMethod: typeof pmId === 'string' ? pms.get(pmId) : undefined,
+  };
+}
+
+export async function loadInvoices(): Promise<{ invoices: StripeObject[]; customers: Map<string, StripeObject> }> {
+  const [invoices, customers] = await Promise.all([list('/v1/invoices'), list('/v1/customers')]);
+  return { invoices, customers: new Map(customers.map((c) => [c.id, c])) };
+}
+
+export async function loadProducts(): Promise<{ products: StripeObject[]; prices: StripeObject[] }> {
+  const [products, prices] = await Promise.all([list('/v1/products'), list('/v1/prices')]);
+  return { products, prices };
+}
+
+export type HomeData = { balance: StripeObject; payments: Payment[]; customers: StripeObject[]; subscriptions: StripeObject[]; invoices: StripeObject[] };
+export async function loadHome(): Promise<HomeData> {
+  const [balance, payments, customers, subscriptions, invoices] = await Promise.all([
+    retrieve('/v1/balance'), loadPayments(), list('/v1/customers'), optional(list('/v1/subscriptions?status=all'), []), optional(list('/v1/invoices'), []),
+  ]);
+  return { balance, payments, customers, subscriptions, invoices };
+}
+
+export async function loadBalances(): Promise<{ balance: StripeObject; transactions: StripeObject[]; payouts: StripeObject[] }> {
+  const [balance, transactions, payouts] = await Promise.all([retrieve('/v1/balance'), optional(list('/v1/balance_transactions'), []), optional(list('/v1/payouts'), [])]);
+  return { balance, transactions, payouts };
+}
+
+export async function loadDevelopers(): Promise<{ events: StripeObject[]; webhooks: StripeObject[]; account?: StripeObject }> {
+  const [events, webhooks, account] = await Promise.all([optional(list('/v1/events'), []), optional(list('/v1/webhook_endpoints'), []), optional(retrieve('/v1/account'), undefined)]);
+  return { events, webhooks, account };
+}
+
+// ── writes ───────────────────────────────────────────────────────────────────
+/** Refund a payment in full (no amount) or in part. */
+export function createRefund(payment: { intent?: StripeObject; charge?: StripeObject }, amount: number | undefined, reason: string | undefined): Promise<StripeObject> {
+  const target = payment.intent ? { payment_intent: String(payment.intent.id) } : { charge: String(payment.charge?.id) };
+  return call('POST', '/v1/refunds', { ...target, amount, reason });
+}
+/** Cancel now (DELETE) or at the end of the current period (cancel_at_period_end). */
+export function cancelSubscription(id: string, when: 'now' | 'period_end'): Promise<StripeObject> {
+  return when === 'now' ? call('DELETE', `/v1/subscriptions/${id}`) : call('POST', `/v1/subscriptions/${id}`, { cancel_at_period_end: true });
+}
+export const createObject = (collection: string, fields: Record<string, string>): Promise<StripeObject> => call('POST', `/v1/${collection}`, fields);