@unisphere/genie-types 1.13.1 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unisphere/genie-types",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "author": "kaltura",
   "license": "AGPL-3.0",
   "repository": {
@@ -9,9 +9,9 @@
   },
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@kaltura-corp/unisphere-rtc-core": "^1.22.1",
-    "@unisphere/core": "^1.91.1",
-    "@unisphere/runtime": "^1.90.1"
+    "@kaltura-sdk/rtc-core": "^1.25.2",
+    "@unisphere/core": "^1.94.1",
+    "@unisphere/runtime": "^1.91.0"
   },
   "module": "./index.esm.js",
   "type": "module",

package/src/index.d.ts

@@ -14,3 +14,6 @@ export * from './lib/nvidia-2026-event-tool-runtime';
 export * from './lib/kaltura-video-player-tool-runtime';
 export * from './lib/gtc-agenda-tool-runtime';
 export * from './lib/gtc-agenda-list-tool-runtime';
+export * from './lib/gen-ui-composer-tool-runtime';
+export * from './lib/gen-ui-components-tool-runtime';
+export * from './lib/content-gallery-tool-runtime';

package/src/lib/admin-demo-runtime/runtime-types.d.ts

@@ -1,5 +1,14 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Configuration settings for the admin demo runtime.
+ *
+ * @example
+ * ```typescript
+ * const settings: AdminDemoRuntimeSettings = {};
+ * ```
+ */
 export interface AdminDemoRuntimeSettings {
 }
 export declare const adminDemoRuntimeSettingsSchema: ValidatorSchema;
+/** Runtime name constant for admin demo experiences */
 export declare const AdminDemoRuntimeName: "admin-demo";

package/src/lib/admin-runtime/runtime-types.d.ts

@@ -1,8 +1,33 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Configuration settings for the admin runtime.
+ *
+ * @example
+ * Basic admin setup:
+ * ```typescript
+ * const settings: AdminRuntimeSettings = {
+ *   ks: 'your-kaltura-session-token'
+ * };
+ * ```
+ *
+ * @example
+ * With partner configuration:
+ * ```typescript
+ * const settings: AdminRuntimeSettings = {
+ *   ks: 'your-kaltura-session-token',
+ *   partnerId: '12345',
+ *   uiConfId: '54321'
+ * };
+ * ```
+ */
 export interface AdminRuntimeSettings {
+    /** Kaltura session token for authentication */
     ks: string;
+    /** UI configuration ID */
     uiConfId?: string;
+    /** Kaltura partner ID */
     partnerId?: string;
 }
 export declare const adminRuntimeSettingsSchema: ValidatorSchema;
+/** Runtime name constant for admin experiences */
 export declare const AdminRuntimeName: "admin";

package/src/lib/application-runtime/runtime-types.d.ts

@@ -1,17 +1,53 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Configuration settings for the application runtime.
+ *
+ * @example
+ * Basic application setup:
+ * ```typescript
+ * const settings: ApplicationRuntimeSettings = {
+ *   pid: 'partner-12345',
+ *   ks: 'your-kaltura-session-token',
+ *   kalturaServerURI: 'https://www.kaltura.com'
+ * };
+ * ```
+ *
+ * @example
+ * With custom source URL generation:
+ * ```typescript
+ * const settings: ApplicationRuntimeSettings = {
+ *   pid: 'partner-12345',
+ *   ks: 'your-kaltura-session-token',
+ *   kalturaServerURI: 'https://www.kaltura.com',
+ *   widgetId: 'widget_abc',
+ *   genieServerUrl: 'https://genie.example.com',
+ *   getSourceUrl: ({ entryId, startTime }) =>
+ *     `https://example.com/media/${entryId}${startTime ? `?t=${startTime}` : ''}`
+ * };
+ * ```
+ */
 export interface ApplicationRuntimeSettings {
+    /** Partner ID in the format `partner-{id}` */
     pid: string;
+    /** Widget identifier */
     widgetId?: string;
+    /** Genie server URL for API requests */
     genieServerUrl?: string;
+    /** Kaltura session token for authentication */
     ks: string;
+    /** Kaltura server URI */
     kalturaServerURI: string;
+    /** Callback function to generate source URLs with entry ID and optional start time */
     getSourceUrl?: ({ entryId, startTime, }: {
         entryId: string;
         startTime?: number;
     }) => string;
+    /** Branding options */
     branding?: {
+        /** Display Kaltura logo in the interface */
         kalturaLogo?: boolean;
     };
 }
 export declare const applicationRuntimeSettingsSchema: ValidatorSchema;
+/** Runtime name constant for application-level experiences */
 export declare const ApplicationRuntimeName: "application";

package/src/lib/avatar-runtime/agent-visual-types.d.ts

@@ -0,0 +1,18 @@
+import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Visual settings for avatar agent display mode.
+ *
+ * @example
+ * ```typescript
+ * const settings: AvatarRuntimeAgentVisualSettings = {
+ *   panelSide: 'right'
+ * };
+ * ```
+ */
+export interface AvatarRuntimeAgentVisualSettings {
+    /** Settings schema version */
+    schemaVersion?: string;
+    /** Side of screen where agent panel appears */
+    panelSide?: 'left' | 'right';
+}
+export declare const avatarRuntimeAgentVisualSettingsSchema: ValidatorSchema;

package/src/lib/avatar-runtime/avatar-service-types.d.ts

@@ -1,30 +1,65 @@
 import { UnisphereService } from '@unisphere/runtime';
 import { TinyDataStoreConsumer } from '@unisphere/core';
-import { DeviceEnumerationResult } from '@kaltura-corp/unisphere-rtc-core';
+import { DeviceEnumerationResult } from '@kaltura-sdk/rtc-core';
+/**
+ * Avatar service configuration.
+ */
 export type AvatarConfig = {
+    /** Avatar server URL */
     serverUrl: string;
+    /** Avatar player URL */
     playerUrl: string;
 };
+/**
+ * Audio device types for avatar connections.
+ */
 export declare enum DeviceType {
+    /** Microphone input device */
     AudioInput = "audioinput",
+    /** Speaker/headphone output device */
     AudioOutput = "audiooutput"
 }
+/**
+ * Avatar connection status states.
+ *
+ * @deprecated Use AvatarConnectionStatus instead
+ */
 export declare enum AvatarStatus {
+    /** Establishing connection */
     Connecting = "connecting",
+    /** Successfully connected */
     Connected = "connected",
+    /** Not connected */
     Disconnected = "disconnected",
+    /** Connection error occurred */
     Error = "error"
 }
+/**
+ * Avatar connection lifecycle states.
+ */
 export declare enum AvatarConnectionStatus {
+    /** Establishing connection */
     Connecting = "connecting",
+    /** Successfully connected */
     Connected = "connected",
+    /** Not connected */
     Disconnected = "disconnected",
+    /** Closing connection */
     Disconnecting = "disconnecting",
+    /** Connection error occurred */
     Error = "error"
 }
+/**
+ * Avatar client initialization status.
+ */
 export type AvatarClientStatus = 'loading' | 'ready';
+/**
+ * Reasons why avatar agent may be unavailable.
+ */
 export declare enum AgentUnavailabilityReasons {
+    /** No agents are currently available */
     NoAgents = "NoAgents",
+    /** Maximum concurrent connections reached */
     CapacityReached = "CapacityReached"
 }
 export type UserDevicesList = Pick<DeviceEnumerationResult, 'availableDevices'> & {
@@ -33,38 +68,78 @@ export type UserDevicesList = Pick<DeviceEnumerationResult, 'availableDevices'>
         audioOutputDevice: string | null;
     };
 };
+/**
+ * Simplified WebSocket interface for avatar communication.
+ */
 export interface SimplifiedSocket {
+    /** Register event listener */
     on: (event: string, callback: (data: any) => void) => void;
+    /** Remove event listener */
     off: (event: string) => void;
+    /** Emit event with data */
     emit: (event: string, data: any) => void;
 }
+/**
+ * Agent state and analytics data.
+ */
 export type AgentData = {
+    /** Whether the agent is currently speaking */
     isTalking: boolean;
+    /** Number of answers provided in this session */
     answersCount: number;
+    /** Optional analytics tracking information */
     analyticsInfo?: {
+        /** Thread identifier */
         threadId?: string;
+        /** Message identifier */
         messageId?: string;
     };
 };
-export type AvatarContentData = {
+/**
+ * Content data for avatar tool integrations.
+ *
+ * Represents tool content displayed within avatar experiences, with different
+ * states for loading, ready, and error conditions.
+ */
+export type AvatarContentData<TSettings = any> = {
+    /** Unique content identifier */
     id: string;
+    /** Associated thread ID */
     threadId?: string;
+    /** Associated message ID */
     messageId?: string;
+    /** Optional new title for the content */
     newTitle?: string;
+    /** Content type identifier */
     type: 'unisphere-tool';
+    /** Widget name for the tool */
     widgetName: string;
+    /** Runtime name for the tool */
     runtimeName: string;
 } & ({
+    /** Content status: loading or ready */
     status: 'loading' | 'ready';
-    settings: any;
+    /** Tool settings configuration */
+    settings: TSettings;
+    /** Optional thread ID */
     threadId?: string;
 } | {
+    /** Content status: error occurred */
     status: 'error';
 });
+/**
+ * Internal avatar connection proxy interface for advanced operations.
+ *
+ * @internal
+ */
 export interface AvatarConnectionProxInternalType {
+    /** Send direct event to server */
     _directEventToServer(message: string, data: any): void;
+    /** Set local content state */
     _setLocalContent(content: any): void;
+    /** Handle player errors */
     onPlayerError(error: Error): void;
+    /** WebSocket connection observable */
     webSocket: TinyDataStoreConsumer<SimplifiedSocket | null>;
 }
 export declare enum DisconnectReasons {
@@ -88,27 +163,46 @@ export declare enum DisconnectReasons {
     ConnectionTimeout = "ConnectionTimeout",
     PlayerConnectionFailed = "PlayerConnectionFailed"
 }
+/**
+ * Avatar connection proxy for managing avatar session state and interactions.
+ *
+ * Provides observable properties for connection state and methods for
+ * sending messages and managing the avatar connection lifecycle.
+ */
 export interface AvatarConnectionProxyType {
+    /** Observable connection status */
     readonly status: TinyDataStoreConsumer<AvatarConnectionStatus>;
+    /** Observable player URL */
     readonly playerUrl: TinyDataStoreConsumer<string | null>;
+    /** Observable session identifier */
     readonly sessionId: TinyDataStoreConsumer<string | null>;
+    /** Observable TURN server URL */
     readonly turnServerURL: TinyDataStoreConsumer<string | null>;
+    /** Observable content data */
     readonly content: TinyDataStoreConsumer<AvatarContentData | null>;
+    /** Observable agent state and analytics */
     readonly agentData: TinyDataStoreConsumer<AgentData | null>;
+    /** Observable available audio devices */
     readonly devicesList: TinyDataStoreConsumer<{
         audioInput: MediaDeviceInfo[];
         audioOutput: MediaDeviceInfo[];
     } | null>;
+    /** Observable disconnect information */
     readonly disconnectData: TinyDataStoreConsumer<{
         reason: DisconnectReasons;
         error?: Error;
         suppressNotification?: boolean;
         skipDisconnect?: boolean;
     } | null>;
+    /** Observable thread identifier */
     readonly threadId: TinyDataStoreConsumer<string | null>;
+    /** Unique connection identifier */
     readonly id: string;
+    /** Send text message to avatar */
     sendAskViaText(text: string): void;
+    /** Send custom event to avatar */
     sendDirectEvent(message: string, data: unknown): void;
+    /** Terminate the avatar connection */
     destroy(): void;
 }
 export declare const isAvatarConnectionProxyInternalType: (x: any) => x is AvatarConnectionProxInternalType;
@@ -133,6 +227,7 @@ export interface AvatarServiceType extends UnisphereService {
         threadId?: string;
         messageId?: string;
     }): void;
+    disconnect(): void;
     onPlayerReady(): void;
     onPlayerError(error: Error): void;
     getKalturaPlayerParams(): {
@@ -144,4 +239,6 @@ export interface AvatarServiceType extends UnisphereService {
     askViaText(text: string): void;
     changeDevice(deviceType: DeviceType, deviceId: string): Promise<boolean>;
     toggleMuteAudio(muted: boolean): Promise<void>;
+    joinSTV(containerId: string, sessionId: string, stvUrl: string, onConnected: () => void): Promise<void>;
+    leaveSTV(): void;
 }

package/src/lib/avatar-runtime/chat-visual-types.d.ts

@@ -1,5 +1,14 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Visual settings for avatar runtime chat display.
+ *
+ * @example
+ * ```typescript
+ * const settings: AvatarRuntimeChatVisualSettings = {};
+ * ```
+ */
 export interface AvatarRuntimeChatVisualSettings {
+    /** Settings schema version */
     schemaVersion?: string;
 }
 export declare const avatarRuntimeChatVisualSettingsSchema: ValidatorSchema;

package/src/lib/avatar-runtime/contained-visual-types.d.ts

@@ -1,5 +1,14 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Visual settings for contained/embedded avatar display mode.
+ *
+ * @example
+ * ```typescript
+ * const settings: AvatarRuntimeContainedVisualSettings = {};
+ * ```
+ */
 export interface AvatarRuntimeContainedVisualSettings {
+    /** Settings schema version */
     schemaVersion?: string;
 }
 export declare const avatarRuntimeContainedVisualSettingsSchema: ValidatorSchema;

package/src/lib/avatar-runtime/index.d.ts

@@ -3,3 +3,4 @@ export * from './chat-visual-types';
 export * from './avatar-service-types';
 export * from './contained-visual-types';
 export * from './lobby-visual-types';
+export * from './agent-visual-types';

package/src/lib/avatar-runtime/lobby-visual-types.d.ts

@@ -1,9 +1,43 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Visual settings for avatar lobby/waiting room display.
+ *
+ * @example
+ * Default lobby:
+ * ```typescript
+ * const settings: AvatarRuntimeLobbyVisualSettings = {
+ *   variant: 'default'
+ * };
+ * ```
+ *
+ * @example
+ * Agent variant with customization:
+ * ```typescript
+ * const settings: AvatarRuntimeLobbyVisualSettings = {
+ *   variant: 'agent',
+ *   agentButtonLabel: 'Start Conversation',
+ *   agentSize: '20rem',
+ *   isTranslucent: true,
+ *   threadId: 'thread-123'
+ * };
+ * ```
+ */
 export interface AvatarRuntimeLobbyVisualSettings {
+    /** Settings schema version */
     schemaVersion?: string;
-    variant?: 'default' | 'mini' | 'buttonOnly';
+    /** Display variant: 'default' for full lobby, 'mini' for compact, 'buttonOnly' for minimal, 'agent' for agent-specific UI */
+    variant?: 'default' | 'mini' | 'buttonOnly' | 'agent';
+    /** Enable translucent/semi-transparent UI elements */
     isTranslucent?: boolean;
+    /** Thread identifier for resuming conversations */
     threadId?: string;
+    /** Message identifier for context */
     messageId?: string;
+    /** Agent variant only: label for the start button */
+    agentButtonLabel?: string;
+    /** Agent variant only: size (width and height) of the card, e.g. '15rem' */
+    agentSize?: string;
+    /** Hide the start conversation button (e.g. when interaction limit is exceeded) */
+    hideStartButton?: boolean;
 }
 export declare const avatarRuntimeLobbyVisualSettingsSchema: ValidatorSchema;

package/src/lib/avatar-runtime/runtime-types.d.ts

@@ -1,34 +1,102 @@
 import { TinyDataStoreConsumer, ValidatorSchema } from '@unisphere/core';
 import { UnisphereRuntimeBaseType } from '@unisphere/runtime';
 import { widgetName } from '../widget-types';
+/** Runtime name constant for avatar experiences */
 export declare const AvatarRuntimeName: "avatar";
+/**
+ * Avatar runtime interface for interactive AI avatar experiences.
+ *
+ * Provides real-time avatar capabilities including video streaming, connection management,
+ * and thread-based conversations.
+ */
 export type AvatarRuntime = UnisphereRuntimeBaseType<AvatarRuntimeSettings> & {
     readonly widgetName: typeof widgetName;
     readonly runtimeName: typeof AvatarRuntimeName;
+    /** Establish connection to the avatar service */
     connect(): void;
+    /** Disconnect from the avatar service */
     disconnect(): void;
+    /** Observable connection status */
     isConnected: TinyDataStoreConsumer<boolean>;
+    /** Observable current thread ID */
     threadId: TinyDataStoreConsumer<string | null>;
+    /** Set the active conversation thread ID */
     setThreadId(id: string | null): void;
 };
+/**
+ * Configuration settings for the avatar runtime.
+ *
+ * @example
+ * Basic avatar setup (required settings only):
+ * ```typescript
+ * const settings: AvatarRuntimeSettings = {
+ *   turnServerUrl: 'https://turn.example.com',
+ *   serverUrl: 'https://avatar.example.com',
+ *   srsBaseUrl: 'https://srs.example.com',
+ *   kaltura: {
+ *     ks: 'your-kaltura-session-token'
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Advanced avatar with custom configuration:
+ * ```typescript
+ * const settings: AvatarRuntimeSettings = {
+ *   turnServerUrl: 'https://turn.example.com',
+ *   serverUrl: 'https://avatar.example.com',
+ *   srsBaseUrl: 'https://srs.example.com',
+ *   clientId: 'client-123',
+ *   roomId: 'room-456',
+ *   avatarId: 'avatar-789',
+ *   agentMode: true,
+ *   noiseReductionEnabled: true,
+ *   kaltura: {
+ *     ks: 'your-kaltura-session-token',
+ *     partnerId: '12345',
+ *     entryId: 'entry_xyz'
+ *   }
+ * };
+ * ```
+ */
 export interface AvatarRuntimeSettings {
+    /** Settings schema version */
     schemaVersion?: string;
+    /** TURN server URL for WebRTC connectivity */
     turnServerUrl: string;
+    /** Avatar service server URL */
     serverUrl: string;
+    /** SRS (Simple Realtime Server) base URL for media streaming */
     srsBaseUrl: string;
-    clientId: string;
-    roomId: string;
-    flowId: string;
+    /** Client identifier for tracking and analytics */
+    clientId?: string;
+    /** Room identifier for multi-user sessions */
+    roomId?: string;
+    /** Flow identifier for conversation routing */
+    flowId?: string;
+    /** URL for loading state video displayed during avatar initialization */
     loadingVideoURL?: string;
+    /** Unique identifier for the avatar persona */
     avatarId?: string;
+    /** Preview image URL displayed before avatar loads */
     previewImageUrl?: string;
+    /** Enable agent mode for advanced AI capabilities */
     agentMode?: boolean;
+    /** Enable audio noise reduction for clearer audio */
     noiseReductionEnabled?: boolean;
+    /** STV cast mode for avatar streaming ('webrtc' | 'rtmp') */
+    castMode?: string;
+    /** Kaltura service integration settings */
     kaltura: {
+        /** Kaltura session token for authentication */
         ks: string;
+        /** Media entry ID for context */
         entryId?: string;
+        /** Kaltura server URI */
         kalturaServerURI?: string;
+        /** Kaltura partner ID */
         partnerId?: string;
+        /** UI configuration ID */
         uiConfId?: string;
     };
 }

package/src/lib/chat-runtime/runtime-flavors/runtime-player-plugin-types.d.ts

@@ -3,19 +3,61 @@ import { ValidatorSchema } from '@unisphere/core';
 import { widgetName } from '../../widget-types';
 import { ChatRuntimeName } from '../types';
 import { GlobalChatSettings } from '../shared-settings';
+/**
+ * Chat runtime interface for player plugin integration.
+ *
+ * Specialized runtime flavor for embedding chat within Kaltura video players.
+ */
 export interface ChatRuntimePlayerPlugin extends UnisphereRuntimeBaseType<ChatRuntimePlayerPluginSettings> {
     readonly widgetName: typeof widgetName;
     readonly runtimeName: typeof ChatRuntimeName;
     readonly flavor: 'player-plugin';
 }
+/**
+ * Configuration settings for chat runtime player plugin.
+ *
+ * @example
+ * Basic player plugin setup:
+ * ```typescript
+ * const settings: ChatRuntimePlayerPluginSettings = {
+ *   entryId: 'video_123',
+ *   ks: 'your-kaltura-session-token'
+ * };
+ * ```
+ *
+ * @example
+ * With integrations:
+ * ```typescript
+ * const settings: ChatRuntimePlayerPluginSettings = {
+ *   entryId: 'video_123',
+ *   ks: 'your-kaltura-session-token',
+ *   partnerId: '12345',
+ *   agentMode: true,
+ *   avatarContainerMode: 'dialog',
+ *   integrations: {
+ *     kaltura: {
+ *       entryId: 'video_123'
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export interface ChatRuntimePlayerPluginSettings {
+    /** Media entry ID for the video being played */
     entryId: string;
+    /** Kaltura session token for authentication */
     ks: string;
+    /** Kaltura partner ID */
     partnerId?: string;
+    /** Settings schema version */
     schemaVersion?: '1';
+    /** External service integrations */
     integrations?: GlobalChatSettings['integrations'];
+    /** Configuration for conversation sharing */
     shareUrl?: GlobalChatSettings['shareUrl'];
+    /** Enable agent mode for advanced AI capabilities */
     agentMode?: boolean;
+    /** Avatar display mode: 'dialog' for modal or 'contained' for embedded */
     avatarContainerMode?: 'dialog' | 'contained';
 }
 export declare const chatRuntimePlayerPluginSettingsSchema: ValidatorSchema;