onairos/llm.txt

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

Using this llm instruction file (@llm.txt) and the Onairos package this is located in (@onairos) 
install and setup Onairos so that we have the onairos button setup in the onbaording and the intialization 
and everything else is setup, including tthe callback function for us to export the data from onairos easily

The following is depth description Onairos package

# Onairos NPM Package - LLM Context

## Package Overview
- **Version**: 3.1.23
- **Type**: React Web Library for Data Requests & OAuth Authentication
- **Main Use**: Personal AI training data collection via social media OAuth
- **Base API**: `https://api2.onairos.uk` (production), `staging-api.onairos.uk` (staging), `dev-api.onairos.uk` (development)
- **Authentication**: Two-tier system (Developer API Keys + JWT User Tokens)

## Key Features ✅
1. **Data Request System**: Users can share "basic info", "personality", or "preferences" data
2. **OAuth Connectors**: 9 platforms (YouTube, LinkedIn, Reddit, Pinterest, Instagram, GitHub, Facebook, Gmail, Notion)
3. **Mobile Browser Support**: Auto-detects mobile and switches popup → redirect OAuth flow
4. **API Integration**: Supports both test/live modes with automatic endpoint switching
5. **PIN-based Encryption**: All models encrypted with user PIN + server key
6. **Responsive Design**: Tailwind CSS with mobile-first approach
7. **API Key Initialization**: Developer API key setup for authentication and environment configuration

## Mobile Browser Compatibility ✅
**WORKS PERFECTLY**: React components, API calls, touch interactions, responsive design, state management

**AUTO-OPTIMIZED**: OAuth flow automatically detects mobile devices:
- **Desktop**: Popup OAuth windows (`window.open`)
- **Mobile**: Redirect OAuth flow (`window.location.href`)

## OAuth Implementation ✅
**Endpoints**: All OAuth connectors use `api2.onairos.uk/{platform}/authorize`
- YouTube: `api2.onairos.uk/youtube/authorize`
- LinkedIn: `api2.onairos.uk/linkedin/authorize`
- Reddit: `api2.onairos.uk/reddit/authorize`
- Pinterest: `api2.onairos.uk/pinterest/authorize`
- Instagram: `api2.onairos.uk/instagram/authorize`
- GitHub: `api2.onairos.uk/github/authorize`
- Facebook: `api2.onairos.uk/facebook/authorize`
- Gmail: `api2.onairos.uk/gmail/authorize`
- Notion: `api2.onairos.uk/notion/authorize`

**Flow**: POST request → Get OAuth URL → Open popup/redirect → Handle callback → Update connection state

## API Endpoints & Environment Configuration

### Environment URLs
```typescript
const API_ENDPOINTS = {
  production: 'https://api2.onairos.uk',
  staging: 'https://staging-api.onairos.uk', 
  development: 'https://dev-api.onairos.uk',
};
```

### Developer API Key Endpoints (Tier 1)
- **API Key Validation**: `POST /auth/validate-key`
- **Email Verification**: `POST /email/verification`
- **App Registration**: `POST /app/register`
- **OAuth Setup**: `POST /oauth/{platform}/setup`

### JWT User Token Endpoints (Tier 2)
- **User Profile**: `GET /user/profile`
- **PIN Operations**: `POST /user/pin`
- **Data Requests**: `POST /user/data-request`
- **Training Routes**: `POST /mobile-training/clean` (regular) or `/enoch` (advanced)

### Authentication Headers

**Developer API Key Headers:**
```typescript
{
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${apiKey}`,
  'User-Agent': 'OnairosSDK/1.0.0',
  'X-SDK-Version': '3.0.72',
  'X-SDK-Environment': 'production',
  'X-API-Key-Type': 'developer',
  'X-Timestamp': new Date().toISOString(),
}
```

**JWT User Token Headers:**
```typescript
{
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${jwtToken}`,
  'User-Agent': 'OnairosSDK/1.0.0',
  'X-SDK-Version': '3.0.72',
  'X-SDK-Environment': 'production',
}
```

## Data Flow
1. **API Key Initialization** → 2. **Email Authentication** → 3. **OAuth Connections** → 4. **PIN Setup** → 5. **Data Request**

**Backend Format**:
```json
{
  "Info": {
    "web3Type": "Normal",
    "confirmations": ["Medium", "Large", "Traits"],
    "Domain": "example.com",
    "EncryptedUserPin": "encrypted_pin",
    "UserSub": "user_hash"
  }
}
```

## API Key Setup ✅
**CRITICAL**: Must initialize API key before using any Onairos components

### 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)

### Complete Initialization
```typescript
import { initializeApiKey } from 'onairos';

// Initialize with developer key
await initializeApiKey({
  apiKey: 'ona_your_api_key_here', // Get from Onairos Dashboard
  environment: 'production', // 'production' | 'staging' | 'development'
  enableLogging: true,
  timeout: 30000,      // Optional: Request timeout (default: 30000ms)
  retryAttempts: 3     // Optional: Retry attempts (default: 3)
});
```

### Supported API Key Formats
- **Developer Keys**: `dev_`, `pk_`, `ona_` prefixes + 32+ characters
- **Admin Key**: Available for testing (contact support for access)
- **Validation**: Backend validation with 5-minute cache

### Configuration Interface
```typescript
interface OnairosConfig {
  apiKey: string;                    // Required: Your API key
  environment?: 'production' | 'staging' | 'development';  // Default: 'production'
  enableLogging?: boolean;           // Default: true
  timeout?: number;                  // Default: 30000ms
  retryAttempts?: number;            // Default: 3
}
```

## Key Components & Functions

### Exposed SDK Functions
- **initializeApiKey**: Primary SDK initialization with developer API key validation (REQUIRED)

### UI Components
- **OnairosButton**: Main entry point with props (testMode, autoFetch, requestData)
- **UniversalOnboarding**: OAuth connector management with mobile detection
- **DataRequest**: Data type selection with visual checkmarks
- **EmailAuth**: Email verification flow
- **PinSetup**: PIN creation for encryption

### Internal Functions (Not Exposed)
The SDK internally handles:
- JWT token management (store/load/clear)
- Developer vs user request authentication
- API key validation and caching
- OAuth flow management
- Error handling and retry logic

## Mobile-Specific Features ✅
- **MobileDataRequestPage**: Mobile-optimized data request UI
- **Touch Events**: Proper touch handling with `touchAction` CSS
- **Viewport Management**: Dynamic viewport height for mobile browsers
- **Mobile OAuth Return**: Handles OAuth callback cleanup in mobile redirect flow

## Known Discrepancies
❌ **NONE** - All OAuth flows now properly handle both desktop and mobile
❌ **NONE** - All API endpoints use correct `api2.onairos.uk` domain
❌ **NONE** - Mobile browser compatibility is complete

## Recent Updates (v2.1.5 → v3.1.8)
✅ **Two-Tier Authentication System**: Developer API keys + JWT user tokens
✅ **Comprehensive SDK Initialization**: `initializeApiKey()` with full validation
✅ **JWT Token Management**: Automatic storage, loading, and cleanup
✅ **Multi-Environment Support**: Production, staging, development endpoints
✅ **Advanced Error Handling**: Retry logic, exponential backoff, auto-recovery
✅ **API Key Validation**: Backend validation with 5-minute caching
✅ **Request Authentication**: Separate headers for developer vs user requests
✅ **Mobile device detection for OAuth flows**
✅ **Mobile OAuth redirect handling**
✅ **Enhanced OAuth URL parsing for all 9 platforms**
✅ **Mobile browser compatibility documentation**
✅ **Fixed OAuth popup blocking on mobile devices**
✅ **Fixed TypeScript declaration file resolution issue in package.json exports**
✅ **React Native AsyncStorage integration for JWT persistence**
✅ **Comprehensive logging system with configurable levels**
✅ **Admin key support for testing and development**
✅ **HTTP client abstraction with automatic authentication headers**

## Complete Usage Flow 🚀

### Step 1: Initialize SDK (Required)
```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',
    enableLogging: true,
    timeout: 30000,
    retryAttempts: 3
  });
  
  console.log('SDK initialized successfully!');
} catch (error) {
  console.error('SDK initialization failed:', error.message);
}
```

### Step 2: Use Onairos Components
```typescript
import { OnairosButton } from 'onairos';

// Components automatically handle all 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)}
/>
```

### Step 2b: Auto Sign-In & Redirect (v5.2.3+) 🚀
For seamless integration with your app's authentication flow, use the new auto sign-in and redirect props:

```typescript
import { OnairosButton } from 'onairos';

// Automatic sign-in and redirect after Onairos completion
<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}
  // NEW: Auto sign-in and redirect props
  autoSignIn={true}              // Sets localStorage auth key after completion
  signInKey="authenticated"       // Custom key name (default: 'authenticated')
  redirectUrl="/dashboard"        // Redirect URL after completion
/>
```

**What happens when `autoSignIn` is enabled:**
1. User completes the Onairos data connection flow
2. SDK automatically sets `localStorage.setItem(signInKey, 'true')`
3. SDK also sets `localStorage.setItem('onairos_personalized', 'true')`
4. SDK stores user data in `localStorage.setItem('onairos_user_data', JSON.stringify(result))`
5. User is redirected to `redirectUrl` (if provided)

**Props Reference:**
- `autoSignIn` (boolean, default: false): Enable automatic localStorage auth setting
- `signInKey` (string, default: 'authenticated'): The localStorage key to set for your app's auth
- `redirectUrl` (string, optional): URL to redirect to after completion (e.g., '/home', '/dashboard')

**Example: Complete Integration**
```typescript
// Your sign-in page component
<OnairosButton
  requestData={{
    basic: { type: "basic", reward: "Access personalized content" },
    personality: { type: "personality", reward: "Better recommendations" }
  }}
  webpageName="MyEducationApp"
  autoSignIn={true}
  signInKey="know_authenticated"  // Match your app's existing auth key
  redirectUrl="/know.html"        // Your app's home/dashboard page
/>
```

Then in your dashboard/home page:
```typescript
// Check for Onairos personalization data
if (localStorage.getItem('onairos_personalized') === 'true') {
  // Show personalized content
  const userData = JSON.parse(localStorage.getItem('onairos_user_data'));
  enablePersonalizedView(userData);
}
```

## Error Handling & Retry Logic 🛡️

### API Key Validation Errors
```typescript
// Invalid format
throw new Error('Invalid API key format. Developer keys must be at least 32 characters and start with "dev_", "pk_", or "ona_"');

// Backend validation failure
throw new Error(`API key validation failed: ${validation.error}`);

// Rate limiting
throw new Error('API rate limit exceeded. Please try again later.');
```

### HTTP Request Errors
- **401 Unauthorized**: Invalid/expired API key or JWT token
- **403 Forbidden**: Insufficient permissions
- **429 Too Many Requests**: Rate limit exceeded
- **500 Server Error**: Backend service unavailable

### Automatic Retry Logic
- **Retry Attempts**: Configurable (default: 3)
- **Timeout**: Configurable (default: 30000ms)
- **Exponential Backoff**: For 429 and 5xx errors
- **JWT Auto-Clear**: Clears expired JWT tokens on 401

## Critical Success Factors
1. **Two-Tier Authentication**: Developer API keys → JWT tokens → User operations
2. **SDK Initialization**: Must call `initializeApiKey()` before using any components
3. **Environment Configuration**: Proper staging/production endpoint management
4. **Cross-Platform**: Same React code works in desktop browsers, mobile browsers, and React Native
5. **OAuth Reliability**: Auto-detects environment and uses appropriate OAuth flow
6. **JWT Token Management**: Automatic storage, loading, and cleanup of user sessions
7. **Mobile UX**: Touch-friendly UI with proper viewport handling
8. **Error Handling**: Comprehensive error states, retry logic, and user guidance

## TypeScript Support ✅
**Full TypeScript Support**: Complete type definitions provided in `onairos.d.ts`

**Usage with TypeScript**:
```typescript
import { OnairosButton } from 'onairos';
import type { OnairosProps } from 'onairos';

// Component usage with full type safety
const MyComponent: React.FC = () => {
  return (
    <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)}
    />
  );
};
```

**Common TypeScript Issues & Solutions**:
- **"Could not find declaration file"**: Fixed in v2.1.5 by adding `types` field to package.json exports
- **Import errors**: Always import from `'onairos'` (not specific paths)
- **Type inference**: All components have full TypeScript support with IntelliSense

## SDK Consistency Across Platforms 🔄

### For Other SDK Implementations
To ensure consistency across all Onairos SDKs, implement:

1. **Same API Key Formats**: `dev_`, `pk_`, `ona_` prefixes + 32+ character length
2. **Same Validation Endpoint**: `POST /auth/validate-key`  
3. **Same Headers Structure**: Authorization, X-API-Key-Type, X-SDK-Version, etc.
4. **Same Two-Tier Auth**: Developer keys → JWT tokens → User operations
5. **Same Error Handling**: 401, 403, 429 status codes with retry logic
6. **Same Caching**: 5-minute validation cache for API keys
7. **Same Admin Key**: `'OnairosIsAUnicorn2025'` for testing

### Environment Consistency
```typescript
// All SDKs should use the same endpoint structure
const endpoints = {
  production: 'https://api2.onairos.uk',
  staging: 'https://staging-api.onairos.uk',
  development: 'https://dev-api.onairos.uk'
};
```

## Build & Development
- **Build**: `npm run build` (creates dist/ folder)
- **Test Files**: Multiple test HTML files for different scenarios
- **Entry Points**: `src/index.js` (main), `src/onairos.native.jsx` (React Native)
- **Responsive**: Tailwind CSS with `sm:`, `md:`, `lg:` breakpoints throughout
- **TypeScript**: Full type definitions with proper package.json exports configuration
- **Authentication**: Two-tier system ensures secure and scalable API access