@odatano/x402 0.1.0 → 0.2.0

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/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

package/srv/client/fetch.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * `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.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.x402Fetch = x402Fetch;
+const envelope_1 = require("./envelope");
+/**
+ * Wrap `fetch` with 402-handling. The returned function has the same
+ * signature as native fetch, so it's a drop-in replacement.
+ */
+function x402Fetch(opts) {
+    if (typeof opts?.pay !== 'function') {
+        throw new TypeError('x402Fetch: opts.pay must be a function');
+    }
+    const baseFetch = opts.fetch ?? globalThis.fetch;
+    if (typeof baseFetch !== 'function') {
+        throw new TypeError('x402Fetch: no fetch implementation available (Node ≥18 or pass opts.fetch)');
+    }
+    const maxRetries = opts.maxRetries ?? 1;
+    const selectFirst = (a) => a[0];
+    const select = opts.selectAccepts ?? selectFirst;
+    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.
+        let nextInit = init;
+        // 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)
+                return res;
+            // Parse 402 body. If it's not a v2 PaymentRequirementsBody we
+            // bail with the original response (caller's problem to handle).
+            let body;
+            try {
+                body = (await res.clone().json());
+            }
+            catch {
+                return res;
+            }
+            if (body?.x402Version !== 2 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+                return res;
+            }
+            const chosen = select(body.accepts);
+            if (!chosen)
+                return res;
+            const { signedTxCborHex, nonceRef } = await opts.pay(chosen);
+            const header = (0, envelope_1.encodePaymentEnvelope)({
+                network: chosen.network,
+                signedTxCborHex,
+                nonceRef,
+            });
+            // Merge PAYMENT-SIGNATURE into headers without mutating caller's init.
+            const mergedHeaders = new Headers(nextInit?.headers ?? init?.headers);
+            mergedHeaders.set('PAYMENT-SIGNATURE', header);
+            nextInit = { ...(nextInit ?? init ?? {}), headers: mergedHeaders };
+            attemptsLeft--;
+        }
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Pre-built `PayHandler` implementations.
+ *
+ * `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
+ * to a caller-supplied `signTx` callback.
+ *
+ * For browser CIP-30 wallets, write your own PayHandler: get UTxOs
+ * from `wallet.getUtxos()`, build the tx with browser CSL, sign via
+ * `wallet.signTx(cborHex, partialSign=true)` and merge the witness
+ * set. (See README "Custom PayHandler" section for an example.)
+ */
+import type { PayHandler } from './types';
+export interface BridgePayHandlerOptions {
+    /** Buyer bech32 — used for UTxO lookup and change. */
+    buyerBech32: string;
+    /**
+     * Sign the unsigned tx CBOR. Returns the SIGNED tx CBOR hex
+     * (with the vkey witness set populated).
+     *
+     * For server-side raw-key signing: use CSL's
+     * `make_vkey_witness(txHash, privKey)` and attach it to the
+     * witness set, then serialize.
+     */
+    signTx: (unsignedTxCborHex: string) => Promise<string>;
+    /** Forwarded to `buildUnsignedPaymentTx`. Default 1800 slots ≈ 30 min. */
+    ttlSlotsFromNow?: number;
+}
+/**
+ * Build a `PayHandler` that runs the whole flow through `@odatano/core`:
+ *   1. `buildUnsignedPaymentTx` (UTxO selection + tx build)
+ *   2. caller-supplied `signTx` (signs the unsigned CBOR)
+ *   3. returns `{ signedTxCborHex, nonceRef }`
+ *
+ * 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;
+//# sourceMappingURL=pay-handlers.d.ts.map

package/srv/client/pay-handlers.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Pre-built `PayHandler` implementations.
+ *
+ * `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
+ * to a caller-supplied `signTx` callback.
+ *
+ * For browser CIP-30 wallets, write your own PayHandler: get UTxOs
+ * from `wallet.getUtxos()`, build the tx with browser CSL, sign via
+ * `wallet.signTx(cborHex, partialSign=true)` and merge the witness
+ * set. (See README "Custom PayHandler" section for an example.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBridgePayHandler = createBridgePayHandler;
+const build_unsigned_tx_1 = require("../helpers/build-unsigned-tx");
+/**
+ * Build a `PayHandler` that runs the whole flow through `@odatano/core`:
+ *   1. `buildUnsignedPaymentTx` (UTxO selection + tx build)
+ *   2. caller-supplied `signTx` (signs the unsigned CBOR)
+ *   3. returns `{ signedTxCborHex, nonceRef }`
+ *
+ * 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) {
+    if (!opts.buyerBech32) {
+        throw new TypeError('createBridgePayHandler: buyerBech32 is required');
+    }
+    if (typeof opts.signTx !== 'function') {
+        throw new TypeError('createBridgePayHandler: signTx must be a function');
+    }
+    return async function bridgePayHandler(requirement) {
+        const built = await (0, build_unsigned_tx_1.buildUnsignedPaymentTx)({
+            buyerBech32: opts.buyerBech32,
+            requirements: requirement,
+            ttlSlotsFromNow: opts.ttlSlotsFromNow,
+        });
+        const signedTxCborHex = await opts.signTx(built.unsignedTxCborHex);
+        if (typeof signedTxCborHex !== 'string' || signedTxCborHex.length === 0) {
+            throw new Error('createBridgePayHandler: signTx must resolve to a non-empty hex string');
+        }
+        return { signedTxCborHex, nonceRef: built.nonceRef };
+    };
+}

package/srv/client/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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`.
+ */
+import type { PaymentRequirementEntry } from '../core/types';
+/**
+ * Signs/produces the payment for one `accepts[]` entry.
+ *
+ * Implementations: see `createBridgePayHandler` (server-to-server, uses
+ * `@odatano/core` to build + the caller-supplied `signTx` to sign), or
+ * write your own for browser CIP-30 wallets.
+ */
+export type PayHandler = (requirement: PaymentRequirementEntry) => Promise<PayHandlerResult>;
+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
+     * unspent UTxO that ALSO appears as an input of the signed tx.
+     * (Server enforces both at validate time.)
+     */
+    nonceRef: string;
+}
+/** 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. */
+    pay: PayHandler;
+    /**
+     * 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.
+     */
+    maxRetries?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/srv/client/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/srv/facilitator/adapter.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Facilitator adapter pattern.
+ *
+ * In v0.1 the verify+settle pipeline was hard-wired into the middlewares
+ * — they imported `process()` from `verify.ts` directly. That made it
+ * impossible to swap the in-process facilitator for a hosted one
+ * (the pattern Coinbase uses via `@coinbase/x402`).
+ *
+ * v0.2 introduces this `Facilitator` interface as the single
+ * extension point. Two implementations ship in-box:
+ *
+ *   - `localFacilitator()`  — runs verify+settle in-process via
+ *                             `@odatano/core`. Default everywhere.
+ *   - `httpFacilitator()`   — POSTs to a remote service (see
+ *                             `srv/facilitator/http.ts` for the wire
+ *                             format and `docs/facilitator-protocol.md`
+ *                             for the protocol reference).
+ *
+ * Consumers wire their choice into the middleware:
+ *
+ *   x402Middleware({
+ *     payTo, network, asset, priceUnits,
+ *     facilitator: httpFacilitator({ url: 'https://...', apiKey }),
+ *   });
+ *
+ * `verifyAndSettle` is the one mandatory operation — it covers the
+ * entire 1.decode → 2.validate → 3.nonce → 4.settle → 5.onAccepted
+ * pipeline. `supported()` is an optional discovery hook used by
+ * tooling / health checks (no middleware path consumes it yet).
+ */
+import type { ProcessResult } from './verify';
+import type { AssetTransferMethod, PaymentClaim, PaymentRequirementsBody } from '../core/types';
+export interface FacilitatorVerifyAndSettleArgs {
+    /** Raw `PAYMENT-SIGNATURE` header value (string, array or undefined). */
+    paymentHeader: string | string[] | undefined;
+    /** 402 body the validator checks the payment against (`accepts[0]`). */
+    requirementsBody: PaymentRequirementsBody;
+    /** Settle poll budget (ms). Default 60_000. */
+    settlePollBudgetMs?: number;
+    /** Allow txs without a validity-range upper bound. Default false. */
+    allowNoTtl?: boolean;
+    /**
+     * Best-effort audit callback. Invoked exactly once on `accepted`.
+     * **Not transmittable over HTTP** — the http facilitator wrapper
+     * invokes it locally after the remote call returns.
+     */
+    onAccepted?: (claim: PaymentClaim) => void | Promise<void>;
+}
+/** Identical to the legacy `ProcessResult` — kept as a type alias for now. */
+export type FacilitatorResult = ProcessResult;
+/** Discovery response — what this facilitator can handle. */
+export interface FacilitatorSupportedResult {
+    networks: string[];
+    assetTransferMethods: AssetTransferMethod[];
+}
+export interface Facilitator {
+    verifyAndSettle(args: FacilitatorVerifyAndSettleArgs): Promise<FacilitatorResult>;
+    /** Optional discovery hook. May be omitted by minimal facilitators. */
+    supported?(): Promise<FacilitatorSupportedResult>;
+}
+/**
+ * Default in-process facilitator. Verify+settle runs locally using the
+ * `@odatano/core` bridge.
+ *
+ * Stateless — call `localFacilitator()` once per service (or inline per
+ * middleware mount); the returned object holds no per-instance state.
+ */
+export declare function localFacilitator(): Facilitator;
+//# sourceMappingURL=adapter.d.ts.map

package/srv/facilitator/adapter.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Facilitator adapter pattern.
+ *
+ * In v0.1 the verify+settle pipeline was hard-wired into the middlewares
+ * — they imported `process()` from `verify.ts` directly. That made it
+ * impossible to swap the in-process facilitator for a hosted one
+ * (the pattern Coinbase uses via `@coinbase/x402`).
+ *
+ * v0.2 introduces this `Facilitator` interface as the single
+ * extension point. Two implementations ship in-box:
+ *
+ *   - `localFacilitator()`  — runs verify+settle in-process via
+ *                             `@odatano/core`. Default everywhere.
+ *   - `httpFacilitator()`   — POSTs to a remote service (see
+ *                             `srv/facilitator/http.ts` for the wire
+ *                             format and `docs/facilitator-protocol.md`
+ *                             for the protocol reference).
+ *
+ * Consumers wire their choice into the middleware:
+ *
+ *   x402Middleware({
+ *     payTo, network, asset, priceUnits,
+ *     facilitator: httpFacilitator({ url: 'https://...', apiKey }),
+ *   });
+ *
+ * `verifyAndSettle` is the one mandatory operation — it covers the
+ * entire 1.decode → 2.validate → 3.nonce → 4.settle → 5.onAccepted
+ * pipeline. `supported()` is an optional discovery hook used by
+ * tooling / health checks (no middleware path consumes it yet).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localFacilitator = localFacilitator;
+const verify_1 = require("./verify");
+/**
+ * Default in-process facilitator. Verify+settle runs locally using the
+ * `@odatano/core` bridge.
+ *
+ * Stateless — call `localFacilitator()` once per service (or inline per
+ * middleware mount); the returned object holds no per-instance state.
+ */
+function localFacilitator() {
+    return {
+        verifyAndSettle: (args) => (0, verify_1.process)(args),
+        async supported() {
+            return {
+                networks: ['cardano:mainnet', 'cardano:preprod', 'cardano:preview'],
+                assetTransferMethods: ['default'],
+            };
+        },
+    };
+}

package/srv/facilitator/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `httpFacilitator` — delegates verify+settle to a remote HTTP service.
+ *
+ * Wire format (see `docs/facilitator-protocol.md` for the full reference):
+ *
+ *   POST <url>/verify-settle
+ *     body: { paymentHeader, requirementsBody, settlePollBudgetMs?, allowNoTtl? }
+ *     200 → FacilitatorResult (accepted | rejected | pending)
+ *     ≥400 → throws Error (the middleware translates to 500 to the buyer)
+ *
+ *   GET <url>/supported
+ *     200 → { networks: string[], assetTransferMethods: string[] }
+ *
+ * Auth: optional `apiKey` sent as `Authorization: Bearer <key>`. For
+ * custom schemes (mTLS, OAuth, HMAC), pass a `headers()` builder.
+ *
+ * `onAccepted` cannot cross HTTP — the wrapper strips it from the wire
+ * payload and invokes it locally after the remote returns `accepted`.
+ * This preserves the local-facilitator semantics exactly.
+ */
+import type { Facilitator } from './adapter';
+type FetchFn = typeof globalThis.fetch;
+export interface HttpFacilitatorConfig {
+    /** Base URL of the remote facilitator (no trailing slash required). */
+    url: string;
+    /** Optional API key — sent as `Authorization: Bearer <apiKey>`. */
+    apiKey?: string;
+    /**
+     * Optional custom header builder, merged onto the defaults. Use for
+     * mTLS, OAuth, signed-request auth, request IDs, etc.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Override the underlying fetch (testing, custom agents). */
+    fetch?: FetchFn;
+    /**
+     * Per-request timeout in ms. Default 90_000 — needs to be longer than
+     * the facilitator's settle-poll budget plus chain-confirmation latency.
+     */
+    timeoutMs?: number;
+}
+export declare function httpFacilitator(config: HttpFacilitatorConfig): Facilitator;
+export {};
+//# sourceMappingURL=http.d.ts.map

package/srv/facilitator/http.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * `httpFacilitator` — delegates verify+settle to a remote HTTP service.
+ *
+ * Wire format (see `docs/facilitator-protocol.md` for the full reference):
+ *
+ *   POST <url>/verify-settle
+ *     body: { paymentHeader, requirementsBody, settlePollBudgetMs?, allowNoTtl? }
+ *     200 → FacilitatorResult (accepted | rejected | pending)
+ *     ≥400 → throws Error (the middleware translates to 500 to the buyer)
+ *
+ *   GET <url>/supported
+ *     200 → { networks: string[], assetTransferMethods: string[] }
+ *
+ * Auth: optional `apiKey` sent as `Authorization: Bearer <key>`. For
+ * custom schemes (mTLS, OAuth, HMAC), pass a `headers()` builder.
+ *
+ * `onAccepted` cannot cross HTTP — the wrapper strips it from the wire
+ * payload and invokes it locally after the remote returns `accepted`.
+ * This preserves the local-facilitator semantics exactly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFacilitator = httpFacilitator;
+function trimTrailingSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+function httpFacilitator(config) {
+    if (!config.url) {
+        throw new TypeError('httpFacilitator: url is required');
+    }
+    const baseFetch = config.fetch ?? globalThis.fetch;
+    if (typeof baseFetch !== 'function') {
+        throw new TypeError('httpFacilitator: no fetch implementation available (Node ≥18 or pass config.fetch)');
+    }
+    const timeoutMs = config.timeoutMs ?? 90_000;
+    const baseUrl = trimTrailingSlash(config.url);
+    async function buildHeaders(extra) {
+        const h = { 'content-type': 'application/json', ...extra };
+        if (config.apiKey)
+            h.authorization = `Bearer ${config.apiKey}`;
+        if (config.headers) {
+            const custom = await config.headers();
+            Object.assign(h, custom);
+        }
+        return h;
+    }
+    async function withTimeout(op) {
+        const ctrl = new AbortController();
+        const tid = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            return await op(ctrl.signal);
+        }
+        finally {
+            clearTimeout(tid);
+        }
+    }
+    return {
+        async verifyAndSettle(args) {
+            // Strip `onAccepted` — not transmittable. Invoke locally after the
+            // remote settles, preserving local-facilitator semantics.
+            const { onAccepted, ...wire } = args;
+            const result = await withTimeout(async (signal) => {
+                const res = await baseFetch(`${baseUrl}/verify-settle`, {
+                    method: 'POST',
+                    headers: await buildHeaders(),
+                    body: JSON.stringify(wire),
+                    signal,
+                });
+                if (!res.ok) {
+                    throw new Error(`httpFacilitator: POST /verify-settle returned ${res.status} ${res.statusText}`);
+                }
+                return (await res.json());
+            });
+            if (result.kind === 'accepted' && onAccepted) {
+                // Same best-effort semantics as the local facilitator —
+                // swallow errors so accepted payments are never lost to a
+                // failing audit callback.
+                try {
+                    await onAccepted(result.payment);
+                }
+                catch { /* deliberately ignored — payment already on chain */ }
+            }
+            return result;
+        },
+        async supported() {
+            return withTimeout(async (signal) => {
+                const res = await baseFetch(`${baseUrl}/supported`, {
+                    method: 'GET',
+                    headers: await buildHeaders(),
+                    signal,
+                });
+                if (!res.ok) {
+                    throw new Error(`httpFacilitator: GET /supported returned ${res.status} ${res.statusText}`);
+                }
+                return (await res.json());
+            });
+        },
+    };
+}

package/srv/index.d.ts

@@ -43,9 +43,16 @@ export type { AssetTransferMethod, ResourceDescriptor, PaymentRequirementEntry,
 export { process as verifyPayment, type ProcessArgs, type ProcessResult, type ProcessKind, } from './facilitator/verify';
 export { settle, type SettleArgs, type SettleResult } from './facilitator/settle';
 export { checkNonceUnspent, type NonceCheckArgs, type NonceResult } from './facilitator/nonce';
+export { localFacilitator, type Facilitator, type FacilitatorVerifyAndSettleArgs, type FacilitatorResult, type FacilitatorSupportedResult, } from './facilitator/adapter';
+export { httpFacilitator, type HttpFacilitatorConfig, } from './facilitator/http';
 export { verifyConfirmedPayment, type VerifyConfirmedArgs, type VerifyConfirmedResult, } from './helpers/verify-confirmed';
 export { buildUnsignedPaymentTx, type BuildUnsignedTxArgs, type UnsignedTxResult, } from './helpers/build-unsigned-tx';
 export { x402Middleware, type X402MiddlewareOptions } from './middleware/express';
 export { gateService, type X402CapOptions } from './middleware/cap';
+export { x402Fetch, type X402FetchOptions } from './client/fetch';
+export { x402Axios } from './client/axios';
+export { encodePaymentEnvelope, type EncodeEnvelopeArgs, } from './client/envelope';
+export { createBridgePayHandler, type BridgePayHandlerOptions, } from './client/pay-handlers';
+export type { PayHandler, PayHandlerResult, AcceptsSelector, X402ClientOptions, } from './client/types';
 export * as bridge from './bridge';
 //# sourceMappingURL=index.d.ts.map

package/srv/index.js

@@ -68,7 +68,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bridge = exports.gateService = exports.x402Middleware = exports.buildUnsignedPaymentTx = exports.verifyConfirmedPayment = exports.checkNonceUnspent = exports.settle = exports.verifyPayment = exports.Codes = exports.X402Error = exports.networksMatch = exports.isNetwork = exports.parseNetwork = exports.buildAssetString = exports.parseAsset = exports.validatePayment = exports.decode = exports.flatRequirements = exports.buildEntry = exports.buildPaymentRequirements = void 0;
+exports.bridge = exports.createBridgePayHandler = exports.encodePaymentEnvelope = exports.x402Axios = exports.x402Fetch = exports.gateService = exports.x402Middleware = exports.buildUnsignedPaymentTx = exports.verifyConfirmedPayment = exports.httpFacilitator = exports.localFacilitator = exports.checkNonceUnspent = exports.settle = exports.verifyPayment = exports.Codes = exports.X402Error = exports.networksMatch = exports.isNetwork = exports.parseNetwork = exports.buildAssetString = exports.parseAsset = exports.validatePayment = exports.decode = exports.flatRequirements = exports.buildEntry = exports.buildPaymentRequirements = void 0;
 // ─── Core builders / validators (pure) ────────────────────────────────
 var requirements_1 = require("./core/requirements");
 Object.defineProperty(exports, "buildPaymentRequirements", { enumerable: true, get: function () { return requirements_1.buildPaymentRequirements; } });
@@ -97,6 +97,11 @@ var settle_1 = require("./facilitator/settle");
 Object.defineProperty(exports, "settle", { enumerable: true, get: function () { return settle_1.settle; } });
 var nonce_1 = require("./facilitator/nonce");
 Object.defineProperty(exports, "checkNonceUnspent", { enumerable: true, get: function () { return nonce_1.checkNonceUnspent; } });
+// ─── Facilitator adapter (pluggable local vs hosted) ──────────────────
+var adapter_1 = require("./facilitator/adapter");
+Object.defineProperty(exports, "localFacilitator", { enumerable: true, get: function () { return adapter_1.localFacilitator; } });
+var http_1 = require("./facilitator/http");
+Object.defineProperty(exports, "httpFacilitator", { enumerable: true, get: function () { return http_1.httpFacilitator; } });
 // ─── Helpers ──────────────────────────────────────────────────────────
 var verify_confirmed_1 = require("./helpers/verify-confirmed");
 Object.defineProperty(exports, "verifyConfirmedPayment", { enumerable: true, get: function () { return verify_confirmed_1.verifyConfirmedPayment; } });
@@ -107,5 +112,14 @@ var express_1 = require("./middleware/express");
 Object.defineProperty(exports, "x402Middleware", { enumerable: true, get: function () { return express_1.x402Middleware; } });
 var cap_1 = require("./middleware/cap");
 Object.defineProperty(exports, "gateService", { enumerable: true, get: function () { return cap_1.gateService; } });
+// ─── Client (HTTP wrappers that auto-handle 402) ──────────────────────
+var fetch_1 = require("./client/fetch");
+Object.defineProperty(exports, "x402Fetch", { enumerable: true, get: function () { return fetch_1.x402Fetch; } });
+var axios_1 = require("./client/axios");
+Object.defineProperty(exports, "x402Axios", { enumerable: true, get: function () { return axios_1.x402Axios; } });
+var envelope_1 = require("./client/envelope");
+Object.defineProperty(exports, "encodePaymentEnvelope", { enumerable: true, get: function () { return envelope_1.encodePaymentEnvelope; } });
+var pay_handlers_1 = require("./client/pay-handlers");
+Object.defineProperty(exports, "createBridgePayHandler", { enumerable: true, get: function () { return pay_handlers_1.createBridgePayHandler; } });
 // ─── Bridge (lower-level: exposed for advanced consumers) ─────────────
 exports.bridge = __importStar(require("./bridge"));

package/srv/middleware/cap.d.ts

@@ -25,6 +25,7 @@
  * the request passes through unmodified.
  */
 import cds from '@sap/cds';
+import { type Facilitator } from '../facilitator/adapter';
 import type { AssetTransferMethod, Network, PaymentClaim } from '../core/types';
 export interface X402CapOptions {
     payTo: string;
@@ -51,6 +52,12 @@ export interface X402CapOptions {
      * builder to embed pair / entity id in the resource string.
      */
     resourceUrl?: (req: cds.Request) => string;
+    /**
+     * Facilitator implementation handling verify+settle. Default
+     * `localFacilitator()` — in-process via `@odatano/core`. Use
+     * `httpFacilitator({ url, apiKey })` to delegate to a hosted service.
+     */
+    facilitator?: Facilitator;
 }
 /**
  * Attach the x402 gate to a CAP ApplicationService. Returns the service