@umituz/react-native-auth 3.4.32 → 3.4.34

package/README.md

@@ -1,426 +1,425 @@
 # @umituz/react-native-auth
 
-> Authentication service for React Native apps - Secure, type-safe, and production-ready. Provider-agnostic design with dependency injection, configurable validation, and comprehensive error handling.
+Authentication service for React Native applications with secure, type-safe, and production-ready implementation.
 
-[![npm version](https://badge.fury.io/js/%40umituz%2Freact-native-auth.svg)](https://www.npmjs.com/package/@umituz/react-native-auth)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+
+## Strategy
+
+**Purpose**: Provides comprehensive authentication solution for React Native apps with Domain-Driven Design architecture, supporting multiple authentication methods and providers.
+
+**When to Use**:
+- Building React Native apps requiring authentication
+- Need multiple auth methods (email, social, anonymous)
+- Want type-safe auth implementation
+- Prefer DDD architecture
+- Need production-ready auth solution
+
+**Package Location**: `/src`
+
+**Documentation**: See `/src/[layer]/README.md` for detailed documentation
+
+---
 
-## Features
+## Core Features
 
-- 🔐 **Multiple Auth Methods** - Email/Password, Google, Apple, Anonymous
-- 🎯 **Type-Safe** - Written in TypeScript with full type definitions
-- 🏗️ **DDD Architecture** - Domain-Driven Design with clean separation of concerns
-- 🔌 **Provider Agnostic** - Easy to swap auth providers (Firebase, custom backend, etc.)
-- ⚡ **React Hooks** - Simple and intuitive React hooks for auth operations
-- 🎨 **UI Components** - Pre-built authentication screens and components
-- 📱 **React Native Ready** - Optimized for iOS and Android
-- 🔒 **Secure** - Built-in validation and error handling
+### Authentication Methods
+
+**SUPPORTED METHODS**:
+- Email/Password authentication
+- Google OAuth integration
+- Apple Sign-In (iOS)
+- Anonymous user sessions
+- Account upgrade (anonymous → registered)
+
+### Architecture
+
+**DOMAIN-DRIVEN DESIGN LAYERS**:
+- **Domain**: Core business logic and entities
+- **Application**: Use cases and interfaces
+- **Infrastructure**: External integrations
+- **Presentation**: UI components and hooks
+
+---
 
 ## Installation
 
+### Package Installation
+
+**NPM**:
 ```bash
 npm install @umituz/react-native-auth
-# or
+```
+
+**Yarn**:
+```bash
 yarn add @umituz/react-native-auth
 ```
 
-## Peer Dependencies
+### Peer Dependencies
 
-```json
-{
-  "firebase": ">=11.0.0",
-  "react": ">=18.2.0",
-  "react-native": ">=0.74.0",
-  "@tanstack/react-query": ">=5.0.0",
-  "zustand": ">=4.0.0"
-}
-```
+**REQUIRED PACKAGES**:
+- `firebase`: >= 11.0.0
+- `react`: >= 18.2.0
+- `react-native`: >= 0.74.0
+- `@tanstack/react-query`: >= 5.0.0
+- `zustand`: >= 4.0.0
 
-## Quick Start
+**EXTERNAL DEPENDENCIES**:
+- `@umituz/react-native-firebase` - Firebase integration
+- `@umituz/react-native-design-system` - UI components
 
-### 1. Initialize Auth
+---
 
-Wrap your app with `AuthProvider` and initialize auth:
+## Configuration
 
-```typescript
-import React, { useEffect } from 'react';
-import { AuthProvider, initializeAuth } from '@umituz/react-native-auth';
-import { getAuth } from 'firebase/auth';
-import { NavigationContainer } from '@react-navigation/native';
-import { createNativeStackNavigator } from '@react-navigation/native-stack';
-
-// Initialize auth (call once in app root)
-initializeAuth({
-  onAuthStateChanged: (user) => {
-    console.log('Auth state changed:', user);
-  },
-});
-
-function App() {
-  return (
-    <AuthProvider>
-      <NavigationContainer>
-        <Stack.Navigator>
-          <Stack.Screen name="Login" component={LoginScreen} />
-          <Stack.Screen name="Home" component={HomeScreen} />
-        </Stack.Navigator>
-      </NavigationContainer>
-    </AuthProvider>
-  );
-}
-```
+### Firebase Setup
 
-### 2. Use Auth Hook
+**Rules**:
+- MUST create Firebase project
+- MUST enable Authentication
+- MUST enable Firestore (for user documents)
+- MUST configure OAuth providers
 
-```typescript
-import { useAuth } from '@umituz/react-native-auth';
-import { View, Text, Button } from 'react-native';
-
-function LoginScreen() {
-  const { signIn, loading, error } = useAuth();
-
-  const handleLogin = async () => {
-    try {
-      await signIn('user@example.com', 'password123');
-      // Navigate to home
-    } catch (err) {
-      // Error is automatically set in error state
-    }
-  };
-
-  return (
-    <View>
-      <Button onPress={handleLogin} disabled={loading}>
-        {loading ? 'Signing in...' : 'Sign In'}
-      </Button>
-      {error && <Text>{error}</Text>}
-    </View>
-  );
-}
-```
+**MUST NOT**:
+- Skip Firebase console setup
+- Use production keys in development
+- Forget to enable required providers
 
-### 3. Protect Routes
+**Steps**:
+1. Create Firebase project at console.firebase.google.com
+2. Enable Authentication
+3. Enable Google Sign-In
+4. Enable Apple Sign-In (for iOS)
+5. Enable Firestore
+6. Download config files
 
-```typescript
-import { useAuthRequired } from '@umituz/react-native-auth';
-
-function ProtectedComponent() {
-  const { isAllowed, checkAndRequireAuth } = useAuthRequired();
-
-  const handleAction = () => {
-    if (checkAndRequireAuth()) {
-      // User is authenticated, proceed with action
-      console.log('Action performed');
-    }
-    // If not authenticated, auth modal is shown automatically
-  };
-
-  return (
-    <Button onPress={handleAction}>
-      {isAllowed ? 'Perform Action' : 'Sign In to Continue'}
-    </Button>
-  );
-}
-```
+---
 
-## Social Login
+## Layer Overview
 
-### Google Sign-In
+### Domain Layer
 
-```typescript
-import { useGoogleAuth } from '@umituz/react-native-auth';
-
-function GoogleLoginButton() {
-  const { signInWithGoogle, googleLoading } = useGoogleAuth({
-    iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
-    webClientId: 'your-web-client-id.apps.googleusercontent.com',
-  });
-
-  return (
-    <Button onPress={signInWithGoogle} disabled={googleLoading}>
-      Sign in with Google
-    </Button>
-  );
-}
-```
+**Location**: `src/domain/`
 
-### Apple Sign-In
+**Purpose**: Core business logic and entities
 
-```typescript
-import { useAppleAuth } from '@umituz/react-native-auth';
+**CONTAINS**:
+- `AuthUser` entity
+- `UserProfile` entity
+- `AuthConfig` value object
+- `AuthError` hierarchy
 
-function AppleLoginButton() {
-  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
+**Documentation**: `src/domain/README.md`
 
-  if (!appleAvailable) return null;
+---
 
-  return (
-    <Button onPress={signInWithApple} disabled={appleLoading}>
-      Sign in with Apple
-    </Button>
-  );
-}
-```
+### Application Layer
 
-## Pre-built Screens
+**Location**: `src/application/`
 
-Use pre-built authentication screens:
+**Purpose**: Use cases and interfaces
 
-```typescript
-import { LoginScreen, RegisterScreen, AccountScreen } from '@umituz/react-native-auth';
+**CONTAINS**:
+- Authentication ports
+- User profile ports
+- Account management ports
 
-<Stack.Screen
-  name="Login"
-  component={LoginScreen}
-  options={{ headerShown: false }}
-/>
-```
+**Documentation**: `src/application/README.md`
 
-## User Profile
+---
 
-### Display Profile
+### Infrastructure Layer
 
-```typescript
-import { useUserProfile } from '@umituz/react-native-auth';
-
-function ProfileHeader() {
-  const profile = useUserProfile({
-    accountRoute: '/account',
-  });
-
-  if (!profile) return <LoadingSpinner />;
-
-  return (
-    <View>
-      <Avatar source={{ uri: profile.avatarUrl }} />
-      <Text>{profile.displayName}</Text>
-      {profile.isAnonymous && <Badge>Guest</Badge>}
-    </View>
-  );
-}
-```
+**Location**: `src/infrastructure/`
 
-### Update Profile
+**Purpose**: External integrations and implementations
 
-```typescript
-import { useProfileUpdate } from '@umituz/react-native-auth';
-
-function EditProfileScreen() {
-  const { updateProfile, isUpdating } = useProfileUpdate();
-
-  const handleSave = async (data) => {
-    try {
-      await updateProfile({
-        displayName: data.name,
-        photoURL: data.avatarUrl,
-      });
-    } catch (error) {
-      Alert.alert('Error', 'Failed to update profile');
-    }
-  };
-
-  return <ProfileForm onSave={handleSave} loading={isUpdating} />;
-}
-```
+**CONTAINS**:
+- Firebase Auth service
+- Firestore repositories
+- Validation utilities
+- Provider implementations
+
+**Documentation**:
+- `src/infrastructure/README.md`
+- `src/infrastructure/services/README.md`
+
+---
+
+### Presentation Layer
 
-## Account Management
+**Location**: `src/presentation/`
 
-### Delete Account
+**Purpose**: UI components and hooks
 
+**CONTAINS**:
+- React hooks for auth
+- Pre-built components
+- Screen components
+- State management (Zustand)
+
+**Documentation**:
+- `src/presentation/README.md`
+- `src/presentation/hooks/README.md`
+- `src/presentation/components/README.md`
+- `src/presentation/screens/README.md`
+
+---
+
+## Usage Guidelines
+
+### Authentication Hooks
+
+**PRIMARY HOOK**: `useAuth`
+**Location**: `src/presentation/hooks/useAuth.ts`
+
+**When to Use**:
+- Need authentication state
+- Require user information
+- Performing auth operations
+- Checking auth status
+
+**Import Path**:
 ```typescript
-import { useAccountManagement } from '@umituz/react-native-auth';
-
-function AccountSettings() {
-  const { deleteAccount, logout } = useAccountManagement({
-    onReauthRequired: async () => {
-      // Show re-authentication UI
-      const result = await showReauthDialog();
-      return result.success;
-    },
-  });
-
-  return (
-    <View>
-      <Button onPress={logout}>Sign Out</Button>
-      <Button onPress={deleteAccount}>Delete Account</Button>
-    </View>
-  );
-}
+import { useAuth } from '@umituz/react-native-auth';
 ```
 
-## Validation
+**Rules**:
+- MUST initialize AuthProvider before use
+- MUST handle loading state
+- MUST check auth readiness
+- MUST handle errors appropriately
 
-### Password Validation
+---
 
+### Components
+
+**AVAILABLE COMPONENTS**:
+- `LoginForm` - Email/password login
+- `RegisterForm` - User registration
+- `SocialLoginButtons` - Google/Apple buttons
+- `ProfileSection` - Profile display
+- `AccountActions` - Account management
+
+**Import Path**:
 ```typescript
 import {
-  validatePasswordForRegister,
-  validatePasswordConfirmation,
+  LoginForm,
+  RegisterForm,
+  SocialLoginButtons
 } from '@umituz/react-native-auth';
-
-// Validate password
-const result = validatePasswordForRegister('MyPass123!');
-
-if (result.isValid) {
-  console.log('Password is strong');
-} else {
-  console.log('Requirements:', result.requirements);
-  // {
-  //   hasMinLength: true,
-  //   hasUppercase: true,
-  //   hasLowercase: true,
-  //   hasNumber: true,
-  //   hasSpecialChar: true
-  // }
-}
-
-// Validate password confirmation
-const matchResult = validatePasswordConfirmation('pass123', 'pass123');
-// { isValid: true, matches: true }
 ```
 
-### Email Validation
+**Rules**:
+- MUST follow component documentation
+- MUST provide required props
+- MUST handle events appropriately
+- MUST NOT override internal logic
 
-```typescript
-import { validateEmail } from '@umituz/react-native-auth';
+---
 
-const result = validateEmail('user@example.com');
-// { isValid: true }
-```
+## Platform Support
 
-## Configuration
+### Supported Platforms
 
-### Auth Config
+**iOS**: ✅ Full support
+- All authentication methods
+- Apple Sign-In available
+- Google Sign-In available
 
-```typescript
-import { DEFAULT_AUTH_CONFIG } from '@umituz/react-native-auth';
-
-const customConfig: AuthConfig = {
-  password: {
-    minLength: 12,
-    requireUppercase: true,
-    requireLowercase: true,
-    requireNumber: true,
-    requireSpecialChar: true,
-  },
-  social: {
-    google: {
-      enabled: true,
-      webClientId: Config.GOOGLE_WEB_CLIENT_ID,
-      iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
-    },
-    apple: {
-      enabled: Platform.OS === 'ios',
-    },
-  },
-};
-```
+**Android**: ✅ Full support
+- All authentication methods (except Apple)
+- Google Sign-In available
 
-## Architecture
+**Web**: ✅ Full support
+- All authentication methods (except Apple)
+- Google Sign-In available
 
-This package follows **Domain-Driven Design (DDD)** principles with clean architecture:
+---
 
-```
-src/
-├── domain/           # Business logic and entities
-│   ├── entities/     # AuthUser, UserProfile
-│   ├── value-objects/# AuthConfig, PasswordConfig
-│   ├── errors/       # AuthError classes
-│   └── utils/        # Domain utilities
-├── application/      # Interfaces and ports
-│   └── ports/        # IAuthService, IAuthProvider
-├── infrastructure/   # External integrations
-│   ├── providers/    # Firebase implementation
-│   ├── services/     # AuthService, UserDocumentService
-│   └── utils/        # Validation, storage adapters
-└── presentation/     # UI layer
-    ├── hooks/        # React hooks
-    ├── components/   # React components
-    ├── screens/      # Full screens
-    ├── stores/       # State management (Zustand)
-    └── navigation/   # Navigation setup
-```
+## Security Requirements
 
-## API Reference
+### Rules
 
-### Hooks
+**MUST**:
+- Validate all inputs
+- Use HTTPS for all operations
+- Implement proper error handling
+- Follow Firebase security best practices
+- Use secure token storage
+- Validate tokens server-side
 
-| Hook | Description |
-|------|-------------|
-| `useAuth` | Main auth state and operations |
-| `useAuthRequired` | Check auth requirements |
-| `useRequireAuth` | Get userId or throw |
-| `useUserProfile` | Fetch user profile |
-| `useProfileUpdate` | Update profile |
-| `useProfileEdit` | Profile editing form state |
-| `useAccountManagement` | Account operations |
-| `useSocialLogin` | Social login management |
-| `useGoogleAuth` | Google authentication |
-| `useAppleAuth` | Apple authentication |
-| `useAuthBottomSheet` | Auth bottom sheet management |
+**MUST NOT**:
+- Store tokens in AsyncStorage
+- Log passwords or tokens
+- Expose sensitive data in errors
+- Skip validation
+- Use HTTP for auth operations
 
-### Components
+---
+
+## Architecture Principles
+
+### Domain-Driven Design
+
+**PRINCIPLES**:
+- Business logic in domain layer
+- Infrastructure concerns isolated
+- Presentation layer UI-focused
+- Application layer orchestrates
+
+**BENEFITS**:
+- Testable business logic
+- Swappable providers
+- Clear separation of concerns
+- Maintainable codebase
+
+---
+
+## Error Handling
+
+### Strategy
+
+**Purpose**: Comprehensive error handling throughout application.
+
+**Rules**:
+- MUST handle auth errors gracefully
+- MUST show user-friendly messages
+- MUST allow retry after failures
+- MUST log errors for debugging
+- MUST not expose sensitive data
+
+**Error Hierarchy**:
+- `AuthError` - Base error class
+- `ValidationError` - Input validation errors
+- `AuthenticationError` - Auth operation errors
+- `NetworkError` - Network issues
+
+---
+
+## Validation Strategy
+
+### Purpose
+
+**Purpose**: Ensure data integrity and security.
+
+**Rules**:
+- MUST validate email format
+- MUST validate password complexity
+- MUST validate required fields
+- MUST provide clear error messages
+- MUST prevent invalid submissions
+
+**Validation Location**: `src/infrastructure/utils/AuthValidation.ts`
 
-| Component | Description |
-|-----------|-------------|
-| `LoginForm` | Login form |
-| `RegisterForm` | Registration form |
-| `SocialLoginButtons` | Social login buttons |
-| `PasswordStrengthIndicator` | Password strength visualizer |
-| `PasswordMatchIndicator` | Password match indicator |
-| `ProfileSection` | User profile display |
-| `AccountActions` | Account action buttons |
-
-### Services
-
-| Service | Description |
-|---------|-------------|
-| `AuthService` | Main auth service |
-| `initializeAuth` | Auth initialization |
-| `UserDocumentService` | Firestore user documents |
-| `AnonymousModeService` | Anonymous authentication |
-
-## Documentation
-
-- [Domain Layer](./src/domain/README.md) - Business logic and entities
-- [Application Layer](./src/application/README.md) - Interfaces and ports
-- [Infrastructure Layer](./src/infrastructure/README.md) - External integrations
-- [Presentation Layer](./src/presentation/README.md) - UI components and hooks
-- [Hooks Documentation](./src/presentation/hooks/README.md) - All hooks
-- [Components Documentation](./src/presentation/components/README.md) - All components
-- [Screens Documentation](./src/presentation/screens/README.md) - Pre-built screens
-- [Services Documentation](./src/infrastructure/services/README.md) - Core services
-
-## Examples
-
-Check out the [examples](./examples) directory for complete implementations:
-
-- [Basic Auth](./examples/basic-auth) - Simple email/password auth
-- [Social Auth](./examples/social-auth) - Google and Apple sign-in
-- [Protected Routes](./examples/protected-routes) - Route protection
-- [Profile Management](./examples/profile-management) - User profile operations
+---
+
+## Migration Guide
+
+### From Previous Versions
+
+**Breaking Changes**:
+- See changelog for details
+- Follow migration steps
+- Update component props
+- Update hook usage
+
+**Rules**:
+- MUST read migration guide
+- MUST test thoroughly after upgrade
+- MUST update dependencies
+- MUST check deprecated features
+
+---
+
+## Performance Considerations
+
+### Optimization
+
+**Rules**:
+- MUST memoize expensive computations
+- MUST minimize re-renders
+- MUST optimize state updates
+- MUST use efficient selectors
+
+**Constraints**:
+- Auth state single source of truth
+- Minimal network requests
+- Efficient validation checks
+- Optimized component rendering
+
+---
+
+## Testing Strategy
+
+### Unit Testing
+
+**WHAT TO TEST**:
+- Domain logic and entities
+- Validation utilities
+- Hook behavior
+- Component rendering
+
+**RULES**:
+- MUST test auth operations
+- MUST test validation
+- MUST test error handling
+- MUST mock Firebase dependencies
+
+---
 
 ## Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details.
+### Development Setup
+
+**RULES**:
+- MUST follow DDD principles
+- MUST maintain type safety
+- MUST update documentation
+- MUST add tests for new features
+- MUST follow existing patterns
+
+**MUST NOT**:
+- Break DDD layer boundaries
+- Skip documentation
+- Add code without tests
+- Introduce breaking changes without major version bump
+
+---
 
 ## License
 
-MIT © [Ümit UZ](https://github.com/umituz)
+MIT License - See LICENSE file for details
+
+---
+
+## Support and Documentation
 
-## Support
+### Documentation Structure
 
-- 📧 Email: umit@umituz.com
-- 🐦 Twitter: [@umituz](https://twitter.com/umituz)
-- 💻 GitHub: [umituz/react-native-auth](https://github.com/umituz/react-native-auth)
+**MAIN README**: This file
 
-## Related Packages
+**LAYER DOCUMENTATION**:
+- `src/domain/README.md` - Domain layer details
+- `src/application/README.md` - Application layer details
+- `src/infrastructure/README.md` - Infrastructure details
+- `src/presentation/README.md` - Presentation layer details
 
-- [@umituz/react-native-firebase](https://github.com/umituz/react-native-firebase) - Firebase integration
-- [@umituz/react-native-localization](https://github.com/umituz/react-native-localization) - Localization
-- [@umituz/react-native-storage](https://github.com/umituz/react-native-storage) - Storage abstraction
-- [@umituz/react-native-tanstack](https://github.com/umituz/react-native-tanstack) - TanStack Query integration
+**COMPONENT/HOOK DOCUMENTATION**:
+- Each component has dedicated .md file
+- Each hook has dedicated .md file
+- Follows Strategy/Rules/Constraints format
+
+### Getting Help
+
+- Read documentation first
+- Check existing issues
+- Review examples in docs
+- Follow AI agent guidelines
 
 ---
 
-Made with ❤️ by [Ümit UZ](https://umituz.com)
+## Changelog
+
+See CHANGELOG.md for version history and changes.