@zeroxyz/sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.13.0
+
+### Added
+
+- **Pay and sign from a non-primary wallet** — `client.fetch()`, `payments.pay()` / `payMpp()`, and `client.auth.signMessage/signTransaction/signTypedData` accept an optional `walletAddress` (session mode). The SDK resolves the named profile wallet for the payment intent's `from`, the managed signature, and the recorded run's attribution (`runs.create` gained the same optional `walletAddress`), so per-wallet run filters reflect which wallet acted. The wallet must be on the caller's profile. Default behavior (primary wallet) is unchanged. (ZERO-488)
+- **`client.runs.list({ walletAddress })`** — narrow session run reads to specific profile wallets (string or string[]). Default remains all profile wallets; an address not on the profile is a server-side 400, never a silent intersection. (ZERO-488)
+- **Wallet nicknames** — `client.wallet.setNickname({ walletAddress, nickname })` (null clears), optional `nickname` on `client.wallet.import()`, and `UserWalletDto.nickname`. Nicknames are private to the authenticated user. New export `SetNicknameOptions`. (ZERO-488)
+- **`client.wallet.revokeDelegation()` / `client.wallet.reauthorizeDelegation()`** — per-wallet delegation lifecycle (default: the primary wallet). New export `DelegationOptions`. (ZERO-488)
+
+## 0.12.0
+
+### Added
+
+- **`exampleRequest` on capability responses** (`capabilities.get()`) — the bare, ready-to-send request body an agent should copy: `.request` unwrapped from the stored `{request,response}` transcript **and** the HTTP-transport envelope, validated against the current `bodySchema`. `null` when there's no usable example or the stored one is stale (missing a now-required field); the raw `example` is retained for the response sample. Prefer `exampleRequest` over `example` when building a fetch body. (ZERO-393, #757)
+
+### Fixed
+
+- **MPP session close honors a metered zero receipt** — a no-result metered call now closes the channel at `$0` instead of throwing an orphan `close-failed`. An ambiguous zero close (no explicit metered receipt) still refuses, as before. (#761)
+
 ## 0.11.0
 
 ### Added

package/README.md

@@ -102,7 +102,7 @@ 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.
+**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. When present, **`exampleRequest`** is the single best artifact to copy — the bare, ready-to-send request body from a real successful call, already unwrapped from the stored transcript and validated against the current schema (it's `null` when there's no example or the stored one is stale, so fall back to `bodySchema`). The raw `example` (`{ request, response }`) is retained for the response sample.
 
 Each search result also carries a `token` field (format: `z_xxx.N`) — a short server-issued attribution token that encodes the search context and the result's position. Pass it as `capabilityId` to `fetch()` (or as the `id` to `capabilities.get()`) instead of the raw uid/slug; the server uses it to attribute the run back to the originating search for ranking and analytics. Tokens expire when the session rolls, so use them within the same search session.
 
@@ -133,6 +133,7 @@ const result = await client.fetch(url, {
   body: JSON.stringify({ city: "tokyo" }),
   maxPay: "0.01",          // USDC ceiling; an over-cap challenge aborts before signing
   capabilityId: "cap_abc", // attribute the run to a known capability
+  walletAddress: "0x…",    // session mode: pay from this profile wallet (default: primary)
   signal: controller.signal,
 });
 
@@ -230,20 +231,32 @@ await client.wallet.list();      // every wallet linked to the session user
 await client.wallet.provision(); // create the user's managed wallet (idempotent)
 
 // Link an existing self-custody wallet by private key (0x prefix optional).
-// Pass makePrimary to have it pay for the user's calls from now on.
+// Pass makePrimary to have it pay for the user's calls from now on, and an
+// optional nickname (owner-private display name, max 64 chars).
 const imported = await client.wallet.import({
   privateKey: "0x…",
   makePrimary: true,
+  nickname: "Trading bot",
 });
 
 // Switch which linked wallet is primary, or unlink one. remove() rejects the
 // primary wallet and any wallet holding a balance — reassign / drain first.
 await client.wallet.setPrimary({ walletAddress: imported.walletAddress });
 await client.wallet.remove({ walletAddress: "0x…" });
+
+// Nickname a wallet (or clear with null). Nicknames are private to the
+// authenticated user — they never appear on reviews or public surfaces.
+await client.wallet.setNickname({ walletAddress: "0x…", nickname: "Cold storage" });
+
+// Revoke / re-grant Zero's signing delegation per wallet (default: primary).
+await client.wallet.revokeDelegation({ walletAddress: "0x…" });
+await client.wallet.reauthorizeDelegation({ walletAddress: "0x…" });
 ```
 
 `wallet.address()` covers the common case (resolve — or provision — the primary managed wallet); reach for the methods above when you need the full wallet objects, explicit provisioning, or multi-wallet management. Imported wallets carry an `importedAt` timestamp on the returned wallet objects.
 
+To **pay from a non-primary wallet**, pass `walletAddress` on the call itself — `client.fetch(url, { walletAddress })` (or `payments.pay` / `payMpp`) resolves the named profile wallet for the payment intent's `from`, the managed signature, and the recorded run's attribution, and `client.auth.sign*` accept `{ walletAddress }` too. The wallet must be a delegated Privy-embedded wallet on the session user's profile. Runs can likewise be filtered per wallet: `client.runs.list({ walletAddress: ["0x…"] })` (default remains all profile wallets; an address not on the profile is a 400).
+
 ## Namespaces
 
 Beyond `search()` and `fetch()`, the client groups the rest of the API into resource namespaces:
@@ -262,8 +275,8 @@ const cap = await client.capabilities.get("cap_abc");     // by uid
 const cap2 = await client.capabilities.get("z_Ab12cd.1"); // by search token
 
 // Wallet — balance, one-time funding URL, and (session mode) multi-wallet
-// management: list / provision / import / setPrimary / remove. See
-// "Wallet & funding" above.
+// management: list / provision / import / setPrimary / remove / setNickname /
+// revokeDelegation / reauthorizeDelegation. See "Wallet & funding" above.
 const { amount } = await client.wallet.balance();
 const fundUrl    = await client.wallet.fundingUrl({ amount: "10" });
 

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

@@ -15,36 +15,40 @@ var crypto$1 = require('crypto');
 var zod = require('zod');
 
 // src/auth/managed-account.ts
-var createManagedAccount = (client, address) => accounts.toAccount({
-  address,
-  async signMessage({ message }) {
-    return await client.auth.signMessage(
-      { message },
-      { expectedAddress: address }
-    );
-  },
-  async signTypedData(typedData) {
-    const td = typedData;
-    return await client.auth.signTypedData(
-      {
-        domain: td.domain,
-        types: td.types,
-        primaryType: td.primaryType,
-        message: td.message
-      },
-      { expectedAddress: address }
-    );
-  },
-  async signTransaction(transaction, options) {
-    const serialize = options?.serializer ?? viem.serializeTransaction;
-    const unsigned = await serialize(transaction);
-    const signature = await client.auth.signTransaction(
-      { unsignedTransaction: unsigned },
-      { expectedAddress: address }
-    );
-    return await serialize(transaction, viem.parseSignature(signature));
-  }
-});
+var createManagedAccount = (client, address, opts = {}) => {
+  const signOptions = {
+    // expectedAddress pins verification to this adapter's frozen address.
+    expectedAddress: address,
+    ...opts.explicitWallet ? { walletAddress: address } : {}
+  };
+  return accounts.toAccount({
+    address,
+    async signMessage({ message }) {
+      return await client.auth.signMessage({ message }, signOptions);
+    },
+    async signTypedData(typedData) {
+      const td = typedData;
+      return await client.auth.signTypedData(
+        {
+          domain: td.domain,
+          types: td.types,
+          primaryType: td.primaryType,
+          message: td.message
+        },
+        signOptions
+      );
+    },
+    async signTransaction(transaction, options) {
+      const serialize = options?.serializer ?? viem.serializeTransaction;
+      const unsigned = await serialize(transaction);
+      const signature = await client.auth.signTransaction(
+        { unsignedTransaction: unsigned },
+        signOptions
+      );
+      return await serialize(transaction, viem.parseSignature(signature));
+    }
+  });
+};
 var USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 var USDC_TEMPO = "0x20c000000000000000000000b9537d11c60e8b50";
 var TEMPO_CHAIN_ID = 4217;
@@ -591,6 +595,7 @@ var pickSessionCloseAmount = (receipt, openTimeCumulative) => {
   if (receipt.metered === true) return fromReceipt;
   return fromReceipt > openTimeCumulative ? fromReceipt : openTimeCumulative;
 };
+var isMeteredZeroReceipt = (receipt) => receipt?.metered === true && BigInt(receipt.acceptedCumulative) === 0n && BigInt(receipt.spent) === 0n;
 var raceWithSignal = (p, signal, client) => {
   if (!signal) return p;
   if (signal.aborted) {
@@ -640,12 +645,12 @@ var cancelBody = (response) => {
   } catch {
   }
 };
-var resolveAccount = async (client, overrideAccount, signal) => {
+var resolveAccount = async (client, overrideAccount, signal, walletAddress) => {
   if (overrideAccount) return overrideAccount;
   const credentials = client.getCredentials();
   if (credentials.kind === "account") return credentials.account;
   if (credentials.kind === "session") {
-    return await client.resolveManagedAccount(signal);
+    return await client.resolveManagedAccount(signal, walletAddress);
   }
   throw new ZeroAuthError(
     "auth_no_credentials",
@@ -691,7 +696,8 @@ var Payments = class {
     const account = await resolveAccount(
       this.client,
       input.account,
-      input.signal
+      input.signal,
+      input.walletAddress
     );
     let capturedAmount = null;
     let capturedNetwork;
@@ -826,7 +832,8 @@ var Payments = class {
     const account = await resolveAccount(
       this.client,
       input.account,
-      input.signal
+      input.signal,
+      input.walletAddress
     );
     const configuredFetch = buildConfiguredFetch(this.client, {
       timeoutMs: input.timeoutMs
@@ -1164,7 +1171,7 @@ var Payments = class {
     }
     const receipt = readSessionReceipt(response);
     let closeAmount = pickSessionCloseAmount(receipt, openTimeCumulative);
-    if (closeAmount === 0n && channelEntry.cumulativeAmount > 0n) {
+    if (closeAmount === 0n && channelEntry.cumulativeAmount > 0n && !isMeteredZeroReceipt(receipt)) {
       closeAmount = channelEntry.cumulativeAmount;
     }
     const reconcileAmount = receipt && isUintString(receipt.acceptedCumulative) ? receipt.acceptedCumulative : closeAmount.toString();
@@ -1181,7 +1188,7 @@ var Payments = class {
       capturedAmount,
       cause
     });
-    if (closeAmount === 0n) {
+    if (closeAmount === 0n && !isMeteredZeroReceipt(receipt)) {
       throw closeFailed(
         `Refusing to sign zero close credential for channel ${channelId} \u2014 neither receipt nor channelEntry produced a nonzero cumulativeAmount. Query escrow directly to recover; check logger for an earlier 'non-bigint cumulativeAmount' warning.`
       );
@@ -1606,7 +1613,8 @@ var recordErrorFetchRun = async (client, opts, result, capabilityIdOverride) =>
       ...fetchOriginForRecord && { fetchOrigin: fetchOriginForRecord },
       ...result.status !== null && { status: result.status },
       latencyMs: result.latencyMs,
-      ...opts.requestSchema && { requestSchema: opts.requestSchema }
+      ...opts.requestSchema && { requestSchema: opts.requestSchema },
+      ...opts.walletAddress && !opts.account && { walletAddress: opts.walletAddress }
     });
     result.runId = created.runId;
     delete result.runTrackingSkipped;
@@ -1715,6 +1723,7 @@ var clientFetch = async (client, url, opts = {}) => {
           body: requestBody,
           maxPay: opts.maxPay,
           account: opts.account,
+          ...opts.walletAddress && { walletAddress: opts.walletAddress },
           signal: opts.signal,
           timeoutMs: opts.timeoutMs,
           ...opts.displayCostAmount && {
@@ -1887,6 +1896,10 @@ var clientFetch = async (client, url, opts = {}) => {
           ...opts.capabilityId === void 0 ? { fetchOrigin: "direct_url" } : opts.fetchOrigin && { fetchOrigin: opts.fetchOrigin },
           status: response.status,
           latencyMs,
+          // Attribute to the selected wallet in session mode. Skipped when a
+          // per-call `account` override records the run — that account's own
+          // EIP-191 identity is the attribution.
+          ...opts.walletAddress && !opts.account && { walletAddress: opts.walletAddress },
           ...opts.requestSchema && { requestSchema: opts.requestSchema },
           ...derived?.responseSchema && {
             responseSchema: derived.responseSchema
@@ -1952,7 +1965,7 @@ var clientFetch = async (client, url, opts = {}) => {
 
 // package.json
 var package_default = {
-  version: "0.11.0"};
+  version: "0.13.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2442,6 +2455,9 @@ var userWalletDtoSchema = zod.z.object({
   walletAddress: zod.z.string(),
   source: zod.z.enum(["self_custody", "privy_embedded"]),
   isPrimary: zod.z.boolean(),
+  // Owner-chosen display name; null/absent = unnamed (show the address).
+  // Optional so the SDK tolerates servers that predate nicknames.
+  nickname: zod.z.string().nullable().optional(),
   linkedAt: zod.z.union([zod.z.string(), zod.z.date()]).nullable().optional(),
   importedAt: zod.z.union([zod.z.string(), zod.z.date()]).nullable().optional(),
   delegationGranted: zod.z.boolean(),
@@ -2659,7 +2675,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-message",
-            body: { message: normalizeMessage(input.message) }
+            body: {
+              message: normalizeMessage(input.message),
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -2684,7 +2703,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-transaction",
-            body: { unsignedTransaction: input.unsignedTransaction }
+            body: {
+              unsignedTransaction: input.unsignedTransaction,
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -2723,7 +2745,10 @@ var Auth = class {
           {
             method: "POST",
             path: "/v1/users/me/sign-typed-data",
-            body: { typedData: input }
+            body: {
+              typedData: input,
+              ...opts.walletAddress ? { walletAddress: opts.walletAddress } : {}
+            }
           },
           signResponseSchema
         );
@@ -2842,6 +2867,12 @@ var capabilityResponseSchema = zod.z.object({
   bodySchema: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
   responseSchema: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
   example: zod.z.object({ request: zod.z.unknown(), response: zod.z.unknown() }).nullable(),
+  // The bare, schema-validated request body to send — `.request` unwrapped
+  // from the transcript envelope and checked against the current bodySchema.
+  // Null when there's no usable example or it's stale vs the schema; `example`
+  // is retained for the response sample. Optional for back-compat with older
+  // servers that don't emit it.
+  exampleRequest: zod.z.record(zod.z.string(), zod.z.unknown()).nullable().optional(),
   tags: zod.z.array(zod.z.string()).nullable(),
   exampleAgentPrompt: zod.z.string().nullable().optional(),
   whatItDoes: zod.z.string().nullable().optional(),
@@ -3094,6 +3125,9 @@ var Runs = class {
     if (params.unreviewed !== void 0) query.unreviewed = params.unreviewed;
     if (params.limit !== void 0) query.limit = params.limit;
     if (params.cursor !== void 0) query.cursor = params.cursor;
+    if (params.walletAddress !== void 0) {
+      query.walletAddress = Array.isArray(params.walletAddress) ? params.walletAddress.join(",") : params.walletAddress;
+    }
     return request(
       this.client,
       {
@@ -3229,6 +3263,50 @@ var Wallet = class {
     },
     userWalletDtoSchema
   );
+  // Re-stamp Zero's signing delegation on a profile wallet (default: the
+  // primary). Session-only. Naming a wallet re-authorizes THAT wallet and
+  // never provisions; the server 404s an address not on the profile.
+  reauthorizeDelegation = (opts = {}) => request(
+    this.client,
+    {
+      method: "POST",
+      path: "/v1/users/me/wallets/provision",
+      ...opts.walletAddress ? { body: { walletAddress: opts.walletAddress } } : {},
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Revoke Zero's signing delegation on a profile wallet (default: the
+  // primary). Session-only. Managed signing on that wallet 403s until it is
+  // re-authorized. Note: this stamps the server-side gate — removing Zero's
+  // signer cryptographically is owner-authorized and happens in the user's
+  // Privy session (the web profile page does both).
+  revokeDelegation = (opts = {}) => request(
+    this.client,
+    {
+      method: "DELETE",
+      path: "/v1/users/me/wallets/delegation",
+      ...opts.walletAddress ? { query: { walletAddress: opts.walletAddress } } : {},
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Set, change, or clear (null / empty string) the owner-chosen nickname on
+  // a profile wallet. Session-only. Nicknames are private to the
+  // authenticated user — they never appear on reviews or public surfaces.
+  setNickname = (opts) => request(
+    this.client,
+    {
+      method: "PATCH",
+      path: "/v1/users/me/wallets/nickname",
+      body: {
+        walletAddress: opts.walletAddress,
+        nickname: opts.nickname
+      },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
   // Link an existing self-custody wallet to the session user by private key.
   // Session-only. 409s when the wallet is already linked (to this or another
   // profile — the error message says which).
@@ -3239,7 +3317,8 @@ var Wallet = class {
       path: "/v1/users/me/wallets/import",
       body: {
         privateKey: opts.privateKey,
-        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {}
+        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {},
+        ...opts.nickname !== void 0 ? { nickname: opts.nickname } : {}
       },
       signal: opts.signal
     },
@@ -3442,6 +3521,9 @@ var ZeroClient = class _ZeroClient {
   managedAccountInFlight = null;
   managedAccountAC = null;
   managedAccountGen = 0;
+  // Explicitly-selected (non-default) managed wallets, keyed by lowercased
+  // address. Same lifecycle as managedAccount: cleared on clearManagedAccount.
+  managedAccountByAddress = /* @__PURE__ */ new Map();
   // Multi-tenant servers calling `client.fetch(url, { account: tenantAccount })`
   // on every request would otherwise construct a new ZeroClient (with
   // five namespace instances) per call. Keyed by lowercased account
@@ -3663,8 +3745,16 @@ var ZeroClient = class _ZeroClient {
     }
     this.withAccountCache.clear();
   };
-  /** @internal — used by payments.pay() in session mode. Cached, dedupes concurrent lookups. */
-  resolveManagedAccount = (signal) => {
+  /**
+   * @internal — used by payments.pay() in session mode. Cached, dedupes
+   * concurrent lookups. Pass `walletAddress` to sign as a specific profile
+   * wallet instead of the primary; explicit wallets are cached per address
+   * and their sign requests carry the address so intent and signer agree.
+   */
+  resolveManagedAccount = (signal, walletAddress) => {
+    if (walletAddress) {
+      return this.resolveManagedAccountByAddress(walletAddress, signal);
+    }
     if (this.managedAccount) return Promise.resolve(this.managedAccount);
     if (this.managedAccountInFlight) {
       return this.raceWithSignal(this.managedAccountInFlight, signal);
@@ -3706,6 +3796,42 @@ var ZeroClient = class _ZeroClient {
     });
     return this.raceWithSignal(this.managedAccountInFlight, signal);
   };
+  // Explicit-wallet variant of resolveManagedAccount. No in-flight dedupe:
+  // this is the rare path (per-wallet pay), the resolution is idempotent, and
+  // the per-address cache absorbs repeat calls.
+  resolveManagedAccountByAddress = async (walletAddress, signal) => {
+    if (this.credentials.kind !== "session") {
+      throw new ZeroAuthError(
+        "auth_no_credentials",
+        "resolveManagedAccount() requires session credentials."
+      );
+    }
+    const canonical = viem.getAddress(walletAddress);
+    const cached = this.managedAccountByAddress.get(canonical.toLowerCase());
+    if (cached) return cached;
+    const startedAtGen = this.managedAccountGen;
+    const wallets = await this.auth.wallets({ signal });
+    const match = wallets.find(
+      (w) => w.walletAddress.toLowerCase() === canonical.toLowerCase()
+    );
+    if (!match || match.source !== "privy_embedded") {
+      throw new ZeroAuthError(
+        "auth_error",
+        `Wallet ${canonical} is not a Privy-embedded wallet on this profile. Managed signing can only use profile wallets (see client.wallet.list()).`
+      );
+    }
+    if (this.managedAccountGen !== startedAtGen) {
+      throw new ZeroAuthError(
+        "auth_session_expired",
+        "Session cleared during managed-account resolution. Retry to rebuild against the current session."
+      );
+    }
+    const acc = createManagedAccount(this, canonical, {
+      explicitWallet: true
+    });
+    this.managedAccountByAddress.set(canonical.toLowerCase(), acc);
+    return acc;
+  };
   // Per-caller signal gate: each caller can reject on their own abort
   // without cancelling the shared underlying promise.
   raceWithSignal = (p, signal) => {
@@ -3736,6 +3862,7 @@ var ZeroClient = class _ZeroClient {
     this.managedAccountAC?.abort();
     this.managedAccountInFlight = null;
     this.managedAccountAC = null;
+    this.managedAccountByAddress.clear();
     this.managedAccountGen++;
   };
   /** @internal — Read cached managed account without triggering resolution. */
@@ -3828,5 +3955,5 @@ exports.normalizeTransportEnvelopeRequest = normalizeTransportEnvelopeRequest;
 exports.paymentHasAnchor = paymentHasAnchor;
 exports.tempoChainLabelFromId = tempoChainLabelFromId;
 exports.unwrapTransportEnvelope = unwrapTransportEnvelope;
-//# sourceMappingURL=chunk-HKF4TRC6.cjs.map
-//# sourceMappingURL=chunk-HKF4TRC6.cjs.map
+//# sourceMappingURL=chunk-2A2ZZ5XR.cjs.map
+//# sourceMappingURL=chunk-2A2ZZ5XR.cjs.map