@zeroxyz/sdk 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.4.0
+
+### Added
+
+- Pre-flight **balance gate** on paid `client.fetch()` / `payments.pay()` / `payments.payMpp()`. Before signing a paid leg the SDK reads the payer's USDC balance (x402 → Base; MPP → Tempo, including the Base→Tempo bridge math) and, if it can't cover the call, aborts with the new `ZeroInsufficientFundsError` instead of signing a doomed transaction. Previously an empty wallet signed anyway, the chain rejected, and the run was recorded at status 402 → the server classified it `payment_gated`, **indistinguishable from a capability that correctly payment-gates** — so unfunded wallets silently dinged cap reliability. (#585)
+- New `FetchOutcome` value **`insufficient_funds`** and new error class **`ZeroInsufficientFundsError`** (`ZeroErrorCode` `insufficient_funds`, carrying `have` / `need`). On this outcome `client.fetch()` records **no run** (`status: null`, `runTrackingSkipped` includes `insufficient_funds_not_recorded`) — a wallet condition is never charged against the capability; the wallet funnel stays observable via the `fetch_executed.outcome` analytics event. (#585)
+
+### Notes
+
+- The balance read is **fail-open**: an RPC error proceeds to attempt payment rather than re-introducing a false `payment_gated`. Free capabilities are unaffected — a non-402 response never enters the payment path, and a `0`-amount challenge passes the gate (`balance < 0` is never true). The `maxPay` contract is unchanged. (#585)
+
+## 0.3.0
+
+### Added
+
+- `SearchResult` now carries `method` (the capability's HTTP verb) and `brandName`. Both are already returned by the search API but were previously stripped by the SDK's response schema. Surfacing `method` lets a caller tell GET from POST straight from a search result — enough to `fetch()` a no-body GET without a `capabilities.get()` round-trip. Both fields are optional, so a response that omits them still parses. (#593)
+
+### Documentation
+
+- Expanded the README with a **Wallet & funding** section (`wallet.balance()` / `wallet.fundingUrl()`), the full `FetchResult` shape, the `runId`-requires-`capabilityId` precondition, and search → get → fetch guidance. (#593)
+
 ## 0.2.0
 
 ### Changed

package/README.md

@@ -25,7 +25,7 @@ const client = new ZeroClient();
 
 const { capabilities } = await client.search("current weather in tokyo");
 for (const cap of capabilities) {
-  console.log(cap.id, cap.name, cap.url, cap.availabilityStatus);
+  console.log(cap.id, cap.name, cap.method, cap.url, cap.availabilityStatus);
 }
 ```
 
@@ -102,6 +102,8 @@ The SDK refreshes the access token automatically after a `401`, and every refres
 
 Endpoints that don't charge pass straight through: a `200` on the first request returns with `payment: null` and `outcome: "success"`. No payment is attempted.
 
+**Building the request — search → get → fetch.** A `search()` result carries the `url` and `method`, so a no-body `GET` capability can go straight to `fetch()`. For anything that takes a request body, call `capabilities.get()` first: its `bodySchema`, `method`, and `headers` are what tell you how to construct the call. Don't guess the body from the search summary.
+
 ```ts
 const result = await client.fetch(url, {
   method: "POST",
@@ -116,9 +118,15 @@ switch (result.outcome) {
   case "success":
     // 2xx/3xx — result.body / result.bodyRaw are populated.
     break;
+  case "insufficient_funds":
+    // Wallet balance is too low to cover the challenge amount. No payment
+    // was attempted. Top off via `zero wallet fund` (CLI) or fund the
+    // wallet before retrying. result.error is a ZeroInsufficientFundsError
+    // with .have and .need fields.
+    break;
   case "payment_failed":
-    // Couldn't pay: over your maxPay, insufficient balance, or an
-    // unrecognized 402 protocol. Nothing settled — generally safe to retry.
+    // Couldn't pay: over your maxPay or an unrecognized 402 protocol.
+    // Nothing settled — generally safe to retry.
     break;
   case "payment_rejected":
     // Paid, but the capability still returned 402 (a settlement/facilitator
@@ -142,12 +150,65 @@ for (const warning of result.warnings ?? []) {
 }
 ```
 
+### The `FetchResult`
+
+`fetch()` always resolves to one object — it doesn't reject for expected runtime failures (those come back as an `outcome`; see [Errors](#errors)). The full shape:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `outcome` | `FetchOutcome` | The closed enum above — branch on this first. |
+| `ok` | `boolean` | `true` iff `status` is 2xx. Convenience for the HTTP-success check; `outcome === "success"` is the same signal at the payment-and-HTTP level. |
+| `status` | `number \| null` | Upstream HTTP status; `null` if the request never reached the server. |
+| `body` | `unknown` | Parsed JSON when the response is JSON, otherwise the text (base64 for binary). |
+| `bodyRaw` | `string \| null` | The exact response text, for hashing/forwarding. `bodyEncoding: "base64"` is set when binary. |
+| `payment` | `PaymentResult \| null` | `{ protocol, chain, txHash, amount, asset, … }` when a payment settled; `null` on a free call. |
+| `runId` | `string \| null` | The recorded run, for `runs.review()`. **`null` unless you pass `capabilityId`** (and a wallet is configured). |
+| `latencyMs` | `number` | End-to-end call latency. |
+| `upstreamError` | `UpstreamError?` | Present on `server_error` — the capability's own 4xx/5xx detail. |
+| `warnings` | `string[]?` | Non-fatal notes (truncated body, MPP close failure, …) — keyed by `FETCH_WARNINGS`. |
+| `runTrackingSkipped` | `string[]?` | Why a run wasn't recorded (e.g. no `capabilityId`) — keyed by `FETCH_SKIP_REASONS`. |
+
+`capabilityId` accepts the capability's `uid` (`cap_…`) or `slug` — i.e. the `id`/`slug` from a `search()` result or the `uid`/`slug` from `capabilities.get()`.
+
 ### `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.
 
 To put a human in the loop before any spend, read the price up front (`cost.amount` is on every search result and on `capabilities.get()`), show it to your user, and only call `fetch()` with `maxPay` once they approve.
 
+## Wallet & funding
+
+The wallet you construct the client with **is** the agent's identity — paid calls draw USDC from it, and there are no per-service API keys to provision. Keeping it funded is the only operational task. Two funding models, both first-class:
+
+- **Partner-funded shared wallet** *(the common default).* You hold one wallet on behalf of all your users, keep it topped up as a backend cost, and recoup it through your own billing. Per-user spend tracking and caps live in your app — `maxPay` is the per-call guard.
+- **End-user top-up.** Each user funds the wallet directly; you surface a funding link when their balance runs low. Pairs with a per-user wallet.
+
+The same two primitives serve both:
+
+```ts
+// The configured address (null in session mode until the first paid call resolves it).
+client.wallet.address;
+
+// Balance in USDC. Sums Base + Tempo by default; pass a chain for just one.
+const { amount } = await client.wallet.balance();          // e.g. "12.50"
+const onBase     = await client.wallet.balance({ chain: "base" });
+
+// A one-time hosted top-up link — Coinbase by default, or provider: "stripe".
+// USDC settles on Base.
+const url = await client.wallet.fundingUrl({ amount: "10" });
+```
+
+Poll `balance()` to decide when to top up. Then either open `fundingUrl()` yourself to refill the shared wallet — from an ops dashboard, a low-balance alert, or alongside a direct USDC transfer to `wallet.address` — or hand the link to the end user. Either way the link is **single-use** and burns when opened, so generate it at the moment of funding and don't pre-open one you intend to give to someone else.
+
+In **session mode** (acting for a Zero user) the wallet is Zero-managed, and a couple more methods apply:
+
+```ts
+await client.wallet.list();      // every wallet linked to the session user
+await client.wallet.provision(); // create the user's managed wallet (idempotent)
+```
+
+To move funds from a user's own (BYO) wallet into their Zero-managed wallet, sign an EIP-3009 `ReceiveWithAuthorization` and relay it with `client.wallet.migrateAuthorization(authorization)` — Zero pays the gas and sweeps the USDC to Base.
+
 ## Namespaces
 
 Beyond `search()` and `fetch()`, the client groups the rest of the API into resource namespaces:
@@ -162,10 +223,9 @@ const { capabilities } = await client.search("translate text to french", {
 // Capabilities — full detail for one capability by id
 const cap = await client.capabilities.get("cap_abc");
 
-// Wallet (account or session mode)
-const balance = await client.wallet.balance();                 // Base + Tempo
-const onBase  = await client.wallet.balance({ chain: "base" }); // a single chain
-const fundUrl = await client.wallet.fundingUrl({ amount: "10" }); // onramp link
+// Wallet — balance + one-time funding URL. See "Wallet & funding" above.
+const { amount } = await client.wallet.balance();
+const fundUrl    = await client.wallet.fundingUrl({ amount: "10" });
 
 // Runs — fetch() records these for you on paid calls; reach for them
 // directly when you want to log or review a call yourself
@@ -223,10 +283,11 @@ The SDK throws typed errors instead of strings. Match them with `instanceof`:
 
 ```ts
 import {
-  ZeroApiError,                // a 4xx/5xx from Zero's own API
-  ZeroAuthError,               // missing auth, failed refresh, expired session
-  ZeroPaymentError,            // payment failed before settlement
-  ZeroSessionCloseFailedError, // MPP session-close voucher rejected
+  ZeroApiError,                  // a 4xx/5xx from Zero's own API
+  ZeroAuthError,                 // missing auth, failed refresh, expired session
+  ZeroInsufficientFundsError,    // wallet balance too low; .have and .need in USDC
+  ZeroPaymentError,              // payment failed before settlement
+  ZeroSessionCloseFailedError,   // MPP session-close voucher rejected
   ZeroTimeoutError,            // the configured timeout was exceeded
   ZeroConfigurationError,      // invalid ClientOptions
   ZeroWalletError,             // a wallet read or write failed
@@ -247,7 +308,7 @@ try {
 }
 ```
 
-`client.fetch()` reserves throwing for programmer errors — bad config, missing credentials, and the like. Expected runtime failures (`network_error`, `payment_failed`, an upstream `5xx`) come back as a `FetchResult` with the matching `outcome`, so you handle them by branching on the result rather than by catching.
+`client.fetch()` reserves throwing for programmer errors — bad config, missing credentials, and the like. Expected runtime failures (`insufficient_funds`, `network_error`, `payment_failed`, an upstream `5xx`) come back as a `FetchResult` with the matching `outcome`, so you handle them by branching on the result rather than by catching.
 
 ## Logging
 

package/dist/{chunk-LHS7KBN7.cjs → chunk-5ZVIL7AZ.cjs}

@@ -79,6 +79,16 @@ var ZeroPaymentError = class extends ZeroError {
     this.name = "ZeroPaymentError";
   }
 };
+var ZeroInsufficientFundsError = class extends ZeroError {
+  have;
+  need;
+  constructor(message, init) {
+    super("insufficient_funds", message, { cause: init.cause });
+    this.name = "ZeroInsufficientFundsError";
+    this.have = init.have;
+    this.need = init.need;
+  }
+};
 var ZeroSessionCloseFailedError = class extends ZeroError {
   session;
   response;
@@ -425,7 +435,12 @@ var FETCH_SKIP_REASONS = Object.freeze({
   bodyReadFailed: "body_read_failed",
   mppSessionCloseFailedNotRecorded: "mpp_session_close_failed_not_recorded",
   paidButStill402NotRecorded: FETCH_WARNINGS.paidButStill402NotRecorded,
-  paymentSettlementUnconfirmed: FETCH_WARNINGS.paymentSettlementUnconfirmed
+  paymentSettlementUnconfirmed: FETCH_WARNINGS.paymentSettlementUnconfirmed,
+  // Pre-sign abort: deliberately NOT recorded as a run — the wallet was
+  // empty before we reached the capability, so charging it as a 402 would
+  // corrupt cap reliability. The wallet funnel is tracked via the
+  // fetch_executed.outcome analytics event instead.
+  insufficientFunds: "insufficient_funds_not_recorded"
 });
 var MAX_RECEIPT_HEADER_BYTES = 8 * 1024;
 var decodeSessionReceiptHeader = (header) => {
@@ -567,6 +582,7 @@ var Payments = class {
     );
     let capturedAmount = null;
     let capturedNetwork;
+    let preflightError = null;
     const x402 = client.registerExactEvmScheme(new client$1.x402Client(), { signer: account });
     x402.onBeforePaymentCreation(async (context) => {
       const selected = context.selectedRequirements;
@@ -600,6 +616,29 @@ var Payments = class {
           reason: `Payment of ${capturedAmount} USDC exceeds maxPay ${input.maxPay}`
         };
       }
+      const detected = networkToChain(capturedNetwork);
+      const balanceChain = detected === "base-sepolia" ? "base-sepolia" : "base";
+      let balance = null;
+      try {
+        balance = await this.readUsdcBalance(account.address, balanceChain);
+      } catch (readErr) {
+        this.client.logger?.({
+          level: "warn",
+          message: "Pre-flight balance read failed; proceeding to attempt payment",
+          meta: {
+            chain: balanceChain,
+            error: readErr instanceof Error ? readErr.message : String(readErr)
+          }
+        });
+      }
+      if (balance !== null && balance < rawAmountUnits) {
+        const have = viem.formatUnits(balance, 6);
+        preflightError = new ZeroInsufficientFundsError(
+          `wallet has ${have} USDC on Base, needs ${capturedAmount}.`,
+          { have, need: capturedAmount }
+        );
+        return { abort: true, reason: preflightError.message };
+      }
     });
     const configuredFetch = buildConfiguredFetch(this.client, {
       timeoutMs: input.timeoutMs
@@ -620,6 +659,7 @@ var Payments = class {
         signal: input.signal
       });
     } catch (err) {
+      if (preflightError) throw preflightError;
       if (err instanceof ZeroError) throw err;
       throw new ZeroPaymentError(
         `x402 payment failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -864,23 +904,29 @@ var Payments = class {
     );
     if (tempoBalance < requiredRaw) {
       if (coerced.chain === "tempo-testnet") {
-        throw new ZeroPaymentError(
-          `Insufficient pathUSD on Tempo testnet: have ${viem.formatUnits(tempoBalance, 6)}, need ${capturedAmount}. Fund via the Tempo testnet faucet: https://docs.tempo.xyz/quickstart/faucet`
+        const have = viem.formatUnits(tempoBalance, 6);
+        throw new ZeroInsufficientFundsError(
+          `Insufficient pathUSD on Tempo testnet: have ${have}, need ${capturedAmount}. Fund via the Tempo testnet faucet: https://docs.tempo.xyz/quickstart/faucet`,
+          { have, need: capturedAmount }
         );
       }
-      await this.bridgeBaseToTempo(account, requiredRaw - tempoBalance);
+      await this.bridgeBaseToTempo(account, requiredRaw - tempoBalance, {
+        isSessionDeposit: challenge.intent === "session",
+        depositTotal: capturedAmount
+      });
     }
     return capturedAmount;
   };
-  bridgeBaseToTempo = async (account, requiredAmount) => {
+  bridgeBaseToTempo = async (account, requiredAmount, depositContext) => {
     this.ensureRelayClient();
     const baseBalance = await this.readUsdcBalance(account.address, "base");
     const buffer = calculateBuffer(baseBalance);
     const bridgeAmount = requiredAmount + buffer;
     if (baseBalance < bridgeAmount) {
-      throw new ZeroPaymentError(
-        `Insufficient Base USDC to bridge: have ${viem.formatUnits(baseBalance, 6)}, need ${viem.formatUnits(bridgeAmount, 6)} (${viem.formatUnits(requiredAmount, 6)} + ${viem.formatUnits(buffer, 6)} buffer). This capability uses an MPP payment channel, which is pre-funded up front. Either fund your wallet on Base, or pass \`maxPay\` to size a smaller channel (e.g. \`maxPay: '0.05'\` for a ~5-cent channel sized for a single cheap call).`
-      );
+      const have = viem.formatUnits(baseBalance, 6);
+      const need = viem.formatUnits(bridgeAmount, 6);
+      const message = depositContext?.isSessionDeposit ? `wallet has ${have} USDC on Base, but this capability pre-funds a ${depositContext.depositTotal} USDC MPP payment channel up front (the channel is deposited before the call, so it asks for more than a single charge). Needs ${need} on Base to open it \u2014 fund the wallet, or pass a smaller \`maxPay\` (e.g. '0.05') to size the channel down to one cheap call.` : `wallet has ${have} USDC on Base, needs ${need} to fund this capability's MPP payment channel (${viem.formatUnits(requiredAmount, 6)} + ${viem.formatUnits(buffer, 6)} buffer). Tip: pass a smaller \`maxPay\` (e.g. '0.05') to size a cheaper channel.`;
+      throw new ZeroInsufficientFundsError(message, { have, need });
     }
     this.client.logger?.({
       level: "info",
@@ -1100,7 +1146,7 @@ var Payments = class {
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.4.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2482,6 +2528,15 @@ var clientFetch = async (client, url, opts = {}) => {
             session: err.session
           };
           warnings.push(FETCH_WARNINGS.mppSessionCloseFailed);
+        } else if (err instanceof ZeroInsufficientFundsError) {
+          return errorFetchResult(
+            startedAt,
+            err.message,
+            FETCH_SKIP_REASONS.insufficientFunds,
+            capabilityIdRequested,
+            "insufficient_funds",
+            null
+          );
         } else if (err instanceof ZeroPaymentError || err instanceof ZeroAuthError) {
           const result2 = errorFetchResult(
             startedAt,
@@ -2679,8 +2734,15 @@ var searchResultSchema = zod.z.object({
   slug: zod.z.string(),
   name: zod.z.string(),
   canonicalName: zod.z.string().nullable().optional(),
+  brandName: zod.z.string().nullable().optional(),
   description: zod.z.string(),
   whatItDoes: zod.z.string().nullable().optional(),
+  // HTTP verb the capability expects. Surfaced on the search row so a caller
+  // can tell GET from POST without a `capabilities.get()` round-trip — enough
+  // to `fetch()` a no-body GET directly. POST bodies still need `get()` for
+  // the `bodySchema`. Optional (not required) so a response that omits it —
+  // an older API deploy — still parses rather than failing the whole search.
+  method: zod.z.string().optional(),
   url: zod.z.string(),
   urlTemplate: zod.z.string().nullable().optional(),
   cost: zod.z.object({ amount: zod.z.string(), asset: zod.z.string() }),
@@ -3107,5 +3169,5 @@ exports.coerceTempoChainId = coerceTempoChainId;
 exports.createManagedAccount = createManagedAccount;
 exports.paymentHasAnchor = paymentHasAnchor;
 exports.tempoChainLabelFromId = tempoChainLabelFromId;
-//# sourceMappingURL=chunk-LHS7KBN7.cjs.map
-//# sourceMappingURL=chunk-LHS7KBN7.cjs.map
+//# sourceMappingURL=chunk-5ZVIL7AZ.cjs.map
+//# sourceMappingURL=chunk-5ZVIL7AZ.cjs.map