@umituz/react-native-design-system 4.23.100 → 4.23.101

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

@@ -1,120 +0,0 @@
-# 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/MediaUploadService.README.md

@@ -1,135 +0,0 @@
-# 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/MediaValidationService.README.md

@@ -1,135 +0,0 @@
-# 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/MultimediaFlashcardService.README.md

@@ -1,142 +0,0 @@
-# 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/utils/mediaHelpers.README.md

@@ -1,96 +0,0 @@
-# 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