@volter/twin-stripe 3.0.0 → 3.0.1

package/src/engine/stripe.ts

@@ -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, type TwinResource } from '@volter/world-core';
 import { SERVED_VERSION } from './version.ts';
 
@@ -170,8 +167,6 @@ export function threeDsNextAction(): Record<string, unknown> {
 // 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: Array<Record<string, unknown>>): boolean {
   for (const params of paramSets) {
     const ref = resolveCardRef(params);
@@ -188,31 +183,6 @@ export function microdepositsNextAction(): Record<string, unknown> {
     },
   };
 }
-/** The two deposits' amounts as sent: the test values (docs.stripe.com/payments/ach-direct-debit/accept-a-payment). */
-function amountsMatch(params: Record<string, unknown>): boolean {
-  const got = (params.amounts as unknown[]).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: Record<string, unknown>): boolean {
-  return String(params.descriptor_code) === MICRODEPOSIT_DESCRIPTOR;
-}
-/** Stripe's refusal of deposits that do not match what was sent. */
-function depositMismatch(byAmounts: boolean): StripeResponse {
-  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: Record<string, unknown>, _existing: Record<string, unknown>): StripeResponse | null {
-  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).
@@ -364,7 +334,7 @@ export function asBool(v: unknown): boolean {
 // resource view. This is the vendor's OWN per-field semantics (A4: not a cross-vendor query
 // engine — it lives in the Stripe pack and speaks Stripe's language only). Unsupported
 // constructs cause the clause to not match (safe), never a fabricated hit.
-type SearchClause = { field: string; op: ':' | '>' | '<' | '>=' | '<='; value: string };
+type SearchClause = { field: string; op: ':' | '~' | '>' | '<' | '>=' | '<='; value: string };
 // Tokenize on top-level AND/OR (we treat the whole query as either all-AND or all-OR; mixed
 // precedence is uncommon in practice and Stripe groups with parens we don't model — kept simple).
 function parseSearchQuery(query: string): { clauses: SearchClause[]; disjunction: boolean } | null {
@@ -373,12 +343,13 @@ function parseSearchQuery(query: string): { clauses: SearchClause[]; disjunction
   const disjunction = / OR /i.test(trimmed) && !/ AND /i.test(trimmed);
   const parts = trimmed.split(disjunction ? / OR /i : / AND /i);
   const clauses: SearchClause[] = [];
-  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) return null;
     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] as SearchClause['op'], value });
   }
   return { clauses, disjunction };
@@ -396,22 +367,19 @@ function searchFieldValue(item: Record<string, unknown>, field: string): unknown
 }
 /** A search's numeric comparison other than `>=` (docs.stripe.com/search#search-query-language). */
 function otherComparison(op: string, a: number, n: number): boolean {
-  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: Record<string, unknown>, c: SearchClause): boolean {
   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;
     // numeric exact when both look numeric; else string-equality (case-sensitive, like Stripe tokens)
     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;
+    if (typeof actual === 'boolean') return String(actual).toLowerCase() === c.value.toLowerCase();
+    return String(actual).toLowerCase() === c.value.toLowerCase();
   }
   const n = Number(c.value);
   const a = Number(actual);
@@ -470,23 +438,6 @@ export function buildDiscount(coupon: Record<string, unknown>, customer: string,
   };
 }
 
-// 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: Record<string, unknown>): Array<{ price: string; quantity: number }> {
-  const items = sub.items as { data?: unknown } | undefined;
-  const data = Array.isArray(items?.data) ? items!.data : Array.isArray(sub.items) ? (sub.items as unknown[]) : [];
-  const out: Array<{ price: string; quantity: number }> = [];
-  for (const it of data as Array<Record<string, unknown>>) {
-    const p = it?.price;
-    const id = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).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
@@ -548,18 +499,13 @@ export function addBillingInterval(atUnix: number, interval: BillingInterval, co
 // 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: unknown, find: FindStored): { price: Record<string, unknown> | string | null; plan: Record<string, unknown> | null } {
   const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).id ?? '') : '');
   const price = priceId ? find('price', priceId) : undefined;
-  const recurring = price?.recurring as Record<string, unknown> | undefined;
-  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 };
 }
 
@@ -612,20 +558,6 @@ export function resolveTrial(params: Record<string, unknown>, at: number): { sta
   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: Record<string, unknown>, find: FindStored): Record<string, unknown> {
-  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']);
@@ -656,10 +588,10 @@ function controlsRefused(what: 'dictionary' | 'categories' | 'countries' | 'limi
 // 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: unknown, currency: string | null): { controls?: Record<string, unknown>; error?: StripeResponse } {
+export function normalizeSpendingControls(raw: unknown, currency: string | null, previous?: Record<string, unknown>): { controls?: Record<string, unknown>; error?: StripeResponse } {
   if (raw === undefined) return {};
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return controlsRefused('dictionary');
-  const sc = raw as Record<string, unknown>;
+  const sc = { ...previous, ...(raw as Record<string, unknown>) };
   const strArr = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.map(String) : undefined);
   const allowedCats = strArr(sc.allowed_categories);
   const blockedCats = strArr(sc.blocked_categories);
@@ -681,6 +613,9 @@ export function normalizeSpendingControls(raw: unknown, currency: string | null)
   const arrOrNull = (v: string[] | undefined) => (v === undefined ? undefined : v.length ? v : null);
   const controls: Record<string, unknown> = {
     ...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 } : {}),
   };
@@ -789,6 +724,9 @@ function cardSubObject(params: Params): 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,
@@ -1014,3 +952,17 @@ export function chargeDefaults(chargeId: string, amount: number, captured: boole
 // 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: Record<string, unknown>): Record<string, unknown> {
+  const recurring = price.recurring as Record<string, unknown> | undefined;
+  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/src/engine/subscriptions.ts

@@ -3,7 +3,6 @@
 // invoice's PaymentIntent; canceling it is the machine's move in ../manifest.ts. Retrieve of a
 // subscription and of an item are the derived core's.
 import type { Row } from './common.ts';
-
 export const SUB = 'subscription';
 
 // pause_collection pauses billing (the subscription stays active; the paused event fires) and
@@ -36,5 +35,3 @@ export function movedTrial(sub: Row, fields: Row, end: number, now: number): und
   });
   return undefined;
 }
-
-export const ITEM_ATTRIBUTES = new Set(['billing_thresholds', 'discounts', 'metadata', 'price', 'quantity', 'tax_rates']);

package/src/engine/transfers.ts

@@ -19,5 +19,4 @@
 // captured; the refusals' wording is the twin's.
 // Transfer list, retrieve and update and application-fee list and retrieve are the derived core's.
 import type { Row } from './common.ts';
-
 export const emptyList = (url: string): Row => ({ object: 'list', data: [], has_more: false, total_count: 0, url });

package/src/engine/version.ts

@@ -15,6 +15,7 @@ type Row = Record<string, unknown>;
 /** 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?: string | null): boolean => !pinned || pinned >= BASIL;
@@ -23,6 +24,9 @@ export const servesCurrent = (pinned?: string | null): boolean => !pinned || pin
 // flag, the payment behavior a subscription was created with) and links it follows internally.
 const KEPT: Record<string, string[]> = {
   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
@@ -37,7 +41,7 @@ const KEPT: Record<string, string[]> = {
   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'],
@@ -66,8 +70,7 @@ const BASIL_CHANGES: Record<string, (o: Row, parent?: Row) => Row> = {
     // "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']),
@@ -228,9 +231,6 @@ const INCLUDABLE: Record<string, string[]> = {
   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: string[] = [...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: Request): Promise<string[]> {
   const url = new URL(request.url);
@@ -274,9 +274,17 @@ export function render(value: unknown, pinned?: string | null, expand: string[]
     // reader coerces a numeric-looking value to a number, which the answer gives back as the string it was sent as
     // 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 as Row).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/src/engine/webhooks.ts

@@ -3,9 +3,7 @@
 // event type, Stripe's own event types (the spec's list, ../generated/events.gen.json), and the one message Stripe decides
 // by its receiver's answer, the real-time authorization request.
 import { hmac } from '@volter/world-core';
-
 import vendorEvents from '../generated/events.gen.json' with { type: 'json' };
-
 /** Every event type Stripe's spec enumerates: a write whose operation is one sends it, and `<resource>.create`,
  *  `.update` and `.delete` send `<resource>.created`, `.updated` and `.deleted` when Stripe has that type. */
 export const STRIPE_EVENT_TYPES: ReadonlyArray<string> = (vendorEvents as { types: string[] }).types;

package/src/fetch.ts

@@ -8,8 +8,8 @@ import { clock } from './semantics/clock.ts';
 import * as doors from './semantics/doors.ts';
 import { stripeSemantics } from './semantics/index.ts';
 import { screen as screen_billing_portal } from './screens/billing-portal.tsx';
+import { screen as screen_checkout_js } from './screens/checkout-js.ts';
 import { screen as screen_checkout } from './screens/checkout.tsx';
-import { screen as screen_connect_oauth } from './screens/connect-oauth.tsx';
 import { screen as screen_connect_onboarding } from './screens/connect-onboarding.tsx';
 import { screen as screen_dashboard } from './screens/dashboard.tsx';
 import { screen as screen_stripe_js } from './screens/stripe-js.ts';
@@ -22,6 +22,6 @@ export function createStripeFetch(options: PackFetchOptions = {}): DerivedFetch
     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);
 }