uvd-x402-sdk 2.78.0 → 2.80.0

package/dist/backend/index.mjs

@@ -1106,6 +1106,7 @@ var REPLAYABLE_LEASE_REASONS = [
   "body_unreadable"
 ];
 var AMBIGUOUS_LEASE_REASONS = ["forward_failed"];
+var SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
 var MAX_RETRY_AFTER_SECONDS = 15;
 var DEFAULT_RETRY_AFTER_SECONDS = 5;
 var DEFAULT_FACILITATOR_RETRIES = 2;
@@ -1127,15 +1128,44 @@ function parseRetryAfterSeconds(response) {
   if (!Number.isFinite(seconds) || seconds < 0) return void 0;
   return Math.min(seconds, MAX_RETRY_AFTER_SECONDS);
 }
-function reasonFrom(body) {
+function stringField(source, key) {
+  const value = source[key];
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function transactionHashIn(source) {
+  const tx = source.transaction;
+  if (tx && typeof tx === "object") {
+    const hash = tx.hash;
+    if (typeof hash === "string" && hash !== "") return hash;
+  }
+  if (typeof tx === "string" && tx !== "") return tx;
+  for (const key of ["txHash", "tx_hash", "transaction_hash"]) {
+    const value = stringField(source, key);
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function parseFacilitatorErrorBody(body) {
+  let parsed;
   try {
-    const parsed = JSON.parse(body);
-    if (parsed && typeof parsed === "object" && typeof parsed.reason === "string") {
-      return parsed.reason;
-    }
+    parsed = JSON.parse(body);
   } catch {
+    return {};
   }
-  return void 0;
+  if (!parsed || typeof parsed !== "object") return {};
+  return {
+    errorCode: stringField(parsed, "error"),
+    reason: stringField(parsed, "reason"),
+    transaction: transactionHashIn(parsed),
+    paymentId: stringField(parsed, "paymentId"),
+    retryable: typeof parsed.retryable === "boolean" ? parsed.retryable : void 0
+  };
+}
+function isDeclaredUnretryable(parsed) {
+  return parsed.retryable === false || parsed.errorCode === SETTLEMENT_UNCONFIRMED || parsed.transaction !== void 0;
+}
+function isSettlementUnconfirmed(failure) {
+  return failure.errorCode === SETTLEMENT_UNCONFIRMED;
 }
 async function readFacilitatorError(response) {
   let body = "";
@@ -1145,14 +1175,19 @@ async function readFacilitatorError(response) {
     body = "";
   }
   const status = response.status;
-  const reason = reasonFrom(body);
-  const retryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const parsed = parseFacilitatorErrorBody(body);
+  const reason = parsed.reason;
+  const transportRetryable = status === 429 || status === 502 || status === 503 || status === 504;
+  const retryable = transportRetryable && !isDeclaredUnretryable(parsed);
   const retryAfterSeconds = retryable ? parseRetryAfterSeconds(response) ?? DEFAULT_RETRY_AFTER_SECONDS : void 0;
-  const safeToReplay = status === 429 || status === 503 && isReplayableLeaseReason(reason);
+  const safeToReplay = retryable && (status === 429 || status === 503 && isReplayableLeaseReason(reason));
   return {
     error: `Facilitator error: ${status} - ${body}`,
     status,
     reason,
+    errorCode: parsed.errorCode,
+    transaction: parsed.transaction,
+    paymentId: parsed.paymentId,
     retryAfterSeconds,
     retryable,
     safeToReplay,
@@ -1165,6 +1200,11 @@ function failureFields(info) {
     retryable: info.retryable,
     safeToReplay: info.safeToReplay,
     ...info.reason !== void 0 ? { reason: info.reason } : {},
+    ...info.errorCode !== void 0 ? { errorCode: info.errorCode } : {},
+    // Without these the caller is told "do not retry" and given nothing to do
+    // instead — an error that swallows the hash is the same defect one layer up.
+    ...info.transaction !== void 0 ? { transaction: info.transaction } : {},
+    ...info.paymentId !== void 0 ? { paymentId: info.paymentId } : {},
     ...info.retryAfterSeconds !== void 0 ? { retryAfterSeconds: info.retryAfterSeconds } : {}
   };
 }
@@ -1172,6 +1212,9 @@ function carryFailureFields(source) {
   return {
     ...source.status !== void 0 ? { status: source.status } : {},
     ...source.reason !== void 0 ? { reason: source.reason } : {},
+    ...source.errorCode !== void 0 ? { errorCode: source.errorCode } : {},
+    ...source.transaction !== void 0 ? { transaction: source.transaction } : {},
+    ...source.paymentId !== void 0 ? { paymentId: source.paymentId } : {},
     ...source.retryable !== void 0 ? { retryable: source.retryable } : {},
     ...source.retryAfterSeconds !== void 0 ? { retryAfterSeconds: source.retryAfterSeconds } : {},
     ...source.safeToReplay !== void 0 ? { safeToReplay: source.safeToReplay } : {}
@@ -1259,7 +1302,23 @@ function buildPaymentRequirements(options) {
 }
 function buildVerifyRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // The literal `1` names THIS ENVELOPE, not the payer's header. Echoing
+    // `paymentHeader.x402Version` here -- what this did until 2026-09-04 --
+    // let a buyer who declared `2` produce a body that says "2" while carrying
+    // `paymentRequirements`, which is the v1 shape. The facilitator serves it
+    // anyway because its envelope enum is untagged and matches on shape, so
+    // nothing broke; but it ALREADY picks the hint in its 400 off this marker:
+    //
+    //   "This body declares `x402Version: 2`. x402 v2 is a JSON object with
+    //    `paymentPayload`, `resource` and `accepted`..."
+    //
+    // So the day that body fails for any other reason, the diagnosis sends the
+    // integrator to document the wrong shape. That inversion -- being told to
+    // fix the fields when the wrapper is what is wrong -- is what cost two
+    // teams a day. The payer's own marker survives untouched inside
+    // `paymentPayload`, where it belongs: it describes the payment, not the
+    // envelope carrying it.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
@@ -1282,13 +1341,21 @@ function buildSettleRequestV2(payload, resource, accepted) {
 }
 function buildSettleRequest(paymentHeader, requirements) {
   return {
-    x402Version: paymentHeader.x402Version,
+    // `1` for the same reason as {@link buildVerifyRequest}: it names the
+    // envelope, and `/settle` takes the same body as `/verify`.
+    x402Version: 1,
     paymentPayload: paymentHeader,
     paymentRequirements: requirements
   };
 }
 function isCaip2Network(network) {
-  return network.includes(":");
+  return typeof network === "string" && network.includes(":");
+}
+function networkOfPayload(payload) {
+  const top = payload.network;
+  if (typeof top === "string") return top;
+  const accepted = payload.accepted;
+  return typeof accepted?.network === "string" ? accepted.network : void 0;
 }
 function toResourceInfoV2(requirements) {
   return {
@@ -1298,9 +1365,15 @@ function toResourceInfoV2(requirements) {
   };
 }
 function toPaymentRequirementsV2(requirements) {
+  const network = isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network);
+  if (!isCaip2Network(network)) {
+    throw new Error(
+      `Network '${requirements.network}' has no CAIP-2 form, so it cannot travel in the x402 v2 envelope. Use x402Version: 1 for this network.`
+    );
+  }
   return {
     scheme: requirements.scheme,
-    network: isCaip2Network(requirements.network) ? requirements.network : chainToCAIP2(requirements.network),
+    network,
     asset: requirements.asset,
     amount: requirements.maxAmountRequired,
     payTo: requirements.payTo,
@@ -1313,7 +1386,7 @@ function resolveEnvelopeVersion(paymentHeader, requirements, requested = "auto")
   if (requested !== "auto") {
     return requested;
   }
-  return isCaip2Network(paymentHeader.network) || isCaip2Network(requirements.network) ? 2 : 1;
+  return isCaip2Network(networkOfPayload(paymentHeader)) || isCaip2Network(requirements.network) ? 2 : 1;
 }
 function buildVerifyRequestForVersion(paymentHeader, requirements, version) {
   if (version === 2) {
@@ -1986,16 +2059,23 @@ function createPaymentMiddleware(getRequirements, options = {}) {
           respondUnavailable(res, "Payment settlement unavailable", settleResult);
           return;
         }
-        res.status(500).json({
-          error: "Payment settlement failed",
-          reason: settleResult.error || "Unknown settlement error"
-        });
+        res.status(500).json(settlementFailureBody(settleResult, "Unknown settlement error"));
         return;
       }
     }
     next();
   };
 }
+function settlementFailureBody(failure, fallbackReason) {
+  return {
+    error: "Payment settlement failed",
+    reason: failure.error || fallbackReason,
+    retryable: false,
+    ...failure.errorCode !== void 0 ? { errorCode: failure.errorCode } : {},
+    ...failure.transaction !== void 0 ? { transaction: failure.transaction } : {},
+    ...failure.paymentId !== void 0 ? { paymentId: failure.paymentId } : {}
+  };
+}
 function honoUnavailable(c, message, failure) {
   const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
   c.header?.("Retry-After", String(seconds));
@@ -2070,10 +2150,7 @@ function createHonoMiddleware(options) {
         if (settleResult.retryable) {
           return honoUnavailable(c, "Payment settlement unavailable", settleResult);
         }
-        return c.json({
-          error: "Payment settlement failed",
-          reason: settleResult.error || "Unknown error"
-        }, 500);
+        return c.json(settlementFailureBody(settleResult, "Unknown error"), 500);
       }
     }
     await next();
@@ -2876,8 +2953,19 @@ var Erc8004LookupError = class extends Error {
    * `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.
+   *
+   * **Except when the body says otherwise.** `POST /register` goes through the
+   * same EVM `send_transaction_from` as a settle, so it can answer
+   * `settlement_unconfirmed`: the mint was broadcast and may be mined. That is
+   * a `502` where retrying is precisely the thing that mints the duplicate this
+   * class exists to prevent, so an explicit `retryable: false` wins over the
+   * status. See {@link SETTLEMENT_UNCONFIRMED}.
    */
   get retryable() {
+    const parsed = parseFacilitatorErrorBody(this.body);
+    if (parsed.retryable === false || parsed.errorCode === SETTLEMENT_UNCONFIRMED) {
+      return false;
+    }
     return this.status === 429 || this.status === 502 || this.status === 503 || this.status === 504;
   }
   /**
@@ -2887,14 +2975,25 @@ var Erc8004LookupError = class extends Error {
    * 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;
+    return parseFacilitatorErrorBody(this.body).reason;
+  }
+  /** The facilitator's machine-readable `error` code, when the body carried one. */
+  get errorCode() {
+    return parseFacilitatorErrorBody(this.body).errorCode;
+  }
+  /**
+   * A transaction that WAS broadcast and could not be confirmed.
+   *
+   * Present on `settlement_unconfirmed`. This is what to do INSTEAD of
+   * retrying: look it up on chain. An error that carries "do not retry" and no
+   * hash leaves the caller with nothing to act on.
+   */
+  get transaction() {
+    return parseFacilitatorErrorBody(this.body).transaction;
+  }
+  /** The payment id for {@link transaction}, identical to a successful settle's. */
+  get paymentId() {
+    return parseFacilitatorErrorBody(this.body).paymentId;
   }
   /**
    * The facilitator NAMED a reason proving it executed nothing.
@@ -2904,7 +3003,7 @@ var Erc8004LookupError = class extends Error {
    * this is false is the sequence that minted five duplicate agents.
    */
   get safeToReplay() {
-    return this.status === 429 || this.status === 503 && isReplayableLeaseReason(this.reason);
+    return this.retryable && (this.status === 429 || this.status === 503 && isReplayableLeaseReason(this.reason));
   }
   /** Seconds to wait before retrying, clamped. Absent when not retryable. */
   get retryAfterSeconds() {
@@ -4741,6 +4840,6 @@ var AdvancedEscrowClient = class {
   }
 };
 
-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, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, 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, SETTLEMENT_UNCONFIRMED, TIER_FILTERS, TIER_TIMINGS, USDC_DOMAIN_NAME, WRITER_LEASE_REASONS, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, buildErc8004PaymentRequirements, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, canRefundEscrow, canReleaseEscrow, carryFailureFields, create402Response, createHonoMiddleware, createPaymentMiddleware, epochToDate, escrowTimeRemaining, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, getEscrowContractsByChainId, getEscrowSupportedChainIds, isAlive, isAmbiguousLeaseReason, isEscrowExpired, isEscrowSupportedOnChain, isRegisterJobTerminal, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parsePaymentHeader, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, supportsRelayedFeedback, toPaymentRequirementsV2, toResourceInfoV2, wireNetwork };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map