uvd-x402-sdk 2.78.0 → 2.80.0

package/dist/index.mjs

@@ -3762,6 +3762,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;
@@ -3783,15 +3784,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 = "";
@@ -3801,14 +3831,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,
@@ -3821,6 +3856,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 } : {}
   };
 }
@@ -3828,6 +3868,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 } : {}
@@ -3915,7 +3958,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
   };
@@ -3938,13 +3997,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 {
@@ -3954,9 +4021,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,
@@ -3969,7 +4042,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) {
@@ -4642,16 +4715,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));
@@ -4726,10 +4806,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();
@@ -4758,6 +4835,6 @@ var ESCROW_TIMEOUT_MS = {
   // Monad: 90s
 };
 
-export { AMBIGUOUS_LEASE_REASONS, ANCHOR_MAX_REQUEST_BYTES, CAIP2_IDENTIFIERS, CAIP2_TO_CHAIN, ContentHashMismatch, DEFAULT_CHAIN, DEFAULT_CONFIG, DEFAULT_FACILITATOR_RETRIES, DEFAULT_FACILITATOR_URL, DEFAULT_PAYMENT_HEADER, DEFAULT_RETRY_AFTER_SECONDS, DELEGATE_PREFIX, DX402Error, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, EnvKeyAdapter, EvidenceSkipped, FACILITATOR_ADDRESSES, FacilitatorClient, KEEPALIVE_INTERVAL_MS, MAX_RETRY_AFTER_SECONDS, OPERATOR_FEE_BPS, OWSWalletAdapter, PAYMENT_HEADER_NAMES, REPLAYABLE_LEASE_REASONS, SMA_WRAP_TARGETS, SSEParser, SUPPORTED_CHAINS, TrafficStreamError, WRITER_LEASE_REASONS, X402Client, X402Error, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildSignatureBase, buildSignatureParams, buildTokenMetadata, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, caip2ToChain, chainToCAIP2, computeEscrowNonce, contentHash, convertX402Header, create402Response, createHonoMiddleware, createPaymentHeaders, createPaymentMiddleware, createSignedFetch, createX402Header, createX402V1Header, createX402V2Header, decodeBase64Utf8, decodeX402Header, delegateTarget, dereferencePointer, detectX402Version, paymentId as dx402PaymentId, ed25519ToX25519, encodeBase64Json, encodeBase64Utf8, encodeX402Header, evidenceFromHeaders, evidenceHeader, extractPaymentFromHeaders, facilitatorFetch, fetchNonce, generatePaymentOptions, getAlgorandChains, getChainById, getChainByName, getChainsByNetworkType, getChainsByToken, getCorsHeaders, getEVMChainIds, getEnabledChains, getExplorerAddressUrl, getExplorerTxUrl, getFacilitatorAddress, getNetworkType, getPaymentHeader, getSVMChains, getSuiChains, getSupportedTokens, getTokenByAddress, getTokenConfig, getXRPLChains, isAlgorandChain, isAmbiguousLeaseReason, isCAIP2Format, isChainSupported, isDelegated, isEndToEnd, isReplayableLeaseReason, isSVMChain, isSuiChain, isTokenSupported, isXRPLChain, matchesFilters, needsAccountWrap, parseEvidenceHeader, parseNetworkIdentifier, parseRetryAfterSeconds, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, paymentChallengeFrom, readFacilitatorError, recoverEvidence, replaySafeTypedData, resolveDelegation, resolveEnvelopeVersion, rpcDelegationResolver, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, toPaymentRequirementsV2, toResourceInfoV2, unseal, validateAmount, validateRecipient, wrapSignature };
+export { AMBIGUOUS_LEASE_REASONS, ANCHOR_MAX_REQUEST_BYTES, CAIP2_IDENTIFIERS, CAIP2_TO_CHAIN, ContentHashMismatch, DEFAULT_CHAIN, DEFAULT_CONFIG, DEFAULT_FACILITATOR_RETRIES, DEFAULT_FACILITATOR_URL, DEFAULT_PAYMENT_HEADER, DEFAULT_RETRY_AFTER_SECONDS, DELEGATE_PREFIX, DX402Error, ESCROW_DEPOSIT_LIMIT_USD, ESCROW_TIER_WINDOWS, EVENT_KINDS, EVIDENCE_HEADER, EnvKeyAdapter, EvidenceSkipped, FACILITATOR_ADDRESSES, FacilitatorClient, KEEPALIVE_INTERVAL_MS, MAX_RETRY_AFTER_SECONDS, OPERATOR_FEE_BPS, OWSWalletAdapter, PAYMENT_HEADER_NAMES, REPLAYABLE_LEASE_REASONS, SETTLEMENT_UNCONFIRMED, SMA_WRAP_TARGETS, SSEParser, SUPPORTED_CHAINS, TrafficStreamError, WRITER_LEASE_REASONS, X402Client, X402Error, X402_CORS_HEADERS, X402_HEADER_NAMES, ZERO_ADDRESS, anchorDigest, anchorEvidence, availableBackends, buildEscrowPreAuth, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildSignatureBase, buildSignatureParams, buildTokenMetadata, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, caip2ToChain, chainToCAIP2, computeEscrowNonce, contentHash, convertX402Header, create402Response, createHonoMiddleware, createPaymentHeaders, createPaymentMiddleware, createSignedFetch, createX402Header, createX402V1Header, createX402V2Header, decodeBase64Utf8, decodeX402Header, delegateTarget, dereferencePointer, detectX402Version, paymentId as dx402PaymentId, ed25519ToX25519, encodeBase64Json, encodeBase64Utf8, encodeX402Header, evidenceFromHeaders, evidenceHeader, extractPaymentFromHeaders, facilitatorFetch, fetchNonce, generatePaymentOptions, getAlgorandChains, getChainById, getChainByName, getChainsByNetworkType, getChainsByToken, getCorsHeaders, getEVMChainIds, getEnabledChains, getExplorerAddressUrl, getExplorerTxUrl, getFacilitatorAddress, getNetworkType, getPaymentHeader, getSVMChains, getSuiChains, getSupportedTokens, getTokenByAddress, getTokenConfig, getXRPLChains, isAlgorandChain, isAmbiguousLeaseReason, isCAIP2Format, isChainSupported, isDelegated, isEndToEnd, isReplayableLeaseReason, isSVMChain, isSettlementUnconfirmed, isSuiChain, isTokenSupported, isXRPLChain, matchesFilters, needsAccountWrap, parseEvidenceHeader, parseFacilitatorErrorBody, parseNetworkIdentifier, parseRetryAfterSeconds, parseSealed, parseTrafficEvent, payerKeyFromEvmSignature, payerKeyFromSolanaAddress, paymentChallengeFrom, readFacilitatorError, recoverEvidence, replaySafeTypedData, resolveDelegation, resolveEnvelopeVersion, rpcDelegationResolver, sealEvidence, sealEvidenceTo, sealedRoles, sellerDigestFor, signAnchorEd25519, signAnchorEvm, signRequest, signRequestWithSigner, signRequestWithWallet, streamTrafficEvents, toPaymentRequirementsV2, toResourceInfoV2, unseal, validateAmount, validateRecipient, wrapSignature };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map