@bosonprotocol/x402-client 0.1.1-alpha-1 → 0.2.0-alpha-0

package/dist/cjs/index.d.ts

@@ -1,7 +1,7 @@
 import { P as Policy, X as X402bClientConfig, E as ExchangeSummary, S as Signer } from './types-DLOroMb1.js';
 export { F as FulfillmentConfig, R as RedeemMode, T as TokenDomainResolver } from './types-DLOroMb1.js';
-import { EscrowPaymentRequirements, BosonCommitActionId, BosonMetaTx, Hex as Hex$1 } from '@bosonprotocol/x402-core/schemes/escrow';
-import { ActionId } from '@bosonprotocol/x402-core/state-machine';
+import { EscrowPaymentRequirements, BosonCommitActionId, BosonMetaTx, Hex as Hex$1, NextAction, EscrowNextActions } from '@bosonprotocol/x402-core/schemes/escrow';
+import { ActionId, ExchangeState, DisputeState } from '@bosonprotocol/x402-core/state-machine';
 import { Address, Hex } from 'viem';
 import '@bosonprotocol/x402-core/eip712/token-auth';
 
@@ -28,6 +28,11 @@ declare class MaxAmountExceededError extends Error {
  */
 declare function pickAction(requirements: EscrowPaymentRequirements, policy?: Policy): BosonCommitActionId;
 
+/** Decode a base64-encoded string to UTF-8. */
+declare function decodeBase64(value: string): string;
+/** Encode a UTF-8 string as base64. */
+declare function encodeBase64(value: string): string;
+
 interface ResolvedFulfillment {
     option: string;
     /**
@@ -121,6 +126,84 @@ interface SignedPostCommitAction {
     signedPayload: Hex$1;
 }
 
+/** Channels this submitter drives over HTTP. */
+type SubmitChannel = "server" | "facilitator";
+/**
+ * Why a channel attempt didn't yield a 2xx. `"no-endpoint"` is a
+ * configuration gap (channel advertised, but no URL listed under
+ * `action.endpoints`) — distinct from a real transport-level
+ * `"network"` failure so callers branching on `reason` can tell the
+ * two apart. `"invalid-response"` covers 2xx replies whose body
+ * doesn't match the channel's expected shape — the server replied
+ * but with something we can't make sense of, treated as a
+ * recoverable failure (the next channel is tried).
+ */
+type ChannelFailureReason = "5xx" | "4xx" | "network" | "timeout" | "no-endpoint" | "invalid-response";
+/** Per-channel attempt record — every walk-step appended to `attempts[]`. */
+type ChannelAttempt = {
+    channel: SubmitChannel;
+    ok: true;
+    status: number;
+} | {
+    channel: SubmitChannel;
+    ok: false;
+    reason: ChannelFailureReason;
+    status?: number;
+    message?: string;
+};
+/** Caller passes `{ option, data }` for the redeem-only fulfillment payload. */
+interface FulfillmentRequest {
+    option: string;
+    data: Record<string, unknown> | null;
+}
+interface SubmitArgs {
+    action: NextAction;
+    signed: SignedPostCommitAction;
+    exchangeId: string;
+    /** CAIP-2 (e.g. `"eip155:31337"`). Required by the facilitator route. */
+    network: string;
+    /** Escrow contract address. Required by the facilitator route. */
+    escrowAddress: Address;
+    /** Redeem-only — forwarded to the `server` channel body; ignored by `facilitator`. */
+    fulfillment?: FulfillmentRequest;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-channel timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+}
+interface SubmitResult {
+    txHash: Hex;
+    newExchangeState: ExchangeState;
+    newDisputeState?: DisputeState;
+    /** Present only when the `server` channel handled the action. */
+    nextActions?: EscrowNextActions;
+    channelUsed: SubmitChannel;
+    attempts: readonly ChannelAttempt[];
+}
+/** Thrown when no advertised channel matches one this submitter can drive. */
+declare class NoCompatibleChannelError extends Error {
+    readonly actionId: string;
+    readonly advertisedChannels: readonly string[];
+    constructor(actionId: string, advertisedChannels: readonly string[]);
+}
+/**
+ * Thrown when every attempted channel failed. Carries the per-channel
+ * attempt log so callers can branch on the final cause (e.g. 4xx from
+ * the server → buyer payload bug; 5xx from both → outage).
+ */
+declare class AllChannelsFailedError extends Error {
+    readonly attempts: readonly ChannelAttempt[];
+    constructor(actionId: string, attempts: readonly ChannelAttempt[]);
+}
+/**
+ * Submit a signed post-commit action through the first responsive HTTP
+ * channel advertised on `action.channels`. Returns the normalized result
+ * on first 2xx; throws `NoCompatibleChannelError` when no submittable
+ * channel is advertised, or `AllChannelsFailedError` when every attempt
+ * failed.
+ */
+declare function submitAction(args: SubmitArgs): Promise<SubmitResult>;
+
 type BigNumberish = string | number | bigint;
 /**
  * Resolution targets accepted by the "withdraw all" helper. Either
@@ -165,6 +248,27 @@ interface SignedWithdrawFunds {
     tokenAmounts: readonly string[];
 }
 
+/**
+ * Args for `client.submitAction`. Layered over `SignActionArgs`: the
+ * client signs the meta-tx, then resolves the matching `NextAction`
+ * entry on `priorNextActions` and walks its `channels[]` (server →
+ * facilitator) until the first 2xx. See `submit.ts` for the channel
+ * walk semantics; see `signAction` for the signing args.
+ */
+type SubmitActionArgs = SignActionArgs & {
+    /**
+     * The `nextActions` envelope returned by the prior server response.
+     * Used to read `channels[]` + `endpoints[channel]` for the entry
+     * matching `actionId`.
+     */
+    priorNextActions: EscrowNextActions;
+    /** Redeem-only fulfillment payload — forwarded to the `server` channel body. */
+    fulfillment?: FulfillmentRequest;
+    /** Override the default `globalThis.fetch`. Useful for tests / custom transports. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-channel timeout in milliseconds. Default 10000. */
+    timeoutMs?: number;
+};
 interface X402bClient {
     /**
      * Consume a parsed escrow PaymentRequirements and return the base64
@@ -188,6 +292,25 @@ interface X402bClient {
      * of MVP.
      */
     signAction(args: SignActionArgs): Promise<SignedPostCommitAction>;
+    /**
+     * Sign a buyer post-commit action via {@link X402bClient.signAction} and
+     * submit it through the first responsive HTTP channel the seller
+     * advertised on the matching `nextActions.next[]` entry. Order is taken
+     * from `priorNextActions` (the envelope from the prior server response);
+     * the walk is intersected with `["server", "facilitator"]` — `onchain` /
+     * `mcp` / `xmtp` channels are out of scope for this method.
+     *
+     * Falls back to the next channel on **5xx / network error / timeout**.
+     * Stops and throws on **4xx** (a buyer-side payload error fallback
+     * can't fix — masking it would hide bugs). Throws
+     * `NoCompatibleChannelError` when the matching entry advertises only
+     * non-HTTP channels, and `AllChannelsFailedError` when every attempt
+     * failed.
+     *
+     * Pre-existing callers that prefer to keep submission outside the SDK
+     * can still use `signAction` + their own dispatch.
+     */
+    submitAction(args: SubmitActionArgs): Promise<SubmitResult>;
     /**
      * Sign a `withdrawFunds(entityId, tokenList, tokenAmounts)` meta-tx.
      * Caller-resolved entity + tokens snapshot — see
@@ -237,4 +360,4 @@ interface Web3LibAdapterLike {
  */
 declare function signerFromEthersAdapter(adapter: Web3LibAdapterLike): Signer;
 
-export { ExchangeSummary, FulfillmentValidationError, MaxAmountExceededError, NoCompatibleActionError, Policy, type ResolveDisputeArgs, type ResolvedFulfillment, type SignActionArgs, type SignWithdrawAllAvailableFundsArgs, type SignWithdrawFundsArgs, type SignedPostCommitAction, type SignedWithdrawFunds, Signer, type SimplePostCommitArgs, UnsupportedSchemeError, UnsupportedTokenAuthError, type Web3LibAdapterLike, type WithdrawEntitySelector, type X402bClient, X402bClientConfig, createX402bClient, parseChainId, parsePaymentResponse, pickAction, resolveFulfillment, signerFromEthersAdapter };
+export { AllChannelsFailedError, type ChannelAttempt, type ChannelFailureReason, ExchangeSummary, type FulfillmentRequest, FulfillmentValidationError, MaxAmountExceededError, NoCompatibleActionError, NoCompatibleChannelError, Policy, type ResolveDisputeArgs, type ResolvedFulfillment, type SignActionArgs, type SignWithdrawAllAvailableFundsArgs, type SignWithdrawFundsArgs, type SignedPostCommitAction, type SignedWithdrawFunds, Signer, type SimplePostCommitArgs, type SubmitActionArgs, type SubmitArgs, type SubmitChannel, type SubmitResult, UnsupportedSchemeError, UnsupportedTokenAuthError, type Web3LibAdapterLike, type WithdrawEntitySelector, type X402bClient, X402bClientConfig, createX402bClient, decodeBase64, encodeBase64, parseChainId, parsePaymentResponse, pickAction, resolveFulfillment, signerFromEthersAdapter, submitAction };

package/dist/cjs/index.js

@@ -4,6 +4,7 @@ var Ajv = require('ajv');
 var coreSdk = require('@bosonprotocol/core-sdk');
 var escrow = require('@bosonprotocol/x402-core/schemes/escrow');
 var codec = require('@bosonprotocol/x402-evm/codec');
+var stateMachine = require('@bosonprotocol/x402-core/state-machine');
 var viem = require('viem');
 var tokenAuth = require('@bosonprotocol/x402-core/eip712/token-auth');
 
@@ -72,6 +73,30 @@ function pickAction(requirements, policy) {
     `no commit-time action ('${FLOW_A}' or '${FLOW_B}') with 'server' channel found in requirements.actions.next`
   );
 }
+
+// src/base64.ts
+function decodeBase64(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "base64").toString("utf8");
+  }
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new TextDecoder().decode(bytes);
+}
+function encodeBase64(value) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "utf8").toString("base64");
+  }
+  const bytes = new TextEncoder().encode(value);
+  let binary = "";
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
 function resolveFulfillment(requirements, config) {
   const required = requirements.fulfillment?.required ?? false;
   if (!required) {
@@ -244,17 +269,6 @@ function isClientStateShape(v) {
   }
   return true;
 }
-function decodeBase64(value) {
-  if (typeof Buffer !== "undefined") {
-    return Buffer.from(value, "base64").toString("utf8");
-  }
-  const binary = atob(value);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return new TextDecoder().decode(bytes);
-}
 function pickString(obj, keys) {
   for (const key of keys) {
     const v = obj[key];
@@ -297,16 +311,7 @@ function assemblePayload({
 }
 function assembleAndEncodePayload(args) {
   const payload = assemblePayload(args);
-  const json = JSON.stringify(payload);
-  if (typeof Buffer !== "undefined") {
-    return Buffer.from(json, "utf8").toString("base64");
-  }
-  const bytes = new TextEncoder().encode(json);
-  let binary = "";
-  for (const b of bytes) {
-    binary += String.fromCharCode(b);
-  }
-  return btoa(binary);
+  return encodeBase64(JSON.stringify(payload));
 }
 
 // src/utils/crypto.ts
@@ -425,6 +430,235 @@ async function callSignMetaTx(coreSdk, args, nonce) {
     }
   }
 }
+var SUBMIT_CHANNELS = ["server", "facilitator"];
+var NoCompatibleChannelError = class extends Error {
+  constructor(actionId, advertisedChannels) {
+    super(
+      `x402-client: action '${actionId}' advertises channels [${advertisedChannels.join(", ")}] but none are submittable over HTTP (server / facilitator).`
+    );
+    this.name = "NoCompatibleChannelError";
+    this.actionId = actionId;
+    this.advertisedChannels = advertisedChannels;
+  }
+};
+var AllChannelsFailedError = class extends Error {
+  constructor(actionId, attempts) {
+    super(
+      `x402-client: action '${actionId}' failed on every attempted channel \u2014 ${attempts.map((a) => formatAttempt(a)).join("; ")}`
+    );
+    this.name = "AllChannelsFailedError";
+    this.attempts = attempts;
+  }
+};
+function formatAttempt(a) {
+  if (a.ok) return `${a.channel}=ok(${a.status})`;
+  const tail = a.status !== void 0 ? `(${a.status})` : "";
+  return `${a.channel}=${a.reason}${tail}`;
+}
+async function submitAction(args) {
+  const fetcher = args.fetch ?? globalThis.fetch.bind(globalThis);
+  const timeoutMs = args.timeoutMs ?? 1e4;
+  const ordered = orderedChannels(args.action);
+  if (ordered.length === 0) {
+    throw new NoCompatibleChannelError(args.action.id, args.action.channels);
+  }
+  const attempts = [];
+  for (const channel of ordered) {
+    const endpoint = args.action.endpoints?.[channel];
+    if (endpoint === void 0) {
+      attempts.push({
+        channel,
+        ok: false,
+        reason: "no-endpoint",
+        message: `no endpoint advertised for channel '${channel}'`
+      });
+      continue;
+    }
+    const outcome = await attemptChannel({
+      channel,
+      endpoint,
+      args,
+      fetcher,
+      timeoutMs
+    });
+    attempts.push(outcome.attempt);
+    if (outcome.attempt.ok && outcome.result !== void 0) {
+      return { ...outcome.result, attempts };
+    }
+    if (!outcome.attempt.ok && outcome.attempt.reason === "4xx") {
+      throw new AllChannelsFailedError(args.action.id, attempts);
+    }
+  }
+  throw new AllChannelsFailedError(args.action.id, attempts);
+}
+function orderedChannels(action) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const c of action.channels) {
+    if (SUBMIT_CHANNELS.includes(c) && !seen.has(c)) {
+      seen.add(c);
+      out.push(c);
+    }
+  }
+  return out;
+}
+async function attemptChannel(input) {
+  const { channel, endpoint, args, fetcher, timeoutMs } = input;
+  const body = channel === "server" ? buildServerBody(args) : buildFacilitatorBody(args);
+  let res;
+  try {
+    res = await fetchWithTimeout(fetcher, endpoint, body, timeoutMs);
+  } catch (e) {
+    const reason = isTimeout(e) ? "timeout" : "network";
+    return {
+      attempt: {
+        channel,
+        ok: false,
+        reason,
+        message: e instanceof Error ? e.message : String(e)
+      }
+    };
+  }
+  const parsed = await res.json().catch(() => null);
+  if (res.status >= 500) {
+    return {
+      attempt: { channel, ok: false, reason: "5xx", status: res.status }
+    };
+  }
+  if (!res.ok) {
+    return {
+      attempt: { channel, ok: false, reason: "4xx", status: res.status }
+    };
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return {
+      attempt: {
+        channel,
+        ok: false,
+        reason: "invalid-response",
+        status: res.status,
+        message: "response body is not a JSON object"
+      }
+    };
+  }
+  try {
+    const result = channel === "server" ? parseServerResult(parsed) : parseFacilitatorResult(parsed);
+    return {
+      attempt: { channel, ok: true, status: res.status },
+      result: { ...result, channelUsed: channel }
+    };
+  } catch (e) {
+    return {
+      attempt: {
+        channel,
+        ok: false,
+        reason: "invalid-response",
+        status: res.status,
+        message: e instanceof Error ? e.message : String(e)
+      }
+    };
+  }
+}
+function buildServerBody(args) {
+  const body = {
+    exchangeId: args.exchangeId,
+    signedPayload: args.signed.signedPayload
+  };
+  if (args.action.id === "boson-redeem" && args.fulfillment !== void 0) {
+    body.fulfillment = args.fulfillment;
+  }
+  return body;
+}
+function buildFacilitatorBody(args) {
+  return {
+    action: args.action.id,
+    exchangeId: args.exchangeId,
+    network: args.network,
+    escrowAddress: args.escrowAddress,
+    signedPayload: args.signed.signedPayload
+  };
+}
+async function fetchWithTimeout(fetcher, endpoint, body, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new TimeoutError(timeoutMs)), timeoutMs);
+  try {
+    return await fetcher(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var TimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`x402-client/submit: channel attempt timed out after ${timeoutMs}ms`);
+    this.isTimeout = true;
+    this.name = "TimeoutError";
+  }
+};
+function isTimeout(e) {
+  if (e instanceof TimeoutError) return true;
+  if (typeof e !== "object" || e === null) return false;
+  const obj = e;
+  if (obj.isTimeout === true) return true;
+  if (obj.name === "AbortError" || obj.name === "TimeoutError") return true;
+  if (typeof obj.cause === "object" && obj.cause !== null) {
+    const cause = obj.cause;
+    if (cause.isTimeout === true) return true;
+    if (cause.name === "TimeoutError") return true;
+  }
+  return false;
+}
+function parseServerResult(body) {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("server response body is not an object");
+  }
+  const raw = body;
+  const txHash = raw.txHash;
+  const exchangeState = raw.nextActions?.exchangeState;
+  if (!isHexHash(txHash) || !isExchangeState(exchangeState)) {
+    throw new Error("server response missing txHash or nextActions.exchangeState");
+  }
+  const out = {
+    txHash,
+    newExchangeState: exchangeState,
+    nextActions: raw.nextActions
+  };
+  if (isDisputeState(raw.nextActions?.disputeState)) {
+    out.newDisputeState = raw.nextActions.disputeState;
+  }
+  return out;
+}
+function parseFacilitatorResult(body) {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("facilitator response body is not an object");
+  }
+  const raw = body;
+  if (raw.ok !== true || !isHexHash(raw.txHash) || !isExchangeState(raw.newExchangeState)) {
+    throw new Error("facilitator response missing ok/txHash/newExchangeState");
+  }
+  const out = {
+    txHash: raw.txHash,
+    newExchangeState: raw.newExchangeState
+  };
+  if (isDisputeState(raw.newDisputeState)) {
+    out.newDisputeState = raw.newDisputeState;
+  }
+  return out;
+}
+var TX_HASH_RE = /^0x[0-9a-fA-F]{64}$/;
+function isHexHash(v) {
+  return typeof v === "string" && TX_HASH_RE.test(v);
+}
+function isExchangeState(v) {
+  return typeof v === "string" && Object.values(stateMachine.ExchangeState).includes(v);
+}
+function isDisputeState(v) {
+  return typeof v === "string" && Object.values(stateMachine.DisputeState).includes(v);
+}
 function normalizeEntityId(value) {
   if (typeof value === "bigint") {
     if (value < 0n) throw new Error(`entityId must be non-negative, got ${value.toString()}`);
@@ -848,6 +1082,26 @@ function createX402bClient(config) {
     signAction(args) {
       return signPostCommitAction(args, { buildCoreSdk, getBuyerAddress });
     },
+    async submitAction(args) {
+      const signed = await signPostCommitAction(args, { buildCoreSdk, getBuyerAddress });
+      const action = args.priorNextActions.next.find((entry) => entry.id === args.actionId);
+      if (action === void 0) {
+        throw new Error(
+          `x402-client/submitAction: actionId '${args.actionId}' is not present in priorNextActions.next[]`
+        );
+      }
+      const submitArgs = {
+        action,
+        signed,
+        exchangeId: String(args.exchangeId),
+        network: args.network,
+        escrowAddress: args.escrowAddress,
+        fulfillment: args.fulfillment,
+        fetch: args.fetch,
+        timeoutMs: args.timeoutMs
+      };
+      return submitAction(submitArgs);
+    },
     signWithdrawFunds(args) {
       return signWithdrawFunds(args, { buildCoreSdk, getSignerAddress: getBuyerAddress });
     },
@@ -908,16 +1162,21 @@ function deriveEip712DomainType(domain) {
   return fields;
 }
 
+exports.AllChannelsFailedError = AllChannelsFailedError;
 exports.FulfillmentValidationError = FulfillmentValidationError;
 exports.MaxAmountExceededError = MaxAmountExceededError;
 exports.NoCompatibleActionError = NoCompatibleActionError;
+exports.NoCompatibleChannelError = NoCompatibleChannelError;
 exports.UnsupportedSchemeError = UnsupportedSchemeError;
 exports.UnsupportedTokenAuthError = UnsupportedTokenAuthError;
 exports.createX402bClient = createX402bClient;
+exports.decodeBase64 = decodeBase64;
+exports.encodeBase64 = encodeBase64;
 exports.parseChainId = parseChainId;
 exports.parsePaymentResponse = parsePaymentResponse;
 exports.pickAction = pickAction;
 exports.resolveFulfillment = resolveFulfillment;
 exports.signerFromEthersAdapter = signerFromEthersAdapter;
+exports.submitAction = submitAction;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map