# API stability, versioning & support

## Semantic versioning

`@oddin-gg/havik-player` follows [SemVer](https://semver.org/). Releases are automated
by semantic-release from Conventional Commits: `fix:` → patch, `feat:` → minor,
breaking change → major. **Pin a version in production** (npm and the CDN URL).

## What is public vs internal

**Stable public API** (changes only follow SemVer; the runtime export set is frozen by
`test/public-api.test.ts`):

- `createPlayer` + the `Player` interface (Mode A)
- `resolveStream`, `fetchCatalog`, `flattenMatches`, `watchStatus`,
  `licenseRequestHeaders`, `getDeviceId`, `clearDeviceId`, `isLowLatencyManifest` (Mode B)
- `mountEmbed` / `bootEmbed` + `EmbedHandle` / the `oddin:*` postMessage protocol (Mode C)
- `PlaybackError` and all exported `type` definitions

**Advanced / experimental** (public but may evolve faster): `pollToLive`, `isOddinMessage`.

**Internal**: **not** part of the public API and excluded from the type declarations
(`stripInternal`): the `PlaybackEngine` engine seam, `EngineEvent`, `resolvePlaybackOnce`,
`resolveCredential`. Do not depend on these.

## Deprecation policy

- Anything to be removed is first marked `@deprecated` (with the replacement) for **at
  least one minor release** before removal.
- Removals and breaking signature changes ship only in a **major**, and are called out in
  the `CHANGELOG.md` and the GitHub release notes.

## postMessage protocol (Mode C)

The host↔iframe protocol is versioned via `PROTOCOL_VERSION`, sent in `oddin:ready`.
Changes are additive within a major. `mountEmbed` logs a warning if the embed
page's protocol version differs from the host SDK's. Pin the embed page version
to the SDK version to avoid CDN auto-update skew.

## Browser support

See [`.browserslistrc`](../.browserslistrc). DRM: Widevine on Chrome/Edge/Firefox/Android;
FairPlay (Safari/iOS) is not yet implemented.

## Supported versions

Security and bug fixes target the latest published minor.

## Export control / cryptography note

This SDK performs no proprietary cryptography and bundles no DRM client/CDM. It
relies solely on the browser's built-in Encrypted Media Extensions (EME) and the
OS or browser-provided Content Decryption Module. The device id uses the standard
Web Crypto API. It is
publicly available open-source software. For US export classification this typically falls
under license-exception TSU / ECCN 5D002 NLR-eligible, but confirm the appropriate
classification with your legal/compliance team for your jurisdiction.