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

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

@@ -0,0 +1,80 @@
+/**
+ * Media Generation Service
+ * Handles AI media generation (text-to-image, text-to-audio)
+ */
+
+import type {
+  MediaAttachment,
+  MediaGenerationRequest,
+  MediaGenerationResult,
+  MediaType,
+  MediaPosition,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+
+export class MediaGenerationService {
+  /**
+   * Generate media from AI (text-to-image, text-to-audio, etc.)
+   */
+  async generateMedia(
+    request: MediaGenerationRequest,
+  ): Promise<MediaGenerationResult> {
+    try {
+      const startTime = Date.now();
+
+      // Simulate AI generation
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+
+      const attachments: MediaAttachment[] = [];
+
+      switch (request.type) {
+        case "text_to_image":
+          for (let i = 0; i < (request.options.maxResults || 1); i++) {
+            attachments.push({
+              id: `ai_img_${Date.now()}_${i}`,
+              type: "image" as MediaType,
+              position: "both" as MediaPosition,
+              url: `https://picsum.photos/400/300?random=${Date.now() + i}`,
+              filename: `ai_generated_${i}.jpg`,
+              fileSize: 150000,
+              mimeType: "image/jpeg",
+              isDownloaded: false,
+              createdAt: new Date().toISOString(),
+            });
+          }
+          break;
+
+        case "text_to_audio":
+          attachments.push({
+            id: `ai_audio_${Date.now()}`,
+            type: "audio" as MediaType,
+            position: "back" as MediaPosition,
+            url: `https://example.com/audio_${Date.now()}.mp3`,
+            filename: `ai_generated_${Date.now()}.mp3`,
+            fileSize: 80000,
+            mimeType: "audio/mp3",
+            duration: 10,
+            isDownloaded: false,
+            createdAt: new Date().toISOString(),
+          });
+          break;
+      }
+
+      return {
+        success: true,
+        attachments,
+        creditsUsed: request.type === "text_to_image" ? 5 : 3,
+        processingTime: Date.now() - startTime,
+        requestId: `req_${Date.now()}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        attachments: [],
+        creditsUsed: 0,
+        processingTime: 0,
+        error: error instanceof Error ? error.message : "Unknown error",
+        requestId: "",
+      };
+    }
+  }
+}

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

@@ -0,0 +1,145 @@
+# MediaOptimizerService
+
+## Purpose
+Optimizes and compresses media files to reduce file size while maintaining acceptable quality, and manages media deletion operations.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaOptimizerService`
+
+## Strategy
+
+### Core Purpose
+- Reduce media file size through compression
+- Maintain acceptable quality after optimization
+- Support quality and dimension constraints
+- Delete media from server and local storage
+- Generate optimized versions of existing media
+
+### Usage Scenarios
+- Pre-upload optimization
+- Storage cost reduction
+- Performance improvement
+- Bandwidth optimization
+- Media cleanup workflows
+
+### Integration Points
+- After upload, before storage
+- In media management workflows
+- Storage optimization processes
+- Media cleanup routines
+- Performance tuning operations
+
+## Forbidden
+
+### MUST NOT
+- Optimize media beyond usable quality
+- Delete media without proper authorization
+- Assume optimization always succeeds
+- Modify original media files
+- Ignore quality settings
+- Delete without confirmation in critical workflows
+
+### MUST NEVER
+- Optimize already optimized media repeatedly
+- Use quality below 0.3 without explicit request
+- Delete media without backup when required
+- Assume optimization is lossless
+- Ignore file size after optimization
+- Return different media ID after optimization
+
+## Rules
+
+### Optimization Operations
+- MUST accept media attachment and options
+- MUST preserve original media (create new version)
+- MUST return optimized media attachment
+- MUST maintain same media ID
+- MUST update file size accurately
+- MUST add optimization indicator to URL
+
+### Compression Options
+- MUST support quality adjustment (0-1)
+- MUST support max width constraint
+- MUST support max height constraint
+- MUST support format conversion
+- MUST validate compression parameters
+- MUST respect quality vs size tradeoff
+
+### Quality Levels
+- High quality (0.9-1.0): 10-20% size reduction
+- Medium quality (0.7-0.8): 30-50% size reduction
+- Low quality (0.5-0.6): 50-70% size reduction
+- Preview quality (0.3-0.4): 70-80% size reduction
+- MUST document quality tradeoffs
+
+### Deletion Operations
+- MUST accept media ID for deletion
+- MUST delete from both server and local storage
+- MUST handle non-existent media gracefully
+- MUST confirm deletion success
+- MUST be permanent and irreversible
+
+### Return Values
+- MUST preserve original media ID
+- MUST preserve media type
+- MUST update file size
+- MUST preserve MIME type
+- MUST preserve creation date
+- MUST update URL with optimization indicator
+
+### Error Handling
+- MUST handle optimization failures
+- MUST handle deletion failures
+- MUST handle invalid media IDs
+- MUST handle invalid compression options
+- MUST provide meaningful error messages
+- MUST allow retry on transient failures
+
+## AI Agent Guidelines
+
+### When Implementing Optimization
+1. Always validate compression options
+2. Calculate expected file size reduction
+3. Apply compression with specified quality
+4. Update metadata accurately
+5. Return optimized version with same ID
+
+### When Working with Quality Settings
+- Use 0.7-0.8 for general use (recommended)
+- Use 0.9-1.0 for high-quality requirements
+- Use 0.5-0.6 for previews and thumbnails
+- Avoid quality below 0.3 unless specifically needed
+- Consider content type when setting quality
+
+### When Performing Deletion
+- Confirm media ID exists before deletion
+- Handle deletion from both storage locations
+- Provide confirmation in critical workflows
+- Log deletion operations for audit
+- Handle non-existent media gracefully
+
+### When Adding Features
+- Add new compression formats carefully
+- Support new dimension constraints
+- Add batch optimization if needed
+- Maintain backward compatibility
+- Add optimization presets for common cases
+
+### When Refactoring
+- Keep optimization API stable
+- Preserve ID generation logic
+- Maintain URL structure
+- Don't change return value structure
+- Add deprecation warnings for breaking changes
+
+### Common Patterns to Follow
+- Receive attachment -> Validate options -> Optimize -> Return optimized
+- Calculate size -> Apply quality -> Update metadata -> Return
+- Receive ID -> Validate -> Delete -> Confirm
+- Always wrap in try-catch for unexpected errors
+- Provide user feedback for optimization progress
+
+## Dependencies
+
+- Domain types: MediaAttachment, MediaCompressionOptions from MultimediaFlashcardTypes
+- No external library dependencies (uses native APIs)

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

@@ -0,0 +1,32 @@
+/**
+ * Media Optimizer Service
+ * Handles media optimization and deletion
+ */
+
+import type {
+  MediaAttachment,
+  MediaCompressionOptions,
+} from "../../domain/entities/MultimediaFlashcardTypes";
+
+export class MediaOptimizerService {
+  /**
+   * Optimize media file
+   */
+  async optimizeMedia(
+    attachment: MediaAttachment,
+    options: MediaCompressionOptions,
+  ): Promise<MediaAttachment> {
+    return {
+      ...attachment,
+      fileSize: Math.floor(attachment.fileSize * options.quality),
+      url: `${attachment.url}?optimized=true`,
+    };
+  }
+
+  /**
+   * Delete media attachment
+   */
+  async deleteMedia(_attachmentId: string): Promise<void> {
+    // Mock implementation
+  }
+}

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

@@ -0,0 +1,106 @@
+# MediaPickerService
+
+## Purpose
+Provides image and video selection functionality from device camera and gallery, including permission management and media type filtering.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaPickerService`
+
+## Strategy
+
+### Core Purpose
+- Enable users to select media from device gallery or capture using camera
+- Support single and multiple media selection
+- Handle platform-specific permission requirements
+- Provide customizable selection options
+
+### Usage Scenarios
+- User profile picture selection
+- Content creation workflows
+- Multi-image selection for galleries
+- Video recording for user-generated content
+- Mixed media selection (images and videos)
+
+### Integration Points
+- Forms requiring media attachments
+- Content management systems
+- Social media features
+- Document upload workflows
+
+## Forbidden
+
+### MUST NOT
+- Bypass permission checks or force camera/gallery access
+- Assume permissions are always granted
+- Hardcode file paths or URIs
+- Access media without explicit user action
+- Automatically launch camera without user consent
+- Store selected media URIs in permanent storage without validation
+
+### MUST NEVER
+- Allow infinite selection limits without boundaries
+- Use base64 conversion by default (performance impact)
+- Assume all devices support the same media types
+- Ignore permission denial states
+- Access camera roll without proper permissions
+
+## Rules
+
+### Permission Management
+- MUST request camera permission before launching camera
+- MUST request media library permission before accessing gallery
+- MUST handle permission denial gracefully
+- MUST check permission status before operations
+- MUST provide clear error messages when permissions are denied
+
+### Media Selection
+- MUST respect selection limits
+- MUST validate selected media before processing
+- MUST handle user cancellation (canceled: true)
+- MUST support both single and multiple selection modes
+- MUST filter media types appropriately
+
+### Platform Considerations
+- MUST handle iOS and Android permission differences
+- MUST account for platform-specific media type restrictions
+- MUST test on both platforms for compatibility
+- MUST handle aspect ratio options correctly (only works with allowsEditing: true)
+
+### Performance
+- MUST avoid base64 conversion unless explicitly required
+- MUST set reasonable quality defaults
+- MUST handle large media files appropriately
+- MUST provide loading states during selection
+
+## AI Agent Guidelines
+
+### When Implementing Media Selection
+1. Always check permissions before launching picker
+2. Handle both success (canceled: false) and cancellation (canceled: true)
+3. Validate returned assets array exists and has items
+4. Consider media type (image vs video) for different handling
+5. Use appropriate quality settings based on use case
+
+### When Adding Features
+- Add new permission types only if required by new functionality
+- Extend options interface without breaking existing functionality
+- Maintain backward compatibility with existing selection methods
+- Add error handling for new edge cases
+
+### When Refactoring
+- Keep public API stable
+- Preserve permission handling logic
+- Maintain platform-specific behavior differences
+- Don't remove existing selection methods without deprecation
+
+### Common Patterns to Follow
+- Request permission -> Check status -> Launch picker
+- Handle result -> Validate -> Return or process
+- Always wrap in try-catch for unexpected errors
+- Provide user feedback for permission states
+
+## Dependencies
+
+- Domain types: MediaPickerOptions, MediaPickerResult, CameraOptions, MediaType, MediaLibraryPermission, MEDIA_CONSTANTS from Media
+- External libraries: expo-image-picker
+- Internal utilities: mediaPickerMappers (mapMediaType, mapPermissionStatus, mapPickerResult)

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

@@ -0,0 +1,173 @@
+/**
+ * Media Domain - Media Picker Service
+ *
+ * Service for picking images/videos using expo-image-picker.
+ * Handles camera, gallery, and media library permissions.
+ */
+
+import * as ImagePicker from "expo-image-picker";
+import type {
+  MediaPickerOptions,
+  MediaPickerResult,
+  CameraOptions,
+} from "../../domain/entities/Media";
+import {
+  MediaLibraryPermission,
+  MediaType,
+  MEDIA_CONSTANTS,
+} from "../../domain/entities/Media";
+import {
+  mapMediaType,
+  mapPermissionStatus,
+  mapPickerResult,
+} from "../utils/mediaPickerMappers";
+
+/**
+ * Media picker service for selecting images/videos
+ */
+export class MediaPickerService {
+  static async requestCameraPermission(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } = await ImagePicker.requestCameraPermissionsAsync();
+      return mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  static async requestMediaLibraryPermission(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } =
+        await ImagePicker.requestMediaLibraryPermissionsAsync();
+      return mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  static async getCameraPermissionStatus(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } = await ImagePicker.getCameraPermissionsAsync();
+      return mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  static async getMediaLibraryPermissionStatus(): Promise<MediaLibraryPermission> {
+    try {
+      const { status } = await ImagePicker.getMediaLibraryPermissionsAsync();
+      return mapPermissionStatus(status);
+    } catch {
+      return MediaLibraryPermission.DENIED;
+    }
+  }
+
+  static async launchCamera(
+    options?: CameraOptions
+  ): Promise<MediaPickerResult> {
+    try {
+      const permission = await MediaPickerService.requestCameraPermission();
+      if (permission === MediaLibraryPermission.DENIED) {
+        return { canceled: true };
+      }
+
+      const result = await ImagePicker.launchCameraAsync({
+        mediaTypes: ["images"],
+        allowsEditing: options?.allowsEditing ?? false,
+        aspect: options?.aspect,
+        quality: options?.quality ?? MEDIA_CONSTANTS.DEFAULT_QUALITY,
+        base64: options?.base64 ?? false,
+      });
+
+      return mapPickerResult(result);
+    } catch {
+      return { canceled: true };
+    }
+  }
+
+  static async launchCameraForVideo(
+    options?: CameraOptions
+  ): Promise<MediaPickerResult> {
+    try {
+      const permission = await MediaPickerService.requestCameraPermission();
+      if (permission === MediaLibraryPermission.DENIED) {
+        return { canceled: true };
+      }
+
+      const result = await ImagePicker.launchCameraAsync({
+        mediaTypes: ["videos"],
+        allowsEditing: options?.allowsEditing ?? false,
+        quality: options?.quality ?? MEDIA_CONSTANTS.DEFAULT_QUALITY,
+        videoMaxDuration: options?.videoMaxDuration,
+      });
+
+      return mapPickerResult(result);
+    } catch {
+      return { canceled: true };
+    }
+  }
+
+  static async pickImage(
+    options?: MediaPickerOptions
+  ): Promise<MediaPickerResult> {
+    try {
+      const permission =
+        await MediaPickerService.requestMediaLibraryPermission();
+      if (permission === MediaLibraryPermission.DENIED) {
+        return { canceled: true };
+      }
+
+      const result = await ImagePicker.launchImageLibraryAsync({
+        mediaTypes: mapMediaType(options?.mediaTypes),
+        allowsEditing: options?.allowsEditing ?? false,
+        allowsMultipleSelection: options?.allowsMultipleSelection ?? false,
+        aspect: options?.aspect,
+        quality: options?.quality ?? MEDIA_CONSTANTS.DEFAULT_QUALITY,
+        selectionLimit:
+          options?.selectionLimit ?? MEDIA_CONSTANTS.DEFAULT_SELECTION_LIMIT,
+        base64: options?.base64 ?? false,
+      });
+
+      return mapPickerResult(result);
+    } catch {
+      return { canceled: true };
+    }
+  }
+
+  static async pickSingleImage(
+    options?: Omit<MediaPickerOptions, "allowsMultipleSelection">
+  ): Promise<MediaPickerResult> {
+    return MediaPickerService.pickImage({
+      ...options,
+      allowsMultipleSelection: false,
+    });
+  }
+
+  static async pickMultipleImages(
+    options?: Omit<MediaPickerOptions, "allowsMultipleSelection">
+  ): Promise<MediaPickerResult> {
+    return MediaPickerService.pickImage({
+      ...options,
+      allowsMultipleSelection: true,
+    });
+  }
+
+  static async pickVideo(
+    options?: Omit<MediaPickerOptions, "mediaTypes">
+  ): Promise<MediaPickerResult> {
+    return MediaPickerService.pickImage({
+      ...options,
+      mediaTypes: MediaType.VIDEO,
+    });
+  }
+
+  static async pickMedia(
+    options?: MediaPickerOptions
+  ): Promise<MediaPickerResult> {
+    return MediaPickerService.pickImage({
+      ...options,
+      mediaTypes: MediaType.ALL,
+    });
+  }
+}

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