assistant-cloud 0.1.43 → 0.2.1

package/src/tests/AssistantCloud.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { AssistantCloud } from "../AssistantCloud";
 import type { AssistantCloudTelemetryConfig } from "../AssistantCloudAPI";
 
@@ -13,6 +13,10 @@ const createCloud = (
   });
 
 describe("AssistantCloud telemetry config", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   it("defaults to enabled", () => {
     expect(createCloud().telemetry.enabled).toBe(true);
     expect(createCloud(true).telemetry.enabled).toBe(true);
@@ -23,6 +27,13 @@ describe("AssistantCloud telemetry config", () => {
     expect(createCloud({ enabled: false }).telemetry.enabled).toBe(false);
   });
 
+  it("can disable engagement events without disabling run reports", () => {
+    expect(createCloud({ events: false }).telemetry).toEqual({
+      enabled: true,
+      events: false,
+    });
+  });
+
   it("stays enabled when the config object carries an undefined enabled", () => {
     const beforeReport: NonNullable<
       AssistantCloudTelemetryConfig["beforeReport"]
@@ -36,4 +47,47 @@ describe("AssistantCloud telemetry config", () => {
     expect(telemetry.enabled).toBe(true);
     expect(telemetry.beforeReport).toBe(beforeReport);
   });
+
+  it("preserves configured run report dimensions", () => {
+    expect(
+      createCloud({
+        release: "web-2026.09.08",
+        environment: "production",
+        tags: ["region:sg", "tier:paid"],
+      }).telemetry,
+    ).toEqual({
+      enabled: true,
+      release: "web-2026.09.08",
+      environment: "production",
+      tags: ["region:sg", "tier:paid"],
+    });
+  });
+
+  it("forwards registered SDK identities to requests and stream options", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers(),
+      text: vi.fn().mockResolvedValue(JSON.stringify({ threads: [] })),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const cloud = createCloud();
+    cloud.registerSdk({ name: "@assistant-ui/core", version: "0.3.18" });
+
+    await cloud.threads.list();
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(init.headers).toMatchObject({
+      "Aui-Sdk": expect.stringMatching(
+        /^assistant-cloud\/.* @assistant-ui\/core\/0\.3\.18$/,
+      ),
+    });
+    await expect(
+      cloud.runs.__internal_getAssistantOptions("assistant-id").headers(),
+    ).resolves.toMatchObject({
+      "Aui-Sdk": expect.stringMatching(
+        /^assistant-cloud\/.* @assistant-ui\/core\/0\.3\.18$/,
+      ),
+    });
+  });
 });

package/src/tests/AssistantCloudAPI.test.ts

@@ -45,6 +45,7 @@ describe("AssistantCloudAPI", () => {
       Authorization: "Bearer test-key",
       "Aui-User-Id": "u-1",
       "Aui-Workspace-Id": "w-1",
+      "Aui-Sdk": expect.stringMatching(/^assistant-cloud\//),
       "Content-Type": "application/json",
       "X-Test": "1",
     });
@@ -53,6 +54,56 @@ describe("AssistantCloudAPI", () => {
     expect(init.body).toBe(JSON.stringify({ hello: "world" }));
   });
 
+  it("ignores identities that cannot travel in a header", () => {
+    const api = new AssistantCloudAPI({
+      apiKey: "test-key",
+      userId: "u-1",
+      workspaceId: "w-1",
+    });
+    api.registerSdk({ name: "bad name", version: "1.0.0" });
+    api.registerSdk({ name: "@scope/pkg", version: "1.0.0 ok" });
+    api.registerSdk({ name: "@scope/pkg\ttab", version: "1.0.0" });
+    api.registerSdk({ name: "@scope/ok", version: " 1.0.0 " });
+
+    expect(api.sdkHeader().split(" ")).toEqual([
+      expect.stringMatching(/^assistant-cloud\//),
+      "@scope/ok/1.0.0",
+    ]);
+  });
+
+  it("sends each registered SDK identity once in registration order", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers(),
+      json: vi.fn().mockResolvedValue({}),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new AssistantCloudAPI({
+      apiKey: "test-key",
+      userId: "u-1",
+      workspaceId: "w-1",
+    });
+
+    api.registerSdk({ name: " @assistant-ui/core ", version: " 0.3.18 " });
+    api.registerSdk({ name: "@assistant-ui/core", version: "0.3.18" });
+    api.registerSdk({ name: "@assistant-ui/ai-sdk", version: "0.0.5" });
+    api.registerSdk({ name: " ", version: "0.0.5" });
+    api.registerSdk({ name: "@assistant-ui/react-langgraph", version: " " });
+
+    await api.makeRawRequest("/threads", {
+      headers: { "Aui-Sdk": "overridden" },
+    });
+
+    const [, init] = fetchMock.mock.calls[0]!;
+    expect(init.headers).toMatchObject({ "Aui-Sdk": api.sdkHeader() });
+    expect(api.sdkHeader().split(" ")).toEqual([
+      expect.stringMatching(/^assistant-cloud\//),
+      "@assistant-ui/core/0.3.18",
+      "@assistant-ui/ai-sdk/0.0.5",
+    ]);
+  });
+
   it("uses custom baseUrl when provided with apiKey config", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
@@ -143,7 +194,7 @@ describe("AssistantCloudAPI", () => {
     );
   });
 
-  it("throws APIError with parsed message for JSON error responses", async () => {
+  it("preserves the current error shape for JSON error responses without a code", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: false,
       status: 400,
@@ -167,16 +218,54 @@ describe("AssistantCloudAPI", () => {
     expect(error.name).toBe("CloudAPIError");
     expect(error.message).toBe("invalid request payload");
     expect(error.status).toBe(400);
+    expect(error.code).toBeUndefined();
+    expect(error.details).toBeUndefined();
+  });
+
+  it("exposes the plan-limit error code and details", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 402,
+      headers: new Headers(),
+      text: vi.fn().mockResolvedValue(
+        JSON.stringify({
+          error: "plan_limit_reached",
+          plan: "free",
+          period_end: "2026-10-01T00:00:00.000Z",
+          cap: 100,
+        }),
+      ),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new AssistantCloudAPI({
+      apiKey: "test-key",
+      userId: "u-1",
+      workspaceId: "w-1",
+    });
+
+    const error = await api.makeRawRequest("/threads").catch((e) => e);
+    expect(error).toBeInstanceOf(CloudAPIError);
+    expect(error.message).toBe(
+      'Request failed with status 402, {"error":"plan_limit_reached","plan":"free","period_end":"2026-10-01T00:00:00.000Z","cap":100}',
+    );
+    expect(error.status).toBe(402);
+    expect(error.code).toBe("plan_limit_reached");
+    expect(error.details).toEqual({
+      plan: "free",
+      period_end: "2026-10-01T00:00:00.000Z",
+      cap: 100,
+    });
   });
 
-  it("falls back to the response text when the JSON error body has no message", async () => {
+  it("exposes rate-limit error codes with empty details", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: false,
       status: 429,
       headers: new Headers(),
       text: vi
         .fn()
-        .mockResolvedValue(JSON.stringify({ error: "rate limited" })),
+        .mockResolvedValue(JSON.stringify({ error: "rate_limited" })),
     });
     vi.stubGlobal("fetch", fetchMock);
 
@@ -189,9 +278,11 @@ describe("AssistantCloudAPI", () => {
     const error = await api.makeRawRequest("/threads").catch((e) => e);
     expect(error).toBeInstanceOf(CloudAPIError);
     expect(error.message).toBe(
-      'Request failed with status 429, {"error":"rate limited"}',
+      'Request failed with status 429, {"error":"rate_limited"}',
     );
     expect(error.status).toBe(429);
+    expect(error.code).toBe("rate_limited");
+    expect(error.details).toEqual({});
   });
 
   it("throws generic error with status for non-JSON error responses", async () => {

package/src/tests/AssistantCloudAuthStrategy.test.ts

@@ -1,7 +1,9 @@
+/// <reference types="node" />
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   AssistantCloudAnonymousAuthStrategy,
   AssistantCloudJWTAuthStrategy,
+  readAnonymousRefreshToken,
 } from "../AssistantCloudAuthStrategy";
 import { CloudResponseError } from "../cloudResponse";
 
@@ -56,6 +58,73 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     }
   });
 
+  it("reads the stored anonymous refresh token", () => {
+    const values = new Map([[refreshTokenKey, JSON.stringify(refreshToken)]]);
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+
+    expect(readAnonymousRefreshToken(baseUrl)).toBe(refreshToken.token);
+  });
+
+  it("reads the token stored for a base url given with a trailing slash", () => {
+    // The two-step cast below erases the contextual Storage typing the plain
+    // `as Storage` sites get, so this parameter needs its own annotation.
+    installLocalStorage({
+      getItem: (key: string) =>
+        key === refreshTokenKey ? JSON.stringify(refreshToken) : null,
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    } as unknown as Storage);
+
+    expect(readAnonymousRefreshToken(`${baseUrl}/`)).toBe(refreshToken.token);
+  });
+
+  it("returns null when no anonymous refresh token is stored", () => {
+    installLocalStorage({
+      getItem: () => null,
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    } as unknown as Storage);
+
+    expect(readAnonymousRefreshToken(baseUrl)).toBeNull();
+  });
+
+  it.each([30_000, 0, -1])(
+    "returns null when the stored anonymous refresh token expires in %i ms",
+    (expiresIn) => {
+      vi.useFakeTimers();
+      const now = Date.UTC(2026, 8, 4, 12, 0, 0);
+      vi.setSystemTime(now);
+      const values = new Map([
+        [
+          refreshTokenKey,
+          JSON.stringify({
+            token: refreshToken.token,
+            expires_at: new Date(now + expiresIn).toISOString(),
+          }),
+        ],
+      ]);
+      installLocalStorage({
+        getItem: (key) => values.get(key) ?? null,
+        setItem: (key, value) => {
+          values.set(key, value);
+        },
+        removeItem: (key) => {
+          values.delete(key);
+        },
+      } as Storage);
+
+      expect(readAnonymousRefreshToken(baseUrl)).toBeNull();
+    },
+  );
+
   it.each([
     "2099-01-01",
     "2099-01-01T00:00:00Z",
@@ -269,7 +338,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
                 { once: true },
               );
             }),
-        } as Response),
+        } as unknown as Response),
       )
       .mockResolvedValueOnce({
         ok: true,
@@ -598,7 +667,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     const removeItem = vi.fn(() => {
       throw new DOMException("blocked", "SecurityError");
     });
-    installLocalStorage({ getItem, setItem, removeItem } as Storage);
+    installLocalStorage({ getItem, setItem, removeItem } as unknown as Storage);
     mockAnonymousTokenFetch();
 
     await expect(
@@ -881,4 +950,26 @@ describe("AssistantCloudJWTAuthStrategy", () => {
     });
     expect(authToken).toHaveBeenCalledTimes(2);
   });
+
+  it("does not cache a malformed rotated token", async () => {
+    const authToken = vi
+      .fn<() => Promise<string | null>>()
+      .mockResolvedValue(accessToken);
+    const strategy = new AssistantCloudJWTAuthStrategy(authToken);
+
+    await expect(strategy.getAuthHeaders()).resolves.toEqual({
+      Authorization: `Bearer ${accessToken}`,
+    });
+
+    expect(() =>
+      strategy.readAuthHeaders(
+        new Headers({ Authorization: "Bearer malformed" }),
+      ),
+    ).toThrow("Unable to determine the token expiry");
+
+    await expect(strategy.getAuthHeaders()).resolves.toEqual({
+      Authorization: `Bearer ${accessToken}`,
+    });
+    expect(authToken).toHaveBeenCalledTimes(1);
+  });
 });

package/src/tests/AssistantCloudProjects.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, vi } from "vitest";
 import { AssistantCloudProjects } from "../AssistantCloudProjects";
 import type { AssistantCloudAPI } from "../AssistantCloudAPI";
 
@@ -19,10 +19,6 @@ describe("AssistantCloudProjects", () => {
     projects = new AssistantCloudProjects(mockApi);
   });
 
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
   it("lists project threads with the query", async () => {
     vi.mocked(mockApi.makeRequest).mockResolvedValue({ threads: [] });
 

package/src/tests/CloudEngagementReporter.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloud } from "../AssistantCloud";
+import {
+  CloudEngagementReporter,
+  type EngagementIdResolver,
+} from "../CloudEngagementReporter";
+
+const createCloud = () => {
+  const track = vi.fn();
+  const cloud = { events: { track } } as unknown as AssistantCloud;
+  return { cloud, track };
+};
+
+const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe("CloudEngagementReporter", () => {
+  it("resolves ids through the resolver and awaits the thread only for a send", async () => {
+    const { cloud, track } = createCloud();
+    const resolveIds = vi.fn<EngagementIdResolver>(
+      async (threadId, messageId) => ({
+        thread_id: `remote-${threadId}`,
+        ...(messageId ? { message_id: `remote-${messageId}` } : undefined),
+      }),
+    );
+    const reporter = new CloudEngagementReporter(cloud, resolveIds);
+
+    reporter.messageSent("t1", { messageId: "m1", chars: 12, attachments: 1 });
+    reporter.messageCopied("t1", "m2");
+    await flush();
+
+    expect(resolveIds).toHaveBeenNthCalledWith(1, "t1", "m1", {
+      awaitThread: true,
+    });
+    expect(resolveIds).toHaveBeenNthCalledWith(2, "t1", "m2", {
+      awaitThread: false,
+    });
+    expect(track).toHaveBeenCalledWith({
+      kind: "message_sent",
+      thread_id: "remote-t1",
+      message_id: "remote-m1",
+      props: { chars: 12, attachments: 1 },
+    });
+    expect(track).toHaveBeenCalledWith({
+      kind: "message_copied",
+      thread_id: "remote-t1",
+      message_id: "remote-m2",
+    });
+  });
+
+  it("reports tool approval decisions with their resolved message IDs", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(
+      cloud,
+      (threadId, messageId) => ({
+        thread_id: `remote-${threadId}`,
+        ...(messageId !== undefined
+          ? { message_id: `remote-${messageId}` }
+          : {}),
+      }),
+    );
+
+    reporter.toolApproved("t1", "m1", "tool-1", "send_email");
+    reporter.toolRejected("t1", "m2", "tool-2", "delete_account");
+    await flush();
+
+    expect(track).toHaveBeenNthCalledWith(1, {
+      kind: "tool_approved",
+      thread_id: "remote-t1",
+      message_id: "remote-m1",
+      props: { toolCallId: "tool-1", toolName: "send_email" },
+    });
+    expect(track).toHaveBeenNthCalledWith(2, {
+      kind: "tool_rejected",
+      thread_id: "remote-t1",
+      message_id: "remote-m2",
+      props: { toolCallId: "tool-2", toolName: "delete_account" },
+    });
+  });
+
+  it("measures a stop against the run start and reports it once per run", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+
+    vi.setSystemTime(new Date("2023-01-01T00:00:00.000Z"));
+    reporter.runStopped("t1");
+    reporter.runStarted("t1");
+    vi.setSystemTime(new Date("2023-01-01T00:00:01.500Z"));
+    reporter.runStopped("t1");
+    reporter.runStopped("t1");
+    await flush();
+
+    expect(track).toHaveBeenCalledOnce();
+    expect(track).toHaveBeenCalledWith({
+      kind: "run_stopped",
+      thread_id: "t1",
+      value: 1500,
+    });
+  });
+
+  it("carries the time since the previous run ended on the next send", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+
+    vi.setSystemTime(new Date("2023-01-01T00:00:00.000Z"));
+    reporter.runStarted("t1");
+    reporter.runEnded("t1");
+    vi.setSystemTime(new Date("2023-01-01T00:00:04.000Z"));
+    reporter.messageSent("t1", { chars: 3, attachments: 0 });
+    await flush();
+
+    expect(track).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "message_sent", value: 4000 }),
+    );
+  });
+
+  it("shows one error per run and one suggestion list per thread", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+
+    reporter.runStarted("t1");
+    reporter.errorShown("t1", { messageId: "m1", reason: "error" });
+    reporter.errorShown("t1", { messageId: "m1", reason: "error" });
+    reporter.runStarted("t1");
+    reporter.errorShown("t1", { reason: "timeout" });
+    reporter.suggestionsShown("t1", 3);
+    reporter.suggestionsShown("t1", 3);
+    await flush();
+
+    const kinds = track.mock.calls.map(([event]) => event.kind);
+    expect(kinds).toEqual(["error_shown", "error_shown", "suggestions_shown"]);
+    expect(track).toHaveBeenCalledWith({
+      kind: "suggestions_shown",
+      thread_id: "t1",
+      value: 3,
+    });
+  });
+
+  it("drops a thread switch the cloud cannot attribute and survives a failing resolver", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud, (threadId) =>
+      threadId === "known" ? { thread_id: "remote" } : {},
+    );
+    reporter.threadSwitched("unknown");
+    reporter.threadSwitched("known");
+    const failing = new CloudEngagementReporter(cloud, () => {
+      throw new Error("no ids");
+    });
+    failing.messageCopied("t1");
+    await flush();
+
+    expect(track).toHaveBeenCalledOnce();
+    expect(track).toHaveBeenCalledWith({
+      kind: "thread_switched",
+      thread_id: "remote",
+    });
+  });
+
+  it("keeps the state of the most recently touched threads only", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+    for (let index = 0; index < 300; index++) {
+      reporter.suggestionsShown(`t${index}`, 1);
+    }
+    reporter.suggestionsShown("t0", 1);
+    reporter.suggestionsShown("t299", 1);
+    await flush();
+
+    expect(track).toHaveBeenCalledTimes(301);
+  });
+
+  it("keeps a started run until it stops, however many threads ran since", async () => {
+    const { cloud, track } = createCloud();
+    const reporter = new CloudEngagementReporter(cloud);
+    for (let index = 0; index < 300; index++) {
+      reporter.runStarted(`t${index}`);
+    }
+    reporter.runStopped("t0");
+    await flush();
+
+    expect(track).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "run_stopped", thread_id: "t0" }),
+    );
+  });
+});