@bosonprotocol/x402-server 0.2.0 → 0.3.0

package/dist/cjs/facilitator/index.js

@@ -11,7 +11,22 @@ var FacilitatorHttpError = class extends Error {
   }
 };
 
+// src/logger.ts
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+
 // src/facilitator/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_RETRY = { attempts: 3, backoffMs: 200 };
+var IDEMPOTENCY_KEY_HEADER = "x-x402b-idempotency-key";
 function createFacilitatorClient(opts) {
   const fetchImpl = opts.fetch ?? globalThis.fetch;
   if (fetchImpl === void 0) {
@@ -21,19 +36,49 @@ function createFacilitatorClient(opts) {
   }
   const baseUrl = opts.url.replace(/\/+$/, "");
   const baseHeaders = { "content-type": "application/json", ...opts.headers ?? {} };
-  const post = async (path, body, validate) => {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retry = opts.retry ?? DEFAULT_RETRY;
+  if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {
+    throw new Error("createFacilitatorClient: retry.attempts must be an integer >= 1");
+  }
+  if (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0) {
+    throw new Error("createFacilitatorClient: retry.backoffMs must be a finite number >= 0");
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("createFacilitatorClient: timeoutMs must be a finite number > 0");
+  }
+  const newIdempotencyKey = opts.idempotencyKey ?? (() => globalThis.crypto.randomUUID());
+  const setTimeoutImpl = opts.setTimeout ?? setTimeout;
+  const clearTimeoutImpl = opts.clearTimeout ?? clearTimeout;
+  const logger = opts.logger ?? noopLogger;
+  const postOnce = async (path, body, validate, extraHeaders) => {
+    const controller = new AbortController();
+    const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);
+    const headers = { ...baseHeaders, ...extraHeaders };
     let res;
     try {
       res = await fetchImpl(`${baseUrl}${path}`, {
         method: "POST",
-        headers: baseHeaders,
-        body: JSON.stringify(body)
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
       });
     } catch (cause) {
-      throw new FacilitatorHttpError(`facilitator network error (${path})`, {
-        code: "NETWORK_ERROR",
-        cause
+      const aborted = controller.signal.aborted;
+      logger.warn(aborted ? "facilitator request timed out" : "facilitator network error", {
+        path,
+        timeoutMs: aborted ? timeoutMs : void 0,
+        error: cause instanceof Error ? cause.message : String(cause)
       });
+      throw new FacilitatorHttpError(
+        aborted ? `facilitator request timed out after ${timeoutMs}ms (${path})` : `facilitator network error (${path})`,
+        {
+          code: aborted ? "TIMEOUT" : "NETWORK_ERROR",
+          cause
+        }
+      );
+    } finally {
+      clearTimeoutImpl(timer);
     }
     let text;
     try {
@@ -60,6 +105,12 @@ function createFacilitatorClient(opts) {
         return parsed;
       }
       const facilitatorCode = extractFacilitatorCode(parsed);
+      logger.warn("facilitator HTTP non-2xx", {
+        path,
+        status: res.status,
+        facilitatorCode,
+        reason: reasonString(parsed)
+      });
       throw new FacilitatorHttpError(
         `facilitator HTTP ${res.status} (${path}): ${reasonString(parsed) ?? text}`,
         {
@@ -77,16 +128,76 @@ function createFacilitatorClient(opts) {
     }
     return parsed;
   };
+  const post = async (path, body, validate, extraHeaders = {}) => {
+    let lastError;
+    for (let attempt = 0; attempt < retry.attempts; attempt += 1) {
+      if (attempt > 0) {
+        await sleep(retry.backoffMs * attempt, setTimeoutImpl);
+      }
+      try {
+        return await postOnce(path, body, validate, extraHeaders);
+      } catch (e) {
+        if (e instanceof FacilitatorHttpError && isRetryable(e)) {
+          lastError = e;
+          continue;
+        }
+        throw e;
+      }
+    }
+    throw lastError;
+  };
   return {
     verify: (input) => post("/verify", input, isVerifyResult),
-    settle: (input) => post("/settle", input, isSettleResult),
+    settle: (input) => post("/settle", input, isSettleResult, {
+      [IDEMPOTENCY_KEY_HEADER]: newIdempotencyKey()
+    }),
     performAction: (input) => post(
       `/perform-action?action=${encodeURIComponent(input.action)}`,
       input,
       isPerformActionResult
-    )
+    ),
+    async healthCheck() {
+      const controller = new AbortController();
+      const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);
+      let res;
+      try {
+        res = await fetchImpl(`${baseUrl}/healthz`, {
+          method: "GET",
+          headers: { ...opts.headers ?? {} },
+          signal: controller.signal
+        });
+      } catch (cause) {
+        const aborted = controller.signal.aborted;
+        throw new FacilitatorHttpError(
+          aborted ? `facilitator request timed out after ${timeoutMs}ms (/healthz)` : "facilitator network error (/healthz)",
+          {
+            code: aborted ? "TIMEOUT" : "NETWORK_ERROR",
+            cause
+          }
+        );
+      } finally {
+        clearTimeoutImpl(timer);
+      }
+      if (!res.ok) {
+        throw new FacilitatorHttpError(`facilitator HTTP ${res.status} (/healthz)`, {
+          code: "BAD_HTTP_STATUS",
+          status: res.status
+        });
+      }
+    }
   };
 }
+function isRetryable(e) {
+  if (e.code === "NETWORK_ERROR" || e.code === "TIMEOUT") return true;
+  if (e.code === "BAD_HTTP_STATUS" && e.status !== void 0 && e.status >= 500) return true;
+  return false;
+}
+function sleep(ms, setTimeoutImpl) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeoutImpl(resolve, ms);
+  });
+}
 function isObject(v) {
   return v !== null && typeof v === "object";
 }
@@ -131,6 +242,7 @@ function reasonString(body) {
 }
 
 exports.FacilitatorHttpError = FacilitatorHttpError;
+exports.IDEMPOTENCY_KEY_HEADER = IDEMPOTENCY_KEY_HEADER;
 exports.createFacilitatorClient = createFacilitatorClient;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

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

@@ -1 +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"]}
+{"version":3,"sources":["../../../src/facilitator/errors.ts","../../../src/logger.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","// Minimal four-method logger interface threaded through the server.\n// Matches the de-facto shape every observability library in the JS\n// ecosystem (pino, winston, console, bunyan, …) so hosts adapt their\n// existing logger in one line. The default is `noopLogger`, which\n// discards every event — no overhead, no surprise output, opt-in\n// observability.\n\nexport interface Logger {\n  debug(msg: string, meta?: Record<string, unknown>): void;\n  info(msg: string, meta?: Record<string, unknown>): void;\n  warn(msg: string, meta?: Record<string, unknown>): void;\n  error(msg: string, meta?: Record<string, unknown>): void;\n}\n\n/** No-op logger — the default when the host doesn't supply one. */\nexport const noopLogger: Logger = {\n  debug: () => {},\n  info: () => {},\n  warn: () => {},\n  error: () => {},\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//\n// Transport hardening: every request enforces a per-attempt timeout via\n// `AbortController` and retries `NETWORK_ERROR` / `TIMEOUT` / 5xx with\n// linear backoff. `/settle` calls additionally carry a stable\n// `x-x402b-idempotency-key` header so a facilitator-side dedup table\n// (separate package) can recognise a retried request as the same\n// underlying intent.\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\";\nimport { noopLogger, type Logger } from \"../logger.js\";\n\nexport type FetchLike = (\n  input: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n    signal?: AbortSignal;\n  },\n) => Promise<{\n  ok: boolean;\n  status: number;\n  text: () => Promise<string>;\n  json?: () => Promise<unknown>;\n}>;\n\nexport interface FacilitatorRetryOptions {\n  /** Total attempt budget (initial try + retries). Default 3. */\n  attempts: number;\n  /** Linear-backoff multiplier in ms: sleep `backoffMs * attemptIndex` between attempts. Default 200. */\n  backoffMs: number;\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   * Per-attempt timeout in ms. Default 30_000. The `AbortController`\n   * aborts in-flight fetches when this elapses; the error surfaces as\n   * `FacilitatorHttpError` with code `TIMEOUT` and is retried under\n   * the same policy as `NETWORK_ERROR`.\n   */\n  timeoutMs?: number;\n  /**\n   * Retry policy applied to `NETWORK_ERROR`, `TIMEOUT`, and HTTP 5xx\n   * responses. Defaults to `{ attempts: 3, backoffMs: 200 }` — three\n   * attempts total at 0/200/400 ms. Set `{ attempts: 1, backoffMs: 0 }`\n   * to disable.\n   */\n  retry?: FacilitatorRetryOptions;\n  /**\n   * Factory for the `x-x402b-idempotency-key` header attached to\n   * `/settle` calls. Called once per logical request — *not* once per\n   * retry attempt — so the facilitator's dedup table can recognise\n   * retries of the same intent. Defaults to `crypto.randomUUID`.\n   */\n  idempotencyKey?: () => string;\n  /** Override for `setTimeout` — tests use this to skip real backoff sleeps. */\n  setTimeout?: typeof setTimeout;\n  /** Override for `clearTimeout` — paired with `setTimeout`. */\n  clearTimeout?: typeof clearTimeout;\n  /** Optional structured logger. Defaults to no-op. Receives `warn` on errored requests; `debug` on each call. */\n  logger?: Logger;\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   * GET `/healthz` liveness probe. Resolves on any 2xx; throws on\n   * network error or non-2xx. Designed for the server SDK's\n   * `healthCheck()` helper — hosts mount that one behind whatever\n   * `/healthz` route their framework uses.\n   */\n  healthCheck(): Promise<void>;\n}\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_RETRY: FacilitatorRetryOptions = { attempts: 3, backoffMs: 200 };\n\n/** Idempotency-key header name. Stable so a facilitator-side dedup table can recognise it. */\nexport const IDEMPOTENCY_KEY_HEADER = \"x-x402b-idempotency-key\";\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  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const retry = opts.retry ?? DEFAULT_RETRY;\n  // Defensive validation: `x402bServerConfigSchema` enforces these\n  // bounds when the client is built via `createX402bServer`, but\n  // `createFacilitatorClient` is also exported for direct use — a bad\n  // `attempts` would silently fall through the retry loop and throw\n  // `undefined` instead of a `FacilitatorHttpError`.\n  if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {\n    throw new Error(\"createFacilitatorClient: retry.attempts must be an integer >= 1\");\n  }\n  if (!Number.isFinite(retry.backoffMs) || retry.backoffMs < 0) {\n    throw new Error(\"createFacilitatorClient: retry.backoffMs must be a finite number >= 0\");\n  }\n  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {\n    throw new Error(\"createFacilitatorClient: timeoutMs must be a finite number > 0\");\n  }\n  const newIdempotencyKey = opts.idempotencyKey ?? (() => globalThis.crypto.randomUUID());\n  const setTimeoutImpl = opts.setTimeout ?? setTimeout;\n  const clearTimeoutImpl = opts.clearTimeout ?? clearTimeout;\n  const logger: Logger = opts.logger ?? noopLogger;\n\n  const postOnce = async <Req, Res>(\n    path: string,\n    body: Req,\n    validate: (parsed: unknown) => parsed is Res,\n    extraHeaders: Record<string, string>,\n  ): Promise<Res> => {\n    const controller = new AbortController();\n    const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);\n    const headers = { ...baseHeaders, ...extraHeaders };\n\n    let res: Awaited<ReturnType<FetchLike>>;\n    try {\n      res = await fetchImpl(`${baseUrl}${path}`, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify(body),\n        signal: controller.signal,\n      });\n    } catch (cause) {\n      const aborted = controller.signal.aborted;\n      logger.warn(aborted ? \"facilitator request timed out\" : \"facilitator network error\", {\n        path,\n        timeoutMs: aborted ? timeoutMs : undefined,\n        error: cause instanceof Error ? cause.message : String(cause),\n      });\n      throw new FacilitatorHttpError(\n        aborted\n          ? `facilitator request timed out after ${timeoutMs}ms (${path})`\n          : `facilitator network error (${path})`,\n        {\n          code: aborted ? \"TIMEOUT\" : \"NETWORK_ERROR\",\n          cause,\n        },\n      );\n    } finally {\n      clearTimeoutImpl(timer);\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      logger.warn(\"facilitator HTTP non-2xx\", {\n        path,\n        status: res.status,\n        facilitatorCode,\n        reason: reasonString(parsed),\n      });\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  const post = async <Req, Res>(\n    path: string,\n    body: Req,\n    validate: (parsed: unknown) => parsed is Res,\n    extraHeaders: Record<string, string> = {},\n  ): Promise<Res> => {\n    let lastError: FacilitatorHttpError | undefined;\n    for (let attempt = 0; attempt < retry.attempts; attempt += 1) {\n      if (attempt > 0) {\n        await sleep(retry.backoffMs * attempt, setTimeoutImpl);\n      }\n      try {\n        return await postOnce(path, body, validate, extraHeaders);\n      } catch (e) {\n        if (e instanceof FacilitatorHttpError && isRetryable(e)) {\n          lastError = e;\n          continue;\n        }\n        throw e;\n      }\n    }\n    // Non-null assertion: the loop above sets `lastError` on every retryable\n    // failure and only falls through after the final attempt also failed.\n    throw lastError as FacilitatorHttpError;\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        [IDEMPOTENCY_KEY_HEADER]: newIdempotencyKey(),\n      }),\n    performAction: (input) =>\n      post<FacilitatorPerformActionInput, FacilitatorPerformActionResult>(\n        `/perform-action?action=${encodeURIComponent(input.action)}`,\n        input,\n        isPerformActionResult,\n      ),\n    async healthCheck() {\n      // GET /healthz — body is ignored. Any 2xx is healthy; anything\n      // else (network error, timeout, non-2xx) raises FacilitatorHttpError\n      // so the `createHealthCheck` helper maps to \"down\". The abort\n      // timer mirrors `postOnce` so a stuck connection can't hang the\n      // host's /healthz route indefinitely. `opts.headers` (e.g.\n      // `Authorization` for hosted facilitators) must ride along here\n      // too — otherwise normal POSTs would succeed while /healthz\n      // would always 401 → \"down\".\n      const controller = new AbortController();\n      const timer = setTimeoutImpl(() => controller.abort(), timeoutMs);\n      let res: Awaited<ReturnType<FetchLike>>;\n      try {\n        res = await fetchImpl(`${baseUrl}/healthz`, {\n          method: \"GET\",\n          headers: { ...(opts.headers ?? {}) },\n          signal: controller.signal,\n        });\n      } catch (cause) {\n        const aborted = controller.signal.aborted;\n        throw new FacilitatorHttpError(\n          aborted\n            ? `facilitator request timed out after ${timeoutMs}ms (/healthz)`\n            : \"facilitator network error (/healthz)\",\n          {\n            code: aborted ? \"TIMEOUT\" : \"NETWORK_ERROR\",\n            cause,\n          },\n        );\n      } finally {\n        clearTimeoutImpl(timer);\n      }\n      if (!res.ok) {\n        throw new FacilitatorHttpError(`facilitator HTTP ${res.status} (/healthz)`, {\n          code: \"BAD_HTTP_STATUS\",\n          status: res.status,\n        });\n      }\n    },\n  };\n}\n\nfunction isRetryable(e: FacilitatorHttpError): boolean {\n  if (e.code === \"NETWORK_ERROR\" || e.code === \"TIMEOUT\") return true;\n  if (e.code === \"BAD_HTTP_STATUS\" && e.status !== undefined && e.status >= 500) return true;\n  return false;\n}\n\nfunction sleep(ms: number, setTimeoutImpl: typeof setTimeout): Promise<void> {\n  if (ms <= 0) return Promise.resolve();\n  return new Promise((resolve) => {\n    setTimeoutImpl(resolve, ms);\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"]}

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

@@ -1,267 +1,11 @@
-import { EscrowPaymentRequirements, Address } from '@bosonprotocol/x402-core/schemes/escrow';
-import { EscrowNextActions, ExchangeState, DisputeState, ChannelRegistry } from '@bosonprotocol/x402-actions';
-import { ExchangeReader } from '../onchain/index.js';
-import { F as FacilitatorClient } from '../client-tnrpqVMW.js';
-import { X as X402bServerConfig, F as FulfillmentRecoveryEntry, b as CoreSdkReadAdapter } from '../config-CBr9qMps.js';
-import { ExchangeActionId } from '@bosonprotocol/x402-core/state-machine';
-import { Hex } from 'viem';
+export { f as ADDRESS_RE, e as AvailableFundsBody, g as AvailableFundsContext, h as AvailableFundsEntry, A as AvailableFundsQuery, i as CommitHandlerContext, C as CommitHandlerInput, a as CommitOk, D as DECIMAL_UINT_RE, E as EmitNextActionsInput, j as HEX_BYTES_RE, k as HandlerErrorBody, H as HandlerResult, l as HandlerStatus, m as HandlerWarning, n as PerformActionContext, b as PerformActionInput, P as PerformActionOk, c as PlainHandlerResult, o as RedeemHandlerContext, R as RedeemHandlerInput, p as ResolveEntityError, q as ResolveEntityInput, r as ResolveEntityOk, s as ResolveEntityResult, t as WithdrawFundsContext, W as WithdrawFundsInput, d as WithdrawFundsOk, u as emitNextActions, v as handleCommit, w as handleCommitAndRedeem, x as handleComplete, y as handleDisputeEscalate, z as handleDisputeRaise, B as handleDisputeResolve, F as handleDisputeRetract, G as handleGetAvailableFunds, I as handlePerformAction, J as handleRedeem, K as handleWithdrawFunds, L as handlerErr, M as handlerOk, N as plainHandlerOk, O as resolveEntityId } from '../index-COmLTH-U.js';
+import '@bosonprotocol/x402-core/schemes/escrow';
+import '@bosonprotocol/x402-actions';
+import '../onchain/index.js';
+import '../client-B2yejopi.js';
 import '@bosonprotocol/x402-facilitator';
+import '../config-hnCiZiXF.js';
+import 'viem';
 import 'zod';
 import '@bosonprotocol/core-sdk';
-
-type HandlerStatus = 200 | 400 | 402 | 404 | 409 | 500 | 502;
-type HandlerResult<TBody> = {
-    ok: true;
-    status: 200;
-    body: TBody & {
-        nextActions: EscrowNextActions;
-    };
-} | {
-    ok: false;
-    status: Exclude<HandlerStatus, 200>;
-    body: HandlerErrorBody;
-};
-/**
- * Result shape for handlers whose success body does NOT carry a
- * `nextActions` envelope — used by entity-keyed actions
- * (`boson-withdrawFunds`) and the read-only `available-funds`
- * endpoint, neither of which advance the exchange state machine.
- */
-type PlainHandlerResult<TBody> = {
-    ok: true;
-    status: 200;
-    body: TBody;
-} | {
-    ok: false;
-    status: Exclude<HandlerStatus, 200>;
-    body: HandlerErrorBody;
-};
-interface HandlerErrorBody {
-    /** Stable identifier — caller branches on this rather than the human-readable `reason`. */
-    code: string;
-    reason: string;
-    /** Optional rich detail — validator field/expected/got, facilitator code, etc. */
-    details?: unknown;
-}
-interface HandlerWarning {
-    /** Stable identifier — caller branches on this rather than the human-readable `reason`. */
-    code: string;
-    reason: string;
-    /** Optional rich detail — tx hash, exchange id, deferred operation, etc. */
-    details?: unknown;
-}
-declare function handlerOk<TBody>(body: TBody & {
-    nextActions: EscrowNextActions;
-}): HandlerResult<TBody>;
-declare function plainHandlerOk<TBody>(body: TBody): PlainHandlerResult<TBody>;
-declare function handlerErr(status: Exclude<HandlerStatus, 200>, code: string, reason: string, details?: unknown): HandlerResult<never> & PlainHandlerResult<never>;
-
-interface CommitHandlerInput {
-    /** Raw `X-PAYMENT` header value (base64'd JSON). */
-    paymentHeader: string | undefined | null;
-    /** The 402 `PaymentRequirements` the buyer is responding to. */
-    requirements: EscrowPaymentRequirements;
-}
-interface CommitHandlerContext {
-    config: X402bServerConfig;
-    facilitator: FacilitatorClient;
-    exchangeReader: ExchangeReader;
-    fulfillmentRecoveryStore: Map<string, FulfillmentRecoveryEntry>;
-    /**
-     * Per-exchange fulfillment option policy. Flow A writes the ids
-     * advertised by the original requirements so the redeem-time choice
-     * is constrained to the offer's own channel set.
-     */
-    exchangeFulfillmentOptionStore: Map<string, readonly string[]>;
-}
-interface CommitOk {
-    exchangeId: string;
-    txHash: string;
-    /**
-     * Non-fatal post-settle conditions. Today only Flow B uses this slot —
-     * the on-chain redeem may have succeeded while the configured channel
-     * adapter's `onCommit(...)` failed (the buyer's funds and voucher are
-     * already gone; the seller's host needs to recover the delivery target
-     * out-of-band). The exchange state is the wire-format source of truth;
-     * warnings are advisory.
-     */
-    warnings?: HandlerWarning[];
-}
-/**
- * Flow A — `boson-createOfferAndCommit`. Settles via facilitator,
- * expects the resulting exchange in `COMMITTED`, returns 200 with
- * `nextActions` advertising the legal post-COMMITTED transitions.
- */
-declare function handleCommit(input: CommitHandlerInput, ctx: CommitHandlerContext): Promise<HandlerResult<CommitOk>>;
-/**
- * Flow B — `boson-createOfferCommitAndRedeem`. Same pipeline as
- * `handleCommit` but verifies the exchange reached `REDEEMED`.
- */
-declare function handleCommitAndRedeem(input: CommitHandlerInput, ctx: CommitHandlerContext): Promise<HandlerResult<CommitOk>>;
-
-/** Per-action inputs accepted by every post-commit convenience handler. */
-interface PerformActionInput {
-    exchangeId: string;
-    /** ABI-encoded `BosonMetaTx` tuple — see `encodeSignedPayload` in `@bosonprotocol/x402-facilitator`. */
-    signedPayload: Hex;
-}
-/**
- * Redeem-time variant of `PerformActionInput`. Carries the buyer's
- * `fulfillment` selection for Flow A — `data` is the delivery target
- * the redeem-time channel adapter persists. Required when the
- * original 402 advertised `fulfillment.required = true`; omitted
- * otherwise.
- */
-interface RedeemHandlerInput extends PerformActionInput {
-    fulfillment?: {
-        option: string;
-        data: Record<string, unknown> | null;
-    };
-}
-interface PerformActionContext {
-    config: X402bServerConfig;
-    facilitator: FacilitatorClient;
-    exchangeReader: ExchangeReader;
-}
-interface RedeemHandlerContext extends PerformActionContext {
-    exchangeFulfillmentOptionStore: Map<string, readonly string[]>;
-    fulfillmentRecoveryStore: Map<string, FulfillmentRecoveryEntry>;
-}
-interface PerformActionOk {
-    txHash: string;
-    warnings?: HandlerWarning[];
-}
-/**
- * Generic exchange-keyed post-commit handler — wired from each of the
- * per-action wrappers below. Entity-keyed actions (e.g. `withdrawFunds`)
- * have their own handler in `./withdraw-funds.ts`.
- */
-declare function handlePerformAction(action: ExchangeActionId, input: PerformActionInput, ctx: PerformActionContext): Promise<HandlerResult<PerformActionOk>>;
-/**
- * Redeem handler. Validates the buyer's `fulfillment` selection (if
- * present) against the offer's advertised option set and the host's
- * channel registry, runs the channel's `validate` up-front, then
- * forwards to the facilitator. The corresponding
- * `onCommit(exchangeId, data)` upsert is deferred until *after* the
- * facilitator + state verification confirm the exchange reached
- * `REDEEMED`, so a failed redeem leaves the stored delivery target
- * unchanged. The voucher NFT is transferable; whichever wallet signs
- * `boson-redeem` supplies the delivery data — it's the redeemer's
- * choice end-to-end.
- */
-declare function handleRedeem(input: RedeemHandlerInput, ctx: RedeemHandlerContext): Promise<HandlerResult<PerformActionOk>>;
-/** Per-action sugar — preserves the action id at the type level. */
-declare const handleComplete: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
-declare const handleDisputeRaise: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
-declare const handleDisputeResolve: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
-declare const handleDisputeRetract: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
-declare const handleDisputeEscalate: (input: PerformActionInput, ctx: PerformActionContext) => Promise<HandlerResult<PerformActionOk>>;
-
-interface WithdrawFundsBaseInput {
-    /** ABI-encoded `BosonMetaTx` tuple — see `encodeSignedPayload` in `@bosonprotocol/x402-evm/codec`. */
-    signedPayload: Hex;
-}
-type WithdrawFundsInput = WithdrawFundsBaseInput & ({
-    entityId: string;
-} | {
-    address: string;
-    role?: "buyer" | "seller";
-});
-interface WithdrawFundsContext {
-    config: X402bServerConfig;
-    facilitator: FacilitatorClient;
-    coreSdkRead: CoreSdkReadAdapter;
-}
-interface WithdrawFundsOk {
-    txHash: string;
-    entityId: string;
-    role?: "buyer" | "seller";
-}
-declare function handleWithdrawFunds(input: WithdrawFundsInput, ctx: WithdrawFundsContext): Promise<PlainHandlerResult<WithdrawFundsOk>>;
-
-interface AvailableFundsEntry {
-    tokenAddress: Address;
-    tokenSymbol: string;
-    tokenName: string;
-    decimals: number;
-    availableAmount: string;
-}
-interface AvailableFundsBody {
-    entityId: string;
-    /** Present when the caller looked up by `address`; omitted when looked up by `entityId`. */
-    role?: "buyer" | "seller";
-    funds: AvailableFundsEntry[];
-}
-type AvailableFundsQuery = {
-    entityId: string;
-} | {
-    address: string;
-    role?: "buyer" | "seller";
-};
-interface AvailableFundsContext {
-    coreSdkRead: CoreSdkReadAdapter;
-}
-declare function handleGetAvailableFunds(query: AvailableFundsQuery, ctx: AvailableFundsContext): Promise<PlainHandlerResult<AvailableFundsBody>>;
-
-interface ResolveEntityInput {
-    address: string;
-    role?: "buyer" | "seller";
-}
-interface ResolveEntityOk {
-    ok: true;
-    entityId: string;
-    role: "buyer" | "seller";
-}
-type ResolveEntityError = {
-    ok: false;
-    code: "NOT_FOUND";
-    reason: string;
-} | {
-    ok: false;
-    code: "AMBIGUOUS";
-    reason: string;
-    /** Seller ids matching the address (one or many). Absent when no sellers matched. */
-    sellerIds?: string[];
-    /** Buyer ids matching the address (one or many). Absent when no buyers matched. */
-    buyerIds?: string[];
-} | {
-    ok: false;
-    code: "SUBGRAPH_FAILURE";
-    reason: string;
-};
-type ResolveEntityResult = ResolveEntityOk | ResolveEntityError;
-declare function resolveEntityId(coreSdk: CoreSdkReadAdapter, input: ResolveEntityInput): Promise<ResolveEntityResult>;
-
-/** Boson account `entityId` — uint256 in decimal-string form, no leading zeros. */
-declare const DECIMAL_UINT_RE: RegExp;
-/** 20-byte EVM address, 0x-prefixed, any letter case (we normalise downstream). */
-declare const ADDRESS_RE: RegExp;
-/**
- * Hex-string check for `signedPayload`. Requires `0x` followed by an
- * *even* number of hex digits so the body decodes to whole bytes —
- * odd-length payloads like `0xabc` would surface as
- * `signedPayload decode failed: …` deep in the facilitator pipeline,
- * which is a less precise 502 than the adapter-level 400 this regex
- * catches. Stricter than core's `HEX_BYTES` (which permits odd
- * lengths) so we keep this one local.
- */
-declare const HEX_BYTES_RE: RegExp;
-
-type EmitNextActionsInput = {
-    exchangeId: string;
-} & ({
-    exchangeState: Exclude<ExchangeState, typeof ExchangeState.DISPUTED>;
-    disputeState?: never;
-} | {
-    exchangeState: typeof ExchangeState.DISPUTED;
-    disputeState: DisputeState;
-});
-/**
- * Build the `nextActions` envelope a handler attaches to its 200 body.
- * Pure wrapper; the logic beyond `deriveNextActions` is the
- * `DISPUTED → disputeState required` narrowing and the optional
- * facilitator-endpoint stamp.
- */
-declare function emitNextActions(input: EmitNextActionsInput, registry: ChannelRegistry, facilitatorUrl?: string): EscrowNextActions;
-
-export { ADDRESS_RE, type AvailableFundsBody, type AvailableFundsContext, type AvailableFundsEntry, type AvailableFundsQuery, type CommitHandlerContext, type CommitHandlerInput, type CommitOk, DECIMAL_UINT_RE, type EmitNextActionsInput, HEX_BYTES_RE, type HandlerErrorBody, type HandlerResult, type HandlerStatus, type HandlerWarning, type PerformActionContext, type PerformActionInput, type PerformActionOk, type PlainHandlerResult, type RedeemHandlerContext, type RedeemHandlerInput, type ResolveEntityError, type ResolveEntityInput, type ResolveEntityOk, type ResolveEntityResult, type WithdrawFundsContext, type WithdrawFundsInput, type WithdrawFundsOk, emitNextActions, handleCommit, handleCommitAndRedeem, handleComplete, handleDisputeEscalate, handleDisputeRaise, handleDisputeResolve, handleDisputeRetract, handleGetAvailableFunds, handlePerformAction, handleRedeem, handleWithdrawFunds, handlerErr, handlerOk, plainHandlerOk, resolveEntityId };
+import '@bosonprotocol/x402-core/state-machine';