@interactive-video-labs/core/dist/index.d.mts

Framework-agnostic interactive video engine core

/**
 * Interactive Video Labs Player Types
 * This file defines the types and interfaces used in the IVLabsPlayer.
 * It includes types for player configuration, cue points, interactions, analytics,
 * and localization.
 */
type PlayerConfig = {
    videoUrl?: string;
    cues?: CuePoint[];
    subtitlesUrl?: string;
    locale?: string;
    translations?: Record<string, Translations>;
    autoplay?: boolean;
    loop?: boolean;
    analyticsOptions?: Record<string, any>;
    interactions?: InteractionPayload[];
    initialState?: PlayerState;
    decisionAdapterType?: 'memory' | 'localStorage';
    decisionAdapter?: DecisionAdapter;
};
type Translations = Record<string, string | Record<string, string>>;
type CuePoint = {
    id: string;
    time: number;
    label?: string;
    payload?: any;
};
type InteractionResponse = {
    cueId: string;
    choice: string;
    metadata?: Record<string, any>;
};
type AnalyticsEvent = 'PLAYER_LOADED' | 'VIDEO_STARTED' | 'VIDEO_PAUSED' | 'CUE_LOADED' | 'CUE_TRIGGERED' | 'INTERACTION_SHOWN' | 'INTERACTION_COMPLETED' | 'VIDEO_ENDED' | 'PLAYER_DESTROYED' | 'ERROR' | 'onCueEnter' | 'onPromptShown' | 'onInteractionSelected' | 'onBranchJump' | 'onSessionEnd';
type AnalyticsPayload = {
    event: AnalyticsEvent;
    timestamp: number;
    cueId?: string;
    data?: any;
};
interface AnalyticsHook$1 {
    (payload?: AnalyticsPayload): void;
}
type ChoiceVideoSegmentChangeOption = {
    level: string;
    video: string;
};
type InteractionPayload = {
    type: 'choice' | 'text' | 'rating' | 'choice-video-segment-change';
    title?: string;
    description?: string;
    question: string;
    options?: (string | ChoiceVideoSegmentChangeOption)[];
    correctAnswer?: string;
    response?: Record<string, any>;
};
type PlayerEvent = 'play' | 'pause' | 'ended' | 'cue' | 'interaction' | 'branch' | 'error' | 'segmentchange';
type InteractionSegment = {
    id: string;
    cueId: string;
    payload: InteractionPayload;
    triggerTime?: number;
};
type PlayerState = 'idle' | 'playing' | 'waitingForInteraction' | 'ended' | 'error';
interface HTMLVideoElementWithControlsList extends HTMLVideoElement {
    controlsList: string;
}
type Decision = {
    cueId: string;
    choice: string;
    timestamp: number;
    metadata?: Record<string, any>;
};
interface DecisionAdapter {
    saveDecision(decision: Decision): Promise<void>;
    getDecisionHistory(): Promise<Decision[]>;
    clearDecisionHistory(): Promise<void>;
}

/**
 * The main class for the Interactive Video Labs Player.
 * This class orchestrates the video playback, cue handling, interaction management,
 * and analytics tracking.
 */
declare class IVLabsPlayer {
    private videoElement;
    private config;
    private stateMachine;
    private cueHandler;
    private interactionManager;
    private analytics;
    private segmentManager;
    private i18n;
    private decisionAdapter;
    private videoContainer;
    constructor(target: string, config: PlayerConfig);
    /**
     * Binds event listeners for cue handling, interaction response, and analytics.
     */
    private bindEvents;
    /** Loads cue points into the player. */
    loadCues(cues: CuePoint[]): void;
    /** Loads interaction segments into the player. */
    loadInteractions(interactions: CuePoint[]): void;
    /** Returns the current player state. */
    getState(): PlayerState;
    /** Plays the video. */
    play(): void;
    /** Pauses the video. */
    pause(): void;
    /**
     * Registers a custom analytics hook for a specific event.
     * @param event - The event to listen for.
     * @param callback - The function to be called when the event is tracked.
     */
    on(event: AnalyticsEvent, callback: (payload: AnalyticsPayload | undefined) => void): void;
    /**
     * Sets the current language for localization.
     * @param locale - The new locale.
     */
    setLocale(locale: string): void;
    /**
     * Loads a set of translations for a specific locale.
     * @param locale - The locale for the translations.
     * @param translations - The translation data.
     */
    loadTranslations(locale: string, translations: Translations): void;
    /**
     * Retrieves the user's decision history.
     * @returns A promise that resolves to an array of Decision objects.
     */
    getDecisionHistory(): Promise<Decision[]>;
    /**
     * Clears the user's decision history.
     * @returns A promise that resolves when the history is cleared.
     */
    clearDecisionHistory(): Promise<void>;
    /**
     * Injects fallback CSS into the document head.
     * This ensures basic styling is present even if external stylesheets are not loaded.
     */
    private _injectFallbackCss;
    /** Cleans up the player, removes listeners and resets state. */
    destroy(): void;
}

type StateTransition<S extends string> = {
    from: S;
    to: S;
    condition?: () => boolean;
    action?: () => void;
};
/**
 * Manages state transitions for the player.
 * This class provides a generic state machine implementation that allows
 * defining states, transitions between them, and actions to be performed
 * during transitions.
 */
declare class StateMachine<S extends string = PlayerState> {
    private currentState;
    private transitions;
    /**
     * Creates an instance of StateMachine.
     * @param initialState - The initial state of the state machine.
     */
    constructor(initialState: S);
    /**
     * Gets the current state of the state machine.
     * @returns The current state.
     */
    getState(): S;
    /**
     * Adds a new state transition to the state machine.
     * @param transition - The state transition to be added.
     */
    addTransition(transition: StateTransition<S>): void;
    /**
     * Transitions to a new state if the transition is valid.
     * @param targetState - The state to transition to.
     * @returns True if the transition was successful, false otherwise.
     */
    transitionTo(targetState: S): boolean;
    /**
     * Resets the state machine to its initial state.
     * @param initialState - Optional initial state to reset to.
     */
    reset(initialState?: S): void;
}

type CueCallback = (cue: CuePoint) => void;
/**
 * Manages and triggers cue points during video playback.
 * This class is responsible for registering cue points, listening for video
 * time updates, and triggering registered callbacks when a cue point is reached.
 */
declare class CueHandler {
    private cues;
    private callback?;
    private triggered;
    private videoElement;
    /**
     * Creates an instance of CueHandler.
     * @param video - The HTMLVideoElement to monitor for cue points.
     */
    constructor(video: HTMLVideoElement);
    /**
     * Registers cue points and sets up the video element to listen for time updates.
     * @param cues - An array of Cue objects to register.
     */
    registerCues(cues: CuePoint[]): void;
    loadCues(cues: CuePoint[]): void;
    /**
     * Sets the callback function to be called when a cue point is reached.
     * @param callback - The callback function to be executed.
     */
    onCue(callback: CueCallback): void;
    /**
     * Starts listening for cue points.
     */
    start(): void;
    /**
     * Stops listening for cue points.
     */
    stop(): void;
    /**
     *  Handles the time update event from the video element.
     *  Checks if the current time matches any registered cue points and triggers the callback.
     */
    private handleTimeUpdate;
    /**
     * Destroys the CueHandler instance.
     */
    destroy(): void;
}

/**
 * The I18n class handles internationalization for the player.
 * It allows loading translations for different locales and provides methods to translate keys.
 */
declare class I18n {
    private translations;
    private locale;
    /**
     * Loads translations for a specific locale.
     * @param locale - The locale to load translations for.
     * @param translations - The translation data.
     */
    load(locale: string, translations: Translations): void;
    /**
     * Sets the current locale for localization.
     * @param locale - The new locale.
     */
    setLocale(locale: string): void;
    /**
     * Translates a key to the current locale.
     * @param key - The key to translate.
     * @param options - Optional placeholders to replace in the translation.
     * @returns The translated string or the original key if not found.
     */
    translate(key: string, options?: Record<string, string>): string;
    /**
     * Gets the translation for a key in a specific locale.
     * @param key - The key to translate.
     * @param locale - The locale to get the translation for.
     * @returns The translated string or undefined if not found.
     */
    private getTranslation;
    /**
     * Replaces placeholders in a translation string.
     * @param text - The translation string with placeholders.
     * @param options - Optional placeholders to replace in the translation.
     * @returns The translated string with placeholders replaced.
     */
    private replacePlaceholders;
}

type InteractionHandler = (payload: InteractionPayload, cue: CuePoint) => void;
type ResponseHandler = (response: any, cue: CuePoint) => void;
/**
 * Manages the lifecycle of interactions within the player.
 * This class is responsible for rendering interactions, handling user responses,
 * and communicating with the parent application.
 */
declare class InteractionManager {
    private onPromptCallback?;
    private onResponseCallback?;
    private container;
    private interactionDiv;
    private interactionRenderers;
    private interactionStore;
    private i18n;
    private decisionAdapter;
    /**
     * Creates an instance of InteractionManager.
     * @param container - The container element where interactions will be rendered.
     * @param i18n - The I18n instance for localization.
     */
    constructor(container: HTMLElement, i18n: I18n, decisionAdapter: DecisionAdapter);
    /**
     * Determines if the options array contains only strings.
     * @param options - Array of options to check.
     * @returns True if the array consists of strings only.
     */
    private _isStringOptions;
    /**
     * Loads interactions from a given array of cue points.
     * Stores them internally mapped by cue time.
     * @param interactions - An array of interaction cue objects to be loaded.
     */
    loadInteractions(interactions: CuePoint[]): void;
    /**
     * Registers a callback for when an interaction prompt is triggered.
     * @param handler - The function to call on interaction prompt.
     */
    onPrompt(handler: InteractionHandler): void;
    /**
     * Registers a callback for when a user responds to an interaction.
     * @param handler - The function to call on user response.
     */
    onResponse(handler: ResponseHandler): void;
    /**
     * Handles an interaction cue by rendering it and invoking the prompt handler.
     * @param cue - Cue containing interaction metadata.
     */
    handleInteractionCue(cue: CuePoint): void;
    /**
     * Renders the interaction UI based on type and cue.
     */
    private renderInteraction;
    /**
     * Renders choice-based interactions.
     */
    private renderChoiceInteraction;
    /**
     * Renders text-based interactions.
     */
    private renderTextInteraction;
    /**
     * Renders default interaction fallback.
     */
    private renderDefaultInteraction;
    /**
     * Clears currently rendered interaction UI.
     */
    private clearInteractions;
    /**
     * Invokes the response handler with processed data.
     */
    handleUserResponse(response: any, cue: CuePoint): void;
    /**
     * Destroys the manager and clears memory.
     */
    destroy(): void;
}

type AnalyticsHook = (event: AnalyticsEvent, payload?: AnalyticsPayload) => void;
/**
 * Handles analytics tracking for the player.
 * This class provides a simple interface for tracking events and allows
 * for the registration of custom hooks to process analytics data.
 */
declare class Analytics {
    private options;
    private hooks;
    /**
     * Initializes the Analytics instance.
     * @param options - Optional configuration for the analytics instance.
     */
    constructor(options?: Record<string, any>);
    /**
     * Registers a new analytics hook for a specific event.
     * @param event - The event to listen for.
     * @param hook - The function to be called when the event is tracked.
     */
    on(event: AnalyticsEvent, hook: AnalyticsHook): void;
    /**
     * Tracks an event with optional payload.
     * @param event - The event to be tracked.
     * @param payload - Optional data associated with the event.
     */
    track(event: AnalyticsEvent, payload?: AnalyticsPayload): void;
    /**
     * Resets the analytics hooks.
     */
    reset(): void;
}

export { Analytics, type AnalyticsEvent, type AnalyticsHook$1 as AnalyticsHook, type AnalyticsPayload, type ChoiceVideoSegmentChangeOption, CueHandler, type CuePoint, type Decision, type DecisionAdapter, type HTMLVideoElementWithControlsList, IVLabsPlayer, InteractionManager, type InteractionPayload, type InteractionResponse, type InteractionSegment, type PlayerConfig, type PlayerEvent, type PlayerState, StateMachine, type Translations };