@volter/twin-stripe 2.0.38 → 3.0.1

package/dist/src/{stripe-version.d.ts → 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/{stripe-version.js → engine/version.js}

@@ -8,16 +8,20 @@
 // 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' };
 /** 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'],
@@ -58,9 +62,8 @@ const BASIL_CHANGES = {
         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']),
@@ -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);
@@ -277,11 +278,22 @@ export function render(value, pinned, expand = []) {
             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
+        // 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).map(([k, v]) => [k, typeof v === 'number' || typeof v === 'boolean' ? String(v) : v]));
+            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/engine/webhook-endpoints.d.ts

@@ -0,0 +1 @@
+export declare const WE = "webhook_endpoint";

package/dist/src/engine/webhook-endpoints.js

@@ -0,0 +1,12 @@
+// 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/dist/src/engine/webhooks.d.ts

@@ -0,0 +1,31 @@
+/** 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 declare const STRIPE_EVENT_TYPES: ReadonlyArray<string>;
+/** 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 declare const NAMED_EVENTS: Record<string, string>;
+/** Whether an endpoint's `enabled_events` takes a type: `*` takes all, `<family>.*` the family, else the type itself. */
+export declare function stripeEventMatches(enabledEvents: unknown, type: string): boolean;
+/** 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 declare const stripeSignature: (payload: string, secret: string, timestamp: number) => string;
+export declare const STRIPE_REALTIME_AUTH_TIMEOUT_MS = 2000;
+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 declare function readDecision(res: {
+    status: number;
+    body: string;
+}): StripeAuthRequestOutcome;

package/dist/src/engine/webhooks.js

@@ -0,0 +1,68 @@
+// 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 = vendorEvents.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 = {
+    '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, type) {
+    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, secret, timestamp) => `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;
+/** 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) {
+    if (res.status < 200 || res.status >= 300)
+        return { kind: 'error', message: `Webhook endpoint responded with HTTP status ${res.status}.` };
+    let parsed;
+    try {
+        parsed = JSON.parse(res.body);
+    }
+    catch {
+        return { kind: 'error', message: 'Webhook response body was not valid JSON.' };
+    }
+    const approved = parsed?.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.amount;
+    return { kind: 'approved', ...(typeof amount === 'number' && Number.isInteger(amount) && amount > 0 ? { amount } : {}) };
+}

package/dist/src/fetch.d.ts

@@ -0,0 +1,2 @@
+import { type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+export declare function createStripeFetch(options?: PackFetchOptions): DerivedFetch;

package/dist/src/fetch.js

@@ -0,0 +1,26 @@
+// 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 } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { around } from "./semantics/around.js";
+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_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";
+export function createStripeFetch(options = {}) {
+    return createPackFetch({
+        manifest,
+        surface: surface,
+        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);
+}