better typing for media properties

packages/core/src/index.ts

@@ -42,6 +42,7 @@ export type {
   SessionContext,
   MediaAdapterApi,
   MediaAdapterInterface,
+  MediaEventProperties,
   MediaEventType,
 } from './types';
 export type { TanilyticsConfig } from './config/types';

packages/core/src/types.ts

@@ -74,12 +74,34 @@ export interface IngestionPayload {
  */
 export type TrackingEvent = IngestionEvent;
 
+/**
+ * Standard media event properties emitted by media adapters.
+ * These fields are extracted server-side for media engagement rollups.
+ */
+export interface MediaEventProperties extends EventProperties {
+  provider?: string;
+  video_id?: string;
+  video_url?: string;
+  title?: string;
+  current_time?: number;
+  duration?: number;
+  percent?: number;
+  buffered_fraction?: number;
+  delta_seconds?: number;
+  from_time?: number;
+  to_time?: number;
+  progress_percent?: number;
+}
+
 /**
  * Minimal API surface the core tracker exposes to media adapters.
  * Adapter events flow through the normal privacy, session, and queue pipeline.
  */
 export interface MediaAdapterApi {
-  trackMedia(eventType: MediaEventType, properties?: EventProperties): void;
+  trackMedia(
+    eventType: MediaEventType,
+    properties?: MediaEventProperties,
+  ): void;
 }
 
 /**

packages/media-adapters/youtube/src/lib/events.ts

@@ -14,7 +14,7 @@ import type {
   YouTubePlayerEvent,
   VideoSnapshot,
 } from './types';
-import type { EventProperties } from 'tanilytics';
+import type { MediaEventProperties } from 'tanilytics';
 
 interface CreatePlayerEventHandlersOptions {
   adapterApi: YouTubeMediaAdapterApi;
@@ -620,14 +620,14 @@ function emit(
   adapterApi: YouTubeMediaAdapterApi,
   context: PlaybackContext,
   eventType: YouTubeMediaEventType,
-  extraProperties?: EventProperties,
+  extraProperties?: MediaEventProperties,
 ): void {
   if (context.player === null) {
     return;
   }
 
   const snapshot = readSnapshot(context.player);
-  const properties: EventProperties = { provider: 'youtube' };
+  const properties: MediaEventProperties = { provider: 'youtube' };
 
   if (snapshot.videoId !== undefined) {
     properties.video_id = snapshot.videoId;

packages/media-adapters/youtube/src/lib/types.ts

@@ -1,4 +1,4 @@
-import type { EventProperties } from 'tanilytics';
+import type { MediaEventProperties } from 'tanilytics';
 
 export type YouTubeMediaEventType =
   | 'media_play'
@@ -82,7 +82,7 @@ export interface PlaybackContext {
 export interface YouTubeMediaAdapterApi {
   trackMedia(
     eventType: YouTubeMediaEventType,
-    properties?: EventProperties,
+    properties?: MediaEventProperties,
   ): void;
 }