@onairos/react-native 3.3.0 → 3.3.2

package/src/services/apiKeyService.ts

@@ -1,922 +1,979 @@
-import type { OnairosConfig, ApiKeyValidationResult } from '../types';
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
-// Admin key for backend validation
-export const ADMIN_API_KEY = 'OnairosIsAUnicorn2025';
-
-// API key types
-export enum ApiKeyType {
-  DEVELOPER = 'developer',
-  ADMIN = 'admin',
-  INVALID = 'invalid'
-}
-
-// JWT token storage key
-const JWT_TOKEN_KEY = 'onairos_jwt_token';
-
-/**
- * Two-Tier Authentication Service for Onairos React Native SDK
- * 
- * This service implements the two-tier authentication system:
- * 1. Developer API Keys: For app-level operations (email verification, app registration)
- * 2. JWT User Tokens: For user-level operations (PIN storage, user profile)
- * 
- * How it works:
- * 1. Initialize with developer API key
- * 2. Use API key for email verification requests
- * 3. Store JWT token from email verification response
- * 4. Use JWT token for user-authenticated requests
- * 5. Handle token expiration gracefully
- * 
- * Backend Integration:
- * - Developer routes: Authorization: Bearer ${API_KEY}
- * - User routes: Authorization: Bearer ${JWT_TOKEN}
- */
-
-// Global configuration state
-let globalConfig: OnairosConfig | null = null;
-let validationCache: Map<string, { result: ApiKeyValidationResult; timestamp: number }> = new Map();
-let isInitialized = false;
-let userToken: string | null = null;
-
-// Cache duration (5 minutes)
-const CACHE_DURATION = 5 * 60 * 1000;
-
-// API endpoints for different environments (updated to standard)
-const API_ENDPOINTS = {
-  production: 'https://api.onairos.uk',
-  staging: 'https://staging-api.onairos.uk', 
-  development: 'https://dev-api.onairos.uk',
-};
-
-/**
- * Initialize the SDK with developer API key
- * @param config API configuration including developer API key
- */
-export const initializeApiKey = async (config: OnairosConfig): Promise<void> => {
-  try {
-    console.log('🔑 Initializing Onairos SDK with developer API key...');
-    
-    if (!config.apiKey) {
-      throw new Error('Developer API key is required for SDK initialization');
-    }
-
-    // Check if it's admin key first (admin key is shorter than 32 chars)
-    if (!isAdminKey(config.apiKey) && config.apiKey.length < 32) {
-      throw new Error('Invalid API key format. Developer keys must be at least 32 characters long.');
-    }
-
-    // Set global configuration
-    globalConfig = {
-      apiKey: config.apiKey,
-      environment: config.environment || 'production',
-      enableLogging: config.enableLogging !== false, // Default to true
-      timeout: config.timeout || 30000,
-      retryAttempts: config.retryAttempts || 3,
-    };
-
-    if (globalConfig.enableLogging) {
-      console.log('📝 SDK Configuration:', {
-        environment: globalConfig.environment,
-        timeout: globalConfig.timeout,
-        retryAttempts: globalConfig.retryAttempts,
-        apiKeyPrefix: config.apiKey.substring(0, 8) + '...',
-        enableLogging: globalConfig.enableLogging,
-      });
-    }
-
-    // Validate the API key (handles both admin and developer keys)
-    const validation = await validateApiKey(config.apiKey);
-    
-    if (!validation.isValid) {
-      // If it's a network error or JSON parse error, warn but don't fail initialization
-      // Use defensive coding to handle cases where validation.error might be undefined
-      const errorMessage = validation.error || '';
-      if (errorMessage.includes('Network error') || 
-          errorMessage.includes('JSON Parse error') || 
-          errorMessage.includes('API validation endpoint returned')) {
-        console.warn('⚠️ API key validation failed due to network/server issues, continuing in offline mode:', validation.error);
-        console.warn('📝 SDK will function with limited validation. Ensure your API key is valid for production use.');
-      } else {
-        throw new Error(`API key validation failed: ${validation.error}`);
-      }
-    }
-
-    // Try to load existing JWT token
-    await loadJWT();
-
-    isInitialized = true;
-    
-    if (globalConfig.enableLogging) {
-      console.log('✅ Onairos SDK initialized successfully');
-      
-      if (isAdminKey(config.apiKey)) {
-        console.log('🔑 Admin API key ready with full permissions');
-      } else {
-        console.log('🔑 Developer API key ready for app-level operations');
-      }
-      
-      if (userToken) {
-        console.log('🎫 User JWT token loaded from storage');
-      }
-      if (validation.permissions) {
-        console.log('🔐 API Key Permissions:', validation.permissions);
-      }
-      if (validation.rateLimits) {
-        console.log('⏱️ Rate Limits:', validation.rateLimits);
-      }
-    }
-  } catch (error) {
-    console.error('❌ Failed to initialize Onairos SDK:', error);
-    isInitialized = false;
-    throw error;
-  }
-};
-
-/**
- * Determine API key type
- * @param apiKey The API key to check
- * @returns The type of API key
- */
-export const getApiKeyType = (apiKey: string): ApiKeyType => {
-  if (apiKey === ADMIN_API_KEY) {
-    return ApiKeyType.ADMIN;
-  }
-  
-  // Developer keys should be at least 32 characters and start with specific prefix
-  if (apiKey.length >= 32 && (apiKey.startsWith('dev_') || apiKey.startsWith('pk_') || apiKey.startsWith('ona_'))) {
-    return ApiKeyType.DEVELOPER;
-  }
-  
-  return ApiKeyType.INVALID;
-};
-
-/**
- * Check if API key is admin key
- * @param apiKey The API key to check
- * @returns True if admin key
- */
-export const isAdminKey = (apiKey: string): boolean => {
-  return apiKey === ADMIN_API_KEY;
-};
-
-/**
- * Validate an API key with the Onairos backend
- * @param apiKey The API key to validate
- * @returns Validation result with permissions and rate limits
- */
-export const validateApiKey = async (apiKey: string): Promise<ApiKeyValidationResult> => {
-  try {
-    console.log('🔍 Validating API key...');
-    
-    // Check if it's an admin key
-    if (isAdminKey(apiKey)) {
-      console.log('🔑 Admin key detected - granting full permissions');
-      return {
-        isValid: true,
-        permissions: ['*'], // Full permissions for admin
-        rateLimits: {
-          remaining: 999999,
-          resetTime: Date.now() + 24 * 60 * 60 * 1000 // 24 hours
-        },
-        keyType: ApiKeyType.ADMIN
-      };
-    }
-    
-    // Check basic format for developer keys
-    const keyType = getApiKeyType(apiKey);
-    if (keyType === ApiKeyType.INVALID) {
-      return {
-        isValid: false,
-        error: 'Invalid API key format. Developer keys must be at least 32 characters and start with "dev_", "pk_", or "ona_"',
-        keyType: ApiKeyType.INVALID
-      };
-    }
-    
-    // Check cache first
-    const cached = validationCache.get(apiKey);
-    if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
-      if (globalConfig?.enableLogging) {
-        console.log('📋 Using cached API key validation result');
-      }
-      return cached.result;
-    }
-
-    const environment = globalConfig?.environment || 'production';
-    const baseUrl = API_ENDPOINTS[environment];
-    const timeout = globalConfig?.timeout || 30000;
-    const maxRetries = globalConfig?.retryAttempts || 3;
-
-    // Retry logic for network failures
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-      // Create abort controller for timeout
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), timeout);
-
-      try {
-        if (globalConfig?.enableLogging && attempt > 1) {
-          console.log(`🔄 Retry attempt ${attempt}/${maxRetries} for API key validation`);
-        }
-
-        const response = await fetch(`${baseUrl}/auth/validate-key`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${apiKey}`,
-            'User-Agent': 'OnairosReactNative/3.2.1',
-            'X-API-Key-Type': keyType,
-            'X-SDK-Platform': 'react-native',
-            'X-Retry-Attempt': attempt.toString(),
-          },
-          body: JSON.stringify({
-            environment,
-            sdk_version: '3.2.1',
-            platform: 'react-native',
-            keyType,
-            timestamp: new Date().toISOString(),
-            attempt,
-          }),
-          signal: controller.signal,
-        });
-
-        clearTimeout(timeoutId);
-
-        // First check if we got a valid response
-        if (!response) {
-          throw new Error('No response received from server');
-        }
-
-        // Check if response is actually JSON before trying to parse
-        const contentType = response.headers.get('content-type');
-        const isJsonResponse = contentType && contentType.includes('application/json');
-        
-        if (!isJsonResponse) {
-          const textContent = await response.text();
-          const previewText = textContent.substring(0, 200);
-          
-          console.error('❌ API endpoint returned non-JSON response:', {
-            status: response.status,
-            statusText: response.statusText,
-            contentType: contentType || 'unknown',
-            preview: previewText,
-            url: `${baseUrl}/auth/validate-key`,
-            attempt: attempt
-          });
-          
-          // Handle specific error cases
-          if (response.status === 404) {
-            throw new Error(`API validation endpoint not found (404). The endpoint ${baseUrl}/auth/validate-key may not exist or be configured correctly.`);
-          } else if (response.status === 500) {
-            throw new Error(`Server error (500). The Onairos backend is experiencing issues.`);
-          } else if (response.status === 502 || response.status === 503) {
-            throw new Error(`Service unavailable (${response.status}). The Onairos backend may be temporarily down.`);
-          } else if (textContent.includes('<html') || textContent.includes('<!DOCTYPE')) {
-            throw new Error(`Server returned HTML page instead of JSON API response. This often indicates a routing issue or server misconfiguration.`);
-          } else {
-            throw new Error(`API validation endpoint returned ${response.status} - ${response.statusText}. Expected JSON but got ${contentType || 'unknown content type'}.`);
-          }
-        }
-
-        // Parse JSON response
-        let data;
-        try {
-          data = await response.json();
-        } catch (jsonError) {
-          console.error('❌ Failed to parse JSON response:', {
-            error: jsonError.message,
-            status: response.status,
-            contentType,
-            attempt: attempt
-          });
-          throw new Error(`Failed to parse server response as JSON: ${jsonError.message}`);
-        }
-
-        // Handle successful response
-        if (response.ok && data.success) {
-          const result: ApiKeyValidationResult = {
-            isValid: true,
-            permissions: data.permissions || [],
-            rateLimits: data.rateLimits || null,
-            keyType: keyType,
-          };
-
-          // Cache the successful result
-          validationCache.set(apiKey, {
-            result,
-            timestamp: Date.now(),
-          });
-
-          if (globalConfig?.enableLogging) {
-            console.log('✅ API key validation successful');
-          }
-
-          return result;
-        } else {
-          // Handle API errors (invalid key, etc.)
-          const errorMessage = data.error || data.message || `HTTP ${response.status}: ${response.statusText}`;
-          
-          const result: ApiKeyValidationResult = {
-            isValid: false,
-            error: errorMessage,
-            keyType: keyType,
-          };
-
-          // For client errors (4xx), don't retry
-          if (response.status >= 400 && response.status < 500) {
-            if (globalConfig?.enableLogging) {
-              console.error('❌ API key validation failed (client error):', errorMessage);
-            }
-            return result;
-          }
-
-          // For server errors (5xx), retry
-          throw new Error(errorMessage);
-        }
-
-      } catch (fetchError: any) {
-        clearTimeout(timeoutId);
-        
-        if (fetchError.name === 'AbortError') {
-          const errorMessage = `API key validation timeout (${timeout}ms)`;
-          console.error('⏱️ API key validation timeout');
-          
-          if (attempt === maxRetries) {
-            return { isValid: false, error: errorMessage, keyType: keyType };
-          }
-          continue; // Retry timeout errors
-        }
-        
-        // Enhanced error message based on error type
-        let errorMessage = `Network error during API key validation: ${fetchError.message}`;
-        
-        // Add specific guidance for common errors
-        if (fetchError.message.includes('JSON Parse error') || fetchError.message.includes('Unexpected character')) {
-          errorMessage = `Server returned invalid JSON response. This usually indicates the API endpoint returned HTML instead of JSON (often a 404 or server error page). ${fetchError.message}`;
-        } else if (fetchError.message.includes('Network request failed') || fetchError.message.includes('fetch')) {
-          errorMessage = `Network connectivity issue. Please check internet connection and verify the Onairos API is accessible. ${fetchError.message}`;
-        } else if (fetchError.message.includes('DNS') || fetchError.message.includes('ENOTFOUND')) {
-          errorMessage = `DNS resolution failed for ${baseUrl}. Please check network settings and domain accessibility. ${fetchError.message}`;
-        }
-        
-        console.error('🌐 Network error during API key validation:', {
-          error: fetchError,
-          endpoint: `${baseUrl}/auth/validate-key`,
-          attempt: attempt,
-          maxRetries: maxRetries,
-          retryable: attempt < maxRetries
-        });
-
-        // If this is the last attempt, return the error
-        if (attempt === maxRetries) {
-          return { 
-            isValid: false, 
-            error: errorMessage, 
-            keyType: keyType 
-          };
-        }
-
-                 // Wait before retrying (exponential backoff)
-         const backoffDelay = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
-         if (globalConfig?.enableLogging) {
-           console.log(`⏳ Waiting ${backoffDelay}ms before retry...`);
-         }
-         await new Promise<void>(resolve => setTimeout(() => resolve(), backoffDelay));
-      }
-    }
-
-    // This should never be reached, but just in case
-    return { 
-      isValid: false, 
-      error: 'All retry attempts exhausted', 
-      keyType: keyType 
-    };
-
-  } catch (error: any) {
-    const errorMessage = `API key validation error: ${error.message}`;
-    console.error('❌ API key validation error:', error);
-    return { isValid: false, error: errorMessage, keyType: ApiKeyType.INVALID };
-  }
-};
-
-/**
- * Get the current API configuration
- * @returns Current API configuration or null if not initialized
- */
-export const getApiConfig = (): OnairosConfig | null => {
-  return globalConfig;
-};
-
-/**
- * Get the current API key
- * @returns Current API key or null if not initialized
- */
-export const getApiKey = (): string | null => {
-  return globalConfig?.apiKey || null;
-};
-
-/**
- * Check if the SDK is properly initialized
- * @returns True if initialized with valid API key
- */
-export const isApiKeyInitialized = (): boolean => {
-  return isInitialized && globalConfig !== null;
-};
-
-/**
- * Store JWT token securely after email verification
- * @param token JWT token from email verification response
- */
-export const storeJWT = async (token: string): Promise<void> => {
-  try {
-    await AsyncStorage.setItem(JWT_TOKEN_KEY, token);
-    userToken = token;
-    
-    if (globalConfig?.enableLogging) {
-      console.log('🎫 JWT token stored successfully');
-    }
-  } catch (error) {
-    console.error('❌ Failed to store JWT token:', error);
-    throw error;
-  }
-};
-
-/**
- * Load JWT token from storage
- * @returns JWT token or null if not found
- */
-export const loadJWT = async (): Promise<string | null> => {
-  try {
-    const token = await AsyncStorage.getItem(JWT_TOKEN_KEY);
-    userToken = token;
-    return token;
-  } catch (error) {
-    console.error('❌ Failed to load JWT token:', error);
-    return null;
-  }
-};
-
-/**
- * Get current JWT token
- * @returns JWT token or null if not available
- */
-export const getJWT = (): string | null => {
-  return userToken;
-};
-
-/**
- * Clear JWT token (on logout or token expiration)
- */
-export const clearJWT = async (): Promise<void> => {
-  try {
-    await AsyncStorage.removeItem(JWT_TOKEN_KEY);
-    userToken = null;
-    
-    if (globalConfig?.enableLogging) {
-      console.log('🗑️ JWT token cleared');
-    }
-  } catch (error) {
-    console.error('❌ Failed to clear JWT token:', error);
-  }
-};
-
-/**
- * React Native compatible base64 decoder
- * @param str Base64 encoded string
- * @returns Decoded string
- */
-const base64Decode = (str: string): string => {
-  // Simple base64 decoding for React Native
-  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-  let result = '';
-  let i = 0;
-  
-  str = str.replace(/[^A-Za-z0-9+/]/g, '');
-  
-  while (i < str.length) {
-    const a = chars.indexOf(str.charAt(i++));
-    const b = chars.indexOf(str.charAt(i++));
-    const c = chars.indexOf(str.charAt(i++));
-    const d = chars.indexOf(str.charAt(i++));
-    
-    const bitmap = (a << 18) | (b << 12) | (c << 6) | d;
-    
-    result += String.fromCharCode((bitmap >> 16) & 255);
-    if (c !== 64) result += String.fromCharCode((bitmap >> 8) & 255);
-    if (d !== 64) result += String.fromCharCode(bitmap & 255);
-  }
-  
-  return result;
-};
-
-/**
- * Decode JWT token payload (React Native compatible)
- * @param token JWT token string
- * @returns Decoded payload or null if invalid
- */
-export const decodeJWTPayload = (token: string): any => {
-  try {
-    // Split JWT token (header.payload.signature)
-    const parts = token.split('.');
-    if (parts.length !== 3) {
-      console.error('❌ Invalid JWT token format');
-      return null;
-    }
-
-    // Decode payload (base64url to base64)
-    const payload = parts[1];
-    const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
-    
-    // Add padding if needed
-    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
-    
-    // Decode base64 to JSON using React Native compatible decoder
-    const decoded = base64Decode(padded);
-    return JSON.parse(decoded);
-  } catch (error) {
-    console.error('❌ Failed to decode JWT token:', error);
-    return null;
-  }
-};
-
-/**
- * Extract username from JWT token
- * @param token JWT token (optional, uses stored token if not provided)
- * @returns Username or null if not found
- */
-export const extractUsernameFromJWT = (token?: string): string | null => {
-  try {
-    const jwtToken = token || userToken;
-    if (!jwtToken) {
-      console.warn('⚠️ No JWT token available for username extraction');
-      return null;
-    }
-
-    const payload = decodeJWTPayload(jwtToken);
-    if (!payload) {
-      return null;
-    }
-
-    // Try different possible username fields in order of preference
-    const username = payload.userName || payload.username || payload.userId || payload.email;
-    
-    if (globalConfig?.enableLogging) {
-      console.log('👤 Extracted username from JWT:', username);
-    }
-
-    return username || null;
-  } catch (error) {
-    console.error('❌ Failed to extract username from JWT:', error);
-    return null;
-  }
-};
-
-/**
- * Extract user data from JWT token
- * @param token JWT token (optional, uses stored token if not provided)
- * @returns User data object or null if not found
- */
-export const extractUserDataFromJWT = (token?: string): any => {
-  try {
-    const jwtToken = token || userToken;
-    if (!jwtToken) {
-      console.warn('⚠️ No JWT token available for user data extraction');
-      return null;
-    }
-
-    const payload = decodeJWTPayload(jwtToken);
-    if (!payload) {
-      return null;
-    }
-
-    const userData = {
-      id: payload.id,
-      email: payload.email,
-      userId: payload.userId,
-      userName: payload.userName || payload.username,
-      verified: payload.verified,
-      iat: payload.iat,
-      exp: payload.exp
-    };
-
-    if (globalConfig?.enableLogging) {
-      console.log('👤 Extracted user data from JWT:', userData);
-    }
-
-    return userData;
-  } catch (error) {
-    console.error('❌ Failed to extract user data from JWT:', error);
-    return null;
-  }
-};
-
-/**
- * Check if user is authenticated with JWT token
- * @returns True if user has valid JWT token
- */
-export const isUserAuthenticated = (): boolean => {
-  return !!userToken;
-};
-
-/**
- * Get authenticated headers for API requests
- * @returns Headers object with Authorization and other required headers
- */
-export const getAuthHeaders = (): Record<string, string> => {
-  if (!globalConfig?.apiKey) {
-    throw new Error('SDK not initialized. Call initializeApiKey() first.');
-  }
-
-  const keyType = getApiKeyType(globalConfig.apiKey);
-  
-  return {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${globalConfig.apiKey}`,
-    'User-Agent': 'OnairosReactNative/3.0.72',
-    'X-SDK-Version': '3.0.72',
-    'X-SDK-Environment': globalConfig.environment || 'production',
-    'X-API-Key-Type': keyType,
-    'X-Timestamp': new Date().toISOString(),
-  };
-};
-
-/**
- * Get authentication headers for developer API requests
- * @returns Headers with developer API key
- */
-export const getDeveloperAuthHeaders = (): Record<string, string> => {
-  if (!globalConfig?.apiKey) {
-    throw new Error('SDK not initialized. Call initializeApiKey() first.');
-  }
-
-  const keyType = getApiKeyType(globalConfig.apiKey);
-  
-  return {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${globalConfig.apiKey}`,
-    'User-Agent': 'OnairosSDK/1.0.0',
-    'X-SDK-Version': '3.0.72',
-    'X-SDK-Environment': globalConfig.environment || 'production',
-    'X-API-Key-Type': keyType,
-    'X-Timestamp': new Date().toISOString(),
-  };
-};
-
-/**
- * Get authentication headers for user JWT requests
- * @returns Headers with user JWT token
- */
-export const getUserAuthHeaders = (): Record<string, string> => {
-  if (!userToken) {
-    throw new Error('User not authenticated. Please verify email first.');
-  }
-
-  return {
-    'Content-Type': 'application/json',
-    'Authorization': `Bearer ${userToken}`,
-    'User-Agent': 'OnairosSDK/1.0.0',
-    'X-SDK-Version': '3.0.72',
-    'X-SDK-Environment': globalConfig?.environment || 'production',
-  };
-};
-
-/**
- * Make an authenticated API request
- * @param endpoint The API endpoint (relative to base URL)
- * @param options Fetch options
- * @returns Response promise
- */
-export const makeAuthenticatedRequest = async (
-  endpoint: string,
-  options: RequestInit = {}
-): Promise<Response> => {
-  if (!isApiKeyInitialized()) {
-    throw new Error('SDK not initialized. Call initializeApiKey() first.');
-  }
-
-  const config = getApiConfig()!;
-  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
-  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
-
-  // Merge authentication headers
-  const headers = {
-    ...getAuthHeaders(),
-    ...(options.headers || {}),
-  };
-
-  // Add timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
-
-  try {
-    if (config.enableLogging) {
-      console.log(`🌐 Making authenticated request to: ${endpoint}`);
-    }
-
-    const response = await fetch(url, {
-      ...options,
-      headers,
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (config.enableLogging) {
-      console.log(`📡 Response status: ${response.status} for ${endpoint}`);
-    }
-
-    // Handle API key errors
-    if (response.status === 401) {
-      console.error('❌ API key authentication failed. Please check your API key.');
-      throw new Error('Invalid or expired API key');
-    }
-
-    if (response.status === 403) {
-      console.error('❌ API key permissions insufficient for this operation.');
-      throw new Error('Insufficient API key permissions');
-    }
-
-    if (response.status === 429) {
-      console.error('❌ API rate limit exceeded. Please try again later.');
-      throw new Error('Rate limit exceeded');
-    }
-
-    return response;
-  } catch (error) {
-    clearTimeout(timeoutId);
-    
-    if (error.name === 'AbortError') {
-      console.error('⏱️ Request timeout for:', endpoint);
-      throw new Error('Request timeout');
-    }
-    
-    throw error;
-  }
-};
-
-/**
- * Make authenticated request with developer API key
- * @param endpoint The API endpoint
- * @param options Fetch options
- * @returns Response promise
- */
-export const makeDeveloperRequest = async (
-  endpoint: string,
-  options: RequestInit = {}
-): Promise<Response> => {
-  if (!isApiKeyInitialized()) {
-    throw new Error('SDK not initialized. Call initializeApiKey() first.');
-  }
-
-  const config = getApiConfig()!;
-  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
-  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
-
-  // Merge developer authentication headers
-  const headers = {
-    ...getDeveloperAuthHeaders(),
-    ...(options.headers || {}),
-  };
-
-  // Add timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
-
-  try {
-    if (config.enableLogging) {
-      console.log(`🌐 Making developer request to: ${endpoint}`);
-    }
-
-    const response = await fetch(url, {
-      ...options,
-      headers,
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (config.enableLogging) {
-      console.log(`📡 Developer request response: ${response.status} for ${endpoint}`);
-    }
-
-    // Handle API key errors
-    if (response.status === 401) {
-      console.error('❌ Developer API key authentication failed');
-      throw new Error('Invalid or expired API key');
-    }
-
-    if (response.status === 403) {
-      console.error('❌ Developer API key permissions insufficient');
-      throw new Error('Insufficient API key permissions');
-    }
-
-    if (response.status === 429) {
-      console.error('❌ API rate limit exceeded');
-      throw new Error('Rate limit exceeded');
-    }
-
-    return response;
-  } catch (error) {
-    clearTimeout(timeoutId);
-    
-    if (error.name === 'AbortError') {
-      console.error('⏱️ Request timeout for:', endpoint);
-      throw new Error('Request timeout');
-    }
-    
-    throw error;
-  }
-};
-
-/**
- * Make authenticated request with user JWT token
- * @param endpoint The API endpoint
- * @param options Fetch options
- * @returns Response promise
- */
-export const makeUserRequest = async (
-  endpoint: string,
-  options: RequestInit = {}
-): Promise<Response> => {
-  if (!isUserAuthenticated()) {
-    await loadJWT(); // Try to load from storage
-  }
-
-  if (!isUserAuthenticated()) {
-    throw new Error('User not authenticated. Please verify email first.');
-  }
-
-  const config = getApiConfig() || { environment: 'production', timeout: 30000, enableLogging: false };
-  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
-  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
-
-  // Merge user authentication headers
-  const headers = {
-    ...getUserAuthHeaders(),
-    ...(options.headers || {}),
-  };
-
-  // Add timeout
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
-
-  try {
-    if (config.enableLogging) {
-      console.log(`🌐 Making user request to: ${endpoint}`);
-    }
-
-    const response = await fetch(url, {
-      ...options,
-      headers,
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutId);
-
-    if (config.enableLogging) {
-      console.log(`📡 User request response: ${response.status} for ${endpoint}`);
-    }
-
-    // Handle JWT token errors
-    if (response.status === 401) {
-      console.error('❌ JWT token authentication failed - token may be expired');
-      await clearJWT(); // Clear expired token
-      throw new Error('Authentication expired. Please verify email again.');
-    }
-
-    if (response.status === 403) {
-      console.error('❌ JWT token permissions insufficient');
-      throw new Error('Insufficient permissions for this operation');
-    }
-
-    return response;
-  } catch (error) {
-    clearTimeout(timeoutId);
-    
-    if (error.name === 'AbortError') {
-      console.error('⏱️ Request timeout for:', endpoint);
-      throw new Error('Request timeout');
-    }
-    
-    throw error;
-  }
-};
-
-/**
- * Clear the API key validation cache
- */
-export const clearValidationCache = (): void => {
-  validationCache.clear();
-  if (globalConfig?.enableLogging) {
-    console.log('🗑️ API key validation cache cleared');
-  }
-};
-
-/**
- * Reset the SDK initialization state
- */
-export const resetApiKeyService = (): void => {
-  globalConfig = null;
-  isInitialized = false;
-  clearValidationCache();
-  console.log('🔄 API key service reset');
+import type { OnairosConfig, ApiKeyValidationResult } from '../types';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import NetInfo from '@react-native-community/netinfo';
+
+// Admin key for backend validation
+export const ADMIN_API_KEY = 'OnairosIsAUnicorn2025';
+
+// API key types
+export enum ApiKeyType {
+  DEVELOPER = 'developer',
+  ADMIN = 'admin',
+  INVALID = 'invalid'
+}
+
+// JWT token storage key
+const JWT_TOKEN_KEY = 'onairos_jwt_token';
+
+/**
+ * Two-Tier Authentication Service for Onairos React Native SDK
+ * 
+ * This service implements the two-tier authentication system:
+ * 1. Developer API Keys: For app-level operations (email verification, app registration)
+ * 2. JWT User Tokens: For user-level operations (PIN storage, user profile)
+ * 
+ * How it works:
+ * 1. Initialize with developer API key
+ * 2. Use API key for email verification requests
+ * 3. Store JWT token from email verification response
+ * 4. Use JWT token for user-authenticated requests
+ * 5. Handle token expiration gracefully
+ * 
+ * Backend Integration:
+ * - Developer routes: Authorization: Bearer ${API_KEY}
+ * - User routes: Authorization: Bearer ${JWT_TOKEN}
+ */
+
+// Global configuration state
+let globalConfig: OnairosConfig | null = null;
+let validationCache: Map<string, { result: ApiKeyValidationResult; timestamp: number }> = new Map();
+let isInitialized = false;
+let userToken: string | null = null;
+
+// Cache duration (5 minutes)
+const CACHE_DURATION = 5 * 60 * 1000;
+
+/**
+ * Check network connectivity
+ * @returns Promise<boolean> - true if connected, false otherwise
+ */
+const checkNetworkConnectivity = async (): Promise<boolean> => {
+  try {
+    const netInfo = await NetInfo.fetch();
+    return netInfo.isConnected === true && netInfo.isInternetReachable !== false;
+  } catch (error) {
+    console.warn('⚠️ Failed to check network connectivity:', error);
+    // If we can't check connectivity, assume we're connected and let the request fail naturally
+    return true;
+  }
+};
+
+// API endpoints for different environments (updated to handle non-existent dev endpoint)
+const API_ENDPOINTS = {
+  production: 'https://api2.onairos.uk',
+  staging: 'https://api2.onairos.uk', // Fallback to production for staging
+  development: 'https://api2.onairos.uk', // Fallback to production since dev-api2.onairos.uk doesn't exist
+};
+
+/**
+ * Initialize the SDK with developer API key
+ * @param config API configuration including developer API key
+ */
+export const initializeApiKey = async (config: OnairosConfig): Promise<void> => {
+  try {
+    console.log('🔑 Initializing Onairos SDK with developer API key...');
+    
+    if (!config.apiKey) {
+      throw new Error('Developer API key is required for SDK initialization');
+    }
+
+    // Check if it's admin key first (admin key is shorter than 32 chars)
+    if (!isAdminKey(config.apiKey) && config.apiKey.length < 32) {
+      throw new Error('Invalid API key format. Developer keys must be at least 32 characters long.');
+    }
+
+    // Set global configuration
+    globalConfig = {
+      apiKey: config.apiKey,
+      environment: config.environment || 'production',
+      enableLogging: config.enableLogging !== false, // Default to true
+      timeout: config.timeout || 30000,
+      retryAttempts: config.retryAttempts || 3,
+    };
+
+    if (globalConfig.enableLogging) {
+      console.log('📝 SDK Configuration:', {
+        environment: globalConfig.environment,
+        timeout: globalConfig.timeout,
+        retryAttempts: globalConfig.retryAttempts,
+        apiKeyPrefix: config.apiKey.substring(0, 8) + '...',
+        enableLogging: globalConfig.enableLogging,
+      });
+    }
+
+    // Validate the API key (handles both admin and developer keys)
+    const validation = await validateApiKey(config.apiKey);
+    
+    if (!validation.isValid) {
+      // Use defensive coding to handle cases where validation.error might be undefined
+      const errorMessage = validation.error || '';
+      
+      // Check if it's a network/connectivity issue (either from error message or the flag)
+      const isNetworkError = validation.isNetworkError || 
+                            errorMessage.includes('Network request failed') ||
+                            errorMessage.includes('Network error') || 
+                            errorMessage.includes('JSON Parse error') || 
+                            errorMessage.includes('API validation endpoint returned') ||
+                            errorMessage.includes('timeout') ||
+                            errorMessage.includes('ENOTFOUND') ||
+                            errorMessage.includes('fetch') ||
+                            errorMessage.includes('No network connection');
+      
+      if (isNetworkError) {
+        console.warn('⚠️ API key validation failed due to network/connectivity issues');
+        console.warn('🔄 Continuing in offline mode with basic validation');
+        console.warn('📝 SDK will function with limited validation. Network connectivity will be retried automatically.');
+        console.warn('🌐 Error details:', validation.error);
+        
+        // Continue initialization in offline mode - don't throw error
+        console.log('📱 SDK initialized in offline mode - will retry validation when network is available');
+      } else {
+        // Only throw for actual API key validation errors (not network issues)
+        throw new Error(`API key validation failed: ${validation.error}`);
+      }
+    }
+
+    // Try to load existing JWT token
+    await loadJWT();
+
+    isInitialized = true;
+    
+    if (globalConfig.enableLogging) {
+      console.log('✅ Onairos SDK initialized successfully');
+      
+      if (isAdminKey(config.apiKey)) {
+        console.log('🔑 Admin API key ready with full permissions');
+      } else {
+        console.log('🔑 Developer API key ready for app-level operations');
+      }
+      
+      if (userToken) {
+        console.log('🎫 User JWT token loaded from storage');
+      }
+      if (validation.permissions) {
+        console.log('🔐 API Key Permissions:', validation.permissions);
+      }
+      if (validation.rateLimits) {
+        console.log('⏱️ Rate Limits:', validation.rateLimits);
+      }
+    }
+  } catch (error) {
+    console.error('❌ Failed to initialize Onairos SDK:', error);
+    isInitialized = false;
+    throw error;
+  }
+};
+
+/**
+ * Determine API key type
+ * @param apiKey The API key to check
+ * @returns The type of API key
+ */
+export const getApiKeyType = (apiKey: string): ApiKeyType => {
+  if (apiKey === ADMIN_API_KEY) {
+    return ApiKeyType.ADMIN;
+  }
+  
+  // Developer keys should be at least 32 characters and start with specific prefix
+  if (apiKey.length >= 32 && (apiKey.startsWith('dev_') || apiKey.startsWith('pk_') || apiKey.startsWith('ona_'))) {
+    return ApiKeyType.DEVELOPER;
+  }
+  
+  return ApiKeyType.INVALID;
+};
+
+/**
+ * Check if API key is admin key
+ * @param apiKey The API key to check
+ * @returns True if admin key
+ */
+export const isAdminKey = (apiKey: string): boolean => {
+  return apiKey === ADMIN_API_KEY;
+};
+
+/**
+ * Validate an API key with the Onairos backend
+ * @param apiKey The API key to validate
+ * @returns Validation result with permissions and rate limits
+ */
+export const validateApiKey = async (apiKey: string): Promise<ApiKeyValidationResult> => {
+  try {
+    console.log('🔍 Validating API key...');
+    
+    // Check if it's an admin key
+    if (isAdminKey(apiKey)) {
+      console.log('🔑 Admin key detected - granting full permissions');
+      return {
+        isValid: true,
+        permissions: ['*'], // Full permissions for admin
+        rateLimits: {
+          remaining: 999999,
+          resetTime: Date.now() + 24 * 60 * 60 * 1000 // 24 hours
+        },
+        keyType: ApiKeyType.ADMIN
+      };
+    }
+    
+    // Check basic format for developer keys
+    const keyType = getApiKeyType(apiKey);
+    if (keyType === ApiKeyType.INVALID) {
+      return {
+        isValid: false,
+        error: 'Invalid API key format. Developer keys must be at least 32 characters and start with "dev_", "pk_", or "ona_"',
+        keyType: ApiKeyType.INVALID
+      };
+    }
+    
+    // Check cache first
+    const cached = validationCache.get(apiKey);
+    if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
+      if (globalConfig?.enableLogging) {
+        console.log('📋 Using cached API key validation result');
+      }
+      return cached.result;
+    }
+
+    // Check network connectivity before making API calls
+    const isConnected = await checkNetworkConnectivity();
+    if (!isConnected) {
+      console.warn('⚠️ No network connectivity detected');
+      return {
+        isValid: false,
+        error: 'No network connection available. Please check your internet connection and try again.',
+        keyType: keyType,
+        isNetworkError: true
+      };
+    }
+
+    const environment = globalConfig?.environment || 'production';
+    const baseUrl = API_ENDPOINTS[environment];
+    const timeout = globalConfig?.timeout || 30000;
+    const maxRetries = globalConfig?.retryAttempts || 3;
+
+    // Retry logic for network failures
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      // Create abort controller for timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      try {
+        if (globalConfig?.enableLogging && attempt > 1) {
+          console.log(`🔄 Retry attempt ${attempt}/${maxRetries} for API key validation`);
+        }
+
+        const response = await fetch(`${baseUrl}/auth/validate-key`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+            'User-Agent': 'OnairosReactNative/3.3.1',
+            'X-API-Key-Type': keyType,
+            'X-SDK-Platform': 'react-native',
+            'X-Retry-Attempt': attempt.toString(),
+          },
+          body: JSON.stringify({
+            environment,
+            sdk_version: '3.3.1',
+            platform: 'react-native',
+            keyType,
+            timestamp: new Date().toISOString(),
+            attempt,
+          }),
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        // First check if we got a valid response
+        if (!response) {
+          throw new Error('No response received from server');
+        }
+
+        // Handle common HTTP errors that indicate server issues
+        if (response.status === 502) {
+          throw new Error('Onairos API is temporarily unavailable (502 Bad Gateway). Please try again later.');
+        }
+        
+        if (response.status === 503) {
+          throw new Error('Onairos API is under maintenance (503 Service Unavailable). Please try again later.');
+        }
+        
+        if (response.status === 504) {
+          throw new Error('Onairos API request timed out (504 Gateway Timeout). Please try again.');
+        }
+
+        // Check if response is actually JSON before trying to parse
+        const contentType = response.headers.get('content-type');
+        const isJsonResponse = contentType && contentType.includes('application/json');
+        
+        if (!isJsonResponse) {
+          const textContent = await response.text();
+          const previewText = textContent.substring(0, 200);
+          
+          console.error('❌ API endpoint returned non-JSON response:', {
+            status: response.status,
+            statusText: response.statusText,
+            contentType: contentType || 'unknown',
+            preview: previewText,
+            url: `${baseUrl}/auth/validate-key`,
+            attempt: attempt
+          });
+          
+          // Handle specific error cases
+          if (response.status === 404) {
+            throw new Error(`API validation endpoint not found (404). The endpoint ${baseUrl}/auth/validate-key may not exist or be configured correctly.`);
+          } else if (response.status === 500) {
+            throw new Error(`Server error (500). The Onairos backend is experiencing issues.`);
+          } else if (response.status === 502 || response.status === 503) {
+            throw new Error(`Service unavailable (${response.status}). The Onairos backend may be temporarily down.`);
+          } else if (textContent.includes('<html') || textContent.includes('<!DOCTYPE')) {
+            throw new Error(`Server returned HTML page instead of JSON API response. This often indicates a routing issue or server misconfiguration.`);
+          } else {
+            throw new Error(`API validation endpoint returned ${response.status} - ${response.statusText}. Expected JSON but got ${contentType || 'unknown content type'}.`);
+          }
+        }
+
+        // Parse JSON response
+        let data;
+        try {
+          data = await response.json();
+        } catch (jsonError) {
+          console.error('❌ Failed to parse JSON response:', {
+            error: jsonError.message,
+            status: response.status,
+            contentType,
+            attempt: attempt
+          });
+          throw new Error(`Failed to parse server response as JSON: ${jsonError.message}`);
+        }
+
+        // Handle successful response
+        if (response.ok && data.success) {
+          const result: ApiKeyValidationResult = {
+            isValid: true,
+            permissions: data.permissions || [],
+            rateLimits: data.rateLimits || null,
+            keyType: keyType,
+          };
+
+          // Cache the successful result
+          validationCache.set(apiKey, {
+            result,
+            timestamp: Date.now(),
+          });
+
+          if (globalConfig?.enableLogging) {
+            console.log('✅ API key validation successful');
+          }
+
+          return result;
+        } else {
+          // Handle API errors (invalid key, etc.)
+          const errorMessage = data.error || data.message || `HTTP ${response.status}: ${response.statusText}`;
+          
+          const result: ApiKeyValidationResult = {
+            isValid: false,
+            error: errorMessage,
+            keyType: keyType,
+          };
+
+          // For client errors (4xx), don't retry
+          if (response.status >= 400 && response.status < 500) {
+            if (globalConfig?.enableLogging) {
+              console.error('❌ API key validation failed (client error):', errorMessage);
+            }
+            return result;
+          }
+
+          // For server errors (5xx), retry
+          throw new Error(errorMessage);
+        }
+
+      } catch (fetchError: any) {
+        clearTimeout(timeoutId);
+        
+        if (fetchError.name === 'AbortError') {
+          const errorMessage = `API key validation timeout (${timeout}ms)`;
+          console.error('⏱️ API key validation timeout');
+          
+          if (attempt === maxRetries) {
+            return { isValid: false, error: errorMessage, keyType: keyType };
+          }
+          continue; // Retry timeout errors
+        }
+        
+        // Enhanced error message based on error type
+        let errorMessage = `Network error during API key validation: ${fetchError.message}`;
+        
+        // Add specific guidance for common errors
+        if (fetchError.message.includes('JSON Parse error') || fetchError.message.includes('Unexpected character')) {
+          errorMessage = `Server returned invalid JSON response. This usually indicates the API endpoint returned HTML instead of JSON (often a 404 or server error page). ${fetchError.message}`;
+        } else if (fetchError.message.includes('Network request failed') || fetchError.message.includes('fetch')) {
+          errorMessage = `Network connectivity issue. Please check internet connection and verify the Onairos API is accessible. ${fetchError.message}`;
+        } else if (fetchError.message.includes('DNS') || fetchError.message.includes('ENOTFOUND')) {
+          errorMessage = `DNS resolution failed for ${baseUrl}. Please check network settings and domain accessibility. ${fetchError.message}`;
+        }
+        
+        console.error('🌐 Network error during API key validation:', {
+          error: fetchError,
+          endpoint: `${baseUrl}/auth/validate-key`,
+          attempt: attempt,
+          maxRetries: maxRetries,
+          retryable: attempt < maxRetries
+        });
+
+        // If this is the last attempt, return the error
+        if (attempt === maxRetries) {
+          return { 
+            isValid: false, 
+            error: errorMessage, 
+            keyType: keyType,
+            isNetworkError: true // Flag to indicate this is a network issue, not an API key issue
+          };
+        }
+
+                 // Wait before retrying (exponential backoff)
+         const backoffDelay = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
+         if (globalConfig?.enableLogging) {
+           console.log(`⏳ Waiting ${backoffDelay}ms before retry...`);
+         }
+         await new Promise<void>(resolve => setTimeout(() => resolve(), backoffDelay));
+      }
+    }
+
+    // This should never be reached, but just in case
+    return { 
+      isValid: false, 
+      error: 'All retry attempts exhausted', 
+      keyType: keyType 
+    };
+
+  } catch (error: any) {
+    const errorMessage = `API key validation error: ${error.message}`;
+    console.error('❌ API key validation error:', error);
+    return { isValid: false, error: errorMessage, keyType: ApiKeyType.INVALID };
+  }
+};
+
+/**
+ * Get the current API configuration
+ * @returns Current API configuration or null if not initialized
+ */
+export const getApiConfig = (): OnairosConfig | null => {
+  return globalConfig;
+};
+
+/**
+ * Get the current API key
+ * @returns Current API key or null if not initialized
+ */
+export const getApiKey = (): string | null => {
+  return globalConfig?.apiKey || null;
+};
+
+/**
+ * Check if the SDK is properly initialized
+ * @returns True if initialized with valid API key
+ */
+export const isApiKeyInitialized = (): boolean => {
+  return isInitialized && globalConfig !== null;
+};
+
+/**
+ * Store JWT token securely after email verification
+ * @param token JWT token from email verification response
+ */
+export const storeJWT = async (token: string): Promise<void> => {
+  try {
+    await AsyncStorage.setItem(JWT_TOKEN_KEY, token);
+    userToken = token;
+    
+    if (globalConfig?.enableLogging) {
+      console.log('🎫 JWT token stored successfully');
+    }
+  } catch (error) {
+    console.error('❌ Failed to store JWT token:', error);
+    throw error;
+  }
+};
+
+/**
+ * Load JWT token from storage
+ * @returns JWT token or null if not found
+ */
+export const loadJWT = async (): Promise<string | null> => {
+  try {
+    const token = await AsyncStorage.getItem(JWT_TOKEN_KEY);
+    userToken = token;
+    return token;
+  } catch (error) {
+    console.error('❌ Failed to load JWT token:', error);
+    return null;
+  }
+};
+
+/**
+ * Get current JWT token
+ * @returns JWT token or null if not available
+ */
+export const getJWT = (): string | null => {
+  return userToken;
+};
+
+/**
+ * Clear JWT token (on logout or token expiration)
+ */
+export const clearJWT = async (): Promise<void> => {
+  try {
+    await AsyncStorage.removeItem(JWT_TOKEN_KEY);
+    userToken = null;
+    
+    if (globalConfig?.enableLogging) {
+      console.log('🗑️ JWT token cleared');
+    }
+  } catch (error) {
+    console.error('❌ Failed to clear JWT token:', error);
+  }
+};
+
+/**
+ * React Native compatible base64 decoder
+ * @param str Base64 encoded string
+ * @returns Decoded string
+ */
+const base64Decode = (str: string): string => {
+  // Simple base64 decoding for React Native
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+  let result = '';
+  let i = 0;
+  
+  str = str.replace(/[^A-Za-z0-9+/]/g, '');
+  
+  while (i < str.length) {
+    const a = chars.indexOf(str.charAt(i++));
+    const b = chars.indexOf(str.charAt(i++));
+    const c = chars.indexOf(str.charAt(i++));
+    const d = chars.indexOf(str.charAt(i++));
+    
+    const bitmap = (a << 18) | (b << 12) | (c << 6) | d;
+    
+    result += String.fromCharCode((bitmap >> 16) & 255);
+    if (c !== 64) result += String.fromCharCode((bitmap >> 8) & 255);
+    if (d !== 64) result += String.fromCharCode(bitmap & 255);
+  }
+  
+  return result;
+};
+
+/**
+ * Decode JWT token payload (React Native compatible)
+ * @param token JWT token string
+ * @returns Decoded payload or null if invalid
+ */
+export const decodeJWTPayload = (token: string): any => {
+  try {
+    // Split JWT token (header.payload.signature)
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      console.error('❌ Invalid JWT token format');
+      return null;
+    }
+
+    // Decode payload (base64url to base64)
+    const payload = parts[1];
+    const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    
+    // Add padding if needed
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    
+    // Decode base64 to JSON using React Native compatible decoder
+    const decoded = base64Decode(padded);
+    return JSON.parse(decoded);
+  } catch (error) {
+    console.error('❌ Failed to decode JWT token:', error);
+    return null;
+  }
+};
+
+/**
+ * Extract username from JWT token
+ * @param token JWT token (optional, uses stored token if not provided)
+ * @returns Username or null if not found
+ */
+export const extractUsernameFromJWT = (token?: string): string | null => {
+  try {
+    const jwtToken = token || userToken;
+    if (!jwtToken) {
+      console.warn('⚠️ No JWT token available for username extraction');
+      return null;
+    }
+
+    const payload = decodeJWTPayload(jwtToken);
+    if (!payload) {
+      return null;
+    }
+
+    // Try different possible username fields in order of preference
+    const username = payload.userName || payload.username || payload.userId || payload.email;
+    
+    if (globalConfig?.enableLogging) {
+      console.log('👤 Extracted username from JWT:', username);
+    }
+
+    return username || null;
+  } catch (error) {
+    console.error('❌ Failed to extract username from JWT:', error);
+    return null;
+  }
+};
+
+/**
+ * Extract user data from JWT token
+ * @param token JWT token (optional, uses stored token if not provided)
+ * @returns User data object or null if not found
+ */
+export const extractUserDataFromJWT = (token?: string): any => {
+  try {
+    const jwtToken = token || userToken;
+    if (!jwtToken) {
+      console.warn('⚠️ No JWT token available for user data extraction');
+      return null;
+    }
+
+    const payload = decodeJWTPayload(jwtToken);
+    if (!payload) {
+      return null;
+    }
+
+    const userData = {
+      id: payload.id,
+      email: payload.email,
+      userId: payload.userId,
+      userName: payload.userName || payload.username,
+      verified: payload.verified,
+      iat: payload.iat,
+      exp: payload.exp
+    };
+
+    if (globalConfig?.enableLogging) {
+      console.log('👤 Extracted user data from JWT:', userData);
+    }
+
+    return userData;
+  } catch (error) {
+    console.error('❌ Failed to extract user data from JWT:', error);
+    return null;
+  }
+};
+
+/**
+ * Check if user is authenticated with JWT token
+ * @returns True if user has valid JWT token
+ */
+export const isUserAuthenticated = (): boolean => {
+  return !!userToken;
+};
+
+/**
+ * Get authenticated headers for API requests
+ * @returns Headers object with Authorization and other required headers
+ */
+export const getAuthHeaders = (): Record<string, string> => {
+  if (!globalConfig?.apiKey) {
+    throw new Error('SDK not initialized. Call initializeApiKey() first.');
+  }
+
+  const keyType = getApiKeyType(globalConfig.apiKey);
+  
+  return {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${globalConfig.apiKey}`,
+    'User-Agent': 'OnairosReactNative/3.0.72',
+    'X-SDK-Version': '3.0.72',
+    'X-SDK-Environment': globalConfig.environment || 'production',
+    'X-API-Key-Type': keyType,
+    'X-Timestamp': new Date().toISOString(),
+  };
+};
+
+/**
+ * Get authentication headers for developer API requests
+ * @returns Headers with developer API key
+ */
+export const getDeveloperAuthHeaders = (): Record<string, string> => {
+  if (!globalConfig?.apiKey) {
+    throw new Error('SDK not initialized. Call initializeApiKey() first.');
+  }
+
+  const keyType = getApiKeyType(globalConfig.apiKey);
+  
+  return {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${globalConfig.apiKey}`,
+    'User-Agent': 'OnairosSDK/1.0.0',
+    'X-SDK-Version': '3.0.72',
+    'X-SDK-Environment': globalConfig.environment || 'production',
+    'X-API-Key-Type': keyType,
+    'X-Timestamp': new Date().toISOString(),
+  };
+};
+
+/**
+ * Get authentication headers for user JWT requests
+ * @returns Headers with user JWT token
+ */
+export const getUserAuthHeaders = (): Record<string, string> => {
+  if (!userToken) {
+    throw new Error('User not authenticated. Please verify email first.');
+  }
+
+  return {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${userToken}`,
+    'User-Agent': 'OnairosSDK/1.0.0',
+    'X-SDK-Version': '3.0.72',
+    'X-SDK-Environment': globalConfig?.environment || 'production',
+  };
+};
+
+/**
+ * Make an authenticated API request
+ * @param endpoint The API endpoint (relative to base URL)
+ * @param options Fetch options
+ * @returns Response promise
+ */
+export const makeAuthenticatedRequest = async (
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<Response> => {
+  if (!isApiKeyInitialized()) {
+    throw new Error('SDK not initialized. Call initializeApiKey() first.');
+  }
+
+  const config = getApiConfig()!;
+  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
+  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+
+  // Merge authentication headers
+  const headers = {
+    ...getAuthHeaders(),
+    ...(options.headers || {}),
+  };
+
+  // Add timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
+
+  try {
+    if (config.enableLogging) {
+      console.log(`🌐 Making authenticated request to: ${endpoint}`);
+    }
+
+    const response = await fetch(url, {
+      ...options,
+      headers,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (config.enableLogging) {
+      console.log(`📡 Response status: ${response.status} for ${endpoint}`);
+    }
+
+    // Handle API key errors
+    if (response.status === 401) {
+      console.error('❌ API key authentication failed. Please check your API key.');
+      throw new Error('Invalid or expired API key');
+    }
+
+    if (response.status === 403) {
+      console.error('❌ API key permissions insufficient for this operation.');
+      throw new Error('Insufficient API key permissions');
+    }
+
+    if (response.status === 429) {
+      console.error('❌ API rate limit exceeded. Please try again later.');
+      throw new Error('Rate limit exceeded');
+    }
+
+    return response;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    
+    if (error.name === 'AbortError') {
+      console.error('⏱️ Request timeout for:', endpoint);
+      throw new Error('Request timeout');
+    }
+    
+    throw error;
+  }
+};
+
+/**
+ * Make authenticated request with developer API key
+ * @param endpoint The API endpoint
+ * @param options Fetch options
+ * @returns Response promise
+ */
+export const makeDeveloperRequest = async (
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<Response> => {
+  if (!isApiKeyInitialized()) {
+    throw new Error('SDK not initialized. Call initializeApiKey() first.');
+  }
+
+  const config = getApiConfig()!;
+  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
+  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+
+  // Merge developer authentication headers
+  const headers = {
+    ...getDeveloperAuthHeaders(),
+    ...(options.headers || {}),
+  };
+
+  // Add timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
+
+  try {
+    if (config.enableLogging) {
+      console.log(`🌐 Making developer request to: ${endpoint}`);
+    }
+
+    const response = await fetch(url, {
+      ...options,
+      headers,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (config.enableLogging) {
+      console.log(`📡 Developer request response: ${response.status} for ${endpoint}`);
+    }
+
+    // Handle API key errors
+    if (response.status === 401) {
+      console.error('❌ Developer API key authentication failed');
+      throw new Error('Invalid or expired API key');
+    }
+
+    if (response.status === 403) {
+      console.error('❌ Developer API key permissions insufficient');
+      throw new Error('Insufficient API key permissions');
+    }
+
+    if (response.status === 429) {
+      console.error('❌ API rate limit exceeded');
+      throw new Error('Rate limit exceeded');
+    }
+
+    return response;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    
+    if (error.name === 'AbortError') {
+      console.error('⏱️ Request timeout for:', endpoint);
+      throw new Error('Request timeout');
+    }
+    
+    throw error;
+  }
+};
+
+/**
+ * Make authenticated request with user JWT token
+ * @param endpoint The API endpoint
+ * @param options Fetch options
+ * @returns Response promise
+ */
+export const makeUserRequest = async (
+  endpoint: string,
+  options: RequestInit = {}
+): Promise<Response> => {
+  if (!isUserAuthenticated()) {
+    await loadJWT(); // Try to load from storage
+  }
+
+  if (!isUserAuthenticated()) {
+    throw new Error('User not authenticated. Please verify email first.');
+  }
+
+  const config = getApiConfig() || { environment: 'production', timeout: 30000, enableLogging: false };
+  const baseUrl = API_ENDPOINTS[config.environment || 'production'];
+  const url = `${baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+
+  // Merge user authentication headers
+  const headers = {
+    ...getUserAuthHeaders(),
+    ...(options.headers || {}),
+  };
+
+  // Add timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout || 30000);
+
+  try {
+    if (config.enableLogging) {
+      console.log(`🌐 Making user request to: ${endpoint}`);
+    }
+
+    const response = await fetch(url, {
+      ...options,
+      headers,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (config.enableLogging) {
+      console.log(`📡 User request response: ${response.status} for ${endpoint}`);
+    }
+
+    // Handle JWT token errors
+    if (response.status === 401) {
+      console.error('❌ JWT token authentication failed - token may be expired');
+      await clearJWT(); // Clear expired token
+      throw new Error('Authentication expired. Please verify email again.');
+    }
+
+    if (response.status === 403) {
+      console.error('❌ JWT token permissions insufficient');
+      throw new Error('Insufficient permissions for this operation');
+    }
+
+    return response;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    
+    if (error.name === 'AbortError') {
+      console.error('⏱️ Request timeout for:', endpoint);
+      throw new Error('Request timeout');
+    }
+    
+    throw error;
+  }
+};
+
+/**
+ * Clear the API key validation cache
+ */
+export const clearValidationCache = (): void => {
+  validationCache.clear();
+  if (globalConfig?.enableLogging) {
+    console.log('🗑️ API key validation cache cleared');
+  }
+};
+
+/**
+ * Reset the SDK initialization state
+ */
+export const resetApiKeyService = (): void => {
+  globalConfig = null;
+  isInitialized = false;
+  clearValidationCache();
+  console.log('🔄 API key service reset');
 };