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;
}

/**
 * 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
 * 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;

/**
 * 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 & {
    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;
    /**
     * 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;
    /**
     * Start playback once ready. Default: true. With false the player resolves
     * playback, then holds in a pre-play 'paused' state (poster + play card,
     * no spinner) and defers media loading — segments and DRM license traffic —
     * until the first play(). The hls.js engine still parses the manifest
     * pre-play ('ready', track lists); the native engine defers all fetching
     * and emits 'ready' at attach. A policy-blocked programmatic play()
     * ('autoplayblocked') leaves the loader warming the buffer — media and DRM
     * traffic flows from that kick, not from a viewer gesture.
     */
    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: 2 (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' prefers hls.js wherever supported (incl. modern
     *  Safari/iOS via ManagedMediaSource) and falls back to native HLS. 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 shown instead of {@link endedMessage} when the stream stopped but
     * the match is still running (the server's `interrupted` reason — an ingest
     * outage that outlived the bridge's reconnect hold). Default:
     * "Reconnecting — please stand by" — a promise the player keeps while
     * {@link rejoinOnLive} is on (the default; it also needs
     * {@link liveStateEvents}). Override it if you disable auto-rejoin, since
     * nothing will then re-attach on its own.
     */
    interruptedMessage?: string;
    /** Message on the fatal-error card. Default: the error's own message. */
    errorMessage?: string;
    /**
     * Turn on hls.js's internal console logging — segment/part scheduling, ABR
     * switches, and EME key-session + license traffic. Default: false.
     *
     * For diagnosing a playback problem with Oddin support; leave it off in
     * production (it logs on every fragment, and the EME lines include license
     * request/response metadata). hls.js engine only — a no-op on the native
     * engine, which has no equivalent. Equivalent to `hlsConfig: { debug: true }`,
     * which still wins if you set both.
     */
    debug?: boolean;
    /** Escape hatch for low-level hls.js tuning. */
    hlsConfig?: Partial<HlsConfig>;
    /** Stats sampling cadence. Default: 2000ms. */
    statsIntervalMs?: number;
    /**
     * How often to silently re-resolve playback so the signed DRM license URL
     * the player would use next stays inside its signature lifetime (~10 min).
     * Default: 8 min. Set 0 to disable.
     *
     * This refreshes the URL, not the license. It gives the player a newer URL
     * for the next license request it makes, and issues none of its own, so it
     * cannot extend a license the CDM already holds: how long that stays valid
     * is set when it is issued, server-side. A session that outlasts its license
     * ends with a fatal `DRM_CLIENT` error whatever this is set to.
     */
    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`; a later pushed `live`
     * rejoins automatically (see {@link rejoinOnLive}). 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;
    /**
     * Rejoin automatically when a stream that ended comes back live. An ingest
     * outage longer than the bridge's reconnect grace tears the session down
     * and — when the encoder reconnects — recreates it under a NEW manifest
     * URL, while the old playlist freezes at HTTP 200 forever. A player that
     * latched `ended` can therefore only recover by re-resolving playback.
     * With this on (the default), the live-state subscription stays open after
     * `ended` (it closes on `gone`, the past-catchup terminal), and a pushed
     * `live` re-arms and re-attaches automatically through the same jittered
     * go-live path the pre-live wait uses. Set false to keep `ended` terminal
     * (the pre-1.13 behavior). No effect when {@link liveStateEvents} is
     * disabled — without the push channel there is nothing to rejoin on.
     */
    rejoinOnLive?: 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;
    /**
     * Extra headers attached to every request the SDK makes to {@link baseUrl}
     * (playback resolution, live-status polling) — and ONLY there: never to
     * CDN manifest/segment hosts, DRM license endpoints, the SSE events host,
     * or the beacons endpoint. For integrations whose API front door wants
     * its own auth signal on top of the publishable key — an operator console
     * proving a session to its reverse proxy, or a customer gateway in front
     * of the streams API. `x-api-key` cannot be overridden through this map.
     */
    apiHeaders?: Record<string, string>;
    /**
     * QoE beacons + CMCD session attribution. Active only when the playback
     * response carries an analytics sid (the server-side flag) — without one
     * this option does nothing. Default: true, with the beacons endpoint
     * derived from {@link baseUrl} by hostname convention (`feed[-dev].…` →
     * `beacons[-dev].…`). Pass `false` to opt out entirely, or
     * `{ endpoint }` to point at a non-conventional beacons host.
     *
     * If {@link baseUrl} is NOT a `feed[-dev].<domain>` host — a CDN or gateway
     * fronting the streams API, say — nothing can be derived and beacons are
     * disabled. That is reported, not silent: a `console.warn` naming the host
     * (once per host) plus a non-fatal `warning` event. Supply `{ endpoint }`.
     *
     * Privacy: the sid is an opaque per-session id, held in memory only and
     * never persisted. Beacons carry playback QoE numbers plus the session's
     * environment (form factor, device model and OS version where the browser
     * offers client hints, screen, connection, embedding origin) — never an
     * IP, never the raw user agent, and no identifier beyond the sid.
     */
    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;
    };
}

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;

/**
 * Probe whether DRM playback can work here. Resolves — never rejects.
 *
 * Call it lazily (only for content whose descriptor says `drmEnabled`), CACHE
 * the result yourself (probes are not memoized, and the EME spec allows each
 * call to show consent prompts / trigger CDM downloads), and treat
 * 'supported' as necessary-not-sufficient: the licence server, CORS
 * onboarding and content packaging still have to cooperate.
 */
export declare function detectDrmSupport(opts?: DetectDrmSupportOptions): Promise<DrmSupportResult>;

export declare interface DetectDrmSupportOptions {
    /** Systems to probe, in order. Default: both. */
    systems?: DrmSystem[];
    /** OVERALL budget for the whole call before concluding 'probe-timeout' —
     *  shared across every probed system/stage, not per probe. Default 5000ms. */
    timeoutMs?: number;
}

export declare interface DrmInfo {
    widevine?: WidevineInfo;
    fairplay?: FairPlayInfo;
}

export declare interface DrmSupportResult {
    verdict: DrmSupportVerdict;
    /** The first system that probed as working (when verdict is 'supported'). */
    system?: DrmSystem;
    /** Per-system outcome, for diagnostics/support bundles. */
    detail: Partial<Record<DrmSystem, string>>;
}

export declare type DrmSupportVerdict = 
/** At least one probed system produced working MediaKeys. */
'supported'
/** EME exists but no probed system yields a CDM (e.g. iOS third-party browsers). */
| 'no-cdm'
/** Not a secure context — EME is unavailable by spec (http://<LAN-IP> dev, etc.). */
| 'insecure-context'
/** SecurityError: permissions-policy / iframe allow="encrypted-media" missing. */
| 'blocked-by-policy'
/** The access promise never settled within timeoutMs (some WebViews). */
| 'probe-timeout';

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;
    /**
     * 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 {
    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;
}

/**
 * Why a stream ended (havik-streams #191). `ended` alone cannot tell a viewer
 * whether the MATCH finished or only its stream dropped — two situations that
 * deserve opposite messaging:
 *
 * - `interrupted` — the match is still running; no session is serving (an
 *   ingest outage that outlived the bridge's reconnect grace). Play is
 *   expected to resume, so surface "reconnecting", never "this has ended".
 * - `match_ended` — the match itself finished. A real end.
 *
 * Absent on every other state, and absent entirely from servers predating the
 * field — so treat `undefined` as "unknown, assume a real end" (what clients
 * did before it existed).
 */
export declare type EndedReason = 'interrupted' | 'match_ended';

/**
 * Enter fullscreen for `video`, walking the capability ladder above.
 * `container` is the element to present in element fullscreen (defaults to
 * the video) — pass your player wrapper to keep your own controls visible on
 * platforms that support it. Returns false when NO mechanism exists (some
 * webviews) so the caller can hide or disable its button; rejections from a
 * denied request (permissions policy) propagate.
 *
 * Call from a user gesture: every branch of the ladder requires one.
 */
export declare function enterVideoFullscreen(video: HTMLVideoElement, container?: HTMLElement): Promise<boolean>;

/**
 * Leave whichever fullscreen presentation `video` is in: iPhone's video-native
 * fullscreen first (it reports only through the video, never the document),
 * then element fullscreen via the document (unprefixed or prefixed). Safe to
 * call when not fullscreen — and scoped to THIS video's presentation: an
 * unrelated element's fullscreen (a lightbox, another player) is left alone,
 * mirroring the ownership check exitPictureInPicture makes on
 * pictureInPictureElement. Pass the same `container` you entered with.
 */
export declare function exitVideoFullscreen(video: HTMLVideoElement, container?: HTMLElement): Promise<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;
    /**
     * Extra headers attached to every request to {@link baseUrl} — and only
     * there: never to CDN or license hosts. `x-api-key` cannot be overridden.
     */
    apiHeaders?: Record<string, 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;
    /**
     * Extra headers attached to every request to {@link baseUrl} — and only
     * there: never to CDN or license hosts. `x-api-key` cannot be overridden.
     */
    apiHeaders?: Record<string, 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;

/**
 * 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;
    /** 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;
    /** Set only on `ended`; see {@link EndedReason}. */
    reason?: EndedReason;
    /** 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-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;
    /**
     * 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' | 'DRM_CLIENT' | '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;
    /**
     * TOTAL frames this session — the denominator dropped frames need, and it
     * ALREADY INCLUDES the dropped ones (it is
     * `VideoPlaybackQuality.totalVideoFrames`). So the ratio is
     * `droppedFrames / decodedFrames`, with nothing added to the bottom.
     *
     * The name says "decoded" because it is the wire field's name and a
     * contract rename is not worth a migration (plan D10). Read it as "total".
     */
    decodedFrames?: 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;
    /** Cumulative media segment bytes fetched this session (hls.js engine only). */
    bytesLoaded?: number;
    /** Cumulative manifest/playlist bytes fetched this session (hls.js engine only). */
    playlistBytesLoaded?: number;
    /** Cumulative ABR rendition switches this session (hls.js engine only). */
    renditionSwitches?: number;
    /** Bitrate of the current rendition in kbps, when known. */
    renditionBitrateKbps?: number;
    /** Duration of the most recent DRM license acquisition in ms (0 = none yet). */
    licenseTimeMs?: number;
    /** RFC 6381 codec strings of the current rendition. */
    videoCodec?: string;
    audioCodec?: string;
    /** The offered rendition ladder, ascending heights, and its top bitrate. */
    ladderHeights?: number[];
    ladderTopBitrateKbps?: number;
    /** DRM the engine negotiated for the session. */
    keySystem?: 'widevine' | 'fairplay' | 'none';
    /** Robustness requested/granted, e.g. Widevine L3 (software) on the web. */
    drmSecurityLevel?: string;
    /** The viewer pinned a quality; ABR is not deciding. */
    qualityPinned?: boolean;
    /** Cumulative ABR switch direction split (renditionSwitches = both). */
    upshifts?: number;
    downshifts?: number;
    /** Cumulative media requests completed / failed, and the durations of the
     *  most recent ones (ms, newest last, bounded) for interval percentiles. */
    requestCount?: number;
    requestErrors?: number;
    requestTimesMs?: number[];
    /** Host of the most recent media request — host only, never the path. */
    cdnHost?: string;
}

export declare interface Player {
    readonly state: PlayerState;
    readonly descriptor: StreamDescriptor | null;
    /** Why the stream ended, when the server said so; null otherwise. Cleared
     *  when fresh playback commits (including a rejoin). See EndedReason. */
    readonly endedReason: EndedReason | 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>;
    /**
     * Enter fullscreen: element fullscreen on the player container where the
     * API exists (custom controls stay on screen); on iPhone Safari falls back
     * to the video-native presentation with NATIVE controls (there is no
     * element Fullscreen API there at all). Call from a user gesture; on
     * iPhone it takes effect once media is loaded. Resolves false when no
     * fullscreen mechanism exists on the platform.
     */
    enterFullscreen(): Promise<boolean>;
    /** Leave fullscreen (element or video-native). Safe when not fullscreen. */
    exitFullscreen(): 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;
    /**
     * End of stream. The payload says WHY when the server told us
     * (`interrupted` = the match is still running and play should resume, so
     * do NOT say "ended"; `match_ended` = a real end); `undefined` means the
     * end came from the HLS staleness watchdog or a server predating the
     * field — treat it as a real end, the pre-existing behavior. Fires again
     * with `match_ended` if an interruption later turns out to be the end.
     */
    ended: EndedReason | undefined;
    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 — `https://feed.oddin-video.gg`
     * (production) or `https://feed-dev.oddin-video.gg` (integration). Prefer
     * resolving it from the endpoint directory at runtime over hard-coding it;
     * see Service URL discovery in the API reference.
     */
    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;
    /**
     * Extra headers attached to every request this call makes to {@link baseUrl}
     * — and ONLY there: never to CDN manifest/segment hosts or DRM license
     * endpoints. For integrations whose API front door wants its own auth
     * signal on top of the publishable key (gateways, operator consoles).
     * `x-api-key` cannot be overridden.
     */
    apiHeaders?: Record<string, string>;
}

/**
 * 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;
    /**
     * Analytics session binding minted by havik-streams (present when the
     * server has analytics enabled). The sid is an opaque per-playback-session
     * id — non-secret by design (DRM remains the access gate) — echoed in CMCD
     * query params on CDN requests and carried by QoE beacons. It lives only in
     * memory for the duration of the session and is never persisted.
     */
    analytics?: {
        sid?: string;
    };
    /** 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 connection that stops
 * delivering without closing is caught by the idle watchdog
 * (`idleTimeoutMs`) — see the note on it in `readStream`. 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;
    /**
     * How long a request may stay silent before it is treated as dead and
     * reconnected. Applies to both phases: waiting for response headers, and
     * waiting for the next byte on an open connection. Default 45000 — two
     * missed 20s server heartbeats. Set `0` to disable the watchdog (a silent
     * connection then stays open forever, which is what this subscription did
     * before the watchdog existed).
     */
    idleTimeoutMs?: 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;
}

/**
 * True while this video's fullscreen presentation is active: element
 * fullscreen on `container` or the video itself, or iPhone's video-native
 * fullscreen. Pass the same `container` you pass to enterVideoFullscreen.
 */
export declare function videoFullscreenActive(video: HTMLVideoElement, container?: HTMLElement): 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;
    /**
     * Extra headers attached to every request to {@link baseUrl} — and only
     * there: never to CDN or license hosts. `x-api-key` cannot be overridden.
     */
    apiHeaders?: Record<string, string>;
}

export declare interface WidevineInfo {
    licenseUrl: string;
}

export { }


declare global {
    interface Window {
        HAVIK_EMBED_CONFIG?: Partial<EmbedConfig>;
    }
}