view data fixes

apps/website/lib/gateways/api/base/ApiConnectionMonitor.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ApiConnectionMonitor } from './ApiConnectionMonitor';
+
+describe('ApiConnectionMonitor', () => {
+  let monitor: ApiConnectionMonitor;
+
+  beforeEach(() => {
+    // Reset singleton instance
+    (ApiConnectionMonitor as any).instance = undefined;
+    monitor = ApiConnectionMonitor.getInstance();
+  });
+
+  describe('getInstance', () => {
+    it('should return a singleton instance', () => {
+      const instance1 = ApiConnectionMonitor.getInstance();
+      const instance2 = ApiConnectionMonitor.getInstance();
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe('startMonitoring', () => {
+    it('should start monitoring without errors', () => {
+      expect(() => monitor.startMonitoring()).not.toThrow();
+    });
+
+    it('should be idempotent', () => {
+      monitor.startMonitoring();
+      expect(() => monitor.startMonitoring()).not.toThrow();
+    });
+  });
+
+  describe('recordSuccess', () => {
+    it('should record a successful request', () => {
+      const responseTime = 100;
+      monitor.recordSuccess(responseTime);
+      
+      const health = monitor.getHealth();
+      expect(health.totalRequests).toBe(1);
+      expect(health.successfulRequests).toBe(1);
+      expect(health.failedRequests).toBe(0);
+    });
+
+    it('should update average response time', () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(200);
+      
+      const health = monitor.getHealth();
+      expect(health.averageResponseTime).toBe(150);
+    });
+  });
+
+  describe('recordFailure', () => {
+    it('should record a failed request', () => {
+      const error = new Error('Test error');
+      monitor.recordFailure(error);
+      
+      const health = monitor.getHealth();
+      expect(health.totalRequests).toBe(1);
+      expect(health.successfulRequests).toBe(0);
+      expect(health.failedRequests).toBe(1);
+    });
+
+    it('should track consecutive failures', () => {
+      const error1 = new Error('Error 1');
+      const error2 = new Error('Error 2');
+      
+      monitor.recordFailure(error1);
+      monitor.recordFailure(error2);
+      
+      const health = monitor.getHealth();
+      expect(health.consecutiveFailures).toBe(2);
+    });
+  });
+
+  describe('getStatus', () => {
+    it('should return current status', () => {
+      const status = monitor.getStatus();
+      expect(typeof status).toBe('string');
+      expect(['connected', 'disconnected', 'degraded', 'checking']).toContain(status);
+    });
+  });
+
+  describe('getHealth', () => {
+    it('should return health metrics', () => {
+      const health = monitor.getHealth();
+      expect(health).toHaveProperty('status');
+      expect(health).toHaveProperty('lastCheck');
+      expect(health).toHaveProperty('lastSuccess');
+      expect(health).toHaveProperty('lastFailure');
+      expect(health).toHaveProperty('consecutiveFailures');
+      expect(health).toHaveProperty('totalRequests');
+      expect(health).toHaveProperty('successfulRequests');
+      expect(health).toHaveProperty('failedRequests');
+      expect(health).toHaveProperty('averageResponseTime');
+    });
+
+    it('should calculate success rate correctly', () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error('Test'));
+      
+      const health = monitor.getHealth();
+      const successRate = health.successfulRequests / health.totalRequests;
+      expect(successRate).toBeCloseTo(2/3, 10);
+    });
+  });
+
+  describe('isAvailable', () => {
+    it('should return true when healthy', () => {
+      // Record some successful requests
+      for (let i = 0; i < 5; i++) {
+        monitor.recordSuccess(100);
+      }
+      
+      expect(monitor.isAvailable()).toBe(true);
+    });
+
+    it('should return false when many failures occur', () => {
+      // Record many failures
+      for (let i = 0; i < 10; i++) {
+        monitor.recordFailure(new Error('Test'));
+      }
+
+      expect(monitor.isAvailable()).toBe(false);
+    });
+  });
+
+  describe('getReliability', () => {
+    it('should return reliability score', () => {
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+      monitor.recordSuccess(100);
+      monitor.recordFailure(new Error('Test'));
+      
+      const reliability = monitor.getReliability();
+      expect(reliability).toBeGreaterThanOrEqual(0);
+      expect(reliability).toBeLessThanOrEqual(100);
+    });
+
+    it('should return 1 for perfect reliability', () => {
+      for (let i = 0; i < 10; i++) {
+        monitor.recordSuccess(100);
+      }
+
+      expect(monitor.getReliability()).toBe(100);
+    });
+
+    it('should return 0 for complete failure', () => {
+      for (let i = 0; i < 10; i++) {
+        monitor.recordFailure(new Error('Test'));
+      }
+      
+      expect(monitor.getReliability()).toBe(0);
+    });
+  });
+
+  describe('performHealthCheck', () => {
+    it('should return health check result', async () => {
+      const result = await monitor.performHealthCheck();
+      expect(result).toHaveProperty('timestamp');
+      expect(result).toHaveProperty('healthy');
+      expect(result).toHaveProperty('responseTime');
+    });
+  });
+});

apps/website/lib/gateways/api/base/ApiConnectionMonitor.ts

@@ -0,0 +1,349 @@
+/**
+ * API Connection Status Monitor and Health Checks
+ */
+
+import { EventEmitter } from 'events';
+
+export type ConnectionStatus = 'connected' | 'disconnected' | 'degraded' | 'checking';
+
+export interface ConnectionHealth {
+  status: ConnectionStatus;
+  lastCheck: Date | null;
+  lastSuccess: Date | null;
+  lastFailure: Date | null;
+  consecutiveFailures: number;
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  averageResponseTime: number;
+}
+
+export interface HealthCheckResult {
+  healthy: boolean;
+  responseTime: number;
+  error?: string;
+  timestamp: Date;
+}
+
+export class ApiConnectionMonitor extends EventEmitter {
+  private static instance: ApiConnectionMonitor;
+  private health: ConnectionHealth;
+  private isChecking = false;
+  private checkInterval: NodeJS.Timeout | null = null;
+  private healthCheckEndpoint: string;
+  private readonly CHECK_INTERVAL = 300000; // 5 minutes
+  private readonly DEGRADATION_THRESHOLD = 0.7; // 70% failure rate
+
+  private constructor(healthCheckEndpoint: string = '/health') {
+    super();
+    this.healthCheckEndpoint = healthCheckEndpoint;
+    this.health = {
+      status: 'disconnected',
+      lastCheck: null,
+      lastSuccess: null,
+      lastFailure: null,
+      consecutiveFailures: 0,
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      averageResponseTime: 0,
+    };
+  }
+
+  static getInstance(healthCheckEndpoint?: string): ApiConnectionMonitor {
+    if (!ApiConnectionMonitor.instance) {
+      ApiConnectionMonitor.instance = new ApiConnectionMonitor(healthCheckEndpoint);
+    }
+    return ApiConnectionMonitor.instance;
+  }
+
+  /**
+   * Start automatic health monitoring
+   */
+  startMonitoring(intervalMs?: number): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+    }
+
+    const interval = intervalMs || this.CHECK_INTERVAL;
+    this.checkInterval = setInterval(() => {
+      this.performHealthCheck();
+    }, interval);
+
+    // Initial check
+    this.performHealthCheck();
+  }
+
+  /**
+   * Stop automatic health monitoring
+   */
+  stopMonitoring(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+  }
+
+  /**
+   * Perform a manual health check
+   */
+  async performHealthCheck(): Promise<HealthCheckResult> {
+    if (this.isChecking) {
+      return {
+        healthy: false,
+        responseTime: 0,
+        error: 'Check already in progress',
+        timestamp: new Date(),
+      };
+    }
+
+    this.isChecking = true;
+    const startTime = Date.now();
+
+    try {
+      // Try multiple endpoints to determine actual connectivity
+      const baseUrl = this.getBaseUrl();
+      const endpointsToTry = [
+        `${baseUrl}${this.healthCheckEndpoint}`,
+        `${baseUrl}/api/health`,
+        `${baseUrl}/status`,
+        baseUrl, // Root endpoint
+      ];
+
+      let lastError: Error | null = null;
+      let successfulResponse: Response | null = null;
+
+      for (const endpoint of endpointsToTry) {
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 3000);
+
+          const response = await fetch(endpoint, {
+            method: 'GET',
+            signal: controller.signal,
+            cache: 'no-store',
+            // Add credentials to handle auth
+            credentials: 'include',
+          });
+
+          clearTimeout(timeoutId);
+
+          // Consider any response (even 404) as connectivity success
+          if (response.ok || response.status === 404 || response.status === 401) {
+            successfulResponse = response;
+            break;
+          }
+        } catch (endpointError) {
+          lastError = endpointError as Error;
+          // Try next endpoint
+          continue;
+        }
+      }
+
+      const responseTime = Date.now() - startTime;
+
+      if (successfulResponse) {
+        this.recordSuccess(responseTime);
+        this.isChecking = false;
+
+        return {
+          healthy: true,
+          responseTime,
+          timestamp: new Date(),
+        };
+      } else {
+        // If we got here, all endpoints failed
+        const errorMessage = lastError?.message || 'All endpoints failed to respond';
+        this.recordFailure(errorMessage);
+        this.isChecking = false;
+
+        return {
+          healthy: false,
+          responseTime,
+          error: errorMessage,
+          timestamp: new Date(),
+        };
+      }
+    } catch (error) {
+      const responseTime = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      
+      this.recordFailure(errorMessage);
+      this.isChecking = false;
+
+      return {
+        healthy: false,
+        responseTime,
+        error: errorMessage,
+        timestamp: new Date(),
+      };
+    }
+  }
+
+  /**
+   * Record a successful API request
+   */
+  recordSuccess(responseTime: number = 0): void {
+    this.health.totalRequests++;
+    this.health.successfulRequests++;
+    this.health.consecutiveFailures = 0;
+    this.health.lastSuccess = new Date();
+    this.health.lastCheck = new Date();
+
+    // Update average response time
+    const total = this.health.successfulRequests;
+    this.health.averageResponseTime = 
+      ((this.health.averageResponseTime * (total - 1)) + responseTime) / total;
+
+    this.updateStatus();
+    this.emit('success', { responseTime });
+  }
+
+  /**
+   * Record a failed API request
+   */
+  recordFailure(error: string | Error): void {
+    this.health.totalRequests++;
+    this.health.failedRequests++;
+    this.health.consecutiveFailures++;
+    this.health.lastFailure = new Date();
+    this.health.lastCheck = new Date();
+
+    this.updateStatus();
+    this.emit('failure', { 
+      error: typeof error === 'string' ? error : error.message,
+      consecutiveFailures: this.health.consecutiveFailures 
+    });
+  }
+
+  /**
+   * Get current connection health
+   */
+  getHealth(): ConnectionHealth {
+    return { ...this.health };
+  }
+
+  /**
+   * Get current connection status
+   */
+  getStatus(): ConnectionStatus {
+    return this.health.status;
+  }
+
+  /**
+   * Check if API is currently available
+   */
+  isAvailable(): boolean {
+    return this.health.status === 'connected' || this.health.status === 'degraded';
+  }
+
+  /**
+   * Get reliability percentage
+   */
+  getReliability(): number {
+    if (this.health.totalRequests === 0) return 0;
+    return (this.health.successfulRequests / this.health.totalRequests) * 100;
+  }
+
+  /**
+   * Reset all statistics
+   */
+  reset(): void {
+    this.health = {
+      status: 'disconnected',
+      lastCheck: null,
+      lastSuccess: null,
+      lastFailure: null,
+      consecutiveFailures: 0,
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      averageResponseTime: 0,
+    };
+    this.emit('reset');
+  }
+
+  /**
+   * Get detailed status report for development
+   */
+  getDebugReport(): string {
+    const reliability = this.getReliability().toFixed(2);
+    const avgTime = this.health.averageResponseTime.toFixed(2);
+    
+    return `API Connection Status:
+  Status: ${this.health.status}
+  Reliability: ${reliability}%
+  Total Requests: ${this.health.totalRequests}
+  Successful: ${this.health.successfulRequests}
+  Failed: ${this.health.failedRequests}
+  Consecutive Failures: ${this.health.consecutiveFailures}
+  Avg Response Time: ${avgTime}ms
+  Last Check: ${this.health.lastCheck?.toISOString() || 'never'}
+  Last Success: ${this.health.lastSuccess?.toISOString() || 'never'}
+  Last Failure: ${this.health.lastFailure?.toISOString() || 'never'}`;
+  }
+
+  private updateStatus(): void {
+    const reliability = this.health.totalRequests > 0
+      ? this.health.successfulRequests / this.health.totalRequests
+      : 0;
+
+    // More nuanced status determination
+    if (this.health.totalRequests === 0) {
+      // No requests yet - don't assume disconnected
+      this.health.status = 'checking';
+    } else if (this.health.consecutiveFailures >= 3) {
+      // Multiple consecutive failures indicates real connectivity issue
+      this.health.status = 'disconnected';
+    } else if (reliability < this.DEGRADATION_THRESHOLD && this.health.totalRequests >= 5) {
+      // Only degrade if we have enough samples and reliability is low
+      this.health.status = 'degraded';
+    } else if (reliability >= this.DEGRADATION_THRESHOLD || this.health.successfulRequests > 0) {
+      // If we have any successes, we're connected
+      this.health.status = 'connected';
+    } else {
+      // Default to checking if uncertain
+      this.health.status = 'checking';
+    }
+
+    // Emit status change events (only on actual changes)
+    if (this.health.status === 'disconnected') {
+      this.emit('disconnected');
+    } else if (this.health.status === 'degraded') {
+      this.emit('degraded');
+    } else if (this.health.status === 'connected') {
+      this.emit('connected');
+    } else if (this.health.status === 'checking') {
+      this.emit('checking');
+    }
+  }
+
+  private getBaseUrl(): string {
+    // Try to get base URL from environment or fallback
+    if (typeof window !== 'undefined') {
+      return process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3001';
+    }
+    return process.env.API_BASE_URL || process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3001';
+  }
+}
+
+/**
+ * Global connection status utility
+ */
+export const connectionMonitor = ApiConnectionMonitor.getInstance();
+
+/**
+ * Hook for React components to monitor connection status
+ */
+export function useConnectionStatus() {
+  const monitor = ApiConnectionMonitor.getInstance();
+  
+  return {
+    status: monitor.getStatus(),
+    health: monitor.getHealth(),
+    isAvailable: monitor.isAvailable(),
+    reliability: monitor.getReliability(),
+    checkHealth: () => monitor.performHealthCheck(),
+    getDebugReport: () => monitor.getDebugReport(),
+  };
+}

apps/website/lib/gateways/api/base/ApiError.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { ApiError, isApiError, isNetworkError, isAuthError, isRetryableError } from './ApiError';
+import type { ApiErrorType, ApiErrorContext } from './ApiError';
+
+describe('ApiError', () => {
+  describe('constructor', () => {
+    it('should create an ApiError with correct properties', () => {
+      const context: ApiErrorContext = {
+        endpoint: '/api/test',
+        method: 'GET',
+        timestamp: '2024-01-01T00:00:00Z',
+        statusCode: 500,
+      };
+
+      const error = new ApiError('Test error', 'SERVER_ERROR', context);
+
+      expect(error.message).toBe('Test error');
+      expect(error.type).toBe('SERVER_ERROR');
+      expect(error.context).toEqual(context);
+      expect(error.name).toBe('ApiError');
+    });
+
+    it('should accept an optional originalError', () => {
+      const originalError = new Error('Original');
+      const context: ApiErrorContext = { timestamp: '2024-01-01T00:00:00Z' };
+      
+      const error = new ApiError('Wrapped', 'NETWORK_ERROR', context, originalError);
+
+      expect(error.originalError).toBe(originalError);
+    });
+  });
+
+  describe('getUserMessage', () => {
+    it('should return correct user message for NETWORK_ERROR', () => {
+      const error = new ApiError('Connection failed', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Unable to connect to the server. Please check your internet connection.');
+    });
+
+    it('should return correct user message for AUTH_ERROR', () => {
+      const error = new ApiError('Unauthorized', 'AUTH_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Authentication required. Please log in again.');
+    });
+
+    it('should return correct user message for VALIDATION_ERROR', () => {
+      const error = new ApiError('Invalid data', 'VALIDATION_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('The data you provided is invalid. Please check your input.');
+    });
+
+    it('should return correct user message for NOT_FOUND', () => {
+      const error = new ApiError('Not found', 'NOT_FOUND', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('The requested resource was not found.');
+    });
+
+    it('should return correct user message for SERVER_ERROR', () => {
+      const error = new ApiError('Server error', 'SERVER_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Server is experiencing issues. Please try again later.');
+    });
+
+    it('should return correct user message for RATE_LIMIT_ERROR', () => {
+      const error = new ApiError('Rate limited', 'RATE_LIMIT_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Too many requests. Please wait a moment and try again.');
+    });
+
+    it('should return correct user message for TIMEOUT_ERROR', () => {
+      const error = new ApiError('Timeout', 'TIMEOUT_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Request timed out. Please try again.');
+    });
+
+    it('should return correct user message for CANCELED_ERROR', () => {
+      const error = new ApiError('Canceled', 'CANCELED_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('Request was canceled.');
+    });
+
+    it('should return correct user message for UNKNOWN_ERROR', () => {
+      const error = new ApiError('Unknown', 'UNKNOWN_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getUserMessage()).toBe('An unexpected error occurred. Please try again.');
+    });
+  });
+
+  describe('getDeveloperMessage', () => {
+    it('should return developer message with type and message', () => {
+      const error = new ApiError('Test error', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getDeveloperMessage()).toBe('[NETWORK_ERROR] Test error');
+    });
+
+    it('should include endpoint and method when available', () => {
+      const context: ApiErrorContext = {
+        endpoint: '/api/users',
+        method: 'POST',
+        timestamp: '2024-01-01T00:00:00Z',
+      };
+      const error = new ApiError('Test error', 'SERVER_ERROR', context);
+      expect(error.getDeveloperMessage()).toBe('[SERVER_ERROR] Test error POST /api/users');
+    });
+
+    it('should include status code when available', () => {
+      const context: ApiErrorContext = {
+        endpoint: '/api/users',
+        method: 'GET',
+        statusCode: 404,
+        timestamp: '2024-01-01T00:00:00Z',
+      };
+      const error = new ApiError('Not found', 'NOT_FOUND', context);
+      expect(error.getDeveloperMessage()).toBe('[NOT_FOUND] Not found GET /api/users status:404');
+    });
+
+    it('should include retry count when available', () => {
+      const context: ApiErrorContext = {
+        endpoint: '/api/users',
+        method: 'GET',
+        retryCount: 3,
+        timestamp: '2024-01-01T00:00:00Z',
+      };
+      const error = new ApiError('Failed', 'NETWORK_ERROR', context);
+      expect(error.getDeveloperMessage()).toBe('[NETWORK_ERROR] Failed GET /api/users retry:3');
+    });
+
+    it('should include all context fields when available', () => {
+      const context: ApiErrorContext = {
+        endpoint: '/api/users',
+        method: 'POST',
+        statusCode: 500,
+        retryCount: 2,
+        timestamp: '2024-01-01T00:00:00Z',
+      };
+      const error = new ApiError('Server error', 'SERVER_ERROR', context);
+      expect(error.getDeveloperMessage()).toBe('[SERVER_ERROR] Server error POST /api/users status:500 retry:2');
+    });
+  });
+
+  describe('isRetryable', () => {
+    it('should return true for retryable error types', () => {
+      const retryableTypes = ['NETWORK_ERROR', 'SERVER_ERROR', 'RATE_LIMIT_ERROR', 'TIMEOUT_ERROR'];
+      
+      retryableTypes.forEach(type => {
+        const error = new ApiError('Test', type as ApiErrorType, { timestamp: '2024-01-01T00:00:00Z' });
+        expect(error.isRetryable()).toBe(true);
+      });
+    });
+
+    it('should return false for non-retryable error types', () => {
+      const nonRetryableTypes = ['AUTH_ERROR', 'VALIDATION_ERROR', 'NOT_FOUND', 'CANCELED_ERROR', 'UNKNOWN_ERROR'];
+      
+      nonRetryableTypes.forEach(type => {
+        const error = new ApiError('Test', type as ApiErrorType, { timestamp: '2024-01-01T00:00:00Z' });
+        expect(error.isRetryable()).toBe(false);
+      });
+    });
+  });
+
+  describe('isConnectivityIssue', () => {
+    it('should return true for NETWORK_ERROR', () => {
+      const error = new ApiError('Network', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.isConnectivityIssue()).toBe(true);
+    });
+
+    it('should return true for TIMEOUT_ERROR', () => {
+      const error = new ApiError('Timeout', 'TIMEOUT_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.isConnectivityIssue()).toBe(true);
+    });
+
+    it('should return false for other error types', () => {
+      const otherTypes = ['AUTH_ERROR', 'VALIDATION_ERROR', 'NOT_FOUND', 'SERVER_ERROR', 'RATE_LIMIT_ERROR', 'CANCELED_ERROR', 'UNKNOWN_ERROR'];
+      
+      otherTypes.forEach(type => {
+        const error = new ApiError('Test', type as ApiErrorType, { timestamp: '2024-01-01T00:00:00Z' });
+        expect(error.isConnectivityIssue()).toBe(false);
+      });
+    });
+  });
+
+  describe('getSeverity', () => {
+    it('should return "warn" for AUTH_ERROR', () => {
+      const error = new ApiError('Auth', 'AUTH_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getSeverity()).toBe('warn');
+    });
+
+    it('should return "warn" for VALIDATION_ERROR', () => {
+      const error = new ApiError('Validation', 'VALIDATION_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getSeverity()).toBe('warn');
+    });
+
+    it('should return "warn" for NOT_FOUND', () => {
+      const error = new ApiError('Not found', 'NOT_FOUND', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getSeverity()).toBe('warn');
+    });
+
+    it('should return "info" for RATE_LIMIT_ERROR', () => {
+      const error = new ApiError('Rate limited', 'RATE_LIMIT_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getSeverity()).toBe('info');
+    });
+
+    it('should return "info" for CANCELED_ERROR', () => {
+      const error = new ApiError('Canceled', 'CANCELED_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(error.getSeverity()).toBe('info');
+    });
+
+    it('should return "error" for other error types', () => {
+      const errorTypes = ['NETWORK_ERROR', 'SERVER_ERROR', 'TIMEOUT_ERROR', 'UNKNOWN_ERROR'];
+      
+      errorTypes.forEach(type => {
+        const error = new ApiError('Test', type as ApiErrorType, { timestamp: '2024-01-01T00:00:00Z' });
+        expect(error.getSeverity()).toBe('error');
+      });
+    });
+  });
+});
+
+describe('Type guards', () => {
+  describe('isApiError', () => {
+    it('should return true for ApiError instances', () => {
+      const error = new ApiError('Test', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isApiError(error)).toBe(true);
+    });
+
+    it('should return false for non-ApiError instances', () => {
+      expect(isApiError(new Error('Test'))).toBe(false);
+      expect(isApiError('string')).toBe(false);
+      expect(isApiError(null)).toBe(false);
+      expect(isApiError(undefined)).toBe(false);
+      expect(isApiError({})).toBe(false);
+    });
+  });
+
+  describe('isNetworkError', () => {
+    it('should return true for NETWORK_ERROR ApiError', () => {
+      const error = new ApiError('Network', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isNetworkError(error)).toBe(true);
+    });
+
+    it('should return false for other error types', () => {
+      const error = new ApiError('Auth', 'AUTH_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isNetworkError(error)).toBe(false);
+    });
+
+    it('should return false for non-ApiError', () => {
+      expect(isNetworkError(new Error('Test'))).toBe(false);
+    });
+  });
+
+  describe('isAuthError', () => {
+    it('should return true for AUTH_ERROR ApiError', () => {
+      const error = new ApiError('Auth', 'AUTH_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isAuthError(error)).toBe(true);
+    });
+
+    it('should return false for other error types', () => {
+      const error = new ApiError('Network', 'NETWORK_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isAuthError(error)).toBe(false);
+    });
+
+    it('should return false for non-ApiError', () => {
+      expect(isAuthError(new Error('Test'))).toBe(false);
+    });
+  });
+
+  describe('isRetryableError', () => {
+    it('should return true for retryable ApiError', () => {
+      const error = new ApiError('Server', 'SERVER_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isRetryableError(error)).toBe(true);
+    });
+
+    it('should return false for non-retryable ApiError', () => {
+      const error = new ApiError('Auth', 'AUTH_ERROR', { timestamp: '2024-01-01T00:00:00Z' });
+      expect(isRetryableError(error)).toBe(false);
+    });
+
+    it('should return false for non-ApiError', () => {
+      expect(isRetryableError(new Error('Test'))).toBe(false);
+    });
+  });
+});

apps/website/lib/gateways/api/base/ApiError.ts

@@ -0,0 +1,154 @@
+/**
+ * Enhanced API Error with detailed classification and context
+ */
+
+export type ApiErrorType = 
+  | 'NETWORK_ERROR'          // Connection failed, timeout, CORS
+  | 'AUTH_ERROR'             // 401, 403 - Authentication/Authorization issues
+  | 'VALIDATION_ERROR'       // 400 - Bad request, invalid data
+  | 'NOT_FOUND'              // 404 - Resource not found
+  | 'SERVER_ERROR'           // 500, 502, 503 - Server-side issues
+  | 'RATE_LIMIT_ERROR'       // 429 - Too many requests
+  | 'CANCELED_ERROR'         // Request was canceled
+  | 'TIMEOUT_ERROR'          // Request timeout
+  | 'UNKNOWN_ERROR';         // Everything else
+
+export interface ApiErrorContext {
+  endpoint?: string;
+  method?: string;
+  requestBody?: unknown;
+  timestamp: string;
+  statusCode?: number;
+  responseText?: string;
+  retryCount?: number;
+  wasRetry?: boolean;
+  troubleshooting?: string;
+  source?: string;
+  componentStack?: string;
+  isRetryable?: boolean;
+  isConnectivity?: boolean;
+  developerHint?: string;
+}
+
+export class ApiError extends Error {
+  public readonly type: ApiErrorType;
+  public readonly context: ApiErrorContext;
+  public readonly originalError?: Error;
+
+  constructor(
+    message: string,
+    type: ApiErrorType,
+    context: ApiErrorContext,
+    originalError?: Error
+  ) {
+    super(message);
+    this.name = 'ApiError';
+    this.type = type;
+    this.context = context;
+    this.originalError = originalError;
+
+    // Maintains proper stack trace for where our error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ApiError);
+    }
+  }
+
+  /**
+   * User-friendly message for production environments
+   */
+  getUserMessage(): string {
+    switch (this.type) {
+      case 'NETWORK_ERROR':
+        return 'Unable to connect to the server. Please check your internet connection.';
+      case 'AUTH_ERROR':
+        return 'Authentication required. Please log in again.';
+      case 'VALIDATION_ERROR':
+        return 'The data you provided is invalid. Please check your input.';
+      case 'NOT_FOUND':
+        return 'The requested resource was not found.';
+      case 'SERVER_ERROR':
+        return 'Server is experiencing issues. Please try again later.';
+      case 'RATE_LIMIT_ERROR':
+        return 'Too many requests. Please wait a moment and try again.';
+      case 'TIMEOUT_ERROR':
+        return 'Request timed out. Please try again.';
+      case 'CANCELED_ERROR':
+        return 'Request was canceled.';
+      default:
+        return 'An unexpected error occurred. Please try again.';
+    }
+  }
+
+  /**
+   * Developer-friendly message with full context
+   */
+  getDeveloperMessage(): string {
+    const base = `[${this.type}] ${this.message}`;
+    const ctx = [
+      this.context.method,
+      this.context.endpoint,
+      this.context.statusCode ? `status:${this.context.statusCode}` : null,
+      this.context.retryCount ? `retry:${this.context.retryCount}` : null,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return ctx ? `${base} ${ctx}` : base;
+  }
+
+  /**
+   * Check if this error is retryable
+   */
+  isRetryable(): boolean {
+    const retryableTypes: ApiErrorType[] = [
+      'NETWORK_ERROR',
+      'SERVER_ERROR',
+      'RATE_LIMIT_ERROR',
+      'TIMEOUT_ERROR',
+    ];
+    return retryableTypes.includes(this.type);
+  }
+
+  /**
+   * Check if this error indicates connectivity issues
+   */
+  isConnectivityIssue(): boolean {
+    return this.type === 'NETWORK_ERROR' || this.type === 'TIMEOUT_ERROR';
+  }
+
+  /**
+   * Get error severity for logging
+   */
+  getSeverity(): 'error' | 'warn' | 'info' {
+    switch (this.type) {
+      case 'AUTH_ERROR':
+      case 'VALIDATION_ERROR':
+      case 'NOT_FOUND':
+        return 'warn';
+      case 'RATE_LIMIT_ERROR':
+      case 'CANCELED_ERROR':
+        return 'info';
+      default:
+        return 'error';
+    }
+  }
+}
+
+/**
+ * Type guards for error classification
+ */
+export function isApiError(error: unknown): error is ApiError {
+  return error instanceof ApiError;
+}
+
+export function isNetworkError(error: unknown): boolean {
+  return isApiError(error) && error.type === 'NETWORK_ERROR';
+}
+
+export function isAuthError(error: unknown): boolean {
+  return isApiError(error) && error.type === 'AUTH_ERROR';
+}
+
+export function isRetryableError(error: unknown): boolean {
+  return isApiError(error) && error.isRetryable();
+}

apps/website/lib/gateways/api/base/BaseApiClient.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { BaseApiClient } from './BaseApiClient';
+
+describe('BaseApiClient', () => {
+  it('should be defined', () => {
+    expect(BaseApiClient).toBeDefined();
+  });
+});

apps/website/lib/gateways/api/base/BaseApiClient.ts

@@ -0,0 +1,475 @@
+/**
+ * Base API Client for HTTP operations
+ *
+ * Provides generic HTTP methods with common request/response handling,
+ * error handling, authentication, retry logic, and circuit breaker.
+ */
+
+import { Logger } from '../../interfaces/Logger';
+import { ErrorReporter } from '../../interfaces/ErrorReporter';
+import { ApiError, ApiErrorType } from './ApiError';
+import { RetryHandler, CircuitBreakerRegistry, DEFAULT_RETRY_CONFIG } from './RetryHandler';
+import { ApiConnectionMonitor } from './ApiConnectionMonitor';
+import { getGlobalApiLogger } from '@/lib/infrastructure/ApiRequestLogger';
+
+export interface BaseApiClientOptions {
+  timeout?: number;
+  retry?: boolean;
+  retryConfig?: typeof DEFAULT_RETRY_CONFIG;
+  allowUnauthenticated?: boolean;
+}
+
+export class BaseApiClient {
+  protected baseUrl: string;
+  private errorReporter: ErrorReporter;
+  private logger: Logger;
+  private retryHandler: RetryHandler;
+  private circuitBreakerRegistry: CircuitBreakerRegistry;
+  private connectionMonitor: ApiConnectionMonitor;
+  private defaultOptions: BaseApiClientOptions;
+
+  constructor(
+    baseUrl: string,
+    errorReporter: ErrorReporter,
+    logger: Logger,
+    options: BaseApiClientOptions = {}
+  ) {
+    this.baseUrl = baseUrl;
+    this.errorReporter = errorReporter;
+    this.logger = logger;
+    this.retryHandler = new RetryHandler(options.retryConfig || DEFAULT_RETRY_CONFIG);
+    this.circuitBreakerRegistry = CircuitBreakerRegistry.getInstance();
+    this.connectionMonitor = ApiConnectionMonitor.getInstance();
+    this.defaultOptions = {
+      timeout: options.timeout || 30000,
+      retry: options.retry !== false,
+      retryConfig: options.retryConfig || DEFAULT_RETRY_CONFIG,
+    };
+
+    // Start monitoring connection health
+    // this.connectionMonitor.startMonitoring();
+  }
+
+  /**
+   * Classify HTTP status code into error type
+   */
+  private classifyError(status: number): ApiErrorType {
+    if (status >= 500) return 'SERVER_ERROR';
+    if (status === 429) return 'RATE_LIMIT_ERROR';
+    if (status === 401 || status === 403) return 'AUTH_ERROR';
+    if (status === 400) return 'VALIDATION_ERROR';
+    if (status === 404) return 'NOT_FOUND';
+    return 'UNKNOWN_ERROR';
+  }
+
+  /**
+   * Create an ApiError from fetch response
+   */
+  private async createApiError(
+    response: Response,
+    method: string,
+    path: string,
+    retryCount: number = 0
+  ): Promise<ApiError> {
+    const status = response.status;
+    const errorType = this.classifyError(status);
+    
+    let message = response.statusText;
+    let responseText = '';
+
+    try {
+      responseText = await response.text();
+      if (responseText) {
+        const errorData = JSON.parse(responseText);
+        if (errorData.message) {
+          message = errorData.message;
+        }
+      }
+    } catch {
+      // Keep default message
+    }
+
+    return new ApiError(
+      message,
+      errorType,
+      {
+        endpoint: path,
+        method,
+        statusCode: status,
+        responseText,
+        timestamp: new Date().toISOString(),
+        retryCount,
+      }
+    );
+  }
+
+  /**
+   * Create an ApiError from network/timeout errors
+   */
+  private createNetworkError(
+    error: Error,
+    method: string,
+    path: string,
+    retryCount: number = 0
+  ): ApiError {
+    let errorType: ApiErrorType = 'NETWORK_ERROR';
+    let message = error.message;
+
+    // More specific error classification
+    if (error.name === 'AbortError') {
+      errorType = 'CANCELED_ERROR';
+      message = 'Request was canceled';
+    } else if (error.name === 'TypeError' && error.message.includes('fetch')) {
+      errorType = 'NETWORK_ERROR';
+      // Check for CORS specifically
+      if (error.message.includes('Failed to fetch') || error.message.includes('fetch failed')) {
+        message = 'Unable to connect to server. Possible CORS or network issue.';
+      }
+    } else if (error.message.includes('timeout') || error.message.includes('timed out')) {
+      errorType = 'TIMEOUT_ERROR';
+      message = 'Request timed out after 30 seconds';
+    } else if (error.message.includes('Failed to fetch') || error.message.includes('NetworkError')) {
+      errorType = 'NETWORK_ERROR';
+      // This could be CORS, network down, or server not responding
+      message = 'Network error: Unable to reach the API server';
+    }
+
+    return new ApiError(
+      message,
+      errorType,
+      {
+        endpoint: path,
+        method,
+        timestamp: new Date().toISOString(),
+        retryCount,
+        // Add helpful context for developers
+        troubleshooting: this.getTroubleshootingContext(error, path),
+        isRetryable: this.isRetryableError(errorType),
+        isConnectivity: errorType === 'NETWORK_ERROR' || errorType === 'TIMEOUT_ERROR',
+        developerHint: this.getDeveloperHint(error, path, method),
+      },
+      error
+    );
+  }
+
+  /**
+   * Check if error type is retryable
+   */
+  private isRetryableError(errorType: ApiErrorType): boolean {
+    const retryableTypes: ApiErrorType[] = [
+      'NETWORK_ERROR',
+      'SERVER_ERROR',
+      'RATE_LIMIT_ERROR',
+      'TIMEOUT_ERROR',
+    ];
+    return retryableTypes.includes(errorType);
+  }
+
+  /**
+   * Get developer-friendly hint for troubleshooting
+   */
+  private getDeveloperHint(error: Error, _path: string, _method: string): string {
+    if (error.message.includes('fetch failed') || error.message.includes('Failed to fetch')) {
+      return 'Check if API server is running and CORS is configured correctly';
+    }
+    if (error.message.includes('timeout')) {
+      return 'Request timed out - consider increasing timeout or checking network';
+    }
+    if (error.message.includes('ECONNREFUSED')) {
+      return 'Connection refused - verify API server address and port';
+    }
+    return 'Review network connection and API endpoint configuration';
+  }
+
+  /**
+   * Get troubleshooting context for network errors
+   */
+  private getTroubleshootingContext(error: Error, _path: string): string {
+    if (typeof window !== 'undefined') {
+      const baseUrl = this.baseUrl;
+      const currentOrigin = window.location.origin;
+      
+      // Check if it's likely a CORS issue
+      if (baseUrl && !baseUrl.includes(currentOrigin) && error.message.includes('Failed to fetch')) {
+        return 'CORS issue likely. Check API server CORS configuration.';
+      }
+      
+      // Check if API server is same origin
+      if (baseUrl.includes(currentOrigin) || baseUrl.startsWith('/')) {
+        return 'Same-origin request. Check if API server is running.';
+      }
+    }
+    
+    return 'Check network connection and API server status.';
+  }
+
+  protected async request<T>(
+    method: string,
+    path: string,
+    data?: object | FormData,
+    options: BaseApiClientOptions & { allowUnauthenticated?: boolean } = {},
+  ): Promise<T> {
+    const finalOptions = { ...this.defaultOptions, ...options };
+    const endpoint = `${this.baseUrl}${path}`;
+
+    // Check circuit breaker
+    const circuitBreaker = this.circuitBreakerRegistry.getBreaker(path);
+    if (!circuitBreaker.canExecute()) {
+      const error = new ApiError(
+        'Circuit breaker is open - service temporarily unavailable',
+        'SERVER_ERROR',
+        {
+          endpoint: path,
+          method,
+          timestamp: new Date().toISOString(),
+        }
+      );
+      this.handleError(error);
+      throw error;
+    }
+
+    const executeRequest = async (signal: AbortSignal): Promise<T> => {
+      const isFormData = typeof FormData !== 'undefined' && data instanceof FormData;
+      const headers: Record<string, string> = isFormData
+        ? {}
+        : {
+            'Content-Type': 'application/json',
+          };
+
+      // Forward cookies if running on server
+      if (typeof window === 'undefined') {
+        try {
+          const { cookies } = await import('next/headers');
+          const cookieStore = await cookies();
+          const cookieString = cookieStore.toString();
+          if (cookieString) {
+            headers['Cookie'] = cookieString;
+          }
+        } catch (e) {
+          // Not in a request context or next/headers not available
+        }
+      }
+
+      const config: RequestInit = {
+        method,
+        headers,
+        credentials: 'include',
+        signal,
+      };
+
+      if (data) {
+        config.body = isFormData ? data : JSON.stringify(data);
+      }
+
+      const startTime = Date.now();
+      let requestId: string | undefined;
+
+      // Log request start (only in development for maximum transparency)
+      if (process.env.NODE_ENV === 'development') {
+        try {
+          const apiLogger = getGlobalApiLogger();
+          const headerObj: Record<string, string> = {};
+          if (typeof headers === 'object') {
+            Object.entries(headers).forEach(([key, value]) => {
+              headerObj[key] = value;
+            });
+          }
+          requestId = apiLogger.logRequest(
+            endpoint,
+            method,
+            headerObj,
+            data
+          );
+        } catch (e) {
+          // Silent fail - logger might not be initialized
+        }
+      }
+
+      try {
+        const response = await fetch(endpoint, config);
+        const responseTime = Date.now() - startTime;
+
+        // Record success for monitoring
+        this.connectionMonitor.recordSuccess(responseTime);
+
+        if (!response.ok) {
+          if (
+            finalOptions.allowUnauthenticated &&
+            (response.status === 401 || response.status === 403)
+          ) {
+            // For auth probe endpoints, 401/403 is expected
+            return null as T;
+          }
+
+          const error = await this.createApiError(response, method, path);
+          circuitBreaker.recordFailure();
+          this.connectionMonitor.recordFailure(error);
+          this.handleError(error);
+
+          // Log error
+          if (process.env.NODE_ENV === 'development' && requestId) {
+            try {
+              const apiLogger = getGlobalApiLogger();
+              apiLogger.logError(requestId, error, responseTime);
+            } catch (e) {
+              // Silent fail
+            }
+          }
+
+          throw error;
+        }
+
+        // Record successful circuit breaker call
+        circuitBreaker.recordSuccess();
+
+        const text = await response.text();
+        if (!text) {
+          // Log empty response
+          if (process.env.NODE_ENV === 'development' && requestId) {
+            try {
+              const apiLogger = getGlobalApiLogger();
+              apiLogger.logResponse(requestId, response, null, responseTime);
+            } catch (e) {
+              // Silent fail
+            }
+          }
+          return null as T;
+        }
+
+        const parsedData = JSON.parse(text) as T;
+
+        // Log successful response
+        if (process.env.NODE_ENV === 'development' && requestId) {
+          try {
+            const apiLogger = getGlobalApiLogger();
+            apiLogger.logResponse(requestId, response, parsedData, responseTime);
+          } catch (e) {
+            // Silent fail
+          }
+        }
+
+        return parsedData;
+
+      } catch (error) {
+        const responseTime = Date.now() - startTime;
+
+        if (error instanceof ApiError) {
+          throw error;
+        }
+
+        // Convert to ApiError
+        const apiError = this.createNetworkError(error as Error, method, path);
+        
+        circuitBreaker.recordFailure();
+        this.connectionMonitor.recordFailure(apiError);
+        this.handleError(apiError);
+
+        // Log network error
+        if (process.env.NODE_ENV === 'development' && requestId) {
+          try {
+            const apiLogger = getGlobalApiLogger();
+            apiLogger.logError(requestId, apiError, responseTime);
+          } catch (e) {
+            // Silent fail
+          }
+        }
+        
+        throw apiError;
+      }
+    };
+
+    // Wrap with retry logic if enabled
+    if (finalOptions.retry) {
+      try {
+        return await this.retryHandler.execute(executeRequest);
+      } catch (error) {
+        // If retry exhausted, throw the final error
+        throw error;
+      }
+    } else {
+      // No retry, just execute with timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), finalOptions.timeout);
+
+      try {
+        return await executeRequest(controller.signal);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+
+  /**
+   * Handle errors - log and report
+   */
+  private handleError(error: ApiError): void {
+    const severity = error.getSeverity();
+    const message = error.getDeveloperMessage();
+
+    // Enhanced context for better debugging
+    const enhancedContext = {
+      ...error.context,
+      severity,
+      isRetryable: error.isRetryable(),
+      isConnectivity: error.isConnectivityIssue(),
+    };
+
+    // Use appropriate log level
+    if (severity === 'error') {
+      this.logger.error(message, error, enhancedContext);
+    } else if (severity === 'warn') {
+      this.logger.warn(message, enhancedContext);
+    } else {
+      this.logger.info(message, enhancedContext);
+    }
+
+    // Report to error tracking
+    this.errorReporter.report(error, enhancedContext);
+  }
+
+  protected get<T>(path: string, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('GET', path, undefined, options);
+  }
+
+  protected post<T>(path: string, data: object, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('POST', path, data, options);
+  }
+
+  protected put<T>(path: string, data: object, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('PUT', path, data, options);
+  }
+
+  protected delete<T>(path: string, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('DELETE', path, undefined, options);
+  }
+
+  protected patch<T>(path: string, data: object, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('PATCH', path, data, options);
+  }
+
+  /**
+   * Get current connection health status
+   */
+  getConnectionStatus() {
+    return {
+      status: this.connectionMonitor.getStatus(),
+      health: this.connectionMonitor.getHealth(),
+      isAvailable: this.connectionMonitor.isAvailable(),
+      reliability: this.connectionMonitor.getReliability(),
+    };
+  }
+
+  /**
+   * Force a health check
+   */
+  async checkHealth() {
+    return this.connectionMonitor.performHealthCheck();
+  }
+
+  /**
+   * Get circuit breaker status for debugging
+   */
+  getCircuitBreakerStatus() {
+    return this.circuitBreakerRegistry.getStatus();
+  }
+}

apps/website/lib/gateways/api/base/GracefulDegradation.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import { GracefulService, responseCache, withGracefulDegradation } from './GracefulDegradation';
+
+describe('GracefulDegradation', () => {
+  it('should export graceful degradation utilities', () => {
+    expect(withGracefulDegradation).toBeDefined();
+    expect(responseCache).toBeDefined();
+    expect(GracefulService).toBeDefined();
+  });
+});

apps/website/lib/gateways/api/base/GracefulDegradation.ts

@@ -0,0 +1,321 @@
+/**
+ * Graceful degradation utilities for when API is unavailable
+ */
+
+import { ApiConnectionMonitor } from './ApiConnectionMonitor';
+import { ApiError } from './ApiError';
+
+export interface DegradationOptions<T> {
+  /**
+   * Fallback data to return when API is unavailable
+   */
+  fallback?: T;
+  
+  /**
+   * Whether to throw error or return fallback
+   */
+  throwOnError?: boolean;
+  
+  /**
+   * Maximum time to wait for API response
+   */
+  timeout?: number;
+  
+  /**
+   * Whether to use cached data if available
+   */
+  useCache?: boolean;
+}
+
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: Date;
+  expiry: Date;
+}
+
+/**
+ * Simple in-memory cache for API responses
+ */
+class ResponseCache {
+  private cache = new Map<string, CacheEntry<unknown>>();
+
+  /**
+   * Get cached data if not expired
+   */
+  get<T>(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (new globalThis.Date() > entry.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data as T;
+  }
+
+  /**
+   * Set cached data with expiry
+   */
+  set<T>(key: string, data: T, ttlMs: number = 300000): void {
+    const now = new globalThis.Date();
+    const expiry = new globalThis.Date(now.getTime() + ttlMs);
+    
+    this.cache.set(key, {
+      data,
+      timestamp: now,
+      expiry,
+    });
+  }
+
+  /**
+   * Clear all cached data
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    return {
+      size: this.cache.size,
+      entries: Array.from(this.cache.entries()).map(([key, entry]) => ({
+        key,
+        timestamp: entry.timestamp,
+        expiry: entry.expiry,
+      })),
+    };
+  }
+}
+
+/**
+ * Global cache instance
+ */
+export const responseCache = new ResponseCache();
+
+/**
+ * Execute a function with graceful degradation
+ */
+export async function withGracefulDegradation<T>(
+  fn: () => Promise<T>,
+  options: DegradationOptions<T> = {}
+): Promise<T | undefined> {
+  const {
+    fallback,
+    throwOnError = false,
+    timeout = 10000,
+    useCache = true,
+  } = options;
+
+  const monitor = ApiConnectionMonitor.getInstance();
+
+  // Check if API is available
+  if (!monitor.isAvailable()) {
+    // Try cache first
+    if (useCache && options.fallback) {
+      const cacheKey = `graceful:${fn.toString()}`;
+      const cached = responseCache.get<T>(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    // Return fallback
+    if (fallback !== undefined) {
+      return fallback;
+    }
+
+    // Throw error if no fallback
+    if (throwOnError) {
+      throw new ApiError(
+        'API unavailable and no fallback provided',
+        'NETWORK_ERROR',
+        {
+          timestamp: new globalThis.Date().toISOString(),
+        }
+      );
+    }
+
+    // Return undefined (caller must handle)
+    return undefined;
+  }
+
+  // API is available, try to execute
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const result = await Promise.race([
+      fn(),
+      new Promise<never>((_, reject) => {
+        controller.signal.addEventListener('abort', () => {
+          reject(new Error('Request timeout'));
+        });
+      }),
+    ]);
+
+    clearTimeout(timeoutId);
+
+    // Cache the result if enabled
+    if (useCache && result !== null && result !== undefined) {
+      const cacheKey = `graceful:${fn.toString()}`;
+      responseCache.set(cacheKey, result);
+    }
+
+    return result;
+
+  } catch (error) {
+    // Record failure in monitor
+    if (error instanceof ApiError) {
+      monitor.recordFailure(error);
+    } else {
+      monitor.recordFailure(error as Error);
+    }
+
+    // Try cache as fallback
+    if (useCache && options.fallback) {
+      const cacheKey = `graceful:${fn.toString()}`;
+      const cached = responseCache.get<T>(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    // Return fallback if provided
+    if (fallback !== undefined) {
+      return fallback;
+    }
+
+    // Re-throw or return undefined
+    if (throwOnError) {
+      throw error;
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Service wrapper for graceful degradation
+ */
+export class GracefulService<T> {
+  private monitor: ApiConnectionMonitor;
+  private cacheKey: string;
+
+  constructor(
+    private serviceName: string,
+    private getData: () => Promise<T>,
+    private defaultFallback: T
+  ) {
+    this.monitor = ApiConnectionMonitor.getInstance();
+    this.cacheKey = `service:${serviceName}`;
+  }
+
+  /**
+   * Get data with graceful degradation
+   */
+  async get(options: Partial<DegradationOptions<T>> = {}): Promise<T> {
+    const result = await withGracefulDegradation(this.getData, {
+      fallback: this.defaultFallback,
+      throwOnError: false,
+      useCache: true,
+      ...options,
+    });
+
+    return result ?? this.defaultFallback;
+  }
+
+  /**
+   * Force refresh data
+   */
+  async refresh(): Promise<T> {
+    responseCache.clear(); // Clear cache for this service
+    return this.get({ useCache: false });
+  }
+
+  /**
+   * Get service health status
+   */
+  getStatus() {
+    const health = this.monitor.getHealth();
+    const isAvailable = this.monitor.isAvailable();
+    
+    return {
+      serviceName: this.serviceName,
+      available: isAvailable,
+      reliability: health.totalRequests > 0 
+        ? (health.successfulRequests / health.totalRequests) * 100 
+        : 100,
+      lastCheck: health.lastCheck,
+    };
+  }
+}
+
+/**
+ * Offline mode detection
+ */
+export class OfflineDetector {
+  private static instance: OfflineDetector;
+  private isOffline = false;
+  private listeners: Array<(isOffline: boolean) => void> = [];
+
+  private constructor() {
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', () => this.setOffline(false));
+      window.addEventListener('offline', () => this.setOffline(true));
+      
+      // Initial check
+      this.isOffline = !navigator.onLine;
+    }
+  }
+
+  static getInstance(): OfflineDetector {
+    if (!OfflineDetector.instance) {
+      OfflineDetector.instance = new OfflineDetector();
+    }
+    return OfflineDetector.instance;
+  }
+
+  private setOffline(offline: boolean): void {
+    if (this.isOffline !== offline) {
+      this.isOffline = offline;
+      this.listeners.forEach(listener => listener(offline));
+    }
+  }
+
+  /**
+   * Check if browser is offline
+   */
+  isBrowserOffline(): boolean {
+    return this.isOffline;
+  }
+
+  /**
+   * Add listener for offline status changes
+   */
+  onStatusChange(callback: (isOffline: boolean) => void): void {
+    this.listeners.push(callback);
+  }
+
+  /**
+   * Remove listener
+   */
+  removeListener(callback: (isOffline: boolean) => void): void {
+    this.listeners = this.listeners.filter(cb => cb !== callback);
+  }
+}
+
+/**
+ * Hook for offline detection
+ */
+export function useOfflineStatus() {
+  if (typeof window === 'undefined') {
+    return false; // Server-side
+  }
+
+  // This would need to be used in a React component context
+  // For now, provide a simple check function
+  return OfflineDetector.getInstance().isBrowserOffline();
+}

apps/website/lib/gateways/api/base/RetryHandler.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { RetryHandler, CircuitBreaker, CircuitBreakerRegistry, DEFAULT_RETRY_CONFIG } from './RetryHandler';
+
+describe('RetryHandler', () => {
+  let handler: RetryHandler;
+  const fastConfig = {
+    ...DEFAULT_RETRY_CONFIG,
+    baseDelay: 1,
+    maxDelay: 1,
+    backoffMultiplier: 1,
+  };
+
+  beforeEach(() => {
+    handler = new RetryHandler(fastConfig);
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('execute', () => {
+    it('should execute function successfully without retry', async () => {
+      const fn = vi.fn().mockResolvedValue('success');
+      const result = await handler.execute(fn);
+      
+      expect(result).toBe('success');
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it('should retry on failure and eventually succeed', async () => {
+      const fn = vi.fn()
+        .mockRejectedValueOnce(new Error('First attempt'))
+        .mockResolvedValueOnce('success');
+      
+      const result = await handler.execute(fn);
+      
+      expect(result).toBe('success');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should exhaust retries and throw final error', async () => {
+      const fn = vi.fn().mockRejectedValue(new Error('Always fails'));
+      
+      await expect(handler.execute(fn)).rejects.toThrow('Always fails');
+      expect(fn).toHaveBeenCalledTimes(fastConfig.maxRetries + 1);
+    });
+
+    it('should respect custom retry config', async () => {
+      const customConfig = { ...fastConfig, maxRetries: 2 };
+      const customHandler = new RetryHandler(customConfig);
+      const fn = vi.fn().mockRejectedValue(new Error('Fail'));
+      
+      await expect(customHandler.execute(fn)).rejects.toThrow('Fail');
+      expect(fn).toHaveBeenCalledTimes(3); // 2 retries + 1 initial
+    });
+  });
+});
+
+describe('CircuitBreaker', () => {
+  let breaker: CircuitBreaker;
+
+  beforeEach(() => {
+    breaker = new CircuitBreaker({ failureThreshold: 3, successThreshold: 1, timeout: 1000 });
+  });
+
+  describe('canExecute', () => {
+    it('should allow execution when closed', () => {
+      expect(breaker.canExecute()).toBe(true);
+    });
+
+    it('should prevent execution when open', () => {
+      breaker.recordFailure();
+      breaker.recordFailure();
+      breaker.recordFailure();
+      
+      expect(breaker.canExecute()).toBe(false);
+    });
+  });
+
+  describe('recordSuccess', () => {
+    it('should reset failure count on success', () => {
+      breaker.recordFailure();
+      breaker.recordFailure();
+      breaker.recordSuccess();
+      
+      // Should be closed again
+      expect(breaker.canExecute()).toBe(true);
+    });
+  });
+
+  describe('recordFailure', () => {
+    it('should increment failure count', () => {
+      breaker.recordFailure();
+      expect(breaker.canExecute()).toBe(true);
+      
+      breaker.recordFailure();
+      expect(breaker.canExecute()).toBe(true);
+      
+      breaker.recordFailure();
+      expect(breaker.canExecute()).toBe(false);
+    });
+  });
+});
+
+describe('CircuitBreakerRegistry', () => {
+  it('should return singleton instance', () => {
+    const registry1 = CircuitBreakerRegistry.getInstance();
+    const registry2 = CircuitBreakerRegistry.getInstance();
+    expect(registry1).toBe(registry2);
+  });
+
+  it('should return same breaker for same path', () => {
+    const registry = CircuitBreakerRegistry.getInstance();
+    const breaker1 = registry.getBreaker('/api/test');
+    const breaker2 = registry.getBreaker('/api/test');
+    expect(breaker1).toBe(breaker2);
+  });
+
+  it('should return different breakers for different paths', () => {
+    const registry = CircuitBreakerRegistry.getInstance();
+    const breaker1 = registry.getBreaker('/api/test1');
+    const breaker2 = registry.getBreaker('/api/test2');
+    expect(breaker1).not.toBe(breaker2);
+  });
+});

apps/website/lib/gateways/api/base/RetryHandler.ts

@@ -0,0 +1,275 @@
+/**
+ * Retry logic and circuit breaker for API requests
+ */
+
+import { ApiError } from './ApiError';
+
+export interface RetryConfig {
+  maxRetries: number;
+  baseDelay: number; // milliseconds
+  maxDelay: number; // milliseconds
+  backoffMultiplier: number;
+  timeout: number; // milliseconds
+}
+
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxRetries: 1,
+  baseDelay: 1000,
+  maxDelay: 10000,
+  backoffMultiplier: 2,
+  timeout: 30000,
+};
+
+export interface CircuitBreakerConfig {
+  failureThreshold: number;
+  successThreshold: number;
+  timeout: number; // milliseconds before trying again
+}
+
+export const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 5,
+  successThreshold: 3,
+  timeout: 60000, // 1 minute
+};
+
+export class CircuitBreaker {
+  private failures = 0;
+  private successes = 0;
+  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';
+  private lastFailureTime: number | null = null;
+  private readonly config: CircuitBreakerConfig;
+
+  constructor(config: CircuitBreakerConfig = DEFAULT_CIRCUIT_BREAKER_CONFIG) {
+    this.config = config;
+  }
+
+  /**
+   * Check if request should proceed
+   */
+  canExecute(): boolean {
+    if (this.state === 'CLOSED') {
+      return true;
+    }
+
+    if (this.state === 'OPEN') {
+      const now = Date.now();
+      if (this.lastFailureTime && now - this.lastFailureTime > this.config.timeout) {
+        this.state = 'HALF_OPEN';
+        return true;
+      }
+      return false;
+    }
+
+    // HALF_OPEN - allow one request to test if service recovered
+    return true;
+  }
+
+  /**
+   * Record a successful request
+   */
+  recordSuccess(): void {
+    if (this.state === 'HALF_OPEN') {
+      this.successes++;
+      if (this.successes >= this.config.successThreshold) {
+        this.reset();
+      }
+    } else if (this.state === 'CLOSED') {
+      // Keep failures in check
+      this.failures = Math.max(0, this.failures - 1);
+    }
+  }
+
+  /**
+   * Record a failed request
+   */
+  recordFailure(): void {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+
+    if (this.state === 'HALF_OPEN') {
+      this.state = 'OPEN';
+      this.successes = 0;
+    } else if (this.state === 'CLOSED' && this.failures >= this.config.failureThreshold) {
+      this.state = 'OPEN';
+    }
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): string {
+    return this.state;
+  }
+
+  /**
+   * Get failure count
+   */
+  getFailures(): number {
+    return this.failures;
+  }
+
+  /**
+   * Reset the circuit breaker
+   */
+  reset(): void {
+    this.failures = 0;
+    this.successes = 0;
+    this.state = 'CLOSED';
+    this.lastFailureTime = null;
+  }
+}
+
+export class RetryHandler {
+  private config: RetryConfig;
+  private abortController: AbortController | null = null;
+
+  constructor(config: RetryConfig = DEFAULT_RETRY_CONFIG) {
+    this.config = config;
+  }
+
+  /**
+   * Execute a function with retry logic
+   */
+  async execute<T>(
+    fn: (signal: AbortSignal) => Promise<T>,
+    isRetryable?: (error: ApiError) => boolean
+  ): Promise<T> {
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+
+    let lastError: Error | null = null;
+    
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        // Check if already aborted
+        if (signal.aborted) {
+          throw new Error('Request aborted');
+        }
+
+        const result = await fn(signal);
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+
+        // Check if we should abort
+        if (signal.aborted) {
+          throw error;
+        }
+
+        // Check if this is the last attempt
+        if (attempt === this.config.maxRetries) {
+          break;
+        }
+
+        // Check if error is retryable
+        if (error instanceof ApiError) {
+          if (!error.isRetryable()) {
+            throw error;
+          }
+          if (isRetryable && !isRetryable(error)) {
+            throw error;
+          }
+        }
+
+        // Calculate delay with exponential backoff
+        const delay = this.calculateDelay(attempt);
+        
+        // Wait before retrying
+        await this.sleep(delay, signal);
+      }
+    }
+
+    // All retries exhausted
+    throw lastError;
+  }
+
+  /**
+   * Cancel the current request
+   */
+  abort(): void {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+
+  /**
+   * Calculate delay for retry attempt
+   */
+  private calculateDelay(attempt: number): number {
+    const delay = Math.min(
+      this.config.baseDelay * Math.pow(this.config.backoffMultiplier, attempt),
+      this.config.maxDelay
+    );
+    // Add jitter to prevent thundering herd
+    const jitter = Math.random() * 0.3 * delay;
+    return delay + jitter;
+  }
+
+  /**
+   * Sleep with abort support
+   */
+  private sleep(ms: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        signal.removeEventListener('abort', abortHandler);
+        resolve();
+      }, ms);
+
+      const abortHandler = () => {
+        clearTimeout(timeout);
+        signal.removeEventListener('abort', abortHandler);
+        reject(new Error('Request aborted during retry delay'));
+      };
+
+      signal.addEventListener('abort', abortHandler, { once: true });
+    });
+  }
+}
+
+/**
+ * Global circuit breaker registry for different API endpoints
+ */
+export class CircuitBreakerRegistry {
+  private static instance: CircuitBreakerRegistry;
+  private breakers: Map<string, CircuitBreaker> = new Map();
+
+  private constructor() {}
+
+  static getInstance(): CircuitBreakerRegistry {
+    if (!CircuitBreakerRegistry.instance) {
+      CircuitBreakerRegistry.instance = new CircuitBreakerRegistry();
+    }
+    return CircuitBreakerRegistry.instance;
+  }
+
+  /**
+   * Get or create circuit breaker for a specific endpoint
+   */
+  getBreaker(endpoint: string, config?: CircuitBreakerConfig): CircuitBreaker {
+    if (!this.breakers.has(endpoint)) {
+      this.breakers.set(endpoint, new CircuitBreaker(config));
+    }
+    return this.breakers.get(endpoint)!;
+  }
+
+  /**
+   * Reset all circuit breakers
+   */
+  resetAll(): void {
+    this.breakers.forEach(breaker => breaker.reset());
+  }
+
+  /**
+   * Get status of all circuit breakers
+   */
+  getStatus(): Record<string, { state: string; failures: number }> {
+    const status: Record<string, { state: string; failures: number }> = {};
+    this.breakers.forEach((breaker, endpoint) => {
+      status[endpoint] = {
+        state: breaker.getState(),
+        failures: breaker.getFailures(),
+      };
+    });
+    return status;
+  }
+}