@zeroxyz/sdk 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.8.0
+
+### Added
+
+- **`CapabilityResponse.instructions`** — optional natural-language field describing how an agent should call this capability (authentication hints, required context, usage notes). Exposed on `capabilities.get()` responses and in the `CapabilityResponse` type. (#693, ZERO-134)
+
+## 0.7.0
+
+### Added
+
+- **`SearchResult.token`** — every search result now carries a short server-issued attribution token (`z_xxx.N` format, where `xxx` is a 6-char base-62 ID shared across all results from the same search and `N` is the 1-based position). Pass it directly as the `id` to `capabilities.get()` or as `capabilityId` to `client.fetch()` — the server resolves it back to the capability and ties the run to the originating search for accurate ranking and analytics. Tokens are generated per-search and expire when the session rolls. (#665)
+- **`isShortToken(id)`** — exported predicate that returns `true` when a string is a `z_xxx.N` attribution token (vs a uid, slug, or URL). Use it to route capabilityId arguments without regex-ing the format yourself. (#665)
+- **`@deprecated`** JSDoc on `GetCapabilityOptions.searchId`, `FetchOptions.searchId`, and `CreateRunInput.searchId` — pass the token as the `id`/`capabilityId` argument instead; the token already embeds the search context. These fields remain in place for back-compat with callers that pass uid + searchId separately. (#665)
+
 ## 0.6.0
 
 ### Added

package/README.md

@@ -104,6 +104,8 @@ Endpoints that don't charge pass straight through: a `200` on the first request
 
 **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.
 
+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.
+
 **The HTTP-transport envelope.** Some capabilities store their request contract as Zero's HTTP-transport envelope — `{ input: { type: "http", method, queryParams, body } }` — rather than a bare body. You don't have to special-case it: `fetch()` detects an envelope body and normalizes it to the real wire request — it **carries the method** (from the envelope's `input.method`, never inferring `POST` from body-presence) and moves a `GET`'s `queryParams` onto the URL query string. So passing the envelope straight through works:
 
 ```ts
@@ -180,7 +182,7 @@ for (const warning of result.warnings ?? []) {
 | `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()`.
+`capabilityId` accepts the capability's `uid` (`cap_…`), `slug`, or an attribution token (`z_xxx.N`) from a `search()` result. Prefer the token when one is available — it lets the server tie the run back to the originating search for accurate ranking and analytics. Pass the uid or slug for direct fetches where no search was performed.
 
 ### `maxPay`
 
@@ -232,8 +234,9 @@ const { capabilities } = await client.search("translate text to french", {
   protocol: "x402", // optional: "x402" | "mpp"
 });
 
-// Capabilities — full detail for one capability by id
-const cap = await client.capabilities.get("cap_abc");
+// Capabilities — full detail for one capability by uid, slug, or attribution token
+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.
 const { amount } = await client.wallet.balance();