@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/client/dashboard-api.d.ts

@@ -0,0 +1,107 @@
+export type StripeObject = Record<string, any>;
+export declare function wireBaseFrom(hasBaseElement: boolean, baseURI: string): string;
+export declare const API_BASE: string;
+export declare class StripeApiError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare const retrieve: (path: string) => Promise<StripeObject>;
+/** A list endpoint's `data`, newest first as Stripe returns it (one page of up to 100). */
+export declare function list(path: string): Promise<StripeObject[]>;
+/** 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 declare function paymentStatusOf(intent: StripeObject | undefined, charge: StripeObject | undefined): PaymentStatus;
+export declare const declineReasonText: (code: string | undefined) => string | undefined;
+/** The Payments list: every PaymentIntent, and every Charge made without one. */
+export declare function loadPayments(): Promise<Payment[]>;
+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 declare function loadPayment(id: string): Promise<PaymentDetail>;
+export type CustomerRow = StripeObject & {
+    defaultCard?: StripeObject;
+    totalSpend: number;
+    payments: number;
+    refunds: number;
+    currency: string;
+};
+export declare function loadCustomers(): Promise<CustomerRow[]>;
+export type CustomerDetail = {
+    customer: StripeObject;
+    paymentMethods: StripeObject[];
+    subscriptions: StripeObject[];
+    invoices: StripeObject[];
+    payments: Payment[];
+    products: Map<string, StripeObject>;
+    events: StripeObject[];
+};
+export declare function loadCustomer(id: string): Promise<CustomerDetail>;
+export type Billing = {
+    subscriptions: StripeObject[];
+    customers: Map<string, StripeObject>;
+    products: Map<string, StripeObject>;
+};
+export declare function loadSubscriptions(): Promise<Billing>;
+export type SubscriptionDetail = {
+    subscription: StripeObject;
+    customer?: StripeObject;
+    invoices: StripeObject[];
+    products: Map<string, StripeObject>;
+    events: StripeObject[];
+    paymentMethod?: StripeObject;
+};
+export declare function loadSubscription(id: string): Promise<SubscriptionDetail>;
+export declare function loadInvoices(): Promise<{
+    invoices: StripeObject[];
+    customers: Map<string, StripeObject>;
+}>;
+export declare function loadProducts(): Promise<{
+    products: StripeObject[];
+    prices: StripeObject[];
+}>;
+export type HomeData = {
+    balance: StripeObject;
+    payments: Payment[];
+    customers: StripeObject[];
+    subscriptions: StripeObject[];
+    invoices: StripeObject[];
+};
+export declare function loadHome(): Promise<HomeData>;
+export declare function loadBalances(): Promise<{
+    balance: StripeObject;
+    transactions: StripeObject[];
+    payouts: StripeObject[];
+}>;
+export declare function loadDevelopers(): Promise<{
+    events: StripeObject[];
+    webhooks: StripeObject[];
+    account?: StripeObject;
+}>;
+/** Refund a payment in full (no amount) or in part. */
+export declare function createRefund(payment: {
+    intent?: StripeObject;
+    charge?: StripeObject;
+}, amount: number | undefined, reason: string | undefined): Promise<StripeObject>;
+/** Cancel now (DELETE) or at the end of the current period (cancel_at_period_end). */
+export declare function cancelSubscription(id: string, when: 'now' | 'period_end'): Promise<StripeObject>;
+export declare const createObject: (collection: string, fields: Record<string, string>) => Promise<StripeObject>;

package/dist/client/dashboard-api.js

@@ -0,0 +1,238 @@
+// 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.
+export function wireBaseFrom(hasBaseElement, baseURI) {
+    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 {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+async function call(method, path, body) {
+    const init = { 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['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) => 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) {
+    const sep = path.includes('?') ? '&' : '?';
+    const body = await call('GET', `${path}${sep}limit=100`);
+    return Array.isArray(body?.data) ? body.data : [];
+}
+const optional = (p, fallback) => p.catch(() => fallback);
+export function paymentStatusOf(intent, charge) {
+    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 = {
+    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) => (code ? DECLINE_REASONS[code] ?? code.replace(/_/g, ' ') : undefined);
+async function paymentMethodsById(ids) {
+    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)));
+    return new Map(found.filter((pm) => Boolean(pm?.id)).map((pm) => [pm.id, pm]));
+}
+function paymentOf(intent, charge, refunds, dir) {
+    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() {
+    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 = { 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);
+}
+/** One payment's page: the intent (or charge), its charge, refunds, card, customer and the events about it. */
+export async function loadPayment(id) {
+    let intent;
+    let charge;
+    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 = { customers: new Map(customer ? [[customer.id, customer]] : []), paymentMethods: pms };
+    const related = new Set([base.id, charge?.id, intent?.id, ...refunds.map((r) => r.id)].filter(Boolean));
+    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,
+    };
+}
+export async function loadCustomers() {
+    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 async function loadCustomer(id) {
+    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),
+    };
+}
+export async function loadSubscriptions() {
+    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 async function loadSubscription(id) {
+    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() {
+    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() {
+    const [products, prices] = await Promise.all([list('/v1/products'), list('/v1/prices')]);
+    return { products, prices };
+}
+export async function loadHome() {
+    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() {
+    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() {
+    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, amount, reason) {
+    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, when) {
+    return when === 'now' ? call('DELETE', `/v1/subscriptions/${id}`) : call('POST', `/v1/subscriptions/${id}`, { cancel_at_period_end: true });
+}
+export const createObject = (collection, fields) => call('POST', `/v1/${collection}`, fields);

package/dist/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);