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

package/dist/esm/index.js

@@ -1,10 +1,11 @@
 import { buildPaymentRequirements, signFullOffer } from './chunk-GBPU373M.js';
 export { buildPaymentRequirements, signFullOffer } from './chunk-GBPU373M.js';
-import { createFacilitatorClient } from './chunk-EAKQ4EFZ.js';
-export { createFacilitatorClient } from './chunk-EAKQ4EFZ.js';
-import { handleGetAvailableFunds, handleWithdrawFunds, handleDisputeEscalate, handleDisputeRetract, handleDisputeResolve, handleDisputeRaise, handleComplete, handleRedeem, handleCommitAndRedeem, handleCommit, stampFacilitatorEndpoints } from './chunk-Y5HFLCAT.js';
-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 } from './chunk-Y5HFLCAT.js';
-export { FacilitatorHttpError } from './chunk-PU5Y7FZG.js';
+import { createFacilitatorClient } from './chunk-OMJEQEOF.js';
+export { IDEMPOTENCY_KEY_HEADER, createFacilitatorClient } from './chunk-OMJEQEOF.js';
+import { handleGetAvailableFunds, handleWithdrawFunds, handleDisputeEscalate, handleDisputeRetract, handleDisputeResolve, handleDisputeRaise, handleComplete, handleRedeem, handleCommitAndRedeem, handleCommit, stampFacilitatorEndpoints } from './chunk-SHYOIKYU.js';
+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 } from './chunk-SHYOIKYU.js';
+import { noopLogger } from './chunk-RAESVNQG.js';
+export { FacilitatorHttpError, noopLogger } from './chunk-RAESVNQG.js';
 import './chunk-WU7QJ7YP.js';
 export { verifyExchange, verifyExchangeSnapshot } from './chunk-4NQ3VKC3.js';
 import './chunk-DJMCSCBE.js';
@@ -36,6 +37,31 @@ function createReadOnlyWeb3LibStub() {
     getCurrentTimeMs: () => Promise.reject(unreachable("getCurrentTimeMs"))
   };
 }
+
+// src/store.ts
+function mapAsStore(m) {
+  return {
+    async get(key) {
+      return m.get(key);
+    },
+    async set(key, value) {
+      m.set(key, value);
+    },
+    async delete(key) {
+      m.delete(key);
+    },
+    async *entries() {
+      for (const e of m.entries()) yield e;
+    }
+  };
+}
+function isStore(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.get === "function" && typeof v.set === "function" && typeof v.delete === "function" && typeof v.entries === "function";
+}
+
+// src/config.ts
 var httpUrlSchema = z.string().url().refine((url) => url.startsWith("http://") || url.startsWith("https://"), {
   message: "must be an http(s) URL"
 });
@@ -58,22 +84,40 @@ var coreSdkReadShallowSchema = z.object({
 var fulfillmentChannelShallowSchema = z.object({
   id: z.string().min(1),
   validate: z.function(),
-  onCommit: z.function()
+  onCommit: z.function(),
+  // Optional delivery dispatch — present on real channels, omitted by
+  // hosts that deliver out-of-band.
+  onFulfill: z.function().optional()
 }).passthrough();
+var asyncStoreSchema = () => z.custom(isStore, {
+  message: "must implement the async Store<V> interface (get/set/delete/entries)"
+});
 var x402bServerConfigSchema = z.object({
   network: evmNetworkSchema,
   chainId: z.number().int().positive(),
   escrow: addressSchema,
   signer: sellerSignerSchema,
   facilitator: z.object({
-    url: httpUrlSchema
+    url: httpUrlSchema,
+    timeoutMs: z.number().int().positive().optional(),
+    retry: z.object({
+      attempts: z.number().int().positive(),
+      backoffMs: z.number().int().nonnegative()
+    }).strict().optional(),
+    idempotencyKey: z.function().args().returns(z.string()).optional()
   }).strict(),
   channelRegistry: channelRegistryZodSchema,
   exchangeReader: exchangeReaderShallowSchema.optional(),
   subgraphUrl: httpUrlSchema.optional(),
   coreSdkRead: coreSdkReadShallowSchema.optional(),
-  exchangeFulfillmentOptionStore: z.instanceof(Map).optional(),
-  fulfillmentRecoveryStore: z.instanceof(Map).optional(),
+  exchangeFulfillmentOptionStore: asyncStoreSchema().optional(),
+  fulfillmentRecoveryStore: asyncStoreSchema().optional(),
+  logger: z.object({
+    debug: z.function(),
+    info: z.function(),
+    warn: z.function(),
+    error: z.function()
+  }).passthrough().optional(),
   fulfillmentChannels: z.array(fulfillmentChannelShallowSchema).superRefine((channels, ctx) => {
     const seen = /* @__PURE__ */ new Set();
     const duplicates = /* @__PURE__ */ new Set();
@@ -87,7 +131,8 @@ var x402bServerConfigSchema = z.object({
         message: `fulfillmentChannels has duplicate id(s): ${[...duplicates].join(", ")}`
       });
     }
-  }).optional()
+  }).optional(),
+  mode: z.enum(["development", "production"]).optional()
 }).strict().superRefine((cfg, ctx) => {
   const networkChainId = Number(cfg.network.split(":")[1]);
   if (networkChainId !== cfg.chainId) {
@@ -97,6 +142,36 @@ var x402bServerConfigSchema = z.object({
       message: `chainId (${cfg.chainId}) must match network (${cfg.network})`
     });
   }
+  if (cfg.mode === "production") {
+    if (cfg.exchangeReader === void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["exchangeReader"],
+        message: "required when mode is 'production' (post-settle state verification)"
+      });
+    }
+    if (cfg.coreSdkRead === void 0 && cfg.subgraphUrl === void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["subgraphUrl"],
+        message: "one of `coreSdkRead` or `subgraphUrl` is required when mode is 'production' (read client for withdraw / available-funds)"
+      });
+    }
+    if (cfg.exchangeFulfillmentOptionStore === void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["exchangeFulfillmentOptionStore"],
+        message: "required when mode is 'production'; without a persistent store the Flow A redeem-time option gate silently relaxes after a restart"
+      });
+    }
+    if (cfg.fulfillmentRecoveryStore === void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["fulfillmentRecoveryStore"],
+        message: "required when mode is 'production'; without a persistent store, post-settle channel-onCommit failures lose their replay handle"
+      });
+    }
+  }
 });
 function assertChannelRegistryEscrowMatch(config) {
   if (config.escrow.toLowerCase() !== config.channelRegistry.escrow.toLowerCase()) {
@@ -111,6 +186,52 @@ function asCoreSdkReadAdapter(coreSdk) {
   return coreSdk;
 }
 
+// src/concurrency.ts
+function createKeyedMutex() {
+  const chains = /* @__PURE__ */ new Map();
+  return {
+    runExclusive(key, fn) {
+      const prev = chains.get(key) ?? Promise.resolve();
+      const run = prev.then(fn, fn);
+      const tracked = run.catch(() => void 0);
+      chains.set(key, tracked);
+      tracked.then(() => {
+        if (chains.get(key) === tracked) chains.delete(key);
+      });
+      return run;
+    }
+  };
+}
+
+// src/health.ts
+function createHealthCheck(deps) {
+  return async () => {
+    const facilitator = await probe(() => deps.facilitator.healthCheck()) ? "ok" : "down";
+    let readClient;
+    let readClientFailed = false;
+    if (typeof deps.coreSdkRead === "function") {
+      try {
+        readClient = deps.coreSdkRead();
+      } catch {
+        readClientFailed = true;
+      }
+    } else {
+      readClient = deps.coreSdkRead;
+    }
+    const subgraph = readClientFailed ? "down" : readClient === void 0 ? "n/a" : await probe(() => readClient.getSellersByAddress(ZERO_ADDRESS_PROBE)) ? "ok" : "down";
+    return { facilitator, subgraph };
+  };
+}
+async function probe(fn) {
+  try {
+    await fn();
+    return true;
+  } catch {
+    return false;
+  }
+}
+var ZERO_ADDRESS_PROBE = "0x0000000000000000000000000000000000000000";
+
 // src/server.ts
 function withFacilitatorEndpoints(requirements, facilitatorUrl) {
   return {
@@ -124,9 +245,23 @@ function withFacilitatorEndpoints(requirements, facilitatorUrl) {
 function createX402bServer(config) {
   const validated = x402bServerConfigSchema.parse(config);
   assertChannelRegistryEscrowMatch(validated);
-  const facilitator = createFacilitatorClient({ url: validated.facilitator.url });
-  const exchangeFulfillmentOptionStore = validated.exchangeFulfillmentOptionStore ?? /* @__PURE__ */ new Map();
-  const fulfillmentRecoveryStore = validated.fulfillmentRecoveryStore ?? /* @__PURE__ */ new Map();
+  const logger = validated.logger ?? noopLogger;
+  logger.info("x402-server: createX402bServer", {
+    network: validated.network,
+    chainId: validated.chainId,
+    escrow: validated.escrow,
+    facilitatorUrl: validated.facilitator.url
+  });
+  const facilitator = createFacilitatorClient({
+    url: validated.facilitator.url,
+    logger,
+    ...validated.facilitator.timeoutMs !== void 0 ? { timeoutMs: validated.facilitator.timeoutMs } : {},
+    ...validated.facilitator.retry !== void 0 ? { retry: validated.facilitator.retry } : {},
+    ...validated.facilitator.idempotencyKey !== void 0 ? { idempotencyKey: validated.facilitator.idempotencyKey } : {}
+  });
+  const exchangeMutex = createKeyedMutex();
+  const exchangeFulfillmentOptionStore = validated.exchangeFulfillmentOptionStore ?? mapAsStore(/* @__PURE__ */ new Map());
+  const fulfillmentRecoveryStore = validated.fulfillmentRecoveryStore ?? mapAsStore(/* @__PURE__ */ new Map());
   validated.exchangeFulfillmentOptionStore = exchangeFulfillmentOptionStore;
   validated.fulfillmentRecoveryStore = fulfillmentRecoveryStore;
   const signOffer = (unsigned) => signFullOffer({
@@ -144,14 +279,10 @@ function createX402bServer(config) {
     return validated.exchangeReader;
   };
   let cachedCoreSdkRead;
-  const requireCoreSdkRead = (action) => {
+  const getOrCreateCoreSdkRead = () => {
     if (validated.coreSdkRead !== void 0) return validated.coreSdkRead;
     if (cachedCoreSdkRead !== void 0) return cachedCoreSdkRead;
-    if (validated.subgraphUrl === void 0) {
-      throw new Error(
-        `x402-server: handlers.${action}() requires either \`coreSdkRead\` or \`subgraphUrl\` in config (subgraph read step).`
-      );
-    }
+    if (validated.subgraphUrl === void 0) return void 0;
     cachedCoreSdkRead = asCoreSdkReadAdapter(
       new CoreSDK({
         web3Lib: createReadOnlyWeb3LibStub(),
@@ -162,10 +293,106 @@ function createX402bServer(config) {
     );
     return cachedCoreSdkRead;
   };
+  const requireCoreSdkRead = (action) => {
+    const client = getOrCreateCoreSdkRead();
+    if (client === void 0) {
+      throw new Error(
+        `x402-server: handlers.${action}() requires either \`coreSdkRead\` or \`subgraphUrl\` in config (subgraph read step).`
+      );
+    }
+    return client;
+  };
+  const recovery = {
+    async list() {
+      const entries = [];
+      for await (const [, value] of fulfillmentRecoveryStore.entries()) {
+        entries.push(value);
+      }
+      return entries;
+    },
+    async replay(exchangeId) {
+      const entry = await fulfillmentRecoveryStore.get(exchangeId);
+      if (entry === void 0) {
+        return { ok: false, reason: `no pending recovery entry for exchangeId '${exchangeId}'` };
+      }
+      const channels = validated.fulfillmentChannels ?? [];
+      const channel = channels.find((c) => c.id === entry.option);
+      if (channel === void 0) {
+        const reason = `no channel adapter is registered for option '${entry.option}'`;
+        await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+        logger.warn("x402-server: recovery replay failed (no adapter)", {
+          exchangeId,
+          option: entry.option
+        });
+        return { ok: false, reason };
+      }
+      if (entry.phase === "delivery") {
+        if (channel.onFulfill === void 0) {
+          const reason = `channel '${entry.option}' has no onFulfill; cannot replay delivery phase`;
+          await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+          logger.warn("x402-server: recovery replay failed (no onFulfill)", {
+            exchangeId,
+            option: entry.option
+          });
+          return { ok: false, reason };
+        }
+        try {
+          await channel.onFulfill(exchangeId);
+          await fulfillmentRecoveryStore.delete(exchangeId);
+          logger.info("x402-server: recovery replay succeeded", {
+            exchangeId,
+            option: entry.option,
+            phase: entry.phase
+          });
+          return { ok: true };
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+          logger.warn("x402-server: recovery replay failed (channel error)", {
+            exchangeId,
+            option: entry.option,
+            phase: entry.phase,
+            error: reason
+          });
+          return { ok: false, reason };
+        }
+      }
+      try {
+        await channel.onCommit(exchangeId, entry.data);
+        await fulfillmentRecoveryStore.delete(exchangeId);
+        logger.info("x402-server: recovery replay succeeded", {
+          exchangeId,
+          option: entry.option,
+          phase: entry.phase
+        });
+        return { ok: true };
+      } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        await fulfillmentRecoveryStore.set(exchangeId, { ...entry, error: reason });
+        logger.warn("x402-server: recovery replay failed (channel error)", {
+          exchangeId,
+          option: entry.option,
+          phase: entry.phase,
+          error: reason
+        });
+        return { ok: false, reason };
+      }
+    }
+  };
+  const healthCheck = createHealthCheck({
+    facilitator,
+    // Materialise the lazy `subgraphUrl`-backed read client on first
+    // probe so a configured subgraph is actually checked (reporting
+    // `"ok"` / `"down"` rather than `"n/a"`). Only the
+    // "no `coreSdkRead` AND no `subgraphUrl`" case maps to `"n/a"`.
+    coreSdkRead: () => getOrCreateCoreSdkRead()
+  });
   return {
     config: validated,
     facilitator,
     signOffer,
+    recovery,
+    healthCheck,
     async buildPaymentRequirements(input) {
       const offer = "unsigned" in input.offer ? await signOffer(input.offer.unsigned) : input.offer;
       const requirements = buildPaymentRequirements({
@@ -188,47 +415,73 @@ function createX402bServer(config) {
         facilitator,
         exchangeReader: await requireReader("commit"),
         fulfillmentRecoveryStore,
-        exchangeFulfillmentOptionStore
+        exchangeFulfillmentOptionStore,
+        logger
       }),
       commitAndRedeem: async (input) => handleCommitAndRedeem(input, {
         config: validated,
         facilitator,
         exchangeReader: await requireReader("commitAndRedeem"),
         fulfillmentRecoveryStore,
-        exchangeFulfillmentOptionStore
-      }),
-      redeem: async (input) => handleRedeem(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("redeem"),
         exchangeFulfillmentOptionStore,
-        fulfillmentRecoveryStore
-      }),
-      complete: async (input) => handleComplete(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("complete")
-      }),
-      disputeRaise: async (input) => handleDisputeRaise(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeRaise")
-      }),
-      disputeResolve: async (input) => handleDisputeResolve(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeResolve")
-      }),
-      disputeRetract: async (input) => handleDisputeRetract(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeRetract")
-      }),
-      disputeEscalate: async (input) => handleDisputeEscalate(input, {
-        config: validated,
-        facilitator,
-        exchangeReader: await requireReader("disputeEscalate")
+        logger
       }),
+      redeem: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleRedeem(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("redeem"),
+          exchangeFulfillmentOptionStore,
+          fulfillmentRecoveryStore,
+          logger
+        })
+      ),
+      complete: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleComplete(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("complete"),
+          logger
+        })
+      ),
+      disputeRaise: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeRaise(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeRaise"),
+          logger
+        })
+      ),
+      disputeResolve: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeResolve(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeResolve"),
+          logger
+        })
+      ),
+      disputeRetract: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeRetract(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeRetract"),
+          logger
+        })
+      ),
+      disputeEscalate: async (input) => exchangeMutex.runExclusive(
+        input.exchangeId,
+        async () => handleDisputeEscalate(input, {
+          config: validated,
+          facilitator,
+          exchangeReader: await requireReader("disputeEscalate"),
+          logger
+        })
+      ),
       withdrawFunds: async (input) => handleWithdrawFunds(input, {
         config: validated,
         facilitator,
@@ -256,6 +509,6 @@ function encodeXPaymentResponse(body) {
 }
 var X_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
 
-export { X_PAYMENT_RESPONSE_HEADER, asCoreSdkReadAdapter, assertChannelRegistryEscrowMatch, createX402bServer, encodeXPaymentResponse, x402bServerConfigSchema };
+export { X_PAYMENT_RESPONSE_HEADER, asCoreSdkReadAdapter, assertChannelRegistryEscrowMatch, createHealthCheck, createKeyedMutex, createX402bServer, encodeXPaymentResponse, isStore, mapAsStore, x402bServerConfigSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map