@decartai/sdk 0.0.48 → 0.0.49

package/dist/index.d.ts

@@ -1,12 +1,15 @@
+import { LogLevel, Logger, createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { ImageModelDefinition, ImageModels, Model, ModelDefinition, RealTimeModels, VideoModelDefinition, VideoModels, isImageModel, isRealtimeModel, isVideoModel, models } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
 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 { 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 { CreateTokenResponse, TokensClient } from "./tokens/client.js";
@@ -17,11 +20,15 @@ type DecartClientOptions = {
   apiKey?: never;
   baseUrl?: string;
   integration?: string;
+  logger?: Logger;
+  telemetry?: boolean;
 } | {
   proxy?: never;
   apiKey?: string;
   baseUrl?: string;
   integration?: string;
+  logger?: Logger;
+  telemetry?: boolean;
 };
 /**
  * Create a Decart API client.
@@ -121,4 +128,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   tokens: TokensClient;
 };
 //#endregion
-export { type ConnectionState, type CreateTokenResponse, DecartClientOptions, type DecartSDKError, ERROR_CODES, type FileInput, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type Model, type ModelDefinition, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type VideoModelDefinition, type VideoModels, createDecartClient, isImageModel, isRealtimeModel, isVideoModel, models };
+export { type ConnectionPhase, type ConnectionState, type CreateTokenResponse, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type IceCandidateEvent, type IceStateEvent, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelState, type PeerConnectionStateEvent, type PhaseTimingEvent, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SelectedCandidatePairEvent, type SetInput, type SignalingStateEvent, type SubscribeEvents, type SubscribeOptions, type TokensClient, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isImageModel, isRealtimeModel, isVideoModel, models, noopLogger };

package/dist/index.js

@@ -5,6 +5,7 @@ import { isImageModel, isRealtimeModel, isVideoModel, models } from "./shared/mo
 import { createRealTimeClient } from "./realtime/client.js";
 import { createTokensClient } from "./tokens/client.js";
 import { readEnv } from "./utils/env.js";
+import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { z } from "zod";
 
 //#region src/index.ts
@@ -56,11 +57,15 @@ const createDecartClient = (options = {}) => {
 	if (isProxyMode && "proxy" in parsedOptions.data && parsedOptions.data.proxy) baseUrl = parsedOptions.data.proxy;
 	else baseUrl = parsedOptions.data.baseUrl || "https://api.decart.ai";
 	const { integration } = parsedOptions.data;
+	const logger = "logger" in options && options.logger ? options.logger : noopLogger;
+	const telemetryEnabled = "telemetry" in options && options.telemetry === false ? false : true;
 	return {
 		realtime: createRealTimeClient({
 			baseUrl: "wss://api3.decart.ai",
 			apiKey: apiKey || "",
-			integration
+			integration,
+			logger,
+			telemetryEnabled
 		}),
 		process: createProcessClient({
 			baseUrl,
@@ -81,4 +86,4 @@ const createDecartClient = (options = {}) => {
 };
 
 //#endregion
-export { ERROR_CODES, createDecartClient, isImageModel, isRealtimeModel, isVideoModel, models };
+export { ERROR_CODES, createConsoleLogger, createDecartClient, isImageModel, isRealtimeModel, isVideoModel, models, noopLogger };

package/dist/realtime/client.d.ts

@@ -1,6 +1,8 @@
 import { DecartSDKError } from "../utils/errors.js";
+import { DiagnosticEvent } from "./diagnostics.js";
 import { ConnectionState } from "./types.js";
 import { SetInput } from "./methods.js";
+import { WebRTCStats } from "./webrtc-stats.js";
 import { z } from "zod";
 
 //#region src/realtime/client.d.ts
@@ -41,6 +43,8 @@ type Events = {
   generationTick: {
     seconds: number;
   };
+  diagnostic: DiagnosticEvent;
+  stats: WebRTCStats;
 };
 type RealTimeClient = {
   set: (input: SetInput) => Promise<void>;

package/dist/realtime/client.js

@@ -1,11 +1,13 @@
-import { createWebrtcError } from "../utils/errors.js";
+import { classifyWebrtcError } from "../utils/errors.js";
 import { modelDefinitionSchema } from "../shared/model.js";
 import { modelStateSchema } from "../shared/types.js";
 import { AudioStreamManager } from "./audio-stream-manager.js";
 import { createEventBuffer } from "./event-buffer.js";
 import { realtimeMethods } from "./methods.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,7 +60,7 @@ const realTimeClientConnectOptionsSchema = z.object({
 	customizeOffer: createAsyncFunctionSchema(z.function()).optional()
 });
 const createRealTimeClient = (opts) => {
-	const { baseUrl, apiKey, integration } = opts;
+	const { baseUrl, apiKey, integration, logger } = opts;
 	const connect = async (stream, options) => {
 		const parsedOptions = realTimeClientConnectOptionsSchema.safeParse(options);
 		if (!parsedOptions.success) throw parsedOptions.error;
@@ -71,6 +73,8 @@ const createRealTimeClient = (opts) => {
 			inputStream = audioStreamManager.getStream();
 		} else inputStream = stream ?? new MediaStream();
 		let webrtcManager;
+		let telemetryReporter = new NullTelemetryReporter();
+		let handleConnectionStateChange = null;
 		try {
 			const initialImage = initialState?.image ? await imageToBase64(initialState.image) : void 0;
 			const initialPrompt = initialState?.prompt ? {
@@ -82,13 +86,22 @@ const createRealTimeClient = (opts) => {
 			webrtcManager = new WebRTCManager({
 				webrtcUrl: `${url}?api_key=${encodeURIComponent(apiKey)}&model=${encodeURIComponent(options.model.name)}`,
 				integration,
+				logger,
+				onDiagnostic: (name, data) => {
+					emitOrBuffer("diagnostic", {
+						name,
+						data
+					});
+					addTelemetryDiagnostic(name, data);
+				},
 				onRemoteStream,
 				onConnectionStateChange: (state) => {
 					emitOrBuffer("connectionChange", state);
+					handleConnectionStateChange?.(state);
 				},
 				onError: (error) => {
-					console.error("WebRTC error:", error);
-					emitOrBuffer("error", createWebrtcError(error));
+					logger.error("WebRTC error", { error: error.message });
+					emitOrBuffer("error", classifyWebrtcError(error));
 				},
 				customizeOffer: options.customizeOffer,
 				vp8MinBitrate: 300,
@@ -100,9 +113,42 @@ 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;
+				}
 			};
 			manager.getWebsocketMessageEmitter().on("sessionId", sessionIdListener);
 			const tickListener = (msg) => {
@@ -111,12 +157,74 @@ 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();
 					stop();
 					manager.cleanup();
 					audioStreamManager?.cleanup();
@@ -142,6 +250,7 @@ const createRealTimeClient = (opts) => {
 			flush();
 			return client;
 		} catch (error) {
+			telemetryReporter.stop();
 			webrtcManager?.cleanup();
 			audioStreamManager?.cleanup();
 			throw error;
@@ -156,13 +265,20 @@ const createRealTimeClient = (opts) => {
 			webrtcManager = new WebRTCManager({
 				webrtcUrl: subscribeUrl,
 				integration,
+				logger,
+				onDiagnostic: (name, data) => {
+					emitOrBuffer("diagnostic", {
+						name,
+						data
+					});
+				},
 				onRemoteStream: options.onRemoteStream,
 				onConnectionStateChange: (state) => {
 					emitOrBuffer("connectionChange", state);
 				},
 				onError: (error) => {
-					console.error("WebRTC subscribe error:", error);
-					emitOrBuffer("error", createWebrtcError(error));
+					logger.error("WebRTC subscribe error", { error: error.message });
+					emitOrBuffer("error", classifyWebrtcError(error));
 				}
 			});
 			const manager = webrtcManager;

package/dist/realtime/diagnostics.d.ts

@@ -0,0 +1,78 @@
+//#region src/realtime/diagnostics.d.ts
+/** Connection phase names for timing events. */
+type ConnectionPhase = "websocket" | "avatar-image" | "initial-prompt" | "webrtc-handshake" | "total";
+type PhaseTimingEvent = {
+  phase: ConnectionPhase;
+  durationMs: number;
+  success: boolean;
+  error?: string;
+};
+type IceCandidateEvent = {
+  source: "local" | "remote";
+  candidateType: "host" | "srflx" | "prflx" | "relay" | "unknown";
+  protocol: "udp" | "tcp" | "unknown";
+  address?: string;
+  port?: number;
+};
+type IceStateEvent = {
+  state: string;
+  previousState: string;
+  timestampMs: number;
+};
+type PeerConnectionStateEvent = {
+  state: string;
+  previousState: string;
+  timestampMs: number;
+};
+type SignalingStateEvent = {
+  state: string;
+  previousState: string;
+  timestampMs: number;
+};
+type SelectedCandidatePairEvent = {
+  local: {
+    candidateType: string;
+    protocol: string;
+    address?: string;
+    port?: number;
+  };
+  remote: {
+    candidateType: string;
+    protocol: string;
+    address?: string;
+    port?: number;
+  };
+};
+type ReconnectEvent = {
+  attempt: number;
+  maxAttempts: number;
+  durationMs: number;
+  success: boolean;
+  error?: string;
+};
+type VideoStallEvent = {
+  /** True when a stall is detected, false when recovered. */
+  stalled: boolean;
+  /** Duration of the stall in ms (0 when stall first detected, actual duration on recovery). */
+  durationMs: number;
+};
+/** All diagnostic event types keyed by name. */
+type DiagnosticEvents = {
+  phaseTiming: PhaseTimingEvent;
+  iceCandidate: IceCandidateEvent;
+  iceStateChange: IceStateEvent;
+  peerConnectionStateChange: PeerConnectionStateEvent;
+  signalingStateChange: SignalingStateEvent;
+  selectedCandidatePair: SelectedCandidatePairEvent;
+  reconnect: ReconnectEvent;
+  videoStall: VideoStallEvent;
+};
+type DiagnosticEventName = keyof DiagnosticEvents;
+/** A single diagnostic event with its name and typed data. */
+type DiagnosticEvent = { [K in DiagnosticEventName]: {
+  name: K;
+  data: DiagnosticEvents[K];
+} }[DiagnosticEventName];
+/** Callback for emitting diagnostic events from the connection/manager layers. */
+//#endregion
+export { ConnectionPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, IceCandidateEvent, IceStateEvent, PeerConnectionStateEvent, PhaseTimingEvent, ReconnectEvent, SelectedCandidatePairEvent, SignalingStateEvent, VideoStallEvent };

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

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

package/dist/realtime/telemetry-reporter.js

@@ -0,0 +1,120 @@
+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;
+/** No-op reporter that silently discards all data. Used when telemetry is disabled. */
+var NullTelemetryReporter = class {
+	start() {}
+	addStats() {}
+	addDiagnostic() {}
+	flush() {}
+	stop() {}
+};
+var TelemetryReporter = class {
+	apiKey;
+	sessionId;
+	model;
+	integration;
+	logger;
+	reportIntervalMs;
+	intervalId = null;
+	statsBuffer = [];
+	diagnosticsBuffer = [];
+	constructor(options) {
+		this.apiKey = options.apiKey;
+		this.sessionId = options.sessionId;
+		this.model = options.model;
+		this.integration = options.integration;
+		this.logger = options.logger;
+		this.reportIntervalMs = options.reportIntervalMs ?? DEFAULT_REPORT_INTERVAL_MS;
+	}
+	/** Start the periodic reporting timer. */
+	start() {
+		if (this.intervalId !== null) return;
+		this.intervalId = setInterval(() => this.flush(), this.reportIntervalMs);
+	}
+	/** Add a stats snapshot to the buffer. */
+	addStats(stats) {
+		this.statsBuffer.push(stats);
+	}
+	/** Add a diagnostic event to the buffer. */
+	addDiagnostic(event) {
+		this.diagnosticsBuffer.push(event);
+	}
+	/** Flush buffered data immediately. */
+	flush() {
+		this.sendReport(false);
+	}
+	/** Stop the reporter and send a final report with keepalive. */
+	stop() {
+		if (this.intervalId !== null) {
+			clearInterval(this.intervalId);
+			this.intervalId = null;
+		}
+		this.sendReport(true);
+	}
+	/**
+	* Build a single chunk from the front of the buffers, respecting MAX_ITEMS_PER_REPORT.
+	* Returns null when both buffers are empty.
+	*/
+	createReportChunk() {
+		if (this.statsBuffer.length === 0 && this.diagnosticsBuffer.length === 0) return null;
+		const tags = {
+			session_id: this.sessionId,
+			sdk_version: VERSION,
+			...this.model ? { model: this.model } : {},
+			...this.integration ? { integration: this.integration } : {}
+		};
+		return {
+			sessionId: this.sessionId,
+			timestamp: Date.now(),
+			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)
+		};
+	}
+	sendReport(keepalive) {
+		if (this.statsBuffer.length === 0 && this.diagnosticsBuffer.length === 0) return;
+		try {
+			const commonHeaders = {
+				...buildAuthHeaders({
+					apiKey: this.apiKey,
+					integration: this.integration
+				}),
+				"Content-Type": "application/json"
+			};
+			let chunk = this.createReportChunk();
+			while (chunk !== null) {
+				const isLast = this.statsBuffer.length === 0 && this.diagnosticsBuffer.length === 0;
+				fetch(TELEMETRY_URL, {
+					method: "POST",
+					headers: commonHeaders,
+					body: JSON.stringify(chunk),
+					keepalive: keepalive && isLast
+				}).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) });
+				});
+				chunk = this.createReportChunk();
+			}
+		} catch (error) {
+			this.logger.debug("Telemetry report failed", { error: String(error) });
+		}
+	}
+};
+
+//#endregion
+export { NullTelemetryReporter, TelemetryReporter };

package/dist/realtime/webrtc-connection.js

@@ -4,15 +4,28 @@ import mitt from "mitt";
 //#region src/realtime/webrtc-connection.ts
 const ICE_SERVERS = [{ urls: "stun:stun.l.google.com:19302" }];
 const AVATAR_SETUP_TIMEOUT_MS = 3e4;
+const noopDiagnostic = () => {};
 var WebRTCConnection = class {
 	pc = null;
 	ws = null;
 	localStream = null;
 	connectionReject = null;
+	logger;
+	emitDiagnostic;
 	state = "disconnected";
 	websocketMessagesEmitter = mitt();
 	constructor(callbacks = {}) {
 		this.callbacks = callbacks;
+		this.logger = callbacks.logger ?? {
+			debug() {},
+			info() {},
+			warn() {},
+			error() {}
+		};
+		this.emitDiagnostic = callbacks.onDiagnostic ?? noopDiagnostic;
+	}
+	getPeerConnection() {
+		return this.pc;
 	}
 	async connect(url, localStream, timeout, integration) {
 		const deadline = Date.now() + timeout;
@@ -25,24 +38,37 @@ var WebRTCConnection = class {
 		});
 		connectAbort.catch(() => {});
 		this.connectionReject = (error) => rejectConnect(error);
+		const totalStart = performance.now();
 		try {
+			const wsStart = performance.now();
 			await Promise.race([new Promise((resolve, reject) => {
 				const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("WebSocket timeout")), timeout);
 				this.ws = new WebSocket(wsUrl);
 				this.ws.onopen = () => {
 					clearTimeout(timer);
+					this.emitDiagnostic("phaseTiming", {
+						phase: "websocket",
+						durationMs: performance.now() - wsStart,
+						success: true
+					});
 					resolve();
 				};
 				this.ws.onmessage = (e) => {
 					try {
 						this.handleSignalingMessage(JSON.parse(e.data));
 					} catch (err) {
-						console.error("[WebRTC] Parse error:", err);
+						this.logger.error("Signaling message parse error", { error: String(err) });
 					}
 				};
 				this.ws.onerror = () => {
 					clearTimeout(timer);
 					const error = /* @__PURE__ */ new Error("WebSocket error");
+					this.emitDiagnostic("phaseTiming", {
+						phase: "websocket",
+						durationMs: performance.now() - wsStart,
+						success: false,
+						error: error.message
+					});
 					reject(error);
 					rejectConnect(error);
 				};
@@ -53,27 +79,65 @@ var WebRTCConnection = class {
 					rejectConnect(/* @__PURE__ */ new Error("WebSocket closed"));
 				};
 			}), connectAbort]);
-			if (this.callbacks.initialImage) await Promise.race([this.setImageBase64(this.callbacks.initialImage, {
-				prompt: this.callbacks.initialPrompt?.text,
-				enhance: this.callbacks.initialPrompt?.enhance
-			}), connectAbort]);
-			else if (this.callbacks.initialPrompt) await Promise.race([this.sendInitialPrompt(this.callbacks.initialPrompt), connectAbort]);
+			if (this.callbacks.initialImage) {
+				const imageStart = performance.now();
+				await Promise.race([this.setImageBase64(this.callbacks.initialImage, {
+					prompt: this.callbacks.initialPrompt?.text,
+					enhance: this.callbacks.initialPrompt?.enhance
+				}), connectAbort]);
+				this.emitDiagnostic("phaseTiming", {
+					phase: "avatar-image",
+					durationMs: performance.now() - imageStart,
+					success: true
+				});
+			} else if (this.callbacks.initialPrompt) {
+				const promptStart = performance.now();
+				await Promise.race([this.sendInitialPrompt(this.callbacks.initialPrompt), connectAbort]);
+				this.emitDiagnostic("phaseTiming", {
+					phase: "initial-prompt",
+					durationMs: performance.now() - promptStart,
+					success: true
+				});
+			}
+			const handshakeStart = performance.now();
 			await this.setupNewPeerConnection();
 			await Promise.race([new Promise((resolve, reject) => {
 				const checkConnection = setInterval(() => {
 					if (this.state === "connected" || this.state === "generating") {
 						clearInterval(checkConnection);
+						this.emitDiagnostic("phaseTiming", {
+							phase: "webrtc-handshake",
+							durationMs: performance.now() - handshakeStart,
+							success: true
+						});
 						resolve();
 					} else if (this.state === "disconnected") {
 						clearInterval(checkConnection);
+						this.emitDiagnostic("phaseTiming", {
+							phase: "webrtc-handshake",
+							durationMs: performance.now() - handshakeStart,
+							success: false,
+							error: "Connection lost during handshake"
+						});
 						reject(/* @__PURE__ */ new Error("Connection lost during WebRTC handshake"));
 					} else if (Date.now() >= deadline) {
 						clearInterval(checkConnection);
+						this.emitDiagnostic("phaseTiming", {
+							phase: "webrtc-handshake",
+							durationMs: performance.now() - handshakeStart,
+							success: false,
+							error: "Timeout"
+						});
 						reject(/* @__PURE__ */ new Error("Connection timeout"));
 					}
 				}, 100);
 				connectAbort.catch(() => clearInterval(checkConnection));
 			}), connectAbort]);
+			this.emitDiagnostic("phaseTiming", {
+				phase: "total",
+				durationMs: performance.now() - totalStart,
+				success: true
+			});
 		} finally {
 			this.connectionReject = null;
 		}
@@ -82,6 +146,7 @@ var WebRTCConnection = class {
 		try {
 			if (msg.type === "error") {
 				const error = new Error(msg.error);
+				error.source = "server";
 				this.callbacks.onError?.(error);
 				if (this.connectionReject) {
 					this.connectionReject(error);
@@ -144,7 +209,14 @@ var WebRTCConnection = class {
 					});
 					break;
 				case "ice-candidate":
-					if (msg.candidate) await this.pc.addIceCandidate(msg.candidate);
+					if (msg.candidate) {
+						await this.pc.addIceCandidate(msg.candidate);
+						this.emitDiagnostic("iceCandidate", {
+							source: "remote",
+							candidateType: msg.candidate.candidate?.match(/typ (\w+)/)?.[1] ?? "unknown",
+							protocol: msg.candidate.candidate?.match(/udp|tcp/i)?.[0]?.toLowerCase() ?? "unknown"
+						});
+					}
 					break;
 				case "ice-restart": {
 					const turnConfig = msg.turn_config;
@@ -153,7 +225,7 @@ var WebRTCConnection = class {
 				}
 			}
 		} catch (error) {
-			console.error("[WebRTC] Error:", error);
+			this.logger.error("Signaling handler error", { error: String(error) });
 			this.callbacks.onError?.(error);
 			this.connectionReject?.(error);
 		}
@@ -163,7 +235,7 @@ var WebRTCConnection = class {
 			this.ws.send(JSON.stringify(message));
 			return true;
 		}
-		console.warn("[WebRTC] Message dropped: WebSocket is not open");
+		this.logger.warn("Message dropped: WebSocket is not open");
 		return false;
 	}
 	async setImageBase64(imageBase64, options) {
@@ -265,22 +337,90 @@ var WebRTCConnection = class {
 				type: "ice-candidate",
 				candidate: e.candidate
 			});
+			if (e.candidate) this.emitDiagnostic("iceCandidate", {
+				source: "local",
+				candidateType: e.candidate.type ?? "unknown",
+				protocol: e.candidate.protocol ?? "unknown",
+				address: e.candidate.address ?? void 0,
+				port: e.candidate.port ?? void 0
+			});
 		};
+		let prevPcState = "new";
 		this.pc.onconnectionstatechange = () => {
 			if (!this.pc) return;
 			const s = this.pc.connectionState;
+			this.emitDiagnostic("peerConnectionStateChange", {
+				state: s,
+				previousState: prevPcState,
+				timestampMs: performance.now()
+			});
+			prevPcState = s;
+			if (s === "connected") this.emitSelectedCandidatePair();
 			const nextState = s === "connected" ? "connected" : ["connecting", "new"].includes(s) ? "connecting" : "disconnected";
 			if (this.state === "generating" && nextState !== "disconnected") return;
 			this.setState(nextState);
 		};
+		let prevIceState = "new";
 		this.pc.oniceconnectionstatechange = () => {
-			if (this.pc?.iceConnectionState === "failed") {
+			if (!this.pc) return;
+			const newIceState = this.pc.iceConnectionState;
+			this.emitDiagnostic("iceStateChange", {
+				state: newIceState,
+				previousState: prevIceState,
+				timestampMs: performance.now()
+			});
+			prevIceState = newIceState;
+			if (newIceState === "failed") {
 				this.setState("disconnected");
 				this.callbacks.onError?.(/* @__PURE__ */ new Error("ICE connection failed"));
 			}
 		};
+		let prevSignalingState = "stable";
+		this.pc.onsignalingstatechange = () => {
+			if (!this.pc) return;
+			const newState = this.pc.signalingState;
+			this.emitDiagnostic("signalingStateChange", {
+				state: newState,
+				previousState: prevSignalingState,
+				timestampMs: performance.now()
+			});
+			prevSignalingState = newState;
+		};
 		this.handleSignalingMessage({ type: "ready" });
 	}
+	async emitSelectedCandidatePair() {
+		if (!this.pc) return;
+		try {
+			const stats = await this.pc.getStats();
+			let found = false;
+			stats.forEach((report) => {
+				if (found) return;
+				if (report.type === "candidate-pair" && report.state === "succeeded") {
+					found = true;
+					let localCandidate;
+					let remoteCandidate;
+					stats.forEach((r) => {
+						if (r.id === report.localCandidateId) localCandidate = r;
+						if (r.id === report.remoteCandidateId) remoteCandidate = r;
+					});
+					if (localCandidate && remoteCandidate) this.emitDiagnostic("selectedCandidatePair", {
+						local: {
+							candidateType: String(localCandidate.candidateType ?? "unknown"),
+							protocol: String(localCandidate.protocol ?? "unknown"),
+							address: localCandidate.address,
+							port: localCandidate.port
+						},
+						remote: {
+							candidateType: String(remoteCandidate.candidateType ?? "unknown"),
+							protocol: String(remoteCandidate.protocol ?? "unknown"),
+							address: remoteCandidate.address,
+							port: remoteCandidate.port
+						}
+					});
+				}
+			});
+		} catch {}
+	}
 	cleanup() {
 		this.pc?.close();
 		this.pc = null;
@@ -292,17 +432,17 @@ var WebRTCConnection = class {
 	applyCodecPreference(preferredCodecName) {
 		if (!this.pc) return;
 		if (typeof RTCRtpSender === "undefined" || typeof RTCRtpSender.getCapabilities !== "function") {
-			console.warn("RTCRtpSender capabilities are not available in this environment.");
+			this.logger.debug("RTCRtpSender capabilities not available in this environment");
 			return;
 		}
 		const videoTransceiver = this.pc.getTransceivers().find((r) => r.sender.track?.kind === "video" || r.receiver.track?.kind === "video");
 		if (!videoTransceiver) {
-			console.error("Could not find video transceiver. Ensure track is added to peer connection.");
+			this.logger.warn("Video transceiver not found for codec preference");
 			return;
 		}
 		const capabilities = RTCRtpSender.getCapabilities("video");
 		if (!capabilities) {
-			console.error("Could not get video sender capabilities.");
+			this.logger.warn("Video sender capabilities unavailable");
 			return;
 		}
 		const preferredCodecs = [];
@@ -313,13 +453,13 @@ var WebRTCConnection = class {
 		});
 		const orderedCodecs = [...preferredCodecs, ...otherCodecs];
 		if (orderedCodecs.length === 0) {
-			console.warn("No video codecs found to set preferences for.");
+			this.logger.debug("No video codecs found for preference setting");
 			return;
 		}
 		try {
 			videoTransceiver.setCodecPreferences(orderedCodecs);
 		} catch {
-			console.warn("[WebRTC] setCodecPreferences not supported, skipping codec preference.");
+			this.logger.debug("setCodecPreferences not supported, skipping");
 		}
 	}
 	modifyVP8Bitrate(offer) {

package/dist/realtime/webrtc-manager.js

@@ -20,6 +20,7 @@ const RETRY_OPTIONS = {
 var WebRTCManager = class {
 	connection;
 	config;
+	logger;
 	localStream = null;
 	subscribeMode = false;
 	managerState = "disconnected";
@@ -29,6 +30,12 @@ var WebRTCManager = class {
 	reconnectGeneration = 0;
 	constructor(config) {
 		this.config = config;
+		this.logger = config.logger ?? {
+			debug() {},
+			info() {},
+			warn() {},
+			error() {}
+		};
 		this.connection = new WebRTCConnection({
 			onRemoteStream: config.onRemoteStream,
 			onStateChange: (state) => this.handleConnectionStateChange(state),
@@ -38,7 +45,9 @@ var WebRTCManager = class {
 			vp8StartBitrate: config.vp8StartBitrate,
 			modelName: config.modelName,
 			initialImage: config.initialImage,
-			initialPrompt: config.initialPrompt
+			initialPrompt: config.initialPrompt,
+			logger: this.logger,
+			onDiagnostic: config.onDiagnostic
 		});
 	}
 	emitState(state) {
@@ -72,8 +81,11 @@ var WebRTCManager = class {
 		const reconnectGeneration = ++this.reconnectGeneration;
 		this.isReconnecting = true;
 		this.emitState("reconnecting");
+		const reconnectStart = performance.now();
 		try {
+			let attemptCount = 0;
 			await pRetry(async () => {
+				attemptCount++;
 				if (this.intentionalDisconnect || reconnectGeneration !== this.reconnectGeneration) throw new AbortError("Reconnect cancelled");
 				if (!this.subscribeMode && !this.localStream) throw new AbortError("Reconnect cancelled: no local stream");
 				this.connection.cleanup();
@@ -86,7 +98,17 @@ var WebRTCManager = class {
 				...RETRY_OPTIONS,
 				onFailedAttempt: (error) => {
 					if (this.intentionalDisconnect || reconnectGeneration !== this.reconnectGeneration) return;
-					console.error(`[WebRTC] Reconnect attempt failed: ${error.message}`);
+					this.logger.warn("Reconnect attempt failed", {
+						error: error.message,
+						attempt: error.attemptNumber
+					});
+					this.config.onDiagnostic?.("reconnect", {
+						attempt: error.attemptNumber,
+						maxAttempts: RETRY_OPTIONS.retries + 1,
+						durationMs: performance.now() - reconnectStart,
+						success: false,
+						error: error.message
+					});
 					this.connection.cleanup();
 				},
 				shouldRetry: (error) => {
@@ -95,6 +117,12 @@ var WebRTCManager = class {
 					return !PERMANENT_ERRORS.some((err) => msg.includes(err));
 				}
 			});
+			this.config.onDiagnostic?.("reconnect", {
+				attempt: attemptCount,
+				maxAttempts: RETRY_OPTIONS.retries + 1,
+				durationMs: performance.now() - reconnectStart,
+				success: true
+			});
 		} catch (error) {
 			this.isReconnecting = false;
 			if (this.intentionalDisconnect || reconnectGeneration !== this.reconnectGeneration) return;
@@ -117,7 +145,10 @@ var WebRTCManager = class {
 		}, {
 			...RETRY_OPTIONS,
 			onFailedAttempt: (error) => {
-				console.error(`[WebRTC] Failed to connect: ${error.message}`);
+				this.logger.warn("Connection attempt failed", {
+					error: error.message,
+					attempt: error.attemptNumber
+				});
 				this.connection.cleanup();
 			},
 			shouldRetry: (error) => {
@@ -144,6 +175,9 @@ var WebRTCManager = class {
 	getConnectionState() {
 		return this.managerState;
 	}
+	getPeerConnection() {
+		return this.connection.getPeerConnection();
+	}
 	getWebsocketMessageEmitter() {
 		return this.connection.websocketMessagesEmitter;
 	}

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

@@ -0,0 +1,59 @@
+//#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

@@ -0,0 +1,154 @@
+//#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 };

package/dist/utils/errors.d.ts

@@ -8,7 +8,6 @@ type DecartSDKError = {
 declare const ERROR_CODES: {
   readonly INVALID_API_KEY: "INVALID_API_KEY";
   readonly INVALID_BASE_URL: "INVALID_BASE_URL";
-  readonly WEB_RTC_ERROR: "WEB_RTC_ERROR";
   readonly PROCESSING_ERROR: "PROCESSING_ERROR";
   readonly INVALID_INPUT: "INVALID_INPUT";
   readonly INVALID_OPTIONS: "INVALID_OPTIONS";
@@ -18,6 +17,11 @@ declare const ERROR_CODES: {
   readonly QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR";
   readonly JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED";
   readonly TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR";
+  readonly WEBRTC_WEBSOCKET_ERROR: "WEBRTC_WEBSOCKET_ERROR";
+  readonly WEBRTC_ICE_ERROR: "WEBRTC_ICE_ERROR";
+  readonly WEBRTC_TIMEOUT_ERROR: "WEBRTC_TIMEOUT_ERROR";
+  readonly WEBRTC_SERVER_ERROR: "WEBRTC_SERVER_ERROR";
+  readonly WEBRTC_SIGNALING_ERROR: "WEBRTC_SIGNALING_ERROR";
 };
 //#endregion
 export { DecartSDKError, ERROR_CODES };

package/dist/utils/errors.js

@@ -2,7 +2,6 @@
 const ERROR_CODES = {
 	INVALID_API_KEY: "INVALID_API_KEY",
 	INVALID_BASE_URL: "INVALID_BASE_URL",
-	WEB_RTC_ERROR: "WEB_RTC_ERROR",
 	PROCESSING_ERROR: "PROCESSING_ERROR",
 	INVALID_INPUT: "INVALID_INPUT",
 	INVALID_OPTIONS: "INVALID_OPTIONS",
@@ -11,7 +10,12 @@ const ERROR_CODES = {
 	QUEUE_STATUS_ERROR: "QUEUE_STATUS_ERROR",
 	QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR",
 	JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED",
-	TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR"
+	TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR",
+	WEBRTC_WEBSOCKET_ERROR: "WEBRTC_WEBSOCKET_ERROR",
+	WEBRTC_ICE_ERROR: "WEBRTC_ICE_ERROR",
+	WEBRTC_TIMEOUT_ERROR: "WEBRTC_TIMEOUT_ERROR",
+	WEBRTC_SERVER_ERROR: "WEBRTC_SERVER_ERROR",
+	WEBRTC_SIGNALING_ERROR: "WEBRTC_SIGNALING_ERROR"
 };
 function createSDKError(code, message, data, cause) {
 	return {
@@ -27,8 +31,38 @@ function createInvalidApiKeyError() {
 function createInvalidBaseUrlError(url) {
 	return createSDKError(ERROR_CODES.INVALID_BASE_URL, `Invalid base URL${url ? `: ${url}` : ""}`);
 }
-function createWebrtcError(error) {
-	return createSDKError(ERROR_CODES.WEB_RTC_ERROR, "WebRTC error", { cause: error });
+function createWebrtcWebsocketError(error) {
+	return createSDKError(ERROR_CODES.WEBRTC_WEBSOCKET_ERROR, "WebSocket connection failed", void 0, error);
+}
+function createWebrtcIceError(error) {
+	return createSDKError(ERROR_CODES.WEBRTC_ICE_ERROR, "ICE connection failed", void 0, error);
+}
+function createWebrtcTimeoutError(phase, timeoutMs, cause) {
+	const hasTimeout = typeof timeoutMs === "number" && Number.isFinite(timeoutMs);
+	return createSDKError(ERROR_CODES.WEBRTC_TIMEOUT_ERROR, hasTimeout ? `${phase} timed out after ${timeoutMs}ms` : `${phase} timed out`, hasTimeout ? {
+		phase,
+		timeoutMs
+	} : { phase }, cause);
+}
+function createWebrtcServerError(message) {
+	return createSDKError(ERROR_CODES.WEBRTC_SERVER_ERROR, message);
+}
+function createWebrtcSignalingError(error) {
+	return createSDKError(ERROR_CODES.WEBRTC_SIGNALING_ERROR, "Signaling error", void 0, error);
+}
+/**
+* Classify a raw WebRTC error into a specific SDK error based on its message.
+*/
+function classifyWebrtcError(error) {
+	const msg = error.message.toLowerCase();
+	if (error.source === "server") return createWebrtcServerError(error.message);
+	if (msg.includes("websocket")) return createWebrtcWebsocketError(error);
+	if (msg.includes("ice connection failed")) return createWebrtcIceError(error);
+	if (msg.includes("timeout") || msg.includes("timed out")) {
+		const timeoutMatch = msg.match(/(\d+)\s*ms/);
+		return createWebrtcTimeoutError("connection", timeoutMatch ? Number.parseInt(timeoutMatch[1], 10) : void 0, error);
+	}
+	return createWebrtcSignalingError(error);
 }
 function createInvalidInputError(message) {
 	return createSDKError(ERROR_CODES.INVALID_INPUT, message);
@@ -47,4 +81,4 @@ function createQueueResultError(message, status) {
 }
 
 //#endregion
-export { ERROR_CODES, createInvalidApiKeyError, createInvalidBaseUrlError, createInvalidInputError, createModelNotFoundError, createQueueResultError, createQueueStatusError, createQueueSubmitError, createSDKError, createWebrtcError };
+export { ERROR_CODES, classifyWebrtcError, createInvalidApiKeyError, createInvalidBaseUrlError, createInvalidInputError, createModelNotFoundError, createQueueResultError, createQueueStatusError, createQueueSubmitError, createSDKError };

package/dist/utils/logger.d.ts

@@ -0,0 +1,18 @@
+//#region src/utils/logger.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+type Logger = {
+  debug: (message: string, data?: Record<string, unknown>) => void;
+  info: (message: string, data?: Record<string, unknown>) => void;
+  warn: (message: string, data?: Record<string, unknown>) => void;
+  error: (message: string, data?: Record<string, unknown>) => void;
+};
+/** A logger that discards all messages. Zero overhead. */
+declare const noopLogger: Logger;
+/**
+ * Creates a console-based logger that only logs messages at or above the given level.
+ *
+ * @param minLevel - Minimum log level to output. Default: "warn".
+ */
+declare function createConsoleLogger(minLevel?: LogLevel): Logger;
+//#endregion
+export { LogLevel, Logger, createConsoleLogger, noopLogger };

package/dist/utils/logger.js

@@ -0,0 +1,37 @@
+//#region src/utils/logger.ts
+/** A logger that discards all messages. Zero overhead. */
+const noopLogger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {}
+};
+const LOG_LEVELS = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+/**
+* Creates a console-based logger that only logs messages at or above the given level.
+*
+* @param minLevel - Minimum log level to output. Default: "warn".
+*/
+function createConsoleLogger(minLevel = "warn") {
+	const threshold = LOG_LEVELS[minLevel];
+	const log = (level, message, data) => {
+		if (LOG_LEVELS[level] < threshold) return;
+		const prefix = "[DecartSDK]";
+		if (data) console[level](prefix, message, data);
+		else console[level](prefix, message);
+	};
+	return {
+		debug: (msg, data) => log("debug", msg, data),
+		info: (msg, data) => log("info", msg, data),
+		warn: (msg, data) => log("warn", msg, data),
+		error: (msg, data) => log("error", msg, data)
+	};
+}
+
+//#endregion
+export { createConsoleLogger, noopLogger };

package/package.json

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