@umituz/react-native-firebase 1.13.58 → 1.13.60

package/src/auth/domain/errors/README.md

@@ -0,0 +1,291 @@
+# Auth Errors
+
+Firebase Authentication error types and error handling utilities.
+
+## Purpose
+
+Provides custom error classes for Firebase Authentication operations with structured error handling, type safety, and user-friendly error messages.
+
+## For AI Agents
+
+### Before Using Auth Errors
+
+1. **USE** custom error classes (not raw Firebase errors)
+2. **CHECK** error types with instanceof
+3. **PROVIDE** user-friendly error messages
+4. **HANDLE** retryable errors appropriately
+5. **LOG** errors for debugging
+
+### Required Practices
+
+1. **Use custom error classes** - Import from auth module
+2. **Check error types** - Use instanceof for type checking
+3. **Map error codes** - Convert to user-friendly messages
+4. **Handle retryable errors** - Implement retry logic
+5. **Log errors** - Include context for debugging
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Throw primitive values (always Error instances)
+- Show technical error messages to users
+- Ignore error codes
+- Assume all errors are fatal
+- Catch and suppress errors silently
+
+## ⚠️ Avoid
+
+- Generic error handling
+- Not checking error types
+- Not providing user feedback
+- Missing error context
+- Not logging auth errors
+
+## Error Classes
+
+### FirebaseAuthError
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+**Purpose:** Base error class for all Firebase Auth errors
+
+**Properties:**
+- `code: string` - Error code for programmatic handling
+- `message: string` - Human-readable error message
+
+**Usage:**
+- Base class for all auth errors
+- Type checking with instanceof
+- Error code for conditional logic
+
+**When to Use:**
+- Throwing custom auth errors
+- Catching and handling auth errors
+- Type-safe error handling
+
+### FirebaseAuthInitializationError
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+**Purpose:** Error thrown when Firebase Auth fails to initialize
+
+**Extends:** FirebaseAuthError
+
+**Usage:**
+- Initialization failures
+- Configuration errors
+- Firebase setup issues
+
+**When to Use:**
+- Auth not initialized
+- Invalid Firebase config
+- Initialization timeout
+
+## Error Handling Strategies
+
+### For Auth Operation Errors
+
+**Strategy:** Catch and handle auth errors with user-friendly messages.
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+**When to Use:**
+- Sign-in failures
+- Sign-up failures
+- Password reset failures
+- Email verification failures
+
+**Handling Strategy:**
+1. Wrap auth operation in try-catch
+2. Check error type with instanceof
+3. Map error code to user message
+4. Display error to user
+5. Provide retry option if appropriate
+6. Log technical error for debugging
+
+### For Initialization Errors
+
+**Strategy:** Handle Firebase Auth initialization failures.
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+**When to Use:**
+- App startup
+- Auth service initialization
+- Configuration loading
+
+**Handling Strategy:**
+1. Catch initialization error
+2. Check if FirebaseAuthInitializationError
+3. Show setup error message
+4. Provide setup instructions
+5. Offer retry option
+
+### For Network Errors
+
+**Strategy:** Retry transient network failures.
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+**When to Use:**
+- Network connection failed
+- Request timeout
+- Service unavailable
+
+**Handling Strategy:**
+1. Check error code for network issues
+2. Show network error message
+3. Provide retry button
+4. Implement retry with delay
+5. Limit retry attempts
+
+### For User-Facing Messages
+
+**Strategy:** Map error codes to user-friendly messages.
+
+**Import From:** Use error.code to map messages
+
+**Common Error Messages:**
+- `INVALID_CREDENTIALS` → "Invalid email or password"
+- `USER_NOT_FOUND` → "Account not found"
+- `WEAK_PASSWORD` → "Password is too weak"
+- `EMAIL_ALREADY_IN_USE` → "Email already registered"
+- `NETWORK_ERROR` → "Network error. Please check your connection"
+- `TOO_MANY_REQUESTS` → "Too many attempts. Please try again later"
+
+**Implementation:**
+1. Create error message mapper
+2. Map error codes to messages
+3. Display message to user
+4. Provide action buttons
+5. Handle retry scenarios
+
+## Error Codes Reference
+
+### Common Error Codes
+
+**Import From:** Error.code property
+
+| Error Code | Description | Retryable | User Message |
+|------------|-------------|-----------|--------------|
+| `INVALID_CREDENTIALS` | Invalid email or password | No | Invalid email or password |
+| `USER_NOT_FOUND` | User account not found | No | Account not found |
+| `WEAK_PASSWORD` | Password too weak | No | Password is too weak |
+| `EMAIL_ALREADY_IN_USE` | Email already registered | No | Email already registered |
+| `NETWORK_ERROR` | Network connection failed | Yes | Network error. Check connection |
+| `TIMEOUT` | Request timeout | Yes | Request timeout. Try again |
+| `TOO_MANY_REQUESTS` | Rate limit exceeded | Yes | Too many attempts. Wait |
+| `USER_DISABLED` | User account disabled | No | Account disabled |
+| `INVALID_EMAIL` | Invalid email format | No | Invalid email format |
+| `EMAIL_NOT_VERIFIED` | Email not verified | No | Please verify your email |
+
+## Common Mistakes to Avoid
+
+1. ❌ Not checking error types
+   - ✅ Use instanceof for type checking
+
+2. ❌ Showing technical messages to users
+   - ✅ Map error codes to user-friendly messages
+
+3. ❌ Not providing retry options
+   - ✅ Offer retry for retryable errors
+
+4. ❌ Not logging errors
+   - ✅ Log errors with context
+
+5. ❌ Generic error handling
+   - ✅ Handle specific error types
+
+## AI Agent Instructions
+
+### When Handling Auth Errors
+
+1. Wrap auth operations in try-catch
+2. Check error type with instanceof
+3. Map error code to user message
+4. Display user-friendly message
+5. Provide retry option if appropriate
+6. Log technical error for debugging
+
+### When Creating Error Messages
+
+1. Map error codes to messages
+2. Use clear, non-technical language
+3. Provide actionable next steps
+4. Keep messages concise
+5. Localize if needed
+
+### When Implementing Retry Logic
+
+1. Check if error is retryable
+2. Show retry button to user
+3. Implement retry with delay
+4. Limit retry attempts
+5. Show countdown if rate limited
+
+## Code Quality Standards
+
+### Error Handling
+
+- Always use custom error classes
+- Check error types before handling
+- Provide user-friendly messages
+- Log errors with context
+- Handle specific error types
+
+### Type Safety
+
+- Use instanceof for type checking
+- Never use `any` for errors
+- Type all error parameters
+- Export error classes
+- Use discriminated unions
+
+### User Experience
+
+- Show clear error messages
+- Provide actionable next steps
+- Offer retry when appropriate
+- Don't show technical details
+- Test error flows
+
+## Performance Considerations
+
+### Error Logging
+
+- Log errors asynchronously
+- Don't block on logging
+- Include context (operation, userId)
+- Sanitize sensitive data
+- Use error tracking service
+
+### Retry Logic
+
+- Limit retry attempts
+- Use exponential backoff
+- Show retry progress
+- Don't retry non-retryable errors
+- Consider rate limiting
+
+## Related Documentation
+
+- [Auth Module README](../../README.md)
+- [Auth Services README](../infrastructure/services/README.md)
+- [Auth Stores README](../infrastructure/stores/README.md)
+
+## API Reference
+
+### Error Classes
+
+**Import Path:** `@umituz/react-native-firebase/auth` or `src/auth/domain/errors`
+
+| Class | Constructor Parameters | Description |
+|-------|----------------------|-------------|
+| `FirebaseAuthError` | `(message: string, code: string)` | Base auth error |
+| `FirebaseAuthInitializationError` | `(message: string)` | Init error |
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Auth Module Team

package/src/auth/infrastructure/config/README.md

@@ -0,0 +1,239 @@
+# Auth Configuration
+
+Firebase Authentication client initialization, configuration management, and service access.
+
+## Purpose
+
+Provides core Firebase Auth client functionality including initialization, state management, service access, error handling, and client reset.
+
+## For AI Agents
+
+### Before Using Auth Config
+
+1. **INITIALIZE** Auth once at app startup
+2. **CHECK** initialization status before use
+3. **USE** getFirebaseAuth() to get Auth instance
+4. **HANDLE** initialization errors appropriately
+5. **NEVER** initialize Auth multiple times
+
+### Required Practices
+
+1. **Initialize once** - Call initializeFirebaseAuth() at app startup
+2. **Check status** - Verify initialization before using Auth
+3. **Get Auth instance** - Use getFirebaseAuth() after initialization
+4. **Handle errors** - Check for initialization errors
+5. **Use services** - Use auth services instead of direct Auth SDK
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Initialize Firebase Auth multiple times
+- Use Auth SDK before initialization
+- Use getAuth() from firebase/auth directly
+- Ignore initialization errors
+- Skip initialization status check
+
+## ⚠️ Avoid
+
+- Initializing Auth in components
+- Not checking initialization status
+- Direct Firebase Auth SDK usage
+- Initializing without Firebase app
+- Not handling initialization failures
+
+## Initialization Strategy
+
+### Basic Initialization
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/config`
+
+**Function:** `initializeFirebaseAuth()`
+
+**Returns:** `Promise<void>`
+
+**When to Use:**
+- App startup (after Firebase initialized)
+- Before any auth operations
+- Root component initialization
+
+**Initialization Flow:**
+1. Verify Firebase app initialized
+2. Get Firebase app instance
+3. Initialize Auth with app
+4. Set initialization state
+5. Handle errors appropriately
+
+### Check Initialization Status
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/config`
+
+**Functions:**
+- `isFirebaseAuthInitialized()` - Check if Auth initialized
+- `isFirebaseAuthInitializing()` - Check if initializing
+- `getFirebaseAuthInitializationError()` - Get error if failed
+
+**Returns:**
+- `boolean` for status checks
+- `Error | null` for error check
+
+**When to Use:**
+- Before auth operations
+- Before using auth services
+- Error recovery
+- Status display
+
+**Usage Strategy:**
+1. Check isFirebaseAuthInitialized()
+2. If false, show loading or initialize
+3. If error, show error message
+4. Proceed with auth operations
+
+## Service Access
+
+### Get Auth Instance
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/config`
+
+**Function:** `getFirebaseAuth()`
+
+**Returns:** `Auth` instance from Firebase Auth SDK
+
+**Usage Strategy:**
+1. Check initialization status first
+2. Call getFirebaseAuth()
+3. Use Auth instance for operations
+4. Handle errors appropriately
+
+**When to Use:**
+- Custom auth operations
+- Direct Auth SDK usage (rare)
+- Advanced auth features
+- Auth service implementations
+
+**Important:** Prefer using auth services over direct Auth SDK usage
+
+### Reset Client
+
+**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/config`
+
+**Function:** `resetFirebaseAuthClient()`
+
+**Purpose:** Reset Auth client state (useful for testing)
+
+**When to Use:**
+- Testing scenarios
+- Error recovery
+- Reinitialization
+- Development
+
+**Usage Strategy:**
+1. Call resetFirebaseAuthClient()
+2. Reinitialize if needed
+3. Use only in development/testing
+4. Never use in production
+
+## Common Mistakes to Avoid
+
+1. ❌ Initializing Auth multiple times
+   - ✅ Initialize once at app startup
+
+2. ❌ Not checking initialization status
+   - ✅ Always check isFirebaseAuthInitialized()
+
+3. ❌ Using getAuth() from firebase/auth
+   - ✅ Use getFirebaseAuth() from auth config
+
+4. ❌ Initializing before Firebase app
+   - ✅ Initialize Firebase first, then Auth
+
+5. ❌ Ignoring initialization errors
+   - ✅ Handle and display errors
+
+## AI Agent Instructions
+
+### When Initializing Auth
+
+1. Initialize Firebase first
+2. Call initializeFirebaseAuth()
+3. Await initialization completion
+4. Check for errors
+5. Show error message if failed
+
+### When Using Auth Services
+
+1. Check Auth initialization status
+2. If not initialized, initialize first
+3. Use auth services (not direct SDK)
+4. Handle errors appropriately
+5. Show user feedback
+
+### When Getting Auth Instance
+
+1. Check isFirebaseAuthInitialized()
+2. Call getFirebaseAuth()
+3. Use Auth instance
+4. Handle uninitialized state
+5. Prefer auth services over direct usage
+
+## Code Quality Standards
+
+### Initialization
+
+- Initialize once at startup
+- Check status before use
+- Handle errors gracefully
+- Show loading states
+- Provide error feedback
+
+### Error Handling
+
+- Catch initialization errors
+- Store error in state
+- Provide error context
+- Allow retry/recovery
+- Log for debugging
+
+## Performance Considerations
+
+### Initialization Overhead
+
+- One-time cost at app startup
+- Async initialization (non-blocking)
+- ~50-200ms typical
+- Initialize once, reuse Auth instance
+- Don't reinitialize unnecessarily
+
+### State Checking
+
+- Fast boolean checks
+- No performance overhead
+- Safe to call frequently
+- Use before auth operations
+- Prevents errors
+
+## Related Documentation
+
+- [Auth Module README](../../README.md)
+- [Auth Services README](../services/README.md)
+- [Firebase Infrastructure Config README](../../../infrastructure/config/README.md)
+
+## API Reference
+
+### Main Functions
+
+**Import Path:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/config`
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `initializeFirebaseAuth` | `Promise<void>` | Initialize Firebase Auth |
+| `getFirebaseAuth` | `Auth` | Get Auth instance |
+| `isFirebaseAuthInitialized` | `boolean` | Check if initialized |
+| `isFirebaseAuthInitializing` | `boolean` | Check if initializing |
+| `getFirebaseAuthInitializationError` | `Error \| null` | Get initialization error |
+| `resetFirebaseAuthClient` | `void` | Reset client state (testing) |
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Auth Module Team

package/src/auth/infrastructure/config/initializers/FirebaseAuthInitializer.ts

@@ -8,7 +8,7 @@
 import {
   initializeAuth,
   getAuth,
-  // @ts-ignore: getReactNativePersistence exists in the React Native bundle but missing from type definitions
+  // @ts-expect-error: getReactNativePersistence exists in the React Native bundle but missing from type definitions
   // See: https://github.com/firebase/firebase-js-sdk/issues/9316
   getReactNativePersistence,
 } from 'firebase/auth';