@onairos/react-native 3.4.1 → 3.6.0

package/src/services/SDK_API_KEY_VALIDATION.md

@@ -1,421 +0,0 @@
-# Onairos SDK API Key Validation - Standardized Documentation
-
-## Overview
-
-This document outlines the standardized API key validation system for all Onairos SDKs (React Native, Web, Mobile, etc.). The system provides a unified interface for initializing and validating developer API keys across all platforms.
-
-## 🔑 API Key Format
-
-### Developer API Keys
-- **Format**: Must be at least 32 characters
-- **Prefixes**: `dev_`, `pk_`, or `ona_`
-- **Example**: `ona_1234567890abcdef1234567890abcdef12345678`
-
-### Admin API Keys (Internal Use)
-- **Format**: Special admin keys for internal testing
-- **Permissions**: Full access (`*`)
-
-## 🚀 SDK Initialization Standard
-
-### Step 1: Initialize SDK (Required for all SDKs)
-
-All SDKs should implement an `initializeApiKey` function that validates the API key before allowing SDK usage.
-
-```typescript
-import { initializeApiKey } from 'onairos';
-
-// Initialize SDK with developer API key
-try {
-  await initializeApiKey({
-    apiKey: 'ona_your_api_key_here', // Get from Onairos Dashboard
-    environment: 'production', // 'production' | 'development'
-    enableLogging: true,
-    timeout: 30000,
-    retryAttempts: 3
-  });
-  
-  console.log('SDK initialized successfully!');
-} catch (error) {
-  console.error('SDK initialization failed:', error.message);
-}
-```
-
-### Step 2: Use SDK Components
-
-After successful initialization, all SDK components work automatically:
-
-```typescript
-import { OnairosButton } from 'onairos';
-
-// Components automatically handle authentication internally
-<OnairosButton
-  requestData={{
-    basic: { type: "basic", reward: "10 tokens" },
-    personality: { type: "personality", reward: "25 tokens" }, 
-    preferences: { type: "preferences", reward: "15 tokens" }
-  }}
-  webpageName="MyApp"
-  testMode={false}
-  autoFetch={true}
-  onComplete={(result) => console.log(result)}
-/>
-```
-
-## 🌐 API Endpoints
-
-### Primary Validation Endpoint
-
-**POST** `/dev/validate`
-
-This is the main endpoint that all SDKs should use for API key validation.
-
-#### Request Headers
-```http
-Authorization: Bearer ona_your_api_key_here
-Content-Type: application/json
-X-SDK-Platform: react-native|web|mobile (optional)
-User-Agent: OnairosReactNative/3.1.10 (optional)
-```
-
-#### Request Body
-```json
-{
-  "environment": "production",
-  "sdk_version": "3.1.10",
-  "platform": "react-native",
-  "keyType": "developer",
-  "timestamp": "2024-01-01T00:00:00.000Z",
-  "attempt": 1
-}
-```
-
-#### Success Response (200)
-```json
-{
-  "valid": true,
-  "apiKey": {
-    "id": "68f7f1bef71b2523faade626",
-    "name": "My App Key",
-    "createdAt": "2025-10-21T20:49:02.205Z",
-    "lastUsed": "2025-10-24T00:15:54.478Z",
-    "usageCount": 13
-  },
-  "application": {
-    "name": "My Application",
-    "theme": "productivity",
-    "description": "Application description"
-  }
-}
-```
-
-#### Error Response (401/400/500)
-```json
-{
-  "valid": false,
-  "error": "Invalid API key format",
-  "message": "Developer keys must be at least 32 characters and start with 'dev_', 'pk_', or 'ona_'",
-  "code": "INVALID_API_KEY_FORMAT"
-}
-```
-
-### Alternative Endpoints
-
-#### Legacy Endpoints (Deprecated)
-- **POST** `/auth/validate-key` - Old validation endpoint (deprecated, use `/dev/validate`)
-- **GET** `/auth/validate-key?key=API_KEY` - Old GET validation (deprecated)
-
-## 🛡️ Error Handling & Retry Logic
-
-### Common Error Codes
-
-| Code | Description | Action |
-|------|-------------|--------|
-| `MISSING_API_KEY` | No API key provided | Provide API key in Authorization header |
-| `INVALID_API_KEY_FORMAT` | Invalid key format | Check key format (32+ chars, correct prefix) |
-| `INVALID_API_KEY` | Key not found/inactive | Verify key exists and is active |
-| `API_KEY_EXPIRED` | Key has expired | Renew or generate new API key |
-| `DEVELOPER_NOT_FOUND` | Developer account inactive | Contact support |
-| `RATE_LIMIT_EXCEEDED` | Too many requests | Wait and retry |
-| `INTERNAL_ERROR` | Server error | Retry with exponential backoff |
-
-### Retry Strategy
-
-```typescript
-const validateApiKey = async (apiKey: string, config: Config): Promise<ValidationResult> => {
-  const maxRetries = config.retryAttempts || 3;
-  
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      const response = await fetch(`${baseUrl}/auth/validate-key`, {
-        method: 'POST',
-        headers: {
-          'Authorization': `Bearer ${apiKey}`,
-          'Content-Type': 'application/json',
-          'X-SDK-Platform': config.platform || 'unknown'
-        },
-        body: JSON.stringify({
-          environment: config.environment || 'production',
-          sdk_version: config.sdkVersion,
-          platform: config.platform,
-          timestamp: new Date().toISOString(),
-          attempt
-        }),
-        signal: AbortSignal.timeout(config.timeout || 30000)
-      });
-      
-      if (response.ok) {
-        return await response.json();
-      }
-      
-      // Don't retry client errors (4xx)
-      if (response.status >= 400 && response.status < 500) {
-        throw new Error(`Client error: ${response.status}`);
-      }
-      
-      // Retry server errors (5xx)
-      if (attempt === maxRetries) {
-        throw new Error(`Server error after ${maxRetries} attempts`);
-      }
-      
-    } catch (error) {
-      if (attempt === maxRetries) {
-        throw error;
-      }
-      
-      // Exponential backoff
-      const delay = Math.min(1000 * Math.pow(2, attempt - 1), 5000);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-};
-```
-
-## 📱 Platform-Specific Implementation
-
-### React Native SDK
-
-```typescript
-export const validateApiKey = async (apiKey: string): Promise<ApiKeyValidationResult> => {
-  // Check admin keys first
-  if (isAdminKey(apiKey)) {
-    return {
-      isValid: true,
-      permissions: ['*'],
-      rateLimits: { remaining: 999999, resetTime: Date.now() + 24*60*60*1000 },
-      keyType: ApiKeyType.ADMIN
-    };
-  }
-  
-  // Validate format
-  const keyType = getApiKeyType(apiKey);
-  if (keyType === ApiKeyType.INVALID) {
-    return {
-      isValid: false,
-      error: 'Invalid API key format',
-      keyType: ApiKeyType.INVALID
-    };
-  }
-  
-  // Make API call
-  const response = await fetch(`${baseUrl}/dev/validate`, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${apiKey}`,
-      'Content-Type': 'application/json',
-      'User-Agent': 'OnairosReactNative/3.3.1',
-      'X-API-Key-Type': keyType,
-      'X-SDK-Platform': 'react-native'
-    },
-    body: JSON.stringify({
-      environment: globalConfig?.environment || 'production',
-      sdk_version: '3.3.1',
-      platform: 'react-native',
-      keyType,
-      timestamp: new Date().toISOString()
-    })
-  });
-  
-  const data = await response.json();
-  
-  if (data.valid || data.success) {
-    return {
-      isValid: true,
-      permissions: data.permissions || [],
-      rateLimits: data.rateLimits || null,
-      keyType: keyType
-    };
-  } else {
-    return {
-      isValid: false,
-      error: data.error || data.message,
-      keyType: keyType
-    };
-  }
-};
-```
-
-### Web SDK
-
-```typescript
-class OnairosSDK {
-  private apiKey: string | null = null;
-  private isInitialized: boolean = false;
-  
-  async initialize(config: InitConfig): Promise<void> {
-    const validation = await this.validateApiKey(config.apiKey);
-    
-    if (!validation.isValid) {
-      throw new Error(`SDK initialization failed: ${validation.error}`);
-    }
-    
-    this.apiKey = config.apiKey;
-    this.isInitialized = true;
-    
-    console.log('Onairos SDK initialized successfully');
-  }
-  
-  private async validateApiKey(apiKey: string): Promise<ValidationResult> {
-    // Similar implementation to React Native
-    // ...
-  }
-}
-```
-
-## 🔧 Configuration Options
-
-### InitConfig Interface
-
-```typescript
-interface InitConfig {
-  apiKey: string;                    // Required: Developer API key
-  environment?: 'production' | 'development'; // Default: 'production'
-  enableLogging?: boolean;           // Default: false
-  timeout?: number;                  // Default: 30000ms
-  retryAttempts?: number;            // Default: 3
-  baseUrl?: string;                  // Default: auto-detected
-}
-```
-
-### ValidationResult Interface
-
-```typescript
-interface ValidationResult {
-  isValid: boolean;
-  permissions?: string[];
-  rateLimits?: {
-    remaining: number;
-    resetTime: number;
-  };
-  keyType: 'admin' | 'developer' | 'invalid';
-  error?: string;
-}
-```
-
-## 🌍 Environment Configuration
-
-### Base URLs
-
-```typescript
-const API_ENDPOINTS = {
-  production: 'https://api2.onairos.uk',
-  development: 'https://dev-api2.onairos.uk'
-};
-```
-
-### Environment Detection
-
-```typescript
-const detectEnvironment = (): 'production' | 'development' => {
-  if (typeof window !== 'undefined') {
-    // Browser environment
-    return window.location.hostname.includes('localhost') ? 'development' : 'production';
-  } else {
-    // Node.js/React Native environment
-    return process.env.NODE_ENV === 'development' ? 'development' : 'production';
-  }
-};
-```
-
-## 🚀 Quick Start Examples
-
-### React Native
-
-```typescript
-import { initializeApiKey, OnairosButton } from 'onairos-react-native';
-
-// 1. Initialize SDK
-await initializeApiKey({
-  apiKey: 'ona_your_key_here',
-  environment: 'production'
-});
-
-// 2. Use components
-<OnairosButton requestData={{...}} onComplete={handleResult} />
-```
-
-### Web/JavaScript
-
-```typescript
-import { OnairosSDK } from 'onairos-web';
-
-// 1. Initialize SDK
-const sdk = new OnairosSDK();
-await sdk.initialize({
-  apiKey: 'ona_your_key_here',
-  environment: 'production'
-});
-
-// 2. Use SDK methods
-const result = await sdk.collectData({...});
-```
-
-### Node.js Backend
-
-```typescript
-import { OnairosAPI } from 'onairos-node';
-
-// 1. Initialize API client
-const api = new OnairosAPI({
-  apiKey: 'ona_your_key_here',
-  environment: 'production'
-});
-
-// 2. Make API calls
-const validation = await api.validateKey();
-```
-
-## 🔍 Testing & Debugging
-
-### Test API Key Validation
-
-```bash
-# Test with curl
-curl -X POST https://api2.onairos.uk/dev/validate \
-  -H "Authorization: Bearer ona_your_key_here" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "environment": "production",
-    "platform": "test"
-  }'
-```
-
-### Debug Mode
-
-Enable logging in SDK initialization:
-
-```typescript
-await initializeApiKey({
-  apiKey: 'ona_your_key_here',
-  enableLogging: true  // Shows detailed logs
-});
-```
-
-## 📞 Support
-
-- **Documentation**: https://docs.onairos.uk
-- **Dashboard**: https://dashboard.onairos.uk
-- **Support**: support@onairos.uk
-
----
-
-*Last updated: October 2024*