@iii-dev/helpers 0.19.4-alpha.2

package/LICENSE.spdx

@@ -0,0 +1,25 @@
+SPDXVersion: SPDX-2.3
+DataLicense: CC0-1.0
+SPDXID: SPDXRef-DOCUMENT
+DocumentName: iii
+DocumentNamespace: https://iii.dev/spdx/iii
+PackageName: iii
+SPDXID: SPDXRef-Package
+PackageSupplier: Organization: Motia LLC
+PackageHomePage: https://iii.dev
+PackageLicenseDeclared: Apache-2.0 AND Elastic-2.0
+PackageLicenseConcluded: Apache-2.0 AND Elastic-2.0
+PackageCopyrightText: 2024-present, Motia LLC
+PackageSummary: <text>iii turns distributed backend complexity into a
+simple set of real-time, interoperable primitives called Workers,
+Triggers, and Functions. The result is coordinated execution
+that behaves as if it were a single runtime.
+                </text>
+PackageComment: <text>Inbound contributions from external
+contributors are accepted under Apache-2.0 only; see CONTRIBUTING.md.
+                </text>
+Created: 2024-01-01T00:00:00Z
+PackageDownloadLocation: git://github.com/iii-hq/iii
+PackageDownloadLocation: git+https://github.com/iii-hq/iii.git
+PackageDownloadLocation: git+ssh://github.com/iii-hq/iii.git
+Creator: Organization: Motia LLC

package/README.md

@@ -0,0 +1,5 @@
+# @iii-dev/helpers
+
+Shared helper primitives across the iii SDKs.
+
+See https://github.com/iii-hq/iii for the full project.

package/dist/http/index.cjs

@@ -0,0 +1,46 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/http/index.ts
+/**
+* Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)
+* into the function handler format expected by the SDK.
+*
+* @param callback - Async handler receiving a streaming request and response.
+* @returns A function handler compatible with `IIIClient.registerFunction`.
+*
+* @example
+* ```typescript
+* import { http } from '@iii-dev/helpers/http'
+*
+* iii.registerFunction(
+*   'my-api',
+*   http(async (req, res) => {
+*     res.status(200)
+*     res.headers({ 'content-type': 'application/json' })
+*     res.stream.end(JSON.stringify({ hello: 'world' }))
+*     res.close()
+*   }),
+* )
+* ```
+*/
+const http = (callback) => {
+	return async (req) => {
+		const { response, ...request } = req;
+		return callback(request, {
+			status: (status_code) => response.sendMessage(JSON.stringify({
+				type: "set_status",
+				status_code
+			})),
+			headers: (headers) => response.sendMessage(JSON.stringify({
+				type: "set_headers",
+				headers
+			})),
+			stream: response.stream,
+			close: () => response.close()
+		});
+	};
+};
+
+//#endregion
+exports.http = http;
+//# sourceMappingURL=index.cjs.map

package/dist/http/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/http/index.ts"],"sourcesContent":["/**\n * HTTP method accepted by {@link HttpInvocationConfig}. Distinct from the core\n * `builtin_triggers` HTTP method enum, which also covers HEAD/OPTIONS.\n */\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n\n/**\n * Authentication configuration for HTTP-invoked functions.\n *\n * - `hmac` -- HMAC signature verification using a shared secret.\n * - `bearer` -- Bearer token authentication.\n * - `api_key` -- API key sent via a custom header.\n */\nexport type HttpAuthConfig =\n  | { type: 'hmac'; secret_key: string }\n  | { type: 'bearer'; token_key: string }\n  | { type: 'api_key'; header: string; value_key: string }\n\n/**\n * Configuration for registering an HTTP-invoked function (Lambda, Cloudflare\n * Workers, etc.) instead of a local handler.\n */\nexport type HttpInvocationConfig = {\n  /** URL to invoke. */\n  url: string\n  /** HTTP method. Defaults to `POST`. */\n  method?: HttpMethod\n  /** Timeout in milliseconds. */\n  timeout_ms?: number\n  /** Custom headers to send with the request. */\n  headers?: Record<string, string>\n  /** Authentication configuration. */\n  auth?: HttpAuthConfig\n}\n\n/**\n * Incoming buffered HTTP request received by a function handler.\n *\n * @typeParam TBody - Type of the parsed request body.\n */\nexport type HttpRequest<TBody = unknown> = {\n  path_params: Record<string, string>\n  query_params: Record<string, string | string[]>\n  body: TBody\n  headers: Record<string, string | string[]>\n  method: string\n  request_body: HttpStreamReader\n}\n\n/**\n * Structured buffered HTTP response returned from function handlers.\n *\n * @typeParam TStatus - HTTP status code literal type.\n * @typeParam TBody - Type of the response body.\n *\n * @example\n * ```typescript\n * const response: HttpResponse = {\n *   status_code: 200,\n *   headers: { 'content-type': 'application/json' },\n *   body: { message: 'ok' },\n * }\n * ```\n */\nexport type HttpResponse<\n  TStatus extends number = number,\n  TBody = string | Buffer | Record<string, unknown>,\n> = {\n  /** HTTP status code. */\n  status_code: TStatus\n  /** Response headers. */\n  headers?: Record<string, string>\n  /** Response body. */\n  body?: TBody\n}\n\n/**\n * Structural shape of the reader end of a stream channel. Declared locally so\n * the helpers package does not runtime-depend on the core SDK.\n */\ntype HttpStreamReader = {\n  stream: NodeJS.ReadableStream\n  readAll: () => Promise<Buffer>\n  onMessage: (callback: (msg: string) => void) => void\n  close: () => void\n}\n\n/** Structural shape of the writer end of a stream channel. */\ntype HttpStreamWriter = {\n  sendMessage: (message: string) => unknown\n  stream: NodeJS.WritableStream\n  close: () => unknown\n}\n\n/** Structural shape of a streaming request passed to the {@link http} handler. */\ntype HttpStreamingRequest = {\n  path_params: Record<string, string>\n  query_params: Record<string, string | string[]>\n  body: unknown\n  headers: Record<string, string | string[]>\n  method: string\n  request_body: HttpStreamReader\n}\n\n/** Structural shape of the streaming response passed to the {@link http} handler. */\ntype HttpStreamingResponse = {\n  status: (statusCode: number) => void\n  headers: (headers: Record<string, string>) => void\n  stream: NodeJS.WritableStream\n  close: () => void\n}\n\n/** Structural shape of the internal request delivered by the runtime. */\ntype HttpInternalRequest = HttpStreamingRequest & { response: HttpStreamWriter }\n\n/**\n * Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)\n * into the function handler format expected by the SDK.\n *\n * @param callback - Async handler receiving a streaming request and response.\n * @returns A function handler compatible with `IIIClient.registerFunction`.\n *\n * @example\n * ```typescript\n * import { http } from '@iii-dev/helpers/http'\n *\n * iii.registerFunction(\n *   'my-api',\n *   http(async (req, res) => {\n *     res.status(200)\n *     res.headers({ 'content-type': 'application/json' })\n *     res.stream.end(JSON.stringify({ hello: 'world' }))\n *     res.close()\n *   }),\n * )\n * ```\n */\nexport const http = (\n  // biome-ignore lint/suspicious/noConfusingVoidType: void is necessary here\n  callback: (req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse>,\n) => {\n  return async (req: HttpInternalRequest) => {\n    const { response, ...request } = req\n\n    const httpResponse: HttpStreamingResponse = {\n      status: (status_code: number) =>\n        response.sendMessage(JSON.stringify({ type: 'set_status', status_code })),\n      headers: (headers: Record<string, string>) =>\n        response.sendMessage(JSON.stringify({ type: 'set_headers', headers })),\n      stream: response.stream,\n      close: () => response.close(),\n    }\n\n    return callback(request, httpResponse)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyIA,MAAa,QAEX,aACG;AACH,QAAO,OAAO,QAA6B;EACzC,MAAM,EAAE,UAAU,GAAG,YAAY;AAWjC,SAAO,SAAS,SAT4B;GAC1C,SAAS,gBACP,SAAS,YAAY,KAAK,UAAU;IAAE,MAAM;IAAc;IAAa,CAAC,CAAC;GAC3E,UAAU,YACR,SAAS,YAAY,KAAK,UAAU;IAAE,MAAM;IAAe;IAAS,CAAC,CAAC;GACxE,QAAQ,SAAS;GACjB,aAAa,SAAS,OAAO;GAC9B,CAEqC"}

package/dist/http/index.d.cts

@@ -0,0 +1,130 @@
+//#region src/http/index.d.ts
+/**
+ * HTTP method accepted by {@link HttpInvocationConfig}. Distinct from the core
+ * `builtin_triggers` HTTP method enum, which also covers HEAD/OPTIONS.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * 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?: HttpMethod; /** Timeout in milliseconds. */
+  timeout_ms?: number; /** Custom headers to send with the request. */
+  headers?: Record<string, string>; /** Authentication configuration. */
+  auth?: HttpAuthConfig;
+};
+/**
+ * Incoming buffered HTTP request received by a function handler.
+ *
+ * @typeParam TBody - Type of the parsed request body.
+ */
+type HttpRequest<TBody = unknown> = {
+  path_params: Record<string, string>;
+  query_params: Record<string, string | string[]>;
+  body: TBody;
+  headers: Record<string, string | string[]>;
+  method: string;
+  request_body: HttpStreamReader;
+};
+/**
+ * Structured buffered HTTP response returned from function handlers.
+ *
+ * @typeParam TStatus - HTTP status code literal type.
+ * @typeParam TBody - Type of the response body.
+ *
+ * @example
+ * ```typescript
+ * const response: HttpResponse = {
+ *   status_code: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: { message: 'ok' },
+ * }
+ * ```
+ */
+type HttpResponse<TStatus extends number = number, TBody = string | Buffer | Record<string, unknown>> = {
+  /** HTTP status code. */status_code: TStatus; /** Response headers. */
+  headers?: Record<string, string>; /** Response body. */
+  body?: TBody;
+};
+/**
+ * Structural shape of the reader end of a stream channel. Declared locally so
+ * the helpers package does not runtime-depend on the core SDK.
+ */
+type HttpStreamReader = {
+  stream: NodeJS.ReadableStream;
+  readAll: () => Promise<Buffer>;
+  onMessage: (callback: (msg: string) => void) => void;
+  close: () => void;
+};
+/** Structural shape of the writer end of a stream channel. */
+type HttpStreamWriter = {
+  sendMessage: (message: string) => unknown;
+  stream: NodeJS.WritableStream;
+  close: () => unknown;
+};
+/** Structural shape of a streaming request passed to the {@link http} handler. */
+type HttpStreamingRequest = {
+  path_params: Record<string, string>;
+  query_params: Record<string, string | string[]>;
+  body: unknown;
+  headers: Record<string, string | string[]>;
+  method: string;
+  request_body: HttpStreamReader;
+};
+/** Structural shape of the streaming response passed to the {@link http} handler. */
+type HttpStreamingResponse = {
+  status: (statusCode: number) => void;
+  headers: (headers: Record<string, string>) => void;
+  stream: NodeJS.WritableStream;
+  close: () => void;
+};
+/** Structural shape of the internal request delivered by the runtime. */
+type HttpInternalRequest = HttpStreamingRequest & {
+  response: HttpStreamWriter;
+};
+/**
+ * Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)
+ * into the function handler format expected by the SDK.
+ *
+ * @param callback - Async handler receiving a streaming request and response.
+ * @returns A function handler compatible with `IIIClient.registerFunction`.
+ *
+ * @example
+ * ```typescript
+ * import { http } from '@iii-dev/helpers/http'
+ *
+ * iii.registerFunction(
+ *   'my-api',
+ *   http(async (req, res) => {
+ *     res.status(200)
+ *     res.headers({ 'content-type': 'application/json' })
+ *     res.stream.end(JSON.stringify({ hello: 'world' }))
+ *     res.close()
+ *   }),
+ * )
+ * ```
+ */
+declare const http: (callback: (req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse>) => (req: HttpInternalRequest) => Promise<void | HttpResponse<number, string | Buffer<ArrayBufferLike> | Record<string, unknown>>>;
+//#endregion
+export { HttpAuthConfig, HttpInvocationConfig, HttpMethod, HttpRequest, HttpResponse, http };
+//# sourceMappingURL=index.d.cts.map

package/dist/http/index.d.mts

@@ -0,0 +1,130 @@
+//#region src/http/index.d.ts
+/**
+ * HTTP method accepted by {@link HttpInvocationConfig}. Distinct from the core
+ * `builtin_triggers` HTTP method enum, which also covers HEAD/OPTIONS.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * 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?: HttpMethod; /** Timeout in milliseconds. */
+  timeout_ms?: number; /** Custom headers to send with the request. */
+  headers?: Record<string, string>; /** Authentication configuration. */
+  auth?: HttpAuthConfig;
+};
+/**
+ * Incoming buffered HTTP request received by a function handler.
+ *
+ * @typeParam TBody - Type of the parsed request body.
+ */
+type HttpRequest<TBody = unknown> = {
+  path_params: Record<string, string>;
+  query_params: Record<string, string | string[]>;
+  body: TBody;
+  headers: Record<string, string | string[]>;
+  method: string;
+  request_body: HttpStreamReader;
+};
+/**
+ * Structured buffered HTTP response returned from function handlers.
+ *
+ * @typeParam TStatus - HTTP status code literal type.
+ * @typeParam TBody - Type of the response body.
+ *
+ * @example
+ * ```typescript
+ * const response: HttpResponse = {
+ *   status_code: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: { message: 'ok' },
+ * }
+ * ```
+ */
+type HttpResponse<TStatus extends number = number, TBody = string | Buffer | Record<string, unknown>> = {
+  /** HTTP status code. */status_code: TStatus; /** Response headers. */
+  headers?: Record<string, string>; /** Response body. */
+  body?: TBody;
+};
+/**
+ * Structural shape of the reader end of a stream channel. Declared locally so
+ * the helpers package does not runtime-depend on the core SDK.
+ */
+type HttpStreamReader = {
+  stream: NodeJS.ReadableStream;
+  readAll: () => Promise<Buffer>;
+  onMessage: (callback: (msg: string) => void) => void;
+  close: () => void;
+};
+/** Structural shape of the writer end of a stream channel. */
+type HttpStreamWriter = {
+  sendMessage: (message: string) => unknown;
+  stream: NodeJS.WritableStream;
+  close: () => unknown;
+};
+/** Structural shape of a streaming request passed to the {@link http} handler. */
+type HttpStreamingRequest = {
+  path_params: Record<string, string>;
+  query_params: Record<string, string | string[]>;
+  body: unknown;
+  headers: Record<string, string | string[]>;
+  method: string;
+  request_body: HttpStreamReader;
+};
+/** Structural shape of the streaming response passed to the {@link http} handler. */
+type HttpStreamingResponse = {
+  status: (statusCode: number) => void;
+  headers: (headers: Record<string, string>) => void;
+  stream: NodeJS.WritableStream;
+  close: () => void;
+};
+/** Structural shape of the internal request delivered by the runtime. */
+type HttpInternalRequest = HttpStreamingRequest & {
+  response: HttpStreamWriter;
+};
+/**
+ * Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)
+ * into the function handler format expected by the SDK.
+ *
+ * @param callback - Async handler receiving a streaming request and response.
+ * @returns A function handler compatible with `IIIClient.registerFunction`.
+ *
+ * @example
+ * ```typescript
+ * import { http } from '@iii-dev/helpers/http'
+ *
+ * iii.registerFunction(
+ *   'my-api',
+ *   http(async (req, res) => {
+ *     res.status(200)
+ *     res.headers({ 'content-type': 'application/json' })
+ *     res.stream.end(JSON.stringify({ hello: 'world' }))
+ *     res.close()
+ *   }),
+ * )
+ * ```
+ */
+declare const http: (callback: (req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse>) => (req: HttpInternalRequest) => Promise<void | HttpResponse<number, string | Buffer<ArrayBufferLike> | Record<string, unknown>>>;
+//#endregion
+export { HttpAuthConfig, HttpInvocationConfig, HttpMethod, HttpRequest, HttpResponse, http };
+//# sourceMappingURL=index.d.mts.map

package/dist/http/index.mjs

@@ -0,0 +1,44 @@
+//#region src/http/index.ts
+/**
+* Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)
+* into the function handler format expected by the SDK.
+*
+* @param callback - Async handler receiving a streaming request and response.
+* @returns A function handler compatible with `IIIClient.registerFunction`.
+*
+* @example
+* ```typescript
+* import { http } from '@iii-dev/helpers/http'
+*
+* iii.registerFunction(
+*   'my-api',
+*   http(async (req, res) => {
+*     res.status(200)
+*     res.headers({ 'content-type': 'application/json' })
+*     res.stream.end(JSON.stringify({ hello: 'world' }))
+*     res.close()
+*   }),
+* )
+* ```
+*/
+const http = (callback) => {
+	return async (req) => {
+		const { response, ...request } = req;
+		return callback(request, {
+			status: (status_code) => response.sendMessage(JSON.stringify({
+				type: "set_status",
+				status_code
+			})),
+			headers: (headers) => response.sendMessage(JSON.stringify({
+				type: "set_headers",
+				headers
+			})),
+			stream: response.stream,
+			close: () => response.close()
+		});
+	};
+};
+
+//#endregion
+export { http };
+//# sourceMappingURL=index.mjs.map

package/dist/http/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/http/index.ts"],"sourcesContent":["/**\n * HTTP method accepted by {@link HttpInvocationConfig}. Distinct from the core\n * `builtin_triggers` HTTP method enum, which also covers HEAD/OPTIONS.\n */\nexport type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'\n\n/**\n * Authentication configuration for HTTP-invoked functions.\n *\n * - `hmac` -- HMAC signature verification using a shared secret.\n * - `bearer` -- Bearer token authentication.\n * - `api_key` -- API key sent via a custom header.\n */\nexport type HttpAuthConfig =\n  | { type: 'hmac'; secret_key: string }\n  | { type: 'bearer'; token_key: string }\n  | { type: 'api_key'; header: string; value_key: string }\n\n/**\n * Configuration for registering an HTTP-invoked function (Lambda, Cloudflare\n * Workers, etc.) instead of a local handler.\n */\nexport type HttpInvocationConfig = {\n  /** URL to invoke. */\n  url: string\n  /** HTTP method. Defaults to `POST`. */\n  method?: HttpMethod\n  /** Timeout in milliseconds. */\n  timeout_ms?: number\n  /** Custom headers to send with the request. */\n  headers?: Record<string, string>\n  /** Authentication configuration. */\n  auth?: HttpAuthConfig\n}\n\n/**\n * Incoming buffered HTTP request received by a function handler.\n *\n * @typeParam TBody - Type of the parsed request body.\n */\nexport type HttpRequest<TBody = unknown> = {\n  path_params: Record<string, string>\n  query_params: Record<string, string | string[]>\n  body: TBody\n  headers: Record<string, string | string[]>\n  method: string\n  request_body: HttpStreamReader\n}\n\n/**\n * Structured buffered HTTP response returned from function handlers.\n *\n * @typeParam TStatus - HTTP status code literal type.\n * @typeParam TBody - Type of the response body.\n *\n * @example\n * ```typescript\n * const response: HttpResponse = {\n *   status_code: 200,\n *   headers: { 'content-type': 'application/json' },\n *   body: { message: 'ok' },\n * }\n * ```\n */\nexport type HttpResponse<\n  TStatus extends number = number,\n  TBody = string | Buffer | Record<string, unknown>,\n> = {\n  /** HTTP status code. */\n  status_code: TStatus\n  /** Response headers. */\n  headers?: Record<string, string>\n  /** Response body. */\n  body?: TBody\n}\n\n/**\n * Structural shape of the reader end of a stream channel. Declared locally so\n * the helpers package does not runtime-depend on the core SDK.\n */\ntype HttpStreamReader = {\n  stream: NodeJS.ReadableStream\n  readAll: () => Promise<Buffer>\n  onMessage: (callback: (msg: string) => void) => void\n  close: () => void\n}\n\n/** Structural shape of the writer end of a stream channel. */\ntype HttpStreamWriter = {\n  sendMessage: (message: string) => unknown\n  stream: NodeJS.WritableStream\n  close: () => unknown\n}\n\n/** Structural shape of a streaming request passed to the {@link http} handler. */\ntype HttpStreamingRequest = {\n  path_params: Record<string, string>\n  query_params: Record<string, string | string[]>\n  body: unknown\n  headers: Record<string, string | string[]>\n  method: string\n  request_body: HttpStreamReader\n}\n\n/** Structural shape of the streaming response passed to the {@link http} handler. */\ntype HttpStreamingResponse = {\n  status: (statusCode: number) => void\n  headers: (headers: Record<string, string>) => void\n  stream: NodeJS.WritableStream\n  close: () => void\n}\n\n/** Structural shape of the internal request delivered by the runtime. */\ntype HttpInternalRequest = HttpStreamingRequest & { response: HttpStreamWriter }\n\n/**\n * Helper that wraps an HTTP-style handler (with separate `req`/`res` arguments)\n * into the function handler format expected by the SDK.\n *\n * @param callback - Async handler receiving a streaming request and response.\n * @returns A function handler compatible with `IIIClient.registerFunction`.\n *\n * @example\n * ```typescript\n * import { http } from '@iii-dev/helpers/http'\n *\n * iii.registerFunction(\n *   'my-api',\n *   http(async (req, res) => {\n *     res.status(200)\n *     res.headers({ 'content-type': 'application/json' })\n *     res.stream.end(JSON.stringify({ hello: 'world' }))\n *     res.close()\n *   }),\n * )\n * ```\n */\nexport const http = (\n  // biome-ignore lint/suspicious/noConfusingVoidType: void is necessary here\n  callback: (req: HttpStreamingRequest, res: HttpStreamingResponse) => Promise<void | HttpResponse>,\n) => {\n  return async (req: HttpInternalRequest) => {\n    const { response, ...request } = req\n\n    const httpResponse: HttpStreamingResponse = {\n      status: (status_code: number) =>\n        response.sendMessage(JSON.stringify({ type: 'set_status', status_code })),\n      headers: (headers: Record<string, string>) =>\n        response.sendMessage(JSON.stringify({ type: 'set_headers', headers })),\n      stream: response.stream,\n      close: () => response.close(),\n    }\n\n    return callback(request, httpResponse)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyIA,MAAa,QAEX,aACG;AACH,QAAO,OAAO,QAA6B;EACzC,MAAM,EAAE,UAAU,GAAG,YAAY;AAWjC,SAAO,SAAS,SAT4B;GAC1C,SAAS,gBACP,SAAS,YAAY,KAAK,UAAU;IAAE,MAAM;IAAc;IAAa,CAAC,CAAC;GAC3E,UAAU,YACR,SAAS,YAAY,KAAK,UAAU;IAAE,MAAM;IAAe;IAAS,CAAC,CAAC;GACxE,QAAQ,SAAS;GACjB,aAAa,SAAS,OAAO;GAC9B,CAEqC"}

package/dist/queue/index.d.cts

@@ -0,0 +1,10 @@
+//#region src/queue/index.d.ts
+/**
+ * Result returned when a function is invoked with `TriggerAction.Enqueue`.
+ */
+type EnqueueResult = {
+  /** Unique receipt ID for the enqueued message. */messageReceiptId: string;
+};
+//#endregion
+export { EnqueueResult };
+//# sourceMappingURL=index.d.cts.map

package/dist/queue/index.d.mts

@@ -0,0 +1,10 @@
+//#region src/queue/index.d.ts
+/**
+ * Result returned when a function is invoked with `TriggerAction.Enqueue`.
+ */
+type EnqueueResult = {
+  /** Unique receipt ID for the enqueued message. */messageReceiptId: string;
+};
+//#endregion
+export { EnqueueResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/queue/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/stream/index.d.cts

@@ -0,0 +1,249 @@
+//#region src/stream/index.d.ts
+/** Input for stream authentication. */
+interface StreamAuthInput {
+  /** Request headers. */
+  headers: Record<string, string>;
+  /** Request path. */
+  path: string;
+  /** Query parameters. */
+  query_params: Record<string, string[]>;
+  /** Client address. */
+  addr: string;
+}
+/** Result of stream authentication. */
+interface StreamAuthResult {
+  /** Arbitrary context passed to stream handlers after authentication. */
+  context?: any;
+}
+/** Context type extracted from {@link StreamAuthResult}. */
+type StreamContext = StreamAuthResult['context'];
+/** Event payload for stream join/leave events. */
+interface StreamJoinLeaveEvent {
+  /** Unique subscription identifier. */
+  subscription_id: string;
+  /** Name of the stream. */
+  stream_name: string;
+  /** Group identifier. */
+  group_id: string;
+  /** Item identifier (if applicable). */
+  id?: string;
+  /** Auth context from {@link StreamAuthResult}. */
+  context?: StreamContext;
+}
+/** Result of a stream join request. */
+interface StreamJoinResult {
+  /** Whether the join was unauthorized. */
+  unauthorized: boolean;
+}
+/** Input for retrieving a single stream item. */
+type StreamGetInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string;
+};
+/** Input for setting a stream item. */
+type StreamSetInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string; /** Data to store. */
+  data: any;
+};
+/** Input for deleting a stream item. */
+type StreamDeleteInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string;
+};
+/** Input for listing all items in a stream group. */
+type StreamListInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string;
+};
+/** Input for listing all groups in a stream. */
+type StreamListGroupsInput = {
+  /** Name of the stream. */stream_name: string;
+};
+/** Result of a stream set operation. */
+type StreamSetResult<TData> = {
+  /** Previous value (if it existed). */old_value?: TData; /** New value that was stored. */
+  new_value: TData;
+};
+/** Result of a stream update operation. */
+type StreamUpdateResult<TData> = {
+  /** Previous value (if it existed). */old_value?: TData; /** New value after the update. */
+  new_value: TData;
+  /**
+   * Per-op errors. Emitted by `merge` and `append` for validation
+   * rejections (path depth/size, value depth, or a
+   * `__proto__`/`constructor`/`prototype` segment or top-level key)
+   * and by `append` for the case-2 `append.type_mismatch` and
+   * `append.target_not_object` surfaces. Successfully applied ops are
+   * still reflected in `new_value`. The field is omitted from the
+   * JSON wire when empty.
+   */
+  errors?: UpdateOpError[];
+};
+/** Set a field at the given path to a value. */
+type UpdateSet = {
+  type: 'set'; /** First-level field path. Use an empty string to target the root value. */
+  path: string; /** Value to set. */
+  value: any;
+};
+/** Increment a numeric field by a given amount. */
+type UpdateIncrement = {
+  type: 'increment'; /** First-level field path. */
+  path: string; /** Amount to increment by. */
+  by: number;
+};
+/** Decrement a numeric field by a given amount. */
+type UpdateDecrement = {
+  type: 'decrement'; /** First-level field path. */
+  path: string; /** Amount to decrement by. */
+  by: number;
+};
+/**
+ * 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).
+ *
+ * Engine semantics:
+ *   - Missing or non-object intermediates along a nested path are
+ *     auto-replaced with `{}` so a stray `null` or scalar never blocks
+ *     future appends.
+ *   - At the leaf:
+ *       - missing/null + nested path → `[value]` (always an array)
+ *       - missing/null + single-string path → string-as-string for the
+ *         string-concat tier, otherwise `[value]`
+ *       - existing array → push
+ *       - existing string + string value → concatenate
+ *       - existing object/scalar at the leaf → `append.type_mismatch`
+ *   - Each path segment is a literal key. `["a.b"]` targets a single
+ *     key named `"a.b"`, not `a → b`.
+ *
+ * Validation: invalid paths (depth > 32 segments, segment > 256
+ * bytes, or any `__proto__`/`constructor`/`prototype` segment) are
+ * rejected with a structured error in the `errors` field of the
+ * `state::update` / `stream::update` response. The append does not
+ * apply when an error is returned for that op.
+ */
+type UpdateAppend = {
+  type: 'append';
+  /**
+   * Optional path to the append target. Accepts a single first-level
+   * key (legacy `string`) or an array of literal segments for nested
+   * append. See {@link MergePath} (the same shape is reused).
+   */
+  path?: MergePath; /** Value to append. String targets only accept string values. */
+  value: any;
+};
+/** Remove a field at the given path. */
+type UpdateRemove = {
+  type: 'remove'; /** First-level field path. */
+  path: string;
+};
+/**
+ * Path target for a {@link 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.
+ *
+ * @example single first-level field
+ *   { type: 'merge', path: 'session-abc', value: { author: 'alice' } }
+ * @example nested path (closes issue #1546's structured-state use case)
+ *   { type: 'merge', path: ['sessions', 'abc'], value: { ts: chunk } }
+ */
+type MergePath = string | string[];
+/**
+ * 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.
+ *
+ * Engine semantics:
+ *   - Missing or non-object intermediates along the path are
+ *     auto-replaced with `{}` so a stray `null` or scalar never
+ *     blocks future merges.
+ *   - The merge is shallow at the target — top-level keys of `value`
+ *     replace same-named keys; siblings are preserved.
+ *   - Each path segment is a literal key. `["a.b"]` writes a single
+ *     key named `"a.b"`, not `a → b`.
+ *
+ * Validation: invalid paths/values (depth > 32 segments, 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 `errors` field of the
+ * `state::update` / `stream::update` response. The merge does not
+ * apply when an error is returned for that op.
+ */
+type UpdateMerge = {
+  type: 'merge'; /** Optional path to the merge target. See {@link MergePath}. */
+  path?: MergePath; /** Object to merge. Must be a JSON object. */
+  value: any;
+};
+/** Per-op error returned by `state::update` / `stream::update`. */
+type UpdateOpError = {
+  /** Index of the offending op within the original `ops` array. */op_index: number; /** Stable error code, e.g. `"merge.path.too_deep"`. */
+  code: string; /** Human-readable description with concrete numbers when applicable. */
+  message: string; /** Optional documentation URL. */
+  doc_url?: string;
+};
+/** Result of a stream delete operation. */
+type StreamDeleteResult = {
+  /** Previous value (if it existed). */old_value?: any;
+};
+/**
+ * Union of all atomic update operations supported by streams.
+ *
+ * @see {@link UpdateSet}, {@link UpdateIncrement}, {@link UpdateDecrement},
+ *      {@link UpdateAppend}, {@link UpdateRemove}, {@link UpdateMerge}
+ */
+type UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge;
+/** Input for atomically updating a stream item. */
+type StreamUpdateInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string; /** Ordered list of update operations to apply atomically. */
+  ops: UpdateOp[];
+};
+/** Trigger config for `stream` triggers. Filters which item changes fire the handler. */
+interface StreamTriggerConfig {
+  /** Stream name to watch. Only changes on this stream fire the handler. */
+  stream_name: string;
+  /** If set, only changes within this group fire the handler. */
+  group_id?: string;
+  /** If set, only changes to this specific item fire the handler. */
+  item_id?: string;
+  /** Function ID for conditional execution. If it returns `false`, the handler is skipped. */
+  condition_function_id?: string;
+}
+/** Trigger config for `stream:join` and `stream:leave` triggers. */
+interface StreamJoinLeaveTriggerConfig {
+  /** Function ID for conditional execution. If it returns `false`, the handler is skipped. */
+  condition_function_id?: string;
+}
+/** Detail of a stream change event containing the mutation type and data. */
+type StreamChangeEventDetail = {
+  /** The kind of mutation (create, update, or delete). */type: 'create' | 'update' | 'delete'; /** The data associated with the event. */
+  data: any;
+};
+/** Handler input for `stream` triggers, fired when an item changes via `stream::set`, `stream::update`, or `stream::delete`. */
+interface StreamChangeEvent {
+  /** The event type. */
+  type: 'stream';
+  /** Unix timestamp of the event. */
+  timestamp: number;
+  /** The stream where the change occurred. */
+  streamName: string;
+  /** The group where the change occurred. */
+  groupId: string;
+  /** The item ID that changed. */
+  id?: string;
+  /** The event detail containing mutation type and data. */
+  event: StreamChangeEventDetail;
+}
+//#endregion
+export { MergePath, StreamAuthInput, StreamAuthResult, StreamChangeEvent, StreamChangeEventDetail, StreamContext, StreamDeleteInput, StreamDeleteResult, StreamGetInput, StreamJoinLeaveEvent, StreamJoinLeaveTriggerConfig, StreamJoinResult, StreamListGroupsInput, StreamListInput, StreamSetInput, StreamSetResult, StreamTriggerConfig, StreamUpdateInput, StreamUpdateResult, UpdateAppend, UpdateDecrement, UpdateIncrement, UpdateMerge, UpdateOp, UpdateOpError, UpdateRemove, UpdateSet };
+//# sourceMappingURL=index.d.cts.map

package/dist/stream/index.d.mts

@@ -0,0 +1,249 @@
+//#region src/stream/index.d.ts
+/** Input for stream authentication. */
+interface StreamAuthInput {
+  /** Request headers. */
+  headers: Record<string, string>;
+  /** Request path. */
+  path: string;
+  /** Query parameters. */
+  query_params: Record<string, string[]>;
+  /** Client address. */
+  addr: string;
+}
+/** Result of stream authentication. */
+interface StreamAuthResult {
+  /** Arbitrary context passed to stream handlers after authentication. */
+  context?: any;
+}
+/** Context type extracted from {@link StreamAuthResult}. */
+type StreamContext = StreamAuthResult['context'];
+/** Event payload for stream join/leave events. */
+interface StreamJoinLeaveEvent {
+  /** Unique subscription identifier. */
+  subscription_id: string;
+  /** Name of the stream. */
+  stream_name: string;
+  /** Group identifier. */
+  group_id: string;
+  /** Item identifier (if applicable). */
+  id?: string;
+  /** Auth context from {@link StreamAuthResult}. */
+  context?: StreamContext;
+}
+/** Result of a stream join request. */
+interface StreamJoinResult {
+  /** Whether the join was unauthorized. */
+  unauthorized: boolean;
+}
+/** Input for retrieving a single stream item. */
+type StreamGetInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string;
+};
+/** Input for setting a stream item. */
+type StreamSetInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string; /** Data to store. */
+  data: any;
+};
+/** Input for deleting a stream item. */
+type StreamDeleteInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string;
+};
+/** Input for listing all items in a stream group. */
+type StreamListInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string;
+};
+/** Input for listing all groups in a stream. */
+type StreamListGroupsInput = {
+  /** Name of the stream. */stream_name: string;
+};
+/** Result of a stream set operation. */
+type StreamSetResult<TData> = {
+  /** Previous value (if it existed). */old_value?: TData; /** New value that was stored. */
+  new_value: TData;
+};
+/** Result of a stream update operation. */
+type StreamUpdateResult<TData> = {
+  /** Previous value (if it existed). */old_value?: TData; /** New value after the update. */
+  new_value: TData;
+  /**
+   * Per-op errors. Emitted by `merge` and `append` for validation
+   * rejections (path depth/size, value depth, or a
+   * `__proto__`/`constructor`/`prototype` segment or top-level key)
+   * and by `append` for the case-2 `append.type_mismatch` and
+   * `append.target_not_object` surfaces. Successfully applied ops are
+   * still reflected in `new_value`. The field is omitted from the
+   * JSON wire when empty.
+   */
+  errors?: UpdateOpError[];
+};
+/** Set a field at the given path to a value. */
+type UpdateSet = {
+  type: 'set'; /** First-level field path. Use an empty string to target the root value. */
+  path: string; /** Value to set. */
+  value: any;
+};
+/** Increment a numeric field by a given amount. */
+type UpdateIncrement = {
+  type: 'increment'; /** First-level field path. */
+  path: string; /** Amount to increment by. */
+  by: number;
+};
+/** Decrement a numeric field by a given amount. */
+type UpdateDecrement = {
+  type: 'decrement'; /** First-level field path. */
+  path: string; /** Amount to decrement by. */
+  by: number;
+};
+/**
+ * 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).
+ *
+ * Engine semantics:
+ *   - Missing or non-object intermediates along a nested path are
+ *     auto-replaced with `{}` so a stray `null` or scalar never blocks
+ *     future appends.
+ *   - At the leaf:
+ *       - missing/null + nested path → `[value]` (always an array)
+ *       - missing/null + single-string path → string-as-string for the
+ *         string-concat tier, otherwise `[value]`
+ *       - existing array → push
+ *       - existing string + string value → concatenate
+ *       - existing object/scalar at the leaf → `append.type_mismatch`
+ *   - Each path segment is a literal key. `["a.b"]` targets a single
+ *     key named `"a.b"`, not `a → b`.
+ *
+ * Validation: invalid paths (depth > 32 segments, segment > 256
+ * bytes, or any `__proto__`/`constructor`/`prototype` segment) are
+ * rejected with a structured error in the `errors` field of the
+ * `state::update` / `stream::update` response. The append does not
+ * apply when an error is returned for that op.
+ */
+type UpdateAppend = {
+  type: 'append';
+  /**
+   * Optional path to the append target. Accepts a single first-level
+   * key (legacy `string`) or an array of literal segments for nested
+   * append. See {@link MergePath} (the same shape is reused).
+   */
+  path?: MergePath; /** Value to append. String targets only accept string values. */
+  value: any;
+};
+/** Remove a field at the given path. */
+type UpdateRemove = {
+  type: 'remove'; /** First-level field path. */
+  path: string;
+};
+/**
+ * Path target for a {@link 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.
+ *
+ * @example single first-level field
+ *   { type: 'merge', path: 'session-abc', value: { author: 'alice' } }
+ * @example nested path (closes issue #1546's structured-state use case)
+ *   { type: 'merge', path: ['sessions', 'abc'], value: { ts: chunk } }
+ */
+type MergePath = string | string[];
+/**
+ * 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.
+ *
+ * Engine semantics:
+ *   - Missing or non-object intermediates along the path are
+ *     auto-replaced with `{}` so a stray `null` or scalar never
+ *     blocks future merges.
+ *   - The merge is shallow at the target — top-level keys of `value`
+ *     replace same-named keys; siblings are preserved.
+ *   - Each path segment is a literal key. `["a.b"]` writes a single
+ *     key named `"a.b"`, not `a → b`.
+ *
+ * Validation: invalid paths/values (depth > 32 segments, 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 `errors` field of the
+ * `state::update` / `stream::update` response. The merge does not
+ * apply when an error is returned for that op.
+ */
+type UpdateMerge = {
+  type: 'merge'; /** Optional path to the merge target. See {@link MergePath}. */
+  path?: MergePath; /** Object to merge. Must be a JSON object. */
+  value: any;
+};
+/** Per-op error returned by `state::update` / `stream::update`. */
+type UpdateOpError = {
+  /** Index of the offending op within the original `ops` array. */op_index: number; /** Stable error code, e.g. `"merge.path.too_deep"`. */
+  code: string; /** Human-readable description with concrete numbers when applicable. */
+  message: string; /** Optional documentation URL. */
+  doc_url?: string;
+};
+/** Result of a stream delete operation. */
+type StreamDeleteResult = {
+  /** Previous value (if it existed). */old_value?: any;
+};
+/**
+ * Union of all atomic update operations supported by streams.
+ *
+ * @see {@link UpdateSet}, {@link UpdateIncrement}, {@link UpdateDecrement},
+ *      {@link UpdateAppend}, {@link UpdateRemove}, {@link UpdateMerge}
+ */
+type UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge;
+/** Input for atomically updating a stream item. */
+type StreamUpdateInput = {
+  /** Name of the stream. */stream_name: string; /** Group identifier. */
+  group_id: string; /** Item identifier. */
+  item_id: string; /** Ordered list of update operations to apply atomically. */
+  ops: UpdateOp[];
+};
+/** Trigger config for `stream` triggers. Filters which item changes fire the handler. */
+interface StreamTriggerConfig {
+  /** Stream name to watch. Only changes on this stream fire the handler. */
+  stream_name: string;
+  /** If set, only changes within this group fire the handler. */
+  group_id?: string;
+  /** If set, only changes to this specific item fire the handler. */
+  item_id?: string;
+  /** Function ID for conditional execution. If it returns `false`, the handler is skipped. */
+  condition_function_id?: string;
+}
+/** Trigger config for `stream:join` and `stream:leave` triggers. */
+interface StreamJoinLeaveTriggerConfig {
+  /** Function ID for conditional execution. If it returns `false`, the handler is skipped. */
+  condition_function_id?: string;
+}
+/** Detail of a stream change event containing the mutation type and data. */
+type StreamChangeEventDetail = {
+  /** The kind of mutation (create, update, or delete). */type: 'create' | 'update' | 'delete'; /** The data associated with the event. */
+  data: any;
+};
+/** Handler input for `stream` triggers, fired when an item changes via `stream::set`, `stream::update`, or `stream::delete`. */
+interface StreamChangeEvent {
+  /** The event type. */
+  type: 'stream';
+  /** Unix timestamp of the event. */
+  timestamp: number;
+  /** The stream where the change occurred. */
+  streamName: string;
+  /** The group where the change occurred. */
+  groupId: string;
+  /** The item ID that changed. */
+  id?: string;
+  /** The event detail containing mutation type and data. */
+  event: StreamChangeEventDetail;
+}
+//#endregion
+export { MergePath, StreamAuthInput, StreamAuthResult, StreamChangeEvent, StreamChangeEventDetail, StreamContext, StreamDeleteInput, StreamDeleteResult, StreamGetInput, StreamJoinLeaveEvent, StreamJoinLeaveTriggerConfig, StreamJoinResult, StreamListGroupsInput, StreamListInput, StreamSetInput, StreamSetResult, StreamTriggerConfig, StreamUpdateInput, StreamUpdateResult, UpdateAppend, UpdateDecrement, UpdateIncrement, UpdateMerge, UpdateOp, UpdateOpError, UpdateRemove, UpdateSet };
+//# sourceMappingURL=index.d.mts.map

package/dist/stream/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/worker-connection-manager/index.d.cts

@@ -0,0 +1,95 @@
+//#region src/worker-connection-manager/index.d.ts
+/**
+ * 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>; /** Optional prefix applied to all function IDs registered by this worker. */
+  function_registration_prefix?: string;
+};
+/**
+ * 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 {@link OnTriggerTypeRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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>;
+};
+/**
+ * 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.
+ */
+type OnTriggerTypeRegistrationResult = {
+  /** Mapped trigger type ID. */trigger_type_id?: string; /** Mapped description. */
+  description?: string;
+};
+/**
+ * Input passed to the `on_trigger_registration_function_id` hook
+ * when a worker attempts to register a trigger through the RBAC port.
+ * Return an {@link OnTriggerRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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; /** Arbitrary metadata attached to the trigger. */
+  metadata?: Record<string, unknown>; /** Auth context from `AuthResult.context` for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * Result returned from the `on_trigger_registration_function_id` hook.
+ * All fields are optional -- omitted fields keep the original value from the
+ * registration request.
+ */
+type OnTriggerRegistrationResult = {
+  /** Mapped trigger ID. */trigger_id?: string; /** Mapped trigger type. */
+  trigger_type?: string; /** Mapped function ID. */
+  function_id?: string; /** Mapped trigger configuration. */
+  config?: unknown;
+};
+/**
+ * Input passed to the `on_function_registration_function_id` hook
+ * when a worker attempts to register a function through the RBAC port.
+ * Return an {@link OnFunctionRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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 from the `on_function_registration_function_id` hook.
+ * All fields are optional -- omitted fields keep the original value from the
+ * registration request.
+ */
+type OnFunctionRegistrationResult = {
+  /** Mapped function ID. */function_id?: string; /** Mapped description. */
+  description?: string; /** Mapped metadata. */
+  metadata?: Record<string, unknown>;
+};
+//#endregion
+export { AuthInput, AuthResult, OnFunctionRegistrationInput, OnFunctionRegistrationResult, OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult };
+//# sourceMappingURL=index.d.cts.map

package/dist/worker-connection-manager/index.d.mts

@@ -0,0 +1,95 @@
+//#region src/worker-connection-manager/index.d.ts
+/**
+ * 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>; /** Optional prefix applied to all function IDs registered by this worker. */
+  function_registration_prefix?: string;
+};
+/**
+ * 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 {@link OnTriggerTypeRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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>;
+};
+/**
+ * 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.
+ */
+type OnTriggerTypeRegistrationResult = {
+  /** Mapped trigger type ID. */trigger_type_id?: string; /** Mapped description. */
+  description?: string;
+};
+/**
+ * Input passed to the `on_trigger_registration_function_id` hook
+ * when a worker attempts to register a trigger through the RBAC port.
+ * Return an {@link OnTriggerRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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; /** Arbitrary metadata attached to the trigger. */
+  metadata?: Record<string, unknown>; /** Auth context from `AuthResult.context` for this session. */
+  context: Record<string, unknown>;
+};
+/**
+ * Result returned from the `on_trigger_registration_function_id` hook.
+ * All fields are optional -- omitted fields keep the original value from the
+ * registration request.
+ */
+type OnTriggerRegistrationResult = {
+  /** Mapped trigger ID. */trigger_id?: string; /** Mapped trigger type. */
+  trigger_type?: string; /** Mapped function ID. */
+  function_id?: string; /** Mapped trigger configuration. */
+  config?: unknown;
+};
+/**
+ * Input passed to the `on_function_registration_function_id` hook
+ * when a worker attempts to register a function through the RBAC port.
+ * Return an {@link OnFunctionRegistrationResult} with the (possibly mapped)
+ * fields, or throw to deny 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 from the `on_function_registration_function_id` hook.
+ * All fields are optional -- omitted fields keep the original value from the
+ * registration request.
+ */
+type OnFunctionRegistrationResult = {
+  /** Mapped function ID. */function_id?: string; /** Mapped description. */
+  description?: string; /** Mapped metadata. */
+  metadata?: Record<string, unknown>;
+};
+//#endregion
+export { AuthInput, AuthResult, OnFunctionRegistrationInput, OnFunctionRegistrationResult, OnTriggerRegistrationInput, OnTriggerRegistrationResult, OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult };
+//# sourceMappingURL=index.d.mts.map

package/dist/worker-connection-manager/index.mjs

@@ -0,0 +1 @@
+export {  };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@iii-dev/helpers",
+  "version": "0.19.4-alpha.2",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "author": "III",
+  "license": "Apache-2.0",
+  "description": "Shared helper primitives across iii SDKs.",
+  "keywords": [
+    "iii",
+    "helpers"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    "./http": {
+      "import": {
+        "types": "./dist/http/index.d.mts",
+        "default": "./dist/http/index.mjs"
+      },
+      "require": {
+        "types": "./dist/http/index.d.cts",
+        "default": "./dist/http/index.cjs"
+      }
+    },
+    "./queue": {
+      "import": {
+        "types": "./dist/queue/index.d.mts",
+        "default": "./dist/queue/index.mjs"
+      },
+      "require": {
+        "types": "./dist/queue/index.d.cts",
+        "default": "./dist/queue/index.cjs"
+      }
+    },
+    "./stream": {
+      "import": {
+        "types": "./dist/stream/index.d.mts",
+        "default": "./dist/stream/index.mjs"
+      },
+      "require": {
+        "types": "./dist/stream/index.d.cts",
+        "default": "./dist/stream/index.cjs"
+      }
+    },
+    "./worker-connection-manager": {
+      "import": {
+        "types": "./dist/worker-connection-manager/index.d.mts",
+        "default": "./dist/worker-connection-manager/index.mjs"
+      },
+      "require": {
+        "types": "./dist/worker-connection-manager/index.d.cts",
+        "default": "./dist/worker-connection-manager/index.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^2.1.0",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}