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

package/src/media/index.ts.README.md

@@ -0,0 +1,191 @@
+# @umituz/react-native-media - Main Export
+
+## Purpose
+Main entry point for the library. Exports all services, hooks, types, and utilities for media management in React Native applications.
+
+## File Location
+`src/index.ts`
+
+## Strategy
+- Provide a single import point for all library functionality
+- Organize exports by category (services, hooks, types, utils)
+- Enable tree-shaking by using named exports
+- Maintain clear separation between general media and card-specific features
+- Support both individual imports and bulk imports
+
+## Forbidden
+- **DO NOT** add default exports - only named exports
+- **DO NOT** re-export external dependencies directly
+- **DO NOT** create circular import dependencies
+- **DO NOT** mix categories in export groups
+- **DO NOT** export internal implementation details
+- **DO NOT** use wildcard exports from sub-modules
+- **DO NOT** change export names once published
+
+## Rules
+1. All public exports must be re-exported from this file
+2. Exports must be organized by category (services, hooks, types, utils)
+3. Each category must be clearly commented
+4. General media features must be separate from card-specific features
+5. Type exports must use `export type` for tree-shaking
+6. Service exports must be singleton instances or static classes
+7. Hook exports must be named with `use` prefix
+8. All exports must have TypeScript types
+9. Breaking changes require major version bump
+10. All exports must be documented in their respective README files
+
+## AI Agent Guidelines
+
+### Import Strategy
+
+When working with this library:
+
+1. **Single Entry Point**: All imports should come from `@umituz/react-native-media`
+2. **Specific Imports**: Import only what you need for better tree-shaking
+3. **Type Imports**: Use `import type` for type-only imports
+4. **Category Awareness**: Understand the difference between general and card-specific features
+
+### Export Categories
+
+#### Services (Infrastructure Layer)
+All services follow singleton pattern:
+- `MediaPickerService` - Image/video selection from camera and gallery
+- `MediaSaveService` - Saving media to device gallery
+- `MediaUploadService` - Upload/download media and URL management
+- `MediaGenerationService` - AI-powered text-to-image and text-to-audio
+- `MediaValidationService` - File validation before upload
+- `MediaOptimizerService` - Compression and optimization
+- `CardMultimediaService` - Card-specific media operations
+- `CardMediaGenerationService` - Card AI generation with image search
+- `CardMediaUploadService` - Card upload with position support
+- `CardMediaValidationService` - Card validation with stricter rules
+- `CardMediaOptimizerService` - Card optimization
+- `MultimediaFlashcardService` - Main flashcard service
+- `CardMultimediaFlashcardService` - Main card flashcard service
+
+#### Hooks (Presentation Layer)
+All hooks are named with `use` prefix:
+
+**General Media Hooks:**
+- `useMedia` - Core media selection and camera
+- `useMediaUpload` - Upload with progress tracking
+- `useMediaGeneration` - AI generation
+- `useMediaValidation` - Pre-upload validation
+- `useMultimediaFlashcard` - Flashcard creation
+
+**Card-Specific Hooks:**
+- `useCardMultimediaFlashcard` - Card flashcard management
+- `useCardMediaGeneration` - Card AI generation
+- `useCardMediaUpload` - Card upload with position
+- `useCardMediaValidation` - Card validation
+
+#### Types (Domain Layer)
+Organized by functionality:
+
+**Basic Types:**
+- `MediaType` - Media type enum (IMAGE, VIDEO, ALL)
+- `ImageFormat` - Format enum (JPEG, PNG, WEBP)
+- `MediaQuality` - Quality enum (LOW, MEDIUM, HIGH)
+- `MediaLibraryPermission` - Permission states
+- `MediaAsset` - Media file properties
+- `MediaPickerResult` - Picker return type
+- `MediaPickerOptions` - Picker configuration
+- `CameraOptions` - Camera configuration
+
+**Card Types:**
+- `CardMediaType` - Card media types
+- `CardMediaPosition` - Position (FRONT, BACK, BOTH)
+- `CardMediaAttachment` - Card media with position
+- `CardMultimediaFlashcard` - Card entity
+- `CardMediaGenerationRequest` - Generation request
+- `CardMediaGenerationResult` - Generation result
+- `CardMediaUploadProgress` - Upload progress
+- `CardMediaCompressionOptions` - Compression options
+- `CardMediaValidation` - Validation result
+
+**Flashcard Types:**
+- `MediaAttachment` - General media attachment
+- `MultimediaFlashcard` - Flashcard entity
+- `MediaGenerationRequest` - Generation request
+- `MediaGenerationResult` - Generation result
+
+#### Utils (Domain & Infrastructure)
+Utility functions and helpers:
+
+**Domain Utils:**
+- `MediaUtils` - Core media utilities
+
+**Infrastructure Utils:**
+- Helper functions for media operations
+- Mapper functions for type conversions
+
+### Module Selection Guidelines
+
+#### Use General Media Features When:
+- Working with standard media operations
+- No card/flashcard requirements
+- Need basic upload/download/validation
+- Building general-purpose media features
+
+#### Use Card-Specific Features When:
+- Building flashcard applications
+- Need position-based media (front/back)
+- Working with card entities
+- Need card-specific validation rules
+- Using card generation or upload services
+
+### Dependency Rules
+
+1. **Services** can be used independently or through hooks
+2. **Hooks** wrap services and provide React state management
+3. **Types** are used by both services and hooks
+4. **Utils** provide helper functions used across layers
+
+### Common Import Patterns
+
+**Service-only usage:**
+- Import service classes directly
+- Use for non-React code or direct service access
+- Services follow singleton pattern
+
+**Hook usage (recommended for React components):**
+- Import hooks for React components
+- Hooks provide state management
+- Hooks wrap services with React integration
+
+**Type imports:**
+- Use `import type` for type-only imports
+- Enables tree-shaking
+- Better IDE support
+
+**Combined imports:**
+- Mix services, hooks, and types as needed
+- All imports from single entry point
+- Named exports only
+
+## File Structure Reference
+
+The library follows Clean Architecture with three main layers:
+
+**Domain Layer** (`src/domain/`)
+- `entities/` - Core type definitions and interfaces
+- `utils/` - Domain utility functions
+
+**Infrastructure Layer** (`src/infrastructure/`)
+- `services/` - Service implementations with external integrations
+- `utils/` - Helper functions and mappers
+
+**Presentation Layer** (`src/presentation/`)
+- `hooks/` - React hooks for UI integration
+
+**Main Export** (`src/index.ts`)
+- Single entry point for all exports
+- Organized by category
+- This file
+
+## Dependencies
+
+- Exports all domain entities and types
+- Exports all infrastructure services
+- Exports all presentation hooks
+- Re-exports utilities from domain and infrastructure layers

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