PTHMINT-117: terminals and terminal-groups APIs and tests

examples/terminal_group_manager/get_terminals_by_group.py

@@ -0,0 +1,57 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+import os
+
+from dotenv import load_dotenv
+
+from multisafepay import Sdk
+from multisafepay.client import ScopedCredentialResolver
+
+# Load environment variables from a .env file
+load_dotenv()
+
+default_account_api_key = (os.getenv("API_KEY") or "").strip()
+partner_affiliate_api_key = (os.getenv("PARTNER_API_KEY") or "").strip()
+
+terminal_group_id = os.getenv(
+    "CLOUD_POS_TERMINAL_GROUP_ID",
+    "<terminal_group_id>",
+).strip()
+
+if __name__ == "__main__":
+    # get_terminals_by_group → partner_affiliate scope → resolver returns
+    # partner_affiliate_api_key, falls back to default_api_key
+    resolver_kwargs = {
+        "default_api_key": default_account_api_key,
+        "partner_affiliate_api_key": partner_affiliate_api_key,
+    }
+
+    credential_resolver = ScopedCredentialResolver(**resolver_kwargs)
+
+    multisafepay_sdk = Sdk(
+        is_production=False,
+        credential_resolver=credential_resolver,
+    )
+
+    # Get the 'TerminalGroup' manager from the SDK
+    terminal_group_manager = multisafepay_sdk.get_terminal_group_manager()
+
+    # Define optional pagination parameters
+    options = {
+        "limit": 10,
+        "page": 1,
+    }
+
+    # Fetch terminals assigned to the specified terminal group
+    terminals_by_group_response = terminal_group_manager.get_terminals_by_group(
+        terminal_group_id=terminal_group_id,
+        options=options,
+    )
+
+    # Print the terminal listing data
+    print(terminals_by_group_response.get_data())

examples/terminal_manager/create.py

@@ -0,0 +1,61 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+import os
+
+from dotenv import load_dotenv
+
+from multisafepay import Sdk
+from multisafepay.api.paths.terminals.request.create_terminal_request import (
+    CreateTerminalRequest,
+)
+from multisafepay.client import ScopedCredentialResolver
+
+# Load environment variables from a .env file
+load_dotenv()
+
+default_account_api_key = (os.getenv("API_KEY") or "").strip()
+partner_affiliate_api_key = (os.getenv("PARTNER_API_KEY") or "").strip()
+
+terminal_group_id_raw = os.getenv(
+    "CLOUD_POS_TERMINAL_GROUP_ID",
+    "<terminal_group_id>",
+).strip()
+
+if __name__ == "__main__":
+    # create_terminal → default scope → resolver returns default_api_key
+    terminal_group_id = int(terminal_group_id_raw)
+
+    resolver_kwargs = {
+        "default_api_key": default_account_api_key,
+        "partner_affiliate_api_key": partner_affiliate_api_key,
+    }
+
+    credential_resolver = ScopedCredentialResolver(**resolver_kwargs)
+
+    multisafepay_sdk = Sdk(
+        is_production=False,
+        credential_resolver=credential_resolver,
+    )
+
+    # Get the 'Terminal' manager from the SDK
+    terminal_manager = multisafepay_sdk.get_terminal_manager()
+
+    # Build the create terminal request
+    create_request = (
+        CreateTerminalRequest()
+        .add_provider("CTAP")
+        .add_group_id(terminal_group_id)
+        .add_name("Demo POS Terminal")
+    )
+
+    # Create a new POS terminal
+    terminal_response = terminal_manager.create_terminal(create_request)
+
+    # Print the created terminal data
+    terminal_data = terminal_response.get_data()
+    print(terminal_data)

examples/terminal_manager/get_terminals.py

@@ -0,0 +1,49 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+import os
+
+from dotenv import load_dotenv
+
+from multisafepay import Sdk
+from multisafepay.client import ScopedCredentialResolver
+
+# Load environment variables from a .env file
+load_dotenv()
+
+default_account_api_key = (os.getenv("API_KEY") or "").strip()
+partner_affiliate_api_key = (os.getenv("PARTNER_API_KEY") or "").strip()
+
+if __name__ == "__main__":
+    # get_terminals → partner_affiliate scope → resolver returns
+    # partner_affiliate_api_key, falls back to default_api_key
+    resolver_kwargs = {
+        "default_api_key": default_account_api_key,
+        "partner_affiliate_api_key": partner_affiliate_api_key,
+    }
+
+    credential_resolver = ScopedCredentialResolver(**resolver_kwargs)
+
+    multisafepay_sdk = Sdk(
+        is_production=False,
+        credential_resolver=credential_resolver,
+    )
+
+    # Get the 'Terminal' manager from the SDK
+    terminal_manager = multisafepay_sdk.get_terminal_manager()
+
+    # Define optional pagination parameters
+    options = {
+        "limit": 10,
+        "page": 1,
+    }
+
+    # Fetch terminals for the account
+    terminals_response = terminal_manager.get_terminals(options=options)
+
+    # Print the terminal listing data
+    print(terminals_response.get_data())

src/multisafepay/api/paths/terminal_groups/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+"""Terminal group API endpoints."""
+
+from multisafepay.api.paths.terminal_groups.terminal_group_manager import (
+    TerminalGroupManager,
+)
+
+__all__ = [
+    "TerminalGroupManager",
+]

src/multisafepay/api/paths/terminal_groups/terminal_group_manager.py

@@ -0,0 +1,107 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+"""Terminal group manager for `/json/terminal-groups/{terminal_group_id}/terminals`."""
+
+from multisafepay.api.base.abstract_manager import AbstractManager
+from multisafepay.api.base.listings.listing_pager import ListingPager
+from multisafepay.api.base.listings.pager import Pager
+from multisafepay.api.base.response.api_response import ApiResponse
+from multisafepay.api.base.response.custom_api_response import (
+    CustomApiResponse,
+)
+from multisafepay.api.paths.terminals.response.terminal import Terminal
+from multisafepay.client.client import Client
+from multisafepay.client.credential_resolver import AuthScope
+from multisafepay.util.message import MessageList, gen_could_not_created_msg
+from pydantic import ValidationError
+
+ALLOWED_OPTIONS = {
+    "page": "",
+    "limit": "",
+}
+
+
+class TerminalGroupManager(AbstractManager):
+    """A class representing the TerminalGroupManager."""
+
+    def __init__(self: "TerminalGroupManager", client: Client) -> None:
+        """
+        Initialize the TerminalGroupManager with a client.
+
+        Parameters
+        ----------
+        client (Client): The client used to make API requests.
+
+        """
+        super().__init__(client)
+
+    @staticmethod
+    def __custom_terminal_listing_response(
+        response: ApiResponse,
+    ) -> CustomApiResponse:
+        args: dict = {
+            **response.dict(),
+            "data": None,
+        }
+
+        pager = None
+        raw_pager = response.get_pager()
+        if isinstance(raw_pager, dict):
+            pager = Pager.from_dict(raw_pager.copy())
+
+        try:
+            args["data"] = ListingPager(
+                data=response.get_body_data().copy(),
+                pager=pager,
+                class_type=Terminal,
+            )
+        except (AttributeError, TypeError, ValidationError):
+            args["warnings"] = MessageList().add_message(
+                gen_could_not_created_msg("Listing Terminal"),
+            )
+
+        return CustomApiResponse(**args)
+
+    def get_terminals_by_group(
+        self: "TerminalGroupManager",
+        terminal_group_id: str,
+        options: dict = None,
+    ) -> CustomApiResponse:
+        """
+        List POS terminals for the given terminal group.
+
+        Parameters
+        ----------
+        terminal_group_id (str): Terminal group identifier.
+        options (dict): Request options (`page`, `limit`). Defaults to None.
+
+        Returns
+        -------
+        CustomApiResponse: The response containing terminal listing data.
+
+        """
+        if options is None:
+            options = {}
+        options = {k: v for k, v in options.items() if k in ALLOWED_OPTIONS}
+
+        encoded_terminal_group_id = self.encode_path_segment(terminal_group_id)
+        endpoint = (
+            f"json/terminal-groups/{encoded_terminal_group_id}/terminals"
+        )
+        context = {"terminal_group_id": terminal_group_id}
+        response = self.client.create_get_request(
+            endpoint=endpoint,
+            params=options,
+            context=context,
+            auth_scope=AuthScope(
+                scope=Client.AUTH_SCOPE_PARTNER_AFFILIATE,
+            ),
+        )
+        return TerminalGroupManager.__custom_terminal_listing_response(
+            response,
+        )

src/multisafepay/api/paths/terminals/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+"""Terminal API endpoints for POS terminal and receipt operations."""
+
+from multisafepay.api.paths.terminals.terminal_manager import (
+    TerminalManager,
+)
+
+__all__ = [
+    "TerminalManager",
+]

src/multisafepay/api/paths/terminals/request/__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) MultiSafepay, Inc. All rights reserved.
+
+# This file is licensed under the Open Software License (OSL) version 3.0.
+# For a copy of the license, see the LICENSE.txt file in the project root.
+
+# See the DISCLAIMER.md file for disclaimer details.
+
+"""Request models for terminal-related API calls."""
+
+from multisafepay.api.paths.terminals.request.create_terminal_request import (
+    CreateTerminalRequest,
+)
+
+__all__ = [
+    "CreateTerminalRequest",
+]