nemo-cli 0.0.1__py3-none-any.whl

nemo_cli/__init__.py

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

nemo_cli/__main__.py

@@ -0,0 +1,4 @@
+from nemo_cli.cli import main
+
+if __name__ == "__main__":
+    main()

nemo_cli/api/client.py

@@ -0,0 +1,81 @@
+from typing import Any
+
+import httpx
+
+from nemo_cli.auth.jwt import is_expiring_within
+from nemo_cli.auth.service import refresh_token, sign_in
+from nemo_cli.auth.token_store import clear_token, get_token, set_token
+from nemo_cli.config import API_BASE_URL
+
+# How close to expiry (in seconds) we proactively renew the token before
+# sending the next request. ADR-012 picks 60s as a balance between racing
+# the actual expiry and refreshing too eagerly on short CLI invocations.
+_PROACTIVE_REFRESH_SECONDS = 60
+
+
+def _ensure_token() -> str:
+    """Return a usable bearer token, refreshing proactively if it is close
+    to expiry. Bootstraps via SignIn if no token is cached.
+    """
+    cached = get_token()
+    if cached is None:
+        return _bootstrap_signin()
+
+    if is_expiring_within(cached, _PROACTIVE_REFRESH_SECONDS):
+        # Cached token is about to expire — renew before using it.
+        try:
+            renewed = refresh_token(cached)
+        except RuntimeError:
+            # The server rejected our refresh (token is too stale or
+            # otherwise invalid). Fall back to a fresh SignIn.
+            return _bootstrap_signin()
+        set_token(renewed)
+        return renewed
+
+    return cached
+
+
+def _bootstrap_signin() -> str:
+    """Clear any stale cache and obtain a fresh token via SignIn."""
+    clear_token()
+    fresh = sign_in()
+    set_token(fresh)
+    return fresh
+
+
+def api_request(
+    method: str,
+    path: str,
+    *,
+    json: Any | None = None,
+    params: dict[str, Any] | None = None,
+    timeout: float = 15.0,
+) -> httpx.Response:
+    url = f"{API_BASE_URL}{path}"
+
+    def send(token: str) -> httpx.Response:
+        return httpx.request(
+            method,
+            url,
+            json=json,
+            params=params,
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+
+    token = _ensure_token()
+    response = send(token)
+
+    if response.status_code == 401:
+        # The proactive check missed (server-side revocation, clock
+        # skew, schema change). Try Refresh first; only re-SignIn if
+        # Refresh itself fails. ADR-012.
+        try:
+            renewed = refresh_token(token)
+            set_token(renewed)
+            response = send(renewed)
+        except RuntimeError:
+            fresh = _bootstrap_signin()
+            response = send(fresh)
+
+    return response

nemo_cli/auth/jwt.py

@@ -0,0 +1,47 @@
+"""Read-only JWT introspection helpers.
+
+Used to time refresh calls (peek at the `exp` claim). Signature
+verification is intentionally skipped — the server is the authority on
+whether a token is valid; we just want a hint for when to renew.
+"""
+
+import base64
+import binascii
+import json
+import time
+from typing import cast
+
+
+def is_expiring_within(token: str, seconds: int) -> bool:
+    """True if the JWT's `exp` claim is at most `seconds` away from now.
+
+    Already-expired tokens (exp <= now) return True. Malformed tokens
+    return False — the caller treats them as fresh and lets the
+    reactive 401 path handle any actual rejection.
+    """
+    payload = _decode_payload(token)
+    if payload is None:
+        return False
+    exp = payload.get("exp")
+    if not isinstance(exp, (int, float)):
+        return False
+    return exp - time.time() <= seconds
+
+
+def _decode_payload(token: str) -> dict[str, object] | None:
+    parts = token.split(".")
+    if len(parts) != 3:
+        return None
+    payload_b64 = parts[1]
+    padded = payload_b64 + "=" * (-len(payload_b64) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(padded)
+    except (ValueError, binascii.Error):
+        return None
+    try:
+        parsed = json.loads(decoded)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    return cast(dict[str, object], parsed)

nemo_cli/auth/service.py

@@ -0,0 +1,56 @@
+from typing import cast
+
+import httpx
+
+from nemo_cli.config import API_BASE_URL, load_credentials
+
+
+def sign_in() -> str:
+    credentials = load_credentials()
+    url = f"{API_BASE_URL}/publicapi/shared/auth/SignIn"
+    response = httpx.post(
+        url,
+        json={"userName": credentials.user_name, "password": credentials.password},
+        timeout=15.0,
+    )
+    if response.status_code >= 400:
+        raise RuntimeError(
+            f"SignIn failed ({response.status_code} {response.reason_phrase}): {response.text}"
+        )
+
+    raw: object = response.json()
+    if not isinstance(raw, dict):
+        raise RuntimeError("SignIn response was not a JSON object.")
+
+    payload = cast(dict[str, object], raw)
+    token = payload.get("token")
+    if not isinstance(token, str) or not token:
+        raise RuntimeError("SignIn response missing top-level 'token' string.")
+    return token
+
+
+def refresh_token(current_token: str) -> str:
+    """Trade an existing bearer token for a freshly minted one.
+
+    Calls `GET /api/publicapi/shared/auth/RefreshToken` with the current
+    token in the Authorization header. The response body is a
+    JSON-encoded string containing the new JWT. Raises RuntimeError on
+    any non-2xx or malformed payload — the caller is expected to fall
+    back to `sign_in()` with credentials.
+    """
+    url = f"{API_BASE_URL}/publicapi/shared/auth/RefreshToken"
+    response = httpx.get(
+        url,
+        headers={"Authorization": f"Bearer {current_token}"},
+        timeout=15.0,
+    )
+    if response.status_code >= 400:
+        raise RuntimeError(
+            f"RefreshToken failed "
+            f"({response.status_code} {response.reason_phrase}): {response.text}"
+        )
+
+    payload: object = response.json()
+    if not isinstance(payload, str) or not payload:
+        raise RuntimeError("RefreshToken response was not a non-empty string.")
+    return payload

nemo_cli/auth/token_store.py

@@ -0,0 +1,37 @@
+import json
+from pathlib import Path
+from typing import cast
+
+from platformdirs import user_config_path
+
+_APP_NAME = "nemo-cli"
+
+
+def _config_file() -> Path:
+    return user_config_path(_APP_NAME, ensure_exists=True) / "token.json"
+
+
+def get_token() -> str | None:
+    path = _config_file()
+    if not path.exists():
+        return None
+    try:
+        raw: object = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    data = cast(dict[str, object], raw)
+    token = data.get("token")
+    return token if isinstance(token, str) and token else None
+
+
+def set_token(token: str) -> None:
+    path = _config_file()
+    path.write_text(json.dumps({"token": token}), encoding="utf-8")
+
+
+def clear_token() -> None:
+    path = _config_file()
+    if path.exists():
+        path.unlink()

nemo_cli/cli.py

@@ -0,0 +1,46 @@
+import typer
+
+from nemo_cli import __version__
+from nemo_cli.commands.instruments import app as instruments_app
+from nemo_cli.commands.login import login
+from nemo_cli.commands.logout import logout
+from nemo_cli.commands.portfolio import app as portfolio_app
+from nemo_cli.commands.whoami import whoami
+
+app = typer.Typer(
+    name="nemo",
+    help="Personal CLI for Chilean stockbroker portals.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"nemo {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    version: bool = typer.Option(  # noqa: ARG001 — consumed via callback
+        False,
+        "--version",
+        "-V",
+        help="Show the CLI version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Personal CLI for Chilean stockbroker portals."""
+
+
+app.command()(login)
+app.command()(logout)
+app.command()(whoami)
+app.add_typer(instruments_app, name="instruments")
+app.add_typer(portfolio_app, name="portfolio")
+
+
+def main() -> None:
+    app()

nemo_cli/commands/instruments.py

@@ -0,0 +1,271 @@
+import json
+from dataclasses import asdict
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from nemo_cli.instruments.international import (
+    InternationalAssetsPage,
+    list_international_assets,
+)
+from nemo_cli.instruments.local import (
+    DEFAULT_SUBCLASSES,
+    LocalInstrumentsPage,
+    list_local_instruments,
+)
+from nemo_cli.instruments.prices import (
+    PriceHistory,
+    get_price_history,
+)
+
+app = typer.Typer(
+    help="Browse instruments — local Chilean and international markets.",
+    no_args_is_help=True,
+)
+
+
+@app.command("local")
+def local(
+    search: str = typer.Option("", "--search", "-s", help="Substring filter on nemotecnico."),
+    classes: str = typer.Option(
+        ",".join(DEFAULT_SUBCLASSES),
+        "--classes",
+        help="Comma-separated subclasses (ACC, ACC_INT, CFI, ETF, OPC, …).",
+    ),
+    page: int = typer.Option(1, "--page", min=1),
+    limit: int = typer.Option(30, "--limit", min=1, max=200),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON instead of a table."),
+) -> None:
+    """List local Chilean instruments via the FiltrarInstrumentos endpoint."""
+    subclasses = tuple(c.strip() for c in classes.split(",") if c.strip())
+    try:
+        page_result = list_local_instruments(
+            search=search,
+            subclasses=subclasses,
+            page=page,
+            limit=limit,
+        )
+    except Exception as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from error
+
+    if as_json:
+        _print_json_local(page_result, page=page, limit=limit)
+    else:
+        _print_table_local(page_result, page=page, limit=limit)
+
+
+@app.command("international")
+def international(
+    search: str = typer.Option("", "--search", "-s", help="Substring filter on symbol/name."),
+    exchange: str = typer.Option("", "--exchange", help="Restrict to an exchange (NASDAQ, NYSE)."),
+    page: int = typer.Option(1, "--page", min=1),
+    page_size: int = typer.Option(30, "--page-size", min=1, max=200),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON instead of a table."),
+) -> None:
+    """List international (US equities) assets via the frontoffice/Asset endpoint."""
+    try:
+        page_result = list_international_assets(
+            search=search,
+            exchange=exchange,
+            page=page,
+            page_size=page_size,
+        )
+    except Exception as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from error
+
+    if as_json:
+        _print_json_international(page_result, page=page, page_size=page_size)
+    else:
+        _print_table_international(page_result, page=page, page_size=page_size)
+
+
+def _print_table_local(page_result: LocalInstrumentsPage, *, page: int, limit: int) -> None:
+    console = Console()
+    table = Table(title=f"Local instruments — page {page} ({page_result.total} total)")
+    table.add_column("Nemotécnico", style="cyan", no_wrap=True)
+    table.add_column("Descripción", style="white")
+    table.add_column("Subclase", style="magenta")
+    table.add_column("Familia", style="yellow")
+    table.add_column("Moneda")
+    table.add_column("ISIN", style="dim")
+
+    for instrument in page_result.items:
+        table.add_row(
+            instrument.nemotecnico,
+            instrument.descripcion,
+            instrument.cod_sub_clase,
+            instrument.codigo_familia,
+            instrument.cod_moneda,
+            instrument.isin or "—",
+        )
+    console.print(table)
+    _print_pagination_hint(total=page_result.total, page=page, page_size=limit)
+
+
+def _print_table_international(
+    page_result: InternationalAssetsPage,
+    *,
+    page: int,
+    page_size: int,
+) -> None:
+    console = Console()
+    table = Table(title=f"International assets — page {page} ({page_result.total} total)")
+    table.add_column("Symbol", style="cyan", no_wrap=True)
+    table.add_column("Name", style="white")
+    table.add_column("Exchange", style="magenta")
+    table.add_column("Class", style="yellow")
+    table.add_column("Tradable", justify="center")
+    table.add_column("Volume", justify="right")
+
+    for asset in page_result.items:
+        table.add_row(
+            asset.symbol,
+            asset.name,
+            asset.exchange,
+            asset.asset_class,
+            "✓" if asset.tradable else "✗",
+            f"{asset.volume:,}",
+        )
+    console.print(table)
+    _print_pagination_hint(total=page_result.total, page=page, page_size=page_size)
+
+
+def _print_pagination_hint(*, total: int, page: int, page_size: int) -> None:
+    if total <= page * page_size:
+        return
+    remaining = total - page * page_size
+    console = Console()
+    console.print(
+        f"[dim]… {remaining} more. Use --page {page + 1} to continue.[/dim]"
+    )
+
+
+def _print_json_local(
+    page_result: LocalInstrumentsPage,
+    *,
+    page: int,
+    limit: int,
+) -> None:
+    payload = {
+        "market": "local",
+        "page": page,
+        "page_size": limit,
+        "total": page_result.total,
+        "items": [asdict(item) for item in page_result.items],
+    }
+    typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _print_json_international(
+    page_result: InternationalAssetsPage,
+    *,
+    page: int,
+    page_size: int,
+) -> None:
+    payload = {
+        "market": "international",
+        "page": page,
+        "page_size": page_size,
+        "total": page_result.total,
+        "items": [asdict(item) for item in page_result.items],
+    }
+    typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+@app.command("prices")
+def prices(
+    instrument_id: int = typer.Option(
+        ...,
+        "--id",
+        help=(
+            "Local instrument id (idInstrumento). Find it via "
+            "`nemo instruments local --search NEMO --json`."
+        ),
+    ),
+    as_json: bool = typer.Option(
+        False, "--json", help="Emit JSON (stats + full point series) instead of a stats panel."
+    ),
+) -> None:
+    """Show ~1 year of daily price history for a local Chilean instrument.
+
+    Note: this endpoint is **not available for international assets** —
+    use it only with `idInstrumento` values from `nemo instruments local`.
+    """
+    try:
+        history = get_price_history(instrument_id=instrument_id)
+    except Exception as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from error
+
+    if as_json:
+        _print_json_prices(history)
+    else:
+        _print_prices_panel(history)
+
+
+def _print_prices_panel(history: PriceHistory) -> None:
+    console = Console()
+    if not history.points or history.stats is None:
+        console.print(
+            f"[yellow]No price data for instrument {history.instrument_id}. "
+            f"Note: this endpoint only serves local Chilean instruments.[/yellow]"
+        )
+        return
+
+    stats = history.stats
+    color = "green" if stats.total_return_pct >= 0 else "red"
+
+    table = Table(title=f"Price history — instrument {history.instrument_id}")
+    table.add_column("Field", style="bold")
+    table.add_column("Value", justify="right")
+    table.add_row("Period", f"{stats.first_date} → {stats.last_date}")
+    table.add_row("Days", f"{stats.days}")
+    table.add_row("First", f"{stats.first_price:,.2f}")
+    table.add_row("Last", f"{stats.last_price:,.2f}")
+    table.add_row(
+        "Total return",
+        f"[{color}]{stats.total_return_pct * 100:+.2f}%[/{color}]",
+    )
+    table.add_row("Min", f"{stats.min_price:,.2f}  ({stats.min_date})")
+    table.add_row("Max", f"{stats.max_price:,.2f}  ({stats.max_date})")
+    table.add_row("Mean", f"{stats.mean_price:,.2f}")
+    table.add_row(
+        "Daily return σ",
+        f"{stats.daily_return_std_pct * 100:.3f}%  (not annualised)",
+    )
+    console.print(table)
+    console.print()
+
+    sparkline = _sparkline([p.price for p in history.points])
+    console.print(f"[bold]Trend:[/bold] {sparkline}")
+
+
+def _sparkline(prices: list[float], width: int = 80) -> str:
+    if not prices:
+        return ""
+    chars = "▁▂▃▄▅▆▇█"
+    if len(prices) > width:
+        step = len(prices) / width
+        sampled = [prices[int(i * step)] for i in range(width)]
+    else:
+        sampled = prices
+    pmin, pmax = min(sampled), max(sampled)
+    if pmax == pmin:
+        return chars[3] * len(sampled)
+    out: list[str] = []
+    for value in sampled:
+        idx = int((value - pmin) / (pmax - pmin) * (len(chars) - 1))
+        out.append(chars[idx])
+    return "".join(out)
+
+
+def _print_json_prices(history: PriceHistory) -> None:
+    payload: dict[str, object] = {
+        "instrument_id": history.instrument_id,
+        "stats": asdict(history.stats) if history.stats is not None else None,
+        "points": [asdict(p) for p in history.points],
+    }
+    typer.echo(json.dumps(payload, ensure_ascii=False, indent=2))

nemo_cli/commands/login.py

@@ -0,0 +1,15 @@
+import typer
+
+from nemo_cli.auth.service import sign_in
+from nemo_cli.auth.token_store import set_token
+
+
+def login() -> None:
+    """Authenticate against the configured broker portal and cache the token locally."""
+    try:
+        token = sign_in()
+    except Exception as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from error
+    set_token(token)
+    typer.secho("Login successful. Token cached.", fg=typer.colors.GREEN)

nemo_cli/commands/logout.py

@@ -0,0 +1,9 @@
+import typer
+
+from nemo_cli.auth.token_store import clear_token
+
+
+def logout() -> None:
+    """Clear the cached authentication token."""
+    clear_token()
+    typer.secho("Logged out. Cached token removed.", fg=typer.colors.GREEN)