tlnt-cli 1.5.1__py3-none-any.whl

tlnt/core/services/timeoff.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.services import positive_id, with_client
+from tlnt.core.session import SessionStore
+
+
+def timeoff_types_list(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.timeoff_types_list(token), store, client)
+
+
+def timeoff_balance(
+    date: str = "",
+    keyword: str = "",
+    show_unlimited_balance: bool = False,
+    policy_id: str = "",
+    limited_by_date: str = "",
+    refresh: bool = True,
+    show_special_leave: bool = False,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    def balance(c: MekariClient, token: str) -> Result:
+        profile = c.employment_info(token)
+        if not profile.ok:
+            return profile
+        data = profile.data if isinstance(profile.data, dict) else {}
+        company_id = positive_id(data.get("company_id"))
+        user_id = positive_id(data.get("id"))
+        if company_id is None or user_id is None:
+            return Result(
+                False,
+                "remote_error",
+                "Mekari profile is missing or has invalid time-off balance identifiers",
+            )
+        return c.timeoff_balance(
+            token,
+            company_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,
+        )
+
+    return with_client(balance, store, client)
+
+
+def timeoff_delegation_list(
+    page: int = 1,
+    search: str = "",
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.timeoff_delegation_list(token, page, search), store, client
+    )
+
+
+def timeoff_list(
+    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,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.timeoff_list(
+            token,
+            page,
+            limit,
+            date,
+            end_date,
+            status,
+            policy_id,
+            all_period,
+            show_metrics,
+        ),
+        store,
+        client,
+    )
+
+
+def timeoff_detail(
+    request_id: int,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.timeoff_detail(token, request_id), store, client)
+
+
+def timeoff_request(
+    date: str,
+    policy_id: str,
+    reason: str,
+    *,
+    half_day_after_break: bool = False,
+    half_day_before_break: bool = False,
+    delegate_to: str = "",
+    file_path: str | None = None,
+    schedule_in: str = "",
+    schedule_out: str = "",
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.timeoff_request(
+            token,
+            date,
+            policy_id,
+            reason,
+            half_day_after_break=half_day_after_break,
+            half_day_before_break=half_day_before_break,
+            delegate_to=delegate_to,
+            file_path=file_path,
+            schedule_in=schedule_in,
+            schedule_out=schedule_out,
+        ),
+        store,
+        client,
+    )
+
+
+def timeoff_cancel(
+    request_id: int,
+    request_type: str = "1002",
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.timeoff_cancel(token, request_id, request_type),
+        store,
+        client,
+    )

tlnt/core/session.py

@@ -0,0 +1,189 @@
+"""Secure session persistence and access."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+import keyring
+from keyring.errors import PasswordDeleteError
+from platformdirs import user_data_path
+
+from tlnt.core.config import get_setting
+from tlnt.core.models import MobileToken, Profile, Result, SessionState
+
+KEYRING_SERVICE = "tlnt"
+
+
+class SessionMissing(FileNotFoundError):
+    pass
+
+
+class InvalidSession(ValueError):
+    pass
+
+
+class SessionStore:
+    def __init__(self, path: Path | None = None) -> None:
+        configured_path = get_setting(
+            "TALENTA_SESSION_PATH",
+            "session_path",
+            "",
+        )
+        self.path = (
+            path
+            if path is not None
+            else (
+                Path(configured_path).expanduser()
+                if configured_path
+                else user_data_path("tlnt", appauthor=False) / "session.json"
+            )
+        )
+
+    def load(self) -> SessionState:
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError as error:
+            raise SessionMissing("no saved session; run `tlnt login`") from error
+        except (json.JSONDecodeError, OSError) as error:
+            raise InvalidSession("session file is unreadable") from error
+        return self._parse(payload)
+
+    def save(self, session: SessionState) -> None:
+        parent = self.path.parent
+        # Tighten only a folder tlnt creates or its own data folder, never a
+        # shared one like /tmp or the home folder.
+        owned = not parent.exists() or parent == user_data_path("tlnt", appauthor=False)
+        parent.mkdir(parents=True, exist_ok=True)
+        if owned:
+            parent.chmod(0o700)
+        temporary_path: Path | None = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                "w",
+                encoding="utf-8",
+                dir=self.path.parent,
+                delete=False,
+            ) as temporary:
+                temporary_path = Path(temporary.name)
+                temporary_path.chmod(0o600)
+                json.dump(
+                    asdict(session),
+                    temporary,
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                )
+                temporary.flush()
+                os.fsync(temporary.fileno())
+            os.replace(temporary_path, self.path)
+            self.path.chmod(0o600)
+        finally:
+            if temporary_path is not None and temporary_path.exists():
+                temporary_path.unlink()
+
+    def delete(self) -> None:
+        self.path.unlink(missing_ok=True)
+
+    @staticmethod
+    def delete_password(keyring_ref: str) -> None:
+        try:
+            keyring.delete_password(KEYRING_SERVICE, keyring_ref)
+        except PasswordDeleteError:
+            pass
+
+    @staticmethod
+    def _parse(payload: Any) -> SessionState:
+        if not isinstance(payload, dict) or payload.get("version") != 1:
+            raise InvalidSession("unsupported session version")
+
+        profile = payload.get("profile")
+        mobile = payload.get("mobile")
+        web_storage = payload.get("web_storage")
+        saved_at = payload.get("saved_at")
+        if (
+            (profile is not None and not isinstance(profile, dict))
+            or (mobile is not None and not isinstance(mobile, dict))
+            or not isinstance(web_storage, dict)
+            or not isinstance(saved_at, str)
+        ):
+            raise InvalidSession("session file has an invalid shape")
+
+        try:
+            return SessionState(
+                version=1,
+                saved_at=saved_at,
+                web_storage=web_storage,
+                profile=(
+                    Profile(
+                        name=str(profile["name"]),
+                        email=str(profile["email"]),
+                        talenta_user_id=str(profile["talenta_user_id"]),
+                        company_id=str(profile["company_id"]),
+                        company_name=(
+                            str(profile["company_name"])
+                            if profile.get("company_name") is not None
+                            else None
+                        ),
+                    )
+                    if profile is not None
+                    else None
+                ),
+            mobile=(
+                MobileToken(
+                    access_token=str(mobile["access_token"]),
+                    captured_at=str(mobile["captured_at"]),
+                    expires_at=(
+                        str(mobile["expires_at"])
+                        if mobile.get("expires_at") is not None
+                        else None
+                    ),
+                )
+                if mobile is not None
+                else None
+            ),
+            credential_email=(
+                str(payload["credential_email"])
+                if payload.get("credential_email") is not None
+                else None
+            ),
+            keyring_ref=(
+                str(payload["keyring_ref"])
+                if payload.get("keyring_ref") is not None
+                else None
+            ),
+        )
+        except KeyError as error:
+            raise InvalidSession("session profile is incomplete") from error
+
+
+def load_session(store: SessionStore | None = None) -> SessionState | Result:
+    try:
+        return (store or SessionStore()).load()
+    except SessionMissing as error:
+        return Result(False, "session_missing", str(error))
+    except InvalidSession as error:
+        return Result(False, "session_invalid", str(error))
+
+
+def mobile_token(
+    store: SessionStore | None = None,
+    session: SessionState | None = None,
+) -> str | Result:
+    env_token = os.environ.get("TALENTA_BEARER")
+    if env_token:
+        return env_token
+
+    loaded = session or load_session(store)
+    if isinstance(loaded, Result):
+        return loaded
+    if loaded.mobile is not None:
+        return loaded.mobile.access_token
+    return Result(
+        False,
+        "mobile_token_missing",
+        "No mobile token; run `tlnt login` or set TALENTA_BEARER",
+    )

tlnt/core/user_agent.py

@@ -0,0 +1,71 @@
+"""Random Android device headers, fixed for the life of the process."""
+
+from __future__ import annotations
+
+import random
+import secrets
+from functools import lru_cache
+
+
+_ANDROID_VERSIONS = ("10.0", "11.0", "12.0", "13.0", "14.0", "15.0", "16.0")
+_ANDROID_DEVICES = (
+    "SM-G960F",
+    "Pixel 5",
+    "SM-A505F",
+    "Pixel 4a",
+    "Pixel 6 Pro",
+    "SM-N975F",
+    "SM-G973F",
+    "Pixel 3",
+    "SM-G980F",
+    "Pixel 5a",
+    "SM-G998B",
+    "Pixel 4",
+    "SM-G991B",
+    "SM-G996B",
+    "SM-F711B",
+    "SM-F916B",
+    "SM-G781B",
+    "SM-N986B",
+    "SM-N981B",
+    "Pixel 2",
+    "Pixel 2 XL",
+    "Pixel 3 XL",
+    "Pixel 4 XL",
+    "Pixel 5 XL",
+    "Pixel 6",
+    "Pixel 6 XL",
+    "Pixel 6a",
+    "Pixel 7",
+    "Pixel 7 Pro",
+    "OnePlus 8",
+    "OnePlus 8 Pro",
+    "OnePlus 9",
+)
+
+
+@lru_cache(maxsize=1)
+def random_device_headers() -> dict[str, str]:
+    """Headers for one random Android device; every call in a process agrees."""
+    device_model = random.choice(_ANDROID_DEVICES)
+    os_version = random.choice(_ANDROID_VERSIONS)
+    chrome_version = ".".join(
+        str(part)
+        for part in (
+            random.randrange(125, 138),
+            random.randrange(10),
+            random.randrange(1000, 10000),
+            random.randrange(100),
+        )
+    )
+    return {
+        "User-Agent": (
+            f"Mozilla/5.0 (Linux; Android {os_version}; {device_model}) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{chrome_version} Mobile Safari/537.36"
+        ),
+        "X-Device-Fingerprint": secrets.token_hex(32),
+        "X-Device-ID": secrets.token_hex(8),
+        "X-Device-Model": device_model,
+        "X-OS-Version": os_version,
+    }

tlnt/mcp/main.py

@@ -0,0 +1,176 @@
+"""Read-only MCP adapter."""
+
+from __future__ import annotations
+
+import errno
+import time
+from collections.abc import Callable
+from importlib import metadata
+from typing import Any
+
+from mcp.server import MCPServer
+from mcp.types import ToolAnnotations
+
+from tlnt import DISTRIBUTION
+from tlnt.core.logs import logger
+from tlnt.core.models import Result
+from tlnt.core.services.attendance import (
+    preview_clock,
+    validate_coordinates,
+    validate_notes,
+)
+from tlnt.core.services.profile import profile
+from tlnt.core.services.status import status
+
+_log = logger.bind(component="mcp")
+
+
+def _read_only(*, open_world: bool) -> ToolAnnotations:
+    return ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=open_world,
+    )
+
+
+def _call_tool(
+    name: str,
+    action: Callable[..., Result],
+    *args: Any,
+    argument_keys: tuple[str, ...] = (),
+    **kwargs: Any,
+) -> dict[str, Any]:
+    started_at = time.monotonic()
+    _log.bind(
+        event="tool_started",
+        tool=name,
+        argument_keys=argument_keys,
+    ).info("tool started")
+    try:
+        result = action(*args, **kwargs)
+    except Exception as error:
+        _log.bind(
+            event="tool_failed",
+            tool=name,
+            error_type=type(error).__name__,
+            duration_ms=round((time.monotonic() - started_at) * 1000, 2),
+        ).warning("tool failed")
+        raise
+
+    finished_log = _log.bind(
+        event="tool_finished",
+        tool=name,
+        ok=result.ok,
+        code=result.code,
+        duration_ms=round((time.monotonic() - started_at) * 1000, 2),
+        data_type=type(result.data).__name__,
+        data_keys=(
+            tuple(sorted(str(key) for key in result.data))
+            if isinstance(result.data, dict)
+            else ()
+        ),
+    )
+    if result.status_code is not None:
+        finished_log = finished_log.bind(status_code=result.status_code)
+    finished_log.info("tool finished")
+    return result.as_dict()
+
+
+def create_server(
+    *,
+    status_action: Callable[[], Result] = status,
+    profile_action: Callable[[], Result] = profile,
+    preview_action: Callable[..., Result] = preview_clock,
+) -> MCPServer:
+    server = MCPServer(
+        "tlnt",
+        version=metadata.version(DISTRIBUTION),
+        instructions="Read-only Talenta session, profile, and clock-in preview tools.",
+    )
+
+    @server.tool(annotations=_read_only(open_world=False))
+    def get_session_status() -> dict[str, Any]:
+        """Check whether a saved, unexpired Talenta mobile token is available."""
+        return _call_tool(
+            "get_session_status",
+            status_action,
+            argument_keys=(),
+        )
+
+    @server.tool(annotations=_read_only(open_world=True))
+    def get_profile() -> dict[str, Any]:
+        """Read Talenta employment information with the mobile token."""
+        return _call_tool(
+            "get_profile",
+            profile_action,
+            argument_keys=(),
+        )
+
+    @server.tool(annotations=_read_only(open_world=True))
+    def preview_clockin(
+        event_type: str,
+        latitude: str,
+        longitude: str,
+        notes: str = "",
+        location_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Preview a mobile attendance request without submitting it."""
+        validation = validate_notes(notes) or validate_coordinates(latitude, longitude)
+        if validation is not None:
+            return validation.as_dict()
+        return _call_tool(
+            "preview_clockin",
+            preview_action,
+            event_type,
+            notes,
+            argument_keys=(
+                "event_type",
+                "latitude",
+                "longitude",
+                "notes",
+                "location_id",
+            ),
+            latitude=latitude,
+            longitude=longitude,
+            location_id=location_id,
+        )
+
+    return server
+
+
+def _is_expected_stdio_shutdown(error: BaseException) -> bool:
+    if isinstance(error, OSError):
+        return error.errno == errno.EIO
+
+    nested = getattr(error, "exceptions", ())
+    return isinstance(nested, tuple) and bool(nested) and all(
+        _is_expected_stdio_shutdown(item) for item in nested
+    )
+
+
+def _log_server_stopped(reason: str) -> None:
+    _log.bind(
+        event="server_stopped",
+        transport="stdio",
+        reason=reason,
+    ).info("MCP server stopped")
+
+
+def run_server() -> None:
+    _log.bind(
+        event="server_starting",
+        transport="stdio",
+    ).info("MCP server starting")
+    try:
+        create_server().run()
+    except KeyboardInterrupt:
+        _log_server_stopped("interrupt")
+        return
+    except Exception as error:
+        if _is_expected_stdio_shutdown(error):
+            _log_server_stopped("interrupt")
+            return
+        _log.exception("unhandled MCP server error")
+        raise
+    _log_server_stopped("completed")