@zeroxyz/sdk 0.5.0 → 0.7.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.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
+
+- **Envelope-aware `client.fetch()` routing.** When a request body is Zero's HTTP-transport envelope (`{ input: { type:"http", method, queryParams, body } }` — how many caps store their request contract), `fetch()` now normalizes it into a real wire request: the verb is **carried** (explicit `method` → the envelope's `input.method` → body-presence, in that order) rather than inferred from body-presence, and a GET's `queryParams` are moved onto the URL query string with the body dropped. This stops the SDK from POSTing the ~6,614 indexed GET capabilities that store an MPP-style envelope on an x402 GET endpoint (which 404'd with "Cannot POST"). The envelope is never a wire format, so the normalization is unconditional and protocol-agnostic. (#677)
+- New pure exports for envelope/schema handling, lifted out of the CLI so SDK-direct consumers get them too: `extractInputEnvelope`, `unwrapTransportEnvelope`, `normalizeTransportEnvelopeRequest`, `asSchemaNode`, and the `JsonSchemaNode` type. (#677)
+- **`client.runs.get(runId)`** — fetch a single run's detail. New exports `RunDetail` and `runDetailSchema`. (#667)
+
+## 0.5.0
+
+### Added
+
+- Direct-URL `client.fetch()` calls now record a run via a server-side URL→capability resolve, so a bare URL that missed the local cache is still attributable without the caller supplying a `capabilityId`. The resolve runs concurrently with the probe (no added latency) and is fail-open. (#558, ZERO-335)
+
 ## 0.4.0
 
 ### Added

package/README.md

@@ -104,6 +104,20 @@ 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
+// A GET capability whose schema is the envelope — fetch() routes it to
+// GET https://…/weather/current?city=tokyo (not a POST).
+await client.fetch(cap.url, {
+  body: JSON.stringify({ input: { type: "http", method: "GET", queryParams: { city: "tokyo" } } }),
+});
+```
+
+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).
+
 ```ts
 const result = await client.fetch(url, {
   method: "POST",
@@ -168,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`
 
@@ -220,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();