@umituz/react-native-ai-gemini-provider 1.14.28 → 1.14.30

package/src/infrastructure/utils/ERROR_MAPPER.md

@@ -0,0 +1,170 @@
+# Error Mapper Utility
+
+Maps Gemini API errors to standardized error types with retry information. Provides consistent error categorization.
+
+## 📍 Import Path
+
+```
+import {
+  mapGeminiError,
+  isGeminiErrorRetryable,
+  categorizeGeminiError
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use error mapper to categorize and handle Gemini API errors consistently. Provides retry information and error types.
+
+**When to use:**
+- Categorize API errors
+- Determine retry eligibility
+- Handle error responses
+- Implement retry logic
+- Provide user feedback
+
+## 📌 Strategy
+
+Consistent error handling improves reliability. This utility:
+- Maps errors to standard types
+- Provides retry information
+- Categorizes errors appropriately
+- Includes status codes
+- Simplifies error handling
+
+**Key Decision**: Always map errors before handling. Provides consistent error information across the application.
+
+## ⚠️ Rules
+
+### Error Mapping Rules
+- **MUST** map all API errors
+- **SHOULD** check retry status
+- **MUST** handle unknown errors
+- **SHOULD** preserve error context
+- **MUST NOT** expose sensitive data
+
+### Retry Rules
+- **SHOULD** retry retryable errors
+- **MUST** implement backoff
+- **SHOULD** set retry limits
+- **MUST NOT** retry non-retryable errors
+- **SHOULD** track retry attempts
+
+### Categorization Rules
+- **MUST** use correct error type
+- **SHOULD** check error category
+- **MUST** handle all categories
+- **SHOULD** provide context
+- **MUST NOT** miscategorize errors
+
+### Error Handling Rules
+- **MUST** catch and map errors
+- **SHOULD** log error details
+- **MUST** inform user appropriately
+- **SHOULD** provide recovery options
+- **MUST NOT** suppress errors
+
+## 🤖 AI Agent Guidelines
+
+### When Mapping Errors
+1. **CATCH** API error
+2. **CALL** mapGeminiError()
+3. **GET** error information
+4. **CHECK** retry status
+5. **HANDLE** appropriately
+
+### When Checking Retry Eligibility
+1. **CALL** isGeminiErrorRetryable()
+2. **CHECK** return value
+3. **RETRY** if true
+4. **FAIL** if false
+5. **IMPLEMENT** backoff
+
+### When Categorizing Errors
+1. **CALL** categorizeGeminiError()
+2. **GET** error type
+3. **SWITCH** on category
+4. **HANDLE** each case
+5. **PROVIDE** user feedback
+
+### Code Style Rules
+- **MAP** all errors consistently
+- **CHECK** retry before retrying
+- **HANDLE** all error types
+- **PROVIDE** clear messages
+- **LOG** error information
+
+## 📦 Available Functions
+
+**Refer to**: [`error-mapper.util.ts`](./error-mapper.util.ts)
+
+### Error Mapping
+- `mapGeminiError(error)` - Map error to GeminiErrorInfo
+- `isGeminiErrorRetryable(error)` - Check if error is retryable
+- `categorizeGeminiError(error)` - Categorize error type
+
+## 🔗 Related Modules
+
+- **Error Utilities**: [`./ERROR_UTILITIES.md`](./ERROR_UTILITIES.md)
+- **Retry Service**: [`../services/RETRY_SERVICE.md`](../services/RETRY_SERVICE.md)
+- **Domain Types**: [`../../domain/README.md`](../../domain/README.md)
+
+## 📋 Error Categories
+
+### Retryable Errors
+- `QUOTA_EXCEEDED` - API quota exceeded
+- `RATE_LIMIT` - Rate limit hit
+- `NETWORK` - Network error
+- `TIMEOUT` - Request timeout
+- `SERVER` - Server error (5xx)
+
+### Non-Retryable Errors
+- `AUTHENTICATION` - Invalid credentials
+- `SAFETY` - Safety filter triggered
+- `MODEL_NOT_FOUND` - Invalid model
+- `VALIDATION` - Invalid request
+- `UNKNOWN` - Unknown error
+
+## 🎓 Usage Patterns
+
+### Error Handling
+1. Catch API error
+2. Map to GeminiError
+3. Check retryable status
+4. Retry or fail appropriately
+5. Provide user feedback
+
+### Retry Logic
+1. Check isGeminiErrorRetryable()
+2. If true, implement retry
+3. Use exponential backoff
+4. Set retry limit
+5. Fail after max retries
+
+### Error Categorization
+1. Call categorizeGeminiError()
+2. Get error type
+3. Switch on type
+4. Handle each case
+5. Provide specific feedback
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Skip error mapping
+- Retry without checking
+- Ignore error types
+- Suppress errors
+- Expose sensitive data
+
+### Do
+- Always map errors
+- Check retry status
+- Handle all categories
+- Provide clear feedback
+- Log error details
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/utils/ERROR_UTILITIES.md

@@ -0,0 +1,208 @@
+# Error Utilities
+
+Utilities for managing and standardizing Gemini API errors. Provides error categorization, retry detection, and user-friendly messaging.
+
+## 📍 Import Path
+
+```
+import {
+  mapGeminiError,
+  isGeminiErrorRetryable,
+  categorizeGeminiError,
+  createGeminiError
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use these utilities to handle Gemini API errors consistently. Provides error categorization, retry logic, and user-friendly messaging.
+
+**When to use:**
+- Categorize API errors by type
+- Determine if errors are retryable
+- Create user-friendly error messages
+- Implement retry logic
+- Log errors for monitoring
+
+## 📌 Strategy
+
+Consistent error handling improves UX and debugging. These utilities:
+- Categorize errors into standard types
+- Identify retryable vs non-retryable errors
+- Provide structured error information
+- Enable intelligent retry logic
+- Support error analytics and monitoring
+
+**Key Decision**: Use error categorization to determine retry logic. Only retry transient errors (network, rate limit, server errors), not permanent errors (auth, validation, safety).
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** categorize errors before handling
+- **SHOULD** check retryable status before retrying
+- **MUST** provide user-friendly messages
+- **SHOULD** log errors for debugging
+- **MUST NOT** expose API keys in errors
+
+### Error Handling Rules
+- **MUST** use `isGeminiErrorRetryable()` before retrying
+- **SHOULD** use `categorizeGeminiError()` for error handling
+- **MUST** handle permanent errors appropriately (no retry)
+- **SHOULD** implement user-friendly error messages
+- **MUST** log errors with full context
+
+### Retry Rules
+- **WILL RETRY**: QUOTA_EXCEEDED, RATE_LIMIT, NETWORK, TIMEOUT, SERVER (5xx)
+- **WILL NOT RETRY**: AUTHENTICATION, SAFETY, VALIDATION, MODEL_NOT_FOUND
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying These Utilities
+1. **READ** the implementation file first
+2. **UNDERSTAND** error patterns
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new error patterns
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar error handling exists
+2. **FOLLOW** existing patterns
+3. **ADD** new error patterns to mapper
+4. **DOCUMENT** in type definitions
+5. **ADD** examples to tests (not docs)
+
+### When Fixing Bugs
+1. **REPRODUCE** bug locally first
+2. **IDENTIFY** root cause
+3. **FIX** with minimal changes
+4. **ADD** regression test
+5. **VERIFY** all tests pass
+
+### Code Style Rules
+- **VALIDATE** error inputs
+- **THROW** typed errors (`GeminiError`)
+- **LOG** error categorization
+- **COMMENT** complex pattern matching
+- **USE** consistent error types
+
+## 📦 Available Functions
+
+### `mapGeminiError(error)`
+
+Convert Gemini API errors to standard format.
+
+**Refer to**: [`error-mapper.util.ts`](./error-mapper.util.ts)
+
+### `isGeminiErrorRetryable(error)`
+
+Check if error is retryable.
+
+**Refer to**: [`error-mapper.util.ts`](./error-mapper.util.ts)
+
+### `categorizeGeminiError(error)`
+
+Determine error category.
+
+**Refer to**: [`error-mapper.util.ts`](./error-mapper.util.ts)
+
+### `createGeminiError(error)`
+
+Create `GeminiError` instance.
+
+**Refer to**: [`error-mapper.util.ts`](./error-mapper.util.ts)
+
+## 🔗 Related Modules
+
+- **Error Types**: [`domain/entities/error.types.ts`](../domain/entities/error.types.ts)
+- **Retry Service**: [`RETRY_SERVICE.md`](../infrastructure/services/RETRY_SERVICE.md)
+- **Error Mapper**: [`ERROR_MAPPER.md`](./ERROR_MAPPER.md)
+
+## 📋 Configuration Reference
+
+### GeminiErrorType Categories
+
+| Error Type | Description | Retry | Example Message |
+|------------|-------------|-------|-----------------|
+| `QUOTA_EXCEEDED` | Quota exceeded | ✅ | "Quota exceeded" |
+| `RATE_LIMIT` | Rate limit | ✅ | "Too many requests" |
+| `AUTHENTICATION` | Authentication failed | ❌ | "Invalid API key" |
+| `SAFETY` | Safety blocked | ❌ | "Content blocked" |
+| `MODEL_NOT_FOUND` | Model not found | ❌ | "Model not found" |
+| `NETWORK` | Network error | ✅ | "Network error" |
+| `TIMEOUT` | Request timeout | ✅ | "Request timeout" |
+| `SERVER` | Server error (5xx) | ✅ | "Internal server error" |
+| `VALIDATION` | Validation error | ❌ | "Invalid request" |
+| `UNKNOWN` | Unknown error | ❌ | "Unknown error" |
+
+### Error Patterns
+
+Error mapper searches for these patterns in error messages:
+- **Quota**: "quota", "resource exhausted", "429"
+- **Rate Limit**: "rate limit", "too many requests"
+- **Auth**: "unauthorized", "invalid api key", "401", "403"
+- **Safety**: "safety", "blocked", "harmful"
+- **Not Found**: "model not found", "404"
+- **Network**: "network", "fetch failed", "connection"
+- **Timeout**: "timeout", "timed out"
+- **Server**: "500", "502", "503", "504", "internal server"
+- **Validation**: "invalid", "bad request", "400"
+
+## 🎓 Usage Patterns
+
+### Retry Logic
+1. Catch error from API call
+2. Check `isGeminiErrorRetryable()`
+3. If retryable and max retries not reached, retry with backoff
+4. If non-retryable or max retries reached, handle error
+5. Provide user feedback
+
+### Error Categorization
+1. Catch error from operation
+2. Call `categorizeGeminiError()` to get error type
+3. Switch on error type for handling
+4. Show appropriate user message per type
+5. Log error with full context
+
+### User-Friendly Messages
+1. Categorize error using `categorizeGeminiError()`
+2. Map error type to user-friendly message
+3. Display message to user
+4. Provide actionable next steps when possible
+5. Log technical details separately
+
+### Error Analytics
+1. Categorize each error
+2. Track error counts by type
+3. Calculate error rates
+4. Send to analytics service
+5. Monitor error trends
+
+### Conditional Retry
+1. Attempt operation
+2. On error, check if retryable
+3. If retryable, calculate backoff delay
+4. Wait for backoff period
+5. Retry operation or fail after max attempts
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Retry non-retryable errors (auth, validation, safety)
+- Show technical error messages to users
+- Ignore error categorization
+- Forget to log errors
+- Expose API keys in error messages
+
+### Do
+- Always check error type before handling
+- Use retryable status for retry logic
+- Provide user-friendly messages
+- Log errors with full context
+- Track errors for analytics
+- Implement exponential backoff for retries
+- Handle permanent errors appropriately
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/utils/IMAGE_PREPARER_UTILS.md

@@ -0,0 +1,185 @@
+# Image Preparer Utility
+
+Helper functions for preparing images for Gemini API. Handles URI to base64 conversion and MIME type detection.
+
+## 📍 Import Path
+
+```
+import {
+  prepareImageFromUri,
+  prepareImage,
+  isValidBase64
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use image preparer to convert image URIs to base64 format. Handles various URI types and MIME type detection.
+
+**When to use:**
+- Convert image URIs to base64
+- Detect MIME types from URIs
+- Prepare images for API upload
+- Validate base64 data
+- Handle React Native image selection
+
+## 📌 Strategy
+
+Image preparation ensures compatibility. This utility:
+- Converts various URI formats to base64
+- Detects MIME types automatically
+- Validates base64 data
+- Handles different image sources
+- Simplifies image processing
+
+**Key Decision**: Always use preparer for image data. Handles URI conversion and MIME detection automatically.
+
+## ⚠️ Rules
+
+### Conversion Rules
+- **MUST** validate URI before conversion
+- **SHOULD** handle various URI formats
+- **MUST** detect MIME type correctly
+- **SHOULD** validate output base64
+- **MUST NOT** lose data integrity
+
+### Validation Rules
+- **SHOULD** validate base64 format
+- **MUST** check for empty data
+- **SHOULD** validate MIME types
+- **MUST** handle validation errors
+- **SHOULD NOT** accept invalid data
+
+### URI Handling Rules
+- **MUST** support various URI types
+- **SHOULD** detect format automatically
+- **MUST** handle network URIs
+- **SHOULD** cache conversions when possible
+- **MUST NOT** fail silently
+
+### Performance Rules
+- **SHOULD** cache prepared images
+- **MUST** handle large images efficiently
+- **SHOULD** optimize when needed
+- **MUST NOT** block main thread
+- **SHOULD** handle concurrent requests
+
+## 🤖 AI Agent Guidelines
+
+### When Preparing Images
+1. **CALL** prepareImageFromUri()
+2. **PROVIDE** image URI
+3. **WAIT** for conversion
+4. **VALIDATE** output
+5. **HANDLE** errors gracefully
+
+### When Validating Base64
+1. **CALL** isValidBase64()
+2. **PROVIDE** base64 string
+3. **CHECK** return value
+4. **HANDLE** invalid data
+5. **PROVIDE** clear feedback
+
+### When Processing Multiple Images
+1. **PREPARE** images in parallel
+2. **USE** Promise.all()
+3. **VALIDATE** all results
+4. **CACHE** prepared images
+5. **HANDLE** partial failures
+
+### Code Style Rules
+- **VALIDATE** input URIs
+- **HANDLE** conversion errors
+- **CACHE** when appropriate
+- **VALIDATE** output data
+- **LOG** preparation issues
+
+## 📦 Available Functions
+
+**Refer to**: [`image-preparer.util.ts`](./image-preparer.util.ts)
+
+### Image Preparation
+- `prepareImageFromUri(uri)` - Convert URI to base64
+- `prepareImage(uri)` - Alias for prepareImageFromUri
+
+### Validation
+- `isValidBase64(str)` - Validate base64 format
+
+## 🔗 Related Modules
+
+- **Data Transformer**: [`./DATA_TRANSFORMER_UTILS.md`](./DATA_TRANSFORMER_UTILS.md)
+- **Input Builders**: [`./INPUT_BUILDERS.md`](./INPUT_BUILDERS.md)
+- **Image Edit Service**: [`../services/IMAGE_EDIT_SERVICE.md`](../services/IMAGE_EDIT_SERVICE.md)
+
+## 📋 Supported Formats
+
+### URI Types
+- Data URL: `data:image/png;base64,...`
+- HTTP/HTTPS URL: `https://example.com/image.jpg`
+- File URI: `file:///path/to/image.png`
+- React Native Asset: Asset paths
+
+### MIME Types
+- JPEG: `.jpg`, `.jpeg` → `image/jpeg`
+- PNG: `.png` → `image/png`
+- GIF: `.gif` → `image/gif`
+- WebP: `.webp` → `image/webp`
+
+### Return Type
+```typescript
+{
+  base64: string;    // Pure base64 (no data URL)
+  mimeType: string;  // Detected MIME type
+}
+```
+
+## 🎓 Usage Patterns
+
+### Basic Preparation
+1. Provide image URI
+2. Call prepareImageFromUri()
+3. Get base64 and MIME type
+4. Use in API request
+5. Handle errors
+
+### Image Picker Integration
+1. Get URI from image picker
+2. Call prepareImageFromUri()
+3. Validate prepared image
+4. Use in service call
+5. Display to user
+
+### Multiple Images
+1. Collect all image URIs
+2. Prepare in parallel
+3. Validate all results
+4. Use in batch operations
+5. Handle partial failures
+
+### Base64 Validation
+1. Get base64 string
+2. Call isValidBase64()
+3. Check validation result
+4. Use or reject data
+5. Provide feedback
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Skip validation of prepared images
+- Assume URI format
+- Forget to handle errors
+- Use unvalidated base64
+- Block main thread with large images
+
+### Do
+- Always validate output
+- Handle various URI formats
+- Cache prepared images
+- Handle errors gracefully
+- Optimize for performance
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)