assistant-cloud 0.1.35 → 0.1.36

package/src/AssistantCloudThreads.ts

@@ -1,5 +1,13 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import {
+  readCloudArray,
+  readCloudBoolean,
+  readCloudNullableString,
+  readCloudRecord,
+  readCloudString,
+  readCloudTimestamp,
+} from "./cloudResponse";
 
 type AssistantCloudThreadsListQuery = {
   is_archived?: boolean;
@@ -7,7 +15,7 @@ type AssistantCloudThreadsListQuery = {
   after?: string;
 };
 
-type CloudThread = {
+export type CloudThread = {
   title: string;
   last_message_at: Date;
   metadata: unknown;
@@ -42,6 +50,31 @@ type AssistantCloudThreadsUpdateBody = {
   is_archived?: boolean | undefined;
 };
 
+export const decodeCloudThread = (
+  value: unknown,
+  field: string,
+): CloudThread => {
+  const thread = readCloudRecord(value, field);
+  return {
+    title: readCloudNullableString(thread.title, `${field}.title`) ?? "",
+    last_message_at: readCloudTimestamp(
+      thread.last_message_at,
+      `${field}.last_message_at`,
+    ),
+    metadata: thread.metadata,
+    external_id: readCloudNullableString(
+      thread.external_id,
+      `${field}.external_id`,
+    ),
+    id: readCloudString(thread.id, `${field}.id`),
+    project_id: readCloudString(thread.project_id, `${field}.project_id`),
+    created_at: readCloudTimestamp(thread.created_at, `${field}.created_at`),
+    updated_at: readCloudTimestamp(thread.updated_at, `${field}.updated_at`),
+    workspace_id: readCloudString(thread.workspace_id, `${field}.workspace_id`),
+    is_archived: readCloudBoolean(thread.is_archived, `${field}.is_archived`),
+  };
+};
+
 export class AssistantCloudThreads {
   public readonly messages: AssistantCloudThreadMessages;
 
@@ -52,11 +85,26 @@ export class AssistantCloudThreads {
   public async list(
     query?: AssistantCloudThreadsListQuery,
   ): Promise<AssistantCloudThreadsListResponse> {
-    return this.cloud.makeRequest("/threads", { query });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/threads", { query }),
+      "thread list response",
+    );
+    const threads = readCloudArray(response.threads, "threads");
+
+    return {
+      threads: threads.map((thread, index) =>
+        decodeCloudThread(thread, `threads[${index}]`),
+      ),
+    };
   }
 
   public async get(threadId: string): Promise<CloudThread> {
-    return this.cloud.makeRequest(`/threads/${encodeURIComponent(threadId)}`);
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(`/threads/${encodeURIComponent(threadId)}`),
+      "thread response",
+    );
+
+    return decodeCloudThread(response.thread, "thread");
   }
 
   public async create(

package/src/CloudMessagePersistence.ts

@@ -14,8 +14,13 @@ import type { AssistantCloud } from "./AssistantCloud";
  */
 export class CloudMessagePersistence {
   private idMapping: Record<string, string | Promise<string>> = {};
+  private getCloud: () => AssistantCloud;
 
-  constructor(private cloud: AssistantCloud) {}
+  constructor(cloud: AssistantCloud);
+  constructor(getCloud: () => AssistantCloud);
+  constructor(cloud: AssistantCloud | (() => AssistantCloud)) {
+    this.getCloud = typeof cloud === "function" ? cloud : () => cloud;
+  }
 
   /**
    * Persist a message to the cloud.
@@ -33,12 +38,13 @@ export class CloudMessagePersistence {
     format: string,
     content: ReadonlyJSONObject,
   ): Promise<void> {
+    const cloud = this.getCloud();
     // Resolve parent's remote ID if it exists (may be a promise if concurrent)
     const resolvedParentId = parentId
       ? ((await this.idMapping[parentId]) ?? parentId)
       : null;
 
-    const task = this.cloud.threads.messages
+    const task = cloud.threads.messages
       .create(threadId, {
         parent_id: resolvedParentId,
         format,
@@ -70,9 +76,15 @@ export class CloudMessagePersistence {
     _format: string,
     content: ReadonlyJSONObject,
   ): Promise<void> {
+    const cloud = this.getCloud();
     const remoteId = await this.getRemoteId(messageId);
-    if (!remoteId) return; // not persisted yet, skip
-    await this.cloud.threads.messages.update(threadId, remoteId, { content });
+    if (!remoteId) {
+      console.warn(
+        `Skipping update for message ${messageId}: no remote id is mapped.`,
+      );
+      return;
+    }
+    await cloud.threads.messages.update(threadId, remoteId, { content });
   }
 
   /**
@@ -103,7 +115,8 @@ export class CloudMessagePersistence {
    * @returns Array of cloud messages
    */
   async load(threadId: string, format?: string) {
-    const { messages } = await this.cloud.threads.messages.list(
+    const cloud = this.getCloud();
+    const { messages } = await cloud.threads.messages.list(
       threadId,
       format ? { format } : undefined,
     );

package/src/cloudResponse.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { CloudResponseError, readCloudTimestamp } from "./cloudResponse";
+
+describe("readCloudTimestamp", () => {
+  it("decodes a canonical Cloud timestamp", () => {
+    expect(
+      readCloudTimestamp(
+        "2026-07-16T12:15:00.123Z",
+        "thread.updated_at",
+      ).toISOString(),
+    ).toBe("2026-07-16T12:15:00.123Z");
+  });
+
+  it.each([
+    "2026-02-30T12:15:00.000Z",
+    "2026-13-01T12:15:00Z",
+    "2026-07-16 12:15:00.123456",
+    "2026-07-16T12:15:00.123+00:00",
+    new Date("2026-07-16T12:15:00.123Z"),
+    "not-a-timestamp",
+  ])("rejects invalid timestamp %s", (value) => {
+    const decode = () => readCloudTimestamp(value, "thread.updated_at");
+    expect(decode).toThrow(CloudResponseError);
+    expect(decode).toThrow(
+      'Invalid Assistant Cloud response for "thread.updated_at": expected a canonical ISO timestamp',
+    );
+  });
+});

package/src/cloudResponse.ts

@@ -0,0 +1,72 @@
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+export class CloudResponseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CloudResponseError";
+  }
+}
+
+const invalidCloudResponse = (field: string, expected: string) =>
+  new CloudResponseError(
+    `Invalid Assistant Cloud response for "${field}": expected ${expected}`,
+  );
+
+export const readCloudRecord = (
+  value: unknown,
+  field: string,
+): Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalidCloudResponse(field, "an object");
+  }
+  return value as Record<string, unknown>;
+};
+
+export const readCloudArray = (value: unknown, field: string): unknown[] => {
+  if (!Array.isArray(value)) throw invalidCloudResponse(field, "an array");
+  return value;
+};
+
+export const readCloudString = (value: unknown, field: string): string => {
+  if (typeof value !== "string") throw invalidCloudResponse(field, "a string");
+  return value;
+};
+
+export const readCloudNullableString = (
+  value: unknown,
+  field: string,
+): string | null => {
+  if (value === null) return null;
+  return readCloudString(value, field);
+};
+
+export const readCloudBoolean = (value: unknown, field: string): boolean => {
+  if (typeof value !== "boolean") {
+    throw invalidCloudResponse(field, "a boolean");
+  }
+  return value;
+};
+
+export const readCloudInteger = (value: unknown, field: string): number => {
+  if (!Number.isInteger(value)) throw invalidCloudResponse(field, "an integer");
+  return value as number;
+};
+
+export const readCloudTimestamp = (value: unknown, field: string): Date => {
+  if (typeof value !== "string") {
+    throw invalidCloudResponse(field, "a canonical ISO timestamp");
+  }
+
+  const date = new Date(value);
+  // The round trip pins the backend DTO's Date#toISOString() wire contract.
+  if (Number.isNaN(date.getTime()) || date.toISOString() !== value) {
+    throw invalidCloudResponse(field, "a canonical ISO timestamp");
+  }
+
+  return date;
+};
+
+export const readCloudJSONObject = (
+  value: unknown,
+  field: string,
+): ReadonlyJSONObject => readCloudRecord(value, field) as ReadonlyJSONObject;

package/src/index.ts

@@ -1,6 +1,7 @@
 export type { CloudMessage } from "./AssistantCloudThreadMessages";
 export type { AssistantCloudTelemetryConfig } from "./AssistantCloudAPI";
 export { CloudAPIError } from "./AssistantCloudAPI";
+export { CloudResponseError } from "./cloudResponse";
 export type { AssistantCloudRunReport } from "./AssistantCloudRuns";
 export { AssistantCloud } from "./AssistantCloud";
 export { CloudMessagePersistence } from "./CloudMessagePersistence";

package/src/tests/AssistantCloudAPI.test.ts

@@ -1,11 +1,22 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { AssistantCloudAPI, CloudAPIError } from "../AssistantCloudAPI";
 
+const createJwt = () => {
+  const payload = Buffer.from(JSON.stringify({ exp: 4_102_444_800 })).toString(
+    "base64url",
+  );
+  return `header.${payload}.signature`;
+};
+
 describe("AssistantCloudAPI", () => {
   beforeEach(() => {
     vi.restoreAllMocks();
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
   it("serializes query params, merges auth headers, and sends JSON body", async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
@@ -90,6 +101,65 @@ describe("AssistantCloudAPI", () => {
     expect(url.toString()).toBe("https://custom.example.com/v1/threads");
   });
 
+  it("strips a trailing slash from a JWT baseUrl", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      headers: new Headers(),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new AssistantCloudAPI({
+      baseUrl: "https://custom.example.com/",
+      authToken: async () => createJwt(),
+    });
+
+    await api.makeRawRequest("/threads");
+
+    const [url] = fetchMock.mock.calls[0]!;
+    expect(url.toString()).toBe("https://custom.example.com/v1/threads");
+  });
+
+  it("strips a trailing slash from anonymous auth URLs", async () => {
+    const storage = {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    };
+    vi.stubGlobal("localStorage", storage);
+
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: createJwt(),
+          refresh_token: {
+            token: "refresh-token",
+            expires_at: "2100-01-01T00:00:00.000Z",
+          },
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        headers: new Headers(),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const api = new AssistantCloudAPI({
+      baseUrl: "https://custom.example.com/",
+      anonymous: true,
+    });
+
+    await api.makeRawRequest("/threads");
+
+    expect(fetchMock.mock.calls[0]![0]).toBe(
+      "https://custom.example.com/v1/auth/tokens/anonymous",
+    );
+    expect(fetchMock.mock.calls[1]![0].toString()).toBe(
+      "https://custom.example.com/v1/threads",
+    );
+  });
+
   it("rejects before fetch when auth token callback returns null", async () => {
     const fetchMock = vi.fn();
     vi.stubGlobal("fetch", fetchMock);

package/src/tests/AssistantCloudAuthStrategy.test.ts

@@ -1,5 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { AssistantCloudAnonymousAuthStrategy } from "../AssistantCloudAuthStrategy";
+import {
+  AssistantCloudAnonymousAuthStrategy,
+  AssistantCloudJWTAuthStrategy,
+} from "../AssistantCloudAuthStrategy";
 
 const baseUrl = "https://test.example.com";
 const accessToken = `${Buffer.from(JSON.stringify({ alg: "none" })).toString("base64url")}.${Buffer.from(JSON.stringify({ exp: 4102444800 })).toString("base64url")}.sig`;
@@ -72,6 +75,25 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     );
   });
 
+  it("deduplicates concurrent anonymous token requests", async () => {
+    delete (globalThis as { localStorage?: Storage }).localStorage;
+    const fetchMock = mockAnonymousTokenFetch();
+    const strategy = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    await expect(
+      Promise.all([
+        strategy.getAuthHeaders(),
+        strategy.getAuthHeaders(),
+        strategy.getAuthHeaders(),
+      ]),
+    ).resolves.toEqual([
+      { Authorization: `Bearer ${accessToken}` },
+      { Authorization: `Bearer ${accessToken}` },
+      { Authorization: `Bearer ${accessToken}` },
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
   it("returns an anonymous access token without localStorage", async () => {
     delete (globalThis as { localStorage?: Storage }).localStorage;
     mockAnonymousTokenFetch();
@@ -102,7 +124,9 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
   it("returns an anonymous access token when storage methods throw", async () => {
     const getItem = vi
       .fn<(key: string) => string | null>()
-      .mockReturnValueOnce(JSON.stringify(refreshToken))
+      .mockReturnValueOnce(
+        JSON.stringify({ token: "expired", expires_at: "2022-01-01" }),
+      )
       .mockImplementation(() => {
         throw new DOMException("blocked", "SecurityError");
       });
@@ -115,26 +139,12 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     installLocalStorage({ getItem, setItem, removeItem } as Storage);
     mockAnonymousTokenFetch();
 
-    const originalDate = globalThis.Date;
-    const fixedDate = (originalDate as unknown as () => Date)();
-    const fixedTime = originalDate.now();
-    globalThis.Date = Object.assign(
-      function Date() {
-        return fixedDate;
-      },
-      { now: () => fixedTime },
-    ) as unknown as DateConstructor;
-
-    try {
-      await expect(
-        new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
-      ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
-      await expect(
-        new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
-      ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
-    } finally {
-      globalThis.Date = originalDate;
-    }
+    await expect(
+      new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
+    ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
+    await expect(
+      new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders(),
+    ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
     expect(getItem).toHaveBeenCalledTimes(2);
     expect(setItem).toHaveBeenCalledTimes(2);
     expect(removeItem).toHaveBeenCalledTimes(1);
@@ -161,3 +171,21 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     expect(values.get("aui:refresh_token")).toBe(JSON.stringify(refreshToken));
   });
 });
+
+describe("AssistantCloudJWTAuthStrategy", () => {
+  it("retries token acquisition after a failed request", async () => {
+    const authToken = vi
+      .fn<() => Promise<string | null>>()
+      .mockRejectedValueOnce(new Error("authentication unavailable"))
+      .mockResolvedValueOnce(accessToken);
+    const strategy = new AssistantCloudJWTAuthStrategy(authToken);
+
+    await expect(strategy.getAuthHeaders()).rejects.toThrow(
+      "authentication unavailable",
+    );
+    await expect(strategy.getAuthHeaders()).resolves.toEqual({
+      Authorization: `Bearer ${accessToken}`,
+    });
+    expect(authToken).toHaveBeenCalledTimes(2);
+  });
+});

package/src/tests/AssistantCloudProjects.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AssistantCloudProjects } from "../AssistantCloudProjects";
+import type { AssistantCloudAPI } from "../AssistantCloudAPI";
+
+vi.mock("../AssistantCloudAPI");
+
+describe("AssistantCloudProjects", () => {
+  let projects: AssistantCloudProjects;
+  let mockApi: AssistantCloudAPI;
+
+  beforeEach(() => {
+    mockApi = {
+      makeRequest: vi.fn().mockResolvedValue({}),
+      makeRawRequest: vi.fn(),
+      _auth: { getAuthHeaders: vi.fn() },
+      _baseUrl: "https://backend.assistant-api.com",
+    } as unknown as AssistantCloudAPI;
+
+    projects = new AssistantCloudProjects(mockApi);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("lists project threads with the query", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({ threads: [] });
+
+    await projects.threads.list({ limit: 10, after: "t1" });
+
+    expect(mockApi.makeRequest).toHaveBeenCalledWith("/projects/threads", {
+      query: { limit: 10, after: "t1" },
+    });
+  });
+
+  it("sends both archive filter values as strings", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({ threads: [] });
+
+    await projects.threads.list({ is_archived: false });
+    expect(mockApi.makeRequest).toHaveBeenLastCalledWith("/projects/threads", {
+      query: { is_archived: "false" },
+    });
+
+    await projects.threads.list({ is_archived: true });
+    expect(mockApi.makeRequest).toHaveBeenLastCalledWith("/projects/threads", {
+      query: { is_archived: "true" },
+    });
+  });
+
+  it("lists project thread messages with the query", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({ messages: [] });
+
+    await projects.threads.messages.list("thread_123", {
+      format: "ai-sdk/v5",
+      limit: 100,
+      after: "msg_9",
+    });
+
+    expect(mockApi.makeRequest).toHaveBeenCalledWith(
+      "/projects/threads/thread_123/messages",
+      { query: { format: "ai-sdk/v5", limit: 100, after: "msg_9" } },
+    );
+  });
+
+  it("url-encodes the thread id in the messages path", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({ messages: [] });
+
+    await projects.threads.messages.list("thread/with space");
+
+    expect(mockApi.makeRequest).toHaveBeenCalledWith(
+      "/projects/threads/thread%2Fwith%20space/messages",
+      { query: undefined },
+    );
+  });
+
+  it("decodes project thread list responses", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({
+      threads: [
+        {
+          title: "Project thread",
+          last_message_at: "2026-07-16T12:30:00.000Z",
+          metadata: {},
+          external_id: null,
+          id: "thread_1",
+          project_id: "project_1",
+          created_at: "2026-07-16T12:00:00.000Z",
+          updated_at: "2026-07-16T12:15:00.000Z",
+          workspace_id: "workspace_1",
+          is_archived: false,
+        },
+      ],
+    });
+
+    const result = await projects.threads.list();
+    const thread = result.threads[0]!;
+
+    expect(thread.last_message_at instanceof Date).toBe(true);
+    expect(thread.is_archived).toBeTypeOf("boolean");
+  });
+
+  it("decodes project thread message list responses", async () => {
+    vi.mocked(mockApi.makeRequest).mockResolvedValue({
+      messages: [
+        {
+          id: "message_1",
+          parent_id: null,
+          height: 0,
+          created_at: "2026-07-16T13:00:00.000Z",
+          updated_at: "2026-07-16T13:05:00.000Z",
+          format: "aui/v0",
+          content: {},
+        },
+      ],
+    });
+
+    const result = await projects.threads.messages.list("thread_1");
+    const message = result.messages[0]!;
+
+    expect(message.created_at instanceof Date).toBe(true);
+  });
+});

package/src/tests/CloudMessagePersistence.test.ts

@@ -37,6 +37,33 @@ describe("CloudMessagePersistence", () => {
     expect(await persistence.getRemoteId("local-1")).toBe("remote-1");
   });
 
+  it("uses the current client without losing ID mappings", async () => {
+    const firstCloud = createMockCloud();
+    const secondCloud = createMockCloud();
+    let currentCloud = firstCloud;
+    persistence = new CloudMessagePersistence(() => currentCloud);
+    vi.mocked(firstCloud.threads.messages.create).mockResolvedValue({
+      message_id: "remote-parent",
+    });
+    vi.mocked(secondCloud.threads.messages.create).mockResolvedValue({
+      message_id: "remote-child",
+    });
+
+    await persistence.append("thread-1", "parent", null, "aui/v0", {
+      text: "parent",
+    });
+    currentCloud = secondCloud;
+    await persistence.append("thread-1", "child", "parent", "aui/v0", {
+      text: "child",
+    });
+
+    expect(secondCloud.threads.messages.create).toHaveBeenCalledWith(
+      "thread-1",
+      expect.objectContaining({ parent_id: "remote-parent" }),
+    );
+    expect(await persistence.getRemoteId("child")).toBe("remote-child");
+  });
+
   it("resolves parent ID from a concurrent append", async () => {
     // Parent creation is delayed — the promise won't resolve immediately
     let resolveParent!: (v: { message_id: string }) => void;
@@ -121,6 +148,19 @@ describe("CloudMessagePersistence", () => {
     );
   });
 
+  it("warns and skips update when no remote id is mapped", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    await persistence.update("thread-1", "unmapped-1", "aui/v0", {
+      text: "x",
+    });
+
+    expect(cloud.threads.messages.update).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(
+      "Skipping update for message unmapped-1: no remote id is mapped.",
+    );
+  });
+
   it("cleans up ID mapping on append failure", async () => {
     vi.mocked(cloud.threads.messages.create).mockRejectedValue(
       new Error("network error"),

package/src/tests/setup.ts

@@ -1,11 +1,4 @@
-// This file contains setup code for tests
 import { vi } from "vitest";
 
-// Set up globalThis mocks if needed
-// Using a fixed date to avoid recursive calls
-const OriginalDate = globalThis.Date;
-const fixedDate = new OriginalDate("2023-01-01");
-globalThis.Date = vi.fn(() => fixedDate) as any;
-globalThis.Date.now = vi.fn(() => fixedDate.getTime());
-
-// Add any other globalThis setup needed for tests
+vi.useFakeTimers({ toFake: ["Date"] });
+vi.setSystemTime(new Date("2023-01-01T00:00:00.000Z"));