@onlineapps/conn-orch-cookbook/README.md

Complete cookbook toolkit for all services - unified wrapper including core, executor, transformer, and router functionality

# @onlineapps/connector-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.

### What's New in v2.0

- **Modular architecture** - Four specialized modules combined
- **Backward compatibility** - All v1.x APIs still work
- **Unified approach** - Same package for ALL services (infrastructure and business)
- **Complete toolkit** - Parsing, execution, transformation, and routing

### Why Unified Approach?

Per architectural decision, ALL services including workflow_launcher use this single package to ensure:
- **Consistency** - Same API everywhere
- **Predictability** - No special cases
- **Maintainability** - Single source of truth
- **Simplicity** - One package to learn

## 📦 Installation

```bash
npm install @onlineapps/connector-cookbook
# or
yarn add @onlineapps/connector-cookbook
```

## 🔧 Quick Start

### Backward Compatible (v1.x style)

```javascript
const {
  parseCookbookFromFile,
  validateCookbook
} = require('@onlineapps/connector-cookbook');

// Works exactly as before
const cookbook = await parseCookbookFromFile('./workflow.json');
validateCookbook(cookbook);
```

### New Modular Approach (v2.0)

```javascript
const cookbook = require('@onlineapps/connector-cookbook');

// Use specific modules
const { CookbookExecutor } = cookbook.executor;
const { CookbookRouter } = cookbook.router;
const { CookbookGenerator } = cookbook.transformer;

// Or use factory functions
const processor = cookbook.createProcessor({
  cookbook: myCookbook,
  maxRetries: 3
});
```

## 📚 Included Modules

### 1. Core Module (@onlineapps/cookbook-core)
- JSON Schema validation
- Recursive step validation
- Parsing from file/object
- Lightweight (~50KB)

### 2. Executor Module (@onlineapps/cookbook-executor)
- Workflow execution engine
- Context management
- Variable resolution ($api_input, $steps)
- Step processing for all types

### 3. Transformer Module (@onlineapps/cookbook-transformer)
- OpenAPI to cookbook generation
- API spec analysis
- Response mapping
- JSONPath transformations

### 4. Router Module (@onlineapps/cookbook-router)
- Service discovery
- Queue management
- Retry with exponential backoff
- Dead letter queue handling

## 🎯 Usage Examples

### Complete Service Implementation

```javascript
const cookbook = require('@onlineapps/connector-cookbook');
const MQClient = require('@onlineapps/connector-mq-client');
const RegistryClient = require('@onlineapps/connector-registry-client');

class MyService {
  constructor() {
    // Initialize clients
    this.mqClient = new MQClient(mqConfig);
    this.registryClient = new RegistryClient(registryConfig);

    // Create router for message handling
    this.router = cookbook.createRouter(
      this.mqClient,
      this.registryClient
    );
  }

  async processWorkflow(message) {
    // Parse and validate
    const workflowDef = cookbook.parseCookbookFromObject(message.cookbook);

    // Create executor
    const executor = new cookbook.CookbookExecutor(workflowDef);

    // Execute workflow
    const result = await executor.execute(message.context);

    // Route to next service
    await this.router.routeToNextService(
      workflowDef,
      result,
      message.current_step
    );
  }
}
```

### Infrastructure Service (workflow_launcher)

```javascript
// workflow_launcher uses the SAME package
const cookbook = require('@onlineapps/connector-cookbook');

class WorkflowLauncher {
  async handleWorkflowInit(message) {
    // Validate cookbook
    cookbook.validateCookbook(message.cookbook);

    // Route to first service
    await this.router.routeWorkflow(
      message.cookbook,
      message.context
    );
  }
}
```

### OpenAPI Integration

```javascript
const { CookbookGenerator } = require('@onlineapps/connector-cookbook');

const generator = new CookbookGenerator({
  defaultTimeout: 10000,
  defaultRetry: { maxAttempts: 3, delayMs: 2000 }
});

// Generate cookbook from OpenAPI spec
const openApiSpec = require('./api-spec.json');
const cookbook = generator.generate(openApiSpec);
```

## 📖 Cookbook Structure

### Basic Example (v2.0 Schema)
```json
{
  "version": "2.0.0",
  "api_input": {
    "customer": "ACME Corp",
    "amount": 1000
  },
  "steps": [
    {
      "step_id": "invoice_step",
      "type": "task",
      "service": "invoice-service",
      "operation": "createInvoice",
      "input": {
        "customer": "${api_input.customer}",
        "amount": "${api_input.amount}"
      },
      "output": {
        "invoice_id": "${response.invoice_id}"
      },
      "retry": {
        "max_attempts": 3,
        "delay_ms": 2000
      }
    }
  ]
}
```

## 📚 Step Types

All 7 step types are fully supported:

- **task** - Service operation execution
- **foreach** - Iteration over arrays
- **fork_join** - Parallel execution
- **switch** - Conditional branching
- **sub_workflow** - Nested workflows
- **wait** - Time delays
- **dispatch** - Webhook dispatching

## 🔄 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 cookbook = await parseCookbookFromFile('./workflow.json');
```

To access new features, use the modular exports:

```javascript
// New modular approach
const { executor, router, transformer } = require('@onlineapps/connector-cookbook');
```

## 📋 API Reference

### Legacy Exports (v1.x compatible)
- `parseCookbookFromFile(path)` - Parse from file
- `parseCookbookFromObject(obj)` - Parse from object
- `validateCookbook(cookbook)` - Validate structure
- `CookbookValidationError` - Error class

### New Modular Exports (v2.0)
- `core` - Core parsing and validation
- `executor` - Workflow execution
- `transformer` - OpenAPI transformation
- `router` - Message routing
- `createProcessor(options)` - Factory for complete processor
- `createRouter(mqClient, registryClient, options)` - Factory for router

## 🧪 Testing

```bash
npm test              # Run all tests
npm run test:unit     # Unit tests only
npm run test:integration  # Integration tests
```

## ⚠️ Important Notes

### Schema v2.0 Update
The cookbook schema has been updated to version 2.0 with improved semantics and consistency:

**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

**Example v2.0 step:**
```javascript
{
  step_id: 'process_items',
  type: 'foreach',
  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

## 🤝 Contributing

Internal package - contributions via internal GitLab only.

---
*For detailed documentation on individual modules, see their respective README files in the shared/ directory.*