@openmrs/esm-report-builder 0.1.1-pre.87

package/src/utils/etl-monitor/endpoint-config-normalizer.util.ts

@@ -0,0 +1,383 @@
+/**
+ * Endpoint Configuration Normalizer
+ * Handles conversion between legacy and v2 API endpoint configurations
+ */
+
+import type {
+  ApiEndpoint,
+  AuthType,
+} from '../../types/etl-monitor';
+
+/**
+ * Normalized endpoint configuration
+ * Uses consistent structure across all configuration versions
+ */
+export interface NormalizedEndpointConfig {
+  url: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  auth: {
+    type: 'NONE' | 'OPENMRS' | 'BASIC' | 'API_KEY' | 'BEARER_TOKEN';
+    useSession?: boolean;
+    username?: string;
+    password?: string;
+    headerName?: string;
+    apiKey?: string;
+    token?: string;
+  };
+  timeout?: number;
+  headers?: Record<string, string>;
+  queryParams?: Record<string, string>;
+  requestBody?: any;
+}
+
+/**
+ * Configuration format detection result
+ */
+export interface ConfigDetectionResult {
+  version: 'v1-legacy' | 'v1-apiEndpoint' | 'v2';
+  hasApiEndpoint: boolean;
+  hasApiUrl: boolean;
+  authFormat: 'nested' | 'flat' | 'mixed';
+  issues: string[];
+}
+
+/**
+ * Detect the configuration format version
+ */
+export function detectConfigFormat(config: any): ConfigDetectionResult {
+  const result: ConfigDetectionResult = {
+    version: 'v2',
+    hasApiEndpoint: false,
+    hasApiUrl: false,
+    authFormat: 'nested',
+    issues: [],
+  };
+
+  if (!config || typeof config !== 'object') {
+    result.version = 'v1-legacy';
+    result.issues.push('Invalid or empty configuration');
+    return result;
+  }
+
+  // Check for apiEndpoint (v1+ and v2)
+  if ('apiEndpoint' in config) {
+    result.hasApiEndpoint = true;
+    const endpoint = config.apiEndpoint;
+
+    if (!endpoint || typeof endpoint !== 'object') {
+      result.issues.push('apiEndpoint is not an object');
+      return result;
+    }
+
+    // Check for v2 nested auth structure
+    if ('auth' in endpoint && endpoint.auth && typeof endpoint.auth === 'object') {
+      if ('type' in endpoint.auth) {
+        result.version = 'v2';
+        result.authFormat = 'nested';
+        return result;
+      }
+    }
+
+    // Check for v1 flat auth structure
+    if ('authType' in endpoint || 'authConfig' in endpoint) {
+      result.version = 'v1-apiEndpoint';
+      result.authFormat = 'flat';
+      return result;
+    }
+
+    result.issues.push('apiEndpoint lacks auth configuration');
+  }
+
+  // Check for apiUrl (legacy v1)
+  if ('apiUrl' in config) {
+    result.hasApiUrl = true;
+    result.version = 'v1-legacy';
+    result.authFormat = 'flat';
+  }
+
+  // Default to v2 if schemaVersion is present
+  if (config.schemaVersion === 2) {
+    result.version = 'v2';
+  }
+
+  return result;
+}
+
+/**
+ * Normalize authentication configuration to v2 format
+ */
+export function normalizeAuthConfig(config: any): NormalizedEndpointConfig['auth'] {
+  if (!config) {
+    return { type: 'NONE' };
+  }
+
+  // V2 format: auth.type, auth.useSession
+  if (config.auth && typeof config.auth === 'object') {
+    const auth = config.auth;
+    return {
+      type: auth.type || 'NONE',
+      useSession: normalizeBoolean(auth.useSession),
+      username: auth.username,
+      password: auth.password,
+      headerName: auth.headerName,
+      apiKey: auth.apiKey,
+      token: auth.token,
+    };
+  }
+
+  // V1 format: authType, authConfig
+  if (config.authType) {
+    const authType = config.authType as AuthType;
+    const authConfig = config.authConfig || {};
+
+    return {
+      type: authType,
+      useSession: authType === 'OPENMRS' ? normalizeBoolean(authConfig.useSession) : undefined,
+      username: authConfig.username,
+      password: authConfig.password,
+      headerName: authConfig.headerName,
+      apiKey: authConfig.apiKey,
+      token: authConfig.token,
+    };
+  }
+
+  // Legacy format: authentication string
+  if (config.authentication) {
+    return {
+      type: config.authentication === 'OPENMRS' ? 'OPENMRS' : 'NONE',
+      useSession: config.authentication === 'OPENMRS' ? true : undefined,
+    };
+  }
+
+  return { type: 'NONE' };
+}
+
+/**
+ * Normalize a boolean value that might be stored as a string
+ */
+export function normalizeBoolean(value: any): boolean | undefined {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    return value.toLowerCase() === 'true';
+  }
+  return undefined;
+}
+
+/**
+ * Normalize HTTP method to uppercase
+ */
+export function normalizeMethod(method?: string): 'GET' | 'POST' | 'PUT' | 'DELETE' {
+  if (!method) return 'GET';
+  const upper = method.toUpperCase();
+  if (['GET', 'POST', 'PUT', 'DELETE'].includes(upper)) {
+    return upper as 'GET' | 'POST' | 'PUT' | 'DELETE';
+  }
+  return 'GET';
+}
+
+/**
+ * Sanitize URL by decoding HTML entities in query strings
+ * Converts &amp; to &, etc.
+ */
+export function sanitizeUrl(url: string): string {
+  if (!url) return '';
+
+  // Only decode in query strings (after ?)
+  const queryIndex = url.indexOf('?');
+  if (queryIndex === -1) return url;
+
+  const baseUrl = url.substring(0, queryIndex);
+  const queryString = url.substring(queryIndex);
+
+  // Decode HTML entities in query string
+  const decoded = queryString
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+
+  return baseUrl + decoded;
+}
+
+/**
+ * Validate URL structure
+ */
+export function validateUrl(url: string): { valid: boolean; error?: string } {
+  if (!url || typeof url !== 'string') {
+    return { valid: false, error: 'URL is required' };
+  }
+
+  const sanitized = sanitizeUrl(url);
+
+  // Check for unsafe schemes
+  const unsafeSchemes = ['file://', 'ftp://', 'jar://', 'data:', 'javascript:', 'vbscript:'];
+  for (const scheme of unsafeSchemes) {
+    if (sanitized.toLowerCase().startsWith(scheme)) {
+      return { valid: false, error: `Unsafe URL scheme: ${scheme}` };
+    }
+  }
+
+  // Validate URL format for absolute URLs
+  if (sanitized.includes('://')) {
+    try {
+      new URL(sanitized);
+    } catch {
+      return { valid: false, error: 'Invalid URL format' };
+    }
+  } else if (!sanitized.startsWith('/')) {
+    // Relative URLs must start with /
+    return { valid: false, error: 'Relative URLs must start with /' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Normalize endpoint configuration to v2 format
+ */
+export function normalizeEndpointConfig(config: any): NormalizedEndpointConfig {
+  const detection = detectConfigFormat(config);
+
+  const normalized: NormalizedEndpointConfig = {
+    url: '',
+    method: 'GET',
+    auth: { type: 'NONE' },
+  };
+
+  // Extract URL
+  if (detection.hasApiEndpoint && config.apiEndpoint) {
+    normalized.url = sanitizeUrl(config.apiEndpoint.url || '');
+    normalized.method = normalizeMethod(config.apiEndpoint.method);
+    normalized.auth = normalizeAuthConfig(config.apiEndpoint);
+    normalized.headers = config.apiEndpoint.headers;
+    normalized.queryParams = config.apiEndpoint.queryParams;
+    normalized.requestBody = config.apiEndpoint.requestBody;
+  } else if (detection.hasApiUrl) {
+    normalized.url = sanitizeUrl(config.apiUrl || '');
+    normalized.method = normalizeMethod(config.httpMethod);
+    normalized.auth = {
+      type: config.authentication || 'NONE',
+      useSession: config.authentication === 'OPENMRS' ? true : undefined,
+    };
+  }
+
+  return normalized;
+}
+
+/**
+ * Convert normalized config back to API endpoint format
+ */
+export function toApiEndpointFormat(normalized: NormalizedEndpointConfig): ApiEndpoint {
+  const endpoint: ApiEndpoint = {
+    url: normalized.url,
+    method: normalized.method,
+    authType: normalized.auth.type as AuthType,
+  };
+
+  // Build auth config based on type
+  if (normalized.auth.type !== 'NONE') {
+    endpoint.authConfig = {};
+
+    if (normalized.auth.type === 'BASIC') {
+      endpoint.authConfig.username = normalized.auth.username;
+      endpoint.authConfig.password = normalized.auth.password;
+    } else if (normalized.auth.type === 'API_KEY') {
+      endpoint.authConfig.headerName = normalized.auth.headerName;
+      endpoint.authConfig.apiKey = normalized.auth.apiKey;
+    } else if (normalized.auth.type === 'BEARER_TOKEN') {
+      endpoint.authConfig.token = normalized.auth.token;
+    } else if (normalized.auth.type === 'OPENMRS') {
+      endpoint.authConfig.useSession = normalized.auth.useSession ? 'true' : 'false';
+    }
+  }
+
+  if (normalized.headers) {
+    endpoint.headers = normalized.headers;
+  }
+
+  if (normalized.queryParams) {
+    endpoint.queryParams = normalized.queryParams;
+  }
+
+  if (normalized.requestBody) {
+    endpoint.requestBody = normalized.requestBody;
+  }
+
+  return endpoint;
+}
+
+/**
+ * Validate normalized endpoint configuration
+ */
+export function validateEndpointConfig(config: NormalizedEndpointConfig): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Validate URL
+  const urlValidation = validateUrl(config.url);
+  if (!urlValidation.valid) {
+    errors.push(urlValidation.error || 'Invalid URL');
+  }
+
+  // Validate auth configuration
+  if (config.auth.type === 'BASIC') {
+    if (!config.auth.username) {
+      errors.push('Username is required for Basic authentication');
+    }
+    if (!config.auth.password) {
+      warnings.push('Password is missing for Basic authentication');
+    }
+  } else if (config.auth.type === 'API_KEY') {
+    if (!config.auth.headerName) {
+      errors.push('Header name is required for API Key authentication');
+    }
+    if (!config.auth.apiKey) {
+      warnings.push('API Key is missing');
+    }
+  } else if (config.auth.type === 'BEARER_TOKEN') {
+    if (!config.auth.token) {
+      warnings.push('Bearer token is missing');
+    }
+  }
+
+  // Validate timeout
+  if (config.timeout !== undefined) {
+    if (config.timeout < 1 || config.timeout > 300) {
+      errors.push('Timeout must be between 1 and 300 seconds');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Merge multiple endpoint configs (last one wins for conflicts)
+ */
+export function mergeEndpointConfigs(...configs: Partial<NormalizedEndpointConfig>[]): NormalizedEndpointConfig {
+  const merged: NormalizedEndpointConfig = {
+    url: '',
+    method: 'GET',
+    auth: { type: 'NONE' },
+  };
+
+  for (const config of configs) {
+    if (config.url) merged.url = config.url;
+    if (config.method) merged.method = config.method;
+    if (config.auth) merged.auth = { ...merged.auth, ...config.auth };
+    if (config.timeout) merged.timeout = config.timeout;
+    if (config.headers) merged.headers = { ...merged.headers, ...config.headers };
+    if (config.queryParams) merged.queryParams = { ...merged.queryParams, ...config.queryParams };
+    if (config.requestBody) merged.requestBody = config.requestBody;
+  }
+
+  return merged;
+}

package/src/utils/etl-monitor/index.ts

@@ -0,0 +1,10 @@
+/**
+ * ETL Monitor Utilities
+ */
+export * from './endpoint-config-normalizer.util';
+export * from './config-v2-adapter.util';
+export * from './schema-inspector.util';
+export * from './semantic-type-detector.util';
+export * from './value-formatters.util';
+export * from './status-mapper.util';
+export * from './jsonpath-resolver.util';

package/src/utils/etl-monitor/jsonpath-resolver.util.ts

@@ -0,0 +1,118 @@
+/**
+ * JSONPath Resolver Utility
+ * Extract values from JSON using JSONPath-like expressions
+ */
+
+/**
+ * Get value from object using a simple path expression
+ * Supports dot notation and array indexing
+ */
+export function resolvePath(obj: any, path: string): any {
+  if (!obj || !path) {
+    return undefined;
+  }
+
+  const parts = path.split('.');
+  let current = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+
+    // Handle array indexing: items[0]
+    const arrayMatch = part.match(/^(\w+)\[(\d+)\]$/);
+    if (arrayMatch) {
+      const [, key, index] = arrayMatch;
+      current = current[key];
+      if (Array.isArray(current)) {
+        current = current[parseInt(index, 10)];
+      }
+    } else {
+      current = current[part];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Set value in object using path
+ */
+export function setPath(obj: any, path: string, value: any): void {
+  if (!obj || !path) {
+    return;
+  }
+
+  const parts = path.split('.');
+  const lastPart = parts.pop()!;
+  let current = obj;
+
+  for (const part of parts) {
+    if (!(part in current)) {
+      current[part] = {};
+    }
+    current = current[part];
+  }
+
+  current[lastPart] = value;
+}
+
+/**
+ * Get all values matching a pattern
+ */
+export function resolvePattern(obj: any, pattern: string): any[] {
+  if (!obj || !pattern) {
+    return [];
+  }
+
+  // Convert * pattern to regex
+  const regexPattern = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*/g, '[^.]*');
+  const regex = new RegExp(`^${regexPattern}$`);
+
+  const results: any[] = [];
+
+  function traverse(current: any, currentPath: string) {
+    if (typeof current !== 'object' || current === null) {
+      return;
+    }
+
+    for (const key in current) {
+      if (Object.prototype.hasOwnProperty.call(current, key)) {
+        const newPath = currentPath ? `${currentPath}.${key}` : key;
+        if (regex.test(newPath)) {
+          results.push({ path: newPath, value: current[key] });
+        }
+        traverse(current[key], newPath);
+      }
+    }
+  }
+
+  traverse(obj, '');
+  return results;
+}
+
+/**
+ * Extract field value using various strategies
+ */
+export function extractFieldValue(data: any, field: string): any {
+  // Try direct property access
+  if (field in data) {
+    return data[field];
+  }
+
+  // Try dot notation
+  const dotValue = resolvePath(data, field);
+  if (dotValue !== undefined) {
+    return dotValue;
+  }
+
+  // Try bracket notation
+  if (data[field] !== undefined) {
+    return data[field];
+  }
+
+  return undefined;
+}

package/src/utils/etl-monitor/schema-inspector.util.ts

@@ -0,0 +1,76 @@
+/**
+ * Schema Inspector Utility
+ * Provides functions for inspecting JSON schema and API response structures
+ */
+
+/**
+ * Inspect a JSON object and return its schema structure
+ */
+export function inspectSchema(obj: any): any {
+  if (!obj || typeof obj !== 'object') {
+    return { type: typeof obj };
+  }
+
+  if (Array.isArray(obj)) {
+    return {
+      type: 'array',
+      items: obj.length > 0 ? inspectSchema(obj[0]) : { type: 'unknown' },
+    };
+  }
+
+  const properties: Record<string, any> = {};
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      properties[key] = inspectSchema(obj[key]);
+    }
+  }
+
+  return { type: 'object', properties };
+}
+
+/**
+ * Get all keys from a nested object
+ */
+export function getAllKeys(obj: any, prefix = ''): string[] {
+  if (!obj || typeof obj !== 'object') {
+    return [];
+  }
+
+  const keys: string[] = [];
+
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      keys.push(fullKey);
+
+      if (typeof obj[key] === 'object' && obj[key] !== null && !Array.isArray(obj[key])) {
+        keys.push(...getAllKeys(obj[key], fullKey));
+      }
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Check if a value is empty
+ */
+export function isEmpty(value: any): boolean {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.length === 0;
+  }
+
+  if (typeof value === 'object') {
+    return Object.keys(value).length === 0;
+  }
+
+  if (typeof value === 'string') {
+    return value.trim() === '';
+  }
+
+  return false;
+}

package/src/utils/etl-monitor/semantic-type-detector.util.ts

@@ -0,0 +1,76 @@
+/**
+ * Semantic Type Detector Utility
+ * Detects semantic types from field names and values
+ */
+
+/**
+ * Detect semantic type from field name and value
+ */
+export function detectSemanticType(fieldName: string, value: any): string {
+  const name = fieldName.toLowerCase();
+
+  // Date patterns
+  if (name.includes('date') || name.includes('time')) {
+    if (isValidDate(value)) {
+      return name.includes('time') ? 'DATETIME' : 'DATE';
+    }
+  }
+
+  // Number patterns
+  if (name.includes('count') || name.includes('num') || name.includes('qty')) {
+    if (typeof value === 'number') {
+      return 'NUMBER';
+    }
+  }
+
+  // Status patterns
+  if (name.includes('status') || name.includes('state')) {
+    return 'STATUS';
+  }
+
+  // ID patterns
+  if (name.includes('id') || name.includes('uuid')) {
+    return 'ID';
+  }
+
+  // Boolean patterns
+  if (name.startsWith('is') || name.startsWith('has')) {
+    if (typeof value === 'boolean') {
+      return 'BOOLEAN';
+    }
+  }
+
+  // Default to string
+  return typeof value;
+}
+
+/**
+ * Check if value is a valid date
+ */
+function isValidDate(value: any): boolean {
+  if (!value) return false;
+  const date = new Date(value);
+  return !isNaN(date.getTime());
+}
+
+/**
+ * Get format hint for semantic type
+ */
+export function getFormatHint(semanticType: string): string {
+  switch (semanticType) {
+    case 'DATE':
+      return 'YYYY-MM-DD';
+    case 'DATETIME':
+      return 'YYYY-MM-DD HH:mm:ss';
+    case 'NUMBER':
+      return '#,##0.00';
+    case 'PERCENTAGE':
+      return '0.0%';
+    case 'BOOLEAN':
+      return 'true/false';
+    case 'STATUS':
+      return 'enum';
+    default:
+      return 'text';
+  }
+}