@volter/twin-stripe 0.1.2 → 2.0.0

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

@@ -0,0 +1,55 @@
+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

@@ -0,0 +1,155 @@
+// 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

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