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

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

@@ -0,0 +1,99 @@
+# CardMediaGenerationService
+
+## Purpose
+Service that performs AI-based media generation operations for flashcards, including text-to-image, text-to-audio, and image-search capabilities.
+
+## File Location
+`/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-media/src/infrastructure/services/CardMediaGenerationService`
+
+## Strategy
+- Generate media content using AI APIs for card applications
+- Support multiple generation types (text-to-image, text-to-audio, image-search)
+- Track processing time and credit/balance usage
+- Return card-compatible media attachments with position support
+- Provide detailed result information including success status and error messages
+- Enable batch generation with multiple results
+- Maintain unique request IDs for tracking and debugging
+
+## Forbidden
+- **DO NOT** generate media without checking available credits/balance
+- **DO NOT** use empty or null prompts for generation
+- **DO NOT** assume all generation requests will succeed
+- **DO NOT** ignore generation timeout limits
+- **DO NOT** generate inappropriate or copyrighted content
+- **DO NOT** proceed without error handling for API failures
+- **DO NOT** mix generation types in single requests
+- **DO NOT** bypass request ID tracking
+
+## Rules
+1. All generation operations must include a valid prompt
+2. Text-to-image generation requires prompt and optional style/maxResults
+3. Text-to-audio generation requires prompt, language, and optional voice/speed
+4. Image search requires keyword prompt and optional maxResults
+5. Credit costs vary by type: text-to-image (5), text-to-audio (3), image-search (2)
+6. All generated media must have position attribute set to 'both' by default
+7. Processing time must be tracked and returned in milliseconds
+8. Unique request IDs must be generated for each operation
+9. Generation failures must return clear error messages
+10. Audio files must be assigned a 10-second duration by default
+11. maxResults defaults to 1 for text-to-image, 5 for image-search
+
+## AI Agent Guidelines
+
+When working with CardMediaGenerationService:
+
+1. **Pre-generation Checks**: Always verify credit/balance before generation requests
+2. **Prompt Quality**: Use clear, descriptive prompts for better results
+3. **Type Selection**: Choose appropriate generation type for use case
+4. **Result Validation**: Always check success flag before using results
+5. **Error Handling**: Handle API failures, timeouts, and insufficient credits
+6. **Position Assignment**: Set correct position (front/back/both) for card use
+7. **Request Tracking**: Store request IDs for debugging and support
+
+### Generation Type Guidelines
+
+- **Text-to-Image**: Use for visual content on cards (front typically)
+  - Specify style (realistic, artistic) for better results
+  - Set maxResults to 1 unless multiple options needed
+  - Images receive position='both' by default
+
+- **Text-to-Audio**: Use for pronunciation or audio explanations
+  - Specify language code (tr-TR, en-US, etc.)
+  - Set voice type (male, female) if applicable
+  - Adjust speed (0.5-2.0) for playback preferences
+  - Audio receives 10-second duration by default
+
+- **Image Search**: Use for finding relevant visuals
+  - Use specific keywords for better results
+  - Set maxResults for multiple options
+  - Credits are cheaper than text-to-image
+
+### Credit Management
+
+- Calculate total credits before batch operations
+- Text-to-image: 5 credits per request
+- Text-to-audio: 3 credits per request
+- Image search: 2 credits per request
+- Handle insufficient credit errors gracefully
+- Track credits used from generation results
+
+### Error Handling Patterns
+
+- Check success flag before accessing attachments
+- Parse error messages for specific failure types:
+  - "insufficient credits" - balance too low
+  - "timeout" - operation took too long
+  - "invalid prompt" - prompt validation failed
+  - "api error" - underlying API failure
+
+### Performance Considerations
+
+- Generation operations are simulated (3 seconds delay)
+- Batch multiple results in single request when possible
+- Track processing time for performance monitoring
+- Use request IDs for debugging slow operations
+
+## Dependencies
+- CardMediaAttachment type from domain layer
+- AI generation APIs (simulated in development)
+- Credit/balance management system

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

@@ -0,0 +1,101 @@
+/**
+ * Card Media Generation Service
+ * Handles AI media generation (text-to-image, text-to-audio, image-search)
+ */
+
+import type {
+  CardMediaAttachment,
+  CardMediaGenerationRequest,
+  CardMediaGenerationResult,
+  CardMediaType,
+  CardMediaPosition,
+} from "../../domain/entities/CardMultimedia.types";
+
+export class CardMediaGenerationService {
+  /**
+   * Generate media from AI (text-to-image, text-to-audio, etc.)
+   */
+  async generateMedia(
+    request: CardMediaGenerationRequest,
+  ): Promise<CardMediaGenerationResult> {
+    try {
+      const startTime = Date.now();
+
+      // Simulate AI generation
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+
+      const attachments: CardMediaAttachment[] = [];
+
+      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 CardMediaType,
+              position: "both" as CardMediaPosition,
+              url: `https://picsum.photos/400/300?random=${Date.now() + i}`,
+              filename: `ai_generated_${i}.jpg`,
+              fileSize: 150000, // 150KB
+              mimeType: "image/jpeg",
+              isDownloaded: false,
+              createdAt: new Date().toISOString(),
+            });
+          }
+          break;
+
+        case "text_to_audio":
+          attachments.push({
+            id: `ai_audio_${Date.now()}`,
+            type: "audio" as CardMediaType,
+            position: "back" as CardMediaPosition,
+            url: `https://example.com/audio_${Date.now()}.mp3`,
+            filename: `ai_generated_${Date.now()}.mp3`,
+            fileSize: 80000, // 80KB
+            mimeType: "audio/mp3",
+            duration: 10, // 10 seconds
+            isDownloaded: false,
+            createdAt: new Date().toISOString(),
+          });
+          break;
+
+        case "image_search":
+          for (let i = 0; i < (request.options.maxResults || 5); i++) {
+            attachments.push({
+              id: `search_img_${Date.now()}_${i}`,
+              type: "image" as CardMediaType,
+              position: "both" as CardMediaPosition,
+              url: `https://picsum.photos/400/300?random=${Date.now() + i}`,
+              filename: `search_result_${i}.jpg`,
+              fileSize: 120000, // 120KB
+              mimeType: "image/jpeg",
+              isDownloaded: false,
+              createdAt: new Date().toISOString(),
+            });
+          }
+          break;
+      }
+
+      return {
+        success: true,
+        attachments,
+        creditsUsed:
+          request.type === "text_to_image"
+            ? 5
+            : request.type === "text_to_audio"
+              ? 3
+              : 2,
+        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/CardMediaOptimizerService.README.md

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

@@ -0,0 +1,36 @@
+/**
+ * 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(`[CardMediaOptimizerService] Deleting media: ${attachmentId}`);
+    }
+  }
+}

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

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

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