assistant-cloud 0.1.42 → 0.2.0

package/src/tests/AssistantCloud.test.ts

@@ -23,6 +23,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 +43,19 @@ 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"],
+    });
+  });
 });

package/src/tests/AssistantCloudAPI.test.ts

@@ -143,7 +143,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 +167,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("falls back to the response text when the JSON error body has no message", async () => {
+  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("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 +227,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";
 
@@ -43,6 +45,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
   });
 
   afterEach(() => {
+    vi.useRealTimers();
     vi.unstubAllGlobals();
     if (originalLocalStorageDescriptor) {
       Object.defineProperty(
@@ -55,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",
@@ -83,7 +153,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     expect(values.get(refreshTokenKey)).toBe(JSON.stringify(nextRefreshToken));
     expect(fetchMock).toHaveBeenCalledWith(
       `${baseUrl}/v1/auth/tokens/anonymous`,
-      { method: "POST" },
+      { method: "POST", signal: expect.any(AbortSignal) },
     );
   });
 
@@ -106,6 +176,276 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
+  it("deduplicates anonymous token requests across strategy instances", async () => {
+    const values = new Map<string, string>();
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    const fetchMock = mockAnonymousTokenFetch();
+    const first = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+    const second = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    await expect(
+      Promise.all([first.getAuthHeaders(), second.getAuthHeaders()]),
+    ).resolves.toEqual([
+      { Authorization: `Bearer ${accessToken}` },
+      { Authorization: `Bearer ${accessToken}` },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+  });
+
+  it("coordinates anonymous token requests across realms", async () => {
+    const values = new Map<string, string>();
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    let lockTail: Promise<unknown> = Promise.resolve();
+    const lockRequest = vi.fn(
+      (_name: string, callback: () => Promise<string | null>) => {
+        const request = lockTail.then(callback);
+        lockTail = request.then(
+          () => undefined,
+          () => undefined,
+        );
+        return request;
+      },
+    );
+    vi.stubGlobal("navigator", { locks: { request: lockRequest } });
+    const rotatedRefreshToken = { token: "r2", expires_at: "2099-01-01" };
+    const response = (refreshTokenValue: typeof refreshToken) => ({
+      ok: true,
+      json: vi.fn().mockResolvedValue({
+        access_token: accessToken,
+        refresh_token: refreshTokenValue,
+      }),
+    });
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(response(refreshToken))
+      .mockResolvedValueOnce(response(rotatedRefreshToken));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const first = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+    vi.resetModules();
+    const { AssistantCloudAnonymousAuthStrategy: Second } =
+      await import("../AssistantCloudAuthStrategy");
+
+    await expect(
+      Promise.all([
+        first.getAuthHeaders(),
+        new Second(baseUrl).getAuthHeaders(),
+      ]),
+    ).resolves.toEqual([
+      { Authorization: `Bearer ${accessToken}` },
+      { Authorization: `Bearer ${accessToken}` },
+    ]);
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      `${baseUrl}/v1/auth/tokens/anonymous`,
+      { method: "POST", signal: expect.any(AbortSignal) },
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      `${baseUrl}/v1/auth/tokens/refresh`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: refreshToken.token }),
+        signal: expect.any(AbortSignal),
+      },
+    );
+    expect(lockRequest).toHaveBeenCalledTimes(2);
+    expect(values.get(refreshTokenKey)).toBe(
+      JSON.stringify(rotatedRefreshToken),
+    );
+  });
+
+  it("retries shared anonymous token requests after a failure", async () => {
+    const values = new Map<string, string>();
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    const failure = new Error("authentication unavailable");
+    const fetchMock = vi
+      .fn()
+      .mockRejectedValueOnce(failure)
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: refreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+    const first = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+    const second = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    await Promise.all([
+      expect(first.getAuthHeaders()).rejects.toBe(failure),
+      expect(second.getAuthHeaders()).rejects.toBe(failure),
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    await expect(
+      new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
+    ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("aborts timed out shared anonymous token requests before retrying", async () => {
+    vi.useFakeTimers();
+    const values = new Map<string, string>();
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    let requestSignal: AbortSignal | null | undefined;
+    const fetchMock = vi
+      .fn()
+      .mockImplementationOnce((_input: RequestInfo | URL, init?: RequestInit) =>
+        Promise.resolve({
+          ok: true,
+          json: () =>
+            new Promise<never>((_resolve, reject) => {
+              requestSignal = init?.signal;
+              requestSignal?.addEventListener(
+                "abort",
+                () => reject(requestSignal?.reason),
+                { once: true },
+              );
+            }),
+        } as unknown as Response),
+      )
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: refreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+    const first = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+    const second = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    const firstRequest = expect(first.getAuthHeaders()).rejects.toThrow(
+      "Assistant Cloud anonymous token request timed out after 30000ms",
+    );
+    const secondRequest = expect(second.getAuthHeaders()).rejects.toThrow(
+      "Assistant Cloud anonymous token request timed out after 30000ms",
+    );
+    await vi.advanceTimersByTimeAsync(0);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(requestSignal).toBeInstanceOf(AbortSignal);
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    await Promise.all([firstRequest, secondRequest]);
+    expect(requestSignal?.aborted).toBe(true);
+    expect(values.has(refreshTokenKey)).toBe(false);
+
+    await expect(
+      new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
+    ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("aborts timed out refresh requests without replacing the identity", async () => {
+    vi.useFakeTimers();
+    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);
+    let requestSignal: AbortSignal | null | undefined;
+    const rotatedRefreshToken = { token: "r2", expires_at: "2099-02-01" };
+    const fetchMock = vi
+      .fn()
+      .mockImplementationOnce(
+        (_input: RequestInfo | URL, init?: RequestInit) =>
+          new Promise<Response>((_resolve, reject) => {
+            requestSignal = init?.signal;
+            requestSignal?.addEventListener(
+              "abort",
+              () => reject(requestSignal?.reason),
+              { once: true },
+            );
+          }),
+      )
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: rotatedRefreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+    const strategy = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    const request = expect(strategy.getAuthHeaders()).rejects.toThrow(
+      "Assistant Cloud refresh token request timed out after 30000ms",
+    );
+    expect(requestSignal).toBeInstanceOf(AbortSignal);
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    await request;
+    expect(requestSignal?.aborted).toBe(true);
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+
+    await expect(strategy.getAuthHeaders()).resolves.toEqual({
+      Authorization: `Bearer ${accessToken}`,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(values.get(refreshTokenKey)).toBe(
+      JSON.stringify(rotatedRefreshToken),
+    );
+  });
+
+  it("keeps anonymous token requests independent without localStorage", async () => {
+    delete (globalThis as { localStorage?: Storage }).localStorage;
+    const lockRequest = vi.fn();
+    vi.stubGlobal("navigator", { locks: { request: lockRequest } });
+    const fetchMock = mockAnonymousTokenFetch();
+    const first = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+    const second = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    await expect(
+      Promise.all([first.getAuthHeaders(), second.getAuthHeaders()]),
+    ).resolves.toEqual([
+      { Authorization: `Bearer ${accessToken}` },
+      { Authorization: `Bearer ${accessToken}` },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(lockRequest).not.toHaveBeenCalled();
+  });
+
   it("scopes anonymous refresh tokens by backend", async () => {
     const secondBaseUrl = "https://other.example.com";
     const values = new Map<string, string>();
@@ -140,20 +480,20 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
       });
     vi.stubGlobal("fetch", fetchMock);
 
-    await new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders();
-    await new AssistantCloudAnonymousAuthStrategy(
-      secondBaseUrl,
-    ).getAuthHeaders();
+    await Promise.all([
+      new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
+      new AssistantCloudAnonymousAuthStrategy(secondBaseUrl).getAuthHeaders(),
+    ]);
 
     expect(fetchMock).toHaveBeenNthCalledWith(
       1,
       `${baseUrl}/v1/auth/tokens/anonymous`,
-      { method: "POST" },
+      { method: "POST", signal: expect.any(AbortSignal) },
     );
     expect(fetchMock).toHaveBeenNthCalledWith(
       2,
       `${secondBaseUrl}/v1/auth/tokens/anonymous`,
-      { method: "POST" },
+      { method: "POST", signal: expect.any(AbortSignal) },
     );
     expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
     expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
@@ -206,12 +546,13 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ refresh_token: refreshToken.token }),
+        signal: expect.any(AbortSignal),
       },
     );
     expect(fetchMock).toHaveBeenNthCalledWith(
       2,
       `${secondBaseUrl}/v1/auth/tokens/anonymous`,
-      { method: "POST" },
+      { method: "POST", signal: expect.any(AbortSignal) },
     );
     expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
     expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
@@ -270,12 +611,13 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ refresh_token: scopedRefreshToken.token }),
+        signal: expect.any(AbortSignal),
       },
     );
     expect(fetchMock).toHaveBeenNthCalledWith(
       2,
       `${secondBaseUrl}/v1/auth/tokens/anonymous`,
-      { method: "POST" },
+      { method: "POST", signal: expect.any(AbortSignal) },
     );
     expect(values.has("aui:refresh_token")).toBe(false);
     expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
@@ -325,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(
@@ -470,6 +812,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ refresh_token: refreshToken.token }),
+        signal: expect.any(AbortSignal),
       },
     );
     expect(setItem).not.toHaveBeenCalled();
@@ -538,7 +881,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
       expect(fetchMock).toHaveBeenNthCalledWith(
         2,
         `${baseUrl}/v1/auth/tokens/anonymous`,
-        { method: "POST" },
+        { method: "POST", signal: expect.any(AbortSignal) },
       );
       expect(values.get(refreshTokenKey)).toBe(
         JSON.stringify(replacementRefreshToken),