@unisphere/models-sdk-js 1.2.0

package/src/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Kaltura Avatar SDK - Core Types
+ *
+ * This file contains shared TypeScript types and interfaces used across the SDK.
+ */
+/**
+ * Configuration options for the Kaltura Avatar SDK
+ */
+export interface AvatarConfig {
+    /** Base URL for the avatar backend API. Defaults to production URL. */
+    baseUrl?: string;
+    /** ICE servers for WebRTC connection. Defaults to Google STUN. */
+    iceServers?: RTCIceServer[];
+    /** ICE transport policy: 'all' allows both STUN and TURN, 'relay' forces TURN only */
+    iceTransportPolicy?: 'all' | 'relay';
+    /** Retry configuration for API calls and connections */
+    retryConfig?: RetryConfig;
+    /** Logging level for the SDK */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Options for creating an avatar session
+ */
+export interface CreateSessionOptions {
+    /** ID of the avatar to use */
+    avatarId: string;
+    /** Optional voice ID for the avatar */
+    voiceId?: string;
+}
+/**
+ * Configuration for retry logic with exponential backoff
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts. Default: 3 */
+    maxAttempts: number;
+    /** Initial delay in milliseconds before first retry. Default: 500 */
+    initialDelayMs: number;
+    /** Maximum delay in milliseconds between retries. Default: 5000 */
+    maxDelayMs: number;
+    /** Multiplier for exponential backoff. Default: 2 */
+    backoffMultiplier: number;
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Session state machine states
+ */
+export declare enum SessionState {
+    /** Session not created yet */
+    IDLE = "idle",
+    /** Session is being created */
+    CREATING = "creating",
+    /** Session is ready for commands */
+    READY = "ready",
+    /** Session has ended */
+    ENDED = "ended",
+    /** Session encountered an error */
+    ERROR = "error"
+}
+/**
+ * WebRTC connection state
+ */
+export declare enum ConnectionState {
+    /** Not connected */
+    DISCONNECTED = "disconnected",
+    /** Connection in progress */
+    CONNECTING = "connecting",
+    /** Connection established */
+    CONNECTED = "connected",
+    /** Connection failed */
+    FAILED = "failed",
+    /** Connection closed */
+    CLOSED = "closed"
+}
+/**
+ * Session-level events that can be subscribed to
+ */
+export type SessionEvent = 'stateChange' | 'connectionChange' | 'error';
+/**
+ * RTC-level events
+ */
+export type RTCEvent = 'connected' | 'disconnected' | 'failed' | 'track';
+/**
+ * Error codes for different types of failures
+ */
+export declare enum AvatarErrorCode {
+    INVALID_STATE = "INVALID_STATE",
+    SESSION_CREATE_FAILED = "SESSION_CREATE_FAILED",
+    SESSION_INIT_FAILED = "SESSION_INIT_FAILED",
+    API_REQUEST_FAILED = "API_REQUEST_FAILED",
+    API_AUTH_FAILED = "API_AUTH_FAILED",
+    API_NETWORK_ERROR = "API_NETWORK_ERROR",
+    RTC_CONNECTION_FAILED = "RTC_CONNECTION_FAILED",
+    SIGNALING_FAILED = "SIGNALING_FAILED",
+    ICE_GATHERING_TIMEOUT = "ICE_GATHERING_TIMEOUT",
+    PEER_CONNECTION_FAILED = "PEER_CONNECTION_FAILED",
+    VIDEO_ELEMENT_INVALID = "VIDEO_ELEMENT_INVALID",
+    MEDIA_PLAYBACK_FAILED = "MEDIA_PLAYBACK_FAILED",
+    INVALID_ARGUMENT = "INVALID_ARGUMENT",
+    TIMEOUT = "TIMEOUT",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+/**
+ * Custom error class for avatar SDK errors
+ */
+export declare class AvatarError extends Error {
+    code: AvatarErrorCode;
+    cause?: Error | undefined;
+    /**
+     * Create a new AvatarError
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param cause - Optional underlying error that caused this error
+     */
+    constructor(message: string, code: AvatarErrorCode, cause?: Error | undefined);
+}

package/src/utils/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Error utilities for the Kaltura Avatar SDK
+ */
+import { AvatarError, AvatarErrorCode } from '../types';
+/**
+ * Create an AvatarError from an unknown error
+ * @param error - The error to convert
+ * @param code - The error code to use
+ * @param message - Optional custom message
+ * @returns AvatarError instance
+ */
+export declare function createAvatarError(error: unknown, code: AvatarErrorCode, message?: string): AvatarError;
+/**
+ * Check if an error is a network error
+ * @param error - The error to check
+ * @returns true if it's a network error
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Check if an HTTP status code is retryable (5xx or network errors)
+ * @param statusCode - HTTP status code
+ * @returns true if the request should be retried
+ */
+export declare function isRetryableStatusCode(statusCode: number): boolean;
+/**
+ * Check if an error should trigger a retry
+ * @param error - The error to check
+ * @param statusCode - Optional HTTP status code
+ * @returns true if the operation should be retried
+ */
+export declare function shouldRetry(error: unknown, statusCode?: number): boolean;

package/src/utils/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Logging utilities for the Kaltura Avatar SDK
+ */
+/**
+ * Log levels in order of severity
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+/**
+ * Simple logger interface
+ */
+export interface Logger {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * Create a logger with a specific prefix and minimum log level
+ *
+ * @param prefix - Prefix for log messages (e.g., class name)
+ * @param minLevel - Minimum log level to output
+ * @returns Logger instance
+ */
+export declare function createLogger(prefix: string, minLevel?: LogLevel): Logger;
+/**
+ * Convert string log level to LogLevel enum
+ *
+ * @param level - String log level
+ * @returns LogLevel enum value
+ */
+export declare function parseLogLevel(level?: string): LogLevel;

package/src/utils/retry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Retry utilities with exponential backoff for the Kaltura Avatar SDK
+ */
+import { RetryConfig } from '../types';
+/**
+ * Execute a function with retry logic and exponential backoff
+ *
+ * @param fn - The async function to execute
+ * @param config - Retry configuration
+ * @param shouldRetryFn - Optional function to determine if error should trigger retry
+ * @returns Promise that resolves with the function result
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await retryWithBackoff(
+ *   async () => await fetch('/api/endpoint'),
+ *   { maxAttempts: 3, initialDelayMs: 500, maxDelayMs: 5000, backoffMultiplier: 2 }
+ * );
+ * ```
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, config: RetryConfig, shouldRetryFn?: (error: unknown, attempt: number) => boolean): Promise<T>;
+/**
+ * Wait for a condition to be true with timeout
+ *
+ * @param condition - Function that returns true when condition is met
+ * @param timeoutMs - Maximum time to wait in milliseconds
+ * @param checkIntervalMs - How often to check the condition (default: 100ms)
+ * @returns Promise that resolves when condition is true
+ * @throws Error if timeout is reached
+ */
+export declare function waitForCondition(condition: () => boolean, timeoutMs: number, checkIntervalMs?: number): Promise<void>;

package/src/utils/text-chunker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Text chunking utilities for the Kaltura Avatar SDK
+ *
+ * The avatar backend processes text more efficiently when sent in small chunks.
+ * This utility splits text into word-based chunks for optimal processing.
+ */
+/**
+ * Split text into chunks of N words each
+ *
+ * @param text - The text to chunk
+ * @param wordsPerChunk - Number of words per chunk (default: 3)
+ * @returns Array of text chunks
+ *
+ * @example
+ * ```typescript
+ * chunkText('Hello how are you doing today', 3)
+ * // Returns: ['Hello how are', 'you doing today']
+ *
+ * chunkText('Hi there', 3)
+ * // Returns: ['Hi there']
+ * ```
+ */
+export declare function chunkText(text: string, wordsPerChunk?: number): string[];
+/**
+ * Generate a unique turn ID for grouping related text chunks
+ * Uses UUID v4 format
+ *
+ * @returns UUID string
+ */
+export declare function generateTurnId(): string;