@decartai/sdk 0.0.67 → 0.0.68

package/README.md

@@ -79,6 +79,16 @@ Options:
 - `"auto"` — mirror when the input track reports `facingMode: "user"` (mobile front cameras).
 - `true` — always mirror (e.g. desktop webcams).
 
+#### Output resolution
+
+```ts
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  resolution: "1080p", // default: "720p"
+  // ...
+});
+```
+
 ### Async Processing (Queue API)
 
 For video generation jobs, use the queue API to submit jobs and poll for results:

package/dist/index.d.ts

@@ -5,11 +5,11 @@ import { ProcessClient } from "./process/client.js";
 import { JobStatus, JobStatusResponse, JobSubmitResponse, QueueJobResult, QueueSubmitAndPollOptions, QueueSubmitOptions } from "./queue/types.js";
 import { QueueClient } from "./queue/client.js";
 import { DecartSDKError, ERROR_CODES } from "./utils/errors.js";
-import { ConnectionPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, IceCandidateEvent, IceStateEvent, PeerConnectionStateEvent, PhaseTimingEvent, ReconnectEvent, SelectedCandidatePairEvent, SignalingStateEvent, VideoStallEvent } from "./realtime/diagnostics.js";
 import { ConnectionState } from "./realtime/types.js";
+import { ConnectionPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, IceCandidateEvent, IceStateEvent, PeerConnectionStateEvent, PhaseTimingEvent, ReconnectEvent, SelectedCandidatePairEvent, SignalingStateEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
+import { WebRTCStats } from "./realtime/observability/webrtc-stats.js";
 import { SetInput } from "./realtime/methods.js";
 import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
-import { WebRTCStats } from "./realtime/webrtc-stats.js";
 import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState } from "./realtime/client.js";
 import { ModelState } from "./shared/types.js";
 import { CreateTokenOptions, CreateTokenResponse, TokensClient } from "./tokens/client.js";

package/dist/realtime/client.d.ts

@@ -1,9 +1,9 @@
 import { CustomModelDefinition, ModelDefinition } from "../shared/model.js";
 import { DecartSDKError } from "../utils/errors.js";
-import { DiagnosticEvent } from "./diagnostics.js";
 import { ConnectionState } from "./types.js";
+import { DiagnosticEvent } from "./observability/diagnostics.js";
+import { WebRTCStats } from "./observability/webrtc-stats.js";
 import { SetInput } from "./methods.js";
-import { WebRTCStats } from "./webrtc-stats.js";
 import { z } from "zod";
 
 //#region src/realtime/client.d.ts
@@ -37,6 +37,10 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
   }, z.core.$strip>>;
   customizeOffer: z.ZodOptional<z.ZodCustom<z.core.$InferInnerFunctionTypeAsync<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>, z.core.$InferInnerFunctionTypeAsync<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>>;
   mirror: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodBoolean]>>;
+  resolution: z.ZodOptional<z.ZodEnum<{
+    "720p": "720p";
+    "1080p": "1080p";
+  }>>;
 }, z.core.$strip>;
 type RealTimeClientConnectOptions = Omit<z.infer<typeof realTimeClientConnectOptionsSchema>, "model"> & {
   model: ModelDefinition | CustomModelDefinition;

package/dist/realtime/client.js

@@ -4,10 +4,9 @@ import { modelStateSchema } from "../shared/types.js";
 import { createEventBuffer } from "./event-buffer.js";
 import { realtimeMethods } from "./methods.js";
 import { createMirroredStream, shouldMirrorTrack } from "./mirror-stream.js";
+import { RealtimeObservability } from "./observability/realtime-observability.js";
 import { decodeSubscribeToken, encodeSubscribeToken } from "./subscribe-client.js";
-import { NullTelemetryReporter, TelemetryReporter } from "./telemetry-reporter.js";
 import { WebRTCManager } from "./webrtc-manager.js";
-import { WebRTCStatsCollector } from "./webrtc-stats.js";
 import { z } from "zod";
 
 //#region src/realtime/client.ts
@@ -58,14 +57,15 @@ const realTimeClientConnectOptionsSchema = z.object({
 	onRemoteStream: z.custom((val) => typeof val === "function", { message: "onRemoteStream must be a function" }),
 	initialState: realTimeClientInitialStateSchema.optional(),
 	customizeOffer: createAsyncFunctionSchema(z.function()).optional(),
-	mirror: z.union([z.literal("auto"), z.boolean()]).optional()
+	mirror: z.union([z.literal("auto"), z.boolean()]).optional(),
+	resolution: z.enum(["720p", "1080p"]).optional()
 });
 const createRealTimeClient = (opts) => {
 	const { baseUrl, apiKey, integration, logger } = opts;
 	const connect = async (stream, options) => {
 		const parsedOptions = realTimeClientConnectOptionsSchema.safeParse(options);
 		if (!parsedOptions.success) throw parsedOptions.error;
-		const { onRemoteStream, initialState } = parsedOptions.data;
+		const { onRemoteStream, initialState, resolution } = parsedOptions.data;
 		const mirror = parsedOptions.data.mirror ?? false;
 		let inputStream = stream ?? new MediaStream();
 		let mirroredStream;
@@ -79,8 +79,16 @@ const createRealTimeClient = (opts) => {
 			logger.warn("Failed to mirror input stream; falling back to un-mirrored input", { error: error instanceof Error ? error.message : String(error) });
 		}
 		let webrtcManager;
-		let telemetryReporter = new NullTelemetryReporter();
-		let handleConnectionStateChange = null;
+		const { emitter: eventEmitter, emitOrBuffer, flush, stop } = createEventBuffer();
+		const observability = new RealtimeObservability({
+			telemetryEnabled: opts.telemetryEnabled,
+			apiKey,
+			model: options.model.name,
+			integration,
+			logger,
+			onDiagnostic: (event) => emitOrBuffer("diagnostic", event),
+			onStats: opts.telemetryEnabled ? (stats) => emitOrBuffer("stats", stats) : void 0
+		});
 		try {
 			const initialImage = initialState?.image ? await imageToBase64(initialState.image) : void 0;
 			const initialPrompt = initialState?.prompt ? {
@@ -88,22 +96,15 @@ const createRealTimeClient = (opts) => {
 				enhance: initialState.prompt.enhance
 			} : void 0;
 			const url = `${baseUrl}${options.model.urlPath}`;
-			const { emitter: eventEmitter, emitOrBuffer, flush, stop } = createEventBuffer();
+			const resolutionQs = resolution ? `&resolution=${encodeURIComponent(resolution)}` : "";
 			webrtcManager = new WebRTCManager({
-				webrtcUrl: `${url}?api_key=${encodeURIComponent(apiKey)}&model=${encodeURIComponent(options.model.name)}`,
+				webrtcUrl: `${url}?api_key=${encodeURIComponent(apiKey)}&model=${encodeURIComponent(options.model.name)}${resolutionQs}`,
 				integration,
 				logger,
-				onDiagnostic: (name, data) => {
-					emitOrBuffer("diagnostic", {
-						name,
-						data
-					});
-					addTelemetryDiagnostic(name, data);
-				},
+				observability,
 				onRemoteStream,
 				onConnectionStateChange: (state) => {
 					emitOrBuffer("connectionChange", state);
-					handleConnectionStateChange?.(state);
 				},
 				onError: (error) => {
 					logger.error("WebRTC error", { error: error.message });
@@ -118,42 +119,10 @@ const createRealTimeClient = (opts) => {
 			const manager = webrtcManager;
 			let sessionId = null;
 			let subscribeToken = null;
-			const pendingTelemetryDiagnostics = [];
-			let telemetryReporterReady = false;
-			const addTelemetryDiagnostic = (name, data, timestamp = Date.now()) => {
-				if (!opts.telemetryEnabled) return;
-				if (!telemetryReporterReady) {
-					pendingTelemetryDiagnostics.push({
-						name,
-						data,
-						timestamp
-					});
-					return;
-				}
-				telemetryReporter.addDiagnostic({
-					name,
-					data,
-					timestamp
-				});
-			};
 			const sessionIdListener = (msg) => {
 				subscribeToken = encodeSubscribeToken(msg.session_id, msg.server_ip, msg.server_port);
 				sessionId = msg.session_id;
-				if (opts.telemetryEnabled) {
-					if (telemetryReporterReady) telemetryReporter.stop();
-					const reporter = new TelemetryReporter({
-						apiKey,
-						sessionId: msg.session_id,
-						model: options.model.name,
-						integration,
-						logger
-					});
-					reporter.start();
-					telemetryReporter = reporter;
-					telemetryReporterReady = true;
-					for (const diagnostic of pendingTelemetryDiagnostics) telemetryReporter.addDiagnostic(diagnostic);
-					pendingTelemetryDiagnostics.length = 0;
-				}
+				observability.sessionStarted(msg.session_id);
 			};
 			manager.getWebsocketMessageEmitter().on("sessionId", sessionIdListener);
 			const tickListener = (msg) => {
@@ -162,74 +131,13 @@ const createRealTimeClient = (opts) => {
 			manager.getWebsocketMessageEmitter().on("generationTick", tickListener);
 			await manager.connect(inputStream);
 			const methods = realtimeMethods(manager, imageToBase64);
-			let statsCollector = null;
-			let statsCollectorPeerConnection = null;
-			const STALL_FPS_THRESHOLD = .5;
-			let videoStalled = false;
-			let stallStartMs = 0;
-			const startStatsCollection = () => {
-				statsCollector?.stop();
-				videoStalled = false;
-				stallStartMs = 0;
-				statsCollector = new WebRTCStatsCollector();
-				const pc = manager.getPeerConnection();
-				statsCollectorPeerConnection = pc;
-				if (pc) statsCollector.start(pc, (stats) => {
-					emitOrBuffer("stats", stats);
-					telemetryReporter.addStats(stats);
-					const fps = stats.video?.framesPerSecond ?? 0;
-					if (!videoStalled && stats.video && fps < STALL_FPS_THRESHOLD) {
-						videoStalled = true;
-						stallStartMs = Date.now();
-						emitOrBuffer("diagnostic", {
-							name: "videoStall",
-							data: {
-								stalled: true,
-								durationMs: 0
-							}
-						});
-						addTelemetryDiagnostic("videoStall", {
-							stalled: true,
-							durationMs: 0
-						}, stallStartMs);
-					} else if (videoStalled && fps >= STALL_FPS_THRESHOLD) {
-						const durationMs = Date.now() - stallStartMs;
-						videoStalled = false;
-						emitOrBuffer("diagnostic", {
-							name: "videoStall",
-							data: {
-								stalled: false,
-								durationMs
-							}
-						});
-						addTelemetryDiagnostic("videoStall", {
-							stalled: false,
-							durationMs
-						});
-					}
-				});
-				return () => {
-					statsCollector?.stop();
-					statsCollector = null;
-					statsCollectorPeerConnection = null;
-				};
-			};
-			handleConnectionStateChange = (state) => {
-				if (!opts.telemetryEnabled) return;
-				if (state !== "connected" && state !== "generating") return;
-				const peerConnection = manager.getPeerConnection();
-				if (!peerConnection || peerConnection === statsCollectorPeerConnection) return;
-				startStatsCollection();
-			};
-			if (opts.telemetryEnabled) startStatsCollection();
 			const client = {
 				set: methods.set,
 				setPrompt: methods.setPrompt,
 				isConnected: () => manager.isConnected(),
 				getConnectionState: () => manager.getConnectionState(),
 				disconnect: () => {
-					statsCollector?.stop();
-					telemetryReporter.stop();
+					observability.stop();
 					stop();
 					manager.cleanup();
 					mirroredStream?.dispose();
@@ -251,7 +159,7 @@ const createRealTimeClient = (opts) => {
 			flush();
 			return client;
 		} catch (error) {
-			telemetryReporter.stop();
+			observability.stop();
 			webrtcManager?.cleanup();
 			mirroredStream?.dispose();
 			throw error;
@@ -262,17 +170,21 @@ const createRealTimeClient = (opts) => {
 		const subscribeUrl = `${baseUrl}/subscribe/${encodeURIComponent(sid)}?IP=${encodeURIComponent(ip)}&port=${encodeURIComponent(port)}&api_key=${encodeURIComponent(apiKey)}`;
 		const { emitter: eventEmitter, emitOrBuffer, flush, stop } = createEventBuffer();
 		let webrtcManager;
+		const observability = new RealtimeObservability({
+			telemetryEnabled: opts.telemetryEnabled,
+			apiKey,
+			integration,
+			logger,
+			onDiagnostic: (event) => emitOrBuffer("diagnostic", event),
+			onStats: opts.telemetryEnabled ? (stats) => emitOrBuffer("stats", stats) : void 0
+		});
+		observability.sessionStarted(sid);
 		try {
 			webrtcManager = new WebRTCManager({
 				webrtcUrl: subscribeUrl,
 				integration,
 				logger,
-				onDiagnostic: (name, data) => {
-					emitOrBuffer("diagnostic", {
-						name,
-						data
-					});
-				},
+				observability,
 				onRemoteStream: options.onRemoteStream,
 				onConnectionStateChange: (state) => {
 					emitOrBuffer("connectionChange", state);
@@ -288,6 +200,7 @@ const createRealTimeClient = (opts) => {
 				isConnected: () => manager.isConnected(),
 				getConnectionState: () => manager.getConnectionState(),
 				disconnect: () => {
+					observability.stop();
 					stop();
 					manager.cleanup();
 				},
@@ -297,6 +210,7 @@ const createRealTimeClient = (opts) => {
 			flush();
 			return client;
 		} catch (error) {
+			observability.stop();
 			webrtcManager?.cleanup();
 			throw error;
 		}

package/dist/realtime/{diagnostics.d.ts → observability/diagnostics.d.ts}

@@ -1,4 +1,4 @@
-//#region src/realtime/diagnostics.d.ts
+//#region src/realtime/observability/diagnostics.d.ts
 /** Connection phase names for timing events. */
 type ConnectionPhase = "websocket" | "avatar-image" | "initial-prompt" | "webrtc-handshake" | "total";
 type PhaseTimingEvent = {

package/dist/realtime/observability/realtime-observability.js

@@ -0,0 +1,109 @@
+import { NullTelemetryReporter, TelemetryReporter } from "./telemetry-reporter.js";
+import { WebRTCStatsCollector } from "./webrtc-stats.js";
+
+//#region src/realtime/observability/realtime-observability.ts
+const STALL_FPS_THRESHOLD = .5;
+var RealtimeObservability = class {
+	telemetryReporter = new NullTelemetryReporter();
+	telemetryReporterReady = false;
+	pendingTelemetryDiagnostics = [];
+	statsCollector = null;
+	statsCollectorSource = null;
+	videoStalled = false;
+	stallStartMs = 0;
+	constructor(options) {
+		this.options = options;
+	}
+	diagnostic(name, data, timestamp = Date.now()) {
+		this.options.logger.debug(name, data);
+		this.options.onDiagnostic?.({
+			name,
+			data
+		});
+		this.addTelemetryDiagnostic(name, data, timestamp);
+	}
+	sessionStarted(sessionId) {
+		if (!this.options.telemetryEnabled) return;
+		if (this.telemetryReporterReady) this.telemetryReporter.stop();
+		const reporter = new TelemetryReporter({
+			apiKey: this.options.apiKey,
+			sessionId,
+			model: this.options.model,
+			integration: this.options.integration,
+			logger: this.options.logger
+		});
+		reporter.start();
+		this.telemetryReporter = reporter;
+		this.telemetryReporterReady = true;
+		for (const diagnostic of this.pendingTelemetryDiagnostics) this.telemetryReporter.addDiagnostic(diagnostic);
+		this.pendingTelemetryDiagnostics.length = 0;
+	}
+	setStatsProvider(source) {
+		if (!source) {
+			this.stopStats();
+			return;
+		}
+		if (source === this.statsCollectorSource) return;
+		this.stopStats();
+		this.statsCollectorSource = source;
+		if (!this.options.telemetryEnabled && !this.options.onStats) return;
+		this.statsCollector = new WebRTCStatsCollector();
+		this.statsCollector.start(source, (stats) => this.handleStats(stats));
+	}
+	stopStats() {
+		this.statsCollector?.stop();
+		this.statsCollector = null;
+		this.statsCollectorSource = null;
+		this.resetStallDetection();
+	}
+	stop() {
+		this.stopStats();
+		this.telemetryReporter.stop();
+		this.telemetryReporter = new NullTelemetryReporter();
+		this.telemetryReporterReady = false;
+		this.pendingTelemetryDiagnostics.length = 0;
+	}
+	handleStats(stats) {
+		this.options.onStats?.(stats);
+		this.telemetryReporter.addStats(stats);
+		this.detectVideoStall(stats);
+	}
+	detectVideoStall(stats) {
+		const fps = stats.video?.framesPerSecond ?? 0;
+		if (!this.videoStalled && stats.video && fps < STALL_FPS_THRESHOLD) {
+			this.videoStalled = true;
+			this.stallStartMs = Date.now();
+			this.diagnostic("videoStall", {
+				stalled: true,
+				durationMs: 0
+			}, this.stallStartMs);
+		} else if (this.videoStalled && fps >= STALL_FPS_THRESHOLD) {
+			const durationMs = Date.now() - this.stallStartMs;
+			this.videoStalled = false;
+			this.diagnostic("videoStall", {
+				stalled: false,
+				durationMs
+			});
+		}
+	}
+	addTelemetryDiagnostic(name, data, timestamp) {
+		if (!this.options.telemetryEnabled) return;
+		const diagnostic = {
+			name,
+			data,
+			timestamp
+		};
+		if (!this.telemetryReporterReady) {
+			this.pendingTelemetryDiagnostics.push(diagnostic);
+			return;
+		}
+		this.telemetryReporter.addDiagnostic(diagnostic);
+	}
+	resetStallDetection() {
+		this.videoStalled = false;
+		this.stallStartMs = 0;
+	}
+};
+
+//#endregion
+export { RealtimeObservability };

package/dist/realtime/{telemetry-reporter.js → observability/telemetry-reporter.js}

@@ -1,7 +1,7 @@
-import { VERSION } from "../version.js";
-import { buildAuthHeaders } from "../shared/request.js";
+import { VERSION } from "../../version.js";
+import { buildAuthHeaders } from "../../shared/request.js";
 
-//#region src/realtime/telemetry-reporter.ts
+//#region src/realtime/observability/telemetry-reporter.ts
 const DEFAULT_REPORT_INTERVAL_MS = 1e4;
 const TELEMETRY_URL = "https://platform.decart.ai/api/v1/telemetry";
 /**

package/dist/realtime/observability/webrtc-stats.d.ts

@@ -0,0 +1,147 @@
+//#region src/realtime/observability/webrtc-stats.d.ts
+type WebRTCStats = {
+  timestamp: number;
+  video: {
+    framesDecoded: number;
+    framesDropped: number;
+    framesReceived: number;
+    keyFramesDecoded: number;
+    framesPerSecond: number;
+    frameWidth: number;
+    frameHeight: number;
+    bytesReceived: number;
+    packetsReceived: number;
+    packetsLost: number;
+    jitter: number;
+    /** Estimated inbound bitrate in bits/sec, computed from bytesReceived delta. */
+    bitrate: number;
+    freezeCount: number;
+    totalFreezesDuration: number;
+    /** Delta: packets lost since previous sample. */
+    packetsLostDelta: number;
+    /** Delta: frames dropped since previous sample. */
+    framesDroppedDelta: number;
+    /** Delta: freeze count since previous sample. */
+    freezeCountDelta: number;
+    /** Delta: freeze duration (seconds) since previous sample. */
+    freezeDurationDelta: number;
+    /** NACKs sent to the sender (requesting packet retransmission). */
+    nackCount: number;
+    nackCountDelta: number;
+    /** PLIs sent to the sender (full frame retransmission request). */
+    pliCount: number;
+    /** FIRs sent to the sender (forced intra-refresh request). */
+    firCount: number;
+    /**
+     * Average decode time (ms/frame), cumulative since stream start.
+     * Derived from totalDecodeTime/framesDecoded. `null` if the browser
+     * hasn't produced the underlying counters yet.
+     */
+    avgDecodeTimeMs: number | null;
+    /** Average jitter-buffer time (ms/frame emitted). Cumulative. */
+    avgJitterBufferMs: number | null;
+    /**
+     * Average total processing delay (ms/frame decoded) — from network
+     * receive to decoder output. Cumulative.
+     */
+    avgProcessingDelayMs: number | null;
+    /** Average inter-frame delay at the decoder (ms). */
+    avgInterFrameDelayMs: number | null;
+    /**
+     * Std-dev of inter-frame delay (ms), computed from
+     * totalInterFrameDelay + totalSquaredInterFrameDelay.
+     */
+    interFrameDelayStdDevMs: number | null;
+    /** Current target delay of the jitter buffer (ms). */
+    jitterBufferTargetDelayMs: number | null;
+    /** Current minimum delay of the jitter buffer (ms). */
+    jitterBufferMinimumDelayMs: number | null;
+    /** Which decoder the browser picked (e.g. "libvpx", "ExternalDecoder"). */
+    decoderImplementation: string;
+  } | null;
+  audio: {
+    bytesReceived: number;
+    packetsReceived: number;
+    packetsLost: number;
+    jitter: number;
+    /** Estimated inbound bitrate in bits/sec, computed from bytesReceived delta. */
+    bitrate: number;
+    /** Delta: packets lost since previous sample. */
+    packetsLostDelta: number;
+  } | null;
+  /** Outbound video track stats (from the local camera/screen share being sent). */
+  outboundVideo: {
+    /** Why the encoder is limiting quality: "none", "bandwidth", "cpu", or "other". */
+    qualityLimitationReason: string;
+    /** Cumulative time (seconds) spent in each quality limitation state. */
+    qualityLimitationDurations: Record<string, number>;
+    bytesSent: number;
+    packetsSent: number;
+    framesPerSecond: number;
+    frameWidth: number;
+    frameHeight: number;
+    /** Estimated outbound bitrate in bits/sec, computed from bytesSent delta. */
+    bitrate: number;
+    /** Encoder's current target bitrate in kbps (BWE output). */
+    targetBitrateKbps: number | null;
+    /** Average encode time per frame (ms), cumulative. */
+    avgEncodeTimeMs: number | null;
+    /** Average packet send delay (ms), cumulative. */
+    avgPacketSendDelayMs: number | null;
+    /** Average quantization parameter across encoded frames (lower is better). */
+    avgQp: number | null;
+    /** NACKs received from receiver (retransmission requests). */
+    nackCount: number;
+    /** PLIs received from receiver. */
+    pliCount: number;
+    /** FIRs received from receiver. */
+    firCount: number;
+    retransmittedBytesSent: number;
+    retransmittedPacketsSent: number;
+    /** Which encoder the browser picked (e.g. "libvpx", "SimulcastEncoderAdapter"). */
+    encoderImplementation: string;
+  } | null;
+  /**
+   * Remote-inbound stats — what the far end reports *about its reception
+   * of our outbound stream*. Answers "does the server think we're lossy?"
+   * independently of what we see locally. Populated from
+   * `remote-inbound-rtp` reports.
+   */
+  remoteInbound: {
+    fractionLost: number | null;
+    /** In seconds. */
+    jitter: number | null;
+    /** In seconds. Often more accurate than connection.currentRoundTripTime. */
+    roundTripTime: number | null;
+  } | null;
+  connection: {
+    /** Current round-trip time in seconds, or null if unavailable. */
+    currentRoundTripTime: number | null;
+    /** Available outgoing bitrate estimate in bits/sec, or null if unavailable. */
+    availableOutgoingBitrate: number | null;
+    /**
+     * Selected ICE candidate pairs (usually one per PC). Populated from
+     * the `candidate-pair` report with state="succeeded" plus the matching
+     * `local-candidate` / `remote-candidate` lookups. Lets diagnostic tools
+     * tell direct-UDP sessions from TURN-relayed ones — the path affects
+     * jitter and failure modes, so this is essential signal for
+     * benchmarking and incident triage.
+     */
+    selectedCandidatePairs: Array<{
+      local: IceCandidateInfo;
+      remote: IceCandidateInfo;
+    }>;
+  };
+};
+/** One side of an ICE candidate pair (sender or receiver). */
+type IceCandidateInfo = {
+  /** "host" | "srflx" | "prflx" | "relay" */
+  candidateType: string;
+  /** IP (v4 or v6). May be `""` for mDNS-obfuscated host candidates. */
+  address: string;
+  port: number;
+  /** "udp" | "tcp" */
+  protocol: string;
+};
+//#endregion
+export { WebRTCStats };

package/dist/realtime/observability/webrtc-stats.js

@@ -0,0 +1,278 @@
+//#region src/realtime/observability/webrtc-stats.ts
+const DEFAULT_INTERVAL_MS = 1e3;
+const MIN_INTERVAL_MS = 500;
+var WebRTCStatsCollector = class {
+	source = null;
+	intervalId = null;
+	prevBytesVideo = 0;
+	prevBytesAudio = 0;
+	prevBytesSentVideo = 0;
+	prevTimestamp = 0;
+	prevPacketsLostVideo = 0;
+	prevFramesDropped = 0;
+	prevFreezeCount = 0;
+	prevFreezeDuration = 0;
+	prevPacketsLostAudio = 0;
+	prevNackCountInbound = 0;
+	onStats = null;
+	intervalMs;
+	constructor(options = {}) {
+		this.intervalMs = Math.max(options.intervalMs ?? DEFAULT_INTERVAL_MS, MIN_INTERVAL_MS);
+	}
+	/** Attach to a stats provider and start polling. */
+	start(source, onStats) {
+		this.stop();
+		this.source = source;
+		this.onStats = onStats;
+		this.prevBytesVideo = 0;
+		this.prevBytesAudio = 0;
+		this.prevBytesSentVideo = 0;
+		this.prevTimestamp = 0;
+		this.prevPacketsLostVideo = 0;
+		this.prevFramesDropped = 0;
+		this.prevFreezeCount = 0;
+		this.prevFreezeDuration = 0;
+		this.prevPacketsLostAudio = 0;
+		this.prevNackCountInbound = 0;
+		this.intervalId = setInterval(() => this.collect(), this.intervalMs);
+	}
+	/** Stop polling and release resources. */
+	stop() {
+		if (this.intervalId !== null) {
+			clearInterval(this.intervalId);
+			this.intervalId = null;
+		}
+		this.source = null;
+		this.onStats = null;
+	}
+	isRunning() {
+		return this.intervalId !== null;
+	}
+	async collect() {
+		if (!this.source || !this.onStats) return;
+		try {
+			const rawStats = await this.source.getStats();
+			const stats = this.parse(rawStats);
+			this.onStats(stats);
+		} catch {
+			this.stop();
+		}
+	}
+	parse(rawStats) {
+		const now = performance.now();
+		const elapsed = this.prevTimestamp > 0 ? (now - this.prevTimestamp) / 1e3 : 0;
+		let video = null;
+		let audio = null;
+		let outboundVideo = null;
+		let remoteInbound = null;
+		const connection = {
+			currentRoundTripTime: null,
+			availableOutgoingBitrate: null,
+			selectedCandidatePairs: []
+		};
+		const succeededPairs = [];
+		rawStats.forEach((report) => {
+			if (report.type === "inbound-rtp" && report.kind === "video") {
+				const bytesReceived = report.bytesReceived ?? 0;
+				const bitrate = elapsed > 0 ? (bytesReceived - this.prevBytesVideo) * 8 / elapsed : 0;
+				this.prevBytesVideo = bytesReceived;
+				const r = report;
+				const packetsLost = r.packetsLost ?? 0;
+				const framesDropped = r.framesDropped ?? 0;
+				const freezeCount = r.freezeCount ?? 0;
+				const freezeDuration = r.totalFreezesDuration ?? 0;
+				const framesDecoded = r.framesDecoded ?? 0;
+				const nackCount = r.nackCount ?? 0;
+				const jbEmitted = r.jitterBufferEmittedCount ?? 0;
+				const totalDecodeTime = r.totalDecodeTime ?? 0;
+				const totalProcessingDelay = r.totalProcessingDelay ?? 0;
+				const totalInterFrameDelay = r.totalInterFrameDelay ?? 0;
+				const totalSquaredInterFrameDelay = r.totalSquaredInterFrameDelay ?? 0;
+				const jitterBufferDelay = r.jitterBufferDelay ?? 0;
+				const jitterBufferTargetDelay = r.jitterBufferTargetDelay ?? 0;
+				const jitterBufferMinimumDelay = r.jitterBufferMinimumDelay ?? 0;
+				const avgDecodeTimeMs = framesDecoded > 0 ? totalDecodeTime / framesDecoded * 1e3 : null;
+				const avgProcessingDelayMs = framesDecoded > 0 ? totalProcessingDelay / framesDecoded * 1e3 : null;
+				const avgInterFrameDelayMs = framesDecoded > 0 ? totalInterFrameDelay / framesDecoded * 1e3 : null;
+				const interFrameDelayStdDevMs = framesDecoded > 0 ? Math.sqrt(Math.max(0, totalSquaredInterFrameDelay / framesDecoded - (totalInterFrameDelay / framesDecoded) ** 2)) * 1e3 : null;
+				const avgJitterBufferMs = jbEmitted > 0 ? jitterBufferDelay / jbEmitted * 1e3 : null;
+				const jitterBufferTargetDelayMs = jbEmitted > 0 ? jitterBufferTargetDelay / jbEmitted * 1e3 : null;
+				const jitterBufferMinimumDelayMs = jbEmitted > 0 ? jitterBufferMinimumDelay / jbEmitted * 1e3 : null;
+				video = {
+					framesDecoded,
+					framesDropped,
+					framesReceived: r.framesReceived ?? 0,
+					keyFramesDecoded: r.keyFramesDecoded ?? 0,
+					framesPerSecond: r.framesPerSecond ?? 0,
+					frameWidth: r.frameWidth ?? 0,
+					frameHeight: r.frameHeight ?? 0,
+					bytesReceived,
+					packetsReceived: r.packetsReceived ?? 0,
+					packetsLost,
+					jitter: r.jitter ?? 0,
+					bitrate: Math.round(bitrate),
+					freezeCount,
+					totalFreezesDuration: freezeDuration,
+					packetsLostDelta: Math.max(0, packetsLost - this.prevPacketsLostVideo),
+					framesDroppedDelta: Math.max(0, framesDropped - this.prevFramesDropped),
+					freezeCountDelta: Math.max(0, freezeCount - this.prevFreezeCount),
+					freezeDurationDelta: Math.max(0, freezeDuration - this.prevFreezeDuration),
+					nackCount,
+					nackCountDelta: Math.max(0, nackCount - this.prevNackCountInbound),
+					pliCount: r.pliCount ?? 0,
+					firCount: r.firCount ?? 0,
+					avgDecodeTimeMs,
+					avgJitterBufferMs,
+					avgProcessingDelayMs,
+					avgInterFrameDelayMs,
+					interFrameDelayStdDevMs,
+					jitterBufferTargetDelayMs,
+					jitterBufferMinimumDelayMs,
+					decoderImplementation: r.decoderImplementation ?? ""
+				};
+				this.prevPacketsLostVideo = packetsLost;
+				this.prevFramesDropped = framesDropped;
+				this.prevFreezeCount = freezeCount;
+				this.prevFreezeDuration = freezeDuration;
+				this.prevNackCountInbound = nackCount;
+			}
+			if (report.type === "outbound-rtp" && report.kind === "video") {
+				const r = report;
+				const bytesSent = r.bytesSent ?? 0;
+				const packetsSent = r.packetsSent ?? 0;
+				const frameWidth = r.frameWidth ?? 0;
+				const frameHeight = r.frameHeight ?? 0;
+				const pixels = frameWidth * frameHeight;
+				const framesEncoded = r.framesEncoded ?? 0;
+				const totalEncodeTime = r.totalEncodeTime ?? 0;
+				const totalPacketSendDelay = r.totalPacketSendDelay ?? 0;
+				const qpSum = r.qpSum ?? 0;
+				const nackCount = r.nackCount ?? 0;
+				const pliCount = r.pliCount ?? 0;
+				const firCount = r.firCount ?? 0;
+				const retransmittedBytesSent = r.retransmittedBytesSent ?? 0;
+				const retransmittedPacketsSent = r.retransmittedPacketsSent ?? 0;
+				const targetBitrate = r.targetBitrate ?? null;
+				const avgEncodeTimeMs = framesEncoded > 0 ? totalEncodeTime / framesEncoded * 1e3 : null;
+				const avgPacketSendDelayMs = packetsSent > 0 ? totalPacketSendDelay / packetsSent * 1e3 : null;
+				const avgQp = framesEncoded > 0 ? qpSum / framesEncoded : null;
+				if (outboundVideo === null) outboundVideo = {
+					qualityLimitationReason: r.qualityLimitationReason ?? "none",
+					qualityLimitationDurations: r.qualityLimitationDurations ?? {},
+					bytesSent,
+					packetsSent,
+					framesPerSecond: r.framesPerSecond ?? 0,
+					frameWidth,
+					frameHeight,
+					bitrate: 0,
+					targetBitrateKbps: targetBitrate != null ? Math.round(targetBitrate / 1e3) : null,
+					avgEncodeTimeMs,
+					avgPacketSendDelayMs,
+					avgQp,
+					nackCount,
+					pliCount,
+					firCount,
+					retransmittedBytesSent,
+					retransmittedPacketsSent,
+					encoderImplementation: r.encoderImplementation ?? ""
+				};
+				else {
+					outboundVideo.bytesSent += bytesSent;
+					outboundVideo.packetsSent += packetsSent;
+					outboundVideo.nackCount += nackCount;
+					outboundVideo.pliCount += pliCount;
+					outboundVideo.firCount += firCount;
+					outboundVideo.retransmittedBytesSent += retransmittedBytesSent;
+					outboundVideo.retransmittedPacketsSent += retransmittedPacketsSent;
+					if (pixels > outboundVideo.frameWidth * outboundVideo.frameHeight) {
+						outboundVideo.frameWidth = frameWidth;
+						outboundVideo.frameHeight = frameHeight;
+						outboundVideo.framesPerSecond = r.framesPerSecond ?? 0;
+						outboundVideo.qualityLimitationReason = r.qualityLimitationReason ?? "none";
+						outboundVideo.qualityLimitationDurations = r.qualityLimitationDurations ?? {};
+						outboundVideo.targetBitrateKbps = targetBitrate != null ? Math.round(targetBitrate / 1e3) : null;
+						outboundVideo.avgEncodeTimeMs = avgEncodeTimeMs;
+						outboundVideo.avgPacketSendDelayMs = avgPacketSendDelayMs;
+						outboundVideo.avgQp = avgQp;
+						outboundVideo.encoderImplementation = r.encoderImplementation ?? "";
+					}
+				}
+			}
+			if (report.type === "remote-inbound-rtp" && report.kind === "video") {
+				const r = report;
+				remoteInbound = {
+					fractionLost: r.fractionLost ?? null,
+					jitter: r.jitter ?? null,
+					roundTripTime: r.roundTripTime ?? null
+				};
+			}
+			if (report.type === "inbound-rtp" && report.kind === "audio") {
+				const bytesReceived = report.bytesReceived ?? 0;
+				const bitrate = elapsed > 0 ? (bytesReceived - this.prevBytesAudio) * 8 / elapsed : 0;
+				this.prevBytesAudio = bytesReceived;
+				const r = report;
+				const audioPacketsLost = r.packetsLost ?? 0;
+				audio = {
+					bytesReceived,
+					packetsReceived: r.packetsReceived ?? 0,
+					packetsLost: audioPacketsLost,
+					jitter: r.jitter ?? 0,
+					bitrate: Math.round(bitrate),
+					packetsLostDelta: Math.max(0, audioPacketsLost - this.prevPacketsLostAudio)
+				};
+				this.prevPacketsLostAudio = audioPacketsLost;
+			}
+			if (report.type === "candidate-pair") {
+				const r = report;
+				if (r.state === "succeeded") {
+					connection.currentRoundTripTime = r.currentRoundTripTime ?? null;
+					connection.availableOutgoingBitrate = r.availableOutgoingBitrate ?? null;
+					const localId = r.localCandidateId;
+					const remoteId = r.remoteCandidateId;
+					if (localId && remoteId) succeededPairs.push({
+						localId,
+						remoteId
+					});
+				}
+			}
+		});
+		if (succeededPairs.length > 0) {
+			const toInfo = (id) => {
+				const c = rawStats.get(id);
+				if (!c) return null;
+				return {
+					candidateType: c.candidateType ?? "",
+					address: c.address ?? c.ip ?? "",
+					port: c.port ?? 0,
+					protocol: c.protocol ?? ""
+				};
+			};
+			for (const { localId, remoteId } of succeededPairs) {
+				const local = toInfo(localId);
+				const remote = toInfo(remoteId);
+				if (local && remote) connection.selectedCandidatePairs.push({
+					local,
+					remote
+				});
+			}
+		}
+		const ov = outboundVideo;
+		if (ov !== null) {
+			const outBitrate = elapsed > 0 ? (ov.bytesSent - this.prevBytesSentVideo) * 8 / elapsed : 0;
+			ov.bitrate = Math.max(0, Math.round(outBitrate));
+			this.prevBytesSentVideo = ov.bytesSent;
+		}
+		this.prevTimestamp = now;
+		return {
+			timestamp: Date.now(),
+			video,
+			audio,
+			outboundVideo,
+			connection,
+			remoteInbound
+		};
+	}
+};
+
+//#endregion
+export { WebRTCStatsCollector };

package/dist/realtime/subscribe-client.d.ts

@@ -1,6 +1,7 @@
 import { DecartSDKError } from "../utils/errors.js";
-import { DiagnosticEvent } from "./diagnostics.js";
 import { ConnectionState } from "./types.js";
+import { DiagnosticEvent } from "./observability/diagnostics.js";
+import { WebRTCStats } from "./observability/webrtc-stats.js";
 
 //#region src/realtime/subscribe-client.d.ts
 
@@ -8,6 +9,7 @@ type SubscribeEvents = {
   connectionChange: ConnectionState;
   error: DecartSDKError;
   diagnostic: DiagnosticEvent;
+  stats: WebRTCStats;
 };
 type RealTimeSubscribeClient = {
   isConnected: () => boolean;

package/dist/realtime/webrtc-connection.js

@@ -4,17 +4,16 @@ import mitt from "mitt";
 //#region src/realtime/webrtc-connection.ts
 const ICE_SERVERS = [{ urls: "stun:stun.l.google.com:19302" }];
 const SETUP_TIMEOUT_MS = 3e4;
-const noopDiagnostic = () => {};
 var WebRTCConnection = class {
 	pc = null;
 	ws = null;
 	localStream = null;
 	connectionReject = null;
 	logger;
-	emitDiagnostic;
+	observability;
 	state = "disconnected";
 	websocketMessagesEmitter = mitt();
-	constructor(callbacks = {}) {
+	constructor(callbacks) {
 		this.callbacks = callbacks;
 		this.logger = callbacks.logger ?? {
 			debug() {},
@@ -22,7 +21,7 @@ var WebRTCConnection = class {
 			warn() {},
 			error() {}
 		};
-		this.emitDiagnostic = callbacks.onDiagnostic ?? noopDiagnostic;
+		this.observability = callbacks.observability;
 	}
 	getPeerConnection() {
 		return this.pc;
@@ -46,7 +45,7 @@ var WebRTCConnection = class {
 				this.ws = new WebSocket(wsUrl);
 				this.ws.onopen = () => {
 					clearTimeout(timer);
-					this.emitDiagnostic("phaseTiming", {
+					this.observability.diagnostic("phaseTiming", {
 						phase: "websocket",
 						durationMs: performance.now() - wsStart,
 						success: true
@@ -63,7 +62,7 @@ var WebRTCConnection = class {
 				this.ws.onerror = () => {
 					clearTimeout(timer);
 					const error = /* @__PURE__ */ new Error("WebSocket error");
-					this.emitDiagnostic("phaseTiming", {
+					this.observability.diagnostic("phaseTiming", {
 						phase: "websocket",
 						durationMs: performance.now() - wsStart,
 						success: false,
@@ -85,7 +84,7 @@ var WebRTCConnection = class {
 					prompt: this.callbacks.initialPrompt?.text,
 					enhance: this.callbacks.initialPrompt?.enhance
 				}), connectAbort]);
-				this.emitDiagnostic("phaseTiming", {
+				this.observability.diagnostic("phaseTiming", {
 					phase: "avatar-image",
 					durationMs: performance.now() - imageStart,
 					success: true
@@ -93,7 +92,7 @@ var WebRTCConnection = class {
 			} else if (this.callbacks.initialPrompt) {
 				const promptStart = performance.now();
 				await Promise.race([this.sendInitialPrompt(this.callbacks.initialPrompt), connectAbort]);
-				this.emitDiagnostic("phaseTiming", {
+				this.observability.diagnostic("phaseTiming", {
 					phase: "initial-prompt",
 					durationMs: performance.now() - promptStart,
 					success: true
@@ -101,7 +100,7 @@ var WebRTCConnection = class {
 			} else if (localStream) {
 				const nullStart = performance.now();
 				await Promise.race([this.setImageBase64(null, { prompt: null }), connectAbort]);
-				this.emitDiagnostic("phaseTiming", {
+				this.observability.diagnostic("phaseTiming", {
 					phase: "initial-prompt",
 					durationMs: performance.now() - nullStart,
 					success: true
@@ -113,7 +112,7 @@ var WebRTCConnection = class {
 				const checkConnection = setInterval(() => {
 					if (this.state === "connected" || this.state === "generating") {
 						clearInterval(checkConnection);
-						this.emitDiagnostic("phaseTiming", {
+						this.observability.diagnostic("phaseTiming", {
 							phase: "webrtc-handshake",
 							durationMs: performance.now() - handshakeStart,
 							success: true
@@ -121,7 +120,7 @@ var WebRTCConnection = class {
 						resolve();
 					} else if (this.state === "disconnected") {
 						clearInterval(checkConnection);
-						this.emitDiagnostic("phaseTiming", {
+						this.observability.diagnostic("phaseTiming", {
 							phase: "webrtc-handshake",
 							durationMs: performance.now() - handshakeStart,
 							success: false,
@@ -130,7 +129,7 @@ var WebRTCConnection = class {
 						reject(/* @__PURE__ */ new Error("Connection lost during WebRTC handshake"));
 					} else if (Date.now() >= deadline) {
 						clearInterval(checkConnection);
-						this.emitDiagnostic("phaseTiming", {
+						this.observability.diagnostic("phaseTiming", {
 							phase: "webrtc-handshake",
 							durationMs: performance.now() - handshakeStart,
 							success: false,
@@ -141,7 +140,7 @@ var WebRTCConnection = class {
 				}, 100);
 				connectAbort.catch(() => clearInterval(checkConnection));
 			}), connectAbort]);
-			this.emitDiagnostic("phaseTiming", {
+			this.observability.diagnostic("phaseTiming", {
 				phase: "total",
 				durationMs: performance.now() - totalStart,
 				success: true
@@ -219,7 +218,7 @@ var WebRTCConnection = class {
 				case "ice-candidate":
 					if (msg.candidate) {
 						await this.pc.addIceCandidate(msg.candidate);
-						this.emitDiagnostic("iceCandidate", {
+						this.observability.diagnostic("iceCandidate", {
 							source: "remote",
 							candidateType: msg.candidate.candidate?.match(/typ (\w+)/)?.[1] ?? "unknown",
 							protocol: msg.candidate.candidate?.match(/udp|tcp/i)?.[0]?.toLowerCase() ?? "unknown"
@@ -332,7 +331,7 @@ var WebRTCConnection = class {
 				type: "ice-candidate",
 				candidate: e.candidate
 			});
-			if (e.candidate) this.emitDiagnostic("iceCandidate", {
+			if (e.candidate) this.observability.diagnostic("iceCandidate", {
 				source: "local",
 				candidateType: e.candidate.type ?? "unknown",
 				protocol: e.candidate.protocol ?? "unknown",
@@ -344,7 +343,7 @@ var WebRTCConnection = class {
 		this.pc.onconnectionstatechange = () => {
 			if (!this.pc) return;
 			const s = this.pc.connectionState;
-			this.emitDiagnostic("peerConnectionStateChange", {
+			this.observability.diagnostic("peerConnectionStateChange", {
 				state: s,
 				previousState: prevPcState,
 				timestampMs: performance.now()
@@ -359,7 +358,7 @@ var WebRTCConnection = class {
 		this.pc.oniceconnectionstatechange = () => {
 			if (!this.pc) return;
 			const newIceState = this.pc.iceConnectionState;
-			this.emitDiagnostic("iceStateChange", {
+			this.observability.diagnostic("iceStateChange", {
 				state: newIceState,
 				previousState: prevIceState,
 				timestampMs: performance.now()
@@ -374,7 +373,7 @@ var WebRTCConnection = class {
 		this.pc.onsignalingstatechange = () => {
 			if (!this.pc) return;
 			const newState = this.pc.signalingState;
-			this.emitDiagnostic("signalingStateChange", {
+			this.observability.diagnostic("signalingStateChange", {
 				state: newState,
 				previousState: prevSignalingState,
 				timestampMs: performance.now()
@@ -398,7 +397,7 @@ var WebRTCConnection = class {
 						if (r.id === report.localCandidateId) localCandidate = r;
 						if (r.id === report.remoteCandidateId) remoteCandidate = r;
 					});
-					if (localCandidate && remoteCandidate) this.emitDiagnostic("selectedCandidatePair", {
+					if (localCandidate && remoteCandidate) this.observability.diagnostic("selectedCandidatePair", {
 						local: {
 							candidateType: String(localCandidate.candidateType ?? "unknown"),
 							protocol: String(localCandidate.protocol ?? "unknown"),

package/dist/realtime/webrtc-manager.js

@@ -21,6 +21,7 @@ var WebRTCManager = class {
 	connection;
 	config;
 	logger;
+	observability;
 	localStream = null;
 	subscribeMode = false;
 	managerState = "disconnected";
@@ -28,6 +29,7 @@ var WebRTCManager = class {
 	isReconnecting = false;
 	intentionalDisconnect = false;
 	reconnectGeneration = 0;
+	statsProviderConnection = null;
 	constructor(config) {
 		this.config = config;
 		this.logger = config.logger ?? {
@@ -36,6 +38,7 @@ var WebRTCManager = class {
 			warn() {},
 			error() {}
 		};
+		this.observability = config.observability;
 		this.connection = new WebRTCConnection({
 			onRemoteStream: config.onRemoteStream,
 			onStateChange: (state) => this.handleConnectionStateChange(state),
@@ -46,7 +49,7 @@ var WebRTCManager = class {
 			initialImage: config.initialImage,
 			initialPrompt: config.initialPrompt,
 			logger: this.logger,
-			onDiagnostic: config.onDiagnostic
+			observability: this.observability
 		});
 	}
 	emitState(state) {
@@ -56,15 +59,28 @@ var WebRTCManager = class {
 			this.config.onConnectionStateChange?.(state);
 		}
 	}
+	syncStatsProvider() {
+		const pc = this.getPeerConnection();
+		const isLive = this.managerState === "connected" || this.managerState === "generating";
+		if (isLive && pc && pc !== this.statsProviderConnection) {
+			this.statsProviderConnection = pc;
+			this.observability.setStatsProvider(pc);
+		} else if (!isLive && this.statsProviderConnection) {
+			this.statsProviderConnection = null;
+			this.observability.setStatsProvider(null);
+		}
+	}
 	handleConnectionStateChange(state) {
 		if (this.intentionalDisconnect) {
 			this.emitState("disconnected");
+			this.syncStatsProvider();
 			return;
 		}
 		if (this.isReconnecting) {
 			if (state === "connected" || state === "generating") {
 				this.isReconnecting = false;
 				this.emitState(state);
+				this.syncStatsProvider();
 			}
 			return;
 		}
@@ -73,6 +89,7 @@ var WebRTCManager = class {
 			return;
 		}
 		this.emitState(state);
+		this.syncStatsProvider();
 	}
 	async reconnect() {
 		if (this.isReconnecting || this.intentionalDisconnect) return;
@@ -80,6 +97,8 @@ var WebRTCManager = class {
 		const reconnectGeneration = ++this.reconnectGeneration;
 		this.isReconnecting = true;
 		this.emitState("reconnecting");
+		this.observability.setStatsProvider(null);
+		this.statsProviderConnection = null;
 		const reconnectStart = performance.now();
 		try {
 			let attemptCount = 0;
@@ -101,7 +120,7 @@ var WebRTCManager = class {
 						error: error.message,
 						attempt: error.attemptNumber
 					});
-					this.config.onDiagnostic?.("reconnect", {
+					this.observability.diagnostic("reconnect", {
 						attempt: error.attemptNumber,
 						maxAttempts: RETRY_OPTIONS.retries + 1,
 						durationMs: performance.now() - reconnectStart,
@@ -116,7 +135,7 @@ var WebRTCManager = class {
 					return !PERMANENT_ERRORS.some((err) => msg.includes(err));
 				}
 			});
-			this.config.onDiagnostic?.("reconnect", {
+			this.observability.diagnostic("reconnect", {
 				attempt: attemptCount,
 				maxAttempts: RETRY_OPTIONS.retries + 1,
 				durationMs: performance.now() - reconnectStart,
@@ -166,6 +185,8 @@ var WebRTCManager = class {
 		this.reconnectGeneration += 1;
 		this.connection.cleanup();
 		this.localStream = null;
+		this.statsProviderConnection = null;
+		this.observability.setStatsProvider(null);
 		this.emitState("disconnected");
 	}
 	isConnected() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.0.67",
+  "version": "0.0.68",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",

package/dist/realtime/webrtc-stats.d.ts

@@ -1,59 +0,0 @@
-//#region src/realtime/webrtc-stats.d.ts
-type WebRTCStats = {
-  timestamp: number;
-  video: {
-    framesDecoded: number;
-    framesDropped: number;
-    framesPerSecond: number;
-    frameWidth: number;
-    frameHeight: number;
-    bytesReceived: number;
-    packetsReceived: number;
-    packetsLost: number;
-    jitter: number;
-    /** Estimated inbound bitrate in bits/sec, computed from bytesReceived delta. */
-    bitrate: number;
-    freezeCount: number;
-    totalFreezesDuration: number;
-    /** Delta: packets lost since previous sample. */
-    packetsLostDelta: number;
-    /** Delta: frames dropped since previous sample. */
-    framesDroppedDelta: number;
-    /** Delta: freeze count since previous sample. */
-    freezeCountDelta: number;
-    /** Delta: freeze duration (seconds) since previous sample. */
-    freezeDurationDelta: number;
-  } | null;
-  audio: {
-    bytesReceived: number;
-    packetsReceived: number;
-    packetsLost: number;
-    jitter: number;
-    /** Estimated inbound bitrate in bits/sec, computed from bytesReceived delta. */
-    bitrate: number;
-    /** Delta: packets lost since previous sample. */
-    packetsLostDelta: number;
-  } | null;
-  /** Outbound video track stats (from the local camera/screen share being sent). */
-  outboundVideo: {
-    /** Why the encoder is limiting quality: "none", "bandwidth", "cpu", or "other". */
-    qualityLimitationReason: string;
-    /** Cumulative time (seconds) spent in each quality limitation state. */
-    qualityLimitationDurations: Record<string, number>;
-    bytesSent: number;
-    packetsSent: number;
-    framesPerSecond: number;
-    frameWidth: number;
-    frameHeight: number;
-    /** Estimated outbound bitrate in bits/sec, computed from bytesSent delta. */
-    bitrate: number;
-  } | null;
-  connection: {
-    /** Current round-trip time in seconds, or null if unavailable. */
-    currentRoundTripTime: number | null;
-    /** Available outgoing bitrate estimate in bits/sec, or null if unavailable. */
-    availableOutgoingBitrate: number | null;
-  };
-};
-//#endregion
-export { WebRTCStats };

package/dist/realtime/webrtc-stats.js

@@ -1,154 +0,0 @@
-//#region src/realtime/webrtc-stats.ts
-const DEFAULT_INTERVAL_MS = 1e3;
-const MIN_INTERVAL_MS = 500;
-var WebRTCStatsCollector = class {
-	pc = null;
-	intervalId = null;
-	prevBytesVideo = 0;
-	prevBytesAudio = 0;
-	prevBytesSentVideo = 0;
-	prevTimestamp = 0;
-	prevPacketsLostVideo = 0;
-	prevFramesDropped = 0;
-	prevFreezeCount = 0;
-	prevFreezeDuration = 0;
-	prevPacketsLostAudio = 0;
-	onStats = null;
-	intervalMs;
-	constructor(options = {}) {
-		this.intervalMs = Math.max(options.intervalMs ?? DEFAULT_INTERVAL_MS, MIN_INTERVAL_MS);
-	}
-	/** Attach to a peer connection and start polling. */
-	start(pc, onStats) {
-		this.stop();
-		this.pc = pc;
-		this.onStats = onStats;
-		this.prevBytesVideo = 0;
-		this.prevBytesAudio = 0;
-		this.prevBytesSentVideo = 0;
-		this.prevTimestamp = 0;
-		this.prevPacketsLostVideo = 0;
-		this.prevFramesDropped = 0;
-		this.prevFreezeCount = 0;
-		this.prevFreezeDuration = 0;
-		this.prevPacketsLostAudio = 0;
-		this.intervalId = setInterval(() => this.collect(), this.intervalMs);
-	}
-	/** Stop polling and release resources. */
-	stop() {
-		if (this.intervalId !== null) {
-			clearInterval(this.intervalId);
-			this.intervalId = null;
-		}
-		this.pc = null;
-		this.onStats = null;
-	}
-	isRunning() {
-		return this.intervalId !== null;
-	}
-	async collect() {
-		if (!this.pc || !this.onStats) return;
-		try {
-			const rawStats = await this.pc.getStats();
-			const stats = this.parse(rawStats);
-			this.onStats(stats);
-		} catch {
-			this.stop();
-		}
-	}
-	parse(rawStats) {
-		const now = performance.now();
-		const elapsed = this.prevTimestamp > 0 ? (now - this.prevTimestamp) / 1e3 : 0;
-		let video = null;
-		let audio = null;
-		let outboundVideo = null;
-		const connection = {
-			currentRoundTripTime: null,
-			availableOutgoingBitrate: null
-		};
-		rawStats.forEach((report) => {
-			if (report.type === "inbound-rtp" && report.kind === "video") {
-				const bytesReceived = report.bytesReceived ?? 0;
-				const bitrate = elapsed > 0 ? (bytesReceived - this.prevBytesVideo) * 8 / elapsed : 0;
-				this.prevBytesVideo = bytesReceived;
-				const r = report;
-				const packetsLost = r.packetsLost ?? 0;
-				const framesDropped = r.framesDropped ?? 0;
-				const freezeCount = r.freezeCount ?? 0;
-				const freezeDuration = r.totalFreezesDuration ?? 0;
-				video = {
-					framesDecoded: r.framesDecoded ?? 0,
-					framesDropped,
-					framesPerSecond: r.framesPerSecond ?? 0,
-					frameWidth: r.frameWidth ?? 0,
-					frameHeight: r.frameHeight ?? 0,
-					bytesReceived,
-					packetsReceived: r.packetsReceived ?? 0,
-					packetsLost,
-					jitter: r.jitter ?? 0,
-					bitrate: Math.round(bitrate),
-					freezeCount,
-					totalFreezesDuration: freezeDuration,
-					packetsLostDelta: Math.max(0, packetsLost - this.prevPacketsLostVideo),
-					framesDroppedDelta: Math.max(0, framesDropped - this.prevFramesDropped),
-					freezeCountDelta: Math.max(0, freezeCount - this.prevFreezeCount),
-					freezeDurationDelta: Math.max(0, freezeDuration - this.prevFreezeDuration)
-				};
-				this.prevPacketsLostVideo = packetsLost;
-				this.prevFramesDropped = framesDropped;
-				this.prevFreezeCount = freezeCount;
-				this.prevFreezeDuration = freezeDuration;
-			}
-			if (report.type === "outbound-rtp" && report.kind === "video") {
-				const r = report;
-				const bytesSent = r.bytesSent ?? 0;
-				const outBitrate = elapsed > 0 ? (bytesSent - this.prevBytesSentVideo) * 8 / elapsed : 0;
-				this.prevBytesSentVideo = bytesSent;
-				outboundVideo = {
-					qualityLimitationReason: r.qualityLimitationReason ?? "none",
-					qualityLimitationDurations: r.qualityLimitationDurations ?? {},
-					bytesSent,
-					packetsSent: r.packetsSent ?? 0,
-					framesPerSecond: r.framesPerSecond ?? 0,
-					frameWidth: r.frameWidth ?? 0,
-					frameHeight: r.frameHeight ?? 0,
-					bitrate: Math.round(outBitrate)
-				};
-			}
-			if (report.type === "inbound-rtp" && report.kind === "audio") {
-				const bytesReceived = report.bytesReceived ?? 0;
-				const bitrate = elapsed > 0 ? (bytesReceived - this.prevBytesAudio) * 8 / elapsed : 0;
-				this.prevBytesAudio = bytesReceived;
-				const r = report;
-				const audioPacketsLost = r.packetsLost ?? 0;
-				audio = {
-					bytesReceived,
-					packetsReceived: r.packetsReceived ?? 0,
-					packetsLost: audioPacketsLost,
-					jitter: r.jitter ?? 0,
-					bitrate: Math.round(bitrate),
-					packetsLostDelta: Math.max(0, audioPacketsLost - this.prevPacketsLostAudio)
-				};
-				this.prevPacketsLostAudio = audioPacketsLost;
-			}
-			if (report.type === "candidate-pair") {
-				const r = report;
-				if (r.state === "succeeded") {
-					connection.currentRoundTripTime = r.currentRoundTripTime ?? null;
-					connection.availableOutgoingBitrate = r.availableOutgoingBitrate ?? null;
-				}
-			}
-		});
-		this.prevTimestamp = now;
-		return {
-			timestamp: Date.now(),
-			video,
-			audio,
-			outboundVideo,
-			connection
-		};
-	}
-};
-
-//#endregion
-export { WebRTCStatsCollector };