@bosonprotocol/x402-server 0.1.0-alpha-0

package/dist/cjs/config-CBr9qMps.d.ts

@@ -0,0 +1,419 @@
+import * as _bosonprotocol_x402_facilitator from '@bosonprotocol/x402-facilitator';
+import * as _bosonprotocol_x402_actions from '@bosonprotocol/x402-actions';
+import { ChannelRegistry } from '@bosonprotocol/x402-actions';
+import { EvmNetwork, Address } from '@bosonprotocol/x402-core/schemes/escrow';
+import { Hex } from 'viem';
+import { z } from 'zod';
+import { CoreSDK } from '@bosonprotocol/core-sdk';
+import { ExchangeReader } from './onchain/index.js';
+
+/** Funds entity returned by `coreSdk.getFunds` — narrowed to the fields the handler reshapes. */
+interface CoreSdkFundsEntity {
+    id?: string;
+    accountId: string;
+    availableAmount: string;
+    token: {
+        address: string;
+        decimals: string;
+        symbol: string;
+        name: string;
+    };
+}
+/** Seller entity returned by `coreSdk.getSellersByAddress` — only the id is consumed. */
+interface CoreSdkSellerEntity {
+    id: string;
+}
+/** Buyer entity returned by `coreSdk.getBuyers` — only the id is consumed. */
+interface CoreSdkBuyerEntity {
+    id: string;
+}
+/**
+ * The subset of `CoreSDK` the read-only handlers actually use. Both the
+ * real `CoreSDK` and a hand-rolled stub for tests satisfy this shape.
+ */
+interface CoreSdkReadAdapter {
+    getFunds(queryVars: {
+        fundsFilter: {
+            accountId: string;
+        };
+    }): Promise<CoreSdkFundsEntity[]>;
+    getSellersByAddress(address: string): Promise<CoreSdkSellerEntity[]>;
+    getBuyers(queryVars: {
+        buyersFilter: {
+            wallet: string;
+        };
+    }): Promise<CoreSdkBuyerEntity[]>;
+}
+/**
+ * Cast a full `CoreSDK` to the narrowed adapter shape. Structural-only;
+ * does not capture or wrap anything.
+ */
+declare function asCoreSdkReadAdapter(coreSdk: CoreSDK): CoreSdkReadAdapter;
+
+/**
+ * Minimal signing surface needed by `signFullOffer`. Structurally
+ * compatible with viem's `Account` (in particular `LocalAccount` from
+ * `privateKeyToAccount`), but kept narrow so consumers can plug in
+ * HSM- / KMS- / ERC-1271-backed signers without depending on viem's
+ * internal account types.
+ */
+interface SellerSigner {
+    /** Address that the EIP-712 signature must recover to (`creator` in `BosonOfferRef`). */
+    readonly address: Address;
+    /** EIP-712 typed-data signer. Accepts the same shape viem's `signTypedData` does. */
+    signTypedData: (params: {
+        domain: Record<string, unknown>;
+        types: Record<string, readonly {
+            name: string;
+            type: string;
+        }[]>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }) => Promise<Hex>;
+}
+/**
+ * Per-server configuration. Validated by `x402bServerConfigSchema` at
+ * `createX402bServer` time so bad config fails fast at boot rather than
+ * later inside a 402 response.
+ */
+interface X402bServerConfig {
+    /** CAIP-2 EVM network the server advertises (e.g. `eip155:8453`). */
+    network: EvmNetwork;
+    /** EVM chain id matching `network` — passed straight to the EIP-712 builder's salt. */
+    chainId: number;
+    /** Address of the Boson Diamond — the EIP-712 `verifyingContract` and the wire-level `escrowAddress`. */
+    escrow: Address;
+    /** Seller signer (signs the FullOffer EIP-712 typed-data). */
+    signer: SellerSigner;
+    /** Facilitator service the server forwards meta-tx envelopes to. The URL is also advertised in `nextActions[].endpoints.facilitator`. */
+    facilitator: {
+        url: string;
+    };
+    /** Per-seller channel + endpoint registry consumed by `deriveNextActions`. */
+    channelRegistry: ChannelRegistry;
+    /**
+     * Reader the convenience handlers use to verify the post-settle /
+     * post-perform-action exchange state. Required at runtime when any
+     * write handler is invoked; the `signOffer` / `buildPaymentRequirements`
+     * read-only paths don't touch it. See `./onchain/verify-exchange.ts`
+     * for the interface.
+     */
+    exchangeReader?: ExchangeReader;
+    /**
+     * URL of the Boson Protocol subgraph for this network. Used by the
+     * read-only `available-funds` handler and the address→entityId
+     * resolver shared with `withdraw-funds`. Optional at config time
+     * (legacy commit/redeem handlers don't need it); required at runtime
+     * by `handlers.withdrawFunds` / `handlers.getAvailableFunds`.
+     */
+    subgraphUrl?: string;
+    /**
+     * Pre-built read-only core-sdk client. If omitted, the server
+     * constructs one internally from `subgraphUrl` + `escrow` + `chainId`
+     * with a throwing `Web3LibAdapter` stub. Provide your own for tests
+     * or when you want to share a single core-sdk instance with the
+     * rest of your service.
+     */
+    coreSdkRead?: CoreSdkReadAdapter;
+    /**
+     * Server-side store of the fulfillment option ids advertised for
+     * each Flow A exchange (keyed by `exchangeId`). Populated from the
+     * original `PaymentRequirements` after commit verification and read
+     * at redeem time so the buyer's redeem-time fulfillment choice
+     * cannot switch to a channel the offer never advertised.
+     *
+     * Optional in the config: when omitted, `createX402bServer` wires up
+     * an in-memory `Map`. Hosts running multiple instances should plug
+     * in their own cross-process `Map`-shaped backing store.
+     */
+    exchangeFulfillmentOptionStore?: Map<string, readonly string[]>;
+    /**
+     * Pending fulfillment updates that reached REDEEMED on-chain but
+     * failed the server-side `channel.onCommit(...)` upsert. The commit
+     * handler records Flow B updates here before attempting the channel
+     * write; the redeem handler does the same for Flow A. Both delete the
+     * record on success and leave it behind with the error message on
+     * failure so the host can replay/reconcile out of band.
+     */
+    fulfillmentRecoveryStore?: Map<string, FulfillmentRecoveryEntry>;
+    /**
+     * Fulfillment channels the server accepts at redeem time when the
+     * client re-submits delivery data. Structurally a subset of
+     * `@bosonprotocol/x402-fulfillment`'s `FulfillmentChannel` — only
+     * `id`, `validate`, and `onCommit` are read here, so existing
+     * channel instances pass through directly. Required iff a host
+     * wants to accept redeem-time fulfillment updates; absent means
+     * redeem requests carrying `fulfillment` are rejected with
+     * `FULFILLMENT_CHANNELS_NOT_CONFIGURED`.
+     */
+    fulfillmentChannels?: readonly RedeemFulfillmentChannel[];
+}
+/**
+ * Minimal structural slice of `FulfillmentChannel` the redeem
+ * handler needs. Kept inline so `@bosonprotocol/x402-server` does
+ * not depend on `@bosonprotocol/x402-fulfillment` (avoids a hard
+ * coupling between the resource-server SDK and a specific channel
+ * package); any real channel implementation is type-compatible.
+ */
+interface RedeemFulfillmentChannel {
+    readonly id: string;
+    validate(data: Record<string, unknown> | null): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    onCommit(exchangeId: string, data: Record<string, unknown> | null): Promise<void>;
+}
+interface FulfillmentRecoveryEntry {
+    exchangeId: string;
+    option: string;
+    data: Record<string, unknown> | null;
+    redeemer: Address;
+    recordedAt: number;
+    error?: string;
+}
+/**
+ * zod validator for `X402bServerConfig`. Shallow on the signer +
+ * exchange reader (viem account types bring their own structural
+ * validators; the user-supplied reader impl is structurally typed);
+ * strict on the scalar fields we own here, and on the channel
+ * registry via `@bosonprotocol/x402-actions`.
+ */
+declare const x402bServerConfigSchema: z.ZodEffects<z.ZodObject<{
+    network: z.ZodString;
+    chainId: z.ZodNumber;
+    escrow: z.ZodString;
+    signer: z.ZodObject<{
+        address: z.ZodString;
+        signTypedData: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodPromise<z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        address: z.ZodString;
+        signTypedData: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodPromise<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        address: z.ZodString;
+        signTypedData: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodPromise<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>;
+    facilitator: z.ZodObject<{
+        url: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        url: string;
+    }, {
+        url: string;
+    }>;
+    channelRegistry: z.ZodObject<{
+        channels: z.ZodEffects<z.ZodArray<z.ZodEnum<[_bosonprotocol_x402_actions.ActionChannel, ..._bosonprotocol_x402_actions.ActionChannel[]]>, "many">, _bosonprotocol_x402_actions.ActionChannel[], _bosonprotocol_x402_actions.ActionChannel[]>;
+        endpoints: z.ZodOptional<z.ZodRecord<z.ZodEnum<[_bosonprotocol_x402_facilitator.ActionId, ..._bosonprotocol_x402_facilitator.ActionId[]]>, z.ZodEffects<z.ZodString, string, string>>>;
+        xmtp: z.ZodOptional<z.ZodString>;
+        mcp: z.ZodOptional<z.ZodString>;
+        escrow: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    }, {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    }>;
+    exchangeReader: z.ZodOptional<z.ZodObject<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    subgraphUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    coreSdkRead: z.ZodOptional<z.ZodObject<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>>;
+    exchangeFulfillmentOptionStore: z.ZodOptional<z.ZodType<Map<unknown, unknown>, z.ZodTypeDef, Map<unknown, unknown>>>;
+    fulfillmentRecoveryStore: z.ZodOptional<z.ZodType<Map<unknown, unknown>, z.ZodTypeDef, Map<unknown, unknown>>>;
+    fulfillmentChannels: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, "many">, z.objectOutputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[], z.objectInputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[]>>;
+}, "strict", z.ZodTypeAny, {
+    chainId: number;
+    network: string;
+    escrow: string;
+    channelRegistry: {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    };
+    facilitator: {
+        url: string;
+    };
+    signer: {
+        address: string;
+        signTypedData: (args_0: unknown, ...args: unknown[]) => Promise<string>;
+    } & {
+        [k: string]: unknown;
+    };
+    subgraphUrl?: string | undefined;
+    exchangeReader?: z.objectOutputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    coreSdkRead?: z.objectOutputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    exchangeFulfillmentOptionStore?: Map<unknown, unknown> | undefined;
+    fulfillmentRecoveryStore?: Map<unknown, unknown> | undefined;
+    fulfillmentChannels?: z.objectOutputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
+}, {
+    chainId: number;
+    network: string;
+    escrow: string;
+    channelRegistry: {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    };
+    facilitator: {
+        url: string;
+    };
+    signer: {
+        address: string;
+        signTypedData: (args_0: unknown, ...args: unknown[]) => Promise<string>;
+    } & {
+        [k: string]: unknown;
+    };
+    subgraphUrl?: string | undefined;
+    exchangeReader?: z.objectInputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    coreSdkRead?: z.objectInputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    exchangeFulfillmentOptionStore?: Map<unknown, unknown> | undefined;
+    fulfillmentRecoveryStore?: Map<unknown, unknown> | undefined;
+    fulfillmentChannels?: z.objectInputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
+}>, {
+    chainId: number;
+    network: string;
+    escrow: string;
+    channelRegistry: {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    };
+    facilitator: {
+        url: string;
+    };
+    signer: {
+        address: string;
+        signTypedData: (args_0: unknown, ...args: unknown[]) => Promise<string>;
+    } & {
+        [k: string]: unknown;
+    };
+    subgraphUrl?: string | undefined;
+    exchangeReader?: z.objectOutputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    coreSdkRead?: z.objectOutputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    exchangeFulfillmentOptionStore?: Map<unknown, unknown> | undefined;
+    fulfillmentRecoveryStore?: Map<unknown, unknown> | undefined;
+    fulfillmentChannels?: z.objectOutputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
+}, {
+    chainId: number;
+    network: string;
+    escrow: string;
+    channelRegistry: {
+        channels: _bosonprotocol_x402_actions.ActionChannel[];
+        escrow: string;
+        mcp?: string | undefined;
+        xmtp?: string | undefined;
+        endpoints?: Partial<Record<_bosonprotocol_x402_facilitator.ActionId, string>> | undefined;
+    };
+    facilitator: {
+        url: string;
+    };
+    signer: {
+        address: string;
+        signTypedData: (args_0: unknown, ...args: unknown[]) => Promise<string>;
+    } & {
+        [k: string]: unknown;
+    };
+    subgraphUrl?: string | undefined;
+    exchangeReader?: z.objectInputType<{
+        read: z.ZodFunction<z.ZodTuple<[z.ZodString], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    coreSdkRead?: z.objectInputType<{
+        getFunds: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getSellersByAddress: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+        getBuyers: z.ZodFunction<z.ZodTuple<[z.ZodUnknown], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+    exchangeFulfillmentOptionStore?: Map<unknown, unknown> | undefined;
+    fulfillmentRecoveryStore?: Map<unknown, unknown> | undefined;
+    fulfillmentChannels?: z.objectInputType<{
+        id: z.ZodString;
+        validate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+        onCommit: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
+}>;
+/**
+ * Cross-field invariant: `config.escrow` and
+ * `config.channelRegistry.escrow` must agree — the Diamond address is
+ * the same on both sides. Run this after `x402bServerConfigSchema.parse`.
+ */
+declare function assertChannelRegistryEscrowMatch(config: X402bServerConfig): void;
+
+export { type CoreSdkBuyerEntity as C, type FulfillmentRecoveryEntry as F, type RedeemFulfillmentChannel as R, type SellerSigner as S, type X402bServerConfig as X, type CoreSdkFundsEntity as a, type CoreSdkReadAdapter as b, type CoreSdkSellerEntity as c, asCoreSdkReadAdapter as d, assertChannelRegistryEscrowMatch as e, x402bServerConfigSchema as x };

package/dist/cjs/facilitator/index.d.ts

@@ -0,0 +1,26 @@
+export { C as CreateFacilitatorClientOptions, F as FacilitatorClient, a as FetchLike, c as createFacilitatorClient } from '../client-tnrpqVMW.js';
+import { FacilitatorErrorCode } from '@bosonprotocol/x402-facilitator';
+export { FacilitatorErrorCode, FacilitatorPerformActionInput, FacilitatorPerformActionResult, FacilitatorSettleInput, FacilitatorSettleResult, FacilitatorVerifyInput, FacilitatorVerifyResult } from '@bosonprotocol/x402-facilitator';
+
+/**
+ * Stable, x402-server-side codes for HTTP-transport failures.
+ * Distinct from the facilitator-side `FacilitatorErrorCode` enum so
+ * callers can branch on "the facilitator answered with X" vs "we
+ * never reached the facilitator".
+ */
+type FacilitatorHttpErrorCode = "NETWORK_ERROR" | "BAD_HTTP_STATUS" | "BAD_RESPONSE_BODY" | "TIMEOUT";
+/** Network- or transport-layer failure when calling the facilitator. */
+declare class FacilitatorHttpError extends Error {
+    readonly code: FacilitatorHttpErrorCode;
+    readonly status?: number;
+    /** Original facilitator-side error code, if the body parsed cleanly. */
+    readonly facilitatorCode?: FacilitatorErrorCode;
+    constructor(message: string, init: {
+        code: FacilitatorHttpErrorCode;
+        status?: number;
+        facilitatorCode?: FacilitatorErrorCode;
+        cause?: unknown;
+    });
+}
+
+export { FacilitatorHttpError, type FacilitatorHttpErrorCode };

package/dist/cjs/facilitator/index.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// src/facilitator/errors.ts
+var FacilitatorHttpError = class extends Error {
+  constructor(message, init) {
+    super(message, init.cause !== void 0 ? { cause: init.cause } : void 0);
+    this.name = "FacilitatorHttpError";
+    this.code = init.code;
+    if (init.status !== void 0) this.status = init.status;
+    if (init.facilitatorCode !== void 0) this.facilitatorCode = init.facilitatorCode;
+  }
+};
+
+// src/facilitator/client.ts
+function createFacilitatorClient(opts) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (fetchImpl === void 0) {
+    throw new Error(
+      "createFacilitatorClient: no `fetch` implementation available. Pass `opts.fetch` explicitly."
+    );
+  }
+  const baseUrl = opts.url.replace(/\/+$/, "");
+  const baseHeaders = { "content-type": "application/json", ...opts.headers ?? {} };
+  const post = async (path, body, validate) => {
+    let res;
+    try {
+      res = await fetchImpl(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: baseHeaders,
+        body: JSON.stringify(body)
+      });
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator network error (${path})`, {
+        code: "NETWORK_ERROR",
+        cause
+      });
+    }
+    let text;
+    try {
+      text = await res.text();
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator response body could not be read (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status,
+        cause
+      });
+    }
+    let parsed;
+    try {
+      parsed = text.length === 0 ? null : JSON.parse(text);
+    } catch (cause) {
+      throw new FacilitatorHttpError(`facilitator returned non-JSON body (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status,
+        cause
+      });
+    }
+    if (!res.ok) {
+      if (res.status === 400 && isFailureBranch(parsed) && validate(parsed)) {
+        return parsed;
+      }
+      const facilitatorCode = extractFacilitatorCode(parsed);
+      throw new FacilitatorHttpError(
+        `facilitator HTTP ${res.status} (${path}): ${reasonString(parsed) ?? text}`,
+        {
+          code: "BAD_HTTP_STATUS",
+          status: res.status,
+          ...facilitatorCode !== void 0 ? { facilitatorCode } : {}
+        }
+      );
+    }
+    if (!validate(parsed)) {
+      throw new FacilitatorHttpError(`facilitator returned unexpected body shape (${path})`, {
+        code: "BAD_RESPONSE_BODY",
+        status: res.status
+      });
+    }
+    return parsed;
+  };
+  return {
+    verify: (input) => post("/verify", input, isVerifyResult),
+    settle: (input) => post("/settle", input, isSettleResult),
+    performAction: (input) => post(
+      `/perform-action?action=${encodeURIComponent(input.action)}`,
+      input,
+      isPerformActionResult
+    )
+  };
+}
+function isObject(v) {
+  return v !== null && typeof v === "object";
+}
+function isFailureBranch(v) {
+  return isObject(v) && v.ok === false && typeof v.code === "string" && typeof v.reason === "string";
+}
+function isVerifyResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) return true;
+  return isFailureBranch(parsed);
+}
+function isSettleResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) {
+    return typeof parsed.exchangeId === "string" && typeof parsed.txHash === "string";
+  }
+  return isFailureBranch(parsed);
+}
+function isPerformActionResult(parsed) {
+  if (!isObject(parsed)) return false;
+  if (parsed.ok === true) {
+    if (typeof parsed.txHash !== "string") return false;
+    if (parsed.newExchangeState !== void 0 && typeof parsed.newExchangeState !== "string") {
+      return false;
+    }
+    if (parsed.newDisputeState !== void 0 && typeof parsed.newDisputeState !== "string") {
+      return false;
+    }
+    return true;
+  }
+  return isFailureBranch(parsed);
+}
+function extractFacilitatorCode(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const code = body.code;
+  return typeof code === "string" ? code : void 0;
+}
+function reasonString(body) {
+  if (body === null || typeof body !== "object") return void 0;
+  const reason = body.reason;
+  return typeof reason === "string" ? reason : void 0;
+}
+
+exports.FacilitatorHttpError = FacilitatorHttpError;
+exports.createFacilitatorClient = createFacilitatorClient;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/cjs/facilitator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/facilitator/errors.ts","../../../src/facilitator/client.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// Typed error class for HTTP-level facilitator failures. Distinct from\n// the `{ ok: false, code }` shape the facilitator itself returns —\n// those are domain errors and surface in the typed result. This class\n// is thrown only when the HTTP transport fails (network error,\n// non-2xx response with an unparseable body, etc.).\n\nimport type { FacilitatorErrorCode } from \"@bosonprotocol/x402-facilitator\";\n\n/**\n * Stable, x402-server-side codes for HTTP-transport failures.\n * Distinct from the facilitator-side `FacilitatorErrorCode` enum so\n * callers can branch on \"the facilitator answered with X\" vs \"we\n * never reached the facilitator\".\n */\nexport type FacilitatorHttpErrorCode =\n  | \"NETWORK_ERROR\"\n  | \"BAD_HTTP_STATUS\"\n  | \"BAD_RESPONSE_BODY\"\n  | \"TIMEOUT\";\n\n/** Network- or transport-layer failure when calling the facilitator. */\nexport class FacilitatorHttpError extends Error {\n  readonly code: FacilitatorHttpErrorCode;\n  readonly status?: number;\n  /** Original facilitator-side error code, if the body parsed cleanly. */\n  readonly facilitatorCode?: FacilitatorErrorCode;\n\n  constructor(\n    message: string,\n    init: {\n      code: FacilitatorHttpErrorCode;\n      status?: number;\n      facilitatorCode?: FacilitatorErrorCode;\n      cause?: unknown;\n    },\n  ) {\n    super(message, init.cause !== undefined ? { cause: init.cause } : undefined);\n    this.name = \"FacilitatorHttpError\";\n    this.code = init.code;\n    if (init.status !== undefined) this.status = init.status;\n    if (init.facilitatorCode !== undefined) this.facilitatorCode = init.facilitatorCode;\n  }\n}\n","// HTTP client for the Boson facilitator service. The facilitator runs\n// as a remote process implementing the three endpoints in\n// docs/boson-impl-07-facilitator.md (`/verify`, `/settle`,\n// `/perform-action?action=<action>`); this module wraps `fetch` with the typed\n// request/response shapes exported by `@bosonprotocol/x402-facilitator`.\n//\n// Domain results (`{ ok: true, ... }` or `{ ok: false, code, reason }`)\n// are returned verbatim — both shapes are answers the caller branches\n// on. The facilitator-express adapter emits domain failures over HTTP\n// 400 (so curl users still see a 4xx), but the wire body is still a\n// well-formed result; we recognise that shape on HTTP 400 responses and\n// hand it back rather than throwing. HTTP-transport failures (network\n// down, non-JSON body, schema-mismatched body) throw\n// `FacilitatorHttpError` so the composition layer can distinguish\n// \"facilitator said no\" from \"we couldn't reach the facilitator\".\n\nimport type {\n  FacilitatorErrorCode,\n  FacilitatorPerformActionInput,\n  FacilitatorPerformActionResult,\n  FacilitatorSettleInput,\n  FacilitatorSettleResult,\n  FacilitatorVerifyInput,\n  FacilitatorVerifyResult,\n} from \"@bosonprotocol/x402-facilitator\";\n\nimport { FacilitatorHttpError } from \"./errors.js\";\n\nexport type FetchLike = (\n  input: string,\n  init?: { method?: string; headers?: Record<string, string>; body?: string },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  text: () => Promise<string>;\n  json?: () => Promise<unknown>;\n}>;\n\nexport interface CreateFacilitatorClientOptions {\n  /** Base URL of the facilitator service (no trailing slash needed). */\n  url: string;\n  /** Optional `fetch` override — defaults to the global `fetch`. Useful for tests + non-`fetch` runtimes. */\n  fetch?: FetchLike;\n  /** Optional headers attached to every request — e.g. an `Authorization` for hosted facilitators. */\n  headers?: Record<string, string>;\n}\n\nexport interface FacilitatorClient {\n  verify(input: FacilitatorVerifyInput): Promise<FacilitatorVerifyResult>;\n  settle(input: FacilitatorSettleInput): Promise<FacilitatorSettleResult>;\n  performAction(input: FacilitatorPerformActionInput): Promise<FacilitatorPerformActionResult>;\n}\n\n/**\n * Construct a typed HTTP client for the facilitator. The returned\n * methods stringify the input as JSON and POST to the matching path\n * on the configured URL. Bodies matching the well-formed result shape\n * (whether HTTP 2xx success or HTTP 400 domain rejection) are returned\n * verbatim; transport failures (network, non-JSON body,\n * schema-mismatched body) raise `FacilitatorHttpError`.\n */\nexport function createFacilitatorClient(opts: CreateFacilitatorClientOptions): FacilitatorClient {\n  const fetchImpl = opts.fetch ?? (globalThis.fetch as FetchLike | undefined);\n  if (fetchImpl === undefined) {\n    throw new Error(\n      \"createFacilitatorClient: no `fetch` implementation available. Pass `opts.fetch` explicitly.\",\n    );\n  }\n  const baseUrl = opts.url.replace(/\\/+$/, \"\");\n  const baseHeaders = { \"content-type\": \"application/json\", ...(opts.headers ?? {}) };\n\n  const post = async <Req, Res>(\n    path: string,\n    body: Req,\n    validate: (parsed: unknown) => parsed is Res,\n  ): Promise<Res> => {\n    let res: Awaited<ReturnType<FetchLike>>;\n    try {\n      res = await fetchImpl(`${baseUrl}${path}`, {\n        method: \"POST\",\n        headers: baseHeaders,\n        body: JSON.stringify(body),\n      });\n    } catch (cause) {\n      throw new FacilitatorHttpError(`facilitator network error (${path})`, {\n        code: \"NETWORK_ERROR\",\n        cause,\n      });\n    }\n\n    let text: string;\n    try {\n      text = await res.text();\n    } catch (cause) {\n      throw new FacilitatorHttpError(`facilitator response body could not be read (${path})`, {\n        code: \"BAD_RESPONSE_BODY\",\n        status: res.status,\n        cause,\n      });\n    }\n\n    let parsed: unknown;\n    try {\n      parsed = text.length === 0 ? null : JSON.parse(text);\n    } catch (cause) {\n      throw new FacilitatorHttpError(`facilitator returned non-JSON body (${path})`, {\n        code: \"BAD_RESPONSE_BODY\",\n        status: res.status,\n        cause,\n      });\n    }\n\n    if (!res.ok) {\n      // The facilitator-express adapter returns domain failures as\n      // HTTP 400 with the `{ok:false, code, reason}` body. Detect that\n      // shape and surface it as the typed result — every endpoint's\n      // `Res` union includes the same `{ok:false, code, reason}`\n      // variant, so the cast through `validate` (which also accepts\n      // that shape) preserves type-safety. Any other non-2xx status is\n      // a genuine transport failure even if its body happens to look\n      // like a facilitator result.\n      if (res.status === 400 && isFailureBranch(parsed) && validate(parsed)) {\n        return parsed;\n      }\n      const facilitatorCode = extractFacilitatorCode(parsed);\n      throw new FacilitatorHttpError(\n        `facilitator HTTP ${res.status} (${path}): ${reasonString(parsed) ?? text}`,\n        {\n          code: \"BAD_HTTP_STATUS\",\n          status: res.status,\n          ...(facilitatorCode !== undefined ? { facilitatorCode } : {}),\n        },\n      );\n    }\n\n    if (!validate(parsed)) {\n      throw new FacilitatorHttpError(`facilitator returned unexpected body shape (${path})`, {\n        code: \"BAD_RESPONSE_BODY\",\n        status: res.status,\n      });\n    }\n    return parsed;\n  };\n\n  return {\n    verify: (input) =>\n      post<FacilitatorVerifyInput, FacilitatorVerifyResult>(\"/verify\", input, isVerifyResult),\n    settle: (input) =>\n      post<FacilitatorSettleInput, FacilitatorSettleResult>(\"/settle\", input, isSettleResult),\n    performAction: (input) =>\n      post<FacilitatorPerformActionInput, FacilitatorPerformActionResult>(\n        `/perform-action?action=${encodeURIComponent(input.action)}`,\n        input,\n        isPerformActionResult,\n      ),\n  };\n}\n\n// --- Response-shape type guards ----------------------------------------\n//\n// A buggy or malicious facilitator could return any 2xx JSON; without a\n// runtime check, `parsed as Res` would silently slip an unexpected shape\n// past the type system and the convenience handlers (PR 4) would\n// dereference fields that aren't there. These guards mirror the\n// discriminated unions in `@bosonprotocol/x402-facilitator`'s types and\n// fail any response that doesn't fit — surfaced as\n// `BAD_RESPONSE_BODY` so the caller treats it as a transport-layer\n// failure rather than a domain answer.\n\nfunction isObject(v: unknown): v is Record<string, unknown> {\n  return v !== null && typeof v === \"object\";\n}\n\n/**\n * Failure branch is identical across all three endpoints. Accepts\n * `unknown` so the non-2xx path can pre-check the parsed body without\n * narrowing first.\n */\nfunction isFailureBranch(v: unknown): v is { ok: false; code: string; reason: string } {\n  return (\n    isObject(v) && v.ok === false && typeof v.code === \"string\" && typeof v.reason === \"string\"\n  );\n}\n\nfunction isVerifyResult(parsed: unknown): parsed is FacilitatorVerifyResult {\n  if (!isObject(parsed)) return false;\n  if (parsed.ok === true) return true; // `{ ok: true }` carries no further fields\n  return isFailureBranch(parsed);\n}\n\nfunction isSettleResult(parsed: unknown): parsed is FacilitatorSettleResult {\n  if (!isObject(parsed)) return false;\n  if (parsed.ok === true) {\n    return typeof parsed.exchangeId === \"string\" && typeof parsed.txHash === \"string\";\n  }\n  return isFailureBranch(parsed);\n}\n\nfunction isPerformActionResult(parsed: unknown): parsed is FacilitatorPerformActionResult {\n  if (!isObject(parsed)) return false;\n  if (parsed.ok === true) {\n    if (typeof parsed.txHash !== \"string\") return false;\n    // Entity-keyed actions (e.g. `boson-withdrawFunds`) return just\n    // `{ ok: true, txHash }` — no exchange state transition. Accept\n    // that shape; only require `newExchangeState` when present.\n    if (parsed.newExchangeState !== undefined && typeof parsed.newExchangeState !== \"string\") {\n      return false;\n    }\n    if (parsed.newDisputeState !== undefined && typeof parsed.newDisputeState !== \"string\") {\n      return false;\n    }\n    return true;\n  }\n  return isFailureBranch(parsed);\n}\n\nfunction extractFacilitatorCode(body: unknown): FacilitatorErrorCode | undefined {\n  if (body === null || typeof body !== \"object\") return undefined;\n  const code = (body as { code?: unknown }).code;\n  return typeof code === \"string\" ? (code as FacilitatorErrorCode) : undefined;\n}\n\nfunction reasonString(body: unknown): string | undefined {\n  if (body === null || typeof body !== \"object\") return undefined;\n  const reason = (body as { reason?: unknown }).reason;\n  return typeof reason === \"string\" ? reason : undefined;\n}\n"]}