glossa-cli 0.1.1__py3-none-any.whl

glossa_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Glossa CLI — a standalone terminal client for the Glossa REST API.
+
+Talks to the API over HTTP using the same auth as the MCP server
+(``GLOSSA_API_TOKEN`` static token or OAuth device-code flow). Install with::
+
+    uv tool install glossa-cli      # or: pipx install glossa-cli / uvx glossa-cli
+"""

glossa_cli/auth.py

@@ -0,0 +1,227 @@
+"""OAuth 2.0 Device-Code flow + credential storage for the Glossa CLI.
+
+Vendored from ``backend/glossa_mcp/auth.py`` so the CLI ships as a standalone,
+lightweight package (httpx + stdlib only) without depending on the heavy
+``glossa-backend`` distribution.
+
+Design:
+- Credentials are stored in ``~/.config/glossa/credentials.json`` (shared with
+  the MCP client — a token approved once works for both).
+- When a valid access token exists it's used directly.
+- When the access token has expired the refresh token is used to get a new pair.
+- When there are no credentials at all, the device-code flow is initiated:
+    1. POST /api/oauth/device_authorization → get device_code + user_code
+    2. Print verification_uri_complete to stderr so the user can approve it.
+    3. Poll /api/oauth/token every ``interval`` seconds until approved, denied
+       or the device code expires.
+    4. Save the resulting access + refresh tokens to disk.
+
+Only ``ensure_token(base_url)`` is the public entry-point — it returns a valid
+Bearer token string or raises ``AuthError`` (fatal, surfaced to the user).
+"""
+
+import asyncio
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import httpx
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+CREDENTIALS_PATH = Path.home() / ".config" / "glossa" / "credentials.json"
+POLL_MAX_SECONDS = 600  # 10 min — matches backend DEVICE_CODE_TTL
+DEFAULT_POLL_INTERVAL = 5  # seconds between /token poll attempts
+
+
+# ── Data ─────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str
+    expires_at: float  # Unix timestamp when access_token expires
+    base_url: str
+
+    def access_expired(self) -> bool:
+        # Give a 30-second buffer so we refresh before the token actually expires.
+        return time.time() >= (self.expires_at - 30)
+
+
+# ── Storage ──────────────────────────────────────────────────────────────────
+
+
+def _load() -> Credentials | None:
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        data = json.loads(CREDENTIALS_PATH.read_text())
+        return Credentials(**data)
+    except Exception:
+        return None
+
+
+def _save(creds: Credentials) -> None:
+    CREDENTIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(asdict(creds), indent=2))
+
+
+def _clear() -> None:
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+
+
+def clear_credentials() -> bool:
+    """Remove any cached OAuth credentials. Returns True if a file was removed."""
+    existed = CREDENTIALS_PATH.exists()
+    _clear()
+    return existed
+
+
+# ── Errors ───────────────────────────────────────────────────────────────────
+
+
+class AuthError(Exception):
+    """Fatal auth failure — message is user-visible."""
+
+
+# ── OAuth HTTP helpers ────────────────────────────────────────────────────────
+
+
+async def _post(client: httpx.AsyncClient, path: str, body: dict) -> dict:
+    resp = await client.post(path, json=body)
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = {}
+    if resp.is_success:
+        return payload
+    # Surface OAuth error_description if present
+    detail = payload.get("detail") or {}
+    if isinstance(detail, dict):
+        msg = detail.get("error_description") or detail.get("error") or str(payload)
+    elif isinstance(detail, str):
+        msg = detail
+    else:
+        msg = resp.text or resp.reason_phrase
+    raise httpx.HTTPStatusError(msg, request=resp.request, response=resp)
+
+
+async def _refresh(client: httpx.AsyncClient, refresh_token: str, base_url: str) -> Credentials:
+    data = await _post(client, "/api/oauth/token", {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+    })
+    return Credentials(
+        access_token=data["access_token"],
+        refresh_token=data["refresh_token"],
+        expires_at=time.time() + data.get("expires_in", 3600),
+        base_url=base_url,
+    )
+
+
+# ── Device-code flow ─────────────────────────────────────────────────────────
+
+
+async def _device_flow(base_url: str) -> Credentials:
+    """Run the full RFC 8628 device-code flow interactively (via stderr)."""
+    async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+        # 1 — Request codes
+        init = await _post(client, "/api/oauth/device_authorization", {})
+        device_code = init["device_code"]
+        user_code = init["user_code"]
+        verification_uri_complete = init["verification_uri_complete"]
+        interval = int(init.get("interval", DEFAULT_POLL_INTERVAL))
+
+        # 2 — Prompt user (stderr keeps stdout clean for piping / JSON output)
+        print(
+            f"\n{'─' * 60}\n"
+            f"  Glossa CLI — authorisation required\n\n"
+            f"  1. Open this URL in your browser:\n"
+            f"     {verification_uri_complete}\n\n"
+            f"  2. Code to confirm: {user_code}\n"
+            f"{'─' * 60}\n",
+            file=sys.stderr,
+            flush=True,
+        )
+
+        # 3 — Poll
+        deadline = time.time() + POLL_MAX_SECONDS
+        while time.time() < deadline:
+            await asyncio.sleep(interval)
+            try:
+                data = await _post(client, "/api/oauth/token", {
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                })
+                # Success
+                print("  ✓ Authorised — Glossa CLI is ready.\n", file=sys.stderr, flush=True)
+                return Credentials(
+                    access_token=data["access_token"],
+                    refresh_token=data["refresh_token"],
+                    expires_at=time.time() + data.get("expires_in", 3600),
+                    base_url=base_url,
+                )
+            except httpx.HTTPStatusError as exc:
+                # Parse the body that _post embeds in the exception message
+                try:
+                    body = exc.response.json()
+                    detail = body.get("detail", {})
+                    error_code = detail.get("error") if isinstance(detail, dict) else None
+                except Exception:
+                    error_code = None
+
+                if error_code == "authorization_pending":
+                    continue  # keep polling
+                if error_code == "slow_down":
+                    interval += 5
+                    continue
+                if error_code in ("access_denied", "expired_token", "invalid_grant"):
+                    # Upgrade path: surface the upgrade URL if present
+                    upgrade_url = (
+                        (detail or {}).get("upgrade_url") if isinstance(detail, dict) else None
+                    )
+                    if upgrade_url:
+                        raise AuthError(
+                            f"Glossa access requires a Pro subscription.\n"
+                            f"Upgrade at: {upgrade_url}"
+                        ) from exc
+                    raise AuthError(f"Authorisation denied ({error_code}).") from exc
+                # Unknown error — surface verbatim
+                raise AuthError(f"Token error: {exc}") from exc
+
+        raise AuthError("Authorisation timed out — please run the command again.")
+
+
+# ── Public entry-point ────────────────────────────────────────────────────────
+
+
+async def ensure_token(base_url: str) -> str:
+    """Return a valid Bearer token for *base_url*, refreshing or re-authorising as needed."""
+    creds = _load()
+
+    # Mismatched base_url (e.g. switched from prod to dev) — start fresh
+    if creds is not None and creds.base_url.rstrip("/") != base_url.rstrip("/"):
+        _clear()
+        creds = None
+
+    if creds is not None and not creds.access_expired():
+        return creds.access_token
+
+    if creds is not None and creds.refresh_token:
+        try:
+            async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+                creds = await _refresh(client, creds.refresh_token, base_url)
+            _save(creds)
+            return creds.access_token
+        except Exception:
+            # Refresh failed (revoked / expired / downgraded) — full re-auth
+            _clear()
+
+    # No usable credentials — run device-code flow
+    creds = await _device_flow(base_url)
+    _save(creds)
+    return creds.access_token

glossa_cli/cli.py

@@ -0,0 +1,376 @@
+"""Glossa command-line interface.
+
+Subcommands:
+    glossa analyze   — CEFR-leveled word/phrase breakdown of arbitrary text
+    glossa add       — add a word/phrase to your vocabulary
+    glossa set       — change a word's state (saved / learning / known)
+    glossa list      — list your vocabulary
+    glossa review    — interactive FSRS review session
+
+Auth & config come from the environment (see ``client.GlossaClient``):
+    GLOSSA_API_URL    e.g. https://api.glossa.pro (or http://localhost:8000)
+    GLOSSA_API_TOKEN  a glossa_* token; omit to use the OAuth browser flow.
+"""
+
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from glossa_cli.auth import clear_credentials
+from glossa_cli.client import GlossaApiError, GlossaClient
+
+app = typer.Typer(
+    help="Glossa vocabulary CLI — analyze text and manage your vocabulary.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+LANGUAGES = {"en", "fr", "pt-PT"}
+STATUSES = {"saved", "learning", "known"}
+RATINGS = {1: "Again", 2: "Hard", 3: "Good", 4: "Easy"}
+
+
+# ── Shared helpers ─────────────────────────────────────────────────────────────
+
+
+def _format_error(exc: Exception) -> str:
+    if isinstance(exc, GlossaApiError):
+        if exc.status_code == 401:
+            return (
+                "Glossa rejected your credentials. Generate a token in "
+                "Glossa → Settings → Tokens and export it as GLOSSA_API_TOKEN, "
+                "or omit it to use the browser sign-in flow."
+            )
+        if exc.status_code == 404:
+            return f"Not found: {exc.detail}"
+        return f"Glossa API error ({exc.status_code}): {exc.detail}"
+    if isinstance(exc, httpx.HTTPError):
+        return (
+            f"Could not reach Glossa at {os.environ.get('GLOSSA_API_URL', '')!r}: {exc}. "
+            "Is the backend running and GLOSSA_API_URL correct?"
+        )
+    return f"Glossa error: {exc}"
+
+
+def _run(fn: Callable[[GlossaClient], Awaitable[Any]]) -> Any:
+    """Open an authenticated client, run *fn*, and surface errors as exit code 1."""
+
+    async def _wrap() -> Any:
+        async with GlossaClient() as client:
+            return await fn(client)
+
+    try:
+        return asyncio.run(_wrap())
+    except (GlossaApiError, RuntimeError, httpx.HTTPError) as exc:
+        err_console.print(f"[red]{_format_error(exc)}[/red]")
+        raise typer.Exit(1) from exc
+
+
+def _validate_lang(language_code: str | None) -> None:
+    if language_code is not None and language_code not in LANGUAGES:
+        err_console.print(
+            f"[red]Unknown language '{language_code}'. Choose from: "
+            f"{', '.join(sorted(LANGUAGES))}.[/red]"
+        )
+        raise typer.Exit(2)
+
+
+def _validate_status(status: str) -> None:
+    if status not in STATUSES:
+        err_console.print(
+            f"[red]Invalid status '{status}'. Choose from: "
+            f"{', '.join(sorted(STATUSES))}.[/red]"
+        )
+        raise typer.Exit(2)
+
+
+# ── Commands ───────────────────────────────────────────────────────────────────
+
+
+@app.command()
+def login(
+    force: bool = typer.Option(
+        False, "--force", help="Clear cached credentials and sign in again."
+    ),
+) -> None:
+    """Sign in to Glossa. Run this first — opens a browser to authorise you."""
+    using_token = bool(os.environ.get("GLOSSA_API_TOKEN"))
+
+    if force and not using_token and clear_credentials():
+        console.print("[dim]Cleared saved credentials.[/dim]")
+
+    # Opening the client runs the OAuth device flow (printing an auth URL) when
+    # there's no usable token; the tiny authenticated call then confirms it worked.
+    _run(lambda c: c.reviews_due(limit=1))
+
+    if using_token:
+        console.print("[green]✓ Signed in with your GLOSSA_API_TOKEN.[/green]")
+    else:
+        console.print(
+            "[green]✓ Signed in.[/green] You're ready to use Glossa — try "
+            "[bold]glossa list[/bold]."
+        )
+
+
+@app.command()
+def analyze(
+    text: str | None = typer.Argument(
+        None, help="Text to analyze. Omit to read --file or stdin."
+    ),
+    file: str | None = typer.Option(None, "--file", "-f", help="Read text from this file."),
+    lang: str | None = typer.Option(
+        None, "--lang", "-l", help="Language: en, fr, pt-PT. Auto-detected if omitted."
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """Analyze text and show its vocabulary breakdown (CEFR levels, phrases)."""
+    _validate_lang(lang)
+
+    if file is not None:
+        try:
+            with open(file, encoding="utf-8") as fh:
+                content = fh.read()
+        except OSError as exc:
+            err_console.print(f"[red]Cannot read {file}: {exc}[/red]")
+            raise typer.Exit(2) from exc
+    elif text is not None:
+        content = text
+    elif not sys.stdin.isatty():
+        content = sys.stdin.read()
+    else:
+        err_console.print("[red]No text provided. Pass TEXT, --file, or pipe via stdin.[/red]")
+        raise typer.Exit(2)
+
+    if not content.strip():
+        err_console.print("[red]Empty input.[/red]")
+        raise typer.Exit(2)
+
+    result = _run(lambda c: c.analyze_text(content, language_code=lang))
+
+    if as_json:
+        console.print_json(json.dumps(result))
+        return
+
+    words = result.get("words", [])
+    table = Table(title="Vocabulary breakdown")
+    table.add_column("Lemma", style="bold")
+    table.add_column("POS")
+    table.add_column("Count", justify="right")
+    table.add_column("CEFR")
+    table.add_column("Type")
+    for w in words:
+        kind = w.get("type", "word")
+        if kind == "phrase" and w.get("pattern_type"):
+            kind = f"phrase · {w['pattern_type']}"
+        table.add_row(
+            w.get("lemma", ""),
+            w.get("part_of_speech", "") or "",
+            str(w.get("occurrences", "")),
+            w.get("cefr_level") or "—",
+            kind,
+        )
+    console.print(table)
+    console.print(
+        f"[dim]{result.get('unique_lemmas', 0)} unique lemmas · "
+        f"{result.get('unique_phrases', 0)} phrases · "
+        f"{result.get('total_tokens', 0)} tokens[/dim]"
+    )
+
+
+@app.command()
+def add(
+    lemma: str = typer.Argument(..., help="Dictionary form, e.g. 'serendipity' or 'break the ice'."),  # noqa: E501
+    lang: str = typer.Option("en", "--lang", "-l", help="Language: en, fr, pt-PT."),
+    pos: str | None = typer.Option(None, "--pos", help="NOUN, VERB, ADJ, or ADV."),
+    status: str = typer.Option("learning", "--status", "-s", help="saved, learning, or known."),
+    translation: str | None = typer.Option(None, "--translation", "-t", help="Your translation."),
+) -> None:
+    """Add a word or phrase to your vocabulary."""
+    _validate_lang(lang)
+    _validate_status(status)
+    result = _run(
+        lambda c: c.add_word(
+            lemma=lemma,
+            language_code=lang,
+            part_of_speech=pos,
+            status=status,
+            translation=translation,
+        )
+    )
+    _print_vocab_item(result, action="Saved")
+
+
+@app.command(name="set")
+def set_status(
+    lemma: str = typer.Argument(..., help="The word/phrase to update (or pass --id instead)."),
+    status: str = typer.Argument(..., help="New state: saved, learning, or known."),
+    lang: str = typer.Option("en", "--lang", "-l", help="Language: en, fr, pt-PT."),
+    pos: str | None = typer.Option(None, "--pos", help="NOUN, VERB, ADJ, or ADV."),
+    translation: str | None = typer.Option(None, "--translation", "-t", help="Your translation."),
+    entry_id: int | None = typer.Option(
+        None, "--id", help="Update a specific lexical_entry_id (from `glossa list`) precisely."
+    ),
+) -> None:
+    """Change a word's state. By default upserts by lemma; --id targets one sense."""
+    _validate_status(status)
+    if entry_id is not None:
+        result = _run(
+            lambda c: c.update_status(
+                lexical_entry_id=entry_id, status=status, user_translation=translation
+            )
+        )
+    else:
+        _validate_lang(lang)
+        result = _run(
+            lambda c: c.add_word(
+                lemma=lemma,
+                language_code=lang,
+                part_of_speech=pos,
+                status=status,
+                translation=translation,
+            )
+        )
+    _print_vocab_item(result, action="Updated")
+
+
+@app.command(name="list")
+def list_words(
+    status: str | None = typer.Option(
+        None, "--status", "-s", help="Filter: saved, learning, or known."
+    ),
+    lang: str | None = typer.Option(None, "--lang", "-l", help="Filter: en, fr, pt-PT."),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw JSON response."),
+) -> None:
+    """List your vocabulary."""
+    if status is not None:
+        _validate_status(status)
+    _validate_lang(lang)
+    items = _run(lambda c: c.list_vocabulary(status=status, language_code=lang))
+
+    if as_json:
+        console.print_json(json.dumps(items))
+        return
+
+    if not items:
+        console.print("[dim]No matching words.[/dim]")
+        return
+
+    table = Table(title="Your vocabulary")
+    table.add_column("ID", justify="right", style="dim")
+    table.add_column("Lemma", style="bold")
+    table.add_column("POS")
+    table.add_column("Lang")
+    table.add_column("Status")
+    table.add_column("CEFR")
+    table.add_column("Next review")
+    for it in items:
+        table.add_row(
+            str(it.get("lexical_entry_id", "")),
+            it.get("lemma") or "",
+            it.get("part_of_speech") or "",
+            it.get("language_code") or "",
+            it.get("status") or "",
+            it.get("cefr_level") or "—",
+            _fmt_dt(it.get("next_review")),
+        )
+    console.print(table)
+    console.print(f"[dim]{len(items)} word(s)[/dim]")
+
+
+@app.command()
+def review(
+    lang: str | None = typer.Option(None, "--lang", "-l", help="Filter: en, fr, pt-PT."),
+    limit: int = typer.Option(50, "--limit", help="Max cards to fetch (1–200)."),
+) -> None:
+    """Interactive FSRS review of words that are due."""
+    _validate_lang(lang)
+    cards = _run(lambda c: c.reviews_due(limit=limit))
+
+    # The /reviews/due endpoint has no language filter; apply it client-side.
+    if lang is not None:
+        cards = [c for c in cards if c.get("language_code") in (None, lang)]
+
+    if not cards:
+        console.print("[green]Nothing due for review — you're all caught up![/green]")
+        return
+
+    console.print(
+        f"[bold]{len(cards)}[/bold] card(s) due. Rate each: "
+        r"1 Again  2 Hard  3 Good  4 Easy  (q to quit)" + "\n"
+    )
+
+    reviewed = 0
+    for idx, card in enumerate(cards, start=1):
+        console.print(
+            f"[dim]{idx}/{len(cards)}[/dim]  [bold]{card.get('lemma', '')}[/bold] "
+            f"[dim]({card.get('part_of_speech', '')})[/dim]"
+        )
+        if card.get("context_sentence"):
+            console.print(f"  [italic dim]{card['context_sentence']}[/italic dim]")
+
+        rating = _prompt_rating()
+        if rating is None:
+            break
+
+        result = _run(
+            lambda c, cid=card["id"], r=rating: c.submit_review(user_vocabulary_id=cid, rating=r)
+        )
+        reviewed += 1
+        console.print(
+            f"  [green]✓ {RATINGS[rating]}[/green] — next review "
+            f"{_fmt_dt(result.get('next_review'))}\n"
+        )
+
+    console.print(f"[bold]Reviewed {reviewed} of {len(cards)} card(s).[/bold]")
+
+
+# ── Output helpers ─────────────────────────────────────────────────────────────
+
+
+def _prompt_rating() -> int | None:
+    """Prompt until a valid 1–4 rating or 'q' is entered. Returns None on quit."""
+    while True:
+        raw = typer.prompt("  Rating (1-4, q to quit)").strip().lower()
+        if raw in ("q", "quit"):
+            return None
+        if raw.isdigit() and int(raw) in RATINGS:
+            return int(raw)
+        err_console.print("  [red]Enter 1, 2, 3, 4, or q.[/red]")
+
+
+def _print_vocab_item(item: dict, action: str) -> None:
+    bits = [f"[green]{action}[/green] [bold]{item.get('lemma', '')}[/bold]"]
+    if item.get("part_of_speech"):
+        bits.append(f"({item['part_of_speech']})")
+    bits.append(f"→ status [bold]{item.get('status', '')}[/bold]")
+    if item.get("cefr_level"):
+        bits.append(f"· CEFR {item['cefr_level']}")
+    console.print(" ".join(bits))
+    if item.get("next_review"):
+        console.print(f"[dim]Next review: {_fmt_dt(item['next_review'])}[/dim]")
+
+
+def _fmt_dt(value: str | None) -> str:
+    if not value:
+        return "—"
+    # ISO timestamps render fine trimmed to the minute.
+    return value.replace("T", " ")[:16]
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

glossa_cli/client.py

@@ -0,0 +1,176 @@
+"""Thin httpx client for the Glossa REST API.
+
+Vendored from ``backend/glossa_mcp/client.py`` and extended with the vocabulary
+and review endpoints the CLI needs. Authentication is resolved in this order:
+
+1. ``GLOSSA_API_TOKEN`` env var — a static ``glossa_*`` API token generated in
+   Glossa Settings → Tokens. Useful for scripting / CI.
+2. OAuth 2.0 device-code flow (RFC 8628) — the first time there are no stored
+   credentials, a URL is printed to stderr so the user can approve in a browser.
+   Subsequent runs load the saved access/refresh tokens from
+   ``~/.config/glossa/credentials.json`` and refresh automatically.
+
+Set ``GLOSSA_API_URL`` (default ``https://api.glossa.pro``) to point at a
+different instance (e.g. ``http://localhost:8000`` for local dev).
+"""
+
+import os
+from typing import Any
+
+import httpx
+
+from glossa_cli.auth import AuthError, ensure_token
+
+DEFAULT_TIMEOUT_SECONDS = 30
+DEFAULT_BASE_URL = "https://api.glossa.pro"
+
+
+class GlossaApiError(Exception):
+    """Raised when the API responds with an error status."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"HTTP {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class GlossaClient:
+    """Async client that authenticates with a static API token **or** OAuth.
+
+    Call ``await client.ensure_auth()`` before the first request — or just
+    use the async context manager which calls it for you.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("GLOSSA_API_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self._static_token = token or os.environ.get("GLOSSA_API_TOKEN", "")
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    async def ensure_auth(self) -> None:
+        """Resolve the bearer token (static env var or OAuth) and open the httpx client."""
+        if self._client is not None:
+            return  # already initialised
+
+        if not self.base_url:
+            raise RuntimeError(
+                "GLOSSA_API_URL is not set. Export it (e.g. "
+                "https://api.glossa.pro, or http://localhost:8000 for local dev)."
+            )
+
+        if self._static_token:
+            bearer = self._static_token
+        else:
+            try:
+                bearer = await ensure_token(self.base_url)
+            except AuthError as exc:
+                raise RuntimeError(str(exc)) from exc
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self._timeout,
+            headers={"Authorization": f"Bearer {bearer}"},
+        )
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "GlossaClient":
+        await self.ensure_auth()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self, method: str, path: str, json: dict | None = None
+    ) -> Any:
+        if self._client is None:
+            await self.ensure_auth()
+        resp = await self._client.request(method, path, json=json)  # type: ignore[union-attr]
+        if resp.is_success:
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+        try:
+            payload = resp.json()
+            detail = payload.get("detail", resp.text) if isinstance(payload, dict) else resp.text
+        except ValueError:
+            detail = resp.text or resp.reason_phrase
+        raise GlossaApiError(resp.status_code, str(detail))
+
+    # ── Text analysis ─────────────────────────────────────────────────────────
+
+    async def analyze_text(
+        self, content: str, language_code: str | None = None
+    ) -> Any:
+        body: dict[str, Any] = {"content": content}
+        if language_code is not None:
+            body["language_code"] = language_code
+        return await self._request("POST", "/api/articles/analyze", body)
+
+    # ── Vocabulary ──────────────────────────────────────────────────────────────
+
+    async def add_word(
+        self,
+        lemma: str,
+        language_code: str,
+        part_of_speech: str | None = None,
+        status: str = "learning",
+        translation: str | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {
+            "lemma": lemma,
+            "language_code": language_code,
+            "status": status,
+        }
+        if part_of_speech is not None:
+            body["part_of_speech"] = part_of_speech
+        if translation is not None:
+            body["user_translation"] = translation
+        return await self._request("POST", "/api/vocabulary/add", body)
+
+    async def list_vocabulary(
+        self, status: str | None = None, language_code: str | None = None
+    ) -> Any:
+        params: dict[str, str] = {}
+        if status is not None:
+            params["status"] = status
+        if language_code is not None:
+            params["language_code"] = language_code
+        query = ("?" + "&".join(f"{k}={v}" for k, v in params.items())) if params else ""
+        return await self._request("GET", f"/api/vocabulary{query}")
+
+    async def update_status(
+        self,
+        lexical_entry_id: int,
+        status: str,
+        user_translation: str | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {
+            "lexical_entry_id": lexical_entry_id,
+            "status": status,
+        }
+        if user_translation is not None:
+            body["user_translation"] = user_translation
+        return await self._request("POST", "/api/vocabulary/update", body)
+
+    async def list_learning_words(self, language_code: str | None = None) -> Any:
+        params = f"?language_code={language_code}" if language_code else ""
+        return await self._request("GET", f"/api/extension/learning-words{params}")
+
+    # ── Reviews (FSRS) ────────────────────────────────────────────────────────
+
+    async def reviews_due(self, limit: int = 50) -> Any:
+        return await self._request("GET", f"/api/reviews/due?limit={limit}")
+
+    async def submit_review(self, user_vocabulary_id: int, rating: int) -> Any:
+        body = {"user_vocabulary_id": user_vocabulary_id, "rating": rating}
+        return await self._request("POST", "/api/reviews/submit", body)

glossa_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: glossa-cli
+Version: 0.1.1
+Summary: Command-line client for Glossa — analyze text and manage your vocabulary from the terminal
+Project-URL: Homepage, https://glossa.pro
+Project-URL: Repository, https://github.com/artemiy-rodionov/glossa
+Project-URL: Issues, https://github.com/artemiy-rodionov/glossa/issues
+Author-email: Artemiy Rodionov <artemiy.rodionov@gmail.com>
+Keywords: cli,flashcards,fsrs,glossa,language-learning,vocabulary
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+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 :: Education
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# glossa-cli
+
+A standalone command-line client for [Glossa](https://glossa.pro) — analyze text
+and manage your vocabulary from the terminal.
+
+## Install (one command)
+
+```sh
+pipx install glossa-cli      # recommended — isolated install
+# or:
+pip install glossa-cli
+```
+
+Both put the `glossa` command on your PATH. No `uv` or source checkout required.
+
+## Sign in (OAuth — no token to copy)
+
+Run `glossa login` first. It opens a browser to authorise you; after you
+approve, your tokens are cached in `~/.config/glossa/credentials.json` and
+refreshed automatically — you won't need to sign in again.
+
+```sh
+glossa login          # opens a browser; prints an auth URL to approve
+glossa login --force  # clear the cached sign-in and authorise again
+```
+
+> **Self-hosted / local dev:** point the CLI at your instance with
+> `export GLOSSA_API_URL=http://localhost:8000` (defaults to
+> `https://api.glossa.pro`).
+>
+> **CI / scripting:** skip the browser flow by exporting a static token from
+> Glossa → Settings → Tokens: `export GLOSSA_API_TOKEN=glossa_xxx`.
+
+## Usage
+
+```sh
+# Analyze text (arg, --file, or stdin)
+echo "The serendipitous discovery broke the ice." | glossa analyze --lang en
+glossa analyze --file article.txt
+glossa analyze "a short sentence" --json
+
+# Add a word or phrase
+glossa add serendipity --lang en --status learning
+glossa add "break the ice" --lang en -t "сломать лёд"
+
+# Change a word's state (upserts by lemma; --id targets one sense)
+glossa set serendipity known --lang en
+glossa set --id 1234 saved
+
+# List your vocabulary
+glossa list --status learning
+glossa list --lang fr --json
+
+# Interactive FSRS review session
+glossa review --lang en
+```

glossa_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+glossa_cli/__init__.py,sha256=VFFQyFCA4dTGSTkMLNyFoZ-r5wIbwksWAww-zG2mIyo,304
+glossa_cli/auth.py,sha256=ejzoZyEeGPD1if7EaQ1wkkYZgUfObsGxz6BHNNnnlrE,9347
+glossa_cli/cli.py,sha256=FgvGaD_KaeYpoDY2S5BrrhVrKq-qDbJTUnxuFSVENvY,13341
+glossa_cli/client.py,sha256=aJCu_2shn717ReIXDUbc1g-oHNDpaXAl1XHNaQ3MSpk,6892
+glossa_cli-0.1.1.dist-info/METADATA,sha256=6IdfUXu3wkDxUXKL4AuI3jBs6KypevX0v6u4C9NiHFE,2789
+glossa_cli-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+glossa_cli-0.1.1.dist-info/entry_points.txt,sha256=1GYBHUNF3-081eXSSeQM25FRKrqMw9R7DYsDFV2QcGY,47
+glossa_cli-0.1.1.dist-info/RECORD,,

glossa_cli-0.1.1.dist-info/WHEEL

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

glossa_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+glossa = glossa_cli.cli:main