@agent-score/commerce 1.8.0 → 2.0.0

package/dist/payment/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/payment/index.ts
 var payment_exports = {};
 __export(payment_exports, {
+  RAIL_SPEC_DEFAULTS: () => RAIL_SPEC_DEFAULTS,
   SETTLEMENT_OVERRIDES_HEADER: () => SETTLEMENT_OVERRIDES_HEADER,
   USDC: () => USDC,
   X402_SUPPORTED_BASE_NETWORKS: () => X402_SUPPORTED_BASE_NETWORKS,
@@ -29,11 +30,19 @@ __export(payment_exports, {
   buildPaymentHeaders: () => buildPaymentHeaders,
   buildPaymentRequestBlob: () => buildPaymentRequestBlob,
   buildX402AcceptsFor402: () => buildX402AcceptsFor402,
+  classifyOrchestrationError: () => classifyOrchestrationError,
   classifyX402SettleResult: () => classifyX402SettleResult,
   createMppxServer: () => createMppxServer,
   createX402Server: () => createX402Server,
+  detectRailFromHeaders: () => detectRailFromHeaders,
   dispatchSettlementByNetwork: () => dispatchSettlementByNetwork,
   extractPaymentSigner: () => extractPaymentSigner,
+  extractPaymentSignerFromAuth: () => extractPaymentSignerFromAuth,
+  extractSignerForPrecheck: () => extractSignerForPrecheck,
+  formatUsdCents: () => formatUsdCents,
+  lazyMppxServer: () => lazyMppxServer,
+  lazyX402Server: () => lazyX402Server,
+  loadSolanaFeePayer: () => loadSolanaFeePayer,
   lookupRail: () => lookupRail,
   networkFamily: () => networkFamily,
   networks: () => networks,
@@ -43,11 +52,14 @@ __export(payment_exports, {
   rails: () => rails,
   readX402PaymentHeader: () => readX402PaymentHeader,
   registerX402SchemesV1V2: () => registerX402SchemesV1V2,
+  resolveRecipient: () => resolveRecipient,
   settlementOverrideHeader: () => settlementOverrideHeader,
+  usdToAtomic: () => usdToAtomic,
   validateX402NetworkConfig: () => validateX402NetworkConfig,
   verifyX402Request: () => verifyX402Request,
   wrapSolanaChargeWithFinalizedBlockhash: () => wrapSolanaChargeWithFinalizedBlockhash,
-  wwwAuthenticateHeader: () => wwwAuthenticateHeader
+  wwwAuthenticateHeader: () => wwwAuthenticateHeader,
+  zeroAmountCarveOut: () => zeroAmountCarveOut
 });
 module.exports = __toCommonJS(payment_exports);
 
@@ -168,49 +180,116 @@ function lookupRail(name) {
 }
 
 // src/payment/directive.ts
-function buildPaymentRequestBlob(input) {
-  const railDef = input.rail ? lookupRail(input.rail) : void 0;
-  const decimals = input.decimals ?? railDef?.decimals ?? 6;
-  const currency = input.currency ?? railDef?.currency ?? "usd";
-  const chainId = input.chainId ?? railDef?.chainId;
-  const amountNum = typeof input.amountUsd === "string" ? Number(input.amountUsd) : input.amountUsd;
-  const amountRaw = BigInt(Math.round(amountNum * 10 ** decimals)).toString();
-  const blob = { amount: amountRaw, currency, decimals };
-  if (input.recipient) blob.recipient = input.recipient;
+function buildPaymentRequestBlob({
+  rail,
+  amountUsd,
+  currency,
+  decimals,
+  recipient,
+  chainId,
+  networkId
+}) {
+  const railDef = rail ? lookupRail(rail) : void 0;
+  const decimalsResolved = decimals ?? railDef?.decimals ?? 6;
+  const currencyResolved = currency ?? railDef?.currency ?? "usd";
+  const chainIdResolved = chainId ?? railDef?.chainId;
+  const amountNum = typeof amountUsd === "string" ? Number(amountUsd) : amountUsd;
+  const amountRaw = BigInt(Math.round(amountNum * 10 ** decimalsResolved)).toString();
+  const blob = { amount: amountRaw, currency: currencyResolved, decimals: decimalsResolved };
+  if (recipient) blob.recipient = recipient;
   const methodDetails = {};
-  if (chainId !== void 0) methodDetails.chainId = chainId;
-  if (input.networkId) methodDetails.networkId = input.networkId;
+  if (chainIdResolved !== void 0) methodDetails.chainId = chainIdResolved;
+  if (networkId) methodDetails.networkId = networkId;
   if (Object.keys(methodDetails).length > 0) blob.methodDetails = methodDetails;
   return Buffer.from(JSON.stringify(blob)).toString("base64url");
 }
-function paymentDirective(input) {
-  const railDef = input.rail ? lookupRail(input.rail) : void 0;
-  const method = input.method ?? railDef?.method ?? "unknown";
-  const intent = input.intent ?? "charge";
-  const expires = input.expires ?? new Date(Date.now() + 5 * 60 * 1e3).toISOString();
-  return `Payment id="${input.id}", realm="${input.realm}", method="${method}", intent="${intent}", expires="${expires}", request="${input.request}"`;
+function paymentDirective({
+  rail,
+  id,
+  realm,
+  method,
+  intent,
+  expires,
+  request
+}) {
+  const railDef = rail ? lookupRail(rail) : void 0;
+  const methodResolved = method ?? railDef?.method ?? "unknown";
+  const intentResolved = intent ?? "charge";
+  const expiresResolved = expires ?? new Date(Date.now() + 5 * 60 * 1e3).toISOString();
+  return `Payment id="${id}", realm="${realm}", method="${methodResolved}", intent="${intentResolved}", expires="${expiresResolved}", request="${request}"`;
 }
-function buildPaymentDirective(input) {
+function buildPaymentDirective({
+  rail,
+  id,
+  realm,
+  amountUsd,
+  currency,
+  decimals,
+  recipient,
+  chainId,
+  networkId,
+  method,
+  intent,
+  expires
+}) {
   const request = buildPaymentRequestBlob({
-    rail: input.rail,
-    amountUsd: input.amountUsd,
-    currency: input.currency,
-    decimals: input.decimals,
-    recipient: input.recipient,
-    chainId: input.chainId,
-    networkId: input.networkId
+    rail,
+    amountUsd,
+    currency,
+    decimals,
+    recipient,
+    chainId,
+    networkId
   });
   return paymentDirective({
-    rail: input.rail,
-    id: input.id,
-    realm: input.realm,
-    method: input.method,
-    intent: input.intent,
-    expires: input.expires,
+    rail,
+    id,
+    realm,
+    method,
+    intent,
+    expires,
     request
   });
 }
 
+// src/payment/rail_spec.ts
+async function resolveRecipient(r) {
+  if (typeof r === "string") return r;
+  return Promise.resolve(r());
+}
+var RAIL_SPEC_DEFAULTS = {
+  tempo: {
+    network: "tempo-mainnet",
+    chainId: 4217,
+    token: USDC.tempo.mainnet.address,
+    symbol: "USDC.e",
+    decimals: 6,
+    testnet: false,
+    recommend: "both"
+  },
+  x402Base: {
+    network: "eip155:8453",
+    chainId: 8453,
+    token: USDC.base.mainnet.address,
+    symbol: "USDC",
+    decimals: 6,
+    mode: "exact"
+  },
+  solanaMpp: {
+    network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+    token: USDC.solana.mainnet.mint,
+    symbol: "USDC",
+    decimals: 6
+  },
+  stripe: {
+    rails: ["card", "link", "shared_payment_token"]
+  },
+  tempoSession: {
+    currency: USDC.tempo.mainnet.address,
+    testnet: false
+  }
+};
+
 // src/payment/x402.ts
 function registerX402SchemesV1V2(server, network, scheme) {
   server.register(network, scheme);
@@ -228,7 +307,8 @@ async function createX402Server(opts = {}) {
     );
   }
   let facilitator;
-  if (opts.facilitator === "coinbase") {
+  const facilitatorChoice = opts.facilitator ?? (process.env.CDP_API_KEY_ID && process.env.CDP_API_KEY_SECRET ? "coinbase" : "http");
+  if (facilitatorChoice === "coinbase") {
     const cb = await dynamicImport("@coinbase/x402");
     if (!cb?.facilitator) {
       throw new Error(
@@ -236,10 +316,10 @@ async function createX402Server(opts = {}) {
       );
     }
     facilitator = new x402Core.HTTPFacilitatorClient(cb.facilitator);
-  } else if (opts.facilitator === void 0 || opts.facilitator === "http") {
+  } else if (facilitatorChoice === "http") {
     facilitator = new x402Core.HTTPFacilitatorClient();
   } else {
-    facilitator = opts.facilitator;
+    facilitator = facilitatorChoice;
   }
   const server = new x402Core.x402ResourceServer(facilitator);
   let evmExactModule = null;
@@ -349,44 +429,95 @@ function classifyX402SettleResult(result) {
       };
   }
 }
-async function processX402Settle(input) {
-  const server = input.x402Server;
+function classifyOrchestrationError(err) {
+  let msg;
+  if (err instanceof Error) {
+    msg = err.message;
+  } else if (typeof err === "string") {
+    msg = err;
+  } else {
+    return null;
+  }
+  const msgLower = msg.toLowerCase();
+  if (msgLower.includes("x402version") || msgLower.includes("invalid payment") || msgLower.includes("unsupported x402")) {
+    return {
+      status: 400,
+      code: "payment_proof_invalid",
+      message: "Payment credential is malformed or uses an unsupported version",
+      nextSteps: {
+        action: "regenerate_payment_credential",
+        user_message: "The payment credential is malformed or uses an unsupported version. Regenerate from a fresh 402 challenge and re-sign."
+      }
+    };
+  }
+  if (msgLower.includes("stripe") || msgLower.includes("facilitator") || msgLower.includes("cdp")) {
+    return {
+      status: 503,
+      code: "payment_provider_unavailable",
+      message: "Payment provider returned an error",
+      nextSteps: {
+        action: "retry_or_swap_method",
+        retry_after_seconds: 10,
+        user_message: "Transient payment-provider error. Retry in a few seconds, or pick a different rail from the 402 challenge."
+      }
+    };
+  }
+  return null;
+}
+async function processX402Settle({
+  x402Server,
+  payload,
+  resourceConfig,
+  resourceMeta,
+  extension,
+  transportContext
+}) {
+  const server = x402Server;
   let builtRequirements;
   try {
-    builtRequirements = await server.buildPaymentRequirements(input.resourceConfig);
+    builtRequirements = await server.buildPaymentRequirements(resourceConfig);
   } catch (err) {
+    console.warn("[x402_settle] build_requirements failed:", err instanceof Error ? err.message : err);
     return { success: false, phase: "facilitator_error", step: "build_requirements", error: err };
   }
   const matchedRequirement = builtRequirements[0];
   if (!matchedRequirement) {
     return { success: false, phase: "no_requirements", reason: "x402Server.buildPaymentRequirements returned empty" };
   }
-  const transportContext = input.transportContext ?? (() => {
-    const path = new URL(input.resourceMeta.url).pathname;
+  const resolvedTransportContext = transportContext ?? (() => {
+    const path = new URL(resourceMeta.url).pathname;
     return { method: "POST", adapter: { getPath: () => path }, routePattern: path };
   })();
   let enrichedExt;
   try {
-    enrichedExt = input.extension !== void 0 ? server.enrichExtensions(input.extension, transportContext) : void 0;
+    enrichedExt = extension !== void 0 ? server.enrichExtensions(extension, resolvedTransportContext) : void 0;
   } catch (err) {
+    console.warn("[x402_settle] enrich_extensions failed:", err instanceof Error ? err.message : err);
     return { success: false, phase: "facilitator_error", step: "enrich_extensions", error: err };
   }
   let verifyResult;
   try {
-    verifyResult = await server.processPaymentRequest(
-      input.payload,
-      input.resourceConfig,
-      input.resourceMeta,
-      enrichedExt
+    verifyResult = await server.verifyPayment(
+      payload,
+      matchedRequirement,
+      enrichedExt,
+      resolvedTransportContext
     );
   } catch (err) {
-    return { success: false, phase: "facilitator_error", step: "process_payment_request", error: err };
+    console.warn("[x402_settle] verify_payment failed:", err instanceof Error ? err.message : err);
+    return { success: false, phase: "facilitator_error", step: "verify_payment", error: err };
   }
-  if (!verifyResult.success) {
+  const verifyOk = verifyResult.isValid === true || verifyResult.success === true;
+  if (!verifyOk) {
     return { success: false, phase: "verify_failed", verifyResult };
   }
   try {
-    const settleResult = await server.settlePayment(input.payload, matchedRequirement);
+    const settleResult = await server.settlePayment(
+      payload,
+      matchedRequirement,
+      enrichedExt,
+      resolvedTransportContext
+    );
     const paymentResponseHeader = settleResult ? Buffer.from(JSON.stringify(settleResult)).toString("base64") : void 0;
     return {
       success: true,
@@ -405,10 +536,10 @@ var X402_SUPPORTED_BASE_NETWORKS = /* @__PURE__ */ new Set([
   networks.base.mainnet.caip2,
   networks.base.sepolia.caip2
 ]);
-function validateX402NetworkConfig(input) {
-  if (!X402_SUPPORTED_BASE_NETWORKS.has(input.baseNetwork)) {
+function validateX402NetworkConfig({ baseNetwork }) {
+  if (!X402_SUPPORTED_BASE_NETWORKS.has(baseNetwork)) {
     throw new Error(
-      `X402_BASE_NETWORK=${input.baseNetwork} is not supported. Use one of: ${[...X402_SUPPORTED_BASE_NETWORKS].join(", ")}`
+      `X402_BASE_NETWORK=${baseNetwork} is not supported. Use one of: ${[...X402_SUPPORTED_BASE_NETWORKS].join(", ")}`
     );
   }
 }
@@ -424,8 +555,12 @@ function regenerateBody(message, userMessage) {
     }
   };
 }
-async function verifyX402Request(input) {
-  const headerValue = input.request.headers.get("payment-signature") ?? input.request.headers.get("x-payment");
+async function verifyX402Request({
+  request,
+  isCachedAddress,
+  acceptedNetwork
+}) {
+  const headerValue = request.headers.get("payment-signature") ?? request.headers.get("x-payment");
   if (!headerValue) {
     return {
       ok: false,
@@ -451,13 +586,13 @@ async function verifyX402Request(input) {
   }
   const signedNetwork = payload.accepted?.network;
   const signedPayTo = payload.accepted?.payTo;
-  if (!signedNetwork || signedNetwork !== input.acceptedNetwork) {
+  if (!signedNetwork || signedNetwork !== acceptedNetwork) {
     if (signedNetwork && signedNetwork.toLowerCase().startsWith("solana:")) {
       return {
         ok: false,
         status: 400,
         body: regenerateBody(
-          `x402 on ${signedNetwork} is not accepted; Solana payments must use the \`solana/charge\` rail advertised in the 402 challenge. This server accepts x402 on ${input.acceptedNetwork} only.`,
+          `x402 on ${signedNetwork} is not accepted; Solana payments must use the \`solana/charge\` rail advertised in the 402 challenge. This server accepts x402 on ${acceptedNetwork} only.`,
           "Solana payments are not accepted over x402 at this merchant. Pick the `solana/charge` rail from the 402 challenge and re-sign."
         )
       };
@@ -466,7 +601,7 @@ async function verifyX402Request(input) {
       ok: false,
       status: 400,
       body: regenerateBody(
-        `Unsupported x402 network ${signedNetwork ?? "<missing>"}; this server accepts ${input.acceptedNetwork}.`,
+        `Unsupported x402 network ${signedNetwork ?? "<missing>"}; this server accepts ${acceptedNetwork}.`,
         "The credential signed for an unsupported network. Pick the accepted network from the 402 challenge and re-sign."
       )
     };
@@ -482,7 +617,7 @@ async function verifyX402Request(input) {
       )
     };
   }
-  if (!await input.isCachedAddress(signedPayTo)) {
+  if (!await isCachedAddress(signedPayTo)) {
     return {
       ok: false,
       status: 400,
@@ -496,7 +631,11 @@ async function verifyX402Request(input) {
 }
 
 // src/stripe-multichain/mppx_stripe.ts
-async function createMppxStripe(input) {
+async function createMppxStripe({
+  profileId,
+  secretKey,
+  paymentMethodTypes
+}) {
   const moduleName = "mppx/server";
   const mppx = await import(moduleName).catch(() => null);
   if (!mppx?.stripe?.charge) {
@@ -505,80 +644,130 @@ async function createMppxStripe(input) {
     );
   }
   return mppx.stripe.charge({
-    networkId: input.profileId,
-    paymentMethodTypes: input.paymentMethodTypes ?? ["card", "link"],
-    secretKey: input.secretKey
+    networkId: profileId,
+    paymentMethodTypes: paymentMethodTypes ?? ["card", "link"],
+    secretKey
   });
 }
 
 // src/payment/mppx_server.ts
-async function createMppxServer(opts) {
+function isStripeRailSpec(s) {
+  return !("recipient" in s);
+}
+function isTempoSessionRailSpec(s) {
+  return "escrowContract" in s && "store" in s;
+}
+function isSolanaMppRailSpec(s) {
+  if (!("recipient" in s)) return false;
+  if ("escrowContract" in s) return false;
+  if ("rpcUrl" in s || "tokenProgram" in s) return true;
+  return s.network?.startsWith("solana:") ?? false;
+}
+function solanaNetworkFromCAIP2(caip2) {
+  if (caip2 === networks.solana.devnet.caip2) return "devnet";
+  return "mainnet-beta";
+}
+function solanaDefaultRpcUrl(network) {
+  if (network === "mainnet-beta") return "https://api.mainnet-beta.solana.com";
+  if (network === "devnet") return "https://api.devnet.solana.com";
+  return "http://localhost:8899";
+}
+async function createMppxServer({
+  rails: rails2,
+  methods: extraMethods,
+  secretKey
+}) {
   const mppx = await dynamicImport2("mppx/server");
   if (!mppx?.Mppx?.create) {
     throw new Error("mppx not installed \u2014 `npm install mppx` to use createMppxServer.");
   }
-  const methods = [...opts.methods ?? []];
-  if (opts.rails?.tempo) {
-    if (!mppx.tempo?.charge) {
-      throw new Error("mppx.tempo.charge not available \u2014 check installed mppx version.");
+  const methods = [...extraMethods ?? []];
+  for (const [name, spec] of Object.entries(rails2 ?? {})) {
+    if (isStripeRailSpec(spec)) {
+      methods.push(await registerStripe(spec));
+      continue;
+    }
+    if (isTempoSessionRailSpec(spec)) {
+      methods.push(await registerTempoSession(mppx, spec));
+      continue;
     }
-    const t = opts.rails.tempo;
-    const defaultCurrency = t.testnet ? USDC.tempo.testnet.address : USDC.tempo.mainnet.address;
-    methods.push(
-      mppx.tempo.charge({
-        currency: t.currency ?? defaultCurrency,
-        recipient: t.recipient,
-        testnet: t.testnet ?? false
-      })
+    if (isSolanaMppRailSpec(spec)) {
+      methods.push(await registerSolana(spec));
+      continue;
+    }
+    methods.push(registerTempo(mppx, spec, name));
+  }
+  return mppx.Mppx.create({ methods, secretKey });
+}
+function registerTempo(mppx, spec, _name) {
+  if (!mppx.tempo?.charge) {
+    throw new Error("mppx.tempo.charge not available \u2014 check installed mppx version.");
+  }
+  const defaultCurrency = spec.testnet ? USDC.tempo.testnet.address : USDC.tempo.mainnet.address;
+  if (typeof spec.recipient !== "string") {
+    throw new TypeError(
+      "createMppxServer: TempoRailSpec requires a string recipient (per-order factories not supported here)."
     );
   }
-  if (opts.rails?.tempo_session) {
-    if (!mppx.tempo?.session) {
-      throw new Error(
-        "mppx.tempo.session not available \u2014 your mppx version may not support sessions yet. Upgrade with `npm install mppx@latest`."
-      );
-    }
-    const s = opts.rails.tempo_session;
-    const defaultCurrency = s.testnet ? USDC.tempo.testnet.address : USDC.tempo.mainnet.address;
-    methods.push(
-      mppx.tempo.session({
-        currency: s.currency ?? defaultCurrency,
-        recipient: s.recipient,
-        escrowContract: s.escrowContract,
-        store: s.store,
-        testnet: s.testnet ?? false,
-        ...s.chains ? { chains: s.chains } : {}
-      })
+  return mppx.tempo.charge({
+    currency: spec.token ?? defaultCurrency,
+    recipient: spec.recipient,
+    testnet: spec.testnet ?? false
+  });
+}
+async function registerTempoSession(mppx, spec) {
+  if (!mppx.tempo?.session) {
+    throw new Error(
+      "mppx.tempo.session not available \u2014 your mppx version may not support sessions yet. Upgrade with `npm install mppx@latest`."
     );
   }
-  if (opts.rails?.solana) {
-    const solanaMpp = await dynamicImport2("@solana/mpp/server");
-    if (!solanaMpp?.charge) {
-      throw new Error(
-        "@solana/mpp not installed \u2014 `npm install @solana/mpp @solana/kit` to use the solana rail."
-      );
-    }
-    const s = opts.rails.solana;
-    const network = s.network ?? "mainnet-beta";
-    const defaultMint = network === "mainnet-beta" ? USDC.solana.mainnet.mint : USDC.solana.devnet.mint;
-    const defaultDecimals = network === "mainnet-beta" ? USDC.solana.mainnet.decimals : USDC.solana.devnet.decimals;
-    const baseMethod = solanaMpp.charge({
-      recipient: s.recipient,
-      currency: s.currency ?? defaultMint,
-      decimals: s.decimals ?? defaultDecimals,
-      network,
-      ...s.rpcUrl ? { rpcUrl: s.rpcUrl } : {},
-      ...s.signer ? { signer: s.signer } : {},
-      ...s.tokenProgram ? { tokenProgram: s.tokenProgram } : {}
-    });
-    const rpcUrl = s.rpcUrl ?? (network === "mainnet-beta" ? "https://api.mainnet-beta.solana.com" : network === "devnet" ? "https://api.devnet.solana.com" : "http://localhost:8899");
-    methods.push(wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl));
+  const defaultCurrency = spec.testnet ? USDC.tempo.testnet.address : USDC.tempo.mainnet.address;
+  return mppx.tempo.session({
+    currency: spec.currency ?? defaultCurrency,
+    recipient: await resolveRecipient(spec.recipient),
+    escrowContract: spec.escrowContract,
+    store: spec.store,
+    testnet: spec.testnet ?? false,
+    ...spec.chains ? { chains: spec.chains } : {}
+  });
+}
+async function registerSolana(spec) {
+  const solanaMpp = await dynamicImport2("@solana/mpp/server");
+  if (!solanaMpp?.charge) {
+    throw new Error(
+      "@solana/mpp not installed \u2014 `npm install @solana/mpp @solana/kit` to use the solana rail."
+    );
   }
-  if (opts.rails?.stripe) {
-    const stripeMethod = await createMppxStripe(opts.rails.stripe);
-    methods.push(stripeMethod);
+  const network = solanaNetworkFromCAIP2(spec.network);
+  const defaultMint = network === "mainnet-beta" ? USDC.solana.mainnet.mint : USDC.solana.devnet.mint;
+  const defaultDecimals = network === "mainnet-beta" ? USDC.solana.mainnet.decimals : USDC.solana.devnet.decimals;
+  if (typeof spec.recipient !== "string") {
+    throw new TypeError(
+      "createMppxServer: SolanaMppRailSpec requires a string recipient (per-order factories not supported here)."
+    );
   }
-  return mppx.Mppx.create({ methods, secretKey: opts.secretKey });
+  const baseMethod = solanaMpp.charge({
+    recipient: spec.recipient,
+    currency: spec.token ?? defaultMint,
+    decimals: spec.decimals ?? defaultDecimals,
+    network,
+    ...spec.rpcUrl ? { rpcUrl: spec.rpcUrl } : {},
+    ...spec.signer ? { signer: spec.signer } : {},
+    ...spec.tokenProgram ? { tokenProgram: spec.tokenProgram } : {}
+  });
+  return wrapSolanaChargeWithFinalizedBlockhash(baseMethod, spec.rpcUrl ?? solanaDefaultRpcUrl(network));
+}
+async function registerStripe(spec) {
+  if (!spec.profileId || !spec.secretKey) {
+    throw new Error(
+      "createMppxServer: StripeRailSpec requires both profileId and secretKey."
+    );
+  }
+  return createMppxStripe({
+    profileId: spec.profileId,
+    secretKey: spec.secretKey,
+    paymentMethodTypes: spec.paymentMethodTypes
+  });
 }
 async function dynamicImport2(moduleName) {
   try {
@@ -620,6 +809,29 @@ function wrapSolanaChargeWithFinalizedBlockhash(baseMethod, rpcUrl) {
 }
 
 // src/payment/dispatch.ts
+function detectRailFromHeaders(headers) {
+  const get = (name) => {
+    if (headers instanceof Headers) {
+      return headers.get(name) ?? "";
+    }
+    const lower = name.toLowerCase();
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() === lower) {
+        if (v === void 0 || v === null) return "";
+        return Array.isArray(v) ? v[0] ?? "" : v;
+      }
+    }
+    return "";
+  };
+  const auth = get("authorization");
+  if (auth.toLowerCase().startsWith("payment ")) {
+    return "mpp";
+  }
+  if (get("payment-signature") || get("x-payment")) {
+    return "x402";
+  }
+  return null;
+}
 async function dispatchSettlementByNetwork(payload, handlers) {
   const network = payload.accepted.network;
   if (network.startsWith("eip155:")) {
@@ -652,37 +864,45 @@ function aliasAmountFields(accepts) {
     return e;
   });
 }
-function paymentRequiredHeader(input) {
-  return Buffer.from(JSON.stringify(input)).toString("base64");
+function paymentRequiredHeader({
+  x402Version,
+  accepts,
+  resource
+}) {
+  return Buffer.from(JSON.stringify({ x402Version, accepts, ...resource ? { resource } : {} })).toString("base64");
 }
 
 // src/payment/headers.ts
-function buildPaymentHeaders(input) {
-  const directives = input.rails.map((rail) => {
-    const directiveInput = {
-      id: `${input.orderId}-${rail.rail}`,
-      realm: input.realm,
+function buildPaymentHeaders({
+  rails: rails2,
+  orderId,
+  realm,
+  x402
+}) {
+  const directives = rails2.map(
+    (rail) => buildPaymentDirective({
+      id: `${orderId}-${rail.rail}`,
+      realm,
       rail: rail.rail,
-      amountUsd: rail.amountUsd
-    };
-    if (rail.recipient !== void 0) directiveInput.recipient = rail.recipient;
-    if (rail.networkId !== void 0) directiveInput.networkId = rail.networkId;
-    if (rail.chainId !== void 0) directiveInput.chainId = rail.chainId;
-    if (rail.currency !== void 0) directiveInput.currency = rail.currency;
-    if (rail.decimals !== void 0) directiveInput.decimals = rail.decimals;
-    if (rail.method !== void 0) directiveInput.method = rail.method;
-    if (rail.intent !== void 0) directiveInput.intent = rail.intent;
-    if (rail.expires !== void 0) directiveInput.expires = rail.expires;
-    return buildPaymentDirective(directiveInput);
-  });
+      amountUsd: rail.amountUsd,
+      ...rail.recipient !== void 0 ? { recipient: rail.recipient } : {},
+      ...rail.networkId !== void 0 ? { networkId: rail.networkId } : {},
+      ...rail.chainId !== void 0 ? { chainId: rail.chainId } : {},
+      ...rail.currency !== void 0 ? { currency: rail.currency } : {},
+      ...rail.decimals !== void 0 ? { decimals: rail.decimals } : {},
+      ...rail.method !== void 0 ? { method: rail.method } : {},
+      ...rail.intent !== void 0 ? { intent: rail.intent } : {},
+      ...rail.expires !== void 0 ? { expires: rail.expires } : {}
+    })
+  );
   const result = {
     "www-authenticate": wwwAuthenticateHeader(directives)
   };
-  if (input.x402) {
+  if (x402) {
     result["PAYMENT-REQUIRED"] = paymentRequiredHeader({
-      x402Version: input.x402.version ?? 2,
-      accepts: input.x402.accepts,
-      ...input.x402.resource ? { resource: input.x402.resource } : {}
+      x402Version: x402.version ?? 2,
+      accepts: x402.accepts,
+      ...x402.resource ? { resource: x402.resource } : {}
     });
   }
   return result;
@@ -690,15 +910,20 @@ function buildPaymentHeaders(input) {
 
 // src/payment/idempotency.ts
 var SERVER_IDEMPOTENCY_KEY_MAX = 200;
-function buildIdempotencyKey(input) {
-  const prefix = input.prefix ? `${input.prefix}-` : "";
-  if (input.paymentIntentId) {
-    const key = `${prefix}${input.paymentIntentId}`;
+function buildIdempotencyKey({
+  paymentIntentId,
+  orderId,
+  amountCents,
+  prefix
+}) {
+  const prefixPart = prefix ? `${prefix}-` : "";
+  if (paymentIntentId) {
+    const key = `${prefixPart}${paymentIntentId}`;
     return clampKey(key);
   }
-  if (input.orderId) {
-    const amountSuffix = input.amountCents !== void 0 ? `-${input.amountCents}` : "";
-    const key = `${prefix}pi-${input.orderId}${amountSuffix}`;
+  if (orderId) {
+    const amountSuffix = amountCents !== void 0 ? `-${amountCents}` : "";
+    const key = `${prefixPart}pi-${orderId}${amountSuffix}`;
     return clampKey(key);
   }
   return void 0;
@@ -784,17 +1009,218 @@ async function extractPaymentSigner(request, x402PaymentHeader) {
   }
   return null;
 }
+async function extractPaymentSignerFromAuth(authHeader, x402PaymentHeader) {
+  const request = new Request("http://internal.gate/", {
+    headers: authHeader ? { authorization: authHeader } : {}
+  });
+  return extractPaymentSigner(request, x402PaymentHeader);
+}
 function readX402PaymentHeader(request) {
   return request.headers.get("payment-signature") ?? request.headers.get("x-payment") ?? void 0;
 }
+function lowerHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = v;
+  return out;
+}
+async function extractSignerForPrecheck(headers) {
+  const lower = lowerHeaders(headers);
+  const x402 = lower["payment-signature"] ?? lower["x-payment"];
+  if (x402) {
+    const signer = await extractPaymentSignerFromAuth(void 0, x402);
+    if (signer !== null) return signer;
+  }
+  const authorization = lower["authorization"];
+  if (authorization && authorization.toLowerCase().startsWith("payment ")) {
+    return await extractPaymentSignerFromAuth(authorization);
+  }
+  return null;
+}
 
 // src/payment/settlement_override.ts
 var SETTLEMENT_OVERRIDES_HEADER = "Settlement-Overrides";
 function settlementOverrideHeader(overrides) {
   return { name: SETTLEMENT_OVERRIDES_HEADER, value: JSON.stringify(overrides) };
 }
+
+// src/payment/amounts.ts
+function usdToAtomic(usd, opts) {
+  const { decimals } = opts;
+  if (!Number.isInteger(decimals) || decimals < 0) {
+    throw new RangeError(`decimals must be a non-negative integer, got ${decimals}`);
+  }
+  if (typeof usd === "number") {
+    if (!Number.isFinite(usd)) {
+      throw new RangeError(`usd must be finite, got ${usd}`);
+    }
+    if (usd < 0) {
+      throw new RangeError(`usd must be non-negative, got ${usd}`);
+    }
+  }
+  const s = (typeof usd === "number" ? usd.toString() : usd).trim();
+  if (s.startsWith("-")) {
+    throw new RangeError(`usd must be non-negative, got ${s}`);
+  }
+  if (s === "NaN" || s === "Infinity") {
+    throw new RangeError(`usd must be finite, got ${s}`);
+  }
+  const match = /^(\d*)(?:\.(\d*))?$/.exec(s);
+  if (!match || match[1] === "" && (match[2] === void 0 || match[2] === "")) {
+    throw new SyntaxError(`invalid usd value: ${JSON.stringify(usd)}`);
+  }
+  const intPart = match[1] || "0";
+  const fracPart = match[2] ?? "";
+  if (fracPart.length <= decimals) {
+    return BigInt(intPart + fracPart.padEnd(decimals, "0"));
+  }
+  const kept = fracPart.slice(0, decimals);
+  const roundDigit = fracPart[decimals];
+  let result = BigInt(intPart + kept);
+  if (roundDigit >= "5") {
+    result += 1n;
+  }
+  return result;
+}
+function formatUsdCents(cents) {
+  return (cents / 100).toFixed(2);
+}
+
+// src/payment/zero-settle.ts
+var EVM_RE = /^0x[0-9a-fA-F]{40}$/;
+var SOLANA_BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+var NULL_RESULT = {
+  signerAddress: null,
+  signerNetwork: null,
+  txHash: null
+};
+function zeroAmountCarveOut({
+  rail,
+  payload,
+  authorizationHeader
+}) {
+  if (rail === "x402-base") {
+    return x402SignerFromPayload(payload);
+  }
+  if (rail === "tempo" || rail === "solana") {
+    return mppSignerFromAuth(authorizationHeader);
+  }
+  return NULL_RESULT;
+}
+function x402SignerFromPayload(payload) {
+  if (!payload || typeof payload !== "object") return NULL_RESULT;
+  const inner = payload.payload;
+  if (!inner || typeof inner !== "object") return NULL_RESULT;
+  const authorization = inner.authorization;
+  if (!authorization || typeof authorization !== "object") return NULL_RESULT;
+  const fromAddr = authorization.from;
+  if (typeof fromAddr !== "string" || !EVM_RE.test(fromAddr)) return NULL_RESULT;
+  return {
+    signerAddress: fromAddr.toLowerCase(),
+    signerNetwork: "evm",
+    txHash: null
+  };
+}
+function mppSignerFromAuth(authorizationHeader) {
+  if (typeof authorizationHeader !== "string") return NULL_RESULT;
+  if (!authorizationHeader.toLowerCase().startsWith("payment ")) return NULL_RESULT;
+  const token = authorizationHeader.slice("payment ".length).trim();
+  if (!token) return NULL_RESULT;
+  let credential;
+  try {
+    credential = JSON.parse(atob(token));
+  } catch {
+    return NULL_RESULT;
+  }
+  if (!credential || typeof credential !== "object") return NULL_RESULT;
+  let source = credential.source;
+  if (typeof source !== "string") {
+    const challenge = credential.challenge;
+    if (challenge && typeof challenge === "object") {
+      source = challenge.source;
+    }
+  }
+  if (typeof source !== "string") return NULL_RESULT;
+  const parts = source.split(":");
+  if (parts.length < 4 || parts[0] !== "did" || parts[1] !== "pkh") return NULL_RESULT;
+  const family = parts[2];
+  const addr = parts[parts.length - 1] ?? "";
+  if (family === "eip155" && EVM_RE.test(addr)) {
+    return { signerAddress: addr.toLowerCase(), signerNetwork: "evm", txHash: null };
+  }
+  if (family === "solana" && SOLANA_BASE58_RE.test(addr)) {
+    return { signerAddress: addr, signerNetwork: "solana", txHash: null };
+  }
+  return NULL_RESULT;
+}
+
+// src/payment/lazy.ts
+function x402RailName(spec) {
+  const network = spec.network ?? "eip155:8453";
+  if (network === "eip155:8453") return "x402-base-mainnet";
+  if (network === "eip155:84532") return "x402-base-sepolia";
+  throw new Error(
+    `lazyX402Server: unsupported X402BaseRailSpec.network=${JSON.stringify(network)}`
+  );
+}
+function lazyX402Server(opts) {
+  const { spec, cdpApiKeyId, cdpApiKeySecret } = opts;
+  const railName = x402RailName(spec);
+  const useCdp = Boolean(cdpApiKeyId && cdpApiKeySecret);
+  const facilitator = useCdp ? "coinbase" : "http";
+  let cached;
+  let pending;
+  return async () => {
+    if (cached !== void 0) return cached;
+    if (pending !== void 0) return pending;
+    pending = (async () => {
+      const server = await createX402Server({ facilitator, rails: [railName] });
+      cached = server;
+      pending = void 0;
+      return server;
+    })();
+    return pending;
+  };
+}
+function lazyMppxServer(opts) {
+  const { rails: rails2, secretKey } = opts;
+  let cached;
+  let pending;
+  return async () => {
+    if (cached !== void 0) return cached;
+    if (pending !== void 0) return pending;
+    pending = (async () => {
+      const server = await createMppxServer({ secretKey, rails: rails2 });
+      cached = server;
+      pending = void 0;
+      return server;
+    })();
+    return pending;
+  };
+}
+
+// src/payment/solana.ts
+async function loadSolanaFeePayer(opts) {
+  const raw = opts.privateKey;
+  if (!raw) return void 0;
+  const moduleName = "@solana/kit";
+  const kit = await import(moduleName).catch(() => null);
+  if (!kit?.createKeyPairSignerFromPrivateKeyBytes || !kit.getBase58Codec) {
+    throw new Error(
+      "@solana/kit not installed \u2014 `npm install @solana/kit` for loadSolanaFeePayer."
+    );
+  }
+  let bytes;
+  if (/^[0-9a-fA-F]{128}$/.test(raw)) {
+    bytes = new Uint8Array(raw.match(/.{2}/g).map((h) => parseInt(h, 16))).slice(0, 32);
+  } else {
+    const decoded = new Uint8Array(kit.getBase58Codec().encode(raw));
+    bytes = decoded.length === 64 ? decoded.slice(0, 32) : decoded;
+  }
+  return kit.createKeyPairSignerFromPrivateKeyBytes(bytes);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  RAIL_SPEC_DEFAULTS,
   SETTLEMENT_OVERRIDES_HEADER,
   USDC,
   X402_SUPPORTED_BASE_NETWORKS,
@@ -804,11 +1230,19 @@ function settlementOverrideHeader(overrides) {
   buildPaymentHeaders,
   buildPaymentRequestBlob,
   buildX402AcceptsFor402,
+  classifyOrchestrationError,
   classifyX402SettleResult,
   createMppxServer,
   createX402Server,
+  detectRailFromHeaders,
   dispatchSettlementByNetwork,
   extractPaymentSigner,
+  extractPaymentSignerFromAuth,
+  extractSignerForPrecheck,
+  formatUsdCents,
+  lazyMppxServer,
+  lazyX402Server,
+  loadSolanaFeePayer,
   lookupRail,
   networkFamily,
   networks,
@@ -818,10 +1252,13 @@ function settlementOverrideHeader(overrides) {
   rails,
   readX402PaymentHeader,
   registerX402SchemesV1V2,
+  resolveRecipient,
   settlementOverrideHeader,
+  usdToAtomic,
   validateX402NetworkConfig,
   verifyX402Request,
   wrapSolanaChargeWithFinalizedBlockhash,
-  wwwAuthenticateHeader
+  wwwAuthenticateHeader,
+  zeroAmountCarveOut
 });
 //# sourceMappingURL=index.js.map