@onlineapps/conn-orch-api-mapper 1.0.33 → 1.0.34

package/API.md

@@ -19,7 +19,7 @@ Handles OpenAPI parsing, request transformation, and response mapping.</p>
 ## Functions
 
 <dl>
-<dt><a href="#loadOpenApiSpec">loadOpenApiSpec(spec)</a> ⇒ <code>Object</code></dt>
+<dt><a href="#loadOperations">loadOperations(spec)</a> ⇒ <code>Object</code></dt>
 <dd><p>Load OpenAPI specification</p>
 </dd>
 <dt><a href="#mapOperationToEndpoint">mapOperationToEndpoint(operationName)</a> ⇒ <code>Object</code></dt>
@@ -57,7 +57,7 @@ Create API mapper instance
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | config | <code>Object</code> |  | Configuration options |
-| config.openApiSpec | <code>Object</code> \| <code>string</code> |  | OpenAPI specification object or path |
+| config.operations | <code>Object</code> \| <code>string</code> |  | Operations spec (operations.json contract; legacy OpenAPI accepted as fallback) |
 | config.serviceUrl | <code>string</code> |  | Base URL of the service |
 | [config.service] | <code>Object</code> |  | Express app instance for direct calls |
 | [config.directCall] | <code>boolean</code> | <code>false</code> | Use direct Express calls instead of HTTP |
@@ -66,7 +66,7 @@ Create API mapper instance
 **Example**  
 ```js
 const apiMapper = create({
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   serviceUrl: 'http://127.0.0.1:3000'
 });
 ```
@@ -97,7 +97,7 @@ Create a new ApiMapper instance
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | config | <code>Object</code> |  | Configuration object |
-| config.openApiSpec | <code>Object</code> \| <code>string</code> |  | OpenAPI specification object or path |
+| config.operations | <code>Object</code> \| <code>string</code> |  | Operations spec (operations.json contract; legacy OpenAPI accepted as fallback) |
 | config.serviceUrl | <code>string</code> |  | Base URL of the service (required; no defaults) |
 | [config.service] | <code>Object</code> |  | Express app instance for direct calls |
 | [config.directCall] | <code>boolean</code> | <code>false</code> | Use direct Express calls instead of HTTP |
@@ -107,7 +107,7 @@ Create a new ApiMapper instance
 **Example**  
 ```js
 const apiMapper = new ApiMapper({
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   serviceUrl: 'http://hello-service:3000'
 });
 ```
@@ -138,7 +138,7 @@ Create a new ApiMapper instance
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
 | config | <code>Object</code> |  | Configuration object |
-| config.openApiSpec | <code>Object</code> \| <code>string</code> |  | OpenAPI specification object or path |
+| config.operations | <code>Object</code> \| <code>string</code> |  | Operations spec (operations.json contract; legacy OpenAPI accepted as fallback) |
 | config.serviceUrl | <code>string</code> |  | Base URL of the service (required; no defaults) |
 | [config.service] | <code>Object</code> |  | Express app instance for direct calls |
 | [config.directCall] | <code>boolean</code> | <code>false</code> | Use direct Express calls instead of HTTP |
@@ -148,13 +148,13 @@ Create a new ApiMapper instance
 **Example**  
 ```js
 const apiMapper = new ApiMapper({
-  openApiSpec: require('./openapi.json'),
+  operations: require('./openapi.json'),
   serviceUrl: 'http://hello-service:3000'
 });
 ```
-<a name="loadOpenApiSpec"></a>
+<a name="loadOperations"></a>
 
-## loadOpenApiSpec(spec) ⇒ <code>Object</code>
+## loadOperations(spec) ⇒ <code>Object</code>
 Load OpenAPI specification
 
 **Kind**: global function  

package/README.md

@@ -231,9 +231,9 @@ const valid = await mapper.validateOperation({
   params: { name: 'World' }
 });
 
-// Generate request from OpenAPI
+// Generate request from operations spec
 const request = await mapper.fromOpenAPI({
-  spec: openApiSpec,
+  spec: operationsSpec,
   operationId: 'greetUser',
   params: { name: 'World' }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-api-mapper",
-  "version": "1.0.33",
+  "version": "1.0.34",
   "description": "API mapping connector for OA Drive - maps cookbook operations to HTTP endpoints",
   "main": "src/index.js",
   "scripts": {
@@ -21,7 +21,7 @@
   "license": "MIT",
   "dependencies": {
     "axios": "^1.4.0",
-    "@onlineapps/content-resolver": "1.1.15"
+    "@onlineapps/content-resolver": "1.1.16"
   },
   "devDependencies": {
     "jest": "^29.5.0",

package/src/ApiMapper.js

@@ -5,39 +5,54 @@ const ContentAccessor = require('@onlineapps/content-resolver');
 
 /**
  * @class ApiMapper
- * @description Maps cookbook operations to HTTP API endpoints using OpenAPI specification.
+ * @description Maps cookbook operations to HTTP API endpoints using the
+ * operations.json contract (see operations-registry-contract.md §3). A legacy
+ * OpenAPI `paths` payload is still accepted as a fallback during migration.
+ *
  * 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.
+ *
+ * @see api/docs/standards/operations-registry-contract.md §3 Operation schema
  */
 class ApiMapper {
   /**
-   * Create a new ApiMapper instance
+   * Create a new ApiMapper instance.
+   *
    * @constructor
    * @param {Object} config - Configuration object
-   * @param {Object|string} config.openApiSpec - OpenAPI specification object or path
+   * @param {Object} config.operations - Operations specification. Primary format:
+   *   `{ operations: { <operationId>: { method, endpoint, input, output, ... } } }`
+   *   (see operations-registry-contract.md §3). Legacy OpenAPI `{ paths }`
+   *   payloads are still accepted as a fallback.
    * @param {string} config.serviceUrl - Base URL of the service (required; no topology defaults)
    * @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 {Object} config.logger - Logger instance (required; must expose `warn`)
    *
    * @example
    * const apiMapper = new ApiMapper({
-   *   openApiSpec: require('./openapi.json'),
-   *   serviceUrl: 'http://hello-service:3000'
+   *   operations: require('./config/service/operations.json'),
+   *   serviceUrl: 'http://hello-service:3000',
+   *   logger
    * });
    */
   constructor(config) {
-    if (!config.openApiSpec) {
-      throw new Error('OpenAPI specification is required');
+    if (!config.operations) {
+      throw new Error('[ApiMapper] operations specification is required (see operations-registry-contract.md §3)');
     }
 
     if (typeof config.serviceUrl !== 'string' || config.serviceUrl.trim().length === 0) {
       throw new Error('[ApiMapper] Missing configuration - serviceUrl is required (no defaults)');
     }
 
-    this.openApiSpec = config.openApiSpec;
+    /**
+     * Raw operations specification as provided by the caller. For operations.json
+     * payloads this is `{ operations: { ... } }`; for legacy OpenAPI it is
+     * `{ paths: { ... } }`.
+     */
+    this.operationsSpec = config.operations;
     this.serviceUrl = config.serviceUrl;
     this.service = config.service;
     this.directCall = config.directCall === true;
@@ -46,19 +61,20 @@ class ApiMapper {
     }
     this.logger = config.logger;
 
-    // Parse OpenAPI to create operation map
-    this.operations = this._parseOpenApiSpec(this.openApiSpec);
+    // Parsed operation map: <operationId> → endpoint/HTTP details used at runtime.
+    this.operations = this._parseOperations(this.operationsSpec);
   }
 
   /**
-   * Load OpenAPI specification
-   * @method loadOpenApiSpec
-   * @param {Object|string} spec - OpenAPI specification or path
-   * @returns {Object} Parsed operations map
+   * Load (or reload) the operations specification.
+   *
+   * @method loadOperations
+   * @param {Object} spec - Operations specification (see constructor)
+   * @returns {Object} Parsed operation map
    */
-  loadOpenApiSpec(spec) {
-    this.openApiSpec = spec;
-    this.operations = this._parseOpenApiSpec(spec);
+  loadOperations(spec) {
+    this.operationsSpec = spec;
+    this.operations = this._parseOperations(spec);
     return this.operations;
   }
 
@@ -545,12 +561,14 @@ class ApiMapper {
   }
 
   /**
-   * Parse OpenAPI specification or operations.json to extract operations
+   * Parse operations specification (operations.json primary, OpenAPI fallback)
+   * into a runtime operation map keyed by operationId.
+   *
    * @private
-   * @param {Object} spec - OpenAPI specification or operations.json format
+   * @param {Object} spec - operations.json payload or legacy OpenAPI spec
    * @returns {Object} Operations map
    */
-  _parseOpenApiSpec(spec) {
+  _parseOperations(spec) {
     const operations = {};
 
     if (!spec || typeof spec !== 'object') {

package/src/index.js

@@ -2,10 +2,11 @@
 
 /**
  * @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.
+ * @description API mapping connector that maps cookbook operations to HTTP endpoints
+ * using the operations.json contract (primary format).
  *
- * @see {@link https://github.com/onlineapps/oa-drive/tree/main/shared/connector/conn-orch-api-mapper|GitHub Repository}
+ * @see /api/docs/architecture/operations-registry-contract.md §3 (operations.json)
+ * @see /api/shared/connector/conn-orch-api-mapper/README.md
  * @author OA Drive Team
  * @license MIT
  * @since 1.0.0
@@ -17,17 +18,19 @@ 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.operations - Operations specification (operations.json contract).
+ *   Legacy OpenAPI `{ paths }` payload still accepted as a fallback.
+ * @param {string} config.serviceUrl - Base URL of the service (required)
  * @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 {Object} config.logger - Logger instance (required)
  * @returns {ApiMapper} New API mapper instance
  *
  * @example
  * const apiMapper = create({
- *   openApiSpec: require('./openapi.json'),
- *   serviceUrl: 'http://127.0.0.1:3000'
+ *   operations: require('./config/service/operations.json'),
+ *   serviceUrl: 'http://127.0.0.1:3000',
+ *   logger: myLogger
  * });
  */
 function create(config) {