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

[github-actions]

Qodana Community for .NET

60 new problems were found

Inspection name	Severity	Problems
Redundant nullable warning suppression expression	🔶 Warning	8
Do not use object initializer for 'using' variable: Do not use object initializer for 'using' variable	🔶 Warning	8
Redundant using directive	🔶 Warning	7
Conditional access qualifier expression is not null according to nullable reference types' annotations	🔶 Warning	5
Inconsistent Naming	🔶 Warning	5
Namespace does not correspond to file location	🔶 Warning	3
Auto-property accessor is never used: Non-private accessibility	🔶 Warning	3
Use of obsolete symbol	🔶 Warning	1
Expression is always 'true' or 'false' according to nullable reference types' annotations	🔶 Warning	1
Invalid XML documentation comment	🔶 Warning	1
Type member is never used: Non-private accessibility	◽️ Notice	7
Type member is never accessed via base type: Non-private accessibility	◽️ Notice	3
Use UTF-8 string literal	◽️ Notice	2
Auto-property can be made get-only: Non-private accessibility	◽️ Notice	1
Class is never instantiated: Non-private accessibility	◽️ Notice	1
'if' statement can be rewritten as '?:' expression	◽️ Notice	1
Convert into lambda expression	◽️ Notice	1
Redundant string interpolation	◽️ Notice	1
Type is never used: Non-private accessibility	◽️ Notice	1

View the detailed Qodana report

To be able to view the detailed Qodana report, you can either:

• Register at Qodana Cloud and configure the action
• Use GitHub Code Scanning with Qodana
• Host Qodana report at GitHub Pages
• Inspect and use qodana.sarif.json (see the Qodana SARIF format for details)

To get *.log files or any other Qodana artifacts, run the action with upload-result option set to true,
so that the action will upload the files as the job artifacts:

      - name: 'Qodana Scan'
        uses: JetBrains/qodana-action@v2025.2.3
        with:
          upload-result: true

Contact Qodana team

Contact us at qodana-support@jetbrains.com

• Or via our issue tracker: https://jb.gg/qodana-issue
• Or share your feedback: https://jb.gg/qodana-discussions