@elqnt/workflow

Workflow definitions and execution for Eloquent platform. Provides models, API functions, and React hooks for building and managing workflows.

Installation

pnpm add @elqnt/workflow

Quick Start

Using React Hooks

import { useWorkflows, useWorkflowInstances } from "@elqnt/workflow/hooks";

function WorkflowManager() {
  const { listWorkflows, createWorkflow, loading, error } = useWorkflows({
    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
    orgId: currentOrgId,
  });

  const { createInstance, executeNode } = useWorkflowInstances({
    baseUrl: process.env.NEXT_PUBLIC_API_GATEWAY_URL!,
    orgId: currentOrgId,
  });

  // List all workflows
  const workflows = await listWorkflows();

  // Create a new workflow instance and execute
  const instance = await createInstance(workflowId, {
    variables: { customerId: "123" },
    autoExecute: true,
  });
}

Using API Functions Directly

import {
  listWorkflowsApi,
  createWorkflowApi,
  createWorkflowInstanceApi,
} from "@elqnt/workflow/api";

const response = await listWorkflowsApi({
  baseUrl: "https://api.elqnt.ai",
  orgId: "org-uuid",
});

if (response.data) {
  console.log("Workflows:", response.data.definitions);
}

Exports

| Import Path | Description | |-------------|-------------| | @elqnt/workflow | All exports | | @elqnt/workflow/api | Browser API functions | | @elqnt/workflow/hooks | React hooks | | @elqnt/workflow/models | TypeScript types (generated from Go via tygo) |

API Reference

API Functions (@elqnt/workflow/api)

Workflow Definitions

| Function | Description | |----------|-------------| | listWorkflowsApi(options) | List all workflow definitions | | getWorkflowApi(workflowId, options) | Get a specific workflow | | createWorkflowApi(workflow, options) | Create a new workflow | | updateWorkflowApi(workflowId, workflow, options) | Update a workflow | | deleteWorkflowApi(workflowId, options) | Delete a workflow |

Workflow Instances

| Function | Description | |----------|-------------| | createWorkflowInstanceApi(definitionId, data, options) | Create and optionally start an instance | | getWorkflowInstanceApi(instanceId, options) | Get instance details | | listWorkflowInstancesApi(definitionId, options) | List instances for a workflow | | updateWorkflowInstanceStatusApi(instanceId, status, options) | Update instance status | | executeWorkflowNodeApi(instanceId, nodeId, input, options) | Execute a specific node | | resumeWorkflowNodeApi(instanceId, nodeId, result, options) | Resume a waiting node | | retryWorkflowNodeApi(instanceId, nodeId, options) | Retry a failed node |

Workflow Templates

| Function | Description | |----------|-------------| | listWorkflowTemplatesApi(options) | List available templates | | getWorkflowTemplateApi(templateId, options) | Get template details | | instantiateWorkflowTemplateApi(templateId, params, options) | Create workflow from template |

React Hooks (@elqnt/workflow/hooks)

useWorkflows(options)

Hook for workflow definition CRUD operations.

const {
  loading,        // boolean - operation in progress
  error,          // string | null - error message
  listWorkflows,  // () => Promise<WorkflowDefinition[]>
  getWorkflow,    // (id) => Promise<WorkflowDefinition | null>
  createWorkflow, // (workflow) => Promise<WorkflowDefinition | null>
  updateWorkflow, // (id, workflow) => Promise<WorkflowDefinition | null>
  deleteWorkflow, // (id) => Promise<boolean>
} = useWorkflows({ baseUrl, orgId });

useWorkflowInstances(options)

Hook for workflow instance operations.

const {
  loading,
  error,
  listInstances,  // (definitionId, filters?) => Promise<WorkflowInstance[]>
  getInstance,    // (instanceId) => Promise<WorkflowInstance | null>
  createInstance, // (definitionId, data?) => Promise<WorkflowInstance | null>
  updateStatus,   // (instanceId, status) => Promise<WorkflowInstance | null>
  executeNode,    // (instanceId, nodeId, input) => Promise<object | null>
  resumeNode,     // (instanceId, nodeId, result) => Promise<WorkflowInstance | null>
  retryNode,      // (instanceId, nodeId) => Promise<WorkflowInstance | null>
} = useWorkflowInstances({ baseUrl, orgId });

useWorkflowTemplates(options)

Hook for workflow template operations.

const {
  loading,
  error,
  listTemplates,        // (category?) => Promise<WorkflowTemplate[]>
  getTemplate,          // (templateId) => Promise<WorkflowTemplate | null>
  instantiateTemplate,  // (templateId, params) => Promise<WorkflowDefinition | null>
} = useWorkflowTemplates({ baseUrl, orgId });

Types (@elqnt/workflow/models)

Key types generated from Go via tygo:

import type {
  // Definitions
  WorkflowDefinition,
  WorkflowNode,
  WorkflowEdge,
  WorkflowVariables,
  NodeDefinition,

  // Instances
  WorkflowInstance,
  InstanceState,
  NodeState,
  ExecutionContext,

  // Status enums
  InstanceStatus,
  NodeStatus,
  EdgeStatus,

  // Node types
  NodeType,
  NodeSubType,
  EdgeType,
  WorkflowType,
} from "@elqnt/workflow/models";

Instance Status

const InstanceStatusNew: InstanceStatus = "NEW";
const InstanceStatusRunning: InstanceStatus = "RUNNING";
const InstanceStatusWaiting: InstanceStatus = "WAITING";
const InstanceStatusPaused: InstanceStatus = "PAUSED";
const InstanceStatusCompleted: InstanceStatus = "COMPLETED";
const InstanceStatusFailed: InstanceStatus = "FAILED";

Node Types

const NodeTypeTrigger: NodeType = "trigger";
const NodeTypeHumanAction: NodeType = "humanAction";
const NodeTypeAgent: NodeType = "agent";
const NodeTypeAction: NodeType = "action";
const NodeTypeLogic: NodeType = "logic";
const NodeTypeLoop: NodeType = "loop";
const NodeTypeDelay: NodeType = "delay";
const NodeTypeData: NodeType = "data";
// ... and more

Workflow Definition Structure

interface WorkflowDefinition {
  id?: string;
  name: string;           // Normalized: lowercase, dashes
  title: string;          // Display name
  description: string;
  type: WorkflowType;     // "entity", "chat", "document", etc.
  nodes: { [key: string]: WorkflowNode };
  edges: WorkflowEdge[];
  entryPoints: string[];  // Start node IDs
  variables: WorkflowVariables;
  permissions: WorkflowPermissions;
  metadata: WorkflowMetadata;
}

Peer Dependencies

• @reduxjs/toolkit ^2.0.0
• react ^18.0.0 || ^19.0.0
• react-redux ^9.0.0

License

Private - Eloquent Platform