@zeroxyz/cli 1.26.1 → 1.27.0

package/dist/index.js

@@ -78668,7 +78668,7 @@ init_esm_shims();
 // ../sdk/dist/index.js
 init_esm_shims();
 
-// ../sdk/dist/chunk-YB3TVCUC.js
+// ../sdk/dist/chunk-MQZT5KEN.js
 init_esm_shims();
 
 // ../../node_modules/.pnpm/viem@2.52.2_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@6.0.6_zod@4.3.6/node_modules/viem/_esm/index.js
@@ -164225,6 +164225,20 @@ var ERC20_BALANCE_ABI = [
   }
 ];
 var USDC_DECIMALS = 6;
+var ERROR_MAX = 500;
+var redactUrl = (raw) => {
+  try {
+    const parsed = new URL(raw);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return "<invalid-url>";
+  }
+};
+var truncateError = (raw) => raw.length > ERROR_MAX ? `${raw.slice(0, ERROR_MAX)}\u2026` : raw;
+var package_default = {
+  version: "0.20.0"
+};
+var SDK_VERSION2 = package_default.version;
 var ZeroError = class extends Error {
   code;
   constructor(code, message2, options) {
@@ -164384,10 +164398,6 @@ var normalizeTransportEnvelopeRequest = (url4, opts) => {
     body: hasInnerBody ? JSON.stringify(innerBody) : void 0
   };
 };
-var package_default = {
-  version: "0.19.1"
-};
-var SDK_VERSION2 = package_default.version;
 var refreshResponseSchema = external_exports3.object({
   accessToken: external_exports3.string(),
   refreshToken: external_exports3.string()
@@ -165994,7 +166004,7 @@ var isTextContentType = (contentType) => {
   const lower = contentType.toLowerCase();
   return TEXT_CONTENT_TYPES.some((marker) => lower.includes(marker));
 };
-var redactUrl = (url4) => {
+var redactUrl2 = (url4) => {
   try {
     const u = new URL(url4);
     return `${u.origin}${u.pathname}`;
@@ -166306,7 +166316,7 @@ var resolveRecordingClient = (client, opts) => {
 var recordErrorFetchRun = async (client, opts, result, capabilityIdOverride, requestUrl, requestMethod) => {
   const effectiveCapId = capabilityIdOverride ?? opts.capabilityId;
   const urlTarget = requestUrl ? {
-    requestUrl: redactUrl(requestUrl),
+    requestUrl: redactUrl2(requestUrl),
     ...requestMethod && { requestMethod }
   } : void 0;
   const runTarget = effectiveCapId !== void 0 ? { capabilityId: effectiveCapId, ...urlTarget } : urlTarget ?? null;
@@ -166391,7 +166401,7 @@ var clientFetch = async (client, url4, opts = {}) => {
     client,
     opts
   );
-  const resolvePromise = !capabilityIdRequested && canRecordForResolve ? client.capabilities.resolveByUrl(redactUrl(requestUrl), method).catch(() => null) : Promise.resolve(null);
+  const resolvePromise = !capabilityIdRequested && canRecordForResolve ? client.capabilities.resolveByUrl(redactUrl2(requestUrl), method).catch(() => null) : Promise.resolve(null);
   const probeHeaders = withDefaultContentType(opts.headers, requestBody);
   const requestInit = {
     method,
@@ -166676,9 +166686,9 @@ var clientFetch = async (client, url4, opts = {}) => {
   } : { resolved: false } : void 0;
   const runTarget = effectiveCapabilityId !== void 0 ? {
     capabilityId: effectiveCapabilityId,
-    requestUrl: redactUrl(requestUrl),
+    requestUrl: redactUrl2(requestUrl),
     requestMethod: method
-  } : { requestUrl: redactUrl(requestUrl), requestMethod: method };
+  } : { requestUrl: redactUrl2(requestUrl), requestMethod: method };
   const fetchOutcome = computeOutcome(response.status, payment, warnings);
   {
     const { recordingClient, canRecord } = resolveRecordingClient(client, opts);
@@ -166745,7 +166755,7 @@ var clientFetch = async (client, url4, opts = {}) => {
           level: "warn",
           message: "Failed to record run for fetch",
           meta: {
-            url: redactUrl(url4),
+            url: redactUrl2(url4),
             capabilityId: effectiveCapabilityId,
             error: errorMessage2,
             errorCode: code
@@ -168074,6 +168084,219 @@ var Wallet = class {
 var DEFAULT_BASE_URL = "https://api.zero.xyz";
 var DEFAULT_TIMEOUT_MS = 18e4;
 var DEFAULT_MAX_RETRIES = 2;
+var QUERY_MAX = 200;
+var toAnalyticsWallet = (address5) => address5.toLowerCase();
+var SAFE_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "DOMException",
+  "Error",
+  "TypeError",
+  "ZeroAgentAuthError",
+  "ZeroApiError",
+  "ZeroAuthError",
+  "ZeroConfigurationError",
+  "ZeroError",
+  "ZeroInsufficientFundsError",
+  "ZeroPaymentError",
+  "ZeroSessionCloseFailedError",
+  "ZeroTimeoutError",
+  "ZeroValidationError",
+  "ZeroWalletError"
+]);
+var SAFE_ERROR_CODES = /* @__PURE__ */ new Set([
+  "api_error",
+  "auth_error",
+  "auth_no_credentials",
+  "auth_session_expired",
+  "configuration_error",
+  "insufficient_funds",
+  "payment_error",
+  "payment_session_close_failed",
+  "timeout_error",
+  "validation_error",
+  "wallet_error"
+]);
+var safeErrorLabel = (error98, fallback2) => {
+  const record3 = typeof error98 === "object" && error98 !== null ? error98 : null;
+  const name = typeof record3?.name === "string" && SAFE_ERROR_NAMES.has(record3.name) ? record3.name : "Error";
+  const code = typeof record3?.code === "string" && SAFE_ERROR_CODES.has(record3.code) ? record3.code : fallback2;
+  return `${name}:${code}`;
+};
+var sanitizeRunTrackingSkipReason = (reason) => reason.split(":", 1)[0] ?? "run_tracking_failed";
+var outcomeToErrorClass = (outcome, status) => {
+  switch (outcome) {
+    case "insufficient_funds":
+      return "insufficient_funds";
+    case "payment_failed":
+      return "payment_failed";
+    case "payment_rejected":
+    case "payment_close_failed":
+      return "payment_rejected";
+    case "network_error":
+      return "network";
+    case "server_error":
+      if (status !== null && status >= 400 && status < 500)
+        return "upstream_4xx";
+      if (status !== null && status >= 500) return "upstream_5xx";
+      return "unknown";
+    default:
+      return "unknown";
+  }
+};
+var classifyFetchError = (error98) => {
+  const record3 = typeof error98 === "object" && error98 !== null ? error98 : null;
+  const status = typeof record3?.status === "number" ? record3.status : null;
+  const code = typeof record3?.code === "string" ? record3.code : null;
+  switch (code) {
+    case "validation_error":
+      return { errorClass: "schema_validation_failed", status };
+    case "timeout_error":
+      return { errorClass: "network", status };
+    case "auth_error":
+    case "auth_session_expired":
+    case "auth_no_credentials":
+      return { errorClass: "auth_missing", status };
+    case "insufficient_funds":
+      return { errorClass: "insufficient_funds", status };
+    case "payment_error":
+      return { errorClass: "payment_failed", status };
+    case "payment_session_close_failed":
+      return { errorClass: "payment_rejected", status };
+    case "api_error":
+      if (status !== null && status >= 400 && status < 500)
+        return { errorClass: "upstream_4xx", status };
+      if (status !== null && status >= 500)
+        return { errorClass: "upstream_5xx", status };
+      return { errorClass: "unknown", status };
+    default:
+      return { errorClass: "unknown", status };
+  }
+};
+var isCallerAbort = (error98) => {
+  const record3 = typeof error98 === "object" && error98 !== null ? error98 : null;
+  if (record3?.name === "AbortError") return true;
+  if (record3?.code !== "api_error" || record3.status !== 0) return false;
+  const cause = typeof record3.cause === "object" && record3.cause !== null ? record3.cause : null;
+  return cause?.name === "AbortError";
+};
+var AnalyticsEmitter = class {
+  isEnabled;
+  sink;
+  distinctIdOverride;
+  extraProps;
+  // Mutable: session-mode clients don't know their wallet until the managed
+  // account resolves. setWalletAddress stamps it so later events attribute
+  // correctly and the wallet becomes the distinctId fallback.
+  walletAddress;
+  constructor(opts, initialWallet) {
+    this.isEnabled = opts?.enabled === true && typeof opts.capture === "function";
+    this.sink = this.isEnabled ? opts?.capture : void 0;
+    this.distinctIdOverride = opts?.distinctId;
+    this.extraProps = opts?.properties ?? {};
+    this.walletAddress = this.isEnabled && initialWallet ? toAnalyticsWallet(initialWallet) : null;
+  }
+  setWalletAddress(address5) {
+    this.walletAddress = toAnalyticsWallet(address5);
+  }
+  emit(event, properties) {
+    if (!this.sink) return;
+    const distinctId = this.distinctIdOverride ?? this.walletAddress ?? null;
+    try {
+      this.sink({
+        event,
+        distinctId,
+        properties: {
+          ...this.extraProps,
+          // SDK-native truth wins over caller enrichment. Per-call/base props
+          // may attach context but cannot rewrite outcomes, IDs, or filters.
+          ...properties,
+          // Reserved stamps always win (ZERO-43: a stray same-named prop must
+          // not clobber the cross-surface dimensions).
+          source: "sdk",
+          sdk_version: SDK_VERSION2,
+          wallet_address: this.walletAddress
+        }
+      });
+    } catch {
+    }
+  }
+  search(query, opts, res) {
+    if (!this.sink) return;
+    this.emit("sdk_search", {
+      // Caller-side context is enrichment only: native fields below win if
+      // an adopter accidentally reuses one of their names.
+      ...opts.analytics?.props ?? {},
+      // Truncate with a trailing ellipsis — same shape as truncateError and
+      // the CLI's truncateQuery, so a consumer mapping this back to its own
+      // event (e.g. CLI search_executed) is byte-for-byte identical.
+      query: query.length > QUERY_MAX ? `${query.slice(0, QUERY_MAX)}\u2026` : query,
+      query_length: query.length,
+      result_count: res.capabilities.length,
+      search_id: res.searchId,
+      total: res.total,
+      has_more: res.hasMore,
+      offset: opts.offset ?? null,
+      limit: opts.limit ?? null,
+      free_only: opts.freeOnly ?? null,
+      max_cost: opts.maxCost ?? null,
+      protocol: opts.protocol ?? null,
+      availability_status: opts.availabilityStatus ?? null,
+      include_all: opts.includeAll ?? null,
+      listing_source: opts.source ?? null,
+      exclude_listing_source: opts.excludeSource ?? null
+    });
+  }
+  fetchExecuted(url4, opts, res) {
+    if (!this.sink) return;
+    const resolution = res.capabilityResolution;
+    this.emit("fetch_executed", {
+      // Caller-side context is enrichment only; execution truth below wins.
+      ...opts.analytics?.props ?? {},
+      url: redactUrl(url4),
+      status: res.status,
+      outcome: res.outcome,
+      error_class: res.outcome === "success" ? null : outcomeToErrorClass(res.outcome, res.status),
+      latency_ms: res.latencyMs,
+      has_payment: res.payment !== null,
+      payment_protocol: res.payment?.protocol ?? null,
+      payment_amount: res.payment?.amount ?? null,
+      // Opaque cap uid / slug / attribution token — not PII, useful for
+      // joining back to the capabilities table in BI.
+      capability_id: opts.capabilityId ?? null,
+      capability_uid: resolution?.resolved ? resolution.capabilityId ?? null : null,
+      capability_slug: resolution?.resolved ? resolution.capabilitySlug ?? null : null,
+      search_id: opts.searchId ?? null,
+      // Always-present correlation key (runId is null exactly when recording
+      // failed), so dashboards can join the event to the execution even then.
+      fetch_id: res.fetchId,
+      run_id: res.runId,
+      run_tracked: res.runId !== null,
+      run_tracking_skipped: res.runTrackingSkipped?.map(sanitizeRunTrackingSkipReason) ?? null,
+      // Upstream response text can contain credentials or user content. Keep
+      // only the already-derived client-side hash/length for clustering.
+      error_snippet_hash: res.upstreamError?.snippetHash ?? null,
+      error_snippet_length: res.upstreamError?.snippetLength ?? null
+    });
+  }
+  fetchError(url4, opts, error98, errorClass, status) {
+    if (!this.sink) return;
+    this.emit("fetch_error", {
+      url: redactUrl(url4),
+      error_class: errorClass,
+      status,
+      capability_id: opts.capabilityId ?? null,
+      search_id: opts.searchId ?? null,
+      error: safeErrorLabel(error98, errorClass)
+    });
+  }
+  walletResolved(address5, walletSource) {
+    if (!this.sink) return;
+    this.setWalletAddress(address5);
+    this.emit("sdk_wallet_resolved", {
+      resolved_wallet_address: toAnalyticsWallet(address5),
+      wallet_source: walletSource
+    });
+  }
+};
 var noopRefresh = async () => {
 };
 var searchResultSchema = external_exports3.object({
@@ -168156,6 +168379,13 @@ var ZeroClient = class _ZeroClient {
   fetchImpl;
   fetchOptions;
   logger;
+  analyticsOptions;
+  // Opt-in telemetry (ZERO-434). Always constructed; a no-op when analytics
+  // was omitted/disabled (its methods short-circuit before the sink), so the
+  // hot paths carry no branch of their own. Kept private so the supported
+  // public surface is the constructor option + emitted event types, not the
+  // mutable emitter implementation.
+  analytics;
   // Private — read via getCredentials(), mutate only via applyRefreshedTokens().
   // Keeping a single mutator funnel is what lets the transport replay
   // requests with a fresh access token after a 401 → refresh.
@@ -168214,6 +168444,7 @@ var ZeroClient = class _ZeroClient {
     this.fetchImpl = options.fetch ?? ((...args) => globalThis.fetch(...args));
     this.fetchOptions = options.fetchOptions;
     this.logger = options.logger;
+    this.analyticsOptions = options.analytics;
     this.refreshOverride = options.refresh;
     this.withAccountCache = options._sharedAccountCache ?? /* @__PURE__ */ new Map();
     this.auth = new Auth(this);
@@ -168222,6 +168453,11 @@ var ZeroClient = class _ZeroClient {
     this.payments = new Payments(this);
     this.runs = new Runs(this);
     this.wallet = new Wallet(this);
+    const initialWallet = this.credentials.kind === "account" ? this.credentials.account.address : null;
+    this.analytics = new AnalyticsEmitter(options.analytics, initialWallet);
+    if (initialWallet && this.analytics.isEnabled) {
+      this.analytics.walletResolved(initialWallet, "self_custody");
+    }
   }
   // Convenience factory: derives a viem account from a raw 0x-prefixed
   // private key and constructs a client in account mode. Equivalent to
@@ -168329,7 +168565,8 @@ var ZeroClient = class _ZeroClient {
     defaultHeaders: { ...this.defaultHeaders },
     fetch: this.fetchImpl,
     fetchOptions: this.fetchOptions ? { ...this.fetchOptions } : void 0,
-    logger: this.logger
+    logger: this.logger,
+    analytics: this.analyticsOptions
   });
   // Returns a new client bound to a different viem account. Mirrors
   // withSession for the self-custody auth path — multi-tenant servers
@@ -168381,6 +168618,7 @@ var ZeroClient = class _ZeroClient {
       fetch: this.fetchImpl,
       fetchOptions: this.fetchOptions ? { ...this.fetchOptions } : void 0,
       logger: this.logger,
+      analytics: this.analyticsOptions,
       _sharedAccountCache: this.withAccountCache
     });
     this.withAccountCache.set(key, sub);
@@ -168441,6 +168679,7 @@ var ZeroClient = class _ZeroClient {
       }
       const acc = createManagedAccount(this, getAddress(primary.walletAddress));
       this.managedAccount = acc;
+      this.analytics.walletResolved(primary.walletAddress, "privy_embedded");
       return acc;
     })().finally(() => {
       if (this.managedAccountGen === startedAtGen) {
@@ -168484,6 +168723,7 @@ var ZeroClient = class _ZeroClient {
       explicitWallet: true
     });
     this.managedAccountByAddress.set(canonical.toLowerCase(), acc);
+    this.analytics.walletResolved(match.walletAddress, "privy_embedded");
     return acc;
   };
   // Per-caller signal gate: each caller can reject on their own abort
@@ -168524,9 +168764,9 @@ var ZeroClient = class _ZeroClient {
   // `search` is a flat method, not a namespace — it's the hot path most
   // consumers hit first, and Stripe/Anthropic/OpenAI all keep their primary
   // entry point flat for the same reason.
-  search = (query, opts = {}) => {
-    const { signal, ...rest } = opts;
-    return request2(
+  search = async (query, opts = {}) => {
+    const { signal, analytics: _analytics, ...rest } = opts;
+    const response = await request2(
       this,
       {
         method: "POST",
@@ -168536,11 +168776,25 @@ var ZeroClient = class _ZeroClient {
       },
       searchResponseSchema
     );
+    this.analytics.search(query, opts, response);
+    return response;
   };
   // Paid fetch — search → get → fetch is Zero's canonical loop. The hot
   // path is flat on the client, same rationale as `search` above.
   // Orchestration lives in fetch.ts so this class stays readable.
-  fetch = (url4, opts = {}) => clientFetch(this, url4, opts);
+  fetch = async (url4, opts = {}) => {
+    try {
+      const result = await clientFetch(this, url4, opts);
+      this.analytics.fetchExecuted(url4, opts, result);
+      return result;
+    } catch (error98) {
+      if (this.analytics.isEnabled && !isCallerAbort(error98)) {
+        const { errorClass, status } = classifyFetchError(error98);
+        this.analytics.fetchError(url4, opts, error98, errorClass, status);
+      }
+      throw error98;
+    }
+  };
   // Poll the API server's /health endpoint until it responds OK. Useful for
   // warming up a cold container before spawning a subprocess that needs the
   // API ready. Resolves when healthy, resolves (silently) when maxAttempts
@@ -168659,16 +168913,6 @@ var tryParseJson2 = (text) => {
     return null;
   }
 };
-var ERROR_MAX = 500;
-var redactUrl2 = (raw) => {
-  try {
-    const parsed = new URL(raw);
-    return `${parsed.origin}${parsed.pathname}`;
-  } catch {
-    return raw;
-  }
-};
-var truncateError = (raw) => raw.length > ERROR_MAX ? `${raw.slice(0, ERROR_MAX)}\u2026` : raw;
 var schemaTypeLabel = (node) => {
   const t = node.type;
   if (typeof t === "string") return t;
@@ -168782,7 +169026,7 @@ var placeholderFor = (fieldName, propSchema) => String(sampleValueFor(fieldName,
 
 // package.json
 var package_default2 = {
-  version: "1.26.1"};
+  version: "1.27.0"};
 
 // src/app.ts
 init_esm_shims();
@@ -170494,7 +170738,7 @@ var fetchCommand = (appContext) => new Command("fetch").description(
         const message2 = err instanceof Error ? err.message : "Failed to read request body";
         analyticsService.capture("fetch_error", {
           cliErrorClass: /exceeds the .* byte local cap/.test(message2) ? "payload_too_large" : "schema_validation_failed",
-          url: redactUrl2(resolvedUrl),
+          url: redactUrl(resolvedUrl),
           error: truncateError(message2)
         });
         console.error(message2);
@@ -170601,13 +170845,28 @@ var fetchCommand = (appContext) => new Command("fetch").description(
               }
             }
             return {};
+          },
+          // fetch_executed is emitted by the SDK (ZERO-434) and mapped
+          // back to the CLI taxonomy in captureSdk. These are the
+          // CLI-only props the SDK can't compute; they ride onto the
+          // emitted event verbatim. The recovered capabilityUid/Slug on
+          // the bare-URL path come from the SDK's own capabilityResolution
+          // (surfaced on the SDK-origin fetch_executed), NOT from here.
+          analytics: {
+            props: {
+              capabilityId: capabilityId ?? void 0,
+              capabilityUid: capabilityUid ?? void 0,
+              capabilitySlug: capabilitySlug ?? void 0,
+              signingSource: appContext.services.signing?.source ?? "none",
+              fetchOrigin
+            }
           }
         });
       } catch (err) {
         const message2 = err instanceof Error ? err.message : "Fetch failed";
         analyticsService.capture("fetch_error", {
           cliErrorClass: "network",
-          url: redactUrl2(resolvedUrl),
+          url: redactUrl(resolvedUrl),
           error: truncateError(message2)
         });
         console.error(`  Fetch failed: ${message2}`);
@@ -170615,7 +170874,6 @@ var fetchCommand = (appContext) => new Command("fetch").description(
         return;
       }
       const {
-        fetchId,
         runId,
         status,
         latencyMs,
@@ -170706,7 +170964,7 @@ var fetchCommand = (appContext) => new Command("fetch").description(
           capabilityUid = capabilityResolution.capabilityId ?? capabilityUid;
           capabilitySlug = capabilityResolution.capabilitySlug ?? capabilitySlug;
           analyticsService.capture("capability_resolution_recovered", {
-            url: redactUrl2(resolvedUrl),
+            url: redactUrl(resolvedUrl),
             method,
             capabilityUid: capabilityResolution.capabilityId,
             capabilitySlug: capabilityResolution.capabilitySlug,
@@ -170720,42 +170978,11 @@ var fetchCommand = (appContext) => new Command("fetch").description(
             );
           }
           analyticsService.capture("capability_resolution_missed", {
-            url: redactUrl2(resolvedUrl),
+            url: redactUrl(resolvedUrl),
             method
           });
         }
       }
-      analyticsService.capture("fetch_executed", {
-        // The correlation key: joins this client event to the server's
-        // run_started / run_completed / payment_processed, and to the run
-        // row itself. Works even when runId is null — i.e. exactly when
-        // the run failed to record, which is what we most need to trace.
-        fetchId,
-        url: redactUrl2(resolvedUrl),
-        status: status ?? void 0,
-        outcome,
-        latencyMs,
-        hasPayment: !!payment,
-        paymentProtocol: payment?.protocol,
-        paymentAmount: payment && payment.amount !== "unknown" ? payment.amount : void 0,
-        // Canonical join keys — capabilitySlug is the dashboard
-        // breakdown dimension; capabilityUid is the stable join
-        // key with the capabilities table. capabilityId is the
-        // back-compat alias (same value as capabilityUid when
-        // resolved, else the raw --capability input).
-        capabilityUid: capabilityUid ?? void 0,
-        capabilitySlug: capabilitySlug ?? void 0,
-        capabilityId: capabilityId ?? void 0,
-        searchId: searchId ?? void 0,
-        resultRank: resultRank ?? void 0,
-        runId: runId ?? void 0,
-        runTracked: !!runId,
-        signingSource: signing?.source ?? "none",
-        // A NULL searchId on a direct_slug fetch is correct here,
-        // not a funnel gap to paper over.
-        fetchOrigin,
-        ...resultError && { error: truncateError(resultError) }
-      });
       const outcomeInfo = OUTCOMES[outcome];
       if (outcomeInfo.errorClass !== null) {
         const cliErrorClass = cliErrorClassFor(
@@ -170770,7 +170997,7 @@ var fetchCommand = (appContext) => new Command("fetch").description(
           capabilityId: capabilityId ?? void 0,
           searchId: searchId ?? void 0,
           resultRank: resultRank ?? void 0,
-          url: redactUrl2(resolvedUrl),
+          url: redactUrl(resolvedUrl),
           status: typeof status === "number" ? status : void 0,
           upstreamErrorMessage: upstreamError?.message,
           errorSnippetHash: upstreamError?.snippetHash,
@@ -170915,7 +171142,7 @@ var fetchCommand = (appContext) => new Command("fetch").description(
       try {
         appContext.services.analyticsService.capture("fetch_error", {
           cliErrorClass: "unknown",
-          url: url4 ? redactUrl2(url4) : "unknown",
+          url: url4 ? redactUrl(url4) : "unknown",
           error: truncateError(message2)
         });
       } catch {
@@ -172519,13 +172746,6 @@ Examples:
 
 // src/commands/search-command.ts
 init_esm_shims();
-
-// src/util/redact.ts
-init_esm_shims();
-var QUERY_MAX = 200;
-var truncateQuery = (raw) => raw.length > QUERY_MAX ? `${raw.slice(0, QUERY_MAX)}\u2026` : raw;
-
-// src/commands/search-command.ts
 var DEFAULT_MAX_COST_USD = "30";
 var formatStatusBadge = (status) => {
   if (!status || !(status in AVAILABILITY_BADGES)) return "";
@@ -172562,7 +172782,7 @@ var searchCommand = (appContext) => new Command("search").description("Search fo
 ).action(
   async (query, options) => {
     try {
-      const { analyticsService, client } = appContext.services;
+      const { client } = appContext.services;
       if (options.protocol && !["x402", "mpp"].includes(options.protocol)) {
         console.error(
           `Invalid protocol "${options.protocol}". Must be x402 or mpp.`
@@ -172591,27 +172811,14 @@ var searchCommand = (appContext) => new Command("search").description("Search fo
         availabilityStatus: effectiveStatus,
         includeAll: options.all,
         source: options.source,
-        excludeSource: options.excludeSource
-      });
-      analyticsService.capture("search_executed", {
-        query: truncateQuery(query),
-        queryLength: query.length,
-        resultCount: result.capabilities.length,
-        searchId: result.searchId,
-        total: result.total,
-        hasMore: result.hasMore,
-        offset: options.offset,
-        limit: options.limit,
-        freeOnly: options.free ?? false,
-        maxCost: effectiveMaxCost,
-        maxCostDefaulted: appliedDefaultMaxCost,
-        protocol: options.protocol,
-        availabilityStatus: effectiveStatus,
-        availabilityStatusDefaulted: appliedDefaultStatus,
-        includeAll: options.all ?? false,
-        listingSource: options.source,
-        excludeListingSource: options.excludeSource,
-        json: options.json ?? false
+        excludeSource: options.excludeSource,
+        analytics: {
+          props: {
+            maxCostDefaulted: appliedDefaultMaxCost,
+            availabilityStatusDefaulted: appliedDefaultStatus,
+            json: options.json ?? false
+          }
+        }
       });
       if (options.json) {
         console.log(
@@ -177486,10 +177693,82 @@ var PostHog = class extends PostHogBackendClient {
   }
 };
 
+// src/analytics/sdk-event-map.ts
+init_esm_shims();
+var orUndef = (value) => value === null ? void 0 : value;
+var dropUnknownAmount = (value) => value === null || value === "unknown" ? void 0 : value;
+var mapSdkEventToCliEvent = (event) => {
+  const p = event.properties;
+  switch (event.event) {
+    case "sdk_search":
+      return {
+        event: "search_executed",
+        props: {
+          query: p.query,
+          queryLength: p.query_length,
+          resultCount: p.result_count,
+          searchId: p.search_id,
+          total: p.total,
+          hasMore: p.has_more,
+          offset: orUndef(p.offset),
+          limit: orUndef(p.limit),
+          // The CLI historically defaulted these two booleans (never null).
+          freeOnly: p.free_only ?? false,
+          maxCost: orUndef(p.max_cost),
+          // CLI-only, carried in via the SDK's per-call analytics.props.
+          maxCostDefaulted: p.maxCostDefaulted,
+          protocol: orUndef(p.protocol),
+          availabilityStatus: orUndef(p.availability_status),
+          availabilityStatusDefaulted: p.availabilityStatusDefaulted,
+          includeAll: p.include_all ?? false,
+          listingSource: orUndef(p.listing_source),
+          excludeListingSource: orUndef(p.exclude_listing_source),
+          json: p.json
+        }
+      };
+    case "fetch_executed":
+      return {
+        event: "fetch_executed",
+        props: {
+          // SDK-native execution truth (snake→camel).
+          fetchId: p.fetch_id,
+          url: p.url,
+          status: orUndef(p.status),
+          outcome: p.outcome,
+          latencyMs: p.latency_ms,
+          hasPayment: p.has_payment,
+          paymentProtocol: orUndef(p.payment_protocol),
+          paymentAmount: dropUnknownAmount(p.payment_amount),
+          runId: orUndef(p.run_id),
+          runTracked: p.run_tracked,
+          error: orUndef(p.error),
+          // capabilityUid/Slug: prefer the adopter-supplied value (token /
+          // slug paths, from analytics.props), else the SDK's bare-URL
+          // resolution — mirroring how the CLI recovered them post-fetch.
+          capabilityUid: p.capabilityUid ?? orUndef(p.capability_uid),
+          capabilitySlug: p.capabilitySlug ?? orUndef(p.capability_slug),
+          // CLI-only context carried in via analytics.props.
+          capabilityId: p.capabilityId,
+          signingSource: p.signingSource,
+          fetchOrigin: p.fetchOrigin,
+          // searchId is server-derived (always omitted client-side);
+          // resultRank is likewise dead on the CLI event.
+          searchId: orUndef(p.search_id)
+        }
+      };
+    default:
+      return null;
+  }
+};
+
 // src/services/analytics-service.ts
+var FORWARDED_SDK_EVENTS = /* @__PURE__ */ new Set([
+  "sdk_wallet_resolved"
+]);
 var POSTHOG_API_KEY = "phc_B2vLyNxAf2mnqvdPQajf4d4b2iXc35dep2ZrvebMJLuX";
 var POSTHOG_HOST = "https://us.i.posthog.com";
-var toAnalyticsWallet = (walletAddress) => walletAddress.toLowerCase();
+var resolvePostHogHost = () => process.env.NODE_ENV === "test" && process.env.ZERO_ANALYTICS_TEST_HOST ? process.env.ZERO_ANALYTICS_TEST_HOST : POSTHOG_HOST;
+var toAnalyticsWallet2 = (walletAddress) => walletAddress.toLowerCase();
 var AnalyticsService = class {
   posthog;
   distinctId;
@@ -177501,7 +177780,7 @@ var AnalyticsService = class {
   constructor(opts) {
     this.cliVersion = opts.cliVersion;
     this.environment = opts.environment;
-    this.walletAddress = opts.walletAddress ? toAnalyticsWallet(opts.walletAddress) : null;
+    this.walletAddress = opts.walletAddress ? toAnalyticsWallet2(opts.walletAddress) : null;
     this.requestId = opts.requestId;
     this.agentHost = opts.agentHost;
     let telemetryEnabled = true;
@@ -177524,7 +177803,7 @@ var AnalyticsService = class {
       return;
     }
     if (opts.walletAddress) {
-      this.distinctId = toAnalyticsWallet(opts.walletAddress);
+      this.distinctId = toAnalyticsWallet2(opts.walletAddress);
     } else if (persistedAnonId) {
       this.distinctId = persistedAnonId;
     } else {
@@ -177552,7 +177831,7 @@ var AnalyticsService = class {
       originalConsoleError.apply(console, args);
     };
     this.posthog = new PostHog(POSTHOG_API_KEY, {
-      host: POSTHOG_HOST,
+      host: resolvePostHogHost(),
       flushAt: 1,
       flushInterval: 0,
       // Vitest spins up many AnalyticsService instances per process; each
@@ -177566,7 +177845,7 @@ var AnalyticsService = class {
       this.maybeAliasAnonToWallet(
         opts.configPath,
         persistedAnonId,
-        toAnalyticsWallet(opts.walletAddress)
+        toAnalyticsWallet2(opts.walletAddress)
       );
     }
   }
@@ -177607,7 +177886,7 @@ var AnalyticsService = class {
   // via PostHog alias, when AnalyticsService is constructed with both
   // the persisted anonId and the new walletAddress.
   setWalletAddress(walletAddress) {
-    this.walletAddress = toAnalyticsWallet(walletAddress);
+    this.walletAddress = toAnalyticsWallet2(walletAddress);
   }
   capture(event, properties) {
     if (!this.posthog) return;
@@ -177635,6 +177914,42 @@ var AnalyticsService = class {
       }
     });
   }
+  // Sink for the SDK's opt-in analytics (ZERO-434), wired into the ZeroClient
+  // as its `capture` callback in app-services. This is the CLI end of the
+  // injected-sink pattern — the same shape a partner would write. It keeps the
+  // SDK's own `source: "sdk"` stamp (the event genuinely came from the SDK
+  // layer, not a hand-authored CLI event) but adds the CLI's stitching
+  // super-props so it correlates to the rest of the invocation. Overlapping
+  // events are filtered out via FORWARDED_SDK_EVENTS above — the CLI's own
+  // emissions remain the source of truth for search/fetch.
+  captureSdk(event) {
+    if (!this.posthog) return;
+    const mapped = mapSdkEventToCliEvent(event);
+    if (mapped) {
+      this.capture(mapped.event, mapped.props);
+      return;
+    }
+    if (!FORWARDED_SDK_EVENTS.has(event.event)) return;
+    this.posthog.capture({
+      // The SDK resolves the wallet as distinctId; fall back to the CLI's
+      // distinctId (anon UUID before any wallet) so the event still stitches.
+      distinctId: event.distinctId ?? this.distinctId,
+      event: event.event,
+      properties: {
+        // event.properties already carries source:"sdk", sdk_version, and
+        // wallet_address. Add the CLI's correlation super-props (but NOT
+        // source:"cli" — this is an SDK-layer event, honestly stamped).
+        ...event.properties,
+        environment: this.environment,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        cli_version: this.cliVersion,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        request_id: this.requestId,
+        // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+        agent_host: this.agentHost
+      }
+    });
+  }
   captureException(error98, properties) {
     if (!this.posthog) return;
     this.posthog.captureException(error98, this.distinctId, {
@@ -177720,7 +178035,19 @@ var getServices = async (env) => {
   const byoAccount = byoPrivateKey ? privateKeyToAccount(byoPrivateKey) : null;
   const lowBalanceWarning = typeof config3.lowBalanceWarning === "number" ? config3.lowBalanceWarning : 1;
   const onSessionRefreshed = buildOnSessionRefreshed(configPath);
+  let analyticsSink = null;
+  const pendingSdkEvents = [];
   const client = new ZeroClient({
+    analytics: config3.telemetry === false ? { enabled: false } : {
+      enabled: true,
+      capture: (event) => {
+        if (analyticsSink) {
+          analyticsSink.captureSdk(event);
+          return;
+        }
+        pendingSdkEvents.push(event);
+      }
+    },
     baseUrl: env.ZERO_API_URL,
     // The SDK scopes defaultHeaders to same-origin API calls, so this
     // never reaches capability URLs.
@@ -177761,6 +178088,14 @@ var getServices = async (env) => {
     requestId: randomUUID(),
     agentHost: detectAgentHost()
   });
+  analyticsSink = analyticsService;
+  for (const event of pendingSdkEvents) {
+    try {
+      analyticsService.captureSdk(event);
+    } catch {
+    }
+  }
+  pendingSdkEvents.length = 0;
   return {
     analyticsService,
     client,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "1.26.1",
+	"version": "1.27.0",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",
@@ -19,6 +19,7 @@
 		"dev": "ZERO_ENV=development tsx src/index.ts",
 		"cli": "ZERO_ENV=development ZERO_API_URL=http://localhost:1111 tsx src/index.ts",
 		"test:integration": "vitest run --project integration",
+		"test:e2e": "tsup && vitest run --project e2e",
 		"test:online": "vitest run --project online",
 		"test:unit": "vitest run --project unit",
 		"test": "pnpm run test:unit && pnpm run test:integration",