API stability, versioning & support

Semantic versioning

@oddin-gg/havik-player follows SemVer. 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. 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), the OS/browser-provided Content Decryption Module, and (for the device id) 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.