@volter/twin-stripe 2.0.38 → 3.0.1

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>;