@observertc/observer-js 1.0.0-beta.21 → 1.0.0-beta.23

package/dist/index.d.mts

@@ -12,7 +12,7 @@ type ExtensionStat = {
     /**
     * The payload of the extension stats the custom app provides
     */
-    payload?: string;
+    payload?: Record<string, boolean | string | number>;
 };
 /**
 * A list of additional client events.
@@ -23,9 +23,9 @@ type ClientMetaData = {
     */
     type: string;
     /**
-    * The value associated with the event, if applicable.
+    * The attributes of the meta data entry, if applicable.
     */
-    payload?: string;
+    payload?: Record<string, boolean | string | number>;
     /**
     * The unique identifier of the peer connection for which the event was generated.
     */
@@ -52,15 +52,13 @@ type ClientIssue = {
     */
     type: string;
     /**
-    * Identity of a **stateful** issue, shared by its raise entry and its `<type>-resolved`
-    * companion, so a server can open an active issue on the raise and close it on the match
-    * (client-monitor-js >= 4.6.0, `sendResolvedIssuesToServer`). One-shot issues have no key.
+    * Identifier of the related issue or resolution when it is provided.
     */
     key?: string;
     /**
-    * The value associated with the event, if applicable.
+    * The attributes of the issue, if applicable.
     */
-    payload?: string;
+    payload?: Record<string, boolean | string | number>;
     /**
     * The timestamp in epoch format when the event was generated.
     */
@@ -75,16 +73,16 @@ type ClientEvent = {
     */
     type: string;
     /**
-    * The value associated with the event, if applicable.
+    * The attributes of the event, if applicable.
     */
-    payload?: string;
+    payload?: Record<string, boolean | string | number>;
     /**
     * The timestamp in epoch format when the event was generated.
     */
     timestamp?: number;
 };
 /**
-* Certificates
+* Certificate Stats
 */
 type CertificateStats = {
     /**
@@ -108,7 +106,7 @@ type CertificateStats = {
     */
     base64Certificate?: string;
     /**
-    * The certificate ID of the issuer (nullable).
+    * The certificate ID of the issuer.
     */
     issuerCertificateId?: string;
     /**
@@ -125,7 +123,7 @@ type IceCandidatePairStats = {
     */
     id: string;
     /**
-    * The timestamp of when the stats were recorded, in seconds.
+    * The timestamp of when the stats were recorded, in milliseconds.
     */
     timestamp: number;
     /**
@@ -140,7 +138,10 @@ type IceCandidatePairStats = {
     * The ID of the remote ICE candidate in this pair.
     */
     remoteCandidateId?: string;
-    state?: 'new' | 'in-progress' | 'waiting' | 'failed' | 'succeeded' | 'cancelled' | 'inprogress';
+    /**
+    * The checklist state of this candidate pair. Values follow the W3C RTCStatsIceCandidatePairState enum (frozen, waiting, in-progress, failed, succeeded). Two further values are accepted for backward compatibility and are not part of the current spec: `new` (never standardised) and `cancelled` (removed from the spec after 2016).
+    */
+    state?: "new" | "frozen" | "in-progress" | "waiting" | "failed" | "succeeded" | "cancelled" | "inprogress";
     /**
     * Whether this candidate pair has been nominated.
     */
@@ -235,7 +236,7 @@ type IceCandidateStats = {
     */
     transportId?: string;
     /**
-    * The IP address of the ICE candidate (nullable).
+    * The IP address of the ICE candidate.
     */
     address?: string;
     /**
@@ -364,7 +365,15 @@ type IceTransportStats = {
     */
     selectedCandidatePairChanges?: number;
     /**
-    * Additional information attached to this stats
+    * Number of congestion control feedback (CCFB) messages sent on this transport.
+    */
+    ccfbMessagesSent?: number;
+    /**
+    * Number of congestion control feedback (CCFB) messages received on this transport.
+    */
+    ccfbMessagesReceived?: number;
+    /**
+    * Additional information attached to this stats.
     */
     attachments?: Record<string, unknown>;
 };
@@ -545,7 +554,7 @@ type MediaSourceStats = {
     attachments?: Record<string, unknown>;
 };
 /**
-* Remote Outbound RTPs
+* Remote Outbound RTP Stats
 */
 type RemoteOutboundRtpStats = {
     /**
@@ -631,7 +640,24 @@ type QualityLimitationDurations = {
     other: number;
 };
 /**
-* Outbound RTPs
+* Cumulative PSNR measurements for Y, U, V components.
+*/
+type PsnrSum = {
+    /**
+    * PSNR value for the Y (luminance) component.
+    */
+    y: number;
+    /**
+    * PSNR value for the U (chrominance) component.
+    */
+    u: number;
+    /**
+    * PSNR value for the V (chrominance) component.
+    */
+    v: number;
+};
+/**
+* Outbound RTP Stats
 */
 type OutboundRtpStats = {
     /**
@@ -683,6 +709,10 @@ type OutboundRtpStats = {
     */
     rid?: string;
     /**
+    * Index of the encoding in the encoding array.
+    */
+    encodingIndex?: number;
+    /**
     * The total number of header bytes sent on this stream.
     */
     headerBytesSent?: number;
@@ -739,6 +769,14 @@ type OutboundRtpStats = {
     */
     qpSum?: number;
     /**
+    * Cumulative PSNR measurements for Y, U, V components.
+    */
+    psnrSum?: PsnrSum;
+    /**
+    * Total number of PSNR measurements collected.
+    */
+    psnrMeasurements?: number;
+    /**
     * The total time spent encoding frames on this stream in seconds.
     */
     totalEncodeTime?: number;
@@ -747,10 +785,14 @@ type OutboundRtpStats = {
     */
     totalPacketSendDelay?: number;
     /**
-    * The reason for any quality limitation on this stream.
+    * The reason for any quality limitation on this stream (e.g., 'cpu', 'bandwidth', 'other').
     */
     qualityLimitationReason?: string;
     /**
+    * The duration of quality limitation reasons categorized by type.
+    */
+    qualityLimitationDurations?: QualityLimitationDurations;
+    /**
     * The number of resolution changes due to quality limitations.
     */
     qualityLimitationResolutionChanges?: number;
@@ -771,7 +813,7 @@ type OutboundRtpStats = {
     */
     encoderImplementation?: string;
     /**
-    * Indicates whether the encoder is power efficient.
+    * Indicates whether the encoder is power-efficient.
     */
     powerEfficientEncoder?: boolean;
     /**
@@ -783,16 +825,16 @@ type OutboundRtpStats = {
     */
     scalabilityMode?: string;
     /**
-    * The duration of quality limitation reasons categorized by type.
+    * Number of packets sent with ECT(1) congestion marking.
     */
-    qualityLimitationDurations?: QualityLimitationDurations;
+    packetsSentWithEct1?: number;
     /**
     * Additional information attached to this stats.
     */
     attachments?: Record<string, unknown>;
 };
 /**
-* Remote Inbound RTPs
+* Remote Inbound RTP Stats
 */
 type RemoteInboundRtpStats = {
     /**
@@ -824,6 +866,22 @@ type RemoteInboundRtpStats = {
     */
     packetsReceived?: number;
     /**
+    * Total number of RTP packets received for this SSRC marked with the ECT(1) marking.
+    */
+    packetsReceivedWithEct1?: number;
+    /**
+    * Total number of RTP packets received for this SSRC marked with the CE marking.
+    */
+    packetsReceivedWithCe?: number;
+    /**
+    * Total number of RTP packets for which an RFC8888 report has been sent with a zero R bit.
+    */
+    packetsReportedAsLost?: number;
+    /**
+    * Total number of RTP packets reported as lost but later recovered in a subsequent RFC8888 report.
+    */
+    packetsReportedAsLostButRecovered?: number;
+    /**
     * The total number of packets lost on this stream.
     */
     packetsLost?: number;
@@ -852,12 +910,16 @@ type RemoteInboundRtpStats = {
     */
     roundTripTimeMeasurements?: number;
     /**
+    * Number of packets with ECT(1) marking that were bleached by a middlebox.
+    */
+    packetsWithBleachedEct1Marking?: number;
+    /**
     * Additional information attached to this stats
     */
     attachments?: Record<string, unknown>;
 };
 /**
-* Inbound RTPs
+* Inbound RTP Stats
 */
 type InboundRtpStats = {
     /**
@@ -893,6 +955,22 @@ type InboundRtpStats = {
     */
     packetsReceived?: number;
     /**
+    * Total number of RTP packets received for this SSRC marked with the ECT(1) marking.
+    */
+    packetsReceivedWithEct1?: number;
+    /**
+    * Total number of RTP packets received for this SSRC marked with the CE marking.
+    */
+    packetsReceivedWithCe?: number;
+    /**
+    * Total number of RTP packets for which an RFC8888 report has been sent with a zero R bit.
+    */
+    packetsReportedAsLost?: number;
+    /**
+    * Total number of RTP packets reported as lost but later recovered in a subsequent RFC8888 report.
+    */
+    packetsReportedAsLostButRecovered?: number;
+    /**
     * Number of packets lost on the RTP stream.
     */
     packetsLost?: number;
@@ -901,7 +979,7 @@ type InboundRtpStats = {
     */
     jitter?: number;
     /**
-    * The MediaStream ID of the RTP stream.
+    * The media stream identification tag from the SDP media section.
     */
     mid?: string;
     /**
@@ -997,15 +1075,15 @@ type InboundRtpStats = {
     */
     bytesReceived?: number;
     /**
-    * Number of NACKs sent.
+    * Number of NACKs received.
     */
     nackCount?: number;
     /**
-    * Number of Full Intra Requests sent.
+    * Number of Full Intra Requests received.
     */
     firCount?: number;
     /**
-    * Number of Picture Loss Indications sent.
+    * Number of Picture Loss Indications received.
     */
     pliCount?: number;
     /**
@@ -1183,10 +1261,14 @@ type OutboundTrackSample = {
     */
     kind: string;
     /**
-    * Calculated score for track (details should be added to attachments)
+    * Calculated score for track (details should be added to scoreReasons)
     */
     score?: number;
     /**
+    * Reasons for the score calculation, mapping each reason to how much it contributed to the score
+    */
+    scoreReasons?: Record<string, number>;
+    /**
     * Additional information attached to this stats
     */
     attachments?: Record<string, unknown>;
@@ -1208,16 +1290,20 @@ type InboundTrackSample = {
     */
     kind: string;
     /**
-    * Calculated score for track (details should be added to attachments)
+    * Calculated score for track (details should be added to scoreReasons)
     */
     score?: number;
     /**
+    * Reasons for the score calculation, mapping each reason to how much it contributed to the score
+    */
+    scoreReasons?: Record<string, number>;
+    /**
     * Additional information attached to this stats
     */
     attachments?: Record<string, unknown>;
 };
 /**
-* docs
+* A sample containing statistics and metrics for a WebRTC peer connection
 */
 type PeerConnectionSample = {
     /**
@@ -1229,10 +1315,14 @@ type PeerConnectionSample = {
     */
     attachments?: Record<string, unknown>;
     /**
-    * Calculated score for peer connection (details should be added to attachments)
+    * Calculated score for peer connection (details should be added to scoreReasons)
     */
     score?: number;
     /**
+    * Reasons for the score calculation, mapping each reason to how much it contributed to the score
+    */
+    scoreReasons?: Record<string, number>;
+    /**
     * Inbound Track Stats items
     */
     inboundTracks?: InboundTrackSample[];
@@ -1245,19 +1335,19 @@ type PeerConnectionSample = {
     */
     codecs?: CodecStats[];
     /**
-    * Inbound RTPs
+    * Inbound RTP Stats
     */
     inboundRtps?: InboundRtpStats[];
     /**
-    * Remote Inbound RTPs
+    * Remote Inbound RTP Stats
     */
     remoteInboundRtps?: RemoteInboundRtpStats[];
     /**
-    * Outbound RTPs
+    * Outbound RTP Stats
     */
     outboundRtps?: OutboundRtpStats[];
     /**
-    * Remote Outbound RTPs
+    * Remote Outbound RTP Stats
     */
     remoteOutboundRtps?: RemoteOutboundRtpStats[];
     /**
@@ -1289,7 +1379,7 @@ type PeerConnectionSample = {
     */
     iceCandidatePairs?: IceCandidatePairStats[];
     /**
-    * Certificates
+    * Certificate Stats
     */
     certificates?: CertificateStats[];
 };
@@ -1314,10 +1404,14 @@ type ClientSample = {
     */
     attachments?: Record<string, unknown>;
     /**
-    * Calculated score for client (details should be added to attachments)
+    * Calculated score for client (details should be added to scoreReasons)
     */
     score?: number;
     /**
+    * Reasons for the score calculation, mapping each reason to how much it contributed to the score
+    */
+    scoreReasons?: Record<string, number>;
+    /**
     * Samples taken PeerConnections
     */
     peerConnections?: PeerConnectionSample[];
@@ -2490,8 +2584,9 @@ declare function concludeObserverIssue(spread: ObserverIssueSpread): IssueConclu
  *
  * ### Why this is not `ClientIssue`
  *
- * `ClientIssue` is a **wire** type: it arrives inside a `ClientSample`, so its `payload` has to be a
- * string. Server-raised findings were reusing it, which forced every detector to `JSON.stringify` a
+ * `ClientIssue` is a **wire** type: it arrives inside a `ClientSample`, so its `payload` is bound to
+ * what the schema can carry — a record of primitives since schema 3.5.0, a JSON string on samples
+ * from earlier clients. Server-raised findings were reusing it, which forced every detector to `JSON.stringify` a
  * perfectly good object on the way out and every handler to `JSON.parse` it back on the way in —
  * paying serialisation on a path where nothing is ever serialised, and losing type information in
  * both directions. These go straight to an in-process handler, so they carry the object.