@umituz/react-native-firebase 1.13.57 → 1.13.59

package/src/storage/deleter/README.md

@@ -0,0 +1,370 @@
+# Storage Deleter
+
+Firebase Storage deletion functionality supporting single file and batch deletion operations.
+
+## Purpose
+
+Provides file deletion capabilities for Firebase Storage with single file deletion, batch deletion operations, URL/path parsing, and comprehensive error handling/reporting.
+
+## For AI Agents
+
+### Before Using Storage Deleter
+
+1. **ALWAYS** use deleter functions (never Firebase Storage SDK directly)
+2. **TRACK** file paths in database for cleanup
+3. **USE** batch deletion for multiple files
+4. **HANDLE** deletion errors appropriately
+5. **VERIFY** file paths before deletion
+
+### Required Practices
+
+1. **Use deleter functions** - Import from storage module
+2. **Track file paths** - Store paths in Firestore database
+3. **Use batch deletion** - Delete multiple files efficiently
+4. **Handle partial failures** - Some files may fail to delete
+5. **Check deletion results** - Verify success/failure
+6. **Clean up old files** - Remove unused files regularly
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Use Firebase Storage SDK directly in application code
+- Delete files without tracking paths
+- Ignore deletion failures
+- Delete files based on URL patterns (unreliable)
+- Assume deletion always succeeds
+- Delete without user confirmation (for user-initiated actions)
+
+## ⚠️ Avoid
+
+- Sequential single deletes (use batch instead)
+- Not tracking deleted files
+- Deleting without verification
+- Not cleaning up temporary files
+- Ignoring partial batch failures
+
+## Usage Strategies
+
+### For Single File Deletion
+
+**Strategy:** Use deleteStorageFile for individual file deletion.
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/deleter`
+
+**When to Use:**
+- Deleting single file (avatar, document)
+- Replacing old file with new
+- User-initiated deletion
+- Temporary file cleanup
+
+**Function:** `deleteStorageFile(downloadUrlOrPath)`
+
+**Parameters:**
+- `downloadUrlOrPath: string` - Download URL or storage path
+
+**Returns:** `Promise<DeleteResult>`
+- `success: boolean` - Deletion succeeded
+- `storagePath: string` - Storage path
+
+**Strategy:**
+1. Use stored file path (from database)
+2. Call deleteStorageFile
+3. Check result.success
+4. Handle failures appropriately
+5. Update database to remove path reference
+
+### For Batch Deletion
+
+**Strategy:** Use deleteStorageFiles for multiple file deletion.
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/deleter`
+
+**When to Use:**
+- Deleting all user files
+- Cleaning up multiple documents
+- Gallery deletion
+- Bulk file cleanup
+
+**Function:** `deleteStorageFiles(urlsOrPaths)`
+
+**Parameters:**
+- `urlsOrPaths: string[]` - Array of download URLs or storage paths
+
+**Returns:** `Promise<BatchDeleteResult>`
+- `successful: string[]` - Array of deleted storage paths
+- `failed: Array<{path, error}>` - Failed deletions with errors
+
+**Strategy:**
+1. Collect file paths from database
+2. Call deleteStorageFiles with paths array
+3. Check result.successful and result.failed
+4. Log or retry failed deletions
+5. Update database to remove deleted paths
+
+### For User Account Deletion
+
+**Strategy:** Delete all user files when account is deleted.
+
+**Import From:** `@umituz/react-native-firebase/storage` and firestore
+
+**When to Use:**
+- User deletes account
+- GDPR compliance
+- User data cleanup
+- Admin-initiated deletion
+
+**Implementation Strategy:**
+1. Fetch all user file paths from Firestore
+2. Call deleteStorageFiles with paths
+3. Check for partial failures
+4. Log failed deletions for manual cleanup
+5. Delete Firestore user document
+6. Delete Auth account
+
+### For Old Avatar Replacement
+
+**Strategy:** Delete old avatar when uploading new one.
+
+**Import From:** `@umituz/react-native-firebase/storage` and firestore
+
+**When to Use:**
+- User updates profile picture
+- Avatar replacement
+- Image updates
+
+**Implementation Strategy:**
+1. Upload new avatar
+2. Get new download URL
+3. Delete old avatar if path exists
+4. Update user document with new path
+5. Handle deletion failure gracefully (old file not critical)
+
+### For Temporary File Cleanup
+
+**Strategy:** Delete temporary files after use.
+
+**Import From:** `@umituz/react-native-firebase/storage` and firestore
+
+**When to Use:**
+- Clean up temp files after processing
+- Remove upload drafts
+- Delete expired files
+
+**Implementation Strategy:**
+1. Track temporary files in database
+2. Schedule cleanup after time period
+3. Use batch deletion
+4. Log failures for manual review
+5. Update database to remove references
+
+### For File Path Tracking
+
+**Strategy:** Store file paths in Firestore for later deletion.
+
+**Import From:** Firestore repository
+
+**When to Use:**
+- Need to delete files later
+- User account management
+- File ownership tracking
+
+**Tracking Strategy:**
+1. Store storagePath in document when uploading
+2. Add to array field for multiple files
+3. Use arrayUnion for adding paths
+4. Use arrayRemove for removing paths
+5. Query all paths when deleting
+
+**Example Fields:**
+- `avatarPath: string` - Single avatar path
+- `photoPaths: string[]` - Multiple photo paths
+- `temporaryPaths: string[]` - Temporary file paths
+- `documentPaths: string[]` - Document file paths
+
+### For Conditional Deletion
+
+**Strategy:** Delete file only if not referenced elsewhere.
+
+**Import From:** `@umituz/react-native-firebase/storage` and firestore
+
+**When to Use:**
+- File may be referenced by multiple documents
+- Need to verify file not in use
+- Prevent accidental deletion
+
+**Implementation Strategy:**
+1. Check if file path referenced in database
+2. Only delete if not referenced
+3. Use transactions for verification
+4. Handle race conditions
+5. Log skipped deletions
+
+## Error Handling
+
+### Batch Deletion Failures
+
+**Strategy:** Handle partial failures in batch operations.
+
+**Import From:** Handle BatchDeleteResult from deleteStorageFiles
+
+**Failure Types:**
+- File not found (non-critical)
+- Network errors (retry recommended)
+- Unauthorized access (critical)
+- Storage quota exceeded (rare for deletion)
+
+**Handling Strategy:**
+1. Check result.failed array
+2. Log failed deletions with errors
+3. Retry network failures
+4. Alert on unauthorized errors
+5. Continue on file-not-found errors
+
+### Retry Strategy
+
+**Strategy:** Retry failed deletions with exponential backoff.
+
+**Implementation:**
+1. First attempt: deleteStorageFiles
+2. Collect failed paths from result
+3. Wait with exponential backoff (1s, 2s, 4s)
+4. Retry only failed paths
+5. Limit retries to 3 attempts
+6. Log permanently failed paths
+
+## Common Mistakes to Avoid
+
+1. ❌ Not tracking file paths
+   - ✅ Store paths in Firestore database
+
+2. ❌ Ignoring deletion failures
+   - ✅ Check result.success and handle failures
+
+3. ❌ Deleting without user confirmation
+   - ✅ Confirm before destructive operations
+
+4. ❌ Using sequential single deletes
+   - ✅ Use batch deletion for multiple files
+
+5. ❌ Not cleaning up temporary files
+   - ✅ Schedule regular cleanup tasks
+
+6. ❌ Assuming deletion always succeeds
+   - ✅ Verify and handle partial failures
+
+## AI Agent Instructions
+
+### When Deleting Single File
+
+1. Retrieve file path from database
+2. Call deleteStorageFile with path
+3. Check result.success
+4. Update database to remove path
+5. Handle errors appropriately
+
+### When Deleting Multiple Files
+
+1. Collect all file paths from database
+2. Call deleteStorageFiles with paths array
+3. Check result.failed for partial failures
+4. Retry failed deletions if appropriate
+5. Update database to remove deleted paths
+6. Log permanently failed deletions
+
+### When Replacing File
+
+1. Upload new file first
+2. Get new download URL and path
+3. Delete old file if path exists
+4. Handle deletion failure gracefully
+5. Update database with new path
+
+### When Cleaning User Files
+
+1. Query all user file paths from database
+2. Use batch deletion
+3. Check for partial failures
+4. Log failures for manual cleanup
+5. Delete user document
+6. Delete Auth account
+
+## Code Quality Standards
+
+### TypeScript
+
+- Use DeleteResult type for single deletion
+- Use BatchDeleteResult for batch deletion
+- Type all file path parameters
+- Handle errors properly
+
+### Error Handling
+
+- Always check result.success
+- Handle result.failed in batch operations
+- Log technical errors for debugging
+- Return user-friendly error messages
+- Retry when appropriate
+
+### File Path Management
+
+- Store paths in Firestore database
+- Use descriptive field names (avatarPath, photoPaths)
+- Update paths on file operations
+- Clean up path references on deletion
+
+## Performance Considerations
+
+### Batch vs Sequential
+
+**Batch Deletion:**
+- Deletes files in parallel
+- Faster for multiple files
+- Single API call
+- Recommended for > 1 file
+
+**Sequential Deletion:**
+- Only use for single file
+- Slower for multiple files
+- Multiple API calls
+- Not recommended
+
+### Path Tracking Overhead
+
+- Minimal overhead to store paths
+- Faster deletion with known paths
+- No need to list Storage files
+- Better than URL parsing
+
+## Related Documentation
+
+- [Storage Module README](../README.md)
+- [Storage Uploader README](../uploader/README.md)
+- [Storage Types README](../types/README.md)
+- [Auth README](../../auth/README.md)
+
+## API Reference
+
+### Main Functions
+
+**Import Path:** `@umituz/react-native-firebase/storage` or `src/storage/deleter`
+
+| Function | Parameters | Returns | Description |
+|----------|-----------|---------|-------------|
+| `deleteStorageFile` | downloadUrlOrPath | `Promise<DeleteResult>` | Delete single file |
+| `deleteStorageFiles` | urlsOrPaths[] | `Promise<BatchDeleteResult>` | Delete multiple files |
+
+### Type Definitions
+
+**DeleteResult:**
+- `success: boolean` - Deletion succeeded
+- `storagePath: string` - Storage path
+
+**BatchDeleteResult:**
+- `successful: string[]` - Array of deleted storage paths
+- `failed: Array<{path, error}>` - Failed deletions with error messages
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Storage Module Team

package/src/storage/types/README.md

@@ -0,0 +1,313 @@
+# Storage Types
+
+TypeScript types and interfaces for Firebase Storage operations.
+
+## Purpose
+
+Provides TypeScript type definitions for Storage operations including upload results, upload options, delete results, and batch deletion results.
+
+## For AI Agents
+
+### Before Using Storage Types
+
+1. **IMPORT** types from storage module for type safety
+2. **USE** types for all Storage operation return values
+3. **DEFINE** function parameters and return types
+4. **NEVER** use `any` type for Storage operations
+5. **CHECK** types with type guards when needed
+
+### Required Practices
+
+1. **Import types** from `@umituz/react-native-firebase/storage` or `src/storage/types`
+2. **Type all functions** that interact with Storage
+3. **Use type guards** for runtime type checking
+4. **Define custom types** based on base types when needed
+5. **Handle type unions** properly with discriminated unions
+
+### Forbidden Practices
+
+## ❌ NEVER
+
+- Use `any` type for Storage operations
+- Ignore TypeScript type errors
+- Skip typing function parameters
+- Assume types without checking
+- Mix incompatible types
+
+## ⚠️ Avoid
+
+- Overly complex type transformations
+- Unnecessary type assertions
+- Not using provided types
+- Creating duplicate type definitions
+
+## Type Definitions
+
+### UploadResult
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/types`
+
+**Purpose:** Result type for successful file uploads
+
+**Properties:**
+- `downloadUrl: string` - Public download URL
+- `storagePath: string` - Internal storage path
+
+**Usage:**
+- Return type for uploadBase64Image()
+- Return type for uploadFile()
+- Type-safe access to upload results
+
+**When to Use:**
+- Typing upload function returns
+- Processing upload results
+- Storing upload metadata
+
+### UploadOptions
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/types`
+
+**Purpose:** Options for file uploads
+
+**Properties:**
+- `mimeType?: string` - Content type (auto-detected for base64)
+- `customMetadata?: Record<string, string>` - Custom metadata
+
+**Usage:**
+- Pass to uploadBase64Image() as third parameter
+- Pass to uploadFile() as third parameter
+- Add tracking metadata to uploads
+
+**When to Use:**
+- Specifying MIME type explicitly
+- Adding custom metadata to uploads
+- Tracking upload information
+
+**Common Metadata Fields:**
+- `uploadedBy` - User ID
+- `originalFileName` - Original file name
+- `type` - File type/category
+- `uploadedAt` - ISO timestamp
+- `width` / `height` - Image dimensions
+
+### DeleteResult
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/types`
+
+**Purpose:** Result type for file deletion operations
+
+**Properties:**
+- `success: boolean` - Deletion succeeded
+- `storagePath: string` - Storage path
+
+**Usage:**
+- Return type for deleteStorageFile()
+- Check success status
+- Access deleted file path
+
+**When to Use:**
+- Typing delete function returns
+- Verifying deletion success
+- Error handling
+
+### BatchDeleteResult
+
+**Import From:** `@umituz/react-native-firebase/storage` or `src/storage/types`
+
+**Purpose:** Result type for batch file deletion operations
+
+**Properties:**
+- `successful: string[]` - Array of deleted storage paths
+- `failed: Array<{path, error}>` - Array of failed deletions
+
+**Usage:**
+- Return type for deleteStorageFiles()
+- Check partial failures
+- Handle batch operations
+
+**When to Use:**
+- Typing batch delete returns
+- Processing batch results
+- Handling partial failures
+
+## Type Guards
+
+### isUploadResult
+
+**Import From:** Create in your codebase or import from utils
+
+**Purpose:** Check if value is UploadResult
+
+**Returns:** `boolean`
+
+**Usage Strategy:**
+1. Check if value is object
+2. Check for downloadUrl property
+3. Check for storagePath property
+4. Verify types are strings
+5. Return boolean
+
+### isSuccessfulDelete
+
+**Import From:** Create in your codebase or import from utils
+
+**Purpose:** Check if DeleteResult is successful
+
+**Returns:** `boolean`
+
+**Usage Strategy:**
+1. Check result.success property
+2. Return boolean
+3. Use for conditional logic
+
+### hasFailures
+
+**Import From:** Create in your codebase or import from utils
+
+**Purpose:** Check if BatchDeleteResult has failures
+
+**Returns:** `boolean`
+
+**Usage Strategy:**
+1. Check result.failed.length > 0
+2. Return boolean
+3. Use for error handling
+
+## Type Utilities
+
+### Utility Types
+
+**Import From:** Use with base types from storage
+
+**Purpose:** Create derived types from base types
+
+**Common Utilities:**
+- `UploadResults` - Array of UploadResult
+- `DeleteResults` - Array of DeleteResult
+- `UploadResultMap` - Record<string, UploadResult>
+- `DeleteResultMap` - Record<string, DeleteResult>
+- `UploadPromise` - Promise<UploadResult>
+- `DeletePromise` - Promise<DeleteResult>
+- `BatchDeletePromise` - Promise<BatchDeleteResult>
+
+**Usage:**
+- Type arrays of results
+- Type promises of results
+- Type mapped result objects
+- Create generic type-safe functions
+
+### Extract Types
+
+**Import From:** Use TypeScript utility types
+
+**Purpose:** Extract specific property types
+
+**Examples:**
+- `type DownloadURL = UploadResult['downloadUrl']`
+- `type StoragePath = UploadResult['storagePath']`
+
+**Usage:**
+- Type specific properties
+- Create utility functions
+- Enforce type consistency
+
+## Common Mistakes to Avoid
+
+1. ❌ Not typing upload results
+   - ✅ Always use UploadResult type
+
+2. ❌ Not checking delete success
+   - ✅ Check result.success property
+
+3. ❌ Ignoring batch delete failures
+   - ✅ Check result.failed array
+
+4. ❌ Using any type
+   - ✅ Use specific types
+
+5. ❌ Not using provided types
+   - ✅ Import types from storage module
+
+## AI Agent Instructions
+
+### When Typing Upload Functions
+
+1. Import UploadResult and UploadOptions
+2. Type return value as Promise<UploadResult>
+3. Type options parameter as UploadOptions
+4. Use type guards for validation
+5. Handle errors appropriately
+
+### When Typing Delete Functions
+
+1. Import DeleteResult or BatchDeleteResult
+2. Type return value appropriately
+3. Check result.success for single delete
+4. Check result.failed for batch delete
+5. Handle partial failures
+
+### When Creating Custom Types
+
+1. Import base types from storage
+2. Extend or use utility types
+3. Add specific properties
+4. Maintain type compatibility
+5. Export custom types
+
+## Code Quality Standards
+
+### TypeScript
+
+- Always use provided types
+- Never use `any` type
+- Use type guards for runtime checks
+- Prefer explicit types over inferred
+- Export custom types
+
+### Type Safety
+
+- Enable strict mode
+- Use noImplicitAny
+- Enable strictNullChecks
+- Use proper discriminated unions
+- Avoid type assertions
+
+## Performance Considerations
+
+### Type Checking Overhead
+
+- Zero runtime overhead
+- Compile-time type checking only
+- No performance impact
+- Use type guards sparingly
+
+### Type Inference
+
+- Let TypeScript infer when possible
+- Use explicit types for public APIs
+- Type guards for runtime validation
+- Keep type definitions simple
+
+## Related Documentation
+
+- [Storage Module README](../README.md)
+- [Storage Uploader README](../uploader/README.md)
+- [Storage Deleter README](../deleter/README.md)
+
+## API Reference
+
+### Main Types
+
+**Import Path:** `@umituz/react-native-firebase/storage` or `src/storage/types`
+
+| Type | Purpose | Properties |
+|------|---------|------------|
+| `UploadResult` | Upload operation result | downloadUrl, storagePath |
+| `UploadOptions` | Upload configuration | mimeType?, customMetadata? |
+| `DeleteResult` | Delete operation result | success, storagePath |
+| `BatchDeleteResult` | Batch delete result | successful[], failed[] |
+
+---
+
+**Last Updated:** 2025-01-08
+**Maintainer:** Storage Module Team