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

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

@@ -0,0 +1,142 @@
+# MultimediaFlashcardService
+
+## Purpose
+Main service that manages all media operations for media-enabled flashcards from a single point, combining upload, generation, validation, and optimization capabilities through a singleton instance.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MultimediaFlashcardService`
+
+## Strategy
+- Provide unified interface for all flashcard media operations
+- Coordinate upload, generation, validation, and optimization services
+- Maintain singleton pattern for resource efficiency
+- Simplify media management for flashcard applications
+- Support general flashcard media requirements
+- Enable batch operations for card sets
+- Provide consistent API across all media operations
+- Reduce complexity by exposing single service instance
+
+## 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 flashcard media with other media types
+- **DO NOT** assume all operations will succeed
+
+## 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 handle all operation failures gracefully
+6. MUST support MediaAttachment and MediaPosition types
+7. MUST provide consistent interface through all methods
+8. MUST initialize all sub-services on first use
+9. MUST coordinate between sub-services for complex operations
+10. MUST handle asynchronous operations properly
+11. MUST return appropriate error messages for failures
+
+## AI Agent Guidelines
+
+When working with MultimediaFlashcardService:
+
+1. **Singleton Pattern**: Always use getInstance(), never constructor
+2. **Validation First**: Validate before upload or generation
+3. **Operation Flow**: Follow validate -> upload/generate -> optimize -> store
+4. **Error Handling**: Handle errors at each step appropriately
+5. **Resource Management**: Rely on singleton for efficient resource use
+6. **Type Safety**: Use MediaAttachment and MediaPosition types
+7. **Service Coordination**: Let service coordinate sub-operations
+
+### Flashcard Creation Workflow
+
+- **Step 1 - Get Instance**: `MultimediaFlashcardService.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 - Optimize** (Optional): Optimize if file is large
+- **Step 6 - Store**: Save attachment with flashcard data
+- **Step 7 - Handle Errors**: Provide feedback at each step
+
+### Media Upload Workflow
+
+- Use for user-selected media (images, audio, video)
+- Always validate before uploading
+- Consider compression for large files
+- Set appropriate position if applicable
+- Store returned attachment with flashcard
+- Handle upload failures with user feedback
+
+### AI Content Generation Workflow
+
+- Use for text-to-image or text-to-audio generation
+- Validate prompts before generation
+- Check credit/balance availability
+- Set appropriate options (language, voice, style)
+- Handle generation failures gracefully
+- Store successful attachments with flashcard
+
+### Media Optimization Workflow
+
+- Use when file size impacts performance
+- Choose quality level based on use case
+- Consider flashcard importance (front/back)
+- Calculate expected size reduction
+- Preserve attachments through optimization
+- Update flashcard with optimized media
+
+### Media Deletion Workflow
+
+- Verify media ownership before deletion
+- Check flashcard associations
+- Confirm deletion with user if needed
+- Delete from all storage locations
+- Update flashcard references
+- Handle missing files gracefully
+
+### Batch Operations
+
+- For multiple flashcards, 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
+
+### 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
+- **Network Errors**: Show connection message, allow retry
+
+### Service Coordination
+
+The service automatically coordinates:
+- UploadService handles file uploads
+- GenerationService handles AI generation
+- ValidationService checks file validity
+- OptimizerService handles compression
+- All services work together seamlessly
+
+### 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
+
+## Dependencies
+- MediaUploadService for upload operations
+- MediaGenerationService for AI generation
+- MediaValidationService for validation
+- MediaOptimizerService for optimization
+- MediaAttachment type from domain layer
+- MediaPosition type for media placement

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

@@ -0,0 +1,95 @@
+/**
+ * Multimedia Flashcard Service
+ * Media attachments for flashcards - Main entry point
+ */
+
+import type {
+  MediaAttachment,
+  MediaGenerationRequest,
+  MediaGenerationResult,
+  MediaCompressionOptions,
+  MediaValidation,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+import { MediaUploadService } from "./MediaUploadService";
+import { MediaGenerationService } from "./MediaGenerationService";
+import { MediaValidationService } from "./MediaValidationService";
+import { MediaOptimizerService } from "./MediaOptimizerService";
+
+export class MultimediaFlashcardService {
+  private static instance: MultimediaFlashcardService;
+  private uploadService: MediaUploadService;
+  private generationService: MediaGenerationService;
+  private validationService: MediaValidationService;
+  private optimizerService: MediaOptimizerService;
+
+  private constructor() {
+    this.uploadService = new MediaUploadService();
+    this.generationService = new MediaGenerationService();
+    this.validationService = new MediaValidationService();
+    this.optimizerService = new MediaOptimizerService();
+  }
+
+  static getInstance(): MultimediaFlashcardService {
+    if (!MultimediaFlashcardService.instance) {
+      MultimediaFlashcardService.instance = new MultimediaFlashcardService();
+    }
+    return MultimediaFlashcardService.instance;
+  }
+
+  /**
+   * Upload media file with optional compression
+   */
+  async uploadMedia(
+    file: any,
+    options?: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    return this.uploadService.uploadMedia(file, options);
+  }
+
+  /**
+   * Generate media from AI (text-to-image, text-to-audio, etc.)
+   */
+  async generateMedia(
+    request: MediaGenerationRequest,
+  ): Promise<MediaGenerationResult> {
+    return this.generationService.generateMedia(request);
+  }
+
+  /**
+   * Validate media file before upload
+   */
+  async validateMedia(file: any): Promise<MediaValidation> {
+    return this.validationService.validateMedia(file);
+  }
+
+  /**
+   * Optimize media file
+   */
+  async optimizeMedia(
+    attachment: MediaAttachment,
+    options: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    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/utils/mediaHelpers.README.md

@@ -0,0 +1,96 @@
+# Media Helper Utilities
+
+## Purpose
+Core utility functions for media type detection, duration calculation, thumbnail generation, and file size operations.
+
+## File Location
+`src/infrastructure/utils/mediaHelpers.ts`
+
+## Strategy
+- Provide pure utility functions for common media operations
+- Enable media type classification from MIME types
+- Support file size calculations and formatting
+- Generate thumbnails for video files
+- Extract metadata from media collections
+- Maintain framework-agnostic approach where possible
+
+## Forbidden
+- **DO NOT** add business logic to utility functions
+- **DO NOT** make network calls or API requests
+- **DO NOT** modify input parameters (pure functions)
+- **DO NOT** store state or cache results globally
+- **DO NOT** depend on React or UI frameworks
+- **DO NOT** throw exceptions without clear error messages
+- **DO NOT** use locale-specific string formatting
+
+## Rules
+1. All functions must be pure (same input = same output)
+2. File size calculations must use bytes as the base unit
+3. Media type detection must use MIME type patterns
+4. Duration calculation must return seconds (or undefined for non-audio/video)
+5. Thumbnail generation must only return URLs for video files
+6. Type extraction must remove duplicates and preserve order
+7. Size formatting must use appropriate units (Bytes/KB/MB/GB)
+8. All functions must handle edge cases (empty arrays, null values)
+9. Must support both CardMediaAttachment and MediaAttachment types
+10. Must return fallback values for invalid inputs
+
+## AI Agent Guidelines
+
+When working with media helper utilities:
+
+1. **Type Detection**: Always use `getCardMediaType()` for consistent type classification from MIME types
+2. **Size Calculations**: Use `calculateTotalSize()` for aggregating file sizes, never sum manually
+3. **Duration Handling**: Check for undefined return value from `getMediaDuration()` for non-audio/video files
+4. **Thumbnail Generation**: Only videos return thumbnail URLs; images return undefined
+5. **Type Extraction**: Use `extractMediaTypes()` to get unique media types from collections
+6. **Size Formatting**: Always use `formatFileSize()` for user-facing size displays
+7. **Null Safety**: Always handle null/undefined returns appropriately
+8. **Collection Operations**: Use provided utilities instead of manual array operations
+
+### Media Type Classification
+
+- **Supported Types**: "image", "audio", "video"
+- **Detection Method**: MIME type pattern matching
+- **Default Behavior**: Unknown types default to "image"
+- **Common Patterns**:
+  - Images: image/jpeg, image/png, image/gif, image/webp
+  - Audio: audio/mp3, audio/wav, audio/mpeg, audio/aac
+  - Video: video/mp4, video/quicktime, video/x-msvideo
+
+### File Size Operations
+
+1. **Aggregation**: `calculateTotalSize()` - Sum all file sizes in bytes
+2. **Formatting**: `formatFileSize()` - Convert bytes to readable format
+3. **Unit Selection**: Automatically chooses appropriate unit (Bytes/KB/MB/GB)
+4. **Rounding**: Rounds to 2 decimal places for KB and above
+
+### Duration and Metadata
+
+1. **Duration**: Returns seconds for audio/video, undefined for images
+2. **Thumbnails**: Only generated for video files using external service
+3. **Type Extraction**: Returns unique types in order of appearance
+4. **Media Support**: Works with both CardMediaAttachment and MediaAttachment
+
+### Error Handling
+
+1. Handle undefined returns from `getMediaDuration()` for images
+2. Handle undefined returns from `generateThumbnail()` for non-videos
+3. Validate MIME type strings before type detection
+4. Handle empty arrays in collection operations
+5. Always check for null/undefined file objects
+
+### Usage Patterns
+
+1. **Media Analysis**: Combine multiple utilities for comprehensive file analysis
+2. **Validation**: Use type detection and size calculation for pre-upload validation
+3. **Statistics**: Aggregate collection data using type extraction and size calculation
+4. **Display**: Format sizes for user interfaces using formatFileSize
+5. **Filtering**: Use extracted types for conditional logic and filtering
+
+## Dependencies
+
+- Domain layer types (MediaAttachment, CardMediaAttachment)
+- No external libraries
+- No framework dependencies
+- Pure TypeScript/JavaScript utilities

package/src/media/infrastructure/utils/mediaHelpers.ts

@@ -0,0 +1,82 @@
+/**
+ * Media Helper Utilities
+ * Shared helper functions for media operations
+ */
+
+import type {
+  CardMediaAttachment,
+  CardMediaType,
+} from "../../domain/entities/CardMultimedia.types";
+import type { MediaAttachment } from "../../domain/entities/MultimediaFlashcardTypes";
+
+/**
+ * Get media type from MIME type for CardMedia
+ */
+export const getCardMediaType = (mimeType: string): CardMediaType => {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "image";
+};
+
+/**
+ * Get media type from MIME type for Media
+ */
+export const getMediaType = (mimeType: string): "image" | "audio" | "video" => {
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("video/")) return "video";
+  return "image";
+};
+
+/**
+ * Get media duration for audio/video files
+ */
+export const getMediaDuration = async (
+  file: any
+): Promise<number | undefined> => {
+  if (file.type.startsWith("audio/") || file.type.startsWith("video/")) {
+    return Math.floor(Math.random() * 60) + 10;
+  }
+  return undefined;
+};
+
+/**
+ * Generate thumbnail URL for video files
+ */
+export const generateThumbnail = (file: any): string | undefined => {
+  if (file.type.startsWith("video/")) {
+    return `https://picsum.photos/200/150?random=${Date.now()}`;
+  }
+  return undefined;
+};
+
+/**
+ * Extract unique media types from attachments
+ */
+export const extractMediaTypes = (
+  media: CardMediaAttachment[] | MediaAttachment[]
+): ("image" | "audio" | "video")[] => {
+  const types: Set<string> = new Set();
+  media.forEach((m) => types.add(m.type));
+  return Array.from(types) as ("image" | "audio" | "video")[];
+};
+
+/**
+ * Calculate total file size of media attachments
+ */
+export const calculateTotalSize = (
+  media: CardMediaAttachment[] | MediaAttachment[]
+): number => {
+  return media.reduce((total, m) => total + m.fileSize, 0);
+};
+
+/**
+ * Format bytes to human-readable file size
+ */
+export const formatFileSize = (bytes: number): string => {
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  if (bytes === 0) return "0 Bytes";
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return Math.round((bytes / Math.pow(1024, i)) * 100) / 100 + " " + sizes[i];
+};

package/src/media/infrastructure/utils/mediaPickerMappers.README.md

@@ -0,0 +1,129 @@
+# Media Picker Mappers
+
+## Purpose
+Mapper functions to convert between expo-image-picker types and domain types, maintaining abstraction layer.
+
+## File Location
+`src/infrastructure/utils/mediaPickerMappers.ts`
+
+## Strategy
+- Isolate expo-image-picker dependency to infrastructure layer
+- Provide clean mapping between external and domain types
+- Handle permission status conversion
+- Convert media type enums to library-specific formats
+- Transform picker results to domain entities
+- Maintain compatibility with expo-image-picker API changes
+
+## Forbidden
+- **DO NOT** import expo-image-picker outside infrastructure layer
+- **DO NOT** add business logic to mapping functions
+- **DO NOT** modify input parameters during mapping
+- **DO NOT** throw exceptions for invalid inputs (use defaults)
+- **DO NOT** add side effects to mapping functions
+- **DO NOT** directly use mapped types in domain or presentation layers
+- **DO NOT** create circular dependencies with picker implementation
+
+## Rules
+1. All mapping functions must be pure transformations
+2. Permission status must map UNDETERMINED to DENIED
+3. MediaType must convert to array format for expo-image-picker
+4. Asset properties must use fallback values for undefined fields
+5. All mappers must handle null/undefined inputs gracefully
+6. Mapped types must match domain type contracts exactly
+7. Must preserve all original data during transformation
+8. Type conversion must be reversible where possible
+9. Must handle all enum values explicitly
+10. Default values must be documented
+
+## AI Agent Guidelines
+
+When working with media picker mappers:
+
+1. **Layer Isolation**: Only use mappers in infrastructure layer, never in domain/presentation
+2. **Type Conversion**: Always use provided mappers, never manually convert types
+3. **Permission Handling**: Check mapped permission status, not raw expo-image-picker values
+4. **Media Types**: Use domain MediaType enum, then map to expo format when calling picker
+5. **Result Processing**: Always map picker results before passing to other layers
+6. **Fallback Values**: Be aware that asset properties may have default values
+7. **Null Safety**: Handle undefined optional properties in mapped results
+8. **Version Compatibility**: Update mappers when upgrading expo-image-picker
+
+### Permission Status Mapping
+
+- **GRANTED** → GRANTED (full access)
+- **DENIED** → DENIED (no access)
+- **UNDETERMINED** → DENIED (treat as denied, request again)
+
+**Strategy**: Convert undetermined to denied to force explicit permission request
+
+### MediaType Mapping
+
+| Domain MediaType | expo-image-picker Format |
+|-----------------|------------------------|
+| IMAGE | ["images"] |
+| VIDEO | ["videos"] |
+| ALL | ["images", "videos"] |
+| undefined | ["images"] (default) |
+
+**Strategy**: Convert domain enum to array format required by library
+
+### Asset Transformation
+
+All asset fields are mapped with fallback values:
+- **uri**: Required, no fallback
+- **width**: Number, fallback 0
+- **height**: Number, fallback 0
+- **type**: MediaType enum (IMAGE or VIDEO)
+- **fileSize**: Number, fallback 0
+- **fileName**: String or undefined
+- **duration**: Number or undefined (video only)
+- **base64**: String or undefined (only when requested)
+- **mimeType**: String or undefined
+
+### Picker Result Structure
+
+**Input Structure (expo-image-picker)**:
+- A boolean `canceled` field indicating whether the user cancelled the operation
+- An optional `assets` array containing Asset objects from expo-image-picker
+
+**Output Structure (MediaPickerResult)**:
+- A boolean `canceled` field (same as input)
+- An optional `assets` array containing MediaAsset domain objects
+- All Asset fields are transformed to MediaAsset fields with appropriate fallback values
+
+### Integration Patterns
+
+1. **Before Picker**: Convert domain types to picker types
+2. **After Picker**: Convert picker results to domain types
+3. **Permission Check**: Map permission status before domain layer access
+4. **Error Handling**: Check canceled flag before processing assets
+5. **Type Safety**: Use domain types throughout application logic
+
+### Common Workflows
+
+1. **Permission Request**: Check status → Map → Request → Map result
+2. **Media Selection**: Map MediaType → Launch picker → Map result
+3. **Multiple Selection**: Handle array of assets in mapper
+4. **Camera vs Library**: Use same mappers for both picker types
+
+### Validation Rules
+
+1. Always check `canceled` flag before accessing assets
+2. Validate assets array exists and has length > 0
+3. Handle undefined optional properties gracefully
+4. Check permission status before launching picker
+5. Handle null asset properties with fallback values
+
+### Error Handling
+
+1. Cancelled operations return `{ canceled: true }`
+2. Missing assets return empty array or undefined
+3. Invalid types use default fallback values
+4. Permission denied operations should be handled at application level
+5. Never throw exceptions from mapping functions
+
+## Dependencies
+
+- expo-image-picker (external library)
+- Domain layer types (MediaAsset, MediaPickerResult, MediaType, MediaLibraryPermission)
+- Infrastructure layer only

package/src/media/infrastructure/utils/mediaPickerMappers.ts

@@ -0,0 +1,76 @@
+/**
+ * Media Picker Mapper Utilities
+ * Mapping functions for media picker operations
+ */
+
+import * as ImagePicker from "expo-image-picker";
+import {
+  MediaLibraryPermission,
+  MediaType,
+  type MediaAsset,
+  type MediaPickerResult,
+} from "../../domain/entities/Media";
+
+/**
+ * Map expo-image-picker permission status to MediaLibraryPermission
+ */
+export const mapPermissionStatus = (
+  status: ImagePicker.PermissionStatus
+): MediaLibraryPermission => {
+  switch (status) {
+    case ImagePicker.PermissionStatus.GRANTED:
+      return MediaLibraryPermission.GRANTED;
+    case ImagePicker.PermissionStatus.DENIED:
+      return MediaLibraryPermission.DENIED;
+    case ImagePicker.PermissionStatus.UNDETERMINED:
+      return MediaLibraryPermission.DENIED;
+    default:
+      return MediaLibraryPermission.DENIED;
+  }
+};
+
+/**
+ * Map MediaType to expo-image-picker media types
+ */
+export const mapMediaType = (
+  type?: MediaType
+): ImagePicker.MediaType[] => {
+  switch (type) {
+    case MediaType.IMAGE:
+      return ["images"];
+    case MediaType.VIDEO:
+      return ["videos"];
+    case MediaType.ALL:
+      return ["images", "videos"];
+    default:
+      return ["images"];
+  }
+};
+
+/**
+ * Map expo-image-picker result to MediaPickerResult
+ */
+export const mapPickerResult = (
+  result: ImagePicker.ImagePickerResult
+): MediaPickerResult => {
+  if (result.canceled) {
+    return { canceled: true };
+  }
+
+  const assets: MediaAsset[] = result.assets.map((asset) => ({
+    uri: asset.uri,
+    width: asset.width,
+    height: asset.height,
+    type: asset.type === "video" ? MediaType.VIDEO : MediaType.IMAGE,
+    fileSize: asset.fileSize,
+    fileName: asset.fileName ?? undefined,
+    duration: asset.duration ?? undefined,
+    base64: asset.base64 ?? undefined,
+    mimeType: asset.mimeType ?? undefined,
+  }));
+
+  return {
+    canceled: false,
+    assets,
+  };
+};