@codenkay/video-nsgplayer-core 3.0.0 → 3.0.2

package/dist/index.d.cts

@@ -151,6 +151,12 @@ type StreamingConfig = {
      * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
      */
     getKeyAccessToken?: () => string | null | undefined;
+    /**
+     * Max same-origin key-proxy failures before the session permanently switches
+     * to browser Bearer / signed-query (default 2). Prevents hls.js from hammering
+     * a Cloudflare-blocked BFF (9–10× 502s).
+     */
+    keyProxyMaxFailures?: number;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -198,6 +204,7 @@ type PlayerConfig = Required<{
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
         getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+        keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -279,7 +286,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "2.0.1";
+declare const PACKAGE_VERSION = "3.0.2";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -312,6 +319,7 @@ type PlayerConfigPartial = Partial<{
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
         getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
+        keyProxyMaxFailures?: PlayerConfig["streaming"]["keyProxyMaxFailures"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -431,6 +439,7 @@ type HlsEngineOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -447,7 +456,8 @@ type HlsEngineOptions = {
  * (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
+ * `streaming.getKeyAccessToken` (Bearer only after signed-query 401/403).
+ * CDN keys prefer signed query without Authorization (no CORS preflight).
  * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
@@ -646,44 +656,37 @@ declare class RefreshManager {
 
 type HlsLoaderInstance = {
     stats: LoaderStats;
+    context: LoaderContext | null;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
-    abort?: () => void;
+    abort(): void;
 };
-type HlsLoader = new (config: object) => HlsLoaderInstance;
+/** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
+type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Max same-origin BFF key attempts before the session circuit opens. */
+declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    /** Override max BFF key failures before permanent browser fallback (default 2). */
+    keyProxyMaxFailures?: number;
 };
 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`).
+ * Resolve the builtin loader from the **same** `hls.js` module instance the
+ * engine loaded. Never statically import `XhrLoader` — that can pull a second
+ * hls.js copy into the app bundle after npm pack/publish and break key loads.
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- *
- * 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 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.
+ * hls.js loader: auth query rewrite + enterprise AES key loading.
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -692,4 +695,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 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 PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, 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, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, 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

@@ -151,6 +151,12 @@ type StreamingConfig = {
      * Use when the BFF cannot reach Appextech (Cloudflare challenge on server IP).
      */
     getKeyAccessToken?: () => string | null | undefined;
+    /**
+     * Max same-origin key-proxy failures before the session permanently switches
+     * to browser Bearer / signed-query (default 2). Prevents hls.js from hammering
+     * a Cloudflare-blocked BFF (9–10× 502s).
+     */
+    keyProxyMaxFailures?: number;
 };
 type LoggingConfig = {
     enabled?: boolean;
@@ -198,6 +204,7 @@ type PlayerConfig = Required<{
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
         keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
         getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+        keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -279,7 +286,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "2.0.1";
+declare const PACKAGE_VERSION = "3.0.2";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -312,6 +319,7 @@ type PlayerConfigPartial = Partial<{
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
         keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
         getKeyAccessToken?: PlayerConfig["streaming"]["getKeyAccessToken"];
+        keyProxyMaxFailures?: PlayerConfig["streaming"]["keyProxyMaxFailures"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -431,6 +439,7 @@ type HlsEngineOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    keyProxyMaxFailures?: StreamingConfig["keyProxyMaxFailures"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -447,7 +456,8 @@ type HlsEngineOptions = {
  * (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
+ * `streaming.getKeyAccessToken` (Bearer only after signed-query 401/403).
+ * CDN keys prefer signed query without Authorization (no CORS preflight).
  * when query-signed CDN access is insufficient.
  */
 declare class HlsEngine {
@@ -646,44 +656,37 @@ declare class RefreshManager {
 
 type HlsLoaderInstance = {
     stats: LoaderStats;
+    context: LoaderContext | null;
     load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
     destroy(): void;
-    abort?: () => void;
+    abort(): void;
 };
-type HlsLoader = new (config: object) => HlsLoaderInstance;
+/** Constructor shape compatible with `Hls.DefaultConfig.loader`. */
+type HlsLoaderConstructor = new (config: object) => HlsLoaderInstance;
+/** Max same-origin BFF key attempts before the session circuit opens. */
+declare const KEY_PROXY_MAX_FAILURES = 2;
 type AuthParamsLoaderOptions = {
     videoId?: string;
     keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     getKeyAccessToken?: StreamingConfig["getKeyAccessToken"];
+    /** Override max BFF key failures before permanent browser fallback (default 2). */
+    keyProxyMaxFailures?: number;
 };
 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`).
+ * Resolve the builtin loader from the **same** `hls.js` module instance the
+ * engine loaded. Never statically import `XhrLoader` — that can pull a second
+ * hls.js copy into the app bundle after npm pack/publish and break key loads.
  */
-declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoader;
+declare function resolveBuiltinHlsLoader(HlsClass: typeof Hls): HlsLoaderConstructor;
 /**
  * Rewrites an HLS request URL so signed auth query params are present.
- *
- * 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 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.
+ * hls.js loader: auth query rewrite + enterprise AES key loading.
  */
-declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoaderConstructor;
 
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 /**
@@ -692,4 +695,4 @@ declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>
  */
 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 PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, 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, KEY_PROXY_MAX_FAILURES, type LiveMediaSnapshot, type LoggingConfig, PACKAGE_VERSION, PLAYBACK_RATES, type PlayIconPreset, type PlaybackCredentialConfig, type PlaybackRate, type PlaybackSource, type PlaybackSourceContext, PlaybackSourceManager, type PlayerAudioTrack, type PlayerBehaviorConfig, type PlayerConfig, type PlayerDiagnostics, type PlayerError, PlayerErrorCode, type PlayerEventMap, type PlayerSkipSeconds, type PlayerState, type PlayerTextTrack, type PlayerZoomLevel, type QualitySelection, RefreshManager, SECRET_SCAN_MAX_DEPTH, type SeekToLiveResult, type StreamingConfig, type TextTrackSelection, type ThemeConfig, type VideoPlayer, type WatermarkConfig, assertNoSecretsInConfig, createAuthParamsLoader, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isEncryptionKeyUrl, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, resolveBuiltinHlsLoader, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };