onairos/SDK_QUICK_REFERENCE.md

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

# SDK Quick Reference Guide

## 🚀 Essential Endpoints & Flows

### Base URL: `https://api2.onairos.uk`

---


## 🔐 Authentication Headers

```javascript
// Pattern 1: API Key + User JWT (Primary)
const headers = {
  'x-api-key': 'ona_your_32_character_api_key',
  'Authorization': `Bearer ${userJwtToken}`,
  'Content-Type': 'application/json'
};

// Pattern 2: User JWT Only (Enoch users)
const headers = {
  'Authorization': `Bearer ${userJwtToken}`,
  'Content-Type': 'application/json'
};

// Testing: Admin key bypasses validation
const adminKey = 'OnairosIsAUnicorn2025';
```

---


## 📧 Email Verification Flow

### Request Code
```http
POST /email/verification
{
  "email": "user@example.com",
  "action": "request"
}
```

### Verify Code & Get JWT
```http
POST /email/verification
{
  "email": "user@example.com", 
  "action": "verify",
  "code": "123456"
}
```

**Response (New User)**:
```json
{
  "success": true,
  "isNewUser": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "userName": "user123",
  "enochInstructions": {
    "recommendedFlow": "onboarding"
  }
}
```

**Response (Existing User)**:
```json
{
  "success": true,
  "isNewUser": false,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "existingUserData": {
    "hasExistingData": true,
    "summary": {
      "connectionsCount": 3,
      "traitsCount": 5
    }
  },
  "enochInstructions": {
    "recommendedFlow": "dashboard"
  }
}
```

---


## 🔒 PIN Management

### Store PIN
```http
POST /store-pin/mobile
Authorization: Bearer {userJwtToken}
{
  "username": "user123",
  "pin": "MySecure1!"
}
```

**PIN Requirements**: 8+ chars, 1 uppercase, 1 symbol

### Check PIN Status
```http
GET /store-pin/status/{username}
→ {"success": true, "hasPinStored": true}
```

---


## 🔗 OAuth Connectors

### YouTube Native Auth
```http
POST /youtube/native-auth
x-api-key: {apiKey}
Authorization: Bearer {userJwt}
{
  "userAccountInfo": {
    "username": "user123",
    "email": "user@example.com",
    "channelName": "My Channel",
    "channelId": "UCxxxxx"
  },
  "accessToken": "ya29.a0AfH6SMC...",
  "refreshToken": "4/0AX4XfWi...",
  "idToken": "eyJhbGciOiJSUzI1NiIs..."
}
```

**Critical OAuth Config**:
```javascript
{
  offlineAccess: true,
  forceCodeForRefreshToken: true,
  prompt: 'consent',
  scopes: ['https://www.googleapis.com/auth/youtube.readonly', 'openid', 'profile', 'email']
}
```

### Other Platforms
- **LinkedIn**: `POST /linkedin/authorize`
- **Reddit**: `POST /reddit/authorize`  
- **Pinterest**: `POST /pinterest/authorize`
- **Instagram**: `POST /instagram/authorize`

---


## 📊 Data Requests

### Get Data API URL
```http
POST /getAPIurlMobile
{
  "Info": {
    "storage": "local",
    "appId": "your_app_id",
    "confirmations": [{"data": "Large", "date": "2024-01-15T10:30:00Z"}],
    "EncryptedUserPin": "encrypted_pin_data",
    "account": "user123",
    "proofMode": false
  }
}
```

**Response**:
```json
{
  "apiUrl": "https://api2.onairos.uk/mobileInferenceNoProof",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}
```

### Get Traits
```http
POST /traits
Authorization: Bearer {inferenceToken}
→ {"traits": {"openness": 0.75, "conscientiousness": 0.68}}
```

### Mobile Inference
```http
POST /mobileInferenceNoProof
Authorization: Bearer {inferenceToken}
{"Input": "text_to_analyze"}
```

---


## 👤 User Data

### Connected Accounts
```http
GET /connected-accounts?username={username}
→ {
  "connectedAccounts": [
    {
      "platform": "YouTube",
      "accountName": "My Channel", 
      "status": "active",
      "hasData": true
    }
  ]
}
```

### Connection Health
```http
GET /youtube/connection-status/{username}
→ {
  "success": true,
  "connectionStatus": "healthy",
  "needsReauth": false,
  "tokenDetails": {
    "hasRefreshToken": true,
    "isExpired": false
  }
}
```

---


## 🏋️ Training & Models

### Training Progress (WebSocket)
```javascript
socket.emit('startTraining', {
  username: 'user123',
  encryptionMode: true,
  platforms: ['youtube', 'linkedin']
});

// Receive updates
socket.on('trainingUpdate', (data) => {
  console.log(`Progress: ${data.progress}% - ${data.stage}`);
});
```

### Download Model
```http
POST /mobile-training/download-model
Authorization: Bearer {userJwt}
→ {
  "model": "base64_encoded_model_data",
  "encryption": {"iv": "base64_iv", "key": "base64_key"}
}
```

---


## 🚨 Error Codes

| Code | Description | Action |
|------|-------------|---------|
| `MISSING_API_KEY` | No API key provided | Add x-api-key header |
| `INVALID_CODE` | Wrong verification code | Ask user to re-enter |
| `USER_NOT_FOUND` | User doesn't exist | Create new account |
| `PIN_REQUIRED` | PIN not set | Redirect to PIN setup |
| `RATE_LIMITED` | Too many requests | Wait and retry |

---


## 💻 Actual Implementation Patterns

### Direct API Calls (Your Actual Pattern)

```javascript
// 1. Email Verification (Direct)
const verifyEmail = async (email, code, apiKey) => {
  const response = await fetch('https://api2.onairos.uk/email/verification', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: email,
      action: 'verify',
      code: code
    })
  });
  return await response.json();
};

// 2. YouTube Mobile Signin (Your Actual Pattern)
const connectYouTubeMobile = async (tokens, username, apiKey) => {
  const response = await fetch('https://api2.onairos.uk/youtube/mobileSignin', {
    method: 'POST',
    headers: {
      'x-api-key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      idToken: tokens.idToken,
      accessToken: tokens.accessToken,
      serverAuthCode: tokens.serverAuthCode,
      username: username
    })
  });
  return await response.json();
};

// 3. Mobile Training (WebSocket + HTTP)
const startMobileTraining = async (userJwt, socketId, platforms) => {
  const response = await fetch('https://api2.onairos.uk/mobile-training/clean', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${userJwt}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      socketId: socketId,
      connectedPlatforms: platforms
    })
  });
  return await response.json();
};

// 4. Data Request (Your Info Pattern)
const requestDataAccess = async (userInfo) => {
  const response = await fetch('https://api2.onairos.uk/getAPIurlMobile', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Info: {
        storage: "local",
        appId: userInfo.appId,
        confirmations: userInfo.confirmations,
        EncryptedUserPin: userInfo.encryptedPin,
        account: userInfo.username,
        proofMode: false
      }
    })
  });
  return await response.json();
};

// 5. Mobile Model Download (Your Actual Pattern)
const downloadModel = async (username) => {
  const response = await fetch('https://api2.onairos.uk/sendMobileModel', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      Info: {
        username: username
      }
    })
  });
  return await response.json();
};
```

---


## ✅ Implementation Checklist

- [ ] **Auth**: Email verification + JWT storage
- [ ] **PIN**: Secure PIN storage with validation
- [ ] **OAuth**: Proper refresh token handling
- [ ] **Data**: Training + inference flows
- [ ] **Errors**: Handle all error codes gracefully
- [ ] **Testing**: Use admin key for development

---


### WebSocket Training Pattern
```javascript
// Complete training flow example
const runMobileTraining = async (jwtToken, username, platforms) => {
  // 1. Connect to WebSocket
  const socket = io('https://api2.onairos.uk');
  
  // 2. Set up listeners
  socket.on('trainingUpdate', (data) => {
    console.log(`Progress: ${data.progress}% - ${data.stage}`);
    updateTrainingUI(data);
  });
  
  socket.on('trainingCompleted', (data) => {
    console.log('Training completed!', data);
    showTrainingComplete(data);
  });
  
  // 3. Start training via HTTP
  const response = await fetch('https://api2.onairos.uk/mobile-training/clean', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      socketId: socket.id,
      connectedPlatforms: platforms
    })
  });
  
  return await response.json();
};
```

**Key Implementation Points:**
1. **Use direct fetch calls** - no SDK wrapper needed
2. **Follow Info pattern** for data requests: `{Info: {username: "..."}}`  
3. **WebSocket + HTTP combo** for training with real-time updates
4. **serverAuthCode is refresh token** in OAuth flows
5. **Store JWT securely** (Keychain/Keystore)
6. **Test with admin key** (`OnairosIsAUnicorn2025`) before production