@convai/web-sdk 1.8.0-beta.4 → 1.8.0-beta.5

package/README.md

@@ -114,6 +114,7 @@ Full documentation is at **<a href="https://docs.convai.com/api-docs/plugins-and
 | <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/auth-tokens" target="_blank" rel="noopener noreferrer">Auth Tokens</a>                       | Server-side token exchange for production                                                          |
 | <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/websocket-transport-layer" target="_blank" rel="noopener noreferrer">WebSocket Transport</a> | Alternative transport for WebRTC-constrained environments                                          |
 | <a href="https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk" target="_blank" rel="noopener noreferrer">SSE Transport</a>                         | Text-only interaction transport; the one that runs under Node                                      |
+| [Character Versioning](docs/convai_character_versioning.md)                                                                                                                              | Connect to a draft, latest, or tagged version; list, compare, release and promote versions         |
 
 ---
 
@@ -181,6 +182,30 @@ Full guide: [SSE Interaction Transport](docs/convai_sse_transport.md).
 
 ---
 
+## Character versioning (beta)
+
+Connect to a character's editable draft, its promoted latest release, or an immutable tag, and
+manage those versions from the same client:
+
+```ts
+const client = new ConvaiClient({
+  apiKey: "...",
+  characterId: "...",
+  characterVersion: "draft", // or "latest", "1.2" — omit for the effective latest
+});
+
+const versions = client.characterVersions!;
+const { has_unpublished_changes } = await versions.list();
+if (has_unpublished_changes) await versions.create("1.1", { makeLatest: true });
+await client.connect();
+```
+
+Explicit selectors are resolved by the runtime through the Character REST platform; staging has
+this today and production returns `503` for explicit selectors until it is promoted there.
+Full guide: [Character Versioning](docs/convai_character_versioning.md).
+
+---
+
 ## Vision dynamic context beta
 
 Vision dynamic context is the default WebRTC/LiveKit vision path when `enableVideo: true`. Camera, screen, canvas, and custom video tracks can feed unified vision context; set `visionInputConfig.enabled: false` only when you need to keep the video channel while opting out.

package/dist/core/CharacterVersionManager.d.ts

@@ -0,0 +1,100 @@
+import type { CharacterDraftBootstrapResult, CharacterVersionInfo, CharacterVersionList, CharacterVersionManagerOptions, CharacterVersionRawDiff, CharacterVersionSemanticDiff, CreateCharacterVersionOptions, DiscardCharacterDraftResult, ForkCharacterVersionResult, ResolveCharacterVersionOptions, ResolvedCharacterVersion, RevertCharacterChangeOptions, RevertCharacterChangeResult } from "./types.js";
+import { type CharacterVersionSelector } from "./characterReference.js";
+export declare 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 declare class CharacterApiError extends Error {
+    readonly status: number;
+    readonly detail: unknown;
+    constructor(message: string, status: number, detail: unknown);
+}
+/**
+ * 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 declare class CharacterVersionManager {
+    private readonly apiKey;
+    private readonly personalAccessToken;
+    private readonly baseUrl;
+    private readonly workspaceId;
+    readonly characterId: string;
+    constructor(options: CharacterVersionManagerOptions);
+    /** List released tags plus the current latest and draft revisions. */
+    list(): Promise<CharacterVersionList>;
+    /**
+     * 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.
+     */
+    resolve(version?: CharacterVersionSelector | null, options?: ResolveCharacterVersionOptions): Promise<ResolvedCharacterVersion>;
+    /**
+     * Give a character that predates versioning an editable draft. Safe to call
+     * repeatedly — `created` is false when a draft already existed.
+     */
+    bootstrap(): Promise<CharacterDraftBootstrapResult>;
+    /**
+     * Compare two references. Each side is `draft`, `latest`, or a tag.
+     * The raw view lists JSON paths; the semantic view groups them into
+     * labelled changes that {@link revert} can undo one at a time.
+     */
+    diff(from: string, to: string, options?: {
+        view?: "raw";
+    }): Promise<CharacterVersionRawDiff>;
+    diff(from: string, to: string, options: {
+        view: "semantic";
+    }): Promise<CharacterVersionSemanticDiff>;
+    /**
+     * Release the current draft as an immutable tagged version.
+     * @param version - New tag, `major.minor` or `major.minor.patch`
+     */
+    create(version: string, options?: CreateCharacterVersionOptions): Promise<CharacterVersionInfo>;
+    /** Point `latest` at an already released tag — the way to roll back. */
+    promote(version: string): Promise<CharacterVersionInfo>;
+    /**
+     * 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.
+     */
+    discardDraft(expectedDraftRevisionId: string): Promise<DiscardCharacterDraftResult>;
+    /** Undo one semantic change in the draft, identified by a semantic diff's `change_id`. */
+    revert(options: RevertCharacterChangeOptions): Promise<RevertCharacterChangeResult>;
+    /** Mark a tag deprecated, or restore it with `deprecated: false`. Deprecated tags stay connectable. */
+    deprecate(version: string, deprecated?: boolean): Promise<CharacterVersionInfo>;
+    /**
+     * 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.
+     */
+    fork(version: string, expectedDraftRevisionId?: string): Promise<ForkCharacterVersionResult>;
+    private assertSelector;
+    private assertTag;
+    private request;
+}
+//# sourceMappingURL=CharacterVersionManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CharacterVersionManager.d.ts","sourceRoot":"","sources":["../../src/core/CharacterVersionManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,6BAA6B,EAG7B,oBAAoB,EACpB,oBAAoB,EACpB,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,EAC9B,wBAAwB,EACxB,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,yBAAyB,4BAA4B,CAAC;AAEnE;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;CAM7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAgB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,8BAA8B;IAgBnD,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAI3C;;;;OAIG;IACG,OAAO,CACX,OAAO,CAAC,EAAE,wBAAwB,GAAG,IAAI,EACzC,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,wBAAwB,CAAC;IAUpC;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,6BAA6B,CAAC;IAIzD;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAC5F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,4BAA4B,CAAC;IAWpG;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,6BAAkC,GAAG,OAAO,CAAC,oBAAoB,CAAC;IASzG,wEAAwE;IAClE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAM7D;;;;OAIG;IACG,YAAY,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC;IASzF,0FAA0F;IACpF,MAAM,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAczF,uGAAuG;IACjG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,UAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAMlF;;;;OAIG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,uBAAuB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC;IASlG,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,SAAS;YASH,OAAO;CA2CtB"}

package/dist/core/CharacterVersionManager.js

@@ -0,0 +1,227 @@
+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

@@ -0,0 +1 @@
+{"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/ConvaiClient.d.ts

@@ -3,6 +3,8 @@ import { ConvaiConfig, ConvaiClientState, ChatMessage, IConvaiClient, AudioContr
 import { EventEmitter } from "./EventEmitter.js";
 import { BlendshapeQueue } from "./BlendshapeQueue.js";
 import { MemoryManager } from "./MemoryManager.js";
+import { CharacterVersionManager } from "./CharacterVersionManager.js";
+import { type CharacterVersionSelector } from "./characterReference.js";
 /**
  * Main Convai client class for managing AI voice assistant connections
  * Provides complete interface for connecting to Convai's voice assistants,
@@ -46,6 +48,10 @@ export declare class ConvaiClient extends EventEmitter implements IConvaiClient
     private _apiKey;
     private _authToken;
     private _characterId;
+    private _characterVersion;
+    private _characterReference;
+    private _characterVersionManager;
+    private _characterVersionManagerKey;
     private _characterSessionId;
     private _isBotReady;
     private _participantSid;
@@ -88,6 +94,15 @@ export declare class ConvaiClient extends EventEmitter implements IConvaiClient
     get apiKey(): string | null;
     get authToken(): string | null;
     get characterId(): string | null;
+    get characterVersion(): CharacterVersionSelector | null;
+    get characterReference(): string | null;
+    /**
+     * Character version manager for the configured character. Built from the
+     * live connection when there is one, otherwise from the stored config, so
+     * versions can be listed and released before connecting. Null without an
+     * API key (the Character REST platform does not accept realtime auth tokens).
+     */
+    get characterVersions(): CharacterVersionManager | null;
     get room(): Room;
     get chatMessages(): ChatMessage[];
     get userTranscription(): string;

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

@@ -1 +1 @@
-{"version":3,"file":"ConvaiClient.d.ts","sourceRoot":"","sources":["../../src/core/ConvaiClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ConvaiClient.d.ts","sourceRoot":"","sources":["../../src/core/ConvaiClient.ts"],"names":[],"mappings":"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"}

package/dist/core/ConvaiClient.js

@@ -8,6 +8,8 @@ import { MessageHandler } from "./MessageHandler.js";
 import { SDK_VERSION } from "../version.js";
 import { EventEmitter } from "./EventEmitter.js";
 import { MemoryManager } from "./MemoryManager.js";
+import { CharacterVersionManager } from "./CharacterVersionManager.js";
+import { resolveCharacterReference, } from "./characterReference.js";
 import { ConnectionStateHandler } from "./ConnectionStateHandler.js";
 import { buildActionConnectConfig, buildBlendshapeConnectConfig, buildEmotionConnectConfig, } from "./connectRequest.js";
 import { shouldPreemptForContextUpdateResponse, shouldPreemptForExplicitRespondMode, } from "./contextUpdateRequest.js";
@@ -81,6 +83,10 @@ export class ConvaiClient extends EventEmitter {
         this._apiKey = null;
         this._authToken = null;
         this._characterId = null;
+        this._characterVersion = null;
+        this._characterReference = null;
+        this._characterVersionManager = null;
+        this._characterVersionManagerKey = null;
         this._characterSessionId = "-1";
         this._isBotReady = false;
         this._participantSid = "";
@@ -169,6 +175,42 @@ export class ConvaiClient extends EventEmitter {
     get characterId() {
         return this._characterId;
     }
+    get characterVersion() {
+        return this._characterVersion;
+    }
+    get characterReference() {
+        return this._characterReference;
+    }
+    /**
+     * Character version manager for the configured character. Built from the
+     * live connection when there is one, otherwise from the stored config, so
+     * versions can be listed and released before connecting. Null without an
+     * API key (the Character REST platform does not accept realtime auth tokens).
+     */
+    get characterVersions() {
+        const apiKey = this._apiKey ?? this._storedConfig?.apiKey ?? null;
+        const rawCharacterId = this._characterId ?? this._storedConfig?.characterId ?? null;
+        if (!apiKey || !rawCharacterId)
+            return null;
+        let characterId = rawCharacterId;
+        try {
+            characterId = resolveCharacterReference(rawCharacterId).characterId;
+        }
+        catch {
+            // A malformed id is reported by connect(); use it verbatim here.
+        }
+        const baseUrl = this._storedConfig?.characterApiUrl ?? undefined;
+        const key = `${apiKey}\u0000${characterId}\u0000${baseUrl ?? ""}`;
+        if (this._characterVersionManagerKey !== key) {
+            this._characterVersionManager = new CharacterVersionManager({
+                apiKey,
+                characterId,
+                baseUrl,
+            });
+            this._characterVersionManagerKey = key;
+        }
+        return this._characterVersionManager;
+    }
     get room() {
         return this._room;
     }
@@ -430,6 +472,8 @@ export class ConvaiClient extends EventEmitter {
             this._apiKey = configWithDefaults.apiKey ?? null;
             this._authToken = configWithDefaults.authToken ?? null;
             this._characterId = configWithDefaults.characterId;
+            this._characterVersion = configWithDefaults.characterVersion ?? null;
+            this._characterReference = configWithDefaults.characterReference;
             // Determine connection type based on enableVideo
             const connType = configWithDefaults.enableVideo ? "video" : "audio";
             this._connectionType = connType;
@@ -453,7 +497,7 @@ export class ConvaiClient extends EventEmitter {
                 this._sseSession = new SSESession({
                     interactionApiUrl: configWithDefaults.interactionApiUrl,
                     authorization: configWithDefaults.authToken ?? configWithDefaults.apiKey,
-                    characterId: configWithDefaults.characterId,
+                    characterId: configWithDefaults.characterReference,
                     getCharacterSessionId: () => this._characterSessionId,
                     takeStateOfMind: () => {
                         const stateOfMind = this._stateOfMind;
@@ -496,7 +540,7 @@ export class ConvaiClient extends EventEmitter {
             // Prepare request body with required parameters
             const characterSessionIdToSend = configWithDefaults.characterSessionId ?? this._characterSessionId;
             const requestBody = {
-                character_id: configWithDefaults.characterId,
+                character_id: configWithDefaults.characterReference,
                 ...(stateOfMind ? { state_of_mind: stateOfMind } : {}),
                 ...(configWithDefaults.endUserId && {
                     end_user_id: configWithDefaults.endUserId,
@@ -686,7 +730,16 @@ export class ConvaiClient extends EventEmitter {
         if (missingCredential || !configWithDefaults.characterId) {
             throw new Error("Either apiKey or authToken is required, and characterId is required");
         }
-        return configWithDefaults;
+        // Split the character id from its version selector. The bare UUID names
+        // the character everywhere inside the SDK (memory, character info); the
+        // joined reference is what the runtime receives.
+        const reference = resolveCharacterReference(configWithDefaults.characterId, configWithDefaults.characterVersion);
+        return {
+            ...configWithDefaults,
+            characterId: reference.characterId,
+            characterVersion: reference.version,
+            characterReference: reference.reference,
+        };
     }
     /**
      * Consume a /connect response and bring up the transport.
@@ -718,6 +771,8 @@ export class ConvaiClient extends EventEmitter {
         this._apiKey = configWithDefaults.apiKey ?? null;
         this._authToken = configWithDefaults.authToken ?? null;
         this._characterId = configWithDefaults.characterId;
+        this._characterVersion = configWithDefaults.characterVersion ?? null;
+        this._characterReference = configWithDefaults.characterReference;
         const connType = configWithDefaults.enableVideo ? "video" : "audio";
         this._connectionType = connType;
         const transportType = configWithDefaults.transport ?? "livekit";
@@ -1016,6 +1071,8 @@ export class ConvaiClient extends EventEmitter {
         this._apiKey = null;
         this._authToken = null;
         this._characterId = null;
+        this._characterVersion = null;
+        this._characterReference = null;
         this._endUserId = null;
         this._endUserMetadata = null;
         this._memoryManager = null; // Clear memory manager on disconnect