@newrelic/video-core 5.0.2 → 5.1.0

package/dist/types/utils/eventBuilder.d.ts

@@ -0,0 +1,69 @@
+export type EventAttributes = Record<string, any>;
+export interface Harvester {
+    addEvent(eventObject: EventAttributes): boolean;
+    setHarvestInterval(ms: number): void;
+    /** Set (or clear, with `null`) the callback run just before the next harvest drain. */
+    setBeforeDrainCallback(callback: (() => void) | null): void;
+    /** Merge fresh QoE KPI values into the buffered QOE_AGGREGATE event for a view. */
+    refreshQoeKpis(freshKpis: EventAttributes, viewId?: string): void;
+    /** Force the next harvest cycle to be treated as a QoE cycle. Only the browser harvester supports this — the connected-device harvester does not implement it. */
+    forceNextQoeCycle?(): void;
+}
+interface BuildEventObjectsOptions {
+    addTimeSinceLoad?: boolean;
+}
+/**
+ * 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 declare function buildEventObjects(eventType: string, attributes: EventAttributes, info: Record<string, any>, { addTimeSinceLoad }?: BuildEventObjectsOptions): {
+    eventObject: EventAttributes;
+    qoeEventObject: EventAttributes | null;
+};
+/**
+ * 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 declare function dispatchRecordEvent(eventType: string, attributes: EventAttributes, info: Record<string, any>, harvester: Harvester | null | undefined, qoeEnabled: boolean, { addTimeSinceLoad }?: BuildEventObjectsOptions): boolean;
+export {};

package/dist/types/utils/harvestTimer.d.ts

@@ -0,0 +1,45 @@
+export interface HarvestTimerOptions {
+    /** Initial tick interval in ms. */
+    interval: number;
+    /** Pipeline-specific drain callback. Awaited; the next tick is scheduled in `finally`. */
+    onTick: () => Promise<void> | void;
+    /** Prefix for the error log when `onTick` throws (e.g. "HarvestScheduler"). */
+    errorLabel: string;
+}
+export interface HarvestTimer {
+    start: () => void;
+    stop: () => void;
+    cancelAndReschedule: () => void;
+    updateInterval: (ms: number) => void;
+    isRunning: () => boolean;
+}
+/**
+ * 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 declare function createHarvestTimer({ interval, onTick, errorLabel }: HarvestTimerOptions): HarvestTimer;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Builds the harvest URL with proper query parameters.
+ * @returns {string} Harvest URL
+ */
+export declare function buildUrl(fallbackUrl?: string): string | null;
+export declare function dataSize(data: unknown): number | undefined;
+/**
+ * Determines if a request should be retried based on HTTP status code
+ * @param {number} status - HTTP status code
+ * @returns {boolean} - True if request should be retried
+ */
+export declare function shouldRetry(status: number): boolean;
+/**
+ * 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 declare function compressPayload(payload: unknown): Promise<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 declare function decompressPayload(compressedData: Blob | ArrayBuffer | Uint8Array): Promise<unknown>;
+/**
+ * Filters an object to include only the specified keys.
+ * Creates a new object containing only the key-value pairs from the source object
+ * that match the provided keys array.
+ * @param {string[]} keys - Array of keys to extract from the object. If empty, null, or not an array, returns the original object.
+ * @param {object} obj - The source object to extract entries from.
+ * @returns {object} A new object containing only the entries that match the specified keys. Returns an empty object if obj is invalid.
+ * @example
+ * const data = { name: 'John', age: 30, city: 'NYC', country: 'USA' };
+ * const filtered = getObjectEntriesForKeys(['name', 'city'], data);
+ * // Returns: { name: 'John', city: 'NYC' }
+ */
+export declare function getObjectEntriesForKeys(keys: string[], obj: Record<string, unknown>): Record<string, unknown>;

package/dist/types/utils/qoeFilters.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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
+ */
+type QoeEvent = Record<string, any>;
+type QoeSnapshots = Record<string, Record<string, any>>;
+interface QoeBuffer {
+    addOrReplaceByActionNameAndViewId(actionName: string, viewId: string, event: QoeEvent): boolean;
+    addOrReplaceByActionName(actionName: string, event: QoeEvent): boolean;
+    add(event: QoeEvent): boolean;
+    findByActionNameAndViewId(actionName: string, viewId: string): QoeEvent | null;
+    findByActionName(actionName: string): QoeEvent | null;
+}
+/**
+ * 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 declare function bufferEventWithQoeDedup(buffer: QoeBuffer, eventObject: QoeEvent): boolean;
+/**
+ * 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 declare function refreshQoeKpisInBuffer(buffer: QoeBuffer, freshKpis: QoeEvent, viewId?: string): void;
+/**
+ * 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 declare function qoeKpisUnchanged(snapshots: QoeSnapshots, event: QoeEvent): boolean;
+/**
+ * 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 declare function saveQoeKpiSnapshot(snapshots: QoeSnapshots, event: QoeEvent): void;
+/**
+ * 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 declare function partitionByQoeCycle(drained: QoeEvent[], isQoeCycle: boolean, buffer: QoeBuffer): QoeEvent[];
+/**
+ * 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 declare function applyQoeDirtyFilter(filtered: QoeEvent[], snapshots: QoeSnapshots, isForced: boolean): void;
+export {};

package/dist/types/videoConfiguration.d.ts

@@ -0,0 +1,90 @@
+import { VegaEndpoint } from "./connectedDevice/connectedDeviceConstants";
+import { ObfuscationRule } from "./obfuscate";
+export interface NrVideoBrowserInfo {
+    region?: string;
+    beacon: string;
+    licenseKey: string;
+    applicationID?: string;
+    appName?: string;
+}
+export interface NrVideoBrowserConfig {
+    qoeAggregate: boolean;
+    qoeIntervalFactor: number;
+    obfuscate: ObfuscationRule[];
+}
+export interface NrVideoCdInfo {
+    accountId?: string;
+    applicationToken: string;
+    endpoint: VegaEndpoint;
+    appName?: string;
+    applicationID?: string;
+    deviceInfo?: unknown;
+}
+export interface NrVideoCdConfig {
+    qoeAggregate: boolean;
+    qoeIntervalFactor: number;
+    obfuscate: ObfuscationRule[];
+}
+/** Raw, unvalidated user-supplied config — shape varies by pipeline (`src`). */
+export type RawVideoConfigInfo = Record<string, any>;
+export type RawVideoConfigOptions = Record<string, any>;
+/**
+ * Enhanced video analytics configuration system that extends the existing auth configuration.
+ * Provides feature flags, retry policies, and advanced harvesting options.
+ */
+declare class VideoConfiguration {
+    /**
+     * Validates and sets the video analytics configuration.
+     * @param {object} userInfo - User provided configuration
+     * @param {object} [config] - Optional configuration object
+     * @returns {boolean} True if configuration is valid and set
+     */
+    setConfiguration(userInfo: RawVideoConfigInfo, config?: RawVideoConfigOptions, src?: string): boolean;
+    /**
+     * Validates required Vega configuration fields.
+     * @param {object} info
+     * @returns {boolean} True if valid
+     */
+    validateVegaFields(info: RawVideoConfigInfo): boolean;
+    /**
+     * Validates required configuration fields.
+     * @param {object} config - Configuration to validate
+     * @returns {boolean} True if valid
+     */
+    validateRequiredFields(info: RawVideoConfigInfo): boolean;
+    /**
+     * Validates optional config fields.
+     * @param {object} config - Config to validate
+     * @returns {boolean} True if valid
+     */
+    validateConfigFields(config?: RawVideoConfigOptions): boolean;
+    /**
+     * Filters obfuscation rules, warning about and removing invalid ones.
+     * @param {Array} rules - Raw obfuscation rules
+     * @returns {Array} Valid rules only
+     */
+    filterObfuscateRules(rules?: any[]): ObfuscationRule[];
+    /**
+     * Sanitizes qoeIntervalFactor, defaulting to Constants.DEFAULT_QOE_INTERVAL_FACTOR
+     * if the value is not a positive integer.
+     * @param {*} value
+     * @returns {number}
+     */
+    sanitizeQoeIntervalFactor(value: unknown): number;
+    /**
+     * Initializes the global NRVIDEO configuration object.
+     * @param {object} userInfo - User provided configuration
+     * @param {object} [config] - Optional configuration object
+     */
+    initializeGlobalConfig(userInfo: RawVideoConfigInfo, config?: RawVideoConfigOptions, src?: string): void;
+}
+declare const videoConfiguration: VideoConfiguration;
+/**
+ * Sets the video analytics configuration.
+ * @param {object} info - Info configuration object
+ * @param {object} [config] - Optional configuration object
+ * @returns {boolean} True if configuration was set successfully
+ */
+export declare function setVideoConfig(info: RawVideoConfigInfo, config?: RawVideoConfigOptions, src?: string): boolean;
+export { videoConfiguration };
+export default VideoConfiguration;