@unisphere/genie-types 1.13.1 → 1.13.2

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

@@ -1,34 +1,100 @@
 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;
+    /** 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;

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

@@ -3,30 +3,90 @@ import { ValidatorSchema } from '@unisphere/core';
 import { widgetName } from '../../widget-types';
 import { ChatRuntimeName } from '../types';
 import { GlobalChatSettings } from '../shared-settings';
+/**
+ * Chat runtime interface for Genie conversational AI experiences.
+ *
+ * Provides the core runtime for chat-based interactions with Genie's AI assistant,
+ * including conversation management, message handling, and integration features.
+ */
 export interface ChatRuntime extends UnisphereRuntimeBaseType<ChatRuntimeSettings> {
     readonly widgetName: typeof widgetName;
     readonly runtimeName: typeof ChatRuntimeName;
     readonly flavor: '';
 }
+/**
+ * Configuration settings for the chat runtime.
+ *
+ * @example
+ * Basic chat setup (required settings only):
+ * ```typescript
+ * const settings: ChatRuntimeSettings = {
+ *   ks: 'your-kaltura-session-token'
+ * };
+ * ```
+ *
+ * @example
+ * Advanced chat with custom features:
+ * ```typescript
+ * const settings: ChatRuntimeSettings = {
+ *   ks: 'your-kaltura-session-token',
+ *   partnerId: '12345',
+ *   entryId: 'entry_xyz',
+ *   initialQuestion: 'Hello! How can I help?',
+ *   integrations: {
+ *     kaltura: {
+ *       serverUrl: 'https://www.kaltura.com',
+ *       uiConfId: '54321'
+ *     }
+ *   },
+ *   customization: {
+ *     breadcrumb: {
+ *       root: {
+ *         url: 'https://example.com',
+ *         label: 'Home'
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export interface ChatRuntimeSettings {
+    /** Kaltura session token for authentication */
     ks: string;
+    /** Optional initial question to display when chat starts */
     initialQuestion?: string;
+    /** Settings schema version, defaults to '1' */
     schemaVersion?: '1';
+    /** Genie server URL for API requests */
     genieServerUrl?: string;
+    /** Kaltura partner ID */
     partnerId?: string;
+    /** Media entry ID for context-aware chat */
     entryId?: string;
+    /** Enable agent mode for advanced AI features */
     agentMode?: boolean;
+    /** Avatar display mode: 'dialog' for modal or 'contained' for embedded */
     avatarContainerMode?: 'dialog' | 'contained';
+    /** Callback function to generate source URLs with entry ID and optional start time */
     getSourceUrl?: GlobalChatSettings['getSourceUrl'];
+    /** Configuration for conversation sharing functionality */
     shareUrl?: GlobalChatSettings['shareUrl'];
+    /** @deprecated Use visual settings or customization settings instead */
     branding?: {
+        /** Display Kaltura logo in the chat interface */
         kalturaLogo?: boolean;
     };
+    /** External service integrations (Kaltura player, avatar) */
     integrations?: GlobalChatSettings['integrations'];
+    /** UI customization options */
     customization?: {
+        /** Breadcrumb navigation configuration */
         breadcrumb?: {
+            /** Root breadcrumb item */
             root?: {
+                /** URL for the root breadcrumb link */
                 url: string;
+                /** Display label for the root breadcrumb */
                 label: string;
             };
         };

package/src/lib/chat-runtime/shared-settings.d.ts

@@ -1,37 +1,125 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Branding configuration for chat UI.
+ */
 export interface ChatBranding {
+    /** Display Kaltura logo in the chat interface */
     kalturaLogo?: boolean;
 }
+/**
+ * Avatar service integration configuration.
+ *
+ * @example
+ * Manual configuration:
+ * ```typescript
+ * const integration: AvatarIntegration = {
+ *   type: 'config',
+ *   turnServerUrl: 'https://turn.example.com',
+ *   serverUrl: 'https://avatar.example.com',
+ *   srsBaseUrl: 'https://srs.example.com',
+ *   clientId: 'client-123',
+ *   roomId: 'room-456',
+ *   flowId: 'flow-789'
+ * };
+ * ```
+ *
+ * @example
+ * Automatic configuration via KS:
+ * ```typescript
+ * const integration: AvatarIntegration = {
+ *   type: 'byKS',
+ *   previewImageUrl: 'https://example.com/avatar-preview.jpg'
+ * };
+ * ```
+ */
 export type AvatarIntegration = {
+    /** Configuration type: 'config' for manual setup */
     type: 'config';
+    /** TURN server URL for WebRTC */
     turnServerUrl: string;
+    /** Avatar service server URL */
     serverUrl: string;
+    /** SRS (Simple Realtime Server) base URL */
     srsBaseUrl: string;
+    /** Client identifier */
     clientId: string;
+    /** Room identifier */
     roomId: string;
+    /** Flow identifier */
     flowId: string;
+    /** Loading video URL displayed during initialization */
     loadingVideoURL?: string;
+    /** Preview image URL displayed before avatar loads */
+    previewImageUrl?: string;
 } | {
+    /** Configuration type: 'byKS' for automatic setup using Kaltura session */
     type: 'byKS';
+    /** Preview image URL displayed before avatar loads */
+    previewImageUrl?: string;
 };
+/**
+ * Kaltura service integration configuration.
+ *
+ * @example
+ * ```typescript
+ * const integration: KalturaIntegration = {
+ *   entryId: 'video_123'
+ * };
+ * ```
+ */
 export interface KalturaIntegration {
+    /** Media entry ID for context */
     entryId?: string;
 }
+/**
+ * Global chat configuration settings shared across chat components.
+ *
+ * @example
+ * ```typescript
+ * const settings: GlobalChatSettings = {
+ *   ks: 'your-kaltura-session-token',
+ *   avatarContainerMode: 'dialog',
+ *   getSourceUrl: ({ entryId, startTime }) =>
+ *     `https://example.com/media/${entryId}${startTime ? `?t=${startTime}` : ''}`,
+ *   shareUrl: {
+ *     queryParam: 'msg',
+ *     createUrl: ({ messageId }) =>
+ *       `${window.location.href}?msg=${messageId}`
+ *   },
+ *   integrations: {
+ *     kaltura: {
+ *       entryId: 'video_123'
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export interface GlobalChatSettings {
+    /** Kaltura session token for authentication */
     ks: string;
+    /** Entry ID for context-aware features */
+    entryId?: string;
+    /** Callback function to generate source URLs with entry ID and optional start time */
     getSourceUrl?: (params: {
         entryId: string;
         startTime?: number;
     }) => string;
+    /** Configuration for conversation sharing */
     shareUrl?: {
+        /** Query parameter name for message ID in shared URLs */
         queryParam: string;
+        /** Callback to generate shareable URL for a message */
         createUrl: (params: {
             messageId: string;
         }) => string;
     };
+    /** Avatar display mode: 'dialog' for modal, 'contained' for embedded, or null */
     avatarContainerMode: 'dialog' | 'contained' | null;
+    /** External service integrations */
     integrations?: {
+        /** Avatar service integration */
         avatar?: AvatarIntegration;
+        /** Kaltura service integration */
         kaltura?: KalturaIntegration;
     };
 }

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

@@ -1 +1,2 @@
+/** Runtime name constant for chat experiences */
 export declare const ChatRuntimeName: "chat";

package/src/lib/chat-runtime/visuals-types.d.ts

@@ -1,28 +1,94 @@
 import { ValidatorSchema } from '@unisphere/core';
 import { ChatCustomization } from '../shared/chat-customizations-types';
 import { AnswerTypeEnum } from '../types';
+/**
+ * Visual settings for page-embedded chat experiences.
+ *
+ * @example
+ * ```typescript
+ * const settings: PageVisualSettings = {
+ *   customization: {
+ *     scroll: 'container',
+ *     theme: { translucent: true }
+ *   }
+ * };
+ * ```
+ */
 export interface PageVisualSettings {
+    /** Settings schema version */
     schemaVersion?: '1';
+    /** Custom UI styling and behavior options */
     customization?: ChatCustomization;
 }
+/**
+ * Visual settings for banner/hero-style chat landing pages.
+ *
+ * @example
+ * ```typescript
+ * const settings: BannerVisualSettings = {
+ *   title: 'Ask anything about this video',
+ *   background: {
+ *     type: 'url',
+ *     url: 'https://example.com/banner.jpg'
+ *   },
+ *   predefinedQuestions: [
+ *     {
+ *       text: 'What are the key topics?',
+ *       label: 'Key Topics',
+ *       answerType: AnswerTypeEnum.GENERAL
+ *     }
+ *   ]
+ * };
+ * ```
+ */
 export interface BannerVisualSettings {
+    /** Settings schema version */
     schemaVersion?: '1';
+    /** Banner title text */
     title?: string;
+    /** Background image configuration */
     background?: {
+        /** Background type - currently only 'url' is supported */
         type: 'url';
+        /** Image URL */
         url: string;
     };
+    /** Suggested questions to display on banner */
     predefinedQuestions?: {
+        /** Question text sent to AI */
         text: string;
+        /** Display label for the button */
         label: string;
+        /** Preferred answer type */
         answerType?: AnswerTypeEnum;
     }[];
 }
+/**
+ * Visual settings for popup/modal chat dialogs.
+ *
+ * @example
+ * ```typescript
+ * const settings: PopupVisualSettings = {
+ *   customization: {
+ *     scroll: 'modal'
+ *   },
+ *   initialQuestion: {
+ *     question: 'Tell me about this topic',
+ *     answerType: AnswerTypeEnum.GENERAL
+ *   }
+ * };
+ * ```
+ */
 export interface PopupVisualSettings {
+    /** Settings schema version */
     schemaVersion?: '1';
+    /** Custom UI styling and behavior options */
     customization?: ChatCustomization;
+    /** Optional question to ask automatically when popup opens */
     initialQuestion?: {
+        /** Question text */
         question: string;
+        /** Preferred answer type */
         answerType?: AnswerTypeEnum;
     };
 }

package/src/lib/flashcards-tool-runtime/runtime-types.d.ts

@@ -2,13 +2,40 @@ import { UnisphereRuntimeBaseType } from '@unisphere/runtime';
 import { ValidatorSchema } from '@unisphere/core';
 import { widgetName } from '../widget-types';
 import { ChatCustomization } from '../shared/chat-customizations-types';
+/** Runtime name constant for flashcards tool */
 export declare const FlashcardsToolRuntimeName: "flashcards-tool";
+/**
+ * Flashcards tool runtime interface for educational study aids.
+ *
+ * Provides interactive flashcard experiences for learning and knowledge reinforcement.
+ */
 export interface FlashcardsToolRuntime extends UnisphereRuntimeBaseType<FlashcardsToolRuntimeSettings> {
     readonly widgetName: typeof widgetName;
     readonly runtimeName: typeof FlashcardsToolRuntimeName;
 }
+/**
+ * Configuration settings for the flashcards tool runtime.
+ *
+ * @example
+ * Basic flashcards setup:
+ * ```typescript
+ * const settings: FlashcardsToolRuntimeSettings = {};
+ * ```
+ *
+ * @example
+ * With custom UI styling:
+ * ```typescript
+ * const settings: FlashcardsToolRuntimeSettings = {
+ *   customization: {
+ *     // Custom chat UI settings
+ *   }
+ * };
+ * ```
+ */
 export interface FlashcardsToolRuntimeSettings {
+    /** Settings schema version, defaults to '1' */
     schemaVersion?: '1';
+    /** Custom UI styling and behavior options */
     customization?: ChatCustomization;
 }
 export declare const flashcardsToolRuntimeSettingsSchema: ValidatorSchema;

package/src/lib/flashcards-tool-runtime/visuals-types.d.ts

@@ -1,14 +1,50 @@
 import { ValidatorSchema } from '@unisphere/core';
 import { CardsVideoDataType } from '../types';
 import { BlockVisualContext } from '../shared/general-visual-types';
+/**
+ * Visual settings for flashcard Genie answer display.
+ *
+ * Configures how flashcard answers are rendered, including title, summary,
+ * and key points with video citations.
+ *
+ * @example
+ * ```typescript
+ * const visualSettings: GenieAnswerVisualSettings = {
+ *   title: 'Key Concepts',
+ *   summary: 'Main ideas from the lesson',
+ *   keypoints: [
+ *     {
+ *       title: 'Introduction',
+ *       summary: 'Overview of the topic',
+ *       citation: {
+ *         clips: [{
+ *           entry_id: 'video_123',
+ *           start_time: 10,
+ *           end_time: 30,
+ *           thumbnail: 'https://example.com/thumb.jpg'
+ *         }]
+ *       }
+ *     }
+ *   ]
+ * };
+ * ```
+ */
 export interface GenieAnswerVisualSettings {
+    /** Visual block context for rendering */
     blockContext?: BlockVisualContext;
+    /** Title for the answer display */
     title?: string;
+    /** Summary text for the answer */
     summary?: string;
+    /** Array of key points with optional video citations */
     keypoints?: {
+        /** Title of the key point */
         title?: string;
+        /** Summary text for the key point */
         summary?: string;
+        /** Video citations supporting this key point */
         citation?: {
+            /** Array of video clip references */
             clips?: CardsVideoDataType[];
         };
     }[];

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

@@ -1,9 +1,27 @@
 import { ValidatorSchema } from '@unisphere/core';
 import { BlockVisualContext } from '../shared';
+/**
+ * Visual settings for follow-up questions in avatar mode.
+ *
+ * @example
+ * ```typescript
+ * const visualSettings: FollowupsToolRuntimeAvatarVisualSettings = {
+ *   questions: [
+ *     'Can you explain more?',
+ *     'What are the next steps?'
+ *   ],
+ *   onAction: (data) => console.log('Action triggered:', data)
+ * };
+ * ```
+ */
 export interface FollowupsToolRuntimeAvatarVisualSettings {
+    /** Settings schema version */
     schemaVersion?: string;
+    /** Visual block context for rendering */
     blockContext?: BlockVisualContext;
+    /** Array of suggested follow-up questions */
     questions?: string[];
+    /** Callback function triggered when user selects a question */
     onAction: (data: any) => void;
 }
 export declare const followupsToolRuntimeAvatarVisualSettingsSchema: ValidatorSchema;

package/src/lib/followups-tool-runtime/runtime-types.d.ts

@@ -2,17 +2,48 @@ import { ValidatorSchema } from '@unisphere/core';
 import { UnisphereRuntimeBaseType } from '@unisphere/runtime';
 import { widgetName } from '../widget-types';
 import { BlockVisualContext } from '../shared/general-visual-types';
+/** Runtime name constant for followups tool */
 export declare const FollowupsToolRuntimeName: "followups-tool";
+/**
+ * Followups tool runtime interface for suggested conversation continuations.
+ *
+ * Provides AI-generated follow-up questions to guide users deeper into topics.
+ */
 export type FollowupsToolRuntime = UnisphereRuntimeBaseType<FollowupsToolRuntimeSettings> & {
     readonly widgetName: typeof widgetName;
     readonly runtimeName: typeof FollowupsToolRuntimeName;
 };
+/**
+ * Configuration settings for the followups tool runtime.
+ *
+ * @example
+ * ```typescript
+ * const settings: FollowupsToolRuntimeSettings = {};
+ * ```
+ */
 export interface FollowupsToolRuntimeSettings {
+    /** Settings schema version */
     schemaVersion?: string;
 }
 export declare const followupsToolRuntimeSettingsSchema: ValidatorSchema;
+/**
+ * Visual settings for followup questions displayed in Genie answers.
+ *
+ * @example
+ * ```typescript
+ * const visualSettings: FollowupsToolRuntimeGenieAnswerVisualSettings = {
+ *   questions: [
+ *     'Tell me more about this topic',
+ *     'What are some related concepts?',
+ *     'Can you provide an example?'
+ *   ]
+ * };
+ * ```
+ */
 export interface FollowupsToolRuntimeGenieAnswerVisualSettings {
+    /** Visual block context for rendering */
     blockContext?: BlockVisualContext;
+    /** Array of suggested follow-up questions */
     questions?: string[];
 }
 export declare const followupsToolRuntimeGenieAnswerVisualSettingsSchema: ValidatorSchema;

package/src/lib/gtc-agenda-list-tool-runtime/genie-answer-visual-types.d.ts

@@ -1,6 +1,21 @@
 import { ValidatorSchema } from '@unisphere/core';
+/**
+ * Visual settings for GTC agenda list displayed in Genie answers.
+ *
+ * @example
+ * ```typescript
+ * const visualSettings: GtcAgendaListToolRuntimeGenieAnswerVisualSettings = {
+ *   sessions: [
+ *     { id: 'session_123' },
+ *     { id: 'session_456' }
+ *   ]
+ * };
+ * ```
+ */
 export interface GtcAgendaListToolRuntimeGenieAnswerVisualSettings {
+    /** Settings schema version */
     schemaVersion?: string;
+    /** Array of session identifiers to display */
     sessions: {
         id: string;
     }[];