@codenkay/video-nsgplayer-core 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
@@ -166,6 +168,7 @@ type PlayerConfig = Required<{
     streaming: {
         engine: "hls";
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
+        keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -239,7 +242,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.2";
+declare const PACKAGE_VERSION = "0.1.3";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -270,7 +273,7 @@ type PlayerConfigPartial = Partial<{
     streaming: {
         engine?: "hls";
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
-        keyProxyUrlBuilder?: unknown;
+        keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -343,7 +346,14 @@ declare class AuthParamsStore {
     constructor(initial?: URLSearchParams | Record<string, string>);
     getSnapshot(): URLSearchParams;
     toRecord(): Record<string, string>;
+    /** True when at least one auth query param is stored. */
+    hasParams(): boolean;
+    toString(): string;
     update(next: URLSearchParams | Record<string, string>): void;
+    /**
+     * Merges current auth params onto a target URL, preserving unrelated query keys.
+     * Critical for child HLS playlists/segments that omit signed query params.
+     */
     applyToUrl(rawUrl: string, baseOrigin?: string): string;
 }
 
@@ -376,6 +386,8 @@ type HlsEngineOptions = {
     startMuted: boolean;
     startPosition?: number;
     volume?: number;
+    videoId?: string;
+    keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -387,6 +399,11 @@ 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.
  */
 declare class HlsEngine {
     private readonly options;
@@ -558,7 +575,27 @@ declare class RefreshManager {
     private renew;
 }
 
+type HlsLoader = new (config: object) => {
+    load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
+    destroy(): void;
+};
+type AuthParamsLoaderOptions = {
+    videoId?: string;
+    keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+};
+/**
+ * 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.
+ */
+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.
+ */
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 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, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, 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, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, rewriteHlsRequestUrl, seekToLiveEdge, themeToCssVars };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import Hls, { LoaderContext, LoaderConfiguration, LoaderCallbacks } from 'hls.js';
+
 /** Player lifecycle states. */
 type PlayerState = "idle" | "loading" | "ready" | "playing" | "paused" | "buffering" | "renewing" | "ended" | "error" | "destroyed";
 type HlsSupportMode = "hls.js" | "native" | "unsupported";
@@ -166,6 +168,7 @@ type PlayerConfig = Required<{
     streaming: {
         engine: "hls";
         hls: Required<NonNullable<StreamingConfig["hls"]>>;
+        keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     };
     logging: Required<LoggingConfig>;
     debug: Required<DebugConfig>;
@@ -239,7 +242,7 @@ type PlayerEventMap = {
 };
 
 declare const PLAYBACK_RATES: readonly [0.5, 0.75, 1, 1.25, 1.5, 2];
-declare const PACKAGE_VERSION = "0.1.2";
+declare const PACKAGE_VERSION = "0.1.3";
 declare const DEFAULT_PLAYER_BEHAVIOR: Required<PlayerBehaviorConfig>;
 declare const DEFAULT_CONTROLS: Required<ControlsConfig>;
 declare const DEFAULT_THEME: Required<ThemeConfig>;
@@ -270,7 +273,7 @@ type PlayerConfigPartial = Partial<{
     streaming: {
         engine?: "hls";
         hls?: Partial<PlayerConfig["streaming"]["hls"]>;
-        keyProxyUrlBuilder?: unknown;
+        keyProxyUrlBuilder?: PlayerConfig["streaming"]["keyProxyUrlBuilder"];
     };
     logging: Partial<PlayerConfig["logging"]>;
     debug: Partial<PlayerConfig["debug"]>;
@@ -343,7 +346,14 @@ declare class AuthParamsStore {
     constructor(initial?: URLSearchParams | Record<string, string>);
     getSnapshot(): URLSearchParams;
     toRecord(): Record<string, string>;
+    /** True when at least one auth query param is stored. */
+    hasParams(): boolean;
+    toString(): string;
     update(next: URLSearchParams | Record<string, string>): void;
+    /**
+     * Merges current auth params onto a target URL, preserving unrelated query keys.
+     * Critical for child HLS playlists/segments that omit signed query params.
+     */
     applyToUrl(rawUrl: string, baseOrigin?: string): string;
 }
 
@@ -376,6 +386,8 @@ type HlsEngineOptions = {
     startMuted: boolean;
     startPosition?: number;
     volume?: number;
+    videoId?: string;
+    keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
     hlsConfig: {
         enableWorker: boolean;
         lowLatencyMode: boolean;
@@ -387,6 +399,11 @@ 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.
  */
 declare class HlsEngine {
     private readonly options;
@@ -558,7 +575,27 @@ declare class RefreshManager {
     private renew;
 }
 
+type HlsLoader = new (config: object) => {
+    load(context: LoaderContext, config: LoaderConfiguration, callbacks: LoaderCallbacks<LoaderContext>): void;
+    destroy(): void;
+};
+type AuthParamsLoaderOptions = {
+    videoId?: string;
+    keyProxyUrlBuilder?: StreamingConfig["keyProxyUrlBuilder"];
+};
+/**
+ * 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.
+ */
+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.
+ */
+declare function createAuthParamsLoader(HlsClass: typeof Hls, store: AuthParamsStore, options?: AuthParamsLoaderOptions): HlsLoader;
+
 declare function redactValue(key: string, value: unknown, seen?: WeakSet<object>, depth?: number): unknown;
 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, createPlayerError, createVideoPlayer, getLiveEdgeTime, isAtLiveEdge, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, 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, isPlainObject, mergePlayerConfig, redactObject, redactSensitive, redactValue, 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.2";
+var PACKAGE_VERSION = "0.1.3";
 var DEFAULT_PLAYER_BEHAVIOR = {
   autoplay: true,
   startMuted: true,
@@ -322,7 +322,8 @@ function mergePlayerConfig(partial) {
       hls: {
         ...DEFAULT_PLAYER_CONFIG.streaming.hls,
         ...partial?.streaming?.hls
-      }
+      },
+      keyProxyUrlBuilder: partial?.streaming?.keyProxyUrlBuilder
     },
     logging: { ...DEFAULT_PLAYER_CONFIG.logging, ...partial?.logging },
     debug: { ...DEFAULT_PLAYER_CONFIG.debug, ...partial?.debug },
@@ -498,11 +499,25 @@ var AuthParamsStore = class {
     });
     return out;
   }
+  /** True when at least one auth query param is stored. */
+  hasParams() {
+    return [...this.params.keys()].length > 0;
+  }
+  toString() {
+    return this.params.toString();
+  }
   update(next) {
     this.params = next instanceof URLSearchParams ? new URLSearchParams(next) : new URLSearchParams(next);
   }
+  /**
+   * Merges current auth params onto a target URL, preserving unrelated query keys.
+   * Critical for child HLS playlists/segments that omit signed query params.
+   */
   applyToUrl(rawUrl, baseOrigin) {
-    const target = new URL(rawUrl, baseOrigin ?? (typeof location !== "undefined" ? location.origin : "http://localhost"));
+    const target = new URL(
+      rawUrl,
+      baseOrigin ?? (typeof location !== "undefined" ? location.origin : "http://localhost")
+    );
     this.params.forEach((value, key) => {
       target.searchParams.set(key, value);
     });
@@ -737,6 +752,39 @@ function seekToLiveEdge(media, options) {
   return { moved: true, edge };
 }
 
+// src/streaming/authParamsLoader.ts
+var ENC_KEY_PATH_RE = /\/enc\.key$/i;
+function rewriteHlsRequestUrl(rawUrl, store, options = {}, baseOrigin = typeof location !== "undefined" ? location.origin : "http://localhost") {
+  if (!rawUrl) return rawUrl;
+  const parsed = new URL(rawUrl, baseOrigin);
+  const isKey = ENC_KEY_PATH_RE.test(parsed.pathname);
+  if (isKey && options.keyProxyUrlBuilder && options.videoId) {
+    const snapshot = store.toRecord();
+    return options.keyProxyUrlBuilder({
+      videoId: options.videoId,
+      keyUrl: parsed.toString(),
+      token: snapshot.token,
+      expires: snapshot.expires
+    });
+  }
+  if (!store.hasParams()) return parsed.toString();
+  return store.applyToUrl(rawUrl, baseOrigin);
+}
+function createAuthParamsLoader(HlsClass, store, options = {}) {
+  const BaseLoader = HlsClass.DefaultConfig.loader;
+  return class AuthParamsLoader extends BaseLoader {
+    load(context, config, callbacks) {
+      if (context.url) {
+        try {
+          context.url = rewriteHlsRequestUrl(context.url, store, options);
+        } catch {
+        }
+      }
+      super.load(context, config, callbacks);
+    }
+  };
+}
+
 // src/streaming/HlsEngine.ts
 var HlsEngine = class {
   constructor(options) {
@@ -789,15 +837,16 @@ var HlsEngine = class {
     }
   }
   async startWithHlsJs(Hls, playbackUrl) {
-    const { videoEl, authParams, hlsConfig, callbacks } = this.options;
+    const { videoEl, authParams, hlsConfig, callbacks, videoId, keyProxyUrlBuilder } = this.options;
+    const loader = createAuthParamsLoader(Hls, authParams, {
+      videoId,
+      keyProxyUrlBuilder
+    });
     this.hls = new Hls({
       enableWorker: hlsConfig.enableWorker,
       lowLatencyMode: hlsConfig.lowLatencyMode,
       backBufferLength: hlsConfig.backBufferLength,
-      xhrSetup: (xhr, url) => {
-        void xhr;
-        void url;
-      }
+      loader
     });
     this.hls.attachMedia(videoEl);
     this.hls.loadSource(authParams.applyToUrl(playbackUrl));
@@ -1005,6 +1054,8 @@ function createVideoPlayer(options) {
         startMuted: config.player.startMuted,
         startPosition: config.player.startPosition,
         volume: config.player.volume,
+        videoId: options.videoId,
+        keyProxyUrlBuilder: options.streaming?.keyProxyUrlBuilder,
         hlsConfig: config.streaming.hls,
         logger,
         callbacks: {
@@ -1265,7 +1316,8 @@ function createVideoPlayer(options) {
         watermark: { ...config.watermark, ...partial?.watermark },
         streaming: {
           engine: "hls",
-          hls: { ...config.streaming.hls, ...partial?.streaming?.hls }
+          hls: { ...config.streaming.hls, ...partial?.streaming?.hls },
+          keyProxyUrlBuilder: partial?.streaming?.keyProxyUrlBuilder ?? config.streaming.keyProxyUrlBuilder
         },
         logging: { ...config.logging, ...partial?.logging },
         debug: { ...config.debug, ...partial?.debug },
@@ -1303,6 +1355,7 @@ export {
   RefreshManager,
   SECRET_SCAN_MAX_DEPTH,
   assertNoSecretsInConfig,
+  createAuthParamsLoader,
   createPlayerError,
   createVideoPlayer,
   getLiveEdgeTime,
@@ -1312,6 +1365,7 @@ export {
   redactObject,
   redactSensitive,
   redactValue,
+  rewriteHlsRequestUrl,
   seekToLiveEdge,
   themeToCssVars
 };