@revenexx/integrations-node-sdk 1.8.1 → 1.9.1

package/dist/conditions.d.ts

@@ -0,0 +1,16 @@
+import type { IShowIfCondition } from './types.js';
+/**
+ * Whether a setting applies, given what the author has filled in so far.
+ *
+ * A setting with no condition always applies — which is what makes `showIf`
+ * additive: a node that says nothing gets the behaviour it has today, and an
+ * editor that does not know the key draws every field as before.
+ *
+ * The value the condition reads is taken from the config as it stands mid-edit,
+ * so it is routinely `undefined`: the moment a node is dropped on the canvas
+ * nothing is filled in. That is why `equals` against a missing value is `false`
+ * rather than an error — the setting does not apply *yet*.
+ */
+export declare function settingApplies(field: {
+    showIf?: IShowIfCondition;
+}, config: Record<string, unknown>): boolean;

package/dist/credentialType.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reduce an `IConfigField.credentialType` (a single slug or an array of slugs)
+ * to a normalized, deduplicated `string[]`.
+ *
+ * The union `string | string[]` exists so node authors can write the common
+ * single-type case as a bare string, but every consumer (the editor that
+ * lists tenant credential instances, the Laravel side) needs a list to
+ * iterate. This centralizes the
+ * "is it a string or an array?" branch — analogous to {@link normalizeLocalized}
+ * for `LocalizedString` — so the rules are defined once:
+ *
+ * - a single non-empty slug becomes a one-element array;
+ * - an array is trimmed of blank entries and deduplicated, preserving order;
+ * - `undefined`, an empty string, or an empty/all-blank array yields `[]`, so
+ *   the caller can treat "accepts nothing" uniformly.
+ */
+export declare function normalizeCredentialType(value: string | string[] | undefined): string[];

package/dist/credentials.d.ts

@@ -0,0 +1,162 @@
+import type { ICredential, ICredentialContext, ICredentialDescription, ICredentialOAuthAuthorize, ICredentialResolveResult, ICredentialTestResult } from './types.js';
+/**
+ * Reusable credential base classes. Concrete credential types (in node
+ * packages) extend one of these and only supply field mappings / endpoints —
+ * the auth strategy itself lives here so it is implemented once.
+ *
+ * All of this runs in the credentials broker (a Node side-container), never in
+ * workflow code, so wall-clock time and network I/O are fine.
+ */
+type Config = Record<string, unknown>;
+type DurableCreds = Record<string, unknown> | null;
+export interface OAuthTokenResponse {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    token_type?: string;
+    /**
+     * Provider-specific base URL the access token must target (e.g. Pipedrive
+     * returns the company-scoped `api_domain` on both the initial exchange and
+     * every refresh). Absent for providers that use a single global API host.
+     */
+    api_domain?: string;
+    [key: string]: unknown;
+}
+/**
+ * The base for every credential type. Stores the published description and
+ * provides a small HTTP helper. `resolve` is abstract; `test` defaults to a
+ * presence check and should be overridden where a real connection test exists.
+ */
+export declare abstract class BaseCredential implements ICredential {
+    abstract readonly description: ICredentialDescription;
+    abstract resolve(ctx: ICredentialContext, config: Config, durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
+    test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
+    /**
+     * POST `application/x-www-form-urlencoded` and parse a JSON token response.
+     *
+     * Goes through {@link safeFetch}, not a raw `fetch` (PO-185). The token
+     * endpoint is not a constant: `tokenUrl(config)` derives it from credential
+     * config, i.e. from a value someone types into a credential form. A raw fetch
+     * would happily POST the client secret at `http://169.254.169.254/…` or any
+     * other internal address, which is precisely what `assertPublicUrl` exists to
+     * prevent. Every OAuth token exchange in this file — client-credentials,
+     * auth-code, refresh — funnels through here, so this is the one call site that
+     * has to hold.
+     *
+     * Two behaviours safeFetch adds, both wanted here: a request budget
+     * (`DEFAULT_TIMEOUT_MS`) on top of `ctx.signal`, and manual redirect handling
+     * that re-checks each hop and drops `Authorization` across an origin boundary.
+     * Note that a 301/302 answer to this POST is downgraded to a bodiless GET —
+     * per the redirect rules, not a quirk of ours. Real token endpoints do not
+     * redirect; one that does was never going to complete the exchange anyway.
+     *
+     * The third protection is the caller's own: safeFetch hands back a `Response`
+     * and reading it is not its job, so the answer goes through {@link readText}
+     * under {@link MAX_TOKEN_RESPONSE_BYTES} rather than a bare `res.text()`.
+     * Both branches below read that same string, so the cap covers the refusal as
+     * well as the token — an error body is the less predictable of the two.
+     */
+    protected postForm(ctx: ICredentialContext, url: string, form: Record<string, string | undefined>, headers?: Record<string, string>): Promise<OAuthTokenResponse>;
+}
+/**
+ * "Simple value retrieval": the validated config fields ARE the access data
+ * handed to the node (e.g. SMTP host/port/user/password, SFTP host/key). No
+ * token, no expiry. Override `test` to add a real connection check.
+ */
+export declare abstract class SimpleValueCredential extends BaseCredential {
+    resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
+}
+/**
+ * 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.
+ */
+export 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>;
+}
+/**
+ * HTTP Basic auth credential. Exposes `{ username, password }` by default.
+ */
+export declare abstract class BasicAuthCredential extends BaseCredential {
+    protected usernameField(): string;
+    protected passwordField(): string;
+    resolve(_ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
+}
+/**
+ * OAuth2 client-credentials grant (service-to-service, no user, no
+ * refresh_token). Concrete types supply the token endpoint + client creds via
+ * the config field map. Robust to downtime: a fresh access token is minted on
+ * every resolve when the broker cache misses.
+ */
+export declare abstract class OAuth2ClientCredentialsCredential extends BaseCredential {
+    protected abstract tokenUrl(config: Config): string;
+    protected abstract clientId(config: Config): string;
+    protected abstract clientSecret(config: Config): string;
+    protected scope(_config: Config): string | undefined;
+    /** Map the raw token response to the node-facing credentials. */
+    protected credentialShape(token: OAuthTokenResponse): Record<string, unknown>;
+    resolve(ctx: ICredentialContext, config: Config, _durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
+    test(ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
+}
+/**
+ * OAuth2 authorization-code grant (3-legged, interactive consent). Implements
+ * the consent dance (with PKCE by default), code exchange, and refresh-token
+ * based resolution. The long-lived `refresh_token` is stored in durableCreds;
+ * if the provider rotates it, the new one is persisted via the context.
+ */
+export declare abstract class OAuth2AuthCodeCredential extends BaseCredential implements ICredentialOAuthAuthorize {
+    protected abstract authorizeUrl(config: Config): string;
+    protected abstract tokenUrl(config: Config): string;
+    protected abstract clientId(config: Config): string;
+    protected abstract clientSecret(config: Config): string;
+    protected scope(_config: Config): string | undefined;
+    protected usePkce(): boolean;
+    protected credentialShape(token: OAuthTokenResponse): Record<string, unknown>;
+    buildAuthorizeUrl(_ctx: ICredentialContext, config: Config, params: {
+        redirectUri: string;
+        state: string;
+    }): Promise<{
+        authorizeUrl: string;
+        codeVerifier?: string;
+    }>;
+    exchangeCode(ctx: ICredentialContext, config: Config, params: {
+        code: string;
+        redirectUri: string;
+        codeVerifier?: string;
+    }): Promise<{
+        durableCreds: Record<string, unknown>;
+    }>;
+    resolve(ctx: ICredentialContext, config: Config, durableCreds: DurableCreds): Promise<ICredentialResolveResult>;
+    test(_ctx: ICredentialContext, config: Config): Promise<ICredentialTestResult>;
+}
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class NodeError extends Error {
+    readonly code: string;
+    readonly meta?: Record<string, unknown>;
+    constructor(code: string, message: string, meta?: Record<string, unknown>);
+}

package/dist/extract.d.ts

@@ -0,0 +1,5 @@
+import type { ICredential, ICredentialDescription, INode, INodeDescription } from './types.js';
+export declare function extractManifest(node: INode): INodeDescription;
+export declare function extractManifests(nodes: INode[]): INodeDescription[];
+export declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
+export declare function extractCredentialManifests(credentials: ICredential[]): ICredentialDescription[];

package/dist/fetch.d.ts

@@ -0,0 +1,111 @@
+import type { IConfigField } from './types.js';
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const MAX_TIMEOUT_MS = 120000;
+/** Maximum number of redirect hops `safeFetch` follows before giving up. */
+export declare const MAX_REDIRECTS = 5;
+/**
+ * Whether a request header with this name goes on to the next hop when
+ * {@link safeFetch} follows a redirect to another origin — `true` for `Accept`,
+ * `Accept-Encoding`, `Accept-Language`, `Content-Encoding`, `Content-Language`,
+ * `Content-Type`, `Idempotency-Key`, `If-Match`, `If-Modified-Since`,
+ * `If-None-Match`, `If-Range`, `If-Unmodified-Since`, `Range`, `SOAPAction` and
+ * `User-Agent`, in any case, and `false` for every other name. The keep-list is by
+ * name, so it can only keep a secret out of the headers it drops: a credential
+ * whose header name the author chooses must refuse a name this answers `true`
+ * for, or its key would cross with the harmless headers.
+ */
+export declare function headerCrossesOrigin(name: string): boolean;
+export declare const DEFAULT_RETRY_ATTEMPTS = 0;
+export declare const MAX_RETRY_ATTEMPTS = 5;
+export 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.
+ */
+export 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}.
+ */
+export declare const MAX_RESPONSE_BYTES: number;
+/** Clamp a requested `maxBytes` into `[1, MAX_RESPONSE_BYTES]`. */
+export declare function clampResponseBytes(maxBytes: number): number;
+export interface SafeFetchRetry {
+    attempts: number;
+    delayMs?: number;
+}
+export interface SafeFetchOptions extends RequestInit {
+    timeoutMs?: number;
+    /** Pass `ctx.signal` so the workflow engine can cancel the request. */
+    signal?: AbortSignal;
+    retry?: SafeFetchRetry;
+}
+export 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. Both refusal paths
+ * cancel the body first, so neither leaves the connection held.
+ */
+export declare function readArrayBuffer(res: Response, maxBytes?: number): Promise<ArrayBuffer>;
+/** Read a response body as UTF-8 text, capped at `maxBytes` (see {@link readArrayBuffer}). */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function retryConfigFields(opts?: {
+    defaultAttempts?: number;
+    defaultDelayMs?: number;
+}): IConfigField[];

package/dist/images.d.ts

@@ -0,0 +1,28 @@
+import type { IImage } from './types.js';
+/** Something that may carry an `images` array (a node/credential/template manifest). */
+interface WithImages {
+    images?: IImage[];
+}
+/**
+ * Collect the unique `src` of every image declared across all nodes,
+ * credential types, and templates in a manifest.
+ */
+export declare function collectImageSources(manifest: {
+    nodes?: WithImages[];
+    credentials?: WithImages[];
+    templates?: WithImages[];
+}): string[];
+/**
+ * Copy declared image files into `dist/`, preserving their sub-path
+ * (`images/x.png` → `dist/images/x.png`) so `npm pack` picks them up via the
+ * package's `files: ["dist"]`. Sources are resolved relative to `rootDir`
+ * (the package root, `process.cwd()`).
+ *
+ * Every problematic declaration warns and is skipped rather than throwing, so a
+ * stale manifest never breaks the build: this covers a missing file, a `src`
+ * that is a directory rather than a file, and — defensively — an unsafe `src`
+ * that is absolute or escapes the package root via `..` traversal (which would
+ * otherwise read/write outside `dist/`).
+ */
+export declare function copyImages(sources: string[], outDir: string, rootDir: string): void;
+export {};

package/dist/index.cjs

@@ -572,6 +572,15 @@ async function guardUrl(url, ctxSignal, effectiveMs) {
     clearTimeout(timer);
   }
 }
+function hasContent(body) {
+  if (body == null) return false;
+  if (typeof body === "string") return body.length > 0;
+  if (body instanceof ArrayBuffer) return body.byteLength > 0;
+  if (ArrayBuffer.isView(body)) return body.byteLength > 0;
+  if (body instanceof Blob) return body.size > 0;
+  if (body instanceof URLSearchParams) return body.toString().length > 0;
+  return true;
+}
 async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
   let currentUrl = url;
   let currentInit = { ...fetchOptions, redirect: "manual" };
@@ -604,7 +613,6 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
     if (base.protocol === "https:" && nextUrl.protocol !== "https:") {
       throw new NodeError("BLOCKED_ADDRESS", "Blocked https\u2192http downgrade on redirect", { status: 0 });
     }
-    await guardUrl(nextUrl, ctxSignal, effectiveMs);
     const headers = new Headers(currentInit.headers);
     let method = (currentInit.method ?? "GET").toUpperCase();
     let body = currentInit.body;
@@ -614,6 +622,14 @@ async function guardedFetch(url, fetchOptions, ctxSignal, effectiveMs) {
       headers.delete("content-type");
       headers.delete("content-length");
     }
+    if (hasContent(body) && nextUrl.origin !== base.origin) {
+      throw new NodeError(
+        "BLOCKED_ADDRESS",
+        `Blocked ${redirectStatus} redirect to another origin: it would resend the request body to ${nextUrl.origin}`,
+        { status: 0 }
+      );
+    }
+    await guardUrl(nextUrl, ctxSignal, effectiveMs);
     if (nextUrl.origin !== base.origin) {
       for (const name of [...headers.keys()]) {
         if (!headerCrossesOrigin(name)) headers.delete(name);