qapinterface/index.js

Comprehensive API utilities for Node.js applications including authentication, security, request processing, and response handling with zero external dependencies

/**
 * API Utilities NPM Module - Main Entry Point
 * 
 * ARCHITECTURE DESIGN & RATIONALE:
 * This module serves as the centralized export hub for a comprehensive API utilities library.
 * The design follows strict Single Responsibility Principle (SRP) where each imported module
 * handles exactly one concern, enabling developers to use only what they need while maintaining
 * a cohesive, well-tested API surface.
 * 
 * ORGANIZATION PHILOSOPHY:
 * Functions are grouped by domain (HTTP, Security, Authentication, etc.) rather than by
 * implementation details. This allows developers to quickly find related functionality
 * and understand the available tools for each aspect of API development.
 * 
 * WHY THIS APPROACH:
 * 1. Tree-shaking friendly - consumers only bundle what they import
 * 2. Maintainability - each module can be tested and updated independently
 * 3. Discoverability - clear categorization helps developers find relevant utilities
 * 4. API stability - changes to implementation don't affect the public interface
 * 5. Performance - lazy loading of heavy dependencies only when needed
 * 
 * DEPENDENCY STRATEGY:
 * All requires are synchronous and immediate because:
 * - Faster startup for CLI tools and serverless functions
 * - Predictable module resolution behavior
 * - Simpler error handling (fail fast on missing dependencies)
 * - Better IDE support for autocomplete and type checking
 */

// String operations (removed formatString per refactoring - see commit history)

// Validation operations - Input validation and sanitization modules
const { createValidator, validators } = require(`./lib/utility/validation`); // exposes validator factory & schema helpers
const { validateApiPath } = require(`./lib/validation/api-path-validator`);
const { validateEmail } = require(`./lib/validation/email-validator`);

// Data operations
const { sanitizeApiData } = require('./lib/data/sanitizer');

// Versioning operations
const { formatApiVersion } = require('./lib/versioning/formatter');

// ID generation
const { generateId } = require('./lib/id/generator');

// HTTP response operations - Standardized API response handling with error safety
const { createSuccessResponse } = require('./lib/http/success-response-creator');
const { sendJsonResponse } = require('./lib/http/json-response-sender');

// Enhanced error handling with qerrors integration (selective import to avoid winston issues)
let ErrorFactory, ErrorTypes, ErrorSeverity, handleControllerError, errorMiddleware, createTypedError;
try {
  // Import error types and factories first (these don't depend on winston)
  const qerrorsErrorTypes = require('qerrors/lib/errorTypes');
  ErrorFactory = qerrorsErrorTypes.ErrorFactory;
  ErrorTypes = qerrorsErrorTypes.ErrorTypes;
  ErrorSeverity = qerrorsErrorTypes.ErrorSeverity;
  createTypedError = qerrorsErrorTypes.createTypedError;
  handleControllerError = qerrorsErrorTypes.handleControllerError;
  errorMiddleware = qerrorsErrorTypes.errorMiddleware;
} catch (error) {
  console.warn('qerrors integration partially disabled due to winston compatibility issue');
  // Fallback to our existing error handling
  const { createErrorResponse } = require('./lib/http/error-response-creator');
  const { handleControllerError: legacyHandler } = require('./lib/http/controller-error-handler');
  ErrorFactory = { validation: (msg) => ({ message: msg, statusCode: 400 }) };
  ErrorTypes = { VALIDATION: 'validation', AUTHENTICATION: 'authentication' };
  ErrorSeverity = { LOW: 'low', MEDIUM: 'medium', HIGH: 'high', CRITICAL: 'critical' };
  createTypedError = (msg, type, code) => ({ message: msg, type, code });
  handleControllerError = legacyHandler;
  errorMiddleware = (err, req, res, next) => res.status(500).json(createErrorResponse('Internal Server Error'));
}

// Import createErrorResponse for backward compatibility
const { createErrorResponse } = require('./lib/http/error-response-creator');

// Enhanced error handling implementations
const { 
  createEnhancedError,
  createValidationError,
  createAuthenticationError,
  createDatabaseError,
  createNetworkError
} = require('./lib/error-handling/enhanced-error-factory');

const {
  handleControllerErrorEnhanced,
  withErrorHandling,
  enhancedErrorMiddleware
} = require('./lib/error-handling/controller-error-handler-enhanced');

// Enhanced logging capabilities
const {
  logger: structuredLogger,
  createPerformanceTimer,
  loggedExecution,
  sanitizeContext
} = require('./lib/logging/structured-logger');

// AI-powered error analysis
const {
  analyzeErrorWithGemini,
  handleErrorWithAI,
  isAIAnalysisAvailable
} = require('./lib/ai-analysis/gemini-error-analyzer');

// Security: CSP operations - Content Security Policy implementation for XSS protection
const { generateSecureNonce } = require('./lib/security/csp-nonce-generator');
const { nonceGenerator } = require('./lib/security/nonce-middleware');
const { createCSPHeader } = require('./lib/security/csp-header-builder');
const { validateCSPNonce } = require('./lib/security/csp-nonce-validator');

// Security: HTTPS operations - Force HTTPS redirect middleware for secure communications
const { enforceHTTPS } = require('./lib/security/https-enforcer');

// Security: Event operations - Security incident logging and monitoring infrastructure
const { logSecurityEvent } = require('./lib/security/event-logger');

// Security: Detection operations - Real-time threat detection for common attack patterns
const { detectSQLInjection } = require('./lib/security/sql-injection-detector');
const { detectNoSQLInjection } = require('./lib/security/nosql-injection-detector');
const { detectXSSAttempts } = require('./lib/security/xss-detector');
const { detectPathTraversal } = require('./lib/security/path-traversal-detector');
const { detectSuspiciousUserAgent } = require('./lib/security/user-agent-analyzer');
const { analyzeSecurityPatterns } = require('./lib/security/pattern-analyzer');
const { createSecurityMonitoringMiddleware } = require('./lib/security/monitoring-middleware');

// Request operations
const { generateRequestId } = require('./lib/request/id-generator');
const { extractRequestContext } = require('./lib/request/context-extractor');
const { validateRequestStructure } = require('./lib/request/structure-validator');

// Timing operations
const { startTiming, calculateProcessingTime } = require('./lib/timing/timer');

// Rate limiting operations
const { createRateLimitTracker } = require('./lib/rate-limiting/rate-limit-tracker');

// Middleware operations
const { createRequestProcessingMiddleware } = require('./lib/middleware/request-processor');
const { securityMiddlewareStack } = require('./lib/middleware/security-stack-creator');
const { handleValidationErrors } = require('./lib/middleware/validation-error-handler');
const { requestLogger } = require('./lib/middleware/request-logger');
const { errorLogger } = require('./lib/middleware/error-logger');

// Service operations  
const { checkServiceHealth } = require('./lib/services/health-check');
const { validateServiceConnection } = require('./lib/services/retry-handler');
const { validateServiceAsync } = require('./lib/services/async-validator');
const { validateMultipleServices } = require('./lib/services/multi-validator');
const { validateServiceWithErrorClassification } = require('./lib/services/error-classifier');
const { connectWithRetry } = require('./lib/service');

// Authentication operations
const { extractApiKey } = require('./lib/authentication/api-key-extractor');
const { generateApiKey } = require('./lib/authentication/api-key-generator');
const { validateApiKeyFormat } = require('./lib/api');
const { createCookieApiKeyMiddleware } = require('./lib/authentication/cookie-api-key-middleware');
const { validateApiKeyEnvironment, shouldSkipAuthentication } = require('./lib/authentication/environment-validator');
const { extractApiKeyFromCookie, extractMultipleCookies } = require('./lib/authentication/cookie-extractor');

// API operations
const { handleApiCall } = require('./lib/api/call-handler');
const { processApiResponse } = require('./lib/api/response-processor');
const { extractApiError } = require('./lib/api/error-extractor');
const { logApiCallStart, logApiCallSuccess, logApiCallError } = require('./lib/api/call-logger');

// Retry operations
const { withRetry } = require('./lib/retry/retry-handler');
const { calculateRetryDelay } = require('./lib/retry/delay-calculator');
const { sleep, sleepWithJitter } = require('./lib/retry/sleep-handler');
const { isRetryableError, getErrorCategory } = require('./lib/retry/error-classifier');
const { logRetryAttempt, logRetryFailure, logRetrySuccess } = require('./lib/retry/retry-logger');

// URL operations
const { createUrlSchema } = require('./lib/url/schema-creator');
const { createUrlValidationMiddleware } = require('./lib/url/validation-middleware');
const { buildUrl } = require('./lib/url/builder');
const { parseUrlParts } = require('./lib/url/parser');
const { validateProxyUrl } = require('./lib/url/proxy-validator');
const { getTargetUrlParts } = require('./lib/url/target-extractor');
const { createProxyUrlValidationMiddleware } = require('./lib/url/proxy-middleware');

// Additional clean SRP functions
const { _assertString } = require('./lib/utils');
const { createSecurityMiddleware } = require('./lib/security');
const { appendQueryParams } = require('./lib/url');
const { addRequestId } = require('./lib/request');

// Logging operations
const { createLogger } = require('./lib/logging/logger-creator');
const { closeLogger } = require('./lib/logging/logger-closer');
const { startMemoryMonitoring } = require('./lib/logging/memory-monitor-starter');
const { stopMemoryMonitoring } = require('./lib/logging/memory-monitor-stopper');
const { initializeLogger, logger: asyncLogger } = require('./lib/asyncLogger');
const { createMemoryMonitor, MemoryMonitor } = require('./lib/utility/memoryMonitor'); // memory monitor utilities

// Rate limiting
const { createRateLimiter } = require('./lib/rate-limiting/limiter-creator');
const { createRateLimiterMiddleware } = require('./lib/rate-limiting/middleware-creator');

module.exports = {
  // String operations (formatString removed per refactoring)

  // Validation operations
  createValidator,
  validateApiPath,
  validateEmail,
  validators,
  
  // Data operations
  sanitizeApiData,
  
  // Versioning operations
  formatApiVersion,
  
  // ID generation
  generateId,
  
  // HTTP operations
  createSuccessResponse,
  createErrorResponse, // Backward compatibility
  sendJsonResponse,
  
  // Enhanced Error Handling (qerrors integration)
  ErrorFactory,
  ErrorTypes,
  ErrorSeverity,
  handleControllerError,
  errorMiddleware,
  createTypedError,
  
  // Enhanced Error Creation
  createEnhancedError,
  createValidationError,
  createAuthenticationError,  
  createDatabaseError,
  createNetworkError,
  
  // Enhanced Controller Error Handling
  handleControllerErrorEnhanced,
  withErrorHandling,
  enhancedErrorMiddleware,
  
  // Security: CSP operations
  generateSecureNonce,
  nonceGenerator,
  createCSPHeader,
  validateCSPNonce,
  
  // Security: HTTPS operations
  enforceHTTPS,
  
  // Security: Event operations
  logSecurityEvent,
  
  // Security: Detection operations
  detectSQLInjection,
  detectNoSQLInjection,
  detectXSSAttempts,
  detectPathTraversal,
  detectSuspiciousUserAgent,
  analyzeSecurityPatterns,
  createSecurityMonitoringMiddleware,
  
  // Request operations
  generateRequestId,
  addRequestId,
  extractRequestContext,
  validateRequestStructure,
  
  // Timing operations
  startTiming,
  calculateProcessingTime,
  
  // Rate limiting operations
  createRateLimitTracker,
  createRateLimiter,
  createRateLimiterMiddleware,
  
  // Middleware operations
  createRequestProcessingMiddleware,
  securityMiddlewareStack,
  handleValidationErrors,
  requestLogger,
  errorLogger,
  
  // Service operations
  checkServiceHealth,
  validateServiceConnection,
  validateServiceAsync,
  validateMultipleServices,
  validateServiceWithErrorClassification,
  connectWithRetry,
  
  // Authentication operations
  extractApiKey,
  generateApiKey,
  validateApiKeyFormat,
  createCookieApiKeyMiddleware,
  validateApiKeyEnvironment,
  shouldSkipAuthentication,
  extractApiKeyFromCookie,
  extractMultipleCookies,
  
  // API operations
  handleApiCall,
  processApiResponse,
  extractApiError,
  logApiCallStart,
  logApiCallSuccess,
  logApiCallError,
  
  // Retry operations
  withRetry,
  calculateRetryDelay,
  sleep,
  sleepWithJitter,
  isRetryableError,
  getErrorCategory,
  logRetryAttempt,
  logRetryFailure,
  logRetrySuccess,
  
  // URL operations
  createUrlSchema,
  createUrlValidationMiddleware,
  buildUrl,
  parseUrlParts,
  validateProxyUrl,
  getTargetUrlParts,
  createProxyUrlValidationMiddleware,
  
  // Additional clean SRP functions
  _assertString,
  createSecurityMiddleware,
  appendQueryParams,
  
  // Enhanced Logging (structured logging with performance monitoring)
  structuredLogger,
  createPerformanceTimer,
  loggedExecution,
  sanitizeContext,
  
  // AI-Powered Error Analysis (Gemini integration)
  analyzeErrorWithGemini,
  handleErrorWithAI,
  isAIAnalysisAvailable,
  
  // Basic Logging operations
  createLogger,
  closeLogger,
  startMemoryMonitoring,
  stopMemoryMonitoring,
  createMemoryMonitor,
  MemoryMonitor,
  initializeLogger,
  asyncLogger,
};