@svta/cml-cmcd 2.1.2 → 2.3.0

package/dist/index.js

@@ -62,11 +62,11 @@ const CMCD_V2 = 2;
 //#endregion
 //#region src/CmcdEventType.ts
 /**
-* CMCD event type for the 'br' key (bitrate change).
+* CMCD event type for the 'bc' key (bitrate change).
 *
 * @public
 */
-const CMCD_EVENT_BITRATE_CHANGE = "br";
+const CMCD_EVENT_BITRATE_CHANGE = "bc";
 /**
 * CMCD event type for the 'ps' key (play state change).
 *
@@ -166,9 +166,10 @@ const CMCD_EVENT_CUSTOM_EVENT = "ce";
 /**
 * CMCD event types for the 'e' key (event mode).
 *
-*
 * @enum
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event | CTA-5004-A Event}
+*
 * @public
 */
 const CmcdEventType = {
@@ -297,6 +298,7 @@ function isCmcdCustomKey(key) {
 
 //#endregion
 //#region src/isCmcdRequestKey.ts
+const CMCD_REQUEST_KEY_SET = new Set(CMCD_REQUEST_KEYS);
 /**
 * Check if a key is a valid CMCD request key.
 *
@@ -310,7 +312,7 @@ function isCmcdCustomKey(key) {
 * {@includeCode ../test/isCmcdRequestKey.test.ts#example}
 */
 function isCmcdRequestKey(key) {
-	return CMCD_REQUEST_KEYS.includes(key) || isCmcdCustomKey(key);
+	return CMCD_REQUEST_KEY_SET.has(key) || isCmcdCustomKey(key);
 }
 
 //#endregion
@@ -333,6 +335,7 @@ const CMCD_RESPONSE_KEYS = [
 
 //#endregion
 //#region src/isCmcdResponseReceivedKey.ts
+const CMCD_RESPONSE_KEY_SET = new Set(CMCD_RESPONSE_KEYS);
 /**
 * Check if a key is a valid CMCD response key.
 *
@@ -346,11 +349,12 @@ const CMCD_RESPONSE_KEYS = [
 * {@includeCode ../test/isCmcdResponseReceivedKey.test.ts#example}
 */
 function isCmcdResponseReceivedKey(key) {
-	return CMCD_RESPONSE_KEYS.includes(key);
+	return CMCD_RESPONSE_KEY_SET.has(key);
 }
 
 //#endregion
 //#region src/isCmcdEventKey.ts
+const CMCD_EVENT_KEY_SET = new Set(CMCD_EVENT_KEYS);
 /**
 * Check if a key is a valid CMCD event key.
 *
@@ -364,9 +368,35 @@ function isCmcdResponseReceivedKey(key) {
 * {@includeCode ../test/isCmcdEventKey.test.ts#example}
 */
 function isCmcdEventKey(key) {
-	return isCmcdRequestKey(key) || isCmcdResponseReceivedKey(key) || CMCD_EVENT_KEYS.includes(key);
+	return isCmcdRequestKey(key) || isCmcdResponseReceivedKey(key) || CMCD_EVENT_KEY_SET.has(key);
 }
 
+//#endregion
+//#region src/CMCD_INNER_LIST_KEYS.ts
+/**
+* Keys that are inner lists in V2 but plain scalars in V1.
+*
+* Used by both encoding (down-conversion) and decoding (up-conversion).
+*
+* @internal
+*/
+const CMCD_INNER_LIST_KEYS = new Set([
+	"ab",
+	"bl",
+	"br",
+	"bsa",
+	"bsd",
+	"bsda",
+	"lab",
+	"lb",
+	"mtp",
+	"pb",
+	"tab",
+	"tb",
+	"tbl",
+	"tpb"
+]);
+
 //#endregion
 //#region src/CMCD_V1_KEYS.ts
 /**
@@ -397,6 +427,7 @@ const CMCD_V1_KEYS = [
 
 //#endregion
 //#region src/isCmcdV1Key.ts
+const CMCD_V1_KEY_SET$1 = new Set(CMCD_V1_KEYS);
 /**
 * Filter function for CMCD v1 keys.
 *
@@ -410,11 +441,18 @@ const CMCD_V1_KEYS = [
 * {@includeCode ../test/isCmcdV1Key.test.ts#example}
 */
 function isCmcdV1Key(key) {
-	return CMCD_V1_KEYS.includes(key) || isCmcdCustomKey(key);
+	return CMCD_V1_KEY_SET$1.has(key) || isCmcdCustomKey(key);
 }
 
 //#endregion
 //#region src/isTokenField.ts
+const TOKEN_FIELDS = new Set([
+	"ot",
+	"sf",
+	"st",
+	"e",
+	"sta"
+]);
 /**
 * Checks if the given key is a token field.
 *
@@ -425,13 +463,7 @@ function isCmcdV1Key(key) {
 * @internal
 */
 function isTokenField(key) {
-	return [
-		"ot",
-		"sf",
-		"st",
-		"e",
-		"sta"
-	].includes(key);
+	return TOKEN_FIELDS.has(key);
 }
 
 //#endregion
@@ -457,25 +489,6 @@ const filterMap = {
 	[CMCD_REQUEST_MODE]: isCmcdRequestKey
 };
 /**
-* V1 keys that use inner lists in V2 but plain numbers in V1.
-*/
-const INNER_LIST_V1_KEYS = new Set([
-	"ab",
-	"bl",
-	"br",
-	"bsa",
-	"bsd",
-	"bsda",
-	"lab",
-	"lb",
-	"mtp",
-	"pb",
-	"tab",
-	"tb",
-	"tbl",
-	"tpb"
-]);
-/**
 * Unwrap an inner list or SfItem value to a plain scalar.
 */
 function unwrapValue(value, ot) {
@@ -507,7 +520,7 @@ function downConvertToV1(obj) {
 				result["nor"] = first.value;
 				if (first.params?.r) result["nrr"] = first.params.r;
 			} else result["nor"] = first;
-		} else if (INNER_LIST_V1_KEYS.has(key)) result[key] = unwrapValue(value, obj["ot"]);
+		} else if (CMCD_INNER_LIST_KEYS.has(key)) result[key] = unwrapValue(value, obj["ot"]);
 		else result[key] = value;
 	}
 	return result;
@@ -527,37 +540,37 @@ function prepareCmcdData(obj, options = {}) {
 	const reportingMode = options.reportingMode || CMCD_REQUEST_MODE;
 	const data = version === 1 ? downConvertToV1(obj) : obj;
 	const keyFilter = version === 1 ? isCmcdV1Key : filterMap[reportingMode];
-	let keys$1 = Object.keys(data).filter(keyFilter);
-	if (data["e"] && data["e"] !== CMCD_EVENT_RESPONSE_RECEIVED) keys$1 = keys$1.filter((key) => !isCmcdResponseReceivedKey(key));
+	let keys = Object.keys(data).filter(keyFilter);
+	if (data["e"] && data["e"] !== CMCD_EVENT_RESPONSE_RECEIVED) keys = keys.filter((key) => !isCmcdResponseReceivedKey(key));
 	const filter = options.filter;
-	if (typeof filter === "function") keys$1 = keys$1.filter(filter);
+	if (typeof filter === "function") keys = keys.filter(filter);
 	const isEventMode = reportingMode === CMCD_EVENT_MODE;
 	if (isEventMode) {
 		const eventType = data["e"];
-		if (!keys$1.includes("e") && eventType != null) keys$1.push("e");
-		if (!keys$1.includes("ts")) keys$1.push("ts");
-		if (!keys$1.includes("cen") && data["cen"] != null && eventType === CMCD_EVENT_CUSTOM_EVENT) keys$1.push("cen");
+		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$1.length === 0) return results;
-	if (version > 1 && !keys$1.includes("v")) keys$1.push("v");
-	const formatters = Object.assign({}, CMCD_FORMATTER_MAP, options.formatters);
+	if (keys.length === 0) return results;
+	if (version > 1 && !keys.includes("v")) keys.push("v");
 	const formatterOptions = {
 		version,
 		reportingMode,
 		baseUrl: options.baseUrl
 	};
-	keys$1.sort().forEach((key) => {
+	keys.sort();
+	for (const key of keys) {
 		let value = data[key];
-		const formatter = formatters[key];
+		const formatter = options.formatters?.[key] ?? CMCD_FORMATTER_MAP[key];
 		if (typeof formatter === "function") value = formatter(value, formatterOptions);
-		if (key === "v") if (version === 1) return;
+		if (key === "v") if (version === 1) continue;
 		else value = version;
-		if (key == "pr" && value === 1) return;
+		if (key === "pr" && value === 1) continue;
 		if (isEventMode && key === "ts" && !Number.isFinite(value)) value = Date.now();
-		if (!isValid(value)) return;
+		if (!isValid(value)) continue;
 		if (isTokenField(key) && typeof value === "string") value = new SfToken(value);
 		results[key] = value;
-	});
+	}
 	return results;
 }
 
@@ -601,12 +614,27 @@ const CmcdHeaderField = {
 	SESSION: CMCD_SESSION,
 	STATUS: CMCD_STATUS
 };
+/**
+* All CMCD header fields as an array.
+*
+* @public
+*/
+const CMCD_HEADER_FIELDS = [
+	CMCD_OBJECT,
+	CMCD_REQUEST,
+	CMCD_SESSION,
+	CMCD_STATUS
+];
 
 //#endregion
 //#region src/CMCD_HEADER_MAP.ts
 /**
 * The map of CMCD keys to their appropriate header shard.
 *
+* Note: Event-only keys (e, ts, cen, h) and response-received keys
+* (rc, ttfb, ttlb, url, etc.) are intentionally absent. They are
+* transmitted via the event-mode POST body, not HTTP headers.
+*
 * @public
 */
 const CMCD_HEADER_MAP = {
@@ -667,19 +695,21 @@ function createHeaderMap(headerMap) {
 *
 * @returns The CMCD header shards.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#header-field-definition | CTA-5004-A Header Field Definition}
+*
 * @public
 */
 function groupCmcdHeaders(cmcd, customHeaderMap) {
 	const result = {};
 	if (!cmcd) return result;
-	const keys$1 = Object.keys(cmcd);
+	const keys = Object.keys(cmcd);
 	const custom = customHeaderMap ? createHeaderMap(customHeaderMap) : {};
-	return keys$1.reduce((acc, key) => {
+	for (const key of keys) {
 		const field = CMCD_HEADER_MAP[key] || custom[key] || CmcdHeaderField.REQUEST;
-		const data = acc[field] ??= {};
+		const data = result[field] ??= {};
 		data[key] = cmcd[key];
-		return acc;
-	}, result);
+	}
+	return result;
 }
 
 //#endregion
@@ -696,11 +726,11 @@ function groupCmcdHeaders(cmcd, customHeaderMap) {
 function toPreparedCmcdHeaders(data, customHeaderMap) {
 	const result = {};
 	const shards = groupCmcdHeaders(data, customHeaderMap);
-	return Object.entries(shards).reduce((acc, [field, value]) => {
+	for (const [field, value] of Object.entries(shards)) {
 		const shard = encodeSfDict(value, { whitespace: false });
-		if (shard) acc[field] = shard;
-		return acc;
-	}, result);
+		if (shard) result[field] = shard;
+	}
+	return result;
 }
 
 //#endregion
@@ -713,6 +743,8 @@ function toPreparedCmcdHeaders(data, customHeaderMap) {
 *
 * @returns The CMCD header shards.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#header-field-definition | CTA-5004-A Header Field Definition}
+*
 * @public
 *
 * @example
@@ -738,6 +770,8 @@ function toCmcdHeaders(cmcd, options = {}) {
 *
 * @example
 * {@includeCode ../test/appendCmcdHeaders.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#header-field-definition | CTA-5004-A Header Field Definition}
 */
 function appendCmcdHeaders(headers, cmcd, options) {
 	return Object.assign(headers, toCmcdHeaders(cmcd, options));
@@ -776,6 +810,8 @@ function encodePreparedCmcd(data) {
 *
 * @returns The encoded CMCD string.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#payload-definition-for-headers-and-query-argument-transmission | CTA-5004-A Payload Definition}
+*
 * @public
 *
 * @example
@@ -796,6 +832,8 @@ function encodeCmcd(cmcd, options = {}) {
 *
 * @returns The URL encoded CMCD data.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#query-argument-definition | CTA-5004-A Query Argument Definition}
+*
 * @public
 */
 function toCmcdUrl(cmcd, options = {}) {
@@ -814,6 +852,8 @@ function toCmcdUrl(cmcd, options = {}) {
 *
 * @returns The CMCD query arg.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#query-argument-definition | CTA-5004-A Query Argument Definition}
+*
 * @public
 *
 * @example
@@ -840,6 +880,8 @@ const REGEX = /CMCD=[^&#]+/;
 *
 * @example
 * {@includeCode ../test/appendCmcdQuery.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#query-argument-definition | CTA-5004-A Query Argument Definition}
 */
 function appendCmcdQuery(url, cmcd, options) {
 	const query = toCmcdQuery(cmcd, options);
@@ -859,18 +901,26 @@ const CMCD_DEFAULT_TIME_INTERVAL = 30;
 
 //#endregion
 //#region src/CMCD_KEYS.ts
-const keySet = new Set([
+/**
+* A list of all CMCD keys.
+*
+* @public
+*/
+const CMCD_KEYS = [
 	...CMCD_V1_KEYS,
 	...CMCD_REQUEST_KEYS,
 	...CMCD_RESPONSE_KEYS,
 	...CMCD_EVENT_KEYS
-]);
+].filter((key, index, arr) => arr.indexOf(key) === index);
+
+//#endregion
+//#region src/CMCD_MIME_TYPE.ts
 /**
-* A list of all CMCD keys.
+* CMCD MIME type for event report payloads.
 *
 * @public
 */
-const CMCD_KEYS = Array.from(keySet);
+const CMCD_MIME_TYPE = "application/cmcd";
 
 //#endregion
 //#region src/CMCD_V1.ts
@@ -889,6 +939,8 @@ const CMCD_V1 = 1;
 * @public
 *
 * @enum
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#object-type | CTA-5004-A Object Type}
 */
 const CmcdObjectType = {
 	MANIFEST: "m",
@@ -911,6 +963,8 @@ const CmcdObjectType = {
 * @enum
 *
 * @public
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#state | CTA-5004-A State}
 */
 const CmcdPlayerState = {
 	STARTING: "s",
@@ -963,11 +1017,11 @@ const CmcdTransmissionMode = {
 //#endregion
 //#region src/CmcdReporter.ts
 function createEncodingOptions(reportingMode, config, baseUrl) {
-	const { enabledKeys = [] } = config;
+	const enabledKeySet = new Set(config.enabledKeys ?? []);
 	return {
 		version: config.version || CMCD_V2,
 		reportingMode,
-		filter: (key) => enabledKeys.includes(key),
+		filter: (key) => enabledKeySet.has(key),
 		baseUrl
 	};
 }
@@ -998,6 +1052,8 @@ function createCmcdReporterConfig(config) {
 /**
 * The CMCD reporter.
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reporting-modes-when-we-send-data | CTA-5004-A Reporting Modes}
+*
 * @public
 */
 var CmcdReporter = class {
@@ -1034,6 +1090,10 @@ var CmcdReporter = class {
 	}
 	/**
 	* Starts the CMCD reporter. Called by the player when the reporter is enabled.
+	*
+	* Note: This fires an initial time-interval event immediately (synchronously)
+	* before the first interval elapses. Ensure CMCD data (sid, cid, etc.) is
+	* populated before calling start().
 	*/
 	start() {
 		this.eventTargets.forEach((target, config) => {
@@ -1071,10 +1131,7 @@ var CmcdReporter = class {
 	* @param data - The data to update.
 	*/
 	update(data) {
-		if (data.sid && data.sid !== this.data.sid) {
-			this.resetSession();
-			return;
-		}
+		if (data.sid && data.sid !== this.data.sid) this.resetSession();
 		if (data.msd && !isNaN(data.msd)) this.msd = data.msd;
 		this.data = {
 			...this.data,
@@ -1189,7 +1246,7 @@ var CmcdReporter = class {
 	* Creates a new request with the CMCD request report data applied. Called by the player
 	* before sending the request.
 	*
-	* @param req - The request to apply the CMCD request report to.
+	* @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
 	*               should be updated using `update()`.
@@ -1245,7 +1302,9 @@ var CmcdReporter = class {
 			if (queue.length < config.batchSize && !flush) return;
 			const deleteCount = flush ? queue.length : config.batchSize;
 			const events = queue.splice(0, deleteCount);
-			this.sendEventReport(config, events);
+			this.sendEventReport(config, events).catch(() => {
+				target.queue.unshift(...events);
+			});
 			reprocess ||= queue.length > 0;
 		});
 		if (reprocess) this.processEventTargets();
@@ -1261,18 +1320,11 @@ var CmcdReporter = class {
 		const { status } = await this.requester({
 			url: target.url,
 			method: "POST",
-			headers: { "Content-Type": "text/cmcd" },
-			body: data.reduce((acc, item) => acc += `${encodeCmcd(item, options)}\n`, "")
+			headers: { "Content-Type": CMCD_MIME_TYPE },
+			body: data.map((item) => encodeCmcd(item, options)).join("\n") + "\n"
 		});
-		switch (status) {
-			case 410:
-				this.eventTargets.delete(target);
-				break;
-			case 429: break;
-			default:
-				if (status > 499 && status < 600) {}
-				break;
-		}
+		if (status === 410) this.eventTargets.delete(target);
+		else if (status === 429 || status > 499 && status < 600) throw new Error(`Event report failed with status ${status}`);
 	}
 	/**
 	* Resets the session related data. Called when the session ID changes.
@@ -1288,9 +1340,10 @@ var CmcdReporter = class {
 /**
 * Common Media Client Data Streaming Format
 *
-*
 * @enum
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#streaming-format | CTA-5004-A Streaming Format}
+*
 * @public
 */
 const CmcdStreamingFormat = {
@@ -1307,6 +1360,8 @@ const CmcdStreamingFormat = {
 *
 * @enum
 *
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#stream-type | CTA-5004-A Stream Type}
+*
 * @public
 */
 const CmcdStreamType = {
@@ -1315,116 +1370,993 @@ const CmcdStreamType = {
 	LOW_LATENCY: "ll"
 };
 
+//#endregion
+//#region src/CmcdValidationSeverity.ts
+/**
+* CMCD validation severity level: error.
+*
+* @public
+*/
+const CMCD_VALIDATION_SEVERITY_ERROR = "error";
+/**
+* CMCD validation severity level: warning.
+*
+* @public
+*/
+const CMCD_VALIDATION_SEVERITY_WARNING = "warning";
+/**
+* CMCD validation severity level.
+*
+* @public
+*/
+const CmcdValidationSeverity = {
+	ERROR: CMCD_VALIDATION_SEVERITY_ERROR,
+	WARNING: CMCD_VALIDATION_SEVERITY_WARNING
+};
+
+//#endregion
+//#region src/upConvertToV2.ts
+/**
+* Up-convert V1 CMCD data to V2 format.
+*
+* - Wraps plain scalar values in arrays for inner-list keys.
+* - Wraps `nor` string in an array.
+*
+* If the data is already V2 (has `v: 2`), it is returned unchanged.
+*
+* @internal
+*/
+function upConvertToV2(obj) {
+	if (obj["v"] === CMCD_V2) return obj;
+	const result = {};
+	for (const [key, value] of Object.entries(obj)) {
+		if (value == null) {
+			result[key] = value;
+			continue;
+		}
+		if (CMCD_INNER_LIST_KEYS.has(key) && !Array.isArray(value)) result[key] = [value];
+		else if (key === "nor" && typeof value === "string") result[key] = [value];
+		else result[key] = value;
+	}
+	return result;
+}
+
 //#endregion
 //#region src/decodeCmcd.ts
 function reduceValue(value) {
 	if (Array.isArray(value)) return value.map(reduceValue);
 	if (typeof value === "symbol") return symbolToStr(value);
 	if (value instanceof SfItem && !value.params) return reduceValue(value.value);
-	if (typeof value === "string") return decodeURIComponent(value);
+	if (typeof value === "string") return value;
 	return value;
 }
+function decodeCmcd(cmcd, options) {
+	if (!cmcd) return {};
+	const sfDict = decodeSfDict(cmcd);
+	const result = {};
+	for (const [key, item] of Object.entries(sfDict)) result[key] = reduceValue(item.value);
+	if (options?.convertToLatest) return upConvertToV2(result);
+	return result;
+}
+
+//#endregion
+//#region src/ensureHeaders.ts
+/**
+* Converts a record of header fields to a `Headers` instance if necessary.
+*
+* @param headers - A `Headers` instance or a plain record of header fields.
+* @returns A `Headers` instance.
+*
+* @internal
+*/
+function ensureHeaders(headers) {
+	return headers instanceof Headers ? headers : new Headers(headers);
+}
+
+//#endregion
+//#region src/fromCmcdHeaders.ts
+function fromCmcdHeaders(headers, options) {
+	const h = ensureHeaders(headers);
+	const result = {};
+	for (const field of CMCD_HEADER_FIELDS) {
+		const value = h.get(field);
+		if (value) Object.assign(result, decodeCmcd(value));
+	}
+	if (options?.convertToLatest) return upConvertToV2(result);
+	return result;
+}
+
+//#endregion
+//#region src/fromCmcdQuery.ts
+function fromCmcdQuery(query, options) {
+	if (typeof query === "string") query = new URLSearchParams(query);
+	return decodeCmcd(query.get(CMCD_PARAM) ?? "", options);
+}
+
+//#endregion
+//#region src/fromCmcdUrl.ts
+function fromCmcdUrl(url, options) {
+	return decodeCmcd(decodeURIComponent(url.replace(/^CMCD=/, "")), options);
+}
+
+//#endregion
+//#region src/isCmcdV1Data.ts
 /**
-* Decode a CMCD string to an object.
+* Check if a CMCD data object is version 1.
 *
-* @param cmcd - The CMCD string to decode.
+* @param data - The CMCD data object to check.
 *
-* @returns The decoded CMCD object.
+* @returns `true` if the data is version 1, `false` otherwise.
 *
 * @public
 *
 * @example
-* {@includeCode ../test/decodeCmcd.test.ts#example}
+* {@includeCode ../test/isCmcdV1Data.test.ts#example}
 */
-function decodeCmcd(cmcd) {
-	if (!cmcd) return {};
-	const sfDict = decodeSfDict(cmcd);
-	return Object.entries(sfDict).reduce((acc, [key, item]) => {
-		acc[key] = reduceValue(item.value);
-		return acc;
-	}, {});
+function isCmcdV1Data(data) {
+	return data.v !== CMCD_V2;
 }
 
 //#endregion
-//#region src/fromCmcdHeaders.ts
-const keys = [
-	CMCD_OBJECT,
-	CMCD_REQUEST,
-	CMCD_SESSION,
-	CMCD_STATUS
-];
+//#region src/isCmcdV2Data.ts
 /**
-* Decode CMCD data from request headers.
+* Check if a CMCD data object is version 2.
 *
-* @param headers - The request headers to decode.
+* @param data - The CMCD data object to check.
 *
-* @returns The decoded CMCD data.
+* @returns `true` if the data is version 2, `false` otherwise.
 *
 * @public
 *
 * @example
-* {@includeCode ../test/fromCmcdHeaders.test.ts#example}
+* {@includeCode ../test/isCmcdV2Data.test.ts#example}
 */
-function fromCmcdHeaders(headers) {
-	if (!(headers instanceof Headers)) headers = new Headers(headers);
-	return keys.reduce((acc, key) => {
-		const value = headers.get(key);
-		return Object.assign(acc, decodeCmcd(value));
-	}, {});
+function isCmcdV2Data(data) {
+	return data.v === CMCD_V2;
 }
 
 //#endregion
-//#region src/fromCmcdQuery.ts
+//#region src/toCmcdValue.ts
 /**
-* Decode CMCD data from a query string.
+* Convert a value to a CMCD value.
 *
-* @param query - The query string to decode.
+* @param value - The value to convert to a CMCD value.
+* @param params - The parameters to convert to a CMCD value.
+* @returns The CMCD value.
 *
-* @returns The decoded CMCD data.
+* @public
+*/
+function toCmcdValue(value, params) {
+	return new SfItem(value, params);
+}
+
+//#endregion
+//#region src/mergeValidationResults.ts
+/**
+* Merges multiple validation results into a single result.
+*
+* @internal
+*/
+function mergeValidationResults(...results) {
+	const issues = results.flatMap((r) => r.issues);
+	return {
+		valid: issues.every((i) => i.severity !== CMCD_VALIDATION_SEVERITY_ERROR),
+		issues
+	};
+}
+
+//#endregion
+//#region src/resolveVersion.ts
+/**
+* Resolves the CMCD version from explicit options, the payload's `v` key, or the default (v1).
+*
+* @internal
+*/
+function resolveVersion(data, options) {
+	if (options?.version === 1 || options?.version === 2) return options.version;
+	const payloadVersion = data["v"];
+	if (payloadVersion === 1 || payloadVersion === 2) return payloadVersion;
+	return CMCD_V1;
+}
+
+//#endregion
+//#region src/validateCmcdKeys.ts
+const CMCD_V1_KEY_SET = new Set(CMCD_V1_KEYS);
+const CMCD_KEY_SET = new Set(CMCD_KEYS);
+/**
+* Validates that all keys in a CMCD payload are recognized spec keys or valid custom keys.
+*
+* @example
+* {@includeCode ../test/validateCmcdKeys.test.ts#example}
+*
+* @param data - The CMCD payload to validate.
+* @param options - Validation options.
+* @returns The validation result.
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reserved-keys | CTA-5004-A Reserved Keys}
 *
 * @public
+*/
+function validateCmcdKeys(data, options) {
+	const version = resolveVersion(data, options);
+	const validKeySet = version === CMCD_V1 ? CMCD_V1_KEY_SET : CMCD_KEY_SET;
+	const issues = [];
+	for (const key of Object.keys(data)) {
+		if (isCmcdCustomKey(key)) continue;
+		if (!validKeySet.has(key)) issues.push({
+			key,
+			message: `Unknown CMCD key "${key}" for version ${version}.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+
+//#endregion
+//#region src/validateCmcdStructure.ts
+/**
+* Validates the structural rules of a CMCD payload.
 *
 * @example
-* {@includeCode ../test/fromCmcdQuery.test.ts#example}
+* {@includeCode ../test/validateCmcdStructure.test.ts#example}
+*
+* @param data - The CMCD payload to validate.
+* @param options - Validation options.
+* @returns The validation result.
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#data-payload-definition-what-data-to-send | CTA-5004-A Data Payload Definition}
+*
+* @public
 */
-function fromCmcdQuery(query) {
-	if (typeof query === "string") query = new URLSearchParams(query);
-	return decodeCmcd(query.get(CMCD_PARAM));
+function validateCmcdStructure(data, options) {
+	const version = resolveVersion(data, options);
+	const issues = [];
+	if (options?.reportingMode === CMCD_REQUEST_MODE) {
+		for (const key of CMCD_EVENT_KEYS) if (key in data) issues.push({
+			key,
+			message: `Event key "${key}" must not be present in request mode.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		for (const key of CMCD_RESPONSE_KEYS) if (key in data) issues.push({
+			key,
+			message: `Response key "${key}" must not be present in request mode.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	if (options?.reportingMode === CMCD_EVENT_MODE) {
+		if (!("e" in data)) issues.push({
+			key: "e",
+			message: "Event mode requires the \"e\" key to be present.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		if (!("ts" in data)) issues.push({
+			key: "ts",
+			message: "Event mode requires the \"ts\" key to be present.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	if ("e" in data) {
+		if (data["e"] === CMCD_EVENT_CUSTOM_EVENT) {
+			if (!("cen" in data)) issues.push({
+				key: "cen",
+				message: "Custom event (e=\"ce\") requires the \"cen\" key to be present.",
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+		} else if ("cen" in data) issues.push({
+			key: "cen",
+			message: "The \"cen\" key must only be present when e=\"ce\".",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		if (data["e"] === CMCD_EVENT_RESPONSE_RECEIVED) {
+			if (!("url" in data)) issues.push({
+				key: "url",
+				message: "Response received event (e=\"rr\") requires the \"url\" key to be present.",
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+		} else for (const key of CMCD_RESPONSE_KEYS) if (key in data) issues.push({
+			key,
+			message: `Response key "${key}" must only be present when e="rr".`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		if (data["e"] === CMCD_EVENT_PLAY_STATE && !("sta" in data)) issues.push({
+			key: "sta",
+			message: "Play state event (e=\"ps\") requires the \"sta\" key to be present.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		if (data["e"] === CMCD_EVENT_ERROR && !("ec" in data)) issues.push({
+			key: "ec",
+			message: "Error event (e=\"e\") requires the \"ec\" key to be present.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	if ("v" in data && data["v"] !== 1 && data["v"] !== 2) issues.push({
+		key: "v",
+		message: `Unsupported CMCD version "${String(data["v"])}". Expected 1 or 2.`,
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
+	else if (version > 1 && !("v" in data)) issues.push({
+		key: "v",
+		message: "Version 2 payloads require the \"v\" key to be present.",
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
+	else if (version === CMCD_V1 && "v" in data) issues.push({
+		key: "v",
+		message: "Version 1 payloads should omit the \"v\" key (v1 is the default).",
+		severity: CMCD_VALIDATION_SEVERITY_WARNING
+	});
+	return {
+		valid: issues.every((i) => i.severity !== CMCD_VALIDATION_SEVERITY_ERROR),
+		issues
+	};
 }
 
 //#endregion
-//#region src/fromCmcdUrl.ts
+//#region src/CMCD_KEY_TYPES.ts
+/**
+* CMCD key value type: inner list of numbers with token identifiers.
+*
+* @internal
+*/
+const CMCD_KEY_TYPE_NUMBER_LIST = "number[]";
+/**
+* CMCD key value type: inner list of strings.
+*
+* @internal
+*/
+const CMCD_KEY_TYPE_STRING_LIST = "string[]";
+/**
+* CMCD key value type: integer.
+*
+* @internal
+*/
+const CMCD_KEY_TYPE_INTEGER = "integer";
 /**
-* Decode CMCD data from a url encoded string.
+* CMCD key value type: number (decimal).
 *
-* @param url - The url encoded string to decode.
+* @internal
+*/
+const CMCD_KEY_TYPE_NUMBER = "number";
+/**
+* CMCD key value type: boolean.
 *
-* @returns The decoded CMCD data.
+* @internal
+*/
+const CMCD_KEY_TYPE_BOOLEAN = "boolean";
+/**
+* CMCD key value type: string.
+*
+* @internal
+*/
+const CMCD_KEY_TYPE_STRING = "string";
+/**
+* CMCD key value type: token.
+*
+* @internal
+*/
+const CMCD_KEY_TYPE_TOKEN = "token";
+/**
+* Maps each CMCD spec key to its expected value type for v2.
+* Keys that differ between v1 and v2 are handled by CMCD_V1_KEY_TYPE_OVERRIDES.
+*
+* @internal
+*/
+const CMCD_KEY_TYPES = {
+	ab: CMCD_KEY_TYPE_NUMBER_LIST,
+	bl: CMCD_KEY_TYPE_NUMBER_LIST,
+	br: CMCD_KEY_TYPE_NUMBER_LIST,
+	bsa: CMCD_KEY_TYPE_NUMBER_LIST,
+	bsd: CMCD_KEY_TYPE_NUMBER_LIST,
+	bsda: CMCD_KEY_TYPE_NUMBER_LIST,
+	lab: CMCD_KEY_TYPE_NUMBER_LIST,
+	lb: CMCD_KEY_TYPE_NUMBER_LIST,
+	mtp: CMCD_KEY_TYPE_NUMBER_LIST,
+	pb: CMCD_KEY_TYPE_NUMBER_LIST,
+	tab: CMCD_KEY_TYPE_NUMBER_LIST,
+	tb: CMCD_KEY_TYPE_NUMBER_LIST,
+	tbl: CMCD_KEY_TYPE_NUMBER_LIST,
+	tpb: CMCD_KEY_TYPE_NUMBER_LIST,
+	ec: CMCD_KEY_TYPE_STRING_LIST,
+	nor: CMCD_KEY_TYPE_STRING_LIST,
+	d: CMCD_KEY_TYPE_INTEGER,
+	dfa: CMCD_KEY_TYPE_INTEGER,
+	dl: CMCD_KEY_TYPE_INTEGER,
+	ltc: CMCD_KEY_TYPE_INTEGER,
+	msd: CMCD_KEY_TYPE_INTEGER,
+	pt: CMCD_KEY_TYPE_INTEGER,
+	rc: CMCD_KEY_TYPE_INTEGER,
+	rtp: CMCD_KEY_TYPE_INTEGER,
+	sn: CMCD_KEY_TYPE_INTEGER,
+	ts: CMCD_KEY_TYPE_INTEGER,
+	ttfb: CMCD_KEY_TYPE_INTEGER,
+	ttfbb: CMCD_KEY_TYPE_INTEGER,
+	ttlb: CMCD_KEY_TYPE_INTEGER,
+	v: CMCD_KEY_TYPE_INTEGER,
+	pr: CMCD_KEY_TYPE_NUMBER,
+	bg: CMCD_KEY_TYPE_BOOLEAN,
+	bs: CMCD_KEY_TYPE_BOOLEAN,
+	nr: CMCD_KEY_TYPE_BOOLEAN,
+	su: CMCD_KEY_TYPE_BOOLEAN,
+	cdn: CMCD_KEY_TYPE_STRING,
+	cen: CMCD_KEY_TYPE_STRING,
+	cid: CMCD_KEY_TYPE_STRING,
+	cmsdd: CMCD_KEY_TYPE_STRING,
+	cmsds: CMCD_KEY_TYPE_STRING,
+	cs: CMCD_KEY_TYPE_STRING,
+	h: CMCD_KEY_TYPE_STRING,
+	nrr: CMCD_KEY_TYPE_STRING,
+	sid: CMCD_KEY_TYPE_STRING,
+	smrt: CMCD_KEY_TYPE_STRING,
+	url: CMCD_KEY_TYPE_STRING,
+	e: CMCD_KEY_TYPE_TOKEN,
+	ot: CMCD_KEY_TYPE_TOKEN,
+	sf: CMCD_KEY_TYPE_TOKEN,
+	st: CMCD_KEY_TYPE_TOKEN,
+	sta: CMCD_KEY_TYPE_TOKEN
+};
+/**
+* Maps keys to their v1-specific types when they differ from v2.
+*
+* @internal
+*/
+const CMCD_V1_KEY_TYPE_OVERRIDES = {
+	bl: CMCD_KEY_TYPE_INTEGER,
+	br: CMCD_KEY_TYPE_NUMBER,
+	mtp: CMCD_KEY_TYPE_INTEGER,
+	tb: CMCD_KEY_TYPE_NUMBER,
+	nor: CMCD_KEY_TYPE_STRING
+};
+
+//#endregion
+//#region src/CMCD_STRING_LENGTH_LIMITS.ts
+/**
+* Maps CMCD keys to their maximum string length.
+*
+* @internal
+*/
+const CMCD_STRING_LENGTH_LIMITS = {
+	sid: 64,
+	cid: 128,
+	cdn: 128,
+	h: 128,
+	cen: 64
+};
+/**
+* Maximum length for custom key values.
+*
+* @internal
+*/
+const CMCD_CUSTOM_KEY_VALUE_MAX_LENGTH = 64;
+
+//#endregion
+//#region src/CMCD_TOKEN_VALUES.ts
+/**
+* Maps token keys to their valid values.
+*
+* @internal
+*/
+const CMCD_TOKEN_VALUES = {
+	e: [
+		"bc",
+		"ps",
+		"e",
+		"t",
+		"c",
+		"b",
+		"m",
+		"um",
+		"pe",
+		"pc",
+		"rr",
+		"as",
+		"ae",
+		"abs",
+		"abe",
+		"sk",
+		"ce"
+	],
+	ot: [
+		"m",
+		"a",
+		"v",
+		"av",
+		"i",
+		"c",
+		"tt",
+		"k",
+		"o"
+	],
+	sf: [
+		"d",
+		"h",
+		"s",
+		"o"
+	],
+	st: [
+		"v",
+		"l",
+		"ll"
+	],
+	sta: [
+		"s",
+		"p",
+		"k",
+		"r",
+		"a",
+		"w",
+		"e",
+		"f",
+		"q",
+		"d"
+	]
+};
+
+//#endregion
+//#region src/validateCmcdValues.ts
+const HUNDRED_ROUNDING_KEYS = new Set([
+	"bl",
+	"dl",
+	"mtp",
+	"rtp",
+	"tbl"
+]);
+const INTEGER_ROUNDING_KEYS = new Set([
+	"br",
+	"d",
+	"tb"
+]);
+function isFiniteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value);
+}
+function validateListValue(key, value, issues) {
+	if (!Array.isArray(value)) {
+		issues.push({
+			key,
+			message: `Key "${key}" must be an array.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		return;
+	}
+	for (let i = 0; i < value.length; i++) {
+		const element = value[i];
+		if (element instanceof SfItem) {
+			if (!isFiniteNumber(element.value)) issues.push({
+				key,
+				message: `Key "${key}" array element [${i}] must be a finite number.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+		} else if (!isFiniteNumber(element)) issues.push({
+			key,
+			message: `Key "${key}" array element [${i}] must be a finite number.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+}
+function validateStringArrayValue(key, value, issues) {
+	if (!Array.isArray(value)) {
+		issues.push({
+			key,
+			message: `Key "${key}" must be an array.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		return;
+	}
+	for (let i = 0; i < value.length; i++) {
+		const element = value[i];
+		if (element instanceof SfItem) {
+			if (typeof element.value !== "string") issues.push({
+				key,
+				message: `Key "${key}" array element [${i}] must be a string.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+		} else if (typeof element !== "string") issues.push({
+			key,
+			message: `Key "${key}" array element [${i}] must be a string.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+}
+/**
+* Validates that all values in a CMCD payload conform to the expected types and constraints.
+*
+* @example
+* {@includeCode ../test/validateCmcdValues.test.ts#example}
+*
+* @param data - The CMCD payload to validate.
+* @param options - Validation options.
+* @returns The validation result.
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reserved-keys | CTA-5004-A Reserved Keys}
 *
 * @public
+*/
+function validateCmcdValues(data, options) {
+	const version = resolveVersion(data, options);
+	const issues = [];
+	for (const [key, value] of Object.entries(data)) {
+		if (isCmcdCustomKey(key)) {
+			if (typeof value !== "string") issues.push({
+				key,
+				message: `Custom key "${key}" value must be a string or token.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+			else if (value.length > CMCD_CUSTOM_KEY_VALUE_MAX_LENGTH) issues.push({
+				key,
+				message: `Custom key "${key}" value exceeds maximum length of ${CMCD_CUSTOM_KEY_VALUE_MAX_LENGTH}.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+			continue;
+		}
+		if (key === "v") {
+			if (value !== 1 && value !== 2) issues.push({
+				key,
+				message: `Key "v" must be 1 or 2.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+			continue;
+		}
+		let expectedType = CMCD_KEY_TYPES[key];
+		if (!expectedType) continue;
+		if (version === CMCD_V1 && key in CMCD_V1_KEY_TYPE_OVERRIDES) expectedType = CMCD_V1_KEY_TYPE_OVERRIDES[key];
+		switch (expectedType) {
+			case CMCD_KEY_TYPE_INTEGER:
+				if (!isFiniteNumber(value) || !Number.isInteger(value)) issues.push({
+					key,
+					message: `Key "${key}" must be a finite integer.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				else if (HUNDRED_ROUNDING_KEYS.has(key) && value % 100 !== 0) issues.push({
+					key,
+					message: `Key "${key}" should be rounded to the nearest 100.`,
+					severity: CMCD_VALIDATION_SEVERITY_WARNING
+				});
+				break;
+			case CMCD_KEY_TYPE_NUMBER:
+				if (!isFiniteNumber(value)) issues.push({
+					key,
+					message: `Key "${key}" must be a finite number.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				else if (HUNDRED_ROUNDING_KEYS.has(key) && value % 100 !== 0) issues.push({
+					key,
+					message: `Key "${key}" should be rounded to the nearest 100.`,
+					severity: CMCD_VALIDATION_SEVERITY_WARNING
+				});
+				else if (INTEGER_ROUNDING_KEYS.has(key) && !Number.isInteger(value)) issues.push({
+					key,
+					message: `Key "${key}" should be rounded to an integer.`,
+					severity: CMCD_VALIDATION_SEVERITY_WARNING
+				});
+				break;
+			case CMCD_KEY_TYPE_BOOLEAN:
+				if (typeof value !== "boolean") issues.push({
+					key,
+					message: `Key "${key}" must be a boolean.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				break;
+			case CMCD_KEY_TYPE_STRING:
+				if (typeof value !== "string") issues.push({
+					key,
+					message: `Key "${key}" must be a string.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				else if (key in CMCD_STRING_LENGTH_LIMITS && value.length > CMCD_STRING_LENGTH_LIMITS[key]) issues.push({
+					key,
+					message: `Key "${key}" exceeds maximum length of ${CMCD_STRING_LENGTH_LIMITS[key]}.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				break;
+			case CMCD_KEY_TYPE_TOKEN: {
+				const validValues = CMCD_TOKEN_VALUES[key];
+				if (validValues && !validValues.includes(value)) issues.push({
+					key,
+					message: `Key "${key}" has invalid token value "${String(value)}". Expected one of: ${validValues.join(", ")}.`,
+					severity: CMCD_VALIDATION_SEVERITY_ERROR
+				});
+				break;
+			}
+			case CMCD_KEY_TYPE_NUMBER_LIST:
+				validateListValue(key, value, issues);
+				break;
+			case CMCD_KEY_TYPE_STRING_LIST:
+				validateStringArrayValue(key, value, issues);
+				break;
+		}
+	}
+	return {
+		valid: issues.every((i) => i.severity !== CMCD_VALIDATION_SEVERITY_ERROR),
+		issues
+	};
+}
+
+//#endregion
+//#region src/validateCmcd.ts
+/**
+* Validates a CMCD payload by checking keys, values, and structure.
 *
 * @example
-* {@includeCode ../test/fromCmcdUrl.test.ts#example}
+* {@includeCode ../test/validateCmcd.test.ts#example}
+*
+* @param data - The CMCD payload to validate.
+* @param options - Validation options.
+* @returns The validation result.
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#data-payload-definition-what-data-to-send | CTA-5004-A Data Payload Definition}
+*
+* @public
 */
-function fromCmcdUrl(url) {
-	return decodeCmcd(decodeURIComponent(url.replace(/^CMCD=/, "")));
+function validateCmcd(data, options) {
+	return mergeValidationResults(validateCmcdKeys(data, options), validateCmcdValues(data, options), validateCmcdStructure(data, options));
 }
 
 //#endregion
-//#region src/toCmcdValue.ts
+//#region src/validateCmcdEvents.ts
 /**
-* Convert a value to a CMCD value.
+* Validates a raw CMCD string as an event-mode payload.
 *
-* @param value - The value to convert to a CMCD value.
-* @param params - The parameters to convert to a CMCD value.
-* @returns The CMCD value.
+* This function decodes the string internally and validates it with
+* `reportingMode` set to `'event'`. The input may contain multiple
+* newline-separated events (e.g. an `application/cmcd` POST body), in which
+* case each line is validated independently and the results are merged.
+*
+* @param cmcd - The raw CMCD-encoded string to validate. May contain
+*   multiple newline-separated event lines.
+* @param options - Validation options (excluding `reportingMode`).
+* @returns The validation result including decoded data per event line.
+*
+* @example
+* {@includeCode ../test/validateCmcdEvents.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#body-definition | CTA-5004-A Body Definition}
 *
 * @public
 */
-function toCmcdValue(value, params) {
-	return new SfItem(value, params);
+function validateCmcdEvents(cmcd, options) {
+	const opts = {
+		...options,
+		reportingMode: CMCD_EVENT_MODE
+	};
+	const lines = cmcd.split(/\r?\n/).filter((line) => line.length > 0);
+	if (lines.length === 0) return {
+		valid: false,
+		issues: [{
+			message: "Empty event mode payload. At least one event line is required.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		}],
+		data: []
+	};
+	const decodedLines = [];
+	const lineResults = [];
+	for (let i = 0; i < lines.length; i++) try {
+		const data = decodeCmcd(lines[i]);
+		decodedLines.push(data);
+		lineResults.push(validateCmcd(data, opts));
+	} catch {
+		decodedLines.push({});
+		lineResults.push({
+			valid: false,
+			issues: [{
+				message: `Failed to decode event line ${i + 1}: invalid structured field syntax.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			}]
+		});
+	}
+	return {
+		...mergeValidationResults(...lineResults),
+		data: decodedLines
+	};
+}
+
+//#endregion
+//#region src/validateCmcdEventReport.ts
+/**
+* Validates a full HTTP request as an event-mode payload.
+*
+* Accepts an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
+*
+* This function validates that the request uses the POST method and has
+* the correct `Content-Type` header (`application/cmcd`) in addition to
+* validating the body content via {@link validateCmcdEvents}.
+*
+* @param request - An `HttpRequest` to validate.
+* @param options - Validation options (excluding `reportingMode`).
+* @returns The validation result including decoded data per event line.
+*
+* @example {@includeCode ../test/validateCmcdEventReport.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event-mode | CTA-5004-A Event Mode}
+*
+* @public
+*/
+function validateCmcdEventReport(request, options) {
+	const issues = [];
+	if (request.method !== "POST") issues.push({
+		message: `Invalid HTTP method '${request.method ?? "GET"}'. Event reports must use POST.`,
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
+	const contentType = request.headers ? ensureHeaders(request.headers).get("Content-Type") : void 0;
+	if (!contentType) issues.push({
+		message: `Missing Content-Type header. Event reports must use '${CMCD_MIME_TYPE}'.`,
+		severity: CMCD_VALIDATION_SEVERITY_ERROR
+	});
+	else {
+		const mediaType = contentType.split(";")[0].trim().toLowerCase();
+		if (mediaType !== CMCD_MIME_TYPE) issues.push({
+			message: `Invalid Content-Type '${mediaType}'. Event reports must use '${CMCD_MIME_TYPE}'.`,
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+	}
+	const body = request.body;
+	if (body === void 0 || body === null) {
+		issues.push({
+			message: "Missing request body. Event reports must include a body.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		return {
+			valid: false,
+			issues,
+			data: []
+		};
+	}
+	if (typeof body !== "string") {
+		issues.push({
+			message: "Request body must be a string.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		});
+		return {
+			valid: false,
+			issues,
+			data: []
+		};
+	}
+	const bodyResult = validateCmcdEvents(body, options);
+	return {
+		valid: issues.length === 0 && bodyResult.valid,
+		issues: [...issues, ...bodyResult.issues],
+		data: bodyResult.data
+	};
+}
+
+//#endregion
+//#region src/validateCmcdHeaders.ts
+/**
+* Validates CMCD HTTP headers by checking shard placement and payload validity.
+*
+* This function accepts raw CMCD header strings, decodes each shard
+* internally, verifies that each key is placed in its correct header shard,
+* then merges all shards and runs full payload validation (keys, values, and
+* structure) on the merged data.
+*
+* @example
+* {@includeCode ../test/validateCmcdHeaders.test.ts#example}
+*
+* @param headers - A `Headers` instance or a record of CMCD header fields to their raw encoded string values.
+* @param options - Validation options (excluding `reportingMode`).
+* @returns The validation result including decoded data.
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#header-field-definition | CTA-5004-A Header Field Definition}
+*
+* @public
+*/
+function validateCmcdHeaders(headers, options) {
+	const h = ensureHeaders(headers);
+	const issues = [];
+	const decoded = {};
+	for (const headerField of CMCD_HEADER_FIELDS) {
+		const raw = h.get(headerField);
+		if (!raw) continue;
+		let shard;
+		try {
+			shard = decodeCmcd(raw);
+		} catch {
+			issues.push({
+				key: headerField,
+				message: `Failed to decode "${headerField}" header: invalid structured field syntax.`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+			continue;
+		}
+		decoded[headerField] = shard;
+		for (const key of Object.keys(shard)) {
+			if (isCmcdCustomKey(key)) continue;
+			const expectedHeader = CMCD_HEADER_MAP[key];
+			if (expectedHeader && expectedHeader !== headerField) issues.push({
+				key,
+				message: `Key "${key}" is in "${headerField}" but should be in "${expectedHeader}".`,
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			});
+		}
+	}
+	const shardResult = {
+		valid: issues.length === 0,
+		issues
+	};
+	const merged = Object.assign({}, ...CMCD_HEADER_FIELDS.map((f) => decoded[f]).filter(Boolean));
+	return {
+		...mergeValidationResults(shardResult, validateCmcd(merged, {
+			...options,
+			reportingMode: CMCD_REQUEST_MODE
+		})),
+		data: merged
+	};
+}
+
+//#endregion
+//#region src/validateCmcdRequest.ts
+/**
+* Validates CMCD data from a request as a request-mode payload.
+*
+* Accepts a
+* {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
+* object or an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
+*
+* The function checks for CMCD data in the HTTP headers first. If CMCD
+* headers are found, validation includes shard-placement checks via
+* {@link validateCmcdHeaders}. Otherwise, the CMCD query parameter is
+* extracted from the URL and validated.
+*
+* @param request - A `Request` or `HttpRequest` to validate.
+* @param options - Validation options (excluding `reportingMode`).
+* @returns The validation result including decoded data.
+*
+* @example
+* {@includeCode ../test/validateCmcdRequest.test.ts#example}
+*
+* @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#request-mode | CTA-5004-A Request Mode}
+*
+* @public
+*/
+function validateCmcdRequest(request, options) {
+	const headers = extractHeaderRecord(request.headers);
+	if (headers) return validateCmcdHeaders(headers, options);
+	const param = new URL(request.url).searchParams.get(CMCD_PARAM);
+	if (!param) return {
+		valid: false,
+		issues: [{
+			message: "No CMCD data found in request headers or query parameters.",
+			severity: CMCD_VALIDATION_SEVERITY_ERROR
+		}],
+		data: {}
+	};
+	let data;
+	try {
+		data = decodeCmcd(param);
+	} catch {
+		return {
+			valid: false,
+			issues: [{
+				message: "Failed to decode CMCD query parameter: invalid structured field syntax.",
+				severity: CMCD_VALIDATION_SEVERITY_ERROR
+			}],
+			data: {}
+		};
+	}
+	return {
+		...validateCmcd(data, {
+			...options,
+			reportingMode: CMCD_REQUEST_MODE
+		}),
+		data
+	};
+}
+function extractHeaderRecord(headers) {
+	if (!headers) return;
+	const h = ensureHeaders(headers);
+	const result = {};
+	let found = false;
+	for (const field of CMCD_HEADER_FIELDS) {
+		const value = h.get(field);
+		if (value) {
+			result[field] = value;
+			found = true;
+		}
+	}
+	return found ? result : void 0;
 }
 
 //#endregion
-export { CMCD_DEFAULT_TIME_INTERVAL, CMCD_EVENT_AD_BREAK_END, CMCD_EVENT_AD_BREAK_START, CMCD_EVENT_AD_END, CMCD_EVENT_AD_START, CMCD_EVENT_BACKGROUNDED_MODE, CMCD_EVENT_BITRATE_CHANGE, CMCD_EVENT_CONTENT_ID, CMCD_EVENT_CUSTOM_EVENT, CMCD_EVENT_ERROR, CMCD_EVENT_KEYS, CMCD_EVENT_MODE, CMCD_EVENT_MUTE, CMCD_EVENT_PLAYER_COLLAPSE, CMCD_EVENT_PLAYER_EXPAND, CMCD_EVENT_PLAY_STATE, CMCD_EVENT_RESPONSE_RECEIVED, CMCD_EVENT_SKIP, CMCD_EVENT_TIME_INTERVAL, CMCD_EVENT_UNMUTE, CMCD_FORMATTER_MAP, CMCD_HEADERS, CMCD_HEADER_MAP, CMCD_JSON, CMCD_KEYS, CMCD_OBJECT, CMCD_PARAM, CMCD_QUERY, CMCD_REQUEST, CMCD_REQUEST_KEYS, CMCD_REQUEST_MODE, CMCD_RESPONSE_KEYS, CMCD_SESSION, CMCD_STATUS, CMCD_V1, CMCD_V1_KEYS, CMCD_V2, CmcdEventType, CmcdHeaderField, CmcdObjectType, CmcdPlayerState, CmcdReporter, CmcdReportingMode, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, appendCmcdHeaders, appendCmcdQuery, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Key, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue };
+export { CMCD_DEFAULT_TIME_INTERVAL, CMCD_EVENT_AD_BREAK_END, CMCD_EVENT_AD_BREAK_START, CMCD_EVENT_AD_END, CMCD_EVENT_AD_START, CMCD_EVENT_BACKGROUNDED_MODE, CMCD_EVENT_BITRATE_CHANGE, CMCD_EVENT_CONTENT_ID, CMCD_EVENT_CUSTOM_EVENT, CMCD_EVENT_ERROR, CMCD_EVENT_KEYS, CMCD_EVENT_MODE, CMCD_EVENT_MUTE, CMCD_EVENT_PLAYER_COLLAPSE, CMCD_EVENT_PLAYER_EXPAND, CMCD_EVENT_PLAY_STATE, CMCD_EVENT_RESPONSE_RECEIVED, CMCD_EVENT_SKIP, CMCD_EVENT_TIME_INTERVAL, CMCD_EVENT_UNMUTE, CMCD_FORMATTER_MAP, CMCD_HEADERS, CMCD_HEADER_FIELDS, CMCD_HEADER_MAP, CMCD_JSON, CMCD_KEYS, CMCD_MIME_TYPE, CMCD_OBJECT, CMCD_PARAM, CMCD_QUERY, CMCD_REQUEST, CMCD_REQUEST_KEYS, CMCD_REQUEST_MODE, CMCD_RESPONSE_KEYS, CMCD_SESSION, CMCD_STATUS, CMCD_V1, CMCD_V1_KEYS, CMCD_V2, CMCD_VALIDATION_SEVERITY_ERROR, CMCD_VALIDATION_SEVERITY_WARNING, CmcdEventType, CmcdHeaderField, CmcdObjectType, CmcdPlayerState, CmcdReporter, CmcdReportingMode, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdValidationSeverity, appendCmcdHeaders, appendCmcdQuery, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Data, isCmcdV1Key, isCmcdV2Data, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue, validateCmcd, validateCmcdEventReport, validateCmcdEvents, validateCmcdHeaders, validateCmcdKeys, validateCmcdRequest, validateCmcdStructure, validateCmcdValues };
 //# sourceMappingURL=index.js.map