Skip to main content
@nika-open/nika runs .nika workflows from your application and proves what they did. Your product owns the request, the interface and the business state. The Nika engine owns parsing, admission, execution, policy, events, receipts and traces, and the engine comes inside the npm package.
The first integration is two calls, admit and settle:
run() admits the workflow before it returns: a file the engine refuses throws a typed NikaOperationError, and no handle is ever handed out. result() is the one settlement: an admitted workflow that fails resolves as status: 'failed' data, not a throw. The quickstart runs this end to end in five minutes.

Two doors, one client

Omit url for the local transport. Supply url and token for HTTP. On a server, a served name such as workflows/release.nika (the workflow’s path from the server’s project root) needs no local engine or file; an explicit local path such as ./release.nika uses a compatible local engine to capture an immutable snapshot first. How the SDK works compares the two doors line by line.

An illustration of the two doors, with captured content. new Nika() starts the bundled engine as a child process, and new Nika({ url, token }) reaches nika serve with the same methods and other options. Two lines of demo.mts, the quick start in the package README, change between them: line 3, the constructor, takes url, token and allowInsecureHttp: true, which a plain http:// URL to a loopback host needs, and line 6, the run options, takes an idempotencyKey in place of maxCostUsd, which a server run refuses. The engine checks before anything runs: it refuses list-files.nika with NIKA-SEC-004, so no run exists, and runs hello.nika. The app reads six events from the local engine or two from the server, the run’s record is sealed, traceVerify(receipt) answers verified locally and sealed from the server, and one changed byte makes the verifier report BROKEN at line 5. An illustration: every code line, event, verdict, hash and version on screen was captured from @supernovae-st/nika 0.123.0, its bundled engine nika 0.123.0 (0bfde3765) and nika serve 0.123.0 in a mock/echo rehearsal; the cards, lanes, packets and pacing are drawn, and a real run takes milliseconds.

One lifecycle vocabulary

run() returns a handle only after admission; the handle is not a result. Events are optional to render; run.result() is the run’s one ending, including a pause at a human gate. Locally, a paused run resumes from the command line; nika serve 0.124.3 has no route to answer the gate. Configuration, compatibility, transport and protocol failures throw typed errors.
nika.events(run), nika.cancel(run), nika.status(run) and run.done remain as deprecated aliases. run.done is the same promise as run.result(). New code should call the methods on the run handle: run.events(), run.result(), run.cancel(), run.status().

Documentation map

How it works

The two doors, the run lifecycle and who owns what.

Start

Install the published package and complete one typed, verified run.

Project

nika.yaml, arm policy, precedence and runtime state.

Local API

Check, run, observe, cancel and compile through the bundled engine.

Runtime

Results, events, errors, receipts, spend caps and permits.

Remote API

Authenticated jobs, recovery, SSE, workflows and schedules on nika serve.

Operations

CI admission, resident serving, OS schedulers and security.

Reference

Constructor, methods, errors and exported types.

Authority boundary

  • The SDK does not parse a second Nika language.
  • It does not reconstruct traces or receipts in TypeScript.
  • An observer AbortSignal does not cancel a run; call run.cancel().
  • It does not infer success from an event kind.
  • It exposes only the routes the released server answers.

Version and channel

Live project control plane. The released engine discovers nika.yaml from the working directory toward its ancestors. The file is optional when built-in defaults are enough. Its project-shape grammar is closed: nika · ceiling · arm · traces · registry. Direct runs and the cadence path (nika arm · nika serve) read the same file.

Review the published source

The source of the published SDK release and its engine payloads.