iii-browser-sdk

name	iii-browser-sdk
description	Browser SDK for connecting to the iii engine from web applications via WebSocket. Use when building browser-based clients that register functions, invoke triggers, or consume streams from the frontend.

Browser SDK

The browser-optimized SDK for connecting web applications to the iii engine.

Documentation

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

Install

npm install iii-browser-sdk

Key Exports

Export	Purpose
registerWorker(address, options?)	Connect to the engine via WebSocket
registerFunction(id, handler, options?)	Register a browser-side function handler
registerTrigger({ type, function_id, config })	Bind a trigger to a function
trigger({ function_id, payload, action?, timeoutMs? })	Invoke a function
TriggerAction.Void()	Fire-and-forget invocation mode
TriggerAction.Enqueue({ queue })	Durable async invocation mode
registerTriggerType({ id, description }, handler)	Custom trigger type registration
createChannel()	Binary/text streaming between workers
addConnectionStateListener(handler)	Observe connect/disconnect state

Key Differences from Node SDK

• No custom WebSocket headers — use query parameters, cookies, or a protected RBAC listener for auth
• No Logger export — use browser console or your own logging
• No SDK OpenTelemetry export from the browser package
• No HTTP-invoked function registration from the browser package
• Trigger metadata is not available in the current browser registration API
• Connects directly via ws:// or wss:// URL (no registerWorker URL options)
• Function, trigger, and channel APIs are similar to Node, but not identical

Security Model

• Do not expose the internal engine worker port directly to untrusted browsers.
• Connect browser apps to an RBAC-protected listener, usually a dedicated iii-worker-manager port.
• Put auth context in query params, cookies, or an upstream session; custom WebSocket headers are not portable in browsers.
• Keep secrets, API keys, and service credentials on server-side workers.
• Browser functions are useful for real-time UI callbacks and interactive tools, not privileged backend work.

Quick Start

import { registerWorker, TriggerAction } from 'iii-browser-sdk'

const iii = registerWorker('ws://localhost:49135?token=dev-token')

iii.registerFunction('ui::greet', async (data) => {
  return { message: `Hello, ${data.name}!` }
})

const result = await iii.trigger({
  function_id: 'backend::get-user',
  payload: { userId: '123' },
})

await iii.trigger({
  function_id: 'analytics::track',
  payload: { event: 'page_view' },
  action: TriggerAction.Void(),
})

Common Patterns

Code using this pattern commonly includes, when relevant:

• registerWorker('ws://host:49135?token=...') — connect from browser to an RBAC listener
• registerWorker('wss://host:49135?token=...') — connect with TLS in production
• iii.registerFunction(id, handler) — register browser-side handler
• iii.trigger({ function_id, payload }) — call server-side functions
• iii.trigger({ ..., action: TriggerAction.Void() }) — fire-and-forget from browser
• const { writer, reader, readerRef, writerRef } = await iii.createChannel() — create a channel
• writer.sendBinary(uint8Array) / writer.sendMessage(text) — send channel data
• reader.onBinary(callback) / reader.onMessage(callback) / reader.readAll() — consume channel data
• iii.addConnectionStateListener(listener) — update UI on reconnects

Pattern Boundaries

• For server-side Node.js workers, prefer iii-node-sdk.
• For channel-based binary transfer, see iii-channels.
• For RBAC-protected browser access, see iii-worker-rbac.
• For Python or Rust workers, see iii-python-sdk or iii-rust-sdk.
• Stay with iii-browser-sdk when the client is a web browser.

When to Use

• Use this skill when the task is primarily about iii-browser-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.