@jaaq/jaaq-sdk-js 1.0.1 → 1.1.0

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

@@ -0,0 +1,288 @@
+/**
+ * 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;
+
+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;
+};
+
+/**
+ * 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;
+}
+
+export { JaaqCollectionPlayerElement, JaaqVideoPlayerElement, isRegistered, registerJaaqComponents };
+export type { PlayerConfig, PlayerEventMap, PlayerState };