@codenkay/video-nsgplayer-core 0.1.5 → 1.0.0

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";
@@ -255,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.5";
+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>;
@@ -415,9 +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.
- * Encrypted VOD also requires a same-origin `enc.key` proxy (Bearer + query)
- * via `streaming.keyProxyUrlBuilder` — browser CORS cannot fetch Video API keys.
+ * 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;
@@ -591,32 +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 (pick one):
- * 1. `keyProxyUrlBuilder` — same-origin BFF (needs Cloudflare-allowlisted server IP)
- * 2. `getKeyAccessToken` — browser-direct CDN fetch with API Bearer header
+ * 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.js

@@ -146,7 +146,7 @@ var AuthManager = class {
 
 // src/config/defaults.ts
 var PLAYBACK_RATES = [0.5, 0.75, 1, 1.25, 1.5, 2];
-var PACKAGE_VERSION = "0.1.5";
+var PACKAGE_VERSION = "0.1.8";
 var DEFAULT_PLAYER_BEHAVIOR = {
   autoplay: true,
   startMuted: true,
@@ -406,23 +406,25 @@ function isPlainObject2(value) {
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
 }
-function redactValue(key, value, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
-  if (SENSITIVE_KEYS.test(key)) return "[REDACTED]";
-  if (typeof value === "string") {
-    if (/^https?:\/\//i.test(value) && /[?&](token|expires)=/i.test(value)) {
-      try {
-        const url = new URL(value);
-        for (const param of ["token", "expires", "signature", "sig"]) {
-          if (url.searchParams.has(param)) {
-            url.searchParams.set(param, "[REDACTED]");
-          }
-        }
-        return url.toString();
-      } catch {
-        return "[REDACTED_URL]";
+function redactStringUrl(value) {
+  if (!/^https?:\/\//i.test(value) || !/[?&](token|expires)=/i.test(value)) {
+    return value;
+  }
+  try {
+    const url = new URL(value);
+    for (const param of ["token", "expires", "signature", "sig"]) {
+      if (url.searchParams.has(param)) {
+        url.searchParams.set(param, "[REDACTED]");
       }
     }
+    return url.toString();
+  } catch {
+    return "[REDACTED_URL]";
   }
+}
+function redactValue(key, value, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
+  if (SENSITIVE_KEYS.test(key)) return "[REDACTED]";
+  if (typeof value === "string") return redactStringUrl(value);
   if (Array.isArray(value)) {
     if (depth >= REDACT_MAX_DEPTH || seen.has(value)) return "[REDACTED_CYCLE]";
     seen.add(value);
@@ -689,10 +691,11 @@ var RefreshManager = class {
       this.options.logger.debug("Playback source renewed", { reason });
     } catch (error) {
       this.consecutiveFailures += 1;
-      const message = error instanceof Error ? error.message : "Playback refresh failed";
+      const message = refreshErrorMessage(error);
       this.options.logger.warn("Playback refresh failed", {
         reason,
-        failure: this.consecutiveFailures
+        failure: this.consecutiveFailures,
+        message
       });
       if (this.consecutiveFailures >= this.options.renewMaxRetries) {
         this.options.onFatal?.(message);
@@ -712,6 +715,13 @@ var RefreshManager = class {
     }
   }
 };
+function refreshErrorMessage(error) {
+  if (error instanceof Error && error.message) return error.message;
+  if (error && typeof error === "object" && "message" in error && typeof error.message === "string" && error.message) {
+    return error.message;
+  }
+  return "Playback refresh failed";
+}
 
 // src/playback/liveEdge.ts
 var DEFAULT_LIVE_EDGE_TOLERANCE_SECONDS = 3;
@@ -755,7 +765,9 @@ function seekToLiveEdge(media, options) {
 }
 
 // src/streaming/authParamsLoader.ts
+import { XhrLoader as BuiltinXhrLoader } from "hls.js";
 var ENC_KEY_PATH_RE = /enc\.key$/i;
+var BUILTIN_LOADER_NAMES = /* @__PURE__ */ new Set(["XhrLoader", "FetchLoader"]);
 function isEncryptionKeyUrl(rawUrl, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
   try {
     return ENC_KEY_PATH_RE.test(new URL(rawUrl, baseOrigin).pathname);
@@ -763,6 +775,27 @@ function isEncryptionKeyUrl(rawUrl, baseOrigin = typeof location !== "undefined"
     return /enc\.key/i.test(rawUrl);
   }
 }
+function resolveBuiltinHlsLoader(HlsClass) {
+  if (typeof BuiltinXhrLoader === "function") {
+    return BuiltinXhrLoader;
+  }
+  const start = HlsClass.DefaultConfig.loader;
+  let current = start;
+  const seen = /* @__PURE__ */ new Set();
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const name = typeof current.name === "string" ? current.name : "";
+    if (BUILTIN_LOADER_NAMES.has(name)) {
+      return current;
+    }
+    const parentCtor = Object.getPrototypeOf(current.prototype)?.constructor;
+    if (!parentCtor || parentCtor === Object || parentCtor === Function) {
+      break;
+    }
+    current = parentCtor;
+  }
+  return start;
+}
 function rewriteHlsRequestUrl(rawUrl, store, options = {}, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
   if (!rawUrl) return rawUrl;
   const parsed = new URL(rawUrl, baseOrigin);
@@ -781,28 +814,145 @@ function rewriteHlsRequestUrl(rawUrl, store, options = {}, baseOrigin = typeof l
   if (!store.hasParams()) return parsed.toString();
   return store.applyToUrl(rawUrl, baseOrigin);
 }
+function createLoaderStats() {
+  const now = performance.now();
+  return {
+    aborted: false,
+    loaded: 0,
+    retry: 0,
+    total: 0,
+    chunkCount: 0,
+    bwEstimate: 0,
+    loading: { start: now, first: 0, end: 0 },
+    parsing: { start: 0, end: 0 },
+    buffering: { start: 0, first: 0, end: 0 }
+  };
+}
+async function loadEncryptionKeyWithFetch(context, callbacks, accessToken, signal) {
+  const stats = createLoaderStats();
+  stats.loading.first = performance.now();
+  const headers = {
+    Accept: "*/*",
+    ...context.headers
+  };
+  if (accessToken) {
+    headers.Authorization = `Bearer ${accessToken}`;
+  }
+  const response = await fetch(context.url, {
+    method: "GET",
+    headers,
+    credentials: "omit",
+    cache: "no-store",
+    signal
+  });
+  if (!response.ok) {
+    callbacks.onError(
+      {
+        code: response.status,
+        text: response.statusText || `enc.key HTTP ${response.status}`
+      },
+      context,
+      response,
+      stats
+    );
+    return;
+  }
+  const data = await response.arrayBuffer();
+  const end = performance.now();
+  stats.loading.end = end;
+  stats.loaded = data.byteLength;
+  stats.total = data.byteLength;
+  const head = new TextDecoder().decode(data.slice(0, 32));
+  if (/<!DOCTYPE|<html/i.test(head)) {
+    callbacks.onError(
+      {
+        code: 403,
+        text: "enc.key returned HTML (CDN challenge/block), not an AES key"
+      },
+      context,
+      response,
+      stats
+    );
+    return;
+  }
+  callbacks.onSuccess(
+    {
+      url: response.url || context.url,
+      data,
+      code: response.status
+    },
+    stats,
+    context,
+    response
+  );
+}
 function createAuthParamsLoader(HlsClass, store, options = {}) {
-  const BaseLoader = HlsClass.DefaultConfig.loader;
-  return class AuthParamsLoader extends BaseLoader {
+  const BaseLoader = resolveBuiltinHlsLoader(HlsClass);
+  return class AuthParamsLoader {
+    constructor(config) {
+      this.keyAbort = null;
+      this.inner = new BaseLoader(config);
+      this.stats = this.inner.stats;
+    }
+    abort() {
+      this.keyAbort?.abort();
+      this.keyAbort = null;
+      this.inner.abort?.();
+    }
+    destroy() {
+      this.keyAbort?.abort();
+      this.keyAbort = null;
+      this.inner.destroy();
+    }
     load(context, config, callbacks) {
-      if (context.url) {
-        try {
-          const originalUrl = context.url;
-          const isKey = isEncryptionKeyUrl(originalUrl);
-          context.url = rewriteHlsRequestUrl(originalUrl, store, options);
-          if (isKey && !options.keyProxyUrlBuilder && options.getKeyAccessToken) {
-            const accessToken = options.getKeyAccessToken();
-            if (accessToken) {
-              context.headers = {
-                ...context.headers ?? {},
-                Authorization: `Bearer ${accessToken}`
-              };
-            }
+      if (!context.url) {
+        this.inner.load(context, config, callbacks);
+        return;
+      }
+      try {
+        const originalUrl = context.url;
+        const isKey = isEncryptionKeyUrl(originalUrl);
+        const usingKeyProxy = Boolean(
+          isKey && options.keyProxyUrlBuilder && options.videoId
+        );
+        context.url = rewriteHlsRequestUrl(originalUrl, store, options);
+        if (usingKeyProxy) {
+          this.inner.load(context, config, callbacks);
+          return;
+        }
+        if (isKey && typeof options.getKeyAccessToken === "function") {
+          const accessToken = options.getKeyAccessToken() ?? null;
+          if (accessToken) {
+            this.keyAbort?.abort();
+            this.keyAbort = new AbortController();
+            const timeoutMs = typeof config?.timeout === "number" && config.timeout > 0 ? config.timeout : 2e4;
+            const timer = setTimeout(() => this.keyAbort?.abort(), timeoutMs);
+            void loadEncryptionKeyWithFetch(
+              context,
+              callbacks,
+              accessToken,
+              this.keyAbort.signal
+            ).catch((error) => {
+              const stats = createLoaderStats();
+              const aborted = error instanceof DOMException && error.name === "AbortError";
+              callbacks.onError(
+                {
+                  code: 0,
+                  text: aborted ? "enc.key fetch aborted/timeout" : error instanceof Error ? error.message : "enc.key fetch failed"
+                },
+                context,
+                null,
+                stats
+              );
+            }).finally(() => {
+              clearTimeout(timer);
+            });
+            return;
           }
-        } catch {
         }
+      } catch {
       }
-      super.load(context, config, callbacks);
+      this.inner.load(context, config, callbacks);
     }
   };
 }
@@ -893,19 +1043,24 @@ var HlsEngine = class {
   }
   handleHlsError(Hls, data) {
     if (this.destroyed) return;
-    const { callbacks, hlsConfig, keyProxyUrlBuilder, getKeyAccessToken } = this.options;
+    const { callbacks, hlsConfig } = this.options;
     const status = data.response?.code;
-    if (data.details === Hls.ErrorDetails.KEY_LOAD_ERROR && !keyProxyUrlBuilder && !getKeyAccessToken) {
-      callbacks.onFatalError?.(
-        "Encryption key load failed. Configure streaming.getKeyAccessToken (browser Bearer) or streaming.keyProxyUrlBuilder (Cloudflare-allowlisted BFF) for Appextech AES-encrypted HLS."
-      );
-      return;
+    const authFailure = isAuthHttpStatus(status);
+    if (data.details === Hls.ErrorDetails.KEY_LOAD_ERROR) {
+      if (authFailure) {
+        callbacks.onAuthRecoveryNeeded?.("key_error");
+        if (!data.fatal) return;
+      } else if (!data.fatal) {
+        callbacks.onFatalError?.(
+          status ? `Encryption key load failed (HTTP ${status}).` : "Encryption key load failed (network/CORS). Ensure signed query params are applied, or use keyProxyUrlBuilder / getKeyAccessToken when the key host requires API Bearer."
+        );
+        return;
+      }
     }
-    const authFailure = isAuthHttpStatus(status) || data.details === Hls.ErrorDetails.KEY_LOAD_ERROR && (status === void 0 || status === 0 || isAuthHttpStatus(status));
     if (!data.fatal) {
-      if (authFailure && data.type === Hls.ErrorTypes.NETWORK_ERROR && (data.details === Hls.ErrorDetails.FRAG_LOAD_ERROR || data.details === Hls.ErrorDetails.LEVEL_LOAD_ERROR || data.details === Hls.ErrorDetails.KEY_LOAD_ERROR)) {
+      if (authFailure && data.type === Hls.ErrorTypes.NETWORK_ERROR && (data.details === Hls.ErrorDetails.FRAG_LOAD_ERROR || data.details === Hls.ErrorDetails.LEVEL_LOAD_ERROR)) {
         callbacks.onAuthRecoveryNeeded?.(
-          data.details === Hls.ErrorDetails.KEY_LOAD_ERROR ? "key_error" : data.details === Hls.ErrorDetails.LEVEL_LOAD_ERROR ? "level_error" : "frag_error"
+          data.details === Hls.ErrorDetails.LEVEL_LOAD_ERROR ? "level_error" : "frag_error"
         );
       }
       return;
@@ -1134,6 +1289,11 @@ function createVideoPlayer(options) {
         volume: config.player.volume,
         videoId: options.videoId,
         keyProxyUrlBuilder: config.streaming.keyProxyUrlBuilder,
+        // Optional: browser Bearer for Video API–origin enc.key (CORS-dependent).
+        // CDN keys use signed query via the auth loader (no Bearer) — same as
+        // segments. Apps can pass getKeyAccessToken or rely on keyProxyUrlBuilder.
+        // When unset, defaults to AuthManager token only if explicitly requested
+        // via streaming.getKeyAccessToken; otherwise query-signed XHR.
         getKeyAccessToken: config.streaming.getKeyAccessToken,
         hlsConfig: config.streaming.hls,
         logger,
@@ -1448,11 +1608,13 @@ export {
   createVideoPlayer,
   getLiveEdgeTime,
   isAtLiveEdge,
+  isEncryptionKeyUrl,
   isPlainObject,
   mergePlayerConfig,
   redactObject,
   redactSensitive,
   redactValue,
+  resolveBuiltinHlsLoader,
   rewriteHlsRequestUrl,
   seekToLiveEdge,
   themeToCssVars