@newrelic/video-core 5.0.1 → 5.1.0

package/src/connectedDevice/{connectedDeviceHarvester.js → connectedDeviceHarvester.ts}

@@ -10,6 +10,7 @@ import {
   CD_CONNECT_RETRY_DELAY_MS,
   CD_CONNECT_TIMEOUT_MS,
   CD_DATA_TIMEOUT_MS,
+  VegaEndpoint,
 } from "./connectedDeviceConstants";
 import {
   bufferEventWithQoeDedup,
@@ -17,9 +18,27 @@ import {
   partitionByQoeCycle,
   applyQoeDirtyFilter,
 } from "../utils/qoeFilters";
-import { createHarvestTimer } from "../utils/harvestTimer";
+import { createHarvestTimer, HarvestTimer } from "../utils/harvestTimer";
 import { applyObfuscationRules } from "../obfuscate";
 import Log from "../log";
+import { EventAttributes } from "../utils/eventBuilder";
+
+export interface ConnectedDeviceHarvesterOptions {
+  accountId?: string;
+  applicationToken: string;
+  endpoint: string;
+  deviceInfo?: Record<string, any>;
+}
+
+interface DeviceInfo {
+  uuid: any;
+  osVersion: any;
+  deviceModel: any;
+  deviceManufacturer: any;
+  osBuild: any;
+  appBuild: any;
+  architecture: any;
+}
 
 /**
  * Generic NR mobile-collector harvester for the connected-device pipeline
@@ -32,11 +51,29 @@ import Log from "../log";
  *
  */
 export default class ConnectedDeviceHarvester {
+  accountId?: string;
+  applicationToken: string;
+  endpoint: VegaEndpoint;
+  harvestInterval: number;
+  maxBufferSize: number;
+  deviceInfo: DeviceInfo;
+  eventBuffer: NrVideoEventAggregator;
+  dataToken: string | null;
+  isHarvesting: boolean;
+  isDisposed: boolean;
+  _isFetchingToken: boolean;
+  timer: HarvestTimer;
+  qoeCycleCount: number;
+  forceQoeNextCycle: boolean;
+  beforeDrainCallback: (() => void) | null;
+  _lastSentQoeKpis: Record<string, any>;
+  _connectAttempt: number;
+
   /**
    * @param {object} opts
    * @param {string} [opts.accountId]         Captured for parity with CAF; not transmitted.
-   * @param {string} opts.applicationToken    Sent as `X-App-License-Key` header. 
-   * @param {string} opts.endpoint            One of `US`, `EU`, `staging`. 
+   * @param {string} opts.applicationToken    Sent as `X-App-License-Key` header.
+   * @param {string} opts.endpoint            One of `US`, `EU`, `staging`.
    * @param {object} [opts.deviceInfo]        Customer-collected device identity. Any of:
    *   uuid, osVersion, deviceModel, deviceManufacturer, osBuild, appBuild, architecture.
    *   Each field optional — missing values fall back to placeholders from
@@ -52,18 +89,18 @@ export default class ConnectedDeviceHarvester {
     applicationToken,
     endpoint,
     deviceInfo,
-  } = {}) {
+  }: Partial<ConnectedDeviceHarvesterOptions> = {}) {
     if (!applicationToken) {
-      throw new Error("applicationToken is required"); 
+      throw new Error("applicationToken is required");
     }
     const normalizedEndpoint = endpoint?.toLowerCase();
-    if (!(normalizedEndpoint in ENDPOINT_URL)) {
+    if (!((normalizedEndpoint as string) in ENDPOINT_URL)) {
       throw new Error("Invalid endpoint");
     }
 
     this.accountId = accountId;
     this.applicationToken = applicationToken;
-    this.endpoint = normalizedEndpoint;
+    this.endpoint = normalizedEndpoint as VegaEndpoint;
     this.harvestInterval = DEFAULT_HARVEST_TIME;
     this.maxBufferSize = DEFAULT_BUFFER_SIZE;
 
@@ -90,16 +127,16 @@ export default class ConnectedDeviceHarvester {
       architecture:       architecture       || CD_METADATA.architecture,
     };
 
-    this.eventBuffer = new NrVideoEventAggregator(); 
+    this.eventBuffer = new NrVideoEventAggregator();
 
     // Smart-harvest wiring: buffer triggers an early drain at 60% (smart) and
     // 90% (overflow) capacity, before makeRoom()'s drop-oldest FIFO eviction
-    // would silently lose events. 
+    // would silently lose events.
     this.eventBuffer.setSmartHarvestCallback((type, threshold) =>
       this.triggerSmartHarvest(type, threshold)
     );
 
-    this.dataToken = null; 
+    this.dataToken = null;
     this.isHarvesting = false;
     this.isDisposed = false;
     this._isFetchingToken = false; // guard: prevents parallel /v5/connect sequences
@@ -112,13 +149,13 @@ export default class ConnectedDeviceHarvester {
       errorLabel: "ConnectedDeviceHarvester",
     });
 
-    // QoE state 
+    // QoE state
     this.qoeCycleCount = 1;
     this.forceQoeNextCycle = false;
     this.beforeDrainCallback = null;
     this._lastSentQoeKpis = {};
 
-    // Connect retry state 
+    // Connect retry state
     this._connectAttempt = 0;
 
     // fire-and-forget initialise.
@@ -132,15 +169,15 @@ export default class ConnectedDeviceHarvester {
    *
    * @returns {string}
    */
-  getEndpointBaseUrl() {
+  getEndpointBaseUrl(): string {
     return ENDPOINT_URL[this.endpoint] ?? ENDPOINT_URL.us;
   }
 
   /**
-   * Two-phase init: fetch dataToken, then start harvest interval. 
+   * Two-phase init: fetch dataToken, then start harvest interval.
    * @returns {Promise<void>}
    */
-  async initialise() {
+  async initialise(): Promise<void> {
     await this.fetchDataTokens();
     // Defensive guard: if dispose() ran while fetchDataTokens was awaiting,
     // do not start an interval that will outlive the harvester.
@@ -153,7 +190,7 @@ export default class ConnectedDeviceHarvester {
   /**
    * POST `/v5/connect` to obtain a dataToken. Retries up to
    * CD_CONNECT_MAX_ATTEMPTS times with a fixed CD_CONNECT_RETRY_DELAY_MS
-   * wait between attempts. 
+   * wait between attempts.
    *
    * Iterative loop keeps the call stack flat across all attempts.
    * `_isFetchingToken` guard ensures only one connect sequence runs at a
@@ -163,7 +200,7 @@ export default class ConnectedDeviceHarvester {
    *
    * @returns {Promise<void>}
    */
-  async fetchDataTokens() {
+  async fetchDataTokens(): Promise<void> {
     if (this._isFetchingToken) return;
     this._isFetchingToken = true;
 
@@ -205,7 +242,7 @@ export default class ConnectedDeviceHarvester {
           this._connectAttempt = attempt + 1;
           Log.notice("ConnectedDeviceHarvester: dataToken acquired");
           return;
-        } catch (err) {
+        } catch (err: any) {
           this._connectAttempt = attempt + 1;
           Log.error(
             `ConnectedDeviceHarvester: /v5/connect failed (attempt ${this._connectAttempt}/${CD_CONNECT_MAX_ATTEMPTS}):`,
@@ -231,7 +268,7 @@ export default class ConnectedDeviceHarvester {
    * Starts the periodic harvest timer.
    * Idempotent — safe to call repeatedly.
    */
-  startHarvestInterval() {
+  startHarvestInterval(): void {
     if (this.isDisposed) return;
     this.timer.start();
   }
@@ -247,14 +284,14 @@ export default class ConnectedDeviceHarvester {
    * @param {number} threshold - The threshold percentage that triggered the harvest (60 or 90).
    * @returns {Promise<void>}
    */
-  async triggerSmartHarvest(type, threshold) {
+  async triggerSmartHarvest(type: string, threshold: number): Promise<void> {
     Log.notice(
       `ConnectedDeviceHarvester: smart-harvest trigger (${type} at ${threshold}%)`
     );
     if (!this.eventBuffer || this.eventBuffer.isEmpty()) return;
     try {
       await this.sendBufferedEvents();
-    } catch (error) {
+    } catch (error: any) {
       Log.error(`${type} smart-harvest failed:`, error.message);
     } finally {
       // Reset the periodic clock — next periodic tick happens `harvestInterval`
@@ -269,13 +306,13 @@ export default class ConnectedDeviceHarvester {
    * @param {object} eventObject
    * @returns {boolean}
    */
-  addEvent(eventObject) {
+  addEvent(eventObject: EventAttributes): boolean {
     try {
       // Shared QOE_AGGREGATE dedup + non-QoE append. Timestamp
       // is preserved from `recordEvent.js` (emit-time), matching the Browser
       // pipeline. Cross-pipeline analytics produce consistent timestamps.
       return bufferEventWithQoeDedup(this.eventBuffer, eventObject);
-    } catch (err) {
+    } catch (err: any) {
       Log.error("ConnectedDeviceHarvester.addEvent failed:", err.message);
       return false;
     }
@@ -285,7 +322,7 @@ export default class ConnectedDeviceHarvester {
    * Forces the next harvest cycle to ship QOE_AGGREGATE regardless of cycle
    * multiplier or dirty check. Used at CONTENT_END for final QoE flush.
    */
-  forceQoeNextHarvest() {
+  forceQoeNextHarvest(): void {
     this.forceQoeNextCycle = true;
   }
 
@@ -295,7 +332,7 @@ export default class ConnectedDeviceHarvester {
    * before they ship.
    * @param {Function|null} cb
    */
-  setBeforeDrainCallback(cb) {
+  setBeforeDrainCallback(cb: (() => void) | null): void {
     if (typeof cb === "function" || cb === null) {
       this.beforeDrainCallback = cb;
     }
@@ -309,7 +346,7 @@ export default class ConnectedDeviceHarvester {
    * @param {object} freshKpis - Object with latest KPI values
    * @param {string} [viewId] - The viewId of the player whose QoE event to update
    */
-  refreshQoeKpis(freshKpis, viewId) {
+  refreshQoeKpis(freshKpis: EventAttributes, viewId?: string): void {
     refreshQoeKpisInBuffer(this.eventBuffer, freshKpis, viewId);
   }
 
@@ -320,7 +357,7 @@ export default class ConnectedDeviceHarvester {
    *
    * @param {number} interval - New cadence in ms.
    */
-  setHarvestInterval(interval) {
+  setHarvestInterval(interval: number): void {
     if (typeof interval !== "number" || interval <= 0) return;
     this.harvestInterval = interval;
     this.timer.updateInterval(interval);
@@ -336,7 +373,7 @@ export default class ConnectedDeviceHarvester {
    *
    * @returns {Promise<void>}
    */
-  async sendBufferedEvents() {
+  async sendBufferedEvents(): Promise<void> {
     if (this.isHarvesting) return;
     if (!this.dataToken) return;
     if (this.eventBuffer.isEmpty()) return;
@@ -345,7 +382,7 @@ export default class ConnectedDeviceHarvester {
     if (typeof this.beforeDrainCallback === "function") {
       try {
         this.beforeDrainCallback();
-      } catch (e) {
+      } catch (e: any) {
         Log.error("ConnectedDeviceHarvester beforeDrainCallback failed:", e.message);
       }
     }
@@ -426,7 +463,7 @@ export default class ConnectedDeviceHarvester {
 
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       Log.notice(`ConnectedDeviceHarvester: sent ${filtered.length} events`);
-    } catch (err) {
+    } catch (err: any) {
       Log.error("ConnectedDeviceHarvester: /v3/data send failed:", err.message);
       // Re-queue drained events into buffer; next tick retries.
       for (const e of filtered) this.eventBuffer.add(e);
@@ -443,7 +480,7 @@ export default class ConnectedDeviceHarvester {
    * @returns {Array}
    * @private
    */
-  _buildDeviceInfo() {
+  _buildDeviceInfo(): any[] {
     const d = this.deviceInfo;
     return [
       CD_DEVICE_INFO[0],          // osName        — fixed ("Vega")
@@ -469,7 +506,7 @@ export default class ConnectedDeviceHarvester {
    * @returns {object}
    * @private
    */
-  _buildMetadata() {
+  _buildMetadata(): Record<string, any> {
     const d = this.deviceInfo;
     return {
       ...CD_METADATA,
@@ -495,7 +532,7 @@ export default class ConnectedDeviceHarvester {
    * @returns {Promise<Response>}
    * @private
    */
-  _fetchWithTimeout(url, options, timeoutMs) {
+  _fetchWithTimeout(url: string, options: RequestInit, timeoutMs: number): Promise<Response> {
     const controller = new AbortController();
     const timerId = setTimeout(() => controller.abort(), timeoutMs);
     return fetch(url, { ...options, signal: controller.signal })
@@ -506,7 +543,7 @@ export default class ConnectedDeviceHarvester {
    * Stops the harvest interval and attempts one final best-effort send.
    * @returns {Promise<void>}
    */
-  async dispose() {
+  async dispose(): Promise<void> {
     this.isDisposed = true;
     this.timer.stop();
     return this.sendBufferedEvents();

package/src/constants.ts

@@ -0,0 +1,62 @@
+/**
+ * Constants for the library.
+ * @class Constants
+ * @static
+ */
+class Constants {
+  /**
+   * Enum for types/positions of ads.
+   * @example var type = Constants.AdPositions.PRE
+   * @enum {String}
+   */
+  static AdPositions = {
+    /** For ads shown before the content. */
+    PRE: "pre",
+    /** For ads shown during the content. */
+    MID: "mid",
+    /** For ads shown after the content. */
+    POST: "post",
+  };
+
+  // bam.nr-data.net
+  //bam-cell.nr-data.net
+  static COLLECTOR: Record<string, string | string[]> = {
+    US: ["bam.nr-data.net", "bam-cell.nr-data.net"],
+    EU: "bam.eu01.nr-data.net",
+    JP: "bam.jp.nr-data.net",
+    Staging: "staging-bam-cell.nr-data.net",
+    GOV: "gov-bam.nr-data.net",
+  };
+
+  // ====== VALID EVENT TYPES ======
+  static VALID_EVENT_TYPES = [
+    "VideoAction",
+    "VideoAdAction",
+    "VideoErrorAction",
+    "VideoCustomAction",
+  ];
+
+  static MAX_PAYLOAD_SIZE = 1048576; // 1MB = 1024 × 1024 bytes
+  static MAX_BEACON_SIZE = 61440; // 60KB = 60 × 1024 bytes
+  static MAX_EVENTS_PER_BATCH = 1000;
+  static INTERVAL = 10000; //10 seconds
+  static DEFAULT_QOE_INTERVAL_FACTOR = 2;
+
+  static QOE_KPI_KEYS = [
+    "startupTime", "peakBitrate", "averageBitrate", "totalPlaytime",
+    "totalRebufferingTime", "rebufferingRatio", "hadStartupError",
+    "hadPlaybackError", "numberOfErrors"
+  ];
+
+  static QOE_AGGREGATE_KEYS = [
+    "coreVersion", "instrumentation.name",
+    "instrumentation.provider", "instrumentation.version", "isBackgroundEvent", "playerName", "playerVersion",
+    "src", "viewId", "viewSession", "contentIsAutoplayed", "contentIsMuted", "contentRenditionHeight", "contentRenditionWidth",
+    "contentSrc", "numberOfVideos", "pageUrl", "trackerName", "trackerVersion", "contentDuration", "contentPlayrate", "contentPlayhead",
+    "contentPreload", "elapsedTime", "contentTitle", "contentId", "contentIsLive", "deviceType", "deviceGroup", "deviceManufacturer",
+    "deviceModel", "deviceName", "deviceSize", "deviceUuid", "contentRenditionName", "contentIsFullscreen", "contentCdn",
+    "contentFps", "asnOrganization", "asnLongitude", "asnLatitude", "asn", "timeSinceRequested", "timeSinceStarted"
+  ];
+}
+
+export default Constants;

package/src/{core.js → core.ts}

@@ -1,6 +1,19 @@
 import Log from "./log";
 import { recordEvent } from "./recordEvent";
-import { setVideoConfig } from "./videoConfiguration";
+import { setVideoConfig, RawVideoConfigInfo, RawVideoConfigOptions } from "./videoConfiguration";
+import Emitter from "./emitter";
+
+/** Structural contract Core needs from anything passed to addTracker/removeTracker. */
+export interface TrackerLike extends Emitter {
+  dispose(): void;
+  trackerInit?(): void;
+}
+
+export interface CoreAddTrackerOptions {
+  info?: RawVideoConfigInfo;
+  config?: RawVideoConfigOptions;
+  src?: string;
+}
 
 /**
  * Static class that sums up core functionalities of the library.
@@ -13,14 +26,14 @@ class Core {
    * @param {(Emitter|Tracker)} tracker Tracker instance to add.
    * @param {object} options Configuration options including video analytics settings.
    */
-  static addTracker(tracker, options) {
+  static addTracker(tracker: TrackerLike, options?: CoreAddTrackerOptions): void {
     // Set video analytics configuration. The optional `options.src` field
     // selects the pipeline: `'Vega'` writes globalThis.__NRVIDEO_CD__,
-    // anything else writes window.NRVIDEO. 
+    // anything else writes window.NRVIDEO.
     if (options?.info) {
       setVideoConfig(options.info, options?.config, options?.src);
     }
-    
+
     if (tracker.on && tracker.emit) {
       trackers.push(tracker);
       tracker.on("*", eventHandler);
@@ -37,7 +50,7 @@ class Core {
    *
    * @param {Tracker} tracker Tracker to remove.
    */
-  static removeTracker(tracker) {
+  static removeTracker(tracker: TrackerLike): void {
     tracker.off("*", eventHandler);
     tracker.dispose();
     let index = trackers.indexOf(tracker);
@@ -49,7 +62,7 @@ class Core {
    *
    * @returns {Tracker[]} Array of trackers.
    */
-  static getTrackers() {
+  static getTrackers(): TrackerLike[] {
     return trackers;
   }
 
@@ -59,13 +72,13 @@ class Core {
    * @param {string} actionName - Action name
    * @param {object} data - Event data
    */
-  static send(eventType, actionName, data) {
+  static send(eventType: string, actionName: string, data?: Record<string, any>): boolean | undefined {
     const enrichedData = {
       actionName,
       ...data,
-     
+
     };
-    
+
     return recordEvent(eventType, enrichedData);
   }
 
@@ -77,7 +90,7 @@ class Core {
    *
    * @param {object} att attributes to be sent along the error.
    */
-  static sendError(att) {
+  static sendError(att?: Record<string, any>): boolean | undefined {
     return recordEvent("VideoErrorAction", {
       actionName: "ERROR",
       ...att
@@ -86,8 +99,8 @@ class Core {
 
 }
 
-let trackers = [];
-let isErrorShown = false;
+let trackers: TrackerLike[] = [];
+let isErrorShown: boolean = false;
 
 /**
  * Enhanced event handler with error handling and performance monitoring.
@@ -95,11 +108,11 @@ let isErrorShown = false;
  * @private
  * @param {Event} e Event
  */
-function eventHandler(e) {
+function eventHandler(e: any) {
   try {
     let data = cleanData(e.data);
-    
-    if (Log.level <= Log.Levels.DEBUG) {
+
+    if ((Log.level as any) <= Log.Levels.DEBUG) {
       Log.notice("Sent", e.type, data);
     } else {
       Log.notice("Sent", e.type);
@@ -108,7 +121,7 @@ function eventHandler(e) {
     // Send event without priority discrimination
     Core.send(e.eventType, e.type, data);
 
-  } catch (error) {
+  } catch (error: any) {
     Log.error("Error in event handler:", error.message);
   }
 }
@@ -119,8 +132,8 @@ function eventHandler(e) {
  * @param {Object} data Data to clean
  * @returns {Object} Cleaned object
  */
-function cleanData(data) {
-  let ret = {};
+function cleanData(data: Record<string, any>): Record<string, any> {
+  let ret: Record<string, any> = {};
   for (let i in data) {
     if (data[i] !== null && typeof data[i] !== "undefined") ret[i] = data[i];
   }

package/src/{emitter.js → emitter.ts}

@@ -1,3 +1,12 @@
+export interface TrackerEventPayload {
+  eventType: string;
+  type: string;
+  data: Record<string, unknown>;
+  target: Emitter;
+}
+
+export type ListenerCallback = (payload: TrackerEventPayload) => void;
+
 /**
  * This base class implements a basic behavior of listeners and events. Extend this object to have
  * this feature built-in inside your classes.
@@ -5,6 +14,8 @@
  * @class Emitter
  */
 class Emitter {
+  _listeners?: Record<string, ListenerCallback[]>;
+
   /**
    * Sets a listener to a given event. Use {@link emit} to trigger those events.
    * Pass '*' to listen ALL events.
@@ -13,7 +24,7 @@ class Emitter {
    * @param {function} callback Callback of the event. Receives event and data.
    * @return this
    */
-  on(event, callback) {
+  on(event: string, callback: ListenerCallback): this | undefined {
     this._listeners = this._listeners || {};
     if (typeof callback === "function") {
       this._listeners[event] = this._listeners[event] || [];
@@ -29,7 +40,7 @@ class Emitter {
    * @param {function} callback Callback of the event.
    * @return this
    */
-  off(event, callback) {
+  off(event: string, callback: ListenerCallback): this {
     this._listeners = this._listeners || {};
 
     if (this._listeners[event]) {
@@ -48,7 +59,7 @@ class Emitter {
    * @param {object} [data] Custom data to be sent to the callbacks.
    * @return this
    */
-  emit(eventType, event, data) {
+  emit(eventType: string, event: string, data?: Record<string, unknown>): this {
     this._listeners = this._listeners || {};
     data = data || {};
 
@@ -57,7 +68,7 @@ class Emitter {
         callback.call(this, {
           eventType,
           type: event,
-          data: data,
+          data: data as Record<string, unknown>,
           target: this,
         });
       });
@@ -68,7 +79,7 @@ class Emitter {
         callback.call(this, {
           eventType,
           type: event,
-          data: data,
+          data: data as Record<string, unknown>,
           target: this,
         });
       });