Terminal API: support Regions

[gcatanese]

Terminal API integrations must define the closest Region. This PR introduces several changes:

• Add RegionEnum to support the available regions
• Update Config object to include the region attribute (to allow setting the Region for the Terminal API integration)
• Refactor the Client constructor to enforce best practises: instantiate Client object passing the configuration in the Config object to simplify and centralise the configuration management

const config = new Config({
    apiKey: "myApiKey",
    environment: "LIVE",
    liveEndpointUrlPrefix: "myPrefix",
    region: RegionEnum.US
});
client = new Client(config);

‼️ This is a breaking change: all client configuration (API key, environment, region, live endpoint prefix) must be passed via the dedicated Config object. Previous overloaded constructors are removed.

• setEnvironment public method has been removed to enforce best practises: define instead the Config object
• define TEST and LIVE endpoints in the Config class
• add tests

Fix #1528

[gemini-code-assist]

Summary of Changes

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!

This pull request significantly enhances the Terminal API integration by introducing explicit region support and undertaking a major refactor of the client's configuration management. The changes centralize all environment and endpoint settings within a dedicated Config object, promoting a more robust and explicit setup for API interactions, especially in live environments.

Highlights

• Terminal API Region Support: I've introduced explicit support for geographical regions in the Terminal API integration. This includes defining a RegionEnum and mapping region-specific live endpoints, ensuring that integrations specify the closest region for optimal performance and compliance.
• Client Configuration Refactor: The Client constructor has been refactored to enforce a best practice: all client configuration, including API keys, environment, and now region and live endpoint prefixes, must be passed via a dedicated Config object. This removes previous overloaded constructors and the setEnvironment method, centralizing configuration management.
• Endpoint Management Centralization: All environment-specific endpoints (TEST/LIVE for Terminal API and MarketPay) are now managed directly within the Config class. This improves consistency and maintainability by making endpoint determination part of the configuration process rather than dynamic client methods.
• Stricter Live Environment Validation: I've added stricter validation to ensure that a liveEndpointUrlPrefix is always provided when the client is configured for a LIVE environment. This prevents common misconfigurations and ensures correct routing for live API calls.

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 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 or fill out our survey 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 pull request is a great step towards improving the client configuration by enforcing the use of the Config object and removing the mutable setEnvironment method. The introduction of RegionEnum for the Terminal API is also a welcome addition.

My review focuses on a few areas for improvement:

• Documentation: Updating a code example in the README.md to be self-contained and runnable.
• Code Duplication: Removing redundant validation logic in service.ts that is already handled in the Client constructor.
• Code Clarity: Simplifying logic in config.ts and removing a console.info side-effect from the Client constructor.

These changes will help improve the robustness and maintainability of the library. Overall, this is a solid refactoring.

[gcatanese]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request significantly enhances the library's capabilities for Terminal API integrations by introducing explicit support for geographical regions. It also undertakes a major refactoring of the client initialization process, centralizing all configuration into a dedicated Config object, which simplifies future management but introduces breaking changes for existing implementations.

Highlights

• Terminal API Region Support: Introduced a new RegionEnum and added a region property to the Config object. This enables the library to support region-specific Terminal API integrations by resolving the correct endpoint based on the specified region.
• Centralized Client Configuration (Breaking Change): Refactored the Client constructor to exclusively accept a Config object for all initialization parameters, including API key, environment, region, and live endpoint prefix. This is a breaking change, as all previous overloaded constructors and the setEnvironment public method have been removed.
• Streamlined Endpoint Management: Centralized the definition of TEST and LIVE API endpoints within the Config class. New static helper methods (isRegionValid, getTerminalApiEndpoint) were added to Config to facilitate region validation and dynamic endpoint retrieval for Terminal API.

Changelog

• README.md
  • Updated Client initialization examples to demonstrate the new Config object usage, including setting the LIVE environment and specifying a RegionEnum for Terminal API.
  • Added a new note clarifying that when using a custom HttpClient, all required properties (e.g., API key, content-type) must be defined by the user.
• src/mocks/base.ts
  • Modified the createClient mock function to align with the new Client constructor signature, now passing the Config object directly instead of an object containing it.
• src/tests/checkout.spec.ts
  • Updated the test case for missing live identifier on live environment to use client.config.environment = "LIVE" (line 387) instead of the removed client.setEnvironment("LIVE").
  • Adjusted the expected error message for missing live URL prefix to reflect the updated validation logic (line 394).
• src/tests/client.spec.ts
  • Added new tests to ensure the Client constructor throws an error if the environment is not defined (line 66).
  • Introduced tests to verify that an error is thrown if the environment is LIVE and an invalid region is provided (line 72).
  • Added tests to confirm that terminalApiCloudEndpoint is correctly set for both TEST (line 84) and LIVE (line 94) environments based on the specified region.
  • Included a new test to verify that connectionTimeoutMillis can be defined directly in the Config object (line 46).
  • Added tests for setting and getting a custom HTTP client (line 106) and setting the application name via setApplicationName (line 117).
• src/tests/service.spec.ts
  • Added a new test file to validate the Service class's createBaseUrl method, ensuring it correctly handles environment-specific URL transformations.
  • Included tests for scenarios where liveEndpointUrlPrefix is undefined or empty in a LIVE environment, verifying appropriate error handling (lines 31, 46, 78).
  • Tested the correct construction of pal- and checkout- URLs using the liveEndpointUrlPrefix (lines 62, 93, 108).
• src/client.ts
  • Removed all overloaded Client constructors and the setEnvironment method, enforcing that the Client can only be instantiated with a Config object (lines 5-20, 47-48, 78-89 removed).
  • Integrated the logic for setting terminalApiCloudEndpoint and marketPayEndpoint directly into the Client constructor, utilizing the Config object's environment and region properties (lines 43-62).
  • Deprecated static TERMINAL_API_ENDPOINT_TEST and TERMINAL_API_ENDPOINT_LIVE constants, advising users to refer to the Config class for these values (lines 15-17).
• src/config.ts
  • Defined TERMINAL_API_ENDPOINT_TEST and various TERMINAL_API_ENDPOINT_LIVE constants for different regions (lines 3-9).
  • Introduced RegionEnum to enumerate supported Terminal API regions (EU, AU, US, APSE) (lines 14-19).
  • Created TERMINAL_API_ENDPOINTS_MAP to map RegionEnum values to their respective live endpoints (lines 22-27).
  • Added liveEndpointUrlPrefix and region properties to both ConfigConstructor (lines 41-42) and the Config class (lines 59-60).
  • Implemented static methods isRegionValid (line 83) and getTerminalApiEndpoint (line 93) within the Config class for region validation and endpoint retrieval.
• src/service.ts
  • Updated the createBaseUrl method to retrieve liveEndpointUrlPrefix directly from this.client.config (lines 58, 63, 67, 74, 78), aligning with the centralized configuration.
  • Refined the error message for missing live URL prefix to be more generic (line 53).

Activity

• The SonarQube bot reported that the Quality Gate passed, with 2 new issues identified.
• The author, gcatanese, requested a Gemini summary.
• A review comment from gemini-code-assist[bot] (high priority) suggested removing redundant validation from Service.createBaseUrl (BaseCommentID: 2223834346). The author, gcatanese, responded that this validation is needed in case the environment is dynamically updated after client initialization.
• Another review comment from gemini-code-assist[bot] (medium priority) pointed out that RegionEnum was not imported in the README.md example and suggested using a string literal instead (BaseCommentID: 2223834354).
• A third review comment from gemini-code-assist[bot] (medium priority) advised against using console.info within the Client constructor, suggesting that the requirement for a region for Terminal API could be emphasized in JSDoc or the README (BaseCommentID: 2223834363).
• A fourth review comment from gemini-code-assist[bot] (medium priority) suggested removing a redundant fallback in Config.getTerminalApiEndpoint (BaseCommentID: 2223834366). The author, gcatanese, replied that the fallback is kept in case the method is called after the Client is initialized.

[gcatanese]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a Config object to simplify client configuration and adds support for Terminal API regions. The changes improve the library's usability and maintainability. I've provided comments to enhance documentation clarity, test readability, and eliminate redundant code. Addressing these suggestions will further improve the quality of this pull request.

[sonarqubecloud]

Quality Gate passed

Issues
2 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