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

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

@@ -0,0 +1,142 @@
+# MediaGenerationService
+
+## Purpose
+Provides AI-powered media generation capabilities including text-to-image and text-to-audio generation with credit/balance management.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/MediaGenerationService`
+
+## Strategy
+
+### Core Purpose
+- Generate images from text descriptions (text-to-image)
+- Generate audio from text (text-to-audio)
+- Support multiple result generation
+- Track processing time and performance
+- Manage generation costs/credits
+
+### Usage Scenarios
+- AI-generated visual content for cards
+- Text-to-speech conversion
+- Creative content generation
+- Localization and voice-over creation
+- Dynamic asset generation
+
+### Integration Points
+- AI-powered content creation workflows
+- Text-to-speech features
+- Automated asset generation
+- Creative assistance tools
+- Educational content generation
+
+## Forbidden
+
+### MUST NOT
+- Generate without sufficient credits/balance
+- Assume generation always succeeds
+- Generate inappropriate or harmful content
+- Ignore rate limiting or API constraints
+- Cache generated content without validation
+- Generate without user prompt input
+
+### MUST NEVER
+- Expose API keys or credentials
+- Allow unlimited free generation
+- Ignore generation failures
+- Bypass credit/balance checks
+- Generate without proper error handling
+- Assume instant generation results
+
+## Rules
+
+### Generation Operations
+- MUST validate prompt before generation
+- MUST check sufficient credits/balance
+- MUST handle generation failures
+- MUST track processing time
+- MUST return unique request ID
+- MUST respect result limits (maxResults)
+
+### Text-to-Image Generation
+- MUST support style options
+- MUST support aspect ratio options
+- MUST generate multiple results if requested
+- MUST validate image generation parameters
+- MUST handle generation timeouts
+
+### Text-to-Audio Generation
+- MUST support voice options
+- MUST support language selection
+- MUST support speed adjustment
+- MUST return audio duration
+- MUST validate audio parameters
+
+### Credit Management
+- MUST deduct credits per generation
+- MUST track credit usage in results
+- MUST validate credit availability
+- MUST prevent generation with insufficient credits
+- MUST report credits used in result
+
+### Return Values
+- MUST include success status
+- MUST include generated media attachments
+- MUST include credits used
+- MUST include processing time
+- MUST include unique request ID
+- MUST include error details on failure
+
+### Error Handling
+- MUST handle insufficient credits
+- MUST handle generation timeouts
+- MUST handle invalid prompts
+- MUST handle API failures
+- MUST provide meaningful error messages
+- MUST allow retry after appropriate delay
+
+## AI Agent Guidelines
+
+### When Implementing Generation Features
+1. Always validate prompt input
+2. Check credit/balance before generation
+3. Set appropriate timeouts
+4. Handle both success and failure cases
+5. Track and report processing metrics
+
+### When Working with Text-to-Image
+- Support common aspect ratios (16:9, 4:3, 1:1)
+- Provide style presets (realistic, artistic, etc.)
+- Limit max results to reasonable number
+- Validate image generation parameters
+
+### When Working with Text-to-Audio
+- Support common languages
+- Provide voice options (male, female)
+- Allow speed adjustment (0.5-2.0)
+- Return accurate duration
+
+### When Adding Features
+- Add new generation types with validation
+- Extend options without breaking compatibility
+- Add new credit tiers carefully
+- Support batch generation if needed
+- Add content filtering if required
+
+### When Refactoring
+- Keep generation API stable
+- Preserve credit calculation logic
+- Maintain request ID generation
+- Don't change result structure
+- Add deprecation warnings for breaking changes
+
+### Common Patterns to Follow
+- Validate prompt -> Check credits -> Generate -> Return result
+- Handle timeout -> Retry if appropriate -> Return error
+- Calculate credits -> Deduct -> Track usage
+- Always wrap in try-catch for unexpected errors
+- Provide user feedback for generation status
+
+## Dependencies
+
+- Domain types: MediaAttachment, MediaGenerationRequest, MediaGenerationResult, MediaType, MediaPosition from MultimediaFlashcardTypes
+- No external library dependencies (uses native APIs)

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