brynq-sdk-sage-germany 1.0.0__py3-none-any.whl

brynq_sdk_sage_germany/cost_centers.py

@@ -0,0 +1,89 @@
+"""
+Cost center endpoint implementations for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas.cost_centers import CostCentersGet, CostCenterCreate
+
+
+class CostCenters:
+    """
+    Handles cost-center-related operations scoped to companies.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/company/Kostenstellen"
+
+    def _collect_company_ids(self) -> List[int]:
+        """
+        Retrieve distinct company ids using the employee search endpoint.
+        """
+        records = self.sage._employee_search()
+        company_ids = {record["MdNr"] for record in records if record.get("MdNr") is not None}
+        return list(company_ids)
+
+    def get(self, company_ids: Optional[List[int]] = None) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve cost center entries for the provided companies.
+        """
+        try:
+            companies = company_ids or self._collect_company_ids()
+            if not companies:
+                return pd.DataFrame(), pd.DataFrame()
+
+            cost_center_records: List[Dict[str, Any]] = []
+            for company_id in companies:
+                response = self.sage.get(
+                    path=self.base_url,
+                    params={"MdNr": company_id},
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if isinstance(payload, list):
+                    cost_center_records.extend(payload)
+
+            if not cost_center_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(cost_center_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=CostCentersGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve cost center data.") from exc
+
+    def create(self, data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Dict[str, Any]:
+        """
+        Create or update cost centers using bulk PUT.
+        """
+        try:
+            if isinstance(data, dict):
+                items = [data]
+            elif isinstance(data, list):
+                items = data
+            else:
+                raise ValueError("Cost center create payload must be a dictionary or list of dictionaries.")
+
+            payload = [
+                CostCenterCreate(**item).model_dump(by_alias=True, exclude_none=True, mode="json")
+                for item in items
+            ]
+
+            response = self.sage.put(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create or update Sage Germany cost centers.") from exc

brynq_sdk_sage_germany/employees.py

@@ -0,0 +1,140 @@
+"""
+Employees endpoint implementations for Sage Germany.
+"""
+
+from typing import Any, Dict, Optional, Tuple
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas.employees import EmployeeUpdateRequest, EmployeeCreateForm, EmployeesGet
+from .absences import Absences
+from .allowances import Allowances
+from .salaries import Salary
+from .start_end_dates import StartEndDates
+from .work_hours import WorkHours
+from .vacation_account import VacationAccount
+from .contracts import Contracts
+from .helpers import sage_flat_to_nested_with_prefix
+from .organization import Organization
+
+
+class Employees:
+    """
+    Handles employee-related operations.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.absences = Absences(sage)
+        self.allowances = Allowances(sage)
+        self.salary = Salary(sage)
+        self.start_end_dates = StartEndDates(sage)
+        self.work_hours = WorkHours(sage)
+        self.vacation_account = VacationAccount(sage)
+        self.contracts = Contracts(sage)
+        self.organization = Organization(sage)
+
+    def _fetch_employee_record(self, mdnr: int, annr: int) -> Dict[str, Any]:
+        """
+        Fetch a single employee detail payload from the API.
+        """
+        response = self.sage.get(
+            path="/employeenew/person/personal",
+            params={"MdNr": mdnr, "AnNr": annr},
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+    def get(
+        self,
+        employee_id: Optional[int] = None,
+        company_id: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve employee details, flatten them, and validate using Pandera schemas.
+        """
+        try:
+            if employee_id is not None or company_id is not None:
+                if employee_id is None or company_id is None:
+                    raise ValueError(
+                        "Both company_id and employee_id are required to fetch a single employee."
+                    )
+                try:
+                    data = self._fetch_employee_record(mdnr=company_id, annr=employee_id)
+                    if not data:
+                        return pd.DataFrame(), pd.DataFrame()
+                except Exception as exc:  # pragma: no cover - upstream errors
+                    raise RuntimeError("Failed to fetch employee record.") from exc
+                records = [data]
+            else:
+                employees = self.sage._employee_search()
+                if not employees:
+                    return pd.DataFrame(), pd.DataFrame()
+
+                records = [
+                    self._fetch_employee_record(mdnr=item["MdNr"], annr=item["AnNr"])
+                    for item in employees
+                ]
+                records = [record for record in records if record]
+
+            if not records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=EmployeesGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:  # pragma: no cover - upstream errors
+            raise RuntimeError("Failed to retrieve employee data.") from exc
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new employee using the EmployeeNew Neuanlage endpoint.
+        """
+
+        try:
+            valid_data = EmployeeCreateForm(**data)
+            payload = valid_data.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+            response = self.sage.post(
+                path="/EmployeeNew/Neuanlage",
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"}
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create Sage Germany employee.") from exc
+
+    def update(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Update an existing employee personal record in Sage Germany.
+
+        Args:
+            data: Flat dictionary that matches `EmployeeUpdateRequest` field names
+                using prefixes such as `person_`, `address_`, `identity_`, etc.
+
+        Returns:
+            Dict[str, Any]: Raw response JSON returned by the Sage API.
+        """
+        try:
+            nested_payload = sage_flat_to_nested_with_prefix(data, EmployeeUpdateRequest)
+            validated = EmployeeUpdateRequest(**nested_payload)
+            request_body = validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+        except ValidationError as exc:
+            raise ValueError(f"Invalid employee update payload: {exc}") from exc
+
+        try:
+            response = self.sage.post(
+                path="/employeenew/person/personal",
+                body=request_body,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to update Sage Germany employee.") from exc

brynq_sdk_sage_germany/helpers.py

@@ -0,0 +1,391 @@
+"""
+Helper utilities specific to the Sage Germany SDK.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Type, get_args, get_origin
+
+from pydantic import BaseModel
+
+
+def _extract_basemodel(annotation: Any) -> Optional[Type[BaseModel]]:
+    """
+    Return the BaseModel class from an annotation if present.
+    """
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+
+    origin = get_origin(annotation)
+    if origin:
+        for arg in get_args(annotation):
+            if isinstance(arg, type) and issubclass(arg, BaseModel):
+                return arg
+    return None
+
+
+def _get_prefix(field_info) -> Optional[str]:
+    """
+    Read json_schema_extra prefix metadata if available.
+    """
+    if field_info.json_schema_extra and isinstance(field_info.json_schema_extra, dict):
+        return field_info.json_schema_extra.get("prefix")
+    return None
+
+
+def _collect_indexed_prefixes(flat_dict: Dict[str, Any], prefix: str) -> List[int]:
+    """
+    Extract list indices for list-based payloads (e.g., addresses_0_city).
+    """
+    pattern = re.compile(rf"^{re.escape(prefix)}(\d+)_")
+    indices: List[int] = []
+    for key in flat_dict:
+        match = pattern.match(key)
+        if match:
+            indices.append(int(match.group(1)))
+    return sorted(set(indices))
+
+
+def sage_flat_to_nested_with_prefix(
+    flat_dict: Dict[str, Any],
+    model: Type[BaseModel],
+) -> Dict[str, Any]:
+    """
+    Convert a flat Sage Germany payload into the nested structure defined by the schema.
+
+    Differences from the generic implementation:
+    - Nested prefixes are treated as absolute so Sage-specific prefixes such as
+      `person_title_` are not concatenated twice.
+    - Falls back to parent prefixes only when a nested field does not define its own prefix.
+    """
+
+    def process_model(model_cls: Type[BaseModel], parent_prefix: str = "") -> Dict[str, Any]:
+        nested: Dict[str, Any] = {}
+
+        for field_name, field_info in model_cls.model_fields.items():
+            alias = field_info.alias or field_name
+            field_type = field_info.annotation
+            prefix_hint = _get_prefix(field_info)
+            effective_prefix = prefix_hint if prefix_hint is not None else parent_prefix
+
+            origin = get_origin(field_type)
+            if origin is list:
+                list_model = _extract_basemodel(field_type)
+                if list_model and effective_prefix:
+                    list_items = process_list(list_model, effective_prefix)
+                    if list_items:
+                        nested[alias] = list_items
+                continue
+
+            nested_model = _extract_basemodel(field_type)
+            if nested_model:
+                child_payload = process_model(nested_model, effective_prefix)
+                if child_payload:
+                    nested[alias] = child_payload
+                continue
+
+            key_candidates = []
+            if effective_prefix:
+                key_candidates.append(f"{effective_prefix}{field_name}")
+            key_candidates.append(field_name)
+
+            for key in key_candidates:
+                if key in flat_dict and flat_dict[key] is not None:
+                    nested[alias] = flat_dict[key]
+                    break
+
+        return nested
+
+    def process_list(model_cls: Type[BaseModel], prefix: str) -> Optional[List[Dict[str, Any]]]:
+        indices = _collect_indexed_prefixes(flat_dict, prefix)
+        if not indices:
+            return None
+
+        items: List[Dict[str, Any]] = []
+        for index in indices:
+            index_prefix = f"{prefix}{index}_"
+            payload = process_model(model_cls, index_prefix)
+            if payload:
+                items.append(payload)
+        return items or None
+
+    return process_model(model)
+
+
+def organization_flat_to_nested(flat: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Organization-specific flat-to-nested converter.
+    Expects prefixes like cost_center_0_id, org_assign_0_structure_id, fixed_0_cost_center_id, etc.
+    """
+
+    def pop_prefix(prefix: str) -> Dict[str, Any]:
+        return {k[len(prefix):]: v for k, v in flat.items() if k.startswith(prefix) and v is not None}
+
+    nested: Dict[str, Any] = {}
+
+    # Key
+    key_fields = pop_prefix("key_")
+    if key_fields:
+        nested["Key"] = {
+            "Date": key_fields.get("date"),
+            "MdNr": key_fields.get("company_id"),
+            "AnNr": key_fields.get("employee_number"),
+            "CombinedKey": key_fields.get("combined_key"),
+        }
+
+    # Flags
+    if "is_fixed_cost_split" in flat:
+        nested["IstFesteKostenAufteilung"] = flat.get("is_fixed_cost_split")
+
+    # General data
+    general = pop_prefix("general_")
+    if general:
+        def id_text(prefix: str) -> Optional[Dict[str, Any]]:
+            if general.get(f"{prefix}id") is None and general.get(f"{prefix}text") is None:
+                return None
+            return {"Id": general.get(f"{prefix}id"), "Text": general.get(f"{prefix}text")}
+
+        nested["AllgemeineDaten"] = {
+            "VerwendungBetriebsstaetten": general.get("use_operating_sites"),
+            "Abrechnungskreis": id_text("payroll_group_"),
+            "Abrechnungslauf": id_text("payroll_run_"),
+            "Bundesland": id_text("state_"),
+            "Betriebsstaette": id_text("site_"),
+            "DebitorenNummer": general.get("debtor_number"),
+            "KalkulatorischeKostenstelle": id_text("calc_cost_center_"),
+            "Position": id_text("position_"),
+        }
+
+    # Search terms
+    search = pop_prefix("search_terms_")
+    if search:
+        nested["Suchbegriffe"] = {
+            "Such1": search.get("search_1"),
+            "Such2": search.get("search_2"),
+            "Such3": search.get("search_3"),
+            "Such4": search.get("search_4"),
+        }
+
+    def build_split(prefix: str) -> Optional[List[Dict[str, Any]]]:
+        items: Dict[int, Dict[str, Any]] = {}
+        for k, v in flat.items():
+            if not k.startswith(prefix):
+                continue
+            remainder = k[len(prefix):]
+            parts = remainder.split("_", 1)
+            if len(parts) != 2:
+                continue
+            try:
+                idx = int(parts[0])
+            except ValueError:
+                continue
+            field = parts[1]
+            items.setdefault(idx, {})[field] = v
+        if not items:
+            return None
+        out: List[Dict[str, Any]] = []
+        for idx in sorted(items):
+            entry = items[idx]
+            out.append(
+                {
+                    "Id": entry.get("id"),
+                    "Number": entry.get("number"),
+                    "Text": entry.get("text"),
+                    "Anteil": entry.get("portion"),
+                }
+            )
+        return out or None
+
+    cc = build_split("cost_center_")
+    if cc:
+        nested["Kostenstellen"] = {"Aufteilung": cc}
+
+    cu = build_split("cost_unit_")
+    if cu:
+        nested["Kostentraeger"] = {"Aufteilung": cu}
+
+    d1 = build_split("dimension_one_")
+    if d1:
+        nested["Dimension1"] = {"Aufteilung": d1}
+    d2 = build_split("dimension_two_")
+    if d2:
+        nested["Dimension2"] = {"Aufteilung": d2}
+    d3 = build_split("dimension_three_")
+    if d3:
+        nested["Dimension3"] = {"Aufteilung": d3}
+
+    # Org assignments
+    org_items: Dict[int, Dict[str, Any]] = {}
+    for k, v in flat.items():
+        if not k.startswith("org_assign_"):
+            continue
+        remainder = k[len("org_assign_"):]
+        parts = remainder.split("_", 1)
+        if len(parts) != 2:
+            continue
+        try:
+            idx = int(parts[0])
+        except ValueError:
+            continue
+        field = parts[1]
+        org_items.setdefault(idx, {})[field] = v
+
+    if org_items:
+        nested["OrgaEinordnungen"] = []
+        for idx in sorted(org_items):
+            entry = org_items[idx]
+            nested["OrgaEinordnungen"].append(
+                {
+                    "Id": entry.get("id"),
+                    "Struktur": {"Id": entry.get("structure_id"), "Text": entry.get("structure_text")},
+                    "Einheit": {"Id": entry.get("unit_id"), "Text": entry.get("unit_text")},
+                    "ValidFrom": entry.get("valid_from"),
+                    "ValidTo": entry.get("valid_to"),
+                }
+            )
+
+    # Fixed distribution
+    fixed_items: Dict[int, Dict[str, Any]] = {}
+    for k, v in flat.items():
+        if not k.startswith("fixed_"):
+            continue
+        remainder = k[len("fixed_"):]
+        parts = remainder.split("_", 1)
+        if len(parts) != 2:
+            continue
+        try:
+            idx = int(parts[0])
+        except ValueError:
+            continue
+        field = parts[1]
+        fixed_items.setdefault(idx, {})[field] = v
+
+    if fixed_items:
+        nested["FesteAufteilung"] = []
+        for idx in sorted(fixed_items):
+            entry = fixed_items[idx]
+            nested["FesteAufteilung"].append(
+                {
+                    "Id": entry.get("id"),
+                    "Kostenstelle": {"Id": entry.get("cost_center_id"), "Text": entry.get("cost_center_text")},
+                    "Kostentraeger": {"Id": entry.get("cost_unit_id"), "Text": entry.get("cost_unit_text")},
+                    "Dimension1": {"Id": entry.get("dimension_one_id"), "Text": entry.get("dimension_one_text")},
+                    "Dimension2": {"Id": entry.get("dimension_two_id"), "Text": entry.get("dimension_two_text")},
+                    "Dimension3": {"Id": entry.get("dimension_three_id"), "Text": entry.get("dimension_three_text")},
+                    "Anteil": entry.get("portion"),
+                }
+            )
+
+    # Clean empties
+    def prune(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            cleaned = {k: prune(v) for k, v in obj.items()}
+            return {k: v for k, v in cleaned.items() if v not in (None, {}, [])}
+        if isinstance(obj, list):
+            cleaned_list = [prune(i) for i in obj]
+            return [i for i in cleaned_list if i not in (None, {}, [])]
+        return obj
+
+    return prune(nested)
+
+
+def start_end_flat_to_nested(
+    flat_dict: Dict[str, Any],
+    model: Type[BaseModel],
+) -> Dict[str, Any]:
+    """
+    Local flat-to-nested converter supporting Optional[List[BaseModel]] for start/end dates.
+    Keeps the shared helper unchanged to avoid side effects in other endpoints.
+    """
+
+    def _extract_basemodel(annotation: Any) -> Optional[Type[BaseModel]]:
+        if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            return annotation
+        origin = get_origin(annotation)
+        if origin:
+            for arg in get_args(annotation):
+                if isinstance(arg, type) and issubclass(arg, BaseModel):
+                    return arg
+        return None
+
+    def _extract_list_model(annotation: Any) -> Optional[Type[BaseModel]]:
+        origin = get_origin(annotation)
+        if origin is list:
+            return _extract_basemodel(get_args(annotation)[0])
+        if origin:
+            for arg in get_args(annotation):
+                arg_origin = get_origin(arg)
+                if arg_origin is list:
+                    return _extract_basemodel(get_args(arg)[0])
+        return None
+
+    def _get_prefix(field_info) -> Optional[str]:
+        if field_info.json_schema_extra and isinstance(field_info.json_schema_extra, dict):
+            return field_info.json_schema_extra.get("prefix")
+        return None
+
+    def _collect_indexed_prefixes(prefix: str) -> List[int]:
+        pattern = re.compile(rf"^{re.escape(prefix)}(\d+)_")
+        indices: List[int] = []
+        for key in flat_dict:
+            match = pattern.match(key)
+            if match:
+                indices.append(int(match.group(1)))
+        return sorted(set(indices))
+
+    def process_model(model_cls: Type[BaseModel], parent_prefix: str = "") -> Dict[str, Any]:
+        nested: Dict[str, Any] = {}
+        for field_name, field_info in model_cls.model_fields.items():
+            alias = field_info.alias or field_name
+            field_type = field_info.annotation
+            prefix_hint = _get_prefix(field_info)
+            effective_prefix = parent_prefix
+            if prefix_hint:
+                if parent_prefix and prefix_hint.startswith("entry_exit_"):
+                    effective_prefix = prefix_hint.replace("entry_exit_", parent_prefix, 1)
+                else:
+                    effective_prefix = prefix_hint
+
+            list_model = _extract_list_model(field_type)
+            if list_model and effective_prefix:
+                list_items = process_list(list_model, effective_prefix)
+                if list_items:
+                    nested[alias] = list_items
+                continue
+
+            nested_model = _extract_basemodel(field_type)
+            if nested_model:
+                child_payload = process_model(nested_model, effective_prefix)
+                if child_payload:
+                    nested[alias] = child_payload
+                continue
+
+            key_candidates = []
+            if effective_prefix:
+                key_candidates.append(f"{effective_prefix}{field_name}")
+            key_candidates.append(field_name)
+
+            for key in key_candidates:
+                if key in flat_dict and flat_dict[key] is not None:
+                    nested[alias] = flat_dict[key]
+                    break
+
+        return nested
+
+    def process_list(model_cls: Type[BaseModel], prefix: str) -> Optional[List[Dict[str, Any]]]:
+        indices = _collect_indexed_prefixes(prefix)
+        if not indices:
+            return None
+        items: List[Dict[str, Any]] = []
+        for index in indices:
+            index_prefix = f"{prefix}{index}_"
+            payload = process_model(model_cls, index_prefix)
+            if payload:
+                items.append(payload)
+        return items or None
+
+    return process_model(model)
+
+
+__all__ = ["sage_flat_to_nested_with_prefix", "organization_flat_to_nested", "start_end_flat_to_nested"]