npm package: @pixeldojo/sdk
Description: TypeScript SDK for the PixelDojo image and video generation API
Latest version: 0.1.0

# @pixeldojo/sdk

TypeScript SDK for the [PixelDojo](https://pixeldojo.ai) image and video generation API.

## Install

```bash
npm install @pixeldojo/sdk
```

## Quick Start

```typescript
import { PixelDojoClient } from '@pixeldojo/sdk';

const pd = new PixelDojoClient({ apiKey: 'pd_your_api_key' });

// Generate an image and wait for the result
const job = await pd.generate('flux-1.1-pro', {
  prompt: 'A fantasy castle on a cliff at sunset',
  aspect_ratio: '16:9',
});

console.log(job.assets[0].url);
```

## Usage

### List available models

```typescript
const { models } = await pd.listModels();
const imageModels = await pd.listModels({ modality: 'image' });
```

### Get model schema

```typescript
const schema = await pd.getModelSchema('flux-1.1-pro');
console.log(schema.schema); // JSON Schema for the request body
```

### Submit a job (async)

```typescript
const submitted = await pd.run('flux-1.1-pro', {
  prompt: 'A sunset over the ocean',
  aspect_ratio: '1:1',
  webhook_url: 'https://example.com/webhook',
});

console.log(submitted.jobId);     // "job_abc123"
console.log(submitted.statusUrl); // poll URL
```

### Poll for results

```typescript
const job = await pd.getJob('job_abc123');

if (job.status === 'completed') {
  console.log(job.output?.images);
  console.log(job.assets);
}
```

### Generate and wait (convenience)

```typescript
const job = await pd.generate('wan-2.6-video', {
  prompt: 'Drone flight through coastal cliffs',
  duration: 6,
  aspect_ratio: '16:9',
}, {
  intervalMs: 3000,
  timeoutMs: 120_000,
  onStatusChange: (j) => console.log(`Status: ${j.status}`),
});
```

### List recent jobs

```typescript
const { jobs } = await pd.listJobs({ limit: 10, status: 'completed' });
```

### Webhooks

```typescript
// Check webhook delivery state
const state = await pd.getWebhookState('job_abc123');

// Replay a webhook for a completed/failed job
const replay = await pd.replayWebhook('job_abc123');
```

## Error Handling

```typescript
import {
  PixelDojoClient,
  InsufficientCreditsError,
  NotFoundError,
  TimeoutError,
} from '@pixeldojo/sdk';

try {
  const job = await pd.generate('flux-1.1-pro', { prompt: 'Hello' });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log(`Need ${err.required} credits, have ${err.available}`);
  } else if (err instanceof NotFoundError) {
    console.log('Model not found');
  } else if (err instanceof TimeoutError) {
    console.log(`Job ${err.jobId} timed out — you can still poll manually`);
  }
}
```

## Configuration

```typescript
const pd = new PixelDojoClient({
  apiKey: 'pd_your_api_key',
  baseUrl: 'https://pixeldojo.ai',  // default
  fetch: customFetchFn,              // optional, for testing or custom runtimes
});
```

## API Reference

| Method | Description |
|--------|-------------|
| `listModels(options?)` | List all available models |
| `getModel(apiId)` | Get model details including schema |
| `getModelSchema(apiId)` | Get the JSON Schema for a model's request body |
| `run(apiId, input)` | Submit a generation job (returns immediately) |
| `getJob(jobId)` | Poll a job's status and results |
| `listJobs(options?)` | List recent jobs for your API key |
| `getWebhookState(jobId)` | Inspect webhook delivery status |
| `replayWebhook(jobId)` | Replay webhook for completed/failed jobs |
| `generate(apiId, input, options?)` | Submit + poll until complete |

## License

MIT