@decartai/sdk 0.0.21 → 0.0.23

package/README.md

@@ -62,7 +62,9 @@ realtimeClient.setPrompt("Cyberpunk city");
 realtimeClient.disconnect();
 ```
 
-### Process Files
+### Async Processing (Queue API)
+
+For video generation jobs, use the queue API to submit jobs and poll for results:
 
 ```typescript
 import { createDecartClient, models } from "@decartai/sdk";
@@ -71,15 +73,41 @@ const client = createDecartClient({
   apiKey: "your-api-key-here"
 });
 
-// Process a video file
-const file = fileInput.files[0];
-const result = await client.process({
-  model: models.video("lucy-pro-v2v"),
-  prompt: "Lego World",
-  data: file
+// Submit and poll automatically
+const result = await client.queue.submitAndPoll({
+  model: models.video("lucy-pro-t2v"),
+  prompt: "A cat playing piano",
+  onStatusChange: (job) => {
+    console.log(`Status: ${job.status}`);
+  }
 });
 
-videoElement.src = URL.createObjectURL(result);
+if (result.status === "completed") {
+  videoElement.src = URL.createObjectURL(result.data);
+} else {
+  console.error("Job failed:", result.error);
+}
+```
+
+Or manage the polling manually:
+
+```typescript
+// Submit the job
+const job = await client.queue.submit({
+  model: models.video("lucy-pro-t2v"),
+  prompt: "A cat playing piano"
+});
+console.log(`Job ID: ${job.job_id}`);
+
+// Poll for status
+const status = await client.queue.status(job.job_id);
+console.log(`Status: ${status.status}`);
+
+// Get result when completed
+if (status.status === "completed") {
+  const blob = await client.queue.result(job.job_id);
+  videoElement.src = URL.createObjectURL(blob);
+}
 ```
 
 ## Development

package/dist/index.d.ts

@@ -10,12 +10,29 @@ import { z } from "zod";
 
 //#region src/index.d.ts
 declare const decartClientOptionsSchema: z.ZodObject<{
-  apiKey: z.ZodString;
+  apiKey: z.ZodOptional<z.ZodString>;
   baseUrl: z.ZodOptional<z.ZodURL>;
   integration: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type DecartClientOptions = z.infer<typeof decartClientOptionsSchema>;
-declare const createDecartClient: (options: DecartClientOptions) => {
+/**
+ * Create a Decart API client.
+ *
+ * @param options - Configuration options
+ * @param options.apiKey - API key for authentication. Defaults to the DECART_API_KEY environment variable.
+ * @param options.baseUrl - Override the default API base URL.
+ * @param options.integration - Optional integration identifier.
+ *
+ * @example
+ * ```ts
+ * // Option 1: Explicit API key
+ * const client = createDecartClient({ apiKey: "your-api-key" });
+ *
+ * // Option 2: Using DECART_API_KEY environment variable
+ * const client = createDecartClient();
+ * ```
+ */
+declare const createDecartClient: (options?: DecartClientOptions) => {
   realtime: {
     connect: (stream: MediaStream, options: RealTimeClientConnectOptions) => Promise<RealTimeClient>;
   };

package/dist/index.js

@@ -3,42 +3,60 @@ import { createProcessClient } from "./process/client.js";
 import { createQueueClient } from "./queue/client.js";
 import { models } from "./shared/model.js";
 import { createRealTimeClient } from "./realtime/client.js";
+import { readEnv } from "./utils/env.js";
 import { z } from "zod";
 
 //#region src/index.ts
 const decartClientOptionsSchema = z.object({
-	apiKey: z.string().min(1),
+	apiKey: z.string().min(1).optional(),
 	baseUrl: z.url().optional(),
 	integration: z.string().optional()
 });
-const createDecartClient = (options) => {
-	const parsedOptions = decartClientOptionsSchema.safeParse(options);
+/**
+* Create a Decart API client.
+*
+* @param options - Configuration options
+* @param options.apiKey - API key for authentication. Defaults to the DECART_API_KEY environment variable.
+* @param options.baseUrl - Override the default API base URL.
+* @param options.integration - Optional integration identifier.
+*
+* @example
+* ```ts
+* // Option 1: Explicit API key
+* const client = createDecartClient({ apiKey: "your-api-key" });
+*
+* // Option 2: Using DECART_API_KEY environment variable
+* const client = createDecartClient();
+* ```
+*/
+const createDecartClient = (options = {}) => {
+	const apiKey = options.apiKey ?? readEnv("DECART_API_KEY");
+	if (!apiKey) throw createInvalidApiKeyError();
+	const parsedOptions = decartClientOptionsSchema.safeParse({
+		...options,
+		apiKey
+	});
 	if (!parsedOptions.success) {
-		const issue = parsedOptions.error.issues[0];
-		if (issue.path.includes("apiKey")) throw createInvalidApiKeyError();
-		if (issue.path.includes("baseUrl")) throw createInvalidBaseUrlError(options.baseUrl);
+		if (parsedOptions.error.issues[0].path.includes("baseUrl")) throw createInvalidBaseUrlError(options.baseUrl);
 		throw parsedOptions.error;
 	}
-	const { baseUrl = "https://api.decart.ai", apiKey, integration } = parsedOptions.data;
-	const realtime = createRealTimeClient({
-		baseUrl: "wss://api3.decart.ai",
-		apiKey,
-		integration
-	});
-	const process = createProcessClient({
-		baseUrl,
-		apiKey,
-		integration
-	});
-	const queue = createQueueClient({
-		baseUrl,
-		apiKey,
-		integration
-	});
+	const { baseUrl = "https://api.decart.ai", integration } = parsedOptions.data;
 	return {
-		realtime,
-		process,
-		queue
+		realtime: createRealTimeClient({
+			baseUrl: "wss://api3.decart.ai",
+			apiKey,
+			integration
+		}),
+		process: createProcessClient({
+			baseUrl,
+			apiKey,
+			integration
+		}),
+		queue: createQueueClient({
+			baseUrl,
+			apiKey,
+			integration
+		})
 	};
 };
 

package/dist/process/client.js

@@ -6,7 +6,7 @@ import { sendRequest } from "./request.js";
 const createProcessClient = (opts) => {
 	const { apiKey, baseUrl, integration } = opts;
 	const _process = async (options) => {
-		const { model, signal,...inputs } = options;
+		const { model, signal, ...inputs } = options;
 		const parsedInputs = model.inputSchema.safeParse(inputs);
 		if (!parsedInputs.success) throw createInvalidInputError(`Invalid inputs for ${model.name}: ${parsedInputs.error.message}`);
 		const processedInputs = {};

package/dist/process/types.d.ts

@@ -25,6 +25,11 @@ interface ImageEditingInputs {
    * It's highly recommended to read our [Prompt Engineering for Edits](https://docs.platform.decart.ai/models/image/image-editing#prompt-engineering-for-edits) guide for how to write effective editing prompts.
    */
   prompt: string;
+  /**
+   * The data to use for generation (for image-to-image).
+   * Can be a File, Blob, ReadableStream, URL, or string URL.
+   */
+  data?: FileInput;
 }
 /**
  * Model-specific input documentation for video models.
@@ -36,6 +41,13 @@ interface VideoModelInputs {
    * See our [Prompt Engineering](https://docs.platform.decart.ai/models/video/video-generation#prompt-engineering) guide for how to write prompt for Decart video models effectively.
    */
   prompt: string;
+  /**
+   * The data to use for generation (for image-to-video and video-to-video).
+   * Can be a File, Blob, ReadableStream, URL, or string URL.
+   *
+   * Output video is limited to 5 seconds.
+   */
+  data?: FileInput;
 }
 /**
  * Default inputs for models that only require a prompt.
@@ -73,11 +85,6 @@ interface ProcessInputs {
    * @default "landscape"
    */
   orientation?: "landscape" | "portrait";
-  /**
-   * The data to use for generation (for image-to-image and video-to-video).
-   * Can be a File, Blob, ReadableStream, URL, or string URL.
-   */
-  data?: FileInput;
   /**
    * The start frame image (for first-last-frame models).
    * Can be a File, Blob, ReadableStream, URL, or string URL.

package/dist/queue/client.js

@@ -7,7 +7,7 @@ import { getJobContent, getJobStatus, submitJob } from "./request.js";
 const createQueueClient = (opts) => {
 	const { apiKey, baseUrl, integration } = opts;
 	const submit = async (options) => {
-		const { model, signal,...inputs } = options;
+		const { model, signal, ...inputs } = options;
 		const parsedInputs = model.inputSchema.safeParse(inputs);
 		if (!parsedInputs.success) throw createInvalidInputError(`Invalid inputs for ${model.name}: ${parsedInputs.error.message}`);
 		const processedInputs = {};
@@ -39,7 +39,7 @@ const createQueueClient = (opts) => {
 		});
 	};
 	const submitAndPoll = async (options) => {
-		const { onStatusChange, signal,...submitOptions } = options;
+		const { onStatusChange, signal, ...submitOptions } = options;
 		const job = await submit(submitOptions);
 		if (onStatusChange) onStatusChange(job);
 		return pollUntilComplete({

package/dist/queue/types.d.ts

@@ -36,10 +36,6 @@ type QueueJobResult = {
  * Re-exports ProcessInputs fields with queue-specific documentation.
  */
 interface QueueInputs extends ProcessInputs {
-  /**
-   * The data to use for generation (for image-to-image and video-to-video).
-   */
-  data?: FileInput;
   /**
    * The start frame image (for first-last-frame models).
    */

package/dist/realtime/client.js

@@ -24,9 +24,8 @@ const createRealTimeClient = (opts) => {
 		if (!parsedOptions.success) throw parsedOptions.error;
 		const sessionId = v4();
 		const { onRemoteStream, initialState } = parsedOptions.data;
-		const url = `${baseUrl}${options.model.urlPath}`;
 		const webrtcManager = new WebRTCManager({
-			webrtcUrl: `${url}?api_key=${apiKey}&model=${options.model.name}`,
+			webrtcUrl: `${`${baseUrl}${options.model.urlPath}`}?api_key=${apiKey}&model=${options.model.name}`,
 			apiKey,
 			sessionId,
 			fps: options.model.fps,

package/dist/realtime/webrtc-connection.js

@@ -17,8 +17,7 @@ var WebRTCConnection = class {
 		const deadline = Date.now() + timeout;
 		this.localStream = localStream;
 		const userAgent = encodeURIComponent(buildUserAgent(integration));
-		const separator = url.includes("?") ? "&" : "?";
-		const wsUrl = `${url}${separator}user_agent=${userAgent}`;
+		const wsUrl = `${url}${url.includes("?") ? "&" : "?"}user_agent=${userAgent}`;
 		await new Promise((resolve, reject) => {
 			this.connectionReject = reject;
 			const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("WebSocket timeout")), timeout);

package/dist/shared/model.js

@@ -63,19 +63,19 @@ const modelInputSchemas = {
 	}),
 	"lucy-pro-i2v": z.object({
 		prompt: z.string().min(1).max(1e3).describe("The prompt to use for the generation"),
-		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL)"),
+		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL). Output video is limited to 5 seconds."),
 		seed: z.number().optional().describe("The seed to use for the generation"),
 		resolution: proResolutionSchema()
 	}),
 	"lucy-dev-i2v": z.object({
 		prompt: z.string().min(1).max(1e3).describe("The prompt to use for the generation"),
-		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL)"),
+		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL). Output video is limited to 5 seconds."),
 		seed: z.number().optional().describe("The seed to use for the generation"),
 		resolution: devResolutionSchema
 	}),
 	"lucy-pro-v2v": z.object({
 		prompt: z.string().min(1).max(1e3).describe("The prompt to use for the generation"),
-		data: fileInputSchema.describe("The video data to use for generation (File, Blob, ReadableStream, URL, or string URL)"),
+		data: fileInputSchema.describe("The video data to use for generation (File, Blob, ReadableStream, URL, or string URL). Output video is limited to 5 seconds."),
 		seed: z.number().optional().describe("The seed to use for the generation"),
 		resolution: proV2vResolutionSchema,
 		enhance_prompt: z.boolean().optional().describe("Whether to enhance the prompt"),
@@ -83,7 +83,7 @@ const modelInputSchemas = {
 	}),
 	"lucy-fast-v2v": z.object({
 		prompt: z.string().min(1).max(1e3).describe("The prompt to use for the generation"),
-		data: fileInputSchema.describe("The video data to use for generation (File, Blob, ReadableStream, URL, or string URL)"),
+		data: fileInputSchema.describe("The video data to use for generation (File, Blob, ReadableStream, URL, or string URL). Output video is limited to 5 seconds."),
 		seed: z.number().optional().describe("The seed to use for the generation"),
 		resolution: proV2vResolutionSchema,
 		enhance_prompt: z.boolean().optional().describe("Whether to enhance the prompt")
@@ -103,7 +103,7 @@ const modelInputSchemas = {
 		enhance_prompt: z.boolean().optional().describe("Whether to enhance the prompt")
 	}),
 	"lucy-motion": z.object({
-		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL)"),
+		data: fileInputSchema.describe("The image data to use for generation (File, Blob, ReadableStream, URL, or string URL). Output video is limited to 5 seconds."),
 		trajectory: z.array(z.object({
 			frame: z.number().min(0),
 			x: z.number().min(0),

package/dist/utils/env.js

@@ -0,0 +1,9 @@
+//#region src/utils/env.ts
+const readEnv = (env) => {
+	const globalThisAny = globalThis;
+	if (typeof globalThisAny.process !== "undefined") return globalThisAny.process.env?.[env]?.trim();
+	if (typeof globalThisAny.Deno !== "undefined") return globalThisAny.Deno.env?.get?.(env)?.trim();
+};
+
+//#endregion
+export { readEnv };

package/dist/utils/errors.js

@@ -21,7 +21,7 @@ function createSDKError(code, message, data, cause) {
 	};
 }
 function createInvalidApiKeyError() {
-	return createSDKError(ERROR_CODES.INVALID_API_KEY, "API key is required and must be a non-empty string");
+	return createSDKError(ERROR_CODES.INVALID_API_KEY, "Missing API key. Pass `apiKey` to createDecartClient() or set the DECART_API_KEY environment variable.");
 }
 function createInvalidBaseUrlError(url) {
 	return createSDKError(ERROR_CODES.INVALID_BASE_URL, `Invalid base URL${url ? `: ${url}` : ""}`);

package/dist/version.js

@@ -4,7 +4,7 @@
 * Injected at build time from package.json.
 * Falls back to '0.0.0-dev' in development.
 */
-const VERSION = "0.0.21";
+const VERSION = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : "0.0.0-dev";
 
 //#endregion
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
   "dependencies": {
     "mitt": "^3.0.1",
     "p-retry": "^6.2.1",
-    "uuid": "^11.1.0",
+    "uuid": "^13.0.0",
     "zod": "^4.0.17"
   },
   "scripts": {