@volter/twin-stripe 0.1.1 → 2.0.0

package/dist/src/stripe-perform-harness.js

@@ -0,0 +1,26 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). The kernel's loop
+// (`performEntries`) needs a bound root and a sealed credential a unit test does not have; this is the same
+// shape without one — the same `deployableEntries`, the pack's own push, the same `confirmAction`. Not on
+// the serve path, not exported from the pack.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { INTERNAL_SUBJECT_TYPES, isPushable, pushStripeAction } from "./stripe-connector.js";
+export async function performPending(execute, opts) {
+    const confirmed = [];
+    const externalIds = {};
+    for (const entry of deployableEntries('stripe', opts.root)) {
+        const op = entry.operation ?? `${entry.subject.type}.update`;
+        // the twin's own records — the recorded event envelopes and the idempotency bookkeeping — are local
+        // state and are never sent
+        if (INTERNAL_SUBJECT_TYPES.has(entry.subject.type) || !isPushable(op))
+            continue;
+        const { externalId } = await pushStripeAction(execute, { operation: op, subject: entry.subject, fields: entry.fields ?? {} });
+        confirmAction({
+            service: 'stripe', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+            occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+            ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(entry.id);
+        externalIds[entry.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds };
+}

package/dist/src/stripe-server.d.ts

@@ -0,0 +1,33 @@
+import { type DerivedFetch } from '@volter/world-core';
+/** 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; /** the World instant, when a caller pins it */
+    clock?: () => string;
+};
+/**
+ * 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 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
+ * pack fetches IN-PROCESS behind one router. Handing that entry `Bun.serve` is not an
+ * option, so the vendor HTTP adaptation has to be a value it can call. Keeping the server a
+ * thin `Bun.serve(fetch)` also means the local and hosted lanes execute the SAME bytes of
+ * serving code — the parity claim (R9) is about one code path, not two that resemble each
+ * other.
+ *
+ * SCOPING THE STORES AROUND IT: this fetch is ASYNC, so install the world store with
+ * `setActiveWorldStore(store)` in a try/finally — **not** `withWorldStore(store, fn)`, whose
+ * `finally` fires when `fn` RETURNS, i.e. at the first `await`, restoring the previous store
+ * under the rest of the request.
+ */
+export declare function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch;
+export declare function createStripeTwinServer(options: StripeTwinOptions): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/stripe-server.js

@@ -0,0 +1,326 @@
+// Stripe twin HTTP server — serve the full Stripe twin handler over HTTP so the
+// real `stripe` SDK ({host,port,protocol}) works unmodified (R1), or route the QA
+// backend sandbox's api.stripe.com interception at it. Form-encoded bodies (what
+// the SDK sends) pass through to the handler. Writable by default (the local stack
+// uses the twin as its authoritative Stripe); pass readOnly to reject writes (R4).
+//
+// 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 { bindSemantics, coreFor, createDerivedFetch, crossCutting, readParams, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import { stripeCheckoutFlow } from "./screens/checkout.js";
+import { stripeJs } from "./stripe-js.js";
+import { stripeFinancialConnectionsFlow } from "./screens/financial-connections.js";
+import { stripeIdentityFlow } from "./screens/identity.js";
+import { stripeOnboardingFlow } from "./screens/onboarding.js";
+import { stripePortalFlow } from "./screens/portal.js";
+import { stripePublicDetailsFlow } from "./screens/public-details.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { appsSecrets } from "./semantics/apps-secrets.js";
+import { balances } from "./semantics/balance.js";
+import { billing } from "./semantics/billing.js";
+import { charges } from "./semantics/charges.js";
+import { checkout } from "./semantics/checkout.js";
+import { connect } from "./semantics/connect.js";
+import { coupons } from "./semantics/coupons.js";
+import { creditNotes } from "./semantics/credit-notes.js";
+import { customers } from "./semantics/customers.js";
+import { disputes } from "./semantics/disputes.js";
+import { entitlements } from "./semantics/entitlements.js";
+import { ephemeralKeys } from "./semantics/ephemeral-keys.js";
+import { files } from "./semantics/files.js";
+import { invoices } from "./semantics/invoices.js";
+import { issuing, lapseRealtimeRequests } from "./semantics/issuing.js";
+import { paymentIntents } from "./semantics/payment-intents.js";
+import { paymentLinks } from "./semantics/payment-links.js";
+import { paymentMethods } from "./semantics/payment-methods.js";
+import { platform } from "./semantics/platform.js";
+import { plans } from "./semantics/plans.js";
+import { products } from "./semantics/products.js";
+import { radar } from "./semantics/radar.js";
+import { refunds } from "./semantics/refunds.js";
+import { setupIntents } from "./semantics/setup-intents.js";
+import { subscriptionSchedules } from "./semantics/subscription-schedules.js";
+import { subscriptions } from "./semantics/subscriptions.js";
+import { tax } from "./semantics/tax.js";
+import { terminal } from "./semantics/terminal.js";
+import { testClocks } from "./semantics/test-clocks.js";
+import { ledger } from "./semantics/ledger.js";
+import { tokens } from "./semantics/tokens.js";
+import { transfers } from "./semantics/transfers.js";
+import { treasury } from "./semantics/treasury.js";
+import { webhookEndpoints } from "./semantics/webhook-endpoints.js";
+import { advancePayouts, balanceBody, payDuePayouts } from "./semantics/balance.js";
+import { settleDueEntries } from "./semantics/ledger.js";
+import { settleHeldRefunds } from "./semantics/refunds.js";
+import { settleBankDebits } from "./semantics/payment-intents.js";
+import { lapseCoupons } from "./semantics/coupons.js";
+import { finishClockAdvances } from "./semantics/test-clocks.js";
+import { settleTopups } from "./semantics/terminal.js";
+import { finishReportRuns } from "./semantics/platform.js";
+import { advanceBilling } from "./semantics/renewals.js";
+import { refuseParameters } from "./stripe-params.js";
+import { afterStripeWrite, handleStripeDoor, PLATFORM_ACCOUNT_ID } from "./stripe-twin.js";
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+import { expandOf, render, servesCurrent, withoutEndpointSecret } from "./stripe-version.js";
+// ── 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 = {
+    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, scope) {
+    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, id) {
+    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 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
+ * pack fetches IN-PROCESS behind one router. Handing that entry `Bun.serve` is not an
+ * option, so the vendor HTTP adaptation has to be a value it can call. Keeping the server a
+ * thin `Bun.serve(fetch)` also means the local and hosted lanes execute the SAME bytes of
+ * serving code — the parity claim (R9) is about one code path, not two that resemble each
+ * other.
+ *
+ * SCOPING THE STORES AROUND IT: this fetch is ASYNC, so install the world store with
+ * `setActiveWorldStore(store)` in a try/finally — **not** `withWorldStore(store, fn)`, whose
+ * `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) {
+    const readOnly = options.readOnly ?? false;
+    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() {
+        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, url) => {
+        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) => {
+        const url = new URL(request.url);
+        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.find((o) => o.id === 'GetSubscriptions');
+    const catchUp = async (request) => {
+        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) => {
+        if (readOnly)
+            return Response.json({ error: 'twin is read-only; omit readOnly to accept writes' }, { status: 405 });
+        await catchUp(request);
+        const at = (account) => 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 = [];
+        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 } : {}) });
+            }
+        }
+        return Response.json({ delivered });
+    };
+    const served = async (request) => {
+        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) => {
+        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 async function createStripeTwinServer(options) {
+    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.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, coreMerges, scope) {
+    if (request.method !== 'POST' || (request.headers.get('content-type') ?? '').includes('multipart'))
+        return request;
+    const path = new URL(request.url).pathname;
+    let op;
+    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 : {};
+    const merges = coreMerges(op) && manifest.resources[resource]?.update !== 'replace';
+    let metadata;
+    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 }).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/dist/src/stripe-shared.d.ts

@@ -0,0 +1,106 @@
+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 declare const PLATFORM_DEFAULT_NAME = "Twin Inc.";
+export declare function publicBusinessName(account: StripeRow | undefined): string;
+/**
+ * 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 declare function formatStripeAmount(value: unknown, currency?: string): string;
+/**
+ * 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 declare function formatRecurring(recurring: unknown): string;
+/**
+ * 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 declare function formatPaymentMethod(pm: unknown): string;
+/**
+ * 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 declare function productImageUrls(images: unknown): string[];
+/**
+ * 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 declare function formatPaymentError(error: unknown): string;
+/**
+ * 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 declare function formatBalanceSummary(balance: unknown): Array<{
+    bucket: string;
+    text: string;
+}>;
+/**
+ * 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 declare function formatAccountFlags(account: unknown): AccountFlag[];
+/**
+ * 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 declare function accountCurrentlyDue(account: unknown): string[];
+/** Tone for a status pill: 'ok' (green), 'warn' (amber), 'bad' (red), '' (neutral). */
+export type PillTone = 'ok' | 'warn' | 'bad' | '';
+export declare function statusTone(value: unknown): PillTone;
+/** True when a key names a field whose value is a Stripe object id we can link. */
+export declare function isReferenceKey(key: string): boolean;
+/** The collection a reference field points at, or undefined if not a reference. */
+export declare function referenceCollection(key: string): string | undefined;
+/** 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 declare function flattenStripeValue(value: unknown, opts?: {
+    label?: string;
+    depth?: number;
+    currency?: string;
+}): FlatLine[];
+/**
+ * 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[];
+};
+export declare function resolveCrossRefs(collection: string, row: StripeRow, data: Record<string, StripeRow[]>): CrossRefs;