tlnt-cli 1.5.1__py3-none-any.whl

tlnt/cli/commands/timeoff.py

@@ -0,0 +1,491 @@
+from __future__ import annotations
+
+from datetime import date as date_type
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.prompt import Prompt
+
+from tlnt.cli import prompts
+from tlnt.cli.commands.approvals import run_approval
+from tlnt.cli.options import InteractiveOption, JsonOption, TableOption, VerboseOption
+from tlnt.cli.output import action_banner, confirm, console, dig, emit, run
+from tlnt.core.models import Result
+from tlnt.core.services import positive_id
+from tlnt.core.services import timeoff as timeoff_service
+from tlnt.core.services.notifications import (
+    notification_detail as notification_detail_action,
+    notification_timeoff_list as notification_timeoff_list_action,
+    timeoff_approve as timeoff_approve_action,
+)
+
+
+def timeoff_types_list(
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read available time-off types."""
+    run(
+        "Loading time-off policies...",
+        timeoff_service.timeoff_types_list,
+        json_output,
+        verbose,
+    )
+
+
+def timeoff_balance(
+    date: Annotated[
+        str,
+        typer.Option("--date", help="Balance date."),
+    ] = "",
+    keyword: Annotated[
+        str,
+        typer.Option("--keyword", help="Filter balances by keyword."),
+    ] = "",
+    show_unlimited_balance: Annotated[
+        bool,
+        typer.Option("--show-unlimited-balance", help="Include unlimited balances."),
+    ] = False,
+    policy_id: Annotated[
+        str,
+        typer.Option("--policy-id", help="Filter by time-off policy ID."),
+    ] = "",
+    limited_by_date: Annotated[
+        str,
+        typer.Option("--limited-by-date", help="Limit balances by date."),
+    ] = "",
+    refresh: Annotated[
+        bool,
+        typer.Option("--refresh/--no-refresh", help="Refresh balances before reading."),
+    ] = True,
+    show_special_leave: Annotated[
+        bool,
+        typer.Option("--show-special-leave", help="Include special leave balances."),
+    ] = False,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read the signed-in user's time-off balances."""
+    run(
+        "Loading time-off balance...",
+        lambda: timeoff_service.timeoff_balance(
+            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,
+        ),
+        json_output,
+        verbose,
+    )
+
+
+def timeoff_delegation_list(
+    page: Annotated[
+        int,
+        typer.Option("--page", help="Delegation page number."),
+    ] = 1,
+    search: Annotated[
+        str,
+        typer.Option("--search", help="Search for a delegate."),
+    ] = "",
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Search employees available for time-off delegation."""
+    if page < 1:
+        raise typer.BadParameter("page must be at least 1")
+    run(
+        "Loading delegates...",
+        lambda: timeoff_service.timeoff_delegation_list(page=page, search=search),
+        json_output,
+        verbose,
+    )
+
+
+def timeoff_list(
+    page: Annotated[
+        int,
+        typer.Option("--page", help="Request page number."),
+    ] = 1,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", help="Maximum requests per page."),
+    ] = 30,
+    date: Annotated[
+        str,
+        typer.Option("--date", help="Start date filter."),
+    ] = "",
+    end_date: Annotated[
+        str,
+        typer.Option("--end-date", help="End date filter."),
+    ] = "",
+    status: Annotated[
+        int,
+        typer.Option("--status", help="Time-off request status."),
+    ] = 0,
+    policy_id: Annotated[
+        str,
+        typer.Option("--policy-id", help="Filter by time-off policy ID."),
+    ] = "",
+    all_period: Annotated[
+        bool,
+        typer.Option("--all-period/--no-all-period", help="Include all periods."),
+    ] = True,
+    show_metrics: Annotated[
+        bool,
+        typer.Option("--show-metrics", help="Include request metrics."),
+    ] = False,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read time-off requests."""
+    if page < 1:
+        raise typer.BadParameter("page must be at least 1")
+    if limit < 1:
+        raise typer.BadParameter("limit must be at least 1")
+    run(
+        "Loading time-off requests...",
+        lambda: timeoff_service.timeoff_list(
+            page=page,
+            limit=limit,
+            date=date,
+            end_date=end_date,
+            status=status,
+            policy_id=policy_id,
+            all_period=all_period,
+            show_metrics=show_metrics,
+        ),
+        json_output,
+        verbose,
+    )
+
+
+def timeoff_detail(
+    request_id: Annotated[
+        int,
+        typer.Argument(help="Time-off request ID."),
+    ],
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read one time-off request."""
+    if request_id < 1:
+        raise typer.BadParameter("request_id must be at least 1")
+    run(
+        "Loading time-off request...",
+        lambda: timeoff_service.timeoff_detail(request_id),
+        json_output,
+        verbose,
+    )
+
+
+
+def _valid_schedule_time(value: str) -> bool:
+    return (
+        len(value) == 5
+        and value[2] == ":"
+        and value[:2].isdigit()
+        and value[3:].isdigit()
+        and 0 <= int(value[:2]) < 24
+        and 0 <= int(value[3:]) < 60
+    )
+
+
+def timeoff_request(
+    date: Annotated[
+        str | None,
+        typer.Option("--date", help="Time-off date in YYYY-MM-DD format."),
+    ] = None,
+    policy_id: Annotated[
+        str | None,
+        typer.Option("--policy-id", help="Time-off policy ID."),
+    ] = None,
+    reason: Annotated[
+        str | None,
+        typer.Option("--reason", help="Reason for the time-off request."),
+    ] = None,
+    half_day: Annotated[
+        str | None,
+        typer.Option(
+            "--half-day",
+            help="Choose before or after break for a half-day leave.",
+        ),
+    ] = None,
+    schedule_in: Annotated[
+        str,
+        typer.Option("--schedule-in", help="Schedule start time (HH:MM)."),
+    ] = "",
+    schedule_out: Annotated[
+        str,
+        typer.Option("--schedule-out", help="Schedule end time (HH:MM)."),
+    ] = "",
+    delegate_to: Annotated[
+        str,
+        typer.Option("--delegate-to", help="Delegate the request to an employee ID."),
+    ] = "",
+    file_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--file",
+            exists=True,
+            dir_okay=False,
+            readable=True,
+            help="Attach one file to the request.",
+        ),
+    ] = None,
+    interactive: InteractiveOption = False,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Request a full-day or half-day time off."""
+    if interactive:
+        unavailable = prompts.guard(json_output, title="Time-off request")
+        if unavailable is not None:
+            emit(unavailable, json_output)
+            return
+        if policy_id is None:
+            policies = timeoff_service.timeoff_types_list()
+            if not policies.ok:
+                emit(policies, json_output)
+                return
+            rows = dig(policies.data, "timeOffPolicies")
+            if not rows:
+                raise typer.BadParameter("No time-off policies available.")
+            selected = prompts.pick(rows, ("id", "policy_name"), "Select a policy")
+            policy_id = str(selected["id"])
+        date = prompts.ask_required(
+            "Date (YYYY-MM-DD)", date or "", default=date_type.today().isoformat()
+        )
+        reason = prompts.ask_required("Reason", reason or "")
+        if half_day is None:
+            leave_type = Prompt.ask(
+                "Leave type",
+                choices=["full", "before", "after"],
+                default="full",
+                console=console,
+            )
+            half_day = None if leave_type == "full" else leave_type
+        if half_day:
+            schedule_in = prompts.ask_required("Schedule start (HH:MM)", schedule_in)
+            schedule_out = prompts.ask_required("Schedule end (HH:MM)", schedule_out)
+        file_path = prompts.ask_path("Attachment path (optional)", file_path)
+
+    if date is None:
+        raise typer.BadParameter("Missing option '--date'.", param_hint="--date")
+    if policy_id is None:
+        raise typer.BadParameter("Missing option '--policy-id'.", param_hint="--policy-id")
+    if reason is None:
+        raise typer.BadParameter("Missing option '--reason'.", param_hint="--reason")
+
+    try:
+        parsed_date = date_type.fromisoformat(date)
+    except ValueError as error:
+        raise typer.BadParameter(
+            "date must use YYYY-MM-DD format",
+            param_hint="--date",
+        ) from error
+    if parsed_date.isoformat() != date:
+        raise typer.BadParameter("date must use YYYY-MM-DD format", param_hint="--date")
+    if not policy_id.strip():
+        raise typer.BadParameter("policy_id must not be empty", param_hint="--policy-id")
+    if not reason.strip():
+        raise typer.BadParameter("reason must not be empty", param_hint="--reason")
+    if half_day not in {None, "before", "after"}:
+        raise typer.BadParameter(
+            "half-day must be before or after",
+            param_hint="--half-day",
+        )
+    if half_day:
+        if not schedule_in or not schedule_out:
+            raise typer.BadParameter(
+                "both schedule times are required for half-day leave",
+                param_hint="--schedule-in and --schedule-out",
+            )
+        if not _valid_schedule_time(schedule_in):
+            raise typer.BadParameter(
+                "schedule-in must use 24-hour HH:MM format",
+                param_hint="--schedule-in",
+            )
+        if not _valid_schedule_time(schedule_out):
+            raise typer.BadParameter(
+                "schedule-out must use 24-hour HH:MM format",
+                param_hint="--schedule-out",
+            )
+    elif schedule_in or schedule_out:
+        raise typer.BadParameter(
+            "schedule times require --half-day",
+            param_hint="--half-day",
+        )
+
+    request_period = (
+        f"{half_day}-break half-day from {schedule_in} to {schedule_out}"
+        if half_day
+        else "full-day"
+    )
+    action_banner("Time-off request", enabled=not json_output)
+    if not confirm(
+        f"Request {request_period} time off on {date} with policy {policy_id} "
+        f"for {reason!r}?",
+        default=False,
+        err=json_output,
+    ):
+        emit(
+            Result(False, "timeoff_action_cancelled", "Time-off request cancelled"),
+            json_output,
+        )
+        return
+    emit(
+        timeoff_service.timeoff_request(
+            date=date,
+            policy_id=policy_id,
+            reason=reason,
+            half_day_after_break=half_day == "after",
+            half_day_before_break=half_day == "before",
+            schedule_in=schedule_in,
+            delegate_to=delegate_to,
+            file_path=str(file_path) if file_path is not None else None,
+            schedule_out=schedule_out,
+        ),
+        json_output,
+    )
+
+
+def timeoff_cancel(
+    request_id: Annotated[
+        int | None,
+        typer.Argument(help="Time-off request ID."),
+    ] = None,
+    request_type: Annotated[
+        str,
+        typer.Option("--type", help="Cancellation request type."),
+    ] = "1002",
+    interactive: InteractiveOption = False,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Cancel a time-off request after confirmation."""
+    if interactive:
+        unavailable = prompts.guard(json_output, title="Cancel time-off")
+        if unavailable is not None:
+            emit(unavailable, json_output)
+            return
+        if request_id is None:
+            listing = timeoff_service.timeoff_list(
+                page=1,
+                limit=30,
+                date="",
+                end_date="",
+                status=0,
+                policy_id="",
+                all_period=True,
+                show_metrics=False,
+            )
+            if not listing.ok:
+                emit(listing, json_output)
+                return
+            rows = dig(listing.data, "time_off_request.data")
+            if not rows:
+                raise typer.BadParameter("No time-off requests available to cancel.")
+            last_page = dig(listing.data, "time_off_request.last_page")
+            if isinstance(last_page, int) and last_page > 1:
+                console.print(
+                    "More time-off requests may exist — see `tlnt timeoff list --page`.",
+                    style="yellow",
+                )
+            selected = prompts.pick(rows, ("id", "request_id"), "Select a request to cancel")
+            request_id = int(selected["id"])
+
+    if request_id is None:
+        raise typer.BadParameter("Missing argument 'REQUEST_ID'.")
+    if request_id < 1:
+        raise typer.BadParameter("request_id must be at least 1")
+    action_banner("Cancel time-off", enabled=not json_output)
+    if not confirm(
+        f"Cancel time-off request {request_id} (type {request_type})?",
+        default=False,
+        err=json_output,
+    ):
+        emit(
+            Result(False, "timeoff_action_cancelled", "Time-off action cancelled"),
+            json_output,
+        )
+        return
+    emit(
+        timeoff_service.timeoff_cancel(
+            request_id=request_id,
+            request_type=request_type,
+        ),
+        json_output,
+    )
+
+
+def _timeoff_approval_fields(detail: Result) -> tuple[int, str] | Result:
+    inbox = dig(detail.data, "inbox")
+    if isinstance(dig(inbox, "live_attendance_request"), dict):
+        return Result(
+            False,
+            "invalid_input",
+            "This inbox item is an attendance request; approve it with "
+            "`tlnt attendance approve`",
+        )
+    message = inbox.get("message") if isinstance(inbox, dict) else None
+    # fk_ref and timeoff_request.id name the same request; when both are
+    # present they must agree.
+    ids = {
+        positive_id(raw_id)
+        for raw_id in (dig(inbox, "fk_ref"), dig(inbox, "timeoff_request.id"))
+        if raw_id is not None
+    }
+    request_id = ids.pop() if len(ids) == 1 else None
+    if request_id is None or not isinstance(message, str):
+        return Result(
+            False,
+            "remote_error",
+            "Mekari returned an invalid time-off approval response",
+            detail.status_code,
+            detail.data,
+        )
+    return int(request_id), message
+
+
+def timeoff_approve(
+    inbox_id: Annotated[
+        int | None,
+        typer.Argument(help="Talenta inbox ID."),
+    ] = None,
+    reason: Annotated[
+        str,
+        typer.Option("--reason", help="Optional approval reason."),
+    ] = "",
+    interactive: InteractiveOption = False,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Approve a time-off request after confirmation."""
+    run_approval(
+        inbox_id,
+        reason,
+        interactive,
+        json_output,
+        verbose,
+        noun="time-off",
+        id_label="Time-off request ID",
+        list_command="tlnt notification timeoff-list",
+        cancelled_code="timeoff_approval_cancelled",
+        list_page=lambda: notification_timeoff_list_action(page=1),
+        load_detail=notification_detail_action,
+        fields=_timeoff_approval_fields,
+        submit=timeoff_approve_action,
+    )

tlnt/cli/commands/update.py

@@ -0,0 +1,86 @@
+"""Self-update command."""
+
+from __future__ import annotations
+
+import subprocess
+from importlib import metadata
+from typing import NoReturn
+
+import httpx
+import typer
+
+from tlnt import DISTRIBUTION
+from tlnt.core import play_store
+
+PYPI_URL = f"https://pypi.org/pypi/{DISTRIBUTION}/json"
+
+
+def _fail(message: str) -> NoReturn:
+    typer.echo(message, err=True)
+    raise typer.Exit(1)
+
+
+def _version_key(version: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in version.split("."))
+
+
+def latest_release_version(timeout: float = 10) -> str:
+    """Return the newest tlnt version published on PyPI."""
+    response = httpx.get(PYPI_URL, timeout=timeout, follow_redirects=True)
+    response.raise_for_status()
+    return response.json()["info"]["version"]
+
+
+def fetch_latest_version() -> str | None:
+    """Like latest_release_version, but quick and silent: None on any failure."""
+    try:
+        version = latest_release_version(timeout=3)
+    except (httpx.HTTPError, ValueError, KeyError, TypeError):
+        return None
+    return version if isinstance(version, str) else None
+
+
+def update_warning() -> str | None:
+    """Return a notice when PyPI has a newer tlnt than the installed one."""
+    installed = metadata.version(DISTRIBUTION)
+    latest = play_store.cached_version("pypi_version.json", fetch_latest_version)
+    try:
+        if not latest or _version_key(latest) <= _version_key(installed):
+            return None
+    except ValueError:
+        return None  # pre-release or dev version: stay silent
+    return (
+        f"⚠️ tlnt v{installed} is installed, but v{latest} is available. "
+        "Run `tlnt update` to update."
+    )
+
+
+def _install_release(installed: str, latest: str) -> int:
+    typer.echo(f"Installing tlnt {latest} (current {installed})")
+    try:
+        return subprocess.run(
+            ["uv", "tool", "install", f"{DISTRIBUTION}=={latest}", "--force"]
+        ).returncode
+    except FileNotFoundError:
+        _fail("uv not found; install uv first: https://docs.astral.sh/uv/")
+
+
+def update() -> None:
+    """Update tlnt to the latest PyPI release."""
+    installed = metadata.version(DISTRIBUTION)
+    try:
+        latest = latest_release_version()
+    except (httpx.HTTPError, ValueError, KeyError, TypeError):
+        _fail("Could not read the latest tlnt release from PyPI")
+    try:
+        latest_key = _version_key(latest)
+    except ValueError:
+        _fail(f"Unexpected release version: {latest}")
+    installed_key = _version_key(installed)
+    if latest_key == installed_key:
+        typer.echo(f"tlnt {installed} is the latest release")
+        raise typer.Exit(0)
+    if latest_key < installed_key:
+        typer.echo(f"tlnt {installed} is newer than the latest release ({latest})")
+        raise typer.Exit(0)
+    raise typer.Exit(_install_release(installed, latest))

tlnt/cli/commands/version.py

@@ -0,0 +1,15 @@
+"""Version command callback."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+import typer
+
+from tlnt import DISTRIBUTION
+
+
+def print_version(show: bool) -> None:
+    if show:
+        typer.echo(metadata.version(DISTRIBUTION))
+        raise typer.Exit()