@amigo-ai/platform-sdk 0.22.0 → 0.24.0

package/api.md

@@ -66,7 +66,6 @@ All workspace-scoped resources also expose `withOptions(options)`.
 
 ### `workspaces`
 
-- `create`
 - `createSelfService`
 - `list`
 - `listAutoPaging`
@@ -240,6 +239,7 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `close`
 - `createTurn`
 - `createTurnStream`
+- `streamTurn`
 - `textStreamUrl`
 - `sessionConnectUrl`
 
@@ -417,6 +417,10 @@ All workspace-scoped resources also expose `withOptions(options)`.
 - `getHipaa`
 - `getAccessReview`
 
+### `events`
+
+- `subscribeToWorkspace`
+
 ### `functions`
 
 - `list`

package/dist/index.cjs

@@ -882,14 +882,6 @@ function resolveScopedPlatformClient(client) {
 
 // src/resources/workspaces.ts
 var WorkspacesResource = class extends WorkspaceScopedResource {
-  /** Create a new workspace (unauthenticated — no owner membership created) */
-  async create(body) {
-    return extractData(
-      await this.client.POST("/v1/workspaces", {
-        body
-      })
-    );
-  }
   /** Create a workspace for the authenticated user and attach owner access */
   async createSelfService(body) {
     return extractData(
@@ -2024,7 +2016,10 @@ var ConversationsResource = class extends WorkspaceScopedResource {
       "/v1/{workspace_id}/conversations/{conversation_id}/turns",
       {
         params: {
-          path: { workspace_id: this.workspaceId, conversation_id: conversationId }
+          path: { workspace_id: this.workspaceId, conversation_id: conversationId },
+          ...options?.includeToolCalls !== void 0 && {
+            query: { include_tool_calls: options.includeToolCalls }
+          }
         },
         body: request,
         headers: { Accept: "text/event-stream" },
@@ -2037,6 +2032,35 @@ var ConversationsResource = class extends WorkspaceScopedResource {
     }
     return result.data;
   }
+  /**
+   * Send a message and receive the agent's response as a typed
+   * `TurnStreamEvent` async iterable.
+   *
+   * The bytes-and-parser dance from `createTurnStream` is now hidden inside
+   * the SDK — consumers iterate strongly typed events directly. Each yielded
+   * value is a member of the `TurnStreamEvent` discriminated union (`token`,
+   * `thinking`, `tool_call_started`, `tool_call_completed`, `message`,
+   * `done`, `error`), validated as a record with a known `event`
+   * discriminator. Unknown / malformed frames are dropped silently — this
+   * matches the wire-format-drift behavior of the lower-level
+   * `createTurnStream` while keeping the strict `TurnStreamEvent` static
+   * contract intact for consumers.
+   *
+   * @example
+   * ```ts
+   * for await (const event of client.conversations.streamTurn(convId, { message: "Hello" })) {
+   *   if (event.event === "token") process.stdout.write(event.text);
+   *   else if (event.event === "done") break;
+   * }
+   * ```
+   */
+  async *streamTurn(conversationId, request, options) {
+    const byteStream = await this.createTurnStream(conversationId, request, options);
+    for await (const frame of parseSSEFrames(byteStream)) {
+      const event = parseTurnStreamFrame(frame.event, frame.data);
+      if (event) yield event;
+    }
+  }
   /** Build the real-time text WebSocket URL for browser or custom clients. */
   textStreamUrl(params) {
     const url = buildTextStreamUrl({
@@ -2228,6 +2252,80 @@ function describeInvalidSubprotocolChars(token) {
   }
   return [...chars].map((char) => JSON.stringify(char)).join(", ");
 }
+async function* parseSSEFrames(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  function* drain(text) {
+    buffer += text;
+    while (true) {
+      const idx = findFrameTerminator(buffer);
+      if (idx === null) break;
+      const block = buffer.slice(0, idx.terminatorStart);
+      buffer = buffer.slice(idx.terminatorEnd);
+      const frame = parseSSEBlock(block);
+      if (frame) yield frame;
+    }
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield* drain(decoder.decode(value, { stream: true }));
+    }
+    yield* drain(decoder.decode());
+    if (buffer.trim().length > 0) {
+      const frame = parseSSEBlock(buffer);
+      if (frame) yield frame;
+      buffer = "";
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function findFrameTerminator(s) {
+  const lf = s.indexOf("\n\n");
+  const crlf = s.indexOf("\r\n\r\n");
+  if (lf < 0 && crlf < 0) return null;
+  if (lf < 0) return { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+  if (crlf < 0) return { terminatorStart: lf, terminatorEnd: lf + 2 };
+  return lf < crlf ? { terminatorStart: lf, terminatorEnd: lf + 2 } : { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+}
+function parseSSEBlock(block) {
+  let event = "";
+  const dataLines = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") dataLines.push(value);
+  }
+  if (!event || dataLines.length === 0) return null;
+  return { event, data: dataLines.join("\n") };
+}
+var KNOWN_TURN_STREAM_EVENTS = /* @__PURE__ */ new Set([
+  "token",
+  "thinking",
+  "tool_call_started",
+  "tool_call_completed",
+  "message",
+  "done",
+  "error"
+]);
+function parseTurnStreamFrame(eventName, dataJson) {
+  if (!KNOWN_TURN_STREAM_EVENTS.has(eventName)) return null;
+  let payload;
+  try {
+    payload = JSON.parse(dataJson);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  return { ...payload, event: eventName };
+}
 
 // src/resources/phone-numbers.ts
 var PhoneNumbersResource = class extends WorkspaceScopedResource {
@@ -3246,6 +3344,318 @@ var ComplianceResource = class extends WorkspaceScopedResource {
   }
 };
 
+// src/resources/events.ts
+var DEFAULT_INITIAL_DELAY_MS = 3e3;
+var DEFAULT_MAX_DELAY_MS = 3e4;
+var DEFAULT_MAX_RECONNECTS = 10;
+var MAX_FRAME_BYTES = 1048576;
+var EventsResource = class extends WorkspaceScopedResource {
+  constructor(client, workspaceId2) {
+    super(client, workspaceId2);
+  }
+  /**
+   * Subscribe to the workspace event stream.
+   *
+   * Establishes an SSE connection to ``/v1/{workspace_id}/events/stream``
+   * and invokes ``onEvent`` once per typed {@link WorkspaceSSEEvent}.
+   * Unrecoverable failures (auth errors, exhausted reconnect budget,
+   * caller abort) surface through ``onError``.
+   *
+   * Reconnection is automatic: on a network drop or 5xx, the helper
+   * backs off (initial delay derived from the ``retry:`` directive,
+   * default 3s, doubling with full jitter up to ``maxDelayMs``) and
+   * resumes with the most recently seen ``Last-Event-ID``. The platform
+   * buffers 5 minutes of events for gapless replay.
+   *
+   * @returns a {@link SubscriptionHandle} for cleanup. Aborting the
+   *   caller's ``signal`` is equivalent to calling ``unsubscribe()``.
+   */
+  subscribeToWorkspace(options) {
+    const localController = new AbortController();
+    const cleanups = [];
+    if (options.signal) {
+      if (options.signal.aborted) {
+        localController.abort(options.signal.reason);
+      } else {
+        const onAbort = () => localController.abort(options.signal?.reason);
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        cleanups.push(() => options.signal?.removeEventListener("abort", onAbort));
+      }
+    }
+    const done = runSubscription(
+      this.client,
+      this.workspaceId,
+      options,
+      localController.signal
+    ).finally(() => {
+      for (const cleanup of cleanups) cleanup();
+    });
+    return {
+      done,
+      unsubscribe: () => localController.abort()
+    };
+  }
+};
+async function runSubscription(client, workspaceId2, options, signal) {
+  let lastEventId = options.lastEventId;
+  let attempt = 0;
+  let delayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const maxReconnects = options.maxReconnects ?? DEFAULT_MAX_RECONNECTS;
+  let errorReported = false;
+  const reportError = (error) => {
+    if (errorReported) return;
+    errorReported = true;
+    try {
+      options.onError?.(error);
+    } catch {
+    }
+  };
+  while (!signal.aborted) {
+    if (attempt > 0) {
+      try {
+        options.onReconnect?.(attempt);
+      } catch {
+      }
+    }
+    let outcome;
+    try {
+      outcome = await runOneConnection({
+        client,
+        workspaceId: workspaceId2,
+        lastEventId,
+        signal,
+        onEvent: options.onEvent,
+        onIdAdvance: (id) => {
+          lastEventId = id;
+        },
+        onRetryDirective: (ms) => {
+          delayMs = clampDelay(ms, options.initialDelayMs, maxDelayMs);
+        }
+      });
+    } catch (err) {
+      reportError(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    if (signal.aborted || outcome.kind === "aborted") {
+      return;
+    }
+    if (outcome.kind === "auth-error") {
+      reportError(outcome.error);
+      return;
+    }
+    if (attempt >= maxReconnects) {
+      reportError(
+        new Error(
+          `SSE subscription exhausted reconnect budget (${maxReconnects}): ${outcome.reason}`
+        )
+      );
+      return;
+    }
+    attempt += 1;
+    const sleepMs = jitter(delayMs);
+    delayMs = Math.min(delayMs * 2, maxDelayMs);
+    const slept = await abortableSleep(sleepMs, signal);
+    if (!slept) return;
+  }
+}
+async function runOneConnection(args) {
+  const headers = { Accept: "text/event-stream" };
+  if (args.lastEventId !== void 0) {
+    headers["Last-Event-ID"] = args.lastEventId;
+  }
+  let result;
+  try {
+    result = await args.client.GET("/v1/{workspace_id}/events/stream", {
+      params: { path: { workspace_id: args.workspaceId } },
+      headers,
+      parseAs: "stream",
+      signal: args.signal
+    });
+  } catch (err) {
+    if (args.signal.aborted) return { kind: "aborted" };
+    const error = err instanceof Error ? err : new Error(String(err));
+    const status = readStatus(error);
+    if (status === 401 || status === 403) {
+      return { kind: "auth-error", error };
+    }
+    return { kind: "transport-error", reason: error.message };
+  }
+  if (result.error !== void 0) {
+    return { kind: "transport-error", reason: `API error: ${safeStringify(result.error)}` };
+  }
+  const body = result.data;
+  if (!(body instanceof ReadableStream)) {
+    return { kind: "transport-error", reason: "Expected ReadableStream body for SSE" };
+  }
+  try {
+    for await (const frame of parseSSEFrames2(body, args.signal)) {
+      if (args.signal.aborted) return { kind: "aborted" };
+      if (frame.retry !== void 0) {
+        args.onRetryDirective(frame.retry);
+      }
+      if (frame.id !== void 0) {
+        args.onIdAdvance(frame.id);
+      }
+      if (frame.event && frame.data !== void 0) {
+        const event = parseWorkspaceFrame(frame.event, frame.data);
+        if (event) {
+          try {
+            args.onEvent(event);
+          } catch {
+          }
+        }
+      }
+    }
+  } catch (err) {
+    if (args.signal.aborted) return { kind: "aborted" };
+    const reason = err instanceof Error ? err.message : String(err);
+    return { kind: "transport-error", reason };
+  }
+  if (args.signal.aborted) return { kind: "aborted" };
+  return { kind: "transport-error", reason: "Stream closed by server" };
+}
+async function* parseSSEFrames2(stream, signal) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let cancelled = false;
+  const onAbort = () => {
+    if (cancelled) return;
+    cancelled = true;
+    void reader.cancel().catch(() => {
+    });
+  };
+  let removeAbortHandler;
+  if (signal.aborted) {
+    onAbort();
+  } else {
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortHandler = () => signal.removeEventListener("abort", onAbort);
+  }
+  function* drain(text) {
+    buffer += text;
+    if (buffer.length > MAX_FRAME_BYTES) {
+      throw new Error(`SSE frame buffer exceeded ${MAX_FRAME_BYTES} bytes without terminator`);
+    }
+    while (true) {
+      const idx = findFrameTerminator2(buffer);
+      if (idx === null) break;
+      const block = buffer.slice(0, idx.terminatorStart);
+      buffer = buffer.slice(idx.terminatorEnd);
+      const frame = parseSSEBlock2(block);
+      if (frame) yield frame;
+    }
+  }
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield* drain(decoder.decode(value, { stream: true }));
+    }
+    yield* drain(decoder.decode());
+    if (buffer.trim().length > 0) {
+      const frame = parseSSEBlock2(buffer);
+      if (frame) yield frame;
+      buffer = "";
+    }
+  } finally {
+    removeAbortHandler?.();
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+}
+function findFrameTerminator2(s) {
+  const lf = s.indexOf("\n\n");
+  const crlf = s.indexOf("\r\n\r\n");
+  if (lf < 0 && crlf < 0) return null;
+  if (lf < 0) return { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+  if (crlf < 0) return { terminatorStart: lf, terminatorEnd: lf + 2 };
+  return lf < crlf ? { terminatorStart: lf, terminatorEnd: lf + 2 } : { terminatorStart: crlf, terminatorEnd: crlf + 4 };
+}
+function parseSSEBlock2(block) {
+  let event = "";
+  let id;
+  let retry;
+  const dataLines = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (line === "" || line.startsWith(":")) continue;
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") {
+      event = value;
+    } else if (field === "data") {
+      dataLines.push(value);
+    } else if (field === "id") {
+      id = value;
+    } else if (field === "retry") {
+      const parsed = Number.parseInt(value, 10);
+      if (Number.isFinite(parsed) && parsed >= 0) retry = parsed;
+    }
+  }
+  if (!event && dataLines.length === 0 && id === void 0 && retry === void 0) {
+    return null;
+  }
+  return {
+    event,
+    data: dataLines.length > 0 ? dataLines.join("\n") : void 0,
+    id,
+    retry
+  };
+}
+function parseWorkspaceFrame(eventName, dataJson) {
+  let payload;
+  try {
+    payload = JSON.parse(dataJson);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  return {
+    ...payload,
+    event_type: eventName
+  };
+}
+function readStatus(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const status = error.statusCode;
+  return typeof status === "number" ? status : void 0;
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function jitter(ms) {
+  return Math.floor(Math.random() * Math.max(1, ms));
+}
+function clampDelay(ms, floor, ceiling) {
+  const lo = floor ?? DEFAULT_INITIAL_DELAY_MS;
+  if (!Number.isFinite(ms) || ms <= 0) return lo;
+  return Math.min(Math.max(ms, lo), ceiling);
+}
+async function abortableSleep(ms, signal) {
+  if (signal.aborted) return false;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      resolve(false);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 // src/resources/functions.ts
 var FunctionsResource = class extends WorkspaceScopedResource {
   async list() {
@@ -3961,6 +4371,7 @@ var AmigoClient = class _AmigoClient {
   webhookDestinations;
   safety;
   compliance;
+  events;
   functions;
   /** @internal — exposed for path-level type inference in GET/POST/PUT/etc. */
   api;
@@ -4056,6 +4467,7 @@ var AmigoClient = class _AmigoClient {
     mutable.webhookDestinations = new WebhookDestinationsResource(client, workspaceId2);
     mutable.safety = new SafetyResource(client, workspaceId2);
     mutable.compliance = new ComplianceResource(client, workspaceId2);
+    mutable.events = new EventsResource(client, workspaceId2);
     mutable.functions = new FunctionsResource(client, workspaceId2);
   }
   async resolveApiRequest(path, method, init) {