@revenexx/integrations-node-sdk 1.10.0 → 1.11.0

package/dist/branches.d.ts

@@ -0,0 +1,47 @@
+import type { INode, INodeDescription, INodeResult, IOutputPort } from './types.js';
+/**
+ * A node's output ports are alternatives: exactly one fires. A node with a
+ * single port has nothing to choose between, so its result may leave `branch`
+ * out; a node with several must say which one it took, because the worker
+ * otherwise activates every outgoing connection (PO-751).
+ *
+ * A node counts as multi-port when EITHER holds:
+ *  - more than one port is declared (an `error` port counts: `out` + `error` is two);
+ *  - a port is marked `resolveOutputs`, because that set is only known while the
+ *    author edits and may hold several.
+ *
+ * A single port is one way out however it is declared — of kind `branch`, or named
+ * from a setting by `sourceFromConfig` (one name, with its `fallback`).
+ */
+export declare function isMultiPort(outputs: readonly IOutputPort[] | undefined): boolean;
+/** A result that names its branch — what every multi-port node returns. */
+export interface IBranchedNodeResult extends INodeResult {
+    branch: string;
+}
+/**
+ * Declaration problems of a node's output ports that the manifest build can see.
+ * Returns one sentence per problem, empty when there is none.
+ *
+ * A node with several ports must give each fixed port a unique `name`, since `branch`
+ * names one of them, and a generated port's `fallback` name must not repeat a fixed
+ * one. (Whether `execute` really returns a `branch` cannot be read from a declaration
+ * — see {@link assertBranchNamed}.)
+ */
+export declare function outputProblems(description: INodeDescription): string[];
+/**
+ * The warnings `rvnxx-nodes manifest` prints for a package's nodes: every
+ * {@link outputProblems} finding, worded for the log. In 1.x they are warnings and the
+ * build continues; the next major turns them into errors.
+ */
+export declare function outputWarnings(nodes: readonly INode[]): string[];
+/**
+ * Check a result against the node's declaration. For a node's own tests:
+ * `assertBranchNamed(node, await node.execute(ctx, inputs), config)`.
+ *
+ * Throws when a multi-port node returned no `branch`, and when the branch is none of
+ * the names the node can produce: a fixed name is always accepted; beyond that, a
+ * `resolveOutputs` port accepts any name (it is unknown here), and a `sourceFromConfig`
+ * port accepts its fallback name and — when `config` is passed — the value it holds
+ * (with no `config`, any name). A single-port node may leave `branch` out.
+ */
+export declare function assertBranchNamed(node: INode | INodeDescription, result: INodeResult, config?: Record<string, unknown>): void;

package/dist/chunk-XO73F62E.js

@@ -0,0 +1,122 @@
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+function assertBranchNamed(node, result, config) {
+  const description = "execute" in node ? node.description : node;
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return;
+  const branch = result.branch;
+  if (typeof branch !== "string" || branch === "") {
+    throw new Error(
+      `${description.slug} has several outputs, so its result must name the branch it took; without it every output fires.`
+    );
+  }
+  if (outputs.some((p) => !isGenerated(p) && p.name === branch)) return;
+  const producible = outputs.some((p) => {
+    if (p.resolveOutputs === true) return true;
+    if (p.sourceFromConfig === void 0) return false;
+    if (p.fallback?.name === branch) return true;
+    return config === void 0 || config[p.sourceFromConfig] === branch;
+  });
+  if (!producible) {
+    const names = outputs.map((p) => p.name ?? p.fallback?.name).filter((n) => n);
+    throw new Error(
+      `${description.slug} returned branch "${branch}", which none of its outputs can produce (${names.join(", ")}).`
+    );
+  }
+}
+
+// src/extract.ts
+function extractManifest(node) {
+  return node.description;
+}
+function extractManifests(nodes) {
+  return nodes.map(extractManifest);
+}
+function extractCredentialManifest(credential) {
+  return credential.description;
+}
+function extractCredentialManifests(credentials) {
+  return credentials.map(extractCredentialManifest);
+}
+
+// src/manifest.ts
+var MANIFEST_VERSION = "v0-draft";
+var PACKAGE_ICON = /^lucide:[a-z0-9]+(-[a-z0-9]+)*$/;
+var PHP_TRIM = /^[ \t\n\r\0\v]+|[ \t\n\r\0\v]+$/g;
+function packageIconProblem(icon) {
+  if (icon === void 0 || PACKAGE_ICON.test(icon)) return void 0;
+  return `package.json "revenexx.icon" must be a Lucide icon name such as "lucide:bell", got "${icon}".`;
+}
+function parsePackageMeta(raw) {
+  const obj = raw && typeof raw === "object" ? raw : {};
+  const str = (v) => typeof v === "string" ? v.trim() : "";
+  const revenexx = obj.revenexx && typeof obj.revenexx === "object" ? obj.revenexx : {};
+  const displayName = str(revenexx.displayName);
+  const icon = typeof revenexx.icon === "string" ? revenexx.icon.replace(PHP_TRIM, "") : "";
+  return {
+    name: str(obj.name),
+    version: str(obj.version),
+    displayName: displayName !== "" ? displayName : void 0,
+    icon: icon !== "" ? icon : void 0
+  };
+}
+function buildManifest(nodes, credentials = [], templates = []) {
+  const manifest = {
+    manifestVersion: MANIFEST_VERSION,
+    nodes: extractManifests(nodes)
+  };
+  if (credentials.length > 0) {
+    manifest.credentials = extractCredentialManifests(credentials);
+  }
+  if (templates.length > 0) {
+    manifest.templates = templates;
+  }
+  return manifest;
+}
+
+export {
+  isMultiPort,
+  outputProblems,
+  outputWarnings,
+  assertBranchNamed,
+  extractManifest,
+  extractManifests,
+  extractCredentialManifest,
+  extractCredentialManifests,
+  MANIFEST_VERSION,
+  packageIconProblem,
+  parsePackageMeta,
+  buildManifest
+};

package/dist/cli.cjs

@@ -28,6 +28,41 @@ var fs2 = __toESM(require("fs"), 1);
 var import_node_path2 = require("path");
 var import_node_url = require("url");
 
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+
 // src/images.ts
 var fs = __toESM(require("fs"), 1);
 var import_node_path = require("path");
@@ -174,6 +209,9 @@ async function runManifest() {
       '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
     );
   }
+  for (const w of outputWarnings(mod.NODES)) {
+    console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
   const outDir = (0, import_node_path2.resolve)(projectRoot, "dist");
   const outFile = (0, import_node_path2.resolve)(outDir, "manifest.json");

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import {
   buildManifest,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-5BCAXRU3.js";
+} from "./chunk-XO73F62E.js";
 
 // src/cli.ts
 import * as fs2 from "fs";
@@ -107,6 +108,9 @@ async function runManifest() {
       '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
     );
   }
+  for (const w of outputWarnings(mod.NODES)) {
+    console.warn(`\u26A0 ${w} This will be an error in the next major version.`);
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
   const outDir = resolve2(projectRoot, "dist");
   const outFile = resolve2(outDir, "manifest.json");

package/dist/index.cjs

@@ -50,6 +50,7 @@ __export(index_exports, {
   RetryableError: () => RetryableError,
   SimpleValueCredential: () => SimpleValueCredential,
   VALUELESS_OPERATORS: () => VALUELESS_OPERATORS,
+  assertBranchNamed: () => assertBranchNamed,
   assertPublicUrl: () => assertPublicUrl,
   backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
@@ -64,12 +65,15 @@ __export(index_exports, {
   headerCrossesOrigin: () => headerCrossesOrigin,
   httpErrorResult: () => httpErrorResult,
   isBlockedAddress: () => isBlockedAddress,
+  isMultiPort: () => isMultiPort,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
   isOperator: () => isOperator,
   maxBytesConfigField: () => maxBytesConfigField,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
+  outputProblems: () => outputProblems,
+  outputWarnings: () => outputWarnings,
   packageIconProblem: () => packageIconProblem,
   parsePackageMeta: () => parsePackageMeta,
   readArrayBuffer: () => readArrayBuffer,
@@ -294,6 +298,65 @@ function extractCredentialManifests(credentials) {
   return credentials.map(extractCredentialManifest);
 }
 
+// src/branches.ts
+function isMultiPort(outputs) {
+  if (!outputs) return false;
+  return outputs.length > 1 || outputs.some((p) => p.resolveOutputs === true);
+}
+var isGenerated = (p) => p.sourceFromConfig !== void 0 || p.resolveOutputs === true;
+function outputProblems(description) {
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return [];
+  const problems = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [i, port] of outputs.entries()) {
+    if (isGenerated(port)) continue;
+    if (port.name === void 0 || port.name === "") {
+      problems.push(
+        `${description.slug}: output ${i + 1} has no name, so a branch cannot choose it \u2014 a node with several outputs must name each one.`
+      );
+    } else if (seen.has(port.name)) {
+      problems.push(`${description.slug}: output name "${port.name}" is declared twice.`);
+    } else {
+      seen.add(port.name);
+    }
+  }
+  for (const port of outputs) {
+    const fb = port.fallback?.name;
+    if (isGenerated(port) && fb !== void 0 && seen.has(fb)) {
+      problems.push(`${description.slug}: the fallback name "${fb}" is also the name of a fixed output, so a branch "${fb}" is ambiguous.`);
+    }
+  }
+  return problems;
+}
+function outputWarnings(nodes) {
+  return nodes.flatMap((n) => outputProblems(n.description));
+}
+function assertBranchNamed(node, result, config) {
+  const description = "execute" in node ? node.description : node;
+  const outputs = description.outputs ?? [];
+  if (!isMultiPort(outputs)) return;
+  const branch = result.branch;
+  if (typeof branch !== "string" || branch === "") {
+    throw new Error(
+      `${description.slug} has several outputs, so its result must name the branch it took; without it every output fires.`
+    );
+  }
+  if (outputs.some((p) => !isGenerated(p) && p.name === branch)) return;
+  const producible = outputs.some((p) => {
+    if (p.resolveOutputs === true) return true;
+    if (p.sourceFromConfig === void 0) return false;
+    if (p.fallback?.name === branch) return true;
+    return config === void 0 || config[p.sourceFromConfig] === branch;
+  });
+  if (!producible) {
+    const names = outputs.map((p) => p.name ?? p.fallback?.name).filter((n) => n);
+    throw new Error(
+      `${description.slug} returned branch "${branch}", which none of its outputs can produce (${names.join(", ")}).`
+    );
+  }
+}
+
 // src/ssrf.ts
 var import_node_diagnostics_channel = require("diagnostics_channel");
 var import_node_net = require("net");
@@ -1235,6 +1298,7 @@ function base64Url(buf) {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
@@ -1249,12 +1313,15 @@ function base64Url(buf) {
   headerCrossesOrigin,
   httpErrorResult,
   isBlockedAddress,
+  isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta,
   readArrayBuffer,

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './credentialType.js';
 export * from './errors.js';
 export * from './nodeErrors.js';
 export * from './extract.js';
+export * from './branches.js';
 export * from './fetch.js';
 export { assertPublicUrl, isBlockedAddress } from './ssrf.js';
 export type { LookupAddress, LookupFn } from './ssrf.js';

package/dist/index.js

@@ -1,13 +1,17 @@
 import {
   MANIFEST_VERSION,
+  assertBranchNamed,
   buildManifest,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  isMultiPort,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta
-} from "./chunk-5BCAXRU3.js";
+} from "./chunk-XO73F62E.js";
 
 // src/types.ts
 function isNodeWithIteration(node) {
@@ -1107,6 +1111,7 @@ export {
   RetryableError,
   SimpleValueCredential,
   VALUELESS_OPERATORS,
+  assertBranchNamed,
   assertPublicUrl,
   backoffDelay,
   buildManifest,
@@ -1121,12 +1126,15 @@ export {
   headerCrossesOrigin,
   httpErrorResult,
   isBlockedAddress,
+  isMultiPort,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
   isOperator,
   maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
+  outputProblems,
+  outputWarnings,
   packageIconProblem,
   parsePackageMeta,
   readArrayBuffer,

package/dist/types.d.ts

@@ -368,6 +368,14 @@ export interface INodeState {
 }
 export interface INodeResult {
     outputs: Record<string, unknown>;
+    /**
+     * The output port the node took. Output ports are alternatives — exactly one
+     * fires — so a node with more than one output (an `error` port counts) must
+     * name it; only a node with a single output may omit it. The worker fails such
+     * a step from the integrations release that carries PO-751; until then a result
+     * without `branch` fires every output. See `isMultiPort` for what counts as
+     * several, and `assertBranchNamed` to check a result in the node's own tests.
+     */
     branch?: string;
 }
 /**

package/package.json

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

package/dist/chunk-5BCAXRU3.js

@@ -1,59 +0,0 @@
-// src/extract.ts
-function extractManifest(node) {
-  return node.description;
-}
-function extractManifests(nodes) {
-  return nodes.map(extractManifest);
-}
-function extractCredentialManifest(credential) {
-  return credential.description;
-}
-function extractCredentialManifests(credentials) {
-  return credentials.map(extractCredentialManifest);
-}
-
-// src/manifest.ts
-var MANIFEST_VERSION = "v0-draft";
-var PACKAGE_ICON = /^lucide:[a-z0-9]+(-[a-z0-9]+)*$/;
-var PHP_TRIM = /^[ \t\n\r\0\v]+|[ \t\n\r\0\v]+$/g;
-function packageIconProblem(icon) {
-  if (icon === void 0 || PACKAGE_ICON.test(icon)) return void 0;
-  return `package.json "revenexx.icon" must be a Lucide icon name such as "lucide:bell", got "${icon}".`;
-}
-function parsePackageMeta(raw) {
-  const obj = raw && typeof raw === "object" ? raw : {};
-  const str = (v) => typeof v === "string" ? v.trim() : "";
-  const revenexx = obj.revenexx && typeof obj.revenexx === "object" ? obj.revenexx : {};
-  const displayName = str(revenexx.displayName);
-  const icon = typeof revenexx.icon === "string" ? revenexx.icon.replace(PHP_TRIM, "") : "";
-  return {
-    name: str(obj.name),
-    version: str(obj.version),
-    displayName: displayName !== "" ? displayName : void 0,
-    icon: icon !== "" ? icon : void 0
-  };
-}
-function buildManifest(nodes, credentials = [], templates = []) {
-  const manifest = {
-    manifestVersion: MANIFEST_VERSION,
-    nodes: extractManifests(nodes)
-  };
-  if (credentials.length > 0) {
-    manifest.credentials = extractCredentialManifests(credentials);
-  }
-  if (templates.length > 0) {
-    manifest.templates = templates;
-  }
-  return manifest;
-}
-
-export {
-  extractManifest,
-  extractManifests,
-  extractCredentialManifest,
-  extractCredentialManifests,
-  MANIFEST_VERSION,
-  packageIconProblem,
-  parsePackageMeta,
-  buildManifest
-};