Sdk Reference

<!-- generated by iii-skill-render. DO NOT EDIT (changes here are overwritten on the next render). Edit docs/0-17-0/sdk-reference/node-sdk.mdx. -->

# Node.js SDK


{/* TODO: Re-link worker references to https://workers.iii.dev/workers/<name> once the Worker Docs migration ships. */}

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

## Installation

```bash
npm install iii-sdk
```

## Common methods

### `registerWorker`

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

```typescript
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, timeouts, reconnection, and OpenTelemetry. The returned `ISdk` carries every
method below.

### `registerFunction`

Register a callable function on this worker.

```typescript
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.

```typescript
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.

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

### `unregisterTriggerType`

Remove a previously registered trigger type.

```typescript
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`.

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

### `shutdown`

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

```typescript
worker.shutdown(): Promise<void>;
```

## Trigger actions

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

```typescript
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" }`,
exported as `TriggerActionType`.

## 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`.

```typescript
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:

```typescript
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`. 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`, 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.