@volter/twin-stripe 0.1.2 → 2.0.1

package/src/stripe-shared.ts

@@ -0,0 +1,297 @@
+// 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.';
+/** The bookkeeping type of a connected account's Connect OAuth connection (screens/connect-oauth.tsx): one row per
+ *  account, `revoked: true` once deauthorized or its code reused. Read by the account list and the event path too. */
+export const OAUTH_CONNECTIONS = '_oauth_connection';
+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 };
+}