@revenexx/integrations-node-sdk 1.3.0 → 1.4.1

package/dist/index.cjs

@@ -671,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: "An answer larger than this is refused instead of read, counted per answer rather than per run. This package enforces a ceiling of its own above it, so a larger value buys nothing.",
+      de: "Eine gr\xF6\xDFere Antwort wird abgelehnt statt gelesen; gez\xE4hlt wird je Antwort, nicht je Lauf. Dar\xFCber liegt zus\xE4tzlich die feste Obergrenze dieses Pakets, ein h\xF6herer Wert bringt also nichts."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
     validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
@@ -680,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 }
@@ -690,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 }
@@ -898,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);

package/dist/index.d.cts

@@ -771,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;
@@ -1043,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>;
 }

package/dist/index.d.ts

@@ -771,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;
@@ -1043,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>;
 }

package/dist/index.js

@@ -580,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: "An answer larger than this is refused instead of read, counted per answer rather than per run. This package enforces a ceiling of its own above it, so a larger value buys nothing.",
+      de: "Eine gr\xF6\xDFere Antwort wird abgelehnt statt gelesen; gez\xE4hlt wird je Antwort, nicht je Lauf. Dar\xFCber liegt zus\xE4tzlich die feste Obergrenze dieses Pakets, ein h\xF6herer Wert bringt also nichts."
+    },
     type: "number",
     default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
     validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
@@ -589,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 }
@@ -599,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 }
@@ -780,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);

package/package.json

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