@newrelic/video-core 4.1.8-beta → 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,13 @@ 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",
+    "totalRebufferingTime", "rebufferingRatio", "hadStartupError",
+    "hadPlaybackError", "numberOfErrors"
+];
 
 Constants.QOE_AGGREGATE_KEYS = [
     "coreVersion", "instrumentation.name",

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/eventAggregator.js

@@ -55,6 +55,54 @@ export class NrVideoEventAggregator {
       }
     }
 
+  /**
+   * If an event with the specified actionName and viewId already exists in the buffer, it will be replaced.
+   * Otherwise, the event will be added as a new entry.
+   * @param {string} actionName - The actionName to search for in the buffer
+   * @param {string} viewId - The viewId to scope the lookup to
+   * @param {object} eventObject - The event object to add or use as replacement.
+   * @returns {boolean} True if the operation succeeded, false if an error occurred
+   */
+  addOrReplaceByActionNameAndViewId(actionName, viewId, eventObject) {
+      const i = this.buffer.findIndex(
+          e => e.actionName === actionName && e.viewId === viewId
+      );
+      try {
+          if (i === -1) {
+              this.add(eventObject);
+          } else {
+              this.add(eventObject, i);
+          }
+          return true;
+      } catch (error) {
+          Log.error("Failed to set or replace the event to buffer:", error.message);
+          return false;
+      }
+  }
+
+  /**
+   * Returns the existing event in buffer matching the given actionName and viewId, or null.
+   * @param {string} actionName
+   * @param {string} viewId
+   * @returns {object|null}
+   */
+  findByActionNameAndViewId(actionName, viewId) {
+      const event = this.buffer.find(
+          e => e.actionName === actionName && e.viewId === viewId
+      );
+      return event || null;
+  }
+
+  /**
+   * Returns the existing event in buffer matching the given actionName, or null.
+   * @param {string} actionName
+   * @returns {object|null}
+   */
+  findByActionName(actionName) {
+      const event = this.buffer.find(e => e.actionName === actionName);
+      return event || null;
+  }
+
   /**
    * Adds an event to the unified buffer.
    * All events are treated equally in FIFO order.

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/obfuscate.js

@@ -0,0 +1,33 @@
+import Log from "./log";
+
+/**
+ * Applies obfuscation rules to a JSON string before sending to the collector.
+ * Each rule replaces matches of `regex` with `replacement` in the string.
+ *
+ * @param {string} jsonString - Serialized JSON payload
+ * @param {Array<{regex: string|RegExp, replacement: string}>} rules - Obfuscation rules
+ * @returns {string} Obfuscated string
+ */
+export function applyObfuscationRules(jsonString, rules) {
+  if (!rules || rules.length === 0) return jsonString;
+
+  return rules.reduce((str, rule) => {
+    let pattern;
+    try {
+      if (rule.regex instanceof RegExp) {
+        // Ensure global flag so all occurrences are replaced
+        const flags = rule.regex.flags.includes("g")
+          ? rule.regex.flags
+          : rule.regex.flags + "g";
+        pattern = new RegExp(rule.regex.source, flags);
+      } else {
+        pattern = new RegExp(rule.regex, "g");
+      }
+    } catch (e) {
+      Log.warn("applyObfuscationRules: invalid regex, skipping rule:", rule.regex, e.message);
+      return str;
+    }
+    let s = str.replace(pattern, rule.replacement);
+    return s;
+  }, jsonString);
+}

package/src/optimizedHttpClient.js

@@ -1,5 +1,6 @@
-import { dataSize, shouldRetry } from "./utils";
+import { shouldRetry } from "./utils";
 import Log from "./log";
+import { applyObfuscationRules } from "./obfuscate";
 
 /**
  * Optimized HTTP client for video analytics data transmission with
@@ -50,7 +51,10 @@ export class OptimizedHttpClient {
     const startTime = Date.now();
 
     try {
-      const requestBody = JSON.stringify(payload.body);
+      const requestBody = applyObfuscationRules(
+        JSON.stringify(payload.body),
+        window.NRVIDEO?.config?.obfuscate
+      );
 
       // Handle final harvest with sendBeacon
       if (options.isFinalHarvest && navigator.sendBeacon) {

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.