@oddin-gg/havik-player 1.8.4 → 1.9.0

package/dist/index.d.cts

@@ -164,6 +164,21 @@ export declare interface CreatePlayerOptions {
      * differs from that convention.
      */
     eventsBaseUrl?: string;
+    /**
+     * QoE beacons + CMCD session attribution. Active only when the playback
+     * response carries an analytics sid (the server-side flag) — without one
+     * this option does nothing. Default: true, with the beacons endpoint
+     * derived from {@link baseUrl} by hostname convention (`feed[-dev].…` →
+     * `beacons[-dev].…`). Pass `false` to opt out entirely, or
+     * `{ endpoint }` to point at a non-conventional beacons host.
+     *
+     * Privacy: the sid is an opaque per-session id, held in memory only and
+     * never persisted; beacons carry playback QoE numbers, never identifiers
+     * beyond the sid. See the analytics plan (D11) for the full posture.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 declare interface Credential_2 {
@@ -559,6 +574,16 @@ export declare interface PlaybackStats {
     isLive?: boolean;
     /** Whether playback is at/near the live edge (within the live sync window). */
     atLiveEdge?: boolean;
+    /** Cumulative media segment bytes fetched this session (hls.js engine only). */
+    bytesLoaded?: number;
+    /** Cumulative manifest/playlist bytes fetched this session (hls.js engine only). */
+    playlistBytesLoaded?: number;
+    /** Cumulative ABR rendition switches this session (hls.js engine only). */
+    renditionSwitches?: number;
+    /** Bitrate of the current rendition in kbps, when known. */
+    renditionBitrateKbps?: number;
+    /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */
+    licenseTimeMs?: number;
 }
 
 export declare interface Player {
@@ -693,6 +718,16 @@ export declare interface StreamDescriptor {
     liveStartsAt?: string;
     /** Filled by the player once a media playlist with EXT-X-PART-INF is seen. */
     isLowLatency?: boolean;
+    /**
+     * Analytics session binding minted by havik-streams (present when the
+     * server has analytics enabled). The sid is an opaque per-playback-session
+     * id — non-secret by design (DRM remains the access gate) — echoed in CMCD
+     * query params on CDN requests and carried by QoE beacons. It lives only in
+     * memory for the duration of the session and is never persisted.
+     */
+    analytics?: {
+        sid?: string;
+    };
     /** Any unrecognized top-level fields from the playback response (forward-compat). */
     extensions?: Record<string, unknown>;
 }

package/dist/index.d.ts

@@ -164,6 +164,21 @@ export declare interface CreatePlayerOptions {
      * differs from that convention.
      */
     eventsBaseUrl?: string;
+    /**
+     * QoE beacons + CMCD session attribution. Active only when the playback
+     * response carries an analytics sid (the server-side flag) — without one
+     * this option does nothing. Default: true, with the beacons endpoint
+     * derived from {@link baseUrl} by hostname convention (`feed[-dev].…` →
+     * `beacons[-dev].…`). Pass `false` to opt out entirely, or
+     * `{ endpoint }` to point at a non-conventional beacons host.
+     *
+     * Privacy: the sid is an opaque per-session id, held in memory only and
+     * never persisted; beacons carry playback QoE numbers, never identifiers
+     * beyond the sid. See the analytics plan (D11) for the full posture.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 declare interface Credential_2 {
@@ -559,6 +574,16 @@ export declare interface PlaybackStats {
     isLive?: boolean;
     /** Whether playback is at/near the live edge (within the live sync window). */
     atLiveEdge?: boolean;
+    /** Cumulative media segment bytes fetched this session (hls.js engine only). */
+    bytesLoaded?: number;
+    /** Cumulative manifest/playlist bytes fetched this session (hls.js engine only). */
+    playlistBytesLoaded?: number;
+    /** Cumulative ABR rendition switches this session (hls.js engine only). */
+    renditionSwitches?: number;
+    /** Bitrate of the current rendition in kbps, when known. */
+    renditionBitrateKbps?: number;
+    /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */
+    licenseTimeMs?: number;
 }
 
 export declare interface Player {
@@ -693,6 +718,16 @@ export declare interface StreamDescriptor {
     liveStartsAt?: string;
     /** Filled by the player once a media playlist with EXT-X-PART-INF is seen. */
     isLowLatency?: boolean;
+    /**
+     * Analytics session binding minted by havik-streams (present when the
+     * server has analytics enabled). The sid is an opaque per-playback-session
+     * id — non-secret by design (DRM remains the access gate) — echoed in CMCD
+     * query params on CDN requests and carried by QoE beacons. It lives only in
+     * memory for the duration of the session and is never persisted.
+     */
+    analytics?: {
+        sid?: string;
+    };
     /** Any unrecognized top-level fields from the playback response (forward-compat). */
     extensions?: Record<string, unknown>;
 }