@decartai/sdk 0.0.67 → 0.1.0

package/README.md

@@ -15,12 +15,15 @@ yarn add @decartai/sdk
 ## Documentation
 
 For complete documentation, guides, and examples, visit:
-**https://docs.platform.decart.ai/sdks/javascript**
+**[https://docs.platform.decart.ai/sdks/javascript](https://docs.platform.decart.ai/sdks/javascript)**
 
 ## Quick Start
 
 ### Real-time Video Transformation
 
+Realtime connections are LiveKit-backed in the SDK. Existing client usage stays the same: provide a
+camera `MediaStream`, choose a realtime model, and handle the transformed remote stream.
+
 ```typescript
 import { createDecartClient, models } from "@decartai/sdk";
 
@@ -79,6 +82,53 @@ Options:
 - `"auto"` — mirror when the input track reports `facingMode: "user"` (mobile front cameras).
 - `true` — always mirror (e.g. desktop webcams).
 
+### Watch a Stream
+
+A connected realtime session exposes an SDK `subscribeToken` once it reaches a
+connected state. Share that SDK token with viewers — `client.realtime.subscribe`
+uses it to request receive-only LiveKit credentials from Decart, then connects to
+the LiveKit room for the styled output stream. No viewer camera is required.
+
+**Producer** — capture the token from the active session:
+
+```typescript
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  onRemoteStream: (transformedStream) => {
+    videoElement.srcObject = transformedStream;
+  },
+});
+
+realtimeClient.on("connectionChange", (state) => {
+  if ((state === "connected" || state === "generating") && realtimeClient.subscribeToken) {
+    const subscribeToken = realtimeClient.subscribeToken;
+    // Pass `subscribeToken` to the viewer snippet below.
+  }
+});
+```
+
+**Viewer** — attach to the producer's stream with the token:
+
+```typescript
+import { createDecartClient, type RealTimeSubscribeClient } from "@decartai/sdk";
+
+const client = createDecartClient({ apiKey: "your-api-key-here" });
+
+const subscriber: RealTimeSubscribeClient = await client.realtime.subscribe({
+  token: subscribeToken,
+  onRemoteStream: (stream) => {
+    videoElement.srcObject = stream;
+  },
+});
+
+subscriber.on("connectionChange", (state) => {
+  console.log(`Viewer state: ${state}`);
+});
+
+// Disconnect when done
+subscriber.disconnect();
+```
+
 ### Async Processing (Queue API)
 
 For video generation jobs, use the queue API to submit jobs and poll for results:
@@ -151,12 +201,12 @@ pnpm install
 
 1. **Version bump**: Run `pnpm release` to bump the version (this uses `bumpp` to create a new version tag) and push it to GitHub
 2. **Automated publish**: The GitHub Actions workflow will:
-   - Build the project
-   - Publish to npm
-   - Create a GitHub release with changelog
+  - Build the project
+  - Publish to npm
+  - Create a GitHub release with changelog
 
 The package is published to npm as `@decartai/sdk`.
 
 ## License
 
-MIT
+MIT

package/dist/index.d.ts

@@ -5,12 +5,12 @@ import { ProcessClient } from "./process/client.js";
 import { JobStatus, JobStatusResponse, JobSubmitResponse, QueueJobResult, QueueSubmitAndPollOptions, QueueSubmitOptions } from "./queue/types.js";
 import { QueueClient } from "./queue/client.js";
 import { DecartSDKError, ERROR_CODES } from "./utils/errors.js";
-import { ConnectionPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, IceCandidateEvent, IceStateEvent, PeerConnectionStateEvent, PhaseTimingEvent, ReconnectEvent, SelectedCandidatePairEvent, SignalingStateEvent, VideoStallEvent } from "./realtime/diagnostics.js";
-import { ConnectionState } from "./realtime/types.js";
+import { ClientSessionConnectionBreakdownEvent, ClientSessionConnectionBreakdownPhase, DiagnosticEvent, DiagnosticEventName, DiagnosticEvents, ReconnectEvent, VideoStallEvent } from "./realtime/observability/diagnostics.js";
+import { WebRTCStats } from "./realtime/observability/webrtc-stats.js";
+import { ConnectionState, GenerationEndedMessage, QueuePosition, QueuePositionMessage } from "./realtime/types.js";
 import { SetInput } from "./realtime/methods.js";
-import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
-import { WebRTCStats } from "./realtime/webrtc-stats.js";
 import { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState } from "./realtime/client.js";
+import { RealTimeSubscribeClient, SubscribeEvents, SubscribeOptions } from "./realtime/subscribe-client.js";
 import { ModelState } from "./shared/types.js";
 import { CreateTokenOptions, CreateTokenResponse, TokensClient } from "./tokens/client.js";
 
@@ -42,6 +42,8 @@ type DecartClientOptions = {
  * @param options.realtimeBaseUrl - Override the default WebSocket base URL for realtime connections.
  * @param options.integration - Optional integration identifier.
  *
+ * Realtime media uses LiveKit only (inference must enable it in `TRANSPORTS_ENABLED`).
+ *
  * @example
  * ```ts
  * //  (direct API access)Option 1: Explicit API key
@@ -134,4 +136,4 @@ declare const createDecartClient: (options?: DecartClientOptions) => {
   tokens: TokensClient;
 };
 //#endregion
-export { type CanonicalModel, type ConnectionPhase, type ConnectionState, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type IceCandidateEvent, type IceStateEvent, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type PeerConnectionStateEvent, type PhaseTimingEvent, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SelectedCandidatePairEvent, type SetInput, type SignalingStateEvent, type SubscribeEvents, type SubscribeOptions, type TokensClient, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };
+export { type CanonicalModel, type ClientSessionConnectionBreakdownEvent, type ClientSessionConnectionBreakdownPhase, type ConnectionState, type CreateTokenOptions, type CreateTokenResponse, type CustomModelDefinition, DecartClientOptions, type DecartSDKError, type DiagnosticEvent, type DiagnosticEventName, type DiagnosticEvents, ERROR_CODES, type FileInput, type GenerationEndedMessage, type ImageModelDefinition, type ImageModels, type JobStatus, type JobStatusResponse, type JobSubmitResponse, type ListedModelDefinition, type LogLevel, type Logger, type Model, type ModelDefinition, type ModelKind, type ModelState, type ProcessClient, type ProcessOptions, type QueueClient, type QueueJobResult, type QueuePosition, type QueuePositionMessage, type QueueSubmitAndPollOptions, type QueueSubmitOptions, type ReactNativeFile, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, type Events as RealTimeEvents, type RealTimeModels, type RealTimeSubscribeClient, type ReconnectEvent, type SetInput, type SubscribeEvents, type SubscribeOptions, type TokensClient, type VideoModelDefinition, type VideoModels, type VideoStallEvent, type WebRTCStats, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };

package/dist/index.js

@@ -2,12 +2,12 @@ import { ERROR_CODES, createInvalidApiKeyError, createInvalidBaseUrlError } from
 import { createProcessClient } from "./process/client.js";
 import { createQueueClient } from "./queue/client.js";
 import { isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, resolveCanonicalModelAlias, resolveModelAlias } from "./shared/model.js";
+import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { createRealTimeClient } from "./realtime/client.js";
+import { createRealTimeSubscribeClient } from "./realtime/subscribe-client.js";
 import { createTokensClient } from "./tokens/client.js";
 import { readEnv } from "./utils/env.js";
-import { createConsoleLogger, noopLogger } from "./utils/logger.js";
 import { z } from "zod";
-
 //#region src/index.ts
 const proxySchema = z.union([z.string().url(), z.string().startsWith("/")]);
 const decartClientOptionsSchema = z.object({
@@ -31,6 +31,8 @@ const decartClientOptionsSchema = z.object({
 * @param options.realtimeBaseUrl - Override the default WebSocket base URL for realtime connections.
 * @param options.integration - Optional integration identifier.
 *
+* Realtime media uses LiveKit only (inference must enable it in `TRANSPORTS_ENABLED`).
+*
 * @example
 * ```ts
 * //  (direct API access)Option 1: Explicit API key
@@ -59,33 +61,46 @@ const createDecartClient = (options = {}) => {
 	if (isProxyMode && "proxy" in parsedOptions.data && parsedOptions.data.proxy) baseUrl = parsedOptions.data.proxy;
 	else baseUrl = parsedOptions.data.baseUrl || "https://api.decart.ai";
 	const { integration } = parsedOptions.data;
-	const logger = "logger" in options && options.logger ? options.logger : noopLogger;
-	const telemetryEnabled = "telemetry" in options && options.telemetry === false ? false : true;
+	const logger = "logger" in options && options.logger ? options.logger : createConsoleLogger("info");
+	const telemetryEnabled = !("telemetry" in options && options.telemetry === false);
+	const wsBaseUrl = parsedOptions.data.realtimeBaseUrl || "wss://api3.decart.ai";
+	const realtimePublish = createRealTimeClient({
+		baseUrl: wsBaseUrl,
+		apiKey: apiKey || "",
+		integration,
+		logger,
+		telemetryEnabled
+	});
+	const realtimeSubscribe = createRealTimeSubscribeClient({
+		baseUrl: isProxyMode || parsedOptions.data.baseUrl !== void 0 ? baseUrl : wsBaseUrl.replace(/^wss?:\/\//i, "https://"),
+		apiKey: apiKey || "",
+		integration,
+		logger
+	});
+	const process = createProcessClient({
+		baseUrl,
+		apiKey: apiKey || "",
+		integration
+	});
+	const queue = createQueueClient({
+		baseUrl,
+		apiKey: apiKey || "",
+		integration
+	});
+	const tokens = createTokensClient({
+		baseUrl,
+		apiKey: apiKey || "",
+		integration
+	});
 	return {
-		realtime: createRealTimeClient({
-			baseUrl: parsedOptions.data.realtimeBaseUrl || "wss://api3.decart.ai",
-			apiKey: apiKey || "",
-			integration,
-			logger,
-			telemetryEnabled
-		}),
-		process: createProcessClient({
-			baseUrl,
-			apiKey: apiKey || "",
-			integration
-		}),
-		queue: createQueueClient({
-			baseUrl,
-			apiKey: apiKey || "",
-			integration
-		}),
-		tokens: createTokensClient({
-			baseUrl,
-			apiKey: apiKey || "",
-			integration
-		})
+		realtime: {
+			connect: realtimePublish.connect,
+			subscribe: realtimeSubscribe.subscribe
+		},
+		process,
+		queue,
+		tokens
 	};
 };
-
 //#endregion
-export { ERROR_CODES, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };
+export { ERROR_CODES, createConsoleLogger, createDecartClient, isCanonicalModel, isImageModel, isModel, isRealtimeModel, isVideoModel, listModels, modelAliases, models, noopLogger, resolveCanonicalModelAlias, resolveModelAlias };

package/dist/process/client.js

@@ -1,7 +1,6 @@
 import { createInvalidInputError } from "../utils/errors.js";
 import { fileInputToBlob } from "../shared/request.js";
 import { sendRequest } from "./request.js";
-
 //#region src/process/client.ts
 const createProcessClient = (opts) => {
 	const { apiKey, baseUrl, integration } = opts;
@@ -23,6 +22,5 @@ const createProcessClient = (opts) => {
 	};
 	return _process;
 };
-
 //#endregion
-export { createProcessClient };
+export { createProcessClient };

package/dist/process/request.js

@@ -1,6 +1,5 @@
 import { createSDKError } from "../utils/errors.js";
 import { buildAuthHeaders, buildFormData } from "../shared/request.js";
-
 //#region src/process/request.ts
 async function sendRequest({ baseUrl, apiKey, model, inputs, signal, integration }) {
 	const formData = buildFormData(inputs);
@@ -21,6 +20,5 @@ async function sendRequest({ baseUrl, apiKey, model, inputs, signal, integration
 	}
 	return response.blob();
 }
-
 //#endregion
-export { sendRequest };
+export { sendRequest };

package/dist/queue/client.js

@@ -2,7 +2,6 @@ import { createInvalidInputError } from "../utils/errors.js";
 import { fileInputToBlob } from "../shared/request.js";
 import { pollUntilComplete } from "./polling.js";
 import { getJobContent, getJobStatus, submitJob } from "./request.js";
-
 //#region src/queue/client.ts
 const createQueueClient = (opts) => {
 	const { apiKey, baseUrl, integration } = opts;
@@ -68,6 +67,5 @@ const createQueueClient = (opts) => {
 		submitAndPoll
 	};
 };
-
 //#endregion
-export { createQueueClient };
+export { createQueueClient };

package/dist/queue/polling.js

@@ -35,6 +35,5 @@ async function pollUntilComplete({ checkStatus, getContent, onStatusChange, sign
 		await sleep(POLLING_DEFAULTS.interval);
 	}
 }
-
 //#endregion
-export { pollUntilComplete };
+export { pollUntilComplete };

package/dist/queue/request.js

@@ -1,6 +1,5 @@
 import { createQueueResultError, createQueueStatusError, createQueueSubmitError } from "../utils/errors.js";
 import { buildAuthHeaders, buildFormData } from "../shared/request.js";
-
 //#region src/queue/request.ts
 /**
 * Submit a job to the queue.
@@ -68,6 +67,5 @@ async function getJobContent({ baseUrl, apiKey, jobId, signal, integration }) {
 	}
 	return response.blob();
 }
-
 //#endregion
-export { getJobContent, getJobStatus, submitJob };
+export { getJobContent, getJobStatus, submitJob };

package/dist/realtime/client.d.ts

@@ -1,9 +1,9 @@
 import { CustomModelDefinition, ModelDefinition } from "../shared/model.js";
 import { DecartSDKError } from "../utils/errors.js";
-import { DiagnosticEvent } from "./diagnostics.js";
-import { ConnectionState } from "./types.js";
+import { DiagnosticEvent } from "./observability/diagnostics.js";
+import { WebRTCStats } from "./observability/webrtc-stats.js";
+import { ConnectionState, GenerationEnded, GenerationTick, ImageSetOptions, QueuePosition } from "./types.js";
 import { SetInput } from "./methods.js";
-import { WebRTCStats } from "./webrtc-stats.js";
 import { z } from "zod";
 
 //#region src/realtime/client.d.ts
@@ -16,18 +16,27 @@ declare const realTimeClientInitialStateSchema: z.ZodObject<{
   image: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>>;
 }, z.core.$strip>;
 type OnRemoteStreamFn = (stream: MediaStream) => void;
+type OnConnectionChangeFn = (state: ConnectionState) => void;
+type OnQueuePositionFn = (queuePosition: QueuePosition) => void;
 type RealTimeClientInitialState = z.infer<typeof realTimeClientInitialStateSchema>;
 declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
   model: z.ZodObject<{
     name: z.ZodString;
     urlPath: z.ZodString;
     queueUrlPath: z.ZodOptional<z.ZodString>;
-    fps: z.ZodNumber;
+    fps: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+      max: z.ZodOptional<z.ZodNumber>;
+      min: z.ZodOptional<z.ZodNumber>;
+      ideal: z.ZodOptional<z.ZodNumber>;
+      exact: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>;
     width: z.ZodNumber;
     height: z.ZodNumber;
     inputSchema: z.ZodOptional<z.ZodAny>;
   }, z.core.$strip>;
   onRemoteStream: z.ZodCustom<OnRemoteStreamFn, OnRemoteStreamFn>;
+  onConnectionChange: z.ZodOptional<z.ZodCustom<OnConnectionChangeFn, OnConnectionChangeFn>>;
+  onQueuePosition: z.ZodOptional<z.ZodCustom<OnQueuePositionFn, OnQueuePositionFn>>;
   initialState: z.ZodOptional<z.ZodObject<{
     prompt: z.ZodOptional<z.ZodObject<{
       text: z.ZodString;
@@ -35,18 +44,22 @@ declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     image: z.ZodOptional<z.ZodUnion<readonly [z.ZodCustom<Blob, Blob>, z.ZodCustom<File, File>, z.ZodString]>>;
   }, z.core.$strip>>;
-  customizeOffer: z.ZodOptional<z.ZodCustom<z.core.$InferInnerFunctionTypeAsync<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>, z.core.$InferInnerFunctionTypeAsync<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>>;
+  queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   mirror: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodBoolean]>>;
+  resolution: z.ZodOptional<z.ZodEnum<{
+    "720p": "720p";
+    "1080p": "1080p";
+  }>>;
 }, z.core.$strip>;
 type RealTimeClientConnectOptions = Omit<z.infer<typeof realTimeClientConnectOptionsSchema>, "model"> & {
   model: ModelDefinition | CustomModelDefinition;
 };
 type Events = {
   connectionChange: ConnectionState;
+  queuePosition: QueuePosition;
   error: DecartSDKError;
-  generationTick: {
-    seconds: number;
-  };
+  generationTick: GenerationTick;
+  generationEnded: GenerationEnded;
   diagnostic: DiagnosticEvent;
   stats: WebRTCStats;
 };
@@ -64,11 +77,8 @@ type RealTimeClient = {
   off: <K extends keyof Events>(event: K, listener: (data: Events[K]) => void) => void;
   sessionId: string | null;
   subscribeToken: string | null;
-  setImage: (image: Blob | File | string | null, options?: {
-    prompt?: string;
-    enhance?: boolean;
-    timeout?: number;
-  }) => Promise<void>;
+  getSubscribeToken: () => string | null;
+  setImage: (image: Blob | File | string | null, options?: ImageSetOptions) => Promise<void>;
 };
 //#endregion
 export { Events, RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState };