@aifabrix/builder 2.31.0 → 2.32.1

package/lib/utils/external-system-display.js

@@ -12,72 +12,210 @@ const chalk = require('chalk');
 const logger = require('./logger');
 
 /**
- * Displays formatted test results
- * @param {Object} results - Test results
- * @param {boolean} verbose - Show detailed output
+ * Displays system file results
+ * @function displaySystemResults
+ * @param {Object[]} systemResults - System file results
  */
-function displayTestResults(results, verbose = false) {
-  logger.log(chalk.blue('\n📊 Test Results\n'));
-
-  if (results.systemResults.length > 0) {
-    logger.log(chalk.blue('System Files:'));
-    for (const systemResult of results.systemResults) {
-      if (systemResult.valid) {
-        logger.log(chalk.green(`  ✓ ${systemResult.file}`));
-      } else {
-        logger.log(chalk.red(`  ✗ ${systemResult.file}`));
-      }
+function displaySystemResults(systemResults) {
+  if (systemResults.length === 0) {
+    return;
+  }
+  logger.log(chalk.blue('System Files:'));
+  for (const systemResult of systemResults) {
+    if (systemResult.valid) {
+      logger.log(chalk.green(`  ✓ ${systemResult.file}`));
+    } else {
+      logger.log(chalk.red(`  ✗ ${systemResult.file}`));
     }
   }
+}
 
-  if (results.datasourceResults.length > 0) {
-    logger.log(chalk.blue('\nDatasource Files:'));
-    for (const dsResult of results.datasourceResults) {
-      if (dsResult.valid) {
-        logger.log(chalk.green(`  ✓ ${dsResult.key} (${dsResult.file})`));
-      } else {
-        logger.log(chalk.red(`  ✗ ${dsResult.key} (${dsResult.file})`));
-        if (verbose && dsResult.errors.length > 0) {
-          dsResult.errors.forEach(err => logger.log(chalk.red(`    - ${err}`)));
-        }
-      }
+/**
+ * Displays verbose datasource details
+ * @function displayVerboseDatasourceDetails
+ * @param {Object} dsResult - Datasource result
+ */
+function displayVerboseDatasourceDetails(dsResult) {
+  if (dsResult.warnings.length > 0) {
+    dsResult.warnings.forEach(warn => logger.log(chalk.yellow(`    ⚠ ${warn}`)));
+  }
+
+  if (dsResult.fieldMappingResults) {
+    const fm = dsResult.fieldMappingResults;
+    logger.log(chalk.gray(`    Field mappings: ${Object.keys(fm.mappedFields || {}).length} fields`));
+  }
+
+  if (dsResult.metadataSchemaResults) {
+    const ms = dsResult.metadataSchemaResults;
+    const statusMsg = ms.valid ? '    Metadata schema: ✓ Valid' : '    Metadata schema: ✗ Invalid';
+    logger.log(ms.valid ? chalk.gray(statusMsg) : chalk.red(statusMsg));
+  }
+}
 
-      if (verbose) {
-        if (dsResult.warnings.length > 0) {
-          dsResult.warnings.forEach(warn => logger.log(chalk.yellow(`    ⚠ ${warn}`)));
-        }
-
-        if (dsResult.fieldMappingResults) {
-          const fm = dsResult.fieldMappingResults;
-          logger.log(chalk.gray(`    Field mappings: ${Object.keys(fm.mappedFields || {}).length} fields`));
-        }
-
-        if (dsResult.metadataSchemaResults) {
-          const ms = dsResult.metadataSchemaResults;
-          const statusMsg = ms.valid ? '    Metadata schema: ✓ Valid' : '    Metadata schema: ✗ Invalid';
-          logger.log(ms.valid ? chalk.gray(statusMsg) : chalk.red(statusMsg));
-        }
+/**
+ * Displays datasource file results
+ * @function displayDatasourceResults
+ * @param {Object[]} datasourceResults - Datasource file results
+ * @param {boolean} verbose - Show detailed output
+ */
+function displayDatasourceResults(datasourceResults, verbose) {
+  if (datasourceResults.length === 0) {
+    return;
+  }
+  logger.log(chalk.blue('\nDatasource Files:'));
+  for (const dsResult of datasourceResults) {
+    if (dsResult.valid) {
+      logger.log(chalk.green(`  ✓ ${dsResult.key} (${dsResult.file})`));
+    } else {
+      logger.log(chalk.red(`  ✗ ${dsResult.key} (${dsResult.file})`));
+      if (verbose && dsResult.errors.length > 0) {
+        dsResult.errors.forEach(err => logger.log(chalk.red(`    - ${err}`)));
       }
     }
+
+    if (verbose) {
+      displayVerboseDatasourceDetails(dsResult);
+    }
   }
+}
 
-  if (results.errors.length > 0) {
+/**
+ * Displays errors and warnings
+ * @function displayErrorsAndWarnings
+ * @param {string[]} errors - Error messages
+ * @param {string[]} warnings - Warning messages
+ */
+function displayErrorsAndWarnings(errors, warnings) {
+  if (errors.length > 0) {
     logger.log(chalk.red('\n❌ Errors:'));
-    results.errors.forEach(err => logger.log(chalk.red(`  - ${err}`)));
+    errors.forEach(err => logger.log(chalk.red(`  - ${err}`)));
   }
 
-  if (results.warnings.length > 0) {
+  if (warnings.length > 0) {
     logger.log(chalk.yellow('\n⚠ Warnings:'));
-    results.warnings.forEach(warn => logger.log(chalk.yellow(`  - ${warn}`)));
+    warnings.forEach(warn => logger.log(chalk.yellow(`  - ${warn}`)));
   }
+}
 
-  if (results.valid) {
+/**
+ * Displays final test status
+ * @function displayFinalTestStatus
+ * @param {boolean} valid - Whether all tests passed
+ */
+function displayFinalTestStatus(valid) {
+  if (valid) {
     logger.log(chalk.green('\n✅ All tests passed!'));
   } else {
     logger.log(chalk.red('\n❌ Some tests failed'));
   }
 }
 
+/**
+ * Displays formatted test results
+ * @param {Object} results - Test results
+ * @param {boolean} verbose - Show detailed output
+ */
+function displayTestResults(results, verbose = false) {
+  logger.log(chalk.blue('\n📊 Test Results\n'));
+
+  displaySystemResults(results.systemResults);
+  displayDatasourceResults(results.datasourceResults, verbose);
+  displayErrorsAndWarnings(results.errors, results.warnings);
+  displayFinalTestStatus(results.valid);
+}
+
+/**
+ * Displays validation results in verbose mode
+ * @function displayVerboseValidationResults
+ * @param {Object} vr - Validation results
+ */
+function displayVerboseValidationResults(vr) {
+  if (vr.isValid) {
+    logger.log(chalk.gray('    Validation: ✓ Valid'));
+  } else {
+    logger.log(chalk.red('    Validation: ✗ Invalid'));
+  }
+  if (vr.errors && vr.errors.length > 0) {
+    vr.errors.forEach(err => logger.log(chalk.red(`      - ${err}`)));
+  }
+  if (vr.warnings && vr.warnings.length > 0) {
+    vr.warnings.forEach(warn => logger.log(chalk.yellow(`      ⚠ ${warn}`)));
+  }
+}
+
+/**
+ * Displays field mapping results in verbose mode
+ * @function displayVerboseFieldMappingResults
+ * @param {Object} fmr - Field mapping results
+ */
+function displayVerboseFieldMappingResults(fmr) {
+  logger.log(chalk.gray(`    Field mappings: ${fmr.mappingCount || 0} attributes`));
+  if (fmr.dimensions && Object.keys(fmr.dimensions).length > 0) {
+    const dimensionKeys = Object.keys(fmr.dimensions);
+    logger.log(chalk.gray(`      Dimensions: ${dimensionKeys.join(', ')}`));
+  }
+}
+
+/**
+ * Displays endpoint test results in verbose mode
+ * @function displayVerboseEndpointResults
+ * @param {Object} etr - Endpoint test results
+ */
+function displayVerboseEndpointResults(etr) {
+  if (etr.endpointConfigured) {
+    logger.log(chalk.gray('    Endpoint: ✓ Configured'));
+  } else {
+    logger.log(chalk.gray('    Endpoint: Not configured'));
+  }
+}
+
+/**
+ * Displays verbose integration test details
+ * @function displayVerboseIntegrationDetails
+ * @param {Object} dsResult - Datasource result
+ */
+function displayVerboseIntegrationDetails(dsResult) {
+  if (!dsResult.validationResults) {
+    return;
+  }
+
+  displayVerboseValidationResults(dsResult.validationResults);
+
+  if (dsResult.fieldMappingResults) {
+    displayVerboseFieldMappingResults(dsResult.fieldMappingResults);
+  }
+
+  if (dsResult.endpointTestResults) {
+    displayVerboseEndpointResults(dsResult.endpointTestResults);
+  }
+}
+
+/**
+ * Displays a single datasource integration test result
+ * @function displayDatasourceIntegrationResult
+ * @param {Object} dsResult - Datasource result
+ * @param {boolean} verbose - Show detailed output
+ */
+function displayDatasourceIntegrationResult(dsResult, verbose) {
+  if (dsResult.skipped) {
+    logger.log(chalk.yellow(`  ⚠ ${dsResult.key}: ${dsResult.reason}`));
+    return;
+  }
+
+  if (dsResult.success) {
+    logger.log(chalk.green(`  ✓ ${dsResult.key}`));
+  } else {
+    logger.log(chalk.red(`  ✗ ${dsResult.key}`));
+    if (dsResult.error) {
+      logger.log(chalk.red(`    Error: ${dsResult.error}`));
+    }
+  }
+
+  if (verbose) {
+    displayVerboseIntegrationDetails(dsResult);
+  }
+}
+
 /**
  * Displays formatted integration test results
  * @param {Object} results - Integration test results
@@ -93,51 +231,7 @@ function displayIntegrationTestResults(results, verbose = false) {
   }
 
   for (const dsResult of results.datasourceResults) {
-    if (dsResult.skipped) {
-      logger.log(chalk.yellow(`  ⚠ ${dsResult.key}: ${dsResult.reason}`));
-      continue;
-    }
-
-    if (dsResult.success) {
-      logger.log(chalk.green(`  ✓ ${dsResult.key}`));
-    } else {
-      logger.log(chalk.red(`  ✗ ${dsResult.key}`));
-      if (dsResult.error) {
-        logger.log(chalk.red(`    Error: ${dsResult.error}`));
-      }
-    }
-
-    if (verbose && dsResult.validationResults) {
-      const vr = dsResult.validationResults;
-      if (vr.isValid) {
-        logger.log(chalk.gray('    Validation: ✓ Valid'));
-      } else {
-        logger.log(chalk.red('    Validation: ✗ Invalid'));
-      }
-      if (vr.errors && vr.errors.length > 0) {
-        vr.errors.forEach(err => logger.log(chalk.red(`      - ${err}`)));
-      }
-      if (vr.warnings && vr.warnings.length > 0) {
-        vr.warnings.forEach(warn => logger.log(chalk.yellow(`      ⚠ ${warn}`)));
-      }
-
-      if (dsResult.fieldMappingResults) {
-        const fmr = dsResult.fieldMappingResults;
-        logger.log(chalk.gray(`    Field mappings: ${fmr.mappingCount || 0} fields`));
-        if (fmr.accessFields && fmr.accessFields.length > 0) {
-          logger.log(chalk.gray(`      Access fields: ${fmr.accessFields.join(', ')}`));
-        }
-      }
-
-      if (dsResult.endpointTestResults) {
-        const etr = dsResult.endpointTestResults;
-        if (etr.endpointConfigured) {
-          logger.log(chalk.gray('    Endpoint: ✓ Configured'));
-        } else {
-          logger.log(chalk.gray('    Endpoint: Not configured'));
-        }
-      }
-    }
+    displayDatasourceIntegrationResult(dsResult, verbose);
   }
 
   if (results.success) {

package/lib/utils/external-system-validators.js

@@ -58,6 +58,158 @@ function validateFieldMappingExpression(expression) {
  * @param {Object} testPayload - Test payload object
  * @returns {Object} Validation results
  */
+/**
+ * Validates a single field mapping
+ * @function validateSingleFieldMapping
+ * @param {string} fieldName - Field name
+ * @param {Object} fieldConfig - Field configuration
+ * @param {Object} payloadTemplate - Payload template
+ * @param {Object} results - Results object to update
+ */
+function validateSingleFieldMapping(fieldName, fieldConfig, payloadTemplate, results) {
+  if (!fieldConfig.expression) {
+    results.errors.push(`Field '${fieldName}' missing expression`);
+    results.valid = false;
+    return;
+  }
+
+  // Validate expression syntax
+  const exprValidation = validateFieldMappingExpression(fieldConfig.expression);
+  if (!exprValidation.isValid) {
+    results.errors.push(`Field '${fieldName}': ${exprValidation.error}`);
+    results.valid = false;
+    return;
+  }
+
+  // Try to extract path from expression
+  const pathMatch = fieldConfig.expression.match(/\{\{([^}]+)\}\}/);
+  if (pathMatch) {
+    const fieldPath = pathMatch[1].trim();
+    const pathExists = checkPathExistsInPayload(fieldPath, payloadTemplate);
+
+    if (!pathExists) {
+      results.warnings.push(`Field '${fieldName}': Path '${fieldPath}' may not exist in payload`);
+    } else {
+      results.mappedFields[fieldName] = fieldConfig.expression;
+    }
+  }
+}
+
+/**
+ * Checks if path exists in payload
+ * @function checkPathExistsInPayload
+ * @param {string} fieldPath - Field path
+ * @param {Object} payloadTemplate - Payload template
+ * @returns {boolean} True if path exists
+ */
+function checkPathExistsInPayload(fieldPath, payloadTemplate) {
+  const pathParts = fieldPath.split('.');
+  let current = payloadTemplate;
+
+  for (const part of pathParts) {
+    if (current && typeof current === 'object' && part in current) {
+      current = current[part];
+    } else {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validates dimensions object structure and content
+ * @param {Object} dimensions - Dimensions object to validate
+ * @param {Object} results - Results object to update
+ */
+function validateDimensions(dimensions, results) {
+  if (!dimensions) {
+    results.errors.push('fieldMappings.dimensions is required (dimensions-first model)');
+    results.valid = false;
+    return;
+  }
+
+  if (typeof dimensions !== 'object' || Array.isArray(dimensions)) {
+    results.errors.push('fieldMappings.dimensions must be an object mapping dimension keys to attribute paths');
+    results.valid = false;
+    return;
+  }
+
+  // Validate dimension keys and values
+  for (const [dimensionKey, attributePath] of Object.entries(dimensions)) {
+    if (!/^[a-zA-Z0-9_]+$/.test(dimensionKey)) {
+      results.errors.push(`Invalid dimension key '${dimensionKey}': must match pattern ^[a-zA-Z0-9_]+$`);
+      results.valid = false;
+    }
+    if (typeof attributePath !== 'string' || !/^[a-zA-Z0-9_.]+$/.test(attributePath)) {
+      results.errors.push(`Invalid attribute path '${attributePath}' for dimension '${dimensionKey}': must match pattern ^[a-zA-Z0-9_.]+$`);
+      results.valid = false;
+    }
+  }
+}
+
+/**
+ * Validates attributes object structure
+ * @param {Object} attributes - Attributes object to validate
+ * @param {Object} results - Results object to update
+ * @returns {Object|null} Attributes object if valid, null otherwise
+ */
+function validateAttributesStructure(attributes, results) {
+  if (!attributes) {
+    results.errors.push('fieldMappings.attributes is required');
+    results.valid = false;
+    return null;
+  }
+
+  if (typeof attributes !== 'object' || Array.isArray(attributes)) {
+    results.errors.push('fieldMappings.attributes must be an object');
+    results.valid = false;
+    return null;
+  }
+
+  return attributes;
+}
+
+/**
+ * Validates a single attribute configuration
+ * @param {string} attributeName - Attribute name
+ * @param {Object} attributeConfig - Attribute configuration
+ * @param {Object} payloadTemplate - Payload template
+ * @param {Object} results - Results object to update
+ */
+function validateSingleAttribute(attributeName, attributeConfig, payloadTemplate, results) {
+  if (!attributeConfig || typeof attributeConfig !== 'object') {
+    results.errors.push(`Attribute '${attributeName}' must be an object with expression and type`);
+    results.valid = false;
+    return;
+  }
+
+  // Validate indexed property if present
+  if ('indexed' in attributeConfig && typeof attributeConfig.indexed !== 'boolean') {
+    results.errors.push(`Attribute '${attributeName}': indexed property must be a boolean`);
+    results.valid = false;
+  }
+
+  // Validate expression
+  if (!attributeConfig.expression || typeof attributeConfig.expression !== 'string') {
+    results.errors.push(`Attribute '${attributeName}': expression is required`);
+    results.valid = false;
+    return;
+  }
+
+  // Validate record_ref: expressions
+  if (attributeConfig.expression.startsWith('record_ref:')) {
+    const entityType = attributeConfig.expression.substring(11);
+    if (!/^[a-z0-9-]+$/.test(entityType)) {
+      results.errors.push(`Attribute '${attributeName}': Invalid entity type in record_ref expression: ${entityType}`);
+      results.valid = false;
+    }
+  } else {
+    // Validate regular expression syntax
+    validateSingleFieldMapping(attributeName, attributeConfig, payloadTemplate, results);
+  }
+}
+
 function validateFieldMappings(datasource, testPayload) {
   const results = {
     valid: true,
@@ -66,54 +218,24 @@ function validateFieldMappings(datasource, testPayload) {
     mappedFields: {}
   };
 
-  if (!datasource.fieldMappings || !datasource.fieldMappings.fields) {
+  if (!datasource.fieldMappings) {
     results.warnings.push('No field mappings defined');
     return results;
   }
 
-  const fields = datasource.fieldMappings.fields;
-  const payloadTemplate = testPayload.payloadTemplate || testPayload;
-
-  // Validate each field mapping expression
-  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
-    if (!fieldConfig.expression) {
-      results.errors.push(`Field '${fieldName}' missing expression`);
-      results.valid = false;
-      continue;
-    }
-
-    // Validate expression syntax
-    const exprValidation = validateFieldMappingExpression(fieldConfig.expression);
-    if (!exprValidation.isValid) {
-      results.errors.push(`Field '${fieldName}': ${exprValidation.error}`);
-      results.valid = false;
-      continue;
-    }
+  // Validate dimensions (required in new schema)
+  validateDimensions(datasource.fieldMappings.dimensions, results);
 
-    // Try to extract path from expression
-    const pathMatch = fieldConfig.expression.match(/\{\{([^}]+)\}\}/);
-    if (pathMatch) {
-      const fieldPath = pathMatch[1].trim();
-      // Check if path exists in payload (simple check)
-      const pathParts = fieldPath.split('.');
-      let current = payloadTemplate;
-      let pathExists = true;
-
-      for (const part of pathParts) {
-        if (current && typeof current === 'object' && part in current) {
-          current = current[part];
-        } else {
-          pathExists = false;
-          break;
-        }
-      }
+  // Validate attributes structure (required in new schema)
+  const attributes = validateAttributesStructure(datasource.fieldMappings.attributes, results);
+  if (!attributes) {
+    return results;
+  }
 
-      if (!pathExists) {
-        results.warnings.push(`Field '${fieldName}': Path '${fieldPath}' may not exist in payload`);
-      } else {
-        results.mappedFields[fieldName] = fieldConfig.expression;
-      }
-    }
+  // Validate each attribute
+  const payloadTemplate = testPayload.payloadTemplate || testPayload;
+  for (const [attributeName, attributeConfig] of Object.entries(attributes)) {
+    validateSingleAttribute(attributeName, attributeConfig, payloadTemplate, results);
   }
 
   return results;

package/lib/utils/file-upload.js

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview File upload utilities for multipart/form-data requests
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { makeApiCall, authenticatedApiCall } = require('./api');
+
+/**
+ * Upload a file using multipart/form-data
+ * @async
+ * @function uploadFile
+ * @param {string} url - API endpoint URL
+ * @param {string} filePath - Path to file to upload
+ * @param {string} fieldName - Form field name for the file (default: 'file')
+ * @param {Object} [authConfig] - Authentication configuration
+ * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-credentials')
+ * @param {string} [authConfig.token] - Bearer token
+ * @param {string} [authConfig.clientId] - Client ID
+ * @param {string} [authConfig.clientSecret] - Client secret
+ * @param {Object} [additionalFields] - Additional form fields to include
+ * @returns {Promise<Object>} API response
+ * @throws {Error} If file upload fails
+ */
+/**
+ * Validates file exists
+ * @async
+ * @function validateFileExists
+ * @param {string} filePath - File path
+ * @throws {Error} If file not found
+ */
+async function validateFileExists(filePath) {
+  try {
+    await fs.access(filePath);
+  } catch (error) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+}
+
+/**
+ * Builds FormData with file and additional fields
+ * @async
+ * @function buildFormData
+ * @param {string} filePath - File path
+ * @param {string} fieldName - Field name
+ * @param {Object} additionalFields - Additional fields
+ * @returns {Promise<FormData>} FormData object
+ */
+async function buildFormData(filePath, fieldName, additionalFields) {
+  const formData = new FormData();
+  const fileContent = await fs.readFile(filePath);
+  const fileName = path.basename(filePath);
+  const fileBlob = new Blob([fileContent], { type: 'application/octet-stream' });
+  formData.append(fieldName, fileBlob, fileName);
+
+  for (const [key, value] of Object.entries(additionalFields)) {
+    formData.append(key, String(value));
+  }
+
+  return formData;
+}
+
+/**
+ * Builds authentication headers
+ * @function buildAuthHeaders
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Object} Headers object
+ */
+function buildAuthHeaders(authConfig) {
+  const headers = {};
+  if (authConfig.type === 'bearer' && authConfig.token) {
+    headers['Authorization'] = `Bearer ${authConfig.token}`;
+  } else if (authConfig.type === 'client-credentials') {
+    if (authConfig.clientId) {
+      headers['x-client-id'] = authConfig.clientId;
+    }
+    if (authConfig.clientSecret) {
+      headers['x-client-secret'] = authConfig.clientSecret;
+    }
+  }
+  return headers;
+}
+
+async function uploadFile(url, filePath, fieldName = 'file', authConfig = {}, additionalFields = {}) {
+  await validateFileExists(filePath);
+
+  const formData = await buildFormData(filePath, fieldName, additionalFields);
+  const headers = buildAuthHeaders(authConfig);
+
+  const options = {
+    method: 'POST',
+    headers,
+    body: formData
+  };
+
+  // Use authenticatedApiCall if bearer token, otherwise makeApiCall
+  if (authConfig.type === 'bearer' && authConfig.token) {
+    return await authenticatedApiCall(url, options, authConfig.token);
+  }
+
+  return await makeApiCall(url, options);
+}
+
+module.exports = {
+  uploadFile
+};
+