@svta/cml-cmcd 2.2.0 → 2.3.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
@@ -108,9 +108,10 @@ declare const CMCD_EVENT_CUSTOM_EVENT: "ce";
108
108
  /**
109
109
  * CMCD event types for the 'e' key (event mode).
110
110
  *
111
- *
112
111
  * @enum
113
112
  *
113
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event | CTA-5004-A Event}
114
+ *
114
115
  * @public
115
116
  */
116
117
  declare const CmcdEventType: {
@@ -214,6 +215,8 @@ type CmcdCustomValue = string | SfItem<string> | (string | SfItem<string>)[] | n
214
215
  * @public
215
216
  *
216
217
  * @enum
218
+ *
219
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#object-type | CTA-5004-A Object Type}
217
220
  */
218
221
  declare const CmcdObjectType: {
219
222
  /**
@@ -274,6 +277,8 @@ type CmcdObjectTypeList = (number | SfItem<number, ExclusiveRecord<CmcdObjectTyp
274
277
  * @enum
275
278
  *
276
279
  * @public
280
+ *
281
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#state | CTA-5004-A State}
277
282
  */
278
283
  declare const CmcdPlayerState: {
279
284
  /**
@@ -328,6 +333,8 @@ type CmcdPlayerState = ValueOf<typeof CmcdPlayerState>;
328
333
  *
329
334
  * @enum
330
335
  *
336
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#stream-type | CTA-5004-A Stream Type}
337
+ *
331
338
  * @public
332
339
  */
333
340
  declare const CmcdStreamType: {
@@ -353,9 +360,10 @@ type CmcdStreamType = ValueOf<typeof CmcdStreamType>;
353
360
  /**
354
361
  * Common Media Client Data Streaming Format
355
362
  *
356
- *
357
363
  * @enum
358
364
  *
365
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#streaming-format | CTA-5004-A Streaming Format}
366
+ *
359
367
  * @public
360
368
  */
361
369
  declare const CmcdStreamingFormat: {
@@ -388,7 +396,7 @@ type CmcdStreamingFormat = ValueOf<typeof CmcdStreamingFormat>;
388
396
  * A standardized set of HTTP request header fields and query string parameters
389
397
  * for communicating media playback metrics in request mode.
390
398
  *
391
- * @see {@link https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf|CMCD v1 Spec}
399
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#request-mode | CTA-5004-A Request Mode}
392
400
  *
393
401
  * @public
394
402
  */
@@ -407,6 +415,8 @@ type CmcdRequest = {
407
415
  * the encoded bitrate is known.
408
416
  *
409
417
  * Inner list of integer kbps with token identifiers
418
+ *
419
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#aggregate-encoded-bitrate | CTA-5004-A Aggregate Encoded Bitrate}
410
420
  */
411
421
  ab?: CmcdObjectTypeList;
412
422
  /**
@@ -416,6 +426,8 @@ type CmcdRequest = {
416
426
  * be sent if it is TRUE. If the visibility state of the player is not known this key SHOULD NOT be reported.
417
427
  *
418
428
  * Boolean
429
+ *
430
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#backgrounded | CTA-5004-A Backgrounded}
419
431
  */
420
432
  bg?: boolean;
421
433
  /**
@@ -424,6 +436,8 @@ type CmcdRequest = {
424
436
  * The buffer length associated with the media object being requested. This value SHOULD be rounded to the nearest 100 ms.
425
437
  *
426
438
  * Inner list of integer milliseconds with token identifiers
439
+ *
440
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#buffer-length | CTA-5004-A Buffer Length}
427
441
  */
428
442
  bl?: CmcdObjectTypeList;
429
443
  /**
@@ -435,6 +449,8 @@ type CmcdRequest = {
435
449
  * If the playlist declares both peak and average bitrate values, the peak value MUST be transmitted.
436
450
  *
437
451
  * Inner list of integer kbps with token identifiers
452
+ *
453
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#encoded-bitrate | CTA-5004-A Encoded Bitrate}
438
454
  */
439
455
  br?: CmcdObjectTypeList;
440
456
  /**
@@ -445,6 +461,8 @@ type CmcdRequest = {
445
461
  * new CDN, then this key might initially report buffering caused by the prior CDN. This key SHOULD NOT be reported if it is FALSE.
446
462
  *
447
463
  * Boolean
464
+ *
465
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#buffer-starvation | CTA-5004-A Buffer Starvation}
448
466
  */
449
467
  bs?: boolean;
450
468
  /**
@@ -454,6 +472,8 @@ type CmcdRequest = {
454
472
  * to rebuffering. Token identifier MAY be omitted if the cause of the rebuffering is unknown.
455
473
  *
456
474
  * Inner list of integers with optional token identifiers
475
+ *
476
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#buffer-starvation-absolute | CTA-5004-A Buffer Starvation Absolute}
457
477
  */
458
478
  bsa?: CmcdObjectTypeList;
459
479
  /**
@@ -463,6 +483,8 @@ type CmcdRequest = {
463
483
  * once per reporting mode and report destination. Token identifier MAY be omitted if the cause of the rebuffering is unknown.
464
484
  *
465
485
  * Inner list of integer milliseconds with optional token identifiers
486
+ *
487
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#buffer-starvation-duration | CTA-5004-A Buffer Starvation Duration}
466
488
  */
467
489
  bsd?: CmcdObjectTypeList;
468
490
  /**
@@ -472,6 +494,8 @@ type CmcdRequest = {
472
494
  * rebuffering is unknown.
473
495
  *
474
496
  * Inner list of integer milliseconds with optional token identifiers
497
+ *
498
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#buffer-starvation-duration-absolute | CTA-5004-A Buffer Starvation Duration Absolute}
475
499
  */
476
500
  bsda?: CmcdObjectTypeList;
477
501
  /**
@@ -480,6 +504,8 @@ type CmcdRequest = {
480
504
  * A string identifying the current delivery network from which the player is retrieving content. Maximum length is 128 characters.
481
505
  *
482
506
  * String
507
+ *
508
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#cdn-id | CTA-5004-A CDN ID}
483
509
  */
484
510
  cdn?: string;
485
511
  /**
@@ -489,6 +515,8 @@ type CmcdRequest = {
489
515
  * sessions and devices and is defined and updated at the discretion of the service provider.
490
516
  *
491
517
  * String
518
+ *
519
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#content-id | CTA-5004-A Content ID}
492
520
  */
493
521
  cid?: string;
494
522
  /**
@@ -498,6 +526,8 @@ type CmcdRequest = {
498
526
  * to the content. For example, this field may be used to transmit the C2PA signature associated with the content being viewed.
499
527
  *
500
528
  * String
529
+ *
530
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#content-signature | CTA-5004-A Content Signature}
501
531
  */
502
532
  cs?: string;
503
533
  /**
@@ -509,6 +539,8 @@ type CmcdRequest = {
509
539
  * This value MUST NOT be sent for objects which do not have an object type of 'a', 'v', 'av', 'tt', 'c', or 'o'.
510
540
  *
511
541
  * Integer milliseconds
542
+ *
543
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#object-duration | CTA-5004-A Object Duration}
512
544
  */
513
545
  d?: number;
514
546
  /**
@@ -519,6 +551,8 @@ type CmcdRequest = {
519
551
  * beneficial if accompanied by the playhead time 'pt' key to allow for correct interpretation.
520
552
  *
521
553
  * Integer
554
+ *
555
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#dropped-frames-absolute | CTA-5004-A Dropped Frames Absolute}
522
556
  */
523
557
  dfa?: number;
524
558
  /**
@@ -529,6 +563,8 @@ type CmcdRequest = {
529
563
  * player's remaining buffer length.
530
564
  *
531
565
  * Integer milliseconds
566
+ *
567
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#deadline | CTA-5004-A Deadline}
532
568
  */
533
569
  dl?: number;
534
570
  /**
@@ -539,6 +575,8 @@ type CmcdRequest = {
539
575
  * Even if only one error code is being specified, the list notation MUST still be used.
540
576
  *
541
577
  * Inner list of strings
578
+ *
579
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#player-error-code | CTA-5004-A Player Error Code}
542
580
  */
543
581
  ec?: string[];
544
582
  /**
@@ -550,6 +588,8 @@ type CmcdRequest = {
550
588
  * sent if the lowest encoded bitrate is known.
551
589
  *
552
590
  * Inner list of integer kbps with token identifiers
591
+ *
592
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#lowest-aggregated-encoded-bitrate | CTA-5004-A Lowest Aggregated Encoded Bitrate}
553
593
  */
554
594
  lab?: CmcdObjectTypeList;
555
595
  /**
@@ -561,6 +601,8 @@ type CmcdRequest = {
561
601
  * requests for audio objects MUST specify the lowest audio bitrate.
562
602
  *
563
603
  * Inner list of integer kbps with token identifiers
604
+ *
605
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#lowest-encoded-bitrate | CTA-5004-A Lowest Encoded Bitrate}
564
606
  */
565
607
  lb?: CmcdObjectTypeList;
566
608
  /**
@@ -570,6 +612,8 @@ type CmcdRequest = {
570
612
  * accuracy of this estimate is dependent on synchronization between the packager and the player clocks.
571
613
  *
572
614
  * Integer milliseconds
615
+ *
616
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#live-stream-latency | CTA-5004-A Live Stream Latency}
573
617
  */
574
618
  ltc?: number;
575
619
  /**
@@ -582,6 +626,8 @@ type CmcdRequest = {
582
626
  * This key MUST only be sent once per Session ID and MUST be sent for each reporting mode which is active within the player.
583
627
  *
584
628
  * Integer milliseconds
629
+ *
630
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#media-start-delay | CTA-5004-A Media Start Delay}
585
631
  */
586
632
  msd?: number;
587
633
  /**
@@ -597,6 +643,8 @@ type CmcdRequest = {
597
643
  * since the prior interval report.
598
644
  *
599
645
  * Inner list of integer kbps with token identifiers
646
+ *
647
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#measured-throughput | CTA-5004-A Measured Throughput}
600
648
  */
601
649
  mtp?: CmcdObjectTypeList;
602
650
  /**
@@ -616,6 +664,8 @@ type CmcdRequest = {
616
664
  * The player SHOULD NOT depend upon any pre-fetch action being taken - it is merely a request for such a pre-fetch to take place.
617
665
  *
618
666
  * Inner list of strings
667
+ *
668
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#next-object-request | CTA-5004-A Next Object Request}
619
669
  */
620
670
  nor?: (string | SfItem<string, {
621
671
  r: string;
@@ -626,6 +676,8 @@ type CmcdRequest = {
626
676
  * True when the content being retrieved by a player is not rendered as audio or video. The key SHOULD only be sent when it is TRUE.
627
677
  *
628
678
  * Boolean
679
+ *
680
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#non-rendered | CTA-5004-A Non Rendered}
629
681
  */
630
682
  nr?: boolean;
631
683
  /**
@@ -647,6 +699,8 @@ type CmcdRequest = {
647
699
  * This key is also used as a token parameter for other keys.
648
700
  *
649
701
  * Token
702
+ *
703
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#object-type | CTA-5004-A Object Type}
650
704
  */
651
705
  ot?: CmcdObjectType;
652
706
  /**
@@ -655,6 +709,8 @@ type CmcdRequest = {
655
709
  * The encoded bitrate of the media object(s) being shown to the end user.
656
710
  *
657
711
  * Inner list of integer kbps with token identifiers
712
+ *
713
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#playhead-bitrate | CTA-5004-A Playhead Bitrate}
658
714
  */
659
715
  pb?: CmcdObjectTypeList;
660
716
  /**
@@ -663,6 +719,8 @@ type CmcdRequest = {
663
719
  * 1.0 if real-time, 2.0 if double speed, 0 if not playing. SHOULD only be sent if not equal to 1.0.
664
720
  *
665
721
  * Decimal
722
+ *
723
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#playback-rate | CTA-5004-A Playback Rate}
666
724
  */
667
725
  pr?: number;
668
726
  /**
@@ -671,6 +729,8 @@ type CmcdRequest = {
671
729
  * The playhead time, expressed in milliseconds, which is being rendered to the viewer when the report is made.
672
730
  *
673
731
  * Integer milliseconds
732
+ *
733
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#playhead-time | CTA-5004-A Playhead Time}
674
734
  */
675
735
  pt?: number;
676
736
  /**
@@ -680,6 +740,8 @@ type CmcdRequest = {
680
740
  * nearest 100kbps.
681
741
  *
682
742
  * Integer kbps
743
+ *
744
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#requested-maximum-throughput | CTA-5004-A Requested Maximum Throughput}
683
745
  */
684
746
  rtp?: number;
685
747
  /**
@@ -694,6 +756,8 @@ type CmcdRequest = {
694
756
  * - `o` = other
695
757
  *
696
758
  * Token
759
+ *
760
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#streaming-format | CTA-5004-A Streaming Format}
697
761
  */
698
762
  sf?: CmcdStreamingFormat;
699
763
  /**
@@ -705,6 +769,8 @@ type CmcdRequest = {
705
769
  * UUID specification.
706
770
  *
707
771
  * String
772
+ *
773
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#session-id | CTA-5004-A Session ID}
708
774
  */
709
775
  sid?: string;
710
776
  /**
@@ -714,6 +780,8 @@ type CmcdRequest = {
714
780
  * zero on the start of a new session-id. Sequence numbers increase independently per each combination of mode and target.
715
781
  *
716
782
  * Integer
783
+ *
784
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#sequence-number | CTA-5004-A Sequence Number}
717
785
  */
718
786
  sn?: number;
719
787
  /**
@@ -724,6 +792,8 @@ type CmcdRequest = {
724
792
  * - `ll` = low latency LIVE
725
793
  *
726
794
  * Token
795
+ *
796
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#stream-type | CTA-5004-A Stream Type}
727
797
  */
728
798
  st?: CmcdStreamType;
729
799
  /**
@@ -742,6 +812,8 @@ type CmcdRequest = {
742
812
  * - `d` - preloading: the player is loading, or has loaded, assets ahead of starting in order to provide a fast startup. The expectation is that playback will commence at a future time.
743
813
  *
744
814
  * Token - one of [s,p,k,r,a,e,f,q,d]
815
+ *
816
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#state | CTA-5004-A State}
745
817
  */
746
818
  sta?: CmcdPlayerState;
747
819
  /**
@@ -751,6 +823,8 @@ type CmcdRequest = {
751
823
  * reports this key as true until its buffer first reaches the target buffer for stable playback.
752
824
  *
753
825
  * Boolean
826
+ *
827
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#startup | CTA-5004-A Startup}
754
828
  */
755
829
  su?: boolean;
756
830
  /**
@@ -762,6 +836,8 @@ type CmcdRequest = {
762
836
  * sent if the top encoded bitrate is known.
763
837
  *
764
838
  * Inner list of integer kbps with token identifiers
839
+ *
840
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#top-aggregated-encoded-bitrate | CTA-5004-A Top Aggregated Encoded Bitrate}
765
841
  */
766
842
  tab?: CmcdObjectTypeList;
767
843
  /**
@@ -773,6 +849,8 @@ type CmcdRequest = {
773
849
  * specify the top video bitrate and requests for audio objects MUST specify the top audio bitrate.
774
850
  *
775
851
  * Inner list of integer kbps with token identifiers
852
+ *
853
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#top-encoded-bitrate | CTA-5004-A Top Encoded Bitrate}
776
854
  */
777
855
  tb?: CmcdObjectTypeList;
778
856
  /**
@@ -782,6 +860,8 @@ type CmcdRequest = {
782
860
  * to the nearest 100 ms.
783
861
  *
784
862
  * Inner list of integer milliseconds with token identifiers
863
+ *
864
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#target-buffer-length | CTA-5004-A Target Buffer Length}
785
865
  */
786
866
  tbl?: CmcdObjectTypeList;
787
867
  /**
@@ -800,6 +880,8 @@ type CmcdRequest = {
800
880
  * of 'a', 'v', 'av' or 'c'.
801
881
  *
802
882
  * Inner list of integer kbps with token identifiers
883
+ *
884
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#top-playable-bitrate | CTA-5004-A Top Playable Bitrate}
803
885
  */
804
886
  tpb?: CmcdObjectTypeList;
805
887
  /**
@@ -810,6 +892,8 @@ type CmcdRequest = {
810
892
  * if the version is not 1.
811
893
  *
812
894
  * Integer
895
+ *
896
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#version | CTA-5004-A Version}
813
897
  */
814
898
  v?: number;
815
899
  };
@@ -821,6 +905,8 @@ type CmcdRequest = {
821
905
  * Extends {@link CmcdRequest} with event-specific keys for reporting events
822
906
  * according to the CMCD version 2 specification.
823
907
  *
908
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event-mode | CTA-5004-A Event Mode}
909
+ *
824
910
  * @public
825
911
  */
826
912
  type CmcdEvent = CmcdRequest & {
@@ -832,6 +918,8 @@ type CmcdEvent = CmcdRequest & {
832
918
  * a custom value associated with this event. The names chosen SHOULD associate the custom event name with the custom key name.
833
919
  *
834
920
  * String
921
+ *
922
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#custom-event-name | CTA-5004-A Custom Event Name}
835
923
  */
836
924
  cen?: string;
837
925
  /**
@@ -861,6 +949,8 @@ type CmcdEvent = CmcdRequest & {
861
949
  * - `um` - unmute
862
950
  *
863
951
  * Token
952
+ *
953
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event | CTA-5004-A Event}
864
954
  */
865
955
  e?: CmcdEventType;
866
956
  /**
@@ -869,6 +959,8 @@ type CmcdEvent = CmcdRequest & {
869
959
  * A string identifying the current hostname from which the player is retrieving content. Maximum length is 128 characters.
870
960
  *
871
961
  * String
962
+ *
963
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#hostname | CTA-5004-A Hostname}
872
964
  */
873
965
  h?: string;
874
966
  /**
@@ -881,6 +973,8 @@ type CmcdEvent = CmcdRequest & {
881
973
  * This key MUST be included with all Event reports.
882
974
  *
883
975
  * Integer milliseconds
976
+ *
977
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#timestamp | CTA-5004-A Timestamp}
884
978
  */
885
979
  ts?: number;
886
980
  };
@@ -892,6 +986,8 @@ type CmcdEvent = CmcdRequest & {
892
986
  * Extends {@link CmcdRequest} with response-specific keys for reporting
893
987
  * response data according to the CMCD version 2 specification.
894
988
  *
989
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#response-mode | CTA-5004-A Response Mode}
990
+ *
895
991
  * @public
896
992
  */
897
993
  type CmcdResponse = CmcdRequest & {
@@ -902,6 +998,8 @@ type CmcdResponse = CmcdRequest & {
902
998
  * events of type `rr` (response received).
903
999
  *
904
1000
  * String
1001
+ *
1002
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#cmsd-dynamic-header | CTA-5004-A CMSD Dynamic Header}
905
1003
  */
906
1004
  cmsdd?: string;
907
1005
  /**
@@ -911,6 +1009,8 @@ type CmcdResponse = CmcdRequest & {
911
1009
  * events of type `rr` (response received).
912
1010
  *
913
1011
  * String
1012
+ *
1013
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#cmsd-static-header | CTA-5004-A CMSD Static Header}
914
1014
  */
915
1015
  cmsds?: string;
916
1016
  /**
@@ -922,6 +1022,8 @@ type CmcdResponse = CmcdRequest & {
922
1022
  * This key MUST only be reported on events of type `rr` (response received).
923
1023
  *
924
1024
  * Integer
1025
+ *
1026
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#response-code | CTA-5004-A Response Code}
925
1027
  */
926
1028
  rc?: number;
927
1029
  /**
@@ -931,6 +1033,8 @@ type CmcdResponse = CmcdRequest & {
931
1033
  * only be reported on events of type `rr` (response received).
932
1034
  *
933
1035
  * String
1036
+ *
1037
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#smrt-data-header | CTA-5004-A SMRT-Data Header}
934
1038
  */
935
1039
  smrt?: string;
936
1040
  /**
@@ -940,6 +1044,8 @@ type CmcdResponse = CmcdRequest & {
940
1044
  * was received. This key MUST only be reported on events of type `rr` (response received).
941
1045
  *
942
1046
  * Integer milliseconds
1047
+ *
1048
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#time-to-first-byte | CTA-5004-A Time to First Byte}
943
1049
  */
944
1050
  ttfb?: number;
945
1051
  /**
@@ -949,6 +1055,8 @@ type CmcdResponse = CmcdRequest & {
949
1055
  * are received. This key MUST only be reported on events of type `rr` (response received).
950
1056
  *
951
1057
  * Integer milliseconds
1058
+ *
1059
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#time-to-first-body-byte | CTA-5004-A Time to First Body Byte}
952
1060
  */
953
1061
  ttfbb?: number;
954
1062
  /**
@@ -958,6 +1066,8 @@ type CmcdResponse = CmcdRequest & {
958
1066
  * This key MUST only be reported on events of type `rr` (response received).
959
1067
  *
960
1068
  * Integer milliseconds
1069
+ *
1070
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#time-to-last-byte | CTA-5004-A Time to Last Byte}
961
1071
  */
962
1072
  ttlb?: number;
963
1073
  /**
@@ -967,6 +1077,8 @@ type CmcdResponse = CmcdRequest & {
967
1077
  * MUST be reported on events of type `rr` (response received).
968
1078
  *
969
1079
  * String
1080
+ *
1081
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#request-url | CTA-5004-A Request URL}
970
1082
  */
971
1083
  url?: string;
972
1084
  };
@@ -1294,6 +1406,8 @@ type CmcdEncodeOptions = {
1294
1406
  *
1295
1407
  * @example
1296
1408
  * {@includeCode ../test/appendCmcdHeaders.test.ts#example}
1409
+ *
1410
+ * @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}
1297
1411
  */
1298
1412
  declare function appendCmcdHeaders(headers: Record<string, string>, cmcd: Cmcd, options?: CmcdEncodeOptions): Record<string, string>;
1299
1413
  //#endregion
@@ -1311,9 +1425,103 @@ declare function appendCmcdHeaders(headers: Record<string, string>, cmcd: Cmcd,
1311
1425
  *
1312
1426
  * @example
1313
1427
  * {@includeCode ../test/appendCmcdQuery.test.ts#example}
1428
+ *
1429
+ * @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}
1314
1430
  */
1315
1431
  declare function appendCmcdQuery(url: string, cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1316
1432
  //#endregion
1433
+ //#region src/CMCD_DEFAULT_TIME_INTERVAL.d.ts
1434
+ /**
1435
+ * The default time interval in seconds when using using event mode
1436
+ *
1437
+ * @public
1438
+ */
1439
+ declare const CMCD_DEFAULT_TIME_INTERVAL = 30;
1440
+ //#endregion
1441
+ //#region src/CMCD_EVENT_KEYS.d.ts
1442
+ /**
1443
+ * Defines the event-specific keys for CMCD (Common Media Client Data) version 2.
1444
+ *
1445
+ * @public
1446
+ */
1447
+ declare const CMCD_EVENT_KEYS: readonly ["cen", "e", "h", "ts"];
1448
+ //#endregion
1449
+ //#region src/CMCD_FORMATTER_MAP.d.ts
1450
+ /**
1451
+ * The default formatters for CMCD values.
1452
+ *
1453
+ * @public
1454
+ */
1455
+ declare const CMCD_FORMATTER_MAP: Record<string, CmcdFormatter>;
1456
+ //#endregion
1457
+ //#region src/CmcdRequestKey.d.ts
1458
+ /**
1459
+ * A CMCD request key.
1460
+ *
1461
+ * @public
1462
+ */
1463
+ type CmcdRequestKey = keyof CmcdRequest | "nrr";
1464
+ //#endregion
1465
+ //#region src/CMCD_HEADER_MAP.d.ts
1466
+ /**
1467
+ * The map of CMCD keys to their appropriate header shard.
1468
+ *
1469
+ * Note: Event-only keys (e, ts, cen, h) and response-received keys
1470
+ * (rc, ttfb, ttlb, url, etc.) are intentionally absent. They are
1471
+ * transmitted via the event-mode POST body, not HTTP headers.
1472
+ *
1473
+ * @public
1474
+ */
1475
+ declare const CMCD_HEADER_MAP: Record<CmcdRequestKey | "nrr", CmcdHeaderField>;
1476
+ //#endregion
1477
+ //#region src/CMCD_KEYS.d.ts
1478
+ /**
1479
+ * A list of all CMCD keys.
1480
+ *
1481
+ * @public
1482
+ */
1483
+ declare const CMCD_KEYS: CmcdKey[];
1484
+ //#endregion
1485
+ //#region src/CMCD_MIME_TYPE.d.ts
1486
+ /**
1487
+ * CMCD MIME type for event report payloads.
1488
+ *
1489
+ * @public
1490
+ */
1491
+ declare const CMCD_MIME_TYPE = "application/cmcd";
1492
+ //#endregion
1493
+ //#region src/CMCD_PARAM.d.ts
1494
+ /**
1495
+ * CMCD parameter name.
1496
+ *
1497
+ * @public
1498
+ */
1499
+ declare const CMCD_PARAM = "CMCD";
1500
+ //#endregion
1501
+ //#region src/CMCD_REQUEST_KEYS.d.ts
1502
+ /**
1503
+ * Defines the request-specific keys for CMCD (Common Media Client Data) version 2.
1504
+ *
1505
+ * @public
1506
+ */
1507
+ 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"];
1508
+ //#endregion
1509
+ //#region src/CMCD_RESPONSE_KEYS.d.ts
1510
+ /**
1511
+ * CMCD v2 - Response-only and timing keys.
1512
+ *
1513
+ * @public
1514
+ */
1515
+ declare const CMCD_RESPONSE_KEYS: readonly ["cmsdd", "cmsds", "rc", "smrt", "ttfb", "ttfbb", "ttlb", "url"];
1516
+ //#endregion
1517
+ //#region src/CMCD_V1_KEYS.d.ts
1518
+ /**
1519
+ * Defines the keys for CMCD (Common Media Client Data) version 1.
1520
+ *
1521
+ * @public
1522
+ */
1523
+ declare const CMCD_V1_KEYS: readonly ["bl", "br", "bs", "cid", "d", "dl", "mtp", "nor", "nrr", "ot", "pr", "rtp", "sf", "sid", "st", "su", "tb", "v"];
1524
+ //#endregion
1317
1525
  //#region src/CmcdData.d.ts
1318
1526
  /**
1319
1527
  * CMCD version 1 data.
@@ -1362,108 +1570,107 @@ type CmcdV2Data = Omit<Cmcd, "v"> & {
1362
1570
  */
1363
1571
  type CmcdData = CmcdV1Data | CmcdV2Data;
1364
1572
  //#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
1384
- //#region src/CMCD_DEFAULT_TIME_INTERVAL.d.ts
1385
- /**
1386
- * The default time interval in seconds when using using event mode
1387
- *
1388
- * @public
1389
- */
1390
- declare const CMCD_DEFAULT_TIME_INTERVAL = 30;
1391
- //#endregion
1392
- //#region src/CMCD_EVENT_KEYS.d.ts
1573
+ //#region src/CmcdValidationSeverity.d.ts
1393
1574
  /**
1394
- * Defines the event-specific keys for CMCD (Common Media Client Data) version 2.
1575
+ * CMCD validation severity level: error.
1395
1576
  *
1396
1577
  * @public
1397
1578
  */
1398
- declare const CMCD_EVENT_KEYS: readonly ["cen", "e", "h", "ts"];
1399
- //#endregion
1400
- //#region src/CMCD_FORMATTER_MAP.d.ts
1579
+ declare const CMCD_VALIDATION_SEVERITY_ERROR: "error";
1401
1580
  /**
1402
- * The default formatters for CMCD values.
1581
+ * CMCD validation severity level: warning.
1403
1582
  *
1404
1583
  * @public
1405
1584
  */
1406
- declare const CMCD_FORMATTER_MAP: Record<string, CmcdFormatter>;
1407
- //#endregion
1408
- //#region src/CmcdRequestKey.d.ts
1585
+ declare const CMCD_VALIDATION_SEVERITY_WARNING: "warning";
1409
1586
  /**
1410
- * A CMCD request key.
1587
+ * CMCD validation severity level.
1411
1588
  *
1412
1589
  * @public
1413
1590
  */
1414
- type CmcdRequestKey = keyof CmcdRequest | "nrr";
1415
- //#endregion
1416
- //#region src/CMCD_HEADER_MAP.d.ts
1591
+ declare const CmcdValidationSeverity: {
1592
+ readonly ERROR: typeof CMCD_VALIDATION_SEVERITY_ERROR;
1593
+ readonly WARNING: typeof CMCD_VALIDATION_SEVERITY_WARNING;
1594
+ };
1417
1595
  /**
1418
- * The map of CMCD keys to their appropriate header shard.
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.
1596
+ * CMCD validation severity level.
1423
1597
  *
1424
1598
  * @public
1425
1599
  */
1426
- declare const CMCD_HEADER_MAP: Record<CmcdRequestKey | "nrr", CmcdHeaderField>;
1600
+ type CmcdValidationSeverity = ValueOf<typeof CmcdValidationSeverity>;
1427
1601
  //#endregion
1428
- //#region src/CMCD_KEYS.d.ts
1602
+ //#region src/CmcdValidationIssue.d.ts
1429
1603
  /**
1430
- * A list of all CMCD keys.
1604
+ * Describes a single validation issue found in a CMCD payload.
1431
1605
  *
1432
1606
  * @public
1433
1607
  */
1434
- declare const CMCD_KEYS: CmcdKey[];
1608
+ type CmcdValidationIssue = {
1609
+ /**
1610
+ * The CMCD key associated with the issue, or undefined for
1611
+ * structural issues.
1612
+ */
1613
+ key?: string;
1614
+ /**
1615
+ * A human-readable description of the issue.
1616
+ */
1617
+ message: string;
1618
+ /**
1619
+ * The severity of the issue.
1620
+ */
1621
+ severity: CmcdValidationSeverity;
1622
+ };
1435
1623
  //#endregion
1436
- //#region src/CMCD_PARAM.d.ts
1624
+ //#region src/CmcdValidationResult.d.ts
1437
1625
  /**
1438
- * CMCD parameter name.
1626
+ * The result of validating a CMCD payload.
1439
1627
  *
1440
1628
  * @public
1441
1629
  */
1442
- declare const CMCD_PARAM = "CMCD";
1630
+ type CmcdValidationResult = {
1631
+ /** Whether the payload is valid. True if there are zero errors
1632
+ * (warnings are acceptable).
1633
+ */
1634
+ valid: boolean;
1635
+ /**
1636
+ * The list of validation issues found.
1637
+ */
1638
+ issues: CmcdValidationIssue[];
1639
+ };
1443
1640
  //#endregion
1444
- //#region src/CMCD_REQUEST_KEYS.d.ts
1641
+ //#region src/CmcdDataValidationResult.d.ts
1445
1642
  /**
1446
- * Defines the request-specific keys for CMCD (Common Media Client Data) version 2.
1643
+ * The result of validating a single CMCD payload (headers or query).
1447
1644
  *
1448
- * @public
1449
- */
1450
- 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"];
1451
- //#endregion
1452
- //#region src/CMCD_RESPONSE_KEYS.d.ts
1453
- /**
1454
- * CMCD v2 - Response-only and timing keys.
1645
+ * Extends {@link CmcdValidationResult} with the decoded {@link CmcdData}.
1455
1646
  *
1456
1647
  * @public
1457
1648
  */
1458
- declare const CMCD_RESPONSE_KEYS: readonly ["cmsdd", "cmsds", "rc", "smrt", "ttfb", "ttfbb", "ttlb", "url"];
1649
+ type CmcdDataValidationResult = CmcdValidationResult & {
1650
+ /**
1651
+ * The decoded CMCD data.
1652
+ */
1653
+ data: CmcdData;
1654
+ };
1459
1655
  //#endregion
1460
- //#region src/CMCD_V1_KEYS.d.ts
1656
+ //#region src/CmcdDecodeOptions.d.ts
1461
1657
  /**
1462
- * Defines the keys for CMCD (Common Media Client Data) version 1.
1658
+ * Options for decoding CMCD data.
1463
1659
  *
1464
1660
  * @public
1465
1661
  */
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"];
1662
+ type CmcdDecodeOptions = {
1663
+ /**
1664
+ * When `true`, up-converts version 1 data to version 2 format by wrapping
1665
+ * scalar values in arrays for inner-list keys (e.g., `bl`, `br`, `mtp`).
1666
+ *
1667
+ * This ensures a consistent data shape regardless of the source version,
1668
+ * mirroring the down-conversion that occurs during encoding.
1669
+ *
1670
+ * @defaultValue false
1671
+ */
1672
+ convertToLatest?: boolean;
1673
+ };
1467
1674
  //#endregion
1468
1675
  //#region src/CmcdReportConfig.d.ts
1469
1676
  /**
@@ -1530,6 +1737,22 @@ type CmcdEventReportConfig = CmcdReportConfig & {
1530
1737
  batchSize?: number;
1531
1738
  };
1532
1739
  //#endregion
1740
+ //#region src/CmcdEventsValidationResult.d.ts
1741
+ /**
1742
+ * The result of validating a multi-line CMCD event payload.
1743
+ *
1744
+ * Extends {@link CmcdValidationResult} with an array of decoded
1745
+ * {@link CmcdData} objects, one per event line.
1746
+ *
1747
+ * @public
1748
+ */
1749
+ type CmcdEventsValidationResult = CmcdValidationResult & {
1750
+ /**
1751
+ * The decoded CMCD data, one entry per event line.
1752
+ */
1753
+ data: CmcdData[];
1754
+ };
1755
+ //#endregion
1533
1756
  //#region src/CmcdHeaderKey.d.ts
1534
1757
  /**
1535
1758
  * A CMCD header key.
@@ -1654,6 +1877,8 @@ type CmcdRequestReport<D = unknown> = HttpRequest & {
1654
1877
  /**
1655
1878
  * The CMCD reporter.
1656
1879
  *
1880
+ * @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}
1881
+ *
1657
1882
  * @public
1658
1883
  */
1659
1884
  declare class CmcdReporter {
@@ -1789,6 +2014,24 @@ declare class CmcdReporter {
1789
2014
  private resetSession;
1790
2015
  }
1791
2016
  //#endregion
2017
+ //#region src/CmcdValidationOptions.d.ts
2018
+ /**
2019
+ * Options for CMCD validation functions.
2020
+ *
2021
+ * @public
2022
+ */
2023
+ type CmcdValidationOptions = {
2024
+ /**
2025
+ * Explicit CMCD version override. If not provided, the version is
2026
+ * inferred from the payload's `v` key, defaulting to 1.
2027
+ */
2028
+ version?: CmcdVersion;
2029
+ /**
2030
+ * The reporting mode of the payload.
2031
+ */
2032
+ reportingMode?: CmcdReportingMode;
2033
+ };
2034
+ //#endregion
1792
2035
  //#region src/decodeCmcd.d.ts
1793
2036
  /**
1794
2037
  * Decode a CMCD string to an object.
@@ -1798,6 +2041,8 @@ declare class CmcdReporter {
1798
2041
  *
1799
2042
  * @returns The decoded CMCD object.
1800
2043
  *
2044
+ * @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}
2045
+ *
1801
2046
  * @public
1802
2047
  *
1803
2048
  * @example
@@ -1817,6 +2062,8 @@ declare function decodeCmcd<T extends CmcdData = CmcdData>(cmcd: string, options
1817
2062
  *
1818
2063
  * @returns The encoded CMCD string.
1819
2064
  *
2065
+ * @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}
2066
+ *
1820
2067
  * @public
1821
2068
  *
1822
2069
  * @example
@@ -1833,6 +2080,8 @@ declare function encodeCmcd(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
1833
2080
  *
1834
2081
  * @returns The decoded CMCD data.
1835
2082
  *
2083
+ * @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}
2084
+ *
1836
2085
  * @public
1837
2086
  *
1838
2087
  * @example
@@ -1852,6 +2101,8 @@ declare function fromCmcdHeaders(headers: Record<string, string> | Headers, opti
1852
2101
  *
1853
2102
  * @returns The decoded CMCD data.
1854
2103
  *
2104
+ * @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}
2105
+ *
1855
2106
  * @public
1856
2107
  *
1857
2108
  * @example
@@ -1871,6 +2122,8 @@ declare function fromCmcdQuery(query: string | URLSearchParams, options?: CmcdDe
1871
2122
  *
1872
2123
  * @returns The decoded CMCD data.
1873
2124
  *
2125
+ * @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}
2126
+ *
1874
2127
  * @public
1875
2128
  *
1876
2129
  * @example
@@ -1890,6 +2143,8 @@ declare function fromCmcdUrl(url: string, options?: CmcdDecodeOptions): CmcdData
1890
2143
  *
1891
2144
  * @returns The CMCD header shards.
1892
2145
  *
2146
+ * @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}
2147
+ *
1893
2148
  * @public
1894
2149
  */
1895
2150
  declare function groupCmcdHeaders(cmcd: Cmcd, customHeaderMap?: Partial<CmcdHeaderMap>): Record<CmcdHeaderField, CmcdHeaderValue>;
@@ -2016,6 +2271,8 @@ declare function prepareCmcdData(obj: Record<string, any>, options?: CmcdEncodeO
2016
2271
  *
2017
2272
  * @returns The CMCD header shards.
2018
2273
  *
2274
+ * @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}
2275
+ *
2019
2276
  * @public
2020
2277
  *
2021
2278
  * @example
@@ -2032,6 +2289,8 @@ declare function toCmcdHeaders(cmcd: Cmcd, options?: CmcdEncodeOptions): Record<
2032
2289
  *
2033
2290
  * @returns The CMCD query arg.
2034
2291
  *
2292
+ * @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}
2293
+ *
2035
2294
  * @public
2036
2295
  *
2037
2296
  * @example
@@ -2048,6 +2307,8 @@ declare function toCmcdQuery(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
2048
2307
  *
2049
2308
  * @returns The URL encoded CMCD data.
2050
2309
  *
2310
+ * @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}
2311
+ *
2051
2312
  * @public
2052
2313
  */
2053
2314
  declare function toCmcdUrl(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
@@ -2064,137 +2325,44 @@ declare function toCmcdUrl(cmcd: Cmcd, options?: CmcdEncodeOptions): string;
2064
2325
  */
2065
2326
  declare function toCmcdValue<V extends SfBareItem, P>(value: V, params?: P): SfItem<V, P>;
2066
2327
  //#endregion
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
2328
+ //#region src/validateCmcd.d.ts
2097
2329
  /**
2098
- * Describes a single validation issue found in a CMCD payload.
2330
+ * Validates a CMCD payload by checking keys, values, and structure.
2099
2331
  *
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.
2332
+ * @example
2333
+ * {@includeCode ../test/validateCmcd.test.ts#example}
2121
2334
  *
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).
2335
+ * @param data - The CMCD payload to validate.
2336
+ * @param options - Validation options.
2337
+ * @returns The validation result.
2138
2338
  *
2139
- * Extends {@link CmcdValidationResult} with the decoded {@link CmcdData}.
2339
+ * @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}
2140
2340
  *
2141
2341
  * @public
2142
2342
  */
2143
- type CmcdDataValidationResult = CmcdValidationResult & {
2144
- /**
2145
- * The decoded CMCD data.
2146
- */
2147
- data: CmcdData;
2148
- };
2343
+ declare function validateCmcd(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2149
2344
  //#endregion
2150
- //#region src/CmcdEventsValidationResult.d.ts
2345
+ //#region src/validateCmcdEventReport.d.ts
2151
2346
  /**
2152
- * The result of validating a multi-line CMCD event payload.
2347
+ * Validates a full HTTP request as an event-mode payload.
2153
2348
  *
2154
- * Extends {@link CmcdValidationResult} with an array of decoded
2155
- * {@link CmcdData} objects, one per event line.
2349
+ * Accepts an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
2156
2350
  *
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.
2351
+ * This function validates that the request uses the POST method and has
2352
+ * the correct `Content-Type` header (`application/cmcd`) in addition to
2353
+ * validating the body content via {@link validateCmcdEvents}.
2169
2354
  *
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.
2355
+ * @param request - An `HttpRequest` to validate.
2356
+ * @param options - Validation options (excluding `reportingMode`).
2357
+ * @returns The validation result including decoded data per event line.
2187
2358
  *
2188
- * @example
2189
- * {@includeCode ../test/validateCmcd.test.ts#example}
2359
+ * @example {@includeCode ../test/validateCmcdEventReport.test.ts#example}
2190
2360
  *
2191
- * @param data - The CMCD payload to validate.
2192
- * @param options - Validation options.
2193
- * @returns The validation result.
2361
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#event-mode | CTA-5004-A Event Mode}
2194
2362
  *
2195
2363
  * @public
2196
2364
  */
2197
- declare function validateCmcd(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2365
+ declare function validateCmcdEventReport(request: HttpRequest, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdEventsValidationResult;
2198
2366
  //#endregion
2199
2367
  //#region src/validateCmcdEvents.d.ts
2200
2368
  /**
@@ -2202,17 +2370,19 @@ declare function validateCmcd(data: Record<string, unknown>, options?: CmcdValid
2202
2370
  *
2203
2371
  * This function decodes the string internally and validates it with
2204
2372
  * `reportingMode` set to `'event'`. The input may contain multiple
2205
- * newline-separated events (e.g. a `text/cmcd` POST body), in which
2373
+ * newline-separated events (e.g. an `application/cmcd` POST body), in which
2206
2374
  * case each line is validated independently and the results are merged.
2207
2375
  *
2208
- * @example
2209
- * {@includeCode ../test/validateCmcdEvents.test.ts#example}
2210
- *
2211
2376
  * @param cmcd - The raw CMCD-encoded string to validate. May contain
2212
2377
  * multiple newline-separated event lines.
2213
2378
  * @param options - Validation options (excluding `reportingMode`).
2214
2379
  * @returns The validation result including decoded data per event line.
2215
2380
  *
2381
+ * @example
2382
+ * {@includeCode ../test/validateCmcdEvents.test.ts#example}
2383
+ *
2384
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#body-definition | CTA-5004-A Body Definition}
2385
+ *
2216
2386
  * @public
2217
2387
  */
2218
2388
  declare function validateCmcdEvents(cmcd: string, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdEventsValidationResult;
@@ -2233,6 +2403,8 @@ declare function validateCmcdEvents(cmcd: string, options?: Omit<CmcdValidationO
2233
2403
  * @param options - Validation options (excluding `reportingMode`).
2234
2404
  * @returns The validation result including decoded data.
2235
2405
  *
2406
+ * @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}
2407
+ *
2236
2408
  * @public
2237
2409
  */
2238
2410
  declare function validateCmcdHeaders(headers: Record<string, string> | Headers, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdDataValidationResult;
@@ -2248,6 +2420,8 @@ declare function validateCmcdHeaders(headers: Record<string, string> | Headers,
2248
2420
  * @param options - Validation options.
2249
2421
  * @returns The validation result.
2250
2422
  *
2423
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reserved-keys | CTA-5004-A Reserved Keys}
2424
+ *
2251
2425
  * @public
2252
2426
  */
2253
2427
  declare function validateCmcdKeys(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
@@ -2258,20 +2432,22 @@ declare function validateCmcdKeys(data: Record<string, unknown>, options?: CmcdV
2258
2432
  *
2259
2433
  * Accepts a
2260
2434
  * {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
2261
- * object or an {@link @svta/cml-utils#HttpRequest | HttpRequest} object.
2435
+ * object or an {@link @svta/cml-utils!HttpRequest | HttpRequest} object.
2262
2436
  *
2263
2437
  * The function checks for CMCD data in the HTTP headers first. If CMCD
2264
2438
  * headers are found, validation includes shard-placement checks via
2265
2439
  * {@link validateCmcdHeaders}. Otherwise, the CMCD query parameter is
2266
2440
  * extracted from the URL and validated.
2267
2441
  *
2268
- * @example
2269
- * {@includeCode ../test/validateCmcdRequest.test.ts#example}
2270
- *
2271
2442
  * @param request - A `Request` or `HttpRequest` to validate.
2272
2443
  * @param options - Validation options (excluding `reportingMode`).
2273
2444
  * @returns The validation result including decoded data.
2274
2445
  *
2446
+ * @example
2447
+ * {@includeCode ../test/validateCmcdRequest.test.ts#example}
2448
+ *
2449
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#request-mode | CTA-5004-A Request Mode}
2450
+ *
2275
2451
  * @public
2276
2452
  */
2277
2453
  declare function validateCmcdRequest(request: Request | HttpRequest, options?: Omit<CmcdValidationOptions, "reportingMode">): CmcdDataValidationResult;
@@ -2287,6 +2463,8 @@ declare function validateCmcdRequest(request: Request | HttpRequest, options?: O
2287
2463
  * @param options - Validation options.
2288
2464
  * @returns The validation result.
2289
2465
  *
2466
+ * @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}
2467
+ *
2290
2468
  * @public
2291
2469
  */
2292
2470
  declare function validateCmcdStructure(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
@@ -2302,9 +2480,11 @@ declare function validateCmcdStructure(data: Record<string, unknown>, options?:
2302
2480
  * @param options - Validation options.
2303
2481
  * @returns The validation result.
2304
2482
  *
2483
+ * @see {@link https://cta-wave.github.io/Resources/common-media-client-data--cta-5004-b.html#reserved-keys | CTA-5004-A Reserved Keys}
2484
+ *
2305
2485
  * @public
2306
2486
  */
2307
2487
  declare function validateCmcdValues(data: Record<string, unknown>, options?: CmcdValidationOptions): CmcdValidationResult;
2308
2488
  //#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 };
2489
+ 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, 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, validateCmcdEventReport, validateCmcdEvents, validateCmcdHeaders, validateCmcdKeys, validateCmcdRequest, validateCmcdStructure, validateCmcdValues };
2310
2490
  //# sourceMappingURL=index.d.ts.map