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

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

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

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

@@ -1,106 +0,0 @@
-# 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/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)