@agent-score/commerce 1.8.1 → 2.0.1

package/dist/payment/index.d.ts

@@ -1,7 +1,20 @@
-export { P as PaymentRequiredHeaderInput, a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-CU1eNvMQ.js';
-export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, r as readX402PaymentHeader } from '../signer-CFVQsWjL.js';
+import { T as TempoRailSpec, S as SolanaMppRailSpec, a as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from '../rail_spec-XP0wKgJV.js';
+export { R as RAIL_SPEC_DEFAULTS, c as RecipientLike, r as resolveRecipient } from '../rail_spec-XP0wKgJV.js';
+import { X as X402Server } from '../x402_server-hgQzWQwB.js';
+export { B as BuildX402AcceptsForOptions, C as CreateX402ServerOptions, a as X402FacilitatorChoice, b as X402SymbolicRail, c as buildX402AcceptsFor402, d as createX402Server } from '../x402_server-hgQzWQwB.js';
+export { a as aliasAmountFields, p as paymentRequiredHeader, w as wwwAuthenticateHeader } from '../wwwauthenticate-D_FMnPgU.js';
+import { S as SignerNetwork } from '../signer-3FAit11j.js';
+export { P as PaymentSigner, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from '../signer-3FAit11j.js';
+export { f as formatUsdCents, l as loadSolanaFeePayer, u as usdToAtomic } from '../solana-Cds87OTu.js';
 
-interface PaymentRequestInput {
+/**
+ * Build the base64-encoded `request` blob for an MPP Payment directive (per the
+ * paymentauth.org spec). Output shape matches what link-cli `mpp decode` expects:
+ *
+ *   { amount: "<raw_integer>", currency: "<token>", recipient?: "<addr>",
+ *     methodDetails?: { chainId?: number, networkId?: string } }
+ */
+declare function buildPaymentRequestBlob({ rail, amountUsd, currency, decimals, recipient, chainId, networkId, }: {
     /** Symbolic rail name (e.g., 'tempo-mainnet', 'x402-base-mainnet') — fills in defaults */
     rail?: string;
     /** Amount in USD as a number or string. Converted to raw integer using `decimals`. */
@@ -16,16 +29,13 @@ interface PaymentRequestInput {
     chainId?: number;
     /** Stripe profile_id or similar (goes into methodDetails.networkId — note camelCase per link-cli's mpp decode validator). */
     networkId?: string;
-}
+}): string;
 /**
- * Build the base64-encoded `request` blob for an MPP Payment directive (per the
- * paymentauth.org spec). Output shape matches what link-cli `mpp decode` expects:
- *
- *   { amount: "<raw_integer>", currency: "<token>", recipient?: "<addr>",
- *     methodDetails?: { chainId?: number, networkId?: string } }
+ * Format an MPP Payment directive string for the WWW-Authenticate header.
+ * Output shape: `Payment id="...", realm="...", method="...", intent="charge",
+ *                expires="...", request="<base64>"`
  */
-declare function buildPaymentRequestBlob(input: PaymentRequestInput): string;
-interface PaymentDirectiveInput {
+declare function paymentDirective({ rail, id, realm, method, intent, expires, request, }: {
     /** Symbolic rail name — sets `method` automatically */
     rail?: string;
     /** Challenge id (unique per request, used to correlate retries) */
@@ -40,21 +50,25 @@ interface PaymentDirectiveInput {
     expires?: string;
     /** Base64-encoded request blob. Pass the result of buildPaymentRequestBlob. */
     request: string;
-}
-/**
- * Format an MPP Payment directive string for the WWW-Authenticate header.
- * Output shape: `Payment id="...", realm="...", method="...", intent="charge",
- *                expires="...", request="<base64>"`
- */
-declare function paymentDirective(input: PaymentDirectiveInput): string;
-interface BuildPaymentDirectiveInput extends Omit<PaymentRequestInput, 'rail'>, Omit<PaymentDirectiveInput, 'request'> {
-    rail: string;
-}
+}): string;
 /**
  * Convenience: build the request blob and the directive in one call. Most vendors
  * want this rather than the two-step form.
  */
-declare function buildPaymentDirective(input: BuildPaymentDirectiveInput): string;
+declare function buildPaymentDirective({ rail, id, realm, amountUsd, currency, decimals, recipient, chainId, networkId, method, intent, expires, }: {
+    rail: string;
+    id: string;
+    realm: string;
+    amountUsd: string | number;
+    currency?: string;
+    decimals?: number;
+    recipient?: string;
+    chainId?: number;
+    networkId?: string;
+    method?: string;
+    intent?: string;
+    expires?: string;
+}): string;
 
 /**
  * Named network registry. Vendors reference symbolic names (`networks.base.mainnet.caip2`)
@@ -244,86 +258,6 @@ interface X402ServerLike {
  */
 declare function registerX402SchemesV1V2(server: X402ServerLike, network: string, scheme: unknown): void;
 
-type X402SymbolicRail = 'x402-base-mainnet' | 'x402-base-sepolia' | 'x402-base-mainnet-upto' | 'x402-base-sepolia-upto';
-type X402FacilitatorChoice = 'coinbase' | 'http' | unknown;
-interface CreateX402ServerOptions {
-    /**
-     * Facilitator selection:
-     * - 'coinbase' → Coinbase CDP facilitator (requires `@coinbase/x402` installed)
-     * - 'http' → HTTP-only public testnet facilitator
-     * - any object → custom facilitator instance, used directly
-     * - omitted → defaults to 'http'
-     */
-    facilitator?: X402FacilitatorChoice;
-    /**
-     * Symbolic rail names to register schemes for. Each gets v1+v2 dual-register applied.
-     * Requires `@x402/evm` peer dep installed.
-     */
-    rails?: X402SymbolicRail[];
-    /** Advanced: register custom {network, scheme} pairs (in addition to or instead of `rails`). */
-    schemes?: {
-        network: string;
-        scheme: unknown;
-    }[];
-    /** Register the Bazaar discovery extension. Requires `@x402/extensions` installed. */
-    bazaar?: boolean;
-    /** Initialize the server immediately (calls facilitator). Default true. */
-    initialize?: boolean;
-}
-/**
- * Loose type for the x402 resource server. We name the methods commerce calls during
- * setup; everything else (settlePayment, buildPaymentRequirements, processPaymentRequest,
- * enrichExtensions, etc.) is callable via the index signature so vendor code can use the
- * full @x402/core surface without us having to mirror every method signature.
- */
-interface X402Server {
-    register(network: string, scheme: unknown): void;
-    registerV1?(network: string, scheme: unknown): void;
-    registerExtension(ext: unknown): void;
-    initialize(): Promise<void>;
-    [key: string]: any;
-}
-/**
- * One-call x402 server setup. Resolves facilitator, constructs the server, registers
- * schemes per network with v1+v2 dual-register, optionally adds the Bazaar extension,
- * and initializes — replaces ~15 lines of boilerplate with a single config call.
- *
- * x402 packages are peer dependencies — vendors install only the schemes they use.
- * Throws a guiding error if a required peer is missing.
- *
- *   const server = await createX402Server({
- *     facilitator: 'coinbase',
- *     rails: ['x402-base-mainnet'],
- *     bazaar: true,
- *   });
- */
-declare function createX402Server(opts?: CreateX402ServerOptions): Promise<X402Server>;
-interface BuildX402AcceptsForOptions {
-    network: string;
-    price: string;
-    payTo: string;
-    scheme?: string;
-    maxTimeoutSeconds?: number;
-    extensions?: string[];
-}
-/**
- * Build x402 `accepts[]` entries for a 402 challenge body.
- *
- * Wraps `server.buildPaymentRequirements(...)` so merchants don't have to:
- *
- * 1. Construct the resource-config object themselves
- * 2. Remember to serialize each Pydantic-equivalent requirement back to a
- *    plain object before stitching it into the 402 body
- * 3. Hardcode `extra` (which differs by the actual on-chain contract — base
- *    mainnet USDC has `name: "USD Coin"`, base sepolia USDC has `name: "USDC"`;
- *    EIP-712 domain hashes differ, so getting this wrong silently breaks every
- *    signature verify at the facilitator)
- *
- * Returns a list of plain objects in the shape that x402 expects on the wire —
- * drop them straight into the `accepts` field of the 402 challenge body.
- */
-declare function buildX402AcceptsFor402(server: X402Server, opts: BuildX402AcceptsForOptions): Promise<unknown[]>;
-
 /**
  * `processX402Settle`: single-call x402 verify+settle for merchants.
  *
@@ -341,26 +275,6 @@ declare function buildX402AcceptsFor402(server: X402Server, opts: BuildX402Accep
  * map the tagged result to a recommended HTTP response.
  */
 
-interface ProcessX402SettleInput {
-    /** The x402 server instance from `createX402Server`. */
-    x402Server: X402Server;
-    /** The verified x402 payload extracted from the X-Payment header. */
-    payload: unknown;
-    /** Resource configuration the facilitator validates against (network, price, payTo,
-     *  asset, maxTimeoutSeconds, etc.). Shape is x402-server-specific. */
-    resourceConfig: unknown;
-    /** Resource metadata exposed to the facilitator (URL, description, mime type). */
-    resourceMeta: {
-        url: string;
-        description: string;
-        mimeType: string;
-    };
-    /** Optional extension to enrich during verify (e.g. Bazaar). */
-    extension?: unknown;
-    /** Transport context for the extension enrich step. Defaults to `{ method: 'POST',
-     *  adapter: { getPath: () => new URL(resourceMeta.url).pathname }, routePattern: <pathname> }`. */
-    transportContext?: unknown;
-}
 type ProcessX402SettleResult = {
     success: true;
     /** The matched requirement passed to `settlePayment`. */
@@ -420,7 +334,7 @@ type ProcessX402SettleResult = {
      *  so the agent can pick a different rail. */
     phase: 'facilitator_error';
     /** Which verify-stage step threw. */
-    step: 'build_requirements' | 'enrich_extensions' | 'process_payment_request';
+    step: 'build_requirements' | 'enrich_extensions' | 'verify_payment';
     error: unknown;
 };
 /**
@@ -459,7 +373,49 @@ interface ClassifiedX402Error {
  * is intentionally facilitator-agnostic and never carries raw error detail.
  */
 declare function classifyX402SettleResult(result: ProcessX402SettleResult): ClassifiedX402Error | null;
-declare function processX402Settle(input: ProcessX402SettleInput): Promise<ProcessX402SettleResult>;
+/**
+ * Classify a thrown error during the 402 orchestration.
+ *
+ * Catches errors that escape `processX402Settle` (e.g. raised by `mppx.compose`,
+ * a Stripe SDK call, or any other payment-side library code wrapped in a single
+ * `try/catch` around the full settle flow). Returns a `ClassifiedX402Error`
+ * when the error message matches a known pattern; `null` otherwise.
+ *
+ * Callers should rethrow on `null` — this helper never swallows unknown errors.
+ *
+ * Pattern matching is case-insensitive substring on the error message:
+ * - `"x402version"` / `"invalid payment"` / `"unsupported x402"` →
+ *   400 `payment_proof_invalid` / `regenerate_payment_credential`
+ * - `"stripe"` / `"facilitator"` / `"cdp"` →
+ *   503 `payment_provider_unavailable` / `retry_or_swap_method`
+ * - Anything else → `null` (caller rethrows)
+ *
+ * Substring matching is intentionally narrow. New error families should land
+ * here explicitly rather than have the helper grow opaque heuristics. For
+ * tagged failure results that already classify themselves, use
+ * `classifyX402SettleResult`.
+ */
+declare function classifyOrchestrationError(err: unknown): ClassifiedX402Error | null;
+declare function processX402Settle({ x402Server, payload, resourceConfig, resourceMeta, extension, transportContext, }: {
+    /** The x402 server instance from `createX402Server`. */
+    x402Server: X402Server;
+    /** The verified x402 payload extracted from the X-Payment header. */
+    payload: unknown;
+    /** Resource configuration the facilitator validates against (network, price, payTo,
+     *  asset, maxTimeoutSeconds, etc.). Shape is x402-server-specific. */
+    resourceConfig: unknown;
+    /** Resource metadata exposed to the facilitator (URL, description, mime type). */
+    resourceMeta: {
+        url: string;
+        description: string;
+        mimeType: string;
+    };
+    /** Optional extension to enrich during verify (e.g. Bazaar). */
+    extension?: unknown;
+    /** Transport context for the extension enrich step. Defaults to `{ method: 'POST',
+     *  adapter: { getPath: () => new URL(resourceMeta.url).pathname }, routePattern: <pathname> }`. */
+    transportContext?: unknown;
+}): Promise<ProcessX402SettleResult>;
 
 /**
  * x402 boot-time + per-request validation helpers.
@@ -478,10 +434,6 @@ declare function processX402Settle(input: ProcessX402SettleInput): Promise<Proce
  */
 /** CAIP-2 networks the commerce SDK supports for x402 Base (EVM USDC). */
 declare const X402_SUPPORTED_BASE_NETWORKS: Set<string>;
-interface ValidateX402NetworkConfigInput {
-    /** CAIP-2 base network string (e.g. `'eip155:8453'`). */
-    baseNetwork: string;
-}
 /**
  * Boot-time guard: throws if the base network isn't supported. Call once at module
  * init / server boot.
@@ -490,17 +442,9 @@ interface ValidateX402NetworkConfigInput {
  * options — agents tracking down a misconfigured deploy don't need to grep for the
  * supported list.
  */
-declare function validateX402NetworkConfig(input: ValidateX402NetworkConfigInput): void;
-interface VerifyX402RequestInput {
-    /** The incoming Request — `verifyX402Request` reads the X-Payment / payment-signature header. */
-    request: Request;
-    /** Async lookup that returns true when the address was minted by this merchant
-     *  (typically `piCache.hasAddress`). The check validates that the credential's
-     *  deposit address matches one the merchant actually minted. */
-    isCachedAddress: (address: string) => Promise<boolean>;
-    /** The merchant's accepted Base network. CAIP-2, e.g. `'eip155:8453'`. */
-    acceptedNetwork: string;
-}
+declare function validateX402NetworkConfig({ baseNetwork }: {
+    baseNetwork: string;
+}): void;
 type VerifyX402RequestResult = {
     ok: true;
     /** The base64-decoded JSON payload from the X-Payment header. */
@@ -549,108 +493,43 @@ type VerifyX402RequestResult = {
  * Reads the header from `payment-signature` first, falling back to `x-payment` (both
  * are in the wild as the binary-friendly transport name evolved).
  */
-declare function verifyX402Request(input: VerifyX402RequestInput): Promise<VerifyX402RequestResult>;
+declare function verifyX402Request({ request, isCachedAddress, acceptedNetwork, }: {
+    /** The incoming Request — `verifyX402Request` reads the X-Payment / payment-signature header. */
+    request: Request;
+    /** Async lookup that returns true when the address was minted by this merchant
+     *  (typically `piCache.hasAddress`). The check validates that the credential's
+     *  deposit address matches one the merchant actually minted. */
+    isCachedAddress: (address: string) => Promise<boolean>;
+    /** The merchant's accepted Base network. CAIP-2, e.g. `'eip155:8453'`. */
+    acceptedNetwork: string;
+}): Promise<VerifyX402RequestResult>;
 
-type SolanaMppNetwork = 'mainnet-beta' | 'devnet' | 'localnet';
-interface CreateMppxServerOptions {
-    /** Symbolic rail config — commerce wires the boilerplate (tempo.charge, mppStripe.charge, solana.charge, etc.). */
-    rails?: {
-        /** One-shot Tempo USDC charge (intent: 'charge'). */
-        tempo?: {
-            recipient: string;
-            /** Custom currency token. Default: USDC on Tempo. */
-            currency?: string;
-            /** Use Tempo testnet (Moderato). Default false. */
-            testnet?: boolean;
-        };
-        /**
-         * Solana SPL charge (intent: 'charge'). Bakes createAssociatedTokenIdempotent
-         * into the buyer's tx so payments work against any payTo, fresh or warmed.
-         *
-         * Requires `@solana/mpp` + `@solana/kit` peer deps.
-         * Underlying spec: paymentauth.org/draft-solana-charge-00.
-         */
-        solana?: {
-            /** Base58-encoded Solana recipient public key. */
-            recipient: string;
-            /** SPL token mint (base58). Default: USDC for the selected network. */
-            currency?: string;
-            /** Token decimals. Default 6 (USDC). */
-            decimals?: number;
-            /** Solana network. Default 'mainnet-beta'. */
-            network?: SolanaMppNetwork;
-            /** Custom RPC URL. Default: public RPC for the network. */
-            rpcUrl?: string;
-            /**
-             * Optional fee-payer signer for server-side fee sponsorship. When provided,
-             * the server's pubkey is advertised as `feePayerKey` in the 402 challenge and
-             * the server co-signs settle txs as fee payer (so buyers don't need SOL, and
-             * ATA-creation rent is server-funded). Construct via
-             * `@solana/kit`'s `createKeyPairSignerFromBytes` or equivalent.
-             *
-             * Typed as `unknown` to avoid a hard dep on @solana/kit at this layer; pass any
-             * `TransactionPartialSigner` from `@solana/kit`.
-             */
-            signer?: unknown;
-            /** SPL token program hint (TOKEN_PROGRAM or TOKEN_2022_PROGRAM). Auto-detected when omitted. */
-            tokenProgram?: string;
-        };
-        /**
-         * Tempo session (intent: 'session') — pay-as-you-go channel for repeated calls or
-         * SSE-streamed responses. Vendor brings their own ChannelStore (DB-backed implementation
-         * tracking open channels + voucher state) and an `escrowContract` address.
-         */
-        tempo_session?: {
-            recipient: string;
-            currency?: string;
-            testnet?: boolean;
-            /**
-             * On-chain escrow contract address that holds channel deposits and pays out
-             * cumulative vouchers on settlement. Vendor-deployed.
-             */
-            escrowContract: string;
-            /**
-             * Channel store implementation tracking open channels + cumulative voucher state.
-             * Pass an instance of mppx's `ChannelStore` interface (you can use the in-memory
-             * default for dev or implement a Postgres/Redis-backed store for production).
-             */
-            store: unknown;
-            /** Optional supported chains; defaults to mppx defaults. */
-            chains?: unknown;
-        };
-        /** Stripe SPT (Shared Payment Token) — see also @agent-score/commerce/stripe-multichain. */
-        stripe?: {
-            profileId: string;
-            secretKey: string;
-            paymentMethodTypes?: string[];
-        };
-    };
-    /** Advanced: pass mppx method instances directly (in addition to or instead of `rails`). */
-    methods?: unknown[];
-    /** MPP secret key (merchant's). */
-    secretKey: string;
-}
+type MppxRailSpec = TempoRailSpec | SolanaMppRailSpec | TempoSessionRailSpec | StripeRailSpec;
 /**
- * One-call mppx server setup. Wires `tempo.charge(...)`, `tempo.session(...)`, and Stripe SPT
- * (via createMppxStripe) from symbolic rail config, replacing the boilerplate of constructing
- * each method by hand.
+ * One-call mppx server setup. Wires `tempo.charge(...)`, `tempo.session(...)`,
+ * `@solana/mpp.charge(...)`, and Stripe SPT (via createMppxStripe) from canonical
+ * `*RailSpec` configs, replacing the boilerplate of constructing each method by
+ * hand.
  *
  *   const mppx = await createMppxServer({
  *     rails: {
- *       tempo: { recipient: TEMPO_ADDR, testnet: false },             // intent: 'charge'
- *       tempo_session: {                                                // intent: 'session'
- *         recipient: TEMPO_ADDR,
- *         escrowContract: ESCROW_ADDR,
- *         store: myChannelStore,
- *       },
- *       stripe: { profileId: STRIPE_PROFILE_ID, secretKey: STRIPE_SECRET_KEY },
+ *       tempo: { recipient: TEMPO_ADDR } satisfies TempoRailSpec,
+ *       solana: { recipient: SOL_ADDR } satisfies SolanaMppRailSpec,
+ *       stripe: { profileId: STRIPE_PROFILE_ID, secretKey: STRIPE_SECRET_KEY } satisfies StripeRailSpec,
  *     },
  *     secretKey: MPP_SECRET_KEY,
  *   });
  *
+ * Keys are rail names (`tempo` / `solana` / `tempo_session` / `stripe`); values
+ * are the matching `*RailSpec` types every other helper also consumes.
+ *
  * `mppx` is an OPTIONAL peer dependency — install it only if you accept MPP rails.
  */
-declare function createMppxServer(opts: CreateMppxServerOptions): Promise<unknown>;
+declare function createMppxServer({ rails, methods: extraMethods, secretKey, }: {
+    rails?: Record<string, MppxRailSpec>;
+    methods?: unknown[];
+    secretKey: string;
+}): Promise<unknown>;
 type SolanaChargeRequestArgs = {
     credential?: unknown;
     request?: unknown;
@@ -673,7 +552,66 @@ type SolanaChargeMethod = {
  * Fine for agent-driven flows; manual signing flows still have plenty of margin.
  */
 declare function wrapSolanaChargeWithFinalizedBlockhash(baseMethod: SolanaChargeMethod, rpcUrl: string): SolanaChargeMethod;
+/**
+ * Result shape of `composeMppxRequest`. mppx's `mppx.compose(...)(request)`
+ * resolves to one of two variants — type-narrowed here so consumers can
+ * `if (result.status === 200) { result.withReceipt(...) }` without an
+ * `as any` cast.
+ */
+type MppxComposeResult = {
+    status: 200;
+    /** Wraps a Response with the `Payment-Receipt` header attached. */
+    withReceipt: (response: Response) => Response;
+    [k: string]: unknown;
+} | {
+    status: 402;
+    /** The 402 challenge Response mppx emitted (carries WWW-Authenticate). */
+    challenge: Response;
+    [k: string]: unknown;
+};
+/**
+ * Run `mppx.compose(...intents)(request)` with a typed return. Replaces the
+ * `(mppx as any).compose(...intents)(request)` cast every hand-rolled
+ * `composeMppx` hook ends up writing.
+ *
+ * @example
+ * ```ts
+ * const result = await composeMppxRequest(mppx, [
+ *   ['tempo/charge', { amount, currency, decimals, recipient }],
+ *   ['stripe/charge', { amount, currency: 'usd', decimals: 2 }],
+ * ], ctx.request.raw);
+ * if (result.status === 402) return { status: 402, headers: mppxChallengeHeaders(result) };
+ * return { status: 200, raw: result };
+ * ```
+ */
+declare function composeMppxRequest(mppx: unknown, intents: readonly unknown[], request: Request): Promise<MppxComposeResult>;
+/**
+ * Extract the 402 challenge response's headers as a plain `Record<string, string>`,
+ * the shape `MppxComposeOutcome.headers` accepts. Wraps the one-liner every
+ * hand-rolled compose hook writes.
+ */
+declare function mppxChallengeHeaders(result: {
+    challenge: Response;
+}): Record<string, string>;
 
+/**
+ * Detect which payment-protocol family the inbound request carries.
+ *
+ * Returns `"mpp"` when an `Authorization` header starts with the `Payment`
+ * scheme (case-insensitive per RFC 7235). Returns `"x402"` when a non-empty
+ * `payment-signature` or `x-payment` header is present. Returns `null` otherwise.
+ *
+ * In practice a client constructs a request with exactly one protocol's headers;
+ * both arriving together is a client bug or misconfigured proxy. The helper checks
+ * MPP first so the rare degenerate case resolves to MPP. Empty header values are
+ * treated as absent. Header-name lookups are case-insensitive (RFC 7230 §3.2).
+ * The narrower rail naming (`"tempo"` vs `"solana"` inside MPP) is merchant-side,
+ * derived from the credential body, not this helper.
+ *
+ * Accepts either a Web Fetch `Headers` instance (case-insensitive lookup native)
+ * or a plain object (case-insensitive lookup applied internally).
+ */
+declare function detectRailFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): 'x402' | 'mpp' | null;
 interface SettlementHandlers<TPayload, TResult> {
     evm?: (payload: TPayload) => TResult | Promise<TResult>;
     svm?: (payload: TPayload) => TResult | Promise<TResult>;
@@ -726,28 +664,6 @@ interface PaymentHeadersRail {
     /** ISO-8601 expiry. Default now + 5 min. */
     expires?: string;
 }
-interface BuildPaymentHeadersInput {
-    /** Rails the merchant accepts on this 402. Each becomes one `Payment` directive. */
-    rails: PaymentHeadersRail[];
-    /** Order id used as the directive challenge id (per-rail it becomes `${orderId}-${rail}`). */
-    orderId: string;
-    /** Realm — the host of the merchant URL (e.g. `agents.merchant.example`). */
-    realm: string;
-    /**
-     * Optional x402 `accepts` array — included as the standard PAYMENT-REQUIRED header so
-     * x402 clients (`@x402/fetch`, `@x402/core` HTTPClient, `agentscore-pay`) can parse the
-     * base64-encoded JSON form instead of the WWW-Authenticate text directives. Pass
-     * `undefined` (or omit) to skip the PAYMENT-REQUIRED header.
-     */
-    x402?: {
-        accepts: unknown[];
-        version?: 1 | 2;
-        resource?: {
-            url: string;
-            mimeType?: string;
-        };
-    };
-}
 interface PaymentHeadersResult {
     'www-authenticate': string;
     'PAYMENT-REQUIRED'?: string;
@@ -772,7 +688,28 @@ interface PaymentHeadersResult {
  * return new Response(JSON.stringify(body), { status: 402, headers });
  * ```
  */
-declare function buildPaymentHeaders(input: BuildPaymentHeadersInput): PaymentHeadersResult;
+declare function buildPaymentHeaders({ rails, orderId, realm, x402, }: {
+    /** Rails the merchant accepts on this 402. Each becomes one `Payment` directive. */
+    rails: PaymentHeadersRail[];
+    /** Order id used as the directive challenge id (per-rail it becomes `${orderId}-${rail}`). */
+    orderId: string;
+    /** Realm — the host of the merchant URL (e.g. `agents.merchant.example`). */
+    realm: string;
+    /**
+     * Optional x402 `accepts` array — included as the standard PAYMENT-REQUIRED header so
+     * x402 clients (`@x402/fetch`, `@x402/core` HTTPClient, `agentscore-pay`) can parse the
+     * base64-encoded JSON form instead of the WWW-Authenticate text directives. Pass
+     * `undefined` (or omit) to skip the PAYMENT-REQUIRED header.
+     */
+    x402?: {
+        accepts: unknown[];
+        version?: 1 | 2;
+        resource?: {
+            url: string;
+            mimeType?: string;
+        };
+    };
+}): PaymentHeadersResult;
 
 /**
  * Idempotency-key composition.
@@ -789,16 +726,6 @@ declare function buildPaymentHeaders(input: BuildPaymentHeadersInput): PaymentHe
  *   3. Server caps idempotency keys at 200 chars; this helper warns when that boundary is
  *      crossed so a future caller doesn't silently get truncation collisions.
  */
-interface BuildIdempotencyKeyInput {
-    /** Upstream rail's stable payment id — Stripe PaymentIntent id, x402 tx hash, etc. Wins when present. */
-    paymentIntentId?: string | null;
-    /** Order id — used to compose a fallback key when no paymentIntentId exists. */
-    orderId?: string | null;
-    /** Amount in cents (or smallest currency unit) — added to the fallback for extra collision resistance. */
-    amountCents?: number;
-    /** Optional extra prefix to namespace the key (e.g. `"refund"`, `"void"`). */
-    prefix?: string;
-}
 /**
  * Compose a stable idempotency key for AgentScore wallet capture and other retry-safe POSTs.
  *
@@ -814,7 +741,16 @@ interface BuildIdempotencyKeyInput {
  * buildIdempotencyKey({});                                       // → undefined
  * ```
  */
-declare function buildIdempotencyKey(input: BuildIdempotencyKeyInput): string | undefined;
+declare function buildIdempotencyKey({ paymentIntentId, orderId, amountCents, prefix, }: {
+    /** Upstream rail's stable payment id — Stripe PaymentIntent id, x402 tx hash, etc. Wins when present. */
+    paymentIntentId?: string | null;
+    /** Order id — used to compose a fallback key when no paymentIntentId exists. */
+    orderId?: string | null;
+    /** Amount in cents (or smallest currency unit) — added to the fallback for extra collision resistance. */
+    amountCents?: number;
+    /** Optional extra prefix to namespace the key (e.g. `"refund"`, `"void"`). */
+    prefix?: string;
+}): string | undefined;
 
 /**
  * x402 Settlement-Overrides header helpers — used with the `upto` scheme to specify the
@@ -847,4 +783,100 @@ declare function settlementOverrideHeader(overrides: SettlementOverrides): {
     value: string;
 };
 
-export { type BuildIdempotencyKeyInput, type BuildPaymentDirectiveInput, type BuildPaymentHeadersInput, type BuildX402AcceptsForOptions, type ClassifiedX402Error, type CreateMppxServerOptions, type CreateX402ServerOptions, type NetworkFamily, type PaymentDirectiveInput, type PaymentHeadersRail, type PaymentHeadersResult, type PaymentRequestInput, type ProcessX402SettleInput, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, type SolanaMppNetwork, USDC, type ValidateX402NetworkConfigInput, type VerifyX402RequestInput, type VerifyX402RequestResult, type X402FacilitatorChoice, type X402Server, type X402ServerLike, type X402SymbolicRail, X402_SUPPORTED_BASE_NETWORKS, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, buildX402AcceptsFor402, classifyX402SettleResult, createMppxServer, createX402Server, dispatchSettlementByNetwork, lookupRail, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash };
+/**
+ * Zero-amount carve-out: skip upstream verify+settle for $0 orders.
+ *
+ * CDP rejects EIP-3009 `transferWithAuthorization` with `value=0` as
+ * `invalid_payload`; `mppx`'s tempo intents accept only `hash` and
+ * `transaction` payload types (rejecting the `proof` payload that gets
+ * emitted for $0 settles). Both upstream verify+settle paths fail when the
+ * authorized amount is zero, so merchants that drop the settle to $0 in a
+ * redemption-code flow need a way to skip verify+settle entirely while
+ * still recovering the signer for wallet-capture attribution.
+ *
+ * `zeroAmountCarveOut` is that path: parse the credential, lift the
+ * signer, return `{ signerAddress, signerNetwork, txHash: null }`. Identity
+ * is still authenticated by the merchant's gate above; the redemption code
+ * is single-use; nothing on-chain to verify.
+ *
+ * The MPP path uses inline base64+JSON parsing (no `mppx` dependency at
+ * runtime) so the cross-language byte-parity fixtures with the Python
+ * sibling resolve to identical results. The full `extractPaymentSigner`
+ * path is still mppx-backed for production traffic where the credential
+ * is a real mppx-shaped object.
+ */
+
+type ZeroSettleRail = 'x402-base' | 'tempo' | 'solana';
+interface ZeroSettleResult {
+    /** Recovered signer address, or `null` when the credential is malformed
+     *  or shaped wrong for the requested rail. */
+    signerAddress: string | null;
+    /** `"evm"` or `"solana"`, matching the recovered signer's key family.
+     *  `null` when no signer was recoverable. */
+    signerNetwork: SignerNetwork | null;
+    /** Always `null`. A zero-amount carve-out skips on-chain settlement, so
+     *  no transaction hash exists. The field is present so callers can use
+     *  `ZeroSettleResult` interchangeably with the success path of
+     *  `processX402Settle` etc. without branching on shape. */
+    txHash: null;
+}
+/**
+ * Skip verify+settle for a zero-amount order; recover the signer from the credential.
+ *
+ * Returns a `ZeroSettleResult`. `signerAddress` / `signerNetwork` are `null`
+ * when the credential is malformed, missing required fields, or shaped wrong
+ * for the requested rail. `txHash` is always `null` since no on-chain settle runs.
+ */
+declare function zeroAmountCarveOut({ rail, payload, authorizationHeader, }: {
+    rail: ZeroSettleRail;
+    /** For `rail: 'x402-base'`: the verified x402 payload (decoded JSON
+     *  from `verifyX402Request(...).payload`). Reads
+     *  `payload.payload.authorization.from`. */
+    payload?: Record<string, unknown> | null;
+    /** For `rail: 'tempo'` / `'solana'`: the full `Authorization: Payment <base64>`
+     *  header value. Reads the `did:pkh:*` source DID. */
+    authorizationHeader?: string | null;
+}): ZeroSettleResult;
+
+/**
+ * Lazy-init helpers for x402 + mppx servers.
+ *
+ * Every merchant accepting these rails writes the same singleton-with-lock
+ * pattern around `createX402Server` / `createMppxServer`. These helpers collapse
+ * the boilerplate to a single call; the returned getter is safe to call from
+ * any number of concurrent handlers; only one server instance is ever
+ * constructed per merchant.
+ *
+ * The x402 helper also derives the facilitator choice (`coinbase` vs `http`)
+ * from optional CDP credentials so merchants don't repeat the boot-time
+ * conditional.
+ */
+
+/**
+ * Build a memoized async getter for an x402 server.
+ *
+ * First call constructs the server; subsequent calls return the cached
+ * instance. Concurrent first-callers serialize on a Promise lock so we never
+ * construct two and discard one.
+ *
+ * When both CDP creds are passed, the server uses Coinbase's facilitator;
+ * otherwise it falls back to the public HTTP facilitator. Merchants who only
+ * have one of the two creds get the HTTP fallback.
+ */
+declare function lazyX402Server(opts: {
+    spec: X402BaseRailSpec;
+    cdpApiKeyId?: string;
+    cdpApiKeySecret?: string;
+}): () => Promise<X402Server>;
+/**
+ * Build a memoized async getter for an mppx server.
+ *
+ * Same singleton + lock semantics as {@link lazyX402Server}. Forwards `rails`
+ * + `secretKey` unchanged to {@link createMppxServer}.
+ */
+declare function lazyMppxServer(opts: {
+    rails: Record<string, MppxRailSpec>;
+    secretKey: string;
+}): () => Promise<unknown>;
+
+export { type ClassifiedX402Error, type MppxComposeResult, type MppxRailSpec, type NetworkFamily, type PaymentHeadersRail, type PaymentHeadersResult, type ProcessX402SettleResult, type RailDefinition, type RailName, SETTLEMENT_OVERRIDES_HEADER, type SettlementHandlers, type SettlementOverrides, type SettlementPayloadLike, SignerNetwork, SolanaMppRailSpec, StripeRailSpec, TempoRailSpec, TempoSessionRailSpec, USDC, type VerifyX402RequestResult, X402BaseRailSpec, X402Server, type X402ServerLike, X402_SUPPORTED_BASE_NETWORKS, type ZeroSettleRail, type ZeroSettleResult, buildIdempotencyKey, buildPaymentDirective, buildPaymentHeaders, buildPaymentRequestBlob, classifyOrchestrationError, classifyX402SettleResult, composeMppxRequest, createMppxServer, detectRailFromHeaders, dispatchSettlementByNetwork, lazyMppxServer, lazyX402Server, lookupRail, mppxChallengeHeaders, networkFamily, networks, paymentDirective, processX402Settle, rails, registerX402SchemesV1V2, settlementOverrideHeader, validateX402NetworkConfig, verifyX402Request, wrapSolanaChargeWithFinalizedBlockhash, zeroAmountCarveOut };