tokenroute 0.1.0__py3-none-any.whl

tokenroute-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: tokenroute
+Version: 0.1.0
+Summary: Agent-first CLI for tokenroute — OpenAI-compatible LLM gateway with smart routing and transparent billing
+Project-URL: Homepage, https://tokenroute.io
+Project-URL: Documentation, https://docs.tokenroute.io
+Project-URL: Repository, https://github.com/jiangjin11/tokenroute
+Author: Paradigx Pte Ltd
+License: MIT
+Keywords: agent,ai,anthropic,cli,gateway,llm,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13.0
+Requires-Dist: typer<1.0,>=0.15
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tokenroute (Python CLI)
+
+Agent-first CLI for [tokenroute](https://tokenroute.io) — the OpenAI-compatible LLM API gateway with smart routing and transparent token billing.
+
+## Install
+
+```bash
+pip install tokenroute
+# or, run once without installing:
+uvx tokenroute --help
+pipx run tokenroute --help
+```
+
+## Quickstart
+
+```bash
+tokenroute login                                 # OAuth device-flow, opens browser
+tokenroute whoami                                # current user + balance
+tokenroute keys create --name my-app             # create new sk-tr-* key
+tokenroute balance                               # current credit
+```
+
+All commands accept `--json` (or env `TOKENROUTE_JSON=1`) for machine-parseable output that's friendly to agents and CI.
+
+## Agent / sub-agent usage (no interactive login)
+
+For automation, skip `tokenroute login` and call the OpenAI-compatible API directly with a pre-issued key:
+
+```bash
+export TOKENROUTE_API_KEY=sk-tr-...
+curl https://api.tokenroute.io/v1/chat/completions \
+  -H "Authorization: Bearer $TOKENROUTE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `TOKENROUTE_API_URL` | `https://api.tokenroute.io` | Override gateway base URL |
+| `TOKENROUTE_API_KEY` | _(unset)_ | sk-tr-* key for LLM calls — skips `login` |
+| `TOKENROUTE_JSON` | _(unset)_ | Set to `1` to force JSON output globally |
+
+Credentials from `tokenroute login` are stored at `~/.tokenroute/credentials.json` (owner-readable only on POSIX).
+
+## License
+
+MIT

tokenroute-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tokenroute_cli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+tokenroute_cli/__main__.py,sha256=T9u3jQJMW6dSUO-GZMlpjQcelPjOzhFLezZv9FOIiz4,10332
+tokenroute_cli/client.py,sha256=g0bSFiN3aXi2rEb8ku40-VmDJUXv60uDqDClahlcn80,2077
+tokenroute_cli/config.py,sha256=JSM4ZHQlbrSaFS6LGGarGuauEQ_9ezYIqiAqDE_gINU,3726
+tokenroute_cli/device_flow.py,sha256=s1mlTbMqge24rgnRT-TFyh1xU8XRrB9EvqJP4E8UzJ4,4241
+tokenroute_cli/output.py,sha256=COk7Ah5GfszxCdFPWJX7x_Ffl1ungLGqVkgCricx4xU,1825
+tokenroute-0.1.0.dist-info/METADATA,sha256=01h7V9LWmg7tnScHtVdvSwyMd1HyFU6L-hmt364Zw30,2817
+tokenroute-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tokenroute-0.1.0.dist-info/entry_points.txt,sha256=fEOMYzeUq6-96SxJq0koCld65Ojf138yKWmeTYa0DSg,59
+tokenroute-0.1.0.dist-info/RECORD,,

tokenroute-0.1.0.dist-info/WHEEL

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

tokenroute-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tokenroute = tokenroute_cli.__main__:app

tokenroute_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tokenroute_cli/__main__.py

@@ -0,0 +1,334 @@
+"""tokenroute CLI entry point.
+
+  tokenroute login                          # OAuth device-flow
+  tokenroute logout
+  tokenroute whoami                         # user + balance
+  tokenroute balance
+  tokenroute keys create --name <n>
+  tokenroute keys list
+  tokenroute keys revoke <id>
+
+All commands accept `--json` (or env TOKENROUTE_JSON=1) for agent-friendly
+machine-parseable output. Authentication: `tokenroute login` writes
+~/.tokenroute/credentials.json; subsequent commands re-use it.
+"""
+from __future__ import annotations
+
+import os
+import time
+
+import typer
+
+from . import __version__
+from .client import ApiError, request
+from .config import (
+    Credentials,
+    api_url,
+    clear_credentials,
+    resolve_api_key,
+    save_credentials,
+    save_last_key,
+)
+from .device_flow import fetch_discovery, open_browser, poll_for_token, request_device_code
+from .output import emit, error, info, success
+
+app = typer.Typer(
+    name="tokenroute",
+    help="Agent-first CLI for tokenroute LLM gateway.",
+    add_completion=False,
+    no_args_is_help=True,
+)
+keys_app = typer.Typer(name="keys", help="Manage your tokenroute API keys.", no_args_is_help=True)
+app.add_typer(keys_app, name="keys")
+
+
+def _global_callback(
+    json_output: bool = typer.Option(
+        False, "--json", help="Machine-parseable JSON output (for agents / scripts)."
+    ),
+) -> None:
+    if json_output or os.environ.get("TOKENROUTE_JSON") == "1":
+        os.environ["_TOKENROUTE_OUTPUT_JSON"] = "1"
+
+
+app.callback()(_global_callback)
+
+
+# ─── login / logout / whoami ─────────────────────────────────────────
+
+
+@app.command()
+def login() -> None:
+    """Log in via OAuth device-flow (opens browser)."""
+    try:
+        disc = fetch_discovery()
+    except Exception as e:
+        error(f"could not reach tokenroute API: {e}", code=2)
+
+    try:
+        code = request_device_code(disc)
+    except Exception as e:
+        error(f"device-flow init failed: {e}", code=3)
+
+    info(f"\nVisit: [bold cyan]{code.verification_uri}[/bold cyan]")
+    info(f"And enter code: [bold yellow]{code.user_code}[/bold yellow]\n")
+    info("(opening browser automatically — if it doesn't, use the URL above)")
+    open_browser(code.verification_uri_complete)
+
+    info("Waiting for authorization...")
+    try:
+        token = poll_for_token(disc, code)
+    except RuntimeError as e:
+        error(str(e), code=3)
+
+    expires_at = int(time.time()) + int(token.get("expires_in", 3600))
+    save_credentials(
+        Credentials(
+            access_token=token["access_token"],
+            refresh_token=token.get("refresh_token"),
+            expires_at=expires_at,
+            issuer=disc.issuer,
+            client_id=disc.client_id,
+        )
+    )
+    success("logged in")
+
+
+@app.command()
+def logout() -> None:
+    """Forget locally stored credentials."""
+    if clear_credentials():
+        success("logged out")
+    else:
+        info("(no stored credentials)")
+
+
+@app.command()
+def whoami() -> None:
+    """Show current user + balance."""
+    try:
+        me = request("GET", "/api/v1/me")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(me)
+
+
+@app.command()
+def balance() -> None:
+    """Show available credit balance."""
+    try:
+        body = request("GET", "/api/v1/balance")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(body)
+
+
+# ─── keys subcommands ────────────────────────────────────────────────
+
+
+@keys_app.command("create")
+def keys_create(
+    name: str = typer.Option(..., "--name", "-n", help="Human-friendly key label."),
+    no_cache: bool = typer.Option(
+        False, "--no-cache", help="Don't save raw key to ~/.tokenroute/last_key.txt"
+    ),
+) -> None:
+    """Create a new sk-tr-* API key. The raw key is shown ONCE."""
+    try:
+        out = request("POST", "/api/v1/me/keys", json_body={"name": name})
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    raw = out.get("raw")
+    if raw and not no_cache:
+        save_last_key(raw)
+    emit(out)
+    if not os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        info("\n[yellow]Save the `raw` key — it won't be shown again.[/yellow]")
+        if raw and not no_cache:
+            info(
+                "[dim]Cached at ~/.tokenroute/last_key.txt for `env` / `test` / `models`. "
+                "Pass --no-cache to skip.[/dim]"
+            )
+
+
+# ─── topup / test / env / usage / models ─────────────────────────────
+
+
+@app.command()
+def topup(
+    amount: float = typer.Option(
+        ..., "--amount", "-a", help="USD amount to top up (>= 1).", min=1.0
+    ),
+    open_url: bool = typer.Option(
+        True, "--open/--no-open", help="Open the Stripe Checkout page in browser."
+    ),
+) -> None:
+    """Get a Stripe Checkout URL to add credit. Agents must NOT auto-pay."""
+    try:
+        out = request("POST", "/api/v1/topup", json_body={"amount_usd": str(amount)})
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(out)
+    url = out.get("checkout_url")
+    if url and open_url and not os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        info(f"\nOpening browser: {url}")
+        open_browser(url)
+
+
+@app.command()
+def usage(
+    days: int = typer.Option(30, "--days", "-d", help="Look-back window in days.", min=1, max=365),
+) -> None:
+    """Summary spend over the last N days."""
+    try:
+        body = request("GET", f"/api/v1/me/usage?days={days}")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(body)
+
+
+@app.command(name="env")
+def env_cmd(
+    key: str = typer.Option(
+        None,
+        "--key",
+        "-k",
+        help="Override API key (default: env TOKENROUTE_API_KEY or last cached).",
+    ),
+) -> None:
+    """Print OPENAI_API_KEY + OPENAI_BASE_URL for shell sourcing.
+
+    Usage:  tokenroute env >> .env
+    """
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first, "
+            "or set TOKENROUTE_API_KEY env var",
+            code=1,
+        )
+    base = f"{api_url()}/v1"
+    if os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        emit({"OPENAI_API_KEY": raw, "OPENAI_BASE_URL": base})
+        return
+    # Plain printf — must work in `>> .env` redirection. No rich formatting.
+    print(f"OPENAI_API_KEY={raw}")
+    print(f"OPENAI_BASE_URL={base}")
+
+
+@app.command()
+def test(
+    model: str = typer.Option(
+        "openai/gpt-4o-mini", "--model", "-m", help="Model id to test against."
+    ),
+    key: str = typer.Option(
+        None, "--key", "-k", help="Override API key (default: cached / env)."
+    ),
+) -> None:
+    """Send a tiny chat completion to verify the gateway + your key work."""
+    import httpx
+
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first",
+            code=1,
+        )
+    url = f"{api_url()}/v1/chat/completions"
+    body = {
+        "model": model,
+        "messages": [{"role": "user", "content": "Reply with the single word 'OK'."}],
+        "max_tokens": 8,
+    }
+    try:
+        with httpx.Client(timeout=30.0) as c:
+            r = c.post(url, json=body, headers={"Authorization": f"Bearer {raw}"})
+        if not r.is_success:
+            error(f"chat failed ({r.status_code}): {r.text}", code=1 if r.status_code < 500 else 3)
+        data = r.json()
+    except httpx.RequestError as e:
+        error(f"network error: {e}", code=2)
+    reply = data["choices"][0]["message"]["content"]
+    if os.environ.get("_TOKENROUTE_OUTPUT_JSON"):
+        emit({"ok": True, "model": data.get("model", model), "reply": reply})
+    else:
+        success(f"connected ({data.get('model', model)})")
+        info(f"  reply: [italic]{reply}[/italic]")
+
+
+@app.command(name="models")
+def models_cmd(
+    list_models: bool = typer.Option(
+        True, "--list/--no-list", help="(reserved — only `list` is implemented in Phase A)"
+    ),
+    key: str = typer.Option(
+        None, "--key", "-k", help="Override API key (default: cached / env)."
+    ),
+) -> None:
+    """List available models with pricing."""
+    import httpx
+
+    raw = key or resolve_api_key()
+    if not raw:
+        error(
+            "no API key available — run `tokenroute keys create --name <name>` first",
+            code=1,
+        )
+    try:
+        with httpx.Client(timeout=15.0) as c:
+            r = c.get(f"{api_url()}/v1/models", headers={"Authorization": f"Bearer {raw}"})
+        if not r.is_success:
+            error(f"models lookup failed ({r.status_code}): {r.text}", code=3)
+        items = r.json().get("data", [])
+    except httpx.RequestError as e:
+        error(f"network error: {e}", code=2)
+    emit(
+        items,
+        table_columns=[
+            ("ID", "id"),
+            ("Provider", "owned_by"),
+            ("Tier", "complexity_tier"),
+            ("$/1k in", "input_usd_per_1k"),
+            ("$/1k out", "output_usd_per_1k"),
+        ],
+    )
+
+
+@keys_app.command("list")
+def keys_list() -> None:
+    """List your API keys (raw values never shown)."""
+    try:
+        items = request("GET", "/api/v1/me/keys")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(
+        items,
+        table_columns=[
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Prefix", "key_prefix"),
+            ("Status", "status"),
+            ("Balance USD", "balance_usd"),
+            ("Created", "created_at"),
+        ],
+    )
+
+
+@keys_app.command("revoke")
+def keys_revoke(key_id: str = typer.Argument(..., help="Key id (uuid).")) -> None:
+    """Revoke an API key. Future calls with it return 401."""
+    try:
+        out = request("DELETE", f"/api/v1/me/keys/{key_id}")
+    except ApiError as e:
+        error(e.message, code=1 if e.status < 500 else 3)
+    emit(out)
+
+
+@app.command()
+def version() -> None:
+    """Print CLI version."""
+    emit({"version": __version__})
+
+
+if __name__ == "__main__":
+    app()

tokenroute_cli/client.py

@@ -0,0 +1,74 @@
+"""Thin httpx wrapper for hitting the tokenroute gateway API.
+
+For /api/v1/me* and /api/v1/topup we send the saved Logto JWT as Bearer.
+For /v1/* (OpenAI-compatible chat etc.) we send the sk-tr-* API key instead.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .config import Credentials, api_url, load_credentials
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, message: str, body: Any = None):
+        super().__init__(f"HTTP {status}: {message}")
+        self.status = status
+        self.message = message
+        self.body = body
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "User-Agent": f"tokenroute-cli/{__version__}",
+        "Accept": "application/json",
+    }
+
+
+def _require_login() -> Credentials:
+    creds = load_credentials()
+    if creds is None or not creds.access_token:
+        raise ApiError(401, "not logged in — run `tokenroute login` first")
+    return creds
+
+
+def _raise(resp: httpx.Response) -> None:
+    if resp.is_success:
+        return
+    try:
+        body = resp.json()
+    except (ValueError, httpx.DecodingError):
+        body = resp.text
+    if isinstance(body, dict):
+        msg = (
+            body.get("error", {}).get("message")
+            if isinstance(body.get("error"), dict)
+            else body.get("detail") or body.get("error") or resp.reason_phrase
+        )
+    else:
+        msg = resp.reason_phrase
+    raise ApiError(resp.status_code, str(msg), body)
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    json_body: Any | None = None,
+    auth_jwt: bool = True,
+    timeout: float = 30.0,
+) -> Any:
+    headers = _default_headers()
+    if auth_jwt:
+        creds = _require_login()
+        headers["Authorization"] = f"Bearer {creds.access_token}"
+    url = f"{api_url()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.request(method, url, json=json_body, headers=headers)
+    _raise(resp)
+    if resp.status_code == 204 or not resp.content:
+        return None
+    return resp.json()

tokenroute_cli/config.py

@@ -0,0 +1,133 @@
+"""Local config and credential storage for the CLI.
+
+Credentials live at `~/.tokenroute/credentials.json` (owner-readable only
+on POSIX). We don't use the OS keychain in Phase A — adds platform-specific
+deps for marginal benefit; revisit in Phase B if users complain.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_API_URL = "https://api.tokenroute.io"
+
+
+def api_url() -> str:
+    return os.environ.get("TOKENROUTE_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def static_api_key() -> str | None:
+    """If set, CLI uses it as Bearer for /v1/* (LLM) calls.
+
+    For /api/v1/me* endpoints this is NOT applicable — those need a Logto
+    JWT. CI / sub-agent flows that only need to *call* the LLM gateway
+    (not manage account) should set this and skip `tokenroute login`.
+    """
+    return os.environ.get("TOKENROUTE_API_KEY")
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".tokenroute"
+
+
+def _creds_path() -> Path:
+    return _config_dir() / "credentials.json"
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str | None = None
+    expires_at: int | None = None  # unix seconds
+    issuer: str | None = None
+    client_id: str | None = None
+
+
+def load_credentials() -> Credentials | None:
+    p = _creds_path()
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    return Credentials(
+        access_token=data.get("access_token", ""),
+        refresh_token=data.get("refresh_token"),
+        expires_at=data.get("expires_at"),
+        issuer=data.get("issuer"),
+        client_id=data.get("client_id"),
+    )
+
+
+def save_credentials(creds: Credentials) -> Path:
+    d = _config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _creds_path()
+    p.write_text(
+        json.dumps(
+            {
+                "access_token": creds.access_token,
+                "refresh_token": creds.refresh_token,
+                "expires_at": creds.expires_at,
+                "issuer": creds.issuer,
+                "client_id": creds.client_id,
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    # Owner-only read/write on POSIX. On Windows chmod is mostly a no-op
+    # but doesn't error, so we just call it unconditionally.
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+    return p
+
+
+def clear_credentials() -> bool:
+    p = _creds_path()
+    if p.exists():
+        p.unlink()
+        return True
+    return False
+
+
+# ─── last-created raw key cache ────────────────────────────────────
+#
+# `keys create` returns a raw sk-tr-* once and never again. We optionally
+# cache it locally so `env` / `test` / `models` can use it without the
+# user having to copy-paste. Users who don't want the cache pass
+# `--no-cache` to `keys create` (Phase B).
+
+
+def _last_key_path() -> Path:
+    return _config_dir() / "last_key.txt"
+
+
+def save_last_key(raw_key: str) -> Path:
+    d = _config_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    p = _last_key_path()
+    p.write_text(raw_key, encoding="utf-8")
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)
+    except OSError:
+        pass
+    return p
+
+
+def load_last_key() -> str | None:
+    p = _last_key_path()
+    if not p.exists():
+        return None
+    return p.read_text(encoding="utf-8").strip() or None
+
+
+def resolve_api_key() -> str | None:
+    """For `test` / `env` / `models`: prefer env var, then cached last key."""
+    return static_api_key() or load_last_key()

tokenroute_cli/device_flow.py

@@ -0,0 +1,132 @@
+"""OIDC device-flow client — talks directly to Logto.
+
+Discovery happens via tokenroute gateway (`/api/v1/auth/discovery`), so
+the CLI doesn't hardcode any Logto URL or client_id. After polling
+succeeds we hand the access_token back to the caller, who saves it via
+`config.save_credentials`.
+"""
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+
+import httpx
+
+from .config import api_url
+
+# Per RFC 8628 §3.5 we honor the server's `interval` field; this is just
+# a sane floor in case the server returns 0 or omits it.
+_MIN_POLL_INTERVAL_SECONDS = 5
+
+
+@dataclass
+class DiscoveryInfo:
+    issuer: str
+    client_id: str
+    resource: str
+    scopes: list[str]
+    device_authorization_endpoint: str
+    token_endpoint: str
+
+
+@dataclass
+class DeviceCodeResponse:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+def fetch_discovery() -> DiscoveryInfo:
+    """GET tokenroute /api/v1/auth/discovery."""
+    with httpx.Client(timeout=10.0) as c:
+        r = c.get(f"{api_url()}/api/v1/auth/discovery")
+    r.raise_for_status()
+    data = r.json()
+    return DiscoveryInfo(
+        issuer=data["issuer"],
+        client_id=data["client_id"],
+        resource=data["resource"],
+        scopes=data["scopes"],
+        device_authorization_endpoint=data["device_authorization_endpoint"],
+        token_endpoint=data["token_endpoint"],
+    )
+
+
+def request_device_code(disc: DiscoveryInfo) -> DeviceCodeResponse:
+    """POST {device_authorization_endpoint} → device_code + user_code."""
+    with httpx.Client(timeout=10.0) as c:
+        r = c.post(
+            disc.device_authorization_endpoint,
+            data={
+                "client_id": disc.client_id,
+                "scope": " ".join(disc.scopes),
+                "resource": disc.resource,
+            },
+        )
+    r.raise_for_status()
+    body = r.json()
+    return DeviceCodeResponse(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri=body["verification_uri"],
+        verification_uri_complete=body.get(
+            "verification_uri_complete", body["verification_uri"]
+        ),
+        expires_in=body["expires_in"],
+        interval=max(body.get("interval", 5), _MIN_POLL_INTERVAL_SECONDS),
+    )
+
+
+def open_browser(url: str) -> bool:
+    """Best-effort. False if no display / headless environment."""
+    try:
+        return webbrowser.open(url)
+    except webbrowser.Error:
+        return False
+
+
+def poll_for_token(
+    disc: DiscoveryInfo,
+    code: DeviceCodeResponse,
+    *,
+    on_pending=None,
+) -> dict:
+    """Poll {token_endpoint} until success / expired / denied.
+
+    Returns the raw token response dict (access_token / refresh_token / ...).
+    Raises RuntimeError with a human-readable message on failure.
+    """
+    deadline = time.time() + code.expires_in
+    interval = code.interval
+    with httpx.Client(timeout=10.0) as client:
+        while time.time() < deadline:
+            time.sleep(interval)
+            r = client.post(
+                disc.token_endpoint,
+                data={
+                    "client_id": disc.client_id,
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": code.device_code,
+                    "resource": disc.resource,
+                },
+            )
+            if r.is_success:
+                return r.json()
+            err = r.json().get("error") if r.headers.get("content-type", "").startswith("application/json") else None
+            if err == "authorization_pending":
+                if on_pending is not None:
+                    on_pending()
+                continue
+            if err == "slow_down":
+                interval += 5
+                continue
+            if err == "expired_token":
+                raise RuntimeError("device code expired — run `tokenroute login` again")
+            if err == "access_denied":
+                raise RuntimeError("login denied by user")
+            raise RuntimeError(f"token exchange failed ({r.status_code}): {r.text}")
+    raise RuntimeError("device code expired before user completed login")

tokenroute_cli/output.py

@@ -0,0 +1,65 @@
+"""Output helpers — toggle between human-friendly rich tables and --json."""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+_console = Console()
+_err_console = Console(stderr=True)
+
+
+def is_json_mode() -> bool:
+    """`--json` is set globally via env var (set by Typer callback)."""
+    import os
+
+    return os.environ.get("_TOKENROUTE_OUTPUT_JSON") == "1"
+
+
+def emit(payload: Any, *, table_columns: list[tuple[str, str]] | None = None) -> None:
+    """Print `payload` either as JSON (agent mode) or a rich table (human mode).
+
+    `table_columns` is a list of `(header, dict_key)` pairs. When None, we
+    fall back to JSON output even in human mode (e.g. for single objects
+    that don't fit a table).
+    """
+    if is_json_mode():
+        print(json.dumps(payload, indent=2, default=str))
+        return
+
+    if isinstance(payload, list) and table_columns:
+        table = Table(show_header=True, header_style="bold")
+        for header, _ in table_columns:
+            table.add_column(header)
+        for row in payload:
+            table.add_row(*[str(row.get(k, "")) for _, k in table_columns])
+        _console.print(table)
+        return
+
+    if isinstance(payload, dict):
+        for k, v in payload.items():
+            _console.print(f"[bold]{k}[/bold]: {v}")
+        return
+
+    _console.print(payload)
+
+
+def info(msg: str) -> None:
+    if not is_json_mode():
+        _console.print(msg)
+
+
+def success(msg: str) -> None:
+    if not is_json_mode():
+        _console.print(f"[green]✓[/green] {msg}")
+
+
+def error(msg: str, *, code: int = 1) -> None:
+    if is_json_mode():
+        print(json.dumps({"error": msg}, indent=2))
+    else:
+        _err_console.print(f"[red]error[/red]: {msg}")
+    sys.exit(code)