# Onairos OAuth Integration Guide

This guide explains how to integrate the Onairos OAuth functionality into your Flutter application, focusing on connecting to various platforms like YouTube, Instagram, Pinterest, and Reddit.

## Overview

The Onairos package provides a streamlined OAuth connection flow that:
- Uses native SDKs when available (currently supported for YouTube via Google Sign-In)
- Falls back to web-based OAuth flows presented in a bottom modal overlay
- Maintains a consistent UI experience across all platforms
- Handles authentication tokens securely

## Setup Requirements

### 1. Update Dependencies

Add the Onairos package to your `pubspec.yaml`:

```yaml
dependencies:
  onairos: ^0.2.143  # Use the latest version
```

### 2. Platform-Specific Configuration

#### For YouTube/Google Sign-In:

**Android:**
Add to your `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET"/>
```

**iOS:**
Update your `ios/Runner/Info.plist`:

```xml
<!-- Google Sign-in Section -->
<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<!-- Replace with your reversed client ID -->
			<string>com.googleusercontent.apps.YOUR-CLIENT-ID</string>
		</array>
	</dict>
</array>
```

#### For Instagram:

The package uses the Opacity SDK for Instagram connections, which is already included as a dependency.

#### For Pinterest and Reddit:

No additional configuration is needed as these use web-based OAuth flows.

## Usage

### Universal Onboarding

The simplest way to integrate OAuth connections is through the Universal Onboarding component:

```dart
import 'package:flutter/material.dart';
import 'package:onairos/onairos.dart';

// Inside your widget
void showOnboarding() {
  showModalBottomSheet(
    context: context,
    isScrollControlled: true,
    backgroundColor: Colors.transparent,
    builder: (context) => UniversalOnboarding(
      platforms: ['youtube', 'instagram', 'pinterest', 'reddit'],
      onComplete: (connectedPlatforms) {
        // Handle connected platforms
        print('Connected platforms: $connectedPlatforms');
      },
    ),
  );
}
```

### Direct OAuth Service Usage

For more control, you can use the OAuthService directly:

```dart
import 'package:flutter/material.dart';
import 'package:onairos/services/oauth_service.dart';

// Inside your widget
final oauthService = OAuthService();

Future<void> connectToYouTube() async {
  final connected = await oauthService.connectYouTube(context);
  if (connected) {
    // Successfully connected
  } else {
    // Connection failed
  }
}

Future<void> connectToInstagram() async {
  final connected = await oauthService.connectInstagram(context);
  if (connected) {
    // Successfully connected
  } else {
    // Connection failed
  }
}

// Similar methods for Pinterest and Reddit
```

## UI Customization

All OAuth flows in the Onairos package follow the bottom modal overlay design pattern. The modals:

- Occupy a significant portion of the screen height
- Have rounded corners at the top
- Slide in from the bottom
- Include a security badge that fades out after a few seconds
- Provide visual feedback during the connection process

### Example: Customizing the Modal Height

When showing the Universal Onboarding or OAuth web view, you can customize the modal height:

```dart
showModalBottomSheet(
  context: context,
  isScrollControlled: true,
  backgroundColor: Colors.transparent,
  builder: (context) => FractionallySizedBox(
    heightFactor: 0.85, // Adjust this value to change the height
    child: UniversalOnboarding(
      platforms: ['youtube', 'instagram'],
      onComplete: (connectedPlatforms) {
        // Handle connected platforms
      },
    ),
  ),
);
```

## Error Handling

The OAuth service includes built-in error handling with user-friendly dialog prompts. However, you can also implement custom error handling:

```dart
try {
  final connected = await oauthService.connectYouTube(context);
  if (!connected) {
    // Show custom error UI
  }
} catch (e) {
  // Handle exceptions
  showDialog(
    context: context,
    builder: (context) => AlertDialog(
      title: Text('Connection Error'),
      content: Text('Failed to connect: $e'),
      actions: [
        TextButton(
          onPressed: () => Navigator.pop(context),
          child: Text('OK'),
        ),
      ],
    ),
  );
}
```

## Best Practices

1. **Always show OAuth flows in bottom modal overlays** to maintain consistency with the Onairos design language.

2. **Handle connection failures gracefully** by providing clear feedback to the user.

3. **Store tokens securely** using the secure storage provided by the package.

4. **Test connections thoroughly** across different platforms and devices.

5. **Update the Onairos package regularly** to get the latest improvements and security updates.

## Troubleshooting

### Common Issues

1. **OAuth flow not appearing in a bottom modal**
   - Make sure you're using `showModalBottomSheet` with `isScrollControlled: true` and `backgroundColor: Colors.transparent`.

2. **Google Sign-In not working**
   - Verify that you've added the correct configuration to your AndroidManifest.xml and Info.plist files.
   - Ensure you're using the latest version of the Onairos package.

3. **Web OAuth flow not completing**
   - Check your internet connection.
   - Verify that the OAuth provider's servers are operational.
   - Ensure that your OAuth credentials are correctly configured.

For additional support, please open an issue on the Onairos GitHub repository.
