Skip to main content

Documentation Index

Fetch the complete documentation index at: https://iii.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
registerFunction

Register a callable function on this worker. 
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" }, 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. 
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. 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.