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

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

@@ -0,0 +1,123 @@
+# CardMediaUploadService
+
+## Purpose
+Service that handles media file upload, download, and URL management for flashcard applications, with support for compression and automatic thumbnail generation.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMediaUploadService`
+
+## Strategy
+- Upload media files to server storage with unique identifiers
+- Support compression options during upload (quality, dimensions, format)
+- Generate thumbnails automatically for uploaded media
+- Download media from server to local storage
+- Retrieve and manage media URLs
+- Calculate duration for audio/video files
+- Return card-compatible media attachments with position support
+- Handle all media types (image, video, audio) with automatic type detection
+
+## Forbidden
+- **DO NOT** upload files without validation
+- **DO NOT** bypass file size limits
+- **DO NOT** upload unsupported file types
+- **DO NOT** ignore upload failures
+- **DO NOT** assume all uploads will succeed
+- **DO NOT** overwrite existing media without verification
+- **DO NOT** proceed without error handling for network issues
+- **DO NOT** download media without checking URL validity
+
+## Rules
+1. All uploads must include valid file metadata (name, type, size, uri)
+2. Compression options are optional but recommended for large files
+3. Quality must be between 0-1 when specified
+4. Max dimensions must be positive integers when specified
+5. Supported formats are jpeg and png for compression
+6. All attachments receive unique IDs automatically
+7. Position defaults to 'both' for uploaded media
+8. isDownloaded defaults to true for uploads
+9. Thumbnails are generated automatically for visual content
+10. Audio/video duration is calculated automatically
+11. File type is determined automatically from MIME type
+12. Upload operations must handle network failures gracefully
+13. Download operations must validate URL before processing
+
+## AI Agent Guidelines
+
+When working with CardMediaUploadService:
+
+1. **Pre-upload Validation**: Always validate files before upload attempts
+2. **Compression Strategy**: Apply compression for files larger than 5MB
+3. **Type Detection**: Rely on automatic type detection from MIME type
+4. **Error Handling**: Handle network timeouts and connection failures
+5. **Position Assignment**: Set correct position (front/back/both) for card use
+6. **Thumbnail Usage**: Use thumbnails for previews to save bandwidth
+7. **Duration Handling**: Use calculated duration for audio/video scheduling
+
+### Upload Guidelines
+
+- **Before Upload**:
+  - Validate file size and type
+  - Consider compression for large files
+  - Check network connectivity
+  - Prepare error handling
+
+- **During Upload**:
+  - Monitor for failures
+  - Handle network errors
+  - Store attachment information
+  - Track upload progress
+
+- **After Upload**:
+  - Verify upload success
+  - Store attachment ID and URL
+  - Set position for card use
+  - Consider optimization if needed
+
+### Compression Options
+
+- **Quality**: 0.9 (high), 0.7 (medium/recommended), 0.5 (low)
+- **Max Dimensions**: 1920x1080 (recommended), 1280x720 (smaller)
+- **Format**: jpeg (smaller size), png (better quality)
+- Apply compression when file size > 5MB for images
+- Use quality 0.7 for balance of size and quality
+
+### Media Type Detection
+
+- **Image**: MIME types starting with 'image/'
+  - Supported: image/jpeg, image/png, image/webp
+- **Audio**: MIME types starting with 'audio/'
+  - Supported: audio/mp3, audio/wav, audio/m4a
+- **Video**: MIME types starting with 'video/'
+  - Supported: video/mp4, video/mov
+
+### Download Guidelines
+
+- Validate media URL before download
+- Handle missing files gracefully
+- Use local path for offline access
+- Check isDownloaded status before re-downloading
+- Manage local storage space
+
+### Error Handling Patterns
+
+- Handle network errors: timeout, connection refused
+- Handle file errors: invalid format, corrupted file
+- Handle server errors: 500, 503, insufficient storage
+- Handle validation errors: size exceeded, unsupported type
+- Always provide fallback behavior for failed uploads
+
+### Performance Considerations
+
+- Upload operations are simulated (2 seconds delay)
+- Compress before upload to reduce transfer time
+- Use thumbnails for previews instead of full media
+- Batch uploads when possible for multiple files
+- Consider lazy loading for card media
+
+## Dependencies
+- CardMediaAttachment type from domain layer
+- CardMediaCompressionOptions type for compression settings
+- getCardMediaType helper for type detection
+- getMediaDuration helper for duration calculation
+- generateThumbnail helper for thumbnail creation
+- Upload API endpoints (simulated in development)

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

@@ -0,0 +1,67 @@
+/**
+ * Card Media Upload Service
+ * Handles media upload, download, and URL operations
+ */
+
+declare var __DEV__: boolean;
+
+import type {
+  CardMediaAttachment,
+  CardMediaCompressionOptions,
+} from "../../domain/entities/CardMultimedia.types";
+import {
+  generateThumbnail,
+  getCardMediaType,
+  getMediaDuration,
+} from "../utils/mediaHelpers";
+
+export class CardMediaUploadService {
+  /**
+   * Upload media file with optional compression
+   */
+  async uploadMedia(
+    file: any,
+    _options?: CardMediaCompressionOptions,
+  ): Promise<CardMediaAttachment> {
+    try {
+      // Simulate upload process
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      const attachment: CardMediaAttachment = {
+        id: `card_media_${Date.now()}`,
+        type: getCardMediaType(file.type),
+        position: "both",
+        url: `https://storage.example.com/media/${Date.now()}_${file.name}`,
+        filename: file.name,
+        fileSize: file.size || 100000,
+        mimeType: file.type,
+        duration: await getMediaDuration(file),
+        thumbnailUrl: generateThumbnail(file),
+        caption: "",
+        isDownloaded: true,
+        createdAt: new Date().toISOString(),
+      };
+
+      return attachment;
+    } catch (error) {
+      throw new Error(`Failed to upload media: ${error}`);
+    }
+  }
+
+  /**
+   * Get media URL
+   */
+  async getMediaUrl(attachmentId: string): Promise<string> {
+    return `https://storage.example.com/media/${attachmentId}`;
+  }
+
+  /**
+   * Download media to local storage
+   */
+  async downloadMedia(attachmentId: string): Promise<string> {
+    if (__DEV__) {
+      console.log(`[CardMediaUploadService] Downloading media: ${attachmentId}`);
+    }
+    return `/local/storage/${attachmentId}`;
+  }
+}

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);
+  }
+}