Onairos React Native SDK

A React Native SDK for integrating Onairos authentication and AI model training into your mobile applications. This package provides a complete solution for social media platform connection, secure authentication, and AI model training.

Features

• Universal onboarding flow with multi-platform support
• Multi-platform OAuth authentication (Pinterest, YouTube, LinkedIn, Gmail, Reddit)
• Real-time AI model training with Socket.io integration
• Secure credential management with biometric authentication
• PIN-based security with validation and encryption
• Deep linking support for OAuth callbacks
• Email verification and account management
• Existing user detection and data confirmation
• Background training optimization
• Comprehensive error handling and retry logic
• Haptic feedback integration
• Customizable UI components
• Full TypeScript support

Installation

npm install @onairos/react-native
# or
yarn add @onairos/react-native

🎯 Example App

A complete example app is available in the example/ directory demonstrating real-world SDK integration:

cd example
npm install
npm run ios  # or npm run android

The example app showcases:

• ✅ SDK initialization and configuration
• ✅ OnairosButton component integration
• ✅ WelcomeScreen component usage
• ✅ Custom styling options
• ✅ JWT token handling and user data extraction
• ✅ Error handling and debugging

See example/README.md for detailed setup instructions.

TypeScript Support

The package includes full TypeScript declarations. Import types directly:

import { OnairosButton, OnairosCredentials, PlatformConfig } from '@onairos/react-native';

// Type your component props
const MyComponent: React.FC<{ credentials: OnairosCredentials }> = ({ credentials }) => {
  // Your component code
};

// Type your handlers
const handleResolved = (apiUrl: string, accessToken: string, loginDetails: any) => {
  console.log('Authentication successful:', { apiUrl, accessToken, loginDetails });
};

Required Dependencies

The package requires the following dependencies:

# Core dependencies
yarn add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-safe-area-context

# Authentication dependencies
yarn add react-native-webview react-native-keychain 

# UI dependencies
yarn add react-native-vector-icons

# Network and encryption
yarn add @react-native-community/netinfo react-native-rsa-native react-native-crypto-js

iOS Setup

1. Install pods:

cd ios && pod install

2. Add the following to your Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <!-- <string>onairosreact</string> -->
      <string>onairosanime</string>
    </array>
  </dict>
</array>

<!-- Add for biometric authentication -->
<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to securely access your Onairos account</string>

3. Configure your OAuth providers in the project settings and register the callback URLs.

Android Setup

1. Add the following to your android/app/src/main/AndroidManifest.xml:

<activity>
  <!-- ... -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- <data android:scheme="onairosreact" /> -->
    <data android:scheme="onairosanime" />
  </intent-filter>
</activity>

2. Add biometric permissions:

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

Usage

📖 Quick Integration Guide - Start here for immediate copy-paste setup!

📖 For comprehensive usage examples in both JavaScript and TypeScript, see USAGE_EXAMPLES.md

Important: Setup Portal Host

For modals and overlays to appear properly, you must wrap your app with the PortalHost component:

import { PortalHost } from '@onairos/react-native';

export default function App() {
  return (
    <PortalHost>
      {/* Your app content goes here */}
      <MainNavigator />
    </PortalHost>
  );
}

Basic Button Integration

1. Import and initialize the SDK:

import { OnairosButton, initializeApiKey } from '@onairos/react-native';

// Initialize once at app startup
await initializeApiKey({ apiKey: 'YOUR_API_KEY' });

2. Use the component in your app:

export default function App() {
  const handleComplete = (result) => {
    console.log('API URL:', result.apiUrl);
    console.log('Token:', result.token);
    console.log('User data:', result.apiResponse);
    console.log('Authorized data:', result.authorizedData);
    // authorizedData = { basic: true, personality: true, preferences: true, ... }
  };

  return (
    <View style={styles.container}>
      <OnairosButton
        AppName="YourApp"
        autoFetch={true}
        onComplete={handleComplete}
        requestData={{
          personality: {
            name: 'Personality Traits',
            description: 'Your personality profile',
          },
          preferences: {
            name: 'Content Analysis',
            description: 'Inference and sentiment',
          },
        }}
      />
    </View>
  );
}

External Auth Token Support

If your app already handles authentication, pass the user JWT to SDK APIs:

import { setUserToken, clearUserToken } from '@onairos/react-native';

// After your app login succeeds
await setUserToken(userJwtToken);

// Later, when user logs out
await clearUserToken();

Security-migrated backend routes (/sendModel, /updateAccountInfo, /inferenceUsername) now require this user JWT and ignore username fields sent in request bodies.

requestData Configuration

The requestData prop controls which consent options appear on the DataRequest screen.

Valid keys: | Key | Description | When Shown | |-----|-------------|------------| | basic | Basic profile info | Always shown | | personality | Personality traits (LLM profile) | If included | | preferences | Inference/sentiment (ML model) | If included | | rawMemories | Raw LLM conversation data | If included AND LLM connected |

Supported formats:

// Object format (full control)
requestData={{
  personality: { name: 'Personality', description: '...' },
  preferences: { name: 'Content Analysis', description: '...' },
}}

// Array format (uses SDK default descriptions)
requestData={['personality', 'preferences']}

Note: If requestData is not provided, only "Basic Profile" is shown and a warning is logged.

Initialize OAuth Service

Add this to your app's entry point to handle deep linking for OAuth:

import { initializeOAuthService } from '@onairos/react-native';

// In your app's entry point
useEffect(() => {
  // Set up OAuth deep linking
  initializeOAuthService();
  
  // Clean up when component unmounts
  return () => {
    cleanupOAuthService();
  };
}, []);

Working with Secure Storage

import { storeCredentials, getCredentials, hasCredentials } from '@onairos/react-native';

// Check if user has stored credentials
const checkAuth = async () => {
  const hasExisting = await hasCredentials();
  
  if (hasExisting) {
    // Get credentials with biometric authentication
    const credentials = await getCredentials({
      useBiometrics: true,
      biometricPrompt: {
        title: 'Authenticate to continue',
        subtitle: 'Please verify your identity'
      }
    });
    
    if (credentials) {
      // User is authenticated
      console.log('User authenticated:', credentials.username);
    }
  } else {
    // Redirect to onboarding flow
    setShowOnboarding(true);
  }
};

API Reference

Main Components

OnairosButton

The main entry point for Onairos authentication with full training flow support.

| Prop | Type | Required | Description | |------|------|----------|-------------| | AppName | string | Yes | Your application name | | requestData | object/array | Yes | Consent options to show (see below) | | onComplete | function | Yes | Callback with OnairosResult object | | autoFetch | boolean | No | Auto-fetch approved data after consent (default: true) | | backgroundLoadData | boolean | No | Skip SDK training UI and return training metadata for host-side handling (default: false) | | trainingScreenMode | 'mock' | 'fast' | 'real' | 'none' | No | Training UI behavior. Defaults to fast, or none when backgroundLoadData=true | | appIcon | ImageSource | No | Your app icon for onboarding UI | | buttonType | 'circle' | 'pill' | No | Button style (default: 'circle') | | color | string | No | Button color (default: #00BFA5) | | debug | boolean | No | Enable debug mode (default: false) |

requestData keys: basic (always shown), personality, preferences, rawMemories

onComplete(result) is the primary completion callback. onResolved(apiUrl, token, userData) is still supported for older integrations, but new code should use onComplete.

When autoFetch=false, the SDK returns apiUrl, token, consent/authorization metadata, and training metadata so the host app can fetch final data itself.

OnairosResult:

{
  apiUrl: string;
  token: string;
  userData: object;
  apiResponse?: object;       // If autoFetch=true
  authorizedData?: object;    // What user consented to
  training?: { ready: boolean; statusUrl?: string; pollIntervalMs?: number };
}

UniversalOnboarding

The universal onboarding flow component.

| Prop | Type | Required | Description | |------|------|----------|-------------| | visible | boolean | Yes | Whether the onboarding is visible | | onClose | function | Yes | Callback when onboarding is closed | | AppName | string | Yes | Your application name | | requestData | object/array | Yes | Consent options: basic, personality, preferences, rawMemories | | onComplete | function | Yes | Callback with (apiUrl, token, userData) | | autoFetch | boolean | No | Auto-fetch approved data after consent (default: true) | | backgroundLoadData | boolean | No | Skip SDK training UI and return training metadata for host-side handling (default: false) | | trainingScreenMode | 'mock' | 'fast' | 'real' | 'none' | No | Training UI behavior. Defaults to fast, or none when backgroundLoadData=true | | debug | boolean | No | Enable debug mode (default: false) |

TrainingModal

Email authentication and training progress modal.

| Prop | Type | Required | Description | |------|------|----------|-------------| | visible | boolean | Yes | Whether the modal is visible | | onCancel | function | Yes | Callback when modal is cancelled | | onComplete | function | Yes | Callback when training is complete | | modelKey | string | No | Model key for training | | username | string | No | Username for training | | isPrimaryAuth | boolean | No | Whether this is primary authentication | | autoFocusEmailInput | boolean | No | Auto-focus email input on show |

WelcomeScreen

New welcome flow component with modern UI.

| Prop | Type | Required | Description | |------|------|----------|-------------| | visible | boolean | Yes | Whether the screen is visible | | onClose | function | Yes | Callback when screen is closed | | onComplete | function | Yes | Callback when flow is complete |

Overlay

Data request overlay component.

| Prop | Type | Required | Description | |------|------|----------|-------------| | visible | boolean | Yes | Whether the overlay is visible | | onClose | function | Yes | Callback when overlay is closed | | onAccept | function | Yes | Callback when request is accepted | | AppName | string | Yes | Your application name | | requestData | object | Yes | Data being requested | | biometricType | 'FaceID' | 'TouchID' | 'BiometricID' | No | Type of biometric auth to use |

Utility Functions

Secure Storage

• storeCredentials(credentials, options): Store credentials securely
• getCredentials(options): Retrieve credentials with optional biometric auth
• hasCredentials(): Check if user has stored credentials
• deleteCredentials(): Delete stored credentials
• updateCredentials(updates, options): Update specific fields in credentials
• generateDeviceUsername(): Generate a device-specific unique username
• verifyCredentials(credentials): Verify if credentials are valid

OAuth Service

• connectPlatform(platform): Initiate OAuth flow for a specific platform
• disconnectPlatform(platform, credentials): Disconnect a platform
• initializeOAuthService(): Initialize OAuth service handlers
• cleanupOAuthService(): Clean up OAuth service handlers
• storePlatformConnection(platform, connectionData, credentials): Store platform connection

API Communication

• validateCredentials(username, options): Validate user credentials with the API
• createAccount(credentials, options): Create a new user account
• authenticate(credentials, options): Authenticate with the API using credentials
• refreshToken(refreshToken, options): Refresh authentication token
• getPlatformData(accessToken, platform, options): Get user's connected platform data
• getUserProfile(accessToken, options): Get user profile information
• updatePlatformConnections(accessToken, platforms, options): Update user platform connections

Development and Testing

Setup Development Environment

1. Clone the repository:

git clone https://github.com/onairos/onairos-react-native.git
cd onairos-react-native

2. Install dependencies:

yarn install

3. Run the typecheck:

yarn typecheck

Building the Package

npm run build:all

Testing with a Local App

1. Link the package locally:

# In your package directory
yarn link

# In your app directory
yarn link @onairos/react-native

2. Run your app and test the integration.

Troubleshooting

OAuth Callback Issues

• Ensure your deep link schemes are properly configured in both iOS and Android
• Check that the callback URLs match what's registered with your OAuth providers
• Ensure all required permissions are enabled in your app configurations

Biometric Authentication Issues

• Ensure proper permissions are set in Info.plist and AndroidManifest.xml
• Test on physical devices as simulators may not support all biometric features
• For iOS, ensure that Face ID/Touch ID is enabled and set up on the device

Platform Specific Issues

iOS

• For keychain issues, check that the Keychain Sharing capability is enabled
• Ensure the bundle identifier is consistent with your OAuth configuration

Android

• For deep linking issues, check the androidManifest.xml configuration
• Ensure that biometric hardware is available on test devices

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT