@onlineapps/conn-orch-orchestrator 1.0.1 → 1.0.3

package/README.md

@@ -1,585 +1,138 @@
-<a name="module_@onlineapps/conn-orch-orchestrator"></a>
+# @onlineapps/conn-orch-orchestrator
 
-## @onlineapps/conn-orch-orchestrator
-Workflow orchestration coordinator managing complete workflow execution.
-Provides centralized control flow handling, step routing, and workflow state management
-for OA Drive microservices.
+Workflow orchestration coordinator managing complete workflow execution for OA Drive microservices.
 
-**See**: [GitHub Repository](https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-orchestrator)  
-**Since**: 1.0.0  
-**Author**: OA Drive Team  
-**License**: MIT  
+## Features
 
-* [@onlineapps/conn-orch-orchestrator](#module_@onlineapps/conn-orch-orchestrator)
-    * _static_
-        * [.VERSION](#module_@onlineapps/conn-orch-orchestrator.VERSION) : <code>string</code>
-    * _inner_
-        * [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
-            * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-            * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-        * [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
-            * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-            * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-        * [~processWorkflowMessage(message)](#module_@onlineapps/conn-orch-orchestrator..processWorkflowMessage) ⇒ <code>Promise.&lt;WorkflowResult&gt;</code> \| <code>boolean</code> \| <code>string</code> \| <code>number</code>
-        * [~processStep(message)](#module_@onlineapps/conn-orch-orchestrator..processStep) ⇒ <code>Promise.&lt;\*&gt;</code>
-        * [~handleControlFlow(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleControlFlow) ⇒ <code>Promise.&lt;\*&gt;</code>
-        * [~handleIfStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleIfStep) ⇒ <code>Promise.&lt;\*&gt;</code>
-        * [~handleForeachStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleForeachStep) ⇒ <code>Promise.&lt;Array&gt;</code>
-        * [~handleForkJoinStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleForkJoinStep) ⇒ <code>Promise.&lt;\*&gt;</code>
-        * [~handleSwitchStep(step, message)](#module_@onlineapps/conn-orch-orchestrator..handleSwitchStep) ⇒ <code>Promise.&lt;\*&gt;</code>
-        * [~routeToNextService(message, nextService, stepResult, nextIndex)](#module_@onlineapps/conn-orch-orchestrator..routeToNextService) ⇒ <code>Promise.&lt;void&gt;</code>
-        * [~completeWorkflow(message, finalResult)](#module_@onlineapps/conn-orch-orchestrator..completeWorkflow) ⇒ <code>Promise.&lt;void&gt;</code>
-        * [~handleWorkflowFailure(message, error)](#module_@onlineapps/conn-orch-orchestrator..handleWorkflowFailure) ⇒ <code>Promise.&lt;void&gt;</code>
-        * [~getStats()](#module_@onlineapps/conn-orch-orchestrator..getStats) ⇒ <code>OrchestratorStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code>
-        * [~resetStats()](#module_@onlineapps/conn-orch-orchestrator..resetStats) ⇒ <code>void</code>
-        * [~create(config)](#module_@onlineapps/conn-orch-orchestrator..create) ⇒ <code>OrchestratorConnector</code>
-        * [~WorkflowMessage](#module_@onlineapps/conn-orch-orchestrator..WorkflowMessage) : <code>Object</code>
-        * [~WorkflowResult](#module_@onlineapps/conn-orch-orchestrator..WorkflowResult) : <code>Object</code>
-        * [~ControlFlowStep](#module_@onlineapps/conn-orch-orchestrator..ControlFlowStep) : <code>Object</code>
-        * [~OrchestratorStats](#module_@onlineapps/conn-orch-orchestrator..OrchestratorStats) : <code>Object</code>
+- 🎯 **Workflow coordination** - Complete workflow execution management
+- 🔀 **Control flow handling** - If/else, switch, foreach, fork-join patterns
+- 📊 **State management** - Workflow state tracking and persistence
+- 🚦 **Step routing** - Intelligent routing to next services
+- 📈 **Statistics tracking** - Workflow execution metrics
+- ⚡ **Async processing** - Non-blocking workflow execution
 
-<a name="module_@onlineapps/conn-orch-orchestrator.VERSION"></a>
+## Installation
 
-### @onlineapps/conn-orch-orchestrator.VERSION : <code>string</code>
-Current version
-
-**Kind**: static constant of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector"></a>
-
-### @onlineapps/conn-orch-orchestrator~OrchestratorConnector
-**Kind**: inner class of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-
-* [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
-    * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-    * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-
-<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
-
-#### new OrchestratorConnector()
-Workflow orchestration connector managing complete workflow execution
-
-**Example** *(Basic Usage)*  
-```js
-const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  serviceName: 'invoice-service'
-});
-
-await orchestrator.processWorkflowMessage(message);
-```
-**Example** *(With Caching)*  
-```js
-const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  cache: cacheConnector,
-  serviceName: 'invoice-service',
-  defaultTimeout: 60000
-});
-```
-<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
-
-#### new OrchestratorConnector(config)
-Creates a new OrchestratorConnector instance
-
-**Throws**:
-
-- <code>TypeError</code> If required dependencies are missing
-
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| config | <code>Object</code> |  | Configuration object |
-| config.mqClient | <code>Object</code> |  | MQ client connector for message routing |
-| config.cookbook | <code>Object</code> |  | Cookbook connector for workflow parsing |
-| [config.apiMapper] | <code>Object</code> |  | API mapper for HTTP calls |
-| [config.cache] | <code>Object</code> |  | Cache connector for step caching |
-| [config.logger] | <code>Object</code> | <code>console</code> | Logger instance |
-| [config.serviceName] | <code>string</code> | <code>&quot;&#x27;unknown&#x27;&quot;</code> | Service name for tracing |
-| [config.defaultTimeout] | <code>number</code> | <code>30000</code> | Default timeout in ms |
-| [config.maxStepRetries] | <code>number</code> | <code>3</code> | Maximum retries per step |
-
-**Example** *(Full Configuration)*  
-```js
-const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  cache: cacheConnector,
-  logger: loggerConnector,
-  serviceName: 'invoice-service',
-  defaultTimeout: 60000,
-  maxStepRetries: 5
-});
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector"></a>
-
-### @onlineapps/conn-orch-orchestrator~OrchestratorConnector
-**Kind**: inner class of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-
-* [~OrchestratorConnector](#module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector)
-    * [new OrchestratorConnector()](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-    * [new OrchestratorConnector(config)](#new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new)
-
-<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
-
-#### new OrchestratorConnector()
-Workflow orchestration connector managing complete workflow execution
-
-**Example** *(Basic Usage)*  
-```js
-const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  serviceName: 'invoice-service'
-});
-
-await orchestrator.processWorkflowMessage(message);
-```
-**Example** *(With Caching)*  
-```js
-const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  cache: cacheConnector,
-  serviceName: 'invoice-service',
-  defaultTimeout: 60000
-});
+```bash
+npm install @onlineapps/conn-orch-orchestrator
 ```
-<a name="new_module_@onlineapps/conn-orch-orchestrator..OrchestratorConnector_new"></a>
 
-#### new OrchestratorConnector(config)
-Creates a new OrchestratorConnector instance
+## Quick Start
 
-**Throws**:
+```javascript
+const { OrchestratorConnector } = require('@onlineapps/conn-orch-orchestrator');
 
-- <code>TypeError</code> If required dependencies are missing
-
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| config | <code>Object</code> |  | Configuration object |
-| config.mqClient | <code>Object</code> |  | MQ client connector for message routing |
-| config.cookbook | <code>Object</code> |  | Cookbook connector for workflow parsing |
-| [config.apiMapper] | <code>Object</code> |  | API mapper for HTTP calls |
-| [config.cache] | <code>Object</code> |  | Cache connector for step caching |
-| [config.logger] | <code>Object</code> | <code>console</code> | Logger instance |
-| [config.serviceName] | <code>string</code> | <code>&quot;&#x27;unknown&#x27;&quot;</code> | Service name for tracing |
-| [config.defaultTimeout] | <code>number</code> | <code>30000</code> | Default timeout in ms |
-| [config.maxStepRetries] | <code>number</code> | <code>3</code> | Maximum retries per step |
-
-**Example** *(Full Configuration)*  
-```js
 const orchestrator = new OrchestratorConnector({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  apiMapper: apiMapperConnector,
-  cache: cacheConnector,
-  logger: loggerConnector,
-  serviceName: 'invoice-service',
-  defaultTimeout: 60000,
-  maxStepRetries: 5
+  amqpUrl: process.env.AMQP_URL,
+  storageUrl: process.env.MINIO_URL
 });
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..processWorkflowMessage"></a>
 
-### @onlineapps/conn-orch-orchestrator~processWorkflowMessage(message) ⇒ <code>Promise.&lt;WorkflowResult&gt;</code> \| <code>boolean</code> \| <code>string</code> \| <code>number</code>
-Process workflow message - main entry point
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;WorkflowResult&gt;</code> - Processing result<code>boolean</code> - result.success - Whether processing succeeded<code>string</code> - result.workflowId - Workflow ID<code>number</code> - result.duration - Processing duration in ms  
-**Throws**:
-
-- <code>Error</code> If cookbook validation fails
-- <code>Error</code> If step processing fails
-
-**Emits**: [<code>completed</code>](#OrchestratorConnector+workflow.event_completed), [<code>failed</code>](#OrchestratorConnector+workflow.event_failed)  
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| message | <code>WorkflowMessage</code> |  | Workflow message to process |
-| [message.workflow_id] | <code>string</code> |  | Unique workflow ID |
-| message.cookbook | <code>Object</code> |  | Cookbook definition |
-| [message.current_step] | <code>number</code> | <code>0</code> | Current step index |
-| [message.context] | <code>Object</code> | <code>{}</code> | Workflow context data |
-| [message.trace] | <code>Array</code> | <code>[]</code> | Execution trace |
-
-**Example** *(Process Workflow)*  
-```js
+// Process workflow message
 const result = await orchestrator.processWorkflowMessage({
-  workflow_id: 'wf-123',
-  cookbook: cookbookDef,
-  current_step: 0,
-  context: { invoice_id: 'inv-456' }
+  workflowId: 'wf-123',
+  steps: [
+    { service: 'validation', operation: 'validate' },
+    { service: 'processing', operation: 'process' },
+    { service: 'notification', operation: 'notify' }
+  ],
+  currentStep: 0,
+  context: { /* workflow data */ }
 });
 
-if (result.success) {
-  console.log(`Workflow completed in ${result.duration}ms`);
-}
-```
-**Example** *(With Error Handling)*  
-```js
-try {
-  await orchestrator.processWorkflowMessage(message);
-} catch (error) {
-  console.error('Workflow failed:', error);
-  // Message sent to DLQ automatically
-}
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..processStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~processStep(message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Process single workflow step
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - Step execution result  
-**Throws**:
-
-- <code>Error</code> If step not found in cookbook
-- <code>Error</code> If API call fails and onError is not 'continue'
-
-
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>WorkflowMessage</code> | Workflow message with step info |
-
-**Example** *(Process Regular Step)*  
-```js
-const result = await orchestrator.processStep({
-  cookbook: cookbook,
-  current_step: 2,
-  context: { data: 'value' }
-});
-```
-**Example** *(Process Control Flow Step)*  
-```js
-const result = await orchestrator.processStep({
-  cookbook: { steps: [{ type: 'foreach', items: [...] }] },
-  current_step: 0
-});
+// Get statistics
+const stats = orchestrator.getStats();
+console.log(`Processed: ${stats.processed}, Failed: ${stats.failed}`);
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleControlFlow"></a>
-
-### @onlineapps/conn-orch-orchestrator~handleControlFlow(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Handle control flow steps (if, foreach, fork_join, switch)
 
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - Control flow execution result  
-**Throws**:
+## Configuration
 
-- <code>Error</code> If unknown control flow type
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AMQP_URL` | RabbitMQ connection URL | required |
+| `STORAGE_URL` | MinIO storage URL | required |
+| `WORKFLOW_TIMEOUT` | Max workflow execution time (ms) | 300000 |
+| `MAX_RETRIES` | Maximum retry attempts | 3 |
 
+## Control Flow Patterns
 
-| Param | Type | Description |
-| --- | --- | --- |
-| step | <code>ControlFlowStep</code> | Control flow step definition |
-| step.type | <code>string</code> | Type: 'if', 'foreach', 'fork_join', 'switch' |
-| message | <code>WorkflowMessage</code> | Workflow message |
-
-**Example** *(If/Else Flow)*  
-```js
-await orchestrator.handleControlFlow({
+### If/Else
+```javascript
+{
   type: 'if',
-  condition: '${amount} > 1000',
-  then: { service: 'approval', operation: 'request' },
-  else: { service: 'payment', operation: 'process' }
-}, message);
-```
-**Example** *(Foreach Iteration)*  
-```js
-await orchestrator.handleControlFlow({
-  type: 'foreach',
-  items: '${invoices}',
-  do: { service: 'invoice', operation: 'process' }
-}, message);
-```
-**Example** *(Fork-Join Parallel)*  
-```js
-await orchestrator.handleControlFlow({
-  type: 'fork_join',
-  branches: [
-    { service: 'inventory', operation: 'check' },
-    { service: 'pricing', operation: 'calculate' }
-  ],
-  joinStrategy: 'merge'
-}, message);
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleIfStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~handleIfStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Handle if/else control flow
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - Branch execution result or null  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| step | <code>IfStep</code> | If step definition |
-| step.condition | <code>string</code> | Condition expression |
-| [step.then] | <code>Object</code> | Branch for true condition |
-| [step.else] | <code>Object</code> | Branch for false condition |
-| message | <code>WorkflowMessage</code> | Workflow message |
-
-**Example**  
-```js
-await orchestrator.handleIfStep({
-  condition: '${status} === "pending"',
-  then: { service: 'approval', operation: 'request' },
-  else: { service: 'notification', operation: 'send' }
-}, message);
+  condition: { field: 'status', operator: 'equals', value: 'active' },
+  then: { service: 'activeHandler' },
+  else: { service: 'inactiveHandler' }
+}
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleForeachStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~handleForeachStep(step, message) ⇒ <code>Promise.&lt;Array&gt;</code>
-Handle foreach iteration
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;Array&gt;</code> - Array of results from each iteration  
-**Throws**:
-
-- <code>Error</code> If items is not an array
-
 
-| Param | Type | Description |
-| --- | --- | --- |
-| step | <code>ForeachStep</code> | Foreach step definition |
-| step.items | <code>string</code> \| <code>Array</code> | Items to iterate (or path to items) |
-| step.do | <code>Object</code> | Step to execute for each item |
-| message | <code>WorkflowMessage</code> | Workflow message |
-
-**Example**  
-```js
-const results = await orchestrator.handleForeachStep({
-  items: '${invoice.line_items}',
-  do: { service: 'tax', operation: 'calculate' }
-}, message);
+### Switch/Case
+```javascript
+{
+  type: 'switch',
+  field: 'priority',
+  cases: {
+    'high': { service: 'urgentHandler' },
+    'normal': { service: 'standardHandler' },
+    'low': { service: 'batchHandler' }
+  },
+  default: { service: 'defaultHandler' }
+}
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleForkJoinStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~handleForkJoinStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Handle fork-join parallel execution
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - Joined results based on strategy  
-**Throws**:
-
-- <code>Error</code> If MQ client doesn't support fork-join
-
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| step | <code>ForkJoinStep</code> |  | Fork-join step definition |
-| step.branches | <code>Array.&lt;Object&gt;</code> |  | Parallel branches to execute |
-| [step.joinStrategy] | <code>string</code> | <code>&quot;&#x27;merge&#x27;&quot;</code> | Join strategy: 'merge', 'array', 'first' |
-| [step.timeout] | <code>number</code> |  | Overall timeout for all branches |
-| message | <code>WorkflowMessage</code> |  | Workflow message |
 
-**Example**  
-```js
-const result = await orchestrator.handleForkJoinStep({
-  branches: [
-    { service: 'inventory', operation: 'reserve' },
-    { service: 'payment', operation: 'authorize' },
-    { service: 'shipping', operation: 'estimate' }
-  ],
-  joinStrategy: 'merge',
-  timeout: 10000
-}, message);
+### Foreach
+```javascript
+{
+  type: 'foreach',
+  items: 'context.items',
+  step: { service: 'itemProcessor' }
+}
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleSwitchStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~handleSwitchStep(step, message) ⇒ <code>Promise.&lt;\*&gt;</code>
-Handle switch statement
 
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>Promise.&lt;\*&gt;</code> - Matched case execution result or null  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| step | <code>SwitchStep</code> | Switch step definition |
-| step.value | <code>string</code> | Value expression to switch on |
-| step.cases | <code>Array.&lt;Object&gt;</code> | Case definitions |
-| [step.default] | <code>Object</code> | Default case |
-| message | <code>WorkflowMessage</code> | Workflow message |
-
-**Example**  
-```js
-await orchestrator.handleSwitchStep({
-  value: '${order.type}',
-  cases: [
-    { value: 'standard', do: { service: 'shipping', operation: 'standard' } },
-    { value: 'express', do: { service: 'shipping', operation: 'express' } }
+### Fork-Join
+```javascript
+{
+  type: 'fork-join',
+  parallel: [
+    { service: 'validator' },
+    { service: 'enricher' },
+    { service: 'scorer' }
   ],
-  default: { do: { service: 'shipping', operation: 'economy' } }
-}, message);
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..routeToNextService"></a>
-
-### @onlineapps/conn-orch-orchestrator~routeToNextService(message, nextService, stepResult, nextIndex) ⇒ <code>Promise.&lt;void&gt;</code>
-Route to next service in workflow
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Emits**: <code>MQClient#event:publish - Publishes to next service queue</code>  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>WorkflowMessage</code> | Current workflow message |
-| nextService | <code>string</code> | Next service name |
-| stepResult | <code>\*</code> | Current step result |
-| nextIndex | <code>number</code> | Next step index |
-
-**Example**  
-```js
-await orchestrator.routeToNextService(
-  message,
-  'invoice-service',
-  { processed: true, total: 1500 },
-  3
-);
-// Message published to 'invoice-service.workflow' queue
+  join: { service: 'aggregator' }
+}
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..completeWorkflow"></a>
 
-### @onlineapps/conn-orch-orchestrator~completeWorkflow(message, finalResult) ⇒ <code>Promise.&lt;void&gt;</code>
-Complete workflow
+## API Reference
 
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Emits**: <code>MQClient#workflow.event:completed - Workflow completion event</code>  
+### OrchestratorConnector
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>WorkflowMessage</code> | Workflow message |
-| finalResult | <code>\*</code> | Final workflow result |
+Main orchestrator class for workflow execution.
 
-**Example**  
-```js
-await orchestrator.completeWorkflow(message, {
-  status: 'success',
-  invoice_id: 'inv-789',
-  total: 1500
-});
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..handleWorkflowFailure"></a>
+#### Methods
 
-### @onlineapps/conn-orch-orchestrator~handleWorkflowFailure(message, error) ⇒ <code>Promise.&lt;void&gt;</code>
-Handle workflow failure
+- `processWorkflowMessage(message)` - Process a workflow message
+- `processStep(message)` - Process a single workflow step
+- `handleControlFlow(step, message)` - Handle control flow steps
+- `routeToNextService(message, nextService, result, nextIndex)` - Route to next service
+- `completeWorkflow(message, result)` - Complete workflow execution
+- `handleWorkflowFailure(message, error)` - Handle workflow failures
+- `getStats()` - Get execution statistics
+- `resetStats()` - Reset statistics
 
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Emits**: <code>MQClient#workflow.event:dlq - Sends to dead letter queue</code>  
+## Testing
 
-| Param | Type | Description |
-| --- | --- | --- |
-| message | <code>WorkflowMessage</code> | Workflow message |
-| error | <code>Error</code> | Failure error |
+```bash
+# Run all tests
+npm test
 
-**Example**  
-```js
-await orchestrator.handleWorkflowFailure(message,
-  new Error('Service unavailable')
-);
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..getStats"></a>
+# Run unit tests
+npm run test:unit
 
-### @onlineapps/conn-orch-orchestrator~getStats() ⇒ <code>OrchestratorStats</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code> \| <code>number</code>
-Get orchestrator statistics
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>OrchestratorStats</code> - Current statistics<code>number</code> - stats.started - Workflows started<code>number</code> - stats.completed - Workflows completed<code>number</code> - stats.failed - Workflows failed<code>number</code> - stats.steps - Total steps processed<code>number</code> - stats.avgDuration - Average duration in ms<code>number</code> - stats.activeWorkflows - Currently active workflows  
-**Example**  
-```js
-const stats = orchestrator.getStats();
-console.log(`Success rate: ${stats.completed / stats.started * 100}%`);
-console.log(`Average duration: ${stats.avgDuration}ms`);
+# Run integration tests
+npm run test:integration
 ```
-<a name="module_@onlineapps/conn-orch-orchestrator..resetStats"></a>
-
-### @onlineapps/conn-orch-orchestrator~resetStats() ⇒ <code>void</code>
-Reset statistics
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Example**  
-```js
-orchestrator.resetStats();
-// All counters reset to 0
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..create"></a>
-
-### @onlineapps/conn-orch-orchestrator~create(config) ⇒ <code>OrchestratorConnector</code>
-Factory function to create orchestrator instance
-
-**Kind**: inner method of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Returns**: <code>OrchestratorConnector</code> - New orchestrator instance  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| config | <code>Object</code> | Configuration object |
-
-**Example**  
-```js
-const orchestrator = OrchestratorConnector.create({
-  mqClient: mqConnector,
-  cookbook: cookbookConnector,
-  serviceName: 'invoice-service'
-});
-```
-<a name="module_@onlineapps/conn-orch-orchestrator..WorkflowMessage"></a>
-
-### @onlineapps/conn-orch-orchestrator~WorkflowMessage : <code>Object</code>
-**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Properties**
-
-| Name | Type | Default | Description |
-| --- | --- | --- | --- |
-| [workflow_id] | <code>string</code> |  | Unique workflow identifier |
-| cookbook | <code>Object</code> |  | Cookbook definition |
-| [current_step] | <code>number</code> | <code>0</code> | Current step index |
-| [context] | <code>Object</code> | <code>{}</code> | Workflow context data |
-| [trace] | <code>Array</code> | <code>[]</code> | Execution trace |
-| [correlation_id] | <code>string</code> |  | Correlation ID for tracing |
-
-<a name="module_@onlineapps/conn-orch-orchestrator..WorkflowResult"></a>
-
-### @onlineapps/conn-orch-orchestrator~WorkflowResult : <code>Object</code>
-**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| success | <code>boolean</code> | Whether workflow succeeded |
-| workflowId | <code>string</code> | Workflow identifier |
-| duration | <code>number</code> | Processing duration in ms |
-
-<a name="module_@onlineapps/conn-orch-orchestrator..ControlFlowStep"></a>
-
-### @onlineapps/conn-orch-orchestrator~ControlFlowStep : <code>Object</code>
-**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| type | <code>string</code> | Control flow type: 'if', 'foreach', 'fork_join', 'switch' |
-| [condition] | <code>\*</code> | Condition for if steps |
-| [items] | <code>\*</code> | Items for foreach steps |
-| [branches] | <code>Array</code> | Branches for fork_join |
-| [value] | <code>string</code> | Value for switch steps |
-
-<a name="module_@onlineapps/conn-orch-orchestrator..OrchestratorStats"></a>
-
-### @onlineapps/conn-orch-orchestrator~OrchestratorStats : <code>Object</code>
-**Kind**: inner typedef of [<code>@onlineapps/conn-orch-orchestrator</code>](#module_@onlineapps/conn-orch-orchestrator)  
-**Properties**
 
-| Name | Type | Description |
-| --- | --- | --- |
-| started | <code>number</code> | Workflows started |
-| completed | <code>number</code> | Workflows completed |
-| failed | <code>number</code> | Workflows failed |
-| steps | <code>number</code> | Total steps processed |
-| avgDuration | <code>number</code> | Average duration in ms |
-| activeWorkflows | <code>number</code> | Currently active workflows |
+## 📚 Documentation
 
+- [Complete Connectors Documentation](../../../docs/modules/connector.md)
+- [Workflow Architecture](../../../docs/modules/workflow.md)
+- [Testing Standards](../../../docs/modules/connector.md#testing-standards)

package/jest.config.js

@@ -6,9 +6,9 @@ module.exports = {
     '!src/**/*.test.js'
   ],
   testMatch: [
-    '**/test/unit/**/*.test.js',
-    '**/test/component/**/*.test.js',
-    '**/test/integration/**/*.test.js'
+    '**/tests/unit/**/*.test.js',
+    '**/tests/component/**/*.test.js',
+    '**/tests/integration/**/*.test.js'
   ],
   testPathIgnorePatterns: [
     '/node_modules/'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-orchestrator",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Workflow orchestration connector for OA Drive - handles message routing and workflow execution",
   "main": "src/index.js",
   "scripts": {
@@ -20,7 +20,7 @@
   "author": "OA Drive Team",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/conn-base-logger": "^1.0.0",
+    "@onlineapps/conn-base-monitoring": "^1.0.0",
     "@onlineapps/conn-infra-mq": "^1.1.0",
     "@onlineapps/conn-orch-registry": "^1.1.4",
     "@onlineapps/conn-orch-cookbook": "^2.0.0",
@@ -38,4 +38,4 @@
       "src/**/*.js"
     ]
   }
-}
+}

package/src/WorkflowOrchestrator.js

@@ -70,6 +70,14 @@ class WorkflowOrchestrator {
       // Validate cookbook structure
       this.cookbook.validateCookbook(cookbookDef);
 
+      // Ensure delivery configuration is preserved in context (required by Delivery Dispatcher)
+      // Delivery comes from cookbook.delivery (set by Gateway) and must be passed through to workflow.completed
+      const enrichedContext = {
+        ...context,
+        // Preserve delivery from cookbook if not already in context
+        delivery: context?.delivery || cookbookDef?.delivery || { handler: 'none' }
+      };
+
       // Find current step
       const step = cookbookDef.steps.find(s => s.id === current_step);
       if (!step) {
@@ -83,29 +91,52 @@ class WorkflowOrchestrator {
         return { skipped: true, reason: 'wrong_service' };
       }
 
+      // Publish workflow.progress to monitoring.workflow using unified helper
+      const { publishToMonitoringWorkflow } = require('@onlineapps/mq-client-core').monitoring;
+      try {
+        const stepIndex = cookbookDef.steps.findIndex(s => s.id === current_step);
+        await publishToMonitoringWorkflow(this.mqClient, {
+          event_type: 'progress',
+          workflow_id: workflow_id,
+          service_name: serviceName,
+          step_index: stepIndex >= 0 ? stepIndex : 0,
+          step_id: current_step,
+          cookbook: cookbookDef,
+          context: enrichedContext,
+          status: 'in_progress',
+          timestamp: new Date().toISOString()
+        }, this.logger, { workflow_id, step_id: current_step });
+      } catch (monitoringError) {
+        // Don't fail workflow if monitoring publish fails (helper already logs)
+        this.logger.warn('Failed to publish workflow.progress to monitoring', {
+          workflow_id,
+          error: monitoringError.message
+        });
+      }
+
       // Check cache if available
       let result;
       if (this.cache && step.type === 'task') {
-        const cacheKey = this._getCacheKey(step, context);
+        const cacheKey = this._getCacheKey(step, enrichedContext);
         result = await this.cache.get(cacheKey);
 
         if (result) {
           this.logger.info('Cache hit', { step: step.id, cacheKey });
         } else {
           // Execute the step
-          result = await this._executeStep(step, context, cookbookDef);
+          result = await this._executeStep(step, enrichedContext, cookbookDef);
           await this.cache.set(cacheKey, result, { ttl: 300 });
         }
       } else {
         // Execute without cache
-        result = await this._executeStep(step, context, cookbookDef);
+        result = await this._executeStep(step, enrichedContext, cookbookDef);
       }
 
-      // Update context with result
+      // Update context with result (preserve delivery from enrichedContext)
       const updatedContext = {
-        ...context,
+        ...enrichedContext,
         steps: {
-          ...context.steps,
+          ...enrichedContext.steps,
           [current_step]: result
         }
       };
@@ -130,11 +161,34 @@ class WorkflowOrchestrator {
       };
 
     } catch (error) {
-      this.logger.error(`Workflow processing failed: ${error.message}`, {
-        workflow_id,
-        current_step,
-        error: error.stack
-      });
+      // Publish to workflow.failed queue
+      try {
+        console.log(`[WorkflowOrchestrator] [PUBLISH] Preparing to publish workflow.failed for ${workflow_id}`);
+        this.logger.error(`[WorkflowOrchestrator] [PUBLISH] Workflow processing failed: ${error.message}`, {
+          workflow_id,
+          current_step,
+          error: error.stack
+        });
+        
+        await this.mqClient.publish('workflow.failed', {
+          workflow_id,
+          current_step,
+          error: error.message,
+          errorStack: error.stack,
+          failed_at: new Date().toISOString()
+        });
+        
+        console.log(`[WorkflowOrchestrator] [PUBLISH] ✓ Successfully published workflow.failed for ${workflow_id}`);
+        this.logger.info(`[WorkflowOrchestrator] [PUBLISH] ✓ Published workflow.failed: ${workflow_id}`);
+      } catch (publishError) {
+        console.error(`[WorkflowOrchestrator] [PUBLISH] ✗ Failed to publish workflow.failed for ${workflow_id}:`, publishError.message);
+        this.logger.error(`[WorkflowOrchestrator] [PUBLISH] ✗ Failed to publish workflow.failed`, {
+          workflow_id,
+          originalError: error.message,
+          publishError: publishError.message
+        });
+        // Don't throw - original error is more important
+      }
 
       // Handle error
       if (this.errorHandler) {
@@ -273,13 +327,41 @@ class WorkflowOrchestrator {
    * @param {Object} finalContext - Final workflow context
    */
   async _completeWorkflow(workflow_id, finalContext) {
-    await this.mqClient.publish('workflow.completed', {
-      workflow_id,
-      result: finalContext,
-      completed_at: new Date().toISOString()
-    });
+    try {
+      console.log(`[WorkflowOrchestrator] [PUBLISH] Preparing to publish workflow.completed for ${workflow_id}`);
+      this.logger.info(`[WorkflowOrchestrator] [PUBLISH] Preparing to publish workflow.completed`, {
+        workflow_id,
+        hasMqClient: !!this.mqClient,
+        mqClientConnected: this.mqClient?._connected
+      });
+      
+      // Extract delivery configuration from context (passed from Gateway)
+      // Delivery Dispatcher requires: workflow_id, status, delivery (must be object, not null)
+      const delivery = finalContext?.delivery || { handler: 'none' }; // Default to 'none' handler if not provided
+      
+      // Build message in format expected by Delivery Dispatcher
+      const workflowCompletedMessage = {
+        workflow_id,
+        status: 'completed',
+        delivery: delivery, // Delivery configuration from Gateway context (must be object)
+        context: finalContext, // Full context for output resolution
+        steps: finalContext?.steps || {}, // Steps results for output resolution
+        completed_at: new Date().toISOString()
+      };
+      
+      await this.mqClient.publish('workflow.completed', workflowCompletedMessage);
 
-    this.logger.info(`Workflow completed: ${workflow_id}`);
+      console.log(`[WorkflowOrchestrator] [PUBLISH] ✓ Successfully published workflow.completed for ${workflow_id}`);
+      this.logger.info(`[WorkflowOrchestrator] [PUBLISH] ✓ Workflow completed: ${workflow_id}`);
+    } catch (error) {
+      console.error(`[WorkflowOrchestrator] [PUBLISH] ✗ Failed to publish workflow.completed for ${workflow_id}:`, error.message);
+      this.logger.error(`[WorkflowOrchestrator] [PUBLISH] ✗ Failed to publish workflow.completed`, {
+        workflow_id,
+        error: error.message,
+        errorStack: error.stack
+      });
+      throw error; // Re-throw to allow ServiceWrapper to handle
+    }
   }
 
   /**

package/{test → tests}/component/orchestrator.component.test.js

@@ -7,7 +7,7 @@
 
 const WorkflowOrchestrator = require('../../src/WorkflowOrchestrator');
 
-describe('Orchestrator - Component Tests', () => {
+describe('Orchestrator - Component Tests @component', () => {
   let orchestrator;
   let mqClientStub;
   let registryClientStub;

package/{test → tests}/integration/orchestrator.integration.test.js

@@ -13,10 +13,11 @@ const CookbookConnector = require('@onlineapps/conn-orch-cookbook');
 
 // Skip integration tests if external services are not available
 const SKIP_INTEGRATION = process.env.SKIP_INTEGRATION === 'true';
-const RABBITMQ_URL = process.env.RABBITMQ_URL || 'amqp://localhost:5672';
-const REGISTRY_URL = process.env.REGISTRY_URL || 'http://localhost:4000';
+const { requireEnv } = require('../../../../../tests/_helpers/test-config');
+const RABBITMQ_URL = requireEnv('RABBITMQ_URL', 'RabbitMQ connection URL');
+const REGISTRY_URL = requireEnv('REGISTRY_URL', 'Registry service URL');
 
-describe('Orchestrator - Integration Tests', () => {
+describe('Orchestrator - Integration Tests @integration', () => {
   if (SKIP_INTEGRATION) {
     it.skip('Skipping integration tests (SKIP_INTEGRATION=true)', () => {});
     return;

package/{test → tests}/unit/WorkflowOrchestrator.test.js

@@ -7,7 +7,7 @@
 
 const WorkflowOrchestrator = require('../../src/WorkflowOrchestrator');
 
-describe('WorkflowOrchestrator - Unit Tests', () => {
+describe('WorkflowOrchestrator - Unit Tests @unit', () => {
   let orchestrator;
   let mockMqClient;
   let mockRegistryClient;