@objectstack/service-automation 3.0.7

package/dist/index.d.cts

@@ -0,0 +1,149 @@
+import { FlowNodeParsed } from '@objectstack/spec/automation';
+import { IAutomationService, Logger, AutomationContext, AutomationResult } from '@objectstack/spec/contracts';
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Each node type corresponds to a NodeExecutor.
+ * Third-party plugins only need to implement this interface and register
+ * it with the engine to extend automation capabilities.
+ */
+interface NodeExecutor {
+    /** Corresponds to FlowNodeAction enum value */
+    readonly type: string;
+    /**
+     * Execute a node
+     * @param node - Current node definition
+     * @param variables - Flow variable context (read/write)
+     * @param context - Trigger context
+     * @returns Execution result (may include output data, branch conditions, etc.)
+     */
+    execute(node: FlowNodeParsed, variables: Map<string, unknown>, context: AutomationContext): Promise<NodeExecutionResult>;
+}
+interface NodeExecutionResult {
+    success: boolean;
+    output?: Record<string, unknown>;
+    error?: string;
+    /** Used by decision nodes — returns the selected branch label */
+    branchLabel?: string;
+}
+/**
+ * Trigger interface. Schedule/Event/API triggers are registered via plugins.
+ */
+interface FlowTrigger {
+    readonly type: string;
+    start(flowName: string, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+}
+declare class AutomationEngine implements IAutomationService {
+    private flows;
+    private nodeExecutors;
+    private triggers;
+    private logger;
+    constructor(logger: Logger);
+    /** Register a node executor (called by plugins) */
+    registerNodeExecutor(executor: NodeExecutor): void;
+    /** Unregister a node executor (hot-unplug) */
+    unregisterNodeExecutor(type: string): void;
+    /** Register a trigger (called by plugins) */
+    registerTrigger(trigger: FlowTrigger): void;
+    /** Unregister a trigger (hot-unplug) */
+    unregisterTrigger(type: string): void;
+    /** Get all registered node types */
+    getRegisteredNodeTypes(): string[];
+    /** Get all registered trigger types */
+    getRegisteredTriggerTypes(): string[];
+    registerFlow(name: string, definition: unknown): void;
+    unregisterFlow(name: string): void;
+    listFlows(): Promise<string[]>;
+    execute(flowName: string, context?: AutomationContext): Promise<AutomationResult>;
+    private executeNode;
+    private evaluateCondition;
+    private retryExecution;
+}
+
+/**
+ * Configuration options for the AutomationServicePlugin.
+ */
+interface AutomationServicePluginOptions {
+    /** Enable debug logging for flow execution */
+    debug?: boolean;
+}
+/**
+ * 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
+ * 3. destroy phase: Clean up resources
+ *
+ * Does NOT implement any specific nodes — nodes are registered by other plugins
+ * via the engine's extension API.
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { AutomationServicePlugin } from '@objectstack/service-automation';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new AutomationServicePlugin());
+ * await kernel.bootstrap();
+ *
+ * const automation = kernel.getService('automation');
+ * ```
+ */
+declare class AutomationServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private engine?;
+    private readonly options;
+    constructor(options?: AutomationServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * CRUD Node Plugin — Provides get_record / create_record / update_record / delete_record
+ *
+ * Dependencies: service-automation (engine)
+ *
+ * In a full runtime environment these nodes would delegate to ObjectQL (data layer).
+ * This MVP implementation provides the extension point structure.
+ */
+declare class CrudNodesPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+/**
+ * Logic Node Plugin — Provides decision / assignment / loop nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+declare class LogicNodesPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+/**
+ * HTTP + Connector Node Plugin — Provides http_request / connector_action nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+declare class HttpConnectorPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+export { AutomationEngine, AutomationServicePlugin, type AutomationServicePluginOptions, CrudNodesPlugin, type FlowTrigger, HttpConnectorPlugin, LogicNodesPlugin, type NodeExecutionResult, type NodeExecutor };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { FlowNodeParsed } from '@objectstack/spec/automation';
+import { IAutomationService, Logger, AutomationContext, AutomationResult } from '@objectstack/spec/contracts';
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Each node type corresponds to a NodeExecutor.
+ * Third-party plugins only need to implement this interface and register
+ * it with the engine to extend automation capabilities.
+ */
+interface NodeExecutor {
+    /** Corresponds to FlowNodeAction enum value */
+    readonly type: string;
+    /**
+     * Execute a node
+     * @param node - Current node definition
+     * @param variables - Flow variable context (read/write)
+     * @param context - Trigger context
+     * @returns Execution result (may include output data, branch conditions, etc.)
+     */
+    execute(node: FlowNodeParsed, variables: Map<string, unknown>, context: AutomationContext): Promise<NodeExecutionResult>;
+}
+interface NodeExecutionResult {
+    success: boolean;
+    output?: Record<string, unknown>;
+    error?: string;
+    /** Used by decision nodes — returns the selected branch label */
+    branchLabel?: string;
+}
+/**
+ * Trigger interface. Schedule/Event/API triggers are registered via plugins.
+ */
+interface FlowTrigger {
+    readonly type: string;
+    start(flowName: string, callback: (ctx: AutomationContext) => Promise<void>): void;
+    stop(flowName: string): void;
+}
+declare class AutomationEngine implements IAutomationService {
+    private flows;
+    private nodeExecutors;
+    private triggers;
+    private logger;
+    constructor(logger: Logger);
+    /** Register a node executor (called by plugins) */
+    registerNodeExecutor(executor: NodeExecutor): void;
+    /** Unregister a node executor (hot-unplug) */
+    unregisterNodeExecutor(type: string): void;
+    /** Register a trigger (called by plugins) */
+    registerTrigger(trigger: FlowTrigger): void;
+    /** Unregister a trigger (hot-unplug) */
+    unregisterTrigger(type: string): void;
+    /** Get all registered node types */
+    getRegisteredNodeTypes(): string[];
+    /** Get all registered trigger types */
+    getRegisteredTriggerTypes(): string[];
+    registerFlow(name: string, definition: unknown): void;
+    unregisterFlow(name: string): void;
+    listFlows(): Promise<string[]>;
+    execute(flowName: string, context?: AutomationContext): Promise<AutomationResult>;
+    private executeNode;
+    private evaluateCondition;
+    private retryExecution;
+}
+
+/**
+ * Configuration options for the AutomationServicePlugin.
+ */
+interface AutomationServicePluginOptions {
+    /** Enable debug logging for flow execution */
+    debug?: boolean;
+}
+/**
+ * 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
+ * 3. destroy phase: Clean up resources
+ *
+ * Does NOT implement any specific nodes — nodes are registered by other plugins
+ * via the engine's extension API.
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { AutomationServicePlugin } from '@objectstack/service-automation';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new AutomationServicePlugin());
+ * await kernel.bootstrap();
+ *
+ * const automation = kernel.getService('automation');
+ * ```
+ */
+declare class AutomationServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    private engine?;
+    private readonly options;
+    constructor(options?: AutomationServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * CRUD Node Plugin — Provides get_record / create_record / update_record / delete_record
+ *
+ * Dependencies: service-automation (engine)
+ *
+ * In a full runtime environment these nodes would delegate to ObjectQL (data layer).
+ * This MVP implementation provides the extension point structure.
+ */
+declare class CrudNodesPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+/**
+ * Logic Node Plugin — Provides decision / assignment / loop nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+declare class LogicNodesPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+/**
+ * HTTP + Connector Node Plugin — Provides http_request / connector_action nodes
+ *
+ * Dependencies: service-automation (engine)
+ */
+declare class HttpConnectorPlugin implements Plugin {
+    name: string;
+    version: string;
+    type: "standard";
+    dependencies: string[];
+    init(ctx: PluginContext): Promise<void>;
+}
+
+export { AutomationEngine, AutomationServicePlugin, type AutomationServicePluginOptions, CrudNodesPlugin, type FlowTrigger, HttpConnectorPlugin, LogicNodesPlugin, type NodeExecutionResult, type NodeExecutor };

package/dist/index.js

@@ -0,0 +1,350 @@
+// src/engine.ts
+import { FlowSchema } from "@objectstack/spec/automation";
+var AutomationEngine = class {
+  constructor(logger) {
+    this.flows = /* @__PURE__ */ new Map();
+    this.nodeExecutors = /* @__PURE__ */ new Map();
+    this.triggers = /* @__PURE__ */ new Map();
+    this.logger = logger;
+  }
+  // ── Plugin Extension API ──────────────────────────────
+  /** Register a node executor (called by plugins) */
+  registerNodeExecutor(executor) {
+    if (this.nodeExecutors.has(executor.type)) {
+      this.logger.warn(`Node executor '${executor.type}' replaced`);
+    }
+    this.nodeExecutors.set(executor.type, executor);
+    this.logger.info(`Node executor registered: ${executor.type}`);
+  }
+  /** Unregister a node executor (hot-unplug) */
+  unregisterNodeExecutor(type) {
+    this.nodeExecutors.delete(type);
+    this.logger.info(`Node executor unregistered: ${type}`);
+  }
+  /** Register a trigger (called by plugins) */
+  registerTrigger(trigger) {
+    this.triggers.set(trigger.type, trigger);
+    this.logger.info(`Trigger registered: ${trigger.type}`);
+  }
+  /** Unregister a trigger (hot-unplug) */
+  unregisterTrigger(type) {
+    this.triggers.delete(type);
+    this.logger.info(`Trigger unregistered: ${type}`);
+  }
+  /** Get all registered node types */
+  getRegisteredNodeTypes() {
+    return [...this.nodeExecutors.keys()];
+  }
+  /** Get all registered trigger types */
+  getRegisteredTriggerTypes() {
+    return [...this.triggers.keys()];
+  }
+  // ── IAutomationService Contract Implementation ────────
+  registerFlow(name, definition) {
+    const parsed = FlowSchema.parse(definition);
+    this.flows.set(name, parsed);
+    this.logger.info(`Flow registered: ${name}`);
+  }
+  unregisterFlow(name) {
+    this.flows.delete(name);
+    this.logger.info(`Flow unregistered: ${name}`);
+  }
+  async listFlows() {
+    return [...this.flows.keys()];
+  }
+  async execute(flowName, context) {
+    const startTime = Date.now();
+    const flow = this.flows.get(flowName);
+    if (!flow) {
+      return { success: false, error: `Flow '${flowName}' not found` };
+    }
+    const variables = /* @__PURE__ */ new Map();
+    if (flow.variables) {
+      for (const v of flow.variables) {
+        if (v.isInput && context?.params?.[v.name] !== void 0) {
+          variables.set(v.name, context.params[v.name]);
+        }
+      }
+    }
+    if (context?.record) {
+      variables.set("$record", context.record);
+    }
+    try {
+      const startNode = flow.nodes.find((n) => n.type === "start");
+      if (!startNode) {
+        return { success: false, error: "Flow has no start node" };
+      }
+      await this.executeNode(startNode, flow, variables, context ?? {});
+      const output = {};
+      if (flow.variables) {
+        for (const v of flow.variables) {
+          if (v.isOutput) {
+            output[v.name] = variables.get(v.name);
+          }
+        }
+      }
+      return {
+        success: true,
+        output,
+        durationMs: Date.now() - startTime
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      if (flow.errorHandling?.strategy === "retry") {
+        return this.retryExecution(flowName, context, startTime, flow.errorHandling);
+      }
+      return {
+        success: false,
+        error: errorMessage,
+        durationMs: Date.now() - startTime
+      };
+    }
+  }
+  // ── DAG Traversal Core ──────────────────────────────────
+  async executeNode(node, flow, variables, context) {
+    if (node.type === "end") return;
+    const executor = this.nodeExecutors.get(node.type);
+    if (!executor) {
+      if (node.type !== "start") {
+        throw new Error(`No executor registered for node type '${node.type}'`);
+      }
+    } else {
+      const result = await executor.execute(node, variables, context);
+      if (!result.success) {
+        throw new Error(`Node '${node.id}' failed: ${result.error}`);
+      }
+      if (result.output) {
+        for (const [key, value] of Object.entries(result.output)) {
+          variables.set(`${node.id}.${key}`, value);
+        }
+      }
+    }
+    const outEdges = flow.edges.filter((e) => e.source === node.id);
+    for (const edge of outEdges) {
+      if (edge.condition && !this.evaluateCondition(edge.condition, variables)) {
+        continue;
+      }
+      const nextNode = flow.nodes.find((n) => n.id === edge.target);
+      if (nextNode) {
+        await this.executeNode(nextNode, flow, variables, context);
+      }
+    }
+  }
+  evaluateCondition(expression, variables) {
+    let resolved = expression;
+    for (const [key, value] of variables) {
+      resolved = resolved.split(`{${key}}`).join(String(value));
+    }
+    try {
+      return new Function(`return (${resolved})`)();
+    } catch {
+      return false;
+    }
+  }
+  async retryExecution(flowName, context, startTime, errorHandling) {
+    const maxRetries = errorHandling.maxRetries ?? 3;
+    const delay = errorHandling.retryDelayMs ?? 1e3;
+    for (let i = 0; i < maxRetries; i++) {
+      await new Promise((r) => setTimeout(r, delay));
+      const result = await this.execute(flowName, context);
+      if (result.success) return result;
+    }
+    return { success: false, error: "Max retries exceeded", durationMs: Date.now() - startTime };
+  }
+};
+
+// src/plugin.ts
+var AutomationServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service-automation";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    this.engine = new AutomationEngine(ctx.logger);
+    ctx.registerService("automation", this.engine);
+    if (this.options.debug) {
+      ctx.hook("automation:beforeExecute", async (flowName) => {
+        ctx.logger.debug(`[Automation] Before execute: ${flowName}`);
+      });
+    }
+    ctx.logger.info("[Automation] Engine initialized");
+  }
+  async start(ctx) {
+    if (!this.engine) return;
+    await ctx.trigger("automation:ready", this.engine);
+    const nodeTypes = this.engine.getRegisteredNodeTypes();
+    ctx.logger.info(
+      `[Automation] Engine started with ${nodeTypes.length} node types: ${nodeTypes.join(", ") || "(none)"}`
+    );
+  }
+  async destroy() {
+    this.engine = void 0;
+  }
+};
+
+// src/plugins/crud-nodes-plugin.ts
+var CrudNodesPlugin = class {
+  constructor() {
+    this.name = "com.objectstack.automation.crud-nodes";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.service-automation"];
+  }
+  async init(ctx) {
+    const engine = ctx.getService("automation");
+    engine.registerNodeExecutor({
+      type: "get_record",
+      async execute(node, _variables, _context) {
+        const config = node.config;
+        return {
+          success: true,
+          output: { records: [], object: config?.object }
+        };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "create_record",
+      async execute(node, _variables, _context) {
+        const config = node.config;
+        return {
+          success: true,
+          output: { id: "new-record-id", object: config?.object }
+        };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "update_record",
+      async execute(_node, _variables, _context) {
+        return { success: true };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "delete_record",
+      async execute(_node, _variables, _context) {
+        return { success: true };
+      }
+    });
+    ctx.logger.info("[CRUD Nodes] 4 node executors registered");
+  }
+};
+
+// src/plugins/logic-nodes-plugin.ts
+var LogicNodesPlugin = class {
+  constructor() {
+    this.name = "com.objectstack.automation.logic-nodes";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.service-automation"];
+  }
+  async init(ctx) {
+    const engine = ctx.getService("automation");
+    engine.registerNodeExecutor({
+      type: "decision",
+      async execute(node, variables, _context) {
+        const config = node.config;
+        const conditions = config?.conditions ?? [];
+        for (const cond of conditions) {
+          let expr = cond.expression;
+          for (const [k, v] of variables) {
+            expr = expr.split(`{${k}}`).join(String(v));
+          }
+          try {
+            if (new Function(`return (${expr})`)()) {
+              return { success: true, branchLabel: cond.label };
+            }
+          } catch {
+          }
+        }
+        return { success: true, branchLabel: "default" };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "assignment",
+      async execute(node, variables, _context) {
+        const config = node.config ?? {};
+        for (const [key, value] of Object.entries(config)) {
+          variables.set(key, value);
+        }
+        return { success: true };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "loop",
+      async execute(node, variables, _context) {
+        const config = node.config;
+        const collectionName = config?.collection;
+        if (collectionName) {
+          const collection = variables.get(collectionName);
+          if (Array.isArray(collection)) {
+            variables.set("$loopItems", collection);
+            variables.set("$loopIndex", 0);
+          }
+        }
+        return { success: true };
+      }
+    });
+    ctx.logger.info("[Logic Nodes] 3 node executors registered");
+  }
+};
+
+// src/plugins/http-connector-plugin.ts
+var HttpConnectorPlugin = class {
+  constructor() {
+    this.name = "com.objectstack.automation.http-connector";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = ["com.objectstack.service-automation"];
+  }
+  async init(ctx) {
+    const engine = ctx.getService("automation");
+    engine.registerNodeExecutor({
+      type: "http_request",
+      async execute(node, _variables, _context) {
+        const config = node.config;
+        const url = config?.url;
+        const method = config?.method ?? "GET";
+        const headers = config?.headers;
+        const body = config?.body;
+        if (!url) {
+          return { success: false, error: "http_request: url is required" };
+        }
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0
+        });
+        const data = await response.json();
+        return {
+          success: response.ok,
+          output: { response: data, status: response.status },
+          error: response.ok ? void 0 : `HTTP ${response.status}`
+        };
+      }
+    });
+    engine.registerNodeExecutor({
+      type: "connector_action",
+      async execute(node, _variables, _context) {
+        const connectorConfig = node.connectorConfig;
+        if (!connectorConfig) {
+          return { success: false, error: "connector_action: connectorConfig is required" };
+        }
+        ctx.logger.info(
+          `Connector action: ${connectorConfig.connectorId}.${connectorConfig.actionId}`
+        );
+        return { success: true, output: { connectorResult: {} } };
+      }
+    });
+    ctx.logger.info("[HTTP Connector] 2 node executors registered");
+  }
+};
+export {
+  AutomationEngine,
+  AutomationServicePlugin,
+  CrudNodesPlugin,
+  HttpConnectorPlugin,
+  LogicNodesPlugin
+};
+//# sourceMappingURL=index.js.map