@onairos/react-native 3.4.1 → 3.6.0

package/README.md

@@ -1,375 +1,424 @@
-# 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 (Instagram, Pinterest, Reddit, YouTube)
-- Secure credential management with biometric authentication
-- PIN-based security with validation
-- Deep linking support for OAuth callbacks
-- AI model training progress tracking
-- Customizable UI components
-- TypeScript support
-
-## Installation
-
-```bash
-npm install onairos-react-native
-# or
-yarn add onairos-react-native
-```
-
-### TypeScript Support
-
-The package includes full TypeScript declarations. Import types directly:
-
-```typescript
-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:
-
-```bash
-# 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:
-```bash
-cd ios && pod install
-```
-
-2. Add the following to your `Info.plist`:
-```xml
-<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`:
-```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:
-```xml
-<uses-permission android:name="android.permission.USE_BIOMETRIC" />
-```
-
-## Usage
-
-📖 **[Quick Integration Guide](./QUICK_INTEGRATION_GUIDE.md) - Start here for immediate copy-paste setup!**
-
-📖 **For comprehensive usage examples in both JavaScript and TypeScript, see [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md)**
-
-### Important: Setup Portal Host
-
-For modals and overlays to appear properly, you must wrap your app with the `PortalHost` component:
-
-```javascript
-import { PortalHost } from 'onairos-react-native';
-
-export default function App() {
-  return (
-    <PortalHost>
-      {/* Your app content goes here */}
-      <MainNavigator />
-    </PortalHost>
-  );
-}
-```
-
-### Basic Button Integration
-
-1. Import the OnairosButton component:
-```javascript
-import { OnairosButton } from 'onairos-react-native';
-```
-
-2. Use the component in your app:
-```javascript
-export default function App() {
-  const handleResolved = (apiUrl, accessToken, loginDetails) => {
-    console.log('Authentication successful:', { apiUrl, accessToken, loginDetails });
-    // Store the tokens and proceed with your app logic
-  };
-
-  return (
-    <View style={styles.container}>
-      <OnairosButton
-        AppName="YourApp"
-        requestData={{
-          "Social Media": {
-            "Profile Information": "Access to your basic profile data",
-            "Post History": "Access to your post history for analysis"
-          },
-          "Content": {
-            "Images": "Access to image data for AI training",
-            "Text": "Access to text data for AI training"
-          }
-        }}
-        returnLink="your-app://auth-callback"
-        onResolved={handleResolved}
-        buttonType="pill"
-        color="#00BFA5"
-      />
-    </View>
-  );
-}
-```
-
-### Initialize OAuth Service
-
-Add this to your app's entry point to handle deep linking for OAuth:
-
-```javascript
-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
-
-```javascript
-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.
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| AppName | string | Yes | Your application name |
-| requestData | object | Yes | Platform-specific OAuth scopes and data requests |
-| returnLink | string | Yes | Deep link URL for OAuth callback |
-| embedd | boolean | No | Whether to use embedded flow (default: false) |
-| color | string | No | Button color (default: #00BFA5) |
-| icon | string | No | Button icon name (default: 'auto_awesome') |
-| onResolved | function | Yes | Callback for successful auth with (apiUrl, accessToken, loginDetails) |
-| login | boolean | No | Enable login mode (default: false) |
-| buttonType | 'circle' \| 'pill' | No | Button style (default: 'circle') |
-| debug | boolean | No | Enable debug mode (default: false) |
-| test | boolean | No | Enable test mode (default: false) |
-
-#### `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 | Yes | Platform-specific OAuth scopes |
-| returnLink | string | Yes | Deep link URL for OAuth callback |
-| onComplete | function | Yes | Callback when onboarding is complete |
-| embedd | boolean | No | Whether to use embedded flow |
-| debug | boolean | No | Enable debug mode |
-| test | boolean | No | Enable test mode |
-
-#### `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:
-```bash
-git clone https://github.com/onairos/onairos-react-native.git
-cd onairos-react-native
-```
-
-2. Install dependencies:
-```bash
-yarn install
-```
-
-3. Run the typecheck:
-```bash
-yarn typecheck
-```
-
-### Building the Package
-
-```bash
-npm run build:all
-```
-
-### Testing with a Local App
-
-1. Link the package locally:
-```bash
-# 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
-
+# 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
+
+```bash
+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:
+
+```bash
+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`](./example/README.md) for detailed setup instructions.
+
+### TypeScript Support
+
+The package includes full TypeScript declarations. Import types directly:
+
+```typescript
+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:
+
+```bash
+# 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:
+```bash
+cd ios && pod install
+```
+
+2. Add the following to your `Info.plist`:
+```xml
+<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`:
+```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:
+```xml
+<uses-permission android:name="android.permission.USE_BIOMETRIC" />
+```
+
+## Usage
+
+📖 **[Quick Integration Guide](./QUICK_INTEGRATION_GUIDE.md) - Start here for immediate copy-paste setup!**
+
+📖 **For comprehensive usage examples in both JavaScript and TypeScript, see [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md)**
+
+### Important: Setup Portal Host
+
+For modals and overlays to appear properly, you must wrap your app with the `PortalHost` component:
+
+```javascript
+import { PortalHost } from '@onairos/react-native';
+
+export default function App() {
+  return (
+    <PortalHost>
+      {/* Your app content goes here */}
+      <MainNavigator />
+    </PortalHost>
+  );
+}
+```
+
+### Basic Button Integration
+
+1. Import the OnairosButton component:
+```javascript
+import { OnairosButton } from '@onairos/react-native';
+```
+
+2. Use the component in your app:
+```javascript
+export default function App() {
+  const handleResolved = (apiUrl, accessToken, loginDetails) => {
+    console.log('Authentication successful:', { apiUrl, accessToken, loginDetails });
+    // Store the tokens and proceed with your app logic
+  };
+
+  return (
+    <View style={styles.container}>
+      <OnairosButton
+        AppName="YourApp"
+        requestData={{
+          "Social Media": {
+            "Profile Information": "Access to your basic profile data",
+            "Post History": "Access to your post history for analysis"
+          },
+          "Content": {
+            "Images": "Access to image data for AI training",
+            "Text": "Access to text data for AI training"
+          }
+        }}
+        returnLink="your-app://auth-callback"
+        onResolved={handleResolved}
+        buttonType="pill"
+        color="#00BFA5"
+      />
+    </View>
+  );
+}
+```
+
+### Initialize OAuth Service
+
+Add this to your app's entry point to handle deep linking for OAuth:
+
+```javascript
+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
+
+```javascript
+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 | Yes | Platform-specific OAuth scopes and data requests |
+| returnLink | string | Yes | Deep link URL for OAuth callback |
+| embedd | boolean | No | Whether to use embedded flow (default: false) |
+| color | string | No | Button color (default: #00BFA5) |
+| icon | string | No | Button icon name (default: 'auto_awesome') |
+| onResolved | function | Yes | Callback for successful auth with (apiUrl, accessToken, loginDetails) |
+| login | boolean | No | Enable login mode (default: false) |
+| buttonType | 'circle' \| 'pill' | No | Button style (default: 'circle') |
+| debug | boolean | No | Enable debug mode (default: false) |
+| test | boolean | No | Enable test mode (default: false) |
+
+#### `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 | Yes | Platform-specific OAuth scopes |
+| returnLink | string | Yes | Deep link URL for OAuth callback |
+| onComplete | function | Yes | Callback when onboarding is complete |
+| embedd | boolean | No | Whether to use embedded flow |
+| debug | boolean | No | Enable debug mode |
+| test | boolean | No | Enable test mode |
+
+#### `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:
+```bash
+git clone https://github.com/onairos/onairos-react-native.git
+cd onairos-react-native
+```
+
+2. Install dependencies:
+```bash
+yarn install
+```
+
+3. Run the typecheck:
+```bash
+yarn typecheck
+```
+
+### Building the Package
+
+```bash
+npm run build:all
+```
+
+### Testing with a Local App
+
+1. Link the package locally:
+```bash
+# 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