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

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

@@ -1,167 +0,0 @@
-# CardMediaOptimizerService
-
-## Purpose
-Service that optimizes and compresses flashcard media files to reduce 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/CardMediaOptimizerService`
-
-## Strategy
-- Optimize media files by reducing file size with quality settings
-- Support dimension resizing (maxWidth, maxHeight)
-- Provide multiple quality levels for different use cases
-- Generate new optimized versions while preserving originals
-- Delete media from server and local storage
-- Return optimized media with updated file size and URL
-- Maintain card media position through optimization
-- Calculate size reduction percentages
-
-## Forbidden
-- **DO NOT** optimize below usable quality (quality < 0.3)
-- **DO NOT** modify original media files
-- **DO NOT** delete media without verifying ownership
-- **DO NOT** assume optimization will always succeed
-- **DO NOT** use negative or invalid quality values
-- **DO NOT** set dimensions to zero or negative values
-- **DO NOT** delete media without user confirmation
-- **DO NOT** bypass optimization error handling
-
-## Rules
-1. Quality value must be between 0-1 (0 = worst, 1 = best)
-2. Max dimensions must be positive integers if specified
-3. Original media is always preserved, never modified
-4. Optimized media receives new URL with ?optimized=true parameter
-5. File size is approximately calculated as: original * quality
-6. Position attribute is preserved through optimization
-7. All other attachment properties remain unchanged
-8. Optimization must maintain aspect ratio when resizing
-9. Delete operation is permanent and irreversible
-10. Optimized size calculation is simulated (not actual compression)
-11. Quality levels: high (0.9-1.0), medium (0.7-0.8), low (0.5-0.6)
-
-## AI Agent Guidelines
-
-When working with CardMediaOptimizerService:
-
-1. **Quality Selection**: Choose appropriate quality for use case
-2. **Size Calculation**: Estimate size reduction before optimization
-3. **Original Preservation**: Always keep original media intact
-4. **Error Handling**: Handle optimization failures gracefully
-5. **Position Maintenance**: Preserve position through all operations
-6. **Delete Confirmation**: Always verify before deletion
-7. **Batch Operations**: Consider batch optimization for multiple files
-
-### Quality Level Guidelines
-
-- **High Quality (0.9-1.0)**:
-  - Use for: Card front images, important visuals
-  - Size reduction: 10-20%
-  - When to use: High quality requirements, focal content
-
-- **Medium Quality (0.7-0.8)** - RECOMMENDED:
-  - Use for: General card media, back images
-  - Size reduction: 30-50%
-  - When to use: Balance of quality and size, most cases
-
-- **Low Quality (0.5-0.6)**:
-  - Use for: Thumbnails, previews, non-critical content
-  - Size reduction: 50-70%
-  - When to use: Previews, placeholders, bandwidth-constrained
-
-- **Very Low Quality (0.3-0.4)**:
-  - Use for: Low-quality previews only
-  - Size reduction: 70-80%
-  - When to use: Extreme bandwidth constraints
-
-### Dimension Guidelines
-
-- **Full Resolution**: No max dimensions specified
-  - Use when: Quality is critical, storage is abundant
-
-- **1920x1080** - RECOMMENDED:
-  - Use for: General card media, good balance
-  - Suitable for: Most modern displays
-
-- **1280x720**:
-  - Use for: Smaller cards, bandwidth optimization
-  - Suitable for: Mobile devices, previews
-
-- **Lower than 1280x720**:
-  - Use for: Thumbnails, very small cards
-  - Consider: May appear pixelated on large screens
-
-### Card-Specific Optimization
-
-- **Front Side Media**:
-  - Use higher quality (0.8-0.9)
-  - Full or near-full resolution
-  - This is the focal point of the card
-
-- **Back Side Media**:
-  - Use medium quality (0.7)
-  - Moderate resolution (1280x720 or 1920x1080)
-  - Secondary content can be more compressed
-
-- **Audio Files**:
-  - This service is designed for image optimization only
-  - Audio optimization requires different approach (bitrate)
-
-### Deletion Guidelines
-
-- **Before Delete**:
-  - Verify media ownership
-  - Check card associations
-  - Confirm with user if applicable
-  - Consider soft delete option
-
-- **During Delete**:
-  - Remove from server storage
-  - Remove from local storage
-  - Update card references
-  - Handle missing files gracefully
-
-- **After Delete**:
-  - Update database references
-  - Clean up orphaned files
-  - Cannot be undone (permanent)
-
-### Optimization Workflow
-
-1. Start with original media attachment
-2. Determine target quality and dimensions
-3. Calculate expected size reduction
-4. Run optimization operation
-5. Receive optimized attachment with new URL
-6. Replace or keep both versions
-7. Update card media references
-
-### Error Handling
-
-- **Optimization Failures**:
-  - Return original media unchanged
-  - Log error for debugging
-  - Continue with original if appropriate
-
-- **Invalid Parameters**:
-  - Quality outside 0-1 range
-  - Negative or zero dimensions
-  - Must reject with clear error
-
-- **Delete Failures**:
-  - Media not found
-  - Permission denied
-  - Handle gracefully, log error
-
-### Performance Considerations
-
-- Optimization is simulated (size * quality calculation)
-- In production, integrate actual optimization API
-- Consider lazy optimization (optimize on demand)
-- Batch optimization for multiple files
-- Cache optimized versions when possible
-
-## Dependencies
-- CardMediaAttachment type from domain layer
-- CardMediaCompressionOptions type for optimization settings
-- Optimization API endpoints (simulated in development)
-- Storage access for deletion operations

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

@@ -1,36 +0,0 @@
-/**
- * Card Media Optimizer Service
- * Handles media optimization and deletion
- */
-
-declare var __DEV__: boolean;
-
-import type {
-  CardMediaAttachment,
-  CardMediaCompressionOptions,
-} from "../../domain/entities/CardMultimedia.types";
-
-export class CardMediaOptimizerService {
-  /**
-   * Optimize media file
-   */
-  async optimizeMedia(
-    attachment: CardMediaAttachment,
-    options: CardMediaCompressionOptions,
-  ): Promise<CardMediaAttachment> {
-    return {
-      ...attachment,
-      fileSize: Math.floor(attachment.fileSize * options.quality),
-      url: `${attachment.url}?optimized=true`,
-    };
-  }
-
-  /**
-   * Delete media attachment
-   */
-  async deleteMedia(attachmentId: string): Promise<void> {
-    if (__DEV__) {
-      console.log(`[DesignSystem] CardMediaOptimizerService: Deleting media ${attachmentId}`);
-    }
-  }
-}

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

@@ -1,123 +0,0 @@
-# CardMediaUploadService
-
-## Purpose
-Service that handles media file upload, download, and URL management for flashcard applications, with support for compression and automatic thumbnail generation.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMediaUploadService`
-
-## Strategy
-- Upload media files to server storage with unique identifiers
-- Support compression options during upload (quality, dimensions, format)
-- Generate thumbnails automatically for uploaded media
-- Download media from server to local storage
-- Retrieve and manage media URLs
-- Calculate duration for audio/video files
-- Return card-compatible media attachments with position support
-- Handle all media types (image, video, audio) with automatic type detection
-
-## Forbidden
-- **DO NOT** upload files without validation
-- **DO NOT** bypass file size limits
-- **DO NOT** upload unsupported file types
-- **DO NOT** ignore upload failures
-- **DO NOT** assume all uploads will succeed
-- **DO NOT** overwrite existing media without verification
-- **DO NOT** proceed without error handling for network issues
-- **DO NOT** download media without checking URL validity
-
-## Rules
-1. All uploads must include valid file metadata (name, type, size, uri)
-2. Compression options are optional but recommended for large files
-3. Quality must be between 0-1 when specified
-4. Max dimensions must be positive integers when specified
-5. Supported formats are jpeg and png for compression
-6. All attachments receive unique IDs automatically
-7. Position defaults to 'both' for uploaded media
-8. isDownloaded defaults to true for uploads
-9. Thumbnails are generated automatically for visual content
-10. Audio/video duration is calculated automatically
-11. File type is determined automatically from MIME type
-12. Upload operations must handle network failures gracefully
-13. Download operations must validate URL before processing
-
-## AI Agent Guidelines
-
-When working with CardMediaUploadService:
-
-1. **Pre-upload Validation**: Always validate files before upload attempts
-2. **Compression Strategy**: Apply compression for files larger than 5MB
-3. **Type Detection**: Rely on automatic type detection from MIME type
-4. **Error Handling**: Handle network timeouts and connection failures
-5. **Position Assignment**: Set correct position (front/back/both) for card use
-6. **Thumbnail Usage**: Use thumbnails for previews to save bandwidth
-7. **Duration Handling**: Use calculated duration for audio/video scheduling
-
-### Upload Guidelines
-
-- **Before Upload**:
-  - Validate file size and type
-  - Consider compression for large files
-  - Check network connectivity
-  - Prepare error handling
-
-- **During Upload**:
-  - Monitor for failures
-  - Handle network errors
-  - Store attachment information
-  - Track upload progress
-
-- **After Upload**:
-  - Verify upload success
-  - Store attachment ID and URL
-  - Set position for card use
-  - Consider optimization if needed
-
-### Compression Options
-
-- **Quality**: 0.9 (high), 0.7 (medium/recommended), 0.5 (low)
-- **Max Dimensions**: 1920x1080 (recommended), 1280x720 (smaller)
-- **Format**: jpeg (smaller size), png (better quality)
-- Apply compression when file size > 5MB for images
-- Use quality 0.7 for balance of size and quality
-
-### Media Type Detection
-
-- **Image**: MIME types starting with 'image/'
-  - Supported: image/jpeg, image/png, image/webp
-- **Audio**: MIME types starting with 'audio/'
-  - Supported: audio/mp3, audio/wav, audio/m4a
-- **Video**: MIME types starting with 'video/'
-  - Supported: video/mp4, video/mov
-
-### Download Guidelines
-
-- Validate media URL before download
-- Handle missing files gracefully
-- Use local path for offline access
-- Check isDownloaded status before re-downloading
-- Manage local storage space
-
-### Error Handling Patterns
-
-- Handle network errors: timeout, connection refused
-- Handle file errors: invalid format, corrupted file
-- Handle server errors: 500, 503, insufficient storage
-- Handle validation errors: size exceeded, unsupported type
-- Always provide fallback behavior for failed uploads
-
-### Performance Considerations
-
-- Upload operations are simulated (2 seconds delay)
-- Compress before upload to reduce transfer time
-- Use thumbnails for previews instead of full media
-- Batch uploads when possible for multiple files
-- Consider lazy loading for card media
-
-## Dependencies
-- CardMediaAttachment type from domain layer
-- CardMediaCompressionOptions type for compression settings
-- getCardMediaType helper for type detection
-- getMediaDuration helper for duration calculation
-- generateThumbnail helper for thumbnail creation
-- Upload API endpoints (simulated in development)

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

@@ -1,62 +0,0 @@
-/**
- * Card Media Upload Service
- * Handles media upload, download, and URL operations
- */
-
-import type {
-  CardMediaAttachment,
-  CardMediaCompressionOptions,
-  CardMediaFile,
-} from "../../domain/entities/CardMultimedia.types";
-import { generateThumbnail, getMediaDuration } from "../utils/file-media-utils";
-import { getMediaTypeFromMime } from "../utils/mime-type-detector";
-
-export class CardMediaUploadService {
-  /**
-   * Upload media file with optional compression
-   */
-  async uploadMedia(
-    file: CardMediaFile,
-    _options?: CardMediaCompressionOptions,
-  ): Promise<CardMediaAttachment> {
-    try {
-      // Simulate upload process
-      await new Promise((resolve) => setTimeout(resolve, 2000));
-
-      const attachment: CardMediaAttachment = {
-        id: `card_media_${Date.now()}`,
-        type: getMediaTypeFromMime(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> {
-    if (__DEV__) {
-    }
-    return `/local/storage/${attachmentId}`;
-  }
-}

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

@@ -1,134 +0,0 @@
-# CardMediaValidationService
-
-## Purpose
-Service that validates flashcard media files before upload, checking file size, type, and media-specific properties with detailed error, warning, and recommendation reporting.
-
-## File Location
-`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMediaValidationService`
-
-## Strategy
-- Validate media files before upload operations
-- Check file size against maximum limits (50 MB hard limit)
-- Validate file type compatibility (image, audio, video)
-- Provide media-specific warnings (large images, long videos)
-- Generate actionable recommendations for optimization
-- Return structured validation results with errors, warnings, and recommendations
-- Support asynchronous validation operations
-- Format file sizes in human-readable format
-
-## Forbidden
-- **DO NOT** upload files with validation errors
-- **DO NOT** ignore validation warnings about performance impact
-- **DO NOT** bypass validation for any media upload
-- **DO NOT** allow unsupported file types
-- **DO NOT** proceed when file size exceeds maximum
-- **DO NOT** suppress error messages
-- **DO NOT** assume all validations will pass
-- **DO NOT** skip validation for "trusted" sources
-
-## Rules
-1. Maximum file size is 50 MB (hard error)
-2. Large file warning is triggered at 10 MB+
-3. Very large image warning is triggered at 5 MB+
-4. Long audio/video warning is triggered at 5 minutes (300 seconds)
-5. Supported image types: image/jpeg, image/png, image/webp
-6. Supported audio types: audio/mp3, audio/wav, audio/m4a
-7. Supported video types: video/mp4, video/mov
-8. Unsupported file types must return error
-9. Validation must be asynchronous operation
-10. Warnings must not block upload but inform user
-11. Recommendations must provide actionable improvement steps
-12. File size must be checked in bytes
-13. Validation result must include isValid boolean flag
-
-## AI Agent Guidelines
-
-When working with CardMediaValidationService:
-
-1. **Always Validate**: Never upload without validation first
-2. **Check isValid**: Block upload if isValid is false
-3. **Handle Errors**: Show error messages to user and prevent upload
-4. **Show Warnings**: Display warnings but allow user to proceed
-5. **Provide Recommendations**: Show optimization suggestions
-6. **Media-Specific Checks**: Apply different rules for each media type
-7. **User Communication**: Present validation results clearly
-
-### Validation Workflow
-
-- **Step 1 - Validate**: Run validation before any upload
-- **Step 2 - Check Errors**: If errors exist, show and stop
-- **Step 3 - Show Warnings**: Display warnings, ask user to confirm
-- **Step 4 - Show Recommendations**: Present optimization suggestions
-- **Step 5 - Proceed or Stop**: Allow upload if valid, stop if invalid
-
-### Error Handling
-
-- **File Size Errors**:
-  - "File size (X MB) exceeds maximum allowed size (50 MB)"
-  - Must prevent upload operation
-  - User must reduce file size
-
-- **File Type Errors**:
-  - "Unsupported file type: [type]"
-  - Must prevent upload operation
-  - User must convert to supported format
-
-### Warning Handling
-
-- **Large File Warning** (10+ MB):
-  - "Large file size may impact performance"
-  - Allow upload with user confirmation
-  - Recommend compression
-
-- **Large Image Warning** (5+ MB):
-  - "Very large image may cause performance issues"
-  - Allow upload with user confirmation
-  - Recommend resizing to under 5 MB
-
-- **Long Content Warning** (5+ minutes):
-  - "Long audio/video files may impact app performance"
-  - Allow upload with user confirmation
-  - Recommend trimming to under 5 minutes
-
-### Recommendation Patterns
-
-- **For Large Files**: "Consider compressing file"
-- **For Large Images**: "Consider resizing image to under 5MB"
-- **For Long Content**: "Consider trimming to under 5 minutes"
-- **For Format**: Recommend MP3 for audio, MP4 for video
-- **For Resolution**: Recommend 1920x1080 or smaller
-
-### Media-Specific Validation
-
-- **Images**:
-  - Check MIME type against supported formats
-  - Warn if size > 5 MB
-  - Recommend JPEG for better compression
-  - Consider resolution checks (optional)
-
-- **Audio**:
-  - Check MIME type against supported formats
-  - Warn if duration > 5 minutes
-  - Recommend MP3 format
-  - Consider bitrate checks (optional)
-
-- **Video**:
-  - Check MIME type against supported formats
-  - Warn if duration > 5 minutes
-  - Recommend MP4 format
-  - Consider resolution checks (optional)
-
-### User Communication
-
-- Display errors prominently (block upload)
-- Show warnings with clear impact explanation
-- Present recommendations as actionable steps
-- Allow user to decide on warnings
-- Format file sizes in MB/KB for readability
-- Group messages by severity (errors, warnings, recommendations)
-
-## Dependencies
-- CardMediaValidation type for validation results
-- File size constants for limits
-- MIME type validation utilities
-- Media type detection helpers

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

@@ -1,81 +0,0 @@
-/**
- * Card Media Validation Service
- * Handles media file validation before upload
- */
-
-import { formatFileSize } from "../utils/media-collection-utils";
-import { getMediaDuration } from "../utils/file-media-utils";
-import type { CardMediaValidation, CardMediaFile } from "../../domain/entities/CardMultimedia.types";
-
-export class CardMediaValidationService {
-  /**
-   * Validate media file before upload
-   */
-  async validateMedia(file: CardMediaFile): Promise<CardMediaValidation> {
-    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) {
-        // 10MB
-        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}`);
-      }
-
-      // Media-specific validations
-      if (file.type.startsWith("image/")) {
-        if (file.size > 5 * 1024 * 1024) {
-          // 5MB for images
-          warnings.push("Very large image may cause performance issues");
-          recommendations.push("Consider resizing image to under 5MB");
-        }
-      }
-
-      if (file.type.startsWith("audio/") || file.type.startsWith("video/")) {
-        const duration = await getMediaDuration(file);
-        if (duration && duration > 300) {
-          // 5 minutes
-          warnings.push("Long audio/video files may impact app performance");
-          recommendations.push("Consider trimming to under 5 minutes");
-        }
-      }
-
-      return {
-        isValid: errors.length === 0,
-        errors,
-        warnings,
-        recommendations,
-      };
-    } catch (error) {
-      return {
-        isValid: false,
-        errors: [error instanceof Error ? error.message : "Validation failed"],
-        warnings: [],
-        recommendations: [],
-      };
-    }
-  }
-}