@volter/twin-stripe 2.0.37 → 3.0.0

package/README.md

@@ -1,213 +1,88 @@
 # @volter/twin-stripe
 
-The **Stripe twin** — a local, spec-correct replica of the Stripe REST API on the
-shared [`@volter/world-core`](../../world-core) kernel. The real `stripe` SDK works against it
-unmodified; it's the QA stack's authoritative local Stripe (it replaced the old
-hand-made in-process mock).
-
-## Surface
-
-- **REST API** (`stripe-twin.ts` → `handleStripeTwinRequest`; HTTP wrapper
-  `stripe-server.ts` → `createStripeTwinServer`): charges, customers,
-  payment_intents, setup_intents, payment_methods, products, prices, invoices,
-  invoiceitems, subscriptions, refunds, coupons, promotion_codes, identity
-  verification sessions, ephemeral_keys, checkout sessions, billing/customer-portal
-  sessions + configurations, and the legacy **Plans** API (`semantics/plans.ts`: a plan is the recurring
-  price it is; plan writes send `plan.created`/`plan.updated`/`plan.deleted`; a deleted plan's price stays
-  readable, inactive, for its existing subscribers).
-- **Hosted pages** (`src/screens/`): Stripe's own pages an application sends a person to, served at their
-  vendor urls — Checkout's payment page (`checkout.stripe.com/c/pay/{id}`: the customer pays, the session
-  completes and `checkout.session.completed` fires), the Customer Portal (`billing.stripe.com/p/session/{id}`),
-  Connect hosted onboarding (`connect.stripe.com/setup/…`), Identity (`verify.stripe.com/start/{id}`) and the
-  Financial Connections bank-linking flow Stripe.js opens.
-- **Stripe.js** (`stripe-js.ts`): `js.stripe.com` serves the client library at `/v3`, `/v3/`, `/v3/stripe.js` and
-  `/<release train>/stripe.js` — the paths the `@stripe/stripe-js` loader loads or accepts — with
-  `redirectToCheckout({ sessionId })` sending the page to the hosted Checkout page; any other member throws,
-  naming itself (`stripe.js.loader`).
-- **Writes** are local transactions (action log); reads are the projection (R3/R5/R18).
-- **Card declines** (`stripe-twin.ts`): Stripe's documented test cards get vendor-faithful
-  outcomes on charge create / PaymentIntent confirm — `4242…4242` (and `pm_card_visa`/`tok_visa`)
-  succeed; `4000…0002`, `4000…9995`, `4000…0069`, `4000…0127`, `4000…0119` (and the matching
-  `pm_card_*`/`tok_*` tokens) return the real `card_error` envelope (HTTP 402) and leave a
-  confirmed PaymentIntent at `requires_payment_method`. Unknown cards succeed. See
-  `_card.declines-test-set-only` in `stripe-known-deviations.json`.
-- **Manual capture** (`semantics/payment-intents.ts`, `semantics/charges.ts`): confirming a `capture_method=manual`
-  intent authorizes an uncaptured charge (`captured: false`, nothing on the balance); capture takes that charge
-  (`charge.captured`; a partial capture releases the rest with no Refund, Stripe's basil change), and an incremental
-  authorization grows its amount. An uncaptured charge is never refunded out of the balance: cancelling a
-  `requires_capture` intent releases the authorization (no Refund; `amount_captured` 0, `refunded` false) and its
-  charge's capture is then refused with `payment_intent_unexpected_state`, a refund of a PaymentIntent's uncaptured
-  charge is refused (cancel the intent, as Stripe's refunds guide says), and a `capture=false` charge's refund releases
-  it, after which its capture is refused with `charge_already_refunded`. An uncaptured charge is refused as a transfer's
-  `source_transaction` (the twin's rule; the docs are silent).
-- **Idempotency keys**: the `Idempotency-Key` header is honored on POST — a replay with the
-  same key returns the stored response without re-applying the write (`_idempotency.stored-per-root`).
-- **Events** (`stripe-events.ts`): fires Stripe `event` objects on write
-  (`payment_intent.succeeded`, `customer.subscription.created`, `invoice.paid`, …). A charge fires the event
-  Stripe sends for it — `charge.succeeded` (made, or authorized under manual capture), `charge.failed` (a declined
-  attempt), `charge.captured` (an authorization captured) — never an invented `charge.created`.
-- **Connect webhooks**: an event of a connected account (a write made with its `Stripe-Account` header, its own
-  `account.updated`, or a row kept on its books such as the automatic payout time makes for it) carries the
-  top-level `account` and reaches only endpoints created with `connect=true`; the platform's reach only the others
-  (`stripe.connect.webhook_scope`, `stripe.connect.event_scope`). `GET /v1/events` and `/v1/events/{id}` answer the
-  acting account's events: with the header that account's, without it the platform's. An event's id is minted once
-  per World (`evt_twin_<n>`) and is the delivered webhook's id and the stored event's alike (`stripe.events.ids`).
-  `world-stripe emit` re-fires a connected account's object with its `account`; it does not yet route it to Connect
-  endpoints only (the kernel's emit seam has no endpoint scope).
-- **Connect OAuth (Standard accounts)** (`src/screens/connect-oauth.tsx`, `src/screens/connect-settings.tsx`;
-  docs.stripe.com/connect/oauth-reference). The platform's **client_id is `ca_twin_self`** in every World (a test
-  client_id; the platform account is `acct_twin_self`), shown on the Dashboard's Connect OAuth settings page,
-  `dashboard.stripe.com/settings/connect/onboarding-options/oauth` (also `/settings/connect` and the `/test/…` link),
-  in `<code data-testid="connect-client-id">`. OAuth starts **off**: a runner POSTs that page as a browser does,
-  `oauth_enabled=on&redirect_uris=<one per line>` (303 to `?saved=1`), and the saved URIs are listed in
-  `data-testid="connect-redirect-uri"` items. `GET connect.stripe.com/oauth/authorize` checks client_id (unknown:
-  `invalid_client`), OAuth on, `redirect_uri` (must exactly match a registered one; absent: the first; http and
-  localhost allowed, as Stripe's test client_id allows), `response_type=code` and `scope` (`read_write` | `read_only`,
-  default `read_only`), each refusal a 400 JSON `{error, error_description, state}` as the reference says (no
-  redirect). The page offers the test-mode **Skip this form**, which creates a new Standard account (controller type
-  `account`, prefilled from valid `stripe_user[...]` values, charges and payouts enabled) and redirects with
-  `scope`, `code` and `state`, and **Deny access**, which redirects with
-  `error=access_denied&error_description=The%20user%20denied%20your%20request&state=…`. `POST
-  connect.stripe.com/oauth/token` (the secret key as Bearer, Basic or `client_secret`) exchanges a code once, within 5
-  minutes, into `{access_token, livemode, refresh_token, scope, stripe_publishable_key, stripe_user_id, token_type}`;
-  a reused code is `invalid_grant` and revokes the connection; `refresh_token` grants an equal or lesser scope.
-  `POST connect.stripe.com/oauth/deauthorize` answers `{stripe_user_id}`, after which the Stripe-Account header (and
-  `/v1/accounts/{id}`) for that account is refused 403 `account_invalid`. `account.application.authorized` /
-  `.deauthorized` reach Connect endpoints with the account; once revoked, `GET /v1/accounts` no longer lists it and its own events (payouts, balance) stop reaching the platform. The token answer's
-  deprecated `access_token` and `stripe_publishable_key` act as the connected account (as the Stripe-Account header
-  does, as Bearer or Basic; `GET /v1/account` then answers it), a token replaced by a refresh or revoked is a 401 invalid API key, and it is never the platform's key at `/oauth/token` or `/oauth/deauthorize`. The
-  application's own setting of its client_id (Cal.com's `client_id` app key, `STRIPE_CLIENT_ID`) is the runner's to
-  set to `ca_twin_self`; the World does not provision it. Where the docs stop, the twin decides (the file header lists
-  each): connecting an existing Stripe account, the full account application form, and holding a `read_only`
-  connection to reads are not modelled (todos in `stripe-capabilities.ts`).
-- **Signing secrets in a World**: Stripe mints an endpoint's `secret`; in a World the app's env is the World's, so an
-  endpoint is given the World's value, which the app already verifies with: `STRIPE_WEBHOOK_SECRET` (or
-  `STRIPE_WEBHOOK_SIGNING_SECRET`, `STRIPE_ENDPOINT_SECRET`, `STRIPE_WEBHOOK_SECRET_KEY`,
-  `NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET`), and for a `connect=true` endpoint `STRIPE_CONNECT_WEBHOOK_SECRET` (or
-  `STRIPE_WEBHOOK_SECRET_CONNECT`, `STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET`) first. With none set the twin mints
-  `whsec_twin_<id>`. Where Stripe stops and the twin decides: Stripe lets no one choose a secret.
-- **Conformance** (`stripe-conformance.ts`): field name + type checked vs Stripe's
-  real OpenAPI (standing gate).
-- **UI mirror** (`stripe-mirror-ui.ts`): a Stripe-dashboard-style React app over the
-  twin's own REST API.
-
-## CLI
+A local Stripe: the REST API the unmodified `stripe` SDK calls (`https://api.stripe.com/v1`), the hosted pages an
+application sends a person through, and Stripe.js, over one state.
+
+A Protocol 3 pack ([architecture](../../../docs/contributing/architecture.md), "Protocol 3"). Its surface is generated
+from Stripe's published OpenAPI document (`spec/`). The derived core serves plain reads, writes and deletes. Handlers
+are in `src/semantics/<family>.ts`, the state machines in `src/semantics/states.ts`, and Stripe's own computation
+(money and declines, billing, the ledger, the API versions) in `src/engine/`.
 
 ```bash
-world-stripe serve [--read-only] [--port N] [--root DIR]
-world-stripe mirror [--port N] [--root DIR]
-world-stripe conformance [--fields FILE] [--root DIR]
+world-stripe serve [--port N] [--root DIR] [--read-only]
 ```
 
-`serve` defaults to `simulator` (the stack uses the twin as a writable Stripe).
-Point the real `stripe` SDK at it with `{ host, port, protocol: 'http' }`.
-
-## Interaction surfaces
-
-1. **SDK/API** — *zero edits (preferred):* `STRIPE_TWIN_URL=http://127.0.0.1:PORT node --require @volter/world-core/inject your-app` redirects the real `stripe` SDK from `api.stripe.com` to the twin (`cookbook/zero-edit-inject`). For browser routing, follow [run a full stack](../../../docs/guides/run-a-full-stack.md). *Or* override directly: `new Stripe(key, { host: '127.0.0.1', port: PORT, protocol: 'http' })`.
-2. **API + CLI** — run the twin in a World and inspect it with `volter world log` and `diff`. Use the [deployment guide](../../../docs/guides/deploy-from-a-shared-world.md) for changeset review and deployment.
-3. **Read-only** — `world-stripe serve --read-only`: unlimited local reads, no rate limits; writes refuse like Stripe (4xx).
-4. **UI mirror** — `world-stripe mirror` renders a Stripe-dashboard-style view of the twin's state.
-5. **Time's events** — `POST /_twin/drain` sends what World time produced since the last drain: `balance.available`
-   to each account whose settled funds added to its balance (never for negative transactions alone), `payout.paid` for
-   each payout that arrived, a connected account's with its `account` to its Connect endpoints
-   (`stripe.events.time_drain`). A read sees time's moves without it; a runner's drainer calls it so the events
-   arrive, as the qstash and vercel twins' drain doors do.
-   Test mode keeps live timing except where Stripe documents otherwise: a card charge's funds are pending two days,
-   except the cards that bypass the pending balance (4000000000000077, 4000003720000278, `pm_card_bypassPending*`,
-   `tok_bypassPending*`, and a PaymentMethod saved from one) and US bank account debits ("Test transactions settle
-   instantly"), whose funds, and a `source_transaction` transfer's from them, are available at once; every credit
-   available at once is sent as `balance.available` at the next drain; a test payout is paid at its `arrival_date`
-   (`stripe.balance.test_mode_bypass_pending`; sources in `src/semantics/ledger.ts`).
-
-(See Getting Started → "Twin interaction surfaces".)
-
-Stable on the twin rubric: fidelity, read/write/fork, sync, observability, event emission, and conformance are tracked with explicit coverage gaps.
-
-## Coverage
-
-Goal: **honest, explicitly tracked coverage of Stripe's core feature surface.** Every capability
-is either done or a tracked todo; anything not done is a gap to close.
-
-**Done** — core resources: **customers**, **charges**, **payment_intents** (+ confirm),
-**setup_intents** (+ confirm), **payment_methods** (+ detach), **subscriptions** (create/
-update/cancel), **prices**, **products**, **invoices** (+ finalize/pay/void), **invoiceitems**,
-**refunds**, **disputes** (+ update/close), **payouts** (+ cancel), **balance_transactions**,
-**balance** (synthesized from the ledger), **events** (Events API list/retrieve),
-**Checkout Sessions** (create/retrieve/list/`line_items`/expire + modeled completion that
-creates+links a payment_intent/subscription/setup_intent; `amount_total` computed from
-line_items), **Customer Portal** (`billing_portal` sessions + configurations create/retrieve/
-list/update), **Connect** (connected **accounts** create/retrieve/list/update/delete +
-`login_links`, and **transfers** platform→connected-account create/retrieve/list filtered by
-destination; a new account starts un-onboarded with charges/payouts disabled + a `requirements`
-hash; a transfer's `source_transaction` waives the balance check only while its charge is unsettled,
-takes the charge's `transfer_group` or writes `group_<payment intent>` onto both, and counts reversals
-back as room; connected-account balances, payouts (manual and automatic) and payout reversal, top-ups,
-account sessions, persons, external accounts, application fees, hosted onboarding and Connect OAuth for Standard accounts), plus **ephemeral_keys**, **identity verification_sessions**, **file_links**
-(synthesized) and **coupons**/**promotion_codes** (retrieve/list, seed-only). Cursor pagination
-(`limit`/`starting_after`/`ending_before` + `has_more`); per-resource list filters; `expand[]`
-on the modeled paths; vendor-faithful **test-card declines** (`4242…` succeeds; documented
-decline PANs + `pm_card_*`/`tok_*` tokens return the real `card_error` 402); **idempotency keys**
-(`Idempotency-Key` replay, no re-write); **events/webhooks** (`stripe-events.ts`); spec
-**conformance** gate; **UI mirror** (rung-5 ✅, `client/stripe-mirror.tsx` + structure check);
-**connector** pull (customers + subscriptions) + push (create/update/cancel/confirm/detach/
-finalize/pay/void/close to the real REST surface).
-
-This cycle added: **ACH/SEPA micro-deposit verification** (`payment_intents`/`setup_intents`
-`/verify_microdeposits` — confirm with `pm_us_bank_account` → `requires_action` with a
-`verify_with_microdeposits` next_action, then the 32/45 amounts or `SM11AA` descriptor →
-`succeeded`), **Customer.list_payment_methods** (`/v1/customers/:id/payment_methods`),
-**subscription items** CRUD (create/retrieve/list/update/delete, kept in sync with the parent
-sub's `items` list), **subscriptions/invoices search**, **invoice line items**
-(`/lines` + `add_lines`/`update_lines`/`remove_lines` with recomputed totals), **invoice
-edge-action gating** (finalize/pay/mark_uncollectible/void state machine), **Tax transactions**
-(`create_from_calculation` + `create_reversal` with negated lines), **quote** cancel-from-draft/
-open lifecycle gates, **customer + subscription discount delete**, **promotion-code update**
-(active toggle), **charge fraud-marking** (`fraud_details[user_report]`), and the **Radar**
-family — **Reviews** (`/approve`), **Value Lists** (+ items), **Rules** — plus a **Radar
-dashboard screen** in the UI mirror.
-
-**Issuing** (modeled) — cardholders/cards/authorizations/transactions/disputes + test helpers
-(present authorization, capture, force capture, fund_balance), including the **real-time
-authorization leg**: an endpoint enrolled for `issuing_authorization.request` receives the
-signed request event **synchronously** at present time and its JSON response
-(`{approved, amount?}`) decides the authorization within Stripe's 2-second window (timeout →
-declined `webhook_timeout`, invalid response → `webhook_error`); **spending_controls**
-(category/country allow+block lists, per_authorization/all_time/calendar-window spending
-limits) are enforced ahead of the webhook with the vendor's `spending_controls` decline
-reason; and **captures debit the issuing balance** (`balance_transaction` type
-`issuing_transaction`, `balance_type: 'issuing'`, served in `GET /v1/balance`'s `issuing`
-section). Remaining issuing gaps (authorization holds, expire/increment/reverse test
-helpers) are tracked todos in `stripe-capabilities.ts`. **Terminal**
-(locations/readers/connection tokens + process_payment_intent) is likewise modeled — the old
-"Planned" listing for both families was stale.
-
-Also modelled: **Treasury** financial accounts and money movement, **Climate** orders,
-**Financial Connections** sessions/accounts/transactions, **Entitlements**, **Billing** meters,
-credit grants and usage alerts, **Reporting** report runs, and the legacy **Sources** API.
-
-**Planned** (known-missing, will do) — **Sigma scheduled query runs** (`GET /v1/sigma/scheduled_query_runs`
-list + retrieve, with the run object's status/result-file lifecycle), Treasury financial addresses and
-reversals, Financial Connections refresh, the Issuing gaps above, connector pulls of payment methods and
-setup intents, and additional list endpoints/filters as needed. (See `stripe-capabilities.ts` for the full
-honest todo list — every entry is a tracked gap.)
-
-## Rate budget — the fail-closed backstop on live calls
-
-`liveStripeExecute` is the **one place** this pack issues a live request, so every call it makes is charged
-against a persistent, fail-closed spend ledger **before** the request goes out. Past the ceiling, or
-while a `Retry-After`/429 cooldown is armed, it **throws instead of calling**. The ledger is keyed by
-vendor and a hash of the credential (limits are per credential, so it is deliberately *not*
-cwd-scoped) and persists across processes, so a fresh process does not get a fresh allowance; a
-corrupt ledger counts as a **full** window rather than zero spend. There is no option to disable it,
-and no value you can pass for `budget` that yields an unguarded client — an injected budget is
-validated by *method identity*, so a subclass or a `Proxy` that replaces `checkBudget` is refused.
-
-The declared numbers: **120 weighted units / 60s** = 2 requests/second — 2% of Stripe's documented 100/s live mode and 8% of the 25/s a sandbox key or any single endpoint gets. `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) and `POST /v1/payouts` costs 5 (documented at 15 creates/second). Stripe's own window is a **second** while this one is a minute, so an intra-second burst reaches Stripe's limiter first; the 429 cooldown is the backstop for that shape.
-
-The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
-`packages/world-core/src/rateBudget.ts`); what lives here in [`src/stripe-budget.ts`](src/stripe-budget.ts) is this vendor's
-**declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
-the vendor-bound `StripeBudget`. The rule is ratified as
-[../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and the kernel module's header documents what the
-guard does *not* guarantee — read that before trusting it.
+## What it models
+
+The calls the applications make (`journeys/demand.json`: Dub, Twenty, Inbox Zero, Rallly, cal.com and Ponder, and the
+frontends' Stripe.js):
+
+- **Customers**: created, updated, searched, deleted; their balance, payment methods and entitlements.
+- **Catalog**: products (with search) and prices, coupons and promotion codes.
+- **Checkout Sessions** and the customer portal (sessions and configurations).
+- **Subscriptions**: their items and schedules, previews, updates, searches and cancellations.
+- **Invoices**: invoice items, finalize, send, pay, void, delete and lines.
+- **Intents**: payment and setup intents (confirmed by Stripe.js with the publishable key and the client secret),
+  payment methods (attach, detach), refunds, charges, disputes.
+- **Test clocks**, billing meters, the Apps secret store.
+- **Connect**: Express accounts, account links and login links, external accounts, transfers, payouts, the balance and
+  its transactions.
+
+**Keys.** The platform's secret and publishable keys, and its webhook secret, are issued by the credential door and
+held by their SHA-256. A request with no key, or with one Stripe never issued, is refused 401. A connected account's
+OAuth key acts as that account.
+
+**The gap.** Every other operation answers Stripe's unknown-URL 404: Issuing, Terminal, Treasury, Tax, Quotes, credit
+notes, reporting, identity, sources, plans, payment links, and the webhook endpoints and keys APIs.
+
+## Events
+
+Every write Stripe reports sends its event (`payment_intent.succeeded`, `customer.subscription.created`,
+`invoice.paid`, …; a charge sends `charge.succeeded`, `charge.failed` or `charge.captured`, never an invented
+`charge.created`), declared as data the kernel renders, stores, signs (`Stripe-Signature: t=…,v1=…`, which the
+SDK's `constructEvent` verifies) and delivers to the account's enabled webhook endpoints whose `enabled_events` take it
+(`*`, `<family>.*` or the type). Each event is rendered in the writing request's API version.
+
+- **Connect**: an event of a connected account (a write made with its `Stripe-Account` header, its own
+  `account.updated`, or a row kept on its books, such as the payout time makes for it) carries the top-level `account`
+  and reaches only endpoints created with `connect=true`; the platform's reach only the others.
+- **Signing secrets in a World**: the credential door issues the application its keys and two signing secrets, its
+  account's (`STRIPE_WEBHOOK_SECRET` and the other names an application reads it by) and its Connect endpoint's
+  (`STRIPE_CONNECT_WEBHOOK_SECRET`), the same on every boot; an endpoint made on the Webhooks page (a door) is signed
+  with the one of its kind. The twin reads no env.
+
+## Screens
+
+Stripe's own pages, at their vendor urls (`src/screens/`):
+
+- **Checkout** (`checkout.stripe.com/c/pay/{session}`): the customer pays; the session completes and
+  `checkout.session.completed` fires.
+- **Customer portal** (`billing.stripe.com/p/session/{session}`): cancel or renew a plan, update the card, pay an
+  open invoice.
+- **Connect onboarding** (`connect.stripe.com/setup/…`): an Account Link's hosted onboarding.
+- **Connect OAuth** (`connect.stripe.com/oauth/authorize`, `/oauth/token`, `/oauth/deauthorize`; Standard accounts,
+  docs.stripe.com/connect/oauth-reference). The platform's client_id is `ca_twin_self` in every World (a test
+  client_id; the platform account is `acct_twin_self`), shown on the Dashboard's Connect OAuth settings page in
+  `<code data-testid="connect-client-id">`. OAuth starts off: a runner POSTs that page as a browser does,
+  `oauth_enabled=on&redirect_uris=<one per line>`. The authorize page offers the test-mode **Skip this form** (a new
+  Standard account, connected) and **Deny access**; the token endpoint exchanges a code once, within 5 minutes (a
+  reused code revokes the connection), and refreshes to an equal or lesser scope; after a deauthorization the
+  account's `Stripe-Account` header is refused 403 `account_invalid`. The deprecated `access_token` and
+  `stripe_publishable_key` act as the connected account. Not modelled: connecting an existing Stripe account, the full
+  account application, holding a `read_only` connection to reads.
+- **Stripe.js** (`js.stripe.com/v3/`, `/v3/stripe.js`, `/<release train>/stripe.js`): `redirectToCheckout({ sessionId })`
+  goes to the hosted Checkout page; any other member
+  throws, naming itself.
+- **Dashboard** (`dashboard.stripe.com/settings/public`, `/settings/connect/onboarding-options/oauth`): Public details
+  (the business name Checkout and the portal show) and the Connect OAuth settings.
+
+## Doors
+
+The World's hands where Stripe's API has no act (`src/semantics/doors.ts`), refused on a read-only twin:
+
+- `POST /_twin/app-credentials`: the platform's keys and webhook secret, as the runtime issues them to a World's
+  applications.
+- `POST /_twin/webhook-endpoints {url, events, connect?}`: an endpoint added on the Dashboard's Webhooks page.
+- `POST /_twin/account {settings?, business_profile?, …}`: the platform's own account settings, as the Dashboard
+  changes them.
+- `POST /_twin/drain`: time's events, sent when a runner drives them (`payout.paid`, `balance.available`).

package/dist/generated/pack-facts.json

@@ -0,0 +1,94 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "stripe": {
+      "adoption": {
+        "pypi": [
+          "stripe"
+        ],
+        "sdks": [
+          "stripe"
+        ],
+        "envStems": [
+          "STRIPE",
+          "NEXTPRIVATESTRIPE"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "api.stripe.com"
+        },
+        {
+          "host": "checkout.stripe.com",
+          "pathPattern": "^/c/pay/"
+        },
+        {
+          "host": "billing.stripe.com",
+          "pathPattern": "^/p/session/"
+        },
+        {
+          "host": "connect.stripe.com",
+          "pathPattern": "^/setup/|^/oauth/(authorize|token|deauthorize)/?$"
+        },
+        {
+          "host": "dashboard.stripe.com",
+          "pathPattern": "^/settings/public/?$|^/(test/)?settings/connect(/onboarding-options/oauth)?/?$"
+        },
+        {
+          "host": "verify.stripe.com",
+          "pathPattern": "^/start/"
+        },
+        {
+          "host": "js.stripe.com",
+          "pathPattern": "^/v3/financial-connections/|^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "charge",
+        "customer",
+        "payment_intent",
+        "setup_intent",
+        "payment_method",
+        "subscription",
+        "price",
+        "product",
+        "invoice",
+        "invoiceitem",
+        "refund",
+        "event"
+      ],
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "STRIPE_SECRET_KEY": "secret_key",
+          "STRIPE_API_KEY": "secret_key",
+          "STRIPE_PRIVATE_KEY": "secret_key",
+          "BILLING_STRIPE_API_KEY": "secret_key",
+          "STRIPE_PUBLISHABLE_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_PUBLIC_KEY": "publishable_key",
+          "NEXT_PUBLIC_STRIPE_KEY": "publishable_key",
+          "STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "STRIPE_WEBHOOK_SIGNING_SECRET": "webhook_secret",
+          "STRIPE_ENDPOINT_SECRET": "webhook_secret",
+          "STRIPE_WEBHOOK_SECRET_KEY": "webhook_secret",
+          "NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "BILLING_STRIPE_WEBHOOK_SECRET": "webhook_secret",
+          "STRIPE_CONNECT_WEBHOOK_SECRET": "connect_webhook_secret",
+          "STRIPE_WEBHOOK_SECRET_CONNECT": "connect_webhook_secret",
+          "STRIPE_CONNECT_WEBHOOK_SIGNING_SECRET": "connect_webhook_secret"
+        }
+      },
+      "serveExport": "createStripeTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/dist/spec/SOURCE.md

@@ -0,0 +1,14 @@
+# stripe spec — provenance
+
+- **File:** `openapi.json.gz`, gzip of Stripe's published OpenAPI document.
+- **Upstream:** https://github.com/stripe/openapi, `openapi/spec3.json` on `master`.
+- **Spec version:** `2026-09-30.endive` (`info.version`).
+- **SHA-256 of the uncompressed document:** `6b4680299e7b7743811c41537e828b0eae363a11cea44441511013b55e52f7ad`.
+- **Read by:** `bun scripts/derive-pack.ts stripe`, which writes `../src/generated/surface.gen.json`.
+
+The pack serves this document's version (`SERVED_VERSION` in `src/stripe-version.ts`).
+
+- **Published examples:** `fixtures3.json.gz`, gzip of Stripe's `openapi/fixtures3.json` (one sample object per resource,
+  the objects Stripe's API reference shows), from commit `0d98342fc985dc7710a44be25e8528dd8e099bc2` (2026-09-23).
+  SHA-256 of the uncompressed file: `e6822f7ee6fd71bdde6228537368aafcfb7191109340fe119d9aca27c6e9396d`.
+  **Read by:** `bun scripts/vendor-examples.ts stripe`.

package/dist/spec/patches.json

@@ -0,0 +1,34 @@
+{
+  "patches": [
+    {
+      "op": "add",
+      "path": "/components/schemas/invoiceitem/properties/net_amount/nullable",
+      "value": true,
+      "why": "The spec types an invoice item's net_amount as a bare integer, yet its own description says the field answers null for every discountable item, so the field is nullable.",
+      "source": {
+        "spec": "/components/schemas/invoiceitem/properties/net_amount/description",
+        "quote": "This field is `null` for `discountable=true` items."
+      }
+    },
+    {
+      "op": "add",
+      "path": "/components/schemas/file/properties/purpose/enum/-",
+      "value": "issuing_logo",
+      "why": "The spec's personalization-design card_logo says \"Must have a `purpose` value of `issuing_logo`\", yet neither the File object's purpose nor the file upload's purpose lists it; Stripe's own guide uploads the logo with that purpose (https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code), so issuing_logo is a purpose a file has.",
+      "source": {
+        "url": "https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code",
+        "quote": "Use the [Files API](https://docs.stripe.com/api/files/create.md) to upload a .PNG file of your card logo, and specify the purpose as `issuing_logo`."
+      }
+    },
+    {
+      "op": "add",
+      "path": "/paths/~1v1~1files/post/requestBody/content/multipart~1form-data/schema/properties/purpose/enum/-",
+      "value": "issuing_logo",
+      "why": "The spec's personalization-design card_logo says \"Must have a `purpose` value of `issuing_logo`\", yet neither the File object's purpose nor the file upload's purpose lists it; Stripe's own guide uploads the logo with that purpose (https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code), so issuing_logo is a purpose a file has.",
+      "source": {
+        "url": "https://docs.stripe.com/issuing/cards/physical/create-design.md?testing-method=with-code",
+        "quote": "Use the [Files API](https://docs.stripe.com/api/files/create.md) to upload a .PNG file of your card logo, and specify the purpose as `issuing_logo`."
+      }
+    }
+  ]
+}