@umituz/react-native-firebase 2.0.0 → 2.0.2

package/src/domains/auth/infrastructure/services/README.md

@@ -1,346 +0,0 @@
-# Auth Services
-
-Firebase Authentication service layer providing authentication operations, utilities, and guards.
-
-## Purpose
-
-Provides service layer for Firebase Authentication including anonymous auth, Google OAuth, Apple Auth, reauthentication, account deletion, auth guards, and auth-related Firestore utilities.
-
-## For AI Agents
-
-### Before Using Auth Services
-
-1. **USE** services (never Firebase Auth SDK directly in UI)
-2. **HANDLE** service results properly
-3. **CHECK** success property before using data
-4. **HANDLE** errors appropriately
-5. **USE** auth guards for protected routes
-
-### Required Practices
-
-1. **Use services** - Import from auth infrastructure/services
-2. **Check results** - Always check success property
-3. **Handle errors** - Display user-friendly messages
-4. **Use guards** - Protect routes with authGuardService
-5. **Clean up** - Delete Firestore data on account deletion
-
-### Forbidden Practices
-
-## ❌ NEVER
-
-- Use Firebase Auth SDK directly in UI components
-- Ignore success property in results
-- Skip error handling
-- Mix service concerns
-- Delete Auth without Firestore cleanup
-
-## ⚠️ Avoid
-
-- Not checking success before using user data
-- Showing technical error messages
-- Not using auth guards for protected routes
-- Forgetting to delete Firestore data
-- Hardcoding auth configuration
-
-## Service Overview
-
-### AnonymousAuthService
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Handle anonymous (guest) user authentication
-
-**Methods:**
-- `signIn()` - Sign in as anonymous user
-
-**Returns:** `Promise<AnonymousAuthResult>`
-- `success: boolean` - Operation succeeded
-- `user?: User` - Authenticated user
-- `error?: Error` - Error if failed
-
-**Usage Strategy:**
-1. Call signIn() for guest access
-2. Check success property
-3. Access user data if successful
-4. Handle errors appropriately
-5. Prompt to upgrade to permanent account
-
-**When to Use:**
-- Quick app tryout without registration
-- Temporary user sessions
-- Testing without credentials
-- Guest access with limited functionality
-
-### GoogleAuthService
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Handle Google OAuth authentication
-
-**Methods:**
-- `signIn(config)` - Sign in with Google
-
-**Parameters:**
-- `config: GoogleAuthConfig`
-  - `clientId: string` - Google OAuth Client ID
-
-**Returns:** `Promise<GoogleAuthResult>`
-- `success: boolean` - Operation succeeded
-- `user?: User` - Authenticated user
-- `idToken?: string` - Google ID token
-- `error?: Error` - Error if failed
-
-**Usage Strategy:**
-1. Configure with Google Client ID
-2. Call signIn() on user action
-3. Check success property
-4. Access user and idToken if successful
-5. Handle errors gracefully
-
-**When to Use:**
-- Primary authentication method
-- Google account sign-in
-- Account linking
-- Reauthentication
-
-### AppleAuthService
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Handle Apple ID authentication (iOS only)
-
-**Methods:**
-- `signIn()` - Sign in with Apple ID
-
-**Returns:** `Promise<AppleAuthResult>`
-- `success: boolean` - Operation succeeded
-- `user?: User` - Authenticated user
-- `authorizationCode?: string` - Apple authorization code
-- `error?: Error` - Error if failed
-
-**Usage Strategy:**
-1. Call signIn() on user action (iOS only)
-2. Automatically skipped on Android
-3. Check success property
-4. Access user data if successful
-5. Handle errors appropriately
-
-**When to Use:**
-- iOS applications
-- Alternative to Google sign-in
-- Privacy-focused authentication
-- Account linking
-
-## Account Operations
-
-### ReauthenticationService
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Handle user reauthentication for sensitive operations
-
-**Methods:**
-- `reauthenticate(user)` - Reauthenticate current user
-
-**When to Use:**
-- Before account deletion
-- Before password change
-- Before sensitive operations
-- Email verification
-
-**Strategy:**
-1. Verify user identity
-2. Call reauthenticate method
-3. Handle reauthentication
-4. Proceed with sensitive operation
-5. Handle errors appropriately
-
-### Account Deletion Service
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Handle complete account deletion including Auth and Firestore data
-
-**Methods:**
-- `deleteCurrentUser()` - Delete current user account
-
-**Cleanup Process:**
-1. Delete Firebase Auth account
-2. Automatically delete Firestore user data
-3. Clean up Storage files (manual if needed)
-4. Sign out user
-5. Navigate to login screen
-
-**When to Use:**
-- User requests account deletion
-- GDPR compliance
-- User data cleanup
-- Account testing
-
-**Strategy:**
-1. Confirm deletion with user
-2. Call deleteCurrentUser()
-3. Auth deletion automatic
-4. Firestore cleanup automatic
-5. Manual Storage cleanup if needed
-
-## Route Protection
-
-### AuthGuardService
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Protect routes that require authentication
-
-**Methods:**
-- `canActivate()` - Check if route can be activated
-- `canActivateAnonymous()` - Check if anonymous users allowed
-
-**Returns:** `boolean` - Whether route can be accessed
-
-**Usage Strategy:**
-1. Use in protected route components
-2. Check canActivate() before rendering
-3. Redirect to login if not authenticated
-4. Handle anonymous users appropriately
-5. Show loading state during check
-
-**When to Use:**
-- Pages requiring authentication
-- User profile pages
-- Dashboard and settings
-- Protected features
-
-## Firestore Utilities
-
-### AuthFirestoreUtils
-
-**Import From:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-**Purpose:** Helper functions for auth-related Firestore operations
-
-**Utilities:**
-- User document path resolution
-- User data creation/update
-- User data cleanup on deletion
-- Auth state synchronization
-
-**When to Use:**
-- Creating user documents in Firestore
-- Updating user profile data
-- Cleaning up user data
-- Syncing auth state with database
-
-## Service Result Types
-
-### AuthResult Pattern
-
-**Import From:** All auth services return similar result types
-
-**Common Properties:**
-- `success: boolean` - Operation succeeded
-- `user?: User` - Authenticated user (when applicable)
-- `error?: Error` - Error if operation failed
-
-**Usage:**
-1. Call service method
-2. Check result.success
-3. Use result.user if success
-4. Handle result.error if failed
-5. Never assume success
-
-## Common Mistakes to Avoid
-
-1. ❌ Not checking success property
-   - ✅ Always check result.success first
-
-2. ❌ Using Firebase Auth SDK directly
-   - ✅ Use auth services
-
-3. ❌ Not handling errors
-   - ✅ Check result.error and display message
-
-4. ❌ Deleting Auth without Firestore cleanup
-   - ✅ Use deleteCurrentUser() for complete cleanup
-
-5. ❌ Not protecting routes
-   - ✅ Use authGuardService
-
-## AI Agent Instructions
-
-### When Using Auth Services
-
-1. Import service from auth infrastructure/services
-2. Call service method with appropriate parameters
-3. Check result.success property
-4. Use result.user data if successful
-5. Handle result.error appropriately
-
-### When Protecting Route
-
-1. Use authGuardService.canActivate()
-2. Check result before showing protected content
-3. Redirect to login if not authenticated
-4. Handle anonymous users appropriately
-5. Show loading state during check
-
-### When Deleting Account
-
-1. Confirm deletion with user
-2. Call deleteCurrentUser() service
-3. Firestore cleanup automatic
-4. Clean up Storage files if needed
-5. Sign out and navigate to login
-
-## Code Quality Standards
-
-### TypeScript
-
-- Type all service methods
-- Use proper result types
-- Handle errors with types
-- Export service instances
-- Document service behavior
-
-### Error Handling
-
-- Always return success property
-- Include error details
-- Provide context in errors
-- Handle edge cases
-- Test error flows
-
-## Related Documentation
-
-- [Auth Module README](../../README.md)
-- [Auth Stores README](../stores/README.md)
-- [Auth Hooks README](../../presentation/hooks/README.md)
-- [Auth Errors README](../../domain/errors/README.md)
-
-## API Reference
-
-### Main Services
-
-**Import Path:** `@umituz/react-native-firebase/auth` or `src/auth/infrastructure/services`
-
-| Service | Purpose | Methods |
-|---------|---------|---------|
-| `anonymousAuthService` | Anonymous authentication | `signIn()` |
-| `googleAuthService` | Google OAuth | `signIn(config)` |
-| `appleAuthService` | Apple ID authentication | `signIn()` |
-| `authGuardService` | Route protection | `canActivate()`, `canActivateAnonymous()` |
-| `reauthenticationService` | User reauthentication | `reauthenticate(user)` |
-| `accountDeletionService` | Account deletion | `deleteCurrentUser()` |
-
-### Result Types
-
-| Type | Properties |
-|------|------------|
-| `AnonymousAuthResult` | success, user?, error? |
-| `GoogleAuthResult` | success, user?, idToken?, error? |
-| `AppleAuthResult` | success, user?, authorizationCode?, error? |
-
----
-
-**Last Updated:** 2025-01-08
-**Maintainer:** Auth Module Team

package/src/domains/firestore/domain/README.md

@@ -1,325 +0,0 @@
-# Firestore Domain
-
-Domain layer for Firestore module containing business logic, entities, value objects, errors, and domain services.
-
-## Purpose
-
-Implements Domain-Driven Design (DDD) principles for Firestore, separating business logic from infrastructure concerns and providing a clean architecture.
-
-## For AI Agents
-
-### Before Using Firestore Domain
-
-1. **UNDERSTAND** DDD architecture (domain → infrastructure → presentation)
-2. **USE** domain entities (not infrastructure)
-3. **NEVER** import Firebase SDK in domain layer
-4. **DEFINE** business logic in domain
-5. **KEEP** domain layer Firebase-free
-
-### Required Practices
-
-1. **Keep domain Firebase-free** - No Firebase imports in domain
-2. **Define entities** - Business entities with behavior
-3. **Create value objects** - Immutable value types
-4. **Define domain errors** - Custom error classes
-5. **Write domain services** - Business logic services
-
-### Forbidden Practices
-
-## ❌ NEVER
-
-- Import Firebase SDK in domain layer
-- Mix infrastructure concerns in domain
-- Create anemic domain models (data without behavior)
-- Skip domain validation
-- Put business logic in infrastructure
-
-## ⚠️ Avoid
-
-- Leaking domain logic to infrastructure
-- Not validating business rules
-- Missing domain entities
-- Complex domain services
-- Unclear domain boundaries
-
-## Domain Layer Structure
-
-### Organization
-
-**Import From:** `src/firestore/domain`
-
-**Structure:**
-- `entities/` - Business entities (QuotaMetrics, RequestLog)
-- `services/` - Domain services (QuotaCalculator)
-- `constants/` - Domain constants (QuotaLimits)
-- `errors/` - Domain errors (FirebaseFirestoreError)
-
-**Principles:**
-- No external dependencies (Firebase-free)
-- Pure business logic
-- Type-safe entities
-- Clear boundaries
-- Testable in isolation
-
-## Entities
-
-### QuotaMetrics
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
-
-**Purpose:** Represents Firestore quota usage metrics
-
-**Properties:**
-- `totalReads: number` - Total read operations
-- `totalWrites: number` - Total write operations
-- `totalDeletes: number` - Total delete operations
-- `reads: QuotaStatus` - Read quota details
-- `writes: QuotaStatus` - Write quota details
-- `deletes: QuotaStatus` - Delete quota details
-
-**QuotaStatus Properties:**
-- `used: number` - Amount used
-- `limit: number` - Total limit
-- `percentage: number` - Usage percentage (0-100)
-
-**Usage:**
-- Track quota usage
-- Display usage to users
-- Check thresholds
-- Calculate remaining quota
-- Monitor trends
-
-**When to Use:**
-- After quota calculations
-- Displaying quota status
-- Checking thresholds
-- Monitoring usage
-- Cost analysis
-
-### RequestLog
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
-
-**Purpose:** Log entry for a Firestore request
-
-**Properties:**
-- `type: RequestType` - Operation type ('read', 'write', 'delete')
-- `collectionName: string` - Collection being accessed
-- `documentCount: number` - Number of documents affected
-- `timestamp: number` - Unix timestamp of request
-- `queryHash?: string` - Hash of query for duplicate detection
-
-**Usage:**
-- Create log entry before operation
-- Populate with operation details
-- Store for analytics and monitoring
-- Use queryHash for deduplication
-
-**When to Use:**
-- Repository operations (read, write, delete)
-- Quota tracking middleware
-- Performance monitoring
-- Analytics and reporting
-
-## Value Objects
-
-### QuotaStatus
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain`
-
-**Purpose:** Represents quota usage status for a single operation type
-
-**Properties:**
-- `used: number` - Amount used
-- `limit: number` - Total limit
-- `percentage: number` - Usage percentage
-
-**Characteristics:**
-- Immutable value object
-- Used in QuotaMetrics
-- Calculated from raw counts
-- Used for threshold checking
-
-**When to Use:**
-- Calculating quota usage
-- Checking thresholds
-- Displaying quota status
-- Monitoring limits
-
-## Domain Services
-
-### QuotaCalculator
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/services`
-
-**Purpose:** Business logic for quota calculations
-
-**Responsibilities:**
-- Calculate quota usage percentages
-- Check quota thresholds
-- Calculate remaining quota
-- Validate quota limits
-
-**Methods:**
-- Calculate usage from operation counts
-- Compare against thresholds
-- Return QuotaMetrics object
-
-**When to Use:**
-- After batch operations
-- Displaying quota status
-- Checking before large operations
-- Monitoring usage trends
-
-## Domain Constants
-
-### QuotaLimits
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/constants`
-
-**Purpose:** Firebase free tier quota limits
-
-**Constants:**
-- Daily read limit (50,000)
-- Daily write limit (20,000)
-- Monthly delete limit (20,000)
-
-**Usage:**
-- Quota calculations
-- Display limits to users
-- Calculate remaining quota
-- Set up monitoring
-
-**When to Use:**
-- Calculating quota usage
-- Displaying quota information
-- Setting up alerts
-- Checking remaining quota
-
-## Domain Errors
-
-### FirebaseFirestoreError
-
-**Import From:** `@umituz/react-native-firebase/firestore` or `src/firestore/domain/errors`
-
-**Purpose:** Base error class for all Firestore errors
-
-**Properties:**
-- `code: string` - Error code
-- `message: string` - Error message
-
-**Hierarchy:**
-- FirebaseFirestoreError (base)
-  - FirebaseFirestoreInitializationError
-  - FirebaseFirestoreQuotaError
-
-**When to Use:**
-- Throwing custom Firestore errors
-- Type-safe error handling
-- Error code for conditional logic
-- Structured error information
-
-## Common Mistakes to Avoid
-
-1. ❌ Importing Firebase in domain layer
-   - ✅ Keep domain Firebase-free
-
-2. ❌ Anemic domain models
-   - ✅ Add behavior to entities
-
-3. ❌ Business logic in infrastructure
-   - ✅ Put business logic in domain
-
-4. ❌ Not validating business rules
-   - ✅ Validate in domain layer
-
-5. ❌ Leaking domain logic
-   - ✅ Keep domain logic contained
-
-## AI Agent Instructions
-
-### When Creating Domain Entity
-
-1. Define entity interface
-2. Add business logic methods
-3. Validate invariants
-4. Keep Firebase-free
-5. Export for infrastructure use
-
-### When Creating Domain Service
-
-1. Identify business logic
-2. Create service class
-3. Implement business rules
-4. Keep pure functions
-5. Test in isolation
-
-### When Creating Domain Error
-
-1. Extend base error class
-2. Add error code
-3. Provide clear message
-4. Include context
-5. Export for use
-
-## Code Quality Standards
-
-### Domain Layer
-
-- No Firebase imports
-- Pure TypeScript
-- Business logic only
-- Type-safe entities
-- Clear interfaces
-
-### Testing
-
-- Test domain in isolation
-- Mock infrastructure
-- Test business rules
-- Validate invariants
-- Unit test coverage
-
-## Related Documentation
-
-- [Firestore Module README](../../README.md)
-- [Firestore Infrastructure README](../../infrastructure/README.md)
-- [Firestore Errors README](../errors/README.md)
-- [Quota Constants README](../constants/README.md)
-
-## Architecture
-
-### Domain Layer Responsibilities
-
-**What Domain Does:**
-- Defines business entities
-- Contains business logic
-- Validates business rules
-- Provides domain services
-- Defines domain errors
-
-**What Domain Doesn't Do:**
-- No Firebase SDK usage
-- No database operations
-- No HTTP requests
-- No external integrations
-- No UI concerns
-
-### DDD Principles
-
-**Strategic Patterns:**
-- Entities (identity-based objects)
-- Value Objects (immutable values)
-- Domain Services (stateless operations)
-- Aggregates (consistency boundaries)
-- Repositories (infrastructure concern)
-
-**Tactical Patterns:**
-- Factory (creation)
-- Strategy (algorithms)
-- Specification (business rules)
-
----
-
-**Last Updated:** 2025-01-08
-**Maintainer:** Firestore Module Team