@revenexx/integrations-node-sdk 1.9.0 → 1.9.1

package/dist/localized.d.ts

@@ -0,0 +1,15 @@
+import type { LocalizedString } from './types.js';
+/**
+ * Reduce a {@link LocalizedString} to a single plain string.
+ *
+ * Every consumer (the UI, the Laravel side) repeats the same "is it a
+ * string or a localized map?" branch to render a name/label; this centralizes
+ * it so the rules are defined once:
+ *
+ * - a plain string is trimmed and returned (or `undefined` if blank);
+ * - a localized map prefers `fallbackLang` (default `en`), then the first
+ *   non-empty value;
+ * - a missing, empty, or blank-only value yields `undefined`, so the caller
+ *   can apply its own fallback.
+ */
+export declare function normalizeLocalized(value: LocalizedString | undefined | null, fallbackLang?: string): string | undefined;

package/dist/manifest.d.ts

@@ -0,0 +1,83 @@
+import type { ICredential, ICredentialDescription, INode, INodeDescription, ITemplateDescription } from './types.js';
+/**
+ * Envelope version expected by the integrations server-side
+ * `TarballInspector`. Earlier (pre-registry) builds emitted a bare array
+ * without any `manifestVersion` field; `v0-draft` is currently the only
+ * accepted value (see `SchemaServiceProvider::DOMAIN_NODE` in the
+ * integrations service). Keeping it versioned lets the registry evolve the
+ * shape without breaking older publishers.
+ */
+export declare const MANIFEST_VERSION = "v0-draft";
+export interface NodeManifest {
+    manifestVersion: typeof MANIFEST_VERSION;
+    nodes: INodeDescription[];
+    /**
+     * Credential types this package publishes. Optional and additive: packages
+     * that ship no credentials omit it (older publishers never set it).
+     */
+    credentials?: ICredentialDescription[];
+    /**
+     * Workflow templates this package publishes. Optional and additive: packages
+     * that ship no templates omit it. Templates are plain data (no executable
+     * code), so they are carried verbatim from the package's `TEMPLATES` export.
+     */
+    templates?: ITemplateDescription[];
+}
+/**
+ * The registry-relevant fields of a node package's `package.json`, as read by
+ * the CLI. `name`/`version` identify the package; `displayName` is the
+ * human-readable bundle label shown in the editor's node palette (e.g.
+ * „Business Central"); `icon` marks its folder there. All four are read straight
+ * from `package.json` by the integrations server on upload — the CLI reads them
+ * only to warn about a missing label, to annotate the manifest log line, and to
+ * stop on an icon the server would refuse.
+ *
+ * The label lives under a namespaced `revenexx` group in `package.json`
+ * (`{ "revenexx": { "displayName": "…" } }`), not a bespoke top-level key, so
+ * it can't collide with unrelated tooling that squats on `displayName`.
+ */
+export interface NodePackageMeta {
+    name: string;
+    version: string;
+    /** Human-readable bundle label (e.g. „Business Central"); optional. */
+    displayName?: string;
+    /**
+     * The glyph that marks the package's folder in the studio's palette, as
+     * `lucide:<kebab-name>` (e.g. `lucide:bell`); optional. Declared by a package
+     * holding several services, which has no one vendor logo to mark its folder
+     * with — a package that is one vendor leaves it out. Trimmed, and a value that
+     * is not a string counts as none, as the server reads it; whether it is well
+     * formed is {@link packageIconProblem}'s question.
+     */
+    icon?: string;
+}
+/**
+ * Why a declared `revenexx.icon` would be refused by the registry, or
+ * `undefined` when it is fine (or absent). Lets the build stop where the author
+ * can still fix it, rather than at upload. Takes the icon as
+ * {@link parsePackageMeta} returns it — trimmed as the registry trims it; an
+ * untrimmed raw value can be refused here although the registry accepts it.
+ */
+export declare function packageIconProblem(icon: string | undefined): string | undefined;
+/**
+ * Extracts {@link NodePackageMeta} from parsed `package.json` contents, keeping
+ * only the registry-relevant fields and coercing anything malformed to a safe
+ * shape. All four fields are trimmed — the icon of ASCII whitespace only, as the
+ * server's PHP `trim()` does, so a pasted no-break space is refused here as it
+ * is there rather than trimmed away; a blank or whitespace-only value becomes
+ * `''` (`name`/`version`) or `undefined` (`displayName`, `icon`, matching how the
+ * server treats them), so whitespace can't masquerade as a present value in
+ * tooling. The bundle label and the folder icon are read from the `revenexx`
+ * group (`revenexx.displayName`, `revenexx.icon`).
+ * Does not validate that `name`/`version` are present — the integrations server
+ * enforces that on upload; this is a typed, lenient read for tooling.
+ */
+export declare function parsePackageMeta(raw: unknown): NodePackageMeta;
+/**
+ * Builds the manifest envelope from a package's `NODES` (and optional
+ * `CREDENTIALS` / `TEMPLATES`) exports. The result is what gets written to
+ * `dist/manifest.json` and uploaded to the registry inside the tarball. The
+ * bundle label is NOT carried here — the integrations server reads it straight
+ * from `package.json` (`revenexx.displayName`).
+ */
+export declare function buildManifest(nodes: INode[], credentials?: ICredential[], templates?: ITemplateDescription[]): NodeManifest;

package/dist/nodeErrors.d.ts

@@ -0,0 +1,61 @@
+import type { INodeResult, IOutputPort } from './types.js';
+/**
+ * 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).
+ */
+export 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.
+ */
+export declare function toErrorOutput(err: unknown): NodeErrorOutput;
+/** Wrap an error output into an `INodeResult` routed to the `error` port. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function errorPort(opts?: {
+    body?: boolean;
+}): IOutputPort;

package/dist/operators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The comparison vocabulary, in one place because it is read in three:
+ * a node that compares two values (a condition, a filter), a settings condition
+ * saying when a field applies (`IConfigField.showIf`), and the editor drawing
+ * that field. An author who has met these words in one of the three must not
+ * have to learn a second set for the others.
+ *
+ * The names are the vocabulary; what each one *means* is {@link evaluate}, and
+ * the answer table in `operators.test.ts` is what a second implementation of it
+ * — the editor, the platform's workflow validator — is checked against.
+ */
+export declare const OPERATORS: readonly ['equals', 'notEquals', 'contains', 'notContains', 'startsWith', 'endsWith', 'greaterThan', 'greaterThanOrEqual', 'lessThan', 'lessThanOrEqual', 'exists', 'notExists', 'isEmpty', 'isNotEmpty'];
+export type Operator = (typeof OPERATORS)[number];
+/** The four that read whether a value is there rather than what it is. */
+export declare const VALUELESS_OPERATORS: readonly Operator[];
+export declare function isOperator(value: unknown): value is Operator;
+/** Whether an operator reads a second value at all, or only the first. */
+export declare function takesValue(op: Operator): boolean;
+/**
+ * What an operator means.
+ *
+ * Equality is deliberately lenient across the string/number line: a `select`
+ * carries `1` where a text box carries `'1'`, and an author means one thing by
+ * both. A second implementation has to reproduce that — and has to be careful
+ * with booleans, whose default stringification differs between languages.
+ */
+export declare function evaluate(left: unknown, op: Operator, right: unknown): boolean;

package/dist/retry.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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". */
+export 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;
+    });
+}
+export 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;
+}
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, policy: Partial<RetryPolicy>, hooks: RetryHooks): Promise<T>;

package/dist/ssrf.d.ts

@@ -0,0 +1,88 @@
+import { NodeError } from './errors.js';
+/**
+ * A resolved DNS address, mirroring the shape of Node's `dns.LookupAddress`.
+ * `family` is `4` or `6`; only `address` is consulted by the guard.
+ */
+export interface LookupAddress {
+    address: string;
+    family: number;
+}
+/**
+ * Resolves a hostname to every address it maps to. Modelled on
+ * `dns.lookup(host, { all: true })`. Injectable so tests can drive the guard
+ * deterministically without real DNS — see {@link ssrfResolver}.
+ */
+export type LookupFn = (hostname: string) => Promise<LookupAddress[]>;
+/**
+ * The DNS resolver the SSRF guard uses when a caller does not pass an explicit
+ * `lookup`. It is a mutable holder (rather than a bare function) purely so tests
+ * can swap `ssrfResolver.lookup` via a spy and restore it afterwards — the guard
+ * itself always runs. **Do not repoint this in production.**
+ */
+export declare const ssrfResolver: {
+    lookup: LookupFn;
+};
+/**
+ * Return `true` when `ip` (a literal IPv4/IPv6 address) points at a private,
+ * loopback, link-local, carrier-grade NAT, multicast, broadcast, reserved,
+ * unallocated or otherwise non-public target that a server-side fetch must never be
+ * steered to.
+ *
+ * The verdict is an allow-list: the address is refused unless the classification
+ * calls its range public unicast and — for IPv6, where that verdict is a default
+ * rather than a determination — it also sits inside the block IANA has allocated
+ * (see {@link GLOBAL_UNICAST_V6}). The IPv6 forms that embed an IPv4 address are
+ * unwrapped and the embedded address judged in its place, so a public host stays
+ * reachable when it is written that way. An address we cannot parse is treated as
+ * blocked (fail-closed).
+ *
+ * Promised behaviour: specs/ssrf-guard.md (AC-9, AC-11, AC-19).
+ */
+export declare function isBlockedAddress(ip: string): boolean;
+/**
+ * Put `url`'s host **and port** under the connect-time guard and return the
+ * release for it. Ref-counted, so concurrent calls to one target do not release
+ * each other. Host and port together are as narrow as the scope can be made: the
+ * `connected` message carries the target and not the caller, so this says which
+ * connections are *candidates* for judgement, never which one is ours.
+ *
+ * The window is the call, not the connection. A connect that completes after the
+ * release — the fetch it belonged to having already timed out or aborted — finds
+ * its target unregistered and is not judged; see the gap in
+ * `specs/ssrf-guard.md`.
+ *
+ * Deliberately **not** re-exported from `index.ts`. The guard is engaged by
+ * `safeFetch`, which is the one sanctioned way out to the network (PO-185); an
+ * exported handle would be a second one, and one that is easy to hold wrongly —
+ * the judgement it enables lasts exactly as long as the registration does.
+ */
+export declare function guardConnectionsTo(url: URL): () => void;
+/**
+ * The refusal this guard raised on a socket, as it comes back out of `fetch`.
+ * undici reports a destroyed connection as `TypeError('fetch failed')` carrying
+ * the destroy reason as its `cause`, so the caller sees a generic network
+ * failure — which `safeFetch` would then *retry*. Unwrap it, so a blocked target
+ * surfaces as the deterministic `BLOCKED_ADDRESS` it is.
+ */
+export declare function connectionRefusal(err: unknown): NodeError | undefined;
+/**
+ * Assert that `url` is safe for a server-side fetch: an http(s) URL whose target
+ * resolves only to public addresses. Rejects non-http(s) protocols, empty hosts
+ * and `localhost`, checks literal-IP hosts directly, and otherwise resolves the
+ * hostname (via the injectable `lookup`, defaulting to {@link ssrfResolver}) and
+ * rejects if **any** resolved address is private/reserved. Throws
+ * `NodeError('BLOCKED_ADDRESS', …, { status: 0 })` on rejection.
+ *
+ * This is the pre-flight half of the guard: the connection that follows resolves
+ * the name again on its own, so `safeFetch` also judges the address the socket
+ * actually reached (PO-184). A caller that opens its own request after
+ * `assertPublicUrl` gets the check and not that second half.
+ *
+ * Pass `signal` (the per-request timeout/cancellation budget) so a hung or
+ * hostile DNS resolve cannot block the guard past that budget — see
+ * {@link resolveHost}.
+ */
+export declare function assertPublicUrl(url: string | URL, opts?: {
+    lookup?: LookupFn;
+    signal?: AbortSignal;
+}): Promise<void>;