tlnt-cli 1.5.1__py3-none-any.whl

tlnt/cli/avatars.py

@@ -0,0 +1,51 @@
+"""Terminal thumbnails for Talenta avatar URLs."""
+
+from __future__ import annotations
+
+import io
+from functools import lru_cache
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from PIL import Image
+from rich_pixels import Pixels
+
+from tlnt.core.logs import logger
+
+_log = logger.bind(component="cli.avatars")
+
+# HalfcellRenderer packs two pixels into one terminal row, so 8px -> 8 cols x 4 rows.
+SIZE = 8
+TIMEOUT = 3.0
+
+
+def is_avatar_url(value: Any) -> bool:
+    """True for an http(s) URL whose path contains an /avatar/ segment."""
+    if not isinstance(value, str) or not value.startswith(("http://", "https://")):
+        return False
+    return "/avatar/" in urlparse(value).path
+
+
+@lru_cache(maxsize=64)
+def thumbnail(url: str) -> Pixels | None:
+    """Square half-block thumbnail, or None when the image is unusable.
+
+    Anonymous on purpose: avatars live on a third-party CDN, so no session
+    cookie or bearer token is ever attached. Failures are cached too, so a
+    dead URL is not refetched once per row.
+    """
+    try:
+        response = httpx.get(url, timeout=TIMEOUT, follow_redirects=True)
+        response.raise_for_status()
+        with Image.open(io.BytesIO(response.content)) as image:
+            return Pixels.from_image(image, resize=(SIZE, SIZE))
+    except Exception as error:  # best effort: a bad avatar must not break a table
+        # Host and error type only: the avatar path (and httpx's error text,
+        # which repeats the URL) can identify an employee.
+        _log.bind(
+            event="avatar_failed",
+            host=urlparse(url).hostname,
+            error_type=type(error).__name__,
+        ).debug("avatar unavailable")
+        return None

tlnt/cli/commands/approvals.py

@@ -0,0 +1,98 @@
+"""The confirm-then-submit flow shared by attendance and time-off approvals."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import typer
+
+from tlnt.cli import prompts
+from tlnt.cli.output import action_banner, confirm, console, dig, emit, spinner
+from tlnt.core.models import Result
+
+
+def _is_pending(flag: object) -> bool:
+    """Documented contract: only a numeric 0 marks a pending approval."""
+    return isinstance(flag, int) and not isinstance(flag, bool) and flag == 0
+
+
+def run_approval(
+    inbox_id: int | None,
+    reason: str,
+    interactive: bool,
+    json_output: bool,
+    verbose: bool,
+    *,
+    noun: str,
+    id_label: str,
+    list_command: str,
+    cancelled_code: str,
+    list_page: Callable[[], Result],
+    load_detail: Callable[[int], Result],
+    fields: Callable[[Result], tuple[int, str] | Result],
+    submit: Callable[[int, int, str, str], Result],
+) -> None:
+    """Show one inbox request and approve it only after terminal confirmation."""
+    if interactive:
+        unavailable = prompts.guard(json_output, title=f"Approve {noun}")
+        if unavailable is not None:
+            emit(unavailable, json_output)
+            return
+    if interactive and inbox_id is None:
+        spinner_enabled = not (json_output or verbose)
+        with spinner("Loading pending approvals...", enabled=spinner_enabled):
+            listing = list_page()
+        if not listing.ok:
+            emit(listing, json_output)
+            return
+        rows = dig(listing.data, "inbox.data") or []
+        pending = [
+            row
+            for row in rows
+            if isinstance(row, dict) and _is_pending(row.get("approval_flag"))
+        ]
+        if not pending:
+            emit(
+                Result(False, "no_pending_approvals", f"No pending {noun} approvals"),
+                json_output,
+            )
+            return
+        last_page = dig(listing.data, "inbox.last_page")
+        if isinstance(last_page, int) and last_page > 1:
+            console.print(
+                "More pending approvals may exist — "
+                f"see `{list_command} --page`.",
+                style="warning",
+            )
+        selected = prompts.pick(pending, ("id", "message"), "Select a request to approve")
+        inbox_id = int(selected["id"])
+
+    if inbox_id is None:
+        raise typer.BadParameter("Missing argument 'INBOX_ID'.")
+    if inbox_id < 1:
+        raise typer.BadParameter("inbox_id must be at least 1")
+
+    detail = load_detail(inbox_id)
+    if not detail.ok:
+        emit(detail, json_output)
+        return
+    checked = fields(detail)
+    if isinstance(checked, Result):
+        emit(checked, json_output)
+        return
+    request_id, message = checked
+    action_banner(f"Approve {noun}", enabled=not json_output)
+    typer.echo(f"Inbox ID: {inbox_id}", err=True)
+    typer.echo(f"{id_label}: {request_id}", err=True)
+    typer.echo(f"Message: {message}", err=True)
+    if not confirm(
+        f"Approve this {noun} request?",
+        default=False,
+        err=True,
+    ):
+        emit(
+            Result(False, cancelled_code, f"{noun.capitalize()} approval cancelled"),
+            json_output,
+        )
+        return
+    emit(submit(inbox_id, request_id, message, reason), json_output)

tlnt/cli/commands/attendance.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+from datetime import date
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from tlnt.cli import prompts
+from tlnt.cli.commands.approvals import run_approval
+from tlnt.cli.output import action_banner, confirm, emit, spinner
+from tlnt.cli.options import (
+    AvatarsOption,
+    InteractiveOption,
+    JsonOption,
+    TableOption,
+    VerboseOption,
+)
+from tlnt.core.config import get_setting
+from tlnt.core.models import Result
+from tlnt.core.services import positive_id
+from tlnt.core.services.attendance import (
+    clock as clock_action,
+    preview_clock as preview_action,
+    schedule as schedule_action,
+    summary_list as summary_list_action,
+    summary_metrics as summary_metrics_action,
+    validate_coordinates,
+    validate_notes,
+)
+from tlnt.core.services.notifications import (
+    attendance_approve as attendance_approve_action,
+    notification_attendance_list as notification_attendance_list_action,
+    notification_detail as notification_detail_action,
+)
+
+def _run_attendance(
+    event_type: str,
+    action_label: str,
+    dry_run: bool,
+    notes: str,
+    selfie: Path | None,
+    json_output: bool,
+    latitude: str | None,
+    longitude: str | None,
+    location_id: str | None,
+    interactive: bool = False,
+    verbose: bool = False,
+    avatars: bool = False,
+) -> None:
+    if interactive:
+        unavailable = prompts.guard(json_output, title=action_label)
+        if unavailable is not None:
+            emit(unavailable, json_output)
+            return
+        latitude = prompts.ask_required(
+            "Latitude",
+            latitude or "",
+            default=get_setting("TALENTA_LATITUDE", "latitude"),
+        )
+        longitude = prompts.ask_required(
+            "Longitude",
+            longitude or "",
+            default=get_setting("TALENTA_LONGITUDE", "longitude"),
+        )
+        location_id = prompts.ask_optional("Location ID", location_id or "") or None
+        notes = prompts.ask_optional("Notes", notes)
+        selfie = prompts.ask_path("Selfie photo path", selfie)
+
+    if latitude is None:
+        raise typer.BadParameter("Missing option '--latitude'.")
+    if longitude is None:
+        raise typer.BadParameter("Missing option '--longitude'.")
+
+    validation = validate_notes(notes) or validate_coordinates(latitude, longitude)
+    if validation is not None:
+        raise typer.BadParameter(validation.message)
+
+    spinner_enabled = not (json_output or verbose)
+
+    if dry_run:
+        emit(
+            preview_action(
+                event_type,
+                notes,
+                latitude=latitude,
+                longitude=longitude,
+                location_id=location_id,
+            ),
+            json_output,
+            avatars=avatars,
+        )
+        return
+
+    with spinner("Checking active schedule...", enabled=spinner_enabled):
+        active = schedule_action()
+    if isinstance(active, Result):
+        emit(active, json_output)
+        return
+
+    location = f"{latitude}, {longitude}"
+    if location_id is not None:
+        location += f" [{location_id}]"
+    action_banner(action_label, enabled=not json_output)
+    if not confirm(
+        f"{action_label} on {active.schedule_date} at {location}?",
+        err=json_output,
+    ):
+        cancelled_code = (
+            "clockout_cancelled" if event_type == "clock_out" else "clockin_cancelled"
+        )
+        emit(
+            Result(False, cancelled_code, f"{action_label} cancelled"),
+            json_output,
+        )
+        return
+
+    with spinner(f"{action_label}...", enabled=spinner_enabled):
+        result = clock_action(
+            event_type,
+            notes,
+            selfie,
+            schedule=active,
+            latitude=latitude,
+            longitude=longitude,
+            location_id=location_id,
+        )
+    emit(result, json_output, avatars=avatars)
+
+
+def _clock_command(event_type: str, label: str, doc: str) -> Callable[..., None]:
+    """Clock-in and clock-out share every option and differ only in the event."""
+
+    def command(
+        latitude: Annotated[
+            str | None,
+            typer.Option("--latitude", help="Attendance latitude."),
+        ] = None,
+        longitude: Annotated[
+            str | None,
+            typer.Option("--longitude", help="Attendance longitude."),
+        ] = None,
+        location_id: Annotated[
+            str | None,
+            typer.Option("--location-id", help="Optional Talenta location ID."),
+        ] = None,
+        dry_run: Annotated[
+            bool,
+            typer.Option("--dry-run", help="Preview without submitting attendance."),
+        ] = False,
+        notes: Annotated[
+            str,
+            typer.Option("--notes", help="Optional attendance note."),
+        ] = "",
+        selfie: Annotated[
+            Path | None,
+            typer.Option(
+                "--selfie",
+                help="Optional selfie photo to attach.",
+                exists=True,
+                dir_okay=False,
+                readable=True,
+            ),
+        ] = None,
+        interactive: InteractiveOption = False,
+        json_output: JsonOption = False,
+        table: TableOption = False,
+        avatars: AvatarsOption = False,
+        verbose: VerboseOption = False,
+    ) -> None:
+        _run_attendance(
+            event_type,
+            label,
+            dry_run,
+            notes,
+            selfie,
+            json_output,
+            latitude,
+            longitude,
+            location_id,
+            interactive=interactive,
+            verbose=verbose,
+            avatars=avatars,
+        )
+
+    command.__doc__ = doc
+    return command
+
+
+attendance_clockin = _clock_command(
+    "clock_in", "Clock in", "Clock in now or preview a request."
+)
+attendance_clockout = _clock_command(
+    "clock_out", "Clock out", "Clock out now or preview a request."
+)
+
+
+def _attendance_date(value: str | None) -> date:
+    if value is None:
+        return date.today()
+    try:
+        selected_date = date.fromisoformat(value)
+    except ValueError as error:
+        raise typer.BadParameter("date must be YYYY-MM-DD") from error
+    if selected_date.isoformat() != value:
+        raise typer.BadParameter("date must be YYYY-MM-DD")
+    return selected_date
+
+
+def attendance_summary_list(
+    selected_date: Annotated[
+        str | None,
+        typer.Option("--date", help="Attendance date (YYYY-MM-DD)."),
+    ] = None,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read attendance summaries for a date."""
+    emit(summary_list_action(_attendance_date(selected_date)), json_output)
+
+
+def attendance_summary_metrics(
+    selected_date: Annotated[
+        str | None,
+        typer.Option("--date", help="Attendance date (YYYY-MM-DD)."),
+    ] = None,
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read attendance summary metrics for a date."""
+    emit(summary_metrics_action(_attendance_date(selected_date)), json_output)
+
+
+def _approval_fields(detail: Result) -> tuple[int, str] | Result:
+    data = detail.data
+    inbox = data.get("inbox") if isinstance(data, dict) else None
+    request = inbox.get("live_attendance_request") if isinstance(inbox, dict) else None
+    message = inbox.get("message") if isinstance(inbox, dict) else None
+    attendance_id = positive_id(request.get("id")) if isinstance(request, dict) else None
+    if attendance_id is None or not isinstance(message, str):
+        return Result(
+            False,
+            "remote_error",
+            "Mekari returned an invalid live-attendance approval response",
+            detail.status_code,
+            data,
+        )
+    return int(attendance_id), message
+
+
+def attendance_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 live attendance request after confirmation."""
+    run_approval(
+        inbox_id,
+        reason,
+        interactive,
+        json_output,
+        verbose,
+        noun="attendance",
+        id_label="Attendance ID",
+        list_command="tlnt notification attendance-list",
+        cancelled_code="attendance_approval_cancelled",
+        list_page=lambda: notification_attendance_list_action(page=1),
+        load_detail=notification_detail_action,
+        fields=_approval_fields,
+        submit=attendance_approve_action,
+    )

tlnt/cli/commands/calendar.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Annotated, Any
+
+import typer
+
+from tlnt.cli.options import JsonOption, TableOption, VerboseOption
+from tlnt.cli.output import run
+from tlnt.core.services import calendar as calendar_service
+
+
+def _calendar_params(
+    start_date: str | None,
+    end_date: str | None,
+    limit: int,
+    month: int | None,
+    year: int | None,
+    page: int,
+    item_id: str | None,
+    event_type: str | None,
+    search: str | None,
+    date: str | None,
+    user_id: str | None,
+) -> dict[str, Any]:
+    if page < 1:
+        raise typer.BadParameter("page must be at least 1")
+    if limit < 1:
+        raise typer.BadParameter("limit must be at least 1")
+
+    return {
+        key: value
+        for key, value in {
+            "start_date": start_date,
+            "end_date": end_date,
+            "limit": limit,
+            "month": month,
+            "year": year,
+            "page": page,
+            "id": item_id,
+            "type": event_type,
+            "search": search,
+            "date": date,
+            "user_id": user_id,
+        }.items()
+        if value is not None
+    }
+
+
+def _filtered_command(name: str, label: str, doc: str) -> Callable[..., None]:
+    """One calendar lookup that takes the shared filters."""
+
+    def command(
+        start_date: Annotated[str | None, typer.Option("--start-date")] = None,
+        end_date: Annotated[str | None, typer.Option("--end-date")] = None,
+        limit: Annotated[int, typer.Option("--limit")] = 10,
+        month: Annotated[int | None, typer.Option("--month")] = None,
+        year: Annotated[int | None, typer.Option("--year")] = None,
+        page: Annotated[int, typer.Option("--page")] = 1,
+        item_id: Annotated[str | None, typer.Option("--id")] = None,
+        event_type: Annotated[str | None, typer.Option("--type")] = None,
+        search: Annotated[str | None, typer.Option("--search")] = None,
+        date: Annotated[str | None, typer.Option("--date")] = None,
+        user_id: Annotated[str | None, typer.Option("--user-id")] = None,
+        json_output: JsonOption = False,
+        table: TableOption = False,
+        verbose: VerboseOption = False,
+    ) -> None:
+        params = _calendar_params(
+            start_date, end_date, limit, month, year, page,
+            item_id, event_type, search, date, user_id,
+        )
+        # Looked up per call so tests can patch the service function.
+        run(label, lambda: getattr(calendar_service, name)(params), json_output, verbose)
+
+    command.__doc__ = doc
+    return command
+
+
+calendar_holiday = _filtered_command(
+    "calendar_holiday", "Loading calendar holidays...", "Read calendar holidays."
+)
+calendar_timeoff = _filtered_command(
+    "calendar_timeoff", "Loading calendar time off...", "Read calendar time-off events."
+)
+calendar_index = _filtered_command(
+    "calendar_index", "Loading calendar index...", "Read dates with calendar events."
+)
+calendar_birthday = _filtered_command(
+    "calendar_birthday", "Loading calendar birthdays...", "Read employee birthday events."
+)
+calendar_activity = _filtered_command(
+    "calendar_activity", "Loading calendar activity...", "Read calendar activity events."
+)
+
+
+def calendar_my_birthday(
+    json_output: JsonOption = False,
+    table: TableOption = False,
+    verbose: VerboseOption = False,
+) -> None:
+    """Read your birthday date."""
+    run(
+        "Loading your birthday...",
+        calendar_service.calendar_my_birthday,
+        json_output,
+        verbose,
+    )