assistant-cloud 0.1.42 → 0.2.0

package/src/AssistantCloudEvents.test.ts

@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AssistantCloudEvents,
+  type AssistantCloudEvent,
+} from "./AssistantCloudEvents";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+
+const event = (index: number): AssistantCloudEvent => ({
+  kind: "message_sent",
+  thread_id: `thread-${index}`,
+});
+
+const createEvents = (enabled = true) => {
+  const makeRequest = vi.fn().mockResolvedValue({ accepted: 1 });
+  const events = new AssistantCloudEvents(
+    { makeRequest } as unknown as AssistantCloudAPI,
+    () => enabled,
+  );
+  return { events, makeRequest };
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+  Object.defineProperty(document, "visibilityState", {
+    configurable: true,
+    value: "visible",
+  });
+});
+
+describe("AssistantCloudEvents", () => {
+  it("flushes twenty events in one keepalive request", async () => {
+    const { events, makeRequest } = createEvents();
+
+    for (let index = 0; index < 20; index++) events.track(event(index));
+
+    await vi.waitFor(() => expect(makeRequest).toHaveBeenCalledOnce());
+    expect(makeRequest).toHaveBeenCalledWith("/events", {
+      method: "POST",
+      body: { events: Array.from({ length: 20 }, (_, index) => event(index)) },
+      keepalive: true,
+    });
+  });
+
+  it("keeps its page listeners only while events are buffered", async () => {
+    const add = vi.spyOn(window, "addEventListener");
+    const remove = vi.spyOn(window, "removeEventListener");
+    const { events, makeRequest } = createEvents();
+
+    for (let index = 0; index < 20; index++) events.track(event(index));
+    expect(add).toHaveBeenCalledWith("pagehide", expect.any(Function));
+
+    await vi.waitFor(() => expect(makeRequest).toHaveBeenCalledOnce());
+    await vi.waitFor(() =>
+      expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function)),
+    );
+  });
+
+  it("dispose removes the listeners and flushes what is buffered", async () => {
+    const remove = vi.spyOn(document, "removeEventListener");
+    const { events, makeRequest } = createEvents();
+
+    events.track(event(1));
+    events.dispose();
+
+    expect(remove).toHaveBeenCalledWith(
+      "visibilitychange",
+      expect.any(Function),
+    );
+    await vi.waitFor(() => expect(makeRequest).toHaveBeenCalledOnce());
+  });
+
+  it("flushes buffered events after two seconds", async () => {
+    vi.useFakeTimers();
+    const { events, makeRequest } = createEvents();
+
+    events.track(event(1));
+    await vi.advanceTimersByTimeAsync(1_999);
+    expect(makeRequest).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    expect(makeRequest).toHaveBeenCalledOnce();
+  });
+
+  it("flushes when the document becomes hidden", async () => {
+    const { events, makeRequest } = createEvents();
+    events.track(event(1));
+
+    Object.defineProperty(document, "visibilityState", {
+      configurable: true,
+      value: "hidden",
+    });
+    document.dispatchEvent(new Event("visibilitychange"));
+
+    await vi.waitFor(() => expect(makeRequest).toHaveBeenCalledOnce());
+  });
+
+  it("does not send events when telemetry is disabled", async () => {
+    vi.useFakeTimers();
+    const { events, makeRequest } = createEvents(false);
+    events.track(event(1));
+
+    await vi.advanceTimersByTimeAsync(2_000);
+    expect(makeRequest).not.toHaveBeenCalled();
+  });
+
+  it("keeps every request below the server batch limit", async () => {
+    const { events, makeRequest } = createEvents();
+
+    for (let index = 0; index < 51; index++) events.track(event(index));
+
+    const sent = () =>
+      makeRequest.mock.calls.reduce(
+        (count, [, options]) => count + options.body.events.length,
+        0,
+      );
+    await vi.waitFor(() => expect(sent()).toBe(51));
+    for (const [, options] of makeRequest.mock.calls) {
+      expect(options.body.events.length).toBeLessThanOrEqual(50);
+    }
+  });
+});

package/src/AssistantCloudEvents.ts

@@ -0,0 +1,185 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+
+export type AssistantCloudEventKind =
+  | "message_sent"
+  | "message_edited"
+  | "run_stopped"
+  | "message_regenerated"
+  | "message_copied"
+  | "branch_switched"
+  | "suggestions_shown"
+  | "suggestion_clicked"
+  | "attachment_added"
+  | "attachment_failed"
+  | "thread_switched"
+  | "tool_approved"
+  | "tool_rejected"
+  | "speech_started"
+  | "voice_started"
+  | "error_shown";
+
+export type AssistantCloudEvent = {
+  kind: AssistantCloudEventKind;
+  thread_id?: string | undefined;
+  message_id?: string | undefined;
+  run_id?: string | undefined;
+  value?: number | undefined;
+  props?: Readonly<Record<string, string | number | boolean>> | undefined;
+};
+
+const FLUSH_SIZE = 20;
+const MAX_BATCH_SIZE = 50;
+const FLUSH_DELAY_MS = 2_000;
+
+export class AssistantCloudEvents {
+  private buffer: AssistantCloudEvent[] = [];
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private flushing: Promise<void> | undefined;
+
+  private readonly cloud: AssistantCloudAPI;
+  private readonly isEnabled: () => boolean;
+
+  private listening = false;
+
+  constructor(cloud: AssistantCloudAPI, isEnabled: () => boolean) {
+    this.cloud = cloud;
+    this.isEnabled = isEnabled;
+  }
+
+  public track(event: AssistantCloudEvent): void {
+    if (!this.isEnabled()) return;
+
+    this.listen();
+    this.buffer.push(normalizeEvent(event));
+    if (this.buffer.length >= FLUSH_SIZE) {
+      void this.flush();
+      return;
+    }
+
+    this.scheduleFlush();
+  }
+
+  private listen(): void {
+    if (
+      this.listening ||
+      typeof window === "undefined" ||
+      typeof document === "undefined"
+    ) {
+      return;
+    }
+    this.listening = true;
+    window.addEventListener("pagehide", this.flush);
+    document.addEventListener("visibilitychange", this.onVisibilityChange);
+  }
+
+  private unlisten(): void {
+    if (!this.listening) return;
+    this.listening = false;
+    window.removeEventListener("pagehide", this.flush);
+    document.removeEventListener("visibilitychange", this.onVisibilityChange);
+  }
+
+  public dispose(): void {
+    this.unlisten();
+    this.clearFlushTimer();
+    void this.flush();
+  }
+
+  private onVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      void this.flush();
+    }
+  };
+
+  private flush = async (): Promise<void> => {
+    if (!this.isEnabled()) {
+      this.buffer = [];
+      this.clearFlushTimer();
+      this.unlisten();
+      return;
+    }
+    if (this.flushing) return this.flushing;
+
+    this.clearFlushTimer();
+    const task = this.flushPending();
+    this.flushing = task;
+    void task.then(() => {
+      if (this.flushing !== task) return;
+      this.flushing = undefined;
+      if (this.buffer.length === 0) {
+        this.clearFlushTimer();
+        this.unlisten();
+      } else {
+        void this.flush();
+      }
+    });
+    return task;
+  };
+
+  private async flushPending(): Promise<void> {
+    while (this.buffer.length > 0) {
+      const events = this.buffer.splice(0, MAX_BATCH_SIZE);
+      try {
+        await this.cloud.makeRequest("/events", {
+          method: "POST",
+          body: { events },
+          keepalive: true,
+        });
+      } catch {}
+    }
+  }
+
+  private scheduleFlush() {
+    if (this.timer !== undefined) return;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      void this.flush();
+    }, FLUSH_DELAY_MS);
+  }
+
+  private clearFlushTimer() {
+    if (this.timer === undefined) return;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+}
+
+const normalizeEvent = (event: AssistantCloudEvent): AssistantCloudEvent => {
+  const props = normalizeProps(event.props);
+  return {
+    kind: event.kind,
+    ...(normalizeId(event.thread_id) ? { thread_id: event.thread_id } : {}),
+    ...(normalizeId(event.message_id) ? { message_id: event.message_id } : {}),
+    ...(normalizeId(event.run_id) ? { run_id: event.run_id } : {}),
+    ...(isNonNegativeInteger(event.value) ? { value: event.value } : {}),
+    ...(props ? { props } : {}),
+  };
+};
+
+const normalizeId = (value: string | undefined): string | undefined =>
+  value && value.length <= 48 ? value : undefined;
+
+const isNonNegativeInteger = (value: number | undefined): value is number =>
+  value !== undefined && Number.isInteger(value) && value >= 0;
+
+const normalizeProps = (
+  props: AssistantCloudEvent["props"],
+): AssistantCloudEvent["props"] => {
+  if (!props) return undefined;
+  const entries = Object.entries(props);
+  if (
+    entries.some(
+      ([, value]) =>
+        (typeof value === "string" && value.length > 256) ||
+        (typeof value !== "string" &&
+          typeof value !== "number" &&
+          typeof value !== "boolean"),
+    )
+  ) {
+    return undefined;
+  }
+  const value = Object.fromEntries(entries);
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength <= 1024
+    ? value
+    : undefined;
+};

package/src/AssistantCloudFiles.test.ts

@@ -40,6 +40,27 @@ describe("AssistantCloudFiles responses", () => {
   });
 
   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",
+      key: "attachments/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",
+      key: "attachments/file",
+    });
+  });
+
+  it("accepts presigned upload responses from older clouds without a key", async () => {
     const { files, makeRequest } = createCloudFiles();
     makeRequest.mockResolvedValue({
       success: true,
@@ -68,4 +89,42 @@ describe("AssistantCloudFiles responses", () => {
       'Invalid Assistant Cloud response for "presigned upload response.success": expected a boolean',
     );
   });
+
+  it("decodes presigned download responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      signedUrl: "https://downloads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      key: "attachments/file",
+    });
+
+    await expect(
+      files.generatePresignedDownloadUrl({ key: "attachments/file" }),
+    ).resolves.toEqual({
+      signedUrl: "https://downloads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      key: "attachments/file",
+    });
+    expect(makeRequest).toHaveBeenCalledWith(
+      "/files/attachments/generate-presigned-download-url",
+      { method: "POST", body: { key: "attachments/file" } },
+    );
+  });
+
+  it("rejects malformed presigned download responses", async () => {
+    const { files, makeRequest } = createCloudFiles();
+    makeRequest.mockResolvedValue({
+      signedUrl: "https://downloads.example.com/file",
+      expiresAt: "2026-08-16T12:00:00.000Z",
+      key: 42,
+    });
+
+    await expect(
+      files.generatePresignedDownloadUrl({
+        url: "https://cdn.example.com/file",
+      }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "presigned download response.key": expected a string',
+    );
+  });
 });

package/src/AssistantCloudFiles.ts

@@ -26,6 +26,13 @@ type GeneratePresignedUploadUrlResponse = {
   signedUrl: string;
   expiresAt: string;
   publicUrl: string;
+  key?: string;
+};
+
+export type GeneratePresignedDownloadUrlResponse = {
+  signedUrl: string;
+  expiresAt: string;
+  key: string;
 };
 
 export class AssistantCloudFiles {
@@ -93,6 +100,38 @@ export class AssistantCloudFiles {
         response.publicUrl,
         "presigned upload response.publicUrl",
       ),
+      ...("key" in response
+        ? {
+            key: readCloudString(response.key, "presigned upload response.key"),
+          }
+        : {}),
+    };
+  }
+
+  public async generatePresignedDownloadUrl(
+    body: { key: string } | { url: string },
+  ): Promise<GeneratePresignedDownloadUrlResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest(
+        "/files/attachments/generate-presigned-download-url",
+        {
+          method: "POST",
+          body,
+        },
+      ),
+      "presigned download response",
+    );
+
+    return {
+      signedUrl: readCloudString(
+        response.signedUrl,
+        "presigned download response.signedUrl",
+      ),
+      expiresAt: readCloudString(
+        response.expiresAt,
+        "presigned download response.expiresAt",
+      ),
+      key: readCloudString(response.key, "presigned download response.key"),
     };
   }
 }

package/src/AssistantCloudRuns.ts

@@ -14,11 +14,21 @@ type AssistantCloudRunsStreamBody = {
 };
 
 // NOTE: Keep this payload shape aligned with the strict runtime validator in
-// assistant-cloud: apps/aui-cloud-api/src/endpoints/runs/create.ts
+// assistant-cloud: apps/api/src/endpoints/runs/create.ts
 // (createRunSchema). New telemetry fields must be added in both repos together.
 export type AssistantCloudRunReport = {
   thread_id: string;
   status: "completed" | "incomplete" | "error";
+  outcome_type?: "aborted" | "disconnected" | "length" | "content_filter";
+  message_id?: string;
+  first_token_ms?: number;
+  release?: string;
+  environment?: string;
+  tags?: string[];
+  provider?: string;
+  trace_id?: string;
+  error_code?: string;
+  error?: string;
   total_steps?: number;
   tool_calls?: AssistantCloudRunReportToolCall[];
   steps?: {
@@ -29,6 +39,7 @@ export type AssistantCloudRunReport = {
     tool_calls?: AssistantCloudRunReportToolCall[];
     start_ms?: number;
     end_ms?: number;
+    finish_reason?: string;
   }[];
   input_tokens?: number;
   output_tokens?: number;

package/src/AssistantCloudScores.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import { AssistantCloudScores } from "./AssistantCloudScores";
+
+const createCloudScores = () => {
+  const makeRequest = vi.fn();
+  const api = { makeRequest } as unknown as AssistantCloudAPI;
+  return { scores: new AssistantCloudScores(api), makeRequest };
+};
+
+describe("AssistantCloudScores", () => {
+  it("decodes the number the cloud stores for a boolean score", async () => {
+    const { scores, makeRequest } = createCloudScores();
+    makeRequest.mockResolvedValue({
+      score_id: "score_2",
+      name: "resolved",
+      data_type: "boolean",
+      value: 1,
+      string_value: null,
+    });
+
+    await expect(
+      scores.create({
+        name: "resolved",
+        data_type: "boolean",
+        value: true,
+        thread_id: "thread_1",
+      }),
+    ).resolves.toMatchObject({ data_type: "boolean", value: 1 });
+  });
+
+  it("posts the score body as given and decodes the response", async () => {
+    const { scores, makeRequest } = createCloudScores();
+    makeRequest.mockResolvedValue({
+      score_id: "score_1",
+      name: "helpfulness",
+      data_type: "numeric",
+      value: 0.8,
+      string_value: null,
+    });
+
+    await expect(
+      scores.create({
+        name: "helpfulness",
+        data_type: "numeric",
+        value: 0.8,
+        thread_id: "thread_1",
+        message_id: "msg_1",
+      }),
+    ).resolves.toEqual({
+      score_id: "score_1",
+      name: "helpfulness",
+      data_type: "numeric",
+      value: 0.8,
+      string_value: null,
+    });
+    expect(makeRequest).toHaveBeenCalledWith("/scores", {
+      method: "POST",
+      body: {
+        name: "helpfulness",
+        data_type: "numeric",
+        value: 0.8,
+        thread_id: "thread_1",
+        message_id: "msg_1",
+      },
+    });
+  });
+
+  it("decodes a categorical score", async () => {
+    const { scores, makeRequest } = createCloudScores();
+    makeRequest.mockResolvedValue({
+      score_id: "score_2",
+      name: "tone",
+      data_type: "categorical",
+      value: null,
+      string_value: "friendly",
+    });
+
+    await expect(
+      scores.create({
+        name: "tone",
+        data_type: "categorical",
+        string_value: "friendly",
+        run_id: "run_1",
+      }),
+    ).resolves.toMatchObject({
+      data_type: "categorical",
+      string_value: "friendly",
+    });
+  });
+
+  it("rejects a malformed score response", async () => {
+    const { scores, makeRequest } = createCloudScores();
+    makeRequest.mockResolvedValue({
+      score_id: 42,
+      name: "helpfulness",
+      data_type: "numeric",
+      value: 1,
+      string_value: null,
+    });
+
+    await expect(
+      scores.create({
+        name: "helpfulness",
+        data_type: "numeric",
+        value: 1,
+        run_id: "run_1",
+      }),
+    ).rejects.toThrow(
+      'Invalid Assistant Cloud response for "score response.score_id": expected a string',
+    );
+  });
+});

package/src/AssistantCloudScores.ts

@@ -0,0 +1,61 @@
+import type { AssistantCloudAPI } from "./AssistantCloudAPI";
+import {
+  readCloudEnum,
+  readCloudNullableNumber,
+  readCloudNullableString,
+  readCloudRecord,
+  readCloudString,
+} from "./cloudResponse";
+
+const SCORE_DATA_TYPES = ["numeric", "categorical", "boolean"] as const;
+
+export type AssistantCloudScoreBody = {
+  name: string;
+  data_type: "numeric" | "categorical" | "boolean";
+  value?: number | boolean;
+  string_value?: string;
+  comment?: string;
+  thread_id?: string;
+  message_id?: string;
+  run_id?: string;
+};
+
+export type AssistantCloudScoreResponse = {
+  score_id: string;
+  name: string;
+  data_type: "numeric" | "categorical" | "boolean";
+  value: number | null;
+  string_value: string | null;
+};
+
+export class AssistantCloudScores {
+  private cloud: AssistantCloudAPI;
+
+  constructor(cloud: AssistantCloudAPI) {
+    this.cloud = cloud;
+  }
+
+  public async create(
+    body: AssistantCloudScoreBody,
+  ): Promise<AssistantCloudScoreResponse> {
+    const response = readCloudRecord(
+      await this.cloud.makeRequest("/scores", { method: "POST", body }),
+      "score response",
+    );
+
+    return {
+      score_id: readCloudString(response.score_id, "score response.score_id"),
+      name: readCloudString(response.name, "score response.name"),
+      data_type: readCloudEnum(
+        response.data_type,
+        "score response.data_type",
+        SCORE_DATA_TYPES,
+      ),
+      value: readCloudNullableNumber(response.value, "score response.value"),
+      string_value: readCloudNullableString(
+        response.string_value,
+        "score response.string_value",
+      ),
+    };
+  }
+}

package/src/AssistantCloudThreadMessages.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AssistantCloudAPI } from "./AssistantCloudAPI";
 import { AssistantCloudThreadMessages } from "./AssistantCloudThreadMessages";
+import { CloudResponseError } from "./cloudResponse";
 
 const createCloudThreadMessages = () => {
   const makeRequest = vi.fn();
@@ -32,6 +33,41 @@ describe("AssistantCloudThreadMessages responses", () => {
     );
   });
 
+  it("submits and validates message feedback", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    const body = { type: "positive" as const };
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-1",
+      type: "positive",
+    });
+
+    await expect(
+      messages.feedback("thread/1", "message/1", body),
+    ).resolves.toEqual({
+      feedback_id: "feedback-1",
+      type: "positive",
+    });
+    expect(makeRequest).toHaveBeenCalledWith(
+      "/threads/thread%2F1/messages/message%2F1/feedback",
+      { method: "POST", body },
+    );
+
+    makeRequest.mockResolvedValueOnce({ type: "positive" });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", body),
+    ).rejects.toBeInstanceOf(CloudResponseError);
+
+    makeRequest.mockResolvedValueOnce({
+      feedback_id: "feedback-1",
+      type: "neutral",
+    });
+
+    await expect(
+      messages.feedback("thread-1", "message-1", body),
+    ).rejects.toThrow('expected one of "positive", "negative"');
+  });
+
   it("decodes canonical message responses without changing content", async () => {
     const { messages, makeRequest } = createCloudThreadMessages();
     makeRequest.mockResolvedValue({
@@ -58,4 +94,19 @@ describe("AssistantCloudThreadMessages responses", () => {
       created_at: "leave-this-string-untouched",
     });
   });
+
+  it("forwards the pagination query to the list endpoint", async () => {
+    const { messages, makeRequest } = createCloudThreadMessages();
+    makeRequest.mockResolvedValueOnce({ messages: [] });
+
+    await messages.list("thread/1", {
+      format: "aui/v0",
+      limit: 200,
+      after: "message-200",
+    });
+
+    expect(makeRequest).toHaveBeenCalledWith("/threads/thread%2F1/messages", {
+      query: { format: "aui/v0", limit: 200, after: "message-200" },
+    });
+  });
 });