@copilotkit/learning 0.0.1

package/src/__tests__/collector.test.ts

@@ -0,0 +1,307 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createCollector } from "../collector";
+import type { CollectorOptions, LearningBatch, LearningSink } from "../types";
+
+const NOW = 1_790_000_000_000;
+const realFetch = globalThis.fetch;
+const fakeFetch = vi.fn<typeof fetch>(
+  async () => new Response(null, { status: 204 }),
+);
+let stopCurrent: (() => void) | undefined;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(NOW);
+  globalThis.fetch = fakeFetch;
+  history.replaceState(null, "", "/learning");
+});
+
+afterEach(() => {
+  stopCurrent?.();
+  stopCurrent = undefined;
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  globalThis.fetch = realFetch;
+});
+
+function setup(overrides: Partial<CollectorOptions> = {}) {
+  const batches: LearningBatch[] = [];
+  const sink: LearningSink = (batch) => {
+    batches.push(batch);
+  };
+  const collector = createCollector({
+    sink,
+    routes: ["/learning/deals/:id"],
+    ...overrides,
+  });
+  stopCurrent = () => collector.stop();
+  return { collector, batches };
+}
+
+function names(batches: LearningBatch[]) {
+  return batches.flatMap((batch) => batch.events.map((event) => event.name));
+}
+
+describe("createCollector", () => {
+  it("installs nothing before start", () => {
+    const { batches } = setup();
+
+    history.pushState(null, "", "/learning/deals/1");
+    vi.advanceTimersByTime(5000);
+
+    expect(globalThis.fetch).toBe(fakeFetch);
+    expect(batches).toEqual([]);
+  });
+
+  it("sends a page event, then batches every 2 seconds", () => {
+    const { collector, batches } = setup();
+
+    collector.start({ trajectoryId: "traj-1", learningContainerIds: ["c-1"] });
+    history.pushState(null, "", "/learning/deals/1");
+    vi.advanceTimersByTime(2000);
+
+    expect(batches).toEqual([
+      {
+        trajectoryId: "traj-1",
+        learningContainerIds: ["c-1"],
+        dropped: 0,
+        events: [
+          {
+            type: "CUSTOM",
+            name: "page",
+            timestamp: NOW,
+            value: {
+              route: "/learning",
+              url: `${location.origin}/learning`,
+              title: document.title,
+              referrer: document.referrer,
+              seq: 1,
+            },
+          },
+          {
+            type: "CUSTOM",
+            name: "navigation",
+            timestamp: NOW,
+            value: {
+              from: `${location.origin}/learning`,
+              to: `${location.origin}/learning/deals/1`,
+              navigationType: "push",
+              seq: 2,
+            },
+          },
+        ],
+      },
+    ]);
+  });
+
+  it("flushes as soon as 50 events are queued", () => {
+    const { collector, batches } = setup();
+    collector.start({ trajectoryId: "traj-1" });
+
+    for (let index = 0; index < 49; index += 1)
+      collector.emit("deal.viewed", { index });
+
+    expect(batches).toHaveLength(1);
+    expect(batches[0]?.events).toHaveLength(50);
+  });
+
+  it("ignores a second start with the same id and warns for another id", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { collector, batches } = setup();
+
+    collector.start({ trajectoryId: "traj-1" });
+    collector.start({ trajectoryId: "traj-1" });
+    collector.start({ trajectoryId: "traj-2" });
+    vi.advanceTimersByTime(2000);
+
+    expect(collector.trajectoryId).toBe("traj-1");
+    expect(names(batches)).toEqual(["page"]);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("starts without the password watcher when the DOM is partial", () => {
+    vi.spyOn(document, "querySelectorAll").mockImplementation(() => {
+      throw new Error("no query support");
+    });
+    vi.stubGlobal(
+      "MutationObserver",
+      class {
+        observe() {
+          throw new Error("no observer support");
+        }
+        disconnect() {}
+        takeRecords() {
+          return [];
+        }
+      },
+    );
+    const { collector } = setup();
+
+    expect(() => collector.start({ trajectoryId: "traj-1" })).not.toThrow();
+    expect(collector.trajectoryId).toBe("traj-1");
+    expect(() => collector.stop()).not.toThrow();
+  });
+
+  it("installs hooks once across start, stop, start (StrictMode)", () => {
+    const { collector, batches } = setup();
+
+    collector.start({ trajectoryId: "traj-1" });
+    collector.stop();
+    collector.start({ trajectoryId: "traj-1" });
+    history.pushState(null, "", "/learning/deals/9");
+    vi.advanceTimersByTime(2000);
+
+    expect(names(batches)).toEqual(["page", "page", "navigation"]);
+    expect(
+      batches.flatMap((batch) => batch.events.map((event) => event.value.seq)),
+    ).toEqual([1, 2, 3]);
+  });
+
+  it("sends the final outcome once and removes capture hooks on stop", () => {
+    const { collector, batches } = setup();
+    collector.start({ trajectoryId: "traj-1" });
+    collector.emit("deal.approved", { dealId: "deal-1" });
+
+    collector.stop();
+    collector.stop();
+    collector.emit("deal.viewed", {});
+    history.pushState(null, "", "/learning/deals/1");
+    vi.advanceTimersByTime(5000);
+
+    expect(batches).toHaveLength(1);
+    expect(batches[0]?.trajectoryId).toBe("traj-1");
+    expect(names(batches)).toEqual(["page", "deal.approved"]);
+    expect(batches[0]?.events[1]?.value).toEqual({ dealId: "deal-1", seq: 2 });
+    expect(collector.trajectoryId).toBeNull();
+    expect(globalThis.fetch).toBe(fakeFetch);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each(["throw", "reject"])(
+    "does not retry or carry failed final events into the next trajectory (%s)",
+    async (failure) => {
+      const sink = vi.fn<LearningSink>(() => {
+        if (failure === "throw") throw new Error("offline");
+        return Promise.reject(new Error("offline"));
+      });
+      const { collector } = setup({ sink });
+      collector.start({ trajectoryId: "traj-1" });
+      collector.emit("deal.approved", {});
+
+      expect(() => collector.stop()).not.toThrow();
+      expect(collector.trajectoryId).toBeNull();
+      sink.mockImplementation(() => {});
+      collector.start({ trajectoryId: "traj-2" });
+      await vi.advanceTimersByTimeAsync(5000);
+
+      expect(sink).toHaveBeenCalledTimes(2);
+      expect(sink.mock.calls[1]?.[0]).toMatchObject({
+        trajectoryId: "traj-2",
+        dropped: 0,
+        events: [{ name: "page", value: { seq: 3 } }],
+      });
+    },
+  );
+
+  it("retains raw paths and full URLs in captured activity", async () => {
+    history.replaceState(null, "", "/reset/eyJhbGc.eyJzdWIi.sig");
+    const { collector, batches } = setup();
+    collector.start({ trajectoryId: "traj-1" });
+    history.pushState(null, "", "/users/jane@x.com?q=hello#details");
+    await fetch("/search/private%20search");
+    await vi.advanceTimersByTimeAsync(0);
+
+    collector.stop();
+
+    expect(batches[0]?.events).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: "page",
+          value: expect.objectContaining({
+            route: "/reset/eyJhbGc.eyJzdWIi.sig",
+          }),
+        }),
+        expect.objectContaining({
+          name: "navigation",
+          value: expect.objectContaining({
+            from: `${location.origin}/reset/eyJhbGc.eyJzdWIi.sig`,
+            to: `${location.origin}/users/jane@x.com?q=hello#details`,
+          }),
+        }),
+        expect.objectContaining({
+          name: "network",
+          value: expect.objectContaining({ route: "/search/private%20search" }),
+        }),
+      ]),
+    );
+  });
+
+  it("lets beforeSend redact or drop events", () => {
+    const { collector, batches } = setup({
+      beforeSend: (event) =>
+        event.name === "deal.secret"
+          ? null
+          : { ...event, value: { ...event.value, route: "redacted" } },
+    });
+    collector.start({ trajectoryId: "traj-1" });
+    collector.emit("deal.secret", {});
+
+    vi.advanceTimersByTime(2000);
+
+    expect(
+      batches[0]?.events.map((event) => [event.name, event.value.route]),
+    ).toEqual([["page", "redacted"]]);
+  });
+
+  it("rejects built-in names from emit but accepts them from ɵemit", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { collector, batches } = setup();
+    collector.start({ trajectoryId: "traj-1" });
+
+    collector.emit("click", { fake: true });
+    collector.ɵemit("thread.linked", { threadId: "t-1" });
+    vi.advanceTimersByTime(2000);
+
+    expect(names(batches)).toEqual(["page", "thread.linked"]);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("survives a failing sink and reports the loss in the next batch", async () => {
+    const batches: LearningBatch[] = [];
+    let calls = 0;
+    const sink: LearningSink = async (batch) => {
+      calls += 1;
+      if (calls === 1) throw new Error("offline");
+      batches.push(batch);
+    };
+    const { collector } = setup({ sink });
+    collector.start({ trajectoryId: "traj-1" });
+    collector.emit("deal.viewed", {});
+
+    vi.advanceTimersByTime(2000);
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(batches).toEqual([
+      {
+        trajectoryId: "traj-1",
+        learningContainerIds: undefined,
+        dropped: 2,
+        events: [],
+      },
+    ]);
+  });
+
+  it("flushes with beacon on pagehide", () => {
+    const sends: unknown[] = [];
+    const sink: LearningSink = (_batch, options) => {
+      sends.push(options);
+    };
+    const { collector } = setup({ sink });
+    collector.start({ trajectoryId: "traj-1" });
+
+    window.dispatchEvent(new Event("pagehide"));
+
+    expect(sends).toEqual([{ beacon: true }]);
+  });
+});

package/src/__tests__/http-sink.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { httpSink } from "../http-sink";
+import type { LearningBatch } from "../types";
+
+const realFetch = globalThis.fetch;
+const realSendBeacon = navigator.sendBeacon;
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  navigator.sendBeacon = realSendBeacon;
+});
+
+function createBatch(): LearningBatch {
+  return {
+    trajectoryId: "traj-1",
+    dropped: 0,
+    events: [
+      {
+        type: "CUSTOM",
+        name: "page",
+        timestamp: 1,
+        value: { seq: 1, route: "/" },
+      },
+    ],
+  };
+}
+
+describe("httpSink", () => {
+  it("POSTs the batch as JSON with keepalive and the extra headers", async () => {
+    const fetchMock = vi.fn<typeof fetch>(
+      async () => new Response(null, { status: 204 }),
+    );
+    globalThis.fetch = fetchMock;
+
+    await httpSink("/api/learning-events", {
+      headers: { "x-project": "demo" },
+    })(createBatch());
+
+    expect(fetchMock.mock.calls[0]?.[1]).toEqual({
+      method: "POST",
+      keepalive: true,
+      headers: { "content-type": "application/json", "x-project": "demo" },
+      body: JSON.stringify(createBatch()),
+    });
+  });
+
+  it("rejects when the sink responds with an error status", async () => {
+    globalThis.fetch = vi.fn<typeof fetch>(
+      async () => new Response(null, { status: 500 }),
+    );
+
+    await expect(
+      httpSink("/api/learning-events")(createBatch()),
+    ).rejects.toThrow("Sink responded with 500");
+  });
+
+  it("uses sendBeacon when the page is going away", async () => {
+    const beacon = vi.fn<typeof navigator.sendBeacon>(() => true);
+    navigator.sendBeacon = beacon;
+    const fetchMock = vi.fn<typeof fetch>();
+    globalThis.fetch = fetchMock;
+
+    await httpSink("/api/learning-events")(createBatch(), { beacon: true });
+
+    expect(beacon.mock.calls[0]?.[0]).toBe("/api/learning-events");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("exposes its url so the collector never captures its own requests", () => {
+    expect(httpSink("/api/learning-events").url).toBe("/api/learning-events");
+  });
+});

package/src/__tests__/inputs.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { installInputCapture } from "../inputs";
+
+let uninstall: (() => void) | undefined;
+afterEach(() => {
+  uninstall?.();
+  document.body.innerHTML = "";
+});
+
+describe("input capture", () => {
+  it("captures edited text, checkbox state, and selected values, and redacts passwords", () => {
+    document.body.innerHTML = `<input id="name"><input id="password" type="password" value="secret"><input id="check" type="checkbox"><textarea id="notes"></textarea><select id="choice" multiple><option value="a" selected>A</option><option value="b" selected>B</option></select><div id="editor" contenteditable="true">Rich text</div>`;
+    const events: Record<string, unknown>[] = [];
+    uninstall = installInputCapture({
+      emit: (name, value) => events.push({ name, ...value }),
+      isTrusted: () => true,
+    });
+    for (const id of [
+      "name",
+      "password",
+      "check",
+      "notes",
+      "choice",
+      "editor",
+    ]) {
+      const element = document.getElementById(id)!;
+      if (
+        element instanceof HTMLInputElement ||
+        element instanceof HTMLTextAreaElement
+      )
+        element.value = `synthetic-${id}`;
+      if (element instanceof HTMLInputElement && element.type === "checkbox")
+        element.checked = true;
+      element.dispatchEvent(new Event("input", { bubbles: true }));
+    }
+    expect(events).toHaveLength(6);
+    expect(events[0]).toMatchObject({
+      name: "input",
+      eventType: "input",
+      url: location.href,
+      target: { value: "synthetic-name", attributes: { id: "name" } },
+    });
+    expect(events[1]).toMatchObject({
+      target: { value: "[redacted]", attributes: { value: "[redacted]" } },
+    });
+    expect(JSON.stringify(events[1])).not.toContain("secret");
+    expect(events[2]).toMatchObject({ target: { checked: true } });
+    expect(events[3]).toMatchObject({ target: { value: "synthetic-notes" } });
+    expect(events[4]).toMatchObject({ target: { selectedValues: ["a", "b"] } });
+    expect(events[5]).toMatchObject({ target: { value: "Rich text" } });
+    uninstall();
+    document
+      .getElementById("name")!
+      .dispatchEvent(new Event("change", { bubbles: true }));
+    expect(events).toHaveLength(6);
+  });
+
+  it("ignores synthetic edits by default and honors explicit opt-outs", () => {
+    document.body.innerHTML = `<input id="field" value="synthetic" data-copilotkit-ignore>`;
+    // Assert externally because capture deliberately catches observer exceptions.
+    const events: unknown[] = [];
+    uninstall = installInputCapture({ emit: (...args) => events.push(args) });
+    document
+      .getElementById("field")!
+      .dispatchEvent(new Event("input", { bubbles: true }));
+    expect(events).toEqual([]);
+    uninstall();
+    uninstall = installInputCapture({
+      emit: (...args) => events.push(args),
+      isTrusted: () => true,
+    });
+    document
+      .getElementById("field")!
+      .dispatchEvent(new Event("change", { bubbles: true }));
+    expect(events).toEqual([]);
+  });
+});

package/src/__tests__/navigation.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { installNavigationCapture } from "../navigation";
+
+interface Captured {
+  name: string;
+  value: Record<string, unknown>;
+}
+
+const originalPushState = History.prototype.pushState;
+const originalReplaceState = History.prototype.replaceState;
+let uninstall: (() => void) | undefined;
+
+beforeEach(() => {
+  originalReplaceState.call(history, null, "", "/learning");
+});
+
+afterEach(() => {
+  uninstall?.();
+  uninstall = undefined;
+  Reflect.deleteProperty(history, "pushState");
+});
+
+function setup() {
+  const events: Captured[] = [];
+  uninstall = installNavigationCapture({
+    emit: (name, value) => events.push({ name, value }),
+    routes: ["/learning/deals/:id"],
+  });
+  return events;
+}
+
+describe("installNavigationCapture (history fallback)", () => {
+  it("emits push and replace when the full URL changes", () => {
+    const events = setup();
+
+    history.pushState(null, "", "/learning/deals/42");
+    history.replaceState(null, "", "/learning/events");
+
+    expect(events).toEqual([
+      {
+        name: "navigation",
+        value: {
+          from: `${location.origin}/learning`,
+          to: `${location.origin}/learning/deals/42`,
+          navigationType: "push",
+        },
+      },
+      {
+        name: "navigation",
+        value: {
+          from: `${location.origin}/learning/deals/42`,
+          to: `${location.origin}/learning/events`,
+          navigationType: "replace",
+        },
+      },
+    ]);
+  });
+
+  it("records changes within a route, including query strings and fragments", () => {
+    const events = setup();
+
+    history.pushState(null, "", "/learning/deals/1");
+    history.pushState(null, "", "/learning/deals/2?tab=notes#top");
+
+    expect(events).toHaveLength(2);
+    expect(events[1]?.value.to).toBe(
+      `${location.origin}/learning/deals/2?tab=notes#top`,
+    );
+  });
+
+  it("still fires when a router wrapped the instance method before install", () => {
+    const routerPushState = history.pushState;
+    history.pushState = function (...args) {
+      return routerPushState.apply(this, args);
+    };
+    const events = setup();
+
+    history.pushState(null, "", "/learning/deals/7");
+
+    expect(events).toEqual([
+      {
+        name: "navigation",
+        value: {
+          from: `${location.origin}/learning`,
+          to: `${location.origin}/learning/deals/7`,
+          navigationType: "push",
+        },
+      },
+    ]);
+  });
+
+  it("emits traverse on back navigation", async () => {
+    const events = setup();
+    history.pushState(null, "", "/learning/deals/3");
+    const popped = new Promise((resolve) =>
+      window.addEventListener("popstate", resolve, { once: true }),
+    );
+
+    history.back();
+    await popped;
+
+    expect(events.at(-1)?.value).toEqual({
+      from: `${location.origin}/learning/deals/3`,
+      to: `${location.origin}/learning`,
+      navigationType: "traverse",
+    });
+  });
+
+  it("restores the original history methods on uninstall", () => {
+    setup();
+    uninstall?.();
+    uninstall = undefined;
+
+    expect(History.prototype.pushState).toBe(originalPushState);
+    expect(History.prototype.replaceState).toBe(originalReplaceState);
+  });
+});