@seenn/node

> Open Source Backend SDK for Job State Transport


Real-time job progress tracking for AI video generation, image processing, and long-running async tasks.

Features

- Fluent API - Chain job updates naturally
- Auto-retry - Exponential backoff with jitter
- TypeScript - Full type definitions
- Self-hosted - Use with your own backend
- Open Source - MIT License

---

Installation

``bash
npm install @seenn/node


or

yarn add @seenn/node

or

pnpm add @seenn/node
`

---

Quick Start

$3

`typescript
import { SeennClient } from '@seenn/node';

const seenn = new SeennClient({
apiKey: 'sk_live_your_api_key',
});
`

$3

`typescript
import { SeennClient } from '@seenn/node';

const seenn = new SeennClient({
apiKey: 'sk_live_your_api_key',
baseUrl: 'https://api.yourapp.com', // Your backend URL
});
`

---

Usage

$3

`typescript
const job = await seenn.jobs.start({
jobType: 'video-generation',
userId: 'user_123',
title: 'Generating video...',
metadata: { prompt: 'A cat playing piano' },
queue: { position: 5, total: 20 },
stage: { name: 'queued', current: 1, total: 4 },
});

console.log(Job started: ${job.id});
`

$3

`typescript
await job.setProgress(50, {
message: 'Rendering frames...',
stage: { name: 'render', current: 2, total: 4 },
});
`

$3

`typescript
await job.complete({
result: {
type: 'video',
url: 'https://cdn.example.com/video.mp4',
data: { duration: 30, resolution: '1080p' },
},
message: 'Video ready!',
});
`

$3

`typescript
await job.fail({
error: {
code: 'RENDER_FAILED',
message: 'GPU memory exceeded',
details: { gpuMemory: '16GB', required: '24GB' },
},
retryable: true,
});
`

$3

`typescript
// Get single job
const job = await seenn.jobs.get('job_01ABC123');
console.log(job.status, job.progress);

// List user's jobs
const { jobs, nextCursor } = await seenn.jobs.list('user_123', {
limit: 20,
});
`

---

Configuration

`typescript
const seenn = new SeennClient({
apiKey: string; // Required: sk_live_xxx or sk_test_xxx
baseUrl?: string; // Default: https://api.seenn.io
timeout?: number; // Default: 30000 (30s)
maxRetries?: number; // Default: 3
debug?: boolean; // Default: false
});
`

---

Error Handling

`typescript
import { SeennError, RateLimitError, ValidationError, NotFoundError } from '@seenn/node';

try {
await seenn.jobs.start({ ... });
} catch (error) {
if (error instanceof RateLimitError) {
console.log(Rate limited. Retry after ${error.retryAfter}s);
} else if (error instanceof ValidationError) {
console.log('Invalid input:', error.details);
} else if (error instanceof NotFoundError) {
console.log('Job not found');
} else if (error instanceof SeennError) {
console.log(Error ${error.code}: ${error.message});
}
}
`

---

Self-Hosted Requirements

To use this SDK with your own backend, implement these endpoints:

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /v1/jobs | Create a new job |
| GET | /v1/jobs/:id | Get job by ID |
| GET | /v1/jobs?userId=xxx | List user's jobs |
| POST | /v1/jobs/:id/progress | Update job progress |
| POST | /v1/jobs/:id/complete | Mark job as completed |
| POST | /v1/jobs/:id/fail` | Mark job as failed |

See Self-Hosted Guide for full API specification.

---

Links

- Documentation
- Website
- GitHub
- npm

---

License

MIT © Seenn