@newrelic/video-core 4.1.8 → 5.0.0

package/src/constants.js

@@ -25,6 +25,7 @@ Constants.AdPositions = {
 Constants.COLLECTOR = {
   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",
 };
@@ -41,6 +42,7 @@ Constants.MAX_PAYLOAD_SIZE = 1048576; // 1MB = 1024 × 1024 bytes
 Constants.MAX_BEACON_SIZE = 61440; // 60KB = 60 × 1024 bytes
 Constants.MAX_EVENTS_PER_BATCH = 1000;
 Constants.INTERVAL = 10000; //10 seconds
+Constants.DEFAULT_QOE_INTERVAL_FACTOR = 2;
 
 Constants.QOE_KPI_KEYS = [
     "startupTime", "peakBitrate", "averageBitrate", "totalPlaytime",

package/src/core.js

@@ -14,9 +14,11 @@ class Core {
    * @param {object} options Configuration options including video analytics settings.
    */
   static addTracker(tracker, options) {
-    // Set video analytics configuration
+    // Set video analytics configuration. The optional `options.src` field
+    // selects the pipeline: `'Vega'` writes globalThis.__NRVIDEO_CD__,
+    // anything else writes window.NRVIDEO. 
     if (options?.info) {
-      setVideoConfig(options.info, options?.config);
+      setVideoConfig(options.info, options?.config, options?.src);
     }
     
     if (tracker.on && tracker.emit) {
@@ -82,22 +84,6 @@ class Core {
     });
   }
 
-  
-  
-
-  /**
-   * Forces an immediate harvest of all pending events.
-   * @returns {Promise<object>} Harvest result
-   */
-  static async forceHarvest() {
-    try {
-      const { videoAnalyticsHarvester } = require("./agent"); // lazy loading for dynamic import
-      return await videoAnalyticsHarvester.forceHarvest();
-    } catch (error) {
-      Log.error("Failed to force harvest:", error.message);
-      return { success: false, error: error.message };
-    }
-  }
 }
 
 let trackers = [];

package/src/index.js

@@ -9,12 +9,14 @@ import VideoTrackerState from "./videotrackerstate";
 import { NrVideoEventAggregator } from "./eventAggregator";
 import { RetryQueueHandler } from "./retryQueueHandler";
 import { OptimizedHttpClient } from "./optimizedHttpClient";
-import { HarvestScheduler } from "./harvestScheduler";
-import { recordEvent } from "./recordEvent";
+import { HarvestScheduler } from "./browser/harvestScheduler";
+import { recordEvent, getRegisteredHarvester } from "./recordEvent";
 import { version } from "../package.json";
 
+// Harvesters are exported as NAMED exports only — never added to the `nrvideo`
+// default-namespace object. This is the load-bearing detail for tree-shaking
+
 const nrvideo = {
-  // Core components (existing)
   Constants,
   Chrono,
   Log,
@@ -25,19 +27,16 @@ const nrvideo = {
   Core,
   version,
 
-  // Enhanced video analytics components (new)
- 
   NrVideoEventAggregator,
   RetryQueueHandler,
   OptimizedHttpClient,
   HarvestScheduler,
 
-
-
-  // Enhanced event recording
   recordEvent,
-
-
 };
 
+export { videoAnalyticsHarvester } from "./browser/agent";
+export { connectedDeviceAnalyticsHarvester } from "./connectedDevice/connectedDeviceAgent";
+export { getRegisteredHarvester } from "./recordEvent";
+
 export default nrvideo;

package/src/recordEvent.js

@@ -1,68 +1,75 @@
-import { videoAnalyticsHarvester } from "./agent.js";
 import Constants from "./constants.js";
 import Log from "./log.js";
-import Tracker from "./tracker";
-import {getObjectEntriesForKeys} from "./utils";
+import { dispatchRecordEvent } from "./utils/eventBuilder";
 
 /**
- * Enhanced record event function with validation, enrichment, and unified handling.
- * @param {string} eventType - Type of event to record
- * @param {object} attributes - Event attributes
+ * Registry-based recordEvent (split build).
+ *
+ * No static harvester imports. Each harvester self-registers under a key
+ * (`'Browser'` or `'Vega'`) at module load time via `registerHarvester`.
  */
+const harvesters = Object.create(null);
+
+/**
+ * Register a harvester implementation under a routing key.
+ * Called by `agent.js` (key `'Browser'`) and `connectedDeviceAgent.js`
+ * (key `'Vega'`) at module load time.
+ *
+ * @param {string} key  Routing key matching `attributes.src`.
+ * @param {{ addEvent: function }} harvester
+ */
+export function registerHarvester(key, harvester) {
+  harvesters[key] = harvester;
+}
+
+/**
+ * Look up a harvester registered under a routing key. Returns `undefined` if
+ * no module has registered for that key in this build (e.g. on the `/browser`
+ * subpath, the 'Vega' key is never registered because `connectedDeviceAgent.js`
+ * is unreachable from that entry's import graph).
+ *
+ * Trackers use this getter — instead of importing the harvester binding by
+ * name — so the same `tracker.js` / `vegaTracker.js` source files compile
+ * unchanged across all three core entry points (main, /browser, /vega) when
+ * the html5 webpack build aliases `@newrelic/video-core` to a specific
+ * subpath. Without this, parent-class file `tracker.js` would carry an
+ * unconditional `import { videoAnalyticsHarvester }` that fails to resolve
+ * against the `/vega` subpath.
+ *
+ * @param {string} key
+ * @returns {{ addEvent: function }|undefined}
+ */
+export function getRegisteredHarvester(key) {
+  return harvesters[key];
+}
+
 export function recordEvent(eventType, attributes = {}) {
   try {
-    // Validate event type
     if (!Constants.VALID_EVENT_TYPES.includes(eventType)) {
       Log.warn("Invalid event type provided to recordEvent", { eventType });
       return false;
     }
 
-    // Get app configuration
-
-    if (!window?.NRVIDEO?.info) return;
+    const isVega = attributes.src === "Vega";
+    const routingKey = isVega ? "Vega" : "Browser";
+    const w = typeof window !== "undefined" ? window : undefined;
+    const info = isVega ? globalThis.__NRVIDEO_CD__?.info : w?.NRVIDEO?.info;
+    if (!info) return;
 
-    const { appName, applicationID } = window.NRVIDEO.info;
-
-    const { qoe, ...eventAttributes } = attributes;
-    const qoeAttrs = qoe ? { ...qoe } : {};
-
-    const otherAttrs = {
-        ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
-        timestamp: Date.now(),
-        timeSinceLoad: window.performance
-            ? window.performance.now() / 1000
-            : null,
-    }
-
-    const eventObject = {
-      ...eventAttributes,
-      eventType,
-      ...otherAttrs,
-    };
-
-    const metadataAttributes = getObjectEntriesForKeys(Constants.QOE_AGGREGATE_KEYS, attributes)
-
-    let qoeEventObject = null;
-    if(eventType === "VideoAction") {
-        qoeEventObject = {
-            eventType: "VideoAction",
-            actionName: Tracker.Events.QOE_AGGREGATE,
-            qoeAggregateVersion: '1.0.0',
-            ...qoeAttrs,
-            ...metadataAttributes,
-            ...otherAttrs,
-        }
+    const harvester = harvesters[routingKey];
+    if (!harvester) {
+      Log.warn("No harvester registered for routing key", { routingKey });
+      return false;
     }
 
-    // Send to video analytics harvester
-    const success = videoAnalyticsHarvester.addEvent(eventObject);
-
-    if(qoeEventObject && window?.NRVIDEO?.config?.qoeAggregate) {
-        const successQoe = videoAnalyticsHarvester.addEvent(qoeEventObject);
-        return success && successQoe;
-    }
+    const qoeEnabled = isVega
+      ? globalThis.__NRVIDEO_CD__?.config?.qoeAggregate
+      : w?.NRVIDEO?.config?.qoeAggregate;
 
-    return success;
+    return dispatchRecordEvent(
+      eventType, attributes, info, harvester, qoeEnabled,
+      { addTimeSinceLoad: !isVega }
+    );
   } catch (error) {
     Log.error("Failed to record event:", error.message);
     return false;

package/src/tracker.js

@@ -2,7 +2,6 @@ import pkg from "../package.json";
 import Emitter from "./emitter";
 import Chrono from "./chrono";
 import Constants from "./constants";
-import { videoAnalyticsHarvester } from "./agent";
 import Log from "./log";
 
 /**
@@ -269,18 +268,29 @@ class Tracker extends Emitter {
    */
 
   setHarvestInterval(interval) {
-    if (!videoAnalyticsHarvester) {
-      Log.error("VideoAnalyticsHarvester is not available");
+    const harvester = this.getHarvester?.();
+    if (!harvester) {
+      Log.error("Tracker has no harvester; setHarvestInterval ignored");
       return;
     }
 
     try {
-      videoAnalyticsHarvester.setHarvestInterval(interval);
+      harvester.setHarvestInterval(interval);
     } catch (error) {
       Log.error("Failed to set harvest interval:", error.message);
       return;
     }
   }
+
+  /**
+   * Default harvester accessor. Subclasses (Html5Tracker, VegaTracker, etc.)
+   * override this to point to their specific harvester. Returning `null` here
+   * means a tracker that doesn't override `getHarvester()` will silently no-op
+   * on harvester-bound calls (setHarvestInterval, QoE drain wiring).
+   */
+  getHarvester() {
+    return null;
+  }
 }
 
 /**

package/src/utils/eventBuilder.js

@@ -0,0 +1,126 @@
+import Constants from "../constants";
+import Tracker from "../tracker";
+import { getObjectEntriesForKeys } from "./index";
+
+/**
+ * Pure helper that constructs the wire-format event objects from `recordEvent`
+ * arguments. Used by `src/recordEvent.js`, which is the single shared
+ * implementation re-exported from all three subpath entry points:
+ *
+ *   - `src/recordEvent.js`                (registry dispatcher; runtime hot path
+ *                                          and the only direct caller of this helper)
+ *   - `src/browser/index.js`              (Browser subpath re-export)
+ *   - `src/connectedDevice/index.js`      (Vega subpath re-export)
+ *
+ * Pipeline-specific concerns (which info global to read, which harvester to
+ * call, which qoeAggregate config to check) stay at the call site. This helper
+ * is purely about event-object shape.
+ *
+ * @param {string} eventType - One of `Constants.VALID_EVENT_TYPES`.
+ * @param {object} attributes - Caller-supplied attributes including optional `qoe`.
+ * @param {object} info - The pipeline's resolved `info` object (with `appName` /
+ *   `applicationID` for namespacing).
+ * @param {{ addTimeSinceLoad?: boolean }} [opts] - When `true`, stamp
+ *   `timeSinceLoad` on the event. Browser sets this; Vega does not.
+ *
+ * @returns {{ eventObject: object, qoeEventObject: object|null }}
+ */
+export function buildEventObjects(
+  eventType,
+  attributes,
+  info,
+  { addTimeSinceLoad = false } = {}
+) {
+  const { appName, applicationID } = info;
+  const { qoe, ...eventAttributes } = attributes;
+  const qoeAttrs = qoe ? { ...qoe } : {};
+
+  const otherAttrs = {
+    ...(applicationID ? {} : { appName }),
+    timestamp: Date.now(),
+    ...(addTimeSinceLoad
+      ? {
+          timeSinceLoad:
+            typeof window !== "undefined" && window.performance
+              ? window.performance.now() / 1000
+              : null,
+        }
+      : {}),
+  };
+
+  const eventObject = {
+    ...eventAttributes,
+    eventType,
+    ...otherAttrs,
+  };
+
+  let qoeEventObject = null;
+  if (eventType === "VideoAction") {
+    const metadataAttributes = getObjectEntriesForKeys(
+      Constants.QOE_AGGREGATE_KEYS,
+      attributes
+    );
+    qoeEventObject = {
+      eventType: "VideoAction",
+      actionName: Tracker.Events.QOE_AGGREGATE,
+      qoeAggregateVersion: "1.0.0",
+      ...qoeAttrs,
+      ...metadataAttributes,
+      ...otherAttrs,
+    };
+  }
+
+  return { eventObject, qoeEventObject };
+}
+
+/**
+ * Build + dispatch a video analytics event to the given harvester.
+ *
+ * This is the full dispatch loop shared by all three `recordEvent` entry
+ * points:
+ *   1. Build `eventObject` (and optional `qoeEventObject`) via
+ *      `buildEventObjects`.
+ *   2. Call `harvester.addEvent(eventObject)`.
+ *   3. If qoeEnabled and a QoE companion event was produced, also call
+ *      `harvester.addEvent(qoeEventObject)`.
+ *   4. Return a boolean indicating overall success.
+ *
+ * Pipeline-specific concerns — which global to read for `info`, which
+ * harvester to use, whether qoeAggregate is on — are resolved by the caller.
+ * This function only handles the build + dispatch.
+ *
+ * @param {string} eventType
+ * @param {object} attributes
+ * @param {object} info - Resolved `info` from the pipeline's config global.
+ * @param {{ addEvent: function }} harvester - The registered harvester for
+ *   the current pipeline. Returns false if null/undefined.
+ * @param {boolean} qoeEnabled 
+ * @param {{ addTimeSinceLoad?: boolean }} [opts] - Forwarded to
+ *   `buildEventObjects`.
+ * @returns {boolean}
+ */
+export function dispatchRecordEvent(
+  eventType,
+  attributes,
+  info,
+  harvester,
+  qoeEnabled,
+  { addTimeSinceLoad = false } = {}
+) {
+  if (!harvester) return false;
+
+  const { eventObject, qoeEventObject } = buildEventObjects(
+    eventType,
+    attributes,
+    info,
+    { addTimeSinceLoad }
+  );
+
+  const success = harvester.addEvent(eventObject);
+
+  if (qoeEventObject && qoeEnabled) {
+    return success && harvester.addEvent(qoeEventObject);
+  }
+
+  return success;
+}

package/src/utils/harvestTimer.js

@@ -0,0 +1,109 @@
+import Log from "../log";
+
+/**
+ * Periodic harvest timer using chained `setTimeout`. Each tick schedules the
+ * next one only after the current `onTick` callback resolves — by construction
+ * there can never be overlapping ticks, even if `onTick` is async and slow.
+ *
+ * Used by both pipelines:
+ *   - `browser/harvestScheduler.js` — Browser pipeline drain orchestration
+ *   - `connectedDevice/connectedDeviceHarvester.js` — Vega CAF pipeline
+ *
+ * Single source of truth for harvest timing. Future timer changes (drift
+ * compensation, jitter, exponential back-off, etc.) land here and apply to
+ * both pipelines automatically.
+ *
+ * @param {object} opts
+ * @param {number} opts.interval - Initial tick interval in ms.
+ * @param {() => Promise<void>|void} opts.onTick - Pipeline-specific drain
+ *   callback. Awaited; the next tick is scheduled in `finally` so a slow or
+ *   throwing tick can't overlap with the next one.
+ * @param {string} opts.errorLabel - Prefix for the error log when `onTick`
+ *   throws (e.g. "HarvestScheduler", "ConnectedDeviceHarvester").
+ *
+ * @returns {{
+ *   start: () => void,
+ *   stop: () => void,
+ *   cancelAndReschedule: () => void,
+ *   updateInterval: (ms: number) => void,
+ *   isRunning: () => boolean,
+ * }}
+ */
+export function createHarvestTimer({ interval, onTick, errorLabel }) {
+  let isStarted = false;
+  let currentTimerId = null;
+  let currentInterval = interval;
+
+  function scheduleNext() {
+    if (!isStarted) return;
+    currentTimerId = setTimeout(async () => {
+      currentTimerId = null;
+      try {
+        await onTick();
+      } catch (error) {
+        Log.error(`${errorLabel}: scheduled tick failed:`, error.message);
+      } finally {
+        if (isStarted) scheduleNext();
+      }
+    }, currentInterval);
+  }
+
+  return {
+    /**
+     * Start the timer. Idempotent — repeated calls have no effect while
+     * already running.
+     */
+    start() {
+      if (isStarted) return;
+      isStarted = true;
+      scheduleNext();
+    },
+
+    /**
+     * Stop the timer. The pending tick (if any) is cancelled. The currently-
+     * executing tick (if any) will see `isStarted === false` in its `finally`
+     * and won't schedule a successor.
+     */
+    stop() {
+      isStarted = false;
+      if (currentTimerId) {
+        clearTimeout(currentTimerId);
+        currentTimerId = null;
+      }
+    },
+
+    /**
+     * Cancel any pending tick and reschedule from now. Used by smart-harvest /
+     * forceHarvest paths that drain the buffer immediately and want the
+     * periodic clock reset relative to that drain.
+     */
+    cancelAndReschedule() {
+      if (currentTimerId) {
+        clearTimeout(currentTimerId);
+        currentTimerId = null;
+      }
+      if (isStarted) scheduleNext();
+    },
+
+    /**
+     * Update the tick interval. Takes effect on the next scheduled tick.
+     * If the timer is currently running, the pending tick is cancelled and
+     * a new one is scheduled with the new interval.
+     *
+     * @param {number} ms - New interval in milliseconds. Must be a positive
+     *   number; invalid values are silently ignored.
+     */
+    updateInterval(ms) {
+      if (typeof ms !== "number" || ms <= 0) return;
+      currentInterval = ms;
+      if (isStarted && currentTimerId) {
+        clearTimeout(currentTimerId);
+        currentTimerId = null;
+        scheduleNext();
+      }
+    },
+
+    /** @returns {boolean} True iff `start()` has been called and `stop()` has not. */
+    isRunning: () => isStarted,
+  };
+}

package/src/{utils.js → utils/index.js}

@@ -1,5 +1,5 @@
-import pkg from "../package.json";
-import Log from "./log";
+import pkg from "../../package.json";
+import Log from "../log";
 
 /**
  * Builds the harvest URL with proper query parameters.

package/src/utils/qoeFilters.js

@@ -0,0 +1,149 @@
+/**
+ * QoE-related buffer + cycle helpers shared by both pipelines.
+ *
+ * All six helpers were previously duplicated between
+ *   - `browser/agent.js`           (`addEvent`, `refreshQoeKpis`)
+ *   - `browser/harvestScheduler.js` (cycle filter, dirty splice, _qoeKpisUnchanged, _saveQoeKpis)
+ *   - `connectedDevice/connectedDeviceHarvester.js` (same six)
+ *
+ * They're pure helpers — no class state. Callers pass in the buffer / snapshot
+ * map / event array. Keeping them shared makes the QoE behavior one source of
+ * truth across pipelines, so a fix landed once applies to both Browser and
+ * Vega (and any future CAF device pipeline).
+ *
+ * @module utils/qoeFilters
+ */
+
+import Constants from "../constants";
+import Tracker from "../tracker";
+
+/**
+ * Add an event to the buffer with QOE_AGGREGATE dedup. QOE_AGGREGATE events
+ * are deduplicated by `(actionName, viewId)` so multiple players sharing one
+ * harvester each get exactly one buffered QoE event per view. Non-QoE events
+ * are appended as-is, preserving the emit-time `timestamp` already set by
+ * `recordEvent.js`.
+ *
+ * @param {NrVideoEventAggregator} buffer
+ * @param {object} eventObject
+ * @returns {boolean} True if added/replaced.
+ */
+export function bufferEventWithQoeDedup(buffer, eventObject) {
+  if (!eventObject) return false;
+  if (eventObject.actionName === Tracker.Events.QOE_AGGREGATE) {
+    if (eventObject.viewId) {
+      return buffer.addOrReplaceByActionNameAndViewId(
+        Tracker.Events.QOE_AGGREGATE,
+        eventObject.viewId,
+        eventObject
+      );
+    }
+    return buffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, eventObject);
+  }
+  return buffer.add(eventObject);
+}
+
+/**
+ * Update QoE KPI fields on the buffered QOE_AGGREGATE event for a given viewId.
+ * Looks up the existing buffered event, merges the fresh KPI values for keys
+ * listed in `Constants.QOE_KPI_KEYS`, and replaces it in the buffer. No-op if
+ * no QOE_AGGREGATE event is currently buffered.
+ *
+ * @param {NrVideoEventAggregator} buffer
+ * @param {object} freshKpis
+ * @param {string} [viewId]
+ */
+export function refreshQoeKpisInBuffer(buffer, freshKpis, viewId) {
+  if (!buffer || !freshKpis) return;
+  const existing = viewId
+    ? buffer.findByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId)
+    : buffer.findByActionName(Tracker.Events.QOE_AGGREGATE);
+  if (!existing) return;
+  const updated = { ...existing };
+  for (const key of Constants.QOE_KPI_KEYS) {
+    if (key in freshKpis) updated[key] = freshKpis[key];
+  }
+  if (viewId) {
+    buffer.addOrReplaceByActionNameAndViewId(Tracker.Events.QOE_AGGREGATE, viewId, updated);
+  } else {
+    buffer.addOrReplaceByActionName(Tracker.Events.QOE_AGGREGATE, updated);
+  }
+}
+
+/**
+ * Cross-cycle dirty check — true iff every KPI field on `event` equals the
+ * snapshot saved for that event's viewId.
+ *
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot
+ * @param {object} event
+ * @returns {boolean}
+ */
+export function qoeKpisUnchanged(snapshots, event) {
+  const snapshot = snapshots[event.viewId];
+  if (!snapshot) return false;
+  for (const key of Constants.QOE_KPI_KEYS) {
+    if (event[key] !== snapshot[key]) return false;
+  }
+  return true;
+}
+
+/**
+ * Save a snapshot of an event's QoE KPI fields, keyed by viewId, for the next
+ * cross-cycle dirty check.
+ *
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot (mutated in place)
+ * @param {object} event
+ */
+export function saveQoeKpiSnapshot(snapshots, event) {
+  const snapshot = {};
+  for (const key of Constants.QOE_KPI_KEYS) {
+    snapshot[key] = event[key];
+  }
+  snapshots[event.viewId] = snapshot;
+}
+
+/**
+ * Partition drained events by the QoE-cycle filter. On a QoE cycle, all events
+ * pass through. On a non-QoE cycle, QOE_AGGREGATE events are re-buffered (so
+ * they ship on the next QoE cycle) and only non-QoE events are returned.
+ *
+ * @param {object[]} drained
+ * @param {boolean} isQoeCycle
+ * @param {NrVideoEventAggregator} buffer
+ * @returns {object[]}
+ */
+export function partitionByQoeCycle(drained, isQoeCycle, buffer) {
+  if (isQoeCycle) return drained;
+  const filtered = [];
+  for (const e of drained) {
+    if (e.actionName === Tracker.Events.QOE_AGGREGATE) {
+      buffer.add(e);
+    } else {
+      filtered.push(e);
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Cross-cycle dirty splice. Walks the array in reverse and drops any
+ * QOE_AGGREGATE event whose KPI fields are unchanged since the last send (so
+ * we don't waste bytes shipping identical aggregates). Saves a fresh snapshot
+ * for any QOE_AGGREGATE that does ship. Mutates `filtered` in place.
+ *
+ * @param {object[]} filtered
+ * @param {Object<string, object>} snapshots - viewId → KPI snapshot (read+written)
+ * @param {boolean} isForced - When true, skip the dirty check and ship every
+ *   QOE_AGGREGATE regardless of KPI sameness (final flush, CONTENT_END, etc.)
+ */
+export function applyQoeDirtyFilter(filtered, snapshots, isForced) {
+  for (let i = filtered.length - 1; i >= 0; i--) {
+    const e = filtered[i];
+    if (e.actionName !== Tracker.Events.QOE_AGGREGATE) continue;
+    if (!isForced && qoeKpisUnchanged(snapshots, e)) {
+      filtered.splice(i, 1);
+    } else {
+      saveQoeKpiSnapshot(snapshots, e);
+    }
+  }
+}