@zeroxyz/sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@zeroxyz/sdk` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — with the pre-1.0 caveat that minor versions may include breaking changes.
 
+## 0.14.0
+
+### Added
+
+- **Explicit payment-protocol selection** — `client.fetch(url, { paymentProtocol: "x402" | "mpp" })` forces one advertised rail instead of using the default x402-first negotiation order. Selection is strict: when the requested protocol is absent, the fetch fails without silently falling back. The CLI exposes the same control as `zero fetch --protocol x402|mpp`. (#785)
+
+### Fixed
+
+- **ZeroClick-style x402 identity-then-charge flows** — `client.fetch()` now handles one zero-value identity challenge before exactly one positive-value payment attempt, reparsing the fresh post-identity 402 instead of signing the stale `$0` challenge. `maxPay` still gates the real charge before signing, and any second positive-value challenge is refused before another payment authorization is created. (#785)
+
 ## 0.13.0
 
 ### Added

package/README.md

@@ -95,7 +95,7 @@ The SDK refreshes the access token automatically after a `401`, and every refres
 `client.fetch()` is the call you'll reach for most. Given a URL, it:
 
 1. Sends the request.
-2. If the server answers `402 Payment Required` (x402 or MPP), reads the payment challenge and pays it.
+2. If the server answers `402 Payment Required` (x402 or MPP), reads the payment challenge and pays it. For x402 endpoints that use a zero-dollar identity challenge before the real charge, it handles one free identity stage followed by exactly one positive-value payment attempt.
 3. Replays the request with proof of payment.
 4. Returns the body, status, and payment metadata together.
 5. Records a run on Zero when you pass a `capabilityId`, so the capability's reliability signal stays current and the call stays reviewable.
@@ -131,7 +131,8 @@ const result = await client.fetch(url, {
   method: "POST",
   headers: { "content-type": "application/json" },
   body: JSON.stringify({ city: "tokyo" }),
-  maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
+	maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
+	paymentProtocol: "mpp",  // optional: force "x402" or "mpp" when both are offered
   capabilityId: "cap_abc", // attribute the run to a known capability
   walletAddress: "0x…",    // session mode: pay from this profile wallet (default: primary)
   signal: controller.signal,
@@ -195,7 +196,7 @@ for (const warning of result.warnings ?? []) {
 
 ### `maxPay`
 
-`maxPay` is your hard per-call ceiling, in USDC. The challenge amount is checked against it **before** anything is signed; an over-cap challenge aborts with `outcome: "payment_failed"` and no on-chain spend. Set it on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.
+`maxPay` is your hard per-call ceiling, in USDC. The single positive-value challenge is checked **before** it is signed; a preceding zero-value identity handshake does not consume the cap. An over-cap challenge aborts with `outcome: "payment_failed"`, and a second positive-value challenge is refused before signing. Set `maxPay` on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.
 
 To put a human in the loop before any spend, read the price up front, show it to your user, and only call `fetch()` with `maxPay` once they approve. Prefer `capabilities.get()`'s **`pricing`** object when present: `pricing.summary` is the server-resolved display string (render it verbatim — don't re-derive from raw fields), `pricing.kind` classifies the shape (`static | dynamic | session | metered | subscription | free | unknown`), and `pricing.primary.amountUsd` / `depositUsd` give the structured numbers for sizing `maxPay`. `cost.amount` remains on every search result as the raw advertised scalar, but it flattens usage-priced caps — a `dynamic` cap's real cost scales with input.
 

package/dist/{chunk-2A2ZZ5XR.cjs → chunk-AM5RDERD.cjs}

@@ -8,7 +8,6 @@ var client$1 = require('@x402/core/client');
 var http = require('@x402/core/http');
 var client = require('@x402/evm/exact/client');
 var signInWithX = require('@x402/extensions/sign-in-with-x');
-var fetch = require('@x402/fetch');
 var mppx = require('mppx');
 var client$2 = require('mppx/client');
 var crypto$1 = require('crypto');
@@ -700,6 +699,9 @@ var Payments = class {
       input.walletAddress
     );
     let capturedAmount = null;
+    let pendingAmountUnits = 0n;
+    let identityChallengeHandled = false;
+    let paidChallengeHandled = false;
     let capturedNetwork;
     let preflightError = null;
     const x402 = client.registerExactEvmScheme(new client$1.x402Client(), { signer: account });
@@ -728,11 +730,25 @@ var Payments = class {
         };
       }
       const rawAmountUnits = BigInt(rawAmount);
-      capturedAmount = viem.formatUnits(rawAmountUnits, 6);
+      pendingAmountUnits = rawAmountUnits;
+      const challengeAmount = viem.formatUnits(rawAmountUnits, 6);
+      if (rawAmountUnits === 0n) {
+        if (identityChallengeHandled || paidChallengeHandled) {
+          return {
+            abort: true,
+            reason: "Only one zero-value identity challenge is allowed, and it must precede payment."
+          };
+        }
+      } else if (paidChallengeHandled) {
+        return {
+          abort: true,
+          reason: "A positive-value x402 payment was already attempted for this fetch; refusing a second charge."
+        };
+      }
       if (maxPayUnits !== null && rawAmountUnits > maxPayUnits) {
         return {
           abort: true,
-          reason: `Payment of ${capturedAmount} USDC exceeds maxPay ${input.maxPay}`
+          reason: `Payment of ${challengeAmount} USDC exceeds maxPay ${input.maxPay}`
         };
       }
       const detected = networkToChain(capturedNetwork);
@@ -752,9 +768,10 @@ var Payments = class {
       }
       if (balance !== null && balance < rawAmountUnits) {
         const have = viem.formatUnits(balance, 6);
+        const requiredAmount = viem.formatUnits(rawAmountUnits, 6);
         preflightError = new ZeroInsufficientFundsError(
-          `wallet has ${have} USDC on Base, needs ${capturedAmount}.`,
-          { have, need: capturedAmount }
+          `wallet has ${have} USDC on Base, needs ${requiredAmount}.`,
+          { have, need: requiredAmount }
         );
         return { abort: true, reason: preflightError.message };
       }
@@ -765,18 +782,64 @@ var Payments = class {
     const httpClient = new http.x402HTTPClient(x402).onPaymentRequired(
       signInWithX.createSIWxClientHook(account)
     );
-    const wrappedFetch = fetch.wrapFetchWithPayment(
-      withSynthesizedX402Header(configuredFetch),
-      httpClient
-    );
+    const paymentFetch = withSynthesizedX402Header(configuredFetch);
     let response;
     try {
-      response = await wrappedFetch(input.url, {
+      const request2 = new Request(input.url, {
         method: input.method ?? "GET",
         headers: input.headers,
         body: input.body,
         signal: input.signal
       });
+      response = await paymentFetch(request2.clone());
+      for (let paymentStage = 0; paymentStage < 2; paymentStage++) {
+        if (response.status !== 402) break;
+        const parseChallenge = async (challengeResponse) => {
+          let body;
+          try {
+            const text = await challengeResponse.clone().text();
+            if (text) body = JSON.parse(text);
+          } catch {
+          }
+          return httpClient.getPaymentRequiredResponse(
+            (name) => challengeResponse.headers.get(name),
+            body
+          );
+        };
+        let paymentRequired = await parseChallenge(response);
+        const hookHeaders = await httpClient.handlePaymentRequired(paymentRequired);
+        if (hookHeaders) {
+          const hookRequest = request2.clone();
+          for (const [key, value] of Object.entries(hookHeaders)) {
+            hookRequest.headers.set(key, value);
+          }
+          response = await paymentFetch(hookRequest);
+          if (response.status === 402) {
+            paymentRequired = await parseChallenge(response);
+          } else {
+            break;
+          }
+        }
+        pendingAmountUnits = 0n;
+        const paymentPayload = await x402.createPaymentPayload(paymentRequired);
+        if (pendingAmountUnits === 0n) {
+          identityChallengeHandled = true;
+          capturedAmount = "0";
+        } else {
+          paidChallengeHandled = true;
+          capturedAmount = viem.formatUnits(pendingAmountUnits, 6);
+        }
+        const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+        const paidRequest = request2.clone();
+        for (const [key, value] of Object.entries(paymentHeaders)) {
+          paidRequest.headers.set(key, value);
+        }
+        paidRequest.headers.set(
+          "Access-Control-Expose-Headers",
+          "PAYMENT-RESPONSE,X-PAYMENT-RESPONSE"
+        );
+        response = await paymentFetch(paidRequest);
+      }
     } catch (err) {
       if (preflightError) throw preflightError;
       if (err instanceof ZeroError) throw err;
@@ -1344,8 +1407,17 @@ var cancelBody2 = (response) => {
   } catch {
   }
 };
-var detectPaymentRequirement = async (response) => {
+var detectPaymentRequirement = async (response, preferredProtocol) => {
   if (response.status !== 402) return null;
+  const wwwAuth = response.headers.get("www-authenticate");
+  const advertisesMpp = wwwAuth ? splitWwwAuthenticateChallenges(wwwAuth).some((challenge) => {
+    const scheme = challenge.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+    return MPP_SCHEME_TOKENS.has(scheme);
+  }) : false;
+  if (preferredProtocol === "mpp") {
+    cancelBody2(response);
+    return advertisesMpp ? { protocol: "mpp", raw: { "www-authenticate": wwwAuth } } : { protocol: "unknown", raw: { requestedProtocol: "mpp" } };
+  }
   const x402Header = response.headers.get("payment-required") ?? response.headers.get("x-payment-required");
   if (x402Header) {
     cancelBody2(response);
@@ -1375,15 +1447,13 @@ var detectPaymentRequirement = async (response) => {
     } catch {
     }
   }
-  const wwwAuth = response.headers.get("www-authenticate");
-  if (wwwAuth) {
-    const schemes = splitWwwAuthenticateChallenges(wwwAuth).map(
-      (challenge) => challenge.trim().split(/\s+/)[0]?.toLowerCase() ?? ""
-    );
-    if (schemes.some((scheme) => MPP_SCHEME_TOKENS.has(scheme))) {
-      cancelBody2(response);
-      return { protocol: "mpp", raw: { "www-authenticate": wwwAuth } };
-    }
+  if (preferredProtocol === "x402") {
+    cancelBody2(response);
+    return { protocol: "unknown", raw: { requestedProtocol: "x402" } };
+  }
+  if (advertisesMpp) {
+    cancelBody2(response);
+    return { protocol: "mpp", raw: { "www-authenticate": wwwAuth } };
   }
   cancelBody2(response);
   return { protocol: "unknown", raw: {} };
@@ -1709,7 +1779,10 @@ var clientFetch = async (client, url, opts = {}) => {
     return result2;
   }
   if (response.status === 402) {
-    const requirement = await detectPaymentRequirement(response);
+    const requirement = await detectPaymentRequirement(
+      response,
+      opts.paymentProtocol
+    );
     if (requirement?.protocol === "x402" || requirement?.protocol === "mpp") {
       const payCall = requirement.protocol === "x402" ? client.payments.pay : client.payments.payMpp;
       try {
@@ -1781,7 +1854,7 @@ var clientFetch = async (client, url, opts = {}) => {
     } else if (requirement?.protocol === "unknown") {
       const result2 = errorFetchResult(
         startedAt,
-        "Capability returned 402 with an unrecognized payment protocol. Neither x402 nor MPP markers were detected in the response headers or body.",
+        opts.paymentProtocol ? `Capability did not advertise the requested ${opts.paymentProtocol} payment protocol.` : "Capability returned 402 with an unrecognized payment protocol. Neither x402 nor MPP markers were detected in the response headers or body.",
         "unrecognized_402_protocol",
         capabilityIdRequested,
         "payment_failed",
@@ -1965,7 +2038,7 @@ var clientFetch = async (client, url, opts = {}) => {
 
 // package.json
 var package_default = {
-  version: "0.13.0"};
+  version: "0.14.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -3955,5 +4028,5 @@ exports.normalizeTransportEnvelopeRequest = normalizeTransportEnvelopeRequest;
 exports.paymentHasAnchor = paymentHasAnchor;
 exports.tempoChainLabelFromId = tempoChainLabelFromId;
 exports.unwrapTransportEnvelope = unwrapTransportEnvelope;
-//# sourceMappingURL=chunk-2A2ZZ5XR.cjs.map
-//# sourceMappingURL=chunk-2A2ZZ5XR.cjs.map
+//# sourceMappingURL=chunk-AM5RDERD.cjs.map
+//# sourceMappingURL=chunk-AM5RDERD.cjs.map