chore: add SDK usage examples

AGENTS.md

@@ -12,10 +12,15 @@
 
 ## Project Architecture
 - **src/index.ts** - Main entry point, exports createDecartClient with realtime and process clients
-- **src/process/** - HTTP API for asynchronous video/image generation
+- **src/process/** - HTTP API for synchronous image generation
   - `client.ts` - Process client implementation for model inference
   - `request.ts` - HTTP request handling and file input processing
   - `types.ts` - TypeScript types for process API options
+- **src/queue/** - Queue-based async job processing for video generation
+  - `client.ts` - Queue client for submit, status check, and polling
+  - `polling.ts` - Polling logic until job completion
+  - `request.ts` - HTTP request handling for queue API
+  - `types.ts` - TypeScript types for queue operations
 - **src/realtime/** - WebRTC real-time video streaming logic
   - `client.ts` - Real-time client implementation with WebRTC connection management
   - `webrtc-manager.ts` - WebRTC connection lifecycle and signaling
@@ -24,9 +29,12 @@
   - `types.ts` - TypeScript types for WebRTC messages and events
 - **src/shared/** - Shared model definitions and types
   - `model.ts` - Model registry with definitions for realtime, video, and image models
+  - `request.ts` - Shared HTTP request utilities and file input processing
   - `types.ts` - Common types across APIs (ModelState, etc.)
 - **src/utils/** - Shared utilities
+  - `env.ts` - Environment variable handling
   - `errors.ts` - Error factory pattern with ERROR_CODES constants
+  - `user-agent.ts` - User-agent string generation for HTTP requests
 - **tests/** - Test files using Vitest (.test.ts extension)
 - **dist/** - Build output (gitignored, generated by tsdown)
 
@@ -46,7 +54,7 @@
   - Dev: tsdown (build), vitest (test), typescript, vite (examples), bumpp (releases)
 
 ## API Design Patterns
-- **Factory Functions**: Use `create*` pattern for constructors (createDecartClient, createRealTimeClient, createProcessClient)
+- **Factory Functions**: Use `create*` pattern for constructors (createDecartClient, createRealTimeClient, createProcessClient, createQueueClient)
 - **Options Validation**: Validate all public API options with Zod schemas
 - **Error Messages**: Provide clear, actionable error messages with specific error codes
 - **Type Exports**: Export all public types alongside implementations
@@ -59,13 +67,14 @@
 - `mirage_v2` - Real-time video restyling model (v2)
 - `lucy_v2v_720p_rt` - Real-time video editing model
 
-### Video Models (Process API)
+### Video Models (Queue API)
 - `lucy-dev-i2v` - image-to-video (Dev quality)
 - `lucy-fast-v2v` - video-to-video (Fast quality)
 - `lucy-pro-t2v` - text-to-video (Pro quality)
 - `lucy-pro-i2v` - image-to-video (Pro quality)
 - `lucy-pro-v2v` - video-to-video (Pro quality)
 - `lucy-pro-flf2v` - first-last-frame-to-video (Pro quality)
+- `lucy-motion` - motion-based image-to-video (trajectory-guided animation)
 
 ### Image Models (Process API)
 - `lucy-pro-t2i` - text-to-image (Pro quality)

examples/bun-cli/.env.example

@@ -0,0 +1 @@
+DECART_API_KEY=your-api-key-here

examples/bun-cli/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+.env
+decart-cli
+output.png

examples/bun-cli/README.md

@@ -0,0 +1,39 @@
+# Bun CLI Example
+
+A simple CLI for text-to-image generation using the Decart SDK.
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+2. Set your API key:
+   ```bash
+   export DECART_API_KEY=your-api-key-here
+   ```
+
+3. Build:
+   ```bash
+   bun run build
+   ```
+
+4. Link the executable:
+   ```bash
+   bun link
+   ```
+
+## Usage
+
+### Dev-time
+```
+./cli.ts text-to-image "A cyberpunk cityscape at night"
+```
+
+### Compiled
+```bash
+decart text-to-image "A cyberpunk cityscape at night"
+```
+
+The generated image will be saved to `output.png`.

examples/bun-cli/cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+import { createDecartClient, models } from "@decartai/sdk";
+
+const [command, prompt] = process.argv.slice(2);
+
+if (command !== "text-to-image" || !prompt) {
+	console.error("Usage: decart text-to-image <prompt>");
+	process.exit(1);
+}
+
+const client = createDecartClient();
+
+console.log("Generating image...");
+const image = await client.process({
+	model: models.image("lucy-pro-t2i"),
+	prompt,
+});
+
+await Bun.write("output.png", image);
+
+console.log("Image saved to output.png");

examples/bun-cli/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@example/bun-cli",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"bin": {
+		"decart": "decart-cli"
+	},
+	"scripts": {
+		"build": "bun build ./cli.ts --compile --outfile decart-cli"
+	},
+	"dependencies": {
+		"@decartai/sdk": "workspace:*"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	}
+}

examples/express-api/.env.example

@@ -0,0 +1,2 @@
+DECART_API_KEY=your-api-key-here
+PORT=3000

examples/express-api/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+.env

examples/express-api/README.md

@@ -0,0 +1,78 @@
+# Express API Example
+
+An Express server demonstrating the Decart SDK's Process and Queue APIs.
+
+## Setup
+
+1. Copy `.env.example` to `.env` and add your API key:
+
+```sh
+cp .env.example .env
+```
+
+2. Install dependencies from the repo root:
+
+```sh
+cd ../..
+pnpm install
+pnpm build
+```
+
+3. Start the development server:
+
+```sh
+cd examples/express-api
+pnpm dev
+```
+
+## Endpoints
+
+### Image Generation
+
+```bash
+# Text-to-image
+curl -X POST http://localhost:3000/api/image/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "A beautiful sunset over mountains"}' \
+  --output image.png
+
+# Image-to-image
+curl -X POST http://localhost:3000/api/image/transform \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Oil painting style", "imageUrl": "https://example.com/image.jpg"}' \
+  --output transformed.png
+```
+
+### Video Generation
+
+```bash
+# Submit video job
+curl -X POST http://localhost:3000/api/video/generate \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "A cat playing piano"}'
+# Returns: {"jobId": "abc123", "status": "pending"}
+
+# Check status
+curl http://localhost:3000/api/video/status/abc123
+# Returns: {"job_id": "abc123", "status": "processing"}
+
+# Get result (when completed)
+curl http://localhost:3000/api/video/result/abc123 --output video.mp4
+
+# Or use the sync endpoint (waits for completion)
+curl -X POST http://localhost:3000/api/video/generate-sync \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "A timelapse of clouds moving"}' \
+  --output video.mp4
+```
+
+## API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/image/generate` | POST | Generate image from text |
+| `/api/image/transform` | POST | Transform image with prompt |
+| `/api/video/generate` | POST | Submit video generation job |
+| `/api/video/status/:id` | GET | Check video job status |
+| `/api/video/result/:id` | GET | Get completed video |
+| `/api/video/generate-sync` | POST | Generate video (waits for completion) |

examples/express-api/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "@example/express-api",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "tsx watch src/server.ts",
+		"start": "tsx src/server.ts"
+	},
+	"dependencies": {
+		"@decartai/sdk": "workspace:*",
+		"dotenv": "^16.4.0",
+		"express": "^4.21.0"
+	},
+	"devDependencies": {
+		"@types/express": "^4.17.0",
+		"@types/node": "^22.0.0",
+		"tsx": "^4.19.0",
+		"typescript": "^5.8.0"
+	}
+}