iii-browser-sdk 0.10.0

package/dist/index.d.cts

@@ -0,0 +1,839 @@
+import { n as IStream } from "./stream-B4Etd7Hp.cjs";
+
+//#region src/iii-types.d.ts
+declare enum MessageType {
+  RegisterFunction = "registerfunction",
+  UnregisterFunction = "unregisterfunction",
+  RegisterService = "registerservice",
+  InvokeFunction = "invokefunction",
+  InvocationResult = "invocationresult",
+  RegisterTriggerType = "registertriggertype",
+  RegisterTrigger = "registertrigger",
+  UnregisterTrigger = "unregistertrigger",
+  UnregisterTriggerType = "unregistertriggertype",
+  TriggerRegistrationResult = "triggerregistrationresult",
+  WorkerRegistered = "workerregistered"
+}
+type RegisterTriggerTypeMessage = {
+  message_type: MessageType.RegisterTriggerType;
+  id: string;
+  description: string;
+};
+type RegisterTriggerMessage = {
+  message_type: MessageType.RegisterTrigger;
+  id: string;
+  type: string;
+  function_id: string;
+  config: unknown;
+};
+type RegisterServiceMessage = {
+  message_type: MessageType.RegisterService;
+  id: string;
+  name?: string;
+  description?: string;
+  parent_service_id?: string;
+};
+/**
+ * Authentication configuration for HTTP-invoked functions.
+ *
+ * - `hmac` -- HMAC signature verification using a shared secret.
+ * - `bearer` -- Bearer token authentication.
+ * - `api_key` -- API key sent via a custom header.
+ */
+type HttpAuthConfig = {
+  type: 'hmac';
+  secret_key: string;
+} | {
+  type: 'bearer';
+  token_key: string;
+} | {
+  type: 'api_key';
+  header: string;
+  value_key: string;
+};
+/**
+ * Configuration for registering an HTTP-invoked function (Lambda, Cloudflare
+ * Workers, etc.) instead of a local handler.
+ */
+type HttpInvocationConfig = {
+  /** URL to invoke. */url: string; /** HTTP method. Defaults to `POST`. */
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; /** Timeout in milliseconds. */
+  timeout_ms?: number; /** Custom headers to send with the request. */
+  headers?: Record<string, string>; /** Authentication configuration. */
+  auth?: HttpAuthConfig;
+};
+type RegisterFunctionFormat = {
+  /**
+   * The name of the parameter
+   */
+  name?: string;
+  /**
+   * The description of the parameter
+   */
+  description?: string;
+  /**
+   * The type of the parameter
+   */
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null' | 'map';
+  /**
+   * The body of the parameter
+   */
+  properties?: Record<string, RegisterFunctionFormat>;
+  /**
+   * The items of the parameter
+   */
+  items?: RegisterFunctionFormat;
+  /**
+   * Whether the parameter is required
+   */
+  required?: string[];
+};
+type RegisterFunctionMessage = {
+  message_type: MessageType.RegisterFunction;
+  /**
+   * The path of the function (use :: for namespacing, e.g. external::my_lambda)
+   */
+  id: string;
+  /**
+   * The description of the function
+   */
+  description?: string;
+  /**
+   * The request format of the function
+   */
+  request_format?: RegisterFunctionFormat;
+  /**
+   * The response format of the function
+   */
+  response_format?: RegisterFunctionFormat;
+  metadata?: Record<string, unknown>;
+  /**
+   * HTTP invocation config for external HTTP functions (Lambda, Cloudflare Workers, etc.)
+   */
+  invocation?: HttpInvocationConfig;
+};
+/**
+ * Routing action for {@link TriggerRequest}. Determines how the engine
+ * handles the invocation.
+ *
+ * - `enqueue` -- Routes through a named queue for async processing.
+ * - `void` -- Fire-and-forget, no response.
+ */
+type TriggerAction$1 = {
+  type: 'enqueue';
+  queue: string;
+} | {
+  type: 'void';
+};
+/**
+ * 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.
+ */
+type AuthInput = {
+  /** HTTP headers from the WebSocket upgrade request. */headers: Record<string, string>; /** Query parameters from the upgrade URL. Each key maps to an array of values to support repeated keys. */
+  query_params: Record<string, string[]>; /** IP address of the connecting client. */
+  ip_address: string;
+};
+/**
+ * Return value from the RBAC auth function. Controls which functions the
+ * authenticated worker can invoke and what context is forwarded to the
+ * middleware.
+ */
+type AuthResult = {
+  /** Additional function IDs to allow beyond the `expose_functions` config. */allowed_functions: string[]; /** Function IDs to deny even if they match `expose_functions`. Takes precedence over allowed. */
+  forbidden_functions: string[]; /** Trigger type IDs the worker may register triggers for. When omitted, all types are allowed. */
+  allowed_trigger_types?: string[]; /** Whether the worker may register new trigger types. */
+  allow_trigger_type_registration: boolean; /** Whether the worker may register new functions. Defaults to `true` if omitted. */
+  allow_function_registration?: boolean; /** Arbitrary context forwarded to the middleware function on every invocation. */
+  context: Record<string, unknown>;
+};
+/**
+ * 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.
+ */
+type MiddlewareFunctionInput = {
+  /** ID of the function being invoked. */function_id: string; /** Payload sent by the caller. */
+  payload: Record<string, unknown>; /** Routing action, if any. */
+  action?: TriggerAction$1; /** Auth context returned by the auth function for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * 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 `true` to allow the registration.
+ */
+type OnTriggerTypeRegistrationInput = {
+  /** ID of the trigger type being registered. */trigger_type_id: string; /** Human-readable description of the trigger type. */
+  description: string; /** Auth context from `AuthResult.context` for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * Input passed to the `on_trigger_registration_function_id` hook
+ * when a worker attempts to register a trigger through the RBAC port.
+ * Return `true` to allow the registration.
+ */
+type OnTriggerRegistrationInput = {
+  /** ID of the trigger being registered. */trigger_id: string; /** Trigger type identifier. */
+  trigger_type: string; /** ID of the function this trigger is bound to. */
+  function_id: string; /** Trigger-specific configuration. */
+  config: unknown; /** Auth context from `AuthResult.context` for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * Input passed to the `on_function_registration_function_id` hook
+ * when a worker attempts to register a function through the RBAC port.
+ * Return `true` to allow the registration.
+ */
+type OnFunctionRegistrationInput = {
+  /** ID of the function being registered. */function_id: string; /** Human-readable description of the function. */
+  description?: string; /** Arbitrary metadata attached to the function. */
+  metadata?: Record<string, unknown>; /** Auth context from `AuthResult.context` for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * Result returned when a function is invoked with `TriggerAction.Enqueue`.
+ */
+type EnqueueResult = {
+  /** Unique receipt ID for the enqueued message. */messageReceiptId: string;
+};
+/**
+ * Request object passed to {@link ISdk.trigger}.
+ *
+ * @typeParam TInput - Type of the payload.
+ */
+type TriggerRequest<TInput = unknown> = {
+  /** ID of the function to invoke. */function_id: string; /** Payload to pass to the function. */
+  payload: TInput; /** Routing action. Omit for synchronous request/response. */
+  action?: TriggerAction$1; /** Override the default invocation timeout in milliseconds. */
+  timeoutMs?: number;
+};
+/**
+ * Metadata about a registered function, returned by `ISdk.listFunctions`.
+ */
+type FunctionInfo = {
+  /** Unique function identifier. */function_id: string; /** Human-readable description. */
+  description?: string; /** Schema describing expected request format. */
+  request_format?: RegisterFunctionFormat; /** Schema describing expected response format. */
+  response_format?: RegisterFunctionFormat; /** Arbitrary metadata attached to the function. */
+  metadata?: Record<string, unknown>;
+};
+/**
+ * Information about a registered trigger.
+ */
+type TriggerInfo = {
+  /** Unique trigger identifier. */id: string; /** Type of the trigger (e.g. `http`, `cron`, `queue`). */
+  trigger_type: string; /** ID of the function this trigger is bound to. */
+  function_id: string; /** Trigger-specific configuration. */
+  config?: unknown;
+};
+/**
+ * Information about a registered trigger type, returned by `ISdk.listTriggerTypes`.
+ */
+type TriggerTypeInfo = {
+  /** Trigger type identifier (e.g. `http`, `cron`, `queue`). */id: string; /** Human-readable description of the trigger type. */
+  description: string; /** JSON Schema for the trigger configuration. */
+  trigger_request_format?: unknown; /** JSON Schema for the call request payload. */
+  call_request_format?: unknown;
+};
+/** Worker connection status. */
+type WorkerStatus = 'connected' | 'available' | 'busy' | 'disconnected';
+/**
+ * Metadata about a connected worker, returned by `ISdk.listWorkers`.
+ */
+type WorkerInfo = {
+  /** Unique worker identifier assigned by the engine. */id: string; /** Display name of the worker. */
+  name?: string; /** Runtime environment (e.g. `node`, `python`, `rust`). */
+  runtime?: string; /** SDK version. */
+  version?: string; /** Operating system info. */
+  os?: string; /** IP address of the worker. */
+  ip_address?: string; /** Current connection status. */
+  status: WorkerStatus; /** Timestamp (ms since epoch) when the worker connected. */
+  connected_at_ms: number; /** Number of functions registered by this worker. */
+  function_count: number; /** List of function IDs registered by this worker. */
+  functions: string[]; /** Number of currently active invocations. */
+  active_invocations: number;
+};
+/**
+ * Serializable reference to one end of a streaming channel. Can be included
+ * in invocation payloads to pass channel endpoints between workers.
+ */
+type StreamChannelRef = {
+  /** Unique channel identifier. */channel_id: string; /** Access key for authentication. */
+  access_key: string; /** Whether this ref is for reading or writing. */
+  direction: 'read' | 'write';
+};
+//#endregion
+//#region src/channels.d.ts
+/**
+ * Write end of a streaming channel. Uses native browser WebSocket.
+ *
+ * @example
+ * ```typescript
+ * const channel = await iii.createChannel()
+ *
+ * channel.writer.sendMessage(JSON.stringify({ type: 'event', data: 'test' }))
+ * channel.writer.sendBinary(new Uint8Array([1, 2, 3]))
+ * channel.writer.close()
+ * ```
+ */
+declare class ChannelWriter {
+  private static readonly FRAME_SIZE;
+  private ws;
+  private wsReady;
+  private readonly pendingMessages;
+  private readonly url;
+  constructor(engineWsBase: string, ref: StreamChannelRef);
+  private ensureConnected;
+  /** Send a text message through the channel. */
+  sendMessage(msg: string): void;
+  /** Send binary data through the channel. */
+  sendBinary(data: Uint8Array): void;
+  /** Close the channel writer. */
+  close(): void;
+  private sendRaw;
+}
+/**
+ * Read end of a streaming channel. Uses native browser WebSocket.
+ *
+ * @example
+ * ```typescript
+ * const channel = await iii.createChannel()
+ *
+ * channel.reader.onMessage((msg) => console.log('Got:', msg))
+ * channel.reader.onBinary((data) => console.log('Binary:', data.byteLength))
+ * ```
+ */
+declare class ChannelReader {
+  private ws;
+  private connected;
+  private readonly messageCallbacks;
+  private readonly binaryCallbacks;
+  private readonly url;
+  constructor(engineWsBase: string, ref: StreamChannelRef);
+  private ensureConnected;
+  /** Register a callback to receive text messages from the channel. */
+  onMessage(callback: (msg: string) => void): void;
+  /** Register a callback to receive binary data from the channel. */
+  onBinary(callback: (data: Uint8Array) => void): void;
+  /** Read all binary data from the channel until it closes. */
+  readAll(): Promise<Uint8Array>;
+  /** Close the channel reader. */
+  close(): void;
+}
+//#endregion
+//#region src/iii-constants.d.ts
+/** Configuration for WebSocket reconnection behavior */
+interface IIIReconnectionConfig {
+  /** Starting delay in milliseconds (default: 1000ms) */
+  initialDelayMs: number;
+  /** Maximum delay cap in milliseconds (default: 30000ms) */
+  maxDelayMs: number;
+  /** Exponential backoff multiplier (default: 2) */
+  backoffMultiplier: number;
+  /** Random jitter factor 0-1 (default: 0.3) */
+  jitterFactor: number;
+  /** Maximum retry attempts, -1 for infinite (default: -1) */
+  maxRetries: number;
+}
+//#endregion
+//#region src/triggers.d.ts
+/**
+ * Configuration passed to a trigger handler when a trigger instance is
+ * registered or unregistered.
+ *
+ * @typeParam TConfig - Type of the trigger-specific configuration.
+ */
+type TriggerConfig<TConfig> = {
+  /** Trigger instance ID. */id: string; /** Function to invoke when the trigger fires. */
+  function_id: string; /** Trigger-specific configuration. */
+  config: TConfig;
+};
+/**
+ * Handler interface for custom trigger types. Passed to
+ * `ISdk.registerTriggerType`.
+ *
+ * @typeParam TConfig - Type of the trigger-specific configuration.
+ *
+ * @example
+ * ```typescript
+ * const handler: TriggerHandler<{ interval: number }> = {
+ *   async registerTrigger({ id, function_id, config }) {
+ *     // Set up periodic invocation
+ *   },
+ *   async unregisterTrigger({ id, function_id, config }) {
+ *     // Clean up
+ *   },
+ * }
+ * ```
+ */
+type TriggerHandler<TConfig> = {
+  /** Called when a trigger instance is registered. */registerTrigger(config: TriggerConfig<TConfig>): Promise<void>; /** Called when a trigger instance is unregistered. */
+  unregisterTrigger(config: TriggerConfig<TConfig>): Promise<void>;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Async function handler for a registered function. Receives the invocation
+ * payload and returns the result.
+ *
+ * @typeParam TInput - Type of the invocation payload.
+ * @typeParam TOutput - Type of the return value.
+ *
+ * @example
+ * ```typescript
+ * const handler: RemoteFunctionHandler<{ name: string }, { message: string }> =
+ *   async (data) => ({ message: `Hello, ${data.name}!` })
+ * ```
+ */
+type RemoteFunctionHandler<TInput = any, TOutput = any> = (data: TInput) => Promise<TOutput>;
+type RegisterTriggerInput = Omit<RegisterTriggerMessage, 'message_type' | 'id'>;
+type RegisterServiceInput = Omit<RegisterServiceMessage, 'message_type'>;
+type RegisterFunctionInput = Omit<RegisterFunctionMessage, 'message_type'>;
+type RegisterTriggerTypeInput = Omit<RegisterTriggerTypeMessage, 'message_type'>;
+type FunctionsAvailableCallback = (functions: FunctionInfo[]) => void;
+interface ISdk {
+  /**
+   * Registers a new trigger. A trigger is a way to invoke a function when a certain event occurs.
+   * @param trigger - The trigger to register
+   * @returns A trigger object that can be used to unregister the trigger
+   *
+   * @example
+   * ```typescript
+   * const trigger = iii.registerTrigger({
+   *   type: 'cron',
+   *   function_id: 'my-service::process-batch',
+   *   config: { schedule: '*\/5 * * * *' },
+   * })
+   *
+   * // Later, remove the trigger
+   * trigger.unregister()
+   * ```
+   */
+  registerTrigger(trigger: RegisterTriggerInput): Trigger;
+  /**
+   * Registers a new function with a local handler.
+   * @param func - The function to register
+   * @param handler - The handler for local execution
+   * @returns A handle that can be used to unregister the function
+   *
+   * @example
+   * ```typescript
+   * const ref = iii.registerFunction(
+   *   { id: 'greet', description: 'Returns a greeting' },
+   *   async (data: { name: string }) => ({ message: `Hello, ${data.name}!` }),
+   * )
+   *
+   * // Later, remove the function
+   * ref.unregister()
+   * ```
+   */
+  /**
+   * Registers a new service.
+   * @param message - The service to register
+   */
+  registerService(message: RegisterServiceInput): void;
+  registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler): FunctionRef;
+  /**
+   * Registers a new function with an HTTP invocation config (Lambda, Cloudflare
+   * Workers, etc.).
+   * @param func - The function to register
+   * @param invocation - HTTP invocation config
+   * @returns A handle that can be used to unregister the function
+   *
+   * @example
+   * ```typescript
+   * const ref = iii.registerFunction(
+   *   { id: 'external::my-lambda', description: 'Proxied Lambda function' },
+   *   {
+   *     url: 'https://abc123.lambda-url.us-east-1.on.aws',
+   *     method: 'POST',
+   *     timeout_ms: 30_000,
+   *     auth: { type: 'bearer', token_key: 'LAMBDA_AUTH_TOKEN' },
+   *   },
+   * )
+   * ```
+   */
+  registerFunction(func: RegisterFunctionInput, invocation: HttpInvocationConfig): FunctionRef;
+  /**
+   * Invokes a function using a request object.
+   *
+   * @param request - The trigger request containing function_id, payload, and optional action/timeout
+   * @returns The result of the function
+   *
+   * @example
+   * ```typescript
+   * // Synchronous invocation
+   * const result = await iii.trigger<{ name: string }, { message: string }>({
+   *   function_id: 'greet',
+   *   payload: { name: 'World' },
+   *   timeoutMs: 5000,
+   * })
+   * console.log(result.message) // "Hello, World!"
+   *
+   * // Fire-and-forget
+   * await iii.trigger({
+   *   function_id: 'send-email',
+   *   payload: { to: 'user@example.com' },
+   *   action: TriggerAction.Void(),
+   * })
+   *
+   * // Enqueue for async processing
+   * const receipt = await iii.trigger({
+   *   function_id: 'process-order',
+   *   payload: { orderId: '123' },
+   *   action: TriggerAction.Enqueue({ queue: 'orders' }),
+   * })
+   * ```
+   */
+  trigger<TInput, TOutput>(request: TriggerRequest<TInput>): Promise<TOutput>;
+  /**
+   * Lists all registered functions.
+   *
+   * @example
+   * ```typescript
+   * const functions = await iii.listFunctions()
+   * for (const fn of functions) {
+   *   console.log(`${fn.function_id}: ${fn.description}`)
+   * }
+   * ```
+   */
+  listFunctions(): Promise<FunctionInfo[]>;
+  /**
+   * Lists all connected workers.
+   *
+   * @returns An array of {@link WorkerInfo} objects.
+   */
+  listWorkers(): Promise<WorkerInfo[]>;
+  /**
+   * Lists all registered triggers.
+   * @param includeInternal - Whether to include internal triggers (default: false)
+   */
+  listTriggers(includeInternal?: boolean): Promise<TriggerInfo[]>;
+  /**
+   * Lists all trigger types registered with the engine.
+   * @param includeInternal - Whether to include internal trigger types (default: false)
+   *
+   * @example
+   * ```typescript
+   * const triggerTypes = await iii.listTriggerTypes()
+   * for (const tt of triggerTypes) {
+   *   console.log(`${tt.id}: ${tt.description}`)
+   * }
+   * ```
+   */
+  listTriggerTypes(includeInternal?: boolean): Promise<TriggerTypeInfo[]>;
+  /**
+   * Registers a new trigger type. A trigger type is a way to invoke a function when a certain event occurs.
+   * @param triggerType - The trigger type to register
+   * @param handler - The handler for the trigger type
+   * @returns A trigger type object that can be used to unregister the trigger type
+   *
+   * @example
+   * ```typescript
+   * type CronConfig = { schedule: string }
+   *
+   * iii.registerTriggerType<CronConfig>(
+   *   { id: 'cron', description: 'Fires on a cron schedule' },
+   *   {
+   *     async registerTrigger({ id, function_id, config }) {
+   *       startCronJob(id, config.schedule, () =>
+   *         iii.trigger({ function_id, payload: {} }),
+   *       )
+   *     },
+   *     async unregisterTrigger({ id }) {
+   *       stopCronJob(id)
+   *     },
+   *   },
+   * )
+   * ```
+   */
+  registerTriggerType<TConfig>(triggerType: RegisterTriggerTypeInput, handler: TriggerHandler<TConfig>): TriggerTypeRef<TConfig>;
+  /**
+   * Unregisters a trigger type.
+   * @param triggerType - The trigger type to unregister
+   *
+   * @example
+   * ```typescript
+   * iii.unregisterTriggerType({ id: 'cron', description: 'Fires on a cron schedule' })
+   * ```
+   */
+  unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;
+  /**
+   * Creates a streaming channel pair for worker-to-worker data transfer.
+   * Returns a Channel with a local writer/reader and serializable refs that
+   * can be passed as fields in the invocation data to other functions.
+   *
+   * @param bufferSize - Optional buffer size for the channel (default: 64)
+   * @returns A Channel with writer, reader, and their serializable refs
+   *
+   * @example
+   * ```typescript
+   * const channel = await iii.createChannel()
+   *
+   * // Pass the writer ref to another function
+   * await iii.trigger({
+   *   function_id: 'stream-producer',
+   *   payload: { outputChannel: channel.writerRef },
+   * })
+   *
+   * // Read data locally
+   * channel.reader.onMessage((msg) => {
+   *   console.log('Received:', msg)
+   * })
+   * ```
+   */
+  createChannel(bufferSize?: number): Promise<Channel>;
+  /**
+   * Creates a new stream implementation.
+   *
+   * This overrides the default stream implementation.
+   *
+   * @param streamName - The name of the stream
+   * @param stream - The stream implementation
+   *
+   * @example
+   * ```typescript
+   * iii.createStream('sessions', {
+   *   async get({ group_id, item_id }) { return null },
+   *   async set({ group_id, item_id, data }) { return { new_value: data } },
+   *   async delete({ group_id, item_id }) { return {} },
+   *   async list({ group_id }) { return [] },
+   *   async listGroups() { return [] },
+   *   async update() { return null },
+   * })
+   * ```
+   */
+  createStream<TData>(streamName: string, stream: IStream<TData>): void;
+  /**
+   * Registers a callback to receive the current functions list
+   * when the engine announces changes.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = iii.onFunctionsAvailable((functions) => {
+   *   console.log(`${functions.length} functions available:`)
+   *   for (const fn of functions) {
+   *     console.log(`  - ${fn.function_id}`)
+   *   }
+   * })
+   *
+   * // Later, stop listening
+   * unsubscribe()
+   * ```
+   */
+  onFunctionsAvailable(callback: FunctionsAvailableCallback): () => void;
+  /**
+   * Gracefully shutdown the iii, cleaning up all resources.
+   *
+   * @example
+   * ```typescript
+   * await iii.shutdown()
+   * ```
+   */
+  shutdown(): Promise<void>;
+}
+/**
+ * Handle returned by {@link ISdk.registerTrigger}. Use `unregister()` to
+ * remove the trigger from the engine.
+ */
+type Trigger = {
+  /** Removes this trigger from the engine. */unregister(): void;
+};
+/**
+ * Handle returned by {@link ISdk.registerFunction}. Contains the function's
+ * `id` and an `unregister()` method.
+ */
+type FunctionRef = {
+  /** The unique function identifier. */id: string; /** Removes this function from the engine. */
+  unregister: () => void;
+};
+/**
+ * Typed handle returned by {@link 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.
+ *
+ * @typeParam TConfig - Trigger-specific configuration type.
+ *
+ * @example
+ * ```typescript
+ * type CronConfig = { schedule: string }
+ *
+ * const cron = iii.registerTriggerType<CronConfig>(
+ *   { id: 'cron', description: 'Fires on a cron schedule' },
+ *   cronHandler,
+ * )
+ *
+ * // Register a trigger -- type is inferred as CronConfig
+ * cron.registerTrigger('my-fn', { schedule: '* * * * *' })
+ *
+ * // Register a function and bind a trigger in one call
+ * cron.registerFunction(
+ *   { id: 'my-fn', description: 'Cron-triggered function' },
+ *   async (data) => { return { ok: true } },
+ *   { schedule: '* * * * *' },
+ * )
+ * ```
+ */
+type TriggerTypeRef<TConfig = unknown> = {
+  /** The trigger type identifier. */id: string;
+  /**
+   * Register a trigger bound to this trigger type.
+   *
+   * @param functionId - The function to invoke when the trigger fires.
+   * @param config - Trigger-specific configuration.
+   * @returns A {@link Trigger} handle with an `unregister()` method.
+   */
+  registerTrigger(functionId: string, config: TConfig): Trigger;
+  /**
+   * Register a function and immediately bind it to this trigger type.
+   *
+   * @param func - Function registration input.
+   * @param handler - Local function handler.
+   * @param config - Trigger-specific configuration.
+   * @returns A {@link FunctionRef} handle.
+   */
+  registerFunction(func: RegisterFunctionInput, handler: RemoteFunctionHandler, config: TConfig): FunctionRef;
+  /**
+   * Unregister this trigger type from the engine.
+   */
+  unregister(): void;
+};
+/**
+ * A streaming channel pair for worker-to-worker data transfer. Created via
+ * {@link ISdk.createChannel}.
+ */
+type Channel = {
+  /** Writer end of the channel. */writer: ChannelWriter; /** Reader end of the channel. */
+  reader: ChannelReader; /** Serializable reference to the writer (can be sent to other workers). */
+  writerRef: StreamChannelRef; /** Serializable reference to the reader (can be sent to other workers). */
+  readerRef: StreamChannelRef;
+};
+/**
+ * Incoming HTTP request received by a function registered with an HTTP trigger.
+ *
+ * @typeParam TBody - Type of the parsed request body.
+ */
+type ApiRequest<TBody = unknown> = {
+  path_params: Record<string, string>;
+  query_params: Record<string, string | string[]>;
+  body: TBody;
+  headers: Record<string, string | string[]>;
+  method: string;
+};
+/**
+ * Structured API response returned from HTTP function handlers.
+ *
+ * @typeParam TStatus - HTTP status code literal type.
+ * @typeParam TBody - Type of the response body.
+ *
+ * @example
+ * ```typescript
+ * const response: ApiResponse = {
+ *   status_code: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: { message: 'ok' },
+ * }
+ * ```
+ */
+type ApiResponse<TStatus extends number = number, TBody = string | Record<string, unknown>> = {
+  /** HTTP status code. */status_code: TStatus; /** Response headers. */
+  headers?: Record<string, string>; /** Response body. */
+  body?: TBody;
+};
+//#endregion
+//#region src/iii.d.ts
+/** @internal */
+type TelemetryOptions = {
+  language?: string;
+  project_name?: string;
+  framework?: string;
+  amplitude_api_key?: string;
+};
+/**
+ * Configuration options passed to {@link registerWorker}.
+ *
+ * @example
+ * ```typescript
+ * const iii = registerWorker('ws://localhost:49135', {
+ *   workerName: 'my-browser-worker',
+ *   invocationTimeoutMs: 10000,
+ *   reconnectionConfig: { maxRetries: 5 },
+ * })
+ * ```
+ */
+type InitOptions = {
+  /** Display name for this worker. Defaults to `browser:<random-id>`. */workerName?: string; /** Default timeout for `trigger()` in milliseconds. Defaults to `30000`. */
+  invocationTimeoutMs?: number;
+  /**
+   * WebSocket reconnection behavior.
+   *
+   * @see {@link IIIReconnectionConfig} for available fields and defaults.
+   */
+  reconnectionConfig?: Partial<IIIReconnectionConfig>; /** Custom headers are not supported by browser WebSocket. Use query parameters or cookies for auth. */
+  headers?: Record<string, string>; /** @internal */
+  telemetry?: TelemetryOptions;
+};
+/**
+ * Factory object that constructs routing actions for {@link ISdk.trigger}.
+ *
+ * @example
+ * ```typescript
+ * import { TriggerAction } from 'iii-browser-sdk'
+ *
+ * // Enqueue to a named queue
+ * iii.trigger({
+ *   function_id: 'process',
+ *   payload: { data: 'hello' },
+ *   action: TriggerAction.Enqueue({ queue: 'jobs' }),
+ * })
+ *
+ * // Fire-and-forget
+ * iii.trigger({
+ *   function_id: 'notify',
+ *   payload: {},
+ *   action: TriggerAction.Void(),
+ * })
+ * ```
+ */
+declare const TriggerAction: {
+  /**
+   * Routes the invocation through a named queue. The engine enqueues the job,
+   * acknowledges the caller with `{ messageReceiptId }`, and processes it
+   * asynchronously.
+   *
+   * @param opts - Queue routing options.
+   * @param opts.queue - Name of the target queue.
+   */
+  readonly Enqueue: (opts: {
+    queue: string;
+  }) => TriggerAction$1;
+  /**
+   * Fire-and-forget routing. The engine forwards the invocation without
+   * waiting for a response or queuing the job.
+   */
+  readonly Void: () => TriggerAction$1;
+};
+/**
+ * Creates and returns a connected SDK instance. The WebSocket connection is
+ * established automatically -- there is no separate `connect()` call.
+ *
+ * @param address - WebSocket URL of the III engine (e.g. `ws://localhost:49135`).
+ * @param options - Optional {@link InitOptions} for worker name, timeouts, and reconnection.
+ * @returns A connected {@link ISdk} instance.
+ *
+ * @example
+ * ```typescript
+ * import { registerWorker } from 'iii-browser-sdk'
+ *
+ * const iii = registerWorker('ws://localhost:49135', {
+ *   workerName: 'my-browser-worker',
+ * })
+ * ```
+ */
+declare const registerWorker: (address: string, options?: InitOptions) => ISdk;
+//#endregion
+export { type ApiRequest, type ApiResponse, type AuthInput, type AuthResult, type Channel, ChannelReader, ChannelWriter, type EnqueueResult, type FunctionRef, type HttpAuthConfig, type HttpInvocationConfig, type ISdk, type InitOptions, type MessageType, type MiddlewareFunctionInput, type OnFunctionRegistrationInput, type OnTriggerRegistrationInput, type OnTriggerTypeRegistrationInput, type RegisterFunctionInput, type RegisterFunctionMessage, type RegisterServiceInput, type RegisterTriggerInput, type RegisterTriggerMessage, type RegisterTriggerTypeInput, type RegisterTriggerTypeMessage, type RemoteFunctionHandler, type StreamChannelRef, type Trigger, TriggerAction, type TriggerAction$1 as TriggerActionType, type TriggerConfig, type TriggerHandler, type TriggerInfo, type TriggerRequest, type TriggerTypeInfo, type TriggerTypeRef, registerWorker };
+//# sourceMappingURL=index.d.cts.map