@volter/twin-stripe 2.0.1 → 2.0.2

package/dist/src/stripe-events.js

@@ -1,4 +1,4 @@
-import { nodeBuiltin, worldNow } from '@volter/world-core';
+import { nodeBuiltin, worldNow, deliveryTraceHeaders } from '@volter/world-core';
 import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 import vendorEvents from './generated/events.gen.json' with { type: 'json' };
@@ -240,7 +240,7 @@ async function postEvent(url, event, payload, secret) {
     for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt += 1) {
         try {
             const header = generateTestHeaderString({ payload, secret });
-            await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header }, body: payload });
+            await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() }, body: payload });
             return;
         }
         catch (error) {
@@ -296,7 +296,7 @@ async function httpAuthRequestDelivery(url, event, secret) {
 async function postAuthRequest(url, payload, header) {
     const res = await appFetch(url, {
         method: 'POST',
-        headers: { 'content-type': 'application/json', 'stripe-signature': header },
+        headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() },
         body: payload,
         signal: AbortSignal.timeout(STRIPE_REALTIME_AUTH_TIMEOUT_MS),
     });

package/dist/src/stripe-mirror-ui.js

@@ -4,11 +4,11 @@
 // 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 } from '@volter/world-core';
+import { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
 import { serveHttp } from '@volter/world-core';
 import { createStripeTwinFetch } from "./stripe-server.js";
-const CLIENT_ENTRY = () => new URL('../client/stripe-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => new URL('../client/stripe-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+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.
 //

package/dist/src/stripe-server.js

@@ -7,7 +7,7 @@
 // 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, readParams, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, derivedRequestScopes, readParams, runAsVendorMove, runWithRequestTrace, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
 import { stripeCheckoutFlow } from "./screens/checkout.js";
 import { stripeJs } from "./stripe-js.js";
 import { stripeFinancialConnectionsFlow } from "./screens/financial-connections.js";
@@ -219,26 +219,29 @@ export function createStripeTwinFetch(options) {
     // 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.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) => {
         if (readOnly)
             return;
-        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);
+        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
@@ -330,7 +333,10 @@ export function createStripeTwinFetch(options) {
         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 });
     };
-    return Object.assign(rendered, { owners: derived.owners });
+    // 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) => runWithRequestTrace(request, () => rendered(request)), { owners: derived.owners }));
 }
 export async function createStripeTwinServer(options) {
     const server = await serveHttp({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Local Stripe twin — a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -56,15 +56,15 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "dependencies": {
-    "@volter/world-ui": "0.1.1",
+    "@volter/world-ui": "0.1.2",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.1"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.1",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",

package/src/stripe-events.ts

@@ -1,4 +1,4 @@
-import { nodeBuiltin, worldNow } from '@volter/world-core';
+import { nodeBuiltin, worldNow, deliveryTraceHeaders } from '@volter/world-core';
 import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 import vendorEvents from './generated/events.gen.json' with { type: 'json' };
@@ -274,7 +274,7 @@ async function postEvent(url: string, event: StripeEvent, payload: string, secre
   for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt += 1) {
     try {
       const header = generateTestHeaderString({ payload, secret });
-      await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header }, body: payload });
+      await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() }, body: payload });
       return;
     } catch (error) {
       last = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
@@ -338,7 +338,7 @@ async function httpAuthRequestDelivery(url: string, event: StripeEvent, secret:
 async function postAuthRequest(url: string, payload: string, header: string): Promise<StripeWebhookEndpointResponse> {
   const res = await appFetch(url, {
     method: 'POST',
-    headers: { 'content-type': 'application/json', 'stripe-signature': header },
+    headers: { 'content-type': 'application/json', 'stripe-signature': header, ...deliveryTraceHeaders() },
     body: payload,
     signal: AbortSignal.timeout(STRIPE_REALTIME_AUTH_TIMEOUT_MS),
   });

package/src/stripe-mirror-ui.ts

@@ -4,12 +4,12 @@
 // 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 } from '@volter/world-core';
+import { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
 import { serveHttp } from '@volter/world-core';
 import { createStripeTwinFetch } from './stripe-server.ts';
 
-const CLIENT_ENTRY = () => new URL('../client/stripe-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => new URL('../client/stripe-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+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.

package/src/stripe-server.ts

@@ -7,7 +7,7 @@
 // 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, readParams, semanticsContext, serveHttp, vendorError, type DerivedCall, type DerivedFetch } from '@volter/world-core';
+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';
@@ -215,25 +215,28 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
   // 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;
-    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);
+    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
@@ -309,7 +312,10 @@ export function createStripeTwinFetch(options: StripeTwinOptions): DerivedFetch
     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 });
   };
-  return Object.assign(rendered, { owners: derived.owners });
+  // 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 }> {