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

package/src/infrastructure/services/VIDEO_DOWNLOADER_SERVICE.md

@@ -0,0 +1,166 @@
+# Video Downloader Service
+
+Utility for downloading videos from authenticated Veo URLs and converting them to base64 data URIs. Veo URLs require authentication via the `x-goog-api-key` header.
+
+## 📍 Import Path
+
+```
+import { downloadVideoFromVeo } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video downloader to fetch generated videos from authenticated Veo URLs. Downloads and converts videos to base64 for local use.
+
+**When to use:**
+- Download generated videos from Veo API
+- Convert videos to base64 format
+- Handle authenticated video URLs
+- Prepare videos for local storage
+- Display videos in React Native apps
+
+## 📌 Strategy
+
+Veo URLs require authentication. This service:
+- Adds authentication headers to requests
+- Downloads video data
+- Converts to base64 format
+- Provides file metadata
+- Handles download errors
+
+**Key Decision**: Always use downloader for Veo video URLs. Direct requests will fail without authentication.
+
+## ⚠️ Rules
+
+### Download Rules
+- **MUST** provide valid API key
+- **SHOULD** validate video URL format
+- **MUST** handle download errors
+- **SHOULD** check file size limits
+- **MUST NOT** expose API key in errors
+
+### Authentication Rules
+- **MUST** include API key in headers
+- **SHOULD** use secure storage for keys
+- **MUST NOT** cache video URLs indefinitely
+- **SHOULD** refresh expired URLs
+- **MUST** handle authentication failures
+
+### File Handling Rules
+- **SHOULD** validate video format
+- **MUST** handle large files
+- **SHOULD** compress if needed
+- **MUST** check available storage
+- **SHOULD NOT** block main thread
+
+### Error Handling Rules
+- **MUST** handle network errors
+- **SHOULD** retry on transient failures
+- **MUST** provide clear error messages
+- **SHOULD** log download failures
+- **MUST NOT** lose download progress
+
+## 🤖 AI Agent Guidelines
+
+### When Downloading Videos
+1. **VALIDATE** video URL
+2. **PROVIDE** API key
+3. **CALL** downloadVideoFromVeo()
+4. **HANDLE** download result
+5. **STORE** or display video
+
+### When Handling Large Videos
+1. **CHECK** file size before download
+2. **WARN** user about large downloads
+3. **IMPLEMENT** progress tracking
+4. **HANDLE** storage constraints
+5. **PROVIDE** cancellation option
+
+### When Handling Errors
+1. **CATCH** download errors
+2. **CHECK** error type
+3. **RETRY** if appropriate
+4. **INFORM** user of failure
+5. **LOG** error details
+
+### Code Style Rules
+- **VALIDATE** inputs before download
+- **HANDLE** all error cases
+- **PROVIDE** progress feedback
+- **CLEAN UP** on failure
+- **SECURE** API keys
+
+## 📦 Available Function
+
+### downloadVideoFromVeo
+
+**Refer to**: [`gemini-video-downloader.ts`](./gemini-video-downloader.ts)
+
+**Parameters:**
+- `videoUrl`: string - Authenticated Veo video URL
+- `apiKey`: string - Google Cloud API key
+
+**Returns:** Promise<VideoDownloadResult>
+- `base64DataUri`: string - Base64 video with data URI prefix
+- `sizeInMB`: number - File size in megabytes
+- `mimeType`: string - Video MIME type
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Video URL Extractor**: [`VIDEO_URL_EXTRACTOR_SERVICE.md`](./VIDEO_URL_EXTRACTOR_SERVICE.md)
+
+## 📋 Return Type
+
+```typescript
+interface VideoDownloadResult {
+  base64DataUri: string;  // data:video/mp4;base64,...
+  sizeInMB: number;       // File size in MB
+  mimeType: string;       // video/mp4 or video/webm
+}
+```
+
+## 🎓 Usage Patterns
+
+### Basic Download
+1. Get video URL from generation response
+2. Call downloadVideoFromVeo()
+3. Get base64 result
+4. Store or display video
+5. Handle errors
+
+### Large File Handling
+1. Check file size before download
+2. Warn user if large
+3. Implement progress tracking
+4. Download with cancellation option
+5. Handle storage constraints
+
+### Error Recovery
+1. Catch download errors
+2. Check if retryable
+3. Retry with backoff
+4. Inform user of failure
+5. Provide alternative options
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use direct fetch for Veo URLs
+- Expose API key in errors
+- Ignore file size limits
+- Block main thread
+- Skip error handling
+
+### Do
+- Always use downloader service
+- Secure API keys properly
+- Check file sizes
+- Handle errors gracefully
+- Provide user feedback
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_ERROR_HANDLER_SERVICE.md

@@ -0,0 +1,185 @@
+# Video Error Handler Service
+
+Factory for creating typed video generation errors with retry information. Provides consistent error handling for video generation operations.
+
+## 📍 Import Path
+
+```
+import { createVideoError } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video error handler to create typed errors for video generation failures. Provides consistent error handling with retry information.
+
+**When to use:**
+- Create video generation errors
+- Determine retry behavior
+- Handle video operation failures
+- Provide consistent error messages
+- Categorize error types
+
+## 📌 Strategy
+
+Typed errors improve error handling. This service:
+- Categorizes error types
+- Provides retry information
+- Creates consistent error objects
+- Includes status codes
+- Simplifies error handling
+
+**Key Decision**: Always use createVideoError for video failures. Provides consistent error handling across video operations.
+
+## ⚠️ Rules
+
+### Error Creation Rules
+- **MUST** specify error type
+- **SHOULD** provide clear messages
+- **MUST** include context information
+- **SHOULD** set retry flag correctly
+- **MUST NOT** expose sensitive data
+
+### Error Type Rules
+- **MUST** use appropriate error type
+- **SHOULD** distinguish retryable errors
+- **MUST** match error to situation
+- **SHOULD** provide status codes
+- **MUST NOT** use unknown type unnecessarily
+
+### Retry Rules
+- **SHOULD** retry NETWORK errors
+- **SHOULD** retry TIMEOUT errors
+- **MUST NOT** retry VALIDATION errors
+- **SHOULD NOT** retry QUOTA errors
+- **MUST** implement backoff for retries
+
+### Error Handling Rules
+- **MUST** catch all video errors
+- **SHOULD** log error details
+- **MUST** inform user appropriately
+- **SHOULD** provide recovery options
+- **MUST NOT** suppress errors
+
+## 🤖 AI Agent Guidelines
+
+### When Creating Errors
+1. **IDENTIFY** error type
+2. **CREATE** error with createVideoError()
+3. **INCLUDE** relevant context
+4. **SET** retry flag appropriately
+5. **THROW** or return error
+
+### When Handling Errors
+1. **CATCH** video generation errors
+2. **CHECK** error type
+3. **DETERMINE** retry eligibility
+4. **INFORM** user appropriately
+5. **PROVIDE** recovery options
+
+### When Implementing Retries
+1. **CHECK** error.retryable flag
+2. **IMPLEMENT** exponential backoff
+3. **SET** retry limit
+4. **LOG** retry attempts
+5. **FAIL** after max retries
+
+### Code Style Rules
+- **USE** typed error creation
+- **PROVIDE** clear error messages
+- **INCLUDE** relevant context
+- **HANDLE** all error types
+- **LOG** error information
+
+## 📦 Available Function
+
+### createVideoError
+
+**Refer to**: [`gemini-video-error.ts`](./gemini-video-error.ts)
+
+**Parameters:**
+- `type`: VideoGenerationErrorType - Error category
+- `message`: string - Human-readable error message
+- `statusCode?`: number - HTTP status code
+
+**Returns:** VideoGenerationError
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Error Utilities**: [`../utils/ERROR_UTILITIES.md`](../utils/ERROR_UTILITIES.md)
+- **Retry Service**: [`RETRY_SERVICE.md`](./RETRY_SERVICE.md)
+
+## 📋 Error Types
+
+### NETWORK
+Network-related errors (retryable)
+
+### TIMEOUT
+Request timeout (retryable)
+
+### API
+API-level errors (may be retryable)
+
+### VALIDATION
+Input validation errors (not retryable)
+
+### QUOTA
+Quota/rate limit errors (not retryable)
+
+### UNKNOWN
+Uncategorized errors
+
+### Retry Behavior
+
+| Error Type | Retryable | Description |
+|------------|-----------|-------------|
+| NETWORK | Yes | Transient network issues |
+| TIMEOUT | Yes | Request timeouts |
+| API | Maybe | API-specific errors |
+| VALIDATION | No | Invalid input |
+| QUOTA | No | Rate limit exceeded |
+| UNKNOWN | Maybe | Uncategorized errors |
+
+## 🎓 Usage Patterns
+
+### Error Creation
+1. Identify error type
+2. Call createVideoError()
+3. Provide message and status
+4. Include context
+5. Throw or return error
+
+### Error Handling
+1. Catch video errors
+2. Check error type
+3. Determine retry eligibility
+4. Handle appropriately
+5. Inform user
+
+### Retry Logic
+1. Check error.retryable
+2. Implement backoff
+3. Set retry limit
+4. Log attempts
+5. Fail after max retries
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use generic errors
+- Skip error type specification
+- Ignore retry flag
+- Expose sensitive data
+- Suppress errors
+
+### Do
+- Use typed error creation
+- Specify error type correctly
+- Check retry flag
+- Provide clear messages
+- Handle all error cases
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_GENERATION_SERVICE.md

@@ -0,0 +1,176 @@
+# Video Generation Service
+
+Generates videos from text prompts and images using Google Veo API.
+
+## 📍 Import Path
+
+```
+import { geminiVideoGenerationService } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this service to generate AI-powered videos from text descriptions or images. Supports text-to-video and image-to-video generation with progress tracking using Veo models.
+
+**When to use:**
+- Generate videos from text descriptions
+- Animate existing images
+- Create video content for applications
+- Product visualization and motion graphics
+
+## 📌 Strategy
+
+Video generation is an async, long-running operation that requires special handling. This service:
+- Implements automatic polling for operation status
+- Provides progress callbacks for UI feedback
+- Supports multiple aspect ratios for different platforms
+- Handles video download and URL generation
+- Manages queuing and processing states
+
+**Key Decision**: Video generation uses polling mechanism since processing takes time. The service automatically handles status checks and provides progress updates through callbacks.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** initialize provider with API key before use
+- **MUST** handle async operation completion
+- **SHOULD** implement progress callbacks for UX
+- **MUST NOT** assume immediate results
+- **MUST** handle video generation errors appropriately
+
+### Prompt Rules
+- **SHOULD** describe motion and action clearly
+- **SHOULD** specify camera movements
+- **MUST NOT** exceed 2000 character limit
+- **SHOULD** include atmosphere and mood details
+
+### Configuration Rules
+- **MUST** use valid model IDs (veo-3.1-fast-generate-preview)
+- **SHOULD** select appropriate aspect ratio for platform
+- **MUST** respect content safety guidelines
+- **SHOULD** set reasonable timeout expectations
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **MUST** check `result.status` for completion
+- **MUST** handle `result.error` for failures
+- **SHOULD** provide user-friendly error messages
+- **MUST NOT** expose API keys in errors
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying This Service
+1. **READ** the implementation file first
+2. **UNDERSTAND** polling mechanism
+3. **MAINTAIN** backward compatibility
+4. **ADD** tests for new functionality
+5. **UPDATE** type definitions
+
+### When Adding New Features
+1. **CHECK** if similar feature exists in video services
+2. **FOLLOW** existing patterns
+3. **USE** established error handling
+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
+- **USE** async/await (no callbacks except onProgress)
+- **VALIDATE** inputs at function entry
+- **THROW** typed errors (`GeminiError`)
+- **LOG** important operations
+- **COMMENT** complex logic only
+
+## 📦 Available Methods
+
+### `generateTextToVideo(input, onProgress?)`
+
+Generate video from text prompt.
+
+**Refer to**: [`gemini-video-generation.service.ts`](./gemini-video-generation.service.ts)
+
+### `generateVideo(input, onProgress?)`
+
+Generate video from text and/or image.
+
+**Refer to**: [`gemini-video-generation.service.ts`](./gemini-video-generation.service.ts)
+
+## 🔗 Related Modules
+
+- **Domain Types**: [`domain/entities/README.md`](../domain/entities/README.md)
+- **Veo HTTP Client**: [`VEO_HTTP_CLIENT_SERVICE.md`](./VEO_HTTP_CLIENT_SERVICE.md)
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+- **Video Error Handler**: [`VIDEO_ERROR_HANDLER_SERVICE.md`](./VIDEO_ERROR_HANDLER_SERVICE.md)
+
+## 📋 Configuration Reference
+
+### Generation Config
+See: [`domain/entities/README.md`](../domain/entities/README.md)
+
+### Model Selection
+- Current model: `veo-3.1-fast-generate-preview`
+- Aspect ratios: `16:9` | `9:16` | `1:1` | `4:3`
+- Resolution: Up to 4K
+- Duration: Auto-determined by model
+
+### Error Types
+See: [`ERROR_UTILITIES.md`](../infrastructure/utils/ERROR_UTILITIES.md)
+
+## 🎓 Usage Patterns
+
+### Basic Text-to-Video
+1. Import service
+2. Call `generateTextToVideo()` with prompt and options
+3. Provide `onProgress` callback for UI updates
+4. Handle response (contains `videoUrl`, `status`, `progress`)
+5. Display video or handle errors
+
+### Image-to-Video
+1. Import service
+2. Prepare base64-encoded image
+3. Call `generateVideo()` with prompt and image
+4. Monitor progress through callback
+5. Download or display result video
+
+### With Progress Tracking
+1. Implement progress callback function
+2. Update UI with progress percentage and status
+3. Handle status changes: queued → processing → completed/failed
+4. Show appropriate loading states
+5. Display final video or error message
+
+### With Negative Prompts
+1. Prepare main prompt describing desired content
+2. Add negative prompt for unwanted elements
+3. Call generation method with both prompts
+4. Handle result as normal
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume immediate video generation (takes minutes)
+- Ignore progress callbacks (bad UX)
+- Forget to handle failed status
+- Use extremely long prompts (>2000 chars)
+- Expect all videos to have same duration
+
+### Do
+- Implement progress tracking
+- Handle all status states (queued, processing, completed, failed)
+- Provide loading feedback to users
+- Use descriptive prompts with motion details
+- Specify camera movements and atmosphere
+- Handle timeouts appropriately
+- Consider aspect ratio for target platform
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/infrastructure/services/VIDEO_URL_EXTRACTOR_SERVICE.md

@@ -0,0 +1,186 @@
+# Video URL Extractor Service
+
+Utility for extracting video URLs from Veo API operation responses. Handles multiple response formats from different Veo API versions.
+
+## 📍 Import Path
+
+```
+import { extractVideoUrl } from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use video URL extractor to get video URLs from Veo operation responses. Handles multiple API response formats transparently.
+
+**When to use:**
+- Extract video URLs from Veo responses
+- Handle different API versions
+- Parse operation results
+- Get download URLs
+- Process video generation responses
+
+## 📌 Strategy
+
+Veo API has multiple response formats. This utility:
+- Handles all response format variations
+- Extracts URLs transparently
+- Provides null safety
+- Supports API version changes
+- Simplifies response parsing
+
+**Key Decision**: Always use extractor for Veo responses. Handles format variations automatically.
+
+## ⚠️ Rules
+
+### Extraction Rules
+- **MUST** handle all response formats
+- **SHOULD** validate operation object
+- **MUST** return null if URL not found
+- **SHOULD** log unexpected formats
+- **MUST NOT** throw on missing URL
+
+### Validation Rules
+- **SHOULD** check operation structure
+- **MUST** validate URL format
+- **SHOULD** handle null responses
+- **MUST** verify URL accessibility
+- **SHOULD NOT** assume format
+
+### Error Handling Rules
+- **MUST** return null on failure
+- **SHOULD** log parsing errors
+- **MUST NOT** throw exceptions
+- **SHOULD** handle malformed responses
+- **MUST** provide graceful degradation
+
+### URL Handling Rules
+- **MUST** validate URL strings
+- **SHOULD** check URL scheme
+- **MUST** handle authentication requirements
+- **SHOULD NOT** expose sensitive data
+- **MUST** preserve URL parameters
+
+## 🤖 AI Agent Guidelines
+
+### When Extracting URLs
+1. **PROVIDE** operation object
+2. **CALL** extractVideoUrl()
+3. **CHECK** return value
+4. **HANDLE** null result
+5. **USE** URL or report error
+
+### When Handling Missing URLs
+1. **CHECK** if result is null
+2. **LOG** response structure
+3. **VERIFY** operation completed
+4. **REPORT** error to user
+5. **PROVIDE** recovery options
+
+### When Validating Responses
+1. **CHECK** operation object structure
+2. **LOOK** for expected fields
+3. **HANDLE** format variations
+4. **LOG** unexpected formats
+5. **UPDATE** for new API versions
+
+### Code Style Rules
+- **VALIDATE** input structure
+- **HANDLE** all format variations
+- **RETURN** null for missing URLs
+- **LOG** unexpected structures
+- **TEST** with various formats
+
+## 📦 Available Function
+
+### extractVideoUrl
+
+**Refer to**: [`gemini-video-url-extractor.ts`](./gemini-video-url-extractor.ts)
+
+**Parameters:**
+- `operation`: VeoOperation - Veo operation response object
+
+**Returns:** string | null - Video URL if found, otherwise null
+
+## 🔗 Related Modules
+
+- **Video Generation**: [`VIDEO_GENERATION_SERVICE.md`](./VIDEO_GENERATION_SERVICE.md)
+- **Video Downloader**: [`VIDEO_DOWNLOADER_SERVICE.md`](./VIDEO_DOWNLOADER_SERVICE.md)
+- **Veo Polling**: [`VEO_POLLING_SERVICE.md`](./VEO_POLLING_SERVICE.md)
+
+## 📋 Supported Response Formats
+
+### Format 1: New SDK Format
+```typescript
+{
+  response: {
+    generatedVideos: [{
+      video: { uri: "https://..." }
+    }]
+  }
+}
+```
+
+### Format 2: Alternative SDK Format
+```typescript
+{
+  response: {
+    generatedVideos: [{
+      uri: "https://..."
+    }]
+  }
+}
+```
+
+### Format 3: Legacy Format
+```typescript
+{
+  done: true,
+  response: {
+    videoUri: "https://..."
+  }
+}
+```
+
+## 🎓 Usage Patterns
+
+### URL Extraction
+1. Get operation response
+2. Call extractVideoUrl()
+3. Check if URL exists
+4. Use URL for download
+5. Handle missing URL
+
+### Format Handling
+1. Provide operation object
+2. Extract URL transparently
+3. Handle any format variation
+4. Get URL or null
+5. Process result accordingly
+
+### Error Handling
+1. Call extractor
+2. Check for null result
+3. Log response structure if missing
+4. Report error to user
+5. Provide recovery options
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Assume specific response format
+- Throw on missing URL
+- Skip null checking
+- Hardcode response paths
+- Ignore format variations
+
+### Do
+- Always check for null
+- Handle all formats
+- Log unexpected structures
+- Return null gracefully
+- Test with various responses
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../../AI_GUIDELINES.md)