boss-web-player-sdk 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,897 @@
+import { default as default_2 } from 'react';
+import { JSX } from 'react/jsx-runtime';
+
+export declare type AnalyticsCallback = (event: AnalyticsEvent) => void;
+
+export declare interface AnalyticsEvent {
+    eventType: 'play' | 'pause' | 'seek' | 'ended' | 'complete' | 'buffering_start' | 'buffering_end' | 'stall' | 'quality_change' | 'audio_track_change' | 'volume_change' | 'speed_change' | 'subtitle_change' | 'mute' | 'fast_forward' | 'fast_backward' | 'key_moments' | 'pip_toggle' | 'fullscreen_enter' | 'fullscreen_exit' | 'cast_start' | 'cast_stop' | 'error' | 'network_error' | 'session_start' | 'video_loaded' | 'first_quartile' | 'midpoint' | 'third_quartile' | 'heartbeat' | 'watch_progress' | 'streaming_time';
+    timestamp: number;
+    currentTime: number;
+    duration: number;
+    bitrate?: number;
+    rendition?: string;
+    fromRendition?: string;
+    volume?: number;
+    speed?: number;
+    errorMessage?: string;
+    errorCode?: number;
+    isRecoverable?: boolean;
+    sessionId?: string;
+    videoId?: string;
+    deviceType?: string;
+    networkType?: string;
+    watchPercentage?: number;
+    totalWatchTime?: number;
+    streamingTime?: number;
+    adWatchTime?: number;
+    bufferingCount?: number;
+    totalBufferingTime?: number;
+    seekFrom?: number;
+    seekTo?: number;
+    isMuted?: boolean;
+    skipSeconds?: number;
+    momentTitle?: string;
+    momentTime?: number;
+    pipState?: 'entered' | 'exited';
+    audioTrack?: string;
+    subtitleLanguage?: string;
+    subtitleEnabled?: boolean;
+    isAutoSwitch?: boolean;
+}
+
+declare class AnalyticsModule {
+    private callback?;
+    private heartbeatInterval?;
+    private watchProgressTimer?;
+    private isBuffering;
+    private sessionId;
+    private videoId;
+    private deviceType;
+    private networkType;
+    private adBreaks;
+    private isFirstPlay;
+    private watchStartTime;
+    private totalWatchTime;
+    private streamingWindowStart;
+    private streamingTime;
+    private isInAdBreak;
+    private adWatchWindowStart;
+    private adWatchTime;
+    private bufferingCount;
+    private totalBufferingTime;
+    private bufferingStartTime;
+    private milestonesHit;
+    private lastHeartbeatPosition;
+    private lastHeartbeatAt;
+    constructor(callback?: AnalyticsCallback, src?: string, seed?: AnalyticsSessionSnapshot, videoId?: string);
+    getSessionSnapshot(): AnalyticsSessionSnapshot;
+    registerCallback(callback: AnalyticsCallback): void;
+    setAdBreaks(adBreaks: Array<{
+        startTime: number;
+        endTime: number;
+    }>): void;
+    private getTotalAdDuration;
+    private getElapsedAdTime;
+    track(eventType: AnalyticsEvent['eventType'], videoEl: HTMLVideoElement, extra?: Partial<AnalyticsEvent>): void;
+    startHeartbeat(videoEl: HTMLVideoElement, getExtra: () => Partial<AnalyticsEvent>, watchProgressInterval?: number): void;
+    stopHeartbeat(): void;
+    setBuffering(isBuffering: boolean, videoEl: HTMLVideoElement, getExtra: () => Partial<AnalyticsEvent>): void;
+    setAdBreak(inAdBreak: boolean, videoEl: HTMLVideoElement): void;
+    private checkMilestones;
+    private checkStall;
+    private getTotalWatchTime;
+    private getStreamingTime;
+    private getAdWatchTime;
+    private dispatchRaw;
+    private generateSessionId;
+    private extractVideoId;
+    private getDeviceType;
+    private getNetworkType;
+}
+
+declare interface AnalyticsSessionSnapshot {
+    sessionId: string;
+    /** True once session_start has fired — a seeded module must not fire it again. */
+    sessionStartFired: boolean;
+    totalWatchTime: number;
+    streamingTime: number;
+    adWatchTime: number;
+    bufferingCount: number;
+    totalBufferingTime: number;
+    /** Quartile milestones already dispatched ('first_quartile' | 'midpoint' | 'third_quartile'). */
+    milestonesHit: string[];
+}
+
+export declare function BossVideoPlayer({ playerKey, src, subtitles, licenseKey, themeColor, firebaseConfig, proxyDomains, apiBaseUrl, adTrackingUrl, overlayAdUrl, videoId: videoIdProp, title, watermark, autoplay, muted, autoFullscreen, enableControls, enableSkipAd, skipAdAfterSeconds, chaptersDisplayMode, volumeControlType, subtitleStyle, drmConfig, onAnalyticsEvent, delegate, onKeyMomentsLoaded, initialTime, onTimeUpdate, }: BossVideoPlayerProps): JSX.Element;
+
+export declare interface BossVideoPlayerProps {
+    /** Player key from the GoBOSS dashboard — identifies your tenant. */
+    playerKey: string;
+    /**
+     * Stream source(s) to play.
+     * - Pass a single URL string for standard single-stream playback.
+     * - Pass an array of `{ label, url }` objects to let the user switch between
+     *   multiple streams at runtime (e.g. 4K, Dolby, Stereo). The first item plays by default.
+     */
+    src: string | SourceItem[];
+    /**
+     * External subtitle tracks (WebVTT/SRT) to load alongside any tracks
+     * auto-detected from the M3U8 manifest. Merged into a single subtitle menu.
+     */
+    subtitles?: SubtitleTrack[];
+    /** License key for playback authorization. */
+    licenseKey?: string;
+    /** Accent color for the player UI (hex). Defaults to '#6366f1'. */
+    themeColor?: string;
+    /** Firebase config for analytics. */
+    firebaseConfig?: FirebaseConfig;
+    /**
+     * CDN proxy domain mappings as a comma-separated string.
+     * Format: "cdn.example.com=/my-proxy,other.cdn.com=/other-proxy"
+     * Any request URL matching a domain is rewritten to the proxy path.
+     */
+    proxyDomains?: string;
+    /**
+     * Base URL for the GoBOSS API. Defaults to 'https://dev-api.go-boss.com'.
+     * Override this if you need to route through a reverse proxy.
+     */
+    apiBaseUrl?: string;
+    /** AWS MediaTailor ad tracking URL for skip-ad flow. */
+    adTrackingUrl?: string;
+    /** AWS MediaTailor overlay ad tracking URL. */
+    overlayAdUrl?: string;
+    videoId?: string;
+    /** Video title shown in the player UI. */
+    title?: string;
+    /** Watermark text stamped on the video. */
+    watermark?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    autoFullscreen?: boolean;
+    enableControls?: boolean;
+    enableSkipAd?: boolean;
+    skipAdAfterSeconds?: number;
+    chaptersDisplayMode?: 'strip' | 'panel';
+    volumeControlType?: 'slider' | 'button';
+    subtitleStyle?: SubtitleStyle;
+    drmConfig?: DRMConfig;
+    /** Called for every analytics event — lets consumers add custom tracking. */
+    onAnalyticsEvent?: (event: AnalyticsEvent) => void;
+    /**
+     * Typed per-event callbacks (playerDidStartPlaying, playerDidPause, …) that
+     * receive only the arguments relevant to each event. Prefer this over
+     * `onAnalyticsEvent` for analytics, logging, and business logic; implement
+     * only the methods you need.
+     */
+    delegate?: PlayerDelegate;
+    /** Called when chapter/key-moment data is parsed from the stream. */
+    onKeyMomentsLoaded?: (keyMoments: Chapter[]) => void;
+    /** Seek to this position (in seconds) when the video is ready. Use for resume-playback. */
+    initialTime?: number;
+    /** Called on every timeupdate with the current playback position in seconds. Use to persist watch progress. */
+    onTimeUpdate?: (currentTime: number) => void;
+}
+
+declare class CastingModule {
+    private isCasting;
+    private castDeviceName;
+    private onCastStateChangeCallback?;
+    private onRemoteStateChangeCallback?;
+    private castContext;
+    private remotePlayer;
+    private remotePlayerController;
+    constructor();
+    private initCastApi;
+    getCastingState(): {
+        isCasting: boolean;
+        deviceName: string;
+    };
+    getRemoteState(): RemoteCastState | null;
+    /**
+     * Derives the Cast MediaInfo content type from the stream URL so HLS/DASH manifests
+     * aren't sent to the receiver mislabeled as video/mp4, which causes load failures.
+     */
+    private getContentType;
+    /**
+     * Prompts the native Google Cast device picker overlay, then loads media on the remote device.
+     * The caller is responsible for pausing local playback before/after this resolves.
+     */
+    requestSession(currentSrc: string, currentTime: number): Promise<void>;
+    /**
+     * Disconnects the current cast session.
+     */
+    stopCasting(): void;
+    remotePlayPause(): void;
+    remoteSeek(time: number): void;
+    remoteSetVolume(volume: number): void;
+    remoteSetMute(muted: boolean): void;
+    onCastStateChange(callback: (isCasting: boolean, deviceName: string) => void): void;
+    onRemoteStateChange(callback: (state: RemoteCastState) => void): void;
+    requestAirPlaySession(videoElement: HTMLVideoElement): void;
+    stopAirPlay(videoElement: HTMLVideoElement): void;
+    isAirPlayAvailable(): boolean;
+}
+
+export declare interface Chapter {
+    title: string;
+    startTime: number;
+    endTime: number;
+    thumbnail?: string;
+    description?: string;
+}
+
+declare class ChaptersModule extends KeyMomentsModule {
+}
+
+/**
+ * Mounts the full video player into any DOM element.
+ * Identical to <BossVideoPlayer> — handles player key validation, feature gating,
+ * session tracking, and heartbeat automatically.
+ *
+ * Use this in Vue, Angular, Vanilla JS, or any environment where JSX is unavailable.
+ *
+ * @example Vanilla JS
+ *   const player = createPlayer(document.getElementById('player'), {
+ *     playerKey: 'bsp_abc123',
+ *     src: 'https://my-cdn.com/video.m3u8',
+ *   });
+ *   player.destroy(); // cleanup
+ *
+ * @example Vue 3
+ *   const player = createPlayer(containerRef.value, { playerKey: 'bsp_abc123', src: props.src });
+ *   onUnmounted(() => player.destroy());
+ *
+ * @example Angular
+ *   const player = createPlayer(this.containerRef.nativeElement, { playerKey: 'bsp_abc123', src: this.src });
+ *   ngOnDestroy() { this.player.destroy(); }
+ */
+export declare function createPlayer(container: HTMLElement, props: PlayerProps): PlayerInstance;
+
+export declare interface DRMConfig {
+    widevineLicenseUrl?: string;
+    playreadyLicenseUrl?: string;
+    fairplayLicenseUrl?: string;
+    authToken?: string;
+    authHeader?: string;
+    allowedDomains?: string[];
+    watermarkText?: string;
+}
+
+declare class DRMModule {
+    private config?;
+    private watermarkElement?;
+    private floatInterval?;
+    constructor(config?: DRMConfig);
+    /**
+     * Validates if the active origin domain is permitted to load this stream asset.
+     */
+    validateDomain(currentDomain: string): boolean;
+    getAuthToken(): string | undefined;
+    getAuthHeader(): string | undefined;
+    getRequestHeaders(): Record<string, string>;
+    /**
+     * Injects an animated floating watermark on top of the media container to obstruct piracy or recording.
+     */
+    setupWatermark(container: HTMLElement): void;
+    /**
+     * Cleans up active watermarks.
+     */
+    removeWatermark(): void;
+    isDRMProtected(): boolean;
+    getDRMDetails(): {
+        widevine: string | null;
+        playready: string | null;
+        fairplay: string | null;
+        authTokenPresent: boolean;
+        allowedDomains: string[];
+    };
+}
+
+/**
+ * Ends the session and finalizes billed minutes. `currentTime` and `duration`
+ * are required by the API — pass the final playback position and content length.
+ */
+export declare function endSession(playerKey: string, sessionId: string, currentTime?: number, duration?: number, apiBase?: string): Promise<void>;
+
+export declare type FeatureFlags = {
+    m3u8_playback: boolean;
+    subtitle_support: boolean;
+    playback_speed: boolean;
+    airplay: boolean;
+    chromecast: boolean;
+    picture_in_picture: boolean;
+    multiple_resolution: boolean;
+    multiple_audio: boolean;
+    key_moments: boolean;
+    drm_protection: boolean;
+    screen_recording_prevention: boolean;
+    signal_strength: boolean;
+    ad_support: boolean;
+};
+
+/**
+ * Sends all player analytics events to Firebase Analytics (GA4).
+ *
+ * Events appear in:
+ *   Firebase Console → Analytics → Events       (24-48 hr aggregated view)
+ *   Firebase Console → Analytics → DebugView    (real-time while testing)
+ *   Google Analytics 4 → Reports → Realtime     (within a few minutes)
+ *
+ * No Firestore / database setup required — Firebase Analytics handles all storage.
+ */
+export declare class FirebaseAnalyticsProvider {
+    private analytics;
+    private logEventFn;
+    private pendingEvents;
+    constructor(config: FirebaseConfig);
+    private init;
+    private flushPending;
+    createCallback(): AnalyticsCallback;
+    private handleEvent;
+    private logToFirebase;
+    private buildParams;
+    destroy(): Promise<void>;
+}
+
+export declare interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+    measurementId?: string;
+}
+
+export declare function initSdk(playerKey: string, apiBase?: string, options?: SdkInitOptions): Promise<SdkInitResponse>;
+
+export declare type KeyMoment = Chapter;
+
+declare class KeyMomentsModule {
+    private keyMoments;
+    private currentMomentIndex;
+    private onMomentChangeCallback?;
+    constructor(keyMoments?: KeyMoment[]);
+    /**
+     * Sorts and stores the key moments.
+     */
+    setKeyMoments(keyMoments: KeyMoment[]): void;
+    getKeyMoments(): KeyMoment[];
+    /**
+     * Locates the key moment corresponding to the active playback timestamp.
+     */
+    getCurrentMoment(currentTime: number): {
+        keyMoment: KeyMoment | null;
+        index: number;
+    };
+    /**
+     * Evaluates if playback has crossed a key moment boundary.
+     */
+    updateTime(currentTime: number): void;
+    /**
+     * Subscribes a callback to change events.
+     */
+    onMomentChange(callback: (keyMoment: KeyMoment | null, index: number) => void): void;
+    setChapters(chapters: KeyMoment[]): void;
+    getChapters(): KeyMoment[];
+    getCurrentChapter(currentTime: number): {
+        chapter: KeyMoment | null;
+        index: number;
+    };
+    onChapterChange(callback: (chapter: KeyMoment | null, index: number) => void): void;
+}
+
+/**
+ * Typed per-event callbacks for tenant applications.
+ *
+ * Unlike `AnalyticsCallback` (which receives the full analytics event for every
+ * event type), each delegate method receives only the arguments relevant to that
+ * event — clean signatures for logging, custom UI, and business logic.
+ *
+ * All methods are optional; implement only the ones you need.
+ *
+ * Conventions:
+ * - Arguments named `*Time` / `*At` are playback positions in seconds.
+ * - `watchDuration` and `seekDuration` are wall-clock seconds.
+ * - `from*` arguments are `undefined` when there was no previous value
+ *   (e.g. the first quality selection after load).
+ */
+export declare interface PlayerDelegate {
+    /** Playback started for the first time (or restarted after finishing). */
+    playerDidStartPlaying?(startTime: number, autoplay: boolean): void;
+    /** Playback resumed after a pause. */
+    playerDidResumePlaying?(resumedAt: number): void;
+    /** Playback paused by the user (not fired for the implicit pause at end of stream). */
+    playerDidPause?(pausedAt: number): void;
+    /** Playback reached the end of the stream. */
+    playerDidFinishPlaying?(finishedAt: number, watchDuration: number): void;
+    /** The player was torn down (unmount / tab close) before playback finished. Fired at most once. */
+    playerDidDismiss?(dismissedAt: number, watchDuration: number): void;
+    /** A seek started (scrubber, ±10s skip). Fired once per seek gesture. */
+    playerDidStartSeeking?(fromTime: number): void;
+    /** The seek landed. `fromTime` is where the gesture began, `seekDuration` is wall-clock seconds it took. */
+    playerDidFinishSeeking?(fromTime: number, toTime: number, seekDuration: number): void;
+    /** Playback position update — fires on every native `timeupdate` (roughly 4×/second). */
+    playerDidUpdateCurrentTime?(currentTime: number, duration: number): void;
+    playerDidStartBuffering?(startedAt: number): void;
+    playerDidFinishBuffering?(endedAt: number): void;
+    /** Rendition changed. `isAutoSwitch` is true when ABR picked the level, false for a manual selection. */
+    playerDidChangeQuality?(fromQuality: string | undefined, toQuality: string, isAutoSwitch: boolean): void;
+    /** Subtitle track changed (languages, e.g. 'en' → 'fr'). */
+    playerDidChangeSubtitle?(fromSubtitle: string | undefined, toSubtitle: string): void;
+    /** Subtitles were turned off. `disabledSubtitle` is the language that was active. */
+    playerDidDisableSubtitle?(disabledSubtitle: string | undefined): void;
+    /** Audio track changed (track labels). */
+    playerDidChangeAudioTrack?(fromAudioTrack: string | undefined, toAudioTrack: string): void;
+    playerDidChangePlaybackSpeed?(fromSpeed: number, toSpeed: number): void;
+    /** `orientation` is the current `screen.orientation.type` (e.g. 'landscape-primary') when available. */
+    playerDidEnterFullscreen?(orientation?: string): void;
+    playerDidExitFullscreen?(orientation?: string): void;
+    /** A key moment was selected. `fromTime`/`toTime` are the chapter's start/end. */
+    playerDidSelectKeyMoment?(chapterId: string | undefined, chapterTitle: string, fromTime: number, toTime: number): void;
+    playerDidEnterPictureInPicture?(enteredAt?: number): void;
+    playerDidExitPictureInPicture?(exitedAt?: number): void;
+    /** A media/playback error. `isRecoverable` is true when the player will attempt recovery itself. */
+    playerDidEncounterPlaybackError?(errorCode: string, message: string, isRecoverable: boolean): void;
+    /** A network/CDN error. `statusCode` is the HTTP status when known, 0 otherwise. */
+    playerDidEncounterNetworkError?(statusCode: number, message: string, isRecoverable: boolean): void;
+}
+
+/**
+ * In-session telemetry payload for POST /api/player/sdk/events.
+ * `eventType`, `sessionId` and `currentTime` are always required; `videoId`,
+ * `videoTitle` and any event-specific extras (e.g. `from`/`to`, `speed`,
+ * `bufferingCount`) are sent at the top level — never wrapped in a client
+ * `properties` object (the server nests them).
+ */
+export declare interface PlayerEventPayload {
+    eventType: string;
+    sessionId: string;
+    currentTime: number;
+    videoId?: string;
+    videoTitle?: string;
+    [key: string]: unknown;
+}
+
+export declare interface PlayerInstance {
+    /** Re-render the player with updated props (src change, theme, etc.) */
+    update(props: Partial<PlayerProps>): void;
+    /** Unmounts the player and releases all resources */
+    destroy(): void;
+}
+
+export declare interface PlayerProps extends BossVideoPlayerProps {
+}
+
+export declare interface PlayerSDKOptions {
+    container: HTMLElement;
+    src: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    chapters?: Chapter[];
+    keyMoments?: KeyMoment[];
+    subtitles?: SubtitleTrack[];
+    thumbnails?: ThumbnailConfig;
+    drm?: DRMConfig;
+    analyticsCallback?: AnalyticsCallback;
+    videoId?: string;
+    analyticsSessionSeed?: AnalyticsSessionSnapshot;
+    watchProgressInterval?: number;
+    themeColor?: string;
+    watermark?: string;
+    /**
+     * Optional URL transformer applied to every HLS segment/manifest request.
+     * Use this to route requests through a CORS proxy without hardcoding domains.
+     * Example: (url) => url.replace('https://cdn.example.com', '/my-proxy')
+     */
+    urlTransformer?: (url: string) => string;
+}
+
+declare interface RemoteCastState {
+    currentTime: number;
+    duration: number;
+    isPaused: boolean;
+    volumeLevel: number;
+    isMuted: boolean;
+}
+
+export declare type SdkInitData = {
+    tenantId: string;
+    features: SdkInitFeatures;
+    planTier: string;
+    /** How often to call /session/heartbeat. Falls back to 30s when absent. */
+    heartbeatIntervalSeconds?: number;
+};
+
+export declare type SdkInitFeatures = {
+    subtitles: boolean;
+    ads: boolean;
+    chapterMarkers: boolean;
+    [key: string]: boolean;
+};
+
+/** Optional context accepted by POST /init. `referrer` is intentionally not sent. */
+export declare interface SdkInitOptions {
+    videoUrl?: string;
+}
+
+export declare type SdkInitResponse = {
+    result: {
+        data: SdkInitData;
+        metadata: Record<string, unknown>;
+    };
+};
+
+export declare type SdkPackage = {
+    package: string;
+    is_active: boolean;
+    features: FeatureFlags;
+    limits: {
+        streaming_minutes: number;
+    };
+};
+
+/**
+ * Records a single in-session analytics event. One event per request.
+ * The endpoint returns 204 No Content on success, so there is no body to parse.
+ */
+export declare function sendEvent(playerKey: string, payload: PlayerEventPayload, apiBase?: string): Promise<void>;
+
+export declare function sendHeartbeat(playerKey: string, sessionId: string, currentTime: number, duration: number, apiBase?: string): Promise<void>;
+
+export declare interface SourceItem {
+    label: string;
+    url: string;
+}
+
+export declare function startSession(playerKey: string, options: StartSessionOptions, apiBase?: string): Promise<void>;
+
+/**
+ * Body for POST /session/start. Only `sessionId` is required for HTTP acceptance,
+ * but `videoId`, `videoTitle` and `contentDurationSec` drive the video-level CMS
+ * analytics (Top Videos, retention, completion) — send them whenever they're known.
+ * `platform` and `referrer` are intentionally not sent by this SDK.
+ */
+export declare interface StartSessionOptions {
+    /** Client-generated UUID identifying this play. */
+    sessionId: string;
+    /** Stable content ID — the grouping key for video-level analytics. */
+    videoId?: string;
+    /** Display title for CMS dashboards. */
+    videoTitle?: string;
+    /** Playback URL. */
+    videoUrl?: string;
+    /** Full content length in seconds, when known. */
+    contentDurationSec?: number;
+}
+
+declare class SubtitlesModule {
+    private tracks;
+    private activeTrackId;
+    private currentCues;
+    private activeText;
+    private onSubtitleChangeCallback?;
+    private onTrackSwitchCallback?;
+    constructor(tracks?: SubtitleTrack[]);
+    getTracks(): SubtitleTrack[];
+    getActiveTrackId(): string;
+    setHlsTracks(hlsTracks: SubtitleTrack[]): void;
+    addTrack(track: SubtitleTrack): void;
+    onTrackSwitch(callback: (track: SubtitleTrack | null) => void): void;
+    setCustomSubtitleText(text: string): void;
+    /**
+     * Switches the active track. Fetches external tracks if they need loading.
+     */
+    setActiveTrack(trackId: string): Promise<void>;
+    /**
+     * Scans the subtitle cues for the current playback position.
+     */
+    updateTime(currentTime: number): void;
+    /**
+     * Triggers the text update callback if a change in caption is detected.
+     */
+    private updateActiveText;
+    onSubtitleChange(callback: (text: string) => void): void;
+    /**
+     * Robust parser supporting WebVTT and SRT formats.
+     */
+    private parseVttOrSrt;
+}
+
+export declare interface SubtitleStyle {
+    size?: 'small' | 'medium' | 'large';
+    background?: 'none' | 'dim' | 'solid';
+    color?: string;
+}
+
+declare interface SubtitleStyle_2 {
+    size?: 'small' | 'medium' | 'large';
+    background?: 'none' | 'dim' | 'solid';
+    color?: string;
+}
+
+export declare interface SubtitleTrack {
+    id: string;
+    label: string;
+    lang: string;
+    src?: string;
+    isDefault?: boolean;
+    cues?: Array<{
+        startTime: number;
+        endTime: number;
+        text: string;
+    }>;
+    isHls?: boolean;
+    hlsTrackId?: number;
+    isNative?: boolean;
+    nativeTrackIndex?: number;
+}
+
+export declare interface ThumbnailConfig {
+    spriteUrl: string;
+    tileWidth: number;
+    tileHeight: number;
+    columns: number;
+    rows: number;
+    interval: number;
+    totalCount: number;
+}
+
+declare class ThumbnailsModule {
+    private config?;
+    constructor(config?: ThumbnailConfig);
+    /**
+     * Calculates the position offset inside the sprite sheet for a given seek hover time.
+     */
+    getThumbnail(time: number): {
+        url: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    hasThumbnails(): boolean;
+}
+
+export declare class VideoPlayerSDK {
+    private options;
+    private videoElement;
+    private hlsInstance;
+    private dashInstance;
+    private activeQuality;
+    private qualityLevels;
+    analytics: AnalyticsModule;
+    keyMoments: KeyMomentsModule;
+    chapters: ChaptersModule;
+    subtitles: SubtitlesModule;
+    drm: DRMModule;
+    casting: CastingModule;
+    thumbnails: ThumbnailsModule;
+    private hlsSubtitleCues;
+    private hlsActiveSubtitleKey;
+    private audioTrackList;
+    private adBreaks;
+    private isAdBreak;
+    private adBreaksFromAvails;
+    private contentPlaybackRate;
+    private networkErrorRetries;
+    private mediaErrorRecovered;
+    private static readonly MAX_NETWORK_RETRIES;
+    private static readonly TERMINAL_HTTP_STATUSES;
+    private static readonly STALL_TIMEOUT_MS;
+    private stallTimer;
+    private isBuffering;
+    private progressTick;
+    private hasFailed;
+    private lastPlaybackPos;
+    private pendingSeekAttribution;
+    private eventListeners;
+    constructor(options: PlayerSDKOptions);
+    /**
+     * Builds the video DOM hierarchy, binds events, validates domain restrictions, and mounts DRM watermarks.
+     */
+    private initializePlayer;
+    /**
+     * Binds direct event listeners to the native HTML5 Video tag, routing them to our sub-packages.
+     */
+    private bindMediaEvents;
+    private rewriteToProxy;
+    /**
+     * Initializes HLS adaptive streaming through Hls.js or falls back to native browser playback.
+     */
+    private loadSource;
+    /**
+     * Sets up global lock-screen metadata and media control keys (Media Session API).
+     */
+    private setupBackgroundControls;
+    play(): void;
+    pause(): void;
+    seek(seconds: number): void;
+    /**
+     * Attributes the NEXT seek to a specific user gesture so telemetry reports it as
+     * `fast_forward` / `fast_backward` / `key_moments` instead of a generic `seek`.
+     * Call immediately before triggering the seek. The attribution expires after a
+     * short window so it can never leak onto an unrelated later seek.
+     */
+    attributeNextSeek(eventType: 'fast_forward' | 'fast_backward' | 'key_moments', extras?: Partial<AnalyticsEvent>): void;
+    setVolume(volume: number): void;
+    setMute(muted: boolean): void;
+    setPlaybackRate(rate: number): void;
+    /**
+     * Sets manual video quality rendition or switches back to auto bitrate scaling.
+     */
+    setQuality(qualityId: number): void;
+    /**
+     * Activates native Picture-in-Picture floating viewport.
+     */
+    togglePictureInPicture(): Promise<boolean>;
+    /**
+     * Requests element-level fullscreen.
+     */
+    toggleFullscreen(): void;
+    getVideoElement(): HTMLVideoElement;
+    getCurrentTime(): number;
+    getDuration(): number;
+    getVolume(): number;
+    isMuted(): boolean;
+    getPlaybackRate(): number;
+    getActiveQuality(): VideoQuality;
+    getQualityLevels(): VideoQuality[];
+    getBufferLength(): number;
+    getBufferedRanges(): Array<{
+        start: number;
+        end: number;
+    }>;
+    /**
+     * Returns true if the browser can decode at least one of the manifest's renditions.
+     *
+     * Deliberately conservative to avoid ever blocking a valid stream:
+     *  - A codec that isn't declared is treated as playable (we never assume unsupported).
+     *  - Any failure to verify (no MediaSource, isTypeSupported throws) returns true.
+     *  - The stream is "playable" if even one rendition's declared codecs are all supported,
+     *    matching how HLS.js itself selects a level.
+     * Returns false only when the browser explicitly reports every declared codec as
+     * undecodable (e.g. Dolby EC-3/AC-3 in Chrome).
+     */
+    private hasPlayableLevel;
+    private getAnalyticsPayload;
+    on(event: string, callback: (...args: any[]) => void): void;
+    off(event: string, callback: (...args: any[]) => void): void;
+    private emit;
+    private extractSubtitlesFromManifest;
+    private extractKeyMomentsFromManifest;
+    private extractAdBreaksFromManifest;
+    private buildManifestUrl;
+    private findFirstVariantUri;
+    private resolveUrl;
+    private static readonly AD_HOST_PATTERNS;
+    private static readonly AD_STITCHER_PATH_PATTERNS;
+    private static readonly AD_PATH_HINT_PATTERNS;
+    private parseSegmentUrl;
+    private isKnownAdSegment;
+    private hasAdPathHint;
+    private classifyAdGroups;
+    private mergeAdjacentRanges;
+    private parseAdBreaksFromFragments;
+    private parseAdBreaksFromPlaylist;
+    private sameAdBreaks;
+    private isTimeInAdBreak;
+    /**
+     * Syncs isAdBreak/playbackRate/ad-mode UI state against `time` and emits
+     * adbreakchange on transitions. Called from timeupdate, but also called
+     * eagerly as soon as ad breaks or metadata become known — timeupdate alone
+     * doesn't fire until playback actually starts, which left a preroll ad's
+     * first frame briefly showing content controls (rewind/forward, etc.)
+     * while autoplay was blocked or the source was still buffering.
+     */
+    private refreshAdBreakState;
+    /**
+     * Converts raw (stitched) video time to content-only time by subtracting the
+     * ad time elapsed before `time`. During an ad break the result is frozen at
+     * the content timestamp where the break started. Identity when no ad breaks
+     * are known. Mirrors the seekbar mapping in the UI layer.
+     */
+    private videoTimeToContentTime;
+    getAdBreaks(): Array<{
+        startTime: number;
+        endTime: number;
+    }>;
+    setAdBreaks(breaks: Array<{
+        startTime: number;
+        endTime: number;
+    }>): void;
+    isInAdBreak(): boolean;
+    getAudioTracks(): Array<{
+        id: number;
+        label: string;
+        lang: string;
+    }>;
+    setAudioTrack(id: number): void;
+    /**
+     * Arms a one-shot timer while buffering. If the timer fires and no data has
+     * arrived since it was armed (progressTick unchanged) and we're still
+     * buffering, the stream is considered dead. If data did arrive but we're still
+     * buffering (slow connection), it re-arms for another window rather than
+     * failing — so slow internet never trips it.
+     */
+    private armStallWatchdog;
+    private clearStallWatchdog;
+    /**
+     * Terminal error path: emit 'error' (which drives the error screen) and tear
+     * down the player. Guarded so it runs at most once, no matter how many error
+     * events fire during teardown.
+     */
+    private fail;
+    destroy(): void;
+}
+
+export declare interface VideoQuality {
+    id: number;
+    height: number;
+    width: number;
+    bitrate: number;
+    label: string;
+}
+
+export declare const WebVideoPlayer: default_2.FC<WebVideoPlayerProps>;
+
+declare interface WebVideoPlayerProps {
+    src: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    chapters?: Chapter[];
+    keyMoments?: KeyMoment[];
+    subtitles?: SubtitleTrack[];
+    watermark?: string;
+    themeColor?: string;
+    drmConfig?: any;
+    firebaseConfig?: FirebaseConfig;
+    onAnalyticsEvent?: (event: AnalyticsEvent) => void;
+    onAdBreakChange?: (active: boolean) => void;
+    onKeyMomentsLoaded?: (keyMoments: KeyMoment[]) => void;
+    enableControls?: boolean;
+    enableChromecast?: boolean;
+    enableKeyMoments?: boolean;
+    enableSubtitles?: boolean;
+    enableQuality?: boolean;
+    enablePlaybackSpeed?: boolean;
+    enablePiP?: boolean;
+    enableFullscreen?: boolean;
+    autoFullscreen?: boolean;
+    watchProgressInterval?: number;
+    subtitleStyle?: SubtitleStyle_2;
+    /**
+     * Pre-resolved entitlement package from BossVideoPlayer.
+     * When provided, features are determined exclusively by this package (API mode).
+     * When absent, features fall back to explicit props with true defaults (standalone mode).
+     */
+    resolvedEntitlement?: {
+        package: string;
+        is_active: boolean;
+        features: Record<string, boolean>;
+        limits: {
+            streaming_minutes: number;
+        };
+    } | null;
+    licenseKey?: string | null;
+    title?: string;
+    chaptersDisplayMode?: 'strip' | 'panel';
+    volumeControlType?: 'slider' | 'button';
+    urlTransformer?: (url: string) => string;
+    pauseAdOnTabSwitch?: boolean;
+    enableSkipAd?: boolean;
+    skipAdAfterSeconds?: number;
+    overlayAdUrl?: string;
+    adTrackingUrl?: string;
+    videoId?: string;
+    sources?: SourceItem[];
+    activeSourceIndex?: number;
+    onSourceChange?: (index: number) => void;
+    /** Seek to this position (in seconds) as soon as the video is ready. Use for resume-playback. */
+    initialTime?: number;
+    /** Called on every timeupdate with the current playback position in seconds. Use to persist watch progress. */
+    onTimeUpdate?: (currentTime: number) => void;
+}
+
+export { }