GetAlbum and DownloadAlbum / Files

[ChaseDRedmon]

This PR introduces several new features, improvements, and infrastructure updates to the CatBox.NET library.

🚀 New Features

Album File Limit Enforcement

• Added MaxAlbumFiles constant (500) to centralize the CatBox album limit
• Added CatBoxAlbumFileLimitExceededException for clear error handling when limits are exceeded
• Added Throw.IfAlbumFileLimitExceeds() validation helper
• Validation is now enforced in CreateAlbumAsync and ModifyAlbumAsync operations

Capacity-Aware Uploads

• Added UploadImagesToAlbumSafeAsync() method that intelligently handles album capacity
• Fetches album first to determine available space
• Uploads only what fits within the 500-file limit
• Returns AlbumUploadResult with detailed metrics:
  • Files uploaded / skipped / remaining capacity

GetAlbum API Support

• Added GetAlbumAsync() to retrieve album information including file lists
• New request/response models: GetAlbumRequest, AlbumInfo, GetAlbumApiResponse

File & Album Downloads

• Added DownloadFileAsync() for single file downloads (skips if file exists)
• Added DownloadAlbumAsync() for batch album downloads (yields FileInfo per file)
• Supports both DirectoryInfo and string path overloads

URL Parsing Extensions

• ToCatboxImageName() - extracts filename from CatBox URLs
• ToAlbumShortCode() - extracts album ID from album URLs

⚡ Performance & Quality Improvements

Native AOT Compatibility

• Enabled IsAotCompatible flag in project file
• Added JSON source generation context (CatBoxJsonContext) for AOT scenarios
• Added CatBoxApiErrorResponse model for structured JSON error handling

Async Best Practices

• Added ToListAsync extension for IAsyncEnumerable
• Replaced ToBlockingEnumerable() with proper async/await patterns
• Added ConfigureAwait(false) throughout for library code best practices

Error Handling

• Improved retry policy to not retry client errors (4xx)
• Only retries HttpRequestException and server errors (5xx)
• Enhanced JSON error parsing for API responses

🧪 Testing

• Added unit tests for album file limit validation
• Added unit tests for URL parsing extensions
• Updated integration tests to use proper async/await patterns
• 127 unit tests passing

📁 Files Changed

• 24 files modified/added
• 4 new response models created
• 1 new request model created