iii-node-sdk

name	iii-node-sdk
description	Node.js/TypeScript SDK for the iii engine. Use when building workers, registering functions, or invoking triggers in TypeScript or JavaScript.

Node.js SDK

The TypeScript/JavaScript SDK for connecting Node workers to the iii engine.

Documentation

Full API reference: https://iii.dev/docs/api-reference/sdk-node

Install

npm install iii-sdk

Key APIs

API	Purpose
registerWorker(url, options?)	Connect to the engine and return the iii client
InitOptions	Worker name, metrics, headers, reconnect, OpenTelemetry
iii.registerFunction(id, handler, options?)	Register a local async function handler
iii.registerFunction(id, HttpInvocationConfig, options?)	Register an external HTTP endpoint as a function
iii.registerTrigger({ type, function_id, config, metadata? })	Bind a trigger to a function
iii.trigger({ function_id, payload, action?, timeoutMs? })	Invoke a function
TriggerAction.Void()	Fire-and-forget invocation mode
TriggerAction.Enqueue({ queue })	Durable async invocation mode
iii.createChannel(bufferSize?)	Binary/text streaming between workers
ChannelReader / ChannelWriter	Consume/write channel payloads
Logger	Structured logs with OpenTelemetry fallback
withSpan	OpenTelemetry custom spans
IIIInvocationError	Remote invocation error with code and function_id
iii.registerTriggerType({ id, description }, handler)	Custom trigger type registration

InitOptions

registerWorker(address, options?) supports:

• workerName
• enableMetricsReporting
• invocationTimeoutMs
• reconnectionConfig (initialDelayMs, maxDelayMs, backoffMultiplier, jitterFactor, maxRetries)
• headers
• otel

Use headers only for server-side Node workers. Browser workers cannot send custom WebSocket headers.

Functions and Metadata

• Local handler: iii.registerFunction('orders::validate', async (payload) => result, { description, metadata, request_format, response_format })
• HTTP-invoked handler: iii.registerFunction('legacy::charge', { url, method, timeout_ms, headers, auth }, options?)
• metadata is discoverable through engine function listings and should contain stable ownership or capability data, not secrets.
• HTTP auth supports { type: 'hmac', secret_key }, { type: 'bearer', token_key }, and { type: 'api_key', header, value_key }.

Trigger Actions and Errors

• Default trigger() waits for the result and rejects on handler/engine errors.
• TriggerAction.Void() returns undefined after dispatch; use only for optional side effects.
• TriggerAction.Enqueue({ queue }) returns { messageReceiptId } after the job is accepted.
• timeoutMs overrides the invocation timeout for a single call.
• Catch IIIInvocationError; inspect error.code for FORBIDDEN, TIMEOUT, function_not_found, function_not_invokable, invocation_failed, and invocation_stopped.

Channels

• const channel = await iii.createChannel()
• Pass channel.readerRef or channel.writerRef through a trigger() payload.
• Write binary chunks with channel.writer.stream.write(buffer) or text messages with channel.writer.sendMessage(text).
• Read binary data with reader.stream, reader.readAll(), and text messages with reader.onMessage(callback).

RBAC Auth Result Fields

When implementing an auth function for RBAC workers, the AuthResult supports:

Field	Purpose
allowed_functions: string[]	Additional function IDs to allow
forbidden_functions: string[]	Function IDs to deny (overrides expose_functions)
allowed_trigger_types?: string[]	Trigger types the worker may register
allow_trigger_type_registration	Whether the worker can register new trigger types
function_registration_prefix?	Prefix applied to functions registered by worker
context: Record<string, unknown>	Arbitrary context forwarded to middleware/handlers

Browser SDK

For browser environments, use iii-browser-sdk. It has browser-specific security and WebSocket constraints; see iii-browser-sdk for details.

Pattern Boundaries

• For usage patterns and working examples, see iii-functions-and-triggers
• For HTTP endpoint patterns, see iii-http-endpoints
• For HTTP middleware patterns, see iii-http-middleware
• For browser-side usage, see iii-browser-sdk
• For channels, see iii-channels
• For errors, see iii-error-handling
• For Python SDK, see iii-python-sdk
• For Rust SDK, see iii-rust-sdk

When to Use

• Use this skill when the task is primarily about iii-node-sdk in the iii engine.
• Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

• Never use this skill as a generic fallback for unrelated tasks.
• You must not apply this skill when a more specific iii skill is a better fit.
• Always verify environment and safety constraints before applying examples from this skill.