Add EX_BASE_02 branch details query

Author: akalipetis

ergani/client.py

@@ -7,6 +7,7 @@
 from ergani.auth import ErganiAuthentication
 from ergani.exceptions import APIError, AuthenticationError
 from ergani.models import (
+    BusinessBranch,
     CompanyDailySchedule,
     CompanyOvertime,
     CompanyWeeklySchedule,
@@ -280,3 +281,28 @@ def get_services_list(self) -> Optional[Response]:
         """
 
         return self._request("GET", "/WebServices/ServicesList", None)
+
+    def get_branch_details(self) -> List[BusinessBranch]:
+        """
+        Fetches the authenticated employer's branch details from the Ergani API.
+
+        Returns:
+            List[BusinessBranch]: The parsed branch detail entries.
+
+        Raises:
+            APIError: An error occurred while communicating with the Ergani API
+            AuthenticationError: Raised if there is an authentication error with the Ergani API
+            ValueError: The response payload could not be parsed as a branch list
+        """
+
+        response = self._execute_service("EX_BASE_02")
+
+        if response is None:
+            return BusinessBranch.parse_many(None)
+
+        try:
+            payload = response.json()
+        except ValueError as error:
+            raise ValueError("EX_BASE_02 returned a non-JSON response") from error
+
+        return BusinessBranch.parse_many(payload)

ergani/models.py

@@ -1,6 +1,8 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from datetime import date, datetime, time
-from typing import List, Literal, Optional, TypedDict
+from typing import Any, Dict, List, Literal, Optional, TypedDict
 
 from ergani.typings import (
     LateDeclarationJustificationType,
@@ -21,6 +23,78 @@
 )
 
 
+@dataclass
+class BusinessBranch:
+    """
+    Represents a business branch returned by the Ergani query services.
+
+    Attributes:
+        branch_number (Optional[int]): The verified branch identifier used by later
+            query endpoints when present in the payload.
+        address (Optional[str]): The branch address when returned by EX_BASE_02.
+        raw_payload (Dict[str, Any]): The original response object returned by the API.
+    """
+
+    branch_number: Optional[int]
+    address: Optional[str]
+    raw_payload: Dict[str, Any]
+
+    @classmethod
+    def parse_many(cls, payload: Any) -> List[BusinessBranch]:
+        branch_payloads = cls._parse_payloads(payload)
+
+        return [cls._parse(payload) for payload in branch_payloads]
+
+    @classmethod
+    def _parse(cls, payload: Any) -> BusinessBranch:
+        if not isinstance(payload, dict):
+            raise ValueError("Expected branch details item to be an object")
+
+        return cls(
+            branch_number=cls._parse_branch_number(payload),
+            address=payload.get("Address"),
+            raw_payload=dict(payload),
+        )
+
+    @classmethod
+    def _parse_payloads(cls, payload: Any) -> List[Dict[str, Any]]:
+        if payload is None:
+            return []
+
+        if isinstance(payload, dict):
+            if "EX_BASE_02" in payload:
+                payload = payload["EX_BASE_02"]
+
+            if isinstance(payload, dict) and "Pararthma" in payload:
+                payload = payload["Pararthma"]
+
+            if isinstance(payload, dict):
+                return [payload]
+
+        if not isinstance(payload, list):
+            raise ValueError("Expected branch details response to be a list")
+
+        return payload
+
+    @classmethod
+    def _parse_branch_number(cls, payload: Dict[str, Any]) -> Optional[int]:
+        for key in ("PararthmaAa", "Aa"):
+            if key in payload:
+                return _parse_int(payload[key])
+
+        return None
+
+
+def _parse_int(value: Any) -> Optional[int]:
+    if value is None or value == "":
+        return None
+
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
 @dataclass
 class WorkCard:
     """

tests/test_branch_details.py

@@ -0,0 +1,80 @@
+from unittest import TestCase
+from unittest.mock import Mock, patch
+
+from requests.models import Response
+
+from ergani.client import ErganiClient
+from ergani.models import BusinessBranch
+
+
+class BusinessBranchTests(TestCase):
+    def test_business_branch_parse_many_reads_wrapped_response(self):
+        self.assertEqual(
+            BusinessBranch.parse_many(
+                {
+                    "EX_BASE_02": {
+                        "Pararthma": {
+                            "Aa": "0",
+                            "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                        }
+                    }
+                }
+            ),
+            [
+                BusinessBranch(
+                    branch_number=0,
+                    address="ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                    raw_payload={
+                        "Aa": "0",
+                        "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                    },
+                )
+            ],
+        )
+
+    def test_business_branch_parse_many_requires_object_or_list_payload(self):
+        with self.assertRaises(ValueError):
+            BusinessBranch.parse_many("invalid")
+
+    def test_get_branch_details_uses_execute_service_and_parses_wrapped_response(self):
+        client = ErganiClient("username", "password", "https://example.test")
+        response = Mock(spec=Response)
+        response.json.return_value = {
+            "EX_BASE_02": {
+                "Pararthma": {
+                    "Aa": "0",
+                    "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                }
+            }
+        }
+
+        with patch.object(
+            client, "_execute_service", return_value=response
+        ) as execute_service_mock:
+            result = client.get_branch_details()
+
+        self.assertEqual(
+            result,
+            [
+                BusinessBranch(
+                    branch_number=0,
+                    address="ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                    raw_payload={
+                        "Aa": "0",
+                        "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 10561 ΑΘΗΝΑ",
+                    },
+                )
+            ],
+        )
+        execute_service_mock.assert_called_once_with("EX_BASE_02")
+
+    def test_get_branch_details_returns_empty_list_for_no_content(self):
+        client = ErganiClient("username", "password", "https://example.test")
+
+        with patch.object(
+            client, "_execute_service", return_value=None
+        ) as execute_service_mock:
+            result = client.get_branch_details()
+
+        self.assertEqual(result, [])
+        execute_service_mock.assert_called_once_with("EX_BASE_02")