@furious.luke/argus-js 0.5.4 → 0.5.6

package/dist/index.d.cts

@@ -102,6 +102,12 @@ type SignalMessage = {
     turn_username?: string;
     turn_credential?: string;
     read_token?: string;
+} | {
+    type: "placement_redirect";
+    gateway_url: string;
+} | {
+    type: "unavailable";
+    retry_after_ms?: number;
 };
 /**
  * Callbacks emitted by the Publisher during its lifecycle.
@@ -125,6 +131,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called for every periodic connection-stats sample while connected — the raw
+     * feed behind {@link onConnectionQualityChange}. Fires at
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -138,6 +157,86 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A coarse assessment of the uplink to the media server, derived from periodic
+ * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -165,7 +264,12 @@ interface GatewayReadyInfo {
  * Options for publishing a media stream.
  */
 interface PublisherOptions {
-    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    /**
+     * Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are
+     * opened at once; the region whose `accepted` returns first is selected on
+     * network path, and only that region places the stream. The rest are held as
+     * standbys the publisher fails over to.
+     */
     gatewayURLs: string[];
     /** The short-lived join token from POST /api/streams. */
     token: string;
@@ -187,11 +291,26 @@ interface PublisherOptions {
      */
     turnTransportPolicy?: TurnTransportPolicy;
     /**
-     * Overall deadline for the initial accepted/proceed/ready gateway race.
-     * Unaccepted sockets are replaced after three seconds within this deadline.
-     * Defaults to 20 seconds.
+     * Overall deadline for the initial accepted/proceed/ready gateway race,
+     * spanning selection, placement, and any failovers. Sockets that have not sent
+     * `accepted` are replaced after three seconds within this deadline. Defaults to
+     * 20 seconds.
      */
     gatewayHandshakeTimeoutMs?: number;
+    /**
+     * How long the selected region has to return `ready` before the publisher
+     * abandons it and fails over to the next-fastest acknowledgement. This is a
+     * backstop for a region whose socket stays open but silent (a hung placement);
+     * a socket that closes or errors fails over immediately regardless. It is
+     * deliberately generous — placement includes the selected region's own
+     * control-plane round-trips, and a short deadline would abandon exactly the
+     * user-close-but-control-plane-distant regions this race is meant to prefer.
+     * Defaults to 8 seconds and is capped at 20 seconds: the gateway reaps a
+     * standby socket that has been accepted but not yet told to proceed, so the
+     * failover window must stay below that deadline or standbys would disappear
+     * before the browser fails over to them.
+     */
+    gatewayFailoverTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
     /**
@@ -206,6 +325,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -251,6 +388,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -433,6 +575,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -662,4 +811,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };

package/dist/index.d.ts

@@ -102,6 +102,12 @@ type SignalMessage = {
     turn_username?: string;
     turn_credential?: string;
     read_token?: string;
+} | {
+    type: "placement_redirect";
+    gateway_url: string;
+} | {
+    type: "unavailable";
+    retry_after_ms?: number;
 };
 /**
  * Callbacks emitted by the Publisher during its lifecycle.
@@ -125,6 +131,19 @@ interface PublisherCallbacks {
     onUserTextResult?: (event: UserTextResultEvent) => void;
     /** Called once the explicitly requested outbound speech track arrives. */
     onSpeechTrack?: (track: MediaStreamTrack, streams: readonly MediaStream[]) => void;
+    /**
+     * Called for every periodic connection-stats sample while connected — the raw
+     * feed behind {@link onConnectionQualityChange}. Fires at
+     * {@link PublisherOptions.connectionStatsIntervalMs}.
+     */
+    onConnectionStats?: (sample: ConnectionStatsSample) => void;
+    /**
+     * Called when the derived connection-quality level changes (including the
+     * first assessment after connecting). Downgrades are debounced; upgrades fire
+     * immediately. Use this to react to a degrading network — e.g. warn the user
+     * or drop a secondary track.
+     */
+    onConnectionQualityChange?: (quality: ConnectionQuality) => void;
 }
 interface AssistantTextEvent {
     utteranceId: string;
@@ -138,6 +157,86 @@ interface UserTextResultEvent {
     accepted: boolean;
     reason?: string;
 }
+/**
+ * A coarse assessment of the uplink to the media server, derived from periodic
+ * WebRTC stats. Ordered worst-last by severity: `"good"` is a healthy
+ * connection, `"critical"` is barely usable.
+ */
+type ConnectionQualityLevel = "good" | "fair" | "poor" | "critical";
+/**
+ * One periodic sample of the outbound connection's health, taken from
+ * `RTCPeerConnection.getStats()`. Packet loss and send bitrate are windowed over
+ * the interval since the previous sample (the first sample covers the session so
+ * far); the rest are point-in-time readings. A field is `null` when the browser
+ * did not report the underlying stat for this sample.
+ */
+interface ConnectionStatsSample {
+    /** Monotonic clock timestamp (ms) when the sample was taken. */
+    timestamp: number;
+    /**
+     * Fraction of outbound RTP packets lost, in `0..1` — the primary quality
+     * signal. A traffic-weighted mean of each stream's loss fraction: a stream uses
+     * its remote `fractionLost` (its loss ratio over the last RTCP report interval)
+     * when present, otherwise its windowed
+     * `Δpacketslost / Δ(packetsSent - retransmittedPacketsSent)`. Both kinds of
+     * stream are combined, so a lossy stream is never dropped for lacking
+     * `fractionLost`.
+     */
+    lossRatio: number;
+    /** Round-trip time in milliseconds, or `null` if unknown. */
+    rttMs: number | null;
+    /** Inter-arrival jitter in milliseconds, or `null` if unknown. */
+    jitterMs: number | null;
+    /** ICE-estimated available outgoing bitrate in bits/sec, or `null` if unknown. */
+    availableOutgoingBitrate: number | null;
+    /** Actual send bitrate over the interval in bits/sec, or `null` if unknown. */
+    sendBitrate: number | null;
+    /**
+     * Why the encoder is limiting quality: `"none"`, `"cpu"`, `"bandwidth"`, or
+     * `"other"`. `null` when no video is being sent. `"bandwidth"` is treated as a
+     * degradation signal by the default classifier.
+     */
+    qualityLimitationReason: string | null;
+    /** Cumulative NACKs received on outbound media, or `null` if unknown. */
+    nackCount: number | null;
+    /** Cumulative PLIs received on outbound media, or `null` if unknown. */
+    pliCount: number | null;
+}
+/**
+ * A committed connection-quality assessment, delivered to
+ * {@link PublisherCallbacks.onConnectionQualityChange} whenever the level
+ * changes. `sample` is the reading that triggered the transition.
+ */
+interface ConnectionQuality {
+    level: ConnectionQualityLevel;
+    sample: ConnectionStatsSample;
+}
+/**
+ * Thresholds mapping a {@link ConnectionStatsSample} to a
+ * {@link ConnectionQualityLevel}. Packet loss is the primary axis; RTT and
+ * jitter can only push the assessment to a worse level, never a better one, and
+ * a `"bandwidth"` encoder limitation forces at least `"fair"`. Any subset may be
+ * overridden via {@link PublisherOptions.connectionQualityThresholds}; the rest
+ * keep their defaults.
+ */
+interface ConnectionQualityThresholds {
+    /** Loss ratio (`0..1`) at or above which quality is at least `"fair"`. Default `0.02`. */
+    fairLossRatio: number;
+    /** Loss ratio at or above which quality is at least `"poor"`. Default `0.05`. */
+    poorLossRatio: number;
+    /** Loss ratio at or above which quality is `"critical"`. Default `0.12`. */
+    criticalLossRatio: number;
+    /** RTT (ms) at or above which quality is at least `"fair"`. Default `300`. */
+    fairRttMs: number;
+    /** RTT (ms) at or above which quality is at least `"poor"`. Default `600`. */
+    poorRttMs: number;
+    /** RTT (ms) at or above which quality is `"critical"`. Default `1000`. */
+    criticalRttMs: number;
+    /** Jitter (ms) at or above which quality is at least `"fair"`. Default `50`. */
+    fairJitterMs: number;
+    /** Jitter (ms) at or above which quality is at least `"poor"`. Default `150`. */
+    poorJitterMs: number;
+}
 type PublisherRecoveryState = "recovering" | "recovered" | "failed";
 type PublisherRecoveryAction = "sender_restart" | "ice_restart";
 type PublisherRecoveryFailureReason = "capture_ended" | "automatic_recovery_failed";
@@ -165,7 +264,12 @@ interface GatewayReadyInfo {
  * Options for publishing a media stream.
  */
 interface PublisherOptions {
-    /** Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are raced simultaneously. */
+    /**
+     * Gateway WebSocket URLs returned by POST /api/streams `gateway_urls`. All are
+     * opened at once; the region whose `accepted` returns first is selected on
+     * network path, and only that region places the stream. The rest are held as
+     * standbys the publisher fails over to.
+     */
     gatewayURLs: string[];
     /** The short-lived join token from POST /api/streams. */
     token: string;
@@ -187,11 +291,26 @@ interface PublisherOptions {
      */
     turnTransportPolicy?: TurnTransportPolicy;
     /**
-     * Overall deadline for the initial accepted/proceed/ready gateway race.
-     * Unaccepted sockets are replaced after three seconds within this deadline.
-     * Defaults to 20 seconds.
+     * Overall deadline for the initial accepted/proceed/ready gateway race,
+     * spanning selection, placement, and any failovers. Sockets that have not sent
+     * `accepted` are replaced after three seconds within this deadline. Defaults to
+     * 20 seconds.
      */
     gatewayHandshakeTimeoutMs?: number;
+    /**
+     * How long the selected region has to return `ready` before the publisher
+     * abandons it and fails over to the next-fastest acknowledgement. This is a
+     * backstop for a region whose socket stays open but silent (a hung placement);
+     * a socket that closes or errors fails over immediately regardless. It is
+     * deliberately generous — placement includes the selected region's own
+     * control-plane round-trips, and a short deadline would abandon exactly the
+     * user-close-but-control-plane-distant regions this race is meant to prefer.
+     * Defaults to 8 seconds and is capped at 20 seconds: the gateway reaps a
+     * standby socket that has been accepted but not yet told to proceed, so the
+     * failover window must stay below that deadline or standbys would disappear
+     * before the browser fails over to them.
+     */
+    gatewayFailoverTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
     /**
@@ -206,6 +325,24 @@ interface PublisherOptions {
     preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
+    /**
+     * How often, in milliseconds, to poll `RTCPeerConnection.getStats()` for
+     * connection-quality assessment once connected. Defaults to 2000. Set to 0 to
+     * disable stats polling entirely — neither {@link PublisherCallbacks.onConnectionStats}
+     * nor {@link PublisherCallbacks.onConnectionQualityChange} will fire.
+     */
+    connectionStatsIntervalMs?: number;
+    /**
+     * Overrides for the connection-quality classification thresholds. Any omitted
+     * field keeps its default. See {@link ConnectionQualityThresholds}.
+     */
+    connectionQualityThresholds?: Partial<ConnectionQualityThresholds>;
+    /**
+     * Number of consecutive worse-than-current samples required before a quality
+     * downgrade is committed, damping transient blips. Improvements are reported
+     * on the first better sample. Defaults to 2; values below 1 are treated as 1.
+     */
+    connectionQualityDebounceSamples?: number;
     /** Callbacks for lifecycle events. */
     callbacks?: PublisherCallbacks;
 }
@@ -251,6 +388,11 @@ declare class Publisher {
     private gatewayURL;
     private lastReportedICEPath;
     private watchedICETransports;
+    private connectionStatsTimer;
+    private statsSampleInFlight;
+    private lastStatsSample;
+    private currentQualityLevel;
+    private qualityDowngradeStreak;
     private stopped;
     private lifecycleGeneration;
     private runAbort;
@@ -433,6 +575,13 @@ declare class Publisher {
     private releaseLocalCandidateBatch;
     private applyAnswered;
     private watchSelectedICEPairChanges;
+    private startConnectionStatsLoop;
+    private stopConnectionStatsLoop;
+    private sampleConnectionQuality;
+    private buildStatsSample;
+    private resolveQualityThresholds;
+    private classifyQuality;
+    private updateConnectionQuality;
     private reportSelectedICEPath;
     private completeMediaRecovery;
     private failMediaRecovery;
@@ -662,4 +811,4 @@ interface CaptureMicrophoneOptions {
  */
 declare function captureMicrophone(opts?: CaptureMicrophoneOptions): Promise<MediaStream>;
 
-export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };
+export { type AssistantTextEvent, type CaptureCameraOptions, type CaptureMicrophoneOptions, type CaptureScreenOptions, type ConnectionQuality, type ConnectionQualityLevel, type ConnectionQualityThresholds, type ConnectionStatsSample, type GatewayReadyInfo, Publisher, type PublisherCallbacks, type PublisherOptions, type PublisherRecoveryAction, type PublisherRecoveryEvent, type PublisherRecoveryFailureReason, type PublisherRecoveryState, type SignalMessage, type TrackLabel, type TrackType, type TurnTransportPolicy, type UserTextResultEvent, type VideoTrackType, captureCamera, captureMicrophone, captureScreen };