@umituz/react-native-auth 3.4.33 → 3.4.34

package/src/infrastructure/services/README.md

@@ -1,417 +1,491 @@
-# Auth Services
+# Infrastructure Services
 
-React Native Auth paketi için core servisler ve authentication işlevselliği.
+Core authentication services and infrastructure implementations.
 
-## Servisler
+---
+
+## Strategy
+
+**Purpose**: Provides concrete implementations for authentication operations, user document management, event handling, and validation.
 
-- **[`AuthService`](./AuthService.ts)** - Ana authentication servisi
-- **[`initializeAuth`](./initializeAuth.ts)** - Auth başlatma servisi
-- **[`UserDocumentService`](./UserDocumentService.ts)** - Kullanıcı dokümanı servisi
-- **[`AnonymousModeService`](./AnonymousModeService.ts)** - Anonymous mod servisi
-- **[`AuthEventService`](./AuthEventService.ts)** - Auth event servisi
+**When to Use**:
+- Understanding service architecture
+- Implementing custom services
+- Debugging service issues
+- Learning about Firebase integration
+
+**Location**: `src/infrastructure/services/`
 
 ---
 
-## AuthService
+## Available Services
 
-Ana authentication servisi. Firebase Authentication ile tüm auth işlemlerini yönetir.
+### AuthService
 
-### Kullanım
+**PURPOSE**: Main authentication service orchestrating all auth operations
 
+**IMPORT PATH**:
 ```typescript
 import {
   AuthService,
   initializeAuthService,
-  getAuthService
+  getAuthService,
+  resetAuthService
 } from '@umituz/react-native-auth';
+```
 
-// Service başlatma
-initializeAuthService({
-  firebaseAuth: getAuth(),
-});
+**File**: `AuthService.ts`
+
+**METHODS**:
+- `signIn(params)` - Sign in with email/password
+- `signUp(params)` - Create new account
+- `signOut()` - Sign out current user
+- `getCurrentUser()` - Get current user
+- `sendPasswordResetEmail(email)` - Reset password
+
+**FUNCTIONS**:
+- `initializeAuthService(config)` - Initialize service
+- `getAuthService()` - Get service instance
+- `resetAuthService()` - Reset service (testing only)
+
+**Rules**:
+- MUST initialize before use
+- MUST implement IAuthService interface
+- MUST handle Firebase errors
+- MUST create user documents on registration
+- MUST not create multiple instances
+
+**MUST NOT**:
+- Skip initialization
+- Use before initialization
+- Expose Firebase types
+- Create multiple service instances
+- Skip error handling
 
-// Service alma
-const authService = getAuthService();
+---
 
-// Giriş yapma
-await authService.signIn({ email, password });
+### initializeAuth
 
-// Kayıt olma
-await authService.signUp({ email, password, displayName });
+**PURPOSE**: Initialize authentication system and Firebase Auth state listener
 
-// Çıkış yapma
-await authService.signOut();
+**IMPORT PATH**:
+```typescript
+import {
+  initializeAuth,
+  isAuthInitialized,
+  resetAuthInitialization
+} from '@umituz/react-native-auth';
 ```
 
-### API
-
-#### Methods
-
-| Method | Parametreler | Açıklama |
-|--------|--------------|----------|
-| `signIn` | `{ email, password }` | Email/password ile giriş |
-| `signUp` | `{ email, password, displayName? }` | Yeni kullanıcı kaydı |
-| `signOut` | - | Çıkış yapma |
-| `sendPasswordResetEmail` | `email` | Şifre sıfırlama email'i gönderme |
+**File**: `initializeAuth.ts`
 
-### Örnekler
+**PARAMETERS**:
+- `onAuthStateChanged` - Auth state callback (optional)
+- `onAuthError` - Error callback (optional)
 
-#### Service Başlatma
+**FUNCTIONS**:
+- `initializeAuth(options)` - Initialize auth system
+- `isAuthInitialized()` - Check initialization status
+- `resetAuthInitialization()` - Reset (testing only)
 
-```typescript
-import { initializeAuthService } from '@umituz/react-native-auth';
-import { getAuth } from 'firebase/auth';
-
-function App() {
-  useEffect(() => {
-    const firebaseAuth = getAuth();
-
-    initializeAuthService({
-      firebaseAuth,
-      onAuthStateChanged: (user) => {
-        console.log('Auth state changed:', user);
-      },
-    });
-  }, []);
-
-  return <AppNavigator />;
-}
-```
+**Rules**:
+- MUST call once at app startup
+- MUST wait for initialization completion
+- MUST handle initialization errors
+- MUST not call multiple times
+- MUST check status before operations
 
-#### Custom AuthService
+**MUST NOT**:
+- Skip initialization
+- Call in components (use app root)
+- Initialize multiple times
+- Skip status check
+- Ignore initialization errors
 
-```typescript
-import { AuthService } from '@umituz/react-native-auth';
-
-class CustomAuthService extends AuthService {
-  async signInWithCustomToken(token: string) {
-    // Custom implementation
-    const userCredential = await signInWithCustomToken(
-      this.firebaseAuth,
-      token
-    );
-
-    await this.ensureUserDocument(userCredential.user);
-    return userCredential.user;
-  }
-}
-
-// Custom service kullanımı
-const customService = new CustomAuthService({
-  firebaseAuth: getAuth(),
-});
-```
+**CALLBACKS**:
+- `onAuthStateChanged(user)` - Called when auth state changes
+- `onAuthError(error)` - Called on auth errors
 
 ---
 
-## initializeAuth
-
-Authentication sistemini başlatır. Firebase Auth listener'ını kurar ve user state'ini yönetir.
+### UserDocumentService
 
-### Kullanım
+**PURPOSE**: Manage Firestore user documents
 
+**IMPORT PATH**:
 ```typescript
-import { initializeAuth } from '@umituz/react-native-auth';
-
-function App() {
-  useEffect(() => {
-    const init = async () => {
-      await initializeAuth({
-        onAuthStateChanged: (user) => {
-          console.log('User:', user);
-        },
-      });
-    };
-
-    init();
-  }, []);
-
-  return <AppNavigator />;
-}
+import {
+  ensureUserDocument,
+  markUserDeleted,
+  configureUserDocumentService
+} from '@umituz/react-native-auth';
 ```
 
-### Options
+**File**: `UserDocumentService.ts`
+
+**FUNCTIONS**:
+- `ensureUserDocument(user, data?)` - Create/retrieve user document
+- `markUserDeleted(userId)` - Mark user as deleted
+- `configureUserDocumentService(config)` - Configure service
+
+**Rules**:
+- MUST create document on registration
+- MUST check document existence
+- MUST use server timestamps
+- MUST support custom configuration
+- MUST not delete documents permanently
+
+**MUST NOT**:
+- Skip document creation
+- Overwrite existing data
+- Use client timestamps
+- Hardcode collection name
+- Delete documents permanently
+
+**CONFIGURATION**:
+- `collection` - Firestore collection name (default: 'users')
+- `timestamps` - Add createdAt/updatedAt fields
+- `userData` - Custom fields to add to documents
+
+**CUSTOM DATA**:
+- Can add custom fields on document creation
+- Merges with existing data
+- Supports nested objects
+- Preserves user-provided data
 
-```typescript
-interface InitializeAuthOptions {
-  onAuthStateChanged?: (user: AuthUser | null) => void;
-  onAuthError?: (error: Error) => void;
-}
-```
+---
 
-### Örnekler
+### AnonymousModeService
 
-#### Basit Başlatma
+**PURPOSE**: Handle anonymous user authentication and upgrade
 
+**IMPORT PATH**:
 ```typescript
-import { initializeAuth } from '@umituz/react-native-auth';
-
-function App() {
-  useEffect(() => {
-    initializeAuth();
-  }, []);
-
-  return <Navigator />;
-}
+import { AnonymousModeService } from '@umituz/react-native-auth';
 ```
 
-#### Callback ile Başlatma
+**File**: `AnonymousModeService.ts`
 
-```typescript
-import { initializeAuth } from '@umituz/react-native-auth';
-
-function App() {
-  const navigation = useNavigation();
-
-  useEffect(() => {
-    initializeAuth({
-      onAuthStateChanged: (user) => {
-        if (user) {
-          navigation.reset({
-            index: 0,
-            routes: [{ name: 'Home' }],
-          });
-        } else {
-          navigation.reset({
-            index: 0,
-            routes: [{ name: 'Login' }],
-          });
-        }
-      },
-      onAuthError: (error) => {
-        console.error('Auth error:', error);
-        Alert.alert('Auth Hatası', error.message);
-      },
-    });
-  }, []);
-
-  return <Navigator />;
-}
-```
+**METHODS**:
+- `signInAnonymously()` - Create anonymous user
 
----
+**UPGRADE**:
+- Handled via Firebase credential linking
+- Converts anonymous to permanent account
+- Preserves anonymous user data
 
-## UserDocumentService
+**Rules**:
+- MUST create temporary accounts
+- MUST support upgrade to permanent account
+- MUST warn about data loss
+- MUST handle upgrade failures
+- MUST not delete anonymous data on sign out
 
-Firestore'da kullanıcı dokümanlarını yönetir.
+**MUST NOT**:
+- Skip upgrade warnings
+- Lose user data during upgrade
+- Allow restricted operations without warning
+- Make anonymous accounts permanent
 
-### Kullanım
+**CONSTRAINTS**:
+- Anonymous users have limited functionality
+- Data lost if signed out without upgrade
+- Upgrade requires valid credentials
+- Cannot revert to anonymous after upgrade
 
-```typescript
-import {
-  ensureUserDocument,
-  markUserDeleted,
-  configureUserDocumentService
-} from '@umituz/react-native-auth';
+---
 
-// Kullanıcı dokümanını garanti altına al
-await ensureUserDocument(user);
+### AuthEventService
 
-// Kullanıcıyı silinmiş olarak işaretle
-await markUserDeleted(user.uid);
+**PURPOSE**: Pub/sub system for authentication events
 
-// Service konfigürasyonu
-configureUserDocumentService({
-  collection: 'users',
-  timestamps: true,
-});
+**IMPORT PATH**:
+```typescript
+import { AuthEventService } from '@umituz/react-native-auth';
 ```
 
-### API
+**File**: `AuthEventService.ts`
+
+**METHODS**:
+- `on(event, callback)` - Subscribe to event
+- `emit(event, data)` - Emit event
+- Returns unsubscribe function
+
+**EVENTS**:
+- `signIn` - User signed in (payload: AuthUser)
+- `signUp` - New user registered (payload: AuthUser)
+- `signOut` - User signed out (payload: undefined)
+- `authStateChanged` - Auth state changed (payload: AuthUser | null)
+
+**Rules**:
+- MUST emit events on state changes
+- MUST support multiple subscribers
+- MUST provide unsubscribe function
+- MUST not throw in event handlers
+- MUST handle subscriber errors gracefully
+
+**MUST NOT**:
+- Skip critical events
+- Block event emission on handler errors
+- Throw unhandled errors
+- Memory leak subscribers
+- Modify event payload
+
+**USAGE**:
+- Subscribe returns unsubscribe function
+- Multiple subscribers per event allowed
+- Subscriber errors should not affect other subscribers
+- Unsubscribe when done to prevent memory leaks
 
-| Method | Parametreler | Açıklama |
-|--------|--------------|----------|
-| `ensureUserDocument` | `user` | Kullanıcı dokümanını oluştur |
-| `markUserDeleted` | `userId` | Kullanıcıyı silinmiş olarak işaretle |
-| `configureUserDocumentService` | `config` | Service konfigürasyonu |
+---
 
-### Örnekler
+## Storage Adapter
 
-#### Custom Konfigürasyon
+### StorageProviderAdapter
 
-```typescript
-import { configureUserDocumentService } from '@umituz/react-native-auth';
-
-configureUserDocumentService({
-  collection: 'customers', // Varsayılan: 'users'
-  timestamps: true,        // createdAt, updatedAt alanları ekle
-  userData: {
-    source: 'app',
-    version: '1.0.0',
-  },
-});
-```
-
-#### Custom User Data
+**PURPOSE**: Interface for storage providers (AsyncStorage, MMKV, etc.)
 
+**IMPORT PATH**:
 ```typescript
-import { ensureUserDocument } from '@umituz/react-native-auth';
-
-const user = await signInWithGoogle();
-
-await ensureUserDocument(user, {
-  role: 'user',
-  subscription: 'free',
-  preferences: {
-    newsletter: true,
-    notifications: true,
-  },
-});
+import {
+  createStorageProvider,
+  StorageProviderAdapter
+} from '@umituz/react-native-auth';
 ```
 
+**INTERFACE METHODS**:
+- `getItem(key)` - Retrieve value (returns string | null)
+- `setItem(key, value)` - Store value
+- `removeItem(key)` - Delete value
+
+**Rules**:
+- MUST implement all three methods
+- MUST handle async operations
+- MUST return null for missing keys
+- MUST handle storage errors
+- MUST only store string values
+
+**MUST NOT**:
+- Throw for missing keys
+- Skip error handling
+- Assume synchronous operations
+- Store non-string values
+- Return undefined for missing keys
+
+**IMPLEMENTATIONS**:
+- AsyncStorage (React Native default)
+- MMKV (faster alternative)
+- SecureStorage (for sensitive data)
+- Custom implementations allowed
+
 ---
 
-## AnonymousModeService
+## Validation
 
-Anonymous kullanıcı modunu yönetir.
+### AuthValidation Utilities
 
-### Kullanım
+**PURPOSE**: Input validation for authentication forms
 
+**IMPORT PATH**:
 ```typescript
-import { AnonymousModeService } from '@umituz/react-native-auth';
-
-const anonymousService = new AnonymousModeService();
-
-// Anonymous kullanıcı oluştur
-const user = await anonymousService.signInAnonymously();
-
-// Anonymous kullanıcıyı authenticated kullanıcısına yükselt
-const credential = EmailAuthProvider.credential(email, password);
-await user.linkWithCredential(credential);
+import {
+  validateEmail,
+  validatePasswordForLogin,
+  validatePasswordForRegister,
+  validatePasswordConfirmation,
+  validateDisplayName,
+  DEFAULT_VAL_CONFIG
+} from '@umituz/react-native-auth';
 ```
 
+**VALIDATORS**:
+
+**validateEmail(email)**
+- Validates email format
+- Returns: `{ isValid: boolean, error?: string }`
+
+**validatePasswordForLogin(password)**
+- Checks password not empty
+- Returns: `{ isValid: boolean, error?: string }`
+
+**validatePasswordForRegister(password)**
+- Checks password complexity
+- Returns: `{ isValid: boolean, error?: string, requirements: PasswordRequirements }`
+
+**validatePasswordConfirmation(password, confirmation)**
+- Checks passwords match
+- Returns: `{ isValid: boolean, matches: boolean, error?: string }`
+
+**validateDisplayName(name)**
+- Validates display name
+- Returns: `{ isValid: boolean, error?: string }`
+
+**Rules**:
+- MUST return validation result object
+- MUST provide error messages
+- MUST use configurable rules
+- MUST not throw for invalid input
+- MUST support internationalization
+
+**MUST NOT**:
+- Return boolean only
+- Skip error messages
+- Hardcode validation rules
+- Throw on validation failure
+- Assume required fields present
+
+**DEFAULT CONFIG**:
+- `password.minLength` - 8 characters
+- `password.requireUppercase` - true
+- `password.requireLowercase` - true
+- `password.requireNumber` - true
+- `password.requireSpecialChar` - true
+
 ---
 
-## AuthEventService
+## Migration Utilities
 
-Authentication event'lerini yönetir ve yayınlar.
+### User Data Migration
 
-### Kullanım
+**PURPOSE**: Migrate user data between collections
 
+**IMPORT PATH**:
 ```typescript
-import { AuthEventService } from '@umituz/react-native-auth';
+import {
+  migrateUserData,
+  configureMigration
+} from '@umituz/react-native-auth';
+```
 
-const eventService = new AuthEventService();
+**FUNCTIONS**:
+- `configureMigration(config)` - Configure migration
+- `migrateUserData(userId)` - Run migration
+
+**Rules**:
+- MUST configure before migrating
+- MUST transform data correctly
+- MUST handle migration errors
+- MUST verify migration success
+- MUST not delete source data automatically
+
+**MUST NOT**:
+- Skip configuration
+- Lose data during migration
+- Assume identical schemas
+- Delete source without verification
+- Migrate without backup
+
+**CONFIGURATION**:
+- `from` - Source collection name
+- `to` - Target collection name
+- `transform` - Data transformation function
+- `verify` - Verification function (optional)
 
-// Event dinle
-const unsubscribe = eventService.on('signIn', (user) => {
-  console.log('User signed in:', user);
-});
+---
 
-// Event tetikle
-eventService.emit('signIn', user);
+## Best Practices
 
-// Dinlemeyi bırak
-unsubscribe();
-```
+### Service Initialization
 
-### Event Türleri
+**MUST**:
+- Initialize services at app root
+- Wait for initialization completion
+- Handle initialization errors
+- Check initialization status
+- Configure before initialization
 
-| Event | Açıklama |
-|-------|----------|
-| `signIn` | Kullanıcı giriş yaptı |
-| `signUp` | Yeni kullanıcı kayıt oldu |
-| `signOut` | Kullanıcı çıkış yaptı |
-| `authStateChanged` | Auth state değişti |
+**MUST NOT**:
+- Initialize in components
+- Use before initialization
+- Skip error handling
+- Initialize multiple times
+- Ignore status checks
 
 ---
 
-## Migration
+### User Document Management
 
-Kullanıcı verilerini taşımak için utility:
+**MUST**:
+- Create documents on registration
+- Use server timestamps
+- Handle existing documents
+- Configure collection name
+- Add custom fields appropriately
 
-```typescript
-import { migrateUserData, configureMigration } from '@umituz/react-native-auth';
-
-// Migration konfigürasyonu
-configureMigration({
-  from: 'legacy_users',
-  to: 'users',
-  transform: (legacyData) => ({
-    displayName: legacyData.name,
-    email: legacyData.email_address,
-    createdAt: legacyData.joined_at,
-  }),
-});
-
-// Migration çalıştırma
-await migrateUserData(userId);
-```
+**MUST NOT**:
+- Skip document creation
+- Overwrite existing data unnecessarily
+- Use client timestamps
+- Hardcode collection names
+- Delete documents permanently
 
 ---
 
-## Storage Provider
+### Event Handling
 
-Custom storage provider tanımlama:
+**MUST**:
+- Emit events on all state changes
+- Support multiple subscribers
+- Provide unsubscribe function
+- Handle subscriber errors gracefully
+- Unsubscribe when done
 
-```typescript
-import {
-  createStorageProvider,
-  StorageProviderAdapter
-} from '@umituz/react-native-auth';
+**MUST NOT**:
+- Skip critical events
+- Block on subscriber errors
+- Throw unhandled errors
+- Memory leak subscribers
+- Emit duplicate events
 
-// Custom storage provider
-class CustomStorageAdapter implements StorageProviderAdapter {
-  async getItem(key: string): Promise<string | null> {
-    return await AsyncStorage.getItem(key);
-  }
+---
 
-  async setItem(key: string, value: string): Promise<void> {
-    await AsyncStorage.setItem(key, value);
-  }
+### Validation
 
-  async removeItem(key: string): Promise<void> {
-    await AsyncStorage.removeItem(key);
-  }
-}
+**MUST**:
+- Validate all user inputs
+- Provide clear error messages
+- Use consistent return types
+- Support internationalization
+- Configure rules appropriately
 
-// Kullanımı
-const storageProvider = createStorageProvider(new CustomStorageAdapter());
-```
+**MUST NOT**:
+- Skip validation
+- Return ambiguous results
+- Hardcode rules
+- Throw on invalid input
+- Assume required fields present
 
 ---
 
-## Validation
+## Error Handling
 
-Auth validasyon utility'leri:
+### Service Errors
 
-```typescript
-import {
-  validateEmail,
-  validatePasswordForLogin,
-  validatePasswordForRegister,
-  validatePasswordConfirmation,
-  validateDisplayName
-} from '@umituz/react-native-auth';
-
-// Email validasyonu
-const emailResult = validateEmail('test@example.com');
-// { isValid: true }
-
-// Şifre validasyonu (kayıt için)
-const passwordResult = validatePasswordForRegister('MyPass123!');
-// {
-//   isValid: true,
-//   requirements: { hasMinLength: true, hasUppercase: true, ... }
-// }
+**STRATEGY**:
+- Map Firebase errors to domain errors
+- Provide error context
+- Log appropriately
+- Show user-friendly messages
+- Allow retry where appropriate
 
-// Şifre validasyonu (giriş için)
-const loginPasswordResult = validatePasswordForLogin('password');
-// { isValid: true }
+**Rules**:
+- MUST map all Firebase errors
+- MUST preserve error context
+- MUST use domain error types
+- MUST handle network failures
+- MUST not expose implementation details
 
-// Şifre eşleşme validasyonu
-const matchResult = validatePasswordConfirmation('password', 'password');
-// { isValid: true, matches: true }
-
-// DisplayName validasyonu
-const nameResult = validateDisplayName('John Doe');
-// { isValid: true }
-```
+**MUST NOT**:
+- Throw raw Firebase errors
+- Lose error context
+- Expose technical details
+- Skip error logging
+- Suppress errors silently
 
 ---
 
-## İlgili Modüller
+## Related Modules
 
-- **[Domain](../../domain/README.md)** - Domain entities ve value objects
-- **[Application](../../application/README.md)** - Application ports ve interfaces
-- **[Hooks](../../presentation/hooks/README.md)** - React hooks
+- **Domain** (`../../domain/README.md`) - AuthUser entity, AuthError, AuthConfig
+- **Application** (`../../application/README.md`) - IAuthService, IAuthProvider interfaces
+- **Presentation** (`../../presentation/README.md`) - UI components and hooks