@volter/twin-stripe 0.1.2 → 2.0.0

package/src/stripe-server.ts

@@ -7,18 +7,121 @@
 // The surface is a plain `fetch` (`createStripeTwinFetch`) and the SERVER is one line of
 // `Bun.serve` around it — see that factory's docstring for why (a serverless entry has no
 // port to bind, so it mounts the fetch in-process).
-import { handleStripeTwinRequest } from './stripe-twin.ts';
-import { worldNow, statefulTwinManifest} from '@volter/twin';
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, readParams, semanticsContext, serveHttp, vendorError, type DerivedCall, type DerivedFetch } from '@volter/world-core';
+import { stripeCheckoutFlow } from './screens/checkout.tsx';
+import { stripeJs } from './stripe-js.ts';
+import { stripeFinancialConnectionsFlow } from './screens/financial-connections.tsx';
+import { stripeIdentityFlow } from './screens/identity.tsx';
+import { stripeOnboardingFlow } from './screens/onboarding.tsx';
+import { stripePortalFlow } from './screens/portal.tsx';
+import { stripePublicDetailsFlow } from './screens/public-details.tsx';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { appsSecrets } from './semantics/apps-secrets.ts';
+import { balances } from './semantics/balance.ts';
+import { billing } from './semantics/billing.ts';
+import { charges } from './semantics/charges.ts';
+import { checkout } from './semantics/checkout.ts';
+import { connect } from './semantics/connect.ts';
+import { coupons } from './semantics/coupons.ts';
+import { creditNotes } from './semantics/credit-notes.ts';
+import { customers } from './semantics/customers.ts';
+import { disputes } from './semantics/disputes.ts';
+import { entitlements } from './semantics/entitlements.ts';
+import { ephemeralKeys } from './semantics/ephemeral-keys.ts';
+import { files } from './semantics/files.ts';
+import { invoices } from './semantics/invoices.ts';
+import { issuing, lapseRealtimeRequests } from './semantics/issuing.ts';
+import { paymentIntents } from './semantics/payment-intents.ts';
+import { paymentLinks } from './semantics/payment-links.ts';
+import { paymentMethods } from './semantics/payment-methods.ts';
+import { platform } from './semantics/platform.ts';
+import { plans } from './semantics/plans.ts';
+import { products } from './semantics/products.ts';
+import { radar } from './semantics/radar.ts';
+import { refunds } from './semantics/refunds.ts';
+import { setupIntents } from './semantics/setup-intents.ts';
+import { subscriptionSchedules } from './semantics/subscription-schedules.ts';
+import { subscriptions } from './semantics/subscriptions.ts';
+import { tax } from './semantics/tax.ts';
+import { terminal } from './semantics/terminal.ts';
+import { testClocks } from './semantics/test-clocks.ts';
+import { ledger } from './semantics/ledger.ts';
+import { tokens } from './semantics/tokens.ts';
+import { transfers } from './semantics/transfers.ts';
+import { treasury } from './semantics/treasury.ts';
+import { webhookEndpoints } from './semantics/webhook-endpoints.ts';
+import { advancePayouts, balanceBody, payDuePayouts } from './semantics/balance.ts';
+import { settleDueEntries } from './semantics/ledger.ts';
+import { settleHeldRefunds } from './semantics/refunds.ts';
+import { settleBankDebits } from './semantics/payment-intents.ts';
+import { lapseCoupons } from './semantics/coupons.ts';
+import { finishClockAdvances } from './semantics/test-clocks.ts';
+import { settleTopups } from './semantics/terminal.ts';
+import { finishReportRuns } from './semantics/platform.ts';
+import { advanceBilling } from './semantics/renewals.ts';
+import { refuseParameters } from './stripe-params.ts';
+import { afterStripeWrite, handleStripeDoor, PLATFORM_ACCOUNT_ID } from './stripe-twin.ts';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import { expandOf, render, servesCurrent, withoutEndpointSecret } from './stripe-version.ts';
 
 /** Options shared by the fetch handler and the Bun.serve wrapper around it. `port` is a
  *  BIND concern the fetch ignores; it stays in one shape so a caller configures the twin
  *  once whichever way it is mounted. */
-export type StripeTwinOptions = { root?: string; port?: number; readOnly?: boolean };
+export type StripeTwinOptions = { root?: string; port?: number; readOnly?: boolean; /** the World instant, when a caller pins it */ clock?: () => string };
+
+// ── what a publishable key may call ──
+// "Publishable API key pk_... | Safe to expose: Yes | API key for Stripe.js, Elements, and mobile SDKs. It can identify
+// your account and create tokens or PaymentMethods from payment details, but it can't perform sensitive operations such
+// as creating charges or reading account data" (docs.stripe.com/keys). The served spec names the calls a publishable key
+// makes with an object's client secret: "You can retrieve a PaymentIntent client-side using a publishable key when the
+// client_secret is provided in the query string" (GET /v1/payment_intents/{intent}), "Client-side retrieval using a
+// publishable key is allowed when the client_secret is provided" (GET /v1/setup_intents/{intent}), "Required if a
+// publishable key is used to retrieve the source" (GET /v1/sources/{source}), and the confirm and verify_microdeposits
+// calls that take "The client secret of the PaymentIntent" (or SetupIntent). Anything else is refused with Stripe's
+// code: "secret_key_required | The API key provided is a publishable key, but a secret key is required"
+// (docs.stripe.com/error-codes), as 403, "The API key doesn't have permissions to perform the request"
+// (docs.stripe.com/api/errors).
+// Where the documentation stops and the twin decides: the list above is the whole of what a publishable key may call
+// (Stripe publishes no complete list); a client-secret call without the secret answers parameter_missing, and one with a
+// secret that is not the object's answers the object's 404, as though the key could not see it.
+const PUBLISHABLE_CREATES = new Set(['PostTokens', 'PostPaymentMethods']);
+const BY_CLIENT_SECRET: Record<string, { type: string; param: string }> = {
+  GetPaymentIntentsIntent: { type: 'payment_intent', param: 'intent' },
+  PostPaymentIntentsIntentConfirm: { type: 'payment_intent', param: 'intent' },
+  PostPaymentIntentsIntentVerifyMicrodeposits: { type: 'payment_intent', param: 'intent' },
+  GetSetupIntentsIntent: { type: 'setup_intent', param: 'intent' },
+  PostSetupIntentsIntentConfirm: { type: 'setup_intent', param: 'intent' },
+  PostSetupIntentsIntentVerifyMicrodeposits: { type: 'setup_intent', param: 'intent' },
+  GetSourcesSource: { type: 'source', param: 'source' },
+};
+
+/** Stripe's refusal of a call a publishable key may not make, or undefined when the key may make it. */
+async function publishableKeyRefused(call: DerivedCall, scope: { root?: string; clock?: () => string }): Promise<Response | undefined> {
+  const key = /^bearer\s+(\S+)/i.exec(call.request.headers.get('authorization') ?? '')?.[1] ?? '';
+  if (!key.startsWith('pk_')) return undefined;
+  if (PUBLISHABLE_CREATES.has(call.operation.id)) return undefined;
+  const scoped = BY_CLIENT_SECRET[call.operation.id];
+  if (!scoped) return vendorError(manifest, { status: 403, code: 'secret_key_required', message: 'The API key provided is a publishable key, but a secret key is required.' });
+  const params = await readParams(manifest, call.request.clone(), call.operation);
+  const secret = typeof params.client_secret === 'string' ? params.client_secret : '';
+  if (!secret) return vendorError(manifest, { status: 400, code: 'parameter_missing', param: 'client_secret', message: 'Missing required param: client_secret.' });
+  const id = call.params[scoped.param] ?? '';
+  // the context reads a body of its own, so the handler after this still has the request's
+  const ctx = await semanticsContext(manifest, call.request.clone(), call.operation, scope);
+  return ctx.get(scoped.type, id)?.client_secret === secret ? undefined : wrongClientSecret(scoped, id);
+}
+
+/** A client-secret call whose secret is not the object's: answered as though the key could not see it (the twin's
+ *  decision, above). */
+function wrongClientSecret(scoped: { type: string; param: string }, id: string): Response {
+  return vendorError(manifest, { status: 404, code: 'resource_missing', param: scoped.param, message: `No such ${scoped.type}: '${id}'` });
+}
 
 /**
  * The whole Stripe serve path as a plain `(Request) => Response` — the `/twin` manifest
  * door, the header threading (idempotency key, pinned API version, Connect account) and
- * the dispatch into `handleStripeTwinRequest`. NOTHING about it is port-bound.
+ * the derived dispatch over the hand-written routes. NOTHING about it is port-bound.
  *
  * Why this is the factory and `createStripeTwinServer` is a wrapper (runtime contract R12,
  * the Cloudflare ruling): a Durable Object / Worker entry has no loopback ports — it mounts
@@ -33,49 +136,171 @@ export type StripeTwinOptions = { root?: string; port?: number; readOnly?: boole
  * `finally` fires when `fn` RETURNS, i.e. at the first `await`, restoring the previous store
  * under the rest of the request.
  */
-export function createStripeTwinFetch(options: StripeTwinOptions): (request: Request) => Promise<Response> {
+export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch {
   const readOnly = options.readOnly ?? false;
-  return async function stripeTwinFetch(request: Request): Promise<Response> {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  // The derived dispatch owns the API: an operation with a semantics handler is served by it, one on a
+  // resource the manifest declares by the derived core, and one neither models answers Stripe's
+  // unrecognized-URL 404.
+  const guard = crossCutting(manifest, { readOnly, ...scope });
+  const handlerMap = { ...billing, ...paymentIntents, ...customers, ...products, ...plans, ...charges, ...refunds, ...setupIntents, ...paymentMethods, ...subscriptions, ...invoices, ...checkout, ...ephemeralKeys, ...disputes, ...balances, ...coupons, ...creditNotes, ...subscriptionSchedules, ...entitlements, ...testClocks, ...webhookEndpoints, ...connect, ...transfers, ...appsSecrets, ...tokens, ...files, ...tax, ...paymentLinks, ...radar, ...issuing, ...terminal, ...treasury, ...platform, ...ledger };
+  const core = coreFor(manifest, scope);
+  const derived = createDerivedFetch({
+    surface,
+    handlers: bindSemantics(manifest, handlerMap, scope),
+    core,
+    // after the credential and the version, a publishable key is held to the client-side calls, then a request's
+    // parameters are checked against the operation's (stripe-params.ts)
+    around: (call, next) => guard(call, async () => (await publishableKeyRefused(call, scope)) ?? (await refuseParameters(call)) ?? next()),
+    gap: (request) => vendorError(manifest, { status: 404, message: `Unrecognized request URL (${request.method}: ${new URL(request.url).pathname}).` }),
+  });
+  // the hosted flows sit beside the API: checkout.stripe.com's payment page, billing.stripe.com's customer portal,
+  // connect.stripe.com's onboarding, verify.stripe.com's identity check and the bank-linking flow Stripe.js opens, and
+  // the Dashboard's Public details page (dashboard.stripe.com/settings/public, the platform's customer-facing name);
+  // a read-only twin takes no payments and moves nothing
+  const flows = [stripeCheckoutFlow(scope), stripePortalFlow(scope), stripeOnboardingFlow(scope), stripeIdentityFlow(scope), stripeFinancialConnectionsFlow(scope), stripePublicDetailsFlow(scope)];
+  // the twin's own doors sit in front of the API: discovery, and what stands in for an act Stripe's API
+  // does not have (stripe-twin.ts)
+  // GET /twin: what this twin is (not Stripe's; a host reads it)
+  function discovery(): Response {
+    return Response.json(statefulTwinManifest({ vendor: 'stripe', twinOf: 'the Stripe REST API', stores: 'customers, payment objects, checkout sessions, products/prices and webhook endpoints (signed events)' }));
+  }
+  // /_twin/…: a door's body is read as the API's is: a form, or JSON
+  const twinDoor = async (request: Request, url: URL): Promise<Response | undefined> => {
+    const answer = await handleStripeDoor({
+      method: request.method, path: url.pathname, readOnly,
+      occurredAt: options.clock ? options.clock() : worldNow(),
+      ...(options.root !== undefined ? { root: options.root } : {}),
+    }, await readParams(manifest, request));
+    return answer && Response.json(answer.body, { status: answer.status, headers: { 'request-id': 'req_twin' } });
+  };
+  const door = async (request: Request): Promise<Response | undefined> => {
     const url = new URL(request.url);
-    // GET /twin — the discovery manifest (education inside the twin).
-    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
-      return Response.json(statefulTwinManifest({ vendor: 'stripe', twinOf: 'the Stripe REST API', stores: 'customers, payment objects, checkout sessions, products/prices and webhook endpoints (signed events)' }));
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') return discovery();
+    return url.pathname.startsWith('/_twin/') ? twinDoor(request, url) : undefined;
+  };
+  // time's moves Stripe makes on its own (a subscription renewing at its period's end, its renewal charged an hour
+  // later: semantics/renewals.ts; each account's automatic payouts: semantics/balance.ts) are caught up to the World's clock before anything is answered, so every door
+  // (the API, the hosted pages) reads the account as it stands now
+  const billingClock = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'GetSubscriptions')!;
+  const catchUp = async (request: Request): Promise<void> => {
+    if (readOnly) return;
+    const ctx = await semanticsContext(manifest, new Request(request.url), billingClock, scope);
+    // a test clock advanced by the last request has reached its time (semantics/test-clocks.ts)
+    await finishClockAdvances(ctx);
+    await advanceBilling(ctx);
+    // a submitted bank debit settles (in test mode at once) before anything is answered (semantics/payment-intents.ts)
+    await settleBankDebits(ctx);
+    // a coupon past its redeem_by is no longer valid (semantics/coupons.ts)
+    await lapseCoupons(ctx);
+    // a top-up's funds arrive five days after it is made (semantics/terminal.ts)
+    await settleTopups(ctx);
+    // a report run completes (semantics/platform.ts)
+    await finishReportRuns(ctx);
+    // a real-time authorization request no one answered is decided when its window ends (semantics/issuing.ts)
+    await lapseRealtimeRequests(ctx);
+    // a refund held for want of balance is made when funds cover it, before any payout takes them (semantics/refunds.ts)
+    await settleHeldRefunds(ctx);
+    await advancePayouts(ctx);
+  };
+  // Time's EVENTS, sent on the vendor's clock through a twin-only drain door, as the qstash and vercel twins send
+  // theirs (a caller — a runner's drainer — drives each move). POST /_twin/drain catches time up as every request
+  // does, then writes what time settled on each account: payouts whose arrival date came (pending → paid, sent as
+  // payout.paid) and funds that came due (pending → available), for which the account is sent one balance.available
+  // ("Occurs whenever your Stripe balance has been updated (e.g., when a charge is available to be paid out)",
+  // docs.stripe.com/api/events/types) carrying its Balance, when an entry that settled adds to it ("This event is not
+  // fired for negative transactions", the same page); a connected account's events go to Connect endpoints.
+  // A read already sees these moves; the drain is what makes Stripe's events about them arrive. Answers what it sent.
+  const drain = async (request: Request): Promise<Response> => {
+    if (readOnly) return Response.json({ error: 'twin is read-only; omit readOnly to accept writes' }, { status: 405 });
+    await catchUp(request);
+    const at = (account?: string) => semanticsContext(manifest, new Request(request.url, account ? { headers: { 'stripe-account': account } } : {}), billingClock, scope);
+    const platformCtx = await at();
+    const accounts = [undefined, ...platformCtx.rows('account').map((a) => String(a.id)).filter((id) => id !== PLATFORM_ACCOUNT_ID)];
+    const delivered: Array<{ type: string; id?: string; account?: string }> = [];
+    for (const account of accounts) {
+      const ctx = account ? await at(account) : platformCtx;
+      for (const id of await payDuePayouts(ctx)) delivered.push({ type: 'payout.paid', id, ...(account ? { account } : {}) });
+      if ((await settleDueEntries(ctx)).some((t) => Number(t.net) > 0)) {
+        await afterStripeWrite('balance', 'balance.available', balanceBody(ctx), options.root, ctx.occurredAt, undefined, account);
+        delivered.push({ type: 'balance.available', ...(account ? { account } : {}) });
+      }
     }
-    const body = request.method === 'GET' ? '' : await request.text();
-    // Stripe sends the idempotency key as the `Idempotency-Key` request header; the
-    // real SDK sets it from { idempotencyKey } on a write call. Thread it through so
-    // a replay returns the stored response without re-applying the write.
-    const idempotencyKey = request.headers.get('idempotency-key') ?? undefined;
-    // Stripe pins API behavior via the `Stripe-Version` request header; the real SDK
-    // sets it from { apiVersion }. Thread it through so the twin can reflect it (and
-    // reject a malformed value with a 400) exactly like real Stripe.
-    const apiVersion = request.headers.get('stripe-version') ?? undefined;
-    // Connect: the SDK sets `Stripe-Account` from { stripeAccount } to act on behalf of a
-    // connected account. Thread it through so account-scoped writes (e.g. a payout created
-    // on the connected account's balance) are attributed to that account, like real Stripe.
-    const stripeAccount = request.headers.get('stripe-account') ?? undefined;
-    const { status, body: out } = await handleStripeTwinRequest({
-      method: request.method,
-      path: url.pathname + (url.search || ''),
-      body,
-      readOnly,
-      ...(apiVersion ? { apiVersion } : {}),
-      ...(stripeAccount ? { stripeAccount } : {}),
-      // The WORLD instant (R9): served `created` epochs come from the world clock, never
-      // wall time. Embedded/test callers pass their own occurredAt.
-      occurredAt: worldNow(),
-      ...(idempotencyKey ? { idempotencyKey } : {}),
-      ...(options.root !== undefined ? { root: options.root } : {}),
-    });
-    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', 'request-id': 'req_twin' } });
+    return Response.json({ delivered });
+  };
+  const served = async (request: Request): Promise<Response> => {
+    if (request.method === 'POST' && new URL(request.url).pathname.replace(/\/+$/, '') === '/_twin/drain') return drain(request);
+    const opened = await door(request);
+    if (opened) return opened;
+    // the client library an application's page loads from js.stripe.com (stripe-js.ts); it moves nothing, so a
+    // read-only twin serves it too
+    const library = stripeJs(request);
+    if (library) return library;
+    await catchUp(request);
+    if (!readOnly) for (const flow of flows) { const page = await flow(request); if (page) return page; }
+    // an update's metadata is merged into what the object holds before the handler or the core serves it (mergeMetadata)
+    return derived(readOnly ? request : await mergeMetadata(request, (op) => !(op.id in handlerMap) && core.owns(op), scope));
   };
+  // every answer in the shape of the API version the caller is served (stripe-version.ts)
+  const rendered = async (request: Request): Promise<Response> => {
+    const expand = expandOf(request.clone());
+    const creates = request.method === 'POST' && new URL(request.url).pathname.replace(/\/+$/, '') === '/v1/webhook_endpoints';
+    const res = await served(request);
+    const pinned = request.headers.get('stripe-version');
+    if (!(res.headers.get('content-type') ?? '').includes('json')) return res;
+    if (!servesCurrent(pinned) && creates) return res;
+    const body = await res.json();
+    // a webhook endpoint's `secret` is "Only returned at creation" (docs.stripe.com/api/webhook_endpoints/object)
+    const answered = creates ? body : withoutEndpointSecret(body);
+    return new Response(JSON.stringify(servesCurrent(pinned) ? render(answered, pinned, await expand) : answered), { status: res.status, statusText: res.statusText, headers: res.headers });
+  };
+  return Object.assign(rendered, { owners: derived.owners });
 }
 
-export function createStripeTwinServer(options: StripeTwinOptions): { port: number; stop: () => void } {
-  const server = Bun.serve({
+export async function createStripeTwinServer(options: StripeTwinOptions): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
     port: options.port ?? 0,
     idleTimeout: 60,
     fetch: createStripeTwinFetch(options),
   });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }
+
+// the update operations, by their path as a pattern, for mergeMetadata
+const UPDATES = (surface.operations as Array<DerivedCall['operation']>).filter((o) => o.class === 'update' && o.method.toUpperCase() === 'POST')
+  .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
+
+/** An update's `metadata`, merged into what the object holds before anything serves the update. "This parameter uses a
+ *  merge mechanism, which allows you to add new key-value pairs to an object in an update call without affecting any
+ *  existing metadata"; "Pass in the key with an empty string as the value to remove the key from the metadata"; "Pass an
+ *  empty string as the value for the metadata attribute to delete all of the keys simultaneously"
+ *  (docs.stripe.com/metadata). The derived core already merges a nested hash where the manifest leaves `update` at
+ *  `merge` (dropping keys set to ""), so only a clear-all is rewritten for it; where a handler or a `replace` update
+ *  stores the request's metadata whole, the request is rewritten to carry the merged hash, so every door stores the same
+ *  answer. The request is rewritten as JSON (readParams reads either). */
+async function mergeMetadata(request: Request, coreMerges: (op: DerivedCall['operation']) => boolean, scope: { root?: string; clock?: () => string }): Promise<Request> {
+  if (request.method !== 'POST' || (request.headers.get('content-type') ?? '').includes('multipart')) return request;
+  const path = new URL(request.url).pathname;
+  let op: DerivedCall['operation'] | undefined;
+  let id = '';
+  for (const u of UPDATES) { const m = u.re.exec(path); if (m) { op = u.op; id = decodeURIComponent(m.at(-1) ?? ''); break; } }
+  if (!op?.resource) return request;
+  const params = await readParams(manifest, request.clone(), op);
+  if (!('metadata' in params)) return request;
+  const given = params.metadata;
+  // a plan is kept as the recurring price it is (semantics/plans.ts)
+  const resource = op.resource === 'plan' ? 'price' : op.resource;
+  const ctx = await semanticsContext(manifest, request.clone(), op, scope);
+  const held = ctx.get(resource, id)?.metadata;
+  const prior = held && typeof held === 'object' ? (held as Record<string, unknown>) : {};
+  const merges = coreMerges(op) && manifest.resources[resource]?.update !== 'replace';
+  let metadata: Record<string, unknown>;
+  if (given === '') metadata = merges ? Object.fromEntries(Object.keys(prior).map((k) => [k, ''])) : {};
+  else if (given && typeof given === 'object' && !Array.isArray(given)) {
+    if (merges) return request;
+    metadata = Object.fromEntries(Object.entries({ ...prior, ...(given as Record<string, unknown>) }).filter(([, v]) => v !== ''));
+  } else return request;
+  const headers = new Headers(request.headers);
+  headers.set('content-type', 'application/json');
+  return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...params, metadata }) });
+}

package/src/stripe-shared.ts

@@ -0,0 +1,294 @@
+// The stripe mirror's SHARED vocabulary — formatters, tones, reference resolution — with no
+// import from the server side: the mirror client bundles this into the browser (a server import
+// would drag core, and with it node:async_hooks, into the bundle and the page would never mount).
+// The server module re-exports it, so nothing else moves.
+
+export type StripeRow = Record<string, any>;
+
+/** The name an account shows its customers (Checkout, the customer portal): its public business name,
+ *  `business_profile.name` ("The customer-facing business name", docs.stripe.com/api/accounts/object), which the
+ *  operator sets on the Dashboard ("You can change a Checkout page's name by modifying the Business name field",
+ *  docs.stripe.com/payments/checkout/customization/appearance). Where the documentation stops and the twin decides:
+ *  with none set it falls back to the Dashboard's account name, `settings.dashboard.display_name` ("used on the Stripe
+ *  Dashboard to differentiate between accounts", the same object page), and with neither to "Twin Inc.", the name the
+ *  Dashboard mirror has always given the World's own account. */
+export const PLATFORM_DEFAULT_NAME = 'Twin Inc.';
+export function publicBusinessName(account: StripeRow | undefined): string {
+  const named = (v: unknown): string | undefined => (typeof v === 'string' && v.trim() ? v : undefined);
+  return named(account?.business_profile?.name) ?? named(account?.settings?.dashboard?.display_name) ?? PLATFORM_DEFAULT_NAME;
+}
+
+/** Zero-decimal currencies (Stripe stores these in whole units, not cents). */
+const ZERO_DECIMAL = new Set(['bif', 'clp', 'djf', 'gnf', 'jpy', 'kmf', 'krw', 'mga', 'pyg', 'rwf', 'ugx', 'vnd', 'vuv', 'xaf', 'xof', 'xpf']);
+
+/**
+ * Format a Stripe minor-unit amount (cents) as a localized currency string.
+ * Honors zero-decimal currencies (¥4200 not ¥42.00). Non-numbers → an em dash.
+ */
+export function formatStripeAmount(value: unknown, currency?: string): string {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return '—';
+  const ccy = String(currency ?? 'usd').toLowerCase();
+  const zero = ZERO_DECIMAL.has(ccy);
+  const major = zero ? value : value / 100;
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency', currency: ccy.toUpperCase(),
+      minimumFractionDigits: zero ? 0 : 2, maximumFractionDigits: zero ? 0 : 2,
+    }).format(major);
+  } catch {
+    // Unknown/invalid currency code → a stable, readable fallback.
+    return `${zero ? major : major.toFixed(2)} ${ccy.toUpperCase()}`;
+  }
+}
+
+/**
+ * Render a Stripe price's `recurring` block as a short interval label, e.g.
+ * "every month", "every 3 months". Returns '' when it isn't a recurring price.
+ */
+export function formatRecurring(recurring: unknown): string {
+  if (!recurring || typeof recurring !== 'object') return '';
+  const r = recurring as Record<string, unknown>;
+  const interval = typeof r.interval === 'string' ? r.interval : '';
+  if (!interval) return '';
+  const count = Number(r.interval_count);
+  return count > 1 ? `every ${count} ${interval}s` : `every ${interval}`;
+}
+
+/**
+ * Render a saved payment method as a short human label, e.g. "Visa •••• 4242"
+ * for a card, or the bare `type` ("us_bank_account") for non-card methods.
+ */
+export function formatPaymentMethod(pm: unknown): string {
+  if (!pm || typeof pm !== 'object') return '—';
+  const m = pm as Record<string, any>;
+  const card = m.card && typeof m.card === 'object' ? (m.card as Record<string, any>) : undefined;
+  if (card && (card.brand || card.last4)) {
+    const brand = card.brand ? String(card.brand).replace(/\b\w/g, (c) => c.toUpperCase()) : 'Card';
+    return card.last4 ? `${brand} •••• ${card.last4}` : brand;
+  }
+  return typeof m.type === 'string' && m.type ? m.type : (m.id ?? '—');
+}
+
+/**
+ * Extract the HTTP(S) image URLs from a product's `images` field (Stripe stores an
+ * array of URL strings) so the mirror can render them as <img> thumbnails instead
+ * of plain text. Non-arrays / non-URL entries are dropped. Order is preserved.
+ */
+export function productImageUrls(images: unknown): string[] {
+  if (!Array.isArray(images)) return [];
+  return images.filter((u): u is string => typeof u === 'string' && /^https?:\/\//i.test(u));
+}
+
+/**
+ * Render a payment_intent / charge `last_payment_error` (the test-card decline state)
+ * as a single human-readable line, e.g. "card_declined (insufficient_funds): Your card
+ * has insufficient funds." Returns '' when there is no error object. This is the
+ * vendor-faithful decline reason the twin populates on a declined confirm.
+ */
+export function formatPaymentError(error: unknown): string {
+  if (!error || typeof error !== 'object') return '';
+  const e = error as Record<string, any>;
+  const code = typeof e.code === 'string' ? e.code : '';
+  const declineCode = typeof e.decline_code === 'string' ? e.decline_code : '';
+  const message = typeof e.message === 'string' ? e.message : '';
+  const head = code ? (declineCode ? `${code} (${declineCode})` : code) : declineCode;
+  if (head && message) return `${head}: ${message}`;
+  return head || message;
+}
+
+/**
+ * Summarize a synthesized Stripe `balance` object (available/pending arrays, one entry
+ * per currency) into short per-bucket lines, e.g. ["available: $42.00", "pending: $0.00"].
+ * The balance is not a list collection, so the mirror renders this summary directly.
+ */
+export function formatBalanceSummary(balance: unknown): Array<{ bucket: string; text: string }> {
+  if (!balance || typeof balance !== 'object') return [];
+  const b = balance as Record<string, any>;
+  const sum = (arr: unknown): string => {
+    if (!Array.isArray(arr) || arr.length === 0) return formatStripeAmount(0, 'usd');
+    return arr
+      .map((e) => formatStripeAmount((e as Record<string, any>)?.amount, (e as Record<string, any>)?.currency))
+      .join(', ');
+  };
+  const out: Array<{ bucket: string; text: string }> = [];
+  if (Array.isArray(b.available)) out.push({ bucket: 'available', text: sum(b.available) });
+  if (Array.isArray(b.pending)) out.push({ bucket: 'pending', text: sum(b.pending) });
+  return out;
+}
+
+/**
+ * Summarize a Connect connected `account` object's enablement state into the three
+ * boolean capability flags a real Stripe Connect dashboard shows up front:
+ * charges_enabled, payouts_enabled, details_submitted. Each is rendered as a tone-
+ * carrying flag (true → ok, false → warn) so an un-onboarded account reads as such.
+ */
+export type AccountFlag = { key: string; label: string; enabled: boolean };
+export function formatAccountFlags(account: unknown): AccountFlag[] {
+  if (!account || typeof account !== 'object') return [];
+  const a = account as Record<string, any>;
+  return [
+    { key: 'charges_enabled', label: 'Charges', enabled: a.charges_enabled === true },
+    { key: 'payouts_enabled', label: 'Payouts', enabled: a.payouts_enabled === true },
+    { key: 'details_submitted', label: 'Details submitted', enabled: a.details_submitted === true },
+  ];
+}
+
+/**
+ * Extract a Connect account's outstanding onboarding requirements (the
+ * `requirements.currently_due` list real Stripe shows as "needs attention"). Returns
+ * an ordered list of the still-due field paths; empty when nothing is due.
+ */
+export function accountCurrentlyDue(account: unknown): string[] {
+  if (!account || typeof account !== 'object') return [];
+  const req = (account as Record<string, any>).requirements;
+  if (!req || typeof req !== 'object') return [];
+  const due = (req as Record<string, any>).currently_due;
+  return Array.isArray(due) ? due.filter((d): d is string => typeof d === 'string') : [];
+}
+
+/** Tone for a status pill: 'ok' (green), 'warn' (amber), 'bad' (red), '' (neutral). */
+export type PillTone = 'ok' | 'warn' | 'bad' | '';
+const PILL_OK = new Set(['active', 'succeeded', 'paid', 'true', 'enabled', 'available', 'won']);
+const PILL_WARN = new Set(['open', 'draft', 'pending', 'processing', 'incomplete', 'trialing', 'requires_confirmation', 'requires_action', 'requires_capture', 'requires_payment_method', 'past_due', 'unpaid', 'in_transit', 'warning_needs_response', 'needs_response', 'under_review', 'warning_under_review']);
+const PILL_BAD = new Set(['canceled', 'cancelled', 'void', 'uncollectible', 'failed', 'incomplete_expired', 'false', 'disabled', 'lost', 'charge_refunded']);
+export function statusTone(value: unknown): PillTone {
+  const v = String(value ?? '').toLowerCase();
+  if (PILL_OK.has(v)) return 'ok';
+  if (PILL_BAD.has(v)) return 'bad';
+  if (PILL_WARN.has(v)) return 'warn';
+  return '';
+}
+
+/** True when a key names a field whose value is a Stripe object id we can link. */
+export function isReferenceKey(key: string): boolean {
+  return REFERENCE_FIELDS.has(key);
+}
+// field name → the COLLECTION it points at (so the UI can jump sections + select).
+const REFERENCE_FIELD_MAP: Record<string, string> = {
+  customer: 'customers', product: 'products', price: 'prices',
+  subscription: 'subscriptions', latest_invoice: 'invoices', invoice: 'invoices',
+  payment_intent: 'payment_intents', latest_charge: 'charges', charge: 'charges',
+  payment_method: 'payment_methods', default_payment_method: 'payment_methods',
+  dispute: 'disputes', payout: 'payouts', balance_transaction: 'balance_transactions',
+  source_transaction: 'charges', setup_intent: 'setup_intents',
+  // Connect: a transfer's `destination` points at a connected account.
+  account: 'accounts', destination: 'accounts',
+  // Billing: a customer_balance_transaction may reference the credit_note that created it.
+  credit_note: 'credit_notes',
+};
+const REFERENCE_FIELDS = new Set(Object.keys(REFERENCE_FIELD_MAP));
+/** The collection a reference field points at, or undefined if not a reference. */
+export function referenceCollection(key: string): string | undefined {
+  return REFERENCE_FIELD_MAP[key];
+}
+
+/** A single line in the flattened, human-readable view of a nested value. */
+export type FlatLine = { depth: number; label: string; value: string; ref?: string };
+
+/**
+ * Flatten an arbitrary nested Stripe value (object / array / scalar) into ordered,
+ * indented label/value lines suitable for a readable detail view — instead of the
+ * old "[object Object]". Stripe "list" wrappers ({object:'list',data:[...]}) are
+ * unwrapped to their `data`. Amount-ish fields are currency-formatted.
+ */
+export function flattenStripeValue(value: unknown, opts: { label?: string; depth?: number; currency?: string } = {}): FlatLine[] {
+  const depth = opts.depth ?? 0;
+  const label = opts.label ?? '';
+  const currency = opts.currency;
+  if (value === null || value === undefined) return [{ depth, label, value: '—' }];
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [{ depth, label, value: '(none)' }];
+    const out: FlatLine[] = label ? [{ depth, label, value: '' }] : [];
+    value.forEach((item, i) => {
+      const childDepth = label ? depth + 1 : depth;
+      out.push(...flattenStripeValue(item, { label: `#${i + 1}`, depth: childDepth, currency }));
+    });
+    return out;
+  }
+
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    // Unwrap Stripe list objects to their data array.
+    if (obj.object === 'list' && Array.isArray(obj.data)) {
+      return flattenStripeValue(obj.data, { label, depth, currency });
+    }
+    const childCurrency = typeof obj.currency === 'string' ? obj.currency : currency;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== null && obj[k] !== undefined && k !== 'object');
+    if (keys.length === 0) return [{ depth, label, value: '(empty)' }];
+    const out: FlatLine[] = label ? [{ depth, label, value: '' }] : [];
+    const childDepth = label ? depth + 1 : depth;
+    for (const k of keys) out.push(...flattenStripeValue(obj[k], { label: k, depth: childDepth, currency: childCurrency }));
+    return out;
+  }
+
+  // scalar
+  const ref = typeof value === 'string' && isReferenceKey(label) ? value : undefined;
+  const isMoney = typeof value === 'number' && (label === 'unit_amount' || /amount|total|subtotal|balance/.test(label));
+  const rendered = isMoney ? formatStripeAmount(value, currency) : String(value);
+  return [{ depth, label, value: rendered, ...(ref ? { ref } : {}) }];
+}
+
+/**
+ * Resolve the cross-references for a row: the rows in other collections that this
+ * row points AT (outgoing, e.g. invoice→customer) and the rows that point BACK at
+ * it (incoming, e.g. customer←subscriptions). Resolved purely from already-fetched
+ * collection data, so the UI can render clickable links without extra requests.
+ */
+export type RefLink = { collection: string; id: string; label: string };
+export type CrossRefs = { outgoing: RefLink[]; incoming: RefLink[] };
+
+const LABELERS: Record<string, (r: StripeRow) => string> = {
+  customers: (r) => r.name || r.email || r.id,
+  products: (r) => r.name || r.id,
+  prices: (r) => `${formatStripeAmount(r.unit_amount, r.currency)}${formatRecurring(r.recurring) ? ` ${formatRecurring(r.recurring)}` : ''}`,
+  subscriptions: (r) => `${r.status ?? 'subscription'} · ${r.id}`,
+  invoices: (r) => `${r.status ?? 'invoice'} · ${formatStripeAmount(r.total ?? r.amount_due, r.currency)}`,
+  payment_intents: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? ''}`,
+  charges: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? ''}`,
+  refunds: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'refund'}`,
+  payment_methods: (r) => `${formatPaymentMethod(r)} · ${r.id}`,
+  disputes: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'dispute'}`,
+  payouts: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'payout'}`,
+  balance_transactions: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.type ?? 'txn'}`,
+  events: (r) => `${r.type ?? 'event'} · ${r.id}`,
+  setup_intents: (r) => `${r.status ?? 'setup_intent'} · ${r.id}`,
+  invoiceitems: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.id}`,
+  accounts: (r) => `${r.email || r.id} · ${r.type ?? 'account'}`,
+  transfers: (r) => `${formatStripeAmount(r.amount, r.currency)} → ${r.destination ?? '?'}`,
+  credit_notes: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.status ?? 'credit_note'}`,
+  tax_ids: (r) => `${r.value ?? r.id} · ${r.type ?? ''}`,
+};
+function labelFor(collection: string, row: StripeRow): string {
+  return (LABELERS[collection] ?? ((r: StripeRow) => r.id))(row);
+}
+
+export function resolveCrossRefs(
+  collection: string,
+  row: StripeRow,
+  data: Record<string, StripeRow[]>,
+): CrossRefs {
+  const outgoing: RefLink[] = [];
+  const incoming: RefLink[] = [];
+  if (!row) return { outgoing, incoming };
+
+  // Outgoing: every reference field on this row that we can resolve to a row.
+  for (const [key, value] of Object.entries(row)) {
+    if (typeof value !== 'string' || !isReferenceKey(key)) continue;
+    const target = referenceCollection(key)!;
+    const found = (data[target] ?? []).find((r) => r.id === value);
+    outgoing.push({ collection: target, id: value, label: `${key}: ${found ? labelFor(target, found) : value}` });
+  }
+
+  // Incoming: rows in other collections whose reference field points at this row.
+  for (const [other, rows] of Object.entries(data)) {
+    if (other === collection) continue;
+    for (const r of rows) {
+      for (const [key, value] of Object.entries(r)) {
+        if (value !== row.id || !isReferenceKey(key)) continue;
+        incoming.push({ collection: other, id: r.id, label: `${labelFor(other, r)}` });
+      }
+    }
+  }
+  return { outgoing, incoming };
+}