@newrelic/video-core 5.0.1 → 5.1.0

package/package.json

@@ -1,26 +1,31 @@
 {
   "name": "@newrelic/video-core",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "New Relic video tracking core library",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js"
     },
     "./browser": {
+      "types": "./dist/types/browser/index.d.ts",
       "import": "./dist/esm/browser/index.js",
       "require": "./dist/cjs/browser/index.js"
     },
     "./vega": {
+      "types": "./dist/types/connectedDevice/index.d.ts",
       "import": "./dist/esm/vega/index.js",
       "require": "./dist/cjs/vega/index.js"
     },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "webpack --mode production",
+    "build": "webpack --mode production && npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly",
     "build:dev": "webpack --mode development",
     "watch": "webpack --mode production --progress --color --watch",
     "watch:dev": "webpack --progress --color --watch",
@@ -46,6 +51,7 @@
     "@babel/core": "^7.24.5",
     "@babel/plugin-transform-modules-commonjs": "^7.24.1",
     "@babel/preset-env": "^7.24.5",
+    "@babel/preset-typescript": "^7.29.7",
     "@babel/register": "^7.24.6",
     "@newrelic/newrelic-oss-cli": "^0.1.2",
     "@semantic-release/changelog": "^6.0.3",
@@ -56,6 +62,7 @@
     "@semantic-release/release-notes-generator": "^13.0.0",
     "babel-jest": "^30.0.0",
     "babel-loader": "^9.1.3",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
     "diff": "^5.0.0",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
@@ -64,6 +71,7 @@
     "nyc": "^18.0.0",
     "semantic-release": "^25.0.8",
     "sinon": "^2.4.1",
+    "typescript": "^7.0.2",
     "webpack": "^5.91.0",
     "webpack-cli": "^4.9.2"
   },
@@ -83,5 +91,10 @@
   },
   "dependencies": {
     "terser-webpack-plugin": "^5.6.1"
+  },
+  "overrides": {
+    "ip-address": "^10.3.1",
+    "serialize-javascript": "^7.0.5",
+    "undici": "^6.28.0"
   }
 }

package/src/browser/{agent.js → agent.ts}

@@ -1,16 +1,21 @@
-import { HarvestScheduler } from "./harvestScheduler.js";
-import { NrVideoEventAggregator } from "../eventAggregator.js";
-import Log from "../log.js";
-import { registerHarvester } from "../recordEvent.js";
+import { HarvestScheduler } from "./harvestScheduler";
+import { NrVideoEventAggregator } from "../eventAggregator";
+import Log from "../log";
+import { registerHarvester } from "../recordEvent";
 import {
   bufferEventWithQoeDedup,
   refreshQoeKpisInBuffer,
 } from "../utils/qoeFilters";
+import { EventAttributes, Harvester } from "../utils/eventBuilder";
 
 /**
  * Enhanced video analytics agent with HarvestScheduler only.
  */
-class VideoAnalyticsAgent {
+class VideoAnalyticsAgent implements Harvester {
+  isInitialized: boolean;
+  harvestScheduler: HarvestScheduler | null;
+  eventBuffer: NrVideoEventAggregator | null;
+
   constructor() {
     this.isInitialized = false;
     this.harvestScheduler = null;
@@ -20,7 +25,7 @@ class VideoAnalyticsAgent {
   /**
    * Initializes the video analytics agent with enhanced HarvestScheduler.
    */
-  initialize() {
+  initialize(): void {
     if (this.isInitialized) {
       Log.warn("Video analytics agent already initialized");
       return;
@@ -35,7 +40,7 @@ class VideoAnalyticsAgent {
 
       this.isInitialized = true;
       Log.notice("Video analytics agent initialized successfully");
-    } catch (error) {
+    } catch (error: any) {
       Log.error("Failed to initialize video analytics agent:", error.message);
     }
   }
@@ -45,7 +50,7 @@ class VideoAnalyticsAgent {
    * @param {object} eventObject - Event to add
    * @returns {boolean} True if event was added successfully
    */
-  addEvent(eventObject) {
+  addEvent(eventObject: EventAttributes): boolean {
     if (!this.isInitialized) {
       Log.warn("Video analytics agent not initialized, initializing now");
       this.initialize();
@@ -53,8 +58,8 @@ class VideoAnalyticsAgent {
 
     try {
       // QOE_AGGREGATE dedup + plain append, shared with the Vega pipeline.
-      return bufferEventWithQoeDedup(this.eventBuffer, eventObject);
-    } catch (error) {
+      return bufferEventWithQoeDedup(this.eventBuffer as NrVideoEventAggregator, eventObject);
+    } catch (error: any) {
       Log.error("Failed to add event to harvesting system:", error.message);
       return false;
     }
@@ -65,19 +70,19 @@ class VideoAnalyticsAgent {
    * @param {number} interval - The harvest interval in milliseconds.
    */
 
-  setHarvestInterval(interval) {
+  setHarvestInterval(interval: number): void {
     if (!this.isInitialized) {
       this.initialize();
     }
 
-    this.harvestScheduler.updateHarvestInterval(interval);
+    (this.harvestScheduler as HarvestScheduler).updateHarvestInterval(interval);
   }
 
   /**
    * Forces the next harvest cycle to include QOE_AGGREGATE events.
    * Called at CONTENT_END to ensure final QoE is sent.
    */
-  forceNextQoeCycle() {
+  forceNextQoeCycle(): void {
     if (this.harvestScheduler) {
       this.harvestScheduler.forceNextQoeCycle = true;
     }
@@ -87,7 +92,7 @@ class VideoAnalyticsAgent {
    * Sets a callback to be called before each drain to refresh QoE KPIs.
    * @param {Function|null} callback - Function that refreshes QoE data in the buffer, or null to clear
    */
-  setBeforeDrainCallback(callback) {
+  setBeforeDrainCallback(callback: (() => void) | null): void {
     if (this.harvestScheduler) {
       this.harvestScheduler.beforeDrainCallback = callback;
     }
@@ -99,8 +104,8 @@ class VideoAnalyticsAgent {
    * @param {object} freshKpis - Object with latest KPI values
    * @param {string} [viewId] - The viewId of the player whose QoE event to update
    */
-  refreshQoeKpis(freshKpis, viewId) {
-    refreshQoeKpisInBuffer(this.eventBuffer, freshKpis, viewId);
+  refreshQoeKpis(freshKpis: EventAttributes, viewId?: string): void {
+    refreshQoeKpisInBuffer(this.eventBuffer as NrVideoEventAggregator, freshKpis, viewId);
   }
 }
 

package/src/browser/{harvestScheduler.js → harvestScheduler.ts}

@@ -6,10 +6,24 @@ import {
   partitionByQoeCycle,
   applyQoeDirtyFilter,
 } from "../utils/qoeFilters";
-import { createHarvestTimer } from "../utils/harvestTimer";
+import { createHarvestTimer, HarvestTimer } from "../utils/harvestTimer";
 import Constants from "../constants";
 import Tracker from "../tracker";
 import Log from "../log";
+import { EventAttributes } from "../utils/eventBuilder";
+
+interface HarvestOptions {
+  isFinalHarvest?: boolean;
+  force?: boolean;
+}
+
+interface HarvestResult {
+  success: boolean;
+  reason?: string;
+  totalChunks?: number;
+  results?: any[];
+  error?: string;
+}
 
 /**
  * Enhanced harvest scheduler that orchestrates the video analytics data collection,
@@ -17,7 +31,20 @@ import Log from "../log";
  */
 
 export class HarvestScheduler {
-  constructor(eventAggregator) {
+  eventBuffer: NrVideoEventAggregator;
+  retryQueueHandler: RetryQueueHandler;
+  httpClient: OptimizedHttpClient;
+  fallBackUrl: string;
+  retryCount: number;
+  harvestCycle: number;
+  isHarvesting: boolean;
+  qoeCycleCount: number;
+  forceNextQoeCycle: boolean;
+  beforeDrainCallback: (() => void) | null;
+  _lastSentQoeKpis: Record<string, any>;
+  timer: HarvestTimer;
+
+  constructor(eventAggregator: NrVideoEventAggregator) {
     // Core components
     this.eventBuffer = eventAggregator;
     this.retryQueueHandler = new RetryQueueHandler();
@@ -55,14 +82,14 @@ export class HarvestScheduler {
    * Whether the scheduler is currently running. Backed by the shared timer.
    * @returns {boolean}
    */
-  get isStarted() {
+  get isStarted(): boolean {
     return this.timer.isRunning();
   }
 
   /**
    * Starts the harvest scheduler.
    */
-  startScheduler() {
+  startScheduler(): void {
     if (this.timer.isRunning()) {
       Log.warn("Harvest scheduler is already started");
       return;
@@ -79,7 +106,7 @@ export class HarvestScheduler {
   /**
    * Stops the harvest scheduler.
    */
-  stopScheduler() {
+  stopScheduler(): void {
     if (!this.timer.isRunning()) return;
     this.timer.stop();
     Log.notice("Harvest scheduler stopped");
@@ -90,7 +117,7 @@ export class HarvestScheduler {
    * @param {string} type - Type of harvest trigger ('smart' or 'overflow')
    * @param {number} threshold - Threshold percentage that triggered the harvest (60 or 90)
    */
-  async triggerSmartHarvest(type, threshold) {
+  async triggerSmartHarvest(type: string, threshold: number): Promise<void> {
     Log.notice(`${type} harvest triggered at ${threshold}% threshold`, {
       type,
       threshold,
@@ -101,7 +128,7 @@ export class HarvestScheduler {
 
     try {
       await this.triggerHarvest({});
-    } catch (error) {
+    } catch (error: any) {
       Log.error(`${type} harvest failed:`, error.message);
     } finally {
       // Reset the periodic clock — next periodic tick happens `harvestCycle`
@@ -114,7 +141,7 @@ export class HarvestScheduler {
    * Periodic-tick callback. Invoked by the shared harvest timer on each cycle.
    * @private
    */
-  async onHarvestInterval() {
+  async onHarvestInterval(): Promise<void> {
     // Check if there's any data to harvest (buffer or retry queue) before
     // starting the harvest process — avoids unnecessary network calls when
     // there's nothing to ship.
@@ -132,7 +159,7 @@ export class HarvestScheduler {
    * @param {boolean} options.force - Force harvest even if buffer is empty
    * @returns {Promise<object>} Harvest result
    */
-  async triggerHarvest(options = {}) {
+  async triggerHarvest(options: HarvestOptions = {}): Promise<HarvestResult> {
     if (this.isHarvesting) {
       return { success: false, reason: "harvest_in_progress" };
     }
@@ -146,7 +173,7 @@ export class HarvestScheduler {
       // For beacon harvests, trim events to fit beacon size if necessary
       if (options.isFinalHarvest) {
         const maxBeaconSize = Constants.MAX_BEACON_SIZE;
-        const payloadSize = dataSize(events);
+        const payloadSize = dataSize(events) ?? 0;
 
         if (payloadSize > maxBeaconSize) {
           // Trim events to fit beacon size (keep most recent events)
@@ -162,7 +189,7 @@ export class HarvestScheduler {
         totalChunks: 1,
         results: [result],
       };
-    } catch (error) {
+    } catch (error: any) {
       Log.error("Harvest cycle failed:", error.message);
       this.handleHarvestFailure(error);
 
@@ -183,18 +210,18 @@ export class HarvestScheduler {
    * @returns {Array} Trimmed events that fit within size limit
    * @private
    */
-  trimEventsToFit(events, maxSize) {
+  trimEventsToFit(events: EventAttributes[], maxSize: number): EventAttributes[] {
     if (events.length === 0) return events;
 
     // Start from the most recent events (end of array) and work backwards
-    const trimmedEvents = [];
+    const trimmedEvents: EventAttributes[] = [];
     let currentSize = 0;
 
     for (let i = events.length - 1; i >= 0; i--) {
       const event = events[i];
 
       // Check if adding this event would exceed the limit
-      const testPayloadSize = dataSize({ ins: [event, ...trimmedEvents] });
+      const testPayloadSize = dataSize({ ins: [event, ...trimmedEvents] }) ?? 0;
 
       if (testPayloadSize > maxSize) continue;
 
@@ -231,7 +258,7 @@ export class HarvestScheduler {
    * @returns {Array} Drained events
    * @private
    */
-  drainEvents(options = {}) {
+  drainEvents(options: HarvestOptions = {}): EventAttributes[] {
     // Determine if this cycle should include the QOE_AGGREGATE event
     const multiplier = window.NRVIDEO?.config?.qoeIntervalFactor ?? 1;
     const isForced = !!options.isFinalHarvest || this.forceNextQoeCycle;
@@ -245,7 +272,7 @@ export class HarvestScheduler {
     if (this.beforeDrainCallback && typeof this.beforeDrainCallback === 'function') {
       try {
         this.beforeDrainCallback();
-      } catch (e) {
+      } catch (e: any) {
         Log.error("Before drain callback failed:", e.message);
       }
     }
@@ -265,7 +292,7 @@ export class HarvestScheduler {
     applyQoeDirtyFilter(filteredFreshEvents, this._lastSentQoeKpis, isForced);
 
     let events = [...filteredFreshEvents];
-    let currentPayloadSize = dataSize(filteredFreshEvents);
+    let currentPayloadSize = dataSize(filteredFreshEvents) ?? 0;
 
     // Always check retry queue if it has data - no flags needed
     if (this.retryQueueHandler && this.retryQueueHandler.getQueueSize() > 0) {
@@ -298,8 +325,8 @@ export class HarvestScheduler {
    * @returns {Promise<object>} Send result
    * @private
    */
-  async sendChunk(chunk, options, isLastChunk) {
-    const url = buildUrl(this.fallBackUrl); //
+  async sendChunk(chunk: EventAttributes[], options: HarvestOptions, isLastChunk: boolean): Promise<{ success: boolean; status: number; error?: string; chunk: EventAttributes[]; eventCount: number }> {
+    const url = buildUrl(this.fallBackUrl) as string; //
     const payload = { body: { ins: chunk } };
     const requestOptions = {
       url,
@@ -334,7 +361,7 @@ export class HarvestScheduler {
    * @param {Array} chunk - Failed chunk to add to retry queue
    * @private
    */
-  handleRequestFailure(chunk) {
+  handleRequestFailure(chunk: EventAttributes[]): void {
     // Add failed events to retry queue
     this.retryQueueHandler.addFailedEvents(chunk);
     // Only apply failover logic for US region
@@ -346,7 +373,7 @@ export class HarvestScheduler {
       this.fallBackUrl = "";
     } else if (this.retryCount >= 2) {
       // Switch to fallback after 2 consecutive failures
-      this.fallBackUrl = Constants.COLLECTOR["US"][1];
+      this.fallBackUrl = (Constants.COLLECTOR["US"] as string[])[1];
     }
   }
 
@@ -355,7 +382,7 @@ export class HarvestScheduler {
    * @param {Error} error - Harvest error
    * @private
    */
-  handleHarvestFailure(error) {
+  handleHarvestFailure(error: Error): void {
     Log.warn("Harvest failure handled", { error: error.message });
   }
 
@@ -365,7 +392,7 @@ export class HarvestScheduler {
    * @returns {boolean} - True if interval was updated successfully, false otherwise
    */
 
-  updateHarvestInterval(newInterval) {
+  updateHarvestInterval(newInterval: number): void {
     if (typeof newInterval !== "number" || isNaN(newInterval)) {
       Log.warn("Invalid newInterval provided to updateHarvestInterval");
       return;
@@ -388,7 +415,7 @@ export class HarvestScheduler {
    * Sets up page lifecycle event handlers.
    * @private
    */
-  setupPageLifecycleHandlers() {
+  setupPageLifecycleHandlers(): void {
     let finalHarvestTriggered = false;
 
     const triggerFinalHarvest = () => {

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

@@ -2,6 +2,29 @@
  * This class calculates time lapses between two points on time.
  */
 class Chrono {
+  /** Start time */
+  startTime: number = 0;
+
+  /** Stop time */
+  stopTime: number = 0;
+
+  /** accumulation of all the start and stop intervals */
+  accumulator: number = 0;
+
+  /**
+   * If you set an offset in a chrono, its value will be added getDeltaTime and stop.
+   *
+   * @example
+   * let chrono = new Chrono()
+   * chrono.offset = 500
+   * chrono.start()
+   * process.sleep(500)
+   * chrono.stop() // Will return 1000
+   *
+   * @type {number}
+   */
+  offset: number = 0;
+
   /**
    * Constructor
    */
@@ -10,28 +33,10 @@ class Chrono {
   }
 
   /** Reset chrono values. */
-  reset() {
-    /** Start time */
+  reset(): void {
     this.startTime = 0;
-
-    /** Stop time */
     this.stopTime = 0;
-
-    /** accumulation of all the start and stop intervals */
     this.accumulator = 0;
-
-    /**
-     * If you set an offset in a chrono, its value will be added getDeltaTime and stop.
-     *
-     * @example
-     * let chrono = new Chrono()
-     * chrono.offset = 500
-     * chrono.start()
-     * process.sleep(500)
-     * chrono.stop() // Will return 1000
-     *
-     * @type {number}
-     */
     this.offset = 0;
   }
 
@@ -40,7 +45,7 @@ class Chrono {
    * called.
    * @return {(number|null)} Time lapse in ms.
    */
-  getDeltaTime() {
+  getDeltaTime(): number | null {
     if (this.startTime) {
       return this.offset + (new Date().getTime() - this.startTime);
     } else {
@@ -51,7 +56,7 @@ class Chrono {
   /**
    * Starts the chrono.
    */
-  start() {
+  start(): void {
     this.startTime = new Date().getTime();
     this.stopTime = 0;
   }
@@ -60,7 +65,7 @@ class Chrono {
    * Stops the timer and returns delta time.
    * @return {(number|null)} Returns the delta time
    */
-  stop() {
+  stop(): number | null {
     this.stopTime = new Date().getTime();
     if(this.startTime < this.stopTime) {
       this.accumulator += (this.stopTime - this.startTime);
@@ -68,7 +73,7 @@ class Chrono {
     return this.getDeltaTime();
   }
 
-  getDuration() {
+  getDuration(): number {
     if(this.stopTime) {
       return this.accumulator + this.offset;
     } else {
@@ -80,7 +85,7 @@ class Chrono {
    * Creates a copy of the chrono.
    * @returns {Chrono} Cloned chrono
    */
-  clone() {
+  clone(): Chrono {
     var chrono = new Chrono();
     chrono.startTime = this.startTime;
     chrono.stopTime = this.stopTime;

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

@@ -1,11 +1,15 @@
 import ConnectedDeviceHarvester from "./connectedDeviceHarvester";
 import Log from "../log";
 import { registerHarvester } from "../recordEvent";
+import { EventAttributes, Harvester } from "../utils/eventBuilder";
 
 /**
  * Vega-side analytics agent. Mirror of `VideoAnalyticsAgent` in `agent.js`.
  */
-class ConnectedDeviceAnalyticsAgent {
+class ConnectedDeviceAnalyticsAgent implements Harvester {
+  isInitialized: boolean;
+  harvester: ConnectedDeviceHarvester | null;
+
   constructor() {
     this.isInitialized = false;
     this.harvester = null;
@@ -16,7 +20,7 @@ class ConnectedDeviceAnalyticsAgent {
    * constructs the wrapped `ConnectedDeviceHarvester`. If `info` is not yet populated,
    * returns without flipping `isInitialized` so the next `addEvent` retries.
    */
-  initialize() {
+  initialize(): void {
     if (this.isInitialized) return;
 
     const info = globalThis.__NRVIDEO_CD__?.info;
@@ -31,7 +35,7 @@ class ConnectedDeviceAnalyticsAgent {
       this.harvester = new ConnectedDeviceHarvester(info);
       this.isInitialized = true;
       Log.notice("ConnectedDeviceAnalyticsAgent initialized");
-    } catch (err) {
+    } catch (err: any) {
       Log.error("ConnectedDeviceAnalyticsAgent.initialize failed:", err.message);
     }
   }
@@ -46,17 +50,17 @@ class ConnectedDeviceAnalyticsAgent {
    * @param {object} eventObject
    * @returns {boolean}
    */
-  addEvent(eventObject) {
+  addEvent(eventObject: EventAttributes): boolean {
     if (!this.isInitialized) this.initialize();
     if (!this.isInitialized) return false;
-    return this.harvester.addEvent(eventObject);
+    return (this.harvester as ConnectedDeviceHarvester).addEvent(eventObject);
   }
 
   /**
    * Forwards to the underlying ConnectedDeviceHarvester. No-op if not yet initialized.
    * @see ConnectedDeviceHarvester#forceQoeNextHarvest
    */
-  forceQoeNextHarvest() {
+  forceQoeNextHarvest(): void {
     if (this.harvester) this.harvester.forceQoeNextHarvest();
   }
 
@@ -65,7 +69,7 @@ class ConnectedDeviceAnalyticsAgent {
    * single method name on whichever harvester `getHarvester()` returns —
    * Browser exposes `forceNextQoeCycle`, Vega exposes both names.
    */
-  forceNextQoeCycle() {
+  forceNextQoeCycle(): void {
     this.forceQoeNextHarvest();
   }
 
@@ -74,7 +78,7 @@ class ConnectedDeviceAnalyticsAgent {
    * @see ConnectedDeviceHarvester#setBeforeDrainCallback
    * @param {Function|null} cb
    */
-  setBeforeDrainCallback(cb) {
+  setBeforeDrainCallback(cb: (() => void) | null): void {
     if (this.harvester) this.harvester.setBeforeDrainCallback(cb);
   }
 
@@ -86,7 +90,7 @@ class ConnectedDeviceAnalyticsAgent {
    * @param {object} freshKpis
    * @param {string} [viewId]
    */
-  refreshQoeKpis(freshKpis, viewId) {
+  refreshQoeKpis(freshKpis: EventAttributes, viewId?: string): void {
     if (!this.isInitialized) this.initialize();
     if (this.harvester) this.harvester.refreshQoeKpis(freshKpis, viewId);
   }
@@ -98,7 +102,7 @@ class ConnectedDeviceAnalyticsAgent {
    *
    * @param {number} interval
    */
-  setHarvestInterval(interval) {
+  setHarvestInterval(interval: number): void {
     if (!this.isInitialized) this.initialize();
     if (this.harvester) this.harvester.setHarvestInterval(interval);
   }

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

@@ -6,11 +6,13 @@
 // Only `connectedDeviceHarvester.js` imports these — browser builds
 // never reference this file, keeping the browser bundle lean.
 
+export type VegaEndpoint = "us" | "eu" | "staging" | "gov" | "jp";
+
 /**
  * Maps region key (lowercase) directly to the regional mobile collector base URL.
  * Accepts global.region.key values: us, eu, gov, jp, staging.
  */
-export const ENDPOINT_URL = {
+export const ENDPOINT_URL: Record<VegaEndpoint, string> = {
   us:      "https://mobile-collector.newrelic.com/mobile",
   eu:      "https://mobile-collector.eu01.nr-data.net/mobile",
   staging: "https://staging-mobile-collector.newrelic.com/mobile",
@@ -55,7 +57,7 @@ export const CD_DATA_TIMEOUT_MS = 30000;
  * `agentName='AndroidAgent'` for collector auth; the real device identity
  * is recorded in slot [1] / slot [8] of `/v3/data`.
  */
-export const CD_DATA_TOKENS_PAYLOAD = [
+export const CD_DATA_TOKENS_PAYLOAD: any[] = [
   // appInfo
   [
     "newrelic_mobile_example", // appName
@@ -86,7 +88,7 @@ export const CD_DATA_TOKENS_PAYLOAD = [
  * (Vega + Amazon by default). Customer-supplied `info.deviceInfo` overrides
  * the runtime fields; static slots (osName, agentName, etc.) stay fixed.
  */
-export const CD_DEVICE_INFO = [
+export const CD_DEVICE_INFO: any[] = [
   "Vega",                                    // osName
   "1.0",                                     // osVersion
   "VegaDevice",                              // deviceModel