@svta/cml-cmcd 2.1.1 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -4,11 +4,11 @@ import { ExclusiveRecord, HttpRequest, HttpResponse, ValueOf, ValueOrArray } fro
4
4
  //#region src/CmcdEventType.d.ts
5
5
 
6
6
  /**
7
- * CMCD event type for the 'br' key (bitrate change).
7
+ * CMCD event type for the 'bc' key (bitrate change).
8
8
  *
9
9
  * @public
10
10
  */
11
- declare const CMCD_EVENT_BITRATE_CHANGE: "br";
11
+ declare const CMCD_EVENT_BITRATE_CHANGE: "bc";
12
12
  /**
13
13
  * CMCD event type for the 'ps' key (play state change).
14
14
  *
@@ -1022,6 +1022,30 @@ declare const CmcdReportingMode: {
1022
1022
  */
1023
1023
  type CmcdReportingMode = ValueOf<typeof CmcdReportingMode>;
1024
1024
  //#endregion
1025
+ //#region src/CMCD_V1.d.ts
1026
+ /**
1027
+ * CMCD Version 1
1028
+ *
1029
+ * @public
1030
+ */
1031
+ declare const CMCD_V1: 1;
1032
+ //#endregion
1033
+ //#region src/CMCD_V2.d.ts
1034
+ /**
1035
+ * CMCD Version 2
1036
+ *
1037
+ * @public
1038
+ */
1039
+ declare const CMCD_V2: 2;
1040
+ //#endregion
1041
+ //#region src/CmcdVersion.d.ts
1042
+ /**
1043
+ * The version of the CMCD specification.
1044
+ *
1045
+ * @public
1046
+ */
1047
+ type CmcdVersion = typeof CMCD_V1 | typeof CMCD_V2;
1048
+ //#endregion
1025
1049
  //#region src/CmcdFormatterOptions.d.ts
1026
1050
  /**
1027
1051
  * Options for formatting CMCD data values.
@@ -1032,7 +1056,7 @@ type CmcdFormatterOptions = {
1032
1056
  /**
1033
1057
  * The version of the CMCD specification to use.
1034
1058
  */
1035
- version: number;
1059
+ version: CmcdVersion;
1036
1060
  /**
1037
1061
  * The reporting mode to use.
1038
1062
  */
@@ -1196,6 +1220,12 @@ declare const CmcdHeaderField: {
1196
1220
  * @public
1197
1221
  */
1198
1222
  type CmcdHeaderField = ValueOf<typeof CmcdHeaderField>;
1223
+ /**
1224
+ * All CMCD header fields as an array.
1225
+ *
1226
+ * @public
1227
+ */
1228
+ declare const CMCD_HEADER_FIELDS: readonly CmcdHeaderField[];
1199
1229
  //#endregion
1200
1230
  //#region src/CmcdHeaderMap.d.ts
1201
1231
  /**
@@ -1217,7 +1247,7 @@ type CmcdEncodeOptions = {
1217
1247
  *
1218
1248
  * @defaultValue `1`
1219
1249
  */
1220
- version?: number;
1250
+ version?: CmcdVersion;
1221
1251
  /**
1222
1252
  * The reporting mode to use.
1223
1253
  *
@@ -1284,6 +1314,73 @@ declare function appendCmcdHeaders(headers: Record<string, string>, cmcd: Cmcd,
1284
1314
  */
1285
1315
  declare function appendCmcdQuery(url: string, cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1286
1316
  //#endregion
1317
+ //#region src/CmcdData.d.ts
1318
+ /**
1319
+ * CMCD version 1 data.
1320
+ *
1321
+ * Overrides keys whose types differ in version 1 (e.g., `bl` and `br`
1322
+ * are plain integers instead of inner lists).
1323
+ *
1324
+ * @public
1325
+ */
1326
+ type CmcdV1Data = Omit<CmcdRequest, keyof CmcdV1 | "v"> & CmcdV1 & {
1327
+ v?: 1;
1328
+ };
1329
+ /**
1330
+ * CMCD version 2 data.
1331
+ *
1332
+ * Includes all request, event, and response mode keys with version 2
1333
+ * types.
1334
+ *
1335
+ * @public
1336
+ */
1337
+ type CmcdV2Data = Omit<Cmcd, "v"> & {
1338
+ v: 2;
1339
+ };
1340
+ /**
1341
+ * A CMCD data object that is either version 1 or version 2.
1342
+ *
1343
+ * The `v` property acts as a discriminator:
1344
+ *
1345
+ * - When `v` is `2`, the type narrows to {@link CmcdV2Data} with
1346
+ * inner-list values and event/response keys.
1347
+ * - When `v` is `1` or absent, the type narrows to {@link CmcdV1Data}
1348
+ * with scalar values.
1349
+ *
1350
+ * @example
1351
+ * ```ts
1352
+ * function process(data: CmcdData) {
1353
+ * if (data.v === 2) {
1354
+ * // data.bl is CmcdObjectTypeList | undefined
1355
+ * } else {
1356
+ * // data.bl is number | undefined
1357
+ * }
1358
+ * }
1359
+ * ```
1360
+ *
1361
+ * @public
1362
+ */
1363
+ type CmcdData = CmcdV1Data | CmcdV2Data;
1364
+ //#endregion
1365
+ //#region src/CmcdDecodeOptions.d.ts
1366
+ /**
1367
+ * Options for decoding CMCD data.
1368
+ *
1369
+ * @public
1370
+ */
1371
+ type CmcdDecodeOptions = {
1372
+ /**
1373
+ * When `true`, up-converts version 1 data to version 2 format by wrapping
1374
+ * scalar values in arrays for inner-list keys (e.g., `bl`, `br`, `mtp`).
1375
+ *
1376
+ * This ensures a consistent data shape regardless of the source version,
1377
+ * mirroring the down-conversion that occurs during encoding.
1378
+ *
1379
+ * @defaultValue false
1380
+ */
1381
+ convertToLatest?: boolean;
1382
+ };
1383
+ //#endregion
1287
1384
  //#region src/CMCD_DEFAULT_TIME_INTERVAL.d.ts
1288
1385
  /**
1289
1386
  * The default time interval in seconds when using using event mode
@@ -1320,6 +1417,10 @@ type CmcdRequestKey = keyof CmcdRequest | "nrr";
1320
1417
  /**
1321
1418
  * The map of CMCD keys to their appropriate header shard.
1322
1419
  *
1420
+ * Note: Event-only keys (e, ts, cen, h) and response-received keys
1421
+ * (rc, ttfb, ttlb, url, etc.) are intentionally absent. They are
1422
+ * transmitted via the event-mode POST body, not HTTP headers.
1423
+ *
1323
1424
  * @public
1324
1425
  */
1325
1426
  declare const CMCD_HEADER_MAP: Record<CmcdRequestKey | "nrr", CmcdHeaderField>;
@@ -1356,14 +1457,6 @@ declare const CMCD_REQUEST_KEYS: readonly ["ab", "bg", "bl", "br", "bs", "bsa",
1356
1457
  */
1357
1458
  declare const CMCD_RESPONSE_KEYS: readonly ["cmsdd", "cmsds", "rc", "smrt", "ttfb", "ttfbb", "ttlb", "url"];
1358
1459
  //#endregion
1359
- //#region src/CMCD_V1.d.ts
1360
- /**
1361
- * CMCD Version 1
1362
- *
1363
- * @public
1364
- */
1365
- declare const CMCD_V1: 1;
1366
- //#endregion
1367
1460
  //#region src/CMCD_V1_KEYS.d.ts
1368
1461
  /**
1369
1462
  * Defines the keys for CMCD (Common Media Client Data) version 1.
@@ -1372,22 +1465,6 @@ declare const CMCD_V1: 1;
1372
1465
  */
1373
1466
  declare const CMCD_V1_KEYS: readonly ["bl", "br", "bs", "cid", "d", "dl", "mtp", "nor", "nrr", "ot", "pr", "rtp", "sf", "sid", "st", "su", "tb", "v"];
1374
1467
  //#endregion
1375
- //#region src/CMCD_V2.d.ts
1376
- /**
1377
- * CMCD Version 2
1378
- *
1379
- * @public
1380
- */
1381
- declare const CMCD_V2: 2;
1382
- //#endregion
1383
- //#region src/CmcdVersion.d.ts
1384
- /**
1385
- * The version of the CMCD specification.
1386
- *
1387
- * @public
1388
- */
1389
- type CmcdVersion = typeof CMCD_V1 | typeof CMCD_V2;
1390
- //#endregion
1391
1468
  //#region src/CmcdReportConfig.d.ts
1392
1469
  /**
1393
1470
  * Configuration for a CMCD report.
@@ -1600,10 +1677,16 @@ declare class CmcdReporter {
1600
1677
  }>);
1601
1678
  /**
1602
1679
  * Starts the CMCD reporter. Called by the player when the reporter is enabled.
1680
+ *
1681
+ * Note: This fires an initial time-interval event immediately (synchronously)
1682
+ * before the first interval elapses. Ensure CMCD data (sid, cid, etc.) is
1683
+ * populated before calling start().
1603
1684
  */
1604
1685
  start(): void;
1605
1686
  /**
1606
1687
  * Stops the CMCD reporter. Called by the player when the reporter is disabled.
1688
+ *
1689
+ * @param flush - Whether to flush the event targets.
1607
1690
  */
1608
1691
  stop(flush?: boolean): void;
1609
1692
  /**
@@ -1627,6 +1710,16 @@ declare class CmcdReporter {
1627
1710
  * be updated using `update()`.
1628
1711
  */
1629
1712
  recordEvent(type: CmcdEventType, data?: Partial<Cmcd>): void;
1713
+ /**
1714
+ * Records an event for a target. Called by the reporter when an event occurs.
1715
+ *
1716
+ * @param target - The target to record the event for.
1717
+ * @param config - The configuration for the target.
1718
+ * @param type - The type of event to record.
1719
+ * @param data - Additional data to record with the event. This data
1720
+ * only applies to this event report. Persistent data should
1721
+ * be updated using `update()`.
1722
+ */
1630
1723
  private recordTargetEvent;
1631
1724
  /**
1632
1725
  * Records a response-received event. Called by the player when a media
@@ -1670,7 +1763,7 @@ declare class CmcdReporter {
1670
1763
  * Creates a new request with the CMCD request report data applied. Called by the player
1671
1764
  * before sending the request.
1672
1765
  *
1673
- * @param req - The request to apply the CMCD request report to.
1766
+ * @param request - The request to apply the CMCD request report to.
1674
1767
  * @param data - The data to apply to the request. This data only
1675
1768
  * applies to this request report. Persistent data
1676
1769
  * should be updated using `update()`.
@@ -1701,6 +1794,7 @@ declare class CmcdReporter {
1701
1794
  * Decode a CMCD string to an object.
1702
1795
  *
1703
1796
  * @param cmcd - The CMCD string to decode.
1797
+ * @param options - Options for decoding.
1704
1798
  *
1705
1799
  * @returns The decoded CMCD object.
1706
1800
  *
@@ -1709,7 +1803,10 @@ declare class CmcdReporter {
1709
1803
  * @example
1710
1804
  * {@includeCode ../test/decodeCmcd.test.ts#example}
1711
1805
  */
1712
- declare function decodeCmcd<T extends Cmcd = Cmcd>(cmcd: string): T;
1806
+ declare function decodeCmcd(cmcd: string, options: CmcdDecodeOptions & {
1807
+ convertToLatest: true;
1808
+ }): Cmcd;
1809
+ declare function decodeCmcd<T extends CmcdData = CmcdData>(cmcd: string, options?: CmcdDecodeOptions): T;
1713
1810
  //#endregion
1714
1811
  //#region src/encodeCmcd.d.ts
1715
1812
  /**
@@ -1732,6 +1829,7 @@ declare function encodeCmcd(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1732
1829
  * Decode CMCD data from request headers.
1733
1830
  *
1734
1831
  * @param headers - The request headers to decode.
1832
+ * @param options - Options for decoding.
1735
1833
  *
1736
1834
  * @returns The decoded CMCD data.
1737
1835
  *
@@ -1740,13 +1838,17 @@ declare function encodeCmcd(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1740
1838
  * @example
1741
1839
  * {@includeCode ../test/fromCmcdHeaders.test.ts#example}
1742
1840
  */
1743
- declare function fromCmcdHeaders(headers: Record<string, string> | Headers): Cmcd;
1841
+ declare function fromCmcdHeaders(headers: Record<string, string> | Headers, options: CmcdDecodeOptions & {
1842
+ convertToLatest: true;
1843
+ }): Cmcd;
1844
+ declare function fromCmcdHeaders(headers: Record<string, string> | Headers, options?: CmcdDecodeOptions): CmcdData;
1744
1845
  //#endregion
1745
1846
  //#region src/fromCmcdQuery.d.ts
1746
1847
  /**
1747
1848
  * Decode CMCD data from a query string.
1748
1849
  *
1749
1850
  * @param query - The query string to decode.
1851
+ * @param options - Options for decoding.
1750
1852
  *
1751
1853
  * @returns The decoded CMCD data.
1752
1854
  *
@@ -1755,13 +1857,17 @@ declare function fromCmcdHeaders(headers: Record<string, string> | Headers): Cmc
1755
1857
  * @example
1756
1858
  * {@includeCode ../test/fromCmcdQuery.test.ts#example}
1757
1859
  */
1758
- declare function fromCmcdQuery(query: string | URLSearchParams): Cmcd;
1860
+ declare function fromCmcdQuery(query: string | URLSearchParams, options: CmcdDecodeOptions & {
1861
+ convertToLatest: true;
1862
+ }): Cmcd;
1863
+ declare function fromCmcdQuery(query: string | URLSearchParams, options?: CmcdDecodeOptions): CmcdData;
1759
1864
  //#endregion
1760
1865
  //#region src/fromCmcdUrl.d.ts
1761
1866
  /**
1762
1867
  * Decode CMCD data from a url encoded string.
1763
1868
  *
1764
1869
  * @param url - The url encoded string to decode.
1870
+ * @param options - Options for decoding.
1765
1871
  *
1766
1872
  * @returns The decoded CMCD data.
1767
1873
  *
@@ -1770,7 +1876,10 @@ declare function fromCmcdQuery(query: string | URLSearchParams): Cmcd;
1770
1876
  * @example
1771
1877
  * {@includeCode ../test/fromCmcdUrl.test.ts#example}
1772
1878
  */
1773
- declare function fromCmcdUrl(url: string): Cmcd;
1879
+ declare function fromCmcdUrl(url: string, options: CmcdDecodeOptions & {
1880
+ convertToLatest: true;
1881
+ }): Cmcd;
1882
+ declare function fromCmcdUrl(url: string, options?: CmcdDecodeOptions): CmcdData;
1774
1883
  //#endregion
1775
1884
  //#region src/groupCmcdHeaders.d.ts
1776
1885
  /**
@@ -1842,6 +1951,21 @@ declare function isCmcdRequestKey(key: string): key is keyof Cmcd;
1842
1951
  */
1843
1952
  declare function isCmcdResponseReceivedKey(key: string): key is keyof Cmcd;
1844
1953
  //#endregion
1954
+ //#region src/isCmcdV1Data.d.ts
1955
+ /**
1956
+ * Check if a CMCD data object is version 1.
1957
+ *
1958
+ * @param data - The CMCD data object to check.
1959
+ *
1960
+ * @returns `true` if the data is version 1, `false` otherwise.
1961
+ *
1962
+ * @public
1963
+ *
1964
+ * @example
1965
+ * {@includeCode ../test/isCmcdV1Data.test.ts#example}
1966
+ */
1967
+ declare function isCmcdV1Data(data: CmcdData): data is CmcdV1Data;
1968
+ //#endregion
1845
1969
  //#region src/isCmcdV1Key.d.ts
1846
1970
  /**
1847
1971
  * Filter function for CMCD v1 keys.
@@ -1857,6 +1981,21 @@ declare function isCmcdResponseReceivedKey(key: string): key is keyof Cmcd;
1857
1981
  */
1858
1982
  declare function isCmcdV1Key(key: string): key is CmcdKey;
1859
1983
  //#endregion
1984
+ //#region src/isCmcdV2Data.d.ts
1985
+ /**
1986
+ * Check if a CMCD data object is version 2.
1987
+ *
1988
+ * @param data - The CMCD data object to check.
1989
+ *
1990
+ * @returns `true` if the data is version 2, `false` otherwise.
1991
+ *
1992
+ * @public
1993
+ *
1994
+ * @example
1995
+ * {@includeCode ../test/isCmcdV2Data.test.ts#example}
1996
+ */
1997
+ declare function isCmcdV2Data(data: CmcdData): data is CmcdV2Data;
1998
+ //#endregion
1860
1999
  //#region src/prepareCmcdData.d.ts
1861
2000
  /**
1862
2001
  * Convert a generic object to CMCD data.
@@ -1925,5 +2064,247 @@ declare function toCmcdUrl(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1925
2064
  */
1926
2065
  declare function toCmcdValue<V extends SfBareItem, P>(value: V, params?: P): SfItem<V, P>;
1927
2066
  //#endregion
1928
- 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, Cmcd, CmcdCustomKey, CmcdCustomValue, CmcdEncodeOptions, CmcdEvent, CmcdEventReportConfig, CmcdEventType, CmcdFormatter, CmcdFormatterMap, CmcdFormatterOptions, CmcdHeaderField, CmcdHeaderKey, CmcdHeaderMap, CmcdHeaderValue, CmcdKey, CmcdObjectType, CmcdObjectTypeList, CmcdPlayerState, CmcdReportConfig, CmcdReporter, CmcdReporterConfig, CmcdReportingMode, CmcdRequest, CmcdRequestKey, CmcdRequestReport, CmcdRequestReportConfig, CmcdResponse, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdV1, CmcdValue, CmcdVersion, appendCmcdHeaders, appendCmcdQuery, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Key, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue };
2067
+ //#region src/CmcdValidationSeverity.d.ts
2068
+ /**
2069
+ * CMCD validation severity level: error.
2070
+ *
2071
+ * @public
2072
+ */
2073
+ declare const CMCD_VALIDATION_SEVERITY_ERROR: "error";
2074
+ /**
2075
+ * CMCD validation severity level: warning.
2076
+ *
2077
+ * @public
2078
+ */
2079
+ declare const CMCD_VALIDATION_SEVERITY_WARNING: "warning";
2080
+ /**
2081
+ * CMCD validation severity level.
2082
+ *
2083
+ * @public
2084
+ */
2085
+ declare const CmcdValidationSeverity: {
2086
+ readonly ERROR: typeof CMCD_VALIDATION_SEVERITY_ERROR;
2087
+ readonly WARNING: typeof CMCD_VALIDATION_SEVERITY_WARNING;
2088
+ };
2089
+ /**
2090
+ * CMCD validation severity level.
2091
+ *
2092
+ * @public
2093
+ */
2094
+ type CmcdValidationSeverity = ValueOf<typeof CmcdValidationSeverity>;
2095
+ //#endregion
2096
+ //#region src/CmcdValidationIssue.d.ts
2097
+ /**
2098
+ * Describes a single validation issue found in a CMCD payload.
2099
+ *
2100
+ * @public
2101
+ */
2102
+ type CmcdValidationIssue = {
2103
+ /**
2104
+ * The CMCD key associated with the issue, or undefined for
2105
+ * structural issues.
2106
+ */
2107
+ key?: string;
2108
+ /**
2109
+ * A human-readable description of the issue.
2110
+ */
2111
+ message: string;
2112
+ /**
2113
+ * The severity of the issue.
2114
+ */
2115
+ severity: CmcdValidationSeverity;
2116
+ };
2117
+ //#endregion
2118
+ //#region src/CmcdValidationResult.d.ts
2119
+ /**
2120
+ * The result of validating a CMCD payload.
2121
+ *
2122
+ * @public
2123
+ */
2124
+ type CmcdValidationResult = {
2125
+ /** Whether the payload is valid. True if there are zero errors
2126
+ * (warnings are acceptable).
2127
+ */
2128
+ valid: boolean;
2129
+ /**
2130
+ * The list of validation issues found.
2131
+ */
2132
+ issues: CmcdValidationIssue[];
2133
+ };
2134
+ //#endregion
2135
+ //#region src/CmcdDataValidationResult.d.ts
2136
+ /**
2137
+ * The result of validating a single CMCD payload (headers or query).
2138
+ *
2139
+ * Extends {@link CmcdValidationResult} with the decoded {@link CmcdData}.
2140
+ *
2141
+ * @public
2142
+ */
2143
+ type CmcdDataValidationResult = CmcdValidationResult & {
2144
+ /**
2145
+ * The decoded CMCD data.
2146
+ */
2147
+ data: CmcdData;
2148
+ };
2149
+ //#endregion
2150
+ //#region src/CmcdEventsValidationResult.d.ts
2151
+ /**
2152
+ * The result of validating a multi-line CMCD event payload.
2153
+ *
2154
+ * Extends {@link CmcdValidationResult} with an array of decoded
2155
+ * {@link CmcdData} objects, one per event line.
2156
+ *
2157
+ * @public
2158
+ */
2159
+ type CmcdEventsValidationResult = CmcdValidationResult & {
2160
+ /**
2161
+ * The decoded CMCD data, one entry per event line.
2162
+ */
2163
+ data: CmcdData[];
2164
+ };
2165
+ //#endregion
2166
+ //#region src/CmcdValidationOptions.d.ts
2167
+ /**
2168
+ * Options for CMCD validation functions.
2169
+ *
2170
+ * @public
2171
+ */
2172
+ type CmcdValidationOptions = {
2173
+ /**
2174
+ * Explicit CMCD version override. If not provided, the version is
2175
+ * inferred from the payload's `v` key, defaulting to 1.
2176
+ */
2177
+ version?: CmcdVersion;
2178
+ /**
2179
+ * The reporting mode of the payload.
2180
+ */
2181
+ reportingMode?: CmcdReportingMode;
2182
+ };
2183
+ //#endregion
2184
+ //#region src/validateCmcd.d.ts
2185
+ /**
2186
+ * Validates a CMCD payload by checking keys, values, and structure.
2187
+ *
2188
+ * @example
2189
+ * {@includeCode ../test/validateCmcd.test.ts#example}
2190
+ *
2191
+ * @param data - The CMCD payload to validate.
2192
+ * @param options - Validation options.
2193
+ * @returns The validation result.
2194
+ *
2195
+ * @public
2196
+ */
2197
+ declare function validateCmcd(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2198
+ //#endregion
2199
+ //#region src/validateCmcdEvents.d.ts
2200
+ /**
2201
+ * Validates a raw CMCD string as an event-mode payload.
2202
+ *
2203
+ * This function decodes the string internally and validates it with
2204
+ * `reportingMode` set to `'event'`. The input may contain multiple
2205
+ * newline-separated events (e.g. a `text/cmcd` POST body), in which
2206
+ * case each line is validated independently and the results are merged.
2207
+ *
2208
+ * @example
2209
+ * {@includeCode ../test/validateCmcdEvents.test.ts#example}
2210
+ *
2211
+ * @param cmcd - The raw CMCD-encoded string to validate. May contain
2212
+ * multiple newline-separated event lines.
2213
+ * @param options - Validation options (excluding `reportingMode`).
2214
+ * @returns The validation result including decoded data per event line.
2215
+ *
2216
+ * @public
2217
+ */
2218
+ declare function validateCmcdEvents(cmcd: string, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdEventsValidationResult;
2219
+ //#endregion
2220
+ //#region src/validateCmcdHeaders.d.ts
2221
+ /**
2222
+ * Validates CMCD HTTP headers by checking shard placement and payload validity.
2223
+ *
2224
+ * This function accepts raw CMCD header strings, decodes each shard
2225
+ * internally, verifies that each key is placed in its correct header shard,
2226
+ * then merges all shards and runs full payload validation (keys, values, and
2227
+ * structure) on the merged data.
2228
+ *
2229
+ * @example
2230
+ * {@includeCode ../test/validateCmcdHeaders.test.ts#example}
2231
+ *
2232
+ * @param headers - A `Headers` instance or a record of CMCD header fields to their raw encoded string values.
2233
+ * @param options - Validation options (excluding `reportingMode`).
2234
+ * @returns The validation result including decoded data.
2235
+ *
2236
+ * @public
2237
+ */
2238
+ declare function validateCmcdHeaders(headers: Record<string, string> | Headers, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdDataValidationResult;
2239
+ //#endregion
2240
+ //#region src/validateCmcdKeys.d.ts
2241
+ /**
2242
+ * Validates that all keys in a CMCD payload are recognized spec keys or valid custom keys.
2243
+ *
2244
+ * @example
2245
+ * {@includeCode ../test/validateCmcdKeys.test.ts#example}
2246
+ *
2247
+ * @param data - The CMCD payload to validate.
2248
+ * @param options - Validation options.
2249
+ * @returns The validation result.
2250
+ *
2251
+ * @public
2252
+ */
2253
+ declare function validateCmcdKeys(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2254
+ //#endregion
2255
+ //#region src/validateCmcdRequest.d.ts
2256
+ /**
2257
+ * Validates CMCD data from a request as a request-mode payload.
2258
+ *
2259
+ * Accepts a
2260
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
2261
+ * object or an {@link @svta/cml-utils#HttpRequest | HttpRequest} object.
2262
+ *
2263
+ * The function checks for CMCD data in the HTTP headers first. If CMCD
2264
+ * headers are found, validation includes shard-placement checks via
2265
+ * {@link validateCmcdHeaders}. Otherwise, the CMCD query parameter is
2266
+ * extracted from the URL and validated.
2267
+ *
2268
+ * @example
2269
+ * {@includeCode ../test/validateCmcdRequest.test.ts#example}
2270
+ *
2271
+ * @param request - A `Request` or `HttpRequest` to validate.
2272
+ * @param options - Validation options (excluding `reportingMode`).
2273
+ * @returns The validation result including decoded data.
2274
+ *
2275
+ * @public
2276
+ */
2277
+ declare function validateCmcdRequest(request: Request | HttpRequest, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdDataValidationResult;
2278
+ //#endregion
2279
+ //#region src/validateCmcdStructure.d.ts
2280
+ /**
2281
+ * Validates the structural rules of a CMCD payload.
2282
+ *
2283
+ * @example
2284
+ * {@includeCode ../test/validateCmcdStructure.test.ts#example}
2285
+ *
2286
+ * @param data - The CMCD payload to validate.
2287
+ * @param options - Validation options.
2288
+ * @returns The validation result.
2289
+ *
2290
+ * @public
2291
+ */
2292
+ declare function validateCmcdStructure(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2293
+ //#endregion
2294
+ //#region src/validateCmcdValues.d.ts
2295
+ /**
2296
+ * Validates that all values in a CMCD payload conform to the expected types and constraints.
2297
+ *
2298
+ * @example
2299
+ * {@includeCode ../test/validateCmcdValues.test.ts#example}
2300
+ *
2301
+ * @param data - The CMCD payload to validate.
2302
+ * @param options - Validation options.
2303
+ * @returns The validation result.
2304
+ *
2305
+ * @public
2306
+ */
2307
+ declare function validateCmcdValues(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2308
+ //#endregion
2309
+ 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_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, Cmcd, CmcdCustomKey, CmcdCustomValue, CmcdData, CmcdDataValidationResult, CmcdDecodeOptions, CmcdEncodeOptions, CmcdEvent, CmcdEventReportConfig, CmcdEventType, CmcdEventsValidationResult, CmcdFormatter, CmcdFormatterMap, CmcdFormatterOptions, CmcdHeaderField, CmcdHeaderKey, CmcdHeaderMap, CmcdHeaderValue, CmcdKey, CmcdObjectType, CmcdObjectTypeList, CmcdPlayerState, CmcdReportConfig, CmcdReporter, CmcdReporterConfig, CmcdReportingMode, CmcdRequest, CmcdRequestKey, CmcdRequestReport, CmcdRequestReportConfig, CmcdResponse, CmcdStreamType, CmcdStreamingFormat, CmcdTransmissionMode, CmcdV1, CmcdV1Data, CmcdV2Data, CmcdValidationIssue, CmcdValidationOptions, CmcdValidationResult, CmcdValidationSeverity, CmcdValue, CmcdVersion, appendCmcdHeaders, appendCmcdQuery, decodeCmcd, encodeCmcd, fromCmcdHeaders, fromCmcdQuery, fromCmcdUrl, groupCmcdHeaders, isCmcdCustomKey, isCmcdEventKey, isCmcdRequestKey, isCmcdResponseReceivedKey, isCmcdV1Data, isCmcdV1Key, isCmcdV2Data, prepareCmcdData, toCmcdHeaders, toCmcdQuery, toCmcdUrl, toCmcdValue, validateCmcd, validateCmcdEvents, validateCmcdHeaders, validateCmcdKeys, validateCmcdRequest, validateCmcdStructure, validateCmcdValues };
1929
2310
  //# sourceMappingURL=index.d.ts.map