@decartai/sdk 0.1.14 → 0.1.16

package/dist/realtime/config-realtime.js

@@ -44,43 +44,78 @@ const REALTIME_CONFIG = {
 		telemetryReportIntervalMs: 1e4,
 		telemetryUrl: "https://platform.decart.ai/api/v1/telemetry",
 		telemetryMaxItemsPerReport: 120,
+		/**
+		* Thresholds for the derived in-session connection-quality signal
+		* (see observability/connection-quality.ts). Tuned for a camera-up
+		* real-time pipeline (~3–3.5 Mbps upstream, model fps ~25–30). All
+		* values are tunable here so behaviour can change without code edits.
+		*/
 		connectionQuality: {
+			/** Rolling-window size used to smooth raw per-sample metrics. */
 			windowSamples: 5,
+			/**
+			* Samples to wait before the bitrate dimensions count — the encoder
+			* and BWE ramp for several seconds after connect, so early low
+			* bitrate is not a slow network. RTT/loss/stall start scoring sooner.
+			* `decart-try-on` waits 30 samples watching inbound bitrate alone.
+			*/
 			warmupSamples: 8,
+			/** Consecutive worse samples required before the level downgrades. */
 			downgradeConsecutive: 5,
+			/** Consecutive better samples required before the level upgrades (recover slow). */
 			upgradeConsecutive: 5,
+			/** Round-trip time bands (ms). Bands widen by relayExtraMs on TURN-relayed paths. */
 			rtt: {
 				goodMs: 150,
 				fairMs: 300,
 				poorMs: 500,
 				relayExtraMs: 100
 			},
+			/**
+			* Mid-stream (steady-state) true glass-to-glass latency bands (ms) — the
+			* real per-frame camera→display latency through the model, used for the
+			* latency dimension *instead of* RTT when frame-metadata measurement is on.
+			* Already includes both network legs, so relayExtraMs does not apply.
+			* Excludes startup (see `ttff`). Anchored to Datadog
+			* `rt.stream.pipeline_latency_ms` (server-side median ~285ms / p95 ~510ms)
+			* plus network + jitter-buffer + decode headroom. Tune with real data.
+			*/
 			glassToGlass: {
 				goodMs: 500,
 				fairMs: 900,
 				poorMs: 1500
 			},
+			/**
+			* Time-to-first-frame bands (ms) — startup latency from connect to the
+			* first rendered model frame. An order of magnitude larger than mid-stream
+			* and judged separately (a slow first frame is a different problem from a
+			* laggy steady state). ~4–5s is an acceptable ("fair") cold start today.
+			*/
 			ttff: {
 				goodMs: 4e3,
 				fairMs: 6e3,
 				poorMs: 1e4
 			},
+			/** Fraction of outbound packets the server reports lost (0..1). */
 			loss: {
 				good: .001,
 				fair: .01,
 				poor: .05
 			},
+			/** End-to-end frame drop ratio (0..1), when a frame identity is available. */
 			g2gDrop: {
 				good: .001,
 				fair: .01,
 				poor: .05
 			},
+			/** Upstream headroom = available BWE ÷ the intended publish bitrate (requiredUpstreamKbps). */
 			upstream: {
 				goodRatio: 1,
 				fairRatio: .8,
 				poorRatio: .5,
 				requiredUpstreamKbps: 3500
 			},
+			/** Rendered (inbound) frames-per-second. */
 			stall: {
 				goodFps: 20,
 				fairFps: 12,
@@ -88,13 +123,29 @@ const REALTIME_CONFIG = {
 			}
 		}
 	},
+	/**
+	* SDK-only preflight (see preflight.ts). Validates WebRTC reachability
+	* (does UDP egress work / will the path need TURN) and latency via a
+	* throwaway RTCPeerConnection — no backend session, no media server.
+	*/
 	preflight: {
+		/** Public STUN servers used to gather server-reflexive candidates. */
 		defaultStunUrls: ["stun:stun.l.google.com:19302"],
+		/** Abort candidate gathering after this long. */
 		iceGatherTimeoutMs: 5e3,
+		/** RTT bands (ms) for the preflight verdict. */
 		rtt: {
 			goodMs: 150,
 			marginalMs: 300
 		},
+		/**
+		* Deep probe (`checkConnectivity({ deep: true, model })`): briefly opens a
+		* real session with a synthetic source + frame-metadata measurement to get a
+		* true glass-to-glass verdict, then tears it down. Costs a short GPU session.
+		* The verdict reuses the in-session `connectionQuality` bands. Duration must
+		* cover TTFF (~4–5s) + mid-stream warm-up (~2s) before steady-state samples
+		* accrue; resolves early once `minSamples` exist.
+		*/
 		active: {
 			durationMs: 12e3,
 			minSamples: 5

package/dist/realtime/livekit.js

@@ -23,4 +23,4 @@ function loadLiveKitClient() {
 	return liveKitModulePromise;
 }
 //#endregion
-export { loadLiveKitClient };
+export { loadLiveKitClient, validateLiveKitModule };

package/dist/realtime/media-channel.js

@@ -3,7 +3,7 @@ import { REALTIME_CONFIG } from "./config-realtime.js";
 import { loadLiveKitClient } from "./livekit.js";
 import mitt from "mitt";
 //#region src/realtime/media-channel.ts
-function getDefaultVideoPublishOptions(source, videoCodec) {
+function getDefaultVideoPublishOptions(source, videoCodec, frameMetadata = false) {
 	const resolvedCodec = videoCodec ?? REALTIME_CONFIG.livekit.defaultVideoCodec;
 	const maxBitrate = resolvedCodec === "vp9" ? REALTIME_CONFIG.livekit.vp9MaxVideoBitrateBps : REALTIME_CONFIG.livekit.defaultMaxVideoBitrateBps;
 	return {
@@ -13,13 +13,16 @@ function getDefaultVideoPublishOptions(source, videoCodec) {
 		videoEncoding: {
 			maxBitrate,
 			maxFramerate: REALTIME_CONFIG.livekit.defaultPublishFps
-		}
+		},
+		...frameMetadata ? { frameMetadata: { timestamp: true } } : {}
 	};
 }
 var LiveKitMediaChannel = class {
+	config;
 	room = null;
 	cameraTrackSource = null;
 	remoteStream = null;
+	frameMetadataEnabled = false;
 	events = mitt();
 	logger;
 	constructor(config) {
@@ -38,14 +41,32 @@ var LiveKitMediaChannel = class {
 	async connect(opts) {
 		const { Room: LiveKitRoom, RoomEvent, Track } = await loadLiveKitClient();
 		this.cameraTrackSource = Track.Source.Camera;
-		this.room ??= new LiveKitRoom(REALTIME_CONFIG.livekit.roomOptions);
+		if (!this.room) {
+			let worker;
+			if (this.config.createFrameMetadataWorker) try {
+				worker = this.config.createFrameMetadataWorker();
+			} catch (error) {
+				this.logger.warn("Failed to create LiveKit frame-metadata worker; continuing without latency metrics", { error: error instanceof Error ? error.message : String(error) });
+			}
+			this.frameMetadataEnabled = worker !== void 0;
+			try {
+				this.room = new LiveKitRoom({
+					...REALTIME_CONFIG.livekit.roomOptions,
+					...worker ? { frameMetadata: { worker } } : {}
+				});
+			} catch (error) {
+				worker?.terminate();
+				this.frameMetadataEnabled = false;
+				throw error;
+			}
+		}
 		const room = this.room;
 		room.on(RoomEvent.TrackSubscribed, (track, _pub, participant) => {
 			if (!participant.identity.startsWith(REALTIME_CONFIG.livekit.inferenceServerIdentityPrefix)) return;
 			if (track.kind !== "video" && track.kind !== "audio") return;
 			const mediaStreamTrack = track.mediaStreamTrack;
 			if (mediaStreamTrack) {
-				if (track.kind === "video") this.config.observability?.attachRemoteVideoTrack(mediaStreamTrack);
+				if (track.kind === "video") this.config.observability?.attachRemoteVideoTrack(track);
 				const tracks = this.remoteStream?.getTracks() ?? [];
 				if (!tracks.includes(mediaStreamTrack)) tracks.push(mediaStreamTrack);
 				this.remoteStream = new MediaStream(tracks);
@@ -79,6 +100,7 @@ var LiveKitMediaChannel = class {
 		this.room = null;
 		this.cameraTrackSource = null;
 		this.remoteStream = null;
+		this.frameMetadataEnabled = false;
 		this.config.observability?.setLiveKitRoom(null);
 		if (room) room.disconnect().catch(() => {});
 	}
@@ -86,10 +108,10 @@ var LiveKitMediaChannel = class {
 		if (!this.room) return;
 		for (const track of stream.getTracks()) if (track.kind === "video") {
 			if (!this.cameraTrackSource) throw new Error("Cannot publish video track: media channel is not connected");
-			await this.room.localParticipant.publishTrack(track, getDefaultVideoPublishOptions(this.cameraTrackSource, this.config.videoCodec));
+			await this.room.localParticipant.publishTrack(track, getDefaultVideoPublishOptions(this.cameraTrackSource, this.config.videoCodec, this.frameMetadataEnabled));
 		} else await this.room.localParticipant.publishTrack(track);
 	}
 };
 const createLiveKitMediaChannel = (config) => new LiveKitMediaChannel(config);
 //#endregion
-export { createLiveKitMediaChannel };
+export { LiveKitMediaChannel, createLiveKitMediaChannel, getDefaultVideoPublishOptions };

package/dist/realtime/methods.js

@@ -6,6 +6,10 @@ import { z } from "zod";
 const setInputSchema = z.object({
 	prompt: z.string().min(1).optional(),
 	enhance: z.boolean().optional().default(true),
+	/**
+	* - `Blob`/`File`/data:/http(s):/base64 string: bytes traverse the wire as base64.
+	* - `"file_..."` id (from `client.files.upload(...).id`): sent as a server-side reference.
+	*/
 	image: z.union([
 		globalInstanceSchema("Blob"),
 		globalInstanceSchema("File"),

package/dist/realtime/observability/connection-quality.d.ts

@@ -17,7 +17,7 @@ type ConnectionQualityMetrics = {
   /**
    * Mid-stream (steady-state) glass-to-glass latency (ms) — the real per-frame
    * camera→display latency through the model, excluding startup. Only populated
-   * when the opt-in pixel-marker measurement is on (`connect({ debugQuality: true })`)
+   * when the opt-in frame-metadata measurement is on (`connect({ debugQuality: true })`)
    * and past warm-up; null otherwise. When present it drives the latency verdict
    * instead of `rttMs`.
    */
@@ -36,8 +36,8 @@ type ConnectionQualityMetrics = {
   /** Server's view of upstream (client→server) jitter in ms, or null. Observational. */
   upstreamJitterMs: number | null;
   /**
-   * End-to-end frame drop ratio (0–1) inferred from the pixel-marker seq stream.
-   * Only populated under the opt-in g2g measurement; null otherwise.
+   * End-to-end frame drop ratio (0–1). Null until frame identity is propagated
+   * end-to-end; latency measurement itself only requires the capture timestamp.
    */
   g2gDropRatio: number | null;
   /** Estimated available upstream bandwidth in kbps. Chromium-only — null on Safari/Firefox. */

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

@@ -76,6 +76,7 @@ function minOrNull(values) {
 	return values.length === 0 ? null : Math.min(...values);
 }
 var RingBuffer = class {
+	size;
 	values = [];
 	constructor(size) {
 		this.size = size;
@@ -101,6 +102,7 @@ var RingBuffer = class {
 * warm-up state changes; `current()` returns the latest at any time.
 */
 var ConnectionQualityEvaluator = class {
+	thresholds;
 	rtt;
 	glassToGlass;
 	loss;
@@ -216,4 +218,4 @@ var ConnectionQualityEvaluator = class {
 	}
 };
 //#endregion
-export { ConnectionQualityEvaluator, extractSignals, scoreLowerBetter, worst };
+export { ConnectionQualityEvaluator, RANK, extractSignals, scoreLowerBetter, scoreMetrics, worst };

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

@@ -5,6 +5,7 @@ import { NullTelemetryReporter, TelemetryReporter } from "./telemetry-reporter.j
 import { WebRTCStatsCollector } from "./webrtc-stats.js";
 //#region src/realtime/observability/realtime-observability.ts
 var RealtimeObservability = class {
+	options;
 	telemetryReporter = new NullTelemetryReporter();
 	telemetryReporterReady = false;
 	pendingTelemetryDiagnostics = [];
@@ -20,22 +21,7 @@ var RealtimeObservability = class {
 		this.options = options;
 		this.glassToGlass = options.glassToGlass;
 	}
-	/**
-	* Wrap the outgoing stream so each frame carries a marker, feeding the shared
-	* tracker that the reader matches against. Returns the stream to publish
-	* (unchanged when g2g is off or stamping can't start). Owned here so the
-	* writer and reader of the tracker share one lifecycle and survive reconnects.
-	*/
-	attachOutgoingStream(stream, fps) {
-		if (!this.glassToGlass) return stream;
-		try {
-			return this.glassToGlass.attachOutgoingStream(stream, fps);
-		} catch (error) {
-			this.options.logger.warn("Failed to start glass-to-glass stamp pump; continuing without it", { error: error instanceof Error ? error.message : String(error) });
-			return stream;
-		}
-	}
-	/** Feed the remote video track to the marker reader (called from the media channel). */
+	/** Feed the LiveKit remote video track to the frame-metadata reader. */
 	attachRemoteVideoTrack(track) {
 		this.glassToGlass?.attachRemoteVideoTrack(track);
 	}

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

@@ -133,8 +133,8 @@ type WebRTCStats = {
   };
   /**
    * True glass-to-glass latency + end-to-end drop signal, merged in by
-   * `RealtimeObservability` when the opt-in pixel-marker measurement is active
-   * (see glass-to-glass.ts). Null otherwise — the stats collector does not
+   * `RealtimeObservability` when the opt-in frame-metadata measurement is active.
+   * Null otherwise — the stats collector does not
    * populate it.
    */
   glassToGlass: G2GMetrics | null;
@@ -154,4 +154,4 @@ type IceCandidatePair = {
   remote: IceCandidateInfo;
 };
 //#endregion
-export { WebRTCStats };
+export { IceCandidateInfo, IceCandidatePair, WebRTCStats };

package/dist/realtime/signaling-channel.js

@@ -36,6 +36,7 @@ function buildInitialStateRequest(initialState) {
 	return null;
 }
 var SignalingChannel = class {
+	config;
 	ws = null;
 	events = mitt();
 	pendingAcks = [];
@@ -66,7 +67,8 @@ var SignalingChannel = class {
 		const userSetInitialState = opts.initialState != null && (opts.initialState.image != null || opts.initialState.imageRef != null || opts.initialState.prompt != null);
 		const joinMessage = {
 			type: "livekit_join",
-			passthrough: opts.passthrough ?? !userSetInitialState
+			passthrough: opts.passthrough ?? !userSetInitialState,
+			...opts.frameTiming ? { client_capabilities: { frame_timing: true } } : {}
 		};
 		if (!this.writeMessage(joinMessage)) {
 			roomInfoWait.cancel();

package/dist/realtime/stream-session.js

@@ -16,6 +16,7 @@ function getInitialImageSizeKb(image) {
 	return Math.max(0, Math.round(bytes / 1024));
 }
 var StreamSession = class {
+	config;
 	signaling;
 	media;
 	events = mitt();
@@ -109,7 +110,8 @@ var StreamSession = class {
 			const { roomInfo, initialStateAck } = await this.signaling.openAndJoin({
 				connectTimeout: REALTIME_CONFIG.session.connectionTimeoutMs,
 				initialState,
-				passthrough: this.config.initialPassthrough
+				passthrough: this.config.initialPassthrough,
+				frameTiming: this.config.frameTiming
 			});
 			this.watchInitialStateAck(initialStateAck, attempt);
 			if (this.disposed || this.currentAttempt !== attempt) {
@@ -266,4 +268,4 @@ var StreamSession = class {
 	}
 };
 //#endregion
-export { StreamSession };
+export { StreamSession, encodeSubscribeToken };

package/dist/realtime/subscribe-client.js

@@ -122,4 +122,4 @@ const createRealTimeSubscribeClient = (opts) => {
 	return { subscribe };
 };
 //#endregion
-export { createRealTimeSubscribeClient };
+export { createRealTimeSubscribeClient, decodeSubscribeToken };

package/dist/shared/model.d.ts

@@ -411,4 +411,4 @@ declare const models: {
   };
 };
 //#endregion
-export { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelInputSchemas, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelInputSchemas, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, canonicalModelSchema, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelInputSchemas, modelSchema, models, realtimeModels, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/dist/shared/model.js

@@ -488,18 +488,45 @@ function listModels(options = {}) {
 	});
 }
 const models = {
+	/**
+	* Get a realtime streaming model identifier.
+	*
+	* Available options:
+	*   - `"lucy-2.1"` - Lucy 2.1 realtime video editing
+	*   - `"lucy-2.5"` - Lucy 2.5 realtime video editing
+	*   - `"lucy-vton-2"` - Lucy virtual try-on 2
+	*   - `"lucy-vton-3"` - Lucy virtual try-on 3
+	*   - `"lucy-restyle-2"` - Realtime video restyling
+	*/
 	realtime: (model) => {
 		warnDeprecated(model);
 		const modelDefinition = _models.realtime[model];
 		if (!modelDefinition) throw createModelNotFoundError(model);
 		return modelDefinition;
 	},
+	/**
+	* Get a video model identifier.
+	*
+	* Available options:
+	*   - `"lucy-clip"` - Video-to-video editing
+	*   - `"lucy-2.1"` - Long-form video editing (Lucy 2.1)
+	*   - `"lucy-2.5"` - Long-form video editing (Lucy 2.5)
+	*   - `"lucy-vton-2"` - Virtual try-on 2 video editing
+	*   - `"lucy-vton-3"` - Virtual try-on 3 video editing
+	*   - `"lucy-restyle-2"` - Video restyling
+	*/
 	video: (model) => {
 		warnDeprecated(model);
 		const modelDefinition = _models.video[model];
 		if (!modelDefinition) throw createModelNotFoundError(model);
 		return modelDefinition;
 	},
+	/**
+	* Get an image model identifier.
+	*
+	* Available options:
+	*   - `"lucy-image-2"` - Image-to-image editing
+	*/
 	image: (model) => {
 		warnDeprecated(model);
 		const modelDefinition = _models.image[model];
@@ -508,4 +535,4 @@ const models = {
 	}
 };
 //#endregion
-export { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { canonicalImageModels, canonicalModelSchema, canonicalRealtimeModels, canonicalVideoModels, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, modelInputSchemas, modelSchema, models, realtimeModels, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/dist/shared/types.d.ts

@@ -11,4 +11,4 @@ declare const modelStateSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ModelState = z.infer<typeof modelStateSchema>;
 //#endregion
-export { ModelState };
+export { ModelState, modelStateSchema };

package/dist/shared/types.js

@@ -6,6 +6,12 @@ const modelStateSchema = z.object({
 		text: z.string().min(1),
 		enhance: z.boolean().optional().default(true)
 	}).optional(),
+	/**
+	* Initial image for the session. Pass either bytes (`Blob`/`File`/data URL/
+	* http(s) URL/base64 string) or a `"file_..."` id returned by
+	* `client.files.upload(...)`.id — the SDK detects the prefix and sends a
+	* server-side reference instead of base64.
+	*/
 	image: z.union([
 		globalInstanceSchema("Blob"),
 		globalInstanceSchema("File"),

package/dist/utils/errors.js

@@ -98,4 +98,4 @@ function createQueueResultError(message, status) {
 	return createSDKError(ERROR_CODES.QUEUE_RESULT_ERROR, message, { status });
 }
 //#endregion
-export { ERROR_CODES, classifyWebrtcError, createInvalidApiKeyError, createInvalidBaseUrlError, createInvalidInputError, createLiveKitInitializationError, createModelNotFoundError, createQueueResultError, createQueueStatusError, createQueueSubmitError, createReactNativeSetupRequiredError, createSDKError, createUnsupportedPlatformFeatureError };
+export { ERROR_CODES, classifyWebrtcError, createInvalidApiKeyError, createInvalidBaseUrlError, createInvalidInputError, createLiveKitInitializationError, createModelNotFoundError, createQueueResultError, createQueueStatusError, createQueueSubmitError, createReactNativeSetupRequiredError, createSDKError, createUnsupportedPlatformFeatureError, createWebrtcIceError, createWebrtcServerError, createWebrtcSignalingError, createWebrtcTimeoutError, createWebrtcWebsocketError };

package/dist/utils/media.js

@@ -40,4 +40,4 @@ async function imageToBase64(image) {
 	return blobToBase64(image);
 }
 //#endregion
-export { imageToBase64 };
+export { blobToBase64, imageToBase64 };

package/dist/utils/user-agent.js

@@ -27,4 +27,4 @@ function buildUserAgent(integration, globalThisAny = globalThis) {
 	].join(" ");
 }
 //#endregion
-export { buildUserAgent };
+export { buildUserAgent, getRuntimeEnvironment };

package/dist/version.js

@@ -1,9 +1,14 @@
+import { version } from "./package.js";
 //#region src/version.ts
 /**
-* The current version of the Decart SDK.
-* Injected at build time from package.json.
-* Falls back to '0.0.0-dev' in development.
+* The current version of the Decart SDK, read from package.json.
+*
+* Read as a real module binding rather than a build-time `define` replacement:
+* `define` is rejected by the pinned tsdown/rolldown ("Invalid key: define"),
+* so a magic-token approach silently fell back to a placeholder and shipped the
+* wrong version in the User-Agent. The bundler tree-shakes this import down to
+* just the version string at build time.
 */
-const VERSION = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : "0.0.0-dev";
+const VERSION = version;
 //#endregion
 export { VERSION };

package/package.json

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

package/dist/realtime/browser/glass-to-glass-diagnostics.js

@@ -1,27 +0,0 @@
-import { SeqTracker, createMarkerReader, createStampPump } from "./glass-to-glass.js";
-//#region src/realtime/browser/glass-to-glass-diagnostics.ts
-function createBrowserGlassToGlassDiagnostics() {
-	const tracker = new SeqTracker();
-	const reader = createMarkerReader(tracker);
-	let pump;
-	return {
-		attachOutgoingStream: (stream, fps) => {
-			pump?.dispose();
-			pump = createStampPump(stream, {
-				tracker,
-				fps
-			});
-			return pump.stream;
-		},
-		attachRemoteVideoTrack: (track) => reader.attach(track),
-		markStart: () => tracker.markStart(performance.now()),
-		snapshot: () => tracker.snapshot(),
-		dispose: () => {
-			pump?.dispose();
-			pump = void 0;
-			reader.dispose();
-		}
-	};
-}
-//#endregion
-export { createBrowserGlassToGlassDiagnostics };