@newrelic/video-core 3.2.0-beta-1 → 4.0.1

package/src/retryQueueHandler.js

@@ -0,0 +1,124 @@
+import Log from "./log";
+import { dataSize } from "./utils";
+import Constants from "./constants";
+
+const { MAX_PAYLOAD_SIZE, MAX_EVENTS_PER_BATCH } = Constants;
+
+/**
+ * Retry Queue Handler for managing failed events with retry logic,
+ * backoff strategies, and persistent storage capabilities.
+ */
+export class RetryQueueHandler {
+  constructor() {
+    this.retryQueue = [];
+    this.maxQueueSize = MAX_EVENTS_PER_BATCH; // Max 1000 events
+    this.maxQueueSizeBytes = MAX_PAYLOAD_SIZE; // Max 1MB
+  }
+
+  /**
+   * Adds failed events to the retry queue for retry processing.
+   * @param {Array|object} events - Failed event(s) to add to retry queue
+   */
+  addFailedEvents(events) {
+    try {
+      const eventsArray = Array.isArray(events) ? events : [events];
+
+      Log.notice(`Adding ${eventsArray.length} failed events to retry queue`, {
+        queueSizeBefore: this.retryQueue.length,
+      });
+
+      for (const event of eventsArray) {
+        // Check queue size and make room if necessary
+        if (this.retryQueue.length >= this.maxQueueSize) {
+          this.evictOldestEvent();
+        }
+
+        // Check queue memory size and make room if necessary
+        const eventSize = dataSize(event);
+        while (dataSize(this.retryQueue) + eventSize > this.maxQueueSizeBytes) {
+          this.evictOldestEvent();
+        }
+
+        // Store event directly - no wrapper needed
+        this.retryQueue.push({ ...event });
+      }
+    } catch (err) {
+      Log.error("Failed to add events to retry queue:", err.message);
+    }
+  }
+
+  /**
+   * Discards an event that cannot be retried.
+   * @param {object} event - Event to discard
+   * @param {string} reason - Reason for discarding
+   * @private
+   */
+  discardEvent(event, reason) {
+    Log.warn(`Discarded event`, {
+      reason,
+      eventType: event.eventType,
+    });
+  }
+
+  /**
+   * Evicts the oldest event from the queue to make room.
+   * @private
+   */
+  evictOldestEvent() {
+    if (this.retryQueue.length > 0) {
+      const oldest = this.retryQueue.shift();
+      this.discardEvent(oldest, "Queue full - evicted oldest");
+    }
+  }
+
+  /**
+   * For unified harvesting - get retry events that fit within payload limits
+   * Removes the selected events from the retry queue since they're being retried
+   * @param {number} availableSpace - Available payload space in bytes
+   * @param {number} availableEventCount - Available event count
+   * @returns {Array} Array of events that fit within limits
+   */
+  getRetryEventsToFit(availableSpace, availableEventCount) {
+    const retryEvents = [];
+    let usedSpace = 0;
+    let eventCount = 0;
+
+    // Process retry queue in chronological order (oldest first) by iterating backwards
+    // This allows us to remove elements immediately without index shifting issues
+    for (let i = this.retryQueue.length - 1; i >= 0; i--) {
+      const event = this.retryQueue[i]; // 1000
+
+      if (eventCount >= availableEventCount) break;
+
+      const eventSize = dataSize(event);
+      if (usedSpace + eventSize > availableSpace) break;
+
+      // Add to beginning of retryEvents to maintain chronological order (oldest first)
+      retryEvents.unshift(event);
+      usedSpace += eventSize;
+      eventCount++;
+
+      // Remove immediately - safe because we're iterating backwards
+      this.retryQueue.splice(i, 1);
+    }
+
+    return retryEvents;
+  }
+
+  /**
+   * Gets the current retry queue size.
+   * @returns {number} Queue size
+   */
+  getQueueSize() {
+    return this.retryQueue.length;
+  }
+
+  /**
+   * Clears the retry queue.
+   */
+  clear() {
+    this.retryQueue = [];
+  }
+}
+
+export default RetryQueueHandler;

package/src/tracker.js

@@ -2,6 +2,8 @@ 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";
 
 /**
  * Tracker class provides the basic logic to extend Newrelic's Browser Agent capabilities.
@@ -233,17 +235,12 @@ class Tracker extends Emitter {
    * Internally, this will call {@see Emitter#emit}, so you could listen any event fired.
    *
    * @example
-   * tracker.send('BANNER_CLICK', { url: 'http....' })
+   * tracker.sendVideoAction('BANNER_CLICK', { url: 'http....' })
    *
    * @param {string} event Event name
    * @param {object} [att] Key:value dictionary filled with attributes.
    */
 
-  /**
-   * getElapsedTime: Calculate the time elapsed between two same actions
-   *
-   */
-
   sendVideoAction(event, att) {
     this.emit("VideoAction", event, this.getAttributes(att));
   }
@@ -264,6 +261,26 @@ class Tracker extends Emitter {
       this.getAttributes(att, "customAction")
     );
   }
+
+  /**
+   * Sets the harvest interval for video tracking.
+   * @param {*} interval - The interval in milliseconds.
+   * @returns {void}
+   */
+
+  setHarvestInterval(interval) {
+    if (!videoAnalyticsHarvester) {
+      Log.error("VideoAnalyticsHarvester is not available");
+      return;
+    }
+
+    try {
+      videoAnalyticsHarvester.setHarvestInterval(interval);
+    } catch (error) {
+      Log.error("Failed to set harvest interval:", error.message);
+      return;
+    }
+  }
 }
 
 /**

package/src/utils.js

@@ -1,64 +1,94 @@
+import pkg from "../package.json";
+import Log from "./log";
+
 /**
- * Makes an API call with retry logic and fallback to sendBeacon for final harvests
- * @param {Object} params - Request parameters
- * @param {string} params.url - The URL to send the request to
- * @param {Object} params.payload - The payload object containing body data
- * @param {Object} params.options - Request options
- * @param {boolean} params.options.isFinalHarvest - Whether this is a final harvest on page unload
- * @param {Function} callback - Callback function to handle the response
+ * Builds the harvest URL with proper query parameters.
+ * @returns {string} Harvest URL
  */
-export function callApi({ url, payload, options = {} }, callback) {
-  // Input validation
-  if (!url || !payload || !callback) {
-    console.error("callApi: Missing required parameters");
-    if (callback) callback({ retry: false, status: 0 });
-    return;
-  }
 
-  // The Browser Agent sends the 'body' part of the payload object as the actual request body.
-  let body;
+export function buildUrl(fallbackUrl) {
   try {
-    body = JSON.stringify(payload.body);
+    if (!window.NRVIDEO || !window.NRVIDEO.info) {
+      throw new Error("NRVIDEO info is not available.");
+    }
+
+    let { beacon, licenseKey, applicationID } = window.NRVIDEO.info;
+
+    if (!beacon || !licenseKey)
+      throw new Error(
+        "Options object provided by New Relic is not correctly initialized"
+      );
+
+    if (applicationID) {
+      return `https://${
+        fallbackUrl ? fallbackUrl : beacon
+      }/ins/1/${licenseKey}?a=${applicationID}&v=${pkg.version}&ref=${
+        window.location.href
+      }&ca=VA`;
+    }
+
+    return `https://${
+      fallbackUrl ? fallbackUrl : beacon
+    }/ins/1/${licenseKey}?&v=${pkg.version}&ref=${window.location.href}&ca=VA`;
   } catch (error) {
-    console.error("callApi: Error serializing payload", error);
-    callback({ retry: false, status: 0 });
-    return;
+    console.error(error.message);
+    return null; // Return null instead of undefined
   }
+}
 
-  // For final harvests on page unload, use sendBeacon for reliability.
-  if (options.isFinalHarvest && navigator.sendBeacon) {
-    try {
-      const success = navigator.sendBeacon(url, body);
-      // sendBeacon returns true if the request was successfully queued
-      callback({ retry: !success, status: success ? 200 : 0 });
-    } catch (e) {
-      // sendBeacon can fail if the payload is too large.
-      callback({ retry: true, status: 0 });
+/**
+ * Returns a function for use as a replacer parameter in JSON.stringify() to handle circular references.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value MDN - Cyclical object value}
+ * @returns {Function} A function that filters out values it has seen before.
+ */
+const getCircularReplacer = () => {
+  const seen = new WeakSet();
+  return (key, value) => {
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return;
+      }
+      seen.add(value);
     }
-    return;
+    return value;
+  };
+};
+
+/**
+ * The native JSON.stringify method augmented with a replacer function to handle circular references.
+ * Circular references will be excluded from the JSON output rather than triggering errors.
+ * @param {*} val - A value to be converted to a JSON string.
+ * @returns {string} A JSON string representation of the value, with circular references handled.
+ */
+function stringify(val) {
+  try {
+    return JSON.stringify(val, getCircularReplacer()) ?? "";
+  } catch (e) {
+    Log.error("Error stringifying value:", e.message);
+    return "";
   }
+}
+
+export function dataSize(data) {
+  if (typeof data === "string" && data.length) return data.length;
+  if (typeof data !== "object") return undefined;
+  // eslint-disable-next-line
+  if (
+    typeof ArrayBuffer !== "undefined" &&
+    data instanceof ArrayBuffer &&
+    data.byteLength
+  )
+    return data.byteLength;
+  if (typeof Blob !== "undefined" && data instanceof Blob && data.size)
+    return data.size;
+  if (typeof FormData !== "undefined" && data instanceof FormData)
+    return undefined;
 
-  fetch(url, {
-    method: "POST",
-    body: body,
-    headers: {
-      "Content-Type": "application/json", // More accurate content type
-    },
-    keepalive: options.isFinalHarvest, // Important for final harvest fallback
-  })
-    .then((response) => {
-      // Check for statuses that indicate a retry is needed.
-      const isRetry = shouldRetry(response.status);
-      callback({
-        retry: isRetry,
-        status: response.status,
-        ok: response.ok,
-      });
-    })
-    .catch(() => {
-      // Any network failure (e.g., no internet) should also trigger a retry.
-      callback({ retry: true, status: 0 });
-    });
+  try {
+    return stringify(data).length;
+  } catch (e) {
+    return undefined;
+  }
 }
 
 /**
@@ -66,7 +96,7 @@ export function callApi({ url, payload, options = {} }, callback) {
  * @param {number} status - HTTP status code
  * @returns {boolean} - True if request should be retried
  */
-function shouldRetry(status) {
+export function shouldRetry(status) {
   switch (status) {
     case 408: // Request Timeout
     case 429: // Too Many Requests
@@ -82,20 +112,51 @@ function shouldRetry(status) {
 }
 
 /**
- * Calculates the size of a payload object in megabytes
- * @param {Object} obj - The object to calculate size for
- * @returns {number} - Size in megabytes, or 0 if calculation fails
+ * Compresses a JSON payload using the Compression Streams API with Gzip.
+ * see @description(https://developer.mozilla.org/en-US/docs/Web/API/Compression_Streams_API)
+ * @param {object} payload - The JSON object to compress.
+ * @returns {Promise<Blob>} A Promise that resolves with a Blob of the Gzipped data.
  */
-export function getPayloadSize(obj) {
-  if (!obj || typeof obj !== "object") {
-    return 0;
-  }
 
+export function compressPayload(payload) {
+  const stringifiedPayload = JSON.stringify(payload);
+  const stream = new Blob([stringifiedPayload]).stream();
+  const compressionStream = new CompressionStream("gzip");
+  const compressedStream = stream.pipeThrough(compressionStream);
+
+  return new Response(compressedStream).blob();
+}
+
+/**
+ * Decompresses a gzipped Blob back to a JSON object using the Compression Streams API.
+ * @param {Blob|ArrayBuffer|Uint8Array} compressedData - The gzipped data to decompress.
+ * @returns {Promise<object>} A Promise that resolves with the decompressed JSON object.
+ */
+export async function decompressPayload(compressedData) {
   try {
-    const json = JSON.stringify(obj);
-    return new TextEncoder().encode(json).length / (1024 * 1024);
+    // Convert different input types to a stream
+    let stream;
+    if (compressedData instanceof Blob) {
+      stream = compressedData.stream();
+    } else if (compressedData instanceof ArrayBuffer) {
+      stream = new Blob([compressedData]).stream();
+    } else if (compressedData instanceof Uint8Array) {
+      stream = new Blob([compressedData]).stream();
+    } else {
+      throw new Error("Unsupported compressed data type");
+    }
+
+    // Decompress using DecompressionStream
+    const decompressionStream = new DecompressionStream("gzip");
+    const decompressedStream = stream.pipeThrough(decompressionStream);
+
+    // Convert back to text
+    const response = new Response(decompressedStream);
+    const decompressedText = await response.text();
+
+    // Parse JSON
+    return JSON.parse(decompressedText);
   } catch (error) {
-    console.error("getPayloadSize: Error calculating payload size", error);
-    return 0;
+    throw new Error(`Failed to decompress payload: ${error.message}`);
   }
 }

package/src/videoConfiguration.js

@@ -0,0 +1,113 @@
+import Log from "./log";
+import Constants from "./constants";
+
+const { COLLECTOR } = Constants;
+
+/**
+ * Enhanced video analytics configuration system that extends the existing auth configuration.
+ * Provides feature flags, retry policies, and advanced harvesting options.
+ */
+class VideoConfiguration {
+  /**
+   * Validates and sets the video analytics configuration.
+   * @param {object} userConfig - User provided configuration
+   * @returns {boolean} True if configuration is valid and set
+   */
+
+  setConfiguration(userInfo) {
+    this.initializeGlobalConfig(userInfo);
+    Log.notice("Video analytics configuration initialized successfully");
+    return true;
+  }
+
+  /**
+   * Validates required configuration fields.
+   * @param {object} config - Configuration to validate
+   * @returns {boolean} True if valid
+   */
+  validateRequiredFields(info) {
+    if (!info || typeof info !== "object") {
+      Log.error("Configuration must be an object");
+      return false;
+    }
+
+    const { licenseKey, appName, region, applicationID, beacon } = info;
+
+    if (!licenseKey) {
+      Log.error("licenseKey is required");
+      return false;
+    }
+
+    if (applicationID) {
+      if (!beacon) {
+        Log.error("beacon is required when applicationID is provided");
+        return false;
+      } else {
+        const validBeacons = Object.values(COLLECTOR).flatMap((el) => el);
+        if (!validBeacons.includes(beacon)) {
+          Log.error(`Invalid beacon: ${beacon}`);
+          return false;
+        }
+      }
+    } else {
+      if (!appName || !region) {
+        Log.error(
+          "appName and region are required when applicationID is not provided"
+        );
+        return false;
+      }
+
+      if (!COLLECTOR[region]) {
+        Log.error(
+          `Invalid region: ${region}. Valid regions are: ${Object.keys(
+            COLLECTOR
+          ).join(", ")}`
+        );
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Initializes the global NRVIDEO configuration object.
+   */
+  initializeGlobalConfig(userInfo) {
+    if (!this.validateRequiredFields(userInfo)) return;
+
+    let { licenseKey, appName, region, beacon, applicationID } = userInfo;
+
+    if (region === "US") {
+      beacon = Constants.COLLECTOR["US"][0];
+    } else {
+      beacon = beacon || COLLECTOR[region];
+    }
+
+    window.NRVIDEO = {
+      // Existing format for backward compatibility
+      info: {
+        ...(region ? { region } : {}), // Only include region if available
+        beacon,
+        licenseKey,
+        applicationID,
+        ...(applicationID ? {} : { appName }), // Only include appName when no applicationID
+      },
+    };
+  }
+}
+
+// Create singleton instance
+const videoConfiguration = new VideoConfiguration();
+
+/**
+ * Sets the video analytics configuration.
+ * @param {object} config - Configuration object
+ * @returns {boolean} True if configuration was set successfully
+ */
+export function setVideoConfig(info) {
+  return videoConfiguration.setConfiguration(info);
+}
+
+export { videoConfiguration };
+export default VideoConfiguration;

package/src/videotrackerstate.js

@@ -135,6 +135,12 @@ class VideoTrackerState {
     /** Content only. Chrono that counts time since last AD_END. */
     this.timeSinceLastAd = new Chrono();
 
+    /** Chrono that counts time since last error event. */
+    this.timeSinceLastError = new Chrono();
+
+    /** Chrono that counts time since last ad error event. */
+    this.timeSinceLastAdError = new Chrono();
+
     /** Chrono that counts time since last *_RESUME. Only for buffering events. */
     this.timeSinceResumed = new Chrono();
 
@@ -231,6 +237,12 @@ class VideoTrackerState {
         att.timeSinceAdSeekBegin = this.timeSinceSeekBegin.getDeltaTime();
       if (this.isAdBreak)
         att.timeSinceAdBreakBegin = this.timeSinceAdBreakStart.getDeltaTime();
+
+      // Only include timeSinceLastAdError if an ad error has occurred
+      if (this.numberOfErrors > 0 && this.timeSinceLastAdError.startTime > 0) {
+        att.timeSinceLastAdError = this.timeSinceLastAdError.getDeltaTime();
+      }
+
       att.numberOfAds = this.numberOfAds;
     } else {
       // Content only
@@ -247,6 +259,12 @@ class VideoTrackerState {
       if (this.isSeeking)
         att.timeSinceSeekBegin = this.timeSinceSeekBegin.getDeltaTime();
       att.timeSinceLastAd = this.timeSinceLastAd.getDeltaTime();
+
+      // Only include timeSinceLastError if a content error has occurred
+      if (this.numberOfErrors > 0 && this.timeSinceLastError.startTime > 0) {
+        att.timeSinceLastError = this.timeSinceLastError.getDeltaTime();
+      }
+
       att.numberOfVideos = this.numberOfVideos;
     }
     att.numberOfErrors = this.numberOfErrors;
@@ -556,11 +574,17 @@ class VideoTrackerState {
   }
 
   /**
-   * Increments error counter.
+   * Increments error counter and starts appropriate error timer.
    */
   goError() {
     this.isError = true;
     this.numberOfErrors++;
+
+    if (this.isAd()) {
+      this.timeSinceLastAdError.start();
+    } else {
+      this.timeSinceLastError.start();
+    }
   }
 
   /**