@zeroxyz/sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.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
+
+- **`client.wallet.import()`** — link an existing self-custody wallet to the session user by private key (`{ privateKey, makePrimary? }` → the linked wallet). 409s when the wallet is already linked to this or another profile. New export `ImportWalletOptions`. (ZERO-478)
+- **`client.wallet.setPrimary()` / `client.wallet.remove()`** — session-mode multi-wallet management: switch the primary payer wallet, or unlink a wallet (rejected for the primary wallet or a non-zero balance). New exports `SetPrimaryWalletOptions` / `RemoveWalletOptions`. (ZERO-478)
+- **`UserWalletDto.importedAt`** — set on wallets linked via `wallet.import()`, absent/null otherwise. (ZERO-478)
+
 ## 0.10.0
 
 ### Changed

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.
 
@@ -223,14 +223,26 @@ 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 the `wallet.address()` result — 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:
+In **session mode** (acting for a Zero user) wallets are managed server-side, and a few 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)
+
+// 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.
+const imported = await client.wallet.import({
+  privateKey: "0x…",
+  makePrimary: true,
+});
+
+// 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…" });
 ```
 
-`wallet.address()` covers the common case (resolve — or provision — the primary managed wallet); reach for `list()`/`provision()` directly only when you need the full wallet objects or explicit provisioning.
+`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.
 
 ## Namespaces
 
@@ -249,7 +261,9 @@ const { capabilities } = await client.search("translate text to french", {
 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. See "Wallet & funding" above.
+// Wallet — balance, one-time funding URL, and (session mode) multi-wallet
+// management: list / provision / import / setPrimary / remove. See
+// "Wallet & funding" above.
 const { amount } = await client.wallet.balance();
 const fundUrl    = await client.wallet.fundingUrl({ amount: "10" });
 

package/dist/{chunk-A7WZYQXS.js → chunk-KDWESC42.js}

@@ -589,6 +589,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) {
@@ -1162,7 +1163,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();
@@ -1179,7 +1180,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.`
       );
@@ -1950,7 +1951,7 @@ var clientFetch = async (client, url, opts = {}) => {
 
 // package.json
 var package_default = {
-  version: "0.10.0"};
+  version: "0.12.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2441,6 +2442,7 @@ var userWalletDtoSchema = z.object({
   source: z.enum(["self_custody", "privy_embedded"]),
   isPrimary: z.boolean(),
   linkedAt: z.union([z.string(), z.date()]).nullable().optional(),
+  importedAt: z.union([z.string(), z.date()]).nullable().optional(),
   delegationGranted: z.boolean(),
   signerQuorumId: z.string().nullable(),
   // Per-transaction USDC cap in base units (6 dp). null = unlimited, 0 = free-only.
@@ -2839,6 +2841,12 @@ var capabilityResponseSchema = z.object({
   bodySchema: z.record(z.string(), z.unknown()).nullable(),
   responseSchema: z.record(z.string(), z.unknown()).nullable(),
   example: z.object({ request: z.unknown(), response: 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: z.record(z.string(), z.unknown()).nullable().optional(),
   tags: z.array(z.string()).nullable(),
   exampleAgentPrompt: z.string().nullable().optional(),
   whatItDoes: z.string().nullable().optional(),
@@ -3226,6 +3234,48 @@ var Wallet = class {
     },
     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).
+  import = (opts) => request(
+    this.client,
+    {
+      method: "POST",
+      path: "/v1/users/me/wallets/import",
+      body: {
+        privateKey: opts.privateKey,
+        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {}
+      },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Make one of the session user's linked wallets the primary payer.
+  // Session-only. 404s when the address isn't linked to the user.
+  setPrimary = (opts) => request(
+    this.client,
+    {
+      method: "PATCH",
+      path: "/v1/users/me/wallets/primary",
+      body: { walletAddress: opts.walletAddress },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Unlink a wallet from the session user. Session-only. 409s on the primary
+  // wallet or a non-zero balance (the error message says which); 404s when
+  // the address isn't linked. Responds 204 — resolves to void.
+  remove = async (opts) => {
+    await request(
+      this.client,
+      {
+        method: "DELETE",
+        path: `/v1/users/me/wallets/${opts.walletAddress}`,
+        signal: opts.signal
+      },
+      z.undefined()
+    );
+  };
   // Routes by identity: account mode signs EIP-191 against /v1/wallet/fund-url,
   // session mode hits /v1/users/me/fund-url (Bearer-authed, wallet resolved
   // server-side). Both honor `provider` (coinbase | stripe).
@@ -3744,5 +3794,5 @@ var ZeroClient = class _ZeroClient {
 };
 
 export { Auth, AuthAgent, AuthDevice, BUG_REPORT_CATEGORIES, BugReports, Capabilities, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, FETCH_SKIP_REASONS, FETCH_WARNINGS, Payments, Runs, SDK_VERSION, TEMPO_CHAIN_ID2 as TEMPO_CHAIN_ID, TEMPO_TESTNET_CHAIN_ID, USDC_BASE, USDC_DECIMALS, USDC_TEMPO, Wallet, ZeroAgentAuthError, ZeroApiError, ZeroAuthError, ZeroClient, ZeroConfigurationError, ZeroError, ZeroPaymentError, ZeroSessionCloseFailedError, ZeroTimeoutError, ZeroValidationError, ZeroWalletError, asSchemaNode, coerceTempoChainId, createManagedAccount, extractInputEnvelope, isShortToken, normalizeTransportEnvelopeRequest, paymentHasAnchor, tempoChainLabelFromId, unwrapTransportEnvelope };
-//# sourceMappingURL=chunk-A7WZYQXS.js.map
-//# sourceMappingURL=chunk-A7WZYQXS.js.map
+//# sourceMappingURL=chunk-KDWESC42.js.map
+//# sourceMappingURL=chunk-KDWESC42.js.map