@svta/cml-cmcd 2.3.1 → 2.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { SfItem, SfToken, decodeSfDict, encodeSfDict, symbolToStr } from "@svta/cml-structured-field-values";
-import { urlToRelativePath, uuid } from "@svta/cml-utils";
+import { getBaseUrl, urlToRelativePath, uuid } from "@svta/cml-utils";
 
 //#region src/CMCD_FORMATTER_MAP.ts
 const roundValue = (value) => {
@@ -14,7 +14,7 @@ const toUrlSafe = (value, options) => {
 	if (Array.isArray(value)) return value.map((item) => toUrlSafe(item, options));
 	if (value instanceof SfItem && typeof value.value === "string") return new SfItem(toUrlSafe(value.value, options), value.params);
 	else {
-		if (options.baseUrl) value = urlToRelativePath(value, options.baseUrl);
+		if (options.baseUrl) value = urlToRelativePath(value, getBaseUrl(options.baseUrl));
 		return options.version === 1 ? encodeURIComponent(value) : value;
 	}
 };
@@ -74,6 +74,12 @@ const CMCD_EVENT_BITRATE_CHANGE = "bc";
 */
 const CMCD_EVENT_PLAY_STATE = "ps";
 /**
+* CMCD event type for the 'pr' key (playback rate change).
+*
+* @public
+*/
+const CMCD_EVENT_PLAYBACK_RATE = "pr";
+/**
 * CMCD event type for the 'e' key (error).
 *
 * @public
@@ -175,6 +181,7 @@ const CMCD_EVENT_CUSTOM_EVENT = "ce";
 const CmcdEventType = {
 	BITRATE_CHANGE: CMCD_EVENT_BITRATE_CHANGE,
 	PLAY_STATE: CMCD_EVENT_PLAY_STATE,
+	PLAYBACK_RATE: CMCD_EVENT_PLAYBACK_RATE,
 	ERROR: CMCD_EVENT_ERROR,
 	TIME_INTERVAL: CMCD_EVENT_TIME_INTERVAL,
 	CONTENT_ID: CMCD_EVENT_CONTENT_ID,
@@ -192,6 +199,32 @@ const CmcdEventType = {
 	CUSTOM_EVENT: CMCD_EVENT_CUSTOM_EVENT
 };
 
+//#endregion
+//#region src/CMCD_STATE_EVENT_FIELDS.ts
+/**
+* Maps each state-change event type to the persistent field whose value
+* the event signals.
+*
+* Per CTA-5004-B, the state-change events `ps`, `pr`, `c`, `b`, `bc` are
+* state-transition markers and must carry the field whose value they signal.
+* Consumers force-include the field post-filter (`prepareCmcdData`), dedup
+* against its value (`CmcdReporter`), and check its presence in payloads
+* (`validateCmcdStructure`).
+*
+* Iteration order is load-bearing: `CmcdReporter.update()` fires state-change
+* events in map order when multiple tracked fields change in a single call.
+* Do not reorder entries without auditing reporter behavior.
+*
+* @internal
+*/
+const CMCD_STATE_EVENT_FIELDS = new Map([
+	[CMCD_EVENT_PLAY_STATE, "sta"],
+	[CMCD_EVENT_PLAYBACK_RATE, "pr"],
+	[CMCD_EVENT_CONTENT_ID, "cid"],
+	[CMCD_EVENT_BACKGROUNDED_MODE, "bg"],
+	[CMCD_EVENT_BITRATE_CHANGE, "br"]
+]);
+
 //#endregion
 //#region src/CmcdReportingMode.ts
 /**
@@ -550,6 +583,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");
+		const requiredField = eventType ? CMCD_STATE_EVENT_FIELDS.get(eventType) : void 0;
+		if (requiredField && data[requiredField] != null && !keys.includes(requiredField)) keys.push(requiredField);
 	}
 	if (keys.length === 0) return results;
 	if (version > 1 && !keys.includes("v")) keys.push("v");
@@ -565,9 +600,10 @@ function prepareCmcdData(obj, options = {}) {
 		if (typeof formatter === "function") value = formatter(value, formatterOptions);
 		if (key === "v") if (version === 1) continue;
 		else value = version;
-		if (key === "pr" && value === 1) continue;
+		if (key === "pr" && value === 1 && !(isEventMode && data["e"] === CMCD_EVENT_PLAYBACK_RATE)) continue;
 		if (isEventMode && key === "ts" && !Number.isFinite(value)) value = Date.now();
-		if (!isValid(value)) continue;
+		const isBgFalseTransition = isEventMode && value === false && key === "bg" && data["e"] === CMCD_EVENT_BACKGROUNDED_MODE;
+		if (!isValid(value) && !isBgFalseTransition) continue;
 		if (isTokenField(key) && typeof value === "string") value = new SfToken(value);
 		results[key] = value;
 	}
@@ -979,6 +1015,417 @@ const CmcdPlayerState = {
 	PRELOADING: "d"
 };
 
+//#endregion
+//#region src/CmcdRecordedReportMode.ts
+/**
+* CMCD query reporting mode — CMCD data carried as a `CMCD=` URL
+* query parameter.
+*
+* @public
+*/
+const CMCD_RECORDED_REPORT_MODE_QUERY = "query";
+/**
+* CMCD header reporting mode — CMCD data carried as `Cmcd-*` HTTP
+* headers.
+*
+* @public
+*/
+const CMCD_RECORDED_REPORT_MODE_HEADER = "header";
+/**
+* CMCD event reporting mode — CMCD data carried as a POST body to an
+* event-target URL.
+*
+* @public
+*/
+const CMCD_RECORDED_REPORT_MODE_EVENT = "event";
+/**
+* Reporting mode under which a captured report was observed by
+* `CmcdReportRecorder`.
+*
+* @enum
+*
+* @public
+*/
+const CmcdRecordedReportMode = {
+	QUERY: CMCD_RECORDED_REPORT_MODE_QUERY,
+	HEADER: CMCD_RECORDED_REPORT_MODE_HEADER,
+	EVENT: CMCD_RECORDED_REPORT_MODE_EVENT
+};
+
+//#endregion
+//#region src/CmcdRecordedRequestType.ts
+/**
+* Manifest or playlist request classification.
+*
+* @public
+*/
+const CMCD_RECORDED_REQUEST_TYPE_MANIFEST = "manifest";
+/**
+* Media segment request classification.
+*
+* @public
+*/
+const CMCD_RECORDED_REQUEST_TYPE_SEGMENT = "segment";
+/**
+* CMCD event-mode report request classification (POST to a URL in
+* `eventTargetUrls`).
+*
+* @public
+*/
+const CMCD_RECORDED_REQUEST_TYPE_EVENT = "event";
+/**
+* Fallback classification for requests the recorder did not recognize
+* as manifest, segment, or event.
+*
+* @public
+*/
+const CMCD_RECORDED_REQUEST_TYPE_UNKNOWN = "unknown";
+/**
+* Classification of a captured request, used by `CmcdReportRecorder`
+* for filtering.
+*
+* @enum
+*
+* @public
+*/
+const CmcdRecordedRequestType = {
+	MANIFEST: CMCD_RECORDED_REQUEST_TYPE_MANIFEST,
+	SEGMENT: CMCD_RECORDED_REQUEST_TYPE_SEGMENT,
+	EVENT: CMCD_RECORDED_REQUEST_TYPE_EVENT,
+	UNKNOWN: CMCD_RECORDED_REQUEST_TYPE_UNKNOWN
+};
+
+//#endregion
+//#region src/createFetchTransport.ts
+async function toHttpRequest(request) {
+	const headers = {};
+	request.headers.forEach((value, name) => {
+		headers[name.toLowerCase()] = value;
+	});
+	let body;
+	if (request.body) try {
+		body = await request.text();
+	} catch {
+		body = void 0;
+	}
+	return {
+		url: request.url,
+		method: request.method,
+		headers,
+		body
+	};
+}
+/**
+* Create a transport adapter that patches `globalThis.fetch` to capture
+* CMCD-bearing requests, normalizing each to `HttpRequest` (lowercase
+* headers, body read as UTF-8 string). Returns the adapter object
+* expected by `CmcdReportRecorder`.
+*
+* Bodies are read once via `Request.text()` for inspection. This is
+* safe for the body types CMCD reports use in practice (`string`,
+* `Blob`, `ArrayBuffer`, `FormData`, `URLSearchParams`), which can be
+* read by the wrapper and re-read by the underlying `fetch`. Passing
+* a `ReadableStream` as `init.body` is not supported — the stream is
+* consumed by the wrapper and the underlying `fetch` will receive an
+* already-disturbed stream.
+*
+* @public
+*/
+function createFetchTransport() {
+	return { attach(deliver) {
+		const origFetch = globalThis.fetch;
+		globalThis.fetch = async (input, init) => {
+			const synthetic = deliver(await toHttpRequest(input instanceof Request ? input.clone() : new Request(input, init)));
+			if (synthetic) return synthetic;
+			return origFetch.call(globalThis, input, init);
+		};
+		return () => {
+			globalThis.fetch = origFetch;
+		};
+	} };
+}
+
+//#endregion
+//#region src/createXhrTransport.ts
+async function completeXhrWith(xhr, response) {
+	const text = await response.clone().text().catch(() => "");
+	const ProgressEventCtor = typeof ProgressEvent !== "undefined" ? ProgressEvent : Event;
+	queueMicrotask(() => {
+		try {
+			Object.defineProperty(xhr, "status", {
+				value: response.status,
+				configurable: true
+			});
+			Object.defineProperty(xhr, "statusText", {
+				value: response.statusText,
+				configurable: true
+			});
+			Object.defineProperty(xhr, "readyState", {
+				value: 4,
+				configurable: true
+			});
+			Object.defineProperty(xhr, "responseURL", {
+				value: xhr._cmcdUrl ?? "",
+				configurable: true
+			});
+			Object.defineProperty(xhr, "response", {
+				value: text,
+				configurable: true
+			});
+			Object.defineProperty(xhr, "responseText", {
+				value: text,
+				configurable: true
+			});
+			if (typeof xhr.onload === "function") xhr.onload.call(xhr, new ProgressEventCtor("load"));
+			if (typeof xhr.onloadend === "function") xhr.onloadend.call(xhr, new ProgressEventCtor("loadend"));
+		} catch {
+			const target = xhr;
+			target["status"] = response.status;
+			target["statusText"] = response.statusText;
+			target["readyState"] = 4;
+			target["responseURL"] = xhr._cmcdUrl ?? "";
+			target["response"] = text;
+			target["responseText"] = text;
+			if (typeof xhr.onload === "function") xhr.onload.call(xhr, new ProgressEventCtor("load"));
+			if (typeof xhr.onloadend === "function") xhr.onloadend.call(xhr, new ProgressEventCtor("loadend"));
+		}
+	});
+}
+/**
+* Create a transport adapter that patches `XMLHttpRequest.prototype` to
+* capture CMCD-bearing requests. Returns the adapter object expected by
+* `CmcdReportRecorder`.
+*
+* @public
+*/
+function createXhrTransport() {
+	return { attach(deliver) {
+		const Xhr = globalThis.XMLHttpRequest;
+		if (!Xhr) return () => {};
+		const origOpen = Xhr.prototype.open;
+		const origSetRequestHeader = Xhr.prototype.setRequestHeader;
+		const origSend = Xhr.prototype.send;
+		Xhr.prototype.open = function(method, url) {
+			this._cmcdMethod = method;
+			this._cmcdUrl = typeof url === "string" ? url : url.toString();
+			this._cmcdHeaders = {};
+			return origOpen.apply(this, arguments);
+		};
+		Xhr.prototype.setRequestHeader = function(name, value) {
+			if (this._cmcdHeaders) this._cmcdHeaders[name.toLowerCase()] = value;
+			return origSetRequestHeader.apply(this, [name, value]);
+		};
+		Xhr.prototype.send = function(body) {
+			const synthetic = deliver({
+				url: this._cmcdUrl ?? "",
+				method: (this._cmcdMethod ?? "GET").toUpperCase(),
+				headers: this._cmcdHeaders ?? {},
+				body: (typeof Document !== "undefined" && body instanceof Document ? void 0 : body) ?? void 0
+			});
+			if (synthetic) {
+				completeXhrWith(this, synthetic);
+				return;
+			}
+			return origSend.apply(this, [body]);
+		};
+		return () => {
+			Xhr.prototype.open = origOpen;
+			Xhr.prototype.setRequestHeader = origSetRequestHeader;
+			Xhr.prototype.send = origSend;
+		};
+	} };
+}
+
+//#endregion
+//#region src/CmcdReportRecorder.ts
+const MANIFEST_EXTENSIONS = /\.(m3u8|mpd)(\?|$|\/)/i;
+const SEGMENT_EXTENSIONS = /\.(m4s|m4v|m4a|mp4|ts|aac)(\?|$|\/)/i;
+function classifyUrl(url, isEventTarget) {
+	if (isEventTarget) return CmcdRecordedRequestType.EVENT;
+	if (MANIFEST_EXTENSIONS.test(url)) return CmcdRecordedRequestType.MANIFEST;
+	if (SEGMENT_EXTENSIONS.test(url)) return CmcdRecordedRequestType.SEGMENT;
+	return CmcdRecordedRequestType.UNKNOWN;
+}
+function hasCmcdHeader(headers) {
+	if (!headers) return false;
+	for (const name in headers) if (name.toLowerCase().startsWith("cmcd-")) return true;
+	return false;
+}
+function detectReportingMode(url, headers, isEventTarget) {
+	if (isEventTarget) return "event";
+	if (hasCmcdHeader(headers)) return "header";
+	return url.includes(`${CMCD_PARAM}=`) ? "query" : null;
+}
+/**
+* Test helper that records CMCD-bearing reports across XHR and fetch
+* transports for assertion in e2e tests. Each captured request is
+* normalized to {@link @svta/cml-utils!HttpRequest | HttpRequest} so
+* tests are identical regardless of which transport the player uses.
+*
+* @example
+* {@includeCode ../test/CmcdReportRecorder.test.ts#example}
+*
+* @public
+*/
+var CmcdReportRecorder = class {
+	#reports = [];
+	#detachers = [];
+	#attached = false;
+	#eventTargetUrls = [];
+	#waiters = /* @__PURE__ */ new Map();
+	#onReport;
+	#waitTimeout = 15e3;
+	#deliver = (request) => {
+		const url = request.url;
+		const isEventTarget = (request.method ?? "GET").toUpperCase() === "POST" && this.#eventTargetUrls.some((t) => url.startsWith(t));
+		const reportingMode = detectReportingMode(url, request.headers, isEventTarget);
+		if (reportingMode === null) return;
+		const captured = {
+			request,
+			type: classifyUrl(url, isEventTarget),
+			reportingMode,
+			timestamp: Date.now()
+		};
+		this.#reports.push(captured);
+		if (this.#onReport) try {
+			this.#onReport(captured);
+		} catch (err) {
+			console.error("CmcdReportRecorder onReport listener threw:", err);
+		}
+		this.#notifyWaiters();
+		return isEventTarget ? new Response(null, { status: 204 }) : void 0;
+	};
+	#getMatching(type) {
+		return type === void 0 ? [...this.#reports] : this.#reports.filter((r) => r.type === type);
+	}
+	#notifyWaiters() {
+		for (const [timer, waiter] of this.#waiters) {
+			const matching = this.#getMatching(waiter.type);
+			if (matching.length >= waiter.count) {
+				clearTimeout(timer);
+				this.#waiters.delete(timer);
+				waiter.resolve(matching);
+			}
+		}
+	}
+	#waitFor(type, options) {
+		const count = options.count ?? 1;
+		const timeout = options.timeout ?? this.#waitTimeout;
+		const matching = this.#getMatching(type);
+		if (matching.length >= count) return Promise.resolve(matching);
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.#waiters.delete(timer);
+				const current = this.#getMatching(type);
+				reject(/* @__PURE__ */ new Error(`Timeout waiting for ${count} ${type ?? "any"} CMCD report(s). Got ${current.length}. Total recorded: ${this.#reports.length}.`));
+			}, timeout);
+			this.#waiters.set(timer, {
+				type,
+				count,
+				resolve,
+				reject
+			});
+		});
+	}
+	/**
+	* Install transport patches and begin recording CMCD reports.
+	* No-op if already attached — the previously supplied options are
+	* retained and the new `options` argument is silently ignored.
+	* Call `detach()` first if you need to re-attach with different
+	* options.
+	*
+	* @public
+	*/
+	attach(options = {}) {
+		if (this.#attached) return;
+		this.#attached = true;
+		this.#eventTargetUrls = options.eventTargetUrls ?? [];
+		this.#onReport = options.onReport;
+		this.#waitTimeout = options.waitTimeout ?? 15e3;
+		const transports = options.transports ?? [createXhrTransport(), createFetchTransport()];
+		for (const transport of transports) this.#detachers.push(transport.attach(this.#deliver));
+	}
+	/**
+	* Remove transport patches and stop recording. Rejects any pending
+	* wait promises with `Error('Recorder detached while waiting')`.
+	*
+	* @public
+	*/
+	detach() {
+		if (!this.#attached) return;
+		for (const detacher of this.#detachers) detacher();
+		this.#detachers = [];
+		this.#attached = false;
+		this.#eventTargetUrls = [];
+		this.#onReport = void 0;
+		for (const [timer, waiter] of this.#waiters) {
+			clearTimeout(timer);
+			waiter.reject(/* @__PURE__ */ new Error("Recorder detached while waiting"));
+		}
+		this.#waiters.clear();
+	}
+	/**
+	* Discard all recorded reports. Does not affect the attached state.
+	*
+	* @public
+	*/
+	clear() {
+		this.#reports = [];
+	}
+	/**
+	* Return a defensive copy of all recorded reports.
+	*
+	* @public
+	*/
+	getReports() {
+		return [...this.#reports];
+	}
+	/**
+	* Wait until at least `count` reports of any type are recorded.
+	* Resolves with all matching reports; rejects with a diagnostic error
+	* on timeout. `count` defaults to 1; `timeout` falls back to the
+	* recorder's `waitTimeout` option (default 15000 ms).
+	*
+	* @public
+	*/
+	waitForReports(options = {}) {
+		return this.#waitFor(void 0, options);
+	}
+	/**
+	* Wait until at least `count` manifest reports are recorded.
+	* Resolves with all matching reports; rejects with a diagnostic error
+	* on timeout. `count` defaults to 1; `timeout` falls back to the
+	* recorder's `waitTimeout` option (default 15000 ms).
+	*
+	* @public
+	*/
+	waitForManifest(options = {}) {
+		return this.#waitFor(CmcdRecordedRequestType.MANIFEST, options);
+	}
+	/**
+	* Wait until at least `count` segment reports are recorded.
+	* Resolves with all matching reports; rejects with a diagnostic error
+	* on timeout. `count` defaults to 1; `timeout` falls back to the
+	* recorder's `waitTimeout` option (default 15000 ms).
+	*
+	* @public
+	*/
+	waitForSegments(options = {}) {
+		return this.#waitFor(CmcdRecordedRequestType.SEGMENT, options);
+	}
+	/**
+	* Wait until at least `count` event-mode reports are recorded.
+	* Resolves with all matching reports; rejects with a diagnostic error
+	* on timeout. `count` defaults to 1; `timeout` falls back to the
+	* recorder's `waitTimeout` option (default 15000 ms).
+	*
+	* @public
+	*/
+	waitForEvents(options = {}) {
+		return this.#waitFor(CmcdRecordedRequestType.EVENT, options);
+	}
+};
+
 //#endregion
 //#region src/CmcdTransmissionMode.ts
 /**
@@ -1025,6 +1472,53 @@ function createEncodingOptions(reportingMode, config, baseUrl) {
 		baseUrl
 	};
 }
+/**
+* Deep equality for CmcdObjectTypeList (used for `br` dedup).
+*
+* Order-sensitive: arrays with the same elements in different positions
+* are treated as different. Players that construct `br` consistently
+* get correct dedup; shuffling produces spurious emits, which is the
+* safer failure mode.
+*/
+function cmcdObjectTypeListEqual(a, b) {
+	if (a === b) return true;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		const ai = a[i];
+		const bi = b[i];
+		if (ai === bi) continue;
+		if (typeof ai === "number" || typeof bi === "number") return false;
+		if (ai.value !== bi.value) return false;
+		const ap = ai.params;
+		const bp = bi.params;
+		const ak = ap && Object.keys(ap)[0];
+		const bk = bp && Object.keys(bp)[0];
+		if (ak !== bk) return false;
+		if (ak !== void 0 && bk !== void 0 && ap && bp && ap[ak] !== bp[bk]) return false;
+	}
+	return true;
+}
+const equal = Object.is;
+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]) => {
+	if (field === "br") return {
+		event,
+		field,
+		equal: (a, b) => a === void 0 || b === void 0 ? a === b : cmcdObjectTypeListEqual(a, b),
+		snapshot: (v) => v.slice()
+	};
+	return {
+		event,
+		field,
+		equal,
+		snapshot: identity
+	};
+});
+const STATE_FIELDS_BY_EVENT = new Map(STATE_FIELDS.map((e) => [e.event, e]));
 function defaultRequester(request) {
 	const { url,...init } = request;
 	return fetch(url, init);
@@ -1070,6 +1564,7 @@ var CmcdReporter = class {
 		this.data = {};
 		this.msd = NaN;
 		this.eventTargets = /* @__PURE__ */ new Map();
+		this.lastEmitted = {};
 		this.requestTarget = {
 			sn: 0,
 			msdSent: false
@@ -1098,7 +1593,7 @@ var CmcdReporter = class {
 	start() {
 		this.eventTargets.forEach((target, config) => {
 			this.disarmInterval(target);
-			if (config.interval === 0 || !config.events.includes(CmcdEventType.TIME_INTERVAL)) return;
+			if (config.interval === 0 || !config.events.includes(CMCD_EVENT_TIME_INTERVAL)) return;
 			const timeIntervalEvent = () => {
 				this.recordTargetEvent(target, config, CMCD_EVENT_TIME_INTERVAL);
 				this.processEventTargets();
@@ -1127,7 +1622,22 @@ var CmcdReporter = class {
 		this.processEventTargets(true);
 	}
 	/**
-	* Updates the CMCD data. Called by the player when the data changes.
+	* Updates the CMCD data.
+	*
+	* Called by the player when data changes. For tracked state fields
+	* (`sta`, `pr`, `cid`, `bg`, `br`), if the new value differs from the
+	* last-reported value (the value most recently emitted on the wire for
+	* that field), the corresponding state-change event is automatically
+	* fired. Comparing against the last-reported value (rather than the
+	* previous persisted value) ensures the first state-change event in a
+	* new session always emits, even when the persisted value didn't change
+	* across the `sid` boundary.
+	*
+	* Multi-field updates fire multiple events in the order: `sta` → `pr` →
+	* `cid` → `bg` → `br`. The order of keys in the input object does not
+	* affect the firing order.
+	*
+	* A `sid` change resets the dedup baseline.
 	*
 	* @param data - The data to update.
 	*/
@@ -1139,16 +1649,44 @@ var CmcdReporter = class {
 			...data,
 			msd: void 0
 		};
+		for (const entry of STATE_FIELDS) if (entry.field in data && !entry.equal(this.data[entry.field], this.lastEmitted[entry.field])) this.recordEvent(entry.event);
 	}
 	/**
 	* Records an event. Called by the player when an event occurs.
 	*
+	* For state-change events (`PLAY_STATE`, `PLAYBACK_RATE`, `CONTENT_ID`,
+	* `BACKGROUNDED_MODE`, `BITRATE_CHANGE`), this method:
+	* 1. Persists the dedup field from `data` (if present) into the reporter's
+	*    persistent data store — equivalent to a write-through `update()`.
+	* 2. Drops the event entirely if the dedup field has no value after the
+	*    write-through (never set, or cleared via `update({ field: undefined })`).
+	*    State-change events without their required field would violate CTA-5004-B.
+	* 3. Suppresses the event if the field's current value matches the
+	*    last-emitted value (no state transition).
+	*
+	* 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).
+	*
 	* @param type - The type of event to record.
 	* @param data - Additional data to record with the event. This data
-	*               only applies to this event report. Persistent data should
-	*               be updated using `update()`.
+	*               only applies to this event report, except for the dedup
+	*               field of a state-change event, which is also persisted
+	*               into the reporter's data store.
 	*/
 	recordEvent(type, data = {}) {
+		const entry = STATE_FIELDS_BY_EVENT.get(type);
+		if (entry) {
+			const field = entry.field;
+			const incoming = data[field];
+			if (incoming !== void 0) Object.assign(this.data, { [field]: incoming });
+			const current = this.data[field];
+			if (current === void 0) return;
+			if (entry.equal(current, this.lastEmitted[field])) return;
+			Object.assign(this.lastEmitted, { [field]: entry.snapshot(current) });
+		}
 		this.eventTargets.forEach((target, config) => {
 			this.recordTargetEvent(target, config, type, data);
 		});
@@ -1270,7 +1808,7 @@ var CmcdReporter = class {
 			...data,
 			sn: this.requestTarget.sn++
 		};
-		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, url.origin);
+		const options = createEncodingOptions(CMCD_REQUEST_MODE, this.config, report.url);
 		if (!isNaN(this.msd) && !this.requestTarget.msdSent) {
 			cmcdData.msd = this.msd;
 			this.requestTarget.msdSent = true;
@@ -1351,6 +1889,7 @@ var CmcdReporter = class {
 	resetSession() {
 		this.eventTargets.forEach((target) => target.sn = 0);
 		this.requestTarget.sn = 0;
+		this.lastEmitted = {};
 	}
 };
 
@@ -1680,9 +2219,9 @@ function validateCmcdStructure(data, options) {
 			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.",
+		for (const [eventType, requiredField] of CMCD_STATE_EVENT_FIELDS) if (data["e"] === eventType && !(requiredField in data)) issues.push({
+			key: requiredField,
+			message: `State-change event (e="${eventType}") requires the "${requiredField}" key to be present.`,
 			severity: CMCD_VALIDATION_SEVERITY_ERROR
 		});
 		if (data["e"] === CMCD_EVENT_ERROR && !("ec" in data)) issues.push({
@@ -1860,6 +2399,7 @@ const CMCD_TOKEN_VALUES = {
 	e: [
 		"bc",
 		"ps",
+		"pr",
 		"e",
 		"t",
 		"c",
@@ -2377,5 +2917,5 @@ function extractHeaderRecord(headers) {
 }
 
 //#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_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 };
+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_PLAYBACK_RATE, 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_RECORDED_REPORT_MODE_EVENT, CMCD_RECORDED_REPORT_MODE_HEADER, CMCD_RECORDED_REPORT_MODE_QUERY, CMCD_RECORDED_REQUEST_TYPE_EVENT, CMCD_RECORDED_REQUEST_TYPE_MANIFEST, CMCD_RECORDED_REQUEST_TYPE_SEGMENT, CMCD_RECORDED_REQUEST_TYPE_UNKNOWN, 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, CmcdRecordedReportMode, CmcdRecordedRequestType, CmcdReportRecorder, CmcdReporter, CmcdReportingMode, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdValidationSeverity, appendCmcdHeaders, appendCmcdQuery, createFetchTransport, createXhrTransport, 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