@odatano/x402 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@odatano/x402` are documented here. The format follows [
 
 **Pre-1.0 caveat:** minor versions may include breaking changes until `1.0.0`.
 
+## [0.3.0] - 2026-05-15
+
+### Added
+- **`createFacilitatorRouter()`** , reference HTTP facilitator. Returns an Express `Router` exposing `POST /verify-settle`, `GET /supported`, and an open `GET /healthz` liveness probe. Composable with any auth scheme via the `auth(req)` hook; defaults to `localFacilitator()`. Facilitator-side audit hooks (`onRejected`, `onPending`) fill the gap left by `onAccepted` (which is invoked client-side by `httpFacilitator()`). See [`examples/facilitator-server/`](examples/facilitator-server/) and [`docs/facilitator-protocol.md`](docs/facilitator-protocol.md#reference-implementation).
+- **Multi-accept payment options** , `routePricing` (and `priceUnits`) now accept `RouteOption[]` so a single route can offer e.g. "0.5 ADA *or* 0.1 USDM". The buyer picks one implicitly by which `(payTo, asset)` the payment tx credits; new `pickRequirement()` selector in `srv/core/validate.ts` routes the tx to the matching entry before the six strict checks run. Single-entry behaviour is bit-identical to v0.2. New builder: `buildPaymentRequirementsMulti()`.
+- **Dynamic `PriceResolver`** , `routePricing` can be a function `(PricingContext) => PriceSpec | null | Promise<...>`. Returning `null` passes the request through ungated, enabling free-tier, role-based, or per-payload pricing. `PricingContext` exposes `event`, `target` (CAP), `path`/`method`/`query` (Express), and `headers`. See [`docs/usage.md`](docs/usage.md#pricespec-and-priceresolver).
+- **Receipts persistence (CAP)** , new `receipts?: boolean | { entity?: string }` option on `gateService`. When set, one INSERT per accepted payment, post-settle, pre-response. Default entity `odatano.x402.X402Receipts` ships in `db/x402-receipts.cds` and is auto-discovered by CAP. INSERT failures are logged and never block the response. See [`docs/usage.md`](docs/usage.md#receipts-persistence-receipts).
+- **Subscription / time-limited grants (CAP)** , new `grants?: boolean | { ttlSeconds?: number; entity?: string }` option on `gateService`. On accepted payment the gate issues an opaque token and returns it via `X-PAYMENT-GRANT` / `X-PAYMENT-GRANT-EXPIRES` response headers; subsequent requests presenting the token on `X-PAYMENT-GRANT` bypass the 402 + verify+settle pipeline until expiry. Default TTL 3600s. Grants are single-route (strict URL equality). Default entity `odatano.x402.X402Grants` ships in `db/x402-grants.cds`. DB failures during issue or lookup are swallowed: failing DB never denies a paying buyer their response. See [`docs/usage.md`](docs/usage.md#subscription--time-limited-grants-grants).
+- **Typed client errors** , new `X402PaymentError` class (with `kind`, `code`, `accepts`, `httpStatus`, `serverError`, `cause` fields). Thrown by `x402Fetch` and `x402Axios` to surface payment failures. Pay-handler errors are ALWAYS wrapped (with the original on `.cause`); add `errorOnFailure: true` to opt into typed throws on unrecovered 402s instead of the previous return-the-response / re-throw-AxiosError behaviour. Helpers `parseErrorCode` and `paymentErrorFromBody` are exported for consumers wrapping the wrappers. See [`docs/usage.md`](docs/usage.md#client-side-errors-x402paymenterror).
+- **Browser-buyer example** , `examples/browser-buyer/` Vite scaffold showing CIP-30 wallet + `x402Fetch` wiring. Documents the typical "unsigned-from-server, signed-by-wallet" architecture (server exposes `POST /pay/intent` via `buildUnsignedPaymentTx`; browser signs via CIP-30). Includes CORS notes for cross-origin deployments.
+
+### Fixed
+- **`x402Fetch` / `x402Axios` now interop with `gateService`** out of the box. CAP's `req.reject(402, body)` wraps the canonical v2 body inside its standard OData error envelope (`{ error: { message: "<json>", code: "402", ... } }`), so previous client wrappers saw `body.x402Version === undefined` and bailed without retrying. Both clients now defensively unwrap the OData envelope before validating shape. Reported by the CHAINFEED team; matches the workaround they were shipping in `scripts/buyer-pay-and-fetch.ts`. New helper `unwrapCapEnvelope` is exported for consumers wrapping the wrappers.
+
+### Known issues
+- The CAP `gateService` still emits 402 responses wrapped in CAP's OData error envelope on the wire (because `req.reject` is the only documented abort path). Third-party x402 clients hitting a CAP-gated server will see the wrapped shape; only `@odatano/x402`'s own clients unwrap it. Direct-write-to-`req.http.res` is the planned symmetric fix but needs validation against `@sap/cds` ^9 internals; tracked for v0.3.1.
+- `PaymentClaim.payTo` , verified recipient address now populated on the claim (was previously only on the requirements entry). Useful for `onAccepted` audit and receipts.
+
+### Changed
+- Test count: 177 → 230 (HTTP-server round-trips, multi-accept + dynamic-pricing across `requirements`/`validate`/`verify`/`cap`/`express`, 4 receipts cases, 5 grants cases, 13 client-error cases).
+- `srv/middleware/{cap,express}.ts` now emit `accepts[]` via `buildPaymentRequirementsMulti()`; single-entry callers are unaffected (one-entry array produces a body byte-identical to v0.2).
+- `srv/facilitator/verify.ts` decodes the envelope BEFORE selecting a requirements entry; multi-accept depends on knowing which `(payTo, asset)` the tx actually credited.
+
 ## [0.2.0] - 2026-05-15
 
 ### Added

package/README.md

@@ -1,5 +1,10 @@
 # @odatano/x402
 
+[![npm](https://img.shields.io/npm/v/@odatano/x402?color=cb3837&logo=npm)](https://www.npmjs.com/package/@odatano/x402)
+[![tests](https://github.com/ODATANO/x402/actions/workflows/test.yaml/badge.svg)](https://github.com/ODATANO/x402/actions/workflows/test.yaml)
+[![@odatano/core](https://img.shields.io/github/package-json/dependency-version/ODATANO/x402/peer/@odatano/core?label=%40odatano%2Fcore&color=0e7c66)](https://www.npmjs.com/package/@odatano/core)
+[![spec](https://img.shields.io/badge/Cardano--x402-v2-blueviolet)](https://github.com/masumi-network/x402-cardano)
+
 x402 payment gating for SAP CAP applications, backed by Cardano.
 
 Wire a single `before('*')` hook into your CAP service. Every gated request returns **HTTP 402 Payment Required** until the caller proves on-chain settlement. Asset-agnostic: pay in ADA, USDM, or any native asset.

package/cds-plugin.js

@@ -7,4 +7,6 @@
  * (outDir: ".") so this require path resolves both in dev (tsx) and
  * after `npm run build`.
  */
+// CAP loads this file as a CommonJS entrypoint, so `require()` is required here.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 module.exports = require('./srv/plugin');

package/db/x402-grants.cds

@@ -0,0 +1,49 @@
+/**
+ * Time-limited access grants issued after an accepted x402 payment.
+ *
+ * Pattern: pay once, get N seconds of free access to the same route.
+ * The server issues an opaque random token on `accepted`, returns it via
+ * the `X-PAYMENT-GRANT` response header, and the buyer presents it on
+ * subsequent requests via `X-PAYMENT-GRANT` request header. Until the
+ * grant expires, the gate skips the 402 + verify+settle pipeline.
+ *
+ * Replay defense: each grant is single-route + time-bound. A grant
+ * issued for `/Quotes` cannot be used against `/getBestPrice` (cheap
+ * route boundary, the picker enforces equality). Stolen tokens are
+ * useful only until expiry.
+ *
+ * Cleanup: expired rows accumulate. The `lookupGrant` helper checks
+ * `expiresAt < now` and reports `expired`; consumers may run their own
+ * cleanup (`DELETE … WHERE expiresAt < now()`) on whatever schedule
+ * fits. The library does NOT auto-prune.
+ */
+
+namespace odatano.x402;
+
+entity X402Grants {
+    key id         : UUID;
+
+    @description: 'Opaque random token, base64url 32 bytes.'
+        token      : String(64) @assert.unique;
+
+    @description: 'Resource URL this grant unlocks (exact match).'
+        route      : String(500);
+
+    @description: 'Sender address from the original payment (if resolved).'
+        payerAddr  : String(120);
+
+    @description: 'Tx hash of the payment that bought this grant.'
+        txHash     : String(64);
+
+    @description: 'Asset of the underlying payment, audit only.'
+        asset      : String(120);
+
+    @description: 'cardano:mainnet | cardano:preprod | cardano:preview.'
+        network    : String(20);
+
+    @description: 'Server-side timestamp at issue.'
+        issuedAt   : Timestamp;
+
+    @description: 'Server-side timestamp when the grant becomes invalid.'
+        expiresAt  : Timestamp;
+}

package/db/x402-receipts.cds

@@ -0,0 +1,44 @@
+/**
+ * Optional persistence for accepted x402 payments.
+ *
+ * Enabled per-service by setting `receipts: true` on `gateService(opts)`.
+ * The gate writes one row per accepted payment, after settle confirms,
+ * BEFORE the response is served. Insert failures are logged and never
+ * block the response, the canonical record is on chain regardless.
+ *
+ * Namespace and entity name are stable, consumers can SELECT against
+ * `odatano.x402.X402Receipts` directly or extend it in their own model.
+ */
+
+namespace odatano.x402;
+
+entity X402Receipts {
+    key id         : UUID;
+
+    @description: 'Lowercase 64-char hex of the buyer''s settled payment tx.'
+        txHash     : String(64) @assert.unique;
+
+    @description: 'Sender address (first input bech32) if the facilitator resolved it.'
+        payerAddr  : String(120);
+
+    @description: 'Recipient bech32 the route required.'
+        payTo      : String(120);
+
+    @description: 'v2 asset string, ''lovelace'' or ''<policy>.<nameHex>''.'
+        asset      : String(120);
+
+    @description: 'Amount paid in raw units, BigInt-safe string.'
+        amount     : String(32);
+
+    @description: 'cardano:mainnet | cardano:preprod | cardano:preview.'
+        network    : String(20);
+
+    @description: 'Resource URL the buyer paid for (request originalUrl or cap://<event>).'
+        route      : String(500);
+
+    @description: '<txHash>#<index> of the UTxO that was the replay nonce.'
+        nonceRef   : String(80);
+
+    @description: 'Server-side timestamp when the receipt was written (post-settle).'
+        at         : Timestamp;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odatano/x402",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "x402 Cardano-v2 payment library for SAP CAP applications",
   "license": "Apache-2.0",
   "main": "srv/index.js",
@@ -37,8 +37,8 @@
     }
   },
   "devDependencies": {
-    "@cap-js/cds-types": "^0.15.0",
     "@cap-js/cds-typer": "^0.38.0",
+    "@cap-js/cds-types": "^0.15.0",
     "@cap-js/sqlite": "^2",
     "@odatano/core": "^1.7.8",
     "@odatano/x402": ".",
@@ -53,6 +53,7 @@
     "jest": "^29",
     "ts-jest": "^29",
     "tsx": "^4",
-    "typescript": "^5"
+    "typescript": "^5",
+    "typescript-eslint": "^8.59.3"
   }
 }

package/srv/bridge.d.ts

@@ -3,18 +3,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.
  */
 export interface BridgeAsset {
     unit: string;
@@ -49,18 +46,18 @@ export declare function getProtocolParameters(): Promise<unknown>;
 export declare function submitTransaction(signedCborHex: string): Promise<string>;
 /**
  * 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.
  */
 export declare function getCurrentSlot(): Promise<number>;
 /**
  * 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.
  */
 export declare function isUtxoUnspent(txHash: string, outputIndex: number): Promise<boolean>;

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/client/axios.d.ts

@@ -1,5 +1,5 @@
 /**
- * `x402Axios` — attach a response interceptor to an existing axios
+ * `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

package/srv/client/axios.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * `x402Axios` — attach a response interceptor to an existing axios
+ * `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
@@ -19,6 +19,7 @@
 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) {
@@ -36,26 +37,64 @@ function x402Axios(instance, opts) {
     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);
-        if (retries >= maxRetries)
+        // 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;
-        const body = error.response.data;
-        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 maybeWrap(body, 'invalid_402_body', status, error);
+            }
             throw error;
         }
         const chosen = select(body.accepts);
-        if (!chosen)
+        if (!chosen) {
+            if (opts.errorOnFailure) {
+                throw maybeWrap(body, 'server_rejected', status, error);
+            }
             throw error;
-        const { signedTxCborHex, nonceRef } = await opts.pay(chosen);
+        }
+        // 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,
-            nonceRef,
+            signedTxCborHex: payResult.signedTxCborHex,
+            nonceRef: payResult.nonceRef,
         });
         const nextCfg = {
             ...cfg,

package/srv/client/envelope.d.ts

@@ -13,7 +13,7 @@
  *     }
  *   }))
  *
- * Pure function — no chain calls, no I/O. Callable from any runtime
+ * 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`).
  */

package/srv/client/envelope.js

@@ -14,7 +14,7 @@
  *     }
  *   }))
  *
- * Pure function — no chain calls, no I/O. Callable from any runtime
+ * 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`).
  */

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 } : {}),
+    });
+}