@umituz/react-native-design-system 2.8.8 → 2.8.9

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

@@ -0,0 +1,134 @@
+# CardMediaValidationService
+
+## Purpose
+Service that validates flashcard media files before upload, checking file size, type, and media-specific properties with detailed error, warning, and recommendation reporting.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMediaValidationService`
+
+## Strategy
+- Validate media files before upload operations
+- Check file size against maximum limits (50 MB hard limit)
+- Validate file type compatibility (image, audio, video)
+- Provide media-specific warnings (large images, long videos)
+- Generate actionable recommendations for optimization
+- Return structured validation results with errors, warnings, and recommendations
+- Support asynchronous validation operations
+- Format file sizes in human-readable format
+
+## Forbidden
+- **DO NOT** upload files with validation errors
+- **DO NOT** ignore validation warnings about performance impact
+- **DO NOT** bypass validation for any media upload
+- **DO NOT** allow unsupported file types
+- **DO NOT** proceed when file size exceeds maximum
+- **DO NOT** suppress error messages
+- **DO NOT** assume all validations will pass
+- **DO NOT** skip validation for "trusted" sources
+
+## Rules
+1. Maximum file size is 50 MB (hard error)
+2. Large file warning is triggered at 10 MB+
+3. Very large image warning is triggered at 5 MB+
+4. Long audio/video warning is triggered at 5 minutes (300 seconds)
+5. Supported image types: image/jpeg, image/png, image/webp
+6. Supported audio types: audio/mp3, audio/wav, audio/m4a
+7. Supported video types: video/mp4, video/mov
+8. Unsupported file types must return error
+9. Validation must be asynchronous operation
+10. Warnings must not block upload but inform user
+11. Recommendations must provide actionable improvement steps
+12. File size must be checked in bytes
+13. Validation result must include isValid boolean flag
+
+## AI Agent Guidelines
+
+When working with CardMediaValidationService:
+
+1. **Always Validate**: Never upload without validation first
+2. **Check isValid**: Block upload if isValid is false
+3. **Handle Errors**: Show error messages to user and prevent upload
+4. **Show Warnings**: Display warnings but allow user to proceed
+5. **Provide Recommendations**: Show optimization suggestions
+6. **Media-Specific Checks**: Apply different rules for each media type
+7. **User Communication**: Present validation results clearly
+
+### Validation Workflow
+
+- **Step 1 - Validate**: Run validation before any upload
+- **Step 2 - Check Errors**: If errors exist, show and stop
+- **Step 3 - Show Warnings**: Display warnings, ask user to confirm
+- **Step 4 - Show Recommendations**: Present optimization suggestions
+- **Step 5 - Proceed or Stop**: Allow upload if valid, stop if invalid
+
+### Error Handling
+
+- **File Size Errors**:
+  - "File size (X MB) exceeds maximum allowed size (50 MB)"
+  - Must prevent upload operation
+  - User must reduce file size
+
+- **File Type Errors**:
+  - "Unsupported file type: [type]"
+  - Must prevent upload operation
+  - User must convert to supported format
+
+### Warning Handling
+
+- **Large File Warning** (10+ MB):
+  - "Large file size may impact performance"
+  - Allow upload with user confirmation
+  - Recommend compression
+
+- **Large Image Warning** (5+ MB):
+  - "Very large image may cause performance issues"
+  - Allow upload with user confirmation
+  - Recommend resizing to under 5 MB
+
+- **Long Content Warning** (5+ minutes):
+  - "Long audio/video files may impact app performance"
+  - Allow upload with user confirmation
+  - Recommend trimming to under 5 minutes
+
+### Recommendation Patterns
+
+- **For Large Files**: "Consider compressing file"
+- **For Large Images**: "Consider resizing image to under 5MB"
+- **For Long Content**: "Consider trimming to under 5 minutes"
+- **For Format**: Recommend MP3 for audio, MP4 for video
+- **For Resolution**: Recommend 1920x1080 or smaller
+
+### Media-Specific Validation
+
+- **Images**:
+  - Check MIME type against supported formats
+  - Warn if size > 5 MB
+  - Recommend JPEG for better compression
+  - Consider resolution checks (optional)
+
+- **Audio**:
+  - Check MIME type against supported formats
+  - Warn if duration > 5 minutes
+  - Recommend MP3 format
+  - Consider bitrate checks (optional)
+
+- **Video**:
+  - Check MIME type against supported formats
+  - Warn if duration > 5 minutes
+  - Recommend MP4 format
+  - Consider resolution checks (optional)
+
+### User Communication
+
+- Display errors prominently (block upload)
+- Show warnings with clear impact explanation
+- Present recommendations as actionable steps
+- Allow user to decide on warnings
+- Format file sizes in MB/KB for readability
+- Group messages by severity (errors, warnings, recommendations)
+
+## Dependencies
+- CardMediaValidation type for validation results
+- File size constants for limits
+- MIME type validation utilities
+- Media type detection helpers

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

@@ -0,0 +1,81 @@
+/**
+ * Card Media Validation Service
+ * Handles media file validation before upload
+ */
+
+import { formatFileSize } from "../utils/mediaHelpers";
+import type { CardMediaValidation } from "../../domain/entities/CardMultimedia.types";
+import { getMediaDuration } from "../utils/mediaHelpers";
+
+export class CardMediaValidationService {
+  /**
+   * Validate media file before upload
+   */
+  async validateMedia(file: any): Promise<CardMediaValidation> {
+    try {
+      const errors: string[] = [];
+      const warnings: string[] = [];
+      const recommendations: string[] = [];
+
+      // File size validation
+      const maxSize = 50 * 1024 * 1024; // 50MB
+      if (file.size > maxSize) {
+        errors.push(
+          `File size (${formatFileSize(file.size)}) exceeds maximum allowed size (${formatFileSize(maxSize)})`,
+        );
+      } else if (file.size > 10 * 1024 * 1024) {
+        // 10MB
+        warnings.push(`Large file size may impact performance`);
+        recommendations.push("Consider compressing file");
+      }
+
+      // File type validation
+      const supportedTypes = [
+        "image/jpeg",
+        "image/png",
+        "image/webp",
+        "audio/mp3",
+        "audio/wav",
+        "audio/m4a",
+        "video/mp4",
+        "video/mov",
+      ];
+
+      if (!supportedTypes.includes(file.type)) {
+        errors.push(`Unsupported file type: ${file.type}`);
+      }
+
+      // Media-specific validations
+      if (file.type.startsWith("image/")) {
+        if (file.size > 5 * 1024 * 1024) {
+          // 5MB for images
+          warnings.push("Very large image may cause performance issues");
+          recommendations.push("Consider resizing image to under 5MB");
+        }
+      }
+
+      if (file.type.startsWith("audio/") || file.type.startsWith("video/")) {
+        const duration = await getMediaDuration(file);
+        if (duration && duration > 300) {
+          // 5 minutes
+          warnings.push("Long audio/video files may impact app performance");
+          recommendations.push("Consider trimming to under 5 minutes");
+        }
+      }
+
+      return {
+        isValid: errors.length === 0,
+        errors,
+        warnings,
+        recommendations,
+      };
+    } catch (error) {
+      return {
+        isValid: false,
+        errors: [error instanceof Error ? error.message : "Validation failed"],
+        warnings: [],
+        recommendations: [],
+      };
+    }
+  }
+}

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

@@ -0,0 +1,176 @@
+# 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

@@ -0,0 +1,97 @@
+/**
+ * Card Multimedia Flashcard Service
+ * Media attachments for flashcards - Main entry point
+ */
+
+import type {
+  CardMediaAttachment,
+  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: any,
+    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: any): 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

@@ -0,0 +1,142 @@
+# 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)