Browser SDK

API reference for the iii SDK for Browser / TypeScript.

Installation

npm install iii-browser-sdk

Initialization

registerWorker

Register the worker with a iii instance, returns a connected worker client. The WebSocket connection is established automatically.

Signature

registerWorker(address: string, options?: InitOptions) => ISdk

Parameters

address · string · required

WebSocket URL of the III engine (e.g. ws://localhost:49135).

options · InitOptions

Optional InitOptions for worker name, timeouts, and reconnection.

Show `InitOptions` fields

headers · Record<string, string>

Browser WebSocket connections authenticate via query parameters or cookies; the headers option is ignored.

invocationTimeoutMs · number

Default timeout for worker.trigger() invocations in milliseconds. Defaults to 30000.

namespace · string

Namespace this worker registers under. When omitted the engine applies its default namespace. Scopes worker and function registrations so identically-named entries can coexist across namespaces. The browser has no process.env, so there is no environment-variable fallback: pass the option explicitly.

reconnectionConfig · Partial<IIIReconnectionConfig>

WebSocket reconnection behavior.

workerName · string

Name this worker announces to the engine. Defaults to a unique browser:<random> per client: a browser has no pid to disambiguate by, and the engine allows only one live worker per name in a namespace, so two tabs sharing a fixed name would evict each other.

Example

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

const worker = registerWorker('ws://localhost:49135')

Methods

registerTrigger

Deprecated. Use ISdk.observe instead: iii.observe({ function_id, args, filters }, target, { metadata }). Logs a warning once per page. The http, cron, queue, state, stream, pubsub and database workers still publish trigger types: keep using registerTrigger for them until they ship source functions. Migration guide: https://iii.dev/docs/upgrading/from-0-24-x

Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.

Signature

registerTrigger(trigger: RegisterTriggerInput) => Trigger

Parameters

trigger · RegisterTriggerInput · required

The trigger to register

Hide `RegisterTriggerInput` fields

config · unknown · required

Trigger-type-specific configuration, matching the shape the trigger type expects.

function_id · string · required

ID of the function this trigger invokes when it fires.

namespace · string

Namespace the trigger’s target function resolves in. Omitting it does not bind in the engine’s default: registerTrigger fills it from this worker’s namespace, because the function a trigger names is one this worker registered, and that landed in the worker’s namespace. Name another namespace, default included, to bind elsewhere.

type · string · required

Identifier of the registered trigger type this trigger uses (e.g. storage::object-created, http).

Example

const trigger = worker.registerTrigger({
  type: 'cron',
  function_id: 'my-service::process-batch',
  config: { expression: '0 */5 * * * * *' },
})

// Later, remove the trigger
trigger.unregister()

---

registerFunction

Registers a new function with a local async handler that runs in the browser session. HTTP invocation configs are a Node.js SDK feature.

Signature

registerFunction(functionId: string, handler: RemoteFunctionHandler, options?: RegisterFunctionOptions) => FunctionRef

Parameters

functionId · string · required

Unique function identifier

handler · RemoteFunctionHandler · required

Async handler executed when the function is invoked

options · RegisterFunctionOptions

Optional function registration options (description, request/response formats, metadata)

Show `RegisterFunctionOptions` fields

description · string

The description of the function

localDispatch · boolean

Calls this worker makes to its own function run in-process once the engine confirmed it (default true). Set false for a handler that must always run through the engine.

metadata · Record<string, unknown>

observe · ObserveHooks

Makes the function observable on its own terms: owner delivery (delivery: 'owner', args_format), and callbacks when an observer is added or removed. Without it the function is still observable (auto delivery, no args).

request_format · RegisterFunctionFormat

The request format of the function

response_format · RegisterFunctionFormat

The response format of the function

Example

// Local handler
const ref = worker.registerFunction(
  'greet',
  async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
  { description: 'Returns a greeting' },
)

// Later, remove the function
ref.unregister()

---

trigger

Invokes a function using a request object.

Signature

trigger(request: TriggerRequest<TInput>) => Promise<TOutput>

Parameters

request · TriggerRequest<TInput> · required

The trigger request containing function_id, payload, and optional action/timeout

Hide `TriggerRequest` fields

action · TriggerAction

Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. TriggerAction.Enqueue(), TriggerAction.Void()).

baggage · string

W3C baggage to send along with traceparent; defaults the same way.

dispatch · 'auto' | 'remote'

auto (default) runs a function this worker hosts in-process when the engine confirmed it for local dispatch; remote always goes through the engine. Tests use it, and so do callers that rely on engine-side effects.

function_id · string · required

ID of the function to invoke.

metadata · unknown

Per-invocation metadata (any JSON). Travels beside the payload: the handler receives it as its second argument, and observer filters read it as metadata.*.

namespace · string

Namespace to route this invocation to. Omit to inherit this worker’s; say default to reach the engine’s from a namespaced worker.

payload · TInput · required

Input data passed to the function.

timeoutMs · number

Override the default invocation timeout, in milliseconds.

traceparent · string

W3C traceparent to continue. The browser SDK has no OpenTelemetry, so it never makes one up: when omitted, a call made inside a handler forwards the traceparent that handler was invoked with (see ISdk.currentInvocation); a top-level call sends none and the engine starts the trace.

Example

// Synchronous invocation
const result = await worker.trigger<{ name: string }, { message: string }>({
  function_id: 'greet',
  payload: { name: 'World' },
  timeoutMs: 5000,
})
console.log(result.message) // "Hello, World!"

// Fire-and-forget
await worker.trigger({
  function_id: 'send-email',
  payload: { to: '[e-mail]' },
  action: TriggerAction.Void(),
})

// Enqueue for async processing (the queue must be declared in the
// queue worker's queue_configs)
const receipt = await worker.trigger({
  function_id: 'process-order',
  payload: { orderId: '123' },
  action: TriggerAction.Enqueue({ queue: 'orders' }),
})

---

registerTriggerType

Deprecated. Register a function with an observe descriptor instead: registerFunction(id, handler, { observe: { delivery: 'owner', onObserverAdded, onObserverRemoved } }). Logs a warning once per page. Migration guide: https://iii.dev/docs/upgrading/from-0-24-x

Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.

Signature

registerTriggerType(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>) => TriggerTypeRef<TConfig>

Parameters

triggerType · RegisterTriggerTypeInput · required

The trigger type to register

Show `RegisterTriggerTypeInput` fields

description · string · required

Human-readable description of what this trigger type does.

id · string · required

Unique identifier for the trigger type (e.g. state, durable:subscriber).

handler · TriggerHandler<TConfig> · required

The handler for the trigger type

Show `TriggerHandler` fields

registerTrigger · (config: TriggerConfig<TConfig>) => Promise<void> · required

Called when a trigger instance is registered.

unregisterTrigger · (config: TriggerConfig<TConfig>) => Promise<void> · required

Called when a trigger instance is unregistered.

Example

type CronConfig = { expression: string }

worker.registerTriggerType<CronConfig>(
  { id: 'cron', description: 'Fires on a cron schedule' },
  {
    async registerTrigger({ id, function_id, config }) {
      startCronJob(id, config.expression, () =>
        worker.trigger({ function_id, payload: {} }),
      )
    },
    async unregisterTrigger({ id }) {
      stopCronJob(id)
    },
  },
)

---

unregisterTriggerType

Deprecated. Trigger types are replaced by functions with an observe descriptor.

Unregisters a trigger type.

Signature

unregisterTriggerType(triggerType: RegisterTriggerTypeInput) => void

Parameters

triggerType · RegisterTriggerTypeInput · required

The trigger type to unregister

Show `RegisterTriggerTypeInput` fields

description · string · required

Human-readable description of what this trigger type does.

id · string · required

Unique identifier for the trigger type (e.g. state, durable:subscriber).

Example

worker.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })

---

addConnectionStateListener

Subscribe to connection-state transitions. The handler is fired immediately with the current state, then on every transition. Multiple listeners are supported. Returns an unsubscribe function.

Signature

addConnectionStateListener(handler: (state: IIIConnectionState) => void) => () => void

Parameters

handler · (state: IIIConnectionState) => void · required

Callback invoked with the new connection state whenever it changes.

Example

const unsub = worker.addConnectionStateListener((state) => {
  console.log('connection state:', state)
})

// Later, stop receiving updates
unsub()

---

currentInvocation

The invocation the calling code runs in (remote or local handler), or undefined outside any handler.

Browsers have no AsyncLocalStorage: the SDK knows the invocation while the handler runs synchronously, up to its first await; after it this returns undefined. Read it before awaiting, and re-enter it with ISdk.withInvocation for calls made after.

Code after an await, outside ISdk.withInvocation, runs outside any invocation, but its calls are not treated as new chains: they carry the observe_depth of the deepest invocation running on this page, so the engine’s loop guard (max_observe_depth) still stops an observer cycle whose target awaits before calling back. With several invocations running this over-counts, and a legitimate chain may stop early. They carry a caller and traceparent only when that is unambiguous (one invocation is running, and it is an observe activation); otherwise none. They never get an invocation’s metadata: obs.emit / obs.call filters on metadata.* see it only inside a real scope. An invocation that never settles stops counting as running after 10 minutes (a local call: at its timeout). Local calls nest the same way: a self-recursion that awaits before each call goes through the engine past 64 levels, while calls started together count as one level. A limitation: local calls started in separate ticks while earlier ones still run also look nested, so a long, wide fan-out may send some through the engine (same results). While the socket is closed none is: a function this worker hosts then runs here up to 256 local calls deep, and past that the call fails at once with LOCAL_DEPTH_EXCEEDED (a runaway recursion must not freeze the page).

Signature

currentInvocation() => InvocationContext | undefined

Example

worker.registerFunction('ui::checkout', async (cart) => {
  const inv = worker.currentInvocation() // { function_id, invocation_id, caller, observe_depth, ... }
  const quote = await fetchQuote(cart)
  return worker.withInvocation(inv, () => worker.trigger({ function_id: 'orders::create', payload: quote }))
})

---

getFatalError

The fatal registration rejection that terminated this connection, if any (e.g. a WORKER_NAMESPACE_CONFLICT); undefined while healthy. Mirrors the Node/Python/Rust SDKs.

Signature

getFatalError() => RegistrationRejectedError | undefined

---

observe

Observes a function: every event of source that passes its filters invokes target, a registered function. Returns synchronously (also before the connection is up); the observer is replayed with the same id on reconnect. Errors show up as state error and reject ready(); against an engine without observe that is UNSUPPORTED.

Signature

observe(source: ObserveSource, target: Target, options?: ObserverOptions) => ObserverHandle

Parameters

source · ObserveSource · required

What is observed: function_id, args (owner-delivered functions only), filters, on, capture, deliver.

Show `ObserveSource` fields

args · Record<string, unknown>

Owner-delivered functions only: for the owner; validated against its args_format.

capture · Capture[]

Auto and obs.emit; default ['input', 'output', 'caller'].

deliver · 'input' | 'output' | 'envelope'

Auto and obs.emit; default 'envelope'.

filters · Filter

Which events reach the target; {} (or absent) = every event.

function_id · string · required

The observed function.

namespace · string

Defaults to this worker’s namespace (engine::* resolves to default).

on · 'error' | 'success' | 'complete'

Auto only; default 'success'.

target · Target · required

The function to invoke.

options · ObserverOptions

id, max_fires, expires_in_ms, max_in_flight, metadata.

Show `ObserverOptions` fields

expires_in_ms · number

The observer is disposed this many milliseconds after it is created (EXPIRED). Default: never.

id · string

Default: a random UUID, stable across replays.

max_fires · number

The observer is disposed after this many activations (MAX_FIRES). Default: unlimited.

max_in_flight · number

Activations running at once; further ones queue, then drop as OVERFLOW. Default: the engine’s observers.default_max_in_flight (64).

metadata · Record<string, unknown>

Delivered as the metadata sidecar of every activation.

Example

worker.registerFunction('ui::order-shipped', async ({ input }: Observed) => toast(input))

const shipped = worker.observe(
  { function_id: 'orders::ship', filters: { 'input.customer_id': { $eq: customerId } } },
  'ui::order-shipped',
)
await shipped.ready()

---

shutdown

Gracefully shutdown the iii, cleaning up all resources.

Signature

shutdown() => Promise<void>

Example

await worker.shutdown()

---

withInvocation

Runs fn inside invocation (what ISdk.currentInvocation returned), and returns what fn returns. Calls fn makes before its own first await (trigger, obs.emit, obs.call, currentInvocation) belong to that invocation: they carry its caller, observe_depth and traceparent. When fn returns a promise, the invocation counts as running until it settles, so fn’s code after an await gets the fallback below. undefined runs fn outside any invocation.

Code after an await, outside withInvocation, runs outside any invocation, but its calls are not treated as new chains: they carry the observe_depth of the deepest invocation running on this page, so the engine’s loop guard (max_observe_depth) still stops an observer cycle whose target awaits before calling back. With several invocations running this over-counts, and a legitimate chain may stop early. They carry a caller and traceparent only when that is unambiguous (one invocation is running, and it is an observe activation); otherwise none. They never get an invocation’s metadata: obs.emit / obs.call filters on metadata.* see it only inside a real scope. An invocation that never settles stops counting as running after 10 minutes (a local call: at its timeout). Local calls nest the same way: a self-recursion that awaits before each call goes through the engine past 64 levels, while calls started together count as one level. A limitation: local calls started in separate ticks while earlier ones still run also look nested, so a long, wide fan-out may send some through the engine (same results). While the socket is closed none is: a function this worker hosts then runs here up to 256 local calls deep, and past that the call fails at once with LOCAL_DEPTH_EXCEEDED (a runaway recursion must not freeze the page).

Signature

withInvocation(invocation: InvocationContext | undefined, fn: () => T) => T

Parameters

invocation · InvocationContext | undefined

Show `InvocationContext` fields

activation · { activation_id?: string; observer_id: string }

Set when this invocation is the activation of an observer’s target.

baggage · string

The W3C baggage that came with traceparent.

caller · CallerInfo

function_id · string · required

invocation_id · string · required

observe_depth · number · required

traceparent · string

The W3C traceparent the invocation arrived with (or was triggered with, for a local call). Calls made inside the handler forward it. Browser SDK only: there is no OpenTelemetry context to carry it.

fn · () => T · required

Subpath Exports

The iii-browser-sdk package provides additional entry points:

Import path	Contents
iii-browser-sdk	ApiRequest, ApiResponse, AuthInput, AuthResult, Caller, CallerInfo, Capture, Channel, ChannelReader, ChannelWriter, EngineFunctions, EngineTriggers, EnqueueResult, Filter, FunctionRef, IIIConnectionState, IIIReconnectionConfig, ISdk, InitOptions, InvocationContext, InvocationError, InvocationErrorInit, MessageType, MiddlewareFunctionInput, ObserveDescriptorWire, ObserveDoc, ObserveHooks, ObserveReason, ObserveRejection, ObserveSource, Observed, Observer, ObserverHandle, ObserverOptions, ObserverState, OnFunctionRegistrationInput, OnFunctionRegistrationResult, OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult, OpenEnum, RegisterFunctionFormat, RegisterFunctionInput, RegisterFunctionMessage, RegisterFunctionOptions, RegistrationRejectedError, RegistrationRejectedInit, RemoteFunctionHandler, StreamChannelRef, Target, TriggerAction, TriggerRequest, registerWorker
iii-browser-sdk/state	DeleteResult, IState, StateDeleteInput, StateDeleteResult, StateEventData, StateEventType, StateGetInput, StateListInput, StateSetInput, StateSetResult, StateUpdateInput, StateUpdateResult
iii-browser-sdk/stream	DeleteResult, IStream, MergePath, StreamAuthInput, StreamAuthResult, StreamChangeEvent, StreamContext, StreamDeleteInput, StreamGetInput, StreamJoinLeaveEvent, StreamJoinLeaveTriggerConfig, StreamJoinResult, StreamListGroupsInput, StreamListInput, StreamSetInput, StreamSetResult, StreamTriggerConfig, StreamUpdateInput, StreamUpdateResult, UpdateAppend, UpdateDecrement, UpdateIncrement, UpdateMerge, UpdateOp, UpdateOpError, UpdateRemove, UpdateSet

Types

iii-browser-sdk

ApiRequest · ApiResponse · AuthInput · AuthResult · Caller · CallerInfo · Capture · Channel · ChannelReader · ChannelWriter · EngineFunctions · EngineTriggers · EnqueueResult · Filter · FunctionRef · IIIConnectionState · IIIReconnectionConfig · InitOptions · InvocationContext · InvocationError · InvocationErrorInit · MessageType · MiddlewareFunctionInput · Observed · ObserveDescriptorWire · ObserveDoc · ObserveHooks · Observer · ObserveReason · ObserveRejection · ObserverHandle · ObserverOptions · ObserverState · ObserveSource · OnFunctionRegistrationInput · OnFunctionRegistrationResult · OnTriggerRegistrationInput · OnTriggerRegistrationResult · OnTriggerTypeRegistrationInput · OnTriggerTypeRegistrationResult · OpenEnum · RegisterFunctionFormat · RegisterFunctionInput · RegisterFunctionMessage · RegisterFunctionOptions · RegistrationRejectedError · RegistrationRejectedInit · RemoteFunctionHandler · StreamChannelRef · Target · TriggerAction · TriggerRequest

ApiRequest

Incoming HTTP request received by a function registered with an HTTP trigger.

Name	Type	Required	Description
body	TBody	Yes	-
headers	Record<string, string | string[]>	Yes	-
method	string	Yes	-
path_params	Record<string, string>	Yes	-
query_params	Record<string, string | string[]>	Yes	-

---

ApiResponse

Structured API response returned from HTTP function handlers.

Name	Type	Required	Description
body	TBody	No	Response body.
headers	Record<string, string>	No	Response headers.
status_code	TStatus	Yes	HTTP status code.

---

AuthInput

Input passed to the RBAC auth function during WebSocket upgrade. Contains the HTTP headers, query parameters, and client IP from the connecting worker’s upgrade request.

Name	Type	Required	Description
headers	Record<string, string>	Yes	HTTP headers from the WebSocket upgrade request.
ip_address	string	Yes	IP address of the connecting client.
query_params	Record<string, string[]>	Yes	Query parameters from the upgrade URL. Each key maps to an array of values to support repeated keys.

---

AuthResult

Return value from the RBAC auth function. Controls which functions the authenticated worker can invoke and what context is forwarded to the middleware.

Name	Type	Required	Description
allow_function_registration	boolean	No	Whether the worker may register new functions. Defaults to true if omitted.
allow_trigger_type_registration	boolean	No	Whether the worker may register new trigger types. Defaults to false if omitted.
allowed_functions	string[]	No	Additional function IDs to allow beyond the expose_functions config, in the default namespace only. Put per-namespace grants in namespaces. Defaults to [] if omitted.
allowed_trigger_types	string[]	No	Trigger type IDs the worker may register triggers for. When omitted, all types are allowed.
context	Record<string, unknown>	No	Arbitrary context forwarded to the middleware function on every invocation. Defaults to {} if omitted.
forbidden_functions	string[]	No	Function IDs to deny even if they match expose_functions. Takes precedence over allowed. Defaults to [] if omitted.
function_registration_prefix	string	No	Optional prefix applied to all function IDs registered by this worker.
namespaces	Record<string, string[]>	No	Grants scoped to one namespace each: { orders: ['svc::*'] }. A value is an exact function ID or a wildcard, in either the bare (svc::*) or the match("svc::*") spelling. The keys are also the namespaces the session may declare on engine::workers::register. Omit to scope nothing: the session declares any namespace, and only allowed_functions and expose_functions apply.

---

Caller

Who started an invocation: the worker (worker_id / worker_name, stamped by the engine), and the function and invocation the call was made from.

Name	Type	Required	Description
function_id	string	No	The handler the call was made from; absent for top-level calls.
invocation_id	string	No	-
parent	Omit<Caller, “parent”>	No	The caller of that handler, one level only.
worker_id	string	No	Absent on activations, whose caller is the engine (worker_name: 'iii-engine').
worker_name	string	No	-

---

CallerInfo

A caller as the SDK knows it: every field may be missing (a top-level call has no function; a call made before WorkerRegistered has no worker id).

type CallerInfo = Partial<Omit<Caller, "parent">> & { parent?: Partial<Omit<Caller, "parent">> }

---

Capture

What an observer ships to its target. Default ['input', 'output', 'caller'].

type Capture = "input" | "output" | "error" | "caller" | "metadata"

---

Channel

A streaming channel pair for worker-to-worker data transfer. Created via the createChannel helper from iii-browser-sdk/helpers.

Name	Type	Required	Description
reader	ChannelReader	Yes	Reader end of the channel.
readerRef	StreamChannelRef	Yes	Serializable reference to the reader (can be sent to other workers).
writer	ChannelWriter	Yes	Writer end of the channel.
writerRef	StreamChannelRef	Yes	Serializable reference to the writer (can be sent to other workers).

---

ChannelReader

Read end of a streaming channel. Uses native browser WebSocket.

---

ChannelWriter

Write end of a streaming channel. Uses native browser WebSocket.

---

EngineFunctions

Engine function paths for internal operations.

Naming note: LIST_TRIGGERS / INFO_TRIGGERS cover trigger TYPES (templates). LIST_REGISTERED_TRIGGERS / INFO_REGISTERED_TRIGGERS cover trigger INSTANCES (subscriber rows). The old engine::trigger-types::list builtin has been removed and is now served by engine::triggers::list.

Name	Type	Required	Description
INFO_FUNCTIONS	"engine::functions::info"	Yes	-
INFO_REGISTERED_TRIGGERS	"engine::registered-triggers::info"	Yes	-
INFO_TRIGGERS	"engine::triggers::info"	Yes	-
INFO_WORKERS	"engine::workers::info"	Yes	-
LIST_FUNCTIONS	"engine::functions::list"	Yes	-
LIST_REGISTERED_TRIGGERS	"engine::registered-triggers::list"	Yes	-
LIST_TRIGGERS	"engine::triggers::list"	Yes	-
LIST_WORKERS	"engine::workers::list"	Yes	-
REGISTER_WORKER	"engine::workers::register"	Yes	-

---

EngineTriggers

Engine trigger types

Name	Type	Required	Description
FUNCTIONS_AVAILABLE	"engine::functions-available"	Yes	-

---

EnqueueResult

Result returned when a function is invoked with TriggerAction.Enqueue.

Name	Type	Required	Description
messageReceiptId	string	Yes	Unique receipt ID for the enqueued message.

---

Filter

A declarative filter over input, output, error, caller and metadata, with explicit operators only: { 'input.amount': { $gte: 500 } }. See the filter language reference.

type Filter = Record<string, unknown>

---

FunctionRef

Handle returned by ISdk.registerFunction. Contains the function’s id and an unregister() method.

Name	Type	Required	Description
id	string	Yes	The unique function identifier.
isObserved	() => boolean	Yes	Whether any observer is active on this function (one load, for the emit fast path: skip building an event nobody receives).
observers	() => readonly Observer[]	Yes	The active observers, as this owner sees them.
unregister	() => void	Yes	Removes this function from the engine.

---

IIIConnectionState

Connection state for the III WebSocket

type IIIConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed"

---

IIIReconnectionConfig

Configuration for WebSocket reconnection behavior

Name	Type	Required	Description
backoffMultiplier	number	Yes	Exponential backoff multiplier (default: 2)
initialDelayMs	number	Yes	Starting delay in milliseconds (default: 1000ms)
jitterFactor	number	Yes	Random jitter factor 0-1 (default: 0.3)
maxDelayMs	number	Yes	Maximum delay cap in milliseconds (default: 30000ms)
maxRetries	number	Yes	Maximum retry attempts, -1 for infinite (default: -1)

---

InitOptions

Configuration options passed to registerWorker.

Name	Type	Required	Description
headers	Record<string, string>	No	Browser WebSocket connections authenticate via query parameters or cookies; the headers option is ignored.
invocationTimeoutMs	number	No	Default timeout for worker.trigger() invocations in milliseconds. Defaults to 30000.
namespace	string	No	Namespace this worker registers under. When omitted the engine applies its default namespace. Scopes worker and function registrations so identically-named entries can coexist across namespaces. The browser has no process.env, so there is no environment-variable fallback: pass the option explicitly.
reconnectionConfig	Partial<IIIReconnectionConfig>	No	WebSocket reconnection behavior.
workerName	string	No	Name this worker announces to the engine. Defaults to a unique browser:<random> per client: a browser has no pid to disambiguate by, and the engine allows only one live worker per name in a namespace, so two tabs sharing a fixed name would evict each other.

---

InvocationContext

The invocation the current code runs in, in every handler, remote or local (iii.currentInvocation()).

Browsers have no AsyncLocalStorage, so the SDK knows it only while the handler runs synchronously: up to its first await. To keep it across an await, read it first and re-enter it with iii.withInvocation(inv, fn).

Name	Type	Required	Description
activation	{ activation_id?: string; observer_id: string }	No	Set when this invocation is the activation of an observer’s target.
baggage	string	No	The W3C baggage that came with traceparent.
caller	CallerInfo	No	-
function_id	string	Yes	-
invocation_id	string	Yes	-
observe_depth	number	Yes	-
traceparent	string	No	The W3C traceparent the invocation arrived with (or was triggered with, for a local call). Calls made inside the handler forward it. Browser SDK only: there is no OpenTelemetry context to carry it.

---

InvocationError

An error the SDK raises itself for an invocation, with a machine-readable code: observe delivery errors (NOT_OWNER_DELIVERED, OBSERVER_NOT_ACTIVE, FILTERS_NOT_MATCHED) and an invalid observe descriptor (INVALID_OBSERVE_DESCRIPTOR). Mirrors the Node SDK.

A call the engine answers with an error still rejects with the engine’s error body ({ code, message, stacktrace? }), as in earlier releases, and so does a locally dispatched call whose handler throws: both paths reject with the same value.

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
stacktrace	string	No	-

---

InvocationErrorInit

Fields used to construct an InvocationError.

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
message	string	Yes	-
stacktrace	string	No	-

---

MessageType

Name	Type	Required	Description
FunctionRegistered	"functionregistered"	Yes	Engine → owner: the registerfunction ack, with the function’s full observer set.
InvocationResult	"invocationresult"	Yes	-
InvocationsObserved	"invocationsobserved"	Yes	Owner → engine: matched local invocations and obs.emit events, batched.
InvokeFunction	"invokefunction"	Yes	-
LocalInvocationStats	"localinvocationstats"	Yes	Owner → engine: periodic counts of local invocations and report drops.
Observe	"observe"	Yes	Observing worker → engine: create (or idempotently replay) an observer.
ObserverAck	"observerack"	Yes	Owner → engine: accept (or reject) an added observer.
ObserverAdded	"observeradded"	Yes	Engine → owner: one observer attached to a function this connection hosts.
ObserveResult	"observeresult"	Yes	Engine → observing worker: the reply to observe (also on replay).
ObserverRemoved	"observerremoved"	Yes	Engine → owner: one observer detached.
ObserverStateChanged	"observerstatechanged"	Yes	Engine → observing worker: an observer’s lifecycle transition.
Reattach	"reattach"	Yes	-
RegisterFunction	"registerfunction"	Yes	-
RegisterTrigger	"registertrigger"	Yes	-
RegisterTriggerType	"registertriggertype"	Yes	-
RegistrationRejected	"registrationrejected"	Yes	-
TriggerRegistrationResult	"triggerregistrationresult"	Yes	-
Unobserve	"unobserve"	Yes	Observing worker → engine: dispose an observer this connection owns.
UnregisterFunction	"unregisterfunction"	Yes	-
UnregisterTrigger	"unregistertrigger"	Yes	-
UnregisterTriggerType	"unregistertriggertype"	Yes	-
WorkerRegistered	"workerregistered"	Yes	-

---

MiddlewareFunctionInput

Input passed to the RBAC middleware function on every function invocation through the RBAC port. The middleware can inspect, modify, or reject the call before it reaches the target function.

Name	Type	Required	Description
action	TriggerAction	No	Routing action, if any.
context	Record<string, unknown>	Yes	Auth context returned by the auth function for this session.
function_id	string	Yes	ID of the function being invoked.
namespace	string	No	Target namespace the invoke addressed; forward the call here to stay in the caller’s namespace. Absent → the engine’s default namespace.
payload	Record<string, unknown>	Yes	Payload sent by the caller.

---

Observed

What the target of an auto observer (or of obs.emit) receives with deliver: 'envelope' (the default). Fields not in the observer’s capture are absent.

Name	Type	Required	Description
activation_id	string	Yes	-
caller	Caller	No	-
duration_ms	number	Yes	-
error	{ code: string; message: string }	No	-
function_id	string	Yes	-
input	I	No	-
invocation_id	string	Yes	-
metadata	Record<string, unknown>	No	-
namespace	string	Yes	-
observer_id	string	Yes	-
output	O	No	-
started_at_ms	number	Yes	-
status	"error" | "success"	Yes	-

---

ObserveDescriptorWire

RegisterFunction.observe: the part of the observe hooks that travels. Callbacks never do.

Name	Type	Required	Description
allow	boolean	No	Default true; false makes every observe on it fail with NOT_OBSERVABLE.
args_format	RegisterFunctionFormat	No	Owner only: validates the observers’ args in the engine (INVALID_ARGS).
delivery	OpenEnum<“auto” | “owner”>	No	auto (default) or owner.
legacy_trigger_type	string	No	Phase 5 shim: accept old registertrigger { trigger_type } for this type.

---

ObserveDoc

The document an observer’s filters read (filters.md §1).

Name	Type	Required	Description
caller	CallerInfo	No	-
error	unknown	No	-
input	unknown	No	-
metadata	unknown	No	-
output	unknown	No	-

---

ObserveHooks

The observe option of registerFunction: how the function’s observers are delivered, and the callbacks that run when one is added or removed.

The callbacks of one function run one at a time, in revision order, with one exception: a callback still running after 30 s is treated as failed (OWNER_TIMEOUT) and the next one starts, so a hung callback cannot stall its function forever. It may then overlap with the callbacks after it, and if a timed-out onObserverAdded completes later, onObserverRemoved runs for that observer.

Name	Type	Required	Description
allow	boolean	No	Default true; false refuses every observer (NOT_OBSERVABLE).
args_format	RegisterFunctionFormat	No	Owner only: JSON Schema of the observers’ args (the engine answers INVALID_ARGS).
delivery	"auto" | "owner"	No	auto (default): every invocation is offered to every observer. owner: the handler hands each event to the observers it belongs to, with obs.emit / obs.call.
legacy_trigger_type	string	No	Accept old registerTrigger({ type }) calls for this trigger type.
onObserverAdded	(obs: Observer) => void | Promise<void>	No	Runs once per added observer, before the SDK acks it. Throw to reject it (an ObserveRejection sets the code, anything else is OBSERVE_REJECTED); after 30 s it is rejected with OWNER_TIMEOUT.
onObserverRemoved	(obs: Observer) => void | Promise<void>	No	Runs once per removed observer. Cannot fail: errors are logged.

---

Observer

An observer as the function’s owner sees it (onObserverAdded, FunctionRef.observers()): its args, filters, target, capture and on. Never its metadata, policy or the observing worker.

Name	Type	Required	Description
args	Record<string, unknown>	Yes	The observer’s args, validated against args_format by the engine.
capture	Capture[]	Yes	-
filters	Filter	Yes	The observer’s filters, normalized; the SDK applies them in emit / call.
function_id	string	Yes	The observed function (the one this worker hosts).
id	string	Yes	-
legacy	{ config: unknown; trigger_type: string }	No	Set when the engine’s legacy shim created the observer from an old registerTrigger.
on	"error" | "success" | "complete"	Yes	Auto only.
target	string	Yes	The target function id.
call	(payload: unknown, opts?: { metadata?: undefined; timeoutMs?: number }) => Promise<R>	Yes	Owner delivery, request/response: invokes the target with payload and resolves with its result. Rejects with FILTERS_NOT_MATCHED (nothing is sent) when the filters reject the payload, and with OBSERVER_NOT_ACTIVE when the observer is no longer active.
emit	(event: unknown) => boolean	Yes	Owner delivery, fire-and-forget: hands event to this observer. Returns false and sends nothing when its filters reject the event or the observer is no longer active (removed or rejected meanwhile). Throws NOT_OWNER_DELIVERED on an auto function.
matches	(doc: ObserveDoc) => boolean	Yes	Evaluates the observer’s filters on a document.
reject	(code: string, message: string) => void	Yes	Late rejection of an active observer (e.g. after a config reload). It stops receiving events at once, and stays rejected across reconnects until the engine adds it again.

---

ObserveReason

A state reason or an error: a machine-readable code and a message.

Name	Type	Required	Description
code	string	Yes	-
message	string	Yes	-

---

ObserveRejection

Thrown by an onObserverAdded hook to reject an observer with a code of its own (HTTP_ROUTE_CONFLICT, INVALID_CRON_EXPRESSION, …); any other error rejects it with OBSERVE_REJECTED. Also the error ObserverHandle.ready() rejects with when the observer turns error or disposed.

Name	Type	Required	Description
code	string	Yes	-

---

ObserverHandle

What iii.observe returns, synchronously.

Name	Type	Required	Description
id	string	Yes	-
reason	ObserveReason	No	Why the observer is in its state (error, suspended, disposed).
state	ObserverState	Yes	-
dispose	() => Promise<void>	Yes	Removes the observer (unobserve). It is not replayed on reconnect.
onStateChange	(listener: (state: ObserverState, reason?: ObserveReason) => void) => () => void	Yes	Calls listener on every state change, in order; returns the unsubscribe function. Listeners are called asynchronously (never on the connection’s read path), so they may call the client.
ready	() => Promise<void>	Yes	Resolves when the observer is active; rejects with an ObserveRejection carrying the code when it turns error or disposed first.

---

ObserverOptions

The observer itself: its id, policy and metadata.

Name	Type	Required	Description
expires_in_ms	number	No	The observer is disposed this many milliseconds after it is created (EXPIRED). Default: never.
id	string	No	Default: a random UUID, stable across replays.
max_fires	number	No	The observer is disposed after this many activations (MAX_FIRES). Default: unlimited.
max_in_flight	number	No	Activations running at once; further ones queue, then drop as OVERFLOW. Default: the engine’s observers.default_max_in_flight (64).
metadata	Record<string, unknown>	No	Delivered as the metadata sidecar of every activation.

---

ObserverState

An observer’s lifecycle: pending (no owner yet, waiting for the owner’s ack, or no target yet) → active or error; suspended while its worker or target is away; disposed at the end.

type ObserverState = "pending" | "active" | "suspended" | "error" | "disposed"

---

ObserveSource

The left side of iii.observe: what is observed.

Name	Type	Required	Description
args	Record<string, unknown>	No	Owner-delivered functions only: for the owner; validated against its args_format.
capture	Capture[]	No	Auto and obs.emit; default ['input', 'output', 'caller'].
deliver	"input" | "output" | "envelope"	No	Auto and obs.emit; default 'envelope'.
filters	Filter	No	Which events reach the target; {} (or absent) = every event.
function_id	string	Yes	The observed function.
namespace	string	No	Defaults to this worker’s namespace (engine::* resolves to default).
on	"error" | "success" | "complete"	No	Auto only; default 'success'.

---

OnFunctionRegistrationInput

Input passed to the on_function_registration_function_id hook when a worker attempts to register a function through the RBAC port. Return an OnFunctionRegistrationResult with the (possibly mapped) fields, or throw to deny the registration.

Name	Type	Required	Description
context	Record<string, unknown>	Yes	Auth context from AuthResult.context for this session.
description	string	No	Human-readable description of the function.
function_id	string	Yes	ID of the function being registered.
metadata	Record<string, unknown>	No	Arbitrary metadata attached to the function.
namespace	string	No	Namespace the function registers in. The same id can exist in several namespaces, so the hook needs this to authorize per namespace.

---

OnFunctionRegistrationResult

Result returned from the on_function_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
description	string	No	Mapped description.
function_id	string	No	Mapped function ID.
metadata	Record<string, unknown>	No	Mapped metadata.

---

OnTriggerRegistrationInput

Input passed to the on_trigger_registration_function_id hook when a worker attempts to register a trigger through the RBAC port. Return an OnTriggerRegistrationResult with the (possibly mapped) fields, or throw to deny the registration.

Name	Type	Required	Description
config	unknown	Yes	Trigger-specific configuration.
context	Record<string, unknown>	Yes	Auth context from AuthResult.context for this session.
function_id	string	Yes	ID of the function this trigger is bound to.
namespace	string	No	Namespace the trigger’s target resolves in (explicit, or default when absent). The same id can exist in several namespaces, so the hook needs this to authorize per target namespace.
trigger_id	string	Yes	ID of the trigger being registered.
trigger_type	string	Yes	Trigger type identifier.

---

OnTriggerRegistrationResult

Result returned from the on_trigger_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
config	unknown	No	Mapped trigger configuration.
function_id	string	No	Mapped function ID.
trigger_id	string	No	Mapped trigger ID.
trigger_type	string	No	Mapped trigger type.

---

OnTriggerTypeRegistrationInput

Input passed to the on_trigger_type_registration_function_id hook when a worker attempts to register a new trigger type through the RBAC port. Return an OnTriggerTypeRegistrationResult with the (possibly mapped) fields, or throw to deny the registration.

Name	Type	Required	Description
context	Record<string, unknown>	Yes	Auth context from AuthResult.context for this session.
description	string	Yes	Human-readable description of the trigger type.
trigger_type_id	string	Yes	ID of the trigger type being registered.

---

OnTriggerTypeRegistrationResult

Result returned from the on_trigger_type_registration_function_id hook. All fields are optional; omitted fields keep the original value from the registration request.

Name	Type	Required	Description
description	string	No	Mapped description.
trigger_type_id	string	No	Mapped trigger type ID.

---

OpenEnum

A wire enum that a newer peer may extend: decoders keep a value they do not know instead of failing the frame.

type OpenEnum = T | string & object

---

RegisterFunctionFormat

Name	Type	Required	Description
description	string	No	The description of the parameter
items	unknown	No	The items of the parameter (for arrays)
name	string	No	The name of the parameter
properties	Record<string, unknown>	No	The body of the parameter (for objects)
required	string[]	No	Whether the parameter is required
type	"string" | "number" | "boolean" | "object" | "array" | "null" | "map" | "integer"	No	The type of the parameter
[key: string]	unknown	No	-

---

RegisterFunctionInput

type RegisterFunctionInput = Omit<RegisterFunctionMessage, "message_type">

Name	Type	Required	Description
description	string	No	The description of the function
id	string	Yes	The path of the function (use :: for namespacing, e.g. external::my_lambda)
metadata	Record<string, unknown>	No	-
observe	ObserveDescriptorWire	No	The observe descriptor: how observers of this function are delivered. Only these four fields travel; the hooks stay in the SDK.
request_format	RegisterFunctionFormat	No	The request format of the function
response_format	RegisterFunctionFormat	No	The response format of the function

---

RegisterFunctionMessage

Name	Type	Required	Description
description	string	No	The description of the function
id	string	Yes	The path of the function (use :: for namespacing, e.g. external::my_lambda)
message_type	MessageType.RegisterFunction	Yes	-
metadata	Record<string, unknown>	No	-
observe	ObserveDescriptorWire	No	The observe descriptor: how observers of this function are delivered. Only these four fields travel; the hooks stay in the SDK.
request_format	RegisterFunctionFormat	No	The request format of the function
response_format	RegisterFunctionFormat	No	The response format of the function

---

RegisterFunctionOptions

Options of ISdk.registerFunction: description, request/response formats, metadata, and the observe hooks.

type RegisterFunctionOptions = Omit<RegisterFunctionMessage, "message_type" | "id" | "observe"> & { localDispatch?: boolean; observe?: ObserveHooks }

Name	Type	Required	Description
description	string	No	The description of the function
localDispatch	boolean	No	Calls this worker makes to its own function run in-process once the engine confirmed it (default true). Set false for a handler that must always run through the engine.
metadata	Record<string, unknown>	No	-
observe	ObserveHooks	No	Makes the function observable on its own terms: owner delivery (delivery: 'owner', args_format), and callbacks when an observer is added or removed. Without it the function is still observable (auto delivery, no args).
request_format	RegisterFunctionFormat	No	The request format of the function
response_format	RegisterFunctionFormat	No	The response format of the function

---

RegistrationRejectedError

A terminal registration rejection from the engine. Thrown into every pending invocation and exposed via getFatalError() when a worker-name collision (or other non-retryable rejection) closes the connection for good.

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
namespace	string	Yes	-
owner_worker_id	string	Yes	-
worker_name	string	No	-

---

RegistrationRejectedInit

Name	Type	Required	Description
code	string	Yes	-
function_id	string	No	-
namespace	string	Yes	-
owner_worker_id	string	Yes	-
worker_name	string	No	-

---

RemoteFunctionHandler

Async function handler for a registered function. Receives the invocation payload and its metadata (TriggerRequest.metadata of the call, or an observer’s metadata sidecar on an activation) and returns the result.

type RemoteFunctionHandler = (data: TInput, metadata?: unknown) => Promise<TOutput>

---

StreamChannelRef

Serializable reference to one end of a streaming channel. Can be included in invocation payloads to pass channel endpoints between workers.

Name	Type	Required	Description
access_key	string	Yes	Access key for authentication.
channel_id	string	Yes	Unique channel identifier.
direction	"read" | "write"	Yes	Whether this ref is for reading or writing.

---

Target

The right side of iii.observe: a registered function.

type Target = string | { function_id: string; namespace?: string }

---

TriggerAction

Factory object that constructs routing actions for ISdk.trigger.

Name	Type	Required	Description
Enqueue	(opts: { queue: string }) => { queue: string; type: "enqueue" }	Yes	Routes the invocation through a named queue. The engine enqueues the job, acknowledges the caller with { messageReceiptId }, and processes it asynchronously.
Void	() => { type: "void" }	Yes	Fire-and-forget routing. The engine forwards the invocation without waiting for a response or queuing the job.

---

TriggerRequest

Request object passed to ISdk.trigger.

Name	Type	Required	Description
action	TriggerAction	No	Sets how the trigger is routed. Omit for a synchronous request/response. Specify for a specific routing scheme (e.g. TriggerAction.Enqueue(), TriggerAction.Void()).
baggage	string	No	W3C baggage to send along with traceparent; defaults the same way.
dispatch	"auto" | "remote"	No	auto (default) runs a function this worker hosts in-process when the engine confirmed it for local dispatch; remote always goes through the engine. Tests use it, and so do callers that rely on engine-side effects.
function_id	string	Yes	ID of the function to invoke.
metadata	unknown	No	Per-invocation metadata (any JSON). Travels beside the payload: the handler receives it as its second argument, and observer filters read it as metadata.*.
namespace	string	No	Namespace to route this invocation to. Omit to inherit this worker’s; say default to reach the engine’s from a namespaced worker.
payload	TInput	Yes	Input data passed to the function.
timeoutMs	number	No	Override the default invocation timeout, in milliseconds.
traceparent	string	No	W3C traceparent to continue. The browser SDK has no OpenTelemetry, so it never makes one up: when omitted, a call made inside a handler forwards the traceparent that handler was invoked with (see ISdk.currentInvocation); a top-level call sends none and the engine starts the trace.

iii-browser-sdk/state

DeleteResult · IState · StateDeleteInput · StateDeleteResult · StateEventData · StateEventType · StateGetInput · StateListInput · StateSetInput · StateSetResult · StateUpdateInput · StateUpdateResult

DeleteResult

Result of a state delete operation.

Name	Type	Required	Description
old_value	any	No	Previous value (if it existed).

---

IState

Interface for state management operations. Available via the iii-browser-sdk/state subpath export.

Name	Type	Required	Description
delete	(input: StateDeleteInput) => Promise<DeleteResult>	Yes	Delete a state value.
get	(input: StateGetInput) => Promise<TData | null>	Yes	Retrieve a value by scope and key.
list	(input: StateListInput) => Promise<TData[]>	Yes	List all values in a scope.
set	(input: StateSetInput) => Promise<StateSetResult<TData> | null>	Yes	Set (create or overwrite) a state value.
update	(input: StateUpdateInput) => Promise<StateUpdateResult<TData> | null>	Yes	Apply atomic update operations to a state value.

---

StateDeleteInput

Input for deleting a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).

---

StateDeleteResult

Result of a state delete operation.

Name	Type	Required	Description
old_value	any	No	Previous value (if it existed).

---

StateEventData

Payload for state change events.

Name	Type	Required	Description
event_type	StateEventType	Yes	Type of state change.
key	string	Yes	Key within the scope.
new_value	TData	No	New value (for create/update events).
old_value	TData	No	Previous value (for update/delete events).
scope	string	Yes	State scope (namespace).
type	"state"	Yes	-

---

StateEventType

Types of state change events.

Name	Type	Required	Description
Created	"state:created"	Yes	-
Deleted	"state:deleted"	Yes	-
Updated	"state:updated"	Yes	-

---

StateGetInput

Input for retrieving a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).

---

StateListInput

Input for listing all values in a state scope.

Name	Type	Required	Description
scope	string	Yes	State scope (namespace).

---

StateSetInput

Input for setting a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
scope	string	Yes	State scope (namespace).
value	any	Yes	Value to store.

---

StateSetResult

Result of a state set operation.

Name	Type	Required	Description
new_value	TData	Yes	New value that was stored.
old_value	TData	No	Previous value (if it existed).

---

StateUpdateInput

Input for atomically updating a state value.

Name	Type	Required	Description
key	string	Yes	Key within the scope.
ops	UpdateOp[]	Yes	Ordered list of update operations to apply atomically.
scope	string	Yes	State scope (namespace).

---

StateUpdateResult

Result of a state update operation.

Name	Type	Required	Description
errors	UpdateOpError[]	No	Per-op errors. Currently emitted only by the merge op when input violates validation bounds. Field omitted when empty.
new_value	TData	Yes	New value after the update.
old_value	TData	No	Previous value (if it existed).

iii-browser-sdk/stream

IStream · MergePath · StreamAuthInput · StreamAuthResult · StreamChangeEvent · StreamContext · StreamDeleteInput · StreamGetInput · StreamJoinLeaveEvent · StreamJoinLeaveTriggerConfig · StreamJoinResult · StreamListGroupsInput · StreamListInput · StreamSetInput · StreamSetResult · StreamTriggerConfig · StreamUpdateInput · StreamUpdateResult · UpdateAppend · UpdateDecrement · UpdateIncrement · UpdateMerge · UpdateOp · UpdateOpError · UpdateRemove · UpdateSet

IStream

Interface for custom stream implementations. Passed to ISdk.createStream to override the engine’s built-in stream storage.

Name	Type	Required	Description
delete	(input: StreamDeleteInput) => Promise<DeleteResult>	Yes	Delete a stream item.
get	(input: StreamGetInput) => Promise<TData | null>	Yes	Retrieve a single item by group and item ID.
list	(input: StreamListInput) => Promise<TData[]>	Yes	List all items in a group.
listGroups	(input: StreamListGroupsInput) => Promise<string[]>	Yes	List all group IDs in a stream.
set	(input: StreamSetInput) => Promise<StreamSetResult<TData> | null>	Yes	Set (create or overwrite) a stream item.
update	(input: StreamUpdateInput) => Promise<StreamUpdateResult<TData> | null>	Yes	Apply atomic update operations to a stream item.

---

MergePath

Path target for a UpdateMerge op. Accepts:

• a single string (legacy / first-level field)
• an array of literal segments (nested path; each element is one literal key, dots are NOT interpreted as separators)

Omit path, pass "", or pass [] to target the root value.

type MergePath = string | string[]

---

StreamAuthInput

Input for stream authentication.

Name	Type	Required	Description
addr	string	Yes	Client address.
headers	Record<string, string>	Yes	Request headers.
path	string	Yes	Request path.
query_params	Record<string, string[]>	Yes	Query parameters.

---

StreamAuthResult

Result of stream authentication.

Name	Type	Required	Description
context	any	No	Arbitrary context passed to stream handlers after authentication.

---

StreamChangeEvent

Handler input for stream triggers, fired when an item changes via stream::set, stream::update, or stream::delete.

Name	Type	Required	Description
event	{ data: any; type: "create" | "update" | "delete" }	Yes	The event detail object containing type and data fields.
groupId	string	Yes	The group where the change occurred.
id	string	No	The item ID that changed.
streamName	string	Yes	The stream where the change occurred.
timestamp	number	Yes	Unix timestamp of the event.
type	"stream"	Yes	The event type.

---

StreamContext

Context type extracted from StreamAuthResult.

type StreamContext = StreamAuthResult["context"]

---

StreamDeleteInput

Input for deleting a stream item.

Name	Type	Required	Description
group_id	string	Yes	Group identifier.
item_id	string	Yes	Item identifier.
stream_name	string	Yes	Name of the stream.

---

StreamGetInput

Input for retrieving a single stream item.

Name	Type	Required	Description
group_id	string	Yes	Group identifier.
item_id	string	Yes	Item identifier.
stream_name	string	Yes	Name of the stream.

---

StreamJoinLeaveEvent

Event payload for stream join/leave events.

Name	Type	Required	Description
context	any	No	Auth context from StreamAuthResult.
group_id	string	Yes	Group identifier.
id	string	No	Item identifier (if applicable).
stream_name	string	Yes	Name of the stream.
subscription_id	string	Yes	Unique subscription identifier.

---

StreamJoinLeaveTriggerConfig

Trigger config for stream:join and stream:leave triggers.

Name	Type	Required	Description
condition_function_id	string	No	Function ID for conditional execution. If it returns false, the handler is skipped.

---

StreamJoinResult

Result of a stream join request.

Name	Type	Required	Description
unauthorized	boolean	Yes	Whether the join was unauthorized.

---

StreamListGroupsInput

Input for listing all groups in a stream.

Name	Type	Required	Description
stream_name	string	Yes	Name of the stream.

---

StreamListInput

Input for listing all items in a stream group.

Name	Type	Required	Description
group_id	string	Yes	Group identifier.
stream_name	string	Yes	Name of the stream.

---

StreamSetInput

Input for setting a stream item.

Name	Type	Required	Description
data	any	Yes	Data to store.
group_id	string	Yes	Group identifier.
item_id	string	Yes	Item identifier.
stream_name	string	Yes	Name of the stream.

---

StreamSetResult

Result of a stream set operation.

Name	Type	Required	Description
new_value	TData	Yes	New value that was stored.
old_value	TData	No	Previous value (if it existed).

---

StreamTriggerConfig

Trigger config for stream triggers. Filters which item changes fire the handler.

Name	Type	Required	Description
condition_function_id	string	No	Function ID for conditional execution. If it returns false, the handler is skipped.
group_id	string	No	If set, only changes within this group fire the handler.
item_id	string	No	If set, only changes to this specific item fire the handler.
stream_name	string	Yes	Stream name to watch. Only changes on this stream fire the handler.

---

StreamUpdateInput

Input for atomically updating a stream item.

Name	Type	Required	Description
group_id	string	Yes	Group identifier.
item_id	string	Yes	Item identifier.
ops	UpdateOp[]	Yes	Ordered list of update operations to apply atomically.
stream_name	string	Yes	Name of the stream.

---

StreamUpdateResult

Result of a stream update operation.

Name	Type	Required	Description
errors	UpdateOpError[]	No	Per-op errors. Emitted by merge and append for validation rejections (path/value bounds, proto-pollution segments) and by append for the append.type_mismatch and append.target_not_object surfaces. Field omitted when empty.
new_value	TData	Yes	New value after the update.
old_value	TData	No	Previous value (if it existed).

---

UpdateAppend

Append an element to an array, concatenate a string, or push a new value at a nested path. The target is the root (when path is omitted, empty, or []), a single first-level key (when path is a non-empty string), or an arbitrary nested location (when path is an array of literal segments). See MergePath.

Engine semantics: missing/null intermediates along a nested path are auto-created; missing leaves on a nested path always become arrays (no string-concat tier); existing object/scalar leaves return append.type_mismatch. Each path segment is a literal key, ["a.b"] targets a single key named "a.b", not a → b.

Name	Type	Required	Description
path	MergePath	No	Optional path to the append target. Accepts a single first-level key (legacy string) or an array of literal segments for nested append. See MergePath (the same shape is reused).
type	"append"	Yes	-
value	any	Yes	Value to append. String targets only accept string values.

---

UpdateDecrement

Decrement a numeric field by a given amount.

Name	Type	Required	Description
by	number	Yes	Amount to decrement by.
path	string	Yes	First-level field path.
type	"decrement"	Yes	-

---

UpdateIncrement

Increment a numeric field by a given amount.

Name	Type	Required	Description
by	number	Yes	Amount to increment by.
path	string	Yes	First-level field path.
type	"increment"	Yes	-

---

UpdateMerge

Shallow-merge an object into the target. The target is the root (when path is omitted/empty) or an arbitrary nested location specified by an array of literal segments. See MergePath.

Validation: invalid paths/values (depth > 32, segment > 256 bytes, value depth > 16, > 1024 top-level keys, or any __proto__/constructor/prototype segment or top-level key) are rejected with a structured error in the response’s errors array.

Name	Type	Required	Description
path	MergePath	No	Optional path to the merge target. See MergePath.
type	"merge"	Yes	-
value	any	Yes	Object to merge. Must be a JSON object.

---

UpdateOp

Union of all atomic update operations supported by streams.

type UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge

---

UpdateOpError

Per-op error returned by state::update / stream::update.

Name	Type	Required	Description
code	string	Yes	Stable error code, e.g. "merge.path.too_deep".
doc_url	string	No	Optional documentation URL.
message	string	Yes	Human-readable description with concrete numbers when applicable.
op_index	number	Yes	Index of the offending op within the original ops array.

---

UpdateRemove

Remove a field at the given path.

Name	Type	Required	Description
path	string	Yes	First-level field path.
type	"remove"	Yes	-

---

UpdateSet

Set a field at the given path to a value.

Name	Type	Required	Description
path	string	Yes	First-level field path. Use an empty string to target the root value.
type	"set"	Yes	-
value	any	Yes	Value to set.