@zeroxyz/sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.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
+
+- **BREAKING: `client.wallet.address` is now an async method** (was a sync getter). In account mode it resolves the configured account's address locally (no network, same value as before); in session mode — where the getter used to return `null` — it now resolves the user's managed (Privy-embedded) wallet, provisioning one on first call. It throws instead of returning `null` when the client has no credentials. Migration: `client.wallet.address` → `await client.wallet.address()`. (ZERO-433)
+- **BREAKING: `client.wallet.migrateAuthorization()` removed** along with the `MigrateAuthorization` / `MigrateAuthorizationResponse` types. It existed solely for the CLI's legacy BYO→managed sweep (`zero wallet migrate`), which is removed — usage was near zero and net-new users never need it (ZERO-465). The server route still exists; its removal is tracked separately.
+
+### Added
+
+- **`client.auth.agent`** — the auth.md agent-account lifecycle (AuthKit Agents), moved from the CLI so any consumer can mint and claim autonomous agent accounts: `signup()` (anonymous registration → assertion exchange → Zero session, all in one call), plus the granular `register()`, `exchangeAssertion()`, `exchangeAtZero()`, `startClaim()`, `completeClaim()`, and `endpoints()` (RFC 9728/8414 discovery, cached). Failures on the AuthKit-hosted surface throw the new `ZeroAgentAuthError` (`status`, `body`, `serverCode`). Exported types: `AgentSignupResult`, `AgentRegistration`, `AgentToken`, `AgentZeroSession`, `AgentClaimAttempt`, `AgentVerifiedIdentity`, `CompleteClaimResult`, `AgentAuthEndpoints`. (ZERO-433)
+- **`client.ping()`** — polls `/health` until the API is ready (bounded attempts, never throws). For warming a cold container before dependent work. (ZERO-433)
+- **`BugReports.create()` generates an idempotency key by default** when `idempotencyKey` is omitted; pass `contextSeed` to make the auto-key deterministic per context. Previously only the CLI deduplicated bug reports. (ZERO-433)
+- Pure helpers lifted from the CLI so all consumers share them: `inferSchema(value)`, `tryParseJson(text)`, `urlMatchesTemplate(url, template)`, plus schema-rendering helpers (`sampleValueFor`, `placeholderFor`, `paramAttrs`, `schemaTypeLabel`, `constraintHint`) and `centsToDollars(cents)`. A number of further exports (display formatters, chain constants, `detectAgentHost`, redaction helpers) are marked `@internal` — they exist so Zero's own surfaces render identically and aren't part of the supported partner contract. (ZERO-433)
+
 ## 0.9.0
 
 ### Added

package/README.md

@@ -118,6 +118,14 @@ await client.fetch(cap.url, {
 
 If you'd rather inspect the schema yourself, the SDK exports the pure helpers it uses: `extractInputEnvelope(bodySchema, method)` (the query-param / body schema nodes), `unwrapTransportEnvelope(exampleRequest)` (the inner request from a stored example), and `normalizeTransportEnvelopeRequest(url, { method, body })` (the `{ url, method, body }` the wire request should use).
 
+Additional utilities exported from `@zeroxyz/sdk`:
+
+- `inferSchema(value)` — deterministic structural walk of a JSON value to a JSON-schema-ish draft (types + field names, no values). Useful for logging anonymized request/response shapes.
+- `tryParseJson(text)` — returns parsed JSON or `null` on failure (no throw).
+- `urlMatchesTemplate(url, template)` — returns `true` when a URL matches a path template like `https://api.example.com/users/{id}`. Mirrors the server-side `templateToRegex` logic.
+
+A few further exports (display formatters, chain constants) exist so Zero's own surfaces (CLI, MCP plugin) render identically; they're marked `@internal` and aren't part of the supported partner contract.
+
 ```ts
 const result = await client.fetch(url, {
   method: "POST",
@@ -178,7 +186,7 @@ for (const warning of result.warnings ?? []) {
 | `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. |
+| `upstreamError` | `UpstreamError?` | Present on `server_error` — the capability's own 4xx/5xx detail (`status`, `message`, `snippetHash`). Carries a `fixHint` string for caller-fixable 4xx shapes (wrong HTTP method, unparseable JSON body, unrecognized/extra fields, content-type mismatch, missing required field). |
 | `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`. |
 
@@ -200,8 +208,9 @@ The wallet you construct the client with **is** the agent's identity — paid ca
 The same two primitives serve both:
 
 ```ts
-// The configured address (null in session mode until the first paid call resolves it).
-client.wallet.address;
+// The address this client acts as. Account mode resolves locally; session
+// mode resolves the user's primary managed wallet (provisioning on first call).
+await 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"
@@ -212,23 +221,37 @@ const onBase     = await client.wallet.balance({ chain: "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.
+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…" });
 ```
 
-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.
+`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
 
 Beyond `search()` and `fetch()`, the client groups the rest of the API into resource namespaces:
 
 ```ts
-// Search — ranked capabilities for a query (no auth required)
+// Search — ranked capabilities for a query (no auth required).
+// No implicit price cap: omitting maxCost returns results at any price.
+// Pass a value to cap costs (e.g. "0.05" for a tight cap, "0" for free-only).
 const { capabilities } = await client.search("translate text to french", {
   maxCost: "0.05",  // optional: only results at or under this price
   protocol: "x402", // optional: "x402" | "mpp"
@@ -238,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" });
 
@@ -272,8 +297,33 @@ await client.auth.logout(refreshToken); // revoke the session server-side
 const device = await client.auth.device.start();
 console.log(device.verificationUri, device.userCode);
 const grant = await client.auth.device.poll(device.deviceCode);
+
+// Agent accounts (auth.md) — fully autonomous signup, no browser or human.
+// Persist registration.claimToken + registration.identityAssertion securely:
+// they are returned exactly once. `session` is a Zero session for the account.
+const { registration, session } = await client.auth.agent.signup();
+
+// A human can claim ownership of the account later. startClaim() returns a
+// hosted URL; the page shows the HUMAN a pairing code (the reverse of the
+// device flow) which they read back for completeClaim().
+if (registration.claimToken) {
+  const attempt = await client.auth.agent.startClaim({
+    claimToken: registration.claimToken,
+    email: "human@example.com",
+  });
+  console.log(attempt.verificationUri);
+  const claimed = await client.auth.agent.completeClaim({
+    claimToken: registration.claimToken,
+    userCode: "1234-5678", // read back by the human
+  });
+  // claimed.status: "ok" | "not_confirmed" | "invalid_code" | "expired" —
+  // on "ok", exchange the fresh assertion for a post-claim session:
+  //   exchangeAssertion(claimed.identityAssertion) → exchangeAtZero(accessToken)
+}
 ```
 
+Errors from the AuthKit-hosted agent-auth surface throw `ZeroAgentAuthError` (`status`, `body`, and `serverCode` — the server's own error code, e.g. `claim_expired`).
+
 ## Multi-tenant servers
 
 A server that signs as a different end-user wallet on each request shouldn't build a fresh `ZeroClient` every call. Pass the wallet per call, or derive a reusable sub-client: