@kaltura-sdk/avatars 1.14.0 → 1.15.0

package/index.esm.js

@@ -1,4 +1,4 @@
-import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor, environmentResolver } from '@unisphere/core';
+import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor } from '@unisphere/core';
 import { getPartnerIdFromKs } from '@unisphere/runtime-js';
 import { DisconnectReasons, getAvatarDefaultCapabilities, resolveActiveContextType, AvatarConnectionStatus } from '@unisphere/genie-types';
 import { z as z$1 } from 'zod/mini';
@@ -6805,6 +6805,7 @@ const genieIntellectState = {
       logger: context.logger,
       getClientToolHandler: context.getClientToolHandler,
       ks: context.externalInfo.kaltura.ks,
+      clientToolResponseUrl: context.externalInfo.runtimeSettings.clientToolResponseUrl,
       threadId: context.threadId
     })
   }
@@ -7607,6 +7608,9 @@ const connectingState = {
       },
       on: {
         [AvatarConnectionMachineEventTypes.ServerReadyReceived]: [{
+          guard: 'shouldAutoJoinSTVPlayer',
+          target: 'joiningSTVPlayer'
+        }, {
           guard: 'shouldWaitPlayerReadyState',
           target: 'waitingPlayerReadyState'
         }, {
@@ -7614,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',
@@ -19463,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
@@ -22597,11 +22674,10 @@ const resolveServerConfig = fromPromise(_a => __awaiter(void 0, [_a], void 0, fu
     logger
   } = input;
   if (runtimeSettings.serverConfig === 'studio') {
-    const agenticServerUrl = environmentResolver.getFriendlyRegionUrl({
-      serviceName: 'api.avatar',
-      type: 'microservice',
-      domainSuffix: 'ai'
-    });
+    if (!runtimeSettings.agenticServerUrl) {
+      throw new Error('Studio mode requires runtimeSettings.agenticServerUrl to be set (the api.avatar service URL)');
+    }
+    const agenticServerUrl = runtimeSettings.agenticServerUrl;
     logger.log('Studio mode: fetching server config from appInit');
     const appInitRes = yield fetch(`${agenticServerUrl}/v1/application/appInit`, {
       method: 'POST',
@@ -22881,10 +22957,6 @@ const onAgentClientToolCall = fromCallback(({
   input,
   sendBack
 }) => {
-  const genieServerUrl = environmentResolver.getKalturaServerUrl({
-    serviceName: 'genie',
-    type: 'microservice'
-  });
   return createTinyPubsubEventsHandler({
     source: source$1,
     logger: input.logger,
@@ -22948,13 +23020,18 @@ const onAgentClientToolCall = fromCallback(({
           void executeClientToolCall({
             toolMetadata,
             getToolHandler: input.getClientToolHandler,
-            sendToolResponse: (toolId, toolName, response) => sendClientToolResponse({
-              genieServerUrl,
-              ks: input.ks,
-              toolId,
-              toolName,
-              response
-            }),
+            sendToolResponse: (toolId, toolName, response) => {
+              if (!input.clientToolResponseUrl) {
+                return Promise.reject(new Error('Cannot send client tool call response: runtimeSettings.clientToolResponseUrl is not configured'));
+              }
+              return sendClientToolResponse({
+                url: input.clientToolResponseUrl,
+                ks: input.ks,
+                toolId,
+                toolName,
+                response
+              });
+            },
             logger: input.logger,
             onCompleted: (toolName, waitForResponse) => {
               sendBack({
@@ -23289,6 +23366,7 @@ const avatarConnectionMachine = setup({
     onConversationEnded,
     onError,
     onPlayerReadyState,
+    joinSTVPlayer,
     onAgentTalking,
     onAgentRawText,
     onConversationTimeWarning,
@@ -23317,6 +23395,7 @@ const avatarConnectionMachine = setup({
     hasMoreRecoveryRetries,
     justExceededRecoveryRetries,
     shouldWaitPlayerReadyState,
+    shouldAutoJoinSTVPlayer,
     shouldDisconnect,
     shouldWaitBeforePurge,
     shouldCreateWebsocketConnection,
@@ -23355,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
@@ -23947,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.0",
+  "version": "1.15.0",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -13,7 +13,7 @@
     "@kaltura-sdk/rtc-core": "^1.25.16",
     "@local/genie-shared-utils": "^1.0.0",
     "@unisphere/core": "^1.99.0",
-    "@unisphere/genie-types": "^1.39.0",
+    "@unisphere/genie-types": "^1.39.1",
     "@unisphere/notifications-core": "^1.25.0",
     "@unisphere/runtime": "^1.98.0",
     "@unisphere/runtime-js": "^1.96.0",

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/actors/on-agent-client-tool-call.d.ts

@@ -4,6 +4,8 @@ type OnAgentClientToolCallInput = {
     logger: UnisphereLoggerType;
     getClientToolHandler: GetAvatarClientToolHandler;
     ks: string;
+    /** Full URL to POST client-tool-call responses to — see `AvatarRuntimeSettings.clientToolResponseUrl`. Required for client tool calls to receive a response; if omitted, tool call responses fail with a `delivery-error`. */
+    clientToolResponseUrl?: string;
     threadId: string | null;
 };
 export declare const onAgentClientToolCall: import("xstate").CallbackActorLogic<AgentClientToolCallCompletedEvent | AgentClientToolCallLoggedEvent, OnAgentClientToolCallInput, 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;
@@ -75,6 +75,7 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
         logger: import("@unisphere/core").UnisphereLoggerType;
         getClientToolHandler: import("dist/unisphere/packages/local/shared-utils/src").GetClientToolHandler;
         ks: string;
+        clientToolResponseUrl?: string | undefined;
         threadId: string | null;
     }, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").CallbackActorLogic<import("./types").TapToTalkButtonShownEvent | import("./types").TapToTalkButtonHiddenEvent, {
         logger: import("@unisphere/core").UnisphereLoggerType;
@@ -174,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, {
@@ -282,6 +287,7 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
         logger: import("@unisphere/core").UnisphereLoggerType;
         getClientToolHandler: import("dist/unisphere/packages/local/shared-utils/src").GetClientToolHandler;
         ks: string;
+        clientToolResponseUrl?: string | undefined;
         threadId: string | null;
     }, import("xstate").EventObject>;
     id: string | undefined;
@@ -544,6 +550,9 @@ export declare const avatarConnectionMachine: import("xstate").StateMachine<Avat
 } | {
     type: "shouldWaitPlayerReadyState";
     params: unknown;
+} | {
+    type: "shouldAutoJoinSTVPlayer";
+    params: unknown;
 } | {
     type: "shouldDisconnect";
     params: unknown;
@@ -592,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";
@@ -663,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/connected-state.d.ts

@@ -562,6 +562,7 @@ export declare const connectedState: {
                     logger: import("@unisphere/core").UnisphereLoggerType;
                     getClientToolHandler: import("dist/unisphere/packages/local/shared-utils/src").GetClientToolHandler;
                     ks: string;
+                    clientToolResponseUrl: string | undefined;
                     threadId: string | null;
                 };
             };

package/src/lib/avatar-client-manager/machines/avatar-connection/states/connected-states/genie-intellect-state.d.ts

@@ -21,6 +21,7 @@ export declare const genieIntellectState: {
             logger: import("@unisphere/core").UnisphereLoggerType;
             getClientToolHandler: import("dist/unisphere/packages/local/shared-utils/src").GetClientToolHandler;
             ks: string;
+            clientToolResponseUrl: string | undefined;
             threadId: string | null;
         };
     };

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;