@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/stripe-shared.js

@@ -0,0 +1,273 @@
+// 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.
+/** 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) {
+    const named = (v) => (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, currency) {
+    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) {
+    if (!recurring || typeof recurring !== 'object')
+        return '';
+    const r = recurring;
+    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) {
+    if (!pm || typeof pm !== 'object')
+        return '—';
+    const m = pm;
+    const card = m.card && typeof m.card === 'object' ? m.card : 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) {
+    if (!Array.isArray(images))
+        return [];
+    return images.filter((u) => 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) {
+    if (!error || typeof error !== 'object')
+        return '';
+    const e = error;
+    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) {
+    if (!balance || typeof balance !== 'object')
+        return [];
+    const b = balance;
+    const sum = (arr) => {
+        if (!Array.isArray(arr) || arr.length === 0)
+            return formatStripeAmount(0, 'usd');
+        return arr
+            .map((e) => formatStripeAmount(e?.amount, e?.currency))
+            .join(', ');
+    };
+    const out = [];
+    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;
+}
+export function formatAccountFlags(account) {
+    if (!account || typeof account !== 'object')
+        return [];
+    const a = account;
+    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) {
+    if (!account || typeof account !== 'object')
+        return [];
+    const req = account.requirements;
+    if (!req || typeof req !== 'object')
+        return [];
+    const due = req.currently_due;
+    return Array.isArray(due) ? due.filter((d) => typeof d === 'string') : [];
+}
+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) {
+    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) {
+    return REFERENCE_FIELDS.has(key);
+}
+// field name → the COLLECTION it points at (so the UI can jump sections + select).
+const REFERENCE_FIELD_MAP = {
+    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) {
+    return REFERENCE_FIELD_MAP[key];
+}
+/**
+ * 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, opts = {}) {
+    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 = 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;
+        // 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 = 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 } : {}) }];
+}
+const LABELERS = {
+    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, row) {
+    return (LABELERS[collection] ?? ((r) => r.id))(row);
+}
+export function resolveCrossRefs(collection, row, data) {
+    const outgoing = [];
+    const incoming = [];
+    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 };
+}

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

@@ -0,0 +1,155 @@
+export type StripeRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    idempotencyKey?: string;
+    apiVersion?: string;
+    stripeAccount?: string;
+};
+export type StripeResponse = {
+    status: number;
+    body: unknown;
+};
+export declare const TWIN_API_VERSION: string;
+export declare function isValidApiVersion(v: string): boolean;
+export declare function validateMoney(params: Record<string, unknown>): StripeResponse | null;
+type DeclineOutcome = {
+    code: string;
+    decline_code?: string;
+    message: string;
+};
+export declare const TEST_TOKEN_DECLINES: Record<string, DeclineOutcome | null>;
+/** A stored subject by stored type and id, in the pack's view (tombstones included): how the
+ *  semantics hand these helpers the tree they read (semantics/shared.ts `finder`). */
+export type FindStored = (storedType: string, id: string) => Record<string, unknown> | undefined;
+export declare function declineFor(find: FindStored, ...paramSets: Array<Record<string, unknown>>): DeclineOutcome | null | undefined;
+export declare function requiresAuthentication(...paramSets: Array<Record<string, unknown>>): boolean;
+export declare function threeDsNextAction(): Record<string, unknown>;
+export declare function requiresMicrodeposits(...paramSets: Array<Record<string, unknown>>): boolean;
+export declare function microdepositsNextAction(): Record<string, unknown>;
+export declare function verifyMicrodeposits(params: Record<string, unknown>, _existing: Record<string, unknown>): StripeResponse | null;
+/** A card error's body: `charge` "For card errors, the ID of the failed charge", and `payment_intent` "The PaymentIntent
+ *  object for errors returned on a request involving a PaymentIntent" (docs.stripe.com/api/errors). */
+export declare function cardError(outcome: DeclineOutcome, attach?: {
+    charge?: string;
+    payment_intent?: Record<string, unknown>;
+}): StripeResponse;
+export declare function nowUnix(occurredAt?: string): number;
+export declare function mintClientSecret(id: string): string;
+export declare const OBJECT_NAME: Record<string, string>;
+export declare function view(type: string, r: Record<string, unknown>): Record<string, unknown>;
+export declare function paginate(items: Array<Record<string, unknown>>, params: Record<string, unknown>): {
+    page: Array<Record<string, unknown>>;
+    hasMore: boolean;
+};
+/** What follows every stored Stripe write: the webhook for the state change and the stored Event
+ *  the Events API lists. The derived pack's write hook (manifest.ts) is this same function. */
+export declare function afterStripeWrite(type: string, op: string, out: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, stripeAccount?: string): Promise<void>;
+/** The id the World's next event takes: its place in the World's events, so it is deterministic and never repeats
+ *  within a World (a Balance has no id of its own, so nothing about the object can tell two events apart). The number
+ *  is taken synchronously — the count of stored events, or the last number taken, whichever is higher. */
+export declare function nextStripeEventId(root?: string): string;
+export declare function persistStripeEvent(eventType: string, resource: Record<string, unknown>, root?: string, occurredAt?: string, apiVersion?: string, account?: string, id?: string): Promise<void>;
+export declare function asBool(v: unknown): boolean;
+export declare function searchOver(items: Array<Record<string, unknown>>, params: Record<string, unknown>, path: string): StripeResponse;
+export declare function subscriptionHasPrice(sub: Record<string, unknown>, priceId: string): boolean;
+export declare function subscriptionCouponParam(params: Record<string, unknown>): string | undefined;
+/** A coupon applied: the Discount object, naming what it applies to ("customer: The ID of the customer associated
+ *  with this discount"; "subscription: The subscription that this coupon is applied to, if it is applied to a
+ *  particular subscription", docs.stripe.com/api/discounts/object). */
+export declare function buildDiscount(coupon: Record<string, unknown>, customer: string, at: number, on?: {
+    subscription?: string;
+}): Record<string, unknown>;
+export declare function subscriptionItemPairs(sub: Record<string, unknown>): Array<{
+    price: string;
+    quantity: number;
+}>;
+export declare function subscriptionItemEntries(value: unknown): Array<Record<string, unknown>>;
+type BillingInterval = 'day' | 'week' | 'month' | 'year';
+export declare function resolveSubscriptionBillingInterval(entries: Array<Record<string, unknown>>, find: FindStored): {
+    interval: BillingInterval;
+    interval_count: number;
+    resolved: boolean;
+};
+export declare function addBillingInterval(atUnix: number, interval: BillingInterval, count: number): number;
+/** What a subscription item carries of its price: the Price itself and its plan view (a subscription item answers both,
+ *  docs.stripe.com/api/subscription_items/object), by the price's id or an already-resolved Price. */
+export declare function subscriptionItemPrice(p: unknown, find: FindStored): {
+    price: Record<string, unknown> | string | null;
+    plan: Record<string, unknown> | null;
+};
+export declare function buildSubscriptionItemsList(entries: Array<Record<string, unknown>>, subId: string, at: number, find: FindStored): Record<string, unknown>;
+/** What a per-unit price bills for a quantity: its `unit_amount` times the quantity, or, for a price given only as a
+ *  decimal (`unit_amount_decimal`, "represented as a decimal string with at most 12 decimal places", spec/openapi.json.gz),
+ *  the decimal times the quantity rounded to a whole amount: "rounding occurs after multiplying the quantity by the
+ *  decimal amount ... `0.05 * 30 = 1.5`, which rounds up to 2 cents" (docs.stripe.com/products-prices/manage-prices).
+ *  Where the documentation stops and the twin decides: the rounding is to the nearest whole amount, halves up. */
+export declare function priceAmount(price: Record<string, unknown> | undefined | null, quantity: number): number;
+export declare function applyCouponDiscount(subtotal: number, coupon: Record<string, unknown> | undefined): number;
+export declare function resolveTrial(params: Record<string, unknown>, at: number): {
+    start: number;
+    end: number;
+} | undefined;
+export declare function stashVendorType(_type: string, fields: Record<string, unknown>): Record<string, unknown>;
+export declare function embedIssuingAuthorizationCard(body: Record<string, unknown>, root?: string): Record<string, unknown>;
+export declare function emptySpendingControls(): Record<string, unknown>;
+export declare function normalizeSpendingControls(raw: unknown, currency: string | null): {
+    controls?: Record<string, unknown>;
+    error?: StripeResponse;
+};
+type PriorAuthorization = {
+    amount: number;
+    created: number;
+    category: string;
+};
+export declare function spendingControlsViolation(controls: unknown, opts: {
+    amount: number;
+    category: string;
+    country: string | null;
+    nowSec: number;
+    priorApproved: PriorAuthorization[];
+}): string | null;
+export declare function disputeEvidence(): Record<string, unknown>;
+export declare function paymentMethodSubObject(pmType: string, params: Record<string, unknown>): Record<string, unknown>;
+export declare const ACCOUNT_TYPES: Set<string>;
+export declare const PLATFORM_ACCOUNT_ID = "acct_twin_self";
+export declare function accountRequirements(): Record<string, unknown>;
+export declare function accountCapabilities(params: Record<string, unknown>): Record<string, unknown>;
+export declare function accountSettings(input: unknown, existing?: Record<string, unknown>): Record<string, unknown>;
+export type CheckoutItem = {
+    object: 'item';
+    id: string;
+    amount_discount: number;
+    amount_subtotal: number;
+    amount_tax: number;
+    amount_total: number;
+    currency: string;
+    description: string | null;
+    price: Record<string, unknown> | string | null;
+    quantity: number;
+};
+export declare function resolveLineItem(entry: Record<string, unknown>, index: number, fallbackCurrency: string, find: FindStored): {
+    item: CheckoutItem;
+    priceMissing?: string;
+};
+export declare function lineItemEntries(params: Record<string, unknown>): Array<Record<string, unknown>>;
+export declare function chargeDefaults(chargeId: string, amount: number, captured: boolean, occurredAt?: string): Record<string, unknown>;
+/**
+ * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
+ * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
+ * pass straight through). A read-only twin never stores (it cannot write).
+ */
+/** Stripe's API as one call: the request goes through the pack's own dispatch (the derived dispatch over
+ *  its semantics, its derived core and the hand-written routes below), so a caller that holds no
+ *  HTTP server reaches exactly what an SDK does. `occurredAt` pins the World instant. */
+export declare function handleStripeTwinRequest(req: StripeRequest): Promise<StripeResponse>;
+/**
+ * The twin's doors: what stands in for an act Stripe's API does not have, each under `/_twin/`. The
+ * platform's own account settings (its payout schedule) change on Stripe's Dashboard, which has no API:
+ * POST /_twin/account stands in for that page. Answers nothing for any other path.
+ */
+export declare function handleStripeDoor(req: StripeRequest, params: Record<string, unknown>): Promise<StripeResponse | undefined>;
+export {};