@odatano/x402 0.1.0 → 0.3.0

package/srv/bridge.js

@@ -4,18 +4,15 @@
  *
  * The x402 modules (facilitator, helpers, middleware) all import from
  * here so the underlying ODATANO surface is the only thing they couple
- * to — and so renames in core (`getTransaction` → `getTransactionByHash`)
+ * to, and so renames in core (`getTransaction` → `getTransactionByHash`)
  * stay isolated to this file.
  *
- * Two methods needed by Cardano-x402-v2 are NOT (yet) first-class on
- * `@odatano/core@1.7.7`:
- *   - `isUtxoUnspent(txHash, outputIndex)` — for replay-defense check 5b
- *   - `getCurrentSlot()`                   — for TTL check 6
+ * Two methods specific to Cardano-x402-v2 are first-class on
+ * `@odatano/core` since `1.7.8` (our minimum peer):
+ *   - `isUtxoUnspent(txHash, outputIndex)` for replay-defense check 5b
+ *   - `getCurrentSlot()`                   for TTL check 6
  *
- * Both are implemented here as **shims** on top of existing core
- * methods, so x402 works against an unmodified 1.7.7. When ODATANO
- * exposes either method natively (planned ≥1.7.8), we can swap the
- * shim for a direct call without touching downstream code.
+ * Both are called through directly here; no shim layer remains.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTransaction = void 0;
@@ -120,7 +117,7 @@ async function submitTransaction(signedCborHex) {
 }
 /**
  * Current chain tip slot. First-class method on `CardanoClient` since
- * `@odatano/core@1.7.8` — wraps `getLatestBlock().slot` with a
+ * `@odatano/core@1.7.8`, wraps `getLatestBlock().slot` with a
  * `ProviderUnavailableError` translation so consumers don't deal with
  * `null` slots.
  */
@@ -130,11 +127,11 @@ async function getCurrentSlot() {
 }
 /**
  * Check whether a UTxO is still unspent. First-class method since
- * `@odatano/core@1.7.8` — backed by `consumed_by` (Blockfrost) /
+ * `@odatano/core@1.7.8`, backed by `consumed_by` (Blockfrost) /
  * `is_spent` (Koios) / `queryLedgerState/utxo` (Ogmios).
  *
  * Returns `false` for txs that don't exist on chain or for
- * out-of-range output indices — both are "not spendable" from the
+ * out-of-range output indices, both are "not spendable" from the
  * caller's perspective.
  */
 async function isUtxoUnspent(txHash, outputIndex) {
@@ -150,6 +147,6 @@ async function isUtxoUnspent(txHash, outputIndex) {
 // parseTransaction is exported from @odatano/core's barrel and runs
 // entirely client-side. Re-export so x402 users don't need a second
 // import for tx introspection. We declare the type loosely (unknown
-// CBOR-parsed shape) — consumers cast to ODATANO's `ParsedTransaction`
+// CBOR-parsed shape), consumers cast to ODATANO's `ParsedTransaction`
 // from `@odatano/core` directly if they need the structured fields.
 exports.parseTransaction = od ? od.parseTransaction : undefined;

package/srv/cds-augment.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="@cap-js/cds-types" />
+/**
+ * Public types entry — hand-written wrapper around the generated barrel.
+ *
+ * Why this file exists: the triple-slash reference below is the only
+ * way to ship `@cap-js/cds-types`' module-augmentation of `@sap/cds`
+ * to TypeScript consumers without forcing them to mutate their own
+ * tsconfig. References authored inside `.ts` sources get stripped by
+ * tsc during `.d.ts` emit — references in hand-written `.d.ts` files
+ * are preserved verbatim, so we use a hand-written one as the
+ * advertised `types` entry in package.json.
+ *
+ * Consumers should still install `@cap-js/cds-types` (declared as an
+ * optional peer dependency) — this file only routes the augmentation
+ * once that package is resolvable.
+ */
+export * from './index';

package/srv/client/axios.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `x402Axios`, attach a response interceptor to an existing axios
+ * instance so 402 responses trigger a payment and retry.
+ *
+ * **No hard axios dependency.** We use structural typing for the
+ * instance: anything with the standard axios shape (interceptors,
+ * request, defaults.headers) works. Verified against axios 1.x.
+ *
+ * Usage:
+ *   import axios from 'axios';
+ *   import { x402Axios, createBridgePayHandler } from '@odatano/x402';
+ *
+ *   const client = x402Axios(axios.create({ baseURL: '...' }), {
+ *     pay: createBridgePayHandler({ buyerBech32, signTx }),
+ *   });
+ *   await client.get('/api/premium/foo');   // returns 200 after pay
+ */
+import type { X402ClientOptions } from './types';
+interface AxiosRequestConfigLike {
+    headers?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+interface AxiosInstanceLike {
+    interceptors: {
+        response: {
+            use: (onFulfilled: (res: unknown) => unknown, onRejected: (err: unknown) => unknown) => number;
+        };
+    };
+    request: (cfg: AxiosRequestConfigLike) => Promise<unknown>;
+}
+/**
+ * Attach the x402 response interceptor in-place and return the same
+ * instance for chaining. The interceptor only fires on 402 responses;
+ * everything else passes through unchanged.
+ */
+export declare function x402Axios<T extends AxiosInstanceLike>(instance: T, opts: X402ClientOptions): T;
+export {};
+//# sourceMappingURL=axios.d.ts.map

package/srv/client/axios.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * `x402Axios`, attach a response interceptor to an existing axios
+ * instance so 402 responses trigger a payment and retry.
+ *
+ * **No hard axios dependency.** We use structural typing for the
+ * instance: anything with the standard axios shape (interceptors,
+ * request, defaults.headers) works. Verified against axios 1.x.
+ *
+ * Usage:
+ *   import axios from 'axios';
+ *   import { x402Axios, createBridgePayHandler } from '@odatano/x402';
+ *
+ *   const client = x402Axios(axios.create({ baseURL: '...' }), {
+ *     pay: createBridgePayHandler({ buyerBech32, signTx }),
+ *   });
+ *   await client.get('/api/premium/foo');   // returns 200 after pay
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.x402Axios = x402Axios;
+const envelope_1 = require("./envelope");
+const errors_1 = require("./errors");
+// Marker key on the config to break infinite-retry loops.
+const RETRY_KEY = '__x402_x402Retries';
+function isAxiosError(e) {
+    return !!e && typeof e === 'object' && 'response' in e;
+}
+/**
+ * Attach the x402 response interceptor in-place and return the same
+ * instance for chaining. The interceptor only fires on 402 responses;
+ * everything else passes through unchanged.
+ */
+function x402Axios(instance, opts) {
+    if (typeof opts?.pay !== 'function') {
+        throw new TypeError('x402Axios: opts.pay must be a function');
+    }
+    const maxRetries = opts.maxRetries ?? 1;
+    const selectFirst = (a) => a[0];
+    const select = opts.selectAccepts ?? selectFirst;
+    function maybeWrap(body, kind, httpStatus, cause) {
+        if (body && body.x402Version === 2 && Array.isArray(body.accepts)) {
+            return (0, errors_1.paymentErrorFromBody)(body, { kind, httpStatus, cause });
+        }
+        return new errors_1.X402PaymentError({
+            message: `x402Axios: ${kind.replace('_', ' ')}`,
+            kind: 'invalid_402_body',
+            httpStatus,
+            ...(cause !== undefined ? { cause } : {}),
+        });
+    }
+    instance.interceptors.response.use((response) => response, async (error) => {
+        if (!isAxiosError(error) || error.response?.status !== 402 || !error.config) {
+            throw error;
+        }
+        const cfg = error.config;
+        const retries = Number(cfg[RETRY_KEY] ?? 0);
+        // CAP-style servers wrap the v2 body inside an OData error envelope.
+        // Defensively unwrap before validating shape.
+        const body = (0, errors_1.unwrapCapEnvelope)(error.response.data);
+        const status = error.response.status;
+        if (retries >= maxRetries) {
+            if (opts.errorOnFailure) {
+                throw maybeWrap(body, 'retries_exhausted', status, error);
+            }
+            throw error;
+        }
+        if (!body || body.x402Version !== 2 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+            if (opts.errorOnFailure) {
+                throw maybeWrap(body, 'invalid_402_body', status, error);
+            }
+            throw error;
+        }
+        const chosen = select(body.accepts);
+        if (!chosen) {
+            if (opts.errorOnFailure) {
+                throw maybeWrap(body, 'server_rejected', status, error);
+            }
+            throw error;
+        }
+        // Wrap pay-handler throws unconditionally, callers benefit from
+        // the structured shape regardless of errorOnFailure.
+        let payResult;
+        try {
+            payResult = await opts.pay(chosen);
+        }
+        catch (err) {
+            throw new errors_1.X402PaymentError({
+                message: `x402Axios: 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: payResult.signedTxCborHex,
+            nonceRef: payResult.nonceRef,
+        });
+        const nextCfg = {
+            ...cfg,
+            headers: { ...(cfg.headers ?? {}), 'PAYMENT-SIGNATURE': header },
+            [RETRY_KEY]: retries + 1,
+        };
+        return instance.request(nextCfg);
+    });
+    return instance;
+}

package/srv/client/envelope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build the `PAYMENT-SIGNATURE` header value for a Cardano-x402-v2 retry.
+ *
+ * Inverse of `srv/core/decode.ts`. The wire format is:
+ *
+ *   PAYMENT-SIGNATURE: base64(JSON.stringify({
+ *     x402Version: 2,
+ *     scheme: 'exact',
+ *     network: 'cardano:preprod' | 'cardano:mainnet' | 'cardano:preview',
+ *     payload: {
+ *       transaction: '<base64 CBOR of signed tx>',
+ *       nonce:       '<txHash>#<outputIndex>'
+ *     }
+ *   }))
+ *
+ * Pure function, no chain calls, no I/O. Callable from any runtime
+ * that has `Buffer` (Node) or a polyfill (browser bundlers usually
+ * provide one via `buffer`).
+ */
+import type { Network } from '../core/network';
+export interface EncodeEnvelopeArgs {
+    network: Network;
+    /** Hex of the SIGNED payment tx (vkey witnesses already attached). */
+    signedTxCborHex: string;
+    /** `<txHash>#<outputIndex>` UTxO-ref nonce. */
+    nonceRef: string;
+}
+/**
+ * Encode the v2 PAYMENT-SIGNATURE envelope. Validates shape eagerly so
+ * a malformed call fails here, not on the server's `decode()`.
+ */
+export declare function encodePaymentEnvelope(args: EncodeEnvelopeArgs): string;
+//# sourceMappingURL=envelope.d.ts.map

package/srv/client/envelope.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Build the `PAYMENT-SIGNATURE` header value for a Cardano-x402-v2 retry.
+ *
+ * Inverse of `srv/core/decode.ts`. The wire format is:
+ *
+ *   PAYMENT-SIGNATURE: base64(JSON.stringify({
+ *     x402Version: 2,
+ *     scheme: 'exact',
+ *     network: 'cardano:preprod' | 'cardano:mainnet' | 'cardano:preview',
+ *     payload: {
+ *       transaction: '<base64 CBOR of signed tx>',
+ *       nonce:       '<txHash>#<outputIndex>'
+ *     }
+ *   }))
+ *
+ * Pure function, no chain calls, no I/O. Callable from any runtime
+ * that has `Buffer` (Node) or a polyfill (browser bundlers usually
+ * provide one via `buffer`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodePaymentEnvelope = encodePaymentEnvelope;
+const NONCE_RE = /^[0-9a-f]{64}#\d+$/i;
+const HEX_RE = /^[0-9a-f]+$/i;
+/**
+ * Encode the v2 PAYMENT-SIGNATURE envelope. Validates shape eagerly so
+ * a malformed call fails here, not on the server's `decode()`.
+ */
+function encodePaymentEnvelope(args) {
+    if (!args.network) {
+        throw new TypeError('encodePaymentEnvelope: network is required');
+    }
+    if (typeof args.signedTxCborHex !== 'string' || !HEX_RE.test(args.signedTxCborHex)) {
+        throw new TypeError('encodePaymentEnvelope: signedTxCborHex must be a hex string');
+    }
+    if (args.signedTxCborHex.length % 2 !== 0) {
+        throw new TypeError('encodePaymentEnvelope: signedTxCborHex has odd length');
+    }
+    if (!NONCE_RE.test(args.nonceRef)) {
+        throw new TypeError(`encodePaymentEnvelope: nonceRef must be '<txHash>#<outputIndex>' (64-hex#int), got '${args.nonceRef}'`);
+    }
+    const envelope = {
+        x402Version: 2,
+        scheme: 'exact',
+        network: args.network,
+        payload: {
+            transaction: Buffer.from(args.signedTxCborHex, 'hex').toString('base64'),
+            nonce: args.nonceRef,
+        },
+    };
+    return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+}

package/srv/client/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Typed client-side errors thrown by `x402Fetch` / `x402Axios`.
+ *
+ * The server-side `X402Error` (in `srv/core/errors.ts`) is a different
+ * class with a different purpose: it's thrown inside the decode +
+ * validate pipeline and carries one of the canonical `X402Code` values.
+ *
+ * `X402PaymentError` here is the client-facing analog: it surfaces in
+ * caller code (browser, CLI, server-to-server) when a payment attempt
+ * cannot complete. Callers can `instanceof`-check or pattern-match on
+ * `.kind` to distinguish:
+ *
+ *   - 'server_rejected'      , the server returned 402 with a structured
+ *                              body. `code` carries the server's
+ *                              canonical X402Code (e.g. `wrong_recipient`),
+ *                              `serverError` carries the raw error string
+ *                              for human display.
+ *   - 'pay_handler_failed'   , the user-supplied `pay` callback threw
+ *                              (wallet rejection, no funds, signer error,
+ *                              etc). `cause` holds the original error.
+ *   - 'retries_exhausted'    , the request was still 402 after
+ *                              `maxRetries` payment attempts. Same shape
+ *                              as `server_rejected` but indicates
+ *                              repeated failure.
+ *   - 'invalid_402_body'     , the server returned 402 but the body
+ *                              wasn't a v2 PaymentRequirementsBody.
+ *
+ * The class is plain (no abstract methods, no fluent builders) so users
+ * can construct it themselves if they're wrapping the wrappers.
+ */
+import type { PaymentRequirementEntry, PaymentRequirementsBody } from '../core/types';
+export type X402PaymentErrorKind = 'server_rejected' | 'retries_exhausted' | 'pay_handler_failed' | 'invalid_402_body';
+export interface X402PaymentErrorInit {
+    message: string;
+    kind: X402PaymentErrorKind;
+    /** Canonical X402Code from the server, when known. */
+    code?: string;
+    /** `accepts[]` from the 402 body, for the caller to retry against. */
+    accepts?: PaymentRequirementEntry[];
+    /** HTTP status code that triggered the error (usually 402). */
+    httpStatus?: number;
+    /** Verbatim `error` string from the 402 body, for human display. */
+    serverError?: string;
+    /** Wrapped underlying error (wallet rejection, axios error, etc.). */
+    cause?: unknown;
+}
+/**
+ * Thrown by `x402Fetch` and `x402Axios` when a payment attempt fails or
+ * is exhausted.
+ *
+ * `instanceof X402PaymentError` is the reliable runtime check; the
+ * `.kind` field is the discriminator for switching on cause.
+ */
+export declare class X402PaymentError extends Error {
+    readonly kind: X402PaymentErrorKind;
+    readonly code?: string;
+    readonly accepts?: PaymentRequirementEntry[];
+    readonly httpStatus?: number;
+    readonly serverError?: string;
+    readonly cause?: unknown;
+    constructor(init: X402PaymentErrorInit);
+}
+/**
+ * Defensively unwrap a CAP / OData error envelope around a v2 body.
+ *
+ * Background: `gateService` in this package historically (≤ v0.2)
+ * reaches a 402 via `req.reject(402, JSON.stringify(body))`, which
+ * CAP wraps into its standard OData error shape, putting the canonical
+ * v2 body inside `error.message` as a JSON string:
+ *
+ *   { "error": { "message": "{\"x402Version\":2, ... }", "code": "402", ... } }
+ *
+ * The Express middleware emits the v2 body at the top level directly.
+ * This helper detects the CAP wrap and returns the unwrapped candidate
+ * so client wrappers can validate v2 shape uniformly. Non-CAP bodies
+ * pass through untouched.
+ *
+ * Symmetric server-side fix (emit canonical body even through CAP) is
+ * a separate concern, deferred until we can validate the CAP-version
+ * specific behaviour. The unwrap below keeps `x402Fetch` /
+ * `x402Axios` working against both shapes.
+ */
+export declare function unwrapCapEnvelope(parsed: unknown): unknown;
+/**
+ * Parse the (server, canonical) error string from a `PaymentRequirementsBody`.
+ *
+ * The middleware encodes failures as `"<base error> (<code>): <reason>"`
+ * (see `cap.ts` / `express.ts`). We pull the code out so callers can
+ * dispatch on it without re-parsing the wire string. The reason is
+ * preserved in `.serverError`.
+ *
+ * Returns `undefined` when the body has no recognizable code (e.g. the
+ * MISSING_HEADER path, where the middleware omits the parenthesised
+ * suffix).
+ */
+export declare function parseErrorCode(serverError?: string): string | undefined;
+/**
+ * Build an `X402PaymentError` from a parsed 402 body. `kind` defaults
+ * to `server_rejected`; pass `'retries_exhausted'` when called after
+ * the retry loop gave up.
+ */
+export declare function paymentErrorFromBody(body: PaymentRequirementsBody, init?: {
+    kind?: X402PaymentErrorKind;
+    httpStatus?: number;
+    cause?: unknown;
+}): X402PaymentError;
+//# sourceMappingURL=errors.d.ts.map

package/srv/client/errors.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Typed client-side errors thrown by `x402Fetch` / `x402Axios`.
+ *
+ * The server-side `X402Error` (in `srv/core/errors.ts`) is a different
+ * class with a different purpose: it's thrown inside the decode +
+ * validate pipeline and carries one of the canonical `X402Code` values.
+ *
+ * `X402PaymentError` here is the client-facing analog: it surfaces in
+ * caller code (browser, CLI, server-to-server) when a payment attempt
+ * cannot complete. Callers can `instanceof`-check or pattern-match on
+ * `.kind` to distinguish:
+ *
+ *   - 'server_rejected'      , the server returned 402 with a structured
+ *                              body. `code` carries the server's
+ *                              canonical X402Code (e.g. `wrong_recipient`),
+ *                              `serverError` carries the raw error string
+ *                              for human display.
+ *   - 'pay_handler_failed'   , the user-supplied `pay` callback threw
+ *                              (wallet rejection, no funds, signer error,
+ *                              etc). `cause` holds the original error.
+ *   - 'retries_exhausted'    , the request was still 402 after
+ *                              `maxRetries` payment attempts. Same shape
+ *                              as `server_rejected` but indicates
+ *                              repeated failure.
+ *   - 'invalid_402_body'     , the server returned 402 but the body
+ *                              wasn't a v2 PaymentRequirementsBody.
+ *
+ * The class is plain (no abstract methods, no fluent builders) so users
+ * can construct it themselves if they're wrapping the wrappers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402PaymentError = void 0;
+exports.unwrapCapEnvelope = unwrapCapEnvelope;
+exports.parseErrorCode = parseErrorCode;
+exports.paymentErrorFromBody = paymentErrorFromBody;
+/**
+ * Thrown by `x402Fetch` and `x402Axios` when a payment attempt fails or
+ * is exhausted.
+ *
+ * `instanceof X402PaymentError` is the reliable runtime check; the
+ * `.kind` field is the discriminator for switching on cause.
+ */
+class X402PaymentError extends Error {
+    kind;
+    code;
+    accepts;
+    httpStatus;
+    serverError;
+    // Override Error's `cause` typing, ours is `unknown` to allow any value.
+    cause;
+    constructor(init) {
+        super(init.message);
+        this.name = 'X402PaymentError';
+        this.kind = init.kind;
+        if (init.code !== undefined)
+            this.code = init.code;
+        if (init.accepts !== undefined)
+            this.accepts = init.accepts;
+        if (init.httpStatus !== undefined)
+            this.httpStatus = init.httpStatus;
+        if (init.serverError !== undefined)
+            this.serverError = init.serverError;
+        if (init.cause !== undefined)
+            this.cause = init.cause;
+        // V8: keep stack trace pointing at caller, not constructor.
+        if (typeof Error.captureStackTrace === 'function') {
+            Error
+                .captureStackTrace(this, X402PaymentError);
+        }
+    }
+}
+exports.X402PaymentError = X402PaymentError;
+/**
+ * Defensively unwrap a CAP / OData error envelope around a v2 body.
+ *
+ * Background: `gateService` in this package historically (≤ v0.2)
+ * reaches a 402 via `req.reject(402, JSON.stringify(body))`, which
+ * CAP wraps into its standard OData error shape, putting the canonical
+ * v2 body inside `error.message` as a JSON string:
+ *
+ *   { "error": { "message": "{\"x402Version\":2, ... }", "code": "402", ... } }
+ *
+ * The Express middleware emits the v2 body at the top level directly.
+ * This helper detects the CAP wrap and returns the unwrapped candidate
+ * so client wrappers can validate v2 shape uniformly. Non-CAP bodies
+ * pass through untouched.
+ *
+ * Symmetric server-side fix (emit canonical body even through CAP) is
+ * a separate concern, deferred until we can validate the CAP-version
+ * specific behaviour. The unwrap below keeps `x402Fetch` /
+ * `x402Axios` working against both shapes.
+ */
+function unwrapCapEnvelope(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return parsed;
+    const maybeError = parsed.error;
+    if (!maybeError || typeof maybeError !== 'object')
+        return parsed;
+    const msg = maybeError.message;
+    if (typeof msg !== 'string')
+        return parsed;
+    try {
+        return JSON.parse(msg);
+    }
+    catch {
+        return parsed;
+    }
+}
+/**
+ * Parse the (server, canonical) error string from a `PaymentRequirementsBody`.
+ *
+ * The middleware encodes failures as `"<base error> (<code>): <reason>"`
+ * (see `cap.ts` / `express.ts`). We pull the code out so callers can
+ * dispatch on it without re-parsing the wire string. The reason is
+ * preserved in `.serverError`.
+ *
+ * Returns `undefined` when the body has no recognizable code (e.g. the
+ * MISSING_HEADER path, where the middleware omits the parenthesised
+ * suffix).
+ */
+function parseErrorCode(serverError) {
+    if (!serverError)
+        return undefined;
+    const m = serverError.match(/\(([a-z_]+)\)/);
+    return m ? m[1] : undefined;
+}
+/**
+ * Build an `X402PaymentError` from a parsed 402 body. `kind` defaults
+ * to `server_rejected`; pass `'retries_exhausted'` when called after
+ * the retry loop gave up.
+ */
+function paymentErrorFromBody(body, init = {}) {
+    const code = parseErrorCode(body.error);
+    return new X402PaymentError({
+        message: body.error ?? 'payment required',
+        kind: init.kind ?? 'server_rejected',
+        ...(code !== undefined ? { code } : {}),
+        accepts: body.accepts,
+        httpStatus: init.httpStatus ?? 402,
+        ...(body.error !== undefined ? { serverError: body.error } : {}),
+        ...(init.cause !== undefined ? { cause: init.cause } : {}),
+    });
+}

package/srv/client/fetch.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `x402Fetch`, drop-in fetch wrapper that auto-handles 402 responses.
+ *
+ * On a 402 response the wrapper:
+ *   1. Parses the body as a v2 `PaymentRequirementsBody`.
+ *   2. Picks an `accepts[]` entry (via `selectAccepts`, default = first).
+ *   3. Calls the user's `pay` handler to get `{ signedTxCborHex, nonceRef }`.
+ *   4. Encodes a `PAYMENT-SIGNATURE` envelope.
+ *   5. Retries the original request with the header attached.
+ *
+ * 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.
+ *
+ * Native fetch is used by default (Node ≥18, all modern browsers).
+ * Pass `opts.fetch` to override (testing, custom agents, etc.).
+ */
+import type { X402ClientOptions } from './types';
+type FetchFn = typeof globalThis.fetch;
+export interface X402FetchOptions extends X402ClientOptions {
+    /** Override the underlying fetch. Defaults to `globalThis.fetch`. */
+    fetch?: FetchFn;
+}
+/**
+ * Wrap `fetch` with 402-handling. The returned function has the same
+ * signature as native fetch, so it's a drop-in replacement.
+ */
+export declare function x402Fetch(opts: X402FetchOptions): FetchFn;
+export {};
+//# sourceMappingURL=fetch.d.ts.map