@kaltura-sdk/avatars 1.14.1 → 1.15.0

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
@@ -23948,6 +24027,7 @@ class AvatarClientManager extends ActorManager {
           showNotification: this._config.actions.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,

package/package.json

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

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

@@ -66,6 +66,8 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
         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;