@umituz/react-native-auth 3.4.31 → 3.4.33

package/src/presentation/hooks/useSocialLogin.md

@@ -1,411 +1,381 @@
 # Social Login Hooks
 
-Google ve Apple ile social authentication işlemleri için hooks.
-
-## Hooks
-
-- **[`useSocialLogin`](#usesociallogin)** - Genel social login yönetimi
-- **[`useGoogleAuth`](#usegoogleauth)** - Google ile giriş (OAuth flow)
-- **[`useAppleAuth`](#useappleauth)** - Apple ile giriş
+Hooks for Google and Apple social authentication.
 
 ---
 
 ## useSocialLogin
 
-Genel social login işlevselliği sağlar. `@umituz/react-native-firebase` paketinin `useSocialAuth` hook'unu wrap'ler.
+General social login functionality wrapper.
+
+### Strategy
 
-### Kullanım
+**Purpose**: Provides unified interface for Google and Apple social authentication by wrapping `@umituz/react-native-firebase`'s `useSocialAuth`.
 
+**When to Use**:
+- Need both Google and Apple auth
+- Want unified social auth interface
+- Prefer single hook for multiple providers
+- Don't need provider-specific features
+
+**Import Path**:
 ```typescript
 import { useSocialLogin } from '@umituz/react-native-auth';
-
-function LoginScreen() {
-  const {
-    signInWithGoogle,
-    signInWithApple,
-    googleLoading,
-    appleLoading,
-    googleConfigured,
-    appleAvailable,
-  } = useSocialLogin({
-    google: {
-      webClientId: 'your-web-client-id.apps.googleusercontent.com',
-      iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
-    },
-    apple: { enabled: true },
-  });
-
-  return (
-    <View>
-      <Button
-        onPress={signInWithGoogle}
-        disabled={googleLoading || !googleConfigured}
-      >
-        {googleLoading ? 'Giriş yapılıyor...' : 'Google ile Giriş'}
-      </Button>
-
-      <Button
-        onPress={signInWithApple}
-        disabled={appleLoading || !appleAvailable}
-      >
-        {appleLoading ? 'Giriş yapılıyor...' : 'Apple ile Giriş'}
-      </Button>
-    </View>
-  );
-}
 ```
 
-### API
+**Hook Location**: `src/presentation/hooks/useSocialLogin.ts`
 
-#### Parameters
+**Dependency**: `@umituz/react-native-firebase`
 
-| Param | Tip | Açıklama |
-|-------|------|----------|
-| `config` | `UseSocialLoginConfig` | Social auth konfigürasyonu |
+### Rules
 
-#### UseSocialLoginConfig
+**MUST**:
+- Configure provider settings before use
+- Check provider availability before showing buttons
+- Handle loading states appropriately
+- Display errors to users
+- Check `googleConfigured` before using Google
+- Check `appleAvailable` before using Apple
 
-```typescript
-interface UseSocialLoginConfig {
-  google?: {
-    iosClientId?: string;
-    webClientId?: string;
-    androidClientId?: string;
-  };
-  apple?: {
-    enabled: boolean;
-  };
-}
-```
+**MUST NOT**:
+- Show unavailable provider buttons
+- Assume provider is configured
+- Ignore loading states
+- Bypass error handling
 
-#### Return Value
+### Constraints
 
-| Prop | Tip | Açıklama |
-|------|-----|----------|
-| `signInWithGoogle` | `() => Promise<SocialAuthResult>` | Google ile giriş (Not: `useGoogleAuth` kullanın) |
-| `signInWithApple` | `() => Promise<SocialAuthResult>` | Apple ile giriş |
-| `googleLoading` | `boolean` | Google giriş loading durumu |
-| `appleLoading` | `boolean` | Apple giriş loading durumu |
-| `googleConfigured` | `boolean` | Google yapılandırılmış mı |
-| `appleAvailable` | `boolean` | Apple mevcut mu (sadece iOS) |
+**CONFIGURATION PARAMETERS**:
+- `google?: GoogleAuthConfig` - Google client IDs
+- `apple?: { enabled: boolean }` - Apple enable flag
 
-**Not:** `signInWithGoogle` için tam OAuth flow'u `useGoogleAuth` hook'unu kullanın.
+**RETURN VALUES**:
+- `signInWithGoogle: () => Promise<SocialAuthResult>` - Google sign-in
+- `signInWithApple: () => Promise<SocialAuthResult>` - Apple sign-in
+- `googleLoading: boolean` - Google loading state
+- `appleLoading: boolean` - Apple loading state
+- `googleConfigured: boolean` - Google configuration status
+- `appleAvailable: boolean` - Apple availability status
+
+**PLATFORM LIMITATIONS**:
+- Google: All platforms
+- Apple: iOS only (returns `appleAvailable: false` on other platforms)
 
 ---
 
 ## useGoogleAuth
 
-Google OAuth flow'unu `expo-auth-session` kullanarak yönetir ve Firebase authentication ile entegre eder.
+Google OAuth authentication with expo-auth-session.
+
+### Strategy
 
-### Kullanım
+**Purpose**: Complete Google OAuth flow using expo-auth-session for cross-platform support.
 
+**When to Use**:
+- Need Google OAuth specifically
+- Want full OAuth flow (not just Firebase)
+- Need web/expo support
+- Require custom Google configuration
+
+**Import Path**:
 ```typescript
 import { useGoogleAuth } from '@umituz/react-native-auth';
-
-function LoginScreen() {
-  const { signInWithGoogle, googleLoading, googleConfigured } = useGoogleAuth({
-    iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
-    webClientId: 'your-web-client-id.apps.googleusercontent.com',
-    androidClientId: 'your-android-client-id.apps.googleusercontent.com',
-  });
-
-  const handleGoogleSignIn = async () => {
-    const result = await signInWithGoogle();
-
-    if (result.success) {
-      console.log('Google ile giriş başarılı');
-    } else {
-      Alert.alert('Hata', result.error || 'Giriş başarısız');
-    }
-  };
-
-  return (
-    <Button
-      onPress={handleGoogleSignIn}
-      disabled={googleLoading || !googleConfigured}
-    >
-      {googleLoading ? 'Giriş yapılıyor...' : 'Google ile Giriş'}
-    </Button>
-  );
-}
 ```
 
-### API
+**Hook Location**: `src/presentation/hooks/useSocialLogin.ts`
 
-#### Parameters
+**Dependencies**:
+- `expo-auth-session`
+- `expo-web-browser`
+- `@react-native-firebase/auth`
 
-| Param | Tip | Required | Açıklama |
-|-------|------|----------|----------|
-| `iosClientId` | `string` | No* | iOS için Google Client ID |
-| `webClientId` | `string` | No* | Web için Google Client ID |
-| `androidClientId` | `string` | No* | Android için Google Client ID |
+### Rules
 
-*En az biri sağlanmalıdır.
+**MUST**:
+- Provide at least one client ID
+- Call `WebBrowser.maybeCompleteAuthSession()` in app root
+- Check `googleConfigured` before showing button
+- Handle loading and error states
+- Support platform-specific client IDs
 
-#### Return Value
+**MUST NOT**:
+- Call without client ID configuration
+- Skip web browser setup
+- Ignore platform differences
+- Show button if not configured
 
-| Prop | Tip | Açıklama |
-|------|-----|----------|
-| `signInWithGoogle` | `() => Promise<SocialAuthResult>` | Google ile giriş fonksiyonu |
-| `googleLoading` | `boolean` | Loading durumu |
-| `googleConfigured` | `boolean` | Yapılandırılmış mı |
+### Constraints
 
-### Örnekler
+**CLIENT IDs REQUIRED**:
+- `iosClientId?: string` - iOS client ID (optional)
+- `webClientId?: string` - Web client ID (optional)
+- `androidClientId?: string` - Android client ID (optional)
+- At least one MUST be provided
 
-#### Google ile Giriş Ekranı
-
-```typescript
-function SocialLoginScreen() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
-    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-  });
-
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
-
-  return (
-    <View style={styles.container}>
-      <Text style={styles.title}>Giriş Yap</Text>
-
-      <TouchableOpacity
-        style={styles.googleButton}
-        onPress={signInWithGoogle}
-        disabled={googleLoading}
-      >
-        {googleLoading ? (
-          <ActivityIndicator />
-        ) : (
-          <>
-            <GoogleIcon />
-            <Text>Google ile devam et</Text>
-          </>
-        )}
-      </TouchableOpacity>
-
-      {Platform.OS === 'ios' && appleAvailable && (
-        <TouchableOpacity
-          style={styles.appleButton}
-          onPress={signInWithApple}
-          disabled={appleLoading}
-        >
-          {appleLoading ? (
-            <ActivityIndicator />
-          ) : (
-            <>
-              <AppleIcon />
-              <Text>Apple ile devam et</Text>
-            </>
-          )}
-        </TouchableOpacity>
-      )}
-    </View>
-  );
-}
-```
+**RETURN VALUES**:
+- `signInWithGoogle: () => Promise<SocialAuthResult>` - Sign-in function
+- `googleLoading: boolean` - Loading state
+- `googleConfigured: boolean` - Configuration status
 
-#### Hata Yönetimi
+**PLATFORM BEHAVIOR**:
+- iOS: Uses `iosClientId` or falls back to `webClientId`
+- Android: Uses `androidClientId` or falls back to `webClientId`
+- Web: Uses `webClientId`
+- Requires OAuth 2.0 client ID from Google Cloud Console
 
-```typescript
-function LoginWithErrorHandling() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-  });
-
-  const handleGoogleSignIn = async () => {
-    try {
-      const result = await signInWithGoogle();
-
-      if (result.success) {
-        // Başarılı giriş
-        navigation.navigate('Home');
-      } else {
-        // Hata durumunda
-        if (result.error?.includes('cancelled')) {
-          // Kullanıcı iptal etti
-          return;
-        }
-
-        Alert.alert(
-          'Giriş Hatası',
-          result.error || 'Google ile giriş yapılamadı'
-        );
-      }
-    } catch (error) {
-      Alert.alert(
-        'Beklenmeyen Hata',
-        'Bir hata oluştu. Lütfen daha sonra tekrar deneyin.'
-      );
-    }
-  };
-
-  return <Button onPress={handleGoogleSignIn} />;
-}
-```
+**SETUP REQUIREMENTS**:
+- OAuth 2.0 Client ID from Google Cloud Console
+- Authorized redirect URI (auto-configured by expo)
+- Web browser warm-up (maybeCompleteAuthSession)
 
 ---
 
 ## useAppleAuth
 
-Apple Sign-In işlevselliği sağlar. Sadece iOS'ta mevcuttur.
+Apple Sign-In authentication wrapper.
+
+### Strategy
 
-### Kullanım
+**Purpose**: Convenience wrapper for Apple Sign-In functionality on iOS.
 
+**When to Use**:
+- Need Apple Sign-In specifically
+- Targeting iOS users
+- Want simple Apple auth integration
+- Don't need custom Apple configuration
+
+**Import Path**:
 ```typescript
 import { useAppleAuth } from '@umituz/react-native-auth';
-import { Platform } from 'react-native';
-
-function LoginScreen() {
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
-
-  if (Platform.OS !== 'ios' || !appleAvailable) {
-    return null; // Apple sadece iOS'ta çalışır
-  }
-
-  return (
-    <TouchableOpacity
-      onPress={signInWithApple}
-      disabled={appleLoading}
-      style={styles.appleButton}
-    >
-      {appleLoading ? (
-        <ActivityIndicator />
-      ) : (
-        <>
-          <AppleIcon />
-          <Text>Apple ile Giriş</Text>
-        </>
-      )}
-    </TouchableOpacity>
-  );
-}
 ```
 
-### API
+**Hook Location**: `src/presentation/hooks/useSocialLogin.ts`
 
-#### Return Value
+**Dependencies**:
+- `expo-apple-authentication`
+- `@react-native-firebase/auth`
 
-| Prop | Tip | Açıklama |
-|------|-----|----------|
-| `signInWithApple` | `() => Promise<SocialAuthResult>` | Apple ile giriş fonksiyonu |
-| `appleLoading` | `boolean` | Loading durumu |
-| `appleAvailable` | `boolean` | Apple Sign-In mevcut mu (iOS only) |
+### Rules
 
-### Örnekler
+**MUST**:
+- Check `appleAvailable` before showing button
+- Handle loading and error states
+- Only show on iOS platform
+- Support Apple Sign-In requirements
 
-#### Platform-Specific Apple Button
+**MUST NOT**:
+- Show Apple button on Android/Web
+- Call without availability check
+- Ignore Apple's guidelines
+- Require Apple auth for all users
 
-```typescript
-function SocialLoginButtons() {
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-  });
-
-  return (
-    <View>
-      {/* Google - tüm platformlar */}
-      <SocialButton
-        provider="google"
-        onPress={signInWithGoogle}
-        loading={googleLoading}
-      />
-
-      {/* Apple - sadece iOS */}
-      {Platform.OS === 'ios' && appleAvailable && (
-        <SocialButton
-          provider="apple"
-          onPress={signInWithApple}
-          loading={appleLoading}
-        />
-      )}
-    </View>
-  );
-}
-```
+### Constraints
 
-#### Apple ile Giriş ve Hata Yönetimi
+**RETURN VALUES**:
+- `signInWithApple: () => Promise<SocialAuthResult>` - Sign-in function
+- `appleLoading: boolean` - Loading state
+- `appleAvailable: boolean` - iOS availability status
 
-```typescript
-function AppleLoginButton() {
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
-
-  const handleAppleSignIn = async () => {
-    const result = await signInWithApple();
-
-    if (result.success) {
-      console.log('Apple ile giriş başarılı');
-      // Kullanıcıyı ana ekrana yönlendir
-    } else {
-      // Hata yönetimi
-      if (result.error?.includes('cancelled')) {
-        console.log('Kullanıcı iptal etti');
-      } else {
-        Alert.alert('Hata', result.error || 'Apple ile giriş yapılamadı');
-      }
-    }
-  };
-
-  if (!appleAvailable) {
-    return null;
-  }
-
-  return (
-    <TouchableOpacity onPress={handleAppleSignIn} disabled={appleLoading}>
-      <Text>Apple ile Giriş</Text>
-    </TouchableOpacity>
-  );
-}
-```
+**PLATFORM SUPPORT**:
+- iOS: ✅ Fully supported (if configured)
+- Android: ❌ Not supported (appleAvailable = false)
+- Web: ❌ Not supported (appleAvailable = false)
+
+**SETUP REQUIREMENTS**:
+- Apple Developer account
+- App ID with Sign In with Apple enabled
+- Firebase Auth with Apple enabled
+- Physical device (may not work in simulator)
+
+**APPLE GUIDELINES**:
+- Must offer alternative auth methods
+- Cannot require Apple as only option
+- Must follow Apple's UI guidelines
+- Button design per Apple specifications
+
+---
 
 ## SocialAuthResult
 
-Tüm social login fonksiyonları aynı result tipini döner:
+Common return type for all social auth functions.
 
-```typescript
-interface SocialAuthResult {
-  success: boolean;
-  error?: string;
-  user?: AuthUser;
-}
-```
+### Structure
+
+**PROPERTIES**:
+- `success: boolean` - Operation success status
+- `error?: string` - Error message if failed
+- `user?: AuthUser` - User object if successful
+
+**Rules**:
+- MUST check `success` before using `user`
+- MUST handle `error` if `success = false`
+- MUST NOT assume `user` exists without checking
+
+**Constraints**:
+- Always returns success boolean
+- User object only present on success
+- Error string only present on failure
+- Used by all social auth functions
+
+---
+
+## Configuration Strategy
 
-## Konfigürasyon
+### Strategy
 
-### Google Client ID Almak
+**Purpose**: Proper setup and configuration for social authentication.
 
-1. [Google Cloud Console](https://console.cloud.google.com/)'a gidin
-2. Yeni bir proje oluşturun veya mevcut projeyi seçin
-3. "APIs & Services" > "Credentials" sayfasına gidin
-4. "OAuth 2.0 Client IDs" oluşturun:
-   - **iOS**: iOS uygulamanız için
-   - **Android**: Android uygulamanız için
-   - **Web**: Expo/web için
+**Rules**:
+- MUST configure OAuth providers in Firebase Console
+- MUST set up projects in provider consoles
+- MUST provide correct client IDs
+- MUST test on physical devices
 
-### Apple Sign-In Konfigürasyonu
+**MUST NOT**:
+- Use development client IDs in production
+- Skip provider console setup
+- Assume configuration is correct
+- Test only on simulator
 
-1. [Apple Developer](https://developer.apple.com/)'da gidin
-2. "Certificates, Identifiers & Profiles" > "Identifiers"
-3. App ID'nizi seçin ve "Sign In with Apple"ı enable edin
-4. Firebase Console'da Apple Sign-In'i enable edin
+### Constraints
 
-## Önemli Notlar
+**FIREBASE SETUP**:
+- Enable Google Sign-In in Firebase Auth
+- Enable Apple Sign-In in Firebase Auth
+- Configure OAuth consent screen
+- Set up authorized domains
+
+**GOOGLE CONSOLE SETUP**:
+1. Go to Google Cloud Console
+2. Create OAuth 2.0 Client IDs
+3. Add authorized redirect URIs
+4. Copy client IDs to app config
+
+**APPLE SETUP**:
+1. Apple Developer account
+2. Enable Sign In with Apple for App ID
+3. Create provider ID in Firebase
+4. Configure certificates
+
+---
+
+## Error Handling
+
+### Strategy
+
+**Purpose**: Graceful handling of social authentication failures.
+
+**Rules**:
+- MUST distinguish cancellation from errors
+- MUST show user-friendly error messages
+- MUST allow retry after failures
+- MUST not crash on auth failures
+
+**MUST NOT**:
+- Show raw OAuth errors
+- Block retry indefinitely
+- Crash on provider errors
+- Expose sensitive tokens in errors
+
+### Constraints
+
+**ERROR TYPES**:
+- User cancellation: Silent handling
+- Network errors: Retry prompt
+- Configuration errors: Developer message
+- Provider errors: Generic "try again"
+
+**CANCELLATION HANDLING**:
+- Check error message for "cancelled"
+- Don't show error for cancellation
+- Allow retry without blocking
+- Silent return preferred
+
+---
+
+## Security Requirements
+
+### Strategy
+
+**Purpose**: Secure social authentication implementation.
+
+**Rules**:
+- MUST use HTTPS for all OAuth endpoints
+- MUST store tokens securely
+- MUST validate tokens server-side
+- MUST never log OAuth credentials
+- MUST implement token refresh
+
+**MUST NOT**:
+- Store tokens in AsyncStorage
+- Log OAuth responses
+- Skip server-side validation
+- Expose client secrets
+- Use HTTP for OAuth flows
+
+### Constraints
+
+**TOKEN HANDLING**:
+- Tokens managed by Firebase SDK
+- Secure storage automatic
+- App never accesses refresh tokens
+- ID tokens available for API calls
+- Token refresh handled by Firebase
+
+**CLIENT SECRETS**:
+- Never included in app code
+- Public client flows only
+- Server-side validation required
+- Firebase manages credentials
+
+---
+
+## Platform-Specific Behavior
+
+### Strategy
+
+**Purpose**: Optimize social auth experience for each platform.
+
+**Rules**:
+- MUST respect platform limitations
+- MUST use appropriate client IDs
+- MUST handle platform-specific errors
+- MUST test on target platforms
+
+**Constraints**:
+
+**iOS**:
+- Apple Sign-In available
+- Google uses app-based OAuth
+- Requires Info.plist configuration
+- Best on physical devices
+
+**Android**:
+- Apple Sign-In NOT available
+- Google uses app-based OAuth
+- Requires google-services.json
+- Works on emulator
+
+**Web**:
+- Apple Sign-In NOT available
+- Google uses popup OAuth
+- Requires proper callback handling
+- Browser popup blockers
+
+---
 
-### Google
-- `expo-web-browser` kurulumu gerekir
-- `WebBrowser.maybeCompleteAuthSession()` app root'ta çağrılmalı
-- En az bir client ID sağlanmalıdır
+## Related Hooks
 
-### Apple
-- Sadece iOS'ta mevcuttur
-- `expo-apple-authentication` kurulumu gerekir
-- Apple Developer hesabı gerekir
-- Test için cihaz gereklidir (simulator'de çalışmayabilir)
+- **`useAuth`** (`src/presentation/hooks/useAuth.ts`) - Core authentication state
+- **`useAuthBottomSheet`** (`src/presentation/hooks/useAuthBottomSheet.md`) - Auth modal integration
 
-## İlgili Hook'lar
+## Related Components
 
-- [`useAuth`](./useAuth.md) - Ana auth state yönetimi
-- [`useSocialLogin`](#usesociallogin) - Genel social login yönetimi
+- **`SocialLoginButtons`** (`src/presentation/components/SocialLoginButtons.md`) - Social auth UI
 
-## İlgili Component'ler
+## External Dependencies
 
-- [`SocialLoginButtons`](../components/SocialLoginButtons.md) - Social login button component'i
+- **`@umituz/react-native-firebase`** - Firebase social auth wrapper
+- **`expo-auth-session`** - OAuth session management
+- **`expo-web-browser`** - Web browser for OAuth
+- **`expo-apple-authentication`** - Apple Sign-In