@zeroxyz/sdk 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.9.0
+
+### Added
+
+- **`CapabilityResponse.pricing`** — the server-resolved price as a single structured object: `{ kind, summary, primary, accepted }`. `summary` is the canonical display string (render it verbatim instead of re-deriving from raw fields); `kind` classifies the price shape (`static | dynamic | session | metered | subscription | free | unknown`); `primary`/`accepted[]` carry the normalized payment options (`protocol`, `network`, `amountUsd`, `per`, `confidence`, optional `depositUsd`). Optional — absent on older API deploys. (#708, ZERO-199)
+- **Price fields the server was already emitting but the SDK schemas silently stripped** (#687, ZERO-199): `CapabilityResponse.priceDynamic` / `priceHint` (usage-priced caps advertise a rate like `"$0.01/result"`, not a flat scalar), `sessionDeposit` (`{ amountUsd, asset }` — the upfront channel deposit for `mode='session'` caps, distinct from the per-call price), `priceStatus` (`priced | proven_free | free_handshake | unknown_unparsed | unprobed`) and `requiresHandshake`, per-rail `asset`/`unit`/`depositMicros`/`planRef` on `paymentMethods[]`, and `SearchResult.protocol`.
+
+## 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

package/README.md

@@ -188,7 +188,7 @@ for (const warning of result.warnings ?? []) {
 
 `maxPay` is your hard per-call ceiling, in USDC. The challenge amount is checked against it **before** anything is signed; an over-cap challenge aborts with `outcome: "payment_failed"` and no on-chain spend. Set it on every paid call — it's the guardrail that keeps a mispriced or hostile endpoint from draining the wallet.
 
-To put a human in the loop before any spend, read the price up front (`cost.amount` is on every search result and on `capabilities.get()`), show it to your user, and only call `fetch()` with `maxPay` once they approve.
+To put a human in the loop before any spend, read the price up front, show it to your user, and only call `fetch()` with `maxPay` once they approve. Prefer `capabilities.get()`'s **`pricing`** object when present: `pricing.summary` is the server-resolved display string (render it verbatim — don't re-derive from raw fields), `pricing.kind` classifies the shape (`static | dynamic | session | metered | subscription | free | unknown`), and `pricing.primary.amountUsd` / `depositUsd` give the structured numbers for sizing `maxPay`. `cost.amount` remains on every search result as the raw advertised scalar, but it flattens usage-priced caps — a `dynamic` cap's real cost scales with input.
 
 ## Wallet & funding
 

package/dist/{chunk-2HZJHVDN.cjs → chunk-O7QJMY3Y.cjs}

@@ -1838,7 +1838,7 @@ var clientFetch = async (client, url, opts = {}) => {
 
 // package.json
 var package_default = {
-  version: "0.7.0"};
+  version: "0.9.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2442,6 +2442,15 @@ var ratingSchema = zod.z.object({
 });
 
 // src/schemas/capabilities.ts
+var pricingOptionSchema = zod.z.object({
+  kind: zod.z.string(),
+  protocol: zod.z.string(),
+  network: zod.z.string().nullable(),
+  amountUsd: zod.z.string().nullable(),
+  per: zod.z.string(),
+  confidence: zod.z.string(),
+  depositUsd: zod.z.string().optional()
+});
 var capabilityResponseSchema = zod.z.object({
   uid: zod.z.string(),
   slug: zod.z.string(),
@@ -2456,8 +2465,33 @@ var capabilityResponseSchema = zod.z.object({
   example: zod.z.object({ request: zod.z.unknown(), response: zod.z.unknown() }).nullable(),
   tags: zod.z.array(zod.z.string()).nullable(),
   exampleAgentPrompt: zod.z.string().nullable().optional(),
+  whatItDoes: zod.z.string().nullable().optional(),
+  resultDescription: zod.z.string().nullable().optional(),
+  failureModes: zod.z.array(zod.z.string()).nullable().optional(),
+  whenToPreferThis: zod.z.string().nullable().optional(),
+  // Agent-facing execution guide (markdown). Covers usage patterns, input
+  // field guidance, cross-cap composition, and known failure modes.
+  // Named after MCP tool convention: description = what it is, instructions = how to use it.
+  instructions: zod.z.string().nullable().optional(),
   displayCostAmount: zod.z.string(),
   displayCostAsset: zod.z.string(),
+  // Whether the upstream advertises variable/usage-based pricing, and the raw
+  // hint string (e.g. "$0.01/result"). The server emits both; without them an
+  // agent sees a single scalar with no signal that the price scales with input
+  // (ZERO-199). Optional so an older API deploy still parses.
+  priceDynamic: zod.z.boolean().optional(),
+  priceHint: zod.z.string().nullable().optional(),
+  // ZERO-199: the authoritative price classification. Only `proven_free` may be
+  // rendered "Free"; `unknown_unparsed` is a parse miss (never free); a parse
+  // miss must not become "0"→Free. Optional so older deploys still parse.
+  priceStatus: zod.z.enum([
+    "priced",
+    "proven_free",
+    "free_handshake",
+    "unknown_unparsed",
+    "unprobed"
+  ]).optional(),
+  requiresHandshake: zod.z.boolean().optional(),
   reviewCount: zod.z.number(),
   rating: ratingSchema,
   priceObserved: zod.z.object({
@@ -2480,9 +2514,27 @@ var capabilityResponseSchema = zod.z.object({
       mode: zod.z.string(),
       costAmount: zod.z.string(),
       costPer: zod.z.string(),
-      priority: zod.z.number()
+      priority: zod.z.number(),
+      // ZERO-199 rail-union fields (optional; older deploys omit them).
+      asset: zod.z.string().nullable().optional(),
+      unit: zod.z.string().optional(),
+      depositMicros: zod.z.number().nullable().optional(),
+      planRef: zod.z.string().nullable().optional()
     })
   ).nullable(),
+  // Recommended channel deposit for a `mode='session'` cap (the seller's
+  // advertised `suggestedDeposit`). Without it an agent can't size an MPP
+  // session channel. The server emits it; optional for older-deploy parsing
+  // (ZERO-199).
+  sessionDeposit: zod.z.object({ amountUsd: zod.z.string(), asset: zod.z.string() }).nullable().optional(),
+  // ZERO-199 P-B — the single resolved price. Prefer `pricing.summary`/`kind`
+  // over re-deriving from the legacy fields. Optional so older deploys parse.
+  pricing: zod.z.object({
+    kind: zod.z.string(),
+    summary: zod.z.string(),
+    primary: pricingOptionSchema.nullable(),
+    accepted: zod.z.array(pricingOptionSchema)
+  }).optional(),
   availabilityStatus: zod.z.enum(["healthy", "unknown", "down"]).nullable().optional(),
   /**
    * @deprecated The API no longer emits `displayStatus`; it has been replaced
@@ -2913,6 +2965,11 @@ var searchResultSchema = zod.z.object({
   url: zod.z.string(),
   urlTemplate: zod.z.string().nullable().optional(),
   cost: zod.z.object({ amount: zod.z.string(), asset: zod.z.string() }),
+  // Payment protocol (x402 | mpp) for this result. The server emits it; the SDK
+  // previously stripped it, leaving an agent unable to tell which handshake to
+  // engage from a search row. Optional/nullable so older deploys still parse
+  // (ZERO-199).
+  protocol: zod.z.string().nullable().optional(),
   reviewCount: zod.z.number().optional(),
   rating: ratingSchema,
   // All-time activation count (non-deleted runs), mirroring capabilities.ts.
@@ -3344,5 +3401,5 @@ exports.normalizeTransportEnvelopeRequest = normalizeTransportEnvelopeRequest;
 exports.paymentHasAnchor = paymentHasAnchor;
 exports.tempoChainLabelFromId = tempoChainLabelFromId;
 exports.unwrapTransportEnvelope = unwrapTransportEnvelope;
-//# sourceMappingURL=chunk-2HZJHVDN.cjs.map
-//# sourceMappingURL=chunk-2HZJHVDN.cjs.map
+//# sourceMappingURL=chunk-O7QJMY3Y.cjs.map
+//# sourceMappingURL=chunk-O7QJMY3Y.cjs.map