onairos/README.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

# Onairos SDK v5.8

> **Connect user data to your applications with privacy-first identity sharing**

[![npm version](https://img.shields.io/npm/v/onairos.svg)](https://www.npmjs.com/package/onairos)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

The Onairos SDK enables applications to connect and communicate data with Onairos Identities via user authorization. Integration is seamless for React, Vue, Laravel, Framer, and mobile applications.

---

## ✨ Key Features

- **🔐 Privacy-First Data Sharing** - Users authorize exactly what data to share
- **⚛️ React 18 & 19 Support** - Full compatibility with latest React versions
- **📱 Mobile Ready** - Native Capacitor support for iOS & Android
- **🎨 Laravel Integration** - First-class Blade, Vue, and Vite support
- **🖼️ Framer Support** - No-build CDN integration for Framer projects
- **💬 Telegram Mini Apps** - Build data-connected Telegram bots
- **🔄 AutoFetch** - Automatic API calls after user approval
- **📝 TypeScript** - Full type definitions included
- **🎯 Test Mode** - Development testing without live data

---

## 📦 Installation

```bash
npm install onairos
```

### Peer Dependencies

```bash
# Required
npm install react react-dom

# Optional (for specific features)
npm install tailwindcss  # For styled components
npm install socket.io-client  # For real-time features
```

---

## 🚀 Quick Start

### 1. Create a Developer Account

Register at [onairos.uk/dev-board](https://onairos.uk/dev-board) to get your API key and register your domain.

### 2. Basic Usage (React)

```jsx
import { OnairosButton } from "onairos";

function App() {
  return (
    <OnairosButton
      requestData={["email", "profile", "social"]}
      webpageName="My Application"
      onComplete={(result) => {
        console.log("User data:", result.apiResponse);
        console.log("Token:", result.token);
      }}
    />
  );
}
```

That's it! The button handles authentication, user consent, and data retrieval automatically.

---

## 📖 Component Reference

### OnairosButton

The primary component for data requests.

```jsx
<OnairosButton
  // Required
  requestData={["basic", "personality", "preferences"]}  // Data options shown on consent screen
  webpageName="My App"                 // Your app name (shown to users)
  
  // Data fetching
  autoFetch={true}                     // Auto-fetch after approval (default: true)
  inferenceData={null}                 // Input for AI model (required if using inference + autoFetch)
  
  // Mode settings
  testMode={false}                     // Enable test mode for development
  proofMode={false}                    // Enable verification proofs
  
  // Button customization
  buttonType="pill"                    // "pill" | "icon" | "rectangle"
  buttonText="Connect Data"            // Custom button text
  showIcon={true}                      // Show/hide Onairos logo
  textColor="white"                    // "black" | "white"
  
  // Auto sign-in (optional)
  autoSignIn={false}                   // Set localStorage auth after completion
  signInKey="authenticated"            // localStorage key for auth state
  redirectUrl="/dashboard"             // Redirect after completion
  
  // Callbacks
  onComplete={(result) => {
    // Always available:
    console.log("Token:", result.token);
    console.log("API URL:", result.apiUrl);
    console.log("Approved:", result.approved);
    console.log("User Data:", result.userData);
    
    // Only when autoFetch=true:
    console.log("API Response:", result.apiResponse);
  }}
/>
```

### OnairosReconnectButton

Allow users to manage their connected data sources.

```jsx
import { OnairosReconnectButton } from "onairos";

<OnairosReconnectButton
  buttonText="Manage Data Sources"
  appName="My App"
  buttonClass="custom-button-class"
  
  onComplete={(result) => {
    console.log("Connected accounts:", result.connectedAccounts);
    console.log("User data:", result.userData);
  }}
  
  onNoUserData={() => {
    console.log("No existing user data found");
  }}
/>
```

---

## 📊 requestData & inferenceData

### requestData

Defines what data options appear on the consent screen. Users can toggle these on/off.

| Type | Description |
|------|-------------|
| `basic` | Basic profile information (required, always on) |
| `preferences` | User preferences towards your app |
| `personality` | Personality traits and interests |
| `rawMemories` | Raw LLM data from connected AI apps (ChatGPT, Claude, etc.) |

### inferenceData (for AI-powered recommendations)

If your `requestData` includes inference types (`personality`, `preferences`) AND `autoFetch=true`, you should provide `inferenceData` - the input for the AI model to generate personalized recommendations.

```jsx
// ⚠️ IMPORTANT: If requestData includes inference types AND autoFetch=true,
//    provide inferenceData for AI recommendations

<OnairosButton
  requestData={["basic", "personality", "preferences"]}
  webpageName="My Store"
  autoFetch={true}
  inferenceData={[
    { text: "Wireless Headphones", category: "Electronics" },
    { text: "Running Shoes", category: "Sports" },
    { text: "Coffee Maker", category: "Kitchen" }
  ]}
  onComplete={(result) => {
    // result.apiResponse contains personalized recommendations
    console.log(result.apiResponse);
  }}
/>
```

### autoFetch Behavior

| Scenario | What Happens |
|----------|--------------|
| `autoFetch=true` + `inferenceData` provided | SDK fetches personalized inference results |
| `autoFetch=true` + no `inferenceData` | SDK falls back to traits-only (no inference) |
| `autoFetch=false` | SDK returns `token` + `apiUrl` for you to make your own API call |

### onComplete Result Object

```typescript
{
  token: string;           // JWT for API authentication (always included)
  apiUrl: string;          // API endpoint (always included)
  approved: string[];      // Data types user approved (always included)
  userData: object;        // User data including email, connectedAccounts
  apiResponse?: object;    // Fetched data (only when autoFetch=true)
}
```

### Copy-Paste Templates

**Standard (traits only):**
```jsx
<OnairosButton
  requestData={["basic", "personality"]}
  webpageName="My App"
  autoFetch={true}
  onComplete={(result) => {
    console.log("Traits:", result.apiResponse);
  }}
/>
```

**Inference + autoFetch (AI recommendations):**
```jsx
<OnairosButton
  requestData={["basic", "personality", "preferences"]}
  webpageName="My Store"
  autoFetch={true}
  inferenceData={[
    { text: "Product 1", category: "Category A" },
    { text: "Product 2", category: "Category B" }
  ]}
  onComplete={(result) => {
    console.log("Recommendations:", result.apiResponse);
  }}
/>
```

**Manual fetch (host app makes API call):**
```jsx
<OnairosButton
  requestData={["basic", "personality"]}
  webpageName="My App"
  autoFetch={false}
  onComplete={(result) => {
    // Make your own API call with the token and URL
    fetch(result.apiUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${result.token}`
      },
      body: JSON.stringify({
        email: result.userData.email,
        approved: result.approved
      })
    });
  }}
/>
```

---

## 🔧 Platform Integrations

### Laravel + Blade

```js
// vite.config.js
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import { onairosLaravelPlugin } from "onairos/vite-plugin";

export default defineConfig({
  plugins: [
    laravel({
      input: ["resources/css/app.css", "resources/js/app.js"],
      refresh: true,
    }),
    onairosLaravelPlugin({ bladeSupport: true }),
  ],
});
```

```js
// resources/js/app.js
import { initializeOnairosForBlade } from "onairos/blade";

document.addEventListener("DOMContentLoaded", () => {
  initializeOnairosForBlade({
    testMode: import.meta.env.DEV,
    autoDetectMobile: true,
  });
});
```

```blade
{{-- resources/views/dashboard.blade.php --}}
<div id="onairos-button"></div>

<script>
createOnairosButton('onairos-button', {
    requestData: ['email', 'profile'],
    webpageName: 'My Laravel App',
    onComplete: function(result) {
        console.log('Connection successful!', result);
    }
});
</script>
```

### Laravel + Vue

```js
// vite.config.js
import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import vue from "@vitejs/plugin-vue";
import { onairosVuePlugin } from "onairos/vite-plugin";

export default defineConfig({
  plugins: [
    laravel({
      input: ["resources/css/app.css", "resources/js/app.js"],
      refresh: true,
    }),
    vue(),
    onairosVuePlugin(),
  ],
});
```

```vue
<!-- In your Vue component -->
<template>
  <onairos-button
    :request-data="['email', 'profile']"
    webpage-name="Laravel Vue App"
    @complete="handleComplete"
  />
</template>
```

### Capacitor (iOS/Android)

Capacitor requires one-time native setup for Google Sign-In and native ChatGPT import:

```bash
npm install onairos @capgo/capacitor-social-login @onairosofficial/capacitor-llm-onairos
npx cap sync ios
```

Then initialize the SDK before rendering `OnairosButton`:

```jsx
import { initializeApiKey, OnairosButton } from "onairos";

window.onairosOAuthReturnOrigin = "myapp://auth/callback";

await initializeApiKey({
  apiKey: "YOUR_ONAIROS_KEY",
  environment: "production",
  platform: "capacitor-ios",
  googleClientIds: {
    webClientId: "your-web-client-id.apps.googleusercontent.com",
    iosClientId: "your-ios-client-id.apps.googleusercontent.com",
    serverClientId: "your-server-client-id.apps.googleusercontent.com",
  },
});

function MobileApp() {
  return (
    <OnairosButton
      requestData={["email", "profile", "social"]}
      webpageName="My Mobile App"
      onComplete={(result) => {
        console.log("User data:", result.apiResponse);
      }}
    />
  );
}
```

**Mobile Notes:**
- ✅ OAuth flows use mobile-friendly redirects (not popups)
- ✅ Touch interactions fully supported
- ✅ Tested on iOS 13+ and Android 8+

#### iOS URL Schemes

Your iOS app must register two URL schemes in `Info.plist`:

1. The reversed Google iOS client ID scheme for native Google Sign-In
2. Your app callback scheme, which must match `window.onairosOAuthReturnOrigin`

Example:

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.googleusercontent.apps.1234567890-abcdefg</string>
    </array>
  </dict>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>
```

The Onairos callback scheme is not a fixed global scheme. It is your app's own deep-link return path. `onairosevents://auth/callback` is only the sample app value used in `mobile-preview`.

#### Why The Callback Scheme Exists

This is standard for native mobile OAuth flows. After Google Sign-In or a browser-based return step finishes, iOS needs a registered app URL scheme to reopen your app and hand control back to the SDK.

### Vite Configuration

For Vite applications, exclude onairos from optimization:

```ts
// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ["onairos"],
  },
});
```

### Framer (No-Build Integration)

Perfect for Framer projects - no package manager needed! Uses CDN loading:

```typescript
import { addPropertyControls, ControlType } from "framer"
import { useEffect, useState } from "react"

export default function OnairosConnect(props) {
    const [OnairosButton, setOnairosButton] = useState(null)

    useEffect(() => {
        const script = document.createElement("script")
        script.src = "https://unpkg.com/onairos@latest/dist/onairos.bundle.js"
        script.onload = () => setOnairosButton(() => window.Onairos.OnairosButton)
        document.head.appendChild(script)
    }, [])

    return (
        <>
            <link rel="stylesheet" href="https://unpkg.com/onairos@latest/dist/onairos.css" />
            {OnairosButton && (
                <OnairosButton
                    requestData={props.requestData}
                    webpageName={props.webpageName}
                    testMode={props.testMode}
                    onComplete={(result) => console.log(result)}
                />
            )}
        </>
    )
}
```

**📖 [Complete Framer Integration Guide →](./FRAMER_INTEGRATION.md)**

**Framer Notes:**
- ✅ No dependencies to install - works with CDN
- ✅ Full property controls in Framer UI
- ✅ Copy-paste ready Code Component
- ✅ Mobile-responsive out of the box

---

## 🔌 Platform Management API

### Disconnect Platforms

```typescript
import { disconnectPlatform, disconnectMultiplePlatforms } from "onairos";

// Disconnect a single platform
const result = await disconnectPlatform("youtube", "user@example.com");
if (result.success) {
  console.log("YouTube disconnected successfully");
}

// Disconnect multiple platforms
const results = await disconnectMultiplePlatforms(
  ["youtube", "reddit", "linkedin"],
  "user@example.com"
);
console.log(`Disconnected ${results.successful.length} platforms`);
```

### Check Platform Support

```typescript
import { getSupportedPlatforms, isPlatformSupported } from "onairos";

const platforms = getSupportedPlatforms();
console.log("Supported platforms:", platforms);

if (isPlatformSupported("youtube")) {
  // YouTube is available
}
```

---

## ⚙️ OAuth Configuration

### Google OAuth

```typescript
import { updateGoogleClientIds, getGoogleClientIds } from "onairos";

// Configure Google OAuth (required for Google Sign-In)
updateGoogleClientIds({
  webClientId: "your-web-client-id.apps.googleusercontent.com",
  iosClientId: "your-ios-client-id.apps.googleusercontent.com",
});

// Get current configuration
const clientIds = getGoogleClientIds();
```

### YouTube OAuth

```typescript
import { updateYoutubeClientId, getYoutubeClientId } from "onairos";

// Configure YouTube OAuth (separate from Google Sign-In)
updateYoutubeClientId("your-youtube-client-id.apps.googleusercontent.com");
```

---

## 🔍 TypeScript Support

Full TypeScript definitions are included:

```typescript
import { 
  OnairosButton, 
  OnairosCompleteData,
  OnairosProps,
  DisconnectPlatformResponse 
} from "onairos";

const handleComplete = (data: OnairosCompleteData) => {
  // TypeScript knows all available properties
  const { token, apiUrl, approvedData, userData } = data;
  
  if (data.apiResponse) {
    // Process API response
  }
};
```

### Key Types

```typescript
interface OnairosCompleteData {
  token: string;              // JWT for authenticated requests
  apiUrl: string;             // API endpoint URL
  userHash?: string;          // Unique user identifier
  approvedData?: string[];    // Approved data types
  apiResponse?: any;          // API response data
  userData?: any;             // User profile data
  success?: boolean;          // Request success status
  error?: string;             // Error message if failed
}
```

---

## 🌐 Browser & Platform Compatibility

| Platform | Version |
|----------|---------|
| Chrome | 80+ |
| Firefox | 75+ |
| Safari | 13+ |
| Edge | 80+ |
| iOS Safari | 13+ |
| Chrome Mobile | Latest |
| Capacitor | iOS 13+ / Android 8+ |
| React | 18.x, 19.x |
| Framer | All versions |
| Tailwind CSS | 3.x, 4.x |

---

## 🐛 Troubleshooting

### Popup Blocked
Ensure popups are allowed for your domain. On mobile, OAuth automatically uses redirects.

### API Calls Failing
- Verify your domain is registered in the [developer portal](https://onairos.uk/dev-board)
- Check that your API key is valid
- Ensure HTTPS is used in production

### Mobile Issues
- OAuth flows automatically convert to redirects on mobile
- Ensure localStorage is enabled in Capacitor configuration

### Tailwind CSS Conflicts
The SDK is compatible with both Tailwind v3 and v4. No special configuration needed.

---

## 📚 Additional Resources

- **Developer Portal**: [onairos.uk/dev-board](https://onairos.uk/dev-board)
- **Homepage**: [onairos.uk](https://onairos.uk)
- **Issues**: [GitHub Issues](https://github.com/zd819/OnairosNPM/issues)

---

## 📄 License

Apache-2.0 © Zion Darko