@onlineapps/conn-orch-api-mapper 1.0.0

package/src/ApiMapper.js

@@ -0,0 +1,385 @@
+'use strict';
+
+const axios = require('axios');
+
+/**
+ * @class ApiMapper
+ * @description Maps cookbook operations to HTTP API endpoints using OpenAPI specification.
+ * Handles request building, variable resolution, and response transformation.
+ *
+ * This is the core logic moved from service-wrapper's ApiCaller to make
+ * service-wrapper a true thin orchestration layer.
+ */
+class ApiMapper {
+  /**
+   * Create a new ApiMapper instance
+   * @constructor
+   * @param {Object} config - Configuration object
+   * @param {Object|string} config.openApiSpec - OpenAPI specification object or path
+   * @param {string} [config.serviceUrl='http://localhost:3000'] - Base URL of the service
+   * @param {Object} [config.service] - Express app instance for direct calls
+   * @param {boolean} [config.directCall=false] - Use direct Express calls instead of HTTP
+   * @param {Object} [config.logger] - Logger instance
+   * @param {number} [config.port=3000] - Service port for direct calls
+   *
+   * @example
+   * const apiMapper = new ApiMapper({
+   *   openApiSpec: require('./openapi.json'),
+   *   serviceUrl: 'http://hello-service:3000'
+   * });
+   */
+  constructor(config) {
+    if (!config.openApiSpec) {
+      throw new Error('OpenAPI specification is required');
+    }
+
+    this.openApiSpec = config.openApiSpec;
+    this.serviceUrl = config.serviceUrl || `http://localhost:${config.port || 3000}`;
+    this.service = config.service; // Express app for direct calls
+    this.directCall = config.directCall === true;
+    this.logger = config.logger || console;
+
+    // Parse OpenAPI to create operation map
+    this.operations = this._parseOpenApiSpec(this.openApiSpec);
+  }
+
+  /**
+   * Load OpenAPI specification
+   * @method loadOpenApiSpec
+   * @param {Object|string} spec - OpenAPI specification or path
+   * @returns {Object} Parsed operations map
+   */
+  loadOpenApiSpec(spec) {
+    this.openApiSpec = spec;
+    this.operations = this._parseOpenApiSpec(spec);
+    return this.operations;
+  }
+
+  /**
+   * Map operation name to HTTP endpoint details
+   * @method mapOperationToEndpoint
+   * @param {string} operationName - Operation ID from cookbook
+   * @returns {Object} Endpoint details {method, path, parameters}
+   *
+   * @example
+   * const endpoint = apiMapper.mapOperationToEndpoint('getUser');
+   * // Returns: {method: 'GET', path: '/users/{id}', parameters: [...]}
+   */
+  mapOperationToEndpoint(operationName) {
+    const operation = this.operations[operationName];
+    if (!operation) {
+      throw new Error(`Operation not found: ${operationName}`);
+    }
+    return operation;
+  }
+
+  /**
+   * Transform cookbook parameters to HTTP request
+   * @method transformRequest
+   * @param {Object} cookbookParams - Parameters from cookbook step
+   * @param {Object} openApiParams - OpenAPI parameter definitions
+   * @returns {Object} Transformed request {params, query, body, headers}
+   *
+   * @example
+   * const request = apiMapper.transformRequest(
+   *   {userId: '123', name: 'John'},
+   *   operation.parameters
+   * );
+   */
+  transformRequest(cookbookParams, openApiParams) {
+    const result = {
+      params: {},
+      query: {},
+      body: null,
+      headers: {}
+    };
+
+    // Process each parameter according to OpenAPI spec
+    openApiParams.forEach(param => {
+      const value = cookbookParams[param.name];
+      if (value !== undefined) {
+        switch (param.in) {
+          case 'path':
+            result.params[param.name] = value;
+            break;
+          case 'query':
+            result.query[param.name] = value;
+            break;
+          case 'header':
+            result.headers[param.name] = value;
+            break;
+        }
+      } else if (param.required) {
+        throw new Error(`Required parameter missing: ${param.name}`);
+      }
+    });
+
+    // Handle request body
+    if (cookbookParams.body) {
+      result.body = cookbookParams.body;
+    }
+
+    return result;
+  }
+
+  /**
+   * Transform HTTP response to cookbook format
+   * @method transformResponse
+   * @param {Object} httpResponse - HTTP response
+   * @returns {Object} Transformed response for cookbook
+   */
+  transformResponse(httpResponse) {
+    // Extract relevant data from HTTP response
+    if (httpResponse.data) {
+      return httpResponse.data;
+    }
+    return httpResponse;
+  }
+
+  /**
+   * Call operation with parameters
+   * @async
+   * @method callOperation
+   * @param {string} operationId - Operation identifier
+   * @param {Object} input - Input data for the operation
+   * @param {Object} context - Workflow context
+   * @returns {Promise<Object>} API response
+   *
+   * @example
+   * const result = await apiMapper.callOperation('getUser', {id: '123'}, context);
+   */
+  async callOperation(operationId, input = {}, context = {}) {
+    const operation = this.operations[operationId];
+
+    if (!operation) {
+      throw new Error(`Operation not found: ${operationId}`);
+    }
+
+    try {
+      // Resolve variables in input using context
+      const resolvedInput = this._resolveVariables(input, context);
+
+      // Build request
+      const request = this._buildRequest(operation, resolvedInput);
+
+      // Make the call
+      let response;
+      if (this.service && this.directCall) {
+        response = await this._callDirectly(request);
+      } else {
+        response = await this._callViaHttp(request);
+      }
+
+      // Transform and return response
+      return this.transformResponse(response);
+
+    } catch (error) {
+      this.logger.error(`API call failed for ${operationId}`, {
+        error: error.message,
+        input,
+        operation
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Parse OpenAPI specification to extract operations
+   * @private
+   * @param {Object} spec - OpenAPI specification
+   * @returns {Object} Operations map
+   */
+  _parseOpenApiSpec(spec) {
+    const operations = {};
+
+    if (!spec || !spec.paths) {
+      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
+          };
+        }
+      });
+    });
+
+    this.logger.info(`Parsed ${Object.keys(operations).length} operations from OpenAPI spec`);
+    return operations;
+  }
+
+  /**
+   * Resolve variables in input using context
+   * @private
+   * @param {Object} input - Input with potential variable references
+   * @param {Object} context - Context containing variable values
+   * @returns {Object} Resolved input
+   */
+  _resolveVariables(input, context) {
+    if (!input || typeof input !== 'object') {
+      return input;
+    }
+
+    const resolved = {};
+
+    Object.entries(input).forEach(([key, value]) => {
+      if (typeof value === 'string' && value.startsWith('${') && value.endsWith('}')) {
+        // Variable reference: ${context.path.to.value}
+        const path = value.slice(2, -1);
+        resolved[key] = this._getValueFromPath(context, path);
+      } else if (typeof value === 'object' && value !== null) {
+        // Recursive resolution
+        resolved[key] = this._resolveVariables(value, context);
+      } else {
+        resolved[key] = value;
+      }
+    });
+
+    return resolved;
+  }
+
+  /**
+   * Get value from object using dot notation path
+   * @private
+   * @param {Object} obj - Object to search
+   * @param {string} path - Dot notation path
+   * @returns {*} Value at path
+   */
+  _getValueFromPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+
+    for (const part of parts) {
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+
+  /**
+   * Build HTTP request from operation and input
+   * @private
+   * @param {Object} operation - Operation definition
+   * @param {Object} input - Resolved input
+   * @returns {Object} Request object
+   */
+  _buildRequest(operation, input) {
+    const request = {
+      method: operation.method,
+      url: this.serviceUrl + operation.path,
+      params: {},
+      headers: {},
+      data: null
+    };
+
+    // Process path parameters
+    operation.parameters.forEach(param => {
+      const value = input[param.name];
+
+      if (param.in === 'path') {
+        // Replace path parameter in URL
+        request.url = request.url.replace(`{${param.name}}`, value);
+      } else if (param.in === 'query') {
+        request.params[param.name] = value;
+      } else if (param.in === 'header') {
+        request.headers[param.name] = value;
+      }
+    });
+
+    // Add request body if present
+    if (operation.requestBody && input.body) {
+      request.data = input.body;
+      request.headers['Content-Type'] = 'application/json';
+    }
+
+    return request;
+  }
+
+  /**
+   * Call service directly via Express app
+   * @private
+   * @async
+   * @param {Object} request - Request object
+   * @returns {Promise<Object>} Response
+   */
+  async _callDirectly(request) {
+    // Create mock req/res objects for Express
+    const mockReq = {
+      method: request.method,
+      url: request.url.replace(this.serviceUrl, ''),
+      params: {},
+      query: request.params,
+      body: request.data,
+      headers: request.headers
+    };
+
+    // Extract path params from URL
+    const pathMatch = mockReq.url.match(/\/[^?]*/);
+    if (pathMatch) {
+      mockReq.path = pathMatch[0];
+    }
+
+    return new Promise((resolve, reject) => {
+      const mockRes = {
+        status: function(code) {
+          this.statusCode = code;
+          return this;
+        },
+        json: function(data) {
+          resolve({ data, status: this.statusCode || 200 });
+        },
+        send: function(data) {
+          resolve({ data, status: this.statusCode || 200 });
+        }
+      };
+
+      // Call Express app directly
+      this.service(mockReq, mockRes, (err) => {
+        if (err) reject(err);
+        else reject(new Error('Route not found'));
+      });
+    });
+  }
+
+  /**
+   * Call service via HTTP
+   * @private
+   * @async
+   * @param {Object} request - Request object
+   * @returns {Promise<Object>} Response
+   */
+  async _callViaHttp(request) {
+    try {
+      const response = await axios(request);
+      return response;
+    } catch (error) {
+      if (error.response) {
+        // Server responded with error
+        throw new Error(`API returned ${error.response.status}: ${error.response.statusText}`);
+      } else if (error.request) {
+        // Request made but no response
+        throw new Error(`No response from service: ${request.url}`);
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+
+module.exports = ApiMapper;

package/src/index.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * @module @onlineapps/conn-orch-api-mapper
+ * @description API mapping connector that maps cookbook operations to HTTP endpoints.
+ * Handles OpenAPI parsing, request transformation, and response mapping.
+ *
+ * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-api-mapper|GitHub Repository}
+ * @author OA Drive Team
+ * @license MIT
+ * @since 1.0.0
+ */
+
+const ApiMapper = require('./ApiMapper');
+
+/**
+ * Create API mapper instance
+ * @function create
+ * @param {Object} config - Configuration options
+ * @param {Object|string} config.openApiSpec - OpenAPI specification object or path
+ * @param {string} config.serviceUrl - Base URL of the service
+ * @param {Object} [config.service] - Express app instance for direct calls
+ * @param {boolean} [config.directCall=false] - Use direct Express calls instead of HTTP
+ * @param {Object} [config.logger] - Logger instance
+ * @returns {ApiMapper} New API mapper instance
+ *
+ * @example
+ * const apiMapper = create({
+ *   openApiSpec: require('./openapi.json'),
+ *   serviceUrl: 'http://localhost:3000'
+ * });
+ */
+function create(config) {
+  return new ApiMapper(config);
+}
+
+module.exports = {
+  ApiMapper,
+  create,
+  VERSION: '1.0.0'
+};