@objectstack/service-automation 7.3.0 → 7.4.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { FlowNodeParsed, FlowParsed, ExecutionLog } from '@objectstack/spec/automation';
-import { IAutomationService, Logger, AutomationContext, AutomationResult } from '@objectstack/spec/contracts';
+import { ActionDescriptor, FlowNodeParsed, FlowParsed, ExecutionLog } from '@objectstack/spec/automation';
+import { IAutomationService, Logger, AutomationContext, ScreenSpec, AutomationResult, ResumeSignal } from '@objectstack/spec/contracts';
+import { Connector } from '@objectstack/spec/integration';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -8,8 +9,15 @@ import { Plugin, PluginContext } from '@objectstack/core';
  * it with the engine to extend automation capabilities.
  */
 interface NodeExecutor {
-    /** Corresponds to FlowNodeAction enum value */
+    /** Registry node type (built-in id or plugin-defined) */
     readonly type: string;
+    /**
+     * Optional ADR-0018 action descriptor. When present, it is published into
+     * the engine's action registry and surfaced via {@link AutomationEngine.getActionDescriptors}
+     * — feeding flow validation and the designer palette. Plugins SHOULD publish
+     * one so their node appears in the palette and validates as a legal flow node.
+     */
+    readonly descriptor?: ActionDescriptor;
     /**
      * Execute a node
      * @param node - Current node definition
@@ -25,15 +33,127 @@ interface NodeExecutionResult {
     error?: string;
     /** Used by decision nodes — returns the selected branch label */
     branchLabel?: string;
+    /**
+     * ADR-0019 durable pause. When `true`, the node has done its on-entry work
+     * (e.g. opened an approval request) and the run should **suspend** here: the
+     * engine persists a continuation, stops traversal, and `execute()` returns
+     * `{ status: 'paused', runId }`. The run is continued later via
+     * {@link AutomationEngine.resume}. Any `output` is written to variables
+     * before suspending. The node reads its own run id from the `$runId`
+     * flow variable so it can map the run to external state.
+     */
+    suspend?: boolean;
+    /**
+     * Optional correlation key surfaced on the suspended-run record (e.g. an
+     * approval request id). For observability / lookup; not required to resume.
+     */
+    correlation?: string;
+    /**
+     * Screen to render — set by a `screen` node that suspends to collect input.
+     * Surfaced on the paused {@link AutomationResult} so a UI runner can render
+     * the form and `resume()` with the values.
+     */
+    screen?: ScreenSpec;
+}
+/**
+ * A normalized description of *what* fires a flow, derived by the engine from
+ * the flow's `start` node and handed to the matching {@link FlowTrigger} when a
+ * flow is activated. Concrete triggers (record-change, schedule, …) read the
+ * fields they care about and ignore the rest.
+ *
+ * The engine — not the trigger — owns parsing the start node, so trigger
+ * plugins stay decoupled from flow-definition internals (mirrors how
+ * `connector_action` keeps connectors decoupled from node config).
+ */
+interface FlowTriggerBinding {
+    /** Flow this binding activates. */
+    readonly flowName: string;
+    /** record-change: the object whose mutations fire the flow. */
+    readonly object?: string;
+    /** record-change: the start node's `triggerType` (e.g. 'record-after-update'). */
+    readonly event?: string;
+    /**
+     * Optional trigger predicate copied from the start node's `condition`. The
+     * engine evaluates it before running the flow; triggers may ignore it.
+     */
+    readonly condition?: string | {
+        dialect?: string;
+        source?: string;
+        ast?: unknown;
+    };
+    /** schedule: cron/interval descriptor (parsed but not yet acted on here). */
+    readonly schedule?: unknown;
+    /** The raw start-node `config`, for trigger-specific fields not modeled above. */
+    readonly config?: Record<string, unknown>;
 }
 /**
  * Trigger interface. Schedule/Event/API triggers are registered via plugins.
+ *
+ * The engine completes the wiring: when a flow whose start node maps to this
+ * trigger's {@link type} is registered (or when this trigger is registered
+ * after such flows already exist), the engine calls {@link start} with the
+ * parsed {@link FlowTriggerBinding} and a `callback` that runs the flow. The
+ * trigger subscribes to its event source (e.g. an ObjectQL lifecycle hook) and
+ * invokes `callback(ctx)` when it fires. {@link stop} tears that subscription
+ * down when the flow is unregistered/disabled or the trigger is removed.
  */
 interface FlowTrigger {
     readonly type: string;
-    start(flowName: string, callback: (ctx: AutomationContext) => Promise<void>): void;
+    start(binding: FlowTriggerBinding, callback: (ctx: AutomationContext) => Promise<void>): void;
     stop(flowName: string): void;
 }
+/**
+ * Context handed to a connector action handler. Carries the live flow variable
+ * map and the trigger context so a handler can read prior-node output, plus a
+ * logger. The platform ships the registry + the `connector_action` dispatch
+ * node (baseline, ADR-0018 §Addendum); *concrete* connectors — `connector-rest`,
+ * `connector-slack`, … — are plugins that register handlers here.
+ */
+interface ConnectorActionContext {
+    readonly variables: Map<string, unknown>;
+    readonly automation: AutomationContext;
+    readonly logger: Logger;
+}
+/**
+ * A handler for one connector action. Receives the (already-resolved) input
+ * mapped from the flow node and returns the action's output, which the
+ * `connector_action` node writes back into flow variables.
+ */
+type ConnectorActionHandler = (input: Record<string, unknown>, ctx: ConnectorActionContext) => Promise<Record<string, unknown>>;
+/**
+ * A connector registered on the engine: its validated {@link Connector}
+ * definition plus the handler for each action it declares.
+ */
+interface RegisteredConnector {
+    readonly def: Connector;
+    readonly handlers: Record<string, ConnectorActionHandler>;
+}
+/**
+ * A designer-facing view of one connector action — identity + its JSON-Schema
+ * input/output. The runtime handler is intentionally omitted; this is metadata.
+ */
+interface ConnectorActionDescriptor {
+    readonly key: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly inputSchema?: Record<string, unknown>;
+    readonly outputSchema?: Record<string, unknown>;
+}
+/**
+ * A designer-facing descriptor for a registered connector: its identity plus
+ * the actions it exposes. Served by `GET /api/v1/automation/connectors` so the
+ * flow designer can populate the `connector_action` node's connector → action
+ * → input pickers (ADR-0018 §Addendum, ADR-0022). Mirrors `ActionDescriptor`'s
+ * role for node types, but for the connector registry.
+ */
+interface ConnectorDescriptor {
+    readonly name: string;
+    readonly label: string;
+    readonly type: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly actions: ConnectorActionDescriptor[];
+}
 /**
  * Internal execution step log entry.
  */
@@ -78,11 +198,22 @@ declare class AutomationEngine implements IAutomationService {
     private flowEnabled;
     private flowVersionHistory;
     private nodeExecutors;
+    private actionDescriptors;
     private triggers;
+    /**
+     * Flows currently wired to a trigger, keyed by flow name → the trigger
+     * `type` that owns the binding. Used to avoid double-binding and to know
+     * which trigger to `stop()` when a flow is unregistered/disabled.
+     */
+    private boundFlowTriggers;
+    /** Connectors registered by integration plugins, keyed by connector name (ADR-0018 §Addendum). */
+    private connectors;
     private executionLogs;
     private maxLogSize;
     private logger;
     private runCounter;
+    /** Runs paused at a node, keyed by runId (ADR-0019). In-memory, see {@link SuspendedRun}. */
+    private suspendedRuns;
     constructor(logger: Logger);
     /** Register a node executor (called by plugins) */
     registerNodeExecutor(executor: NodeExecutor): void;
@@ -92,8 +223,63 @@ declare class AutomationEngine implements IAutomationService {
     registerTrigger(trigger: FlowTrigger): void;
     /** Unregister a trigger (hot-unplug) */
     unregisterTrigger(type: string): void;
+    /**
+     * Derive a flow's trigger binding from its `start` node, or `undefined` if
+     * the flow has no auto-trigger (manual / screen / api). The convention —
+     * established by the showcase flows — is that the start node carries the
+     * trigger details in its `config`: `{ objectName, triggerType, condition }`
+     * for record-change, or a `schedule` descriptor for time-based flows.
+     */
+    private resolveTriggerBinding;
+    /**
+     * Bind a flow to its matching registered trigger (idempotent). No-op when
+     * the flow has no trigger binding or no trigger is registered for its type
+     * yet — {@link registerTrigger} re-attempts activation when one arrives.
+     */
+    private activateFlowTrigger;
+    /** Unbind a flow from its trigger, if bound. */
+    private deactivateFlowTrigger;
+    /** Active flow→trigger bindings (observability / tests). */
+    getActiveTriggerBindings(): Array<{
+        flowName: string;
+        triggerType: string;
+    }>;
+    /**
+     * Register a connector (called by integration plugins, ADR-0018 §Addendum).
+     * Validates the definition against {@link ConnectorSchema} and asserts every
+     * declared action has a handler, so a half-wired connector fails loudly at
+     * registration rather than silently at dispatch. Re-registering the same
+     * name replaces (mirrors {@link registerNodeExecutor}).
+     */
+    registerConnector(def: Connector, handlers: Record<string, ConnectorActionHandler>): void;
+    /** Unregister a connector (hot-unplug). */
+    unregisterConnector(name: string): void;
+    /**
+     * Resolve the handler for a connector action, used by the baseline
+     * `connector_action` node. Returns `undefined` when the connector or action
+     * is not registered, so the node can fail the step with a clear error.
+     */
+    resolveConnectorAction(connectorId: string, actionId: string): ConnectorActionHandler | undefined;
+    /** Get all registered connector names. */
+    getRegisteredConnectors(): string[];
+    /**
+     * Get a designer-facing descriptor for every registered connector — its
+     * identity plus the actions it exposes (input/output JSON Schema). Backs
+     * `GET /api/v1/automation/connectors` so the designer can fill the
+     * `connector_action` node's connector / action / input pickers (ADR-0022).
+     * Handlers are omitted — they are runtime code, not metadata.
+     */
+    getConnectorDescriptors(): ConnectorDescriptor[];
     /** Get all registered node types */
     getRegisteredNodeTypes(): string[];
+    /**
+     * Get all published action descriptors (ADR-0018). Backs both flow
+     * validation and the designer palette (`GET /api/v1/automation/actions`).
+     * Only executors that published a descriptor appear here.
+     */
+    getActionDescriptors(): ActionDescriptor[];
+    /** Get the action descriptor for a single node type, if published. */
+    getActionDescriptor(type: string): ActionDescriptor | undefined;
     /** Get all registered trigger types */
     getRegisteredTriggerTypes(): string[];
     registerFlow(name: string, definition: unknown): void;
@@ -115,7 +301,41 @@ declare class AutomationEngine implements IAutomationService {
     }): Promise<ExecutionLogEntry[]>;
     getRun(runId: string): Promise<ExecutionLogEntry | null>;
     execute(flowName: string, context?: AutomationContext): Promise<AutomationResult>;
+    /**
+     * Resume a run suspended at a node (ADR-0019 durable pause). Restores the
+     * snapshotted variables, merges `signal.output` under the suspended node's
+     * id, and continues traversal from that node's out-edges — optionally
+     * restricted to the edge labelled `signal.branchLabel` (e.g. the approval
+     * decision). The continuation may itself suspend again, in which case this
+     * returns `{ status: 'paused', runId }` afresh.
+     */
+    resume(runId: string, signal?: ResumeSignal): Promise<AutomationResult>;
+    /**
+     * List the runs currently suspended awaiting {@link resume} (ADR-0019).
+     * Backs operability surfaces such as a "pending approvals" view.
+     */
+    listSuspendedRuns(): Array<{
+        runId: string;
+        flowName: string;
+        nodeId: string;
+        correlation?: string;
+    }>;
+    /**
+     * The screen a paused run is currently waiting on (screen-flow runtime), or
+     * `null` if the run isn't suspended / didn't pause at a screen node. Lets a
+     * UI flow-runner re-fetch the form after a refresh.
+     */
+    getSuspendedScreen(runId: string): ScreenSpec | null;
     private recordLog;
+    /**
+     * Validate each node's `type` against the live action registry (ADR-0018).
+     * A type is known if it is structural (start/end), has a registered
+     * executor, or has a published action descriptor. Unknown types are
+     * warned about (not rejected) so flows authored against a temporarily
+     * absent plugin still register; the runtime surfaces a hard NO_EXECUTOR
+     * error if such a node is actually executed.
+     */
+    private validateNodeTypes;
     /**
      * Detect cycles in the flow graph (DAG validation).
      * Uses DFS with coloring (white/gray/black) to detect back edges.
@@ -135,6 +355,17 @@ declare class AutomationEngine implements IAutomationService {
      * Execute a node with timeout support, fault edge handling, and step logging.
      */
     private executeNode;
+    /**
+     * Traverse a node's out-edges and execute its successors. Split out of
+     * {@link executeNode} so {@link resume} can re-enter traversal from a
+     * suspended node without re-running the node body.
+     *
+     * @param branchLabel - When set (e.g. from a resume signal), restrict
+     *   traversal to out-edges whose `label` matches — this is how an Approval
+     *   node's `approve`/`reject` decision selects its downstream branch. When
+     *   no edge carries the label, traversal falls back to the normal edge set.
+     */
+    private traverseNext;
     /**
      * Execute a promise with timeout using Promise.race.
      */
@@ -176,14 +407,17 @@ interface AutomationServicePluginOptions {
  * AutomationServicePlugin — Core engine plugin
  *
  * Responsibilities:
- * 1. init phase: Create engine instance, register as 'automation' service
- * 2. start phase: Trigger 'automation:ready' hook for node plugin registration,
- *    then pull flow definitions from the ObjectQL schema registry and register
- *    them with the engine.
+ * 1. init phase: Create engine instance, register as 'automation' service, and
+ *    seed the platform's built-in node executors (logic / CRUD / screen-script /
+ *    http_request) via {@link installBuiltinNodes}. Per ADR-0018, foundational
+ *    capabilities are built into the core, not packaged as optional plugins.
+ * 2. start phase: Trigger 'automation:ready' hook so third-party plugins can
+ *    register additional node types, then pull flow definitions from the
+ *    ObjectQL schema registry and register them with the engine.
  * 3. destroy phase: Clean up resources
  *
- * Does NOT implement any specific nodes — nodes are registered by other plugins
- * via the engine's extension API.
+ * The engine's `registerNodeExecutor()` stays open so plugins extend the
+ * node/action vocabulary at runtime — the marketplace-extensibility contract.
  *
  * @example
  * ```ts
@@ -211,8 +445,21 @@ declare class AutomationServicePlugin implements Plugin {
 }
 
 /**
- * CRUD Node Plugin — wires `get_record` / `create_record` / `update_record` /
- * `delete_record` flow nodes to the runtime data layer (ObjectQL / IDataEngine).
+ * Logic built-in nodes — decision / assignment / loop.
+ *
+ * Part of the automation engine's foundational vocabulary, so the core
+ * {@link AutomationServicePlugin} seeds them directly (ADR-0018). These are NOT
+ * shipped as a separately installable plugin — "plugins are plugins; the
+ * platform's foundational capabilities are built in." Third-party node types
+ * are still registered via `engine.registerNodeExecutor()`.
+ */
+declare function registerLogicNodes(engine: AutomationEngine, ctx: PluginContext): void;
+
+/**
+ * CRUD built-in nodes — `get_record` / `create_record` / `update_record` /
+ * `delete_record`, wired to the runtime data layer (ObjectQL / IDataEngine).
+ * Part of the platform baseline, so the core {@link AutomationServicePlugin}
+ * seeds them directly (ADR-0018) rather than shipping a separate plugin.
  *
  * Each executor:
  *  1. Interpolates `{var}` / `{var.path}` / `{$User.*}` / `{NOW()}` tokens in
@@ -225,59 +472,88 @@ declare class AutomationServicePlugin implements Plugin {
  * If no data engine is registered, executors degrade to a no-op success so
  * test environments without ObjectQL still complete the flow without errors.
  */
-declare class CrudNodesPlugin implements Plugin {
-    name: string;
-    version: string;
-    type: "standard";
-    dependencies: string[];
-    init(ctx: PluginContext): Promise<void>;
-}
+declare function registerCrudNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
 /**
- * Logic Node Plugin — Provides decision / assignment / loop nodes
+ * Screen / Script built-in nodes — 'screen' and 'script' executors.
+ * Part of the core flow capability, so the {@link AutomationServicePlugin}
+ * seeds them directly (ADR-0018) rather than shipping a separate plugin.
  *
- * Dependencies: service-automation (engine)
+ * - 'screen' nodes collect user input. A screen that declares `config.fields`
+ *   (or sets `config.waitForInput === true`) suspends the run on entry via the
+ *   engine's durable pause (ADR-0019), surfacing a `ScreenSpec` for the client
+ *   to render; the run continues via `resume()` with the collected values (set
+ *   as bare flow variables). A field-less screen — or one with
+ *   `waitForInput === false` — stays a server pass-through (input vars, if any,
+ *   are already injected from `context.params`).
+ * - 'script' nodes dispatch by `config.actionType`. Currently only 'email'
+ *   has a (logger-backed) implementation; unknown action types still succeed
+ *   so flows can continue and downstream nodes can react.
  */
-declare class LogicNodesPlugin implements Plugin {
-    name: string;
-    version: string;
-    type: "standard";
-    dependencies: string[];
-    init(ctx: PluginContext): Promise<void>;
-}
+declare function registerScreenNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
 /**
- * HTTP + Connector Node Plugin — Provides http_request / connector_action nodes
+ * HTTP built-in node — `http_request` (foundational outbound I/O).
+ *
+ * Part of the platform baseline, so the core {@link AutomationServicePlugin}
+ * seeds it directly (ADR-0018). Its generic-dispatch sibling `connector_action`
+ * (see {@link ./connector-nodes.ts}) is now also baseline: where `http_request`
+ * calls a raw URL, `connector_action` invokes a registered connector's action,
+ * with concrete connectors contributed by plugins via `engine.registerConnector()`
+ * (ADR-0018 §Addendum).
  *
- * Dependencies: service-automation (engine)
+ * ADR-0018 §M3 target: route `http_request` through the service-messaging
+ * outbox (retry / idempotency / dead-letter) under the canonical `http` type.
+ * Today it is a bare `fetch()`.
  */
-declare class HttpConnectorPlugin implements Plugin {
-    name: string;
-    version: string;
-    type: "standard";
-    dependencies: string[];
-    init(ctx: PluginContext): Promise<void>;
-}
+declare function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
 /**
- * Screen / Script Node Plugin — Provides 'screen' and 'script' executors.
+ * Connector built-in node — `connector_action` (generic integration dispatch).
  *
- * - 'screen' nodes are pass-through on the server. The engine already injects
- *   `isInput: true` flow variables from `context.params` into the top-level
- *   variables map before execution begins, so screen nodes have no remaining
- *   server-side work.
- * - 'script' nodes dispatch by `config.actionType`. Currently only 'email'
- *   has a (logger-backed) implementation; unknown action types still succeed
- *   so flows can continue and downstream nodes can react.
+ * Part of the platform baseline alongside `http_request` (ADR-0018 §Addendum):
+ * where `http_request` calls *any raw URL*, `connector_action` invokes *any
+ * registered connector's action*. The platform ships the generic dispatch node
+ * + an (initially empty) connector registry on the engine; concrete connectors
+ * — `connector-rest`, `connector-slack`, `connector-salesforce`, … — populate
+ * the registry at runtime via `engine.registerConnector()`.
  *
- * Dependencies: service-automation (engine)
+ * Because the registry starts empty, a flow referencing a connector that no
+ * plugin has registered fails the *step* with a clear error rather than failing
+ * to register — graceful degradation matching `http_request`'s fail-soft style.
  */
-declare class ScreenNodesPlugin implements Plugin {
-    name: string;
-    version: string;
-    type: "standard";
-    dependencies: string[];
-    init(ctx: PluginContext): Promise<void>;
-}
+declare function registerConnectorNodes(engine: AutomationEngine, ctx: PluginContext): void;
+
+/**
+ * Built-in node executors — the automation engine's foundational vocabulary.
+ *
+ * Per ADR-0018 and the platform principle "plugins are plugins; the platform's
+ * foundational capabilities are built in," these node packs are seeded directly
+ * by the core {@link AutomationServicePlugin} rather than shipped as separately
+ * installable plugins. Each `register*Nodes(engine, ctx)` publishes its
+ * descriptors with `source: 'builtin'`.
+ *
+ * Scope (built-in baseline):
+ *  - logic   — decision / assignment / loop      (engine core)
+ *  - data    — get/create/update/delete_record   (platform CRUD baseline)
+ *  - human   — screen / script                   (core flow capability)
+ *  - io      — http_request                       (foundational outbound I/O)
+ *  - io      — connector_action                   (generic integration dispatch)
+ *  - io      — notify                              (outbound notification via messaging service)
+ *
+ * `connector_action` is the *generic dispatch* counterpart to `http_request`
+ * (ADR-0018 §Addendum): the platform ships the node + an (initially empty)
+ * connector registry on the engine, and *concrete* connectors populate it at
+ * runtime via `engine.registerConnector()`. Third-party node types continue to
+ * extend the vocabulary via `engine.registerNodeExecutor()`, keeping the action
+ * list open and marketplace-extensible.
+ */
+
+/**
+ * Seed every built-in node executor into the engine. Called by
+ * {@link AutomationServicePlugin.init} so a bare `new AutomationServicePlugin()`
+ * yields a fully-functional automation capability with no companion plugins.
+ */
+declare function installBuiltinNodes(engine: AutomationEngine, ctx: PluginContext): void;
 
-export { AutomationEngine, AutomationServicePlugin, type AutomationServicePluginOptions, CrudNodesPlugin, type FlowTrigger, HttpConnectorPlugin, LogicNodesPlugin, type NodeExecutionResult, type NodeExecutor, ScreenNodesPlugin };
+export { AutomationEngine, AutomationServicePlugin, type AutomationServicePluginOptions, type ConnectorActionContext, type ConnectorActionDescriptor, type ConnectorActionHandler, type ConnectorDescriptor, type FlowTrigger, type FlowTriggerBinding, type NodeExecutionResult, type NodeExecutor, type RegisteredConnector, installBuiltinNodes, registerConnectorNodes, registerCrudNodes, registerHttpNodes, registerLogicNodes, registerScreenNodes };