Node.js SDK

This page is a hand-authored snapshot of the planned public surface. The final reference will be generated from the SDK source.

Installation

npm install iii-sdk

Common methods

`registerWorker`

Connect a worker to a running iii engine and return its handle.

function registerWorker(address: string, options?: InitOptions): ISdk;

Pass the engine’s SDK WebSocket URL (e.g. process.env.III_URL) as address. options configures worker identity (workerName, plus an optional workerDescription, a one-line summary surfaced in engine::workers::list / engine::workers::info), timeouts, reconnection, and OpenTelemetry. The returned ISdk carries every method below.

`registerFunction`

worker.registerFunction(
  functionId: string,
  handlerOrInvocation: RemoteFunctionHandler | HttpInvocationConfig,
  options?: RegisterFunctionOptions,
): FunctionRef;

options accepts description, metadata, and optional request_format / response_format JSON Schemas (stored alongside the function for the iii console and agent-readable skills).

`registerTrigger`

Bind a registered function to a configured trigger instance.

worker.registerTrigger(trigger: RegisterTriggerInput): Trigger;

The returned Trigger carries the runtime handle. Drop the trigger with Trigger.unregister(); there is no top-level unregisterTrigger function.

`registerTriggerType`

Declare a new trigger type that this worker advertises so other workers can bind their functions to it.

worker.registerTriggerType<TConfig>(
  triggerType: RegisterTriggerTypeInput,
  handler: TriggerHandler<TConfig>,
): TriggerTypeRef<TConfig>;

`unregisterTriggerType`

Remove a previously registered trigger type.

worker.unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;

`trigger`

Invoke a registered function. Resolves with the function’s return value for synchronous calls, with an EnqueueResult for TriggerAction.Enqueue actions, and with undefined for TriggerAction.Void.

worker.trigger<TInput, TOutput>(request: TriggerRequest<TInput>): Promise<TOutput>;

`shutdown`

Disconnect from the engine and release resources, flushing any pending observability data.

worker.shutdown(): Promise<void>;

Trigger actions

TriggerAction is a runtime const that produces the value passed to trigger’s action field.

TriggerAction.Void();                       // fire-and-forget
TriggerAction.Enqueue({ queue: "math" });   // route through iii-queue

The underlying type is the discriminated union { type: "enqueue"; queue: string } | { type: "void" }.

Error type

IIIInvocationError extends Error. Every failure that crosses the SDK boundary is thrown as an instance of this class with a code: string, a message: string, an optional function_id, and an optional stacktrace.

class IIIInvocationError extends Error {
  code: string;
  message: string;
  function_id?: string;
  stacktrace?: string;
}

Common code values come from the engine: invocation_failed (handler threw), invocation_stopped (engine timeout), function_not_found, function_not_invokable, TIMEOUT (client-side timeout), FORBIDDEN (RBAC denial).

Channels

ChannelReader and ChannelWriter are runtime classes wrapping the engine’s stream WebSockets. StreamChannelRef is the type passed between SDK calls to identify a channel:

type StreamChannelRef = {
  channel_id: string;
  access_key: string;
  direction: "read" | "write";
};

Construct each with the engine’s WS base URL and a StreamChannelRef. ChannelReader exposes a Node Readable plus .sendMessage() and .onMessage(); ChannelWriter exposes a Writable plus .sendMessage(), .sendChunked(), and .close().

Logger

Logger is a runtime class with info, warn, error, and debug methods, each (message: string, data?: unknown) => void. Import it from @iii-dev/observability; it is no longer re-exported from iii-sdk. The output integrates with the SDK’s OpenTelemetry setup; see iii-observability for the export side.

Info types

The SDK re-exports the structured types the engine returns when listing system state:

FunctionInfo. function_id, optional description, optional request_format / response_format, optional metadata.
TriggerInfo. id, trigger_type, function_id, optional config, optional metadata.
WorkerInfo. id, name, optional description (the worker’s self-reported one-line summary; every engine builtin ships one), runtime/version/OS fields, IP, status, connected_at_ms, function_count, registered functions, active_invocations, optional isolation.

WorkerMetadata is not part of this SDK; use WorkerInfo for worker-side metadata.

MessageType

MessageType is a runtime enum naming every wire frame the SDK exchanges with the engine (RegisterFunction, InvokeFunction, InvocationResult, RegisterTrigger, WorkerRegistered, and the rest). Callers rarely use it directly; it surfaces in middleware hooks and protocol-level custom code.

Connection state

The connection-state literal union ("disconnected" | "connecting" | "connected" | "reconnecting" | "failed") is internal in the current build. Treat the connection as established once registerWorker returns; failures raise on the first SDK call.

Engine protocol

Language SDKs

Node.js SDK

Installation

Common methods

`registerWorker`

`registerFunction`

`registerTrigger`

`registerTriggerType`

`unregisterTriggerType`

`trigger`

`shutdown`

Trigger actions

Error type

Channels

Logger

Info types

MessageType

Connection state

​Installation

​Common methods

​registerWorker

​registerFunction

​registerTrigger

​registerTriggerType

​unregisterTriggerType

​trigger

​shutdown

​Trigger actions

​Error type

​Channels

​Logger

​Info types

​MessageType

​Connection state

Installation

Common methods

`registerWorker`

`registerFunction`

`registerTrigger`

`registerTriggerType`

`unregisterTriggerType`

`trigger`

`shutdown`

Trigger actions

Error type

Channels

Logger

Info types

MessageType

Connection state