Merge pull request #184 from objectstack-ai/copilot/add-approval-workflows

Author: hotlong

packages/plugins/workflow/README.md

@@ -10,13 +10,17 @@ A comprehensive workflow and state machine plugin for ObjectOS, providing finite
 - ✅ **Transition Actions** - Execute actions during state transitions
 - ✅ **Workflow Versioning** - Support for multiple versions of workflows
 - ✅ **Multiple Workflow Types**:
-  - **Approval Workflows** - Multi-level approval processes
+  - **Approval Workflows** - Multi-level approval processes with delegation and escalation 🆕
   - **Sequential Workflows** - Step-by-step linear processes
   - **Parallel Workflows** - Concurrent execution paths
   - **Conditional Workflows** - Dynamic branching based on conditions
-- ✅ **Task Management** - Create, complete, and track workflow tasks
+- ✅ **Task Management** - Create, complete, reject, delegate, and escalate workflow tasks 🆕
 - ✅ **State History** - Track all state transitions with full audit trail
 - ✅ **Event Integration** - Emit events for workflow lifecycle
+- ✅ **Multi-Channel Notifications** - Email, Slack, and Webhook notifications 🆕
+- ✅ **Delegation Support** - Delegate tasks with reason tracking and original assignee preservation 🆕
+- ✅ **Escalation Support** - Manual and automatic time-based escalation 🆕
+- ✅ **Approval Chains** - Multi-level approval workflows with configurable requirements 🆕
 
 ## Installation
 
@@ -297,6 +301,166 @@ await api.completeTask(task.id, {
 const tasks = await api.getInstanceTasks(instance.id);
 ```
 
+## Advanced Approval Features 🆕
+
+The workflow plugin now includes powerful approval workflow capabilities with delegation, escalation, and multi-channel notifications.
+
+### Delegation
+
+Delegate tasks to other users when you're unavailable:
+
+```typescript
+// Delegate a task to another user
+const delegated = await api.delegateTask(
+    taskId,
+    'assistant@example.com',      // Delegate to
+    'manager@example.com',         // Delegated by
+    'Out of office this week'      // Reason
+);
+
+console.log(delegated.originalAssignee);  // manager@example.com
+console.log(delegated.assignedTo);        // assistant@example.com
+console.log(delegated.delegationReason);  // Out of office this week
+```
+
+### Escalation
+
+Escalate tasks to higher authorities:
+
+```typescript
+// Escalate a task manually
+const escalated = await api.escalateTask(
+    taskId,
+    'director@example.com',        // Escalate to
+    'Requires executive approval', // Reason
+    'manager@example.com'          // Escalated by
+);
+
+// Auto-escalation based on due date
+const task = await api.createTask({
+    instanceId: workflowId,
+    name: 'manager_approval',
+    assignedTo: 'manager@example.com',
+    status: 'pending',
+    autoEscalate: true,
+    escalationTarget: 'director@example.com',
+    dueDate: new Date(Date.now() + 48 * 60 * 60 * 1000), // 48 hours
+});
+```
+
+### Multi-Channel Notifications
+
+Send notifications via Email, Slack, or Webhooks:
+
+```typescript
+import {
+    NotificationService,
+    EmailNotificationHandler,
+    SlackNotificationHandler,
+} from '@objectos/plugin-workflow';
+
+// Setup notification service
+const notificationService = new NotificationService();
+
+// Register handlers
+const emailHandler = new EmailNotificationHandler('noreply@company.com');
+const slackHandler = new SlackNotificationHandler({ 
+    webhookUrl: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL' 
+});
+
+notificationService.registerHandler('email', emailHandler);
+notificationService.registerHandler('slack', slackHandler);
+
+// Register notification actions
+const engine = api.getEngine();
+
+engine.registerAction('notify_manager', async (ctx) => {
+    await notificationService.send({
+        channel: 'email',
+        recipients: ['manager@company.com'],
+        subject: 'Approval Required',
+        message: `Please review: ${ctx.getData('title')}`,
+        data: ctx.getData(),
+    }, ctx);
+});
+
+engine.registerAction('notify_slack', async (ctx) => {
+    await notificationService.send({
+        channel: 'slack',
+        recipients: ['#approvals'],
+        message: `✅ Approved: ${ctx.getData('title')}`,
+    }, ctx);
+});
+```
+
+### Multi-Level Approval Chains
+
+Create complex approval workflows with multiple levels:
+
+```typescript
+import { ApprovalService } from '@objectos/plugin-workflow';
+
+const approvalService = new ApprovalService(storage);
+
+// Define approval chain
+const approvalChain = {
+    levels: [
+        {
+            level: 1,
+            approver: 'manager@company.com',
+            description: 'Manager approval',
+            required: true,
+            escalationTarget: 'senior_manager@company.com',
+            escalationTimeout: 48 * 60 * 60 * 1000, // 48 hours
+        },
+        {
+            level: 2,
+            approver: 'director@company.com',
+            description: 'Director approval',
+            required: true,
+            escalationTarget: 'vp@company.com',
+            escalationTimeout: 72 * 60 * 60 * 1000, // 72 hours
+        },
+        {
+            level: 3,
+            approver: 'cfo@company.com',
+            description: 'CFO final approval',
+            required: true,
+        },
+    ],
+};
+
+// Create approval tasks for workflow
+const tasks = await approvalService.createApprovalChain(
+    instanceId,
+    approvalChain,
+    'purchase_order'
+);
+
+// Check if approval chain is complete
+const isComplete = await approvalService.isApprovalChainComplete(instanceId);
+
+// Check if any approval was rejected
+const hasRejection = await approvalService.hasRejectedApproval(instanceId);
+
+// Get approval history
+const history = await approvalService.getApprovalHistory(instanceId);
+```
+
+### Complete Example
+
+See `examples/advanced-approval-example.ts` for a comprehensive example demonstrating:
+- Multi-level approval workflow (Manager → Director → CFO)
+- Task delegation with reason tracking
+- Task escalation (manual and automatic)
+- Email and Slack notifications
+- Complete approval history tracking
+
+```bash
+# Run the example
+ts-node examples/advanced-approval-example.ts
+```
+
 ## Querying Workflows
 
 ```typescript
@@ -329,6 +493,7 @@ const page2 = await api.queryWorkflows({
 
 ### WorkflowAPI
 
+**Workflow Management:**
 - `registerWorkflow(definition)` - Register a workflow definition
 - `startWorkflow(workflowId, data, startedBy?)` - Start a new workflow instance
 - `getWorkflowStatus(instanceId)` - Get workflow instance status
@@ -337,11 +502,54 @@ const page2 = await api.queryWorkflows({
 - `queryWorkflows(options)` - Query workflow instances
 - `getAvailableTransitions(instanceId)` - Get available transitions
 - `canExecuteTransition(instanceId, transition)` - Check if transition can be executed
+
+**Task Management:**
 - `createTask(task)` - Create a workflow task
 - `getTask(taskId)` - Get a task
+- `getInstanceTasks(instanceId)` - Get all tasks for a workflow instance
 - `completeTask(taskId, result?)` - Complete a task
 - `rejectTask(taskId, result?)` - Reject a task
 
+**Advanced Approval Features:** 🆕
+- `delegateTask(taskId, delegateTo, delegatedBy, reason?)` - Delegate a task to another user
+- `escalateTask(taskId, escalateTo, reason?, escalatedBy?)` - Escalate a task to higher authority
+
+**Utility:**
+- `getEngine()` - Get the workflow engine for registering guards/actions
+
+### ApprovalService 🆕
+
+- `delegateTask(request)` - Delegate a task with full tracking
+- `escalateTask(request)` - Escalate a task with reason
+- `checkAutoEscalation()` - Check and process overdue tasks for auto-escalation
+- `createApprovalChain(instanceId, chain, workflowName)` - Create multi-level approval tasks
+- `isApprovalChainComplete(instanceId)` - Check if all required approvals are complete
+- `hasRejectedApproval(instanceId)` - Check if any approval was rejected
+- `getApprovalHistory(instanceId)` - Get chronological approval history
+
+### NotificationService 🆕
+
+- `registerHandler(channel, handler)` - Register a notification handler
+- `send(config, context)` - Send a notification through registered handler
+- `isSupported(channel)` - Check if a notification channel is supported
+
+### NotificationHandlers 🆕
+
+**EmailNotificationHandler:**
+- Sends email notifications
+- Supports template rendering with variable substitution
+- Constructor: `new EmailNotificationHandler(fromAddress, smtpConfig?)`
+
+**SlackNotificationHandler:**
+- Sends Slack notifications
+- Supports webhook URL and bot token authentication
+- Constructor: `new SlackNotificationHandler(config?)`
+
+**WebhookNotificationHandler:**
+- Sends HTTP webhook notifications
+- Supports custom payload data
+- Constructor: `new WebhookNotificationHandler()`
+
 ### WorkflowEngine
 
 - `registerGuard(name, guard)` - Register a guard function
@@ -367,7 +575,9 @@ The plugin emits the following events:
 
 See the `/examples` directory for complete examples:
 
-- `approval-workflow.yaml` - Multi-level approval workflow
+- `approval-workflow.yaml` - Basic multi-level approval workflow
+- `multi-level-approval-workflow.yaml` - Advanced approval with delegation and escalation 🆕
+- `advanced-approval-example.ts` - Complete demonstration of approval features 🆕
 - `sequential-workflow.yaml` - Order fulfillment workflow
 - `parallel-workflow.yaml` - Employee onboarding workflow
 - `conditional-workflow.yaml` - Support ticket routing workflow
@@ -379,12 +589,14 @@ See the `/examples` directory for complete examples:
 npm test
 ```
 
-The plugin includes 130+ comprehensive tests covering:
+The plugin includes 170+ comprehensive tests covering:
 - FSM engine functionality
 - YAML parsing and validation
 - API operations
 - Storage operations
 - Plugin lifecycle
+- Approval service (delegation, escalation, approval chains) 🆕
+- Notification service (email, Slack, webhooks) 🆕
 
 ## License