feat: add branch details endpoint (#30)

Author: akalipetis

AGENTS.md

@@ -0,0 +1,4 @@
+# Agent Instructions
+
+- Before handing work over, run autofixable checks first. Use `uv run ruff format && uv run ruff check --fix`, then verify with `uv run ruff format --check && uv run ruff check`.
+- For Python test validation in this repo, use `PYTHONPATH=$PWD uv run --no-project --with requests python3 -m unittest discover -s tests`.

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,
@@ -283,6 +284,30 @@ 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")
+        payload = None
+
+        if response:
+            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)
+
     def get_employer_details(self) -> EmployerDetails:
         """
         Fetches employer details from the Ergani API.

ergani/models.py

@@ -23,6 +23,81 @@
 )
 
 
+@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.
+        sepe_service_code (Optional[str]): The SEPE service code for the branch.
+        oaed_service_code (Optional[str]): The OAED service code for the branch.
+        business_branch_activity_code (Optional[str]): The branch activity code.
+        kallikratis_municipal_code (Optional[str]): The Kallikratis municipal code.
+        status_description (Optional[str]): The current branch status description.
+        raw_payload (Dict[str, Any]): The raw branch payload returned by the API.
+    """
+
+    branch_number: Optional[int]
+    address: Optional[str]
+    sepe_service_code: Optional[str]
+    oaed_service_code: Optional[str]
+    business_branch_activity_code: Optional[str]
+    kallikratis_municipal_code: Optional[str]
+    status_description: Optional[str]
+    raw_payload: Dict[str, Any]
+
+    @classmethod
+    def parse(cls, payload: Dict[str, Any]) -> BusinessBranch:
+        if not isinstance(payload, dict):
+            raise ValueError("Expected EX_BASE_02 branch payload to be an object")
+
+        return cls(
+            branch_number=_parse_int(payload.get("Aa")),
+            address=payload.get("Address"),
+            sepe_service_code=payload.get("YpiresiaSepe"),
+            oaed_service_code=payload.get("YpiresiaOaed"),
+            business_branch_activity_code=payload.get("Kad"),
+            kallikratis_municipal_code=payload.get("Kallikratis"),
+            status_description=payload.get("StatusDescription"),
+            raw_payload=payload,
+        )
+
+    @classmethod
+    def parse_many(cls, payload: Any) -> List[BusinessBranch]:
+        if payload is None:
+            return []
+
+        branch_payload = cls._unwrap_payload(payload)
+
+        if isinstance(branch_payload, dict):
+            return [cls.parse(branch_payload)]
+
+        if not isinstance(branch_payload, list):
+            raise ValueError(
+                "Expected EX_BASE_02 branch payload to be an object or list"
+            )
+
+        return [cls.parse(item) for item in branch_payload]
+
+    @staticmethod
+    def _unwrap_payload(payload: Any) -> Any:
+        if not isinstance(payload, dict):
+            raise ValueError("Expected EX_BASE_02 payload to be an object")
+
+        if "EX_BASE_02" in payload:
+            payload = payload["EX_BASE_02"]
+
+        if not isinstance(payload, dict):
+            raise ValueError("Expected EX_BASE_02 payload to contain an object")
+
+        branch_payload = payload.get("Pararthma", payload)
+
+        return branch_payload
+
+
 @dataclass
 class EmployerDetails:
     employer_id: int | None = None
@@ -68,7 +143,7 @@ def _parse_payload(cls, payload: Any) -> Dict[str, Any]:
         return employer_payload
 
 
-def _parse_int(value: Any) -> int | None:
+def _parse_int(value: Any) -> Optional[int]:
     if value is None or value == "":
         return None
 

tests/test_branch_details.py

@@ -0,0 +1,170 @@
+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
+
+SINGLE_BRANCH_PAYLOAD = {
+    "Aa": "0",
+    "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 6 10561 ΑΘΗΝΑ",
+    "YpiresiaSepe": "11010",
+    "YpiresiaOaed": "101201",
+    "Kad": "6210",
+    "Kallikratis": "91860101",
+    "StatusDescription": "Έναρξη απασχόλησης",
+}
+
+BRANCH_PAYLOAD = {
+    "EX_BASE_02": {
+        "Pararthma": [
+            {
+                "Aa": "0",
+                "Address": "ΑΓ. ΜΑΡΙΝΑΣ 19400 ΚΟΡΩΠΙ",
+            },
+            {
+                "Aa": "1",
+                "Address": "ΛΕΒΙΔΟΥ 14562 ΚΗΦΙΣΙΑ",
+            },
+        ]
+    }
+}
+
+SINGLE_BRANCH_RAW_PAYLOAD = {
+    "Aa": "0",
+    "Address": "ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 6 10561 ΑΘΗΝΑ",
+    "YpiresiaSepe": "11010",
+    "YpiresiaOaed": "101201",
+    "Kad": "6210",
+    "Kallikratis": "91860101",
+    "StatusDescription": "Έναρξη απασχόλησης",
+}
+
+BRANCH_RAW_PAYLOADS = [
+    {
+        "Aa": "0",
+        "Address": "ΑΓ. ΜΑΡΙΝΑΣ 19400 ΚΟΡΩΠΙ",
+    },
+    {
+        "Aa": "1",
+        "Address": "ΛΕΒΙΔΟΥ 14562 ΚΗΦΙΣΙΑ",
+    },
+]
+
+
+class BusinessBranchTests(TestCase):
+    def test_business_branch_parse_reads_single_branch_payload(self) -> None:
+        self.assertEqual(
+            BusinessBranch.parse(SINGLE_BRANCH_PAYLOAD),
+            BusinessBranch(
+                branch_number=0,
+                address="ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 6 10561 ΑΘΗΝΑ",
+                sepe_service_code="11010",
+                oaed_service_code="101201",
+                business_branch_activity_code="6210",
+                kallikratis_municipal_code="91860101",
+                status_description="Έναρξη απασχόλησης",
+                raw_payload=SINGLE_BRANCH_RAW_PAYLOAD,
+            ),
+        )
+
+    def test_business_branch_parse_many_reads_wrapped_response(self) -> None:
+        self.assertEqual(
+            BusinessBranch.parse_many(BRANCH_PAYLOAD),
+            [
+                BusinessBranch(
+                    branch_number=0,
+                    address="ΑΓ. ΜΑΡΙΝΑΣ 19400 ΚΟΡΩΠΙ",
+                    sepe_service_code=None,
+                    oaed_service_code=None,
+                    business_branch_activity_code=None,
+                    kallikratis_municipal_code=None,
+                    status_description=None,
+                    raw_payload=BRANCH_RAW_PAYLOADS[0],
+                ),
+                BusinessBranch(
+                    branch_number=1,
+                    address="ΛΕΒΙΔΟΥ 14562 ΚΗΦΙΣΙΑ",
+                    sepe_service_code=None,
+                    oaed_service_code=None,
+                    business_branch_activity_code=None,
+                    kallikratis_municipal_code=None,
+                    status_description=None,
+                    raw_payload=BRANCH_RAW_PAYLOADS[1],
+                ),
+            ],
+        )
+
+    def test_business_branch_parse_requires_object_payload(self) -> None:
+        with self.assertRaises(ValueError):
+            BusinessBranch.parse("invalid")
+
+    def test_business_branch_parse_many_accepts_single_branch_payload(self) -> None:
+        self.assertEqual(
+            BusinessBranch.parse_many(
+                {"EX_BASE_02": {"Pararthma": SINGLE_BRANCH_PAYLOAD}}
+            ),
+            [
+                BusinessBranch(
+                    branch_number=0,
+                    address="ΠΛΑΤΕΙΑ ΑΓ. ΘΕΟΔΩΡΩΝ 6 10561 ΑΘΗΝΑ",
+                    sepe_service_code="11010",
+                    oaed_service_code="101201",
+                    business_branch_activity_code="6210",
+                    kallikratis_municipal_code="91860101",
+                    status_description="Έναρξη απασχόλησης",
+                    raw_payload=SINGLE_BRANCH_RAW_PAYLOAD,
+                )
+            ],
+        )
+
+    def test_get_branch_details_uses_execute_service_and_parses_wrapped_response(
+        self,
+    ) -> None:
+        client = ErganiClient("username", "password", "https://example.test")
+        response = Mock(spec=Response)
+        response.json.return_value = BRANCH_PAYLOAD
+
+        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="ΑΓ. ΜΑΡΙΝΑΣ 19400 ΚΟΡΩΠΙ",
+                    sepe_service_code=None,
+                    oaed_service_code=None,
+                    business_branch_activity_code=None,
+                    kallikratis_municipal_code=None,
+                    status_description=None,
+                    raw_payload=BRANCH_RAW_PAYLOADS[0],
+                ),
+                BusinessBranch(
+                    branch_number=1,
+                    address="ΛΕΒΙΔΟΥ 14562 ΚΗΦΙΣΙΑ",
+                    sepe_service_code=None,
+                    oaed_service_code=None,
+                    business_branch_activity_code=None,
+                    kallikratis_municipal_code=None,
+                    status_description=None,
+                    raw_payload=BRANCH_RAW_PAYLOADS[1],
+                ),
+            ],
+        )
+        execute_service_mock.assert_called_once_with("EX_BASE_02")
+
+    def test_get_branch_details_returns_empty_list_for_no_content(self) -> None:
+        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")