avios-cli 0.1.0__py3-none-any.whl

avios/__init__.py

@@ -0,0 +1,6 @@
+"""avios — a CLI and TUI for avios.com.
+
+View your Avios balance, transactions and account details from the terminal.
+"""
+
+__version__ = "0.1.0"

avios/auth.py

@@ -0,0 +1,121 @@
+"""Browser-assisted login for avios.
+
+avios.com has no plain credential API: login is Auth0 "Universal Login" guarded by
+hCaptcha, Akamai Bot Manager and SMS/passkey MFA, so there is no way to POST a
+username/password over HTTP and obtain a session. Instead we let a real browser
+handle the login once and capture the resulting session cookie.
+
+Two strategies, both requiring the optional ``login`` extra
+(``pip install "avios-cli[login]"``):
+
+- :func:`login_via_browser` — open a Playwright browser, the user logs in
+  (password + captcha + MFA), and we grab the cookies. Also needs
+  ``playwright install chromium``.
+- :func:`import_from_browser` — read the avios.com cookie straight out of a
+  running browser via ``browser_cookie3`` (no popup) if already logged in there.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol
+
+from avios.session import Session
+
+DASHBOARD_PATH = "/manage-avios/dashboard"
+LOGIN_TIMEOUT_MS = 300_000  # 5 minutes to complete password + captcha + MFA
+SUPPORTED_BROWSERS = ("chrome", "firefox", "edge", "brave", "safari", "chromium")
+
+
+class LoginError(RuntimeError):
+    """Login could not be completed."""
+
+
+class _RawCookie(Protocol):
+    name: str
+    value: str
+    domain: str
+
+
+def _to_cookie_dicts(raw: Iterable[_RawCookie]) -> list[dict[str, Any]]:
+    """Convert browser_cookie3 / cookiejar entries to our stored cookie format."""
+    return [{"name": c.name, "value": c.value, "domain": c.domain} for c in raw]
+
+
+def _only_avios(cookies: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [c for c in cookies if "avios.com" in c.get("domain", "")]
+
+
+def login_via_browser(
+    session: Session | None = None,
+    *,
+    headless: bool = False,
+    timeout_ms: int = LOGIN_TIMEOUT_MS,
+) -> int:
+    """Open a browser, wait for the user to log in, and save the session cookie.
+
+    Returns the number of avios.com cookies captured.
+    """
+    session = session or Session()
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:
+        raise LoginError(
+            'Playwright is required. Install with: pip install "avios-cli[login]" '
+            "then: playwright install chromium"
+        ) from exc
+
+    base_url = session.settings.base_url
+    with sync_playwright() as pw:  # pragma: no cover - requires a real browser
+        browser = pw.chromium.launch(headless=headless)
+        ctx = browser.new_context(user_agent=session.settings.user_agent)
+        page = ctx.new_page()
+        page.goto(f"{base_url}{DASHBOARD_PATH}")
+        try:
+            page.wait_for_url("**/manage-avios/**", timeout=timeout_ms)
+            page.wait_for_timeout(1500)  # let the session cookie settle
+        except Exception as exc:
+            browser.close()
+            raise LoginError("Did not reach the dashboard in time. Please try again.") from exc
+        cookies = list(ctx.cookies())
+        browser.close()
+
+    session.save_cookies(cookies)
+    return len(_only_avios(cookies))
+
+
+def _default_loader(browser: str) -> Callable[[], Iterable[_RawCookie]]:
+    """Return a callable that reads avios.com cookies from ``browser``."""
+    try:
+        import browser_cookie3 as bc3
+    except ImportError as exc:
+        raise LoginError(
+            'browser-cookie3 is required. Install with: pip install "avios-cli[login]"'
+        ) from exc
+    fn = getattr(bc3, browser, None)
+    if fn is None:
+        raise LoginError(
+            f"Unknown browser '{browser}'. Choose from: {', '.join(SUPPORTED_BROWSERS)}"
+        )
+    return lambda: fn(domain_name="avios.com")
+
+
+def import_from_browser(
+    session: Session | None = None,
+    browser: str = "chrome",
+    *,
+    loader: Callable[[], Iterable[_RawCookie]] | None = None,
+) -> int:
+    """Import the avios.com session cookie from a running browser.
+
+    Returns the number of avios.com cookies imported.
+    """
+    session = session or Session()
+    load = loader or _default_loader(browser)
+    cookies = _only_avios(_to_cookie_dicts(load()))
+    if not cookies:
+        raise LoginError(
+            f"No avios.com cookies found in {browser}. Log into avios.com there first."
+        )
+    session.save_cookies(cookies)
+    return len(cookies)

avios/cli.py

@@ -0,0 +1,231 @@
+"""Command-line interface for avios.
+
+Thin presentation layer: every command builds an :class:`~avios.client.AviosClient`,
+calls one method, and renders it with Rich (or raw JSON via ``--json``). Auth
+errors from the session layer are turned into friendly messages in one place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from avios import __version__
+from avios.auth import LoginError, import_from_browser, login_via_browser
+from avios.client import AviosClient
+from avios.models import Balance
+from avios.session import NotAuthenticated, Session, SessionExpired
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="avios — view your Avios balance and transactions from the terminal.",
+)
+console = Console()
+
+JSON_OPTION = typer.Option(False, "--json", help="Output raw JSON instead of a table.")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"avios {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """avios — a CLI and TUI for avios.com."""
+
+
+# -- helpers -----------------------------------------------------------------
+def _client() -> AviosClient:
+    return AviosClient(Session())
+
+
+@contextmanager
+def _handle_errors() -> Iterator[None]:
+    """Turn session/HTTP errors into friendly messages + exit codes."""
+    try:
+        yield
+    except NotAuthenticated as exc:
+        console.print("[red]Not logged in.[/] Run [bold]avios login[/].")
+        raise typer.Exit(1) from exc
+    except SessionExpired as exc:
+        console.print("[red]Session expired.[/] Run [bold]avios login[/] again.")
+        raise typer.Exit(2) from exc
+    except httpx.HTTPError as exc:
+        console.print(f"[red]Request failed:[/] {exc}")
+        raise typer.Exit(1) from exc
+
+
+def _print_json(data: Any) -> None:
+    console.print_json(data=data)
+
+
+def _render_records(records: list[dict[str, Any]], title: str) -> None:
+    if not records:
+        console.print(f"[dim]No {title.lower()}.[/]")
+        return
+    keys = [k for k, v in records[0].items() if not isinstance(v, dict | list)][:6]
+    table = Table(title=title)
+    for key in keys:
+        table.add_column(key)
+    for record in records:
+        table.add_row(*[str(record.get(key, "")) for key in keys])
+    console.print(table)
+
+
+# -- auth commands -----------------------------------------------------------
+@app.command()
+def login(
+    from_browser: bool = typer.Option(
+        False, "--from-browser", help="Import the cookie from a running browser (no popup)."
+    ),
+    browser: str = typer.Option("chrome", help="Browser to import from (with --from-browser)."),
+    headless: bool = typer.Option(
+        False, help="Run the login browser headless (only works without captcha/MFA)."
+    ),
+) -> None:
+    """Log in to avios.com (opens a browser once; captures your session cookie)."""
+    session = Session()
+    try:
+        if from_browser:
+            count = import_from_browser(session, browser)
+        else:
+            console.print(
+                "Opening a browser — log in normally (password, captcha, SMS code). "
+                "I'll capture the session once you reach the dashboard."
+            )
+            count = login_via_browser(session, headless=headless)
+    except LoginError as exc:
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
+
+    console.print(f"[green]Logged in.[/] Saved {count} avios cookie(s).")
+    try:
+        balance = AviosClient(session).get_balance()
+        console.print(
+            f"[green]✓ Session works.[/] Balance: [bold cyan]{balance.balance:,}[/] Avios"
+        )
+    except (NotAuthenticated, SessionExpired, httpx.HTTPError) as exc:
+        console.print(f"[yellow]Saved, but a test call failed:[/] {exc}")
+
+
+@app.command()
+def logout() -> None:
+    """Remove the stored session."""
+    Session().clear()
+    console.print("[green]Logged out.[/]")
+
+
+# -- data commands -----------------------------------------------------------
+@app.command()
+def balance(json_out: bool = JSON_OPTION) -> None:
+    """Show your Avios balance."""
+    with _handle_errors():
+        result = _client().get_balance()
+    if json_out:
+        _print_json(result.as_dict())
+        return
+    _render_balance(result)
+
+
+def _render_balance(result: Balance) -> None:
+    table = Table(show_header=False, box=None)
+    table.add_row("[bold]Avios[/]", f"[bold cyan]{result.balance:,}[/]")
+    if result.household_avios_balance is not None:
+        table.add_row("Household", f"{result.household_avios_balance:,}")
+    console.print(table)
+
+
+@app.command()
+def transactions(
+    limit: int = typer.Option(20, help="Number of transactions to show."),
+    json_out: bool = JSON_OPTION,
+) -> None:
+    """List recent Avios transactions."""
+    with _handle_errors():
+        items = _client().get_transactions(limit=limit)
+    records = [item.as_dict() for item in items]
+    if json_out:
+        _print_json(records)
+        return
+    _render_records(records, "Transactions")
+
+
+@app.command()
+def pending(json_out: bool = JSON_OPTION) -> None:
+    """List pending Avios transactions."""
+    with _handle_errors():
+        items = _client().get_pending_transactions()
+    records = [item.as_dict() for item in items]
+    if json_out:
+        _print_json(records)
+        return
+    _render_records(records, "Pending")
+
+
+@app.command()
+def accounts(json_out: bool = JSON_OPTION) -> None:
+    """List linked loyalty accounts."""
+    with _handle_errors():
+        items = _client().get_accounts()
+    records = [item.as_dict() for item in items]
+    if json_out:
+        _print_json(records)
+        return
+    _render_records(records, "Accounts")
+
+
+@app.command()
+def overview() -> None:
+    """Show the dashboard overview (raw JSON; shape not yet finalised)."""
+    with _handle_errors():
+        result = _client().get_overview()
+    _print_json(result.as_dict())
+
+
+@app.command()
+def whoami() -> None:
+    """Show your profile (raw JSON; shape not yet finalised)."""
+    with _handle_errors():
+        result = _client().get_profile()
+    _print_json(result.as_dict())
+
+
+@app.command()
+def raw(path: str) -> None:
+    """Fetch any endpoint directly and print the response."""
+    with _handle_errors():
+        data = _client().raw(path)
+    if isinstance(data, str):
+        console.print(data)
+    else:
+        _print_json(data)
+
+
+@app.command()
+def tui() -> None:
+    """Launch the full-screen dashboard."""
+    from avios.tui.app import run
+
+    run()
+
+
+if __name__ == "__main__":
+    app()

avios/client.py

@@ -0,0 +1,63 @@
+"""High-level, typed client for the avios.com internal API.
+
+:class:`AviosClient` wraps a :class:`~avios.session.Session` and returns pydantic
+models. Session/expiry errors from the session layer propagate unchanged so the
+CLI/TUI can render a single, friendly "please log in again" message.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from avios import endpoints
+from avios.models import Account, Balance, Overview, Profile, Transaction
+from avios.session import Session
+
+
+def _extract_list(payload: Any) -> list[dict[str, Any]]:
+    """Return the list of items from a payload.
+
+    Handles both a bare JSON array and an object that wraps the array under some
+    key (e.g. ``{"transactions": [...]}``). Returns ``[]`` if none is found.
+    """
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        for value in payload.values():
+            if isinstance(value, list):
+                return value
+    return []
+
+
+class AviosClient:
+    """Typed access to a user's Avios account."""
+
+    def __init__(self, session: Session | None = None) -> None:
+        self.session = session or Session()
+
+    def get_balance(self) -> Balance:
+        return Balance.model_validate(self.session.get_json(endpoints.BALANCE))
+
+    def get_profile(self) -> Profile:
+        return Profile.model_validate(self.session.get_json(endpoints.PROFILE))
+
+    def get_overview(self) -> Overview:
+        return Overview.model_validate(self.session.get_json(endpoints.OVERVIEW))
+
+    def get_accounts(self) -> list[Account]:
+        payload = self.session.get_json(endpoints.ACCOUNTS)
+        return [Account.model_validate(item) for item in _extract_list(payload)]
+
+    def get_transactions(self, limit: int | None = None) -> list[Transaction]:
+        payload = self.session.get_json(endpoints.TRANSACTIONS)
+        items = _extract_list(payload)
+        transactions = [Transaction.model_validate(item) for item in items]
+        return transactions[:limit] if limit is not None else transactions
+
+    def get_pending_transactions(self) -> list[Transaction]:
+        payload = self.session.get_json(endpoints.TRANSACTIONS_PENDING)
+        return [Transaction.model_validate(item) for item in _extract_list(payload)]
+
+    def raw(self, path: str) -> Any:
+        """Fetch an arbitrary endpoint (escape hatch), returning parsed JSON."""
+        return self.session.get_json(path if path.startswith("/") else f"/{path}")

avios/config.py

@@ -0,0 +1,51 @@
+"""Runtime configuration for avios.
+
+Settings are resolved from defaults and ``AVIOS_``-prefixed environment variables
+(e.g. ``AVIOS_BASE_URL``, ``AVIOS_CONFIG_DIR``). The session cookie itself is not
+stored here — see :mod:`avios.session`.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+DEFAULT_BASE_URL = "https://www.avios.com"
+
+# A realistic desktop-Chrome UA. The internal endpoints are cookie-authenticated
+# and don't sign requests, but sending a browser-like UA avoids trivial filtering.
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
+)
+
+
+def _default_config_dir() -> Path:
+    """Return the XDG config directory for avios (``~/.config/avios`` by default)."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "avios"
+
+
+class Settings(BaseSettings):
+    """Resolved runtime settings."""
+
+    model_config = SettingsConfigDict(env_prefix="AVIOS_", extra="ignore")
+
+    base_url: str = DEFAULT_BASE_URL
+    user_agent: str = DEFAULT_USER_AGENT
+    config_dir: Path = Field(default_factory=_default_config_dir)
+    request_timeout: float = 20.0
+
+    @property
+    def state_path(self) -> Path:
+        """Path to the saved session file (cookie jar)."""
+        return self.config_dir / "state.json"
+
+
+def get_settings() -> Settings:
+    """Build a fresh :class:`Settings` (reads the environment each call)."""
+    return Settings()

avios/endpoints.py

@@ -0,0 +1,18 @@
+"""avios.com internal API endpoint paths (relative to ``Settings.base_url``).
+
+These are the JSON endpoints the avios.com web app calls. They are cookie-
+authenticated and unofficial — see the README disclaimer.
+"""
+
+from __future__ import annotations
+
+# Confirmed lightweight balance endpoint used by the "spend Avios" area.
+BALANCE = "/en-GB/spend-avios/api/avios-balance"
+# Balance under the manage-avios API — kept as a fallback.
+BALANCE_ALT = "/manage-avios/api/user/current/balance"
+
+PROFILE = "/manage-avios/api/user/current"
+OVERVIEW = "/manage-avios/api/user/current/dashboard-overview"
+TRANSACTIONS = "/manage-avios/api/user/current/transactions"
+TRANSACTIONS_PENDING = "/manage-avios/api/user/current/transactions/pending"
+ACCOUNTS = "/shell/api/users/current/accounts"

avios/models.py

@@ -0,0 +1,51 @@
+"""Pydantic models for avios.com API payloads.
+
+Only :class:`Balance` has a fully-confirmed shape (observed in captured traffic).
+The remaining payloads were redacted in the capture, so their models keep
+``extra='allow'`` to preserve every field until concrete shapes are pinned from
+live responses. This means nothing is silently dropped and the client can already
+return typed objects today.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AviosModel(BaseModel):
+    """Base model: camelCase-JSON aware, forward-compatible with unknown fields."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    def as_dict(self) -> dict[str, Any]:
+        """Serialise back to the API's camelCase JSON shape."""
+        return self.model_dump(by_alias=True)
+
+
+class Balance(AviosModel):
+    """Avios balance (from ``/en-GB/spend-avios/api/avios-balance``)."""
+
+    balance: int
+    household_avios_balance: int | None = Field(default=None, alias="householdAviosBalance")
+
+
+class Transaction(AviosModel):
+    """A single Avios statement entry.
+
+    Concrete fields are pinned once live transaction payloads are observed; until
+    then every key is preserved via ``extra='allow'``.
+    """
+
+
+class Account(AviosModel):
+    """A linked loyalty account."""
+
+
+class Profile(AviosModel):
+    """The current user's profile."""
+
+
+class Overview(AviosModel):
+    """Dashboard overview summary."""

avios/session.py

@@ -0,0 +1,120 @@
+"""Session and cookie handling for avios.
+
+avios.com authenticates its internal JSON endpoints with a browser session cookie
+(no bearer token, no request signing). This module stores that cookie jar and
+builds pre-authenticated :class:`httpx.Client` instances. Acquiring the cookie in
+the first place (browser-assisted login) lives in :mod:`avios.auth`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from avios.config import Settings, get_settings
+
+
+class SessionError(RuntimeError):
+    """Base class for session problems."""
+
+
+class NotAuthenticated(SessionError):
+    """No stored session is available; the user must log in."""
+
+
+class SessionExpired(SessionError):
+    """The stored session is no longer valid; the user must log in again."""
+
+
+def cookie_header_from(cookies: list[dict[str, Any]]) -> str:
+    """Build a ``Cookie`` header from stored cookies, scoped to avios.com."""
+    return "; ".join(
+        f"{c['name']}={c['value']}" for c in cookies if "avios.com" in c.get("domain", "")
+    )
+
+
+class Session:
+    """Persisted avios session backed by a cookie jar on disk.
+
+    A ``transport`` may be injected for testing (e.g. ``httpx.MockTransport``).
+    The ``AVIOS_COOKIE`` environment variable, if set, overrides the stored jar
+    with a raw ``Cookie`` header string.
+    """
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        *,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.settings = settings or get_settings()
+        self._transport = transport
+
+    @property
+    def state_path(self) -> Path:
+        return self.settings.state_path
+
+    # -- cookie storage -------------------------------------------------------
+    def save_cookies(self, cookies: list[dict[str, Any]]) -> None:
+        """Persist a Playwright/browser-style cookie list to ``state.json`` (0600)."""
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        self.state_path.write_text(json.dumps({"cookies": cookies}))
+        self.state_path.chmod(0o600)
+
+    def load_cookies(self) -> list[dict[str, Any]]:
+        if not self.state_path.exists():
+            return []
+        data = json.loads(self.state_path.read_text())
+        cookies = data.get("cookies", [])
+        return cookies if isinstance(cookies, list) else []
+
+    def cookie_header(self) -> str:
+        env = os.environ.get("AVIOS_COOKIE")
+        if env:
+            return env.strip()
+        return cookie_header_from(self.load_cookies())
+
+    def is_authenticated(self) -> bool:
+        return bool(self.cookie_header())
+
+    def clear(self) -> None:
+        """Remove the stored session (logout)."""
+        self.state_path.unlink(missing_ok=True)
+
+    # -- HTTP -----------------------------------------------------------------
+    def client(self) -> httpx.Client:
+        """Return a pre-authenticated client. Raises :class:`NotAuthenticated`."""
+        cookie = self.cookie_header()
+        if not cookie:
+            raise NotAuthenticated("No saved session. Run `avios login` first.")
+        headers = {
+            "accept": "application/json, text/plain, */*",
+            "user-agent": self.settings.user_agent,
+            "referer": f"{self.settings.base_url}/manage-avios/dashboard",
+            "cookie": cookie,
+        }
+        return httpx.Client(
+            base_url=self.settings.base_url,
+            headers=headers,
+            timeout=self.settings.request_timeout,
+            follow_redirects=False,
+            transport=self._transport,
+        )
+
+    def get_json(self, path: str) -> Any:
+        """GET ``path`` and return parsed JSON.
+
+        A redirect to the auth gateway (301/302) or a 401 means the session is no
+        longer valid, surfaced as :class:`SessionExpired`.
+        """
+        with self.client() as client:
+            response = client.get(path)
+        if response.status_code in (301, 302, 401):
+            raise SessionExpired("Session expired. Run `avios login` again.")
+        response.raise_for_status()
+        ctype = response.headers.get("content-type", "")
+        return response.json() if "json" in ctype else response.text

avios/tui/__init__.py

@@ -0,0 +1,5 @@
+"""Textual TUI for avios."""
+
+from avios.tui.app import AviosApp, run
+
+__all__ = ["AviosApp", "run"]

avios/tui/app.py

@@ -0,0 +1,97 @@
+"""The avios Textual dashboard.
+
+A single screen: a balance header and a scrollable transactions table. Data is
+fetched off the event loop (the API client is synchronous httpx) via
+``asyncio.to_thread`` inside an exclusive worker, so the UI never blocks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+from textual import work
+from textual.app import App, ComposeResult
+from textual.widgets import DataTable, Footer, Header, Static
+
+from avios.client import AviosClient
+from avios.models import Transaction
+from avios.session import NotAuthenticated, Session, SessionExpired
+from avios.tui.art import banner_text
+from avios.tui.widgets import BalanceDisplay
+
+TRANSACTIONS_TO_SHOW = 50
+MAX_COLUMNS = 6
+
+
+class AviosApp(App[None]):
+    """Full-screen Avios dashboard."""
+
+    CSS_PATH = "styles.tcss"
+    TITLE = "avios"
+    SUB_TITLE = "your Avios, in the terminal"
+    BINDINGS = [
+        ("r", "refresh", "Refresh"),
+        ("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, client: AviosClient | None = None) -> None:
+        super().__init__()
+        self._client = client or AviosClient(Session())
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=True)
+        yield Static(banner_text(), id="banner")
+        yield BalanceDisplay("Loading…", id="balance")
+        yield DataTable(id="transactions", zebra_stripes=True, cursor_type="row")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#transactions", DataTable).loading = True
+        self.refresh_data()
+
+    def action_refresh(self) -> None:
+        self.query_one("#transactions", DataTable).loading = True
+        self.refresh_data()
+
+    @work(exclusive=True)
+    async def refresh_data(self) -> None:
+        await self._load()
+
+    async def _load(self) -> None:
+        try:
+            balance = await asyncio.to_thread(self._client.get_balance)
+            transactions = await asyncio.to_thread(
+                self._client.get_transactions, TRANSACTIONS_TO_SHOW
+            )
+        except (NotAuthenticated, SessionExpired) as exc:
+            self._show_error(f"{exc}  —  run `avios login`")
+            return
+        except httpx.HTTPError as exc:
+            self._show_error(f"Request failed: {exc}")
+            return
+        self.query_one("#balance", BalanceDisplay).update_balance(balance)
+        self._populate_transactions(transactions)
+
+    def _show_error(self, message: str) -> None:
+        self.query_one("#balance", BalanceDisplay).update_message(message, error=True)
+        self.query_one("#transactions", DataTable).loading = False
+
+    def _populate_transactions(self, transactions: list[Transaction]) -> None:
+        table = self.query_one("#transactions", DataTable)
+        table.loading = False
+        table.clear(columns=True)
+        records = [txn.as_dict() for txn in transactions]
+        if not records:
+            table.add_column("info")
+            table.add_row("No transactions")
+            return
+        keys = [k for k, v in records[0].items() if not isinstance(v, dict | list)][:MAX_COLUMNS]
+        table.add_columns(*keys)
+        for record in records:
+            table.add_row(*[str(record.get(key, "")) for key in keys])
+
+
+def run(client: AviosClient | None = None) -> None:
+    """Launch the dashboard."""
+    AviosApp(client=client).run()

avios/tui/art.py

@@ -0,0 +1,31 @@
+"""ASCII banner art for the TUI."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+# "AVIOS" in the figlet "ANSI Shadow" style.
+BANNER = r"""
+ █████╗ ██╗   ██╗██╗ ██████╗ ███████╗
+██╔══██╗██║   ██║██║██╔═══██╗██╔════╝
+███████║██║   ██║██║██║   ██║███████╗
+██╔══██║╚██╗ ██╔╝██║██║   ██║╚════██║
+██║  ██║ ╚████╔╝ ██║╚██████╔╝███████║
+╚═╝  ╚═╝  ╚═══╝  ╚═╝ ╚═════╝ ╚══════╝
+"""
+
+TAGLINE = "✈  your Avios, in the terminal"
+
+# Teal → blue gradient applied line by line (evokes the Avios/BA palette).
+_GRADIENT = ["#00d7af", "#00d7d7", "#00afd7", "#0087d7", "#005fd7", "#5f5fd7"]
+
+
+def banner_text() -> Text:
+    """Return the AVIOS banner as a colour-gradient Rich ``Text``."""
+    text = Text(justify="center")
+    lines = BANNER.strip("\n").splitlines()
+    for index, line in enumerate(lines):
+        color = _GRADIENT[min(index, len(_GRADIENT) - 1)]
+        text.append(line + "\n", style=f"bold {color}")
+    text.append(TAGLINE, style="italic #9e9e9e")
+    return text

avios/tui/styles.tcss

@@ -0,0 +1,21 @@
+Screen {
+    background: $surface;
+}
+
+#banner {
+    height: auto;
+    padding: 1 0 0 0;
+    content-align: center middle;
+    text-align: center;
+}
+
+#balance {
+    height: 3;
+    padding: 0 2;
+    content-align: left middle;
+    border-bottom: solid $primary;
+}
+
+#transactions {
+    height: 1fr;
+}

avios/tui/widgets.py

@@ -0,0 +1,30 @@
+"""Reusable TUI widgets."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.widgets import Static
+
+from avios.models import Balance
+
+
+class BalanceDisplay(Static):
+    """A one-line header showing the Avios balance (or a status message).
+
+    The rendered plain text is mirrored on :attr:`last_text` for easy assertions.
+    """
+
+    last_text: str = ""
+
+    def update_balance(self, balance: Balance) -> None:
+        text = Text()
+        text.append("Avios  ", style="bold")
+        text.append(f"{balance.balance:,}", style="bold cyan")
+        if balance.household_avios_balance is not None:
+            text.append(f"     Household  {balance.household_avios_balance:,}", style="dim")
+        self.last_text = text.plain
+        self.update(text)
+
+    def update_message(self, message: str, *, error: bool = False) -> None:
+        self.last_text = message
+        self.update(Text(message, style="bold red" if error else "dim"))

avios_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: avios-cli
+Version: 0.1.0
+Summary: A CLI and TUI for avios.com — view your Avios balance and transactions from the terminal.
+Project-URL: Homepage, https://github.com/alexechoi/avios-cli
+Project-URL: Repository, https://github.com/alexechoi/avios-cli
+Project-URL: Issues, https://github.com/alexechoi/avios-cli/issues
+Author: Alex Choi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: avios,british-airways,cli,loyalty,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: login
+Requires-Dist: browser-cookie3>=0.19; extra == 'login'
+Requires-Dist: playwright>=1.44; extra == 'login'
+Description-Content-Type: text/markdown
+
+# avios-cli
+
+[![CI](https://github.com/alexechoi/avios-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/alexechoi/avios-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+A **CLI and TUI for [avios.com](https://www.avios.com)** — check your Avios balance,
+browse your transactions and manage your account without leaving the terminal.
+
+> ⚠️ **Unofficial.** This project is not affiliated with, authorised by, or endorsed by
+> Avios, British Airways or IAG Loyalty. It drives the same private endpoints the
+> avios.com website uses, with your own logged-in session. Use at your own risk; it may
+> break at any time and may be against the provider's terms of service.
+
+![avios TUI dashboard](docs/dashboard.svg)
+
+<sub>The <code>avios tui</code> dashboard (demo data). Regenerate with <code>uv run python scripts/screenshot.py</code>.</sub>
+
+## Status
+
+Early alpha, built in the open. See the [roadmap](#roadmap).
+
+## Install
+
+Requires Python 3.10+.
+
+```bash
+uvx avios-cli --help     # try it without installing (recommended)
+# or install it:
+pip install avios-cli
+```
+
+Or from source, for development:
+
+```bash
+git clone https://github.com/alexechoi/avios-cli
+cd avios-cli
+uv sync
+uv run avios --help
+```
+
+## Log in
+
+avios.com has no credential API — login is Auth0 Universal Login behind hCaptcha and
+SMS/passkey MFA — so `avios login` rides a real browser session (like `gh`/`aws`
+login). Install the login extra once:
+
+```bash
+uv sync --extra login          # or: pip install "avios-cli[login]"
+uv run playwright install chromium
+```
+
+Then either open a browser to log in, or import the cookie from a browser you're
+already logged into:
+
+```bash
+avios login                    # opens a browser; log in once, cookie is captured
+avios login --from-browser     # instead, read the avios.com cookie from Chrome
+```
+
+Your session cookie is stored at `~/.config/avios/state.json` (mode `600`). It
+expires after ~a day; just run `avios login` again. Run `avios logout` to remove it.
+
+## Usage
+
+```bash
+avios balance                  # your Avios balance
+avios transactions --limit 20  # recent transactions
+avios pending                  # pending Avios
+avios accounts                 # linked loyalty accounts
+avios overview                 # dashboard summary (raw JSON)
+avios whoami                   # your profile (raw JSON)
+avios raw /manage-avios/api/user/current   # hit any endpoint directly
+```
+
+Add `--json` to `balance`, `transactions`, `pending` or `accounts` for scriptable
+output.
+
+## TUI
+
+```bash
+avios tui
+```
+
+A full-screen dashboard: your balance in the header and a scrollable transactions
+table. Press `r` to refresh, `q` to quit.
+
+## Roadmap
+
+- [x] Project scaffolding, packaging and CI
+- [x] Session + cookie storage layer
+- [x] Typed API client (balance, transactions, accounts, profile)
+- [x] Browser-assisted `avios login`
+- [x] CLI commands
+- [x] Textual TUI dashboard
+- [ ] Reward-flight **availability** search _(coming soon — needs a British Airways capture)_
+
+## Development
+
+```bash
+uv sync            # installs the project + the `dev` dependency-group
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and
+[CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Security
+
+No passwords are handled or stored — only your session cookie, kept locally at
+`~/.config/avios/state.json` (mode `600`). See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

avios_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+avios/__init__.py,sha256=5McxIEsfgmtlnfQbcf-2iItj31mtplu5xiS9Z0fPNFc,147
+avios/auth.py,sha256=GF3Cz0gJ_CNYUL30p4lcsp4vCkS0kY5IC2-_C1jXSLQ,4274
+avios/cli.py,sha256=ktjZIAw2pEsNCobQCsdDvRNfc2IHWMUbab0V0hMvGvU,6913
+avios/client.py,sha256=dtG8cBDF0vv41GlB8kadxloRj_M292g46Kq2d-ptyig,2463
+avios/config.py,sha256=ZADQ4Exfyvkr0n63u1eXbjNMjMNFSVb7qKTVouCnYgc,1636
+avios/endpoints.py,sha256=YHt2b5gKBRUTaMIcMhbf-e2L292AStd3iWL2bAw6f5Y,785
+avios/models.py,sha256=608z7Sh6GD-zo1LL9mvOhKihniW0dGB7WTsnBzljdtE,1476
+avios/session.py,sha256=18xwyJoC8fnJAnx-paiNlGkTEYormjwIh-relqqe4TM,4227
+avios/tui/__init__.py,sha256=6Ab42V-TpFQmW_8IVYnCr_ByREwgE-PXuT4Y5Upbdf0,101
+avios/tui/app.py,sha256=n3zWEemNzV_8cdGqLQlH9aI7EPkH_Ld1BwQP9w1eB1g,3352
+avios/tui/art.py,sha256=Ke5IIsb-i1FLYjE1s0Lx3ENqLY2Fd_zL4PnEGBGO1Rc,1372
+avios/tui/styles.tcss,sha256=cc-xF2zqA9995wBLATsCrjdPRUWQyRe5EsQFIktfzzY,298
+avios/tui/widgets.py,sha256=ge-uJwPnlydPBgxzxnpiUwycy04a_8Z0WIWMUNU7Pus,964
+avios_cli-0.1.0.dist-info/METADATA,sha256=9RihSFAWR_aKQf3FqR0LyhegxO8WbzQ2y9NXl8IN2ts,5003
+avios_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+avios_cli-0.1.0.dist-info/entry_points.txt,sha256=Bf7Oc85-qvh6S7aIsLWZCHThuXFL3ix8Plzj_s4VUZE,40
+avios_cli-0.1.0.dist-info/licenses/LICENSE,sha256=vxtn-VeiQV1SGhHDY2UgDPLO6zjZPHcd2UdgVcDtzwU,1066
+avios_cli-0.1.0.dist-info/RECORD,,

avios_cli-0.1.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

avios_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+avios = avios.cli:app

avios_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Choi
+
+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.