@amigo-ai/platform-sdk 0.24.0 → 0.26.0

package/dist/index.cjs

@@ -44,9 +44,11 @@ __export(index_exports, {
   MemoryTokenStorage: () => MemoryTokenStorage,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
+  ObserversResource: () => ObserversResource,
   ParseError: () => ParseError,
   PermissionError: () => PermissionError,
   RateLimitError: () => RateLimitError,
+  ReconnectingWebSocketError: () => ReconnectingWebSocketError,
   RefreshTokenExpiredError: () => RefreshTokenExpiredError,
   RequestTimeoutError: () => RequestTimeoutError,
   ServerError: () => ServerError,
@@ -54,12 +56,14 @@ __export(index_exports, {
   TokenManager: () => TokenManager,
   ValidationError: () => ValidationError,
   WebhookVerificationError: () => WebhookVerificationError,
+  WorkspaceEventStreamError: () => WorkspaceEventStreamError,
   actionId: () => actionId,
   agentId: () => agentId,
   apiKeyId: () => apiKeyId,
   buildLastResponse: () => buildLastResponse,
   callId: () => callId,
   contextGraphId: () => contextGraphId,
+  createReconnectingWebSocket: () => createReconnectingWebSocket,
   dataSourceId: () => dataSourceId,
   entityId: () => entityId,
   eventId: () => eventId,
@@ -71,10 +75,20 @@ __export(index_exports, {
   integrationId: () => integrationId,
   isAmigoError: () => isAmigoError,
   isAuthenticationError: () => isAuthenticationError,
+  isConflictError: () => isConflictError,
+  isHttpException: () => isHttpException,
+  isHttpValidationError: () => isHttpValidationError,
+  isNetworkError: () => isNetworkError,
   isNotFoundError: () => isNotFoundError,
+  isPermissionError: () => isPermissionError,
   isRateLimitError: () => isRateLimitError,
   isRequestTimeoutError: () => isRequestTimeoutError,
+  isServerError: () => isServerError,
+  isUnparseableErrorBody: () => isUnparseableErrorBody,
+  isValidationError: () => isValidationError,
+  isWorkspaceEventStreamError: () => isWorkspaceEventStreamError,
   loginWithDeviceCode: () => loginWithDeviceCode,
+  observerAuthProtocols: () => observerAuthProtocols,
   openBrowser: () => openBrowser,
   paginate: () => paginate,
   parseRateLimitHeaders: () => parseRateLimitHeaders,
@@ -93,6 +107,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/core/errors.ts
+var RAW_BODY_LIMIT = 8 * 1024;
 var SENSITIVE_FIELDS = /* @__PURE__ */ new Set([
   "id_token",
   "access_token",
@@ -128,6 +143,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;
@@ -136,6 +165,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);
@@ -228,21 +259,69 @@ var ConfigurationError = class extends AmigoError {
     super(message);
   }
 };
-async function createApiError(response) {
-  let body = {};
+async function readErrorBody(response) {
+  let rawBody = "";
   try {
-    const rawBody = await response.text();
-    body = JSON.parse(rawBody);
+    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 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);
@@ -292,6 +371,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
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
@@ -2455,6 +2568,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(
@@ -3345,6 +3488,22 @@ 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;
@@ -3396,6 +3555,13 @@ var EventsResource = class extends WorkspaceScopedResource {
     };
   }
 };
+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;
@@ -3444,10 +3610,23 @@ async function runSubscription(client, workspaceId2, options, signal) {
       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 Error(
-          `SSE subscription exhausted reconnect budget (${maxReconnects}): ${outcome.reason}`
+        new WorkspaceEventStreamError(
+          `SSE subscription exhausted reconnect budget (${maxReconnects}): ${outcome.reason}`,
+          "transport_exhausted",
+          true
         )
       );
       return;
@@ -3482,7 +3661,7 @@ async function runOneConnection(args) {
     return { kind: "transport-error", reason: error.message };
   }
   if (result.error !== void 0) {
-    return { kind: "transport-error", reason: `API error: ${safeStringify(result.error)}` };
+    return { kind: "transport-error", reason: `API error: ${safeStringify2(result.error)}` };
   }
   const body = result.data;
   if (!(body instanceof ReadableStream)) {
@@ -3497,6 +3676,19 @@ async function runOneConnection(args) {
       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) {
@@ -3620,12 +3812,63 @@ function parseWorkspaceFrame(eventName, dataJson) {
     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 safeStringify(value) {
+function safeStringify2(value) {
   try {
     return JSON.stringify(value);
   } catch {
@@ -3710,6 +3953,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;
@@ -4373,6 +5060,12 @@ var AmigoClient = class _AmigoClient {
   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) {
@@ -4428,6 +5121,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);
@@ -4469,6 +5166,7 @@ var AmigoClient = class _AmigoClient {
     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);