@convai/web-sdk 1.8.0-beta.7 → 1.8.0

package/dist/core/CharacterVersionManager.js

@@ -1,227 +0,0 @@
-import { isCharacterVersionSelector, parseCharacterReference, } from "./characterReference.js";
-export const DEFAULT_CHARACTER_API_URL = "https://api2.convai.com";
-/**
- * Error raised when the Character REST platform answers with a non-2xx
- * status. `status` carries the HTTP code; `detail` carries the parsed body
- * (`{ detail: string }` for most failures, a validation list for 422).
- */
-export class CharacterApiError extends Error {
-    constructor(message, status, detail) {
-        super(message);
-        this.name = "CharacterApiError";
-        this.status = status;
-        this.detail = detail;
-    }
-}
-/**
- * Authoring client for character versions.
- *
- * Every character has an editable **draft** and, once released, a set of
- * immutable **tagged versions** (`1.0`, `1.1`, …). `latest` is a movable
- * pointer that the runtime follows when a client connects without a
- * selector. The lifecycle is:
- *
- * 1. edit the draft (Playground, `/character/update`, MCP);
- * 2. {@link diff} the draft against `latest` to review the change;
- * 3. {@link create} a tag from the draft, optionally making it latest;
- * 4. {@link promote} an older tag to roll back, or {@link discardDraft} to
- *    throw unreleased edits away.
- *
- * Connect to any of these with `characterVersion` in `ConvaiConfig`.
- *
- * @example
- * ```typescript
- * const versions = new CharacterVersionManager({
- *   apiKey: 'YOUR_API_KEY',
- *   characterId: 'YOUR_CHARACTER_ID',
- * });
- * const { has_unpublished_changes } = await versions.list();
- * if (has_unpublished_changes) {
- *   await versions.create('1.1', { makeLatest: true });
- * }
- * ```
- */
-export class CharacterVersionManager {
-    constructor(options) {
-        const { characterId, apiKey, personalAccessToken, baseUrl, workspaceId } = options;
-        if (!characterId) {
-            throw new Error("Character ID is required");
-        }
-        if (!apiKey && !personalAccessToken) {
-            throw new Error("Either apiKey or personalAccessToken is required");
-        }
-        // Accept a suffixed reference but talk to the API about the bare character.
-        this.characterId = parseCharacterReference(characterId)?.characterId ?? characterId;
-        this.apiKey = apiKey ?? null;
-        this.personalAccessToken = personalAccessToken ?? null;
-        this.baseUrl = (baseUrl || DEFAULT_CHARACTER_API_URL).replace(/\/$/, "");
-        this.workspaceId = workspaceId ?? null;
-    }
-    /** List released tags plus the current latest and draft revisions. */
-    async list() {
-        return this.request("GET", "/character/versions/list");
-    }
-    /**
-     * Resolve a reference to the configuration snapshot the runtime would run.
-     * Omit `version` to resolve the effective latest, or pass `draft`,
-     * `latest`, or a tag.
-     */
-    async resolve(version, options = {}) {
-        const reference = version ? `${this.characterId}-${this.assertSelector(version)}` : this.characterId;
-        return this.request("GET", "/character/versions/resolve", {
-            query: {
-                character_id: reference,
-                ...(options.includeRuntimeSettings ? { include_runtime_settings: "true" } : {}),
-            },
-        });
-    }
-    /**
-     * Give a character that predates versioning an editable draft. Safe to call
-     * repeatedly — `created` is false when a draft already existed.
-     */
-    async bootstrap() {
-        return this.request("POST", "/character/versions/bootstrap");
-    }
-    async diff(from, to, options = {}) {
-        return this.request("GET", "/character/versions/diff", {
-            query: {
-                from: this.assertSelector(from),
-                to: this.assertSelector(to),
-                ...(options.view ? { view: options.view } : {}),
-            },
-        });
-    }
-    /**
-     * Release the current draft as an immutable tagged version.
-     * @param version - New tag, `major.minor` or `major.minor.patch`
-     */
-    async create(version, options = {}) {
-        return this.request("POST", "/character/versions/create", {
-            body: {
-                version: this.assertTag(version),
-                ...(options.makeLatest !== undefined ? { make_latest: options.makeLatest } : {}),
-            },
-        });
-    }
-    /** Point `latest` at an already released tag — the way to roll back. */
-    async promote(version) {
-        return this.request("POST", "/character/versions/promote", {
-            body: { version: this.assertTag(version) },
-        });
-    }
-    /**
-     * Discard every saved draft change and restore the draft from its released
-     * parent. Pass the draft revision you last saw so a concurrent edit is
-     * refused instead of silently thrown away.
-     */
-    async discardDraft(expectedDraftRevisionId) {
-        if (!expectedDraftRevisionId) {
-            throw new Error("expectedDraftRevisionId is required");
-        }
-        return this.request("POST", "/character/versions/discard-draft", {
-            body: { expected_draft_revision_id: expectedDraftRevisionId },
-        });
-    }
-    /** Undo one semantic change in the draft, identified by a semantic diff's `change_id`. */
-    async revert(options) {
-        const { from, changeId, expectedDraftRevisionId } = options;
-        if (!changeId || !expectedDraftRevisionId) {
-            throw new Error("changeId and expectedDraftRevisionId are required");
-        }
-        return this.request("POST", "/character/versions/revert", {
-            body: {
-                from: this.assertSelector(from),
-                change_id: changeId,
-                expected_draft_revision_id: expectedDraftRevisionId,
-            },
-        });
-    }
-    /** Mark a tag deprecated, or restore it with `deprecated: false`. Deprecated tags stay connectable. */
-    async deprecate(version, deprecated = true) {
-        return this.request("POST", "/character/versions/deprecate", {
-            body: { version: this.assertTag(version), deprecated },
-        });
-    }
-    /**
-     * Replace the draft with the contents of a released tag, to branch new work
-     * from an older version. `expectedDraftRevisionId` guards against clobbering
-     * a draft someone else just changed.
-     */
-    async fork(version, expectedDraftRevisionId) {
-        return this.request("POST", "/character/versions/fork", {
-            body: {
-                version: this.assertTag(version),
-                ...(expectedDraftRevisionId ? { expected_draft_revision_id: expectedDraftRevisionId } : {}),
-            },
-        });
-    }
-    assertSelector(value) {
-        if (!isCharacterVersionSelector(value)) {
-            throw new Error(`Expected "draft", "latest", or a major.minor[.patch] tag; received ${JSON.stringify(value)}`);
-        }
-        return value;
-    }
-    assertTag(value) {
-        if (!isCharacterVersionSelector(value) || value === "draft" || value === "latest") {
-            throw new Error(`Expected a major.minor[.patch] version tag; received ${JSON.stringify(value)}`);
-        }
-        return value;
-    }
-    async request(method, path, options = {}) {
-        const params = new URLSearchParams({
-            character_id: this.characterId,
-            ...(this.workspaceId ? { workspace_id: this.workspaceId } : {}),
-            ...options.query,
-        });
-        const url = `${this.baseUrl}${path}?${params.toString()}`;
-        const headers = { Accept: "application/json" };
-        if (this.personalAccessToken) {
-            headers["Authorization"] = `Bearer ${this.personalAccessToken}`;
-        }
-        else if (this.apiKey) {
-            headers["CONVAI-API-KEY"] = this.apiKey;
-        }
-        if (options.body !== undefined) {
-            headers["Content-Type"] = "application/json";
-        }
-        const response = await fetch(url, {
-            method,
-            headers,
-            ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
-        });
-        const text = await response.text();
-        let data = null;
-        if (text) {
-            try {
-                data = JSON.parse(text);
-            }
-            catch {
-                data = text;
-            }
-        }
-        if (!response.ok) {
-            throw new CharacterApiError(describeFailure(response.status, data), response.status, data);
-        }
-        return data;
-    }
-}
-function describeFailure(status, data) {
-    const body = (data ?? null);
-    const detail = body?.detail;
-    if (typeof detail === "string")
-        return detail;
-    // Access denials use `{ error, message }` rather than `{ detail }`.
-    if (typeof body?.message === "string")
-        return body.message;
-    if (Array.isArray(detail)) {
-        const parts = detail
-            .map((e) => [e.loc?.join("."), e.msg].filter(Boolean).join(": "))
-            .filter(Boolean);
-        if (parts.length)
-            return parts.join("; ");
-    }
-    if (typeof data === "string" && data)
-        return `HTTP ${status}: ${data}`;
-    return `HTTP ${status}`;
-}
-//# sourceMappingURL=CharacterVersionManager.js.map

package/dist/core/CharacterVersionManager.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"CharacterVersionManager.js","sourceRoot":"","sources":["../../src/core/CharacterVersionManager.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CharacterDraftBootstrapResult,\n  CharacterVersionDiff,\n  CharacterVersionDiffOptions,\n  CharacterVersionInfo,\n  CharacterVersionList,\n  CharacterVersionManagerOptions,\n  CharacterVersionRawDiff,\n  CharacterVersionSemanticDiff,\n  CreateCharacterVersionOptions,\n  DiscardCharacterDraftResult,\n  ForkCharacterVersionResult,\n  ResolveCharacterVersionOptions,\n  ResolvedCharacterVersion,\n  RevertCharacterChangeOptions,\n  RevertCharacterChangeResult,\n} from \"./types\";\nimport {\n  isCharacterVersionSelector,\n  parseCharacterReference,\n  type CharacterVersionSelector,\n} from \"./characterReference\";\n\nexport const DEFAULT_CHARACTER_API_URL = \"https://api2.convai.com\";\n\n/**\n * Error raised when the Character REST platform answers with a non-2xx\n * status. `status` carries the HTTP code; `detail` carries the parsed body\n * (`{ detail: string }` for most failures, a validation list for 422).\n */\nexport class CharacterApiError extends Error {\n  readonly status: number;\n  readonly detail: unknown;\n\n  constructor(message: string, status: number, detail: unknown) {\n    super(message);\n    this.name = \"CharacterApiError\";\n    this.status = status;\n    this.detail = detail;\n  }\n}\n\n/**\n * Authoring client for character versions.\n *\n * Every character has an editable **draft** and, once released, a set of\n * immutable **tagged versions** (`1.0`, `1.1`, …). `latest` is a movable\n * pointer that the runtime follows when a client connects without a\n * selector. The lifecycle is:\n *\n * 1. edit the draft (Playground, `/character/update`, MCP);\n * 2. {@link diff} the draft against `latest` to review the change;\n * 3. {@link create} a tag from the draft, optionally making it latest;\n * 4. {@link promote} an older tag to roll back, or {@link discardDraft} to\n *    throw unreleased edits away.\n *\n * Connect to any of these with `characterVersion` in `ConvaiConfig`.\n *\n * @example\n * ```typescript\n * const versions = new CharacterVersionManager({\n *   apiKey: 'YOUR_API_KEY',\n *   characterId: 'YOUR_CHARACTER_ID',\n * });\n * const { has_unpublished_changes } = await versions.list();\n * if (has_unpublished_changes) {\n *   await versions.create('1.1', { makeLatest: true });\n * }\n * ```\n */\nexport class CharacterVersionManager {\n  private readonly apiKey: string | null;\n  private readonly personalAccessToken: string | null;\n  private readonly baseUrl: string;\n  private readonly workspaceId: string | null;\n  readonly characterId: string;\n\n  constructor(options: CharacterVersionManagerOptions) {\n    const { characterId, apiKey, personalAccessToken, baseUrl, workspaceId } = options;\n    if (!characterId) {\n      throw new Error(\"Character ID is required\");\n    }\n    if (!apiKey && !personalAccessToken) {\n      throw new Error(\"Either apiKey or personalAccessToken is required\");\n    }\n    // Accept a suffixed reference but talk to the API about the bare character.\n    this.characterId = parseCharacterReference(characterId)?.characterId ?? characterId;\n    this.apiKey = apiKey ?? null;\n    this.personalAccessToken = personalAccessToken ?? null;\n    this.baseUrl = (baseUrl || DEFAULT_CHARACTER_API_URL).replace(/\\/$/, \"\");\n    this.workspaceId = workspaceId ?? null;\n  }\n\n  /** List released tags plus the current latest and draft revisions. */\n  async list(): Promise<CharacterVersionList> {\n    return this.request<CharacterVersionList>(\"GET\", \"/character/versions/list\");\n  }\n\n  /**\n   * Resolve a reference to the configuration snapshot the runtime would run.\n   * Omit `version` to resolve the effective latest, or pass `draft`,\n   * `latest`, or a tag.\n   */\n  async resolve(\n    version?: CharacterVersionSelector | null,\n    options: ResolveCharacterVersionOptions = {},\n  ): Promise<ResolvedCharacterVersion> {\n    const reference = version ? `${this.characterId}-${this.assertSelector(version)}` : this.characterId;\n    return this.request<ResolvedCharacterVersion>(\"GET\", \"/character/versions/resolve\", {\n      query: {\n        character_id: reference,\n        ...(options.includeRuntimeSettings ? { include_runtime_settings: \"true\" } : {}),\n      },\n    });\n  }\n\n  /**\n   * Give a character that predates versioning an editable draft. Safe to call\n   * repeatedly — `created` is false when a draft already existed.\n   */\n  async bootstrap(): Promise<CharacterDraftBootstrapResult> {\n    return this.request<CharacterDraftBootstrapResult>(\"POST\", \"/character/versions/bootstrap\");\n  }\n\n  /**\n   * Compare two references. Each side is `draft`, `latest`, or a tag.\n   * The raw view lists JSON paths; the semantic view groups them into\n   * labelled changes that {@link revert} can undo one at a time.\n   */\n  diff(from: string, to: string, options?: { view?: \"raw\" }): Promise<CharacterVersionRawDiff>;\n  diff(from: string, to: string, options: { view: \"semantic\" }): Promise<CharacterVersionSemanticDiff>;\n  async diff(from: string, to: string, options: CharacterVersionDiffOptions = {}): Promise<CharacterVersionDiff> {\n    return this.request<CharacterVersionDiff>(\"GET\", \"/character/versions/diff\", {\n      query: {\n        from: this.assertSelector(from),\n        to: this.assertSelector(to),\n        ...(options.view ? { view: options.view } : {}),\n      },\n    });\n  }\n\n  /**\n   * Release the current draft as an immutable tagged version.\n   * @param version - New tag, `major.minor` or `major.minor.patch`\n   */\n  async create(version: string, options: CreateCharacterVersionOptions = {}): Promise<CharacterVersionInfo> {\n    return this.request<CharacterVersionInfo>(\"POST\", \"/character/versions/create\", {\n      body: {\n        version: this.assertTag(version),\n        ...(options.makeLatest !== undefined ? { make_latest: options.makeLatest } : {}),\n      },\n    });\n  }\n\n  /** Point `latest` at an already released tag — the way to roll back. */\n  async promote(version: string): Promise<CharacterVersionInfo> {\n    return this.request<CharacterVersionInfo>(\"POST\", \"/character/versions/promote\", {\n      body: { version: this.assertTag(version) },\n    });\n  }\n\n  /**\n   * Discard every saved draft change and restore the draft from its released\n   * parent. Pass the draft revision you last saw so a concurrent edit is\n   * refused instead of silently thrown away.\n   */\n  async discardDraft(expectedDraftRevisionId: string): Promise<DiscardCharacterDraftResult> {\n    if (!expectedDraftRevisionId) {\n      throw new Error(\"expectedDraftRevisionId is required\");\n    }\n    return this.request<DiscardCharacterDraftResult>(\"POST\", \"/character/versions/discard-draft\", {\n      body: { expected_draft_revision_id: expectedDraftRevisionId },\n    });\n  }\n\n  /** Undo one semantic change in the draft, identified by a semantic diff's `change_id`. */\n  async revert(options: RevertCharacterChangeOptions): Promise<RevertCharacterChangeResult> {\n    const { from, changeId, expectedDraftRevisionId } = options;\n    if (!changeId || !expectedDraftRevisionId) {\n      throw new Error(\"changeId and expectedDraftRevisionId are required\");\n    }\n    return this.request<RevertCharacterChangeResult>(\"POST\", \"/character/versions/revert\", {\n      body: {\n        from: this.assertSelector(from),\n        change_id: changeId,\n        expected_draft_revision_id: expectedDraftRevisionId,\n      },\n    });\n  }\n\n  /** Mark a tag deprecated, or restore it with `deprecated: false`. Deprecated tags stay connectable. */\n  async deprecate(version: string, deprecated = true): Promise<CharacterVersionInfo> {\n    return this.request<CharacterVersionInfo>(\"POST\", \"/character/versions/deprecate\", {\n      body: { version: this.assertTag(version), deprecated },\n    });\n  }\n\n  /**\n   * Replace the draft with the contents of a released tag, to branch new work\n   * from an older version. `expectedDraftRevisionId` guards against clobbering\n   * a draft someone else just changed.\n   */\n  async fork(version: string, expectedDraftRevisionId?: string): Promise<ForkCharacterVersionResult> {\n    return this.request<ForkCharacterVersionResult>(\"POST\", \"/character/versions/fork\", {\n      body: {\n        version: this.assertTag(version),\n        ...(expectedDraftRevisionId ? { expected_draft_revision_id: expectedDraftRevisionId } : {}),\n      },\n    });\n  }\n\n  private assertSelector(value: string): string {\n    if (!isCharacterVersionSelector(value)) {\n      throw new Error(\n        `Expected \"draft\", \"latest\", or a major.minor[.patch] tag; received ${JSON.stringify(value)}`,\n      );\n    }\n    return value;\n  }\n\n  private assertTag(value: string): string {\n    if (!isCharacterVersionSelector(value) || value === \"draft\" || value === \"latest\") {\n      throw new Error(\n        `Expected a major.minor[.patch] version tag; received ${JSON.stringify(value)}`,\n      );\n    }\n    return value;\n  }\n\n  private async request<T>(\n    method: \"GET\" | \"POST\",\n    path: string,\n    options: { query?: Record<string, string>; body?: unknown } = {},\n  ): Promise<T> {\n    const params = new URLSearchParams({\n      character_id: this.characterId,\n      ...(this.workspaceId ? { workspace_id: this.workspaceId } : {}),\n      ...options.query,\n    });\n    const url = `${this.baseUrl}${path}?${params.toString()}`;\n\n    const headers: Record<string, string> = { Accept: \"application/json\" };\n    if (this.personalAccessToken) {\n      headers[\"Authorization\"] = `Bearer ${this.personalAccessToken}`;\n    } else if (this.apiKey) {\n      headers[\"CONVAI-API-KEY\"] = this.apiKey;\n    }\n    if (options.body !== undefined) {\n      headers[\"Content-Type\"] = \"application/json\";\n    }\n\n    const response = await fetch(url, {\n      method,\n      headers,\n      ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),\n    });\n\n    const text = await response.text();\n    let data: unknown = null;\n    if (text) {\n      try {\n        data = JSON.parse(text);\n      } catch {\n        data = text;\n      }\n    }\n\n    if (!response.ok) {\n      throw new CharacterApiError(describeFailure(response.status, data), response.status, data);\n    }\n    return data as T;\n  }\n}\n\nfunction describeFailure(status: number, data: unknown): string {\n  const body = (data ?? null) as { detail?: unknown; message?: unknown; error?: unknown } | null;\n  const detail = body?.detail;\n  if (typeof detail === \"string\") return detail;\n  // Access denials use `{ error, message }` rather than `{ detail }`.\n  if (typeof body?.message === \"string\") return body.message;\n  if (Array.isArray(detail)) {\n    const parts = detail\n      .map((e: { loc?: unknown[]; msg?: string }) =>\n        [e.loc?.join(\".\"), e.msg].filter(Boolean).join(\": \"),\n      )\n      .filter(Boolean);\n    if (parts.length) return parts.join(\"; \");\n  }\n  if (typeof data === \"string\" && data) return `HTTP ${status}: ${data}`;\n  return `HTTP ${status}`;\n}\n"]}

package/dist/core/ConvaiRoomError.d.ts

@@ -1,48 +0,0 @@
-/**
- * Typed failure from a room-topology request (`connect()` with a roster, or
- * `joinRoom()`).
- *
- * The runtime answers these with a named code and a `request_trace_id`, and the
- * backend's whole troubleshooting procedure starts from that trace id — it
- * correlates API logs, room records, membership rows, actor logs and LiveKit.
- * A plain `Error` throws it away, so this class carries it through to the
- * caller alongside the status and the machine-readable code.
- */
-export declare class ConvaiRoomError extends Error {
-    readonly status: number;
-    /** Named code such as `ROSTER_FINGERPRINT_MISMATCH`, or null when the body carried none. */
-    readonly code: string | null;
-    /** Quote this to backend support; it correlates every log for the request. */
-    readonly requestTraceId: string | null;
-    /** The parsed response body, or the raw text when it was not JSON. */
-    readonly detail: unknown;
-    constructor(message: string, status: number, code: string | null, requestTraceId: string | null, detail: unknown);
-    /**
-     * True when retrying the identical payload can plausibly succeed.
-     *
-     * Only the two "still working on it" conflicts qualify. A fingerprint
-     * mismatch means the topology genuinely differs, and a capacity or
-     * entitlement rejection will not change on its own — retrying those just
-     * burns the room's provisioning window.
-     */
-    get isRetryable(): boolean;
-}
-/**
- * Pull a named code out of a parsed error body.
- *
- * The runtime is not consistent about where it puts one: some rejections carry
- * `{ code }`, some put the name in `detail` as a bare string, and some nest it
- * under `detail.code`. A code is never synthesised from the status — callers
- * branch on it, and inventing `"CONFLICT"` for every 409 would make
- * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`
- * indistinguishable, which is exactly the distinction that decides whether to
- * retry.
- */
-export declare function extractRoomErrorCode(body: unknown): string | null;
-/** Pull the trace id out of a parsed body, wherever the layer put it. */
-export declare function extractRequestTraceId(body: unknown): string | null;
-/** Human-readable message from a body, falling back to the status. */
-export declare function extractRoomErrorMessage(body: unknown, status: number): string;
-/** Build a `ConvaiRoomError` from a response status and its parsed body. */
-export declare function roomErrorFromResponse(status: number, body: unknown): ConvaiRoomError;
-//# sourceMappingURL=ConvaiRoomError.d.ts.map

package/dist/core/ConvaiRoomError.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ConvaiRoomError.d.ts","sourceRoot":"","sources":["../../src/core/ConvaiRoomError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAGvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,MAAM,EAAE,OAAO;IAUjB;;;;;;;OAOG;IACH,IAAI,WAAW,IAAI,OAAO,CAMzB;CACF;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBjE;AAUD,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUlE;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAc7E;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,GACZ,eAAe,CAQjB"}

package/dist/core/ConvaiRoomError.js

@@ -1,111 +0,0 @@
-/**
- * Typed failure from a room-topology request (`connect()` with a roster, or
- * `joinRoom()`).
- *
- * The runtime answers these with a named code and a `request_trace_id`, and the
- * backend's whole troubleshooting procedure starts from that trace id — it
- * correlates API logs, room records, membership rows, actor logs and LiveKit.
- * A plain `Error` throws it away, so this class carries it through to the
- * caller alongside the status and the machine-readable code.
- */
-export class ConvaiRoomError extends Error {
-    constructor(message, status, code, requestTraceId, detail) {
-        super(message);
-        this.name = "ConvaiRoomError";
-        this.status = status;
-        this.code = code;
-        this.requestTraceId = requestTraceId;
-        this.detail = detail;
-    }
-    /**
-     * True when retrying the identical payload can plausibly succeed.
-     *
-     * Only the two "still working on it" conflicts qualify. A fingerprint
-     * mismatch means the topology genuinely differs, and a capacity or
-     * entitlement rejection will not change on its own — retrying those just
-     * burns the room's provisioning window.
-     */
-    get isRetryable() {
-        if (this.status !== 409)
-            return false;
-        return (this.code === "ROSTER_PROVISIONING_IN_PROGRESS" ||
-            this.code === "CONNECT_ATTEMPT_IN_PROGRESS");
-    }
-}
-/** Response bodies differ by layer; a code can arrive under any of these. */
-const CODE_KEYS = ["code", "error_code", "detail_code"];
-/**
- * Pull a named code out of a parsed error body.
- *
- * The runtime is not consistent about where it puts one: some rejections carry
- * `{ code }`, some put the name in `detail` as a bare string, and some nest it
- * under `detail.code`. A code is never synthesised from the status — callers
- * branch on it, and inventing `"CONFLICT"` for every 409 would make
- * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`
- * indistinguishable, which is exactly the distinction that decides whether to
- * retry.
- */
-export function extractRoomErrorCode(body) {
-    if (typeof body === "string")
-        return looksLikeCode(body) ? body : null;
-    if (typeof body !== "object" || body === null)
-        return null;
-    const record = body;
-    for (const key of CODE_KEYS) {
-        const value = record[key];
-        if (typeof value === "string" && value)
-            return value;
-    }
-    const detail = record.detail;
-    if (typeof detail === "string")
-        return looksLikeCode(detail) ? detail : null;
-    if (typeof detail === "object" && detail !== null) {
-        return extractRoomErrorCode(detail);
-    }
-    return null;
-}
-/**
- * A code is SCREAMING_SNAKE_CASE. `detail` is also where human prose lands
- * ("Human room capacity reached"), so shape is what tells the two apart.
- */
-function looksLikeCode(value) {
-    return /^[A-Z][A-Z0-9_]{2,}$/.test(value.trim());
-}
-/** Pull the trace id out of a parsed body, wherever the layer put it. */
-export function extractRequestTraceId(body) {
-    if (typeof body !== "object" || body === null)
-        return null;
-    const record = body;
-    const direct = record.request_trace_id;
-    if (typeof direct === "string" && direct)
-        return direct;
-    const detail = record.detail;
-    if (typeof detail === "object" && detail !== null) {
-        return extractRequestTraceId(detail);
-    }
-    return null;
-}
-/** Human-readable message from a body, falling back to the status. */
-export function extractRoomErrorMessage(body, status) {
-    if (typeof body === "string" && body.trim())
-        return body.trim();
-    if (typeof body === "object" && body !== null) {
-        const record = body;
-        for (const key of ["message", "detail", "error"]) {
-            const value = record[key];
-            if (typeof value === "string" && value.trim())
-                return value.trim();
-            if (typeof value === "object" && value !== null) {
-                const nested = extractRoomErrorMessage(value, status);
-                if (!nested.startsWith("Room request failed"))
-                    return nested;
-            }
-        }
-    }
-    return `Room request failed with HTTP ${status}`;
-}
-/** Build a `ConvaiRoomError` from a response status and its parsed body. */
-export function roomErrorFromResponse(status, body) {
-    return new ConvaiRoomError(extractRoomErrorMessage(body, status), status, extractRoomErrorCode(body), extractRequestTraceId(body), body);
-}
-//# sourceMappingURL=ConvaiRoomError.js.map

package/dist/core/ConvaiRoomError.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ConvaiRoomError.js","sourceRoot":"","sources":["../../src/core/ConvaiRoomError.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed failure from a room-topology request (`connect()` with a roster, or\n * `joinRoom()`).\n *\n * The runtime answers these with a named code and a `request_trace_id`, and the\n * backend's whole troubleshooting procedure starts from that trace id — it\n * correlates API logs, room records, membership rows, actor logs and LiveKit.\n * A plain `Error` throws it away, so this class carries it through to the\n * caller alongside the status and the machine-readable code.\n */\nexport class ConvaiRoomError extends Error {\n  readonly status: number;\n  /** Named code such as `ROSTER_FINGERPRINT_MISMATCH`, or null when the body carried none. */\n  readonly code: string | null;\n  /** Quote this to backend support; it correlates every log for the request. */\n  readonly requestTraceId: string | null;\n  /** The parsed response body, or the raw text when it was not JSON. */\n  readonly detail: unknown;\n\n  constructor(\n    message: string,\n    status: number,\n    code: string | null,\n    requestTraceId: string | null,\n    detail: unknown,\n  ) {\n    super(message);\n    this.name = \"ConvaiRoomError\";\n    this.status = status;\n    this.code = code;\n    this.requestTraceId = requestTraceId;\n    this.detail = detail;\n  }\n\n  /**\n   * True when retrying the identical payload can plausibly succeed.\n   *\n   * Only the two \"still working on it\" conflicts qualify. A fingerprint\n   * mismatch means the topology genuinely differs, and a capacity or\n   * entitlement rejection will not change on its own — retrying those just\n   * burns the room's provisioning window.\n   */\n  get isRetryable(): boolean {\n    if (this.status !== 409) return false;\n    return (\n      this.code === \"ROSTER_PROVISIONING_IN_PROGRESS\" ||\n      this.code === \"CONNECT_ATTEMPT_IN_PROGRESS\"\n    );\n  }\n}\n\n/** Response bodies differ by layer; a code can arrive under any of these. */\nconst CODE_KEYS = [\"code\", \"error_code\", \"detail_code\"] as const;\n\n/**\n * Pull a named code out of a parsed error body.\n *\n * The runtime is not consistent about where it puts one: some rejections carry\n * `{ code }`, some put the name in `detail` as a bare string, and some nest it\n * under `detail.code`. A code is never synthesised from the status — callers\n * branch on it, and inventing `\"CONFLICT\"` for every 409 would make\n * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`\n * indistinguishable, which is exactly the distinction that decides whether to\n * retry.\n */\nexport function extractRoomErrorCode(body: unknown): string | null {\n  if (typeof body === \"string\") return looksLikeCode(body) ? body : null;\n  if (typeof body !== \"object\" || body === null) return null;\n\n  const record = body as Record<string, unknown>;\n  for (const key of CODE_KEYS) {\n    const value = record[key];\n    if (typeof value === \"string\" && value) return value;\n  }\n\n  const detail = record.detail;\n  if (typeof detail === \"string\") return looksLikeCode(detail) ? detail : null;\n  if (typeof detail === \"object\" && detail !== null) {\n    return extractRoomErrorCode(detail);\n  }\n  return null;\n}\n\n/**\n * A code is SCREAMING_SNAKE_CASE. `detail` is also where human prose lands\n * (\"Human room capacity reached\"), so shape is what tells the two apart.\n */\nfunction looksLikeCode(value: string): boolean {\n  return /^[A-Z][A-Z0-9_]{2,}$/.test(value.trim());\n}\n\n/** Pull the trace id out of a parsed body, wherever the layer put it. */\nexport function extractRequestTraceId(body: unknown): string | null {\n  if (typeof body !== \"object\" || body === null) return null;\n  const record = body as Record<string, unknown>;\n  const direct = record.request_trace_id;\n  if (typeof direct === \"string\" && direct) return direct;\n  const detail = record.detail;\n  if (typeof detail === \"object\" && detail !== null) {\n    return extractRequestTraceId(detail);\n  }\n  return null;\n}\n\n/** Human-readable message from a body, falling back to the status. */\nexport function extractRoomErrorMessage(body: unknown, status: number): string {\n  if (typeof body === \"string\" && body.trim()) return body.trim();\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    for (const key of [\"message\", \"detail\", \"error\"]) {\n      const value = record[key];\n      if (typeof value === \"string\" && value.trim()) return value.trim();\n      if (typeof value === \"object\" && value !== null) {\n        const nested = extractRoomErrorMessage(value, status);\n        if (!nested.startsWith(\"Room request failed\")) return nested;\n      }\n    }\n  }\n  return `Room request failed with HTTP ${status}`;\n}\n\n/** Build a `ConvaiRoomError` from a response status and its parsed body. */\nexport function roomErrorFromResponse(\n  status: number,\n  body: unknown,\n): ConvaiRoomError {\n  return new ConvaiRoomError(\n    extractRoomErrorMessage(body, status),\n    status,\n    extractRoomErrorCode(body),\n    extractRequestTraceId(body),\n    body,\n  );\n}\n"]}

package/dist/core/SSESession.d.ts

@@ -1,59 +0,0 @@
-import type { ConvaiConfig } from "./types.js";
-export interface SSESessionOptions {
-    interactionApiUrl: string;
-    authorization: string;
-    characterId: string;
-    getCharacterSessionId: () => string | null;
-    onCharacterSessionId: (characterSessionId: string) => void;
-    endUserId?: string;
-    endUserMetadata?: Record<string, unknown>;
-    takeStateOfMind: () => string | null;
-    enableEmotion?: ConvaiConfig["enableEmotion"];
-    emotionConfig?: ConvaiConfig["emotionConfig"];
-    actionConfig?: ConvaiConfig["actionConfig"];
-    capabilities?: ConvaiConfig["capabilities"];
-    dynamicInfo?: ConvaiConfig["dynamicInfo"];
-    keepInContext?: ConvaiConfig["keepInContext"];
-    narrativeTemplateKeys?: ConvaiConfig["narrativeTemplateKeys"];
-    sceneDescription?: ConvaiConfig["sceneDescription"];
-    respondModes?: ConvaiConfig["respondModes"];
-    debug?: boolean;
-    useResponseLifecycleContract?: boolean;
-    invocationMetadata?: ConvaiConfig["invocationMetadata"];
-    onMessage: (payload: Uint8Array) => void;
-    onError: (error: unknown) => void;
-}
-export interface SSEMessage {
-    type: string;
-    data: unknown;
-    id?: string;
-}
-/** Text-only interaction transport. One POST/SSE stream is used per message. */
-export declare class SSESession {
-    private readonly options;
-    private static readonly BOT_LLM_TEXT_FLUSH_MS;
-    private connected;
-    private abortController;
-    private queue;
-    private pendingBotLlmText;
-    private botLlmTextFlushTimer;
-    private pendingMessages;
-    constructor(options: SSESessionOptions);
-    get isConnected(): boolean;
-    connect(): void;
-    sendMessage(type: string, data: unknown, id?: string): void;
-    sendMessages(messages: SSEMessage[]): void;
-    /** Update request-scoped dynamic context without opening a control-only request. */
-    updateDynamicInfo(dynamicInfo: string): void;
-    getDynamicInfo(): string | undefined;
-    /** Carry a silent control update into the next stateless interaction request. */
-    queueMessage(type: string, data: unknown): void;
-    disconnect(): Promise<void>;
-    private sendInteraction;
-    private readEvents;
-    private consumeReader;
-    private queueBotLlmText;
-    private flushBotLlmText;
-    private clearPendingBotLlmText;
-}
-//# sourceMappingURL=SSESession.d.ts.map

package/dist/core/SSESession.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SSESession.d.ts","sourceRoot":"","sources":["../../src/core/SSESession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAO5C,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC3C,oBAAoB,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;IAC9C,aAAa,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;IAC9C,YAAY,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAC5C,YAAY,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IAC1C,aAAa,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;IAC9C,qBAAqB,CAAC,EAAE,YAAY,CAAC,uBAAuB,CAAC,CAAC;IAC9D,gBAAgB,CAAC,EAAE,YAAY,CAAC,kBAAkB,CAAC,CAAC;IACpD,YAAY,CAAC,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,kBAAkB,CAAC,EAAE,YAAY,CAAC,oBAAoB,CAAC,CAAC;IACxD,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,gFAAgF;AAChF,qBAAa,UAAU;IAST,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAM;IACnD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,oBAAoB,CAA8C;IAC1E,OAAO,CAAC,eAAe,CAAoB;gBAEd,OAAO,EAAE,iBAAiB;IAEvD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,IAAI,IAAI;IAIf,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAI3D,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,IAAI;IAmB1C,oFAAoF;IACpF,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI5C,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,iFAAiF;IACjF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAIzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YASnB,eAAe;YAkGf,UAAU;YAkBV,aAAa;IA4E3B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,sBAAsB;CAO/B"}