@volter/twin-stripe 2.0.37 → 3.0.0

package/src/stripe-js.ts

@@ -1,70 +0,0 @@
-// STRIPE.JS — the client library an application's page loads from js.stripe.com (docs/contributing/architecture.md,
-// "Screens": a widget the vendor ships into the application's own page "is not a screen: it is a client library,
-// twinned from its published types as an SDK surface is"). Written from @stripe/stripe-js's published loader and types
-// (7.x: dist/index.mjs, dist/stripe-js/stripe.d.ts, dist/stripe-js/hosted-checkout.d.ts), nothing of Stripe's script
-// copied:
-//   - the loader injects https://js.stripe.com/<release train>/stripe.js (or /v3/), and accepts a script already on the
-//     page whose src matches `/^https:\/\/js\.stripe\.com\/(v3|[a-z]+)\/stripe\.js(\?.*)?$/` (so /v3/stripe.js too);
-//     it resolves `window.Stripe`, reads `Stripe.version` (3 is the v3 URL, otherwise the train's name) and calls the
-//     instance's `_registerWrapper` when it has one;
-//   - `stripe.redirectToCheckout({ sessionId })` sends the customer to that Checkout Session's page (hosted-checkout.d.ts,
-//     RedirectToCheckoutServerOptions), which this twin serves at checkout.stripe.com/c/pay/{id} (screens/checkout.tsx),
-//     and its promise settles only on failure (`Promise<never | {error}>`);
-//   - `stripe.collectFinancialConnectionsAccounts({ clientSecret })` loads the Financial Connections authentication
-//     flow for the session whose client_secret it is (stripe.d.ts; docs.stripe.com/js/financial_connections/
-//     collect_financial_connections_accounts: "it will load the Authentication Flow, an on-page modal UI"). Where the
-//     twin decides: it navigates to the flow's page, js.stripe.com/v3/financial-connections/{client_secret}
-//     (screens/financial-connections.tsx), instead of a modal, so its promise does not settle; the flow returns the
-//     holder to the session's return_url, where the application reads the session's accounts.
-// Demand: Dub's upgrade button (apps/web/ui/workspaces/upgrade-plan-button.tsx) creates a session on its server and
-// calls redirectToCheckout. Every other member of the library throws, naming itself, when called: an application
-// reaching one finds the gap instead of a silent no-op.
-
-/** The release train a script path names: `/v3`, `/v3/` or `/v3/stripe.js` → 3, `/<train>/stripe.js` → the train. */
-export function stripeJsTrain(pathname: string): 3 | string | undefined {
-  if (/^\/v3(\/|\/stripe\.js)?$/.test(pathname)) return 3;
-  return /^\/([a-z]+)\/stripe\.js$/.exec(pathname)?.[1];
-}
-
-function script(version: 3 | string): string {
-  return `(function () {
-  var version = ${JSON.stringify(version)};
-  function gap(name) {
-    return function () { throw new Error("Stripe.js (Volter twin): stripe." + name + " is not modelled by this twin yet"); };
-  }
-  function Stripe(publishableKey) {
-    if (typeof publishableKey !== "string" || !publishableKey) throw new Error("Stripe.js (Volter twin): Stripe() needs a publishable key");
-    var known = {
-      _registerWrapper: function () {},
-      redirectToCheckout: function (options) {
-        if (!options || typeof options.sessionId !== "string" || !options.sessionId) return gap("redirectToCheckout without a sessionId")();
-        window.location.assign("https://checkout.stripe.com/c/pay/" + encodeURIComponent(options.sessionId));
-        return new Promise(function () {});
-      },
-      collectFinancialConnectionsAccounts: function (options) {
-        if (!options || typeof options.clientSecret !== "string" || !options.clientSecret) return gap("collectFinancialConnectionsAccounts without a clientSecret")();
-        window.location.assign("https://js.stripe.com/v3/financial-connections/" + encodeURIComponent(options.clientSecret));
-        return new Promise(function () {});
-      }
-    };
-    return new Proxy(known, {
-      get: function (target, name) {
-        if (name in target) return target[name];
-        if (typeof name === "symbol" || name === "then") return undefined;
-        return gap(String(name));
-      }
-    });
-  }
-  Stripe.version = version;
-  window.Stripe = Stripe;
-})();
-`;
-}
-
-/** js.stripe.com's script for a GET of its path, or undefined for any other request. */
-export function stripeJs(request: Request): Response | undefined {
-  if (request.method !== 'GET') return undefined;
-  const train = stripeJsTrain(new URL(request.url).pathname);
-  if (train === undefined) return undefined;
-  return new Response(script(train), { headers: { 'content-type': 'application/javascript; charset=utf-8', 'access-control-allow-origin': '*' } });
-}

package/src/stripe-mirror-ui.ts

@@ -1,90 +0,0 @@
-// The Stripe Dashboard (manifest screen `dashboard`, dashboard.stripe.com/test/{section}): a React app
-// (Bun-bundled) served beside the twin. A PURE FRONTEND (runtime contract R3): this module is the shell, its
-// assets and one listener that mounts the pack's OWN fetch adapter beside them. It imports no handler and no
-// twin internals; the client reads and writes only through Stripe's API (`/v1/...`, client/dashboard-api.ts),
-// so it renders a twin or a real account's test data unchanged, pointed at any origin by configuration.
-import { readFile } from 'node:fs/promises';
-import { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
-import { serveHttp } from '@volter/world-core';
-import { createStripeTwinFetch } from './stripe-server.ts';
-
-const CLIENT_ENTRY = () => filePathOf(new URL('../client/stripe-mirror.tsx', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => filePathOf(new URL('../client/stripe-mirror.css', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-
-// ---------------------------------------------------------------------------
-// Pure, dependency-free render/format/resolution helpers.
-//
-// These are intentionally framework-agnostic (plain data in → plain data out) so
-// they can be unit-tested in isolation AND imported by the React/TSX client
-// (Bun tree-shakes the server-only exports below out of the browser bundle).
-// Keep them free of any `@volter/world-core`/`Bun`/twin-adapter usage.
-// ---------------------------------------------------------------------------
-
-export * from './stripe-shared.ts';
-import { flattenStripeValue, resolveCrossRefs, type CrossRefs, type FlatLine, type StripeRow } from './stripe-shared.ts';
-void flattenStripeValue; void resolveCrossRefs;
-
-const APP_SHELL = `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<base href="/"><title>Dashboard – Stripe</title><link rel="stylesheet" href="assets/styles.css"></head>
-<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
-let clientBundle: Promise<string> | null = null;
-
-/** Build the React/TSX dashboard client to browser JS (Bun bundles TSX); cached. */
-export function buildStripeMirrorClient(): Promise<string> {
-  if (!clientBundle) {
-    clientBundle = bundleClient(CLIENT_ENTRY())
-      .catch((error) => { clientBundle = null; throw error; });
-  }
-  return clientBundle;
-}
-
-/** Serve the Stripe Dashboard (React app) with the twin's own fetch adapter mounted beside it. */
-export async function createStripeMirrorServer(options: { root?: string; port?: number }): Promise<{ port: number; stop: () => void }> {
-  const twin = createStripeTwinFetch(options);
-  const server = await serveHttp({
-    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
-    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
-    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
-    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
-    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
-    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
-    // on loopback, so the verify's fetches deterministically reach THIS server.
-    hostname: '127.0.0.1',
-    port: options.port ?? 0,
-    idleTimeout: 60,
-    async fetch(request) {
-      const url = new URL(request.url);
-      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
-        try { return new Response(await buildStripeMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
-        catch (error) { return new Response(String(error), { status: 500 }); }
-      }
-      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
-        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
-      }
-      // the Dashboard's own paths (/test/payments, /test/customers/cus_…) are the app; `/` opens Home
-      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '' || url.pathname === '/test' || url.pathname.startsWith('/test/'))) {
-        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
-      }
-      // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the React client fetches
-      // the vendor's real paths (/v1/<collection>) and this is the same closure
-      // `createStripeTwinServer` mounts, so there is exactly ONE serving code path — the `/twin`
-      // manifest door, the form-encoded body passed through byte-for-byte, the Idempotency-Key /
-      // Stripe-Version / Stripe-Account threading, the `request-id` response header, the world
-      // clock and an honorable `readOnly` all come from it, and the mirror port cannot drift from
-      // the API port.
-      return twin(request);
-    },
-  });
-  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
-}
-
-/** The app-shell HTML (pure, for tests). The Dashboard itself is the React client. */
-export function stripeMirrorHtml(): string {
-  return APP_SHELL;
-}
-
-/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
-export function stripeMirrorStyles(): Promise<string> {
-  return readFile(CLIENT_CSS(), 'utf8');
-}

package/src/stripe-perform-harness.ts

@@ -1,29 +0,0 @@
-// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). The kernel's loop
-// (`performEntries`) needs a bound root and a sealed credential a unit test does not have; this is the same
-// shape without one — the same `deployableEntries`, the pack's own push, the same `confirmAction`. Not on
-// the serve path, not exported from the pack.
-import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
-import { INTERNAL_SUBJECT_TYPES, isPushable, pushStripeAction, type StripeExecute } from './stripe-connector.ts';
-
-export async function performPending(
-  execute: StripeExecute,
-  opts: { root?: string; occurredAt: string },
-): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
-  const confirmed: string[] = [];
-  const externalIds: Record<string, string> = {};
-  for (const entry of deployableEntries('stripe', opts.root)) {
-    const op = entry.operation ?? `${entry.subject.type}.update`;
-    // the twin's own records — the recorded event envelopes and the idempotency bookkeeping — are local
-    // state and are never sent
-    if (INTERNAL_SUBJECT_TYPES.has(entry.subject.type) || !isPushable(op)) continue;
-    const { externalId } = await pushStripeAction(execute, { operation: op, subject: entry.subject, fields: entry.fields ?? {} });
-    confirmAction({
-      service: 'stripe', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
-      occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
-      ...(opts.root !== undefined ? { root: opts.root } : {}),
-    });
-    confirmed.push(entry.id);
-    externalIds[entry.id] = externalId;
-  }
-  return { pushed: confirmed.length, confirmed, externalIds };
-}

package/src/stripe-server.ts

@@ -1,393 +0,0 @@
-// Stripe twin HTTP server — serve the full Stripe twin handler over HTTP so the
-// real `stripe` SDK ({host,port,protocol}) works unmodified (R1), or route the QA
-// backend sandbox's api.stripe.com interception at it. Form-encoded bodies (what
-// the SDK sends) pass through to the handler. Writable by default (the local stack
-// uses the twin as its authoritative Stripe); pass readOnly to reject writes (R4).
-//
-// The surface is a plain `fetch` (`createStripeTwinFetch`) and the SERVER is one line of
-// `Bun.serve` around it — see that factory's docstring for why (a serverless entry has no
-// port to bind, so it mounts the fetch in-process).
-import { bindSemantics, coreFor, createDerivedFetch, crossCutting, derivedRequestScopes, readParams, runAsVendorMove, runWithRequestTrace, semanticsContext, serveHttp, vendorError, type DerivedCall, type DerivedFetch } from '@volter/world-core';
-import { stripeCheckoutFlow } from './screens/checkout.tsx';
-import { stripeJs } from './stripe-js.ts';
-import { stripeFinancialConnectionsFlow } from './screens/financial-connections.tsx';
-import { stripeIdentityFlow } from './screens/identity.tsx';
-import { stripeOnboardingFlow } from './screens/onboarding.tsx';
-import { stripePortalFlow } from './screens/portal.tsx';
-import { stripePublicDetailsFlow } from './screens/public-details.tsx';
-import { connectionRevoked, oauthKeyAccount, redactKey, stripeConnectOAuthFlow } from './screens/connect-oauth.tsx';
-import { stripeConnectSettingsFlow } from './screens/connect-settings.tsx';
-import surface from './generated/surface.gen.json' with { type: 'json' };
-import { manifest } from './manifest.ts';
-import { appsSecrets } from './semantics/apps-secrets.ts';
-import { balances } from './semantics/balance.ts';
-import { billing } from './semantics/billing.ts';
-import { charges } from './semantics/charges.ts';
-import { checkout } from './semantics/checkout.ts';
-import { connect } from './semantics/connect.ts';
-import { coupons } from './semantics/coupons.ts';
-import { creditNotes } from './semantics/credit-notes.ts';
-import { customers } from './semantics/customers.ts';
-import { disputes } from './semantics/disputes.ts';
-import { entitlements } from './semantics/entitlements.ts';
-import { ephemeralKeys } from './semantics/ephemeral-keys.ts';
-import { files } from './semantics/files.ts';
-import { invoices } from './semantics/invoices.ts';
-import { issuing, lapseRealtimeRequests } from './semantics/issuing.ts';
-import { paymentIntents } from './semantics/payment-intents.ts';
-import { paymentLinks } from './semantics/payment-links.ts';
-import { paymentMethods } from './semantics/payment-methods.ts';
-import { platform } from './semantics/platform.ts';
-import { plans } from './semantics/plans.ts';
-import { products } from './semantics/products.ts';
-import { radar } from './semantics/radar.ts';
-import { refunds } from './semantics/refunds.ts';
-import { setupIntents } from './semantics/setup-intents.ts';
-import { subscriptionSchedules } from './semantics/subscription-schedules.ts';
-import { subscriptions } from './semantics/subscriptions.ts';
-import { tax } from './semantics/tax.ts';
-import { terminal } from './semantics/terminal.ts';
-import { testClocks } from './semantics/test-clocks.ts';
-import { ledger } from './semantics/ledger.ts';
-import { tokens } from './semantics/tokens.ts';
-import { transfers } from './semantics/transfers.ts';
-import { treasury } from './semantics/treasury.ts';
-import { webhookEndpoints } from './semantics/webhook-endpoints.ts';
-import { advancePayouts, balanceBody, payDuePayouts } from './semantics/balance.ts';
-import { settleDueEntries } from './semantics/ledger.ts';
-import { settleHeldRefunds } from './semantics/refunds.ts';
-import { settleBankDebits } from './semantics/payment-intents.ts';
-import { lapseCoupons } from './semantics/coupons.ts';
-import { finishClockAdvances } from './semantics/test-clocks.ts';
-import { settleTopups } from './semantics/terminal.ts';
-import { finishReportRuns } from './semantics/platform.ts';
-import { advanceBilling } from './semantics/renewals.ts';
-import { refuseParameters } from './stripe-params.ts';
-import { afterStripeWrite, handleStripeDoor, PLATFORM_ACCOUNT_ID } from './stripe-twin.ts';
-import { worldNow, statefulTwinManifest} from '@volter/world-core';
-import { expandOf, render, servesCurrent, withoutEndpointSecret } from './stripe-version.ts';
-
-/** Options shared by the fetch handler and the Bun.serve wrapper around it. `port` is a
- *  BIND concern the fetch ignores; it stays in one shape so a caller configures the twin
- *  once whichever way it is mounted. */
-export type StripeTwinOptions = { root?: string; port?: number; readOnly?: boolean; /** the World instant, when a caller pins it */ clock?: () => string };
-
-// ── what a publishable key may call ──
-// "Publishable API key pk_... | Safe to expose: Yes | API key for Stripe.js, Elements, and mobile SDKs. It can identify
-// your account and create tokens or PaymentMethods from payment details, but it can't perform sensitive operations such
-// as creating charges or reading account data" (docs.stripe.com/keys). The served spec names the calls a publishable key
-// makes with an object's client secret: "You can retrieve a PaymentIntent client-side using a publishable key when the
-// client_secret is provided in the query string" (GET /v1/payment_intents/{intent}), "Client-side retrieval using a
-// publishable key is allowed when the client_secret is provided" (GET /v1/setup_intents/{intent}), "Required if a
-// publishable key is used to retrieve the source" (GET /v1/sources/{source}), and the confirm and verify_microdeposits
-// calls that take "The client secret of the PaymentIntent" (or SetupIntent). Anything else is refused with Stripe's
-// code: "secret_key_required | The API key provided is a publishable key, but a secret key is required"
-// (docs.stripe.com/error-codes), as 403, "The API key doesn't have permissions to perform the request"
-// (docs.stripe.com/api/errors).
-// Where the documentation stops and the twin decides: the list above is the whole of what a publishable key may call
-// (Stripe publishes no complete list); a client-secret call without the secret answers parameter_missing, and one with a
-// secret that is not the object's answers the object's 404, as though the key could not see it.
-const PUBLISHABLE_CREATES = new Set(['PostTokens', 'PostPaymentMethods']);
-const BY_CLIENT_SECRET: Record<string, { type: string; param: string }> = {
-  GetPaymentIntentsIntent: { type: 'payment_intent', param: 'intent' },
-  PostPaymentIntentsIntentConfirm: { type: 'payment_intent', param: 'intent' },
-  PostPaymentIntentsIntentVerifyMicrodeposits: { type: 'payment_intent', param: 'intent' },
-  GetSetupIntentsIntent: { type: 'setup_intent', param: 'intent' },
-  PostSetupIntentsIntentConfirm: { type: 'setup_intent', param: 'intent' },
-  PostSetupIntentsIntentVerifyMicrodeposits: { type: 'setup_intent', param: 'intent' },
-  GetSourcesSource: { type: 'source', param: 'source' },
-};
-
-/** Stripe's refusal of a call a publishable key may not make, or undefined when the key may make it. */
-async function publishableKeyRefused(call: DerivedCall, scope: { root?: string; clock?: () => string }): Promise<Response | undefined> {
-  const key = /^bearer\s+(\S+)/i.exec(call.request.headers.get('authorization') ?? '')?.[1] ?? '';
-  if (!key.startsWith('pk_')) return undefined;
-  if (PUBLISHABLE_CREATES.has(call.operation.id)) return undefined;
-  const scoped = BY_CLIENT_SECRET[call.operation.id];
-  if (!scoped) return vendorError(manifest, { status: 403, code: 'secret_key_required', message: 'The API key provided is a publishable key, but a secret key is required.' });
-  const params = await readParams(manifest, call.request.clone(), call.operation);
-  const secret = typeof params.client_secret === 'string' ? params.client_secret : '';
-  if (!secret) return vendorError(manifest, { status: 400, code: 'parameter_missing', param: 'client_secret', message: 'Missing required param: client_secret.' });
-  const id = call.params[scoped.param] ?? '';
-  // the context reads a body of its own, so the handler after this still has the request's
-  const ctx = await semanticsContext(manifest, call.request.clone(), call.operation, scope);
-  return ctx.get(scoped.type, id)?.client_secret === secret ? undefined : wrongClientSecret(scoped, id);
-}
-
-// ── an account whose OAuth connection was revoked ──
-// "After revocation, the account can't be accessed by your platform in the Dashboard or through the API"
-// (docs.stripe.com/connect/oauth-reference, deauthorize; so too a connection revoked by a reused code). A call made as it
-// (the Stripe-Account header) or naming it (/v1/accounts/{account}…) is refused with the error Stripe documents for a
-// Stripe-Account the key cannot use: "account_invalid | The account ID provided as a value for the Stripe-Account header
-// is invalid" (docs.stripe.com/error-codes), as 403, "The API key doesn't have permissions to perform the request"
-// (docs.stripe.com/api/errors). Where the documentation stops and the twin decides: the message's wording; an account
-// the platform created itself, or never connected by OAuth, is not affected.
-async function revokedAccountRefused(call: DerivedCall, scope: { root?: string; clock?: () => string }): Promise<Response | undefined> {
-  const named = [call.request.headers.get('stripe-account') ?? undefined, call.operation.path.startsWith('/v1/accounts/{account}') ? call.params.account : undefined].filter((a): a is string => !!a);
-  if (!named.length) return undefined;
-  const ctx = await semanticsContext(manifest, new Request(call.request.url), call.operation, scope); // the rows only: no body read
-  const revoked = named.find((a) => connectionRevoked(ctx, a));
-  if (!revoked) return undefined;
-  const key = requestKey(call.request);
-  return vendorError(manifest, { status: 403, code: 'account_invalid', message: `The provided key '${redactKey(key)}' does not have access to account '${revoked}' (or that account does not exist). Application access may have been revoked.` });
-}
-
-/** The API key a request carries: Bearer, or Basic's user (`curl -u sk_…:`, docs.stripe.com/api/authentication). */
-function requestKey(request: Request): string {
-  const header = request.headers.get('authorization') ?? '';
-  const bearer = /^bearer\s+(\S+)/i.exec(header)?.[1];
-  if (bearer) return bearer;
-  const basic = /^basic\s+(\S+)/i.exec(header)?.[1];
-  if (basic) { try { return atob(basic).split(':')[0] ?? ''; } catch { return ''; } }
-  return '';
-}
-
-/** A client-secret call whose secret is not the object's: answered as though the key could not see it (the twin's
- *  decision, above). */
-function wrongClientSecret(scoped: { type: string; param: string }, id: string): Response {
-  return vendorError(manifest, { status: 404, code: 'resource_missing', param: scoped.param, message: `No such ${scoped.type}: '${id}'` });
-}
-
-/**
- * The whole Stripe serve path as a plain `(Request) => Response` — the `/twin` manifest
- * door, the header threading (idempotency key, pinned API version, Connect account) and
- * the derived dispatch over the hand-written routes. NOTHING about it is port-bound.
- *
- * Why this is the factory and `createStripeTwinServer` is a wrapper (runtime contract R12,
- * the Cloudflare ruling): a Durable Object / Worker entry has no loopback ports — it mounts
- * pack fetches IN-PROCESS behind one router. Handing that entry `Bun.serve` is not an
- * option, so the vendor HTTP adaptation has to be a value it can call. Keeping the server a
- * thin `Bun.serve(fetch)` also means the local and hosted lanes execute the SAME bytes of
- * serving code — the parity claim (R9) is about one code path, not two that resemble each
- * other.
- *
- * SCOPING THE STORES AROUND IT: this fetch is ASYNC, so install the world store with
- * `setActiveWorldStore(store)` in a try/finally — **not** `withWorldStore(store, fn)`, whose
- * `finally` fires when `fn` RETURNS, i.e. at the first `await`, restoring the previous store
- * under the rest of the request.
- */
-export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch {
-  const readOnly = options.readOnly ?? false;
-  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
-  // The derived dispatch owns the API: an operation with a semantics handler is served by it, one on a
-  // resource the manifest declares by the derived core, and one neither models answers Stripe's
-  // unrecognized-URL 404.
-  const guard = crossCutting(manifest, { readOnly, ...scope });
-  const handlerMap = { ...billing, ...paymentIntents, ...customers, ...products, ...plans, ...charges, ...refunds, ...setupIntents, ...paymentMethods, ...subscriptions, ...invoices, ...checkout, ...ephemeralKeys, ...disputes, ...balances, ...coupons, ...creditNotes, ...subscriptionSchedules, ...entitlements, ...testClocks, ...webhookEndpoints, ...connect, ...transfers, ...appsSecrets, ...tokens, ...files, ...tax, ...paymentLinks, ...radar, ...issuing, ...terminal, ...treasury, ...platform, ...ledger };
-  const core = coreFor(manifest, scope);
-  const derived = createDerivedFetch({
-    surface,
-    handlers: bindSemantics(manifest, handlerMap, scope),
-    core,
-    // after the credential and the version, a publishable key is held to the client-side calls, then a request's
-    // parameters are checked against the operation's (stripe-params.ts)
-    around: (call, next) => guard(call, async () => (await publishableKeyRefused(call, scope)) ?? (await revokedAccountRefused(call, scope)) ?? (await refuseParameters(call)) ?? next()),
-    gap: (request) => vendorError(manifest, { status: 404, message: `Unrecognized request URL (${request.method}: ${new URL(request.url).pathname}).` }),
-  });
-  // the hosted flows sit beside the API: checkout.stripe.com's payment page, billing.stripe.com's customer portal,
-  // connect.stripe.com's onboarding and its OAuth endpoints (screens/connect-oauth.tsx), verify.stripe.com's identity
-  // check and the bank-linking flow Stripe.js opens, and the Dashboard's Public details page
-  // (dashboard.stripe.com/settings/public, the platform's customer-facing name) and Connect OAuth settings
-  // (dashboard.stripe.com/settings/connect/onboarding-options/oauth: the client_id, OAuth on, the redirect URIs);
-  // a read-only twin takes no payments and moves nothing
-  const flows = [stripeCheckoutFlow(scope), stripePortalFlow(scope), stripeOnboardingFlow(scope), stripeIdentityFlow(scope), stripeFinancialConnectionsFlow(scope), stripePublicDetailsFlow(scope), stripeConnectOAuthFlow(scope), stripeConnectSettingsFlow(scope)];
-  // the twin's own doors sit in front of the API: discovery, and what stands in for an act Stripe's API
-  // does not have (stripe-twin.ts)
-  // GET /twin: what this twin is (not Stripe's; a host reads it)
-  function discovery(): Response {
-    return Response.json(statefulTwinManifest({ vendor: 'stripe', twinOf: 'the Stripe REST API', stores: 'customers, payment objects, checkout sessions, products/prices and webhook endpoints (signed events)' }));
-  }
-  // /_twin/…: a door's body is read as the API's is: a form, or JSON
-  const twinDoor = async (request: Request, url: URL): Promise<Response | undefined> => {
-    const answer = await handleStripeDoor({
-      method: request.method, path: url.pathname, readOnly,
-      occurredAt: options.clock ? options.clock() : worldNow(),
-      ...(options.root !== undefined ? { root: options.root } : {}),
-    }, await readParams(manifest, request));
-    return answer && Response.json(answer.body, { status: answer.status, headers: { 'request-id': 'req_twin' } });
-  };
-  const door = async (request: Request): Promise<Response | undefined> => {
-    const url = new URL(request.url);
-    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') return discovery();
-    return url.pathname.startsWith('/_twin/') ? twinDoor(request, url) : undefined;
-  };
-  // time's moves Stripe makes on its own (a subscription renewing at its period's end, its renewal charged an hour
-  // later: semantics/renewals.ts; each account's automatic payouts: semantics/balance.ts) are caught up to the World's clock before anything is answered, so every door
-  // (the API, the hosted pages) reads the account as it stands now
-  const billingClock = (surface.operations as Array<{ id: string; method: string; path: string; class: string }>).find((o) => o.id === 'GetSubscriptions')!;
-  // time's moves are Stripe's own, not the caller's: they land under a read-only request too (runAsVendorMove)
-  const catchUp = async (request: Request): Promise<void> => {
-    if (readOnly) return;
-    await runAsVendorMove(async () => {
-      const ctx = await semanticsContext(manifest, new Request(request.url), billingClock, scope);
-      // a test clock advanced by the last request has reached its time (semantics/test-clocks.ts)
-      await finishClockAdvances(ctx);
-      await advanceBilling(ctx);
-      // a submitted bank debit settles (in test mode at once) before anything is answered (semantics/payment-intents.ts)
-      await settleBankDebits(ctx);
-      // a coupon past its redeem_by is no longer valid (semantics/coupons.ts)
-      await lapseCoupons(ctx);
-      // a top-up's funds arrive five days after it is made (semantics/terminal.ts)
-      await settleTopups(ctx);
-      // a report run completes (semantics/platform.ts)
-      await finishReportRuns(ctx);
-      // a real-time authorization request no one answered is decided when its window ends (semantics/issuing.ts)
-      await lapseRealtimeRequests(ctx);
-      // a refund held for want of balance is made when funds cover it, before any payout takes them (semantics/refunds.ts)
-      await settleHeldRefunds(ctx);
-      await advancePayouts(ctx);
-    });
-  };
-  // Time's EVENTS, sent on the vendor's clock through a twin-only drain door, as the qstash and vercel twins send
-  // theirs (a caller — a runner's drainer — drives each move). POST /_twin/drain catches time up as every request
-  // does, then writes what time settled on each account: payouts whose arrival date came (pending → paid, sent as
-  // payout.paid) and funds that came due (pending → available), for which the account is sent one balance.available
-  // ("Occurs whenever your Stripe balance has been updated (e.g., when a charge is available to be paid out)",
-  // docs.stripe.com/api/events/types) carrying its Balance, when an entry that settled adds to it ("This event is not
-  // fired for negative transactions", the same page); a connected account's events go to Connect endpoints.
-  // A read already sees these moves; the drain is what makes Stripe's events about them arrive. Answers what it sent.
-  const drain = async (request: Request): Promise<Response> => {
-    if (readOnly) return Response.json({ error: 'twin is read-only; omit readOnly to accept writes' }, { status: 405 });
-    await catchUp(request);
-    const at = (account?: string) => semanticsContext(manifest, new Request(request.url, account ? { headers: { 'stripe-account': account } } : {}), billingClock, scope);
-    const platformCtx = await at();
-    const accounts = [undefined, ...platformCtx.rows('account').map((a) => String(a.id)).filter((id) => id !== PLATFORM_ACCOUNT_ID)];
-    const delivered: Array<{ type: string; id?: string; account?: string }> = [];
-    for (const account of accounts) {
-      const ctx = account ? await at(account) : platformCtx;
-      for (const id of await payDuePayouts(ctx)) delivered.push({ type: 'payout.paid', id, ...(account ? { account } : {}) });
-      if ((await settleDueEntries(ctx)).some((t) => Number(t.net) > 0)) {
-        await afterStripeWrite('balance', 'balance.available', balanceBody(ctx), options.root, ctx.occurredAt, undefined, account);
-        delivered.push({ type: 'balance.available', ...(account ? { account } : {}) });
-      }
-    }
-    return Response.json({ delivered });
-  };
-  const served = async (request: Request): Promise<Response> => {
-    if (request.method === 'POST' && new URL(request.url).pathname.replace(/\/+$/, '') === '/_twin/drain') return drain(request);
-    const opened = await door(request);
-    if (opened) return opened;
-    // the client library an application's page loads from js.stripe.com (stripe-js.ts); it moves nothing, so a
-    // read-only twin serves it too
-    const library = stripeJs(request);
-    if (library) return library;
-    await catchUp(request);
-    if (!readOnly) for (const flow of flows) { const page = await flow(request); if (page) return page; }
-    const acting = await actingAsOAuthKey(request);
-    if (acting instanceof Response) return acting;
-    // an update's metadata is merged into what the object holds before the handler or the core serves it (mergeMetadata)
-    return derived(readOnly ? acting : await mergeMetadata(acting, (op) => !(op.id in handlerMap) && core.owns(op), scope));
-  };
-  // A connected account's OAuth keys (screens/connect-oauth.tsx): the token endpoint's access_token is "Use the
-  // Stripe-Account header with your platform's secret key (that can make requests on behalf of this Stripe account)" and
-  // its stripe_publishable_key the same with the publishable key (docs.stripe.com/connect/oauth-reference): a request made
-  // with one acts as that account, as a request with the Stripe-Account header does. A key no live connection holds (its
-  // connection revoked, or replaced by a refresh: "Any existing access token with the same scope and mode ... is
-  // revoked") is Stripe's unknown key, 401 "Invalid API Key provided" (docs.stripe.com/api/authentication, docs.stripe.com
-  // /error-codes); one sent with a Stripe-Account header naming another account cannot act as it (account_invalid).
-  // Where the documentation stops and the twin decides: the messages' wording; a read_only key is not held to reads
-  // (manifest todo stripe.connect.oauth_scope_enforcement).
-  const actingAsOAuthKey = async (request: Request): Promise<Request | Response> => {
-    const key = requestKey(request);
-    if (!/^(sk|pk)_test_oauth_/.test(key)) return request;
-    const held = oauthKeyAccount(await semanticsContext(manifest, new Request(request.url), billingClock, scope), key);
-    if (!held) return vendorError(manifest, { status: 401, message: `Invalid API Key provided: ${redactKey(key)}` });
-    const named = request.headers.get('stripe-account');
-    if (named && named !== held.account) return vendorError(manifest, { status: 403, code: 'account_invalid', message: `The provided key '${redactKey(key)}' does not have access to account '${named}' (or that account does not exist). Application access may have been revoked.` });
-    const headers = new Headers(request.headers);
-    headers.set('stripe-account', held.account);
-    const bodied = request.method !== 'GET' && request.method !== 'HEAD';
-    return new Request(request.url, { method: request.method, headers, ...(bodied ? { body: await request.arrayBuffer() } : {}) });
-  };
-  // every answer in the shape of the API version the caller is served (stripe-version.ts)
-  const rendered = async (request: Request): Promise<Response> => {
-    const expand = expandOf(request.clone());
-    const creates = request.method === 'POST' && new URL(request.url).pathname.replace(/\/+$/, '') === '/v1/webhook_endpoints';
-    const res = await served(request);
-    const pinned = request.headers.get('stripe-version');
-    if (!(res.headers.get('content-type') ?? '').includes('json')) return res;
-    if (!servesCurrent(pinned) && creates) return res;
-    const body = await res.json();
-    // a webhook endpoint's `secret` is "Only returned at creation" (docs.stripe.com/api/webhook_endpoints/object)
-    const answered = creates ? body : withoutEndpointSecret(body);
-    return new Response(JSON.stringify(servesCurrent(pinned) ? render(answered, pinned, await expand) : answered), { status: res.status, statusText: res.statusText, headers: res.headers });
-  };
-  // the request's W3C trace context scopes every door (the API, the hosted flows, the drain): their writes record it and
-  // the webhooks they cause continue it (world-core trace-context)
-  // a read-only request (x-volter-read-only) writes nothing, answered with Stripe's read-only error
-  return derivedRequestScopes(manifest, Object.assign((request: Request) => runWithRequestTrace(request, () => rendered(request)), { owners: derived.owners }));
-}
-
-export async function createStripeTwinServer(options: StripeTwinOptions): Promise<{ port: number; stop: () => void }> {
-  const server = await serveHttp({
-    port: options.port ?? 0,
-    idleTimeout: 60,
-    fetch: createStripeTwinFetch(options),
-  });
-  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
-}
-
-/** A create's `metadata` holds no key posted empty. "Individual keys can be unset by posting an empty value to them. All
- *  keys can be unset by posting an empty value to `metadata`" (every metadata parameter of docs.stripe.com/api): an empty
- *  value is the absence of the key, on a create as on an update, so an object never holds a key set to "". Clients post
- *  one without meaning to: stripe-node encodes a `null` value as `metadata[key]=` (Cal.com's PaymentIntent metadata
- *  carries `bookerPhoneNumber: null` for a guest who gave no phone). The request is rewritten as JSON without them. */
-async function createMetadata(request: Request, path: string): Promise<Request> {
-  const op = CREATES.find((c) => c.re.test(path))?.op;
-  if (!op) return request;
-  const params = await readParams(manifest, request.clone(), op);
-  if (!('metadata' in params)) return request;
-  const given = params.metadata;
-  let metadata: Record<string, unknown>;
-  if (given === '') metadata = {};
-  else if (given && typeof given === 'object' && !Array.isArray(given) && Object.values(given).includes('')) {
-    metadata = Object.fromEntries(Object.entries(given as Record<string, unknown>).filter(([, v]) => v !== ''));
-  } else return request;
-  const headers = new Headers(request.headers);
-  headers.set('content-type', 'application/json');
-  return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...params, metadata }) });
-}
-
-// the create operations, by their path as a pattern, for createMetadata
-const CREATES = (surface.operations as Array<DerivedCall['operation']>).filter((o) => o.class === 'create' && o.method.toUpperCase() === 'POST')
-  .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
-
-// the update operations, by their path as a pattern, for mergeMetadata
-const UPDATES = (surface.operations as Array<DerivedCall['operation']>).filter((o) => o.class === 'update' && o.method.toUpperCase() === 'POST')
-  .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
-
-/** An update's `metadata`, merged into what the object holds before anything serves the update. "This parameter uses a
- *  merge mechanism, which allows you to add new key-value pairs to an object in an update call without affecting any
- *  existing metadata"; "Pass in the key with an empty string as the value to remove the key from the metadata"; "Pass an
- *  empty string as the value for the metadata attribute to delete all of the keys simultaneously"
- *  (docs.stripe.com/metadata). The derived core already merges a nested hash where the manifest leaves `update` at
- *  `merge` (dropping keys set to ""), so only a clear-all is rewritten for it; where a handler or a `replace` update
- *  stores the request's metadata whole, the request is rewritten to carry the merged hash, so every door stores the same
- *  answer. The request is rewritten as JSON (readParams reads either). */
-async function mergeMetadata(request: Request, coreMerges: (op: DerivedCall['operation']) => boolean, scope: { root?: string; clock?: () => string }): Promise<Request> {
-  if (request.method !== 'POST' || (request.headers.get('content-type') ?? '').includes('multipart')) return request;
-  const path = new URL(request.url).pathname;
-  let op: DerivedCall['operation'] | undefined;
-  let id = '';
-  for (const u of UPDATES) { const m = u.re.exec(path); if (m) { op = u.op; id = decodeURIComponent(m.at(-1) ?? ''); break; } }
-  if (!op) return createMetadata(request, path);
-  if (!op.resource) return request;
-  const params = await readParams(manifest, request.clone(), op);
-  if (!('metadata' in params)) return request;
-  const given = params.metadata;
-  // a plan is kept as the recurring price it is (semantics/plans.ts)
-  const resource = op.resource === 'plan' ? 'price' : op.resource;
-  const ctx = await semanticsContext(manifest, request.clone(), op, scope);
-  const held = ctx.get(resource, id)?.metadata;
-  const prior = held && typeof held === 'object' ? (held as Record<string, unknown>) : {};
-  const merges = coreMerges(op) && manifest.resources[resource]?.update !== 'replace';
-  let metadata: Record<string, unknown>;
-  if (given === '') metadata = merges ? Object.fromEntries(Object.keys(prior).map((k) => [k, ''])) : {};
-  else if (given && typeof given === 'object' && !Array.isArray(given)) {
-    if (merges) return request;
-    metadata = Object.fromEntries(Object.entries({ ...prior, ...(given as Record<string, unknown>) }).filter(([, v]) => v !== ''));
-  } else return request;
-  const headers = new Headers(request.headers);
-  headers.set('content-type', 'application/json');
-  return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...params, metadata }) });
-}