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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAGrD,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAGrD,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,8BAA8B,EAC9B,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAG5E,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/core/index.js

@@ -10,6 +10,9 @@ export { VideoManager } from './VideoManager.js';
 export { ScreenShareManager } from './ScreenShareManager.js';
 export { MessageHandler } from './MessageHandler.js';
 export { MemoryManager } from './MemoryManager.js';
+export { CharacterRoster } from './CharacterRoster.js';
+export { ConvaiRoomError } from './ConvaiRoomError.js';
+export { MULTI_CHARACTER_MAX_CHARACTERS, isRosterConfig, } from './rosterRequest.js';
 export { CharacterVersionManager, CharacterApiError, DEFAULT_CHARACTER_API_URL, } from './CharacterVersionManager.js';
 // Character reference helpers (version selectors)
 export { parseCharacterReference, resolveCharacterReference, isCharacterVersionSelector, isCharacterUuid, } from './characterReference.js';

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,4CAA4C;AAC5C,cAAc,SAAS,CAAC;AAExB,mBAAmB;AACnB,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAKrD,gCAAgC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,kDAAkD;AAClD,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,+BAA+B;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// Main client\nexport { ConvaiClient } from './ConvaiClient';\n\n// Types (including IConvaiClient interface)\nexport * from './types';\n\n// Helper functions\nexport { getDisconnectReasonMessage } from './types';\n\n// Type alias for easier usage\nexport type { ConvaiClient as ConvaiClientType } from './ConvaiClient';\n\n// Managers (for advanced usage)\nexport { AudioManager } from './AudioManager';\nexport { VideoManager } from './VideoManager';\nexport { ScreenShareManager } from './ScreenShareManager';\nexport { MessageHandler } from './MessageHandler';\nexport { MemoryManager } from './MemoryManager';\nexport {\n  CharacterVersionManager,\n  CharacterApiError,\n  DEFAULT_CHARACTER_API_URL,\n} from './CharacterVersionManager';\n\n// Character reference helpers (version selectors)\nexport {\n  parseCharacterReference,\n  resolveCharacterReference,\n  isCharacterVersionSelector,\n  isCharacterUuid,\n} from './characterReference';\n\n// Blendshape queue for lipsync\nexport { BlendshapeQueue } from './BlendshapeQueue';\nexport type { TurnStats, BlendshapeChunkMetadata } from './BlendshapeQueue';\n\n// Event Emitter (for advanced usage)\nexport { EventEmitter } from './EventEmitter';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,4CAA4C;AAC5C,cAAc,SAAS,CAAC;AAExB,mBAAmB;AACnB,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAKrD,gCAAgC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,8BAA8B,EAC9B,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,kDAAkD;AAClD,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,0BAA0B,EAC1B,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAE9B,+BAA+B;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,qCAAqC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// Main client\nexport { ConvaiClient } from './ConvaiClient';\n\n// Types (including IConvaiClient interface)\nexport * from './types';\n\n// Helper functions\nexport { getDisconnectReasonMessage } from './types';\n\n// Type alias for easier usage\nexport type { ConvaiClient as ConvaiClientType } from './ConvaiClient';\n\n// Managers (for advanced usage)\nexport { AudioManager } from './AudioManager';\nexport { VideoManager } from './VideoManager';\nexport { ScreenShareManager } from './ScreenShareManager';\nexport { MessageHandler } from './MessageHandler';\nexport { MemoryManager } from './MemoryManager';\nexport { CharacterRoster } from './CharacterRoster';\nexport { ConvaiRoomError } from './ConvaiRoomError';\nexport {\n  MULTI_CHARACTER_MAX_CHARACTERS,\n  isRosterConfig,\n} from './rosterRequest';\nexport {\n  CharacterVersionManager,\n  CharacterApiError,\n  DEFAULT_CHARACTER_API_URL,\n} from './CharacterVersionManager';\n\n// Character reference helpers (version selectors)\nexport {\n  parseCharacterReference,\n  resolveCharacterReference,\n  isCharacterVersionSelector,\n  isCharacterUuid,\n} from './characterReference';\n\n// Blendshape queue for lipsync\nexport { BlendshapeQueue } from './BlendshapeQueue';\nexport type { TurnStats, BlendshapeChunkMetadata } from './BlendshapeQueue';\n\n// Event Emitter (for advanced usage)\nexport { EventEmitter } from './EventEmitter';\n"]}

package/dist/core/rosterRequest.d.ts

@@ -0,0 +1,57 @@
+import type { ConvaiConfig, JoinRoomOptions } from "./types.js";
+/**
+ * Validation and request-body construction for multi-character rooms.
+ *
+ * Pure: no transport, no client state. Every rule below runs before a request
+ * is built, so an illegal topology costs nothing and reports the rule it broke
+ * rather than a 422 from the runtime.
+ */
+/**
+ * Server-wide roster cap. Checked client-side only to fail fast with a clear
+ * message — the server stays authoritative, and a plan may configure a lower
+ * `max_characters` that surfaces as 403 `MULTI_CHARACTER_ROSTER_LIMIT_EXCEEDED`.
+ * This is an operational limit, not a protocol maximum, so it must not leak
+ * into any public type.
+ */
+export declare const MULTI_CHARACTER_MAX_CHARACTERS = 50;
+/** True when this config asks for a multi-character room. */
+export declare function isRosterConfig(config: Pick<ConvaiConfig, "characters">): boolean;
+/**
+ * Validate a roster create config.
+ *
+ * Throws on the first broken rule. Ordered so the most structural problems
+ * (which topology did you mean?) report before the detail ones.
+ */
+export declare function validateRosterConfig(config: ConvaiConfig): void;
+/**
+ * Reject a config that negotiates v2 output protocols alongside room options
+ * the runtime cannot combine them with.
+ *
+ * Verified against staging 2026-09-08: `capabilities.actionProtocolVersion: 2`
+ * or `modelOutputVersion: 2` is answered with 422
+ * `unsupported_action_protocol_topology` / `unsupported_model_output_topology`
+ * unless the request uses `mode='create'`, a singular `characterId`, no
+ * `sharedSessionKey`, and `maxNumParticipants` of 1. Version 1 carries no such
+ * constraint.
+ *
+ * The published contract mentions only the multi-character half of this. The
+ * `sharedSessionKey` and `maxNumParticipants` constraints bite in
+ * single-character sessions too, which is why this runs on every connect
+ * rather than only the roster path.
+ */
+export declare function validateProtocolTopology(config: ConvaiConfig): void;
+/** Validate join options. */
+export declare function validateJoinOptions(options: JoinRoomOptions): void;
+/**
+ * The roster half of a create request. Merged into the existing single-character
+ * body by the caller, so every current option (blendshape, TTS/STT, dynamic
+ * info, action, scene, VAD, vision) continues to apply to every member.
+ */
+export declare function buildRosterConnectFields(config: ConvaiConfig): Record<string, unknown>;
+/**
+ * The complete join request body. A join carries a locator and the human, and
+ * nothing else — the roster is loaded from persisted room state, and resending
+ * topology is rejected.
+ */
+export declare function buildJoinRequestBody(options: JoinRoomOptions): Record<string, unknown>;
+//# sourceMappingURL=rosterRequest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rosterRequest.d.ts","sourceRoot":"","sources":["../../src/core/rosterRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EACZ,eAAe,EAChB,MAAM,SAAS,CAAC;AAGjB;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAKjD,6DAA6D;AAC7D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GACvC,OAAO,CAET;AAeD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CA8E/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CA+BnE;AAED,6BAA6B;AAC7B,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAuBlE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,YAAY,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BzB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB"}

package/dist/core/rosterRequest.js

@@ -0,0 +1,210 @@
+import { isCharacterUuid } from "./characterReference.js";
+/**
+ * Validation and request-body construction for multi-character rooms.
+ *
+ * Pure: no transport, no client state. Every rule below runs before a request
+ * is built, so an illegal topology costs nothing and reports the rule it broke
+ * rather than a 422 from the runtime.
+ */
+/**
+ * Server-wide roster cap. Checked client-side only to fail fast with a clear
+ * message — the server stays authoritative, and a plan may configure a lower
+ * `max_characters` that surfaces as 403 `MULTI_CHARACTER_ROSTER_LIMIT_EXCEEDED`.
+ * This is an operational limit, not a protocol maximum, so it must not leak
+ * into any public type.
+ */
+export const MULTI_CHARACTER_MAX_CHARACTERS = 50;
+/** `shared_session_key` and `connect_attempt_id` share one charset. */
+const KEY_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+/** True when this config asks for a multi-character room. */
+export function isRosterConfig(config) {
+    return Array.isArray(config.characters) && config.characters.length > 0;
+}
+function assertKey(value, field) {
+    if (value === undefined)
+        return;
+    if (!KEY_PATTERN.test(value)) {
+        throw new Error(`${field} must be 1-128 characters of letters, digits, hyphen or underscore`);
+    }
+}
+function nonblank(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Validate a roster create config.
+ *
+ * Throws on the first broken rule. Ordered so the most structural problems
+ * (which topology did you mean?) report before the detail ones.
+ */
+export function validateRosterConfig(config) {
+    const characters = config.characters ?? [];
+    if (config.characterId) {
+        throw new Error("Pass either characterId or characters, not both");
+    }
+    if (characters.length === 0) {
+        throw new Error("characters must contain at least one entry");
+    }
+    if (characters.length > MULTI_CHARACTER_MAX_CHARACTERS) {
+        throw new Error(`characters accepts at most ${MULTI_CHARACTER_MAX_CHARACTERS} entries; ` +
+            `your plan may allow fewer`);
+    }
+    const seenSessions = new Set();
+    characters.forEach((spec, index) => {
+        if (!spec || !nonblank(spec.characterId)) {
+            throw new Error(`characters[${index}] requires a characterId`);
+        }
+        // A roster entry is typed as a bare UUID on the runtime. The version
+        // selectors that single-character `characterId` has accepted since
+        // 1.8.0-beta.5 are a 422 here, and the failure would otherwise only show
+        // up as an opaque validation error from the server.
+        if (!isCharacterUuid(spec.characterId.trim())) {
+            throw new Error(`characters[${index}].characterId must be a bare character UUID; ` +
+                `version selectors are not supported inside a roster`);
+        }
+        if (spec.characterSessionId !== undefined) {
+            if (!nonblank(spec.characterSessionId)) {
+                throw new Error(`characters[${index}].characterSessionId must be nonblank when supplied`);
+            }
+            if (seenSessions.has(spec.characterSessionId)) {
+                throw new Error(`characters[${index}].characterSessionId is repeated; resume ids must be unique within the roster`);
+            }
+            seenSessions.add(spec.characterSessionId);
+        }
+    });
+    if (config.characterSessionId) {
+        throw new Error("characterSessionId is not valid with characters; use characters[].characterSessionId");
+    }
+    if (!nonblank(config.endUserId)) {
+        throw new Error("characters requires a nonblank endUserId");
+    }
+    if (config.transport && config.transport !== "livekit") {
+        throw new Error("Multi-character rooms require the LiveKit transport");
+    }
+    if (config.interactionApiUrl) {
+        throw new Error("Multi-character rooms require the LiveKit transport; interactionApiUrl selects SSE");
+    }
+    if (config.characterVersion) {
+        throw new Error("characterVersion applies to a single character; roster entries take bare UUIDs");
+    }
+    assertKey(config.sharedSessionKey, "sharedSessionKey");
+    assertKey(config.connectAttemptId, "connectAttemptId");
+    if (config.maxNumParticipants !== undefined &&
+        (!Number.isInteger(config.maxNumParticipants) ||
+            config.maxNumParticipants < 1)) {
+        throw new Error("maxNumParticipants must be a positive integer");
+    }
+}
+/**
+ * Reject a config that negotiates v2 output protocols alongside room options
+ * the runtime cannot combine them with.
+ *
+ * Verified against staging 2026-09-08: `capabilities.actionProtocolVersion: 2`
+ * or `modelOutputVersion: 2` is answered with 422
+ * `unsupported_action_protocol_topology` / `unsupported_model_output_topology`
+ * unless the request uses `mode='create'`, a singular `characterId`, no
+ * `sharedSessionKey`, and `maxNumParticipants` of 1. Version 1 carries no such
+ * constraint.
+ *
+ * The published contract mentions only the multi-character half of this. The
+ * `sharedSessionKey` and `maxNumParticipants` constraints bite in
+ * single-character sessions too, which is why this runs on every connect
+ * rather than only the roster path.
+ */
+export function validateProtocolTopology(config) {
+    const negotiatesV2 = config.capabilities?.actionProtocolVersion === 2 ||
+        config.capabilities?.modelOutputVersion === 2;
+    if (!negotiatesV2) {
+        // Tools need v2, so without it they are refused whatever the topology.
+        if (config.actionConfig?.tools?.length) {
+            throw new Error("actionConfig.tools requires capabilities.actionProtocolVersion: 2");
+        }
+        return;
+    }
+    const offenders = [];
+    if (isRosterConfig(config))
+        offenders.push("characters");
+    if (config.sharedSessionKey)
+        offenders.push("sharedSessionKey");
+    if (config.maxNumParticipants !== undefined && config.maxNumParticipants !== 1) {
+        offenders.push("maxNumParticipants greater than 1");
+    }
+    if (offenders.length === 0)
+        return;
+    throw new Error(`Negotiated v2 output protocols require a single-character room: ` +
+        `remove ${offenders.join(", ")}, or drop capabilities to version 1. ` +
+        (offenders.includes("characters")
+            ? "Multi-character rooms cannot use action protocol v2, and therefore cannot use client tools. "
+            : "") +
+        "The runtime rejects this combination with unsupported_action_protocol_topology.");
+}
+/** Validate join options. */
+export function validateJoinOptions(options) {
+    const locators = Number(nonblank(options?.roomSessionId)) +
+        Number(nonblank(options?.sharedSessionKey));
+    if (locators !== 1) {
+        throw new Error("joinRoom requires exactly one of roomSessionId or sharedSessionKey");
+    }
+    if (!nonblank(options.endUserId)) {
+        throw new Error("joinRoom requires a nonblank endUserId");
+    }
+    // Guard the shape even though the type forbids it: a plain-JS caller, or a
+    // config object spread in wholesale, would otherwise send topology that the
+    // runtime rejects with a less specific message.
+    const stray = options;
+    if (stray.characters || stray.characterId || stray.characterSessionId) {
+        throw new Error("joinRoom must not carry character topology; the room's roster is server-owned");
+    }
+    assertKey(options.sharedSessionKey, "sharedSessionKey");
+    assertKey(options.connectAttemptId, "connectAttemptId");
+}
+/**
+ * The roster half of a create request. Merged into the existing single-character
+ * body by the caller, so every current option (blendshape, TTS/STT, dynamic
+ * info, action, scene, VAD, vision) continues to apply to every member.
+ */
+export function buildRosterConnectFields(config) {
+    const characters = (config.characters ?? []).map((spec) => ({
+        character_id: spec.characterId.trim(),
+        ...(spec.characterSessionId
+            ? { character_session_id: spec.characterSessionId }
+            : {}),
+    }));
+    return {
+        // Both carry server defaults that already match, but a roster room is
+        // rejected outright without them, so they are stated rather than assumed.
+        mode: "create",
+        spawn_agent: true,
+        characters,
+        ...(config.sharedSessionKey
+            ? { shared_session_key: config.sharedSessionKey }
+            : {}),
+        ...(config.connectAttemptId
+            ? { connect_attempt_id: config.connectAttemptId }
+            : {}),
+        ...(config.maxNumParticipants !== undefined
+            ? { max_num_participants: config.maxNumParticipants }
+            : {}),
+    };
+}
+/**
+ * The complete join request body. A join carries a locator and the human, and
+ * nothing else — the roster is loaded from persisted room state, and resending
+ * topology is rejected.
+ */
+export function buildJoinRequestBody(options) {
+    return {
+        mode: "join",
+        transport: "livekit",
+        ...(options.roomSessionId
+            ? { room_session_id: options.roomSessionId }
+            : { shared_session_key: options.sharedSessionKey }),
+        end_user_id: options.endUserId,
+        ...(options.endUserMetadata
+            ? { end_user_metadata: options.endUserMetadata }
+            : {}),
+        ...(options.connectAttemptId
+            ? { connect_attempt_id: options.connectAttemptId }
+            : {}),
+    };
+}
+//# sourceMappingURL=rosterRequest.js.map

package/dist/core/rosterRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rosterRequest.js","sourceRoot":"","sources":["../../src/core/rosterRequest.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ConvaiCharacterSpec,\n  ConvaiConfig,\n  JoinRoomOptions,\n} from \"./types\";\nimport { isCharacterUuid } from \"./characterReference\";\n\n/**\n * Validation and request-body construction for multi-character rooms.\n *\n * Pure: no transport, no client state. Every rule below runs before a request\n * is built, so an illegal topology costs nothing and reports the rule it broke\n * rather than a 422 from the runtime.\n */\n\n/**\n * Server-wide roster cap. Checked client-side only to fail fast with a clear\n * message — the server stays authoritative, and a plan may configure a lower\n * `max_characters` that surfaces as 403 `MULTI_CHARACTER_ROSTER_LIMIT_EXCEEDED`.\n * This is an operational limit, not a protocol maximum, so it must not leak\n * into any public type.\n */\nexport const MULTI_CHARACTER_MAX_CHARACTERS = 50;\n\n/** `shared_session_key` and `connect_attempt_id` share one charset. */\nconst KEY_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;\n\n/** True when this config asks for a multi-character room. */\nexport function isRosterConfig(\n  config: Pick<ConvaiConfig, \"characters\">,\n): boolean {\n  return Array.isArray(config.characters) && config.characters.length > 0;\n}\n\nfunction assertKey(value: string | undefined, field: string): void {\n  if (value === undefined) return;\n  if (!KEY_PATTERN.test(value)) {\n    throw new Error(\n      `${field} must be 1-128 characters of letters, digits, hyphen or underscore`,\n    );\n  }\n}\n\nfunction nonblank(value: string | undefined | null): boolean {\n  return typeof value === \"string\" && value.trim().length > 0;\n}\n\n/**\n * Validate a roster create config.\n *\n * Throws on the first broken rule. Ordered so the most structural problems\n * (which topology did you mean?) report before the detail ones.\n */\nexport function validateRosterConfig(config: ConvaiConfig): void {\n  const characters = config.characters ?? [];\n\n  if (config.characterId) {\n    throw new Error(\"Pass either characterId or characters, not both\");\n  }\n  if (characters.length === 0) {\n    throw new Error(\"characters must contain at least one entry\");\n  }\n  if (characters.length > MULTI_CHARACTER_MAX_CHARACTERS) {\n    throw new Error(\n      `characters accepts at most ${MULTI_CHARACTER_MAX_CHARACTERS} entries; ` +\n        `your plan may allow fewer`,\n    );\n  }\n\n  const seenSessions = new Set<string>();\n  characters.forEach((spec, index) => {\n    if (!spec || !nonblank(spec.characterId)) {\n      throw new Error(\n        `characters[${index}] requires a characterId`,\n      );\n    }\n    // A roster entry is typed as a bare UUID on the runtime. The version\n    // selectors that single-character `characterId` has accepted since\n    // 1.8.0-beta.5 are a 422 here, and the failure would otherwise only show\n    // up as an opaque validation error from the server.\n    if (!isCharacterUuid(spec.characterId.trim())) {\n      throw new Error(\n        `characters[${index}].characterId must be a bare character UUID; ` +\n          `version selectors are not supported inside a roster`,\n      );\n    }\n    if (spec.characterSessionId !== undefined) {\n      if (!nonblank(spec.characterSessionId)) {\n        throw new Error(\n          `characters[${index}].characterSessionId must be nonblank when supplied`,\n        );\n      }\n      if (seenSessions.has(spec.characterSessionId)) {\n        throw new Error(\n          `characters[${index}].characterSessionId is repeated; resume ids must be unique within the roster`,\n        );\n      }\n      seenSessions.add(spec.characterSessionId);\n    }\n  });\n\n  if (config.characterSessionId) {\n    throw new Error(\n      \"characterSessionId is not valid with characters; use characters[].characterSessionId\",\n    );\n  }\n  if (!nonblank(config.endUserId)) {\n    throw new Error(\"characters requires a nonblank endUserId\");\n  }\n  if (config.transport && config.transport !== \"livekit\") {\n    throw new Error(\"Multi-character rooms require the LiveKit transport\");\n  }\n  if (config.interactionApiUrl) {\n    throw new Error(\n      \"Multi-character rooms require the LiveKit transport; interactionApiUrl selects SSE\",\n    );\n  }\n  if (config.characterVersion) {\n    throw new Error(\n      \"characterVersion applies to a single character; roster entries take bare UUIDs\",\n    );\n  }\n  assertKey(config.sharedSessionKey, \"sharedSessionKey\");\n  assertKey(config.connectAttemptId, \"connectAttemptId\");\n  if (\n    config.maxNumParticipants !== undefined &&\n    (!Number.isInteger(config.maxNumParticipants) ||\n      config.maxNumParticipants < 1)\n  ) {\n    throw new Error(\"maxNumParticipants must be a positive integer\");\n  }\n}\n\n/**\n * Reject a config that negotiates v2 output protocols alongside room options\n * the runtime cannot combine them with.\n *\n * Verified against staging 2026-09-08: `capabilities.actionProtocolVersion: 2`\n * or `modelOutputVersion: 2` is answered with 422\n * `unsupported_action_protocol_topology` / `unsupported_model_output_topology`\n * unless the request uses `mode='create'`, a singular `characterId`, no\n * `sharedSessionKey`, and `maxNumParticipants` of 1. Version 1 carries no such\n * constraint.\n *\n * The published contract mentions only the multi-character half of this. The\n * `sharedSessionKey` and `maxNumParticipants` constraints bite in\n * single-character sessions too, which is why this runs on every connect\n * rather than only the roster path.\n */\nexport function validateProtocolTopology(config: ConvaiConfig): void {\n  const negotiatesV2 =\n    config.capabilities?.actionProtocolVersion === 2 ||\n    config.capabilities?.modelOutputVersion === 2;\n\n  if (!negotiatesV2) {\n    // Tools need v2, so without it they are refused whatever the topology.\n    if (config.actionConfig?.tools?.length) {\n      throw new Error(\n        \"actionConfig.tools requires capabilities.actionProtocolVersion: 2\",\n      );\n    }\n    return;\n  }\n\n  const offenders: string[] = [];\n  if (isRosterConfig(config)) offenders.push(\"characters\");\n  if (config.sharedSessionKey) offenders.push(\"sharedSessionKey\");\n  if (config.maxNumParticipants !== undefined && config.maxNumParticipants !== 1) {\n    offenders.push(\"maxNumParticipants greater than 1\");\n  }\n  if (offenders.length === 0) return;\n\n  throw new Error(\n    `Negotiated v2 output protocols require a single-character room: ` +\n      `remove ${offenders.join(\", \")}, or drop capabilities to version 1. ` +\n      (offenders.includes(\"characters\")\n        ? \"Multi-character rooms cannot use action protocol v2, and therefore cannot use client tools. \"\n        : \"\") +\n      \"The runtime rejects this combination with unsupported_action_protocol_topology.\",\n  );\n}\n\n/** Validate join options. */\nexport function validateJoinOptions(options: JoinRoomOptions): void {\n  const locators =\n    Number(nonblank(options?.roomSessionId)) +\n    Number(nonblank(options?.sharedSessionKey));\n  if (locators !== 1) {\n    throw new Error(\n      \"joinRoom requires exactly one of roomSessionId or sharedSessionKey\",\n    );\n  }\n  if (!nonblank(options.endUserId)) {\n    throw new Error(\"joinRoom requires a nonblank endUserId\");\n  }\n  // Guard the shape even though the type forbids it: a plain-JS caller, or a\n  // config object spread in wholesale, would otherwise send topology that the\n  // runtime rejects with a less specific message.\n  const stray = options as unknown as Record<string, unknown>;\n  if (stray.characters || stray.characterId || stray.characterSessionId) {\n    throw new Error(\n      \"joinRoom must not carry character topology; the room's roster is server-owned\",\n    );\n  }\n  assertKey(options.sharedSessionKey, \"sharedSessionKey\");\n  assertKey(options.connectAttemptId, \"connectAttemptId\");\n}\n\n/**\n * The roster half of a create request. Merged into the existing single-character\n * body by the caller, so every current option (blendshape, TTS/STT, dynamic\n * info, action, scene, VAD, vision) continues to apply to every member.\n */\nexport function buildRosterConnectFields(\n  config: ConvaiConfig,\n): Record<string, unknown> {\n  const characters = (config.characters ?? []).map(\n    (spec: ConvaiCharacterSpec) => ({\n      character_id: spec.characterId.trim(),\n      ...(spec.characterSessionId\n        ? { character_session_id: spec.characterSessionId }\n        : {}),\n    }),\n  );\n\n  return {\n    // Both carry server defaults that already match, but a roster room is\n    // rejected outright without them, so they are stated rather than assumed.\n    mode: \"create\",\n    spawn_agent: true,\n    characters,\n    ...(config.sharedSessionKey\n      ? { shared_session_key: config.sharedSessionKey }\n      : {}),\n    ...(config.connectAttemptId\n      ? { connect_attempt_id: config.connectAttemptId }\n      : {}),\n    ...(config.maxNumParticipants !== undefined\n      ? { max_num_participants: config.maxNumParticipants }\n      : {}),\n  };\n}\n\n/**\n * The complete join request body. A join carries a locator and the human, and\n * nothing else — the roster is loaded from persisted room state, and resending\n * topology is rejected.\n */\nexport function buildJoinRequestBody(\n  options: JoinRoomOptions,\n): Record<string, unknown> {\n  return {\n    mode: \"join\",\n    transport: \"livekit\",\n    ...(options.roomSessionId\n      ? { room_session_id: options.roomSessionId }\n      : { shared_session_key: options.sharedSessionKey }),\n    end_user_id: options.endUserId,\n    ...(options.endUserMetadata\n      ? { end_user_metadata: options.endUserMetadata }\n      : {}),\n    ...(options.connectAttemptId\n      ? { connect_attempt_id: options.connectAttemptId }\n      : {}),\n  };\n}\n"]}