kuma-stats 0.3.0__py3-none-any.whl

kuma_stats/__init__.py

@@ -0,0 +1,3 @@
+"""kuma-stats: CLI for viewing Uptime Kuma monitor heartbeat data, uptime, and status."""
+
+__version__ = "0.3.0"

kuma_stats/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m kuma_stats`."""
+
+from kuma_stats.cli import main
+
+main()

kuma_stats/cli.py

@@ -0,0 +1,328 @@
+"""kuma-stats command-line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, NoReturn, Optional, TypeVar, cast
+
+import click
+from rich.table import Table
+
+from . import __version__
+from .core.adapter import password_login
+from .core.config import Config, Format
+from .core.errors import KumaStatsError
+from .output import console, emit, emit_error, progress
+from .services import monitors
+
+T = TypeVar("T")
+
+
+def _config(ctx: click.Context) -> Config:
+    return ctx.obj["config"]
+
+
+def _percentage(value: object) -> str:
+    if value is None:
+        return "N/A"
+    if isinstance(value, (int, float)):
+        return f"{value * 100:.1f}%"
+    return str(value)
+
+
+def _table(title: str, data: object) -> Table:
+    table = Table(title=title, title_style="bold cyan")
+    if isinstance(data, dict) and "beats" in data:
+        beats = data["beats"]
+        table.title = f"Heartbeat History: {data['name']} (last {data['hours']}h)"
+        table.add_column("Time")
+        table.add_column("Status")
+        table.add_column("Ping")
+        table.add_column("Message")
+        for beat in beats:
+            ping = beat.get("ping")
+            table.add_row(
+                beat["time"], beat["status"], "N/A" if ping is None else f"{ping}ms", beat["msg"]
+            )
+        total = data["total_beats"]
+        if total:
+            up = sum(beat["status"] == "UP" for beat in beats)
+            table.caption = f"{up}/{total} UP ({up / total * 100:.1f}% uptime in this window)"
+        return table
+    if not isinstance(data, list):
+        return table
+    if title == "Uptime Kuma Monitors":
+        columns = ("ID", "Monitor", "Status", "24h Uptime", "30d Uptime", "Avg Ping", "Interval")
+        for column in columns:
+            table.add_column(column)
+        for monitor in data:
+            ping = monitor["avg_ping_ms"]
+            table.add_row(
+                str(monitor["id"]),
+                monitor["name"],
+                monitor["status"],
+                _percentage(monitor["uptime_24h"]),
+                _percentage(monitor["uptime_30d"]),
+                "N/A" if ping is None else f"{ping:.0f}ms",
+                f"{monitor['interval_seconds']}s",
+            )
+        return table
+    if title == "Uptime Kuma Uptime":
+        for column in ("ID", "Monitor", "24h", "30d", "1y"):
+            table.add_column(column)
+        for monitor in data:
+            table.add_row(
+                str(monitor["id"]),
+                monitor["name"],
+                _percentage(monitor["uptime_24h"]),
+                _percentage(monitor["uptime_30d"]),
+                _percentage(monitor["uptime_1y"]),
+            )
+        return table
+    table.add_column("Monitor")
+    table.add_column("Status")
+    table.add_column("24h")
+    table.add_column("30d")
+    table.add_column("1y")
+    table.add_column("Recent heartbeats")
+    for monitor in data:
+        uptime = monitor["uptime"]
+        table.add_row(
+            f"{monitor['name']} ({monitor['id']})",
+            monitor["status"],
+            _percentage(uptime.get("24")),
+            _percentage(uptime.get("720")),
+            _percentage(uptime.get("1y")),
+            str(len(monitor["recent_heartbeats"])),
+        )
+    return table
+
+
+def _output_options(command):
+    command = click.option(
+        "--format", "output_format", type=click.Choice(["table", "json", "yaml"]), default=None
+    )(command)
+    return click.option("--json", "json_output", is_flag=True, help="Shortcut for --format json.")(
+        command
+    )
+
+
+def _command_config(ctx: click.Context, output_format: Optional[str], json_output: bool) -> Config:
+    return _config(ctx).with_overrides(output_format="json" if json_output else output_format)
+
+
+def _store_token(token: str, path: Path, force: bool) -> None:
+    from dotenv import dotenv_values, set_key
+
+    old = dotenv_values(path).get("KUMA_TOKEN") if path.exists() else None
+    if old and old != token and not force:
+        raise click.ClickException(f"{path} already has a KUMA_TOKEN; use --force to replace it.")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    set_key(str(path), "KUMA_TOKEN", token, quote_mode="never")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("--url", envvar="KUMA_URL", help="Uptime Kuma server URL")
+@click.option("--username", envvar="KUMA_USERNAME", help="Login username")
+@click.option(
+    "--password", envvar="KUMA_PASSWORD", help="Login password (prefer KUMA_PASSWORD in automation)"
+)
+@click.option("--token", envvar="KUMA_TOKEN", help="JWT token (prefer KUMA_TOKEN in automation)")
+@click.option(
+    "--insecure", is_flag=True, default=None, help="Disable TLS certificate verification."
+)
+@click.option(
+    "--format", "output_format", type=click.Choice(["table", "json", "yaml"]), default=None
+)
+@click.option("--json", "json_output", is_flag=True, help="Shortcut for --format json.")
+@click.option(
+    "--timeout",
+    type=click.FloatRange(min=0.1),
+    default=None,
+    help="Connection/retry budget in seconds.",
+)
+@click.option(
+    "--retries",
+    type=click.IntRange(min=0),
+    default=None,
+    help="Retries for transient network failures.",
+)
+@click.version_option(__version__)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    url: Optional[str],
+    username: Optional[str],
+    password: Optional[str],
+    token: Optional[str],
+    insecure: Optional[bool],
+    output_format: Optional[str],
+    json_output: bool,
+    timeout: Optional[float],
+    retries: Optional[int],
+) -> None:
+    """View Uptime Kuma monitor status, uptime, and heartbeat data."""
+    try:
+        base = Config.load()
+    except KumaStatsError as error:
+        selected_format = cast(Format, "json" if json_output else output_format or "table")
+        emit_error(error, Config(output_format=selected_format))
+        ctx.exit(error.exit_code)
+    ctx.obj = {
+        "config": base.with_overrides(
+            url=url,
+            username=username,
+            password=password,
+            token=token,
+            insecure=insecure,
+            output_format="json" if json_output else output_format,
+            timeout_seconds=timeout,
+            max_retries=retries,
+        )
+    }
+
+
+@cli.command()
+@click.option("--store-token", is_flag=True, help="Save JWT to an owner-only dotenv file.")
+@click.option("--store-keyring", is_flag=True, help="Save JWT to the operating-system keyring.")
+@click.option(
+    "--env-file", type=click.Path(path_type=Path), default=Path(".env"), show_default=True
+)
+@click.option("--force", is_flag=True)
+@click.pass_context
+def login(
+    ctx: click.Context, store_token: bool, store_keyring: bool, env_file: Path, force: bool
+) -> None:
+    """Authenticate using username/password and print or save a JWT."""
+    if force and not store_token:
+        raise click.UsageError("--force requires --store-token.")
+    if store_token and store_keyring:
+        raise click.UsageError("Choose only one token storage backend.")
+    config = _config(ctx)
+    response = _execute(
+        config, "Authenticating with Uptime Kuma...", lambda: password_login(config)
+    )
+    token = response.get("token") if isinstance(response, dict) else None
+    if not isinstance(token, str) or not token:
+        _raise_error(
+            config, KumaStatsError("Uptime Kuma login succeeded but returned no JWT token.")
+        )
+    if store_token:
+        _store_token(token, env_file, force)
+        console.print(f"Saved KUMA_TOKEN to {env_file}; token value not printed.")
+    elif store_keyring:
+        from .core.session import save_token
+
+        try:
+            save_token(token)
+        except RuntimeError as error:
+            _raise_error(config, KumaStatsError(str(error)))
+        console.print("Saved JWT to the operating-system keyring; token value not printed.")
+    else:
+        click.echo(token)
+
+
+def _raise_error(config: Config, error: KumaStatsError) -> NoReturn:
+    emit_error(error, config)
+    raise click.exceptions.Exit(error.exit_code)
+
+
+def _execute(config: Config, message: str, operation: Callable[[], T]) -> T:
+    try:
+        with progress(message, enabled=config.output_format == "table"):
+            return operation()
+    except KumaStatsError as error:
+        _raise_error(config, error)
+
+
+def _report(config: Config, title: str, data: object) -> None:
+    emit(data, config, _table(title, data))
+
+
+@cli.command("list")
+@_output_options
+@click.pass_context
+def list_monitors(ctx: click.Context, output_format: Optional[str], json_output: bool) -> None:
+    """List all monitors and their current telemetry."""
+    config = _command_config(ctx, output_format, json_output)
+    _report(
+        config,
+        "Uptime Kuma Monitors",
+        _execute(config, "Fetching monitor telemetry...", lambda: monitors.list_monitors(config)),
+    )
+
+
+@cli.command("status")
+@click.argument("monitor_ids", type=int, nargs=-1)
+@_output_options
+@click.pass_context
+def status(
+    ctx: click.Context,
+    monitor_ids: tuple[int, ...],
+    output_format: Optional[str],
+    json_output: bool,
+) -> None:
+    """Show details for one or more monitor IDs."""
+    config = _command_config(ctx, output_format, json_output)
+    _report(
+        config,
+        "Monitor Status",
+        _execute(
+            config,
+            "Fetching monitor status...",
+            lambda: monitors.status_monitors(config, monitor_ids),
+        ),
+    )
+
+
+@cli.command("beats")
+@click.argument("monitor_id", type=int)
+@click.option("--hours", type=click.IntRange(min=1), default=24, show_default=True)
+@_output_options
+@click.pass_context
+def monitor_beats(
+    ctx: click.Context,
+    monitor_id: int,
+    hours: int,
+    output_format: Optional[str],
+    json_output: bool,
+) -> None:
+    """Show heartbeat history for a monitor."""
+    config = _command_config(ctx, output_format, json_output)
+    _report(
+        config,
+        "Heartbeat History",
+        _execute(
+            config,
+            "Fetching heartbeat history...",
+            lambda: monitors.beats(config, monitor_id, hours),
+        ),
+    )
+
+
+@cli.command("uptime")
+@_output_options
+@click.pass_context
+def uptime(ctx: click.Context, output_format: Optional[str], json_output: bool) -> None:
+    """Show 24-hour, 30-day, and one-year uptime."""
+    config = _command_config(ctx, output_format, json_output)
+    _report(
+        config,
+        "Uptime Kuma Uptime",
+        _execute(config, "Fetching uptime report...", lambda: monitors.uptime_report(config)),
+    )
+
+
+def main() -> None:
+    try:
+        cli(obj={})
+    except KeyboardInterrupt:
+        raise SystemExit(130)
+
+
+if __name__ == "__main__":
+    main()

kuma_stats/core/__init__.py

@@ -0,0 +1 @@
+"""Configuration, error, retry, and vendor-adapter infrastructure."""

kuma_stats/core/adapter.py

@@ -0,0 +1,103 @@
+"""Boundary around uptime-kuma-api, keeping vendor specifics out of commands."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from socketio.exceptions import SocketIOError
+from uptime_kuma_api import UptimeKumaApi
+from uptime_kuma_api.exceptions import Timeout as UptimeKumaTimeout
+from uptime_kuma_api.exceptions import UptimeKumaException
+
+from .config import Config
+from .errors import ApiError, AuthenticationError, NetworkError
+from .retry import with_retry
+
+
+def _disconnect(api: UptimeKumaApi | None) -> None:
+    if api is not None:
+        api.disconnect()
+
+
+def _is_connection_error(error: UptimeKumaException) -> bool:
+    return isinstance(error, UptimeKumaTimeout) or str(error) == "unable to connect"
+
+
+def _authenticate(config: Config) -> UptimeKumaApi:
+    """Construct and authenticate a client in one retryable operation."""
+    api: UptimeKumaApi | None = None
+    try:
+        api = UptimeKumaApi(
+            config.url, timeout=config.timeout_seconds, ssl_verify=not config.insecure
+        )
+        if config.token:
+            api.login_by_token(config.token)
+        else:
+            api.login(config.username, config.password)  # type: ignore[arg-type]
+        return api
+    except UptimeKumaException as error:
+        _disconnect(api)
+        if _is_connection_error(error):
+            raise
+        raise AuthenticationError(f"Unable to authenticate with Uptime Kuma: {error}") from error
+    except Exception:
+        _disconnect(api)
+        raise
+
+
+@contextmanager
+def authenticated_api(config: Config) -> Iterator[UptimeKumaApi]:
+    if not config.url:
+        raise AuthenticationError("Uptime Kuma URL is required. Set KUMA_URL or --url.")
+    if not config.token and (not config.username or not config.password):
+        raise AuthenticationError(
+            "Credentials required. Set KUMA_TOKEN or KUMA_USERNAME and KUMA_PASSWORD."
+        )
+    api = with_retry(
+        lambda: _authenticate(config),
+        attempts=config.max_retries,
+        timeout_seconds=config.timeout_seconds,
+    )
+    try:
+        yield api
+    except UptimeKumaException as error:
+        raise ApiError(f"Uptime Kuma returned an error: {error}") from error
+    except SocketIOError as error:
+        raise NetworkError(f"Connection to Uptime Kuma failed: {error}") from error
+    finally:
+        api.disconnect()
+
+
+def password_login(config: Config) -> dict:
+    if not config.url or not config.username or not config.password:
+        raise AuthenticationError(
+            "Login requires KUMA_URL, KUMA_USERNAME, and KUMA_PASSWORD (or their flags)."
+        )
+    api, response = with_retry(
+        lambda: _password_login(config),
+        attempts=config.max_retries,
+        timeout_seconds=config.timeout_seconds,
+    )
+    try:
+        return response
+    finally:
+        api.disconnect()
+
+
+def _password_login(config: Config) -> tuple[UptimeKumaApi, dict]:
+    api: UptimeKumaApi | None = None
+    try:
+        api = UptimeKumaApi(
+            config.url, timeout=config.timeout_seconds, ssl_verify=not config.insecure
+        )
+        response = api.login(config.username, config.password)
+        return api, response
+    except UptimeKumaException as error:
+        _disconnect(api)
+        if _is_connection_error(error):
+            raise
+        raise AuthenticationError(f"Unable to authenticate with Uptime Kuma: {error}") from error
+    except Exception:
+        _disconnect(api)
+        raise

kuma_stats/core/config.py

@@ -0,0 +1,94 @@
+"""Layered runtime configuration: CLI flags > environment > dotenv defaults."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Literal
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+
+from platformdirs import user_config_dir
+
+from .errors import ConfigurationError
+
+Format = Literal["table", "json", "yaml"]
+_FORMATS = {"table", "json", "yaml"}
+
+
+@dataclass(frozen=True)
+class Config:
+    url: str | None = None
+    username: str | None = None
+    password: str | None = None
+    token: str | None = None
+    insecure: bool = False
+    output_format: Format = "table"
+    timeout_seconds: float = 30.0
+    max_retries: int = 2
+    color: bool = True
+
+    @classmethod
+    def load(cls) -> "Config":
+        # Precedence: defaults < user TOML < dotenv/environment < CLI options.
+        path = Path(
+            os.environ.get("KUMA_CONFIG_FILE", Path(user_config_dir("kuma-stats")) / "config.toml")
+        )
+        try:
+            with path.open("rb") as handle:
+                file_config: dict[str, Any] = tomllib.load(handle)
+        except FileNotFoundError:
+            file_config = {}
+        except tomllib.TOMLDecodeError as error:
+            raise ConfigurationError(f"Invalid TOML configuration in {path}: {error}") from error
+        except OSError as error:
+            raise ConfigurationError(
+                f"Unable to read configuration file {path}: {error}"
+            ) from error
+        from dotenv import load_dotenv
+
+        load_dotenv(dotenv_path=Path.cwd() / ".env")
+
+        def value(name: str, default: Any = None) -> Any:
+            return os.environ.get(f"KUMA_{name.upper()}", file_config.get(name, default))
+
+        def number(name: str, default: float, converter: type[float] | type[int]) -> float | int:
+            try:
+                return converter(value(name, default))
+            except (TypeError, ValueError) as error:
+                raise ConfigurationError(f"KUMA_{name.upper()} must be a number.") from error
+
+        output_format = str(value("format", "table")).lower()
+        if output_format not in _FORMATS:
+            raise ConfigurationError("KUMA_FORMAT must be one of: table, json, yaml.")
+        timeout = number("timeout", 30, float)
+        retries = number("max_retries", 2, int)
+        if timeout <= 0:
+            raise ConfigurationError("KUMA_TIMEOUT must be greater than zero.")
+        if retries < 0:
+            raise ConfigurationError("KUMA_MAX_RETRIES cannot be negative.")
+
+        no_color = bool(os.environ.get("NO_COLOR"))
+        token = value("token")
+        if not token:
+            from .session import get_token
+
+            token = get_token()
+        return cls(
+            url=value("url"),
+            username=value("username"),
+            password=value("password"),
+            token=token,
+            insecure=str(value("insecure", False)).lower() in {"1", "true", "yes"},
+            output_format=output_format,  # type: ignore[arg-type]
+            timeout_seconds=float(timeout),
+            max_retries=int(retries),
+            color=not no_color and not bool(value("no_color", False)),
+        )
+
+    def with_overrides(self, **kwargs: object) -> "Config":
+        return replace(self, **{key: value for key, value in kwargs.items() if value is not None})  # type: ignore[arg-type]

kuma_stats/core/errors.py

@@ -0,0 +1,44 @@
+"""Consistent errors and exit codes for kuma-stats."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class KumaStatsError(Exception):
+    message: str
+    code: str = "API_ERROR"
+    exit_code: int = 1
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return self.message
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"error": True, "code": self.code, "message": self.message, "details": self.details}
+
+
+class ConfigurationError(KumaStatsError):
+    def __init__(self, message: str):
+        super().__init__(message, "INVALID_CONFIGURATION", 2)
+
+
+class AuthenticationError(KumaStatsError):
+    def __init__(self, message: str):
+        super().__init__(message, "AUTH_REQUIRED", 2)
+
+
+class NotFoundError(KumaStatsError):
+    def __init__(self, message: str):
+        super().__init__(message, "NOT_FOUND", 1)
+
+
+class NetworkError(KumaStatsError):
+    def __init__(self, message: str):
+        super().__init__(message, "NETWORK_ERROR", 1)
+
+
+class ApiError(KumaStatsError):
+    def __init__(self, message: str):
+        super().__init__(message, "API_ERROR", 1)

kuma_stats/core/retry.py

@@ -0,0 +1,51 @@
+"""Small synchronous retry helper for transient Kuma connection failures."""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+from socketio.exceptions import SocketIOError
+from uptime_kuma_api.exceptions import Timeout as UptimeKumaTimeout
+from uptime_kuma_api.exceptions import UptimeKumaException
+
+from .errors import NetworkError
+
+T = TypeVar("T")
+
+
+def _is_transient(error: Exception) -> bool:
+    return (
+        not isinstance(error, UptimeKumaException)
+        or isinstance(error, UptimeKumaTimeout)
+        or str(error) == "unable to connect"
+    )
+
+
+def with_retry(operation: Callable[[], T], *, attempts: int, timeout_seconds: float) -> T:
+    """Retry transient Socket.IO and network failures within a backoff budget."""
+    started = time.monotonic()
+    last: Exception | None = None
+    for attempt in range(attempts + 1):
+        try:
+            return operation()
+        except (
+            OSError,
+            ConnectionError,
+            TimeoutError,
+            SocketIOError,
+            UptimeKumaException,
+        ) as error:
+            if not _is_transient(error):
+                raise
+            last = error
+            remaining = timeout_seconds - (time.monotonic() - started)
+            if attempt == attempts or remaining <= 0:
+                break
+            delay = min(0.25 * 2**attempt * (0.75 + random.random() * 0.5), 2.0, remaining)
+            time.sleep(delay)
+    raise NetworkError(
+        f"Unable to contact Uptime Kuma after {attempts + 1} attempt(s): {last}"
+    ) from last

kuma_stats/core/session.py

@@ -0,0 +1,21 @@
+"""Secure optional JWT storage in the operating-system keyring."""
+
+from __future__ import annotations
+import keyring
+
+SERVICE = "kuma-stats"
+ACCOUNT = "jwt"
+
+
+def get_token() -> str | None:
+    try:
+        return keyring.get_password(SERVICE, ACCOUNT)
+    except Exception:
+        return None
+
+
+def save_token(token: str) -> None:
+    try:
+        keyring.set_password(SERVICE, ACCOUNT, token)
+    except Exception as error:
+        raise RuntimeError(f"Unable to store token in OS keyring: {error}") from error

kuma_stats/output/__init__.py

@@ -0,0 +1,54 @@
+"""Output and progress helpers; data always stays on stdout."""
+
+from __future__ import annotations
+import json, sys
+from contextlib import contextmanager
+from collections.abc import Iterator
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from ..core.config import Config
+from ..core.errors import KumaStatsError
+
+console = Console(color_system="auto")
+err_console = Console(stderr=True, color_system="auto")
+
+
+def emit(data: object, config: Config, table: object | None = None) -> None:
+    if config.output_format == "json":
+        print(json.dumps(data, indent=2, default=str))
+    elif config.output_format == "yaml":
+        import yaml
+
+        print(yaml.safe_dump(data, default_flow_style=False, sort_keys=False))
+    elif table is not None:
+        console.print(table)
+
+
+def emit_error(error: KumaStatsError, config: Config) -> None:
+    if config.output_format == "json":
+        print(json.dumps(error.to_dict()), file=sys.stderr)
+    elif config.output_format == "yaml":
+        import yaml
+
+        print(yaml.safe_dump(error.to_dict(), sort_keys=False), file=sys.stderr, end="")
+    else:
+        err_console.print(f"[red]Error:[/] {error.message}")
+
+
+@contextmanager
+def progress(message: str, *, enabled: bool = True) -> Iterator[None]:
+    if not enabled:
+        yield
+        return
+    if not sys.stderr.isatty():
+        print(message, file=sys.stderr)
+        yield
+        return
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=err_console,
+        transient=True,
+    ) as display:
+        display.add_task(message, total=None)
+        yield

kuma_stats/services/__init__.py

@@ -0,0 +1 @@
+"""Application services for querying monitor telemetry."""

kuma_stats/services/monitors.py

@@ -0,0 +1,111 @@
+"""Fetch and normalize Uptime Kuma monitoring telemetry."""
+
+from __future__ import annotations
+from uptime_kuma_api import MonitorStatus
+from ..core.adapter import authenticated_api
+from ..core.config import Config
+from ..core.errors import NotFoundError
+
+
+def status_value(value: MonitorStatus) -> str:
+    return value.name if isinstance(value, MonitorStatus) else str(value)
+
+
+def monitor_map(monitors: list[dict]) -> dict[int, dict]:
+    return {int(m["id"]): m for m in monitors}
+
+
+def list_monitors(config: Config) -> list[dict]:
+    with authenticated_api(config) as api:
+        monitors = monitor_map(api.get_monitors())
+        uptime, pings = api.uptime(), api.avg_ping()
+        statuses = {mid: api.get_monitor_status(mid) for mid in monitors}
+    return [
+        {
+            "id": mid,
+            "name": m.get("name", ""),
+            "url": m.get("url", ""),
+            "status": status_value(statuses[mid]),
+            "uptime_24h": uptime.get(mid, {}).get(24),
+            "uptime_30d": uptime.get(mid, {}).get(720),
+            "avg_ping_ms": pings.get(mid),
+            "interval_seconds": m.get("interval"),
+        }
+        for mid, m in sorted(monitors.items())
+    ]
+
+
+def status_monitors(config: Config, ids: tuple[int, ...]) -> list[dict]:
+    with authenticated_api(config) as api:
+        monitors = monitor_map(api.get_monitors())
+        selected = ids or tuple(sorted(monitors))
+        missing = [str(mid) for mid in selected if mid not in monitors]
+        if missing:
+            raise NotFoundError(f"Monitor IDs not found: {', '.join(missing)}")
+        uptime, pings, heartbeats = api.uptime(), api.avg_ping(), api.get_heartbeats()
+        result = []
+        for mid in selected:
+            m, beats, u = (
+                monitors[mid],
+                sorted(heartbeats.get(mid, []), key=lambda h: h["time"], reverse=True),
+                uptime.get(mid, {}),
+            )
+            result.append(
+                {
+                    "id": mid,
+                    "name": m.get("name", ""),
+                    "url": m.get("url", ""),
+                    "type": m.get("type", ""),
+                    "status": status_value(api.get_monitor_status(mid)),
+                    "interval": m.get("interval"),
+                    "avg_ping_ms": pings.get(mid),
+                    "uptime": {str(k): v for k, v in u.items()},
+                    "recent_heartbeats": [
+                        {
+                            "time": b["time"],
+                            "status": status_value(b["status"]),
+                            "ping": b.get("ping"),
+                        }
+                        for b in beats[:10]
+                    ],
+                }
+            )
+    return result
+
+
+def beats(config: Config, monitor_id: int, hours: int) -> dict:
+    with authenticated_api(config) as api:
+        monitors = monitor_map(api.get_monitors())
+        if monitor_id not in monitors:
+            raise NotFoundError(f"Monitor {monitor_id} not found")
+        raw = api.get_monitor_beats(monitor_id, hours)
+    return {
+        "monitor_id": monitor_id,
+        "name": monitors[monitor_id].get("name", f"Monitor {monitor_id}"),
+        "hours": hours,
+        "total_beats": len(raw),
+        "beats": [
+            {
+                "time": b["time"],
+                "status": status_value(b["status"]),
+                "ping": b.get("ping"),
+                "msg": b.get("msg", ""),
+            }
+            for b in raw
+        ],
+    }
+
+
+def uptime_report(config: Config) -> list[dict]:
+    with authenticated_api(config) as api:
+        monitors, data = monitor_map(api.get_monitors()), api.uptime()
+    return [
+        {
+            "id": mid,
+            "name": m.get("name", ""),
+            "uptime_24h": data.get(mid, data.get(str(mid), {})).get(24),
+            "uptime_30d": data.get(mid, data.get(str(mid), {})).get(720),
+            "uptime_1y": data.get(mid, data.get(str(mid), {})).get("1y"),
+        }
+        for mid, m in sorted(monitors.items())
+    ]

kuma_stats-0.3.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: kuma-stats
+Version: 0.3.0
+Summary: Read-only CLI for Uptime Kuma monitor status, uptime, and heartbeat data
+Project-URL: Homepage, https://github.com/crcatala/kuma-stats
+Project-URL: Repository, https://github.com/crcatala/kuma-stats
+Project-URL: Issues, https://github.com/crcatala/kuma-stats/issues
+Project-URL: Security, https://github.com/crcatala/kuma-stats/security/policy
+Author-email: Christian Catalan <crcatala@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,monitoring,status,uptime,uptime-kuma
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: keyring>=24.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uptime-kuma-api>=1.2.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kuma-stats
+
+[![CI](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml/badge.svg)](https://github.com/crcatala/kuma-stats/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/kuma-stats)](https://pypi.org/project/kuma-stats/)
+[![Python](https://img.shields.io/pypi/pyversions/kuma-stats)](https://pypi.org/project/kuma-stats/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A read-only terminal dashboard for [Uptime Kuma](https://github.com/louislam/uptime-kuma): current monitor state, uptime percentages, response time, and heartbeat history.
+
+> `kuma-stats` is an independent project and is not affiliated with or endorsed by Uptime Kuma.
+
+## Install
+
+Requires Python 3.10 or later.
+
+```bash
+pip install kuma-stats
+# or install as an isolated command-line tool
+uv tool install kuma-stats
+# pipx install kuma-stats
+```
+
+Verify the installation:
+
+```bash
+kuma-stats --version
+```
+
+## Quick start
+
+Set the Uptime Kuma URL and a server-issued JWT token. Environment variables are preferred for automation; do not pass passwords or tokens as command-line arguments because they can be exposed in shell history or process listings.
+
+```bash
+export KUMA_URL=https://kuma.example.com
+export KUMA_TOKEN=your-server-issued-jwt
+kuma-stats list
+kuma-stats --format json uptime
+```
+
+Alternatively, create a `.env` file in the directory where you run the command:
+
+```dotenv
+KUMA_URL=https://kuma.example.com
+KUMA_TOKEN=your-server-issued-jwt
+```
+
+`kuma-stats` loads this working-directory `.env` without overwriting environment variables. Keep it out of version control.
+
+To create a token with username/password credentials already supplied through environment variables, use:
+
+```bash
+export KUMA_USERNAME=your-username
+export KUMA_PASSWORD=your-password
+kuma-stats login --store-keyring
+```
+
+The keyring is the preferred token store. `login --store-token` writes an owner-only `.env` file; use it only when the OS keyring is unavailable.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `login [--store-token \| --store-keyring]` | Authenticate and print or securely save a server-issued JWT |
+| `list` | List all monitors and current telemetry |
+| `status [ID…]` | Show details and recent heartbeats; omit IDs for all monitors |
+| `beats ID [--hours N]` | Show heartbeat history for one monitor |
+| `uptime` | Show 24-hour, 30-day, and one-year uptime |
+
+Examples:
+
+```bash
+kuma-stats list
+kuma-stats status 1 2
+kuma-stats beats 1 --hours 48
+kuma-stats --format yaml uptime
+kuma-stats --format json list
+```
+
+Table output is the default. Use `--format json` or `--format yaml` for structured output. JSON and YAML errors are written to stderr with a stable code and message.
+
+## Configuration
+
+Values are resolved in this order, from highest to lowest precedence:
+
+1. Command-line options
+2. Environment variables
+3. A `.env` file in the working directory
+4. User configuration: `$XDG_CONFIG_HOME/kuma-stats/config.toml` on Linux
+5. An OS-keyring token
+
+Use `KUMA_CONFIG_FILE` to select a different TOML file. Example:
+
+```toml
+url = "https://kuma.example.com"
+format = "table" # table, json, or yaml
+timeout = 30
+max_retries = 2
+insecure = false
+```
+
+| Variable | Purpose |
+| --- | --- |
+| `KUMA_URL` | Uptime Kuma server URL |
+| `KUMA_TOKEN` | Server-issued JWT token |
+| `KUMA_USERNAME`, `KUMA_PASSWORD` | Login credentials; required for `login` without a token |
+| `KUMA_FORMAT` | Default output format: `table`, `json`, or `yaml` |
+| `KUMA_TIMEOUT` | Per-connection timeout and overall retry budget in seconds |
+| `KUMA_MAX_RETRIES` | Retry count for transient connection failures |
+| `KUMA_INSECURE` | Set to `true` only for a trusted self-signed server |
+| `NO_COLOR` | Disable terminal colour |
+
+TLS certificate verification is enabled by default. Use `--insecure` only for a trusted self-signed server. Invalid or unreadable TOML configuration files fail with an `INVALID_CONFIGURATION` error instead of being ignored.
+
+## Compatibility
+
+`kuma-stats` supports Python 3.10–3.12 and uses the maintained [`uptime-kuma-api`](https://github.com/lucasheld/uptime-kuma-api) client for Uptime Kuma communication. CI smoke-tests token authentication, password login, failed authentication, and `list` telemetry against a disposable [Uptime Kuma 1.23.16](https://hub.docker.com/layers/louislam/uptime-kuma/1.23.16/images/sha256-431fee3be822b04861cf0e35daf4beef6b7cb37391c5f26c3ad6e12ce280fe18) Docker container. It uses no external server or credentials.
+
+## Development
+
+```bash
+make setup
+make verify
+make live-test # requires Docker
+```
+
+`make verify` runs linting, type checks, tests, builds wheel/sdist artifacts, and validates their metadata. `make live-test` runs the separately gated Docker compatibility smoke test; it creates disposable credentials and state and never contacts a production server.
+
+### Releasing
+
+Releases are intentionally manual. Draft notes from the commits since the last release:
+
+```bash
+make release-prep
+```
+
+Use the printed prompt with an LLM if useful, review its suggested Keep a Changelog entry, then update `CHANGELOG.md` and `src/kuma_stats/__init__.py`. Preview and create the GitHub Release:
+
+```bash
+make release-dry
+make release
+```
+
+`make release` requires a clean `main` worktree, a new versioned changelog section, and confirmation. It validates the project, creates and pushes an annotated `vX.Y.Z` tag, then attaches the validated wheel and sdist to a GitHub Release. PyPI publishing is a separate deliberate step:
+
+```bash
+uv run twine upload dist/*
+```
+
+See [docs/RELEASING.md](docs/RELEASING.md) for PyPI/TestPyPI account setup, local token storage, testing, and troubleshooting.
+
+## Security and support
+
+See [SECURITY.md](SECURITY.md) for private vulnerability reporting, [CONTRIBUTING.md](CONTRIBUTING.md) for the maintenance policy, and [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+Distributed under the [MIT License](LICENSE).

kuma_stats-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+kuma_stats/__init__.py,sha256=HhA_IKuu9VjT92OgpgYFPib6hJOR1Si_LS8N2-hcR_I,113
+kuma_stats/__main__.py,sha256=-du2PrU1IKC-4dAYUBrSoIyVX8OH-wV_E7gm-REdtnw,88
+kuma_stats/cli.py,sha256=dNHBX5jxVbleqGdZRWvYR9SR9zCa1YNHwWxnmBB--dI,10778
+kuma_stats/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kuma_stats/core/__init__.py,sha256=D1zj7PHtddjEbUGXvyJkjfXWz-NtQ8ozHSkH4el39GM,70
+kuma_stats/core/adapter.py,sha256=c543Fj1odw21b8cXBvAqwK84I0jJoolt_our19ooTLo,3508
+kuma_stats/core/config.py,sha256=WNJajMKrlQyRfQzkKAvr_tuw3mBGqr3IvRxma1A1t7c,3454
+kuma_stats/core/errors.py,sha256=4bAda9oJ7tv0_wiUuDHmRxLMBlfPCfTyeFNI76IMsUM,1188
+kuma_stats/core/retry.py,sha256=sK25AA8gZbJnDZTUmlW3BtRgH7j2EE4_meIpmMW0qqg,1615
+kuma_stats/core/session.py,sha256=ER2MYkf-vDHzMOyKBfQkbPvsyOFX5iDYqMuI8l8FG9s,515
+kuma_stats/output/__init__.py,sha256=OpHFk4d3qesrLwiT3QzmVt33VQZ_3-FZRDoypEmQovI,1692
+kuma_stats/services/__init__.py,sha256=SCrPMM7bgbAhQpuG_TFJSeEc49iUEZvBXllrfo2i7ms,59
+kuma_stats/services/monitors.py,sha256=gPVXAOKt2ZgQetxOkiE4g3xmiZUA3DWkSBAsDdc5N4Y,4045
+kuma_stats-0.3.0.dist-info/METADATA,sha256=b2gWw4NFisjCRdXKj6nwXnuN2nIKTwd3o8BMRsMiPqw,7595
+kuma_stats-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+kuma_stats-0.3.0.dist-info/entry_points.txt,sha256=oYDhrGgZvxWNbuj-z8UZYuPUvmIMM8B0QDkjAjETFOU,51
+kuma_stats-0.3.0.dist-info/licenses/LICENSE,sha256=vpJeqfvQ02IDIT2tVzjQ01DtkG2WL37D7FopDvDKn4o,1074
+kuma_stats-0.3.0.dist-info/RECORD,,

kuma_stats-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kuma_stats-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kuma-stats = kuma_stats.cli:main

kuma_stats-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Catalan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.