@decartai/sdk 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -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, 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

@@ -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, 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.1";
 //#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";
 
@@ -78,6 +78,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

@@ -112,6 +112,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/package.json

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