@decartai/sdk 0.0.68 → 0.1.1

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

@@ -1,16 +1,18 @@
+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
-const STALL_FPS_THRESHOLD = .5;
 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;
 	}
@@ -22,6 +24,56 @@ var RealtimeObservability = class {
 		});
 		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();
@@ -45,15 +97,27 @@ var RealtimeObservability = class {
 		}
 		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() {
@@ -62,6 +126,7 @@ var RealtimeObservability = class {
 		this.telemetryReporter = new NullTelemetryReporter();
 		this.telemetryReporterReady = false;
 		this.pendingTelemetryDiagnostics.length = 0;
+		this.connectionBreakdown = null;
 	}
 	handleStats(stats) {
 		this.options.onStats?.(stats);
@@ -70,14 +135,14 @@ var RealtimeObservability = class {
 	}
 	detectVideoStall(stats) {
 		const fps = stats.video?.framesPerSecond ?? 0;
-		if (!this.videoStalled && stats.video && fps < STALL_FPS_THRESHOLD) {
+		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 >= STALL_FPS_THRESHOLD) {
+		} else if (this.videoStalled && fps >= REALTIME_CONFIG.observability.stallFpsThreshold) {
 			const durationMs = Date.now() - this.stallStartMs;
 			this.videoStalled = false;
 			this.diagnostic("videoStall", {
@@ -104,6 +169,5 @@ var RealtimeObservability = class {
 		this.stallStartMs = 0;
 	}
 };
-
 //#endregion
-export { RealtimeObservability };
+export { RealtimeObservability };

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

@@ -1,14 +1,7 @@
 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
-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;
 /** 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

@@ -127,10 +127,7 @@ type WebRTCStats = {
      * jitter and failure modes, so this is essential signal for
      * benchmarking and incident triage.
      */
-    selectedCandidatePairs: Array<{
-      local: IceCandidateInfo;
-      remote: IceCandidateInfo;
-    }>;
+    selectedCandidatePairs: IceCandidatePair[];
   };
 };
 /** One side of an ICE candidate pair (sender or receiver). */
@@ -143,5 +140,9 @@ type IceCandidateInfo = {
   /** "udp" | "tcp" */
   protocol: string;
 };
+type IceCandidatePair = {
+  local: IceCandidateInfo;
+  remote: IceCandidateInfo;
+};
 //#endregion
 export { WebRTCStats };

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

@@ -1,6 +1,5 @@
+import { REALTIME_CONFIG } from "../config-realtime.js";
 //#region src/realtime/observability/webrtc-stats.ts
-const DEFAULT_INTERVAL_MS = 1e3;
-const MIN_INTERVAL_MS = 500;
 var WebRTCStatsCollector = class {
 	source = null;
 	intervalId = null;
@@ -17,7 +16,7 @@ var WebRTCStatsCollector = class {
 	onStats = null;
 	intervalMs;
 	constructor(options = {}) {
-		this.intervalMs = Math.max(options.intervalMs ?? DEFAULT_INTERVAL_MS, MIN_INTERVAL_MS);
+		this.intervalMs = Math.max(options.intervalMs ?? REALTIME_CONFIG.observability.statsDefaultIntervalMs, REALTIME_CONFIG.observability.statsMinIntervalMs);
 	}
 	/** Attach to a stats provider and start polling. */
 	start(source, onStats) {
@@ -273,6 +272,5 @@ var WebRTCStatsCollector = class {
 		};
 	}
 };
-
 //#endregion
-export { WebRTCStatsCollector };
+export { WebRTCStatsCollector };

package/dist/realtime/signaling-channel.js

@@ -0,0 +1,302 @@
+import { buildUserAgent } from "../utils/user-agent.js";
+import { createConsoleLogger } from "../utils/logger.js";
+import { REALTIME_CONFIG } from "./config-realtime.js";
+import mitt from "mitt";
+//#region src/realtime/signaling-channel.ts
+var SignalingChannel = class {
+	ws = null;
+	events = mitt();
+	pendingAcks = [];
+	pendingRoomInfo = null;
+	connected = false;
+	closing = false;
+	logger;
+	constructor(config) {
+		this.config = config;
+		this.logger = config.logger ?? createConsoleLogger("warn");
+	}
+	on(event, handler) {
+		this.events.on(event, handler);
+	}
+	off(event, handler) {
+		this.events.off(event, handler);
+	}
+	async openAndJoin(opts = {}) {
+		const connectTimeout = opts.connectTimeout ?? REALTIME_CONFIG.signaling.connectTimeoutMs;
+		const handshakeTimeout = opts.handshakeTimeout ?? REALTIME_CONFIG.signaling.handshakeTimeoutMs;
+		this.config.observability?.startPhase("websocket-open");
+		await this.openSocket(connectTimeout);
+		this.config.observability?.endPhase("websocket-open", { success: true });
+		this.config.observability?.startPhase("room-join");
+		const roomInfoWait = this.waitForRoomInfo(handshakeTimeout);
+		if (!this.writeMessage({ type: "livekit_join" })) {
+			roomInfoWait.cancel();
+			throw new Error("WebSocket is not open");
+		}
+		let roomInfo;
+		try {
+			roomInfo = await roomInfoWait.promise;
+		} catch (error) {
+			this.rejectAllPending(error instanceof Error ? error : new Error(String(error)));
+			throw error;
+		}
+		this.config.observability?.endPhase("room-join", { success: true });
+		this.connected = true;
+		const initialStateAck = this.sendInitialStateTracked(opts.initialState);
+		initialStateAck.catch(() => {});
+		return {
+			roomInfo,
+			initialStateAck
+		};
+	}
+	async sendInitialStateTracked(initialState) {
+		if (!initialState) return;
+		this.config.observability?.startPhase("initial-state-handshake");
+		await this.sendInitialState(initialState);
+		this.config.observability?.endPhase("initial-state-handshake", { success: true });
+	}
+	close() {
+		this.closing = true;
+		this.connected = false;
+		const ws = this.ws;
+		this.ws = null;
+		if (ws) try {
+			ws.close();
+		} catch {}
+		this.rejectPendingRoomInfo(/* @__PURE__ */ new Error("Control channel closed"));
+		this.rejectAllPending(/* @__PURE__ */ new Error("Control channel closed"));
+	}
+	async sendPrompt(text, opts = {}) {
+		const ack = await this.request({
+			message: {
+				type: "prompt",
+				prompt: text,
+				enhance_prompt: opts.enhance ?? true
+			},
+			matchAck: (msg) => msg.type === "prompt_ack" && msg.prompt === text,
+			timeoutMs: opts.timeout ?? REALTIME_CONFIG.signaling.requestTimeoutMs,
+			label: "Prompt send"
+		});
+		if (!ack.success) throw new Error(ack.error ?? "Failed to send prompt");
+	}
+	async setImage(payload, opts = {}) {
+		const message = payload.kind === "ref" ? {
+			type: "set_image",
+			image_ref: payload.ref
+		} : {
+			type: "set_image",
+			image_data: payload.data
+		};
+		if (opts.prompt !== void 0) message.prompt = opts.prompt;
+		if (opts.enhance !== void 0) message.enhance_prompt = opts.enhance;
+		const ack = await this.request({
+			message,
+			matchAck: (msg) => msg.type === "set_image_ack",
+			timeoutMs: opts.timeout ?? REALTIME_CONFIG.signaling.requestTimeoutMs,
+			label: "Image send"
+		});
+		if (!ack.success) throw new Error(ack.error ?? "Failed to send image");
+	}
+	async openSocket(timeout) {
+		const userAgent = encodeURIComponent(buildUserAgent(this.config.integration));
+		const separator = this.config.url.includes("?") ? "&" : "?";
+		const wsUrl = `${this.config.url}${separator}user_agent=${userAgent}`;
+		this.closing = false;
+		await new Promise((resolve, reject) => {
+			const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`WebSocket open timeout (${timeout}ms)`)), timeout);
+			const ws = new WebSocket(wsUrl);
+			this.ws = ws;
+			ws.onopen = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			ws.onclose = (e) => {
+				clearTimeout(timer);
+				const wasConnected = this.connected;
+				const pendingCount = this.pendingAcks.length;
+				this.connected = false;
+				this.ws = null;
+				this.logger.warn("signaling: websocket closed", {
+					code: e.code,
+					reason: e.reason,
+					wasConnected,
+					closing: this.closing,
+					pendingAcks: pendingCount
+				});
+				const error = /* @__PURE__ */ new Error(`WebSocket closed: ${e.code} ${e.reason}`);
+				this.rejectPendingRoomInfo(error);
+				this.rejectAllPending(error);
+				if (wasConnected || this.closing) this.events.emit("closed", {
+					code: e.code,
+					reason: e.reason
+				});
+				else reject(error);
+			};
+			ws.onerror = () => {};
+			ws.onmessage = (e) => {
+				try {
+					this.handleMessage(JSON.parse(e.data));
+				} catch {}
+			};
+		});
+	}
+	waitForRoomInfo(timeoutMs) {
+		let cleanup = () => {};
+		return {
+			promise: new Promise((resolve, reject) => {
+				let timer = setTimeout(() => {
+					cleanup();
+					this.logger.warn("signaling: livekit_room_info timeout", { timeoutMs });
+					reject(/* @__PURE__ */ new Error(`livekit_room_info timeout (${timeoutMs}ms)`));
+				}, timeoutMs);
+				const pendingRoomInfo = {
+					resolve: (info) => {
+						cleanup();
+						resolve(info);
+					},
+					reject: (err) => {
+						cleanup();
+						reject(err);
+					},
+					cancel: () => {
+						cleanup();
+					},
+					pauseTimeout: () => {
+						if (timer) {
+							clearTimeout(timer);
+							timer = null;
+						}
+					}
+				};
+				cleanup = () => {
+					if (timer) {
+						clearTimeout(timer);
+						timer = null;
+					}
+					if (this.pendingRoomInfo === pendingRoomInfo) this.pendingRoomInfo = null;
+				};
+				this.pendingRoomInfo = pendingRoomInfo;
+			}),
+			cancel: cleanup
+		};
+	}
+	async sendInitialState(initialState) {
+		if (!initialState) return;
+		if (initialState.imageRef !== void 0) {
+			await this.setImage({
+				kind: "ref",
+				ref: initialState.imageRef
+			}, {
+				prompt: initialState.prompt,
+				enhance: initialState.enhance
+			});
+			return;
+		}
+		if (initialState.image !== void 0) {
+			await this.setImage({
+				kind: "data",
+				data: initialState.image
+			}, {
+				prompt: initialState.prompt,
+				enhance: initialState.enhance
+			});
+			return;
+		}
+		if (initialState.prompt !== void 0 && initialState.prompt !== null) await this.sendPrompt(initialState.prompt, { enhance: initialState.enhance });
+	}
+	async request({ message, matchAck, timeoutMs, label }) {
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				cleanup();
+				this.logger.warn("signaling: ack timed out", {
+					label,
+					timeoutMs
+				});
+				reject(/* @__PURE__ */ new Error(`${label} timed out`));
+			}, timeoutMs);
+			const entry = {
+				matches: matchAck,
+				onMatch: (msg) => {
+					cleanup();
+					resolve(msg);
+				},
+				reject: (err) => {
+					cleanup();
+					reject(err);
+				}
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				this.pendingAcks = this.pendingAcks.filter((e) => e !== entry);
+			};
+			this.pendingAcks.push(entry);
+			if (!this.writeMessage(message)) {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("WebSocket is not open"));
+			}
+		});
+	}
+	writeMessage(message) {
+		if (this.ws?.readyState !== WebSocket.OPEN) return false;
+		this.ws.send(JSON.stringify(message));
+		return true;
+	}
+	handleMessage(msg) {
+		for (const ack of [...this.pendingAcks]) if (ack.matches(msg)) {
+			ack.onMatch(msg);
+			break;
+		}
+		switch (msg.type) {
+			case "livekit_room_info":
+				this.resolvePendingRoomInfo({
+					livekitUrl: msg.livekit_url,
+					token: msg.token,
+					roomName: msg.room_name,
+					sessionId: msg.session_id
+				});
+				break;
+			case "queue_position":
+				this.pendingRoomInfo?.pauseTimeout();
+				this.events.emit("queuePosition", {
+					position: msg.position,
+					queueSize: msg.queue_size
+				});
+				break;
+			case "generation_tick":
+				this.events.emit("generationTick", { seconds: msg.seconds });
+				break;
+			case "generation_ended":
+				this.events.emit("generationEnded", {
+					seconds: msg.seconds,
+					reason: msg.reason
+				});
+				break;
+			case "error": {
+				const error = new Error(msg.error);
+				error.source = "server";
+				this.logger.error("signaling: server error received", { error: msg.error });
+				this.events.emit("serverError", error);
+				this.rejectPendingRoomInfo(error);
+				this.rejectAllPending(error);
+				break;
+			}
+		}
+	}
+	resolvePendingRoomInfo(info) {
+		const pending = this.pendingRoomInfo;
+		if (!pending) return;
+		pending.resolve(info);
+	}
+	rejectPendingRoomInfo(error) {
+		const pending = this.pendingRoomInfo;
+		if (!pending) return;
+		pending.reject(error);
+	}
+	rejectAllPending(error) {
+		const pending = this.pendingAcks;
+		this.pendingAcks = [];
+		for (const entry of pending) entry.reject(error);
+	}
+};
+//#endregion
+export { SignalingChannel };