@volter/twin-stripe 2.0.37 → 3.0.0

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

@@ -1,85 +0,0 @@
-// 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.
-import { worldEnvValue } from '@volter/world-core';
-import { asBool } from "../stripe-twin.js";
-import { actingAccount } from "./ledger.js";
-import { at, created, fail, inRange, list, newest, where } from "./shared.js";
-const WE = 'webhook_endpoint';
-// The signing secret is the World's where the World set one. Stripe mints an endpoint's secret and the app is given it
-// (the dashboard, `stripe listen`); in a World the app's env is the World's, made at boot, so the World's value is the
-// one the app verifies with, and an endpoint the app registers is signed with it: the twin's decision, since Stripe
-// lets no one choose a secret. A Connect endpoint (`connect`) takes a Connect name first. Only a value the World sets
-// counts (worldEnvValue), never one the caller's shell passes through; with none (a twin outside a World) the twin
-// mints, as Stripe does.
-const ACCOUNT_SECRET_ENV = ['STRIPE_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SIGNING_SECRET', 'STRIPE_ENDPOINT_SECRET', 'STRIPE_WEBHOOK_SECRET_KEY', 'NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET'];
-const CONNECT_SECRET_ENV = ['STRIPE_CONNECT_WEBHOOK_SECRET', 'STRIPE_WEBHOOK_SECRET_CONNECT', 'STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET'];
-export function worldEndpointSecret(connect) {
-    for (const name of connect ? [...CONNECT_SECRET_ENV, ...ACCOUNT_SECRET_ENV] : ACCOUNT_SECRET_ENV) {
-        const value = worldEnvValue(name);
-        if (value)
-            return value;
-    }
-    return undefined;
-}
-const create = async (ctx) => {
-    const params = ctx.params;
-    const url = typeof params.url === 'string' ? params.url : '';
-    if (!url)
-        return fail(ctx, 'Missing required param: url.', 400, 'parameter_missing');
-    const enabledEvents = Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : typeof params.enabled_events === 'string' ? [params.enabled_events] : undefined;
-    if (!enabledEvents || enabledEvents.length === 0)
-        return fail(ctx, 'Missing required param: enabled_events.', 400, 'parameter_missing');
-    const id = ctx.mint(WE);
-    return ctx.reply(await created(ctx, WE, { ...params, id }, {
-        url, enabled_events: enabledEvents, status: 'enabled', livemode: false, metadata: {},
-        api_version: '2024-06-20', application: null, description: typeof params.description === 'string' ? params.description : null,
-        secret: worldEndpointSecret(asBool(params.connect)) ?? `whsec_twin_${id}`,
-    }));
-};
-// `disabled` switches delivery off (status disabled) and back on; it is a parameter, not a field
-const update = async (ctx) => {
-    const id = at(ctx, 'webhook_endpoint');
-    const we = ctx.get(WE, id);
-    if (!we)
-        return ctx.notFound(WE, id);
-    const { disabled, ...fields } = { ...ctx.params };
-    if (Array.isArray(ctx.params.enabled_events))
-        fields.enabled_events = ctx.params.enabled_events.map(String);
-    if (disabled !== undefined)
-        return switchDelivery(ctx, id, we, fields, asBool(disabled));
-    return ctx.reply(await ctx.write(WE, id, fields, 'webhook_endpoint.update'));
-};
-/** `disabled` switches delivery off or back on (docs.stripe.com/api/webhook_endpoints/update#update_webhook_endpoint-disabled). */
-async function switchDelivery(ctx, id, we, fields, off) {
-    const status = off ? 'disabled' : 'enabled';
-    const refused = ctx.legal(WE, 'status', 'PostWebhookEndpointsWebhookEndpoint', we.status, status, id);
-    if (refused)
-        return ctx.refuse(refused);
-    return ctx.reply(await ctx.write(WE, id, { ...fields, status }, 'webhook_endpoint.update'));
-}
-/** Whether a stored event is the acting account's (no `account`: the platform's). */
-const ownEvent = (ctx, e) => (typeof e.account === 'string' ? e.account : undefined) === actingAccount(ctx);
-const listEvents = async (ctx) => list(ctx, 'event', where(ctx, newest(ctx, 'event').filter((e) => ownEvent(ctx, e)), {
-    type: (e, v) => e.type === v,
-    types: (e, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(e.type)),
-    created: (e, v) => inRange(e.created, v),
-}));
-const retrieveEvent = async (ctx) => {
-    const e = ctx.get('event', at(ctx, 'id'));
-    return e && ownEvent(ctx, e) ? ctx.reply(e) : ctx.notFound('event', at(ctx, 'id'));
-};
-export const webhookEndpoints = {
-    GetEvents: listEvents,
-    GetEventsId: retrieveEvent,
-    PostWebhookEndpoints: create,
-    PostWebhookEndpointsWebhookEndpoint: update,
-};

package/dist/src/stripe-budget.d.ts

@@ -1,55 +0,0 @@
-import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
-/** Rolling window, in ms. Spend older than this is pruned. */
-export declare const STRIPE_BUDGET_WINDOW_MS = 60000;
-/**
- * Weighted units allowed inside one window. 120/60s = 120 reads a minute (2/second) — 2% of
- * Stripe's documented live-mode 100/second and 8% of the 25/second a sandbox key or any single
- * endpoint gets.
- */
-export declare const STRIPE_BUDGET_CEILING = 120;
-/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
-export declare const STRIPE_BUDGET_MAX_RETRY_AFTER_S = 300;
-/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
-export declare const STRIPE_CALL_WEIGHTS: {
-    /** `POST /v1/payouts` — documented at 15 creates/second, and the most irreversible object here. */
-    readonly payout: 5;
-    /** Any other `POST`/`DELETE` — creates charges, refunds, subscriptions, receipt e-mail. */
-    readonly write: 2;
-    /** Reads: list/retrieve. */
-    readonly other: 1;
-};
-/** THE PACK'S DECLARATION — pure data, the only Stripe-specific thing in the whole budget. */
-export declare const STRIPE_RATE_BUDGET: RateBudgetDeclaration;
-/**
- * Price one call. The key is `"<METHOD> <path>"` — Stripe's executor carries filters as separate
- * `params` rather than in the path, so there is no query string to split off here; a `?` is still
- * handled defensively in case a caller inlines one. An unclassified endpoint costs `defaultWeight`.
- */
-export declare function stripeCallWeight(method: string, path: string): number;
-/** Where Stripe's ledger lives. Key-keyed and cwd-independent by default (limits attach to the
- *  account behind the secret key, so a cwd-scoped ledger would hand the same key a fresh allowance
- *  in every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting.
- *
- *  A live key and a test key are different strings, so they get different ledgers — which matches
- *  Stripe, whose live and sandbox limits are separate (100/s vs 25/s). */
-export declare function stripeBudgetPath(opts?: {
-    root?: string;
-    token?: string;
-} | string): string;
-/** Construction options for Stripe's budget. The vendor is fixed; everything else may only TIGHTEN. */
-export type StripeBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
-/**
- * Stripe's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
- * not an alias, so `budget instanceof StripeBudget` in `liveStripeExecute` means "a budget that
- * accounts against STRIPE's ledger under STRIPE's ceiling": another vendor's `RateBudget` (with its
- * own, possibly larger, ceiling) is NOT assignable there.
- */
-export declare class StripeBudget extends RateBudget {
-    constructor(opts?: StripeBudgetOptions);
-}
-/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
- *  which one refused, and `err.kind` says why. */
-export { RateBudgetError as StripeBudgetError } from '@volter/world-core';
-export type { RateBudgetErrorKind as StripeBudgetErrorKind } from '@volter/world-core';
-export type StripeBudgetReservation = RateBudgetReservation;
-export type StripeBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/stripe-budget.js

@@ -1,155 +0,0 @@
-// Stripe's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
-// bindings `liveStripeExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
-// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
-// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
-// header for the full rationale AND for the honest list of what the guard does not guarantee (an
-// injected clock or ledger path still defeats it — it guards carelessness, not malice).
-//
-// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
-// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
-// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
-// that follows it; a BUDGET binds the code that does not. Stripe is the pack where a runaway loop
-// is not merely rude: its writes MOVE MONEY.
-//
-// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
-// Stripe DOES publish scalar limits, so this models the real thing rather than guessing. From
-// https://docs.stripe.com/rate-limits (read 2026-07-26):
-//   • live mode:                    100 requests/second
-//   • sandbox (test mode):           25 requests/second
-//   • an individual endpoint:        25 requests/second unless noted otherwise
-//   • Payouts, create:               15 requests/second
-//   • Subscriptions:                 10 new invoices per subscription per minute
-//   • Payment Intents:            1,000 update requests per PaymentIntent per hour
-// Over the limit: 429, with a `Stripe-Rate-Limited-Reason` header naming which limit was hit.
-//
-// The ceiling is 120 weighted units per 60s — 120 calls a minute, i.e. 2 requests/second at the
-// default weight. That is 2% of the live-mode 100/s and 8% of the tightest general limit (25/s,
-// which is what a sandbox key and any single endpoint get). It is more permissive than the kernel's
-// undeclared fallback (30 calls/min) precisely because those limits are documented and are one to
-// three ORDERS of magnitude higher; without them it would not be.
-//
-// It bounds the 60-second AVERAGE; it does NOT pace (the kernel refuses, it never sleeps — see its
-// header). Stripe's own window is a SECOND, so a tight loop can legitimately fire all 120 inside
-// one second here — 120 req/s, above the sandbox 25/s — and in that shape Stripe's 429 arrives
-// before this ceiling does. The backstop is then the cooldown: the guard reads the 429 off the
-// response and refuses every later call without touching Stripe. The honest claim is therefore
-// "bounds the minute, and converts Stripe's first 429 into a hard stop", not "refuses before Stripe
-// ever 429s". Pacing is the caller's job; this is the ceiling underneath it.
-//
-// ── HOW THE WEIGHTS WERE CHOSEN ─────────────────────────────────────────────────────────────
-//   • `POST` / `DELETE` cost 2. Stripe counts them the same as a read, so this is NOT a published
-//     ratio — it is a judgement call about blast radius: a write creates a charge, a refund, a
-//     subscription or a receipt e-mail, and unlike a read it cannot be taken back. Halving the rate
-//     at which a runaway loop can do that is worth the cost to a legitimate push, which is small
-//     (a push is a handful of writes).
-//   • `POST /v1/payouts` costs 5, because Stripe documents payout creation at 15/second — six times
-//     tighter than live mode's 100/s — and a payout is the single most irreversible object in the
-//     API. At weight 5 at most 24 land in a window: 0.4/s against a documented 15/s.
-import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
-const VENDOR = 'stripe';
-/** Rolling window, in ms. Spend older than this is pruned. */
-export const STRIPE_BUDGET_WINDOW_MS = 60_000;
-/**
- * Weighted units allowed inside one window. 120/60s = 120 reads a minute (2/second) — 2% of
- * Stripe's documented live-mode 100/second and 8% of the 25/second a sandbox key or any single
- * endpoint gets.
- */
-export const STRIPE_BUDGET_CEILING = 120;
-/** Seconds. A `Retry-After` above this means the key is throttled hard — fail loudly, don't sleep. */
-export const STRIPE_BUDGET_MAX_RETRY_AFTER_S = 300;
-/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
-export const STRIPE_CALL_WEIGHTS = {
-    /** `POST /v1/payouts` — documented at 15 creates/second, and the most irreversible object here. */
-    payout: 5,
-    /** Any other `POST`/`DELETE` — creates charges, refunds, subscriptions, receipt e-mail. */
-    write: 2,
-    /** Reads: list/retrieve. */
-    other: 1,
-};
-/** THE PACK'S DECLARATION — pure data, the only Stripe-specific thing in the whole budget. */
-export const STRIPE_RATE_BUDGET = {
-    windowMs: STRIPE_BUDGET_WINDOW_MS,
-    ceiling: STRIPE_BUDGET_CEILING,
-    defaultWeight: STRIPE_CALL_WEIGHTS.other,
-    maxRetryAfterSeconds: STRIPE_BUDGET_MAX_RETRY_AFTER_S,
-    rules: [
-        { match: '^POST /v1/payouts$', weight: STRIPE_CALL_WEIGHTS.payout },
-        { match: '^(POST|DELETE) ', weight: STRIPE_CALL_WEIGHTS.write },
-    ],
-    reason: 'Stripe documents scalar limits (docs.stripe.com/rate-limits, read 2026-07-26): 100 requests/' +
-        'second in live mode, 25/second in sandbox, 25/second for an individual endpoint unless noted, ' +
-        '15 payout creates/second, 10 new invoices per subscription per minute, 1,000 PaymentIntent ' +
-        'updates per intent per hour; over it, 429 with a Stripe-Rate-Limited-Reason header. 120 ' +
-        'weighted units / 60s is 120 reads a minute = 2 requests/second — 2% of live mode and 8% of the ' +
-        "tightest general limit. It is more permissive than the kernel's undeclared fallback (30 calls/" +
-        'min) BECAUSE those documented limits are one to three orders of magnitude higher. POST/DELETE ' +
-        'cost 2 — NOT a published ratio, a judgement call about blast radius: a write creates a charge, ' +
-        'refund or receipt e-mail and cannot be taken back. POST /v1/payouts costs 5 because Stripe ' +
-        'documents payout creation at 15/second, six times tighter than live mode. The window bounds the ' +
-        "60s AVERAGE and does not pace, and Stripe's own window is a SECOND, so an intra-second burst " +
-        "reaches Stripe's limiter first — the 429 cooldown is the backstop for that shape, not this " +
-        'ceiling.',
-};
-// Declared at module load, so merely importing this module (which `stripe-connector.ts` does) is
-// enough to arm the real ceiling. `RateBudget` reads its policy live precisely so this declaration
-// takes effect the moment it lands, and constructing through the subclass below (which imports this
-// module) is what makes the ordering a non-issue in practice.
-declareRateBudget(VENDOR, STRIPE_RATE_BUDGET);
-/**
- * Price one call. The key is `"<METHOD> <path>"` — Stripe's executor carries filters as separate
- * `params` rather than in the path, so there is no query string to split off here; a `?` is still
- * handled defensively in case a caller inlines one. An unclassified endpoint costs `defaultWeight`.
- */
-export function stripeCallWeight(method, path) {
-    const { bare, query } = splitQuery(path);
-    // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
-    // `execute('post', …)` really does issue a POST and must be priced as one.
-    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
-}
-/**
- * `/v1/x?a=1` -> `{ bare: '/v1/x', query: { a: '1' } }`. Rules match the path; `whenQuery*` the query.
- *
- * NORMALIZED, because the anchored rules are otherwise trivially evaded (§9 finding, 2026-07-26):
- * `fetch` upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE
- * that a `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor
- * while most routers treat it as the same endpoint. Both are input variations, not attacks, and
- * either one silently voids the "expensive endpoints are priced up" claim the ceiling rests on.
- */
-function splitQuery(path) {
-    const at = path.indexOf('?');
-    const query = {};
-    if (at !== -1)
-        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
-            query[k] = v;
-    const raw = at === -1 ? path : path.slice(0, at);
-    // Collapse a trailing slash, but never turn the root path into the empty string.
-    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
-    return { bare, query };
-}
-/** Where Stripe's ledger lives. Key-keyed and cwd-independent by default (limits attach to the
- *  account behind the secret key, so a cwd-scoped ledger would hand the same key a fresh allowance
- *  in every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting.
- *
- *  A live key and a test key are different strings, so they get different ledgers — which matches
- *  Stripe, whose live and sandbox limits are separate (100/s vs 25/s). */
-export function stripeBudgetPath(opts = {}) {
-    const o = typeof opts === 'string' ? { root: opts } : opts;
-    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
-    // excess-property check only catches object literals) must not redirect this pack's ledger to
-    // another vendor's file.
-    return rateBudgetPath({ ...o, vendor: VENDOR });
-}
-/**
- * Stripe's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
- * not an alias, so `budget instanceof StripeBudget` in `liveStripeExecute` means "a budget that
- * accounts against STRIPE's ledger under STRIPE's ceiling": another vendor's `RateBudget` (with its
- * own, possibly larger, ceiling) is NOT assignable there.
- */
-export class StripeBudget extends RateBudget {
-    constructor(opts = {}) {
-        super({ ...opts, vendor: VENDOR });
-    }
-}
-/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
- *  which one refused, and `err.kind` says why. */
-export { RateBudgetError as StripeBudgetError } from '@volter/world-core';

package/dist/src/stripe-capabilities.d.ts

@@ -1,3 +0,0 @@
-import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
-export declare const STRIPE_CAPABILITIES: CapabilitySpec[];
-export declare function stripeCapabilities(): Promise<CapabilityReport>;