@codenkay/video-nsgplayer-core 0.1.3 → 1.0.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
 
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
@@ -117,12 +117,24 @@ type StreamingConfig = {
         backBufferLength?: number;
         fatalRecoveryLimit?: number;
     };
+    /**
+     * Same-origin BFF proxy for `enc.key` (preferred in production when the
+     * server IP is allowlisted by the CDN / Cloudflare).
+     */
     keyProxyUrlBuilder?: (ctx: {
         videoId: string;
         keyUrl: string;
         token?: string;
         expires?: string;
+        username?: string;
+        mobile?: string;
     }) => string;
+    /**
+     * Browser-direct AES key auth: returns the Video API access token so hls.js
+     * can send `Authorization: Bearer …` on `enc.key` requests.
+     * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
+     */
+    getKeyAccessToken?: () => string | null | undefined;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -169,6 +181,7 @@ type PlayerConfig = Required<{
         engine: "hls";
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+        getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -242,7 +255,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.3";
+declare const PACKAGE_VERSION = "0.1.8";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -274,6 +287,7 @@ type PlayerConfigPartial = Partial<{
         engine?: "hls";
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
+        getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -388,6 +402,7 @@ type HlsEngineOptions = {
     volume?: number;
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+    getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -400,10 +415,12 @@ type HlsEngineOptions = {
 /**
  * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
  *
- * Signed CDN playback requires auth query params on *every* HLS request
- * (master, media playlist, segments, keys). hls.js only receives the signed
- * master URL via loadSource; child URIs are relative and unsigned unless a
- * custom loader re-applies AuthParamsStore on each request.
+ * Signed CDN playback requires auth query params on every HLS request
+ * (playlists, segments, and AES `enc.key` on CDN hosts).
+ *
+ * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
+ * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
     private readonly options;
@@ -417,6 +434,8 @@ declare class HlsEngine {
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
+    private handleHlsError;
+    private applyStartPositionAndAutoplay;
     private bindMediaEvents;
     updateAuthParams(): void;
     resumeAfterAuthRenew(): void;
@@ -575,27 +594,52 @@ declare class RefreshManager {
     private renew;
 }
 
-type HlsLoader = new (config: object) => {
+type HlsLoaderInstance = {
+    stats: LoaderStats;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
+    abort?: () => void;
 };
+type HlsLoader = new (config: object) => HlsLoaderInstance;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+    getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
 };
+declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
+/**
+ * Always resolve a builtin hls.js loader (XhrLoader).
+ *
+ * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
+ * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
+ * stack (`InternalError: too much recursion`).
+ */
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- * Master playlists are signed on loadSource; child playlists / segments / keys
- * are relative and would otherwise be fetched unsigned → CDN 403.
+ *
+ * AES `enc.key` handling (enterprise priority order):
+ * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
+ * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
+ *    params — same auth model as segments on Appextech CDN hosts
+ * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that re-applies live AuthParamsStore credentials on every
- * manifest / level / fragment / key request.
+ * hls.js loader that:
+ * - Re-applies signed auth query params on every media request
+ * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
+ *
+ * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
+ * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
  */
 declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+/**
+ * Redacts sensitive fields. Cycle-safe and depth-capped.
+ * Only walks plain objects/arrays — never DOM / host graphs.
+ */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): 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, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+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, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+import Hls, { LoaderStats, LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
 
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
@@ -117,12 +117,24 @@ type StreamingConfig = {
         backBufferLength?: number;
         fatalRecoveryLimit?: number;
     };
+    /**
+     * Same-origin BFF proxy for `enc.key` (preferred in production when the
+     * server IP is allowlisted by the CDN / Cloudflare).
+     */
     keyProxyUrlBuilder?: (ctx: {
         videoId: string;
         keyUrl: string;
         token?: string;
         expires?: string;
+        username?: string;
+        mobile?: string;
     }) => string;
+    /**
+     * Browser-direct AES key auth: returns the Video API access token so hls.js
+     * can send `Authorization: Bearer …` on `enc.key` requests.
+     * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
+     */
+    getKeyAccessToken?: () => string | null | undefined;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -169,6 +181,7 @@ type PlayerConfig = Required<{
         engine: "hls";
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+        getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -242,7 +255,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.3";
+declare const PACKAGE_VERSION = "0.1.8";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -274,6 +287,7 @@ type PlayerConfigPartial = Partial<{
         engine?: "hls";
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
+        getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -388,6 +402,7 @@ type HlsEngineOptions = {
     volume?: number;
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+    getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -400,10 +415,12 @@ type HlsEngineOptions = {
 /**
  * Dual-path HLS engine: hls.js when supported, otherwise native Safari HLS.
  *
- * Signed CDN playback requires auth query params on *every* HLS request
- * (master, media playlist, segments, keys). hls.js only receives the signed
- * master URL via loadSource; child URIs are relative and unsigned unless a
- * custom loader re-applies AuthParamsStore on each request.
+ * Signed CDN playback requires auth query params on every HLS request
+ * (playlists, segments, and AES `enc.key` on CDN hosts).
+ *
+ * Optional `streaming.keyProxyUrlBuilder` (same-origin BFF) or
+ * `streaming.getKeyAccessToken` (browser Bearer) for Video API–origin keys
+ * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
     private readonly options;
@@ -417,6 +434,8 @@ declare class HlsEngine {
     constructor(options: HlsEngineOptions);
     start(): Promise<void>;
     private startWithHlsJs;
+    private handleHlsError;
+    private applyStartPositionAndAutoplay;
     private bindMediaEvents;
     updateAuthParams(): void;
     resumeAfterAuthRenew(): void;
@@ -575,27 +594,52 @@ declare class RefreshManager {
     private renew;
 }
 
-type HlsLoader = new (config: object) => {
+type HlsLoaderInstance = {
+    stats: LoaderStats;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
+    abort?: () => void;
 };
+type HlsLoader = new (config: object) => HlsLoaderInstance;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+    getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
 };
+declare function isEncryptionKeyUrl(rawUrl: string, baseOrigin?: string): boolean;
+/**
+ * Always resolve a builtin hls.js loader (XhrLoader).
+ *
+ * Never trust `Hls.DefaultConfig.loader` alone — if it was reassigned to a
+ * custom wrapper, `extends` / nested `inner.load()` chains blow Firefox's
+ * stack (`InternalError: too much recursion`).
+ */
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- * Master playlists are signed on loadSource; child playlists / segments / keys
- * are relative and would otherwise be fetched unsigned → CDN 403.
+ *
+ * AES `enc.key` handling (enterprise priority order):
+ * 1. `keyProxyUrlBuilder` — same-origin BFF (production; server IP must pass CDN/WAF)
+ * 2. Otherwise keep CDN/API URL and apply signed `token`/`expires` (and related) query
+ *    params — same auth model as segments on Appextech CDN hosts
+ * 3. Optional `getKeyAccessToken` is applied at load-time (Bearer), not in this rewrite
  */
 declare function rewriteHlsRequestUrl(rawUrl: string, store: AuthParamsStore, options?: AuthParamsLoaderOptions, baseOrigin?: string): string;
 /**
- * hls.js loader that re-applies live AuthParamsStore credentials on every
- * manifest / level / fragment / key request.
+ * hls.js loader that:
+ * - Re-applies signed auth query params on every media request
+ * - Loads AES `enc.key` via BFF / optional Bearer fetch / signed-query XHR
+ *
+ * Uses composition (not `extends DefaultConfig.loader`) so repeated mounts,
+ * HMR, or a polluted DefaultConfig cannot nest `super.load()` into recursion.
  */
 declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
+/**
+ * Redacts sensitive fields. Cycle-safe and depth-capped.
+ * Only walks plain objects/arrays — never DOM / host graphs.
+ */
 declare function redactObject(obj: Record<string, unknown>, seen?: WeakSet<object>, depth?: number): 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, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };
+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, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };