@codenkay/video-nsgplayer-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,547 @@
+/** Player lifecycle states. */
+type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
+type HlsSupportMode = "hls.js" | "native" | "unsupported";
+type QualitySelection = "auto" | number;
+type PlaybackRate = 0.5 | 0.75 | 1 | 1.25 | 1.5 | 2;
+type HlsQualityLevel = {
+    index: number;
+    height: number;
+    width: number;
+    bitrate: number;
+    label: string;
+    uri?: string;
+};
+type PlayIconPreset = "triangle" | "circle" | "roundedSquare";
+type PlayerZoomLevel = 1 | 1.25 | 1.5 | 2;
+type PlayerSkipSeconds = 5 | 10 | 15 | 30;
+type AuthToken = {
+    accessToken: string;
+    expiresAt: number;
+};
+type AuthTokenProviderContext = {
+    reason: "initial" | "expired" | "expiring" | "unauthorized" | "manual";
+    videoId?: string;
+};
+type PlaybackSource = {
+    url: string;
+    expiresAt: number;
+    authParams?: Record<string, string>;
+    token?: string;
+    /** When true, UI may show the LIVE badge and seek-to-live affordance. */
+    live?: boolean;
+};
+type PlaybackSourceContext = {
+    videoId: string;
+    reason: "initial" | "expired" | "expiring" | "auth_error" | "manual";
+};
+type AuthConfig = {
+    getToken: (context: AuthTokenProviderContext) => Promise<AuthToken>;
+    refreshBeforeExpiryMs?: number;
+};
+type PlaybackCredentialConfig = {
+    getSource: (context: PlaybackSourceContext) => Promise<PlaybackSource>;
+    refreshSource?: (context: PlaybackSourceContext) => Promise<PlaybackSource>;
+    refreshBeforeExpiryMs?: number;
+    renewMaxRetries?: number;
+    renewBackoffMs?: number;
+    authRecoveryCoalesceMs?: number;
+};
+type PlayerBehaviorConfig = {
+    autoplay?: boolean;
+    startMuted?: boolean;
+    volume?: number;
+    startPosition?: number;
+    skipSeconds?: PlayerSkipSeconds;
+    speedOptionCount?: number;
+    zoomEnabled?: boolean;
+    defaultZoom?: PlayerZoomLevel;
+    playbackRates?: readonly PlaybackRate[];
+};
+type ControlsConfig = {
+    enabled?: boolean;
+    showQuality?: boolean;
+    showSpeed?: boolean;
+    showCaptions?: boolean;
+    showAudio?: boolean;
+    showVolume?: boolean;
+    showFullscreen?: boolean;
+    showZoom?: boolean;
+    showSkip?: boolean;
+    /** Show LIVE badge after time text for live streams. */
+    showLive?: boolean;
+    seekCueDurationMs?: number;
+    keyboardShortcuts?: boolean;
+};
+type ThemeConfig = {
+    playIconPreset?: PlayIconPreset;
+    playButtonBackground?: string;
+    playButtonIconColor?: string;
+    seekTrackColor?: string;
+    seekProgressColor?: string;
+    seekBufferedColor?: string;
+    timeColor?: string;
+    controlIconColor?: string;
+    focusRingColor?: string;
+    spinnerColor?: string;
+    volumeIconColor?: string;
+    volumeTrackColor?: string;
+    volumeProgressColor?: string;
+    qualityOptionTextColor?: string;
+    qualityOptionBackground?: string;
+    qualityOptionActiveBackground?: string;
+    qualityOptionActiveTextColor?: string;
+    speedOptionTextColor?: string;
+    speedOptionBackground?: string;
+    speedOptionActiveBackground?: string;
+    speedOptionActiveTextColor?: string;
+    zoomIconColor?: string;
+    skipIconColor?: string;
+    skipCueBackground?: string;
+    skipCueTextColor?: string;
+    /** Filled LIVE indicator color (hollow ring when behind live). */
+    liveDotColor?: string;
+};
+type WatermarkConfig = {
+    enabled?: boolean;
+    text?: string;
+    durationMs?: number;
+    intervalMaxMs?: number;
+};
+type StreamingConfig = {
+    engine?: "hls";
+    hls?: {
+        enableWorker?: boolean;
+        lowLatencyMode?: boolean;
+        backBufferLength?: number;
+        fatalRecoveryLimit?: number;
+    };
+    keyProxyUrlBuilder?: (ctx: {
+        videoId: string;
+        keyUrl: string;
+        token?: string;
+        expires?: string;
+    }) => string;
+};
+type LoggingConfig = {
+    enabled?: boolean;
+    level?: "silent" | "error" | "warn" | "info" | "debug" | "trace";
+};
+type DebugConfig = {
+    enabled?: boolean;
+    network?: boolean;
+    events?: boolean;
+    state?: boolean;
+};
+type AnalyticsConfig = {
+    onEvent?: (event: {
+        type: string;
+        payload?: Record<string, unknown>;
+    }) => void;
+};
+type AccessibilityConfig = {
+    reducedMotion?: boolean;
+};
+type CreateVideoPlayerOptions = {
+    videoId?: string;
+    mount?: HTMLVideoElement;
+    auth?: AuthConfig;
+    playback?: PlaybackCredentialConfig;
+    /** Direct HLS URL without credential callbacks (no renewal). */
+    sourceUrl?: string;
+    player?: PlayerBehaviorConfig;
+    controls?: ControlsConfig;
+    theme?: ThemeConfig;
+    watermark?: WatermarkConfig;
+    streaming?: StreamingConfig;
+    logging?: LoggingConfig;
+    debug?: DebugConfig;
+    analytics?: AnalyticsConfig;
+    accessibility?: AccessibilityConfig;
+};
+type PlayerConfig = Required<{
+    player: Required<PlayerBehaviorConfig>;
+    controls: Required<ControlsConfig>;
+    theme: Required<ThemeConfig>;
+    watermark: Required<WatermarkConfig>;
+    streaming: {
+        engine: "hls";
+        hls: Required<NonNullable<StreamingConfig["hls"]>>;
+    };
+    logging: Required<LoggingConfig>;
+    debug: Required<DebugConfig>;
+    accessibility: Required<AccessibilityConfig>;
+}>;
+type PlayerDiagnostics = {
+    playerVersion: string;
+    currentState: PlayerState;
+    hlsSupport: HlsSupportMode;
+    videoId: string | null;
+    currentTime: number;
+    duration: number;
+    bufferedEnd: number;
+    currentQuality: string | null;
+    playbackSessionId: string | null;
+    authExpiryStatus: "unknown" | "valid" | "expiring_soon" | "expired";
+    sourceExpiryStatus: "unknown" | "valid" | "expiring_soon" | "expired";
+    lastError: string | null;
+};
+type BufferedRange = {
+    start: number;
+    end: number;
+};
+type PlayerEventMap = {
+    ready: void;
+    play: void;
+    pause: void;
+    playing: void;
+    timeupdate: {
+        currentTime: number;
+        duration: number;
+    };
+    buffering: void;
+    progress: {
+        bufferedEnd: number;
+    };
+    qualitychange: {
+        selection: QualitySelection;
+        label?: string;
+    };
+    volumechange: {
+        volume: number;
+        muted: boolean;
+    };
+    fullscreenchange: {
+        isFullscreen: boolean;
+    };
+    authrefresh: {
+        expiresAt: number;
+    };
+    tokenrefresh: {
+        expiresAt: number;
+    };
+    sourcechange: {
+        expiresAt: number;
+    };
+    autherror: {
+        message: string;
+        retryable: boolean;
+    };
+    ended: void;
+    error: {
+        code: string;
+        message: string;
+        fatal: boolean;
+    };
+    destroy: void;
+    statechange: {
+        state: PlayerState;
+    };
+};
+
+declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
+declare const PACKAGE_VERSION = "0.1.0";
+declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
+declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
+declare const DEFAULT_THEME: Required<ThemeConfig>;
+declare const DEFAULT_WATERMARK: Required<WatermarkConfig>;
+declare const DEFAULT_PLAYER_CONFIG: PlayerConfig;
+declare function assertNoSecretsInConfig(raw: unknown): void;
+declare function mergePlayerConfig(partial?: Partial<{
+    player: Partial<PlayerBehaviorConfig>;
+    controls: Partial<ControlsConfig>;
+    theme: Partial<ThemeConfig>;
+    watermark: Partial<WatermarkConfig>;
+    streaming: {
+        engine?: "hls";
+        hls?: Partial<PlayerConfig["streaming"]["hls"]>;
+        keyProxyUrlBuilder?: unknown;
+    };
+    logging: Partial<PlayerConfig["logging"]>;
+    debug: Partial<PlayerConfig["debug"]>;
+    accessibility: Partial<PlayerConfig["accessibility"]>;
+}>): PlayerConfig;
+/** Maps theme colors to CSS custom properties for UI adapters. */
+declare function themeToCssVars(theme: Required<ThemeConfig>): Record<string, string>;
+
+type Handler<T> = T extends void ? () => void : (payload: T) => void;
+declare class EventEmitter {
+    private listeners;
+    on<K extends keyof PlayerEventMap>(event: K, handler: Handler<PlayerEventMap[K]>): () => void;
+    off<K extends keyof PlayerEventMap>(event: K, handler: Handler<PlayerEventMap[K]>): void;
+    emit<K extends keyof PlayerEventMap>(event: K, ...args: PlayerEventMap[K] extends void ? [] : [PlayerEventMap[K]]): void;
+    removeAll(): void;
+}
+
+/**
+ * Live-edge helpers for HLS DVR / live streams.
+ * Uses HTMLMediaElement.seekable when available; falls back to duration.
+ */
+declare const DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS = 3;
+type SeekableLike = {
+    length: number;
+    start: (index: number) => number;
+    end: (index: number) => number;
+};
+type LiveMediaSnapshot = {
+    currentTime: number;
+    duration: number;
+    seekable: SeekableLike;
+};
+/**
+ * Returns the latest seekable end (live edge), or null when unknown.
+ */
+declare function getLiveEdgeTime(media: Pick<LiveMediaSnapshot, "duration" | "seekable">): number | null;
+/**
+ * True when playback is within `toleranceSeconds` of the live edge.
+ */
+declare function isAtLiveEdge(media: LiveMediaSnapshot, toleranceSeconds?: number): boolean;
+type SeekToLiveResult = {
+    moved: true;
+    edge: number;
+} | {
+    moved: false;
+    reason: "already_at_live" | "edge_unavailable";
+    edge: number | null;
+};
+type SeekableMediaElement = {
+    currentTime: number;
+    duration: number;
+    seekable: SeekableLike;
+};
+/**
+ * Seeks to the live edge. Returns whether the playhead moved.
+ */
+declare function seekToLiveEdge(media: SeekableMediaElement, options?: {
+    toleranceSeconds?: number;
+    /** Leave a tiny buffer behind the absolute end for decoder stability. */
+    edgeOffsetSeconds?: number;
+}): SeekToLiveResult;
+
+/**
+ * Mutable store of the latest playback authorization query parameters.
+ * Updated on renewal without recreating the HLS player.
+ */
+declare class AuthParamsStore {
+    private params;
+    constructor(initial?: URLSearchParams | Record<string, string>);
+    getSnapshot(): URLSearchParams;
+    toRecord(): Record<string, string>;
+    update(next: URLSearchParams | Record<string, string>): void;
+    applyToUrl(rawUrl: string, baseOrigin?: string): string;
+}
+
+declare class Logger {
+    private config;
+    constructor(config: Required<LoggingConfig>);
+    update(config: Partial<LoggingConfig>): void;
+    private shouldLog;
+    private write;
+    error(message: string, details?: Record<string, unknown>): void;
+    warn(message: string, details?: Record<string, unknown>): void;
+    info(message: string, details?: Record<string, unknown>): void;
+    debug(message: string, details?: Record<string, unknown>): void;
+}
+
+type HlsEngineCallbacks = {
+    onStateChange?: (state: PlayerState) => void;
+    onSupportMode?: (mode: HlsSupportMode) => void;
+    onFatalError?: (message: string) => void;
+    onAuthRecoveryNeeded?: (reason: string) => void;
+    onQualitiesChange?: (levels: HlsQualityLevel[]) => void;
+    onQualitySelectionChange?: (selection: QualitySelection) => void;
+    onEnded?: () => void;
+};
+type HlsEngineOptions = {
+    videoEl: HTMLVideoElement;
+    playbackUrl: string;
+    authParams: AuthParamsStore;
+    autoplay: boolean;
+    startMuted: boolean;
+    startPosition?: number;
+    volume?: number;
+    hlsConfig: {
+        enableWorker: boolean;
+        lowLatencyMode: boolean;
+        backBufferLength: number;
+        fatalRecoveryLimit: number;
+    };
+    logger: Logger;
+    callbacks: HlsEngineCallbacks;
+};
+/**
+ * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
+ */
+declare class HlsEngine {
+    private readonly options;
+    private hls;
+    private destroyed;
+    private supportMode;
+    private networkRecoveryCount;
+    private mediaRecoveryCount;
+    private qualities;
+    private qualitySelection;
+    constructor(options: HlsEngineOptions);
+    start(): Promise<void>;
+    private startWithHlsJs;
+    private bindMediaEvents;
+    updateAuthParams(): void;
+    resumeAfterAuthRenew(): void;
+    setQuality(selection: QualitySelection): void;
+    getQuality(): QualitySelection;
+    getQualities(): HlsQualityLevel[];
+    getSupportMode(): HlsSupportMode;
+    destroy(): void;
+}
+
+type VideoPlayer = {
+    play: () => Promise<void>;
+    pause: () => void;
+    seek: (time: number) => void;
+    /** Jump to the latest live edge. No-op when already at live. */
+    goToLive: () => SeekToLiveResult;
+    isLive: () => boolean;
+    isAtLiveEdge: () => boolean;
+    getCurrentTime: () => number;
+    getDuration: () => number;
+    setVolume: (volume: number) => void;
+    getVolume: () => number;
+    mute: () => void;
+    unmute: () => void;
+    isMuted: () => boolean;
+    setPlaybackRate: (rate: number) => void;
+    getPlaybackRate: () => number;
+    getState: () => PlayerState;
+    getBufferedRanges: () => BufferedRange[];
+    getQuality: () => QualitySelection;
+    setQuality: (selection: QualitySelection | string) => void;
+    getAvailableQualities: () => ReturnType<HlsEngine["getQualities"]>;
+    enterFullscreen: () => Promise<void>;
+    exitFullscreen: () => Promise<void>;
+    isFullscreen: () => boolean;
+    reload: () => Promise<void>;
+    destroy: () => void;
+    getDiagnostics: () => PlayerDiagnostics;
+    getConfig: () => PlayerConfig;
+    updateConfig: (partial: Parameters<typeof mergePlayerConfig>[0]) => void;
+    on: EventEmitter["on"];
+    off: EventEmitter["off"];
+};
+/**
+ * Creates a framework-agnostic video player.
+ * Never pass clientSecret — use auth.getToken / playback.getSource callbacks.
+ */
+declare function createVideoPlayer(options: CreateVideoPlayerOptions): VideoPlayer;
+
+declare enum PlayerErrorCode {
+    INVALID_CONFIGURATION = "INVALID_CONFIGURATION",
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED",
+    AUTH_TOKEN_REFRESH_FAILED = "AUTH_TOKEN_REFRESH_FAILED",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    TOKEN_REFRESH_FAILED = "TOKEN_REFRESH_FAILED",
+    SOURCE_RESOLUTION_FAILED = "SOURCE_RESOLUTION_FAILED",
+    MANIFEST_LOAD_FAILED = "MANIFEST_LOAD_FAILED",
+    SEGMENT_LOAD_FAILED = "SEGMENT_LOAD_FAILED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    PLAYBACK_ERROR = "PLAYBACK_ERROR",
+    UNSUPPORTED_BROWSER = "UNSUPPORTED_BROWSER",
+    AUTOPLAY_BLOCKED = "AUTOPLAY_BLOCKED",
+    UNKNOWN = "UNKNOWN"
+}
+type PlayerError = {
+    code: PlayerErrorCode;
+    message: string;
+    category: "config" | "auth" | "network" | "playback" | "unknown";
+    fatal: boolean;
+    retryable: boolean;
+    timestamp: number;
+    cause?: unknown;
+};
+declare function createPlayerError(code: PlayerErrorCode, message: string, options?: Partial<Omit<PlayerError, "code" | "message" | "timestamp">>): PlayerError;
+declare function redactSensitive(input: string): string;
+
+/**
+ * Manages provider auth-token lifecycle (independent from signed playback URL).
+ * Single-flight refresh; never stores clientSecret.
+ * Unauthorized recoveries are bounded to prevent infinite 401 → refresh loops.
+ */
+declare class AuthManager {
+    private readonly auth;
+    private readonly refreshBeforeExpiryMs;
+    private readonly logger;
+    private readonly onRefreshed?;
+    private readonly onError?;
+    private token;
+    private inFlight;
+    private timer;
+    private destroyed;
+    /** Consecutive unauthorized refresh attempts (reset on success). */
+    private unauthorizedAttempts;
+    private readonly maxUnauthorizedRetries;
+    constructor(auth: AuthConfig | undefined, refreshBeforeExpiryMs: number, logger: Logger, onRefreshed?: ((token: AuthToken) => void) | undefined, onError?: ((message: string, retryable: boolean) => void) | undefined, maxUnauthorizedRetries?: number);
+    getAccessToken(): string | null;
+    getExpiresAt(): number | null;
+    ensureToken(context: AuthTokenProviderContext): Promise<AuthToken | null>;
+    refresh(context: AuthTokenProviderContext): Promise<AuthToken>;
+    private scheduleProactiveRefresh;
+    destroy(): void;
+}
+
+/**
+ * Resolves and refreshes signed playback sources via consumer callbacks.
+ */
+declare class PlaybackSourceManager {
+    private readonly playback;
+    private readonly logger;
+    private source;
+    private inFlight;
+    readonly authParams: AuthParamsStore;
+    constructor(playback: PlaybackCredentialConfig | undefined, logger: Logger);
+    getSource(): PlaybackSource | null;
+    getExpiresAt(): number | null;
+    load(context: PlaybackSourceContext): Promise<PlaybackSource>;
+    refresh(context: PlaybackSourceContext): Promise<PlaybackSource>;
+    applyDirectSource(source: PlaybackSource): void;
+    private run;
+    private applyAuthParams;
+    destroy(): void;
+}
+
+type RefreshReason = "proactive" | "frag_error" | "level_error" | "key_error" | "fatal_network" | "manual";
+type RefreshManagerOptions = {
+    videoId: string;
+    authManager: AuthManager;
+    sourceManager: PlaybackSourceManager;
+    refreshBeforeExpiryMs: number;
+    renewMaxRetries: number;
+    renewBackoffMs: number;
+    coalesceMs: number;
+    logger: Logger;
+    isDestroyed: () => boolean;
+    onRenewing?: () => void;
+    onRenewed?: (expiresAt: number) => void;
+    onFatal?: (message: string) => void;
+};
+/**
+ * Schedules signed-URL renewal (playback clock) with single-flight + coalesce.
+ * Ensures auth token is fresh before calling refreshSource.
+ */
+declare class RefreshManager {
+    private readonly options;
+    private timer;
+    private coalesceTimer;
+    private inFlight;
+    private consecutiveFailures;
+    private stopped;
+    private pendingReason;
+    constructor(options: RefreshManagerOptions);
+    start(initialExpiresAt: number): void;
+    requestRenew(reason?: RefreshReason): void;
+    stop(): void;
+    private schedule;
+    private renew;
+}
+
+declare function redactValue(key: string, value: unknown): unknown;
+declare function redactObject(obj: Record<string, unknown>): Record<string, unknown>;
+
+export { type AccessibilityConfig, type AnalyticsConfig, type AuthConfig, AuthManager, AuthParamsStore, type AuthToken, type AuthTokenProviderContext, type BufferedRange, type ControlsConfig, type CreateVideoPlayerOptions, DEFAULT_CONTROLS, DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS, DEFAULT_PLAYER_BEHAVIOR, DEFAULT_PLAYER_CONFIG, DEFAULT_THEME, DEFAULT_WATERMARK, type DebugConfig, EventEmitter, type HlsQualityLevel, type HlsSupportMode, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerZoomLevel, type QualitySelection, RefreshManager, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, mergePlayerConfig, redactObject, redactSensitive, redactValue, seekToLiveEdge, themeToCssVars };