@drip-apex/apex-cli 0.11.0 → 0.12.1

package/README.md

@@ -342,3 +342,39 @@ optimistic concurrency token.
 QA status creates a run only when none exists. Reading an existing run never writes
 to it: `updatedAt` is its last stored mutation time, while `computedAt` is the ISO
 timestamp when the current checklist and summary were computed.
+
+### Decision latency
+
+`apex tracking latency <experiment-id-or-key> [--days <1..30>] [--qa-session <id>] [--json]`
+compares forced-preview and natural decision latency before launch. The default
+window is seven days. The table shows sample counts, decision p50/p95/p99,
+config-fetch p50/p95 (milliseconds), and inline/cache/network/none counts.
+JSON output includes the API body in the standard envelope and assignment-ready
+percentiles. Fewer than five measured samples have null percentiles. Natural
+loads are shop-wide non-QA loads without forced IDs; a QA-session bucket can
+overlap forced loads. Analytics failures return errors. The API position is
+`runtime_inline_no_change`.
+
+The runtime remains unchanged. Natural runtime decides within tens of milliseconds
+of SDK start when config ships inline with the snippet (measured p50 12 ms /
+p95 54 ms on a large storefront). QA previews, screenshot-mode previews and
+cookie-forced sessions take the QA config lane and fetch fresh config over the
+network (measured p50 1.3 s / p95 7 s); they are not representative of launch
+behaviour. URL-forced sessions without a `qa` parameter keep the inline or cached
+config, so these measurements do not describe them. No config preload or
+anti-flicker hold is planned.
+
+### Connection troubleshooting
+
+Connection errors retain the underlying failure. JSON output exposes
+`error.details.reason` and, when available, `error.details.code`; the numeric
+`error.code` remains the CLI exit code.
+
+| Reason | Meaning and usual fix |
+| --- | --- |
+| `dns` | The host could not be resolved. Check `APEX_BASE_URL` (or `DRIP_BASE_URL`), DNS, and whether your sandbox permits network access. |
+| `refused` | The host rejected the connection. Check the base URL, port, and whether the server is running. |
+| `reset` | The connection was interrupted. Check network stability and proxy settings before retrying. |
+| `tls` | Certificate or TLS validation failed. Check expired certificates and your corporate TLS proxy's trusted CA configuration. |
+| `timeout` | The request was aborted or exceeded its deadline. Check server availability and network access. |
+| `unknown` | Another network failure occurred. Use the included cause message to diagnose network or sandbox restrictions. |

package/dist/cli.js

@@ -7112,7 +7112,7 @@ var import_node_os3 = __toESM(require("node:os"));
 // package.json
 var package_default = {
   name: "@drip-apex/apex-cli",
-  version: "0.11.0",
+  version: "0.12.1",
   license: "MIT",
   description: "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   private: false,
@@ -7666,7 +7666,16 @@ function createHttpClient(creds, options) {
     try {
       response = await fetch(`${creds.baseUrl}${path24}`, { method, headers, body: form ? body5 : body5 ? JSON.stringify(body5) : void 0, signal: AbortSignal.timeout(timeoutMs) });
     } catch (error) {
-      return options.onNetworkError({ baseUrl: creds.baseUrl, timeoutMs, cause: error instanceof Error ? error.message : String(error) });
+      const outer = error && typeof error === "object" ? error : void 0;
+      const nested = outer?.cause && typeof outer.cause === "object" ? outer.cause : void 0;
+      return options.onNetworkError({
+        baseUrl: creds.baseUrl,
+        timeoutMs,
+        cause: error instanceof Error ? error.message : String(error),
+        code: typeof nested?.code === "string" ? nested.code : typeof outer?.code === "string" ? outer.code : void 0,
+        name: typeof outer?.name === "string" ? outer.name : void 0,
+        causeMessage: typeof nested?.message === "string" ? nested.message : void 0
+      });
     }
     inspectVersion(response.headers);
     const json = await response.json().catch(() => null);
@@ -7739,10 +7748,42 @@ function sharedClient(creds) {
       transport: testTransport,
       testTransportVersion: () => testTransport ? process.env[["APEX", "CLI", "MOCK", "API", "VERSION"].join("_")] : void 0,
       onNetworkError: (info) => {
+        let url;
+        try {
+          url = new URL(info.baseUrl);
+        } catch {
+        }
+        const host = url?.hostname ?? info.baseUrl;
+        const code = info.code;
+        let reason = "unknown";
+        let message = info.causeMessage ?? info.cause;
+        if (info.name === "TimeoutError" || info.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT") {
+          reason = "timeout";
+          message = `server did not respond within ${info.timeoutMs / 1e3}s`;
+        } else if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+          reason = "dns";
+          message = `could not resolve host ${host}`;
+        } else if (code === "ECONNREFUSED") {
+          reason = "refused";
+          message = `connection refused by ${host}:${url?.port || (url?.protocol === "https:" ? "443" : "80")}`;
+        } else if (code === "ECONNRESET" || code === "EPIPE") {
+          reason = "reset";
+          message = `connection reset by ${host}`;
+        } else if (code?.startsWith("CERT_") || code?.startsWith("ERR_TLS_") || [
+          "DEPTH_ZERO_SELF_SIGNED_CERT",
+          "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+          "SELF_SIGNED_CERT_IN_CHAIN",
+          "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+          "UNABLE_TO_GET_ISSUER_CERT",
+          "HOSTNAME_MISMATCH"
+        ].includes(code ?? "")) {
+          reason = "tls";
+          message = `TLS error (${code})`;
+        }
         throw new CliError(
-          `Could not reach ${info.baseUrl}: check APEX_BASE_URL (or DRIP_BASE_URL) / network; server did not respond within ${info.timeoutMs / 1e3}s.`,
+          `Could not reach ${info.baseUrl}: check APEX_BASE_URL (or DRIP_BASE_URL) / network; ${message}.`,
           EXIT_CODES.general,
-          { ...info }
+          { reason, code, name: info.name, baseUrl: info.baseUrl, timeoutMs: info.timeoutMs }
         );
       }
     });
@@ -7985,6 +8026,11 @@ function trackingEventProperties(event) {
   if (event.goal_id != null) properties.goalId = event.goal_id;
   return properties;
 }
+function getDecisionLatency(creds, experimentId, opts) {
+  const params = new URLSearchParams({ experiment_id: experimentId, days: String(opts.days) });
+  if (opts.qaSessionId) params.set("qa_session_id", opts.qaSessionId);
+  return request(creds, "GET", `/api/v1/tracking/latency?${params}`);
+}
 function verifyTracking(creds, opts) {
   const params = new URLSearchParams();
   if (opts?.minutes) params.set("minutes", String(opts.minutes));
@@ -13096,6 +13142,64 @@ trackingCommand.command("verify").description("Verify live tracking events for t
     }
   });
 });
+trackingCommand.command("latency").description("Measure forced-preview versus natural decision latency before launch").argument("<experiment-id-or-key>", "Experiment ID or test key").option("--days <n>", "Lookback window in days (1\u201330)", "7").option("--qa-session <id>", "Include a QA session bucket").action(async function(experimentId, opts) {
+  const days = Number(opts.days);
+  if (!Number.isInteger(days) || days < 1 || days > 30) {
+    fail(this, "days must be an integer from 1 to 30", classifyStatus(400));
+  }
+  const result = await getDecisionLatency(requireCredentials(), experimentId, {
+    days,
+    qaSessionId: opts.qaSession
+  });
+  if (!result.ok || !result.data) {
+    fail(
+      this,
+      result.error ?? "Failed to read decision latency",
+      classifyStatus(result.status),
+      result.errorDetails
+    );
+  }
+  const summary = result.data;
+  output(this, summary, () => {
+    const buckets = [
+      ["forced", summary.forced],
+      ["natural", summary.natural],
+      ...summary.qa_session ? [["qa_session", summary.qa_session]] : []
+    ];
+    const ms = (value) => value === null ? "-" : String(Math.round(value));
+    printTable(
+      [
+        "Bucket",
+        "Samples",
+        "Decision p50",
+        "p95",
+        "p99",
+        "Config p50",
+        "p95",
+        "inline/cache/network/none"
+      ],
+      buckets.map(([name, bucket]) => [
+        name,
+        String(bucket.samples),
+        ms(bucket.decision_latency_ms.p50),
+        ms(bucket.decision_latency_ms.p95),
+        ms(bucket.decision_latency_ms.p99),
+        ms(bucket.config_fetch_ms.p50),
+        ms(bucket.config_fetch_ms.p95),
+        [
+          bucket.config_sources.inline,
+          bucket.config_sources.cache,
+          bucket.config_sources.network,
+          bucket.config_sources.none
+        ].join("/")
+      ])
+    );
+    console.log("Times in ms. Fewer than 5 measured samples: -.");
+    console.log(
+      "Position: runtime unchanged (inline config decides within tens of ms; forced previews fetch config over the network and are not representative)"
+    );
+  });
+});
 
 // src/commands/goals.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drip-apex/apex-cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "license": "MIT",
   "description": "Apex CLI for managing experiments, approved roadmap ideas, and draft workspaces.",
   "private": false,