@revenexx/integrations-node-sdk 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,467 @@
+type LocalizedString = string | Record<string, string>;
+type DataType = 'any' | 'object' | 'array' | 'string' | 'number' | 'boolean';
+type OutputKind = 'default' | 'branch' | 'error';
+type NodeCategory = 'trigger' | 'action' | 'transform' | 'control' | 'io';
+type ConfigType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref';
+interface IInputPort {
+    dataType: DataType;
+    required?: boolean;
+    description?: LocalizedString;
+}
+interface IOutputField {
+    dataType: DataType;
+    description?: LocalizedString;
+}
+interface IOutputPort {
+    kind: OutputKind;
+    dataType: DataType;
+    name?: string;
+    label?: LocalizedString;
+    description?: LocalizedString;
+    fields?: Record<string, IOutputField>;
+    sourceFromConfig?: string;
+    fallback?: {
+        name: string;
+        label?: LocalizedString;
+        description?: LocalizedString;
+    };
+}
+interface IConfigOption {
+    value: string | number | boolean;
+    label: LocalizedString;
+}
+interface IConfigValidation {
+    pattern?: string;
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+}
+interface IConfigFieldBase {
+    key: string;
+    label: LocalizedString;
+    type: ConfigType;
+    description?: LocalizedString;
+    required?: boolean;
+    default?: unknown;
+    placeholder?: LocalizedString;
+    expressionAllowed?: boolean;
+    multiline?: boolean;
+    validation?: IConfigValidation;
+    options?: IConfigOption[];
+    /**
+     * Only meaningful when `type === 'credentials-ref'`: the namespaced slug(s) of
+     * the credential type(s) this field accepts (e.g. `revenexx:smtp`). The editor
+     * lists tenant credential instances of these type(s); the blob stores the
+     * chosen instance UUID. Pass a single string when only one type is accepted,
+     * or an array to let the field accept instances of any of several types (e.g.
+     * a node that works with both an OAuth and an API-token credential).
+     */
+    credentialType?: string | string[];
+}
+interface IConfigField extends IConfigFieldBase {
+    properties?: IConfigFieldBase[];
+    items?: IConfigFieldBase;
+}
+interface INodeDescription {
+    slug: string;
+    version: string;
+    category: NodeCategory;
+    name: LocalizedString;
+    description?: LocalizedString;
+    icon?: string;
+    inputs: Record<string, IInputPort>;
+    outputs: IOutputPort[];
+    config?: IConfigField[];
+}
+interface INodeContext {
+    signal: AbortSignal;
+    logger: {
+        info(message: string, meta?: Record<string, unknown>): void;
+        warn(message: string, meta?: Record<string, unknown>): void;
+        error(message: string, meta?: Record<string, unknown>): void;
+    };
+    secrets: {
+        get(key: string): Promise<string>;
+    };
+    /**
+     * Resolve the access data of a credential instance the node references via a
+     * `credentials-ref` config field. The runtime fulfils this from the
+     * credentials broker at execution time (inside the Temporal activity), so the
+     * returned value — e.g. a short-lived access token — is always current and
+     * never persisted into workflow history.
+     */
+    credentials: {
+        get(credentialsId: string): Promise<Record<string, unknown>>;
+    };
+}
+interface INodeResult {
+    outputs: Record<string, unknown>;
+    branch?: string;
+}
+interface INode {
+    description: INodeDescription;
+    execute(ctx: INodeContext, inputs: Record<string, unknown>): Promise<INodeResult>;
+}
+/**
+ * Optional capability interface for nodes that iterate over a collection.
+ * Implement this alongside {@link INode} to signal to the worker that this
+ * node drives iteration — the worker will call {@link extractItems} instead
+ * of relying on slug-based detection.
+ *
+ * This interface is the designated dispatch point for future child-workflow
+ * execution: once per-iteration isolation is needed, the worker can swap the
+ * inline loop for `executeChild` calls without any changes to the node or SDK.
+ */
+interface INodeWithIteration {
+    /**
+     * Extracts the array of items to iterate over from the resolved inputs and
+     * config. Must be pure and synchronous — it runs inside a Temporal Activity.
+     */
+    extractItems(inputs: Record<string, unknown>, config: Record<string, unknown>): unknown[];
+}
+/**
+ * Type guard that checks whether a node implements {@link INodeWithIteration}.
+ */
+declare function isNodeWithIteration(node: INode): node is INode & INodeWithIteration;
+/**
+ * The authentication strategy a credential type uses. Determines which SDK
+ * base class a concrete credential extends and how the broker resolves it.
+ */
+type CredentialAuthKind = 'static' | 'api-key' | 'basic' | 'oauth2-client-credentials' | 'oauth2-authcode';
+/**
+ * Field types for the connection parameters a credential type declares. A
+ * superset-subset of {@link ConfigType}: scalars plus `secret` for values that
+ * must be masked in the UI and never returned in plaintext by the public API.
+ */
+type CredentialFieldType = 'string' | 'number' | 'boolean' | 'select' | 'secret';
+interface ICredentialField {
+    key: string;
+    label: LocalizedString;
+    type: CredentialFieldType;
+    description?: LocalizedString;
+    required?: boolean;
+    default?: unknown;
+    placeholder?: LocalizedString;
+    validation?: IConfigValidation;
+    options?: IConfigOption[];
+}
+/**
+ * The published contract of a credential type: how the editor renders its
+ * config form and which auth strategy the broker applies. The imperative
+ * `test`/`resolve` logic lives in the bundled {@link ICredential} code, not in
+ * this description.
+ */
+interface ICredentialDescription {
+    /** Stable namespaced identifier `<namespace>:<slug>` (e.g. `revenexx:smtp`). */
+    slug: string;
+    version: string;
+    name: LocalizedString;
+    description?: LocalizedString;
+    icon?: string;
+    authKind: CredentialAuthKind;
+    fields: ICredentialField[];
+}
+/**
+ * Runtime context handed to a credential's `test`/`resolve`. Runs in the
+ * credentials broker (a Node side-container), never in workflow code.
+ */
+interface ICredentialContext {
+    signal: AbortSignal;
+    logger: {
+        info(message: string, meta?: Record<string, unknown>): void;
+        warn(message: string, meta?: Record<string, unknown>): void;
+        error(message: string, meta?: Record<string, unknown>): void;
+    };
+    /**
+     * Persist updated durable credentials (e.g. a rotated `refresh_token`) back
+     * to storage. The broker wires this to `PATCH /v1/internal/credentials/{id}/durable-creds`.
+     * Absent during pre-save tests where no instance exists yet.
+     */
+    persistDurableCreds?(durableCreds: Record<string, unknown>): Promise<void>;
+}
+interface ICredentialTestResult {
+    ok: boolean;
+    message?: string;
+}
+interface ICredentialResolveResult {
+    /** The access data handed to the node (e.g. `{ host, port, user, password }` or `{ accessToken }`). */
+    credentials: Record<string, unknown>;
+    /** ISO-8601 expiry of the resolved access data; absent for non-expiring (static) credentials. */
+    expiresAt?: string;
+}
+/**
+ * A credential type implementation. `config` is the validated, user-entered
+ * field map; `durableCreds` holds system-managed long-lived secrets (e.g. a
+ * `refresh_token` obtained via 3-legged OAuth) and is `null` until they exist.
+ */
+interface ICredential {
+    description: ICredentialDescription;
+    test(ctx: ICredentialContext, config: Record<string, unknown>): Promise<ICredentialTestResult>;
+    resolve(ctx: ICredentialContext, config: Record<string, unknown>, durableCreds: Record<string, unknown> | null): Promise<ICredentialResolveResult>;
+}
+/**
+ * Optional capability for `oauth2-authcode` credentials that need the
+ * interactive (3-legged) consent dance. The broker exposes these via
+ * `/oauth/authorize-url` and `/oauth/exchange-code`; Laravel proxies them.
+ */
+interface ICredentialOAuthAuthorize {
+    buildAuthorizeUrl(ctx: ICredentialContext, config: Record<string, unknown>, params: {
+        redirectUri: string;
+        state: string;
+    }): Promise<{
+        authorizeUrl: string;
+        codeVerifier?: string;
+    }>;
+    exchangeCode(ctx: ICredentialContext, config: Record<string, unknown>, params: {
+        code: string;
+        redirectUri: string;
+        codeVerifier?: string;
+    }): Promise<{
+        durableCreds: Record<string, unknown>;
+    }>;
+}
+/**
+ * Type guard for credentials that implement the 3-legged OAuth consent flow.
+ */
+declare function isOAuthAuthorizeCredential(credential: ICredential): credential is ICredential & ICredentialOAuthAuthorize;
+/** Difficulty level surfaced in the template gallery. */
+type TemplateLevel = 'beginner' | 'intermediate' | 'advanced';
+/** Trigger kind a template can ship; mirrors the server's `TriggerType`. */
+type TemplateTriggerType = 'manual' | 'schedule' | 'webhook' | 'event';
+/**
+ * A trigger a template instantiates alongside its workflow. The `handle` is a
+ * stable UUID the workflow blob's edges reference via `from.nodeId`. Per-type
+ * `config` shapes: `schedule` → `{ cron, timezone? }`, `webhook` →
+ * `{ method, secretRef?, public? }`, `event` → `{ subject }`, `manual` → none.
+ * The integrations server deep-validates `config` per `type` on publish.
+ */
+interface ITemplateTrigger {
+    /** Stable UUID the blob's edges reference via `from.nodeId`. */
+    handle: string;
+    type: TemplateTriggerType;
+    name?: string;
+    config?: Record<string, unknown>;
+    active?: boolean;
+}
+/**
+ * A workflow template a node package publishes: a ready-made workflow blueprint
+ * the editor offers as a starting point. Unlike {@link INode}/{@link ICredential}
+ * a template carries no executable code — it is plain data, so a package exports
+ * its `ITemplateDescription`s directly (no class wrapper).
+ *
+ * The `definition` is a workflow blob authored against the workflow-blob grammar
+ * named by `blobVersion`; the integrations server validates it on publish.
+ */
+interface ITemplateDescription {
+    /** Stable namespaced identifier `<namespace>:<slug>` (e.g. `revenexx:slack-to-crm`). */
+    slug: string;
+    version: string;
+    /** Free-form grouping label shown in the gallery (e.g. `sales`). */
+    category: string;
+    level: TemplateLevel;
+    name: LocalizedString;
+    /** One-line summary shown on the template card. */
+    shortDescription?: LocalizedString;
+    /** Long-form description in Markdown. */
+    description?: LocalizedString;
+    icon?: string;
+    /** Free-form industry tags (e.g. `any`, `medical`). */
+    industries?: string[];
+    /** Free-form vendor tags (e.g. `pipedrive`, `slack`). */
+    vendors?: string[];
+    /** Workflow-blob schema version `definition` targets (e.g. `v0-draft`). */
+    blobVersion: string;
+    /** The workflow blob instantiated when a user picks this template. */
+    definition: Record<string, unknown>;
+    /**
+     * Triggers instantiated alongside the workflow (their `handle`s are
+     * referenced by `definition`'s edges). Omit for a manual-only template.
+     */
+    triggers?: ITemplateTrigger[];
+}
+
+/**
+ * Reduce a {@link LocalizedString} to a single plain string.
+ *
+ * Every consumer (worker, 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.
+ */
+declare function normalizeLocalized(value: LocalizedString | undefined | null, fallbackLang?: string): string | undefined;
+
+/**
+ * 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 worker that resolves the chosen
+ * instance, 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.
+ */
+declare function normalizeCredentialType(value: string | string[] | undefined): string[];
+
+declare function extractManifest(node: INode): INodeDescription;
+declare function extractManifests(nodes: INode[]): INodeDescription[];
+declare function extractCredentialManifest(credential: ICredential): ICredentialDescription;
+declare function extractCredentialManifests(credentials: ICredential[]): ICredentialDescription[];
+
+/**
+ * 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.
+ */
+declare const MANIFEST_VERSION = "v0-draft";
+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[];
+}
+/**
+ * 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.
+ */
+declare function buildManifest(nodes: INode[], credentials?: ICredential[], templates?: ITemplateDescription[]): NodeManifest;
+
+/**
+ * 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;
+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.
+ */
+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. */
+    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.
+ */
+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.
+ */
+declare abstract class ApiKeyCredential extends BaseCredential {
+    protected apiKeyField(): string;
+    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.
+ */
+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.
+ */
+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.
+ */
+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>;
+}
+
+declare class NodeError extends Error {
+    readonly code: string;
+    readonly meta?: Record<string, unknown>;
+    constructor(code: string, message: string, meta?: Record<string, unknown>);
+}
+
+export { ApiKeyCredential, BaseCredential, BasicAuthCredential, type ConfigType, type CredentialAuthKind, type CredentialFieldType, 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 IInputPort, type INode, type INodeContext, type INodeDescription, type INodeResult, type INodeWithIteration, type IOutputField, type IOutputPort, type ITemplateDescription, type ITemplateTrigger, type LocalizedString, MANIFEST_VERSION, type NodeCategory, NodeError, type NodeManifest, OAuth2AuthCodeCredential, OAuth2ClientCredentialsCredential, type OAuthTokenResponse, type OutputKind, SimpleValueCredential, type TemplateLevel, type TemplateTriggerType, buildManifest, extractCredentialManifest, extractCredentialManifests, extractManifest, extractManifests, isNodeWithIteration, isOAuthAuthorizeCredential, normalizeCredentialType, normalizeLocalized };