@onlineapps/conn-orch-cookbook 2.0.1 → 2.0.3

package/README.md

@@ -1,10 +1,10 @@
-# @onlineapps/connector-cookbook
+# @onlineapps/conn-orch-cookbook
 
 > Complete cookbook toolkit for ALL services - unified wrapper including core, executor, transformer, and router functionality
 
 ## 🚀 Version 2.0 - Major Update
 
-The `connector-cookbook` package (v2.0) is now a complete toolkit that combines all cookbook functionality in one unified package. This ensures architectural consistency across ALL services including infrastructure components like workflow_launcher.
+The `conn-orch-cookbook` package (v2.0) is now a complete toolkit that combines all cookbook functionality in one unified package. This ensures architectural consistency across ALL services including infrastructure components like workflow_launcher.
 
 ### What's New in v2.0
 
@@ -24,9 +24,9 @@ Per architectural decision, ALL services including workflow_launcher use this si
 ## 📦 Installation
 
 ```bash
-npm install @onlineapps/connector-cookbook
+npm install @onlineapps/conn-orch-cookbook
 # or
-yarn add @onlineapps/connector-cookbook
+yarn add @onlineapps/conn-orch-cookbook
 ```
 
 ## 🔧 Quick Start
@@ -37,7 +37,7 @@ yarn add @onlineapps/connector-cookbook
 const {
   parseCookbookFromFile,
   validateCookbook
-} = require('@onlineapps/connector-cookbook');
+} = require('@onlineapps/conn-orch-cookbook');
 
 // Works exactly as before
 const cookbook = await parseCookbookFromFile('./workflow.json');
@@ -47,7 +47,7 @@ validateCookbook(cookbook);
 ### New Modular Approach (v2.0)
 
 ```javascript
-const cookbook = require('@onlineapps/connector-cookbook');
+const cookbook = require('@onlineapps/conn-orch-cookbook');
 
 // Use specific modules
 const { CookbookExecutor } = cookbook.executor;
@@ -92,9 +92,9 @@ const processor = cookbook.createProcessor({
 ### Complete Service Implementation
 
 ```javascript
-const cookbook = require('@onlineapps/connector-cookbook');
-const MQClient = require('@onlineapps/connector-mq-client');
-const RegistryClient = require('@onlineapps/connector-registry-client');
+const cookbook = require('@onlineapps/conn-orch-cookbook');
+const MQClient = require('@onlineapps/conn-infra-mq');
+const RegistryClient = require('@onlineapps/conn-orch-registry');
 
 class MyService {
   constructor() {
@@ -133,7 +133,7 @@ class MyService {
 
 ```javascript
 // workflow_launcher uses the SAME package
-const cookbook = require('@onlineapps/connector-cookbook');
+const cookbook = require('@onlineapps/conn-orch-cookbook');
 
 class WorkflowLauncher {
   async handleWorkflowInit(message) {
@@ -152,7 +152,7 @@ class WorkflowLauncher {
 ### OpenAPI Integration
 
 ```javascript
-const { CookbookGenerator } = require('@onlineapps/connector-cookbook');
+const { CookbookGenerator } = require('@onlineapps/conn-orch-cookbook');
 
 const generator = new CookbookGenerator({
   defaultTimeout: 10000,
@@ -166,29 +166,30 @@ const cookbook = generator.generate(openApiSpec);
 
 ## 📖 Cookbook Structure
 
-### Basic Example
+### Basic Example (v2.0 Schema)
 ```json
 {
-  "version": "1.0.0",
+  "version": "2.0.0",
   "api_input": {
     "customer": "ACME Corp",
     "amount": 1000
   },
   "steps": [
     {
-      "id": "invoice_step",
+      "step_id": "invoice_step",
       "type": "task",
-      "service": "invoice_service",
+      "service": "invoice-service",
+      "operation": "createInvoice",
       "input": {
-        "customer": "$api_input.customer",
-        "amount": "$api_input.amount"
+        "customer": "${api_input.customer}",
+        "amount": "${api_input.amount}"
       },
       "output": {
-        "invoice_id": "$.invoice_id"
+        "invoice_id": "${response.invoice_id}"
       },
       "retry": {
-        "maxAttempts": 3,
-        "delayMs": 2000
+        "max_attempts": 3,
+        "delay_ms": 2000
       }
     }
   ]
@@ -207,13 +208,54 @@ All 7 step types are fully supported:
 - **wait** - Time delays
 - **dispatch** - Webhook dispatching
 
+## 📤 Delivery Block (v2.1)
+
+Cookbook nově může definovat top-level sekci `delivery`, která popisuje způsob
+doručení výsledku klientovi:
+
+```json
+"delivery": {
+  "handler": "dispatcher",
+  "allow_skip": false,
+  "destinations": [
+    {
+      "type": "webhook",
+      "url": "https://client.example.com/api/callback",
+      "method": "POST",
+      "retry": {
+        "max_attempts": 5,
+        "delay_ms": 3000
+      }
+    },
+    {
+      "type": "public_url",
+      "path": "result/${context.workflow_id}/invoice.pdf",
+      "ttl_seconds": 86400,
+      "access": "signed"
+    }
+  ],
+  "output": {
+    "workflow_id": "${context.workflow_id}",
+    "invoice_id": "${steps.invoice_step.output.invoice_id}"
+  }
+}
+```
+
+- `handler`: `dispatcher` (výchozí), `service_step`, nebo `none`.
+- `destinations`: konkrétní výstupy (`webhook`, `websocket`, `public_url`).
+- `output`: mapování hodnot, které se mají doručit.
+
+Detailní specifikace viz
+[Schema Final Specification](/shared/cookbook/cookbook-core/docs/SCHEMA_FINAL_SPECIFICATION.md#11-delivery-blok)
+nebo [API Delivery Dispatcher](../../../docs/architecture/api-delivery-dispatcher.md).
+
 ## 🔄 Migration from v1.x
 
 Version 2.0 maintains full backward compatibility. Existing code continues to work without changes:
 
 ```javascript
 // This still works exactly as before
-const { parseCookbookFromFile } = require('@onlineapps/connector-cookbook');
+const { parseCookbookFromFile } = require('@onlineapps/conn-orch-cookbook');
 const cookbook = await parseCookbookFromFile('./workflow.json');
 ```
 
@@ -221,7 +263,7 @@ To access new features, use the modular exports:
 
 ```javascript
 // New modular approach
-const { executor, router, transformer } = require('@onlineapps/connector-cookbook');
+const { executor, router, transformer } = require('@onlineapps/conn-orch-cookbook');
 ```
 
 ## 📋 API Reference
@@ -250,25 +292,33 @@ npm run test:integration  # Integration tests
 
 ## ⚠️ Important Notes
 
-### Schema Validation Strictness
-The current schema validation is very strict. See [Schema Audit Report](/shared/cookbook/cookbook-core/docs/SCHEMA_AUDIT.md) for detailed analysis and recommendations.
+### Schema v2.0 Update
+The cookbook schema has been updated to version 2.0 with improved semantics and consistency:
 
-**Known Issues:**
-- All step types incorrectly require `service`, `input`, and `output` fields
-- `type` field should be required but isn't
-- Some control flow steps (foreach, switch) have unnecessary field requirements
+**Major Changes:**
+- All naming conventions now use snake_case (not camelCase)
+- Field `id` renamed to `step_id` for clarity
+- Field `operation` is now required only for task steps (maps to OpenAPI operationId)
+- Removed explicit `queue` field (now implicit from service name)
+- Added comprehensive error handling and compensation support
 
-**Workaround:** Until schema is updated, include all required fields even if not used:
+**Example v2.0 step:**
 ```javascript
 {
+  step_id: 'process_items',
   type: 'foreach',
-  service: 'dummy-service',  // Not actually used
-  input: {},                 // Not actually used
-  output: {},                // Optional but may be required by schema
-  // ... actual foreach fields
+  iterator: '${api_input.items}',
+  steps: [
+    // nested steps
+  ],
+  output: {
+    processed_items: '${foreach.results}'
+  }
 }
 ```
 
+See [Schema v2.0 Specification](/shared/cookbook/cookbook-core/docs/SCHEMA_FINAL_SPECIFICATION.md) for full details.
+
 ## 📄 License
 
 PROPRIETARY - All rights reserved

package/docs/DETAILED_API.md

@@ -0,0 +1,117 @@
+# Cookbook Connector - Detailed API Documentation
+
+## API Methods
+
+### CookbookConnector Class
+
+```javascript
+class CookbookConnector {
+  validateCookbook(cookbook) // Validates entire cookbook
+  getCurrentStep(cookbook, stepIndex) // Returns current step details
+  getNextStepIndex(cookbook, currentIndex, results) // Determines next step
+  evaluateCondition(condition, context) // For conditional flows
+  expandForeach(foreachStep, items) // Expands foreach into steps
+}
+```
+
+## What it DOES
+
+- Parses cookbook JSON structure
+- Validates cookbook schema
+- Extracts step information (service, operation, params)
+- Determines step sequence (next, previous)
+- Handles control flow logic (if, foreach, fork_join)
+
+## What it DOES NOT do
+
+- Does NOT execute operations
+- Does NOT make HTTP calls
+- Does NOT route messages
+- Does NOT handle errors
+
+## Usage Example
+
+```javascript
+const { CookbookConnector } = require('@onlineapps/conn-orch-cookbook');
+
+const connector = new CookbookConnector();
+
+// Validate cookbook
+const isValid = await connector.validateCookbook(cookbook);
+
+// Get current step
+const step = connector.getCurrentStep(cookbook, 0);
+// Returns: { service: 'hello-service', operation: 'greet', params: {...} }
+
+// Determine next step based on results
+const nextIndex = connector.getNextStepIndex(cookbook, 0, stepResults);
+// Returns: 1 (or -1 if workflow complete)
+
+// Evaluate conditional logic
+const shouldProceed = connector.evaluateCondition(
+  step.condition,
+  { result: stepResults }
+);
+
+// Expand foreach into multiple steps
+const expandedSteps = connector.expandForeach(foreachStep, itemArray);
+```
+
+## Control Flow Patterns
+
+### Sequential Execution
+```javascript
+steps: [
+  { service: 'service1', operation: 'op1' },
+  { service: 'service2', operation: 'op2' },
+  { service: 'service3', operation: 'op3' }
+]
+```
+
+### Conditional Execution
+```javascript
+{
+  service: 'service1',
+  operation: 'check',
+  condition: 'result.status === "approved"',
+  next_if_true: 'approve_step',
+  next_if_false: 'reject_step'
+}
+```
+
+### Parallel Execution (Fork-Join)
+```javascript
+{
+  type: 'fork_join',
+  parallel_steps: [
+    { service: 'service1', operation: 'op1' },
+    { service: 'service2', operation: 'op2' },
+    { service: 'service3', operation: 'op3' }
+  ],
+  join_strategy: 'all' // or 'any', 'threshold'
+}
+```
+
+### Iteration (Foreach)
+```javascript
+{
+  type: 'foreach',
+  items: 'context.items',
+  step_template: {
+    service: 'processor',
+    operation: 'process_item',
+    params: { item: '{{current_item}}' }
+  }
+}
+```
+
+## Error Handling
+
+The connector validates but does NOT handle errors. Error handling is done by:
+- `conn-infra-error-handler` for error classification
+- Service wrapper for retry logic
+- MQ connector for DLQ routing
+
+## Testing
+
+See test examples in `/test/unit/` and `/test/integration/` directories.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-cookbook",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Complete cookbook toolkit for all services - unified wrapper including core, executor, transformer, and router functionality",
   "main": "src/index.js",
   "repository": {
@@ -20,8 +20,8 @@
     "test:unit": "jest --testPathPattern=unit --coverage",
     "test:component": "jest --testPathPattern=component --coverage",
     "test:integration": "jest --testPathPattern=integration --coverage",
-    "test:fixtures": "jest test/integration/cookbook-fixtures.test.js",
-    "test:smoke": "jest test/smoke.test.js",
+    "test:fixtures": "jest tests/integration/cookbook-fixtures.test.js",
+    "test:smoke": "jest tests/smoke.test.js",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage --coverageReporters=text-lcov html",
     "lint": "eslint \"src/**/*.js\" \"tests/**/*.js\"",
@@ -46,10 +46,11 @@
   },
   "homepage": "https://github.com/onlineapps/connector-cookbook#readme",
   "dependencies": {
-    "@onlineapps/cookbook-core": "^1.0.0",
+    "@onlineapps/cookbook-core": "^2.0.0",
     "@onlineapps/cookbook-executor": "^1.0.0",
     "@onlineapps/cookbook-router": "^1.0.0",
-    "@onlineapps/cookbook-transformer": "^1.0.0"
+    "@onlineapps/cookbook-transformer": "1.1.0",
+    "jsonpath": "^1.1.1"
   },
   "devDependencies": {
     "eslint": "^8.30.0",