@newrelic/video-core 5.0.2 → 5.1.0

package/dist/types/core.d.ts

@@ -0,0 +1,54 @@
+import { RawVideoConfigInfo, RawVideoConfigOptions } from "./videoConfiguration";
+import Emitter from "./emitter";
+/** Structural contract Core needs from anything passed to addTracker/removeTracker. */
+export interface TrackerLike extends Emitter {
+    dispose(): void;
+    trackerInit?(): void;
+}
+export interface CoreAddTrackerOptions {
+    info?: RawVideoConfigInfo;
+    config?: RawVideoConfigOptions;
+    src?: string;
+}
+/**
+ * Static class that sums up core functionalities of the library.
+ * @static
+ */
+declare class Core {
+    /**
+     * Add a tracker to the system. Trackers added will start reporting its events to the video analytics backend.
+     *
+     * @param {(Emitter|Tracker)} tracker Tracker instance to add.
+     * @param {object} options Configuration options including video analytics settings.
+     */
+    static addTracker(tracker: TrackerLike, options?: CoreAddTrackerOptions): void;
+    /**
+     * Disposes and remove given tracker. Removes its listeners.
+     *
+     * @param {Tracker} tracker Tracker to remove.
+     */
+    static removeTracker(tracker: TrackerLike): void;
+    /**
+     * Returns the array of trackers.
+     *
+     * @returns {Tracker[]} Array of trackers.
+     */
+    static getTrackers(): TrackerLike[];
+    /**
+     * Enhanced send method with performance timing.
+     * @param {string} eventType - Type of event
+     * @param {string} actionName - Action name
+     * @param {object} data - Event data
+     */
+    static send(eventType: string, actionName: string, data?: Record<string, any>): boolean | undefined;
+    /**
+     * Sends an error event.
+     * This may be used for external errors launched by the app, the network or
+     * any external factor. Note that errors within the player are normally reported with
+     * tracker.sendError, so this method should not be used to report those.
+     *
+     * @param {object} att attributes to be sent along the error.
+     */
+    static sendError(att?: Record<string, any>): boolean | undefined;
+}
+export default Core;

package/dist/types/emitter.d.ts

@@ -0,0 +1,42 @@
+export interface TrackerEventPayload {
+    eventType: string;
+    type: string;
+    data: Record<string, unknown>;
+    target: Emitter;
+}
+export type ListenerCallback = (payload: TrackerEventPayload) => void;
+/**
+ * This base class implements a basic behavior of listeners and events. Extend this object to have
+ * this feature built-in inside your classes.
+ *
+ * @class Emitter
+ */
+declare class Emitter {
+    _listeners?: Record<string, ListenerCallback[]>;
+    /**
+     * Sets a listener to a given event. Use {@link emit} to trigger those events.
+     * Pass '*' to listen ALL events.
+     *
+     * @param {string} event Name of the event.
+     * @param {function} callback Callback of the event. Receives event and data.
+     * @return this
+     */
+    on(event: string, callback: ListenerCallback): this | undefined;
+    /**
+     * Removes given callback from the listeners of this object.
+     *
+     * @param {string} event Name of the event.
+     * @param {function} callback Callback of the event.
+     * @return this
+     */
+    off(event: string, callback: ListenerCallback): this;
+    /**
+     * Emits given event, triggering all the associated callbacks.
+     *
+     * @param {string} event Name of the event.
+     * @param {object} [data] Custom data to be sent to the callbacks.
+     * @return this
+     */
+    emit(eventType: string, event: string, data?: Record<string, unknown>): this;
+}
+export default Emitter;

package/dist/types/eventAggregator.d.ts

@@ -0,0 +1,97 @@
+import { EventAttributes } from "./utils/eventBuilder";
+export type SmartHarvestCallback = (reason: "overflow" | "smart", percentage: number) => void;
+/**
+ * Enhanced event buffer that manages video events with unified priority handling
+ * and automatic size management. All events are treated with equal priority
+ * unless explicitly specified otherwise.
+ */
+export declare class NrVideoEventAggregator {
+    buffer: EventAttributes[];
+    maxPayloadSize: number;
+    maxEventsPerBatch: number;
+    currentPayloadSize: number;
+    totalEvents: number;
+    smartHarvestPayloadThreshold: number;
+    overflowPayloadThreshold: number;
+    smartHarvestEventThreshold: number;
+    overflowEventThreshold: number;
+    onSmartHarvestTrigger: SmartHarvestCallback | null;
+    constructor();
+    /**
+     * If an event with the specified actionName 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 {object} eventObject - The event object to add or use as replacement. Should contain an actionName property.
+     * @returns {boolean} True if the operation succeeded, false if an error occurred
+     */
+    addOrReplaceByActionName(actionName: string, eventObject: EventAttributes): boolean;
+    /**
+     * 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: string, viewId: string, eventObject: EventAttributes): boolean;
+    /**
+     * 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: string, viewId: string): EventAttributes | null;
+    /**
+     * Returns the existing event in buffer matching the given actionName, or null.
+     * @param {string} actionName
+     * @returns {object|null}
+     */
+    findByActionName(actionName: string): EventAttributes | null;
+    /**
+     * Adds an event to the unified buffer.
+     * All events are treated equally in FIFO order.
+     * @param {object} eventObject - The event to add
+     * @param {number} index - index at which the event should be replaced with
+     */
+    add(eventObject: EventAttributes, index?: number): boolean;
+    /**
+     * Checks if smart harvest should be triggered based on dual threshold system.
+     * Triggers when EITHER condition is met first:
+     * - 60% of payload size (600KB) OR 60% of event count (600 events)
+     * - 90% of payload size (900KB) OR 90% of event count (900 events)
+     * @private
+     */
+    checkSmartHarvestTrigger(): void;
+    /**
+     * Sets the callback function for smart harvest triggers.
+     * @param {Function} callback - Function to call when smart harvest is triggered
+     */
+    setSmartHarvestCallback(callback: SmartHarvestCallback): void;
+    /**
+     * Drains all events from the buffer in FIFO order (first in, first out).
+     * No limits needed since buffer already manages size via makeRoom() and smart harvest triggers.
+     * @returns {Array} Array of events in order they were added
+     */
+    drain(): EventAttributes[];
+    /**
+     * Checks if the buffer is empty.
+     * @returns {boolean} True if all buffers are empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the total number of events across all buffers.
+     * @returns {number} Total event count
+     */
+    size(): number;
+    /**
+     * Clears the entire buffer.
+     */
+    clear(): void;
+    /**
+     * Makes room in the buffer by removing the oldest event.
+     * Uses FIFO approach - removes the first (oldest) event.
+     * @private
+     */
+    makeRoom(newEventSize: number): void;
+}
+export default NrVideoEventAggregator;

package/dist/types/index.d.ts

@@ -0,0 +1,33 @@
+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 { NrVideoEventAggregator } from "./eventAggregator";
+import { RetryQueueHandler } from "./retryQueueHandler";
+import { OptimizedHttpClient } from "./optimizedHttpClient";
+import { HarvestScheduler } from "./browser/harvestScheduler";
+import { recordEvent } from "./recordEvent";
+declare const nrvideo: {
+    Constants: typeof Constants;
+    Chrono: typeof Chrono;
+    Log: typeof Log;
+    Emitter: typeof Emitter;
+    Tracker: typeof Tracker;
+    VideoTracker: typeof VideoTracker;
+    VideoTrackerState: typeof VideoTrackerState;
+    Core: typeof Core;
+    version: string;
+    NrVideoEventAggregator: typeof NrVideoEventAggregator;
+    RetryQueueHandler: typeof RetryQueueHandler;
+    OptimizedHttpClient: typeof OptimizedHttpClient;
+    HarvestScheduler: typeof HarvestScheduler;
+    recordEvent: typeof recordEvent;
+};
+export { videoAnalyticsHarvester } from "./browser/agent";
+export { connectedDeviceAnalyticsHarvester } from "./connectedDevice/connectedDeviceAgent";
+export { getRegisteredHarvester } from "./recordEvent";
+export default nrvideo;

package/dist/types/log.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Static Log class
+ *
+ * @class
+ * @static
+ */
+declare class Log {
+    static Levels: Record<string, number>;
+    static level: number | string;
+    static colorful: boolean;
+    static includeTime: boolean;
+    static prefix: string;
+    /**
+     * Sends an error console log.
+     * @param {...any} [msg] Message to show
+     * @static
+     */
+    static error(...msg: any[]): void;
+    /**
+     * Sends a warning console log.
+     * @method Log.warn
+     * @static
+     * @param {...any} msg Message to show
+     */
+    static warn(...msg: any[]): void;
+    /**
+     * Sends a notice console log.
+     * @method Log.notice
+     * @static
+     * @param {...any} msg Message to show
+     */
+    static notice(...msg: any[]): void;
+    /**
+     * Sends a debug message to console.
+     * @method Log.debug
+     * @static
+     * @param {...any} msg Message to show
+     */
+    static debug(...msg: any[]): void;
+    /**
+     * 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: any, extraEvents?: any[], report?: (e: any) => void): void;
+}
+export default Log;

package/dist/types/obfuscate.d.ts

@@ -0,0 +1,13 @@
+export interface ObfuscationRule {
+    regex: string | RegExp;
+    replacement: string;
+}
+/**
+ * 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 declare function applyObfuscationRules(jsonString: string, rules?: ObfuscationRule[]): string;

package/dist/types/optimizedHttpClient.d.ts

@@ -0,0 +1,83 @@
+export interface HttpRequestOptions {
+    url: string;
+    payload: {
+        body: any;
+    };
+    options?: {
+        isFinalHarvest?: boolean;
+    };
+}
+export interface HttpResultCallback {
+    (result: {
+        retry?: boolean;
+        status: number;
+        statusText?: string;
+        error?: string;
+    }): void;
+}
+interface InternalRequest {
+    url: string;
+    payload: {
+        body: any;
+    };
+    options: {
+        isFinalHarvest?: boolean;
+    };
+    callback: HttpResultCallback;
+}
+interface RequestResult {
+    success: boolean;
+    status: number;
+    statusText?: string;
+    error?: string;
+}
+/**
+ * Optimized HTTP client for video analytics data transmission with
+ * performance monitoring and efficient request handling.
+ */
+export declare class OptimizedHttpClient {
+    /**
+     * Sends data to the specified URL with performance monitoring.
+     * @param {object} requestOptions - Request configuration
+     * @param {string} requestOptions.url - Target URL
+     * @param {object} requestOptions.payload - Request payload
+     * @param {object} requestOptions.options - Additional options
+     * @param {Function} callback - Callback function for handling response
+     * @returns {Promise<void>}
+     */
+    send(requestOptions: HttpRequestOptions, callback: HttpResultCallback): Promise<void>;
+    /**
+     * Executes an HTTP request with timeout and error handling.
+     * @param {object} request - Request object
+     * @private
+     */
+    executeRequest(request: InternalRequest): Promise<void>;
+    /**
+     * Handles request completion.
+     * @param {object} request - Request object
+     * @param {object} result - Request result
+     * @param {number} startTime - Request start timestamp
+     * @param {string} endpoint - The endpoint that was used for the request
+     * @private
+     */
+    handleRequestComplete(request: InternalRequest, result: RequestResult, startTime?: number): void;
+    /**
+     * Sends data using navigator.sendBeacon for final harvests.
+     * @param {string} url - Target URL
+     * @param {string} body - Request body
+     * @returns {Promise<boolean>} True if successful
+     * @private
+     */
+    sendWithBeacon(url: string, body: string): Promise<boolean>;
+    /**
+     * Fetch with timeout implementation.
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortController|MDN AbortController}
+     * @param {string} url - Target URL
+     * @param {object} options - Fetch options
+     * @param {number} timeout - Timeout in milliseconds
+     * @returns {Promise<Response>} Fetch response
+     * @private
+     */
+    fetchWithTimeout(url: string, options: RequestInit, timeout: number): Promise<Response>;
+}
+export default OptimizedHttpClient;

package/dist/types/recordEvent.d.ts

@@ -0,0 +1,30 @@
+import { EventAttributes, Harvester } from "./utils/eventBuilder";
+export type { EventAttributes, Harvester };
+/**
+ * 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 declare function registerHarvester(key: string, harvester: Harvester): void;
+/**
+ * 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 declare function getRegisteredHarvester(key: string): Harvester | undefined;
+export declare function recordEvent(eventType: string, attributes?: EventAttributes): boolean | undefined;

package/dist/types/retryQueueHandler.d.ts

@@ -0,0 +1,46 @@
+import { EventAttributes } from "./utils/eventBuilder";
+/**
+ * Retry Queue Handler for managing failed events with retry logic,
+ * backoff strategies, and persistent storage capabilities.
+ */
+export declare class RetryQueueHandler {
+    retryQueue: EventAttributes[];
+    maxQueueSize: number;
+    maxQueueSizeBytes: number;
+    constructor();
+    /**
+     * Adds failed events to the retry queue for retry processing.
+     * @param {Array|object} events - Failed event(s) to add to retry queue
+     */
+    addFailedEvents(events: EventAttributes | EventAttributes[]): void;
+    /**
+     * Discards an event that cannot be retried.
+     * @param {object} event - Event to discard
+     * @param {string} reason - Reason for discarding
+     * @private
+     */
+    discardEvent(event: EventAttributes, reason: string): void;
+    /**
+     * Evicts the oldest event from the queue to make room.
+     * @private
+     */
+    evictOldestEvent(): void;
+    /**
+     * 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: number, availableEventCount: number): EventAttributes[];
+    /**
+     * Gets the current retry queue size.
+     * @returns {number} Queue size
+     */
+    getQueueSize(): number;
+    /**
+     * Clears the retry queue.
+     */
+    clear(): void;
+}
+export default RetryQueueHandler;

package/dist/types/tracker.d.ts

@@ -0,0 +1,176 @@
+import Emitter from "./emitter";
+import Chrono from "./chrono";
+import { Harvester } from "./utils/eventBuilder";
+export interface TrackerOptions {
+    heartbeat?: number;
+    customData?: Record<string, any>;
+    parentTracker?: Tracker;
+}
+/**
+ * Tracker class provides the basic logic to extend Newrelic's Browser Agent capabilities.
+ * Trackers are designed to listen third party elements (like video tags, banners, etc.) and send
+ * information over to Browser Agent. Extend this class to create your own tracker, override
+ * registerListeners and unregisterListeners for full coverage!
+ *
+ * @example
+ * Tracker instances should be added to Core library to start sending data:
+ * nrvideo.Core.addTracker(new Tracker())
+ *
+ * @extends Emitter
+ */
+declare class Tracker extends Emitter {
+    static Events: Record<string, string>;
+    customData: Record<string, any>;
+    heartbeat: number | null;
+    parentTracker: Tracker | null;
+    /**
+     * Set externally by subclasses (VideoTracker, which assigns a real
+     * VideoTrackerState instance) / tests (which assign plain `{ _isAd }`
+     * objects) before any method that reads `this.state._isAd` is invoked.
+     * Not initialized in the base constructor. Loosely typed (`any`) since
+     * both shapes need to be assignable here without a circular import of
+     * VideoTrackerState into the base Tracker.
+     */
+    state?: any;
+    _trackerReadyChrono: Chrono;
+    _actionTable: any;
+    _actionAdTable: any;
+    _heartbeatInterval?: ReturnType<typeof setInterval>;
+    /**
+     * Constructor, receives options. You should call {@see registerListeners} after this.
+     *
+     * @param {Object} [options] Options for the tracker. See {@link setOptions}.
+     */
+    constructor(options?: TrackerOptions);
+    /**
+     * Set options for the Tracker.
+     *
+     * @param {Object} [options] Options for the tracker.
+     * @param {number} [options.heartbeat] Set time between heartbeats. See {@link heartbeat}.
+     * @param {Object} [options.customData] Set custom data. See {@link customData}.
+     * @param {Tracker} [options.parentTracker] Set parent tracker. See {@link parentTracker}.
+     */
+    setOptions(options?: TrackerOptions): void;
+    /**
+     * Prepares tracker to dispose. Calls {@see unregisterListeners} and drops references.
+     */
+    dispose(): void;
+    /**
+     * Override this method to register listeners to third party elements.
+     *
+     * @example
+     * class SpecificTracker extends Tracker {
+     *  registerListeners() {
+     *    this.player.on('play', () => this.playHandler)
+     *  }
+     *
+     *  playHandler() {
+     *    this.emit(Tracker.Events.REQUESTED)
+     *  }
+     * }
+     */
+    registerListeners(): void;
+    /**
+     * Override this method to unregister listeners to third party elements created with
+     * {@see registerListeners}.
+     *
+     * @example
+     * class SpecificTracker extends Tracker {
+     *  registerListeners() {
+     *    this.player.on('play', () => this.playHandler)
+     *  }
+     *
+     *  unregisterListeners() {
+     *    this.player.off('play', () => this.playHandler)
+     *  }
+     *
+     *  playHandler() {
+     *    this.emit(Tracker.Events.REQUESTED)
+     *  }
+     * }
+     */
+    unregisterListeners(): void;
+    /**
+     * Returns heartbeat time interval. 30000 (30s) if not set. See {@link setOptions}.
+     * @return {number} Heartbeat interval in ms.
+     * @final
+     */
+    getHeartbeat(): number;
+    /**
+     * Starts heartbeating. Interval period set by options.heartbeat. Min 2000 ms.
+     * This method is automaticaly called by the tracker once sendRequest is called.
+     */
+    startHeartbeat(): void;
+    /**
+     * Stops heartbeating. This method is automaticaly called by the tracker.
+     */
+    stopHeartbeat(): void;
+    /**
+     * Heartbeating allows you to call this function each X milliseconds, defined by
+     * {@link getHeartbeat}. This is useful to send regular events to track changes.
+     *
+     * By default it will send {@link Tracker.Events.HEARTBEAT}.
+     * To start heartbeating use {@link startHeartbeat} and to stop them use {@link stopHeartbeat}.
+     *
+     * @example
+     * Override this method to define your own Heartbeat reporting.
+     *
+     * class TrackerChild extends Tracker {
+     *  sendHeartbeat (att) {
+     *    this.send('MY_HEARBEAT_EVENT')
+     *  }
+     * }
+     *
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendHeartbeat(att?: Record<string, any>): void;
+    /**
+     * Override this method to return attributes for actions.
+     *
+     * @example
+     * class SpecificTracker extends Tracker {
+     *  getAttributes(att) {
+     *    att = att || {}
+     *    att.information = 'something'
+     *    return att
+     *  }
+     * }
+     *
+     * @param {object} [att] Collection of key value attributes
+     * @return {object} Filled attributes
+     * @final
+     */
+    getAttributes(att?: Record<string, any>, eventType?: string): Record<string, any>;
+    /** Override to change of the Version of tracker. ie: '1.0.1' */
+    getTrackerVersion(): string;
+    /** Override to change of the Name of the tracker. ie: 'custom-html5' */
+    getTrackerName(): string;
+    /**
+     * Send given event. Will automatically call {@see getAttributes} to fill information.
+     * Internally, this will call {@see Emitter#emit}, so you could listen any event fired.
+     *
+     * @example
+     * tracker.sendVideoAction('BANNER_CLICK', { url: 'http....' })
+     *
+     * @param {string} event Event name
+     * @param {object} [att] Key:value dictionary filled with attributes.
+     */
+    sendVideoAction(event: string, att?: Record<string, any>): void;
+    sendVideoAdAction(event: string, att?: Record<string, any>): void;
+    sendVideoErrorAction(event: string, att?: Record<string, any>): void;
+    sendVideoCustomAction(event: string, att?: Record<string, any>): void;
+    /**
+     * Sets the harvest interval for video tracking.
+     * @param {*} interval - The interval in milliseconds.
+     * @returns {void}
+     */
+    setHarvestInterval(interval: number): void;
+    /**
+     * 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(): Harvester | null;
+}
+export default Tracker;