tlnt-cli 1.5.1__py3-none-any.whl

tlnt/core/clients/mekari/constants.py

@@ -0,0 +1,174 @@
+"""Captured Mekari mobile endpoints and request constants."""
+
+from tlnt.core.config import get_setting
+from tlnt.core.user_agent import random_device_headers
+
+# Mekari domain constants
+MEKARI_DOMAIN = "mekari.com"
+TALENTA_DOMAIN = "talenta.co"
+
+# Mekari URLs
+MEKARI_AUTH_URL = f"https://account.{MEKARI_DOMAIN}"
+MEKARI_API_URL = f"https://api.{MEKARI_DOMAIN}"
+DASHBOARD_TALENTA_URL = f"https://hr.{TALENTA_DOMAIN}/employee/dashboard"
+
+# Mekari OAuth constants
+OAUTH_SCOPE = "sso:profile"
+
+# Mekari Subdomain URLs
+OAUTH_AUTHORIZE_URL = f"{MEKARI_AUTH_URL}/auth"
+OAUTH2_TOKEN_URL = f"{MEKARI_API_URL}/oauth2/token"
+TOKEN_REDIRECT_URL = f"{MEKARI_API_URL}/mobile-platform-oauth2-redirection"
+
+# Mekari GPS constants
+GPS_ACCURACY = "5.0"
+
+# Mekari API endpoints
+DASHBOARD_USER_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/dashboard/user"
+)
+LOGOUT_ENDPOINT = f"{MEKARI_API_URL}/internal/talenta-mobile/v1/logout"
+INBOX_NOTIFICATION_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/inbox-notification"
+)
+INBOX_ENDPOINT = f"{MEKARI_API_URL}/internal/talenta-mobile/v1/inbox"
+INBOX_DETAIL_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/inbox-detail"
+)
+ATTENDANCE_APPROVE_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/"
+    "approval-request/live-attendance"
+)
+TIMEOFF_APPROVE_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/"
+    "approval-request/timeoff"
+)
+TIMEOFF_REQUEST_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/time-off-request"
+)
+TIMEOFF_CANCEL_REQUEST_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/cancel-request"
+)
+TIMEOFF_DELEGATION_LIST_ENDPOINT = f"{TIMEOFF_REQUEST_ENDPOINT}/delegation-list"
+TIMEOFF_HISTORY_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/history-request/timeoff"
+)
+
+
+
+CALENDAR_HOLIDAY_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/calendar/holiday"
+)
+CALENDAR_TIMEOFF_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/calendar/timeoff"
+)
+CALENDAR_INDEX_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v2/calendar/index"
+)
+CALENDAR_MY_BIRTHDAY_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v2/calendar/birthday"
+)
+CALENDAR_BIRTHDAY_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/calendar/birthday"
+)
+CALENDAR_ACTIVITY_ENDPOINT = (
+    f"{MEKARI_API_URL}/internal/talenta-mobile/v1/calendar/activity"
+)
+
+def inbox_endpoint(inbox_type: int) -> str:
+    return f"{INBOX_ENDPOINT}/{inbox_type}"
+
+
+def notification_detail_endpoint(inbox_id: int) -> str:
+    return f"{INBOX_DETAIL_ENDPOINT}/{inbox_id}"
+
+
+def schedule_endpoint(company_id: str) -> str:
+    return (
+        f"{MEKARI_API_URL}/internal/talenta-mobile/v1/attendance/companies/"
+        f"{company_id}/attendance_schedules/active"
+    )
+
+def clock_endpoint(company_id: str) -> str:
+    return (
+        f"{MEKARI_API_URL}/internal/talenta-mobile/v3/attendance/organisations/"
+        f"{company_id}/attendance_clocks"
+    )
+
+
+
+def summary_attendance_clocks_endpoint(company_id: str) -> str:
+    return (
+        f"{MEKARI_API_URL}/internal/talenta-mobile/v2/attendance/"
+        f"organisations/{company_id}/summary_attendance_clocks"
+    )
+
+
+def summary_attendance_metrics_endpoint(company_id: str) -> str:
+    return f"{summary_attendance_clocks_endpoint(company_id)}/metrics_agg"
+
+
+def timeoff_balance_endpoint(company_id: str, user_id: str) -> str:
+    return (
+        f"{MEKARI_API_URL}/internal/talenta-time-off/v1/companies/"
+        f"{company_id}/users/{user_id}/balances"
+    )
+
+
+def timeoff_detail_endpoint(request_id: int) -> str:
+    return f"{TIMEOFF_HISTORY_ENDPOINT}/{request_id}"
+
+# Headers
+DEFAULT_USER_AGENT_MOBILE = "Dart/3.6 (dart:io)"
+HEADER_ACCEPT_LANGUAGE = "en-EN"
+# Fallback when no config sets app_version; .github/workflows/app-version.yml bumps it.
+DEFAULT_APP_VERSION = "2.125.0"
+HEADER_X_PORTAL_VERSION = "2"
+HEADER_X_TL_LEGACY_RESPONSE = "true"
+
+
+# Settings are read when used, so a --config chosen after import still applies.
+def client_id() -> str:
+    return get_setting("TALENTA_CLIENT_ID", "client_id", "")
+
+
+def app_version() -> str:
+    return get_setting("TALENTA_APP_VERSION", "app_version", DEFAULT_APP_VERSION)
+
+
+def user_agent_mobile() -> str:
+    return get_setting(
+        "TALENTA_USER_AGENT_MOBILE", "user_agent_mobile", DEFAULT_USER_AGENT_MOBILE
+    )
+
+
+def request_headers() -> dict[str, str]:
+    return {
+        **random_device_headers(),
+        "Accept-Language": HEADER_ACCEPT_LANGUAGE,
+        "X-App-Version": app_version(),
+        "X-Portal-Version": HEADER_X_PORTAL_VERSION,
+        "X-TL-Legacy-Response": HEADER_X_TL_LEGACY_RESPONSE,
+    }
+
+
+def token_exchange_headers() -> dict[str, str]:
+    return {
+        **request_headers(),
+        "User-Agent": user_agent_mobile(),
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+# Mekari Static asset suffixes
+STATIC_ASSET_SUFFIXES = (
+    ".css",
+    ".js",
+    ".svg",
+    ".png",
+    ".ico",
+    ".ttf",
+    ".woff",
+    ".woff2",
+)

tlnt/core/config.py

@@ -0,0 +1,53 @@
+"""Runtime configuration for withheld Mekari identifiers.
+
+Live values (the mobile OAuth client id) are NOT shipped in source. They
+come from the TALENTA_* environment variables or a local config.json kept
+outside the repo in the platformdirs user config directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+
+_config_path_override: Path | None = None
+
+
+def _config_path() -> Path:
+    if _config_path_override is not None:
+        return _config_path_override
+    return user_config_path("tlnt", appauthor=False) / "config.json"
+
+
+def get_config_path() -> Path:
+    """Return the selected config path or the default OS config path."""
+    return _config_path()
+
+
+def set_config_path(path: Path | None) -> None:
+    """Select the config file for this process."""
+    global _config_path_override
+    _config_path_override = path.expanduser() if path is not None else None
+    _file_config.cache_clear()
+
+
+@lru_cache(maxsize=1)  # ponytail: cached per-process; config.json edits need a fresh run
+def _file_config() -> dict[str, str]:
+    try:
+        raw = json.loads(_config_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return raw if isinstance(raw, dict) else {}
+
+
+def get_setting(env_var: str, config_key: str, default: str = "") -> str:
+    value = os.environ.get(env_var)
+    if value:
+        return value
+    file_value = _file_config().get(config_key)
+    return file_value if isinstance(file_value, str) and file_value else default

tlnt/core/http_client.py

@@ -0,0 +1,110 @@
+"""Shared HTTPX request behavior."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from tlnt.core.logs import logger
+
+
+_RETRYABLE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+_RETRY_DELAY_SECONDS = 0.5
+_MAX_ATTEMPTS = 2
+_log = logger.bind(component="http")
+
+
+def send_request(
+    client: httpx.Client,
+    method: str,
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    params: Mapping[str, Any] | None = None,
+    json_body: Any = None,
+    data: Any = None,
+    files: Any = None,
+) -> httpx.Response:
+    """Send one HTTPX request with safe logging and retries."""
+    normalized_method = method.upper()
+    safe_url = url.split("?", 1)[0]
+    retryable_method = normalized_method in _RETRYABLE_METHODS
+
+    for attempt in range(_MAX_ATTEMPTS):
+        started_at = time.monotonic()
+        _log.bind(
+            event="http_request",
+            method=normalized_method,
+            path=safe_url,
+            attempt=attempt + 1,
+        ).debug("request started")
+        try:
+            response = client.request(
+                method=normalized_method,
+                url=url,
+                headers=headers,
+                params=params,
+                json=json_body,
+                data=data,
+                files=files,
+            )
+        except httpx.RequestError as error:
+            if retryable_method and attempt == 0:
+                _log.bind(
+                    event="http_retry",
+                    method=normalized_method,
+                    path=safe_url,
+                    attempt=attempt + 1,
+                    error_type=type(error).__name__,
+                ).debug("retrying request")
+                time.sleep(_RETRY_DELAY_SECONDS)
+                continue
+            _log.bind(
+                event="failure",
+                method=normalized_method,
+                path=safe_url,
+                attempt=attempt + 1,
+                error_type=type(error).__name__,
+            ).warning("request failed")
+            raise
+
+        duration_ms = round((time.monotonic() - started_at) * 1000, 2)
+        _log.bind(
+            event="http_response",
+            method=normalized_method,
+            path=safe_url,
+            attempt=attempt + 1,
+            status=response.status_code,
+            duration_ms=duration_ms,
+        ).debug("response received")
+
+        if (
+            retryable_method
+            and attempt == 0
+            and (response.status_code == 429 or response.status_code >= 500)
+        ):
+            _log.bind(
+                event="http_retry",
+                method=normalized_method,
+                path=safe_url,
+                attempt=attempt + 1,
+                status=response.status_code,
+            ).debug("retrying response")
+            time.sleep(_RETRY_DELAY_SECONDS)
+            continue
+
+        if response.is_error:
+            _log.bind(
+                event="failure",
+                method=normalized_method,
+                path=safe_url,
+                attempt=attempt + 1,
+                status=response.status_code,
+            ).warning("request failed")
+            response.raise_for_status()
+        return response
+
+    raise RuntimeError("HTTP request attempt loop exhausted unexpectedly")

tlnt/core/logs.py

@@ -0,0 +1,34 @@
+"""Shared structured logging configuration."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+from loguru import logger
+
+
+def _format_record(record: dict[str, Any]) -> str:
+    timestamp: datetime = record["time"].astimezone(timezone.utc)
+    fields = " ".join(
+        f"{key}={value}" for key, value in record["extra"].items()
+    )
+    return (
+        f"{timestamp.isoformat(timespec='milliseconds')} | "
+        f"{record['level'].name:<8} | {fields} | {record['message']}"
+    ) + "\n"
+
+
+def configure_logging(verbose: bool = False) -> None:
+    """Configure application diagnostics for the current process."""
+    logger.remove()
+    logger.configure(extra={"component": "tlnt", "event": "-"})
+
+    logger.add(
+        sys.stderr,
+        level="DEBUG" if verbose else "INFO",
+        format=_format_record,
+        backtrace=False,
+        diagnose=False,
+    )

tlnt/core/models.py

@@ -0,0 +1,84 @@
+"""Shared domain values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    email: str
+    talenta_user_id: str
+    company_id: str
+    company_name: str | None = None
+
+
+@dataclass(frozen=True)
+class MobileToken:
+    access_token: str
+    captured_at: str
+    expires_at: str | None = None
+
+    def is_expired(self, now: datetime) -> bool:
+        """True only for a parseable, timezone-aware expiry at or before now."""
+        if self.expires_at is None:
+            return False
+        try:
+            expires = datetime.fromisoformat(self.expires_at)
+        except ValueError:
+            return False
+        return expires.tzinfo is not None and expires <= now
+
+
+@dataclass(frozen=True)
+class ActiveSchedule:
+    schedule_date: str
+    office_hour_id: str
+    office_hour_setting_id: str
+    clock_type: str
+
+
+@dataclass(frozen=True)
+class SessionState:
+    version: int
+    saved_at: str
+    web_storage: dict[str, Any]
+    profile: Profile | None
+    mobile: MobileToken | None = None
+    credential_email: str | None = None
+    keyring_ref: str | None = None
+
+
+@dataclass(frozen=True)
+class Result:
+    ok: bool
+    code: str
+    message: str
+    status_code: int | None = None
+    data: Any = None
+
+    def as_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "ok": self.ok,
+            "code": self.code,
+            "message": self.message,
+        }
+        if self.status_code is not None:
+            result["status_code"] = self.status_code
+        if self.data is not None:
+            result["data"] = self.data
+        return result
+
+
+def dig(value: Any, path: str) -> Any:
+    """Dotted-key lookup; an empty path returns value unchanged."""
+    if not path:
+        return value
+    for part in path.split("."):
+        if not isinstance(value, dict):
+            return None
+        value = value.get(part)
+    return value

tlnt/core/play_store.py

@@ -0,0 +1,85 @@
+"""Latest Talenta app version from Google Play, cached for 24 hours."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from collections.abc import Callable
+
+import httpx
+from platformdirs import user_cache_path
+
+from tlnt.core import config
+
+PLAY_URL = "https://play.google.com/store/apps/details?id=co.talenta&hl=id"
+_VERSION_RE = re.compile(r'\[\[\["(\d+\.\d+\.\d+)"\]\]')
+_FETCH_TIMEOUT_SECONDS = 3
+_CACHE_TTL_SECONDS = 24 * 60 * 60
+
+
+def parse_play_version(html: str) -> str | None:
+    match = _VERSION_RE.search(html)
+    return match.group(1) if match else None
+
+
+def fetch_play_version() -> str | None:
+    try:
+        response = httpx.get(PLAY_URL, timeout=_FETCH_TIMEOUT_SECONDS, follow_redirects=True)
+        response.raise_for_status()
+    except httpx.HTTPError:
+        return None
+    return parse_play_version(response.text)
+
+
+def _cache_path(name: str):
+    return user_cache_path("tlnt", appauthor=False) / name
+
+
+def cached_version(
+    cache_name: str,
+    fetch: Callable[[], str | None],
+    now: float | None = None,
+) -> str | None:
+    """Return a version cached for 24 hours in the user cache dir, else fetch it.
+
+    A failed lookup is cached too, so a blocked or slow site costs one
+    timeout a day instead of one per command.
+    """
+    now = time.time() if now is None else now
+    path = _cache_path(cache_name)
+    try:
+        cached = json.loads(path.read_text(encoding="utf-8"))
+        version = cached["version"]
+        if (version is None or isinstance(version, str)) and (
+            now - float(cached["checked_at"]) < _CACHE_TTL_SECONDS
+        ):
+            return version
+    except (OSError, ValueError, KeyError, TypeError):
+        pass  # missing, corrupt, or stale cache: fall through to a fresh fetch
+
+    version = fetch() or None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({"version": version, "checked_at": now}),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass  # cache is an optimisation; never fail a command over it
+    return version
+
+
+def latest_play_version(now: float | None = None) -> str | None:
+    return cached_version("play_version.json", fetch_play_version, now)
+
+
+def app_version_warning(current: str) -> str | None:
+    latest = latest_play_version()
+    if not latest or latest == current:
+        return None
+    return (
+        f"⚠️ Talenta app v{current} is configured, but v{latest} is on Google Play. "
+        f'Set "app_version" to "{latest}" in {config.get_config_path()} '
+        "(or TALENTA_APP_VERSION), then run `tlnt logout` and `tlnt login`."
+    )

tlnt/core/services/__init__.py

@@ -0,0 +1,46 @@
+"""Shared service helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import TypeVar
+
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.session import SessionStore, mobile_token
+
+T = TypeVar("T")
+
+
+@contextmanager
+def owned_client(client: MekariClient | None = None) -> Iterator[MekariClient]:
+    """Yield the given client untouched, or a new one that is closed on exit."""
+    if client is not None:
+        yield client
+        return
+    with MekariClient() as created:
+        yield created
+
+
+def with_client(
+    call: Callable[[MekariClient, str], T],
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> T | Result:
+    """Run call(client, token); a missing token returns its Result, no client made."""
+    token = mobile_token(store)
+    if isinstance(token, Result):
+        return token
+    with owned_client(client) as active:
+        return call(active, token)
+
+
+def positive_id(value: object) -> str | None:
+    """A Mekari id as a positive ASCII decimal string, else None."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, float) and value.is_integer():
+        value = int(value)
+    text = str(value).strip()
+    return text if text.isascii() and text.isdecimal() and text.strip("0") else None