@kaltura-sdk/avatars 1.14.1 → 1.15.1

package/README.md

@@ -1 +1,47 @@
-# Unisphere Genie - Package Avatars
+# @kaltura-sdk/avatars
+
+Core implementation of `AvatarClientManager` — the state machine-driven client for Kaltura's conversational avatar. Runs on `xstate` + `@unisphere/core` reactive stores; owns the whole connection lifecycle (RTC session, chat, captions, screen share, tap-to-talk, client tools, Kaltura context).
+
+For a framework-free, CDN-loadable build, use [`@kaltura-sdk/avatars-esm`](../avatars-esm) — it re-exports this package.
+
+## Usage
+
+```ts
+import { AvatarClientManager } from '@kaltura-sdk/avatars';
+
+const manager = new AvatarClientManager({
+  actions: { showNotification }, // optional, defaults to a noop
+  debugMode: true, // optional, default false
+  logger, // optional — UnisphereLoggerType, defaults to an internal 'avatar-client' logger
+  runtimeSettings, // AvatarRuntimeSettings
+  kalturaAnalyticsService, // optional, no-ops if omitted
+  pubSubService, // optional, no-ops if omitted
+  registerDeveloperTools: (actor) => {}, // optional, e.g. xstate inspector
+  videoContainerId: 'avatar-video', // optional — auto-joins STV once castMode is "webrtc"
+});
+
+manager.connectionStatus.onChanges((status) => console.log(status));
+manager.connect({ dynamicVariables, kickOffPhrase });
+manager.disconnect();
+manager.stop(); // full teardown, unsubscribes everything
+```
+
+`connect()`/`disconnect()` are sync (fire-and-forget) — read outcomes off the reactive stores (`connectionStatus`, `castMode`, `disconnectData`, etc).
+
+## API surface
+
+- **Lifecycle**: `connect()`, `disconnect()`, `reconnect()`, `stop()`, `connectionStatus`, `playerUrl`, `sessionId`, `castMode`, `turnServerURL`, `disconnectData`
+- **Pause/resume**: `pause()`, `resume()`, `pauseAfterSpeaking()`, `isPaused`
+- **Chat & content**: `askViaText()`, `chatLog`, `content`, `setLocalContent()`, `clearContent()`, `agentData`
+- **Screen share**: `startScreenShare()`, `stopScreenShare()`, `screenShareInfo`
+- **Tap-to-talk**: `tapToTalkStart()`, `tapToTalkEnd()`, `toggleTapToTalkMode()`, `tapToTalkInfo`
+- **Captions**: `captions` (state + `toggle`/`setReplacements`/`setFilter`)
+- **Kaltura context**: `kalturaContext`, `toggleKalturaContext()`, `updateDynamicVariables()`
+- **Client tools**: `registerClientTools()`, `unregisterClientTools()`, `registeredClientTools`, `clientToolCallLog`
+- **Session metadata**: `threadId`, `setExternalThreadId()`, `isPreviewMode`, `contextSelectorVisible`, `features`, `agentPreviewUrl`, `agentPreviewImageUrl`, `serverUrl`
+- **RTC/device passthrough**: `audioState`, `audioVolumeLevel`, `devicesList`, `joinSTV()`, `leaveSTV()`, `changeDevice()`, `toggleMuteAudio()`
+- **Player events**: `onPlayerReady()`, `onPlayerError()`
+
+All getters return `@unisphere/core` reactive stores (`.consumer`, subscribe via `.onChanges`).
+
+`connection` is a deprecated back-compat facade kept only for consumers not yet migrated to the manager's own getters/methods.

package/index.esm.js

@@ -7608,6 +7608,9 @@ const connectingState = {
       },
       on: {
         [AvatarConnectionMachineEventTypes.ServerReadyReceived]: [{
+          guard: 'shouldAutoJoinSTVPlayer',
+          target: 'joiningSTVPlayer'
+        }, {
           guard: 'shouldWaitPlayerReadyState',
           target: 'waitingPlayerReadyState'
         }, {
@@ -7615,6 +7618,39 @@ const connectingState = {
         }]
       }
     },
+    joiningSTVPlayer: {
+      invoke: {
+        id: 'joinSTVPlayer',
+        src: 'joinSTVPlayer',
+        input: ({
+          context
+        }) => ({
+          logger: context.logger,
+          // videoContainerId presence is enforced by the shouldAutoJoinSTVPlayer guard
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          videoContainerId: context.externalInfo.videoContainerId,
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          sessionId: context.sessionId,
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          webrtcUrl: context.webrtcUrl
+        }),
+        onDone: {
+          target: 'delayingBeforeConnect'
+        },
+        onError: {
+          actions: {
+            type: 'setDisconnectData',
+            params: ({
+              event
+            }) => ({
+              reason: DisconnectReasons.PlayerConnectionFailed,
+              error: event.error
+            })
+          },
+          target: 'error'
+        }
+      }
+    },
     waitingPlayerReadyState: {
       invoke: {
         src: 'onPlayerReadyState',
@@ -19464,12 +19500,52 @@ const onPlayerReadyState = fromCallback(({
   });
 });
 
+/**
+ * Auto-join the STV (webrtc) video stream into a caller-provided container
+ * element, on behalf of consumers that configured `videoContainerId` on the
+ * `AvatarClientManager` constructor instead of managing joinSTV/leaveSTV
+ * themselves (e.g. avatar-react's STVPlayer keeps doing that manually and
+ * never reaches this actor — see `shouldAutoJoinSTVPlayer`).
+ *
+ * Resolves once the STV peer connection is established (mirrors the
+ * `onConnected` callback consumers pass to `joinSTV` directly), not merely
+ * once WebRTC signaling completes.
+ */
+const joinSTVPlayer = fromPromise(_a => __awaiter(void 0, [_a], void 0, function* ({
+  input
+}) {
+  const {
+    logger,
+    videoContainerId,
+    sessionId,
+    webrtcUrl
+  } = input;
+  logger.log('Auto-joining STV player...', {
+    data: {
+      videoContainerId,
+      sessionId
+    }
+  });
+  yield new Promise((resolve, reject) => {
+    avatarRTCClientManager.joinSTV(videoContainerId, sessionId, webrtcUrl, () => {
+      logger.log('STV player auto-joined and connected');
+      resolve();
+    }).catch(reject);
+  });
+}));
+
 const shouldWaitPlayerReadyState = ({
   context
 }) => {
   return context.externalInfo.waitPlayerReadyState === true;
 };
 
+const shouldAutoJoinSTVPlayer = ({
+  context
+}) => {
+  return context.castMode === 'webrtc' && !!context.externalInfo.videoContainerId;
+};
+
 const setContentData = assign$1(({
   context,
   event
@@ -23290,6 +23366,7 @@ const avatarConnectionMachine = setup({
     onConversationEnded,
     onError,
     onPlayerReadyState,
+    joinSTVPlayer,
     onAgentTalking,
     onAgentRawText,
     onConversationTimeWarning,
@@ -23318,6 +23395,7 @@ const avatarConnectionMachine = setup({
     hasMoreRecoveryRetries,
     justExceededRecoveryRetries,
     shouldWaitPlayerReadyState,
+    shouldAutoJoinSTVPlayer,
     shouldDisconnect,
     shouldWaitBeforePurge,
     shouldCreateWebsocketConnection,
@@ -23356,6 +23434,7 @@ const avatarConnectionMachine = setup({
         debugMode: input.debugMode,
         level: (_b = input.level) !== null && _b !== void 0 ? _b : 'published',
         waitPlayerReadyState: (_c = input.waitPlayerReadyState) !== null && _c !== void 0 ? _c : true,
+        videoContainerId: input.videoContainerId,
         kaltura: input.runtimeSettings.kaltura,
         features: Object.assign(Object.assign({}, input.runtimeSettings.features), {
           kickOffPhrase: (_d = input.kickOffPhrase) !== null && _d !== void 0 ? _d : (_e = input.runtimeSettings.features) === null || _e === void 0 ? void 0 : _e.kickOffPhrase
@@ -23551,6 +23630,11 @@ const noopPubSubService = {
     // noop
   }
 };
+const noopAvatarClientManagerActions = {
+  showNotification: () => {
+    // noop
+  }
+};
 /**
  * Avatar-domain manager on top of the generic `ActorManager` engine: owns
  * the `avatarConnectionMachine` actor and exposes it as reactive stores +
@@ -23561,6 +23645,7 @@ const noopPubSubService = {
  */
 class AvatarClientManager extends ActorManager {
   constructor(_config) {
+    var _a;
     super();
     this._config = _config;
     // keep separate from other subscriptions since we don't want to stop when disconnect only when stop called
@@ -23711,7 +23796,7 @@ class AvatarClientManager extends ActorManager {
     this._contextSelectorVisible = new TinyDataStore({
       initialValue: true
     });
-    this._logger = this._config.logger;
+    this._logger = (_a = this._config.logger) !== null && _a !== void 0 ? _a : avatarClientLoggerFactory.getOrCreateLogger('service', 'avatar-client');
     if (this._config.runtimeSettings.features) {
       this._features.setData(() => this._config.runtimeSettings.features);
     }
@@ -23923,7 +24008,7 @@ class AvatarClientManager extends ActorManager {
     return this._agentData.consumer;
   }
   connect(options) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     this._lastConnectOptions = options;
     this._onThreadIdChange = options === null || options === void 0 ? void 0 : options.onThreadIdChange;
     if (this._connection.getData()) {
@@ -23941,26 +24026,27 @@ class AvatarClientManager extends ActorManager {
       input: Object.assign({
         connectionId,
         logger: this._logger,
-        debugMode: this._config.debugMode,
-        kalturaAnalyticsService: (_a = this._config.kalturaAnalyticsService) !== null && _a !== void 0 ? _a : noopKalturaAnalyticsService,
-        pubSubService: (_b = this._config.pubSubService) !== null && _b !== void 0 ? _b : noopPubSubService,
+        debugMode: (_a = this._config.debugMode) !== null && _a !== void 0 ? _a : false,
+        kalturaAnalyticsService: (_b = this._config.kalturaAnalyticsService) !== null && _b !== void 0 ? _b : noopKalturaAnalyticsService,
+        pubSubService: (_c = this._config.pubSubService) !== null && _c !== void 0 ? _c : noopPubSubService,
         externalActions: {
-          showNotification: this._config.actions.showNotification
+          showNotification: ((_d = this._config.actions) !== null && _d !== void 0 ? _d : noopAvatarClientManagerActions).showNotification
         },
         runtimeSettings: this._config.runtimeSettings,
+        videoContainerId: this._config.videoContainerId,
         isInitialKalturaContextActive: this._isKalturaContextActive,
         dynamicVariables: options === null || options === void 0 ? void 0 : options.dynamicVariables,
         kickOffPhrase: options === null || options === void 0 ? void 0 : options.kickOffPhrase,
         clientToolsRegistry: this._clientToolsRegistry,
         getClientToolHandler: this._getClientToolHandler
-      }, ((_c = options === null || options === void 0 ? void 0 : options.context) === null || _c === void 0 ? void 0 : _c.type) === 'thread' && {
+      }, ((_e = options === null || options === void 0 ? void 0 : options.context) === null || _e === void 0 ? void 0 : _e.type) === 'thread' && {
         threadId: options.context.threadId,
         messageId: options.context.messageId
       })
     });
     this._logsInitialized = false;
     this._setupActorSync(actor);
-    (_e = (_d = this._config).registerDeveloperTools) === null || _e === void 0 ? void 0 : _e.call(_d, actor);
+    (_g = (_f = this._config).registerDeveloperTools) === null || _g === void 0 ? void 0 : _g.call(_f, actor);
     actor.start();
   }
   disconnect() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaltura-sdk/avatars",
-  "version": "1.14.1",
+  "version": "1.15.1",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {

package/src/lib/avatar-client-manager/avatar-client-manager.d.ts

@@ -58,14 +58,16 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     private readonly _isPreviewMode;
     private readonly _contextSelectorVisible;
     constructor(_config: {
-        actions: AvatarClientManagerActions;
-        debugMode: boolean;
-        logger: UnisphereLoggerType;
+        actions?: AvatarClientManagerActions;
+        debugMode?: boolean;
+        logger?: UnisphereLoggerType;
         kalturaAnalyticsService?: KalturaAnalyticsServiceType;
         pubSubService?: PubSubServiceType;
         runtimeSettings: AvatarRuntimeSettings;
         /** Optional hook for wiring up devtools/machine-inspector logging; left unset outside the Unisphere widget host. */
         registerDeveloperTools?: (actor: AvatarConnectionActor) => void;
+        /** DOM element id of a container div the SDK should inject its `<video>` element into and auto-join the STV stream against, once castMode is 'webrtc'. Omit to keep managing joinSTV/leaveSTV externally (e.g. avatar-react's STVPlayer). */
+        videoContainerId?: string;
     });
     protected _syncDerivedState(snapshot: ConnectionSnapshot): void;
     protected _isTerminalSnapshot(snapshot: ConnectionSnapshot): boolean;

package/src/lib/avatar-client-manager/machines/avatar-connection/actors/join-stv-player.d.ts

@@ -0,0 +1,22 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+/**
+ * Input parameters for the joinSTVPlayer actor
+ */
+export interface JoinSTVPlayerInput {
+    logger: UnisphereLoggerType;
+    videoContainerId: string;
+    sessionId: string;
+    webrtcUrl: string;
+}
+/**
+ * Auto-join the STV (webrtc) video stream into a caller-provided container
+ * element, on behalf of consumers that configured `videoContainerId` on the
+ * `AvatarClientManager` constructor instead of managing joinSTV/leaveSTV
+ * themselves (e.g. avatar-react's STVPlayer keeps doing that manually and
+ * never reaches this actor — see `shouldAutoJoinSTVPlayer`).
+ *
+ * Resolves once the STV peer connection is established (mirrors the
+ * `onConnected` callback consumers pass to `joinSTV` directly), not merely
+ * once WebRTC signaling completes.
+ */
+export declare const joinSTVPlayer: import("xstate").PromiseActorLogic<void, JoinSTVPlayerInput, import("xstate").EventObject>;

package/src/lib/avatar-client-manager/machines/avatar-connection/avatar-connection-machine.d.ts

@@ -37,7 +37,7 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
         logger: import("@unisphere/core").UnisphereLoggerType;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").CallbackActorLogic<import("./types").PlayerReadyEvent, {
         logger: import("@unisphere/core").UnisphereLoggerType;
-    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").CallbackActorLogic<import("./types").AgentStartedTalkingReceivedEvent | import("./types").AgentFinishedTalkingReceivedEvent, {
+    }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<void, import("./actors/join-stv-player").JoinSTVPlayerInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").CallbackActorLogic<import("./types").AgentStartedTalkingReceivedEvent | import("./types").AgentFinishedTalkingReceivedEvent, {
         logger: import("@unisphere/core").UnisphereLoggerType;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").CallbackActorLogic<import("./types").AgentRawTextMessageCompletedEvent, {
         logger: import("@unisphere/core").UnisphereLoggerType;
@@ -175,6 +175,10 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
         logger: import("@unisphere/core").UnisphereLoggerType;
     }, import("xstate").EventObject>;
     id: string | undefined;
+} | {
+    src: "joinSTVPlayer";
+    logic: import("xstate").PromiseActorLogic<void, import("./actors/join-stv-player").JoinSTVPlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
 } | {
     src: "onAgentTalking";
     logic: import("xstate").CallbackActorLogic<import("./types").AgentStartedTalkingReceivedEvent | import("./types").AgentFinishedTalkingReceivedEvent, {
@@ -546,6 +550,9 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
 } | {
     type: "shouldWaitPlayerReadyState";
     params: unknown;
+} | {
+    type: "shouldAutoJoinSTVPlayer";
+    params: unknown;
 } | {
     type: "shouldDisconnect";
     params: unknown;
@@ -594,7 +601,7 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
 }, never, "error" | "devicePermissionsDenied" | {
     preparing: "done" | "resolvingConfig" | "gettingUserAgentData" | "retryingConfig";
 } | {
-    connecting: "error" | "done" | "initializingRTCSession" | "gettingUserMedia" | "connectingWebsocket" | "waitingServerConnect" | "creatingSession" | "waitingForAgent" | "reconnectingFromExpiry" | "waitingServerReady" | "waitingPlayerReadyState" | "connectingToASR" | "delayingBeforeConnect" | {
+    connecting: "error" | "done" | "initializingRTCSession" | "gettingUserMedia" | "connectingWebsocket" | "waitingServerConnect" | "creatingSession" | "waitingForAgent" | "reconnectingFromExpiry" | "waitingServerReady" | "joiningSTVPlayer" | "waitingPlayerReadyState" | "connectingToASR" | "delayingBeforeConnect" | {
         joiningRoom: {
             waitingClientConfiguration: "done" | "waiting";
             waitingJoinComplete: "done" | "waiting";
@@ -665,6 +672,7 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
                 reconnectingFromExpiry: {};
                 waitingForAgent: {};
                 waitingServerReady: {};
+                joiningSTVPlayer: {};
                 waitingPlayerReadyState: {};
                 delayingBeforeConnect: {};
                 connectingToASR: {};

package/src/lib/avatar-client-manager/machines/avatar-connection/guards/should-auto-join-stv-player.d.ts

@@ -0,0 +1,4 @@
+import { AvatarConnectionMachineContext } from '../types';
+export declare const shouldAutoJoinSTVPlayer: ({ context, }: {
+    context: AvatarConnectionMachineContext;
+}) => boolean;

package/src/lib/avatar-client-manager/machines/avatar-connection/states/connecting-state.d.ts

@@ -317,6 +317,9 @@ export declare const connectingState: {
             };
             on: {
                 ServerReadyReceived: ({
+                    guard: "shouldAutoJoinSTVPlayer";
+                    target: string;
+                } | {
                     guard: "shouldWaitPlayerReadyState";
                     target: string;
                 } | {
@@ -325,6 +328,37 @@ export declare const connectingState: {
                 })[];
             };
         };
+        joiningSTVPlayer: {
+            invoke: {
+                id: string;
+                src: "joinSTVPlayer";
+                input: ({ context }: {
+                    context: import("../types").AvatarConnectionMachineContext;
+                    event: import("../types").AvatarConnectionMachineEvents;
+                    self: import("xstate").ActorRef<import("xstate").MachineSnapshot<import("../types").AvatarConnectionMachineContext, import("../types").AvatarConnectionMachineEvents, Record<string, import("xstate").AnyActorRef>, import("xstate").StateValue, string, unknown, any, any>, import("../types").AvatarConnectionMachineEvents, import("xstate").AnyEventObject>;
+                }) => {
+                    logger: import("@unisphere/core").UnisphereLoggerType;
+                    videoContainerId: string;
+                    sessionId: string;
+                    webrtcUrl: string;
+                };
+                onDone: {
+                    target: string;
+                };
+                onError: {
+                    actions: {
+                        type: "setDisconnectData";
+                        params: ({ event }: {
+                            event: ErrorActorEvent;
+                        }) => {
+                            reason: DisconnectReasons;
+                            error: Error;
+                        };
+                    };
+                    target: string;
+                };
+            };
+        };
         waitingPlayerReadyState: {
             invoke: {
                 src: "onPlayerReadyState";

package/src/lib/avatar-client-manager/machines/avatar-connection/types/context.d.ts

@@ -20,6 +20,7 @@ export interface AvatarConnectionMachineContext {
         debugMode: boolean;
         level: string;
         waitPlayerReadyState: boolean;
+        videoContainerId?: string;
         kaltura: {
             ks: string;
             context?: ChatContext;

package/src/lib/avatar-client-manager/machines/avatar-connection/types/input.d.ts

@@ -20,6 +20,8 @@ export interface AvatarConnectionMachineInput {
     stickyId?: string;
     level?: string;
     waitPlayerReadyState?: boolean;
+    /** DOM element id of a container div the SDK should inject its `<video>` element into and auto-join the STV stream against, once castMode is 'webrtc'. Omit to keep managing joinSTV/leaveSTV externally (e.g. avatar-react's STVPlayer). */
+    videoContainerId?: string;
     isInitialKalturaContextActive?: boolean;
     threadId?: string;
     messageId?: string;