@decartai/sdk 0.2.3 → 0.2.4

package/README.md

@@ -103,6 +103,31 @@ 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.
 
+#### Connect retries and refused sessions
+
+A failed connect is re-dialled up to 5 times with exponential backoff (1 s to 10 s) before
+`connect()` rejects. Two refusals are never retried, because the server would give the same answer:
+a policy close (code 1008) and the API key's concurrent-session limit (close 1013 "Session Limit
+Reached"). The session limit rejects `connect()` on the first attempt with the server's message
+(`Concurrent session limit reached.`); if it lands after the session is established, the session ends
+with a `sessionEnded` event whose `reason` is `"session_limit"`. A capacity refusal (1013 "Try Again
+Later") is transient and still retries.
+
+Apps that hand out connects from their own session queue should turn retries off: every retry is a
+fresh dial that takes a freed slot ahead of the people waiting in line.
+
+```ts
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  retries: 0, // dial once; on failure, rejoin your own queue
+  // ...
+});
+
+realtimeClient.on("sessionEnded", ({ reason }) => {
+  // "session_limit" | "policy_violation" | "moderation_violation" | "insufficient_credits" | ...
+});
+```
+
 ### Watch a Stream
 
 A connected realtime session exposes an SDK `subscribeToken` once it reaches a

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, SessionEnded } from "./realtime/types.js";
+import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage, SessionEndReason, 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";
@@ -35,4 +35,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ClientTokenClaims, 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, VerifyClientTokenOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, decodeClientToken, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, verifyClientToken };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ClientTokenClaims, 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, SessionEndReason, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VerifyClientTokenOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, decodeClientToken, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, verifyClientToken };

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, SessionEnded } from "./realtime/types.js";
+import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage, SessionEndReason, 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";
@@ -35,4 +35,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   files: FilesClient;
 };
 //#endregion
-export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ClientTokenClaims, 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, VerifyClientTokenOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, decodeClientToken, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, verifyClientToken };
+export { CanonicalModel, CheckConnectivityOptions, ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, ClientTokenClaims, 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, SessionEndReason, SessionEnded, SetInput, SubscribeEvents, SubscribeOptions, TokensClient, UploadFileOptions, VerifyClientTokenOptions, VideoModelDefinition, VideoModels, VideoStallEvent, WebRTCStats, createConsoleLogger, createDecartClient, decodeClientToken, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, verifyClientToken };

package/dist/package.js

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

package/dist/realtime/client.d.ts

@@ -61,6 +61,7 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
   speed: z.ZodOptional<z.ZodEnum<{
     fast: "fast";
   }>>;
+  retries: z.ZodOptional<z.ZodNumber>;
   preferredVideoCodec: z.ZodOptional<z.ZodEnum<{
     h264: "h264";
     vp8: "vp8";

package/dist/realtime/client.js

@@ -28,6 +28,15 @@ const realTimeClientConnectOptionsSchema = z.object({
 	* model does not list it in `supportedSpeeds`). Omit it (the default) for standard mode.
 	*/
 	speed: realtimeSpeedSchema.optional(),
+	/**
+	* How many times a failed connect is re-dialled before `connect()` rejects (default 5, exponential
+	* backoff from 1 s to 10 s). `0` dials exactly once. Apps that hand out connects from their own session
+	* queue should pass `0`: every retry is a fresh dial that competes with the people waiting in line.
+	* Refusals the server will not change its mind about (policy close 1008, concurrent-session limit
+	* 1013 "Session Limit Reached") are never retried regardless. Does not affect the automatic
+	* reconnect after an established session drops.
+	*/
+	retries: z.number().int().min(0).optional(),
 	/** Local track publish codec. Desktop Safari is always pinned to vp8 and ignores this value. */
 	preferredVideoCodec: z.enum([
 		"h264",
@@ -47,7 +56,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, speed, preferredVideoCodec } = parsedOptions.data;
+		const { onRemoteStream, onConnectionChange, onConnectionQuality, onQueuePosition, initialState, resolution, speed, retries, preferredVideoCodec } = parsedOptions.data;
 		const mirror = parsedOptions.data.mirror ?? false;
 		let session;
 		let observability;
@@ -104,6 +113,7 @@ const createRealTimeClient = (opts) => {
 				initialImageRef,
 				initialPrompt,
 				initialPassthrough: initialState?.passthrough,
+				connectRetries: retries,
 				logger,
 				videoCodec: preparedConnection.videoCodec,
 				createMediaChannel: preparedConnection.createMediaChannel

package/dist/realtime/config-realtime.js

@@ -33,6 +33,18 @@ const REALTIME_CONFIG = {
 		terminalEndReasons: ["moderation_violation", "insufficient_credits"],
 		/** Close code for a policy termination. */
 		terminalCloseCode: 1008,
+		/**
+		* The bouncer's concurrent-session refusal: an `error` message carrying
+		* `errorText`, then close `closeCode` with `closeReason`. Retrying it only
+		* takes a slot from whoever is next in line. 1013 with any other reason
+		* ("Try Again Later": upstream at capacity) is transient and still retries.
+		* Matched case-insensitively.
+		*/
+		sessionLimit: {
+			closeCode: 1013,
+			closeReason: "session limit reached",
+			errorText: "concurrent session limit reached"
+		},
 		permanentErrorSubstrings: [
 			"permission denied",
 			"not allowed",

package/dist/realtime/stream-session.js

@@ -7,18 +7,36 @@ import pRetry, { AbortError } from "p-retry";
 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. */
+const POLICY_VIOLATION = "policy_violation";
+const SESSION_LIMIT = "session_limit";
+function isSessionLimitClose(code, reason) {
+	const { closeCode, closeReason } = REALTIME_CONFIG.session.sessionLimit;
+	return code === closeCode && typeof reason === "string" && reason.toLowerCase().includes(closeReason);
+}
+/**
+* The 1008 reason is only sent once generation has started; earlier kills carry just
+* the code. 1013 is terminal only with the session-limit reason: its other reason,
+* "Try Again Later", is a transient capacity refusal.
+*/
 function terminalReasonFromClose(cause) {
-	return cause.code === REALTIME_CONFIG.session.terminalCloseCode ? "policy_violation" : null;
+	if (cause.code === REALTIME_CONFIG.session.terminalCloseCode) return POLICY_VIOLATION;
+	if (isSessionLimitClose(cause.code, cause.reason)) return SESSION_LIMIT;
+	return null;
 }
 /**
 * SignalingChannel only emits `closed` after the handshake, so a close during the
-* join reaches us as connect-failure text rather than an event.
+* join reaches us as connect-failure text rather than an event. The session-limit
+* refusal is preceded by an `error` message, which is usually what rejects the join;
+* the 1013 close lands a tick later, so both texts are recognised.
 */
 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;
+	const message = error.message.toLowerCase();
+	const { terminalCloseCode, sessionLimit } = REALTIME_CONFIG.session;
+	if (message.includes(`websocket closed: ${terminalCloseCode}`)) return POLICY_VIOLATION;
+	if (message.includes(`websocket closed: ${sessionLimit.closeCode} ${sessionLimit.closeReason}`)) return SESSION_LIMIT;
+	if (message.includes(sessionLimit.errorText)) return SESSION_LIMIT;
+	return null;
 }
 function encodeSubscribeToken(roomName, options = {}) {
 	return btoa(JSON.stringify({
@@ -82,12 +100,12 @@ var StreamSession = class {
 		this.setState("connecting");
 		this.logger.info("realtime connect: starting", { attemptCycle: attempt });
 		try {
-			await pRetry(() => this.runOneConnect(attempt), this.retryOptionsFor(attempt));
+			await pRetry(() => this.runOneConnect(attempt), this.retryOptionsFor(attempt, this.config.connectRetries));
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			const terminal = this.terminalEndReason ?? terminalReasonFromError(error);
-			if (terminal && !this.disposed) {
-				this.finishTerminally(terminal, {
+			if (terminal) {
+				if (!this.disposed) this.finishTerminally(terminal, {
 					source: "connect",
 					error: message
 				});
@@ -134,9 +152,10 @@ var StreamSession = class {
 	assertConnected() {
 		if (!this.isConnected()) throw new Error(`Cannot send message: connection is ${this.state}`);
 	}
-	retryOptionsFor(attempt) {
+	retryOptionsFor(attempt, retries = REALTIME_CONFIG.session.retry.retries) {
 		return {
 			...REALTIME_CONFIG.session.retry,
+			retries,
 			onFailedAttempt: (_error) => {
 				this.tearDown();
 			},
@@ -287,9 +306,9 @@ var StreamSession = class {
 	*/
 	finishTerminally(reason, cause) {
 		this.logger.warn("realtime session ended by the server; not reconnecting", {
+			...cause,
 			reason,
-			state: this.state,
-			...cause
+			state: this.state
 		});
 		this.terminalEndReason = reason;
 		this.disposed = true;

package/dist/realtime/types.d.ts

@@ -20,9 +20,18 @@ type GenerationEnded = {
   seconds: number;
   reason: string;
 };
+/**
+ * Why the server ended a session on purpose. Terminal `generation_ended` reasons
+ * (`moderation_violation`, `insufficient_credits`) pass through as sent; the SDK
+ * derives the rest from the close:
+ * - `policy_violation`: close 1008 before a reason was sent.
+ * - `session_limit`: the API key's concurrent-session limit was reached (close 1013
+ *   "Session Limit Reached"). Rejoin your own queue instead of dialling again.
+ */
+type SessionEndReason = "moderation_violation" | "insufficient_credits" | "policy_violation" | "session_limit" | (string & {});
 /** The server ended the session on purpose; the SDK will not reconnect. */
 type SessionEnded = {
-  reason: string;
+  reason: SessionEndReason;
 };
 type ImageSetOptions = {
   prompt?: string | null;
@@ -30,4 +39,4 @@ type ImageSetOptions = {
   timeout?: number;
 };
 //#endregion
-export { ConnectionState, GenerationEnded, GenerationEndedMessage, GenerationTick, ImageSetOptions, QueuePosition, QueuePositionMessage, SessionEnded };
+export { ConnectionState, GenerationEnded, GenerationEndedMessage, GenerationTick, ImageSetOptions, QueuePosition, QueuePositionMessage, SessionEndReason, SessionEnded };

package/package.json

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