> ## Documentation Index > Fetch the complete documentation index at: https://iii.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Browser SDK > API reference for the iii SDK for Browser / TypeScript. {/* AI: any skill-check (vale/AI) text fixes belong in the source doc-comments under sdk/packages/node/iii-browser/src (prose) or docs/next/scripts/ (structure/formatting), then regenerate. Never edit this file directly. */} ## Installation ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} npm install iii-browser-sdk ``` ## Initialization ### registerWorker Creates and returns a connected SDK instance. The WebSocket connection is established automatically -- there is no separate `connect()` call. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} registerWorker(address: string, options: InitOptions) => ISdk ``` #### Parameters | Name | Type | Required | Description | | --------- | ----------------------------- | -------- | ----------------------------------------------------------------- | | `address` | `string` | Yes | WebSocket URL of the III engine (e.g. `ws://localhost:49135`). | | `options` | [`InitOptions`](#initoptions) | Yes | Optional InitOptions for worker name, timeouts, and reconnection. | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} import { registerWorker } from 'iii-browser-sdk' const worker = registerWorker('ws://localhost:49135') ``` ## Methods ### registerTrigger Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} registerTrigger(trigger: RegisterTriggerInput) => Trigger ``` #### Parameters | Name | Type | Required | Description | | --------- | ----------------------------------------------- | -------- | ----------------------- | | `trigger` | [`RegisterTriggerInput`](#registertriggerinput) | Yes | The trigger to register | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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 handler or an HTTP invocation config. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} registerFunction(functionId: string, handler: RemoteFunctionHandler, options: RegisterFunctionOptions) => FunctionRef ``` #### Parameters | Name | Type | Required | Description | | ------------ | ----------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `functionId` | `string` | Yes | Unique function identifier | | `handler` | [`RemoteFunctionHandler`](#remotefunctionhandler) | Yes | Async handler for local execution, or an HTTP invocation config for external functions (Lambda, Cloudflare Workers, etc.) | | `options` | [`RegisterFunctionOptions`](#registerfunctionoptions) | Yes | Optional function registration options (description, request/response formats, metadata) | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} // 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** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} trigger(request: TriggerRequest) => Promise ``` #### Parameters | Name | Type | Required | Description | | --------- | -------------------------------------------- | -------- | --------------------------------------------------------------------------------- | | `request` | [`TriggerRequest`](#triggerrequest)\ | Yes | The trigger request containing function\_id, payload, and optional action/timeout | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} // 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: 'user@example.com' }, action: TriggerAction.Void(), }) // Enqueue for async processing const receipt = await worker.trigger({ function_id: 'process-order', payload: { orderId: '123' }, action: TriggerAction.Enqueue({ queue: 'orders' }), }) ``` ### registerTriggerType Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} registerTriggerType(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler) => TriggerTypeRef ``` #### Parameters | Name | Type | Required | Description | | ------------- | ------------------------------------------------------- | -------- | -------------------------------- | | `triggerType` | [`RegisterTriggerTypeInput`](#registertriggertypeinput) | Yes | The trigger type to register | | `handler` | [`TriggerHandler`](#triggerhandler)\ | Yes | The handler for the trigger type | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type CronConfig = { expression: string } worker.registerTriggerType( { 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 Unregisters a trigger type. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} unregisterTriggerType(triggerType: RegisterTriggerTypeInput) => void ``` #### Parameters | Name | Type | Required | Description | | ------------- | ------------------------------------------------------- | -------- | ------------------------------ | | `triggerType` | [`RegisterTriggerTypeInput`](#registertriggertypeinput) | Yes | The trigger type to unregister | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} addConnectionStateListener(handler: (state: IIIConnectionState) => void) => () => void ``` #### Parameters | Name | Type | Required | Description | | --------- | ------------------------------------------------------------ | -------- | ----------- | | `handler` | (state: [`IIIConnectionState`](#iiiconnectionstate)) => void | Yes | - | #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} const unsub = worker.addConnectionStateListener((state) => { console.log('connection state:', state) }) // Later, stop receiving updates unsub() ``` ### shutdown Gracefully shutdown the iii, cleaning up all resources. **Signature** ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} shutdown() => Promise ``` #### Example ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} await worker.shutdown() ``` ## Subpath Exports The `iii-browser-sdk` package provides additional entry points: | Import path | Contents | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `iii-browser-sdk` | `ApiRequest`, `ApiResponse`, `AuthInput`, `AuthResult`, `Channel`, `ChannelReader`, `ChannelWriter`, `EngineFunctions`, `EngineTriggers`, `EnqueueResult`, etc. | | `iii-browser-sdk/state` | `DeleteResult`, `IState`, `StateDeleteInput`, `StateDeleteResult`, `StateEventData`, `StateEventType`, `StateGetInput`, `StateListInput`, `StateSetInput`, `StateSetResult`, etc. | | `iii-browser-sdk/stream` | `DeleteResult`, `IStream`, `MergePath`, `StreamAuthInput`, `StreamAuthResult`, `StreamChangeEvent`, `StreamContext`, `StreamDeleteInput`, `StreamGetInput`, `StreamJoinLeaveEvent`, etc. | ## Types ### iii-browser-sdk [`ApiRequest`](#apirequest) · [`ApiResponse`](#apiresponse) · [`AuthInput`](#authinput) · [`AuthResult`](#authresult) · [`Channel`](#channel) · [`ChannelReader`](#channelreader) · [`ChannelWriter`](#channelwriter) · [`EnqueueResult`](#enqueueresult) · [`FunctionRef`](#functionref) · [`IIIConnectionState`](#iiiconnectionstate) · [`InitOptions`](#initoptions) · [`MessageType`](#messagetype) · [`MiddlewareFunctionInput`](#middlewarefunctioninput) · [`OnFunctionRegistrationInput`](#onfunctionregistrationinput) · [`OnFunctionRegistrationResult`](#onfunctionregistrationresult) · [`OnTriggerRegistrationInput`](#ontriggerregistrationinput) · [`OnTriggerRegistrationResult`](#ontriggerregistrationresult) · [`OnTriggerTypeRegistrationInput`](#ontriggertyperegistrationinput) · [`OnTriggerTypeRegistrationResult`](#ontriggertyperegistrationresult) · [`RegisterFunctionInput`](#registerfunctioninput) · [`RegisterFunctionMessage`](#registerfunctionmessage) · [`RegisterFunctionOptions`](#registerfunctionoptions) · [`RegisterTriggerInput`](#registertriggerinput) · [`RegisterTriggerMessage`](#registertriggermessage) · [`RegisterTriggerTypeInput`](#registertriggertypeinput) · [`RegisterTriggerTypeMessage`](#registertriggertypemessage) · [`RemoteFunctionHandler`](#remotefunctionhandler) · [`StreamChannelRef`](#streamchannelref) · [`Trigger`](#trigger) · [`TriggerConfig`](#triggerconfig) · [`TriggerHandler`](#triggerhandler) · [`TriggerRequest`](#triggerrequest) · [`TriggerTypeRef`](#triggertyperef) #### ApiRequest Incoming HTTP request received by a function registered with an HTTP trigger. | Name | Type | Required | Description | | -------------- | ------------------------------------ | -------- | ----------- | | `body` | `TBody` | Yes | - | | `headers` | `Record` | Yes | - | | `method` | `string` | Yes | - | | `path_params` | `Record` | Yes | - | | `query_params` | `Record` | Yes | - | #### ApiResponse Structured API response returned from HTTP function handlers. | Name | Type | Required | Description | | ------------- | ------------------------ | -------- | ----------------- | | `body` | `TBody` | No | Response body. | | `headers` | `Record` | 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` | Yes | HTTP headers from the WebSocket upgrade request. | | `ip_address` | `string` | Yes | IP address of the connecting client. | | `query_params` | `Record` | 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. 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` | 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. | #### 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`](#channelreader) | Yes | Reader end of the channel. | | `readerRef` | [`StreamChannelRef`](#streamchannelref) | Yes | Serializable reference to the reader (can be sent to other workers). | | `writer` | [`ChannelWriter`](#channelwriter) | Yes | Writer end of the channel. | | `writerRef` | [`StreamChannelRef`](#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. #### 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. | #### 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. | | `unregister` | `() => void` | Yes | Removes this function from the engine. | #### IIIConnectionState Connection state for the III WebSocket ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type IIIConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting" | "failed" ``` #### InitOptions Configuration options passed to registerWorker. | Name | Type | Required | Description | | --------------------- | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | `headers` | `Record` | No | Custom headers are not supported by browser WebSocket. Use query parameters or cookies for auth. | | `invocationTimeoutMs` | `number` | No | Default timeout for `trigger()` in milliseconds. Defaults to `30000`. | | `reconnectionConfig` | `Partial` | No | WebSocket reconnection behavior. | #### MessageType | Name | Type | Required | Description | | --------------------------- | ----------------------------- | -------- | ----------- | | `InvocationResult` | `"invocationresult"` | Yes | - | | `InvokeFunction` | `"invokefunction"` | Yes | - | | `RegisterFunction` | `"registerfunction"` | Yes | - | | `RegisterTrigger` | `"registertrigger"` | Yes | - | | `RegisterTriggerType` | `"registertriggertype"` | Yes | - | | `TriggerRegistrationResult` | `"triggerregistrationresult"` | Yes | - | | `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` | Yes | Auth context returned by the auth function for this session. | | `function_id` | `string` | Yes | ID of the function being invoked. | | `payload` | `Record` | Yes | Payload sent by the caller. | #### 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` | 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` | No | Arbitrary metadata attached to the function. | #### 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` | 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` | Yes | Auth context from `AuthResult.context` for this session. | | `function_id` | `string` | Yes | ID of the function this trigger is bound to. | | `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` | 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. | #### RegisterFunctionInput ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type RegisterFunctionInput = Omit ``` #### 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`](#messagetype).RegisterFunction | Yes | - | | `metadata` | `Record` | No | - | | `request_format` | `RegisterFunctionFormat` | No | The request format of the function | | `response_format` | `RegisterFunctionFormat` | No | The response format of the function | #### RegisterFunctionOptions ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type RegisterFunctionOptions = Omit ``` #### RegisterTriggerInput ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type RegisterTriggerInput = Omit ``` #### RegisterTriggerMessage | Name | Type | Required | Description | | -------------- | --------------------------------------------- | -------- | ----------- | | `config` | `unknown` | Yes | - | | `function_id` | `string` | Yes | - | | `id` | `string` | Yes | - | | `message_type` | [`MessageType`](#messagetype).RegisterTrigger | Yes | - | | `type` | `string` | Yes | - | #### RegisterTriggerTypeInput ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type RegisterTriggerTypeInput = Omit ``` #### RegisterTriggerTypeMessage | Name | Type | Required | Description | | -------------- | ------------------------------------------------- | -------- | ----------- | | `description` | `string` | Yes | - | | `id` | `string` | Yes | - | | `message_type` | [`MessageType`](#messagetype).RegisterTriggerType | Yes | - | #### RemoteFunctionHandler Async function handler for a registered function. Receives the invocation payload and returns the result. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type RemoteFunctionHandler = (data: TInput) => Promise ``` #### 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. | #### Trigger Handle returned by ISdk.registerTrigger. Use `unregister()` to remove the trigger from the engine. | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------- | | `unregister` | `void` | Yes | Removes this trigger from the engine. | #### TriggerConfig Configuration passed to a trigger handler when a trigger instance is registered or unregistered. | Name | Type | Required | Description | | ------------- | --------- | -------- | ------------------------------------------ | | `config` | `TConfig` | Yes | Trigger-specific configuration. | | `function_id` | `string` | Yes | Function to invoke when the trigger fires. | | `id` | `string` | Yes | Trigger instance ID. | #### TriggerHandler Handler interface for custom trigger types. Passed to `ISdk.registerTriggerType`. | Name | Type | Required | Description | | ------------------- | --------------- | -------- | ----------------------------------------------- | | `registerTrigger` | `Promise` | Yes | Called when a trigger instance is registered. | | `unregisterTrigger` | `Promise` | Yes | Called when a trigger instance is unregistered. | #### TriggerRequest Request object passed to ISdk.trigger. | Name | Type | Required | Description | | ------------- | --------------- | -------- | -------------------------------------------------------- | | `action` | `TriggerAction` | No | Routing action. Omit for synchronous request/response. | | `function_id` | `string` | Yes | ID of the function to invoke. | | `payload` | `TInput` | Yes | Payload to pass to the function. | | `timeoutMs` | `number` | No | Override the default invocation timeout in milliseconds. | #### TriggerTypeRef Typed handle returned by ISdk.registerTriggerType. Provides convenience methods to register triggers and functions scoped to this trigger type, so callers don't need to repeat the `type` field. | Name | Type | Required | Description | | ------------------ | ----------------------------- | -------- | ----------------------------------------------------------------- | | `id` | `string` | Yes | The trigger type identifier. | | `registerFunction` | [`FunctionRef`](#functionref) | Yes | Register a function and immediately bind it to this trigger type. | | `registerTrigger` | [`Trigger`](#trigger) | Yes | Register a trigger bound to this trigger type. | | `unregister` | `void` | Yes | Unregister this trigger type from the engine. | ### iii-browser-sdk/state [`DeleteResult`](#deleteresult) · [`IState`](#istate) · [`StateDeleteInput`](#statedeleteinput) · [`StateDeleteResult`](#statedeleteresult) · [`StateEventData`](#stateeventdata) · [`StateEventType`](#stateeventtype) · [`StateGetInput`](#stategetinput) · [`StateListInput`](#statelistinput) · [`StateSetInput`](#statesetinput) · [`StateSetResult`](#statesetresult) · [`StateUpdateInput`](#stateupdateinput) · [`StateUpdateResult`](#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-sdk/state` subpath export. | Name | Type | Required | Description | | -------- | ------------------------------------------------------------------- | -------- | ------------------------------------------------ | | `delete` | Promise\<[`DeleteResult`](#deleteresult)> | Yes | Delete a state value. | | `get` | `Promise` | Yes | Retrieve a value by scope and key. | | `list` | `Promise` | Yes | List all values in a scope. | | `set` | Promise\<[`StateSetResult`](#statesetresult)\ \| null> | Yes | Set (create or overwrite) a state value. | | `update` | Promise\<[`StateUpdateResult`](#stateupdateresult)\ \| 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`](#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`](#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`](#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`](#istream) · [`MergePath`](#mergepath) · [`StreamAuthInput`](#streamauthinput) · [`StreamAuthResult`](#streamauthresult) · [`StreamChangeEvent`](#streamchangeevent) · [`StreamContext`](#streamcontext) · [`StreamDeleteInput`](#streamdeleteinput) · [`StreamGetInput`](#streamgetinput) · [`StreamJoinLeaveEvent`](#streamjoinleaveevent) · [`StreamJoinLeaveTriggerConfig`](#streamjoinleavetriggerconfig) · [`StreamJoinResult`](#streamjoinresult) · [`StreamListGroupsInput`](#streamlistgroupsinput) · [`StreamListInput`](#streamlistinput) · [`StreamSetInput`](#streamsetinput) · [`StreamSetResult`](#streamsetresult) · [`StreamTriggerConfig`](#streamtriggerconfig) · [`StreamUpdateInput`](#streamupdateinput) · [`StreamUpdateResult`](#streamupdateresult) · [`UpdateAppend`](#updateappend) · [`UpdateDecrement`](#updatedecrement) · [`UpdateIncrement`](#updateincrement) · [`UpdateMerge`](#updatemerge) · [`UpdateOp`](#updateop) · [`UpdateOpError`](#updateoperror) · [`UpdateRemove`](#updateremove) · [`UpdateSet`](#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` | Promise\<[`DeleteResult`](#deleteresult)> | Yes | Delete a stream item. | | `get` | `Promise` | Yes | Retrieve a single item by group and item ID. | | `list` | `Promise` | Yes | List all items in a group. | | `listGroups` | `Promise` | Yes | List all group IDs in a stream. | | `set` | Promise\<[`StreamSetResult`](#streamsetresult)\ \| null> | Yes | Set (create or overwrite) a stream item. | | `update` | Promise\<[`StreamUpdateResult`](#streamupdateresult)\ \| 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. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} type MergePath = string | string[] ``` #### StreamAuthInput Input for stream authentication. | Name | Type | Required | Description | | -------------- | -------------------------- | -------- | ----------------- | | `addr` | `string` | Yes | Client address. | | `headers` | `Record` | Yes | Request headers. | | `path` | `string` | Yes | Request path. | | `query_params` | `Record` | 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. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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`](#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`](#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`](#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`](#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. ```typescript theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} 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. |