iii-sdk 0.8.3 → 0.10.0

package/dist/index.mjs

@@ -1,12 +1,29 @@
-import { A as EngineTriggers, C as injectBaggage, D as DEFAULT_BRIDGE_RECONNECTION_CONFIG, O as DEFAULT_INVOCATION_TIMEOUT_MS, _ as currentTraceId, a as stopWorkerGauges, c as SpanKind$1, d as getMeter, f as getTracer, g as currentSpanId, h as withSpan, i as registerWorkerGauges, k as EngineFunctions, m as shutdownOtel, n as isChannelRef, p as initOtel, s as SeverityNumber$1, t as http, u as getLogger, w as injectTraceparent, y as extractContext } from "./utils-coGqiBHT.mjs";
+import { A as EngineTriggers, D as DEFAULT_BRIDGE_RECONNECTION_CONFIG, O as DEFAULT_INVOCATION_TIMEOUT_MS, T as stopWorkerGauges, a as SpanKind$1, b as injectBaggage, c as getMeter, d as shutdownOtel, f as withSpan, g as extractContext, i as SeverityNumber$1, k as EngineFunctions, l as getTracer, m as currentTraceId, n as isChannelRef, p as currentSpanId, s as getLogger, t as http, u as initOtel, w as registerWorkerGauges, x as injectTraceparent } from "./utils-xBUm8n1P.mjs";
 import { createRequire } from "node:module";
+import { Readable, Writable } from "node:stream";
+import { WebSocket } from "ws";
 import { context, trace } from "@opentelemetry/api";
 import * as os from "node:os";
-import { WebSocket } from "ws";
-import { Readable, Writable } from "node:stream";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 
 //#region src/channels.ts
+/**
+* Write end of a streaming channel. Provides both a Node.js `Writable` stream
+* and a `sendMessage` method for sending structured text messages.
+*
+* @example
+* ```typescript
+* const channel = await iii.createChannel()
+*
+* // Stream binary data
+* channel.writer.stream.write(Buffer.from('hello'))
+* channel.writer.stream.end()
+*
+* // Or send text messages
+* channel.writer.sendMessage(JSON.stringify({ type: 'event', data: 'test' }))
+* channel.writer.close()
+* ```
+*/
 var ChannelWriter = class ChannelWriter {
 	static {
 		this.FRAME_SIZE = 64 * 1024;
@@ -26,9 +43,12 @@ var ChannelWriter = class ChannelWriter {
 					callback();
 					return;
 				}
-				if (this.wsReady) this.ws.close(1e3, "stream_complete");
-				else this.ws.on("open", () => this.ws?.close(1e3, "stream_complete"));
-				callback();
+				const doClose = () => {
+					if (this.ws) this.ws.close(1e3, "stream_complete");
+					callback();
+				};
+				if (this.wsReady) setTimeout(doClose, 10);
+				else this.ws.on("open", () => setTimeout(doClose, 10));
 			},
 			destroy: (err, callback) => {
 				if (this.ws) this.ws.terminate();
@@ -51,16 +71,21 @@ var ChannelWriter = class ChannelWriter {
 			if (!this.stream.destroyed) this.stream.destroy();
 		});
 	}
+	/** Send a text message through the channel. */
 	sendMessage(msg) {
 		this.ensureConnected();
 		this.sendRaw(msg, (err) => {
 			if (err) this.stream.destroy(err);
 		});
 	}
+	/** Close the channel writer. */
 	close() {
 		if (!this.ws) return;
-		if (this.wsReady) this.ws.close(1e3, "channel_close");
-		else this.ws.on("open", () => this.ws?.close(1e3, "channel_close"));
+		const doClose = () => {
+			if (this.ws) this.ws.close(1e3, "channel_close");
+		};
+		if (this.wsReady) doClose();
+		else this.ws.on("open", () => doClose());
 	}
 	sendChunked(data, callback) {
 		let offset = 0;
@@ -89,6 +114,21 @@ var ChannelWriter = class ChannelWriter {
 		});
 	}
 };
+/**
+* Read end of a streaming channel. Provides both a Node.js `Readable` stream
+* for binary data and an `onMessage` callback for structured text messages.
+*
+* @example
+* ```typescript
+* const channel = await iii.createChannel()
+*
+* // Stream binary data
+* channel.reader.stream.on('data', (chunk) => console.log(chunk))
+*
+* // Or receive text messages
+* channel.reader.onMessage((msg) => console.log('Got:', msg))
+* ```
+*/
 var ChannelReader = class {
 	constructor(engineWsBase, ref) {
 		this.ws = null;
@@ -131,9 +171,19 @@ var ChannelReader = class {
 			this.stream.destroy(err);
 		});
 	}
+	/** Register a callback to receive text messages from the channel. */
 	onMessage(callback) {
 		this.messageCallbacks.push(callback);
 	}
+	async readAll() {
+		this.ensureConnected();
+		const chunks = [];
+		for await (const chunk of this.stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		return Buffer.concat(chunks);
+	}
+	close() {
+		if (this.ws && this.ws.readyState !== WebSocket.CLOSED) this.ws.close(1e3, "channel_close");
+	}
 };
 function buildChannelUrl(engineWsBase, channelId, accessKey, direction) {
 	return `${engineWsBase.replace(/\/$/, "")}/ws/channels/${channelId}?key=${encodeURIComponent(accessKey)}&dir=${direction}`;
@@ -141,19 +191,19 @@ function buildChannelUrl(engineWsBase, channelId, accessKey, direction) {
 
 //#endregion
 //#region src/iii-types.ts
-let MessageType = /* @__PURE__ */ function(MessageType$1) {
-	MessageType$1["RegisterFunction"] = "registerfunction";
-	MessageType$1["UnregisterFunction"] = "unregisterfunction";
-	MessageType$1["RegisterService"] = "registerservice";
-	MessageType$1["InvokeFunction"] = "invokefunction";
-	MessageType$1["InvocationResult"] = "invocationresult";
-	MessageType$1["RegisterTriggerType"] = "registertriggertype";
-	MessageType$1["RegisterTrigger"] = "registertrigger";
-	MessageType$1["UnregisterTrigger"] = "unregistertrigger";
-	MessageType$1["UnregisterTriggerType"] = "unregistertriggertype";
-	MessageType$1["TriggerRegistrationResult"] = "triggerregistrationresult";
-	MessageType$1["WorkerRegistered"] = "workerregistered";
-	return MessageType$1;
+let MessageType = /* @__PURE__ */ function(MessageType) {
+	MessageType["RegisterFunction"] = "registerfunction";
+	MessageType["UnregisterFunction"] = "unregisterfunction";
+	MessageType["RegisterService"] = "registerservice";
+	MessageType["InvokeFunction"] = "invokefunction";
+	MessageType["InvocationResult"] = "invocationresult";
+	MessageType["RegisterTriggerType"] = "registertriggertype";
+	MessageType["RegisterTrigger"] = "registertrigger";
+	MessageType["UnregisterTrigger"] = "unregistertrigger";
+	MessageType["UnregisterTriggerType"] = "unregistertriggertype";
+	MessageType["TriggerRegistrationResult"] = "triggerregistrationresult";
+	MessageType["WorkerRegistered"] = "workerregistered";
+	return MessageType;
 }({});
 
 //#endregion
@@ -175,11 +225,9 @@ var Sdk = class {
 		this.triggers = /* @__PURE__ */ new Map();
 		this.triggerTypes = /* @__PURE__ */ new Map();
 		this.functionsAvailableCallbacks = /* @__PURE__ */ new Set();
-		this.logCallbacks = /* @__PURE__ */ new Map();
 		this.messagesToSend = [];
 		this.reconnectAttempt = 0;
 		this.connectionState = "disconnected";
-		this.stateCallbacks = /* @__PURE__ */ new Set();
 		this.isShuttingDown = false;
 		this.registerTriggerType = (triggerType, handler) => {
 			this.sendMessage(MessageType.RegisterTriggerType, triggerType, true);
@@ -191,9 +239,6 @@ var Sdk = class {
 				handler
 			});
 		};
-		this.on = (event, callback) => {
-			this.ws?.on(event, callback);
-		};
 		this.unregisterTriggerType = (triggerType) => {
 			this.sendMessage(MessageType.UnregisterTriggerType, triggerType, true);
 			this.triggerTypes.delete(triggerType.id);
@@ -264,14 +309,21 @@ var Sdk = class {
 			};
 		};
 		this.registerService = (message) => {
-			this.sendMessage(MessageType.RegisterService, message, true);
-			this.services.set(message.id, {
+			const msg = {
 				...message,
+				name: message.name ?? message.id
+			};
+			this.sendMessage(MessageType.RegisterService, msg, true);
+			this.services.set(message.id, {
+				...msg,
 				message_type: MessageType.RegisterService
 			});
 		};
 		this.createChannel = async (bufferSize) => {
-			const result = await this.call("engine::channels::create", { buffer_size: bufferSize });
+			const result = await this.trigger({
+				function_id: "engine::channels::create",
+				payload: { buffer_size: bufferSize }
+			});
 			return {
 				writer: new ChannelWriter(this.address, result.writer),
 				reader: new ChannelReader(this.address, result.reader),
@@ -279,11 +331,24 @@ var Sdk = class {
 				readerRef: result.reader
 			};
 		};
-		this.trigger = async (function_id, data, timeoutMs) => {
+		this.trigger = async (request) => {
+			const { function_id, payload, action, timeoutMs } = request;
+			const effectiveTimeout = timeoutMs ?? this.invocationTimeoutMs;
+			if (action?.type === "void") {
+				const traceparent = injectTraceparent();
+				const baggage = injectBaggage();
+				this.sendMessage(MessageType.InvokeFunction, {
+					function_id,
+					data: payload,
+					traceparent,
+					baggage,
+					action
+				});
+				return;
+			}
 			const invocation_id = crypto.randomUUID();
 			const traceparent = injectTraceparent();
 			const baggage = injectBaggage();
-			const effectiveTimeout = timeoutMs ?? this.invocationTimeoutMs;
 			return new Promise((resolve, reject) => {
 				const timeout = setTimeout(() => {
 					if (this.invocations.get(invocation_id)) {
@@ -305,29 +370,30 @@ var Sdk = class {
 				this.sendMessage(MessageType.InvokeFunction, {
 					invocation_id,
 					function_id,
-					data,
+					data: payload,
 					traceparent,
-					baggage
+					baggage,
+					action
 				});
 			});
 		};
-		this.triggerVoid = (function_id, data) => {
-			const traceparent = injectTraceparent();
-			const baggage = injectBaggage();
-			this.sendMessage(MessageType.InvokeFunction, {
-				function_id,
-				data,
-				traceparent,
-				baggage
-			});
-		};
-		this.call = async (function_id, data, timeoutMs) => this.trigger(function_id, data, timeoutMs);
-		this.callVoid = (function_id, data) => this.triggerVoid(function_id, data);
 		this.listFunctions = async () => {
-			return (await this.trigger(EngineFunctions.LIST_FUNCTIONS, {})).functions;
+			return (await this.trigger({
+				function_id: EngineFunctions.LIST_FUNCTIONS,
+				payload: {}
+			})).functions;
 		};
 		this.listWorkers = async () => {
-			return (await this.trigger(EngineFunctions.LIST_WORKERS, {})).workers;
+			return (await this.trigger({
+				function_id: EngineFunctions.LIST_WORKERS,
+				payload: {}
+			})).workers;
+		};
+		this.listTriggers = async (includeInternal = false) => {
+			return (await this.trigger({
+				function_id: EngineFunctions.LIST_TRIGGERS,
+				payload: { include_internal: includeInternal }
+			})).triggers;
 		};
 		this.createStream = (streamName, stream) => {
 			this.registerFunction({ id: `stream::get(${streamName})` }, stream.get.bind(stream));
@@ -361,48 +427,6 @@ var Sdk = class {
 				}
 			};
 		};
-		this.onLog = (callback, config) => {
-			const effectiveConfig = config ?? { level: "all" };
-			this.logCallbacks.set(callback, effectiveConfig);
-			if (!this.logTrigger) {
-				if (!this.logFunctionPath) this.logFunctionPath = `engine.on_log.${crypto.randomUUID()}`;
-				const function_id = this.logFunctionPath;
-				if (!this.functions.has(function_id)) this.registerFunction({ id: function_id }, async (log) => {
-					this.logCallbacks.forEach((cfg, handler) => {
-						try {
-							const minSeverity = this.severityTextToNumber(cfg.level ?? "all");
-							if (cfg.level === "all" || log.severity_number >= minSeverity) handler(log);
-						} catch (error) {
-							this.logError("Log callback handler threw an exception", error);
-						}
-					});
-					return null;
-				});
-				this.logTrigger = this.registerTrigger({
-					type: EngineTriggers.LOG,
-					function_id,
-					config: {
-						level: "all",
-						severity_min: 0
-					}
-				});
-			}
-			return () => {
-				this.logCallbacks.delete(callback);
-				if (this.logCallbacks.size === 0 && this.logTrigger) {
-					this.logTrigger.unregister();
-					this.logTrigger = void 0;
-				}
-			};
-		};
-		this.getConnectionState = () => {
-			return this.connectionState;
-		};
-		this.onConnectionStateChange = (callback) => {
-			this.stateCallbacks.add(callback);
-			callback(this.connectionState);
-			return () => this.stateCallbacks.delete(callback);
-		};
 		this.shutdown = async () => {
 			this.isShuttingDown = true;
 			this.stopMetricsReporting();
@@ -418,12 +442,11 @@ var Sdk = class {
 				this.ws.close();
 				this.ws = void 0;
 			}
-			this.stateCallbacks.clear();
 			this.setConnectionState("disconnected");
 		};
 		this.workerName = options?.workerName ?? getDefaultWorkerName();
 		this.metricsReportingEnabled = options?.enableMetricsReporting ?? true;
-		this.invocationTimeoutMs = options?.invocationTimeoutMs ?? DEFAULT_INVOCATION_TIMEOUT_MS;
+		this.invocationTimeoutMs = options?.invocationTimeoutMs ?? 3e4;
 		this.reconnectionConfig = {
 			...DEFAULT_BRIDGE_RECONNECTION_CONFIG,
 			...options?.reconnectionConfig
@@ -437,29 +460,26 @@ var Sdk = class {
 	registerWorkerMetadata() {
 		const telemetryOpts = this.options?.telemetry;
 		const language = telemetryOpts?.language ?? Intl.DateTimeFormat().resolvedOptions().locale ?? process.env.LANG?.split(".")[0];
-		this.triggerVoid(EngineFunctions.REGISTER_WORKER, {
-			runtime: "node",
-			version: SDK_VERSION,
-			name: this.workerName,
-			os: getOsInfo(),
-			pid: process.pid,
-			telemetry: {
-				language,
-				project_name: telemetryOpts?.project_name,
-				framework: telemetryOpts?.framework,
-				amplitude_api_key: telemetryOpts?.amplitude_api_key
-			}
+		this.trigger({
+			function_id: EngineFunctions.REGISTER_WORKER,
+			payload: {
+				runtime: "node",
+				version: SDK_VERSION,
+				name: this.workerName,
+				os: getOsInfo(),
+				pid: process.pid,
+				telemetry: {
+					language,
+					project_name: telemetryOpts?.project_name,
+					framework: telemetryOpts?.framework,
+					amplitude_api_key: telemetryOpts?.amplitude_api_key
+				}
+			},
+			action: { type: "void" }
 		});
 	}
 	setConnectionState(state) {
-		if (this.connectionState !== state) {
-			this.connectionState = state;
-			for (const callback of this.stateCallbacks) try {
-				callback(state);
-			} catch (error) {
-				this.logError("Error in connection state callback", error);
-			}
-		}
+		if (this.connectionState !== state) this.connectionState = state;
 	}
 	connect() {
 		if (this.isShuttingDown) return;
@@ -604,18 +624,6 @@ var Sdk = class {
 		});
 		else console.error(`[iii] ${message}`, error ?? "");
 	}
-	severityTextToNumber(level) {
-		switch (level) {
-			case "trace": return 1;
-			case "debug": return 5;
-			case "info": return 9;
-			case "warn": return 13;
-			case "error": return 17;
-			case "fatal": return 21;
-			case "all": return 0;
-			default: return 0;
-		}
-	}
 	onInvocationResult(invocation_id, result, error) {
 		const invocation = this.invocations.get(invocation_id);
 		if (invocation) {
@@ -658,12 +666,14 @@ var Sdk = class {
 					baggage: getResponseBaggage()
 				});
 			} catch (error) {
+				const isError = error instanceof Error;
 				this.sendMessage(MessageType.InvocationResult, {
 					invocation_id,
 					function_id,
 					error: {
 						code: "invocation_failed",
-						message: error.message
+						message: isError ? error.message : String(error),
+						stacktrace: isError ? error.stack : void 0
 					},
 					traceparent: getResponseTraceparent(),
 					baggage: getResponseBaggage()
@@ -749,10 +759,82 @@ var Sdk = class {
 		}
 	}
 };
+/**
+* Factory object that constructs routing actions for {@link ISdk.trigger}.
+*
+* @example
+* ```typescript
+* import { TriggerAction } from 'iii-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(),
+* })
+* ```
+*/
+const TriggerAction = {
+	Enqueue: (opts) => ({
+		type: "enqueue",
+		...opts
+	}),
+	Void: () => ({ type: "void" })
+};
+/**
+* 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:49134`).
+* @param options - Optional {@link InitOptions} for worker name, timeouts, reconnection, and OTel.
+* @returns A connected {@link ISdk} instance.
+*
+* @example
+* ```typescript
+* import { registerWorker } from 'iii-sdk'
+*
+* const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134', {
+*   workerName: 'my-worker',
+* })
+* ```
+*/
 const registerWorker = (address, options) => new Sdk(address, options);
 
 //#endregion
 //#region src/logger.ts
+/**
+* Structured logger that emits logs as OpenTelemetry LogRecords.
+*
+* Every log call automatically captures the active trace and span context,
+* correlating your logs with distributed traces without any manual wiring.
+* When OTel is not initialized, Logger gracefully falls back to `console.*`.
+*
+* Pass structured data as the second argument to any log method. Using an
+* object of key-value pairs (instead of string interpolation) lets you
+* filter, aggregate, and build dashboards in your observability backend.
+*
+* @example
+* ```typescript
+* import { Logger } from 'iii-sdk'
+*
+* const logger = new Logger()
+*
+* // Basic logging — trace context is injected automatically
+* logger.info('Worker connected')
+*
+* // Structured context for dashboards and alerting
+* logger.info('Order processed', { orderId: 'ord_123', amount: 49.99, currency: 'USD' })
+* logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge' })
+* logger.error('Payment failed', { orderId: 'ord_123', gateway: 'stripe', errorCode: 'card_declined' })
+* ```
+*/
 var Logger = class {
 	get otelLogger() {
 		if (!this._otelLogger) this._otelLogger = getLogger();
@@ -793,20 +875,72 @@ var Logger = class {
 			default: console.log(message, data);
 		}
 	}
+	/**
+	* Log an info-level message.
+	*
+	* @param message - Human-readable log message.
+	* @param data - Structured context attached as OTel log attributes.
+	*   Use key-value objects to enable filtering and aggregation in your
+	*   observability backend (e.g. Grafana, Datadog, New Relic).
+	*
+	* @example
+	* ```typescript
+	* logger.info('Order processed', { orderId: 'ord_123', status: 'completed' })
+	* ```
+	*/
 	info(message, data) {
 		this.emit(message, SeverityNumber.INFO, data);
 	}
+	/**
+	* Log a warning-level message.
+	*
+	* @param message - Human-readable log message.
+	* @param data - Structured context attached as OTel log attributes.
+	*   Use key-value objects to enable filtering and aggregation in your
+	*   observability backend (e.g. Grafana, Datadog, New Relic).
+	*
+	* @example
+	* ```typescript
+	* logger.warn('Retry attempt', { attempt: 3, maxRetries: 5, endpoint: '/api/charge' })
+	* ```
+	*/
 	warn(message, data) {
 		this.emit(message, SeverityNumber.WARN, data);
 	}
+	/**
+	* Log an error-level message.
+	*
+	* @param message - Human-readable log message.
+	* @param data - Structured context attached as OTel log attributes.
+	*   Use key-value objects to enable filtering and aggregation in your
+	*   observability backend (e.g. Grafana, Datadog, New Relic).
+	*
+	* @example
+	* ```typescript
+	* logger.error('Payment failed', { orderId: 'ord_123', gateway: 'stripe', errorCode: 'card_declined' })
+	* ```
+	*/
 	error(message, data) {
 		this.emit(message, SeverityNumber.ERROR, data);
 	}
+	/**
+	* Log a debug-level message.
+	*
+	* @param message - Human-readable log message.
+	* @param data - Structured context attached as OTel log attributes.
+	*   Use key-value objects to enable filtering and aggregation in your
+	*   observability backend (e.g. Grafana, Datadog, New Relic).
+	*
+	* @example
+	* ```typescript
+	* logger.debug('Cache lookup', { key: 'user:42', hit: false })
+	* ```
+	*/
 	debug(message, data) {
 		this.emit(message, SeverityNumber.DEBUG, data);
 	}
 };
 
 //#endregion
-export { ChannelReader, ChannelWriter, Logger, http, registerWorker };
+export { ChannelReader, ChannelWriter, Logger, TriggerAction, http, registerWorker };
 //# sourceMappingURL=index.mjs.map