@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/{stripe-twin.js → engine/stripe.js}

@@ -1,23 +1,11 @@
-// Stripe twin REQUEST HANDLER — the canonical Stripe API surface for the twin and
-// the QA stack's authoritative Stripe (it replaced the old hand-made in-process
-// mock). Contract: handleStripeTwinRequest({method, path, body, mode}) -> {status,
-// body}. The whole point: this is backed by the event/action-log kernel and its
-// response SHAPES are conformant to real Stripe (see stripe-conformance), instead
-// of being invented — so the SDK/API call shapes the app relies on actually match
-// Stripe. HTTP wrapper: stripe-server.ts → createStripeTwinServer.
-//
-// State lives in the action log (R18): writes are local actions, reads are the
-// projection. No real Stripe is ever called.
-import { applyTwinWrite } from '@volter/world-core';
-import { projectResources } from '@volter/world-core';
-import { createStripeTwinFetch } from "./stripe-server.js";
-import { emitStripeEvent, eventTypeFor } from "./stripe-events.js";
-import { SERVED_VERSION } from "./stripe-version.js";
-import { planOf } from "./semantics/plans.js";
-import { platformAccountDefault } from "./semantics/connect.js";
-import { OAUTH_CONNECTIONS } from "./stripe-shared.js";
-const SERVICE = 'stripe';
-// The Stripe API version a request that pins none is served in: the vendored spec's (stripe-version.ts renders
+import { digest } from '@volter/world-core';
+import { ownFields } from '@volter/world-core';
+import { SERVED_VERSION } from "./version.js";
+/** Stripe's error body: an invalid_request_error with the message, and the code when there is one. */
+export function err(message, status = 404, code) {
+    return { status, body: { error: { type: 'invalid_request_error', message, ...(code ? { code } : {}) } } };
+}
+// The Stripe API version a request that pins none is served in: the vendored spec's (./version.ts renders
 // every answer in it). A request may override it via the `Stripe-Version` header (apiVersion);
 // the value is echoed onto every event the request produces, exactly like real Stripe,
 // whose stored Event.api_version reflects the version in force when the event was created.
@@ -28,61 +16,6 @@ const API_VERSION_RE = /^\d{4}-\d{2}-\d{2}(\.[a-z_]+)?$/;
 export function isValidApiVersion(v) {
     return API_VERSION_RE.test(v);
 }
-// resource type → id prefix (Stripe's conventions).
-const PREFIX = {
-    charge: 'ch', customer: 'cus', payment_intent: 'pi', setup_intent: 'seti', payment_method: 'pm',
-    subscription: 'sub', price: 'price', product: 'prod', invoice: 'in', invoiceitem: 'ii',
-    refund: 're', verification_session: 'vs', ephemeral_key: 'ephkey', file_link: 'link',
-    dispute: 'dp', payout: 'po', balance_transaction: 'txn', event: 'evt',
-    checkout_session: 'cs', billing_portal_session: 'bps', billing_portal_configuration: 'bpc',
-    account: 'acct', transfer: 'tr',
-    tax_rate: 'txr', tax_calculation: 'taxcalc', tax_registration: 'taxreg',
-    credit_note: 'cn', tax_id: 'txi', customer_balance_transaction: 'cbtxn',
-    coupon: 'coupon', promotion_code: 'promo', payment_link: 'plink', quote: 'qt',
-    webhook_endpoint: 'we',
-    subscription_schedule: 'sub_sched', billing_meter: 'mtr', billing_meter_event: 'mtr_evt',
-    usage_record: 'mbur', test_clock: 'clock',
-    token: 'tok', mandate: 'mandate', application_fee: 'fee', fee_refund: 'fr',
-    transfer_reversal: 'trr', account_link: 'acctlink', person: 'person',
-    external_account: 'ba', file: 'file',
-    subscription_item: 'si', tax_transaction: 'tax', radar_review: 'prv',
-    radar_value_list: 'rsl', radar_value_list_item: 'rsli', radar_rule: 'rule',
-    // Issuing family (vendor-faithful Stripe id prefixes).
-    issuing_cardholder: 'ich', issuing_card: 'ic', issuing_authorization: 'iauth',
-    issuing_transaction: 'ipi', issuing_dispute: 'idp',
-    // Terminal family.
-    terminal_location: 'tml', terminal_reader: 'tmr', terminal_configuration: 'tmc',
-    // Top-ups, identity reports, reporting runs.
-    topup: 'tu', verification_report: 'vr', report_run: 'frr',
-    // Customer cash balance ledger + legacy sources.
-    cash_balance_transaction: 'ccsbtxn', source: 'src',
-    // Billing: prepaid credit grants + usage alerts.
-    credit_grant: 'credgr', billing_alert: 'alert',
-    // Entitlements: account-level features + per-customer active entitlements.
-    entitlements_feature: 'feat', active_entitlement: 'ent',
-    // Connect: embedded account sessions + apps secret store.
-    account_session: 'accts', apps_secret: 'apmc',
-    // Issuing: network tokens + card personalization designs.
-    issuing_token: 'iss_tok', personalization_design: 'pd',
-    // Treasury: financial accounts + money-movement flows + ledger.
-    financial_account: 'fa',
-    outbound_payment: 'obp', outbound_transfer: 'obt', inbound_transfer: 'ibt',
-    received_credit: 'rc', received_debit: 'rd',
-    treasury_transaction: 'trxn', treasury_transaction_entry: 'trxne',
-    // Climate (carbon removal): orders. (products/suppliers are a fixed read-only catalog.)
-    climate_order: 'climorder',
-    // Financial Connections: sessions + linked accounts + account transactions.
-    fc_session: 'fcsess', fc_account: 'fca', fc_transaction: 'fctxn',
-    // Forwarding (PAN forwarding) requests + Crypto onramp sessions.
-    forwarding_request: 'fwdr', onramp_session: 'cos',
-    // Entitlements: a product↔feature grant.
-    product_feature: 'prodft',
-    // Tax settings singleton.
-    tax_settings: 'taxset',
-};
-function err(message, status = 404, code) {
-    return { status, body: { error: { type: status === 404 ? 'invalid_request_error' : 'invalid_request_error', message, ...(code ? { code } : {}) } } };
-}
 // Fidelity: real Stripe rejects a charge/payment_intent missing or with a non-positive
 // amount, or missing currency, before any state change.
 export function validateMoney(params) {
@@ -202,8 +135,6 @@ export function threeDsNextAction() {
 // a `descriptor_code` (the test value `SM11AA`). We model that exact pair so the verify
 // can FAIL with the wrong amounts. The well-known token that triggers this flow:
 const MICRODEPOSIT_TOKENS = new Set(['pm_usBankAccount_requiresVerification', 'pm_us_bank_account']);
-const MICRODEPOSIT_AMOUNTS = [32, 45];
-const MICRODEPOSIT_DESCRIPTOR = 'SM11AA';
 export function requiresMicrodeposits(...paramSets) {
     for (const params of paramSets) {
         const ref = resolveCardRef(params);
@@ -221,31 +152,6 @@ export function microdepositsNextAction() {
         },
     };
 }
-/** The two deposits' amounts as sent: the test values (docs.stripe.com/payments/ach-direct-debit/accept-a-payment). */
-function amountsMatch(params) {
-    const got = params.amounts.map((a) => Math.trunc(Number(a) || 0));
-    return got.length === 2 && got[0] === MICRODEPOSIT_AMOUNTS[0] && got[1] === MICRODEPOSIT_AMOUNTS[1];
-}
-/** The deposit's descriptor code as sent: the test value. */
-function descriptorMatches(params) {
-    return String(params.descriptor_code) === MICRODEPOSIT_DESCRIPTOR;
-}
-/** Stripe's refusal of deposits that do not match what was sent. */
-function depositMismatch(byAmounts) {
-    return byAmounts
-        ? err('The amounts provided do not match the amounts that were sent to the bank account.', 400, 'payment_intent_microdeposit_verification_amounts_mismatch')
-        : err('The descriptor code provided does not match the one that was sent to the bank account.', 400, 'payment_intent_microdeposit_verification_descriptor_code_mismatch');
-}
-// Validate the submitted micro-deposit verification params against the modeled test values.
-// Returns a vendor 400 on missing/both/wrong inputs, or null when the verification matches.
-export function verifyMicrodeposits(params, _existing) {
-    const hasAmounts = Array.isArray(params.amounts);
-    const hasDescriptor = typeof params.descriptor_code === 'string' && params.descriptor_code !== '';
-    if (hasAmounts === hasDescriptor)
-        return err('You must pass exactly one of `amounts` and `descriptor_code`.', 400, 'parameter_missing');
-    const matches = hasAmounts ? amountsMatch(params) : descriptorMatches(params);
-    return matches ? null : depositMismatch(hasAmounts);
-}
 // Build the real Stripe card-error envelope (HTTP 402). `param` is 'card' for card
 // errors; charge/payment_intent ids are attached when known so SDK error objects carry
 // them (Stripe does this for confirm/charge failures).
@@ -270,19 +176,6 @@ export function cardError(outcome, attach = {}) {
 export function nowUnix(occurredAt) {
     return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
 }
-function rows(type, root) {
-    return projectResources(SERVICE, root).filter((r) => r.type === type);
-}
-function nextId(type, root) {
-    const prefix = PREFIX[type] ?? type;
-    let max = 0;
-    for (const r of rows(type, root)) {
-        const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(r.id);
-        if (m)
-            max = Math.max(max, Number(m[1]));
-    }
-    return `${prefix}_twin_${max + 1}`;
-}
 // Real Stripe embeds the resource's OWN id inside its client_secret (format
 // `<id>_secret_<random>`) — Stripe.js's confirmPayment/confirmSetup parse the id back
 // out of the client_secret (splitting on `_secret`) to build the same-origin confirm
@@ -290,25 +183,14 @@ function nextId(type, root) {
 // A secret that doesn't carry the real id breaks that round trip: a browser Stripe.js
 // call would try to confirm a resource whose id it invented from the string
 // (`'pi_twin_secret'` → `'pi_twin'`, which was never actually created). Every PI/SI a
-// caller might confirm CLIENT-SIDE (real Stripe.js — see the QA proxy's browserRouting
-// in packages/twin/stripe/src/index.ts) must mint a secret this way.
-export function mintClientSecret(id) {
-    return `${id}_secret_twin`;
-}
-// Stripe resource view: inject `object` + `id`, drop kernel meta.
-//
-// The kernel reserves the field name `type` as its resource-type discriminator, so a
-// stored vendor field literally named `type` is dropped on projection (see actions.ts
-// META). Several Stripe objects (payout.type, balance_transaction.type, event.type,
-// dispute uses `reason` not `type`) DO have a vendor `type`, so the create path stashes
-// it under the reserved key `_stripe_type` (a `_`-prefixed twin-internal field that the
-// conformance gate exempts) and we restore it to `type` here. This keeps the vendor
-// field faithful without touching the kernel discriminator. (price.type stays a declared
-// deviation — its create path predates this and one_time/recurring is derivable.)
-// A few Stripe objects have a DOTTED `object` value that differs from the twin's
-// (identifier-safe) resource type — e.g. type 'checkout_session' emits object
-// 'checkout.session'. Map them on emit so the `object` field is vendor-faithful.
-// (stripe-conformance.ts emitted() mirrors this map.)
+// caller might confirm CLIENT-SIDE (real Stripe.js) must mint a secret this way.
+/** An intent's client secret: its id, `_secret_`, and a secret the World holds for it (ctx.secret, passed in), so no one
+ *  derives it from the intent's id; Stripe.js confirms an intent with it and the publishable key. */
+export function mintClientSecret(id, secret) {
+    return `${id}_secret_${secret.replace(/[^A-Za-z0-9]/g, '').slice(0, 24)}`;
+}
+// A few Stripe objects have a DOTTED `object` value that differs from the twin's (identifier-safe) resource type: type
+// 'checkout_session' is object 'checkout.session'.
 export const OBJECT_NAME = {
     checkout_session: 'checkout.session',
     billing_portal_session: 'billing_portal.session',
@@ -369,18 +251,11 @@ export const OBJECT_NAME = {
     // Forwarding + Crypto onramp.
     forwarding_request: 'forwarding.request', onramp_session: 'crypto.onramp_session',
 };
-// Exported for the pack's own modules that must render the SAME vendor view of a stored
-// resource (stripe-emit.ts synthesizes `data.object` for emitted events from it) — one
-// projection, no drift. Not a public API for consumers.
+/** A stored row as Stripe answers it: its `object`, its own fields (the vendor's `type` among them, which the tree's
+ *  shadows: world-core ownFields) without the twin's `_` bookkeeping, and its id. */
 export function view(type, r) {
-    // `_subscription_data` is twin-internal (a Checkout Session's create-only
-    // subscription_data, held for the completion transition to copy onto the created
-    // subscription) — real Stripe never returns it on the Session, so strip it here.
-    const { type: _t, updatedAt: _u, _stripe_type, _subscription_data, ...rest } = r;
-    const out = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
-    if (_stripe_type !== undefined)
-        out.type = _stripe_type;
-    return out;
+    const own = Object.fromEntries(Object.entries(ownFields(r)).filter(([k]) => !k.startsWith('_') && k !== 'updatedAt'));
+    return { object: OBJECT_NAME[type] ?? type, ...own, id: r.id };
 }
 // Real Stripe list pagination. Honors limit (default 10, max 100, min 1),
 // starting_after (cursor: exclude up to & including that id), ending_before
@@ -414,90 +289,6 @@ export function paginate(items, params) {
     const page = items.slice(from, from + limit);
     return { page, hasMore: from + limit < items.length };
 }
-async function writeResource(type, id, fields, op, root, occurredAt, apiVersion) {
-    const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
-    const out = view(type, resource);
-    await afterStripeWrite(type, op, out, root, occurredAt, apiVersion);
-    return out;
-}
-/** 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 async function afterStripeWrite(type, op, out, root, occurredAt, apiVersion, stripeAccount) {
-    // R17: fire the Stripe event/webhook for this state change (no-op if none registered). An event is a connected
-    // account's when its resource lives in one (a request made as it, the Stripe-Account header) or is a connected
-    // account itself (its account.updated): docs.stripe.com/connect/webhooks, "Connected accounts" scope.
-    // A write with no header is still a connected account's when the row it wrote is kept on that account's books (a
-    // payout or ledger entry's `_account`: an automatic payout time makes for it, semantics/balance.ts).
-    const account = stripeAccount ?? (type === 'account' && typeof out.id === 'string' && out.id !== PLATFORM_ACCOUNT_ID ? out.id : undefined) ?? ownerOf(type, out.id, root);
-    // a plan is stored as the recurring price it is; its own events carry the plan object (semantics/plans.ts)
-    const object = type === 'price' && op.startsWith('plan.') ? planOf(out) : out;
-    // events.full_types: the Stripe `event` envelope for this state change is also stored, so it appears in GET
-    // /v1/events (independent of webhook registration), exactly like real Stripe's stored Events API. Skip when the op
-    // has no mapped event type, and never for event/_idempotency writes themselves (no recursion / no meta-events). The
-    // event's id is minted once and is the delivered webhook's id and the stored event's alike: one event, one id, which
-    // a consumer deduplicates by and retrieves by.
-    const eventType = type !== 'event' && type !== IDEMPOTENCY_TYPE ? eventTypeFor(op) : null;
-    const id = eventType ? nextStripeEventId(root) : undefined;
-    // stored before it is delivered: a consumer that looks its webhook's event up finds it
-    if (eventType)
-        await persistStripeEvent(eventType, object, root, occurredAt, apiVersion, account, id);
-    // a connected account whose OAuth connection was revoked "can't be accessed by your platform" (docs.stripe.com/connect/
-    // oauth-reference): its events (a payout time makes, a renewal) are its own and no longer reach the platform's Connect
-    // endpoints, except the account.application.deauthorized that says so (screens/connect-oauth.tsx)
-    if (account && eventType !== 'account.application.deauthorized' && rows(OAUTH_CONNECTIONS, root).some((c) => c.id === account && c.revoked === true))
-        return;
-    await emitStripeEvent(op, object, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z', endpoints: webhookTargets(root), ...(account ? { account } : {}), ...(id ? { id } : {}) });
-}
-/** Event numbers taken in this process, per root, before their events are stored: two writes whose events overlap
- *  (a webhook handler calling back in, concurrent requests) never take the same number. */
-const takenEventNumbers = new Map();
-/** 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 function nextStripeEventId(root) {
-    const key = root ?? '';
-    const n = Math.max(rows('event', root).length, takenEventNumbers.get(key) ?? 0) + 1;
-    takenEventNumbers.set(key, n);
-    return `evt_twin_${n}`;
-}
-/** The connected account whose books a stored row is kept on (its `_account`), if any. */
-function ownerOf(type, id, root) {
-    if (typeof id !== 'string')
-        return undefined;
-    const owner = rows(type, root).find((r) => r.id === id)?._account;
-    return typeof owner === 'string' ? owner : undefined;
-}
-// Persist a Stripe `event` resource (object 'event') for a state change into the action
-// log so the Events API (GET /v1/events) lists/retrieves it. Deterministic id derived
-// from the per-root event count; data.object carries the resource snapshot. Written via
-// applyTwinWrite directly (NOT writeResource) to avoid re-emitting an event for the event.
-export async function persistStripeEvent(eventType, resource, root, occurredAt, apiVersion, account, id) {
-    const eventId = id ?? nextStripeEventId(root);
-    const fields = {
-        object: 'event', _stripe_type: eventType, created: nowUnix(occurredAt), livemode: false,
-        pending_webhooks: 0, api_version: apiVersion && isValidApiVersion(apiVersion) ? apiVersion : TWIN_API_VERSION,
-        request: { id: null, idempotency_key: null },
-        data: { object: resource },
-        // a connected account's event names it, and is listed to requests made as it (semantics/webhook-endpoints.ts)
-        ...(account ? { account } : {}),
-    };
-    await applyTwinWrite(SERVICE, { operation: 'event.record', subjectType: 'event', subjectId: eventId, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'system' } }, root);
-}
-function getOne(type, id, root) {
-    const r = rows(type, root).find((x) => x.id === id);
-    return r ? view(type, r) : undefined;
-}
-// Stripe list order: newest first by `created` (or `date` for invoiceitem), ties
-// broken by id descending so the order is stable for cursor pagination.
-/** The World's live webhook endpoints, from its tree: delivery survives a restart and belongs to
- *  this World alone. A disabled or deleted endpoint receives nothing, like the vendor. */
-function webhookTargets(root) {
-    // `connect` is a create parameter the endpoint object does not answer, so it is read off the stored row
-    return rows('webhook_endpoint', root)
-        .map((r) => ({ w: view('webhook_endpoint', r), connect: asBool(r.connect) }))
-        .filter(({ w }) => !w.deleted && w.status !== 'disabled' && typeof w.url === 'string')
-        .map(({ w, connect }) => ({ url: String(w.url), ...(typeof w.secret === 'string' ? { secret: w.secret } : {}), ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}), connect }));
-}
 // Stripe's `active=true|false` filters arrive as strings/booleans; normalize.
 export function asBool(v) {
     return v === true || v === 'true' || v === 1 || v === '1';
@@ -511,7 +302,7 @@ function parseSearchQuery(query) {
     const disjunction = / OR /i.test(trimmed) && !/ AND /i.test(trimmed);
     const parts = trimmed.split(disjunction ? / OR /i : / AND /i);
     const clauses = [];
-    const re = /^\s*([A-Za-z0-9_]+(?:\[[^\]]+\])?)\s*(>=|<=|>|<|:)\s*(.+?)\s*$/;
+    const re = /^\s*([A-Za-z0-9_]+(?:\[[^\]]+\])?)\s*(>=|<=|>|<|:|~)\s*(.+?)\s*$/;
     for (const part of parts) {
         const m = re.exec(part);
         if (!m)
@@ -519,6 +310,8 @@ function parseSearchQuery(query) {
         let value = m[3].trim();
         if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
             value = value.slice(1, -1);
+        if (m[2] === '~' && (!['email', 'name'].includes(m[1]) || value.length < 3))
+            return null;
         clauses.push({ field: m[1], op: m[2], value });
     }
     return { clauses, disjunction };
@@ -536,15 +329,13 @@ function searchFieldValue(item, field) {
 }
 /** A search's numeric comparison other than `>=` (docs.stripe.com/search#search-query-language). */
 function otherComparison(op, a, n) {
-    switch (op) {
-        case '>': return a > n;
-        case '<': return a < n;
-        case '<=': return a <= n;
-    }
-    return false;
+    return op === '>' ? a > n : op === '<' ? a < n : a <= n;
 }
 function evalSearchClause(item, c) {
     const actual = searchFieldValue(item, c.field);
+    // source: https://docs.stripe.com/search "Substring match operator (substrings must be a minimum of 3 characters)"
+    if (c.op === '~')
+        return actual != null && String(actual).toLowerCase().includes(c.value.toLowerCase());
     if (c.op === ':') {
         if (c.value === 'null')
             return actual === null || actual === undefined;
@@ -552,8 +343,8 @@ function evalSearchClause(item, c) {
         if (typeof actual === 'number' && /^-?\d+(\.\d+)?$/.test(c.value))
             return actual === Number(c.value);
         if (typeof actual === 'boolean')
-            return String(actual) === c.value;
-        return String(actual) === c.value;
+            return String(actual).toLowerCase() === c.value.toLowerCase();
+        return String(actual).toLowerCase() === c.value.toLowerCase();
     }
     const n = Number(c.value);
     const a = Number(actual);
@@ -611,24 +402,6 @@ export function buildDiscount(coupon, customer, at, on = {}) {
         invoice: null, invoice_item: null, promotion_code: null, checkout_session: null,
     };
 }
-// The (price id, quantity) pairs a subscription bills, normalized across the shapes the
-// twin stores items in (the create form array items:[{price,quantity}], or the canonical
-// items:{data:[{price}]} list). Used to compute upcoming-invoice lines.
-export function subscriptionItemPairs(sub) {
-    const items = sub.items;
-    const data = Array.isArray(items?.data) ? items.data : Array.isArray(sub.items) ? sub.items : [];
-    const out = [];
-    for (const it of data) {
-        const p = it?.price;
-        const id = typeof p === 'string' ? p : (p && typeof p === 'object' ? String(p.id ?? '') : '');
-        if (id)
-            out.push({ price: id, quantity: Math.max(1, Math.trunc(Number(it.quantity) || 1)) });
-    }
-    // a bare `price` field (the connector's flattened shape) counts as one item.
-    if (out.length === 0 && typeof sub.price === 'string' && sub.price)
-        out.push({ price: sub.price, quantity: 1 });
-    return out;
-}
 // The raw item entries a subscription/checkout-derived-subscription create sent,
 // normalized to an ordered array. The form reader already turns the bracket form
 // items[0][price]=… into an array of objects (see lineItemEntries() above for the
@@ -686,18 +459,12 @@ export function addBillingInterval(atUnix, interval, count) {
 // response includes the actual items, mirroring what was requested.
 /** 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. */
+// source: https://docs.stripe.com/api/plans/create "It replaces the Plans API and is backwards compatible to simplify your migration."
+// source: spec:/components/schemas/plan "amount_decimal"
 export function subscriptionItemPrice(p, find) {
     const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String(p.id ?? '') : '');
     const price = priceId ? find('price', priceId) : undefined;
-    const recurring = price?.recurring;
-    const plan = price ? {
-        id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
-        amount_decimal: price.unit_amount_decimal ?? null, billing_scheme: price.billing_scheme ?? 'per_unit',
-        currency: price.currency ?? 'usd', interval: recurring?.interval ?? null,
-        interval_count: recurring?.interval_count ?? 1, livemode: false,
-        metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
-        product: price.product ?? null, tiers_mode: price.tiers_mode ?? null, usage_type: 'licensed',
-    } : null;
+    const plan = price ? planView(price) : null;
     return { price: price ?? (priceId || null), plan };
 }
 export function buildSubscriptionItemsList(entries, subId, at, find) {
@@ -748,40 +515,6 @@ export function resolveTrial(params, at) {
     }
     return undefined;
 }
-// Create a resource from form params, stamping object + id + created + the given
-// defaults. Only real Stripe field names are emitted (conformance-checked).
-// A vendor `type` field (a price's one_time or recurring, a payout's bank_account) always collides with the kernel's
-// row type, so it is stashed under `_stripe_type` and restored by view().
-export function stashVendorType(_type, fields) {
-    if (!('type' in fields))
-        return fields;
-    const { type: vt, ...rest } = fields;
-    return { ...rest, _stripe_type: vt };
-}
-async function create(type, params, defaults, req, opts = {}) {
-    // honor a caller-provided id (seeding uses the catalog's real prod_*/price_* ids);
-    // otherwise assign one. The id is identity, not a stored field.
-    const { id: providedId, ...rest } = params;
-    const id = typeof providedId === 'string' && providedId ? providedId : nextId(type, req.root);
-    // Most Stripe objects stamp `created`; a few (invoiceitem) use a differently-named
-    // timestamp instead (`date`) and have NO `created` field — honor that, don't fabricate.
-    const fields = stashVendorType(type, { object: OBJECT_NAME[type] ?? type, [opts.timeField ?? 'created']: nowUnix(req.occurredAt), ...defaults, ...rest });
-    return { status: 200, body: await writeResource(type, id, fields, `${type}.create`, req.root, req.occurredAt, req.apiVersion) };
-}
-// ── ISSUING helpers: spending controls, real-time-auth shapes ─────────────────────────
-// Authorization.card is the FULL Card object in every vendor egress (API responses and
-// webhook payloads) — it is not expandable (stripe@22.3.0 Issuing.Authorization.card:
-// Stripe.Issuing.Card). The twin stores the id internally and embeds at the boundary;
-// cardholder stays an id string (expandable, unexpanded default). Caught live: the
-// issuing-bridge reads event.data.object.card.id and refused every twin presentment.
-export function embedIssuingAuthorizationCard(body, root) {
-    if (typeof body.card === 'string') {
-        const cardRow = getOne('issuing_card', body.card, root);
-        if (cardRow !== undefined)
-            body.card = cardRow;
-    }
-    return body;
-}
 // The closed interval set for spending_controls[spending_limits][][interval]
 // (stripe@22.3.0 Issuing/Cards.d.ts SpendingLimit.Interval — a documented closed enum).
 const SPENDING_LIMIT_INTERVALS = new Set(['all_time', 'daily', 'monthly', 'per_authorization', 'weekly', 'yearly']);
@@ -809,12 +542,12 @@ function controlsRefused(what, i = 0) {
 // Vendor rules enforced: interval must be in the closed enum; a spending limit amount is a
 // positive integer; allowed_categories "Cannot be set with blocked_categories" (and the
 // merchant-country pair likewise) — both restrictions verbatim from the SDK's field docs.
-export function normalizeSpendingControls(raw, currency) {
+export function normalizeSpendingControls(raw, currency, previous) {
     if (raw === undefined)
         return {};
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return controlsRefused('dictionary');
-    const sc = raw;
+    const sc = { ...previous, ...raw };
     const strArr = (v) => (Array.isArray(v) ? v.map(String) : undefined);
     const allowedCats = strArr(sc.allowed_categories);
     const blockedCats = strArr(sc.blocked_categories);
@@ -841,6 +574,9 @@ export function normalizeSpendingControls(raw, currency) {
     const arrOrNull = (v) => (v === undefined ? undefined : v.length ? v : null);
     const controls = {
         ...emptySpendingControls(),
+        // source: spec:/paths/~1v1~1issuing~1cards~1{card}/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/spending_controls "Rules that control spending for this card."
+        // Keep every documented control, including allowed_card_presences and blocked_card_presences.
+        ...sc,
         spending_limits: limits,
         ...(limits.length ? { spending_limits_currency: typeof sc.spending_limits_currency === 'string' ? sc.spending_limits_currency : currency } : {}),
     };
@@ -948,6 +684,9 @@ function cardSubObject(params) {
             brand: 'visa', last4: number ? number.slice(-4) : '4242',
             exp_month: Number(c.exp_month) || 12, exp_year: Number(c.exp_year) || 2034,
             funding: 'credit', country: 'US',
+            // source: spec:/components/schemas/payment_method_card/properties/fingerprint/description "Uniquely identifies this particular card number."
+            // The synthetic fingerprint is stable for a number; Stripe's opaque fingerprint algorithm is not published.
+            fingerprint: digest('sha256', number || '4242424242424242').slice(0, 16),
             checks: { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
             networks: { available: ['visa'], preferred: null },
             three_d_secure_usage: { supported: true }, wallet: null,
@@ -1121,18 +860,6 @@ export function lineItemEntries(params) {
     const li = params.line_items;
     return Array.isArray(li) ? li.filter((x) => x && typeof x === 'object') : [];
 }
-// ---- IDEMPOTENCY KEYS (vendor-faithful) ----
-// Real Stripe honors the `Idempotency-Key` header on POST: the first request with a
-// key executes and the (status + body) response is stored against the key; a replay
-// with the SAME key returns the SAME stored response WITHOUT re-applying the write.
-// We persist the stored response as an `_idempotency` resource in the action log
-// (per-root, so a fork has its own keyspace). `_idempotency` is a twin-internal type
-// (never served as a Stripe object), so it does not affect spec conformance.
-//
-// Note: real Stripe only persists idempotency for responses it considers "completed"
-// (2xx and most 4xx, including card 402s) and scopes the key to the account; here we
-// store every executed POST response (success and error alike), keyed per-root.
-const IDEMPOTENCY_TYPE = '_idempotency';
 // ── THE MONEY MODEL: a charge and the refunds taken out of it ──────────────────────────
 //
 // The rule this section exists to hold: A FACT RECORDED ON ONE MONEY OBJECT IS VISIBLE FROM
@@ -1154,79 +881,18 @@ export function chargeDefaults(chargeId, amount, captured, occurredAt) {
         billing_details: { address: null, email: null, name: null, phone: null }, livemode: false,
     };
 }
-/**
- * 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 async function handleStripeTwinRequest(req) {
-    const twin = createStripeTwinFetch({ ...(req.root !== undefined ? { root: req.root } : {}), readOnly: req.readOnly ?? false, ...(req.occurredAt ? { clock: () => req.occurredAt } : {}) });
-    const method = req.method.toUpperCase();
-    const headers = { 'content-type': 'application/x-www-form-urlencoded' };
-    if (req.idempotencyKey)
-        headers['idempotency-key'] = req.idempotencyKey;
-    if (req.apiVersion !== undefined)
-        headers['stripe-version'] = req.apiVersion;
-    if (req.stripeAccount)
-        headers['stripe-account'] = req.stripeAccount;
-    // a GET carries its parameters in the query; a caller that handed them as a body keeps them
-    let path = req.path.startsWith('/') ? req.path : `/${req.path}`;
-    if ((method === 'GET' || method === 'HEAD') && req.body)
-        path += (path.includes('?') ? '&' : '?') + req.body;
-    const response = await twin(new Request(`http://stripe.test${path}`, { method, headers, ...(method !== 'GET' && method !== 'HEAD' && req.body ? { body: req.body } : {}) }));
-    const text = await response.text();
-    return { status: response.status, body: text ? JSON.parse(text) : null };
-}
-/**
- * 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 async function handleStripeDoor(req, params) {
-    const method = req.method.toUpperCase();
-    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
-    const seg = path.replace(/^\/+/, '').split('/');
-    if (seg[0] !== '_twin')
-        return undefined;
-    if (req.readOnly)
-        return err('twin is read-only; omit readOnly to accept writes', 405);
-    if (path === '/_twin/account' && method === 'POST') {
-        const ex = getOne('account', PLATFORM_ACCOUNT_ID, req.root);
-        const { type: _t, settings: rawSettings, business_profile: rawProfile, ...rest } = params;
-        // the platform's account is Stripe's default until the page first changes it (semantics/connect.ts, the same
-        // default GET /v1/account answers and the Public details page stores)
-        const fields = {
-            ...(ex ? {} : (({ id: _id, ...base }) => base)(platformAccountDefault())),
-            ...rest,
-            settings: accountSettings(rawSettings, ex?.settings),
-            // a hash is merged into what the account holds, as an update merges it (the name the Public details page saved stays)
-            ...(rawProfile && typeof rawProfile === 'object' ? { business_profile: { ...(ex?.business_profile ?? {}), ...rawProfile } } : {}),
-        };
-        return { status: 200, body: await writeResource('account', PLATFORM_ACCOUNT_ID, stashVendorType('account', fields), 'account.update', req.root, req.occurredAt) };
-    }
-    // Issuing network tokens are minted by the card network when a cardholder adds the card to a
-    // phone's wallet (docs.stripe.com/issuing/cards/digital-wallets): there is no API create, and the
-    // act happens in the phone's wallet app, not on a Stripe page. POST /_twin/issuing/cards/:card/wallets
-    // stands in for that act ({wallet_provider, network}); the API reads the token and moves its status.
-    // Where the documentation stops and the twin decides: the network approves at once (the token is active).
-    if (seg[0] === '_twin' && seg[1] === 'issuing' && seg[2] === 'cards' && seg[3] && seg[4] === 'wallets' && seg.length === 5 && method === 'POST') {
-        const card = decodeURIComponent(seg[3]);
-        const c = getOne('issuing_card', card, req.root);
-        if (!c)
-            return err(`No such card: '${card}'`, 400, 'resource_missing');
-        const wallet = typeof params.wallet_provider === 'string' && ['apple_pay', 'google_pay', 'samsung_pay'].includes(params.wallet_provider)
-            ? params.wallet_provider : 'apple_pay';
-        const network = typeof params.network === 'string' && ['visa', 'mastercard'].includes(params.network) ? params.network : 'visa';
-        const last4 = typeof c.last4 === 'string' ? c.last4 : '0000';
-        return create('issuing_token', { card, cardholder: typeof c.cardholder === 'string' ? c.cardholder : (c.cardholder?.id ?? null) }, {
-            status: 'active', wallet_provider: wallet, network, last4, livemode: false,
-            device_fingerprint: null, network_data: null, network_updated_at: nowUnix(req.occurredAt),
-        }, req);
-    }
-    return undefined;
-}
 // collection path segment → resource type, for the generic list of a collection Stripe does not
 // list at that path (the twin's test clocks, which Stripe lists under /v1/test_helpers).
+export function planView(price) {
+    const recurring = price.recurring;
+    return {
+        id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
+        amount_decimal: price.unit_amount_decimal ?? (price.unit_amount == null ? null : String(price.unit_amount)),
+        billing_scheme: price.billing_scheme ?? 'per_unit', created: price.created, currency: price.currency,
+        interval: recurring?.interval ?? null, interval_count: recurring?.interval_count ?? 1,
+        livemode: price.livemode ?? false, metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
+        product: price.product ?? null, tiers_mode: price.tiers_mode ?? null,
+        meter: recurring?.meter ?? null, trial_period_days: recurring?.trial_period_days ?? null,
+        transform_usage: price.transform_quantity ?? null, usage_type: recurring?.usage_type ?? 'licensed',
+    };
+}

package/dist/src/engine/subscriptions.d.ts

@@ -0,0 +1,11 @@
+import type { Row } from './common.js';
+export declare const SUB = "subscription";
+/** pause_collection pauses billing (the paused event fires) and clearing it resumes
+ *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
+export declare function pauseCollection(pc: unknown, fields: Row): string | undefined;
+/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
+ *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
+ *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
+export declare const MAX_TRIAL: number;
+/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
+export declare function movedTrial(sub: Row, fields: Row, end: number, now: number): undefined;

package/dist/src/engine/subscriptions.js

@@ -0,0 +1,30 @@
+export const SUB = 'subscription';
+// pause_collection pauses billing (the subscription stays active; the paused event fires) and
+// clearing it resumes; cancel_at_period_end schedules or withdraws a cancel; a coupon replaces the
+// discount and an empty one clears it
+/** pause_collection pauses billing (the paused event fires) and clearing it resumes
+ *  (docs.stripe.com/billing/subscriptions/pause-payment); answers the event, or nothing for a value it does not take. */
+export function pauseCollection(pc, fields) {
+    const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc).length === 0);
+    if (isClear) {
+        fields.pause_collection = null;
+        return 'customer.subscription.resumed';
+    }
+    if (!pc || typeof pc !== 'object')
+        return undefined;
+    const p = pc;
+    fields.pause_collection = { behavior: typeof p.behavior === 'string' ? p.behavior : 'void', resumes_at: p.resumes_at !== undefined ? Number(p.resumes_at) : null };
+    return 'customer.subscription.paused';
+}
+/** The longest trial Stripe takes: `trial_end` "Can be at most two years from `billing_cycle_anchor`"
+ *  (docs.stripe.com/api/subscriptions/update#update_subscription-trial_end); "The trial period must be 730 days (2 years)
+ *  or less" (docs.stripe.com/billing/subscriptions/trials/free-trials). */
+export const MAX_TRIAL = 730 * 86400;
+/** A trial moved to end at `end`, or a new one to `end` on a subscription out of its trial (applyTrialEnd). */
+export function movedTrial(sub, fields, end, now) {
+    Object.assign(fields, {
+        status: 'trialing', trial_end: end, trial_start: sub.trial_start ?? now, billing_cycle_anchor: end,
+        current_period_end: end, ...(sub.status !== 'trialing' ? { current_period_start: now } : {}),
+    });
+    return undefined;
+}

package/dist/src/engine/transfers.d.ts

@@ -0,0 +1,2 @@
+import type { Row } from './common.js';
+export declare const emptyList: (url: string) => Row;

package/dist/src/engine/transfers.js

@@ -0,0 +1 @@
+export const emptyList = (url) => ({ object: 'list', data: [], has_more: false, total_count: 0, url });