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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-ai-gemini-provider",
-  "version": "1.14.28",
+  "version": "1.14.29",
   "description": "Google Gemini AI provider for React Native applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domain/README.md

@@ -0,0 +1,232 @@
+# Domain Layer
+
+Core type definitions and constants for the Gemini provider. Contains data structures and constants independent of business logic.
+
+## 📍 Import Path
+
+```
+import type {
+  GeminiConfig,
+  GeminiGenerationConfig,
+  GeminiResponse,
+  GeminiImageGenerationResult,
+  VideoGenerationResult,
+  GeminiError,
+  GeminiErrorType
+} from '@umituz/react-native-ai-gemini-provider';
+
+import {
+  GEMINI_MODELS,
+  DEFAULT_MODELS,
+  getGeminiImageFeatureModel,
+  getGeminiVideoFeatureModel
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use this layer for type-safe integration with Gemini services. Provides TypeScript interfaces and constants for all operations.
+
+**When to use:**
+- Type-check API requests and responses
+- Access model constants and configurations
+- Define function signatures
+- Understand data structures
+- Handle typed errors
+
+## 📌 Strategy
+
+Domain layer contains NO business logic or external dependencies. These definitions:
+- Provide pure type definitions
+- Define constant values
+- Enable compile-time type checking
+- Document API contracts
+- Remain stable despite code changes
+
+**Key Decision**: All domain types have NO external dependencies. This keeps them pure, reusable, and testable.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use types from domain layer
+- **SHOULD** use type imports over value imports
+- **MUST** handle all defined error types
+- **SHOULD** use constants instead of hardcoded values
+- **MUST NOT** use `any` type
+
+### Type Safety Rules
+- **MUST** define explicit return types
+- **SHOULD** use strict null checks
+- **MUST** validate runtime data
+- **SHOULD** use discriminated unions for errors
+- **MUST NOT** bypass type checking
+
+### Constants Rules
+- **MUST** use defined model constants
+- **SHOULD** use helper functions for model selection
+- **MUST NOT** hardcode model IDs
+- **SHOULD** prefer constants over magic strings
+- **MUST** use valid model IDs from constants
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Domain Types
+1. **READ** existing type definitions first
+2. **UNDERSTAND** type relationships
+3. **MAINTAIN** backward compatibility
+4. **UPDATE** all dependent code
+5. **ADD** tests for new types
+
+### When Adding New Types
+1. **CHECK** if similar type exists
+2. **FOLLOW** existing naming conventions
+3. **USE** consistent patterns
+4. **DOCUMENT** with JSDoc comments
+5. **EXPORT** from index files
+
+### When Adding Constants
+1. **CHECK** if constant already exists
+2. **USE** descriptive names
+3. **GROUP** related constants
+4. **PROVIDE** helper functions
+5. **DOCUMENT** constant values
+
+### Code Style Rules
+- **USE** explicit type annotations
+- **AVOID** `any` type
+- **PREFER** readonly where appropriate
+- **USE** discriminated unions
+- **DOCUMENT** complex types
+
+## 📦 Available Modules
+
+### Type Definitions
+
+**Entities**: Core data structures
+
+**Refer to**: [`entities/README.md`](./entities/README.md)
+
+**Files:**
+- [`entities/gemini.types.ts`](./entities/gemini.types.ts) - Main Gemini types
+- [`entities/error.types.ts`](./entities/error.types.ts) - Error types
+- [`entities/models.ts`](./entities/models.ts) - Model definitions
+- [`entities/video.types.ts`](./entities/video.types.ts) - Video types
+
+### Constants
+
+**Feature Models**: Model mappings for features
+
+**Refer to**: [`constants/README.md`](./constants/README.md)
+
+**Files:**
+- [`constants/feature-models.constants.ts`](./constants/feature-models.constants.ts) - Feature model mappings
+- [`constants/models.constants.ts`](./constants/models.constants.ts) - Model constants
+
+## 🔗 Related Modules
+
+- **Services**: [`../infrastructure/services/README.md`](../infrastructure/services/README.md)
+- **Infrastructure**: [`../infrastructure/README.md`](../infrastructure/README.md)
+- **Providers**: [`../providers/README.md`](../providers/README.md)
+
+## 📋 Type Reference
+
+### Configuration Types
+
+**GeminiConfig**: Client configuration
+- `apiKey`: string (required)
+- `baseUrl`: string (optional)
+- `maxRetries`: number (optional)
+- Various model IDs (optional)
+
+**GeminiGenerationConfig**: Generation parameters
+- Compatible with Google SDK
+- Temperature, topP, topK, maxOutputTokens
+- Response schema
+
+### Request/Response Types
+
+**GeminiContent**: API request structure
+- `parts`: Array of text, inline data, or file data
+- `role`: "user" | "model"
+
+**GeminiResponse**: API response structure
+- `candidates`: Generated results
+- `promptFeedback`: Prompt feedback
+- `usageMetadata`: Token usage
+
+### Error Types
+
+**GeminiError**: Custom error class
+- Extends Error
+- Includes error type and original error
+
+**GeminiErrorType**: Error categories
+- API_ERROR, VALIDATION_ERROR, NETWORK_ERROR
+- TIMEOUT_ERROR, RATE_LIMIT_ERROR, PARSING_ERROR
+- QUOTA_EXCEEDED, AUTHENTICATION, SAFETY
+- MODEL_NOT_FOUND, SERVER
+
+### Model Constants
+
+**GEMINI_MODELS**: All supported models
+- Text models (gemini-2.5-flash-lite, gemini-2.5-pro, etc.)
+- Image models (imagen-4.0-generate-001, etc.)
+- Video models (veo-3.1-fast-generate-preview, etc.)
+
+**DEFAULT_MODELS**: Default model selections
+- TEXT: gemini-2.5-flash-lite
+- TEXT_TO_IMAGE: imagen-4.0-generate-001
+- IMAGE_EDIT: gemini-2.5-flash-image
+- VIDEO_GENERATION: veo-3.1-fast-generate-preview
+
+## 🎓 Usage Patterns
+
+### Type Imports
+1. Import types from package
+2. Use for function parameters
+3. Define return types
+4. Handle typed errors
+5. Validate runtime data
+
+### Model Selection
+1. Import model constants
+2. Use helper functions for feature-based selection
+3. Get model ID for specific feature
+4. Use returned ID in service calls
+5. Avoid hardcoded model strings
+
+### Error Handling
+1. Catch error from operation
+2. Check if `instanceof GeminiError`
+3. Switch on error.type
+4. Handle each error type appropriately
+5. Provide user feedback
+
+### Configuration
+1. Create config object
+2. Use types for validation
+3. Specify model IDs from constants
+4. Include retry and timeout settings
+5. Initialize provider with config
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use `any` type to bypass typing
+- Hardcode model IDs
+- Ignore error types
+- Skip runtime validation
+- Use magic strings
+
+### Do
+- Use explicit type annotations
+- Import constants for model IDs
+- Check error types
+- Validate runtime data
+- Use helper functions
+- Define proper interfaces
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../AI_GUIDELINES.md)

package/src/domain/constants/README.md

@@ -0,0 +1,191 @@
+# Domain Constants
+
+Constant values and model catalogs for Gemini provider. Contains feature-based model mappings for image and video operations.
+
+## 📍 Import Path
+
+```
+import {
+  GEMINI_IMAGE_FEATURE_MODELS,
+  GEMINI_VIDEO_FEATURE_MODELS,
+  getGeminiImageFeatureModel,
+  getGeminiVideoFeatureModel,
+  getAllFeatureModels
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use constants to map features to appropriate models. Provides centralized model selection for image and video processing features.
+
+**When to use:**
+- Get model ID for specific feature
+- Display available features in UI
+- Validate feature requests
+- Map user features to models
+- List supported operations
+
+## 📌 Strategy
+
+Features map to specific models. This system:
+- Provides constant feature-to-model mappings
+- Centralizes model configuration
+- Enables feature validation
+- Simplifies model selection
+- Maintains consistency across codebase
+
+**Key Decision**: Use feature constants instead of hardcoded model IDs. This enables centralized model management and updates.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use constants for model selection
+- **SHOULD** validate feature before use
+- **MUST** handle unknown features gracefully
+- **SHOULD** check model compatibility
+- **MUST NOT** hardcode model IDs
+
+### Feature Selection Rules
+- **MUST** select appropriate model for feature
+- **SHOULD** use getter functions
+- **MUST** validate feature type
+- **SHOULD** handle missing features
+- **MUST** return valid model IDs
+
+### Validation Rules
+- **SHOULD** validate feature strings
+- **MUST** check feature exists
+- **SHOULD** provide fallback models
+- **MUST** throw on invalid features
+- **SHOULD** log validation failures
+
+### Maintenance Rules
+- **MUST** update constants when models change
+- **SHOULD** document model changes
+- **MUST** maintain backward compatibility
+- **SHOULD** test feature mappings
+- **MUST** update documentation
+
+## 🤖 AI Agent Guidelines
+
+### When Getting Model for Feature
+1. **CALL** getGeminiImageFeatureModel() or getGeminiVideoFeatureModel()
+2. **VALIDATE** feature exists
+3. **RETURN** model ID
+4. **HANDLE** unknown features
+5. **LOG** model selection
+
+### When Listing Features
+1. **CALL** getAllFeatureModels()
+2. **FILTER** by feature type
+3. **DISPLAY** to user
+4. **GROUP** by category
+5. **HANDLE** empty lists
+
+### When Validating Features
+1. **CHECK** feature in constants
+2. **VERIFY** model exists
+3. **RETURN** validation result
+4. **PROVIDE** error messages
+5. **SUGGEST** alternatives
+
+### Code Style Rules
+- **USE** constants instead of hardcoded values
+- **IMPORT** specific constants needed
+- **VALIDATE** feature inputs
+- **HANDLE** edge cases
+- **DOCUMENT** custom features
+
+## 📦 Available Constants
+
+### Image Feature Models
+
+**Refer to**: [`feature-models.constants.ts`](./feature-models.constants.ts)
+
+**Features:**
+- `upscale` - Image upscaling
+- `photo-restore` - Photo restoration
+- `face-swap` - Face swapping
+- `anime-selfie` - Anime style transformation
+- `remove-background` - Background removal
+- `remove-object` - Object removal
+- `hd-touch-up` - HD enhancement
+- `replace-background` - Background replacement
+
+**Model**: All use `gemini-2.0-flash-exp`
+
+### Video Feature Models
+
+**Refer to**: [`feature-models.constants.ts`](./feature-models.constants.ts)
+
+**Features:**
+- `ai-hug` - AI hugging effect
+- `ai-kiss` - AI kissing effect
+
+**Model**: All use `gemini-2.0-flash-exp`
+
+## 🔗 Related Modules
+
+- **Domain Entities**: [`../entities/README.md`](../entities/README.md)
+- **Domain README**: [`../README.md`](../README.md)
+- **Model Selector**: [`../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md`](../../infrastructure/services/FEATURE_MODEL_SELECTOR_SERVICE.md)
+
+## 📋 Feature Reference
+
+### Image Editing Features
+- **upscale**: Enlarge image while maintaining quality
+- **photo-restore**: Restore old or damaged photos
+- **face-swap**: Swap faces between images
+- **anime-selfie**: Transform selfie to anime style
+- **remove-background**: Remove image background
+- **remove-object**: Remove specific objects from image
+- **hd-touch-up**: Enhance image quality to HD
+- **replace-background**: Replace image background
+
+### Video Features
+- **ai-hug**: Generate video of subjects hugging
+- **ai-kiss**: Generate video of subjects kissing
+
+## 🎓 Usage Patterns
+
+### Feature-Based Model Selection
+1. Determine feature type (image or video)
+2. Call appropriate getter function
+3. Get model ID for feature
+4. Use model in service call
+5. Handle unknown features
+
+### Feature Listing
+1. Call getAllFeatureModels()
+2. Iterate through feature list
+3. Group by category
+4. Display to user
+5. Handle feature selection
+
+### Feature Validation
+1. Check feature in constants
+2. Verify model mapping exists
+3. Validate feature type
+4. Return validation result
+5. Provide feedback
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Hardcode model IDs in application code
+- Use features without validation
+- Assume all features use same model
+- Skip feature existence checks
+- Use invalid feature strings
+
+### Do
+- Use constants for model selection
+- Validate features before use
+- Check model mappings
+- Handle unknown features gracefully
+- Update constants when models change
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)

package/src/domain/entities/README.md

@@ -0,0 +1,238 @@
+# Domain Entities
+
+Core data structures and type definitions for the Gemini provider. Contains all types required for API communication.
+
+## 📍 Import Path
+
+```
+import type {
+  GeminiConfig,
+  GeminiContent,
+  GeminiResponse,
+  GeminiImageGenerationResult,
+  VideoGenerationResult,
+  GeminiError,
+  GeminiErrorType
+} from '@umituz/react-native-ai-gemini-provider';
+```
+
+## 🎯 Purpose
+
+Use these types for type-safe integration with Gemini services. Provides TypeScript interfaces for all API operations.
+
+**When to use:**
+- Type-check API requests and responses
+- Define function signatures
+- Validate data structures
+- Understand API response formats
+- Handle typed errors
+
+## 📌 Strategy
+
+Strong typing prevents runtime errors. These types:
+- Define all API request/response structures
+- Provide type safety for operations
+- Enable autocomplete in IDEs
+- Document API contracts
+- Catch errors at compile time
+
+**Key Decision**: All types defined in domain layer have NO external dependencies. This keeps them pure and reusable.
+
+## ⚠️ Rules
+
+### Usage Rules
+- **MUST** use types from domain layer
+- **SHOULD** prefer type imports over value imports
+- **MUST** handle all error types
+- **SHOULD** use type guards for validation
+- **MUST NOT** use `any` type
+
+### Type Safety Rules
+- **MUST** define explicit return types
+- **SHOULD** use strict null checks
+- **MUST** validate runtime data
+- **SHOULD** use discriminated unions for errors
+- **MUST NOT** bypass type checking
+
+### Error Handling Rules
+- **MUST** catch and handle `GeminiError`
+- **SHOULD** check error types
+- **MUST** handle all error states
+- **SHOULD** provide type-safe error messages
+- **MUST NOT** ignore error types
+
+## 🤖 AI Agent Guidelines
+
+### When Modifying Types
+1. **READ** existing type definitions first
+2. **UNDERSTAND** type relationships
+3. **MAINTAIN** backward compatibility
+4. **UPDATE** all usages
+5. **ADD** tests for new types
+
+### When Adding New Types
+1. **CHECK** if similar type exists
+2. **FOLLOW** existing naming conventions
+3. **USE** consistent patterns
+4. **DOCUMENT** with JSDoc comments
+5. **EXPORT** from index files
+
+### When Fixing Type Bugs
+1. **IDENTIFY** root cause in type definition
+2. **FIX** with minimal changes
+3. **UPDATE** all dependent code
+4. **ADD** type tests
+5. **VERIFY** no breaking changes
+
+### Code Style Rules
+- **USE** explicit type annotations
+- **AVOID** `any` type
+- **PREFER** readonly where appropriate
+- **USE** discriminated unions
+- **DOCUMENT** complex types
+
+## 📦 Available Types
+
+### Configuration Types
+
+**GeminiConfig**: Client configuration
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Request/Response Types
+
+**GeminiContent**: API request content structure
+
+**GeminiResponse**: API response structure
+
+**GeminiCandidate**: Generated candidate results
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Image Types
+
+**GeminiImageGenerationResult**: Image generation result
+
+**GeminiImageInput**: Image input structure
+
+**Refer to**: [`gemini.types.ts`](./gemini.types.ts)
+
+### Video Types
+
+**VideoGenerationInput**: Video generation input
+
+**VideoGenerationResult**: Video generation result
+
+**VideoOperationStatus**: Operation status enum
+
+**Refer to**: [`video.types.ts`](./video.types.ts)
+
+### Error Types
+
+**GeminiError**: Custom error class
+
+**GeminiErrorType**: Error type enum
+
+**GeminiErrorInfo**: Error information interface
+
+**Refer to**: [`error.types.ts`](./error.types.ts)
+
+### Model Types
+
+**GeminiModel**: Model information
+
+**GeminiGenerationConfig**: Generation parameters
+
+**Refer to**: [`models.ts`](./models.ts)
+
+## 🔗 Related Modules
+
+- **Services**: [`../../infrastructure/services/README.md`](../../infrastructure/services/README.md)
+- **Error Utilities**: [`../../infrastructure/utils/ERROR_UTILITIES.md`](../../infrastructure/utils/ERROR_UTILITIES.md)
+- **Constants**: [`../constants/README.md`](../constants/README.md)
+
+## 📋 Type Reference
+
+### Finish Reason Types
+
+Values indicating why generation completed:
+- `STOP` - Normal completion
+- `MAX_TOKENS` - Token limit reached
+- `SAFETY` - Blocked by safety filter
+- `RECITATION` - Copyright detected
+- `OTHER` - Other reasons
+
+### Video Operation Status
+
+Operation lifecycle states:
+- `queued` - Waiting in queue
+- `processing` - Currently processing
+- `completed` - Successfully finished
+- `failed` - Operation failed
+
+### Error Categories
+
+Error types for handling:
+- `API_ERROR` - General API errors
+- `VALIDATION_ERROR` - Input validation errors
+- `NETWORK_ERROR` - Network connectivity issues
+- `TIMEOUT_ERROR` - Request timeout
+- `RATE_LIMIT_ERROR` - Too many requests
+- `PARSING_ERROR` - Response parsing failures
+- `QUOTA_EXCEEDED` - API quota exceeded
+- `AUTHENTICATION` - Invalid credentials
+- `SAFETY` - Content safety violations
+- `MODEL_NOT_FOUND` - Invalid model ID
+- `SERVER` - Server errors (5xx)
+
+## 🎓 Usage Patterns
+
+### Type Imports
+1. Import types from package
+2. Use for function parameters
+3. Define return types
+4. Handle typed errors
+5. Validate runtime data
+
+### Error Type Checking
+1. Catch error from operation
+2. Check if `instanceof GeminiError`
+3. Switch on error.type
+4. Handle each error type appropriately
+5. Provide user feedback
+
+### Image Type Usage
+1. Use `GeminiImageInput` for image data
+2. Provide base64-encoded images
+3. Specify MIME type
+4. Handle image generation results
+5. Extract image URL or base64
+
+### Video Type Usage
+1. Use `VideoGenerationInput` for requests
+2. Monitor `VideoOperationStatus`
+3. Handle progress updates
+4. Extract video URL when complete
+5. Handle errors appropriately
+
+## 🚨 Common Pitfalls
+
+### Don't
+- Use `any` type to bypass typing
+- Ignore error types
+- Skip type validation
+- Use hardcoded model IDs
+- Forget to handle all error states
+
+### Do
+- Use explicit type annotations
+- Check error types
+- Validate runtime data
+- Use type guards
+- Handle all finish reasons
+- Provide type-safe error messages
+
+---
+
+**Last Updated**: 2025-01-08
+**See Also**: [AI_GUIDELINES.md](../../../AI_GUIDELINES.md)