@onlineapps/service-wrapper 2.0.0

package/API.md

@@ -0,0 +1,336 @@
+## Modules
+
+<dl>
+<dt><a href="#module_@onlineapps/service-wrapper">@onlineapps/service-wrapper</a></dt>
+<dd><p>Infrastructure orchestration for microservices.
+Thin layer that delegates all work to specialized connectors.</p>
+</dd>
+<dt><a href="#module_@onlineapps/service-wrapper">@onlineapps/service-wrapper</a></dt>
+<dd><p>Thin orchestration layer for microservices that handles all infrastructure concerns.
+Delegates all actual work to specialized connectors.</p>
+</dd>
+</dl>
+
+<a name="module_@onlineapps/service-wrapper"></a>
+
+## @onlineapps/service-wrapper
+Infrastructure orchestration for microservices.
+Thin layer that delegates all work to specialized connectors.
+
+**See**: [GitHub Repository](https://github.com/onlineapps/oa-drive/tree/main/shared/service-wrapper)  
+**Since**: 2.0.0  
+**Author**: OA Drive Team  
+**License**: MIT  
+
+* [@onlineapps/service-wrapper](#module_@onlineapps/service-wrapper)
+    * [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+        * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+        * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+        * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+        * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [~start()](#module_@onlineapps/service-wrapper..start) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [~stop()](#module_@onlineapps/service-wrapper..stop) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [~getStatus()](#module_@onlineapps/service-wrapper..getStatus) ⇒ <code>Object</code>
+
+<a name="module_@onlineapps/service-wrapper..ServiceWrapper"></a>
+
+### @onlineapps/service-wrapper~ServiceWrapper
+**Kind**: inner class of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+
+* [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+    * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper()
+Thin wrapper that orchestrates all infrastructure concerns for a microservice.
+ALL actual functionality is delegated to specialized connectors.
+
+**Example**  
+```js
+const wrapper = new ServiceWrapper({
+  service: expressApp,
+  serviceName: 'hello-service',
+  openApiSpec: require('./openapi.json'),
+  config: {
+    rabbitmq: process.env.RABBITMQ_URL,
+    redis: process.env.REDIS_HOST,
+    registry: process.env.REGISTRY_URL
+  }
+});
+
+await wrapper.start();
+```
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper(options)
+Create a new ServiceWrapper instance
+
+**Throws**:
+
+- <code>Error</code> If required options are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>Object</code> |  | Configuration options |
+| options.service | <code>Object</code> |  | Express application instance |
+| options.serviceName | <code>string</code> |  | Name of the service |
+| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
+| [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
+| [options.config.redis] | <code>string</code> |  | Redis connection string |
+| [options.config.registry] | <code>string</code> |  | Registry service URL |
+| [options.config.port] | <code>number</code> | <code>3000</code> | Service port |
+| [options.config.prefetch] | <code>number</code> | <code>10</code> | MQ prefetch count |
+
+<a name="module_@onlineapps/service-wrapper..ServiceWrapper"></a>
+
+### @onlineapps/service-wrapper~ServiceWrapper
+**Kind**: inner class of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+
+* [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+    * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper()
+Thin wrapper that orchestrates all infrastructure concerns for a microservice.
+ALL actual functionality is delegated to specialized connectors.
+
+**Example**  
+```js
+const wrapper = new ServiceWrapper({
+  service: expressApp,
+  serviceName: 'hello-service',
+  openApiSpec: require('./openapi.json'),
+  config: {
+    rabbitmq: process.env.RABBITMQ_URL,
+    redis: process.env.REDIS_HOST,
+    registry: process.env.REGISTRY_URL
+  }
+});
+
+await wrapper.start();
+```
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper(options)
+Create a new ServiceWrapper instance
+
+**Throws**:
+
+- <code>Error</code> If required options are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>Object</code> |  | Configuration options |
+| options.service | <code>Object</code> |  | Express application instance |
+| options.serviceName | <code>string</code> |  | Name of the service |
+| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
+| [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
+| [options.config.redis] | <code>string</code> |  | Redis connection string |
+| [options.config.registry] | <code>string</code> |  | Registry service URL |
+| [options.config.port] | <code>number</code> | <code>3000</code> | Service port |
+| [options.config.prefetch] | <code>number</code> | <code>10</code> | MQ prefetch count |
+
+<a name="module_@onlineapps/service-wrapper..start"></a>
+
+### @onlineapps/service-wrapper~start() ⇒ <code>Promise.&lt;void&gt;</code>
+Start the service wrapper
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Example**  
+```js
+await wrapper.start();
+console.log('Service wrapper started');
+```
+<a name="module_@onlineapps/service-wrapper..stop"></a>
+
+### @onlineapps/service-wrapper~stop() ⇒ <code>Promise.&lt;void&gt;</code>
+Stop the service wrapper
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Example**  
+```js
+await wrapper.stop();
+console.log('Service wrapper stopped');
+```
+<a name="module_@onlineapps/service-wrapper..getStatus"></a>
+
+### @onlineapps/service-wrapper~getStatus() ⇒ <code>Object</code>
+Get wrapper status
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Returns**: <code>Object</code> - Status information  
+**Example**  
+```js
+const status = wrapper.getStatus();
+console.log('Wrapper status:', status);
+```
+<a name="module_@onlineapps/service-wrapper"></a>
+
+## @onlineapps/service-wrapper
+Thin orchestration layer for microservices that handles all infrastructure concerns.
+Delegates all actual work to specialized connectors.
+
+**Since**: 2.0.0  
+**Author**: OA Drive Team  
+**License**: MIT  
+
+* [@onlineapps/service-wrapper](#module_@onlineapps/service-wrapper)
+    * [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+        * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+        * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+        * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+        * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [~start()](#module_@onlineapps/service-wrapper..start) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [~stop()](#module_@onlineapps/service-wrapper..stop) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [~getStatus()](#module_@onlineapps/service-wrapper..getStatus) ⇒ <code>Object</code>
+
+<a name="module_@onlineapps/service-wrapper..ServiceWrapper"></a>
+
+### @onlineapps/service-wrapper~ServiceWrapper
+**Kind**: inner class of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+
+* [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+    * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper()
+Thin wrapper that orchestrates all infrastructure concerns for a microservice.
+ALL actual functionality is delegated to specialized connectors.
+
+**Example**  
+```js
+const wrapper = new ServiceWrapper({
+  service: expressApp,
+  serviceName: 'hello-service',
+  openApiSpec: require('./openapi.json'),
+  config: {
+    rabbitmq: process.env.RABBITMQ_URL,
+    redis: process.env.REDIS_HOST,
+    registry: process.env.REGISTRY_URL
+  }
+});
+
+await wrapper.start();
+```
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper(options)
+Create a new ServiceWrapper instance
+
+**Throws**:
+
+- <code>Error</code> If required options are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>Object</code> |  | Configuration options |
+| options.service | <code>Object</code> |  | Express application instance |
+| options.serviceName | <code>string</code> |  | Name of the service |
+| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
+| [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
+| [options.config.redis] | <code>string</code> |  | Redis connection string |
+| [options.config.registry] | <code>string</code> |  | Registry service URL |
+| [options.config.port] | <code>number</code> | <code>3000</code> | Service port |
+| [options.config.prefetch] | <code>number</code> | <code>10</code> | MQ prefetch count |
+
+<a name="module_@onlineapps/service-wrapper..ServiceWrapper"></a>
+
+### @onlineapps/service-wrapper~ServiceWrapper
+**Kind**: inner class of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+
+* [~ServiceWrapper](#module_@onlineapps/service-wrapper..ServiceWrapper)
+    * [new ServiceWrapper()](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+    * [new ServiceWrapper(options)](#new_module_@onlineapps/service-wrapper..ServiceWrapper_new)
+
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper()
+Thin wrapper that orchestrates all infrastructure concerns for a microservice.
+ALL actual functionality is delegated to specialized connectors.
+
+**Example**  
+```js
+const wrapper = new ServiceWrapper({
+  service: expressApp,
+  serviceName: 'hello-service',
+  openApiSpec: require('./openapi.json'),
+  config: {
+    rabbitmq: process.env.RABBITMQ_URL,
+    redis: process.env.REDIS_HOST,
+    registry: process.env.REGISTRY_URL
+  }
+});
+
+await wrapper.start();
+```
+<a name="new_module_@onlineapps/service-wrapper..ServiceWrapper_new"></a>
+
+#### new ServiceWrapper(options)
+Create a new ServiceWrapper instance
+
+**Throws**:
+
+- <code>Error</code> If required options are missing
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| options | <code>Object</code> |  | Configuration options |
+| options.service | <code>Object</code> |  | Express application instance |
+| options.serviceName | <code>string</code> |  | Name of the service |
+| options.openApiSpec | <code>Object</code> |  | OpenAPI specification |
+| [options.config] | <code>Object</code> | <code>{}</code> | Infrastructure configuration |
+| [options.config.rabbitmq] | <code>string</code> |  | RabbitMQ connection URL |
+| [options.config.redis] | <code>string</code> |  | Redis connection string |
+| [options.config.registry] | <code>string</code> |  | Registry service URL |
+| [options.config.port] | <code>number</code> | <code>3000</code> | Service port |
+| [options.config.prefetch] | <code>number</code> | <code>10</code> | MQ prefetch count |
+
+<a name="module_@onlineapps/service-wrapper..start"></a>
+
+### @onlineapps/service-wrapper~start() ⇒ <code>Promise.&lt;void&gt;</code>
+Start the service wrapper
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Example**  
+```js
+await wrapper.start();
+console.log('Service wrapper started');
+```
+<a name="module_@onlineapps/service-wrapper..stop"></a>
+
+### @onlineapps/service-wrapper~stop() ⇒ <code>Promise.&lt;void&gt;</code>
+Stop the service wrapper
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Example**  
+```js
+await wrapper.stop();
+console.log('Service wrapper stopped');
+```
+<a name="module_@onlineapps/service-wrapper..getStatus"></a>
+
+### @onlineapps/service-wrapper~getStatus() ⇒ <code>Object</code>
+Get wrapper status
+
+**Kind**: inner method of [<code>@onlineapps/service-wrapper</code>](#module_@onlineapps/service-wrapper)  
+**Returns**: <code>Object</code> - Status information  
+**Example**  
+```js
+const status = wrapper.getStatus();
+console.log('Wrapper status:', status);
+```

package/README.md

@@ -0,0 +1,185 @@
+# @onlineapps/service-wrapper
+
+Infrastructure wrapper that handles all workflow processing, message queue operations, and service registration for microservices.
+
+## Purpose
+
+This package provides the infrastructure layer that sits between:
+- **Message Queues** (RabbitMQ) and **Services** (business logic)
+- **Workflow Engine** and **Service APIs**
+- **Service Registry** and **Service Implementation**
+
+## Key Features
+
+- **Automatic workflow processing** - Handles cookbook execution
+- **Message queue integration** - Subscribes to queues, routes messages
+- **Service registration** - Auto-registers with service registry
+- **API-to-Cookbook mapping** - Converts workflow steps to API calls
+- **Error handling** - Retry logic, DLQ routing
+- **Health checks** - Automatic health endpoint
+
+## Architecture
+
+```
+[RabbitMQ Message] → [Service Wrapper] → [Service API Call] → [Business Logic]
+                           ↑                    ↑                    ↑
+                    This package         OpenAPI spec        Your service
+                    Handles all          Defines API         Pure business
+                    infrastructure       interface           logic only
+```
+
+## Usage
+
+### 1. Wrap Your Service
+
+```javascript
+const ServiceWrapper = require('@onlineapps/service-wrapper');
+const express = require('express');
+
+// Your pure business logic service
+const app = express();
+app.get('/hello', (req, res) => {
+  res.json({ message: `Hello ${req.query.name}` });
+});
+
+// Wrap with infrastructure
+const wrapper = new ServiceWrapper({
+  service: app,
+  serviceName: 'hello-service',
+  openApiSpec: require('./openapi.json'),
+  config: {
+    rabbitmq: process.env.RABBITMQ_URL,
+    registry: process.env.REGISTRY_URL,
+    port: process.env.PORT || 3000
+  }
+});
+
+// Start wrapped service
+wrapper.start();
+```
+
+### 2. Service Receives
+
+The wrapper automatically:
+- Subscribes to `{serviceName}.workflow` queue
+- Processes workflow messages
+- Calls your API endpoints based on cookbook steps
+- Routes results to next service
+
+### 3. Your Service Focuses on Business Logic
+
+Your service only needs to:
+- Expose API endpoints
+- Implement business logic
+- Return results
+
+NO infrastructure code needed in your service!
+
+## Configuration
+
+```javascript
+{
+  service: expressApp,        // Your Express app
+  serviceName: 'my-service',  // Service identifier
+  openApiSpec: {},            // OpenAPI specification
+  config: {
+    rabbitmq: 'amqp://...',   // RabbitMQ connection
+    registry: 'http://...',   // Registry URL
+    redis: 'redis://...',     // Redis connection
+    port: 3000,               // Service port
+    healthPath: '/health',    // Health check path
+    retryPolicy: {            // Retry configuration
+      maxRetries: 3,
+      backoffMs: 1000
+    }
+  }
+}
+```
+
+## What This Handles
+
+### Workflow Processing
+- Receives workflow messages from queue
+- Validates cookbook structure
+- Executes steps for this service
+- Routes to next service or completion
+
+### API Mapping
+- Maps cookbook steps to API calls
+- Handles input/output transformation
+- Manages context passing between steps
+
+### Infrastructure Concerns
+- Service registration and health checks
+- Message queue subscription and publishing
+- Error handling and retry logic
+- Dead letter queue routing
+
+## Service Requirements
+
+Your service needs:
+1. **OpenAPI specification** - Describes your API
+2. **Express app** - With business logic endpoints
+3. **Environment variables** - For configuration
+
+Your service should NOT have:
+- Workflow processing code
+- Message queue operations
+- Service registration logic
+- Connector imports
+
+## Example Service Structure
+
+```
+my-service/
+├── src/
+│   ├── index.js          # Express app (business logic only)
+│   ├── routes/           # API endpoints
+│   └── services/         # Business logic
+├── connector-config/
+│   └── openapi.json      # API specification
+└── package.json          # Dependencies (no @onlineapps/connector-*)
+```
+
+## Testing
+
+The wrapper provides test utilities:
+
+```javascript
+const { TestWrapper } = require('@onlineapps/service-wrapper');
+
+describe('My Service', () => {
+  let wrapper;
+
+  beforeAll(() => {
+    wrapper = new TestWrapper({
+      service: myApp,
+      mockQueues: true,
+      mockRegistry: true
+    });
+  });
+
+  test('processes workflow step', async () => {
+    const result = await wrapper.processStep({
+      type: 'task',
+      service: 'my-service',
+      operation: 'doSomething'
+    });
+    expect(result).toBeDefined();
+  });
+});
+```
+
+## Migration from Embedded Infrastructure
+
+If your service currently has workflow code:
+
+1. Install service-wrapper: `npm install @onlineapps/service-wrapper`
+2. Remove all `@onlineapps/connector-*` from service code
+3. Delete workflow processing files
+4. Wrap your Express app with ServiceWrapper
+5. Test that everything still works
+
+## License
+
+PROPRIETARY - All rights reserved

package/build-docs.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Manual documentation builder for service-wrapper
+ * Generates API.md from JSDoc comments
+ */
+
+const jsdoc2md = require('jsdoc-to-markdown');
+const fs = require('fs');
+const path = require('path');
+
+async function buildDocs() {
+  console.log('Building API documentation...');
+
+  try {
+    // Configure jsdoc2md options
+    const options = {
+      files: 'src/**/*.js',
+      'no-cache': true,
+      'heading-depth': 2,
+      template: fs.readFileSync(path.join(__dirname, 'docs-template.hbs'), 'utf8').toString()
+    };
+
+    // Generate markdown documentation
+    const output = await jsdoc2md.render(options);
+
+    // Write to API.md
+    fs.writeFileSync('API.md', output);
+
+    console.log('✓ API documentation generated successfully!');
+    console.log('  Output: API.md');
+
+  } catch (error) {
+    console.error('✗ Failed to generate documentation:', error.message);
+
+    // Fallback: use simple generation without template
+    try {
+      const simpleOutput = await jsdoc2md.render({ files: 'src/**/*.js' });
+      fs.writeFileSync('API.md', simpleOutput);
+      console.log('✓ API documentation generated (simple mode)');
+    } catch (fallbackError) {
+      console.error('✗ Fallback also failed:', fallbackError.message);
+      process.exit(1);
+    }
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  buildDocs();
+}
+
+module.exports = { buildDocs };