@decartai/sdk 0.0.47 → 0.0.49

package/dist/index.d.ts

@@ -1,13 +1,16 @@
+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 { AvatarOptions, Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState } from "./realtime/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 AvatarOptions, 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/queue/polling.js

@@ -19,12 +19,17 @@ async function pollUntilComplete({ checkStatus, getContent, onStatusChange, sign
 		if (signal?.aborted) throw new Error("Polling aborted");
 		const status = await checkStatus();
 		if (onStatusChange) onStatusChange(status);
-		if (status.status === "completed") return {
-			status: "completed",
-			data: await getContent()
-		};
+		if (status.status === "completed") {
+			const data = await getContent();
+			return {
+				status: "completed",
+				job_id: status.job_id,
+				data
+			};
+		}
 		if (status.status === "failed") return {
 			status: "failed",
+			job_id: status.job_id,
 			error: "Job failed"
 		};
 		await sleep(POLLING_DEFAULTS.interval);

package/dist/queue/types.d.ts

@@ -26,9 +26,11 @@ type JobStatusResponse = {
  */
 type QueueJobResult = {
   status: "completed";
+  job_id: string;
   data: Blob;
 } | {
   status: "failed";
+  job_id: string;
   error: string;
 };
 /**

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
@@ -10,13 +12,10 @@ declare const realTimeClientInitialStateSchema: z.ZodObject<{
     text: z.ZodString;
     enhance: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
   }, z.core.$strip>>;
+  image: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>>;
 }, z.core.$strip>;
 type OnRemoteStreamFn = (stream: MediaStream) => void;
 type RealTimeClientInitialState = z.infer<typeof realTimeClientInitialStateSchema>;
-declare const avatarOptionsSchema: z.ZodObject<{
-  avatarImage: z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>;
-}, z.core.$strip>;
-type AvatarOptions = z.infer<typeof avatarOptionsSchema>;
 declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
   model: z.ZodObject<{
     name: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"mirage">, z.ZodLiteral<"mirage_v2">, z.ZodLiteral<"lucy_v2v_720p_rt">, z.ZodLiteral<"lucy_2_rt">, z.ZodLiteral<"live_avatar">]>, z.ZodUnion<readonly [z.ZodLiteral<"lucy-dev-i2v">, z.ZodLiteral<"lucy-fast-v2v">, z.ZodLiteral<"lucy-pro-t2v">, z.ZodLiteral<"lucy-pro-i2v">, z.ZodLiteral<"lucy-pro-v2v">, z.ZodLiteral<"lucy-pro-flf2v">, z.ZodLiteral<"lucy-motion">, z.ZodLiteral<"lucy-restyle-v2v">]>, z.ZodUnion<readonly [z.ZodLiteral<"lucy-pro-t2i">, z.ZodLiteral<"lucy-pro-i2i">]>]>;
@@ -33,11 +32,9 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
       text: z.ZodString;
       enhance: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     }, z.core.$strip>>;
+    image: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>>;
   }, 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>>>;
-  avatar: z.ZodOptional<z.ZodObject<{
-    avatarImage: z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>;
-  }, z.core.$strip>>;
 }, z.core.$strip>;
 type RealTimeClientConnectOptions = z.infer<typeof realTimeClientConnectOptionsSchema>;
 type Events = {
@@ -46,6 +43,8 @@ type Events = {
   generationTick: {
     seconds: number;
   };
+  diagnostic: DiagnosticEvent;
+  stats: WebRTCStats;
 };
 type RealTimeClient = {
   set: (input: SetInput) => Promise<void>;
@@ -69,4 +68,4 @@ type RealTimeClient = {
   playAudio?: (audio: Blob | File | ArrayBuffer) => Promise<void>;
 };
 //#endregion
-export { AvatarOptions, Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState };
+export { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState };

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
@@ -51,25 +53,19 @@ async function imageToBase64(image) {
 }
 const realTimeClientInitialStateSchema = modelStateSchema;
 const createAsyncFunctionSchema = (schema) => z.custom((fn) => schema.implementAsync(fn));
-const avatarOptionsSchema = z.object({ avatarImage: z.union([
-	z.instanceof(Blob),
-	z.instanceof(File),
-	z.string()
-]) });
 const realTimeClientConnectOptionsSchema = z.object({
 	model: modelDefinitionSchema,
 	onRemoteStream: z.custom((val) => typeof val === "function", { message: "onRemoteStream must be a function" }),
 	initialState: realTimeClientInitialStateSchema.optional(),
-	customizeOffer: createAsyncFunctionSchema(z.function()).optional(),
-	avatar: avatarOptionsSchema.optional()
+	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;
 		const isAvatarLive = options.model.name === "live_avatar";
-		const { onRemoteStream, initialState, avatar } = parsedOptions.data;
+		const { onRemoteStream, initialState } = parsedOptions.data;
 		let audioStreamManager;
 		let inputStream;
 		if (isAvatarLive && !stream) {
@@ -77,14 +73,11 @@ const createRealTimeClient = (opts) => {
 			inputStream = audioStreamManager.getStream();
 		} else inputStream = stream ?? new MediaStream();
 		let webrtcManager;
+		let telemetryReporter = new NullTelemetryReporter();
+		let handleConnectionStateChange = null;
 		try {
-			let avatarImageBase64;
-			if (isAvatarLive && avatar?.avatarImage) if (typeof avatar.avatarImage === "string") {
-				const response = await fetch(avatar.avatarImage);
-				if (!response.ok) throw new Error(`Failed to fetch image: ${response.status} ${response.statusText}`);
-				avatarImageBase64 = await blobToBase64(await response.blob());
-			} else avatarImageBase64 = await blobToBase64(avatar.avatarImage);
-			const initialPrompt = isAvatarLive && initialState?.prompt ? {
+			const initialImage = initialState?.image ? await imageToBase64(initialState.image) : void 0;
+			const initialPrompt = initialState?.prompt ? {
 				text: initialState.prompt.text,
 				enhance: initialState.prompt.enhance
 			} : void 0;
@@ -93,27 +86,69 @@ 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,
 				vp8StartBitrate: 600,
-				isAvatarLive,
-				avatarImageBase64,
+				modelName: options.model.name,
+				initialImage,
 				initialPrompt
 			});
 			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) => {
@@ -122,16 +157,74 @@ const createRealTimeClient = (opts) => {
 			manager.getWebsocketMessageEmitter().on("generationTick", tickListener);
 			await manager.connect(inputStream);
 			const methods = realtimeMethods(manager, imageToBase64);
-			if (!isAvatarLive && initialState?.prompt) {
-				const { text, enhance } = initialState.prompt;
-				await methods.setPrompt(text, { enhance });
-			}
+			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();
@@ -157,6 +250,7 @@ const createRealTimeClient = (opts) => {
 			flush();
 			return client;
 		} catch (error) {
+			telemetryReporter.stop();
 			webrtcManager?.cleanup();
 			audioStreamManager?.cleanup();
 			throw error;
@@ -171,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 };