view data fixes

apps/website/lib/gateways/api/ApiClient.ts

@@ -0,0 +1,62 @@
+import { AdminApiClient } from './admin/AdminApiClient';
+import { AnalyticsApiClient } from './analytics/AnalyticsApiClient';
+import { AuthApiClient } from './auth/AuthApiClient';
+import { DashboardApiClient } from './dashboard/DashboardApiClient';
+import { DriversApiClient } from './drivers/DriversApiClient';
+import { LeaguesApiClient } from './leagues/LeaguesApiClient';
+import { MediaApiClient } from './media/MediaApiClient';
+import { PaymentsApiClient } from './payments/PaymentsApiClient';
+import { PenaltiesApiClient } from './penalties/PenaltiesApiClient';
+import { PolicyApiClient } from './policy/PolicyApiClient';
+import { ProtestsApiClient } from './protests/ProtestsApiClient';
+import { RacesApiClient } from './races/RacesApiClient';
+import { SponsorsApiClient } from './sponsors/SponsorsApiClient';
+import { TeamsApiClient } from './teams/TeamsApiClient';
+import { WalletsApiClient } from './wallets/WalletsApiClient';
+import { ErrorReporter } from '../interfaces/ErrorReporter';
+import { Logger } from '../interfaces/Logger';
+
+import { ConsoleLogger } from '../infrastructure/logging/ConsoleLogger';
+
+export class ApiClient {
+  public readonly admin: AdminApiClient;
+  public readonly analytics: AnalyticsApiClient;
+  public readonly auth: AuthApiClient;
+  public readonly dashboard: DashboardApiClient;
+  public readonly drivers: DriversApiClient;
+  public readonly leagues: LeaguesApiClient;
+  public readonly media: MediaApiClient;
+  public readonly payments: PaymentsApiClient;
+  public readonly penalties: PenaltiesApiClient;
+  public readonly policy: PolicyApiClient;
+  public readonly protests: ProtestsApiClient;
+  public readonly races: RacesApiClient;
+  public readonly sponsors: SponsorsApiClient;
+  public readonly teams: TeamsApiClient;
+  public readonly wallets: WalletsApiClient;
+
+  constructor(baseUrl: string) {
+    // Default implementations for logger and error reporter if needed
+    const logger: Logger = new ConsoleLogger();
+    const errorReporter: ErrorReporter = { report: (error) => console.error(error) };
+
+    this.admin = new AdminApiClient(baseUrl, errorReporter, logger);
+    this.analytics = new AnalyticsApiClient(baseUrl, errorReporter, logger);
+    this.auth = new AuthApiClient(baseUrl, errorReporter, logger);
+    this.dashboard = new DashboardApiClient(baseUrl, errorReporter, logger);
+    this.drivers = new DriversApiClient(baseUrl, errorReporter, logger);
+    this.leagues = new LeaguesApiClient(baseUrl, errorReporter, logger);
+    this.media = new MediaApiClient(baseUrl, errorReporter, logger);
+    this.payments = new PaymentsApiClient(baseUrl, errorReporter, logger);
+    this.penalties = new PenaltiesApiClient(baseUrl, errorReporter, logger);
+    this.policy = new PolicyApiClient(baseUrl, errorReporter, logger);
+    this.protests = new ProtestsApiClient(baseUrl, errorReporter, logger);
+    this.races = new RacesApiClient(baseUrl, errorReporter, logger);
+    this.sponsors = new SponsorsApiClient(baseUrl, errorReporter, logger);
+    this.teams = new TeamsApiClient(baseUrl, errorReporter, logger);
+    this.wallets = new WalletsApiClient(baseUrl, errorReporter, logger);
+  }
+}
+
+// Export a default instance if needed, but apiClient.ts seems to handle it
+export const api = new ApiClient(process.env.NEXT_PUBLIC_API_URL || '');

apps/website/lib/gateways/api/admin/AdminApiClient.test.ts

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

apps/website/lib/gateways/api/admin/AdminApiClient.ts

@@ -0,0 +1,82 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { UserDto, UserListResponse, ListUsersQuery, DashboardStats } from '@/lib/types/admin';
+
+/**
+ * Admin API Client
+ *
+ * Provides methods for admin operations like user management.
+ * Only accessible to users with Owner or Super Admin roles.
+ */
+export class AdminApiClient extends BaseApiClient {
+  /**
+   * List all users with filtering, sorting, and pagination
+   * Requires Owner or Super Admin role
+   */
+  async listUsers(query: ListUsersQuery = {}): Promise<UserListResponse> {
+    const params = new URLSearchParams();
+    
+    if (query.role) params.append('role', query.role);
+    if (query.status) params.append('status', query.status);
+    if (query.email) params.append('email', query.email);
+    if (query.search) params.append('search', query.search);
+    if (query.page) params.append('page', query.page.toString());
+    if (query.limit) params.append('limit', query.limit.toString());
+    if (query.sortBy) params.append('sortBy', query.sortBy);
+    if (query.sortDirection) params.append('sortDirection', query.sortDirection);
+
+    return this.get<UserListResponse>(`/admin/users?${params.toString()}`);
+  }
+
+  /**
+   * Get a single user by ID
+   * Requires Owner or Super Admin role
+   */
+  async getUser(userId: string): Promise<UserDto> {
+    return this.get<UserDto>(`/admin/users/${userId}`);
+  }
+
+  /**
+   * Update user roles
+   * Requires Owner role only
+   */
+  async updateUserRoles(userId: string, roles: string[]): Promise<UserDto> {
+    return this.patch<UserDto>(`/admin/users/${userId}/roles`, { roles });
+  }
+
+  /**
+   * Update user status (activate/suspend/delete)
+   * Requires Owner or Super Admin role
+   */
+  async updateUserStatus(userId: string, status: string): Promise<UserDto> {
+    return this.patch<UserDto>(`/admin/users/${userId}/status`, { status });
+  }
+
+  /**
+   * Delete a user (soft delete)
+   * Requires Owner or Super Admin role
+   */
+  async deleteUser(userId: string): Promise<void> {
+    return this.delete(`/admin/users/${userId}`);
+  }
+
+  /**
+   * Create a new user
+   * Requires Owner or Super Admin role
+   */
+  async createUser(userData: {
+    email: string;
+    displayName: string;
+    roles: string[];
+    primaryDriverId?: string;
+  }): Promise<UserDto> {
+    return this.post<UserDto>(`/admin/users`, userData);
+  }
+
+  /**
+   * Get dashboard statistics
+   * Requires Owner or Super Admin role
+   */
+  async getDashboardStats(): Promise<DashboardStats> {
+    return this.get<DashboardStats>(`/admin/dashboard/stats`);
+  }
+}

apps/website/lib/gateways/api/analytics/AnalyticsApiClient.test.ts

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

apps/website/lib/gateways/api/analytics/AnalyticsApiClient.ts

@@ -0,0 +1,34 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import { RecordPageViewOutputDTO } from '../../types/generated/RecordPageViewOutputDTO';
+import { RecordEngagementOutputDTO } from '../../types/generated/RecordEngagementOutputDTO';
+import { GetDashboardDataOutputDTO } from '../../types/generated/GetDashboardDataOutputDTO';
+import { GetAnalyticsMetricsOutputDTO } from '../../types/generated/GetAnalyticsMetricsOutputDTO';
+import { RecordPageViewInputDTO } from '../../types/generated/RecordPageViewInputDTO';
+import { RecordEngagementInputDTO } from '../../types/generated/RecordEngagementInputDTO';
+
+/**
+ * Analytics API Client
+ *
+ * Handles all analytics-related API operations.
+ */
+export class AnalyticsApiClient extends BaseApiClient {
+  /** Record a page view */
+  recordPageView(input: RecordPageViewInputDTO): Promise<RecordPageViewOutputDTO> {
+    return this.post<RecordPageViewOutputDTO>('/analytics/page-view', input);
+  }
+
+  /** Record an engagement event */
+  recordEngagement(input: RecordEngagementInputDTO): Promise<RecordEngagementOutputDTO> {
+    return this.post<RecordEngagementOutputDTO>('/analytics/engagement', input);
+  }
+
+  /** Get analytics dashboard data */
+  getDashboardData(): Promise<GetDashboardDataOutputDTO> {
+    return this.get<GetDashboardDataOutputDTO>('/analytics/dashboard');
+  }
+
+  /** Get analytics metrics */
+  getAnalyticsMetrics(): Promise<GetAnalyticsMetricsOutputDTO> {
+    return this.get<GetAnalyticsMetricsOutputDTO>('/analytics/metrics');
+  }
+}

apps/website/lib/gateways/api/auth/AuthApiClient.test.ts

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

apps/website/lib/gateways/api/auth/AuthApiClient.ts

@@ -0,0 +1,45 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import { AuthSessionDTO } from '../../types/generated/AuthSessionDTO';
+import { LoginParamsDTO } from '../../types/generated/LoginParamsDTO';
+import { SignupParamsDTO } from '../../types/generated/SignupParamsDTO';
+import { ForgotPasswordDTO } from '../../types/generated/ForgotPasswordDTO';
+import { ResetPasswordDTO } from '../../types/generated/ResetPasswordDTO';
+
+/**
+ * Auth API Client
+ *
+ * Handles all authentication-related API operations.
+ */
+export class AuthApiClient extends BaseApiClient {
+  /** Sign up with email */
+  signup(params: SignupParamsDTO): Promise<AuthSessionDTO> {
+    return this.post<AuthSessionDTO>('/auth/signup', params);
+  }
+
+  /** Login with email */
+  login(params: LoginParamsDTO): Promise<AuthSessionDTO> {
+    return this.post<AuthSessionDTO>('/auth/login', params);
+  }
+
+  /** Get current session */
+  getSession(): Promise<AuthSessionDTO | null> {
+    return this.request<AuthSessionDTO | null>('GET', '/auth/session', undefined, {
+      allowUnauthenticated: true,
+    });
+  }
+
+  /** Logout */
+  logout(): Promise<void> {
+    return this.post<void>('/auth/logout', {});
+  }
+
+  /** Forgot password - send reset link */
+  forgotPassword(params: ForgotPasswordDTO): Promise<{ message: string; magicLink?: string }> {
+    return this.post<{ message: string; magicLink?: string }>('/auth/forgot-password', params);
+  }
+
+  /** Reset password with token */
+  resetPassword(params: ResetPasswordDTO): Promise<{ message: string }> {
+    return this.post<{ message: string }>('/auth/reset-password', params);
+  }
+}

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;
+  }
+}

apps/website/lib/gateways/api/dashboard/DashboardApiClient.test.ts

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

apps/website/lib/gateways/api/dashboard/DashboardApiClient.ts

@@ -0,0 +1,14 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { DashboardOverviewDTO } from '../../types/generated/DashboardOverviewDTO';
+
+/**
+ * Dashboard API Client
+ *
+ * Handles dashboard overview data aggregation.
+ */
+export class DashboardApiClient extends BaseApiClient {
+  /** Get dashboard overview data */
+  getDashboardOverview(): Promise<DashboardOverviewDTO> {
+    return this.get<DashboardOverviewDTO>('/dashboard/overview');
+  }
+}

apps/website/lib/gateways/api/drivers/DriversApiClient.test.ts

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

apps/website/lib/gateways/api/drivers/DriversApiClient.ts

@@ -0,0 +1,56 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { CompleteOnboardingInputDTO } from '../../types/generated/CompleteOnboardingInputDTO';
+import type { CompleteOnboardingOutputDTO } from '../../types/generated/CompleteOnboardingOutputDTO';
+import type { DriverRegistrationStatusDTO } from '../../types/generated/DriverRegistrationStatusDTO';
+import type { DriverLeaderboardItemDTO } from '../../types/generated/DriverLeaderboardItemDTO';
+import type { GetDriverOutputDTO } from '../../types/generated/GetDriverOutputDTO';
+import type { GetDriverProfileOutputDTO } from '../../types/generated/GetDriverProfileOutputDTO';
+
+type DriversLeaderboardDto = {
+  drivers: DriverLeaderboardItemDTO[];
+};
+
+/**
+ * Drivers API Client
+ *
+ * Handles all driver-related API operations.
+ */
+export class DriversApiClient extends BaseApiClient {
+  /** Get drivers leaderboard */
+  getLeaderboard(): Promise<DriversLeaderboardDto> {
+    return this.get<DriversLeaderboardDto>('/drivers/leaderboard');
+  }
+
+  /** Complete driver onboarding */
+  completeOnboarding(input: CompleteOnboardingInputDTO): Promise<CompleteOnboardingOutputDTO> {
+    return this.post<CompleteOnboardingOutputDTO>('/drivers/complete-onboarding', input);
+  }
+
+  /** Get current driver (based on session) */
+  getCurrent(): Promise<GetDriverOutputDTO | null> {
+    return this.get<GetDriverOutputDTO | null>('/drivers/current', { 
+      allowUnauthenticated: true,
+      retry: false
+    });
+  }
+
+  /** Get driver registration status for a specific race */
+  getRegistrationStatus(driverId: string, raceId: string): Promise<DriverRegistrationStatusDTO> {
+    return this.get<DriverRegistrationStatusDTO>(`/drivers/${driverId}/races/${raceId}/registration-status`);
+  }
+
+  /** Get driver by ID */
+  getDriver(driverId: string): Promise<GetDriverOutputDTO | null> {
+    return this.get<GetDriverOutputDTO | null>(`/drivers/${driverId}`);
+  }
+
+  /** Get driver profile with full details */
+  getDriverProfile(driverId: string): Promise<GetDriverProfileOutputDTO> {
+    return this.get<GetDriverProfileOutputDTO>(`/drivers/${driverId}/profile`);
+  }
+
+  /** Update current driver profile */
+  updateProfile(updates: { bio?: string; country?: string }): Promise<GetDriverOutputDTO> {
+    return this.put<GetDriverOutputDTO>('/drivers/profile', updates);
+  }
+}

apps/website/lib/gateways/api/index.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { ApiClient, api } from './ApiClient';
+
+describe('ApiClient', () => {
+  it('should be defined', () => {
+    expect(ApiClient).toBeDefined();
+  });
+  
+  it('should create instance', () => {
+    const client = new ApiClient('http://test.com');
+    expect(client).toBeDefined();
+    expect(client.leagues).toBeDefined();
+  });
+  
+  it('should have singleton instance', () => {
+    expect(api).toBeDefined();
+  });
+});

apps/website/lib/gateways/api/leagues/LeaguesApiClient.test.ts

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

apps/website/lib/gateways/api/leagues/LeaguesApiClient.ts

@@ -0,0 +1,200 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { AllLeaguesWithCapacityDTO } from '../../types/generated/AllLeaguesWithCapacityDTO';
+import type { TotalLeaguesDTO } from '../../types/generated/TotalLeaguesDTO';
+import type { LeagueStandingsDTO } from '../../types/generated/LeagueStandingsDTO';
+import type { LeagueScheduleDTO } from '../../types/generated/LeagueScheduleDTO';
+import type { LeagueMembershipsDTO } from '../../types/generated/LeagueMembershipsDTO';
+import type { CreateLeagueInputDTO } from '../../types/generated/CreateLeagueInputDTO';
+import type { CreateLeagueOutputDTO } from '../../types/generated/CreateLeagueOutputDTO';
+import type { SponsorshipDetailDTO } from '../../types/generated/SponsorshipDetailDTO';
+import type { RaceDTO } from '../../types/generated/RaceDTO';
+import type { GetLeagueAdminConfigOutputDTO } from '../../types/generated/GetLeagueAdminConfigOutputDTO';
+import type { LeagueScoringPresetDTO } from '../../types/generated/LeagueScoringPresetDTO';
+import type { LeagueSeasonSummaryDTO } from '../../types/generated/LeagueSeasonSummaryDTO';
+import type { CreateLeagueScheduleRaceInputDTO } from '../../types/generated/CreateLeagueScheduleRaceInputDTO';
+import type { CreateLeagueScheduleRaceOutputDTO } from '../../types/generated/CreateLeagueScheduleRaceOutputDTO';
+import type { UpdateLeagueScheduleRaceInputDTO } from '../../types/generated/UpdateLeagueScheduleRaceInputDTO';
+import type { LeagueScheduleRaceMutationSuccessDTO } from '../../types/generated/LeagueScheduleRaceMutationSuccessDTO';
+import type { LeagueSeasonSchedulePublishOutputDTO } from '../../types/generated/LeagueSeasonSchedulePublishOutputDTO';
+import type { LeagueRosterMemberDTO } from '../../types/generated/LeagueRosterMemberDTO';
+import type { LeagueRosterJoinRequestDTO } from '../../types/generated/LeagueRosterJoinRequestDTO';
+import type { ApproveJoinRequestOutputDTO } from '../../types/generated/ApproveJoinRequestOutputDTO';
+import type { RejectJoinRequestOutputDTO } from '../../types/generated/RejectJoinRequestOutputDTO';
+import type { UpdateLeagueMemberRoleOutputDTO } from '../../types/generated/UpdateLeagueMemberRoleOutputDTO';
+import type { RemoveLeagueMemberOutputDTO } from '../../types/generated/RemoveLeagueMemberOutputDTO';
+import type { AllLeaguesWithCapacityAndScoringDTO } from '../../types/AllLeaguesWithCapacityAndScoringDTO';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isRaceDTO(value: unknown): value is RaceDTO {
+  if (!isRecord(value)) return false;
+  return typeof value.id === 'string' && typeof value.name === 'string';
+}
+
+function parseRaceDTOArray(value: unknown): RaceDTO[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isRaceDTO);
+}
+
+/**
+ * Leagues API Client
+ *
+ * Handles all league-related API operations.
+ */
+export class LeaguesApiClient extends BaseApiClient {
+  /** Get all leagues with capacity information */
+  getAllWithCapacity(): Promise<AllLeaguesWithCapacityDTO> {
+    return this.get<AllLeaguesWithCapacityDTO>('/leagues/all-with-capacity', { retry: false });
+  }
+
+  /** Get all leagues with capacity + scoring summary (for leagues page filters) */
+  getAllWithCapacityAndScoring(): Promise<AllLeaguesWithCapacityAndScoringDTO> {
+    return this.get<AllLeaguesWithCapacityAndScoringDTO>('/leagues/all-with-capacity-and-scoring', { retry: false });
+  }
+
+  /** Get total number of leagues */
+  getTotal(): Promise<TotalLeaguesDTO> {
+    return this.get<TotalLeaguesDTO>('/leagues/total-leagues');
+  }
+
+  /** Get league standings */
+  getStandings(leagueId: string): Promise<LeagueStandingsDTO> {
+    return this.get<LeagueStandingsDTO>(`/leagues/${leagueId}/standings`);
+  }
+
+  /** Get league schedule */
+  getSchedule(leagueId: string, seasonId?: string): Promise<LeagueScheduleDTO> {
+    const qs = seasonId ? `?seasonId=${encodeURIComponent(seasonId)}` : '';
+    return this.get<LeagueScheduleDTO>(`/leagues/${leagueId}/schedule${qs}`);
+  }
+
+  /** Get league memberships */
+  async getMemberships(leagueId: string): Promise<LeagueMembershipsDTO> {
+    const response = await this.get<any>(`/leagues/${leagueId}/memberships`);
+    if (Array.isArray(response)) return { members: response };
+    if (response?.members) return response;
+    return { members: [] };
+  }
+
+  /** Create a new league */
+  create(input: CreateLeagueInputDTO): Promise<CreateLeagueOutputDTO> {
+    return this.post<CreateLeagueOutputDTO>('/leagues', input);
+  }
+
+  /** Remove a member from league */
+  removeMember(leagueId: string, performerDriverId: string, targetDriverId: string): Promise<{ success: boolean }> {
+    return this.patch<{ success: boolean }>(`/leagues/${leagueId}/members/${targetDriverId}/remove`, { performerDriverId });
+  }
+
+  /** Update a member's role in league */
+  updateMemberRole(leagueId: string, performerDriverId: string, targetDriverId: string, newRole: string): Promise<{ success: boolean }> {
+    return this.patch<{ success: boolean }>(`/leagues/${leagueId}/members/${targetDriverId}/role`, { performerDriverId, newRole });
+  }
+
+  /** Get league seasons */
+  getSeasons(leagueId: string): Promise<LeagueSeasonSummaryDTO[]> {
+    return this.get<LeagueSeasonSummaryDTO[]>(`/leagues/${leagueId}/seasons`);
+  }
+
+  /** Get season sponsorships */
+  getSeasonSponsorships(seasonId: string): Promise<{ sponsorships: SponsorshipDetailDTO[] }> {
+    return this.get<{ sponsorships: SponsorshipDetailDTO[] }>(`/leagues/seasons/${seasonId}/sponsorships`);
+  }
+
+  /** Get league config */
+  getLeagueConfig(leagueId: string): Promise<GetLeagueAdminConfigOutputDTO> {
+    return this.get<GetLeagueAdminConfigOutputDTO>(`/leagues/${leagueId}/config`);
+  }
+
+  /** Get league scoring presets */
+  getScoringPresets(): Promise<{ presets: LeagueScoringPresetDTO[] }> {
+    return this.get<{ presets: LeagueScoringPresetDTO[] }>(`/leagues/scoring-presets`);
+  }
+
+  /** Transfer league ownership */
+  transferOwnership(leagueId: string, currentOwnerId: string, newOwnerId: string): Promise<{ success: boolean }> {
+    return this.post<{ success: boolean }>(`/leagues/${leagueId}/transfer-ownership`, {
+      currentOwnerId,
+      newOwnerId,
+    });
+  }
+
+  /** Publish a league season schedule (admin/owner only; actor derived from session) */
+  publishSeasonSchedule(leagueId: string, seasonId: string): Promise<LeagueSeasonSchedulePublishOutputDTO> {
+    return this.post<LeagueSeasonSchedulePublishOutputDTO>(`/leagues/${leagueId}/seasons/${seasonId}/schedule/publish`, {});
+  }
+
+  /** Unpublish a league season schedule (admin/owner only; actor derived from session) */
+  unpublishSeasonSchedule(leagueId: string, seasonId: string): Promise<LeagueSeasonSchedulePublishOutputDTO> {
+    return this.post<LeagueSeasonSchedulePublishOutputDTO>(`/leagues/${leagueId}/seasons/${seasonId}/schedule/unpublish`, {});
+  }
+
+  /** Create a schedule race for a league season (admin/owner only; actor derived from session) */
+  createSeasonScheduleRace(
+    leagueId: string,
+    seasonId: string,
+    input: CreateLeagueScheduleRaceInputDTO,
+  ): Promise<CreateLeagueScheduleRaceOutputDTO> {
+    const { example: _, ...payload } = input;
+    return this.post<CreateLeagueScheduleRaceOutputDTO>(`/leagues/${leagueId}/seasons/${seasonId}/schedule/races`, payload);
+  }
+
+  /** Update a schedule race for a league season (admin/owner only; actor derived from session) */
+  updateSeasonScheduleRace(
+    leagueId: string,
+    seasonId: string,
+    raceId: string,
+    input: UpdateLeagueScheduleRaceInputDTO,
+  ): Promise<LeagueScheduleRaceMutationSuccessDTO> {
+    const { example: _, ...payload } = input;
+    return this.patch<LeagueScheduleRaceMutationSuccessDTO>(`/leagues/${leagueId}/seasons/${seasonId}/schedule/races/${raceId}`, payload);
+  }
+
+  /** Delete a schedule race for a league season (admin/owner only; actor derived from session) */
+  deleteSeasonScheduleRace(
+    leagueId: string,
+    seasonId: string,
+    raceId: string,
+  ): Promise<LeagueScheduleRaceMutationSuccessDTO> {
+    return this.delete<LeagueScheduleRaceMutationSuccessDTO>(`/leagues/${leagueId}/seasons/${seasonId}/schedule/races/${raceId}`);
+  }
+
+  /** Get races for a league */
+  async getRaces(leagueId: string): Promise<{ races: RaceDTO[] }> {
+    const response = await this.get<any>(`/leagues/${leagueId}/races`);
+    const races = Array.isArray(response) ? response : (response?.races || []);
+    return { races: parseRaceDTOArray(races) };
+  }
+
+  /** Admin roster: list current members (admin/owner only; actor derived from session) */
+  getAdminRosterMembers(leagueId: string): Promise<LeagueRosterMemberDTO[]> {
+    return this.get<LeagueRosterMemberDTO[]>(`/leagues/${leagueId}/admin/roster/members`);
+  }
+
+  /** Admin roster: list pending join requests (admin/owner only; actor derived from session) */
+  getAdminRosterJoinRequests(leagueId: string): Promise<LeagueRosterJoinRequestDTO[]> {
+    return this.get<LeagueRosterJoinRequestDTO[]>(`/leagues/${leagueId}/admin/roster/join-requests`);
+  }
+
+  /** Admin roster: approve a join request (admin/owner only; actor derived from session) */
+  approveRosterJoinRequest(leagueId: string, joinRequestId: string): Promise<ApproveJoinRequestOutputDTO> {
+    return this.post<ApproveJoinRequestOutputDTO>(`/leagues/${leagueId}/admin/roster/join-requests/${joinRequestId}/approve`, {});
+  }
+
+  /** Admin roster: reject a join request (admin/owner only; actor derived from session) */
+  rejectRosterJoinRequest(leagueId: string, joinRequestId: string): Promise<RejectJoinRequestOutputDTO> {
+    return this.post<RejectJoinRequestOutputDTO>(`/leagues/${leagueId}/admin/roster/join-requests/${joinRequestId}/reject`, {});
+  }
+
+  /** Admin roster: update member role (admin/owner only; actor derived from session) */
+  updateRosterMemberRole(leagueId: string, targetDriverId: string, newRole: string): Promise<UpdateLeagueMemberRoleOutputDTO> {
+    return this.patch<UpdateLeagueMemberRoleOutputDTO>(`/leagues/${leagueId}/admin/roster/members/${targetDriverId}/role`, { newRole });
+  }
+
+  /** Admin roster: remove member (admin/owner only; actor derived from session) */
+  removeRosterMember(leagueId: string, targetDriverId: string): Promise<RemoveLeagueMemberOutputDTO> {
+    return this.patch<RemoveLeagueMemberOutputDTO>(`/leagues/${leagueId}/admin/roster/members/${targetDriverId}/remove`, {});
+  }
+}

apps/website/lib/gateways/api/media/MediaApiClient.test.ts

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

apps/website/lib/gateways/api/media/MediaApiClient.ts

@@ -0,0 +1,59 @@
+import type { DeleteMediaOutputDTO } from '../../types/generated/DeleteMediaOutputDTO';
+import type { GetAvatarOutputDTO } from '../../types/generated/GetAvatarOutputDTO';
+import type { GetMediaOutputDTO } from '../../types/generated/GetMediaOutputDTO';
+import type { RequestAvatarGenerationInputDTO } from '../../types/generated/RequestAvatarGenerationInputDTO';
+import type { RequestAvatarGenerationOutputDTO } from '../../types/generated/RequestAvatarGenerationOutputDTO';
+import type { UpdateAvatarInputDTO } from '../../types/generated/UpdateAvatarInputDTO';
+import type { UpdateAvatarOutputDTO } from '../../types/generated/UpdateAvatarOutputDTO';
+import type { UploadMediaOutputDTO } from '../../types/generated/UploadMediaOutputDTO';
+import type { ValidateFaceInputDTO } from '../../types/generated/ValidateFaceInputDTO';
+import type { ValidateFaceOutputDTO } from '../../types/generated/ValidateFaceOutputDTO';
+import { BaseApiClient } from '../base/BaseApiClient';
+
+/**
+ * Media API Client
+ *
+ * Handles all media-related API operations.
+ */
+export class MediaApiClient extends BaseApiClient {
+  /** Upload media file */
+  uploadMedia(input: { file: File; type: string; category?: string }): Promise<UploadMediaOutputDTO> {
+    const formData = new FormData();
+    formData.append('file', input.file);
+    formData.append('type', input.type);
+    if (input.category) {
+      formData.append('category', input.category);
+    }
+    return this.post<UploadMediaOutputDTO>('/media/upload', formData);
+  }
+
+  /** Get media by ID */
+  getMedia(mediaId: string): Promise<GetMediaOutputDTO> {
+    return this.get<GetMediaOutputDTO>(`/media/${mediaId}`);
+  }
+
+  /** Delete media by ID */
+  deleteMedia(mediaId: string): Promise<DeleteMediaOutputDTO> {
+    return this.delete<DeleteMediaOutputDTO>(`/media/${mediaId}`);
+  }
+
+  /** Request avatar generation */
+  requestAvatarGeneration(input: RequestAvatarGenerationInputDTO): Promise<RequestAvatarGenerationOutputDTO> {
+    return this.post<RequestAvatarGenerationOutputDTO>('/media/avatar/generate', input);
+  }
+
+  /** Get avatar for driver */
+  getAvatar(driverId: string): Promise<GetAvatarOutputDTO> {
+    return this.get<GetAvatarOutputDTO>(`/media/avatar/${driverId}`);
+  }
+
+  /** Update avatar for driver */
+  updateAvatar(input: UpdateAvatarInputDTO): Promise<UpdateAvatarOutputDTO> {
+    return this.put<UpdateAvatarOutputDTO>(`/media/avatar/${input.driverId}`, { avatarUrl: input.avatarUrl });
+  }
+
+  /** Validate face photo for avatar generation */
+  validateFacePhoto(input: ValidateFaceInputDTO): Promise<ValidateFaceOutputDTO> {
+    return this.post<ValidateFaceOutputDTO>('/media/avatar/validate-face', input);
+  }
+}

apps/website/lib/gateways/api/payments/PaymentsApiClient.test.ts

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

apps/website/lib/gateways/api/payments/PaymentsApiClient.ts

@@ -0,0 +1,156 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { MembershipFeeDTO } from '../../types/generated/MembershipFeeDTO';
+import type { MemberPaymentDTO } from '../../types/generated/MemberPaymentDTO';
+import type { PaymentDTO } from '../../types/generated/PaymentDTO';
+import type { PrizeDTO } from '../../types/generated/PrizeDTO';
+import type { TransactionDTO } from '../../types/generated/TransactionDTO';
+import type { UpdatePaymentStatusInputDTO } from '../../types/generated/UpdatePaymentStatusInputDTO';
+import type { WalletDTO } from '../../types/generated/WalletDTO';
+
+// Define missing types that are not fully generated
+type GetPaymentsOutputDto = { payments: PaymentDTO[] };
+type CreatePaymentInputDto = {
+  type: 'sponsorship' | 'membership_fee';
+  amount: number;
+  payerId: string;
+  payerType: 'sponsor' | 'driver';
+  leagueId: string;
+  seasonId?: string;
+};
+type CreatePaymentOutputDto = { payment: PaymentDTO };
+type GetMembershipFeesOutputDto = {
+  fee: MembershipFeeDTO | null;
+  payments: MemberPaymentDTO[]
+};
+type GetPrizesOutputDto = { prizes: PrizeDTO[] };
+type GetWalletOutputDto = {
+  wallet: WalletDTO;
+  transactions: TransactionDTO[]
+};
+type ProcessWalletTransactionInputDto = {
+  leagueId: string;
+  type: 'deposit' | 'withdrawal' | 'platform_fee';
+  amount: number;
+  description: string;
+  referenceId?: string;
+  referenceType?: 'sponsorship' | 'membership_fee' | 'prize';
+};
+type ProcessWalletTransactionOutputDto = {
+  wallet: WalletDTO;
+  transaction: TransactionDTO
+};
+type UpdateMemberPaymentInputDto = {
+  feeId: string;
+  driverId: string;
+  status?: 'pending' | 'paid' | 'overdue';
+  paidAt?: Date | string;
+};
+type UpdateMemberPaymentOutputDto = { payment: MemberPaymentDTO };
+type UpdatePaymentStatusOutputDto = { payment: PaymentDTO };
+type UpsertMembershipFeeInputDto = {
+  leagueId: string;
+  seasonId?: string;
+  type: 'season' | 'monthly' | 'per_race';
+  amount: number;
+};
+type UpsertMembershipFeeOutputDto = { fee: MembershipFeeDTO };
+type CreatePrizeInputDto = {
+  leagueId: string;
+  seasonId: string;
+  position: number;
+  name: string;
+  amount: number;
+  type: 'cash' | 'merchandise' | 'other';
+  description?: string;
+};
+type CreatePrizeOutputDto = { prize: PrizeDTO };
+type AwardPrizeInputDto = {
+  prizeId: string;
+  driverId: string;
+};
+type AwardPrizeOutputDto = { prize: PrizeDTO };
+type DeletePrizeOutputDto = { success: boolean };
+
+/**
+ * Payments API Client
+ *
+ * Handles all payment-related API operations.
+ */
+export class PaymentsApiClient extends BaseApiClient {
+  /** Get payments */
+  getPayments(query?: { leagueId?: string; payerId?: string; type?: 'sponsorship' | 'membership_fee'; status?: 'pending' | 'completed' | 'failed' | 'refunded' }): Promise<GetPaymentsOutputDto> {
+    const params = new URLSearchParams();
+    if (query?.leagueId) params.append('leagueId', query.leagueId);
+    if (query?.payerId) params.append('payerId', query.payerId);
+    if (query?.type) params.append('type', query.type);
+    if (query?.status) params.append('status', query.status);
+    const queryString = params.toString();
+    return this.get<GetPaymentsOutputDto>(`/payments${queryString ? `?${queryString}` : ''}`);
+  }
+
+  /** Create a payment */
+  createPayment(input: CreatePaymentInputDto): Promise<CreatePaymentOutputDto> {
+    return this.post<CreatePaymentOutputDto>('/payments', input);
+  }
+
+  /** Get membership fees */
+  getMembershipFees(query: { leagueId: string; driverId?: string }): Promise<GetMembershipFeesOutputDto> {
+    const params = new URLSearchParams();
+    params.append('leagueId', query.leagueId);
+    if (query.driverId) params.append('driverId', query.driverId);
+    const queryString = params.toString();
+    return this.get<GetMembershipFeesOutputDto>(`/payments/membership-fees?${queryString}`);
+  }
+
+  /** Get prizes */
+  getPrizes(query?: { leagueId?: string; seasonId?: string }): Promise<GetPrizesOutputDto> {
+    const params = new URLSearchParams();
+    if (query?.leagueId) params.append('leagueId', query.leagueId);
+    if (query?.seasonId) params.append('seasonId', query.seasonId);
+    const queryString = params.toString();
+    return this.get<GetPrizesOutputDto>(`/payments/prizes${queryString ? `?${queryString}` : ''}`);
+  }
+
+  /** Get wallet */
+  getWallet(query?: { leagueId?: string }): Promise<GetWalletOutputDto> {
+    const params = new URLSearchParams();
+    if (query?.leagueId) params.append('leagueId', query.leagueId);
+    const queryString = params.toString();
+    return this.get<GetWalletOutputDto>(`/payments/wallets${queryString ? `?${queryString}` : ''}`);
+  }
+
+  /** Update payment status */
+  updatePaymentStatus(input: UpdatePaymentStatusInputDTO): Promise<UpdatePaymentStatusOutputDto> {
+    return this.patch<UpdatePaymentStatusOutputDto>('/payments/status', input);
+  }
+
+  /** Upsert membership fee */
+  upsertMembershipFee(input: UpsertMembershipFeeInputDto): Promise<UpsertMembershipFeeOutputDto> {
+    return this.post<UpsertMembershipFeeOutputDto>('/payments/membership-fees', input);
+  }
+
+  /** Update member payment */
+  updateMemberPayment(input: UpdateMemberPaymentInputDto): Promise<UpdateMemberPaymentOutputDto> {
+    return this.patch<UpdateMemberPaymentOutputDto>('/payments/membership-fees/member-payment', input);
+  }
+
+  /** Create prize */
+  createPrize(input: CreatePrizeInputDto): Promise<CreatePrizeOutputDto> {
+    return this.post<CreatePrizeOutputDto>('/payments/prizes', input);
+  }
+
+  /** Award prize */
+  awardPrize(input: AwardPrizeInputDto): Promise<AwardPrizeOutputDto> {
+    return this.patch<AwardPrizeOutputDto>('/payments/prizes/award', input);
+  }
+
+  /** Delete prize */
+  deletePrize(prizeId: string): Promise<DeletePrizeOutputDto> {
+    return this.delete<DeletePrizeOutputDto>(`/payments/prizes?prizeId=${prizeId}`);
+  }
+
+  /** Process wallet transaction */
+  processWalletTransaction(input: ProcessWalletTransactionInputDto): Promise<ProcessWalletTransactionOutputDto> {
+    return this.post<ProcessWalletTransactionOutputDto>('/payments/wallets/transactions', input);
+  }
+}

apps/website/lib/gateways/api/penalties/PenaltiesApiClient.test.ts

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

apps/website/lib/gateways/api/penalties/PenaltiesApiClient.ts

@@ -0,0 +1,26 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import { RacePenaltiesDTO } from '../../types/generated/RacePenaltiesDTO';
+import { ApplyPenaltyCommandDTO } from '../../types/generated/ApplyPenaltyCommandDTO';
+import type { PenaltyTypesReferenceDTO } from '../../types/PenaltyTypesReferenceDTO';
+
+/**
+ * Penalties API Client
+ *
+ * Handles all penalty-related API operations.
+ */
+export class PenaltiesApiClient extends BaseApiClient {
+  /** Get penalties for a race */
+  getRacePenalties(raceId: string): Promise<RacePenaltiesDTO> {
+    return this.get<RacePenaltiesDTO>(`/races/${raceId}/penalties`);
+  }
+
+  /** Get allowed penalty types and semantics */
+  getPenaltyTypesReference(): Promise<PenaltyTypesReferenceDTO> {
+    return this.get<PenaltyTypesReferenceDTO>('/races/reference/penalty-types');
+  }
+
+  /** Apply a penalty */
+  applyPenalty(input: ApplyPenaltyCommandDTO): Promise<void> {
+    return this.post<void>('/races/penalties/apply', input);
+  }
+}

apps/website/lib/gateways/api/policy/PolicyApiClient.test.ts

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

apps/website/lib/gateways/api/policy/PolicyApiClient.ts

@@ -0,0 +1,28 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { ErrorReporter } from '../../interfaces/ErrorReporter';
+import type { Logger } from '../../interfaces/Logger';
+
+export type OperationalMode = 'normal' | 'maintenance' | 'test';
+export type FeatureState = 'enabled' | 'disabled' | 'coming_soon' | 'hidden';
+
+export type PolicySnapshotDto = {
+  policyVersion: number;
+  operationalMode: OperationalMode;
+  maintenanceAllowlist: {
+    view: string[];
+    mutate: string[];
+  };
+  capabilities: Record<string, FeatureState>;
+  loadedFrom: 'env' | 'file' | 'defaults';
+  loadedAtIso: string;
+};
+
+export class PolicyApiClient extends BaseApiClient {
+  constructor(baseUrl: string, errorReporter: ErrorReporter, logger: Logger) {
+    super(baseUrl, errorReporter, logger);
+  }
+
+  getSnapshot(): Promise<PolicySnapshotDto> {
+    return this.get<PolicySnapshotDto>('/policy/snapshot');
+  }
+}

apps/website/lib/gateways/api/protests/ProtestsApiClient.test.ts

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

apps/website/lib/gateways/api/protests/ProtestsApiClient.ts

@@ -0,0 +1,43 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { ApplyPenaltyCommandDTO } from '../../types/generated/ApplyPenaltyCommandDTO';
+import type { LeagueAdminProtestsDTO } from '../../types/generated/LeagueAdminProtestsDTO';
+import type { RaceProtestsDTO } from '../../types/generated/RaceProtestsDTO';
+import type { RequestProtestDefenseCommandDTO } from '../../types/generated/RequestProtestDefenseCommandDTO';
+import type { ReviewProtestCommandDTO } from '../../types/generated/ReviewProtestCommandDTO';
+
+/**
+ * Protests API Client
+ *
+ * Handles all protest-related API operations.
+ */
+export class ProtestsApiClient extends BaseApiClient {
+  /** Get protests for a league */
+  getLeagueProtests(leagueId: string): Promise<LeagueAdminProtestsDTO> {
+    return this.get<LeagueAdminProtestsDTO>(`/leagues/${leagueId}/protests`);
+  }
+
+  /** Get a specific protest for a league */
+  getLeagueProtest(leagueId: string, protestId: string): Promise<LeagueAdminProtestsDTO> {
+    return this.get<LeagueAdminProtestsDTO>(`/leagues/${leagueId}/protests/${protestId}`);
+  }
+
+  /** Apply a penalty */
+  applyPenalty(input: ApplyPenaltyCommandDTO): Promise<void> {
+    return this.post<void>('/races/penalties/apply', input);
+  }
+
+  /** Request protest defense */
+  requestDefense(input: RequestProtestDefenseCommandDTO): Promise<void> {
+    return this.post<void>('/races/protests/defense/request', input);
+  }
+
+  /** Review protest */
+  reviewProtest(input: ReviewProtestCommandDTO): Promise<void> {
+    return this.post<void>(`/protests/${input.protestId}/review`, input);
+  }
+
+  /** Get protests for a race */
+  getRaceProtests(raceId: string): Promise<RaceProtestsDTO> {
+    return this.get<RaceProtestsDTO>(`/races/${raceId}/protests`);
+  }
+}

apps/website/lib/gateways/api/races/RacesApiClient.test.ts

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

apps/website/lib/gateways/api/races/RacesApiClient.ts

@@ -0,0 +1,100 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { RaceStatsDTO } from '../../types/generated/RaceStatsDTO';
+import type { RacesPageDataRaceDTO } from '../../types/generated/RacesPageDataRaceDTO';
+import type { RaceResultsDetailDTO } from '../../types/generated/RaceResultsDetailDTO';
+import type { RaceWithSOFDTO } from '../../types/generated/RaceWithSOFDTO';
+import type { RegisterForRaceParamsDTO } from '../../types/generated/RegisterForRaceParamsDTO';
+import type { ImportRaceResultsDTO } from '../../types/generated/ImportRaceResultsDTO';
+import type { WithdrawFromRaceParamsDTO } from '../../types/generated/WithdrawFromRaceParamsDTO';
+import type { RaceDetailRaceDTO } from '../../types/generated/RaceDetailRaceDTO';
+import type { RaceDetailLeagueDTO } from '../../types/generated/RaceDetailLeagueDTO';
+import type { RaceDetailEntryDTO } from '../../types/generated/RaceDetailEntryDTO';
+import type { RaceDetailRegistrationDTO } from '../../types/generated/RaceDetailRegistrationDTO';
+import type { RaceDetailUserResultDTO } from '../../types/generated/RaceDetailUserResultDTO';
+import type { FileProtestCommandDTO } from '../../types/generated/FileProtestCommandDTO';
+
+// Define missing types
+export type RacesPageDataDTO = { races: RacesPageDataRaceDTO[] };
+export type RaceDetailDTO = {
+  race: RaceDetailRaceDTO | null;
+  league: RaceDetailLeagueDTO | null;
+  entryList: RaceDetailEntryDTO[];
+  registration: RaceDetailRegistrationDTO;
+  userResult: RaceDetailUserResultDTO | null;
+  error?: string;
+};
+export type ImportRaceResultsSummaryDTO = {
+  success: boolean;
+  raceId: string;
+  driversProcessed: number;
+  resultsRecorded: number;
+  errors?: string[];
+};
+
+/**
+ * Races API Client
+ *
+ * Handles all race-related API operations.
+ */
+export class RacesApiClient extends BaseApiClient {
+  /** Get total number of races */
+  getTotal(): Promise<RaceStatsDTO> {
+    return this.get<RaceStatsDTO>('/races/total-races');
+  }
+
+  /** Get races page data */
+  getPageData(leagueId?: string): Promise<RacesPageDataDTO> {
+    const query = leagueId ? `?leagueId=${encodeURIComponent(leagueId)}` : '';
+    return this.get<RacesPageDataDTO>(`/races/page-data${query}`);
+  }
+
+  /** Get race detail */
+  getDetail(raceId: string, driverId: string): Promise<RaceDetailDTO> {
+    return this.get<RaceDetailDTO>(`/races/${raceId}?driverId=${driverId}`);
+  }
+
+  /** Get race results detail */
+  getResultsDetail(raceId: string): Promise<RaceResultsDetailDTO> {
+    return this.get<RaceResultsDetailDTO>(`/races/${raceId}/results`);
+  }
+
+  /** Get race with strength of field */
+  getWithSOF(raceId: string): Promise<RaceWithSOFDTO> {
+    return this.get<RaceWithSOFDTO>(`/races/${raceId}/sof`);
+  }
+
+  /** Register for race */
+  register(raceId: string, input: RegisterForRaceParamsDTO): Promise<void> {
+    return this.post<void>(`/races/${raceId}/register`, input);
+  }
+
+  /** Import race results */
+  importResults(raceId: string, input: ImportRaceResultsDTO): Promise<ImportRaceResultsSummaryDTO> {
+    return this.post<ImportRaceResultsSummaryDTO>(`/races/${raceId}/import-results`, input);
+  }
+
+  /** Withdraw from race */
+  withdraw(raceId: string, input: WithdrawFromRaceParamsDTO): Promise<void> {
+    return this.post<void>(`/races/${raceId}/withdraw`, input);
+  }
+
+  /** Cancel race */
+  cancel(raceId: string): Promise<void> {
+    return this.post<void>(`/races/${raceId}/cancel`, {});
+  }
+
+  /** Complete race */
+  complete(raceId: string): Promise<void> {
+    return this.post<void>(`/races/${raceId}/complete`, {});
+  }
+
+  /** Re-open race */
+  reopen(raceId: string): Promise<void> {
+    return this.post<void>(`/races/${raceId}/reopen`, {});
+  }
+
+  /** File a protest */
+  fileProtest(input: FileProtestCommandDTO): Promise<void> {
+    return this.post<void>('/races/protests/file', input);
+  }
+}

apps/website/lib/gateways/api/sponsors/SponsorsApiClient.test.ts

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

apps/website/lib/gateways/api/sponsors/SponsorsApiClient.ts

@@ -0,0 +1,114 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+import type { CreateSponsorInputDTO } from '../../types/generated/CreateSponsorInputDTO';
+import type { SponsorDashboardDTO } from '../../types/generated/SponsorDashboardDTO';
+import type { SponsorSponsorshipsDTO } from '../../types/generated/SponsorSponsorshipsDTO';
+import type { GetPendingSponsorshipRequestsOutputDTO } from '../../types/generated/GetPendingSponsorshipRequestsOutputDTO';
+import type { AcceptSponsorshipRequestInputDTO } from '../../types/generated/AcceptSponsorshipRequestInputDTO';
+import type { RejectSponsorshipRequestInputDTO } from '../../types/generated/RejectSponsorshipRequestInputDTO';
+import type { GetSponsorOutputDTO } from '../../types/generated/GetSponsorOutputDTO';
+import type { SponsorDTO } from '../../types/generated/SponsorDTO';
+
+// Types that are not yet generated
+export type CreateSponsorOutputDto = { id: string; name: string };
+export type GetEntitySponsorshipPricingResultDto = { pricing: Array<{ entityType: string; price: number }> };
+export type GetSponsorsOutputDto = { sponsors: SponsorDTO[] };
+
+/**
+ * Sponsors API Client
+ *
+ * Handles all sponsor-related API operations.
+ */
+export class SponsorsApiClient extends BaseApiClient {
+  /** Get sponsorship pricing */
+  getPricing(): Promise<GetEntitySponsorshipPricingResultDto> {
+    return this.get<GetEntitySponsorshipPricingResultDto>('/sponsors/pricing');
+  }
+
+  /** Get all sponsors */
+  getAll(): Promise<GetSponsorsOutputDto> {
+    return this.get<GetSponsorsOutputDto>('/sponsors');
+  }
+
+  /** Create a new sponsor */
+  create(input: CreateSponsorInputDTO): Promise<CreateSponsorOutputDto> {
+    return this.post<CreateSponsorOutputDto>('/sponsors', input);
+  }
+
+  /** Get sponsor dashboard */
+  getDashboard(sponsorId: string): Promise<SponsorDashboardDTO | null> {
+    return this.get<SponsorDashboardDTO | null>(`/sponsors/dashboard/${sponsorId}`);
+  }
+
+  /** Get sponsor sponsorships */
+  getSponsorships(sponsorId: string): Promise<SponsorSponsorshipsDTO | null> {
+    return this.get<SponsorSponsorshipsDTO | null>(`/sponsors/${sponsorId}/sponsorships`);
+  }
+
+  /** Get sponsor by ID */
+  getSponsor(sponsorId: string): Promise<GetSponsorOutputDTO | null> {
+    return this.get<GetSponsorOutputDTO | null>(`/sponsors/${sponsorId}`);
+  }
+
+  /** Get pending sponsorship requests for an entity */
+  getPendingSponsorshipRequests(params: { entityType: string; entityId: string }): Promise<GetPendingSponsorshipRequestsOutputDTO> {
+    return this.get<GetPendingSponsorshipRequestsOutputDTO>(`/sponsors/requests?entityType=${params.entityType}&entityId=${params.entityId}`);
+  }
+
+  /** Accept a sponsorship request */
+  acceptSponsorshipRequest(requestId: string, input: AcceptSponsorshipRequestInputDTO): Promise<void> {
+    return this.post(`/sponsors/requests/${requestId}/accept`, input);
+  }
+
+  /** Reject a sponsorship request */
+  rejectSponsorshipRequest(requestId: string, input: RejectSponsorshipRequestInputDTO): Promise<void> {
+    return this.post(`/sponsors/requests/${requestId}/reject`, input);
+  }
+
+  /** Get sponsor billing information */
+  getBilling(sponsorId: string): Promise<{
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paymentMethods: any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    invoices: any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    stats: any;
+  }> {
+    return this.get(`/sponsors/billing/${sponsorId}`);
+  }
+
+  /** Get available leagues for sponsorship */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getAvailableLeagues(): Promise<any[]> {
+    return this.get('/sponsors/leagues/available');
+  }
+
+  /** Get detailed league information */
+  getLeagueDetail(leagueId: string): Promise<{
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    league: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    drivers: any[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    races: any[];
+  }> {
+    return this.get(`/sponsors/leagues/${leagueId}/detail`);
+  }
+
+  /** Get sponsor settings */
+  getSettings(sponsorId: string): Promise<{
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    profile: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    notifications: any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    privacy: any;
+  }> {
+    return this.get(`/sponsors/settings/${sponsorId}`);
+  }
+
+  /** Update sponsor settings */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateSettings(sponsorId: string, input: any): Promise<void> {
+    return this.put(`/sponsors/settings/${sponsorId}`, input);
+  }
+}

apps/website/lib/gateways/api/teams/TeamsApiClient.test.ts

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

apps/website/lib/gateways/api/teams/TeamsApiClient.ts

@@ -0,0 +1,64 @@
+import type { GetAllTeamsOutputDTO } from '@/lib/types/generated/GetAllTeamsOutputDTO';
+import type { GetTeamsLeaderboardOutputDTO } from '@/lib/types/generated/GetTeamsLeaderboardOutputDTO';
+import type { GetTeamDetailsOutputDTO } from '@/lib/types/generated/GetTeamDetailsOutputDTO';
+import type { GetTeamMembersOutputDTO } from '@/lib/types/generated/GetTeamMembersOutputDTO';
+import type { GetTeamJoinRequestsOutputDTO } from '@/lib/types/generated/GetTeamJoinRequestsOutputDTO';
+import type { CreateTeamInputDTO } from '@/lib/types/generated/CreateTeamInputDTO';
+import type { CreateTeamOutputDTO } from '@/lib/types/generated/CreateTeamOutputDTO';
+import type { UpdateTeamInputDTO } from '@/lib/types/generated/UpdateTeamInputDTO';
+import type { UpdateTeamOutputDTO } from '@/lib/types/generated/UpdateTeamOutputDTO';
+import type { GetDriverTeamOutputDTO } from '@/lib/types/generated/GetDriverTeamOutputDTO';
+import type { GetTeamMembershipOutputDTO } from '@/lib/types/generated/GetTeamMembershipOutputDTO';
+import { BaseApiClient } from '../base/BaseApiClient';
+
+/**
+ * Teams API Client
+ *
+ * Handles all team-related API operations.
+ */
+export class TeamsApiClient extends BaseApiClient {
+  /** Get all teams */
+  getAll(): Promise<GetAllTeamsOutputDTO> {
+    return this.get<GetAllTeamsOutputDTO>('/teams/all');
+  }
+
+  /** Get teams leaderboard */
+  getLeaderboard(): Promise<GetTeamsLeaderboardOutputDTO> {
+    return this.get<GetTeamsLeaderboardOutputDTO>('/teams/leaderboard');
+  }
+
+  /** Get team details */
+  getDetails(teamId: string): Promise<GetTeamDetailsOutputDTO | null> {
+    return this.get<GetTeamDetailsOutputDTO | null>(`/teams/${teamId}`);
+  }
+
+  /** Get team members */
+  getMembers(teamId: string): Promise<GetTeamMembersOutputDTO> {
+    return this.get<GetTeamMembersOutputDTO>(`/teams/${teamId}/members`);
+  }
+
+  /** Get team join requests */
+  getJoinRequests(teamId: string): Promise<GetTeamJoinRequestsOutputDTO> {
+    return this.get<GetTeamJoinRequestsOutputDTO>(`/teams/${teamId}/join-requests`);
+  }
+
+  /** Create a new team */
+  create(input: CreateTeamInputDTO): Promise<CreateTeamOutputDTO> {
+    return this.post<CreateTeamOutputDTO>('/teams', input);
+  }
+
+  /** Update team */
+  update(teamId: string, input: UpdateTeamInputDTO): Promise<UpdateTeamOutputDTO> {
+    return this.patch<UpdateTeamOutputDTO>(`/teams/${teamId}`, input);
+  }
+
+  /** Get driver's team */
+  getDriverTeam(driverId: string): Promise<GetDriverTeamOutputDTO | null> {
+    return this.get<GetDriverTeamOutputDTO | null>(`/teams/driver/${driverId}`);
+  }
+
+  /** Get membership for a driver in a team */
+  getMembership(teamId: string, driverId: string): Promise<GetTeamMembershipOutputDTO | null> {
+    return this.get<GetTeamMembershipOutputDTO | null>(`/teams/${teamId}/members/${driverId}`);
+  }
+}

apps/website/lib/gateways/api/wallets/WalletsApiClient.test.ts

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

apps/website/lib/gateways/api/wallets/WalletsApiClient.ts

@@ -0,0 +1,54 @@
+import { BaseApiClient } from '../base/BaseApiClient';
+
+export interface LeagueWalletDTO {
+  balance: number;
+  currency: string;
+  totalRevenue: number;
+  totalFees: number;
+  totalWithdrawals: number;
+  pendingPayouts: number;
+  canWithdraw: boolean;
+  withdrawalBlockReason?: string;
+  transactions: WalletTransactionDTO[];
+}
+
+export interface WalletTransactionDTO {
+  id: string;
+  type: 'sponsorship' | 'membership' | 'withdrawal' | 'prize';
+  description: string;
+  amount: number;
+  fee: number;
+  netAmount: number;
+  date: string; // ISO string
+  status: 'completed' | 'pending' | 'failed';
+  reference?: string;
+}
+
+export interface WithdrawRequestDTO {
+  amount: number;
+  currency: string;
+  seasonId: string;
+  destinationAccount: string;
+}
+
+export interface WithdrawResponseDTO {
+  success: boolean;
+  message?: string;
+}
+
+/**
+ * Wallets API Client
+ *
+ * Handles all wallet-related API operations.
+ */
+export class WalletsApiClient extends BaseApiClient {
+  /** Get league wallet */
+  getLeagueWallet(leagueId: string): Promise<LeagueWalletDTO> {
+    return this.get<LeagueWalletDTO>(`/leagues/${leagueId}/wallet`);
+  }
+
+  /** Withdraw from league wallet */
+  withdrawFromLeagueWallet(leagueId: string, request: WithdrawRequestDTO): Promise<WithdrawResponseDTO> {
+    return this.post<WithdrawResponseDTO>(`/leagues/${leagueId}/wallet/withdraw`, request);
+  }
+}