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

package/src/infrastructure/telemetry/TELEMETRY_SYSTEM.md

@@ -0,0 +1,200 @@
+# Telemetry System
+
+Monitoring and logging system for AI operations. Allows applications to track requests, responses, errors, and retries in real-time.
+
+## 📍 Import Path
+
+```
+import { telemetryHooks } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use telemetry to monitor AI operations in real-time. Provides event-based system for tracking performance, errors, and usage patterns.
+
+**When to use:**
+- Monitor API call performance
+- Track error rates and types
+- Analyze usage patterns
+- Debug AI operations
+- Send events to analytics services
+- Track rate limiting
+
+## 📌 Strategy
+
+Telemetry provides visibility into AI operations. This system:
+- Uses publish-subscribe pattern for events
+- Supports multiple listeners simultaneously
+- Emits events for all operations
+- Provides timing and metadata
+- Enables custom monitoring solutions
+
+**Key Decision**: Subscribe to telemetry events early in application lifecycle. Use events for monitoring, analytics, and debugging.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** subscribe to events before operations
+- **SHOULD** unsubscribe when done
+- **MUST NOT** emit sensitive data in events
+- **SHOULD** aggregate metrics for performance
+- **MUST** handle listener errors gracefully
+
+### Event Subscription Rules
+- **SHOULD** subscribe at application startup
+- **MUST** store unsubscribe function
+- **SHOULD** handle all event types
+- **MUST NOT** block event emission
+- **SHOULD** filter events as needed
+
+### Data Privacy Rules
+- **MUST NOT** log API keys in events
+- **SHOULD NOT** include user data in metadata
+- **MUST** sanitize sensitive information
+- **SHOULD** use anonymized IDs
+- **MUST** comply with privacy policies
+
+### Performance Rules
+- **SHOULD** keep listeners lightweight
+- **MUST** avoid expensive operations in listeners
+- **SHOULD** batch event processing
+- **MUST NOT** block main thread
+- **SHOULD** use async operations for heavy processing
+
+## 🤖 AI Agent Guidelines
+
+### When Adding Telemetry
+1. **SUBSCRIBE** to telemetry events early
+2. **HANDLE** all event types appropriately
+3. **AGGREGATE** metrics for analysis
+4. **SEND** to monitoring/analytics service
+5. **UNSUBSCRIBE** on cleanup
+
+### When Creating Custom Monitoring
+1. **DEFINE** metrics to track
+2. **CREATE** data structures for aggregation
+3. **IMPLEMENT** event filtering
+4. **CALCULATE** statistics periodically
+5. **EXPORT** metrics for visualization
+
+### When Debugging with Telemetry
+1. **ADD** verbose logging for events
+2. **TRACK** request/response correlation
+3. **MONITOR** error patterns
+4. **ANALYZE** performance metrics
+5. **IDENTIFY** bottlenecks
+
+### Code Style Rules
+- **USE** unsubscribe pattern for cleanup
+- **FILTER** events by type or model
+- **AGGREGATE** metrics efficiently
+- **HANDLE** errors in listeners
+- **LOG** important state changes
+
+## 📦 Available System
+
+### telemetryHooks
+
+**Refer to**: [`TelemetryHooks.ts`](./TelemetryHooks.ts)
+
+**Singleton instance**
+
+**Methods:**
+- `subscribe(listener)` - Add event listener
+- `emit(event)` - Emit custom event
+- `logRequest(model, feature?)` - Log request start
+- `logResponse(model, startTime, feature?, metadata?)` - Log response
+- `logError(model, error, feature?)` - Log error
+- `logRetry(model, attempt, feature?)` - Log retry
+- `clear()` - Clear all listeners
+- `getListenerCount()` - Get active listener count
+
+## 🔗 Related Modules
+
+- **Infrastructure README**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Services**: [`../services/README.md`](../services/README.md)
+- **Interceptors**: [`../interceptors/README.md`](../interceptors/README.md)
+
+## 📋 Event Types
+
+### Request Event
+Emitted when operation starts.
+- Contains model and feature
+- Includes timestamp
+- No duration yet
+
+### Response Event
+Emitted when operation completes.
+- Contains model and feature
+- Includes duration in milliseconds
+- May include metadata (token count, finish reason)
+
+### Error Event
+Emitted when operation fails.
+- Contains model and feature
+- Includes error information
+- May include error type
+
+### Retry Event
+Emitted when retry is attempted.
+- Contains model and feature
+- Includes attempt number
+- Tracks retry behavior
+
+## 🎓 Usage Patterns
+
+### Basic Monitoring
+1. Subscribe to telemetry events
+2. Track metrics in event handler
+3. Send to analytics/monitoring service
+4. Aggregate and analyze metrics
+5. Unsubscribe when done
+
+### Analytics Integration
+1. Subscribe to telemetry events
+2. Transform events to analytics format
+3. Send to analytics service
+4. Filter sensitive information
+5. Handle errors gracefully
+
+### Performance Tracking
+1. Track response times by model
+2. Calculate statistics (avg, min, max)
+3. Monitor trends over time
+4. Alert on slow operations
+5. Generate performance reports
+
+### Error Tracking
+1. Subscribe to error events
+2. Categorize errors by type
+3. Track error rates
+4. Send to error tracking service
+5. Monitor for anomalies
+
+### Custom Dashboard
+1. Aggregate event data
+2. Calculate statistics
+3. Track model usage
+4. Monitor success rates
+5. Generate dashboard metrics
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Forget to unsubscribe from events
+- Log sensitive data in events
+- Block event emission with heavy processing
+- Subscribe multiple times without cleanup
+- Emit custom events without proper format
+
+### Do
+- Subscribe early in application lifecycle
+- Clean up listeners when done
+- Keep listeners lightweight
+- Aggregate telemetry metrics
+- Handle all event types appropriately
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/utils/DATA_TRANSFORMER_UTILS.md

@@ -0,0 +1,175 @@
+# Data Transformer Utilities
+
+Helper functions for transforming and processing Gemini API data. Extracts and converts data formats.
+
+## 📍 Import Path
+
+```
+import {
+  extractBase64Data,
+  extractTextFromResponse
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use data transformers to extract and convert Gemini API data formats. Handles base64 extraction and text parsing.
+
+**When to use:**
+- Extract base64 from data URLs
+- Parse text from API responses
+- Clean up data formats
+- Transform response structures
+- Process multimodal data
+
+## 📌 Strategy
+
+Data transformation ensures compatibility. This system:
+- Extracts base64 from various formats
+- Parses text from complex responses
+- Handles missing data gracefully
+- Normalizes data structures
+- Simplifies data processing
+
+**Key Decision**: Always use transformers for data extraction. Handles edge cases and format variations automatically.
+
+## ⚠️ Rules
+
+### Extraction Rules
+- **MUST** handle missing data gracefully
+- **SHOULD** validate input format
+- **MUST** return empty string on failure
+- **SHOULD** log extraction errors
+- **MUST NOT** throw on invalid data
+
+### Format Rules
+- **MUST** support multiple input formats
+- **SHOULD** detect format automatically
+- **MUST** preserve data integrity
+- **SHOULD** handle encoding correctly
+- **MUST NOT** corrupt data
+
+### Validation Rules
+- **SHOULD** validate base64 before use
+- **MUST** check for empty responses
+- **SHOULD** handle malformed data
+- **MUST** provide safe defaults
+- **SHOULD NOT** assume format
+
+### Error Handling Rules
+- **MUST** wrap extraction in try-catch
+- **SHOULD** log transformation errors
+- **MUST** return safe defaults
+- **SHOULD NOT** propagate errors
+- **MUST** handle all edge cases
+
+## 🤖 AI Agent Guidelines
+
+### When Extracting Base64
+1. **CALL** extractBase64Data()
+2. **PROVIDE** data URL or base64
+3. **GET** pure base64 string
+4. **VALIDATE** output
+5. **HANDLE** extraction errors
+
+### When Extracting Text
+1. **CALL** extractTextFromResponse()
+2. **PROVIDE** Gemini response object
+3. **GET** concatenated text
+4. **CHECK** for empty results
+5. **HANDLE** missing text
+
+### When Transforming Data
+1. **VALIDATE** input format
+2. **CALL** appropriate transformer
+3. **CHECK** output validity
+4. **USE** transformed data
+5. **HANDLE** transformation errors
+
+### Code Style Rules
+- **VALIDATE** input before transformation
+- **HANDLE** all edge cases
+- **PROVIDE** safe defaults
+- **LOG** transformation errors
+- **TEST** with various formats
+
+## 📦 Available Functions
+
+**Refer to**: [`gemini-data-transformer.util.ts`](./gemini-data-transformer.util.ts)
+
+### Base64 Extraction
+- `extractBase64Data(base64)` - Extract base64 from data URL
+
+### Text Extraction
+- `extractTextFromResponse(response)` - Extract text from Gemini response
+
+## 🔗 Related Modules
+
+- **Domain Entities**: [`../../domain/entities/README.md`](../../domain/entities/README.md)
+- **Image Edit Service**: [`../services/IMAGE_EDIT_SERVICE.md`](../services/IMAGE_EDIT_SERVICE.md)
+- **Response Formatter**: [`../response/RESPONSE_FORMATTER.md`](../response/RESPONSE_FORMATTER.md)
+
+## 📋 Supported Formats
+
+### Base64 Input Formats
+- Data URL: `data:image/png;base64,iVBORw0KG...`
+- Pure base64: `iVBORw0KG...`
+- Various MIME types: PNG, JPEG, GIF, WebP
+
+### Response Structure
+```typescript
+{
+  candidates: [{
+    content: {
+      parts: [
+        { text: string },
+        { inlineData: { mimeType: string; data: string } }
+      ]
+    }
+  }]
+}
+```
+
+## 🎓 Usage Patterns
+
+### Base64 Extraction
+1. Provide data URL or base64
+2. Call extractBase64Data()
+3. Get pure base64 string
+4. Use in API requests
+5. Handle empty results
+
+### Text Extraction
+1. Provide Gemini response object
+2. Call extractTextFromResponse()
+3. Get concatenated text
+4. Use extracted text
+5. Handle empty responses
+
+### Data Processing
+1. Validate input format
+2. Transform with utilities
+3. Validate output
+4. Use in application
+5. Handle errors gracefully
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume data format
+- Skip validation
+- Throw on invalid data
+- Ignore empty responses
+- Corrupt data during transformation
+
+### Do
+- Validate input format
+- Handle all edge cases
+- Provide safe defaults
+- Test with various formats
+- Handle errors gracefully
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

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)