@payez/next-mvp 3.0.0

package/src/lib/standardized-client-api.ts

@@ -0,0 +1,896 @@
+"use client";
+
+// ========================================================================================
+// BULLETPROOF STANDARDIZED CLIENT API - ZERO TOLERANCE FOR BAD RESPONSES
+// ========================================================================================
+// This client API ENFORCES the standardized response format
+// It will BREAK if APIs don't return the expected structure
+// NO MORE GUESSING data.data.data.data - EVER AGAIN!
+// ========================================================================================
+
+import { getSession } from 'next-auth/react';
+import { DefaultSession } from 'next-auth';
+import { 
+  StandardizedResponse,
+  StandardizedApiResponse,
+  StandardizedPagedResponse,
+  StandardizedErrorResponse,
+  validateStandardizedResponse,
+  isSuccessResponse,
+  isPagedResponse,
+  isErrorResponse
+} from './types/api-responses';
+
+
+
+// ========================================================================================
+// CLIENT API ERROR TYPES
+// ========================================================================================
+
+/**
+ * ERROR THROWN WHEN API RESPONSE FORMAT IS INVALID
+ * This means the API is NOT following our standardized format
+ */
+export class ApiResponseFormatError extends Error {
+  constructor(message: string, public readonly endpoint: string, public readonly rawResponse: unknown) {
+    super(`API_FORMAT_ERROR: ${message}`);
+    this.name = 'ApiResponseFormatError';
+  }
+}
+
+/**
+ * ERROR THROWN WHEN API RETURNS A STANDARDIZED ERROR RESPONSE
+ * This is a properly formatted error from the API
+ */
+export class ApiBusinessLogicError extends Error {
+  constructor(
+    public readonly errorCode: string,
+    message: string,
+    public readonly operation: string,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiBusinessLogicError';
+  }
+}
+
+/**
+ * ERROR THROWN WHEN VALIDATION FAILS
+ * This is a properly formatted validation error from the API
+ */
+export class ApiValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly operation: string,
+    public readonly validationErrors: Record<string, string[]>,
+    public readonly invalidValue?: unknown,
+    public readonly primaryField?: string
+  ) {
+    super(message);
+    this.name = 'ApiValidationError';
+  }
+}
+
+/**
+ * ERROR THROWN WHEN NETWORK/HTTP ISSUES OCCUR
+ */
+export class ApiNetworkError extends Error {
+  constructor(message: string, public readonly status: number, public readonly endpoint: string) {
+    super(`NETWORK_ERROR: ${message}`);
+    this.name = 'ApiNetworkError';
+  }
+}
+
+// ========================================================================================
+// AUTHENTICATION STATE MANAGEMENT
+// ========================================================================================
+
+// Coordinate client-side refresh to avoid duplicate refresh calls racing with
+// server-side middleware or other tabs. Only one refresh runs at a time.
+let refreshInFlight: Promise<boolean> | null = null;
+
+// Enhanced redirect logic with grace period and retry attempts
+let authRedirectScheduled = false;
+let lastAuthFailureTime = 0;
+let consecutiveAuthFailures = 0;
+const AUTH_FAILURE_GRACE_PERIOD = 2000; // 2 seconds grace period
+const MAX_AUTH_FAILURES_BEFORE_REDIRECT = 2; // Allow 2 failures before redirect
+const AUTH_FAILURE_RESET_WINDOW = 30000; // Reset failure count after 30 seconds
+
+// Helper: detect pre-2FA session (session exists, requires 2FA and not completed)
+function isPreTwoFactorSession(session: any | null | undefined): boolean {
+  return !!(session?.user?.requiresTwoFactor && !session?.user?.twoFactorSessionVerified);
+}
+
+// Reset auth failure state on successful requests
+function resetAuthFailureState() {
+  if (consecutiveAuthFailures > 0) {
+    console.log(`✅ Resetting auth failure state (was ${consecutiveAuthFailures} failures)`);
+    consecutiveAuthFailures = 0;
+    lastAuthFailureTime = 0;
+    authRedirectScheduled = false;
+  }
+}
+
+function scheduleLoginRedirect(isImmediate = false) {
+  if (authRedirectScheduled) return;
+  
+  const now = Date.now();
+  
+  // Reset consecutive failures if enough time has passed
+  if (now - lastAuthFailureTime > AUTH_FAILURE_RESET_WINDOW) {
+    consecutiveAuthFailures = 0;
+  }
+  
+  consecutiveAuthFailures++;
+  lastAuthFailureTime = now;
+  
+  console.warn(`🔴 Auth failure #${consecutiveAuthFailures}, immediate: ${isImmediate}`);
+  
+  // Only redirect if we've had multiple failures or if explicitly requested
+  if (!isImmediate && consecutiveAuthFailures < MAX_AUTH_FAILURES_BEFORE_REDIRECT) {
+    console.log(`⏳ Delaying redirect - only ${consecutiveAuthFailures} failures so far`);
+    return;
+  }
+  
+  authRedirectScheduled = true;
+  
+  const redirectFunction = () => {
+    try {
+      const returnUrl = encodeURIComponent(`${window.location.pathname}${window.location.search}`);
+      console.warn(`🔄 Redirecting to login with return URL: ${returnUrl}`);
+      window.location.href = `/account-auth/login?returnUrl=${returnUrl}`;
+    } catch (error) {
+      console.error('❌ Error during login redirect:', error);
+      // Final fallback
+      try {
+        window.location.href = '/account-auth/login';
+      } catch {
+        // no-op if window is not available
+      }
+    }
+  };
+  
+  if (isImmediate) {
+    // Immediate redirect for critical auth failures
+    redirectFunction();
+  } else {
+    // Small delay to allow any pending requests to complete
+    console.log(`⏳ Scheduling redirect with ${AUTH_FAILURE_GRACE_PERIOD}ms grace period`);
+    setTimeout(redirectFunction, AUTH_FAILURE_GRACE_PERIOD);
+  }
+}
+
+// ========================================================================================
+// RESULT TYPES FOR CLIENT CONSUMPTION
+// ========================================================================================
+
+/**
+ * SUCCESSFUL API CALL RESULT
+ * This is what gets returned to the calling code for successful operations
+ */
+export interface ApiSuccessResult<TData> {
+  /** Always true for success */
+  success: true;
+  /** The actual data - NO NESTING! Direct access! */
+  data: TData;
+  /** Human-readable success message from API */
+  message: string;
+  /** Operation code for tracking/debugging */
+  operation_code: string;
+  /** Server timestamp (if provided) */
+  timestamp?: string;
+}
+
+/**
+ * SUCCESSFUL PAGED API CALL RESULT
+ * This is what gets returned for successful paged operations
+ */
+export interface ApiPagedResult<TData> {
+  /** Always true for success */
+  success: true;
+  /** The actual data array - NO NESTING! Direct access! */
+  items: TData[];
+  /** Human-readable success message from API */
+  message: string;
+  /** Operation code for tracking/debugging */
+  operation_code: string;
+  /** Pagination information */
+  pagination: {
+    current_page: number;
+    total_pages: number;
+    page_size: number;
+    total_items: number;
+    has_next_page: boolean;
+    has_previous_page: boolean;
+  };
+  /** Server timestamp (if provided) */
+  timestamp?: string;
+}
+
+/**
+ * FAILED API CALL RESULT
+ * This is what gets returned to the calling code for failed operations
+ */
+export interface ApiErrorResult {
+  /** Always false for errors */
+  success: false;
+  /** Standardized error code */
+  error_code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Operation that failed */
+  operation: string;
+  /** Additional error details (if any) */
+  details?: unknown;
+  /** Validation errors (if any) */
+  validation_errors?: Record<string, string[]>;
+  /** Server-provided request identifier for tracing (only set on real errors) */
+  request_id?: string;
+}
+
+/** UNION TYPE FOR ALL POSSIBLE API RESULTS */
+export type ApiResult<TData> = ApiSuccessResult<TData> | ApiPagedResult<TData> | ApiErrorResult;
+
+// ========================================================================================
+// BULLETPROOF CLIENT API SERVICE
+// ========================================================================================
+
+class StandardizedClientApiService {
+  private baseUrl: string;
+
+  constructor() {
+    this.baseUrl = '';
+  }
+
+  /**
+   * MAKES HTTP REQUEST AND VALIDATES RESPONSE FORMAT
+   * This method ENFORCES standardized response format compliance
+   * Will throw ApiResponseFormatError if format is invalid
+   */
+  private async makeRequest<TData = unknown>(
+    endpoint: string,
+    options: RequestInit = {},
+    sessionToken?: string
+  ): Promise<ApiResult<TData>> {
+    const fullEndpoint = `${this.baseUrl}${endpoint}`;
+    
+    try {
+      // Use provided token or get from NextAuth session
+      const currentSession = await getSession();
+      let token = sessionToken || currentSession?.accessToken;
+
+      // Preflight freshness check: if token is near expiry, coordinate refresh BEFORE making request
+      const pre2FA = isPreTwoFactorSession(currentSession);
+      const hasRefresh = !!currentSession?.refreshToken;
+      if (!pre2FA && hasRefresh) {
+        try {
+          let timeLeft: number | null = null;
+          if (currentSession?.accessTokenExpires) {
+            timeLeft = currentSession.accessTokenExpires - Date.now();
+          } else if (token) {
+            // Fallback decode only if session did not include expiry
+            const { jwtDecode } = await import('./jwt-decode-client');
+            const decoded: any = jwtDecode(token);
+            const expMs = decoded?.exp ? decoded.exp * 1000 : 0;
+            timeLeft = expMs - Date.now();
+          }
+          // Refresh if <= 60s remaining (or already expired)
+          if (timeLeft !== null && !Number.isNaN(timeLeft) && timeLeft <= 60000) {
+            console.log(`⏳ Access token expiring soon (${Math.floor(timeLeft/1000)}s). Coordinating refresh before request...`);
+            if (!refreshInFlight) {
+              refreshInFlight = (async () => {
+                const reqId = crypto.randomUUID();
+                const rr = await fetch('/api/auth/refresh', {
+                  method: 'POST',
+                  credentials: 'include',
+                  headers: { 'X-Request-ID': reqId },
+                });
+                if (rr.ok || rr.status === 409) {
+                  // ok or in-progress; give it a beat in case of 409
+                  if (rr.status === 409) await new Promise(r => setTimeout(r, 1200));
+                  return true;
+                }
+                if (rr.status === 401 || rr.status === 403) {
+                  scheduleLoginRedirect();
+                  throw new ApiNetworkError('Authentication failed - unable to refresh session', rr.status, endpoint);
+                }
+                const et = await rr.text();
+                throw new ApiNetworkError(et || 'Token refresh failed', rr.status, endpoint);
+              })().finally(() => { refreshInFlight = null; });
+            }
+            await refreshInFlight;
+            const newSessionAfter = await getSession();
+            token = newSessionAfter?.accessToken || token;
+          }
+        } catch (preErr) {
+          console.warn('Preflight token freshness check failed (continuing to attempt request):', preErr);
+        }
+      } else {
+        // Elegantly skip preflight refresh in pre-2FA window or when no refresh token exists
+        if (pre2FA) {
+          console.log('⏭️ Skipping preflight refresh: 2FA not complete (no refresh allowed yet)');
+        } else if (!hasRefresh) {
+          console.log('⏭️ Skipping preflight refresh: no refresh token present');
+        }
+      }
+
+      const config: RequestInit = {
+        ...options,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(token && { 'Authorization': `Bearer ${token}` }),
+          ...options.headers,
+        },
+      };
+
+      console.log(`🔄 API Request: ${options.method || 'GET'} ${fullEndpoint}`);
+
+      const response = await fetch(fullEndpoint, config);
+      
+      if (!response.ok) {
+        // Handle coordination blocking (503) with auto-retry
+        if (response.status === 503) {
+          console.log('🔄 Got 503 Service Unavailable, attempting auto-retry for coordination...');
+          
+          // Parse Retry-After header (in seconds)
+          const retryAfterHeader = response.headers.get('Retry-After');
+          let retryAfterSeconds = 1; // Default to 1 second
+          
+          if (retryAfterHeader && /^\d+$/.test(retryAfterHeader)) {
+            retryAfterSeconds = parseInt(retryAfterHeader, 10);
+          }
+          
+          const baseDelayMs = retryAfterSeconds * 1000;
+          const maxRetries = 3;
+          
+          for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            // Add jitter to prevent thundering herd
+            const jitterMs = Math.floor(Math.random() * 300) - 150; // ±150ms jitter
+            const exponentialBackoff = Math.pow(1.5, attempt - 1); // Mild exponential backoff
+            const delayMs = Math.max(100, baseDelayMs * exponentialBackoff + jitterMs);
+            
+            console.log(`🔄 503 retry attempt ${attempt}/${maxRetries}, waiting ${delayMs}ms...`);
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+            
+            try {
+              const retryResponse = await fetch(fullEndpoint, config);
+              
+              if (retryResponse.ok) {
+                console.log(`✅ 503 retry attempt ${attempt} succeeded`);
+                const rawData = await retryResponse.json();
+                resetAuthFailureState();
+                
+                // COMPATIBILITY MODE: Handle both formats
+                if (rawData && typeof rawData === 'object' && 'success' in rawData) {
+                  const validatedResponse = validateStandardizedResponse<TData>(rawData, endpoint);
+                  return this.convertToApiResult(validatedResponse);
+                } else {
+                  // New format - raw data
+                  const wrappedResponse: ApiSuccessResult<TData> = {
+                    success: true,
+                    data: rawData as TData,
+                    message: 'Success',
+                    operation_code: 'RAW_RESPONSE',
+                    timestamp: new Date().toISOString()
+                  };
+                  return wrappedResponse;
+                }
+              }
+              
+              // If we get another 503, continue retrying
+              if (retryResponse.status === 503) {
+                console.log(`🔄 503 retry attempt ${attempt} got another 503, will retry...`);
+                continue;
+              }
+              
+              // If we get a different error, break and handle it normally
+              console.log(`❌ 503 retry attempt ${attempt} got ${retryResponse.status}, stopping retries`);
+              // Fall through to handle the retry response error
+              const errorText = await retryResponse.text();
+              let errorData;
+              try {
+                errorData = JSON.parse(errorText);
+                if (errorData && typeof errorData === 'object' && 'success' in errorData) {
+                  // Detect PayEz canonical error envelope and map accordingly
+                  if (errorData.error && typeof errorData.error === 'object') {
+                    const reqIdHeader = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+                    const reqIdBody = errorData?.request_id || errorData?.requestId;
+                    const errorResult: ApiErrorResult = {
+                      success: false,
+                      error_code: errorData?.error?.code || errorData?.error_code || errorData?.code || `HTTP_${retryResponse.status}`,
+                      message: errorData?.error?.message || errorData?.message || `Request failed with status ${retryResponse.status}`,
+                      operation: endpoint,
+                      details: (errorData?.error?.details ?? errorData?.details) || undefined,
+                      ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+                    };
+                    return errorResult;
+                  }
+                  // Otherwise attempt to validate as our standardized error shape
+                  const validatedError = validateStandardizedResponse(errorData, endpoint);
+                  return this.convertToApiResult(validatedError) as ApiResult<TData>;
+                } else {
+                  // New/unknown error format - best-effort mapping
+                  const reqIdHeader = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+                  const reqIdBody = errorData?.request_id || errorData?.requestId;
+                  const errorResult: ApiErrorResult = {
+                    success: false,
+                    error_code: errorData?.error_code || errorData?.code || `HTTP_${retryResponse.status}`,
+                    message: errorData?.message || (typeof errorData?.error === 'string' ? errorData.error : errorData?.error?.message) || errorText || `Request failed with status ${retryResponse.status}`,
+                    operation: endpoint,
+                    details: (errorData?.error?.details ?? errorData?.details) || undefined,
+                    ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+                  };
+                  return errorResult;
+                }
+              } catch {
+                const reqIdHeader2 = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+                const errorResult: ApiErrorResult = {
+                  success: false,
+                  error_code: `HTTP_${retryResponse.status}`,
+                  message: errorText || `Request failed with status ${retryResponse.status}`,
+                  operation: endpoint,
+                  ...(reqIdHeader2 ? { request_id: reqIdHeader2 } : {})
+                };
+                return errorResult;
+              }
+              
+            } catch (retryError) {
+              console.log(`❌ 503 retry attempt ${attempt} failed with network error:`, retryError);
+              if (attempt === maxRetries) {
+                // If all retries failed with network errors, throw the original error
+                throw new ApiNetworkError('Service temporarily unavailable after retries', 503, endpoint);
+              }
+              continue;
+            }
+          }
+          
+          // If we got here, all retries failed - fall through to normal error handling
+          console.log('❌ All 503 retry attempts exhausted, treating as error');
+        }
+        
+        // Handle authentication errors with a single refresh+retry
+        if (response.status === 401) {
+          console.log('🔑 Got 401, checking if we have a session to refresh...');
+          
+          // CRITICAL FIX: Check if we actually have a session before attempting refresh
+          const currentSession = await getSession();
+          if (!currentSession || !currentSession.accessToken) {
+            console.log('🚫 No valid session found, redirecting to login instead of refresh');
+            scheduleLoginRedirect(true); // Immediate redirect
+            throw new ApiNetworkError('Authentication required - no valid session', 401, endpoint);
+          }
+
+          // Elegantly gate refresh during pre-2FA or when no refresh token exists
+          const pre2FA_now = isPreTwoFactorSession(currentSession);
+          const hasRefresh_now = !!currentSession?.refreshToken;
+          if (pre2FA_now || !hasRefresh_now) {
+            console.log('⏭️ Skipping 401-driven refresh:', {
+              reason: pre2FA_now ? 'pre-2FA session' : 'no refresh token',
+              requiresTwoFactor: (currentSession?.user as any)?.requiresTwoFactor,
+              twoFactorVerified: (currentSession?.user as any)?.twoFactorSessionVerified,
+              hasRefreshToken: hasRefresh_now
+            });
+            // CRITICAL: Redirect to login immediately if refresh is impossible
+            console.log('🚫 Cannot refresh session, redirecting to login');
+            scheduleLoginRedirect(true); // Immediate redirect
+            throw new ApiNetworkError(
+              pre2FA_now
+                ? 'Two-factor authentication required'
+                : 'Session expired - refresh token unavailable',
+              401,
+              endpoint
+            );
+          }
+          
+          console.log('🔑 Valid session found, attempting token refresh...');
+          
+          // Try to refresh the token, but coordinate to avoid double refresh
+          if (!refreshInFlight) {
+            refreshInFlight = (async () => {
+              const reqId = crypto.randomUUID();
+              const refreshResponse = await fetch('/api/auth/refresh', {
+                method: 'POST',
+                credentials: 'include',
+                headers: { 'X-Request-ID': reqId },
+              });
+
+              if (refreshResponse.ok) {
+                console.log('✅ Token refreshed successfully (client-side coordinator)');
+                return true;
+              }
+
+              // If refresh is already in progress server-side, wait briefly and allow retry
+              if (refreshResponse.status === 409) {
+                console.log('↪️ Refresh in progress server-side (409). Waiting for completion...');
+                await new Promise(r => setTimeout(r, 1500));
+                return true;
+              }
+
+              // For auth failures, schedule redirect; for others, throw
+              if (refreshResponse.status === 401 || refreshResponse.status === 403) {
+                scheduleLoginRedirect();
+                throw new ApiNetworkError('Authentication failed - unable to refresh session', refreshResponse.status, endpoint);
+              }
+
+              const errorText = await refreshResponse.text();
+              throw new ApiNetworkError(errorText || 'Token refresh failed', refreshResponse.status, endpoint);
+            })().finally(() => { refreshInFlight = null; });
+          }
+
+          try {
+            await refreshInFlight;
+          } catch (e) {
+            throw e; // bubble up to caller handling
+          }
+
+          console.log('🔁 Retrying original request after coordinated refresh...');
+          // Get the new session and retry the original request
+          const newSession = await getSession();
+          const newToken = newSession?.accessToken;
+          const retryConfig: RequestInit = {
+            ...options,
+            headers: {
+              'Content-Type': 'application/json',
+              ...(newToken && { 'Authorization': `Bearer ${newToken}` }),
+              ...options.headers,
+            },
+          };
+          
+          const retryResponse = await fetch(fullEndpoint, retryConfig);
+          
+          if (retryResponse.ok) {
+            const rawData = await retryResponse.json();
+            // Reset auth failure state on successful retry
+            resetAuthFailureState();
+            
+            // COMPATIBILITY MODE: Handle both formats in retry as well
+            if (rawData && typeof rawData === 'object' && 'success' in rawData) {
+              const validatedResponse = validateStandardizedResponse<TData>(rawData, endpoint);
+              return this.convertToApiResult(validatedResponse);
+            } else {
+              // New format - raw data
+              console.log(`🔄 Converting raw retry response to standardized format for ${endpoint}`);
+              const wrappedResponse: ApiSuccessResult<TData> = {
+                success: true,
+                data: rawData as TData,
+                message: 'Success',
+                operation_code: 'RAW_RESPONSE',
+                timestamp: new Date().toISOString()
+              };
+              return wrappedResponse;
+            }
+          } else {
+            // If retry still 401, schedule redirect
+            if (retryResponse.status === 401) {
+              scheduleLoginRedirect();
+            }
+            
+            const errorText = await retryResponse.text();
+            let errorData;
+            try {
+              errorData = JSON.parse(errorText);
+              // Check if it has the success field (old format)
+              if (errorData && typeof errorData === 'object' && 'success' in errorData) {
+                // Detect PayEz canonical error envelope and map accordingly
+                if (errorData.error && typeof errorData.error === 'object') {
+                  const reqIdHeader = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+                  const reqIdBody = errorData?.request_id || errorData?.requestId;
+                  const errorResult: ApiErrorResult = {
+                    success: false,
+                    error_code: errorData?.error?.code || errorData?.error_code || errorData?.code || `HTTP_${retryResponse.status}`,
+                    message: errorData?.error?.message || errorData?.message || `Request failed with status ${retryResponse.status}`,
+                    operation: endpoint,
+                    details: (errorData?.error?.details ?? errorData?.details) || undefined,
+                    ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+                  };
+                  return errorResult;
+                }
+                const validatedError = validateStandardizedResponse(errorData, endpoint);
+                return this.convertToApiResult(validatedError) as ApiResult<TData>;
+              } else {
+                // New format - convert raw error to standardized format
+                const reqIdHeader = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+                const reqIdBody = errorData?.request_id || errorData?.requestId;
+                const errorResult: ApiErrorResult = {
+                  success: false,
+                  error_code: errorData?.error_code || errorData?.code || `HTTP_${retryResponse.status}`,
+                  message: errorData?.message || (typeof errorData?.error === 'string' ? errorData.error : errorData?.error?.message) || errorText || `Request failed with status ${retryResponse.status}`,
+                  operation: endpoint,
+                  details: (errorData?.error?.details ?? errorData?.details) || undefined,
+                  ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+                };
+                return errorResult;
+              }
+            } catch {
+              // If we can't parse the error, create a generic error response
+              const reqIdHeader = retryResponse.headers.get('X-Request-ID') || retryResponse.headers.get('X-Correlation-ID');
+              const errorResult: ApiErrorResult = {
+                success: false,
+                error_code: `HTTP_${retryResponse.status}`,
+                message: errorText || `Request failed with status ${retryResponse.status}`,
+                operation: endpoint,
+                ...(reqIdHeader ? { request_id: reqIdHeader } : {})
+              };
+              return errorResult;
+            }
+          }
+        }
+        
+        // Non-401 error: try to parse as standardized error response
+        const errorText = await response.text();
+        let errorData;
+        try {
+          errorData = JSON.parse(errorText);
+          // Check if it has the success field (old format)
+          if (errorData && typeof errorData === 'object' && 'success' in errorData) {
+            // Detect PayEz canonical error envelope and map accordingly
+            if (errorData.error && typeof errorData.error === 'object') {
+              const reqIdHeader = response.headers.get('X-Request-ID') || response.headers.get('X-Correlation-ID');
+              const reqIdBody = errorData?.request_id || errorData?.requestId;
+              const errorResult: ApiErrorResult = {
+                success: false,
+                error_code: errorData?.error?.code || errorData?.error_code || errorData?.code || `HTTP_${response.status}`,
+                message: errorData?.error?.message || errorData?.message || `Request failed with status ${response.status}`,
+                operation: endpoint,
+                details: (errorData?.error?.details ?? errorData?.details) || undefined,
+                validation_errors: errorData?.validation_errors || undefined,
+                ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+              };
+              return errorResult;
+            }
+            const validatedError = validateStandardizedResponse(errorData, endpoint);
+            return this.convertToApiResult(validatedError) as ApiResult<TData>;
+          } else {
+            // New format - convert raw error to standardized format
+            const reqIdHeader = response.headers.get('X-Request-ID') || response.headers.get('X-Correlation-ID');
+            const reqIdBody = errorData?.request_id || errorData?.requestId;
+            const errorResult: ApiErrorResult = {
+              success: false,
+              error_code: errorData?.error_code || errorData?.code || `HTTP_${response.status}`,
+              message: errorData?.message || (typeof errorData?.error === 'string' ? errorData.error : errorData?.error?.message) || errorText || `Request failed with status ${response.status}`,
+              operation: endpoint,
+              details: (errorData?.error?.details ?? errorData?.details) || undefined,
+              validation_errors: errorData?.validation_errors || undefined,
+              ...(reqIdBody || reqIdHeader ? { request_id: (reqIdBody || reqIdHeader) as string } : {})
+            };
+            return errorResult;
+          }
+        } catch (parseError) {
+          // If we can't parse the error, create a generic error response
+          const reqIdHeader = response.headers.get('X-Request-ID') || response.headers.get('X-Correlation-ID');
+          const errorResult: ApiErrorResult = {
+            success: false,
+            error_code: `HTTP_${response.status}`,
+            message: errorText || `Request failed with status ${response.status}`,
+            operation: endpoint,
+            details: undefined,
+            ...(reqIdHeader ? { request_id: reqIdHeader } : {})
+          };
+          return errorResult;
+        }
+      }
+
+      // SUCCESS PATH: Parse and validate response
+      const rawData = await response.json();
+      
+      // Reset auth failure state on successful request
+      resetAuthFailureState();
+      
+      // COMPATIBILITY MODE: Handle both old envelope format and new raw format
+      try {
+        // First check if it's the old standardized format with success field
+        if (rawData && typeof rawData === 'object' && 'success' in rawData) {
+          // Old format - validate as standardized response
+          const validatedResponse = validateStandardizedResponse<TData>(rawData, endpoint);
+          return this.convertToApiResult(validatedResponse);
+        } else {
+          // New format - raw data, wrap it in success envelope for compatibility
+          console.log(`🔄 Converting raw response to standardized format for ${endpoint}`);
+          const wrappedResponse: ApiSuccessResult<TData> = {
+            success: true,
+            data: rawData as TData,
+            message: 'Success',
+            operation_code: 'RAW_RESPONSE',
+            timestamp: new Date().toISOString()
+          };
+          return wrappedResponse;
+        }
+      } catch (validationError) {
+        // If response format is invalid, this is a CRITICAL error
+        throw new ApiResponseFormatError(
+          validationError instanceof Error ? validationError.message : 'Response format validation failed',
+          endpoint,
+          rawData
+        );
+      }
+
+    } catch (error) {
+      // Re-throw our custom errors as-is
+      if (error instanceof ApiResponseFormatError || 
+          error instanceof ApiBusinessLogicError || 
+          error instanceof ApiValidationError ||
+          error instanceof ApiNetworkError) {
+        throw error;
+      }
+      
+      // Wrap unknown errors as network errors
+      console.error('❌ API request failed:', error);
+      throw new ApiNetworkError(
+        error instanceof Error ? error.message : 'Network error',
+        0,
+        endpoint
+      );
+    }
+  }
+
+  /**
+   * CONVERTS VALIDATED STANDARDIZED RESPONSE TO CLIENT RESULT
+   * This normalizes the response for client consumption
+   */
+  private convertToApiResult<TData>(validatedResponse: StandardizedResponse<any>): ApiResult<TData> {
+    if (isSuccessResponse(validatedResponse)) {
+      return {
+        success: true,
+        data: validatedResponse.data as TData,
+        message: validatedResponse.message,
+        operation_code: validatedResponse.operation_code,
+        timestamp: validatedResponse.timestamp
+      } as ApiSuccessResult<TData>;
+    }
+    
+    if (isPagedResponse(validatedResponse)) {
+      return {
+        success: true,
+        items: validatedResponse.data as TData[],
+        message: validatedResponse.message,
+        operation_code: validatedResponse.operation_code,
+        pagination: validatedResponse.pagination,
+        timestamp: validatedResponse.timestamp
+      } as ApiPagedResult<TData>;
+    }
+    
+    if (isErrorResponse(validatedResponse)) {
+      const reqId = (validatedResponse as any)?.request_id || (validatedResponse as any)?.requestId;
+      if (validatedResponse.error_code === 'VALIDATION_ERROR') {
+        // Handle validation error
+        const valError = validatedResponse as any;
+        return {
+          success: false,
+          error_code: validatedResponse.error_code,
+          message: validatedResponse.message,
+          operation: validatedResponse.operation,
+          details: validatedResponse.details,
+          validation_errors: valError.payload?.validation_errors,
+          ...(reqId ? { request_id: reqId } : {})
+        } as ApiErrorResult;
+      } else {
+        // Handle regular error
+        return {
+          success: false,
+          error_code: validatedResponse.error_code,
+          message: validatedResponse.message,
+          operation: validatedResponse.operation,
+          details: validatedResponse.details,
+          ...(reqId ? { request_id: reqId } : {})
+        } as ApiErrorResult;
+      }
+    }
+    
+    // This should never happen due to validation, but TypeScript requires it
+    throw new ApiResponseFormatError('Unknown response type after validation', 'unknown', validatedResponse);
+  }
+
+  // ========================================================================================
+  // HTTP METHOD WRAPPERS - PUBLIC API
+  // ========================================================================================
+
+  /**
+   * GET REQUEST - Returns typed result with direct data access
+   */
+  async get<TData = unknown>(endpoint: string, sessionToken?: string): Promise<ApiResult<TData>> {
+    return this.makeRequest<TData>(endpoint, { method: 'GET' }, sessionToken);
+  }
+
+  /**
+   * POST REQUEST - Returns typed result with direct data access
+   */
+  async post<TData = unknown>(endpoint: string, data?: unknown, sessionToken?: string): Promise<ApiResult<TData>> {
+    return this.makeRequest<TData>(endpoint, {
+      method: 'POST',
+      body: data ? JSON.stringify(data) : undefined,
+    }, sessionToken);
+  }
+
+  /**
+   * PUT REQUEST - Returns typed result with direct data access
+   */
+  async put<TData = unknown>(endpoint: string, data?: unknown, sessionToken?: string): Promise<ApiResult<TData>> {
+    return this.makeRequest<TData>(endpoint, {
+      method: 'PUT',
+      body: data ? JSON.stringify(data) : undefined,
+    }, sessionToken);
+  }
+
+  /**
+   * DELETE REQUEST - Returns typed result with direct data access
+   */
+  async delete<TData = unknown>(endpoint: string): Promise<ApiResult<TData>> {
+    return this.makeRequest<TData>(endpoint, { method: 'DELETE' });
+  }
+}
+
+// ========================================================================================
+// SINGLETON INSTANCE - READY TO USE
+// ========================================================================================
+
+export const standardizedApi = new StandardizedClientApiService();
+
+// ========================================================================================
+// CONVENIENCE HELPER FUNCTIONS
+// ========================================================================================
+
+/**
+ * TYPE-SAFE SUCCESS CHECK
+ * Use this to check if API call was successful with proper type narrowing
+ */
+export function isApiSuccess<TData>(result: ApiResult<TData>): result is ApiSuccessResult<TData> {
+  return result.success === true && 'data' in result;
+}
+
+/**
+ * TYPE-SAFE PAGED SUCCESS CHECK
+ * Use this to check if API call was successful paged response with proper type narrowing
+ */
+export function isApiPagedSuccess<TData>(result: ApiResult<TData>): result is ApiPagedResult<TData> {
+  return result.success === true && 'items' in result;
+}
+
+/**
+ * TYPE-SAFE ERROR CHECK
+ * Use this to check if API call failed with proper type narrowing
+ */
+export function isApiError<TData>(result: ApiResult<TData>): result is ApiErrorResult {
+  return result.success === false;
+}
+
+/**
+ * EXTRACT DATA FROM SUCCESS RESULT
+ * Use this to get the data from a successful API call
+ * Will throw if result is not successful
+ */
+export function extractApiData<TData>(result: ApiResult<TData>): TData {
+  if (isApiSuccess(result)) {
+    return result.data;
+  }
+  if (isApiPagedSuccess(result)) {
+    return result.items as TData;
+  }
+  throw new ApiBusinessLogicError(
+    result.error_code,
+    result.message,
+    result.operation,
+    result.details
+  );
+}
+
+/**
+ * EXTRACT ITEMS FROM PAGED SUCCESS RESULT
+ * Use this to get the items array from a successful paged API call
+ * Will throw if result is not successful paged response
+ */
+export function extractApiItems<TData>(result: ApiResult<TData>): TData[] {
+  if (isApiPagedSuccess(result)) {
+    return result.items as TData[];
+  }
+  if (isApiSuccess(result)) {
+    // If it's a regular success but expected paged, data should be array
+    return result.data as TData[];
+  }
+  throw new ApiBusinessLogicError(
+    result.error_code,
+    result.message,
+    result.operation,
+    result.details
+  );
+}