@umituz/react-native-auth 3.4.33 → 3.4.35

package/src/domain/entities/AuthUser.md

@@ -1,377 +1,236 @@
 # AuthUser Entity
 
-Authentication için provider-agnostic kullanıcı entity'si. Firebase User ile uyumlu, ancak herhangi bir auth provider ile kullanılabilir.
-
-## Tip Tanımı
-
-```typescript
-import type { AuthUser, AuthProviderType } from '@umituz/react-native-auth';
-
-interface AuthUser {
-  uid: string;                    // Unique kullanıcı ID'si
-  email: string | null;           // Email adresi (anonymous'da null)
-  displayName: string | null;     // Görünen ad
-  isAnonymous: boolean;           // Anonymous kullanıcı mı
-  emailVerified: boolean;         // Email doğrulanmış mı
-  photoURL: string | null;        // Profil fotoğrafı URL'si
-  provider: AuthProviderType;     // Auth provider tipi
-}
-
-type AuthProviderType =
-  | "google.com"      // Google ile giriş
-  | "apple.com"       // Apple ile giriş
-  | "password"        // Email/password ile giriş
-  | "anonymous"       // Anonymous kullanıcı
-  | "unknown";        // Bilinmeyen provider
-```
-
-## Örnekler
-
-### Email/Password Kullanıcısı
-
-```typescript
-const emailUser: AuthUser = {
-  uid: 'user-123',
-  email: 'john@example.com',
-  displayName: 'John Doe',
-  isAnonymous: false,
-  emailVerified: true,
-  photoURL: null,
-  provider: 'password',
-};
-```
-
-### Google Kullanıcısı
-
-```typescript
-const googleUser: AuthUser = {
-  uid: 'google-456',
-  email: 'jane@gmail.com',
-  displayName: 'Jane Smith',
-  isAnonymous: false,
-  emailVerified: true,
-  photoURL: 'https://lh3.googleusercontent.com/...',
-  provider: 'google.com',
-};
-```
-
-### Apple Kullanıcısı
-
-```typescript
-const appleUser: AuthUser = {
-  uid: 'apple-789',
-  email: 'user@icloud.com',
-  displayName: 'Apple User',
-  isAnonymous: false,
-  emailVerified: true,
-  photoURL: null,
-  provider: 'apple.com',
-};
-```
-
-### Anonymous Kullanıcı
-
-```typescript
-const anonymousUser: AuthUser = {
-  uid: 'anon-abc',
-  email: null,
-  displayName: null,
-  isAnonymous: true,
-  emailVerified: false,
-  photoURL: null,
-  provider: 'anonymous',
-};
-```
-
-## Kullanım
-
-### Firebase User'dan AuthUser'a Dönüşüm
-
-```typescript
-import { getAuth } from 'firebase/auth';
-import type { AuthUser } from '@umituz/react-native-auth';
-
-function firebaseUserToAuthUser(firebaseUser: FirebaseUser): AuthUser {
-  return {
-    uid: firebaseUser.uid,
-    email: firebaseUser.email,
-    displayName: firebaseUser.displayName,
-    isAnonymous: firebaseUser.isAnonymous,
-    emailVerified: firebaseUser.emailVerified,
-    photoURL: firebaseUser.photoURL,
-    provider: firebaseUser.providerData[0]?.providerId || 'unknown',
-  };
-}
-
-// Kullanım
-const auth = getAuth();
-const firebaseUser = auth.currentUser;
-if (firebaseUser) {
-  const user: AuthUser = firebaseUserToAuthUser(firebaseUser);
-  console.log(user.displayName);
-}
-```
-
-### DisplayName Alma
-
-```typescript
-function getUserDisplayName(user: AuthUser): string {
-  // Önce displayName'i dene
-  if (user.displayName) {
-    return user.displayName;
-  }
-
-  // Yoksa email'i kullan
-  if (user.email) {
-    // Email'den isim çıkar
-    const name = user.email.split('@')[0];
-    return name.charAt(0).toUpperCase() + name.slice(1);
-  }
-
-  // Hiçbiri yoksa varsayılan
-  return 'Kullanıcı';
-}
-
-// Kullanım
-const name = getUserDisplayName(user);
-console.log(name); // "John" veya "Johndoe"
-```
-
-### Provider Kontrolü
-
-```typescript
-function isSocialLogin(user: AuthUser): boolean {
-  return user.provider === 'google.com' || user.provider === 'apple.com';
-}
-
-function isEmailPasswordUser(user: AuthUser): boolean {
-  return user.provider === 'password';
-}
-
-function canChangePassword(user: AuthUser): boolean {
-  // Sadece email/password kullanıcıları şifre değiştirebilir
-  return user.provider === 'password';
-}
-
-// Kullanım
-if (isSocialLogin(user)) {
-  console.log('Social login ile giriş yaptı');
-}
-
-if (canChangePassword(user)) {
-  // Şifre değiştirme butonunu göster
-}
-```
-
-### Email Doğrulama Kontrolü
-
-```typescript
-function requireEmailVerification(user: AuthUser): void {
-  if (user.provider === 'password' && !user.emailVerified) {
-    throw new Error('Email doğrulanması gerekiyor');
-  }
-}
-
-function shouldShowVerifyEmailBanner(user: AuthUser): boolean {
-  return (
-    !user.isAnonymous &&
-    user.provider === 'password' &&
-    !user.emailVerified
-  );
-}
-```
-
-### Avatar URL Alma
-
-```typescript
-function getUserAvatar(user: AuthUser): string | null {
-  // Önce photoURL'yi dene
-  if (user.photoURL) {
-    return user.photoURL;
-  }
-
-  // Anonymous ise null döndür
-  if (user.isAnonymous) {
-    return null;
-  }
-
-  // Default avatar oluştur (örn: UI Avatars)
-  if (user.email) {
-    return `https://ui-avatars.com/api/?name=${encodeURIComponent(user.email)}&background=random`;
-  }
-
-  return null;
-}
-```
-
-### User İsim Oluşturma
-
-```typescript
-function getUserInitials(user: AuthUser): string {
-  if (user.displayName) {
-    const names = user.displayName.trim().split(' ');
-    if (names.length >= 2) {
-      return (names[0][0] + names[names.length - 1][0]).toUpperCase();
-    }
-    return names[0][0].toUpperCase();
-  }
-
-  if (user.email) {
-    return user.email[0].toUpperCase();
-  }
-
-  return '?';
-}
-
-// Kullanım
-const initials = getUserInitials(user);
-console.log(initials); // "JD" veya "J" veya "?"
-```
+Provider-agnostic user entity for authentication.
+
+---
+
+## Strategy
+
+**Purpose**: Represents authenticated user with provider-agnostic design. Compatible with Firebase User but works with any auth provider.
+
+**When to Use**:
+- Type-safe user representation
+- User identity management
+- Authentication operations
+- User profile display
+
+**Location**: `src/domain/entities/AuthUser.ts`
+
+---
+
+## Type Definition
+
+### AuthUser Interface
+
+**PROPERTIES**:
+- `uid: string` - Unique user identifier
+- `email: string | null` - Email address
+- `displayName: string | null` - Display name
+- `isAnonymous: boolean` - Anonymous user flag
+- `emailVerified: boolean` - Email verification status
+- `photoURL: string | null` - Profile photo URL
+- `provider: AuthProviderType` - Auth provider type
+
+### AuthProviderType
+
+**VALUES**:
+- `"google.com"` - Google authentication
+- `"apple.com"` - Apple authentication
+- `"password"` - Email/password authentication
+- `"anonymous"` - Anonymous user
+- `"unknown"` - Unknown provider
+
+**Rules**:
+- MUST have unique uid
+- MUST NOT have empty uid
+- Anonymous users have null email
+- Provider indicates auth method
+
+**Constraints**:
+- Immutable after creation
+- uid cannot be changed
+- Provider determined by auth method
+
+---
+
+## User State Management
+
+### Authenticated User
+
+**CHARACTERISTICS**:
+- Has valid uid
+- Has email or social auth
+- Not anonymous
+- May have email verified flag
+
+**Rules**:
+- MUST have uid set
+- MUST NOT be anonymous
+- SHOULD have email if password provider
+
+**Constraints**:
+- Email can be null for social auth
+- DisplayName optional
+- photoURL optional
+
+---
+
+### Anonymous User
+
+**CHARACTERISTICS**:
+- Has valid uid
+- No email
+- isAnonymous = true
+- provider = "anonymous"
+
+**Rules**:
+- MUST have isAnonymous = true
+- MUST have null email
+- provider MUST be "anonymous"
+
+**Constraints**:
+- Limited functionality
+- Data lost on sign out
+- Can be upgraded to registered account
+
+---
+
+## Provider Types
+
+### Google User
+
+**PROPERTIES**:
+- provider: "google.com"
+- emailVerified: true (typically)
+- Has Google account data
+
+**Rules**:
+- MUST use Google provider
+- MUST have verified email
+- Auto-verifies email
+
+---
+
+### Apple User
+
+**PROPERTIES**:
+- provider: "apple.com"
+- Email may be hidden (user choice)
+- iOS only
+
+**Rules**:
+- MUST use Apple provider
+- iOS platform only
+- Respect user privacy choices
+
+**Constraints**:
+- Email may be private relay
+- Not available on Android/Web
+
+---
+
+### Email/Password User
+
+**PROPERTIES**:
+- provider: "password"
+- emailVerified may be false initially
+- Standard auth flow
+
+**Rules**:
+- MUST have email
+- Email may require verification
+- Can change password
+
+**Constraints**:
+- Email required
+- Password managed by user
+
+---
+
+## User Display
+
+### Display Name Priority
+
+**RULES**:
+1. Use displayName if available
+2. Fall back to email username
+3. Fall back to "User" for anonymous
+4. MUST NOT expose sensitive data
+
+**CONSTRAINTS**:
+- Display name: User-controlled
+- Email: Only first part before @
+- Anonymous: Generated or "Guest"
+
+---
+
+### Profile Photo
+
+**RULES**:
+- MUST provide fallback if null
+- MUST handle loading state
+- MUST not break if missing
+
+**FALLBACK OPTIONS**:
+- Default avatar generator
+- User initials
+- Placeholder icon
+- Null (no avatar)
+
+---
 
 ## Type Guards
 
-```typescript
-function isAuthenticatedUser(user: AuthUser | null): user is AuthUser {
-  return user !== null && !user.isAnonymous;
-}
-
-function isAnonymousUser(user: AuthUser | null): user is AuthUser {
-  return user !== null && user.isAnonymous;
-}
-
-function hasEmail(user: AuthUser | null): user is AuthUser {
-  return user !== null && user.email !== null;
-}
-
-// Kullanım
-if (isAuthenticatedUser(user)) {
-  // TypeScript burada user'ın AuthUser olduğunu bilir
-  console.log(user.email);
-}
-```
-
-## Firebase ile Entegrasyon
-
-### Auth State Değişikliği Dinleme
-
-```typescript
-import { getAuth, onAuthStateChanged } from 'firebase/auth';
-import type { AuthUser } from '@umituz/react-native-auth';
-
-function useAuthUser() {
-  const [user, setUser] = useState<AuthUser | null>(null);
-
-  useEffect(() => {
-    const auth = getAuth();
-    const unsubscribe = onAuthStateChanged(auth, (firebaseUser) => {
-      if (firebaseUser) {
-        const authUser: AuthUser = {
-          uid: firebaseUser.uid,
-          email: firebaseUser.email,
-          displayName: firebaseUser.displayName,
-          isAnonymous: firebaseUser.isAnonymous,
-          emailVerified: firebaseUser.emailVerified,
-          photoURL: firebaseUser.photoURL,
-          provider: firebaseUser.providerData[0]?.providerId || 'unknown',
-        };
-        setUser(authUser);
-      } else {
-        setUser(null);
-      }
-    });
-
-    return unsubscribe;
-  }, []);
-
-  return user;
-}
-```
-
-### User Meta Verileri
-
-```typescript
-interface ExtendedAuthUser extends AuthUser {
-  createdAt?: number;
-  lastSignInAt?: number;
-  metadata?: {
-    lastSignInTime?: string;
-    creationTime?: string;
-  };
-}
-
-function enrichAuthUser(user: AuthUser, firebaseUser: FirebaseUser): ExtendedAuthUser {
-  return {
-    ...user,
-    metadata: {
-      lastSignInTime: firebaseUser.metadata.lastSignInTime,
-      creationTime: firebaseUser.metadata.creationTime,
-    },
-  };
-}
-```
-
-## Validasyon
-
-### User Validasyonu
-
-```typescript
-function validateAuthUser(user: AuthUser): { valid: boolean; errors: string[] } {
-  const errors: string[] = [];
-
-  if (!user.uid || user.uid.length === 0) {
-    errors.push('User ID is required');
-  }
-
-  if (!user.isAnonymous && !user.email) {
-    errors.push('Email is required for non-anonymous users');
-  }
-
-  if (user.email && !isValidEmail(user.email)) {
-    errors.push('Invalid email format');
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-  };
-}
-
-function isValidEmail(email: string): boolean {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-}
-```
-
-## Testler
-
-### Mock User Oluşturma
-
-```typescript
-function createMockAuthUser(overrides?: Partial<AuthUser>): AuthUser {
-  return {
-    uid: 'mock-user-123',
-    email: 'mock@example.com',
-    displayName: 'Mock User',
-    isAnonymous: false,
-    emailVerified: true,
-    photoURL: null,
-    provider: 'password',
-    ...overrides,
-  };
-}
-
-// Testlerde kullanım
-const mockUser = createMockAuthUser({
-  provider: 'google.com',
-  photoURL: 'https://example.com/avatar.jpg',
-});
-```
-
-## İlgili Entity'ler
-
-- **[`UserProfile`](./UserProfile.md)** - Kullanıcı profili entity'si
-- **[`AuthError`](../errors/AuthError.md)** - Auth hataları
-
-## İlgili Type'lar
-
-- **[`AuthProviderType`](#tip-tanımı)** - Provider tipi
-- **[`UpdateProfileParams`](../UserProfile.md)** - Profil güncelleme parametreleri
+### User Type Checks
+
+**isAuthenticatedUser(user)**
+- Checks if user exists and not anonymous
+- Type guard for TypeScript
+
+**isAnonymousUser(user)**
+- Checks if anonymous user
+- Type guard for TypeScript
+
+**hasEmail(user)**
+- Checks if has email
+- Type guard for TypeScript
+
+**Rules**:
+- MUST use for type narrowing
+- MUST validate before operations
+- MUST check null cases
+
+---
+
+## Validation
+
+### User Validation Rules
+
+**MUST**:
+- Validate uid is not empty
+- Validate email format if provided
+- Check provider is valid
+- Verify required fields
+
+**MUST NOT**:
+- Allow empty uid
+- Accept invalid email format
+- Use wrong provider type
+
+**Constraints**:
+- uid required
+- Email format validated
+- Provider must be known type
+
+---
+
+## Related Entities
+
+- **UserProfile** (`./UserProfile.md`) - User profile entity
+- **AuthConfig** (`./ConfigAndErrors.md`) - Configuration
+- **AuthError** (`./ConfigAndErrors.md`) - Error handling
+
+## Related Infrastructure
+
+- **AuthService** (`../../infrastructure/services/AuthService.ts`) - Auth operations
+- **Firebase Auth** - Firebase integration