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

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": "2.0.0",
   "description": "API mapping connector for OA Drive - maps cookbook operations to HTTP endpoints",
   "main": "src/index.js",
   "scripts": {
@@ -20,8 +20,7 @@
   "author": "OA Drive Team",
   "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

@@ -1,913 +1,27 @@
 'use strict';
 
-const axios = require('axios');
-const ContentAccessor = require('@onlineapps/content-resolver');
-
 /**
- * @class ApiMapper
- * @description Maps cookbook operations to HTTP API endpoints using OpenAPI specification.
- * Handles request building, variable resolution, and response transformation.
+ * @onlineapps/conn-orch-api-mapper
+ *
+ * Retired on 2026-04 as part of the biz-service invocation model C-refactor.
+ * The HTTP-loopback dispatch (callOperation + _callViaHttp + _callDirectly +
+ * _buildRequest + _convertOperationsJsonInputToOpenApi) has been removed; biz
+ * services now invoke handlers directly via
+ * @onlineapps/service-wrapper >= 3.0.0 (HandlerRegistry).
+ *
+ * See: api/docs/architecture/biz-service-invocation-model.md
  *
- * This is the core logic moved from service-wrapper's ApiCaller to make
- * service-wrapper a true thin orchestration layer.
+ * This package stays on 1.x as a retirement marker; version bump to 2.0.0 and
+ * removal from consumer dependencies happen in P1.8 and P5.1 of
+ * .cursor/plans/biz_invocation_model_c_1a797518.plan.md.
  */
-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 - 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
-   *
-   * @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');
-    }
-
-    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;
-    this.serviceUrl = config.serviceUrl;
-    this.service = config.service;
-    this.directCall = config.directCall === true;
-    if (!config.logger || typeof config.logger.warn !== 'function') {
-      throw new Error('[ApiMapper] Logger is required — Expected object with warn() method');
-    }
-    this.logger = config.logger;
-
-    // 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
-   * 
-   * CRITICAL RULES:
-   * 1. Handler returns RAW data (temp_path, filename, content_type) - NEVER Descriptors!
-   * 2. ApiMapper is the ONLY place that creates Descriptors
-   * 3. FAIL-FAST on unexpected formats - no fallbacks!
-   * 
-   * @method transformResponse
-   * @param {Object} httpResponse - HTTP response from handler
-   * @param {Object} [operation] - Operation schema from operations.json
-   * @param {Object} [context] - Workflow context { workflow_id, step_id }
-   * @returns {Promise<Object>} Transformed response (Descriptor for file types)
-   */
-  async transformResponse(httpResponse, operation = null, context = {}) {
-    // Extract relevant data from HTTP response
-    let output = httpResponse.data || httpResponse;
-    
-    const workflowId = context.workflow_id || 'standalone';
-    const stepId = context.step_id || 'unknown';
-    const logPrefix = `[${workflowId}:${stepId}:ApiMapper`;
-    
-    // === LOGGING: Input ===
-    console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-      action: 'transform_start',
-      hasOperation: !!operation,
-      outputType: typeof output,
-      outputKeys: output && typeof output === 'object' ? Object.keys(output) : null
-    })}`);
-    
-    // === FAIL-FAST: Handler should NEVER return Descriptors ===
-    if (output && typeof output === 'object') {
-      if (output._descriptor === true) {
-        const errorMsg = 'Handler returned _descriptor:true - handlers must return RAW data, not Descriptors!';
-        console.error(`${logPrefix}:FAIL] ${JSON.stringify({
-          error: 'HANDLER_RETURNED_DESCRIPTOR',
-          message: errorMsg,
-          handler_output_keys: Object.keys(output),
-          expected: 'object with temp_path/filename or raw data'
-        })}`);
-        throw new Error(`[ApiMapper] FAIL-FAST: ${errorMsg}`);
-      }
-      
-      // Also fail if handler returned storage_ref directly (handler shouldn't know about MinIO)
-      if (output.storage_ref && output.storage_ref.startsWith('minio://')) {
-        const errorMsg = 'Handler returned storage_ref - handlers must not interact with MinIO directly!';
-        console.error(`${logPrefix}:FAIL] ${JSON.stringify({
-          error: 'HANDLER_RETURNED_STORAGE_REF',
-          message: errorMsg,
-          storage_ref: output.storage_ref,
-          expected: 'object with temp_path/filename'
-        })}`);
-        throw new Error(`[ApiMapper] FAIL-FAST: ${errorMsg}`);
-      }
-    }
-    
-    // If no operation schema, return as-is (for non-file outputs)
-    if (!operation || !operation.output) {
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'no_schema',
-        result: 'returning_as_is'
-      })}`);
-      return output;
-    }
-    
-    const outputSchema = operation.output;
-    
-    // Initialize ContentResolver (lazy)
-    let contentResolver = null;
-    const getContentResolver = () => {
-      if (!contentResolver) {
-        contentResolver = new ContentAccessor({
-          context: { workflow_id: workflowId, step_id: stepId },
-          logger: this.logger
-        });
-      }
-      return contentResolver;
-    };
-    
-    // === DETECT OUTPUT SCHEMA FORMAT ===
-    // Format A: Direct type - { type: "file", fields: {...} }
-    // Format B: Named fields - { "fieldName": { type: "string" }, ... }
-    const isDirectType = outputSchema.type && 
-                         ['file', 'content', 'string', 'object', 'array'].includes(outputSchema.type);
-    
-    console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-      action: 'schema_detected',
-      format: isDirectType ? 'DIRECT_TYPE' : 'NAMED_FIELDS',
-      schemaType: outputSchema.type
-    })}`);
-    
-    // === FORMAT A: Direct type (entire output is one value) ===
-    if (isDirectType) {
-      const schemaType = outputSchema.type;
-      
-      // For file/content types, convert to Descriptor
-      if (schemaType === 'file' || schemaType === 'content') {
-        return await this._convertToDescriptor(output, outputSchema, getContentResolver, logPrefix, context);
-      }
-      
-      // For other types, return as-is
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'pass_through',
-        schemaType: schemaType
-      })}`);
-      return output;
-    }
-    
-    // === FORMAT B: Named fields ===
-    const normalizedOutput = { ...output };
-    
-    for (const [fieldName, fieldSchema] of Object.entries(outputSchema)) {
-      if (!fieldSchema || typeof fieldSchema !== 'object') continue;
-      
-      const fieldType = fieldSchema.type;
-      const fieldValue = output[fieldName];
-      
-      if (fieldValue === undefined || fieldValue === null) continue;
-      
-      // For file/content fields, convert to Descriptor
-      if (fieldType === 'file' || fieldType === 'content') {
-        normalizedOutput[fieldName] = await this._convertToDescriptor(
-          fieldValue, fieldSchema, getContentResolver, logPrefix, context, fieldName
-        );
-      }
-    }
-    
-    console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-      action: 'transform_complete',
-      outputKeys: Object.keys(normalizedOutput)
-    })}`);
-    
-    return normalizedOutput;
-  }
-  
-  /**
-   * Convert handler output to Descriptor
-   * @private
-   * 
-   * Supported formats from handler/HTTP response:
-   * 1. { data: base64_string, encoding: 'base64', filename, content_type } - HTTP transport format
-   * 2. { temp_path, filename, content_type } - Local file (only for same-process calls)
-   * 3. Buffer - Raw binary data
-   * 4. string - Text content
-   */
-  async _convertToDescriptor(output, schema, getContentResolver, logPrefix, context, fieldName = null) {
-    const fieldLabel = fieldName ? `field '${fieldName}'` : 'output';
-    const forceFile = schema?.type === 'file';
-    
-    // Format 1: Base64-encoded data from HTTP response (primary format for distributed services)
-    if (output && typeof output === 'object' && output.data && output.encoding === 'base64') {
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'convert_base64',
-        field: fieldName,
-        filename: output.filename,
-        size: output.size
-      })}`);
-      
-      // Decode base64 to Buffer
-      const buffer = Buffer.from(output.data, 'base64');
-      
-      const resolver = getContentResolver();
-      const descriptor = await resolver.createDescriptor(buffer, {
-        filename: output.filename || schema.filename || 'output.bin',
-        content_type: output.content_type || schema.content_type,
-        context: {
-          workflow_id: context.workflow_id || 'standalone',
-          step_id: context.step_id || 'api-mapper'
-        },
-        forceFile: true  // Binary data → always store as file
-      });
-      
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'descriptor_created',
-        field: fieldName,
-        storage_ref: descriptor.storage_ref,
-        size: descriptor.size
-      })}`);
-      
-      return descriptor;
-    }
-    
-    // Format 2: Temp file path (for same-process calls, e.g. tests)
-    if (output && typeof output === 'object' && output.temp_path) {
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'convert_temp_file',
-        field: fieldName,
-        temp_path: output.temp_path,
-        filename: output.filename
-      })}`);
-      
-      const resolver = getContentResolver();
-      const descriptor = await resolver.createDescriptorFromFile(output.temp_path, {
-        filename: output.filename,
-        content_type: output.content_type,
-        context: {
-          workflow_id: context.workflow_id || 'standalone',
-          step_id: context.step_id || 'api-mapper'
-        },
-        deleteAfterUpload: true
-      });
-      
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'descriptor_created',
-        field: fieldName,
-        storage_ref: descriptor.storage_ref,
-        size: descriptor.size
-      })}`);
-      
-      return descriptor;
-    }
-    
-    // Format 3: Raw Buffer
-    if (Buffer.isBuffer(output)) {
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'convert_buffer',
-        field: fieldName,
-        size: output.length
-      })}`);
-      
-      const resolver = getContentResolver();
-      return await resolver.createDescriptor(output, {
-        filename: schema.filename || 'output.bin',
-        content_type: schema.content_type,
-        context: {
-          workflow_id: context.workflow_id || 'standalone',
-          step_id: context.step_id || 'api-mapper'
-        },
-        forceFile: true
-      });
-    }
-    
-    // Format 4: Plain string (text content)
-    if (typeof output === 'string') {
-      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
-        action: 'convert_string',
-        field: fieldName,
-        length: output.length
-      })}`);
-      
-      const resolver = getContentResolver();
-      return await resolver.createDescriptor(output, {
-        filename: schema.filename,
-        content_type: schema.content_type,
-        context: {
-          workflow_id: context.workflow_id || 'standalone',
-          step_id: context.step_id || 'api-mapper'
-        },
-        ...(forceFile ? { forceFile: true } : {})
-      });
-    }
-    
-    // FAIL-FAST: Unexpected format
-    const errorMsg = `${fieldLabel} expects file/content but got unexpected format`;
-    console.error(`${logPrefix}:FAIL] ${JSON.stringify({
-      error: 'UNEXPECTED_OUTPUT_FORMAT',
-      field: fieldName,
-      expected: '{ data, encoding: "base64" } or { temp_path } or Buffer or string',
-      received: typeof output,
-      receivedKeys: output && typeof output === 'object' ? Object.keys(output) : null
-    })}`);
-    throw new Error(`[ApiMapper] FAIL-FAST: ${errorMsg}. Expected base64/temp_path/Buffer/string, got ${typeof output}`);
-  }
-
-  /**
-   * 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);
-
-      // CRITICAL: Resolve Content Descriptors to raw data BEFORE calling handler
-      // Handler receives RAW DATA, not Descriptors! ApiMapper is the boundary.
-      const handlerInput = await this._resolveContentDescriptors(resolvedInput, operation);
-
-      // Build request
-      const request = this._buildRequest(operation, handlerInput, context);
-
-      // 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 (with output normalization)
-      return await this.transformResponse(response, operation, context);
-
-    } catch (error) {
-      this.logger.error(`API call failed for ${operationId}`, {
-        error: error.message,
-        input,
-        operation
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Resolve Content Descriptors in input to raw data
-   * CRITICAL: Handler receives RAW DATA, not Descriptors!
-   * This is the boundary between orchestration (Descriptors) and business logic (raw data).
-   * 
-   * @private
-   * @param {Object} input - Input with potential Content Descriptors
-   * @param {Object} operation - Operation definition (for type hints)
-   * @returns {Promise<Object>} Input with Descriptors resolved to raw data
-   */
-  async _resolveContentDescriptors(input, operation) {
-    if (!input || typeof input !== 'object') {
-      return input;
-    }
-
-    // LAZY initialization - ContentResolver only when actually needed
-    let resolver = null;
-    const getResolver = () => {
-      if (!resolver) {
-        resolver = new ContentAccessor({ logger: this.logger });
-      }
-      return resolver;
-    };
-    
-    // Get input schema from operation (if available)
-    const inputSchema = operation?.input || {};
-
-    const resolveValue = async (value, schema, keyPath = '') => {
-      // If descriptor, resolve based on type
-      const isDescriptor = value && typeof value === 'object' &&
-        (value._descriptor === true || value.ref || value.storage_ref);
-
-      // Some upstream steps may serialize arrays into array-like objects: { "0": ..., "1": ... }.
-      // If schema expects an array, normalize such objects back into arrays so item schemas are applied correctly.
-      // Without this, nested descriptors (e.g. attachments[].value) may lose their schema.type='file' and get resolved
-      // into strings, dropping filename/content_type metadata.
-      if (!Array.isArray(value) && value && typeof value === 'object' && schema?.type === 'array') {
-        const keys = Object.keys(value);
-        const isNumericKeyed =
-          keys.length > 0 &&
-          keys.every((k) => /^[0-9]+$/.test(k));
-        if (isNumericKeyed) {
-          const asArray = keys
-            .sort((a, b) => Number(a) - Number(b))
-            .map((k) => value[k]);
-          return resolveValue(asArray, schema, keyPath);
-        }
-      }
-
-      if (isDescriptor) {
-        const fieldType = schema?.type;
-        const storageRef = value.ref || value.storage_ref || value;
-
-        if (fieldType === 'file') {
-          // Pass-through for file type
-          return value;
-        }
-
-        try {
-          const str = await getResolver().getAsString(storageRef);
-          return str;
-        } catch (err) {
-          const label = keyPath || '<root>';
-          throw new Error(`Failed to resolve Content Descriptor for '${label}': ${err.message}`);
-        }
-      }
-
-      // Array: resolve items with item schema if available
-      if (Array.isArray(value)) {
-        const itemSchema = schema?.items || {};
-        const resolvedItems = [];
-        for (let i = 0; i < value.length; i++) {
-          resolvedItems.push(await resolveValue(value[i], itemSchema, `${keyPath}[${i}]`));
-        }
-        return resolvedItems;
-      }
-
-      // Object: recurse into properties (schema.properties if provided)
-      if (value && typeof value === 'object') {
-        const resultObj = {};
-        for (const [k, v] of Object.entries(value)) {
-          const childSchema = schema?.properties?.[k] || {};
-          resultObj[k] = await resolveValue(v, childSchema, keyPath ? `${keyPath}.${k}` : k);
-        }
-        return resultObj;
-      }
-
-      // Primitive or null
-      return value;
-    };
-
-    const resolved = {};
-    for (const [key, value] of Object.entries(input)) {
-      const fieldSchema = inputSchema[key] || {};
-      resolved[key] = await resolveValue(value, fieldSchema, key);
-    }
-
-    return resolved;
-  }
-
-  /**
-   * Parse OpenAPI specification or operations.json to extract operations
-   * @private
-   * @param {Object} spec - OpenAPI specification or operations.json format
-   * @returns {Object} Operations map
-   */
-  _parseOpenApiSpec(spec) {
-    const operations = {};
-
-    if (!spec || typeof spec !== 'object') {
-      return operations;
-    }
 
-    // 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}`,
-          // Static headers from operations.json (e.g. x-validation-request).
-          headers: operation.headers || null,
-          // Store original operations.json input schema for type-driven descriptor handling
-          input: operation.input || null,
-          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,
-          // Store original operations.json output schema for normalization
-          output: operation.output || null
-        };
-      });
-      this.logger?.info(`Parsed ${Object.keys(operations).length} operations from operations.json format`);
-      return operations;
-    }
-
-    // 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
-   * @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
-   * @param {Object} context - Workflow context (must include _system.tenant_id + _system.default_workspace_id)
-   * @returns {Object} Request object
-   */
-  _buildRequest(operation, input, context = {}) {
-    const request = {
-      method: operation.method,
-      url: this.serviceUrl + operation.path,
-      params: {},
-      headers: {},
-      data: null
-    };
-
-    // operations.json static headers (if present)
-    if (operation && operation.headers && typeof operation.headers === 'object') {
-      Object.entries(operation.headers).forEach(([k, v]) => {
-        if (!k) return;
-        // Optional: allow ${context.path} variable resolution (no env side-effects here).
-        if (typeof v === 'string' && v.startsWith('${') && v.endsWith('}')) {
-          const path = v.slice(2, -1);
-          const resolved = this._getValueFromPath(context, path);
-          if (resolved !== undefined) {
-            request.headers[k] = resolved;
-          }
-          return;
-        }
-
-        request.headers[k] = v;
-      });
-    }
-
-    // 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;
-      }
-    });
-
-    // For operations.json format: input is sent as request body for POST/PUT/PATCH
-    // For OpenAPI format: use requestBody if present, otherwise send input as body
-    if (['POST', 'PUT', 'PATCH'].includes(operation.method)) {
-      if (operation.requestBody) {
-        // OpenAPI format: use requestBody structure
-        request.data = input.body || input;
-      } else {
-        // operations.json format or no requestBody: send input directly as body
-        request.data = input;
-      }
-      request.headers['Content-Type'] = 'application/json';
-    } else if (operation.method === 'GET' || operation.method === 'DELETE') {
-      // For GET/DELETE:
-      // - OpenAPI: rely on explicit operation.parameters (path/query/header), do NOT blindly copy all input to query
-      // - operations.json: no explicit query params → copy input as query
-      const hasExplicitNonBodyParams = Array.isArray(operation.parameters) &&
-        operation.parameters.some(p => p && p.in && p.in !== 'body');
-
-      if (!hasExplicitNonBodyParams) {
-        Object.entries(input).forEach(([key, value]) => {
-          if (value !== undefined && value !== null) {
-            request.params[key] = value;
-          }
-        });
-      }
-    }
-
-    const sys = context && typeof context === 'object' ? context._system : null;
-    if (!sys) {
-      throw new Error(
-        '[ApiMapper][TenantContext] Missing _system context - Expected context._system with tenant_id. ' +
-        'Fix: Gateway must set _system.tenant_id.'
-      );
-    }
-
-    if (sys.tenant_id === undefined) {
-      throw new Error(
-        '[ApiMapper][TenantContext] Missing tenant context - Expected _system.tenant_id'
-      );
-    }
-
-    const tenantId = Number.parseInt(String(sys.tenant_id), 10);
-    if (!Number.isInteger(tenantId) || tenantId <= 0) {
-      throw new Error(`[ApiMapper][TenantContext] Invalid tenant_id - Expected positive integer, got: ${sys.tenant_id}`);
-    }
-
-    // workspace_id: per-step override → cookbook default → error
-    // See: .cursor/rules/workspace-architecture.mdc
-    const stepDef = context._pointer?.currentStep || operation;
-    const rawStepWs = stepDef?.workspace_id;
-    const rawDefaultWs = sys.default_workspace_id;
-    const rawWorkspaceId = rawStepWs !== undefined && rawStepWs !== null ? rawStepWs : rawDefaultWs;
-
-    if (rawWorkspaceId === undefined || rawWorkspaceId === null) {
-      throw new Error(
-        '[ApiMapper][TenantContext] Missing workspace_id - set per-step workspace_id or cookbook defaults.workspace_id'
-      );
-    }
-
-    const workspaceId = Number.parseInt(String(rawWorkspaceId), 10);
-    if (!Number.isInteger(workspaceId) || workspaceId <= 0) {
-      throw new Error(`[ApiMapper][TenantContext] Invalid workspace_id - Expected positive integer, got: ${rawWorkspaceId}`);
-    }
-
-    const personId = sys.person_id !== undefined && sys.person_id !== null
-      ? Number.parseInt(String(sys.person_id), 10)
-      : undefined;
-    if (personId === undefined || !Number.isInteger(personId) || personId <= 0) {
-      throw new Error(`[ApiMapper][TenantContext] Invalid person_id - Expected positive integer, got: ${sys.person_id}`);
-    }
-
-    // See: docs/standards/tenant-context-contract.md (§3 Data Flow)
-    request.headers['x-tenant-id'] = String(tenantId);
-    request.headers['x-workspace-id'] = String(workspaceId);
-    request.headers['x-person-id'] = String(personId);
-
-    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) {
-        const status = error.response.status;
-        const data = error.response.data;
-
-        const businessBody = data?.error || data;
-        const remoteCode = businessBody?.code || businessBody?.errorCode || null;
-        const remoteMessage = businessBody?.message || error.response.statusText;
-        const remoteDetails = businessBody?.details || [];
-        const remoteService = businessBody?.service || null;
-        const remoteOperation = businessBody?.operation || null;
-
-        const richMessage = remoteCode
-          ? `[${remoteService || 'service'}] ${remoteCode}: ${remoteMessage}`
-          : `API returned ${status}: ${remoteMessage}`;
-
-        const richError = new Error(richMessage);
-        richError.statusCode = status;
-        richError.errorCode = remoteCode;
-        richError.type = businessBody?.type || null;
-        richError.details = remoteDetails;
-        richError.service = remoteService;
-        richError.operation = remoteOperation;
-        richError.responseBody = data;
-        richError.requestUrl = request.url;
-
-        throw richError;
-      } else if (error.request) {
-        const noResponseError = new Error(`No response from service: ${request.url}`);
-        noResponseError.statusCode = 503;
-        noResponseError.type = 'TRANSIENT';
-        noResponseError.requestUrl = request.url;
-        throw noResponseError;
-      } else {
-        throw error;
-      }
-    }
+class ApiMapper {
+  constructor() {
+    throw new Error(
+      '[ApiMapper] Package retired - Use @onlineapps/service-wrapper@^3.0.0 handler-registry dispatch instead. See api/docs/architecture/biz-service-invocation-model.md'
+    );
   }
 }
 
-module.exports = ApiMapper;
+module.exports = ApiMapper;

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) {