mppx 0.8.19 → 0.9.1

package/dist/server/Mppx.js

@@ -14,11 +14,10 @@ import * as z from '../zod.js';
 import * as Html from './internal/html/config.js';
 import { serviceWorker } from './internal/html/serviceWorker.gen.js';
 import * as Scope from './internal/scope.js';
+import * as SecretKey from './internal/SecretKey.js';
 import * as NodeListener from './NodeListener.js';
 import * as Request from './Request.js';
 import * as Transport from './Transport.js';
-const minimumSecretKeyBytes = 32;
-const secretKeyGenerationCommand = 'openssl rand -base64 32';
 const reservedMppxKeyValues = [
     'challenge',
     'compose',
@@ -52,11 +51,12 @@ export const reservedMppxKeys = new Set(reservedMppxKeyValues);
  * ```
  */
 export function create(config) {
-    const { attestation, realm = Env.get('realm'), selectOffers, secretKey = Env.get('secretKey'), transport = Transport.http(), } = config;
+    const { attestation, requiresAuth, realm = Env.get('realm'), selectOffers, secretKey = Env.get('secretKey'), transport = Transport.http({ requiresAuth }), } = config;
+    const credentialHeader = requiresAuth ? Constants.Headers.paymentAuthorization : undefined;
     if (!secretKey) {
         throw new Error('Missing secret key. Set the MPP_SECRET_KEY environment variable or pass `secretKey` to Mppx.create().');
     }
-    assertSecretKey(secretKey);
+    SecretKey.assert(secretKey);
     const methods = config.methods.flat();
     const serverEvents = createServerEventDispatcher();
     const verifyAttestation = attestation
@@ -73,6 +73,7 @@ export function create(config) {
                         input: ctx.input,
                         receipt: ctx.receipt,
                         request: ctx.request,
+                        ...(ctx.requestInput !== undefined && { requestInput: ctx.requestInput }),
                     });
                 }
             }));
@@ -83,6 +84,7 @@ export function create(config) {
         const fn = createMethodFn({
             ...(verifyAttestation && { attest: verifyAttestation }),
             authorize: mi.authorize,
+            credentialHeader,
             defaults: mi.defaults,
             method: mi,
             realm,
@@ -143,6 +145,7 @@ export function create(config) {
         if (!challengeHandlers[mi.name])
             challengeHandlers[mi.name] = {};
         challengeHandlers[mi.name][mi.alias ?? mi.intent] = createChallengeFn({
+            credentialHeader,
             defaults: mi.defaults,
             method: mi,
             realm,
@@ -235,6 +238,7 @@ export function create(config) {
                     credential: parsedCredential,
                     defaults: mi.defaults,
                     expires: credential.challenge.expires,
+                    header: credential.challenge.header,
                     meta: expectedMeta,
                     method: mi,
                     realm: expectedRealm,
@@ -277,6 +281,7 @@ export function create(config) {
             parsedCredential,
             parsedRequest,
             request,
+            requestInput: shouldValidateRoute ? request : undefined,
         };
     }
     async function validateCredentialFn(input, options) {
@@ -290,7 +295,7 @@ export function create(config) {
     // broadcastCredential: single-call end-to-end validation and broadcast
     async function broadcastCredentialFn(input, options) {
         const prepared = await prepareStandaloneCredential(input, options, { emitFailures: true });
-        const { method: mi, parsedCredential, parsedRequest, request, envelope } = prepared;
+        const { method: mi, parsedCredential, parsedRequest, request, requestInput, envelope, } = prepared;
         const emitStandalonePaymentFailed = async (parameters) => {
             await serverEvents.emit('payment.failed', createPaymentFailedContext({
                 capturedRequest: options?.capturedRequest,
@@ -310,7 +315,7 @@ export function create(config) {
             receipt = await broadcast({ credential: parsedCredential, envelope, request });
         }
         catch (e) {
-            const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
+            const error = e instanceof Errors.PaymentError ? e : new Errors.InternalPaymentError();
             await emitStandalonePaymentFailed({
                 challenge: prepared.credential.challenge,
                 credential: parsedCredential,
@@ -328,6 +333,7 @@ export function create(config) {
             method: mi,
             receipt,
             request: parsedRequest,
+            ...(requestInput !== undefined && { requestInput }),
         }));
         return receipt;
     }
@@ -375,15 +381,9 @@ export function create(config) {
         ...handlers,
     };
 }
-function assertSecretKey(secretKey) {
-    const byteLength = new TextEncoder().encode(secretKey).byteLength;
-    if (byteLength >= minimumSecretKeyBytes)
-        return;
-    throw new Error(`Secret key must be at least ${minimumSecretKeyBytes} bytes. Generate one with \`${secretKeyGenerationCommand}\` and set MPP_SECRET_KEY or pass it to Mppx.create().`);
-}
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters) {
-    const { attest, authorize, defaults, events, method, preflight, realm, respond, secretKey, broadcast, stableBinding, transport, validate, verify, } = parameters;
+    const { attest, authorize, credentialHeader, defaults, events, method, preflight, realm, respond, secretKey, broadcast, stableBinding, transport, validate, verify, } = parameters;
     return (options) => {
         const { description, meta, scope, ...rest } = options;
         const staticMeta = Scope.merge({ meta, scope });
@@ -491,6 +491,7 @@ function createMethodFn(parameters) {
                 defaults,
                 description,
                 expires,
+                header: credentialHeader,
                 meta: effectiveMeta,
                 method,
                 realm,
@@ -505,6 +506,7 @@ function createMethodFn(parameters) {
                     defaults: defaults ?? {},
                     description,
                     expires,
+                    header: credentialHeader,
                     meta: effectiveMeta,
                     method,
                     realm,
@@ -549,7 +551,11 @@ function createMethodFn(parameters) {
             // Credential was provided but malformed
             if (credentialError) {
                 const reason = getSafeCredentialReason(credentialError);
-                const error = new Errors.MalformedCredentialError(reason ? { reason } : {});
+                const error = credentialError instanceof Errors.PaymentError
+                    ? credentialError
+                    : reason
+                        ? new Errors.MalformedCredentialError({ reason })
+                        : new Errors.InternalPaymentError();
                 await emitPaymentFailed({
                     challenge,
                     credential: null,
@@ -611,6 +617,7 @@ function createMethodFn(parameters) {
                                 method,
                                 receipt: authorized.receipt,
                                 request: parsedRequest,
+                                requestInput: request,
                             }));
                             return success(authorized.receipt, {
                                 managementResponse: authorized.response,
@@ -620,7 +627,7 @@ function createMethodFn(parameters) {
                     catch (e) {
                         if (!(e instanceof Errors.PaymentError))
                             console.error('mppx: internal authorization error', e);
-                        const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
+                        const error = e instanceof Errors.PaymentError ? e : new Errors.InternalPaymentError();
                         await emitPaymentFailed({
                             challenge,
                             credential: null,
@@ -793,7 +800,7 @@ function createMethodFn(parameters) {
             catch (e) {
                 if (!(e instanceof Errors.PaymentError))
                     console.error('mppx: internal verification error', e);
-                const error = e instanceof Errors.PaymentError ? e : new Errors.VerificationFailedError();
+                const error = e instanceof Errors.PaymentError ? e : new Errors.InternalPaymentError();
                 await emitPaymentFailed({
                     challenge,
                     credential: parsedCredential,
@@ -833,6 +840,7 @@ function createMethodFn(parameters) {
                 method,
                 receipt: receiptData,
                 request: parsedRequest,
+                requestInput: request,
             }));
             return success(receiptData, {
                 challengeId: credential.challenge.id,
@@ -850,7 +858,7 @@ function createMethodFn(parameters) {
  * but returns a Challenge object directly instead of a request handler.
  */
 function createChallengeFn(parameters) {
-    const { defaults, method, realm, secretKey } = parameters;
+    const { credentialHeader, defaults, method, realm, secretKey } = parameters;
     return async (options) => {
         const { description, meta, scope, ...rest } = options;
         const effectiveMeta = Scope.merge({ meta, scope });
@@ -861,6 +869,7 @@ function createChallengeFn(parameters) {
             defaults,
             description,
             expires,
+            header: credentialHeader,
             meta: effectiveMeta,
             method,
             realm,
@@ -991,6 +1000,9 @@ function createPaymentSuccessContext(parameters) {
         method: snapshotMethod(parameters.method),
         receipt: snapshotValue(parameters.receipt),
         request: snapshotValue(parameters.request),
+        ...(parameters.requestInput !== undefined && {
+            requestInput: snapshotValue(parameters.requestInput),
+        }),
     });
 }
 function snapshotMethod(method) {
@@ -1035,8 +1047,65 @@ function snapshotValue(value) {
         return freezeSnapshot(structuredClone(value));
     }
     catch {
-        return freezeSnapshot(value);
+        return freezeSnapshot(cloneSnapshotFallback(value));
+    }
+}
+/**
+ * Copies object containers when `structuredClone` rejects callable values.
+ * Functions remain callable references, while their containing request data is
+ * detached so snapshot freezing and nested writes cannot affect hook-owned
+ * objects.
+ */
+function cloneSnapshotFallback(value, seen = new WeakMap()) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const existing = seen.get(value);
+    if (existing)
+        return existing;
+    if (value instanceof Date)
+        return new Date(value);
+    if (value instanceof RegExp)
+        return new RegExp(value.source, value.flags);
+    if (value instanceof URL)
+        return new URL(value);
+    if (value instanceof Headers)
+        return new Headers(value);
+    if (value instanceof ArrayBuffer)
+        return value.slice(0);
+    if (ArrayBuffer.isView(value)) {
+        const buffer = new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice().buffer;
+        if (value instanceof DataView)
+            return new DataView(buffer);
+        const Constructor = value.constructor;
+        return new Constructor(buffer);
+    }
+    if (value instanceof Map) {
+        const snapshot = new Map();
+        seen.set(value, snapshot);
+        for (const [key, entry] of value)
+            snapshot.set(cloneSnapshotFallback(key, seen), cloneSnapshotFallback(entry, seen));
+        return snapshot;
+    }
+    if (value instanceof Set) {
+        const snapshot = new Set();
+        seen.set(value, snapshot);
+        for (const entry of value)
+            snapshot.add(cloneSnapshotFallback(entry, seen));
+        return snapshot;
+    }
+    const snapshot = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
+    seen.set(value, snapshot);
+    for (const key of Reflect.ownKeys(value)) {
+        if (Array.isArray(value) && key === 'length')
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor)
+            continue;
+        if ('value' in descriptor)
+            descriptor.value = cloneSnapshotFallback(descriptor.value, seen);
+        Object.defineProperty(snapshot, key, descriptor);
     }
+    return snapshot;
 }
 function snapshotInputProperty(input) {
     if (input === undefined)
@@ -1163,6 +1232,7 @@ async function resolveRouteChallenge(parameters) {
     const challenge = Challenge.fromMethod(parameters.method, {
         description: parameters.description,
         expires: parameters.expires,
+        header: parameters.header,
         meta: parameters.meta,
         realm: effectiveRealm,
         request: request,
@@ -1178,6 +1248,7 @@ function createFallbackChallenge(parameters) {
     return Challenge.fromMethod(parameters.method, {
         description: parameters.description,
         expires: parameters.expires,
+        header: parameters.header,
         meta: parameters.meta,
         realm: parameters.realm ??
             (parameters.capturedRequest
@@ -1405,8 +1476,9 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         // Try to extract a Payment credential to decide whether to dispatch or challenge.
         // Only gate on the Payment scheme — other auth schemes (Bearer, Basic, etc.)
         // should fall through to the merged-402 path so all offers are presented.
-        const header = input.headers.get(Constants.Headers.authorization);
-        const paymentHeader = header ? Credential.extractPaymentScheme(header) : null;
+        const paymentHeader = Array.from(input.headers.values())
+            .map((value) => Credential.extractPaymentScheme(value))
+            .find((value) => value !== null);
         if (paymentHeader) {
             // Parse the credential to find method+intent for dispatch.
             let credential;

package/dist/server/Transport.d.ts

@@ -89,11 +89,17 @@ export declare function from<input = unknown, challengeOutput = unknown, receipt
 /**
  * HTTP transport for server-side payment handling.
  *
- * - Reads credentials from the `Authorization` header
+ * - Reads credentials from the configured payment credential header
  * - Issues challenges via `WWW-Authenticate` header with 402 status
  * - Attaches receipts via `Payment-Receipt` header
  */
-export declare function http(): Http;
+export declare function http(options?: http.Options): Http;
+export declare namespace http {
+    type Options = {
+        /** Uses `Payment-Authorization` for Payment credentials so `Authorization` remains available for application authentication. */
+        requiresAuth?: boolean | undefined;
+    };
+}
 /**
  * MCP transport for server-side payment handling with raw JSON-RPC.
  *

package/dist/server/Transport.js

@@ -1,8 +1,8 @@
 import * as Challenge from '../Challenge.js';
 import * as Constants from '../Constants.js';
 import * as Credential from '../Credential.js';
-import * as Errors from '../Errors.js';
 import * as core_Mcp from '../Mcp.js';
+import * as McpCredential from '../mcp/internal/Credential.js';
 import * as Receipt from '../Receipt.js';
 import * as Html from './internal/html/config.js';
 import { serviceWorker } from './internal/html/serviceWorker.gen.js';
@@ -29,11 +29,14 @@ export function from(transport) {
 /**
  * HTTP transport for server-side payment handling.
  *
- * - Reads credentials from the `Authorization` header
+ * - Reads credentials from the configured payment credential header
  * - Issues challenges via `WWW-Authenticate` header with 402 status
  * - Attaches receipts via `Payment-Receipt` header
  */
-export function http() {
+export function http(options = {}) {
+    const credentialHeader = options.requiresAuth
+        ? Constants.Headers.paymentAuthorization
+        : Constants.Headers.authorization;
     return from({
         name: 'http',
         captureRequest(request) {
@@ -45,7 +48,7 @@ export function http() {
             };
         },
         getCredential(request) {
-            const header = request.headers.get(Constants.Headers.authorization);
+            const header = request.headers.get(credentialHeader);
             if (!header)
                 return null;
             const payment = Credential.extractPaymentScheme(header);
@@ -144,17 +147,20 @@ export function mcp() {
         },
         getCredential(request) {
             const meta = request.params?._meta;
-            const credential = meta?.[core_Mcp.credentialMetaKey];
-            if (!credential)
+            const value = meta?.[core_Mcp.credentialMetaKey];
+            if (value === undefined)
                 return null;
-            return credential;
+            const parsed = McpCredential.parse(value);
+            if (!parsed)
+                throw new Credential.InvalidCredentialEncodingError();
+            return parsed.value;
         },
         respondChallenge({ challenge, input, error }) {
             return {
                 jsonrpc: '2.0',
                 id: input.id,
                 error: {
-                    code: mcpErrorCode(error),
+                    code: core_Mcp.errorCode(error),
                     message: error?.message ?? 'Payment Required',
                     data: {
                         httpStatus: error?.status ?? 402,
@@ -184,16 +190,6 @@ export function mcp() {
         },
     });
 }
-/** @internal */
-function mcpErrorCode(error) {
-    if (!error)
-        return core_Mcp.paymentRequiredCode;
-    if (error instanceof Errors.MalformedCredentialError)
-        return -32602;
-    if (error instanceof Errors.PaymentRequiredError)
-        return core_Mcp.paymentRequiredCode;
-    return core_Mcp.paymentVerificationFailedCode;
-}
 export function safeUrl(url) {
     try {
         if (url instanceof URL)

package/dist/server/internal/SecretKey.d.ts

@@ -0,0 +1,3 @@
+/** Validates the minimum entropy required for HMAC-bound payment challenges. */
+export declare function assert(secretKey: string): void;
+//# sourceMappingURL=SecretKey.d.ts.map

package/dist/server/internal/SecretKey.js

@@ -0,0 +1,9 @@
+const minimumBytes = 32;
+const generationCommand = 'openssl rand -base64 32';
+/** Validates the minimum entropy required for HMAC-bound payment challenges. */
+export function assert(secretKey) {
+    if (new TextEncoder().encode(secretKey).byteLength >= minimumBytes)
+        return;
+    throw new Error(`Secret key must be at least ${minimumBytes} bytes. Generate one with \`${generationCommand}\` and set MPP_SECRET_KEY or pass it to Mppx.create().`);
+}
+//# sourceMappingURL=SecretKey.js.map

package/dist/server/internal/html/serviceWorker.client.d.ts

@@ -1,2 +1,2 @@
-export declare function submitCredential(credential: string): Promise<void>;
+export declare function submitCredential(credential: string, header?: string): Promise<void>;
 //# sourceMappingURL=serviceWorker.client.d.ts.map

package/dist/server/internal/html/serviceWorker.client.js

@@ -1,5 +1,5 @@
 import { params } from './constants.js';
-export async function submitCredential(credential) {
+export async function submitCredential(credential, header = 'Authorization') {
     const url = new URL(location.href);
     url.searchParams.set(params.serviceWorker, '');
     const registration = await navigator.serviceWorker.register(url.pathname + url.search);
@@ -19,7 +19,7 @@ export async function submitCredential(credential) {
     await new Promise((resolve) => {
         const channel = new MessageChannel();
         channel.port1.onmessage = () => resolve();
-        serviceWorker.postMessage({ credential }, [channel.port2]);
+        serviceWorker.postMessage({ credential, header }, [channel.port2]);
     });
     location.reload();
 }

package/dist/server/internal/html/serviceWorker.gen.d.ts

@@ -1,2 +1,2 @@
-export declare const serviceWorker = "(function(){let e=self,t;e.addEventListener(`activate`,t=>{t.waitUntil(e.clients.claim())}),e.addEventListener(`message`,e=>{if(!e.source)return;let n=e.data?.credential;typeof n!=`string`||!n.startsWith(`Payment `)||(t=n,e.ports[0]?.postMessage(`ack`))}),e.addEventListener(`fetch`,n=>{if(!t||n.request.mode!==`navigate`||new URL(n.request.url).origin!==e.location.origin)return;let r=new Headers(n.request.headers);r.set(`Authorization`,t),t=void 0,n.respondWith(fetch(n.request,{headers:r})),e.registration.unregister()})})();";
+export declare const serviceWorker = "(function(){let e=self,t,n=`Authorization`;e.addEventListener(`activate`,t=>{t.waitUntil(e.clients.claim())}),e.addEventListener(`message`,e=>{if(!e.source)return;let r=e.data?.credential;typeof r!=`string`||!r.startsWith(`Payment `)||(t=r,typeof e.data?.header==`string`&&(n=e.data.header),e.ports[0]?.postMessage(`ack`))}),e.addEventListener(`fetch`,r=>{if(!t||r.request.mode!==`navigate`||new URL(r.request.url).origin!==e.location.origin)return;let i=new Headers(r.request.headers);i.set(n,t),t=void 0,r.respondWith(fetch(r.request,{headers:i})),e.registration.unregister()})})();";
 //# sourceMappingURL=serviceWorker.gen.d.ts.map

package/dist/server/internal/html/serviceWorker.gen.js

@@ -1,3 +1,3 @@
 // Generated — do not edit.
-export const serviceWorker = "(function(){let e=self,t;e.addEventListener(`activate`,t=>{t.waitUntil(e.clients.claim())}),e.addEventListener(`message`,e=>{if(!e.source)return;let n=e.data?.credential;typeof n!=`string`||!n.startsWith(`Payment `)||(t=n,e.ports[0]?.postMessage(`ack`))}),e.addEventListener(`fetch`,n=>{if(!t||n.request.mode!==`navigate`||new URL(n.request.url).origin!==e.location.origin)return;let r=new Headers(n.request.headers);r.set(`Authorization`,t),t=void 0,n.respondWith(fetch(n.request,{headers:r})),e.registration.unregister()})})();";
+export const serviceWorker = "(function(){let e=self,t,n=`Authorization`;e.addEventListener(`activate`,t=>{t.waitUntil(e.clients.claim())}),e.addEventListener(`message`,e=>{if(!e.source)return;let r=e.data?.credential;typeof r!=`string`||!r.startsWith(`Payment `)||(t=r,typeof e.data?.header==`string`&&(n=e.data.header),e.ports[0]?.postMessage(`ack`))}),e.addEventListener(`fetch`,r=>{if(!t||r.request.mode!==`navigate`||new URL(r.request.url).origin!==e.location.origin)return;let i=new Headers(r.request.headers);i.set(n,t),t=void 0,r.respondWith(fetch(r.request,{headers:i})),e.registration.unregister()})})();";
 //# sourceMappingURL=serviceWorker.gen.js.map

package/dist/stripe/Methods.d.ts

@@ -22,6 +22,9 @@ export declare const charge: {
             externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
             metadata: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
             networkId: z.ZodMiniString<string>;
+            paymentIntentOptions: z.ZodMiniOptional<z.ZodMiniObject<{
+                metadata: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+            }, z.core.$strip>>;
             paymentMethodTypes: z.ZodMiniArray<z.ZodMiniString<string>>;
             recipient: z.ZodMiniOptional<z.ZodMiniString<string>>;
         }, z.core.$strip>, z.ZodMiniTransform<{
@@ -43,6 +46,9 @@ export declare const charge: {
             externalId?: string | undefined;
             metadata?: Record<string, string> | undefined;
             networkId: string;
+            paymentIntentOptions?: {
+                metadata: Record<string, string>;
+            } | undefined;
             paymentMethodTypes: string[];
             recipient?: string | undefined;
         }>>;

package/dist/stripe/Methods.js

@@ -1,6 +1,7 @@
 import { parseUnits } from 'viem';
 import * as Method from '../Method.js';
 import * as z from '../zod.js';
+import * as PaymentIntent from './internal/payment-intent.js';
 /**
  * Stripe charge intent for one-time payments via Shared Payment Tokens (SPTs).
  *
@@ -24,9 +25,10 @@ export const charge = Method.from({
             externalId: z.optional(z.string()),
             metadata: z.optional(z.record(z.string(), z.string())),
             networkId: z.string(),
+            paymentIntentOptions: z.optional(PaymentIntent.Schema),
             paymentMethodTypes: z.array(z.string()).check(z.minLength(1)),
             recipient: z.optional(z.string()),
-        }), z.transform(({ amount, decimals, metadata, networkId, paymentMethodTypes, ...rest }) => ({
+        }), z.transform(({ amount, decimals, metadata, networkId, paymentIntentOptions: _, paymentMethodTypes, ...rest }) => ({
             ...rest,
             amount: parseUnits(amount, decimals).toString(),
             methodDetails: {

package/dist/stripe/client/Charge.d.ts

@@ -55,6 +55,9 @@ export declare function charge(parameters: charge.Parameters): Method.Client<{
             externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
             metadata: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
             networkId: z.ZodMiniString<string>;
+            paymentIntentOptions: z.ZodMiniOptional<z.ZodMiniObject<{
+                metadata: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+            }, z.core.$strip>>;
             paymentMethodTypes: z.ZodMiniArray<z.ZodMiniString<string>>;
             recipient: z.ZodMiniOptional<z.ZodMiniString<string>>;
         }, z.core.$strip>, z.ZodMiniTransform<{
@@ -76,6 +79,9 @@ export declare function charge(parameters: charge.Parameters): Method.Client<{
             externalId?: string | undefined;
             metadata?: Record<string, string> | undefined;
             networkId: string;
+            paymentIntentOptions?: {
+                metadata: Record<string, string>;
+            } | undefined;
             paymentMethodTypes: string[];
             recipient?: string | undefined;
         }>>;

package/dist/stripe/client/Methods.d.ts

@@ -42,6 +42,9 @@ export declare function stripe(parameters: stripe.Parameters): readonly [import(
             externalId: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
             metadata: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniRecord<import("zod/mini").ZodMiniString<string>, import("zod/mini").ZodMiniString<string>>>;
             networkId: import("zod/mini").ZodMiniString<string>;
+            paymentIntentOptions: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniObject<{
+                metadata: import("zod/mini").ZodMiniRecord<import("zod/mini").ZodMiniString<string>, import("zod/mini").ZodMiniString<string>>;
+            }, import("zod/v4/core").$strip>>;
             paymentMethodTypes: import("zod/mini").ZodMiniArray<import("zod/mini").ZodMiniString<string>>;
             recipient: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniString<string>>;
         }, import("zod/v4/core").$strip>, import("zod/mini").ZodMiniTransform<{
@@ -63,6 +66,9 @@ export declare function stripe(parameters: stripe.Parameters): readonly [import(
             externalId?: string | undefined;
             metadata?: Record<string, string> | undefined;
             networkId: string;
+            paymentIntentOptions?: {
+                metadata: Record<string, string>;
+            } | undefined;
             paymentMethodTypes: string[];
             recipient?: string | undefined;
         }>>;

package/dist/stripe/internal/payment-intent.d.ts

@@ -0,0 +1,7 @@
+import * as z from '../../zod.js';
+/** Stripe PaymentIntent options accepted only by server-side method input. */
+export declare const Schema: z.ZodMiniObject<{
+    metadata: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+}, z.core.$strip>;
+export type Options = z.infer<typeof Schema>;
+//# sourceMappingURL=payment-intent.d.ts.map

package/dist/stripe/internal/payment-intent.js

@@ -0,0 +1,6 @@
+import * as z from '../../zod.js';
+/** Stripe PaymentIntent options accepted only by server-side method input. */
+export const Schema = z.object({
+    metadata: z.record(z.string(), z.string()),
+});
+//# sourceMappingURL=payment-intent.js.map

package/dist/stripe/server/Charge.d.ts

@@ -49,6 +49,9 @@ export declare function charge<const parameters extends charge.Parameters>(param
             externalId: z.ZodMiniOptional<z.ZodMiniString<string>>;
             metadata: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
             networkId: z.ZodMiniString<string>;
+            paymentIntentOptions: z.ZodMiniOptional<z.ZodMiniObject<{
+                metadata: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+            }, z.core.$strip>>;
             paymentMethodTypes: z.ZodMiniArray<z.ZodMiniString<string>>;
             recipient: z.ZodMiniOptional<z.ZodMiniString<string>>;
         }, z.core.$strip>, z.ZodMiniTransform<{
@@ -70,6 +73,9 @@ export declare function charge<const parameters extends charge.Parameters>(param
             externalId?: string | undefined;
             metadata?: Record<string, string> | undefined;
             networkId: string;
+            paymentIntentOptions?: {
+                metadata: Record<string, string>;
+            } | undefined;
             paymentMethodTypes: string[];
             recipient?: string | undefined;
         }>>;

package/dist/stripe/server/Charge.js

@@ -117,13 +117,14 @@ export function charge(parameters) {
         onPaymentSuccess,
         async verify({ credential, envelope, request }) {
             const { challenge } = credential;
+            const { paymentIntentOptions, ...methodRequest } = request;
             const resolvedRequest = (() => {
-                const parsed = Methods.charge.schema.request.safeParse(request);
+                const parsed = Methods.charge.schema.request.safeParse(methodRequest);
                 if (parsed.success)
                     return parsed.data;
                 // verifyCredential() passes the HMAC-bound challenge request, which is
                 // already in canonical output form and should not be transformed again.
-                return request;
+                return methodRequest;
             })();
             Expires.assert(challenge.expires, challenge.id);
             const parsed = Methods.charge.schema.credential.payload.safeParse(credential.payload);
@@ -138,7 +139,11 @@ export function charge(parameters) {
                 });
             }
             const userMetadata = resolvedRequest.methodDetails?.metadata;
-            const resolvedMetadata = { ...buildAnalytics({ credential }), ...userMetadata };
+            const resolvedMetadata = {
+                ...buildAnalytics({ credential }),
+                ...userMetadata,
+                ...paymentIntentOptions?.metadata,
+            };
             const settlement = validateConnectSettlement({
                 amount: resolvedRequest.amount,
                 settlement: typeof connect === 'function'