@umituz/react-native-design-system 4.23.100 → 4.23.101

package/src/media/infrastructure/services/CardMultimediaService.README.md

@@ -1,176 +0,0 @@
-# CardMultimediaService
-
-## Purpose
-Central service for managing all media operations in card-based applications, combining upload, generation, validation, and optimization capabilities through a singleton instance with card-specific media support.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMultimediaService`
-
-## Strategy
-- Provide unified interface for all card media operations
-- Coordinate upload, generation, validation, and optimization services
-- Maintain singleton pattern for resource efficiency
-- Support card-specific media requirements (front/back/both positions)
-- Simplify media management for card applications
-- Enable batch operations for card sets
-- Provide consistent API across all media operations
-- Handle card-specific metadata and associations
-
-## Forbidden
-- **DO NOT** create multiple service instances (use singleton only)
-- **DO NOT** call media operations without validation
-- **DO NOT** assume AI generation is always available
-- **DO NOT** ignore optimization recommendations
-- **DO NOT** bypass singleton pattern with direct service instantiation
-- **DO NOT** proceed without error handling for any operation
-- **DO NOT** mix card media with non-card media types
-- **DO NOT** assume all operations will succeed
-- **DO NOT** ignore card-specific position requirements
-
-## Rules
-1. MUST use getInstance() to retrieve service instance
-2. MUST NOT create new instances with constructor
-3. MUST maintain single instance across application lifecycle
-4. MUST validate media before upload operations
-5. MUST support CardMediaAttachment and CardMediaPosition types
-6. MUST handle position attribute (front/back/both) correctly
-7. MUST handle all operation failures gracefully
-8. MUST provide consistent interface through all methods
-9. MUST initialize all sub-services on first use
-10. MUST coordinate between sub-services for complex operations
-11. MUST handle asynchronous operations properly
-12. MUST return appropriate error messages for failures
-13. MUST support card-specific media constraints
-
-## AI Agent Guidelines
-
-When working with CardMultimediaService:
-
-1. **Singleton Pattern**: Always use getInstance(), never constructor
-2. **Validation First**: Validate before upload or generation
-3. **Position Awareness**: Always consider card position (front/back/both)
-4. **Operation Flow**: Follow validate -> upload/generate -> optimize -> store
-5. **Error Handling**: Handle errors at each step appropriately
-6. **Resource Management**: Rely on singleton for efficient resource use
-7. **Type Safety**: Use CardMediaAttachment and CardMediaPosition types
-8. **Card Context**: Maintain card-specific context throughout operations
-
-### Card Creation Workflow
-
-- **Step 1 - Get Instance**: `CardMultimediaService.getInstance()`
-- **Step 2 - Select File**: Pick file from device or camera
-- **Step 3 - Validate**: Run validation, check results
-- **Step 4 - Upload**: Upload if validation passes
-- **Step 5 - Set Position**: Assign position (front/back/both)
-- **Step 6 - Optimize** (Optional): Optimize if file is large
-- **Step 7 - Store**: Save attachment with card data
-- **Step 8 - Handle Errors**: Provide feedback at each step
-
-### Media Upload with Position
-
-- Use for user-selected media on card sides
-- Always validate before uploading
-- Set position based on card side (front/back/both)
-- Consider compression for large files
-- Store returned attachment with card
-- Handle upload failures with user feedback
-
-### AI Content Generation for Cards
-
-- Use for text-to-image or text-to-audio generation
-- Validate prompts before generation
-- Check credit/balance availability
-- Set position based on use case (front for questions, back for answers)
-- Handle generation failures gracefully
-- Store successful attachments with card
-
-### Position Management
-
-- **Front**: Media displayed on card front side
-  - Typically contains questions or prompts
-  - Often uses text-to-image generation
-  - May require higher quality
-
-- **Back**: Media displayed on card back side
-  - Typically contains answers or explanations
-  - Often uses text-to-audio generation
-  - Can be more compressed
-
-- **Both**: Media used on both sides
-  - Shared content between sides
-  - Less common but supported
-  - Maintain consistency across sides
-
-### Media Optimization for Cards
-
-- Use when file size impacts performance
-- Choose quality level based on position (front = higher, back = lower)
-- Consider card importance and frequency of use
-- Calculate expected size reduction
-- Preserve position through optimization
-- Update card with optimized media
-
-### Media Deletion for Cards
-
-- Verify media ownership before deletion
-- Check card associations and dependencies
-- Confirm deletion with user if needed
-- Delete from all storage locations
-- Update card references
-- Handle missing files gracefully
-
-### Batch Operations for Card Sets
-
-- For multiple cards, use same service instance
-- Process uploads/generations in sequence
-- Collect results before saving
-- Handle partial failures appropriately
-- Consider parallel operations for independent media
-- Track progress for user feedback
-- Maintain position consistency across cards
-
-### Error Handling Patterns
-
-- **Validation Errors**: Show to user, block upload
-- **Upload Errors**: Retry or allow alternative file
-- **Generation Errors**: Check credits, try different prompt
-- **Optimization Errors**: Continue with original media
-- **Deletion Errors**: Log error, notify user
-- **Position Errors**: Validate position before operations
-- **Network Errors**: Show connection message, allow retry
-
-### Card-Specific Considerations
-
-- **Front Media**: Often focal point, prioritize quality
-- **Back Media**: Secondary content, can be more compressed
-- **Both Position**: Ensure quality works for both sides
-- **Multiple Media**: Support multiple attachments per card
-- **Position Validation**: Validate media type compatibility with position
-- **Card Associations**: Maintain references between media and cards
-
-### Service Coordination
-
-The service automatically coordinates:
-- CardMediaUploadService handles file uploads
-- CardMediaGenerationService handles AI generation
-- CardMediaValidationService checks file validity
-- CardMediaOptimizerService handles compression
-- All services work together with card-specific requirements
-
-### Performance Considerations
-
-- Singleton reduces memory footprint
-- Single instance maintains state efficiently
-- Sub-services initialized once
-- All operations are asynchronous
-- Consider lazy loading for large card sets
-- Cache media URLs when possible
-- Optimize media based on card usage patterns
-
-## Dependencies
-- CardMediaUploadService for upload operations
-- CardMediaGenerationService for AI generation (including image-search)
-- CardMediaValidationService for validation
-- CardMediaOptimizerService for optimization
-- CardMediaAttachment type from domain layer
-- CardMediaPosition type for card-side placement

package/src/media/infrastructure/services/CardMultimediaService.ts

@@ -1,98 +0,0 @@
-/**
- * Card Multimedia Flashcard Service
- * Media attachments for flashcards - Main entry point
- */
-
-import type {
-  CardMediaAttachment,
-  CardMediaFile,
-  CardMediaGenerationRequest,
-  CardMediaGenerationResult,
-  CardMediaCompressionOptions,
-  CardMediaValidation,
-  CardMultimediaFlashcardService as ICardMultimediaFlashcardService,
-} from "../../domain/entities/CardMultimedia.types";
-import { CardMediaUploadService } from "./CardMediaUploadService";
-import { CardMediaGenerationService } from "./CardMediaGenerationService";
-import { CardMediaValidationService } from "./CardMediaValidationService";
-import { CardMediaOptimizerService } from "./CardMediaOptimizerService";
-
-export class CardMultimediaFlashcardService implements ICardMultimediaFlashcardService {
-  private static instance: CardMultimediaFlashcardService;
-  private uploadService: CardMediaUploadService;
-  private generationService: CardMediaGenerationService;
-  private validationService: CardMediaValidationService;
-  private optimizerService: CardMediaOptimizerService;
-
-  private constructor() {
-    this.uploadService = new CardMediaUploadService();
-    this.generationService = new CardMediaGenerationService();
-    this.validationService = new CardMediaValidationService();
-    this.optimizerService = new CardMediaOptimizerService();
-  }
-
-  static getInstance(): CardMultimediaFlashcardService {
-    if (!CardMultimediaFlashcardService.instance) {
-      CardMultimediaFlashcardService.instance =
-        new CardMultimediaFlashcardService();
-    }
-    return CardMultimediaFlashcardService.instance;
-  }
-
-  /**
-   * Upload media file with optional compression
-   */
-  async uploadMedia(
-    file: CardMediaFile,
-    options?: CardMediaCompressionOptions,
-  ): Promise<CardMediaAttachment> {
-    return this.uploadService.uploadMedia(file, options);
-  }
-
-  /**
-   * Generate media from AI (text-to-image, text-to-audio, etc.)
-   */
-  async generateMedia(
-    request: CardMediaGenerationRequest,
-  ): Promise<CardMediaGenerationResult> {
-    return this.generationService.generateMedia(request);
-  }
-
-  /**
-   * Validate media file before upload
-   */
-  async validateMedia(file: CardMediaFile): Promise<CardMediaValidation> {
-    return this.validationService.validateMedia(file);
-  }
-
-  /**
-   * Optimize media file
-   */
-  async optimizeMedia(
-    attachment: CardMediaAttachment,
-    options: CardMediaCompressionOptions,
-  ): Promise<CardMediaAttachment> {
-    return this.optimizerService.optimizeMedia(attachment, options);
-  }
-
-  /**
-   * Delete media attachment
-   */
-  async deleteMedia(attachmentId: string): Promise<void> {
-    return this.optimizerService.deleteMedia(attachmentId);
-  }
-
-  /**
-   * Get media URL
-   */
-  async getMediaUrl(attachmentId: string): Promise<string> {
-    return this.uploadService.getMediaUrl(attachmentId);
-  }
-
-  /**
-   * Download media to local storage
-   */
-  async downloadMedia(attachmentId: string): Promise<string> {
-    return this.uploadService.downloadMedia(attachmentId);
-  }
-}

package/src/media/infrastructure/services/MediaGenerationService.README.md

@@ -1,142 +0,0 @@
-# MediaGenerationService
-
-## Purpose
-Provides AI-powered media generation capabilities including text-to-image and text-to-audio generation with credit/balance management.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaGenerationService`
-
-## Strategy
-
-### Core Purpose
-- Generate images from text descriptions (text-to-image)
-- Generate audio from text (text-to-audio)
-- Support multiple result generation
-- Track processing time and performance
-- Manage generation costs/credits
-
-### Usage Scenarios
-- AI-generated visual content for cards
-- Text-to-speech conversion
-- Creative content generation
-- Localization and voice-over creation
-- Dynamic asset generation
-
-### Integration Points
-- AI-powered content creation workflows
-- Text-to-speech features
-- Automated asset generation
-- Creative assistance tools
-- Educational content generation
-
-## Forbidden
-
-### MUST NOT
-- Generate without sufficient credits/balance
-- Assume generation always succeeds
-- Generate inappropriate or harmful content
-- Ignore rate limiting or API constraints
-- Cache generated content without validation
-- Generate without user prompt input
-
-### MUST NEVER
-- Expose API keys or credentials
-- Allow unlimited free generation
-- Ignore generation failures
-- Bypass credit/balance checks
-- Generate without proper error handling
-- Assume instant generation results
-
-## Rules
-
-### Generation Operations
-- MUST validate prompt before generation
-- MUST check sufficient credits/balance
-- MUST handle generation failures
-- MUST track processing time
-- MUST return unique request ID
-- MUST respect result limits (maxResults)
-
-### Text-to-Image Generation
-- MUST support style options
-- MUST support aspect ratio options
-- MUST generate multiple results if requested
-- MUST validate image generation parameters
-- MUST handle generation timeouts
-
-### Text-to-Audio Generation
-- MUST support voice options
-- MUST support language selection
-- MUST support speed adjustment
-- MUST return audio duration
-- MUST validate audio parameters
-
-### Credit Management
-- MUST deduct credits per generation
-- MUST track credit usage in results
-- MUST validate credit availability
-- MUST prevent generation with insufficient credits
-- MUST report credits used in result
-
-### Return Values
-- MUST include success status
-- MUST include generated media attachments
-- MUST include credits used
-- MUST include processing time
-- MUST include unique request ID
-- MUST include error details on failure
-
-### Error Handling
-- MUST handle insufficient credits
-- MUST handle generation timeouts
-- MUST handle invalid prompts
-- MUST handle API failures
-- MUST provide meaningful error messages
-- MUST allow retry after appropriate delay
-
-## AI Agent Guidelines
-
-### When Implementing Generation Features
-1. Always validate prompt input
-2. Check credit/balance before generation
-3. Set appropriate timeouts
-4. Handle both success and failure cases
-5. Track and report processing metrics
-
-### When Working with Text-to-Image
-- Support common aspect ratios (16:9, 4:3, 1:1)
-- Provide style presets (realistic, artistic, etc.)
-- Limit max results to reasonable number
-- Validate image generation parameters
-
-### When Working with Text-to-Audio
-- Support common languages
-- Provide voice options (male, female)
-- Allow speed adjustment (0.5-2.0)
-- Return accurate duration
-
-### When Adding Features
-- Add new generation types with validation
-- Extend options without breaking compatibility
-- Add new credit tiers carefully
-- Support batch generation if needed
-- Add content filtering if required
-
-### When Refactoring
-- Keep generation API stable
-- Preserve credit calculation logic
-- Maintain request ID generation
-- Don't change result structure
-- Add deprecation warnings for breaking changes
-
-### Common Patterns to Follow
-- Validate prompt -> Check credits -> Generate -> Return result
-- Handle timeout -> Retry if appropriate -> Return error
-- Calculate credits -> Deduct -> Track usage
-- Always wrap in try-catch for unexpected errors
-- Provide user feedback for generation status
-
-## Dependencies
-
-- Domain types: MediaAttachment, MediaGenerationRequest, MediaGenerationResult, MediaType, MediaPosition from MultimediaFlashcardTypes
-- No external library dependencies (uses native APIs)

package/src/media/infrastructure/services/MediaOptimizerService.README.md

@@ -1,145 +0,0 @@
-# MediaOptimizerService
-
-## Purpose
-Optimizes and compresses media files to reduce file size while maintaining acceptable quality, and manages media deletion operations.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaOptimizerService`
-
-## Strategy
-
-### Core Purpose
-- Reduce media file size through compression
-- Maintain acceptable quality after optimization
-- Support quality and dimension constraints
-- Delete media from server and local storage
-- Generate optimized versions of existing media
-
-### Usage Scenarios
-- Pre-upload optimization
-- Storage cost reduction
-- Performance improvement
-- Bandwidth optimization
-- Media cleanup workflows
-
-### Integration Points
-- After upload, before storage
-- In media management workflows
-- Storage optimization processes
-- Media cleanup routines
-- Performance tuning operations
-
-## Forbidden
-
-### MUST NOT
-- Optimize media beyond usable quality
-- Delete media without proper authorization
-- Assume optimization always succeeds
-- Modify original media files
-- Ignore quality settings
-- Delete without confirmation in critical workflows
-
-### MUST NEVER
-- Optimize already optimized media repeatedly
-- Use quality below 0.3 without explicit request
-- Delete media without backup when required
-- Assume optimization is lossless
-- Ignore file size after optimization
-- Return different media ID after optimization
-
-## Rules
-
-### Optimization Operations
-- MUST accept media attachment and options
-- MUST preserve original media (create new version)
-- MUST return optimized media attachment
-- MUST maintain same media ID
-- MUST update file size accurately
-- MUST add optimization indicator to URL
-
-### Compression Options
-- MUST support quality adjustment (0-1)
-- MUST support max width constraint
-- MUST support max height constraint
-- MUST support format conversion
-- MUST validate compression parameters
-- MUST respect quality vs size tradeoff
-
-### Quality Levels
-- High quality (0.9-1.0): 10-20% size reduction
-- Medium quality (0.7-0.8): 30-50% size reduction
-- Low quality (0.5-0.6): 50-70% size reduction
-- Preview quality (0.3-0.4): 70-80% size reduction
-- MUST document quality tradeoffs
-
-### Deletion Operations
-- MUST accept media ID for deletion
-- MUST delete from both server and local storage
-- MUST handle non-existent media gracefully
-- MUST confirm deletion success
-- MUST be permanent and irreversible
-
-### Return Values
-- MUST preserve original media ID
-- MUST preserve media type
-- MUST update file size
-- MUST preserve MIME type
-- MUST preserve creation date
-- MUST update URL with optimization indicator
-
-### Error Handling
-- MUST handle optimization failures
-- MUST handle deletion failures
-- MUST handle invalid media IDs
-- MUST handle invalid compression options
-- MUST provide meaningful error messages
-- MUST allow retry on transient failures
-
-## AI Agent Guidelines
-
-### When Implementing Optimization
-1. Always validate compression options
-2. Calculate expected file size reduction
-3. Apply compression with specified quality
-4. Update metadata accurately
-5. Return optimized version with same ID
-
-### When Working with Quality Settings
-- Use 0.7-0.8 for general use (recommended)
-- Use 0.9-1.0 for high-quality requirements
-- Use 0.5-0.6 for previews and thumbnails
-- Avoid quality below 0.3 unless specifically needed
-- Consider content type when setting quality
-
-### When Performing Deletion
-- Confirm media ID exists before deletion
-- Handle deletion from both storage locations
-- Provide confirmation in critical workflows
-- Log deletion operations for audit
-- Handle non-existent media gracefully
-
-### When Adding Features
-- Add new compression formats carefully
-- Support new dimension constraints
-- Add batch optimization if needed
-- Maintain backward compatibility
-- Add optimization presets for common cases
-
-### When Refactoring
-- Keep optimization API stable
-- Preserve ID generation logic
-- Maintain URL structure
-- Don't change return value structure
-- Add deprecation warnings for breaking changes
-
-### Common Patterns to Follow
-- Receive attachment -> Validate options -> Optimize -> Return optimized
-- Calculate size -> Apply quality -> Update metadata -> Return
-- Receive ID -> Validate -> Delete -> Confirm
-- Always wrap in try-catch for unexpected errors
-- Provide user feedback for optimization progress
-
-## Dependencies
-
-- Domain types: MediaAttachment, MediaCompressionOptions from MultimediaFlashcardTypes
-- No external library dependencies (uses native APIs)

package/src/media/infrastructure/services/MediaPickerService.README.md

@@ -1,106 +0,0 @@
-# MediaPickerService
-
-## Purpose
-Provides image and video selection functionality from device camera and gallery, including permission management and media type filtering.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaPickerService`
-
-## Strategy
-
-### Core Purpose
-- Enable users to select media from device gallery or capture using camera
-- Support single and multiple media selection
-- Handle platform-specific permission requirements
-- Provide customizable selection options
-
-### Usage Scenarios
-- User profile picture selection
-- Content creation workflows
-- Multi-image selection for galleries
-- Video recording for user-generated content
-- Mixed media selection (images and videos)
-
-### Integration Points
-- Forms requiring media attachments
-- Content management systems
-- Social media features
-- Document upload workflows
-
-## Forbidden
-
-### MUST NOT
-- Bypass permission checks or force camera/gallery access
-- Assume permissions are always granted
-- Hardcode file paths or URIs
-- Access media without explicit user action
-- Automatically launch camera without user consent
-- Store selected media URIs in permanent storage without validation
-
-### MUST NEVER
-- Allow infinite selection limits without boundaries
-- Use base64 conversion by default (performance impact)
-- Assume all devices support the same media types
-- Ignore permission denial states
-- Access camera roll without proper permissions
-
-## Rules
-
-### Permission Management
-- MUST request camera permission before launching camera
-- MUST request media library permission before accessing gallery
-- MUST handle permission denial gracefully
-- MUST check permission status before operations
-- MUST provide clear error messages when permissions are denied
-
-### Media Selection
-- MUST respect selection limits
-- MUST validate selected media before processing
-- MUST handle user cancellation (canceled: true)
-- MUST support both single and multiple selection modes
-- MUST filter media types appropriately
-
-### Platform Considerations
-- MUST handle iOS and Android permission differences
-- MUST account for platform-specific media type restrictions
-- MUST test on both platforms for compatibility
-- MUST handle aspect ratio options correctly (only works with allowsEditing: true)
-
-### Performance
-- MUST avoid base64 conversion unless explicitly required
-- MUST set reasonable quality defaults
-- MUST handle large media files appropriately
-- MUST provide loading states during selection
-
-## AI Agent Guidelines
-
-### When Implementing Media Selection
-1. Always check permissions before launching picker
-2. Handle both success (canceled: false) and cancellation (canceled: true)
-3. Validate returned assets array exists and has items
-4. Consider media type (image vs video) for different handling
-5. Use appropriate quality settings based on use case
-
-### When Adding Features
-- Add new permission types only if required by new functionality
-- Extend options interface without breaking existing functionality
-- Maintain backward compatibility with existing selection methods
-- Add error handling for new edge cases
-
-### When Refactoring
-- Keep public API stable
-- Preserve permission handling logic
-- Maintain platform-specific behavior differences
-- Don't remove existing selection methods without deprecation
-
-### Common Patterns to Follow
-- Request permission -> Check status -> Launch picker
-- Handle result -> Validate -> Return or process
-- Always wrap in try-catch for unexpected errors
-- Provide user feedback for permission states
-
-## Dependencies
-
-- Domain types: MediaPickerOptions, MediaPickerResult, CameraOptions, MediaType, MediaLibraryPermission, MEDIA_CONSTANTS from Media
-- External libraries: expo-image-picker
-- Internal utilities: mediaPickerMappers (mapMediaType, mapPermissionStatus, mapPickerResult)