@revenexx/integrations-node-sdk 0.12.1 → 0.14.0

package/README.md

@@ -11,7 +11,8 @@ packages and the workflow engine that runs them.
 ```
 integrations-node-sdk          ← this package (types & helpers only)
   └── integrations-nodes-core  ← implements INode, ships dist/manifest.json
-        └── integrations-worker ← registers nodes, executes workflows
+        └── integrations-worker ← reads the manifest, executes workflows
+                                   (no SDK dependency — couples via manifestVersion)
 ```
 
 ## Installation

package/dist/{chunk-X5HI7WPI.js → chunk-WB3BYMLA.js}

@@ -14,6 +14,17 @@ function extractCredentialManifests(credentials) {
 
 // src/manifest.ts
 var MANIFEST_VERSION = "v0-draft";
+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);
+  return {
+    name: str(obj.name),
+    version: str(obj.version),
+    displayName: displayName !== "" ? displayName : void 0
+  };
+}
 function buildManifest(nodes, credentials = [], templates = []) {
   const manifest = {
     manifestVersion: MANIFEST_VERSION,
@@ -34,5 +45,6 @@ export {
   extractCredentialManifest,
   extractCredentialManifests,
   MANIFEST_VERSION,
+  parsePackageMeta,
   buildManifest
 };

package/dist/cli.cjs

@@ -24,9 +24,58 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+var fs2 = __toESM(require("fs"), 1);
+var import_node_path2 = require("path");
+var import_node_url = require("url");
+
+// src/images.ts
 var fs = __toESM(require("fs"), 1);
 var import_node_path = require("path");
-var import_node_url = require("url");
+function collectImageSources(manifest) {
+  const sources = /* @__PURE__ */ new Set();
+  for (const group of [manifest.nodes, manifest.credentials, manifest.templates]) {
+    for (const item of group ?? []) {
+      for (const image of item.images ?? []) {
+        if (typeof image.src === "string" && image.src.length > 0) {
+          sources.add(image.src);
+        }
+      }
+    }
+  }
+  return [...sources];
+}
+function copyImages(sources, outDir, rootDir) {
+  let copied = 0;
+  for (const src of sources) {
+    if (!isSafeRelativePath(src)) {
+      console.warn(`  \u26A0 unsafe image path (absolute or escaping the package root), skipping: ${src}`);
+      continue;
+    }
+    const from = (0, import_node_path.resolve)(rootDir, src);
+    if (!fs.existsSync(from)) {
+      console.warn(`  \u26A0 image not found, skipping: ${src}`);
+      continue;
+    }
+    if (!fs.statSync(from).isFile()) {
+      console.warn(`  \u26A0 image path is not a file, skipping: ${src}`);
+      continue;
+    }
+    const to = (0, import_node_path.resolve)(outDir, src);
+    fs.mkdirSync((0, import_node_path.dirname)(to), { recursive: true });
+    fs.copyFileSync(from, to);
+    copied++;
+  }
+  if (sources.length > 0) {
+    console.log(`  copied ${copied}/${sources.length} image(s) into dist/`);
+  }
+}
+function isSafeRelativePath(src) {
+  if ((0, import_node_path.isAbsolute)(src)) {
+    return false;
+  }
+  const normalized = (0, import_node_path.normalize)(src);
+  return normalized !== ".." && !normalized.startsWith(".." + import_node_path.sep);
+}
 
 // src/extract.ts
 function extractManifest(node) {
@@ -44,6 +93,17 @@ function extractCredentialManifests(credentials) {
 
 // src/manifest.ts
 var MANIFEST_VERSION = "v0-draft";
+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);
+  return {
+    name: str(obj.name),
+    version: str(obj.version),
+    displayName: displayName !== "" ? displayName : void 0
+  };
+}
 function buildManifest(nodes, credentials = [], templates = []) {
   const manifest = {
     manifestVersion: MANIFEST_VERSION,
@@ -64,9 +124,20 @@ function fail(message) {
   console.error(`Error: ${message}`);
   process.exit(1);
 }
+function readPackageJson(root) {
+  const pkgPath = (0, import_node_path2.resolve)(root, "package.json");
+  if (!fs2.existsSync(pkgPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
 async function runManifest() {
-  const distEntry = (0, import_node_path.resolve)(projectRoot, "dist", "index.js");
-  if (!fs.existsSync(distEntry)) {
+  const distEntry = (0, import_node_path2.resolve)(projectRoot, "dist", "index.js");
+  if (!fs2.existsSync(distEntry)) {
     fail("dist/index.js is missing. Run the build (tsup) before `rvnxx-nodes manifest`.");
   }
   const mod = await import((0, import_node_url.pathToFileURL)(distEntry).href);
@@ -81,15 +152,23 @@ async function runManifest() {
   }
   const credentials = mod.CREDENTIALS ?? [];
   const templates = mod.TEMPLATES ?? [];
+  const meta = parsePackageMeta(readPackageJson(projectRoot));
+  const hasPackage = meta.name !== "" && meta.version !== "";
+  if (hasPackage && !meta.displayName) {
+    console.warn(
+      '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
+    );
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
-  const outDir = (0, import_node_path.resolve)(projectRoot, "dist");
-  const outFile = (0, import_node_path.resolve)(outDir, "manifest.json");
-  fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(outFile, JSON.stringify(manifest, null, 2), "utf-8");
+  const outDir = (0, import_node_path2.resolve)(projectRoot, "dist");
+  const outFile = (0, import_node_path2.resolve)(outDir, "manifest.json");
+  fs2.mkdirSync(outDir, { recursive: true });
+  fs2.writeFileSync(outFile, JSON.stringify(manifest, null, 2), "utf-8");
   const credentialCount = manifest.credentials?.length ?? 0;
   const templateCount = manifest.templates?.length ?? 0;
+  const bundlePrefix = hasPackage ? `package ${meta.displayName ? `"${meta.displayName}" ` : ""}(${meta.name}), ` : "";
   console.log(
-    `\u2713 dist/manifest.json \u2014 ${manifest.nodes.length} node(s), ${credentialCount} credential(s), ${templateCount} template(s)`
+    `\u2713 dist/manifest.json \u2014 ${bundlePrefix}${manifest.nodes.length} node(s), ${credentialCount} credential(s), ${templateCount} template(s)`
   );
   for (const m of manifest.nodes) {
     console.log(`  node       ${m.slug}@${m.version}`);
@@ -100,6 +179,7 @@ async function runManifest() {
   for (const t of manifest.templates ?? []) {
     console.log(`  template   ${t.slug}@${t.version} (${t.level})`);
   }
+  copyImages(collectImageSources(manifest), outDir, projectRoot);
 }
 async function main() {
   const command = process.argv[2];

package/dist/cli.js

@@ -1,20 +1,83 @@
 #!/usr/bin/env node
 import {
-  buildManifest
-} from "./chunk-X5HI7WPI.js";
+  buildManifest,
+  parsePackageMeta
+} from "./chunk-WB3BYMLA.js";
 
 // src/cli.ts
-import * as fs from "fs";
-import { resolve } from "path";
+import * as fs2 from "fs";
+import { resolve as resolve2 } from "path";
 import { pathToFileURL } from "url";
+
+// src/images.ts
+import * as fs from "fs";
+import { dirname, isAbsolute, normalize, resolve, sep } from "path";
+function collectImageSources(manifest) {
+  const sources = /* @__PURE__ */ new Set();
+  for (const group of [manifest.nodes, manifest.credentials, manifest.templates]) {
+    for (const item of group ?? []) {
+      for (const image of item.images ?? []) {
+        if (typeof image.src === "string" && image.src.length > 0) {
+          sources.add(image.src);
+        }
+      }
+    }
+  }
+  return [...sources];
+}
+function copyImages(sources, outDir, rootDir) {
+  let copied = 0;
+  for (const src of sources) {
+    if (!isSafeRelativePath(src)) {
+      console.warn(`  \u26A0 unsafe image path (absolute or escaping the package root), skipping: ${src}`);
+      continue;
+    }
+    const from = resolve(rootDir, src);
+    if (!fs.existsSync(from)) {
+      console.warn(`  \u26A0 image not found, skipping: ${src}`);
+      continue;
+    }
+    if (!fs.statSync(from).isFile()) {
+      console.warn(`  \u26A0 image path is not a file, skipping: ${src}`);
+      continue;
+    }
+    const to = resolve(outDir, src);
+    fs.mkdirSync(dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+    copied++;
+  }
+  if (sources.length > 0) {
+    console.log(`  copied ${copied}/${sources.length} image(s) into dist/`);
+  }
+}
+function isSafeRelativePath(src) {
+  if (isAbsolute(src)) {
+    return false;
+  }
+  const normalized = normalize(src);
+  return normalized !== ".." && !normalized.startsWith(".." + sep);
+}
+
+// src/cli.ts
 var projectRoot = process.cwd();
 function fail(message) {
   console.error(`Error: ${message}`);
   process.exit(1);
 }
+function readPackageJson(root) {
+  const pkgPath = resolve2(root, "package.json");
+  if (!fs2.existsSync(pkgPath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
 async function runManifest() {
-  const distEntry = resolve(projectRoot, "dist", "index.js");
-  if (!fs.existsSync(distEntry)) {
+  const distEntry = resolve2(projectRoot, "dist", "index.js");
+  if (!fs2.existsSync(distEntry)) {
     fail("dist/index.js is missing. Run the build (tsup) before `rvnxx-nodes manifest`.");
   }
   const mod = await import(pathToFileURL(distEntry).href);
@@ -29,15 +92,23 @@ async function runManifest() {
   }
   const credentials = mod.CREDENTIALS ?? [];
   const templates = mod.TEMPLATES ?? [];
+  const meta = parsePackageMeta(readPackageJson(projectRoot));
+  const hasPackage = meta.name !== "" && meta.version !== "";
+  if (hasPackage && !meta.displayName) {
+    console.warn(
+      '\u26A0 package.json has no "revenexx.displayName" \u2014 the node palette will fall back to the raw package name.'
+    );
+  }
   const manifest = buildManifest(mod.NODES, credentials, templates);
-  const outDir = resolve(projectRoot, "dist");
-  const outFile = resolve(outDir, "manifest.json");
-  fs.mkdirSync(outDir, { recursive: true });
-  fs.writeFileSync(outFile, JSON.stringify(manifest, null, 2), "utf-8");
+  const outDir = resolve2(projectRoot, "dist");
+  const outFile = resolve2(outDir, "manifest.json");
+  fs2.mkdirSync(outDir, { recursive: true });
+  fs2.writeFileSync(outFile, JSON.stringify(manifest, null, 2), "utf-8");
   const credentialCount = manifest.credentials?.length ?? 0;
   const templateCount = manifest.templates?.length ?? 0;
+  const bundlePrefix = hasPackage ? `package ${meta.displayName ? `"${meta.displayName}" ` : ""}(${meta.name}), ` : "";
   console.log(
-    `\u2713 dist/manifest.json \u2014 ${manifest.nodes.length} node(s), ${credentialCount} credential(s), ${templateCount} template(s)`
+    `\u2713 dist/manifest.json \u2014 ${bundlePrefix}${manifest.nodes.length} node(s), ${credentialCount} credential(s), ${templateCount} template(s)`
   );
   for (const m of manifest.nodes) {
     console.log(`  node       ${m.slug}@${m.version}`);
@@ -48,6 +119,7 @@ async function runManifest() {
   for (const t of manifest.templates ?? []) {
     console.log(`  template   ${t.slug}@${t.version} (${t.level})`);
   }
+  copyImages(collectImageSources(manifest), outDir, projectRoot);
 }
 async function main() {
   const command = process.argv[2];

package/dist/index.cjs

@@ -42,6 +42,7 @@ __export(index_exports, {
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
+  parsePackageMeta: () => parsePackageMeta,
   retryConfigFields: () => retryConfigFields,
   safeFetch: () => safeFetch,
   timeoutConfigField: () => timeoutConfigField
@@ -189,6 +190,17 @@ function retryConfigFields(opts) {
 
 // src/manifest.ts
 var MANIFEST_VERSION = "v0-draft";
+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);
+  return {
+    name: str(obj.name),
+    version: str(obj.version),
+    displayName: displayName !== "" ? displayName : void 0
+  };
+}
 function buildManifest(nodes, credentials = [], templates = []) {
   const manifest = {
     manifestVersion: MANIFEST_VERSION,
@@ -431,6 +443,7 @@ function base64Url(buf) {
   isOAuthAuthorizeCredential,
   normalizeCredentialType,
   normalizeLocalized,
+  parsePackageMeta,
   retryConfigFields,
   safeFetch,
   timeoutConfigField

package/dist/index.d.cts

@@ -2,7 +2,25 @@ type LocalizedString = string | Record<string, string>;
 type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
 type OutputKind = 'default' | 'branch' | 'error';
 type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
-type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref';
+type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+/**
+ * Semantic category of an image, driving how the registry/CDN organises and
+ * displays it.
+ */
+type ImageCategory = 'screenshot' | 'logo' | 'banner' | 'icon' | 'other';
+/**
+ * A single image a node, credential type, or template ships alongside its
+ * description (e.g. a screenshot, logo, or banner). The file is bundled into
+ * the package tarball and uploaded to the Revenexx CDN when the package is
+ * published.
+ */
+interface IImage {
+    /** Path to the image file, relative to the package root (e.g. `images/screenshot.png`). */
+    src: string;
+    alt: LocalizedString;
+    title?: LocalizedString;
+    category: ImageCategory;
+}
 interface IInputPort {
     dataType: DataType;
     required?: boolean;
@@ -20,6 +38,14 @@ interface IOutputPort {
     description?: LocalizedString;
     fields?: Record<string, IOutputField>;
     sourceFromConfig?: string;
+    /**
+     * Marks a generic port set resolved at author time by the node's
+     * `resolveOutputs` callback (PO-143), rather than a static `name` or a
+     * config-driven `sourceFromConfig`. Set at most one of `name`,
+     * `sourceFromConfig`, `resolveOutputs` — this is a server-validated
+     * constraint on publish, not enforced by this (intentionally flat) type.
+     */
+    resolveOutputs?: boolean;
     fallback?: {
         name: string;
         label?: LocalizedString;
@@ -49,6 +75,23 @@ interface IConfigFieldBase {
     multiline?: boolean;
     validation?: IConfigValidation;
     options?: IConfigOption[];
+    /**
+     * When true, a *known* field's `options` are resolved at author time via the
+     * node's `loadOptions` (a live/dependent dropdown) instead of a static
+     * `options[]`. Applies to `select` / `multiselect`; left unset for ordinary
+     * static fields.
+     *
+     * Independent of `type: 'dynamic-schema'`: that field type triggers
+     * `resolveConfigSchema` on its own and does NOT require `dynamic: true`.
+     */
+    dynamic?: boolean;
+    /**
+     * Config keys whose values drive this field's dynamic resolution. The editor
+     * re-resolves when one of them changes. A key listed here is
+     * *dependency-driving* and MUST be a literal (it may not set
+     * `expressionAllowed`), so its value is known at author time.
+     */
+    dependsOn?: string[];
     /**
      * Only meaningful when `type === 'credentials-ref'`: the namespaced slug(s) of
      * the credential type(s) this field accepts (e.g. `revenexx:smtp`). The editor
@@ -70,6 +113,8 @@ interface INodeDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     inputs: Record<string, IInputPort>;
     outputs: IOutputPort[];
     config?: IConfigField[];
@@ -99,18 +144,73 @@ interface INodeResult {
     outputs: Record<string, unknown>;
     branch?: string;
 }
+/**
+ * Context handed to a node's *author-time* resolvers (`loadOptions`,
+ * `resolveConfigSchema`, `resolveOutputs`). These run in the node-runtime host
+ * (a Node side-container) while a user is editing the workflow — never in
+ * `execute`. The result is snapshotted into the workflow blob at save, so the
+ * runtime never calls these (PO-143).
+ */
+interface INodeAuthorContext {
+    signal: AbortSignal;
+    logger: {
+        info(message: string, meta?: Record<string, unknown>): void;
+        warn(message: string, meta?: Record<string, unknown>): void;
+        error(message: string, meta?: Record<string, unknown>): void;
+    };
+    /** The user's current partial config values. */
+    config: Record<string, unknown>;
+    /**
+     * Lazily resolve a `secret-ref` config field's value (a key in the tenant
+     * secret store → a single string). Mirrors {@link INodeContext.secrets} so a
+     * resolver that authenticates via a secret-ref uses the same call it would in
+     * `execute`. Resolves against the internal secret endpoint; only the keys the
+     * resolver actually asks for are fetched.
+     */
+    secrets: {
+        get(key: string): Promise<string>;
+    };
+    /**
+     * Lazily resolve a `credentials-ref` instance's access data via the
+     * credentials broker (id → structured material, e.g. `{ accessToken }`).
+     * Mirrors {@link INodeContext.credentials}.
+     */
+    credentials: {
+        get(credentialsId: string): Promise<Record<string, unknown>>;
+    };
+    /** Preferred locale for resolved labels, when the caller supplies one. */
+    locale?: string;
+}
 interface INode {
     description: INodeDescription;
     execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult>;
+    /**
+     * Author-time: resolve the options of a `dynamic` field (a live/dependent
+     * dropdown). `fieldKey` is the config key being resolved. Optional — declare
+     * it only for nodes with `dynamic` `select`/`multiselect` fields.
+     */
+    loadOptions?(ctx: INodeAuthorContext, fieldKey: string): Promise<IConfigOption[]>;
+    /**
+     * Author-time: resolve the flat set of typed config fields that replaces a
+     * `type: 'dynamic-schema'` marker (e.g. an API's parameters once app + API
+     * are chosen). Returns fields in the same config-field grammar; the node is
+     * responsible for flattening any nested API shape into flat keys.
+     */
+    resolveConfigSchema?(ctx: INodeAuthorContext): Promise<IConfigField[]>;
+    /**
+     * Author-time: resolve a generic output-port set for an output marked
+     * `resolveOutputs` (e.g. ports derived from a connected resource's schema).
+     */
+    resolveOutputs?(ctx: INodeAuthorContext): Promise<IOutputPort[]>;
 }
 /**
  * Optional capability interface for nodes that iterate over a collection.
- * Implement this alongside {@link INode} to signal to the worker that this
- * node drives iteration — the worker will call {@link extractItems} instead
+ * Implement this alongside {@link INode} to signal to the runtime that this
+ * node drives iteration — the runtime will call {@link extractItems} instead
  * of relying on slug-based detection.
  *
  * This interface is the designated dispatch point for future child-workflow
- * execution: once per-iteration isolation is needed, the worker can swap the
+ * execution: once per-iteration isolation is needed, the runtime can swap the
  * inline loop for `executeChild` calls without any changes to the node or SDK.
  */
 interface INodeWithIteration {
@@ -159,6 +259,8 @@ interface ICredentialDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     authKind: CredentialAuthKind;
     fields: ICredentialField[];
 }
@@ -270,6 +372,8 @@ interface ITemplateDescription {
     industries?: string[];
     /** Free-form vendor tags (e.g. `pipedrive`, `slack`). */
     vendors?: string[];
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     /** Workflow-blob schema version `definition` targets (e.g. `v0-draft`). */
     blobVersion: string;
     /** The workflow blob instantiated when a user picks this template. */
@@ -284,7 +388,7 @@ interface ITemplateDescription {
 /**
  * Reduce a {@link LocalizedString} to a single plain string.
  *
- * Every consumer (worker, UI, the Laravel side) repeats the same "is it a
+ * Every consumer (the UI, the Laravel side) repeats the same "is it a
  * string or a localized map?" branch to render a name/label; this centralizes
  * it so the rules are defined once:
  *
@@ -302,8 +406,8 @@ declare function normalizeLocalized(value: LocalizedString | undefined | null, f
  *
  * The union `string | string[]` exists so node authors can write the common
  * single-type case as a bare string, but every consumer (the editor that
- * lists tenant credential instances, the worker that resolves the chosen
- * instance, the Laravel side) needs a list to iterate. This centralizes the
+ * lists tenant credential instances, the Laravel side) needs a list to
+ * iterate. This centralizes the
  * "is it a string or an array?" branch — analogous to {@link normalizeLocalized}
  * for `LocalizedString` — so the rules are defined once:
  *
@@ -374,10 +478,41 @@ interface NodeManifest {
      */
     templates?: ITemplateDescription[];
 }
+/**
+ * The registry-relevant fields of a node package's `package.json`, as read by
+ * the CLI. `name`/`version` identify the package; `displayName` is the
+ * human-readable bundle label shown in the editor's node palette (e.g.
+ * „Business Central"). All three are read straight from `package.json` by the
+ * integrations server on upload — the CLI reads them only to warn about a
+ * missing label and to annotate the manifest log line.
+ *
+ * The label lives under a namespaced `revenexx` group in `package.json`
+ * (`{ "revenexx": { "displayName": "…" } }`), not a bespoke top-level key, so
+ * it can't collide with unrelated tooling that squats on `displayName`.
+ */
+interface NodePackageMeta {
+    name: string;
+    version: string;
+    /** Human-readable bundle label (e.g. „Business Central"); optional. */
+    displayName?: string;
+}
+/**
+ * Extracts {@link NodePackageMeta} from parsed `package.json` contents, keeping
+ * only the registry-relevant fields and coercing anything malformed to a safe
+ * shape. All three fields are trimmed; a blank or whitespace-only value becomes
+ * `''` (`name`/`version`) or `undefined` (`displayName`, matching how the server
+ * treats it), so whitespace can't masquerade as a present value in tooling.
+ * The bundle label is read from the `revenexx` group (`revenexx.displayName`).
+ * Does not validate that `name`/`version` are present — the integrations server
+ * enforces that on upload; this is a typed, lenient read for tooling.
+ */
+declare function parsePackageMeta(raw: unknown): NodePackageMeta;
 /**
  * Builds the manifest envelope from a package's `NODES` (and optional
  * `CREDENTIALS` / `TEMPLATES`) exports. The result is what gets written to
- * `dist/manifest.json` and uploaded to the registry inside the tarball.
+ * `dist/manifest.json` and uploaded to the registry inside the tarball. The
+ * bundle label is NOT carried here — the integrations server reads it straight
+ * from `package.json` (`revenexx.displayName`).
  */
 declare function buildManifest(nodes: INode[], credentials?: ICredential[], templates?: ITemplateDescription[]): NodeManifest;
 
@@ -489,4 +624,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IInputPort, type INode, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type LocalizedString, MANIFEST_VERSION, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, buildManifest, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, normalizeCredentialType, normalizeLocalized, retryConfigFields, safeFetch, timeoutConfigField };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, buildManifest, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, normalizeCredentialType, normalizeLocalized, parsePackageMeta, retryConfigFields, safeFetch, timeoutConfigField };

package/dist/index.d.ts

@@ -2,7 +2,25 @@ type LocalizedString = string | Record<string, string>;
 type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
 type OutputKind = 'default' | 'branch' | 'error';
 type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
-type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref';
+type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+/**
+ * Semantic category of an image, driving how the registry/CDN organises and
+ * displays it.
+ */
+type ImageCategory = 'screenshot' | 'logo' | 'banner' | 'icon' | 'other';
+/**
+ * A single image a node, credential type, or template ships alongside its
+ * description (e.g. a screenshot, logo, or banner). The file is bundled into
+ * the package tarball and uploaded to the Revenexx CDN when the package is
+ * published.
+ */
+interface IImage {
+    /** Path to the image file, relative to the package root (e.g. `images/screenshot.png`). */
+    src: string;
+    alt: LocalizedString;
+    title?: LocalizedString;
+    category: ImageCategory;
+}
 interface IInputPort {
     dataType: DataType;
     required?: boolean;
@@ -20,6 +38,14 @@ interface IOutputPort {
     description?: LocalizedString;
     fields?: Record<string, IOutputField>;
     sourceFromConfig?: string;
+    /**
+     * Marks a generic port set resolved at author time by the node's
+     * `resolveOutputs` callback (PO-143), rather than a static `name` or a
+     * config-driven `sourceFromConfig`. Set at most one of `name`,
+     * `sourceFromConfig`, `resolveOutputs` — this is a server-validated
+     * constraint on publish, not enforced by this (intentionally flat) type.
+     */
+    resolveOutputs?: boolean;
     fallback?: {
         name: string;
         label?: LocalizedString;
@@ -49,6 +75,23 @@ interface IConfigFieldBase {
     multiline?: boolean;
     validation?: IConfigValidation;
     options?: IConfigOption[];
+    /**
+     * When true, a *known* field's `options` are resolved at author time via the
+     * node's `loadOptions` (a live/dependent dropdown) instead of a static
+     * `options[]`. Applies to `select` / `multiselect`; left unset for ordinary
+     * static fields.
+     *
+     * Independent of `type: 'dynamic-schema'`: that field type triggers
+     * `resolveConfigSchema` on its own and does NOT require `dynamic: true`.
+     */
+    dynamic?: boolean;
+    /**
+     * Config keys whose values drive this field's dynamic resolution. The editor
+     * re-resolves when one of them changes. A key listed here is
+     * *dependency-driving* and MUST be a literal (it may not set
+     * `expressionAllowed`), so its value is known at author time.
+     */
+    dependsOn?: string[];
     /**
      * Only meaningful when `type === 'credentials-ref'`: the namespaced slug(s) of
      * the credential type(s) this field accepts (e.g. `revenexx:smtp`). The editor
@@ -70,6 +113,8 @@ interface INodeDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     inputs: Record<string, IInputPort>;
     outputs: IOutputPort[];
     config?: IConfigField[];
@@ -99,18 +144,73 @@ interface INodeResult {
     outputs: Record<string, unknown>;
     branch?: string;
 }
+/**
+ * Context handed to a node's *author-time* resolvers (`loadOptions`,
+ * `resolveConfigSchema`, `resolveOutputs`). These run in the node-runtime host
+ * (a Node side-container) while a user is editing the workflow — never in
+ * `execute`. The result is snapshotted into the workflow blob at save, so the
+ * runtime never calls these (PO-143).
+ */
+interface INodeAuthorContext {
+    signal: AbortSignal;
+    logger: {
+        info(message: string, meta?: Record<string, unknown>): void;
+        warn(message: string, meta?: Record<string, unknown>): void;
+        error(message: string, meta?: Record<string, unknown>): void;
+    };
+    /** The user's current partial config values. */
+    config: Record<string, unknown>;
+    /**
+     * Lazily resolve a `secret-ref` config field's value (a key in the tenant
+     * secret store → a single string). Mirrors {@link INodeContext.secrets} so a
+     * resolver that authenticates via a secret-ref uses the same call it would in
+     * `execute`. Resolves against the internal secret endpoint; only the keys the
+     * resolver actually asks for are fetched.
+     */
+    secrets: {
+        get(key: string): Promise<string>;
+    };
+    /**
+     * Lazily resolve a `credentials-ref` instance's access data via the
+     * credentials broker (id → structured material, e.g. `{ accessToken }`).
+     * Mirrors {@link INodeContext.credentials}.
+     */
+    credentials: {
+        get(credentialsId: string): Promise<Record<string, unknown>>;
+    };
+    /** Preferred locale for resolved labels, when the caller supplies one. */
+    locale?: string;
+}
 interface INode {
     description: INodeDescription;
     execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult>;
+    /**
+     * Author-time: resolve the options of a `dynamic` field (a live/dependent
+     * dropdown). `fieldKey` is the config key being resolved. Optional — declare
+     * it only for nodes with `dynamic` `select`/`multiselect` fields.
+     */
+    loadOptions?(ctx: INodeAuthorContext, fieldKey: string): Promise<IConfigOption[]>;
+    /**
+     * Author-time: resolve the flat set of typed config fields that replaces a
+     * `type: 'dynamic-schema'` marker (e.g. an API's parameters once app + API
+     * are chosen). Returns fields in the same config-field grammar; the node is
+     * responsible for flattening any nested API shape into flat keys.
+     */
+    resolveConfigSchema?(ctx: INodeAuthorContext): Promise<IConfigField[]>;
+    /**
+     * Author-time: resolve a generic output-port set for an output marked
+     * `resolveOutputs` (e.g. ports derived from a connected resource's schema).
+     */
+    resolveOutputs?(ctx: INodeAuthorContext): Promise<IOutputPort[]>;
 }
 /**
  * Optional capability interface for nodes that iterate over a collection.
- * Implement this alongside {@link INode} to signal to the worker that this
- * node drives iteration — the worker will call {@link extractItems} instead
+ * Implement this alongside {@link INode} to signal to the runtime that this
+ * node drives iteration — the runtime will call {@link extractItems} instead
  * of relying on slug-based detection.
  *
  * This interface is the designated dispatch point for future child-workflow
- * execution: once per-iteration isolation is needed, the worker can swap the
+ * execution: once per-iteration isolation is needed, the runtime can swap the
  * inline loop for `executeChild` calls without any changes to the node or SDK.
  */
 interface INodeWithIteration {
@@ -159,6 +259,8 @@ interface ICredentialDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     authKind: CredentialAuthKind;
     fields: ICredentialField[];
 }
@@ -270,6 +372,8 @@ interface ITemplateDescription {
     industries?: string[];
     /** Free-form vendor tags (e.g. `pipedrive`, `slack`). */
     vendors?: string[];
+    /** Associated images (screenshots, logos, banners) shipped with the package. */
+    images?: IImage[];
     /** Workflow-blob schema version `definition` targets (e.g. `v0-draft`). */
     blobVersion: string;
     /** The workflow blob instantiated when a user picks this template. */
@@ -284,7 +388,7 @@ interface ITemplateDescription {
 /**
  * Reduce a {@link LocalizedString} to a single plain string.
  *
- * Every consumer (worker, UI, the Laravel side) repeats the same "is it a
+ * Every consumer (the UI, the Laravel side) repeats the same "is it a
  * string or a localized map?" branch to render a name/label; this centralizes
  * it so the rules are defined once:
  *
@@ -302,8 +406,8 @@ declare function normalizeLocalized(value: LocalizedString | undefined | null, f
  *
  * The union `string | string[]` exists so node authors can write the common
  * single-type case as a bare string, but every consumer (the editor that
- * lists tenant credential instances, the worker that resolves the chosen
- * instance, the Laravel side) needs a list to iterate. This centralizes the
+ * lists tenant credential instances, the Laravel side) needs a list to
+ * iterate. This centralizes the
  * "is it a string or an array?" branch — analogous to {@link normalizeLocalized}
  * for `LocalizedString` — so the rules are defined once:
  *
@@ -374,10 +478,41 @@ interface NodeManifest {
      */
     templates?: ITemplateDescription[];
 }
+/**
+ * The registry-relevant fields of a node package's `package.json`, as read by
+ * the CLI. `name`/`version` identify the package; `displayName` is the
+ * human-readable bundle label shown in the editor's node palette (e.g.
+ * „Business Central"). All three are read straight from `package.json` by the
+ * integrations server on upload — the CLI reads them only to warn about a
+ * missing label and to annotate the manifest log line.
+ *
+ * The label lives under a namespaced `revenexx` group in `package.json`
+ * (`{ "revenexx": { "displayName": "…" } }`), not a bespoke top-level key, so
+ * it can't collide with unrelated tooling that squats on `displayName`.
+ */
+interface NodePackageMeta {
+    name: string;
+    version: string;
+    /** Human-readable bundle label (e.g. „Business Central"); optional. */
+    displayName?: string;
+}
+/**
+ * Extracts {@link NodePackageMeta} from parsed `package.json` contents, keeping
+ * only the registry-relevant fields and coercing anything malformed to a safe
+ * shape. All three fields are trimmed; a blank or whitespace-only value becomes
+ * `''` (`name`/`version`) or `undefined` (`displayName`, matching how the server
+ * treats it), so whitespace can't masquerade as a present value in tooling.
+ * The bundle label is read from the `revenexx` group (`revenexx.displayName`).
+ * Does not validate that `name`/`version` are present — the integrations server
+ * enforces that on upload; this is a typed, lenient read for tooling.
+ */
+declare function parsePackageMeta(raw: unknown): NodePackageMeta;
 /**
  * Builds the manifest envelope from a package's `NODES` (and optional
  * `CREDENTIALS` / `TEMPLATES`) exports. The result is what gets written to
- * `dist/manifest.json` and uploaded to the registry inside the tarball.
+ * `dist/manifest.json` and uploaded to the registry inside the tarball. The
+ * bundle label is NOT carried here — the integrations server reads it straight
+ * from `package.json` (`revenexx.displayName`).
  */
 declare function buildManifest(nodes: INode[], credentials?: ICredential[], templates?: ITemplateDescription[]): NodeManifest;
 
@@ -489,4 +624,4 @@ declare abstract class OAuth2AuthCodeCredential extends BaseCredential implement
     test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
 }
 
-export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IInputPort, type INode, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type LocalizedString, MANIFEST_VERSION, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, buildManifest, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, normalizeCredentialType, normalizeLocalized, retryConfigFields, safeFetch, timeoutConfigField };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_TIMEOUT_MS, type DataType, type IConfigField, type IConfigFieldBase, type IConfigOption, type IConfigValidation, type ICredential, type ICredentialContext, type ICredentialDescription, type ICredentialField, type ICredentialOAuthAuthorize, type ICredentialResolveResult, type ICredentialTestResult, type IImage, type IInputPort, type INode, type INodeAuthorContext, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, buildManifest, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, normalizeCredentialType, normalizeLocalized, parsePackageMeta, retryConfigFields, safeFetch, timeoutConfigField };

package/dist/index.js

@@ -4,8 +4,9 @@ import {
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
-  extractManifests
-} from "./chunk-X5HI7WPI.js";
+  extractManifests,
+  parsePackageMeta
+} from "./chunk-WB3BYMLA.js";
 
 // src/types.ts
 function isNodeWithIteration(node) {
@@ -359,6 +360,7 @@ export {
   isOAuthAuthorizeCredential,
   normalizeCredentialType,
   normalizeLocalized,
+  parsePackageMeta,
   retryConfigFields,
   safeFetch,
   timeoutConfigField

package/package.json

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