boss-web-player-sdk 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,693 @@
+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' | '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;
+    sessionId?: string;
+    videoId?: string;
+    deviceType?: string;
+    networkType?: string;
+    watchPercentage?: number;
+    totalWatchTime?: number;
+    streamingTime?: number;
+    adWatchTime?: number;
+    bufferingCount?: number;
+    totalBufferingTime?: number;
+    seekFrom?: number;
+    pipState?: 'entered' | 'exited';
+}
+
+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);
+    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;
+}
+
+export declare function BossVideoPlayer({ playerKey, src, subtitles, licenseKey, themeColor, firebaseConfig, proxyDomains, apiBaseUrl, adTrackingUrl, overlayAdUrl, title, watermark, autoplay, muted, autoFullscreen, enableControls, enableSkipAd, skipAdAfterSeconds, chaptersDisplayMode, volumeControlType, subtitleStyle, drmConfig, onAnalyticsEvent, 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;
+    /** 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;
+    /** 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;
+    /**
+     * 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[];
+    };
+}
+
+export declare function endSession(playerKey: string, sessionId: string, 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): 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;
+}
+
+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;
+    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;
+};
+
+export declare type SdkInitFeatures = {
+    subtitles: boolean;
+    ads: boolean;
+    chapterMarkers: boolean;
+    [key: string]: boolean;
+};
+
+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;
+    };
+};
+
+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, sessionId: string, videoId: string, apiBase?: string): Promise<void>;
+
+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 contentPlaybackRate;
+    private networkErrorRetries;
+    private mediaErrorRecovered;
+    private static readonly MAX_NETWORK_RETRIES;
+    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;
+    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 parseAdBreaksFromFragments;
+    private parseAdBreaksFromPlaylist;
+    private isTimeInAdBreak;
+    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;
+    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;
+    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 { }