@volter/twin-stripe 0.1.2 → 2.0.0

package/dist/src/stripe-ui-conformance.d.ts

@@ -0,0 +1,5 @@
+import { type UiSurface, type UiCompletenessReport } from '@volter/world-tooling';
+/** What Stripe's Dashboard shows, classified vs the twin + its Dashboard. */
+export declare const STRIPE_UI_INVENTORY: UiSurface[];
+/** Read-only completeness check over the declared Stripe UI inventory. */
+export declare function stripeUiConformance(): UiCompletenessReport;

package/dist/src/stripe-ui-conformance.js

@@ -0,0 +1,79 @@
+// Stripe UI conformance — the declared surface inventory of Stripe's Dashboard, classified against THIS
+// twin, and the read-only completeness check over it.
+//
+// Honesty: `status` is the current truth, verified by the structural cross-check in
+// stripe-ui-conformance.test.ts (which builds the actual Dashboard bundle and asserts each 'rendered'
+// surface's label/class is really present — downgrading to 'modeled' otherwise). `rendered` = the
+// Dashboard shows it today; `modeled` = the twin has the data but the Dashboard doesn't show it; `unmodeled`
+// = Stripe shows it but the twin doesn't model it.
+//
+// Classified against the Dashboard (client/stripe-mirror.tsx, reading through client/dashboard-api.ts):
+// Home, Balances, Transactions > Payments and a payment's page, Customers and a customer's page, Product
+// catalog, Billing's Subscriptions (and a subscription's page) and Invoices (and an invoice's page),
+// Developers, Settings, and the resource lists under Connect, Payments, Reporting and More.
+import { checkUiCompleteness } from '@volter/world-tooling';
+/** What Stripe's Dashboard shows, classified vs the twin + its Dashboard. */
+export const STRIPE_UI_INVENTORY = [
+    // --- shell ---
+    { key: 'navigation', label: 'Left navigation (Home, Balances, Transactions, Customers, Product catalog, Billing, Developers)', status: 'rendered' },
+    { key: 'testModeBand', label: 'Test-mode band', status: 'rendered' },
+    { key: 'search', label: 'Search across customers, payments, subscriptions, invoices, products', status: 'rendered' },
+    { key: 'statusPill', label: "Status pills in Stripe's words (Succeeded, Refunded, Failed, Active, Trialing, Paid, …)", status: 'rendered' },
+    { key: 'amountFormatting', label: 'Currency-formatted amounts with the currency code', status: 'rendered' },
+    // --- Home and Balances ---
+    { key: 'homeToday', label: "Home: today's gross volume, balance and payouts", status: 'rendered' },
+    { key: 'homeOverview', label: 'Home: overview metrics (gross/net volume, successful and failed payments, customers, subscribers)', status: 'rendered' },
+    { key: 'balanceSummary', label: 'Balances: incoming and available per currency', status: 'rendered' },
+    { key: 'balanceTransactions', label: 'Balances: recent activity (balance transactions) and payouts', status: 'rendered' },
+    // --- Payments ---
+    { key: 'paymentList', label: 'Payments list: amount + currency, status, payment method, description, customer, date', status: 'rendered' },
+    { key: 'paymentFilters', label: 'Payments status tabs with counts, and filter chips', status: 'rendered' },
+    { key: 'paymentRefundedDate', label: 'Payments list: refunded date and decline reason', status: 'rendered' },
+    { key: 'paymentExport', label: 'Payments export', status: 'rendered' },
+    { key: 'paymentTimeline', label: "A payment's timeline from its events", status: 'rendered' },
+    { key: 'paymentBreakdown', label: "A payment's breakdown (amount, refunded, net)", status: 'rendered' },
+    { key: 'paymentFees', label: "A payment's Stripe fees (balance transaction fee details)", status: 'unmodeled' },
+    { key: 'paymentRefunds', label: "A payment's refunds", status: 'rendered' },
+    { key: 'paymentMethodDetails', label: "A payment's card: last four, expiry, type, origin, CVC check", status: 'rendered' },
+    { key: 'paymentDecline', label: 'A declined payment states its error and decline code', status: 'rendered' },
+    { key: 'refundDialog', label: 'Refund a payment in full or in part, with a reason', status: 'rendered' },
+    { key: 'disputes', label: 'Disputes', status: 'rendered' },
+    // --- Customers ---
+    { key: 'customerList', label: 'Customers list: name, email, default payment method, created, total spend, payments, refunds', status: 'rendered' },
+    { key: 'createCustomer', label: 'Create customer', status: 'rendered' },
+    { key: 'customerDetails', label: "A customer's details (ID, since, email, description, billing details)", status: 'rendered' },
+    { key: 'customerSubscriptions', label: "A customer's subscriptions", status: 'rendered' },
+    { key: 'customerPayments', label: "A customer's payments", status: 'rendered' },
+    { key: 'customerPaymentMethods', label: "A customer's saved payment methods, default marked", status: 'rendered' },
+    { key: 'customerInvoices', label: "A customer's invoices", status: 'rendered' },
+    { key: 'customerEvents', label: "A customer's events", status: 'rendered' },
+    // --- Billing ---
+    { key: 'subscriptionList', label: 'Subscriptions list: customer, status, billing, product, amount, created', status: 'rendered' },
+    { key: 'subscriptionDetails', label: "A subscription's details: customer, period, trial, billing method, payment method", status: 'rendered' },
+    { key: 'subscriptionPricing', label: "A subscription's pricing items", status: 'rendered' },
+    { key: 'cancelSubscription', label: 'Cancel a subscription now or at period end', status: 'rendered' },
+    { key: 'invoiceList', label: 'Invoices list: amount, status, number, customer, due, created', status: 'rendered' },
+    { key: 'invoiceDetail', label: "An invoice's summary lines and totals", status: 'rendered' },
+    { key: 'quotes', label: 'Quotes', status: 'rendered' },
+    // --- Product catalog ---
+    { key: 'productCatalog', label: 'Product catalog: name, pricing, created, updated', status: 'rendered' },
+    { key: 'createProduct', label: 'Create product', status: 'rendered' },
+    { key: 'coupons', label: 'Coupons', status: 'rendered' },
+    // --- Developers and Settings ---
+    { key: 'apiKeys', label: 'API keys', status: 'rendered' },
+    { key: 'webhooks', label: 'Webhook endpoints', status: 'rendered' },
+    { key: 'eventsLog', label: 'Events', status: 'rendered' },
+    { key: 'payoutSchedule', label: 'Settings: payout schedule', status: 'rendered' },
+    // --- under More ---
+    { key: 'connectAccounts', label: 'Connect: connected accounts, readiness flags and requirements due', status: 'rendered' },
+    { key: 'connectTransfers', label: 'Connect: transfers', status: 'rendered' },
+    { key: 'radar', label: 'Radar: reviews, lists, rules', status: 'rendered' },
+    { key: 'terminal', label: 'Terminal: readers, locations', status: 'rendered' },
+    { key: 'issuing', label: 'Issuing: cards, cardholders', status: 'rendered' },
+    { key: 'taxRates', label: 'Tax: tax rates', status: 'rendered' },
+    { key: 'reports', label: 'Reporting: report runs', status: 'rendered' },
+];
+/** Read-only completeness check over the declared Stripe UI inventory. */
+export function stripeUiConformance() {
+    return checkUiCompleteness('stripe', STRIPE_UI_INVENTORY);
+}

package/dist/src/stripe-ui-structure.d.ts

@@ -0,0 +1,3 @@
+import { type UiStructureReport } from '@volter/world-tooling';
+/** Build the structural checklist from the real rendered markup and run it. */
+export declare function stripeUiStructure(): UiStructureReport;

package/dist/src/stripe-ui-structure.js

@@ -0,0 +1,168 @@
+// The Stripe Dashboard — structural DOM checklist (RUNG-5).
+//
+// Completeness (stripe-ui-conformance.ts) asks "does the Dashboard SHOW the data?". Structure asks
+// "does its rendered DOM have the landmarks Stripe's Dashboard has?": the left navigation at Stripe's
+// paths, the test-mode band, the Payments table with Stripe's columns and status pills, a payment's page
+// (amount, status, timeline from its events, breakdown, refunds, card), a customer's page (details,
+// subscriptions, payments, payment methods, invoices), a subscription's page (pricing, period, invoices,
+// the cancel control), the balance buckets, a connected account's readiness and the resource lists.
+//
+// Each check's `present` is computed from the ACTUAL markup renderToStaticMarkup() produces from the
+// Dashboard's own components (client/stripe-mirror.tsx) over objects shaped as the API returns them, so a
+// check cannot pass unless the component truly emits that structure. Read-only; deterministic.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { checkUiStructure } from '@volter/world-tooling';
+import { SECTIONS, SideNav, ListPane, TestModeBand, PaymentsTable, PaymentDetailView, CustomerDetailView, SubscriptionDetailView, BalanceSummary, ConnectAccountPanel, } from "../client/stripe-mirror.js";
+const noop = () => { };
+const AT = 1790263345;
+const CUSTOMER = { id: 'cus_twin001', object: 'customer', name: 'Ada Lovelace', email: 'ada@example.com', created: AT, invoice_settings: { default_payment_method: 'pm_twin001' }, metadata: {} };
+const CARD = { id: 'pm_twin001', object: 'payment_method', type: 'card', customer: 'cus_twin001', card: { brand: 'visa', last4: '4242', exp_month: 12, exp_year: 2034, funding: 'credit', country: 'US', checks: { cvc_check: 'pass' } }, billing_details: {} };
+const INTENT = { id: 'pi_twin001', object: 'payment_intent', amount: 30000, currency: 'usd', status: 'succeeded', customer: 'cus_twin001', payment_method: 'pm_twin001', latest_charge: 'ch_twin001', description: 'Annual workshop seat', created: AT, metadata: {} };
+const CHARGE = { id: 'ch_twin001', object: 'charge', amount: 30000, currency: 'usd', status: 'succeeded', refunded: false, amount_refunded: 10000, payment_intent: 'pi_twin001', customer: 'cus_twin001', created: AT };
+const REFUND = { id: 're_twin001', object: 'refund', amount: 10000, currency: 'usd', status: 'succeeded', charge: 'ch_twin001', payment_intent: 'pi_twin001', reason: 'requested_by_customer', created: AT + 60 };
+const event = (id, type, object, created) => ({ id, object: 'event', type, created, data: { object } });
+const PARTIAL = {
+    id: 'pi_twin001', amount: 30000, currency: 'usd', status: 'partially_refunded', description: 'Annual workshop seat', created: AT,
+    customer: CUSTOMER, charge: CHARGE, intent: INTENT, paymentMethod: CARD, amountRefunded: 10000, refundedAt: AT + 60,
+    refunds: [REFUND],
+    events: [
+        event('evt_3', 'charge.refunded', CHARGE, AT + 60),
+        event('evt_2', 'payment_intent.succeeded', INTENT, AT + 1),
+        event('evt_1', 'payment_intent.created', INTENT, AT),
+    ],
+};
+const DECLINED_INTENT = {
+    id: 'pi_twin009', object: 'payment_intent', amount: 15000, currency: 'usd', status: 'requires_payment_method', customer: 'cus_twin001', created: AT,
+    last_payment_error: { type: 'card_error', code: 'card_declined', decline_code: 'insufficient_funds', message: 'Your card has insufficient funds.', param: 'card' },
+};
+const DECLINED = {
+    id: 'pi_twin009', amount: 15000, currency: 'usd', status: 'failed', created: AT, customer: CUSTOMER, intent: DECLINED_INTENT,
+    amountRefunded: 0, declineReason: 'Insufficient funds', declineMessage: 'Your card has insufficient funds.', refunds: [],
+    events: [event('evt_9', 'payment_intent.payment_failed', DECLINED_INTENT, AT)],
+};
+const REFUNDED = { id: 'pi_twin002', amount: 2500, currency: 'usd', status: 'refunded', description: 'Twin T-shirt', created: AT, customer: CUSTOMER, paymentMethod: CARD, amountRefunded: 2500, refundedAt: AT + 30 };
+const PAYMENTS = [PARTIAL, DECLINED, REFUNDED, { ...REFUNDED, id: 'pi_twin003', status: 'succeeded', amountRefunded: 0, refundedAt: undefined, description: 'Consulting' }];
+const PRODUCT = { id: 'prod_twin001', object: 'product', name: 'Pro plan' };
+const SUBSCRIPTION = {
+    id: 'sub_twin001', object: 'subscription', status: 'trialing', customer: 'cus_twin001', currency: 'usd', created: AT, start_date: AT,
+    current_period_start: AT, current_period_end: AT + 14 * 86400, trial_start: AT, trial_end: AT + 14 * 86400, collection_method: 'charge_automatically',
+    items: { object: 'list', data: [{ id: 'si_twin001', object: 'subscription_item', quantity: 3, price: { id: 'price_twin001', product: 'prod_twin001', unit_amount: 4900, currency: 'usd', recurring: { interval: 'month' } } }] },
+};
+const INVOICE = { id: 'in_twin001', object: 'invoice', number: 'TWIN-0001', status: 'paid', customer: 'cus_twin001', subscription: 'sub_twin001', currency: 'usd', total: 14700, amount_due: 14700, created: AT };
+const CUSTOMER_PAGE = { customer: CUSTOMER, paymentMethods: [CARD], subscriptions: [SUBSCRIPTION], invoices: [INVOICE], payments: PAYMENTS, products: new Map([[PRODUCT.id, PRODUCT]]), events: [] };
+const SUBSCRIPTION_PAGE = { subscription: SUBSCRIPTION, customer: CUSTOMER, invoices: [INVOICE], products: new Map([[PRODUCT.id, PRODUCT]]), events: [event('evt_s', 'customer.subscription.created', SUBSCRIPTION, AT)], paymentMethod: CARD };
+const BALANCE = { id: 'balance', object: 'balance', available: [{ amount: 16800, currency: 'usd' }], pending: [{ amount: 4200, currency: 'usd' }] };
+const ACCOUNT = {
+    id: 'acct_twin001', object: 'account', type: 'express', country: 'US', charges_enabled: false, payouts_enabled: false, details_submitted: false,
+    requirements: { currently_due: ['external_account', 'tos_acceptance.date'] },
+};
+const TAX_RATE = { id: 'txr_twin001', object: 'tax_rate', display_name: 'Sales Tax', percentage: 8.5, inclusive: false, active: true, jurisdiction: 'US', created: AT };
+const html = (el) => renderToStaticMarkup(el);
+const count = (markup, needle) => (markup.match(needle) ?? []).length;
+/** Build the structural checklist from the real rendered markup and run it. */
+export function stripeUiStructure() {
+    const nav = html(createElement(SideNav, { route: ['payments'], go: noop }));
+    const band = html(createElement(TestModeBand));
+    const payments = html(createElement(PaymentsTable, { payments: PAYMENTS, go: noop }));
+    const partial = html(createElement(PaymentDetailView, { p: PARTIAL, go: noop, onRefund: noop }));
+    const declined = html(createElement(PaymentDetailView, { p: DECLINED, go: noop, onRefund: noop }));
+    const customer = html(createElement(CustomerDetailView, { data: CUSTOMER_PAGE, go: noop }));
+    const subscription = html(createElement(SubscriptionDetailView, { data: SUBSCRIPTION_PAGE, go: noop, onCancel: noop }));
+    const balance = html(createElement(BalanceSummary, { row: BALANCE }));
+    const account = html(createElement(ConnectAccountPanel, { row: ACCOUNT }));
+    const taxRates = html(createElement(ListPane, { section: SECTIONS.find((s) => s.key === 'tax_rates'), rows: [TAX_RATE], onSelect: noop }));
+    const checks = [
+        {
+            key: 'navigation',
+            label: "Left navigation: Home, Balances, Transactions, Customers, Product catalog, Billing's Subscriptions and Invoices, Developers — at Stripe's /test/ paths",
+            present: ['>Home<', '>Balances<', '>Transactions<', '>Customers<', '>Product catalog<', '>Subscriptions<', '>Invoices<', '>Developers<'].every((l) => nav.includes(l))
+                && nav.includes('href="/test/payments"') && nav.includes('href="/test/customers"') && nav.includes('href="/test/subscriptions"'),
+        },
+        {
+            key: 'navActive',
+            label: 'The navigation marks the section being viewed',
+            present: /class="nav-item [^"]*active"[^>]*href="\/test\/payments"|href="\/test\/payments" class="nav-item [^"]*active"/.test(nav),
+        },
+        {
+            key: 'testModeBand',
+            label: "The orange test-mode band across the top",
+            present: band.includes('class="test-band"') && band.includes('Test mode'),
+        },
+        {
+            key: 'paymentsColumns',
+            label: "Payments table carries Stripe's columns (Amount, Payment method, Description, Customer, Date, Refunded date, Decline reason)",
+            present: ['>Amount<', '>Payment method<', '>Description<', '>Customer<', '>Date<', '>Refunded date<', '>Decline reason<'].every((c) => payments.includes(c)),
+        },
+        {
+            key: 'paymentsRowPerPayment',
+            label: 'Payments table emits one row per payment, amount with its currency',
+            present: count(payments, /class="list-row"/g) === PAYMENTS.length && payments.includes('$300.00') && payments.includes('USD'),
+        },
+        {
+            key: 'paymentsStatusPills',
+            label: 'Status pills worded as Stripe words them (Succeeded, Refunded, Partial refund, Failed)',
+            present: ['>Succeeded<', '>Refunded<', '>Partial refund<', '>Failed<'].every((l) => payments.includes(l)),
+        },
+        {
+            key: 'paymentsDeclineReason',
+            label: 'A failed payment shows its decline reason in the list',
+            present: payments.includes('Insufficient funds'),
+        },
+        {
+            key: 'paymentHeader',
+            label: "A payment's page leads with its amount, currency and status, and a Refund control while refundable",
+            present: partial.includes('$300.00') && partial.includes('Partial refund') && partial.includes('Refund</button>'),
+        },
+        {
+            key: 'paymentTimeline',
+            label: "A payment's timeline lists its events (started, succeeded, refunded)",
+            present: partial.includes('class="timeline"') && partial.includes('Payment started') && partial.includes('Payment succeeded') && partial.includes('refunded'),
+        },
+        {
+            key: 'paymentBreakdownAndRefunds',
+            label: "A payment's breakdown (amount, refunded, net) and its refunds",
+            present: partial.includes('Payment breakdown') && partial.includes('$200.00') && partial.includes('>Refunds<') && partial.includes('re_twin001'),
+        },
+        {
+            key: 'paymentMethodBlock',
+            label: "A payment's card: number's last four, expiry, type, CVC check",
+            present: partial.includes('4242') && partial.includes('12 / 2034') && partial.includes('Visa credit card') && partial.includes('Passed'),
+        },
+        {
+            key: 'paymentDecline',
+            label: 'A declined payment states its error and decline code, and offers no refund',
+            present: declined.includes('class="pay-error"') && declined.includes('Your card has insufficient funds.') && declined.includes('insufficient_funds') && !declined.includes('Refund</button>'),
+        },
+        {
+            key: 'customerPage',
+            label: "A customer's page: name, email, Details, Subscriptions, Payments, Payment methods, Invoices",
+            present: customer.includes('Ada Lovelace') && customer.includes('ada@example.com')
+                && ['>Details<', '>Subscriptions<', '>Payments<', '>Payment methods<', '>Invoices<'].every((h) => customer.includes(h))
+                && customer.includes('Pro plan') && customer.includes('TWIN-0001') && customer.includes('>Default<'),
+        },
+        {
+            key: 'subscriptionPage',
+            label: "A subscription's page: customer on product, status, period, pricing items, invoices and Cancel subscription",
+            present: subscription.includes('Ada Lovelace') && subscription.includes('Pro plan') && subscription.includes('>Trialing<')
+                && subscription.includes('Current period') && subscription.includes('>Pricing<') && subscription.includes('$147.00')
+                && subscription.includes('TWIN-0001') && subscription.includes('Cancel subscription'),
+        },
+        {
+            key: 'balanceSummaryBuckets',
+            label: 'The balance renders its incoming and available buckets, amounts formatted',
+            present: balance.includes('class="balance-summary"') && balance.includes('Incoming') && balance.includes('Available') && balance.includes('$168.00') && balance.includes('$42.00'),
+        },
+        {
+            key: 'connectAccountReadiness',
+            label: "A connected account's charges/payouts/details flags and what is currently due",
+            present: account.includes('class="connect-panel"') && count(account, /connect-flag /g) >= 3 && account.includes('Requirements currently due') && account.includes('external_account'),
+        },
+        {
+            key: 'resourceListRow',
+            label: 'A resource list emits one row per object (Tax rates: name and percentage)',
+            present: count(taxRates, /list-row/g) === 1 && taxRates.includes('Sales Tax') && taxRates.includes('8.5'),
+        },
+    ];
+    return checkUiStructure('stripe', checks);
+}

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

@@ -0,0 +1,10 @@
+/** The version the pack serves: its vendored spec's. */
+export declare const SERVED_VERSION: string;
+/** Whether a request is answered in the served version's shape. */
+export declare const servesCurrent: (pinned?: string | null) => boolean;
+/** The `expand[]` paths a request names, in its query or its body (JSON or form). */
+export declare function expandOf(request: Request): Promise<string[]>;
+/** An answer with every webhook endpoint's `secret` left out: Stripe answers it only when the endpoint is created. */
+export declare function withoutEndpointSecret(value: unknown): unknown;
+/** An answer (any JSON) rendered for the version a caller is served, with only the includable fields `expand` names. */
+export declare function render(value: unknown, pinned?: string | null, expand?: string[]): unknown;

package/dist/src/stripe-version.js

@@ -0,0 +1,285 @@
+// STRIPE'S API VERSIONS — how an answer is rendered for the version a caller is served. Stripe keeps one
+// account of an object and renders it per API version (docs.stripe.com/upgrades): a request pinning a version
+// with `Stripe-Version` gets that version's shape, and one that pins none gets the account's. The twin keeps
+// its objects in the shape its rules were written against (the 2024-06-20 one, with the request parameters
+// those rules read), and renders them here: in the spec's version (the one this pack serves, surface.version)
+// for a request that pins none or pins basil (2025-03-31) or later, and as kept for an earlier pin.
+//
+// Where the evidence stops: the changes below are the ones between the kept shape and the vendored spec that
+// the pack's journeys reach, each from Stripe's changelog for basil (docs.stripe.com/changelog/basil); a version
+// pinned between basil and the spec's is rendered in the spec's shape, not its own.
+import surface from './generated/surface.gen.json' with { type: 'json' };
+/** The version the pack serves: its vendored spec's. */
+export const SERVED_VERSION = String(surface.version);
+const BASIL = '2025-03-31';
+/** Whether a request is answered in the served version's shape. */
+export const servesCurrent = (pinned) => !pinned || pinned >= BASIL;
+// What the twin keeps on an object for its rules that Stripe never answers: request parameters (a capture
+// flag, the payment behavior a subscription was created with) and links it follows internally.
+const KEPT = {
+    account: ['livemode'],
+    // a meter event is identified by its identifier; the twin's row id is its own
+    'billing.meter_event': ['id'],
+    // a card source's creation time is the twin's, for ordering
+    card: ['created'],
+    charge: ['capture', 'capture_before'],
+    dispute: ['submit'],
+    ephemeral_key: ['associated_objects'],
+    'financial_connections.account': ['session'],
+    'identity.verification_session': ['return_url'],
+    invoice: ['days_until_due', 'pending_invoice_items_behavior'],
+    'issuing.token': ['cardholder'],
+    payment_intent: ['mandate', 'off_session'],
+    subscription: ['payment_behavior'],
+    subscription_item: ['livemode'],
+    subscription_schedule: ['from_subscription', 'renewal_interval'],
+    'tax.transaction': ['calculation'],
+    'terminal.reader': ['registration_code'],
+    topup: ['destination_balance'],
+    'treasury.outbound_payment': ['destination_payment_method_data'],
+    'treasury.transaction_entry': ['amount'],
+};
+const omit = (o, keys) => Object.fromEntries(Object.entries(o).filter(([k]) => !keys.includes(k)));
+const idOf = (v) => (typeof v === 'string' ? v : v && typeof v === 'object' && typeof v.id === 'string' ? String(v.id) : null);
+/** A price (an id or an expanded object) as basil's pricing block names it. */
+function pricing(price, amount, quantity) {
+    const id = idOf(price);
+    if (!id)
+        return null;
+    const product = price && typeof price === 'object' ? idOf(price.product) : null;
+    const unit = price && typeof price === 'object' && price.unit_amount !== undefined ? price.unit_amount : Number(amount) / (Number(quantity) || 1);
+    return { type: 'price_details', price_details: { price: id, product: product ?? '' }, unit_amount_decimal: String(unit ?? 0) };
+}
+// basil (2025-03-31): what moved, per object
+const BASIL_CHANGES = {
+    // an invoice's subscription is its parent; its payments are the invoice's payments list (docs.stripe.com/changelog/basil/2025-03-31/add-support-for-multiple-partial-payments-on-invoices)
+    invoice: (o) => {
+        const subscription = idOf(o.subscription);
+        const parent = o.parent !== undefined ? o.parent : subscription ? { type: 'subscription_details', quote_details: null, subscription_details: { metadata: {}, subscription } } : null;
+        // "confirmation_secret … Currently, this contains the client_secret of the PaymentIntent that Stripe creates during
+        // invoice finalization" (docs.stripe.com/api/invoices/object; includable, answered only when expanded: INCLUDABLE);
+        // the intent's client_secret is the one stripe-twin.ts mintClientSecret gives it
+        const intent = typeof o.payment_intent === 'string' && o.payment_intent ? o.payment_intent : null;
+        const confirmation_secret = intent ? { type: 'payment_intent', client_secret: `${intent}_secret_twin` } : null;
+        return { ...omit(o, ['payment_intent', 'charge', 'paid', 'paid_out_of_band', 'subscription']), parent, confirmation_secret };
+    },
+    charge: (o) => omit(o, ['invoice', 'source']),
+    payment_intent: (o) => omit(o, ['invoice']),
+    // a subscription's billing period is its items' (docs.stripe.com/changelog/basil/2025-03-31/deprecate-subscription-current-period-start-and-end)
+    subscription: (o) => {
+        const period = { current_period_start: o.current_period_start, current_period_end: o.current_period_end };
+        const items = o.items && typeof o.items === 'object' ? o.items : undefined;
+        const data = Array.isArray(items?.data) ? items.data.map((it) => ({ ...it, current_period_start: it.current_period_start ?? period.current_period_start, current_period_end: it.current_period_end ?? period.current_period_end })) : undefined;
+        return { ...omit(o, ['current_period_start', 'current_period_end']), ...(items && data ? { items: { ...items, data } } : {}) };
+    },
+    subscription_item: (o) => ({ ...omit(o, ['plan']), discounts: o.discounts ?? [] }),
+    invoiceitem: (o) => ({ ...omit(o, ['price']), pricing: o.pricing ?? pricing(o.price, o.amount, o.quantity) }),
+    // a line names what generated it (its parent) and its price and taxes in basil's blocks
+    line_item: (o) => {
+        const proration = o.proration === true;
+        // a line an invoice item made names it; a subscription's line (invoice_item null) is its item's: "Details about the
+        // subscription item that generated this line item" (docs.stripe.com/api/invoice-line-item/object, parent)
+        const fromItem = o.type === 'invoiceitem' || (o.invoice_item !== undefined && o.invoice_item !== null && o.type !== 'subscription');
+        const parent = o.parent !== undefined ? o.parent : fromItem
+            ? { type: 'invoice_item_details', invoice_item_details: { invoice_item: idOf(o.invoice_item) ?? String(o.id).replace(/^il_/, ''), proration, proration_details: null, subscription: idOf(o.subscription) }, subscription_item_details: null }
+            : { type: 'subscription_item_details', subscription_item_details: { subscription_item: idOf(o.subscription_item) ?? '', proration, proration_details: null, subscription: idOf(o.subscription), invoice_item: null }, invoice_item_details: null };
+        const taxes = Array.isArray(o.tax_amounts) ? o.tax_amounts.map((t) => ({ amount: t.amount, tax_behavior: 'exclusive', taxability_reason: t.taxability_reason ?? 'standard_rated', taxable_amount: t.taxable_amount ?? null, type: 'tax_rate_details', tax_rate_details: { tax_rate: idOf(t.tax_rate) } })) : [];
+        return {
+            ...omit(o, ['price', 'invoice_item', 'proration', 'tax_amounts', 'tax_rates', 'type', 'subscription_item']),
+            parent, pricing: o.pricing ?? pricing(o.price, o.amount, o.quantity), taxes,
+            discountable: o.discountable ?? !proration, discounts: o.discounts ?? [], livemode: o.livemode ?? false, metadata: o.metadata ?? {},
+            period: o.period ?? { start: 0, end: 0 }, subtotal: o.subtotal ?? o.amount,
+        };
+    },
+    // a promotion code promotes a coupon (docs.stripe.com/api/promotion_codes/object)
+    promotion_code: (o) => ({ ...omit(o, ['coupon']), promotion: o.promotion ?? { type: 'coupon', coupon: o.coupon ?? null } }),
+};
+// Stripe answers every field of an object, a nullable one it has no value for as null (the Product object's page,
+// docs.stripe.com/api/products/object, lists `package_dimensions` as "(object, nullable)" and its example answers
+// `"package_dimensions": null`): a nullable field of the served spec the twin never set is rendered null. The spec's
+// top-level fields are read from the surface; a sub-object's nullable fields are listed below, each from its object's
+// page, where a published example met one the twin left out.
+const NULLABLE = new Map(surface.resources.map((r) => [r.schema, r.fields.filter((f) => f.nullable).map((f) => f.name)]));
+const NESTED_NULLABLE = {
+    // docs.stripe.com/api/checkout/sessions/object?query=customer_details: business_name, individual_name "(string, nullable)"
+    'checkout.session': { customer_details: ['business_name', 'individual_name'] },
+    // docs.stripe.com/api/subscriptions/object: "billing_mode.flexible (object, nullable)", "automatic_tax.disabled_reason
+    // (enum, nullable)", invoice_settings.account_tax_ids, .custom_fields, .description, .footer each nullable
+    // (and cancellation_details.feedback_option, nullable in the served spec: "Customized feedback options that provide
+    // deeper insight into why the subscription was canceled")
+    subscription: { automatic_tax: ['disabled_reason'], billing_mode: ['flexible'], invoice_settings: ['account_tax_ids', 'custom_fields', 'description', 'footer'], cancellation_details: ['comment', 'feedback', 'feedback_option', 'reason'] },
+    // docs.stripe.com/api/payment_methods/object: billing_details.tax_id, card.fingerprint, card.generated_from,
+    // card.regulated_status each "(…, nullable)"
+    // docs.stripe.com/api/invoices/object: automatic_tax.disabled_reason "(enum, nullable)", automatic_tax.provider
+    // "(string, nullable)"
+    invoice: { automatic_tax: ['disabled_reason', 'provider'] },
+    // docs.stripe.com/api/customers/object: invoice_settings.custom_fields, .default_payment_method, .footer,
+    // .rendering_options each nullable
+    customer: { invoice_settings: ['custom_fields', 'default_payment_method', 'footer', 'rendering_options'] },
+    // docs.stripe.com/api/accounts/object: a fresh account's business_profile answers each of these null
+    account: { business_profile: ['annual_revenue', 'estimated_worker_count', 'mcc', 'minority_owned_business_designation', 'name', 'product_description', 'specified_commercial_transactions_act_url', 'support_address', 'support_email', 'support_phone', 'support_url', 'url'] },
+    // docs.stripe.com/api/charges/object: billing_details.tax_id and each of these payment_method_details.card fields
+    // "(…, nullable)"; extended_authorization, incremental_authorization, multicapture and overcapture are not nullable
+    // in the served spec, so an unmodelled one is left out rather than answered null
+    charge: {
+        billing_details: ['tax_id'],
+        'payment_method_details.card': ['amount_authorized', 'authorization_code', 'electronic_commerce_indicator', 'network_token', 'network_transaction_id', 'regulated_status', 'transaction_link_id'],
+    },
+    payment_method: { billing_details: ['tax_id'], card: ['fingerprint', 'generated_from', 'regulated_status'] },
+    // the served spec's person_relationship: legal_guardian and authorizer, each "(boolean, nullable)"
+    person: { relationship: ['legal_guardian', 'authorizer'] },
+    // the served spec's source_owner: each field "(…, nullable)"; the sources create page's example answers them null
+    source: { owner: ['address', 'email', 'name', 'phone', 'verified_address', 'verified_email', 'verified_name', 'verified_phone'] },
+    // the served spec's address_api_resource_terminal: each line "(string, nullable)"; the location fixture answers line2 null
+    'terminal.location': { address: ['city', 'country', 'line1', 'line2', 'postal_code', 'state'] },
+    // the served spec's issuing_cardholder_individual (dob, verification, card_issuing), its address and its authorization
+    // controls (allowed_card_presences, blocked_card_presences, spending_limits_currency): each "(…, nullable)"
+    'issuing.cardholder': { 'billing.address': ['city', 'country', 'line1', 'line2', 'postal_code', 'state'], individual: ['dob', 'verification', 'card_issuing'], spending_controls: ['allowed_card_presences', 'blocked_card_presences', 'spending_limits_currency'] },
+    // and a card's authorization controls (the served spec's issuing_card_authorization_controls), likewise nullable
+    'issuing.card': { spending_controls: ['allowed_card_presences', 'blocked_card_presences', 'spending_limits_currency'] },
+    // the served spec's issuing_dispute_fraudulent_evidence: additional_documentation and explanation, each nullable
+    'issuing.dispute': { 'evidence.fraudulent': ['additional_documentation', 'explanation'] },
+    // the served spec's issuing_personalization_design_carrier_text: its four texts, each nullable
+    'issuing.personalization_design': { carrier_text: ['footer_body', 'footer_title', 'header_body', 'header_title'] },
+    // the served spec's treasury_shared_resource_billing_details.address: each line "(string, nullable)"
+    'treasury.received_credit': { 'initiating_payment_method_details.billing_details.address': ['city', 'country', 'line1', 'line2', 'postal_code', 'state'], linked_flows: ['credit_reversal', 'issuing_authorization', 'issuing_transaction', 'source_flow', 'source_flow_details', 'source_flow_type'] },
+    // (and its linked flows: every one nullable in the served spec's treasury_received_debits_resource_linked_flows, and
+    // likewise the credit's)
+    'treasury.received_debit': { 'initiating_payment_method_details.billing_details.address': ['city', 'country', 'line1', 'line2', 'postal_code', 'state'], linked_flows: ['debit_reversal', 'inbound_transfer', 'issuing_authorization', 'issuing_transaction', 'payout', 'topup'] },
+    'treasury.inbound_transfer': { 'origin_payment_method_details.billing_details.address': ['city', 'country', 'line1', 'line2', 'postal_code', 'state'] },
+};
+// A field the vendor fills with its default when the request set none, by object, each from its object's page.
+const CARD_DISPLAY = { amex: 'american_express', diners: 'diners_club', eftpos_au: 'eftpos_australia', unionpay: 'union_pay' };
+const DEFAULTS = {
+    // docs.stripe.com/api/payment_methods/object: allow_redisplay "defaults to “unspecified”"; card.display_brand is "The
+    // brand to use when displaying the card … Can be `american_express`, …, `visa`", the brand's display name
+    payment_method: (o) => {
+        const card = o.card && typeof o.card === 'object' ? o.card : undefined;
+        const brand = typeof card?.brand === 'string' ? card.brand : undefined;
+        return {
+            ...(o.allow_redisplay === undefined ? { allow_redisplay: 'unspecified' } : {}),
+            ...(card && brand && card.display_brand === undefined ? { card: { ...card, display_brand: CARD_DISPLAY[brand] ?? (brand === 'unknown' ? 'other' : brand) } } : {}),
+        };
+    },
+    // a line names "The ID of the invoice that contains this line item" (docs.stripe.com/api/invoice-line-item/object)
+    invoice: (o) => {
+        const lines = o.lines && typeof o.lines === 'object' ? o.lines : undefined;
+        if (!Array.isArray(lines?.data) || typeof o.id !== 'string')
+            return {};
+        return { lines: { ...lines, data: lines.data.map((l) => (l && typeof l === 'object' && (l.invoice === undefined || l.invoice === null) ? { ...l, invoice: o.id } : l)) } };
+    },
+    // docs.stripe.com/api/invoiceitems/object: net_amount, "The amount after discounts, but before credits and taxes. This
+    // field is `null` for `discountable=true` items" (the twin puts no discount on an item itself)
+    invoiceitem: (o) => (o.net_amount === undefined ? { net_amount: o.discountable === false ? (typeof o.amount === 'number' ? o.amount : null) : null } : {}),
+    // docs.stripe.com/api/payment_intents/object: confirmation_method `automatic` "(Default)"; amount_details as its
+    // example answers it for a card payment, `{"tip": {}}`
+    payment_intent: (o) => ({
+        ...(o.confirmation_method === undefined ? { confirmation_method: 'automatic' } : {}),
+        ...(o.amount_details === undefined ? { amount_details: { tip: {} } } : {}),
+    }),
+};
+const fill = (o, keys) => (keys.some((k) => !(k in o)) ? { ...o, ...Object.fromEntries(keys.filter((k) => !(k in o)).map((k) => [k, null])) } : o);
+// every object whose served spec gives it a `metadata` it never answers null answers `{}` when none was set: "Set of
+// key-value pairs that you can attach to an object" (docs.stripe.com/api/metadata), `metadata (map)` on each object's
+// page, and its example `"metadata": {}` (the PaymentIntent object's, docs.stripe.com/api/payment_intents/object)
+const METADATA = new Set(surface.resources.filter((r) => r.fields.some((f) => f.name === 'metadata' && !f.nullable)).map((r) => r.schema));
+const withNulls = (o, kind) => {
+    let out = fill(DEFAULTS[kind] ? { ...o, ...DEFAULTS[kind](o) } : o, NULLABLE.get(kind) ?? []);
+    if (METADATA.has(kind) && (out.metadata === undefined || out.metadata === null))
+        out = { ...out, metadata: {} };
+    // a dotted path reaches a sub-object's own sub-object (a charge's payment_method_details.card)
+    const at = (o, path, keys) => {
+        const [head, ...rest] = path;
+        const sub = o[head];
+        if (!sub || typeof sub !== 'object' || Array.isArray(sub))
+            return o;
+        return { ...o, [head]: rest.length ? at(sub, rest, keys) : fill(sub, keys) };
+    };
+    for (const [path, keys] of Object.entries(NESTED_NULLABLE[kind] ?? {}))
+        out = at(out, path.split('.'), keys);
+    return out;
+};
+// A field Stripe includes only when the request expands it: the Checkout Session object's page
+// (docs.stripe.com/api/checkout/sessions/object) marks `line_items` "includable (not returned by default; request it
+// with the `expand` request parameter)". The twin keeps it on the object for its rules; the answer carries it only
+// where the request's `expand[]` names it (`line_items`, or `data.line_items` on a list).
+const INCLUDABLE = {
+    'checkout.session': ['line_items'],
+    // docs.stripe.com/api/charges/object: `refunds` "(object, nullable, includable (not returned by default; …))"
+    charge: ['refunds'],
+    // docs.stripe.com/api/payment-link/object: `line_items` "object Includable", and its example answers none
+    payment_link: ['line_items'],
+    // docs.stripe.com/api/quotes/object: `line_items` "object Includable", and its example answers none
+    quote: ['line_items'],
+    // docs.stripe.com/api/secret_management: `payload` "nullable string Includable": a secret's value is answered only
+    // when the request expands it
+    'apps.secret': ['payload'],
+    // docs.stripe.com/api/tax/calculations/object and /tax/transactions/object: `line_items` "nullable object Includable"
+    'tax.calculation': ['line_items'],
+    'tax.transaction': ['line_items'],
+    // docs.stripe.com/api/invoices/object: `confirmation_secret` "(object, nullable, includable (not returned by default;
+    // request it with the `expand` request parameter))"
+    invoice: ['confirmation_secret'],
+};
+/** The `expand[]` paths a request names, in its query or its body (JSON or form). */
+export async function expandOf(request) {
+    const url = new URL(request.url);
+    const out = [...url.searchParams.entries()].filter(([k]) => /^expand(\[\d*\])?$/.test(k)).map(([, v]) => v);
+    if (request.method === 'GET' || request.method === 'HEAD')
+        return out;
+    const text = await request.text().catch(() => '');
+    if (!text)
+        return out;
+    if ((request.headers.get('content-type') ?? '').includes('json') || text.trim().startsWith('{')) {
+        try {
+            const e = JSON.parse(text).expand;
+            if (Array.isArray(e))
+                out.push(...e.map(String));
+        }
+        catch { /* not JSON */ }
+        return out;
+    }
+    for (const [k, v] of new URLSearchParams(text))
+        if (/^expand(\[\d*\])?$/.test(k))
+            out.push(v);
+    return out;
+}
+/** An answer with every webhook endpoint's `secret` left out: Stripe answers it only when the endpoint is created. */
+export function withoutEndpointSecret(value) {
+    if (Array.isArray(value))
+        return value.map(withoutEndpointSecret);
+    if (!value || typeof value !== 'object')
+        return value;
+    const o = value;
+    const out = Object.fromEntries(Object.entries(o).filter(([k]) => !(k === 'secret' && o.object === 'webhook_endpoint')).map(([k, v]) => [k, withoutEndpointSecret(v)]));
+    return out;
+}
+/** An answer (any JSON) rendered for the version a caller is served, with only the includable fields `expand` names. */
+export function render(value, pinned, expand = []) {
+    if (!servesCurrent(pinned))
+        return value;
+    const expands = (at) => expand.some((e) => e === at || e.startsWith(`${at}.`));
+    const walk = (v, at = '') => {
+        if (Array.isArray(v))
+            return v.map((x) => walk(x, at));
+        if (!v || typeof v !== 'object')
+            return v;
+        const kindOf = typeof v.object === 'string' ? String(v.object) : undefined;
+        // `expand` is a request parameter, never a field of any object (the served spec gives none one); a handler that
+        // keeps its parameters keeps it too, and the answer leaves it out
+        const hidden = [...((kindOf ? INCLUDABLE[kindOf]?.filter((k) => !expands(at ? `${at}.${k}` : k)) : undefined) ?? []), ...(kindOf ? ['expand'] : [])];
+        const o = Object.fromEntries(Object.entries(v).filter(([k]) => !hidden.includes(k)).map(([k, x]) => [k, walk(x, at ? `${at}.${k}` : k)]));
+        const kind = typeof o.object === 'string' ? o.object : undefined;
+        // a deleted object answers only that it is gone
+        if (!kind || o.deleted === true)
+            return o;
+        // metadata holds strings ("key-value pairs", each value up to 500 characters, docs.stripe.com/metadata); the form
+        // reader coerces a numeric-looking value to a number, which the answer gives back as the string it was sent as
+        if (o.metadata && typeof o.metadata === 'object' && !Array.isArray(o.metadata))
+            o.metadata = Object.fromEntries(Object.entries(o.metadata).map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
+        const kept = KEPT[kind] ? omit(o, KEPT[kind]) : o;
+        // an includable field a version's change adds (an invoice's confirmation_secret) is hidden as its stored ones are
+        return omit(withNulls(BASIL_CHANGES[kind] ? BASIL_CHANGES[kind](kept) : kept, kind), hidden);
+    };
+    return walk(value);
+}