@volter/twin-stripe 2.0.1 → 2.0.3

package/dist/src/stripe-capabilities.js

@@ -213,6 +213,20 @@ export const STRIPE_CAPABILITIES = [
         const l = await h({ m: 'GET', p: '/v1/customers' });
         return ok(g) && id(g) === id(c) && ok(u) && field(u, 'name') === 'Ada Lovelace' && field(l, 'object') === 'list';
     })),
+    // stripe-node posts a null metadata value as `metadata[key]=` (Cal.com's PaymentIntent metadata, a guest with no phone)
+    done('stripe.metadata.create_empty_value_unset', 'metadata', 'A create\'s metadata key posted empty is not set (an empty value unsets a key); metadata posted empty is {}', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/v1/customers', b: 'email=sam@twin.test&metadata[identifier]=cal.com&metadata[bookerPhoneNumber]=' });
+        const pi = await h({ m: 'POST', p: '/v1/payment_intents', b: `amount=5000&currency=usd&customer=${id(c)}&metadata[bookingId]=12&metadata[calAccountId]=` });
+        const none = await h({ m: 'POST', p: '/v1/products', b: 'name=Consultation&metadata=' });
+        const got = await h({ m: 'GET', p: `/v1/payment_intents/${id(pi)}` });
+        const md = (r) => r.body.metadata;
+        return ok(c) && JSON.stringify(md(c)) === JSON.stringify({ identifier: 'cal.com' })
+            && ok(pi) && JSON.stringify(md(pi)) === JSON.stringify({ bookingId: '12' }) && JSON.stringify(md(got)) === JSON.stringify({ bookingId: '12' })
+            && ok(none) && JSON.stringify(md(none)) === '{}';
+    })),
+    // Objects on a connected account are that account's: Stripe answers a retrieve of one without its Stripe-Account
+    // header (or with another account's) 404 resource_missing. The twin keeps one store for the platform and its accounts.
+    todo('stripe.connect.account_scoped_objects', 'connect', 'Objects made with a Stripe-Account header are visible only as that account (retrieve/list/update from the platform or another account is resource_missing)', 'api', 'common'),
     done('stripe.customers.list_filter', 'customers', 'Customer list filter by email', 'api', 'core', () => withRoot(async (h) => {
         await h({ m: 'POST', p: '/v1/customers', b: 'email=match@twin.test' });
         await h({ m: 'POST', p: '/v1/customers', b: 'email=other@twin.test' });

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({
@@ -340,6 +346,34 @@ export async function createStripeTwinServer(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, path) {
+    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;
+    if (given === '')
+        metadata = {};
+    else if (given && typeof given === 'object' && !Array.isArray(given) && Object.values(given).includes('')) {
+        metadata = Object.fromEntries(Object.entries(given).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.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.filter((o) => o.class === 'update' && o.method.toUpperCase() === 'POST')
     .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
@@ -365,7 +399,9 @@ async function mergeMetadata(request, coreMerges, scope) {
             break;
         }
     }
-    if (!op?.resource)
+    if (!op)
+        return createMetadata(request, path);
+    if (!op.resource)
         return request;
     const params = await readParams(manifest, request.clone(), op);
     if (!('metadata' in params))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.1"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.1",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",

package/src/stripe-capabilities.ts

@@ -256,6 +256,22 @@ export const STRIPE_CAPABILITIES: CapabilitySpec[] = [
       return ok(g) && id(g) === id(c) && ok(u) && field(u, 'name') === 'Ada Lovelace' && field(l, 'object') === 'list';
     }),
   ),
+  // stripe-node posts a null metadata value as `metadata[key]=` (Cal.com's PaymentIntent metadata, a guest with no phone)
+  done('stripe.metadata.create_empty_value_unset', 'metadata', 'A create\'s metadata key posted empty is not set (an empty value unsets a key); metadata posted empty is {}', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers', b: 'email=sam@twin.test&metadata[identifier]=cal.com&metadata[bookerPhoneNumber]=' });
+      const pi = await h({ m: 'POST', p: '/v1/payment_intents', b: `amount=5000&currency=usd&customer=${id(c)}&metadata[bookingId]=12&metadata[calAccountId]=` });
+      const none = await h({ m: 'POST', p: '/v1/products', b: 'name=Consultation&metadata=' });
+      const got = await h({ m: 'GET', p: `/v1/payment_intents/${id(pi)}` });
+      const md = (r: StripeResponse) => (r.body as Body).metadata as Body;
+      return ok(c) && JSON.stringify(md(c)) === JSON.stringify({ identifier: 'cal.com' })
+        && ok(pi) && JSON.stringify(md(pi)) === JSON.stringify({ bookingId: '12' }) && JSON.stringify(md(got)) === JSON.stringify({ bookingId: '12' })
+        && ok(none) && JSON.stringify(md(none)) === '{}';
+    }),
+  ),
+  // Objects on a connected account are that account's: Stripe answers a retrieve of one without its Stripe-Account
+  // header (or with another account's) 404 resource_missing. The twin keeps one store for the platform and its accounts.
+  todo('stripe.connect.account_scoped_objects', 'connect', 'Objects made with a Stripe-Account header are visible only as that account (retrieve/list/update from the platform or another account is resource_missing)', 'api', 'common'),
   done('stripe.customers.list_filter', 'customers', 'Customer list filter by email', 'api', 'core', () =>
     withRoot(async (h) => {
       await h({ m: 'POST', p: '/v1/customers', b: 'email=match@twin.test' });

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 }> {
@@ -321,6 +327,31 @@ export async function createStripeTwinServer(options: StripeTwinOptions): Promis
   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, '([^/]+)')}/?$`) }));
@@ -339,7 +370,8 @@ async function mergeMetadata(request: Request, coreMerges: (op: DerivedCall['ope
   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?.resource) return request;
+  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;