@umituz/react-native-auth 3.4.33 → 3.4.34

package/src/infrastructure/README.md

@@ -1,576 +1,520 @@
 # Infrastructure Layer
 
-React Native Auth package infrastructure layer. Contains implementations of application interfaces and external service integrations.
+Implements application interfaces and handles external service integrations.
 
-## Structure
+---
 
-```
-infrastructure/
-├── providers/
-│   └── FirebaseAuthProvider.ts    # Firebase auth implementation
-├── services/
-│   ├── AuthService.ts              # Main auth service
-│   ├── initializeAuth.ts           # Auth initialization
-│   ├── UserDocumentService.ts      # User document management
-│   ├── AnonymousModeService.ts     # Anonymous user service
-│   └── AuthEventService.ts         # Event handling
-├── adapters/
-│   └── StorageProviderAdapter.ts   # Storage adapter
-└── utils/
-    └── AuthValidation.ts           # Validation utilities
-```
+## Strategy
 
-## Overview
+**Purpose**: Provides concrete implementations of domain and application layer interfaces. Handles all external dependencies and integrations.
 
-The infrastructure layer implements the interfaces defined in the application layer and handles all external integrations:
+**When to Use**:
+- Understanding Firebase integration
+- Implementing custom services
+- Debugging infrastructure issues
+- Learning about external dependencies
 
-- **Firebase Authentication**: Primary auth provider implementation
-- **Firestore**: User document storage
-- **Firebase Storage**: Profile photo storage
-- **Validation**: Input validation utilities
+**Location**: `src/infrastructure/`
 
 ---
 
-# FirebaseAuthProvider
-
-Firebase Authentication implementation of `IAuthProvider`.
-
-## Features
+## Structure
 
-- Email/Password authentication
-- Google sign-in
-- Apple sign-in
-- Anonymous authentication
-- User state management
+### Services
 
-## Usage
+**AuthService.ts** - Main authentication service
+**Purpose**: Orchestrates all authentication operations
 
+**IMPORT PATH**:
 ```typescript
-import { FirebaseAuthProvider } from '@umituz/react-native-auth';
-import { getAuth } from 'firebase/auth';
-
-const firebaseAuth = getAuth();
-const provider = new FirebaseAuthProvider(firebaseAuth);
-
-// Sign up
-const user = await provider.signUp({
-  email: 'user@example.com',
-  password: 'password123',
-  displayName: 'John Doe',
-});
-
-// Sign in
-const user = await provider.signIn({
-  email: 'user@example.com',
-  password: 'password123',
-});
-
-// Sign out
-await provider.signOut();
-
-// Get current user
-const currentUser = provider.getCurrentUser();
+import { AuthService, initializeAuth } from '@umituz/react-native-auth';
 ```
 
----
-
-# AuthService
+**Rules**:
+- MUST implement IAuthService interface
+- MUST initialize before use
+- MUST handle Firebase errors
+- MUST create user documents
+- MUST not expose Firebase internals
 
-Main authentication service that orchestrates all auth operations.
+**MUST NOT**:
+- Skip initialization
+- Expose Firebase types
+- Ignore error handling
+- Create multiple instances
 
-## Features
+---
 
-- User authentication flow
-- User document creation
-- Error handling
-- State management
+### UserDocumentService
 
-## Usage
+**Purpose**: Manages Firestore user documents
 
+**IMPORT PATH**:
 ```typescript
 import {
-  AuthService,
-  initializeAuthService,
-  getAuthService,
-  resetAuthService,
+  ensureUserDocument,
+  markUserDeleted,
+  configureUserDocumentService
 } from '@umituz/react-native-auth';
-
-// Initialize (must be called once)
-initializeAuthService({
-  firebaseAuth: getAuth(),
-  onAuthStateChanged: (user) => {
-    console.log('Auth state changed:', user);
-  },
-});
-
-// Get service instance
-const authService = getAuthService();
-
-// Sign in
-const user = await authService.signIn({
-  email: 'user@example.com',
-  password: 'password123',
-});
-
-// Sign up
-const user = await authService.signUp({
-  email: 'user@example.com',
-  password: 'password123',
-  displayName: 'John Doe',
-});
-
-// Sign out
-await authService.signOut();
-
-// Reset (testing only)
-resetAuthService();
 ```
 
-## API
-
-### Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `signIn` | `{ email, password }` | `Promise<AuthUser>` | Sign in with email/password |
-| `signUp` | `{ email, password, displayName? }` | `Promise<AuthUser>` | Create new account |
-| `signOut` | - | `Promise<void>` | Sign out current user |
-| `getCurrentUser` | - | `AuthUser \| null` | Get current user |
-| `sendPasswordResetEmail` | `email` | `Promise<void>` | Send password reset email |
+**OPERATIONS**:
+- `ensureUserDocument(user, data?)` - Create/retrieve user document
+- `markUserDeleted(userId)` - Mark user as deleted
+- `configureUserDocumentService(config)` - Configure service
+
+**Rules**:
+- MUST create document on registration
+- MUST handle 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
+
+**CONFIGURATION**:
+- `collection` - Firestore collection name (default: 'users')
+- `timestamps` - Add createdAt/updatedAt fields
+- `userData` - Custom fields to add
 
 ---
 
-# initializeAuth
-
-Initializes the authentication system and sets up Firebase Auth state listener.
-
-## Features
-
-- Firebase Auth initialization
-- Auth state listener setup
-- Automatic user document creation
-- Error handling
+### AnonymousModeService
 
-## Usage
-
-### Basic Initialization
+**Purpose**: Handles anonymous user authentication and upgrade
 
+**IMPORT PATH**:
 ```typescript
-import { initializeAuth } from '@umituz/react-native-auth';
-
-function App() {
-  useEffect(() => {
-    const init = async () => {
-      await initializeAuth({
-        onAuthStateChanged: (user) => {
-          console.log('Auth state changed:', user);
-        },
-      });
-    };
-
-    init();
-  }, []);
-
-  return <AppNavigator />;
-}
+import { AnonymousModeService } from '@umituz/react-native-auth';
 ```
 
-### With Navigation Integration
+**OPERATIONS**:
+- `signInAnonymously()` - Create anonymous user
+- User upgrade via Firebase credential linking
+
+**Rules**:
+- MUST create temporary accounts
+- MUST support upgrade path
+- MUST warn about data loss
+- MUST handle upgrade failures
+- MUST not delete anonymous data
+
+**MUST NOT**:
+- Skip upgrade warnings
+- Lose user data on upgrade
+- Allow anonymous operations without warning
+- Make anonymous permanent
+
+**Constraints**:
+- Anonymous users have limited functionality
+- Data lost if sign out without upgrade
+- Upgrade requires credentials
+- Cannot revert to anonymous after upgrade
 
-```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 Error', error.message);
-      },
-    });
-  }, []);
-
-  return <NavigationContainer>{/* Routes */}</NavigationContainer>;
-}
-```
+### AuthEventService
 
-### Check Initialization Status
+**Purpose**: Pub/sub system for authentication events
 
+**IMPORT PATH**:
 ```typescript
-import { isAuthInitialized, resetAuthInitialization } from '@umituz/react-native-auth';
-
-if (isAuthInitialized()) {
-  console.log('Auth is initialized');
-}
-
-// Reset (testing only)
-resetAuthInitialization();
+import { AuthEventService } from '@umituz/react-native-auth';
 ```
 
----
-
-# UserDocumentService
-
-Manages user documents in Firestore.
+**OPERATIONS**:
+- `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 allow multiple subscribers
+- MUST provide unsubscribe function
+- MUST not throw in event handlers
+- MUST handle subscriber errors
+
+**MUST NOT**:
+- Skip critical events
+- Block on event handlers
+- Throw unhandled errors
+- Memory leak subscribers
 
-## Features
-
-- Automatic user document creation
-- User data updates
-- Account deletion marking
-- Custom configuration
+---
 
-## Usage
+### StorageProviderAdapter
 
-### Ensure User Document
+**Purpose**: Adapter interface for storage providers
 
+**IMPORT PATH**:
 ```typescript
-import { ensureUserDocument } from '@umituz/react-native-auth';
-
-// After user signs in/up, ensure document exists
-const user = await signInWithEmailAndPassword(auth, email, password);
-await ensureUserDocument(user);
+import {
+  createStorageProvider,
+  StorageProviderAdapter
+} from '@umituz/react-native-auth';
 ```
 
-### Mark User as Deleted
+**INTERFACE METHODS**:
+- `getItem(key)` - Retrieve value
+- `setItem(key, value)` - Store value
+- `removeItem(key)` - Delete value
+
+**Rules**:
+- MUST implement all methods
+- MUST handle async operations
+- MUST return null for missing keys
+- MUST handle storage errors
+- MUST support string values only
+
+**MUST NOT**:
+- Throw for missing keys
+- Skip error handling
+- Assume synchronous operations
+- Store non-string values
+
+**IMPLEMENTATIONS**:
+- AsyncStorage
+- MMKV
+- SecureStorage
+- Custom implementations
 
-```typescript
-import { markUserDeleted } from '@umituz/react-native-auth';
+---
 
-// When user deletes account
-await markUserDeleted(userId);
-```
+## Validation Utilities
+
+### AuthValidation
 
-### Configure Service
+**Purpose**: Input validation for authentication
 
+**IMPORT PATH**:
 ```typescript
-import { configureUserDocumentService } from '@umituz/react-native-auth';
-
-configureUserDocumentService({
-  collection: 'customers', // Default: 'users'
-  timestamps: true,        // Add createdAt, updatedAt
-  userData: {
-    source: 'app',
-    version: '1.0.0',
-  },
-});
+import {
+  validateEmail,
+  validatePasswordForLogin,
+  validatePasswordForRegister,
+  validatePasswordConfirmation,
+  validateDisplayName,
+  DEFAULT_VAL_CONFIG
+} from '@umituz/react-native-auth';
 ```
 
-### Custom User Data
+**VALIDATORS**:
+- `validateEmail(email)` - Email format validation
+- `validatePasswordForLogin(password)` - Login password check
+- `validatePasswordForRegister(password)` - Registration password complexity
+- `validatePasswordConfirmation(password, confirmation)` - Password match
+- `validateDisplayName(name)` - Display name validation
 
+**RETURN TYPE**:
 ```typescript
-await ensureUserDocument(user, {
-  role: 'premium',
-  subscription: 'monthly',
-  preferences: {
-    newsletter: true,
-    notifications: true,
-  },
-});
+{
+  isValid: boolean;
+  error?: string;
+  // Additional fields for specific validators
+}
 ```
 
----
-
-# AnonymousModeService
+**Rules**:
+- MUST return validation result object
+- MUST provide error messages
+- MUST use configurable rules
+- MUST support internationalization
+- MUST not throw for invalid input
+
+**MUST NOT**:
+- Return boolean only
+- Skip error messages
+- Hardcode validation rules
+- Throw on validation failure
+
+**DEFAULT CONFIG**:
+- `password.minLength` - 8 characters
+- `password.requireUppercase` - true
+- `password.requireLowercase` - true
+- `password.requireNumber` - true
+- `password.requireSpecialChar` - true
 
-Handles anonymous user authentication.
+---
 
-## Features
+## Firebase Integration
 
-- Anonymous account creation
-- Anonymous user upgrade to regular account
-- Anonymous state management
+### FirebaseAuthProvider
 
-## Usage
+**Purpose**: Firebase Authentication implementation
 
-```typescript
-import { AnonymousModeService } from '@umituz/react-native-auth';
+**Location**: `providers/FirebaseAuthProvider.ts`
 
-const anonymousService = new AnonymousModeService();
+**Rules**:
+- MUST implement IAuthProvider
+- MUST wrap Firebase SDK
+- MUST handle Firebase lifecycle
+- MUST map to domain entities
+- MUST convert Firebase errors
 
-// Sign in anonymously
-const user = await anonymousService.signInAnonymously();
-console.log('Anonymous user:', user.uid);
-
-// Convert anonymous user to regular user
-const credential = EmailAuthProvider.credential(email, password);
-await linkWithCredential(user, credential);
-console.log('User upgraded:', user.email);
-```
+**MUST NOT**:
+- Expose Firebase types
+- Bypass error mapping
+- Skip Firebase initialization
+- Ignore auth state changes
 
 ---
 
-# AuthEventService
-
-Manages authentication events and provides pub/sub functionality.
-
-## Features
+### Error Mapping
 
-- Event emission
-- Event subscription
-- Type-safe events
-
-## Usage
+**Purpose**: Convert Firebase errors to domain errors
 
+**IMPORT PATH**:
 ```typescript
-import { AuthEventService } from '@umituz/react-native-auth';
-
-const eventService = new AuthEventService();
-
-// Subscribe to events
-const unsubscribe = eventService.on('signIn', (user) => {
-  console.log('User signed in:', user);
-});
-
-// Emit events
-eventService.emit('signIn', user);
-
-// Unsubscribe
-unsubscribe();
+import { mapFirebaseError } from '@umituz/react-native-auth';
 ```
 
-### Available Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `signIn` | `AuthUser` | User signed in |
-| `signUp` | `AuthUser` | New user registered |
-| `signOut` | `undefined` | User signed out |
-| `authStateChanged` | `AuthUser \| null` | Auth state changed |
+**MAPPING**:
+- `auth/user-not-found` → AuthUserNotFoundError
+- `auth/wrong-password` → AuthWrongPasswordError
+- `auth/email-already-in-use` → AuthEmailAlreadyInUseError
+- `auth/weak-password` → AuthWeakPasswordError
+- `auth/invalid-email` → AuthInvalidEmailError
+- `auth/network-request-failed` → AuthNetworkError
+
+**Rules**:
+- MUST map all Firebase errors
+- MUST preserve error context
+- MUST use domain error types
+- MUST not lose error information
+- MUST handle unknown errors
+
+**MUST NOT**:
+- Throw raw Firebase errors
+- Skip error mapping
+- Lose error context
+- Use generic error type
 
 ---
 
-# StorageProviderAdapter
+## Initialization
 
-Adapter for storage providers (AsyncStorage, MMKV, etc.).
+### initializeAuth
 
-## Usage
+**Purpose**: Initialize authentication system
 
+**IMPORT PATH**:
 ```typescript
-import {
-  createStorageProvider,
-  StorageProviderAdapter,
-} from '@umituz/react-native-auth';
+import { initializeAuth } from '@umituz/react-native-auth';
+```
 
-// Custom implementation
-class CustomStorageAdapter implements StorageProviderAdapter {
-  async getItem(key: string): Promise<string | null> {
-    return await AsyncStorage.getItem(key);
-  }
+**PARAMETERS**:
+- `onAuthStateChanged` - Auth state callback
+- `onAuthError` - Error callback (optional)
 
-  async setItem(key: string, value: string): Promise<void> {
-    await AsyncStorage.setItem(key, value);
-  }
+**Rules**:
+- MUST call once at app startup
+- MUST wait for initialization
+- MUST handle initialization errors
+- MUST not call multiple times
+- MUST check initialization status
 
-  async removeItem(key: string): Promise<void> {
-    await AsyncStorage.removeItem(key);
-  }
-}
+**MUST NOT**:
+- Skip initialization
+- Call in components
+- Initialize multiple times
+- Ignore initialization status
 
-// Create provider
-const storageProvider = createStorageProvider(new CustomStorageAdapter());
-```
+**CHECK FUNCTIONS**:
+- `isAuthInitialized()` - Check if initialized
+- `resetAuthInitialization()` - Reset (testing only)
 
 ---
 
-# Validation Utilities
+## Configuration
 
-Input validation utilities for authentication.
+### Service Configuration
 
-## Available Validators
+**AuthService Configuration**:
+- Firebase Auth instance
+- Auth state callbacks
+- Error handlers
 
-```typescript
-import {
-  validateEmail,
-  validatePasswordForLogin,
-  validatePasswordForRegister,
-  validatePasswordConfirmation,
-  validateDisplayName,
-  DEFAULT_VAL_CONFIG,
-} from '@umituz/react-native-auth';
-```
+**UserDocumentService Configuration**:
+- Collection name
+- Timestamps
+- Custom user data
 
-### Email Validation
+**Validation Configuration**:
+- Password requirements
+- Email validation rules
+- Display name constraints
 
-```typescript
-const result = validateEmail('test@example.com');
-// { isValid: true }
+**Rules**:
+- MUST configure before use
+- MUST use valid configuration
+- MUST handle config errors
+- MUST not change after initialization
+- MUST validate configuration
 
-const result = validateEmail('invalid-email');
-// { isValid: false, error: 'Invalid email format' }
-```
+**MUST NOT**:
+- Skip configuration
+- Use invalid config
+- Change after initialization
+- Ignore config errors
 
-### Password Validation (Login)
+---
 
-```typescript
-const result = validatePasswordForLogin('password123');
-// { isValid: true }
+## Best Practices
 
-const result = validatePasswordForLogin('');
-// { isValid: false, error: 'Password is required' }
-```
+### Initialization
 
-### Password Validation (Register)
+**MUST**:
+- Initialize at app root
+- Wait for initialization
+- Handle initialization errors
+- Check initialization status
+- Configure properly
 
-```typescript
-const result = validatePasswordForRegister('MyPass123!');
-// {
-//   isValid: true,
-//   requirements: {
-//     hasMinLength: true,
-//     hasUppercase: true,
-//     hasLowercase: true,
-//     hasNumber: true,
-//     hasSpecialChar: true
-//   }
-// }
-
-const result = validatePasswordForRegister('weak');
-// {
-//   isValid: false,
-//   requirements: { ... },
-//   error: 'Password does not meet requirements'
-// }
-```
+**MUST NOT**:
+- Initialize in components
+- Skip initialization check
+- Ignore initialization errors
+- Initialize multiple times
+- Use default config blindly
 
-### Password Confirmation
+---
 
-```typescript
-const result = validatePasswordConfirmation('password123', 'password123');
-// { isValid: true, matches: true }
+### Error Handling
 
-const result = validatePasswordConfirmation('password123', 'different');
-// { isValid: false, matches: false, error: 'Passwords do not match' }
-```
+**MUST**:
+- Map Firebase errors to domain
+- Provide context
+- Log appropriately
+- Show user-friendly messages
+- Handle network failures
 
-### Display Name Validation
+**MUST NOT**:
+- Expose Firebase errors
+- Show technical details
+- Skip error mapping
+- Suppress errors
+- Log sensitive data
 
-```typescript
-const result = validateDisplayName('John Doe');
-// { isValid: true }
+---
 
-const result = validateDisplayName('');
-// { isValid: false, error: 'Display name is required' }
-```
+### User Documents
 
-### Custom Validation Config
+**MUST**:
+- Create document on registration
+- Use server timestamps
+- Handle existing documents
+- Configure collection name
+- Add custom fields
 
-```typescript
-import { DEFAULT_VAL_CONFIG } from '@umituz/react-native-auth';
-
-// Default config
-DEFAULT_VAL_CONFIG;
-// {
-//   password: {
-//     minLength: 8,
-//     requireUppercase: true,
-//     requireLowercase: true,
-//     requireNumber: true,
-//     requireSpecialChar: true,
-//   }
-// }
-```
+**MUST NOT**:
+- Skip document creation
+- Overwrite data
+- Use client timestamps
+- Hardcode collection name
+- Delete documents permanently
 
 ---
 
-# Error Handling
+## Security
 
-## Firebase Error Mapping
+### Data Protection
 
-```typescript
-import {
-  mapFirebaseError,
-  AuthUserNotFoundError,
-  AuthWrongPasswordError,
-} from '@umituz/react-native-auth';
+**MUST**:
+- Validate all inputs
+- Use HTTPS
+- Handle tokens properly
+- Secure credentials
+- Log appropriately
 
-try {
-  await signInWithEmailAndPassword(auth, email, password);
-} catch (error) {
-  const authError = mapFirebaseError(error);
+**MUST NOT**:
+- Log passwords
+- Expose tokens
+- Skip validation
+- Store credentials insecurely
+- Log sensitive data
 
-  if (authError instanceof AuthUserNotFoundError) {
-    Alert.alert('Error', 'User not found');
-  } else if (authError instanceof AuthWrongPasswordError) {
-    Alert.alert('Error', 'Wrong password');
-  }
-}
-```
+---
+
+### Firebase Security
+
+**MUST**:
+- Use Firebase security rules
+- Enable required providers
+- Configure properly
+- Monitor usage
+- Handle errors
+
+**MUST NOT**:
+- Skip Firebase setup
+- Ignore security rules
+- Expose API keys
+- Leave unconfigured
+- Ignore Firebase errors
 
 ---
 
-# Best Practices
+## Constraints
 
-## 1. Initialize Early
+### Platform Limitations
 
-```typescript
-// ✅ Good - Initialize in app root
-function App() {
-  useEffect(() => {
-    initializeAuth();
-  }, []);
+**Firebase Dependencies**:
+- Requires Firebase project
+- Requires Firebase SDK
+- Requires network connection
+- Platform-specific features
 
-  return <Navigator />;
-}
+**Rules**:
+- MUST check platform availability
+- MUST handle platform differences
+- MUST not crash on unsupported
+- MUST document platform constraints
 
-// ❌ Bad - Initialize in component
-function LoginComponent() {
-  useEffect(() => {
-    initializeAuth(); // Too late!
-  }, []);
-}
-```
+---
 
-## 2. Handle Initialization State
+### Network Requirements
 
-```typescript
-function App() {
-  const [isInitialized, setIsInitialized] = useState(false);
+**MUST**:
+- Handle network failures
+- Provide offline fallback
+- Show network errors
+- Allow retry
+- Check connectivity
 
-  useEffect(() => {
-    initializeAuth().then(() => setIsInitialized(true));
-  }, []);
+**MUST NOT**:
+- Assume always online
+- Skip network errors
+- Crash on network failure
+- Prevent offline usage
 
-  if (!isInitialized) {
-    return <LoadingScreen />;
-  }
+---
 
-  return <AppNavigator />;
-}
-```
+## Related Modules
 
-## 3. Check Auth Before Operations
+- **Domain** (`../domain/README.md`) - AuthUser entity, errors, config
+- **Application** (`../application/README.md`) - Interfaces and ports
+- **Presentation** (`../presentation/README.md`) - UI components
 
-```typescript
-async function protectedOperation() {
-  const authService = getAuthService();
-  const user = authService.getCurrentUser();
+---
 
-  if (!user) {
-    throw new Error('User not authenticated');
-  }
+## Service Documentation
 
-  // Proceed with operation
-}
-```
+### Detailed Service Docs
 
-## Related Modules
+**See**: `services/README.md` for detailed service documentation
 
-- **[Domain](../domain/README.md)** - Domain entities
-- **[Application](../application/README.md)** - Application interfaces
-- **[Presentation](../presentation/README.md)** - UI components and hooks
+**Services Covered**:
+- AuthService
+- UserDocumentService
+- AnonymousModeService
+- AuthEventService
+- Validation utilities