@revenexx/integrations-node-sdk 1.2.0 → 1.4.0

package/dist/index.cjs

@@ -54,11 +54,14 @@ __export(index_exports, {
   backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
   clampResponseBytes: () => clampResponseBytes,
+  errorPort: () => errorPort,
+  errorResult: () => errorResult,
   evaluate: () => evaluate,
   extractCredentialManifest: () => extractCredentialManifest,
   extractCredentialManifests: () => extractCredentialManifests,
   extractManifest: () => extractManifest,
   extractManifests: () => extractManifests,
+  httpErrorResult: () => httpErrorResult,
   isBlockedAddress: () => isBlockedAddress,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
@@ -76,6 +79,8 @@ __export(index_exports, {
   sleepWithSignal: () => sleepWithSignal,
   takesValue: () => takesValue,
   timeoutConfigField: () => timeoutConfigField,
+  toErrorOutput: () => toErrorOutput,
+  toErrorResult: () => toErrorResult,
   withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
@@ -203,6 +208,76 @@ var NodeError = class extends Error {
   }
 };
 
+// src/nodeErrors.ts
+function toErrorOutput(err) {
+  if (err instanceof NodeError) {
+    const raw = err.meta?.["status"];
+    const status = typeof raw === "number" && Number.isFinite(raw) ? raw : 0;
+    return { code: err.code, message: err.message, status };
+  }
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "TIMEOUT", message: "Request timed out", status: 0 };
+  }
+  if (err instanceof Error) {
+    return { code: "REQUEST_FAILED", message: err.message, status: 0 };
+  }
+  return { code: "REQUEST_FAILED", message: String(err), status: 0 };
+}
+function errorResult(output, port = "error") {
+  return { outputs: { [port]: output }, branch: port };
+}
+function toErrorResult(err, port = "error") {
+  return errorResult(toErrorOutput(err), port);
+}
+function httpErrorResult(err, port = "error") {
+  const body = err instanceof NodeError ? err.meta?.["body"] ?? null : null;
+  return errorResult({ ...toErrorOutput(err), body }, port);
+}
+function errorPort(opts = {}) {
+  return {
+    name: "error",
+    kind: "error",
+    dataType: "object",
+    label: { en: "Error", de: "Fehler" },
+    description: {
+      en: "Taken when the attempt fails in a way the workflow can carry on from. A node that cannot run as configured fails the run instead of taking this path.",
+      de: "Wird genommen, wenn der Versuch auf eine Weise fehlschl\xE4gt, mit der der Workflow weiterarbeiten kann. Ein Node, der so konfiguriert nicht laufen kann, l\xE4sst den Run scheitern, statt diesen Pfad zu nehmen."
+    },
+    fields: {
+      code: {
+        dataType: "string",
+        description: {
+          en: "Machine-readable name of the failure \u2014 branch on this rather than on the message. A node that talks to a remote system shares `TIMEOUT` and `REQUEST_FAILED` with every other one; the remaining codes belong to this node alone.",
+          de: "Maschinenlesbarer Name des Fehlers \u2014 hierauf verzweigen, nicht auf die Meldung. Ein Node, der mit einem Fremdsystem spricht, teilt `TIMEOUT` und `REQUEST_FAILED` mit allen anderen; die \xFCbrigen Codes geh\xF6ren allein zu diesem Node."
+        }
+      },
+      message: {
+        dataType: "string",
+        description: {
+          en: "Wording for whoever reads the run afterwards, frequently the wording the far end used. It is not a stable value to branch on.",
+          de: "Wortlaut f\xFCr den, der den Run sp\xE4ter liest, h\xE4ufig der des Gegen\xFCbers. Kein stabiler Wert, auf den sich Verzweigungen st\xFCtzen sollten."
+        }
+      },
+      status: {
+        dataType: "number",
+        description: {
+          en: "How the far end answered, as an HTTP status code, where one answered with a status at all. `0` otherwise \u2014 a timeout, a refused connection, an input the node could not use, a node that never leaves the workflow, or a failure the far end reported in its own answer rather than in a status, as a bulk job that ends as failed does. So `0` means there is no status to read, not that nothing was reached.",
+          de: "Wie das Gegen\xFCber geantwortet hat, als HTTP-Statuscode \u2014 sofern eines \xFCberhaupt mit einem Status geantwortet hat. Sonst `0`: Timeout, abgelehnte Verbindung, eine unbrauchbare Eingabe, ein Node, der den Workflow nicht verl\xE4sst, oder ein Fehler, den das Gegen\xFCber in seiner Antwort statt im Status gemeldet hat \u2014 wie ein Bulk-Job, der als fehlgeschlagen endet. `0` hei\xDFt also: kein Status zu lesen, nicht: nichts erreicht."
+        }
+      },
+      ...opts.body ? {
+        body: {
+          dataType: "any",
+          description: {
+            en: "The answer the far end gave, where the failure got far enough to have one: the response body, or the job the platform reported as failed.",
+            de: "Die Antwort des Gegen\xFCbers, sofern der Fehler weit genug kam, um eine zu haben: der Response-Body oder der von der Plattform als fehlgeschlagen gemeldete Job."
+          }
+        }
+      } : {}
+    }
+  };
+}
+
 // src/extract.ts
 function extractManifest(node) {
   return node.description;
@@ -596,7 +671,11 @@ async function readJsonOrText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
 function maxBytesConfigField(opts) {
   return {
     key: "maxBytes",
-    label: "Max response size (bytes)",
+    label: { en: "Max response size (bytes)", de: "Maximale Antwortgr\xF6\xDFe (Bytes)" },
+    description: {
+      en: "Answers larger than this are refused instead of read. The limit this package enforces applies above whatever is set here.",
+      de: "Gr\xF6\xDFere Antworten werden abgelehnt statt gelesen. \xDCber dem hier gesetzten Wert gilt zus\xE4tzlich die Obergrenze dieses Pakets."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
     validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
@@ -605,7 +684,11 @@ function maxBytesConfigField(opts) {
 function timeoutConfigField(opts) {
   return {
     key: "timeoutMs",
-    label: "Timeout (ms)",
+    label: { en: "Timeout (ms)", de: "Zeitlimit (ms)" },
+    description: {
+      en: "How long one attempt may take before it fails as a timeout. Counted per attempt and per redirect hop, not across the whole call.",
+      de: "Wie lange ein einzelner Versuch dauern darf, bevor er als Zeit\xFCberschreitung fehlschl\xE4gt. Gilt je Versuch und je Weiterleitung, nicht f\xFCr den gesamten Aufruf."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_TIMEOUT_MS,
     validation: { min: 100, max: opts?.max ?? MAX_TIMEOUT_MS }
@@ -615,14 +698,22 @@ function retryConfigFields(opts) {
   return [
     {
       key: "retryAttempts",
-      label: "Retry attempts",
+      label: { en: "Retry attempts", de: "Wiederholungsversuche" },
+      description: {
+        en: "How often a failed attempt is repeated. 0 sends the request once and reports the first failure.",
+        de: "Wie oft ein fehlgeschlagener Versuch wiederholt wird. 0 sendet die Anfrage einmal und meldet den ersten Fehler."
+      },
       type: "number",
       default: opts?.defaultAttempts ?? DEFAULT_RETRY_ATTEMPTS,
       validation: { min: 0, max: MAX_RETRY_ATTEMPTS }
     },
     {
       key: "retryDelayMs",
-      label: "Retry delay (ms)",
+      label: { en: "Retry delay (ms)", de: "Wartezeit vor Wiederholung (ms)" },
+      description: {
+        en: "How long to wait before the next attempt.",
+        de: "Wie lange vor dem n\xE4chsten Versuch gewartet wird."
+      },
       type: "number",
       default: opts?.defaultDelayMs ?? DEFAULT_RETRY_DELAY_MS,
       validation: { min: 100 }
@@ -823,11 +914,39 @@ var SimpleValueCredential = class extends BaseCredential {
   }
 };
 var ApiKeyCredential = class extends BaseCredential {
+  /**
+   * Which field of the credential form the key is typed into. Override it to
+   * name the form field this provider calls its key — `botToken`, `authKey`,
+   * `webhookUrl`.
+   *
+   * **What this does not do** (PO-497): it does not decide what a node looks
+   * the key up under at run time. It used to do only half of that — it changed
+   * which field was *read* while {@link credentialShape} went on emitting
+   * `apiKey` — so a credential that renamed its form field alone handed the
+   * node a key under a name it was never told to expect, and the node refused
+   * a perfectly good key as a missing one. The default shape now follows this
+   * name, so overriding this alone is correct on both sides. Overriding
+   * {@link credentialShape} as well is still how a credential emits a
+   * different name, or more than the key.
+   *
+   * Note that no node test can see a mismatch between the two: a mocked node
+   * context is seeded with the resolved blob directly and never calls
+   * `resolve`. Only a credential test asserting the whole resolved shape
+   * catches it, and asserting it loosely still misses — a partial match is
+   * happy with the wrong key present beside the right one.
+   */
   apiKeyField() {
     return "apiKey";
   }
+  /**
+   * What the node receives. Defaults to the key under the name
+   * {@link apiKeyField} returns, so the two cannot drift apart by default.
+   *
+   * Override it where the node needs a different name than the form uses, or
+   * needs more than the key — a base URL derived from it, say.
+   */
   credentialShape(apiKey) {
-    return { apiKey };
+    return { [this.apiKeyField()]: apiKey };
   }
   async resolve(_ctx, config, _durableCreds) {
     const apiKey = requireString(config, this.apiKeyField(), this.description.slug);
@@ -980,11 +1099,14 @@ function base64Url(buf) {
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  errorPort,
+  errorResult,
   evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  httpErrorResult,
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
@@ -1002,5 +1124,7 @@ function base64Url(buf) {
   sleepWithSignal,
   takesValue,
   timeoutConfigField,
+  toErrorOutput,
+  toErrorResult,
   withRetry
 });

package/dist/index.d.cts

@@ -650,6 +650,67 @@ declare class NodeError extends Error {
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
 
+/**
+ * Canonical error-output shape emitted on a node's `error` port. It lives here
+ * rather than in a node package because all four of them were building it
+ * separately — `integrations-nodes-core` in an internal module, `deepl` in a
+ * copy of that module, Business Central in `bc-fetch.ts` and Pipedrive in
+ * `pipedrive-client.ts` — so the workflow editor's guarantee of one
+ * `{ code, message, status }` payload rested on four files agreeing by hand
+ * (PO-442; asked for by PO-134 in June and not done then).
+ */
+interface NodeErrorOutput {
+    /** Machine-readable error code, e.g. `HTTP_ERROR`, `TIMEOUT`, `REQUEST_FAILED`. */
+    code: string;
+    message: string;
+    /** HTTP status code, or `0` for timeouts / network / non-HTTP errors. */
+    status: number;
+    /** Optional response body — HTTP-specific. */
+    body?: unknown;
+}
+/**
+ * Normalize any caught value into the canonical {@link NodeErrorOutput} shape.
+ * Use this in a node's `catch` block before routing to the `error` port.
+ */
+declare function toErrorOutput(err: unknown): NodeErrorOutput;
+/** Wrap an error output into an `INodeResult` routed to the `error` port. */
+declare function errorResult(output: NodeErrorOutput, port?: string): INodeResult;
+/**
+ * Catch-block shortcut: normalize any thrown value and route it to the failure
+ * output. The one helper every node's `catch` funnels into, so the
+ * `{ code, message, status }` mapping lives in a single place instead of being
+ * re-implemented per protocol (FTP/SFTP) or per package.
+ *
+ * `port` is the output taken, `error` unless the node declares its failure
+ * output under another name (`{ ...errorPort(), name: 'failed' }`) — pass the
+ * same name here, or the branch names a port that node does not have.
+ */
+declare function toErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Catch-block shortcut for the HTTP-style nodes whose failure output additionally
+ * declares `body`: the canonical `{ code, message, status }` mapping plus the
+ * response body a {@link NodeError} carries in `meta.body` (`null` when the
+ * failure never reached a response). `port` names the output as above.
+ */
+declare function httpErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Shared `error` output port — the uniform `{ code, message, status }` triple
+ * declared on every node that has an `error` branch. Pass `body: true` for
+ * HTTP-style nodes that additionally emit a response body on the port.
+ *
+ * The sentences travel with the port. The three values mean the same thing
+ * behind every node, so they are written here once instead of per node; a node
+ * whose failures are worth naming more precisely spreads the port and replaces
+ * only its `description` (`{ ...errorPort(), description: … }`).
+ *
+ * The second sentence of the description is the rule this port exists under,
+ * and it is promised in `specs/error-handling.md`: a fault in the author's own
+ * configuration ends the run, a fault met while running is offered here.
+ */
+declare function errorPort(opts?: {
+    body?: boolean;
+}): IOutputPort;
+
 declare function extractManifest(node: INode): INodeDescription;
 declare function extractManifests(nodes: INode[]): INodeDescription[];
 declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
@@ -710,14 +771,45 @@ declare function readText(res: Response, maxBytes?: number): Promise<string>;
  * rather than a raw `SyntaxError`, keeping to the SDK error contract.
  */
 declare function readJsonOrText(res: Response, maxBytes?: number): Promise<unknown>;
+/**
+ * The setting a node offers its workflow author for the response size cap,
+ * ready to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): declaring the setting does not
+ * wire it up. Read the configured value in `execute` and pass it on — the
+ * helpers here only produce the declaration, and a node that spreads this and
+ * never reads `config.maxBytes` offers a setting that does nothing.
+ *
+ * Everything an author reads is supplied in both languages the node packages
+ * write, so spreading this unchanged already satisfies the rule they hold.
+ * Nothing is left to the caller on that side: a node that wants different
+ * words replaces the field rather than completing it.
+ */
 declare function maxBytesConfigField(opts?: {
     default?: number;
     max?: number;
 }): IConfigField;
+/**
+ * The setting a node offers its workflow author for the request budget, ready
+ * to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): pass the configured value to
+ * `safeFetch` as `timeoutMs`. See {@link maxBytesConfigField} for the same note
+ * and for why the label and description are not the caller's to complete.
+ */
 declare function timeoutConfigField(opts?: {
     default?: number;
     max?: number;
 }): IConfigField;
+/**
+ * The two settings a node offers its workflow author for the retry budget,
+ * ready to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): pass both configured values to
+ * `safeFetch` as `retry.attempts` and `retry.delayMs`. See
+ * {@link maxBytesConfigField} for the same note and for why the labels and
+ * descriptions are not the caller's to complete.
+ */
 declare function retryConfigFields(opts?: {
     defaultAttempts?: number;
     defaultDelayMs?: number;
@@ -982,11 +1074,40 @@ declare abstract class SimpleValueCredential extends BaseCredential {
     resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
 }
 /**
- * API-key credential. By default exposes the configured key under
- * `{ apiKey }`; override {@link apiKeyField}/{@link credentialShape} to map.
+ * API-key credential. Reads the key from the configured field and hands it to
+ * the node under that same name; override {@link credentialShape} where the
+ * node needs something else, or more than the key alone.
  */
 declare abstract class ApiKeyCredential extends BaseCredential {
+    /**
+     * Which field of the credential form the key is typed into. Override it to
+     * name the form field this provider calls its key — `botToken`, `authKey`,
+     * `webhookUrl`.
+     *
+     * **What this does not do** (PO-497): it does not decide what a node looks
+     * the key up under at run time. It used to do only half of that — it changed
+     * which field was *read* while {@link credentialShape} went on emitting
+     * `apiKey` — so a credential that renamed its form field alone handed the
+     * node a key under a name it was never told to expect, and the node refused
+     * a perfectly good key as a missing one. The default shape now follows this
+     * name, so overriding this alone is correct on both sides. Overriding
+     * {@link credentialShape} as well is still how a credential emits a
+     * different name, or more than the key.
+     *
+     * Note that no node test can see a mismatch between the two: a mocked node
+     * context is seeded with the resolved blob directly and never calls
+     * `resolve`. Only a credential test asserting the whole resolved shape
+     * catches it, and asserting it loosely still misses — a partial match is
+     * happy with the wrong key present beside the right one.
+     */
     protected apiKeyField(): string;
+    /**
+     * What the node receives. Defaults to the key under the name
+     * {@link apiKeyField} returns, so the two cannot drift apart by default.
+     *
+     * Override it where the node needs a different name than the form uses, or
+     * needs more than the key — a base URL derived from it, say.
+     */
     protected credentialShape(apiKey: string): Record<string, unknown>;
     resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
 }
@@ -1046,4 +1167,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_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeErrorOutput, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, errorPort, errorResult, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, httpErrorResult, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, toErrorOutput, toErrorResult, withRetry };

package/dist/index.d.ts

@@ -650,6 +650,67 @@ declare class NodeError extends Error {
     constructor(code: string, message: string, meta?: Record<string, unknown>);
 }
 
+/**
+ * Canonical error-output shape emitted on a node's `error` port. It lives here
+ * rather than in a node package because all four of them were building it
+ * separately — `integrations-nodes-core` in an internal module, `deepl` in a
+ * copy of that module, Business Central in `bc-fetch.ts` and Pipedrive in
+ * `pipedrive-client.ts` — so the workflow editor's guarantee of one
+ * `{ code, message, status }` payload rested on four files agreeing by hand
+ * (PO-442; asked for by PO-134 in June and not done then).
+ */
+interface NodeErrorOutput {
+    /** Machine-readable error code, e.g. `HTTP_ERROR`, `TIMEOUT`, `REQUEST_FAILED`. */
+    code: string;
+    message: string;
+    /** HTTP status code, or `0` for timeouts / network / non-HTTP errors. */
+    status: number;
+    /** Optional response body — HTTP-specific. */
+    body?: unknown;
+}
+/**
+ * Normalize any caught value into the canonical {@link NodeErrorOutput} shape.
+ * Use this in a node's `catch` block before routing to the `error` port.
+ */
+declare function toErrorOutput(err: unknown): NodeErrorOutput;
+/** Wrap an error output into an `INodeResult` routed to the `error` port. */
+declare function errorResult(output: NodeErrorOutput, port?: string): INodeResult;
+/**
+ * Catch-block shortcut: normalize any thrown value and route it to the failure
+ * output. The one helper every node's `catch` funnels into, so the
+ * `{ code, message, status }` mapping lives in a single place instead of being
+ * re-implemented per protocol (FTP/SFTP) or per package.
+ *
+ * `port` is the output taken, `error` unless the node declares its failure
+ * output under another name (`{ ...errorPort(), name: 'failed' }`) — pass the
+ * same name here, or the branch names a port that node does not have.
+ */
+declare function toErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Catch-block shortcut for the HTTP-style nodes whose failure output additionally
+ * declares `body`: the canonical `{ code, message, status }` mapping plus the
+ * response body a {@link NodeError} carries in `meta.body` (`null` when the
+ * failure never reached a response). `port` names the output as above.
+ */
+declare function httpErrorResult(err: unknown, port?: string): INodeResult;
+/**
+ * Shared `error` output port — the uniform `{ code, message, status }` triple
+ * declared on every node that has an `error` branch. Pass `body: true` for
+ * HTTP-style nodes that additionally emit a response body on the port.
+ *
+ * The sentences travel with the port. The three values mean the same thing
+ * behind every node, so they are written here once instead of per node; a node
+ * whose failures are worth naming more precisely spreads the port and replaces
+ * only its `description` (`{ ...errorPort(), description: … }`).
+ *
+ * The second sentence of the description is the rule this port exists under,
+ * and it is promised in `specs/error-handling.md`: a fault in the author's own
+ * configuration ends the run, a fault met while running is offered here.
+ */
+declare function errorPort(opts?: {
+    body?: boolean;
+}): IOutputPort;
+
 declare function extractManifest(node: INode): INodeDescription;
 declare function extractManifests(nodes: INode[]): INodeDescription[];
 declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
@@ -710,14 +771,45 @@ declare function readText(res: Response, maxBytes?: number): Promise<string>;
  * rather than a raw `SyntaxError`, keeping to the SDK error contract.
  */
 declare function readJsonOrText(res: Response, maxBytes?: number): Promise<unknown>;
+/**
+ * The setting a node offers its workflow author for the response size cap,
+ * ready to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): declaring the setting does not
+ * wire it up. Read the configured value in `execute` and pass it on — the
+ * helpers here only produce the declaration, and a node that spreads this and
+ * never reads `config.maxBytes` offers a setting that does nothing.
+ *
+ * Everything an author reads is supplied in both languages the node packages
+ * write, so spreading this unchanged already satisfies the rule they hold.
+ * Nothing is left to the caller on that side: a node that wants different
+ * words replaces the field rather than completing it.
+ */
 declare function maxBytesConfigField(opts?: {
     default?: number;
     max?: number;
 }): IConfigField;
+/**
+ * The setting a node offers its workflow author for the request budget, ready
+ * to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): pass the configured value to
+ * `safeFetch` as `timeoutMs`. See {@link maxBytesConfigField} for the same note
+ * and for why the label and description are not the caller's to complete.
+ */
 declare function timeoutConfigField(opts?: {
     default?: number;
     max?: number;
 }): IConfigField;
+/**
+ * The two settings a node offers its workflow author for the retry budget,
+ * ready to spread into `description.config`.
+ *
+ * **What the node still has to do** (PO-497): pass both configured values to
+ * `safeFetch` as `retry.attempts` and `retry.delayMs`. See
+ * {@link maxBytesConfigField} for the same note and for why the labels and
+ * descriptions are not the caller's to complete.
+ */
 declare function retryConfigFields(opts?: {
     defaultAttempts?: number;
     defaultDelayMs?: number;
@@ -982,11 +1074,40 @@ declare abstract class SimpleValueCredential extends BaseCredential {
     resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
 }
 /**
- * API-key credential. By default exposes the configured key under
- * `{ apiKey }`; override {@link apiKeyField}/{@link credentialShape} to map.
+ * API-key credential. Reads the key from the configured field and hands it to
+ * the node under that same name; override {@link credentialShape} where the
+ * node needs something else, or more than the key alone.
  */
 declare abstract class ApiKeyCredential extends BaseCredential {
+    /**
+     * Which field of the credential form the key is typed into. Override it to
+     * name the form field this provider calls its key — `botToken`, `authKey`,
+     * `webhookUrl`.
+     *
+     * **What this does not do** (PO-497): it does not decide what a node looks
+     * the key up under at run time. It used to do only half of that — it changed
+     * which field was *read* while {@link credentialShape} went on emitting
+     * `apiKey` — so a credential that renamed its form field alone handed the
+     * node a key under a name it was never told to expect, and the node refused
+     * a perfectly good key as a missing one. The default shape now follows this
+     * name, so overriding this alone is correct on both sides. Overriding
+     * {@link credentialShape} as well is still how a credential emits a
+     * different name, or more than the key.
+     *
+     * Note that no node test can see a mismatch between the two: a mocked node
+     * context is seeded with the resolved blob directly and never calls
+     * `resolve`. Only a credential test asserting the whole resolved shape
+     * catches it, and asserting it loosely still misses — a partial match is
+     * happy with the wrong key present beside the right one.
+     */
     protected apiKeyField(): string;
+    /**
+     * What the node receives. Defaults to the key under the name
+     * {@link apiKeyField} returns, so the two cannot drift apart by default.
+     *
+     * Override it where the node needs a different name than the form uses, or
+     * needs more than the key — a base URL derived from it, say.
+     */
     protected credentialShape(apiKey: string): Record<string, unknown>;
     resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
 }
@@ -1046,4 +1167,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_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, withRetry };
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, DEFAULT_MAX_RESPONSE_BYTES, DEFAULT_RETRY_ATTEMPTS, DEFAULT_RETRY_DELAY_MS, DEFAULT_RETRY_POLICY, 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 INodeState, type INodeWithIteration, type IOutputField, type IOutputPort, type IShowIfCondition, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, type LookupAddress, type LookupFn, MANIFEST_VERSION, MAX_REDIRECTS, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeErrorOutput, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, OPERATORS, type Operator, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, VALUELESS_OPERATORS, assertPublicUrl, backoffDelay, buildManifest, clampResponseBytes, errorPort, errorResult, evaluate, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, httpErrorResult, isBlockedAddress, isNodeWithIteration, isOAuthAuthorizeCredential, isOperator, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, settingApplies, sleepWithSignal, takesValue, timeoutConfigField, toErrorOutput, toErrorResult, withRetry };

package/dist/index.js

@@ -131,6 +131,76 @@ var NodeError = class extends Error {
   }
 };
 
+// src/nodeErrors.ts
+function toErrorOutput(err) {
+  if (err instanceof NodeError) {
+    const raw = err.meta?.["status"];
+    const status = typeof raw === "number" && Number.isFinite(raw) ? raw : 0;
+    return { code: err.code, message: err.message, status };
+  }
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "TIMEOUT", message: "Request timed out", status: 0 };
+  }
+  if (err instanceof Error) {
+    return { code: "REQUEST_FAILED", message: err.message, status: 0 };
+  }
+  return { code: "REQUEST_FAILED", message: String(err), status: 0 };
+}
+function errorResult(output, port = "error") {
+  return { outputs: { [port]: output }, branch: port };
+}
+function toErrorResult(err, port = "error") {
+  return errorResult(toErrorOutput(err), port);
+}
+function httpErrorResult(err, port = "error") {
+  const body = err instanceof NodeError ? err.meta?.["body"] ?? null : null;
+  return errorResult({ ...toErrorOutput(err), body }, port);
+}
+function errorPort(opts = {}) {
+  return {
+    name: "error",
+    kind: "error",
+    dataType: "object",
+    label: { en: "Error", de: "Fehler" },
+    description: {
+      en: "Taken when the attempt fails in a way the workflow can carry on from. A node that cannot run as configured fails the run instead of taking this path.",
+      de: "Wird genommen, wenn der Versuch auf eine Weise fehlschl\xE4gt, mit der der Workflow weiterarbeiten kann. Ein Node, der so konfiguriert nicht laufen kann, l\xE4sst den Run scheitern, statt diesen Pfad zu nehmen."
+    },
+    fields: {
+      code: {
+        dataType: "string",
+        description: {
+          en: "Machine-readable name of the failure \u2014 branch on this rather than on the message. A node that talks to a remote system shares `TIMEOUT` and `REQUEST_FAILED` with every other one; the remaining codes belong to this node alone.",
+          de: "Maschinenlesbarer Name des Fehlers \u2014 hierauf verzweigen, nicht auf die Meldung. Ein Node, der mit einem Fremdsystem spricht, teilt `TIMEOUT` und `REQUEST_FAILED` mit allen anderen; die \xFCbrigen Codes geh\xF6ren allein zu diesem Node."
+        }
+      },
+      message: {
+        dataType: "string",
+        description: {
+          en: "Wording for whoever reads the run afterwards, frequently the wording the far end used. It is not a stable value to branch on.",
+          de: "Wortlaut f\xFCr den, der den Run sp\xE4ter liest, h\xE4ufig der des Gegen\xFCbers. Kein stabiler Wert, auf den sich Verzweigungen st\xFCtzen sollten."
+        }
+      },
+      status: {
+        dataType: "number",
+        description: {
+          en: "How the far end answered, as an HTTP status code, where one answered with a status at all. `0` otherwise \u2014 a timeout, a refused connection, an input the node could not use, a node that never leaves the workflow, or a failure the far end reported in its own answer rather than in a status, as a bulk job that ends as failed does. So `0` means there is no status to read, not that nothing was reached.",
+          de: "Wie das Gegen\xFCber geantwortet hat, als HTTP-Statuscode \u2014 sofern eines \xFCberhaupt mit einem Status geantwortet hat. Sonst `0`: Timeout, abgelehnte Verbindung, eine unbrauchbare Eingabe, ein Node, der den Workflow nicht verl\xE4sst, oder ein Fehler, den das Gegen\xFCber in seiner Antwort statt im Status gemeldet hat \u2014 wie ein Bulk-Job, der als fehlgeschlagen endet. `0` hei\xDFt also: kein Status zu lesen, nicht: nichts erreicht."
+        }
+      },
+      ...opts.body ? {
+        body: {
+          dataType: "any",
+          description: {
+            en: "The answer the far end gave, where the failure got far enough to have one: the response body, or the job the platform reported as failed.",
+            de: "Die Antwort des Gegen\xFCbers, sofern der Fehler weit genug kam, um eine zu haben: der Response-Body oder der von der Plattform als fehlgeschlagen gemeldete Job."
+          }
+        }
+      } : {}
+    }
+  };
+}
+
 // src/ssrf.ts
 import { subscribe } from "diagnostics_channel";
 import { isIP } from "net";
@@ -510,7 +580,11 @@ async function readJsonOrText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
 function maxBytesConfigField(opts) {
   return {
     key: "maxBytes",
-    label: "Max response size (bytes)",
+    label: { en: "Max response size (bytes)", de: "Maximale Antwortgr\xF6\xDFe (Bytes)" },
+    description: {
+      en: "Answers larger than this are refused instead of read. The limit this package enforces applies above whatever is set here.",
+      de: "Gr\xF6\xDFere Antworten werden abgelehnt statt gelesen. \xDCber dem hier gesetzten Wert gilt zus\xE4tzlich die Obergrenze dieses Pakets."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
     validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
@@ -519,7 +593,11 @@ function maxBytesConfigField(opts) {
 function timeoutConfigField(opts) {
   return {
     key: "timeoutMs",
-    label: "Timeout (ms)",
+    label: { en: "Timeout (ms)", de: "Zeitlimit (ms)" },
+    description: {
+      en: "How long one attempt may take before it fails as a timeout. Counted per attempt and per redirect hop, not across the whole call.",
+      de: "Wie lange ein einzelner Versuch dauern darf, bevor er als Zeit\xFCberschreitung fehlschl\xE4gt. Gilt je Versuch und je Weiterleitung, nicht f\xFCr den gesamten Aufruf."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_TIMEOUT_MS,
     validation: { min: 100, max: opts?.max ?? MAX_TIMEOUT_MS }
@@ -529,14 +607,22 @@ function retryConfigFields(opts) {
   return [
     {
       key: "retryAttempts",
-      label: "Retry attempts",
+      label: { en: "Retry attempts", de: "Wiederholungsversuche" },
+      description: {
+        en: "How often a failed attempt is repeated. 0 sends the request once and reports the first failure.",
+        de: "Wie oft ein fehlgeschlagener Versuch wiederholt wird. 0 sendet die Anfrage einmal und meldet den ersten Fehler."
+      },
       type: "number",
       default: opts?.defaultAttempts ?? DEFAULT_RETRY_ATTEMPTS,
       validation: { min: 0, max: MAX_RETRY_ATTEMPTS }
     },
     {
       key: "retryDelayMs",
-      label: "Retry delay (ms)",
+      label: { en: "Retry delay (ms)", de: "Wartezeit vor Wiederholung (ms)" },
+      description: {
+        en: "How long to wait before the next attempt.",
+        de: "Wie lange vor dem n\xE4chsten Versuch gewartet wird."
+      },
       type: "number",
       default: opts?.defaultDelayMs ?? DEFAULT_RETRY_DELAY_MS,
       validation: { min: 100 }
@@ -710,11 +796,39 @@ var SimpleValueCredential = class extends BaseCredential {
   }
 };
 var ApiKeyCredential = class extends BaseCredential {
+  /**
+   * Which field of the credential form the key is typed into. Override it to
+   * name the form field this provider calls its key — `botToken`, `authKey`,
+   * `webhookUrl`.
+   *
+   * **What this does not do** (PO-497): it does not decide what a node looks
+   * the key up under at run time. It used to do only half of that — it changed
+   * which field was *read* while {@link credentialShape} went on emitting
+   * `apiKey` — so a credential that renamed its form field alone handed the
+   * node a key under a name it was never told to expect, and the node refused
+   * a perfectly good key as a missing one. The default shape now follows this
+   * name, so overriding this alone is correct on both sides. Overriding
+   * {@link credentialShape} as well is still how a credential emits a
+   * different name, or more than the key.
+   *
+   * Note that no node test can see a mismatch between the two: a mocked node
+   * context is seeded with the resolved blob directly and never calls
+   * `resolve`. Only a credential test asserting the whole resolved shape
+   * catches it, and asserting it loosely still misses — a partial match is
+   * happy with the wrong key present beside the right one.
+   */
   apiKeyField() {
     return "apiKey";
   }
+  /**
+   * What the node receives. Defaults to the key under the name
+   * {@link apiKeyField} returns, so the two cannot drift apart by default.
+   *
+   * Override it where the node needs a different name than the form uses, or
+   * needs more than the key — a base URL derived from it, say.
+   */
   credentialShape(apiKey) {
-    return { apiKey };
+    return { [this.apiKeyField()]: apiKey };
   }
   async resolve(_ctx, config, _durableCreds) {
     const apiKey = requireString(config, this.apiKeyField(), this.description.slug);
@@ -866,11 +980,14 @@ export {
   backoffDelay,
   buildManifest,
   clampResponseBytes,
+  errorPort,
+  errorResult,
   evaluate,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
+  httpErrorResult,
   isBlockedAddress,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
@@ -888,5 +1005,7 @@ export {
   sleepWithSignal,
   takesValue,
   timeoutConfigField,
+  toErrorOutput,
+  toErrorResult,
   withRetry
 };

package/package.json

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