@umituz/react-native-auth 3.4.33 → 3.4.35

package/src/domain/ConfigAndErrors.md

@@ -1,242 +1,193 @@
 # AuthConfig & AuthError
 
-Authentication configuration value objects and domain-specific error classes.
+Configuration value objects and domain error classes.
 
 ---
 
-# AuthConfig
+## AuthConfig
 
-Authentication configuration value object containing password and social auth settings.
+Authentication configuration value object.
 
-## Type Definitions
+### Strategy
 
-```typescript
-import type {
-  AuthConfig,
-  PasswordConfig,
-  SocialAuthConfig,
-  GoogleAuthConfig,
-  AppleAuthConfig,
-  SocialAuthProvider,
-  DEFAULT_AUTH_CONFIG,
-  DEFAULT_PASSWORD_CONFIG,
-  DEFAULT_SOCIAL_CONFIG,
-} from '@umituz/react-native-auth';
-
-interface PasswordConfig {
-  minLength: number;          // Minimum password length
-  requireUppercase: boolean;  // Require uppercase letter
-  requireLowercase: boolean;  // Require lowercase letter
-  requireNumber: boolean;     // Require number
-  requireSpecialChar: boolean; // Require special character
-}
+**Purpose**: Centralized configuration for password requirements and social auth providers.
 
-interface GoogleAuthConfig {
-  enabled?: boolean;          // Is enabled
-  webClientId?: string;       // Web client ID
-  iosClientId?: string;       // iOS client ID
-  androidClientId?: string;   // Android client ID
-}
+**When to Use**:
+- Configuring auth behavior
+- Setting password policies
+- Enabling social providers
+- Environment-specific config
 
-interface AppleAuthConfig {
-  enabled?: boolean;          // Is enabled (iOS only)
-}
+**Location**: `src/domain/valueObjects/AuthConfig.ts`
 
-interface SocialAuthConfig {
-  google?: GoogleAuthConfig;
-  apple?: AppleAuthConfig;
-}
+---
 
-interface AuthConfig {
-  password: PasswordConfig;
-  social?: SocialAuthConfig;
-}
+## Configuration Types
 
-type SocialAuthProvider = 'google' | 'apple';
-```
+### PasswordConfig
 
-## Default Values
+**PURPOSE**: Password validation requirements
 
-```typescript
-import {
-  DEFAULT_PASSWORD_CONFIG,
-  DEFAULT_SOCIAL_CONFIG,
-  DEFAULT_AUTH_CONFIG,
-} from '@umituz/react-native-auth';
-
-// Default password configuration
-DEFAULT_PASSWORD_CONFIG;
-// {
-//   minLength: 6,
-//   requireUppercase: false,
-//   requireLowercase: false,
-//   requireNumber: false,
-//   requireSpecialChar: false,
-// }
-
-// Default social configuration
-DEFAULT_SOCIAL_CONFIG;
-// {
-//   google: { enabled: false },
-//   apple: { enabled: false },
-// }
-
-// Default auth configuration
-DEFAULT_AUTH_CONFIG;
-// {
-//   password: DEFAULT_PASSWORD_CONFIG,
-//   social: DEFAULT_SOCIAL_CONFIG,
-// }
-```
+**PROPERTIES**:
+- `minLength: number` - Minimum password length
+- `requireUppercase: boolean` - Require uppercase letter
+- `requireLowercase: boolean` - Require lowercase letter
+- `requireNumber: boolean` - Require number
+- `requireSpecialChar: boolean` - Require special character
 
-## Usage
+**DEFAULT VALUES**:
+- minLength: 6
+- All requirements: false (lenient)
 
-### Custom Password Config
+**Rules**:
+- MUST set minLength between 4-128
+- SHOULD enable requirements in production
+- MUST validate password against config
+- MUST NOT allow minLength < 4
 
-```typescript
-const strictPasswordConfig: PasswordConfig = {
-  minLength: 8,
-  requireUppercase: true,
-  requireLowercase: true,
-  requireNumber: true,
-  requireSpecialChar: true,
-};
-
-const authConfig: AuthConfig = {
-  password: strictPasswordConfig,
-};
-```
+**MUST NOT**:
+- Set minLength < 4 (too weak)
+- Set minLength > 128 (too long)
+- Enable all requirements without UX consideration
 
-### Social Auth Config
+---
 
-```typescript
-const socialAuthConfig: SocialAuthConfig = {
-  google: {
-    enabled: true,
-    webClientId: 'your-web-client-id.apps.googleusercontent.com',
-    iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
-    androidClientId: 'your-android-client-id.apps.googleusercontent.com',
-  },
-  apple: {
-    enabled: Platform.OS === 'ios',
-  },
-};
-
-const authConfig: AuthConfig = {
-  password: DEFAULT_PASSWORD_CONFIG,
-  social: socialAuthConfig,
-};
-```
+### GoogleAuthConfig
 
-### Complete Configuration
+**PURPOSE**: Google OAuth configuration
 
-```typescript
-const productionAuthConfig: AuthConfig = {
-  password: {
-    minLength: 8,
-    requireUppercase: true,
-    requireLowercase: true,
-    requireNumber: true,
-    requireSpecialChar: true,
-  },
-  social: {
-    google: {
-      enabled: true,
-      webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-      iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
-      androidClientId: Config.GOOGLE_ANDROID_CLIENT_ID,
-    },
-    apple: {
-      enabled: Platform.OS === 'ios',
-    },
-  },
-};
-```
+**PROPERTIES**:
+- `enabled?: boolean` - Enable Google auth
+- `webClientId?: string` - Web client ID
+- `iosClientId?: string` - iOS client ID
+- `androidClientId?: string` - Android client ID
 
-### Environment-Based Config
+**RULES**:
+- MUST provide at least one client ID if enabled
+- MUST use valid OAuth client IDs
+- MUST match Firebase console
+- MUST test before production
+
+**MUST NOT**:
+- Enable without client ID
+- Use production keys in development
+- Share client IDs across environments
+
+---
+
+### AppleAuthConfig
+
+**PURPOSE**: Apple Sign-In configuration
+
+**PROPERTIES**:
+- `enabled?: boolean` - Enable Apple auth
+
+**RULES**:
+- MUST only enable on iOS
+- MUST have Apple Developer account
+- MUST configure in Firebase
+- MUST follow Apple guidelines
+
+**MUST NOT**:
+- Enable on Android
+- Enable on Web
+- Require as only auth method (Apple rule)
+
+---
+
+### SocialAuthConfig
+
+**PURPOSE**: Social auth provider configuration
+
+**PROPERTIES**:
+- `google?: GoogleAuthConfig` - Google settings
+- `apple?: AppleAuthConfig` - Apple settings
+
+**RULES**:
+- MUST check platform availability
+- MUST configure each provider separately
+- MUST handle provider errors
+- MUST respect platform constraints
+
+**PLATFORM CONSTRAINTS**:
+- Google: All platforms
+- Apple: iOS only
+
+---
+
+### AuthConfig
 
+**COMPLETE CONFIGURATION**:
 ```typescript
-import { DEFAULT_AUTH_CONFIG } from '@umituz/react-native-auth';
-
-function getAuthConfig(): AuthConfig {
-  if (__DEV__) {
-    // Development: Weak password requirements
-    return {
-      password: {
-        minLength: 6,
-        requireUppercase: false,
-        requireLowercase: false,
-        requireNumber: false,
-        requireSpecialChar: false,
-      },
-    };
-  }
-
-  // Production: Strict password requirements
-  return {
-    password: {
-      minLength: 12,
-      requireUppercase: true,
-      requireLowercase: true,
-      requireNumber: true,
-      requireSpecialChar: true,
-    },
-    social: {
-      google: {
-        enabled: true,
-        webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-      },
-    },
-  };
+{
+  password: PasswordConfig;
+  social?: SocialAuthConfig;
 }
 ```
 
+**RULES**:
+- MUST provide password config
+- MAY provide social config
+- MUST validate configuration
+- MUST handle missing providers
+
+---
+
+## Configuration Strategy
+
+### Environment-Based Config
+
+**DEVELOPMENT**:
+- Lenient password requirements
+- May disable social auth
+- Faster iterations
+
+**PRODUCTION**:
+- Strict password requirements
+- Social auth enabled
+- Security-focused
+
+**Rules**:
+- MUST use stricter config in production
+- MUST test with production config
+- MUST not use dev config in production
+- MUST validate config on startup
+
+---
+
 ### Config Validation
 
-```typescript
-function validatePasswordConfig(config: PasswordConfig): boolean {
-  if (config.minLength < 4) {
-    console.error('Minimum length must be at least 4');
-    return false;
-  }
-
-  if (config.minLength > 128) {
-    console.error('Minimum length must be at most 128');
-    return false;
-  }
-
-  return true;
-}
+**VALIDATION RULES**:
+- MUST check password config validity
+- MUST verify social provider IDs
+- MUST ensure platform compatibility
+- MUST throw on invalid config
 
-function validateAuthConfig(config: AuthConfig): {
-  valid: boolean;
-  errors: string[];
-} {
-  const errors: string[] = [];
-
-  if (!validatePasswordConfig(config.password)) {
-    errors.push('Invalid password config');
-  }
-
-  if (config.social?.google?.enabled) {
-    if (!config.social.google.webClientId) {
-      errors.push('Google webClientId is required when enabled');
-    }
-  }
-
-  return {
-    valid: errors.length === 0,
-    errors,
-  };
-}
-```
+**ERRORS**:
+- Invalid password config
+- Missing required client IDs
+- Platform incompatibility
 
 ---
 
-# AuthError
+## AuthError
 
 Domain-specific error classes for authentication.
 
+### Strategy
+
+**Purpose**: Type-safe error handling with clear error types and user-friendly messages.
+
+**When to Use**:
+- Authentication failures
+- Validation errors
+- Network issues
+- Configuration problems
+
+**Location**: `src/domain/errors/AuthError.ts`
+
+---
+
 ## Error Hierarchy
 
 ```
@@ -249,297 +200,211 @@ AuthError (base)
 ├── AuthWrongPasswordError
 ├── AuthEmailAlreadyInUseError
 ├── AuthWeakPasswordError
-└── AuthInvalidEmailError
+�── AuthInvalidEmailError
 ```
 
-## Error Classes
+---
+
+## Error Types
 
 ### AuthError (Base)
 
-```typescript
-import { AuthError } from '@umituz/react-native-auth';
+**PURPOSE**: Base authentication error
 
-throw new AuthError('Authentication failed');
-// { name: 'AuthError', message: 'Authentication failed', code: 'AUTH_ERROR' }
-```
+**RULES**:
+- MUST extend for specific errors
+- MUST include error message
+- MUST have error code
+- MUST be catchable
+
+**PROPERTIES**:
+- `message: string` - Error message
+- `code: string` - Error code
+- `name: string` - Error name
 
-### AuthInitializationError
+---
 
-When auth service is not initialized:
+### AuthUserNotFoundError
 
-```typescript
-import { AuthInitializationError } from '@umituz/react-native-auth';
+**PURPOSE**: User not found error
 
-if (!authService) {
-  throw new AuthInitializationError('Auth service not initialized');
-}
-```
+**WHEN THROWN**: Email not found during sign in
 
-### AuthConfigurationError
+**Rules**:
+- MUST indicate user not found
+- MUST not reveal if email exists
+- MUST suggest registration
 
-Invalid configuration:
+**USER MESSAGE**: "No user found with this email"
 
-```typescript
-import { AuthConfigurationError } from '@umituz/react-native-auth';
+---
 
-if (!config.google.webClientId) {
-  throw new AuthConfigurationError('Google webClientId is required');
-}
-```
+### AuthWrongPasswordError
 
-### AuthValidationError
+**PURPOSE**: Incorrect password error
 
-Validation error:
+**WHEN THROWN**: Wrong password during sign in
 
-```typescript
-import { AuthValidationError } from '@umituz/react-native-auth';
+**Rules**:
+- MUST indicate wrong password
+- MUST not reveal password
+- MUST allow retry
 
-if (!email) {
-  throw new AuthValidationError('Email is required', 'email');
-}
+**USER MESSAGE**: "Incorrect password"
 
-if (password.length < 8) {
-  throw new AuthValidationError('Password too short', 'password');
-}
-```
+---
 
-### AuthNetworkError
+### AuthEmailAlreadyInUseError
 
-Network error:
+**PURPOSE**: Email already registered
 
-```typescript
-import { AuthNetworkError } from '@umituz/react-native-auth';
-
-try {
-  await signIn({ email, password });
-} catch (error) {
-  if (error.code === 'auth/network-request-failed') {
-    throw new AuthNetworkError('No internet connection');
-  }
-}
-```
+**WHEN THROWN**: Email exists during sign up
 
-### AuthUserNotFoundError
+**Rules**:
+- MUST indicate email taken
+- MUST suggest sign in
+- MUST offer password reset
 
-User not found:
+**USER MESSAGE**: "Email already registered"
 
-```typescript
-import { AuthUserNotFoundError } from '@umituz/react-native-auth';
-
-try {
-  await signIn({ email, password });
-} catch (error) {
-  if (error.code === 'auth/user-not-found') {
-    throw new AuthUserNotFoundError('No user found with this email');
-  }
-}
-```
+---
 
-### AuthWrongPasswordError
+### AuthWeakPasswordError
 
-Wrong password:
+**PURPOSE**: Password too weak
 
-```typescript
-import { AuthWrongPasswordError } from '@umituz/react-native-auth';
-
-try {
-  await signIn({ email, password });
-} catch (error) {
-  if (error.code === 'auth/wrong-password') {
-    throw new AuthWrongPasswordError('Incorrect password');
-  }
-}
-```
+**WHEN THROWN**: Password doesn't meet requirements
 
-### AuthEmailAlreadyInUseError
+**Rules**:
+- MUST indicate weak password
+- MUST show requirements
+- MUST suggest stronger password
 
-Email already in use:
+**USER MESSAGE**: "Password does not meet requirements"
 
-```typescript
-import { AuthEmailAlreadyInUseError } from '@umituz/react-native-auth';
-
-try {
-  await signUp({ email, password });
-} catch (error) {
-  if (error.code === 'auth/email-already-in-use') {
-    throw new AuthEmailAlreadyInUseError('Email already registered');
-  }
-}
-```
+---
 
-### AuthWeakPasswordError
+### AuthInvalidEmailError
 
-Weak password:
+**PURPOSE**: Invalid email format
 
-```typescript
-import { AuthWeakPasswordError } from '@umituz/react-native-auth';
-
-try {
-  await signUp({ email, password });
-} catch (error) {
-  if (error.code === 'auth/weak-password') {
-    throw new AuthWeakPasswordError('Password is too weak');
-  }
-}
-```
+**WHEN THROWN**: Email validation fails
 
-### AuthInvalidEmailError
+**Rules**:
+- MUST indicate invalid email
+- MUST suggest valid format
+- MUST not accept malformed email
 
-Invalid email:
+**USER MESSAGE**: "Invalid email format"
 
-```typescript
-import { AuthInvalidEmailError } from '@umituz/react-native-auth';
-
-try {
-  await signUp({ email, password });
-} catch (error) {
-  if (error.code === 'auth/invalid-email') {
-    throw new AuthInvalidEmailError('Invalid email format');
-  }
-}
-```
+---
 
-## Firebase Error Mapping
+### AuthNetworkError
 
-```typescript
-import {
-  AuthError,
-  AuthUserNotFoundError,
-  AuthWrongPasswordError,
-  AuthEmailAlreadyInUseError,
-  AuthWeakPasswordError,
-  AuthInvalidEmailError,
-  AuthNetworkError,
-} from '@umituz/react-native-auth';
+**PURPOSE**: Network connection failure
 
-function mapFirebaseError(error: any): AuthError {
-  const code = error.code;
+**WHEN THROWN**: Network request fails
 
-  switch (code) {
-    case 'auth/user-not-found':
-      return new AuthUserNotFoundError('User not found');
+**Rules**:
+- MUST indicate network problem
+- MUST suggest checking connection
+- MUST allow retry
 
-    case 'auth/wrong-password':
-      return new AuthWrongPasswordError('Incorrect password');
+**USER MESSAGE**: "Network error. Please check your connection"
 
-    case 'auth/email-already-in-use':
-      return new AuthEmailAlreadyInUseError('Email already registered');
+---
 
-    case 'auth/weak-password':
-      return new AuthWeakPasswordError('Password is too weak');
+## Error Handling
 
-    case 'auth/invalid-email':
-      return new AuthInvalidEmailError('Invalid email format');
+### Error Mapping
 
-    case 'auth/network-request-failed':
-      return new AuthNetworkError('Network error');
+**FIREBASE TO DOMAIN ERRORS**:
+- `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
 
-    default:
-      return new AuthError(error.message || 'Authentication failed');
-  }
-}
+**RULES**:
+- MUST map Firebase errors to domain errors
+- MUST preserve error context
+- MUST throw domain errors (not Firebase)
+- MUST handle unknown errors
 
-// Usage
-try {
-  await signInWithEmailAndPassword(auth, email, password);
-} catch (error) {
-  const authError = mapFirebaseError(error);
-  throw authError;
-}
-```
+---
 
-## Error Handling Pattern
+### Error Type Guards
 
-```typescript
-async function handleSignIn(email: string, password: string) {
-  try {
-    await signIn({ email, password });
-  } catch (error) {
-    if (error instanceof AuthUserNotFoundError) {
-      Alert.alert('Error', 'No user found with this email');
-    } else if (error instanceof AuthWrongPasswordError) {
-      Alert.alert('Error', 'Incorrect password');
-    } else if (error instanceof AuthNetworkError) {
-      Alert.alert('Error', 'Check your internet connection');
-    } else if (error instanceof AuthError) {
-      Alert.alert('Error', error.message);
-    } else {
-      Alert.alert('Error', 'An unexpected error occurred');
-    }
-  }
-}
-```
+**PURPOSE**: Type-safe error checking
 
-## Error Type Guards
+**FUNCTIONS**:
+- `isAuthError(error)` - Check if AuthError
+- `isValidationError(error)` - Check if validation error
 
-```typescript
-function isAuthError(error: unknown): error is AuthError {
-  return error instanceof AuthError;
-}
+**RULES**:
+- MUST use for type narrowing
+- MUST check before error handling
+- MUST use in catch blocks
 
-function isValidationError(error: unknown): error is AuthValidationError {
-  return error instanceof AuthValidationError;
-}
+---
 
-// Usage
-try {
-  await signUp({ email, password });
-} catch (error) {
-  if (isValidationError(error)) {
-    console.log('Field:', error.field);
-    console.log('Message:', error.message);
-  }
-}
-```
+### User Messages
 
-## Error Localization
+**STRATEGY**: User-friendly error messages
 
-```typescript
-import { getAuthErrorLocalizationKey } from '@umituz/react-native-auth';
+**RULES**:
+- MUST be clear and simple
+- MUST avoid technical jargon
+- MUST suggest resolution
+- MUST not expose system details
 
-function getErrorMessage(error: AuthError): string {
-  const key = getAuthErrorLocalizationKey(error);
-  return t(key); // Translate with i18n
-}
+**MUST NOT**:
+- Expose error codes
+- Show stack traces
+- Reveal sensitive information
+- Use technical language
 
-// Usage
-try {
-  await signIn({ email, password });
-} catch (error) {
-  if (error instanceof AuthError) {
-    const message = getErrorMessage(error);
-    Alert.alert('Error', message);
-  }
-}
-```
+---
 
-## Custom Errors
+## Configuration Defaults
 
-```typescript
-import { AuthError } from '@umituz/react-native-auth';
+### Default Password Config
 
-class AuthTooManyAttemptsError extends AuthError {
-  constructor(message = 'Too many failed attempts') {
-    super(message, 'AUTH_TOO_MANY_ATTEMPTS');
-    this.name = 'AuthTooManyAttemptsError';
-  }
-}
+**MINIMAL SECURITY**:
+- minLength: 6
+- All requirements: false
 
-class AuthAccountLockedError extends AuthError {
-  constructor(message = 'Account is locked') {
-    super(message, 'AUTH_ACCOUNT_LOCKED');
-    this.name = 'AuthAccountLockedError';
-  }
-}
+**USE CASE**: Development/testing only
 
-// Usage
-if (failedAttempts >= 5) {
-  throw new AuthTooManyAttemptsError('Too many failed attempts. Please try again in 5 minutes.');
-}
-```
+---
+
+### Default Social Config
+
+**DISABLED BY DEFAULT**:
+- google: { enabled: false }
+- apple: { enabled: false }
+
+**USE CASE**: Explicit enable required
+
+---
+
+### Default Auth Config
+
+**COMBINATION**:
+- password: DEFAULT_PASSWORD_CONFIG
+- social: DEFAULT_SOCIAL_CONFIG
+
+**USE CASE**: Starting configuration
+
+---
+
+## Related Entities
+
+- **AuthUser** (`./entities/AuthUser.md`) - User entity
+- **UserProfile** (`./entities/UserProfile.md`) - Profile entity
 
-## Related Modules
+## Related Infrastructure
 
-- **[Domain](../README.md)** - Domain layer
-- **[Infrastructure](../../infrastructure/README.md)** - Infrastructure implementation
-- **[Validation Utils](../../infrastructure/utils/AuthValidation.ts)** - Validation utilities
+- **AuthValidation** (`../../infrastructure/utils/AuthValidation.ts`) - Validation utilities
+- **AuthService** (`../../infrastructure/services/AuthService.ts`) - Auth operations