fix: building

providers/Downloads/MIGRATION.md

@@ -0,0 +1,188 @@
+# Download Provider Migration Guide
+
+## Overview
+
+The DownloadProvider has been completely rewritten to use the new native `BackgroundDownloader` module instead of the third-party `@kesha-antonov/react-native-background-downloader` library.
+
+## What Changed
+
+### New Implementation
+
+- **Native Module**: Uses our custom `BackgroundDownloader` Expo module built with NSURLSession
+- **Simplified**: Focuses only on downloading video files
+- **Background Support**: True iOS background downloads with system integration
+- **Event-Driven**: Uses native event emitters for progress, completion, and errors
+
+### Removed Features (For Now)
+
+The following features from the old implementation have been temporarily removed to simplify the initial version:
+
+- ✗ Trickplay image downloads
+- ✗ Subtitle downloads
+- ✗ Series primary image caching
+- ✗ Intro/credit segment fetching
+- ✗ Download queue management with concurrent limits
+- ✗ Pause/Resume functionality
+- ✗ Speed calculation and ETA
+- ✗ Cache directory management
+
+### Maintained Features
+
+- ✓ Download video files with progress tracking
+- ✓ Database persistence (same structure)
+- ✓ Movies and Episodes support
+- ✓ Download notifications
+- ✓ File deletion and management
+- ✓ Downloaded items listing
+- ✓ Same context API
+
+## API Compatibility
+
+The public API remains mostly the same to avoid breaking existing code:
+
+### Working Methods
+
+```typescript
+const {
+  // Core functionality
+  startBackgroundDownload,
+  cancelDownload,
+  
+  // Database operations
+  getDownloadedItems,
+  getDownloadsDatabase,
+  getDownloadedItemById,
+  getDownloadedItemSize,
+  
+  // File management
+  deleteFile,
+  deleteItems,
+  deleteAllFiles,
+  
+  // State
+  processes,
+  APP_CACHE_DOWNLOAD_DIRECTORY,
+  appSizeUsage,
+} = useDownload();
+```
+
+### Deprecated (No-op) Methods
+
+These methods exist but do nothing in the new version:
+
+- `startDownload()` - Use `startBackgroundDownload()` instead
+- `pauseDownload()` - Not supported yet
+- `resumeDownload()` - Not supported yet
+- `deleteFileByType()` - Not needed (only video files)
+- `cleanCacheDirectory()` - Not needed
+- `updateDownloadedItem()` - Not needed
+- `dumpDownloadDiagnostics()` - Not needed
+
+## Migration Steps
+
+### For Developers
+
+1. **No code changes needed** if you're using `startBackgroundDownload()` and basic file management
+2. **Remove calls** to deprecated methods (they won't break but do nothing)
+3. **Test downloads** to ensure they work in your workflows
+
+### For Users
+
+- **No action required** - the new system uses the same database format
+- **Existing downloads** will still be accessible
+- **New downloads** will use the improved background system
+
+## Future Enhancements
+
+Planned features to add back:
+
+1. **Pause/Resume**: Using NSURLSession's built-in pause/resume
+2. **Queue Management**: Better control over concurrent downloads
+3. **Trickplay**: Re-add trickplay image downloading
+4. **Subtitles**: Download and link subtitle files
+5. **Progress Persistence**: Resume downloads after app restart
+6. **Cellular Control**: Respect cellular data settings
+7. **Speed/ETA**: Better download metrics
+
+## Database Structure
+
+The database structure remains unchanged:
+
+```typescript
+interface DownloadsDatabase {
+  movies: Record<string, DownloadedItem>;
+  series: Record<string, DownloadedSeries>;
+  other: Record<string, DownloadedItem>;
+}
+
+interface DownloadedItem {
+  item: BaseItemDto;
+  mediaSource: MediaSourceInfo;
+  videoFilePath: string;
+  videoFileSize: number;
+  videoFileName?: string;
+  trickPlayData?: TrickPlayData;
+  introSegments?: MediaTimeSegment[];
+  creditSegments?: MediaTimeSegment[];
+  userData: UserData;
+}
+```
+
+## Known Differences
+
+1. **Progress Updates**: More frequent and accurate with native module
+2. **Background Handling**: Better iOS background download support
+3. **Error Messages**: Different error format from native module
+4. **File Paths**: Uses `Paths.document` instead of cache directory
+5. **No Queue**: Downloads start immediately (no queuing system yet)
+
+## Troubleshooting
+
+### Downloads not starting
+
+- Check that the iOS app has been rebuilt with the new native module
+- Verify network permissions
+- Check console logs for errors
+
+### Progress not updating
+
+- Ensure event listeners are properly registered
+- Check that the task ID mapping is correct
+- Verify the download is still active
+
+### Files not found
+
+- Old downloads might be in a different location
+- Re-download content if files are missing
+- Check file permissions
+
+## Old Implementation
+
+The old implementation has been preserved at:
+- `providers/DownloadProvider.deprecated.tsx`
+
+You can reference it if needed, but it should not be used in production.
+
+## Testing
+
+After migration, test these scenarios:
+
+- [ ] Download a movie
+- [ ] Download an episode
+- [ ] Download multiple items
+- [ ] Cancel a download
+- [ ] Delete a downloaded item
+- [ ] View downloaded items list
+- [ ] Background app during download
+- [ ] Force quit and restart app
+- [ ] Verify notifications appear
+- [ ] Check file sizes are correct
+
+## Questions?
+
+If you encounter issues with the migration, please:
+1. Check the console logs
+2. Verify the native module is installed
+3. Review the old implementation for reference
+4. Open an issue with details
+

providers/Downloads/README.md

@@ -0,0 +1,228 @@
+# Download System
+
+This directory contains the types and utilities for the download system in Streamyfin.
+
+## Architecture
+
+### DownloadProvider
+
+The `DownloadProvider` is a React context provider that manages all download operations in the app. It uses a custom native `BackgroundDownloader` module for iOS to enable true background downloads.
+
+**Location**: `providers/DownloadProvider.tsx`
+
+### Key Features
+
+1. **Background Downloads**: Downloads continue even when app is backgrounded
+2. **Progress Tracking**: Real-time progress updates via native events
+3. **Persistent Storage**: Downloads are saved to device storage and tracked in a JSON database
+4. **Type Safety**: Full TypeScript support with proper types
+5. **Notifications**: System notifications for download completion/errors
+
+### Database Structure
+
+Downloads are persisted in MMKV storage with the key `downloads.v2.json`:
+
+```typescript
+interface DownloadsDatabase {
+  movies: Record<string, DownloadedItem>;
+  series: Record<string, DownloadedSeries>;
+  other: Record<string, DownloadedItem>;
+}
+```
+
+### Download Flow
+
+1. **Start Download**
+   ```typescript
+   await startBackgroundDownload(url, item, mediaSource, maxBitrate);
+   ```
+
+2. **Track Progress**
+   - Native module emits progress events
+   - Provider updates `processes` state
+   - UI reflects current progress
+
+3. **Handle Completion**
+   - File is moved to permanent location
+   - Database is updated
+   - User receives notification
+   - Process is cleaned up
+
+4. **Error Handling**
+   - Errors are caught and logged
+   - User receives error notification
+   - Process is marked as failed and removed
+
+## Types
+
+### JobStatus
+
+Represents an active download job:
+
+```typescript
+type JobStatus = {
+  id: string;                    // Item ID
+  inputUrl: string;              // Download URL
+  item: BaseItemDto;             // Jellyfin item
+  itemId: string;                // Item ID
+  deviceId: string;              // Device identifier
+  progress: number;              // 0-100
+  status: DownloadStatus;        // Current status
+  timestamp: Date;               // Created/updated time
+  mediaSource: MediaSourceInfo;  // Media source info
+  maxBitrate: Bitrate;          // Selected bitrate
+  bytesDownloaded?: number;      // Bytes downloaded
+  lastProgressUpdateTime?: Date; // Last update time
+};
+```
+
+### DownloadedItem
+
+Represents a completed download in the database:
+
+```typescript
+interface DownloadedItem {
+  item: BaseItemDto;
+  mediaSource: MediaSourceInfo;
+  videoFilePath: string;
+  videoFileSize: number;
+  videoFileName?: string;
+  trickPlayData?: TrickPlayData;
+  introSegments?: MediaTimeSegment[];
+  creditSegments?: MediaTimeSegment[];
+  userData: UserData;
+}
+```
+
+## Usage Examples
+
+### Basic Download
+
+```typescript
+import { useDownload } from '@/providers/DownloadProvider';
+
+function MyComponent() {
+  const { startBackgroundDownload } = useDownload();
+
+  const handleDownload = async () => {
+    await startBackgroundDownload(
+      downloadUrl,
+      jellyfinItem,
+      mediaSource,
+      selectedBitrate
+    );
+  };
+}
+```
+
+### Monitor Progress
+
+```typescript
+function DownloadsList() {
+  const { processes } = useDownload();
+
+  return (
+    <View>
+      {processes.map(process => (
+        <ProgressBar 
+          key={process.id}
+          progress={process.progress}
+          title={process.item.Name}
+        />
+      ))}
+    </View>
+  );
+}
+```
+
+### List Downloaded Items
+
+```typescript
+function DownloadedList() {
+  const { getDownloadedItems } = useDownload();
+  const items = getDownloadedItems();
+
+  return (
+    <FlatList
+      data={items}
+      renderItem={({ item }) => (
+        <ItemCard item={item.item} />
+      )}
+    />
+  );
+}
+```
+
+### Delete Downloads
+
+```typescript
+function DeleteButton({ itemId }: { itemId: string }) {
+  const { deleteFile } = useDownload();
+
+  const handleDelete = async () => {
+    await deleteFile(itemId);
+  };
+
+  return <Button onPress={handleDelete} title="Delete" />;
+}
+```
+
+## File Storage
+
+Downloads are stored in the app's Documents directory:
+
+```
+Documents/
+  └── [filename].mp4
+```
+
+Filenames are generated based on item type:
+- Movies: `{title}_{year}.mp4`
+- Episodes: `{series}_s{season}e{episode}.mp4`
+
+## Native Module Integration
+
+The provider uses the `BackgroundDownloader` native module:
+
+```typescript
+import { BackgroundDownloader } from '@/modules';
+
+// Start download
+const taskId = await BackgroundDownloader.startDownload(url, destPath);
+
+// Listen for events
+BackgroundDownloader.addProgressListener(event => {
+  // Handle progress
+});
+
+BackgroundDownloader.addCompleteListener(event => {
+  // Handle completion
+});
+
+BackgroundDownloader.addErrorListener(event => {
+  // Handle error
+});
+```
+
+## Platform Support
+
+- **iOS**: Full support with background downloads
+- **Android**: Planned
+- **tvOS**: Disabled (returns no-op functions)
+
+## Migration
+
+If upgrading from the old download system, see [MIGRATION.md](./MIGRATION.md) for details.
+
+## Future Improvements
+
+- [ ] Add pause/resume functionality
+- [ ] Implement download queue with concurrent limits
+- [ ] Add trickplay image downloads
+- [ ] Add subtitle downloads
+- [ ] Add intro/credit segment detection
+- [ ] Persist downloads across app restarts
+- [ ] Add cellular data controls
+- [ ] Improve download speed calculation
+- [ ] Add download size estimates
+