@volter/twin-stripe 3.0.0 → 3.0.1

package/dist/src/engine/stripe.js

@@ -1,7 +1,4 @@
-// Stripe's own computation that its handlers share (docs/contributing/architecture.md, "Pack layout": the engine): money
-// and its declines, 3-D Secure and micro-deposits, the list page and the search grammar, a subscription's items, billing
-// intervals and discounts, Issuing's spending controls, a payment method's sub-object, a Connect account's settings and a
-// Checkout Session's line items. None of it reads or writes state: a caller hands it what it looked up (FindStored).
+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. */
@@ -138,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);
@@ -157,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).
@@ -332,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)
@@ -340,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 };
@@ -357,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;
@@ -373,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);
@@ -432,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
@@ -507,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) {
@@ -569,20 +515,6 @@ export function resolveTrial(params, at) {
     }
     return undefined;
 }
-// ── 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, find) {
-    if (typeof body.card === 'string') {
-        const cardRow = find('issuing_card', body.card);
-        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']);
@@ -610,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);
@@ -642,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 } : {}),
     };
@@ -749,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,
@@ -945,3 +883,16 @@ export function chargeDefaults(chargeId, amount, captured, occurredAt) {
 }
 // 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

@@ -9,4 +9,3 @@ export declare function pauseCollection(pc: unknown, fields: Row): string | unde
 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;
-export declare const ITEM_ATTRIBUTES: Set<string>;

package/dist/src/engine/subscriptions.js

@@ -28,4 +28,3 @@ export function movedTrial(sub, fields, end, now) {
     });
     return undefined;
 }
-export const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);

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

@@ -2,8 +2,6 @@
 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;
-/** Every includable field name, as `expand` paths on a top-level object: what a check of an object's FULL answer expands. */
-export declare const INCLUDABLE_FIELDS: string[];
 /** 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. */

package/dist/src/engine/version.js

@@ -12,12 +12,16 @@ 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';
+const CLOVER = '2025-09-30';
 /** 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'],
+    // source: spec:PostWebhookEndpoints "Whether this endpoint should receive events from connected accounts"
+    // connect configures event delivery; it is not a WebhookEndpoint response field.
+    webhook_endpoint: ['connect'],
     // 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
@@ -32,7 +36,7 @@ const KEPT = {
     payment_intent: ['mandate', 'off_session'],
     subscription: ['payment_behavior'],
     subscription_item: ['livemode'],
-    subscription_schedule: ['from_subscription', 'renewal_interval'],
+    subscription_schedule: ['from_subscription', 'renewal_interval', 'proration_behavior'],
     'tax.transaction': ['calculation'],
     'terminal.reader': ['registration_code'],
     topup: ['destination_balance'],
@@ -59,8 +63,7 @@ const BASIL_CHANGES = {
         // "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.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;
+        const confirmation_secret = o.confirmation_secret ?? null;
         return { ...omit(o, ['payment_intent', 'charge', 'paid', 'paid_out_of_band', 'subscription']), parent, confirmation_secret };
     },
     charge: (o) => omit(o, ['invoice', 'source']),
@@ -221,8 +224,6 @@ const INCLUDABLE = {
     // request it with the `expand` request parameter))"
     invoice: ['confirmation_secret'],
 };
-/** Every includable field name, as `expand` paths on a top-level object: what a check of an object's FULL answer expands. */
-export const INCLUDABLE_FIELDS = [...new Set(Object.values(INCLUDABLE).flat())];
 /** 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);
@@ -280,9 +281,19 @@ export function render(value, pinned, expand = []) {
         // reads the same, and a key posted "" to remove it is not there (../semantics/shared.ts withMetadata)
         if (o.metadata && typeof o.metadata === 'object' && !Array.isArray(o.metadata))
             o.metadata = Object.fromEntries(Object.entries(o.metadata).filter(([, v]) => v !== '').map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
+        // source: spec:/components/schemas/checkout.session/properties/ui_mode "Defaults to `hosted_page`."
+        // Endive names hosted/custom Checkout hosted_page/elements; older SDK versions keep their own names.
+        if (kind === 'checkout.session' && (!pinned || pinned >= '2026-09-30')) {
+            if (o.ui_mode === 'hosted')
+                o.ui_mode = 'hosted_page';
+            if (o.ui_mode === 'custom')
+                o.ui_mode = 'elements';
+        }
         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);
+        // source: https://docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon "Moves the top-level coupon field on Promotion Codes to promotion.coupon"
+        const changed = kind === 'promotion_code' && pinned && pinned < CLOVER ? omit(kept, ['promotion']) : BASIL_CHANGES[kind] ? BASIL_CHANGES[kind](kept) : kept;
+        return omit(withNulls(changed, kind), hidden);
     };
     return walk(value);
 }

package/dist/src/fetch.js

@@ -8,8 +8,8 @@ import { clock } from "./semantics/clock.js";
 import * as doors from "./semantics/doors.js";
 import { stripeSemantics } from "./semantics/index.js";
 import { screen as screen_billing_portal } from "./screens/billing-portal.js";
+import { screen as screen_checkout_js } from "./screens/checkout-js.js";
 import { screen as screen_checkout } from "./screens/checkout.js";
-import { screen as screen_connect_oauth } from "./screens/connect-oauth.js";
 import { screen as screen_connect_onboarding } from "./screens/connect-onboarding.js";
 import { screen as screen_dashboard } from "./screens/dashboard.js";
 import { screen as screen_stripe_js } from "./screens/stripe-js.js";
@@ -21,6 +21,6 @@ export function createStripeFetch(options = {}) {
         doors,
         around,
         clock,
-        screens: { "billing-portal": screen_billing_portal, "checkout": screen_checkout, "connect-oauth": screen_connect_oauth, "connect-onboarding": screen_connect_onboarding, "dashboard": screen_dashboard, "stripe-js": screen_stripe_js },
+        screens: { "billing-portal": screen_billing_portal, "checkout-js": screen_checkout_js, "checkout": screen_checkout, "connect-onboarding": screen_connect_onboarding, "dashboard": screen_dashboard, "stripe-js": screen_stripe_js },
     }, options);
 }