@revenexx/integrations-node-sdk 0.14.0 → 0.16.0

package/dist/index.cjs

@@ -23,29 +23,41 @@ __export(index_exports, {
   ApiKeyCredential: () => ApiKeyCredential,
   BaseCredential: () => BaseCredential,
   BasicAuthCredential: () => BasicAuthCredential,
+  DEFAULT_MAX_RESPONSE_BYTES: () => DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_RETRY_ATTEMPTS: () => DEFAULT_RETRY_ATTEMPTS,
   DEFAULT_RETRY_DELAY_MS: () => DEFAULT_RETRY_DELAY_MS,
+  DEFAULT_RETRY_POLICY: () => DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION: () => MANIFEST_VERSION,
+  MAX_RESPONSE_BYTES: () => MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS: () => MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS: () => MAX_TIMEOUT_MS,
   NodeError: () => NodeError,
   OAuth2AuthCodeCredential: () => OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential: () => OAuth2ClientCredentialsCredential,
+  RetryableError: () => RetryableError,
   SimpleValueCredential: () => SimpleValueCredential,
+  backoffDelay: () => backoffDelay,
   buildManifest: () => buildManifest,
+  clampResponseBytes: () => clampResponseBytes,
   extractCredentialManifest: () => extractCredentialManifest,
   extractCredentialManifests: () => extractCredentialManifests,
   extractManifest: () => extractManifest,
   extractManifests: () => extractManifests,
   isNodeWithIteration: () => isNodeWithIteration,
   isOAuthAuthorizeCredential: () => isOAuthAuthorizeCredential,
+  maxBytesConfigField: () => maxBytesConfigField,
   normalizeCredentialType: () => normalizeCredentialType,
   normalizeLocalized: () => normalizeLocalized,
   parsePackageMeta: () => parsePackageMeta,
+  readArrayBuffer: () => readArrayBuffer,
+  readJsonOrText: () => readJsonOrText,
+  readText: () => readText,
   retryConfigFields: () => retryConfigFields,
   safeFetch: () => safeFetch,
-  timeoutConfigField: () => timeoutConfigField
+  sleepWithSignal: () => sleepWithSignal,
+  timeoutConfigField: () => timeoutConfigField,
+  withRetry: () => withRetry
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -123,6 +135,12 @@ var MAX_TIMEOUT_MS = 12e4;
 var DEFAULT_RETRY_ATTEMPTS = 0;
 var MAX_RETRY_ATTEMPTS = 5;
 var DEFAULT_RETRY_DELAY_MS = 1e3;
+var DEFAULT_MAX_RESPONSE_BYTES = 25 * 1024 * 1024;
+var MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+function clampResponseBytes(maxBytes) {
+  if (!Number.isFinite(maxBytes) || maxBytes < 1) return MAX_RESPONSE_BYTES;
+  return Math.min(maxBytes, MAX_RESPONSE_BYTES);
+}
 async function safeFetch(url, options = {}) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
@@ -160,6 +178,82 @@ async function safeFetch(url, options = {}) {
   }
   throw lastError;
 }
+function tooLargeError(status, bytes, maxBytes) {
+  return new NodeError(
+    "RESPONSE_TOO_LARGE",
+    `Response body of ${bytes} bytes exceeds the ${maxBytes}-byte limit`,
+    { status }
+  );
+}
+async function readArrayBuffer(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const cap = clampResponseBytes(maxBytes);
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > cap) {
+    throw tooLargeError(res.status, declared, cap);
+  }
+  const body = res.body;
+  if (!body) {
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength > cap) throw tooLargeError(res.status, buf.byteLength, cap);
+    return buf;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel().catch(() => {
+        });
+        throw tooLargeError(res.status, total, cap);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+async function readText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const buf = await readArrayBuffer(res, maxBytes);
+  return new TextDecoder().decode(buf);
+}
+function isJsonContentType(contentType) {
+  const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+async function readJsonOrText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const contentType = res.headers.get("content-type") ?? "";
+  const text = await readText(res, maxBytes);
+  if (!isJsonContentType(contentType)) return text;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new NodeError(
+      "RESPONSE_PARSE_ERROR",
+      `Invalid JSON response: ${e.message}`,
+      { status: res.status }
+    );
+  }
+}
+function maxBytesConfigField(opts) {
+  return {
+    key: "maxBytes",
+    label: "Max response size (bytes)",
+    type: "number",
+    default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
+    validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
+  };
+}
 function timeoutConfigField(opts) {
   return {
     key: "timeoutMs",
@@ -188,6 +282,74 @@ function retryConfigFields(opts) {
   ];
 }
 
+// src/retry.ts
+var RetryableError = class extends Error {
+  /** Server-dictated delay before the next attempt, e.g. parsed from `Retry-After`. */
+  retryAfterMs;
+  constructor(message, opts) {
+    super(message, { cause: opts?.cause });
+    this.name = "RetryableError";
+    this.retryAfterMs = opts?.retryAfterMs;
+  }
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 3e4,
+  factor: 2,
+  jitter: true
+};
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+function backoffDelay(attempt, policy) {
+  const exponent = Math.max(0, attempt - 1);
+  const raw = policy.baseDelayMs * Math.pow(policy.factor, exponent);
+  const cap = Math.min(policy.maxDelayMs, raw);
+  return policy.jitter ? Math.random() * cap : cap;
+}
+function sleepWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function withRetry(fn, policy, hooks) {
+  const effective = { ...DEFAULT_RETRY_POLICY, ...policy };
+  const maxAttempts = Math.max(1, effective.maxAttempts);
+  const { signal, logger, onRetry } = hooks;
+  for (let attempt = 1; ; attempt++) {
+    if (signal.aborted) throw abortReason(signal);
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      if (!(err instanceof RetryableError) || attempt >= maxAttempts) throw err;
+      const retryAfter = err.retryAfterMs;
+      const rawDelay = typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : backoffDelay(attempt, effective);
+      const delayMs = Number.isFinite(rawDelay) && rawDelay >= 0 ? rawDelay : 0;
+      onRetry?.({ attempt, delayMs, error: err });
+      logger?.warn("Retrying after retryable error", {
+        attempt,
+        maxAttempts,
+        delayMs,
+        error: err.message
+      });
+      await sleepWithSignal(delayMs, signal);
+    }
+  }
+}
+
 // src/manifest.ts
 var MANIFEST_VERSION = "v0-draft";
 function parsePackageMeta(raw) {
@@ -424,27 +586,39 @@ function base64Url(buf) {
   ApiKeyCredential,
   BaseCredential,
   BasicAuthCredential,
+  DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_RETRY_ATTEMPTS,
   DEFAULT_RETRY_DELAY_MS,
+  DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION,
+  MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS,
   NodeError,
   OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential,
+  RetryableError,
   SimpleValueCredential,
+  backoffDelay,
   buildManifest,
+  clampResponseBytes,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
+  maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
   parsePackageMeta,
+  readArrayBuffer,
+  readJsonOrText,
+  readText,
   retryConfigFields,
   safeFetch,
-  timeoutConfigField
+  sleepWithSignal,
+  timeoutConfigField,
+  withRetry
 });

package/dist/index.d.cts

@@ -113,6 +113,12 @@ interface INodeDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /**
+     * Curated node-picker group path, outermost first (max 4 levels), e.g.
+     * `[{ en: 'Business Central' }, { en: 'Sales Orders' }]`. Optional —
+     * pickers without it fall back to package/category grouping.
+     */
+    groups?: LocalizedString[];
     /** Associated images (screenshots, logos, banners) shipped with the package. */
     images?: IImage[];
     inputs: Record<string, IInputPort>;
@@ -434,6 +440,21 @@ declare const MAX_TIMEOUT_MS = 120000;
 declare const DEFAULT_RETRY_ATTEMPTS = 0;
 declare const MAX_RETRY_ATTEMPTS = 5;
 declare const DEFAULT_RETRY_DELAY_MS = 1000;
+/**
+ * Default cap for response bodies read via {@link readArrayBuffer} /
+ * {@link readText} / {@link readJsonOrText}. Guards the (shared) worker process
+ * against a single oversized response exhausting its memory.
+ */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * Hard upper ceiling for any per-node `maxBytes`. Even a permissive node author
+ * (who calls {@link maxBytesConfigField} without an explicit `max`, or passes a
+ * large `maxBytes` to the `read*` helpers) can never lift the cap above this, so
+ * the shared worker's memory stays bounded. Analogous to {@link MAX_TIMEOUT_MS}.
+ */
+declare const MAX_RESPONSE_BYTES: number;
+/** Clamp a requested `maxBytes` into `[1, MAX_RESPONSE_BYTES]`. */
+declare function clampResponseBytes(maxBytes: number): number;
 interface SafeFetchRetry {
     attempts: number;
     delayMs?: number;
@@ -445,6 +466,31 @@ interface SafeFetchOptions extends RequestInit {
     retry?: SafeFetchRetry;
 }
 declare function safeFetch(url: string | URL, options?: SafeFetchOptions): Promise<Response>;
+/**
+ * Read a response body into an ArrayBuffer while enforcing a hard byte cap.
+ *
+ * The `Content-Length` header is used as a fast-reject (bail before downloading
+ * anything), but the limit is *also* enforced while streaming, since the header
+ * can be absent or lie. On overrun the stream is cancelled and a
+ * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown.
+ */
+declare function readArrayBuffer(res: Response, maxBytes?: number): Promise<ArrayBuffer>;
+/** Read a response body as UTF-8 text, capped at `maxBytes` (see {@link readArrayBuffer}). */
+declare function readText(res: Response, maxBytes?: number): Promise<string>;
+/**
+ * Read a response body as JSON when the `Content-Type` denotes JSON (see
+ * {@link isJsonContentType}), otherwise as text — the content-type sniff
+ * previously duplicated across the HTTP/Upload/DeepL node sinks. Capped at
+ * `maxBytes` (see {@link readArrayBuffer}).
+ *
+ * A malformed JSON body surfaces as `NodeError('RESPONSE_PARSE_ERROR', …, { status })`
+ * rather than a raw `SyntaxError`, keeping to the SDK error contract.
+ */
+declare function readJsonOrText(res: Response, maxBytes?: number): Promise<unknown>;
+declare function maxBytesConfigField(opts?: {
+    default?: number;
+    max?: number;
+}): IConfigField;
 declare function timeoutConfigField(opts?: {
     default?: number;
     max?: number;
@@ -454,6 +500,82 @@ declare function retryConfigFields(opts?: {
     defaultDelayMs?: number;
 }): IConfigField[];
 
+/**
+ * Transport-agnostic retry/backoff primitive (PO-139).
+ *
+ * Wraps *any* async operation — raw `fetch`, an SDK client (axios), a future
+ * transport — with exponential backoff + full jitter, honouring a
+ * server-dictated delay (HTTP `Retry-After`) when the caller supplies one.
+ *
+ * The retry decision lives with the connector: it throws a {@link RetryableError}
+ * only when an attempt failed *and* is worth retrying. Everything else is
+ * rethrown as-is, and terminal API errors that connectors model as *values*
+ * (e.g. a `{ kind: 'http-error' }` union) simply flow back as the return value.
+ *
+ * This is deliberately NOT a circuit breaker, rate limiter, or HTTP client, and
+ * it does not replace Temporal activity-level retries — it is the fine-grained,
+ * idempotency-aware, `Retry-After`-honouring layer inside a single activity.
+ */
+/** Thrown by the wrapped fn to signal "this attempt failed but is retryable". */
+declare class RetryableError extends Error {
+    /** Server-dictated delay before the next attempt, e.g. parsed from `Retry-After`. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, opts?: {
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+interface RetryPolicy {
+    /** Total tries including the first. */
+    maxAttempts: number;
+    /** Base delay for the exponential backoff. */
+    baseDelayMs: number;
+    /** Upper bound for any single computed delay. */
+    maxDelayMs: number;
+    /** Exponential growth factor. */
+    factor: number;
+    /** Apply full jitter to the computed backoff. */
+    jitter: boolean;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+interface RetryHooks {
+    /** Pass `ctx.signal` so cancelling a workflow cancels the wait (and stops retrying) immediately. */
+    signal: AbortSignal;
+    logger?: {
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
+    onRetry?(info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }): void;
+}
+/**
+ * Pure backoff math, exported for testing/reuse. Returns the delay before the
+ * retry that follows the given (1-based) failed `attempt`: an exponential term
+ * `baseDelayMs * factor^(attempt-1)` capped at `maxDelayMs`, with full jitter
+ * (`random() * cap`) when `policy.jitter` is set.
+ */
+declare function backoffDelay(attempt: number, policy: RetryPolicy): number;
+/**
+ * Abort-aware sleep. Resolves after `ms`, or rejects with the signal's reason
+ * (a DOMException `AbortError` by default) as soon as `signal` aborts — so a
+ * caller's retry loop stops cleanly instead of finishing the wait.
+ */
+declare function sleepWithSignal(ms: number, signal: AbortSignal): Promise<void>;
+/**
+ * Runs `fn`; if it throws a {@link RetryableError} and attempts remain, waits
+ * (`RetryableError.retryAfterMs` when present, else the computed
+ * {@link backoffDelay}) respecting `signal`, then retries. Any other throw is
+ * rethrown immediately; on the final attempt the RetryableError itself is
+ * thrown (preserving its `retryAfterMs`/`cause`), not its `.cause`.
+ *
+ * Distinct from `safeFetch`'s built-in fixed-delay `retry` option, which is
+ * unchanged: that is a simple in-fetch retry; this is the richer, transport-
+ * agnostic, `Retry-After`-aware primitive connectors wrap around any operation.
+ */
+declare function withRetry<T>(fn: (attempt: number) => Promise<T>, policy: Partial<RetryPolicy>, hooks: RetryHooks): Promise<T>;
+
 /**
  * Envelope version expected by the integrations server-side
  * `TarballInspector`. Earlier (pre-registry) builds emitted a bare array
@@ -624,4 +746,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 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 };
+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 INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };

package/dist/index.d.ts

@@ -113,6 +113,12 @@ interface INodeDescription {
     name: LocalizedString;
     description?: LocalizedString;
     icon?: string;
+    /**
+     * Curated node-picker group path, outermost first (max 4 levels), e.g.
+     * `[{ en: 'Business Central' }, { en: 'Sales Orders' }]`. Optional —
+     * pickers without it fall back to package/category grouping.
+     */
+    groups?: LocalizedString[];
     /** Associated images (screenshots, logos, banners) shipped with the package. */
     images?: IImage[];
     inputs: Record<string, IInputPort>;
@@ -434,6 +440,21 @@ declare const MAX_TIMEOUT_MS = 120000;
 declare const DEFAULT_RETRY_ATTEMPTS = 0;
 declare const MAX_RETRY_ATTEMPTS = 5;
 declare const DEFAULT_RETRY_DELAY_MS = 1000;
+/**
+ * Default cap for response bodies read via {@link readArrayBuffer} /
+ * {@link readText} / {@link readJsonOrText}. Guards the (shared) worker process
+ * against a single oversized response exhausting its memory.
+ */
+declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+/**
+ * Hard upper ceiling for any per-node `maxBytes`. Even a permissive node author
+ * (who calls {@link maxBytesConfigField} without an explicit `max`, or passes a
+ * large `maxBytes` to the `read*` helpers) can never lift the cap above this, so
+ * the shared worker's memory stays bounded. Analogous to {@link MAX_TIMEOUT_MS}.
+ */
+declare const MAX_RESPONSE_BYTES: number;
+/** Clamp a requested `maxBytes` into `[1, MAX_RESPONSE_BYTES]`. */
+declare function clampResponseBytes(maxBytes: number): number;
 interface SafeFetchRetry {
     attempts: number;
     delayMs?: number;
@@ -445,6 +466,31 @@ interface SafeFetchOptions extends RequestInit {
     retry?: SafeFetchRetry;
 }
 declare function safeFetch(url: string | URL, options?: SafeFetchOptions): Promise<Response>;
+/**
+ * Read a response body into an ArrayBuffer while enforcing a hard byte cap.
+ *
+ * The `Content-Length` header is used as a fast-reject (bail before downloading
+ * anything), but the limit is *also* enforced while streaming, since the header
+ * can be absent or lie. On overrun the stream is cancelled and a
+ * `NodeError('RESPONSE_TOO_LARGE', …, { status })` is thrown.
+ */
+declare function readArrayBuffer(res: Response, maxBytes?: number): Promise<ArrayBuffer>;
+/** Read a response body as UTF-8 text, capped at `maxBytes` (see {@link readArrayBuffer}). */
+declare function readText(res: Response, maxBytes?: number): Promise<string>;
+/**
+ * Read a response body as JSON when the `Content-Type` denotes JSON (see
+ * {@link isJsonContentType}), otherwise as text — the content-type sniff
+ * previously duplicated across the HTTP/Upload/DeepL node sinks. Capped at
+ * `maxBytes` (see {@link readArrayBuffer}).
+ *
+ * A malformed JSON body surfaces as `NodeError('RESPONSE_PARSE_ERROR', …, { status })`
+ * rather than a raw `SyntaxError`, keeping to the SDK error contract.
+ */
+declare function readJsonOrText(res: Response, maxBytes?: number): Promise<unknown>;
+declare function maxBytesConfigField(opts?: {
+    default?: number;
+    max?: number;
+}): IConfigField;
 declare function timeoutConfigField(opts?: {
     default?: number;
     max?: number;
@@ -454,6 +500,82 @@ declare function retryConfigFields(opts?: {
     defaultDelayMs?: number;
 }): IConfigField[];
 
+/**
+ * Transport-agnostic retry/backoff primitive (PO-139).
+ *
+ * Wraps *any* async operation — raw `fetch`, an SDK client (axios), a future
+ * transport — with exponential backoff + full jitter, honouring a
+ * server-dictated delay (HTTP `Retry-After`) when the caller supplies one.
+ *
+ * The retry decision lives with the connector: it throws a {@link RetryableError}
+ * only when an attempt failed *and* is worth retrying. Everything else is
+ * rethrown as-is, and terminal API errors that connectors model as *values*
+ * (e.g. a `{ kind: 'http-error' }` union) simply flow back as the return value.
+ *
+ * This is deliberately NOT a circuit breaker, rate limiter, or HTTP client, and
+ * it does not replace Temporal activity-level retries — it is the fine-grained,
+ * idempotency-aware, `Retry-After`-honouring layer inside a single activity.
+ */
+/** Thrown by the wrapped fn to signal "this attempt failed but is retryable". */
+declare class RetryableError extends Error {
+    /** Server-dictated delay before the next attempt, e.g. parsed from `Retry-After`. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, opts?: {
+        retryAfterMs?: number;
+        cause?: unknown;
+    });
+}
+interface RetryPolicy {
+    /** Total tries including the first. */
+    maxAttempts: number;
+    /** Base delay for the exponential backoff. */
+    baseDelayMs: number;
+    /** Upper bound for any single computed delay. */
+    maxDelayMs: number;
+    /** Exponential growth factor. */
+    factor: number;
+    /** Apply full jitter to the computed backoff. */
+    jitter: boolean;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+interface RetryHooks {
+    /** Pass `ctx.signal` so cancelling a workflow cancels the wait (and stops retrying) immediately. */
+    signal: AbortSignal;
+    logger?: {
+        warn(msg: string, meta?: Record<string, unknown>): void;
+    };
+    onRetry?(info: {
+        attempt: number;
+        delayMs: number;
+        error: unknown;
+    }): void;
+}
+/**
+ * Pure backoff math, exported for testing/reuse. Returns the delay before the
+ * retry that follows the given (1-based) failed `attempt`: an exponential term
+ * `baseDelayMs * factor^(attempt-1)` capped at `maxDelayMs`, with full jitter
+ * (`random() * cap`) when `policy.jitter` is set.
+ */
+declare function backoffDelay(attempt: number, policy: RetryPolicy): number;
+/**
+ * Abort-aware sleep. Resolves after `ms`, or rejects with the signal's reason
+ * (a DOMException `AbortError` by default) as soon as `signal` aborts — so a
+ * caller's retry loop stops cleanly instead of finishing the wait.
+ */
+declare function sleepWithSignal(ms: number, signal: AbortSignal): Promise<void>;
+/**
+ * Runs `fn`; if it throws a {@link RetryableError} and attempts remain, waits
+ * (`RetryableError.retryAfterMs` when present, else the computed
+ * {@link backoffDelay}) respecting `signal`, then retries. Any other throw is
+ * rethrown immediately; on the final attempt the RetryableError itself is
+ * thrown (preserving its `retryAfterMs`/`cause`), not its `.cause`.
+ *
+ * Distinct from `safeFetch`'s built-in fixed-delay `retry` option, which is
+ * unchanged: that is a simple in-fetch retry; this is the richer, transport-
+ * agnostic, `Retry-After`-aware primitive connectors wrap around any operation.
+ */
+declare function withRetry<T>(fn: (attempt: number) => Promise<T>, policy: Partial<RetryPolicy>, hooks: RetryHooks): Promise<T>;
+
 /**
  * Envelope version expected by the integrations server-side
  * `TarballInspector`. Earlier (pre-registry) builds emitted a bare array
@@ -624,4 +746,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 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 };
+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 INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type ImageCategory, type LocalizedString, MANIFEST_VERSION, MAX_RESPONSE_BYTES, MAX_RETRY_ATTEMPTS, MAX_TIMEOUT_MS, type NodeCategory, NodeError, type NodeManifest, type NodePackageMeta, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, type RetryHooks, type RetryPolicy, RetryableError, type SafeFetchOptions, type SafeFetchRetry, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, backoffDelay, buildManifest, clampResponseBytes, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, maxBytesConfigField, normalizeCredentialType, normalizeLocalized, parsePackageMeta, readArrayBuffer, readJsonOrText, readText, retryConfigFields, safeFetch, sleepWithSignal, timeoutConfigField, withRetry };

package/dist/index.js

@@ -68,6 +68,12 @@ var MAX_TIMEOUT_MS = 12e4;
 var DEFAULT_RETRY_ATTEMPTS = 0;
 var MAX_RETRY_ATTEMPTS = 5;
 var DEFAULT_RETRY_DELAY_MS = 1e3;
+var DEFAULT_MAX_RESPONSE_BYTES = 25 * 1024 * 1024;
+var MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+function clampResponseBytes(maxBytes) {
+  if (!Number.isFinite(maxBytes) || maxBytes < 1) return MAX_RESPONSE_BYTES;
+  return Math.min(maxBytes, MAX_RESPONSE_BYTES);
+}
 async function safeFetch(url, options = {}) {
   const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: ctxSignal, retry, ...fetchOptions } = options;
   const effectiveMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.min(timeoutMs, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
@@ -105,6 +111,82 @@ async function safeFetch(url, options = {}) {
   }
   throw lastError;
 }
+function tooLargeError(status, bytes, maxBytes) {
+  return new NodeError(
+    "RESPONSE_TOO_LARGE",
+    `Response body of ${bytes} bytes exceeds the ${maxBytes}-byte limit`,
+    { status }
+  );
+}
+async function readArrayBuffer(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const cap = clampResponseBytes(maxBytes);
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > cap) {
+    throw tooLargeError(res.status, declared, cap);
+  }
+  const body = res.body;
+  if (!body) {
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength > cap) throw tooLargeError(res.status, buf.byteLength, cap);
+    return buf;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel().catch(() => {
+        });
+        throw tooLargeError(res.status, total, cap);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out.buffer;
+}
+async function readText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const buf = await readArrayBuffer(res, maxBytes);
+  return new TextDecoder().decode(buf);
+}
+function isJsonContentType(contentType) {
+  const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+  return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+async function readJsonOrText(res, maxBytes = DEFAULT_MAX_RESPONSE_BYTES) {
+  const contentType = res.headers.get("content-type") ?? "";
+  const text = await readText(res, maxBytes);
+  if (!isJsonContentType(contentType)) return text;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new NodeError(
+      "RESPONSE_PARSE_ERROR",
+      `Invalid JSON response: ${e.message}`,
+      { status: res.status }
+    );
+  }
+}
+function maxBytesConfigField(opts) {
+  return {
+    key: "maxBytes",
+    label: "Max response size (bytes)",
+    type: "number",
+    default: opts?.default ?? DEFAULT_MAX_RESPONSE_BYTES,
+    validation: { min: 1, max: Math.min(opts?.max ?? MAX_RESPONSE_BYTES, MAX_RESPONSE_BYTES) }
+  };
+}
 function timeoutConfigField(opts) {
   return {
     key: "timeoutMs",
@@ -133,6 +215,74 @@ function retryConfigFields(opts) {
   ];
 }
 
+// src/retry.ts
+var RetryableError = class extends Error {
+  /** Server-dictated delay before the next attempt, e.g. parsed from `Retry-After`. */
+  retryAfterMs;
+  constructor(message, opts) {
+    super(message, { cause: opts?.cause });
+    this.name = "RetryableError";
+    this.retryAfterMs = opts?.retryAfterMs;
+  }
+};
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 3e4,
+  factor: 2,
+  jitter: true
+};
+function abortReason(signal) {
+  return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+function backoffDelay(attempt, policy) {
+  const exponent = Math.max(0, attempt - 1);
+  const raw = policy.baseDelayMs * Math.pow(policy.factor, exponent);
+  const cap = Math.min(policy.maxDelayMs, raw);
+  return policy.jitter ? Math.random() * cap : cap;
+}
+function sleepWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(abortReason(signal));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortReason(signal));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function withRetry(fn, policy, hooks) {
+  const effective = { ...DEFAULT_RETRY_POLICY, ...policy };
+  const maxAttempts = Math.max(1, effective.maxAttempts);
+  const { signal, logger, onRetry } = hooks;
+  for (let attempt = 1; ; attempt++) {
+    if (signal.aborted) throw abortReason(signal);
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      if (!(err instanceof RetryableError) || attempt >= maxAttempts) throw err;
+      const retryAfter = err.retryAfterMs;
+      const rawDelay = typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : backoffDelay(attempt, effective);
+      const delayMs = Number.isFinite(rawDelay) && rawDelay >= 0 ? rawDelay : 0;
+      onRetry?.({ attempt, delayMs, error: err });
+      logger?.warn("Retrying after retryable error", {
+        attempt,
+        maxAttempts,
+        delayMs,
+        error: err.message
+      });
+      await sleepWithSignal(delayMs, signal);
+    }
+  }
+}
+
 // src/credentials.ts
 import { createHash, randomBytes } from "crypto";
 function readString(source, key) {
@@ -341,27 +491,39 @@ export {
   ApiKeyCredential,
   BaseCredential,
   BasicAuthCredential,
+  DEFAULT_MAX_RESPONSE_BYTES,
   DEFAULT_RETRY_ATTEMPTS,
   DEFAULT_RETRY_DELAY_MS,
+  DEFAULT_RETRY_POLICY,
   DEFAULT_TIMEOUT_MS,
   MANIFEST_VERSION,
+  MAX_RESPONSE_BYTES,
   MAX_RETRY_ATTEMPTS,
   MAX_TIMEOUT_MS,
   NodeError,
   OAuth2AuthCodeCredential,
   OAuth2ClientCredentialsCredential,
+  RetryableError,
   SimpleValueCredential,
+  backoffDelay,
   buildManifest,
+  clampResponseBytes,
   extractCredentialManifest,
   extractCredentialManifests,
   extractManifest,
   extractManifests,
   isNodeWithIteration,
   isOAuthAuthorizeCredential,
+  maxBytesConfigField,
   normalizeCredentialType,
   normalizeLocalized,
   parsePackageMeta,
+  readArrayBuffer,
+  readJsonOrText,
+  readText,
   retryConfigFields,
   safeFetch,
-  timeoutConfigField
+  sleepWithSignal,
+  timeoutConfigField,
+  withRetry
 };

package/package.json

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