@bosonprotocol/x402-server 0.2.0 → 0.3.0-alpha-0

package/dist/esm/chunk-OMJEQEOF.js

@@ -0,0 +1,223 @@
+import { noopLogger, FacilitatorHttpError } from './chunk-RAESVNQG.js';
+
+// 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) {
+    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 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,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (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 {
+      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);
+      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}`,
+        {
+          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;
+  };
+  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, {
+      [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";
+}
+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;
+}
+
+export { IDEMPOTENCY_KEY_HEADER, createFacilitatorClient };
+//# sourceMappingURL=chunk-OMJEQEOF.js.map
+//# sourceMappingURL=chunk-OMJEQEOF.js.map

package/dist/esm/chunk-OMJEQEOF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/facilitator/client.ts"],"names":[],"mappings":"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","file":"chunk-OMJEQEOF.js","sourcesContent":["// 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/esm/{chunk-PU5Y7FZG.js → chunk-RAESVNQG.js}

@@ -9,6 +9,18 @@ var FacilitatorHttpError = class extends Error {
   }
 };
 
-export { FacilitatorHttpError };
-//# sourceMappingURL=chunk-PU5Y7FZG.js.map
-//# sourceMappingURL=chunk-PU5Y7FZG.js.map
+// src/logger.ts
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+
+export { FacilitatorHttpError, noopLogger };
+//# sourceMappingURL=chunk-RAESVNQG.js.map
+//# sourceMappingURL=chunk-RAESVNQG.js.map

package/dist/esm/chunk-RAESVNQG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/facilitator/errors.ts","../../src/logger.ts"],"names":[],"mappings":";AAqBO,IAAM,oBAAA,GAAN,cAAmC,KAAA,CAAM;AAAA,EAM9C,WAAA,CACE,SACA,IAAA,EAMA;AACA,IAAA,KAAA,CAAM,OAAA,EAAS,KAAK,KAAA,KAAU,MAAA,GAAY,EAAE,KAAA,EAAO,IAAA,CAAK,KAAA,EAAM,GAAI,MAAS,CAAA;AAC3E,IAAA,IAAA,CAAK,IAAA,GAAO,sBAAA;AACZ,IAAA,IAAA,CAAK,OAAO,IAAA,CAAK,IAAA;AACjB,IAAA,IAAI,IAAA,CAAK,MAAA,KAAW,MAAA,EAAW,IAAA,CAAK,SAAS,IAAA,CAAK,MAAA;AAClD,IAAA,IAAI,IAAA,CAAK,eAAA,KAAoB,MAAA,EAAW,IAAA,CAAK,kBAAkB,IAAA,CAAK,eAAA;AAAA,EACtE;AACF;;;AC3BO,IAAM,UAAA,GAAqB;AAAA,EAChC,OAAO,MAAM;AAAA,EAAC,CAAA;AAAA,EACd,MAAM,MAAM;AAAA,EAAC,CAAA;AAAA,EACb,MAAM,MAAM;AAAA,EAAC,CAAA;AAAA,EACb,OAAO,MAAM;AAAA,EAAC;AAChB","file":"chunk-RAESVNQG.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"]}

package/dist/esm/{chunk-Y5HFLCAT.js → chunk-SHYOIKYU.js}

@@ -1,4 +1,4 @@
-import { FacilitatorHttpError } from './chunk-PU5Y7FZG.js';
+import { noopLogger, FacilitatorHttpError } from './chunk-RAESVNQG.js';
 import { verifyExchange } from './chunk-4NQ3VKC3.js';
 import { decodeXPaymentHeader, validatePaymentPayload } from './chunk-CGVXQX5V.js';
 import { ExchangeState, deriveNextActions } from '@bosonprotocol/x402-actions';
@@ -58,6 +58,21 @@ function emitNextActions(input, registry, facilitatorUrl) {
   };
 }
 
+// src/handlers/fulfillment-result.ts
+function serializeFulfillmentResult(result) {
+  if (result.kind === "inline") {
+    return {
+      kind: "inline",
+      body: Buffer.from(result.body).toString("base64"),
+      contentType: result.contentType
+    };
+  }
+  return {
+    kind: "async",
+    ...result.pointer !== void 0 ? { pointer: result.pointer } : {}
+  };
+}
+
 // src/handlers/types.ts
 function handlerOk(body) {
   return { ok: true, status: 200, body };
@@ -85,6 +100,7 @@ async function handleCommitAndRedeem(input, ctx) {
   });
 }
 async function handleCommitImpl(input, ctx, expected) {
+  const logger = ctx.logger ?? noopLogger;
   const decoded = decodeXPaymentHeader(input.paymentHeader);
   if (!decoded.ok) {
     const status = decoded.code === "MISSING_HEADER" ? 402 : 400;
@@ -173,28 +189,38 @@ async function handleCommitImpl(input, ctx, expected) {
     );
   }
   if (expected.expectedState === ExchangeState.COMMITTED) {
-    ctx.exchangeFulfillmentOptionStore.set(
+    await ctx.exchangeFulfillmentOptionStore.set(
       settleResult.exchangeId,
       input.requirements.fulfillment?.options.map((option) => option.id) ?? []
     );
   }
   const warnings = [];
+  let delivery;
   if (expected.expectedState === ExchangeState.REDEEMED && decoded.payload.fulfillment !== void 0 && decoded.payload.fulfillment.data !== void 0) {
     const pending = {
       exchangeId: settleResult.exchangeId,
       option: decoded.payload.fulfillment.option,
       data: decoded.payload.fulfillment.data,
       redeemer: decoded.payload.payload.buyer,
-      recordedAt: Date.now()
+      recordedAt: Date.now(),
+      phase: "commit"
     };
-    ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, pending);
+    logger.debug("x402-server: fulfillment recovery entry recorded (Flow B)", {
+      exchangeId: settleResult.exchangeId,
+      option: decoded.payload.fulfillment.option
+    });
     const channel = channelById.get(decoded.payload.fulfillment.option);
     if (channel === void 0) {
       const reason = "no channel adapter is registered";
-      ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+      await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
         ...pending,
         error: reason
       });
+      logger.error("x402-server: Flow B channel adapter missing post-settle", {
+        exchangeId: settleResult.exchangeId,
+        option: decoded.payload.fulfillment.option
+      });
       warnings.push({
         code: "FULFILLMENT_COMMIT_DEFERRED",
         reason: "atomic redeem succeeded on-chain, but no channel adapter is registered",
@@ -207,13 +233,54 @@ async function handleCommitImpl(input, ctx, expected) {
     } else {
       try {
         await channel.onCommit(settleResult.exchangeId, decoded.payload.fulfillment.data);
-        ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+        if (channel.onFulfill !== void 0) {
+          const deliveryPending = {
+            ...pending,
+            phase: "delivery",
+            recordedAt: Date.now()
+          };
+          await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, deliveryPending);
+          try {
+            delivery = serializeFulfillmentResult(await channel.onFulfill(settleResult.exchangeId));
+            await ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+            logger.debug("x402-server: Flow B channel onCommit succeeded", {
+              exchangeId: settleResult.exchangeId,
+              option: decoded.payload.fulfillment.option
+            });
+          } catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+              ...deliveryPending,
+              error: reason
+            });
+            warnings.push({
+              code: "FULFILLMENT_DELIVERY_DEFERRED",
+              reason: "atomic redeem succeeded on-chain, but the channel's delivery dispatch failed",
+              details: {
+                exchangeId: settleResult.exchangeId,
+                option: decoded.payload.fulfillment.option,
+                error: reason
+              }
+            });
+          }
+        } else {
+          await ctx.fulfillmentRecoveryStore.delete(settleResult.exchangeId);
+          logger.debug("x402-server: Flow B channel onCommit succeeded", {
+            exchangeId: settleResult.exchangeId,
+            option: decoded.payload.fulfillment.option
+          });
+        }
       } catch (e) {
         const reason = e instanceof Error ? e.message : String(e);
-        ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
+        await ctx.fulfillmentRecoveryStore.set(settleResult.exchangeId, {
           ...pending,
           error: reason
         });
+        logger.warn("x402-server: Flow B channel onCommit failed; recovery entry retained", {
+          exchangeId: settleResult.exchangeId,
+          option: decoded.payload.fulfillment.option,
+          error: reason
+        });
         warnings.push({
           code: "FULFILLMENT_COMMIT_DEFERRED",
           reason: "atomic redeem succeeded on-chain, but the channel adapter rejected the data",
@@ -238,7 +305,8 @@ async function handleCommitImpl(input, ctx, expected) {
     exchangeId: settleResult.exchangeId,
     txHash: settleResult.txHash,
     nextActions,
-    ...warnings.length > 0 ? { warnings } : {}
+    ...warnings.length > 0 ? { warnings } : {},
+    ...delivery !== void 0 ? { fulfillment: delivery } : {}
   });
 }
 function buildExpectedFromRequirements(requirements, state) {
@@ -338,7 +406,7 @@ async function handleRedeem(input, ctx) {
   }
   let resolvedChannel;
   if (input.fulfillment !== void 0) {
-    const advertisedOptions = ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
+    const advertisedOptions = await ctx.exchangeFulfillmentOptionStore.get(input.exchangeId);
     if (advertisedOptions !== void 0 && !advertisedOptions.includes(input.fulfillment.option)) {
       return handlerErr(
         400,
@@ -381,23 +449,40 @@ async function handleRedeem(input, ctx) {
   }
   const result = await handlePerformAction("boson-redeem", input, ctx);
   if (!result.ok) return result;
-  let warning;
+  const warnings = [];
+  let delivery;
   if (resolvedChannel !== void 0 && input.fulfillment !== void 0) {
     const pending = {
       exchangeId: input.exchangeId,
       option: input.fulfillment.option,
       data: input.fulfillment.data,
       redeemer,
-      recordedAt: Date.now()
+      recordedAt: Date.now(),
+      phase: "commit"
     };
-    ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    const logger = ctx.logger ?? noopLogger;
+    await ctx.fulfillmentRecoveryStore.set(input.exchangeId, pending);
+    logger.debug("x402-server: fulfillment recovery entry recorded (Flow A redeem)", {
+      exchangeId: input.exchangeId,
+      option: input.fulfillment.option
+    });
+    let onCommitOk = false;
     try {
       await resolvedChannel.onCommit(input.exchangeId, input.fulfillment.data);
-      ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+      onCommitOk = true;
+      logger.debug("x402-server: Flow A channel onCommit succeeded", {
+        exchangeId: input.exchangeId,
+        option: input.fulfillment.option
+      });
     } catch (e) {
       const reason = errorMessage(e);
-      ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
-      warning = {
+      await ctx.fulfillmentRecoveryStore.set(input.exchangeId, { ...pending, error: reason });
+      logger.warn("x402-server: Flow A channel onCommit failed; recovery entry retained", {
+        exchangeId: input.exchangeId,
+        option: input.fulfillment.option,
+        error: reason
+      });
+      warnings.push({
         code: "FULFILLMENT_UPDATE_DEFERRED",
         reason: "redeem succeeded on-chain, but the server could not persist the fulfillment update",
         details: {
@@ -405,16 +490,48 @@ async function handleRedeem(input, ctx) {
           option: input.fulfillment.option,
           error: reason
         }
-      };
+      });
+    }
+    if (onCommitOk) {
+      if (resolvedChannel.onFulfill !== void 0) {
+        const deliveryPending = {
+          ...pending,
+          phase: "delivery",
+          recordedAt: Date.now()
+        };
+        await ctx.fulfillmentRecoveryStore.set(input.exchangeId, deliveryPending);
+        try {
+          delivery = serializeFulfillmentResult(await resolvedChannel.onFulfill(input.exchangeId));
+          await ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+        } catch (e) {
+          const reason = errorMessage(e);
+          await ctx.fulfillmentRecoveryStore.set(input.exchangeId, {
+            ...deliveryPending,
+            error: reason
+          });
+          warnings.push({
+            code: "FULFILLMENT_DELIVERY_DEFERRED",
+            reason: "redeem succeeded on-chain, but the fulfillment channel's delivery dispatch failed",
+            details: {
+              exchangeId: input.exchangeId,
+              option: input.fulfillment.option,
+              error: reason
+            }
+          });
+        }
+      } else {
+        await ctx.fulfillmentRecoveryStore.delete(input.exchangeId);
+      }
     }
   }
-  ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
-  if (warning !== void 0) {
+  await ctx.exchangeFulfillmentOptionStore.delete(input.exchangeId);
+  if (warnings.length > 0 || delivery !== void 0) {
     return {
       ...result,
       body: {
         ...result.body,
-        warnings: [...result.body.warnings ?? [], warning]
+        ...delivery !== void 0 ? { fulfillment: delivery } : {},
+        ...warnings.length > 0 ? { warnings: [...result.body.warnings ?? [], ...warnings] } : {}
       }
     };
   }
@@ -653,5 +770,5 @@ function omitErrorMetadata(resolved) {
 }
 
 export { ADDRESS_RE, DECIMAL_UINT_RE, HEX_BYTES_RE, emitNextActions, handleCommit, handleCommitAndRedeem, handleComplete, handleDisputeEscalate, handleDisputeRaise, handleDisputeResolve, handleDisputeRetract, handleGetAvailableFunds, handlePerformAction, handleRedeem, handleWithdrawFunds, handlerErr, handlerOk, plainHandlerOk, resolveEntityId, stampFacilitatorEndpoints };
-//# sourceMappingURL=chunk-Y5HFLCAT.js.map
-//# sourceMappingURL=chunk-Y5HFLCAT.js.map
+//# sourceMappingURL=chunk-SHYOIKYU.js.map
+//# sourceMappingURL=chunk-SHYOIKYU.js.map