tlnt-cli 1.5.1__py3-none-any.whl

tlnt/core/services/attendance.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from tlnt.core.clients.mekari.client import MekariClient, build_clock_fields
+from tlnt.core.clients.mekari.constants import clock_endpoint
+from tlnt.core.models import ActiveSchedule, Result, SessionState
+from tlnt.core.services import owned_client, positive_id
+from tlnt.core.session import SessionStore, load_session, mobile_token
+
+
+MAX_NOTE_LENGTH = 500
+
+
+def validate_notes(notes: str) -> Result | None:
+    if len(notes) > MAX_NOTE_LENGTH:
+        return Result(
+            False,
+            "invalid_input",
+            f"notes must be at most {MAX_NOTE_LENGTH} characters",
+        )
+    return None
+
+
+def _within(value: str, limit: float) -> bool:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return False
+    return -limit <= number <= limit  # False for nan
+
+
+def validate_coordinates(latitude: str, longitude: str) -> Result | None:
+    """Reject impossible coordinates; accepted strings are sent as typed."""
+    if not _within(latitude, 90):
+        return Result(False, "invalid_input", "latitude must be a number from -90 to 90")
+    if not _within(longitude, 180):
+        return Result(
+            False, "invalid_input", "longitude must be a number from -180 to 180"
+        )
+    return None
+
+
+def _resolve_attendance(
+    store: SessionStore | None,
+    client: MekariClient,
+) -> tuple[SessionState, str, str, dict | None] | Result:
+    session = load_session(store)
+    if isinstance(session, Result):
+        return session
+
+    token = mobile_token(store, session=session)
+    if isinstance(token, Result):
+        return token
+
+    company_id = (
+        session.profile.company_id.strip()
+        if session.profile is not None
+        else ""
+    )
+    profile_data: dict | None = None
+    if not company_id:
+        employment = client.employment_info(token)
+        if isinstance(employment, Result):
+            if not employment.ok:
+                return employment
+            data = employment.data
+        else:
+            data = employment
+        if not isinstance(data, dict):
+            return Result(False, "profile_missing", "Profile company ID is unavailable")
+        company_id = positive_id(data.get("company_id") or data.get("companyId"))
+        if company_id is None:
+            return Result(False, "profile_missing", "Profile company ID is unavailable")
+        profile_data = data
+
+    return session, token, company_id, profile_data
+
+
+def schedule(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> ActiveSchedule | Result:
+    with owned_client(client) as mekari:
+        resolved = _resolve_attendance(store, mekari)
+        if isinstance(resolved, Result):
+            return resolved
+        _, token, company_id, _profile = resolved
+        return mekari.active_schedule(token, company_id)
+
+
+def summary_list(
+    selected_date: date,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    with owned_client(client) as mekari:
+        resolved = _resolve_attendance(store, mekari)
+        if isinstance(resolved, Result):
+            return resolved
+        _, token, company_id, _profile = resolved
+        return mekari.summary_attendance_clocks(
+            token,
+            company_id,
+            selected_date.isoformat(),
+        )
+
+
+def summary_metrics(
+    selected_date: date,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    with owned_client(client) as mekari:
+        resolved = _resolve_attendance(store, mekari)
+        if isinstance(resolved, Result):
+            return resolved
+        _, token, company_id, profile_data = resolved
+
+        if profile_data is None:
+            profile = mekari.employment_info(token)
+            if isinstance(profile, Result):
+                if not profile.ok:
+                    return profile
+                profile_data = profile.data
+            else:
+                profile_data = profile
+        user_id = (
+            positive_id(profile_data.get("id")) if isinstance(profile_data, dict) else None
+        )
+        if user_id is None:
+            return Result(False, "profile_missing", "Profile user ID is unavailable")
+
+        return mekari.summary_attendance_metrics(
+            token,
+            company_id,
+            user_id,
+            selected_date.isoformat(),
+        )
+
+
+def preview_clock(
+    event_type: str,
+    notes: str,
+    *,
+    latitude: str,
+    longitude: str,
+    location_id: str | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    validation = validate_notes(notes) or validate_coordinates(latitude, longitude)
+    if validation is not None:
+        return validation
+    with owned_client(client) as mekari:
+        resolved = _resolve_attendance(store, mekari)
+        if isinstance(resolved, Result):
+            return resolved
+        _, token, company_id, _profile = resolved
+        active = mekari.active_schedule(token, company_id)
+    if isinstance(active, Result):
+        return active
+    return Result(
+        True,
+        "clockin_preview",
+        "Attendance request preview",
+        data={
+            "method": "POST",
+            "url": clock_endpoint(company_id),
+            "fields": build_clock_fields(
+                active,
+                event_type,
+                notes,
+                latitude=latitude,
+                longitude=longitude,
+                location_id=location_id,
+            ),
+        },
+    )
+
+
+def clock(
+    event_type: str,
+    notes: str,
+    selfie: Path | None = None,
+    *,
+    schedule: ActiveSchedule,
+    latitude: str,
+    longitude: str,
+    location_id: str | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    validation = validate_notes(notes) or validate_coordinates(latitude, longitude)
+    if validation is not None:
+        return validation
+    with owned_client(client) as mekari:
+        resolved = _resolve_attendance(store, mekari)
+        if isinstance(resolved, Result):
+            return resolved
+        _, token, company_id, _profile = resolved
+        return mekari.clock(
+            token,
+            company_id,
+            event_type,
+            notes,
+            selfie,
+            schedule=schedule,
+            latitude=latitude,
+            longitude=longitude,
+            location_id=location_id,
+        )

tlnt/core/services/calendar.py

@@ -0,0 +1,54 @@
+from collections.abc import Mapping
+from typing import Any
+
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.services import with_client
+from tlnt.core.session import SessionStore
+
+
+def calendar_holiday(
+    params: Mapping[str, Any] | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_holiday(token, params), store, client)
+
+
+def calendar_timeoff(
+    params: Mapping[str, Any] | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_timeoff(token, params), store, client)
+
+
+def calendar_index(
+    params: Mapping[str, Any] | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_index(token, params), store, client)
+
+
+def calendar_my_birthday(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_my_birthday(token), store, client)
+
+
+def calendar_birthday(
+    params: Mapping[str, Any] | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_birthday(token, params), store, client)
+
+
+def calendar_activity(
+    params: Mapping[str, Any] | None = None,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.calendar_activity(token, params), store, client)

tlnt/core/services/login.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import asdict, replace
+from functools import partial
+
+from keyring.errors import KeyringError
+
+from tlnt.browser.login import (
+    DEFAULT_CDP_ENDPOINT,
+    BrowserLogin,
+    Credentials,
+    LoginFailed,
+    cdp_context,
+    chrome_context,
+)
+from tlnt.browser.scripted import ScriptedLogin
+from tlnt.core.models import Result, SessionState
+from tlnt.core.logs import logger
+from tlnt.core.session import InvalidSession, SessionMissing, SessionStore
+
+
+_log = logger.bind(component="service")
+
+
+def _drop_stored_password(store: SessionStore, session: SessionState) -> SessionState:
+    """Best-effort removal of a password saved by the retired --store-password."""
+    if session.keyring_ref is None:
+        return session
+    try:
+        store.delete_password(session.keyring_ref)
+    except KeyringError:
+        # Keep the reference so a later `tlnt logout` can retry the cleanup.
+        _log.bind(
+            event="warning",
+            operation="login",
+            error_type="KeyringError",
+        ).warning("stored password cleanup failed")
+        return session
+    return replace(session, credential_email=None, keyring_ref=None)
+
+
+def _browser_login(
+    backend: str, cdp: str, credentials: Credentials | None, headless: bool
+) -> BrowserLogin:
+    if backend == "cdp":
+        return BrowserLogin(
+            context_factory=partial(cdp_context, cdp), credentials=credentials
+        )
+    if backend in ("ego", "yab"):
+        return ScriptedLogin(backend)
+    factory = partial(chrome_context, headless=True) if headless else chrome_context
+    return BrowserLogin(context_factory=factory, credentials=credentials)
+
+
+def login(
+    store: SessionStore | None = None,
+    browser: BrowserLogin | None = None,
+    *,
+    backend: str = "chrome",
+    cdp: str = DEFAULT_CDP_ENDPOINT,
+    credentials: Credentials | None = None,
+    headless: bool = False,
+) -> Result:
+    store = store or SessionStore()
+    browser = browser or _browser_login(backend, cdp, credentials, headless)
+    try:
+        existing = store.load()
+    except (SessionMissing, InvalidSession):
+        existing = None
+    try:
+        session = browser.login()
+    except LoginFailed as error:
+        return Result(False, "login_failed", str(error))
+    if existing is not None:
+        session = _drop_stored_password(
+            store,
+            replace(
+                session,
+                profile=session.profile or existing.profile,
+                mobile=session.mobile or existing.mobile,
+                credential_email=existing.credential_email,
+                keyring_ref=existing.keyring_ref,
+            ),
+        )
+
+    try:
+        store.save(session)
+        saved = store.load()
+    except (OSError, InvalidSession):
+        return Result(
+            False,
+            "login_failed",
+            "Login succeeded, but the session could not be saved",
+        )
+    return Result(
+        True,
+        "login_succeeded",
+        "Login saved",
+        data=asdict(saved.profile) if saved.profile is not None else None,
+    )

tlnt/core/services/logout.py

@@ -0,0 +1,38 @@
+from keyring.errors import KeyringError
+
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.services import owned_client
+from tlnt.core.session import SessionStore, load_session, mobile_token
+
+
+def logout(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    store = store or SessionStore()
+    session = load_session(store)
+    token = mobile_token(store, session if not isinstance(session, Result) else None)
+    remote_status: int | None = None
+
+    if not isinstance(token, Result):
+        with owned_client(client) as mekari:
+            remote = mekari.logout(token)
+        # An already-expired token leaves no remote session to end.
+        if not remote.ok and remote.code != "mobile_token_expired":
+            return remote
+        remote_status = remote.status_code
+    if not isinstance(session, Result) and session.keyring_ref is not None:
+        try:
+            store.delete_password(session.keyring_ref)
+        except KeyringError:
+            return Result(
+                False,
+                "logout_failed",
+                "Password could not be removed from the system keyring",
+            )
+    try:
+        store.delete()
+    except OSError:
+        return Result(False, "logout_failed", "Session could not be removed")
+    return Result(True, "logout_succeeded", "Session removed", remote_status)

tlnt/core/services/notifications.py

@@ -0,0 +1,97 @@
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.services import with_client
+from tlnt.core.session import SessionStore
+
+
+def notification_count(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.notification_count(token), store, client)
+
+
+def notification_list(
+    page: int = 1,
+    query: str = "",
+    status: int = 3,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.notification_list(token, page, query, status), store, client
+    )
+
+
+def notification_attendance_list(
+    page: int = 1,
+    query: str = "",
+    status: int = 3,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.notification_attendance_list(token, page, query, status),
+        store,
+        client,
+    )
+
+
+def notification_timeoff_list(
+    page: int = 1,
+    query: str = "",
+    status: int = 3,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.notification_timeoff_list(token, page, query, status),
+        store,
+        client,
+    )
+
+
+def notification_detail(
+    inbox_id: int,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.notification_detail(token, inbox_id), store, client
+    )
+
+
+def attendance_approve(
+    inbox_id: int,
+    attendance_id: int,
+    inbox_message: str,
+    reason: str = "",
+    *,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.attendance_approve(
+            token, inbox_id, attendance_id, inbox_message, reason
+        ),
+        store,
+        client,
+    )
+
+
+def timeoff_approve(
+    inbox_id: int,
+    timeoff_id: int,
+    inbox_message: str,
+    reason: str = "",
+    *,
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(
+        lambda c, token: c.timeoff_approve(
+            token, inbox_id, timeoff_id, inbox_message, reason
+        ),
+        store,
+        client,
+    )

tlnt/core/services/profile.py

@@ -0,0 +1,11 @@
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.models import Result
+from tlnt.core.services import with_client
+from tlnt.core.session import SessionStore
+
+
+def profile(
+    store: SessionStore | None = None,
+    client: MekariClient | None = None,
+) -> Result:
+    return with_client(lambda c, token: c.employment_info(token), store, client)

tlnt/core/services/setup.py

@@ -0,0 +1,85 @@
+"""Create config.json, or bring an existing one up to date."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from tlnt.core import config
+from tlnt.core.clients.mekari.constants import (
+    DEFAULT_APP_VERSION,
+    DEFAULT_USER_AGENT_MOBILE,
+)
+from tlnt.core.models import Result
+
+# Every key tlnt reads from config.json; an empty value means "not set".
+DEFAULT_CONFIG: dict[str, str] = {
+    "client_id": "",
+    "app_version": DEFAULT_APP_VERSION,
+    "user_agent_mobile": DEFAULT_USER_AGENT_MOBILE,
+    "session_path": "",
+    "cdp": "",
+    "latitude": "",
+    "longitude": "",
+}
+
+
+def setup(path: Path | None = None) -> Result:
+    """Add missing keys, drop unknown ones, and keep every value already set."""
+    path = path or config.get_config_path()
+    try:
+        text = path.read_text(encoding="utf-8") if path.exists() else ""
+        current = json.loads(text) if text.strip() else {}
+    except (OSError, ValueError):
+        current = None
+    if not isinstance(current, dict):
+        return Result(
+            False,
+            "setup_failed",
+            f"{path} is not a JSON object and was left unchanged; "
+            "fix or move it, then run `tlnt setup` again",
+        )
+    # A file with none of our keys belongs to something else; never trim it.
+    if current and not current.keys() & DEFAULT_CONFIG.keys():
+        return Result(
+            False,
+            "setup_failed",
+            f"{path} has no tlnt keys and was left unchanged; pass another "
+            "file with --config, or move it, then run `tlnt setup` again",
+        )
+
+    merged = {key: current.get(key, value) for key, value in DEFAULT_CONFIG.items()}
+    added = [key for key in DEFAULT_CONFIG if key not in current]
+    removed = [key for key in current if key not in DEFAULT_CONFIG]
+    if added or removed:
+        try:
+            path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+            path.touch(mode=0o600, exist_ok=True)
+            # ponytail: plain write, not atomic; use a temp file + os.replace
+            # if a truncated config is ever reported.
+            path.write_text(
+                json.dumps(merged, indent=2, ensure_ascii=False) + "\n",
+                encoding="utf-8",
+            )
+        except OSError as error:
+            return Result(
+                False,
+                "setup_failed",
+                f"Could not write {path}: {error.strerror or error}",
+            )
+
+    if not current:
+        message = f"Created {path}"
+    elif added or removed:
+        message = f"Updated {path}"
+    else:
+        message = f"{path} is up to date"
+    if not (merged["client_id"] or os.environ.get("TALENTA_CLIENT_ID")):
+        message += "; set client_id, then run `tlnt login`"
+    return Result(
+        True,
+        "setup_succeeded",
+        message,
+        data={"config_path": str(path), "added": added, "removed": removed},
+    )

tlnt/core/services/status.py

@@ -0,0 +1,35 @@
+from datetime import datetime, timezone
+
+from tlnt.core.models import Result
+from tlnt.core.session import SessionStore, load_session, mobile_token
+
+
+def status(store: SessionStore | None = None) -> Result:
+    session = load_session(store)
+    if isinstance(session, Result):
+        return session
+    token = mobile_token(store, session)
+    if isinstance(token, Result):
+        return token
+    # Expiry applies only to the saved token, never to TALENTA_BEARER.
+    saved = (
+        session.mobile
+        if session.mobile is not None and session.mobile.access_token == token
+        else None
+    )
+    if saved is not None and saved.is_expired(datetime.now(timezone.utc)):
+        return Result(
+            False,
+            "mobile_token_expired",
+            "Mobile token expired; run `tlnt login`",
+        )
+    return Result(
+        True,
+        "session_valid",
+        "Session is valid",
+        data=(
+            {"token_expires_at": saved.expires_at}
+            if saved is not None and saved.expires_at
+            else None
+        ),
+    )