assistant-cloud 0.1.40 → 0.1.41

package/src/AssistantCloudFiles.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudFiles } from "./AssistantCloudFiles";
+
+const createCloudFiles = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return { files: new AssistantCloudFiles(api), makeRequest };
+};
+
+describe("AssistantCloudFiles responses", () => {
+  it("decodes PDF conversion responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      urls: ["https://example.com/page-1.png"],
+      message: "converted",
+    });
+
+    await expect(
+      files.pdfToImages({ file_url: "https://example.com/file.pdf" }),
+    ).resolves.toEqual({
+      success: true,
+      urls: ["https://example.com/page-1.png"],
+      message: "converted",
+    });
+  });
+
+  it("rejects malformed PDF conversion responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      urls: [42],
+      message: "converted",
+    });
+
+    await expect(files.pdfToImages({ file_blob: "data" })).rejects.toThrow(
+      'Invalid Assistant Cloud response for "PDF conversion response.urls[0]": expected a string',
+    );
+  });
+
+  it("decodes presigned upload responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      success: true,
+      signedUrl: "https://uploads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      publicUrl: "https://cdn.example.com/file",
+    });
+
+    await expect(
+      files.generatePresignedUploadUrl({ filename: "notes.txt" }),
+    ).resolves.toEqual({
+      success: true,
+      signedUrl: "https://uploads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      publicUrl: "https://cdn.example.com/file",
+    });
+  });
+
+  it("rejects malformed presigned upload responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({});
+
+    await expect(
+      files.generatePresignedUploadUrl({ filename: "notes.txt" }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "presigned upload response.success": expected a boolean',
+    );
+  });
+});

package/src/AssistantCloudFiles.ts

@@ -1,4 +1,10 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  readCloudArray,
+  readCloudBoolean,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
 
 type PdfToImagesRequestBody = {
   file_blob?: string | undefined;
@@ -32,21 +38,61 @@ export class AssistantCloudFiles {
   public async pdfToImages(
     body: PdfToImagesRequestBody,
   ): Promise<PdfToImagesResponse> {
-    return this.cloud.makeRequest("/files/pdf-to-images", {
-      method: "POST",
-      body,
-    });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/files/pdf-to-images", {
+        method: "POST",
+        body,
+      }),
+      "PDF conversion response",
+    );
+
+    return {
+      success: readCloudBoolean(
+        response.success,
+        "PDF conversion response.success",
+      ),
+      urls: readCloudArray(response.urls, "PDF conversion response.urls").map(
+        (url, index) =>
+          readCloudString(url, `PDF conversion response.urls[${index}]`),
+      ),
+      message: readCloudString(
+        response.message,
+        "PDF conversion response.message",
+      ),
+    };
   }
 
   public async generatePresignedUploadUrl(
     body: GeneratePresignedUploadUrlRequestBody,
   ): Promise<GeneratePresignedUploadUrlResponse> {
-    return this.cloud.makeRequest(
-      "/files/attachments/generate-presigned-upload-url",
-      {
-        method: "POST",
-        body,
-      },
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        "/files/attachments/generate-presigned-upload-url",
+        {
+          method: "POST",
+          body,
+        },
+      ),
+      "presigned upload response",
     );
+
+    return {
+      success: readCloudBoolean(
+        response.success,
+        "presigned upload response.success",
+      ),
+      signedUrl: readCloudString(
+        response.signedUrl,
+        "presigned upload response.signedUrl",
+      ),
+      expiresAt: readCloudString(
+        response.expiresAt,
+        "presigned upload response.expiresAt",
+      ),
+      publicUrl: readCloudString(
+        response.publicUrl,
+        "presigned upload response.publicUrl",
+      ),
+    };
   }
 }

package/src/AssistantCloudRuns.ts

@@ -1,6 +1,11 @@
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import type { SamplingCallData } from "./instrumentMcpSampling";
 import { AssistantStream, PlainTextDecoder } from "assistant-stream";
+import {
+  CloudResponseError,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
 
 type AssistantCloudRunsStreamBody = {
   thread_id: string;
@@ -83,12 +88,40 @@ export class AssistantCloudRuns {
       },
       body,
     });
+
+    if (!response.body) {
+      throw new CloudResponseError(
+        'Invalid Assistant Cloud response for "run stream": expected a response body',
+      );
+    }
+
+    const receivedContentType = response.headers.get("content-type");
+    const contentType = receivedContentType
+      ?.split(";", 1)[0]
+      ?.trim()
+      .toLowerCase();
+    if (contentType !== "text/plain") {
+      await response.body.cancel().catch(() => undefined);
+      throw new CloudResponseError(
+        `Invalid Assistant Cloud response for "run stream": expected a "text/plain" content type, received ${
+          receivedContentType
+            ? `"${receivedContentType}"`
+            : "no Content-Type header"
+        }`,
+      );
+    }
+
     return AssistantStream.fromResponse(response, new PlainTextDecoder());
   }
 
   public async report(
     body: AssistantCloudRunReport,
   ): Promise<{ run_id: string }> {
-    return this.cloud.makeRequest("/runs", { method: "POST", body });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/runs", { method: "POST", body }),
+      "run report response",
+    );
+
+    return { run_id: readCloudString(response.run_id, "run_id") };
   }
 }

package/src/AssistantCloudThreadMessages.test.ts

@@ -12,6 +12,26 @@ const createCloudThreadMessages = () => {
 };
 
 describe("AssistantCloudThreadMessages responses", () => {
+  it("validates created message IDs", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    const body = {
+      parent_id: null,
+      format: "aui/v0",
+      content: {},
+    };
+    makeRequest.mockResolvedValueOnce({ message_id: "message-1" });
+
+    await expect(messages.create("thread-1", body)).resolves.toEqual({
+      message_id: "message-1",
+    });
+
+    makeRequest.mockResolvedValueOnce({});
+
+    await expect(messages.create("thread-1", body)).rejects.toThrow(
+      'Invalid Assistant Cloud response for "message_id": expected a string',
+    );
+  });
+
   it("decodes canonical message responses without changing content", async () => {
     const { messages, makeRequest } = createCloudThreadMessages();
     makeRequest.mockResolvedValue({

package/src/AssistantCloudThreadMessages.ts

@@ -89,10 +89,17 @@ export class AssistantCloudThreadMessages {
     threadId: string,
     body: AssistantCloudThreadMessageCreateBody,
   ): Promise<AssistantCloudMessageCreateResponse> {
-    return this.cloud.makeRequest(
-      `/threads/${encodeURIComponent(threadId)}/messages`,
-      { method: "POST", body },
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        `/threads/${encodeURIComponent(threadId)}/messages`,
+        { method: "POST", body },
+      ),
+      "thread message create response",
     );
+
+    return {
+      message_id: readCloudString(response.message_id, "message_id"),
+    };
   }
 
   public async update(

package/src/AssistantCloudThreads.test.ts

@@ -22,6 +22,23 @@ const threadResponse = {
 };
 
 describe("AssistantCloudThreads responses", () => {
+  it("validates created thread IDs", async () => {
+    const { threads, makeRequest } = createCloudThreads();
+    makeRequest.mockResolvedValueOnce({ thread_id: "thread-1" });
+
+    await expect(
+      threads.create({ last_message_at: new Date() }),
+    ).resolves.toEqual({ thread_id: "thread-1" });
+
+    makeRequest.mockResolvedValueOnce({});
+
+    await expect(
+      threads.create({ last_message_at: new Date() }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "thread_id": expected a string',
+    );
+  });
+
   it("forwards both archive filter values", async () => {
     const { threads, makeRequest } = createCloudThreads();
     makeRequest.mockResolvedValue({ threads: [] });

package/src/AssistantCloudThreads.ts

@@ -117,7 +117,12 @@ export class AssistantCloudThreads {
   public async create(
     body: AssistantCloudThreadsCreateBody,
   ): Promise<AssistantCloudThreadsCreateResponse> {
-    return this.cloud.makeRequest("/threads", { method: "POST", body });
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/threads", { method: "POST", body }),
+      "thread create response",
+    );
+
+    return { thread_id: readCloudString(response.thread_id, "thread_id") };
   }
 
   public async update(

package/src/tests/AssistantCloudAuthStrategy.test.ts

@@ -11,6 +11,7 @@ const refreshToken = {
   token: "r1",
   expires_at: "2099-01-01",
 };
+const refreshTokenKey = `aui:refresh_token:${baseUrl}`;
 
 let originalLocalStorageDescriptor: PropertyDescriptor | undefined;
 
@@ -79,9 +80,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     await expect(strategy.getAuthHeaders()).resolves.toEqual({
       Authorization: `Bearer ${accessToken}`,
     });
-    expect(values.get("aui:refresh_token")).toBe(
-      JSON.stringify(nextRefreshToken),
-    );
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(nextRefreshToken));
     expect(fetchMock).toHaveBeenCalledWith(
       `${baseUrl}/v1/auth/tokens/anonymous`,
       { method: "POST" },
@@ -107,6 +106,183 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     expect(fetchMock).toHaveBeenCalledTimes(1);
   });
 
+  it("scopes anonymous refresh tokens by backend", async () => {
+    const secondBaseUrl = "https://other.example.com";
+    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 secondRefreshToken = {
+      token: "r2",
+      expires_at: "2099-01-01",
+    };
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: refreshToken,
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: secondRefreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders();
+    await new AssistantCloudAnonymousAuthStrategy(
+      secondBaseUrl,
+    ).getAuthHeaders();
+
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      `${baseUrl}/v1/auth/tokens/anonymous`,
+      { method: "POST" },
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      `${secondBaseUrl}/v1/auth/tokens/anonymous`,
+      { method: "POST" },
+    );
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+    expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
+      JSON.stringify(secondRefreshToken),
+    );
+  });
+
+  it("migrates the legacy refresh token to the first backend", async () => {
+    const secondBaseUrl = "https://other.example.com";
+    const secondRefreshToken = {
+      token: "r2",
+      expires_at: "2099-01-01",
+    };
+    const values = new Map([
+      ["aui:refresh_token", JSON.stringify(refreshToken)],
+    ]);
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({ access_token: accessToken }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: secondRefreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders();
+    await new AssistantCloudAnonymousAuthStrategy(
+      secondBaseUrl,
+    ).getAuthHeaders();
+
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      `${baseUrl}/v1/auth/tokens/refresh`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: refreshToken.token }),
+      },
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      `${secondBaseUrl}/v1/auth/tokens/anonymous`,
+      { method: "POST" },
+    );
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+    expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
+      JSON.stringify(secondRefreshToken),
+    );
+    expect(values.has("aui:refresh_token")).toBe(false);
+  });
+
+  it("retires the legacy refresh token when a scoped token exists", async () => {
+    const secondBaseUrl = "https://other.example.com";
+    const scopedRefreshToken = {
+      token: "scoped-r1",
+      expires_at: "2099-01-01",
+    };
+    const secondRefreshToken = {
+      token: "r2",
+      expires_at: "2099-01-01",
+    };
+    const values = new Map([
+      ["aui:refresh_token", JSON.stringify(refreshToken)],
+      [refreshTokenKey, JSON.stringify(scopedRefreshToken)],
+    ]);
+    installLocalStorage({
+      getItem: (key) => values.get(key) ?? null,
+      setItem: (key, value) => {
+        values.set(key, value);
+      },
+      removeItem: (key) => {
+        values.delete(key);
+      },
+    } as Storage);
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({ access_token: accessToken }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: vi.fn().mockResolvedValue({
+          access_token: accessToken,
+          refresh_token: secondRefreshToken,
+        }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await new AssistantCloudAnonymousAuthStrategy(baseUrl).getAuthHeaders();
+    await new AssistantCloudAnonymousAuthStrategy(
+      secondBaseUrl,
+    ).getAuthHeaders();
+
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      `${baseUrl}/v1/auth/tokens/refresh`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: scopedRefreshToken.token }),
+      },
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      `${secondBaseUrl}/v1/auth/tokens/anonymous`,
+      { method: "POST" },
+    );
+    expect(values.has("aui:refresh_token")).toBe(false);
+    expect(values.get(`aui:refresh_token:${secondBaseUrl}`)).toBe(
+      JSON.stringify(secondRefreshToken),
+    );
+  });
+
   it("returns an anonymous access token without localStorage", async () => {
     delete (globalThis as { localStorage?: Storage }).localStorage;
     mockAnonymousTokenFetch();
@@ -160,7 +336,7 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     ).resolves.toEqual({ Authorization: `Bearer ${accessToken}` });
     expect(getItem).toHaveBeenCalledTimes(2);
     expect(setItem).toHaveBeenCalledTimes(2);
-    expect(removeItem).toHaveBeenCalledTimes(1);
+    expect(removeItem).toHaveBeenCalledTimes(2);
   });
 
   it("treats corrupted refresh token JSON as absent", async () => {
@@ -181,7 +357,8 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     await expect(strategy.getAuthHeaders()).resolves.toEqual({
       Authorization: `Bearer ${accessToken}`,
     });
-    expect(values.get("aui:refresh_token")).toBe(JSON.stringify(refreshToken));
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+    expect(values.has("aui:refresh_token")).toBe(false);
   });
 
   it("rejects malformed anonymous token responses without persisting them", async () => {
@@ -298,6 +475,102 @@ describe("AssistantCloudAnonymousAuthStrategy", () => {
     expect(setItem).not.toHaveBeenCalled();
   });
 
+  it.each([429, 500, 503])(
+    "preserves the anonymous identity after transient status %i",
+    async (status) => {
+      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);
+      const fetchMock = vi.fn().mockResolvedValue({ ok: false, status });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const strategy = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+      await expect(strategy.getAuthHeaders()).rejects.toThrow(
+        `Assistant Cloud token refresh failed with status ${status}`,
+      );
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+    },
+  );
+
+  it.each([401, 403])(
+    "replaces an anonymous identity after refresh is rejected with %i",
+    async (status) => {
+      const replacementRefreshToken = {
+        token: "r2",
+        expires_at: "2099-02-01",
+      };
+      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);
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce({ ok: false, status })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: vi.fn().mockResolvedValue({
+            access_token: accessToken,
+            refresh_token: replacementRefreshToken,
+          }),
+        });
+      vi.stubGlobal("fetch", fetchMock);
+
+      const strategy = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+      await expect(strategy.getAuthHeaders()).resolves.toEqual({
+        Authorization: `Bearer ${accessToken}`,
+      });
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        2,
+        `${baseUrl}/v1/auth/tokens/anonymous`,
+        { method: "POST" },
+      );
+      expect(values.get(refreshTokenKey)).toBe(
+        JSON.stringify(replacementRefreshToken),
+      );
+    },
+  );
+
+  it("preserves a rejected refresh token until its replacement succeeds", async () => {
+    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);
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValueOnce({ ok: false, status: 403 })
+        .mockResolvedValueOnce({ ok: false, status: 503 }),
+    );
+
+    const strategy = new AssistantCloudAnonymousAuthStrategy(baseUrl);
+
+    await expect(strategy.getAuthHeaders()).resolves.toBe(false);
+    expect(values.get(refreshTokenKey)).toBe(JSON.stringify(refreshToken));
+  });
+
   it("contextualizes invalid JSON token responses", async () => {
     delete (globalThis as { localStorage?: Storage }).localStorage;
     vi.stubGlobal(