@jaaq/jaaq-sdk-js 1.0.1 → 1.1.0

package/dist/ui/vanilla/index.d.ts

@@ -0,0 +1,465 @@
+type FetchLike = typeof globalThis.fetch;
+type RequestOptions = Parameters<typeof globalThis.fetch>[1];
+interface HttpClient {
+    get<T>(_path: string, _init?: RequestOptions): Promise<T>;
+    post<T>(_path: string, _body?: unknown, _init?: RequestOptions): Promise<T>;
+    put<T>(_path: string, _body?: unknown, _init?: RequestOptions): Promise<T>;
+    patch<T>(_path: string, _body?: unknown, _init?: RequestOptions): Promise<T>;
+    delete<T>(_path: string, _init?: RequestOptions): Promise<T>;
+}
+
+type VideoDTO = {
+    id: string;
+    videoId: string;
+    question: string;
+    status: number;
+    transcription: string;
+    subtitle: string;
+    createdAt: string;
+    videoUrl: string;
+    published: boolean;
+    tags: string[];
+    severity: number | null;
+    duration: number;
+    description: string;
+};
+
+type VideosResource = {
+    getById(_id: string): Promise<VideoDTO>;
+};
+
+type CollectionDTO = {
+    id: string;
+    name: string;
+    description: string;
+    imageUrl: string;
+    createdAt: string;
+    videos: VideoDTO[];
+};
+
+type CollectionsResource = {
+    list(): Promise<CollectionDTO[]>;
+    getById(_id: string): Promise<CollectionDTO>;
+};
+
+interface SDKConfig {
+    baseUrl?: string;
+    apiKey: string;
+    clientId: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}
+declare class JaaqClient {
+    readonly videos: VideosResource;
+    readonly collections: CollectionsResource;
+    private constructor();
+    /**
+     * Public "friend" constructor that remains inside the class boundary.
+     * This method is callable from the module-level build function
+     * without exposing `new JaaqClient(...)` to consumers.
+     */
+    static fromHttp(http: HttpClient): JaaqClient;
+    /**
+     * OO-friendly static initializer.
+     * Delegates to the single source of truth: `buildClient`.
+     */
+    static init(config: SDKConfig): JaaqClient;
+}
+
+/**
+ * Configuration options for video player components
+ */
+type PlayerConfig = {
+    /** Video ID to load */
+    videoId: string;
+    /** API key for authentication (required if no client provided) */
+    apiKey?: string;
+    /** Client ID for authentication (required if no client provided) */
+    clientId?: string;
+    /** Existing JaaqClient instance to use instead of creating a new one */
+    client?: JaaqClient;
+    /** Custom API base URL */
+    baseUrl?: string;
+    /** Whether to automatically start playback when video loads */
+    autoplay?: boolean;
+    /** Whether to show player controls */
+    controls?: boolean;
+    /** CSS width of the player container */
+    width?: string;
+    /** CSS height of the player container */
+    height?: string;
+    /** Additional CSS class name(s) to apply to the player */
+    className?: string;
+    /** Whether to show the JAAQ logo */
+    showLogo?: boolean;
+    /** Whether to show the video title */
+    showTitle?: boolean;
+    /** Whether to show the author name */
+    showAuthor?: boolean;
+    /** Whether to show the description */
+    showDescription?: boolean;
+    /** Whether to show captions button */
+    showCaptions?: boolean;
+};
+/**
+ * Current state of the video player
+ */
+type PlayerState = {
+    /** Whether the video is currently playing */
+    isPlaying: boolean;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Total video duration in seconds */
+    duration: number;
+    /** Current volume level (0-1) */
+    volume: number;
+    /** Whether the audio is muted */
+    isMuted: boolean;
+    /** Whether the player is in fullscreen mode */
+    isFullscreen: boolean;
+    /** Whether the video is currently loading */
+    isLoading: boolean;
+    /** Error message if an error occurred, null otherwise */
+    error: string | null;
+    /** Loaded video data, null if not yet loaded */
+    videoData: VideoDTO | null;
+    /** Whether captions are currently enabled */
+    captionsEnabled: boolean;
+};
+/**
+ * Map of player event names to their payload types
+ */
+type PlayerEventMap = {
+    /** Fired when playback starts */
+    play: void;
+    /** Fired when playback pauses */
+    pause: void;
+    /** Fired when playback time updates, provides current time in seconds */
+    timeupdate: number;
+    /** Fired when volume changes, provides new volume level (0-1) */
+    volumechange: number;
+    /** Fired when playback reaches the end */
+    ended: void;
+    /** Fired when an error occurs, provides Error object */
+    error: Error;
+    /** Fired when video metadata is loaded, provides VideoDTO */
+    loaded: VideoDTO;
+    /** Fired when fullscreen state changes, provides boolean fullscreen state */
+    fullscreenchange: boolean;
+};
+/**
+ * Event callback function type for player events
+ * @template T - The type of data passed to the callback
+ */
+type PlayerEventCallback<T> = (_data: T) => void;
+
+declare class JaaqVideoPlayer {
+    private container;
+    private config;
+    private client;
+    private hls;
+    private videoElement;
+    private state;
+    private listeners;
+    private captionCues;
+    private elements;
+    /**
+     * Creates a new video player instance
+     * @param container - HTML element or CSS selector to render the player into
+     * @param config - Player configuration options
+     * @throws {Error} If container element is not found or if authentication credentials are missing
+     */
+    constructor(container: HTMLElement | string, config: PlayerConfig);
+    private init;
+    private createDOM;
+    private updateControlsVisibility;
+    private loadVideo;
+    private parseWebVTT;
+    private updateOverlayContent;
+    private attachEventListeners;
+    private setState;
+    private updatePlayPauseButton;
+    private updateProgress;
+    private updateVolumeUI;
+    private updateCaptions;
+    private handleSeek;
+    private showError;
+    private togglePlayPause;
+    private toggleCaptions;
+    private updateCaptionsButton;
+    private toggleFullscreen;
+    /**
+     * Starts or resumes video playback
+     */
+    play(): void;
+    /**
+     * Pauses video playback
+     */
+    pause(): void;
+    /**
+     * Sets the playback volume
+     * @param volume - Volume level between 0 (silent) and 1 (maximum)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Toggles audio mute state
+     */
+    toggleMute(): void;
+    /**
+     * Seeks to a specific time in the video
+     * @param time - Target time in seconds
+     */
+    seek(time: number): void;
+    setFeatures(features: Partial<Pick<PlayerConfig, 'showLogo' | 'showTitle' | 'showAuthor' | 'showDescription' | 'showCaptions' | 'controls'>>): void;
+    /**
+     * Returns a copy of the current player state
+     * @returns Current player state object
+     */
+    getState(): PlayerState;
+    /**
+     * Registers an event listener for player events
+     * @param event - Event name to listen for
+     * @param callback - Function to call when event fires
+     */
+    on<K extends keyof PlayerEventMap>(event: K, callback: PlayerEventCallback<PlayerEventMap[K]>): void;
+    /**
+     * Removes an event listener for player events
+     * @param event - Event name to stop listening for
+     * @param callback - Function to remove from listeners
+     */
+    off<K extends keyof PlayerEventMap>(event: K, callback: PlayerEventCallback<PlayerEventMap[K]>): void;
+    private emit;
+    /**
+     * Destroys the player instance and cleans up resources
+     * Removes all event listeners, stops playback, and clears the DOM
+     */
+    destroy(): void;
+}
+
+type CollectionPlayerConfig = {
+    collectionId: string;
+    client?: JaaqClient;
+    apiKey?: string;
+    clientId?: string;
+    baseUrl?: string;
+    autoplay?: boolean;
+    showArrows?: boolean;
+    showDots?: boolean;
+    className?: string;
+};
+type CollectionPlayerEventMap = {
+    loaded: CollectionDTO;
+    slidechange: {
+        index: number;
+        video: VideoDTO;
+    };
+    error: Error;
+};
+type CollectionPlayerEventCallback<T> = (_data: T) => void;
+declare class JaaqCollectionPlayer {
+    private container;
+    private config;
+    private client;
+    private splide;
+    private playerElement;
+    private carouselElement;
+    private collectionData;
+    private autoplayTimeoutId;
+    private listeners;
+    constructor(container: HTMLElement | string, config: CollectionPlayerConfig);
+    private init;
+    private render;
+    private initCarousel;
+    private showLoading;
+    private renderCarousel;
+    private initSplide;
+    private handleSlideChange;
+    private destroyCarousel;
+    private emitError;
+    on<K extends keyof CollectionPlayerEventMap>(event: K, callback: CollectionPlayerEventCallback<CollectionPlayerEventMap[K]>): void;
+    off<K extends keyof CollectionPlayerEventMap>(event: K, callback: CollectionPlayerEventCallback<CollectionPlayerEventMap[K]>): void;
+    private emit;
+    refresh(): void;
+    next(): void;
+    prev(): void;
+    go(index: number): void;
+    destroy(): void;
+    getCollection(): CollectionDTO | null;
+}
+
+/**
+ * Initializes all video players with data-jaaq-player attribute
+ * @param rootElement - Root element to search for players (defaults to document)
+ */
+declare function initializePlayers(rootElement?: Document | Element): void;
+/**
+ * Retrieves a player instance for a given element or selector
+ * @param elementOrSelector - DOM element or CSS selector
+ * @returns Player instance or null if not found
+ */
+declare function getPlayer(elementOrSelector: Element | string): JaaqVideoPlayer | null;
+/**
+ * Destroys all initialized player instances and cleans up resources
+ */
+declare function destroyAll(): void;
+/**
+ * Auto-initialization API for declarative video player setup
+ * Automatically finds and initializes players marked with [data-jaaq-player]
+ * @example
+ * // Auto-initialization on page load
+ * <div data-jaaq-player data-api-key="key" data-client-id="id" data-video-id="video"></div>
+ *
+ * // Manual initialization
+ * JaaqPlayer.init();
+ *
+ * // Get player instance
+ * const player = JaaqPlayer.getPlayer('[data-video-id="video"]');
+ * player.on('play', () => console.log('Playing'));
+ */
+declare const JaaqPlayer: {
+    /** Initialize all players with [data-jaaq-player] attribute */
+    init: typeof initializePlayers;
+    /** Get player instance by element or selector */
+    getPlayer: typeof getPlayer;
+    /** Destroy all initialized players */
+    destroyAll: typeof destroyAll;
+};
+
+/**
+ * Custom web component for JAAQ video player with Shadow DOM encapsulation
+ * Provides a framework-agnostic video player with custom controls and HLS support
+ *
+ * @example
+ * // Declarative usage
+ * <jaaq-video-player
+ *   video-id="video-123"
+ *   api-key="key"
+ *   client-id="client"
+ *   autoplay="false">
+ * </jaaq-video-player>
+ *
+ * @example
+ * // Programmatic usage
+ * const player = document.createElement('jaaq-video-player');
+ * player.setAttribute('video-id', 'video-123');
+ * player.addEventListener('jaaq:play', () => console.log('Playing'));
+ * document.body.appendChild(player);
+ */
+declare class JaaqVideoPlayerElement extends HTMLElement {
+    private player;
+    private container;
+    private clientInstance;
+    private connected;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private render;
+    private updateContainerStyles;
+    private initPlayer;
+    private attachPlayerEvents;
+    private emitError;
+    private destroyPlayer;
+    /**
+     * Gets the current JaaqClient instance
+     */
+    get client(): JaaqClient | null;
+    /**
+     * Sets a JaaqClient instance for the player to use
+     * Reinitializes the player if already connected
+     */
+    set client(value: JaaqClient | null);
+    /**
+     * Gets the current video ID
+     */
+    get videoId(): string | null;
+    /**
+     * Sets the video ID
+     * Updates the video-id attribute and triggers player reinitialization
+     */
+    set videoId(value: string | null);
+    /**
+     * Starts or resumes video playback
+     */
+    play(): void;
+    /**
+     * Pauses video playback
+     */
+    pause(): void;
+    /**
+     * Sets the playback volume
+     * @param volume - Volume level between 0 (silent) and 1 (maximum)
+     */
+    setVolume(volume: number): void;
+    /**
+     * Toggles audio mute state
+     */
+    toggleMute(): void;
+    /**
+     * Seeks to a specific time in the video
+     * @param time - Target time in seconds
+     */
+    seek(time: number): void;
+    /**
+     * Returns the current player state
+     * @returns Current player state object or null if player not initialized
+     */
+    getState(): PlayerState | null;
+    /**
+     * Destroys the player instance and cleans up resources
+     */
+    destroy(): void;
+}
+
+declare class JaaqCollectionPlayerElement extends HTMLElement {
+    private splide;
+    private container;
+    private carouselElement;
+    private clientInstance;
+    private connected;
+    private collectionData;
+    private autoplayTimeoutId;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private getBooleanAttr;
+    private render;
+    private initCarousel;
+    private showLoading;
+    private renderCarousel;
+    private initSplide;
+    private handleSlideChange;
+    private destroyCarousel;
+    private emitError;
+    get client(): JaaqClient | null;
+    set client(value: JaaqClient | null);
+    get collectionId(): string | null;
+    set collectionId(value: string | null);
+    refresh(): void;
+    next(): void;
+    prev(): void;
+    go(index: number): void;
+    destroy(): void;
+    getCollection(): CollectionDTO | null;
+}
+
+/**
+ * Registers JAAQ custom elements (<jaaq-video-player> and <jaaq-collection-player>)
+ * Safe to call multiple times - only registers if not already registered
+ *
+ * @example
+ * import { registerJaaqComponents } from '@jaaq/jaaq-sdk-js/ui/webcomponents';
+ * registerJaaqComponents();
+ */
+declare function registerJaaqComponents(): void;
+/**
+ * Checks if the JAAQ web components are already registered
+ * @returns True if components are registered, false otherwise
+ */
+declare function isRegistered(): boolean;
+
+export { JaaqCollectionPlayer, JaaqCollectionPlayerElement, JaaqPlayer, JaaqVideoPlayer, JaaqVideoPlayerElement, isRegistered, registerJaaqComponents };
+export type { PlayerConfig, PlayerEventMap, PlayerState };