@volter/twin-stripe 2.0.38 → 3.0.1

package/src/engine/subscriptions.ts

@@ -0,0 +1,37 @@
+// Subscription and SubscriptionItem semantics. A subscription is created with its items, its
+// billing period and, under payment_behavior=default_incomplete, its first invoice and that
+// 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
+// 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: unknown, fields: Row): string | undefined {
+  const isClear = pc === '' || pc === null || (typeof pc === 'object' && pc !== null && Object.keys(pc as object).length === 0);
+  if (isClear) {
+    fields.pause_collection = null;
+    return 'customer.subscription.resumed';
+  }
+  if (!pc || typeof pc !== 'object') return undefined;
+  const p = pc as Row;
+  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: Row, fields: Row, end: number, now: number): undefined {
+  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/src/engine/transfers.ts

@@ -0,0 +1,22 @@
+// Transfer and application-fee semantics: money the platform moves to a connected account and
+// claws back (reversals), and the platform's fee on a connected charge and its refunds. A
+// reversal or fee refund never exceeds what is left, and lands on its parent's totals and list.
+// A transfer goes only to an account whose transfers capability is active, comes out of the
+// platform's available balance, and lands in the destination's (docs.stripe.com/connect/separate-
+// charges-and-transfers); a reversal moves it back.
+// A transfer tied to a charge (`source_transaction`, "Transfer availability" in the same guide) "returns success
+// regardless of your available balance if the related charge hasn't settled yet", but "the funds don't become
+// available in the destination account until the funds from the associated charge are available"; a charge whose funds
+// are already available by the World's clock is no exception, and the transfer is held to the available balance as any
+// other. "The amount of the transfer must not exceed the amount of the source charge", several transfers may share one
+// charge while "the sum of the transfers doesn't exceed the source charge", and the charge's balance currency must
+// match. "If the source charge has a `transfer_group` value, Stripe assigns the same value to the transfer's
+// `transfer_group`. If it doesn't, then Stripe generates a string in the format `group_` plus the associated
+// PaymentIntent ID ... It assigns that string as the `transfer_group` for both the charge and the transfer."
+// Where the documentation stops and the twin decides: the sum from one charge counts each transfer less what was
+// reversed of it; a transfer_group the request names is kept only when the charge has none and no PaymentIntent to
+// name one after; an uncaptured charge (an authorization, docs silent) is refused as a source_transaction until it is
+// 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/{stripe-version.ts → engine/version.ts}

@@ -8,13 +8,14 @@
 // 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' };
+import surface from '../generated/surface.gen.json' with { type: 'json' };
 
 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'],
@@ -65,9 +69,8 @@ const BASIL_CHANGES: Record<string, (o: Row, parent?: Row) => Row> = {
     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;
+    // the intent's client_secret is the one ./stripe.ts mintClientSecret gives it
+    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);
@@ -272,10 +272,19 @@ export function render(value: unknown, pinned?: string | null, expand: string[]
     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 as Row).map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
+    // 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/webhook-endpoints.ts

@@ -0,0 +1,14 @@
+// Webhook endpoint semantics: registering a URL and the events it subscribes to. Delivery reads
+// the endpoints from the tree, signing each POST with the endpoint's own secret; a disabled one
+// (the machine in ../manifest.ts) receives nothing. Endpoint list, retrieve and delete are the derived core's.
+//
+// The Events API lists and retrieves the stored events of the account a request acts for: an event of a connected
+// account carries it ("Each event for a connected account contains a top-level `account` property that identifies the
+// connected account. Because the connected account owns the object that triggered the event, you must make API
+// requests for that object as the connected account", docs.stripe.com/connect/webhooks; the event's `account`: "The
+// connected account that originates the event", spec/openapi.json.gz), so a request with the Stripe-Account header
+// sees that account's events and one without it the platform's, those with no `account`. Where the documentation
+// stops and the twin decides: a platform request does not see its connected accounts' events.
+
+export const WE = 'webhook_endpoint';
+

package/src/engine/webhooks.ts

@@ -0,0 +1,70 @@
+// Stripe's events as its handlers and its declared `events` need them (the kernel renders, stores, signs and delivers
+// every event a write sends: ../manifest.ts `events`, ../semantics/shared.ts STRIPE_EVENTS): which write sends which
+// 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;
+
+/** The writes whose event is named otherwise than by their resource (the rest are STRIPE_EVENT_TYPES'). A refund sends
+ *  `refund.created` for the Refund; the charge's own write is recorded as `charge.refunded`, the charge with its new
+ *  totals. `issuing_authorization.request` is no write's: it is asked of the endpoint (askForAuthorization). */
+export const NAMED_EVENTS: Record<string, string> = {
+  'payment_intent.confirm': 'payment_intent.succeeded',
+  'payment_method.attach': 'payment_method.attached',
+  'payment_method.detach': 'payment_method.detached',
+  'setup_intent.confirm': 'setup_intent.succeeded',
+  'subscription.create': 'customer.subscription.created',
+  'subscription.update': 'customer.subscription.updated',
+  'subscription.cancel': 'customer.subscription.deleted',
+  'invoice.finalize': 'invoice.finalized',
+  'invoice.pay': 'invoice.paid',
+  'invoice.void': 'invoice.voided',
+  'dispute.create': 'charge.dispute.created',
+};
+
+/** Whether an endpoint's `enabled_events` takes a type: `*` takes all, `<family>.*` the family, else the type itself. */
+export function stripeEventMatches(enabledEvents: unknown, type: string): boolean {
+  if (!Array.isArray(enabledEvents)) return false;
+  return enabledEvents.some((p) => {
+    const s = String(p);
+    return s === '*' || (s.endsWith('.*') && type.startsWith(s.slice(0, -1))) || s === type;
+  });
+}
+
+/** A `Stripe-Signature` header: HMAC-SHA256 over `${timestamp}.${payload}` keyed by the endpoint's secret, as
+ *  `t=<unix>,v1=<hex>` (docs.stripe.com/webhooks#verify-manually). */
+export const stripeSignature = (payload: string, secret: string, timestamp: number): string => `t=${timestamp},v1=${hmac(secret, `${timestamp}.${payload}`)}`;
+
+// ── Real-time authorization (issuing_authorization.request) ──────────────────────────────────────
+// Stripe delivers issuing_authorization.request to the one enrolled endpoint while the card network holds the
+// authorization open, and the endpoint must answer within Stripe's 2-second window ("This request should be made within
+// the timeout window of the real-time authorization flow", stripe@22.3.0 Issuing/Authorizations.d.ts; the current method
+// is to "respond directly to the webhook request to approve an authorization"). The answer's body carries the decision:
+// a JSON object with a boolean `approved` (and, for an amount-controllable request, an optional integer `amount`).
+// Outcomes map onto request_history.reason (stripe@22.3.0 RequestHistory.Reason): webhook_approved / webhook_declined,
+// the endpoint answered in time; webhook_timeout, no answer inside the window (an unreachable endpoint too);
+// webhook_error, "the direct webhook response is invalid (for example, parsing errors or missing parameters)": a
+// non-2xx status, a body that is not JSON, or no `approved`.
+export const STRIPE_REALTIME_AUTH_TIMEOUT_MS = 2_000;
+
+export type StripeAuthRequestOutcome =
+  | { kind: 'approved'; amount?: number }
+  | { kind: 'declined' }
+  | { kind: 'timeout'; message: string }
+  | { kind: 'error'; message: string };
+
+/** The endpoint's answer read as the decision: `approved` (and an optional `amount`), or an error for an answer Stripe
+ *  cannot read. */
+export function readDecision(res: { status: number; body: string }): StripeAuthRequestOutcome {
+  if (res.status < 200 || res.status >= 300) return { kind: 'error', message: `Webhook endpoint responded with HTTP status ${res.status}.` };
+  let parsed: unknown;
+  try { parsed = JSON.parse(res.body); } catch { return { kind: 'error', message: 'Webhook response body was not valid JSON.' }; }
+  const approved = (parsed as { approved?: unknown } | null)?.approved;
+  if (typeof approved !== 'boolean') return { kind: 'error', message: 'Webhook response is missing the required `approved` parameter.' };
+  if (!approved) return { kind: 'declined' };
+  const amount = (parsed as { amount?: unknown }).amount;
+  return { kind: 'approved', ...(typeof amount === 'number' && Number.isInteger(amount) && amount > 0 ? { amount } : {}) };
+}

package/src/fetch.ts

@@ -0,0 +1,27 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { around } from './semantics/around.ts';
+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_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';
+
+export function createStripeFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: stripeSemantics,
+    doors,
+    around,
+    clock,
+    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);
+}