uvd-x402-sdk 2.78.0 → 2.80.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@ export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAI
 import { S as SigningWalletAdapter } from './wallet-0cX9Pw2F.mjs';
 export { E as EIP3009Authorization, a as EIP3009Params } from './wallet-0cX9Pw2F.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-CYIVd4xO.mjs';
-export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, toPaymentRequirementsV2, toResourceInfoV2 } from './backend/index.mjs';
+export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, ParsedFacilitatorErrorBody, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SETTLEMENT_UNCONFIRMED, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, toPaymentRequirementsV2, toResourceInfoV2 } from './backend/index.mjs';
 
 /**
  * DX402 `durable-evidence`: recover a paid response after the fact.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { A as AlgorandPaymentPayload, C as CAIP2_IDENTIFIERS, a as CAIP2_TO_CHAI
 import { S as SigningWalletAdapter } from './wallet-0cX9Pw2F.js';
 export { E as EIP3009Authorization, a as EIP3009Params } from './wallet-0cX9Pw2F.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from './ows-DTDixPzO.js';
-export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, toPaymentRequirementsV2, toResourceInfoV2 } from './backend/index.js';
+export { AMBIGUOUS_LEASE_REASONS, DEFAULT_FACILITATOR_RETRIES, DEFAULT_RETRY_AFTER_SECONDS, FacilitatorClient, FacilitatorClientOptions, FacilitatorErrorInfo, FacilitatorFailureFields, FacilitatorFetchOptions, HonoMiddlewareOptions, MAX_RETRY_AFTER_SECONDS, ParsedFacilitatorErrorBody, PaymentAcceptance, PaymentMiddlewareOptions, PaymentPayloadV2, PaymentRequirementsV2, REPLAYABLE_LEASE_REASONS, ResourceInfoV2, SETTLEMENT_UNCONFIRMED, SettleRequestV2, VerifiedPaymentState, VerifyRequestV2, WRITER_LEASE_REASONS, WriterLeaseReason, X402_CORS_HEADERS, X402_HEADER_NAMES, buildPaymentRequirements, buildSettleRequest, buildSettleRequestForVersion, buildSettleRequestV2, buildVerifyRequest, buildVerifyRequestForVersion, buildVerifyRequestV2, create402Response, createHonoMiddleware, createPaymentMiddleware, extractPaymentFromHeaders, facilitatorFetch, getCorsHeaders, isAmbiguousLeaseReason, isReplayableLeaseReason, isSettlementUnconfirmed, parseFacilitatorErrorBody, parseRetryAfterSeconds, readFacilitatorError, resolveEnvelopeVersion, toPaymentRequirementsV2, toResourceInfoV2 } from './backend/index.js';
 
 /**
  * DX402 `durable-evidence`: recover a paid response after the fact.

package/dist/index.js

@@ -3764,6 +3764,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;
@@ -3785,15 +3786,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 = "";
@@ -3803,14 +3833,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,
@@ -3823,6 +3858,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 } : {}
   };
 }
@@ -3830,6 +3870,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 } : {}
@@ -3917,7 +3960,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
   };
@@ -3940,13 +3999,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 {
@@ -3956,9 +4023,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,
@@ -3971,7 +4044,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) {
@@ -4644,16 +4717,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));
@@ -4728,10 +4808,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();
@@ -4787,6 +4864,7 @@ exports.OPERATOR_FEE_BPS = OPERATOR_FEE_BPS;
 exports.OWSWalletAdapter = OWSWalletAdapter;
 exports.PAYMENT_HEADER_NAMES = PAYMENT_HEADER_NAMES;
 exports.REPLAYABLE_LEASE_REASONS = REPLAYABLE_LEASE_REASONS;
+exports.SETTLEMENT_UNCONFIRMED = SETTLEMENT_UNCONFIRMED;
 exports.SMA_WRAP_TARGETS = SMA_WRAP_TARGETS;
 exports.SSEParser = SSEParser;
 exports.SUPPORTED_CHAINS = SUPPORTED_CHAINS;
@@ -4867,12 +4945,14 @@ exports.isDelegated = isDelegated;
 exports.isEndToEnd = isEndToEnd;
 exports.isReplayableLeaseReason = isReplayableLeaseReason;
 exports.isSVMChain = isSVMChain;
+exports.isSettlementUnconfirmed = isSettlementUnconfirmed;
 exports.isSuiChain = isSuiChain;
 exports.isTokenSupported = isTokenSupported;
 exports.isXRPLChain = isXRPLChain;
 exports.matchesFilters = matchesFilters;
 exports.needsAccountWrap = needsAccountWrap;
 exports.parseEvidenceHeader = parseEvidenceHeader;
+exports.parseFacilitatorErrorBody = parseFacilitatorErrorBody;
 exports.parseNetworkIdentifier = parseNetworkIdentifier;
 exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
 exports.parseSealed = parseSealed;