iii-sdk 0.8.3 → 0.9.0

package/dist/{utils-CMrMD5Ij.d.mts → utils-BRn3Iff5.d.mts}

@@ -1,9 +1,293 @@
-import { n as IStream } from "./stream-Bzpo5JNV.mjs";
-import { Context, Meter as Meter$1, Span, SpanKind as SpanKind$1, SpanStatusCode as SpanStatusCode$1, Tracer } from "@opentelemetry/api";
+import { n as IStream } from "./stream-BAjVneSg.mjs";
 import { Readable, Writable } from "node:stream";
+import { Context, Meter as Meter$1, Span, SpanKind as SpanKind$1, SpanStatusCode as SpanStatusCode$1, Tracer } from "@opentelemetry/api";
 import { Instrumentation } from "@opentelemetry/instrumentation";
 import { Logger, SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-logs";
 
+//#region src/iii-types.d.ts
+declare enum MessageType {
+  RegisterFunction = "registerfunction",
+  UnregisterFunction = "unregisterfunction",
+  RegisterService = "registerservice",
+  InvokeFunction = "invokefunction",
+  InvocationResult = "invocationresult",
+  RegisterTriggerType = "registertriggertype",
+  RegisterTrigger = "registertrigger",
+  UnregisterTrigger = "unregistertrigger",
+  UnregisterTriggerType = "unregistertriggertype",
+  TriggerRegistrationResult = "triggerregistrationresult",
+  WorkerRegistered = "workerregistered",
+}
+type RegisterTriggerTypeMessage = {
+  message_type: MessageType.RegisterTriggerType;
+  id: string;
+  description: string;
+};
+type RegisterTriggerMessage = {
+  message_type: MessageType.RegisterTrigger;
+  id: string;
+  type: string;
+  function_id: string;
+  config: unknown;
+};
+type RegisterServiceMessage = {
+  message_type: MessageType.RegisterService;
+  id: string;
+  name?: string;
+  description?: string;
+  parent_service_id?: string;
+};
+/**
+ * Authentication configuration for HTTP-invoked functions.
+ *
+ * - `hmac` -- HMAC signature verification using a shared secret.
+ * - `bearer` -- Bearer token authentication.
+ * - `api_key` -- API key sent via a custom header.
+ */
+type HttpAuthConfig = {
+  type: 'hmac';
+  secret_key: string;
+} | {
+  type: 'bearer';
+  token_key: string;
+} | {
+  type: 'api_key';
+  header: string;
+  value_key: string;
+};
+/**
+ * Configuration for registering an HTTP-invoked function (Lambda, Cloudflare
+ * Workers, etc.) instead of a local handler.
+ */
+type HttpInvocationConfig = {
+  /** URL to invoke. */
+  url: string;
+  /** HTTP method. Defaults to `POST`. */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  /** Timeout in milliseconds. */
+  timeout_ms?: number;
+  /** Custom headers to send with the request. */
+  headers?: Record<string, string>;
+  /** Authentication configuration. */
+  auth?: HttpAuthConfig;
+};
+type RegisterFunctionFormat = {
+  name: string;
+  /**
+   * The description of the parameter
+   */
+  description?: string;
+  /**
+   * The type of the parameter
+   */
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'map';
+  /**
+   * The body of the parameter
+   */
+  body?: RegisterFunctionFormat[];
+  /**
+   * The items of the parameter
+   */
+  items?: RegisterFunctionFormat;
+  /**
+   * Whether the parameter is required
+   */
+  required?: boolean;
+};
+type RegisterFunctionMessage = {
+  message_type: MessageType.RegisterFunction;
+  /**
+   * The path of the function (use :: for namespacing, e.g. external::my_lambda)
+   */
+  id: string;
+  /**
+   * The description of the function
+   */
+  description?: string;
+  /**
+   * The request format of the function
+   */
+  request_format?: RegisterFunctionFormat;
+  /**
+   * The response format of the function
+   */
+  response_format?: RegisterFunctionFormat;
+  metadata?: Record<string, unknown>;
+  /**
+   * HTTP invocation config for external HTTP functions (Lambda, Cloudflare Workers, etc.)
+   */
+  invocation?: HttpInvocationConfig;
+};
+/**
+ * Routing action for {@link TriggerRequest}. Determines how the engine
+ * handles the invocation.
+ *
+ * - `enqueue` -- Routes through a named queue for async processing.
+ * - `void` -- Fire-and-forget, no response.
+ */
+type TriggerAction = {
+  type: 'enqueue';
+  queue: string;
+} | {
+  type: 'void';
+};
+/**
+ * Result returned when a function is invoked with `TriggerAction.Enqueue`.
+ */
+type EnqueueResult = {
+  /** Unique receipt ID for the enqueued message. */
+  messageReceiptId: string;
+};
+/**
+ * Request object passed to {@link ISdk.trigger}.
+ *
+ * @typeParam TInput - Type of the payload.
+ */
+type TriggerRequest<TInput = unknown> = {
+  /** ID of the function to invoke. */
+  function_id: string;
+  /** Payload to pass to the function. */
+  payload: TInput;
+  /** Routing action. Omit for synchronous request/response. */
+  action?: TriggerAction;
+  /** Override the default invocation timeout in milliseconds. */
+  timeoutMs?: number;
+};
+/**
+ * Metadata about a registered function, returned by `ISdk.listFunctions`.
+ */
+type FunctionInfo = {
+  /** Unique function identifier. */
+  function_id: string;
+  /** Human-readable description. */
+  description?: string;
+  /** Schema describing expected request format. */
+  request_format?: RegisterFunctionFormat;
+  /** Schema describing expected response format. */
+  response_format?: RegisterFunctionFormat;
+  /** Arbitrary metadata attached to the function. */
+  metadata?: Record<string, unknown>;
+};
+/**
+ * Information about a registered trigger.
+ */
+type TriggerInfo = {
+  /** Unique trigger identifier. */
+  id: string;
+  /** Type of the trigger (e.g. `http`, `cron`, `queue`). */
+  trigger_type: string;
+  /** ID of the function this trigger is bound to. */
+  function_id: string;
+  /** Trigger-specific configuration. */
+  config?: unknown;
+};
+/** Worker connection status. */
+type WorkerStatus = 'connected' | 'available' | 'busy' | 'disconnected';
+/**
+ * Metadata about a connected worker, returned by `ISdk.listWorkers`.
+ */
+type WorkerInfo = {
+  /** Unique worker identifier assigned by the engine. */
+  id: string;
+  /** Display name of the worker. */
+  name?: string;
+  /** Runtime environment (e.g. `node`, `python`, `rust`). */
+  runtime?: string;
+  /** SDK version. */
+  version?: string;
+  /** Operating system info. */
+  os?: string;
+  /** IP address of the worker. */
+  ip_address?: string;
+  /** Current connection status. */
+  status: WorkerStatus;
+  /** Timestamp (ms since epoch) when the worker connected. */
+  connected_at_ms: number;
+  /** Number of functions registered by this worker. */
+  function_count: number;
+  /** List of function IDs registered by this worker. */
+  functions: string[];
+  /** Number of currently active invocations. */
+  active_invocations: number;
+};
+/**
+ * Serializable reference to one end of a streaming channel. Can be included
+ * in invocation payloads to pass channel endpoints between workers.
+ */
+type StreamChannelRef = {
+  /** Unique channel identifier. */
+  channel_id: string;
+  /** Access key for authentication. */
+  access_key: string;
+  /** Whether this ref is for reading or writing. */
+  direction: 'read' | 'write';
+};
+//#endregion
+//#region src/channels.d.ts
+/**
+ * Write end of a streaming channel. Provides both a Node.js `Writable` stream
+ * and a `sendMessage` method for sending structured text messages.
+ *
+ * @example
+ * ```typescript
+ * const channel = await iii.createChannel()
+ *
+ * // Stream binary data
+ * channel.writer.stream.write(Buffer.from('hello'))
+ * channel.writer.stream.end()
+ *
+ * // Or send text messages
+ * channel.writer.sendMessage(JSON.stringify({ type: 'event', data: 'test' }))
+ * channel.writer.close()
+ * ```
+ */
+declare class ChannelWriter {
+  private static readonly FRAME_SIZE;
+  private ws;
+  private wsReady;
+  private readonly pendingMessages;
+  /** Node.js Writable stream for binary data. */
+  readonly stream: Writable;
+  private readonly url;
+  constructor(engineWsBase: string, ref: StreamChannelRef);
+  private ensureConnected;
+  /** Send a text message through the channel. */
+  sendMessage(msg: string): void;
+  /** Close the channel writer. */
+  close(): void;
+  private sendChunked;
+  private sendRaw;
+}
+/**
+ * Read end of a streaming channel. Provides both a Node.js `Readable` stream
+ * for binary data and an `onMessage` callback for structured text messages.
+ *
+ * @example
+ * ```typescript
+ * const channel = await iii.createChannel()
+ *
+ * // Stream binary data
+ * channel.reader.stream.on('data', (chunk) => console.log(chunk))
+ *
+ * // Or receive text messages
+ * channel.reader.onMessage((msg) => console.log('Got:', msg))
+ * ```
+ */
+declare class ChannelReader {
+  private ws;
+  private connected;
+  private readonly messageCallbacks;
+  /** Node.js Readable stream for binary data. */
+  readonly stream: Readable;
+  private readonly url;
+  constructor(engineWsBase: string, ref: StreamChannelRef);
+  private ensureConnected;
+  /** Register a callback to receive text messages from the channel. */
+  onMessage(callback: (msg: string) => void): void;
+  readAll(): Promise<Buffer>;
+  close(): void;
+}
+//#endregion
 //#region src/iii-constants.d.ts
 /**
  * Constants for the III module.
@@ -12,6 +296,7 @@ import { Logger, SeverityNumber as SeverityNumber$1 } from "@opentelemetry/api-l
 declare const EngineFunctions: {
   readonly LIST_FUNCTIONS: "engine::functions::list";
   readonly LIST_WORKERS: "engine::workers::list";
+  readonly LIST_TRIGGERS: "engine::triggers::list";
   readonly REGISTER_WORKER: "engine::workers::register";
 };
 /** Engine trigger types */
@@ -72,7 +357,7 @@ interface OtelConfig {
   serviceNamespace?: string;
   /** The service instance ID to report. Defaults to SERVICE_INSTANCE_ID env var or auto-generated UUID. */
   serviceInstanceId?: string;
-  /** III Engine WebSocket URL. Defaults to III_BRIDGE_URL or "ws://localhost:49134". */
+  /** III Engine WebSocket URL. Defaults to III_URL or "ws://localhost:49134". */
   engineWsUrl?: string;
   /** OpenTelemetry instrumentations to register (e.g., PrismaInstrumentation). */
   instrumentations?: Instrumentation[];
@@ -166,162 +451,60 @@ declare function withSpan<T>(name: string, options: {
   traceparent?: string;
 }, fn: (span: Span) => Promise<T>): Promise<T>;
 //#endregion
-//#region src/iii-types.d.ts
-declare enum MessageType {
-  RegisterFunction = "registerfunction",
-  UnregisterFunction = "unregisterfunction",
-  RegisterService = "registerservice",
-  InvokeFunction = "invokefunction",
-  InvocationResult = "invocationresult",
-  RegisterTriggerType = "registertriggertype",
-  RegisterTrigger = "registertrigger",
-  UnregisterTrigger = "unregistertrigger",
-  UnregisterTriggerType = "unregistertriggertype",
-  TriggerRegistrationResult = "triggerregistrationresult",
-  WorkerRegistered = "workerregistered",
-}
-type RegisterTriggerTypeMessage = {
-  message_type: MessageType.RegisterTriggerType;
-  id: string;
-  description: string;
-};
-type RegisterTriggerMessage = {
-  message_type: MessageType.RegisterTrigger;
-  id: string;
-  type: string;
-  function_id: string;
-  config: unknown;
-};
-type HttpAuthConfig = {
-  type: 'hmac';
-  secret_key: string;
-} | {
-  type: 'bearer';
-  token_key: string;
-} | {
-  type: 'api_key';
-  header: string;
-  value_key: string;
-};
-type HttpInvocationConfig = {
-  url: string;
-  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-  timeout_ms?: number;
-  headers?: Record<string, string>;
-  auth?: HttpAuthConfig;
-};
-type RegisterFunctionFormat = {
-  name: string;
-  /**
-   * The description of the parameter
-   */
-  description?: string;
-  /**
-   * The type of the parameter
-   */
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'map';
-  /**
-   * The body of the parameter
-   */
-  body?: RegisterFunctionFormat[];
-  /**
-   * The items of the parameter
-   */
-  items?: RegisterFunctionFormat;
-  /**
-   * Whether the parameter is required
-   */
-  required?: boolean;
-};
-type RegisterFunctionMessage = {
-  message_type: MessageType.RegisterFunction;
-  /**
-   * The path of the function (use :: for namespacing, e.g. external::my_lambda)
-   */
-  id: string;
-  /**
-   * The description of the function
-   */
-  description?: string;
-  /**
-   * The request format of the function
-   */
-  request_format?: RegisterFunctionFormat;
-  /**
-   * The response format of the function
-   */
-  response_format?: RegisterFunctionFormat;
-  metadata?: Record<string, unknown>;
-  /**
-   * HTTP invocation config for external HTTP functions (Lambda, Cloudflare Workers, etc.)
-   */
-  invocation?: HttpInvocationConfig;
-};
-type FunctionInfo = {
-  function_id: string;
-  description?: string;
-  request_format?: RegisterFunctionFormat;
-  response_format?: RegisterFunctionFormat;
-  metadata?: Record<string, unknown>;
-};
-type WorkerStatus = 'connected' | 'available' | 'busy' | 'disconnected';
-type WorkerInfo = {
-  id: string;
-  name?: string;
-  runtime?: string;
-  version?: string;
-  os?: string;
-  ip_address?: string;
-  status: WorkerStatus;
-  connected_at_ms: number;
-  function_count: number;
-  functions: string[];
-  active_invocations: number;
-};
-type StreamChannelRef = {
-  channel_id: string;
-  access_key: string;
-  direction: 'read' | 'write';
-};
-//#endregion
 //#region src/triggers.d.ts
+/**
+ * Configuration passed to a trigger handler when a trigger instance is
+ * registered or unregistered.
+ *
+ * @typeParam TConfig - Type of the trigger-specific configuration.
+ */
 type TriggerConfig<TConfig> = {
+  /** Trigger instance ID. */
   id: string;
+  /** Function to invoke when the trigger fires. */
   function_id: string;
+  /** Trigger-specific configuration. */
   config: TConfig;
 };
+/**
+ * Handler interface for custom trigger types. Passed to
+ * `ISdk.registerTriggerType`.
+ *
+ * @typeParam TConfig - Type of the trigger-specific configuration.
+ *
+ * @example
+ * ```typescript
+ * const handler: TriggerHandler<{ interval: number }> = {
+ *   async registerTrigger({ id, function_id, config }) {
+ *     // Set up periodic invocation
+ *   },
+ *   async unregisterTrigger({ id, function_id, config }) {
+ *     // Clean up
+ *   },
+ * }
+ * ```
+ */
 type TriggerHandler<TConfig> = {
+  /** Called when a trigger instance is registered. */
   registerTrigger(config: TriggerConfig<TConfig>): Promise<void>;
+  /** Called when a trigger instance is unregistered. */
   unregisterTrigger(config: TriggerConfig<TConfig>): Promise<void>;
 };
 //#endregion
-//#region src/channels.d.ts
-declare class ChannelWriter {
-  private static readonly FRAME_SIZE;
-  private ws;
-  private wsReady;
-  private readonly pendingMessages;
-  readonly stream: Writable;
-  private readonly url;
-  constructor(engineWsBase: string, ref: StreamChannelRef);
-  private ensureConnected;
-  sendMessage(msg: string): void;
-  close(): void;
-  private sendChunked;
-  private sendRaw;
-}
-declare class ChannelReader {
-  private ws;
-  private connected;
-  private readonly messageCallbacks;
-  readonly stream: Readable;
-  private readonly url;
-  constructor(engineWsBase: string, ref: StreamChannelRef);
-  private ensureConnected;
-  onMessage(callback: (msg: string) => void): void;
-}
-//#endregion
 //#region src/types.d.ts
+/**
+ * Async function handler for a registered function. Receives the invocation
+ * payload and returns the result.
+ *
+ * @typeParam TInput - Type of the invocation payload.
+ * @typeParam TOutput - Type of the return value.
+ *
+ * @example
+ * ```typescript
+ * const handler: RemoteFunctionHandler<{ name: string }, { message: string }> =
+ *   async (data) => ({ message: `Hello, ${data.name}!` })
+ * ```
+ */
 type RemoteFunctionHandler<TInput = any, TOutput = any> = (data: TInput) => Promise<TOutput>;
 /** OTEL Log Event from the engine */
 type OtelLogEvent = {
@@ -350,16 +533,8 @@ type OtelLogEvent = {
   /** Instrumentation scope version (if available) */
   instrumentation_scope_version?: string;
 };
-/** Severity levels for log filtering */
-type LogSeverityLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'all';
-/** Optional configuration for onLog */
-type LogConfig = {
-  /** Minimum severity level to receive (default: 'all') */
-  level?: LogSeverityLevel;
-};
-/** Callback type for log events */
-type LogCallback = (log: OtelLogEvent) => void;
 type RegisterTriggerInput = Omit<RegisterTriggerMessage, 'message_type' | 'id'>;
+type RegisterServiceInput = Omit<RegisterServiceMessage, 'message_type'>;
 type RegisterFunctionInput = Omit<RegisterFunctionMessage, 'message_type'>;
 type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, 'message_type'>;
 type FunctionsAvailableCallback = (functions: FunctionInfo[]) => void;
@@ -368,55 +543,148 @@ interface ISdk {
    * Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.
    * @param trigger - The trigger to register
    * @returns A trigger object that can be used to unregister the trigger
+   *
+   * @example
+   * ```typescript
+   * const trigger = iii.registerTrigger({
+   *   type: 'cron',
+   *   function_id: 'my-service::process-batch',
+   *   config: { schedule: '*\/5 * * * *' },
+   * })
+   *
+   * // Later, remove the trigger
+   * trigger.unregister()
+   * ```
    */
   registerTrigger(trigger: RegisterTriggerInput): Trigger;
   /**
-   * Registers a new function. A function is a unit of work that can be invoked by other services.
-   * Pass a handler for local execution, or an HttpInvocationConfig for HTTP-invoked functions.
+   * Registers a new function with a local handler.
    * @param func - The function to register
-   * @param handlerOrInvocation - The handler for local execution, or HTTP invocation config
-   * @returns A function object that can be used to unregister the function
+   * @param handler - The handler for local execution
+   * @returns A handle that can be used to unregister the function
+   *
+   * @example
+   * ```typescript
+   * const ref = iii.registerFunction(
+   *   { id: 'greet', description: 'Returns a greeting' },
+   *   async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
+   * )
+   *
+   * // Later, remove the function
+   * ref.unregister()
+   * ```
+   */
+  /**
+   * Registers a new service.
+   * @param message - The service to register
    */
+  registerService(message: RegisterServiceInput): void;
   registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler): FunctionRef;
+  /**
+   * Registers a new function with an HTTP invocation config (Lambda, Cloudflare Workers, etc.).
+   * @param func - The function to register
+   * @param invocation - HTTP invocation config
+   * @returns A handle that can be used to unregister the function
+   *
+   * @example
+   * ```typescript
+   * const ref = iii.registerFunction(
+   *   { id: 'external::my-lambda', description: 'Proxied Lambda function' },
+   *   {
+   *     url: 'https://abc123.lambda-url.us-east-1.on.aws',
+   *     method: 'POST',
+   *     timeout_ms: 30_000,
+   *     auth: { type: 'bearer', token_key: 'LAMBDA_AUTH_TOKEN' },
+   *   },
+   * )
+   * ```
+   */
   registerFunction(func: RegisterFunctionInput, invocation: HttpInvocationConfig): FunctionRef;
   /**
-   * Invokes a function.
-   * @param function_id - The path to the function
-   * @param data - The data to pass to the function
-   * @param timeoutMs - Optional timeout in milliseconds
+   * Invokes a function using a request object.
+   *
+   * @param request - The trigger request containing function_id, payload, and optional action/timeout
    * @returns The result of the function
+   *
+   * @example
+   * ```typescript
+   * // Synchronous invocation
+   * const result = await iii.trigger<{ name: string }, { message: string }>({
+   *   function_id: 'greet',
+   *   payload: { name: 'World' },
+   *   timeoutMs: 5000,
+   * })
+   * console.log(result.message) // "Hello, World!"
+   *
+   * // Fire-and-forget
+   * await iii.trigger({
+   *   function_id: 'send-email',
+   *   payload: { to: 'user@example.com' },
+   *   action: TriggerAction.Void(),
+   * })
+   *
+   * // Enqueue for async processing
+   * const receipt = await iii.trigger({
+   *   function_id: 'process-order',
+   *   payload: { orderId: '123' },
+   *   action: TriggerAction.Enqueue({ queue: 'orders' }),
+   * })
+   * ```
    */
-  trigger<TInput, TOutput>(function_id: string, data: TInput, timeoutMs?: number): Promise<TOutput>;
+  trigger<TInput, TOutput>(request: TriggerRequest<TInput>): Promise<TOutput>;
   /**
    * Lists all registered functions.
+   *
+   * @example
+   * ```typescript
+   * const functions = await iii.listFunctions()
+   * for (const fn of functions) {
+   *   console.log(`${fn.function_id}: ${fn.description}`)
+   * }
+   * ```
    */
   listFunctions(): Promise<FunctionInfo[]>;
   /**
-   * Invokes a function asynchronously.
-   * @param function_id - The path to the function
-   * @param data - The data to pass to the function
+   * Lists all registered triggers.
+   * @param includeInternal - Whether to include internal triggers (default: false)
    */
-  triggerVoid<TInput>(function_id: string, data: TInput): void;
-  call<TInput, TOutput>(function_id: string, data: TInput, timeoutMs?: number): Promise<TOutput>;
-  callVoid<TInput>(function_id: string, data: TInput): void;
+  listTriggers(includeInternal?: boolean): Promise<TriggerInfo[]>;
   /**
    * Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.
    * @param triggerType - The trigger type to register
    * @param handler - The handler for the trigger type
    * @returns A trigger type object that can be used to unregister the trigger type
+   *
+   * @example
+   * ```typescript
+   * type CronConfig = { schedule: string }
+   *
+   * iii.registerTriggerType<CronConfig>(
+   *   { id: 'cron', description: 'Fires on a cron schedule' },
+   *   {
+   *     async registerTrigger({ id, function_id, config }) {
+   *       startCronJob(id, config.schedule, () =>
+   *         iii.trigger({ function_id, payload: {} }),
+   *       )
+   *     },
+   *     async unregisterTrigger({ id }) {
+   *       stopCronJob(id)
+   *     },
+   *   },
+   * )
+   * ```
    */
   registerTriggerType<TConfig>(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>): void;
   /**
    * Unregisters a trigger type.
    * @param triggerType - The trigger type to unregister
+   *
+   * @example
+   * ```typescript
+   * iii.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })
+   * ```
    */
   unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;
-  /**
-   * Registers a callback for a specific event.
-   * @param event - The event to register the callback for
-   * @param callback - The callback to register
-   */
-  on(event: string, callback: (arg?: unknown) => void): void;
   /**
    * Creates a streaming channel pair for worker-to-worker data transfer.
    * Returns a Channel with a local writer/reader and serializable refs that
@@ -424,6 +692,22 @@ interface ISdk {
    *
    * @param bufferSize - Optional buffer size for the channel (default: 64)
    * @returns A Channel with writer, reader, and their serializable refs
+   *
+   * @example
+   * ```typescript
+   * const channel = await iii.createChannel()
+   *
+   * // Pass the writer ref to another function
+   * await iii.trigger({
+   *   function_id: 'stream-producer',
+   *   payload: { outputChannel: channel.writerRef },
+   * })
+   *
+   * // Read data locally
+   * channel.reader.onMessage((msg) => {
+   *   console.log('Received:', msg)
+   * })
+   * ```
    */
   createChannel(bufferSize?: number): Promise<Channel>;
   /**
@@ -433,36 +717,93 @@ interface ISdk {
    *
    * @param streamName - The name of the stream
    * @param stream - The stream implementation
+   *
+   * @example
+   * ```typescript
+   * const redisStream: IStream<UserSession> = {
+   *   async get({ group_id, item_id }) {
+   *     return JSON.parse(await redis.get(`${group_id}:${item_id}`) ?? 'null')
+   *   },
+   *   async set({ group_id, item_id, data }) {
+   *     const old = await this.get({ stream_name: 'sessions', group_id, item_id })
+   *     await redis.set(`${group_id}:${item_id}`, JSON.stringify(data))
+   *     return { old_value: old ?? undefined, new_value: data }
+   *   },
+   *   async delete({ group_id, item_id }) {
+   *     const old = await this.get({ stream_name: 'sessions', group_id, item_id })
+   *     await redis.del(`${group_id}:${item_id}`)
+   *     return { old_value: old ?? undefined }
+   *   },
+   *   async list({ group_id }) { return [] },
+   *   async listGroups() { return [] },
+   *   async update({ group_id, item_id, ops }) { return { new_value: {} } },
+   * }
+   *
+   * iii.createStream('sessions', redisStream)
+   * ```
    */
   createStream<TData>(streamName: string, stream: IStream<TData>): void;
   /**
    * Registers a callback to receive the current functions list
    * when the engine announces changes.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = iii.onFunctionsAvailable((functions) => {
+   *   console.log(`${functions.length} functions available:`)
+   *   for (const fn of functions) {
+   *     console.log(`  - ${fn.function_id}`)
+   *   }
+   * })
+   *
+   * // Later, stop listening
+   * unsubscribe()
+   * ```
    */
   onFunctionsAvailable(callback: FunctionsAvailableCallback): () => void;
-  /**
-   * Registers a callback to receive OTEL log events from the engine.
-   * @param callback - The callback to invoke when a log event is received
-   * @param config - Optional configuration for filtering logs by severity level
-   * @returns A function to unregister the callback
-   */
-  onLog(callback: LogCallback, config?: LogConfig): () => void;
   /**
    * Gracefully shutdown the iii, cleaning up all resources.
+   *
+   * @example
+   * ```typescript
+   * process.on('SIGTERM', async () => {
+   *   await iii.shutdown()
+   *   process.exit(0)
+   * })
+   * ```
    */
   shutdown(): Promise<void>;
 }
+/**
+ * Handle returned by {@link ISdk.registerTrigger}. Use `unregister()` to
+ * remove the trigger from the engine.
+ */
 type Trigger = {
+  /** Removes this trigger from the engine. */
   unregister(): void;
 };
+/**
+ * Handle returned by {@link ISdk.registerFunction}. Contains the function's
+ * `id` and an `unregister()` method.
+ */
 type FunctionRef = {
+  /** The unique function identifier. */
   id: string;
+  /** Removes this function from the engine. */
   unregister: () => void;
 };
+/**
+ * A streaming channel pair for worker-to-worker data transfer. Created via
+ * {@link ISdk.createChannel}.
+ */
 type Channel = {
+  /** Writer end of the channel. */
   writer: ChannelWriter;
+  /** Reader end of the channel. */
   reader: ChannelReader;
+  /** Serializable reference to the writer (can be sent to other workers). */
   writerRef: StreamChannelRef;
+  /** Serializable reference to the reader (can be sent to other workers). */
   readerRef: StreamChannelRef;
 };
 type InternalHttpRequest<TBody = unknown> = {
@@ -474,51 +815,86 @@ type InternalHttpRequest<TBody = unknown> = {
   response: ChannelWriter;
   request_body: ChannelReader;
 };
+/**
+ * Response object passed to HTTP function handlers. Use `status()` and
+ * `headers()` to set response metadata, write to `stream` for streaming
+ * responses, and call `close()` when done.
+ */
 type HttpResponse = {
+  /** Set the HTTP status code. */
   status: (statusCode: number) => void;
+  /** Set response headers. */
   headers: (headers: Record<string, string>) => void;
+  /** Writable stream for the response body. */
   stream: NodeJS.WritableStream;
+  /** Close the response. */
   close: () => void;
 };
+/**
+ * Incoming HTTP request received by a function registered with an HTTP trigger.
+ *
+ * @typeParam TBody - Type of the parsed request body.
+ */
 type HttpRequest<TBody = unknown> = Omit<InternalHttpRequest<TBody>, 'response'>;
+/**
+ * Alias for {@link HttpRequest}. Represents an incoming API request.
+ *
+ * @typeParam TBody - Type of the parsed request body.
+ */
 type ApiRequest<TBody = unknown> = HttpRequest<TBody>;
+/**
+ * Structured API response returned from HTTP function handlers.
+ *
+ * @typeParam TStatus - HTTP status code literal type.
+ * @typeParam TBody - Type of the response body.
+ *
+ * @example
+ * ```typescript
+ * const response: ApiResponse = {
+ *   status_code: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: { message: 'ok' },
+ * }
+ * ```
+ */
 type ApiResponse<TStatus extends number = number, TBody = string | Buffer | Record<string, unknown>> = {
+  /** HTTP status code. */
   status_code: TStatus;
+  /** Response headers. */
   headers?: Record<string, string>;
+  /** Response body. */
   body?: TBody;
 };
 //#endregion
-//#region src/iii.d.ts
-/** Callback type for connection state changes */
-type ConnectionStateCallback = (state: IIIConnectionState) => void;
-type TelemetryOptions = {
-  language?: string;
-  project_name?: string;
-  framework?: string;
-  amplitude_api_key?: string;
-};
-type InitOptions = {
-  workerName?: string;
-  enableMetricsReporting?: boolean;
-  /** Default timeout for function invocations in milliseconds */
-  invocationTimeoutMs?: number;
-  /** Configuration for WebSocket reconnection behavior */
-  reconnectionConfig?: Partial<IIIReconnectionConfig>;
-  /** OpenTelemetry configuration. OTel is initialized automatically by default.
-   * Set `{ enabled: false }` or env `OTEL_ENABLED=false/0/no/off` to disable.
-   * The engineWsUrl is set automatically from the III address. */
-  otel?: Omit<OtelConfig, 'engineWsUrl'>;
-  telemetry?: TelemetryOptions;
-};
-declare const registerWorker: (address: string, options?: InitOptions) => ISdk;
-//#endregion
 //#region src/utils.d.ts
 /**
  * Safely stringify a value, handling circular references, BigInt, and other edge cases.
  * Returns "[unserializable]" if serialization fails for any reason.
  */
 declare function safeStringify(value: unknown): string;
+/**
+ * Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)
+ * into the function handler format expected by the SDK.
+ *
+ * @param callback - Async handler receiving an {@link HttpRequest} and {@link HttpResponse}.
+ * @returns A function handler compatible with {@link ISdk.registerFunction}.
+ *
+ * @example
+ * ```typescript
+ * import { http } from 'iii-sdk'
+ *
+ * iii.registerFunction(
+ *   { id: 'my-api' },
+ *   http(async (req, res) => {
+ *     res.status(200)
+ *     res.headers({ 'content-type': 'application/json' })
+ *     res.stream.end(JSON.stringify({ hello: 'world' }))
+ *     res.close()
+ *   }),
+ * )
+ * ```
+ */
 declare const http: (callback: (req: HttpRequest, res: HttpResponse) => Promise<void | ApiResponse>) => (req: InternalHttpRequest) => Promise<void | ApiResponse>;
 //#endregion
-export { IIIReconnectionConfig as $, getLogger as A, extractTraceparent as B, WorkerInfo as C, SeverityNumber$1 as D, Meter$1 as E, withSpan as F, removeBaggageEntry as G, getBaggageEntry as H, currentSpanId as I, DEFAULT_BRIDGE_RECONNECTION_CONFIG as J, setBaggageEntry as K, currentTraceId as L, getTracer as M, initOtel as N, Span as O, shutdownOtel as P, IIIConnectionState as Q, extractBaggage as R, StreamChannelRef as S, Logger as T, injectBaggage as U, getAllBaggage as V, injectTraceparent as W, EngineFunctions as X, DEFAULT_INVOCATION_TIMEOUT_MS as Y, EngineTriggers as Z, ChannelReader as _, registerWorker as a, HttpAuthConfig as b, Channel as c, HttpResponse as d, LogFunctions as et, ISdk as f, OtelLogEvent as g, LogSeverityLevel as h, InitOptions as i, getMeter as j, SpanStatusCode$1 as k, FunctionsAvailableCallback as l, LogConfig as m, safeStringify as n, ApiRequest as o, LogCallback as p, OtelConfig as q, ConnectionStateCallback as r, ApiResponse as s, http as t, HttpRequest as u, ChannelWriter as v, WorkerStatus as w, HttpInvocationConfig as x, FunctionInfo as y, extractContext as z };
-//# sourceMappingURL=utils-CMrMD5Ij.d.mts.map
+export { ChannelWriter as $, shutdownOtel as A, injectTraceparent as B, SeverityNumber$1 as C, getMeter as D, getLogger as E, extractContext as F, DEFAULT_BRIDGE_RECONNECTION_CONFIG as G, setBaggageEntry as H, extractTraceparent as I, EngineTriggers as J, DEFAULT_INVOCATION_TIMEOUT_MS as K, getAllBaggage as L, currentSpanId as M, currentTraceId as N, getTracer as O, extractBaggage as P, ChannelReader as Q, getBaggageEntry as R, Meter$1 as S, SpanStatusCode$1 as T, OtelConfig as U, removeBaggageEntry as V, ReconnectionConfig as W, IIIReconnectionConfig as X, IIIConnectionState as Y, LogFunctions as Z, RemoteFunctionHandler as _, Channel as a, RegisterFunctionFormat as at, TriggerHandler as b, HttpRequest as c, RegisterTriggerTypeMessage as ct, InternalHttpRequest as d, TriggerInfo as dt, EnqueueResult as et, OtelLogEvent as f, TriggerRequest as ft, RegisterTriggerTypeInput as g, RegisterTriggerInput as h, ApiResponse as i, MessageType as it, withSpan as j, initOtel as k, HttpResponse as l, StreamChannelRef as lt, RegisterServiceInput as m, WorkerStatus as mt, safeStringify as n, HttpAuthConfig as nt, FunctionRef as o, RegisterFunctionMessage as ot, RegisterFunctionInput as p, WorkerInfo as pt, EngineFunctions as q, ApiRequest as r, HttpInvocationConfig as rt, FunctionsAvailableCallback as s, RegisterTriggerMessage as st, http as t, FunctionInfo as tt, ISdk as u, TriggerAction as ut, Trigger as v, Span as w, Logger as x, TriggerConfig as y, injectBaggage as z };
+//# sourceMappingURL=utils-BRn3Iff5.d.mts.map