@copilotkit/web-inspector 1.64.2-canary.rc-1 → 1.64.2

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

@@ -13,7 +13,9 @@ import {
   maybeShowDisclosure,
   track,
   trackBannerClicked,
+  trackBannerDismissed,
   trackBannerViewed,
+  trackInspectorOpened,
   trackTalkToEngineerClicked,
   trackThreadsEmptyEnabledViewed,
   trackThreadsEnabledViewed,
@@ -162,8 +164,12 @@ describe("track()", () => {
 // ─── Typed per-event helpers ─────────────────────────────────────────────────
 
 describe("typed helpers", () => {
-  it("trackBannerViewed sends banner_id and optional cta_label", async () => {
-    trackBannerViewed({ banner_id: "ts-2025", cta_label: "Try threads" });
+  it("trackBannerViewed sends banner_id, surface, and optional cta_label", async () => {
+    trackBannerViewed({
+      banner_id: "ts-2025",
+      surface: "collapsed_preview",
+      cta_label: "Try threads",
+    });
     await Promise.resolve();
     const [, init] = fetchMock.mock.calls[0]!;
     const body = JSON.parse((init?.body as string) ?? "{}") as {
@@ -172,17 +178,105 @@ describe("typed helpers", () => {
     };
     expect(body.event).toBe(TELEMETRY_EVENTS.bannerViewed);
     expect(body.properties.banner_id).toBe("ts-2025");
+    expect(body.properties.surface).toBe("collapsed_preview");
     expect(body.properties.cta_label).toBe("Try threads");
   });
 
   it("trackBannerViewed omits cta_label when undefined (JSON.stringify drops it)", async () => {
-    trackBannerViewed({ banner_id: "ts-2025" });
+    trackBannerViewed({ banner_id: "ts-2025", surface: "expanded_card" });
     await Promise.resolve();
     const [, init] = fetchMock.mock.calls[0]!;
     const raw = (init?.body as string) ?? "{}";
     expect(raw).not.toContain("cta_label");
   });
 
+  it("trackBannerDismissed sends a first-class dismissed event with its surface", async () => {
+    trackBannerDismissed({
+      banner_id: "ts-2025",
+      surface: "expanded_card",
+      cta_label: "Try threads",
+    });
+    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("oss.inspector.banner_dismissed");
+    expect(body.properties.banner_id).toBe("ts-2025");
+    expect(body.properties.surface).toBe("expanded_card");
+    expect(body.properties.cta_label).toBe("Try threads");
+    // Banner events keep the flat shape their existing dashboards read.
+    expect(body.properties).not.toHaveProperty("package_version");
+    expect(body.package).toEqual({ name: "@copilotkit/web-inspector" });
+  });
+
+  it("trackInspectorOpened sends open_source and is enriched with package identity", async () => {
+    trackInspectorOpened({
+      open_source: "floating_button",
+      license_status: "none",
+      runtime_mode: "sse",
+      runtime_url_type: "localhost",
+      has_unseen_announcement: true,
+    });
+    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("oss.inspector.opened");
+    expect(body.properties).toMatchObject({
+      open_source: "floating_button",
+      license_status: "none",
+      runtime_mode: "sse",
+      runtime_url_type: "localhost",
+      has_unseen_announcement: true,
+      package_name: "@copilotkit/web-inspector",
+      package_version: webInspectorPackage.version,
+    });
+    expect(body.properties.inspector_distinct_id).toBe(
+      body.properties.distinct_id,
+    );
+    expect(body.package).toEqual({
+      name: "@copilotkit/web-inspector",
+      version: webInspectorPackage.version,
+    });
+  });
+
+  it("opened and banner events carry no message, state, or announcement content", async () => {
+    trackInspectorOpened({ open_source: "announcement_preview" });
+    trackBannerDismissed({
+      banner_id: "ts-2025",
+      surface: "collapsed_preview",
+    });
+    await Promise.resolve();
+    for (const [, init] of fetchMock.mock.calls) {
+      const properties = (
+        JSON.parse((init?.body as string) ?? "{}") as {
+          properties: Record<string, unknown>;
+        }
+      ).properties;
+      // Allow-list assertion: any new key has to be added here deliberately,
+      // so an accidental content/PII payload fails the test instead of
+      // shipping.
+      const allowed = new Set([
+        "open_source",
+        "banner_id",
+        "surface",
+        "distinct_id",
+        "inspector_distinct_id",
+        "package_name",
+        "package_version",
+      ]);
+      expect(Object.keys(properties).filter((k) => !allowed.has(k))).toEqual(
+        [],
+      );
+    }
+  });
+
   it("trackBannerClicked sends banner_id, cta, and optional cta_label", async () => {
     trackBannerClicked({ banner_id: "ts-2025", cta: "body" });
     await Promise.resolve();

package/src/lib/telemetry.ts

@@ -27,8 +27,10 @@ import packageJson from "../../package.json" with { type: "json" };
 // owned-prefix gate (oss-path-to-production) can accept them server-side
 // without a per-event sink deploy.
 export const TELEMETRY_EVENTS = {
+  opened: "oss.inspector.opened",
   bannerViewed: "oss.inspector.banner_viewed",
   bannerClicked: "oss.inspector.banner_clicked",
+  bannerDismissed: "oss.inspector.banner_dismissed",
   threadsTabClicked: "oss.inspector.threads_tab_clicked",
   threadsLockedViewed: "oss.inspector.threads_locked_viewed",
   threadsIntelligenceSignupClicked:
@@ -69,8 +71,15 @@ const PACKAGE_VERSION = packageJson.version;
 // runtime's existing scarf-client convention.
 const FETCH_TIMEOUT_MS = 3000;
 
-function isThreadsTelemetryEvent(event: TelemetryEvent): boolean {
+// Events that carry package identity (`package_name` / `package_version`) and
+// the inspector's anonymous distinct-ID alongside their own properties.
+// Threads / memories events have always been enriched this way; `opened`
+// joins them so panel-open volume can be segmented by inspector version.
+// Banner events deliberately keep the flat shape their existing dashboards
+// read.
+function isEnrichedTelemetryEvent(event: TelemetryEvent): boolean {
   return (
+    event === TELEMETRY_EVENTS.opened ||
     event === TELEMETRY_EVENTS.threadsTabClicked ||
     event === TELEMETRY_EVENTS.threadsLockedViewed ||
     event === TELEMETRY_EVENTS.threadsIntelligenceSignupClicked ||
@@ -143,7 +152,7 @@ export function track(
   if (isTelemetryOptedOut()) return;
 
   const distinctId = getOrCreateTelemetryDistinctId();
-  const threadsProperties = isThreadsTelemetryEvent(event)
+  const enrichedProperties = isEnrichedTelemetryEvent(event)
     ? {
         package_name: PACKAGE_NAME,
         package_version: PACKAGE_VERSION,
@@ -156,12 +165,14 @@ export function track(
       event,
       properties: {
         ...properties,
-        ...threadsProperties,
+        ...enrichedProperties,
         distinct_id: distinctId,
       },
       package: {
         name: PACKAGE_NAME,
-        ...(isThreadsTelemetryEvent(event) ? { version: PACKAGE_VERSION } : {}),
+        ...(isEnrichedTelemetryEvent(event)
+          ? { version: PACKAGE_VERSION }
+          : {}),
       },
       ts: Math.floor(Date.now() / 1000),
     });
@@ -176,8 +187,18 @@ export function track(
 // These enforce the known property shape for each V1 event at the call
 // site, so callers can't accidentally include PII under a wrong key.
 
+/**
+ * Where an announcement was rendered when the event fired. The announcement
+ * has two surfaces — the preview bubble beside the *collapsed* floating
+ * button, and the card *inside* the opened panel — and reach on one says
+ * nothing about attention on the other. Always stamped at fire time, never
+ * inferred at fetch time.
+ */
+export type BannerSurface = "collapsed_preview" | "expanded_card";
+
 export function trackBannerViewed(props: {
   banner_id: string;
+  surface: BannerSurface;
   cta_label?: string;
 }): void {
   track(TELEMETRY_EVENTS.bannerViewed, props);
@@ -191,6 +212,58 @@ export function trackBannerClicked(props: {
   track(TELEMETRY_EVENTS.bannerClicked, props);
 }
 
+/**
+ * First-class dismissal signal. Emitted *in addition to*
+ * `banner_clicked { cta: "dismiss" }` rather than replacing it — the
+ * existing dashboards read the `cta` value, so removing it would silently
+ * zero them out. New reporting should prefer this event, whose `surface`
+ * says whether the user swatted the bubble away or dismissed the card
+ * after opening the panel.
+ */
+export function trackBannerDismissed(props: {
+  banner_id: string;
+  surface: BannerSurface;
+  cta_label?: string;
+}): void {
+  track(TELEMETRY_EVENTS.bannerDismissed, props);
+}
+
+/**
+ * How the panel was opened. Restoring a persisted-open panel on mount is
+ * deliberately NOT a source: it is not an open *intent*, and counting it
+ * would turn every dev-server hot reload into an "open".
+ */
+export type InspectorOpenSource = "floating_button" | "announcement_preview";
+
+export type InspectorOpenedTelemetryProps = {
+  open_source: InspectorOpenSource;
+  package_name?: typeof PACKAGE_NAME;
+  package_version?: string;
+  inspector_distinct_id?: string;
+  license_status?:
+    | "valid"
+    | "none"
+    | "expired"
+    | "expiring"
+    | "invalid"
+    | "unknown";
+  runtime_mode?: "sse" | "intelligence";
+  runtime_url_type?: RuntimeUrlType;
+  /** True when an unseen announcement was on screen at open time. */
+  has_unseen_announcement?: boolean;
+};
+
+/**
+ * Panel-open signal (OSS-566). Before this event, opens could only be
+ * inferred from in-panel activity (a floor) or from `banner_clicked`
+ * cta=`body` (which misses the floating-button path entirely).
+ */
+export function trackInspectorOpened(
+  props: InspectorOpenedTelemetryProps,
+): void {
+  track(TELEMETRY_EVENTS.opened, props);
+}
+
 export type InspectorThreadTelemetryProps = {
   package_name?: typeof PACKAGE_NAME;
   package_version?: string;

package/src/lib/testing/telemetry-egress-guard.ts

@@ -0,0 +1,33 @@
+// Test-only helper (imported by vitest.setup.ts — never by the bundle entry).
+//
+// This suite runs in jsdom, where a real `fetch` exists. Inspector telemetry is
+// browser-side and fire-and-forget, so any test that drives a banner / threads /
+// open code path without stubbing fetch POSTs a real `oss.inspector.*` event to
+// the live sink — from a developer's machine and from every CI run — polluting
+// the dataset with traffic indistinguishable from user activity. The
+// announcement-dismissal tests did exactly this before this guard existed.
+//
+// No environment variable can prevent it: the inspector's opt-out is the
+// runtime's `/info` response, and these tests never boot a runtime.
+//
+// The guard swallows requests to the sink and delegates everything else, so
+// tests that stub or spy on fetch themselves are unaffected.
+
+export const TELEMETRY_SINK_ORIGIN = "https://telemetry.copilotkit.ai";
+
+export function createTelemetryEgressGuard(
+  realFetch: typeof fetch,
+): typeof fetch {
+  return (input, init) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.href
+          : input.url;
+    if (url?.startsWith(TELEMETRY_SINK_ORIGIN)) {
+      return Promise.resolve(new Response(null, { status: 204 }));
+    }
+    return realFetch(input, init);
+  };
+}

package/vitest.setup.ts

@@ -18,6 +18,14 @@
 
 import { beforeEach } from "vitest";
 
+import { createTelemetryEgressGuard } from "./src/lib/testing/telemetry-egress-guard.js";
+
+// No test may POST a real `oss.inspector.*` event to the live telemetry sink —
+// see the helper for why no environment variable can cover this.
+if (typeof globalThis.fetch === "function") {
+  globalThis.fetch = createTelemetryEgressGuard(globalThis.fetch);
+}
+
 function createStorageShim(): Storage {
   const store = new Map<string, string>();
   const shim = {