npm package: @suada/react-native
Description: React Native components for Suada integrations
Latest version: 1.0.0-rc.18

# @suada/react-native

React Native components and hooks for Suada integrations. This package provides ready-to-use React Native components that integrate with @suada/core.

## Installation

```bash
npm install @suada/react-native @suada/core
```

## Setup

1. Initialize the Suada provider in your app:

```tsx
import { SuadaProvider } from '@suada/react-native';

function App() {
  return (
    <SuadaProvider
      config={{
        apiKey: 'your-api-key',
        organizationId: 'your-organization-id' // Optional
      }}
    >
      <YourApp />
    </SuadaProvider>
  );
}
```

2. Use Suada components in your screens:

```tsx
import { IntegrationButton, IntegrationList } from '@suada/react-native';

function IntegrationsScreen() {
  const handleSuccess = (result) => {
    console.log('Integration successful:', result);
  };

  const handleError = (error) => {
    console.error('Integration failed:', error);
  };

  return (
    <View style={styles.container}>
      {/* Integration Button */}
      <IntegrationButton
        provider="notion"
        redirectUri="your-app://callback"
        onSuccess={handleSuccess}
        onError={handleError}
      >
        Connect Notion
      </IntegrationButton>

      {/* Integration List */}
      <IntegrationList
        filter={{ provider: 'notion' }}
        onSelect={handleIntegrationSelect}
      />
    </View>
  );
}
```

## Components

### IntegrationButton
A button component that handles the OAuth flow for integrations.

#### Props
- `provider: string` - The integration provider (e.g., 'notion')
- `redirectUri: string` - The OAuth callback URL
- `children: ReactNode` - Button content
- `style?: StyleProp<ViewStyle>` - Optional custom styles
- `textStyle?: StyleProp<TextStyle>` - Optional text styles
- `loading?: boolean` - Show loading state

#### Events
- `onSuccess: (result: IntegrationResult) => void` - Called when integration is successful
- `onError: (error: Error) => void` - Called when an error occurs
- `onPress: () => void` - Called when the button is pressed

### IntegrationList
A component that displays a list of integrated services.

#### Props
- `filter?: IntegrationFilter` - Optional filter for the integrations list
- `layout?: 'grid' | 'list'` - Display layout (default: 'grid')
- `loading?: boolean` - Show loading state
- `style?: StyleProp<ViewStyle>` - Container styles
- `itemStyle?: StyleProp<ViewStyle>` - Individual item styles

#### Events
- `onSelect: (integration: Integration) => void` - Called when an integration is selected
- `onDelete: (integration: Integration) => void` - Called when an integration is deleted

## Hooks

### useSuada
Hook for accessing the Suada client instance and integration state.

```tsx
import { useSuada } from '@suada/react-native';

function YourComponent() {
  const { client, integrations, loading, error } = useSuada();

  const connectNotion = async () => {
    try {
      const authUrl = await client.initializeOAuth('notion', {
        redirectUri: 'your-app://callback'
      });
      // Handle opening authUrl (e.g., using Linking)
    } catch (error) {
      console.error('Failed to initialize OAuth:', error);
    }
  };

  return (
    <View>
      {loading ? (
        <ActivityIndicator />
      ) : (
        <Button title="Connect Notion" onPress={connectNotion} />
      )}
    </View>
  );
}
```

### useIntegration
Hook for managing a specific integration.

```tsx
import { useIntegration } from '@suada/react-native';

function NotionIntegration() {
  const { 
    integration,
    loading,
    error,
    connect,
    disconnect
  } = useIntegration('notion');

  return (
    <View>
      {integration ? (
        <Button title="Disconnect" onPress={disconnect} />
      ) : (
        <Button title="Connect" onPress={connect} />
      )}
    </View>
  );
}
```

## Deep Linking Setup

### iOS
Add the URL scheme to your Info.plist:

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>your-app</string>
    </array>
  </dict>
</array>
```

### Android
Add the intent filter to your 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="your-app" />
  </intent-filter>
</activity>
```

## Error Handling

The package includes typed error classes for better error handling:

```tsx
import { SuadaAuthError, SuadaApiError } from '@suada/react-native';

try {
  await integration.connect();
} catch (error) {
  if (error instanceof SuadaAuthError) {
    // Handle authentication errors
  } else if (error instanceof SuadaApiError) {
    // Handle API errors
  }
}
```

## Platform Support

- iOS 13+
- Android API Level 21+
- Expo SDK 49+

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run type checking
npm run typecheck
```

## 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