iii-node-sdk

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

Quality

73%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/iii-node-sdk/SKILL.md

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.

Repository: iii-hq/iii
Commit: a7ebbbb

Last updated: 5 days ago
Created: 5 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.