@volter/twin-stripe 0.1.0

package/src/stripe-events.ts

@@ -0,0 +1,202 @@
+// Stripe event/webhook emission (scorecard R17). Real Stripe fires `event`
+// objects (and webhooks) on state changes — payment_intent.succeeded,
+// customer.subscription.created, invoice.paid, … — so an app's webhook handler
+// runs. A faithful twin must too. On a twin write we build the Stripe `event`
+// envelope and deliver it to registered endpoints (injected delivery: fake in
+// tests, HTTP POST live, failures swallowed like the real vendor).
+export type StripeEvent = {
+  id: string;
+  object: 'event';
+  type: string;
+  created: number;
+  livemode: false;
+  data: { object: Record<string, unknown> };
+};
+export type StripeEventDelivery = (url: string, event: StripeEvent) => Promise<void> | void;
+
+// ── Webhook signature verification (Stripe's scheme) ────────────────────────────
+// Real Stripe signs each webhook delivery with an HMAC-SHA256 over `${timestamp}.${payload}`
+// keyed by the endpoint's signing secret, and sends it in the `Stripe-Signature` header as
+// `t=<unix>,v1=<hex-sig>`. The SDK's `stripe.webhooks.constructEvent(payload, header, secret)`
+// recomputes the signature and 400s on a mismatch / stale timestamp; tests build the header
+// with `stripe.webhooks.generateTestHeaderString(...)`. We reproduce BOTH, byte-for-byte, so a
+// real `stripe` SDK consumer verifies twin-delivered webhooks unchanged. Pure Node crypto —
+// no network, fully deterministic. `node:crypto` is required lazily (inside the functions that
+// use it) rather than as a top-level static import, so this module can be pulled into the
+// browser bundle of the UI mirror without Bun's browser target choking on `node:crypto` — the
+// signature helpers are server-only and never reached in the browser path.
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return require('node:crypto') as NodeCrypto;
+}
+
+/** HMAC-SHA256(secret, `${timestamp}.${payload}`) as lowercase hex — Stripe's v1 signature. */
+export function computeStripeSignature(payload: string, secret: string, timestamp: number): string {
+  return nodeCrypto().createHmac('sha256', secret).update(`${timestamp}.${payload}`, 'utf8').digest('hex');
+}
+
+/** Build a `Stripe-Signature` header value for `payload` (mirrors generateTestHeaderString). */
+export function generateTestHeaderString(opts: { payload: string; secret: string; timestamp?: number; scheme?: string }): string {
+  const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1000);
+  const scheme = opts.scheme ?? 'v1';
+  const signature = computeStripeSignature(opts.payload, opts.secret, timestamp);
+  return `t=${timestamp},${scheme}=${signature}`;
+}
+
+/** Parse a `Stripe-Signature` header into its timestamp + the list of v1 signatures. */
+function parseSignatureHeader(header: string): { timestamp: number; signatures: string[] } {
+  let timestamp = -1;
+  const signatures: string[] = [];
+  for (const part of header.split(',')) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === 't') timestamp = Number(value);
+    else if (key === 'v1') signatures.push(value);
+  }
+  return { timestamp, signatures };
+}
+
+export class StripeSignatureVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StripeSignatureVerificationError';
+  }
+}
+
+/**
+ * Verify a webhook payload + signature header against the signing secret and return the
+ * parsed event (mirrors `stripe.webhooks.constructEvent`). Throws a
+ * StripeSignatureVerificationError on a malformed/missing header, a signature that does
+ * not match, or (when `tolerance` is given) a timestamp outside the allowed window.
+ */
+export function constructEvent(payload: string, header: string, secret: string, opts: { tolerance?: number; now?: number } = {}): StripeEvent {
+  if (!header) throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
+  const { timestamp, signatures } = parseSignatureHeader(header);
+  if (timestamp < 0 || signatures.length === 0) {
+    throw new StripeSignatureVerificationError('Unable to extract timestamp and signatures from header');
+  }
+  const expected = computeStripeSignature(payload, secret, timestamp);
+  const expectedBuf = Buffer.from(expected, 'utf8');
+  const matched = signatures.some((s) => {
+    const sBuf = Buffer.from(s, 'utf8');
+    return sBuf.length === expectedBuf.length && nodeCrypto().timingSafeEqual(sBuf, expectedBuf);
+  });
+  if (!matched) {
+    throw new StripeSignatureVerificationError('No signatures found matching the expected signature for payload.');
+  }
+  if (opts.tolerance !== undefined) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (now - timestamp > opts.tolerance) {
+      throw new StripeSignatureVerificationError('Timestamp outside the tolerance zone');
+    }
+  }
+  return JSON.parse(payload) as StripeEvent;
+}
+
+const registry: string[] = [];
+export function registerStripeWebhook(url: string): void {
+  if (!registry.includes(url)) registry.push(url);
+}
+export function unregisterStripeWebhook(url: string): void {
+  const i = registry.indexOf(url);
+  if (i !== -1) registry.splice(i, 1);
+}
+export function clearStripeWebhooks(): void {
+  registry.length = 0;
+}
+export function listStripeWebhooks(): string[] {
+  return [...registry];
+}
+
+// twin write operation → Stripe event type (the ones an app's webhooks care about).
+// Returns null when an operation has no event (e.g. a plain create/retrieve we
+// don't model an event for).
+export function eventTypeFor(operation: string): string | null {
+  // Several twin write operations ARE already the Stripe event type (we record the
+  // op as `<resource>.<event>` so it maps 1:1): payment_intent.amount_capturable_updated,
+  // payment_intent.canceled, payment_intent.succeeded. Those pass through directly.
+  const PASSTHROUGH = new Set([
+    'payment_intent.amount_capturable_updated', 'payment_intent.canceled', 'payment_intent.succeeded',
+    'payment_intent.payment_failed', 'payment_intent.created', 'payment_intent.processing',
+    'payment_intent.requires_action',
+    'charge.succeeded', 'charge.captured', 'charge.refunded', 'charge.dispute.created',
+    'customer.updated', 'customer.deleted', 'invoice.created', 'invoice.finalized',
+    'invoice.paid', 'invoice.payment_failed', 'invoice.voided', 'invoice.marked_uncollectible', 'invoice.sent',
+    'customer.subscription.updated', 'customer.subscription.paused', 'customer.subscription.resumed',
+    'payout.created', 'payout.paid', 'payout.canceled', 'price.created', 'product.created',
+    'setup_intent.succeeded', 'setup_intent.created',
+  ]);
+  if (PASSTHROUGH.has(operation)) return operation;
+  switch (operation) {
+    case 'customer.create': return 'customer.created';
+    case 'payment_intent.create': return 'payment_intent.created';
+    case 'payment_intent.confirm': return 'payment_intent.succeeded';
+    case 'payment_method.attach': return 'payment_method.attached';
+    case 'payment_method.detach': return 'payment_method.detached';
+    case 'setup_intent.confirm': return 'setup_intent.succeeded';
+    case 'subscription.create': return 'customer.subscription.created';
+    case 'subscription.update': return 'customer.subscription.updated';
+    case 'subscription.cancel': return 'customer.subscription.deleted';
+    case 'invoice.finalize': return 'invoice.finalized';
+    case 'invoice.pay': return 'invoice.paid';
+    case 'invoice.void': return 'invoice.voided';
+    case 'refund.create': return 'charge.refunded';
+    case 'dispute.create': return 'charge.dispute.created';
+    case 'payout.create': return 'payout.created';
+    case 'product.create': return 'product.created';
+    case 'price.create': return 'price.created';
+    default: return null;
+  }
+}
+
+let counter = 0;
+const httpDelivery: StripeEventDelivery = async (url, event) => {
+  try {
+    await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': 'twin' }, body: JSON.stringify(event) });
+  } catch {
+    /* fire-and-forget */
+  }
+};
+
+// Default deliverer override (a TEST SEAM). The twin's write path emits events without
+// threading a per-call deliverer, so to drive event delivery fully OFFLINE/deterministically
+// — no real sockets — a test installs a fake sink here. When unset, real HTTP POST is used
+// (prod behavior). This keeps D5 honest: verify() exercises the twin's own emission, in-process.
+let defaultDelivery: StripeEventDelivery | null = null;
+/** Install a default deliverer used by the write path when no per-call `deliver` is passed. */
+export function setStripeEventDelivery(deliver: StripeEventDelivery | null): void {
+  defaultDelivery = deliver;
+}
+
+/**
+ * Emit a Stripe event for a twin write to registered endpoints. `resource` is the
+ * Stripe object the event is about. `occurredAt` is caller-supplied (deterministic).
+ * Returns the delivered events (for assertions); no-op when nothing is registered
+ * or the operation has no mapped event type.
+ */
+export async function emitStripeEvent(
+  operation: string,
+  resource: Record<string, unknown>,
+  opts: { occurredAt: string; deliver?: StripeEventDelivery } = { occurredAt: '1970-01-01T00:00:00.000Z' },
+): Promise<StripeEvent[]> {
+  const type = eventTypeFor(operation);
+  if (!type || registry.length === 0) return [];
+  const deliver = opts.deliver ?? defaultDelivery ?? httpDelivery;
+  const event: StripeEvent = {
+    id: `evt_twin_${++counter}`,
+    object: 'event',
+    type,
+    created: Math.floor(Date.parse(opts.occurredAt) / 1000) || 0,
+    livemode: false,
+    data: { object: resource },
+  };
+  const out: StripeEvent[] = [];
+  for (const url of registry) {
+    await deliver(url, event);
+    out.push(event);
+  }
+  return out;
+}

package/src/stripe-form.ts

@@ -0,0 +1,35 @@
+// Parse a Stripe x-www-form-urlencoded body, reconstructing Stripe's BRACKET
+// notation into nested objects/arrays (recurring[interval], items[0][price],
+// metadata[key], expand[]) and coercing numeric strings — so the twin stores the
+// same shapes the real Stripe SDK sends, not mangled flat keys. Shared by the
+// request handler and tests.
+export function parseStripeForm(body: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [rawKey, rawValue] of new URLSearchParams(body)) {
+    // Coerce the wire types the real Stripe API coerces server-side: integer-looking
+    // strings → numbers, and the literal booleans Stripe accepts on form fields
+    // (active, captured, auto_advance, cancel_at_period_end, …) → real booleans, so
+    // the stored shapes match what live Stripe would return (boolean, not "true").
+    const value: unknown = /^-?\d+$/.test(rawValue) ? Number(rawValue)
+      : rawValue === 'true' ? true
+      : rawValue === 'false' ? false
+      : rawValue;
+    // split "a[b][0][c]" → ["a","b","0","c"]
+    const parts = rawKey.replace(/\]/g, '').split('[');
+    let node: any = out;
+    for (let i = 0; i < parts.length; i++) {
+      const key = parts[i]!;
+      const last = i === parts.length - 1;
+      if (last) {
+        if (key === '') { (Array.isArray(node) ? node : (node = node)).push?.(value); }
+        else node[key] = value;
+        continue;
+      }
+      const nextKey = parts[i + 1]!;
+      const wantArray = nextKey === '' || /^\d+$/.test(nextKey);
+      if (node[key] === undefined) node[key] = wantArray ? [] : {};
+      node = node[key];
+    }
+  }
+  return out;
+}

package/src/stripe-mirror-ui.ts

@@ -0,0 +1,345 @@
+// Stripe MIRROR UI (scorecard R13) — a Stripe-dashboard-like view served as a
+// React/TSX app (bundled by Bun, the repo convention; cf. tracker-visualizer).
+// It renders by consuming the twin's OWN REST API on the same origin
+// (/v1/<collection>) — the same endpoints the app uses. Per-vendor + concrete.
+import { handleStripeTwinRequest } from './stripe-twin.ts';
+
+const CLIENT_ENTRY = new URL('../client/stripe-mirror.tsx', import.meta.url).pathname;
+const CLIENT_CSS = new URL('../client/stripe-mirror.css', import.meta.url).pathname;
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format/resolution helpers.
+//
+// These are intentionally framework-agnostic (plain data in → plain data out) so
+// they can be unit-tested in isolation AND imported by the React/TSX client
+// (Bun tree-shakes the server-only exports below out of the browser bundle).
+// Keep them free of any `@volter/twin`/`Bun`/`handleStripeTwinRequest` usage.
+// ---------------------------------------------------------------------------
+
+export type StripeRow = Record<string, any>;
+
+/** 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 ?? ''}`,
+  customer_balance_transactions: (r) => `${formatStripeAmount(r.amount, r.currency)} · ${r.id}`,
+};
+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 };
+}
+
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Stripe UI mirror (twin)</title><link rel="stylesheet" href="/assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`;
+
+let clientBundle: Promise<string> | null = null;
+/** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
+export function buildStripeMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY], target: 'browser', minify: true })
+      .then(async (result) => {
+        if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || 'stripe mirror client build failed');
+        return result.outputs[0]!.text();
+      })
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+/** Serve the Stripe dashboard mirror UI (React app) + its backing REST API. */
+export function createStripeMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildStripeMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return new Response(Bun.file(CLIENT_CSS), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // everything else → the twin's REST API (the React client fetches /v1/<collection>)
+      const body = request.method === 'GET' ? '' : await request.text();
+      const { status, body: out } = await handleStripeTwinRequest({ method: request.method, path: url.pathname + (url.search || ''), body, ...(options.root !== undefined ? { root: options.root } : {}) });
+      return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json' } });
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). The dashboard itself is the React client. */
+export function stripeMirrorHtml(): string {
+  return APP_SHELL;
+}

package/src/stripe-server.ts

@@ -0,0 +1,46 @@
+// 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).
+import { handleStripeTwinRequest } from './stripe-twin.ts';
+
+export function createStripeTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
+  const readOnly = options.readOnly ?? false;
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      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 } : {}),
+        // Stamp real wall-clock time so served objects get a real `created` epoch (not 1970).
+        // Embedded/test callers pass their own occurredAt for determinism; the live HTTP path
+        // — what the real SDK hits — should reflect actual time, like the real vendor.
+        occurredAt: new Date().toISOString(),
+        ...(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 { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}