@kaltura-sdk/avatars 1.20.0 → 1.21.1

package/index.esm.js

@@ -1,4 +1,4 @@
-import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor } from '@unisphere/core';
+import { UnisphereLoggerFactory, TinyDataStore, TinyPubSub, performanceMonitor, getOrCreateGlobalTinyDataStore } 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';
@@ -23828,6 +23828,103 @@ const avatarConnectionMachine = setup({
   }
 });
 
+const ACTIVE_SESSION_STORE_ID = 'agenticExperienceAvatar';
+function createId() {
+  return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/**
+ * Page-wide "who owns the call" record for one avatar manager. Takeover is
+ * just overwriting the shared record: the previous owner sees an id that is
+ * no longer its own and ends its own call (a close callback could not cross
+ * frames).
+ */
+class ActiveSessionCoordinator {
+  constructor(_options) {
+    this._options = _options;
+    this.id = createId();
+    this._owns = false;
+    this._conflict = new TinyDataStore({
+      initialValue: null,
+      compare: 'deep'
+    });
+    this._win = window;
+    this._onPageHide = () => this.release();
+    this._logger = _options.logger;
+    this._global = getOrCreateGlobalTinyDataStore({
+      id: ACTIVE_SESSION_STORE_ID,
+      initialValue: null,
+      logger: _options.logger
+    });
+    this._unsubscribe = this._global.onChanges(value => this._handle(value));
+    // A closed iframe must not leave the page locked.
+    this._win.addEventListener('pagehide', this._onPageHide);
+  }
+  /** The active session owned by another avatar, or null */
+  get conflict() {
+    return this._conflict.consumer;
+  }
+  claim(preventDisconnections) {
+    var _a, _b;
+    if (this._owns && ((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.preventDisconnections) === preventDisconnections) {
+      return;
+    }
+    this._owns = true;
+    (_b = this._logger) === null || _b === void 0 ? void 0 : _b.log('claiming the active avatar session', {
+      data: {
+        id: this.id,
+        preventDisconnections
+      }
+    });
+    this._global.setData(() => ({
+      id: this.id,
+      preventDisconnections
+    }));
+  }
+  /** Republishes the flag only while this avatar owns the call; never claims an idle one */
+  updateFlag(preventDisconnections) {
+    var _a, _b;
+    if (this._owns && ((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.id) === this.id && ((_b = this._global.getData()) === null || _b === void 0 ? void 0 : _b.preventDisconnections) !== preventDisconnections) {
+      this._global.setData(() => ({
+        id: this.id,
+        preventDisconnections
+      }));
+    }
+  }
+  /** Clears the record only if it is still ours, so a taken-over avatar can't wipe the new owner */
+  release() {
+    var _a, _b;
+    this._owns = false;
+    if (((_a = this._global.getData()) === null || _a === void 0 ? void 0 : _a.id) === this.id) {
+      (_b = this._logger) === null || _b === void 0 ? void 0 : _b.log('releasing the active avatar session', {
+        data: {
+          id: this.id
+        }
+      });
+      this._global.setData(() => null);
+    }
+  }
+  dispose() {
+    this.release();
+    this._unsubscribe();
+    this._win.removeEventListener('pagehide', this._onPageHide);
+  }
+  _handle(value) {
+    var _a;
+    const other = value && value.id !== this.id ? value : null;
+    this._conflict.setData(() => other);
+    if (other && this._owns) {
+      this._owns = false;
+      (_a = this._logger) === null || _a === void 0 ? void 0 : _a.log('active avatar session taken over by another avatar', {
+        data: {
+          id: this.id,
+          by: other.id
+        }
+      });
+      this._options.onTakenOver();
+    }
+  }
+}
+
 function setIfChanged(store, next, eq = (a, b) => a === b) {
   if (!eq(store.getData(), next)) {
     store.setData(() => next);
@@ -24108,7 +24205,20 @@ class AvatarClientManager extends ActorManager {
     this._contextSelectorVisible = new TinyDataStore({
       initialValue: true
     });
+    this._multipleAvatarBehavior = new TinyDataStore({
+      initialValue: {
+        preventDisconnections: false
+      },
+      compare: 'deep'
+    });
+    this._isTakeoverPending = new TinyDataStore({
+      initialValue: false
+    });
     this._logger = (_a = this._config.logger) !== null && _a !== void 0 ? _a : avatarClientLoggerFactory.getOrCreateLogger('service', 'avatar-client');
+    this._activeSession = new ActiveSessionCoordinator({
+      onTakenOver: () => this.disconnect(),
+      logger: this._logger
+    });
     if (this._config.runtimeSettings.features) {
       this._features.setData(() => this._config.runtimeSettings.features);
     }
@@ -24121,6 +24231,19 @@ class AvatarClientManager extends ActorManager {
       return this._config.runtimeSettings.serverConfig === 'manual' ? (_a = this._config.runtimeSettings.loadingVideoURL) !== null && _a !== void 0 ? _a : null : null;
     });
     this._setupKalturaContext();
+    this._multipleAvatarBehavior.setData(() => {
+      var _a, _b;
+      return {
+        preventDisconnections: (_b = (_a = this._config.runtimeSettings.multipleAvatarBehavior) === null || _a === void 0 ? void 0 : _a.preventDisconnections) !== null && _b !== void 0 ? _b : false
+      };
+    });
+    this._status.onChanges(status => {
+      if (status === AvatarConnectionStatus.NotConnected || status === AvatarConnectionStatus.Disconnected || status === AvatarConnectionStatus.Error) {
+        this._activeSession.release();
+      }
+    }, {
+      replayLastValue: false
+    });
   }
   // ────────────────────────────────────────────────────────────────────────
   // Private: connection engine
@@ -24327,6 +24450,18 @@ class AvatarClientManager extends ActorManager {
       this._logger.log(`Avatar client already connected`);
       return;
     }
+    const conflict = this._activeSession.conflict.getData();
+    if (conflict) {
+      this._logger.log('Connect pending: another avatar is in a call', {
+        data: {
+          preventDisconnections: conflict.preventDisconnections
+        }
+      });
+      this._pendingTakeoverOptions = options;
+      this._isTakeoverPending.setData(() => true);
+      return;
+    }
+    this._activeSession.claim(this._multipleAvatarBehavior.getData().preventDisconnections);
     const connectionId = 'main';
     this._logger.log(`Connecting to avatar client with connection ID: ${connectionId}`);
     timingTracker.runtimeConnectTime = performance.now();
@@ -24382,6 +24517,22 @@ class AvatarClientManager extends ActorManager {
   reconnect() {
     this.connect(this._lastConnectOptions);
   }
+  confirmTakeover() {
+    var _a;
+    if (!this._isTakeoverPending.getData() || ((_a = this._activeSession.conflict.getData()) === null || _a === void 0 ? void 0 : _a.preventDisconnections)) {
+      return;
+    }
+    const options = this._pendingTakeoverOptions;
+    this._pendingTakeoverOptions = undefined;
+    this._isTakeoverPending.setData(() => false);
+    // Overwriting the page-wide record makes the other avatar end its own call.
+    this._activeSession.claim(this._multipleAvatarBehavior.getData().preventDisconnections);
+    this.connect(options);
+  }
+  cancelTakeover() {
+    this._pendingTakeoverOptions = undefined;
+    this._isTakeoverPending.setData(() => false);
+  }
   // ────────────────────────────────────────────────────────────────────────
   // Public API: pause / resume
   // ────────────────────────────────────────────────────────────────────────
@@ -24584,6 +24735,23 @@ class AvatarClientManager extends ActorManager {
   setIsPreviewMode(value) {
     this._isPreviewMode.setData(() => value);
   }
+  get multipleAvatarBehavior() {
+    return this._multipleAvatarBehavior.consumer;
+  }
+  setMultipleAvatarBehavior(value) {
+    var _a;
+    const preventDisconnections = (_a = value === null || value === void 0 ? void 0 : value.preventDisconnections) !== null && _a !== void 0 ? _a : false;
+    this._multipleAvatarBehavior.setData(() => ({
+      preventDisconnections
+    }));
+    this._activeSession.updateFlag(preventDisconnections);
+  }
+  get activeSessionConflict() {
+    return this._activeSession.conflict;
+  }
+  get isTakeoverPending() {
+    return this._isTakeoverPending.consumer;
+  }
   get contextSelectorVisible() {
     return this._contextSelectorVisible.consumer;
   }
@@ -24661,6 +24829,7 @@ class AvatarClientManager extends ActorManager {
     var _a;
     (_a = this._unsubscribeContextActive) === null || _a === void 0 ? void 0 : _a.call(this);
     this._unsubscribeContextActive = null;
+    this._activeSession.dispose();
     this._cleanupConnection();
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaltura-sdk/avatars",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -12,14 +12,15 @@
     "@kaltura-sdk/rtc-avatar": "^1.33.4",
     "@kaltura-sdk/rtc-core": "^1.26.2",
     "@local/genie-shared-utils": "^1.0.0",
-    "@unisphere/core": "^1.99.0",
-    "@unisphere/genie-types": "^1.46.0",
+    "@unisphere/core": "^1.101.1",
+    "@unisphere/genie-types": "^1.47.0",
     "@unisphere/notifications-core": "^1.25.0",
     "@unisphere/runtime": "^1.98.0",
     "@unisphere/runtime-js": "^1.98.0",
     "immer": "^10.1.1",
     "js-yaml": "^4.1.0",
     "socket.io-client": "^4.8.1",
+    "vitest": "^3.2.7",
     "zod": "^4.2.0"
   },
   "module": "./index.esm.js",

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

@@ -1,6 +1,6 @@
 import { UnisphereLoggerType } from '@unisphere/core';
 import { KalturaAnalyticsServiceType, PubSubServiceType } from '@unisphere/runtime';
-import { AgentData, AgentKalturaContextData, AgentProgressBar, AgentScreenShareInfo, AgentTapToTalkInfo, AvatarClientManagerType, AvatarConnectionProxInternalType, AvatarConnectionProxyType, AvatarConnectionStatus, AvatarContentData, AvatarRuntimeSettings, CaptionConfig, Captions, ChatEntry, ClientToolCallLogEntry, DisconnectReasons, TapToTalkStartOptions } from '@unisphere/genie-types';
+import { AgentData, AgentKalturaContextData, AgentProgressBar, AgentScreenShareInfo, AgentTapToTalkInfo, AvatarClientManagerType, AvatarConnectionProxInternalType, AvatarConnectionProxyType, AvatarConnectionStatus, AvatarContentData, AvatarRuntimeSettings, CaptionConfig, Captions, ChatEntry, ClientToolCallLogEntry, DisconnectReasons, MultipleAvatarBehavior, TapToTalkStartOptions } from '@unisphere/genie-types';
 import { type AvatarClientToolsInput, type AvatarConnectionActor } from './machines/avatar-connection';
 import { AvatarClientManagerActions } from './types';
 import { DeviceType } from '@kaltura-sdk/rtc-core';
@@ -58,6 +58,10 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     private _features;
     private readonly _isPreviewMode;
     private readonly _contextSelectorVisible;
+    private readonly _multipleAvatarBehavior;
+    private readonly _isTakeoverPending;
+    private _pendingTakeoverOptions;
+    private readonly _activeSession;
     constructor(_config: {
         actions?: AvatarClientManagerActions;
         debugMode?: boolean;
@@ -113,6 +117,8 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     }): void;
     disconnect(): void;
     reconnect(): void;
+    confirmTakeover(): void;
+    cancelTakeover(): void;
     get isPaused(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     pause(): void;
     resume(): void;
@@ -149,6 +155,10 @@ export declare class AvatarClientManager extends ActorManager<AvatarConnectionAc
     setExternalThreadId(id: string | null): void;
     get isPreviewMode(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     setIsPreviewMode(value: boolean): void;
+    get multipleAvatarBehavior(): import("@unisphere/core").TinyDataStoreConsumer<MultipleAvatarBehavior>;
+    setMultipleAvatarBehavior(value: MultipleAvatarBehavior | undefined): void;
+    get activeSessionConflict(): import("@unisphere/core").TinyDataStoreConsumer<import("@unisphere/genie-types").ActiveAvatarSession | null>;
+    get isTakeoverPending(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     get contextSelectorVisible(): import("@unisphere/core").TinyDataStoreConsumer<boolean>;
     setContextSelectorVisible(value: boolean): void;
     get features(): import("@unisphere/core").TinyDataStoreConsumer<{

package/src/lib/avatar-client-manager/utils/active-session-coordinator.d.ts

@@ -0,0 +1,33 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+import type { ActiveAvatarSession } from '@unisphere/genie-types';
+export declare const ACTIVE_SESSION_STORE_ID = "agenticExperienceAvatar";
+/**
+ * Page-wide "who owns the call" record for one avatar manager. Takeover is
+ * just overwriting the shared record: the previous owner sees an id that is
+ * no longer its own and ends its own call (a close callback could not cross
+ * frames).
+ */
+export declare class ActiveSessionCoordinator {
+    private readonly _options;
+    readonly id: string;
+    private _owns;
+    private readonly _conflict;
+    private readonly _global;
+    private readonly _unsubscribe;
+    private readonly _win;
+    private readonly _onPageHide;
+    private readonly _logger?;
+    constructor(_options: {
+        onTakenOver: () => void;
+        logger?: UnisphereLoggerType;
+    });
+    /** The active session owned by another avatar, or null */
+    get conflict(): import("@unisphere/core").TinyDataStoreConsumer<ActiveAvatarSession | null>;
+    claim(preventDisconnections: boolean): void;
+    /** Republishes the flag only while this avatar owns the call; never claims an idle one */
+    updateFlag(preventDisconnections: boolean): void;
+    /** Clears the record only if it is still ours, so a taken-over avatar can't wipe the new owner */
+    release(): void;
+    dispose(): void;
+    private _handle;
+}

package/src/lib/test-utils/create-frame-api.d.ts

@@ -0,0 +1,11 @@
+import type { ActiveSessionCoordinator } from '../avatar-client-manager/utils/active-session-coordinator';
+type CoordinatorOptions = ConstructorParameters<typeof ActiveSessionCoordinator>[0];
+export declare function getRealTopWindow(): Window;
+export declare function addFrame(parent: Window): Window;
+export declare function installBrowserLikePostMessage(windows: Window[]): void;
+export declare function createFrameApi(win: Window): Promise<{
+    createCoordinator: (options: CoordinatorOptions) => ActiveSessionCoordinator;
+    cleanup: () => void;
+}>;
+export declare const flush: () => Promise<unknown>;
+export {};