ogplayer 1.0.4 → 1.1.1

package/dist/core/license.d.ts

@@ -4,9 +4,9 @@
  * by the shared private key unlocks all three platforms. No network, ever.
  *
  * License format: `OGP1.<base64url payload JSON>.<base64url ECDSA sig>`.
- * On the web the `apps` patterns bind to the page HOSTNAME (exact match, or
- * prefix match when the pattern ends with `*`). Failure is soft — the caller
- * shows the watermark, playback is unaffected.
+ * On the web the `apps` patterns bind to the page HOSTNAME: exact match, or
+ * `*.example.com` for the domain and all its subdomains. Failure is soft —
+ * the caller shows the watermark, playback is unaffected.
  */
 export type LicenseResult = {
     licensed: true;
@@ -20,7 +20,7 @@ export type LicenseResult = {
 export declare function verifyLicense(licenseKey: string | undefined, hostname: string, publicKeyB64?: string): Promise<LicenseResult>;
 /** DER SEQUENCE { INTEGER r, INTEGER s } → 64-byte raw r||s. */
 export declare function derSignatureToRaw(der: Uint8Array): Uint8Array | null;
-/** Exact match, or prefix match when the pattern ends with `*`. */
+/** Exact match, or `*.example.com` for the domain and all its subdomains. */
 export declare function licensePatternMatches(host: string, pattern: string): boolean;
 /** Valid through the end of `exp` (YYYY-MM-DD), device local date. */
 export declare function isExpired(exp: string): boolean;

package/dist/core/player.d.ts

@@ -1,5 +1,5 @@
 import { type HlsConfig } from "hls.js";
-import { type AudioTrack, type LiveInfo, type OGAnalyticsListener, type OGMediaItem, type PlaybackListener, type PlaybackState, type SubtitleStyle, type TextTrack as OGTextTrack, type ThumbnailFrame, type VideoQuality, type VolumeControlMode } from "./types.js";
+import { type AnalyticsEvent, type AudioTrack, type LiveInfo, type OGAnalyticsListener, type OGMediaItem, type PlaybackListener, type PlaybackState, type SubtitleStyle, type TextTrack as OGTextTrack, type ThumbnailFrame, type VideoQuality, type VolumeControlMode } from "./types.js";
 import type { AdListener } from "../ads/types.js";
 import type { AdsProvider } from "../ads/provider.js";
 export interface OGPlayerOptions {
@@ -66,6 +66,9 @@ export declare class OGPlayer {
     private drmLicenseRequests;
     private thumbnailTrack;
     private lastDroppedTotal;
+    private sessionIdValue;
+    /** BufferStart reasons + time-to-first-frame (per-load state machine). */
+    private sessionTracker;
     /** Saved content position while a content-element ads provider holds the
      * media element (FreeWheel handoff). */
     private breakResume;
@@ -144,6 +147,11 @@ export declare class OGPlayer {
     /** VMAP cue-point times in seconds (negative = postroll). */
     get adCuePoints(): number[];
     get currentLoadGeneration(): number;
+    /** Id of the current analytics session — a fresh UUID minted by every
+     *  `load()`, stamped on each AnalyticsEvent of that load so consumers can
+     *  key their pipelines without inventing their own ids. Null before the
+     *  first load. */
+    get sessionId(): string | null;
     subtitleStyle: SubtitleStyle;
     subtitleTextScale: number;
     onLicenseChanged(cb: (licensed: boolean) => void): void;
@@ -154,7 +162,16 @@ export declare class OGPlayer {
     addAdListener(l: AdListener): void;
     removeAdListener(l: AdListener): void;
     private dispatch;
+    /** Single exit for analytics: every event leaves stamped with the session
+     *  id and asset URL of the load it belongs to (Android parity). */
     private emit;
+    /** @internal Feeds a view-layer analytics event into this player's stream,
+     * session-stamped like every other event. Called by the SDK's own elements
+     * (`<og-player>`) — not host-app API (the web `emitViewAnalytics` of
+     * Android's internal hook; kept off the docs surface via `@internal`). */
+    emitViewAnalytics(e: Extract<AnalyticsEvent, {
+        type: "FullscreenChanged" | "OrientationChanged";
+    }>): void;
     /** The queue set by loadPlaylist() — empty when a single item was loaded. */
     private playlistItems;
     private playlistPosition;
@@ -212,6 +229,17 @@ export declare class OGPlayer {
      */
     retry(): void;
     private attachSource;
+    /**
+     * Emits PlaybackStarted { startupMs } — load() to the load's first
+     * rendered content frame (time-to-first-frame). requestVideoFrameCallback
+     * (Chrome/Safari) reports the actual composited frame; browsers without it
+     * (Firefox) fall back to 'loadeddata' — there the first frame is decoded
+     * and paintable, which lands a paint or two before true presentation but
+     * is the closest cross-browser signal. Armed from attachSource so a
+     * content restore after a content-element ad break (FreeWheel handoff)
+     * re-arms it; the tracker's once-per-load latch dedupes.
+     */
+    private armFirstFrame;
     private adSessionKey;
     private beginAdsIfNeeded;
     private startAdsSession;

package/dist/core/session-tracker.d.ts

@@ -0,0 +1,28 @@
+import type { BufferReason } from "./types.js";
+/**
+ * Pure per-load state behind two analytics facts: why a buffer started
+ * (`BufferReason`) and time-to-first-frame. Reset by every load; driven by
+ * the media-element events the player receives ('seeking', 'seeked',
+ * 'canplay'/'playing'). Pure logic — unit-tested in node without a DOM.
+ * The web port of Android's `PlaybackSessionTracker` (the reference).
+ */
+export declare class PlaybackSessionTracker {
+    private readySeen;
+    private seekInFlight;
+    private loadStartMs;
+    private firstFrameEmitted;
+    onNewLoad(nowMs: number): void;
+    /** 'seeking' fired — buffering that follows is seek-caused. */
+    onSeek(): void;
+    /** 'seeked' fired — the seek is no longer in flight. */
+    onSeekCompleted(): void;
+    /** 'canplay'/'playing' — the load has been ready at least once. */
+    onReady(): void;
+    /** Reason for a buffering transition happening right now. */
+    bufferReason(): BufferReason;
+    /**
+     * Startup time when this is the load's first rendered frame, null on
+     * every later frame (and before any load).
+     */
+    takeFirstFrameStartupMs(nowMs: number): number | null;
+}

package/dist/core/token-fetch.d.ts

@@ -0,0 +1,15 @@
+import type { DrmTokenProvider, DrmTokenRequest } from "./types.js";
+/**
+ * Fenced DRM token fetch — the web counterpart of the Android SDK's
+ * `OGMediaDrmCallback.fetchToken()`: a hung token service must never hold
+ * playback forever. Bounded attempts with a per-attempt timeout and a
+ * progressive backoff; the last failure propagates so callers map it to
+ * DRM_TOKEN_FETCH_FAILED (4002). Same 3 × 8 s fence on all platforms.
+ */
+export declare const TOKEN_ATTEMPTS = 3;
+export declare const TOKEN_TIMEOUT_MS = 8000;
+/** Whole-call deadline for license/certificate HTTP requests — the web
+ *  mirror of Android's `boundedHttpClient` callTimeout and iOS's
+ *  `timeoutIntervalForResource` (15 s on every platform). */
+export declare const LICENSE_CALL_TIMEOUT_MS = 15000;
+export declare function fetchTokenHeaders(provider: DrmTokenProvider, request: DrmTokenRequest, timeoutMs?: number): Promise<Record<string, string>>;

package/dist/core/types.d.ts

@@ -154,7 +154,21 @@ export interface ThumbnailFrame {
     width: number;
     height: number;
 }
-export type AnalyticsEvent = {
+/** Why a BufferStart happened — rebuffer-ratio contracts need initial and
+ *  seek buffering excluded, so the reason is explicit instead of inferred
+ *  from event order. */
+export type BufferReason = "INITIAL" | "SEEK" | "REBUFFER";
+/** Physical device orientation, as reported by the view layer. */
+export type DeviceOrientation = "PORTRAIT" | "LANDSCAPE";
+/** Fields stamped on every analytics event: the per-load session id (a
+ *  fresh UUID minted by every `load()`) and the item URL, so analytics
+ *  pipelines can key events without inventing their own ids. Absent only
+ *  on events emitted before the first load. */
+export interface AnalyticsEventBase {
+    sessionId?: string;
+    assetUrl?: string;
+}
+export type AnalyticsEvent = AnalyticsEventBase & ({
     type: "Play";
 } | {
     type: "Pause";
@@ -162,8 +176,16 @@ export type AnalyticsEvent = {
     type: "Seek";
     fromMs: number;
     toMs: number;
+}
+/** First video frame of a load rendered; `startupMs` is wall time from
+ *  `load()` to that frame — time-to-first-frame, the industry's primary
+ *  startup metric. Emitted once per load. */
+ | {
+    type: "PlaybackStarted";
+    startupMs: number;
 } | {
     type: "BufferStart";
+    reason: BufferReason;
 } | {
     type: "BufferEnd";
 } | {
@@ -172,16 +194,53 @@ export type AnalyticsEvent = {
     width: number;
     height: number;
     frameRate: number;
-} | {
+}
+/** Periodic playback-quality sample, every 10s while playing.
+ *  `liveLatencyMs`/`atLiveEdge` are populated for live streams only. */
+ | {
     type: "QualitySnapshot";
     positionMs: number;
     bufferedMs: number;
     bandwidthEstimateBps: number;
     droppedFramesTotal: number;
+    liveLatencyMs?: number;
+    atLiveEdge?: boolean;
 } | {
     type: "DroppedFrames";
     count: number;
     elapsedMs: number;
+}
+/** The viewer changed volume or mute — the muted-to-sound conversion
+ *  metric for autoplay/ad measurement. */
+ | {
+    type: "VolumeChanged";
+    volume: number;
+    muted: boolean;
+}
+/** A text track was selected (`id` null = subtitles off). */
+ | {
+    type: "TextTrackChanged";
+    id: string | null;
+    language: string | null;
+}
+/** An audio track was selected. */
+ | {
+    type: "AudioTrackChanged";
+    id: string;
+    language: string | null;
+}
+/** The player entered or left fullscreen (reported by the view layer;
+ *  headless integrations do not emit it). */
+ | {
+    type: "FullscreenChanged";
+    isFullscreen: boolean;
+}
+/** The device rotated (reported by the view layer once on attach with the
+ *  initial value, then on change). The vertical feed does not emit it —
+ *  the feed is portrait by design. */
+ | {
+    type: "OrientationChanged";
+    orientation: DeviceOrientation;
 } | {
     type: "DrmKeysLoaded";
 } | {
@@ -205,7 +264,7 @@ export type AnalyticsEvent = {
 } | {
     type: "Error";
     error: OGPlayerError;
-};
+});
 export type OGAnalyticsListener = (event: AnalyticsEvent) => void;
 /** Error taxonomy — same numeric codes as Android/iOS. */
 export declare const ErrorCodes: {

package/dist/core/vertical-feed.d.ts

@@ -104,12 +104,23 @@ export declare class VerticalFeedPlayerPool {
     private activeIndexValue;
     private released;
     private feedMuted;
-    private skipped;
+    /**
+     * ITEMS rejected by the max-duration guard; the feed auto-skips them.
+     * Keyed by the item object (not its index): positions shift on every
+     * `updateItems` refresh, and index-keyed positional skips would
+     * permanently poison whatever lands on those positions in refreshed
+     * lists. A refresh that rebuilds the item objects naturally clears
+     * their skips (the too-long stream is then re-discovered and re-skipped
+     * on first ready); reordering a stable array keeps them.
+     */
+    private skippedItems;
     private licensedValue;
     constructor(config: OGVerticalFeedConfig, callbacks: VerticalFeedPoolCallbacks);
     get activeIndex(): number;
     get isLicensed(): boolean | null;
+    /** Indices of the CURRENT items array whose item is skip-listed. */
     get skippedIndices(): ReadonlySet<number>;
+    private isSkipped;
     updateItems(items: OGVerticalFeedItem[]): void;
     playerAt(index: number): OGPlayer | null;
     setFeedMuted(muted: boolean): void;