@umituz/react-native-auth 3.4.30 → 3.4.31

package/src/presentation/hooks/useAuthBottomSheet.md

@@ -0,0 +1,417 @@
+# useAuthBottomSheet
+
+Authentication bottom sheet yönetimi için hook. Login/Register modal'ını göstermek, yönetmek ve social authentication işlemlerini gerçekleştirmek için kullanılır.
+
+## Özellikler
+
+- Bottom sheet modal yönetimi
+- Login/Register mod değiştirme
+- Social authentication entegrasyonu
+- Otomatik kapanma (başarılı authentication sonrası)
+- Pending callback yönetimi
+
+## Kullanım
+
+```typescript
+import { useAuthBottomSheet } from '@umituz/react-native-auth';
+import { BottomSheetModal } from '@umituz/react-native-design-system';
+
+function AuthBottomSheet() {
+  const {
+    modalRef,
+    mode,
+    providers,
+    googleLoading,
+    appleLoading,
+    handleDismiss,
+    handleClose,
+    handleNavigateToRegister,
+    handleNavigateToLogin,
+    handleGoogleSignIn,
+    handleAppleSignIn,
+  } = useAuthBottomSheet({
+    socialConfig: {
+      google: {
+        iosClientId: 'your-ios-client-id',
+        webClientId: 'your-web-client-id',
+      },
+      apple: { enabled: true },
+    },
+  });
+
+  return (
+    <BottomSheetModal ref={modalRef} onDismiss={handleDismiss}>
+      {mode === 'login' ? (
+        <LoginForm
+          onRegisterPress={handleNavigateToRegister}
+          onGoogleSignIn={handleGoogleSignIn}
+          onAppleSignIn={handleAppleSignIn}
+          googleLoading={googleLoading}
+          appleLoading={appleLoading}
+        />
+      ) : (
+        <RegisterForm
+          onLoginPress={handleNavigateToLogin}
+          onGoogleSignIn={handleGoogleSignIn}
+          onAppleSignIn={handleAppleSignIn}
+          googleLoading={googleLoading}
+          appleLoading={appleLoading}
+        />
+      )}
+    </BottomSheetModal>
+  );
+}
+```
+
+## API
+
+### Parameters
+
+| Param | Tip | Required | Açıklama |
+|-------|------|----------|----------|
+| `socialConfig` | `SocialAuthConfiguration` | No | Social auth konfigürasyonu |
+| `onGoogleSignIn` | `() => Promise<void>` | No | Custom Google sign-in handler |
+| `onAppleSignIn` | `() => Promise<void>` | No | Custom Apple sign-in handler |
+
+#### SocialAuthConfiguration
+
+```typescript
+interface SocialAuthConfiguration {
+  google?: GoogleAuthConfig;
+  apple?: { enabled: boolean };
+}
+```
+
+### Return Value
+
+| Prop | Tip | Açıklama |
+|------|-----|----------|
+| `modalRef` | `RefObject<BottomSheetModalRef>` | Bottom sheet modal referansı |
+| `mode` | `'login' \| 'register'` | Mevcut mod |
+| `providers` | `SocialAuthProvider[]` | Mevcut social provider'lar |
+| `googleLoading` | `boolean` | Google loading durumu |
+| `appleLoading` | `boolean` | Apple loading durumu |
+| `handleDismiss` | `() => void` | Modal'ı kapatma (dismiss) |
+| `handleClose` | `() => void` | Modal'ı kapatma ve temizleme |
+| `handleNavigateToRegister` | `() => void` | Register moduna geçiş |
+| `handleNavigateToLogin` | `() => void` | Login moduna geçiş |
+| `handleGoogleSignIn` | `() => Promise<void>` | Google ile giriş |
+| `handleAppleSignIn` | `() => Promise<void>` | Apple ile giriş |
+
+## Örnekler
+
+### Basit Auth Bottom Sheet
+
+```typescript
+function AuthModal() {
+  const {
+    modalRef,
+    mode,
+    handleDismiss,
+    handleNavigateToRegister,
+    handleNavigateToLogin,
+  } = useAuthBottomSheet();
+
+  return (
+    <BottomSheetModal ref={modalRef} snapPoints={['80%']} onDismiss={handleDismiss}>
+      <View>
+        {mode === 'login' ? (
+          <>
+            <Text>Giriş Yap</Text>
+            <LoginForm />
+            <Button onPress={handleNavigateToRegister}>
+              Hesabınız yok mu? Kayıt Olun
+            </Button>
+          </>
+        ) : (
+          <>
+            <Text>Kayıt Ol</Text>
+            <RegisterForm />
+            <Button onPress={handleNavigateToLogin}>
+              Zaten hesabınız var mı? Giriş Yapın
+            </Button>
+          </>
+        )}
+      </View>
+    </BottomSheetModal>
+  );
+}
+```
+
+### Social Login ile
+
+```typescript
+function AuthBottomSheetWithSocial() {
+  const {
+    modalRef,
+    mode,
+    providers,
+    googleLoading,
+    appleLoading,
+    handleDismiss,
+    handleNavigateToRegister,
+    handleNavigateToLogin,
+    handleGoogleSignIn,
+    handleAppleSignIn,
+  } = useAuthBottomSheet({
+    socialConfig: {
+      google: {
+        webClientId: Config.GOOGLE_WEB_CLIENT_ID,
+        iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
+      },
+      apple: { enabled: Platform.OS === 'ios' },
+    },
+  });
+
+  return (
+    <BottomSheetModal ref={modalRef} snapPoints={['90%']} onDismiss={handleDismiss}>
+      <View>
+        {mode === 'login' ? (
+          <>
+            <LoginForm />
+
+            {/* Social login buttons */}
+            {providers.includes('google') && (
+              <SocialButton
+                provider="google"
+                onPress={handleGoogleSignIn}
+                loading={googleLoading}
+              />
+            )}
+
+            {providers.includes('apple') && (
+              <SocialButton
+                provider="apple"
+                onPress={handleAppleSignIn}
+                loading={appleLoading}
+              />
+            )}
+
+            <Button onPress={handleNavigateToRegister}>
+              Kayıt Ol
+            </Button>
+          </>
+        ) : (
+          <>
+            <RegisterForm />
+
+            {/* Social login buttons */}
+            {providers.includes('google') && (
+              <SocialButton
+                provider="google"
+                onPress={handleGoogleSignIn}
+                loading={googleLoading}
+              />
+            )}
+
+            {providers.includes('apple') && (
+              <SocialButton
+                provider="apple"
+                onPress={handleAppleSignIn}
+                loading={appleLoading}
+              />
+            )}
+
+            <Button onPress={handleNavigateToLogin}>
+              Giriş Yap
+            </Button>
+          </>
+        )}
+      </View>
+    </BottomSheetModal>
+  );
+}
+```
+
+### Custom Social Login Handlers
+
+```typescript
+function AuthBottomSheetWithCustomHandlers() {
+  const { showAuthModal } = useAuthModalStore();
+
+  const handleCustomGoogleSignIn = async () => {
+    try {
+      // Custom Google sign-in logic
+      const result = await customGoogleSignInFlow();
+
+      if (result.success) {
+        // Başarılı authentication sonrası modal otomatik kapanır
+        console.log('Google ile giriş başarılı');
+      }
+    } catch (error) {
+      Alert.alert('Hata', 'Google ile giriş başarısız');
+    }
+  };
+
+  const handleCustomAppleSignIn = async () => {
+    try {
+      // Custom Apple sign-in logic
+      const result = await customAppleSignInFlow();
+
+      if (result.success) {
+        console.log('Apple ile giriş başarılı');
+      }
+    } catch (error) {
+      Alert.alert('Hata', 'Apple ile giriş başarısız');
+    }
+  };
+
+  const {
+    modalRef,
+    mode,
+    googleLoading,
+    appleLoading,
+    handleDismiss,
+    handleNavigateToRegister,
+    handleNavigateToLogin,
+    handleGoogleSignIn,
+    handleAppleSignIn,
+  } = useAuthBottomSheet({
+    onGoogleSignIn: handleCustomGoogleSignIn,
+    onAppleSignIn: handleCustomAppleSignIn,
+  });
+
+  return (
+    <BottomSheetModal ref={modalRef} onDismiss={handleDismiss}>
+      {/* Auth form content */}
+    </BottomSheetModal>
+  );
+}
+```
+
+### Auth Modal Tetikleme
+
+```typescript
+function RequireAuthButton() {
+  const { showAuthModal } = useAuthModalStore();
+  const { isAuthenticated } = useAuth();
+
+  const handlePress = () => {
+    if (!isAuthenticated) {
+      // Login modal'ını göster
+      showAuthModal(undefined, 'login');
+      return;
+    }
+
+    // Auth gerektiren işlemi yap
+    console.log('İşlem başarılı');
+  };
+
+  return (
+    <Button onPress={handlePress}>
+      Auth Gerektiren İşlem
+    </Button>
+  );
+}
+```
+
+### Pending Callback ile
+
+```typescript
+function AddToFavoritesButton() {
+  const { showAuthModal } = useAuthModalStore();
+  const { isAuthenticated } = useAuth();
+
+  const handleAddToFavorites = async () => {
+    if (!isAuthenticated) {
+      // Authentication sonrası çalışacak callback'i kaydet
+      showAuthModal(async () => {
+        await addToFavorites(postId);
+        Alert.alert('Başarılı', 'Favorilere eklendi');
+      }, 'login');
+      return;
+    }
+
+    // Kullanıcı authenticated, doğrudan işlemi yap
+    await addToFavorites(postId);
+    Alert.alert('Başarılı', 'Favorilere eklendi');
+  };
+
+  return (
+    <Button onPress={handleAddToFavorites}>
+      Favorilere Ekle
+    </Button>
+  );
+}
+```
+
+## Otomatik Kapanma
+
+Hook, başarılı authentication sonrası otomatik olarak modal'ı kapatır:
+
+- **Authenticated olmadan authenticated olmaya**: Kullanıcı giriş yaptığında
+- **Anonymous'den authenticated olmaya**: Anonymous kullanıcı kayıt olduğunda
+
+```typescript
+// Kullanıcı giriş yapar
+// → useAuth store güncellenir
+// → useAuthBottomSheet bunu tespit eder
+// → Modal otomatik kapanır
+// → Pending callback çalıştırılır
+```
+
+## Provider Kontrolü
+
+Hook hangi provider'ların mevcut olduğunu otomatik belirler:
+
+```typescript
+const { providers } = useAuthBottomSheet({
+  socialConfig: {
+    google: { webClientId: '...' },
+    apple: { enabled: true },
+  },
+});
+
+// iOS: ['apple', 'google'] veya ['google']
+// Android: ['google']
+// Web: ['google']
+```
+
+## Hata Yönetimi
+
+```typescript
+function AuthBottomSheetWithErrorHandling() {
+  const {
+    modalRef,
+    mode,
+    handleGoogleSignIn,
+    handleAppleSignIn,
+  } = useAuthBottomSheet({
+    socialConfig: {
+      google: { webClientId: Config.GOOGLE_WEB_CLIENT_ID },
+      apple: { enabled: true },
+    },
+  });
+
+  const handleGoogleSignInWithErrorHandling = async () => {
+    try {
+      await handleGoogleSignIn();
+      // Hook hata yönetimini içeride yapar
+    } catch (error) {
+      // Additional error handling if needed
+      Alert.alert('Hata', 'Bir sorun oluştu');
+    }
+  };
+
+  return (
+    <BottomSheetModal ref={modalRef}>
+      <Button onPress={handleGoogleSignInWithErrorHandling}>
+        Google ile Giriş
+      </Button>
+    </BottomSheetModal>
+  );
+}
+```
+
+## İlgili Component'ler
+
+- [`AuthBottomSheet`](../components/AuthBottomSheet.md) - Bottom sheet component'i
+- [`useAuthModalStore`](../stores/authModalStore.md) - Auth modal state store'u
+- [`LoginForm`](../components/LoginForm.md) - Login form component'i
+- [`RegisterForm`](../components/RegisterForm.md) - Register form component'i
+
+## İlgili Hook'lar
+
+- [`useGoogleAuth`](./useSocialLogin.md#usegoogleauth) - Google auth hook'u
+- [`useAppleAuth`](./useSocialLogin.md#useappleauth) - Apple auth hook'u
+- [`useAuth`](./useAuth.md) - Ana auth state yönetimi

package/src/presentation/hooks/useAuthRequired.md

@@ -0,0 +1,248 @@
+# useAuthRequired & useRequireAuth
+
+Two hooks for authentication requirements in components.
+
+---
+
+## useAuthRequired
+
+Check auth requirements and show modal if needed.
+
+### Usage
+
+```typescript
+import { useAuthRequired } from '@umituz/react-native-auth';
+
+function LikeButton() {
+  const { isAllowed, isLoading, requireAuth, checkAndRequireAuth } = useAuthRequired();
+
+  const handleLike = () => {
+    if (checkAndRequireAuth()) {
+      // User is authenticated, proceed
+      likePost();
+    }
+    // Otherwise, auth modal is shown automatically
+  };
+
+  return (
+    <Button onPress={handleLike} disabled={isLoading}>
+      {isAllowed ? 'Like' : 'Sign in to like'}
+    </Button>
+  );
+}
+```
+
+### API
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isAllowed` | `boolean` | Whether user is authenticated (not anonymous) |
+| `isLoading` | `boolean` | Whether auth is still loading |
+| `userId` | `string \| null` | Current user ID (null if not authenticated) |
+| `requireAuth` | `() => void` | Show auth modal |
+| `checkAndRequireAuth` | `() => boolean` | Check and show modal if needed, returns true/false |
+
+### Examples
+
+#### Add to Favorites
+
+```typescript
+function AddToFavoritesButton({ postId }) {
+  const { isAllowed, checkAndRequireAuth } = useAuthRequired();
+
+  const handleAddToFavorites = () => {
+    if (!checkAndRequireAuth()) {
+      return; // Auth modal opened, stop here
+    }
+
+    // User authenticated, proceed
+    addToFavorites(postId);
+  };
+
+  return (
+    <TouchableOpacity onPress={handleAddToFavorites}>
+      <HeartIcon filled={isAllowed} />
+    </TouchableOpacity>
+  );
+}
+```
+
+#### Post Comment
+
+```typescript
+function CommentForm({ postId }) {
+  const { isAllowed, requireAuth, userId } = useAuthRequired();
+  const [comment, setComment] = useState('');
+
+  const handleSubmit = () => {
+    if (!isAllowed) {
+      requireAuth(); // Open auth modal
+      return;
+    }
+
+    // Submit comment
+    submitComment(postId, userId, comment);
+    setComment('');
+  };
+
+  return (
+    <View>
+      <TextInput
+        value={comment}
+        onChangeText={setComment}
+        placeholder={isAllowed ? "Write your comment..." : "Sign in to comment"}
+        editable={isAllowed}
+      />
+      <Button onPress={handleSubmit} disabled={!isAllowed}>
+        {isAllowed ? 'Submit' : 'Sign In'}
+      </Button>
+    </View>
+  );
+}
+```
+
+---
+
+## useRequireAuth
+
+For components that **must** have an authenticated user. Throws if not authenticated.
+
+### Usage
+
+```typescript
+import { useRequireAuth } from '@umituz/react-native-auth';
+
+function UserProfile() {
+  const userId = useRequireAuth(); // string, not null
+
+  useEffect(() => {
+    // userId is guaranteed to be string
+    fetchUserData(userId);
+  }, [userId]);
+
+  return <ProfileContent userId={userId} />;
+}
+```
+
+### useUserId (Safe Alternative)
+
+Returns null if user is not authenticated:
+
+```typescript
+import { useUserId } from '@umituz/react-native-auth';
+
+function MaybeUserProfile() {
+  const userId = useUserId(); // string | null
+
+  if (!userId) {
+    return <LoginPrompt />;
+  }
+
+  return <ProfileContent userId={userId} />;
+}
+```
+
+### Examples
+
+#### Order History
+
+```typescript
+function OrderHistory() {
+  const userId = useRequireAuth(); // User must be authenticated
+
+  const { data: orders, isLoading } = useQuery({
+    queryKey: ['orders', userId],
+    queryFn: () => fetchOrders(userId),
+  });
+
+  if (isLoading) return <LoadingSpinner />;
+
+  return (
+    <FlatList
+      data={orders}
+      renderItem={({ item }) => <OrderCard order={item} />}
+    />
+  );
+}
+```
+
+#### User Settings
+
+```typescript
+function UserSettings() {
+  const userId = useRequireAuth();
+
+  const updateSettings = async (settings: UserSettings) => {
+    await updateUserSettings(userId, settings);
+  };
+
+  return <SettingsForm onSave={updateSettings} />;
+}
+```
+
+### Error Handling
+
+Wrap components using `useRequireAuth` with Error Boundary:
+
+```typescript
+function App() {
+  return (
+    <ErrorBoundary fallback={<LoginScreen />}>
+      <Routes>
+        <Route path="/settings" element={<UserSettings />} />
+        <Route path="/orders" element={<OrderHistory />} />
+      </Routes>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Comparison Table
+
+| Situation | Hook | Why |
+|-----------|------|-----|
+| Check auth before action | `useAuthRequired` | Can show modal, graceful degradation |
+| Show auth modal | `useAuthRequired` | Has `requireAuth()` method |
+| Component requires auth | `useRequireAuth` | Type-safe, non-null userId |
+| Optional auth | `useUserId` | Safe, can return null |
+
+## Code Comparison
+
+```typescript
+// ❌ Wrong - useRequireAuth with modal attempt
+function BadComponent() {
+  const userId = useRequireAuth(); // Will throw!
+
+  const handleClick = () => {
+    // Never reaches here
+  };
+}
+
+// ✅ Good - useAuthRequired with modal
+function GoodComponent() {
+  const { isAllowed, requireAuth } = useAuthRequired();
+
+  const handleClick = () => {
+    if (!isAllowed) {
+      requireAuth(); // Show modal
+      return;
+    }
+    // Perform action
+  };
+}
+
+// ✅ Good - useRequireAuth for required auth
+function ProtectedComponent() {
+  const userId = useRequireAuth(); // Type-safe: string
+
+  // Use userId
+  useEffect(() => {
+    fetchUserData(userId);
+  }, [userId]);
+}
+```
+
+## Related Hooks
+
+- [`useAuth`](./useAuth.md) - Main auth state management
+- [`useAuthModalStore`](../stores/authModalStore.ts) - Auth modal state