Description

This change implements the returnPartialSuccess option for the getBuckets (or ListBuckets) method to handle scenarios where the external API returns a successful response but includes an unreachable list of resources.

• New Option: The boolean parameter returnPartialSuccess is added to the GetBucketsRequest interface.
• Behavior on true: If returnPartialSuccess is set to true and the API response contains resp.unreachable items, the method will execute the callback successfully (with err: null) and pass the array of unreachable bucket IDs as the fifth argument to the callback function.
• Existing Behavior Preservation: If the option is false (or not set) and unreachable items are present, the function follows the existing failure flow (or implicitly returns success, depending on the previous behavior).
• API Payload: The returnPartialSuccess parameter is correctly included in the query string (qs) sent to the API endpoint, as it is a known API parameter.

Impact

This change significantly improves the robustness of the ListBuckets operation. Users can now choose to tolerate minor, non-critical failures (like temporary unavailability of a few regions) and successfully retrieve and process the majority of available buckets, preventing a complete application failure.

Testing

• Unit Tests: Yes, new unit tests have been added to cover the new logic.
  • New Test Cases: Added tests specifically verifying the 5-argument callback signature when returnPartialSuccess: true is set and the API returns an unreachable array.
  • Coverage: Confirmed correct behavior for full success, full failure, and the two partial success/failure modes.
• Tests Changed: No existing tests were changed, only new ones were added.
• Breaking Changes: No breaking changes are necessary for existing users. The fifth callback argument (unreachable) is strictly optional (?) and is only provided when explicitly enabled via the new option.

Additional Information

• This implementation relies on the established convention of the underlying API returning unreachable resource IDs in the resp.unreachable property on a successful HTTP status code.
• The use of a 5th argument in the callback (unreachable) was chosen to avoid modifying the primary result type (Bucket[]) and to maintain compatibility with existing consumers who expect the 4-argument signature.

Checklist

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease
• Appropriate docs were updated
• Appropriate comments were added, particularly in complex areas or places that require background
• No new warnings or issues will be generated from this change

Fixes # 🦕