uvd-x402-sdk 2.74.0 → 2.76.0

package/dist/backend/index.mjs

@@ -1091,6 +1091,118 @@ function decodeX402Header(encoded) {
 var REVIEW_WINDOW_SEC = 7 * 24 * 3600;
 var REFUND_WINDOW_SEC = 7 * 24 * 3600;
 
+// src/backend/facilitator-error.ts
+var WRITER_LEASE_REASONS = [
+  "holder_unknown",
+  "forwarding_disabled",
+  "forwarded_but_not_writer",
+  "body_unreadable",
+  "forward_failed"
+];
+var REPLAYABLE_LEASE_REASONS = [
+  "holder_unknown",
+  "forwarding_disabled",
+  "forwarded_but_not_writer",
+  "body_unreadable"
+];
+var AMBIGUOUS_LEASE_REASONS = ["forward_failed"];
+var MAX_RETRY_AFTER_SECONDS = 15;
+var DEFAULT_RETRY_AFTER_SECONDS = 5;
+var DEFAULT_FACILITATOR_RETRIES = 2;
+function isReplayableLeaseReason(reason) {
+  return REPLAYABLE_LEASE_REASONS.includes(reason);
+}
+function isAmbiguousLeaseReason(reason) {
+  return AMBIGUOUS_LEASE_REASONS.includes(reason);
+}
+function parseRetryAfterSeconds(response) {
+  let raw;
+  try {
+    raw = response?.headers?.get?.("retry-after");
+  } catch {
+    return void 0;
+  }
+  if (raw === null || raw === void 0 || raw === "") return void 0;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) return void 0;
+  return Math.min(seconds, MAX_RETRY_AFTER_SECONDS);
+}
+function reasonFrom(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
+      return parsed.reason;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function readFacilitatorError(response) {
+  let body = "";
+  try {
+    body = await response.text();
+  } catch {
+    body = "";
+  }
+  const status = response.status;
+  const reason = reasonFrom(body);
+  const retryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const retryAfterSeconds = retryable ? parseRetryAfterSeconds(response) ?? DEFAULT_RETRY_AFTER_SECONDS : void 0;
+  const safeToReplay = status === 429 || status === 503 && isReplayableLeaseReason(reason);
+  return {
+    error: `Facilitator error: ${status} - ${body}`,
+    status,
+    reason,
+    retryAfterSeconds,
+    retryable,
+    safeToReplay,
+    body
+  };
+}
+function failureFields(info) {
+  return {
+    status: info.status,
+    retryable: info.retryable,
+    safeToReplay: info.safeToReplay,
+    ...info.reason !== void 0 ? { reason: info.reason } : {},
+    ...info.retryAfterSeconds !== void 0 ? { retryAfterSeconds: info.retryAfterSeconds } : {}
+  };
+}
+function carryFailureFields(source) {
+  return {
+    ...source.status !== void 0 ? { status: source.status } : {},
+    ...source.reason !== void 0 ? { reason: source.reason } : {},
+    ...source.retryable !== void 0 ? { retryable: source.retryable } : {},
+    ...source.retryAfterSeconds !== void 0 ? { retryAfterSeconds: source.retryAfterSeconds } : {},
+    ...source.safeToReplay !== void 0 ? { safeToReplay: source.safeToReplay } : {}
+  };
+}
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function facilitatorFetch(url, init, options) {
+  const retries = options.retries ?? DEFAULT_FACILITATOR_RETRIES;
+  const canReplay = options.canReplay ?? ((info) => info.safeToReplay);
+  const doFetch = options.fetchImpl ?? fetch;
+  const sleep = options.sleepImpl ?? defaultSleep;
+  let attempt = 0;
+  for (; ; ) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeoutMs);
+    let response;
+    try {
+      response = await doFetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (response.ok) return { response };
+    const error = await readFacilitatorError(response);
+    if (attempt >= retries || !error.retryable || !canReplay(error)) {
+      return { response, error };
+    }
+    attempt += 1;
+    await sleep((error.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS) * 1e3);
+  }
+}
+
 // src/backend/index.ts
 function parsePaymentHeader(headerValue) {
   if (!headerValue) {
@@ -1197,10 +1309,12 @@ var FacilitatorClient = class {
   baseUrl;
   timeout;
   explicitTimeout;
+  retries;
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || "https://facilitator.ultravioletadao.xyz";
     this.explicitTimeout = options.timeout !== void 0;
     this.timeout = options.timeout || 3e4;
+    this.retries = options.retries;
   }
   /**
    * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -1227,29 +1341,31 @@ var FacilitatorClient = class {
    */
   async verify(paymentHeader, requirements) {
     const body = buildVerifyRequest(paymentHeader, requirements);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}/verify`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      const { response, error } = await facilitatorFetch(
+        `${this.baseUrl}/verify`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: this.timeout, retries: this.retries }
+      );
+      if (error) {
         return {
           isValid: false,
-          invalidReason: `Facilitator error: ${response.status} - ${errorText}`
+          invalidReason: error.error,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         isValid: false,
-        invalidReason: error instanceof Error ? error.message : "Unknown error"
+        invalidReason: error instanceof Error ? error.message : "Unknown error",
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -1265,21 +1381,21 @@ var FacilitatorClient = class {
   async settle(paymentHeader, requirements) {
     const body = buildSettleRequest(paymentHeader, requirements);
     const settleTimeout = this.getTimeout(requirements.network);
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), settleTimeout);
     try {
-      const response = await fetch(`${this.baseUrl}/settle`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      const { response, error } = await facilitatorFetch(
+        `${this.baseUrl}/settle`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body)
+        },
+        { timeoutMs: settleTimeout, retries: this.retries }
+      );
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`
+          error: error.error,
+          ...failureFields(error)
         };
       }
       const result = await response.json();
@@ -1320,10 +1436,12 @@ var FacilitatorClient = class {
         payer: result.payer
       };
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
-        error: error instanceof Error ? error.message : "Unknown error"
+        error: error instanceof Error ? error.message : "Unknown error",
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -1343,7 +1461,8 @@ var FacilitatorClient = class {
       return {
         verified: false,
         settled: false,
-        error: verifyResult.invalidReason
+        error: verifyResult.invalidReason,
+        ...carryFailureFields(verifyResult)
       };
     }
     const settleResult = await this.settle(paymentHeader, requirements);
@@ -1351,7 +1470,8 @@ var FacilitatorClient = class {
       verified: true,
       settled: settleResult.success,
       transactionHash: settleResult.transactionHash,
-      error: settleResult.error
+      error: settleResult.error,
+      ...carryFailureFields(settleResult)
     };
   }
   /**
@@ -1753,10 +1873,29 @@ function createVerifiedPaymentState(client, payment, requirements, verifyResult)
     }
   };
 }
+function respondUnavailable(res, message, failure) {
+  const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
+  const body = {
+    error: message,
+    reason: failure.reason ?? failure.invalidReason ?? failure.error,
+    retryable: true,
+    retryAfterSeconds: seconds,
+    // False for `forward_failed` and for a bare timeout: the write may already
+    // have landed, so the caller must reconcile before resending.
+    safeToReplay: failure.safeToReplay === true
+  };
+  const staged = res.status(503);
+  if (typeof staged.set === "function") {
+    staged.set({ "Retry-After": String(seconds) }).json(body);
+    return;
+  }
+  staged.json(body);
+}
 function createPaymentMiddleware(getRequirements, options = {}) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
-    timeout: options.timeout
+    timeout: options.timeout,
+    retries: options.retries
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   return async (req, res, next) => {
@@ -1771,6 +1910,10 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     const requirements = buildPaymentRequirements(reqOptions);
     const verifyResult = await client.verify(payment, requirements);
     if (!verifyResult.isValid) {
+      if (verifyResult.retryable) {
+        respondUnavailable(res, "Payment verification unavailable", verifyResult);
+        return;
+      }
       res.status(402).json({
         error: "Payment verification failed",
         reason: verifyResult.invalidReason
@@ -1781,6 +1924,10 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     if (settlementStrategy === "before-handler") {
       const settleResult = await req.x402.settle();
       if (!settleResult.success) {
+        if (settleResult.retryable) {
+          respondUnavailable(res, "Payment settlement unavailable", settleResult);
+          return;
+        }
         res.status(500).json({
           error: "Payment settlement failed",
           reason: settleResult.error || "Unknown settlement error"
@@ -1791,10 +1938,25 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     next();
   };
 }
+function honoUnavailable(c, message, failure) {
+  const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
+  c.header?.("Retry-After", String(seconds));
+  return c.json(
+    {
+      error: message,
+      reason: failure.reason ?? failure.invalidReason ?? failure.error,
+      retryable: true,
+      retryAfterSeconds: seconds,
+      safeToReplay: failure.safeToReplay === true
+    },
+    503
+  );
+}
 function createHonoMiddleware(options) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
-    timeout: options.timeout
+    timeout: options.timeout,
+    retries: options.retries
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   if (!options.accepts[0]) {
@@ -1834,6 +1996,9 @@ function createHonoMiddleware(options) {
     }
     const verifyResult = await client.verify(parsed, requirement);
     if (!verifyResult.isValid) {
+      if (verifyResult.retryable) {
+        return honoUnavailable(c, "Payment verification unavailable", verifyResult);
+      }
       return c.json({
         error: "Payment verification failed",
         reason: verifyResult.invalidReason
@@ -1844,6 +2009,9 @@ function createHonoMiddleware(options) {
     if (settlementStrategy === "before-handler") {
       const settleResult = await verifiedPayment.settle();
       if (!settleResult.success) {
+        if (settleResult.retryable) {
+          return honoUnavailable(c, "Payment settlement unavailable", settleResult);
+        }
         return c.json({
           error: "Payment settlement failed",
           reason: settleResult.error || "Unknown error"
@@ -2625,19 +2793,65 @@ var Erc8004LookupError = class extends Error {
   status;
   /** Raw response body, for debugging */
   body;
-  constructor(message, status, body) {
+  /**
+   * `Retry-After`, already clamped, when the facilitator sent one.
+   *
+   * Optional so every existing three-argument construction keeps compiling; it
+   * falls back to the default wait rather than to zero, because a caller that
+   * retries instantly on a 503 is the load that caused it.
+   */
+  retryAfterHint;
+  constructor(message, status, body, retryAfterSeconds) {
     super(message);
     this.name = "Erc8004LookupError";
     this.status = status;
     this.body = body;
+    this.retryAfterHint = retryAfterSeconds;
   }
   /** The address genuinely owns no agent on this network. */
   get notFound() {
     return this.status === 404;
   }
-  /** The lookup reached no verdict. Retry; never read as "owns nothing". */
+  /**
+   * The lookup reached no verdict. Retry; never read as "owns nothing".
+   *
+   * `502` and `504` join `503` and `429` here: a gateway that answered on the
+   * facilitator's behalf is exactly as silent about the agent's existence, and
+   * reading either as absence has the same consequence -- a duplicate mint.
+   */
   get retryable() {
-    return this.status === 503;
+    return this.status === 429 || this.status === 502 || this.status === 503 || this.status === 504;
+  }
+  /**
+   * The facilitator's own `reason`, when the body carried one.
+   *
+   * On a WRITE route this is the writer-lease reason and it decides whether the
+   * request may be re-sent; see {@link isReplayableLeaseReason}.
+   */
+  get reason() {
+    try {
+      const parsed = JSON.parse(this.body);
+      if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
+        return parsed.reason;
+      }
+    } catch {
+    }
+    return void 0;
+  }
+  /**
+   * The facilitator NAMED a reason proving it executed nothing.
+   *
+   * False for `forward_failed` and for every unattributed 5xx: "something
+   * answered" is not evidence that nothing ran. On `/register`, replaying when
+   * this is false is the sequence that minted five duplicate agents.
+   */
+  get safeToReplay() {
+    return this.status === 429 || this.status === 503 && isReplayableLeaseReason(this.reason);
+  }
+  /** Seconds to wait before retrying, clamped. Absent when not retryable. */
+  get retryAfterSeconds() {
+    if (!this.retryable) return void 0;
+    return this.retryAfterHint ?? DEFAULT_RETRY_AFTER_SECONDS;
   }
 };
 function isRegisterJobTerminal(job) {
@@ -2674,9 +2888,38 @@ function jobToRegisterResponse(job, network) {
 var Erc8004Client = class {
   baseUrl;
   timeout;
+  retries;
   constructor(options = {}) {
     this.baseUrl = options.baseUrl || "https://facilitator.ultravioletadao.xyz";
     this.timeout = options.timeout || 3e4;
+    this.retries = options.retries;
+  }
+  /**
+   * POST a write route, keeping a refusal readable.
+   *
+   * Every ERC-8004 write goes through the facilitator's EVM writer lease, so
+   * every one of them can answer `503` + `reason`. Flattened to a string, those
+   * are indistinguishable from "the registry rejected your feedback" — and on
+   * `/register` the wrong reading re-POSTs a mint that may already have landed,
+   * which is precisely how five duplicate agents were once created.
+   *
+   * A refusal the facilitator proved it did not execute is replayed
+   * automatically (`safeToReplay`); `forward_failed` never is.
+   */
+  async writeJson(url, body, extraHeaders = {}) {
+    return facilitatorFetch(
+      url,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          ...extraHeaders
+        },
+        body: JSON.stringify(body)
+      },
+      { timeoutMs: this.timeout, retries: this.retries }
+    );
   }
   /**
    * Get agent identity from the Identity Registry
@@ -2725,26 +2968,21 @@ var Erc8004Client = class {
     const url = `${this.baseUrl}/identity/${wireNetwork(network)}/owner/${address}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: { "Accept": "application/json" },
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Erc8004LookupError(
-          `ERC-8004 API error: ${response.status} - ${errorText}`,
-          response.status,
-          errorText
-        );
-      }
-      return await response.json();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      throw error;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    }).finally(() => clearTimeout(timeoutId));
+    if (!response.ok) {
+      const info = await readFacilitatorError(response);
+      throw new Erc8004LookupError(
+        `ERC-8004 API error: ${info.status} - ${info.body}`,
+        info.status,
+        info.body,
+        info.retryAfterSeconds
+      );
     }
+    return await response.json();
   }
   /**
    * Resolve agent registration file from agentURI
@@ -2853,34 +3091,28 @@ var Erc8004Client = class {
    */
   async submitFeedback(request) {
     const url = `${this.baseUrl}/feedback`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json"
-        },
-        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
-        signal: controller.signal
+      const { response, error } = await this.writeJson(url, {
+        ...request,
+        network: wireNetwork(request.network)
       });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`,
-          network: request.network
+          error: error.error,
+          network: request.network,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
-        network: request.network
+        network: request.network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -2989,34 +3221,28 @@ var Erc8004Client = class {
    */
   async submitRelayedFeedback(request) {
     const url = `${this.baseUrl}/feedback/evm/submit`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json"
-        },
-        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
-        signal: controller.signal
+      const { response, error } = await this.writeJson(url, {
+        ...request,
+        network: wireNetwork(request.network)
       });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`,
-          network: request.network
+          error: error.error,
+          network: request.network,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
-        network: request.network
+        network: request.network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3032,8 +3258,6 @@ var Erc8004Client = class {
    */
   async revokeFeedback(network, agentId, feedbackIndex, options) {
     const url = `${this.baseUrl}/feedback/revoke`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     const payload = {
       x402Version: 1,
       network: wireNetwork(network),
@@ -3046,31 +3270,24 @@ var Erc8004Client = class {
       payload.originalFeedback = options.originalFeedback;
     }
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json"
-        },
-        body: JSON.stringify(payload),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      const { response, error } = await this.writeJson(url, payload);
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`,
-          network
+          error: error.error,
+          network,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
-        network
+        network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3160,24 +3377,23 @@ var Erc8004Client = class {
   }
   /** Shared POST for the relay routes: a refusal is data, never a throw. */
   async postRelay(path, request, onError) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}${path}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "Accept": "application/json" },
-        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
-        signal: controller.signal
+      const { response, error } = await this.writeJson(`${this.baseUrl}${path}`, {
+        ...request,
+        network: wireNetwork(request.network)
       });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
-        return { ...onError, error: `Facilitator error: ${response.status} - ${errorText}` };
+      if (error) {
+        return { ...onError, error: error.error, ...failureFields(error) };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
-      return { ...onError, error: error instanceof Error ? error.message : "Unknown error" };
+      return {
+        ...onError,
+        error: error instanceof Error ? error.message : "Unknown error",
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
+      };
     }
   }
   /**
@@ -3214,8 +3430,6 @@ var Erc8004Client = class {
    */
   async appendResponse(network, agentId, feedbackIndex, response, options) {
     const url = `${this.baseUrl}/feedback/response`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     const payload = {
       x402Version: 1,
       network: wireNetwork(network),
@@ -3230,31 +3444,24 @@ var Erc8004Client = class {
       payload.sealHash = options.sealHash;
     }
     try {
-      const fetchResponse = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json"
-        },
-        body: JSON.stringify(payload),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!fetchResponse.ok) {
-        const errorText = await fetchResponse.text();
+      const { response: fetchResponse, error } = await this.writeJson(url, payload);
+      if (error) {
         return {
           success: false,
-          error: `Facilitator error: ${fetchResponse.status} - ${errorText}`,
-          network
+          error: error.error,
+          network,
+          ...failureFields(error)
         };
       }
       return await fetchResponse.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
-        network
+        network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3298,47 +3505,42 @@ var Erc8004Client = class {
       return jobToRegisterResponse(terminal, request.network);
     }
     const url = `${this.baseUrl}/register`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json"
-        },
-        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
-        signal: controller.signal
+      const { response, error } = await this.writeJson(url, {
+        ...request,
+        network: wireNetwork(request.network)
       });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
+      if (error) {
         try {
-          const parsed = JSON.parse(errorText);
+          const parsed = JSON.parse(error.body);
           if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
             return {
               ...parsed,
-              // Never let a 4xx body claim success, whatever it says.
+              // Never let a non-2xx body claim success, whatever it says.
               success: false,
-              error: parsed.error ?? `Facilitator error: ${response.status}`,
-              network: parsed.network ?? request.network
+              error: parsed.error ?? `Facilitator error: ${error.status}`,
+              network: parsed.network ?? request.network,
+              ...failureFields(error)
             };
           }
         } catch {
         }
         return {
           success: false,
-          error: `Facilitator error: ${response.status} - ${errorText}`,
-          network: request.network
+          error: error.error,
+          network: request.network,
+          ...failureFields(error)
         };
       }
       return await response.json();
     } catch (error) {
-      clearTimeout(timeoutId);
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
-        network: request.network
+        network: request.network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
       };
     }
   }
@@ -3356,33 +3558,20 @@ var Erc8004Client = class {
    */
   async registerAgentAsync(request) {
     const url = `${this.baseUrl}/register`;
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Accept": "application/json",
-          "Prefer": "respond-async"
-        },
-        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Erc8004LookupError(
-          `ERC-8004 API error: ${response.status} - ${errorText}`,
-          response.status,
-          errorText
-        );
-      }
-      return await response.json();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      throw error;
+    const { response, error } = await this.writeJson(
+      url,
+      { ...request, network: wireNetwork(request.network) },
+      { Prefer: "respond-async" }
+    );
+    if (error) {
+      throw new Erc8004LookupError(
+        `ERC-8004 API error: ${error.status} - ${error.body}`,
+        error.status,
+        error.body,
+        error.retryAfterSeconds
+      );
     }
+    return await response.json();
   }
   /**
    * Read the current state of an asynchronous registration.
@@ -3394,26 +3583,21 @@ var Erc8004Client = class {
     const url = `${this.baseUrl}/register/status/${encodeURIComponent(jobId)}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(url, {
-        method: "GET",
-        headers: { "Accept": "application/json" },
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      if (!response.ok) {
-        const errorText = await response.text();
-        throw new Erc8004LookupError(
-          `ERC-8004 API error: ${response.status} - ${errorText}`,
-          response.status,
-          errorText
-        );
-      }
-      return await response.json();
-    } catch (error) {
-      clearTimeout(timeoutId);
-      throw error;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    }).finally(() => clearTimeout(timeoutId));
+    if (!response.ok) {
+      const info = await readFacilitatorError(response);
+      throw new Erc8004LookupError(
+        `ERC-8004 API error: ${info.status} - ${info.body}`,
+        info.status,
+        info.body,
+        info.retryAfterSeconds
+      );
     }
+    return await response.json();
   }
   /**
    * Poll an asynchronous registration until it finishes.
@@ -3714,6 +3898,7 @@ var AdvancedEscrowClient = class {
   chainId;
   gasLimit;
   timeout;
+  retries;
   contracts;
   signer;
   // ethers.Signer (legacy mode)
@@ -3750,6 +3935,7 @@ var AdvancedEscrowClient = class {
     this.chainId = options.chainId || 8453;
     this.gasLimit = options.gasLimit || 3e5;
     this.timeout = options.timeout || ESCROW_TIMEOUT_MS[this.chainId] || DEFAULT_ESCROW_TIMEOUT_MS;
+    this.retries = options.retries;
     if (this.walletAdapter && !this.rpcUrl) {
       throw new Error(
         "AdvancedEscrowClient: rpcUrl is required when using a SigningWalletAdapter. The adapter signs transactions offline; an RPC provider is needed to build and broadcast them."
@@ -3824,8 +4010,8 @@ var AdvancedEscrowClient = class {
    * Matches the on-chain AuthCaptureEscrow nonce derivation.
    */
   async computeNonce(paymentInfo) {
-    const { ethers: ethers2 } = await import('ethers');
-    const piTuple = ethers2.AbiCoder.defaultAbiCoder().encode(
+    const { ethers: ethers3 } = await import('ethers');
+    const piTuple = ethers3.AbiCoder.defaultAbiCoder().encode(
       ["bytes32", "tuple(address,address,address,address,uint120,uint48,uint48,uint48,uint16,uint16,address,uint256)"],
       [
         PAYMENT_INFO_TYPEHASH,
@@ -3846,12 +4032,12 @@ var AdvancedEscrowClient = class {
         ]
       ]
     );
-    const piHash = ethers2.keccak256(piTuple);
-    const finalEncoded = ethers2.AbiCoder.defaultAbiCoder().encode(
+    const piHash = ethers3.keccak256(piTuple);
+    const finalEncoded = ethers3.AbiCoder.defaultAbiCoder().encode(
       ["uint256", "address", "bytes32"],
       [this.chainId, this.contracts.escrow, piHash]
     );
-    return ethers2.keccak256(finalEncoded);
+    return ethers3.keccak256(finalEncoded);
   }
   /**
    * Sign ReceiveWithAuthorization for ERC-3009.
@@ -4008,17 +4194,17 @@ var AdvancedEscrowClient = class {
   async release(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers2 } = await import('ethers');
+      const { ethers: ethers3 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers2, abi, (iface) => {
+        return this.sendViaAdapter(ethers3, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("release", [tuple, amt, "0x"]) : iface.encodeFunctionData("release", [tuple, amt]);
         });
       }
-      const contract = new ethers2.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.release(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.release(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4042,17 +4228,17 @@ var AdvancedEscrowClient = class {
   async refundInEscrow(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers2 } = await import('ethers');
+      const { ethers: ethers3 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers2, abi, (iface) => {
+        return this.sendViaAdapter(ethers3, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("refundInEscrow", [tuple, amt, "0x"]) : iface.encodeFunctionData("refundInEscrow", [tuple, amt]);
         });
       }
-      const contract = new ethers2.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers3.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.refundInEscrow(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4122,16 +4308,19 @@ var AdvancedEscrowClient = class {
           }
         }
       };
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       try {
-        const response = await fetch(`${this.facilitatorUrl}/settle`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(payload),
-          signal: controller.signal
-        });
-        clearTimeout(timeoutId);
+        const { response, error } = await facilitatorFetch(
+          `${this.facilitatorUrl}/settle`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload)
+          },
+          { timeoutMs: this.timeout, retries: this.retries }
+        );
+        if (error) {
+          return { success: false, error: error.error, ...failureFields(error) };
+        }
         const result = await response.json();
         if (result.success) {
           return {
@@ -4144,7 +4333,6 @@ var AdvancedEscrowClient = class {
           error: result.errorReason || result.error || `Release refused with no reason (HTTP ${response.status}, body keys: ${Object.keys(result ?? {}).sort().join(", ") || "none"})`
         };
       } catch (fetchErr) {
-        clearTimeout(timeoutId);
         if (fetchErr.name === "AbortError") {
           try {
             const state = await this.queryEscrowState(paymentInfo);
@@ -4162,23 +4350,53 @@ var AdvancedEscrowClient = class {
     }
   }
   /**
-   * GASLESS REFUND: Refund escrowed funds via the facilitator.
+   * GASLESS REFUND: return escrowed funds to the payer via the facilitator.
    *
-   * Instead of calling the PaymentOperator contract directly (which requires
-   * gas), this sends a refundInEscrow request to the facilitator, which
-   * submits the transaction on your behalf.
+   * Sends `action: "refundInEscrow"` to `POST /settle`; the facilitator's
+   * PaymentOperator calls `AuthCaptureEscrow.partialVoid`.
+   *
+   * # This is how an EXPIRED escrow is recovered
+   *
+   * A widely repeated claim — including in this SDK's own comments until now —
+   * says that once `authorizationExpiry` passes, only the payer's `reclaim()`
+   * can move the funds. **That is false, and believing it has left real money
+   * stranded.**
+   *
+   * Read the contract (`AuthCaptureEscrow.sol`):
+   *
+   * - `partialVoid` is `onlySender(paymentInfo.operator)` — the operator is the
+   *   FACILITATOR, not the payer — it sends the tokens **to the payer**, and it
+   *   **does not check `authorizationExpiry` at all**. It works before expiry
+   *   and after it, and the payer never has to appear.
+   * - `reclaim` is `onlySender(paymentInfo.payer)` and only after expiry. It is
+   *   a payer's self-service escape hatch, which is why this facilitator does
+   *   not expose it — **not** the only way out.
+   *
+   * So a release that reverted with `AfterAuthorizationExpiry` is recoverable
+   * from here, with no gas and no cooperation from the payer. Get the amount
+   * from {@link queryEscrowState}'s `capturableAmount`.
+   *
+   * # A refusal that is not a refusal
+   *
+   * Check `retryable` before writing an escrow off. A `503` means the
+   * facilitator never reached the chain — the escrow is untouched and the same
+   * request should be sent again.
    *
    * @param paymentInfo - PaymentInfo from the authorize step
-   * @param amount - Amount to refund in atomic units (defaults to maxAmount)
+   * @param amount - Amount to refund in atomic units (defaults to maxAmount).
+   *   For a stuck escrow pass `capturableAmount` from {@link queryEscrowState}.
    * @returns Transaction result from the facilitator
    *
-   * @example
+   * @example Recovering an escrow whose release window already closed
    * ```typescript
-   * const pi = client.buildPaymentInfo('0xWorker...', '5000000', 'standard');
-   * await client.authorize(pi);
-   * // Task cancelled...
-   * const result = await client.refundViaFacilitator(pi);
-   * console.log(result.transactionHash);
+   * const state = await client.queryEscrowState(pi);
+   * if (state.capturableAmount !== '0') {
+   *   // No payer needed, no gas, and expiry is irrelevant to partialVoid.
+   *   const result = await client.refundViaFacilitator(pi, state.capturableAmount);
+   *   if (!result.success && result.retryable) {
+   *     // No verdict was reached. The funds are still there; send it again.
+   *   }
+   * }
    * ```
    */
   async refundViaFacilitator(paymentInfo, amount) {
@@ -4215,16 +4433,19 @@ var AdvancedEscrowClient = class {
           }
         }
       };
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       try {
-        const response = await fetch(`${this.facilitatorUrl}/settle`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(payload),
-          signal: controller.signal
-        });
-        clearTimeout(timeoutId);
+        const { response, error } = await facilitatorFetch(
+          `${this.facilitatorUrl}/settle`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload)
+          },
+          { timeoutMs: this.timeout, retries: this.retries }
+        );
+        if (error) {
+          return { success: false, error: error.error, ...failureFields(error) };
+        }
         const result = await response.json();
         if (result.success) {
           return {
@@ -4232,9 +4453,11 @@ var AdvancedEscrowClient = class {
             transactionHash: result.transaction || result.transactionHash || result.transaction_hash
           };
         }
-        return { success: false, error: result.errorReason || result.error || "Refund failed" };
+        return {
+          success: false,
+          error: result.errorReason || result.error || `Refund refused with no reason (HTTP ${response.status}, body keys: ${Object.keys(result ?? {}).sort().join(", ") || "none"})`
+        };
       } catch (fetchErr) {
-        clearTimeout(timeoutId);
         if (fetchErr.name === "AbortError") {
           try {
             const state = await this.queryEscrowState(paymentInfo);
@@ -4318,7 +4541,7 @@ var AdvancedEscrowClient = class {
   async charge(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers2 } = await import('ethers');
+      const { ethers: ethers3 } = await import('ethers');
       const nonce = await this.computeNonce(paymentInfo);
       const amt = amount || paymentInfo.maxAmount;
       const auth = {
@@ -4330,10 +4553,10 @@ var AdvancedEscrowClient = class {
         nonce
       };
       const signature = await this.signErc3009(auth);
-      const collectorData = ethers2.getBytes(signature);
+      const collectorData = ethers3.getBytes(signature);
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers2, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("charge", [
             tuple,
             amt,
@@ -4342,7 +4565,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers2.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.charge(
         tuple,
         amt,
@@ -4384,11 +4607,11 @@ var AdvancedEscrowClient = class {
   async refundPostEscrow(paymentInfo, amount, tokenCollector, collectorData) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers: ethers2 } = await import('ethers');
+      const { ethers: ethers3 } = await import('ethers');
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers2, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers3, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("refundPostEscrow", [
             tuple,
             amt,
@@ -4397,7 +4620,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers2.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers3.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.refundPostEscrow(
         tuple,
         amt,
@@ -4460,6 +4683,6 @@ var AdvancedEscrowClient = class {
   }
 };
 
-export { AdvancedEscrowClient, BASE_MAINNET_CONTRACTS, BazaarClient, DEPOSIT_LIMIT_USDC, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, Erc8004LookupError, EscrowClient, FacilitatorClient, HEALTH_FILTERS, MAX_SEARCH_LEN, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, RELAYED_FEEDBACK_NETWORKS, RegistrationPendingError, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, parsePaymentHeader, supportsRelayedFeedback, wireNetwork };
+export { AMBIGUOUS_LEASE_REASONS, AdvancedEscrowClient, BASE_MAINNET_CONTRACTS, BazaarClient, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, DEPOSIT_LIMIT_USDC, ERC8004_CONTRACTS, ERC8004_EXTENSION_ID, ESCROW_CONTRACTS, ESCROW_TIMEOUT_MS, Erc8004Client, Erc8004LookupError, EscrowClient, FacilitatorClient, HEALTH_FILTERS, MAX_RETRY_AFTER_SECONDS, MAX_SEARCH_LEN, OPERATOR_ABI, OPERATOR_ABI_CREATE3, PAYMENT_INFO_TYPEHASH, RELAYED_FEEDBACK_NETWORKS, REPLAYABLE_LEASE_REASONS, RegistrationPendingError, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, WRITER_LEASE_REASONS, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, supportsRelayedFeedback, wireNetwork };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map