@newrelic/video-core 3.1.0 → 3.2.0-beta-0

package/src/eventAggregator.js

@@ -0,0 +1,66 @@
+import { getPayloadSize } from "./utils";
+import Constants from "./constants";
+const { MAX_EVENTS_PER_BATCH, MAX_PAYLOAD_SIZE } = Constants;
+
+/**
+ * A simple aggregator that queues raw events without any statistical aggregation.
+ * It includes the necessary save/reload logic for the harvester's retry mechanism.
+ */
+export class NRVideoEventAggregator {
+  #queue = [];
+  #retryQueue = [];
+
+  /**
+   * Checks if the event queue is empty.
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return this.#queue.length === 0 && this.#retryQueue.length === 0;
+  }
+
+  /**
+   * Drains the entire queue and returns all events.
+   * Called by the harvester to begin the chunking process.
+   */
+  drain() {
+    const allEvents = [...this.#retryQueue, ...this.#queue];
+    this.#queue = []; // Clear the active queue
+    this.#retryQueue = []; // Clear the retry queue
+
+    return allEvents;
+  }
+
+  /**
+   * Adds a complete, enriched event object to the queue.
+   * @param {object} eventObject - The event to queue.
+   */
+  add(eventObject) {
+    this.#queue.push(eventObject);
+  }
+
+  // --- Methods for the Harvester ---
+
+  /**
+   * Cleans up the queue after a harvest attempt, based on the result.
+   * @param {object} result - The result from the harvester, containing a 'retry' flag.
+   */
+  postHarvestCleanup(result) {
+    if (!result.retry || !result.chunk?.length) {
+      this.#retryQueue = [];
+      return;
+    }
+
+    while (
+      this.#retryQueue.length > 0 &&
+      (getPayloadSize(this.#retryQueue) + getPayloadSize(result.chunk) >
+        MAX_PAYLOAD_SIZE ||
+        this.#retryQueue.length + result.chunk.length > MAX_EVENTS_PER_BATCH)
+    ) {
+      // Removes the oldest item from the retry queue to make space
+      this.#retryQueue.shift();
+    }
+
+    // Add the entire failed chunk to the retry queue.
+    this.#retryQueue.push(...result.chunk); // result.chunk will be never greater than 1mb or 1000
+  }
+}

package/src/harvester.js

@@ -0,0 +1,171 @@
+import Constants from "./constants";
+import pkg from "../package.json";
+import { callApi, getPayloadSize } from "./utils";
+
+const { INTERVAL, MAX_EVENTS_PER_BATCH, MAX_PAYLOAD_SIZE, MAX_BEACON_SIZE } =
+  Constants;
+
+/**
+ * A scheduler and dispatcher for sending raw event data to the New Relic 'ins' endpoint.
+ * It manages the harvest cycle, URL construction, and retries.
+ */
+export class NRVideoHarvester {
+  #started = false;
+  #aggregate; // EventAggregator instance
+  #timerId = null; // Timer ID for cleanup
+
+  /**
+   * @param {object} agentController - The agent's configuration object.
+   * @param {object} aggregate - The aggregator instance (e.g., EventAggregator).
+   */
+  constructor(aggregate) {
+    this.#aggregate = aggregate;
+    // Ensure any queued data is sent when the user navigates away.
+    window.addEventListener("pagehide", () =>
+      this.triggerHarvest({ isFinalHarvest: true })
+    );
+  }
+
+  /**
+   * Starts the periodic harvest timer.
+   */
+  startTimer() {
+    if (this.#started) return;
+    this.#started = true;
+    const onHarvestInterval = () => {
+      this.triggerHarvest({});
+      if (this.#started) {
+        this.#timerId = setTimeout(onHarvestInterval, INTERVAL);
+      }
+    };
+    this.#timerId = setTimeout(onHarvestInterval, INTERVAL);
+  }
+
+  /**
+   * Stops the harvest timer and cleans up resources.
+   */
+  stopTimer() {
+    this.#started = false;
+    if (this.#timerId) {
+      clearTimeout(this.#timerId);
+      this.#timerId = null;
+    }
+  }
+
+  /**
+   * Executes a harvest cycle by draining the queue and sending it in chunks.
+   */
+
+  triggerHarvest(options = {}) {
+    if (this.#aggregate.isEmpty()) return;
+
+    try {
+      // 1. Drain the entire queue to get all pending events.
+      const allEvents = this.#aggregate.drain();
+
+      // 2. Determine the correct size limit for this harvest.
+      const maxChunkSize = options.isFinalHarvest
+        ? MAX_BEACON_SIZE
+        : MAX_PAYLOAD_SIZE;
+
+      // 3. Split the events into chunks that respect size and count limits.
+      const chunks = this.chunkEvents(allEvents, maxChunkSize);
+
+      // 4. Send each chunk sequentially.
+      chunks.forEach((chunk, index) => {
+        const isLastChunk = index === chunks.length - 1;
+        this.sendChunk(chunk, options, isLastChunk);
+      });
+    } catch (error) {
+      console.error("Error during harvest:", error);
+      // Re-add events to the queue if something went wrong
+      // This is a failsafe to prevent data loss
+    }
+  }
+
+  /**
+   * Splits an array of events into multiple smaller arrays (chunks).
+   */
+  chunkEvents(events, maxChunkSize) {
+    const chunks = [];
+    let currentChunk = [];
+
+    for (const event of events) {
+      if (currentChunk.length >= MAX_EVENTS_PER_BATCH) {
+        chunks.push(currentChunk);
+        currentChunk = [];
+      }
+
+      currentChunk.push(event);
+      const payloadSize = getPayloadSize({ ins: currentChunk });
+      // Use the maxChunkSize passed into the function
+      if (payloadSize > maxChunkSize) {
+        const lastEvent = currentChunk.pop();
+        if (currentChunk.length > 0) {
+          chunks.push(currentChunk);
+        }
+        currentChunk = [lastEvent];
+      }
+    }
+
+    if (currentChunk.length > 0) {
+      chunks.push(currentChunk);
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Sends a single chunk of events.
+   */
+  sendChunk(chunk, options, isLastChunk) {
+    const url = this.#buildUrl();
+    if (!url) {
+      // If URL construction failed, treat as a failed request that shouldn't be retried
+      this.#aggregate.postHarvestCleanup({ retry: false, status: 0 });
+      return;
+    }
+
+    const payload = { body: { ins: chunk } };
+
+    callApi(
+      {
+        url: url,
+        payload: payload,
+        options: options,
+      },
+      (result) => {
+        // Pass the failed chunk back to the aggregator for re-queuing.
+        if (result.retry) {
+          result.chunk = chunk;
+        }
+        this.#aggregate.postHarvestCleanup(result);
+      }
+    );
+  }
+
+  /**
+   * Constructs the specific URL for the New Relic 'ins' endpoint with all required parameters.
+   * @private
+   */
+
+  #buildUrl() {
+    try {
+      if (!window.NRVIDEO || !window.NRVIDEO.info) {
+        throw new Error("NRVIDEO info is not available.");
+      }
+
+      const { beacon, licenseKey, applicationID, sa } = window.NRVIDEO.info;
+
+      if (!beacon || !licenseKey || !applicationID)
+        throw new Error(
+          "Options object provided by New Relic is not correctly initialized"
+        );
+      const url = `https://${beacon}/ins/1/${licenseKey}?a=${applicationID}&v=${pkg.version}&ref=${window.location.href}&ca=VA`;
+      return url;
+    } catch (error) {
+      console.error(error.message);
+      return null; // Return null instead of undefined
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,22 @@
+import Core from "./core";
+import Constants from "./constants";
+import Chrono from "./chrono";
+import Log from "./log";
+import Emitter from "./emitter";
+import Tracker from "./tracker";
+import VideoTracker from "./videotracker";
+import VideoTrackerState from "./videotrackerstate";
+import { version } from "../package.json";
+
+const nrvideo = {
+  Constants,
+  Chrono,
+  Log,
+  Emitter,
+  Tracker,
+  VideoTracker,
+  VideoTrackerState,
+  Core,
+  version,
+};
+export default nrvideo;

package/src/log.js

@@ -0,0 +1,323 @@
+/**
+ * Static Log class
+ *
+ * @class
+ * @static
+ */
+class Log {
+  /**
+   * Sends an error console log.
+   * @param {...any} [msg] Message to show
+   * @static
+   */
+  static error(...msg) {
+    _report(msg, Log.Levels.ERROR, "darkred");
+  }
+
+  /**
+   * Sends a warning console log.
+   * @method Log.warn
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static warn(...msg) {
+    _report(msg, Log.Levels.WARNING, "darkorange");
+  }
+
+  /**
+   * Sends a notice console log.
+   * @method Log.notice
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static notice(...msg) {
+    _report([].slice.call(arguments), Log.Levels.NOTICE, "darkcyan");
+  }
+
+  /**
+   * Sends a debug message to console.
+   * @method Log.debug
+   * @static
+   * @param {...any} msg Message to show
+   */
+  static debug(...msg) {
+    _report(msg, Log.Levels.DEBUG, "indigo");
+  }
+
+  /**
+   * This utility method will add most of the HTML5 common event listeners to the player sent.
+   * Events will be reported as DEBUG level messages.
+   *
+   * @example
+   * // Already included events:
+   * ['canplay', 'buffering', 'waiting', 'ended', 'play', 'playing', 'pause', 'resume', 'error',
+   * 'abort', 'seek', 'seeking', 'seeked', 'stalled', 'dispose', 'loadeddata', 'loadstart',
+   * 'loadedmetadata']
+   *
+   * @method Log.debugCommonVideoEvents
+   * @static
+   * @param {object|function} o Object to attach the events.
+   * @param {array} [extraEvents]
+   * An array of extra events to watch. ie:  ['timeupdate', 'progress'].
+   * If the first item is null, no common events will be added.
+   * @param {function} [report] Callback function called to report events.
+   * Default calls Log.debug()
+   */
+  static debugCommonVideoEvents(o, extraEvents, report) {
+    try {
+      if (Log.level <= Log.Levels.DEBUG) {
+        report =
+          report ||
+          function (e) {
+            Log.debug("Event: " + e.type);
+          };
+
+        var playerEvents = [
+          "canplay",
+          "buffering",
+          "waiting",
+          "ended",
+          "play",
+          "playing",
+          "pause",
+          "resume",
+          "error",
+          "abort",
+          "seek",
+          "seeking",
+          "seeked",
+          "stalled",
+          "dispose",
+          "loadeddata",
+          "loadstart",
+          "loadedmetadata",
+        ];
+        if (extraEvents) {
+          if (extraEvents[0] === null) {
+            extraEvents.shift();
+            playerEvents = extraEvents;
+          } else {
+            playerEvents = playerEvents.concat(extraEvents);
+          }
+        }
+
+        for (var i = 0; i < playerEvents.length; i++) {
+          if (typeof o === "function") {
+            o.call(window, playerEvents[i], report);
+          } else if (o.on) {
+            o.on(playerEvents[i], report);
+          } else if (o.addEventListener) {
+            o.addEventListener(playerEvents[i], report);
+          } else if (o.addEventHandler) {
+            o.addEventHandler(playerEvents[i], report);
+          } else {
+            Log.warn(
+              "debugCommonVideoEvents: No common listener function found for ",
+              o
+            );
+          }
+        }
+      }
+    } catch (err) {
+      Log.warn(err);
+    }
+  }
+}
+
+/**
+ * Enum for log levels
+ * @enum {integer}
+ * @static
+ * @var
+ */
+Log.Levels = {
+  /** No console outputs */
+  SILENT: 5,
+  /** Console will show errors */
+  ERROR: 4,
+  /** Console will show warnings */
+  WARNING: 3,
+  /** Console will show notices (ie: life-cyrcle logs) */
+  NOTICE: 2,
+  /** Console will show debug messages. */
+  DEBUG: 1,
+  /** Show all messages. */
+  ALL: 0,
+};
+
+/**
+ * Only logs of this imporance or higher will be shown.
+ * @example Log.level = Log.Levels.ALL
+ * @default Log.Levels.ERROR
+ * @static
+ */
+Log.level = Log.Levels.ERROR;
+
+/**
+ * If true, logs will be outputed with colors.
+ * @default true
+ * @static
+ */
+Log.colorful = true;
+
+/**
+ * If true, logs will include the time mark.
+ * @default true
+ * @static
+ */
+Log.includeTime = true;
+
+/**
+ * Prefix included at the start of every log.
+ * @default '[New Relic]'
+ * @static
+ */
+Log.prefix = "[nrvideo]";
+
+// PRIVATE MEMBERS
+
+/**
+ * Returns a console message
+ *
+ * @private
+ * @param {array} msg Message array, error object or array of messages.
+ * @param {Log.Level} [level=Log.Levels.NOTICE] Defines the level of the error sent.
+ * Only errors with higher or equal level than Log.logLevel will be displayed.
+ * @param {string} [color='darkgreen'] Color of the header
+ * @see {@link Log.level}
+ */
+function _report(msg, level, color) {
+  level = level || Log.Levels.NOTICE;
+  color = color || "darkcyan";
+
+  var prefix = Log.prefix;
+  if (Log.includeTime) prefix += _getCurrentTime() + " ";
+  prefix += _level2letter(level) + ":";
+
+  // Show messages in actual console if level is enought
+  if (Log.level <= level && level !== Log.Levels.SILENT) {
+    if (
+      !Log.colorful ||
+      (typeof document !== "undefined" && document.documentMode)
+    ) {
+      // document.documentMode exits only in IE
+      _plainReport(msg, prefix);
+    } else {
+      // choose log method
+      var logMethod;
+      if (level === Log.Levels.ERROR && console.error) {
+        logMethod = console.error;
+      } else if (level === Log.Levels.WARNING && console.warn) {
+        logMethod = console.warn;
+      } else if (level === Log.Levels.DEBUG && console.debug) {
+        // NOTE: for some reason console.debug doesn't work on CAF Receivers.
+        if (window.cast == undefined) {
+          logMethod = console.debug;
+        } else {
+          logMethod = console.log;
+        }
+      } else {
+        logMethod = console.log;
+      }
+
+      // print message
+      prefix = "%c" + prefix;
+      msg.splice(0, 0, prefix, "color: " + color);
+      logMethod.apply(console, msg);
+    }
+  }
+}
+
+/**
+ * Returns the current time in format hh:mm:ss.mmm (with trailing 0s)
+ * @private
+ * @return {string} Current time.
+ */
+function _getCurrentTime() {
+  var d = new Date();
+  var hh = ("0" + d.getDate()).slice(-2);
+  var mm = ("0" + d.getMinutes()).slice(-2);
+  var ss = ("0" + d.getSeconds()).slice(-2);
+  var mmm = ("00" + d.getMilliseconds()).slice(-3);
+  return "[" + hh + ":" + mm + ":" + ss + "." + mmm + "]";
+}
+
+/**
+ * Returns a console message without style
+ *
+ * @private
+ * @param {(string|object|array)} msg Message string, object or array of messages.
+ * @param {string} prefix Prefix of the message.
+ */
+function _plainReport(msg, prefix) {
+  if (msg instanceof Array) {
+    for (var m in msg) {
+      _plainReport(msg[m], prefix);
+    }
+  } else {
+    if (typeof msg === "string") {
+      console.log(prefix + " " + msg);
+    } else {
+      console.log(prefix + "↵");
+      console.log(msg);
+    }
+  }
+}
+
+const _letters = {
+  4: "e", // Error
+  3: "w", // Warning
+  2: "n", // Notice
+  1: "d", // Debug
+};
+
+/**
+ * Transforms a level to a letter to identify every message.
+ *
+ * @private
+ * @param {sLog.Level} level Level of the message
+ */
+function _level2letter(level) {
+  return _letters[level];
+}
+
+/**
+ * This function is automatically executed at load.
+ * Will search inside window.location.search for attribute 'nrvideo-debug=X'.
+ * X can have one of these values, that will modify Log.Levels.
+ * 5: SILENT,
+ * 4: ERROR,
+ * 3: WARNING,
+ * 2: NOTICE,
+ * 1: DEBUG,
+ *
+ * If nrvideo-colors=false is present, Log.colorful will be set to false.
+ *
+ * @private
+ */
+function _loadLevelFromUrl() {
+  if (
+    typeof window !== "undefined" &&
+    window.location &&
+    window.location.search
+  ) {
+    var m = /\?.*&*nrvideo-debug=(.+)/i.exec(window.location.search);
+    if (m !== null) {
+      if (m[1] === "true") {
+        Log.level = Log.Levels.ALL;
+      } else {
+        Log.level = m[1];
+      }
+    }
+
+    var m2 = /\?.*&*nrvideo-colors=false/i.exec(window.location.search);
+    if (m2 !== null) {
+      Log.colorful = false;
+    }
+  }
+}
+
+// Execute load level
+_loadLevelFromUrl();
+
+export default Log;

package/src/recordEvent.js

@@ -0,0 +1,68 @@
+import { customEventAggregator } from "./agent.js";
+import { getPayloadSize } from "./utils.js";
+import Constants from "./constants";
+
+const { VALID_EVENT_TYPES, MAX_EVENT_SIZE } = Constants;
+
+/**
+ * Records a video event with the specified type and attributes
+ * @param {string} eventType - The type of event to record
+ * @param {Object} attributes - Additional attributes to include with the event
+ * @returns {boolean} - True if event was recorded successfully, false otherwise
+ */
+export function recordEvent(eventType, attributes = {}) {
+  // Input validation
+  if (
+    typeof eventType !== "string" ||
+    eventType.length === 0 ||
+    !VALID_EVENT_TYPES.includes(eventType)
+  ) {
+    console.warn("recordEvent: Invalid eventType provided:", eventType);
+    return false;
+  }
+
+  // Validate attributes parameter
+  if (
+    attributes !== null &&
+    (typeof attributes !== "object" || Array.isArray(attributes))
+  ) {
+    console.warn("recordEvent: attributes must be a plain object");
+    return false;
+  }
+
+  // Ensure attributes is an object (handle null case)
+  attributes = attributes || {};
+
+  // Check if NRVIDEO is properly initialized
+  if (!window.NRVIDEO || !window.NRVIDEO.info) {
+    console.error("recordEvent: NRVIDEO not properly initialized");
+    return false;
+  }
+
+  try {
+    const { appName } = window.NRVIDEO.info;
+
+    const eventObject = {
+      ...attributes,
+      eventType,
+      appName,
+      timestamp: Date.now(),
+    };
+
+    // Check event size to prevent oversized payloads
+    const eventSize = getPayloadSize(eventObject);
+
+    if (eventSize > MAX_EVENT_SIZE) {
+      console.warn(
+        `recordEvent: Event size (${eventSize} bytes) exceeds maximum (${MAX_EVENT_SIZE} bytes)`
+      );
+      return false;
+    }
+
+    customEventAggregator.add(eventObject);
+    return true;
+  } catch (error) {
+    console.error("recordEvent: Error recording event:", error);
+    return false;
+  }
+}