@svta/cml-cmcd 2.4.1 → 2.5.0

package/dist/index.js

@@ -315,9 +315,12 @@ const CMCD_REQUEST_KEYS = [
 
 //#endregion
 //#region src/isCmcdCustomKey.ts
-const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9.-]+$/;
+const CUSTOM_KEY_REGEX = /^[a-z][a-z0-9.-]*$/;
 /**
-* Check if a key is a custom key.
+* Check if a key is a valid custom key: a lowercase first letter, then
+* characters from `a-z 0-9 . -`, with a hyphen that is neither the first
+* nor the last character. These are the CTA-5004-B custom-key rules
+* restricted to names that survive RFC 8941 key serialization.
 *
 * @param key - The key to check.
 *
@@ -569,6 +572,9 @@ function downConvertToV1(obj) {
 * @param options - Options for encoding.
 *
 * @public
+*
+* @example
+* {@includeCode ../test/prepareCmcdData.test.ts#example}
 */
 function prepareCmcdData(obj, options = {}) {
 	const results = {};
@@ -587,6 +593,8 @@ function prepareCmcdData(obj, options = {}) {
 		if (!keys.includes("e") && eventType != null) keys.push("e");
 		if (!keys.includes("ts")) keys.push("ts");
 		if (!keys.includes("cen") && data["cen"] != null && eventType === CMCD_EVENT_CUSTOM_EVENT) keys.push("cen");
+		if (!keys.includes("ec") && data["ec"] != null && eventType === CMCD_EVENT_ERROR) keys.push("ec");
+		if (!keys.includes("url") && data["url"] != null && eventType === CMCD_EVENT_RESPONSE_RECEIVED) keys.push("url");
 		const requiredField = eventType ? CMCD_STATE_EVENT_FIELDS.get(eventType) : void 0;
 		if (requiredField && data[requiredField] != null && !keys.includes(requiredField)) keys.push(requiredField);
 	}
@@ -1473,7 +1481,8 @@ function createEncodingOptions(reportingMode, config, baseUrl) {
 		version: config.version || CMCD_V2,
 		reportingMode,
 		filter: (key) => enabledKeySet.has(key),
-		baseUrl
+		baseUrl,
+		customHeaderMap: config.customHeaderMap
 	};
 }
 /**
@@ -1523,6 +1532,68 @@ const STATE_FIELDS = /* @__PURE__ */ Array.from(CMCD_STATE_EVENT_FIELDS, ([event
 	};
 });
 const STATE_FIELDS_BY_EVENT = /* @__PURE__ */ new Map(/* @__PURE__ */ STATE_FIELDS.map((e) => [e.event, e]));
+/**
+* Maps each event type to the key CTA-5004-B requires beyond `e` and `ts`.
+* Built from the state-change table plus the three event types whose
+* required key rides the caller's per-event data.
+*/
+const CMCD_REQUIRED_EVENT_KEYS = /* @__PURE__ */ new Map([
+	...CMCD_STATE_EVENT_FIELDS,
+	[CMCD_EVENT_CUSTOM_EVENT, "cen"],
+	[CMCD_EVENT_ERROR, "ec"],
+	[CMCD_EVENT_RESPONSE_RECEIVED, "url"]
+]);
+/**
+* Whether a required key's value will survive report preparation.
+*
+* This is `isValid` minus its `false` exclusion, plus an empty-array check.
+* `false` must count as usable because `bg: false` is a legitimate value on a
+* backgrounded-mode event, which the encoder emits as `?0`; treating it as
+* unusable would let restoration silently revert a transform that cleared it.
+* Empty strings, empty lists and non-finite numbers are dropped downstream, so
+* a transform substituting one leaves the report short a required key.
+*/
+function isUsableRequiredValue(value) {
+	if (value == null || value === "") return false;
+	if (typeof value === "number") return Number.isFinite(value);
+	return !Array.isArray(value) || value.length > 0;
+}
+/**
+* Copies an `SfItem`-shaped value and its `params` record.
+*
+* The prototype is preserved because `prepareCmcdData`, the formatter map,
+* validation, and the structured-field encoder all branch on
+* `instanceof SfItem`. A plain spread (and `structuredClone`) would return a
+* prototype-less object and silently change what goes on the wire.
+*/
+function copyItemValue(value) {
+	if (value === null || typeof value !== "object") return value;
+	const copy = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+	if (copy.params !== null && typeof copy.params === "object") copy.params = { ...copy.params };
+	return copy;
+}
+/**
+* Copies the nested values of a report in place so a transform cannot mutate
+* the reporter's persistent data, or another target's report for the same
+* event, by mutating an array or an `SfItem` it was handed.
+*
+* Complete for the CMCD value space rather than best-effort: `CmcdValue` and
+* `CmcdCustomValue` admit only primitives, `SfItem<primitive>`, and arrays of
+* those, and `SfItem.params` is a flat record. Only called where a transform
+* is configured.
+*/
+function copyReportValues(data) {
+	const record = data;
+	for (const key in record) {
+		const value = record[key];
+		if (Array.isArray(value)) {
+			const copy = new Array(value.length);
+			for (let i = 0; i < value.length; i++) copy[i] = copyItemValue(value[i]);
+			record[key] = copy;
+		} else if (value !== null && typeof value === "object") record[key] = copyItemValue(value);
+	}
+	return data;
+}
 function defaultRequester(request) {
 	const { url,...init } = request;
 	return fetch(url, init);
@@ -1541,7 +1612,8 @@ function createCmcdReporterConfig(config) {
 				url: target.url,
 				events: target.events.slice(),
 				interval: target.interval ?? CMCD_DEFAULT_TIME_INTERVAL,
-				batchSize: target.batchSize || 1
+				batchSize: target.batchSize || 1,
+				transform: target.transform
 			});
 			return acc;
 		}, [])
@@ -1550,6 +1622,14 @@ function createCmcdReporterConfig(config) {
 /**
 * The CMCD reporter.
 *
+* `C` describes the player's own `customData`, which the reporter passes
+* through to each configured `transform`. It is inferred from the
+* configuration, so annotating a single `transform` types the request in every
+* other one; the default leaves `customData` values `unknown`.
+*
+* @typeParam C - The shape of the player's `customData`. Defaults to
+*                `Record<string, unknown>`.
+*
 * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reporting-modes-when-we-send-data | CTA-5004-B Reporting Modes}
 *
 * @public
@@ -1595,6 +1675,7 @@ var CmcdReporter = class {
 	* populated before calling start().
 	*/
 	start() {
+		let failure;
 		this.eventTargets.forEach((target, config) => {
 			this.disarmInterval(target);
 			if (config.interval === 0 || !config.events.includes(CMCD_EVENT_TIME_INTERVAL)) return;
@@ -1603,8 +1684,13 @@ var CmcdReporter = class {
 				this.processEventTargets();
 			};
 			target.intervalId = setInterval(timeIntervalEvent, config.interval * 1e3);
-			timeIntervalEvent();
+			try {
+				timeIntervalEvent();
+			} catch (error) {
+				failure ??= { error };
+			}
 		});
+		if (failure) throw failure.error;
 	}
 	/**
 	* Stops the CMCD reporter. Called by the player when the reporter is disabled.
@@ -1701,6 +1787,20 @@ var CmcdReporter = class {
 	*               into the reporter's data store.
 	*/
 	recordEvent(type, data = {}) {
+		this.emitEvent(type, data);
+	}
+	/**
+	* Records an event across every configured target, applying
+	* state-change dedup once before per-target fan-out.
+	*
+	* @param type - The type of event to record.
+	* @param data - Additional data to record with the event.
+	* @param request - The media request that triggered the event, when
+	*                  one exists. Only `recordResponseReceived()`
+	*                  populates this; it is threaded through to each
+	*                  target's `transform`.
+	*/
+	emitEvent(type, data, request) {
 		const entry = STATE_FIELDS_BY_EVENT.get(type);
 		if (entry) {
 			const field = entry.field;
@@ -1711,10 +1811,16 @@ var CmcdReporter = class {
 			if (entry.equal(current, this.lastEmitted[field])) return;
 			Object.assign(this.lastEmitted, { [field]: entry.snapshot(current) });
 		}
+		let failure;
 		this.eventTargets.forEach((target, config) => {
-			this.recordTargetEvent(target, config, type, data);
+			try {
+				this.recordTargetEvent(target, config, type, data, request);
+			} catch (error) {
+				failure ??= { error };
+			}
 		});
 		this.processEventTargets();
+		if (failure) throw failure.error;
 	}
 	/**
 	* Records an event for a target. Called by the reporter when an event occurs.
@@ -1725,21 +1831,51 @@ var CmcdReporter = class {
 	* @param data - Additional data to record with the event. This data
 	*               only applies to this event report. Persistent data should
 	*               be updated using `update()`.
+	* @param request - The media request that triggered the event, when
+	*                  one exists. Passed to the target's `transform`.
 	*/
-	recordTargetEvent(target, config, type, data = {}) {
+	recordTargetEvent(target, config, type, data = {}, request) {
 		if (!config.events.includes(type)) return;
 		const item = {
 			...this.data,
 			...data,
 			e: type,
-			ts: data.ts ?? Date.now(),
-			sn: target.sn++
+			ts: data.ts ?? Date.now()
 		};
+		const { transform } = config;
+		if (!transform) {
+			this.queueTargetEvent(target, item, type);
+			return;
+		}
+		copyReportValues(item);
+		const requiredKey = CMCD_REQUIRED_EVENT_KEYS.get(type);
+		const requiredValue = requiredKey ? item[requiredKey] : void 0;
+		const ts = item.ts;
+		const report = transform(item, request);
+		if (report == null) return;
+		if (!isUsableRequiredValue(report.ts)) report.ts = ts;
+		if (requiredKey && isUsableRequiredValue(requiredValue) && !isUsableRequiredValue(report[requiredKey])) Object.assign(report, { [requiredKey]: requiredValue });
+		this.queueTargetEvent(target, report, type);
+	}
+	/**
+	* Stamps the reporter-owned fields on a finished event report and pushes it
+	* to the target's queue.
+	*
+	* Called after any transform has run, so a transform cannot bypass the
+	* target's `events` filter via `e` or break `sn` continuity.
+	*
+	* @param target - The target to queue the report for.
+	* @param report - The finished report data.
+	* @param type - The type of event being reported.
+	*/
+	queueTargetEvent(target, report, type) {
+		report.e = type;
+		report.sn = target.sn++;
 		if (!isNaN(this.msd) && !target.msdSent) {
-			item.msd = this.msd;
+			report.msd = this.msd;
 			target.msdSent = true;
 		}
-		target.queue.push(item);
+		target.queue.push(report);
 	}
 	/**
 	* Records a response-received event. Called by the player when a media
@@ -1756,6 +1892,20 @@ var CmcdReporter = class {
 	* Additional keys like `ttfbb`, `cmsdd`, `cmsds`, and `smrt` can be
 	* supplied via the `data` parameter if the player has access to them.
 	*
+	* The request's `customData` is generic, so a player can pass a request
+	* carrying its own taxonomy (e.g. `{ requestType: 'segment' }`) without a
+	* cast. The reporter only reads the optional `cmcd` key that
+	* {@link CmcdReporter.createRequestReport} writes there; every other key is
+	* left untouched and stays visible to an event target's `transform` via
+	* its `request` argument.
+	*
+	* A reporter given a concrete `C` requires the request to satisfy it, so a
+	* request the configured transforms could not read is rejected here rather
+	* than reaching them; see {@link CmcdReporterCustomData}.
+	*
+	* @typeParam RD - The `customData` this request carries. Defaults to the
+	*                reporter's own `C`.
+	*
 	* @param response - The HTTP response received.
 	* @param data - Additional CMCD data to include with the event.
 	*               Values provided here override any auto-derived values.
@@ -1779,11 +1929,11 @@ var CmcdReporter = class {
 			if (timing.duration != null) derived.ttlb = Math.round(timing.duration);
 		}
 		const cmcd = request.customData?.cmcd ?? {};
-		this.recordEvent(CMCD_EVENT_RESPONSE_RECEIVED, {
+		this.emitEvent(CMCD_EVENT_RESPONSE_RECEIVED, {
 			...cmcd,
 			...derived,
 			...data
-		});
+		}, request);
 	}
 	/**
 	* Applies the CMCD request report data to the request. Called by the player
@@ -1809,6 +1959,14 @@ var CmcdReporter = class {
 	* Creates a new request with the CMCD request report data applied. Called by the player
 	* before sending the request.
 	*
+	* A reporter given a concrete `C` requires the request's `customData` to
+	* satisfy it, so a request the configured transform could not read is
+	* rejected here rather than reaching it; see
+	* {@link CmcdReporterCustomData}.
+	*
+	* @typeParam R - The request being decorated. Its `customData` must satisfy
+	*                the reporter's `C`.
+	*
 	* @param request - The request to apply the CMCD request report to.
 	* @param data - The data to apply to the request. This data only
 	*               applies to this request report. Persistent data
@@ -1826,17 +1984,24 @@ var CmcdReporter = class {
 			}
 		};
 		if (!this.config.enabledKeys?.length || !report.url) return report;
-		const url = new URL(report.url);
-		const cmcdData = {
+		const merged = {
 			...this.data,
-			...data,
-			sn: this.requestTarget.sn++
+			...data
 		};
-		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
+		const { transform } = this.config;
+		let cmcdData = merged;
+		if (transform) {
+			copyReportValues(merged);
+			cmcdData = transform(merged, request);
+			if (cmcdData == null) return report;
+		}
+		cmcdData.sn = this.requestTarget.sn++;
 		if (!isNaN(this.msd) && !this.requestTarget.msdSent) {
 			cmcdData.msd = this.msd;
 			this.requestTarget.msdSent = true;
 		}
+		const url = new URL(report.url);
+		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
 		const cmcd = report.customData.cmcd = prepareCmcdData(cmcdData, options);
 		switch (this.config.transmissionMode) {
 			case CMCD_QUERY: