@amigo-ai/platform-sdk 0.23.0 → 0.25.0

package/dist/index.mjs

@@ -1,4 +1,5 @@
 // src/core/errors.ts
+var RAW_BODY_LIMIT = 8 * 1024;
 var SENSITIVE_FIELDS = /* @__PURE__ */ new Set([
   "id_token",
   "access_token",
@@ -34,6 +35,20 @@ var AmigoError = class extends Error {
   requestId;
   detail;
   context;
+  /**
+   * Typed body of the error response, when one was returned and successfully
+   * parsed. Use the `isHttpException` / `isHttpValidationError` /
+   * `isUnparseableErrorBody` type guards to narrow the discriminated union.
+   *
+   * Named `errorBody` (not `body`) to avoid colliding with the legacy
+   * `ParseError.body: string` field.
+   */
+  errorBody;
+  /**
+   * Raw response body (truncated to 8 KB). Populated even when parsing fails,
+   * so callers always have something to log when debugging server errors.
+   */
+  rawBody;
   constructor(message, ctx = {}) {
     super(message);
     this.name = this.constructor.name;
@@ -42,6 +57,8 @@ var AmigoError = class extends Error {
     this.requestId = ctx.requestId;
     this.detail = ctx.detail;
     this.context = ctx.context ? sanitizeErrorContext(ctx.context) : void 0;
+    this.errorBody = ctx.errorBody;
+    this.rawBody = ctx.rawBody;
     Object.setPrototypeOf(this, new.target.prototype);
     if (typeof Error.captureStackTrace === "function") {
       Error.captureStackTrace(this, this.constructor);
@@ -134,21 +151,69 @@ var ConfigurationError = class extends AmigoError {
     super(message);
   }
 };
-async function createApiError(response) {
-  let body = {};
+async function readErrorBody(response) {
+  let rawBody = "";
+  try {
+    rawBody = await response.text();
+  } catch {
+    return {
+      body: { detail: response.statusText || `HTTP ${response.status}`, raw_body: "" },
+      rawBody: ""
+    };
+  }
+  const truncatedRaw = rawBody.length > RAW_BODY_LIMIT ? rawBody.slice(0, RAW_BODY_LIMIT) : rawBody;
+  if (rawBody.length === 0) {
+    return {
+      body: { detail: response.statusText || `HTTP ${response.status}`, raw_body: "" },
+      rawBody: ""
+    };
+  }
   try {
-    const rawBody = await response.text();
-    body = JSON.parse(rawBody);
+    const parsed = JSON.parse(rawBody);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { body: parsed, rawBody: truncatedRaw };
+    }
+    return {
+      body: {
+        detail: response.statusText || `HTTP ${response.status}`,
+        raw_body: truncatedRaw
+      },
+      rawBody: truncatedRaw
+    };
   } catch {
+    return {
+      body: {
+        detail: response.statusText || `HTTP ${response.status}`,
+        raw_body: truncatedRaw
+      },
+      rawBody: truncatedRaw
+    };
   }
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+async function createApiError(response) {
+  const { body, rawBody } = await readErrorBody(response);
+  const flat = body;
+  const detailString = typeof flat.detail === "string" ? flat.detail : flat.detail !== void 0 ? safeStringify(flat.detail) : void 0;
+  const errorCode = typeof flat.error_code === "string" ? flat.error_code : void 0;
+  const requestIdFromBody = typeof flat.request_id === "string" ? flat.request_id : void 0;
+  const messageFromBody = typeof flat.message === "string" ? flat.message : void 0;
   const ctx = {
     statusCode: response.status,
-    errorCode: body.error_code,
-    requestId: body.request_id ?? response.headers.get("x-request-id") ?? void 0,
-    detail: body.detail,
-    context: { url: response.url, response: body }
+    errorCode,
+    requestId: requestIdFromBody ?? response.headers.get("x-request-id") ?? void 0,
+    detail: detailString,
+    context: { url: response.url, response: body },
+    errorBody: body,
+    rawBody
   };
-  const message = body.message ?? body.detail ?? response.statusText ?? `HTTP ${response.status}`;
+  const message = messageFromBody ?? detailString ?? response.statusText ?? `HTTP ${response.status}`;
   switch (response.status) {
     case 400:
       return new BadRequestError(message, ctx);
@@ -198,6 +263,40 @@ function isAuthenticationError(err) {
 function isRequestTimeoutError(err) {
   return err instanceof RequestTimeoutError;
 }
+function isPermissionError(err) {
+  return err instanceof PermissionError;
+}
+function isConflictError(err) {
+  return err instanceof ConflictError;
+}
+function isValidationError(err) {
+  return err instanceof ValidationError;
+}
+function isServerError(err) {
+  return err instanceof ServerError;
+}
+function isNetworkError(err) {
+  return err instanceof NetworkError;
+}
+function isHttpValidationError(err) {
+  if (!(err instanceof AmigoError)) return false;
+  const body = err.errorBody;
+  return Array.isArray(body?.detail);
+}
+function isHttpException(err) {
+  if (!(err instanceof AmigoError)) return false;
+  const body = err.errorBody;
+  if (!body) return false;
+  if (Array.isArray(body.detail)) {
+    return false;
+  }
+  return "detail" in body && !("raw_body" in body);
+}
+function isUnparseableErrorBody(err) {
+  if (!(err instanceof AmigoError)) return false;
+  const body = err.errorBody;
+  return typeof body?.raw_body === "string";
+}
 
 // src/core/openapi-client.ts
 import createClientImport from "openapi-fetch";
@@ -788,14 +887,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(
@@ -2369,6 +2460,36 @@ var IntegrationsResource = class extends WorkspaceScopedResource {
       )
     );
   }
+  /**
+   * Probe an integration's connection + auth without invoking any specific
+   * endpoint. Exercises auth resolution end-to-end (SSM lookups, OAuth2 token
+   * mints, JWT signing) and sends a HEAD request to ``base_url`` (REST/FHIR)
+   * or ``mcp_url`` (MCP). Safe on production integrations — HEAD carries no
+   * side effects.
+   *
+   * The most recent probe outcome is persisted on the integration so
+   * subsequent ``get`` / ``list`` responses surface ``last_tested_at`` +
+   * ``last_test_status`` without re-probing.
+   *
+   * @returns ``status`` is one of ``healthy`` / ``auth_failed`` /
+   *   ``unreachable`` / ``timeout`` / ``ssl_error`` / ``misconfigured``,
+   *   each mapping to a distinct, actionable user message.
+   */
+  async testConnection(integrationId2) {
+    return extractData(
+      await this.client.POST(
+        "/v1/{workspace_id}/integrations/{integration_id}/test-connection",
+        {
+          params: {
+            path: {
+              workspace_id: this.workspaceId,
+              integration_id: integrationId2
+            }
+          }
+        }
+      )
+    );
+  }
   /** Check health of all integrations in the workspace */
   async getHealthCheck() {
     return extractData(
@@ -3258,6 +3379,418 @@ var ComplianceResource = class extends WorkspaceScopedResource {
   }
 };
 
+// src/resources/events.ts
+var WorkspaceEventStreamError = class extends Error {
+  code;
+  retryable;
+  /** Raw decoded ``error`` frame body (or ``undefined`` for transport errors). */
+  frame;
+  constructor(message, code, retryable, frame) {
+    super(message);
+    this.name = "WorkspaceEventStreamError";
+    this.code = code;
+    this.retryable = retryable;
+    this.frame = frame;
+  }
+};
+function isWorkspaceEventStreamError(value) {
+  return value instanceof WorkspaceEventStreamError;
+}
+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()
+    };
+  }
+};
+var TERMINAL_SERVER_ERROR_CODES = {
+  too_many_streams: "too_many_streams"
+};
+var RECOVERABLE_SERVER_ERROR_CODES = {
+  stream_unavailable: "stream_unavailable",
+  stream_error: "stream_error"
+};
+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 (outcome.kind === "terminal-server-error") {
+      reportError(
+        new WorkspaceEventStreamError(
+          outcome.message,
+          outcome.code,
+          outcome.retryable,
+          outcome.frame
+        )
+      );
+      return;
+    }
+    if (attempt >= maxReconnects) {
+      reportError(
+        new WorkspaceEventStreamError(
+          `SSE subscription exhausted reconnect budget (${maxReconnects}): ${outcome.reason}`,
+          "transport_exhausted",
+          true
+        )
+      );
+      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: ${safeStringify2(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 === "error" && frame.data !== void 0) {
+        const errOutcome = interpretServerErrorFrame(frame.data);
+        if (errOutcome.terminal) {
+          return {
+            kind: "terminal-server-error",
+            code: errOutcome.code,
+            message: errOutcome.message,
+            retryable: errOutcome.retryable,
+            frame: errOutcome.frame
+          };
+        }
+        return { kind: "transport-error", reason: errOutcome.message };
+      }
+      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 interpretServerErrorFrame(dataJson) {
+  let payload;
+  try {
+    payload = JSON.parse(dataJson);
+  } catch {
+    return {
+      terminal: false,
+      code: "stream_error",
+      message: "Server sent malformed error frame",
+      retryable: true,
+      frame: {}
+    };
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return {
+      terminal: false,
+      code: "stream_error",
+      message: "Server sent non-object error frame",
+      retryable: true,
+      frame: {}
+    };
+  }
+  const obj = payload;
+  const rawCode = typeof obj["code"] === "string" ? obj["code"] : "";
+  const message = typeof obj["message"] === "string" ? obj["message"] : "Stream error";
+  if (rawCode in TERMINAL_SERVER_ERROR_CODES) {
+    return {
+      terminal: true,
+      code: TERMINAL_SERVER_ERROR_CODES[rawCode],
+      message,
+      retryable: false,
+      frame: obj
+    };
+  }
+  if (rawCode in RECOVERABLE_SERVER_ERROR_CODES) {
+    return {
+      terminal: false,
+      code: RECOVERABLE_SERVER_ERROR_CODES[rawCode],
+      message,
+      retryable: true,
+      frame: obj
+    };
+  }
+  return {
+    terminal: false,
+    code: "unknown",
+    message: rawCode ? `${message} (code=${rawCode})` : message,
+    retryable: true,
+    frame: obj
+  };
+}
+function readStatus(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const status = error.statusCode;
+  return typeof status === "number" ? status : void 0;
+}
+function safeStringify2(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() {
@@ -3312,6 +3845,450 @@ var FunctionsResource = class extends WorkspaceScopedResource {
   }
 };
 
+// src/core/reconnecting-websocket.ts
+var ReconnectingWebSocketError = class extends Error {
+  reason;
+  closeCode;
+  closeReason;
+  attempts;
+  constructor(message, reason, closeCode, closeReason, attempts) {
+    super(message);
+    this.name = "ReconnectingWebSocketError";
+    this.reason = reason;
+    this.closeCode = closeCode;
+    this.closeReason = closeReason;
+    this.attempts = attempts;
+  }
+};
+var TERMINAL_CLOSE_CODES = /* @__PURE__ */ new Set([1008, 4001, 4003, 4100, 4403]);
+var RATE_LIMITED_CLOSE_CODES = /* @__PURE__ */ new Set([1013, 4029]);
+var RATE_LIMITED_FLOOR_MS = 5e3;
+var DEFAULT_INITIAL_DELAY_MS2 = 1e3;
+var DEFAULT_MAX_DELAY_MS2 = 3e4;
+var DEFAULT_MAX_RECONNECTS2 = 10;
+var DEFAULT_IDLE_TIMEOUT_MS = 45e3;
+function createReconnectingWebSocket(options) {
+  const factory = resolveWebSocketFactory(options.webSocketFactory);
+  const initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS2;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS2;
+  const maxReconnects = options.maxReconnects ?? DEFAULT_MAX_RECONNECTS2;
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const localController = new AbortController();
+  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 });
+    }
+  }
+  let currentSocket = null;
+  let state = "connecting";
+  let errorReported = false;
+  function setState(next) {
+    if (state === next) return;
+    state = next;
+    try {
+      options.onStateChange?.(next);
+    } catch {
+    }
+  }
+  function reportError(err) {
+    if (errorReported) return;
+    errorReported = true;
+    setState("terminal");
+    try {
+      options.onError?.(err);
+    } catch {
+    }
+  }
+  const handle = {
+    get state() {
+      return state;
+    },
+    get done() {
+      return done;
+    },
+    send(data) {
+      if (!currentSocket || currentSocket.readyState !== 1) {
+        throw new Error(`Cannot send on socket in state ${state}`);
+      }
+      currentSocket.send(data);
+    },
+    close(code, reason) {
+      localController.abort(new Error(reason ?? "closed"));
+      try {
+        currentSocket?.close(code, reason);
+      } catch {
+      }
+    }
+  };
+  const done = runLoop({
+    factory,
+    options,
+    initialDelayMs,
+    maxDelayMs,
+    maxReconnects,
+    idleTimeoutMs,
+    signal: localController.signal,
+    setState,
+    reportError,
+    setSocket: (s) => {
+      currentSocket = s;
+    }
+  });
+  return handle;
+}
+async function runLoop(args) {
+  const { options, signal, setState, reportError, setSocket } = args;
+  let attempt = 0;
+  let delayMs = args.initialDelayMs;
+  while (!signal.aborted) {
+    if (attempt > 0) {
+      setState("reconnecting");
+      const sleepMs = jitter2(delayMs);
+      try {
+        options.onReconnect?.({ attempt, delayMs: sleepMs, closeCode: void 0 });
+      } catch {
+      }
+      const slept = await abortableSleep2(sleepMs, signal);
+      if (!slept) break;
+      delayMs = Math.min(delayMs * 2, args.maxDelayMs);
+    }
+    setState(attempt === 0 ? "connecting" : "connecting");
+    let outcome;
+    try {
+      outcome = await runOneConnection2(args);
+    } catch (err) {
+      reportError(
+        new ReconnectingWebSocketError(
+          err instanceof Error ? err.message : "Failed to open WebSocket",
+          "open_failed",
+          void 0,
+          void 0,
+          attempt
+        )
+      );
+      return;
+    } finally {
+      setSocket(null);
+    }
+    if (outcome.closeCode !== void 0 && TERMINAL_CLOSE_CODES.has(outcome.closeCode)) {
+      reportError(
+        new ReconnectingWebSocketError(
+          `Server closed with terminal code ${outcome.closeCode}: ${outcome.closeReason ?? ""}`,
+          outcome.closeCode === 4403 ? "auth" : "client_error",
+          outcome.closeCode,
+          outcome.closeReason,
+          attempt
+        )
+      );
+      return;
+    }
+    if (outcome.aborted || signal.aborted) {
+      setState("closed");
+      return;
+    }
+    if (attempt >= args.maxReconnects) {
+      reportError(
+        new ReconnectingWebSocketError(
+          `Reconnect budget exhausted (${args.maxReconnects} attempts)`,
+          "reconnect_budget_exhausted",
+          outcome.closeCode,
+          outcome.closeReason,
+          attempt
+        )
+      );
+      return;
+    }
+    if (outcome.closeCode !== void 0 && RATE_LIMITED_CLOSE_CODES.has(outcome.closeCode)) {
+      delayMs = Math.max(delayMs, RATE_LIMITED_FLOOR_MS);
+    }
+    attempt += 1;
+  }
+  setState("closed");
+}
+async function runOneConnection2(args) {
+  const { options, factory, signal, setState, setSocket, idleTimeoutMs } = args;
+  let socket;
+  try {
+    socket = factory(options.url, options.protocols);
+  } catch (err) {
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+  setSocket(socket);
+  return new Promise((resolve) => {
+    let watchdogTimer = null;
+    let resolved = false;
+    function clearWatchdog() {
+      if (watchdogTimer !== null) {
+        clearTimeout(watchdogTimer);
+        watchdogTimer = null;
+      }
+    }
+    function armWatchdog() {
+      if (idleTimeoutMs <= 0) return;
+      clearWatchdog();
+      watchdogTimer = setTimeout(() => {
+        if (resolved) return;
+        try {
+          socket.close(4001, "idle timeout");
+        } catch {
+        }
+        finalize({
+          closeCode: 4001,
+          closeReason: "idle timeout",
+          watchdogTriggered: true,
+          aborted: false
+        });
+      }, idleTimeoutMs);
+    }
+    function finalize(outcome) {
+      if (resolved) return;
+      resolved = true;
+      clearWatchdog();
+      signal.removeEventListener("abort", onAbort);
+      try {
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("close", onClose);
+        socket.removeEventListener("error", onSocketError);
+      } catch {
+      }
+      resolve(outcome);
+    }
+    function onOpen() {
+      setState("open");
+      armWatchdog();
+    }
+    function onMessage(ev) {
+      armWatchdog();
+      try {
+        options.onMessage(ev);
+      } catch {
+      }
+    }
+    function onClose(ev) {
+      setState("closed");
+      finalize({
+        closeCode: ev.code,
+        closeReason: ev.reason,
+        watchdogTriggered: false,
+        aborted: false
+      });
+    }
+    function onSocketError() {
+    }
+    function onAbort() {
+      try {
+        socket.close(1e3, "client aborted");
+      } catch {
+      }
+      finalize({
+        closeCode: void 0,
+        closeReason: void 0,
+        watchdogTriggered: false,
+        aborted: true
+      });
+    }
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    socket.addEventListener("open", onOpen);
+    socket.addEventListener("message", onMessage);
+    socket.addEventListener(
+      "close",
+      onClose
+    );
+    socket.addEventListener("error", onSocketError);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function resolveWebSocketFactory(factory) {
+  if (factory) return factory;
+  const globalWs = globalThis.WebSocket;
+  if (!globalWs) {
+    return () => {
+      throw new Error(
+        "No global WebSocket available; pass webSocketFactory to createReconnectingWebSocket"
+      );
+    };
+  }
+  return (url, protocols) => new globalWs(url, protocols);
+}
+function jitter2(ms) {
+  return Math.floor(Math.random() * Math.max(1, ms));
+}
+async function abortableSleep2(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/observers.ts
+var WEB_SOCKET_PROTOCOL_TOKEN_RE2 = /^[!#$%&'*+\-.^_`|~A-Za-z0-9]+$/;
+var MAX_AUTH_TOKEN_CHARS2 = 4096;
+function observerAuthProtocols(token) {
+  if (!token) {
+    throw new ConfigurationError("observerAuthProtocols requires a non-empty token");
+  }
+  if (token.length > MAX_AUTH_TOKEN_CHARS2) {
+    throw new ConfigurationError(
+      `observer token exceeds the ${MAX_AUTH_TOKEN_CHARS2}-character WebSocket subprotocol limit`
+    );
+  }
+  if (!WEB_SOCKET_PROTOCOL_TOKEN_RE2.test(token)) {
+    throw new ConfigurationError(
+      "observer token contains characters browsers reject in WebSocket subprotocols"
+    );
+  }
+  return ["auth", token];
+}
+var ObserversResource = class extends WorkspaceScopedResource {
+  agentBaseUrl;
+  constructor(client, workspaceId2, agentBaseUrl) {
+    super(client, workspaceId2);
+    this.agentBaseUrl = agentBaseUrl;
+  }
+  /**
+   * Subscribe to the live observer stream for a call.
+   *
+   * Returns a {@link ReconnectingWebSocketHandle} that resolves
+   * ``handle.done`` when the stream terminates (consumer-aborted, terminal
+   * close code, or reconnect budget exhausted). Errors are surfaced through
+   * ``onError``; the promise never rejects.
+   */
+  subscribe(options) {
+    const url = buildObserverUrl({
+      baseUrl: this.agentBaseUrl ?? this.platformBaseUrl,
+      workspaceId: this.workspaceId,
+      callSid: options.callSid,
+      observerUrl: options.observerUrl
+    });
+    const protocols = observerAuthProtocols(options.token);
+    return createReconnectingWebSocket({
+      url,
+      protocols: [...protocols],
+      onMessage: (ev) => {
+        const parsed = parseObserverFrame(ev.data);
+        if (parsed) {
+          try {
+            options.onEvent(parsed);
+          } catch {
+          }
+        }
+      },
+      onStateChange: options.onStateChange,
+      onReconnect: options.onReconnect,
+      onError: options.onError,
+      signal: options.signal,
+      idleTimeoutMs: options.idleTimeoutMs ?? 6e4,
+      initialDelayMs: options.initialDelayMs ?? 1e3,
+      maxDelayMs: options.maxDelayMs ?? 3e4,
+      maxReconnects: options.maxReconnects ?? 10,
+      webSocketFactory: options.webSocketFactory
+    });
+  }
+};
+var CALL_SID_RE = /^CA[a-zA-Z0-9]{32}$/;
+function buildObserverUrl(args) {
+  if (!args.workspaceId) {
+    throw new ConfigurationError("workspaceId is required to build the observer URL");
+  }
+  if (!args.callSid) {
+    throw new ConfigurationError("callSid is required to subscribe to the observer stream");
+  }
+  if (args.observerUrl) {
+    return parseOverride(args.observerUrl).toString();
+  }
+  if (!CALL_SID_RE.test(args.callSid)) {
+    throw new ConfigurationError(
+      `callSid does not match Twilio CA SID format (CA + 32 hex chars): ${args.callSid}`
+    );
+  }
+  return deriveFromBase(args.baseUrl, args.workspaceId, args.callSid).toString();
+}
+function parseOverride(observerUrl) {
+  let url;
+  try {
+    url = new URL(observerUrl);
+  } catch (cause) {
+    throw new ConfigurationError(
+      `observerUrl must be an absolute URL: ${String(cause)}`
+    );
+  }
+  if (url.protocol !== "ws:" && url.protocol !== "wss:") {
+    throw new ConfigurationError("observerUrl overrides must use ws: or wss: URLs");
+  }
+  if (url.search || url.hash) {
+    throw new ConfigurationError(
+      "observerUrl overrides must not include query parameters or fragments"
+    );
+  }
+  return url;
+}
+function deriveFromBase(baseUrl, workspaceId2, callSid) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch (cause) {
+    throw new ConfigurationError(
+      `observerUrl cannot be derived from baseUrl: ${String(cause)}`
+    );
+  }
+  let scheme;
+  if (parsed.protocol === "https:" || parsed.protocol === "wss:") scheme = "wss:";
+  else if (parsed.protocol === "http:" || parsed.protocol === "ws:") scheme = "ws:";
+  else {
+    throw new ConfigurationError(
+      `observerUrl can only be derived from an http, https, ws, or wss baseUrl: ${baseUrl}`
+    );
+  }
+  if (parsed.pathname !== "/" && parsed.pathname !== "") {
+    throw new ConfigurationError(
+      "observerUrl can only be derived from an origin-only baseUrl; pass observerUrl explicitly when using path-prefixed gateways"
+    );
+  }
+  const out = new URL(`${scheme}//${parsed.host}/v1/${encodeURIComponent(workspaceId2)}/observers/${encodeURIComponent(callSid)}/ws`);
+  return out;
+}
+function parseObserverFrame(data) {
+  let text;
+  if (typeof data === "string") {
+    text = data;
+  } else if (data instanceof ArrayBuffer) {
+    text = new TextDecoder().decode(data);
+  } else if (ArrayBuffer.isView(data)) {
+    const view = data;
+    text = new TextDecoder().decode(
+      new Uint8Array(view.buffer, view.byteOffset, view.byteLength)
+    );
+  } else {
+    return null;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  const obj = payload;
+  if (typeof obj["type"] !== "string") return null;
+  return obj;
+}
+
 // src/core/branded-types.ts
 var workspaceId = (id) => id;
 var apiKeyId = (id) => id;
@@ -3973,7 +4950,14 @@ var AmigoClient = class _AmigoClient {
   webhookDestinations;
   safety;
   compliance;
+  events;
   functions;
+  /**
+   * Voice-call observer real-time stream. Subscribe with
+   * ``client.observers.subscribe({ callSid, token, onEvent })``. See
+   * {@link ObserversResource}.
+   */
+  observers;
   /** @internal — exposed for path-level type inference in GET/POST/PUT/etc. */
   api;
   constructor(config) {
@@ -4029,6 +5013,10 @@ var AmigoClient = class _AmigoClient {
       allowEmptyBody: true
     });
   }
+  defineRoute(method, path) {
+    const dispatcher = this[method];
+    return (init) => dispatcher.call(this, path, init);
+  }
   static fromPlatformClient(client, workspaceId2, baseUrl, agentBaseUrl) {
     const instance = Object.create(_AmigoClient.prototype);
     _AmigoClient.hydrate(instance, client, workspaceId2, baseUrl, agentBaseUrl);
@@ -4068,7 +5056,9 @@ 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);
+    mutable.observers = new ObserversResource(client, workspaceId2, agentBaseUrl);
   }
   async resolveApiRequest(path, method, init) {
     const { baseClient, options } = resolveScopedPlatformClient(this.api);
@@ -4126,9 +5116,11 @@ export {
   MemoryTokenStorage,
   NetworkError,
   NotFoundError,
+  ObserversResource,
   ParseError,
   PermissionError,
   RateLimitError,
+  ReconnectingWebSocketError,
   RefreshTokenExpiredError,
   RequestTimeoutError,
   ServerError,
@@ -4136,12 +5128,14 @@ export {
   TokenManager,
   ValidationError,
   WebhookVerificationError,
+  WorkspaceEventStreamError,
   actionId,
   agentId,
   apiKeyId,
   buildLastResponse,
   callId,
   contextGraphId,
+  createReconnectingWebSocket,
   dataSourceId,
   entityId,
   eventId,
@@ -4153,10 +5147,20 @@ export {
   integrationId,
   isAmigoError,
   isAuthenticationError,
+  isConflictError,
+  isHttpException,
+  isHttpValidationError,
+  isNetworkError,
   isNotFoundError,
+  isPermissionError,
   isRateLimitError,
   isRequestTimeoutError,
+  isServerError,
+  isUnparseableErrorBody,
+  isValidationError,
+  isWorkspaceEventStreamError,
   loginWithDeviceCode,
+  observerAuthProtocols,
   openBrowser,
   paginate,
   parseRateLimitHeaders,