@supernovae-st/nika-client

TypeScript client for the Nika workflow engine HTTP API (nika serve).

• Zero runtime dependencies (uses native fetch)
• Full TypeScript types aligned with nika serve OpenAPI 3.1 spec
• Namespace pattern: nika.jobs.*, nika.workflows.*
• 6 typed error classes with full hierarchy
• Automatic retry on 429/5xx with exponential backoff
• Client-side concurrency limiter (semaphore, default: 24)
• SSE streaming via AsyncIterable with idle timeout + auto-reconnect
• Binary artifact download (Uint8Array) + streaming (ReadableStream)
• Auto-paginating workflow listing
• AbortSignal support on long-running operations
• Webhook HMAC-SHA256 verification (async, Web Crypto API)
• Dual CJS/ESM build
• Node.js 18+

Install

npm install @supernovae-st/nika-client

Quick start

import { Nika } from '@supernovae-st/nika-client';

const nika = new Nika({
  url: 'http://localhost:3000',
  token: process.env.NIKA_TOKEN!,
});

// Submit + poll until done
const job = await nika.jobs.run('translate.nika.yaml', {
  file: 'ui.json',
  locale: 'fr_FR',
});
console.log(job.status); // 'completed'

Usage

Run a workflow and wait for completion

const job = await nika.jobs.run('pipeline.nika.yaml', { topic: 'AI' });
console.log(job.status);       // 'completed'
console.log(job.exit_code);    // 0
console.log(job.completed_at); // '2026-04-02T10:01:00Z'

Stream events in real time (SSE)

const { job_id } = await nika.jobs.submit('pipeline.nika.yaml', { topic: 'AI' });

for await (const event of nika.jobs.stream(job_id)) {
  console.log(event.type, event.task_id ?? '', event.duration_ms ?? '');
  // started
  // task_start research infer
  // task_complete research 1200
  // completed
}

Run and collect all artifacts

const artifacts = await nika.jobs.runAndCollect('research.nika.yaml', {
  topic: 'workflow engines',
});

console.log(artifacts['report.md']);   // markdown string
console.log(artifacts['data.json']);   // parsed JSON object
// binary artifacts (audio, images) are skipped

Download binary artifacts

const bytes = await nika.jobs.artifactBinary('job-id', 'audio.mp3');
// bytes is Uint8Array

Stream large artifacts without loading into memory

import * as fs from 'node:fs';

const stream = await nika.jobs.artifactStream('job-id', 'dataset.csv');
const writer = fs.createWriteStream('output.csv');
for await (const chunk of stream) {
  writer.write(chunk);
}
writer.end();

Paginate workflow listing

// Auto-pagination (default) — fetches all pages transparently
const all = await nika.workflows.list();

// Manual pagination for large lists
const page1 = await nika.workflows.listPage({ limit: 50 });
if (page1.has_more) {
  const last = page1.workflows[page1.workflows.length - 1].name;
  const page2 = await nika.workflows.listPage({ limit: 50, after: last });
}

Cancel a running job with AbortSignal

const controller = new AbortController();
setTimeout(() => controller.abort(), 60_000);

const job = await nika.jobs.run('slow.nika.yaml', {}, {
  signal: controller.signal,
});

Custom fetch (logging middleware)

const nika = new Nika({
  url: 'http://localhost:3000',
  token: process.env.NIKA_TOKEN!,
  fetch: async (url, init) => {
    console.log(`>> ${init?.method ?? 'GET'} ${url}`);
    const res = await fetch(url, init);
    console.log(`<< ${res.status}`);
    return res;
  },
});

Webhook verification

import { Nika } from '@supernovae-st/nika-client';

// Stripe-style HMAC-SHA256 verification (async — uses Web Crypto API)
// Works in Node.js 18+, Deno, Cloudflare Workers, and Bun.
const isValid = await Nika.verifyWebhook(
  rawBody,
  signatureHeader, // 't=1234567890,v1=abc123...'
  webhookSecret,
);

Configuration

new Nika(config)

Option	Type	Default	Description
url	string	(required)	nika serve URL (http/https)
token	string	(required)	Bearer token (NIKA_SERVE_TOKEN)
timeout	number	30000	HTTP request timeout in ms
retries	number	2	Retries on 429/5xx
concurrency	number	24	Max concurrent HTTP requests
pollInterval	number	2000	Initial poll interval in ms
pollTimeout	number	300000	Max poll duration in ms
pollBackoff	number	1.5	Poll backoff multiplier
fetch	typeof fetch	globalThis.fetch	Custom fetch function
logger	NikaLogger	(none)	Logger interface (debug, info, warn, error)

API reference

Jobs — nika.jobs.*

Method	Returns	Description
submit(workflow, inputs?, opts?)	RunResponse	Submit workflow, return { job_id, status }
status(jobId)	NikaJob	Get job status
cancel(jobId)	CancelResponse	Cancel a running job
run(workflow, inputs?, opts?)	NikaJob	Submit + poll until terminal state
stream(jobId, opts?)	AsyncIterable<NikaEvent>	SSE event stream
artifacts(jobId)	NikaArtifact[]	List job artifacts
artifact(jobId, name)	string	Download artifact as text
artifactJson<T>(jobId, name)	T	Download artifact as parsed JSON
artifactBinary(jobId, name)	Uint8Array	Download artifact as raw bytes
artifactStream(jobId, name)	ReadableStream<Uint8Array>	Stream artifact (for large files)
runAndCollect(workflow, inputs?, opts?)	Record<string, unknown>	Run + collect all non-binary artifacts

Workflows — nika.workflows.*

Method	Returns	Description
list()	WorkflowInfo[]	List all workflows (auto-paginates)
listPage(opts?)	ListWorkflowsResponse	List single page (manual pagination)
reload()	WorkflowInfo[]	Rescan workflows directory
source(name)	string	Get raw YAML source

System

Method	Returns	Description
nika.health()	HealthResponse	Health check (no auth required)
Nika.verifyWebhook(body, sig, secret)	boolean	Static: verify webhook HMAC-SHA256

Error classes

All SDK errors extend NikaError. Catch it to handle any SDK error:

NikaError (base)
├── NikaAPIError        — HTTP errors (status, body, requestId)
├── NikaConnectionError — Network errors (DNS, TCP, abort)
├── NikaTimeoutError    — Request or poll timeout
└── NikaJobError        — Job failed (exitCode, job object)
    └── NikaJobCancelledError — Job was cancelled

import { NikaError, NikaAPIError, NikaJobError } from '@supernovae-st/nika-client';

try {
  await nika.jobs.run('pipeline.nika.yaml');
} catch (err) {
  if (err instanceof NikaJobError) {
    console.error('Job failed:', err.job.output, 'exit:', err.exitCode);
  } else if (err instanceof NikaAPIError) {
    console.error('HTTP error:', err.status, err.body);
  } else if (err instanceof NikaError) {
    console.error('SDK error:', err.message);
  }
}

SSE event types

Type	Fields	Terminal
started	job_id	No
task_start	job_id, task_id, verb	No
task_complete	job_id, task_id, duration_ms	No
task_failed	job_id, task_id, error, duration_ms	No
artifact_written	job_id, task_id, path, size	No
completed	job_id, output?	Yes
failed	job_id, error?	Yes
cancelled	job_id	Yes

Terminal events close the SSE stream automatically.

The SDK auto-reconnects on stream drops (up to 3 attempts), using the Last-Event-Id header to resume without losing events. Configure via StreamOptions:

for await (const event of nika.jobs.stream(jobId, {
  maxReconnects: 5,
  reconnectDelay: 2000,
  idleTimeout: 120_000,
})) {
  // events are guaranteed in order, even across reconnects
}

License

AGPL-3.0-or-later