@decartai/sdk 0.0.67 → 0.1.0

package/dist/realtime/observability/livekit-stats-provider.js

@@ -0,0 +1,25 @@
+//#region src/realtime/observability/livekit-stats-provider.ts
+function createLiveKitStatsProvider(room) {
+	let uid = 0;
+	const collectFromTrack = async (track, entries) => {
+		if (!track) return;
+		let report;
+		try {
+			report = await track.getRTCStatsReport();
+		} catch {
+			return;
+		}
+		if (!report) return;
+		report.forEach((stat, id) => {
+			entries.push([`${id}#${uid++}`, stat]);
+		});
+	};
+	return { async getStats() {
+		const entries = [];
+		for (const pub of room.localParticipant.trackPublications.values()) await collectFromTrack(pub.track, entries);
+		for (const participant of room.remoteParticipants.values()) for (const pub of participant.trackPublications.values()) await collectFromTrack(pub.track, entries);
+		return new Map(entries);
+	} };
+}
+//#endregion
+export { createLiveKitStatsProvider };

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

@@ -0,0 +1,173 @@
+import { REALTIME_CONFIG } from "../config-realtime.js";
+import { createLiveKitStatsProvider } from "./livekit-stats-provider.js";
+import { NullTelemetryReporter, TelemetryReporter } from "./telemetry-reporter.js";
+import { WebRTCStatsCollector } from "./webrtc-stats.js";
+//#region src/realtime/observability/realtime-observability.ts
+var RealtimeObservability = class {
+	telemetryReporter = new NullTelemetryReporter();
+	telemetryReporterReady = false;
+	pendingTelemetryDiagnostics = [];
+	statsCollector = null;
+	statsCollectorSource = null;
+	liveKitRoom = null;
+	videoStalled = false;
+	stallStartMs = 0;
+	connectionBreakdown = null;
+	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);
+	}
+	beginConnectionBreakdown(attempt, initialImageSizeKb) {
+		this.connectionBreakdown = {
+			attempt,
+			connectStartedAt: Date.now(),
+			initialImageSizeKb,
+			phases: /* @__PURE__ */ new Map()
+		};
+	}
+	startPhase(name) {
+		if (!this.connectionBreakdown) return;
+		this.connectionBreakdown.phases.set(name, { startedAt: Date.now() });
+	}
+	endPhase(name, opts) {
+		if (!this.connectionBreakdown) return;
+		const entry = this.connectionBreakdown.phases.get(name);
+		if (!entry) {
+			this.options.logger.warn("observability: endPhase called for unknown phase", { phase: name });
+			return;
+		}
+		entry.endedAt = Date.now();
+		entry.success = opts.success;
+		if (opts.error !== void 0) entry.error = opts.error;
+	}
+	finishConnectionBreakdown(opts) {
+		const buffer = this.connectionBreakdown;
+		if (!buffer) return;
+		this.connectionBreakdown = null;
+		const now = Date.now();
+		const phases = [];
+		for (const [phase, entry] of buffer.phases) {
+			const unfinished = entry.endedAt === void 0;
+			const endedAt = entry.endedAt ?? now;
+			const success = entry.success ?? false;
+			const error = entry.error ?? (unfinished && !opts.success ? opts.error : void 0);
+			phases.push({
+				phase,
+				durationMs: endedAt - entry.startedAt,
+				success,
+				...error !== void 0 ? { error } : {}
+			});
+		}
+		this.diagnostic("client-session-connection-breakdown", {
+			attempt: buffer.attempt,
+			success: opts.success,
+			totalDurationMs: now - buffer.connectStartedAt,
+			initialImageSizeKb: buffer.initialImageSizeKb,
+			phases,
+			...opts.error !== void 0 ? { error: opts.error } : {}
+		}, now);
+	}
+	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.resetStallDetection();
+		this.statsCollectorSource = source;
+		if (!this.options.telemetryEnabled && !this.options.onStats) return;
+		this.statsCollector = new WebRTCStatsCollector();
+		this.statsCollector.start(source, (stats) => this.handleStats(stats));
+	}
+	setLiveKitRoom(room) {
+		if (!room) {
+			this.liveKitRoom = null;
+			this.setStatsProvider(null);
+			return;
+		}
+		if (room === this.liveKitRoom) return;
+		this.setStatsProvider(createLiveKitStatsProvider(room));
+		this.liveKitRoom = room;
+	}
+	stopStats() {
+		this.statsCollector?.stop();
+		this.statsCollector = null;
+		this.statsCollectorSource = null;
+		this.liveKitRoom = null;
+		this.resetStallDetection();
+	}
+	stop() {
+		this.stopStats();
+		this.telemetryReporter.stop();
+		this.telemetryReporter = new NullTelemetryReporter();
+		this.telemetryReporterReady = false;
+		this.pendingTelemetryDiagnostics.length = 0;
+		this.connectionBreakdown = null;
+	}
+	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 < REALTIME_CONFIG.observability.stallFpsThreshold) {
+			this.videoStalled = true;
+			this.stallStartMs = Date.now();
+			this.diagnostic("videoStall", {
+				stalled: true,
+				durationMs: 0
+			}, this.stallStartMs);
+		} else if (this.videoStalled && fps >= REALTIME_CONFIG.observability.stallFpsThreshold) {
+			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,14 +1,7 @@
-import { VERSION } from "../version.js";
-import { buildAuthHeaders } from "../shared/request.js";
-
-//#region src/realtime/telemetry-reporter.ts
-const DEFAULT_REPORT_INTERVAL_MS = 1e4;
-const TELEMETRY_URL = "https://platform.decart.ai/api/v1/telemetry";
-/**
-* Maximum number of items per array (stats / diagnostics) in a single report.
-* Matches the backend Zod schema which enforces `z.array().max(120)`.
-*/
-const MAX_ITEMS_PER_REPORT = 120;
+import { VERSION } from "../../version.js";
+import { buildAuthHeaders } from "../../shared/request.js";
+import { REALTIME_CONFIG } from "../config-realtime.js";
+//#region src/realtime/observability/telemetry-reporter.ts
 /** No-op reporter that silently discards all data. Used when telemetry is disabled. */
 var NullTelemetryReporter = class {
 	start() {}
@@ -22,7 +15,6 @@ var TelemetryReporter = class {
 	sessionId;
 	model;
 	integration;
-	logger;
 	reportIntervalMs;
 	intervalId = null;
 	statsBuffer = [];
@@ -32,8 +24,7 @@ var TelemetryReporter = class {
 		this.sessionId = options.sessionId;
 		this.model = options.model;
 		this.integration = options.integration;
-		this.logger = options.logger;
-		this.reportIntervalMs = options.reportIntervalMs ?? DEFAULT_REPORT_INTERVAL_MS;
+		this.reportIntervalMs = options.reportIntervalMs ?? REALTIME_CONFIG.observability.telemetryReportIntervalMs;
 	}
 	/** Start the periodic reporting timer. */
 	start() {
@@ -62,7 +53,7 @@ var TelemetryReporter = class {
 		this.diagnosticsBuffer = [];
 	}
 	/**
-	* Build a single chunk from the front of the buffers, respecting MAX_ITEMS_PER_REPORT.
+	* Build a single chunk from the front of the buffers, respecting the configured report item cap.
 	* Returns null when both buffers are empty.
 	*/
 	createReportChunk() {
@@ -79,8 +70,8 @@ var TelemetryReporter = class {
 			sdkVersion: VERSION,
 			...this.model ? { model: this.model } : {},
 			tags,
-			stats: this.statsBuffer.splice(0, MAX_ITEMS_PER_REPORT),
-			diagnostics: this.diagnosticsBuffer.splice(0, MAX_ITEMS_PER_REPORT)
+			stats: this.statsBuffer.splice(0, REALTIME_CONFIG.observability.telemetryMaxItemsPerReport),
+			diagnostics: this.diagnosticsBuffer.splice(0, REALTIME_CONFIG.observability.telemetryMaxItemsPerReport)
 		};
 	}
 	sendReport() {
@@ -95,25 +86,15 @@ var TelemetryReporter = class {
 			};
 			let chunk = this.createReportChunk();
 			while (chunk !== null) {
-				fetch(TELEMETRY_URL, {
+				fetch(REALTIME_CONFIG.observability.telemetryUrl, {
 					method: "POST",
 					headers: commonHeaders,
 					body: JSON.stringify(chunk)
-				}).then((response) => {
-					if (!response.ok) this.logger.warn("Telemetry report rejected", {
-						status: response.status,
-						statusText: response.statusText
-					});
-				}).catch((error) => {
-					this.logger.debug("Telemetry report failed", { error: String(error) });
-				});
+				}).catch(() => {});
 				chunk = this.createReportChunk();
 			}
-		} catch (error) {
-			this.logger.debug("Telemetry report failed", { error: String(error) });
-		}
+		} catch {}
 	}
 };
-
 //#endregion
-export { NullTelemetryReporter, TelemetryReporter };
+export { NullTelemetryReporter, TelemetryReporter };

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

@@ -0,0 +1,148 @@
+//#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: IceCandidatePair[];
+  };
+};
+/** 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;
+};
+type IceCandidatePair = {
+  local: IceCandidateInfo;
+  remote: IceCandidateInfo;
+};
+//#endregion
+export { WebRTCStats };