@zeroxyz/sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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

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.
 

package/dist/{chunk-T77VVLOM.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.11.0"};
+  version: "0.12.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -2840,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(),
@@ -3787,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-T77VVLOM.js.map
-//# sourceMappingURL=chunk-T77VVLOM.js.map
+//# sourceMappingURL=chunk-KDWESC42.js.map
+//# sourceMappingURL=chunk-KDWESC42.js.map