@parallel-protocol/x402 0.7.0 → 0.8.0

package/dist/{chunk-POU7EH3E.cjs → chunk-NA7245L5.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');
 
@@ -172,26 +172,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,11 +211,25 @@ 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 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 {
@@ -228,19 +248,26 @@ var FacilitatorClient = class {
         signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
       });
       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) {
@@ -250,26 +277,43 @@ var FacilitatorClient = class {
       const response = await fetch(`${this.config.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
           }
         }),
         signal: AbortSignal.timeout(SETTLE_TIMEOUT_MS)
       });
       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 +327,8 @@ var FacilitatorClient = class {
           networkId: toEip155Network(paymentRequirements.network),
           ...parsed.amountSettled !== void 0 && {
             amountSettled: parsed.amountSettled
-          }
+          },
+          ...parsed.alreadySettled && { alreadySettled: true }
         };
       }
       return {
@@ -291,7 +336,7 @@ 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);
     }
   }
   async pay(paymentHeader) {
@@ -305,17 +350,17 @@ var FacilitatorClient = class {
         signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS)
       });
       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() {
@@ -358,20 +403,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 +426,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 +468,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 +528,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 +544,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,29 +619,43 @@ 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(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       "Invalid paymentMiddleware config \u2014 check your routes, facilitator URL and payTo addresses",
       cause
     );
@@ -599,7 +672,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 +705,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 +717,7 @@ function createPaymentGate(config) {
           routeConfig,
           resolvedTokens,
           price,
-          code
+          refusal
         )
       };
     }
@@ -654,12 +728,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 +822,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 +830,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 +866,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/{chunk-AFRDHGDT.js → chunk-QAECRSWF.js}

@@ -2,7 +2,9 @@
 var X402_ERROR_CODES = {
   FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE",
   FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE",
-  INVALID_PAYMENT: "INVALID_PAYMENT"
+  INVALID_PAYMENT: "INVALID_PAYMENT",
+  /** The facilitator did not answer a settle within the client's timeout: the payment may still settle. */
+  SETTLE_TIMEOUT: "SETTLE_TIMEOUT"
 };
 var X402ConfigError = class extends Error {
   constructor(message, cause) {
@@ -12,12 +14,21 @@ var X402ConfigError = class extends Error {
   }
 };
 var X402RuntimeError = class extends Error {
-  constructor(code) {
+  constructor(code, extra) {
     super(code);
     this.code = code;
     this.name = "X402RuntimeError";
+    if (extra?.detail !== void 0) this.detail = extra.detail;
+    if (extra?.status !== void 0) this.status = extra.status;
+    if (extra?.retryAfter !== void 0) this.retryAfter = extra.retryAfter;
   }
   code;
+  /** The facilitator's message for this code, when it answered with one. */
+  detail;
+  /** The facilitator's HTTP status, when the error comes from its answer. */
+  status;
+  /** The facilitator's `Retry-After` header, when it sent one. */
+  retryAfter;
 };
 var X402PriceRejectedError = class extends Error {
   constructor(code, message, status = 400) {