@chunkify/analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chunkify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,413 @@
+# @chunkify/analytics
+
+Standalone playback analytics for Chunkify Player, a native `<video>`, and supported third-party players. It has no runtime dependency on `@chunkify/player` and does not send data to Chunkify. Each event goes to the destinations supplied by the application.
+
+```sh
+npm install @chunkify/analytics
+```
+
+## Monitor Chunkify Player or a video element
+
+Add the player to your page:
+
+```html
+<chunkify-player id="player" controls src="https://example.com/video.m3u8"></chunkify-player>
+```
+
+Replace the example URL with your playback URL. In your application JavaScript, register the component and start monitoring it:
+
+```js
+import "@chunkify/player";
+import { monitor } from "@chunkify/analytics";
+
+const player = document.querySelector("#player");
+const session = monitor(player, {
+  videoId: "video_123",
+  destinations: [{ send: (event) => console.log(event) }],
+});
+```
+
+Call `session.destroy()` when the application removes the player or stops monitoring it.
+
+The same function also accepts a native video element without importing `@chunkify/player`:
+
+```html
+<video id="video" controls src="https://example.com/video.mp4"></video>
+```
+
+```js
+import { monitor } from "@chunkify/analytics";
+
+const video = document.querySelector("#video");
+const session = monitor(video, {
+  videoId: "video_123",
+  destinations: [{ send: (event) => console.log(event) }],
+});
+```
+
+Call `session.startAttempt()` before an application-initiated `video.play()` to count attempts that reject without a play event. Call `session.destroy()` when removing the video or disabling analytics.
+
+`monitor()` selects the direct video collector for `<video>` or the Chunkify adapter for `<chunkify-player>`. The adapter follows the player's active media element when switching between ordinary video and HLS. Other player types are not supported by this function. The lower-level `attachAnalytics()` and `attachPlayerAnalytics()` functions remain available for explicit use.
+
+When Chunkify Player uses hls.js, the adapter also records the selected rendition, rendition switches, playing time by rendition, HLS manifest and segment request totals, transferred bytes, aggregate throughput, and fatal hls.js errors. These measurements are unavailable when playback uses native HLS or ordinary video; the media-level measurements still work.
+
+## Monitor options
+
+The second argument to `monitor()` has the same options as `monitorHlsJs()`, `monitorVideoJs()`, and `monitorShaka()` below.
+
+| Option | Required or default | Meaning |
+| --- | --- | --- |
+| `videoId` | Required | Your video ID or Chunkify asset ID. Every event includes it as `video_id`. |
+| `destinations` | Required, non-empty array | Adapters or objects with `send(event)`. Each included event goes to every destination. |
+| `snapshotIntervalMs` | `30000` | Active playing time between cumulative snapshots, in milliseconds. Must be an integer from `1000` to `2147483647`. |
+| `includeEvents` | All six event types | Exact list of event types sent to destinations: `view_started`, `view_snapshot`, `playback_error`, `view_ended`, `playback_state_changed`, and `rendition_changed`. |
+| `environment` | `null` | Optional application environment string included in events. |
+| `viewerId` | `null` | Optional pseudonymous viewer ID included in events. No viewer identity is generated by default. |
+
+An empty `includeEvents` array sends nothing. Excluding `view_snapshot` stops its timer but still collects the final view metrics. State changes and rendition switches are sent by default, so a view with many pauses, stalls, seeks, or quality changes sends more records. To receive only the original four event types, list those four in `includeEvents`.
+
+## Monitor third-party players
+
+Use the connector for the player's public media API. All connectors take the same analytics options and return a session with `destroy()`.
+
+### hls.js
+
+For a separate player that gives you its `Hls` instance, use the optional hls.js adapter. This example assumes the page has a `<video controls>` element. The adapter follows that element once hls.js attaches it:
+
+```ts
+import Hls from "hls.js";
+import { monitorHlsJs } from "@chunkify/analytics";
+
+const video = document.querySelector("video")!;
+const hls = new Hls();
+const session = monitorHlsJs(hls, {
+  videoId: "video_123",
+  destinations: [{ send: (event) => console.log(event) }],
+});
+hls.attachMedia(video);
+hls.loadSource("https://example.com/video.m3u8");
+
+// Call session.sourceChanged() before replacing the source.
+// When finished, call session.destroy() and hls.destroy().
+```
+
+### Video.js 10
+
+For Video.js 10 HLS media (`<hls-video>`, `<hlsjs-video>`, or `<native-hls-video>`), pass the media element to `monitorVideoJs()`, not the outer `<video-player>`. The collector reads standard playback events from the element. With `<hlsjs-video>` using MSE, it also reads rendition and request metrics from the element's public hls.js `engine`. Native HLS and the lightweight `<hls-video>` expose fewer engine metrics, so those values remain null. For a plain `<video>` inside Video.js 10, use `monitor(video, options)`:
+
+```html
+<video-player>
+  <video-skin style="display: block; width: 100%; aspect-ratio: 16 / 9">
+    <hlsjs-video src="/video.m3u8"></hlsjs-video>
+  </video-skin>
+</video-player>
+```
+
+```ts
+import "@videojs/html/video/player";
+import "@videojs/html/video/skin";
+import "@videojs/html/media/hlsjs-video";
+import { monitorVideoJs } from "@chunkify/analytics";
+
+const media = document.querySelector("hlsjs-video")!;
+const session = monitorVideoJs(media, {
+  videoId: "video_123",
+  destinations: [{ send: (event) => console.log(event) }],
+});
+// Call session.destroy() when the media element is removed.
+```
+
+This integration targets the [Video.js 10 HTML API](https://videojs.org/docs/framework/html/guides/architecture), which is currently a release candidate. It does not target Video.js 8. Video.js also defines an `<hls-video>` tag; that is different from the `hls-video-element` used by Chunkify Player. Use `monitor()` for `<chunkify-player>`.
+
+### Shaka Player
+
+For Shaka Player, use a page with `<video controls>`, attach Shaka to it, then call `monitorShaka()` before `load()`. The connector starts each view on Shaka's `loading` event and enables Shaka's quality observer so it can measure playing time by video rendition at the playhead. It also counts completed network downloads, response bytes, download time, and critical error codes. It discards request URLs and response bodies. Cached responses are excluded from the delivery totals:
+
+```ts
+import shaka from "shaka-player";
+import { monitorShaka } from "@chunkify/analytics";
+
+shaka.polyfill.installAll();
+const video = document.querySelector("video")!;
+const player = new shaka.Player();
+await player.attach(video);
+const session = monitorShaka(player, {
+  videoId: "video_123",
+  destinations: [{ send: (event) => console.log(event) }],
+});
+await player.load("https://example.com/video.m3u8");
+// The viewer can now use the video's controls.
+
+// Call session.destroy() before player.destroy().
+```
+
+Shaka's `unloading` event ends the current view on a source change; its next `loading` event starts a fresh view. Call `session.sourceChanged()` yourself if you replace the source outside Shaka. The quality observer must be enabled before Shaka loads content; creating the session after `load()` may leave rendition playing time unavailable until the next load. `session.destroy()` restores the prior quality-observer setting if monitoring enabled it.
+Shaka may reject `player.load()` without dispatching an `error` event. Handle that promise rejection in your application; only Shaka's emitted critical errors become `playback_error` records.
+See [Shaka's setup guide](https://github.com/shaka-project/shaka-player/blob/main/docs/tutorials/basic-usage.md) for browser support, polyfills, and player setup.
+
+## Events and metrics
+
+The six event names are `chunkify.video.view_started`, `chunkify.video.view_snapshot`, `chunkify.video.playback_error`, `chunkify.video.view_ended`, `chunkify.video.playback_state_changed`, and `chunkify.video.rendition_changed`. All records share identifiers, a timestamp, and a sequence number within the `view_id`. The first four contain cumulative view measurements. Snapshots normally arrive after each 30 seconds of active playing time. State and rendition records have smaller, event-specific payloads. A value is `null` when it is unavailable or does not apply; the collector does not guess it.
+
+### Complete Chunkify Player event example
+
+This complete `view_ended` event is based on `<chunkify-player>` playing a local HLS stream, with timing values rounded for readability. The component used hls.js for this stream, so `connector_name` and `player_name` report `hls.js`. It is the **raw Chunkify event** passed to `send(event)`; an adapter or mapper can reshape it for a destination.
+
+```json
+{
+  "schema_version": 1,
+  "event_name": "chunkify.video.view_ended",
+  "event_id": "06581e06-96d7-421c-b77b-22a6e615c97e",
+  "sequence": 4,
+  "occurred_at": "2026-09-28T07:35:10.879Z",
+  "view_id": "8267fd81-ecf6-4fb1-83d9-4d1fba46b1b6",
+  "video_id": "video_123",
+  "sdk_name": "@chunkify/analytics",
+  "sdk_version": "0.1.0",
+  "connector_name": "hls.js",
+  "connector_version": "1.7.3",
+  "player_name": "hls.js",
+  "player_version": "1.7.3",
+  "delivery_hostname": null,
+  "environment": null,
+  "viewer_id": null,
+  "reason": "ended",
+  "startup_outcome": "started",
+  "error_category": null,
+  "error_code": null,
+  "error_fatal": null,
+  "error_playhead_seconds": null,
+  "media_duration_seconds": 6.021333,
+  "startup_time_ms": 2,
+  "first_video_frame_time_ms": 114,
+  "playing_time_ms": 6086,
+  "rebuffer_count": 0,
+  "rebuffer_duration_ms": 0,
+  "rebuffer_ratio": 0,
+  "seek_count": 0,
+  "seek_duration_ms": 0,
+  "maximum_playhead_seconds": 6.021333,
+  "furthest_progress_ratio": 1,
+  "video_intrinsic_width_css_px": 256,
+  "video_intrinsic_height_css_px": 144,
+  "dropped_video_frames": 0,
+  "total_video_frames": 68,
+  "selected_rendition_width": 256,
+  "selected_rendition_height": 144,
+  "selected_rendition_codec": null,
+  "selected_rendition_bitrate_bps": 250000,
+  "rendition_switch_count": 0,
+  "delivery_request_count": 2,
+  "delivery_transferred_bytes": 96329,
+  "delivery_throughput_bps": 175143637,
+  "rendition_playing_time": [
+    {
+      "width": 256,
+      "height": 144,
+      "codec": null,
+      "bitrate_bps": 250000,
+      "frame_rate": null,
+      "playing_time_ms": 6085
+    }
+  ]
+}
+```
+
+### Playback timeline events
+
+`playback_state_changed` reports the state entered and the wall-clock time spent in the previous state. Possible states are `startup` (the first attempt before playback), `resuming` (waiting after a pause or seek), `playing`, `paused`, `buffering`, `seeking`, `error`, `ended`, and `stopped`. The final transition to `ended` or `stopped` closes the last state before `view_ended`. A fatal error enters `error`; `view_ended` still reports why the view ended. For example, pausing after 20 seconds of playback produces these event-specific fields:
+
+```json
+{
+  "event_name": "chunkify.video.playback_state_changed",
+  "from_state": "playing",
+  "to_state": "paused",
+  "previous_state_duration_ms": 20000,
+  "playhead_seconds": 42
+}
+```
+
+`rendition_changed` reports a change between two known video renditions. It does not fire for the initial selection, repeated reports of the same rendition, or engines that do not expose rendition changes. The event has `previous_rendition_` and `selected_rendition_` fields for width, height, codec, bitrate in bits per second, and frame rate. Unknown properties are `null`:
+
+```json
+{
+  "event_name": "chunkify.video.rendition_changed",
+  "playhead_seconds": 42,
+  "previous_rendition_width": 1280,
+  "previous_rendition_height": 720,
+  "selected_rendition_width": 854,
+  "selected_rendition_height": 480
+}
+```
+
+These are excerpts; actual timeline records also have the shared identifiers and timestamp. `playhead_seconds` is the media element's `currentTime` at the transition, or `null` if unavailable. It is a media position, not elapsed viewing time or a universal timestamp for live video. `occurred_at` and `sequence` place the transition in the viewing timeline. Cumulative playing time by rendition remains in snapshots and `view_ended`.
+
+### Field guide
+
+| Fields | Meaning |
+| --- | --- |
+| `schema_version`, `event_name`, `event_id`, `sequence`, `occurred_at` | Contract version, event type, unique event ID, sequence within this view, and UTC event time. |
+| `view_id`, `video_id` | Ephemeral playback-attempt ID and the `videoId` supplied by your application. A new attempt gets a new `view_id`. |
+| `sdk_name`, `sdk_version`, `connector_name`, `connector_version`, `player_name`, `player_version` | The collector, connector, and player that produced the record. Player fields can be `null`. |
+| `delivery_hostname`, `environment`, `viewer_id` | Delivery host when available, optional application environment, and optional pseudonymous `viewerId` supplied by the application. No complete URL or viewer identity is generated. |
+| `reason`, `startup_outcome` | End reason and startup result on `view_ended`; `null` on other events. Ending before startup does not establish why the viewer left. |
+| `error_category`, `error_code`, `error_fatal`, `error_playhead_seconds` | Normalized error details on `playback_error`; otherwise `null`. Raw error messages and URLs are not included. |
+| `media_duration_seconds`, `startup_time_ms`, `first_video_frame_time_ms`, `playing_time_ms` | Media duration; time from attempt to first `playing`; time to the first frame callback; cumulative actual playing time. The two startup measurements can differ. |
+| `rebuffer_count`, `rebuffer_duration_ms`, `rebuffer_ratio`, `seek_count`, `seek_duration_ms` | Counts, cumulative durations, and rebuffer time divided by playing plus rebuffer time. The ratio is `null` until its denominator is positive. |
+| `maximum_playhead_seconds`, `furthest_progress_ratio` | Furthest playhead reached and that position divided by duration, capped at 1. Seeking near the end raises the ratio without watching the intervening video. |
+| `video_intrinsic_width_css_px`, `video_intrinsic_height_css_px`, `dropped_video_frames`, `total_video_frames` | Intrinsic display dimensions and browser frame counters when exposed. The dimensions are not necessarily encoded frame dimensions. |
+| `selected_rendition_width`, `selected_rendition_height`, `selected_rendition_codec`, `selected_rendition_bitrate_bps`, `rendition_switch_count` | Current video rendition and switches when an engine connector exposes them. Width and height are in pixels; bitrate is in bits per second. |
+| `rendition_playing_time` | Cumulative wall-clock milliseconds by rendition. Each entry has `width`, `height`, `codec`, `bitrate_bps`, `frame_rate`, and `playing_time_ms`. It is `null` without a rendition-aware connector and `[]` before one identifies a rendition. |
+| `delivery_request_count`, `delivery_transferred_bytes`, `delivery_throughput_bps` | Aggregate requests, response bytes, and throughput where the engine exposes them. Throughput is in bits per second. |
+
+`reason` can be `ended`, `destroyed`, `source_changed`, or `page_exit`. `startup_outcome` can be `started`, `failed_before_start`, or `ended_before_start`. Error categories are `aborted`, `network`, `decode`, `unsupported`, or `unknown`.
+
+`first_video_frame_time_ms` uses `requestVideoFrameCallback()` and may remain `null` or precede `startup_time_ms` for a preloaded frame. It is not proof that the viewer saw the frame. `rendition_playing_time` excludes pauses, buffering, seeks, and playback before a rendition is known, so its sum can be lower than `playing_time_ms`. Snapshots repeat cumulative totals: use the final record or differences between snapshots, not the sum of whole snapshots. This package does not aggregate across viewers.
+
+## Map event fields
+
+Use `createEventMapper()` when a destination needs different field names or values. Each output field names a source event field or calculates a value from the event. The mapper returns a new object and leaves the original event unchanged:
+
+```ts
+import { createEventMapper, monitor } from "@chunkify/analytics";
+import { createHttpAdapter } from "@chunkify/analytics/http";
+
+const mapForEndpoint = createEventMapper({
+  videoId: "video_id",
+  viewId: "view_id",
+  eventName: "event_name",
+  playtimeSeconds: (event) => event.playing_time_ms === undefined ? undefined : event.playing_time_ms / 1000,
+});
+
+monitor(video, {
+  videoId: "video_123",
+  destinations: [createHttpAdapter("/api/video-analytics", mapForEndpoint)],
+});
+```
+
+The mapping runs for each event passed to the destination. A field absent from an event-specific payload is omitted from the mapped result, including when a selector returns `undefined`. For example, `playtimeSeconds` above is omitted from a rendition-change event. For destinations that accept the Chunkify event directly, omit the mapper. Mapping does not alter collection, event selection, or snapshot timing. See [Monitor options](#monitor-options) for `includeEvents` and `snapshotIntervalMs`.
+
+To map event types differently, select a mapper in the adapter. This example assumes the Datadog RUM client has already been initialized. Other events keep their original fields:
+
+```js
+import { datadogRum } from "@datadog/browser-rum";
+import { createEventMapper } from "@chunkify/analytics";
+import { createDatadogAdapter } from "@chunkify/analytics/datadog";
+
+const mapStateChange = createEventMapper({
+  videoId: "video_id",
+  from: "from_state",
+  to: "to_state",
+  durationMs: "previous_state_duration_ms",
+});
+const mapRenditionChange = createEventMapper({
+  videoId: "video_id",
+  width: "selected_rendition_width",
+  height: "selected_rendition_height",
+});
+
+const destination = createDatadogAdapter(datadogRum, (event) => {
+  if (event.event_name === "chunkify.video.playback_state_changed") return mapStateChange(event);
+  if (event.event_name === "chunkify.video.rendition_changed") return mapRenditionChange(event);
+  return { ...event };
+});
+```
+
+Pass `destination` in `monitor()`'s `destinations` array. The same pattern works with the PostHog and HTTP adapters.
+
+## Send events to a destination
+
+Destinations keep collection separate from delivery. Provide at least one adapter or object with `send(event)`. Every included event goes to every destination. The package does not retry, queue, or guarantee delivery on page exit. Do not put personal information, tokens, or URLs in supplied metadata. The event payload omits raw URLs and error messages. The Datadog and PostHog examples use [the player markup](#monitor-chunkify-player-or-a-video-element) shown above.
+
+### Datadog RUM
+
+Install `@datadog/browser-rum` in your application. Initialize it with your RUM application ID and **client token** (not a Datadog API key), then pass the client to the adapter. The adapter adds one custom action per analytics event, with the event fields directly in the action context by default:
+
+```js
+import "@chunkify/player";
+import { datadogRum } from "@datadog/browser-rum";
+import { monitor } from "@chunkify/analytics";
+import { createDatadogAdapter } from "@chunkify/analytics/datadog";
+
+datadogRum.init({
+  applicationId: "YOUR_DATADOG_APPLICATION_ID",
+  clientToken: "YOUR_DATADOG_RUM_CLIENT_TOKEN",
+  site: "datadoghq.com", // Use your organization's Datadog site.
+});
+
+monitor(document.querySelector("#player"), {
+  videoId: "video_123",
+  destinations: [createDatadogAdapter(datadogRum)],
+});
+```
+
+Pass a mapper as the second argument to choose or rename context fields; it runs for each event. If a dashboard needs derived actions, such as one action per rendition, add a separate custom destination to create them from `view_ended`.
+
+### PostHog
+
+Install `posthog-js` in your application. Initialize it with your project token and ingestion host, then pass it to the adapter. The adapter captures one event per analytics record, with the event's fields as flat PostHog properties. Its optional second argument maps the properties for each event:
+
+```js
+import "@chunkify/player";
+import posthog from "posthog-js";
+import { monitor } from "@chunkify/analytics";
+import { createPostHogAdapter } from "@chunkify/analytics/posthog";
+
+posthog.init("YOUR_POSTHOG_PROJECT_TOKEN", {
+  api_host: "https://us.i.posthog.com", // Use your project's ingestion host.
+});
+
+monitor(document.querySelector("#player"), {
+  videoId: "video_123",
+  destinations: [createPostHogAdapter(posthog)],
+});
+```
+
+The application controls PostHog's automatic collection and persistence settings. PostHog may add its own event properties, including page context, beyond the fields sent by this adapter; configure the PostHog SDK separately to meet your privacy requirements.
+
+### OTLP/HTTP logs
+
+The OTLP adapter sends each event as an OTLP/HTTP JSON log record. Pass the full URL of a customer-owned `/v1/logs` gateway, or a root-relative path to one. The gateway must allow browser CORS when cross-origin and handle any private provider credentials. The adapter sends no cookies or authorization headers. By default, all event fields become typed log attributes; unavailable values are omitted, and `rendition_playing_time` remains a structured array. Pass a mapper as the second argument to choose or rename log attributes. The OTLP event name, timestamp, and scope still come from the original event. Snapshots contain cumulative values, so aggregate the final record or differences between snapshots rather than summing all records:
+
+```ts
+import { createEventMapper } from "@chunkify/analytics";
+import { createOtlpAdapter } from "@chunkify/analytics/otlp";
+
+const attributes = createEventMapper({
+  video_id: "video_id",
+  view_id: "view_id",
+  event_id: "event_id",
+  playing_time_ms: "playing_time_ms",
+});
+
+monitor(video, {
+  videoId: "video_123",
+  destinations: [createOtlpAdapter("https://analytics.example.com/v1/logs", attributes)],
+});
+```
+
+This adapter emits OTLP **logs**, not OTLP metrics. Your gateway or provider handles storage and aggregation.
+
+### HTTP endpoint
+
+The HTTP adapter posts each event as JSON to a customer-owned endpoint using `fetch`. Pass a mapper as its second argument when the endpoint needs a different payload; otherwise it sends the complete Chunkify event. It accepts an HTTPS URL or root-relative path; loopback HTTP is allowed for local tests. It rejects credentials and query parameters in the endpoint, sends no cookies, and sends no page referrer. The endpoint must support browser CORS when cross-origin and perform its own aggregation. Non-2xx responses reject the adapter's `send()` promise; the collector isolates delivery failures and does not retry them. The final event uses `fetch` keepalive as a best-effort page-exit delivery, subject to browser limits:
+
+```ts
+import { createHttpAdapter } from "@chunkify/analytics/http";
+
+monitor(video, {
+  videoId: "video_123",
+  destinations: [createHttpAdapter("/api/video-analytics")],
+});
+```
+
+### Custom destination
+
+No adapter is needed when you want the normalized event as-is. A destination can inspect it, map it, or pass it to your own client:
+
+```ts
+monitor(video, {
+  videoId: "video_123",
+  destinations: [{ send(event) { console.log(event); } }],
+});
+```

package/dist/core.d.ts

@@ -0,0 +1,144 @@
+import { type AnalyticsEventType } from "./event-types.js";
+export type { AnalyticsEventType } from "./event-types.js";
+export type AnalyticsEndReason = "ended" | "destroyed" | "source_changed" | "page_exit";
+export type AnalyticsErrorCategory = "aborted" | "network" | "decode" | "unsupported" | "unknown";
+export type AnalyticsStartupOutcome = "started" | "failed_before_start" | "ended_before_start";
+export type AnalyticsPlaybackState = "startup" | "resuming" | "playing" | "paused" | "buffering" | "seeking" | "error" | "ended" | "stopped";
+export interface RenditionPlayingTime {
+    width: number | null;
+    height: number | null;
+    codec: string | null;
+    bitrate_bps: number | null;
+    frame_rate: number | null;
+    playing_time_ms: number;
+}
+export type AnalyticsRendition = Omit<RenditionPlayingTime, "playing_time_ms">;
+export interface ViewMetrics {
+    media_duration_seconds: number | null;
+    startup_time_ms: number | null;
+    first_video_frame_time_ms: number | null;
+    playing_time_ms: number;
+    rebuffer_count: number;
+    rebuffer_duration_ms: number;
+    rebuffer_ratio: number | null;
+    seek_count: number;
+    seek_duration_ms: number;
+    maximum_playhead_seconds: number;
+    furthest_progress_ratio: number | null;
+    video_intrinsic_width_css_px: number | null;
+    video_intrinsic_height_css_px: number | null;
+    dropped_video_frames: number | null;
+    total_video_frames: number | null;
+    selected_rendition_width: number | null;
+    selected_rendition_height: number | null;
+    selected_rendition_codec: string | null;
+    selected_rendition_bitrate_bps: number | null;
+    rendition_switch_count: number | null;
+    rendition_playing_time: RenditionPlayingTime[] | null;
+    delivery_request_count: number | null;
+    delivery_transferred_bytes: number | null;
+    delivery_throughput_bps: number | null;
+}
+export interface AnalyticsEventEnvelope {
+    schema_version: 1;
+    event_name: `chunkify.video.${AnalyticsEventType}`;
+    event_id: string;
+    sequence: number;
+    occurred_at: string;
+    view_id: string;
+    video_id: string;
+    sdk_name: "@chunkify/analytics";
+    sdk_version: string;
+    connector_name: string;
+    connector_version: string | null;
+    player_name: string | null;
+    player_version: string | null;
+    delivery_hostname: string | null;
+    environment: string | null;
+    viewer_id: string | null;
+    reason: AnalyticsEndReason | null;
+    startup_outcome: AnalyticsStartupOutcome | null;
+    error_category: AnalyticsErrorCategory | null;
+    error_code: string | number | null;
+    error_fatal: boolean | null;
+    error_playhead_seconds: number | null;
+}
+export interface AnalyticsViewEvent extends AnalyticsEventEnvelope, ViewMetrics {
+    event_name: "chunkify.video.view_started" | "chunkify.video.view_snapshot" | "chunkify.video.playback_error" | "chunkify.video.view_ended";
+}
+export interface AnalyticsPlaybackStateEvent extends AnalyticsEventEnvelope, Partial<ViewMetrics> {
+    event_name: "chunkify.video.playback_state_changed";
+    playhead_seconds: number | null;
+    from_state: AnalyticsPlaybackState;
+    to_state: AnalyticsPlaybackState;
+    previous_state_duration_ms: number;
+}
+export interface AnalyticsRenditionEvent extends AnalyticsEventEnvelope, Partial<ViewMetrics> {
+    event_name: "chunkify.video.rendition_changed";
+    playhead_seconds: number | null;
+    previous_rendition_width: number | null;
+    previous_rendition_height: number | null;
+    previous_rendition_codec: string | null;
+    previous_rendition_bitrate_bps: number | null;
+    previous_rendition_frame_rate: number | null;
+    selected_rendition_width: number | null;
+    selected_rendition_height: number | null;
+    selected_rendition_codec: string | null;
+    selected_rendition_bitrate_bps: number | null;
+    selected_rendition_frame_rate: number | null;
+}
+export type ChunkifyPlayerAnalyticsEvent = AnalyticsViewEvent | AnalyticsPlaybackStateEvent | AnalyticsRenditionEvent;
+export interface AnalyticsDestination {
+    send(event: ChunkifyPlayerAnalyticsEvent): void | Promise<void>;
+}
+export interface AnalyticsConfig {
+    destinations: readonly AnalyticsDestination[];
+    environment?: string | undefined;
+    viewerId?: string | undefined;
+    /** Active playing time between cumulative snapshots. Defaults to 30,000 ms. */
+    snapshotIntervalMs?: number | undefined;
+    /** Event types passed to destinations. Defaults to all six types. */
+    includeEvents?: readonly AnalyticsEventType[] | undefined;
+}
+export interface AnalyticsOptions extends AnalyticsConfig {
+    videoId: string;
+}
+export interface AnalyticsConnectorSnapshot {
+    renditionWidth: number | null;
+    renditionHeight: number | null;
+    renditionCodec: string | null;
+    renditionBitrate: number | null;
+    renditionSwitchCount: number | null;
+    deliveryRequestCount: number | null;
+    deliveryTransferredBytes: number | null;
+    deliveryDurationMs: number | null;
+}
+export interface AnalyticsConnectorError {
+    category: AnalyticsErrorCategory;
+    code: string | number | null;
+    fatal: boolean;
+}
+export interface AnalyticsConnector {
+    name: string;
+    version: string | null;
+    playerName: string | null;
+    playerVersion: string | null;
+    snapshot(): AnalyticsConnectorSnapshot;
+    subscribeToErrors(listener: (error: AnalyticsConnectorError) => void): () => void;
+    /** Fires with the rendition currently reaching playback, including the initial selection. */
+    subscribeToRenditions?(listener: (rendition: AnalyticsRendition | null) => void): () => void;
+}
+export interface AnalyticsSession {
+    /** Call immediately before play() to include attempts that reject before a play event. */
+    startAttempt(): void;
+    /** Finish the current view before its media source or playback engine is replaced. */
+    sourceChanged(): void;
+    /** Add or replace optional engine-specific measurements for subsequent records. */
+    setConnector(connector: AnalyticsConnector | null): void;
+    /** End the current view, if any, and remove all analytics listeners. Idempotent. */
+    destroy(): void;
+}
+export declare function attachAnalytics(media: HTMLMediaElement, options: AnalyticsOptions): AnalyticsSession;
+/** Engine adapters call this when they own source-change events. */
+export declare function attachAnalyticsWithManagedSource(media: HTMLMediaElement, options: AnalyticsOptions): AnalyticsSession;
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGhF,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,WAAW,GAAG,gBAAgB,GAAG,WAAW,CAAC;AACxF,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,CAAC;AAClG,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAC/F,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAC9F,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAC5C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,oBAAoB,EAAE,iBAAiB,CAAC,CAAC;AAC/E,MAAM,WAAW,WAAW;IAC1B,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB,EAAE,MAAM,CAAC;IACjC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,4BAA4B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,6BAA6B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,8BAA8B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,sBAAsB,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAAC;IACtD,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AACD,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,CAAC,CAAC;IAClB,UAAU,EAAE,kBAAkB,kBAAkB,EAAE,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAChD,cAAc,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC9C,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AACD,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB,EAAE,WAAW;IAC7E,UAAU,EAAE,6BAA6B,GAAG,8BAA8B,GACxE,+BAA+B,GAAG,2BAA2B,CAAC;CACjE;AACD,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB,EAAE,OAAO,CAAC,WAAW,CAAC;IAC/F,UAAU,EAAE,uCAAuC,CAAC;IACpD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,sBAAsB,CAAC;IACnC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;CACpC;AACD,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB,EAAE,OAAO,CAAC,WAAW,CAAC;IAC3F,UAAU,EAAE,kCAAkC,CAAC;IAC/C,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,8BAA8B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,6BAA6B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,8BAA8B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,6BAA6B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AACD,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,GAAG,2BAA2B,GAAG,uBAAuB,CAAC;AACtH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,KAAK,EAAE,4BAA4B,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AACD,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC9C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,qEAAqE;IACrE,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;CAC3D;AACD,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,0BAA0B;IACzC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AACD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,sBAAsB,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,IAAI,0BAA0B,CAAC;IACvC,iBAAiB,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAClF,6FAA6F;IAC7F,qBAAqB,CAAC,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9F;AACD,MAAM,WAAW,gBAAgB;IAC/B,0FAA0F;IAC1F,YAAY,IAAI,IAAI,CAAC;IACrB,sFAAsF;IACtF,aAAa,IAAI,IAAI,CAAC;IACtB,mFAAmF;IACnF,YAAY,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAAC;IACzD,oFAAoF;IACpF,OAAO,IAAI,IAAI,CAAC;CACjB;AAoLD,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAEpG;AAED,oEAAoE;AACpE,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAErH"}