@oddin-gg/havik-player 2.7.0 → 2.8.0

package/README.md

@@ -61,7 +61,7 @@ import { createPlayer } from '@oddin-gg/havik-player';
 
 const player = await createPlayer({
   video: document.querySelector('video')!,
-  baseUrl: 'https://feed-dev.oddin-video.gg',
+  env: 'integration', // or 'production'
   matchUrn: 'od:match:1234',
   credential: { apiKey: 'pk_test_…' },
   autoplay: true,
@@ -81,6 +81,39 @@ player.destroy();
 The managed player handles `425 TOO_EARLY` retries (honoring `Retry-After`),
 buffering recovery, and silent DRM **license-URL refresh** for long sessions.
 
+### Choosing an environment
+
+`env` names the stack: `integration` is the shared pre-production environment,
+`production` is the production one. They are separate deployments, not
+aliases. Prefer `env` over a hand-written `baseUrl`. The API host is then
+correct by construction, and so is every host derived from it, including the
+QoE beacons endpoint.
+
+Pass `baseUrl` instead when the named environments do not cover your
+deployment:
+
+- your own CDN or gateway in front of the streams API
+- the CN plane, whose host is not under this domain
+- a pinned build that has to outlive a domain change
+
+`baseUrl` is not deprecated and is not going away. Pass exactly one of the
+two. In TypeScript, passing both or neither is a compile error. In JavaScript
+it throws at `createPlayer`, because the two disagreeing is the
+misconfiguration worth refusing.
+
+Modes B and C still take a `baseUrl`. Use `baseUrlForEnv` there rather than
+copying a hostname into your own config:
+
+```ts
+import { baseUrlForEnv, resolveStream } from '@oddin-gg/havik-player';
+
+const stream = await resolveStream({
+  baseUrl: baseUrlForEnv('production'),
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_live_…' },
+});
+```
+
 ### Controls & skinning
 
 By default, Mode A renders a **branded, fully skinnable control bar**. It covers