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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-api-mapper",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "API mapping connector for OA Drive - maps cookbook operations to HTTP endpoints",
   "main": "src/index.js",
   "scripts": {

package/src/ApiMapper.js

@@ -125,220 +125,225 @@ class ApiMapper {
 
   /**
    * Transform HTTP response to cookbook format
-   * Normalizes output fields to Content Descriptor based on operations.json output schema
    * 
-   * Supports two operations.json output formats:
-   * 1. Named fields: { "message": { "type": "string" }, "pdf": { "type": "file" } }
-   * 2. Direct type: { "type": "file", "description": "..." } (entire output is one value)
+   * 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;
     
+    const workflowId = context.workflow_id || 'standalone';
+    const stepId = context.step_id || 'unknown';
+    const logPrefix = `[${workflowId}:${stepId}:ApiMapper`;
+    
     // === LOGGING: Input ===
-    const logPrefix = '[ApiMapper:transformResponse]';
-    console.log(`${logPrefix} INPUT:`, JSON.stringify({
+    console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
+      action: 'transform_start',
       hasOperation: !!operation,
-      operationOutput: operation?.output,
       outputType: typeof output,
-      outputKeys: output && typeof output === 'object' ? Object.keys(output) : null,
-      output_descriptor: output?._descriptor,
-      output_type: output?.type
-    }));
+      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
+    // If no operation schema, return as-is (for non-file outputs)
     if (!operation || !operation.output) {
-      console.log(`${logPrefix} OUTPUT: No operation schema, returning as-is`);
+      console.log(`${logPrefix}:PROCESS] ${JSON.stringify({
+        action: 'no_schema',
+        result: 'returning_as_is'
+      })}`);
       return output;
     }
     
     const outputSchema = operation.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;
     };
     
     // === DETECT OUTPUT SCHEMA FORMAT ===
-    // Format A: Direct type - { type: "file", description: "..." }
+    // Format A: Direct type - { type: "file", fields: {...} }
     // Format B: Named fields - { "fieldName": { type: "string" }, ... }
     const isDirectType = outputSchema.type && 
-                         (outputSchema.type === 'file' || 
-                          outputSchema.type === 'content' || 
-                          outputSchema.type === 'string' ||
-                          outputSchema.type === 'object' ||
-                          outputSchema.type === 'array');
+                         ['file', 'content', 'string', 'object', 'array'].includes(outputSchema.type);
     
-    console.log(`${logPrefix} Schema format: ${isDirectType ? 'DIRECT_TYPE' : 'NAMED_FIELDS'}`);
+    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;
       
-      // If schema expects file/content, ensure output is Descriptor
+      // For file/content types, convert to Descriptor
       if (schemaType === 'file' || schemaType === 'content') {
-        // Check if output is already a valid Descriptor
-        if (output && typeof output === 'object' && output._descriptor === true) {
-          console.log(`${logPrefix} OUTPUT: Already Descriptor with _descriptor=true`);
-          return output;
-        }
-        
-        // Check if output looks like Descriptor but missing _descriptor flag
-        if (output && typeof output === 'object' && (output.type === 'file' || output.type === 'inline')) {
-          console.log(`${logPrefix} Normalizing Descriptor (missing _descriptor flag)`);
-          try {
-            const accessor = getContentAccessor();
-            const normalized = await accessor.normalizeToDescriptor(output, {
-              filename: output.filename,
-              content_type: output.content_type
-            });
-            console.log(`${logPrefix} OUTPUT: Normalized Descriptor:`, JSON.stringify({
-              _descriptor: normalized._descriptor,
-              type: normalized.type,
-              storage_ref: normalized.storage_ref,
-              filename: normalized.filename
-            }));
-            return normalized;
-          } catch (error) {
-            console.error(`${logPrefix} FAIL: Failed to normalize Descriptor: ${error.message}`);
-            // FAIL-FAST: Don't silently continue with broken data
-            throw new Error(`[ApiMapper] FAIL-FAST: Output is ${schemaType} but failed to normalize: ${error.message}`);
-          }
-        }
-        
-        // Output is string (storage reference) - convert to Descriptor
-        if (typeof output === 'string') {
-          console.log(`${logPrefix} Converting string to Descriptor: ${output.substring(0, 50)}...`);
-          try {
-            const accessor = getContentAccessor();
-            const normalized = await accessor.normalizeToDescriptor(output, {
-              filename: outputSchema.filename,
-              content_type: outputSchema.content_type
-            });
-            console.log(`${logPrefix} OUTPUT: String converted to Descriptor`);
-            return normalized;
-          } catch (error) {
-            console.error(`${logPrefix} FAIL: Failed to convert string to Descriptor: ${error.message}`);
-            throw new Error(`[ApiMapper] FAIL-FAST: Output is ${schemaType} but string conversion failed: ${error.message}`);
-          }
-        }
-        
-        // Output is object with storage_ref - extract and convert
-        if (output && typeof output === 'object' && output.storage_ref) {
-          console.log(`${logPrefix} Converting object with storage_ref to Descriptor`);
-          try {
-            const accessor = getContentAccessor();
-            const normalized = await accessor.normalizeToDescriptor(output.storage_ref, {
-              filename: output.filename || output.output_name,
-              content_type: output.content_type
-            });
-            console.log(`${logPrefix} OUTPUT: Object converted to Descriptor`);
-            return normalized;
-          } catch (error) {
-            console.error(`${logPrefix} FAIL: Failed to convert object to Descriptor: ${error.message}`);
-            throw new Error(`[ApiMapper] FAIL-FAST: Output is ${schemaType} but object conversion failed: ${error.message}`);
-          }
-        }
-        
-        // FAIL-FAST: Schema expects file/content but got unexpected format
-        console.error(`${logPrefix} FAIL-FAST: Schema expects ${schemaType} but got unexpected output format:`, {
-          outputType: typeof output,
-          outputKeys: output && typeof output === 'object' ? Object.keys(output) : null
-        });
-        throw new Error(`[ApiMapper] FAIL-FAST: Schema expects '${schemaType}' but received unexpected format. Output type: ${typeof output}`);
+        return await this._convertToDescriptor(output, outputSchema, getContentResolver, logPrefix, context);
       }
       
-      // For other direct types (string, object, array), return as-is
-      console.log(`${logPrefix} OUTPUT: Direct type '${schemaType}', returning as-is`);
+      // 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 };
     
-    // Process each output field
     for (const [fieldName, fieldSchema] of Object.entries(outputSchema)) {
-      // Skip if fieldSchema is not an object (e.g., "type" key from Format A detected wrongly)
-      if (!fieldSchema || typeof fieldSchema !== 'object') {
-        continue;
-      }
+      if (!fieldSchema || typeof fieldSchema !== 'object') continue;
       
       const fieldType = fieldSchema.type;
       const fieldValue = output[fieldName];
       
-      console.log(`${logPrefix} Processing field '${fieldName}': type=${fieldType}, hasValue=${fieldValue !== undefined}`);
+      if (fieldValue === undefined || fieldValue === null) continue;
       
-      // Skip if field not present or null
-      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), pass through
-          if (typeof fieldValue === 'object' && fieldValue !== null && fieldValue._descriptor === true) {
-            console.log(`${logPrefix} Field '${fieldName}' already Descriptor with _descriptor=true`);
-            normalizedOutput[fieldName] = fieldValue;
-          } else if (typeof fieldValue === 'object' && fieldValue !== null && (fieldValue.type === 'file' || fieldValue.type === 'inline')) {
-            // Looks like Descriptor but missing _descriptor flag - normalize
-            console.log(`${logPrefix} Field '${fieldName}' normalizing Descriptor (missing _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
-            console.log(`${logPrefix} Field '${fieldName}' converting string to Descriptor`);
-            normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue, {
-              filename: fieldSchema.filename,
-              content_type: fieldSchema.content_type
-            });
-          } else if (typeof fieldValue === 'object' && fieldValue !== null && fieldValue.storage_ref) {
-            // Object with storage_ref - extract and normalize
-            console.log(`${logPrefix} Field '${fieldName}' converting object with storage_ref to Descriptor`);
-            normalizedOutput[fieldName] = await accessor.normalizeToDescriptor(fieldValue.storage_ref, {
-              filename: fieldValue.filename || fieldValue.output_name,
-              content_type: fieldValue.content_type
-            });
-          } else {
-            // FAIL-FAST: Unexpected format for file/content field
-            console.error(`${logPrefix} FAIL-FAST: Field '${fieldName}' expects ${fieldType} but got unexpected format:`, {
-              valueType: typeof fieldValue,
-              valueKeys: fieldValue && typeof fieldValue === 'object' ? Object.keys(fieldValue) : null
-            });
-            throw new Error(`[ApiMapper] FAIL-FAST: Field '${fieldName}' expects '${fieldType}' but received unexpected format`);
-          }
-        } catch (error) {
-          if (error.message.includes('FAIL-FAST')) {
-            throw error; // Re-throw fail-fast errors
-          }
-          console.error(`${logPrefix} FAIL: Failed to normalize field '${fieldName}': ${error.message}`);
-          throw new Error(`[ApiMapper] FAIL-FAST: Failed to normalize field '${fieldName}' to Descriptor: ${error.message}`);
-        }
+        normalizedOutput[fieldName] = await this._convertToDescriptor(
+          fieldValue, fieldSchema, getContentResolver, logPrefix, context, fieldName
+        );
       }
     }
     
-    console.log(`${logPrefix} OUTPUT: Normalized fields:`, JSON.stringify(Object.keys(normalizedOutput)));
+    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