@onlineapps/conn-orch-api-mapper 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,262 @@
+# @onlineapps/conn-orch-api-mapper
+
+## Overview
+Maps cookbook operations to HTTP API endpoints. Bridges the gap between MQ-based workflow steps and RESTful service APIs.
+
+## Installation
+```bash
+npm install @onlineapps/conn-orch-api-mapper
+```
+
+## Features
+- Operation to endpoint mapping
+- Parameter transformation
+- Response mapping
+- Header injection
+- Service discovery integration
+- OpenAPI schema support
+
+## Usage
+
+### Basic Setup
+```javascript
+const { ApiMapper } = require('@onlineapps/conn-orch-api-mapper');
+
+const mapper = new ApiMapper({
+  registryUrl: 'http://api_services_registry:33100',
+  cacheEnabled: true,
+  cacheTTL: 300
+});
+
+// Initialize mapper
+await mapper.initialize();
+```
+
+### Operation Mapping
+```javascript
+// Map cookbook operation to HTTP request
+const httpRequest = await mapper.mapOperation({
+  service: 'hello-service',
+  operation: 'greet',
+  params: {
+    name: 'World',
+    language: 'en'
+  }
+});
+
+// Returns:
+{
+  method: 'POST',
+  url: 'http://hello-service:33199/api/greet',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Workflow-Id': 'wf-uuid'
+  },
+  body: {
+    name: 'World',
+    language: 'en'
+  }
+}
+```
+
+### Response Mapping
+```javascript
+// Map HTTP response back to workflow format
+const workflowResult = mapper.mapResponse({
+  status: 200,
+  headers: { 'content-type': 'application/json' },
+  body: { greeting: 'Hello World' }
+});
+
+// Returns:
+{
+  success: true,
+  data: { greeting: 'Hello World' },
+  metadata: {
+    httpStatus: 200,
+    processingTime: 45
+  }
+}
+```
+
+## Configuration
+
+### Options
+```javascript
+{
+  registryUrl: 'http://registry:33100',  // Registry service URL
+  cacheEnabled: true,                    // Cache service mappings
+  cacheTTL: 300,                         // Cache TTL in seconds
+  timeout: 5000,                         // HTTP request timeout
+  retries: 3,                            // Retry attempts
+  validateSchema: true                   // Validate against OpenAPI
+}
+```
+
+### Environment Variables
+```bash
+REGISTRY_URL=http://api_services_registry:33100
+API_MAPPER_CACHE_ENABLED=true
+API_MAPPER_CACHE_TTL=300
+API_MAPPER_TIMEOUT=5000
+```
+
+## Mapping Rules
+
+### Default Mapping
+```javascript
+// Cookbook operation
+{ service: 'service-name', operation: 'operation-name' }
+
+// Maps to HTTP
+POST /api/operation-name
+```
+
+### Custom Mappings
+```javascript
+// Define custom mappings
+mapper.addMapping('hello-service', {
+  greet: {
+    method: 'POST',
+    path: '/api/greet',
+    paramMapping: {
+      name: 'body.name',
+      lang: 'query.language'
+    }
+  },
+  status: {
+    method: 'GET',
+    path: '/health'
+  }
+});
+```
+
+## Service Discovery
+
+The mapper integrates with the service registry:
+
+```javascript
+// Auto-discover service endpoints
+const endpoint = await mapper.discoverEndpoint('hello-service');
+// Returns: http://hello-service:33199
+
+// Get service OpenAPI spec
+const spec = await mapper.getServiceSpec('hello-service');
+// Returns OpenAPI specification object
+```
+
+## Parameter Transformation
+
+### Input Transformation
+```javascript
+// Transform cookbook params to HTTP request
+const transformed = mapper.transformParams({
+  params: { name: 'World', count: 5 },
+  mapping: {
+    name: 'body.name',
+    count: 'query.limit'
+  }
+});
+
+// Returns:
+{
+  body: { name: 'World' },
+  query: { limit: 5 }
+}
+```
+
+### Output Transformation
+```javascript
+// Transform HTTP response to workflow output
+const output = mapper.transformResponse({
+  response: { data: { items: [...] } },
+  mapping: {
+    'data.items': 'results',
+    'data.total': 'count'
+  }
+});
+```
+
+## API Reference
+
+### ApiMapper
+
+#### initialize()
+Initializes the mapper and loads service registry.
+
+#### mapOperation(operation)
+Maps a cookbook operation to HTTP request.
+
+#### mapResponse(response)
+Maps HTTP response to workflow result.
+
+#### discoverEndpoint(serviceName)
+Discovers service endpoint from registry.
+
+#### getServiceSpec(serviceName)
+Retrieves OpenAPI specification for service.
+
+#### addMapping(serviceName, mappings)
+Adds custom operation mappings.
+
+#### transformParams(params, mapping)
+Transforms parameters according to mapping rules.
+
+## Integration with Service Wrapper
+
+The API mapper is automatically used by service-wrapper:
+
+```javascript
+const { ServiceWrapper } = require('@onlineapps/service-wrapper');
+
+const wrapper = new ServiceWrapper({
+  apiMapping: {
+    enabled: true,
+    customMappings: {...}
+  }
+});
+
+// API mapping is automatically configured
+```
+
+## OpenAPI Integration
+
+Supports OpenAPI 3.0 specifications:
+
+```javascript
+// Validate against OpenAPI schema
+const valid = await mapper.validateOperation({
+  service: 'hello-service',
+  operation: 'greet',
+  params: { name: 'World' }
+});
+
+// Generate request from OpenAPI
+const request = await mapper.fromOpenAPI({
+  spec: openApiSpec,
+  operationId: 'greetUser',
+  params: { name: 'World' }
+});
+```
+
+## Testing
+
+```bash
+npm test                 # Run all tests
+npm run test:unit        # Unit tests only
+npm run test:component   # Component tests
+```
+
+## Dependencies
+- `@onlineapps/conn-orch-registry` - Service registry client
+- `axios` - HTTP client
+- `openapi-validator` - Schema validation
+
+## Related Documentation
+- [Service Wrapper](/shared/connector/service-wrapper/README.md) - Integration guide
+- [Registry System](/docs/modules/registry.md) - Service discovery
+- [Cookbook Connector](/shared/connector/conn-orch-cookbook/README.md) - Operation format
+- [API Standards](/docs/STANDARDS_OVERVIEW.md#api-structure) - Endpoint conventions
+
+---
+*Version: 1.0.0 | License: MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-api-mapper",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "API mapping connector for OA Drive - maps cookbook operations to HTTP endpoints",
   "main": "src/index.js",
   "scripts": {
@@ -13,7 +13,6 @@
   "keywords": [
     "api",
     "mapping",
-    "openapi",
     "cookbook",
     "http",
     "connector"

package/src/ApiMapper.js

@@ -184,42 +184,88 @@ class ApiMapper {
   }
 
   /**
-   * Parse OpenAPI specification to extract operations
+   * Parse OpenAPI specification or operations.json to extract operations
    * @private
-   * @param {Object} spec - OpenAPI specification
+   * @param {Object} spec - OpenAPI specification or operations.json format
    * @returns {Object} Operations map
    */
   _parseOpenApiSpec(spec) {
     const operations = {};
 
-    if (!spec || !spec.paths) {
+    if (!spec || typeof spec !== 'object') {
       return operations;
     }
 
-    // Extract all operations from OpenAPI paths
-    Object.entries(spec.paths).forEach(([path, pathItem]) => {
-      Object.entries(pathItem).forEach(([method, operation]) => {
-        if (['get', 'post', 'put', 'patch', 'delete'].includes(method)) {
-          const operationId = operation.operationId ||
-            `${method}_${path.replace(/[^a-zA-Z0-9]/g, '_')}`;
-
-          operations[operationId] = {
-            method: method.toUpperCase(),
-            path,
-            parameters: operation.parameters || [],
-            requestBody: operation.requestBody,
-            responses: operation.responses,
-            summary: operation.summary,
-            description: operation.description
-          };
-        }
+    // Check if this is operations.json format (has "operations" key at root)
+    if (spec.operations && typeof spec.operations === 'object') {
+      // Parse operations.json format
+      Object.entries(spec.operations).forEach(([operationId, operation]) => {
+        operations[operationId] = {
+          method: (operation.method || 'POST').toUpperCase(),
+          path: operation.endpoint || `/${operationId}`,
+          parameters: operation.input ? this._convertOperationsJsonInputToOpenApi(operation.input) : [],
+          requestBody: operation.input ? { content: { 'application/json': { schema: { type: 'object', properties: operation.input } } } } : undefined,
+          responses: operation.output ? { '200': { description: 'Success', content: { 'application/json': { schema: { type: 'object', properties: operation.output } } } } } : { '200': { description: 'Success' } },
+          summary: operation.description,
+          description: operation.description
+        };
       });
-    });
+      this.logger?.info(`Parsed ${Object.keys(operations).length} operations from operations.json format`);
+      return operations;
+    }
 
-    this.logger.info(`Parsed ${Object.keys(operations).length} operations from OpenAPI spec`);
+    // Extract all operations from OpenAPI paths (original OpenAPI format)
+    if (spec.paths) {
+      Object.entries(spec.paths).forEach(([path, pathItem]) => {
+        Object.entries(pathItem).forEach(([method, operation]) => {
+          if (['get', 'post', 'put', 'patch', 'delete'].includes(method)) {
+            const operationId = operation.operationId ||
+              `${method}_${path.replace(/[^a-zA-Z0-9]/g, '_')}`;
+
+            operations[operationId] = {
+              method: method.toUpperCase(),
+              path,
+              parameters: operation.parameters || [],
+              requestBody: operation.requestBody,
+              responses: operation.responses,
+              summary: operation.summary,
+              description: operation.description
+            };
+          }
+        });
+      });
+    }
+
+    this.logger?.info(`Parsed ${Object.keys(operations).length} operations from OpenAPI spec`);
     return operations;
   }
 
+  /**
+   * Convert operations.json input format to OpenAPI parameters
+   * @private
+   * @param {Object} input - operations.json input schema
+   * @returns {Array} OpenAPI parameters array
+   */
+  _convertOperationsJsonInputToOpenApi(input) {
+    const parameters = [];
+    Object.entries(input).forEach(([name, schema]) => {
+      parameters.push({
+        name,
+        in: 'body', // operations.json uses body parameters
+        required: schema.required !== false,
+        schema: {
+          type: schema.type || 'string',
+          description: schema.description,
+          minLength: schema.minLength,
+          maxLength: schema.maxLength,
+          enum: schema.enum,
+          default: schema.default
+        }
+      });
+    });
+    return parameters;
+  }
+
   /**
    * Resolve variables in input using context
    * @private

package/{test → tests}/component/api-mapping-flow.test.js

@@ -6,7 +6,7 @@ const axios = require('axios');
 // Mock axios
 jest.mock('axios');
 
-describe('API Mapper Component Tests', () => {
+describe('API Mapper Component Tests @component', () => {
   let apiMapper;
   let mockOpenApiSpec;
   let mockLogger;

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

@@ -5,7 +5,7 @@ const axios = require('axios');
 
 jest.mock('axios');
 
-describe('ApiMapper Unit Tests', () => {
+describe('ApiMapper Unit Tests @unit', () => {
   let apiMapper;
   let mockLogger;
   let mockOpenApiSpec;