@revenexx/integrations-node-sdk 0.12.0 → 0.12.1

package/README.md

@@ -42,38 +42,180 @@ ESM/CJS output plus `.d.ts` types.
 
 ### Authoring a node
 
-Implement `INode`: a static `description` plus an `execute` method. Single-input
-nodes read the conventional `'in'` port.
+Implement `INode`: an instance `description` property (the metadata the registry
+publishes) plus an `execute` method. A few conventions the engine relies on:
+
+- **`slug` is namespaced** — `<namespace>:<slug>`, e.g. `revenexx:text-replace`.
+  It is the stable identity of the node across versions; not a dotted path.
+- **Every output port carries a `name`.** `execute` returns an `outputs` map
+  keyed by that port `name`, and sets `branch` to the port that fired. The key,
+  the `branch` and the declared `name` must match — that triple is how the
+  engine routes the result to the next node.
+- **Config and inputs arrive in the same map.** The engine resolves each
+  declared `config` field (keyed by its `key`) and the input ports (`'in'`, plus
+  any named fan-in ports) into the single `inputs: Record<string, unknown>`
+  handed to `execute`. So `inputs['in']` is the upstream payload and
+  `inputs['<config-key>']` is the resolved config value.
+- **`ctx.signal` is always provided** — propagate it to every I/O call.
+
+#### Transform node — single input, single output
+
+A `transform` node with one `'in'` port and one named `out` port. Mirrors
+`TextReplaceNode` from `integrations-nodes-core`:
 
 ```ts
-import type { INode, INodeContext } from '@revenexx/integrations-node-sdk';
+import type { INode, INodeContext, INodeDescription, INodeResult } from '@revenexx/integrations-node-sdk';
 import { NodeError } from '@revenexx/integrations-node-sdk';
 
 export class UppercaseNode implements INode {
-  description: INode['description'] = {
-    slug: 'text.uppercase',
+  description = {
+    slug: 'revenexx:text-uppercase',
     version: '1.0.0',
     category: 'transform',
-    name: 'Uppercase',
+    name: { en: 'Uppercase', de: 'Großschreiben' },
+    description: { en: 'Upper-cases a string read from the input.' },
+    icon: 'mdi:format-letter-case-upper',
     inputs: { in: { dataType: 'string', required: true } },
-    outputs: [{ kind: 'default', dataType: 'string' }],
-  };
+    outputs: [{ name: 'out', kind: 'default', dataType: 'string', label: { en: 'Result', de: 'Ergebnis' } }],
+  } satisfies INodeDescription;
 
-  async execute(ctx: INodeContext, inputs: Record<string, unknown>) {
+  async execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult> {
     ctx.signal.throwIfAborted();
     const value = inputs['in'];
     if (typeof value !== 'string') {
-      throw new NodeError('expected a string on the `in` port');
+      // NodeError(code, message, meta?) — a stable code plus a human message.
+      throw new NodeError('INVALID_INPUT', 'expected a string on the `in` port');
     }
-    return { outputs: { out: value.toUpperCase() } };
+    return { outputs: { out: value.toUpperCase() }, branch: 'out' };
   }
 }
 ```
 
-**Error contract:** `throw NodeError` for unexpected failures;
-`return { outputs, branch: '<error-port>' }` for expected, routable errors.
-Never mix both for the same condition. The engine always provides
-`ctx.signal` — propagate it to all I/O.
+#### Control node — branch outputs
+
+A `control` node declares `kind: 'branch'` ports and routes by returning the
+matching `branch`. Condensed from `ConditionIfNode`:
+
+```ts
+export class ConditionIfNode implements INode {
+  description = {
+    slug: 'revenexx:condition-if',
+    version: '1.0.0',
+    category: 'control',
+    name: { en: 'If condition', de: 'Wenn-Bedingung' },
+    icon: 'mdi:source-branch',
+    inputs: { in: { dataType: 'any', required: true } },
+    outputs: [
+      { name: 'true', kind: 'branch', dataType: 'any', label: { en: 'True', de: 'Wahr' } },
+      { name: 'false', kind: 'branch', dataType: 'any', label: { en: 'False', de: 'Falsch' } },
+    ],
+    config: [
+      { key: 'field', label: { en: 'Field (dot-path)' }, type: 'string', required: true },
+      { key: 'value', label: { en: 'Value' }, type: 'string', expressionAllowed: true },
+    ],
+  } satisfies INodeDescription;
+
+  async execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult> {
+    const inputData = inputs['in'];
+    const field = inputs['field'];
+    // `field` is a dot-path selector — resolve it against the input payload,
+    // then compare the resolved value to the configured `value`.
+    const actual =
+      typeof field === 'string'
+        ? field
+            .split('.')
+            .reduce<unknown>(
+              (acc, key) => (acc == null ? undefined : (acc as Record<string, unknown>)[key]),
+              inputData,
+            )
+        : undefined;
+    const branch = actual === inputs['value'] ? 'true' : 'false';
+    // The fired port's name is both the outputs key and the branch.
+    return { outputs: { [branch]: inputData }, branch };
+  }
+}
+```
+
+#### Action node — error output & credentials
+
+An `action` node declares a `kind: 'error'` port for expected, routable
+failures and reads a credential instance via a `credentials-ref` config field.
+Condensed from `HttpRequestNode`:
+
+```ts
+export class HttpRequestNode implements INode {
+  description = {
+    slug: 'revenexx:http-request',
+    version: '1.0.0',
+    category: 'action',
+    name: { en: 'HTTP Request', de: 'HTTP-Anfrage' },
+    icon: 'mdi:web',
+    inputs: { in: { dataType: 'object' } },
+    outputs: [
+      {
+        name: 'response',
+        kind: 'default',
+        dataType: 'object',
+        label: { en: 'Response', de: 'Antwort' },
+        fields: { status: { dataType: 'number' }, body: { dataType: 'any' } },
+      },
+      {
+        name: 'error',
+        kind: 'error',
+        dataType: 'object',
+        label: { en: 'Error', de: 'Fehler' },
+        fields: { code: { dataType: 'string' }, message: { dataType: 'string' } },
+      },
+    ],
+    config: [
+      { key: 'url', label: 'URL', type: 'string', required: true, expressionAllowed: true },
+      {
+        key: 'credentials',
+        label: { en: 'Credentials', de: 'Anmeldedaten' },
+        type: 'credentials-ref',
+        credentialType: 'revenexx:http-bearer',
+      },
+    ],
+  } satisfies INodeDescription;
+
+  async execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult> {
+    const url = inputs['url'];
+    if (typeof url !== 'string' || !url) {
+      throw new NodeError('MISSING_URL', 'URL config field is required');
+    }
+
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    const credentialsRef = inputs['credentials'];
+    if (typeof credentialsRef === 'string') {
+      const creds = await ctx.credentials.get(credentialsRef);
+      if (typeof creds['token'] === 'string') headers['Authorization'] = `Bearer ${creds['token']}`;
+    }
+
+    try {
+      const res = await fetch(url, { headers, signal: ctx.signal }); // always propagate ctx.signal
+      const body = await res.json();
+      if (!res.ok) {
+        return {
+          outputs: { error: { code: 'HTTP_ERROR', message: `${url} → ${res.status}` } },
+          branch: 'error',
+        };
+      }
+      return { outputs: { response: { status: res.status, body } }, branch: 'response' };
+    } catch (err) {
+      if (err instanceof NodeError) throw err;
+      // Don't swallow cancellations/timeouts — let aborts propagate so the
+      // workflow can cancel promptly instead of routing to the error port.
+      if (ctx.signal.aborted || (err instanceof Error && err.name === 'AbortError')) throw err;
+      return { outputs: { error: { code: 'REQUEST_FAILED', message: String(err) } }, branch: 'error' };
+    }
+  }
+}
+```
+
+**Error contract:** `throw NodeError(code, message, meta?)` for unexpected,
+system-level failures; `return { outputs, branch: '<error-port>' }` for
+expected, routable errors (a declared `kind: 'error'` port). Never mix both for
+the same condition.
 
 ### Building a manifest
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenexx/integrations-node-sdk",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "TypeScript interfaces and utilities for Revenexx integration nodes",
   "license": "MIT",
   "author": "revenexx GmbH",