@svta/cml-cmcd 2.4.0 → 2.5.0

package/dist/index.js

@@ -217,7 +217,7 @@ const CmcdEventType = {
 *
 * @internal
 */
-const CMCD_STATE_EVENT_FIELDS = new Map([
+const CMCD_STATE_EVENT_FIELDS = /* @__PURE__ */ new Map([
 	[CMCD_EVENT_PLAY_STATE, "sta"],
 	[CMCD_EVENT_PLAYBACK_RATE, "pr"],
 	[CMCD_EVENT_CONTENT_ID, "cid"],
@@ -315,23 +315,30 @@ const CMCD_REQUEST_KEYS = [
 
 //#endregion
 //#region src/isCmcdCustomKey.ts
-const CUSTOM_KEY_REGEX = /^[a-zA-Z0-9-.]+-[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.
 *
 * @returns `true` if the key is a custom key, `false` otherwise.
 *
 * @public
+*
+* @example
+* {@includeCode ../test/isCmcdCustomKey.test.ts#example}
 */
 function isCmcdCustomKey(key) {
-	return CUSTOM_KEY_REGEX.test(key);
+	const separator = key.indexOf("-", 1);
+	return separator > 0 && separator < key.length - 1 && CUSTOM_KEY_REGEX.test(key);
 }
 
 //#endregion
 //#region src/isCmcdRequestKey.ts
-const CMCD_REQUEST_KEY_SET = new Set(CMCD_REQUEST_KEYS);
+const CMCD_REQUEST_KEY_SET = /* @__PURE__ */ new Set(CMCD_REQUEST_KEYS);
 /**
 * Check if a key is a valid CMCD request key.
 *
@@ -368,7 +375,7 @@ const CMCD_RESPONSE_KEYS = [
 
 //#endregion
 //#region src/isCmcdResponseReceivedKey.ts
-const CMCD_RESPONSE_KEY_SET = new Set(CMCD_RESPONSE_KEYS);
+const CMCD_RESPONSE_KEY_SET = /* @__PURE__ */ new Set(CMCD_RESPONSE_KEYS);
 /**
 * Check if a key is a valid CMCD response key.
 *
@@ -387,7 +394,7 @@ function isCmcdResponseReceivedKey(key) {
 
 //#endregion
 //#region src/isCmcdEventKey.ts
-const CMCD_EVENT_KEY_SET = new Set(CMCD_EVENT_KEYS);
+const CMCD_EVENT_KEY_SET = /* @__PURE__ */ new Set(CMCD_EVENT_KEYS);
 /**
 * Check if a key is a valid CMCD event key.
 *
@@ -460,7 +467,7 @@ const CMCD_V1_KEYS = [
 
 //#endregion
 //#region src/isCmcdV1Key.ts
-const CMCD_V1_KEY_SET$1 = new Set(CMCD_V1_KEYS);
+const CMCD_V1_KEY_SET$1 = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
 /**
 * Filter function for CMCD v1 keys.
 *
@@ -479,7 +486,7 @@ function isCmcdV1Key(key) {
 
 //#endregion
 //#region src/isTokenField.ts
-const TOKEN_FIELDS = new Set([
+const TOKEN_FIELDS = /* @__PURE__ */ new Set([
 	"ot",
 	"sf",
 	"st",
@@ -565,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 = {};
@@ -583,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);
 	}
@@ -942,7 +954,7 @@ const CMCD_DEFAULT_TIME_INTERVAL = 30;
 *
 * @public
 */
-const CMCD_KEYS = [
+const CMCD_KEYS = /* @__PURE__ */ [
 	...CMCD_V1_KEYS,
 	...CMCD_REQUEST_KEYS,
 	...CMCD_RESPONSE_KEYS,
@@ -1469,7 +1481,8 @@ function createEncodingOptions(reportingMode, config, baseUrl) {
 		version: config.version || CMCD_V2,
 		reportingMode,
 		filter: (key) => enabledKeySet.has(key),
-		baseUrl
+		baseUrl,
+		customHeaderMap: config.customHeaderMap
 	};
 }
 /**
@@ -1504,7 +1517,7 @@ const identity = (v) => v;
 * Maps each tracked state field to its event type and equality function.
 * Order matters: `update()` fires events in this order for multi-field updates.
 */
-const STATE_FIELDS = Array.from(CMCD_STATE_EVENT_FIELDS, ([event, field]) => {
+const STATE_FIELDS = /* @__PURE__ */ Array.from(CMCD_STATE_EVENT_FIELDS, ([event, field]) => {
 	if (field === "br") return {
 		event,
 		field,
@@ -1518,7 +1531,69 @@ const STATE_FIELDS = Array.from(CMCD_STATE_EVENT_FIELDS, ([event, field]) => {
 		snapshot: identity
 	};
 });
-const STATE_FIELDS_BY_EVENT = new Map(STATE_FIELDS.map((e) => [e.event, e]));
+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);
@@ -1537,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;
 		}, [])
@@ -1546,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
@@ -1591,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;
@@ -1599,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.
@@ -1637,6 +1727,16 @@ var CmcdReporter = class {
 	* `cid` → `bg` → `br`. The order of keys in the input object does not
 	* affect the firing order.
 	*
+	* To attach snapshot context (e.g., `bl`, `mtp`, `pt`, `ltc`) to a
+	* state-change event, ensure those fields are in the reporter's data
+	* before the state field changes. Either include them alongside the
+	* state field in the same `update()` call, or persist them via earlier
+	* `update()` calls — auto-fired events emit whatever is currently in
+	* the persistent data store. This is also how to keep `TIME_INTERVAL`
+	* reports useful — those events draw from the persistent data store
+	* with no caller hook for per-event data, so fields the player wants
+	* in periodic reports must be kept fresh here.
+	*
 	* A `sid` change resets the dedup baseline.
 	*
 	* @param data - The data to update.
@@ -1666,9 +1766,19 @@ var CmcdReporter = class {
 	*
 	* For all other event types, the event is always emitted.
 	*
-	* Most callers can rely on {@link CmcdReporter.update} to auto-fire state-change events.
-	* Use `recordEvent` directly when you need to attach extra context to the
-	* event report (e.g., `bl`, `pt` at the moment of a play-state transition).
+	* For state-change events, prefer {@link CmcdReporter.update} — including
+	* for snapshot enrichment via a combined call like
+	* `update({ sta: 'p', bl: [3000], mtp: [8500] })`. Calling `recordEvent()`
+	* for a state-change event after `update()` has already auto-fired it
+	* silently drops the second call's `data`, because dedup suppresses the
+	* second emission.
+	*
+	* Use `recordEvent()` directly for events whose payload is intrinsic to
+	* the event call — `CUSTOM_EVENT` with `cen`, `ERROR` with `ec`,
+	* ad-lifecycle events, `MUTE`/`UNMUTE`, `PLAYER_EXPAND`/`PLAYER_COLLAPSE`,
+	* `SKIP`. For `RESPONSE_RECEIVED`, prefer
+	* {@link CmcdReporter.recordResponseReceived}, which derives the
+	* per-response fields automatically.
 	*
 	* @param type - The type of event to record.
 	* @param data - Additional data to record with the event. This data
@@ -1677,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;
@@ -1687,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.
@@ -1701,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
@@ -1732,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.
@@ -1755,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
@@ -1785,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
@@ -1802,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:
@@ -2119,8 +2308,8 @@ function resolveVersion(data, options) {
 
 //#endregion
 //#region src/validateCmcdKeys.ts
-const CMCD_V1_KEY_SET = new Set(CMCD_V1_KEYS);
-const CMCD_KEY_SET = new Set(CMCD_KEYS);
+const CMCD_V1_KEY_SET = /* @__PURE__ */ new Set(CMCD_V1_KEYS);
+const CMCD_KEY_SET = /* @__PURE__ */ new Set(CMCD_KEYS);
 /**
 * Validates that all keys in a CMCD payload are recognized spec keys or valid custom keys.
 *
@@ -2454,14 +2643,14 @@ const CMCD_TOKEN_VALUES = {
 
 //#endregion
 //#region src/validateCmcdValues.ts
-const HUNDRED_ROUNDING_KEYS = new Set([
+const HUNDRED_ROUNDING_KEYS = /* @__PURE__ */ new Set([
 	"bl",
 	"dl",
 	"mtp",
 	"rtp",
 	"tbl"
 ]);
-const INTEGER_ROUNDING_KEYS = new Set([
+const INTEGER_ROUNDING_KEYS = /* @__PURE__ */ new Set([
 	"br",
 	"d",
 	"tb"