@volter/twin-stripe 0.1.2 → 2.0.1

package/dist/src/stripe-connector.js

@@ -0,0 +1,414 @@
+// Stripe CONNECTOR — the live-vendor pull/push path that gives the Stripe twin the
+// full "git for SaaS" lifecycle (the piece every other connector pack already had,
+// and Stripe was missing entirely).
+//
+// PULL  (real → twin):  fetch real Stripe objects, map snake_case → SyncResource[],
+//                       fold into the tree through the kernel's observe (its own diff, so a
+//                       re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real Stripe REST API
+//                       and the head confirms on success — which records the confirmed
+//                       fields as an observed event and suppresses the local
+//                       projection (the change is counted exactly once).
+//
+// The vendor I/O is an INJECTED executor (the auth-boundary, hard-problem #6): the
+// kernel and this pack hold NO Stripe key and import NO network client.
+//   - offline/tests pass a fake executor (deterministic, no network),
+//   - live runs pass `liveStripeExecute(apiKey)` (the user's own secret key).
+// Same code path either way, so the connector is fully exercisable offline AND
+// runnable against a real account.
+import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
+import { StripeBudget, StripeBudgetError, stripeCallWeight } from "./stripe-budget.js";
+const SERVICE = 'stripe';
+// Subject types that are twin-internal and are NEVER pushed to real Stripe: the recorded
+// Stripe `event` envelopes (the local Events-API store) and idempotency bookkeeping.
+export const INTERNAL_SUBJECT_TYPES = new Set(['event', '_idempotency']);
+/**
+ * A live executor against the real Stripe REST API (secret key = the user's own).
+ * Form-encodes POST params; sends GET filters as a query string. Never imported by
+ * the pack's own code path — only constructed by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.stripe.com` request, and therefore the one
+ * place the rate budget has to be enforced — and Stripe is the pack where a runaway loop does not
+ * merely annoy a vendor, it MOVES MONEY. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `StripeBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 429 signal becomes a persisted cooldown that makes every later call fail fast WITHOUT touching
+ * Stripe. There is deliberately no OPTION to disable the guard, and no
+ * value a caller can pass for `budget` that yields an unguarded client. That is NOT immunity from
+ * a caller who WANTS one: a fresh `budgetOptions.path` per construction, or an injected clock,
+ * restores the allowance, because the seam tests need cannot be denied to a determined caller in
+ * the same process. The kernel header states that limit and this does not upgrade it. See `stripe-budget.ts` for why,
+ * and for the limits of the guarantee.
+ */
+export function liveStripeExecute(apiKey, base = 'https://api.stripe.com', opts = {}) {
+    // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+    // UNMODIFIED StripeBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+    // Proxy that traps it are all refused, because all three are one-liners that would otherwise
+    // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
+    // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+    // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+    // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+    const doFetch = opts.fetchImpl ?? fetch;
+    // The default ledger is keyed by a hash of THIS key — Stripe's limits attach to the account
+    // behind it, so a cwd-scoped ledger would hand it a fresh allowance per checkout/worktree/CI leg.
+    // A live key and a test key hash differently, which matches Stripe's separate 100/s and 25/s.
+    // ONE expression decides which budget is used, so there is no second, weaker test that could
+    // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+    // must be an UNMODIFIED StripeBudget — a duck-typed stand-in, a SUBCLASS overriding
+    // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+    // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+    // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+    // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+    // header states that limit rather than pretending otherwise. This closes the accident and the
+    // one-liner, which are the shapes that actually happen.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, StripeBudget, 'liveStripeExecute')
+        : new StripeBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, params) => {
+        const headers = { Authorization: `Bearer ${apiKey}` };
+        let url = `${base}${path}`;
+        const form = encodeForm(params ?? {});
+        const init = { method, headers };
+        if (method === 'GET') {
+            if (form)
+                url += `?${form}`;
+        }
+        else if (form) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+            init.body = form;
+        }
+        const weight = stripeCallWeight(method, path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(url, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const parsed = (await res.json());
+        // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+        // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+        // first either way, so the refusal survives the throw.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Stripe ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof StripeBudgetError) || !res.ok)
+                throw error;
+        }
+        return parsed;
+    };
+}
+// Stripe's nested form encoding (a[b]=c). Only the shapes the connector pushes
+// (flat scalars + one level of object nesting, e.g. metadata) are handled.
+function encodeForm(params, prefix = '') {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        const name = prefix ? `${prefix}[${key}]` : key;
+        if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            const nested = encodeForm(value, name);
+            if (nested)
+                parts.push(nested);
+        }
+        else {
+            parts.push(`${encodeURIComponent(name)}=${encodeURIComponent(value === null ? '' : String(value))}`);
+        }
+    }
+    return parts.join('&');
+}
+function listOf(res) {
+    return Array.isArray(res.data) ? res.data : [];
+}
+function throwIfError(res, ctx) {
+    if (res.error)
+        throw new Error(`stripe ${ctx} failed: ${res.error.message ?? 'unknown error'}`);
+}
+// ── PULL ────────────────────────────────────────────────────────────────────
+/**
+ * Map a real-Stripe customer (snake_case) → a twin sync resource. Only the stable
+ * scalar fields the twin tracks are carried; absent fields become null so the diff
+ * is faithful (an unset email reads as null, not missing).
+ */
+export function mapCustomer(c) {
+    return {
+        type: 'customer',
+        id: String(c.id),
+        fields: {
+            email: c.email ?? null,
+            name: c.name ?? null,
+            description: c.description ?? null,
+            phone: c.phone ?? null,
+            currency: c.currency ?? null,
+            delinquent: typeof c.delinquent === 'boolean' ? c.delinquent : null,
+            created: typeof c.created === 'number' ? c.created : null,
+            livemode: typeof c.livemode === 'boolean' ? c.livemode : null,
+        },
+    };
+}
+/**
+ * Map a real-Stripe subscription (snake_case) → a twin sync resource. The single
+ * subscribed price id is lifted out of items.data[0].price.id (Stripe's nested list
+ * shape) so the twin tracks a flat, diffable `price`.
+ */
+export function mapSubscription(s) {
+    const items = s.items;
+    const firstPrice = items?.data?.[0]?.price?.id;
+    return {
+        type: 'subscription',
+        id: String(s.id),
+        fields: {
+            customer: s.customer ?? null,
+            status: s.status ?? null,
+            currency: s.currency ?? null,
+            cancel_at_period_end: typeof s.cancel_at_period_end === 'boolean' ? s.cancel_at_period_end : null,
+            price: typeof firstPrice === 'string' ? firstPrice : null,
+            created: typeof s.created === 'number' ? s.created : null,
+            livemode: typeof s.livemode === 'boolean' ? s.livemode : null,
+        },
+    };
+}
+/**
+ * A GENERIC scalar mapper for the collections that don't need special id-lifting like
+ * subscriptions do. We carry the stable, diffable scalar fields a twin tracks (anything
+ * that is a string/number/boolean), dropping nested objects/arrays (which the twin either
+ * synthesizes or doesn't diff on). This keeps every collection's pull faithful without a
+ * bespoke mapper per type — vendor-SPECIFIC lifting (subscription.price) stays explicit.
+ */
+export function mapScalarResource(type, r) {
+    const fields = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (k === 'id' || k === 'object')
+            continue;
+        if (v === null || typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+            fields[k] = v ?? null;
+    }
+    return { type, id: String(r.id), fields };
+}
+// The full set of collections a full sync pulls, mapped to the REST list path + the twin
+// resource type. Customers + subscriptions keep their bespoke mappers (id-lifting); the
+// rest use the generic scalar mapper.
+const PULL_COLLECTIONS = [
+    { path: '/v1/customers', type: 'customer', map: mapCustomer },
+    { path: '/v1/subscriptions', type: 'subscription', map: mapSubscription, params: { status: 'all' } },
+    { path: '/v1/products', type: 'product' },
+    { path: '/v1/prices', type: 'price' },
+    { path: '/v1/charges', type: 'charge' },
+    { path: '/v1/payment_intents', type: 'payment_intent' },
+    { path: '/v1/invoices', type: 'invoice' },
+    { path: '/v1/refunds', type: 'refund' },
+    { path: '/v1/payouts', type: 'payout' },
+    { path: '/v1/disputes', type: 'dispute' },
+    { path: '/v1/coupons', type: 'coupon' },
+];
+/** Pull real Stripe customers via the executor and map them to twin sync resources. */
+export async function pullStripeCustomers(execute, opts = {}) {
+    const res = await execute('GET', '/v1/customers', { limit: opts.limit ?? 100 });
+    throwIfError(res, 'pull customers');
+    return listOf(res).map(mapCustomer);
+}
+/** Pull real Stripe subscriptions via the executor and map them to twin sync resources. */
+export async function pullStripeSubscriptions(execute, opts = {}) {
+    const res = await execute('GET', '/v1/subscriptions', { status: 'all', limit: opts.limit ?? 100 });
+    throwIfError(res, 'pull subscriptions');
+    return listOf(res).map(mapSubscription);
+}
+/**
+ * Pull from real Stripe (customers + subscriptions) and fold into the twin (mirror
+ * seeding). The fold makes a re-pull of identical state a no-op.
+ */
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources, opts) {
+    return observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+    });
+}
+export async function syncStripeFromReal(execute, opts) {
+    const customers = await pullStripeCustomers(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
+    const subscriptions = await pullStripeSubscriptions(execute, { ...(opts.limit ? { limit: opts.limit } : {}) });
+    const resources = [...customers, ...subscriptions];
+    const result = fold(resources, opts);
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PUSH ────────────────────────────────────────────────────────────────────
+// Stripe resource type → REST collection segment, for building create paths.
+// (Pluralization isn't uniform — e.g. `dispute`→`disputes` is fine but several types
+// the twin writes need an explicit mapping so the path matches real Stripe exactly.)
+const COLLECTION = {
+    customer: 'customers',
+    subscription: 'subscriptions',
+    charge: 'charges',
+    product: 'products',
+    price: 'prices',
+    invoice: 'invoices',
+    payment_intent: 'payment_intents',
+    setup_intent: 'setup_intents',
+    payment_method: 'payment_methods',
+    refund: 'refunds',
+    dispute: 'disputes',
+    payout: 'payouts',
+};
+// Verb-style twin operations that map to a real-Stripe SUB-ACTION endpoint
+// (POST /v1/<collection>/:id/<verb>) rather than a plain resource update. The twin
+// records these verbs verbatim as the operation's suffix (see stripe-twin.ts:
+// payment_intent.confirm, setup_intent.confirm, payment_method.detach,
+// invoice.finalize|pay|void, dispute.close, payout.cancel). The verb here IS the
+// real Stripe path segment, so this stays faithful as the twin grows.
+const SUBACTION_VERBS = new Set(['confirm', 'detach', 'finalize', 'pay', 'void', 'close']);
+// `cancel` is resource-specific in real Stripe: a subscription is canceled with
+// DELETE /v1/subscriptions/:id, but a payout is canceled with POST
+// /v1/payouts/:id/cancel. Anything else canceled via DELETE on the resource is a safe
+// default (no other type the twin emits a `.cancel` for uses a sub-action path).
+const CANCEL_VIA_SUBACTION = new Set(['payout']);
+/**
+ * Resolve the REST (method, path) for ONE pending action — faithful to the real
+ * Stripe REST surface for EVERY write operation the twin records. The action carries
+ * the twin operation (`<type>.<verb>`) plus its subject:
+ *   - `<type>.create`              → POST   /v1/<collection>
+ *   - `subscription.cancel`        → DELETE /v1/subscriptions/:id
+ *   - `payout.cancel`              → POST   /v1/payouts/:id/cancel  (sub-action)
+ *   - `payment_intent.confirm`     → POST   /v1/payment_intents/:id/confirm
+ *   - `setup_intent.confirm`       → POST   /v1/setup_intents/:id/confirm
+ *   - `payment_method.detach`      → POST   /v1/payment_methods/:id/detach
+ *   - `invoice.finalize|pay|void`  → POST   /v1/invoices/:id/<verb>
+ *   - `dispute.close`              → POST   /v1/disputes/:id/close
+ *   - `<type>.update` (or any other verb) → POST /v1/<collection>/:id
+ *
+ * Unknown/unsupported operations must FAIL LOUDLY at push time (see pushStripeAction),
+ * never be silently dropped — so this resolver always returns a concrete request and
+ * the caller validates the operation is one the twin is allowed to push.
+ */
+export function stripeRequestForAction(action) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    const collection = COLLECTION[action.subject.type] ?? `${action.subject.type}s`;
+    const base = `/v1/${collection}`;
+    if (verb === 'create')
+        return { method: 'POST', path: base };
+    if (verb === 'cancel') {
+        return CANCEL_VIA_SUBACTION.has(action.subject.type)
+            ? { method: 'POST', path: `${base}/${action.subject.id}/cancel` }
+            : { method: 'DELETE', path: `${base}/${action.subject.id}` };
+    }
+    // confirm / detach / finalize / pay / void / close → /:id/<verb>
+    if (SUBACTION_VERBS.has(verb))
+        return { method: 'POST', path: `${base}/${action.subject.id}/${verb}` };
+    // update (and any other plain mutation) → POST the resource itself.
+    return { method: 'POST', path: `${base}/${action.subject.id}` };
+}
+// The twin operations this connector knows how to push to real Stripe. Anything not
+// here (a new/unmodeled write op) must FAIL LOUDLY rather than be silently dropped —
+// pushing an unrecognized op risks hitting the wrong real endpoint or no-op'ing a
+// real change. New twin write ops must be deliberately added here.
+const PUSHABLE_VERBS = new Set(['create', 'update', 'cancel', ...SUBACTION_VERBS]);
+/** Throw if `op` is not a write operation this connector can faithfully push. */
+/** Whether this operation is one the connector can faithfully send to Stripe. */
+export function isPushable(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    return PUSHABLE_VERBS.has(verb);
+}
+function assertPushable(op) {
+    const verb = op.includes('.') ? op.slice(op.indexOf('.') + 1) : op;
+    if (!PUSHABLE_VERBS.has(verb)) {
+        throw new Error(`stripe push: unsupported operation '${op}' — refusing to silently drop a local write`);
+    }
+}
+/**
+ * Push ONE pending action to REAL Stripe via the injected executor. Returns the real
+ * external id (the Stripe object id from the response — for a create that is a freshly
+ * minted id; for an update it echoes the subject). WRITES TO THE REAL ACCOUNT.
+ */
+export async function pushStripeAction(execute, action) {
+    assertPushable(action.operation ?? `${action.subject.type}.update`);
+    const { method, path } = stripeRequestForAction(action);
+    const res = await execute(method, path, method === 'DELETE' ? undefined : (action.fields ?? {}));
+    throwIfError(res, `push ${action.subject.type}`);
+    const id = res.id;
+    return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: the same Stripe REST call, carried by the head. Stripe's API is
+ *  form-encoded, which is what `stripeExecute` already speaks — this only carries it. */
+export function stripeExecuteOver(execute) {
+    return async (method, path, params) => {
+        const body = params === undefined ? undefined : encodeForm(params);
+        const res = await execute({
+            method, path,
+            headers: { accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/x-www-form-urlencoded' }) },
+            ...(body === undefined ? {} : { body }),
+        });
+        if (res.body === '')
+            return {};
+        try {
+            return JSON.parse(res.body);
+        }
+        catch {
+            return { error: { type: 'api_error', message: res.body.slice(0, 200) } };
+        }
+    };
+}
+/** The refresh adapter: pull every modeled collection and the webhook endpoints through the executor. */
+export async function syncStripeFromRemote(execute, opts = {}) {
+    const at = opts.occurredAt ?? new Date().toISOString();
+    const wire = stripeExecuteOver(execute);
+    const resources = [
+        ...await pullStripeAll(wire),
+        ...await pullStripeWebhookEndpoints(wire),
+    ];
+    const report = fold(resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), occurredAt: at });
+    return { observed: report.observed, deltasAppended: report.appended };
+}
+/** The perform adapter: one entry crosses to Stripe, or settles with the reason it never could. The twin's
+ *  own subject types — the recorded `event` envelopes the write path persists for the Events API, and the
+ *  idempotency bookkeeping — are local state and must never be sent. */
+export async function performStripeAction(execute, action, _ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    if (INTERNAL_SUBJECT_TYPES.has(action.subject.type) || !isPushable(op)) {
+        return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at Stripe to write` } };
+    }
+    return pushStripeAction(stripeExecuteOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} });
+}
+// ── FULL SYNC (all collections + webhooks, bi-directional) ───────────────────
+/** Pull a single REST list collection and map each row to a twin sync resource. */
+async function pullCollection(execute, spec, limit) {
+    const res = await execute('GET', spec.path, { ...(spec.params ?? {}), limit });
+    throwIfError(res, `pull ${spec.type}`);
+    const map = spec.map ?? ((r) => mapScalarResource(spec.type, r));
+    return listOf(res).map(map);
+}
+/**
+ * Pull EVERY tracked collection from real Stripe (not just customers + subscriptions) in
+ * one pass and return the combined sync resources. This is the read half of a full sync.
+ */
+export async function pullStripeAll(execute, opts = {}) {
+    const limit = opts.limit ?? 100;
+    const all = [];
+    for (const spec of PULL_COLLECTIONS)
+        all.push(...await pullCollection(execute, spec, limit));
+    return all;
+}
+/** Pull the account's registered webhook endpoints (so the twin mirrors them too). */
+export async function pullStripeWebhookEndpoints(execute, opts = {}) {
+    const res = await execute('GET', '/v1/webhook_endpoints', { limit: opts.limit ?? 100 });
+    throwIfError(res, 'pull webhook_endpoints');
+    return listOf(res).map((w) => mapScalarResource('webhook_endpoint', w));
+}
+/**
+ * FULL bi-directional sync over the injected client: (1) PUSH every pending local action to
+ * real Stripe and confirm it, then (2) PULL all collections + webhook endpoints back and
+ * fold them into the event log. Pushing first means the pull observes the twin's own writes
+ * as confirmed external state (no double-count). Returns per-direction counts. Same code
+ * path offline (fake executor) and live (real key) — D4-faithful.
+ */
+export async function fullSyncStripe(execute, opts) {
+    // protocol 2: this is the PULL half only. The push half is the head's — it performs each entry through
+    // `performStripeAction` and confirms it — so a refresh no longer reconciles both directions at once.
+    const resources = [
+        ...await pullStripeAll(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
+        ...await pullStripeWebhookEndpoints(execute, { ...(opts.limit ? { limit: opts.limit } : {}) }),
+    ];
+    const pull = fold(resources, opts);
+    return { observed: pull.observed, deltasAppended: pull.appended, collections: PULL_COLLECTIONS.length + 1 };
+}

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

@@ -0,0 +1,2 @@
+import { type TwinEmitter } from '@volter/world-core';
+export declare const stripeEmitter: TwinEmitter;

package/dist/src/stripe-emit.js

@@ -0,0 +1,145 @@
+// The Stripe DELIVER verb — `world-stripe emit` (feature-sweep friction: hand-constructing
+// checkout.session.completed / invoice.paid envelopes + HMAC signing to poke an app's webhook
+// handler). This is the pack side of the kernel's emit seam (@volter/world-core emit.ts): the
+// catalog of emittable event types, endpoint registrations read FROM TWIN STATE AT REST
+// (webhook_endpoint rows minted by POST /v1/webhook_endpoints — the CLI runs in its own
+// process, so the in-memory delivery registry in stripe-events.ts does not apply), and
+// synthesis of the exact envelope real Stripe delivers, signed with the DESTINATION
+// endpoint's own whsec_twin_* so `stripe.webhooks.constructEvent(rawBody, header, secret)`
+// in the app's unmodified SDK verifies the delivery unchanged.
+//
+// DELIVER does not transition state: it snapshots the subject AS IT IS in the twin and fires
+// the named event about it. Completing a checkout session / paying an invoice is the twin
+// API's job; this verb answers "my app's webhook handler needs to SEE the event, now."
+import { projectResources, worldNow } from '@volter/world-core';
+import { OBJECT_NAME, PLATFORM_ACCOUNT_ID, TWIN_API_VERSION, view } from "./stripe-twin.js";
+import { STRIPE_WEBHOOK_FALLBACK_SECRET, generateTestHeaderString } from "./stripe-events.js";
+import { render } from "./stripe-version.js";
+const SERVICE = 'stripe';
+// event type → the twin resource type whose current state becomes `data.object`.
+// The catalog is every event type the twin's own write path can produce (eventTypeFor's
+// range) — the emit verb can re-fire anything the twin emits organically.
+const EMITTABLE = {
+    // payment intents
+    'payment_intent.created': 'payment_intent',
+    'payment_intent.succeeded': 'payment_intent',
+    'payment_intent.processing': 'payment_intent',
+    'payment_intent.requires_action': 'payment_intent',
+    'payment_intent.amount_capturable_updated': 'payment_intent',
+    'payment_intent.payment_failed': 'payment_intent',
+    'payment_intent.canceled': 'payment_intent',
+    // charges + disputes
+    'charge.succeeded': 'charge',
+    'charge.failed': 'charge',
+    'charge.captured': 'charge',
+    'charge.refunded': 'charge',
+    'charge.dispute.created': 'dispute',
+    // customers
+    'customer.created': 'customer',
+    'customer.updated': 'customer',
+    'customer.deleted': 'customer',
+    // checkout — the sweep's exact pain
+    'checkout.session.completed': 'checkout_session',
+    // invoices — the sweep's exact pain
+    'invoice.created': 'invoice',
+    'invoice.finalized': 'invoice',
+    'invoice.paid': 'invoice',
+    'invoice.payment_failed': 'invoice',
+    'invoice.voided': 'invoice',
+    'invoice.marked_uncollectible': 'invoice',
+    'invoice.sent': 'invoice',
+    // subscriptions
+    'customer.subscription.created': 'subscription',
+    'customer.subscription.updated': 'subscription',
+    'customer.subscription.deleted': 'subscription',
+    'customer.subscription.paused': 'subscription',
+    'customer.subscription.resumed': 'subscription',
+    // payment methods
+    'payment_method.attached': 'payment_method',
+    'payment_method.detached': 'payment_method',
+    // setup intents
+    'setup_intent.created': 'setup_intent',
+    'setup_intent.succeeded': 'setup_intent',
+    // payouts, catalog
+    'payout.created': 'payout',
+    'payout.paid': 'payout',
+    'payout.canceled': 'payout',
+    'price.created': 'price',
+    'product.created': 'product',
+    // issuing — the settlement consumer's diet (issuing_transaction.created) plus the
+    // authorization/card/cardholder lifecycle. issuing_authorization.request is emittable
+    // too: DELIVER re-fires the request event about an authorization AS IT IS in twin state
+    // (the organic synchronous leg lives in the present-authorization flow; this verb lets
+    // an app's handler see the event again without re-presenting).
+    'issuing_authorization.created': 'issuing_authorization',
+    'issuing_authorization.request': 'issuing_authorization',
+    'issuing_authorization.updated': 'issuing_authorization',
+    'issuing_card.created': 'issuing_card',
+    'issuing_card.updated': 'issuing_card',
+    'issuing_cardholder.created': 'issuing_cardholder',
+    'issuing_cardholder.updated': 'issuing_cardholder',
+    'issuing_transaction.created': 'issuing_transaction',
+};
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+function liveEndpointRows(root) {
+    return rows('webhook_endpoint', root).filter((w) => w.deleted !== true);
+}
+let emitSeq = 0;
+export const stripeEmitter = {
+    vendor: 'stripe',
+    events() {
+        return Object.entries(EMITTABLE).map(([type, subjectType]) => ({ type, subjectType }));
+    },
+    endpoints(root) {
+        return liveEndpointRows(root).map((w) => ({
+            id: String(w.id),
+            url: String(w.url ?? ''),
+            ...(Array.isArray(w.enabled_events) ? { enabledEvents: w.enabled_events.map(String) } : {}),
+        }));
+    },
+    subjects(subjectType, root) {
+        return rows(subjectType, root).filter((r) => r.deleted !== true).map((r) => String(r.id));
+    },
+    synthesize({ type, subjectId, endpoint, root, occurredAt }) {
+        const subjectType = EMITTABLE[type];
+        if (!subjectType)
+            throw new Error(`emit: the stripe pack cannot synthesize "${type}".`);
+        const row = rows(subjectType, root).find((r) => String(r.id) === subjectId && r.deleted !== true);
+        if (!row) {
+            const have = stripeEmitter.subjects(subjectType, root);
+            throw new Error(`emit: no ${subjectType} "${subjectId}" in stripe twin state — cannot synthesize ${type}. ` +
+                (have.length ? `${subjectType} ids in state: ${have.join(', ')}.` : `No ${subjectType} exists in this twin yet (object name: ${OBJECT_NAME[subjectType] ?? subjectType}) — create one through the vendor API first.`));
+        }
+        // The endpoint's own signing secret, from its state row (real Stripe signs per-endpoint).
+        const endpointRow = liveEndpointRows(root).find((w) => String(w.id) === endpoint.id || String(w.url) === endpoint.url);
+        const secret = typeof endpointRow?.secret === 'string' && endpointRow.secret ? endpointRow.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
+        const created = occurredAt ? Math.floor(Date.parse(occurredAt) / 1000) : Math.floor(Date.parse(worldNow()) / 1000);
+        // a connected account's object is its event's, as the write path scopes it (stripe-twin.ts afterStripeWrite): the
+        // account itself, or a row kept on its books (`_account`). "Each event for a connected account contains a top-level
+        // `account` property that identifies the connected account" (docs.stripe.com/connect/webhooks).
+        const account = typeof row._account === 'string' ? row._account : subjectType === 'account' && String(row.id) !== PLATFORM_ACCOUNT_ID ? String(row.id) : undefined;
+        // Same envelope persistStripeEvent stores for GET /v1/events; `evt_twin_emit_*` marks it
+        // operator-fired (never colliding with the write path's organic `evt_twin_<n>` ids).
+        const event = {
+            id: `evt_twin_emit_${created}_${++emitSeq}`,
+            object: 'event',
+            api_version: TWIN_API_VERSION,
+            created,
+            data: { object: view(subjectType, row) },
+            livemode: false,
+            pending_webhooks: 1,
+            request: { id: null, idempotency_key: null },
+            type,
+            ...(account ? { account } : {}),
+        };
+        const payload = JSON.stringify(render(event, TWIN_API_VERSION));
+        const header = generateTestHeaderString({ payload, secret, ...(occurredAt ? { timestamp: created } : {}) });
+        return {
+            payload,
+            headers: { 'content-type': 'application/json', 'stripe-signature': header },
+            event,
+        };
+    },
+};

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

@@ -0,0 +1,93 @@
+export type StripeEvent = {
+    id: string;
+    object: 'event';
+    type: string;
+    created: number;
+    livemode: false;
+    /** the connected account a Connect event is from */
+    account?: string;
+    data: {
+        object: Record<string, unknown>;
+    };
+};
+export type StripeWebhookEndpointResponse = {
+    status: number;
+    body: string;
+};
+export type StripeEventDelivery = (url: string, event: StripeEvent, secret?: string) => Promise<void | StripeWebhookEndpointResponse> | void | StripeWebhookEndpointResponse;
+/** A webhook endpoint a World holds in its tree: where to POST, what to sign with, what it subscribed to. */
+export type StripeWebhookTarget = {
+    url: string;
+    secret?: string;
+    enabledEvents?: string[]; /** a Connect endpoint (`connect: true`): events from connected accounts */
+    connect?: boolean;
+};
+/** HMAC-SHA256(secret, `${timestamp}.${payload}`) as lowercase hex — Stripe's v1 signature. */
+export declare function computeStripeSignature(payload: string, secret: string, timestamp: number): string;
+/** Build a `Stripe-Signature` header value for `payload` (mirrors generateTestHeaderString). */
+export declare function generateTestHeaderString(opts: {
+    payload: string;
+    secret: string;
+    timestamp?: number;
+    scheme?: string;
+}): string;
+export declare class StripeSignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Verify a webhook payload + signature header against the signing secret and return the
+ * parsed event (mirrors `stripe.webhooks.constructEvent`). Throws a
+ * StripeSignatureVerificationError on a malformed/missing header, a signature that does
+ * not match, or (when `tolerance` is given) a timestamp outside the allowed window.
+ */
+export declare function constructEvent(payload: string, header: string, secret: string, opts?: {
+    tolerance?: number;
+    now?: number;
+}): StripeEvent;
+export declare const STRIPE_WEBHOOK_FALLBACK_SECRET = "whsec_twin_default";
+export declare function registerStripeWebhook(url: string, secret?: string, enabledEvents?: string[]): void;
+export declare function unregisterStripeWebhook(url: string): void;
+export declare function clearStripeWebhooks(): void;
+export declare function stripeEventMatches(enabledEvents: unknown, type: string): boolean;
+export declare function listStripeWebhooks(): string[];
+export declare function eventTypeFor(operation: string): string | null;
+/** Install a default deliverer used by the write path when no per-call `deliver` is passed. */
+export declare function setStripeEventDelivery(deliver: StripeEventDelivery | null): void;
+export declare const STRIPE_REALTIME_AUTH_TIMEOUT_MS = 2000;
+export type StripeAuthRequestOutcome = {
+    kind: 'approved';
+    amount?: number;
+} | {
+    kind: 'declined';
+} | {
+    kind: 'timeout';
+    message: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Deliver an issuing_authorization.request event to the enrolled endpoint and interpret
+ * its synchronous response as the authorization decision. Honors the installed test
+ * deliverer (setStripeEventDelivery) so verifies run fully offline: a fake returning a
+ * {status, body} response drives the decision; a fake that throws a TimeoutError (the
+ * exact error AbortSignal.timeout produces) exercises the timeout fallback.
+ */
+export declare function requestAuthorizationDecision(url: string, event: StripeEvent, secret: string): Promise<StripeAuthRequestOutcome>;
+/**
+ * Emit a Stripe event for a twin write to registered endpoints. `resource` is the
+ * Stripe object the event is about. `occurredAt` is caller-supplied (deterministic).
+ * Returns the delivered events (for assertions); no-op when nothing is registered
+ * or the operation has no mapped event type.
+ *
+ * Fan-out filters by each endpoint's registered enabled_events (stripeEventMatches — '*',
+ * 'family.*', exact), like the vendor: a consumer enrolled for one event type receives
+ * only that type. A URL registered without a list (test seam) receives everything.
+ */
+export declare function emitStripeEvent(operation: string, resource: Record<string, unknown>, opts?: {
+    occurredAt: string;
+    deliver?: StripeEventDelivery;
+    endpoints?: StripeWebhookTarget[];
+    account?: string; /** the id the stored event takes (afterStripeWrite) */
+    id?: string;
+}): Promise<StripeEvent[]>;