@zeroxyz/sdk 0.4.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-RPL7VC32.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.4.0"};
+  version: "0.6.0"};
 
 // src/version.ts
 var SDK_VERSION = package_default.version;
@@ -1801,6 +1873,11 @@ var capabilityResponseSchema = z.object({
   lastUsedAt: z.string().nullable().optional(),
   lastSuccessfullyRanAt: z.string().nullable().optional()
 });
+var resolveCapabilityResponseSchema = z.object({
+  capabilityId: z.string(),
+  capabilitySlug: z.string(),
+  matchedVia: z.enum(["exact", "template"])
+});
 
 // src/namespaces/capabilities.ts
 var Capabilities = class {
@@ -1817,6 +1894,31 @@ var Capabilities = class {
     },
     capabilityResponseSchema
   );
+  // Resolve a raw endpoint URL + method back to the capability that owns it,
+  // for the `zero fetch <url>` case where the client has no local search
+  // context to match against (a memoized/cross-session URL). Returns null on
+  // 404 — i.e. no match or an ambiguous multi-match, both of which the server
+  // reports as 404 (resolveByUrl fails closed rather than mis-attribute).
+  // The URL travels in the POST body so it stays out of access logs and is
+  // never stored; the caller uses the returned capabilityId to record an
+  // attributed run without the URL ever touching the run row (ZERO-335).
+  resolveByUrl = async (url, method, opts = {}) => {
+    try {
+      return await request(
+        this.client,
+        {
+          method: "POST",
+          path: "/v1/capabilities/resolve",
+          body: { url, method },
+          signal: opts.signal
+        },
+        resolveCapabilityResponseSchema
+      );
+    } catch (err) {
+      if (err instanceof ZeroApiError && err.status === 404) return null;
+      throw err;
+    }
+  };
 };
 var createRunResponseSchema = z.object({
   runId: z.string()
@@ -1842,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(),
@@ -1923,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,
     {
@@ -2397,14 +2532,17 @@ var resolveRecordingClient = (client, opts) => {
   const canRecord = opts.account !== void 0 || credentials.kind === "account" || credentials.kind === "session";
   return { recordingClient, canRecord };
 };
-var recordErrorFetchRun = async (client, opts, result) => {
-  if (opts.capabilityId === void 0) return;
+var recordErrorFetchRun = async (client, opts, result, capabilityIdOverride) => {
+  const effectiveCapId = opts.capabilityId;
+  if (effectiveCapId === void 0) return;
   const { recordingClient, canRecord } = resolveRecordingClient(client, opts);
   if (!canRecord) return;
+  const fetchOriginForRecord = opts.capabilityId === void 0 ? "direct_url" : opts.fetchOrigin;
   try {
     const created = await recordingClient.runs.create({
-      capabilityId: opts.capabilityId,
+      capabilityId: effectiveCapId,
       ...opts.searchId && { searchId: opts.searchId },
+      ...fetchOriginForRecord && { fetchOrigin: fetchOriginForRecord },
       ...result.status !== null && { status: result.status },
       latencyMs: result.latencyMs,
       ...opts.requestSchema && { requestSchema: opts.requestSchema }
@@ -2414,7 +2552,7 @@ var recordErrorFetchRun = async (client, opts, result) => {
   } catch {
   }
 };
-var recordTimeoutRun = async (client, opts, err, startedAt, capabilityIdRequested) => {
+var recordTimeoutRun = async (client, opts, err, startedAt, capabilityIdRequested, capabilityIdOverride) => {
   const result = errorFetchResult(
     startedAt,
     err.message,
@@ -2450,12 +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 probeHeaders = withDefaultContentType(opts.headers, opts.body);
+  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(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, {
@@ -2466,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(
@@ -2496,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,
@@ -2642,7 +2791,15 @@ var clientFetch = async (client, url, opts = {}) => {
     else if (closeFailed)
       skipReasons.push(FETCH_SKIP_REASONS.mppSessionCloseFailedNotRecorded);
   }
-  if (opts.capabilityId !== void 0 && !paidButStill402 && !closeFailed) {
+  const resolvedCap = await resolvePromise;
+  const effectiveCapabilityId = opts.capabilityId ?? resolvedCap?.capabilityId;
+  const capabilityResolution = !capabilityIdRequested && canRecordForResolve ? resolvedCap !== null ? {
+    resolved: true,
+    capabilityId: resolvedCap.capabilityId,
+    capabilitySlug: resolvedCap.capabilitySlug,
+    matchedVia: resolvedCap.matchedVia
+  } : { resolved: false } : void 0;
+  if (effectiveCapabilityId !== void 0 && !paidButStill402 && !closeFailed) {
     const { recordingClient, canRecord } = resolveRecordingClient(client, opts);
     if (!canRecord) {
       skipReasons.push("no_credentials");
@@ -2662,8 +2819,11 @@ var clientFetch = async (client, url, opts = {}) => {
           }
         }
         const result2 = await recordingClient.runs.create({
-          capabilityId: opts.capabilityId,
+          capabilityId: effectiveCapabilityId,
           searchId: opts.searchId,
+          // Auto-resolved runs are always direct_url — they only fire when
+          // no capabilityId was supplied (the direct_url path by definition).
+          ...opts.capabilityId === void 0 ? { fetchOrigin: "direct_url" } : opts.fetchOrigin && { fetchOrigin: opts.fetchOrigin },
           status: response.status,
           latencyMs,
           ...opts.requestSchema && { requestSchema: opts.requestSchema },
@@ -2696,7 +2856,7 @@ var clientFetch = async (client, url, opts = {}) => {
           message: "Failed to record run for fetch",
           meta: {
             url: redactUrl(url),
-            capabilityId: opts.capabilityId,
+            capabilityId: effectiveCapabilityId,
             error: errorMessage2,
             errorCode: code
           }
@@ -2724,6 +2884,8 @@ var clientFetch = async (client, url, opts = {}) => {
     result.runTrackingSkipped = skipReasons;
   }
   if (warnings.length > 0) result.warnings = warnings;
+  if (capabilityResolution !== void 0)
+    result.capabilityResolution = capabilityResolution;
   return result;
 };
 var searchResultSchema = z.object({
@@ -3137,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-RPL7VC32.js.map
-//# sourceMappingURL=chunk-RPL7VC32.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