@decartai/sdk 0.2.0 → 0.2.2

package/README.md

@@ -82,6 +82,27 @@ Options:
 - `"auto"` — mirror when the input track reports `facingMode: "user"` (mobile front cameras).
 - `true` — always mirror (e.g. desktop webcams).
 
+#### Fast mode
+
+Fast mode (`speed: "fast"`) serves the session from a higher-compute tier for lower latency and higher throughput; output quality is unchanged. It is currently available for `lucy-2.5` / `lucy-latest` and `lucy-vton-3.5` / `lucy-vton-latest`, in the US region only, and is billed at 2x the standard realtime rate for those models. Other models ignore the option. Omit it (the default) for standard mode.
+
+```ts
+const realtimeClient = await client.realtime.connect(stream, {
+  model: models.realtime("lucy-2.5"),
+  speed: "fast",
+  // ...
+});
+```
+
+Models that offer fast mode list it in their definition's `supportedSpeeds`:
+
+```ts
+models.realtime("lucy-2.5").supportedSpeeds; // ["fast"]
+models.realtime("lucy-2.1").supportedSpeeds; // undefined
+```
+
+Passing `speed` for a model without the capability logs a warning through the client's logger and the session runs at standard speed.
+
 ### Watch a Stream
 
 A connected realtime session exposes an SDK `subscribeToken` once it reaches a

package/dist/files/types.d.ts

@@ -12,6 +12,7 @@ import { ReactNativeFile } from "../process/types.js";
 interface FileReference {
   id: string;
   filename: string | null;
+  /** Type of the stored file. The API re-encodes non-JPEG images to JPEG, so a PNG upload reports `image/jpeg`. */
   mime_type: string;
   size_bytes: number;
   /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
+import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
 import { FileReference, FileUploadInput } from "./files/types.js";
 import { FilesClient, UploadFileOptions } from "./files/client.js";
@@ -11,7 +11,7 @@ import { G2GMetrics } from "./realtime/observability/g2g.js";
 import { WebRTCStats } from "./realtime/observability/webrtc-stats.js";
 import { ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport } from "./realtime/observability/connection-quality.js";
 import { ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ReconnectEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
-import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage } from "./realtime/types.js";
+import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage, SessionEnded } from "./realtime/types.js";
 import { SetInput } from "./realtime/methods.js";
 import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, RealtimeMediaStream } from "./realtime/client.js";
 import { CheckConnectivityOptions, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport } from "./realtime/preflight-types.js";
@@ -33,4 +33,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, ReconnectEvent, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, RealtimeSpeed, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };

package/dist/index.react-native.d.ts

@@ -1,4 +1,4 @@
-import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
+import { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
 import { FileInput, ProcessOptions, ReactNativeFile } from "./process/types.js";
 import { FileReference, FileUploadInput } from "./files/types.js";
 import { FilesClient, UploadFileOptions } from "./files/client.js";
@@ -11,7 +11,7 @@ import { G2GMetrics } from "./realtime/observability/g2g.js";
 import { WebRTCStats } from "./realtime/observability/webrtc-stats.js";
 import { ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport } from "./realtime/observability/connection-quality.js";
 import { ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ReconnectEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
-import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage } from "./realtime/types.js";
+import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage, SessionEnded } from "./realtime/types.js";
 import { SetInput } from "./realtime/methods.js";
 import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, RealtimeMediaStream } from "./realtime/client.js";
 import { CheckConnectivityOptions, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport } from "./realtime/preflight-types.js";
@@ -33,4 +33,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, ReconnectEvent, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ConnectionQuality, ConnectionQualityLimitingFactor, ConnectionQualityMetrics, ConnectionQualityReport, ConnectionState, ConnectivityMetrics, ConnectivityReport, ConnectivityTransport, CreateTokenOptions, CreateTokenResponse, CustomModelDefinition, type DecartClientOptions, DecartSDKError, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ERROR_CODES, FileInput, FileReference, FileUploadInput, FilesClient, G2GMetrics, GenerationEndedMessage, ImageModelDefinition, ImageModels, JobStatus, JobStatusResponse, JobSubmitResponse, ListedModelDefinition, LogLevel, Logger, Model, ModelDefinition, ModelFps, ModelKind, ModelState, ProcessClient, ProcessOptions, QueueClient, QueueJobResult, QueuePosition, QueuePositionMessage, QueueSubmitAndPollOptions, QueueSubmitOptions, ReactNativeFile, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState, Events as RealTimeEvents, RealTimeModels, RealTimeSubscribeClient, RealtimeMediaStream, RealtimeSpeed, ReconnectEvent, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.2.0";
+var version = "0.2.2";
 //#endregion
 export { version };

package/dist/realtime/client.d.ts

@@ -3,7 +3,7 @@ import { DecartSDKError } from "../utils/errors.js";
 import { WebRTCStats } from "./observability/webrtc-stats.js";
 import { ConnectionQualityReport } from "./observability/connection-quality.js";
 import { DiagnosticEvent } from "./observability/diagnostics.js";
-import { ConnectionState, GenerationEnded, GenerationTick, ImageSetOptions, QueuePosition } from "./types.js";
+import { ConnectionState, GenerationEnded, GenerationTick, ImageSetOptions, QueuePosition, SessionEnded } from "./types.js";
 import { SetInput } from "./methods.js";
 import { z } from "zod";
 
@@ -36,6 +36,9 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     width: z.ZodNumber;
     height: z.ZodNumber;
     inputSchema: z.ZodOptional<z.ZodAny>;
+    supportedSpeeds: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+      fast: "fast";
+    }>>>>;
   }, z.core.$strip>;
   onRemoteStream: z.ZodCustom<OnRemoteStreamFn, OnRemoteStreamFn>;
   onConnectionChange: z.ZodOptional<z.ZodCustom<OnConnectionChangeFn, OnConnectionChangeFn>>;
@@ -55,6 +58,9 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     "720p": "720p";
     "1080p": "1080p";
   }>>;
+  speed: z.ZodOptional<z.ZodEnum<{
+    fast: "fast";
+  }>>;
   preferredVideoCodec: z.ZodOptional<z.ZodEnum<{
     h264: "h264";
     vp8: "vp8";
@@ -78,6 +84,8 @@ type Events = {
   error: DecartSDKError;
   generationTick: GenerationTick;
   generationEnded: GenerationEnded;
+  /** Terminal: the server ended the session and no reconnect is coming. */
+  sessionEnded: SessionEnded;
   diagnostic: DiagnosticEvent;
   stats: WebRTCStats;
 };

package/dist/realtime/client.js

@@ -1,7 +1,7 @@
 import { classifyWebrtcError } from "../utils/errors.js";
 import { createConsoleLogger } from "../utils/logger.js";
 import { isFileRefId } from "../files/types.js";
-import { modelDefinitionSchema, resolveFpsNumber } from "../shared/model.js";
+import { modelDefinitionSchema, realtimeSpeedSchema, resolveFpsNumber } from "../shared/model.js";
 import { modelStateSchema } from "../shared/types.js";
 import { imageToBase64 } from "../utils/media.js";
 import { createEventBuffer } from "./event-buffer.js";
@@ -20,6 +20,14 @@ const realTimeClientConnectOptionsSchema = z.object({
 	queryParams: z.record(z.string(), z.string()).optional(),
 	mirror: z.union([z.literal("auto"), z.boolean()]).optional(),
 	resolution: z.enum(["720p", "1080p"]).optional(),
+	/**
+	* Realtime speed tier. Fast mode (`"fast"`) serves the session from a higher-compute tier for lower
+	* latency and higher throughput; output quality is unchanged. It is currently available for `lucy-2.5` /
+	* `lucy-latest` and `lucy-vton-3.5` / `lucy-vton-latest`, in the US region only, and is billed at 2x the
+	* standard realtime rate for those models. Other models ignore the option (the SDK logs a warning when the
+	* model does not list it in `supportedSpeeds`). Omit it (the default) for standard mode.
+	*/
+	speed: realtimeSpeedSchema.optional(),
 	/** Local track publish codec. Desktop Safari is always pinned to vp8 and ignores this value. */
 	preferredVideoCodec: z.enum([
 		"h264",
@@ -39,7 +47,7 @@ const createRealTimeClient = (opts) => {
 	const connect = async (stream, options) => {
 		const parsedOptions = realTimeClientConnectOptionsSchema.safeParse(options);
 		if (!parsedOptions.success) throw parsedOptions.error;
-		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, preferredVideoCodec } = parsedOptions.data;
+		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, speed, preferredVideoCodec } = parsedOptions.data;
 		const mirror = parsedOptions.data.mirror ?? false;
 		let session;
 		let observability;
@@ -74,13 +82,19 @@ const createRealTimeClient = (opts) => {
 				}
 			});
 			observability = preparedConnection.observability;
+			if (speed && !options.model.supportedSpeeds?.includes(speed)) logger.warn("realtime: model does not support the requested speed tier; the server serves it at standard speed", {
+				model: options.model.name,
+				speed,
+				supportedSpeeds: options.model.supportedSpeeds ?? []
+			});
 			session = new StreamSession({
 				url: `${url}?${new URLSearchParams({
 					...preparedConnection.queryParams ?? {},
 					...options.queryParams ?? {},
 					api_key: apiKey,
 					model: options.model.name,
-					...resolution ? { resolution } : {}
+					...resolution ? { resolution } : {},
+					...speed ? { speed } : {}
 				}).toString()}`,
 				integration,
 				observability,
@@ -112,6 +126,7 @@ const createRealTimeClient = (opts) => {
 			});
 			session.on("generationTick", (e) => emitOrBuffer("generationTick", e));
 			session.on("generationEnded", (e) => emitOrBuffer("generationEnded", e));
+			session.on("sessionEnded", (e) => emitOrBuffer("sessionEnded", e));
 			session.on("error", (error) => {
 				logger.error("Realtime error", { error: error.message });
 				emitOrBuffer("error", classifyWebrtcError(error));

package/dist/realtime/config-realtime.js

@@ -25,6 +25,14 @@ const REALTIME_CONFIG = {
 			minTimeout: 1e3,
 			maxTimeout: 1e4
 		},
+		/**
+		* `generation_ended` reasons the server will not change its mind about.
+		* The rest of its vocabulary (`error`, `disconnect`, `timeout`) is generic
+		* or overloaded, so those still retry.
+		*/
+		terminalEndReasons: ["moderation_violation", "insufficient_credits"],
+		/** Close code for a policy termination. */
+		terminalCloseCode: 1008,
 		permanentErrorSubstrings: [
 			"permission denied",
 			"not allowed",

package/dist/realtime/stream-session.js

@@ -4,6 +4,22 @@ import { SignalingChannel } from "./signaling-channel.js";
 import mitt from "mitt";
 import pRetry, { AbortError } from "p-retry";
 //#region src/realtime/stream-session.ts
+function isTerminalEndReason(reason) {
+	return reason !== void 0 && REALTIME_CONFIG.session.terminalEndReasons.includes(reason);
+}
+/** The reason is only sent once generation has started; earlier kills carry just the code. */
+function terminalReasonFromClose(cause) {
+	return cause.code === REALTIME_CONFIG.session.terminalCloseCode ? "policy_violation" : null;
+}
+/**
+* SignalingChannel only emits `closed` after the handshake, so a close during the
+* join reaches us as connect-failure text rather than an event.
+*/
+function terminalReasonFromError(error) {
+	if (!(error instanceof Error)) return null;
+	const marker = `websocket closed: ${REALTIME_CONFIG.session.terminalCloseCode}`;
+	return error.message.toLowerCase().includes(marker) ? "policy_violation" : null;
+}
 function encodeSubscribeToken(roomName, options = {}) {
 	return btoa(JSON.stringify({
 		room_name: roomName,
@@ -28,6 +44,13 @@ var StreamSession = class {
 	disposed = false;
 	currentAttempt = 0;
 	teardownGeneration = 0;
+	terminalEndReason = null;
+	/**
+	* Replayed as a reconnect's initial state. Callers usually connect first and
+	* send the image after, so without this the new session joins with nothing
+	* applied and never starts generating.
+	*/
+	appliedState = null;
 	logger;
 	constructor(config) {
 		this.config = config;
@@ -54,6 +77,7 @@ var StreamSession = class {
 	}
 	async connect() {
 		this.disposed = false;
+		this.terminalEndReason = null;
 		const attempt = ++this.currentAttempt;
 		this.setState("connecting");
 		this.logger.info("realtime connect: starting", { attemptCycle: attempt });
@@ -61,6 +85,14 @@ var StreamSession = class {
 			await pRetry(() => this.runOneConnect(attempt), this.retryOptionsFor(attempt));
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
+			const terminal = this.terminalEndReason ?? terminalReasonFromError(error);
+			if (terminal && !this.disposed) {
+				this.finishTerminally(terminal, {
+					source: "connect",
+					error: message
+				});
+				throw error;
+			}
 			this.logger.error("realtime connect: exhausted all retries", { error: message });
 			if (this.currentAttempt === attempt && !this.disposed) this.setState("disconnected");
 			throw error;
@@ -68,11 +100,25 @@ var StreamSession = class {
 	}
 	async sendPrompt(text, opts) {
 		this.assertConnected();
-		return this.signaling.sendPrompt(text, opts);
+		await this.signaling.sendPrompt(text, opts);
+		this.appliedState = {
+			...this.getInitialState(),
+			prompt: text,
+			enhance: opts?.enhance
+		};
 	}
 	async setImage(payload, opts) {
 		this.assertConnected();
-		return this.signaling.setImage(payload, opts);
+		await this.signaling.setImage(payload, opts);
+		this.appliedState = payload.kind === "ref" ? {
+			imageRef: payload.ref,
+			prompt: opts?.prompt ?? null,
+			enhance: opts?.enhance
+		} : {
+			image: payload.data,
+			prompt: opts?.prompt ?? null,
+			enhance: opts?.enhance
+		};
 	}
 	async replaceVideoTrack(track) {
 		this.assertConnected();
@@ -96,6 +142,12 @@ var StreamSession = class {
 			},
 			shouldRetry: (error) => {
 				if (this.disposed || this.currentAttempt !== attempt) return false;
+				const terminal = this.terminalEndReason ?? terminalReasonFromError(error);
+				if (terminal) {
+					this.terminalEndReason = terminal;
+					this.logger.error("realtime connect: session refused, not retrying", { reason: terminal });
+					return false;
+				}
 				const msg = error.message.toLowerCase();
 				const permanent = REALTIME_CONFIG.session.permanentErrorSubstrings.some((err) => msg.includes(err));
 				if (permanent) this.logger.error("realtime connect: permanent error, not retrying", { error: error.message });
@@ -158,6 +210,9 @@ var StreamSession = class {
 		});
 	}
 	getInitialState() {
+		return this.appliedState ?? this.configInitialState();
+	}
+	configInitialState() {
 		if (this.config.initialImageRef !== void 0) return {
 			imageRef: this.config.initialImageRef,
 			prompt: this.config.initialPrompt?.text,
@@ -183,12 +238,18 @@ var StreamSession = class {
 			this.markGenerating();
 			this.events.emit("generationTick", e);
 		});
-		this.signaling.on("generationEnded", (e) => this.events.emit("generationEnded", e));
+		this.signaling.on("generationEnded", (e) => {
+			if (isTerminalEndReason(e.reason)) this.terminalEndReason = e.reason;
+			this.events.emit("generationEnded", e);
+		});
 		this.signaling.on("serverError", (err) => this.events.emit("error", err));
-		this.signaling.on("closed", (info) => this.handleConnectionLoss({
-			source: "signaling",
-			...info
-		}));
+		this.signaling.on("closed", (info) => {
+			this.terminalEndReason ??= terminalReasonFromClose({ ...info });
+			this.handleConnectionLoss({
+				source: "signaling",
+				...info
+			});
+		});
 	}
 	markGenerating() {
 		if (this.state === "connected") this.setState("generating");
@@ -202,6 +263,11 @@ var StreamSession = class {
 	}
 	handleConnectionLoss(cause) {
 		if (this.disposed) return;
+		const terminalReason = this.terminalEndReason ?? terminalReasonFromClose(cause);
+		if (terminalReason) {
+			this.finishTerminally(terminalReason, cause);
+			return;
+		}
 		if (this.state !== "connected" && this.state !== "generating") {
 			this.logger.debug("connection loss ignored (not connected)", {
 				state: this.state,
@@ -215,6 +281,22 @@ var StreamSession = class {
 		});
 		this.scheduleReconnect();
 	}
+	/**
+	* The server ended this session on purpose: retrying would get the same answer
+	* and bill another session, and "reconnecting" would hide the reason.
+	*/
+	finishTerminally(reason, cause) {
+		this.logger.warn("realtime session ended by the server; not reconnecting", {
+			reason,
+			state: this.state,
+			...cause
+		});
+		this.terminalEndReason = reason;
+		this.disposed = true;
+		this.tearDown();
+		this.setState("disconnected");
+		this.events.emit("sessionEnded", { reason });
+	}
 	scheduleReconnect() {
 		const attempt = ++this.currentAttempt;
 		this.setState("reconnecting");
@@ -229,6 +311,14 @@ var StreamSession = class {
 		}).catch((error) => {
 			if (this.disposed || this.currentAttempt !== attempt) return;
 			const message = error instanceof Error ? error.message : String(error);
+			const terminal = this.terminalEndReason ?? terminalReasonFromError(error);
+			if (terminal) {
+				this.finishTerminally(terminal, {
+					source: "reconnect",
+					error: message
+				});
+				return;
+			}
 			this.logger.error("realtime reconnect: failed permanently", { error: message });
 			this.tearDown();
 			this.setState("disconnected");

package/dist/realtime/types.d.ts

@@ -20,10 +20,14 @@ type GenerationEnded = {
   seconds: number;
   reason: string;
 };
+/** The server ended the session on purpose; the SDK will not reconnect. */
+type SessionEnded = {
+  reason: string;
+};
 type ImageSetOptions = {
   prompt?: string | null;
   enhance?: boolean;
   timeout?: number;
 };
 //#endregion
-export { ConnectionState, GenerationEnded, GenerationEndedMessage, GenerationTick, ImageSetOptions, QueuePosition, QueuePositionMessage };
+export { ConnectionState, GenerationEnded, GenerationEndedMessage, GenerationTick, ImageSetOptions, QueuePosition, QueuePositionMessage, SessionEnded };

package/dist/shared/model.d.ts

@@ -289,6 +289,14 @@ type ModelFps = number | {
   ideal?: number;
   exact?: number;
 };
+/**
+ * Realtime speed tiers selectable with the `speed` connect option.
+ * `"fast"` is the only tier today; the standard tier has no value (omit the option).
+ */
+declare const realtimeSpeedSchema: z.ZodEnum<{
+  fast: "fast";
+}>;
+type RealtimeSpeed = z.infer<typeof realtimeSpeedSchema>;
 type ModelDefinition<T extends Model = Model> = {
   name: T;
   urlPath: string;
@@ -297,6 +305,11 @@ type ModelDefinition<T extends Model = Model> = {
   width: number;
   height: number;
   inputSchema: T extends keyof ModelInputSchemas ? ModelInputSchemas[T] : z.ZodTypeAny;
+  /**
+   * Realtime speed tiers this model can be served from via the `speed` connect option.
+   * Absent when the model only offers the standard tier (the server ignores `speed` for it).
+   */
+  supportedSpeeds?: readonly RealtimeSpeed[];
 };
 declare function resolveFpsNumber(fps: ModelFps, fallback?: number): number;
 /**
@@ -375,4 +388,4 @@ declare const models: {
   };
 };
 //#endregion
-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 };
+export { CanonicalModel, CustomModelDefinition, ImageModelDefinition, ImageModels, ListedModelDefinition, Model, ModelDefinition, ModelFps, ModelInputSchemas, ModelKind, RealTimeModels, RealtimeSpeed, VideoModelDefinition, VideoModels, canonicalModelSchema, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelInputSchemas, modelSchema, models, realtimeModels, realtimeSpeedSchema, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/dist/shared/model.js

@@ -185,6 +185,11 @@ const modelInputSchemas = {
 	"lucy-pro-i2i": imageEditSchema,
 	"lucy-restyle-v2v": restyleSchema
 };
+/**
+* Realtime speed tiers selectable with the `speed` connect option.
+* `"fast"` is the only tier today; the standard tier has no value (omit the option).
+*/
+const realtimeSpeedSchema = z.enum(["fast"]);
 function resolveFpsNumber(fps, fallback = 30) {
 	if (typeof fps === "number") return fps;
 	return fps.ideal ?? fps.max ?? fps.exact ?? fps.min ?? fallback;
@@ -201,7 +206,8 @@ const modelDefinitionSchema = z.object({
 	})]),
 	width: z.number().min(1),
 	height: z.number().min(1),
-	inputSchema: z.any().optional()
+	inputSchema: z.any().optional(),
+	supportedSpeeds: z.array(realtimeSpeedSchema).readonly().optional()
 });
 const _models = {
 	realtime: {
@@ -225,7 +231,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-vton-3.5": {
 			urlPath: "/v1/stream",
@@ -236,7 +243,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-restyle-2": {
 			urlPath: "/v1/stream",
@@ -258,7 +266,8 @@ const _models = {
 			},
 			width: 1088,
 			height: 624,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-vton-latest": {
 			urlPath: "/v1/stream",
@@ -269,7 +278,8 @@ const _models = {
 			},
 			width: 1280,
 			height: 720,
-			inputSchema: z.object({})
+			inputSchema: z.object({}),
+			supportedSpeeds: ["fast"]
 		},
 		"lucy-restyle-latest": {
 			urlPath: "/v1/stream",
@@ -483,4 +493,4 @@ const models = {
 	}
 };
 //#endregion
-export { canonicalImageModels, canonicalModelSchema, canonicalRealtimeModels, canonicalVideoModels, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, modelInputSchemas, modelSchema, models, realtimeModels, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };
+export { canonicalImageModels, canonicalModelSchema, canonicalRealtimeModels, canonicalVideoModels, imageModels, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, modelDefinitionSchema, modelInputSchemas, modelSchema, models, realtimeModels, realtimeSpeedSchema, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, videoModels };

package/package.json

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