dev setup

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

@@ -0,0 +1,351 @@
+/**
+ * API Connection Status Monitor and Health Checks
+ */
+
+import { EventEmitter } from 'events';
+import { ApiError } from './ApiError';
+import { CircuitBreakerRegistry } from './RetryHandler';
+
+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 = 30000; // 30 seconds
+  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/api/base/ApiError.ts

@@ -0,0 +1,147 @@
+/**
+ * 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;
+}
+
+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 `${base} ${ctx ? `(${ctx})` : ''}`;
+  }
+
+  /**
+   * 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/api/base/BaseApiClient.ts

@@ -2,99 +2,353 @@
  * Base API Client for HTTP operations
  *
  * Provides generic HTTP methods with common request/response handling,
- * error handling, and authentication.
+ * 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';
+
+export interface BaseApiClientOptions {
+  timeout?: number;
+  retry?: boolean;
+  retryConfig?: typeof DEFAULT_RETRY_CONFIG;
+}
 
 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) {
+  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),
+      },
+      error
+    );
+  }
+
+  /**
+   * 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?: { allowUnauthenticated?: boolean },
+    options: BaseApiClientOptions & { allowUnauthenticated?: boolean } = {},
   ): Promise<T> {
-    this.logger.info(`${method} ${path}`);
+    const finalOptions = { ...this.defaultOptions, ...options };
+    const endpoint = `${this.baseUrl}${path}`;
 
-    const isFormData = typeof FormData !== 'undefined' && data instanceof FormData;
-
-    const headers: HeadersInit = isFormData
-      ? {}
-      : {
-          'Content-Type': 'application/json',
-        };
-
-    const config: RequestInit = {
-      method,
-      headers,
-      credentials: 'include', // Include cookies for auth
-    };
-
-    if (data) {
-      config.body = isFormData ? data : JSON.stringify(data);
-    }
-
-    const response = await fetch(`${this.baseUrl}${path}`, config);
-
-    if (!response.ok) {
-      if (
-        options?.allowUnauthenticated &&
-        (response.status === 401 || response.status === 403)
-      ) {
-        // For "auth probe" endpoints (e.g. session/policy checks), 401/403 is an expected state
-        // in public context and should not be logged as an application error.
-        return null as T;
-      }
-
-      let errorData: { message?: string } = { message: response.statusText };
-      try {
-        errorData = await response.json();
-      } catch {
-        // Keep default error message
-      }
-      const error = new Error(
-        errorData.message || `API request failed with status ${response.status}`,
-      ) as Error & { status?: number };
-      error.status = response.status;
-      this.errorReporter.report(error);
+    // 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 text = await response.text();
-    if (!text) {
-      return null as T;
+    const executeRequest = async (signal: AbortSignal): Promise<T> => {
+      const isFormData = typeof FormData !== 'undefined' && data instanceof FormData;
+      const headers: HeadersInit = isFormData
+        ? {}
+        : {
+            'Content-Type': 'application/json',
+          };
+
+      const config: RequestInit = {
+        method,
+        headers,
+        credentials: 'include',
+        signal,
+      };
+
+      if (data) {
+        config.body = isFormData ? data : JSON.stringify(data);
+      }
+
+      const startTime = Date.now();
+
+      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);
+          throw error;
+        }
+
+        // Record successful circuit breaker call
+        circuitBreaker.recordSuccess();
+
+        const text = await response.text();
+        if (!text) {
+          return null as T;
+        }
+        return JSON.parse(text) as T;
+
+      } 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);
+        
+        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);
+      }
     }
-    return JSON.parse(text) as T;
   }
 
-  protected get<T>(path: string): Promise<T> {
-    return this.request<T>('GET', path);
+  /**
+   * Handle errors - log and report
+   */
+  private handleError(error: ApiError): void {
+    const severity = error.getSeverity();
+    const message = error.getDeveloperMessage();
+
+    // Log based on severity
+    if (severity === 'error') {
+      this.logger.error(message, error, error.context);
+    } else if (severity === 'warn') {
+      this.logger.warn(message, error.context);
+    } else {
+      this.logger.info(message, error.context);
+    }
+
+    // Report to error tracking
+    this.errorReporter.report(error, error.context);
   }
 
-  protected post<T>(path: string, data: object): Promise<T> {
-    return this.request<T>('POST', path, data);
+  protected get<T>(path: string, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('GET', path, undefined, options);
   }
 
-  protected put<T>(path: string, data: object): Promise<T> {
-    return this.request<T>('PUT', path, data);
+  protected post<T>(path: string, data: object, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('POST', path, data, options);
   }
 
-  protected delete<T>(path: string): Promise<T> {
-    return this.request<T>('DELETE', path);
+  protected put<T>(path: string, data: object, options?: BaseApiClientOptions): Promise<T> {
+    return this.request<T>('PUT', path, data, options);
   }
 
-  protected patch<T>(path: string, data: object): Promise<T> {
-    return this.request<T>('PATCH', path, data);
+  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/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<any>>();
+
+  /**
+   * Get cached data if not expired
+   */
+  get<T>(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (new Date() > entry.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Set cached data with expiry
+   */
+  set<T>(key: string, data: T, ttlMs: number = 300000): void {
+    const now = new Date();
+    const expiry = new 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> {
+  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 Date().toISOString(),
+        }
+      );
+    }
+
+    // Return undefined (caller must handle)
+    return undefined as unknown as T;
+  }
+
+  // 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 as unknown as T;
+  }
+}
+
+/**
+ * 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/api/base/RetryHandler.ts

@@ -0,0 +1,275 @@
+/**
+ * Retry logic and circuit breaker for API requests
+ */
+
+import { ApiError, ApiErrorType } 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: 3,
+  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;
+  }
+}