@oddin-gg/havik-player 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,795 @@
+import { HlsConfig } from 'hls.js';
+
+/** Apply a (possibly partial) theme to a player root element as CSS variables. */
+export declare function applyTheme(root: HTMLElement, theme?: Partial<HavikTheme>): void;
+
+/** A selectable audio rendition. */
+export declare interface AudioTrackInfo {
+    id: number;
+    name: string;
+    lang?: string;
+    default: boolean;
+}
+
+/**
+ * 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
+ * trusted parentOrigin it neither accepts commands nor broadcasts events.
+ */
+export declare function bootEmbed(): Promise<void>;
+
+export declare interface Catalog {
+    tournaments: CatalogTournament[];
+    /** ETag for a cheap conditional refresh next time. */
+    etag?: string;
+    /** True when the server returned 304 (the prior etag is still fresh); tournaments is empty. */
+    notModified: boolean;
+}
+
+export declare interface CatalogMatch {
+    matchUrn: string;
+    matchName: string;
+    status: MatchLiveStatus;
+    datePlannedStart?: string;
+    tournamentUrn: string;
+    tournamentName: string;
+    sport: string;
+}
+
+export declare interface CatalogTournament {
+    urn: string;
+    name: string;
+    sport: string;
+    isOffline: boolean;
+    matches: CatalogMatch[];
+}
+
+/**
+ * Clear the persisted device id (localStorage + in-memory cache). The next
+ * getDeviceId() generates a fresh one. Provide this to viewers as a privacy /
+ * "reset my device identifier" control — the device id is sent as X-Device-Id
+ * on every DRM license request and persists across sessions.
+ */
+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.
+ */
+export declare function createPlayer(opts: CreatePlayerOptions): Promise<Player>;
+
+export declare interface CreatePlayerOptions {
+    /** The <video> element the SDK will own. */
+    video: HTMLVideoElement;
+    baseUrl: string;
+    matchUrn: string;
+    credential: CredentialSource;
+    /** Start playback once ready. Default: true. */
+    autoplay?: boolean;
+    /** Mute the element (required for reliable autoplay with sound policies). Default: false. */
+    muted?: boolean;
+    /** Arm on an upcoming match and auto-attach at go-live. See WaitForLive. */
+    waitForLive?: WaitForLive;
+    /** 'auto' lets hls.js decide from the manifest (safe default). Default: 'auto'. */
+    lowLatency?: 'auto' | boolean;
+    /** Poster image shown before playback starts. */
+    poster?: string;
+    /** Initial rendition index (-1 = auto, the default). */
+    startLevel?: number;
+    /** Cap ABR to renditions at/below this bitrate (bps). */
+    maxBitrate?: number;
+    /**
+     * Target live-edge latency in seconds (maps to hls.js liveSyncDuration).
+     * Default: 3 (a balance the engine ships — close to live but back from the
+     * bleeding PART-HOLD-BACK edge, where parts aren't reliably published yet).
+     * Lower = closer to live but more rebuffer-prone; higher = steadier. The
+     * engine derives a matching latency ceiling internally, so this is the only
+     * live-latency knob you need. Live/LL only.
+     */
+    liveLatencyTarget?: number;
+    /**
+     * Snap straight to the live edge when a backgrounded tab is refocused and
+     * playback has fallen well behind. Default: true. Live/LL only.
+     */
+    snapToLiveOnRefocus?: boolean;
+    /** Force an engine; 'auto' picks native HLS on Safari, hls.js elsewhere. Default: 'auto'. */
+    engine?: 'auto' | 'hls' | 'native';
+    /** Optional viewer id (X-User-Id on the license POST). */
+    userId?: string;
+    /**
+     * Which controls to render:
+     *  - 'custom' (default): the Oddin-branded, skinnable control bar.
+     *  - 'native': the browser's built-in `<video controls>` UI.
+     *  - 'none': no controls (drive the player via its API).
+     */
+    controls?: 'custom' | 'native' | 'none';
+    /**
+     * Re-skin the custom control bar. Merged over the Oddin default; any omitted
+     * key keeps the brand value. Equivalent to overriding the `--havik-*` CSS
+     * variables on the player element. Ignored unless controls is 'custom'.
+     */
+    theme?: Partial<HavikTheme>;
+    /**
+     * Show branded full-bleed cards for the stopped/pre-play states — ended
+     * ("This stream has ended"), fatal error (message + Retry when retryable),
+     * pre-play (poster + play CTA), and armed-waiting ("Starting soon…") — instead
+     * of a frozen frame + a dead play button. Themed via the control-bar tokens +
+     * `theme.logoUrl`. Default: true. Set false if you render your own end/error
+     * UI from the player events (`ended`, `error`). Ignored unless controls is
+     * 'custom'.
+     */
+    statusOverlays?: boolean;
+    /** Message on the end-of-stream card. Default: "This stream has ended". */
+    endedMessage?: string;
+    /** Message on the fatal-error card. Default: the error's own message. */
+    errorMessage?: string;
+    /** Escape hatch for low-level hls.js tuning. */
+    hlsConfig?: Partial<HlsConfig>;
+    /** Stats sampling cadence. Default: 2000ms. */
+    statsIntervalMs?: number;
+    /**
+     * How often to silently refresh the signed DRM license URL for long live
+     * sessions (the HMAC expires ~10min). Default: 8min. Set 0 to disable.
+     */
+    licenseRefreshMs?: number;
+    /**
+     * Subscribe to push-based live-state over SSE (`events.<domain>/v1/events/{urn}`)
+     * to detect end-of-stream the instant the bridge flips, instead of waiting on
+     * the frozen Tencent manifest (which never emits #EXT-X-ENDLIST). On `ended`/
+     * `gone` the player stops buffering and emits `ended`. Default: true — and
+     * fully graceful: if the endpoint is unreachable the subscription retries
+     * quietly in the background while the HLS staleness watchdog remains the
+     * layer-fallback, so playback is never affected. Set false to disable.
+     */
+    liveStateEvents?: boolean;
+    /**
+     * Override the SSE endpoint base URL. Default: derived from {@link baseUrl} by
+     * prefixing the host with `events.` (e.g. `feed.<domain>` →
+     * `events.<domain>`, served ALB-direct). Set this if your events subdomain
+     * differs from that convention.
+     */
+    eventsBaseUrl?: string;
+}
+
+declare interface Credential_2 {
+    /** A publishable api-key, e.g. `pk_live_…` / `pk_test_…`. */
+    apiKey: string;
+}
+export { Credential_2 as Credential }
+
+/**
+ * A credential, or a function that produces one. The function form lets a host
+ * plug in a future short-lived-token mint service without an API change; it is
+ * invoked per request so refresh works transparently.
+ */
+export declare type CredentialSource = Credential_2 | (() => Credential_2 | Promise<Credential_2>);
+
+/**
+ * Derive the SSE endpoint base from the API base by prefixing the host with
+ * `events.` — matching the deployed convention (`feed.<domain>` →
+ * `events.<domain>`, served ALB-direct because CloudFront can't stream SSE).
+ * Returns `undefined` if `baseUrl` can't be parsed.
+ */
+export declare function deriveEventsBaseUrl(baseUrl: string): string | undefined;
+
+export declare interface DrmInfo {
+    widevine?: WidevineInfo;
+    fairplay?: FairPlayInfo;
+}
+
+export declare type DrmSystem = 'widevine' | 'fairplay';
+
+export declare interface EmbedConfig {
+    baseUrl: string;
+    matchUrn: string;
+    /** DEV/DEMO ONLY when read from the query string — in production inject server-side. */
+    apiKey: string;
+    /** Origin to post events to and accept commands from. Required for the bridge. */
+    parentOrigin?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    waitForLive?: WaitForLive;
+}
+
+export declare interface EmbedHandle {
+    readonly iframe: HTMLIFrameElement;
+    play(): void;
+    pause(): void;
+    setMuted(muted: boolean): void;
+    setVolume(volume: number): void;
+    setQuality(index: number): void;
+    setMaxBitrate(bitrate: number | null): void;
+    setAudioTrack(id: number): void;
+    setTextTrack(id: number): void;
+    seekToLive(): void;
+    enterPip(): void;
+    exitPip(): void;
+    retry(): void;
+    load(matchUrn: string): void;
+    on(cb: (msg: FrameToHost) => void): () => void;
+    destroy(): void;
+}
+
+export declare interface FairPlayInfo {
+    licenseUrl: string;
+    certificateUrl: string;
+}
+
+/** GET /v1/catalog — metadata only (no manifest/DRM). Supports conditional refresh. */
+export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<Catalog>;
+
+export declare interface FetchCatalogOptions {
+    baseUrl: string;
+    credential: CredentialSource;
+    signal?: AbortSignal;
+    /** Prior ETag for a conditional GET (304 when unchanged). */
+    etag?: string;
+    status?: MatchLiveStatus | MatchLiveStatus[];
+    sport?: string;
+}
+
+/**
+ * `GET /v1/tournaments/{urn}` — single-tournament metadata (matches included,
+ * never any signed/per-viewer URLs; those live on `/v1/playback/{urn}`).
+ *
+ * Returns `notFound: true` on 404 (unknown URN OR caller-not-entitled — the
+ * server intentionally collapses both so existence isn't leaked). Other waitable
+ * statuses (5xx) reject as a typed `PlaybackError`. Supports ETag/304.
+ */
+export declare function fetchTournament(opts: FetchTournamentOptions): Promise<TournamentResult>;
+
+export declare interface FetchTournamentOptions {
+    baseUrl: string;
+    credential: CredentialSource;
+    /** Tournament URN, e.g. `od:tournament:42`. */
+    urn: string;
+    signal?: AbortSignal;
+    /** Prior ETag for a conditional GET (304 when unchanged) — only effective once havik-streams ETags `/v1/tournaments/{urn}` (parity with `/v1/matches/{urn}`). */
+    etag?: string;
+}
+
+/** Flatten a Catalog to a single match list (handy for grids). */
+export declare function flattenMatches(catalog: Catalog): CatalogMatch[];
+
+/** Events the iframe sends up to the host page. */
+export declare type FrameToHost = {
+    type: 'oddin:ready';
+    protocol: number;
+} | {
+    type: 'oddin:autoplayblocked';
+} | {
+    type: 'oddin:state';
+    state: PlayerState;
+} | {
+    type: 'oddin:waiting';
+    retryInMs: number;
+    attempt: number;
+    phase: string;
+} | {
+    type: 'oddin:tracks';
+    quality: QualityLevel[];
+    audio: AudioTrackInfo[];
+    text: TextTrackInfo[];
+} | {
+    type: 'oddin:qualitychange';
+    index: number;
+} | {
+    type: 'oddin:audiotrackchange';
+    id: number;
+} | {
+    type: 'oddin:texttrackchange';
+    id: number;
+} | {
+    type: 'oddin:stats';
+    droppedFrames: number;
+    latencySeconds?: number;
+    bandwidthKbps?: number;
+    levelHeight?: number;
+    lowLatency?: boolean;
+    isLive?: boolean;
+    atLiveEdge?: boolean;
+} | {
+    type: 'oddin:error';
+    code: PlaybackErrorCode;
+    message: string;
+};
+
+export declare function getDeviceId(): string;
+
+export declare interface HavikTheme {
+    /** Primary accent (play button, progress fill, live dot, focus). */
+    accent: string;
+    /** Text/icon color that sits ON the accent (e.g. on the play button). */
+    accentText: string;
+    /** Letterbox / behind-video background. */
+    background: string;
+    /** Control bar + menu surface color. */
+    surface: string;
+    /** Hover/active surface color. */
+    surfaceMuted: string;
+    /** Primary text/icon color. */
+    text: string;
+    /** Secondary text color (timestamps, inactive). */
+    textMuted: string;
+    /** Hairline borders. */
+    border: string;
+    /** Corner radius for buttons/menus. */
+    radius: string;
+    /** Font stack for control-bar text. */
+    fontFamily: string;
+    /** Optional logo shown as a small corner watermark (URL). */
+    logoUrl?: string;
+}
+
+/** Commands the host page sends down to the iframe. */
+export declare type HostToFrame = {
+    type: 'oddin:play';
+} | {
+    type: 'oddin:pause';
+} | {
+    type: 'oddin:setMuted';
+    muted: boolean;
+} | {
+    type: 'oddin:setVolume';
+    volume: number;
+} | {
+    type: 'oddin:setQuality';
+    index: number;
+} | {
+    type: 'oddin:setMaxBitrate';
+    bitrate: number | null;
+} | {
+    type: 'oddin:setAudioTrack';
+    id: number;
+} | {
+    type: 'oddin:setTextTrack';
+    id: number;
+} | {
+    type: 'oddin:seekToLive';
+} | {
+    type: 'oddin:enterPip';
+} | {
+    type: 'oddin:exitPip';
+} | {
+    type: 'oddin:retry';
+} | {
+    type: 'oddin:load';
+    matchUrn: string;
+} | {
+    type: 'oddin:destroy';
+};
+
+export declare function isLowLatencyManifest(playlistText: string): boolean;
+
+export declare function isOddinMessage(data: unknown): data is {
+    type: string;
+};
+
+export declare interface LicenseHeaderOptions {
+    /** Override the persistent device id (defaults to getDeviceId()). */
+    deviceId?: string;
+    /** Optional viewer id, forwarded as X-User-Id for billing/tracking. */
+    userId?: string;
+}
+
+/**
+ * Headers a host player must attach to the DRM license POST. The license URL
+ * itself must be sent VERBATIM (its signed query string is the token) — these
+ * headers are the rest of the contract:
+ *   - x-api-key   : the SAME key used to resolve playback (cid binding)
+ *   - X-Device-Id : required, persistent
+ *   - X-Match-Urn : advisory (the signed `m` param is authoritative)
+ *   - X-User-Id   : optional
+ * Body must be the raw EME challenge bytes (application/octet-stream).
+ */
+export declare function licenseRequestHeaders(descriptor: StreamDescriptor, credential: Credential_2, opts?: LicenseHeaderOptions): Record<string, string>;
+
+/**
+ * Coarse, player-facing live state pushed by havik-streams over SSE. Mirrors
+ * 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)
+ *   ended    ↔ 503            (was live; media stopped, still in catchup)
+ *   gone     ↔ 410 Gone       (ended past the catchup window)
+ */
+export declare type LiveState = 'live' | 'upcoming' | 'ended' | 'gone';
+
+export declare interface LiveStateEvent {
+    matchUrn: string;
+    state: LiveState;
+    /** RFC3339 server timestamp the transition was stamped at. */
+    serverTime: string;
+}
+
+export declare interface LiveStateSubscription {
+    /** Stop the subscription and abort the in-flight request. Idempotent. */
+    close(): void;
+}
+
+export declare type MatchLiveStatus = 'upcoming' | 'live' | 'ended';
+
+export declare interface MatchStatus {
+    matchUrn: string;
+    matchName?: string;
+    status: MatchLiveStatus;
+    datePlannedStart?: string;
+}
+
+/**
+ * Mode C — mount the hosted iframe player and bridge it over postMessage. Both
+ * ends verify event.origin on every message; commands are posted only to the
+ * embed page's origin.
+ */
+export declare function mountEmbed(opts: MountEmbedOptions): EmbedHandle;
+
+export declare interface MountEmbedOptions {
+    /** Element to mount the iframe into. */
+    container: HTMLElement;
+    /** URL of the hosted embed page, e.g. https://player.oddin.gg/embed/. */
+    src: string;
+    baseUrl: string;
+    matchUrn: string;
+    /**
+     * DEV/DEMO ONLY: appended as a query param so the embed page can read it.
+     * In production the embed page is hosted by you and injects the key
+     * server-side — do not pass it here.
+     */
+    apiKey?: string;
+    /** Origin of the embed page used to verify its messages. Defaults to new URL(src).origin. */
+    allowedFrameOrigin?: string;
+    muted?: boolean;
+    /**
+     * iframe sandbox attribute. Default keeps playback + EME + fullscreen working
+     * while blocking top-frame navigation and popups. Override only if you know
+     * what you're doing.
+     */
+    sandbox?: string;
+    /** Convenience callback for every event from the iframe. */
+    onEvent?: (msg: FrameToHost) => void;
+}
+
+/**
+ * Default skin — Oddin.gg brand identity: gold accent on dark navy, white text.
+ */
+export declare const ODDIN_THEME: HavikTheme;
+
+export declare class PlaybackError extends Error {
+    readonly code: PlaybackErrorCode;
+    readonly httpStatus: number;
+    /** Present for TOO_EARLY / RATE_LIMITED / UNAVAILABLE when the server sent Retry-After. */
+    readonly retryAfterMs?: number;
+    /** Server request id, when surfaced — useful for correlating opaque 403/503 in server logs. */
+    readonly requestId?: string;
+    /** Raw server error code (e.g. "TOO_EARLY"), preserved even if `code` maps it to a known enum. */
+    readonly serverCode?: string;
+    /**
+     * Scheduled kickoff time (epoch ms), if the server carried `liveStartsAt` on
+     * a TOO_EARLY body. `pollToLive` reads this to widen poll cadence for
+     * far-future matches.
+     */
+    readonly liveStartsAtMs?: number;
+    constructor(code: PlaybackErrorCode, httpStatus: number, message: string, init?: PlaybackErrorInit);
+}
+
+export declare type PlaybackErrorCode = 'INVALID_URN' | 'NOT_FOUND' | 'GONE' | 'TOO_EARLY' | 'UNAVAILABLE' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'RATE_LIMITED' | 'INTERNAL' | 'NETWORK' | 'TIMEOUT' | 'ABORTED';
+
+export declare interface PlaybackErrorInit {
+    retryAfterMs?: number;
+    requestId?: string;
+    /** The raw server-provided error code string, if any — forward-compatible with new server codes. */
+    serverCode?: string;
+    /**
+     * Scheduled kickoff time (epoch ms), if the server included it on a TOO_EARLY
+     * response body. The SDK uses this to widen poll cadence for far-future
+     * matches without a separate catalog call.
+     */
+    liveStartsAtMs?: number;
+    cause?: unknown;
+}
+
+export declare interface PlaybackStats {
+    droppedFrames: number;
+    /** Live-edge latency in seconds (hls.js engine only). */
+    latencySeconds?: number;
+    /** The live-sync target latency hls.js is converging to, in seconds. Compare
+     *  against latencySeconds to see drift. */
+    targetLatencySeconds?: number;
+    /** Estimated bandwidth in kbps (hls.js engine only). */
+    bandwidthKbps?: number;
+    /** Height of the current rendition, when known. */
+    levelHeight?: number;
+    /** Whether the stream is being played in low-latency mode. */
+    lowLatency?: boolean;
+    /** Whether the current media playlist is live. */
+    isLive?: boolean;
+    /** Whether playback is at/near the live edge (within the live sync window). */
+    atLiveEdge?: boolean;
+}
+
+export declare interface Player {
+    readonly state: PlayerState;
+    readonly descriptor: StreamDescriptor | null;
+    play(): Promise<void>;
+    pause(): void;
+    setMuted(muted: boolean): void;
+    setVolume(volume: number): void;
+    getStats(): PlaybackStats;
+    /** Available renditions (empty on the native engine, which does ABR internally). */
+    getQualityLevels(): QualityLevel[];
+    /** Current rendition index, or -1 when ABR is choosing automatically. */
+    getCurrentQuality(): number;
+    /** Pick a rendition by index, or 'auto'/-1 to re-enable ABR. */
+    setQuality(index: number | 'auto'): void;
+    /** Cap ABR to renditions at/below this bitrate (bps), or null to clear. */
+    setMaxBitrate(bitrate: number | null): void;
+    getAudioTracks(): AudioTrackInfo[];
+    setAudioTrack(id: number): void;
+    getTextTracks(): TextTrackInfo[];
+    /** Select a text track by id, or -1 to disable captions. */
+    setTextTrack(id: number): void;
+    /** Jump to the live edge (live streams). */
+    seekToLive(): void;
+    enterPictureInPicture(): Promise<void>;
+    exitPictureInPicture(): Promise<void>;
+    /** Retry playback after an error (re-resolves and re-attaches). */
+    retry(): Promise<void>;
+    /** Re-resolve playback (refreshes the signed license URL) and re-attach. */
+    reload(): Promise<void>;
+    on<E extends PlayerEvent>(event: E, cb: (payload: PlayerEventMap[E]) => void): () => void;
+    destroy(): void;
+}
+
+export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'stats' | 'statechange';
+
+export declare interface PlayerEventMap {
+    ready: void;
+    waiting: WaitState;
+    playing: void;
+    buffering: void;
+    paused: void;
+    ended: void;
+    error: PlaybackError;
+    /** Non-fatal condition (e.g. FairPlay-not-implemented passthrough, a failed license refresh). Playback continues. */
+    warning: PlaybackError;
+    /** The browser blocked autoplay (NotAllowedError). Prompt a tap-to-play / tap-to-unmute affordance. */
+    autoplayblocked: void;
+    /** Active rendition changed; payload is the level index (-1 = auto). */
+    qualitychange: number;
+    /** Active audio track changed; payload is the track id. */
+    audiotrackchange: number;
+    /** Active text track changed; payload is the track id (-1 = off). */
+    texttrackchange: number;
+    /** Picture-in-Picture entered (true) or exited (false). */
+    pipchange: boolean;
+    stats: PlaybackStats;
+    statechange: PlayerState;
+}
+
+export declare type PlayerState = 'idle' | 'waiting' | 'loading' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error';
+
+/**
+ * Poll `attempt` until it resolves, retrying on waitable PlaybackErrors
+ * (TOO_EARLY / UNAVAILABLE / RATE_LIMITED / NETWORK). Each retry's delay is
+ * computed by {@link nextDelayMs} from (a) the server's `Retry-After` (always a
+ * floor) and (b) the time-to-kickoff from `kickoffAt` and/or
+ * `PlaybackError.liveStartsAtMs`. Far from kickoff the cadence widens (to
+ * `~ttk/10`, capped at `sanityFloorMs`) so the SDK does not hammer the
+ * per-viewer `/v1/playback` endpoint when a viewer is armed hours early; inside
+ * the imminent window it collapses to the tight `[floorMs, ceilMs]` band so a
+ * 200 — i.e. the instant the match goes live — is caught fast. Terminal errors
+ * (404 / 410 / 400 / 401 / 403 / INTERNAL) reject straight away.
+ */
+export declare function pollToLive<T>(attempt: () => Promise<T>, cfg: WaitForLive, signal?: AbortSignal): Promise<T>;
+
+/** A selectable video rendition. */
+export declare interface QualityLevel {
+    /** Index into getQualityLevels() — pass to setQuality(). */
+    index: number;
+    width?: number;
+    height?: number;
+    bitrate: number;
+    codecs?: string;
+}
+
+export declare interface ResolveOptions {
+    /** Base URL of the havik-streams API, e.g. https://streams.oddin.gg. */
+    baseUrl: string;
+    matchUrn: string;
+    credential: CredentialSource;
+    /**
+     * When set, resolve retries internally on 425 TOO_EARLY honoring Retry-After
+     * and resolves the instant the stream is live. See WaitForLive.
+     */
+    waitForLive?: WaitForLive;
+    signal?: AbortSignal;
+}
+
+/**
+ * Resolve a match into a playback descriptor (manifest URL + DRM config). With
+ * `waitForLive`, blocks (politely, server-paced) until the stream is live.
+ */
+export declare function resolveStream(opts: ResolveOptions): Promise<StreamDescriptor>;
+
+export declare interface StatusWatcher {
+    stop(): void;
+}
+
+/**
+ * The per-match playback credential returned by `GET /v1/playback/{urn}`,
+ * normalized for the SDK. `manifestUrl` is an unsigned HLS `.m3u8`; the DRM
+ * license URLs are pre-signed by havik-streams (the signed query string IS the
+ * token — never rewrite them).
+ */
+export declare interface StreamDescriptor {
+    matchUrn: string;
+    protocol: 'hls';
+    /** Producer-set DRM decision. When false, init no EME/CDM at all. */
+    drmEnabled: boolean;
+    manifestUrl: string;
+    /** Present only when drmEnabled. */
+    drm?: DrmInfo;
+    serverTime: string;
+    /** Present only while the match is upcoming. */
+    liveStartsAt?: string;
+    /** Filled by the player once a media playlist with EXT-X-PART-INF is seen. */
+    isLowLatency?: boolean;
+    /** Any unrecognized top-level fields from the playback response (forward-compat). */
+    extensions?: Record<string, unknown>;
+}
+
+/**
+ * Subscribe to a match's live-state stream (`GET /v1/events/{urn}`).
+ *
+ * Uses `fetch` rather than the native `EventSource` because the endpoint
+ * authenticates with the `x-api-key` HEADER, which `EventSource` cannot set.
+ * The body is a `text/event-stream` we parse incrementally. The connection is
+ * long-lived (the server caps it at ~30min and sends heartbeats); on any
+ * close/error the client reconnects with exponential backoff and re-syncs from
+ * the initial snapshot the server replays on connect. A subscription failure
+ * is always non-fatal to playback — callers keep the HLS staleness watchdog as
+ * the layer-fallback.
+ */
+export declare function subscribeLiveState(opts: SubscribeLiveStateOptions): LiveStateSubscription;
+
+export declare interface SubscribeLiveStateOptions {
+    /** Base URL of the SSE endpoint, e.g. `https://events.feed.oddin-video.gg`. */
+    eventsBaseUrl: string;
+    matchUrn: string;
+    credential: CredentialSource;
+    /** Fired for the initial snapshot on connect and every subsequent transition. */
+    onState: (ev: LiveStateEvent) => void;
+    /**
+     * Fired on a non-fatal subscription problem (network drop, HTTP error,
+     * server lifetime-cap close). The client keeps retrying with backoff; this
+     * is observational only — it never tears playback down.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * Fired on EVERY received frame, including heartbeat comments — a liveness
+     * tick. Lets a caller treat the subscription as healthy (e.g. suspend
+     * polling) while frames keep arriving, and fall back when they stop.
+     */
+    onAlive?: () => void;
+    /** Reconnect backoff floor / ceiling (ms). Defaults: 1000 / 15000. */
+    minBackoffMs?: number;
+    maxBackoffMs?: number;
+}
+
+/** A selectable text (caption/subtitle) track. */
+export declare interface TextTrackInfo {
+    id: number;
+    name: string;
+    lang?: string;
+}
+
+export declare interface TournamentResult {
+    /** Present unless the tournament is unknown (404) or the server returned 304. */
+    tournament?: CatalogTournament;
+    /** ETag for a cheap conditional refresh next time, when the server emits one. */
+    etag?: string;
+    /** True when the server returned 304 (the prior etag is still fresh); `tournament` is undefined. */
+    notModified: boolean;
+    /** True when the URN is not in the catalog (or unknown to the caller's brand). */
+    notFound: boolean;
+}
+
+export declare type WaitForLive = boolean | WaitForLiveOptions;
+
+export declare interface WaitForLiveOptions {
+    /** Overall budget before giving up with a TIMEOUT error. Default: unbounded. */
+    timeoutMs?: number;
+    /** Minimum delay between polls. Floored at 1000ms (the server's min / limiter). Default: 1000. */
+    floorMs?: number;
+    /**
+     * Maximum delay between polls in the IMMINENT window (≤ {@link imminentMs}
+     * before kickoff). Far-from-kickoff polls are widened automatically using
+     * `kickoffAt` (see below) up to {@link sanityFloorMs}, regardless of this
+     * value — so this knob really controls only the near-kickoff cadence. Default: 30000.
+     */
+    ceilMs?: number;
+    /**
+     * Caller-supplied scheduled kickoff time (epoch ms, or an ISO string), used to
+     * widen the long-tail poll cadence so the SDK does not hammer the per-viewer
+     * `/v1/playback` endpoint when a viewer is armed hours early.
+     *
+     * Far-from-kickoff (time-to-kickoff > {@link imminentMs}) the poll interval is
+     * stretched to `min(ttk / 10, sanityFloorMs)` (never tighter than the server's
+     * `Retry-After`, never longer than {@link sanityFloorMs}, never longer than
+     * the time remaining to kickoff). Inside the imminent window the cadence
+     * collapses to the tight `[floorMs, ceilMs]` range so a 200 is caught fast.
+     *
+     * When omitted, the SDK also reads `liveStartsAt` off the 425 body if the
+     * server returns it (`PlaybackError.liveStartsAtMs`), so newer servers tune
+     * automatically without any client change.
+     */
+    kickoffAt?: number | string;
+    /**
+     * Threshold (ms) for "imminent kickoff" — inside this window the cadence
+     * collapses to the tight `[floorMs, ceilMs]` range. Default: 10 minutes.
+     */
+    imminentMs?: number;
+    /**
+     * Absolute hard ceiling on any single wait, even when far from kickoff or
+     * when the server returns a very large `Retry-After`. Sanity floor so an
+     * early go-live or a schedule change is caught within bounded latency.
+     * Default: 5 minutes (300_000ms).
+     */
+    sanityFloorMs?: number;
+    /** Add up to +15% jitter to each delay (never reduces below the server's ask). Default: true. */
+    jitter?: boolean;
+    /** Called before each wait with the upcoming retry. */
+    onState?: (state: WaitState) => void;
+}
+
+export declare interface WaitState {
+    phase: 'tooEarly' | 'unavailable' | 'rateLimited' | 'network';
+    /** How long until the next poll, in ms. */
+    retryInMs: number;
+    /** 1-based retry count. */
+    attempt: number;
+    /** Wall-clock ms since the wait started. */
+    elapsedMs: number;
+    /**
+     * Time-to-kickoff (ms) used to compute this delay, if known. `undefined` when
+     * no kickoff hint is available (caller didn't pass `kickoffAt` and the server
+     * didn't carry `liveStartsAt` on the error).
+     */
+    ttkMs?: number;
+}
+
+/**
+ * Poll `GET /v1/matches/{urn}` for the live status (there is no push channel),
+ * firing onChange on transitions. Uses ETag/If-None-Match so unchanged polls
+ * are cheap 304s. This drives discovery; actual readiness is the /v1/playback
+ * 200 (see resolveStream + waitForLive).
+ */
+export declare function watchStatus(opts: WatchStatusOptions): StatusWatcher;
+
+export declare interface WatchStatusOptions {
+    baseUrl: string;
+    matchUrn: string;
+    credential: CredentialSource;
+    /** Fired whenever the status changes (and once on first read). */
+    onChange: (status: MatchStatus) => void;
+    /** Fired on a poll error; polling continues. */
+    onError?: (err: PlaybackError) => void;
+    /** Poll interval in ms. Floored at 2000. Default: 10000 (catalog max-age). */
+    intervalMs?: number;
+}
+
+export declare interface WidevineInfo {
+    licenseUrl: string;
+}
+
+export { }
+
+
+declare global {
+    interface Window {
+        HAVIK_EMBED_CONFIG?: Partial<EmbedConfig>;
+    }
+}