@elqnt/workflow 2.1.1 → 2.1.3

package/README.md

@@ -0,0 +1,235 @@
+# @elqnt/workflow
+
+Workflow definitions and execution for Eloquent platform. Provides models, API functions, and React hooks for building and managing workflows.
+
+## Installation
+
+```bash
+pnpm add @elqnt/workflow
+```
+
+## Quick Start
+
+### Using React Hooks
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elqnt/workflow",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Workflow definitions and execution for Eloquent platform - models, API, hooks, and store",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -36,9 +36,9 @@
     "directory": "packages/workflow"
   },
   "dependencies": {
-    "@elqnt/entity": "2.1.1",
-    "@elqnt/types": "2.0.9",
-    "@elqnt/api-client": "1.0.3"
+    "@elqnt/entity": "2.2.0",
+    "@elqnt/types": "2.0.13",
+    "@elqnt/api-client": "1.0.4"
   },
   "peerDependencies": {
     "@reduxjs/toolkit": "^2.0.0",
@@ -52,7 +52,7 @@
     "react-redux": "^9.1.2",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
-    "@elqnt/api-client": "1.0.3"
+    "@elqnt/api-client": "1.0.4"
   },
   "scripts": {
     "build": "tsup",