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

Framework-agnostic interactive video engine core

type CuePoint = {
    id: string;
    time: number;
    subtitleText?: string;
    label?: string;
    payload?: any;
};

type InteractionResponse = {
    cueId: string;
    choice: string;
    metadata?: Record<string, any>;
};
type ChoiceVideoSegmentChangeOption = {
    level: string;
    video: string;
};
type BaseInteraction = {
    title?: string;
    description?: string;
    question: string;
};
type ChoiceInteraction = BaseInteraction & {
    type: 'choice';
    options: string[];
    correctAnswer?: string;
    response?: Record<string, any>;
};
type TextInteraction = BaseInteraction & {
    type: 'text';
    response?: Record<string, any>;
};
type RatingInteraction = BaseInteraction & {
    type: 'rating';
    response?: Record<string, any>;
};
type ChoiceVideoSegmentChangeInteraction = BaseInteraction & {
    type: 'choice-video-segment-change';
    options: ChoiceVideoSegmentChangeOption[];
    response?: Record<string, any>;
};
type InteractionPayload = ChoiceInteraction | TextInteraction | RatingInteraction | ChoiceVideoSegmentChangeInteraction;
type InteractionSegment = {
    id: string;
    cueId: string;
    payload: InteractionPayload;
    triggerTime?: number;
};

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>;
}

type Translations = Record<string, string | Record<string, string>>;

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 PlayerEvent = 'play' | 'pause' | 'ended' | 'cue' | 'interaction' | 'branch' | 'error' | 'segmentchange';
type PlayerState = 'idle' | 'playing' | 'waitingForInteraction' | 'ended' | 'error';
interface HTMLVideoElementWithControlsList extends HTMLVideoElement {
    controlsList: string;
}

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;
}

/**
 * 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 subtitlesManager?;
    private videoContainer;
    private subtitlesElement?;
    constructor(target: string, config: PlayerConfig);
    private start;
    /**
     * 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;
declare class InteractionManager {
    private onPromptCallback?;
    private onResponseCallback?;
    private container;
    private interactionDiv;
    private interactionStore;
    private i18n;
    private decisionAdapter;
    private interactionRenderers;
    constructor(container: HTMLElement, i18n: I18n, decisionAdapter: DecisionAdapter);
    loadInteractions(interactions: CuePoint[]): void;
    onPrompt(handler: InteractionHandler): void;
    onResponse(handler: ResponseHandler): void;
    handleInteractionCue(cue: CuePoint): void;
    private renderInteraction;
    private renderRatingInteraction;
    private renderChoiceInteraction;
    private renderChoiceVideoSegmentChangeInteraction;
    private renderTextInteraction;
    private renderDefaultInteraction;
    private clearInteractions;
    handleUserResponse(response: any, cue: CuePoint): void;
    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, unknown>);
    /**
     * 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 ChoiceInteraction, type ChoiceVideoSegmentChangeInteraction, 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, type RatingInteraction, StateMachine, type TextInteraction, type Translations };