iii-sdk 0.8.2 → 0.9.0

package/README.md

@@ -14,9 +14,9 @@ npm install iii-sdk
 ## Hello World
 
 ```javascript
-import { init } from 'iii-sdk'
+import { registerWorker } from 'iii-sdk'
 
-const iii = init('ws://localhost:49134')
+const iii = registerWorker('ws://localhost:49134')
 
 iii.registerFunction({ id: 'greet' }, async (input) => {
   return { message: `Hello, ${input.name}!` }
@@ -28,18 +28,18 @@ iii.registerTrigger({
   config: { api_path: '/greet', http_method: 'POST' },
 })
 
-const result = await iii.trigger('greet', { name: 'world' })
+const result = await iii.trigger({ function_id: 'greet', payload: { name: 'world' } })
 ```
 
 ## API
 
 | Operation                | Signature                                            | Description                                                  |
 | ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
-| Initialize               | `init(url, options?)`                                | Create and connect to the engine. Returns an `ISdk` instance |
+| Initialize               | `registerWorker(url, options?)`                      | Create and connect to the engine. Returns an `ISdk` instance |
 | Register function        | `iii.registerFunction({ id }, handler)`              | Register a function that can be invoked by name              |
 | Register trigger         | `iii.registerTrigger({ type, function_id, config })` | Bind a trigger (HTTP, cron, queue, etc.) to a function       |
-| Invoke (await)           | `await iii.trigger(id, data, timeoutMs?)`            | Invoke a function and wait for the result                    |
-| Invoke (fire-and-forget) | `iii.triggerVoid(id, data)`                          | Invoke a function without waiting (fire-and-forget)          |
+| Invoke (await)           | `await iii.trigger({ function_id, payload })`       | Invoke a function and wait for the result                    |
+| Invoke (fire-and-forget) | `iii.trigger({ function_id, payload, action: TriggerAction.Void() })` | Invoke without waiting |
 
 ### Registering Functions
 
@@ -62,23 +62,27 @@ iii.registerTrigger({
 ### Invoking Functions
 
 ```javascript
-const result = await iii.trigger('orders.create', { item: 'widget' })
+import { registerWorker, TriggerAction } from 'iii-sdk'
 
-iii.triggerVoid('analytics.track', { event: 'page_view' })
+const iii = registerWorker('ws://localhost:49134')
+
+const result = await iii.trigger({ function_id: 'orders.create', payload: { item: 'widget' } })
+
+iii.trigger({ function_id: 'analytics.track', payload: { event: 'page_view' }, action: TriggerAction.Void() })
 ```
 
 ## Node Modules
 
 | Import              | What it provides                      |
 | ------------------- | ------------------------------------- |
-| `iii-sdk`           | Core SDK (`init`, types)              |
+| `iii-sdk`           | Core SDK (`registerWorker`, types)    |
 | `iii-sdk/stream`    | Stream client for real-time state     |
 | `iii-sdk/state`     | State client for key-value operations |
 | `iii-sdk/telemetry` | OpenTelemetry integration             |
 
-## Deprecated
+## Removed methods
 
-`call()` and `callVoid()` are deprecated aliases for `trigger()` and `triggerVoid()`. They still work but will be removed in a future release.
+`call`, `callVoid`, and `triggerVoid` have been removed. Use `trigger()` for all invocations. For fire-and-forget, use `trigger({ function_id, payload, action: TriggerAction.Void() })`.
 
 ## Resources
 

package/dist/index.cjs

@@ -25,16 +25,33 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_utils = require('./utils-BJTjoUdq.cjs');
+const require_utils = require('./utils-bsZVduQi.cjs');
+let node_stream = require("node:stream");
+let ws = require("ws");
 let __opentelemetry_api = require("@opentelemetry/api");
 let node_module = require("node:module");
 let node_os = require("node:os");
 node_os = __toESM(node_os);
-let ws = require("ws");
-let node_stream = require("node:stream");
 let __opentelemetry_api_logs = require("@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;
@@ -79,12 +96,14 @@ 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");
@@ -117,6 +136,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;
@@ -159,9 +193,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 !== ws.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}`;
@@ -203,11 +247,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);
@@ -219,9 +261,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);
@@ -292,14 +331,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),
@@ -307,11 +353,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$1 = require_utils.injectTraceparent();
+				const baggage$1 = require_utils.injectBaggage();
+				this.sendMessage(MessageType.InvokeFunction, {
+					function_id,
+					data: payload,
+					traceparent: traceparent$1,
+					baggage: baggage$1,
+					action
+				});
+				return;
+			}
 			const invocation_id = crypto.randomUUID();
 			const traceparent = require_utils.injectTraceparent();
 			const baggage = require_utils.injectBaggage();
-			const effectiveTimeout = timeoutMs ?? this.invocationTimeoutMs;
 			return new Promise((resolve, reject) => {
 				const timeout = setTimeout(() => {
 					if (this.invocations.get(invocation_id)) {
@@ -333,29 +392,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 = require_utils.injectTraceparent();
-			const baggage = require_utils.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(require_utils.EngineFunctions.LIST_FUNCTIONS, {})).functions;
+			return (await this.trigger({
+				function_id: require_utils.EngineFunctions.LIST_FUNCTIONS,
+				payload: {}
+			})).functions;
 		};
 		this.listWorkers = async () => {
-			return (await this.trigger(require_utils.EngineFunctions.LIST_WORKERS, {})).workers;
+			return (await this.trigger({
+				function_id: require_utils.EngineFunctions.LIST_WORKERS,
+				payload: {}
+			})).workers;
+		};
+		this.listTriggers = async (includeInternal = false) => {
+			return (await this.trigger({
+				function_id: require_utils.EngineFunctions.LIST_TRIGGERS,
+				payload: { include_internal: includeInternal }
+			})).triggers;
 		};
 		this.createStream = (streamName, stream) => {
 			this.registerFunction({ id: `stream::get(${streamName})` }, stream.get.bind(stream));
@@ -389,48 +449,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: require_utils.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();
@@ -446,7 +464,6 @@ var Sdk = class {
 				this.ws.close();
 				this.ws = void 0;
 			}
-			this.stateCallbacks.clear();
 			this.setConnectionState("disconnected");
 		};
 		this.workerName = options?.workerName ?? getDefaultWorkerName();
@@ -465,29 +482,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(require_utils.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: require_utils.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;
@@ -632,18 +646,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) {
@@ -686,12 +688,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()
@@ -777,10 +781,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 = require_utils.getLogger();
@@ -821,15 +897,67 @@ 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, __opentelemetry_api_logs.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, __opentelemetry_api_logs.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, __opentelemetry_api_logs.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, __opentelemetry_api_logs.SeverityNumber.DEBUG, data);
 	}
@@ -839,6 +967,7 @@ var Logger = class {
 exports.ChannelReader = ChannelReader;
 exports.ChannelWriter = ChannelWriter;
 exports.Logger = Logger;
+exports.TriggerAction = TriggerAction;
 exports.__toESM = __toESM;
 exports.http = require_utils.http;
 exports.registerWorker = registerWorker;