Node.js SDK

npm install @seenn/node

# yarn
yarn add @seenn/node

# pnpm
pnpm add @seenn/node

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

const seenn = new SeennClient({
  apiKey: process.env.SEENN_SECRET_KEY,
  debug: process.env.NODE_ENV === 'development',
});

const job = await seenn.jobs.start({
  userId: 'user_123',
  jobType: 'video-generation',
  title: 'Creating your video...',
  workflowId: 'sora-v2',        // Track ETAs per model
  estimatedDuration: 120000,   // 2 min default
  metadata: {
    prompt: 'A cat playing piano',
    quality: 'high',
  },
  stage: {
    name: 'initializing',
    current: 1,
    total: 3,
  },
});

console.log(job.id);  // '01HXYZ...'
console.log(job.estimatedCompletionAt);  // '2026-01-23T14:32:00Z'

// In a worker process
const job = await seenn.jobs.get('job_abc123');

console.log(job.status);    // 'running'
console.log(job.progress);  // 25

const { jobs, nextCursor } = await seenn.jobs.list('user_123', {
  limit: 10,
});

for (const job of jobs) {
  console.log(job.title, job.status);
}

// Fetch next page
if (nextCursor) {
  const nextPage = await seenn.jobs.list('user_123', { cursor: nextCursor });
}

const parent = await seenn.jobs.createParent({
  userId: 'user_123',
  jobType: 'batch-processing',
  title: 'Christmas Image Pack (5 images)',
  childCount: 5,
  childProgressMode: 'average',
});

console.log(parent.isParent);  // true
console.log(parent.children);   // { total: 5, completed: 0, ... }

const child = await seenn.jobs.createChild({
  parentJobId: parent.id,
  childIndex: 0,
  userId: 'user_123',
  jobType: 'image-generation',
  title: 'Snowflake Image',
});

console.log(child.isChild);  // true
console.log(child.parent);   // { parentJobId: '...', childIndex: 0 }

// Update child progress - parent auto-updates!
await child.setProgress(50);
await child.complete();

// 1. Create batch job (parent + 5 children)
const { parent, children } = await seenn.jobs.createBatch({
  userId: 'user_123',
  jobType: 'image-pack',
  parentTitle: 'Christmas Pack (5 images)',
  childTitles: [
    'Snowflake',
    'Christmas Tree',
    'Santa Claus',
    'Reindeer',
    'Gift Box',
  ],
  childProgressMode: 'average',
  metadata: { packId: 'christmas-2026', style: 'watercolor' },
});

console.log('Parent ID:', parent.id);          // '01HXY...'
console.log('Children:', children.length);     // 5
console.log('Parent status:', parent.status); // 'pending'

// 2. Process children in parallel with your AI model
await Promise.all(children.map(async (child, index) => {
  try {
    // Update progress as AI processes
    await child.setProgress(10, { message: 'Starting generation...' });

    // Call your AI model
    const imageUrl = await generateImage(child.title, {
      onProgress: (pct) => child.setProgress(pct),
    });

    // Complete with result URL
    await child.complete({
      result: { type: 'image', url: imageUrl },
      message: 'Image ready!',
    });
  } catch (error) {
    // Fail individual child - parent continues!
    await child.fail({
      error: { code: 'GENERATION_FAILED', message: error.message },
      retryable: true,
    });
  }
}));

// 3. Check final results
await parent.refresh();
console.log('Parent status:', parent.status);       // 'completed' or 'failed'
console.log('Completed:', parent.children.completed); // 4
console.log('Failed:', parent.children.failed);       // 1

const { parent, children } = await seenn.jobs.getWithChildren(parentId);

console.log(parent.progress);            // 60 (average of children)
console.log(parent.childProgress);      // { completed: 3, running: 1, pending: 1, ... }

for (const child of children) {
  console.log(`Child ${child.childIndex}: ${child.status} (${child.progress}%)`);
}

// Example: 5 children, 3 at 100%, 1 at 50%, 1 at 0%
// Total progress: 100 + 100 + 100 + 50 + 0 = 350

// 'average' mode: 350 / 5 = 70%
// 'sequential' mode: 3 completed / 5 total = 60%

// After batch processing completes
const { parent, children } = await seenn.jobs.getWithChildren(parentId);

const { completed, failed, total } = parent.children;

if (parent.status === 'completed' && failed > 0) {
  // Partial success - some children failed
  console.log(`Pack completed with ${completed}/${total} images`);

  // Get successful results
  const successfulImages = children
    .filter(c => c.status === 'completed')
    .map(c => c.result?.url);

  // Get failed children for retry
  const failedChildren = children.filter(c => c.status === 'failed');
  for (const child of failedChildren) {
    console.log(`"${child.title}" failed: ${child.error?.message}`);
    // Optionally offer retry to user
  }
} else if (parent.status === 'failed') {
  // Total failure - ALL children failed
  console.log('Pack generation completely failed');
}

// Simple progress update
await job.setProgress(50);

// With message
await job.setProgress(50, { message: 'Processing frames...' });

// With stage info
await job.setProgress(66, {
  message: 'Rendering video...',
  stage: {
    name: 'rendering',
    current: 2,
    total: 3,
    description: 'Combining frames into video',
  },
});

// Fluent chaining
await job
  .setProgress(25, { message: 'Step 1...' })
  .then(j => j.setProgress(50, { message: 'Step 2...' }))
  .then(j => j.setProgress(75, { message: 'Step 3...' }));

// Simple completion
await job.complete();

// With result URL
await job.complete({
  result: {
    type: 'video',
    url: 'https://cdn.example.com/output.mp4',
  },
});

// With custom data
await job.complete({
  result: {
    type: 'analysis',
    data: {
      sentiment: 'positive',
      confidence: 0.95,
      keywords: ['happy', 'success'],
    },
  },
  message: 'Analysis complete!',
});

try {
  // Processing...
} catch (err) {
  await job.fail({
    error: {
      code: 'PROCESSING_ERROR',
      message: 'Failed to generate video',
      details: { reason: err.message },
    },
    retryable: true,
  });
}

// Different models have different processing times
const job = await seenn.jobs.start({
  userId: 'user_123',
  jobType: 'video-generation',
  workflowId: 'sora-v2',  // Track ETAs separately per model
  title: 'Creating video...',
});

// Without workflowId, jobType is used as ETA key
const job2 = await seenn.jobs.start({
  userId: 'user_123',
  jobType: 'image-upscale-4x',  // ETA tracked by jobType
  title: 'Upscaling image...',
});

// Set default ETA for new workflows (before 5 completions)
const job3 = await seenn.jobs.start({
  userId: 'user_123',
  jobType: 'video-generation',
  workflowId: 'new-model-v3',
  estimatedDuration: 180000,  // 3 min default until 5+ jobs complete
  title: 'Creating video...',
});

const job = await seenn.jobs.get('job_123');

// Get remaining time in milliseconds
console.log(job.etaRemaining);  // 45000 (45 seconds)

// Check if job is running past ETA
console.log(job.isPastEta);     // true/false

// ETA metadata
console.log(job.etaConfidence); // 0.85 (85% confidence)
console.log(job.etaBasedOn);    // 42 (based on 42 historical jobs)

// Get ETA stats for a workflow/jobType
const stats = await seenn.eta.getStats('sora-v2');  // etaKey = workflowId or jobType
console.log(stats);
// {
//   etaKey: 'sora-v2',
//   count: 156,
//   avgDuration: 120000,     // 2 minutes average
//   minDuration: 90000,      // fastest completion
//   maxDuration: 180000,     // slowest completion
//   defaultDuration: 120000, // from estimatedDuration param
//   confidence: 0.92,        // min(count/50, 1.0)
//   lastUpdated: '2026-01-23T...'
// }

// List all ETA stats
const allStats = await seenn.eta.list();

// Reset stats (e.g., after significant workflow changes)
await seenn.eta.reset('sora-v2');

const seenn = new SeennClient({
  apiKey: process.env.SEENN_SECRET_KEY,
  // Point to your own backend
  baseUrl: 'https://api.yourcompany.com',
});

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

try {
  await seenn.jobs.get('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Job not found');
  } else if (err instanceof RateLimitError) {
    console.log('Rate limited, retry after:', err.retryAfter);
  } else if (err instanceof ValidationError) {
    console.log('Invalid input:', err.message);
  }
}