npm package: @paulovila/workflow
Description: Generic workflow execution engine plugin for Vetra - provides core workflow orchestration, state management, and execution capabilities
Author: Vetra Team
Latest version: 1.0.1

# @vetra/workflow

Generic workflow execution engine plugin for Vetra. Provides core workflow orchestration, state management, and execution capabilities for building complex business processes.

## Features

- **Generic Workflow Engine**: Execute any type of workflow with flexible block-based architecture
- **State Management**: Track workflow state, progress, and history
- **Block System**: Pluggable block executors for different operations
- **Error Handling**: Comprehensive error handling with retry mechanisms
- **Timeout Management**: Configurable timeouts for workflows and blocks
- **Audit Trail**: Complete audit trail of all workflow actions
- **Workflow Templates**: Pre-built templates for common workflows
- **API Endpoints**: RESTful API for workflow management

## Installation

```bash
npm install @vetra/workflow
```

## Quick Start

### 1. Initialize the Plugin

```typescript
import { workflowPlugin } from '@vetra/workflow';

export default buildConfig({
  plugins: [
    workflowPlugin({
      enabled: true,
      debug: false,
      engineOptions: {
        timeout: 3600000, // 1 hour
        maxRetries: 3,
      },
    }),
  ],
});
```

### 2. Create a Workflow Configuration

```typescript
import { BLOCK_TYPES } from '@vetra/workflow';

const workflowConfig = {
  id: 'my-workflow',
  name: 'My Workflow',
  version: '1.0.0',
  enabled: true,
  blocks: [
    {
      id: 'block-1',
      type: BLOCK_TYPES.FORM_INPUT,
      name: 'Collect Information',
      order: 1,
      required: true,
      enabled: true,
      settings: { autoAdvance: true },
      validation: { required: true, rules: [] },
    },
    {
      id: 'block-2',
      type: BLOCK_TYPES.APPROVAL,
      name: 'Get Approval',
      order: 2,
      required: true,
      enabled: true,
      settings: { autoAdvance: true },
      validation: { required: true, rules: [] },
    },
  ],
  settings: {
    timeout: 604800000, // 7 days
    retryAttempts: 3,
    autoStart: false,
    notifyOnCompletion: true,
  },
};
```

### 3. Execute a Workflow

```typescript
const instance = await engine.executeWorkflow(
  workflowConfig,
  {
    userId: 'user-123',
    sessionId: 'session-456',
    ipAddress: '192.168.1.1',
  },
  {
    timeout: 3600000,
    retryAttempts: 3,
  }
);

console.log(instance.status); // 'completed' or 'failed'
console.log(instance.progress); // 0-100
```

## Workflow States

- `pending` - Workflow is waiting to start
- `in_progress` - Workflow is currently executing
- `completed` - Workflow completed successfully
- `failed` - Workflow failed
- `cancelled` - Workflow was cancelled
- `paused` - Workflow is paused
- `expired` - Workflow expired

## Block Types

### Built-in Block Types

- **ACTION**: Execute custom actions
- **APPROVAL**: Wait for approval
- **CONDITION**: Evaluate conditions
- **DELAY**: Introduce delays
- **NOTIFICATION**: Send notifications
- **FORM_INPUT**: Collect form data
- **VALIDATION**: Validate data
- **DOCUMENT_UPLOAD**: Handle document uploads
- **PAYMENT**: Process payments

### Creating Custom Block Executors

```typescript
import { BaseBlockExecutor } from '@vetra/workflow';

class CustomBlockExecutor extends BaseBlockExecutor {
  async execute(block, instance, context) {
    // Your custom logic here
    return this.createSuccessResult(
      { customData: 'result' },
      processingTime
    );
  }
}

// Register the executor
engine.registerBlockExecutor('custom-type', new CustomBlockExecutor());
```

## Workflow Templates

Pre-built templates are available:

```typescript
import {
  createApprovalWorkflowTemplate,
  createDocumentVerificationTemplate,
  createSignatureWorkflowTemplate,
  createKYCColombiaTemplate,
} from '@vetra/workflow';

const approvalTemplate = createApprovalWorkflowTemplate();
const docTemplate = createDocumentVerificationTemplate();
const signatureTemplate = createSignatureWorkflowTemplate();
const kycTemplate = createKYCColombiaTemplate();
```

## API Endpoints

### Execute Workflow

```
POST /api/workflows/execute
```

Request:
```json
{
  "templateId": "template-id",
  "userId": "user-id",
  "context": {
    "sessionId": "session-id",
    "ipAddress": "192.168.1.1"
  },
  "data": {}
}
```

Response:
```json
{
  "success": true,
  "workflowId": "workflow-id",
  "status": "in_progress",
  "progress": 0
}
```

### Get Workflow Status

```
GET /api/workflows/status/:id
```

Response:
```json
{
  "success": true,
  "id": "workflow-id",
  "status": "completed",
  "progress": 100,
  "currentBlockIndex": 2,
  "errors": []
}
```

### List Workflows

```
GET /api/workflows/list?page=1&limit=10&userId=user-id
```

Response:
```json
{
  "success": true,
  "workflows": [...],
  "total": 50,
  "page": 1,
  "limit": 10
}
```

### Cancel Workflow

```
POST /api/workflows/cancel/:id
```

### Get Workflow History

```
GET /api/workflows/history/:id
```

### Retry Workflow

```
POST /api/workflows/retry/:id
```

## Configuration Options

```typescript
interface WorkflowPluginOptions {
  enabled?: boolean;
  debug?: boolean;
  engineOptions?: {
    timeout?: number;
    maxRetries?: number;
    debug?: boolean;
    persistState?: boolean;
  };
  collections?: {
    workflowDefinitions?: string;
    workflowInstances?: string;
    workflowTemplates?: string;
    workflowLogs?: string;
  };
}
```

## Database Collections

The plugin creates four collections:

1. **workflow-definitions**: Stores workflow configurations
2. **workflow-instances**: Stores workflow execution instances
3. **workflow-templates**: Stores workflow templates
4. **workflow-logs**: Stores audit trail and logs

## Error Handling

The engine provides comprehensive error handling:

```typescript
if (instance.status === 'failed') {
  instance.errors.forEach(error => {
    console.log(`Error: ${error.code} - ${error.message}`);
    console.log(`Block: ${error.blockId}`);
    console.log(`Recoverable: ${error.recoverable}`);
  });
}
```

## Retry Mechanism

Blocks support automatic retries with exponential backoff:

```typescript
{
  id: 'block-1',
  type: BLOCK_TYPES.ACTION,
  settings: {
    retryAttempts: 3,
    timeout: 300000,
  },
}
```

## Workflow Conditions

Blocks can have conditions that determine execution:

```typescript
{
  id: 'block-1',
  type: BLOCK_TYPES.ACTION,
  conditions: [
    {
      field: 'requiresApproval',
      operator: 'equals',
      value: true,
      action: 'show',
    },
  ],
}
```

Supported operators:
- `equals`
- `not_equals`
- `contains`
- `not_contains`
- `greater_than`
- `less_than`
- `greater_than_or_equal`
- `less_than_or_equal`
- `exists`
- `not_exists`
- `in`
- `not_in`

## Testing

Comprehensive testing guide available in [TESTING_GUIDE.md](./TESTING_GUIDE.md).

### Quick Start

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run specific test suite
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:e2e          # End-to-end tests only
npm run test:examples     # Example tests only

# Run standalone test harness (no Payload CMS needed)
node test-harness.js
node test-harness.js --test simple-workflow
node test-harness.js --verbose

# Run tests in Docker
npm run test:docker:build
npm run test:docker
```

### Testing Approaches

1. **Unit Tests** (`tests/unit/`)
   - Test individual functions and components
   - WorkflowEngine methods, block executors, state transitions

2. **Integration Tests** (`tests/integration/`)
   - Test API endpoints and component interactions
   - Execute workflow, get status, cancel, retry endpoints

3. **End-to-End Tests** (`tests/e2e/`)
   - Test complete workflows from start to finish
   - Simple approval, multi-step, conditional, error scenarios

4. **Example Tests** (`tests/examples/`)
   - Practical examples demonstrating common testing patterns
   - SimpleWorkflow, MultiStepWorkflow, ConditionalWorkflow, ErrorHandling

5. **Standalone Test Harness** (`test-harness.js`)
   - Test workflows without full Payload CMS setup
   - Useful for development and debugging
   - Can be run from command line

### Test Coverage

The project enforces >80% coverage thresholds:
- Branches: 80%
- Functions: 80%
- Lines: 80%
- Statements: 80%

View coverage report:
```bash
npm run test:coverage
open coverage/lcov-report/index.html
```

### Writing Custom Tests

See [TESTING_GUIDE.md](./TESTING_GUIDE.md) for:
- Test structure and naming conventions
- Common test patterns
- Test utilities and helpers
- Mock objects
- Best practices

### Test Utilities

Helper functions available in `tests/utils/test-helpers.ts`:
- `createTestWorkflow()` - Create test workflows
- `createTestContext()` - Create test contexts
- `createMockBlockExecutor()` - Create mock executors
- `assertWorkflowSuccess()` - Assert workflow success
- `assertBlockSuccess()` - Assert block success
- And many more...

### Mock Objects

Mock Payload CMS available in `tests/mocks/MockPayloadCMS.ts`:
```typescript
import { createMockPayload } from './tests/mocks/MockPayloadCMS';

const payload = createMockPayload();
const doc = await payload.create('workflow-definitions', { ... });
```

## Architecture

The workflow engine follows a modular architecture:

```
WorkflowEngine
├── Block Executors
│   ├── ActionBlockExecutor
│   ├── ApprovalBlockExecutor
│   ├── ConditionBlockExecutor
│   └── ... (more executors)
├── State Management
│   ├── Workflow State
│   ├── Block State
│   └── Audit Trail
└── API Endpoints
    ├── Execute
    ├── Status
    ├── List
    ├── Cancel
    ├── History
    └── Retry
```

## Best Practices

1. **Always set timeouts**: Prevent workflows from running indefinitely
2. **Use required blocks wisely**: Mark blocks as required only when necessary
3. **Implement proper error handling**: Handle errors gracefully in custom executors
4. **Monitor audit trails**: Use audit trails for debugging and compliance
5. **Test workflows**: Write tests for custom block executors
6. **Use templates**: Leverage pre-built templates for common workflows

## Dependencies

- `payload` (peer dependency)
- `@vetra/shared` (peer dependency)
- `uuid`

## License

MIT

## Support

For issues and questions, please refer to the main Vetra documentation.