@umituz/react-native-ai-gemini-provider 1.14.27 → 1.14.29

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)

package/src/infrastructure/utils/INPUT_BUILDERS.md

@@ -0,0 +1,214 @@
+# Input Builders
+
+Helper functions for building Gemini API inputs for image and video processing features. Creates properly formatted prompts and image arrays.
+
+## 📍 Import Path
+
+```
+import {
+  buildUpscaleInput,
+  buildPhotoRestoreInput,
+  buildRemoveBackgroundInput,
+  buildReplaceBackgroundInput,
+  buildFaceSwapInput,
+  buildSingleImageInput,
+  buildDualImageInput
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use input builders to create properly formatted inputs for image and video features. Simplifies prompt engineering and image data preparation.
+
+**When to use:**
+- Build inputs for image editing features
+- Create prompts for video generation
+- Format image data correctly
+- Combine multiple images
+- Simplify feature integration
+
+## 📌 Strategy
+
+Input builders encapsulate prompt complexity. This system:
+- Creates optimized prompts for features
+- Formats image data correctly
+- Handles single and multiple images
+- Provides consistent interface
+- Simplifies feature usage
+
+**Key Decision**: Always use input builders for image/video features. Ensures correct prompt engineering and data formatting.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use builders for image/video features
+- **SHOULD** provide valid base64 data
+- **MUST** check required parameters
+- **SHOULD** handle missing options
+- **MUST NOT** create inputs manually
+
+### Data Rules
+- **MUST** provide valid base64 strings
+- **SHOULD** validate image data
+- **MUST** include correct MIME types
+- **SHOULD** handle encoding errors
+- **MUST NOT** pass invalid data
+
+### Prompt Rules
+- **MUST** use builder-generated prompts
+- **SHOULD NOT** modify builder prompts
+- **MUST** follow prompt patterns
+- **SHOULD** test prompt effectiveness
+- **MUST NOT** hardcode prompts
+
+### Options Rules
+- **SHOULD** provide appropriate options
+- **MUST** check required parameters
+- **SHOULD** use default values wisely
+- **MUST** validate option values
+- **SHOULD NOT** ignore option validation
+
+## 🤖 AI Agent Guidelines
+
+### When Building Inputs
+1. **SELECT** appropriate builder function
+2. **PROVIDE** valid base64 data
+3. **CONFIGURE** options if needed
+4. **USE** returned prompt and images
+5. **HANDLE** builder errors
+
+### When Using Image Features
+1. **PREPARE** image base64 data
+2. **CALL** appropriate builder
+3. **USE** prompt from builder
+4. **PASS** images array to service
+5. **HANDLE** service response
+
+### When Creating Custom Builders
+1. **ANALYZE** existing builders
+2. **FOLLOW** builder pattern
+3. **CREATE** optimized prompt
+4. **RETURN** consistent structure
+5. **TEST** builder thoroughly
+
+### Code Style Rules
+- **USE** builders instead of manual input
+- **VALIDATE** input data
+- **HANDLE** missing options
+- **FOLLOW** builder patterns
+- **TEST** builder output
+
+## 📦 Available Builders
+
+### Single Image Builders
+
+**Refer to**: [`image-feature-builders.util.ts`](./image-feature-builders.util.ts)
+
+- `buildUpscaleInput(base64, options?)` - Image upscaling
+- `buildPhotoRestoreInput(base64, options?)` - Photo restoration
+- `buildAnimeSelfieInput(base64, options?)` - Anime style transformation
+- `buildRemoveBackgroundInput(base64, options?)` - Background removal
+- `buildRemoveObjectInput(base64, options?)` - Object removal
+- `buildReplaceBackgroundInput(base64, options)` - Background replacement
+- `buildHDTouchUpInput(base64, options?)` - HD enhancement
+
+### Dual Image Builders
+
+**Refer to**: [`image-feature-builders.util.ts`](./image-feature-builders.util.ts)
+
+- `buildFaceSwapInput(sourceBase64, targetBase64, options?)` - Face swapping
+
+### Video Builders
+
+**Refer to**: [`video-feature-builders.util.ts`](./video-feature-builders.util.ts)
+
+- `buildAIHugInput(base64, options?)` - AI hugging effect
+- `buildAIKissInput(base64, options?)` - AI kissing effect
+- `buildVideoFromDualImagesInput(base64a, base64b, options?)` - Dual image to video
+
+### Base Builders
+
+**Refer to**: [`base-input-builders.util.ts`](./base-input-builders.util.ts)
+
+- `buildSingleImageInput(base64, prompt)` - Single image input
+- `buildDualImageInput(base64a, base64b, prompt)` - Dual image input
+
+## 🔗 Related Modules
+
+- **Image Edit Service**: [`../services/IMAGE_EDIT_SERVICE.md`](../services/IMAGE_EDIT_SERVICE.md)
+- **Image Preparer Utils**: [`../utils/IMAGE_PREPARER_UTILS.md`](../utils/IMAGE_PREPARER_UTILS.md)
+- **Content Builder**: [`../content/README.md`](../content/README.md)
+
+## 📋 Builder Return Type
+
+All builders return:
+
+```typescript
+{
+  prompt: string;
+  images: Array<{
+    base64: string;
+    mimeType: string;
+  }>;
+}
+```
+
+This structure is compatible with `geminiImageEditService.editImage()`.
+
+## 🎓 Usage Patterns
+
+### Basic Feature Usage
+1. Prepare image base64 data
+2. Call appropriate builder function
+3. Configure options if needed
+4. Use returned prompt and images
+5. Call image edit service
+
+### Single Image Processing
+1. Get image base64 string
+2. Call single-image builder
+3. Pass prompt and images to service
+4. Handle service response
+5. Display result
+
+### Dual Image Processing
+1. Get both image base64 strings
+2. Call dual-image builder
+3. Use returned input structure
+4. Call appropriate service
+5. Handle response
+
+### Batch Processing
+1. Prepare all images
+2. Call builder for each image
+3. Process inputs in sequence
+4. Collect all results
+5. Return batch results
+
+### Custom Features
+1. Analyze existing builders
+2. Create custom builder function
+3. Follow builder pattern
+4. Return consistent structure
+5. Test thoroughly
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Create inputs manually
+- Modify builder prompts
+- Skip builder functions
+- Hardcode prompts
+- Use invalid base64 data
+
+### Do
+- Always use input builders
+- Follow builder patterns
+- Validate input data
+- Use builder-generated prompts
+- Test builder output
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)