Refactor Options pattern and APIs#21
Merged
Merged
Conversation
Introduce QueryParameterNameAttribute and refactor the Options/Request pattern across the SDK: removed several single-use Options classes, extracted required fields into direct method parameters, and converted remaining JsonPropertyName usages to QueryParameterName for query-building. Updated client interfaces and implementations (Main, Search, Relay, Stream, Torrents, Usenet, WebDownloads), adjusted examples and tests to new signatures, added README versioning note, and small cleanups (AuthHandler header using, formatting in DI extension). These changes simplify API usage and prepare the SDK for clearer query parameter handling; note this contains breaking signature changes intended before public release.
There was a problem hiding this comment.
Pull request overview
Refactors the SDK surface area to reduce “options object” usage for required parameters, simplifying example usage and aligning clients/interfaces with the new method signatures. Also introduces a query-parameter naming attribute and updates documentation.
Changes:
- Replaced several required “options” parameters with explicit required arguments across Main/Search/Relay clients (and updated interfaces, tests, and examples accordingly).
- Updated query/options models to remove now-required fields and added
QueryParameterNameAttributeannotations. - Added README documentation on Semantic Versioning and minor DI/AuthHandler cleanup.
Reviewed changes
Copilot reviewed 68 out of 68 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/TorboxSDK.UnitTests/Search/SearchApiClientTests.cs | Updates unit tests to call Search API methods with explicit parameters instead of options objects. |
| tests/TorboxSDK.UnitTests/Relay/RelayApiClientTests.cs | Updates Relay API unit tests for explicit authId/torrentId parameters. |
| tests/TorboxSDK.UnitTests/Models/WebDownloads/WebDownloadRequestTests.cs | Adjusts serialization tests after removing WebId from request options. |
| tests/TorboxSDK.UnitTests/Models/Usenet/UsenetRequestTests.cs | Adjusts serialization tests after removing UsenetId from request options. |
| tests/TorboxSDK.UnitTests/Models/Torrents/TorrentControlRequestTests.cs | Removes tests for deleted/changed options and updates remaining serialization expectations. |
| tests/TorboxSDK.UnitTests/Models/Torrents/RequestDownloadOptionsTests.cs | Updates request-download options serialization tests after removing required TorrentId. |
| tests/TorboxSDK.UnitTests/Models/Relay/RelayModelTests.cs | Removes serialization tests for deleted CheckInactiveOptions. |
| tests/TorboxSDK.UnitTests/Models/Notifications/NotificationModelTests.cs | Removes serialization tests for deleted GetIntercomHashOptions. |
| tests/TorboxSDK.UnitTests/Models/Common/CommonModelTests.cs | Updates cache-check options serialization tests after removing required hashes field from options. |
| tests/TorboxSDK.UnitTests/Main/WebDownloads/WebDownloadsClientTests.cs | Updates WebDownloads client tests to pass webId/hashes directly and treat options as optional. |
| tests/TorboxSDK.UnitTests/Main/Usenet/UsenetClientTests.cs | Updates Usenet client tests to pass usenetId/hashes directly and treat options as optional. |
| tests/TorboxSDK.UnitTests/Main/Torrents/TorrentsClientTests.cs | Updates Torrents client tests to pass torrentId/hash directly and treat options as optional. |
| tests/TorboxSDK.UnitTests/Main/Stream/StreamClientTests.cs | Updates Stream client tests for explicit required parameters and optional options object. |
| tests/TorboxSDK.UnitTests/Main/Notifications/NotificationsClientTests.cs | Updates Notifications client tests for explicit authId/email parameters. |
| tests/TorBoxSDK.IntegrationTests/Search/SearchApiClientIntegrationTests.cs | Updates Search integration tests for new SearchTorznabAsync/SearchNewznabAsync signatures. |
| tests/TorBoxSDK.IntegrationTests/Main/WebDownloads/WebDownloadsClientIntegrationTests.cs | Updates WebDownloads integration tests to pass hashes directly. |
| tests/TorBoxSDK.IntegrationTests/Main/Usenet/UsenetClientIntegrationTests.cs | Updates Usenet integration tests to pass hashes directly. |
| tests/TorBoxSDK.IntegrationTests/Main/Torrents/TorrentsClientIntegrationTests.cs | Updates Torrents integration tests for direct hashes/hash arguments. |
| tests/TorBoxSDK.IntegrationTests/Main/Notifications/NotificationsClientIntegrationTests.cs | Updates Notifications integration tests for explicit authId/email. |
| src/TorBoxSDK/TorBoxClient.cs | Reorders API client properties for readability without changing behavior. |
| src/TorBoxSDK/Search/SearchApiClient.cs | Refactors methods to accept explicit required params (id/guid, query/apiKey). |
| src/TorBoxSDK/Search/ISearchApiClient.cs | Updates Search interface signatures and XML docs for explicit parameters. |
| src/TorBoxSDK/Relay/RelayApiClient.cs | Refactors inactive-check method to accept explicit authId/torrentId. |
| src/TorBoxSDK/Relay/IRelayApiClient.cs | Updates Relay interface signature and XML docs for explicit parameters. |
| src/TorBoxSDK/Models/WebDownloads/RequestWebDownloadOptions.cs | Removes required WebId field and annotates remaining query params with QueryParameterName. |
| src/TorBoxSDK/Models/Usenet/RequestUsenetDownloadOptions.cs | Removes required UsenetId field and annotates remaining query params with QueryParameterName. |
| src/TorBoxSDK/Models/Torrents/RequestDownloadOptions.cs | Removes required TorrentId field and annotates remaining query params with QueryParameterName. |
| src/TorBoxSDK/Models/Torrents/GetTorrentInfoOptions.cs | Removes required Hash field; keeps optional query params only. |
| src/TorBoxSDK/Models/Torrents/ExportDataOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/Stream/GetStreamDataOptions.cs | Removes required tokens from options; keeps only optional indices. |
| src/TorBoxSDK/Models/Stream/CreateStreamOptions.cs | Removes required id/fileId/type from options; keeps only optional indices. |
| src/TorBoxSDK/Models/Search/UsenetSearchOptions.cs | Replaces JSON-name annotations with query-parameter name annotations. |
| src/TorBoxSDK/Models/Search/TorrentSearchOptions.cs | Replaces JSON-name annotations with query-parameter name annotations. |
| src/TorBoxSDK/Models/Search/SearchTorznabOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/Search/SearchNewznabOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/Search/MetaSearchOptions.cs | Replaces JSON-name annotation with query-parameter name annotation. |
| src/TorBoxSDK/Models/Search/DownloadUsenetOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/Relay/CheckInactiveOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/Queued/GetQueuedOptions.cs | Replaces JSON-name annotations with query-parameter name annotations. |
| src/TorBoxSDK/Models/Notifications/GetIntercomHashOptions.cs | Deletes options model in favor of explicit parameters. |
| src/TorBoxSDK/Models/General/SpeedtestOptions.cs | Replaces JSON-name annotations with query-parameter name annotations. |
| src/TorBoxSDK/Models/Common/GetMyListOptions.cs | Replaces JSON-name annotations with query-parameter name annotations. |
| src/TorBoxSDK/Models/Common/CheckCachedOptions.cs | Removes required hashes from options; annotates remaining optional query params. |
| src/TorBoxSDK/Main/WebDownloads/WebDownloadsClient.cs | Refactors RequestDownloadAsync/CheckCachedAsync to take required args directly and optional options object. |
| src/TorBoxSDK/Main/WebDownloads/IWebDownloadsClient.cs | Updates interface signatures and XML docs to match new parameter patterns. |
| src/TorBoxSDK/Main/Usenet/UsenetClient.cs | Refactors RequestDownloadAsync/CheckCachedAsync to take required args directly and optional options object. |
| src/TorBoxSDK/Main/Usenet/IUsenetClient.cs | Updates interface signatures and XML docs to match new parameter patterns. |
| src/TorBoxSDK/Main/Torrents/TorrentsClient.cs | Refactors download/cache/export/info methods to take required args directly; options become optional. |
| src/TorBoxSDK/Main/Torrents/ITorrentsClient.cs | Updates interface signatures and XML docs for new explicit parameter APIs. |
| src/TorBoxSDK/Main/Stream/StreamClient.cs | Refactors stream methods to accept required args directly; options become optional. |
| src/TorBoxSDK/Main/Stream/IStreamClient.cs | Updates Stream interface signatures and XML docs for explicit parameters. |
| src/TorBoxSDK/Main/Notifications/NotificationsClient.cs | Refactors Intercom hash method to accept explicit authId/email. |
| src/TorBoxSDK/Main/Notifications/INotificationsClient.cs | Updates Notifications interface signature and XML docs for explicit parameters. |
| src/TorBoxSDK/Http/QueryParameterNameAttribute.cs | Adds a new attribute to document query parameter names on option properties. |
| src/TorBoxSDK/Http/Handlers/AuthHandler.cs | Minor cleanup: uses AuthenticationHeaderValue with appropriate using. |
| src/TorBoxSDK/DependencyInjection/TorBoxServiceCollectionExtensions.cs | Formatting/readability changes for AddTorBox extension method signatures. |
| src/TorBoxSDK.Examples/Search/SearchMetaExample.cs | Updates examples to use new Search method signatures. |
| src/TorBoxSDK.Examples/Search/DownloadSearchResultsExample.cs | Updates example to call DownloadUsenetAsync with explicit id/guid. |
| src/TorBoxSDK.Examples/Relay/RelayExample.cs | Updates example to call CheckForInactiveAsync with explicit args. |
| src/TorBoxSDK.Examples/Main/WebDownloads/WebDownloadsAdvancedExample.cs | Updates example to pass hashes directly and options optionally. |
| src/TorBoxSDK.Examples/Main/WebDownloads/CreateWebDownloadExample.cs | Updates example to call RequestDownloadAsync with explicit webDownloadId. |
| src/TorBoxSDK.Examples/Main/Usenet/UsenetAdvancedExample.cs | Updates example to pass hashes directly and options optionally. |
| src/TorBoxSDK.Examples/Main/Usenet/CreateUsenetExample.cs | Updates example to call RequestDownloadAsync with explicit usenetId. |
| src/TorBoxSDK.Examples/Main/Torrents/DownloadTorrentExample.cs | Updates example to call download/export methods with explicit required args. |
| src/TorBoxSDK.Examples/Main/Torrents/CheckCachedExample.cs | Updates example to pass hashes/hash directly rather than via options object. |
| src/TorBoxSDK.Examples/Main/Stream/StreamExample.cs | Updates example to pass required stream args directly; optional indices via options. |
| src/TorBoxSDK.Examples/Main/Notifications/NotificationsExample.cs | Updates example to call Intercom hash method with explicit args. |
| README.md | Adds SemVer section and updates title formatting. |
Simplify the example by combining the multi-line Torrent search await into a single line for improved readability and consistency in the docs. This is a formatting-only change in docs/getting-started.md and introduces no functional changes.
Owner
Author
|
@copilot apply changes based on the comments in this thread |
Agent-Logs-Url: https://github.com/devRael1/TorBoxSDK/sessions/8eeffec2-05c2-41d9-89a5-9bde85ce1921 Co-authored-by: devRael1 <91017912+devRael1@users.noreply.github.com>
Introduce schema validation testing for TorBoxSDK: add a new guidance document detailing static and live OpenAPI-based tests, rules for fetching https://api.torbox.app/openapi.json (no local copy), and required infrastructure and mappings. Update test agent, tests skill, dev skill/job references, code-review instruction map, endpoint checklist, and integration guidance to include schema validation test workflows and registration of SchemaModelMapping entries. Also fix .gitignore trailing newline. These changes enable bidirectional schema checks (field/type coverage and live unmapped-field detection) and document CI/local filtering and API-key behavior.
Contributor
Applied the requested thread fixes in commit |
Delete the large generated open_api.json and introduce JSON serialization improvements and related updates. Adds SnakeCaseEnumConverter for snake_case enum handling and wires it into TorBoxJsonOptions; updates QueryParameterNameAttribute and model DownloadStatus to align naming/polymorphism changes. Adjusts RelayApiClient and example usage, and updates schema validation, integration and unit tests (fixtures, model mapping, and utilities) to match the new JSON/name-mapping behavior.
Change Changelog.Id from int to string (default empty) to match API responses. Update unit tests and model tests to expect string IDs and adjust assertions accordingly. Update schema live tests to use new routes (remove "/general" segment) for speedtest and changelogs endpoints. Add an /items/ folder entry to the solution referencing Directory.Build.props and Directory.Packages.props.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/devRael1/TorBoxSDK/sessions/00d5365b-7046-4dd5-b172-7581e14bee18 Co-authored-by: devRael1 <91017912+devRael1@users.noreply.github.com>
Agent-Logs-Url: https://github.com/devRael1/TorBoxSDK/sessions/00d5365b-7046-4dd5-b172-7581e14bee18 Co-authored-by: devRael1 <91017912+devRael1@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request refactors several example usages and interfaces in the SDK to simplify method signatures and improve clarity. The main focus is on replacing options objects with direct parameter passing for many client methods, making the code easier to use and understand. Additionally, there are minor improvements to documentation, dependency injection, and the addition of a utility attribute for query parameter mapping.
API and Example Usage Simplification:
Refactored many example usages throughout
src/TorBoxSDK.Examplesto pass parameters directly to client methods instead of wrapping them in options objects. This affects methods such asCheckCachedAsync,GetTorrentInfoAsync,RequestDownloadAsync,ExportDataAsync,GetIntercomHashAsync, and others across Torrents, Usenet, WebDownloads, Search, Stream, and Relay examples. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18]Updated the
INotificationsClientinterface to replace theGetIntercomHashAsyncmethod's options parameter with explicitauthIdandemailparameters, and updated corresponding documentation.Dependency Injection and Code Quality Improvements:
Simplified the method signatures for
AddTorBoxinTorBoxServiceCollectionExtensions, removing unnecessary line breaks and improving readability. [1] [2] [3]Minor code cleanup in
AuthHandler.cs, including using a direct reference toAuthenticationHeaderValueand adding a missingusingstatement. [1] [2]New Utility Attribute:
QueryParameterNameAttributeinTorBoxSDK.Httpto allow properties to specify their corresponding HTTP query parameter names, which helps with API documentation and query string building.Documentation:
Added a new section on Semantic Versioning to the
README.mdto clarify the project's versioning policy.Minor formatting fix for the README title.