@unisphere/genie-types 1.13.1 → 1.14.0

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/content-gallery-tool-runtime/avatar-visual-types.d.ts

@@ -0,0 +1,32 @@
+import { ValidatorSchema } from '@unisphere/core';
+export interface VideoClip {
+    start_index: number;
+    last_index: number;
+    entry_id: string;
+    start_time: number;
+    end_time: number;
+    type: string;
+    thumbnail: string | null;
+    video_link: string | null;
+}
+export interface VideoSlide {
+    slide_type: 'video';
+    text: string | null;
+    citation: {
+        clips: VideoClip[];
+    };
+}
+export interface TextSlide {
+    slide_type: 'text';
+    text: string;
+    citation: null;
+}
+export type Slide = VideoSlide | TextSlide;
+export interface ContentGalleryToolRuntimeAvatarVisualSettings {
+    schemaVersion?: string;
+    slides: Slide[];
+    autoplay?: boolean;
+    slideDuration?: number;
+    loop?: boolean;
+}
+export declare const contentGalleryToolRuntimeAvatarVisualSettingsSchema: ValidatorSchema;

package/src/lib/content-gallery-tool-runtime/index.d.ts

@@ -0,0 +1,2 @@
+export * from './runtime-types';
+export * from './avatar-visual-types';

package/src/lib/content-gallery-tool-runtime/runtime-types.d.ts

@@ -0,0 +1,20 @@
+import { ValidatorSchema } from '@unisphere/core';
+import { UnisphereRuntimeBaseType } from '@unisphere/runtime';
+import { widgetName } from '../widget-types';
+export declare const ContentGalleryToolRuntimeName: "content-gallery-tool";
+export type ContentGalleryToolRuntime = UnisphereRuntimeBaseType<ContentGalleryToolRuntimeSettings> & {
+    readonly widgetName: typeof widgetName;
+    readonly runtimeName: typeof ContentGalleryToolRuntimeName;
+};
+export interface ContentGalleryToolRuntimeSettings {
+    schemaVersion?: string;
+    /** Kaltura server URI */
+    kalturaServerURI: string;
+    /** Kaltura partner ID */
+    partnerId: string;
+    /** UI configuration ID */
+    uiConfId: string;
+    /** Kaltura session token for authentication */
+    ks: string;
+}
+export declare const contentGalleryToolRuntimeSettingsSchema: ValidatorSchema;

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/gen-ui-components-tool-runtime/card-visual-types.d.ts

@@ -0,0 +1,39 @@
+/// <reference types="react" />
+import { ValidatorSchema } from '@unisphere/core';
+export interface CardAction {
+    label: string;
+    icon?: React.ReactNode;
+    onClick: React.MouseEventHandler<HTMLButtonElement>;
+}
+export type CardMedia = {
+    type: 'image';
+    src: string;
+    alt: string;
+    placement?: 'left' | 'right';
+} | {
+    type: 'video';
+    src: string;
+    placement?: 'left' | 'right';
+    startTime?: number;
+    endTime?: number;
+} | {
+    type: 'kaltura';
+    entryId: string;
+    kalturaServerURI?: string;
+    partnerId?: string;
+    uiConfId?: string;
+    ks?: string;
+    placement?: 'left' | 'right';
+    startTime?: number;
+    endTime?: number;
+};
+export interface GenUiComponentsToolRuntimeCardVisualSettings {
+    schemaVersion?: string;
+    title?: string;
+    body?: string;
+    action?: CardAction;
+    media?: CardMedia;
+    loading?: boolean;
+    isTranslucent?: boolean;
+}
+export declare const genUiComponentsToolRuntimeCardVisualSettingsSchema: ValidatorSchema;

package/src/lib/gen-ui-components-tool-runtime/index.d.ts

@@ -0,0 +1,4 @@
+export * from './runtime-types';
+export * from './card-visual-types';
+export * from './markdown-visual-types';
+export * from './player-visual-types';

package/src/lib/gen-ui-components-tool-runtime/markdown-visual-types.d.ts

@@ -0,0 +1,7 @@
+import { ValidatorSchema } from '@unisphere/core';
+export interface GenUiComponentsToolRuntimeMarkdownVisualSettings {
+    schemaVersion?: string;
+    content: string;
+    isTranslucent?: boolean;
+}
+export declare const genUiComponentsToolRuntimeMarkdownVisualSettingsSchema: ValidatorSchema;

package/src/lib/gen-ui-components-tool-runtime/player-visual-types.d.ts

@@ -0,0 +1,25 @@
+import { ValidatorSchema } from '@unisphere/core';
+export type PlayerSource = {
+    type: 'native';
+    src: string;
+    poster?: string;
+    startTime?: number;
+    endTime?: number;
+} | {
+    type: 'kaltura';
+    entryId: string;
+    kalturaServerURI?: string;
+    partnerId?: string;
+    uiConfId?: string;
+    ks?: string;
+    startTime?: number;
+    endTime?: number;
+};
+export interface GenUiComponentsToolRuntimePlayerVisualSettings {
+    schemaVersion?: string;
+    source: PlayerSource;
+    title?: string;
+    loading?: boolean;
+    isTranslucent?: boolean;
+}
+export declare const genUiComponentsToolRuntimePlayerVisualSettingsSchema: ValidatorSchema;

package/src/lib/gen-ui-components-tool-runtime/runtime-types.d.ts

@@ -0,0 +1,13 @@
+import { ValidatorSchema } from '@unisphere/core';
+import { UnisphereRuntimeBaseType } from '@unisphere/runtime';
+import { widgetName } from '../widget-types';
+export declare const GenUiComponentsToolRuntimeName: "gen-ui-components-tool";
+export type GenUiComponentsToolRuntime = UnisphereRuntimeBaseType<GenUiComponentsToolRuntimeSettings> & {
+    readonly widgetName: typeof widgetName;
+    readonly runtimeName: typeof GenUiComponentsToolRuntimeName;
+};
+export interface GenUiComponentsToolRuntimeSettings {
+    schemaVersion?: string;
+    baseVisualSettings?: Record<string, unknown>;
+}
+export declare const genUiComponentsToolRuntimeSettingsSchema: ValidatorSchema;

package/src/lib/gen-ui-composer-tool-runtime/avatar-visual-types.d.ts

@@ -0,0 +1,49 @@
+import { ValidatorSchema } from '@unisphere/core';
+export interface RowHeight {
+    type: 'auto' | 'fixed' | 'fill' | 'percentage';
+    value?: number;
+}
+export interface CellWidth {
+    type: 'fill' | 'fit' | 'fixed' | 'percentage' | 'custom';
+    value?: string;
+}
+export interface GridRow {
+    id: string;
+    height: RowHeight;
+    columns: string;
+    cells: GridCell[];
+}
+export interface GridLayout {
+    type: 'cssGrid';
+    gridTemplateAreas?: string;
+    gridTemplateRows?: string;
+    gridTemplateColumns?: string;
+    gap?: string;
+    cells?: GridCell[];
+    rows?: GridRow[];
+}
+export interface GridCell {
+    id: string;
+    name?: string;
+    width?: CellWidth;
+    rowSpan?: number;
+    visual?: UnisphereVisualConfig;
+    runtime?: UnisphereRuntimeConfig;
+    style?: Record<string, unknown>;
+}
+export interface UnisphereVisualConfig {
+    widgetName: string;
+    runtimeName: string;
+    visualType: string;
+    visualSettings?: Record<string, unknown>;
+}
+export interface UnisphereRuntimeConfig {
+    widgetName: string;
+    runtimeName: string;
+    runtimeSettings: Record<string, unknown>;
+}
+export interface GenUiComposerToolRuntimeAvatarVisualSettings {
+    schemaVersion?: string;
+    layout?: GridLayout;
+}
+export declare const genUiComposerToolRuntimeAvatarVisualSettingsSchema: ValidatorSchema;