@decartai/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DecartAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,423 @@
+# Decart SDK
+
+A JavaScript SDK for Decart's models.
+
+## Installation
+
+```bash
+npm install @decartai/sdk
+# or
+pnpm add @decartai/sdk
+# or
+yarn add @decartai/sdk
+```
+
+## Quick Start
+
+### Real-time Video Transformation
+
+```typescript
+import { createDecartClient, models } from "@decartai/sdk";
+
+const model = models.realtime("mirage");
+
+// Get user's camera stream
+const stream = await navigator.mediaDevices.getUserMedia({
+  audio: true,
+  video: { 
+		frameRate: model.fps,
+		width: model.width,
+		height: model.height,
+  }
+});
+
+// Create a client
+const client = createDecartClient({
+  apiKey: "your-api-key-here"
+});
+
+// Connect and transform the video stream
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  onRemoteStream: (transformedStream) => {
+    // Display the transformed video in your app
+    videoElement.srcObject = transformedStream;
+  },
+  initialState: {
+    prompt: {
+      text: "Anime",
+      enrich: true // We will enhance your prompt for better results
+    }
+  }
+});
+
+// Change the style on the fly
+realtimeClient.setPrompt("Cyberpunk city");
+
+// Disconnect when done
+realtimeClient.disconnect();
+```
+
+### Process Video Files
+
+```typescript
+import { createDecartClient } from "@decartai/sdk";
+
+// Create a client
+const client = createDecartClient({
+  apiKey: "your-api-key-here"
+});
+
+// Process a local video file
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+const result = await client.process.video(file, {
+  model: models.realtime("mirage"),
+  prompt: {
+    text: "Lego World",
+    enrich: true
+  },
+  mirror: false
+});
+
+// Display the processed video
+const video = document.querySelector('video');
+video.src = URL.createObjectURL(result);
+
+// Process a video from URL
+const urlResult = await client.process.video(
+  "https://example.com/video.mp4",
+  {
+    model: models.realtime("mirage"),
+    prompt: {
+      text: "Anime style"
+    }
+  }
+);
+```
+
+## Features
+
+- **Real-time video transformation** - Transform video streams with minimal latency using WebRTC
+- **Video file processing** - Transform video files and URLs on-demand
+- **Dynamic prompt switching** - Change styles on the fly without reconnecting
+- **Automatic prompt enhancement** - Decart enriches simple prompts for better results
+- **Mirror mode** - Built-in support for front-facing camera scenarios
+- **Connection state management** - Monitor and react to connection changes
+- **TypeScript support** - Full type definitions included
+
+## Usage Guide
+
+### Real-time API
+
+#### 1. Creating a Client
+
+```typescript
+const client = createDecartClient({
+  apiKey: "your-api-key-here",
+  baseUrl: "https://custom-endpoint.com" // optional, uses default Decart endpoint
+});
+```
+
+#### 2. Connecting to the Real-time API
+
+```typescript
+const realtimeClient = await client.realtime.connect(stream, {
+  model: models.realtime("mirage"),
+  onRemoteStream: (stream: MediaStream) => {
+    // Handle the transformed video stream
+    videoElement.srcObject = stream;
+  },
+  initialState: {
+    prompt: {
+      text: "Lego World",
+      enrich: true // Let Decart enhance the prompt (recommended)
+    },
+    mirror: false // Set to true for front-facing cameras
+  }
+});
+```
+
+#### 3. Managing Prompts
+
+```typescript
+// Simple prompt with automatic enhancement
+realtimeClient.setPrompt("Anime style");
+
+// Use your own detailed prompt without enhancement
+realtimeClient.setPrompt(
+  "A detailed artistic style with specific colors and mood...",
+  { enrich: false }
+);
+
+// Get an enhanced prompt without applying it (for preview/debugging)
+const enhanced = await realtimeClient.enrichPrompt("Pixel art");
+console.log(enhanced);
+realtimeClient.setPrompt(enhanced, { enrich: false });
+```
+
+#### 4. Camera Mirroring
+
+```typescript
+// Toggle mirror mode (useful for front-facing cameras)
+realtimeClient.setMirror(true);
+```
+
+#### 5. Connection State Management
+
+```typescript
+// Check connection state synchronously
+const isConnected = realtimeClient.isConnected();
+const state = realtimeClient.getConnectionState(); // "connected" | "connecting" | "disconnected"
+
+// Listen to connection changes
+realtimeClient.on("connectionChange", (state) => {
+  console.log(`Connection state: ${state}`);
+  if (state === "disconnected") {
+    // Handle disconnection
+  }
+});
+```
+
+#### 6. Error Handling
+
+```typescript
+import type { DecartSDKError } from "@decartai/sdk";
+
+realtimeClient.on("error", (error: DecartSDKError) => {
+  console.error("SDK error:", error.code, error.message);
+  
+  // Handle specific errors
+  switch(error.code) {
+    case "INVALID_API_KEY":
+      // Handle invalid API key
+      break;
+    case "WEB_RTC_ERROR":
+      // Handle WebRTC connection issues
+      break;
+  }
+});
+```
+
+#### 7. Cleanup
+
+```typescript
+// Always disconnect when done
+realtimeClient.disconnect();
+
+// Remove event listeners
+realtimeClient.off("connectionChange", onConnectionChange);
+realtimeClient.off("error", onError);
+```
+
+### Complete Example
+
+```typescript
+import { createDecartClient, type DecartSDKError } from "@decartai/sdk";
+
+async function setupSDK() {
+  try {
+    // Get camera stream
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: true,
+      video: { frameRate: 14 }
+    });
+
+    // Create client
+    const client = createDecartClient({
+      apiKey: process.env.MIRAGE_API_KEY
+    });
+
+    // Connect with initial prompt
+    const realtimeClient = await client.realtime.connect(stream, {
+      onRemoteStream: (stream) => {
+        const video = document.getElementById("output-video");
+        video.srcObject = stream;
+      },
+      initialState: {
+        prompt: {
+          text: "Studio Ghibli animation style",
+          enrich: true
+        },
+        mirror: true // Using front camera
+      }
+    });
+
+    // Set up event handlers
+    realtimeClient.on("connectionChange", (state) => {
+      updateUIConnectionStatus(state);
+    });
+
+    realtimeClient.on("error", (error) => {
+      console.error("SDK error:", error);
+      showErrorToUser(error.message);
+    });
+
+    // Allow user to change styles
+    document.getElementById("style-input").addEventListener("change", async (e) => {
+      realtimeClient.setPrompt(e.target.value);
+    });
+
+    // Cleanup on page unload
+    window.addEventListener("beforeunload", async () => {
+      realtimeClient.disconnect();
+    });
+
+    return realtimeClient;
+  } catch (error) {
+    console.error("Failed to setup DecartSDK:", error);
+  }
+}
+
+setupSDK();
+```
+
+## Process API
+
+#### 1. Creating a Client
+
+```typescript
+const client = createDecartClient({
+  apiKey: "your-api-key-here",
+  baseUrl: "https://custom-endpoint.com" // optional, uses default Decart endpoint
+});
+```
+
+#### 2. Process Video Files
+
+```typescript
+// 1. Process a local file (browser)
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+
+const result = await client.process.video(file, {
+  prompt: {
+    text: "Cartoon style",
+    enrich: true
+  },
+  mirror: false
+});
+
+// Use the processed video
+const video = document.querySelector('video');
+video.src = URL.createObjectURL(result);
+
+// 3. With cancellation
+const controller = new AbortController();
+const result = await client.process.video(file, {
+  prompt: { text: "Watercolor painting" },
+  signal: controller.signal
+});
+
+// Cancel if needed
+controller.abort();
+```
+
+## API Reference
+
+### `createDecartClient(options)`
+Creates a new Decart client instance.
+
+- `options.apiKey` (required) - Your Decart API key
+- `options.baseUrl` (optional) - Custom API endpoint (defaults to Decart)
+
+### Real-time API
+
+#### `client.realtime.connect(stream, options)`
+Connects to the real-time transformation service.
+
+- `stream` - MediaStream from getUserMedia
+- `options.onRemoteStream` - Callback for transformed video stream
+- `options.initialState.prompt` - Initial transformation prompt
+- `options.initialState.mirror` - Enable mirror mode
+
+#### `realtimeClient.setPrompt(prompt, options?)`
+Changes the transformation style.
+
+- `prompt` - Text description of desired style
+- `options.enrich` - Whether to enhance the prompt (default: true)
+
+#### `realtimeClient.enrichPrompt(prompt)`
+Gets an enhanced version of your prompt without applying it.
+
+#### `realtimeClient.setMirror(enabled)`
+Toggles video mirroring.
+
+#### `realtimeClient.sessionId`
+The id of the current real-time inference session.
+
+#### `realtimeClient.disconnect()`
+Closes the connection and cleans up resources.
+
+#### Event: `'connectionChange'`
+Fired when connection state changes.
+
+#### Event: `'error'`
+Fired when an error occurs.
+
+### Process API
+
+#### `client.process.video(input, options?)`
+Process a video file or URL.
+
+**Parameters:**
+- `input: FileInput` - Video input, can be:
+  - `File` - File object from input element (browser)
+  - `Blob` - Binary data (browser)
+  - `ReadableStream` - Streaming input
+  - `URL` or `string` - HTTP/HTTPS URL to video
+
+- `options?: ProcessOptions` - Optional configuration:
+  - `prompt?: { text: string; enrich?: boolean }` - Style transformation
+    - `text` - Style description (required if prompt is provided)
+    - `enrich` - Enable prompt enhancement (default: `true`)
+  - `mirror?: boolean` - Mirror the video horizontally (default: `false`)
+  - `signal?: AbortSignal` - AbortSignal for cancellation
+
+**Returns:** `Promise<Blob>` - The transformed video
+
+**Type Definitions:**
+```typescript
+type FileInput = File | Blob | ReadableStream | URL | string;
+
+type ProcessOptions = {
+  prompt?: {
+    text: string;
+    enrich?: boolean;
+  };
+  mirror?: boolean;
+  signal?: AbortSignal;
+};
+```
+
+## Development
+
+### Install dependencies
+```bash
+pnpm install
+```
+
+### Run tests
+```bash
+pnpm test
+```
+
+### Build the library
+```bash
+pnpm build
+```
+
+### Run development mode
+```bash
+pnpm dev
+```
+
+### Run examples
+```bash
+pnpm dev:example
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Model, ModelDefinition, models } from "./shared/model.js";
+import { FileInput, ProcessOptions } from "./process/types.js";
+import { ProcessClient } from "./process/client.js";
+import { DecartSDKError, ERROR_CODES } from "./utils/errors.js";
+import { RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState } from "./realtime/client.js";
+import { ModelState } from "./shared/types.js";
+import { z } from "zod";
+
+//#region src/index.d.ts
+declare const decartClientOptionsSchema: z.ZodObject<{
+  apiKey: z.ZodString;
+  baseUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+type DecartClientOptions = z.infer<typeof decartClientOptionsSchema>;
+declare const createDecartClient: (options: DecartClientOptions) => {
+  realtime: {
+    connect: (stream: MediaStream, options: RealTimeClientConnectOptions) => Promise<RealTimeClient>;
+  };
+  process: ProcessClient;
+};
+//#endregion
+export { DecartClientOptions, type DecartSDKError, ERROR_CODES, type FileInput, type Model, type ModelDefinition, type ModelState, type ProcessClient, type ProcessOptions, type RealTimeClient, type RealTimeClientConnectOptions, type RealTimeClientInitialState, createDecartClient, models };

package/dist/index.js

@@ -0,0 +1,36 @@
+import { ERROR_CODES, createInvalidApiKeyError, createInvalidBaseUrlError } from "./utils/errors.js";
+import { createProcessClient } from "./process/client.js";
+import { models } from "./shared/model.js";
+import { createRealTimeClient } from "./realtime/client.js";
+import { z } from "zod";
+
+//#region src/index.ts
+const decartClientOptionsSchema = z.object({
+	apiKey: z.string().min(1),
+	baseUrl: z.url().optional()
+});
+const createDecartClient = (options) => {
+	const parsedOptions = decartClientOptionsSchema.safeParse(options);
+	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);
+		throw parsedOptions.error;
+	}
+	const { baseUrl = "https://api.decart.ai", apiKey } = parsedOptions.data;
+	const realtime = createRealTimeClient({
+		baseUrl: "wss://api3.decart.ai",
+		apiKey
+	});
+	const process = createProcessClient({
+		baseUrl,
+		apiKey
+	});
+	return {
+		realtime,
+		process
+	};
+};
+
+//#endregion
+export { ERROR_CODES, createDecartClient, models };

package/dist/process/client.d.ts

@@ -0,0 +1,7 @@
+import { ModelDefinition } from "../shared/model.js";
+import { ProcessOptions } from "./types.js";
+
+//#region src/process/client.d.ts
+type ProcessClient = <T extends ModelDefinition>(options: ProcessOptions<T>) => Promise<Blob>;
+//#endregion
+export { ProcessClient };

package/dist/process/client.js

@@ -0,0 +1,26 @@
+import { createInvalidInputError } from "../utils/errors.js";
+import { fileInputToBlob, sendRequest } from "./request.js";
+
+//#region src/process/client.ts
+const createProcessClient = (opts) => {
+	const { apiKey, baseUrl } = opts;
+	const _process = async (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 = {};
+		for (const [key, value] of Object.entries(parsedInputs.data)) if (key === "data" || key === "start" || key === "end") processedInputs[key] = await fileInputToBlob(value);
+		else processedInputs[key] = value;
+		return await sendRequest({
+			baseUrl,
+			apiKey,
+			model,
+			inputs: processedInputs,
+			signal
+		});
+	};
+	return _process;
+};
+
+//#endregion
+export { createProcessClient };

package/dist/process/request.js

@@ -0,0 +1,35 @@
+import { createInvalidInputError, createSDKError } from "../utils/errors.js";
+
+//#region src/process/request.ts
+async function fileInputToBlob(input) {
+	if (input instanceof Blob || input instanceof File) return input;
+	if (input instanceof ReadableStream) return new Response(input).blob();
+	if (typeof input === "string" || input instanceof URL) {
+		const url = typeof input === "string" ? input : input.toString();
+		if (!url.startsWith("http://") && !url.startsWith("https://")) throw createInvalidInputError("URL must start with http:// or https://");
+		const response = await fetch(url);
+		if (!response.ok) throw createInvalidInputError(`Failed to fetch file from URL: ${response.statusText}`);
+		return response.blob();
+	}
+	throw createInvalidInputError("Invalid file input type");
+}
+async function sendRequest({ baseUrl, apiKey, model, inputs, signal }) {
+	const formData = new FormData();
+	for (const [key, value] of Object.entries(inputs)) if (value !== void 0 && value !== null) if (value instanceof Blob) formData.append(key, value);
+	else formData.append(key, String(value));
+	const endpoint = `${baseUrl}${model.urlPath}`;
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers: { "X-API-KEY": apiKey },
+		body: formData,
+		signal
+	});
+	if (!response.ok) {
+		const errorText = await response.text().catch(() => "Unknown error");
+		throw createSDKError("PROCESSING_ERROR", `Processing failed: ${response.status} - ${errorText}`);
+	}
+	return response.blob();
+}
+
+//#endregion
+export { fileInputToBlob, sendRequest };

package/dist/process/types.d.ts

@@ -0,0 +1,12 @@
+import { ModelDefinition, ModelInputSchemas } from "../shared/model.js";
+import { z } from "zod";
+
+//#region src/process/types.d.ts
+type InferModelInputs<T extends ModelDefinition> = T["name"] extends keyof ModelInputSchemas ? z.input<ModelInputSchemas[T["name"]]> : Record<string, never>;
+type ProcessOptions<T extends ModelDefinition = ModelDefinition> = {
+  model: T;
+  signal?: AbortSignal;
+} & InferModelInputs<T>;
+type FileInput = File | Blob | ReadableStream | URL | string;
+//#endregion
+export { FileInput, ProcessOptions };

package/dist/realtime/client.d.ts

@@ -0,0 +1,55 @@
+import { DecartSDKError } from "../utils/errors.js";
+import { z } from "zod";
+
+//#region src/realtime/client.d.ts
+
+declare const realTimeClientInitialStateSchema: z.ZodObject<{
+  prompt: z.ZodOptional<z.ZodObject<{
+    text: z.ZodString;
+    enrich: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  }, z.core.$strip>>;
+  mirror: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type OnRemoteStreamFn = (stream: MediaStream) => void;
+type RealTimeClientInitialState = z.infer<typeof realTimeClientInitialStateSchema>;
+declare const realTimeClientConnectOptionsSchema: z.ZodObject<{
+  model: z.ZodObject<{
+    name: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodLiteral<"mirage">, z.ZodLiteral<"lucy_v2v_720p_rt">]>, z.ZodUnion<readonly [z.ZodLiteral<"lucy-dev-i2v">, z.ZodLiteral<"lucy-dev-v2v">, z.ZodLiteral<"lucy-pro-t2v">, z.ZodLiteral<"lucy-pro-i2v">, z.ZodLiteral<"lucy-pro-v2v">, z.ZodLiteral<"lucy-pro-flf2v">]>, z.ZodUnion<readonly [z.ZodLiteral<"lucy-pro-t2i">, z.ZodLiteral<"lucy-pro-i2i">]>]>;
+    urlPath: z.ZodString;
+    fps: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    inputSchema: z.ZodAny;
+  }, z.core.$strip>;
+  onRemoteStream: z.ZodCustom<OnRemoteStreamFn, OnRemoteStreamFn>;
+  initialState: z.ZodOptional<z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodObject<{
+      text: z.ZodString;
+      enrich: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    mirror: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+  }, 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>>>;
+}, z.core.$strip>;
+type RealTimeClientConnectOptions = z.infer<typeof realTimeClientConnectOptionsSchema>;
+type Events = {
+  connectionChange: "connected" | "connecting" | "disconnected";
+  error: DecartSDKError;
+};
+type RealTimeClient = {
+  enrichPrompt: (prompt: string) => Promise<string>;
+  setPrompt: (prompt: string, {
+    enrich
+  }?: {
+    enrich?: boolean;
+  }) => void;
+  setMirror: (enabled: boolean) => void;
+  isConnected: () => boolean;
+  getConnectionState: () => "connected" | "connecting" | "disconnected";
+  disconnect: () => void;
+  on: (event: keyof Events, listener: (...args: Events[keyof Events][]) => void) => void;
+  off: (event: keyof Events, listener: (...args: Events[keyof Events][]) => void) => void;
+  sessionId: string;
+};
+//#endregion
+export { RealTimeClient, RealTimeClientConnectOptions, RealTimeClientInitialState };