tlnt-cli 1.5.1__py3-none-any.whl

tlnt/core/clients/mekari/client.py

@@ -0,0 +1,826 @@
+"""Concrete Mekari mobile API client."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from tlnt.core.clients.mekari import constants as mekari_constants
+from tlnt.core.clients.mekari.constants import (
+    ATTENDANCE_APPROVE_ENDPOINT,
+    CALENDAR_ACTIVITY_ENDPOINT,
+    CALENDAR_BIRTHDAY_ENDPOINT,
+    CALENDAR_HOLIDAY_ENDPOINT,
+    CALENDAR_INDEX_ENDPOINT,
+    CALENDAR_MY_BIRTHDAY_ENDPOINT,
+    CALENDAR_TIMEOFF_ENDPOINT,
+    DASHBOARD_USER_ENDPOINT,
+    GPS_ACCURACY,
+    INBOX_NOTIFICATION_ENDPOINT,
+    LOGOUT_ENDPOINT,
+    OAUTH2_TOKEN_URL,
+    TIMEOFF_APPROVE_ENDPOINT,
+    TIMEOFF_CANCEL_REQUEST_ENDPOINT,
+    TIMEOFF_DELEGATION_LIST_ENDPOINT,
+    TIMEOFF_HISTORY_ENDPOINT,
+    TIMEOFF_REQUEST_ENDPOINT,
+    clock_endpoint,
+    inbox_endpoint,
+    notification_detail_endpoint,
+    schedule_endpoint,
+    summary_attendance_clocks_endpoint,
+    summary_attendance_metrics_endpoint,
+    timeoff_balance_endpoint,
+    timeoff_detail_endpoint,
+)
+from tlnt.core.http_client import send_request
+from tlnt.core.logs import logger
+from tlnt.core.models import ActiveSchedule, MobileToken, Result, dig
+
+_TOKEN_SHAPE = re.compile(
+    r"^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}_\S+$",
+    re.IGNORECASE,
+)
+_SENSITIVE_KEYS = ("token", "cookie", "authorization", "password", "secret", "csrf")
+_log = logger.bind(component="mekari")
+
+
+def build_clock_fields(
+    schedule: ActiveSchedule,
+    event_type: str,
+    notes: str,
+    *,
+    latitude: str,
+    longitude: str,
+    location_id: str | None = None,
+) -> dict[str, str]:
+    fields = {
+        "notes": notes,
+        "latitude": latitude,
+        "longitude": longitude,
+        "source": "mobileapp",
+        "schedule_date": schedule.schedule_date,
+        "attendance_clock_type": schedule.clock_type,
+        "attendance_office_hour_id": schedule.office_hour_id,
+        "attendance_office_hour_setting_id": schedule.office_hour_setting_id,
+        "on_live_tracking": "false",
+        "end_live_tracking": "true",
+        "event_type": event_type,
+        "mixpanel[Entry point]": "Index",
+        "gps_accuracy": GPS_ACCURACY,
+    }
+    if location_id is not None:
+        fields["location_id"] = location_id
+    return fields
+
+
+def _approval_body(
+    request_id: int, inbox_id: int, inbox_message: str, reason: str
+) -> dict[str, Any]:
+    """The approve payload shared by attendance and time-off approvals."""
+    return {
+        "id": str(request_id),
+        "approve": "approve",
+        "reason": reason,
+        "inboxID": str(inbox_id),
+        "inboxMessage": inbox_message,
+        "inboxReimbursementBenefit": [],
+        "submissions": [],
+    }
+
+
+def _is_dict(data: Any) -> bool:
+    return isinstance(data, dict)
+
+
+def _shape(path: str, kind: type) -> Callable[[Any], bool]:
+    """Valid when the value at the dotted path inside `data` has this type."""
+    return lambda data: isinstance(dig(data, path), kind)
+
+
+def _is_iso_date(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    try:
+        return date.fromisoformat(value).isoformat() == value
+    except ValueError:
+        return False
+
+
+def _is_iso_date_list(data: Any) -> bool:
+    return isinstance(data, list) and all(_is_iso_date(value) for value in data)
+
+
+_has_events = _shape("events", list)
+
+
+class MekariClient:
+    def __init__(
+        self,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 20.0,
+    ) -> None:
+        self._http = httpx.Client(
+            follow_redirects=True,
+            timeout=timeout,
+            transport=transport,
+            headers=mekari_constants.request_headers(),
+        )
+        self._closed = False
+
+    def exchange_code(self, code: str, verifier: str) -> MobileToken | None:
+        """Trade an authorization code for the mobile token; None on any failure."""
+        body = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "code_verifier": verifier,
+            "client_id": mekari_constants.client_id(),
+        }
+        try:
+            response = send_request(
+                self._http,
+                "POST",
+                OAUTH2_TOKEN_URL,
+                headers=mekari_constants.token_exchange_headers(),
+                json_body=body,
+            )
+            payload = response.json()
+        except (httpx.HTTPError, ValueError) as error:
+            _exchange_failed(type(error).__name__)
+            return None
+        token = payload.get("access_token") if isinstance(payload, dict) else None
+        if not isinstance(token, str) or not _TOKEN_SHAPE.fullmatch(token):
+            _exchange_failed("invalid_token")
+            return None
+        captured = datetime.now().astimezone()
+        expires_in = payload.get("expires_in")
+        expires_at = (
+            (captured + timedelta(seconds=expires_in)).isoformat()
+            if isinstance(expires_in, int)
+            and not isinstance(expires_in, bool)
+            and expires_in > 0
+            else None
+        )
+        return MobileToken(token, captured.isoformat(), expires_at)
+
+    def logout(self, token: str) -> Result:
+        requested = self._request(token, "POST", LOGOUT_ENDPOINT)
+        if isinstance(requested, Result):
+            return requested
+        response, _payload = requested
+        if not response.is_success:
+            return self._remote_error(response)
+        return Result(True, "logout_succeeded", "Logout successful", response.status_code)
+
+    def employment_info(self, token: str) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            DASHBOARD_USER_ENDPOINT,
+            code="profile_loaded",
+            message="Profile loaded",
+            what="dashboard user",
+        )
+
+    def notification_count(self, token: str) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            INBOX_NOTIFICATION_ENDPOINT,
+            code="notification_count_loaded",
+            message="Notification count loaded",
+            what="notification count",
+        )
+
+    def notification_list(
+        self,
+        token: str,
+        page: int = 1,
+        query: str = "",
+        status: int = 3,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            inbox_endpoint(0),
+            code="notification_list_loaded",
+            message="Notification list loaded",
+            what="notification list",
+            valid=_shape("inbox.data", list),
+            params={"page": page, "query": query, "status": status},
+        )
+
+    def notification_attendance_list(
+        self,
+        token: str,
+        page: int = 1,
+        query: str = "",
+        status: int = 3,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            inbox_endpoint(8),
+            code="notification_attendance_list_loaded",
+            message="Attendance notification list loaded",
+            what="attendance notification list",
+            valid=_shape("inbox.data", list),
+            params={"page": page, "query": query, "status": status},
+        )
+
+    def notification_timeoff_list(
+        self,
+        token: str,
+        page: int = 1,
+        query: str = "",
+        status: int = 3,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            inbox_endpoint(3),
+            code="notification_timeoff_list_loaded",
+            message="Time-off notification list loaded",
+            what="time-off notification list",
+            valid=_shape("inbox.data", list),
+            params={"page": page, "query": query, "status": status},
+        )
+
+    def notification_detail(self, token: str, inbox_id: int) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            notification_detail_endpoint(inbox_id),
+            code="notification_detail_loaded",
+            message="Notification detail loaded",
+            what="notification detail",
+            valid=_shape("inbox", dict),
+        )
+
+    def attendance_approve(
+        self,
+        token: str,
+        inbox_id: int,
+        attendance_id: int,
+        inbox_message: str,
+        reason: str = "",
+    ) -> Result:
+        return self._get_data(
+            token,
+            "POST",
+            ATTENDANCE_APPROVE_ENDPOINT,
+            code="attendance_approved",
+            message="Live attendance request approved",
+            what="attendance approval",
+            json_body=_approval_body(attendance_id, inbox_id, inbox_message, reason),
+        )
+
+    def timeoff_approve(
+        self,
+        token: str,
+        inbox_id: int,
+        timeoff_id: int,
+        inbox_message: str,
+        reason: str = "",
+    ) -> Result:
+        requested = self._request(
+            token,
+            "POST",
+            TIMEOFF_APPROVE_ENDPOINT,
+            json_body=_approval_body(timeoff_id, inbox_id, inbox_message, reason),
+        )
+        if isinstance(requested, Result):
+            return requested
+        response, payload = requested
+        data = payload.get("data") if isinstance(payload, dict) else None
+        # This endpoint can answer HTTP 200 with a failing status in the body.
+        if not isinstance(data, dict) or payload.get("status") != response.status_code:
+            return self._invalid(response, payload, "time-off approval")
+        return Result(
+            True,
+            "timeoff_approved",
+            "Time-off request approved",
+            response.status_code,
+            data,
+        )
+
+    def summary_attendance_clocks(
+        self,
+        token: str,
+        company_id: str,
+        selected_date: str,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            summary_attendance_clocks_endpoint(company_id),
+            code="attendance_summary_list_loaded",
+            message="Attendance summary list loaded",
+            what="attendance summary list",
+            valid=_shape("attendance", list),
+            params={"selected_date": selected_date, "include_on_call_log": False},
+        )
+
+    def summary_attendance_metrics(
+        self,
+        token: str,
+        company_id: str,
+        organisation_user_id: str,
+        selected_date: str,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            summary_attendance_metrics_endpoint(company_id),
+            code="attendance_summary_metrics_loaded",
+            message="Attendance summary metrics loaded",
+            what="attendance summary metrics",
+            valid=_shape("attributes", dict),
+            params={
+                "organisation_user_id": organisation_user_id,
+                "selected_date": selected_date,
+            },
+        )
+
+    def timeoff_types_list(self, token: str) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            TIMEOFF_REQUEST_ENDPOINT,
+            code="timeoff_types_list_loaded",
+            message="Time-off types loaded",
+            what="time-off types",
+            valid=_shape("timeOffPolicies", list),
+        )
+
+    def timeoff_balance(
+        self,
+        token: str,
+        company_id: str,
+        user_id: str,
+        *,
+        date: str = "",
+        keyword: str = "",
+        show_unlimited_balance: bool = False,
+        policy_id: str = "",
+        limited_by_date: str = "",
+        refresh: bool = True,
+        show_special_leave: bool = False,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            timeoff_balance_endpoint(company_id, user_id),
+            code="timeoff_balance_loaded",
+            message="Time-off balance loaded",
+            what="time-off balance",
+            valid=_shape("", list),
+            params={
+                "company_id": company_id,
+                "user_id": user_id,
+                "date": date,
+                "keyword": keyword,
+                "show_unlimited_balance": show_unlimited_balance,
+                "policy_id": policy_id,
+                "limited_by_date": limited_by_date,
+                "refresh": refresh,
+                "show_special_leave": show_special_leave,
+            },
+        )
+
+    def timeoff_delegation_list(
+        self,
+        token: str,
+        page: int = 1,
+        search: str = "",
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            TIMEOFF_DELEGATION_LIST_ENDPOINT,
+            code="timeoff_delegation_list_loaded",
+            message="Time-off delegation list loaded",
+            what="time-off delegation list",
+            valid=_shape("data", list),
+            params={"page": page, "search": search},
+        )
+
+    def timeoff_list(
+        self,
+        token: str,
+        page: int = 1,
+        limit: int = 30,
+        date: str = "",
+        end_date: str = "",
+        status: int = 0,
+        policy_id: str = "",
+        all_period: bool = True,
+        show_metrics: bool = False,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            TIMEOFF_HISTORY_ENDPOINT,
+            code="timeoff_list_loaded",
+            message="Time-off request list loaded",
+            what="time-off request list",
+            valid=_shape("time_off_request.data", list),
+            params={
+                "type": "request",
+                "page": page,
+                "limit": limit,
+                "date": date,
+                "endDate": end_date,
+                "status": status,
+                "policy_id": policy_id,
+                "all_period": all_period,
+                "show_metrics": show_metrics,
+            },
+        )
+
+    def timeoff_detail(self, token: str, request_id: int) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            timeoff_detail_endpoint(request_id),
+            code="timeoff_detail_loaded",
+            message="Time-off request detail loaded",
+            what="time-off detail",
+            valid=_shape("timeoff_detail", dict),
+        )
+
+    def timeoff_request(
+        self,
+        token: str,
+        date: str,
+        policy_id: str,
+        reason: str,
+        *,
+        half_day_after_break: bool = False,
+        half_day_before_break: bool = False,
+        schedule_in: str = "",
+        schedule_out: str = "",
+        delegate_to: str = "",
+        file_path: str | Path | None = None,
+    ) -> Result:
+        use_half_day = half_day_after_break or half_day_before_break
+        half_day_type = "1" if half_day_before_break else "2" if half_day_after_break else "0"
+        fields = {
+            "end_date": date,
+            "hourly_start": "",
+            "policy_id": policy_id,
+            "hourly_duration": "",
+            "hourly_start_date": date,
+            "delegate_to": delegate_to,
+            "schedule_out": schedule_out if use_half_day else "",
+            "useHalfDay": "1" if use_half_day else "0",
+            "is_try_again": "false",
+            "halfDayType": half_day_type,
+            "is_block_leave": "0",
+            "schedule_in": schedule_in if use_half_day else "",
+            "user_id": "",
+            "shift_id": "",
+            "comment": reason,
+            "start_date": date,
+        }
+        attachment: list[tuple[str, tuple[str, bytes]]] = []
+        if file_path is not None:
+            path = Path(file_path)
+            try:
+                attachment = [("file[]", (path.name, path.read_bytes()))]
+            except OSError:
+                return Result(
+                    False,
+                    "invalid_input",
+                    f"Attachment could not be read: {path}",
+                )
+        requested = self._request(
+            token,
+            "POST",
+            TIMEOFF_REQUEST_ENDPOINT,
+            files=[(name, (None, value)) for name, value in fields.items()] + attachment,
+        )
+        if isinstance(requested, Result):
+            return requested
+        response, payload = requested
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if not isinstance(data, dict) or payload.get("status") != response.status_code:
+            return self._invalid(response, payload, "time-off request")
+        return Result(
+            True,
+            "timeoff_request_submitted",
+            "Time-off request submitted",
+            response.status_code,
+            data,
+        )
+
+    def timeoff_cancel(
+        self,
+        token: str,
+        request_id: int,
+        request_type: str = "1002",
+    ) -> Result:
+        requested = self._request(
+            token,
+            "POST",
+            TIMEOFF_CANCEL_REQUEST_ENDPOINT,
+            data={"id": str(request_id), "type": request_type},
+        )
+        if isinstance(requested, Result):
+            return requested
+        response, payload = requested
+        if (
+            not isinstance(payload, dict)
+            or not isinstance(payload.get("message"), str)
+            or payload.get("status") != response.status_code
+        ):
+            return self._invalid(response, payload, "time-off cancellation")
+        return Result(
+            True,
+            "timeoff_request_cancelled",
+            "Time-off request cancelled",
+            response.status_code,
+        )
+
+    def calendar_holiday(
+        self,
+        token: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_HOLIDAY_ENDPOINT,
+            code="calendar_holiday_loaded",
+            message="Calendar holidays loaded",
+            what="calendar holiday",
+            valid=_has_events,
+            params=params,
+        )
+
+    def calendar_timeoff(
+        self,
+        token: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_TIMEOFF_ENDPOINT,
+            code="calendar_timeoff_loaded",
+            message="Calendar time-off loaded",
+            what="calendar timeoff",
+            valid=_has_events,
+            params=params,
+        )
+
+    def calendar_index(
+        self,
+        token: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_INDEX_ENDPOINT,
+            code="calendar_index_loaded",
+            message="Calendar index loaded",
+            what="calendar index",
+            valid=_is_iso_date_list,
+            params=params,
+        )
+
+    def calendar_my_birthday(self, token: str) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_MY_BIRTHDAY_ENDPOINT,
+            code="calendar_my_birthday_loaded",
+            message="My birthday loaded",
+            what="calendar my birthday",
+            valid=_is_iso_date,
+        )
+
+    def calendar_birthday(
+        self,
+        token: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_BIRTHDAY_ENDPOINT,
+            code="calendar_birthday_loaded",
+            message="Calendar birthdays loaded",
+            what="calendar birthday",
+            valid=_has_events,
+            params=params,
+        )
+
+    def calendar_activity(
+        self,
+        token: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Result:
+        return self._get_data(
+            token,
+            "GET",
+            CALENDAR_ACTIVITY_ENDPOINT,
+            code="calendar_activity_loaded",
+            message="Calendar activity loaded",
+            what="calendar activity",
+            valid=_has_events,
+            params=params,
+        )
+
+    def active_schedule(self, token: str, company_id: str) -> ActiveSchedule | Result:
+        requested = self._request(
+            token,
+            "GET",
+            schedule_endpoint(company_id),
+            params={
+                "device_time": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                "show_multiple": "true",
+            },
+        )
+        if isinstance(requested, Result):
+            return requested
+        _response, payload = requested
+        entries = payload.get("data") if isinstance(payload, dict) else None
+        entry = entries[0] if isinstance(entries, list) and entries else None
+        office_hour_id = entry.get("current_shift_id") if isinstance(entry, dict) else None
+        setting_id = (
+            entry.get("attendance_office_hour_setting_id") if isinstance(entry, dict) else None
+        )
+        if not str(office_hour_id or "").strip() or not str(setting_id or "").strip():
+            return Result(False, "schedule_unavailable", "No active schedule found")
+        return ActiveSchedule(
+            schedule_date=str(entry.get("current_shift_date") or date.today().isoformat()),
+            office_hour_id=str(office_hour_id),
+            office_hour_setting_id=str(setting_id),
+            clock_type=str(entry.get("attendance_clock_type") or "attendance"),
+        )
+
+    def clock(
+        self,
+        token: str,
+        company_id: str,
+        event_type: str,
+        notes: str,
+        selfie: Path | None = None,
+        *,
+        schedule: ActiveSchedule,
+        latitude: str,
+        longitude: str,
+        location_id: str | None = None,
+    ) -> Result:
+        parts: list[tuple[str, tuple[Any, Any] | tuple[str, bytes, str]]] = [
+            (name, (None, value))
+            for name, value in build_clock_fields(
+                schedule,
+                event_type,
+                notes,
+                latitude=latitude,
+                longitude=longitude,
+                location_id=location_id,
+            ).items()
+        ]
+        if selfie is not None:
+            parts.append(
+                ("selfie_photo", (selfie.name, selfie.read_bytes(), "image/jpeg"))
+            )
+        requested = self._request(token, "POST", clock_endpoint(company_id), files=parts)
+        if isinstance(requested, Result):
+            return requested
+        response, payload = requested
+        if not response.is_success:
+            return self._remote_error(response, payload)
+        return Result(True, "clock_succeeded", "Clock recorded", response.status_code, payload)
+
+    def _request(
+        self,
+        token: str,
+        method: str,
+        url: str,
+        **request: Any,
+    ) -> tuple[httpx.Response, Any] | Result:
+        """Send one authorized request; failures become Results.
+
+        send_request already logs every failed request (network error or
+        HTTP status), so nothing is logged here.
+        """
+        try:
+            response = send_request(
+                self._http,
+                method,
+                url,
+                headers=self._auth_headers(token),
+                **request,
+            )
+        except httpx.RequestError:
+            return Result(False, "network_error", "Could not reach Mekari")
+        except httpx.HTTPStatusError as error:
+            if error.response.status_code == 401:
+                return self._expired()
+            return self._remote_error(error.response)
+        return response, self._response_data(response)
+
+    def _get_data(
+        self,
+        token: str,
+        method: str,
+        url: str,
+        *,
+        code: str,
+        message: str,
+        what: str,
+        valid: Callable[[Any], bool] = _is_dict,
+        **request: Any,
+    ) -> Result:
+        """Return the payload's `data` when `valid` accepts it."""
+        requested = self._request(token, method, url, **request)
+        if isinstance(requested, Result):
+            return requested
+        response, payload = requested
+        data = payload.get("data") if isinstance(payload, dict) else None
+        if not valid(data):
+            return self._invalid(response, payload, what)
+        return Result(True, code, message, response.status_code, data)
+
+    @staticmethod
+    def _invalid(response: httpx.Response, payload: Any, what: str) -> Result:
+        return Result(
+            False,
+            "remote_error",
+            f"Mekari returned an invalid {what} response",
+            response.status_code,
+            payload,
+        )
+
+    @staticmethod
+    def _auth_headers(token: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/json, text/plain, */*",
+        }
+
+    def close(self) -> None:
+        if not self._closed:
+            self._http.close()
+            self._closed = True
+
+    def __enter__(self) -> MekariClient:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> None:
+        self.close()
+
+    @staticmethod
+    def _expired() -> Result:
+        return Result(
+            False,
+            "mobile_token_expired",
+            "Mobile token expired; run `tlnt login`",
+        )
+
+    def _remote_error(self, response: httpx.Response, data: Any = None) -> Result:
+        safe_data = self._response_data(response) if data is None else data
+        message = f"Mekari returned HTTP {response.status_code}"
+        if isinstance(safe_data, dict) and safe_data.get("message"):
+            message = str(safe_data["message"])
+        return Result(False, "remote_error", message, response.status_code, safe_data)
+
+    @classmethod
+    def _response_data(cls, response: httpx.Response) -> Any:
+        if not response.content:
+            return None
+        try:
+            return cls._sanitize(response.json())
+        except ValueError:
+            return None
+
+    @classmethod
+    def _sanitize(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            return {
+                key: cls._sanitize(item)
+                for key, item in value.items()
+                if not any(part in str(key).casefold() for part in _SENSITIVE_KEYS)
+            }
+        if isinstance(value, list):
+            return [cls._sanitize(item) for item in value]
+        return value
+
+
+def _exchange_failed(error_type: str) -> None:
+    _log.bind(
+        event="failure",
+        operation="exchange_code",
+        error_type=error_type,
+    ).warning("operation failed")