@decartai/sdk 0.2.1 → 0.2.3

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
@@ -269,6 +290,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/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";
@@ -17,6 +17,8 @@ import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientIni
 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, 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, 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

@@ -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";
@@ -17,6 +17,8 @@ import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientIni
 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, 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, 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.1";
+var version = "0.2.3";
 //#endregion
 export { version };

package/dist/realtime/client.d.ts

@@ -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";

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,

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/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.1",
+  "version": "0.2.3",
   "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",