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

brynq_sdk_sage_germany/__init__.py

@@ -0,0 +1,278 @@
+"""
+Public package interface for the BrynQ Sage Germany SDK.
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+import os
+
+import requests
+
+from brynq_sdk_brynq import BrynQ
+from .employees import Employees
+from .payroll import Payroll
+from .payslips import Payslips
+from .cost_centers import CostCenters
+from .organization import Organization
+
+class SageGermany(BrynQ):
+    """
+    Base client for interacting with Sage Germany through the BrynQ platform.
+    """
+
+    TIMEOUT_SECONDS = 60
+    SESSION_COOKIE_NAME = "SageHRWebApi_SessionKey"
+
+    def __init__(
+        self,
+        system_type: Optional[Literal["source", "target"]] = None,
+        debug: bool = False,
+    ) -> None:
+        """
+        Initialize the Sage Germany SDK client.
+
+        Args:
+            system_type: Credential type to pull from BrynQ vault.
+            debug: Enables verbose logging.
+            base_url: Optional override for the API base URL.
+            timeout: Optional request timeout in seconds.
+        """
+        super().__init__()
+        self.debug = debug
+        self.timeout = self.TIMEOUT_SECONDS
+        self.session_key = None
+        credentials = self.interfaces.credentials.get(
+            system="sage-germany",
+            system_type=system_type,
+        )
+
+        credential_data = credentials["data"]
+        self._user_name = credential_data["user_name"]
+        self._password = credential_data["password"]
+
+        # Agent and target endpoints
+        self.agent_base_url = credential_data.get("brynq_agent_url")
+        if not self.agent_base_url:
+            raise ValueError("Sage Germany credentials must include brynq_agent_url.")
+        self.agent_rest_url = f"{self.agent_base_url}/brynq-agent/basic-request"
+        self.target_base_url = credential_data.get("target_base_url") or "http://127.0.0.1/hrportalapi"
+        # Preserve legacy attribute expected by existing modules
+        self.base_url = self.target_base_url
+
+        # Agent auth headers (BrynQ domain/token)
+        self.agent_domain = credential_data.get("domain") or os.getenv("BRYNQ_SUBDOMAIN")
+        agent_token = credential_data.get("token") or os.getenv("BRYNQ_API_TOKEN")
+
+        self.session = requests.Session()
+        self.session.timeout = self.timeout
+        base_headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if self.agent_domain:
+            base_headers["domain"] = self.agent_domain
+        if agent_token:
+            base_headers["Authorization"] = f"Bearer {agent_token}"
+        self.session.headers.update(base_headers)
+
+        # Initial authorization against Sage via agent
+        self.session_key = self.authorize()
+
+        self._verify_authorization()
+
+        self.employees = Employees(self)
+        self.payroll = Payroll(self)
+        self.payslips = Payslips(self)
+        self.cost_centers = CostCenters(self)
+        self.organization = Organization(self)
+
+        # Cache for employee search results
+        self._employee_search_cache: Optional[List[Dict[str, int]]] = None
+
+    def _employee_search(self, force_refresh: bool = False) -> List[Dict[str, int]]:
+        """
+        Search employees and return their MdNr/AnNr pairs.
+        Results are cached to avoid repeated API calls.
+
+        Args:
+            force_refresh: If True, bypass cache and fetch fresh data.
+        """
+        if not force_refresh and self._employee_search_cache is not None:
+            return self._employee_search_cache
+
+        response = self._agent_request(
+            path="/EmployeeNew/Employees/Search",
+            method="POST",
+            body={},  # Empty payload is required to retrieve all employees.
+        )
+        response.raise_for_status()
+        payload = response.json()
+        results = payload.get("Results", []) if isinstance(payload, dict) else []
+        self._employee_search_cache = [
+            {"MdNr": record_mdnr, "AnNr": record_annr}
+            for record in results
+            if isinstance(record, dict)
+            if (record_mdnr := record.get("MdNr")) is not None
+            if (record_annr := record.get("AnNr")) is not None
+        ]
+        return self._employee_search_cache
+
+    def get_databases(self) -> Any:
+        """
+        Return the list of databases available in the Sage Germany environment.
+        """
+        response = self._agent_request(
+            path="/configuration/databases",
+            method="GET",
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def authorize(self) -> Optional[str]:
+        """
+        Authenticate and capture the Sage session cookie according to API specs.
+
+        Returns:
+            Optional[str]: Session key (SageHRWebApi_SessionKey) if provided.
+        """
+        username = self._user_name
+        password = self._password
+
+        if not username or not password:
+            raise ValueError("Sage Germany credentials must include username and password.")
+
+        payload: Dict[str, Any] = {
+            "username": username,
+            "password": password,
+            "ntauthorization": False,
+        }
+
+        response = self._agent_request(
+            path="/authorization",
+            method="POST",
+            body=payload,
+        )
+        response.raise_for_status()
+
+        session_key = self.session.cookies.get(self.SESSION_COOKIE_NAME)
+
+        return session_key
+
+
+    def _verify_authorization(self) -> None:
+        """
+        Validate that the authorization cookie works by calling the security probe endpoint.
+        """
+        response = self._agent_request(
+            path="/security/calculate",
+            method="POST",
+        )
+        response.raise_for_status()
+
+    def _agent_request(
+        self,
+        path: str,
+        method: Literal["GET", "POST", "PUT", "DELETE"],
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+        data: Optional[Any] = None,
+    ) -> Any:
+        """
+        Proxy a request to Sage via the local BrynQ agent.
+        """
+        request_body: Dict[str, Any] = {
+            "url": f"{self.target_base_url}/{path.lstrip('/')}",
+            "method": method,
+        }
+        if params:
+            request_body["params"] = params
+        if body is not None:
+            request_body["body"] = body
+        if data is not None:
+            request_body["data"] = data
+        if headers:
+            request_body["headers"] = headers
+        if self.session_key:
+            if "headers" not in request_body:
+                request_body["headers"] = {}
+            request_body["headers"]["Cookie"] = f"{self.SESSION_COOKIE_NAME}={self.session_key}"
+
+
+
+        if self.debug:
+            print(f"[agent-request] {method} {request_body['url']} params={params} body={bool(body)}")
+
+        response = self.session.post(
+            self.agent_rest_url,
+            json=request_body,
+            timeout=self.timeout,
+        )
+
+        return response
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """
+        Perform a GET request via the BrynQ agent.
+        """
+        return self._agent_request(path=path, method="GET", params=params, headers=headers)
+
+    def post(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        data: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """
+        Perform a POST request via the BrynQ agent.
+        """
+        return self._agent_request(
+            path=path,
+            method="POST",
+            params=params,
+            body=body,
+            data=data,
+            headers=headers
+        )
+
+    def put(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """
+        Perform a PUT request via the BrynQ agent.
+        """
+        return self._agent_request(
+            path=path,
+            method="PUT",
+            params=params,
+            body=body,
+            headers=headers,
+        )
+
+    def delete(
+        self,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """
+        Perform a DELETE request via the BrynQ agent.
+        """
+        return self._agent_request(
+            path=path,
+            method="DELETE",
+            params=params,
+            body=body,
+            headers=headers,
+        )

brynq_sdk_sage_germany/absences.py

@@ -0,0 +1,175 @@
+"""
+Absence endpoint implementations for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas.absences import AbsenceTypesGet, AbsencesGet, AbsenceCreate, AbsenceDelete
+from .helpers import sage_flat_to_nested_with_prefix
+
+if TYPE_CHECKING:
+    from .employees import Employees
+
+
+class Absences:
+    """
+    Handles absence-related operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/time/absencetimes"
+        self.types_url = "/time/absencetimetypes"
+
+    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 absence entries for the provided companies.
+        """
+        try:
+            companies = company_ids or self._collect_company_ids()
+            if not companies:
+                return pd.DataFrame(), pd.DataFrame()
+
+            absence_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):
+                    absence_records.extend(payload)
+
+            if not absence_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(absence_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=AbsencesGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve absence data.") from exc
+
+    def get_types(self) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve absence type definitions (global for the instance).
+        """
+        try:
+            type_records: List[Dict[str, Any]] = []
+            response = self.sage.get(
+                path=self.types_url,
+            )
+            response.raise_for_status()
+            payload = response.json()
+            if isinstance(payload, list):
+                type_records.extend(payload)
+
+            if not type_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(type_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=AbsenceTypesGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve absence type data.") from exc
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create an absence entry (AbsenceTime).
+
+        Accepts flat snake_case keys; converts to nested Sage payload using schema prefixes.
+        """
+        try:
+            nested_payload = sage_flat_to_nested_with_prefix(data, AbsenceCreate)
+            validated = AbsenceCreate(**nested_payload)
+            payload = validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+
+            response = self.sage.post(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create Sage Germany absence.") from exc
+
+    def update(self, data: Union[Dict[str, Any], List[Dict[str, Any]]]) -> Dict[str, Any]:
+        """
+        Update absence entries (AbsenceTime) via bulk PUT.
+
+        Accepts a single dict or list of dicts in flat snake_case form; each item is
+        validated against the AbsenceCreateRequest schema and sent as a list payload.
+        """
+        if isinstance(data, dict):
+            items = [data]
+        elif isinstance(data, list):
+            if not data:
+                raise ValueError("Absence update payload list must not be empty.")
+            if not all(isinstance(item, dict) for item in data):
+                raise ValueError("Absence update payload list must contain only dictionaries.")
+            items = data
+        else:
+            raise ValueError("Absence update payload must be a dictionary or list of dictionaries.")
+
+        try:
+            payload = [
+                AbsenceCreate(
+                    **sage_flat_to_nested_with_prefix(item, AbsenceCreate)
+                ).model_dump(by_alias=True, exclude_none=True, mode="json")
+                for item in items
+            ]
+        except Exception as exc:
+            raise ValueError(f"Invalid absence update payload: {exc}") from exc
+
+        try:
+            response = self.sage.put(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to update Sage Germany absences.") from exc
+
+    def delete(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Delete an absence entry.
+
+        Requires at minimum Id, MdNr, AnNr. Accepts flat snake_case keys.
+        """
+        try:
+            validated = AbsenceDelete(**data)
+            payload = validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+        except Exception as exc:
+            raise ValueError(f"Invalid absence delete payload: {exc}") from exc
+
+        try:
+            response = self.sage.delete(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to delete Sage Germany absence.") from exc

brynq_sdk_sage_germany/allowances.py

@@ -0,0 +1,100 @@
+"""
+Allowances endpoint implementations for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
+from datetime import datetime, timezone
+
+import pandas as pd
+from brynq_sdk_functions import Functions
+
+from .schemas.allowances import AllowancesGet, AllowanceCreateRequest
+from .helpers import sage_flat_to_nested_with_prefix
+
+if TYPE_CHECKING:
+    from .employees import Employees
+
+
+class Allowances:
+    """
+    Handles allowance-related operations scoped to employees.
+    """
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.base_url = "/employeenew/entgelte/festebeundabzuege"
+
+    def get(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve allowances for a specific employee or all employees (optionally filtered by date).
+        """
+        try:
+            if company_id is not None and employee_number is not None:
+                employee_keys = [{"MdNr": company_id, "AnNr": employee_number}]
+            else:
+                employee_keys = self.sage._employee_search()
+
+            if not employee_keys:
+                return pd.DataFrame(), pd.DataFrame()
+
+            allowances_records = []
+            for key in employee_keys:
+                params = {
+                    "MdNr": key["MdNr"],
+                    "AnNr": key["AnNr"],
+                    "date": date
+                    or datetime.now(timezone.utc).strftime("%Y-%m-%dT00:00:00"),
+                }
+
+                response = self.sage.get(
+                    path=self.base_url,
+                    params=params,
+                )
+                response.raise_for_status()
+                payload = response.json()
+                if isinstance(payload, list):
+                    allowances_records.extend(payload)
+
+            if not allowances_records:
+                return pd.DataFrame(), pd.DataFrame()
+
+            df = pd.json_normalize(allowances_records, sep="__")
+
+            valid_data, invalid_data = Functions.validate_data(
+                df=df,
+                schema=AllowancesGet,
+            )
+            return valid_data, invalid_data
+        except Exception as exc:
+            raise RuntimeError("Failed to retrieve allowance data.") from exc
+
+    def create(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create or update a fixed earning/deduction (festebeundabzuege) entry.
+
+        Accepts flat, snake_case keys; converts to nested payload per schema
+        prefixes, then serializes using Sage aliases.
+        """
+        try:
+            nested_payload = sage_flat_to_nested_with_prefix(data, AllowanceCreateRequest)
+            validated = AllowanceCreateRequest(**nested_payload)
+            payload = validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+        except Exception as exc:
+            raise ValueError(f"Invalid allowance payload: {exc}") from exc
+
+        try:
+            response = self.sage.post(
+                path=self.base_url,
+                body=payload,
+            )
+            response.raise_for_status()
+            return response
+        except Exception as exc:
+            raise RuntimeError("Failed to create Sage Germany allowance.") from exc

brynq_sdk_sage_germany/contracts.py

@@ -0,0 +1,145 @@
+"""
+Contracts aggregation for Sage Germany.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+import pandas as pd
+
+from .start_end_dates import StartEndDates
+from .payroll import Payroll
+from .work_hours import WorkHours
+from .vacation_account import VacationAccount
+from .organization import Organization
+from .salaries import Salary
+
+
+class Contracts:
+    """
+    Aggregates contract-related data points from existing services.
+    """
+
+    START_END_FIELDS = [
+        "combined_key",
+        "probation_end",
+        "service_time",
+        "service_time_duration",
+        "employment_time",
+        "employment_time_duration",
+    ]
+
+    PAYROLL_FIELDS = [
+        "combined_key",
+        "employment_type_text",
+        "contract_form_text",
+        "employee_group_text",
+        "multi_employed",
+        "social_insurance_key",
+    ]
+
+    WORK_HOUR_FIELDS = [
+        "combined_key",
+        "work_schedule_label",
+        "weekly_hours_average",
+        "days_per_week",
+        "calendar_text",
+    ]
+
+    VACATION_FIELDS = [
+        "combined_key",
+        "vacation_table_text",
+        "entitlement_current_year",
+        "rest_total",
+        "rest_current_year",
+        "reference_year",
+    ]
+
+    ORGANIZATION_FIELDS = [
+        "combined_key",
+        "payroll_group_text",
+        "payroll_run_text",
+        "site_text",
+        "position_text",
+        "search_term_1",
+    ]
+
+    SALARY_FIELDS = [
+        "combined_key",
+        "agreed_salary_amount",
+        "allowance_one_amount",
+        "allowance_two_amount",
+        "automatic_advance_payment",
+        "advance_payment_amount",
+        "hourly_rate_1",
+        "base_hourly_wage",
+    ]
+
+    def __init__(self, sage) -> None:
+        self.sage = sage
+        self.start_end_dates = StartEndDates(sage)
+        self.payroll = Payroll(sage)
+        self.work_hours = WorkHours(sage)
+        self.vacation_account = VacationAccount(sage)
+        self.organization = Organization(sage)
+        self.salary = Salary(sage)
+
+    def get(
+        self,
+        date: Optional[str] = None,
+        company_id: Optional[int] = None,
+        employee_number: Optional[int] = None,
+    ) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        """
+        Retrieve a merged contract view by combining core datasets.
+        """
+
+        datasets= []
+
+        self._add_dataset(
+            self.start_end_dates.get(date=date, company_id=company_id, employee_number=employee_number)[0],
+            self.START_END_FIELDS,
+            datasets,
+        )
+        self._add_dataset(
+            self.payroll.get_master_data(date=date, company_id=company_id, employee_number=employee_number)[0],
+            self.PAYROLL_FIELDS,
+            datasets,
+        )
+        self._add_dataset(
+            self.work_hours.get(date=date, company_id=company_id, employee_number=employee_number)[0],
+            self.WORK_HOUR_FIELDS,
+            datasets,
+        )
+        self._add_dataset(
+            self.vacation_account.get(date=date, company_id=company_id, employee_number=employee_number)[0],
+            self.VACATION_FIELDS,
+            datasets,
+        )
+        self._add_dataset(
+            self.organization.get(date=date, company_id=company_id, employee_number=employee_number)[0],
+            self.ORGANIZATION_FIELDS,
+            datasets,
+        )
+        salary_data, _ = self.salary.get(
+            company_id=company_id,
+            employee_number=employee_number,
+        )
+        self._add_dataset(salary_data, self.SALARY_FIELDS, datasets)
+
+        if not datasets:
+            return pd.DataFrame(), pd.DataFrame()
+
+        contracts_df = datasets[0]
+        for frame in datasets[1:]:
+            contracts_df = contracts_df.merge(frame, on="combined_key", how="left")
+
+        return contracts_df, pd.DataFrame()
+
+    def _add_dataset(self, frame: pd.DataFrame, fields: List[str], datasets: List[pd.DataFrame]) -> None:
+        if frame.empty:
+            return
+        existing = [field for field in fields if field in frame.columns]
+        if existing:
+            datasets.append(frame[existing].drop_duplicates(subset=["combined_key"]))