@onlineapps/conn-orch-api-mapper 1.0.7 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-api-mapper",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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.2"
+    "@onlineapps/content-resolver": "^1.1.3"
   },
   "devDependencies": {
     "jest": "^29.5.0",

package/src/ApiMapper.js

@@ -125,94 +125,225 @@ class ApiMapper {
 
   /**
    * Transform HTTP response to cookbook format
-   * Normalizes output fields to Content Descriptor based on operations.json output schema
+   * 
+   * 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
-   * @param {Object} [operation] - Operation schema from operations.json (for output normalization)
-   * @param {Object} [context] - Workflow context (for ContentAccessor initialization)
-   * @returns {Promise<Object>} Transformed response for cookbook
+   * @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;
     
-    // If no operation schema, return as-is
+    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;
     }
     
-    // Normalize output fields according to operations.json output schema
-    // Fields with type: "file" or type: "content" should be normalized to Descriptor
     const outputSchema = operation.output;
-    const normalizedOutput = { ...output };
     
-    // Initialize ContentAccessor if needed (lazy initialization)
-    let contentAccessor = null;
-    const getContentAccessor = () => {
-      if (!contentAccessor) {
-        contentAccessor = new ContentAccessor({
-          context: {
-            workflow_id: context.workflow_id || 'standalone',
-            step_id: context.step_id || 'api-mapper'
-          }
+    // Initialize ContentResolver (lazy)
+    let contentResolver = null;
+    const getContentResolver = () => {
+      if (!contentResolver) {
+        contentResolver = new ContentAccessor({
+          context: { workflow_id: workflowId, step_id: stepId }
         });
       }
-      return contentAccessor;
+      return contentResolver;
     };
     
-    // Process each output field
+    // === 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];
       
-      // Skip if field not present or null
-      if (fieldValue === undefined || fieldValue === null) {
-        continue;
-      }
+      if (fieldValue === undefined || fieldValue === null) continue;
       
-      // Normalize fields with type: "file" or type: "content" to Descriptor
+      // For file/content fields, convert to Descriptor
       if (fieldType === 'file' || fieldType === 'content') {
-        try {
-          const accessor = getContentAccessor();
-          
-          // If field is already a Descriptor (has _descriptor flag), use as-is
-          if (typeof fieldValue === 'object' && fieldValue !== null && (fieldValue._descriptor === true || fieldValue.type === 'file' || fieldValue.type === 'inline')) {
-            // Already a Descriptor, normalize to ensure completeness and _descriptor flag
-            normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue, {
-              filename: fieldValue.filename,
-              content_type: fieldValue.content_type
-            });
-          } else if (typeof fieldValue === 'string') {
-            // String value - normalize to Descriptor
-            normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue, {
-              filename: fieldSchema.filename,
-              content_type: fieldSchema.content_type
-            });
-          } else if (typeof fieldValue === 'object' && fieldValue !== null) {
-            // Object value (e.g., {storage_ref: "minio://..."}) - extract and normalize
-            if (fieldValue.storage_ref) {
-              // If it's an object with storage_ref, normalize the storage_ref
-              normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue.storage_ref, {
-                filename: fieldValue.filename || fieldValue.output_name,
-                content_type: fieldValue.content_type
-              });
-            } else {
-              // Unknown object format, try to normalize as-is
-              normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue, {
-                filename: fieldSchema.filename,
-                content_type: fieldSchema.content_type
-              });
-            }
-          }
-        } catch (error) {
-          this.logger?.warn(`Failed to normalize output field ${fieldName} to Descriptor: ${error.message}`);
-          // Keep original value on error
-        }
+        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
+   */
+  async _convertToDescriptor(output, schema, getContentResolver, logPrefix, context, fieldName = null) {
+    const fieldLabel = fieldName ? `field '${fieldName}'` : 'output';
+    
+    // Handler should return object with temp_path for file operations
+    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;
+    }
+    
+    // Handler returned Buffer - store it
+    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
+      });
+    }
+    
+    // Handler returned string (for content type) - may be inline or stored
+    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'
+        }
+      });
+    }
+    
+    // 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: 'object with temp_path, Buffer, or string',
+      received: typeof output,
+      receivedKeys: output && typeof output === 'object' ? Object.keys(output) : null
+    })}`);
+    throw new Error(`[ApiMapper] FAIL-FAST: ${errorMsg}. Expected temp_path/Buffer/string, got ${typeof output}`);
+  }
 
   /**
    * Call operation with parameters