cometapi-cli 0.1.0__py3-none-any.whl

cometapi_cli/commands/tokens.py

@@ -0,0 +1,87 @@
+"""Tokens (API keys) management command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ..config import get_client, mask_secret
+from ..constants import extract_items, format_ts, quota_to_usd
+from ..errors import handle_errors
+from ..formatters import OutputFormat, output, resolve_format
+
+_STATUS_MAP = {1: "active", 2: "disabled", 3: "expired", 4: "exhausted"}
+
+
+def _quota_to_usd(quota: int | float) -> str:
+    if quota < 0:
+        return "Unlimited"
+    return quota_to_usd(quota, precision=2)
+
+
+def _format_ts_short(ts: int) -> str:
+    return format_ts(ts, fmt="%Y-%m-%d %H:%M")
+
+
+def _format_token_row(t: dict) -> dict:
+    key = t.get("key", "")
+    unlimited = t.get("unlimited_quota", False)
+    return {
+        "id": t.get("id", ""),
+        "name": t.get("name", "") or "—",
+        "key": mask_secret(key) if key else "—",
+        "status": _STATUS_MAP.get(t.get("status", 0), "unknown"),
+        "balance": "Unlimited" if unlimited else _quota_to_usd(t.get("remain_quota", 0)),
+        "used": _quota_to_usd(t.get("used_quota", 0)),
+        "created": _format_ts_short(t.get("created_time", 0)),
+        "accessed": _format_ts_short(t.get("accessed_time", 0)),
+        "expires": "Never" if t.get("expired_time", 0) == -1 else _format_ts_short(t.get("expired_time", 0)),
+    }
+
+
+@handle_errors
+def tokens(
+    ctx: typer.Context,
+    search: Annotated[str | None, typer.Option("--search", "-s", help="Search tokens by name or key.")] = None,
+    page: Annotated[int, typer.Option("--page", "-p", help="Page number.")] = 1,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Results per page.")] = 20,
+    output_format: Annotated[OutputFormat | None, typer.Option("--format", "-f", help="Output format.")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON.")] = False,
+) -> None:
+    """List and search your API keys (requires access token)."""
+    fmt = resolve_format(ctx, json_output, output_format)
+    client = get_client(require_access_token=True)
+
+    if search:
+        resp = client.search_tokens(keyword=search)
+        # Search returns a flat list — apply client-side limit if specified
+        data = extract_items(resp)
+        if limit and len(data) > limit:
+            data = data[:limit]
+    else:
+        resp = client.list_tokens(page=page, page_size=limit)
+        data = extract_items(resp)
+
+    if fmt == OutputFormat.JSON:
+        output(data, fmt)
+        return
+
+    if not data:
+        from ..console import console
+        console.print("[dim]No tokens found.[/]")
+        return
+
+    rows = [_format_token_row(t) for t in data]
+    columns = {
+        "id": "cyan",
+        "name": "green",
+        "key": "yellow",
+        "status": "green",
+        "balance": "green",
+        "used": "red",
+        "created": "dim",
+        "accessed": "dim",
+        "expires": "dim",
+    }
+    output(rows, fmt, title="API Keys (Tokens)", columns=columns)

cometapi_cli/config.py

@@ -0,0 +1,102 @@
+"""Configuration file management for CometAPI CLI."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+from .errors import ConfigError, ConfigMissing
+
+CONFIG_DIR = Path.home() / ".config" / "cometapi"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+VALID_KEYS = {"api_key", "access_token", "base_url", "default_model", "output_format"}
+
+
+def load_config() -> dict[str, Any]:
+    """Load config from TOML file. Returns empty dict if file doesn't exist."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return tomllib.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except Exception as e:
+        raise ConfigError(
+            f"Config file is corrupt or unreadable: {CONFIG_FILE}\n{e}\n"
+            "Fix the file or delete it and run [bold]cometapi init[/bold]."
+        )
+
+
+def save_config(config: dict[str, Any]) -> None:
+    """Save config to TOML file with restrictive permissions."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_bytes(tomli_w.dumps(config).encode("utf-8"))
+    CONFIG_FILE.chmod(0o600)
+
+
+def get_value(key: str, env_var: str | None = None, default: Any = None) -> Any:
+    """Get a config value with priority: config file > env var > default."""
+    cfg = load_config()
+    val = cfg.get(key)
+    if val:
+        return val
+    if env_var:
+        env_val = os.environ.get(env_var)
+        if env_val:
+            return env_val
+    return default
+
+
+def mask_secret(value: str, show_last: int = 4) -> str:
+    """Mask a secret value, showing only the last N characters."""
+    if not value:
+        return ""
+    if len(value) <= show_last:
+        return "****"
+    return "****" + value[-show_last:]
+
+
+def get_client(require_access_token: bool = False, **overrides: Any) -> Any:
+    """Create a CometClient with config file fallback.
+
+    Priority: override > config file > env var > default.
+    """
+    from cometapi_cli.client import CometClient
+
+    cfg = load_config()
+
+    api_key = overrides.get("api_key") or cfg.get("api_key") or os.environ.get("COMETAPI_KEY")
+    access_token = overrides.get("access_token") or cfg.get("access_token") or os.environ.get("COMETAPI_ACCESS_TOKEN")
+    base_url = overrides.get("base_url") or cfg.get("base_url") or os.environ.get("COMETAPI_BASE_URL")
+
+    if not api_key:
+        raise ConfigMissing(
+            "API key not configured. Set COMETAPI_KEY or run [bold]cometapi init[/bold].\n"
+            "Create one at: https://www.cometapi.com/console/token"
+        )
+
+    if require_access_token and not access_token:
+        raise ConfigMissing(
+            "Access token not configured. This command requires COMETAPI_ACCESS_TOKEN.\n"
+            "Run [bold]cometapi init[/bold] to configure, or set the environment variable.\n"
+            "Get one at: https://www.cometapi.com/console/personal"
+        )
+
+    return CometClient(
+        api_key=api_key,
+        access_token=access_token or None,
+        base_url=base_url or None,
+    )
+
+
+def get_default_model() -> str:
+    """Get the default model from config, env, or fallback."""
+    return get_value("default_model", env_var="COMETAPI_DEFAULT_MODEL", default="gpt-5.4")

cometapi_cli/console.py

@@ -0,0 +1,8 @@
+"""Shared Rich console instances."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+console = Console()
+err_console = Console(stderr=True)

cometapi_cli/constants.py

@@ -0,0 +1,55 @@
+"""Shared constants and helpers for CometAPI CLI commands."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import typer
+
+# $1.00 USD = 500,000 quota units
+QUOTA_PER_UNIT = 500_000.0
+
+
+def quota_to_usd(quota: int | float, precision: int = 4) -> str:
+    """Convert backend quota units to a formatted USD string."""
+    if not quota:
+        return "$0.00"
+    return f"${quota / QUOTA_PER_UNIT:,.{precision}f}"
+
+
+def format_ts(ts: int, fmt: str = "%Y-%m-%d %H:%M:%S") -> str:
+    """Format a Unix timestamp as UTC string."""
+    if not ts:
+        return "—"
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime(fmt)
+
+
+def parse_date(value: str, label: str) -> int:
+    """Parse a date string into a Unix timestamp (UTC).
+
+    Accepts YYYY-MM-DD, ISO 8601, or a raw Unix timestamp.
+    Exits with code 2 on invalid input.
+    """
+    if value.isdigit():
+        return int(value)
+    for date_fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            dt = datetime.strptime(value, date_fmt).replace(tzinfo=timezone.utc)
+            return int(dt.timestamp())
+        except ValueError:
+            continue
+    from .console import err_console
+
+    err_console.print(
+        f"[red]Invalid {label} date:[/] {value}. "
+        "Use YYYY-MM-DD, ISO 8601, or a Unix timestamp."
+    )
+    raise typer.Exit(code=2)
+
+
+def extract_items(resp: dict) -> list:
+    """Extract items from paginated or flat API response."""
+    data = resp.get("data", [])
+    if isinstance(data, dict):
+        return data.get("items", data.get("data", []))
+    return data

cometapi_cli/errors.py

@@ -0,0 +1,113 @@
+"""Error handling and exit codes for CometAPI CLI."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from enum import IntEnum
+from typing import Any, TypeVar
+
+import typer
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ExitCode(IntEnum):
+    """Unix sysexits.h-compatible exit codes."""
+
+    SUCCESS = 0
+    ERROR = 1
+    USAGE = 2
+    CONFIG_MISSING = 64
+    SERVICE_UNAVAILABLE = 69
+    AUTH_ERROR = 77
+    CONFIG_ERROR = 78
+
+
+class CometCLIError(Exception):
+    """Base exception for CLI errors with structured exit codes."""
+
+    def __init__(self, message: str, exit_code: ExitCode = ExitCode.ERROR):
+        self.message = message
+        self.exit_code = exit_code
+        super().__init__(message)
+
+
+class ConfigMissing(CometCLIError):
+    """Required configuration value is missing."""
+
+    def __init__(self, message: str):
+        super().__init__(message, ExitCode.CONFIG_MISSING)
+
+
+class ConfigError(CometCLIError):
+    """Configuration file is corrupt or unreadable."""
+
+    def __init__(self, message: str):
+        super().__init__(message, ExitCode.CONFIG_ERROR)
+
+
+class AuthError(CometCLIError):
+    """Authentication failed."""
+
+    def __init__(self, message: str):
+        super().__init__(message, ExitCode.AUTH_ERROR)
+
+
+class ServiceUnavailable(CometCLIError):
+    """API service is unreachable."""
+
+    def __init__(self, message: str):
+        super().__init__(message, ExitCode.SERVICE_UNAVAILABLE)
+
+
+def handle_errors(func: F) -> F:
+    """Decorator that catches exceptions and produces user-friendly error output."""
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        from .console import err_console
+
+        try:
+            return func(*args, **kwargs)
+        except CometCLIError as e:
+            err_console.print(f"[red bold]Error:[/] {e.message}")
+            raise typer.Exit(code=e.exit_code)
+        except KeyboardInterrupt:
+            err_console.print("\n[dim]Interrupted.[/]")
+            raise typer.Exit(code=130)
+        except (typer.Exit, typer.Abort, SystemExit):
+            raise
+        except Exception as e:
+            exc_type = type(e).__name__
+            msg = str(e)
+
+            if "AuthenticationError" in exc_type:
+                err_console.print(f"[red bold]Authentication failed:[/] {msg}")
+                err_console.print(
+                    "[dim]Check your COMETAPI_KEY or run [bold]cometapi init[/bold] to configure.[/]"
+                )
+                err_console.print(
+                    "[dim]Create a new key at: https://www.cometapi.com/console/token[/]"
+                )
+                raise typer.Exit(code=ExitCode.AUTH_ERROR)
+
+            if "APIConnectionError" in exc_type or "ConnectError" in exc_type:
+                err_console.print(f"[red bold]Connection failed:[/] {msg}")
+                err_console.print(
+                    "[dim]Check your network or run [bold]cometapi doctor[/bold] to diagnose.[/]"
+                )
+                raise typer.Exit(code=ExitCode.SERVICE_UNAVAILABLE)
+
+            if "api_key" in msg.lower() or "COMETAPI_KEY" in msg or "OPENAI_API_KEY" in msg:
+                err_console.print("[red bold]API key not configured.[/]")
+                err_console.print("[dim]Set COMETAPI_KEY or run [bold]cometapi init[/bold].[/]")
+                err_console.print(
+                    "[dim]Create one at: https://www.cometapi.com/console/token[/]"
+                )
+                raise typer.Exit(code=ExitCode.CONFIG_MISSING)
+
+            err_console.print(f"[red bold]Error:[/] {msg}")
+            raise typer.Exit(code=ExitCode.ERROR)
+
+    return wrapper  # type: ignore[return-value]

cometapi_cli/formatters.py

@@ -0,0 +1,156 @@
+"""Multi-format output rendering."""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any
+
+import typer
+from rich.table import Table
+
+from .console import console
+
+
+class OutputFormat(str, Enum):
+    """Supported output formats."""
+
+    TABLE = "table"
+    JSON = "json"
+    YAML = "yaml"
+    CSV = "csv"
+    MARKDOWN = "markdown"
+
+
+def resolve_format(
+    ctx: typer.Context,
+    json_output: bool = False,
+    output_format: OutputFormat | None = None,
+) -> OutputFormat:
+    """Resolve output format: per-command --json > per-command --format > global --format > config file."""
+    if json_output:
+        return OutputFormat.JSON
+    if output_format is not None:
+        return output_format
+    global_fmt = (ctx.obj or {}).get("format", None)
+    if global_fmt is not None:
+        return global_fmt
+    # Fall back to config file output_format
+    from .config import get_value
+
+    cfg_fmt = get_value("output_format")
+    if cfg_fmt:
+        try:
+            return OutputFormat(cfg_fmt)
+        except ValueError:
+            pass
+    return OutputFormat.TABLE
+
+
+def _render_json(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, default=str, indent=2))
+
+
+def _render_yaml(data: Any) -> None:
+    import yaml
+
+    print(yaml.dump(data, allow_unicode=True, default_flow_style=False).rstrip())
+
+
+def _render_csv(rows: Sequence[dict[str, Any]]) -> None:
+    if not rows:
+        return
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=list(rows[0].keys()))
+    writer.writeheader()
+    writer.writerows(rows)
+    print(buf.getvalue().rstrip())
+
+
+def _render_kv_table(data: dict[str, Any], title: str = "") -> None:
+    """Render a single dict as a Field/Value table."""
+    table = Table(title=title or None)
+    table.add_column("Field", style="cyan", no_wrap=True)
+    table.add_column("Value", style="green")
+    for key, value in data.items():
+        display_key = key.replace("_", " ").title()
+        table.add_row(display_key, str(value))
+    console.print(table)
+
+
+def _render_list_table(
+    rows: Sequence[dict[str, Any]],
+    title: str = "",
+    columns: dict[str, str] | None = None,
+) -> None:
+    """Render a list of dicts as a columnar table."""
+    if not rows:
+        console.print("[dim]No data.[/]")
+        return
+    if columns is None:
+        columns = {k: ("cyan" if i == 0 else "green") for i, k in enumerate(rows[0].keys())}
+    table = Table(title=title or None)
+    for col_name, style in columns.items():
+        table.add_column(col_name.replace("_", " ").title(), style=style, no_wrap=True)
+    for row in rows:
+        table.add_row(*(str(row.get(k, "")) for k in columns))
+    console.print(table)
+
+
+def _render_kv_markdown(data: dict[str, Any], title: str = "") -> None:
+    lines = []
+    if title:
+        lines.append(f"## {title}\n")
+    lines.append("| Field | Value |")
+    lines.append("| --- | --- |")
+    for key, value in data.items():
+        display_key = key.replace("_", " ").title()
+        lines.append(f"| {display_key} | {value} |")
+    print("\n".join(lines))
+
+
+def _render_list_markdown(rows: Sequence[dict[str, Any]], title: str = "") -> None:
+    if not rows:
+        return
+    headers = list(rows[0].keys())
+    lines = []
+    if title:
+        lines.append(f"## {title}\n")
+    lines.append("| " + " | ".join(h.replace("_", " ").title() for h in headers) + " |")
+    lines.append("| " + " | ".join("---" for _ in headers) + " |")
+    for row in rows:
+        lines.append("| " + " | ".join(str(row.get(h, "")) for h in headers) + " |")
+    print("\n".join(lines))
+
+
+def output(
+    data: Any,
+    fmt: OutputFormat,
+    title: str = "",
+    columns: dict[str, str] | None = None,
+) -> None:
+    """Dispatch data to the appropriate formatter.
+
+    - dict → rendered as key-value table (TABLE/MARKDOWN) or as-is (JSON/YAML/CSV)
+    - list[dict] → rendered as columnar table
+    """
+    if fmt == OutputFormat.JSON:
+        _render_json(data)
+    elif fmt == OutputFormat.YAML:
+        _render_yaml(data)
+    elif fmt == OutputFormat.CSV:
+        rows = [data] if isinstance(data, dict) else data
+        _render_csv(rows)
+    elif fmt == OutputFormat.MARKDOWN:
+        if isinstance(data, dict):
+            _render_kv_markdown(data, title)
+        else:
+            _render_list_markdown(data, title)
+    else:  # TABLE
+        if isinstance(data, dict):
+            _render_kv_table(data, title)
+        else:
+            _render_list_table(data, title, columns)

cometapi_cli/main.py

@@ -0,0 +1,8 @@
+"""Backward compatibility — use cometapi_cli.app instead."""
+
+from cometapi_cli.app import app  # noqa: F401
+
+__all__ = ["app"]
+
+if __name__ == "__main__":
+    app()