brynq-sdk-trimergo 1.0.0__py3-none-any.whl

brynq_sdk_trimergo/__init__.py

@@ -0,0 +1,211 @@
+"""Trimergo API client for interacting with the Trimergo HR system.
+
+This module provides a client for making authenticated requests to the Trimergo API,
+handling authentication, retries, and session management.
+"""
+
+# Standard library imports
+import base64
+from typing import Optional, Tuple, Any
+
+# Third-party imports
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+# Local imports
+from brynq_sdk_brynq import BrynQ
+from .timesheet import Timesheet
+
+class Trimergo(BrynQ):
+    """Client for interacting with the Trimergo HR system API.
+
+    Handles authentication, session management, and provides methods for
+    accessing various Trimergo API services like Timesheet.
+
+    Attributes:
+        trimergo_host (str): The base URL for the Trimergo API.
+        trimergo_session (requests.Session): The authenticated session for API requests.
+        openapi_json (dict): The OpenAPI specification for the Trimergo API.
+        timesheet (Timesheet): An instance of the Timesheet service client.
+        OPENAPI_VERSION (str): Expected OpenAPI version.
+        TRIMERGO_T2_WEBSERVICES_VERSION (str): Expected Trimergo T2 WebServices version.
+    """
+
+    OPENAPI_VERSION: str = "3.0.1"
+    TRIMERGO_T2_WEBSERVICES_VERSION: str = "1.1.0"
+
+    def __init__(
+        self,
+        interface_id: str,
+        test_environment: bool,
+        system_type: str
+    ) -> None:
+        """Initializes the Trimergo API client.
+
+        Retrieves credentials, initializes an authenticated session, and
+        sets up service-specific clients.
+
+        Args:
+            interface_id (str): ID of the interface to get credentials for.
+            test_environment (bool): True if using the test environment, False otherwise.
+            system_type (str): Specifies 'source' or 'target' system.
+        """
+        super().__init__()
+        # Retrieve trimergo's host (base url) and credentials
+        self.trimergo_host: str
+        trimergo_username: str
+        trimergo_password: str
+        self.trimergo_host, trimergo_username, trimergo_password = (
+            self._get_trimergo_credentials(
+                interface_id, test_environment, system_type
+            )
+        )
+        # Init trimergo session and retrieve openapi json
+        self.trimergo_session: requests.Session
+        self.openapi_json: dict
+        self.trimergo_session, self.openapi_json = self._init_trimergo_session(
+            trimergo_username, trimergo_password
+        )
+        # Init service classes
+        self.timesheet: Timesheet = Timesheet(self)
+
+    def _get_trimergo_credentials(
+        self,
+        interface_id: str = "1",
+        test_environment: bool = False,
+        system_type: Optional[str] = None,
+    ) -> Tuple[str, str, str]:
+        """Retrieves Trimergo API credentials from BrynQ's interface system.
+
+        Args:
+            interface_id (str): ID of the interface.
+            test_environment (bool): True if using the test environment.
+            system_type (Optional[str]): 'source' or 'target'.
+
+        Returns:
+            Tuple[str, str, str]: host, username, password.
+
+        Raises:
+            ValueError: If any required credentials (host, username, password) are missing.
+            Exception: If credential retrieval fails for other reasons.
+        """
+        try:
+            creds =  self.interfaces.credentials.get(
+                system="trimergo",
+                system_type=system_type,
+            )
+
+            if not creds or not creds.get("data"):
+                raise Exception(
+                    f"Failed to retrieve credentials for interface_id {interface_id}. "
+                    f"Response: {creds}"
+                )
+
+            data = creds["data"]
+            host = data.get("host")
+            username = data.get("username")
+            password = data.get("password")
+
+            missing_fields = []
+            if not host or not host.strip():
+                missing_fields.append("host")
+            if not username or not username.strip():
+                missing_fields.append("username")
+            if not password or not password.strip():
+                missing_fields.append("password")
+
+            if missing_fields:
+                error_message = f"Missing Trimergo credentials: {', '.join(missing_fields)}."
+                raise ValueError(error_message)
+
+            return str(host), str(username), str(password)
+        except ValueError:
+            raise
+        except Exception as e:
+            error_message = (
+                f"An unexpected error occurred while retrieving Trimergo credentials "
+                f"for interface_id {interface_id}: {e}"
+            )
+            raise Exception(error_message) from e
+
+    def _init_trimergo_session(
+        self, trimergo_username: str, trimergo_password: str
+    ) -> Tuple[requests.Session, dict]:
+        """Initializes and returns an authenticated Trimergo API session and OpenAPI spec.
+
+        Args:
+            trimergo_username (str): Username for Trimergo API.
+            trimergo_password (str): Password for Trimergo API.
+
+        Returns:
+            Tuple[requests.Session, dict]: Authenticated session and OpenAPI JSON.
+
+        Raises:
+            Exception: If session initialization or version check fails.
+        """
+        try:
+            retry_strategy = Retry(
+                total=3,
+                backoff_factor=1,
+                status_forcelist=[500, 502, 503, 504, 400, 401, 403, 404],
+                allowed_methods=["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE", "POST"],
+            )
+            trimergo_session = requests.Session()
+            adapter = HTTPAdapter(max_retries=retry_strategy)
+            trimergo_session.mount("http://", adapter)
+            trimergo_session.mount("https://", adapter)
+            auth_string = f"{trimergo_username}:{trimergo_password}"
+            auth_b64 = self._encode_string(auth_string)
+            trimergo_session.headers.update({
+                "Authorization": f"Basic {auth_b64}",
+                "Content-Type": "application/json",
+            })
+
+            openapi_url = f"{self.trimergo_host}/tri-server-gateway-ws/api/rest/openapi.json"
+            response = trimergo_session.get(openapi_url)
+            response.raise_for_status()
+
+            openapi_json: dict = response.json()
+
+            api_openapi_version = openapi_json.get("openapi")
+            api_info_version = openapi_json.get("info", {}).get("version")
+
+            if api_openapi_version != self.OPENAPI_VERSION or \
+               api_info_version != self.TRIMERGO_T2_WEBSERVICES_VERSION:
+                warning_msg = (
+                    f"Version mismatch detected for Trimergo API. "
+                    f"Expected OpenAPI: {self.OPENAPI_VERSION} (Got: {api_openapi_version}), "
+                    f"Expected T2 WebServices: {self.TRIMERGO_T2_WEBSERVICES_VERSION} "
+                    f"(Got: {api_info_version}). API might not be compatible."
+                )
+                print(f"WARNING: {warning_msg}")
+
+            return trimergo_session, openapi_json
+        except requests.exceptions.HTTPError as http_err:
+            err_msg = (
+                f"HTTP error during Trimergo session initialization for {openapi_url}: "
+                f"{http_err.response.status_code} - {http_err.response.text}"
+            )
+            raise Exception(err_msg) from http_err
+        except requests.exceptions.RequestException as req_err:
+            err_msg = f"Request error initializing Trimergo session for {openapi_url}: {req_err}"
+            raise Exception(err_msg) from req_err
+        except Exception as e:
+            err_msg = (
+                f"Unexpected error during Trimergo session initialization for {openapi_url}: {e}"
+            )
+            raise Exception(err_msg) from e
+
+    def _encode_string(self, string_to_encode: str) -> str:
+        """Encodes a string to Base64 for Trimergo API authentication headers.
+
+        Args:
+            string_to_encode (str): The string to be Base64 encoded.
+
+        Returns:
+            str: The Base64 encoded string.
+        """
+        string_bytes = string_to_encode.encode('utf-8')
+        string_b64_bytes = base64.b64encode(string_bytes)
+        return string_b64_bytes.decode('utf-8')

brynq_sdk_trimergo/pageinfo_wrapper/pageinfo.py

@@ -0,0 +1,160 @@
+"""Defines PageInfo, Criterion, and Sorter classes for Trimergo API interactions. It wraps/mirrors pageinof.js, which handles query parameters for the trimergo api.
+
+These classes are used to construct and encode query parameters for filtering,
+sorting, and paginating Trimergo API responses, particularly for services
+like Timesheet.
+"""
+
+import base64
+import json
+from typing import Any, Dict, List, Optional
+
+#  Helpers – JS‑identical Base64‑URL codec
+_B64_PLUS = b"+"
+_B64_SLASH = b"/"
+_B64_DASH = b"-"
+_B64_UNDERSCORE = b"_"
+_B64_PAD = b"="
+
+def _b64url_encode(raw: str) -> str:
+    """Encodes a string to a URL-safe Base64 string."""
+    out = base64.b64encode(raw.encode())
+    out = out.replace(_B64_PLUS, _B64_DASH).replace(_B64_SLASH, _B64_UNDERSCORE)
+    return out.rstrip(_B64_PAD).decode()
+
+def _b64url_decode(data: str) -> str:
+    """Decodes a URL-safe Base64 string."""
+    fixed = data.replace("-", "+").replace("_", "/")
+    fixed += "=" * (-len(fixed) % 4)
+    return base64.b64decode(fixed).decode()
+
+class Criterion:
+    """Represents a filter criterion for Trimergo API queries."""
+    __slots__ = ("f", "o", "v", "q")
+
+    def __init__(self,
+                 field: str,
+                 operator: str,
+                 value: Any,
+                 sub: "Optional[Criterion]" = None):
+        """Initializes a Criterion.
+
+        Args:
+            field (str): The field to filter on.
+            operator (str): The operator to use (e.g., '=', '>', 'LIKE').
+            value (Any): The value to compare against.
+            sub (Optional[Criterion]): A sub-criterion for nested queries.
+        """
+        self.f: str = field
+        self.o: str = operator
+        self.v: Any = value
+        self.q: List[Dict[str, Any]] = []
+        if sub is not None:
+            self.q.append(sub.to_dict())
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts the criterion to its dictionary representation."""
+        return {"f": self.f,
+                "o": self.o,
+                "v": self.v,
+                "q": self.q}
+
+class Sorter:
+    """Represents a sort order for Trimergo API queries."""
+    ASC = "asc"
+    DESC = "desc"
+    __slots__ = ("f", "t")
+
+    def __init__(self, field: str,
+                 direction: str):
+        """Initializes a Sorter.
+
+        Args:
+            field (str): The field to sort by.
+            direction (str): The sort direction ('asc' or 'desc').
+
+        Raises:
+            ValueError: If direction is not 'asc' or 'desc'.
+        """
+        if (d := direction.lower()) not in (self.ASC, self.DESC):
+            raise ValueError("Sorter direction must be 'asc' or 'desc'.")
+        self.f: str = field
+        self.t: str = d
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts the sorter to its dictionary representation."""
+        return {"f": self.f, "t": self.t}
+
+class PageInfo:
+    """Represents pagination, filtering, and sorting parameters for Trimergo API queries.
+
+    This class provides methods to add criteria and sorters, and to encode these
+    parameters into the format expected by the Trimergo API.
+    """
+    def __init__(self) -> None:
+        """Initializes a PageInfo object with default pagination settings."""
+        self.pageNo: int = 1
+        self.rpp: int = 1000  # Records Per Page
+        self.criteria: List[Dict[str, Any]] = []
+        self.haystack: Dict[str, Any] = {"fields": [], "needle": ""}
+        self.sorters: List[Dict[str, Any]] = []
+
+    def addCriterion(self, c: Criterion) -> None:
+        """Adds a criterion to the PageInfo.
+
+        Args:
+            c (Criterion): The criterion to add.
+        """
+        self.criteria.append({"q": c.to_dict()})
+
+    def wrapCriterion(self, wrapper: Criterion) -> None:
+        """Wraps existing criteria with a new (outer) criterion, typically for AND logic.
+
+        Args:
+            wrapper (Criterion): The criterion to wrap existing criteria with.
+        """
+        for item in self.criteria:
+            wrapper.q.append(item["q"])
+        self.criteria = [{"q": wrapper.to_dict()}]
+
+    def addSorter(self, s: Sorter) -> None:
+        """Adds a sorter to the PageInfo.
+
+        Args:
+            s (Sorter): The sorter to add.
+        """
+        self.sorters.append({"s": s.to_dict()})
+
+    def _criteria_json(self) -> str:
+        """Internal helper to get criteria as a JSON string."""
+        # Trimergo's API expects empty sub-queries 'q':[] to be omitted
+        return json.dumps(self.criteria).replace(',"q":[]', "")
+
+    def getQ(self) -> str:
+        """Gets the Base64-URL encoded criteria string ('q' parameter)."""
+        return _b64url_encode(self._criteria_json()) if self.criteria else ""
+
+    def getH(self) -> str:
+        """Gets the Base64-URL encoded haystack search string ('h' parameter)."""
+        if not (self.haystack["fields"] and self.haystack["needle"]):
+            return ""
+        # Assuming haystack structure is correct for direct dump
+        return _b64url_encode(json.dumps({"h": self.haystack}))
+
+    def getO(self) -> str:
+        """Gets the Base64-URL encoded sorters string ('o' parameter)."""
+        return _b64url_encode(json.dumps(self.sorters)) if self.sorters else ""
+
+    def getProperties(self) -> Dict[str, str]:
+        """Constructs a dictionary of all page info properties for API query parameters."""
+        props: Dict[str, str] = {
+            "pageNo": str(self.pageNo),
+            "rpp": str(self.rpp)
+        }
+        if q_param := self.getQ():
+            props["q"] = q_param
+        if h_param := self.getH():
+            props["h"] = h_param
+        if o_param := self.getO():
+            props["o"] = o_param
+        return props

brynq_sdk_trimergo/schemas/timesheet.py

@@ -0,0 +1,74 @@
+import pandera as pa
+from pandera.typing import Series, String, Float, DateTime
+from typing import Optional
+import pandas as pd
+from brynq_sdk_functions import BrynQPanderaDataFrameModel
+
+class TimeSheetSchema(BrynQPanderaDataFrameModel):
+    # core timesheet attributes
+    actual_status: Series[String] = pa.Field(coerce=True, description="Actual Status (Y/N)", alias="actualStatus")
+    amount: Series[Float] = pa.Field(coerce=True, nullable=False, description="Billed Amount", alias="amount")
+    amount_break: Series[pd.Int64Dtype] = pa.Field(coerce=True, nullable=True, description="Amount Break (minutes)", alias="amountBreak")
+    approval_date: Series[DateTime] = pa.Field(coerce=True, nullable=True, description="Approval Date", alias="approvalDate")
+    approval_state: Series[String] = pa.Field(coerce=True, nullable=False, description="Approval State Code", alias="approvalState")
+    budget_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Budget Key", alias="budgetKey")
+    etc: Series[Float] = pa.Field(coerce=True, nullable=True, description="ETC Value", alias="etc")
+    extra: Series[bool] = pa.Field(coerce=True, nullable=False, description="Has Extra Flag", alias="extra")
+    extra_time: Series[String] = pa.Field(coerce=True, nullable=True, description="Extra Time Code", alias="extraTime")
+    percentage_done: Series[Float] = pa.Field(coerce=True, nullable=True, description="% Complete", alias="percentageDone")
+    planning_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Planning Key", alias="planningKey")
+    resource_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Resource Key", alias="resourceKey")
+    show_on_report_ready: Optional[Series[pd.BooleanDtype]] = pa.Field(coerce=True, nullable=True, description="Visible On Report", alias="showOnReportReady")
+    str_extra: Series[String] = pa.Field(coerce=True, nullable=True, description="Extra Time (string)", alias="strExtra")
+    tdate: Series[DateTime] = pa.Field(coerce=True, nullable=False, description="Timesheet Date", alias="tdate")
+    time_from: Series[pd.Int64Dtype] = pa.Field(coerce=True, nullable=False, description="Start Minute of Day", alias="timeFrom")
+    time_to: Series[pd.Int64Dtype] = pa.Field(coerce=True, nullable=False, description="End Minute of Day", alias="timeTo")
+    timesheet_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Timesheet Entry Key", alias="timesheetKey")
+    worktype_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Work Type Key", alias="worktypeKey")
+
+    # project sub-object (flattened)
+    project_budget_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Budget Key", alias="project_budgetKey")
+    project_description: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Description", alias="project_description")
+    project_is_parent: Series[bool] = pa.Field(coerce=True, nullable=False, description="Project Is Parent", alias="project_isParent")
+    project_planning_exchange_rate: Series[Float] = pa.Field(coerce=True, nullable=False, description="Project Exchange Rate", alias="project_planningExchangeRate")
+    project_planning_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Planning Key", alias="project_planningKey")
+    project_project_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Key", alias="project_projectKey")
+    project_project_number: Series[String] = pa.Field(coerce=True, nullable=True, description="Project Number", alias="project_projectNumber")
+    project_project_type: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Type Code", alias="project_projectType")
+    project_schedule_duration: Series[pd.Int64Dtype] = pa.Field(coerce=True, nullable=False, description="Scheduled Duration (min)", alias="project_scheduleDuration")
+    project_schedule_finish: Series[String] = pa.Field(coerce=True, nullable=True, description="Scheduled Finish", alias="project_scheduleFinish")
+    project_schedule_start: Series[String] = pa.Field(coerce=True, nullable=True, description="Scheduled Start", alias="project_scheduleStart")
+    project_status: Series[String] = pa.Field(coerce=True, nullable=False, description="Project Status Code", alias="project_status")
+    project_type_name: Series[String] = pa.Field(coerce=True, nullable=False, description="Type Name", alias="project_typeName")
+    project_user_type: Series[String] = pa.Field(coerce=True, nullable=False, description="User Type Code", alias="project_userType")
+
+    # client sub-object (flattened)
+    client_active: Optional[Series[pd.BooleanDtype]] = pa.Field(coerce=True, nullable=True, description="Client Is Active", alias="client_active")
+    client_city_address: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Client City", alias="client_cityAddress")
+    client_country_code: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Client Country Code", alias="client_countryCodeAddress")
+    client_phone1: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Primary Phone", alias="client_phone1")
+    client_phone2: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Secondary Phone", alias="client_phone2")
+    client_relation_address: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Street Address", alias="client_relationAddress")
+    client_relation_id: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Relation ID", alias="client_relationId")
+    client_relation_name: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Relation Name", alias="client_relationName")
+    client_relation_number: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Relation Number", alias="client_relationNumber")
+    client_relation_types: Optional[Series[pd.Int64Dtype]] = pa.Field(coerce=True, nullable=True, description="Relation Types", alias="client_relationTypes")
+    client_zip_address: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="ZIP Code", alias="client_zipAddress")
+    client_country_name: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Country Name", alias="client_countryNameAddress")
+    client_business_unit_key: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="Business Unit Key", alias="client_businessUnitKey")
+
+    # customFields.item[0].value
+    vv_project_uren_locatie: Optional[Series[String]] = pa.Field(coerce=True, nullable=True, description="VV Project Uren Locatie", alias="customFields_item_0_value")
+
+    # resource sub-object (flattened)
+    resource_active: Series[bool] = pa.Field(coerce=True, nullable=False, description="Resource Is Active", alias="resource_active")
+    resource_description: Series[String] = pa.Field(coerce=True, nullable=False, description="Resource Description", alias="resource_description")
+    resource_key: Series[String] = pa.Field(coerce=True, nullable=False, description="Resource Key", alias="resource_resourceKey")
+    resource_number: Series[String] = pa.Field(coerce=True, nullable=False, description="Resource Number", alias="resource_resourceNumber")
+
+    # workType sub-object
+    worktype_description: Series[String] = pa.Field(coerce=True, nullable=False, description="Work Type Description", alias="workType_description")
+    worktype_code: Series[String] = pa.Field(coerce=True, nullable=False, description="Work Type Code", alias="workType_workTypeCode")
+
+    class Config:
+        coerce = True

brynq_sdk_trimergo/timesheet.py

@@ -0,0 +1,350 @@
+"""timesheet.py — Hybrid client for Trimergo timesheets.
+Hybrid in the sense that it supports both pythonic keyword arguments or a PageInfo object for precise query construction.
+Client because it is a client for the Trimergo timesheet API.
+
+This module provides the Timesheet class, which allows interaction with the
+Trimergo timesheet API. It supports querying timesheets using either legacy
+keyword arguments or a PageInfo object that mirrors Trimergo's JavaScript
+PageInfo for precise query construction.
+
+Key Goals:
+1.  Easy and flexible to use: The client is easy to use in both a pythonic way and a more close to API way.
+2.  Consistent query generation: Utilizes a Python port of Trimergo's
+    PageInfo, Criterion, and Sorter to ensure query payloads match those
+    generated by browser interactions.
+3.  Advanced usage: Offers direct access to the PageInfo builder for crafting
+    complex AND/OR filter combinations.
+
+Usage Examples:
+Pythonic Keyword Arguments (kwargs):
+```python
+from trimergo_client import Trimergo # Assuming Trimergo client is available
+tgo_client = Trimergo(interface_id='1', test_environment=False, system_type='source')
+sheet = Timesheet(tgo_client)
+df = sheet.get(tdate__gt="20250101")
+```
+
+PageInfo Builder (similar to Trimergo's JS documentation):
+```python
+from .pageinfo import PageInfo, Criterion # Assuming pageinfo.py is in the same directory
+
+pi = PageInfo()
+pi.addCriterion(Criterion(field="last_name", operator="=", value="Doe"))
+# pi.addSorter(Sorter(field="last_name", direction=Sorter.ASC)) # Sorter not used in this file
+df = sheet.get(pageinfo=pi)
+```
+"""
+# Standard library imports
+from __future__ import annotations
+import re
+import urllib.parse
+from typing import Any, Dict, List, Optional
+
+# Third-party imports
+import pandas as pd
+import requests
+
+# Local imports
+from .schemas.timesheet import TimeSheetSchema
+from . pageinfo_wrapper.pageinfo import PageInfo, Criterion
+from brynq_sdk_functions import Functions
+
+class Timesheet:
+    """Service wrapper for Trimergo timesheets with dual query styles."""
+    _OP_SUFFIX: Dict[str, str] = {
+        "eq": "=",
+        "neq": "!=",
+        "gt": ">",
+        "lt": "<",
+        "gte": ">=",
+        "lte": "<=",
+        "contains": "LIKE",
+        "startswith": "STARTSWITH",
+        "endswith": "ENDSWITH",
+    }
+
+    _DEFAULT_FIELD_STRINGS: List[str] = [
+        'ts.tdate', 'ts.time_from', 'ts.time_to', 'ts.notes',
+        'ts.show_on_reportready', 'ts.amount', 'pl.user_type',
+        'pl.installation_key', 'pr.type_name', 'pr.project_number',
+        'pr.description', 'r.relation_key', 'wt.description',
+        'res.description', 'sys.fn_varbintohexstr(ts.row_versionid)'
+    ]
+
+    def __init__(self, trimergo_client: Any) -> None:
+        self._tgo: Any = trimergo_client  # expects .trimergo_host & .trimergo_session
+        self._allowed: List[Dict[str, str]] = self._load_allowed_fields()
+
+    def get(
+        self,
+        *,
+        pageinfo: Optional[PageInfo] = None,
+        page: int = 1,
+        rpp: int = 1000,
+        map_type: str = "tiny",
+        max_pages: int = int(1e9),
+        **filters: Any,
+    ) -> pd.DataFrame:
+        """Retrieves timesheet data from Trimergo.
+
+        If `pageinfo` is supplied, `filters` are ignored. Otherwise, `filters`
+        are used to construct a PageInfo object internally.
+
+        Args:
+            pageinfo: An optional PageInfo object for precise query control.
+            page: The page number to start fetching from (1-based).
+            rpp: Records per page.
+            map_type: The map type for the API request (e.g., "tiny").
+            max_pages: Maximum number of pages to fetch.
+            **filters: Keyword arguments for filtering (legacy method).
+
+        Returns:
+            A pandas DataFrame containing the timesheet records.
+
+        Raises:
+            ValueError: If both `pageinfo` and `filters` are provided.
+        """
+        if pageinfo and filters:
+            raise ValueError("Pass either 'pageinfo' or filter kwargs, not both.")
+
+        current_pageinfo: PageInfo
+        if pageinfo is None:
+            current_pageinfo = self._kwargs_to_pageinfo(filters, page, rpp)
+        else:
+            current_pageinfo = pageinfo
+            current_pageinfo.pageNo = page
+            current_pageinfo.rpp = rpp
+
+        params = {"map": map_type, **current_pageinfo.getProperties()}
+        df = self._fetch_pages(params=params, start_page=page, max_pages=max_pages)
+        valid_timesheet, invalid_timesheet = Functions.validate_data(df=df, schema=TimeSheetSchema, debug=True)
+        return valid_timesheet, invalid_timesheet
+
+    # Private helpers
+    def _kwargs_to_pageinfo(
+        self, filters: Dict[str, Any], page: int, rpp: int
+    ) -> PageInfo:
+        """Translates legacy keyword arguments into a PageInfo object."""
+        allowed_vars = {d["variable"]: d for d in self._allowed}
+        pi = PageInfo()
+        pi.pageNo = page
+        pi.rpp = rpp
+
+        for idx, (raw_key, value) in enumerate(filters.items()):
+            op = "="
+            field_name = raw_key
+            if "__" in raw_key:
+                base, suffix = raw_key.rsplit("__", 1)
+                if suffix in self._OP_SUFFIX:
+                    op = self._OP_SUFFIX[suffix]
+                    field_name = base
+
+            base_var = field_name.split(".")[-1]
+            if base_var not in allowed_vars:
+                raise ValueError(f"Illegal filter field: {raw_key!r}")
+
+            prefix = allowed_vars[base_var]["prefix"]
+            if "." not in field_name and prefix:
+                field_name = f"{prefix}.{field_name}"
+
+            crit = Criterion(field_name, op, value)
+            if idx == 0:
+                pi.addCriterion(crit)  # seed
+            else:
+                pi.wrapCriterion(crit)  # nest → logical AND
+        return pi
+
+    def _fetch_and_validate_page_data(
+        self,
+        url: str,
+        params: Dict[str, str],
+        page_num: int
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Fetches a single page of data and performs initial validation."""
+        try:
+            resp = self._tgo.trimergo_session.get(url, params=params)
+            resp.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)
+            data = resp.json()
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error fetching page {page_num} ({url}): {http_err}")
+            return None
+        except requests.exceptions.JSONDecodeError as json_err:
+            print(f"JSON decode error for page {page_num} ({url}): {json_err}")
+            return None
+        except requests.exceptions.RequestException as req_err:  # Catches other request-related errors
+            print(f"Request error fetching page {page_num} ({url}): {req_err}")
+            return None
+
+        if not isinstance(data, list):
+            print(f"API Error: Expected list, got {type(data)} for page {page_num}.")
+            return None
+        return data
+
+    def _fetch_pages(
+        self,
+        params: Dict[str, str],
+        *,
+        start_page: int = 1,
+        max_pages: int = int(1e9),
+    ) -> pd.DataFrame:
+        """Crawls paginated Trimergo /timesheet endpoint; returns flat DataFrame."""
+        rpp = int(params.get("rpp", 1000))
+        page_num = start_page
+        records: List[Dict[str, Any]] = []
+
+        while page_num <= max_pages:
+            url = urllib.parse.urljoin(
+                self._tgo.trimergo_host,
+                f"/tri-server-gateway-ws/api/rest/timesheet/page/{page_num}",
+            )
+
+            page_data = self._fetch_and_validate_page_data(url, params, page_num)
+
+            if page_data is None: # Error occurred or invalid data structure
+                break
+
+            if not page_data: # Empty list, means no more data
+                break
+
+            for item in page_data:
+                if isinstance(item, dict) and "timesheet" in item:
+                    records.append(self._flatten_dict(item["timesheet"]))
+                else:
+                    # Log or handle malformed item if necessary
+                    print(f"Warning: Malformed item on page {page_num}: {item}")
+
+            if len(page_data) < rpp:
+                break  # Last page fetched
+            page_num += 1
+        return pd.DataFrame.from_records(records)
+
+    def _get_nested_value(
+        self, data: Dict[str, Any], path: List[str], default: Any = None
+    ) -> Any:
+        """Safely retrieves a value from a nested dictionary path."""
+        current_level = data
+        for key in path:
+            if not isinstance(current_level, dict):
+                # print(f"Warning: Path traversal failed. Expected dict at segment "
+                #       f"{key_index} ('{key}'), got {type(current_level)}.")
+                return default
+            current_level = current_level.get(key)
+            if current_level is None:
+                # print(f"Warning: Path key '{key}' (segment {key_index}) not found.")
+                return default
+        return current_level
+
+    def _flatten_dict(
+        self, d: Dict[str, Any], parent: str = "", sep: str = "_"
+    ) -> Dict[str, Any]:
+        """Recursively flattens nested dicts."""
+        items: Dict[str, Any] = {}
+        for k, v in d.items():
+            new_key = f"{parent}{sep}{k}" if parent else k
+            if isinstance(v, dict) and v:
+                items.update(self._flatten_dict(v, new_key, sep))
+            elif isinstance(v, list):
+                items[new_key] = str(v)
+            elif not isinstance(v, dict): # Add if not dict (to include non-empty values)
+                items[new_key] = v
+        return items
+
+    def _parse_raw_field_strings(self, raw_strings: List[str]) -> List[Dict[str, str]]:
+        """Parses a list of raw field strings into dictionary descriptors."""
+        parsed_fields: List[Dict[str, str]] = []
+        for field_str in raw_strings:
+            try:
+                parsed_fields.append(self._parse_field_descriptor(field_str))
+            except ValueError as ve:
+                print(
+                    f"Warning: Failed to parse field descriptor '{field_str}': {ve}. "
+                    f"Skipping."
+                )
+        return parsed_fields
+
+    def _extract_fields_from_openapi_desc(self) -> List[str]:
+        """Attempts to extract filter field strings from OpenAPI description."""
+        if not (
+            self._tgo
+            and hasattr(self._tgo, 'openapi_json')
+            and isinstance(self._tgo.openapi_json, dict)
+        ):
+            return []
+
+        description_path: List[str] = [
+            "paths", "/api/rest/*/timesheet/page/{pag}", "get", "description"
+        ]
+        description: Any = self._get_nested_value(
+            self._tgo.openapi_json, description_path, default=""
+        )
+        if not isinstance(description, str):
+            description = "" # Ensure description is a string for .split later
+
+        marker: str = "You can filter on these fields:"
+        if marker in description:
+            fields_part = description.split(marker, 1)[1]
+            return [f.strip() for f in fields_part.split(",") if f.strip()]
+        return []
+
+    def _load_allowed_fields(self) -> List[Dict[str, str]]:
+        """Loads allowed filter fields for Trimergo timesheets."""
+        raw_field_strings: List[str] = []
+        try:
+            raw_field_strings = self._extract_fields_from_openapi_desc()
+        except Exception as e: # Catch any error during OpenAPI extraction
+            print(
+                f"Error: Unexpected issue extracting fields from OpenAPI: {e}. "
+                f"Using default field strings."
+            )
+            # Fallback to default strings if OpenAPI extraction fails
+            raw_field_strings = self._DEFAULT_FIELD_STRINGS
+
+        if not raw_field_strings:
+            # print(
+            #     "Info: No fields from OpenAPI or extraction failed cleanly. "
+            #     "Using default field strings."
+            # )
+            raw_field_strings = self._DEFAULT_FIELD_STRINGS
+
+        parsed_fields = self._parse_raw_field_strings(raw_field_strings)
+
+        if not parsed_fields:
+            # This means all attempts (OpenAPI or default) yielded no parsable fields.
+            # This is critical if even defaults fail.
+            print(
+                "Critical Warning: All field strings (OpenAPI or default) failed to parse. "
+                "Attempting to parse hardcoded defaults again as a final fallback."
+            )
+            # Try parsing default strings one last time if all else failed
+            parsed_fields = self._parse_raw_field_strings(self._DEFAULT_FIELD_STRINGS)
+            if not parsed_fields:
+                # If even this fails, something is fundamentally wrong with parsing logic or defaults
+                raise RuntimeError(
+                    "Failed to parse any field descriptors, including hardcoded defaults. "
+                    "Timesheet filtering will be severely impacted."
+                )
+        return parsed_fields
+
+    @staticmethod
+    def _parse_field_descriptor(d: str) -> Dict[str, str]:
+        """Parses a Trimergo field descriptor string into its prefix and variable name."""
+        desc_str = d.strip()
+        match = re.search(r'\((.*)\)', desc_str)
+        if match:
+            inner_content = match.group(1)
+            if '.' in inner_content:
+                desc_str = inner_content.strip()
+
+        if "." not in desc_str:
+            raise ValueError(
+                f"Field '{d}' malformed: expected 'prefix.variable' (got '{desc_str}')."
+            )
+
+        prefix, variable_part = desc_str.split(".", 1)
+        variable_name = variable_part.split(".")[0]
+
+        if not prefix.strip() or not variable_name.strip():
+            raise ValueError(
+                f"Field '{d}' -> empty prefix/var (pf='{prefix}',var='{variable_name}')."
+            )
+        return {"prefix": prefix.strip(), "variable": variable_name.strip()}

brynq_sdk_trimergo-1.0.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: brynq_sdk_trimergo
+Version: 1.0.0
+Summary: Trimergo wrapper from BrynQ
+Author: BrynQ
+Author-email: support@brynq.com
+License: BrynQ License
+Requires-Dist: brynq-sdk-brynq<5,>=4
+Requires-Dist: pandas<3.0.0,>=2.2.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
+
+Trimergo wrapper from BrynQ

brynq_sdk_trimergo-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+brynq_sdk_trimergo/__init__.py,sha256=AiVGBhn27hbqAlmQk2TC2qCajLQ1wz3ZC8jalPRPi10,8329
+brynq_sdk_trimergo/timesheet.py,sha256=oVvNy0-EVEH0FfLYV7Lr8ijpl9RtFBsp9vzPEYHwKPQ,14048
+brynq_sdk_trimergo/pageinfo_wrapper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brynq_sdk_trimergo/pageinfo_wrapper/pageinfo.py,sha256=qAeLIDqOlCs_P-Riof_Pa_AE2bfo5zIr3CCdku0WL3U,5691
+brynq_sdk_trimergo/schemas/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brynq_sdk_trimergo/schemas/timesheet.py,sha256=YGKbjfumAscx7oaucPlCfOwYd0gVT9f_BveHplK56JE,7761
+brynq_sdk_trimergo-1.0.0.dist-info/METADATA,sha256=zS_SvgrZmpyGyPjUSFh5RCnofn5GV9s4X9nU8jcq0js,386
+brynq_sdk_trimergo-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+brynq_sdk_trimergo-1.0.0.dist-info/top_level.txt,sha256=Sra4UJhCvcdQtwLtLX9rtXwdJIDdXnz6g8bZXi00jxY,19
+brynq_sdk_trimergo-1.0.0.dist-info/RECORD,,

brynq_sdk_trimergo-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brynq_sdk_trimergo-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+brynq_sdk_trimergo