@oddin-gg/havik-player 2.7.0 → 2.9.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;
     /**
@@ -321,6 +373,23 @@ export declare interface EmbedConfig {
     autoplay?: boolean;
     muted?: boolean;
     waitForLive?: WaitForLive;
+    /**
+     * QoE beacons, forwarded verbatim to {@link createPlayer}. Same meaning as
+     * there: `false` opts out, `{ endpoint }` names a beacons host.
+     *
+     * Mode C needs this for the same reason Mode A does, and until now had no
+     * way to say it. An embed whose `baseUrl` is not a `feed[-dev].<domain>`
+     * host — a CDN or gateway fronting the streams API — derives no beacons
+     * endpoint, so analytics is off and stays off. Without this option the
+     * only remedy was to move `baseUrl` back onto a feed host, which is not a
+     * choice an integrator who fronts the API deliberately can make.
+     *
+     * INJECTED CONFIG ONLY: unlike every other field here, this is not read
+     * from the query string. See {@link readConfig}.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 export declare interface EmbedHandle {
@@ -477,6 +546,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;
@@ -611,6 +690,18 @@ export declare interface MountEmbedOptions {
     container: HTMLElement;
     /** URL of the hosted embed page, e.g. `https://player-dev.oddin-video.gg/embed/`. */
     src: string;
+    /**
+     * API base URL, forwarded to the embed page as a query parameter.
+     *
+     * ⚠️ QoE beacons: the beacons endpoint is derived from this host by
+     * convention (`feed[-dev].<domain>` → `beacons[-dev].<domain>`). If your
+     * base is NOT a feed host, nothing derives and analytics is off — and
+     * `mountEmbed` CANNOT fix it, because the only way to name an endpoint is
+     * {@link EmbedConfig.analytics}, which the embed page reads from injected
+     * config and deliberately never from the query string (a link must not be
+     * able to redirect a session's telemetry). Host the embed page yourself
+     * and inject `window.HAVIK_EMBED_CONFIG` with `analytics: { endpoint }`.
+     */
     baseUrl: string;
     matchUrn: 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;
     /**
@@ -321,6 +373,23 @@ export declare interface EmbedConfig {
     autoplay?: boolean;
     muted?: boolean;
     waitForLive?: WaitForLive;
+    /**
+     * QoE beacons, forwarded verbatim to {@link createPlayer}. Same meaning as
+     * there: `false` opts out, `{ endpoint }` names a beacons host.
+     *
+     * Mode C needs this for the same reason Mode A does, and until now had no
+     * way to say it. An embed whose `baseUrl` is not a `feed[-dev].<domain>`
+     * host — a CDN or gateway fronting the streams API — derives no beacons
+     * endpoint, so analytics is off and stays off. Without this option the
+     * only remedy was to move `baseUrl` back onto a feed host, which is not a
+     * choice an integrator who fronts the API deliberately can make.
+     *
+     * INJECTED CONFIG ONLY: unlike every other field here, this is not read
+     * from the query string. See {@link readConfig}.
+     */
+    analytics?: boolean | {
+        endpoint?: string;
+    };
 }
 
 export declare interface EmbedHandle {
@@ -477,6 +546,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;
@@ -611,6 +690,18 @@ export declare interface MountEmbedOptions {
     container: HTMLElement;
     /** URL of the hosted embed page, e.g. `https://player-dev.oddin-video.gg/embed/`. */
     src: string;
+    /**
+     * API base URL, forwarded to the embed page as a query parameter.
+     *
+     * ⚠️ QoE beacons: the beacons endpoint is derived from this host by
+     * convention (`feed[-dev].<domain>` → `beacons[-dev].<domain>`). If your
+     * base is NOT a feed host, nothing derives and analytics is off — and
+     * `mountEmbed` CANNOT fix it, because the only way to name an endpoint is
+     * {@link EmbedConfig.analytics}, which the embed page reads from injected
+     * config and deliberately never from the query string (a link must not be
+     * able to redirect a session's telemetry). Host the embed page yourself
+     * and inject `window.HAVIK_EMBED_CONFIG` with `analytics: { endpoint }`.
+     */
     baseUrl: string;
     matchUrn: string;
     /**