@decartai/sdk 0.2.2 → 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
@@ -290,6 +315,38 @@ if (status.status === "completed") {
 }
 ```
 
+### Client Tokens
+
+Mint short-lived client tokens on your server instead of shipping your API key.
+The response also carries a signed JWT (`token`) that any server or edge runtime
+can verify **offline** against the platform's public JWKS — no API key, no
+round-trip to Decart:
+
+```ts
+import { createDecartClient, verifyClientToken, decodeClientToken } from "@decartai/sdk";
+
+const client = createDecartClient({ apiKey: process.env.DECART_API_KEY });
+const { apiKey, token } = await client.tokens.create({ expiresIn: 300, metadata: { service_tier: 0 } });
+
+// Verify offline (EdDSA signature, exp, iss, aud) and read the claims
+const claims = await verifyClientToken(token); // or client.tokens.verify(token)
+claims.serviceTier; // 0
+claims.pool; // "free" for tier 0, otherwise "paid"
+// also: userId, organizationId, apiKeyName, apiKeyId, allowedModels, allowedOrigins,
+// expiresAt, realtimeConcurrentSessionLimit, zeroDataRetention, attribution, raw
+
+// Read claims WITHOUT verifying — no network, no crypto. Untrusted: display/logging only.
+const untrusted = decodeClientToken(token);
+```
+
+The JWKS comes from `https://platform.decart.ai/api/auth/jwks` (the platform
+host, not `baseUrl`) and is cached; the JWT library is loaded lazily so bundles
+that never verify do not ship it. Errors: `TOKEN_INVALID`, `TOKEN_EXPIRED`,
+`TOKEN_VERIFY_ERROR` (JWKS unreachable). Options: `{ jwksUrl, issuer, audience,
+clockTolerance }`. This is an offline check, not an API call. It needs WebCrypto: on
+runtimes without it (React Native) `verify` rejects with `UNSUPPORTED_PLATFORM_FEATURE`;
+`decodeClientToken` works everywhere.
+
 ### React Native / Expo
 
 React Native realtime requires [LiveKit's React Native packages](https://github.com/livekit/client-sdk-react-native)

package/dist/create-client.js

@@ -175,7 +175,7 @@ const createDecartClientForPlatform = (createRealtime, options = {}) => {
 		*/
 		queue,
 		/**
-		* Client for creating client tokens.
+		* Client for creating, verifying and decoding client tokens.
 		* Client tokens are short-lived API keys safe for client-side use.
 		*
 		* @example
@@ -183,7 +183,11 @@ const createDecartClientForPlatform = (createRealtime, options = {}) => {
 		* // Server-side: Create a client token
 		* const serverClient = createDecartClient({ apiKey: process.env.DECART_API_KEY });
 		* const token = await serverClient.tokens.create();
-		* // Returns: { apiKey: "ek_...", expiresAt: "2024-12-15T12:10:00Z" }
+		* // Returns: { apiKey: "ek_...", token: "eyJ...", expiresAt: "2024-12-15T12:10:00Z" }
+		*
+		* // Server-side: Verify a client token offline (JWKS) and read its claims
+		* const claims = await serverClient.tokens.verify(token.token);
+		* console.log(claims.serviceTier, claims.pool, claims.organizationId);
 		*
 		* // Client-side: Use the client token
 		* const client = createDecartClient({ apiKey: token.apiKey });

package/dist/index.d.ts

@@ -11,12 +11,14 @@ 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";
 import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
 import { ModelState } from "./shared/types.js";
+import { ClientTokenClaims, decodeClientToken } from "./tokens/claims.js";
+import { VerifyClientTokenOptions, verifyClientToken } from "./tokens/verify.js";
 import { CreateTokenOptions, CreateTokenResponse, TokensClient } from "./tokens/client.js";
 import { DecartClientOptions } from "./create-client.js";
 
@@ -33,4 +35,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, 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 };
+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.js

@@ -1,4 +1,6 @@
 import { ERROR_CODES } from "./utils/errors.js";
+import { decodeClientToken } from "./tokens/claims.js";
+import { verifyClientToken } from "./tokens/verify.js";
 import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { createDecartClientForPlatform } from "./create-client.js";
 import { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
@@ -6,4 +8,4 @@ import { createBrowserRealtime } from "./realtime/browser/index.js";
 //#region src/index.ts
 const createDecartClient = (options = {}) => createDecartClientForPlatform(createBrowserRealtime, options);
 //#endregion
-export { ERROR_CODES, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { ERROR_CODES, createConsoleLogger, createDecartClient, decodeClientToken, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias, verifyClientToken };

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

@@ -11,12 +11,14 @@ 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";
 import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
 import { ModelState } from "./shared/types.js";
+import { ClientTokenClaims, decodeClientToken } from "./tokens/claims.js";
+import { VerifyClientTokenOptions, verifyClientToken } from "./tokens/verify.js";
 import { CreateTokenOptions, CreateTokenResponse, TokensClient } from "./tokens/client.js";
 import { DecartClientOptions } from "./create-client.js";
 
@@ -33,4 +35,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, 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 };
+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.js

@@ -1,4 +1,6 @@
 import { ERROR_CODES } from "./utils/errors.js";
+import { decodeClientToken } from "./tokens/claims.js";
+import { verifyClientToken } from "./tokens/verify.js";
 import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { createDecartClientForPlatform } from "./create-client.js";
 import { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias } from "./shared/model.js";
@@ -6,4 +8,4 @@ import { createReactNativeRealtime } from "./realtime/react-native/index.js";
 //#region src/index.react-native.ts
 const createDecartClient = (options = {}) => createDecartClientForPlatform(createReactNativeRealtime, options);
 //#endregion
-export { ERROR_CODES, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveFpsNumber, resolveModelAlias };
+export { ERROR_CODES, 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.2";
+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/dist/tokens/claims.d.ts

@@ -0,0 +1,44 @@
+import { Model } from "../shared/model.js";
+
+//#region src/tokens/claims.d.ts
+
+/**
+ * Client-token claims mapped to SDK names. Trusted when returned by `verifyClientToken` /
+ * `client.tokens.verify`; UNTRUSTED when returned by `decodeClientToken` / `client.tokens.decode`.
+ */
+type ClientTokenClaims = {
+  /** `metadata.service_tier` at mint time (`0` is the free tier); `null` when unset. */
+  serviceTier: number | null;
+  /** `"free"` when `serviceTier` is `0`, otherwise `"paid"`. */
+  pool: "free" | "paid";
+  /** `sub` — the owning user (the organization owner for org tokens). */
+  userId: string;
+  organizationId: string | null;
+  apiKeyName: string | null;
+  /** Parent permanent key id when present, else the ephemeral key's own id (`jti`). */
+  apiKeyId: string | null;
+  /** `null` = unrestricted. */
+  allowedModels: (Model | (string & {}))[] | null;
+  /** `null` = unrestricted. */
+  allowedOrigins: string[] | null;
+  /** ISO 8601, like `CreateTokenResponse.expiresAt`. */
+  expiresAt: string;
+  /** `null` when the owning key is exempt from the limit. */
+  realtimeConcurrentSessionLimit: number | null;
+  zeroDataRetention: boolean;
+  attribution: Record<string, string> | null;
+  /** The full JWT payload, for anything not mapped above. */
+  raw: Record<string, unknown>;
+};
+/** JOSE header prefix plus three segments; opaque `ek_*` / `dct_*` keys never match. */
+
+/**
+ * Read a client token's claims WITHOUT verifying it — no network, no crypto, so it works everywhere
+ * including React Native. The result is UNTRUSTED: use it for display or logging, never for
+ * authorization (use `verifyClientToken` / `client.tokens.verify` for that).
+ *
+ * @throws `TOKEN_INVALID` when the string is not a JWT or the payload is malformed.
+ */
+declare function decodeClientToken(token: string): ClientTokenClaims;
+//#endregion
+export { ClientTokenClaims, decodeClientToken };

package/dist/tokens/claims.js

@@ -0,0 +1,53 @@
+import { ERROR_CODES, createSDKError } from "../utils/errors.js";
+//#region src/tokens/claims.ts
+/** JOSE header prefix plus three segments; opaque `ek_*` / `dct_*` keys never match. */
+const isClientTokenJwt = (credential) => typeof credential === "string" && credential.startsWith("eyJ") && credential.split(".").length === 3;
+const invalid = (message, data) => createSDKError(ERROR_CODES.TOKEN_INVALID, `Invalid client token: ${message}`, data);
+/** An integer (not a boolean) or an integer string, else `null`. */
+const parseServiceTier = (raw) => typeof raw === "number" && Number.isInteger(raw) ? raw : typeof raw === "string" && /^\s*[+-]?\d+\s*$/.test(raw) ? Number.parseInt(raw, 10) : null;
+const str = (value) => typeof value === "string" ? value : null;
+const strArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string") ? value : null;
+/** Map a raw JWT payload to {@link ClientTokenClaims}. Requires `sub` and `exp`. */
+function mapClientTokenClaims(raw) {
+	if (typeof raw.sub !== "string" || !raw.sub) throw invalid("missing `sub` claim", { claim: "sub" });
+	if (typeof raw.exp !== "number") throw invalid("missing `exp` claim", { claim: "exp" });
+	const serviceTier = parseServiceTier(raw.service_tier) ?? (raw.priority ? 3 : null);
+	const attribution = raw.attribution;
+	return {
+		serviceTier,
+		pool: serviceTier === 0 ? "free" : "paid",
+		userId: raw.sub,
+		organizationId: str(raw.organizationId),
+		apiKeyName: str(raw.api_key_name),
+		apiKeyId: str(raw.parent_api_key_id) ?? str(raw.jti),
+		allowedModels: strArray(raw.models),
+		allowedOrigins: strArray(raw.origins),
+		expiresAt: (/* @__PURE__ */ new Date(raw.exp * 1e3)).toISOString(),
+		realtimeConcurrentSessionLimit: typeof raw.realtimeConcurrentSessionLimit === "number" ? raw.realtimeConcurrentSessionLimit : null,
+		zeroDataRetention: raw.zeroDataRetention === true,
+		attribution: typeof attribution === "object" && attribution !== null && !Array.isArray(attribution) ? attribution : null,
+		raw
+	};
+}
+/**
+* Read a client token's claims WITHOUT verifying it — no network, no crypto, so it works everywhere
+* including React Native. The result is UNTRUSTED: use it for display or logging, never for
+* authorization (use `verifyClientToken` / `client.tokens.verify` for that).
+*
+* @throws `TOKEN_INVALID` when the string is not a JWT or the payload is malformed.
+*/
+function decodeClientToken(token) {
+	if (!isClientTokenJwt(token)) throw invalid("not a JWT", { reason: "malformed" });
+	let payload;
+	try {
+		const base64 = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
+		const utf8 = atob(base64).replace(/[\s\S]/g, (c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+		payload = JSON.parse(decodeURIComponent(utf8));
+	} catch {
+		throw invalid("payload is not base64url JSON", { reason: "malformed" });
+	}
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) throw invalid("payload is not a JSON object", { reason: "malformed" });
+	return mapClientTokenClaims(payload);
+}
+//#endregion
+export { decodeClientToken, isClientTokenJwt, mapClientTokenClaims };

package/dist/tokens/client.d.ts

@@ -1,4 +1,6 @@
 import { Model } from "../shared/model.js";
+import { ClientTokenClaims } from "./claims.js";
+import { VerifyClientTokenOptions } from "./verify.js";
 
 //#region src/tokens/client.d.ts
 
@@ -25,7 +27,7 @@ type CreateTokenOptions = {
 };
 type CreateTokenResponse = {
   apiKey: string;
-  /** Signed JWT mirroring `apiKey`, verifiable offline via the public JWKS. */
+  /** Signed JWT mirroring `apiKey`, verifiable offline via `client.tokens.verify` / `verifyClientToken`. */
   token?: string;
   expiresAt: string;
   /** Present when `allowedModels` and/or `allowedOrigins` were set on the request. */
@@ -65,6 +67,17 @@ type TokensClient = {
    * ```
    */
   create: (options?: CreateTokenOptions) => Promise<CreateTokenResponse>;
+  /**
+   * Verify a client token's JWT OFFLINE against the platform's public JWKS (cached) and return its
+   * claims — signature (EdDSA), `exp`, `iss`, `aud`. Same as the standalone `verifyClientToken`;
+   * does not use the client's API key or `baseUrl`.
+   */
+  verify: (token: string, options?: VerifyClientTokenOptions) => Promise<ClientTokenClaims>;
+  /**
+   * Read a client token's claims WITHOUT verifying — no network, no crypto. UNTRUSTED: display or
+   * logging only. Same as the standalone `decodeClientToken`.
+   */
+  decode: (token: string) => ClientTokenClaims;
 };
 //#endregion
 export { CreateTokenOptions, CreateTokenResponse, TokensClient };

package/dist/tokens/client.js

@@ -1,5 +1,7 @@
 import { createSDKError } from "../utils/errors.js";
 import { buildAuthHeaders } from "../shared/request.js";
+import { decodeClientToken } from "./claims.js";
+import { verifyClientToken } from "./verify.js";
 //#region src/tokens/client.ts
 const createTokensClient = (opts) => {
 	const { baseUrl, apiKey, integration } = opts;
@@ -22,7 +24,11 @@ const createTokensClient = (opts) => {
 		}
 		return response.json();
 	};
-	return { create };
+	return {
+		create,
+		verify: verifyClientToken,
+		decode: decodeClientToken
+	};
 };
 //#endregion
 export { createTokensClient };

package/dist/tokens/verify.d.ts

@@ -0,0 +1,26 @@
+import { ClientTokenClaims } from "./claims.js";
+
+//#region src/tokens/verify.d.ts
+type VerifyClientTokenOptions = {
+  /** Default `https://platform.decart.ai/api/auth/jwks`. */
+  jwksUrl?: string;
+  /** Expected `iss`. Default `https://platform.decart.ai`. */
+  issuer?: string;
+  /** Expected `aud`. Default `https://platform.decart.ai`. */
+  audience?: string;
+  /** Allowed clock skew in seconds for `exp`. Default 60. */
+  clockTolerance?: number;
+};
+/**
+ * Verify a Decart client token OFFLINE and return its claims: EdDSA signature against the
+ * platform's public JWKS (fetched once and cached), plus `exp` (with clock tolerance), `iss` and
+ * `aud`. This is a local JWKS check, not an API call, and it needs no API key. Requires WebCrypto and `fetch` (Node 20+, Bun, Deno, browsers, Workers, Edge).
+ *
+ * @throws `TOKEN_INVALID` bad signature, wrong `iss`/`aud`, malformed token or unknown `kid`
+ * @throws `TOKEN_EXPIRED` `exp` is in the past
+ * @throws `TOKEN_VERIFY_ERROR` the JWKS could not be fetched — the token itself was not judged
+ * @throws `UNSUPPORTED_PLATFORM_FEATURE` the runtime has no WebCrypto (e.g. React Native)
+ */
+declare function verifyClientToken(token: string, options?: VerifyClientTokenOptions): Promise<ClientTokenClaims>;
+//#endregion
+export { VerifyClientTokenOptions, verifyClientToken };

package/dist/tokens/verify.js

@@ -0,0 +1,53 @@
+import { ERROR_CODES, createSDKError } from "../utils/errors.js";
+import { isClientTokenJwt, mapClientTokenClaims } from "./claims.js";
+//#region src/tokens/verify.ts
+const PLATFORM_URL = "https://platform.decart.ai";
+let jose;
+const jwkSets = /* @__PURE__ */ new Map();
+/**
+* Verify a Decart client token OFFLINE and return its claims: EdDSA signature against the
+* platform's public JWKS (fetched once and cached), plus `exp` (with clock tolerance), `iss` and
+* `aud`. This is a local JWKS check, not an API call, and it needs no API key. Requires WebCrypto and `fetch` (Node 20+, Bun, Deno, browsers, Workers, Edge).
+*
+* @throws `TOKEN_INVALID` bad signature, wrong `iss`/`aud`, malformed token or unknown `kid`
+* @throws `TOKEN_EXPIRED` `exp` is in the past
+* @throws `TOKEN_VERIFY_ERROR` the JWKS could not be fetched — the token itself was not judged
+* @throws `UNSUPPORTED_PLATFORM_FEATURE` the runtime has no WebCrypto (e.g. React Native)
+*/
+async function verifyClientToken(token, options = {}) {
+	if (!isClientTokenJwt(token)) throw createSDKError(ERROR_CODES.TOKEN_INVALID, "Invalid client token: not a JWT", { reason: "malformed" });
+	if (!globalThis.crypto?.subtle) throw createSDKError(ERROR_CODES.UNSUPPORTED_PLATFORM_FEATURE, "verifyClientToken needs WebCrypto (crypto.subtle), which this runtime does not provide. Verify client tokens on your server; decodeClientToken works everywhere.", { feature: "verifyClientToken" });
+	const jwksUrl = options.jwksUrl ?? `${PLATFORM_URL}/api/auth/jwks`;
+	if (!jose) jose = import("jose");
+	const { jwtVerify, createRemoteJWKSet, errors } = await jose;
+	let jwkSet = jwkSets.get(jwksUrl);
+	if (!jwkSet) {
+		jwkSet = createRemoteJWKSet(new URL(jwksUrl), { cooldownDuration: 6e4 });
+		jwkSets.set(jwksUrl, jwkSet);
+	}
+	try {
+		const { payload } = await jwtVerify(token, jwkSet, {
+			algorithms: ["EdDSA"],
+			issuer: options.issuer ?? PLATFORM_URL,
+			audience: options.audience ?? PLATFORM_URL,
+			clockTolerance: options.clockTolerance ?? 60,
+			requiredClaims: ["exp", "sub"]
+		});
+		return mapClientTokenClaims(payload);
+	} catch (error) {
+		const cause = error instanceof Error ? error : void 0;
+		const { code = "unknown", claim } = cause ?? {};
+		const data = {
+			reason: code,
+			...claim ? { claim } : {}
+		};
+		if (error instanceof errors.JWTExpired) throw createSDKError(ERROR_CODES.TOKEN_EXPIRED, `Client token expired: ${cause?.message}`, data, cause);
+		if (!(!(error instanceof errors.JOSEError) || /^ERR_(JOSE_GENERIC|JWKS_INVALID|JWKS_TIMEOUT)$/.test(code))) throw createSDKError(ERROR_CODES.TOKEN_INVALID, `Invalid client token: ${cause?.message}`, data, cause);
+		throw createSDKError(ERROR_CODES.TOKEN_VERIFY_ERROR, `Could not load the client-token JWKS from ${jwksUrl}: ${cause?.message ?? String(error)}`, {
+			...data,
+			jwksUrl
+		}, cause);
+	}
+}
+//#endregion
+export { verifyClientToken };

package/dist/utils/errors.d.ts

@@ -17,6 +17,12 @@ declare const ERROR_CODES: {
   readonly QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR";
   readonly JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED";
   readonly TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR";
+  /** Client-token verification: the token is not a valid, correctly signed Decart client token. */
+  readonly TOKEN_INVALID: "TOKEN_INVALID";
+  /** Client-token verification: signature is fine but `exp` is in the past (beyond clock tolerance). */
+  readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+  /** Client-token verification could not run, e.g. the JWKS could not be fetched. Says nothing about the token. */
+  readonly TOKEN_VERIFY_ERROR: "TOKEN_VERIFY_ERROR";
   readonly FILES_UPLOAD_ERROR: "FILES_UPLOAD_ERROR";
   readonly FILES_GET_ERROR: "FILES_GET_ERROR";
   readonly FILES_DELETE_ERROR: "FILES_DELETE_ERROR";

package/dist/utils/errors.js

@@ -11,6 +11,12 @@ const ERROR_CODES = {
 	QUEUE_RESULT_ERROR: "QUEUE_RESULT_ERROR",
 	JOB_NOT_COMPLETED: "JOB_NOT_COMPLETED",
 	TOKEN_CREATE_ERROR: "TOKEN_CREATE_ERROR",
+	/** Client-token verification: the token is not a valid, correctly signed Decart client token. */
+	TOKEN_INVALID: "TOKEN_INVALID",
+	/** Client-token verification: signature is fine but `exp` is in the past (beyond clock tolerance). */
+	TOKEN_EXPIRED: "TOKEN_EXPIRED",
+	/** Client-token verification could not run, e.g. the JWKS could not be fetched. Says nothing about the token. */
+	TOKEN_VERIFY_ERROR: "TOKEN_VERIFY_ERROR",
 	FILES_UPLOAD_ERROR: "FILES_UPLOAD_ERROR",
 	FILES_GET_ERROR: "FILES_GET_ERROR",
 	FILES_DELETE_ERROR: "FILES_DELETE_ERROR",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
+    "jose": "^6.2.2",
     "livekit-client": "~2.20.1",
     "mitt": "^3.0.1",
     "p-retry": "^6.2.1",