@chunkify/analytics 0.1.0

package/src/datadog.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsDestination, ChunkifyPlayerAnalyticsEvent } from "./core.js";
+
+/** The small part of an initialized Datadog RUM client needed by this adapter. */
+export interface DatadogRumCompatibleClient {
+  addAction(name: string, context: Record<string, unknown>): void;
+}
+
+/** Send one action per event, optionally mapping its Datadog context. */
+export function createDatadogAdapter(
+  client: DatadogRumCompatibleClient,
+  mapEvent: (event: ChunkifyPlayerAnalyticsEvent) => Record<string, unknown> = (event) => ({ ...event }),
+): AnalyticsDestination {
+  if (!client || typeof client.addAction !== "function") {
+    throw new TypeError("Datadog adapter requires an initialized client with addAction().");
+  }
+  if (typeof mapEvent !== "function") {
+    throw new TypeError("Datadog event mapper must be a function.");
+  }
+  return {
+    send(event: ChunkifyPlayerAnalyticsEvent) {
+      client.addAction(event.event_name, mapEvent(event));
+    },
+  };
+}

package/src/event-types.ts

@@ -0,0 +1,6 @@
+export const analyticsEventTypes = [
+  "view_started", "view_snapshot", "playback_error", "view_ended",
+  "playback_state_changed", "rendition_changed",
+] as const;
+
+export type AnalyticsEventType = (typeof analyticsEventTypes)[number];

package/src/hlsjs.ts

@@ -0,0 +1,192 @@
+import type Hls from "hls.js";
+import type {
+  AudioTrackLoadedData, ErrorData, FragLoadedData, LevelLoadedData,
+  LevelSwitchedData, LoaderStats, ManifestLoadedData, SubtitleTrackLoadedData,
+} from "hls.js";
+import { attachAnalyticsWithManagedSource, type AnalyticsConnector, type AnalyticsConnectorError,
+  type AnalyticsConnectorSnapshot, type AnalyticsOptions, type AnalyticsRendition,
+  type AnalyticsSession } from "./core.js";
+import { assertAnalyticsOptions } from "./options.js";
+
+export interface HlsJsAnalyticsConnector extends AnalyticsConnector {
+  destroy(): void;
+}
+
+type HlsJsSnapshot = AnalyticsConnectorSnapshot & {
+  renditionSwitchCount: number;
+  deliveryRequestCount: number;
+  deliveryTransferredBytes: number;
+  deliveryDurationMs: number;
+};
+
+/** Observe an hls.js instance without changing its playback configuration. */
+export function createHlsJsConnector(hls: Hls): HlsJsAnalyticsConnector {
+  const HlsClass = hls.constructor as typeof Hls;
+  const snapshot: HlsJsSnapshot = {
+    renditionWidth: null, renditionHeight: null, renditionCodec: null, renditionBitrate: null,
+    renditionSwitchCount: 0, deliveryRequestCount: 0, deliveryTransferredBytes: 0,
+    deliveryDurationMs: 0,
+  };
+  const seenStats = new WeakSet<object>();
+  const errorListeners = new Set<(error: AnalyticsConnectorError) => void>();
+  const renditionListeners = new Set<(rendition: AnalyticsRendition | null) => void>();
+  let selectedLevel: number | null = null;
+  let currentRendition: AnalyticsRendition | null = null;
+  let destroyed = false;
+
+  const selectLevel = (level: number) => {
+    const rendition = hls.levels[level];
+    if (!rendition) return;
+    if (selectedLevel !== null && selectedLevel !== level) snapshot.renditionSwitchCount++;
+    selectedLevel = level;
+    snapshot.renditionWidth = rendition.width || null;
+    snapshot.renditionHeight = rendition.height || null;
+    snapshot.renditionCodec = rendition.videoCodec || rendition.codecSet || null;
+    snapshot.renditionBitrate = rendition.bitrate || null;
+    currentRendition = {
+      width: snapshot.renditionWidth,
+      height: snapshot.renditionHeight,
+      codec: snapshot.renditionCodec,
+      bitrate_bps: snapshot.renditionBitrate,
+      frame_rate: rendition.frameRate || null,
+    };
+    for (const listener of renditionListeners) listener(currentRendition);
+  };
+  if (hls.currentLevel >= 0) selectLevel(hls.currentLevel);
+
+  const recordStats = (stats: LoaderStats | null | undefined) => {
+    if (!stats || seenStats.has(stats)) return;
+    seenStats.add(stats);
+    const bytes = Number.isFinite(stats.loaded) && stats.loaded >= 0 ? stats.loaded : 0;
+    const elapsed = stats.loading.end - stats.loading.start;
+    snapshot.deliveryRequestCount++;
+    snapshot.deliveryTransferredBytes += bytes;
+    if (Number.isFinite(elapsed) && elapsed > 0) snapshot.deliveryDurationMs += elapsed;
+  };
+  const onManifestLoaded = (_event: unknown, data: ManifestLoadedData) => recordStats(data.stats);
+  const onLevelLoaded = (_event: unknown, data: LevelLoadedData) => recordStats(data.stats);
+  const onAudioTrackLoaded = (_event: unknown, data: AudioTrackLoadedData) => recordStats(data.stats);
+  const onSubtitleTrackLoaded = (_event: unknown, data: SubtitleTrackLoadedData) => recordStats(data.stats);
+  const onFragLoaded = (_event: unknown, data: FragLoadedData) => recordStats(data.part?.stats ?? data.frag.stats);
+  const onLevelSwitched = (_event: unknown, data: LevelSwitchedData) => selectLevel(data.level);
+  const onError = (_event: unknown, data: ErrorData) => {
+    if (!data.fatal) return;
+    const category = data.type === HlsClass.ErrorTypes.NETWORK_ERROR ? "network"
+      : data.type === HlsClass.ErrorTypes.MEDIA_ERROR || data.type === HlsClass.ErrorTypes.MUX_ERROR ? "decode"
+      : data.type === HlsClass.ErrorTypes.KEY_SYSTEM_ERROR ? "unsupported" : "unknown";
+    for (const listener of errorListeners) listener({ category, code: data.details, fatal: true });
+  };
+
+  hls.on(HlsClass.Events.MANIFEST_LOADED, onManifestLoaded);
+  hls.on(HlsClass.Events.LEVEL_LOADED, onLevelLoaded);
+  hls.on(HlsClass.Events.AUDIO_TRACK_LOADED, onAudioTrackLoaded);
+  hls.on(HlsClass.Events.SUBTITLE_TRACK_LOADED, onSubtitleTrackLoaded);
+  hls.on(HlsClass.Events.FRAG_LOADED, onFragLoaded);
+  hls.on(HlsClass.Events.LEVEL_SWITCHED, onLevelSwitched);
+  hls.on(HlsClass.Events.ERROR, onError);
+
+  return {
+    name: "hls.js", version: HlsClass.version,
+    playerName: "hls.js", playerVersion: HlsClass.version,
+    snapshot: () => ({ ...snapshot }),
+    subscribeToErrors(listener) {
+      errorListeners.add(listener);
+      return () => { errorListeners.delete(listener); };
+    },
+    subscribeToRenditions(listener) {
+      renditionListeners.add(listener);
+      listener(currentRendition);
+      return () => { renditionListeners.delete(listener); };
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      hls.off(HlsClass.Events.MANIFEST_LOADED, onManifestLoaded);
+      hls.off(HlsClass.Events.LEVEL_LOADED, onLevelLoaded);
+      hls.off(HlsClass.Events.AUDIO_TRACK_LOADED, onAudioTrackLoaded);
+      hls.off(HlsClass.Events.SUBTITLE_TRACK_LOADED, onSubtitleTrackLoaded);
+      hls.off(HlsClass.Events.FRAG_LOADED, onFragLoaded);
+      hls.off(HlsClass.Events.LEVEL_SWITCHED, onLevelSwitched);
+      hls.off(HlsClass.Events.ERROR, onError);
+      errorListeners.clear();
+      renditionListeners.clear();
+    },
+  };
+}
+
+/** Follow an hls.js instance as it attaches to or detaches from media. */
+export function monitorHlsJs(hls: Hls, options: AnalyticsOptions):
+  Pick<AnalyticsSession, "startAttempt" | "sourceChanged" | "destroy"> {
+  assertAnalyticsOptions(options);
+  const HlsClass = hls.constructor as typeof Hls;
+  let media: HTMLMediaElement | null = null;
+  let session: AnalyticsSession | null = null;
+  let connector: HlsJsAnalyticsConnector | null = null;
+  let pendingAttempt = false;
+  let destroyed = false;
+
+  const releaseMedia = (sourceChanged: boolean) => {
+    const previousSession = session;
+    const previousConnector = connector;
+    media = null;
+    session = null;
+    connector = null;
+    if (sourceChanged) previousSession?.sourceChanged();
+    previousSession?.destroy();
+    previousConnector?.destroy();
+  };
+  const attachMedia = () => {
+    const nextMedia = hls.media;
+    if (destroyed || !nextMedia || nextMedia === media) return;
+    if (media) releaseMedia(true);
+    const nextSession = attachAnalyticsWithManagedSource(nextMedia, options);
+    media = nextMedia;
+    session = nextSession;
+    try {
+      connector = createHlsJsConnector(hls);
+      nextSession.setConnector(connector);
+    } catch {
+      // An engine measurement failure must not prevent media playback analytics.
+    }
+    if (pendingAttempt) {
+      pendingAttempt = false;
+      nextSession.startAttempt();
+    }
+  };
+  const onMediaAttaching = () => attachMedia();
+  const onMediaDetaching = () => {
+    // hls.js can detach and reattach the same media synchronously while
+    // recovering an error or recreating its MediaSource. That is one view.
+    queueMicrotask(() => {
+      if (!destroyed && !hls.media) releaseMedia(true);
+    });
+  };
+  const onDestroying = () => destroy();
+  function destroy() {
+    if (destroyed) return;
+    destroyed = true;
+    hls.off(HlsClass.Events.MEDIA_ATTACHING, onMediaAttaching);
+    hls.off(HlsClass.Events.MEDIA_DETACHING, onMediaDetaching);
+    hls.off(HlsClass.Events.DESTROYING, onDestroying);
+    releaseMedia(false);
+    pendingAttempt = false;
+  }
+
+  hls.on(HlsClass.Events.MEDIA_ATTACHING, onMediaAttaching);
+  hls.on(HlsClass.Events.MEDIA_DETACHING, onMediaDetaching);
+  hls.on(HlsClass.Events.DESTROYING, onDestroying);
+  attachMedia();
+  return {
+    startAttempt() {
+      if (destroyed) return;
+      if (session) session.startAttempt();
+      else pendingAttempt = true;
+    },
+    sourceChanged() {
+      if (destroyed) return;
+      pendingAttempt = false;
+      session?.sourceChanged();
+    },
+    destroy,
+  };
+}

package/src/http.ts

@@ -0,0 +1,43 @@
+import type { AnalyticsDestination, ChunkifyPlayerAnalyticsEvent } from "./core.js";
+
+/** POST each event as JSON to a customer endpoint. No credentials or custom headers are accepted. */
+export function createHttpAdapter(
+  endpoint: string,
+  mapEvent: (event: ChunkifyPlayerAnalyticsEvent) => unknown = (event) => event,
+): AnalyticsDestination {
+  if (typeof mapEvent !== "function") throw new TypeError("HTTP adapter mapper must be a function.");
+  if (typeof endpoint !== "string" || !endpoint || endpoint.startsWith("//")) {
+    throw new TypeError("HTTP adapter requires an HTTPS URL or a root-relative path.");
+  }
+  const rootRelative = endpoint.startsWith("/");
+  const absolute = /^[a-z][a-z\d+.-]*:/i.test(endpoint);
+  let url: URL;
+  try {
+    url = new URL(endpoint, "https://chunkify.invalid");
+  } catch {
+    throw new TypeError("HTTP adapter requires a valid endpoint URL.");
+  }
+  const localHttp = url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if ((!rootRelative && !absolute) ||
+      (rootRelative && url.origin !== "https://chunkify.invalid") ||
+      (!rootRelative && url.protocol !== "https:" && !localHttp) ||
+      url.username || url.password || url.search || url.hash) {
+    throw new TypeError("HTTP adapter requires a root-relative path or HTTPS URL without credentials or query parameters (HTTP is allowed on loopback).");
+  }
+  return {
+    async send(event: ChunkifyPlayerAnalyticsEvent) {
+      const body = JSON.stringify(mapEvent(event));
+      if (body === undefined) throw new TypeError("HTTP adapter mapper must return a JSON value.");
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        credentials: "omit",
+        referrerPolicy: "no-referrer",
+        redirect: "error",
+        keepalive: event.event_name === "chunkify.video.view_ended",
+      });
+      if (!response.ok) throw new Error(`Analytics endpoint returned HTTP ${response.status}.`);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { attachAnalytics } from "./core.js";
+export type { AnalyticsEventType, AnalyticsEndReason, AnalyticsErrorCategory, AnalyticsStartupOutcome,
+  AnalyticsPlaybackState, AnalyticsEventEnvelope, AnalyticsViewEvent, AnalyticsPlaybackStateEvent,
+  AnalyticsRenditionEvent, RenditionPlayingTime, AnalyticsRendition, ViewMetrics, ChunkifyPlayerAnalyticsEvent,
+  AnalyticsDestination, AnalyticsConfig, AnalyticsOptions, AnalyticsConnectorSnapshot,
+  AnalyticsConnectorError, AnalyticsConnector, AnalyticsSession } from "./core.js";
+export { createEventMapper } from "./mapper.js";
+export { monitor, type MonitorSession } from "./monitor.js";
+export { monitorHlsJs } from "./hlsjs.js";
+export { monitorVideoJs } from "./videojs.js";
+export { monitorShaka } from "./shaka.js";

package/src/mapper.ts

@@ -0,0 +1,22 @@
+import type { AnalyticsPlaybackStateEvent, AnalyticsRenditionEvent, AnalyticsViewEvent,
+  ChunkifyPlayerAnalyticsEvent } from "./core.js";
+
+type EventField = keyof AnalyticsViewEvent | keyof AnalyticsPlaybackStateEvent | keyof AnalyticsRenditionEvent;
+type FieldSelector = EventField | ((event: ChunkifyPlayerAnalyticsEvent) => unknown);
+type EventFieldValue<Key extends EventField> = ChunkifyPlayerAnalyticsEvent extends infer Event
+  ? Event extends unknown ? Key extends keyof Event ? Event[Key] : undefined : never
+  : never;
+type SelectedValue<Selector> = Selector extends EventField
+  ? EventFieldValue<Selector>
+  : Selector extends (event: ChunkifyPlayerAnalyticsEvent) => infer Value ? Value : never;
+
+/** Select, rename, or calculate fields for a destination without changing the source event. */
+export function createEventMapper<const Fields extends Record<string, FieldSelector>>(fields: Fields):
+  (event: ChunkifyPlayerAnalyticsEvent) => { [Name in keyof Fields]: SelectedValue<Fields[Name]> } {
+  const entries = Object.entries(fields);
+  return (event) => Object.fromEntries(entries.flatMap(([name, source]) => {
+    if (typeof source !== "function" && !(source in event)) return [];
+    const value = typeof source === "function" ? source(event) : event[source as keyof typeof event];
+    return value === undefined ? [] : [[name, value]];
+  })) as { [Name in keyof Fields]: SelectedValue<Fields[Name]> };
+}

package/src/monitor.ts

@@ -0,0 +1,15 @@
+import { attachAnalytics, type AnalyticsOptions, type AnalyticsSession } from "./core.js";
+import { attachPlayerAnalytics, type MediaPlayerHost } from "./player.js";
+
+export type MonitorSession = Pick<AnalyticsSession, "startAttempt" | "sourceChanged" | "destroy">;
+
+/** Start analytics for a video element or a Chunkify Player. */
+export function monitor(target: HTMLVideoElement | MediaPlayerHost, options: AnalyticsOptions): MonitorSession {
+  const view = target?.ownerDocument?.defaultView;
+  if (view && target instanceof view.HTMLVideoElement) return attachAnalytics(target, options);
+  if (view && target instanceof view.HTMLElement
+    && target.localName === "chunkify-player" && "media" in target) {
+    return attachPlayerAnalytics(target as MediaPlayerHost, options);
+  }
+  throw new TypeError("Analytics supports a <video> or <chunkify-player> element.");
+}

package/src/options.ts

@@ -0,0 +1,28 @@
+import type { AnalyticsOptions } from "./core.js";
+import { analyticsEventTypes } from "./event-types.js";
+
+const eventTypes = new Set<string>(analyticsEventTypes);
+
+/** Validate options before installing any media or engine listeners. */
+export function assertAnalyticsOptions(options: AnalyticsOptions): void {
+  if (typeof options.videoId !== "string" || !options.videoId.trim()) {
+    throw new TypeError("Analytics requires a non-empty videoId.");
+  }
+  if (!Array.isArray(options.destinations) || options.destinations.length === 0 ||
+      !Array.from(options.destinations).every((destination) => destination && typeof destination.send === "function")) {
+    throw new TypeError("Analytics requires a non-empty destinations array with send functions.");
+  }
+  if ((options.environment !== undefined && typeof options.environment !== "string") ||
+      (options.viewerId !== undefined && typeof options.viewerId !== "string")) {
+    throw new TypeError("Analytics environment and viewerId must be strings when provided.");
+  }
+  if (options.snapshotIntervalMs !== undefined &&
+      (!Number.isSafeInteger(options.snapshotIntervalMs) || options.snapshotIntervalMs < 1000 ||
+       options.snapshotIntervalMs > 2_147_483_647)) {
+    throw new TypeError("Analytics snapshotIntervalMs must be an integer from 1000 to 2147483647 ms.");
+  }
+  if (options.includeEvents !== undefined &&
+      (!Array.isArray(options.includeEvents) || !options.includeEvents.every((event) => eventTypes.has(event)))) {
+    throw new TypeError("Analytics includeEvents must be an array of supported event types.");
+  }
+}

package/src/otlp.ts

@@ -0,0 +1,70 @@
+import type { AnalyticsDestination, ChunkifyPlayerAnalyticsEvent } from "./core.js";
+import { createHttpAdapter } from "./http.js";
+
+type OtlpValue =
+  | { stringValue: string }
+  | { boolValue: boolean }
+  | { intValue: string }
+  | { doubleValue: number }
+  | { arrayValue: { values: OtlpValue[] } }
+  | { kvlistValue: { values: OtlpAttribute[] } };
+
+interface OtlpAttribute {
+  key: string;
+  value: OtlpValue;
+}
+
+function toOtlpValue(value: unknown): OtlpValue | null {
+  if (value == null) return null;
+  if (typeof value === "string") return { stringValue: value };
+  if (typeof value === "boolean") return { boolValue: value };
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return null;
+    return Number.isSafeInteger(value) ? { intValue: String(value) } : { doubleValue: value };
+  }
+  if (Array.isArray(value)) {
+    return { arrayValue: { values: value.map(toOtlpValue).filter((item): item is OtlpValue => item !== null) } };
+  }
+  if (typeof value === "object") return { kvlistValue: { values: toOtlpAttributes(value) } };
+  return null;
+}
+
+function toOtlpAttributes(record: object): OtlpAttribute[] {
+  return Object.entries(record).flatMap(([key, value]) => {
+    const encoded = toOtlpValue(value);
+    return encoded === null ? [] : [{ key, value: encoded }];
+  });
+}
+
+function toOtlpLogRequest(event: ChunkifyPlayerAnalyticsEvent, attributes: object) {
+  const occurredAtMs = Date.parse(event.occurred_at);
+  if (!Number.isFinite(occurredAtMs)) throw new TypeError("OTLP adapter requires a valid occurred_at timestamp.");
+
+  return {
+    resourceLogs: [{
+      scopeLogs: [{
+        scope: { name: "@chunkify/analytics", version: event.sdk_version },
+        logRecords: [{
+          timeUnixNano: String(BigInt(occurredAtMs) * 1_000_000n),
+          eventName: event.event_name,
+          attributes: toOtlpAttributes(attributes),
+        }],
+      }],
+    }],
+  };
+}
+
+/** Send each analytics event as an OTLP/HTTP JSON log record to a customer gateway. */
+export function createOtlpAdapter(
+  endpoint: string,
+  mapAttributes: (event: ChunkifyPlayerAnalyticsEvent) => object = (event) => event,
+): AnalyticsDestination {
+  if (typeof mapAttributes !== "function") throw new TypeError("OTLP attribute mapper must be a function.");
+  return createHttpAdapter(endpoint, (event) => {
+    const attributes = mapAttributes(event);
+    if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) {
+      throw new TypeError("OTLP attribute mapper must return an object.");
+    }
+    return toOtlpLogRequest(event, attributes);
+  });
+}

package/src/player.ts

@@ -0,0 +1,96 @@
+import { attachAnalytics, type AnalyticsOptions, type AnalyticsSession } from "./core.js";
+import { createHlsJsConnector, type HlsJsAnalyticsConnector } from "./hlsjs.js";
+import type Hls from "hls.js";
+
+/** The public surface needed from a player that can replace its media element. */
+export interface MediaPlayerHost extends HTMLElement {
+  readonly media: HTMLMediaElement;
+}
+
+/** Attach the standalone media collector to a Chunkify Player. */
+export function attachPlayerAnalytics(
+  player: MediaPlayerHost,
+  options: AnalyticsOptions,
+): Pick<AnalyticsSession, "startAttempt" | "sourceChanged" | "destroy"> {
+  let media = player.media;
+  let session = attachAnalytics(media, options);
+  let destroyed = false;
+  let activeHls: Hls | null = null;
+  let connector: HlsJsAnalyticsConnector | null = null;
+  let checkTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearCheckTimer = () => {
+    if (checkTimer === null) return;
+    clearTimeout(checkTimer);
+    checkTimer = null;
+  };
+  const detachConnector = () => {
+    session.setConnector(null);
+    connector?.destroy();
+    connector = null;
+    activeHls = null;
+  };
+  const syncConnector = () => {
+    if (destroyed) return;
+    const hls = media.localName === "hls-video"
+      ? (media as HTMLMediaElement & { api?: Hls | null }).api ?? null : null;
+    if (hls === activeHls) return;
+    detachConnector();
+    if (!hls) return;
+    try {
+      const next = createHlsJsConnector(hls);
+      session.setConnector(next);
+      connector = next;
+      activeHls = hls;
+    } catch {
+      // Analytics must not interrupt playback if an engine is unavailable.
+    }
+  };
+  const scheduleConnectorCheck = () => {
+    clearCheckTimer();
+    checkTimer = globalThis.setTimeout(() => {
+      checkTimer = null;
+      syncConnector();
+    }, 0);
+  };
+  const observer = new MutationObserver(scheduleConnectorCheck);
+  const bindMedia = () => {
+    media.addEventListener("loadstart", syncConnector);
+    observer.observe(media, { attributes: true, attributeFilter: ["src"] });
+    syncConnector();
+    // hls-video-element creates its hls.js instance after setting src.
+    scheduleConnectorCheck();
+  };
+  const unbindMedia = () => {
+    clearCheckTimer();
+    observer.disconnect();
+    media.removeEventListener("loadstart", syncConnector);
+  };
+  bindMedia();
+
+  const onMediaChange = () => {
+    const next = player.media;
+    if (destroyed || next === media) return;
+    session.sourceChanged();
+    unbindMedia();
+    session.destroy();
+    detachConnector();
+    media = next;
+    session = attachAnalytics(media, options);
+    bindMedia();
+  };
+  player.addEventListener("mediachange", onMediaChange);
+
+  return {
+    startAttempt() { if (!destroyed) session.startAttempt(); },
+    sourceChanged() { if (!destroyed) session.sourceChanged(); },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      player.removeEventListener("mediachange", onMediaChange);
+      unbindMedia();
+      session.destroy();
+      detachConnector();
+    },
+  };
+}

package/src/posthog.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsDestination, ChunkifyPlayerAnalyticsEvent } from "./core.js";
+
+/** The small part of an initialized PostHog browser client needed by this adapter. */
+export interface PostHogCompatibleClient {
+  capture(name: string, properties: Record<string, unknown>): unknown;
+}
+
+/** Send one PostHog event for each analytics event. */
+export function createPostHogAdapter(
+  client: PostHogCompatibleClient,
+  mapEvent: (event: ChunkifyPlayerAnalyticsEvent) => Record<string, unknown> = (event) => ({ ...event }),
+): AnalyticsDestination {
+  if (!client || typeof client.capture !== "function") {
+    throw new TypeError("PostHog adapter requires an initialized client with capture().");
+  }
+  if (typeof mapEvent !== "function") {
+    throw new TypeError("PostHog event mapper must be a function.");
+  }
+  return {
+    send(event: ChunkifyPlayerAnalyticsEvent) {
+      client.capture(event.event_name, mapEvent(event));
+    },
+  };
+}