@oddin-gg/havik-player 1.0.2

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Oddin.gg
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# @oddin-gg/havik-player
+
+HTML5 player SDK for Oddin live streams — **LL-HLS + DRM** against the
+[havik-streams](https://github.com/oddin-gg/havik-streams) API, in three
+integration modes:
+
+| Mode                          | Entry                        | You provide            | SDK owns                                           |
+| ----------------------------- | ---------------------------- | ---------------------- | -------------------------------------------------- |
+| **A — Managed**               | `createPlayer()`             | a `<video>` element    | hls.js, LL-HLS, DRM/EME, retries                   |
+| **B — Bring-your-own-player** | `resolveStream()`            | the player + `<video>` | auth → catalog → playback resolution + DRM helpers |
+| **C — Iframe embed**          | `mountEmbed()` / hosted page | an iframe slot         | everything, behind a `postMessage` API             |
+
+Widevine (Chrome/Firefox/Edge/Android) is fully supported. Safari/iOS plays via
+native passthrough; full FairPlay EME is a tracked fast-follow. See [Limitations](#limitations).
+
+> 📖 **Full API reference:** [docs/API.md](docs/API.md) · **Examples** (vanilla / React / Vue): [examples/](examples/) · **API stability & versioning:** [docs/STABILITY.md](docs/STABILITY.md)
+
+> ⚠️ **Before you integrate — a server-side prerequisite that is out of your code's hands:**
+> the api-key's **AllowedOrigins** (and, for iframes, **AllowedIframeParents**) **and** the
+> DRM service's **CORS allow-list** must both include every origin you serve the player from,
+> or requests fail their preflight and DRM never starts. Onboard your origins with Oddin
+> first; allow a few minutes for propagation. Never use a `["*"]` allow-list in production.
+
+---
+
+## Install
+
+```bash
+npm install @oddin-gg/havik-player
+```
+
+Or via CDN (`<script>` / iframe), exposing `window.HavikPlayer`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player/dist/havik-player.global.js"></script>
+```
+
+You need two things to play a stream: a **match URN** (`od:match:…`) and a
+**publishable api-key** (`pk_live_…` / `pk_test_…`) whose **AllowedOrigins**
+includes the origin your player runs on. See [Auth & onboarding](#auth--onboarding).
+
+---
+
+## Mode A — Managed player
+
+The SDK owns the `<video>`, bundles hls.js, and wires LL-HLS + Widevine DRM.
+
+```ts
+import { createPlayer } from '@oddin-gg/havik-player';
+
+const player = await createPlayer({
+  video: document.querySelector('video')!,
+  baseUrl: 'https://streams.oddin.gg',
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_live_…' },
+  autoplay: true,
+  muted: true, // required for reliable autoplay
+  waitForLive: true, // arm on an upcoming match, auto-play at go-live
+});
+
+player.on('statechange', (s) => console.log('state', s)); // loading|waiting|playing|buffering|paused|ended|error
+player.on('waiting', (w) => console.log('go-live in', w.retryInMs, 'ms')); // armed countdown
+player.on('stats', (s) => console.log(s)); // dropped frames, latency, bitrate, level
+player.on('error', (e) => console.error(e.code, e.httpStatus, e.message));
+
+// later
+player.destroy();
+```
+
+The managed player handles `425 TOO_EARLY` retries (honoring `Retry-After`),
+buffering recovery, and silent DRM **license-URL refresh** for long sessions.
+
+### Controls & skinning
+
+Out of the box, Mode A renders a **branded, fully skinnable control bar** — seek,
+play/pause, volume, a live badge + go-live, quality / audio / subtitle menus,
+Picture-in-Picture, fullscreen, buffering + error/retry overlays, auto-hide, and
+keyboard a11y. Re-skin it to match your brand with a `theme` (or by overriding the
+`--havik-*` CSS variables); or opt out with `controls: 'native'` / `'none'`.
+
+```ts
+await createPlayer({
+  video,
+  baseUrl,
+  matchUrn,
+  credential: { apiKey },
+  controls: 'custom', // 'custom' (default, branded bar) | 'native' | 'none'
+  theme: { accent: '#14b8a6', surface: '#0f172a' }, // merged over the Oddin defaults
+});
+```
+
+See [Controls & theming](docs/API.md#controls--theming) for the full theme/CSS-variable reference.
+
+## Mode B — Bring your own player
+
+The SDK resolves the stream and gives you the DRM header helpers; you own the
+`<video>` and the playback engine.
+
+```ts
+import { resolveStream, licenseRequestHeaders, getDeviceId } from '@oddin-gg/havik-player';
+
+const cred = { apiKey: 'pk_live_…' };
+const stream = await resolveStream({
+  baseUrl: 'https://streams.oddin.gg',
+  matchUrn: 'od:match:1234',
+  credential: cred,
+  waitForLive: true,
+});
+
+// stream = { manifestUrl, drmEnabled, drm: { widevine: { licenseUrl } }, … }
+// Wire into YOUR player. For hls.js, attach the license headers in licenseXhrSetup
+// (NOT xhrSetup — EME license requests route through licenseXhrSetup):
+const headers = licenseRequestHeaders(stream, cred); // { 'x-api-key', 'X-Match-Urn', 'X-Device-Id', 'Content-Type' }
+```
+
+> **DRM rule:** POST to `drm.widevine.licenseUrl` **verbatim** — its signed query
+> string _is_ the token. Never rewrite/normalize the URL, and use the **same
+> api-key** on playback and license requests or the license 403s.
+
+Discovery helpers (there is no push channel — polling only):
+
+```ts
+import { fetchCatalog, watchStatus } from '@oddin-gg/havik-player';
+
+const catalog = await fetchCatalog({ baseUrl, credential: cred }); // tournaments → matches (metadata only)
+const watcher = watchStatus({
+  baseUrl,
+  matchUrn,
+  credential: cred,
+  onChange: (m) => console.log(m.status),
+});
+// watcher.stop();
+```
+
+## Mode C — Iframe embed
+
+Drop in the hosted player page and control it over `postMessage`:
+
+```ts
+import { mountEmbed } from '@oddin-gg/havik-player';
+
+const embed = mountEmbed({
+  container: document.querySelector('#player')!,
+  src: 'https://player.oddin.gg/embed/', // the hosted embed page
+  baseUrl: 'https://streams.oddin.gg',
+  matchUrn: 'od:match:1234',
+  // apiKey is DEV-ONLY here; in production the hosted page injects it server-side.
+  onEvent: (msg) => console.log(msg), // { type: 'oddin:ready' | 'oddin:state' | 'oddin:waiting' | 'oddin:stats' | 'oddin:error' }
+});
+
+embed.play();
+embed.setMuted(false);
+// embed.destroy();
+```
+
+Both ends verify `event.origin` on every message. The embed page reads its
+config from `window.HAVIK_EMBED_CONFIG` (server-injected) or the URL query.
+A ready-to-host page is shipped at `embed/index.html`.
+
+> **Iframe auth:** the key's **AllowedIframeParents** must include the embedding
+> page's origin — iframe navigations send a `Referer`/`Sec-Fetch-Dest: iframe`,
+> which is what havik-streams matches against (no `Origin` header on a top-level
+> iframe nav).
+
+---
+
+## Live pickup (`waitForLive`)
+
+A live match isn't playable until the stream is actually live. With `waitForLive`,
+the player arms and auto-attaches the instant it goes live — no user action.
+
+**By default it does this over a push channel (SSE), not polling.** While the
+live-state stream is connected the player makes **zero** `/v1/playback` requests — it
+waits for the pushed go-live, then resolves once (so it doesn't repeatedly poll while
+waiting for kickoff). If the push channel is unavailable it transparently falls back
+to **polling** `425 TOO_EARLY` + `Retry-After` (scaled ~30s→1s near kickoff, never
+faster than the server asks). Set `liveStateEvents: false` to force polling.
+
+```ts
+waitForLive: {
+  timeoutMs: 30 * 60_000, // overall arm budget (default: unbounded)
+  floorMs: 1000,          // min poll interval (default 1000, server minimum)
+  ceilMs: 30_000,         // cap far-from-kickoff backoff
+  onState: (s) => console.log(s.phase, s.retryInMs, s.attempt),
+}
+```
+
+**End of stream** is detected automatically: when the live stream finishes the player
+stops and fires `ended` — it never sits buffering on a stream that's over. See
+[`subscribeLiveState`](docs/API.md#subscribelivestate) to consume the live-state
+channel directly.
+
+## Error handling
+
+All API errors are a typed `PlaybackError` with `{ code, httpStatus, retryAfterMs?, requestId? }`:
+
+| code                         | HTTP      | meaning                                             | retry?            |
+| ---------------------------- | --------- | --------------------------------------------------- | ----------------- |
+| `INVALID_URN`                | 400       | malformed URN                                       | no                |
+| `NOT_FOUND`                  | 404       | unknown URN **or** not entitled (indistinguishable) | no                |
+| `GONE`                       | 410       | ended past catchup window                           | no                |
+| `TOO_EARLY`                  | 425       | upcoming, not live yet                              | yes (waitForLive) |
+| `UNAVAILABLE`                | 503       | should-be-live, origin warming up                   | yes               |
+| `UNAUTHORIZED` / `FORBIDDEN` | 401 / 403 | bad key / origin not allowed / DRM rejected         | no                |
+| `RATE_LIMITED`               | 429       | per-IP limiter                                      | back off          |
+
+---
+
+## Auth & onboarding
+
+The `x-api-key` is a **publishable** key, by design embeddable in browser JS. Its
+only guardrail is the **server-side per-key allowlist** — so onboarding each
+integrator origin is a hard dependency:
+
+1. **havik-streams**: the key's `AllowedOrigins` must include every origin your
+   player runs on (and `AllowedIframeParents` for Mode C). Never ship `["*"]` to
+   prod — it disables the guardrail.
+2. **havik-drm (`drm-proxy`)**: its `CORS_ALLOWED_ORIGINS` must also include those
+   origins, or the cross-origin license POST fails its preflight and DRM never
+   starts (silent black video).
+3. Scope the key's entitlements to the tournaments you serve.
+
+Revocation isn't instant (≤5min validation cache + ≤24h rotation grace).
+
+**Forward-compatible credentials:** `credential` also accepts an async function
+`() => Promise<{ apiKey }>`, so you can later swap in a short-lived-token mint
+service without changing your integration. (No such service exists today.)
+
+---
+
+## Demo app
+
+A full catalog-browser + live-watch + iframe demo lives in `demo/`:
+
+```bash
+cp demo/.env.local.example demo/.env.local   # set VITE_HAVIK_BASE_URL + VITE_HAVIK_API_KEY
+npm run dev                                   # http://localhost:5173
+```
+
+The key's `AllowedOrigins` must include `http://localhost:5173`.
+
+---
+
+## Limitations
+
+- **FairPlay (Safari/iOS)**: not implemented in v1. Safari uses native HLS
+  passthrough, which only plays DRM where the OS already trusts the origins. Full
+  FairPlay EME (via a Shaka adapter behind the `PlaybackEngine` seam) is a tracked
+  fast-follow.
+- **HLS only** (no DASH); **Widevine + FairPlay** key systems (no PlayReady — Edge
+  uses Widevine). Container CMAF/fMP4, encryption cbcs.
+- hls.js is pinned to `1.7.0-beta.1` (the first version that plays this LL-HLS+DRM
+  content; 1.6.x has a fatal sourceBuffer bug). Pin to `1.7.0` stable when released.
+
+## Privacy
+
+The SDK persists a random per-device id in `localStorage` and sends it as
+`X-Device-Id` on every DRM license request (required by the license server). It is a
+stable cross-session identifier — disclose it in your privacy policy and offer a reset
+via [`clearDeviceId()`](docs/API.md#getdeviceid--cleardeviceid). No other personal
+data is collected by the SDK.
+
+## Browser & runtime support
+
+- **Browser-only.** Importing the package is side-effect-safe (verified in CI), but
+  the SDK must be used **client-side** — call `createPlayer`/`mountEmbed` in the
+  browser, not during SSR (e.g. dynamic-import it in a Next.js client component).
+- Supported targets: see [`.browserslistrc`](.browserslistrc) (Chrome/Edge ≥94,
+  Firefox ≥91, Safari/iOS ≥15). DRM = Widevine on Chrome/Edge/Firefox/Android;
+  FairPlay (Safari/iOS) is not yet implemented.
+
+## Development
+
+```bash
+npm run build       # ESM lib (dist/index.js) + IIFE bundle (dist/havik-player.global.js)
+npm run typecheck
+npm run lint
+npm test            # vitest
+npm run test:coverage
+npm run dev         # demo app
+```
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the vulnerability-disclosure policy.
+
+## License
+
+ISC — see [LICENSE](LICENSE).
+
+### Third-party licenses
+
+This package depends on, and the CDN bundle (`dist/havik-player.global.js`) statically
+embeds, **hls.js** ([Apache-2.0](https://github.com/video-dev/hls.js/blob/master/LICENSE),
+© Dailymotion). Full attribution is in [THIRD_PARTY_NOTICES.txt](THIRD_PARTY_NOTICES.txt),
+which ships with the package and whose attribution is preserved in the bundle banner.
+
+DRM uses the browser's built-in EME/CDM; Widevine™ (Google), FairPlay®/AirPlay® (Apple)
+and PlayReady (Microsoft) are trademarks of their respective owners and no CDM is
+distributed with this package.

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,59 @@
+THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
+============================================
+
+@oddin-gg/havik-player incorporates third-party software. The pre-built browser
+bundle (dist/havik-player.global.js) statically embeds hls.js; the npm package
+declares it as a runtime dependency. The applicable licenses and required
+attributions are reproduced below.
+
+
+--------------------------------------------------------------------------------
+hls.js
+--------------------------------------------------------------------------------
+Project:   hls.js
+Homepage:  https://github.com/video-dev/hls.js
+License:   Apache License, Version 2.0
+Full text: http://www.apache.org/licenses/LICENSE-2.0
+
+Copyright (c) 2017 Dailymotion (http://www.dailymotion.com)
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+src/remux/mp4-generator.js and src/demux/exp-golomb.ts implementation in this project
+are derived from the HLS library for video.js (https://github.com/videojs/videojs-contrib-hls)
+
+That work is also covered by the Apache 2 License, following copyright:
+Copyright (c) 2013-2015 Brightcove
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+
+--------------------------------------------------------------------------------
+DRM / EME — trademark & licensing notice
+--------------------------------------------------------------------------------
+This SDK uses the browser's built-in Encrypted Media Extensions (EME) and the
+Content Decryption Module (CDM) provided by the user's browser/operating system.
+No DRM client or CDM is distributed with this package.
+
+- Widevine™ is a trademark of Google LLC.
+- FairPlay® and AirPlay® are trademarks of Apple Inc.
+- PlayReady is a trademark of Microsoft Corporation.
+
+These names are used for identification only. The corresponding CDMs are licensed
+separately by their respective owners and are not provided by Oddin.gg.