@svta/cml-cmcd 2.4.1 → 2.6.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { SfBareItem, SfItem, SfToken } from "@svta/cml-structured-field-values";
-import { ExclusiveRecord, HttpRequest, HttpResponse, ValueOf, ValueOrArray } from "@svta/cml-utils";
+import { DeepReadonly, ExclusiveRecord, HttpRequest, HttpResponse, ValueOf, ValueOrArray } from "@svta/cml-utils";
 
 //#region src/CmcdEventType.d.ts
 
@@ -206,9 +206,17 @@ type CmcdEventType = ValueOf<typeof CmcdEventType>;
 * revisions to this specification. Clients SHOULD use a reverse-DNS
 * syntax when defining their own prefix.
 *
+* The type requires a lowercase hyphenated string. At runtime a key
+* must also satisfy {@link isCmcdCustomKey} — a lowercase first
+* letter, then characters from `a-z 0-9 . -`, with a hyphen that is
+* neither the first nor the last character — the subset of the CMCD
+* custom-key grammar that survives RFC 8941 key serialization. Keys
+* failing it are dropped during preparation. Lowercase reverse-DNS
+* names satisfy all constraints.
+*
 * @public
 */
-type CmcdCustomKey = `${string}-${string}`;
+type CmcdCustomKey = Lowercase<`${string}-${string}`>;
 //#endregion
 //#region src/CmcdCustomValue.d.ts
 /**
@@ -1376,9 +1384,10 @@ type CmcdHeaderMap = Record<CmcdHeaderField, CmcdKey[]>;
 */
 type CmcdEncodeOptions = {
   /**
-  * The version of the CMCD specification to use.
+  * The version of the CMCD specification to use. If not provided, the version
+  * is inferred from the data's `v` key, defaulting to `CMCD_V2`.
   *
-  * @defaultValue `1`
+  * @defaultValue `CMCD_V2`
   */
   version?: CmcdVersion;
   /**
@@ -1530,6 +1539,32 @@ declare const CMCD_PARAM = "CMCD";
 */
 declare const CMCD_REQUEST_KEYS: readonly ["ab", "bg", "bl", "br", "bs", "bsa", "bsd", "bsda", "cdn", "cid", "cs", "d", "dfa", "dl", "ec", "lab", "lb", "ltc", "msd", "mtp", "nor", "nr", "ot", "pb", "pr", "pt", "rtp", "sf", "sid", "sn", "st", "sta", "su", "tab", "tb", "tbl", "tpb", "v"];
 //#endregion
+//#region src/CMCD_REQUEST_PROVENANCE.d.ts
+/**
+* The `customData` key under which `CmcdReporter.createRequestReport()`
+* stamps session provenance on every request it returns.
+*
+* The value is a frozen `CmcdRequestProvenance` record: `sid` names the
+* session that issued the request, `cid` is the content id in effect when
+* the request was issued, and `data` carries the request's per-call data
+* as an encoded CMCD string. `CmcdReporter.recordResponseReceived()` reads
+* the record to attribute a late response to its session and to rebuild
+* the request-time report keys.
+* Spread and `Object.assign` carry the record through ordinary request
+* clones, but `JSON.stringify` and structured clone drop symbol-keyed
+* properties: read the value before such a boundary and restore it
+* afterward. The record itself survives JSON, and attribution is by the
+* `sid` value rather than object identity, so a revived plain-object copy
+* attributes exactly. A record naming a `sid` the reporter does not retain
+* drops the response rather than relabeling it.
+*
+* Backed by the symbol registry so duplicated copies of this library in
+* one bundle interoperate. The registry key is stable across versions.
+*
+* @public
+*/
+declare const CMCD_REQUEST_PROVENANCE: unique symbol;
+//#endregion
 //#region src/CMCD_RESPONSE_KEYS.d.ts
 /**
 * CMCD v2 - Response-only and timing keys.
@@ -1694,8 +1729,102 @@ type CmcdDecodeOptions = {
   * @defaultValue false
   */
   convertToLatest?: boolean;
+  /**
+  * Controls how RFC 8941 token values are represented in the decoded
+  * data. When omitted, tokens are reduced to plain strings, which cannot
+  * be told apart from string values on re-encoding. `true` decodes
+  * tokens as registry `Symbol`s and `false` as `SfToken` instances;
+  * either preserved representation re-encodes as a bare token, so a
+  * decode/encode round trip keeps the wire bytes.
+  */
+  useSymbol?: boolean;
+};
+//#endregion
+//#region src/CmcdTransformRequest.d.ts
+/**
+* The media request handed to a report transform, as a read-only view.
+*
+* The request is context only. A transform reads it to decide what to do with
+* the report and must not mutate it: it belongs to the caller, which may still
+* be using it. Every member is `readonly`, and `customData` is readonly at
+* every depth, so nested values cannot be written either.
+*
+* By default `customData` values are `unknown` rather than `any`, because the
+* library cannot know the player's shape. Narrow with a cast or bracket access
+* to read player-specific fields:
+*
+* ```ts
+* transform: (data, request) =>
+* 	request?.customData?.['requestType'] === 'segment' ? data : null
+* ```
+*
+* Supply `C` to describe the player's own `customData` instead and those reads
+* become typed dot access. Annotating one transform is enough: the reporter
+* infers `C` for every other transform in the same configuration.
+*
+* ```ts
+* type PlayerData = { requestType: string; };
+*
+* const segmentsOnly: CmcdEventReportTransform<PlayerData> = (data, request) =>
+* 	request?.customData?.requestType === 'segment' ? data : null
+* ```
+*
+* `C` is applied through {@link DeepReadonly}, so describing a nested shape
+* does not trade the no-mutation guarantee for typed reads.
+*
+* Two limits are worth knowing. A mutable body such as `FormData` or
+* `URLSearchParams` has mutating methods of its own that no type can block, and
+* JavaScript callers get no enforcement at all. Mutating the request through
+* either route is unsupported, and the outgoing report may reflect it.
+*
+* @typeParam C - The shape of the player's `customData`. Defaults to
+*                `Record<string, unknown>`.
+*
+* @public
+*/
+type CmcdTransformRequest<C = Record<string, unknown>> = Readonly<Omit<HttpRequest, "customData" | "headers">> & {
+  /**
+  * The headers associated with the request.
+  */
+  readonly headers?: Readonly<Record<string, string>>;
+  /**
+  * Any custom data the caller attached to the request, including the
+  * player's own fields.
+  */
+  readonly customData?: DeepReadonly<C>;
 };
 //#endregion
+//#region src/CmcdEventReportTransform.d.ts
+/**
+* Transforms an event-mode CMCD report before it is queued for its
+* target.
+*
+* Return the data to continue, or `null` to cancel the report. The
+* `data` argument is a per-target copy, so mutating it in place affects
+* neither the reporter's persistent data nor the reports bound for
+* other targets.
+*
+* The `request` argument is the media request that triggered the event
+* when one exists (events recorded via
+* {@link CmcdReporter.recordResponseReceived}), otherwise `undefined`.
+* It is a read-only view, provided as context only and not to be
+* mutated; see {@link CmcdTransformRequest}.
+*
+* The reporter re-stamps `e` and `sid`, and assigns `sn` and `msd`,
+* after this function returns, so values written to those keys are
+* overwritten.
+*
+* Must not throw. Exceptions propagate to the caller that recorded the
+* event, which for time-interval events is the interval timer.
+*
+* @typeParam C - The shape of the player's `customData` on the request.
+*                Defaults to `Record<string, unknown>`, whose values are
+*                `unknown` and read with bracket access.
+*
+* @public
+*/
+type CmcdEventReportTransform<C = Record<string, unknown>> = (data: Cmcd, request: CmcdTransformRequest<C> | undefined) => Cmcd | null;
+//#endregion
 //#region src/CmcdReportConfig.d.ts
 /**
 * Configuration for a CMCD report.
@@ -1723,9 +1852,12 @@ type CmcdReportConfig = {
 /**
 * Configuration for a CMCD event report.
 *
+* @typeParam C - The shape of the player's `customData` on the request that
+*                triggered the event. Defaults to `Record<string, unknown>`.
+*
 * @public
 */
-type CmcdEventReportConfig = CmcdReportConfig & {
+type CmcdEventReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
   /**
   * The version of the CMCD protocol to use. Must be
   * version 2 or higher for event reporting.
@@ -1759,6 +1891,21 @@ type CmcdEventReportConfig = CmcdReportConfig & {
   * @defaultValue `1`
   */
   batchSize?: number;
+  /**
+  * Transform applied to each of this target's event reports before
+  * it is queued. Return the data to continue, or `null` to cancel
+  * the report for this target.
+  *
+  * Scoped to this target only: targets that share a collector URL
+  * each run their own transform, and a report cancelled here is
+  * still sent to other targets that accept the event.
+  *
+  * @defaultValue `undefined`
+  *
+  * @example
+  * {@includeCode ../test/CmcdReporter.test.ts#example-transform}
+  */
+  transform?: CmcdEventReportTransform<C>;
 };
 //#endregion
 //#region src/CmcdEventsValidationResult.d.ts
@@ -2098,6 +2245,32 @@ declare class CmcdReportRecorder {
   waitForEvents(options?: CmcdReportRecorderWaitOptions): Promise<CmcdRecordedReport[]>;
 }
 //#endregion
+//#region src/CmcdRequestReportTransform.d.ts
+/**
+* Transforms a request-mode CMCD report before it is applied to the
+* outgoing request.
+*
+* Return the data to continue, or `null` to skip CMCD decoration for
+* this request entirely. The `data` argument is a per-report copy, so
+* mutating it in place never affects the reporter's persistent data.
+* The `request` argument is the request passed to
+* `createRequestReport()`, as a read-only view. It is context only and
+* must not be mutated; see {@link CmcdTransformRequest}.
+*
+* The reporter re-stamps `sid` and assigns `sn` and `msd` after this
+* function returns, so values written to those keys are overwritten.
+*
+* Must not throw. Exceptions propagate to the `createRequestReport()`
+* caller.
+*
+* @typeParam C - The shape of the player's `customData` on the request.
+*                Defaults to `Record<string, unknown>`, whose values are
+*                `unknown` and read with bracket access.
+*
+* @public
+*/
+type CmcdRequestReportTransform<C = Record<string, unknown>> = (data: Cmcd, request: CmcdTransformRequest<C>) => Cmcd | null;
+//#endregion
 //#region src/CmcdTransmissionMode.d.ts
 /**
 * CMCD `query` transmission mode.
@@ -2151,24 +2324,60 @@ type CmcdTransmissionMode = ValueOf<typeof CmcdTransmissionMode>;
 /**
 * Configuration for a CMCD request report.
 *
+* @typeParam C - The shape of the player's `customData` on the requests
+*                passed to {@link CmcdReporter.createRequestReport}.
+*                Defaults to `Record<string, unknown>`.
+*
 * @public
 */
-type CmcdRequestReportConfig = CmcdReportConfig & {
+type CmcdRequestReportConfig<C = Record<string, unknown>> = CmcdReportConfig & {
   /**
   * The transmission mode to use.
   *
   * @defaultValue `CmcdTransmissionMode.QUERY`
   */
   transmissionMode?: CmcdTransmissionMode;
+  /**
+  * A map of CMCD header fields to the custom keys that should be
+  * emitted in them when the transmission mode is
+  * `CmcdTransmissionMode.HEADERS`. Custom keys not listed in any
+  * shard are emitted in the `CMCD-Request` header. Standard keys
+  * have fixed shards per the CMCD specification and cannot be
+  * re-routed. Has no effect in query transmission mode or on event
+  * reports.
+  *
+  * @defaultValue `undefined`
+  */
+  customHeaderMap?: Partial<CmcdHeaderMap>;
+  /**
+  * Transform applied to each request-mode report before encoding.
+  * Return the data to continue, or `null` to skip CMCD decoration
+  * for that request.
+  *
+  * Applies only to reports created by
+  * {@link CmcdReporter.createRequestReport}. To transform event
+  * reports, set `transform` on the event target instead.
+  *
+  * @defaultValue `undefined`
+  *
+  * @example
+  * {@includeCode ../test/CmcdReporter.test.ts#example-transform}
+  */
+  transform?: CmcdRequestReportTransform<C>;
 };
 //#endregion
 //#region src/CmcdReporterConfig.d.ts
 /**
 * Configuration for a CMCD reporting component.
 *
+* @typeParam C - The shape of the player's `customData` on the requests this
+*                reporter sees. Annotating a single `transform` is enough for
+*                the rest of the configuration to infer it. Defaults to
+*                `Record<string, unknown>`.
+*
 * @public
 */
-type CmcdReporterConfig = CmcdRequestReportConfig & {
+type CmcdReporterConfig<C = Record<string, unknown>> = CmcdRequestReportConfig<C> & {
   /**
   * The session ID. If not provided, a new random session ID will be generated.
   *
@@ -2186,18 +2395,90 @@ type CmcdReporterConfig = CmcdRequestReportConfig & {
   *
   * @defaultValue `undefined`
   */
-  eventTargets?: CmcdEventReportConfig[];
+  eventTargets?: CmcdEventReportConfig<C>[];
+  /**
+  * The number of ended sessions the reporter retains state for, in
+  * addition to the current one. Retained sessions let a response that
+  * completes after a `sid` change report under the session that issued
+  * its request, with that session's data snapshot and sequence numbers.
+  * `0` retains nothing, so stale responses are dropped. `Infinity` never
+  * evicts, which also retains every session's unsent report queues.
+  * Numbers are floored; every other input falls back to the default.
+  *
+  * @defaultValue 2
+  */
+  sessionRetention?: number;
+};
+//#endregion
+//#region src/CmcdReporterCustomData.d.ts
+/**
+* The `customData` a {@link CmcdReporter} method accepts, for a reporter typed
+* `C`.
+*
+* A reporter left on the default `C` constrains nothing, so requests carrying
+* any `customData` are accepted exactly as they were before `C` existed. A
+* reporter given a concrete `C` requires the request to satisfy it, because its
+* transforms read `customData` as `C` and would otherwise be handed a value
+* their type does not describe.
+*
+* @typeParam C - The reporter's `customData` type.
+*
+* @public
+*/
+type CmcdReporterCustomData<C> = Record<string, unknown> extends C ? any : C;
+//#endregion
+//#region src/CmcdRequestProvenance.d.ts
+/**
+* The session-provenance record `CmcdReporter.createRequestReport()` stamps
+* on `customData` under `CMCD_REQUEST_PROVENANCE`.
+*
+* `sid` names the session that issued the request and is the attribution
+* key: `CmcdReporter.recordResponseReceived()` resolves it against the
+* reporter's retained sessions by value, never by object identity, so a
+* copy of the record that crosses a JSON boundary attributes exactly once
+* restored. Session identity rides on the caller's own `sid` values, which
+* CTA-5004-B expects to be unique per playback session: reusing a `sid`
+* replaces the retained namesake, so late responses of the replaced
+* session relabel onto the replacement.
+*
+* `cid` is the content id that was current when the record was minted. A
+* `RESPONSE_RECEIVED` event reports it in place of the session's current
+* `cid`, so a response that completes after a content change keeps the
+* meaning it had when the request was issued.
+*
+* `data` is the per-call data the request was created with, encoded as a
+* CMCD string. The reporter decodes it to rebuild the request-time report
+* keys for a `RESPONSE_RECEIVED` event, so the caller's inputs survive any
+* boundary the record itself is carried across. It is captured before the
+* request `transform` and key filter run, so it also rides requests the
+* reporter does not decorate.
+*
+* The reporter freezes every record it mints. The record is constructible:
+* a hand-built request may carry `{ sid }` to attribute to that session.
+* A record naming a `sid` the reporter does not retain is dropped.
+*
+* @public
+*/
+type CmcdRequestProvenance = {
+  readonly sid: string;
+  readonly cid?: string;
+  readonly data?: string;
 };
 //#endregion
 //#region src/CmcdRequestReport.d.ts
 /**
 * A report of a CMCD request.
 *
+* The provenance member is optional so the type stays constructible by
+* consumers that build or mock request reports; every request returned by
+* `CmcdReporter.createRequestReport()` carries it.
+*
 * @public
 */
 type CmcdRequestReport<D = unknown> = HttpRequest & {
   customData: {
     cmcd: Cmcd;
+    [CMCD_REQUEST_PROVENANCE]?: CmcdRequestProvenance;
   } & D;
   headers: Record<string, string>;
 };
@@ -2206,18 +2487,37 @@ type CmcdRequestReport<D = unknown> = HttpRequest & {
 /**
 * 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
 */
-declare class CmcdReporter {
+declare class CmcdReporter<C = Record<string, unknown>> {
   private timeOrigin;
-  private data;
   private config;
-  private msd;
-  private eventTargets;
-  private lastEmitted;
-  private requestTarget;
+  /**
+  * Retained sessions keyed by `sid`, insertion-ordered oldest first, the
+  * current session last. The ended-session count is capped by
+  * `config.sessionRetention`. CTA-5004-B expects a `sid` to be unique
+  * per playback session; a reused one replaces its retained namesake at
+  * the newest position (see `startSession()`).
+  */
+  private sessions;
+  private session;
+  /**
+  * Armed time-interval timers by target config. Timers outlive session
+  * changes (their callbacks report into whichever session is current at
+  * fire time), so they live on the reporter rather than the session.
+  */
+  private intervals;
+  private started;
   private requester;
   /**
   * Creates a new CMCD reporter.
@@ -2227,10 +2527,15 @@ declare class CmcdReporter {
   *                    The default is a simple wrapper around the
   *                    native `fetch` API.
   */
-  constructor(config: Partial<CmcdReporterConfig>, requester?: (request: HttpRequest) => Promise<{
+  constructor(config: Partial<CmcdReporterConfig<C>>, requester?: (request: HttpRequest) => Promise<{
     status: number;
   }>);
   /**
+  * Creates the state for a new session: fresh counters, gates, queues and
+  * dedup baseline for every configured target.
+  */
+  private createSession;
+  /**
   * Starts the CMCD reporter. Called by the player when the reporter is enabled.
   *
   * Note: This fires an initial time-interval event immediately (synchronously)
@@ -2239,6 +2544,12 @@ declare class CmcdReporter {
   */
   start(): void;
   /**
+  * Arms the time-interval timer for an event target when its config calls
+  * for one. Returns whether a timer was armed. The callback reports into
+  * whichever session is current when it fires.
+  */
+  private armInterval;
+  /**
   * Stops the CMCD reporter. Called by the player when the reporter is disabled.
   *
   * @param flush - Whether to flush the event targets.
@@ -2278,10 +2589,36 @@ declare class CmcdReporter {
   *
   * A `sid` change resets the dedup baseline.
   *
+  * `sid` and `msd` are session-owned: the reporter tracks them itself and
+  * stamps them onto every outgoing report, so this method is the only way
+  * to change them. A per-call value on {@link CmcdReporter.recordEvent},
+  * {@link CmcdReporter.createRequestReport}, or
+  * {@link CmcdReporter.recordResponseReceived} has no effect; response
+  * attribution is by the provenance record alone.
+  * `msd` must be a finite number of milliseconds between `0` and
+  * `999_999_999_999_999` (the RFC 8941 integer maximum); it is rounded to
+  * the nearest integer, and invalid values are ignored.
+  *
   * @param data - The data to update.
   */
   update(data: Partial<Cmcd>): void;
   /**
+  * Starts a new session: the current one is archived in place for stale
+  * attribution, a fresh one takes over, ended sessions are drained, and
+  * the oldest are evicted beyond the configured retention.
+  *
+  * The data store is carried over, and the archived snapshot is frozen:
+  * the ended session's value graph is detached first, so nested values
+  * the caller handed to `update()` can no longer mutate it, and the new
+  * session starts from a shallow copy of the detached graph, so `cid`,
+  * `br`, custom keys and the rest survive a `sid` change as they always
+  * have. Sessions are keyed by `sid`, which CTA-5004-B expects to be
+  * unique per playback session: reusing one replaces the retained
+  * namesake, whose remaining state dies as if evicted and whose late
+  * responses relabel onto the replacement.
+  */
+  private startSession;
+  /**
   * Records an event. Called by the player when an event occurs.
   *
   * For state-change events (`PLAY_STATE`, `PLAYBACK_RATE`, `CONTENT_ID`,
@@ -2314,10 +2651,28 @@ declare class CmcdReporter {
   * @param data - Additional data to record with the event. This data
   *               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.
+  *               into the reporter's data store. Session-owned keys
+  *               (`sid`, `msd`) supplied here are ignored; the reporter
+  *               stamps its own values.
   */
   recordEvent(type: CmcdEventType, data?: Partial<Cmcd>): void;
   /**
+  * Records an event across every configured target of a session, applying
+  * state-change dedup once before per-target fan-out.
+  *
+  * @param session - The session the event belongs to. Everything the event
+  *                  touches (data store, dedup baseline, counters, queues)
+  *                  is that session's; only `recordResponseReceived()` ever
+  *                  passes an archived one.
+  * @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`.
+  */
+  private emitEvent;
+  /**
   * Records an event for a target. Called by the reporter when an event occurs.
   *
   * @param target - The target to record the event for.
@@ -2326,9 +2681,28 @@ declare class CmcdReporter {
   * @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`.
   */
   private recordTargetEvent;
   /**
+  * Stamps the reporter-owned fields on a finished event report, encodes it,
+  * and pushes the wire line to the target's queue.
+  *
+  * Called after any transform has run, so a transform cannot bypass the
+  * target's `events` filter via `e`, break `sn` continuity, or substitute
+  * the session identity carried by `sid` and `msd`. Encoding here means a
+  * report that cannot serialize throws inside the recording call that
+  * produced it, instead of rejecting the batch send and re-queueing
+  * forever.
+  *
+  * @param target - The target to queue the report for.
+  * @param config - The configuration for the target.
+  * @param report - The finished report data.
+  * @param type - The type of event being reported.
+  */
+  private queueTargetEvent;
+  /**
   * Records a response-received event. Called by the player when a media
   * request response has been fully received.
   *
@@ -2343,14 +2717,63 @@ declare class CmcdReporter {
   * 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 reads only the provenance record 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}.
+  *
+  * The event is attributed to the session that issued the request, and to
+  * nothing else: the provenance record that
+  * {@link CmcdReporter.createRequestReport} stored on the request's
+  * `customData` (under {@link CMCD_REQUEST_PROVENANCE}) selects the
+  * session by its `sid`, or the response is dropped rather than
+  * relabeled. There is no other key: a record lost to a serialization
+  * boundary (and not restored; see the bridge notes on
+  * {@link CMCD_REQUEST_PROVENANCE}) and a session no longer retained
+  * (see `CmcdReporterConfig.sessionRetention`) both drop, and a per-call
+  * `data.sid` cannot substitute. The record is honored wherever its
+  * `sid` resolves: a request decorated by another reporter configured
+  * with the same session attributes here, as does a hand-built record.
+  * A response that completes after a `sid` change reports under its own
+  * retained session, with that session's data snapshot and sequence
+  * numbers.
+  *
+  * Request-time report keys come from the record's encoded per-call
+  * `data` snapshot, decoded fresh per response, and the record's `cid`
+  * reports in place of the session's current one, so a response that
+  * completes after a mid-session content change keeps the meaning it
+  * had when its request was issued.
+  *
+  * @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.
+  *               Session-owned keys (`sid`, `msd`) supplied here are
+  *               ignored; attribution is by the provenance record alone.
   */
-  recordResponseReceived(response: HttpResponse<HttpRequest<{
+  recordResponseReceived<RD extends CmcdReporterCustomData<C> = C>(response: HttpResponse<HttpRequest<RD & {
     cmcd?: Cmcd;
+    [CMCD_REQUEST_PROVENANCE]?: CmcdRequestProvenance;
   }>>, data?: Partial<Cmcd>): void;
   /**
+  * Resolves the session a response belongs to: the provenance record's
+  * `sid` names one of this reporter's retained sessions, or the response
+  * is dropped. There is no other key — a record that was lost, or that
+  * names an evicted or never-seen `sid`, resolves nothing, and
+  * attributing it anywhere else would relabel it. The `sid` is read
+  * structurally, so a JSON-revived copy of a record attributes exactly,
+  * and a hand-built record naming a retained session is honored.
+  */
+  private resolveSession;
+  /**
   * Applies the CMCD request report data to the request. Called by the player
   * before sending the request.
   *
@@ -2367,16 +2790,36 @@ declare class CmcdReporter {
   */
   isRequestReportingEnabled(): boolean;
   /**
+  * The provenance record to stamp on a returned request: the session's
+  * frozen base record, extended with the caller's per-call data encoded
+  * as a CMCD string when there is any. Requests without per-call data
+  * share the base record, so decoration stays a single property write.
+  * The snapshot never contains reporter-stamped fields, and a value that
+  * cannot encode contributes no snapshot rather than failing the
+  * request; its response still attributes and reports derived keys over
+  * session data, matching `decodeSnapshot()`'s tolerance on the read
+  * side.
+  */
+  private createRequestProvenance;
+  /**
   * 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
   *               should be updated using `update()`.
   * @returns The request with the CMCD request report applied.
   */
-  createRequestReport<R extends HttpRequest = HttpRequest>(request: R, data?: Partial<Cmcd>): R & CmcdRequestReport<R["customData"]>;
+  createRequestReport<R extends HttpRequest<CmcdReporterCustomData<C>> = HttpRequest<C>>(request: R, data?: Partial<Cmcd>): R & CmcdRequestReport<R["customData"]>;
   /**
   * Processes the event targets. Called by the reporter when an event occurs.
   *
@@ -2387,23 +2830,24 @@ declare class CmcdReporter {
   * Sends an event report. Called by the reporter when a batch is ready to be sent.
   *
   * @param config - The target config to send the event report to.
-  * @param data - The data to send in the event report.
+  * @param data - The encoded report lines to send in the event report.
   */
   private sendEventReport;
   /**
-  * Cancels the time-interval timer for an event target and clears the stored id.
-  * Safe to call when no timer is armed (clearInterval(undefined) is a no-op).
+  * Cancels the time-interval timer for an event target config and clears the
+  * stored id. Safe to call when no timer is armed (clearInterval(undefined)
+  * is a no-op).
   */
   private disarmInterval;
   /**
-  * Permanently removes an event target: cancels its timer and removes it from the
-  * eventTargets map. Used when the collector signals the target is gone (HTTP 410).
+  * Silences an event target URL for the remainder of its session: drops the
+  * queues and blocks further enqueues for every config in the session that
+  * reports to the URL, per CTA-5004-B's per-target-URL suppression scope,
+  * and cancels their timers when the session is the live one. Used when the
+  * collector signals the target is gone (HTTP 410). A session started after
+  * the disposal is unaffected, since it gets fresh target state.
   */
   private disposeEventTarget;
-  /**
-  * Resets the session related data. Called when the session ID changes.
-  */
-  private resetSession;
 }
 //#endregion
 //#region src/CmcdValidationOptions.d.ts
@@ -2572,7 +3016,10 @@ declare function groupCmcdHeaders(cmcd: Cmcd, customHeaderMap?: Partial<CmcdHead
 //#endregion
 //#region src/isCmcdCustomKey.d.ts
 /**
-* 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.
 *
@@ -2683,6 +3130,9 @@ declare function isCmcdV2Data(data: CmcdData): data is CmcdV2Data;
 * @param options - Options for encoding.
 *
 * @public
+*
+* @example
+* {@includeCode ../test/prepareCmcdData.test.ts#example}
 */
 declare function prepareCmcdData(obj: Record<string, any>, options?: CmcdEncodeOptions): Cmcd;
 //#endregion
@@ -2910,5 +3360,5 @@ declare function validateCmcdStructure(data: Record<string, unknown>, options?:
 */
 declare function validateCmcdValues(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
 //#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_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, Cmcd, CmcdCustomKey, CmcdCustomValue, CmcdData, CmcdDataValidationResult, CmcdDecodeOptions, CmcdEncodeOptions, CmcdEvent, CmcdEventReportConfig, CmcdEventType, CmcdEventsValidationResult, CmcdFormatter, CmcdFormatterMap, CmcdFormatterOptions, CmcdHeaderField, CmcdHeaderKey, CmcdHeaderMap, CmcdHeaderValue, CmcdKey, CmcdObjectType, CmcdObjectTypeList, CmcdPlayerState, CmcdRecordedReport, CmcdRecordedReportMode, CmcdRecordedRequestType, CmcdReportConfig, CmcdReportRecorder, CmcdReportRecorderOptions, CmcdReportRecorderWaitOptions, CmcdReporter, CmcdReporterConfig, CmcdReportingMode, CmcdRequest, CmcdRequestDeliver, CmcdRequestKey, CmcdRequestReport, CmcdRequestReportConfig, CmcdResponse, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdTransportAdapter, CmcdV1, CmcdV1Data, CmcdV2Data, CmcdValidationIssue, CmcdValidationOptions, CmcdValidationResult, CmcdValidationSeverity, CmcdValue, CmcdVersion, 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 };
+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_REQUEST_PROVENANCE, CMCD_RESPONSE_KEYS, CMCD_SESSION, CMCD_STATUS, CMCD_V1, CMCD_V1_KEYS, CMCD_V2, CMCD_VALIDATION_SEVERITY_ERROR, CMCD_VALIDATION_SEVERITY_WARNING, Cmcd, CmcdCustomKey, CmcdCustomValue, CmcdData, CmcdDataValidationResult, CmcdDecodeOptions, CmcdEncodeOptions, CmcdEvent, CmcdEventReportConfig, CmcdEventReportTransform, CmcdEventType, CmcdEventsValidationResult, CmcdFormatter, CmcdFormatterMap, CmcdFormatterOptions, CmcdHeaderField, CmcdHeaderKey, CmcdHeaderMap, CmcdHeaderValue, CmcdKey, CmcdObjectType, CmcdObjectTypeList, CmcdPlayerState, CmcdRecordedReport, CmcdRecordedReportMode, CmcdRecordedRequestType, CmcdReportConfig, CmcdReportRecorder, CmcdReportRecorderOptions, CmcdReportRecorderWaitOptions, CmcdReporter, CmcdReporterConfig, CmcdReporterCustomData, CmcdReportingMode, CmcdRequest, CmcdRequestDeliver, CmcdRequestKey, CmcdRequestProvenance, CmcdRequestReport, CmcdRequestReportConfig, CmcdRequestReportTransform, CmcdResponse, CmcdStreamType, CmcdStreamingFormat, CmcdTransformRequest, CmcdTransmissionMode, CmcdTransportAdapter, CmcdV1, CmcdV1Data, CmcdV2Data, CmcdValidationIssue, CmcdValidationOptions, CmcdValidationResult, CmcdValidationSeverity, CmcdValue, CmcdVersion, 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.d.ts.map