# Onairos NPM Package - LLM Context

## Package Overview
- **Version**: 2.1.5
- **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`

## 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
- **Test Mode**: `api2.onairos.uk/inferenceTest`
- **Live Mode**: `api2.onairos.uk/getAPIurlMobile`
- **Email Verification**: `api2.onairos.uk/email/verify`
- **Training Routes**: `api2.onairos.uk/mobile-training/clean` (regular) or `/enoch` (advanced)

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

```javascript
import { initializeApiKey } from '@onairos/react-native';

// Initialize with developer key
await initializeApiKey({
  apiKey: 'dev_your_32_char_key_here',
  environment: 'production', // or 'development'
  enableLogging: true
});
```

**Configuration Options**:
- `apiKey`: Your 32-character developer key (format: `dev_your_32_char_key_here`)
- `environment`: `'production'` or `'development'` mode
- `enableLogging`: Boolean for debug logging

## Key Components
- **initializeApiKey**: API key setup function (must be called first)
- **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

## 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)
✅ Added mobile device detection for OAuth flows
✅ Implemented mobile OAuth redirect handling
✅ Enhanced OAuth URL parsing for all 9 platforms
✅ Added mobile browser compatibility documentation
✅ Fixed OAuth popup blocking on mobile devices
✅ Added API key initialization system for developer authentication
✅ Implemented environment-specific configuration (production/development)
✅ Added comprehensive logging system for debugging
✅ Fixed TypeScript declaration file resolution issue in package.json exports

## Usage Pattern
**Step 1: Initialize API Key (Required)**
```javascript
import { initializeApiKey } from '@onairos/react-native';

// Must be called before using any components
await initializeApiKey({
  apiKey: 'dev_your_32_char_key_here',
  environment: 'production',
  enableLogging: true
});
```

**Step 2: Use Onairos Components**
```javascript
import { OnairosButton } from 'onairos';

<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)}
/>
```

## Critical Success Factors
1. **API Key Setup**: Must call `initializeApiKey()` before using any components
2. **Cross-Platform**: Same React code works in desktop browsers, mobile browsers, and React Native
3. **OAuth Reliability**: Auto-detects environment and uses appropriate OAuth flow
4. **API Consistency**: All endpoints use `api2.onairos.uk` with proper authentication
5. **Mobile UX**: Touch-friendly UI with proper viewport handling
6. **Error Handling**: Comprehensive error states 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

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