@oddin-gg/havik-player 2.6.4 → 2.8.0

package/dist/index.d.cts

@@ -11,6 +11,23 @@ export declare interface AudioTrackInfo {
     default: boolean;
 }
 
+/**
+ * The API base URL for a named environment.
+ *
+ * Mode A takes {@link HavikEnv} directly (`createPlayer({ env: 'production' })`).
+ * Mode B and Mode C still take a `baseUrl`, so call this to get one rather
+ * than copying a hostname into your own config:
+ *
+ * ```ts
+ * resolveStream({ baseUrl: baseUrlForEnv('production'), matchUrn, credential });
+ * ```
+ *
+ * Throws on an unrecognized value rather than returning undefined — callers
+ * reach this from plain JS where the type gives no protection, and a silent
+ * undefined becomes a relative URL against the embedding page.
+ */
+export declare function baseUrlForEnv(env: HavikEnv): string;
+
 /**
  * Boots the iframe-side player and speaks the postMessage protocol with the host.
  * The api-key is NEVER accepted over postMessage. The bridge fails CLOSED: with no
@@ -53,18 +70,53 @@ export declare interface CatalogTournament {
 export declare function clearDeviceId(): void;
 
 /**
- * Mode A — managed player. Owns the <video> and a bundled hls.js, wiring
- * LL-HLS + DRM automatically. With `waitForLive`, arms on an upcoming match and
- * auto-plays the instant it goes live. Resolves to a Player as soon as it is
- * armed/attached — terminal errors (404/410/401/...) reject; the live wait does
- * not block and is surfaced via 'waiting' events.
+ * Endpoint selection, enforced at COMPILE time.
+ *
+ * `env` and `baseUrl` are both optional on {@link CreatePlayerOptions} so it
+ * stays an interface others can `extend` and `Partial<>`. That alone would
+ * make "neither given" type-check and fail only in the browser, which is a
+ * guarantee this SDK used to have while `baseUrl` was required. These two
+ * overloads put it back at the call site without changing the interface: one
+ * names `env` and forbids `baseUrl`, the other the reverse, so neither and
+ * both are both "no overload matches this call".
+ *
+ * resolveEndpoint still enforces the same rule at runtime — the overloads do
+ * nothing for a JavaScript caller, and that is most of the embed surface.
  */
-export declare function createPlayer(opts: CreatePlayerOptions): Promise<Player>;
+export declare function createPlayer(opts: CreatePlayerOptions & {
+    env: HavikEnv;
+    baseUrl?: never;
+}): Promise<Player>;
+
+export declare function createPlayer(opts: CreatePlayerOptions & {
+    baseUrl: string;
+    env?: never;
+}): Promise<Player>;
 
 export declare interface CreatePlayerOptions {
     /** The <video> element the SDK will own. */
     video: HTMLVideoElement;
-    baseUrl: string;
+    /**
+     * Which Oddin environment to play against. Prefer this over
+     * {@link baseUrl}: the host is then correct by construction, and so is
+     * everything derived from it (the SSE events host, the QoE beacons host).
+     *
+     * Exactly one of `env` or {@link baseUrl} is required. Passing both is an
+     * error rather than a precedence rule — the two disagreeing is precisely
+     * the misconfiguration worth refusing, and silently preferring one would
+     * point a player at an environment nobody chose.
+     */
+    env?: HavikEnv;
+    /**
+     * API base URL, when {@link env} does not name it. Use this for a
+     * deployment the named environments do not cover: your own CDN or gateway
+     * fronting the streams API, the CN plane, or a pinned build that must
+     * outlive a domain change.
+     *
+     * Note that a base which is not a `feed[-dev].<domain>` host derives no QoE
+     * beacons endpoint, so pair it with `analytics: { endpoint }`.
+     */
+    baseUrl?: string;
     matchUrn: string;
     credential: CredentialSource;
     /**
@@ -231,6 +283,16 @@ export declare interface CreatePlayerOptions {
      */
     analytics?: boolean | {
         endpoint?: string;
+        /**
+         * How long the player may sit paused before the session closes itself
+         * (`END_REASON_IDLE`), and the suspension gap (OS sleep, a frozen tab)
+         * after which it does the same on waking. Default 10 minutes; `0`
+         * disables the idle close; the suspension gap never goes below five
+         * minutes, whatever this is set to (a hidden tab's throttled timers
+         * legitimately gap to a minute). After an idle close the next play()
+         * reloads the stream — a fresh session, a fresh sid, the live edge.
+         */
+        idleMs?: number;
     };
 }
 
@@ -467,6 +529,16 @@ export declare type FrameToHost = {
 
 export declare function getDeviceId(): string;
 
+/**
+ * A named Oddin environment.
+ *
+ * - `integration` — the shared pre-production stack. Where customers build
+ *   and test against real matches.
+ * - `production` — the production stack. A separate distribution, not an
+ *   alias of integration.
+ */
+export declare type HavikEnv = 'integration' | 'production';
+
 export declare interface HavikTheme {
     /** Primary accent (play button, progress fill, live dot, focus). */
     accent: string;

package/dist/index.d.ts

@@ -11,6 +11,23 @@ export declare interface AudioTrackInfo {
     default: boolean;
 }
 
+/**
+ * The API base URL for a named environment.
+ *
+ * Mode A takes {@link HavikEnv} directly (`createPlayer({ env: 'production' })`).
+ * Mode B and Mode C still take a `baseUrl`, so call this to get one rather
+ * than copying a hostname into your own config:
+ *
+ * ```ts
+ * resolveStream({ baseUrl: baseUrlForEnv('production'), matchUrn, credential });
+ * ```
+ *
+ * Throws on an unrecognized value rather than returning undefined — callers
+ * reach this from plain JS where the type gives no protection, and a silent
+ * undefined becomes a relative URL against the embedding page.
+ */
+export declare function baseUrlForEnv(env: HavikEnv): string;
+
 /**
  * Boots the iframe-side player and speaks the postMessage protocol with the host.
  * The api-key is NEVER accepted over postMessage. The bridge fails CLOSED: with no
@@ -53,18 +70,53 @@ export declare interface CatalogTournament {
 export declare function clearDeviceId(): void;
 
 /**
- * Mode A — managed player. Owns the <video> and a bundled hls.js, wiring
- * LL-HLS + DRM automatically. With `waitForLive`, arms on an upcoming match and
- * auto-plays the instant it goes live. Resolves to a Player as soon as it is
- * armed/attached — terminal errors (404/410/401/...) reject; the live wait does
- * not block and is surfaced via 'waiting' events.
+ * Endpoint selection, enforced at COMPILE time.
+ *
+ * `env` and `baseUrl` are both optional on {@link CreatePlayerOptions} so it
+ * stays an interface others can `extend` and `Partial<>`. That alone would
+ * make "neither given" type-check and fail only in the browser, which is a
+ * guarantee this SDK used to have while `baseUrl` was required. These two
+ * overloads put it back at the call site without changing the interface: one
+ * names `env` and forbids `baseUrl`, the other the reverse, so neither and
+ * both are both "no overload matches this call".
+ *
+ * resolveEndpoint still enforces the same rule at runtime — the overloads do
+ * nothing for a JavaScript caller, and that is most of the embed surface.
  */
-export declare function createPlayer(opts: CreatePlayerOptions): Promise<Player>;
+export declare function createPlayer(opts: CreatePlayerOptions & {
+    env: HavikEnv;
+    baseUrl?: never;
+}): Promise<Player>;
+
+export declare function createPlayer(opts: CreatePlayerOptions & {
+    baseUrl: string;
+    env?: never;
+}): Promise<Player>;
 
 export declare interface CreatePlayerOptions {
     /** The <video> element the SDK will own. */
     video: HTMLVideoElement;
-    baseUrl: string;
+    /**
+     * Which Oddin environment to play against. Prefer this over
+     * {@link baseUrl}: the host is then correct by construction, and so is
+     * everything derived from it (the SSE events host, the QoE beacons host).
+     *
+     * Exactly one of `env` or {@link baseUrl} is required. Passing both is an
+     * error rather than a precedence rule — the two disagreeing is precisely
+     * the misconfiguration worth refusing, and silently preferring one would
+     * point a player at an environment nobody chose.
+     */
+    env?: HavikEnv;
+    /**
+     * API base URL, when {@link env} does not name it. Use this for a
+     * deployment the named environments do not cover: your own CDN or gateway
+     * fronting the streams API, the CN plane, or a pinned build that must
+     * outlive a domain change.
+     *
+     * Note that a base which is not a `feed[-dev].<domain>` host derives no QoE
+     * beacons endpoint, so pair it with `analytics: { endpoint }`.
+     */
+    baseUrl?: string;
     matchUrn: string;
     credential: CredentialSource;
     /**
@@ -231,6 +283,16 @@ export declare interface CreatePlayerOptions {
      */
     analytics?: boolean | {
         endpoint?: string;
+        /**
+         * How long the player may sit paused before the session closes itself
+         * (`END_REASON_IDLE`), and the suspension gap (OS sleep, a frozen tab)
+         * after which it does the same on waking. Default 10 minutes; `0`
+         * disables the idle close; the suspension gap never goes below five
+         * minutes, whatever this is set to (a hidden tab's throttled timers
+         * legitimately gap to a minute). After an idle close the next play()
+         * reloads the stream — a fresh session, a fresh sid, the live edge.
+         */
+        idleMs?: number;
     };
 }
 
@@ -467,6 +529,16 @@ export declare type FrameToHost = {
 
 export declare function getDeviceId(): string;
 
+/**
+ * A named Oddin environment.
+ *
+ * - `integration` — the shared pre-production stack. Where customers build
+ *   and test against real matches.
+ * - `production` — the production stack. A separate distribution, not an
+ *   alias of integration.
+ */
+export declare type HavikEnv = 'integration' | 'production';
+
 export declare interface HavikTheme {
     /** Primary accent (play button, progress fill, live dot, focus). */
     accent: string;