@zeroxyz/sdk 0.5.0 → 0.6.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.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,18 @@ 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.
 
+**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",

package/dist/{chunk-RY3VFSIE.js → chunk-3YKWO4B2.js}

@@ -126,6 +126,78 @@ var ZeroConfigurationError = class extends ZeroError {
   }
 };
 
+// src/input-envelope.ts
+var asSchemaNode = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : null;
+var extractInputEnvelope = (bodySchema, method) => {
+  const root = asSchemaNode(bodySchema);
+  if (!root) return {};
+  const props = asSchemaNode(root.properties);
+  if (!props) return {};
+  const inputProps = asSchemaNode(asSchemaNode(props.input)?.properties);
+  if (inputProps) {
+    return {
+      queryParams: asSchemaNode(inputProps.queryParams) ?? void 0,
+      body: asSchemaNode(inputProps.body) ?? void 0
+    };
+  }
+  const upperMethod = method.toUpperCase();
+  const isGetLike = upperMethod === "GET" || upperMethod === "DELETE";
+  return isGetLike ? { queryParams: root } : { body: root };
+};
+var unwrapTransportEnvelope = (request2) => {
+  const input = asSchemaNode(asSchemaNode(request2)?.input);
+  if (!input || input.type !== "http") return request2;
+  const body = input.body;
+  const hasBody = body !== void 0 && body !== null && !(typeof body === "object" && Object.keys(body).length === 0);
+  if (hasBody) return body;
+  const qp = asSchemaNode(input.queryParams);
+  if (qp && Object.keys(qp).length > 0) return qp;
+  return null;
+};
+var GET_LIKE = /* @__PURE__ */ new Set(["GET", "HEAD", "DELETE"]);
+var appendQueryParams = (url, params) => {
+  const entries = Object.entries(params).filter(([, v]) => v != null);
+  if (entries.length === 0) return url;
+  try {
+    const u = new URL(url);
+    for (const [k, v] of entries) u.searchParams.set(k, String(v));
+    return u.toString();
+  } catch {
+    const qs = entries.map(
+      ([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`
+    ).join("&");
+    return url.includes("?") ? `${url}&${qs}` : `${url}?${qs}`;
+  }
+};
+var normalizeTransportEnvelopeRequest = (url, opts) => {
+  const { method, body } = opts;
+  if (typeof body !== "string") return { url, method, body };
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    return { url, method, body };
+  }
+  const input = asSchemaNode(asSchemaNode(parsed)?.input);
+  if (!input || input.type !== "http") return { url, method, body };
+  const innerBody = input.body;
+  const hasInnerBody = innerBody !== void 0 && innerBody !== null && !(typeof innerBody === "object" && Object.keys(innerBody).length === 0);
+  const verb = (method ?? (typeof input.method === "string" ? input.method : void 0) ?? (hasInnerBody ? "POST" : "GET")).toUpperCase();
+  if (GET_LIKE.has(verb)) {
+    const qp = asSchemaNode(input.queryParams);
+    return {
+      url: qp ? appendQueryParams(url, qp) : url,
+      method: verb,
+      body: void 0
+    };
+  }
+  return {
+    url,
+    method: verb,
+    body: hasInnerBody ? JSON.stringify(innerBody) : void 0
+  };
+};
+
 // src/chains/eip712.ts
 var KNOWN_EIP712_DOMAINS = {
   // Base mainnet USDC. On-chain `name()` is "USD Coin" (NOT "USDC")
@@ -1144,7 +1216,7 @@ var Payments = class {
 
 // package.json
 var package_default = {
-  version: "0.5.0"};
+  version: "0.6.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -1872,6 +1944,30 @@ var listRunsResponseSchema = z.object({
   runs: z.array(runListItemSchema),
   nextCursor: z.string().nullable()
 });
+var runDetailSchema = z.object({
+  runId: z.string(),
+  status: z.number().nullable(),
+  latencyMs: z.number().nullable(),
+  errorClass: z.string().nullable(),
+  createdAt: z.coerce.date(),
+  cost: z.object({ amount: z.string(), asset: z.string().nullable() }).nullable(),
+  payment: z.object({
+    protocol: z.string(),
+    chain: z.string().nullable(),
+    txHash: z.string().nullable(),
+    mode: z.string().nullable()
+  }).nullable(),
+  capability: z.object({
+    uid: z.string(),
+    slug: z.string(),
+    name: z.string(),
+    url: z.string(),
+    method: z.string(),
+    whatItDoes: z.string().nullable(),
+    tags: z.array(z.string())
+  }),
+  reviewed: z.boolean()
+});
 var createReviewResponseSchema = z.object({
   reviewId: z.string(),
   recorded: z.boolean(),
@@ -1953,6 +2049,15 @@ var Runs = class {
       listRunsResponseSchema
     );
   };
+  get = (runId, opts = {}) => request(
+    this.client,
+    {
+      method: "GET",
+      path: `/v1/runs/${runId}`,
+      signal: opts.signal
+    },
+    runDetailSchema
+  );
   review = (input, opts = {}) => request(
     this.client,
     {
@@ -2483,17 +2588,23 @@ var withDefaultContentType = (headers, body) => {
 var clientFetch = async (client, url, opts = {}) => {
   const startedAt = Date.now();
   const capabilityIdRequested = opts.capabilityId !== void 0;
-  const method = opts.method ?? (opts.body !== void 0 ? "POST" : "GET");
+  const normalized = normalizeTransportEnvelopeRequest(url, {
+    method: opts.method,
+    body: opts.body
+  });
+  const requestUrl = normalized.url;
+  const requestBody = normalized.body;
+  const method = normalized.method ?? (requestBody !== void 0 ? "POST" : "GET");
   const { canRecord: canRecordForResolve } = resolveRecordingClient(
     client,
     opts
   );
-  const resolvePromise = !capabilityIdRequested && canRecordForResolve ? client.capabilities.resolveByUrl(redactUrl(url), method).catch(() => null) : Promise.resolve(null);
-  const probeHeaders = withDefaultContentType(opts.headers, opts.body);
+  const resolvePromise = !capabilityIdRequested && canRecordForResolve ? client.capabilities.resolveByUrl(redactUrl(requestUrl), method).catch(() => null) : Promise.resolve(null);
+  const probeHeaders = withDefaultContentType(opts.headers, requestBody);
   const requestInit = {
     method,
     headers: probeHeaders,
-    body: opts.body,
+    body: requestBody,
     signal: opts.signal
   };
   const configuredFetch = buildConfiguredFetch(client, {
@@ -2504,7 +2615,7 @@ var clientFetch = async (client, url, opts = {}) => {
   const skipReasons = [];
   const warnings = [];
   try {
-    response = await configuredFetch(url, requestInit);
+    response = await configuredFetch(requestUrl, requestInit);
   } catch (err) {
     if (err instanceof ZeroTimeoutError) {
       await recordTimeoutRun(
@@ -2534,13 +2645,13 @@ var clientFetch = async (client, url, opts = {}) => {
       const payCall = requirement.protocol === "x402" ? client.payments.pay : client.payments.payMpp;
       try {
         const paid = await payCall({
-          url,
+          url: requestUrl,
           method,
           // Fresh clone for the paid retry — same rationale as
           // the probe-side clone above. Re-derives the default
           // Content-Type so the paid leg matches the probe.
-          headers: withDefaultContentType(opts.headers, opts.body),
-          body: opts.body,
+          headers: withDefaultContentType(opts.headers, requestBody),
+          body: requestBody,
           maxPay: opts.maxPay,
           account: opts.account,
           signal: opts.signal,
@@ -3188,6 +3299,6 @@ var ZeroClient = class _ZeroClient {
   };
 };
 
-export { Auth, 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_ID, TEMPO_TESTNET_CHAIN_ID, Wallet, ZeroApiError, ZeroAuthError, ZeroClient, ZeroConfigurationError, ZeroError, ZeroPaymentError, ZeroSessionCloseFailedError, ZeroTimeoutError, ZeroValidationError, ZeroWalletError, coerceTempoChainId, createManagedAccount, paymentHasAnchor, tempoChainLabelFromId };
-//# sourceMappingURL=chunk-RY3VFSIE.js.map
-//# sourceMappingURL=chunk-RY3VFSIE.js.map
+export { Auth, 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_ID, TEMPO_TESTNET_CHAIN_ID, Wallet, ZeroApiError, ZeroAuthError, ZeroClient, ZeroConfigurationError, ZeroError, ZeroPaymentError, ZeroSessionCloseFailedError, ZeroTimeoutError, ZeroValidationError, ZeroWalletError, asSchemaNode, coerceTempoChainId, createManagedAccount, extractInputEnvelope, normalizeTransportEnvelopeRequest, paymentHasAnchor, tempoChainLabelFromId, unwrapTransportEnvelope };
+//# sourceMappingURL=chunk-3YKWO4B2.js.map
+//# sourceMappingURL=chunk-3YKWO4B2.js.map