iii-sdk 0.4.1 → 0.8.0

package/README.md

@@ -1,100 +1,87 @@
-# III SDK for Node.js
+# iii-sdk
 
-## Installation
+Node.js / TypeScript SDK for the [iii engine](https://github.com/iii-hq/iii).
+
+[![npm](https://img.shields.io/npm/v/iii-sdk)](https://www.npmjs.com/package/iii-sdk)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../../LICENSE)
+
+## Install
 
 ```bash
 npm install iii-sdk
 ```
 
-## Usage
+## Hello World
 
 ```javascript
-import { III } from 'iii-sdk'
+import { init } from 'iii-sdk'
 
-/**
- * Make sure the III Core Instance is up and Running on the given URL.
- */
-const iii = new III(process.env.III_BRIDGE_URL ?? 'ws://localhost:49134')
+const iii = init('ws://localhost:49134')
 
-iii.registerFunction({ id: 'myFunction' }, (req) => {
-  return { status_code: 200, body: { message: 'Hello, world!' } }
+iii.registerFunction({ id: 'greet' }, async (input) => {
+  return { message: `Hello, ${input.name}!` }
 })
 
 iii.registerTrigger({
   type: 'http',
-  function_id: 'myFunction',
-  config: { api_path: 'myApiPath', http_method: 'POST' },
+  function_id: 'greet',
+  config: { api_path: '/greet', http_method: 'POST' },
 })
+
+const result = await iii.trigger('greet', { name: 'world' })
 ```
 
-### Registering Functions
+## API
 
-III Allows you to register functions that can be invoked by other services.
+| Operation                | Signature                                            | Description                                                  |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
+| Initialize               | `init(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)          |
+
+### Registering Functions
 
 ```javascript
-iii.registerFunction({ id: 'myFunction' }, (req) => {
-  // ... do something
-  return { status_code: 200, body: { message: 'Hello, world!' } }
+iii.registerFunction({ id: 'orders.create' }, async (input) => {
+  return { status_code: 201, body: { id: '123', item: input.body.item } }
 })
 ```
 
 ### Registering Triggers
 
-III Allows you to register triggers that can be invoked by other services.
-
 ```javascript
 iii.registerTrigger({
   type: 'http',
-  function_id: 'myFunction',
-  config: { api_path: 'myApiPath', http_method: 'POST' },
+  function_id: 'orders.create',
+  config: { api_path: '/orders', http_method: 'POST' },
 })
 ```
 
-### Registering Trigger Types
-
-Triggers are mostly created by III Core Modules, but you can also create your own triggers
+### Invoking Functions
 
 ```javascript
-iii.registerTrigger_type(
-  {
-    /**
-     * This is the id of the trigger type, it's unique.
-     * Then, you can register a trigger by calling the registerTrigger method.
-     */
-    id: 'myTrigger_type',
-    description: 'My trigger type',
-  },
-  {
-    /**
-     * Trigger config has: id, function_id, and config.
-     * Your logic should know what to do with the config.
-     */
-    registerTrigger: async (config) => {
-      // ... do something
-    },
-    unregisterTrigger: async (config) => {
-      // ... do something
-    },
-  },
-)
-```
+const result = await iii.trigger('orders.create', { item: 'widget' })
 
-### Invoking Functions
+iii.triggerVoid('analytics.track', { event: 'page_view' })
+```
 
-III Allows you to invoke functions, they can be functions from the Core Modules or
-functions registered by workers.
+## Node Modules
 
-```javascript
-const result = await iii.call('myFunction', { param1: 'value1' })
-console.log(result)
-```
+| Import              | What it provides                      |
+| ------------------- | ------------------------------------- |
+| `iii-sdk`           | Core SDK (`init`, types)              |
+| `iii-sdk/stream`    | Stream client for real-time state     |
+| `iii-sdk/state`     | State client for key-value operations |
+| `iii-sdk/telemetry` | OpenTelemetry integration             |
 
-### Invoking Functions Async
+## Deprecated
 
-III Allows you to invoke functions asynchronously, they can be functions from the Core Modules or functions registered by workers.
+`call()` and `callVoid()` are deprecated aliases for `trigger()` and `triggerVoid()`. They still work but will be removed in a future release.
 
-```javascript
-iii.callVoid('myFunction', { param1: 'value1' })
-```
+## Resources
 
-This means the Engine won't hold the execution of the function, it will return immediately. Which means the function will be executed in the background.
+- [Documentation](https://iii.dev/docs)
+- [iii Engine](https://github.com/iii-hq/iii)
+- [Examples](https://github.com/iii-hq/iii-examples)

package/dist/index.cjs

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_otel_worker_gauges = require('./otel-worker-gauges-wK5b_eLY.cjs');
+const require_utils = require('./utils-DYxVY7fy.cjs');
 let __opentelemetry_api = require("@opentelemetry/api");
 let node_module = require("node:module");
 let node_os = require("node:os");
@@ -189,7 +189,7 @@ let MessageType = /* @__PURE__ */ function(MessageType$1) {
 //#region src/logger.ts
 var Logger = class {
 	get otelLogger() {
-		if (!this._otelLogger) this._otelLogger = require_otel_worker_gauges.getLogger();
+		if (!this._otelLogger) this._otelLogger = require_utils.getLogger();
 		return this._otelLogger;
 	}
 	constructor(traceId, serviceName, spanId) {
@@ -203,7 +203,7 @@ var Logger = class {
 		if (this.traceId) attributes.trace_id = this.traceId;
 		if (this.spanId) attributes.span_id = this.spanId;
 		if (this.serviceName) attributes["service.name"] = this.serviceName;
-		if (data !== void 0) attributes["log.data"] = typeof data === "string" ? data : require_otel_worker_gauges.safeStringify(data);
+		if (data !== void 0) attributes["log.data"] = data;
 		if (this.otelLogger) this.otelLogger.emit({
 			severityNumber: severity,
 			body: message,
@@ -268,7 +268,6 @@ var Sdk = class {
 		this.address = address;
 		this.options = options;
 		this.functions = /* @__PURE__ */ new Map();
-		this.httpFunctions = /* @__PURE__ */ new Map();
 		this.services = /* @__PURE__ */ new Map();
 		this.invocations = /* @__PURE__ */ new Map();
 		this.triggers = /* @__PURE__ */ new Map();
@@ -315,59 +314,50 @@ var Sdk = class {
 				this.triggers.delete(id);
 			} };
 		};
-		this.registerFunction = (message, handler) => {
+		this.registerFunction = (message, handlerOrInvocation) => {
 			if (!message.id || message.id.trim() === "") throw new Error("id is required");
-			if (this.httpFunctions.has(message.id)) throw new Error(`function id already registered: ${message.id}`);
-			this.sendMessage(MessageType.RegisterFunction, message, true);
-			this.functions.set(message.id, {
-				message: {
-					...message,
-					message_type: MessageType.RegisterFunction
-				},
-				handler: async (input, traceparent, baggage) => {
-					if (require_otel_worker_gauges.getTracer()) {
-						const parentContext = require_otel_worker_gauges.extractContext(traceparent, baggage);
-						return __opentelemetry_api.context.with(parentContext, () => require_otel_worker_gauges.withSpan(`call ${message.id}`, { kind: __opentelemetry_api.SpanKind.SERVER }, async (span) => {
-							const traceId = require_otel_worker_gauges.currentTraceId() ?? crypto.randomUUID();
-							const spanId = require_otel_worker_gauges.currentSpanId();
-							return withContext(async () => await handler(input), {
-								logger: new Logger(traceId, message.id, spanId),
-								trace: span
-							});
-						}));
-					}
-					return withContext(async () => await handler(input), { logger: new Logger(crypto.randomUUID(), message.id) });
-				}
-			});
-			return {
-				id: message.id,
-				unregister: () => {
-					this.sendMessage(MessageType.UnregisterFunction, { id: message.id }, true);
-					this.functions.delete(message.id);
-				}
-			};
-		};
-		this.registerHttpFunction = (id, config) => {
-			if (!id || id.trim() === "") throw new Error("id is required");
-			if (this.functions.has(id) || this.httpFunctions.has(id)) throw new Error(`function id already registered: ${id}`);
-			const message = {
+			if (this.functions.has(message.id)) throw new Error(`function id already registered: ${message.id}`);
+			const isHandler = typeof handlerOrInvocation === "function";
+			const fullMessage = isHandler ? {
+				...message,
+				message_type: MessageType.RegisterFunction
+			} : {
+				...message,
 				message_type: MessageType.RegisterFunction,
-				id,
 				invocation: {
-					url: config.url,
-					method: config.method ?? "POST",
-					timeout_ms: config.timeout_ms,
-					headers: config.headers,
-					auth: config.auth
+					url: handlerOrInvocation.url,
+					method: handlerOrInvocation.method ?? "POST",
+					timeout_ms: handlerOrInvocation.timeout_ms,
+					headers: handlerOrInvocation.headers,
+					auth: handlerOrInvocation.auth
 				}
 			};
-			this.sendMessage(MessageType.RegisterFunction, message, true);
-			this.httpFunctions.set(id, message);
+			this.sendMessage(MessageType.RegisterFunction, fullMessage, true);
+			if (isHandler) {
+				const handler = handlerOrInvocation;
+				this.functions.set(message.id, {
+					message: fullMessage,
+					handler: async (input, traceparent, baggage) => {
+						if (require_utils.getTracer()) {
+							const parentContext = require_utils.extractContext(traceparent, baggage);
+							return __opentelemetry_api.context.with(parentContext, () => require_utils.withSpan(`call ${message.id}`, { kind: __opentelemetry_api.SpanKind.SERVER }, async (span) => {
+								const traceId = require_utils.currentTraceId() ?? crypto.randomUUID();
+								const spanId = require_utils.currentSpanId();
+								return withContext(async () => await handler(input), {
+									logger: new Logger(traceId, message.id, spanId),
+									trace: span
+								});
+							}));
+						}
+						return withContext(async () => await handler(input), { logger: new Logger(crypto.randomUUID(), message.id) });
+					}
+				});
+			} else this.functions.set(message.id, { message: fullMessage });
 			return {
-				id,
+				id: message.id,
 				unregister: () => {
-					this.sendMessage(MessageType.UnregisterFunction, { id }, true);
-					this.httpFunctions.delete(id);
+					this.sendMessage(MessageType.UnregisterFunction, { id: message.id }, true);
+					this.functions.delete(message.id);
 				}
 			};
 		};
@@ -389,8 +379,8 @@ var Sdk = class {
 		};
 		this.trigger = async (function_id, data, timeoutMs) => {
 			const invocation_id = crypto.randomUUID();
-			const traceparent = require_otel_worker_gauges.injectTraceparent();
-			const baggage = require_otel_worker_gauges.injectBaggage();
+			const traceparent = require_utils.injectTraceparent();
+			const baggage = require_utils.injectBaggage();
 			const effectiveTimeout = timeoutMs ?? this.invocationTimeoutMs;
 			return new Promise((resolve, reject) => {
 				const timeout = setTimeout(() => {
@@ -420,8 +410,8 @@ var Sdk = class {
 			});
 		};
 		this.triggerVoid = (function_id, data) => {
-			const traceparent = require_otel_worker_gauges.injectTraceparent();
-			const baggage = require_otel_worker_gauges.injectBaggage();
+			const traceparent = require_utils.injectTraceparent();
+			const baggage = require_utils.injectBaggage();
 			this.sendMessage(MessageType.InvokeFunction, {
 				function_id,
 				data,
@@ -432,10 +422,10 @@ var Sdk = class {
 		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_otel_worker_gauges.EngineFunctions.LIST_FUNCTIONS, {})).functions;
+			return (await this.trigger(require_utils.EngineFunctions.LIST_FUNCTIONS, {})).functions;
 		};
 		this.listWorkers = async () => {
-			return (await this.trigger(require_otel_worker_gauges.EngineFunctions.LIST_WORKERS, {})).workers;
+			return (await this.trigger(require_utils.EngineFunctions.LIST_WORKERS, {})).workers;
 		};
 		this.createStream = (streamName, stream) => {
 			this.registerFunction({ id: `stream::get(${streamName})` }, stream.get.bind(stream));
@@ -456,7 +446,7 @@ var Sdk = class {
 					return null;
 				});
 				this.functionsAvailableTrigger = this.registerTrigger({
-					type: require_otel_worker_gauges.EngineTriggers.FUNCTIONS_AVAILABLE,
+					type: require_utils.EngineTriggers.FUNCTIONS_AVAILABLE,
 					function_id,
 					config: {}
 				});
@@ -487,7 +477,7 @@ var Sdk = class {
 					return null;
 				});
 				this.logTrigger = this.registerTrigger({
-					type: require_otel_worker_gauges.EngineTriggers.LOG,
+					type: require_utils.EngineTriggers.LOG,
 					function_id,
 					config: {
 						level: "all",
@@ -514,7 +504,7 @@ var Sdk = class {
 		this.shutdown = async () => {
 			this.isShuttingDown = true;
 			this.stopMetricsReporting();
-			await require_otel_worker_gauges.shutdownOtel();
+			await require_utils.shutdownOtel();
 			this.clearReconnectTimeout();
 			for (const [_id, invocation] of this.invocations) {
 				if (invocation.timeout) clearTimeout(invocation.timeout);
@@ -531,12 +521,12 @@ var Sdk = class {
 		};
 		this.workerName = options?.workerName ?? getDefaultWorkerName();
 		this.metricsReportingEnabled = options?.enableMetricsReporting ?? true;
-		this.invocationTimeoutMs = options?.invocationTimeoutMs ?? require_otel_worker_gauges.DEFAULT_INVOCATION_TIMEOUT_MS;
+		this.invocationTimeoutMs = options?.invocationTimeoutMs ?? require_utils.DEFAULT_INVOCATION_TIMEOUT_MS;
 		this.reconnectionConfig = {
-			...require_otel_worker_gauges.DEFAULT_BRIDGE_RECONNECTION_CONFIG,
+			...require_utils.DEFAULT_BRIDGE_RECONNECTION_CONFIG,
 			...options?.reconnectionConfig
 		};
-		require_otel_worker_gauges.initOtel({
+		require_utils.initOtel({
 			...options?.otel,
 			engineWsUrl: this.address
 		});
@@ -545,7 +535,7 @@ 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_otel_worker_gauges.EngineFunctions.REGISTER_WORKER, {
+		this.triggerVoid(require_utils.EngineFunctions.REGISTER_WORKER, {
 			runtime: "node",
 			version: SDK_VERSION,
 			name: this.workerName,
@@ -608,18 +598,18 @@ var Sdk = class {
 	}
 	startMetricsReporting() {
 		if (!this.metricsReportingEnabled || !this.workerId) return;
-		const meter = require_otel_worker_gauges.getMeter();
+		const meter = require_utils.getMeter();
 		if (!meter) {
 			console.warn("[iii] Worker metrics disabled: OpenTelemetry not initialized. Call initOtel() with metricsEnabled: true before creating the iii.");
 			return;
 		}
-		require_otel_worker_gauges.registerWorkerGauges(meter, {
+		require_utils.registerWorkerGauges(meter, {
 			workerId: this.workerId,
 			workerName: this.workerName
 		});
 	}
 	stopMetricsReporting() {
-		require_otel_worker_gauges.stopWorkerGauges();
+		require_utils.stopWorkerGauges();
 	}
 	onSocketClose() {
 		this.ws?.removeAllListeners();
@@ -643,9 +633,6 @@ var Sdk = class {
 		this.functions.forEach(({ message }) => {
 			this.sendMessage(MessageType.RegisterFunction, message, true);
 		});
-		this.httpFunctions.forEach((message) => {
-			this.sendMessage(MessageType.RegisterFunction, message, true);
-		});
 		this.triggers.forEach((trigger) => {
 			this.sendMessage(MessageType.RegisterTrigger, trigger, true);
 		});
@@ -706,7 +693,7 @@ var Sdk = class {
 		else if (!skipIfClosed) this.messagesToSend.push(wireMessage);
 	}
 	logError(message, error) {
-		const otelLogger = require_otel_worker_gauges.getLogger();
+		const otelLogger = require_utils.getLogger();
 		const errorMessage = error instanceof Error ? error.message : String(error ?? "");
 		if (otelLogger) otelLogger.emit({
 			severityNumber: __opentelemetry_api_logs.SeverityNumber.ERROR,
@@ -735,7 +722,7 @@ var Sdk = class {
 		this.invocations.delete(invocation_id);
 	}
 	resolveChannelValue(value) {
-		if (require_otel_worker_gauges.isChannelRef(value)) return value.direction === "read" ? new ChannelReader(this.address, value) : new ChannelWriter(this.address, value);
+		if (require_utils.isChannelRef(value)) return value.direction === "read" ? new ChannelReader(this.address, value) : new ChannelWriter(this.address, value);
 		if (Array.isArray(value)) return value.map((item) => this.resolveChannelValue(item));
 		if (value !== null && typeof value === "object") {
 			const out = {};
@@ -746,10 +733,10 @@ var Sdk = class {
 	}
 	async onInvokeFunction(invocation_id, function_id, input, traceparent, baggage) {
 		const fn = this.functions.get(function_id);
-		const getResponseTraceparent = () => require_otel_worker_gauges.injectTraceparent() ?? traceparent;
-		const getResponseBaggage = () => require_otel_worker_gauges.injectBaggage() ?? baggage;
+		const getResponseTraceparent = () => require_utils.injectTraceparent() ?? traceparent;
+		const getResponseBaggage = () => require_utils.injectBaggage() ?? baggage;
 		const resolvedInput = this.resolveChannelValue(input);
-		if (fn) {
+		if (fn?.handler) {
 			if (!invocation_id) {
 				try {
 					await fn.handler(resolvedInput, traceparent, baggage);
@@ -779,16 +766,20 @@ var Sdk = class {
 					baggage: getResponseBaggage()
 				});
 			}
-		} else this.sendMessage(MessageType.InvocationResult, {
-			invocation_id,
-			function_id,
-			error: {
-				code: "function_not_found",
-				message: "Function not found"
-			},
-			traceparent,
-			baggage
-		});
+		} else {
+			const errorCode = fn ? "function_not_invokable" : "function_not_found";
+			const errorMessage = fn ? "Function is HTTP-invoked and cannot be invoked locally" : "Function not found";
+			if (invocation_id) this.sendMessage(MessageType.InvocationResult, {
+				invocation_id,
+				function_id,
+				error: {
+					code: errorCode,
+					message: errorMessage
+				},
+				traceparent,
+				baggage
+			});
+		}
 	}
 	async onRegisterTrigger(message) {
 		const { trigger_type, id, function_id, config } = message;
@@ -863,7 +854,7 @@ exports.ChannelWriter = ChannelWriter;
 exports.Logger = Logger;
 exports.__toESM = __toESM;
 exports.getContext = getContext;
-exports.http = require_otel_worker_gauges.http;
+exports.http = require_utils.http;
 exports.init = init;
 exports.withContext = withContext;
 //# sourceMappingURL=index.cjs.map