@oddin-gg/havik-player 2.9.3 → 2.11.0

package/dist/index.d.cts

@@ -57,6 +57,29 @@ export declare interface CatalogMatch {
     tournamentUrn: string;
     tournamentName: string;
     sport: string;
+    /**
+     * The two sides, home first, as the server sends them. Absent when no
+     * usable team survives parsing: the server sent no `teams` (an older
+     * havik-streams), or every entry lacked both a URN and a name. A team with
+     * a URN but no name IS kept. `matchName` stays the display string.
+     */
+    teams?: CatalogTeam[];
+}
+
+/**
+ * One side of a match. `urn` is the server's competitor URN
+ * (`od:competitor:N`); `logoUrl` is an https image URL, present only when
+ * the deployment resolves team logos and this team has one.
+ *
+ * A `logoUrl` can still fail to load (the CDN may not have the file), so
+ * always render a fallback for a missing or broken image. Allow the logo
+ * hosts (`cdn.oddin.gg`, and `cdn.runestone.gg`) in a CSP `img-src`.
+ */
+export declare interface CatalogTeam {
+    urn: string;
+    name: string;
+    isHome: boolean;
+    logoUrl?: string;
 }
 
 export declare interface CatalogTournament {
@@ -162,6 +185,15 @@ export declare interface CreatePlayerOptions {
      * playback has fallen well behind. Default: true. Live/LL only.
      */
     snapToLiveOnRefocus?: boolean;
+    /**
+     * DRM cold start: download the first init segment and parts while the
+     * first key is still being acquired, instead of after it (hls.js waits for
+     * the key before requesting any media). Bytes are handed to hls.js only
+     * when it asks for them, so nothing is appended earlier than before; only
+     * the network time leaves the critical path. Default: true. Ignored on
+     * clear streams, and when `hlsConfig.fLoader` is set.
+     */
+    mediaDuringKey?: boolean;
     /** Force an engine; 'auto' prefers hls.js wherever supported (incl. modern
      *  Safari/iOS via ManagedMediaSource) and falls back to native HLS. Default: 'auto'. */
     engine?: 'auto' | 'hls' | 'native';
@@ -660,11 +692,19 @@ export declare function licenseRequestHeaders(descriptor: StreamDescriptor, cred
  * the `/v1/playback` outcome ladder so a pushed event and a follow-up
  * `/v1/playback` call always agree:
  *   live     ↔ 200 OK         (a serveable session exists — play now)
- *   upcoming ↔ 425 Too Early  (scheduled, not serving yet)
+ *   upcoming ↔ 425 Too Early  (scheduled, not serving yet; `liveStartsAt` says when)
+ *   pending  ↔ 425 Too Early  (kickoff has passed, the stream is being packaged —
+ *                              no `liveStartsAt`; `live` follows within seconds
+ *                              to minutes)
  *   ended    ↔ 503            (was live; media stopped, still in catchup)
  *   gone     ↔ 410 Gone       (ended past the catchup window)
+ *
+ * `pending` and `upcoming` ask the same thing of a player — wait — and the
+ * managed player treats them alike ("Starting soon…"). A host that renders
+ * its own waiting UI can tell them apart: `upcoming` has a kickoff to count
+ * down to, `pending` means the match is on and media is seconds away.
  */
-export declare type LiveState = 'live' | 'upcoming' | 'ended' | 'gone';
+export declare type LiveState = 'live' | 'upcoming' | 'pending' | 'ended' | 'gone';
 
 export declare interface LiveStateEvent {
     matchUrn: string;
@@ -680,7 +720,13 @@ export declare interface LiveStateSubscription {
     close(): void;
 }
 
-export declare type MatchLiveStatus = 'upcoming' | 'live' | 'ended';
+/**
+ * `pending` is the catalog's "kickoff has passed, the stream is being
+ * packaged" — not playable yet, `live` expected within seconds to minutes. It
+ * is NOT `upcoming` (which has a kickoff ahead) and not `live` (nothing serves
+ * yet); `/v1/playback` answers `425` for it without a `liveStartsAt`.
+ */
+export declare type MatchLiveStatus = 'upcoming' | 'pending' | 'live' | 'ended';
 
 export declare interface MatchStatus {
     matchUrn: string;
@@ -694,6 +740,12 @@ export declare interface MatchStatus {
      */
     statusRaw?: string;
     datePlannedStart?: string;
+    /**
+     * The match's teams as of this report (see {@link CatalogTeam}).
+     * `watchStatus` fires again when they change, so a logo the server
+     * resolves after the first read is re-reported with the same status.
+     */
+    teams?: CatalogTeam[];
 }
 
 /**
@@ -1167,7 +1219,11 @@ export declare interface WatchStatusOptions {
     baseUrl: string;
     matchUrn: string;
     credential: CredentialSource;
-    /** Fired whenever the status changes (and once on first read). */
+    /**
+     * Fired once on first read and then whenever the status, the teams (a logo
+     * resolved after the first read) or the planned start change. Unchanged
+     * polls (304 or an identical body) stay silent.
+     */
     onChange: (status: MatchStatus) => void;
     /** Fired on a poll error; polling continues. */
     onError?: (err: PlaybackError) => void;

package/dist/index.d.ts

@@ -57,6 +57,29 @@ export declare interface CatalogMatch {
     tournamentUrn: string;
     tournamentName: string;
     sport: string;
+    /**
+     * The two sides, home first, as the server sends them. Absent when no
+     * usable team survives parsing: the server sent no `teams` (an older
+     * havik-streams), or every entry lacked both a URN and a name. A team with
+     * a URN but no name IS kept. `matchName` stays the display string.
+     */
+    teams?: CatalogTeam[];
+}
+
+/**
+ * One side of a match. `urn` is the server's competitor URN
+ * (`od:competitor:N`); `logoUrl` is an https image URL, present only when
+ * the deployment resolves team logos and this team has one.
+ *
+ * A `logoUrl` can still fail to load (the CDN may not have the file), so
+ * always render a fallback for a missing or broken image. Allow the logo
+ * hosts (`cdn.oddin.gg`, and `cdn.runestone.gg`) in a CSP `img-src`.
+ */
+export declare interface CatalogTeam {
+    urn: string;
+    name: string;
+    isHome: boolean;
+    logoUrl?: string;
 }
 
 export declare interface CatalogTournament {
@@ -162,6 +185,15 @@ export declare interface CreatePlayerOptions {
      * playback has fallen well behind. Default: true. Live/LL only.
      */
     snapToLiveOnRefocus?: boolean;
+    /**
+     * DRM cold start: download the first init segment and parts while the
+     * first key is still being acquired, instead of after it (hls.js waits for
+     * the key before requesting any media). Bytes are handed to hls.js only
+     * when it asks for them, so nothing is appended earlier than before; only
+     * the network time leaves the critical path. Default: true. Ignored on
+     * clear streams, and when `hlsConfig.fLoader` is set.
+     */
+    mediaDuringKey?: boolean;
     /** Force an engine; 'auto' prefers hls.js wherever supported (incl. modern
      *  Safari/iOS via ManagedMediaSource) and falls back to native HLS. Default: 'auto'. */
     engine?: 'auto' | 'hls' | 'native';
@@ -660,11 +692,19 @@ export declare function licenseRequestHeaders(descriptor: StreamDescriptor, cred
  * the `/v1/playback` outcome ladder so a pushed event and a follow-up
  * `/v1/playback` call always agree:
  *   live     ↔ 200 OK         (a serveable session exists — play now)
- *   upcoming ↔ 425 Too Early  (scheduled, not serving yet)
+ *   upcoming ↔ 425 Too Early  (scheduled, not serving yet; `liveStartsAt` says when)
+ *   pending  ↔ 425 Too Early  (kickoff has passed, the stream is being packaged —
+ *                              no `liveStartsAt`; `live` follows within seconds
+ *                              to minutes)
  *   ended    ↔ 503            (was live; media stopped, still in catchup)
  *   gone     ↔ 410 Gone       (ended past the catchup window)
+ *
+ * `pending` and `upcoming` ask the same thing of a player — wait — and the
+ * managed player treats them alike ("Starting soon…"). A host that renders
+ * its own waiting UI can tell them apart: `upcoming` has a kickoff to count
+ * down to, `pending` means the match is on and media is seconds away.
  */
-export declare type LiveState = 'live' | 'upcoming' | 'ended' | 'gone';
+export declare type LiveState = 'live' | 'upcoming' | 'pending' | 'ended' | 'gone';
 
 export declare interface LiveStateEvent {
     matchUrn: string;
@@ -680,7 +720,13 @@ export declare interface LiveStateSubscription {
     close(): void;
 }
 
-export declare type MatchLiveStatus = 'upcoming' | 'live' | 'ended';
+/**
+ * `pending` is the catalog's "kickoff has passed, the stream is being
+ * packaged" — not playable yet, `live` expected within seconds to minutes. It
+ * is NOT `upcoming` (which has a kickoff ahead) and not `live` (nothing serves
+ * yet); `/v1/playback` answers `425` for it without a `liveStartsAt`.
+ */
+export declare type MatchLiveStatus = 'upcoming' | 'pending' | 'live' | 'ended';
 
 export declare interface MatchStatus {
     matchUrn: string;
@@ -694,6 +740,12 @@ export declare interface MatchStatus {
      */
     statusRaw?: string;
     datePlannedStart?: string;
+    /**
+     * The match's teams as of this report (see {@link CatalogTeam}).
+     * `watchStatus` fires again when they change, so a logo the server
+     * resolves after the first read is re-reported with the same status.
+     */
+    teams?: CatalogTeam[];
 }
 
 /**
@@ -1167,7 +1219,11 @@ export declare interface WatchStatusOptions {
     baseUrl: string;
     matchUrn: string;
     credential: CredentialSource;
-    /** Fired whenever the status changes (and once on first read). */
+    /**
+     * Fired once on first read and then whenever the status, the teams (a logo
+     * resolved after the first read) or the planned start change. Unchanged
+     * polls (304 or an identical body) stay silent.
+     */
     onChange: (status: MatchStatus) => void;
     /** Fired on a poll error; polling continues. */
     onError?: (err: PlaybackError) => void;