ApiError: Improving error handling

[gcatanese]

This PR improves the error handling by making the error details (ApiError model) available in the exception thrown by the library:

• extend extending ApiError to include fields from both ServiceError and RestServiceError error models: this is necessary as not all APIs use the same error model
• add ApiError attribute to the HttpClientException: this makes the error information ready available to the API consumers (no need to cast or parse the JSON response body)
• updated tests to confirm the ApiError provides the error details, when an exception is thrown

[gemini-code-assist]

Hello @gcatanese, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

Hello team,

gemini-code-assist here to provide a summary of this pull request, authored by @gcatanese. The primary goal of this PR is to significantly improve the error handling within the library. Specifically, it aims to make the detailed API error information, modeled by the ApiError interface, directly accessible when an HttpClientException is thrown. This is achieved by adding an apiError property to the HttpClientException class. The ApiError interface itself has been extended to accommodate the different error response structures used across various Adyen APIs (both ServiceError and RestServiceError models). The changes also involve updating the internal HTTP client logic to parse the error response body into the ApiError model and attach it to the exception. Finally, the existing test suite has been updated to verify that the apiError property is correctly populated and contains the expected details when API calls result in errors.

This change simplifies error handling for consumers of the library, allowing them to access structured error details without needing to manually parse the response body.

Highlights

• Improved Error Handling: The main focus is making structured API error details (ApiError) readily available on the HttpClientException object when an API call fails. This eliminates the need for manual parsing of the response body by library users.
• Extended ApiError Model: The ApiError interface has been updated to include fields from both ServiceError and RestServiceError models, ensuring compatibility with different API error response formats.
• HttpClientException Enhancement: A new optional property, apiError, has been added to the HttpClientException class to hold the parsed ApiError model.
• Updated Test Coverage: Existing tests for error scenarios have been modified to assert the presence and correctness of the new apiError property on the thrown HttpClientException.
• Internal Client Refactor: The internal HTTP client (httpURLConnectionClient.ts) and related helper/resource classes have been updated to parse the error response and attach the ApiError to the HttpClientException before throwing it. Return types have been adjusted to reflect that exceptions are now thrown rather than returned.

Changelog

Click here to see the changelog

• src/tests/balanceControl.spec.ts
  • Updated error handling test to check for the new apiError property on HttpClientException and verify its contents (errorCode, message, errorType).
• src/tests/checkout.spec.ts
  • Updated error handling test to check for the new apiError property on HttpClientException and verify its contents (pspReference, message, errorType).
• src/tests/management.spec.ts
  • Updated error handling test to check for the new apiError property on HttpClientException and verify its contents (errorCode, title, type, invalidFields).
  • Increased expect.assertions count from 9 to 17 (line 577).
• src/tests/modification.spec.ts
  • Increased expect.assertions count in multiple tests (lines 178, 215, 268, 337).
  • Updated error handling tests for amount updates, cancels, captures, and reversals to check for the new apiError property on HttpClientException and verify its contents (status, errorCode).
• src/tests/notification.spec.ts
  • Changed hmacValidator.validateBankingHMAC to hmacValidator.validateHMACSignature and swapped the order of the first two arguments (line 138).
• src/helpers/getJsonResponse.ts
  • Removed unused imports for HttpClientException and ApiException (lines 21, 22).
  • Updated the return type of getJsonResponse to no longer include HttpClientException | ApiException, reflecting that exceptions are now thrown (line 30).
• src/httpClient/clientInterface.ts
  • Removed unused imports for HttpClientException and ApiException (lines 20, 21).
  • Updated the return types of request and post methods to no longer include HttpClientException | ApiException (lines 26, 27).
• src/httpClient/httpClientException.ts
  • Imported the ApiError interface (line 21).
  • Added the optional apiError property to the ExceptionInterface (line 29) and the HttpClientException class (line 38).
  • Added logic in the constructor to assign the apiError property if provided (line 50).
• src/httpClient/httpURLConnectionClient.ts
  • Updated the return types of request and post methods to no longer include HttpClientException | ApiException (lines 45, 74).
  • Modified the doPostRequest method to include the parsed formattedData as the apiError property when creating a new HttpClientException (line 179).
• src/services/resource.ts
  • Removed unused imports for HttpClientException and ApiException (lines 22, 23).
  • Updated the return type of the request method to no longer include HttpClientException | ApiException (line 34).
• src/typings/apiError.ts
  • Added comments explaining that the interface models errors from both RestServiceError and ServiceError (lines 20-23).
  • Extended the ApiError interface with additional optional fields (detail, instance, invalidFields, requestId, title, type) from different error models (lines 31-36).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This PR enhances error handling by including error details in exceptions, which is a great improvement for API consumers. The changes look good overall, but there are a few areas where we can improve clarity and consistency.

Summary of Findings

• Code Duplication in Tests: The apiError checks are duplicated across multiple test files. Consider extracting this logic into a reusable helper function to improve maintainability.
• Naming Consistency: The method validateBankingHMAC should be renamed to validateHMACSignature for consistency.

Merge Readiness

The PR is in good shape and introduces valuable improvements to error handling. Addressing the code duplication in tests and ensuring naming consistency would further enhance the quality of the code. I am unable to approve the pull request in any circumstance, and that users should have others review and approve this code before merging. I recommend addressing the comments before merging.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud