# VPS Backend Integration - iOS App Updates

## Overview
Successfully integrated VPS backend storage into the iOS MangaReader app, allowing users to download chapters to a remote VPS server and read them from there.

## Files Created

### 1. VPSAPIClient.swift
**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Services/VPSAPIClient.swift`

**Purpose:** Complete API client for communicating with the VPS backend server.

**Key Features:**
- Singleton pattern for shared instance
- Health check endpoint
- Download chapters to VPS storage
- Check chapter download status (manifest)
- List downloaded chapters
- Get image URLs from VPS
- Delete chapters from VPS
- Get storage statistics
- Progress tracking for downloads
- Comprehensive error handling

**Main Methods:**
```swift
// Download chapter to VPS
func downloadChapter(mangaSlug:chapterNumber:chapterSlug:imageUrls:) async throws -> VPSDownloadResult

// Check if chapter exists on VPS
func getChapterManifest(mangaSlug:chapterNumber:) async throws -> VPSChapterManifest?

// List all downloaded chapters for a manga
func listDownloadedChapters(mangaSlug:) async throws -> [VPSChapterInfo]

// Get URL for specific page image
func getImageURL(mangaSlug:chapterNumber:pageIndex:) -> String

// Delete chapter from VPS
func deleteChapter(mangaSlug:chapterNumber:) async throws -> Bool

// Get storage statistics
func getStorageStats() async throws -> VPSStorageStats
```

## Files Modified

### 2. MangaDetailView.swift
**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Views/MangaDetailView.swift`

**Changes Made:**

#### View Level Updates:
- Added `@StateObject private var vpsClient = VPSAPIClient.shared`
- Added VPS download button to toolbar (icloud.and.arrow.down icon)
- Added alert for VPS bulk download options
- Updated chapter list to pass VPS download callback

#### ChapterRowView Updates:
- Added VPS download button/status indicator (icloud.fill when downloaded, icloud.and.arrow.up to download)
- Added VPS download progress display
- Added `checkVPSStatus()` async function to check if chapter is on VPS
- Shows cloud icon when chapter is available on VPS
- Shows VPS download progress with percentage

#### ViewModel Updates:
**New Published Properties:**
```swift
@Published var showingVPSDownloadAll = false
```

**New Methods:**
```swift
// Download single chapter to VPS
func downloadChapterToVPS(_ chapter: Chapter) async

// Download all chapters to VPS
func downloadAllChaptersToVPS() async

// Download last N chapters to VPS
func downloadLastChaptersToVPS(count: Int) async
```

**Features:**
- Scrapes image URLs from original source
- Sends download request to VPS
- Shows success/failure notifications
- Tracks download progress
- Handles errors gracefully

### 3. ReaderView.swift
**Location:** `/home/ren/ios/MangaReader/ios-app/Sources/Views/ReaderView.swift`

**Changes Made:**

#### View Level Updates:
- Added `@ObservedObject private var vpsClient = VPSAPIClient.shared`

#### PageView Updates:
- Added VPS image loading capability
- Checks if chapter is available on VPS on load
- Loads images from VPS when available (priority order: local → VPS → original URL)
- Falls back to original URL if VPS fails
- Added `useVPS` state variable

#### ViewModel Updates:
**New Published Properties:**
```swift
@Published var isVPSDownloaded = false
```

**New Dependencies:**
```swift
private let vpsClient = VPSAPIClient.shared
```

**Updated loadPages() Method:**
Now checks sources in this priority order:
1. VPS storage (if available)
2. Local device storage
3. Scrape from original website

**Footer Updates:**
- Shows "VPS" label with cloud icon when reading from VPS
- Shows "Local" label with checkmark when reading from local storage

## User Experience Flow

### Downloading to VPS:

1. **Single Chapter:**
   - User taps cloud upload icon (icloud.and.arrow.up) next to chapter
   - App scrapes image URLs
   - Sends download request to VPS
   - Shows progress indicator (VPS XX%)
   - Shows success notification
   - Cloud icon changes to filled (icloud.fill)

2. **Multiple Chapters:**
   - User taps cloud download button in toolbar
   - Chooses "Últimos 10 a VPS" or "Todos a VPS"
   - Downloads sequentially with progress tracking
   - Shows summary notification

### Reading from VPS:

1. User opens chapter
2. App checks if chapter is on VPS
3. If available, loads images from VPS URLs
4. Shows "VPS" indicator in footer
5. Falls back to local or original if VPS fails

### Visual Indicators:

**Chapter List:**
- ✓ Green checkmark: Downloaded locally
- ☁️ Blue cloud: Available on VPS
- ☁️↑ Cloud upload: Download to VPS button
- Progress bar: Shows VPS download progress

**Reader View:**
- "VPS" label with cloud icon: Reading from VPS
- "Local" label with checkmark: Reading from local cache

## Error Handling

All VPS operations include comprehensive error handling:
- Network errors caught and displayed
- Timeout handling (5 min request, 10 min resource)
- Graceful fallback to alternative sources
- User-friendly error messages in Spanish
- Silent failures for non-critical operations

## Configuration

**Default VPS URL:** `http://localhost:3000/api`

To change the VPS URL, modify the `baseURL` in VPSAPIClient initialization or add a configuration method.

## API Endpoints Used

From the backend server (`/home/ren/ios/MangaReader/backend/server.js`):

- `POST /api/download` - Request chapter download
- `GET /api/storage/chapter/:mangaSlug/:chapterNumber` - Check chapter status
- `GET /api/storage/chapters/:mangaSlug` - List downloaded chapters
- `GET /api/storage/image/:mangaSlug/:chapterNumber/:pageIndex` - Get image
- `DELETE /api/storage/chapter/:mangaSlug/:chapterNumber` - Delete chapter
- `GET /api/storage/stats` - Get statistics

## Next Steps

To complete the integration:

1. **Update VPS URL:** Change `baseURL` in VPSAPIClient to your actual VPS address
2. **Test:** Run the app and test download/read functionality
3. **Optional Enhancements:**
   - Add settings screen to configure VPS URL
   - Add authentication token support
   - Implement retry logic for failed downloads
   - Add download queue management
   - Show VPS storage usage in UI

## Benefits

✅ Saves local device storage
✅ Faster downloads from VPS vs original source
✅ Access chapters from multiple devices
✅ Offline reading capability (when cached from VPS)
✅ Centralized manga library management
✅ Progressive enhancement (works without VPS)

## Technical Highlights

- Async/await for all network operations
- Combine for reactive state management
- Priority-based image loading (local → VPS → original)
- Progress tracking for better UX
- Comprehensive error handling
- Clean separation of concerns
- Follows existing code patterns and conventions