@odatano/x402 0.2.0 → 0.3.1

package/srv/client/fetch.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * `x402Fetch` — drop-in fetch wrapper that auto-handles 402 responses.
+ * `x402Fetch`, drop-in fetch wrapper that auto-handles 402 responses.
  *
  * On a 402 response the wrapper:
  *   1. Parses the body as a v2 `PaymentRequirementsBody`.
@@ -11,7 +11,7 @@
  *
  * Non-402 responses are passed through untouched. After `maxRetries`
  * payment attempts, the last response (whether 402 or other) is
- * returned to the caller — never an infinite loop.
+ * returned to the caller, never an infinite loop.
  *
  * Native fetch is used by default (Node ≥18, all modern browsers).
  * Pass `opts.fetch` to override (testing, custom agents, etc.).
@@ -19,6 +19,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.x402Fetch = x402Fetch;
 const envelope_1 = require("./envelope");
+const errors_1 = require("./errors");
 /**
  * Wrap `fetch` with 402-handling. The returned function has the same
  * signature as native fetch, so it's a drop-in replacement.
@@ -37,34 +38,93 @@ function x402Fetch(opts) {
     return async function paidFetch(input, init) {
         let attemptsLeft = maxRetries;
         // Contextual typing from FetchFn means we don't need to spell out
-        // RequestInfo / RequestInit explicitly — those are DOM-only globals.
+        // RequestInfo / RequestInit explicitly, those are DOM-only globals.
         let nextInit = init;
+        // Remember the last parsed 402 body so retries_exhausted carries
+        // the same diagnostic shape as a fresh server_rejected.
+        let lastBody;
         // Loop: original request + up-to-maxRetries payment retries.
         // eslint-disable-next-line no-constant-condition
         while (true) {
             const res = await baseFetch(input, nextInit);
-            if (res.status !== 402 || attemptsLeft <= 0)
+            if (res.status !== 402)
                 return res;
+            if (attemptsLeft <= 0) {
+                if (opts.errorOnFailure) {
+                    // Use the last successfully-parsed 402 body if we have one
+                    // (we typically do, since the prior attempt parsed it). If
+                    // not, parse one more time to give the caller a useful error.
+                    let body = lastBody;
+                    if (!body) {
+                        try {
+                            body = await res.clone().json();
+                        }
+                        catch { /* fall through */ }
+                    }
+                    if (body) {
+                        throw (0, errors_1.paymentErrorFromBody)(body, { kind: 'retries_exhausted', httpStatus: res.status });
+                    }
+                    throw new errors_1.X402PaymentError({
+                        message: 'x402Fetch: retries exhausted with no parsable 402 body',
+                        kind: 'retries_exhausted',
+                        httpStatus: res.status,
+                    });
+                }
+                return res;
+            }
             // Parse 402 body. If it's not a v2 PaymentRequirementsBody we
-            // bail with the original response (caller's problem to handle).
+            // bail with the original response (or throw under errorOnFailure).
             let body;
             try {
-                body = (await res.clone().json());
+                body = await res.clone().json();
             }
             catch {
+                if (opts.errorOnFailure) {
+                    throw new errors_1.X402PaymentError({
+                        message: 'x402Fetch: 402 body was not JSON',
+                        kind: 'invalid_402_body',
+                        httpStatus: res.status,
+                    });
+                }
                 return res;
             }
-            if (body?.x402Version !== 2 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+            if (!body || body.x402Version !== 2 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+                if (opts.errorOnFailure) {
+                    throw new errors_1.X402PaymentError({
+                        message: 'x402Fetch: 402 body is not a v2 PaymentRequirementsBody',
+                        kind: 'invalid_402_body',
+                        httpStatus: res.status,
+                    });
+                }
                 return res;
             }
+            lastBody = body;
             const chosen = select(body.accepts);
-            if (!chosen)
+            if (!chosen) {
+                if (opts.errorOnFailure) {
+                    throw (0, errors_1.paymentErrorFromBody)(body, { kind: 'server_rejected', httpStatus: res.status });
+                }
                 return res;
-            const { signedTxCborHex, nonceRef } = await opts.pay(chosen);
+            }
+            // Invoke user's pay handler. Wallet rejection / signer errors /
+            // network blips here all surface as X402PaymentError(pay_handler_failed)
+            // with the original error on `.cause`, regardless of errorOnFailure.
+            let payResult;
+            try {
+                payResult = await opts.pay(chosen);
+            }
+            catch (err) {
+                throw new errors_1.X402PaymentError({
+                    message: `x402Fetch: pay handler failed: ${err?.message ?? String(err)}`,
+                    kind: 'pay_handler_failed',
+                    accepts: body.accepts,
+                    cause: err,
+                });
+            }
             const header = (0, envelope_1.encodePaymentEnvelope)({
                 network: chosen.network,
-                signedTxCborHex,
-                nonceRef,
+                signedTxCborHex: payResult.signedTxCborHex,
+                nonceRef: payResult.nonceRef,
             });
             // Merge PAYMENT-SIGNATURE into headers without mutating caller's init.
             const mergedHeaders = new Headers(nextInit?.headers ?? init?.headers);

package/srv/client/pay-handlers.d.ts

@@ -3,8 +3,8 @@
  *
  * `createBridgePayHandler` is the default for server-to-server flows
  * (one CAP service calling another, AI-agent payments). It uses the
- * existing `buildUnsignedPaymentTx` helper — which requires
- * `@odatano/core` bridge access at runtime — and delegates signing
+ * existing `buildUnsignedPaymentTx` helper, which requires
+ * `@odatano/core` bridge access at runtime, and delegates signing
  * to a caller-supplied `signTx` callback.
  *
  * For browser CIP-30 wallets, write your own PayHandler: get UTxOs
@@ -14,7 +14,7 @@
  */
 import type { PayHandler } from './types';
 export interface BridgePayHandlerOptions {
-    /** Buyer bech32 — used for UTxO lookup and change. */
+    /** Buyer bech32, used for UTxO lookup and change. */
     buyerBech32: string;
     /**
      * Sign the unsigned tx CBOR. Returns the SIGNED tx CBOR hex
@@ -34,7 +34,7 @@ export interface BridgePayHandlerOptions {
  *   2. caller-supplied `signTx` (signs the unsigned CBOR)
  *   3. returns `{ signedTxCborHex, nonceRef }`
  *
- * The signed tx is NOT submitted here — the x402 server submits it
+ * The signed tx is NOT submitted here, the x402 server submits it
  * after validating the envelope (per Cardano-x402-v2 facilitator flow).
  */
 export declare function createBridgePayHandler(opts: BridgePayHandlerOptions): PayHandler;

package/srv/client/pay-handlers.js

@@ -4,8 +4,8 @@
  *
  * `createBridgePayHandler` is the default for server-to-server flows
  * (one CAP service calling another, AI-agent payments). It uses the
- * existing `buildUnsignedPaymentTx` helper — which requires
- * `@odatano/core` bridge access at runtime — and delegates signing
+ * existing `buildUnsignedPaymentTx` helper, which requires
+ * `@odatano/core` bridge access at runtime, and delegates signing
  * to a caller-supplied `signTx` callback.
  *
  * For browser CIP-30 wallets, write your own PayHandler: get UTxOs
@@ -22,7 +22,7 @@ const build_unsigned_tx_1 = require("../helpers/build-unsigned-tx");
  *   2. caller-supplied `signTx` (signs the unsigned CBOR)
  *   3. returns `{ signedTxCborHex, nonceRef }`
  *
- * The signed tx is NOT submitted here — the x402 server submits it
+ * The signed tx is NOT submitted here, the x402 server submits it
  * after validating the envelope (per Cardano-x402-v2 facilitator flow).
  */
 function createBridgePayHandler(opts) {

package/srv/client/types.d.ts

@@ -1,10 +1,10 @@
 /**
- * Client-side helper types — symmetric to the server-side facilitator.
+ * Client-side helper types, symmetric to the server-side facilitator.
  *
  * A `PayHandler` is the one extension point: given the `accepts[]` entry
  * the user chose, it must produce a signed payment tx (CBOR hex) + the
- * v2 nonce reference. Everything else — 402-detection, retry loop,
- * envelope encoding — is generic and lives in `fetch.ts` / `axios.ts`.
+ * v2 nonce reference. Everything else, 402-detection, retry loop,
+ * envelope encoding, is generic and lives in `fetch.ts` / `axios.ts`.
  */
 import type { PaymentRequirementEntry } from '../core/types';
 /**
@@ -19,7 +19,7 @@ export interface PayHandlerResult {
     /** Hex of the **signed** payment-tx CBOR (vkey witness set populated). */
     signedTxCborHex: string;
     /**
-     * v2 nonce reference `<txHash>#<outputIndex>` — must point to an
+     * v2 nonce reference `<txHash>#<outputIndex>`, must point to an
      * unspent UTxO that ALSO appears as an input of the signed tx.
      * (Server enforces both at validate time.)
      */
@@ -28,17 +28,29 @@ export interface PayHandlerResult {
 /** Pick which `accepts[]` entry to satisfy. Default picks the first. */
 export type AcceptsSelector = (accepts: PaymentRequirementEntry[]) => PaymentRequirementEntry | undefined;
 export interface X402ClientOptions {
-    /** Required — how to produce the signed payment tx. */
+    /** Required, how to produce the signed payment tx. */
     pay: PayHandler;
     /**
-     * Optional — choose one of the `accepts[]` entries when the server
+     * Optional, choose one of the `accepts[]` entries when the server
      * offers multiple. Defaults to `accepts[0]`.
      */
     selectAccepts?: AcceptsSelector;
     /**
      * Maximum number of 402-driven payment retries per request. Default 1
-     * — i.e. one payment attempt per request, no infinite loops.
+     *, i.e. one payment attempt per request, no infinite loops.
      */
     maxRetries?: number;
+    /**
+     * When `true`, throw an `X402PaymentError` after retries are
+     * exhausted (or when the 402 body is malformed). Default `false`:
+     *
+     *   - `x402Fetch` returns the last `Response` (the 402 itself).
+     *   - `x402Axios` re-throws the original AxiosError.
+     *
+     * Pay-handler throws are ALWAYS wrapped in `X402PaymentError` (kind:
+     * `'pay_handler_failed'`) regardless of this flag, with the original
+     * error preserved on `.cause`.
+     */
+    errorOnFailure?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/srv/client/types.js

@@ -1,10 +1,10 @@
 "use strict";
 /**
- * Client-side helper types — symmetric to the server-side facilitator.
+ * Client-side helper types, symmetric to the server-side facilitator.
  *
  * A `PayHandler` is the one extension point: given the `accepts[]` entry
  * the user chose, it must produce a signed payment tx (CBOR hex) + the
- * v2 nonce reference. Everything else — 402-detection, retry loop,
- * envelope encoding — is generic and lives in `fetch.ts` / `axios.ts`.
+ * v2 nonce reference. Everything else, 402-detection, retry loop,
+ * envelope encoding, is generic and lives in `fetch.ts` / `axios.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });

package/srv/core/asset.d.ts

@@ -21,7 +21,7 @@ export interface ParsedAsset {
     assetNameHex: string;
     /**
      * Concatenation used as the canonical UTxO `unit` key by Blockfrost /
-     * Koios / ODATANO (`policyId + assetNameHex`). Empty for lovelace —
+     * Koios / ODATANO (`policyId + assetNameHex`). Empty for lovelace ,
      * comparisons against UTxO assets short-circuit via `isLovelace`.
      */
     unit: string;

package/srv/core/decode.d.ts

@@ -12,14 +12,14 @@
  *     }
  *   }))
  *
- * The decoder is **pure** — no chain calls, no DB. It produces a
+ * The decoder is **pure**, no chain calls, no DB. It produces a
  * `DecodedPayment` that downstream `validate.ts` checks against
  * `PaymentRequirementEntry` (the 6 mandatory checks).
  */
 import type { DecodedPayment } from './types';
 /**
  * Decode a `PAYMENT-SIGNATURE` header value end-to-end. Throws X402Error
- * with a precise `code` on any malformed input — the caller catches and
+ * with a precise `code` on any malformed input, the caller catches and
  * surfaces the code in the 402 response body.
  */
 export declare function decode(paymentHeader: string | undefined | null): DecodedPayment;

package/srv/core/decode.js

@@ -13,7 +13,7 @@
  *     }
  *   }))
  *
- * The decoder is **pure** — no chain calls, no DB. It produces a
+ * The decoder is **pure**, no chain calls, no DB. It produces a
  * `DecodedPayment` that downstream `validate.ts` checks against
  * `PaymentRequirementEntry` (the 6 mandatory checks).
  */
@@ -59,7 +59,7 @@ const SUPPORTED_SCHEME = 'exact';
 const NONCE_RE = /^([0-9a-f]{64})#(\d+)$/i;
 function decodeBase64ToBuffer(s, errCode) {
     // Node's Buffer.from is lenient (silently drops bad chars). Re-encode
-    // and compare modulo padding to catch malformed input early — otherwise
+    // and compare modulo padding to catch malformed input early, otherwise
     // garbage in `transaction` would only fail at CBOR parse time with a
     // confusing error.
     const buf = Buffer.from(s, 'base64');
@@ -121,7 +121,7 @@ function extractInputs(txBody) {
 /**
  * Pull validity range bounds. CSL exposes `ttl()` (upper) since Shelley
  * and `validity_start_interval_bignum()` (lower) since Allegra. Both can
- * be absent — in which case we return null and the TTL check is skipped
+ * be absent, in which case we return null and the TTL check is skipped
  * (per v2 spec: only validate TTL if buyer set one).
  */
 function extractValidityRange(txBody) {
@@ -166,7 +166,7 @@ function parseNonceRef(nonce) {
 }
 /**
  * Decode a `PAYMENT-SIGNATURE` header value end-to-end. Throws X402Error
- * with a precise `code` on any malformed input — the caller catches and
+ * with a precise `code` on any malformed input, the caller catches and
  * surfaces the code in the 402 response body.
  */
 function decode(paymentHeader) {
@@ -201,7 +201,7 @@ function decode(paymentHeader) {
         throw new errors_1.X402Error(errors_1.Codes.MISSING_FIELD, 'payload.nonce is required (v2 UTxO-ref)');
     }
     // 3. Tx CBOR → CSL Transaction (parses both `transaction` and `fixed`
-    //    representation; we need both — Transaction for body access,
+    //    representation; we need both, Transaction for body access,
     //    FixedTransaction for byte-stable hash).
     const txBuf = decodeBase64ToBuffer(payload.transaction, errors_1.Codes.INVALID_CBOR);
     let tx;

package/srv/core/errors.js

@@ -39,9 +39,9 @@ exports.Codes = Object.freeze({
     WRONG_RECIPIENT: 'wrong_recipient', // check 2
     INSUFFICIENT_AMOUNT: 'insufficient_amount', // check 3
     WRONG_ASSET: 'wrong_asset', // check 4
-    REPLAY: 'replay_detected', // check 5 — UTxO already spent
-    NONCE_NOT_REFERENCED: 'nonce_not_referenced', // check 5 — UTxO not in tx inputs
-    EXPIRED_TTL: 'expired_ttl', // check 6 — validity range upper bound passed
+    REPLAY: 'replay_detected', // check 5, UTxO already spent
+    NONCE_NOT_REFERENCED: 'nonce_not_referenced', // check 5, UTxO not in tx inputs
+    EXPIRED_TTL: 'expired_ttl', // check 6, validity range upper bound passed
     // ---- supporting ----
     UNSIGNED_TRANSACTION: 'unsigned_transaction', // sanity: no vkey witnesses
     // ---- settle ----

package/srv/core/network.d.ts

@@ -10,7 +10,7 @@ export type Network = 'cardano:mainnet' | 'cardano:preprod' | 'cardano:preview';
 export declare function isNetwork(s: unknown): s is Network;
 /**
  * Validate a network string and return it typed. Throws X402Error on
- * malformed input — including v1-style hyphen variants — so the caller's
+ * malformed input, including v1-style hyphen variants, so the caller's
  * 402 body carries a precise diagnostic.
  */
 export declare function parseNetwork(s: string): Network;

package/srv/core/network.js

@@ -18,7 +18,7 @@ function isNetwork(s) {
 }
 /**
  * Validate a network string and return it typed. Throws X402Error on
- * malformed input — including v1-style hyphen variants — so the caller's
+ * malformed input, including v1-style hyphen variants, so the caller's
  * 402 body carries a precise diagnostic.
  */
 function parseNetwork(s) {

package/srv/core/requirements.d.ts

@@ -1,10 +1,10 @@
 /**
  * Build the canonical Cardano-x402-v2 PaymentRequirements body.
  *
- * Asset-agnostic by design — the consumer passes a v2 asset string
+ * Asset-agnostic by design, the consumer passes a v2 asset string
  * (`<policy>.<nameHex>` or `'lovelace'`), a payTo bech32, a network, and
  * a resource descriptor. There is NO USDM default and no decimals
- * assumption — both belong to the consumer's product config.
+ * assumption, both belong to the consumer's product config.
  *
  * The v2 shape diverges from v1 in five places (see `docs/spec-v2-summary.md`
  * once written):
@@ -17,7 +17,7 @@
  *   5. `accepts[].assetTransferMethod`(new field)
  */
 import { type Network } from './network';
-import type { PaymentRequirementEntry, PaymentRequirementsBody, ResourceDescriptor, AssetTransferMethod } from './types';
+import type { PaymentRequirementEntry, PaymentRequirementsBody, ResourceDescriptor, AssetTransferMethod, RouteOption } from './types';
 export interface BuildPaymentRequirementsArgs {
     /** Asset amount in raw units (BigInt-safe). */
     amount: string | number | bigint;
@@ -41,11 +41,43 @@ export interface BuildPaymentRequirementsArgs {
 }
 /**
  * Construct a single `accepts[]` entry. Most callers want
- * `buildPaymentRequirements()` which wraps this in the 402 envelope —
+ * `buildPaymentRequirements()` which wraps this in the 402 envelope ,
  * use `buildEntry()` directly when composing multi-asset accept lists.
  */
 export declare function buildEntry(args: BuildPaymentRequirementsArgs): PaymentRequirementEntry;
 export declare function buildPaymentRequirements(args: BuildPaymentRequirementsArgs): PaymentRequirementsBody;
-/** Pick the first `accepts[]` entry — what the validator inspects. */
+/** Pick the first `accepts[]` entry, what the validator inspects. */
 export declare function flatRequirements(body: PaymentRequirementsBody): PaymentRequirementEntry;
+export interface BuildMultiArgs {
+    /**
+     * Payment options the seller advertises. Buyer picks one implicitly by
+     * which (payTo, asset) the payment tx actually credits. MUST be non-empty.
+     */
+    options: RouteOption[];
+    /** Default recipient if a `RouteOption` omits `payTo`. */
+    payTo: string;
+    /** Default network if a `RouteOption` omits `network`. */
+    network: Network | string;
+    /** Default asset if a `RouteOption` omits `asset`. */
+    asset?: string;
+    resource: ResourceDescriptor | string;
+    description?: string;
+    mimeType?: string;
+    outputSchema?: unknown;
+    assetTransferMethod?: AssetTransferMethod;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+    /** Same as the single-entry builder's flag. See `BuildPaymentRequirementsArgs`. */
+    withMissingHeaderError?: boolean;
+}
+/**
+ * Build a multi-entry `accepts[]` body. Each option inherits the
+ * top-level `payTo` / `network` / `asset` / etc. defaults unless it sets
+ * its own. The `resource` block is shared across all entries (a 402 is
+ * for one route, even when it offers many payment options).
+ *
+ * Single-entry callers should keep using `buildPaymentRequirements()`;
+ * this function is the path for the multi-accept feature.
+ */
+export declare function buildPaymentRequirementsMulti(args: BuildMultiArgs): PaymentRequirementsBody;
 //# sourceMappingURL=requirements.d.ts.map

package/srv/core/requirements.js

@@ -2,10 +2,10 @@
 /**
  * Build the canonical Cardano-x402-v2 PaymentRequirements body.
  *
- * Asset-agnostic by design — the consumer passes a v2 asset string
+ * Asset-agnostic by design, the consumer passes a v2 asset string
  * (`<policy>.<nameHex>` or `'lovelace'`), a payTo bech32, a network, and
  * a resource descriptor. There is NO USDM default and no decimals
- * assumption — both belong to the consumer's product config.
+ * assumption, both belong to the consumer's product config.
  *
  * The v2 shape diverges from v1 in five places (see `docs/spec-v2-summary.md`
  * once written):
@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildEntry = buildEntry;
 exports.buildPaymentRequirements = buildPaymentRequirements;
 exports.flatRequirements = flatRequirements;
+exports.buildPaymentRequirementsMulti = buildPaymentRequirementsMulti;
 const network_1 = require("./network");
 const asset_1 = require("./asset");
 function normalizeResource(resource, description, mimeType, outputSchema) {
@@ -44,7 +45,7 @@ function normalizeResource(resource, description, mimeType, outputSchema) {
 }
 /**
  * Construct a single `accepts[]` entry. Most callers want
- * `buildPaymentRequirements()` which wraps this in the 402 envelope —
+ * `buildPaymentRequirements()` which wraps this in the 402 envelope ,
  * use `buildEntry()` directly when composing multi-asset accept lists.
  */
 function buildEntry(args) {
@@ -77,10 +78,48 @@ function buildPaymentRequirements(args) {
         accepts,
     };
 }
-/** Pick the first `accepts[]` entry — what the validator inspects. */
+/** Pick the first `accepts[]` entry, what the validator inspects. */
 function flatRequirements(body) {
     if (!body.accepts || body.accepts.length === 0) {
         throw new Error('flatRequirements: PaymentRequirementsBody.accepts is empty');
     }
     return body.accepts[0];
 }
+/**
+ * Build a multi-entry `accepts[]` body. Each option inherits the
+ * top-level `payTo` / `network` / `asset` / etc. defaults unless it sets
+ * its own. The `resource` block is shared across all entries (a 402 is
+ * for one route, even when it offers many payment options).
+ *
+ * Single-entry callers should keep using `buildPaymentRequirements()`;
+ * this function is the path for the multi-accept feature.
+ */
+function buildPaymentRequirementsMulti(args) {
+    if (!args.options || args.options.length === 0) {
+        throw new Error('buildPaymentRequirementsMulti: options must be non-empty');
+    }
+    const accepts = args.options.map((opt) => {
+        const asset = opt.asset ?? args.asset;
+        if (!asset) {
+            throw new Error('buildPaymentRequirementsMulti: option is missing `asset` and no top-level default was set');
+        }
+        return buildEntry({
+            amount: opt.amount,
+            asset,
+            payTo: opt.payTo ?? args.payTo,
+            network: opt.network ?? args.network,
+            resource: args.resource,
+            description: opt.description ?? args.description,
+            mimeType: opt.mimeType ?? args.mimeType,
+            outputSchema: args.outputSchema,
+            assetTransferMethod: opt.assetTransferMethod ?? args.assetTransferMethod,
+            maxTimeoutSeconds: opt.maxTimeoutSeconds ?? args.maxTimeoutSeconds,
+            extra: opt.extra ?? args.extra,
+        });
+    });
+    return {
+        x402Version: 2,
+        ...(args.withMissingHeaderError ? { error: 'PAYMENT-SIGNATURE header is required' } : {}),
+        accepts,
+    };
+}

package/srv/core/types.d.ts

@@ -1,15 +1,15 @@
 /**
  * Public type surface for x402 Cardano-v2.
  *
- * The shapes here match the v2 spec excerpt in
- * `docs/x402-cardano-integration.md` (envelope, requirements, payload).
- * Keep them as the single source of truth — middleware, facilitator and
+ * The shapes here match the Cardano-x402-v2 spec (envelope, requirements,
+ * payload). See `docs/protocol.md` for the wire-level reference. Keep
+ * this file as the single source of truth: middleware, facilitator and
  * helpers all import from here.
  */
 import type { Network } from './network';
 /** Asset-transfer method. v2 spec.  MVP supports only `default`. */
 export type AssetTransferMethod = 'default' | 'masumi' | 'script';
-/** v2 resource descriptor — was a bare string in v1. */
+/** v2 resource descriptor, was a bare string in v1. */
 export interface ResourceDescriptor {
     url: string;
     description: string;
@@ -45,7 +45,7 @@ export interface PaymentRequirementsBody {
 /**
  * Decoded `PAYMENT-SIGNATURE` envelope. The envelope payload references
  * a buyer-funded UTxO (the **nonce**) which must also appear in the
- * payment tx's inputs — this is the v2 replay defense, on-chain.
+ * payment tx's inputs, this is the v2 replay defense, on-chain.
  */
 export interface PaymentEnvelope {
     x402Version: 2;
@@ -54,7 +54,7 @@ export interface PaymentEnvelope {
     payload: {
         /** base64 CBOR of the signed payment tx */
         transaction: string;
-        /** `<txHash>#<outputIndex>` — UTxO acting as replay nonce */
+        /** `<txHash>#<outputIndex>`, UTxO acting as replay nonce */
         nonce: string;
     };
 }
@@ -69,6 +69,8 @@ export interface PaymentClaim {
     unit: string;
     /** The v2 asset string from requirements (passed-through for audit). */
     asset: string;
+    /** Bech32 recipient the matched requirements entry credited. */
+    payTo: string;
     /** The route / resource URL the buyer paid for. */
     resourceUrl: string;
     /** UTxO-ref nonce as `<txHash>#<index>`. */
@@ -113,4 +115,64 @@ export interface DecodedInput {
     outputIndex: number;
 }
 export type { Network };
+/**
+ * One payment option inside a multi-accept route. Lets a seller advertise
+ * e.g. "0.5 ADA or 0.1 USDM" for the same route. Top-level middleware
+ * options (`payTo`, `network`, `asset`, `description`, ...) fill any
+ * field the option leaves unset.
+ *
+ * The buyer's tx picks ONE option implicitly by which (payTo, asset) it
+ * actually pays; the facilitator selects the matching entry via
+ * `pickRequirement()` before running the six validation checks against it.
+ */
+export interface RouteOption {
+    amount: string | number | bigint;
+    asset?: string;
+    payTo?: string;
+    network?: Network | string;
+    description?: string;
+    mimeType?: string;
+    assetTransferMethod?: AssetTransferMethod;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+}
+/**
+ * What a `routePricing` entry or a `PriceResolver` may return.
+ *
+ *   - scalar             , single price in the route's default asset
+ *   - `RouteOption`      , single option with field overrides
+ *   - `RouteOption[]`    , multi-accept, buyer picks one on-chain
+ *
+ * Returning `null` from a resolver means "no gate, pass through" , the
+ * non-null type is what gates a request.
+ */
+export type PriceSpec = string | number | bigint | RouteOption | RouteOption[];
+/**
+ * Context passed to a `PriceResolver`. Intentionally minimal so we don't
+ * leak express/CAP-specific shapes through the public API. Both
+ * middlewares fill the common fields; CAP-only fields are optional.
+ */
+export interface PricingContext {
+    /**
+     * CAP: req.event ('READ'|'CREATE'|action-name).
+     * Express: last URL segment with OData function args stripped.
+     */
+    event: string;
+    /** CAP target name (e.g. 'PricesService.Quotes'). Undefined in Express. */
+    target?: string;
+    /** Express request path. Undefined in CAP. */
+    path?: string;
+    /** HTTP method. Express only. */
+    method?: string;
+    /** Lower-cased header map. Array values for multi-valued headers. */
+    headers: Record<string, string | string[] | undefined>;
+    /** Parsed query params (Express). */
+    query?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Dynamic pricing function. Sync or async. Return `null` to skip the
+ * gate, a scalar / option / option-array to charge. Errors thrown here
+ * are treated as middleware failures and surface as 500 to the buyer.
+ */
+export type PriceResolver = (ctx: PricingContext) => PriceSpec | null | Promise<PriceSpec | null>;
 //# sourceMappingURL=types.d.ts.map

package/srv/core/types.js

@@ -2,9 +2,9 @@
 /**
  * Public type surface for x402 Cardano-v2.
  *
- * The shapes here match the v2 spec excerpt in
- * `docs/x402-cardano-integration.md` (envelope, requirements, payload).
- * Keep them as the single source of truth — middleware, facilitator and
+ * The shapes here match the Cardano-x402-v2 spec (envelope, requirements,
+ * payload). See `docs/protocol.md` for the wire-level reference. Keep
+ * this file as the single source of truth: middleware, facilitator and
  * helpers all import from here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });