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

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

@@ -0,0 +1,154 @@
+/**
+ * Media Save Service
+ * Save images and videos to device gallery
+ */
+
+import * as MediaLibrary from "expo-media-library";
+import { MediaType, MediaLibraryPermission } from "../../domain/entities/Media";
+
+export interface SaveResult {
+  success: boolean;
+  assetId?: string;
+  error?: string;
+}
+
+export interface SaveOptions {
+  album?: string;
+}
+
+/**
+ * Service for saving media to gallery
+ */
+export class MediaSaveService {
+  /**
+   * Request media library write permission
+   */
+  static async requestPermission(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } = await MediaLibrary.requestPermissionsAsync();
+      return MediaSaveService.mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  /**
+   * Get current permission status
+   */
+  static async getPermissionStatus(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } = await MediaLibrary.getPermissionsAsync();
+      return MediaSaveService.mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  /**
+   * Save image to gallery
+   */
+  static async saveImage(
+    uri: string,
+    options?: SaveOptions
+  ): Promise<SaveResult> {
+    return MediaSaveService.saveToGallery(uri, MediaType.IMAGE, options);
+  }
+
+  /**
+   * Save video to gallery
+   */
+  static async saveVideo(
+    uri: string,
+    options?: SaveOptions
+  ): Promise<SaveResult> {
+    return MediaSaveService.saveToGallery(uri, MediaType.VIDEO, options);
+  }
+
+  /**
+   * Save media (image or video) to gallery
+   */
+  static async saveToGallery(
+    uri: string,
+    _mediaType: MediaType = MediaType.ALL,
+    options?: SaveOptions
+  ): Promise<SaveResult> {
+    try {
+      const permission = await MediaSaveService.requestPermission();
+
+      if (permission === MediaLibraryPermission.DENIED) {
+        return {
+          success: false,
+          error: "Permission denied to save media",
+        };
+      }
+
+      const asset = await MediaLibrary.createAssetAsync(uri);
+
+      if (options?.album) {
+        const album = await MediaSaveService.getOrCreateAlbum(options.album);
+        if (album) {
+          await MediaLibrary.addAssetsToAlbumAsync([asset], album, false);
+        }
+      }
+
+      return {
+        success: true,
+        assetId: asset.id,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        success: false,
+        error: `Failed to save media: ${message}`,
+      };
+    }
+  }
+
+  /**
+   * Get or create album
+   */
+  private static async getOrCreateAlbum(
+    albumName: string
+  ): Promise<MediaLibrary.Album | null> {
+    try {
+      const albums = await MediaLibrary.getAlbumsAsync();
+      const existingAlbum = albums.find((album) => album.title === albumName);
+
+      if (existingAlbum) {
+        return existingAlbum;
+      }
+
+      const asset = await MediaLibrary.getAssetsAsync({ first: 1 });
+      if (asset.assets.length > 0) {
+        const newAlbum = await MediaLibrary.createAlbumAsync(
+          albumName,
+          asset.assets[0],
+          false
+        );
+        return newAlbum;
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Map permission status
+   */
+  private static mapPermissionStatus(
+    status: MediaLibrary.PermissionStatus
+  ): MediaLibraryPermission {
+    switch (status) {
+      case MediaLibrary.PermissionStatus.GRANTED:
+        return MediaLibraryPermission.GRANTED;
+      case MediaLibrary.PermissionStatus.DENIED:
+        return MediaLibraryPermission.DENIED;
+      case MediaLibrary.PermissionStatus.UNDETERMINED:
+        return MediaLibraryPermission.DENIED;
+      default:
+        return MediaLibraryPermission.DENIED;
+    }
+  }
+}

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

@@ -0,0 +1,135 @@
+# MediaUploadService
+
+## Purpose
+Manages media file uploads to remote servers, including compression, URL management, and download functionality.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaUploadService`
+
+## Strategy
+
+### Core Purpose
+- Upload media files to remote storage
+- Generate and manage media URLs
+- Support compression during upload
+- Download media to local storage
+- Generate thumbnails automatically
+
+### Usage Scenarios
+- User-generated content uploads
+- Profile picture uploads
+- Document/image sharing
+- Media backup workflows
+- Content delivery networks integration
+
+### Integration Points
+- Form submissions with media attachments
+- Social media sharing features
+- Cloud storage synchronization
+- Content management systems
+- Media delivery pipelines
+
+## Forbidden
+
+### MUST NOT
+- Upload invalid or corrupted files
+- Assume network is always available
+- Upload without file size limits
+- Ignore authentication requirements
+- Store sensitive credentials in service
+- Generate duplicate URLs for same media
+
+### MUST NEVER
+- Upload without proper error handling
+- Assume upload progress is always available
+- Retry failed uploads indefinitely
+- Expose sensitive upload endpoints
+- Upload without user consent
+- Ignore network timeout scenarios
+
+## Rules
+
+### Upload Operations
+- MUST validate file before upload
+- MUST handle network errors gracefully
+- MUST support compression options
+- MUST return unique media ID
+- MUST provide upload progress when possible
+- MUST handle timeout scenarios
+
+### Compression Options
+- MUST support quality adjustment (0-1)
+- MUST support max width/height constraints
+- MUST support format conversion (jpeg/png)
+- MUST validate compression parameters
+- MUST apply compression before upload
+
+### URL Management
+- MUST generate unique URLs for each media
+- MUST support URL retrieval by media ID
+- MUST handle invalid media IDs
+- MUST maintain URL consistency
+- MUST support URL expiration if required
+
+### Download Operations
+- MUST validate media ID before download
+- MUST handle download failures
+- MUST return local file path
+- MUST manage storage space
+- MUST support large file downloads
+
+### Return Values
+- MUST include media metadata (type, size, MIME)
+- MUST include unique identifier
+- MUST include URL (full or relative)
+- MUST include thumbnail for applicable types
+- MUST include duration for audio/video
+
+### Error Handling
+- MUST catch network errors
+- MUST handle authentication failures
+- MUST handle storage quota exceeded
+- MUST provide meaningful error messages
+- MUST allow retry after failure
+
+## AI Agent Guidelines
+
+### When Implementing Upload Features
+1. Always validate file metadata before upload
+2. Apply compression options if specified
+3. Generate unique media identifier
+4. Handle network failures gracefully
+5. Return complete media attachment object
+
+### When Working with URLs
+- Generate unique, predictable URLs
+- Support both absolute and relative URLs
+- Include media ID in URL structure
+- Handle URL generation failures
+
+### When Adding Features
+- Add new media types with validation
+- Extend compression options carefully
+- Maintain backward compatibility
+- Add progress tracking for large files
+- Support batch uploads if needed
+
+### When Refactoring
+- Keep upload API stable
+- Preserve media ID generation logic
+- Maintain URL structure consistency
+- Don't change return value structure
+- Add deprecation warnings for breaking changes
+
+### Common Patterns to Follow
+- Validate file -> Apply compression -> Upload -> Return attachment
+- Handle network errors -> Retry if appropriate -> Return error
+- Generate URL -> Store mapping -> Return URL
+- Always wrap network operations in try-catch
+- Provide user feedback for upload progress
+
+## Dependencies
+
+- Domain types: MediaAttachment, MediaCompressionOptions from MultimediaFlashcardTypes
+- Internal utilities: mediaHelpers (generateThumbnail, getMediaDuration, getMediaType)
+- No external library dependencies (uses native APIs and fetch)

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

@@ -0,0 +1,62 @@
+/**
+ * Media Upload Service
+ * Handles media upload, download, and URL operations
+ */
+
+import type {
+  MediaAttachment,
+  MediaCompressionOptions,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+import {
+  generateThumbnail,
+  getMediaDuration,
+  getMediaType,
+} from "../utils/mediaHelpers";
+
+export class MediaUploadService {
+  /**
+   * Upload media file with optional compression
+   */
+  async uploadMedia(
+    file: any,
+    _options?: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    try {
+      // Simulate upload process
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      const attachment: MediaAttachment = {
+        id: `media_${Date.now()}`,
+        type: getMediaType(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> {
+    return `/local/storage/${attachmentId}`;
+  }
+}

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

@@ -0,0 +1,135 @@
+# MediaValidationService
+
+## Purpose
+Validates media files before upload by checking file size, type, and other properties to ensure compatibility and performance.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaValidationService`
+
+## Strategy
+
+### Core Purpose
+- Validate media files before upload
+- Check file size constraints
+- Verify supported file types
+- Provide actionable feedback (errors, warnings, recommendations)
+- Prevent upload of invalid or problematic files
+
+### Usage Scenarios
+- Pre-upload validation checks
+- Form submission workflows
+- File selection validation
+- User feedback on file issues
+- Quality control processes
+
+### Integration Points
+- Before upload operations
+- After file selection
+- In form validation workflows
+- User input feedback loops
+- File processing pipelines
+
+## Forbidden
+
+### MUST NOT
+- Allow uploads of files exceeding size limits
+- Accept unsupported file types
+- Ignore validation results
+- Proceed with upload when isValid is false
+- Assume all files are valid
+- Skip validation for performance
+
+### MUST NEVER
+- Upload files with errors
+- Modify files during validation
+- Cache validation results indefinitely
+- Assume synchronous validation
+- Ignore platform-specific constraints
+- Allow bypass of critical validation rules
+
+## Rules
+
+### Validation Rules
+- MUST check file size (max 50 MB)
+- MUST check file type against supported formats
+- MUST return validation result with isValid boolean
+- MUST provide errors for upload-blocking issues
+- MUST provide warnings for performance concerns
+- MUST provide recommendations for improvements
+
+### File Size Limits
+- MUST reject files over 50 MB (error)
+- MUST warn on files over 10 MB
+- MUST recommend compression for large files
+- MUST format file sizes for readability
+- MUST consider media type for limits
+
+### Supported File Types
+- Images: JPEG, PNG, WebP
+- Audio: MP3, WAV, M4A
+- Video: MP4, MOV
+- MUST validate MIME types
+- MUST reject unsupported types with clear error
+
+### Validation Results
+- MUST include isValid boolean
+- MUST include errors array (upload blockers)
+- MUST include warnings array (performance impacts)
+- MUST include recommendations array (improvements)
+- MUST be serializable for transport
+
+### Error Handling
+- MUST handle missing file metadata
+- MUST handle invalid file structures
+- MUST handle async validation operations
+- MUST provide specific error messages
+- MUST support batch validation
+
+### Feedback Levels
+- Errors: Critical issues that prevent upload
+- Warnings: Non-critical but impactful issues
+- Recommendations: Suggestions for optimization
+- MUST clearly distinguish between levels
+
+## AI Agent Guidelines
+
+### When Implementing Validation
+1. Always check file metadata completeness
+2. Validate size limits before processing
+3. Check MIME type against allowed list
+4. Provide specific, actionable error messages
+5. Return structured validation result
+
+### When Working with Validation Results
+- Check isValid flag before proceeding
+- Display errors to user (block upload)
+- Show warnings to user (allow upload)
+- Present recommendations as optional
+- Format messages for user understanding
+
+### When Adding Validation Rules
+- Add new size limits with clear thresholds
+- Add new file types with MIME validation
+- Add custom rules for specific use cases
+- Maintain backward compatibility
+- Document rule changes
+
+### When Refactoring
+- Keep validation API stable
+- Preserve error message format
+- Maintain validation logic flow
+- Don't change result structure
+- Add deprecation warnings for breaking changes
+
+### Common Patterns to Follow
+- Receive file -> Check metadata -> Validate rules -> Return result
+- Check isValid -> If false, show errors -> If true, proceed
+- Check size -> If large, warn and recommend compression
+- Check type -> If invalid, error with supported types
+- Always handle async validation properly
+
+## Dependencies
+
+- Domain types: MediaValidation from MultimediaFlashcardTypes
+- Internal utilities: mediaHelpers (formatFileSize)
+- No external library dependencies (uses native File API)

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

@@ -0,0 +1,61 @@
+/**
+ * Media Validation Service
+ * Handles media file validation before upload
+ */
+
+import { formatFileSize } from "../utils/mediaHelpers";
+import type { MediaValidation } from "../../domain/entities/MultimediaFlashcardTypes";
+
+export class MediaValidationService {
+  /**
+   * Validate media file before upload
+   */
+  async validateMedia(file: any): Promise<MediaValidation> {
+    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) {
+        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}`);
+      }
+
+      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/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