talis-cli 0.1.0a1__py3-none-any.whl

talis/__init__.py

@@ -0,0 +1,3 @@
+"""Talis command-line client."""
+
+__version__ = "0.1.0a1"

talis/api.py

@@ -0,0 +1,470 @@
+"""
+Thin httpx wrapper for the Talis control plane.
+
+Handles:
+- Bearer auth from the stored credentials
+- ``X-API-Key`` header for the device-flow polling endpoints (no auth)
+- ``X-Request-Id`` correlation header on every outbound request
+- Sensible timeouts
+- A small ``APIError`` that surfaces ``status_code``, parsed ``detail``,
+  and the server-echoed ``request_id`` so callers can paste a single
+  short string into a log search and find both sides of the failure.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from . import config
+
+DEFAULT_TIMEOUT = httpx.Timeout(connect=10.0, read=30.0, write=30.0, pool=10.0)
+
+REQUEST_ID_HEADER = "X-Request-Id"
+
+# Loopback hosts don't traverse the network; HTTP there is fine and we
+# shouldn't add noise to legitimate dev work.
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+# Process-once flag: one stderr line per CLI invocation, not per Client.
+_http_warning_emitted = False
+
+
+def _warn_non_https(endpoint: str) -> None:
+    """One-time warning if `endpoint` is HTTP over a non-loopback host.
+
+    The risk we're flagging: the X-API-Key header carries a Talis JWT and
+    sending it over plain HTTP leaks it to any network observer. Loopback
+    HTTP is exempt because the bytes never hit the network.
+    """
+    global _http_warning_emitted
+    if _http_warning_emitted:
+        return
+    try:
+        parsed = urlparse(endpoint)
+    except ValueError:
+        return
+    if parsed.scheme == "https":
+        return
+    host = (parsed.hostname or "").lower()
+    if host in _LOOPBACK_HOSTS:
+        return
+    sys.stderr.write(
+        f"warning: endpoint {endpoint} is not HTTPS — your token may be "
+        "sent in plaintext.\n"
+    )
+    _http_warning_emitted = True
+
+
+@dataclass
+class APIError(Exception):
+    status_code: int
+    detail: str
+    body: Any = None
+    request_id: str = ""
+
+    def __post_init__(self):
+        super().__init__(self.detail)
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        # Include request_id in the string form so a user pasting the error
+        # message into a bug report carries the correlation key without
+        # having to know the attribute exists.
+        if self.request_id:
+            return f"HTTP {self.status_code} (req {self.request_id}): {self.detail}"
+        return f"HTTP {self.status_code}: {self.detail}"
+
+
+def _generate_request_id() -> str:
+    """Per-Client correlation token. Short, URL-safe, easily greppable.
+
+    The ``cli-`` prefix flags the source so a log diff against server-
+    generated IDs (which start with ``req-``) is one substring away.
+    """
+    return f"cli-{uuid.uuid4().hex[:12]}"
+
+
+def _resolve_request_id(explicit: str | None) -> str:
+    """Pick the request_id for a Client lifetime.
+
+    Order: explicit constructor arg > ``TALIS_REQUEST_ID`` env var > new.
+    Env var lets a wrapping test runner pin one ID across multiple CLI
+    invocations so a higher-level scenario shows up as one logical thread
+    in the server logs.
+    """
+    if explicit:
+        return explicit
+    from_env = (os.environ.get("TALIS_REQUEST_ID") or "").strip()
+    if from_env:
+        return from_env
+    return _generate_request_id()
+
+
+class Client:
+    """One-shot synchronous client. Construct, call, discard."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        token: str | None = None,
+        timeout: httpx.Timeout = DEFAULT_TIMEOUT,
+        request_id: str | None = None,
+    ):
+        self.endpoint = (endpoint or config.endpoint_from_env()).rstrip("/")
+        self.token = token
+        # One correlation ID per Client. Each command typically constructs
+        # one Client, so the ID covers all requests for that command. A
+        # test runner spanning multiple commands can pin one ID via the
+        # ``TALIS_REQUEST_ID`` env var.
+        self.request_id = _resolve_request_id(request_id)
+        self.last_server_request_id = ""  # populated after each call
+        _warn_non_https(self.endpoint)
+        self._client = httpx.Client(base_url=self.endpoint, timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    # Context manager keeps the dispatch site terse.
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ---- request helpers -------------------------------------------------- #
+
+    def _headers(self, auth: bool) -> dict[str, str]:
+        h: dict[str, str] = {
+            "Accept": "application/json",
+            REQUEST_ID_HEADER: self.request_id,
+        }
+        if auth and self.token:
+            # X-API-Key carries the Talis JWT in the existing API contract.
+            # Authorization: Bearer is reserved for Privy tokens on the
+            # /auth/token + /auth/device/approve paths.
+            h["X-API-Key"] = self.token
+        return h
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        auth: bool = True,
+        bearer: str | None = None,
+    ) -> Any:
+        headers = self._headers(auth)
+        if bearer:
+            headers["Authorization"] = f"Bearer {bearer}"
+        resp = self._client.request(method, path, params=params, json=json, headers=headers)
+        # Always record the server's request_id (echo of ours or, in rare
+        # cases like cache-served responses, something different) so callers
+        # have something to paste into a log search even on success.
+        self.last_server_request_id = resp.headers.get(REQUEST_ID_HEADER, "") or ""
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                detail = (
+                    body.get("detail")
+                    if isinstance(body, dict)
+                    else str(body)
+                )
+                if not isinstance(detail, str):
+                    detail = str(detail)
+            except ValueError:
+                body = None
+                detail = resp.text or f"HTTP {resp.status_code}"
+            raise APIError(
+                resp.status_code, detail, body,
+                request_id=self.last_server_request_id,
+            )
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+    # ---- public endpoints ------------------------------------------------- #
+
+    # Device flow
+    def device_code(self, *, client_name: str, scope: str) -> dict:
+        return self._request(
+            "POST", "/auth/device/code",
+            json={"client_name": client_name, "scope": scope},
+            auth=False,
+        )
+
+    def device_token(self, *, device_code: str) -> dict:
+        return self._request(
+            "POST", "/auth/device/token",
+            json={"device_code": device_code},
+            auth=False,
+        )
+
+    def device_approve(self, *, user_code: str, scope: str | None = None) -> dict:
+        payload: dict[str, Any] = {"user_code": user_code}
+        if scope:
+            payload["scope"] = scope
+        return self._request(
+            "POST", "/auth/device/approve",
+            json=payload,
+            auth=True,
+        )
+
+    # OAuth loopback (PKCE) flow — the codex-style primary login.
+    def oauth_token(self, *, code: str, code_verifier: str, redirect_uri: str) -> dict:
+        """Exchange a loopback-captured authorization code for the Talis JWT.
+
+        PKCE is the proof of possession — no auth header. The server validates
+        SHA-256(code_verifier) == the stored code_challenge before minting.
+        """
+        return self._request(
+            "POST", "/auth/oauth/token",
+            json={
+                "grant_type": "authorization_code",
+                "code": code,
+                "code_verifier": code_verifier,
+                "redirect_uri": redirect_uri,
+            },
+            auth=False,
+        )
+
+    # Sessions
+    def list_sessions(self, *, tenant_id: str) -> dict:
+        return self._request("GET", "/auth/sessions", params={"tenant_id": tenant_id})
+
+    def revoke_session(self, *, tenant_id: str, jti_prefix: str) -> dict:
+        return self._request(
+            "DELETE", f"/auth/sessions/{jti_prefix}",
+            params={"tenant_id": tenant_id},
+        )
+
+    def revoke_other_sessions(self, *, tenant_id: str) -> dict:
+        return self._request("DELETE", "/auth/sessions", params={"tenant_id": tenant_id})
+
+    # Read surface
+    def get_portfolio(self, *, tenant_id: str, mode: str | None = None) -> dict:
+        # The route is GET /portfolio/{tenant_id} — tenant_id is bound via the
+        # path, not a query param. No need to send it twice.
+        params: dict[str, Any] = {}
+        if mode:
+            params["mode"] = mode
+        return self._request("GET", f"/portfolio/{tenant_id}", params=params or None)
+
+    def get_balance(self, *, tenant_id: str, exchange: str = "hyperliquid_perpetual") -> dict:
+        return self._request(
+            "GET", "/account/balance",
+            params={"tenant_id": tenant_id, "exchange": exchange},
+        )
+
+    def get_positions(
+        self,
+        *,
+        tenant_id: str,
+        exchange: str = "hyperliquid_perpetual",
+        mode: str | None = None,
+    ) -> dict:
+        params: dict[str, Any] = {"tenant_id": tenant_id, "exchange": exchange}
+        if mode:
+            params["mode"] = mode
+        return self._request("GET", "/positions", params=params)
+
+    def get_open_orders(
+        self,
+        *,
+        tenant_id: str,
+        exchange: str = "hyperliquid_perpetual",
+    ) -> dict:
+        """Open orders for this tenant. Used by ``talis wait order`` and
+        ``talis snapshot``. Server returns ``{"open": [...]}``."""
+        return self._request(
+            "GET", "/orders/open",
+            params={"tenant_id": tenant_id, "exchange": exchange},
+        )
+
+    # -----------------------------------------------------------------
+    # Admin: test-tenant lifecycle (PR 3). All three require admin key.
+    # The CLI surfaces them via ``talis test-tenant {create,delete,list}``.
+    # -----------------------------------------------------------------
+    def create_test_tenant(
+        self,
+        *,
+        label: str = "",
+        initial_balance_usd: float = 10000.0,
+        ttl_seconds: int = 3600,
+        exchange: str = "hyperliquid_perpetual",
+    ) -> dict:
+        return self._request(
+            "POST", "/admin/test-tenants",
+            json={
+                "label": label,
+                "initial_balance_usd": initial_balance_usd,
+                "ttl_seconds": ttl_seconds,
+                "exchange": exchange,
+            },
+        )
+
+    def list_test_tenants(self) -> dict:
+        return self._request("GET", "/admin/test-tenants")
+
+    def delete_test_tenant(
+        self, *, tenant_id: str, exchange: str | None = None,
+    ) -> dict:
+        """Server resolves the exchange from metadata stored at
+        provision time. Pass ``exchange`` only as an explicit override
+        for the rare case where metadata expired (7-day TTL) and the
+        operator knows the original exchange."""
+        params: dict[str, Any] = {}
+        if exchange:
+            params["exchange"] = exchange
+        return self._request(
+            "DELETE", f"/admin/test-tenants/{tenant_id}",
+            params=params or None,
+        )
+
+    # Strategies
+    def list_strategies(self, *, tenant_id: str) -> list[dict] | dict:
+        return self._request("GET", "/strategies", params={"tenant_id": tenant_id})
+
+    def get_strategy(self, *, tenant_id: str, strategy_id: str) -> dict:
+        return self._request(
+            "GET", f"/strategies/{strategy_id}",
+            params={"tenant_id": tenant_id},
+        )
+
+    def stop_strategy(self, *, tenant_id: str, strategy_id: str) -> dict:
+        return self._request(
+            "POST", f"/strategies/{strategy_id}/stop",
+            params={"tenant_id": tenant_id},
+        )
+
+    def delete_strategy(self, *, tenant_id: str, strategy_id: str) -> dict:
+        return self._request(
+            "DELETE", f"/strategies/{strategy_id}",
+            params={"tenant_id": tenant_id},
+        )
+
+    def create_strategy(self, *, body: dict) -> dict:
+        return self._request("POST", "/strategies", json=body)
+
+    # HIP-4 outcome markets
+    def list_outcomes(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+        include_settled: bool = False,
+        network: str | None = None,
+    ) -> dict:
+        """GET /outcomes — browse live HIP-4 outcome markets.
+
+        ``network='testnet'`` browses the testnet catalog (served from an
+        isolated cache); omit it (or 'mainnet') for production markets.
+        """
+        params: dict[str, Any] = {
+            "limit": limit,
+            "offset": offset,
+            "include_settled": str(include_settled).lower(),
+        }
+        if network is not None:
+            params["network"] = network
+        return self._request("GET", "/outcomes", params=params)
+
+    # Direct orders (the iOS manual-trade surface)
+    def place_order(
+        self,
+        *,
+        tenant_id: str,
+        coin: str,
+        side: str,
+        size: float | str,
+        size_mode: str = "usd",
+        order_type: str = "market",
+        price: float | str | None = None,
+        is_spot: bool = False,
+        reduce_only: bool = False,
+        leverage: int | None = None,
+        slippage: float | None = None,
+        network: str | None = None,
+    ) -> dict:
+        """POST /trading/orders — place a direct market/limit order.
+
+        This is the EXACT endpoint the iOS app uses for manual trades, including
+        HIP-4 outcome books (pass an outcome ``#<encoding>`` coin). Unlike
+        ``buy``/``sell`` (which create one-shot strategies via /strategies), this
+        exercises the manual order path end-to-end, so it's the faithful harness
+        for validating manual outcome trading.
+        """
+        body: dict[str, Any] = {
+            "coin": coin,
+            "side": side,
+            "size": str(size),
+            "size_mode": size_mode,
+            "order_type": order_type,
+            "is_spot": is_spot,
+            "reduce_only": reduce_only,
+        }
+        if price is not None:
+            body["price"] = str(price)
+        if leverage is not None:
+            body["leverage"] = leverage
+        if slippage is not None:
+            body["slippage"] = slippage
+        if network is not None:
+            body["network"] = network
+        return self._request(
+            "POST", "/trading/orders",
+            params={"tenant_id": tenant_id},
+            json=body,
+        )
+
+    # Positions
+    def close_position(
+        self,
+        *,
+        tenant_id: str,
+        symbol: str,
+        percentage: float = 100.0,
+        trading_pair: str | None = None,
+        exchange: str = "hyperliquid_perpetual",
+        mode: str | None = None,
+    ) -> dict:
+        """POST /positions/{SYMBOL}/close. Server resolves side + enforces
+        reduce_only based on the current position state.
+
+        ``mode="paper"`` short-circuits to the isolated paper executor and
+        will refuse to touch real positions even if the symbol exists in
+        real state. See engine/api/routes/positions.py:_paper_close_position.
+        """
+        body: dict = {"percentage": percentage}
+        if trading_pair:
+            body["trading_pair"] = trading_pair
+        params: dict[str, Any] = {"tenant_id": tenant_id, "exchange": exchange}
+        if mode:
+            params["mode"] = mode
+        return self._request(
+            "POST", f"/positions/{symbol.upper()}/close",
+            params=params,
+            json=body,
+        )
+
+
+@contextmanager
+def client_from_credentials(creds: config.Credentials):
+    """Convenience: ``with client_from_credentials(creds) as c: ...``."""
+    c = Client(endpoint=creds.endpoint, token=creds.token)
+    try:
+        yield c
+    finally:
+        c.close()

talis/cli.py

@@ -0,0 +1,70 @@
+"""
+Talis CLI entry point.
+
+`talis` resolves to ``main()`` via the project.scripts entry in pyproject.toml.
+
+Command registration here is explicit: each top-level command function is
+imported from its module and decorated with ``app.command(...)``. We avoid
+reaching into ``Typer.registered_commands`` because that's a private surface
+and would break on a Typer upgrade.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from . import __version__, output
+from .commands import auth, trade
+from .commands.auth import sessions_app
+from .commands.outcome import outcome_app
+from .commands.portfolio import portfolio_app
+from .commands.snapshot import snapshot_app
+from .commands.strategies import strategies_app
+from .commands.test_tenant import test_tenant_app
+from .commands.wait import wait_app
+
+app = typer.Typer(
+    name="talis",
+    help="Command-line client for the Talis trading platform.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# --- top-level commands --------------------------------------------------- #
+# Each function is defined as a plain function in its module (no module-level
+# Typer decoration), then registered here. Keeps the call graph easy to follow
+# from cli.py and avoids the "where is this command actually registered?"
+# riddle that ad-hoc sub-typer mounting creates.
+app.command("login")(auth.login)
+app.command("approve")(auth.approve)
+app.command("logout")(auth.logout)
+app.command("whoami")(auth.whoami)
+app.command("buy")(trade.buy)
+app.command("sell")(trade.sell)
+app.command("close")(trade.close)
+
+# --- subgroups ------------------------------------------------------------ #
+app.add_typer(sessions_app, name="sessions")
+app.add_typer(strategies_app, name="strategies")
+app.add_typer(portfolio_app, name="portfolio")
+app.add_typer(wait_app, name="wait")
+app.add_typer(snapshot_app, name="snapshot")
+app.add_typer(test_tenant_app, name="test-tenant")
+app.add_typer(outcome_app, name="outcome")
+
+
+@app.command("version")
+def version(json_: bool = typer.Option(False, "--json", help="JSON output.")) -> None:
+    """Print the CLI version."""
+    if output.should_render_json(json_):
+        output.emit_json({"version": __version__})
+    else:
+        typer.echo(__version__)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

talis/commands/__init__.py

@@ -0,0 +1 @@
+"""Talis CLI subcommands."""

talis/commands/_shared.py

@@ -0,0 +1,152 @@
+"""Shared helpers used by every command module.
+
+Kept in a leading-underscore module so it doesn't show up in the public typer
+subcommand tree. Importers should pull directly: ``from . import _shared``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json as _json
+import os
+from datetime import datetime, timezone
+
+import typer
+
+from .. import config, output
+
+
+def require_creds() -> config.Credentials:
+    """Return the active credentials, or exit 1 if not signed in.
+
+    Precedence:
+      1. ``JARVIS_TOKEN`` environment variable — for non-interactive runs
+         (CI, integration tests, Claude Code with a freshly minted admin
+         token). Validated locally for expiry; the JWT decode is unsigned,
+         which is safe — the server validates on receipt.
+      2. The on-disk credentials file written by ``talis login``.
+
+    The env-var path produces an ephemeral ``Credentials`` (never saved).
+    A real ``talis login`` is still the right path for a long-running
+    workstation; this is for headless agents.
+    """
+    env_token = (os.environ.get("JARVIS_TOKEN") or "").strip()
+    if env_token:
+        creds = creds_from_jwt(env_token, source="JARVIS_TOKEN env var")
+        return creds
+
+    creds = config.load()
+    if not creds:
+        output.error("not signed in. Run `talis login`.")
+        raise typer.Exit(code=1)
+    return creds
+
+
+def jti_from_jwt(token: str) -> str:
+    """Decode the jti claim from a JWT payload WITHOUT verifying the signature.
+
+    Safe: this only inspects a token the CLI itself holds, to extract a claim
+    we'll send back to the server for revocation. The server validates the
+    signature on receipt — a forged/corrupt JWT cannot revoke anyone else's
+    session even if its claims look plausible. Returns "" if the token doesn't
+    decode or the jti claim is absent.
+    """
+    try:
+        payload_b64 = token.split(".", 2)[1]
+        padding = "=" * (-len(payload_b64) % 4)
+        payload = _json.loads(base64.urlsafe_b64decode(payload_b64 + padding))
+        jti = payload.get("jti", "")
+        return jti if isinstance(jti, str) else ""
+    except (ValueError, TypeError, IndexError):
+        return ""
+
+
+def decode_jwt_unverified(token: str) -> dict:
+    """Decode JWT payload claims WITHOUT signature verification.
+
+    The result is used to populate a local ``Credentials`` from a token
+    obtained out-of-band (env var, ``talis login --token``). The server
+    validates the signature on every request — a forged token never
+    survives there. Locally we just need to read the claims to set
+    sensible expiry / scope / tenant on the credentials struct.
+
+    Raises ``ValueError`` on a malformed token. Callers should treat
+    that as "do not save this credential".
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("not a JWT (expected three dot-separated segments)")
+    payload_b64 = parts[1]
+    padding = "=" * (-len(payload_b64) % 4)
+    try:
+        return _json.loads(base64.urlsafe_b64decode(payload_b64 + padding))
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"could not decode JWT payload: {exc}") from exc
+
+
+def creds_from_jwt(
+    token: str,
+    *,
+    endpoint: str | None = None,
+    client_name: str = "Talis CLI (token)",
+    source: str = "token",
+) -> config.Credentials:
+    """Build a ``Credentials`` from a raw JWT string.
+
+    Used by both ``talis login --token <jwt>`` (saved) and the
+    ``JARVIS_TOKEN`` env-var path (ephemeral). Raises ``typer.Exit(1)``
+    on malformed or already-expired tokens — silently accepting an
+    expired token would let the very next request fail with a confusing
+    401.
+    """
+    try:
+        claims = decode_jwt_unverified(token)
+    except ValueError as exc:
+        output.error(f"invalid {source}: {exc}")
+        raise typer.Exit(code=1)
+
+    tenant_id = claims.get("sub") or claims.get("tenant_id")
+    if not isinstance(tenant_id, str) or not tenant_id:
+        output.error(f"invalid {source}: missing `sub` / `tenant_id` claim")
+        raise typer.Exit(code=1)
+
+    exp = claims.get("exp")
+    if isinstance(exp, (int, float)):
+        if exp <= datetime.now(timezone.utc).timestamp():
+            output.error(
+                f"{source} is already expired. Mint a new one and try again."
+            )
+            raise typer.Exit(code=1)
+        expires_at = datetime.fromtimestamp(int(exp), tz=timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%SZ"
+        )
+    else:
+        # No exp claim is unusual for our tokens but not strictly invalid
+        # — let the server enforce. Empty string disables the local check
+        # in config._is_expired.
+        expires_at = ""
+
+    jti = claims.get("jti", "")
+    if not isinstance(jti, str):
+        jti = ""
+    scope = claims.get("scope", "trade")
+    if not isinstance(scope, str):
+        scope = "trade"
+    wallet_address = claims.get("wallet_address")
+    if not isinstance(wallet_address, str):
+        wallet_address = None
+    wallet_id = claims.get("wallet_id")
+    if not isinstance(wallet_id, str):
+        wallet_id = None
+
+    return config.Credentials(
+        endpoint=(endpoint or config.endpoint_from_env()),
+        tenant_id=tenant_id,
+        token=token,
+        expires_at=expires_at,
+        scope=scope,
+        jti_prefix=jti[:8],
+        wallet_address=wallet_address,
+        wallet_id=wallet_id,
+        client_name=client_name,
+    )