unified-video-framework 1.4.157 → 1.4.159

package/packages/core/src/analytics/adapters/PlayerAnalyticsAdapter.ts

@@ -0,0 +1,156 @@
+/**
+ * PlayerAnalyticsAdapter - Adapter for integrating with player analytics API
+ * Maps internal analytics events to the player analytics system format
+ * Implements BaseAnalyticsProvider interface
+ */
+
+import { 
+  AnalyticsEventData,
+  PlayerSessionInfo,
+  BaseAnalyticsProvider,
+  PlayerAnalyticsConfig
+} from '../types/AnalyticsTypes';
+import { deviceDetection } from '../utils/DeviceDetection';
+
+export class PlayerAnalyticsAdapter implements BaseAnalyticsProvider {
+  public name: string;
+  public enabled: boolean;
+  private config: PlayerAnalyticsConfig;
+  private currentSessionId: string | null = null;
+  private eventQueue: AnalyticsEventData[] = [];
+  private flushTimer: any = null;
+
+  constructor(name: string, config: PlayerAnalyticsConfig) {
+    this.name = name;
+    this.enabled = true;
+    this.config = config;
+  }
+
+  async initialize(): Promise<void> {
+    // No initialization needed
+  }
+
+  async startSession(sessionInfo: PlayerSessionInfo): Promise<string> {
+    const sessionId = `sess_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.currentSessionId = sessionId;
+
+    const event: AnalyticsEventData = {
+      eventType: 'session_start',
+      timestamp: Date.now(),
+      video: sessionInfo.initialVideo,
+      device: deviceDetection.getDeviceInfo(),
+      metadata: {
+        sessionId,
+        playerId: this.config.playerId,
+        userId: sessionInfo.userId,
+        customData: sessionInfo.customData
+      }
+    };
+
+    await this.trackEvent(event);
+    return sessionId;
+  }
+
+  async trackEvent(event: AnalyticsEventData): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    this.eventQueue.push(event);
+
+    // Auto-flush if batch size reached
+    if (this.eventQueue.length >= (this.config.batchSize || 10)) {
+      await this.flush();
+    } else {
+      // Schedule flush
+      this.scheduleFlush();
+    }
+  }
+
+  async endSession(): Promise<void> {
+    if (this.currentSessionId) {
+      const event: AnalyticsEventData = {
+        eventType: 'session_end',
+        timestamp: Date.now(),
+        metadata: {
+          sessionId: this.currentSessionId,
+          playerId: this.config.playerId
+        }
+      };
+
+      await this.trackEvent(event);
+      await this.flush();
+      this.currentSessionId = null;
+    }
+  }
+
+  async flush(): Promise<void> {
+    if (this.eventQueue.length === 0) {
+      return;
+    }
+
+    const events = [...this.eventQueue];
+    this.eventQueue = [];
+
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    try {
+      const payload = {
+        session: {
+          sessionId: this.currentSessionId || 'unknown',
+          playerId: this.config.playerId,
+          timestamp: Date.now(),
+          customData: {}
+        },
+        events
+      };
+
+      const response = await fetch(`${this.config.baseUrl}/analytics/player/ingest`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.config.apiKey}`,
+          ...(this.config.tenantId && { 'X-Tenant-ID': this.config.tenantId })
+        },
+        body: JSON.stringify(payload)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Analytics API error: ${response.status}`);
+      }
+    } catch (error) {
+      console.error('Failed to send analytics events:', error);
+      // Re-queue events on failure
+      this.eventQueue = [...events, ...this.eventQueue];
+    }
+  }
+
+  async destroy(): Promise<void> {
+    if (this.currentSessionId) {
+      await this.endSession();
+    }
+
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+
+    // Final flush attempt
+    if (this.eventQueue.length > 0) {
+      await this.flush();
+    }
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushTimer) {
+      return;
+    }
+
+    this.flushTimer = setTimeout(() => {
+      this.flush().catch(console.error);
+    }, (this.config.flushInterval || 30) * 1000);
+  }
+}

package/packages/core/src/analytics/core/AnalyticsProvider.ts

@@ -0,0 +1,169 @@
+/**
+ * AnalyticsProvider - Base provider and factory functions
+ */
+
+import {
+  BaseAnalyticsProvider,
+  AnalyticsEventData,
+  PlayerSessionInfo,
+  AnalyticsProviderType,
+  DynamicAnalyticsConfig,
+  PlayerAnalyticsConfig
+} from '../types/AnalyticsTypes';
+import { PlayerAnalyticsAdapter } from '../adapters/PlayerAnalyticsAdapter';
+
+/**
+ * Abstract base class for analytics providers
+ */
+export abstract class AnalyticsProvider implements BaseAnalyticsProvider {
+  public name: string;
+  public enabled: boolean;
+
+  constructor(name: string, enabled = true) {
+    this.name = name;
+    this.enabled = enabled;
+  }
+
+  abstract initialize(): Promise<void>;
+  abstract trackEvent(event: AnalyticsEventData): Promise<void>;
+  abstract startSession(sessionInfo: PlayerSessionInfo): Promise<string>;
+  abstract endSession(): Promise<void>;
+  abstract flush(): Promise<void>;
+  abstract destroy(): Promise<void>;
+}
+
+/**
+ * Create analytics provider based on type and configuration
+ */
+export function createAnalyticsProvider(
+  type: AnalyticsProviderType,
+  name: string,
+  config: any
+): BaseAnalyticsProvider {
+  switch (type) {
+    case AnalyticsProviderType.PLAYER_ANALYTICS:
+      return new PlayerAnalyticsAdapter(name, config);
+    
+    case AnalyticsProviderType.CUSTOM:
+      if (config.factory) {
+        return config.factory(config);
+      }
+      throw new Error(`Custom provider "${name}" requires a factory function`);
+    
+    case AnalyticsProviderType.GOOGLE_ANALYTICS:
+    case AnalyticsProviderType.ADOBE_ANALYTICS:
+    default:
+      throw new Error(`Analytics provider type "${type}" is not supported yet`);
+  }
+}
+
+/**
+ * Get default analytics configuration
+ */
+export function getDefaultAnalyticsConfig(): DynamicAnalyticsConfig {
+  return {
+    enabled: true,
+    providers: [],
+    globalSettings: {
+      enableConsoleLogging: false,
+      enableErrorReporting: true,
+      sessionTimeout: 60, // 60 minutes
+      defaultBatchSize: 10,
+      defaultFlushInterval: 30, // 30 seconds
+      retryAttempts: 3,
+      retryDelay: 1000 // 1 second
+    }
+  };
+}
+
+/**
+ * Helper function to create Player Analytics provider config
+ */
+export function createPlayerAnalyticsProviderConfig(
+  baseUrl: string,
+  apiKey: string,
+  playerId: string,
+  options: Partial<PlayerAnalyticsConfig> = {}
+): PlayerAnalyticsConfig {
+  return {
+    baseUrl,
+    apiKey,
+    playerId,
+    tenantId: options.tenantId,
+    heartbeatInterval: options.heartbeatInterval || 10,
+    batchSize: options.batchSize || 10,
+    flushInterval: options.flushInterval || 30,
+    enableOfflineStorage: options.enableOfflineStorage !== false,
+    maxRetries: options.maxRetries || 3,
+    retryDelay: options.retryDelay || 1000
+  };
+}
+
+/**
+ * Validate analytics configuration
+ */
+export function validateAnalyticsConfig(config: DynamicAnalyticsConfig): void {
+  if (!config) {
+    throw new Error('Analytics configuration is required');
+  }
+
+  if (typeof config.enabled !== 'boolean') {
+    throw new Error('Analytics configuration must specify enabled state');
+  }
+
+  if (!Array.isArray(config.providers)) {
+    throw new Error('Analytics configuration must include providers array');
+  }
+
+  config.providers.forEach((provider, index) => {
+    if (!provider.name) {
+      throw new Error(`Provider at index ${index} must have a name`);
+    }
+    
+    if (!provider.type) {
+      throw new Error(`Provider "${provider.name}" must have a type`);
+    }
+    
+    if (typeof provider.enabled !== 'boolean') {
+      throw new Error(`Provider "${provider.name}" must specify enabled state`);
+    }
+
+    if (provider.type === AnalyticsProviderType.PLAYER_ANALYTICS) {
+      validatePlayerAnalyticsConfig(provider.config);
+    }
+  });
+}
+
+/**
+ * Validate Player Analytics specific configuration
+ */
+function validatePlayerAnalyticsConfig(config: PlayerAnalyticsConfig): void {
+  if (!config.baseUrl) {
+    throw new Error('Player Analytics provider requires baseUrl');
+  }
+  
+  if (!config.apiKey) {
+    throw new Error('Player Analytics provider requires apiKey');
+  }
+  
+  if (!config.playerId) {
+    throw new Error('Player Analytics provider requires playerId');
+  }
+}
+
+/**
+ * Merge analytics configurations
+ */
+export function mergeAnalyticsConfigs(
+  defaultConfig: DynamicAnalyticsConfig,
+  userConfig: Partial<DynamicAnalyticsConfig>
+): DynamicAnalyticsConfig {
+  return {
+    enabled: userConfig.enabled !== undefined ? userConfig.enabled : defaultConfig.enabled,
+    providers: userConfig.providers || defaultConfig.providers,
+    globalSettings: {
+      ...defaultConfig.globalSettings,
+      ...userConfig.globalSettings
+    }
+  };
+}

package/packages/core/src/analytics/core/DynamicAnalyticsManager.ts

@@ -0,0 +1,199 @@
+/**
+ * DynamicAnalyticsManager - Main analytics system
+ * Manages multiple analytics providers dynamically
+ */
+
+import {
+  DynamicAnalyticsConfig,
+  AnalyticsProviderType,
+  BaseAnalyticsProvider,
+  AnalyticsEventData,
+  VideoInfo,
+  PlayerState,
+  PlayerSessionInfo
+} from '../types/AnalyticsTypes';
+import { createAnalyticsProvider } from './AnalyticsProvider';
+
+export class DynamicAnalyticsManager {
+  private config: DynamicAnalyticsConfig;
+  private providers: Map<string, BaseAnalyticsProvider> = new Map();
+  private currentSessionId: string | null = null;
+  private enabled: boolean;
+
+  constructor(config: DynamicAnalyticsConfig) {
+    this.config = config;
+    this.enabled = config.enabled;
+    this.initializeProviders();
+  }
+
+  private async initializeProviders(): Promise<void> {
+    for (const providerConfig of this.config.providers) {
+      if (providerConfig.enabled) {
+        try {
+          const provider = createAnalyticsProvider(
+            providerConfig.type,
+            providerConfig.name,
+            providerConfig.config
+          );
+          
+          await provider.initialize();
+          this.providers.set(providerConfig.name, provider);
+        } catch (error) {
+          console.error(`Failed to initialize analytics provider "${providerConfig.name}":`, error);
+        }
+      }
+    }
+  }
+
+  startSession(videoInfo: VideoInfo, userInfo: any = {}): string {
+    if (!this.enabled) {
+      return '';
+    }
+
+    const sessionId = `sess_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.currentSessionId = sessionId;
+
+    const sessionInfo: PlayerSessionInfo = {
+      sessionId,
+      playerId: 'default',
+      startTime: Date.now(),
+      userId: userInfo.userId,
+      userType: userInfo.userType,
+      customData: userInfo,
+      initialVideo: videoInfo
+    };
+
+    this.providers.forEach(async (provider) => {
+      if (provider.enabled) {
+        try {
+          await provider.startSession(sessionInfo);
+        } catch (error) {
+          console.error(`Provider "${provider.name}" failed to start session:`, error);
+        }
+      }
+    });
+
+    return sessionId;
+  }
+
+  async endSession(): Promise<void> {
+    if (!this.currentSessionId || !this.enabled) {
+      return;
+    }
+
+    const promises = Array.from(this.providers.values()).map(async (provider) => {
+      if (provider.enabled) {
+        try {
+          await provider.endSession();
+        } catch (error) {
+          console.error(`Provider "${provider.name}" failed to end session:`, error);
+        }
+      }
+    });
+
+    await Promise.allSettled(promises);
+    this.currentSessionId = null;
+  }
+
+  trackEvent(eventType: string, playerState?: PlayerState, customData?: any): void {
+    if (!this.enabled || !this.currentSessionId) {
+      return;
+    }
+
+    const event: AnalyticsEventData = {
+      eventType,
+      timestamp: Date.now(),
+      currentTime: playerState?.currentTime,
+      player: playerState,
+      custom: customData
+    };
+
+    this.providers.forEach(async (provider) => {
+      if (provider.enabled) {
+        try {
+          await provider.trackEvent(event);
+        } catch (error) {
+          console.error(`Provider "${provider.name}" failed to track event:`, error);
+        }
+      }
+    });
+  }
+
+  trackCustomEvent(eventType: string, data: any): void {
+    if (!this.enabled) {
+      return;
+    }
+
+    const event: AnalyticsEventData = {
+      eventType: 'custom',
+      timestamp: Date.now(),
+      custom: { type: eventType, ...data }
+    };
+
+    this.providers.forEach(async (provider) => {
+      if (provider.enabled) {
+        try {
+          await provider.trackEvent(event);
+        } catch (error) {
+          console.error(`Provider "${provider.name}" failed to track custom event:`, error);
+        }
+      }
+    });
+  }
+
+  addProvider(name: string, type: AnalyticsProviderType, config: any): void {
+    try {
+      const provider = createAnalyticsProvider(type, name, config);
+      provider.initialize().then(() => {
+        this.providers.set(name, provider);
+      });
+    } catch (error) {
+      console.error(`Failed to add provider "${name}":`, error);
+    }
+  }
+
+  async removeProvider(name: string): Promise<void> {
+    const provider = this.providers.get(name);
+    if (provider) {
+      try {
+        await provider.destroy();
+        this.providers.delete(name);
+      } catch (error) {
+        console.error(`Failed to remove provider "${name}":`, error);
+      }
+    }
+  }
+
+  toggleProvider(name: string, enabled: boolean): void {
+    const provider = this.providers.get(name);
+    if (provider) {
+      provider.enabled = enabled;
+    }
+  }
+
+  async initialize(): Promise<void> {
+    // Already done in constructor, but this method is needed for interface compatibility
+    return Promise.resolve();
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  async destroy(): Promise<void> {
+    if (this.currentSessionId) {
+      await this.endSession();
+    }
+
+    const promises = Array.from(this.providers.values()).map(async (provider) => {
+      try {
+        await provider.destroy();
+      } catch (error) {
+        console.error(`Provider "${provider.name}" failed to destroy:`, error);
+      }
+    });
+
+    await Promise.allSettled(promises);
+    this.providers.clear();
+  }
+}

package/packages/core/src/analytics/core/EventBatcher.ts

@@ -0,0 +1,160 @@
+/**
+ * EventBatcher - Batches analytics events for efficient network usage
+ */
+
+import { AnalyticsEventData } from '../types/AnalyticsTypes';
+
+export interface BatcherConfig {
+  maxSize?: number;
+  flushInterval?: number; // in milliseconds
+  maxWaitTime?: number; // in milliseconds
+  onFlush: (events: AnalyticsEventData[]) => Promise<void>;
+  onError?: (error: Error, events: AnalyticsEventData[]) => void;
+}
+
+export class EventBatcher {
+  private events: AnalyticsEventData[] = [];
+  private flushTimer: any = null;
+  private maxWaitTimer: any = null;
+  private destroyed = false;
+
+  private readonly maxSize: number;
+  private readonly flushInterval: number;
+  private readonly maxWaitTime: number;
+  private readonly onFlush: (events: AnalyticsEventData[]) => Promise<void>;
+  private readonly onError?: (error: Error, events: AnalyticsEventData[]) => void;
+
+  constructor(config: BatcherConfig) {
+    this.maxSize = config.maxSize || 10;
+    this.flushInterval = config.flushInterval || 30000; // 30 seconds
+    this.maxWaitTime = config.maxWaitTime || 60000; // 60 seconds
+    this.onFlush = config.onFlush;
+    this.onError = config.onError;
+  }
+
+  /**
+   * Add an event to the batch
+   */
+  addEvent(event: AnalyticsEventData): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.events.push(event);
+
+    // Start max wait timer if this is the first event
+    if (this.events.length === 1) {
+      this.startMaxWaitTimer();
+    }
+
+    // Flush if batch is full
+    if (this.events.length >= this.maxSize) {
+      this.flush();
+    } else {
+      // Reset flush timer
+      this.resetFlushTimer();
+    }
+  }
+
+  /**
+   * Manually flush all events
+   */
+  async flush(): Promise<void> {
+    if (this.destroyed || this.events.length === 0) {
+      return;
+    }
+
+    const eventsToFlush = [...this.events];
+    this.events = [];
+    this.clearTimers();
+
+    try {
+      await this.onFlush(eventsToFlush);
+    } catch (error) {
+      if (this.onError) {
+        this.onError(error as Error, eventsToFlush);
+      } else {
+        console.error('EventBatcher flush error:', error);
+      }
+    }
+  }
+
+  /**
+   * Get current batch size
+   */
+  getBatchSize(): number {
+    return this.events.length;
+  }
+
+  /**
+   * Check if batcher has pending events
+   */
+  hasPendingEvents(): boolean {
+    return this.events.length > 0;
+  }
+
+  /**
+   * Destroy the batcher and flush remaining events
+   */
+  async destroy(): Promise<void> {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.destroyed = true;
+    this.clearTimers();
+
+    // Flush remaining events
+    if (this.events.length > 0) {
+      await this.flush();
+    }
+  }
+
+  private resetFlushTimer(): void {
+    this.clearFlushTimer();
+    
+    this.flushTimer = setTimeout(() => {
+      this.flush();
+    }, this.flushInterval);
+  }
+
+  private startMaxWaitTimer(): void {
+    this.clearMaxWaitTimer();
+    
+    this.maxWaitTimer = setTimeout(() => {
+      this.flush();
+    }, this.maxWaitTime);
+  }
+
+  private clearFlushTimer(): void {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  private clearMaxWaitTimer(): void {
+    if (this.maxWaitTimer) {
+      clearTimeout(this.maxWaitTimer);
+      this.maxWaitTimer = null;
+    }
+  }
+
+  private clearTimers(): void {
+    this.clearFlushTimer();
+    this.clearMaxWaitTimer();
+  }
+}
+
+/**
+ * Create an EventBatcher with default configuration
+ */
+export function createEventBatcher(
+  onFlush: (events: AnalyticsEventData[]) => Promise<void>,
+  options: Partial<BatcherConfig> = {}
+): EventBatcher {
+  return new EventBatcher({
+    onFlush,
+    ...options
+  });
+}