@copilotkit/web-inspector 1.61.0 → 1.61.2

package/src/lib/__tests__/telemetry.test.ts

@@ -1,17 +1,27 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { MockInstance } from "vitest";
 
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
 import {
   TELEMETRY_DOCS_URL,
   TELEMETRY_EVENTS,
   TELEMETRY_INGEST_URL,
+  getRuntimeUrlType,
   getTelemetryDistinctIdForUrl,
   maybeShowDisclosure,
   track,
   trackBannerClicked,
   trackBannerViewed,
+  trackTalkToEngineerClicked,
+  trackThreadsEmptyEnabledViewed,
+  trackThreadsEnabledViewed,
+  trackThreadsIntelligenceSignupClicked,
+  trackThreadsLockedViewed,
   trackThreadsTabClicked,
-} from "../telemetry";
+  trackThreadsTalkToEngineerClicked,
+} from "../telemetry.js";
 import {
   _resetTelemetryPersistenceForTesting,
   getOrCreateTelemetryDistinctId,
@@ -19,13 +29,16 @@ import {
   isTelemetryOptedOut,
   markTelemetryDisclosureShown,
   setTelemetryOptOut,
-} from "../persistence";
+} from "../persistence.js";
 
 // The wrapper short-circuits before any network call when opted out, but
 // for the network-touching cases we mock fetch globally so we can read
 // what would have been sent without making real HTTP requests.
 let fetchMock: MockInstance<typeof fetch>;
 let consoleInfoSpy: MockInstance<typeof console.info>;
+const webInspectorPackage = JSON.parse(
+  readFileSync(resolve(process.cwd(), "package.json"), "utf8"),
+) as { version: string };
 
 beforeEach(() => {
   // Each test starts from a clean localStorage so distinct-ID + opt-out
@@ -83,10 +96,12 @@ describe("track()", () => {
     // package is top-level object, not a string inside properties
     expect(body.package).toEqual({ name: "@copilotkit/web-inspector" });
     expect(body.properties).not.toHaveProperty("package");
+    expect(body.properties).not.toHaveProperty("package_name");
+    expect(body.properties).not.toHaveProperty("inspector_distinct_id");
     expect(typeof body.ts).toBe("number");
   });
 
-  it("sends regardless of localStorage opt-out — callers gate on core.telemetryDisabled", async () => {
+  it("short-circuits when localStorage opt-out is set", async () => {
     setTelemetryOptOut(true);
     expect(isTelemetryOptedOut()).toBe(true);
 
@@ -96,9 +111,20 @@ describe("track()", () => {
     });
     await Promise.resolve();
 
-    // track() no longer short-circuits on localStorage; opt-out is enforced
-    // at the call site via core.telemetryDisabled before track*() is invoked.
-    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("swallows unserializable properties before dispatching", async () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    expect(() => track(TELEMETRY_EVENTS.bannerClicked, circular)).not.toThrow();
+    expect(() =>
+      track(TELEMETRY_EVENTS.bannerClicked, { value: 1n }),
+    ).not.toThrow();
+    await Promise.resolve();
+
+    expect(fetchMock).not.toHaveBeenCalled();
   });
 
   it("swallows fetch failures (telemetry is best-effort)", async () => {
@@ -170,17 +196,131 @@ describe("typed helpers", () => {
     expect(body.properties.cta).toBe("body");
   });
 
-  it("trackThreadsTabClicked sends no caller-supplied properties", async () => {
-    trackThreadsTabClicked();
+  it("trackThreadsTabClicked sends thread metadata without content", async () => {
+    trackThreadsTabClicked({
+      intelligence_status: "intelligence_not_enabled",
+      thread_service_status: "unavailable",
+      runtime_mode: "sse",
+      runtime_url_type: "localhost",
+      license_status: "none",
+      telemetry_disabled: false,
+    });
     await Promise.resolve();
     const [, init] = fetchMock.mock.calls[0]!;
     const body = JSON.parse((init?.body as string) ?? "{}") as {
       event: string;
       properties: Record<string, unknown>;
+      package: { name: string; version?: string };
     };
     expect(body.event).toBe(TELEMETRY_EVENTS.threadsTabClicked);
-    // Only distinct_id should be in properties (no caller keys)
-    expect(Object.keys(body.properties)).toEqual(["distinct_id"]);
+    expect(body.properties).toMatchObject({
+      intelligence_status: "intelligence_not_enabled",
+      thread_service_status: "unavailable",
+      runtime_mode: "sse",
+      runtime_url_type: "localhost",
+      license_status: "none",
+      telemetry_disabled: false,
+      package_name: "@copilotkit/web-inspector",
+      package_version: webInspectorPackage.version,
+    });
+    expect(body.properties).toHaveProperty("inspector_distinct_id");
+    expect(body.properties.inspector_distinct_id).toBe(
+      body.properties.distinct_id,
+    );
+    expect(body.package).toEqual({
+      name: "@copilotkit/web-inspector",
+      version: webInspectorPackage.version,
+    });
+  });
+
+  it("sends required threads CTA and viewed events", async () => {
+    trackThreadsLockedViewed({
+      intelligence_status: "intelligence_not_enabled",
+      thread_service_status: "unavailable",
+    });
+    trackThreadsIntelligenceSignupClicked({
+      cta: "signup",
+      cta_surface: "threads_locked",
+      posthog_distinct_id: "abc-123",
+    });
+    trackThreadsTalkToEngineerClicked({
+      cta: "talk_to_engineer",
+      cta_surface: "threads_locked",
+      posthog_distinct_id: "abc-123",
+    });
+    trackTalkToEngineerClicked({
+      cta: "talk_to_engineer",
+      cta_surface: "threads_header",
+      posthog_distinct_id: "abc-123",
+    });
+    trackThreadsEmptyEnabledViewed({
+      intelligence_status: "intelligence_enabled",
+      thread_service_status: "available",
+      thread_count: 0,
+    });
+    trackThreadsEnabledViewed({
+      intelligence_status: "intelligence_enabled",
+      thread_service_status: "available",
+      thread_count: 2,
+    });
+
+    await Promise.resolve();
+
+    const payloads = fetchMock.mock.calls.map(([, init]) => {
+      return JSON.parse((init?.body as string) ?? "{}") as {
+        event: string;
+        properties: Record<string, unknown>;
+      };
+    });
+    const events = payloads.map((payload) => payload.event);
+    expect(events).toEqual([
+      TELEMETRY_EVENTS.threadsLockedViewed,
+      TELEMETRY_EVENTS.threadsIntelligenceSignupClicked,
+      TELEMETRY_EVENTS.threadsTalkToEngineerClicked,
+      TELEMETRY_EVENTS.talkToEngineerClicked,
+      TELEMETRY_EVENTS.threadsEmptyEnabledViewed,
+      TELEMETRY_EVENTS.threadsEnabledViewed,
+    ]);
+    expect(payloads[0]!.properties).toMatchObject({
+      intelligence_status: "intelligence_not_enabled",
+      thread_service_status: "unavailable",
+    });
+    expect(payloads[1]!.properties).toMatchObject({
+      cta: "signup",
+      cta_surface: "threads_locked",
+      posthog_distinct_id: "abc-123",
+    });
+    expect(payloads[2]!.properties).toMatchObject({
+      cta: "talk_to_engineer",
+      cta_surface: "threads_locked",
+      posthog_distinct_id: "abc-123",
+    });
+    expect(payloads[3]!.properties).toMatchObject({
+      cta: "talk_to_engineer",
+      cta_surface: "threads_header",
+      posthog_distinct_id: "abc-123",
+    });
+    expect(payloads[4]!.properties).toMatchObject({
+      intelligence_status: "intelligence_enabled",
+      thread_service_status: "available",
+      thread_count: 0,
+    });
+    expect(payloads[5]!.properties).toMatchObject({
+      intelligence_status: "intelligence_enabled",
+      thread_service_status: "available",
+      thread_count: 2,
+    });
+  });
+});
+
+// ─── Safe URL classification ────────────────────────────────────────────────
+
+describe("getRuntimeUrlType()", () => {
+  it("classifies runtime URLs without exposing origins", () => {
+    expect(getRuntimeUrlType(undefined)).toBe("missing");
+    expect(getRuntimeUrlType("/api/copilotkit")).toBe("relative");
+    expect(getRuntimeUrlType("http://localhost:4000")).toBe("localhost");
+    expect(getRuntimeUrlType("https://example.com/api")).toBe("remote");
   });
 });
 

package/src/lib/context-helpers.ts

@@ -1,4 +1,4 @@
-import type { Anchor, ContextState, Position, Size } from "./types";
+import type { Anchor, ContextState, Position, Size } from "./types.js";
 
 export function updateSizeFromElement(
   state: ContextState,

package/src/lib/persistence.ts

@@ -1,4 +1,4 @@
-import type { Anchor, DockMode, Position, Size } from "./types";
+import type { Anchor, DockMode, Position, Size } from "./types.js";
 
 export type PersistedContextState = {
   anchor?: Anchor;

package/src/lib/telemetry.ts

@@ -1,6 +1,5 @@
-// Inspector-side anonymous telemetry. Three V1 events fire from index.ts —
-// `oss.inspector.banner_viewed`, `oss.inspector.banner_clicked`, and
-// `oss.inspector.threads_tab_clicked`. POSTs directly from the browser
+// Inspector-side anonymous telemetry. V1 events fire from index.ts for
+// banner and thread-inspection interactions. POSTs directly from the browser
 // to the CopilotKit telemetry sink at `telemetry.copilotkit.ai/ingest`,
 // where a Lambda fan-out forwards events to PostHog / Reo / Scarf.
 //
@@ -21,16 +20,24 @@ import {
   hasTelemetryDisclosureBeenShown,
   isTelemetryOptedOut,
   markTelemetryDisclosureShown,
-} from "./persistence";
+} from "./persistence.js";
+import packageJson from "../../package.json" with { type: "json" };
 
 // V1 funnel events. Namespaced `oss.inspector.*` so the lambda's
-// event-type allowlist (oss-path-to-production) can gate them
-// server-side. Adding a new event here requires a corresponding
-// allowlist entry on the lambda or events will be rejected.
+// owned-prefix gate (oss-path-to-production) can accept them server-side
+// without a per-event sink deploy.
 export const TELEMETRY_EVENTS = {
   bannerViewed: "oss.inspector.banner_viewed",
   bannerClicked: "oss.inspector.banner_clicked",
   threadsTabClicked: "oss.inspector.threads_tab_clicked",
+  threadsLockedViewed: "oss.inspector.threads_locked_viewed",
+  threadsIntelligenceSignupClicked:
+    "oss.inspector.threads_intelligence_signup_clicked",
+  threadsTalkToEngineerClicked:
+    "oss.inspector.threads_talk_to_engineer_clicked",
+  talkToEngineerClicked: "oss.inspector.talk_to_engineer_clicked",
+  threadsEmptyEnabledViewed: "oss.inspector.threads_empty_enabled_viewed",
+  threadsEnabledViewed: "oss.inspector.threads_enabled_viewed",
 } as const;
 
 export type TelemetryEvent =
@@ -47,11 +54,63 @@ export const TELEMETRY_INGEST_URL = "https://telemetry.copilotkit.ai/ingest";
 export const TELEMETRY_DOCS_URL = "https://docs.copilotkit.ai/telemetry";
 
 const PACKAGE_NAME = "@copilotkit/web-inspector";
+const PACKAGE_VERSION = packageJson.version;
 
 // 3-second cap so a slow gateway can't hang the host app. Matches the
 // runtime's existing scarf-client convention.
 const FETCH_TIMEOUT_MS = 3000;
 
+function isThreadsTelemetryEvent(event: TelemetryEvent): boolean {
+  return (
+    event === TELEMETRY_EVENTS.threadsTabClicked ||
+    event === TELEMETRY_EVENTS.threadsLockedViewed ||
+    event === TELEMETRY_EVENTS.threadsIntelligenceSignupClicked ||
+    event === TELEMETRY_EVENTS.threadsTalkToEngineerClicked ||
+    event === TELEMETRY_EVENTS.talkToEngineerClicked ||
+    event === TELEMETRY_EVENTS.threadsEmptyEnabledViewed ||
+    event === TELEMETRY_EVENTS.threadsEnabledViewed
+  );
+}
+
+export type RuntimeUrlType =
+  | "missing"
+  | "relative"
+  | "localhost"
+  | "same_origin"
+  | "remote"
+  | "invalid";
+
+export function getRuntimeUrlType(
+  runtimeUrl: string | undefined,
+): RuntimeUrlType {
+  if (!runtimeUrl) return "missing";
+  if (runtimeUrl.startsWith("/") && !runtimeUrl.startsWith("//")) {
+    return "relative";
+  }
+
+  try {
+    const baseHref =
+      typeof window !== "undefined"
+        ? window.location.href
+        : "https://copilotkit.ai";
+    const url = new URL(runtimeUrl, baseHref);
+    const baseUrl = new URL(baseHref);
+    const hostname = url.hostname.toLowerCase();
+
+    if (
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "[::1]"
+    ) {
+      return "localhost";
+    }
+
+    return url.origin === baseUrl.origin ? "same_origin" : "remote";
+  } catch {
+    return "invalid";
+  }
+}
+
 /**
  * Fire-and-forget telemetry send. Returns synchronously; the network
  * call is dispatched in the background and any failure is swallowed.
@@ -64,16 +123,34 @@ export function track(
   event: TelemetryEvent,
   properties: Record<string, unknown> = {},
 ): void {
+  if (isTelemetryOptedOut()) return;
+
   const distinctId = getOrCreateTelemetryDistinctId();
-  const body = JSON.stringify({
-    event,
-    properties: {
-      ...properties,
-      distinct_id: distinctId,
-    },
-    package: { name: PACKAGE_NAME },
-    ts: Math.floor(Date.now() / 1000),
-  });
+  const threadsProperties = isThreadsTelemetryEvent(event)
+    ? {
+        package_name: PACKAGE_NAME,
+        package_version: PACKAGE_VERSION,
+        inspector_distinct_id: distinctId,
+      }
+    : {};
+  let body: string;
+  try {
+    body = JSON.stringify({
+      event,
+      properties: {
+        ...properties,
+        ...threadsProperties,
+        distinct_id: distinctId,
+      },
+      package: {
+        name: PACKAGE_NAME,
+        ...(isThreadsTelemetryEvent(event) ? { version: PACKAGE_VERSION } : {}),
+      },
+      ts: Math.floor(Date.now() / 1000),
+    });
+  } catch {
+    return;
+  }
 
   void postBestEffort(TELEMETRY_INGEST_URL, body, distinctId);
 }
@@ -97,8 +174,75 @@ export function trackBannerClicked(props: {
   track(TELEMETRY_EVENTS.bannerClicked, props);
 }
 
-export function trackThreadsTabClicked(): void {
-  track(TELEMETRY_EVENTS.threadsTabClicked);
+export type InspectorThreadTelemetryProps = {
+  package_name?: typeof PACKAGE_NAME;
+  package_version?: string;
+  inspector_distinct_id?: string;
+  posthog_distinct_id?: string;
+  intelligence_status?:
+    | "intelligence_not_enabled"
+    | "intelligence_enabled"
+    | "unknown";
+  thread_service_status?: "unavailable" | "available" | "unknown" | "error";
+  license_status?:
+    | "valid"
+    | "none"
+    | "expired"
+    | "expiring"
+    | "invalid"
+    | "unknown";
+  runtime_mode?: "sse" | "intelligence";
+  runtime_url_type?: RuntimeUrlType;
+  cta_surface?:
+    | "threads_locked"
+    | "threads_header"
+    | "threads_empty"
+    | "threads_populated";
+  cta?: "signup" | "talk_to_engineer";
+  telemetry_disabled?: boolean;
+  thread_count?: number;
+};
+
+export function trackThreadsTabClicked(
+  props: InspectorThreadTelemetryProps = {},
+): void {
+  track(TELEMETRY_EVENTS.threadsTabClicked, props);
+}
+
+export function trackThreadsLockedViewed(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.threadsLockedViewed, props);
+}
+
+export function trackThreadsIntelligenceSignupClicked(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.threadsIntelligenceSignupClicked, props);
+}
+
+export function trackThreadsTalkToEngineerClicked(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.threadsTalkToEngineerClicked, props);
+}
+
+export function trackTalkToEngineerClicked(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.talkToEngineerClicked, props);
+}
+
+export function trackThreadsEmptyEnabledViewed(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.threadsEmptyEnabledViewed, props);
+}
+
+export function trackThreadsEnabledViewed(
+  props: InspectorThreadTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.threadsEnabledViewed, props);
 }
 
 /**