@d-id/client-sdk 2.0.10 → 3.0.0-staging.413

package/dist/{livekit-manager-25aUaO_G.js → livekit-manager-D-B3qdMq.js}

@@ -1,4 +1,4 @@
-import { c as Qe, C as J, S as l, a as We, b as qe, A as C, d as Ge, l as pe, e as He, t as Xe, f as A, g as U, h as Ze, D as me, i as Ye, j as b, n as en } from "./index-K6rHpqny.js";
+import { c as Qe, C as J, S as l, a as We, b as qe, A as C, d as Ge, l as pe, e as He, t as Xe, f as E, g as U, h as Ze, D as me, i as Ye, j as b, n as en } from "./index-BOeL7MEm.js";
 function nn() {
   try {
     return Intl.DateTimeFormat().resolvedOptions().timeZone ?? "";
@@ -35,7 +35,7 @@ const an = {
 }, Ce = 2e4, cn = [];
 async function sn() {
   try {
-    return await import("./index-K6rHpqny.js").then((f) => f.G);
+    return await import("./index-BOeL7MEm.js").then((f) => f.y);
   } catch {
     throw new Error(
       "LiveKit client is required for this streaming manager. Please install it using: npm install livekit-client"
@@ -51,12 +51,12 @@ const un = {
 }, j = (f = "Stream Error") => new He(f);
 function Se(f, S, u) {
   var i, k;
-  throw S("Failed to connect to LiveKit room:", f), (i = u.onConnectionStateChange) == null || i.call(u, A.Fail, "internal:init-error"), (k = u.onError) == null || k.call(u, f, { sessionId: "" }), f;
+  throw S("Failed to connect to LiveKit room:", f), (i = u.onConnectionStateChange) == null || i.call(u, E.Fail, "internal:init-error"), (k = u.onError) == null || k.call(u, f, { sessionId: "" }), f;
 }
 async function ln(f, S, u) {
   var de;
-  const i = We(u.debug || !1, "LiveKitStreamingManager"), { Room: k, RoomEvent: g, ConnectionState: I, Track: ee } = await sn(), { callbacks: n, auth: Te, baseURL: ve, analytics: ne } = u;
-  let a = null, E = !1;
+  const i = We(u.debug || !1, "LiveKitStreamingManager"), { Room: k, RoomEvent: g, ConnectionState: I, Track: ee } = await sn(), { callbacks: n, auth: Te, baseURL: ye, analytics: ne } = u;
+  let a = null, w = !1;
   const te = qe.Fluent;
   let L = null;
   const P = { isPublishing: !1, publication: null }, Q = { isPublishing: !1, publication: null };
@@ -69,21 +69,21 @@ async function ln(f, S, u) {
   for (const [e, t] of u.rpcMethods ?? [])
     a.registerRpcMethod(e, t);
   let R = null, M = C.Idle, W = !0;
-  const v = /* @__PURE__ */ new Map();
+  const y = /* @__PURE__ */ new Map();
   let x = null, q = null;
-  const ye = rn(Te, ve || Ge, f, n.onError);
-  let y, _, $, ie = !0;
+  const ve = rn(Te, ye || Ge, f, n.onError);
+  let v, _, $, ie = !0;
   try {
-    const e = await ye.createStream({
+    const e = await ve.createStream({
       transport: S.transport,
-      chat_persist: S.chat_persist ?? !0,
+      chat_persist: S.chat_persist ?? !1,
       verbose: u.verbose ?? !1
     }), { id: t, session_token: o, session_url: r, interrupt_enabled: c } = e;
-    (de = n.onStreamCreated) == null || de.call(n, { session_id: t, stream_id: t, agent_id: f }), y = t, _ = o, $ = r, ie = c ?? !0, await a.prepareConnection($, _);
+    (de = n.onStreamCreated) == null || de.call(n, { session_id: t, stream_id: t, agent_id: f }), v = t, _ = o, $ = r, ie = c ?? !0, await a.prepareConnection($, _);
   } catch (e) {
     Se(e, i, n);
   }
-  if (!$ || !_ || !y)
+  if (!$ || !_ || !v)
     return Promise.reject(new Error("Failed to initialize LiveKit stream"));
   a.on(g.ConnectionStateChanged, Ee).on(g.ConnectionQualityChanged, Re).on(g.ParticipantConnected, be).on(g.ParticipantDisconnected, Le).on(g.TrackSubscribed, Me).on(g.TrackUnsubscribed, ke).on(g.DataReceived, Ve).on(g.MediaDevicesError, Fe).on(g.TranscriptionReceived, we).on(g.EncryptionError, Ue).on(g.TrackSubscriptionFailed, je);
   function we(e, t) {
@@ -107,8 +107,8 @@ async function ln(f, S, u) {
       const e = j("Track subscription timeout");
       ne.track("connectivity-error", {
         error: Xe(e),
-        sessionId: y
-      }), (t = n.onError) == null || t.call(n, e, { sessionId: y }), Y("internal:track-subscription-timeout");
+        sessionId: v
+      }), (t = n.onError) == null || t.call(n, e, { sessionId: v }), Y("internal:track-subscription-timeout");
     }, Ce);
   } catch (e) {
     Se(e, i, n);
@@ -120,23 +120,23 @@ async function ln(f, S, u) {
     var t, o, r, c;
     switch (i("Connection state changed:", e), e) {
       case I.Connecting:
-        i("CALLBACK: onConnectionStateChange(Connecting)"), (t = n.onConnectionStateChange) == null || t.call(n, A.Connecting, "livekit:connecting");
+        i("CALLBACK: onConnectionStateChange(Connecting)"), (t = n.onConnectionStateChange) == null || t.call(n, E.Connecting, "livekit:connecting");
         break;
       case I.Connected:
-        i("LiveKit room connected successfully"), E = !0;
+        i("LiveKit room connected successfully"), w = !0;
         break;
       case I.Disconnected:
-        i("LiveKit room disconnected"), E = !1, K = !1, P.publication = null, Q.publication = null, (o = n.onConnectionStateChange) == null || o.call(
+        i("LiveKit room disconnected"), w = !1, K = !1, P.publication = null, Q.publication = null, (o = n.onConnectionStateChange) == null || o.call(
           n,
-          A.Disconnected,
+          E.Disconnected,
           q ?? "livekit:disconnected"
         );
         break;
       case I.Reconnecting:
-        i("LiveKit room reconnecting..."), (r = n.onConnectionStateChange) == null || r.call(n, A.Connecting, "livekit:reconnecting");
+        i("LiveKit room reconnecting..."), (r = n.onConnectionStateChange) == null || r.call(n, E.Connecting, "livekit:reconnecting");
         break;
       case I.SignalReconnecting:
-        i("LiveKit room signal reconnecting..."), (c = n.onConnectionStateChange) == null || c.call(n, A.Connecting, "livekit:signal-reconnecting");
+        i("LiveKit room signal reconnecting..."), (c = n.onConnectionStateChange) == null || c.call(n, E.Connecting, "livekit:signal-reconnecting");
         break;
     }
   }
@@ -176,12 +176,12 @@ async function ln(f, S, u) {
           const ge = ((fe = (le = p == null ? void 0 : p.getReport()) == null ? void 0 : le.webRTCStats) == null ? void 0 : fe.avgRtt) ?? 0;
           F = ge > 0 ? Math.round(ge * 1e3) : 0;
         }
-        const D = V > 0 ? V + (h ?? 0) + F : void 0, w = D !== void 0 && m !== void 0 ? D - m : void 0;
-        (he = n.onFirstAudioDetected) == null || he.call(n, { latency: D, networkLatency: w });
+        const D = V > 0 ? V + (h ?? 0) + F : void 0, A = D !== void 0 && m !== void 0 ? D - m : void 0;
+        (he = n.onFirstAudioDetected) == null || he.call(n, { latency: D, networkLatency: A });
       }
-    )), e.kind === "video" && ((c = n.onStreamReady) == null || c.call(n), i("CALLBACK: onSrcObjectReady"), (d = n.onSrcObjectReady) == null || d.call(n, L), K || (K = !0, i("CALLBACK: onConnectionStateChange(Connected)"), (s = n.onConnectionStateChange) == null || s.call(n, A.Connected, "livekit:track-subscribed")), p = Ze(
+    )), e.kind === "video" && ((c = n.onStreamReady) == null || c.call(n), i("CALLBACK: onSrcObjectReady"), (d = n.onSrcObjectReady) == null || d.call(n, L), K || (K = !0, i("CALLBACK: onConnectionStateChange(Connected)"), (s = n.onConnectionStateChange) == null || s.call(n, E.Connected, "livekit:track-subscribed")), p = Ze(
       () => e.getRTCStatsReport(),
-      () => E,
+      () => w,
       en,
       (h, m) => {
         i(`Video state change: ${h}`), h === b.Start ? (R && (clearTimeout(R), R = null, i("Track subscription timeout cleared")), Pe()) : h === b.Stop && oe(m);
@@ -200,7 +200,7 @@ async function ln(f, S, u) {
     var o, r, c, d;
     if (e === l.ToolCallStarted) {
       const s = t;
-      v.set(s.call_id, {
+      y.set(s.call_id, {
         call: {
           callId: s.call_id,
           name: s.name,
@@ -222,24 +222,24 @@ async function ln(f, S, u) {
     }
   }
   function ae(e) {
-    v.delete(e) && (N(), z());
+    y.delete(e) && (N(), z());
   }
   function Ie(e) {
     let t = !1;
-    for (const [o, r] of v)
-      r.call.executionMode === "blocking" && (e !== null && r.turnId !== null && r.turnId !== e || (v.delete(o), t = !0));
+    for (const [o, r] of y)
+      r.call.executionMode === "blocking" && (e !== null && r.turnId !== null && r.turnId !== e || (y.delete(o), t = !0));
     t && (N(), z());
   }
   function N() {
     var t;
-    const e = ![...v.values()].some(({ call: o }) => o.executionMode === "blocking");
+    const e = ![...y.values()].some(({ call: o }) => o.executionMode === "blocking");
     e !== W && (W = e, (t = n.onInterruptibleChange) == null || t.call(n, e));
   }
   function z() {
     var e;
     (e = n.onRunningToolCallsChange) == null || e.call(
       n,
-      v.size === 0 ? cn : [...v.values()].map(({ call: t }) => t)
+      y.size === 0 ? cn : [...y.values()].map(({ call: t }) => t)
     );
   }
   function _e(e, t) {
@@ -251,7 +251,7 @@ async function ln(f, S, u) {
       });
       return;
     }
-    if (v.size > 0) {
+    if (y.size > 0) {
       M !== C.ToolActive && (M = C.ToolActive, (c = n.onAgentActivityStateChange) == null || c.call(n, C.ToolActive));
       return;
     }
@@ -320,11 +320,11 @@ async function ln(f, S, u) {
   }
   function Fe(e) {
     var t;
-    i("Media devices error:", e), (t = n.onError) == null || t.call(n, j(), { sessionId: y });
+    i("Media devices error:", e), (t = n.onError) == null || t.call(n, j(), { sessionId: v });
   }
   function Ue(e) {
     var t;
-    i("Encryption error:", e), (t = n.onError) == null || t.call(n, j(), { sessionId: y });
+    i("Encryption error:", e), (t = n.onError) == null || t.call(n, j(), { sessionId: v });
   }
   function je(e, t, o) {
     i("Track subscription failed:", { trackSid: e, participant: t, reason: o });
@@ -340,7 +340,7 @@ async function ln(f, S, u) {
   }
   async function se(e, t, o, r, c, d) {
     var V, F, D;
-    if (!E || !a)
+    if (!w || !a)
       throw i(`Room is not connected, cannot publish ${r} stream`), new Error("Room is not connected");
     if (e.isPublishing) {
       i(`${r} publish already in progress, skipping`);
@@ -358,14 +358,14 @@ async function ln(f, S, u) {
       return;
     }
     if ((D = e.publication) != null && D.track) {
-      const w = e.publication.track.mediaStreamTrack;
-      w !== h && (w == null ? void 0 : w.id) !== h.id && (i(`Unpublishing existing ${r} track before publishing new one`), await d());
+      const A = e.publication.track.mediaStreamTrack;
+      A !== h && (A == null ? void 0 : A.id) !== h.id && (i(`Unpublishing existing ${r} track before publishing new one`), await d());
     }
     i(`Publishing ${r} track from provided MediaStream`, { trackId: h.id }), e.isPublishing = !0;
     try {
       e.publication = await a.localParticipant.publishTrack(h, { source: r }), i(`${r} track published successfully`, { trackSid: e.publication.trackSid });
-    } catch (w) {
-      throw i(`Failed to publish ${r} track:`, w), w;
+    } catch (A) {
+      throw i(`Failed to publish ${r} track:`, A), A;
     } finally {
       e.isPublishing = !1;
     }
@@ -394,7 +394,7 @@ async function ln(f, S, u) {
     return ue(P, "Microphone");
   }
   async function ze(e) {
-    if (!E || !a)
+    if (!w || !a)
       throw i("Cannot replace microphone track: room is not connected"), new Error("Room is not connected");
     if (e.kind !== "audio")
       throw i("Cannot replace microphone track: not an audio track", { kind: e.kind }), new Error("Microphone track must be an audio track");
@@ -427,21 +427,21 @@ async function ln(f, S, u) {
   }
   async function Z(e, t) {
     var o, r;
-    if (!E || !a) {
+    if (!w || !a) {
       i("Room is not connected for sending messages"), (o = n.onError) == null || o.call(n, j(), {
-        sessionId: y
+        sessionId: v
       });
       return;
     }
     try {
       await a.localParticipant.sendText(t, { topic: e }), i("Message sent successfully:", t);
     } catch (c) {
-      i("Failed to send message:", c), (r = n.onError) == null || r.call(n, j(), { sessionId: y });
+      i("Failed to send message:", c), (r = n.onError) == null || r.call(n, j(), { sessionId: v });
     }
   }
   async function Y(e) {
     var t, o;
-    R && (clearTimeout(R), R = null), T == null || T.destroy(), T = null, a && ((t = n.onConnectionStateChange) == null || t.call(n, A.Disconnecting, e), await Promise.all([H(), X()]), await a.disconnect()), Je(), E = !1, K = !1, v.size > 0 && (v.clear(), N(), z()), x = null, (o = n.onAgentActivityStateChange) == null || o.call(n, C.Idle), M = C.Idle;
+    R && (clearTimeout(R), R = null), T == null || T.destroy(), T = null, a && ((t = n.onConnectionStateChange) == null || t.call(n, E.Disconnecting, e), await Promise.all([H(), X()]), await a.disconnect()), Je(), w = !1, K = !1, y.size > 0 && (y.clear(), N(), z()), x = null, (o = n.onAgentActivityStateChange) == null || o.call(n, C.Idle), M = C.Idle;
   }
   return {
     speak(e) {
@@ -457,9 +457,9 @@ async function ln(f, S, u) {
       }
       if (!a || !$ || !_)
         throw i("Cannot reconnect: missing room, URL or token"), new Error("Cannot reconnect: session not available");
-      i("Reconnecting to LiveKit room, state:", a.state), K = !1, q = null, (e = n.onConnectionStateChange) == null || e.call(n, A.Connecting, "user:reconnect");
+      i("Reconnecting to LiveKit room, state:", a.state), K = !1, q = null, (e = n.onConnectionStateChange) == null || e.call(n, E.Connecting, "user:reconnect");
       try {
-        if (await a.connect($, _), i("Room reconnected"), E = !0, a.remoteParticipants.size === 0) {
+        if (await a.connect($, _), i("Room reconnected"), w = !0, a.remoteParticipants.size === 0) {
           if (i("Waiting for agent to join..."), !await new Promise((r) => {
             const c = setTimeout(() => {
               a == null || a.off(g.ParticipantConnected, d), r(!1);
@@ -472,7 +472,7 @@ async function ln(f, S, u) {
           i("Agent joined, reconnection successful");
         }
       } catch (o) {
-        throw i("Failed to reconnect:", o), (t = n.onConnectionStateChange) == null || t.call(n, A.Fail, "user:reconnect-failed"), o;
+        throw i("Failed to reconnect:", o), (t = n.onConnectionStateChange) == null || t.call(n, E.Fail, "user:reconnect-failed"), o;
       }
     },
     sendDataChannelMessage: Z,
@@ -482,7 +482,7 @@ async function ln(f, S, u) {
     publishCameraStream: Be,
     unpublishCameraStream: X,
     interrupt(e) {
-      e !== "text" && Z(me.Interrupt, "");
+      return e === "text" || !w || !a ? !1 : (Z(me.Interrupt, ""), !0);
     },
     registerRpcMethod(e, t) {
       a == null || a.registerRpcMethod(e, t);
@@ -490,11 +490,14 @@ async function ln(f, S, u) {
     unregisterRpcMethod(e) {
       a == null || a.unregisterRpcMethod(e);
     },
-    sessionId: y,
-    streamId: y,
+    sessionId: v,
+    streamId: v,
     streamType: te,
     interruptAvailable: ie,
-    isInterruptible: W
+    // A getter, not a snapshot: currentInterruptible changes as blocking tool calls come and go.
+    get isInterruptible() {
+      return W;
+    }
   };
 }
 export {

package/dist/src/api/agents.d.ts

@@ -1,7 +1,7 @@
 import { Agent, Auth, Chat, ChatPayload, ChatResponse, RatingEntity, RatingPayload, STTTokenResponse, SubmitFeedbackResponse } from '../types/index';
 import { RequestOptions } from './apiClient';
 
-export declare function createAgentsApi(auth: Auth, host?: string, onError?: (error: Error, errorData: object) => void, externalId?: string): {
+export declare function createAgentsApi(auth: Auth, host?: string, onError?: (error: Error, errorData: Record<string, unknown>) => void, externalId?: string): {
     getRuntimeById(id: string, options?: RequestOptions): Promise<Agent>;
     newChat(agentId: string, payload: {
         persist: boolean;

package/dist/src/api/apiClient.d.ts

@@ -3,7 +3,7 @@ import { Auth } from '../types/auth';
 export type RequestOptions = RequestInit & {
     skipErrorHandler?: boolean;
 };
-export declare function createClient(auth: Auth, host?: string, onError?: (error: Error, errorData: object) => void, externalId?: string): {
+export declare function createClient(auth: Auth, host?: string, onError?: (error: Error, errorData: Record<string, unknown>) => void, externalId?: string): {
     get<T = any>(url: string, options?: RequestOptions): Promise<T>;
     post<T = any>(url: string, body?: any, options?: RequestOptions): Promise<T>;
     delete<T = any>(url: string, body?: any, options?: RequestOptions): Promise<T>;

package/dist/src/api/knowledge.d.ts

@@ -1,6 +1,6 @@
 import { Auth, CreateDocumentPayload, DocumentData, KnowledgeData, KnowledgePayload, QueryResult, RecordData } from '../types/index';
 
-export declare function createKnowledgeApi(auth: Auth, host?: string, onError?: (error: Error, errorData: object) => void): {
+export declare function createKnowledgeApi(auth: Auth, host?: string, onError?: (error: Error, errorData: Record<string, unknown>) => void): {
     createKnowledge(payload: KnowledgePayload, options?: RequestInit): Promise<KnowledgeData>;
     getKnowledgeBase(options?: RequestInit): Promise<KnowledgeData[]>;
     getKnowledge(knowledgeId: string, options?: RequestInit): Promise<KnowledgeData>;

package/dist/src/api/streams/streamApi.d.ts

@@ -1,3 +1,3 @@
 import { Auth, RtcApi } from '../../types/index';
 
-export declare function createStreamApi(auth: Auth, host: string, agentId: string, onError?: (error: Error, errorData: object) => void): RtcApi;
+export declare function createStreamApi(auth: Auth, host: string, agentId: string, onError?: (error: Error, errorData: Record<string, unknown>) => void): RtcApi;

package/dist/src/api/streams/streamsApiV2.d.ts

@@ -1,5 +1,5 @@
 import { Auth, CreateSessionV2Options, CreateSessionV2Response } from '../../types';
 
-export declare function createStreamApiV2(auth: Auth, host: string, agentId: string, onError?: (error: Error, errorData: object) => void): {
+export declare function createStreamApiV2(auth: Auth, host: string, agentId: string, onError?: (error: Error, errorData: Record<string, unknown>) => void): {
     createStream(options: CreateSessionV2Options): Promise<CreateSessionV2Response>;
 };

package/dist/src/errors/base-error.d.ts

@@ -1,13 +1,182 @@
+/**
+ * The JSON-safe payload {@link BaseError.toJson | toJson()} produces, for logs and error reports.
+ *
+ * Only the fields the SDK deliberately exposes are present, so the payload can be forwarded to a
+ * logging service as it is. Subclasses add their own keys: {@link HttpError} adds `httpStatus` and,
+ * when the failing call is known, `endpoint` and `method`; {@link NetworkError} adds `endpoint`,
+ * `method`, `durationMs`, `online` and `visibility`.
+ *
+ * @example An HttpError from a request that was refused
+ * ```json
+ * {
+ *     "kind": "InsufficientCreditsError",
+ *     "message": "Account has insufficient credits",
+ *     "httpStatus": 402,
+ *     "endpoint": "/agt_x/chat/cht_y",
+ *     "method": "POST"
+ * }
+ * ```
+ * @category Errors
+ */
 export interface ErrorJson {
+    /**
+     * Stable machine-readable code for the failure — the error's {@link BaseError.kind | kind}.
+     */
     kind: string;
+    /**
+     * Human-readable description of the failure — the error's `message`.
+     */
     message: string;
+    /**
+     * Message of the error that caused this one, truncated to 256 characters.
+     *
+     * Present only when {@link BaseError.originalError | originalError} is an `Error` and its
+     * message differs from {@link ErrorJson.message | message}. A cause that is not an `Error` is
+     * never serialized, so an arbitrary object carrying credentials cannot end up in the payload.
+     */
     cause?: string;
+    /**
+     * Additional fields contributed by a subclass, such as `httpStatus` on {@link HttpError}.
+     */
     [key: string]: any;
 }
+/**
+ * Base class of every error the SDK itself raises.
+ *
+ * Catching `BaseError` catches everything the SDK classified; branch on
+ * {@link BaseError.kind | kind}, which is stable, rather than on the message, which is not.
+ * Errors reach the application two ways, and each subclass says which applies: some are thrown to
+ * the caller of the method, so they reject the promise it returned; others are handed to
+ * {@link AgentManagerCallbacks.onError | onError} because no call of yours was in flight when they
+ * happened. {@link HttpError} and {@link NetworkError} do both — the request that failed rejects,
+ * and the callback is notified as well.
+ *
+ * Not everything that reaches the application is one of these. The streaming transport is the main
+ * exception: a failure LiveKit raises inside a media call on an Expressive (V4) agent — no
+ * microphone publication to replace, a room that is not connected — rejects with a plain `Error`,
+ * and so do a few low-level guards inside {@link AgentManager.connect | connect()}, such as a
+ * `livekit-client` package that is not installed, a transport the SDK does not recognise, or a
+ * stream the server created without a session id. An unknown
+ * {@link AgentManagerOptions.auth | auth} type is a plain `Error` too. So keep the
+ * `else throw error` branch in a handler built on {@link isDIDError}.
+ *
+ * Subclasses: {@link HttpError}, {@link NetworkError}, {@link WsError}, {@link StreamError},
+ * {@link ValidationError}, {@link ChatCreationFailed} and {@link ChatModeDowngraded}. When the
+ * caught value is typed `unknown`, {@link isDIDError} narrows it to this class.
+ *
+ * @category Errors
+ */
 export declare class BaseError extends Error {
+    /**
+     * Stable machine-readable code for this failure, and the value to branch on.
+     *
+     * Every subclass redeclares it as the literal it always carries, so a `switch` on `kind`
+     * narrows the caught error to that class: `'NetworkError'` on {@link NetworkError},
+     * `'WSError'` on {@link WsError}, `'StreamError'` on {@link StreamError},
+     * `'ValidationError'` on {@link ValidationError}, `'ChatCreationFailed'` on
+     * {@link ChatCreationFailed} and `'ChatModeDowngraded'` on {@link ChatModeDowngraded}.
+     * {@link HttpError} is the one that stays a plain `string`, because it reuses the server's
+     * own classification when the response carries one and is `'HttpError'` otherwise. On a
+     * `BaseError` built directly it is whatever the caller passed, and `'Error'` when nothing
+     * was.
+     */
     readonly kind: string;
+    /**
+     * The error or value that caused this one, when the SDK was wrapping something else.
+     *
+     * For a {@link NetworkError} this is the browser's own `fetch` rejection. It is not
+     * serialized as-is: {@link BaseError.toJson | toJson()} takes only an `Error` cause's
+     * message.
+     */
     readonly originalError?: unknown | undefined;
-    constructor(message: string, kind?: string, originalError?: unknown | undefined);
+    /**
+     * Creates an SDK error. The SDK builds these itself; applications normally only catch them.
+     *
+     * @param message - Human-readable description of the failure, used as the `Error` message.
+     * @param kind - Stable machine-readable code for the failure.
+     * @param originalError - The underlying error or value this one wraps, when there is one.
+     */
+    constructor(message: string, 
+    /**
+     * Stable machine-readable code for this failure, and the value to branch on.
+     *
+     * Every subclass redeclares it as the literal it always carries, so a `switch` on `kind`
+     * narrows the caught error to that class: `'NetworkError'` on {@link NetworkError},
+     * `'WSError'` on {@link WsError}, `'StreamError'` on {@link StreamError},
+     * `'ValidationError'` on {@link ValidationError}, `'ChatCreationFailed'` on
+     * {@link ChatCreationFailed} and `'ChatModeDowngraded'` on {@link ChatModeDowngraded}.
+     * {@link HttpError} is the one that stays a plain `string`, because it reuses the server's
+     * own classification when the response carries one and is `'HttpError'` otherwise. On a
+     * `BaseError` built directly it is whatever the caller passed, and `'Error'` when nothing
+     * was.
+     */
+    kind?: string, 
+    /**
+     * The error or value that caused this one, when the SDK was wrapping something else.
+     *
+     * For a {@link NetworkError} this is the browser's own `fetch` rejection. It is not
+     * serialized as-is: {@link BaseError.toJson | toJson()} takes only an `Error` cause's
+     * message.
+     */
+    originalError?: unknown | undefined);
+    /**
+     * Serializes the error into the JSON-safe {@link ErrorJson} payload for logging or reporting.
+     *
+     * The payload always carries {@link BaseError.kind | kind} and the message. The cause's message
+     * is added only when {@link BaseError.originalError | originalError} is an `Error` and says
+     * something the message does not, truncated to 256 characters; any other cause is dropped.
+     * Subclasses extend the payload with the fields listed on their own pages.
+     *
+     * @returns The error as plain, JSON-serializable data.
+     * @example An HttpError from a request that was refused
+     * ```json
+     * {
+     *     "kind": "InsufficientCreditsError",
+     *     "message": "Account has insufficient credits",
+     *     "httpStatus": 402,
+     *     "endpoint": "/agt_x/chat/cht_y",
+     *     "method": "POST"
+     * }
+     * ```
+     * @example A NetworkError from a request that never left the browser
+     * ```json
+     * {
+     *     "kind": "NetworkError",
+     *     "message": "Network request failed",
+     *     "cause": "Failed to fetch",
+     *     "endpoint": "/agt_x/chat/cht_y",
+     *     "method": "POST",
+     *     "durationMs": 12,
+     *     "online": false,
+     *     "visibility": "visible"
+     * }
+     * ```
+     */
     toJson(): ErrorJson;
 }
+/**
+ * Type guard that reports whether a caught value is an error raised by the SDK.
+ *
+ * It accepts any `Error` carrying a string `kind`, which every {@link BaseError} has, so it also
+ * recognizes SDK errors that crossed a bundle boundary, where `instanceof BaseError` can fail
+ * because two copies of the class are loaded. Narrowing with it gives typed access to
+ * {@link BaseError.kind | kind}, {@link BaseError.originalError | originalError} and
+ * {@link BaseError.toJson | toJson()}.
+ *
+ * @param error - The caught value to test.
+ * @returns `true` when `error` is a {@link BaseError}.
+ * @example
+ * ```ts
+ * try {
+ *     await agentManager.chat('What is the distance to the moon?');
+ * } catch (error) {
+ *     if (isDIDError(error)) {
+ *         console.error(error.kind, error.toJson());
+ *     } else {
+ *         throw error;
+ *     }
+ * }
+ * ```
+ * @category Errors
+ */
 export declare function isDIDError(error: unknown): error is BaseError;

package/dist/src/errors/chat/chat-creation-failed.d.ts

@@ -1,6 +1,30 @@
 import { ChatMode } from '../../types';
 import { BaseError } from '../base-error';
 
+/**
+ * A chat could not be created for the session.
+ *
+ * {@link AgentManager.chat | chat()} creates a chat on the first message when the session does not
+ * have one yet; this error is thrown when that call comes back without one, so it rejects the
+ * promise `chat()` returned and the user's message is not sent. It is not delivered to
+ * {@link AgentManagerCallbacks.onError | onError} — catch it around `chat()`. A failing request
+ * surfaces as {@link HttpError} or {@link NetworkError} instead; this error is the case where the
+ * request succeeded but produced no chat.
+ *
+ * The message names the {@link ChatMode} in effect and whether a persistent chat was asked for, for
+ * example `Failed to create persistent chat, mode: Functional`.
+ * {@link BaseError.kind | kind} is `'ChatCreationFailed'`.
+ *
+ * @category Errors
+ */
 export declare class ChatCreationFailed extends BaseError {
+    /**
+     * Always `'ChatCreationFailed'`. Branch on it to tell this failure from the other SDK errors.
+     */
+    readonly kind: 'ChatCreationFailed';
+    /**
+     * Builds the error from the attempt that failed.
+     * @internal The SDK builds this itself; applications catch the error rather than construct it.
+     */
     constructor(mode: ChatMode, persistent: boolean);
 }

package/dist/src/errors/chat/chat-mode-downgraded.d.ts

@@ -1,6 +1,35 @@
 import { ChatMode } from '../../types';
 import { BaseError } from '../base-error';
 
+/**
+ * The server put the session into a different chat mode from the one that was requested, and the
+ * new mode cannot stream video.
+ *
+ * Raised while {@link AgentManager.connect | connect()} runs, when the chat the server created came
+ * back in a mode other than the requested {@link AgentManagerOptions.mode | mode} and that mode is
+ * not {@link ChatMode.Functional | Functional} — {@link ChatMode.TextOnly | TextOnly} or
+ * {@link ChatMode.Maintenance | Maintenance}, for instance. The comparison only runs when `mode` was
+ * set in the options, so a session that never asked for a mode never sees this error. The SDK
+ * disconnects the stream it had just opened and `connect()` resolves anyway, so no video will play
+ * and {@link AgentManagerCallbacks.onSrcObjectReady | onSrcObjectReady} will not fire again: the
+ * session continues as a text chat.
+ *
+ * It is delivered to {@link AgentManagerCallbacks.onError | onError} and never thrown, so
+ * `connect()` does not reject on it.
+ * {@link AgentManagerCallbacks.onModeChange | onModeChange} fires with the new mode just before it.
+ * Treat it as a signal to switch the interface to text, not as a connection failure.
+ * {@link BaseError.kind | kind} is `'ChatModeDowngraded'`.
+ *
+ * @category Errors
+ */
 export declare class ChatModeDowngraded extends BaseError {
+    /**
+     * Always `'ChatModeDowngraded'`. Branch on it to tell this failure from the other SDK errors.
+     */
+    readonly kind: 'ChatModeDowngraded';
+    /**
+     * Builds the error from the mode the session ended up in.
+     * @internal The SDK builds this itself; applications catch the error rather than construct it.
+     */
     constructor(mode: ChatMode);
 }