@parallel-protocol/x402 0.7.1 → 0.8.1

package/dist/{chunk-POU7EH3E.cjs → chunk-SNW5Z5HB.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkJPMK5YBU_cjs = require('./chunk-JPMK5YBU.cjs');
+var chunkKZZY5LS6_cjs = require('./chunk-KZZY5LS6.cjs');
 var chains = require('@parallel-protocol/chains');
 var zod = require('zod');
 
@@ -129,8 +129,18 @@ var priceSchema = zod.z.union([
     "Price must be a string, a bigint or a function of the request"
   )
 ]);
+var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function isFacilitatorUrl(value) {
+  if (!URL.canParse(value)) return false;
+  const { protocol, hostname } = new URL(value);
+  return protocol === "https:" || protocol === "http:" && LOCAL_HOSTNAMES.has(hostname);
+}
+var facilitatorUrlSchema = zod.z.string().refine(
+  isFacilitatorUrl,
+  "The facilitator URL must use https (plain http only on localhost, 127.0.0.1 or [::1])"
+);
 var facilitatorConfigSchema = zod.z.object({
-  url: zod.z.string().refine((v) => URL.canParse(v), "Invalid facilitator URL"),
+  url: facilitatorUrlSchema,
   apiKey: zod.z.string().optional()
 });
 var UPTO_MAX_TIMEOUT_SECONDS = 3600;
@@ -172,26 +182,32 @@ var facilitatorResponseSchema = zod.z.discriminatedUnion("success", [
     chain: zod.z.string(),
     gasSponsored: zod.z.boolean(),
     networkId: zod.z.string(),
-    amountSettled: zod.z.string().optional()
+    amountSettled: zod.z.string().optional(),
+    alreadySettled: zod.z.boolean().optional()
   }),
   zod.z.object({
     success: zod.z.literal(false),
     error: zod.z.object({
       code: zod.z.string(),
       message: zod.z.string(),
-      hint: zod.z.string().optional()
+      hint: zod.z.string().optional(),
+      status: zod.z.number().optional(),
+      retryAfter: zod.z.string().optional()
     })
   })
 ]);
 var verifyResponseSchema = zod.z.object({
-  isValid: zod.z.literal(true)
+  isValid: zod.z.literal(true),
+  settleToken: zod.z.string().min(1)
 });
 var settleSuccessSchema = zod.z.object({
   txHash: txHashSchema,
   route: zod.z.string(),
   gasSponsored: zod.z.boolean(),
   // Metered routes: the amount actually charged (smallest unit).
-  amountSettled: zod.z.string().optional()
+  amountSettled: zod.z.string().optional(),
+  // The facilitator answered from a recorded outcome, nothing was broadcast.
+  alreadySettled: zod.z.boolean().optional()
 });
 var settleErrorSchema = zod.z.object({
   error: zod.z.string(),
@@ -205,71 +221,133 @@ var settleResponseSchema = zod.z.union([
 // src/client.ts
 var FACILITATOR_TIMEOUT_MS = 1e4;
 var SETTLE_TIMEOUT_MS = 6e4;
+var RETRY_AFTER_SHAPE = /^(?:\d{1,10}|[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT)$/;
+async function readErrorBody(response) {
+  const json = await response.json().catch(() => null);
+  if (typeof json !== "object" || json === null) return {};
+  const { error, message } = json;
+  return {
+    ...typeof error === "string" && { error },
+    ...typeof message === "string" && { message }
+  };
+}
+function retryAfterOf(response) {
+  const value = response.headers.get("retry-after");
+  return value !== null && RETRY_AFTER_SHAPE.test(value) ? value : void 0;
+}
+function throwIfRedirect(response) {
+  const redirected = response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+  if (!redirected) return;
+  response.body?.cancel().catch(() => {
+  });
+  throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE, {
+    status: response.status
+  });
+}
 function decodePaymentHeader(paymentHeader) {
   try {
     return decodeBase64(paymentHeader);
   } catch {
-    throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.INVALID_PAYMENT);
+    throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.INVALID_PAYMENT);
   }
 }
 var FacilitatorClient = class {
+  // Checked and kept when the client is built: a config changed afterwards
+  // does not move the calls elsewhere.
+  url;
+  apiKey;
   constructor(config) {
-    this.config = config;
+    const url = facilitatorUrlSchema.safeParse(config.url);
+    if (!url.success) {
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(
+        url.error.issues[0]?.message ?? "Invalid facilitator URL",
+        url.error
+      );
+    }
+    this.url = new URL(url.data).href.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
   }
-  config;
   async verify(paymentHeader, paymentRequirements) {
     const paymentPayload = decodePaymentHeader(paymentHeader);
     let json;
     try {
-      const response = await fetch(`${this.config.url}/x402/verify`, {
+      const response = await fetch(`${this.url}/x402/verify`, {
         method: "POST",
         headers: this.buildHeaders(),
         body: JSON.stringify({ paymentPayload, paymentRequirements }),
+        redirect: "manual",
         signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
       });
+      throwIfRedirect(response);
       if (!response.ok) {
-        const errorBody = await response.json().catch(() => null);
-        const code = errorBody?.error ?? chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE;
-        throw new chunkJPMK5YBU_cjs.X402RuntimeError(code);
+        const body = await readErrorBody(response);
+        throw new chunkKZZY5LS6_cjs.X402RuntimeError(
+          body.error ?? chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE,
+          {
+            detail: body.message,
+            status: response.status,
+            retryAfter: retryAfterOf(response)
+          }
+        );
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkJPMK5YBU_cjs.X402RuntimeError) throw e;
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
-      verifyResponseSchema.parse(json);
+      const { settleToken } = verifyResponseSchema.parse(json);
+      return { settleToken };
     } catch {
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
   async settle(paymentHeader, paymentRequirements, options) {
     const paymentPayload = decodePaymentHeader(paymentHeader);
     let json;
     try {
-      const response = await fetch(`${this.config.url}/x402/settle`, {
+      const response = await fetch(`${this.url}/x402/settle`, {
         method: "POST",
         headers: this.buildHeaders(),
-        // settleAmount only travels for metered routes — exact bodies are unchanged.
+        // settleAmount only travels for metered routes; the settle token
+        // travels whenever verify issued one.
         body: JSON.stringify({
           paymentPayload,
           paymentRequirements,
           ...options?.amount !== void 0 && {
             settleAmount: options.amount
+          },
+          ...options?.settleToken !== void 0 && {
+            settleToken: options.settleToken
           }
         }),
+        redirect: "manual",
         signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS)
       });
+      throwIfRedirect(response);
       if (!response.ok) {
-        const errorBody = await response.json().catch(() => null);
-        const code = errorBody?.error ?? "SUBMISSION_FAILED";
-        const message = errorBody?.message ?? "Settlement failed";
-        return { success: false, error: { code, message } };
+        const body = await readErrorBody(response);
+        if (body.error === void 0 && response.status >= 500) {
+          throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+        }
+        const retryAfter = retryAfterOf(response);
+        return {
+          success: false,
+          error: {
+            code: body.error ?? "SUBMISSION_FAILED",
+            message: body.message ?? "Settlement failed",
+            status: response.status,
+            ...retryAfter !== void 0 && { retryAfter }
+          }
+        };
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkJPMK5YBU_cjs.X402RuntimeError) throw e;
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
+      if (e instanceof Error && e.name === "TimeoutError") {
+        throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT);
+      }
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
       const parsed = settleResponseSchema.parse(json);
@@ -283,7 +361,8 @@ var FacilitatorClient = class {
           networkId: toEip155Network(paymentRequirements.network),
           ...parsed.amountSettled !== void 0 && {
             amountSettled: parsed.amountSettled
-          }
+          },
+          ...parsed.alreadySettled && { alreadySettled: true }
         };
       }
       return {
@@ -291,39 +370,45 @@ var FacilitatorClient = class {
         error: { code: parsed.error, message: parsed.message }
       };
     } catch {
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
+  /**
+   * @deprecated The Parallel facilitator no longer serves `/x402/pay`, so this
+   * call fails with `FACILITATOR_UNAVAILABLE`. Use `verify`, then `settle`.
+   */
   async pay(paymentHeader) {
     const headers = this.buildHeaders();
     headers["X-PAYMENT"] = paymentHeader;
     let json;
     try {
-      const response = await fetch(`${this.config.url}/x402/pay`, {
+      const response = await fetch(`${this.url}/x402/pay`, {
         method: "POST",
         headers,
+        redirect: "manual",
         signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
       });
+      throwIfRedirect(response);
       if (!response.ok) {
-        throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+        throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
       }
       json = await response.json();
     } catch (e) {
-      if (e instanceof chunkJPMK5YBU_cjs.X402RuntimeError) throw e;
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
+      if (e instanceof chunkKZZY5LS6_cjs.X402RuntimeError) throw e;
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE);
     }
     try {
       return facilitatorResponseSchema.parse(json);
     } catch {
-      throw new chunkJPMK5YBU_cjs.X402RuntimeError(chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
+      throw new chunkKZZY5LS6_cjs.X402RuntimeError(chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE);
     }
   }
   buildHeaders() {
     const headers = {
       "Content-Type": "application/json"
     };
-    if (this.config.apiKey) {
-      headers["X-API-Key"] = this.config.apiKey;
+    if (this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
     }
     return headers;
   }
@@ -358,20 +443,20 @@ async function requestContext(adapter) {
 }
 async function resolvePrice(config, ctx) {
   if (typeof config.price !== "function") return config.price;
-  if (!ctx) throw new chunkJPMK5YBU_cjs.X402ConfigError("A price function needs the request");
+  if (!ctx) throw new chunkKZZY5LS6_cjs.X402ConfigError("A price function needs the request");
   let price;
   try {
     price = await config.price(ctx);
   } catch (cause) {
-    if (chunkJPMK5YBU_cjs.isPriceRejection(cause)) throw cause;
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    if (chunkKZZY5LS6_cjs.isPriceRejection(cause)) throw cause;
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `The price function of route "${config.network}${ctx.path}" threw`,
       cause
     );
   }
   const valid = typeof price === "bigint" ? price > 0n : typeof price === "string" && PRICE_FORMAT.test(price) && Number(price) > 0;
   if (!valid) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `The price function of route "${config.network}${ctx.path}" returned ${JSON.stringify(
         typeof price === "bigint" ? price.toString() : price
       )} \u2014 expected a positive amount like "0.01" or a bigint`
@@ -381,10 +466,21 @@ async function resolvePrice(config, ctx) {
 }
 var SETTLE_AMOUNT_HEADER = "payment-settle-amount";
 var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+var SETTLEMENT_RESERVE_SECONDS = 120;
 function handlerTimeoutFor(config) {
   if ((config.scheme ?? "exact") !== "upto") return HANDLER_TIMEOUT_MS;
   const seconds = config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
-  return Math.max(HANDLER_TIMEOUT_MS, (seconds - 60) * 1e3);
+  return Math.max(
+    HANDLER_TIMEOUT_MS,
+    (seconds - SETTLEMENT_RESERVE_SECONDS) * 1e3
+  );
+}
+function jsonResult(status, body, headers = {}) {
+  return {
+    status,
+    headers: { "Content-Type": "application/json", ...headers },
+    body
+  };
 }
 function resolveSettleAmount(raw, maxAmount, decimals) {
   if (raw === void 0)
@@ -412,13 +508,16 @@ var INVALID_METER_RESPONSE = {
   message: "The route's meter function failed or returned something that is not an amount; the response was discarded and nothing was charged."
 };
 function invalidSettleAmountResponse(reason) {
-  return reason === "meter" ? INVALID_METER_RESPONSE : INVALID_SETTLE_AMOUNT_RESPONSE;
+  return jsonResult(
+    402,
+    reason === "meter" ? INVALID_METER_RESPONSE : INVALID_SETTLE_AMOUNT_RESPONSE
+  );
 }
 var AMOUNT_FORMAT = /^\d+(?:\.\d+)?$/;
 async function resolveCharge(verified, settleHeader, response) {
   if (verified.meter) {
     if (!verified.request) {
-      throw new chunkJPMK5YBU_cjs.X402ConfigError(
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(
         "A metered payment carries a meter but no request context"
       );
     }
@@ -469,14 +568,14 @@ function resolveAcceptedTokens(config) {
   }
   const defaults = config.scheme === "upto" ? getMeteredAcceptedTokens(config.network) : getDefaultAcceptedTokens(config.network);
   if (defaults) return defaults;
-  throw new chunkJPMK5YBU_cjs.X402ConfigError(
+  throw new chunkKZZY5LS6_cjs.X402ConfigError(
     `acceptedTokens is required for network "${config.network}" \u2014 no defaults available for this chain`
   );
 }
 function resolveDecimals(config, asset) {
   const decimals = config.decimals ?? getTokenDecimals(config.network, asset);
   if (decimals === void 0) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `Unknown decimals for token ${asset} on "${config.network}" \u2014 add it to the @parallel-protocol/chains catalog or set the route's \`decimals\` explicitly`
     );
   }
@@ -485,7 +584,7 @@ function resolveDecimals(config, asset) {
 function priceInUnits(price, decimals, asset) {
   const units = parsePrice(price, decimals);
   if (units === 0n) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `Price ${typeof price === "bigint" ? price.toString() : `"${price}"`} is below the precision of token ${asset} (${decimals} decimals)`
     );
   }
@@ -560,31 +659,46 @@ function buildFacilitatorRequirements(config, asset, price) {
     }
   };
 }
-function paymentRequiredResponse(url, config, resolvedTokens, price, error) {
+var CODE_SHAPE = /^[A-Z][A-Z0-9_]{2,63}$/;
+var MESSAGE_MAX_LENGTH = 300;
+function shapedCode(code) {
+  return typeof code === "string" && CODE_SHAPE.test(code) ? code : void 0;
+}
+function boundedMessage(message) {
+  if (typeof message !== "string") return void 0;
+  const oneLine = message.replace(/[\p{Cc}\p{Cf}]+/gu, " ").replace(/\s+/g, " ").trim();
+  if (!oneLine) return void 0;
+  const chars = Array.from(oneLine);
+  return chars.length > MESSAGE_MAX_LENGTH ? `${chars.slice(0, MESSAGE_MAX_LENGTH).join("")}\u2026` : oneLine;
+}
+function paymentRequiredResponse(url, config, resolvedTokens, price, refusal) {
   const paymentRequired = buildPaymentRequired(
     url,
     config,
     resolvedTokens,
     price
   );
-  if (error) paymentRequired.error = error;
-  return {
-    status: 402,
-    headers: {
-      "Content-Type": "application/json",
-      "payment-required": encodeBase64(paymentRequired),
-      "access-control-expose-headers": "payment-required"
-    },
-    body: paymentRequired
-  };
+  if (refusal) {
+    paymentRequired.error = shapedCode(refusal.code) ?? chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE;
+    const message = boundedMessage(refusal.detail);
+    if (message) paymentRequired.message = message;
+  }
+  return jsonResult(402, paymentRequired, {
+    "payment-required": encodeBase64(paymentRequired),
+    "access-control-expose-headers": "payment-required",
+    ...refusal?.retryAfter !== void 0 && {
+      "Retry-After": refusal.retryAfter
+    }
+  });
 }
 function createPaymentGate(config) {
-  try {
-    paymentMiddlewareConfigSchema.parse(config);
-  } catch (cause) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
-      "Invalid paymentMiddleware config \u2014 check your routes, facilitator URL and payTo addresses",
-      cause
+  const checked = paymentMiddlewareConfigSchema.safeParse(config);
+  if (!checked.success) {
+    const issue = checked.error.issues[0];
+    const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
+      `Invalid paymentMiddleware config${where}: ${issue?.message ?? "check your routes, facilitator URL and payTo addresses"}`,
+      checked.error
     );
   }
   const client = new FacilitatorClient(config.facilitator);
@@ -599,7 +713,7 @@ function createPaymentGate(config) {
     try {
       price = await resolvePrice(routeConfig, request);
     } catch (err) {
-      if (!chunkJPMK5YBU_cjs.isPriceRejection(err)) throw err;
+      if (!chunkKZZY5LS6_cjs.isPriceRejection(err)) throw err;
       const status = Number.isInteger(err.status) && err.status >= 400 && err.status <= 599 ? err.status : 400;
       return {
         type: "error",
@@ -632,10 +746,11 @@ function createPaymentGate(config) {
       asset,
       price
     );
+    let settleToken;
     try {
-      await client.verify(paymentHeader, requirements);
+      ({ settleToken } = await client.verify(paymentHeader, requirements));
     } catch (e) {
-      const code = e instanceof chunkJPMK5YBU_cjs.X402RuntimeError ? e.code : chunkJPMK5YBU_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE;
+      const refusal = e instanceof chunkKZZY5LS6_cjs.X402RuntimeError ? { code: e.code, detail: e.detail, retryAfter: e.retryAfter } : { code: chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE };
       return {
         type: "error",
         result: paymentRequiredResponse(
@@ -643,7 +758,7 @@ function createPaymentGate(config) {
           routeConfig,
           resolvedTokens,
           price,
-          code
+          refusal
         )
       };
     }
@@ -654,12 +769,71 @@ function createPaymentGate(config) {
       maxAmount: BigInt(requirements.maxAmountRequired),
       decimals: resolveDecimals(routeConfig, asset),
       handlerTimeoutMs: handlerTimeoutFor(routeConfig),
-      // Exact routes keep the historical two-argument client call.
-      settle: (options) => options ? client.settle(paymentHeader, requirements, options) : client.settle(paymentHeader, requirements),
+      settle: (options) => client.settle(paymentHeader, requirements, { ...options, settleToken }),
       ...routeConfig.meter && { meter: routeConfig.meter, request }
     };
   };
 }
+var UNKNOWN_SETTLEMENT_MESSAGE = "The payment could not be settled.";
+var MERCHANT_SETTLEMENT_MESSAGE = "The merchant could not complete the settlement of this payment. The payment was not taken: do not sign another payment for this request before checking with the merchant.";
+var AGENT_MESSAGES = {
+  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT]: "The facilitator did not confirm the settlement in time. The payment may still settle: do not sign another payment for this request before checking with the merchant.",
+  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE]: "The facilitator could not be reached to settle the payment. It may still have settled: do not sign another payment for this request before checking with the merchant.",
+  [chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_INVALID_RESPONSE]: "The facilitator answered the settlement with an unexpected response. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
+  SETTLE_IN_PROGRESS: "The facilitator is still settling this payment. Do not sign another payment for this request before checking with the merchant.",
+  RECEIPT_UNAVAILABLE: "The facilitator sent the transaction but could not read its confirmation. The payment may have settled: do not sign another payment for this request before checking with the merchant.",
+  SETTLE_TOKEN_INVALID: MERCHANT_SETTLEMENT_MESSAGE,
+  SETTLE_TOKEN_REQUIRED: MERCHANT_SETTLEMENT_MESSAGE,
+  AMOUNT_MISMATCH: "The facilitator settled a different amount than this request asked for. The response was not served: do not sign another payment for this request before checking with the merchant.",
+  UNKNOWN: UNKNOWN_SETTLEMENT_MESSAGE
+};
+function settlementFailure(code, failure) {
+  const reason = shapedCode(code) ?? "UNKNOWN";
+  return {
+    settled: false,
+    reason,
+    message: AGENT_MESSAGES[reason] ?? boundedMessage(failure?.message) ?? UNKNOWN_SETTLEMENT_MESSAGE,
+    ...failure?.retryAfter !== void 0 && {
+      retryAfter: failure.retryAfter
+    }
+  };
+}
+var RETRY_ONCE_CODES = /* @__PURE__ */ new Set([
+  chunkKZZY5LS6_cjs.X402_ERROR_CODES.SETTLE_TIMEOUT,
+  chunkKZZY5LS6_cjs.X402_ERROR_CODES.FACILITATOR_UNAVAILABLE
+]);
+async function settleVerified(verified, options) {
+  let response;
+  for (let attempt = 0; response === void 0; attempt++) {
+    try {
+      response = await verified.settle(options);
+    } catch (e) {
+      const code = e instanceof chunkKZZY5LS6_cjs.X402RuntimeError ? e.code : "UNKNOWN";
+      if (attempt > 0 || !RETRY_ONCE_CODES.has(code)) {
+        return settlementFailure(code);
+      }
+    }
+  }
+  if (!response.success) {
+    return settlementFailure(response.error.code, response.error);
+  }
+  if (options?.amount !== void 0 && response.amountSettled !== options.amount) {
+    return settlementFailure("AMOUNT_MISMATCH");
+  }
+  return { settled: true, confirmation: response };
+}
+function settlementFailureResponse(failure) {
+  const body = {
+    error: "PAYMENT_SETTLEMENT_FAILED",
+    reason: failure.reason,
+    message: failure.message
+  };
+  return jsonResult(402, body, {
+    ...failure.retryAfter !== void 0 && {
+      "Retry-After": failure.retryAfter
+    }
+  });
+}
 function createPaymentMiddleware(config) {
   const gate = createPaymentGate(config);
   return async (adapter) => {
@@ -689,11 +863,7 @@ function createPaymentMiddleware(config) {
         });
         if (resolved.kind === "invalid") {
           handlerResult.discardResponse();
-          return {
-            status: 402,
-            headers: { "Content-Type": "application/json" },
-            body: invalidSettleAmountResponse(resolved.reason)
-          };
+          return invalidSettleAmountResponse(resolved.reason);
         }
         if (resolved.kind === "skip") {
           handlerResult.sendResponse();
@@ -701,33 +871,19 @@ function createPaymentMiddleware(config) {
         }
         settleOptions = { amount: resolved.amount };
       }
-      let settled = false;
-      try {
-        const settleResponse = settleOptions ? await gateResult.settle(settleOptions) : await gateResult.settle();
-        if (settleResponse.success) {
-          handlerResult.setResponseHeader(
-            "payment-response",
-            encodeBase64(settleResponse)
-          );
-          handlerResult.setResponseHeader(
-            "access-control-expose-headers",
-            "payment-response"
-          );
-          settled = true;
-        }
-      } catch {
-      }
-      if (!settled) {
+      const outcome = await settleVerified(gateResult, settleOptions);
+      if (!outcome.settled) {
         handlerResult.discardResponse();
-        return {
-          status: 402,
-          headers: { "Content-Type": "application/json" },
-          body: {
-            error: "PAYMENT_SETTLEMENT_FAILED",
-            message: "Payment could not be confirmed after multiple attempts. Please retry."
-          }
-        };
+        return settlementFailureResponse(outcome);
       }
+      handlerResult.setResponseHeader(
+        "payment-response",
+        encodeBase64(outcome.confirmation)
+      );
+      handlerResult.setResponseHeader(
+        "access-control-expose-headers",
+        "payment-response"
+      );
     }
     handlerResult.sendResponse();
     return { pass: true, handlerRan: true };
@@ -751,5 +907,7 @@ exports.parsePrice = parsePrice;
 exports.raceTimeout = raceTimeout;
 exports.resolveCharge = resolveCharge;
 exports.resolveSettleAmount = resolveSettleAmount;
+exports.settleVerified = settleVerified;
+exports.settlementFailureResponse = settlementFailureResponse;
 exports.toEip155Network = toEip155Network;
 exports.validateAddress = validateAddress;

package/dist/express.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkPOU7EH3E_cjs = require('./chunk-POU7EH3E.cjs');
-require('./chunk-JPMK5YBU.cjs');
+var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+require('./chunk-KZZY5LS6.cjs');
 
 // src/express/adapter.ts
 function chunkBytes(args) {
@@ -108,8 +108,8 @@ var ExpressAdapter = class {
       return originalEnd(...args);
     });
     next();
-    const outcome = await chunkPOU7EH3E_cjs.raceTimeout(endPromise, options?.timeoutMs);
-    if (outcome === chunkPOU7EH3E_cjs.HANDLER_TIMEOUT) {
+    const outcome = await chunkSNW5Z5HB_cjs.raceTimeout(endPromise, options?.timeoutMs);
+    if (outcome === chunkSNW5Z5HB_cjs.HANDLER_TIMEOUT) {
       discarded = true;
       return {
         status: 504,
@@ -146,7 +146,7 @@ var ExpressAdapter = class {
           const chunk = chunkBytes(args);
           if (chunk) bytes.push(chunk);
         }
-        return chunkPOU7EH3E_cjs.parseJsonBody(
+        return chunkSNW5Z5HB_cjs.parseJsonBody(
           contentType,
           Buffer.concat(bytes).toString("utf8")
         );
@@ -170,7 +170,7 @@ var ExpressAdapter = class {
 
 // src/express/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkPOU7EH3E_cjs.createPaymentMiddleware(config);
+  const middleware = chunkSNW5Z5HB_cjs.createPaymentMiddleware(config);
   return async (req, res, next) => {
     const result = await middleware(new ExpressAdapter(req, res, next));
     if ("pass" in result) {

package/dist/express.d.cts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
-import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.cjs';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.cjs';
 import 'viem';
 
 declare class ExpressAdapter implements HTTPAdapter {

package/dist/express.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
-import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.js';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.js';
 import 'viem';
 
 declare class ExpressAdapter implements HTTPAdapter {

package/dist/express.js

@@ -1,5 +1,5 @@
-import { raceTimeout, HANDLER_TIMEOUT, parseJsonBody, createPaymentMiddleware } from './chunk-AENXD4OC.js';
-import './chunk-AFRDHGDT.js';
+import { raceTimeout, HANDLER_TIMEOUT, parseJsonBody, createPaymentMiddleware } from './chunk-GXPUE3ES.js';
+import './chunk-QAECRSWF.js';
 
 // src/express/adapter.ts
 function chunkBytes(args) {