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

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

@@ -0,0 +1,120 @@
+# MediaSaveService
+
+## Purpose
+Handles saving image and video files to the device's photo gallery, including album management and permission handling.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaSaveService`
+
+## Strategy
+
+### Core Purpose
+- Save media files to device gallery
+- Create and manage custom albums
+- Handle platform-specific save requirements
+- Manage write permissions for media library
+
+### Usage Scenarios
+- Saving downloaded images to gallery
+- Creating app-specific albums
+- Saving captured media to gallery
+- Organizing media into custom collections
+- Backup workflows
+
+### Integration Points
+- After media download completes
+- After media generation/creation
+- User-initiated save actions
+- Batch media save operations
+
+## Forbidden
+
+### MUST NOT
+- Save files without proper write permissions
+- Assume album creation always succeeds
+- Create duplicate albums with same name
+- Overwrite existing media without user consent
+- Save invalid or corrupted media files
+- Ignore save operation results
+
+### MUST NEVER
+- Attempt to save when permission is denied
+- Assume save operation is instant
+- Save to private app storage using this service
+- Modify saved media after save operation completes
+- Bypass platform-specific save restrictions
+
+## Rules
+
+### Permission Management
+- MUST request write permission before saving
+- MUST check permission status before operations
+- MUST handle permission denial gracefully
+- MUST provide clear error messages for permission issues
+- MUST respect user's permission decisions
+
+### Save Operations
+- MUST validate file URI/path before saving
+- MUST determine media type (image/video) correctly
+- MUST handle save failures appropriately
+- MUST return success/failure status
+- MUST include asset ID in successful results
+
+### Album Management
+- MUST create album automatically if it doesn't exist
+- MUST NOT create duplicate albums with same name
+- MUST save to default gallery if no album specified
+- MUST handle album creation failures
+- MUST validate album names
+
+### Error Handling
+- MUST catch and report save failures
+- MUST handle invalid file paths
+- MUST handle insufficient storage scenarios
+- MUST provide meaningful error messages
+- MUST allow retry after permission grant
+
+### Platform Considerations
+- MUST handle iOS save requirements
+- MUST handle Android scoped storage (API 10+)
+- MUST account for platform-specific restrictions
+- MUST test on both platforms
+
+## AI Agent Guidelines
+
+### When Implementing Save Operations
+1. Always check permissions before attempting save
+2. Validate file URI/path exists and is accessible
+3. Determine correct media type for the file
+4. Handle both success and failure cases
+5. Provide user feedback for save operations
+
+### When Working with Albums
+- Check if album exists before creating
+- Use consistent album naming
+- Handle album creation failures gracefully
+- Allow saving to default gallery as fallback
+
+### When Adding Features
+- Add new media types with proper validation
+- Extend save options without breaking changes
+- Maintain backward compatibility
+- Add error handling for new edge cases
+
+### When Refactoring
+- Keep public API stable
+- Preserve permission handling logic
+- Maintain platform-specific behavior
+- Don't remove existing save methods without deprecation
+
+### Common Patterns to Follow
+- Request permission -> Check status -> Validate file -> Save
+- Handle result -> Check success -> Return asset ID or error
+- Always wrap in try-catch for unexpected errors
+- Provide user feedback for save status
+
+## Dependencies
+
+- Domain types: MediaType, MediaLibraryPermission from Media
+- External libraries: expo-media-library
+- No internal utility dependencies

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: [],
+      };
+    }
+  }
+}