tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/__init__.py

@@ -0,0 +1,6 @@
+"""tetra-cli: standalone, backend-free client for the Tetra API.
+
+Speaks only HTTP to a remote Tetra API with a bearer token. Contains NO
+backend server code (no models, routes, services, ORM). Safe to distribute.
+"""
+__version__ = "0.1.0"

tetra_cli/api_client/__init__.py

@@ -0,0 +1,10 @@
+"""Shared HTTP client and operations for the Tetra API.
+
+TetraClient/TetraConfig live in .client/.config (this package — no backend).
+The operations package is the single source of truth for HTTP path, body
+shape, and parameter conversions (e.g. duration_minutes -> seconds).
+"""
+from tetra_cli.api_client.client import TetraClient, TetraClientError
+from tetra_cli.api_client.config import TetraConfig
+
+__all__ = ["TetraClient", "TetraClientError", "TetraConfig"]

tetra_cli/api_client/client.py

@@ -0,0 +1,173 @@
+"""HTTP client wrapper for the Tetra API.
+
+Handles authentication headers, error normalization, and response parsing.
+All MCP tools use this client instead of making raw httpx calls.
+"""
+import logging
+from typing import Any
+
+import httpx
+
+from tetra_cli.api_client.config import TetraConfig
+
+logger = logging.getLogger(__name__)
+
+
+class TetraClientError(Exception):
+    """Error from the Tetra API, formatted for MCP tool output."""
+
+    def __init__(self, message: str, status_code: int = 0):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class TetraClient:
+    """Async HTTP client for the Tetra REST API."""
+
+    def __init__(self, config: TetraConfig):
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.api_url,
+            headers={
+                "Authorization": f"Bearer {config.token}",
+                # The CLI/MCP surface is agent-driven by definition. The backend
+                # honors this header in ``is_agent_request`` so created/updated
+                # entities get ``agent_touched=True`` regardless of whether the
+                # token is a real API key or a JWT minted via ``dev_token.py``.
+                "X-Tetra-Agent": "1",
+            },
+            timeout=30.0,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """GET request with error handling."""
+        response = await self._client.get(path, params=_clean_params(params))
+        return _handle_response(response)
+
+    async def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """POST request with error handling."""
+        response = await self._client.post(path, json=json)
+        return _handle_response(response)
+
+    async def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """PUT request with error handling."""
+        response = await self._client.put(path, json=json)
+        return _handle_response(response)
+
+    async def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """PATCH request with error handling."""
+        response = await self._client.patch(path, json=json)
+        return _handle_response(response)
+
+    async def delete(self, path: str) -> Any:
+        """DELETE request with error handling."""
+        response = await self._client.delete(path)
+        return _handle_response(response)
+
+    async def download(
+        self, path: str, params: dict[str, Any] | None = None
+    ) -> tuple[bytes, str]:
+        """GET a binary/file response. Returns ``(content_bytes, filename)``.
+
+        Used by ``output="file"`` ops whose endpoints return binary or
+        non-JSON bodies (zip, CSV, iCal). Unlike :meth:`get`, this never
+        JSON-decodes the response. On a non-2xx status it delegates to
+        :func:`_handle_response`, which raises :class:`TetraClientError`
+        (and is guarded against binary error bodies).
+
+        Args:
+            path: API path to GET.
+            params: Optional query params (None values are dropped).
+
+        Returns:
+            A tuple of the raw response bytes and a best-effort filename
+            derived from the ``Content-Disposition`` header, the last path
+            segment, or ``"download"``.
+        """
+        response = await self._client.get(path, params=_clean_params(params))
+        if not (200 <= response.status_code < 300):
+            # Reuse the non-2xx error path; it always raises TetraClientError.
+            _handle_response(response)
+        content = response.content
+        filename = (
+            _filename_from_disposition(response.headers.get("content-disposition"))
+            or path.rstrip("/").split("/")[-1]
+            or "download"
+        )
+        return content, filename
+
+
+def _filename_from_disposition(value: str | None) -> str | None:
+    """Extract the filename from a ``Content-Disposition`` header value.
+
+    Parses ``attachment; filename=foo.zip`` (and the quoted
+    ``filename="foo.zip"`` variant). Returns None when the header is absent
+    or carries no ``filename`` directive.
+
+    Args:
+        value: The raw ``Content-Disposition`` header value, or None.
+
+    Returns:
+        The unquoted filename, or None.
+    """
+    if not value:
+        return None
+    for part in value.split(";"):
+        part = part.strip()
+        if part.lower().startswith("filename="):
+            name = part[len("filename="):].strip().strip('"')
+            return name or None
+    return None
+
+
+def _clean_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Remove None values from query parameters."""
+    if params is None:
+        return None
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    """Parse response and raise clear errors for non-2xx status codes."""
+    if response.status_code == 204:
+        return {"deleted": True}
+
+    if 200 <= response.status_code < 300:
+        return response.json()
+
+    # Extract error detail from response body. Guard every access: a binary
+    # error body (e.g. an upstream returning a zip on failure) must not crash
+    # the error path itself, so fall back to text, then to the status code.
+    try:
+        body = response.json()
+        detail = body.get("detail", str(body))
+    except Exception:
+        try:
+            detail = response.text or f"HTTP {response.status_code}"
+        except Exception:
+            detail = f"HTTP {response.status_code}"
+
+    status = response.status_code
+
+    if status == 401:
+        raise TetraClientError(
+            "Authentication failed. Check TETRA_API_KEY or TETRA_USERNAME.", status
+        )
+    if status == 403:
+        raise TetraClientError(f"Permission denied: {detail}", status)
+    if status == 404:
+        raise TetraClientError(f"Not found: {detail}", status)
+    if status == 400:
+        raise TetraClientError(f"Invalid request: {detail}", status)
+    if status == 422:
+        raise TetraClientError(f"Validation error: {detail}", status)
+    if status >= 500:
+        raise TetraClientError(
+            f"Server error (HTTP {status}). Is the Tetra backend running?", status
+        )
+
+    raise TetraClientError(f"Unexpected HTTP {status}: {detail}", status)

tetra_cli/api_client/config.py

@@ -0,0 +1,125 @@
+"""MCP server configuration and authentication resolution.
+
+Resolves authentication token from environment variables using a three-tier
+fallback: API key > credential file > login.
+"""
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+# Default backend for a published install: the CLI exists to act on prod on the
+# user's behalf, so an out-of-the-box `pip install` must point at prod. Local
+# dev/tests override this with `TETRA_API_URL=http://localhost:8000`.
+DEFAULT_API_URL = "https://api.tetraoptum.com"
+
+
+@dataclass(frozen=True)
+class TetraConfig:
+    """Immutable configuration for the Tetra MCP server."""
+
+    api_url: str
+    token: str
+
+    @classmethod
+    def from_env(cls) -> "TetraConfig":
+        """Resolve configuration from environment variables and saved config.
+
+        Priority:
+            1. TETRA_API_KEY env var - direct API key (`tetra_...`)
+            2. ~/.tetra/cli_config.json - saved via `tetra-cli auth login`
+            3. TETRA_USERNAME env - reads ~/.tetra/{username}_credentials.json
+            4. TETRA_USERNAME + TETRA_PASSWORD - POSTs to /api/v1/auth/login
+
+        The API key (1 & 2) is the only public/documented path — it's what we
+        mint for users. The username/credential-file/password paths (3 & 4)
+        exist solely for driving local CLI automation in tests; they're kept
+        out of the published skill so users don't reach for them.
+
+        `TETRA_API_URL` env always overrides whatever URL the saved
+        config/credentials file specifies, so users can flip backends
+        (staging vs prod) without re-running `auth login`.
+
+        Raises:
+            ValueError: If no authentication method can be resolved.
+        """
+        env_api_url = os.environ.get("TETRA_API_URL")
+
+        # Priority 1: TETRA_API_KEY env (highest — explicit per-call override).
+        api_key = os.environ.get("TETRA_API_KEY")
+        if api_key:
+            logger.info("Using TETRA_API_KEY env var")
+            return cls(api_url=env_api_url or DEFAULT_API_URL, token=api_key)
+
+        # Priority 2: Saved CLI config (~/.tetra/cli_config.json).
+        # Created by `tetra-cli auth login`. Lets an AI agent persist
+        # a key once and have every subsequent CLI/MCP call pick it up.
+        saved_cfg_path = Path.home() / ".tetra" / "cli_config.json"
+        if saved_cfg_path.exists():
+            try:
+                saved = json.loads(saved_cfg_path.read_text())
+                saved_token = saved.get("api_key")
+                if saved_token:
+                    api_url = env_api_url or saved.get("api_url") or DEFAULT_API_URL
+                    logger.info("Using saved CLI config: %s", saved_cfg_path)
+                    return cls(api_url=api_url, token=saved_token)
+            except (json.JSONDecodeError, OSError) as exc:
+                logger.warning("Ignoring malformed %s: %s", saved_cfg_path, exc)
+
+        username = os.environ.get("TETRA_USERNAME")
+
+        # Priority 3: Per-username credential file (JWT, may be expired).
+        if username:
+            cred_path = Path.home() / ".tetra" / f"{username}_credentials.json"
+            if cred_path.exists():
+                cred_data = json.loads(cred_path.read_text())
+                token = cred_data.get("token") or cred_data.get("access_token", "")
+                logger.info("Using credential file: %s", cred_path)
+                return cls(
+                    api_url=env_api_url or DEFAULT_API_URL,
+                    token=token,
+                )
+
+        # Priority 4: Login with password.
+        password = os.environ.get("TETRA_PASSWORD")
+        if username and password:
+            api_url = env_api_url or DEFAULT_API_URL
+            logger.info("Logging in as %s", username)
+            token = _login(api_url, username, password)
+            return cls(api_url=api_url, token=token)
+
+        raise ValueError(
+            "No API key configured. Mint one in Settings → API Keys, then either:\n"
+            "  TETRA_API_KEY=tetra_...   - set it in the environment, or\n"
+            "  tetra-cli auth login <key> - save it to ~/.tetra/cli_config.json once.\n"
+            f"Point at another backend with TETRA_API_URL (defaults to {DEFAULT_API_URL})."
+        )
+
+
+def _login(api_url: str, username: str, password: str) -> str:
+    """Authenticate via the login endpoint and return the access token.
+
+    Args:
+        api_url: Base URL of the Tetra API.
+        username: Account username or email.
+        password: Account password.
+
+    Returns:
+        JWT access token string.
+
+    Raises:
+        ValueError: If login fails.
+    """
+    response = httpx.post(
+        f"{api_url}/api/v1/auth/login",
+        json={"identifier": username, "password": password},
+        timeout=10.0,
+    )
+    if response.status_code != 200:
+        raise ValueError(f"Login failed (HTTP {response.status_code}): {response.text}")
+    return response.json()["access_token"]

tetra_cli/api_client/operations/__init__.py

@@ -0,0 +1,9 @@
+"""Pure async operation functions wrapping the Tetra REST API.
+
+Each module exports functions of the shape:
+    async def op_name(client: TetraClient, *, ...kwargs) -> dict[str, Any]
+
+These are the single source of truth for HTTP path, body shape, and
+parameter conversions (e.g. duration_minutes -> seconds). Both the MCP
+tools and the CLI commands call these operations.
+"""

tetra_cli/api_client/operations/accounts.py

@@ -0,0 +1,303 @@
+"""Pure async operations for the accounts API.
+
+Covers the account-profile endpoints (own account, lookup by UID, profile
+update, username availability) and the active-recording session endpoints
+(get / create / update / clear) that the frontend uses to sync an in-progress
+recording across devices.
+
+Recording state is stored under ``account.details['active_recording']``. The
+backend accepts ``start_time`` / ``last_modified`` as ISO-8601 datetime strings
+and ``pending_events`` as a list of objects, so those are exposed as JSON-shaped
+options rather than scalars.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="accounts me",
+    summary="Get the current authenticated account's profile.",
+    covers=[("GET", "/api/v1/accounts/me")],
+)
+async def get_my_account(client: TetraClient) -> dict[str, Any]:
+    """Get the current authenticated account's profile.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Account dict including derived fields (has_passkey, is_pro,
+        subscription_status).
+    """
+    return await client.get("/api/v1/accounts/me")
+
+
+@operation(
+    cli="accounts get",
+    summary="Get an account by UID (own account, or any account for superusers).",
+    covers=[("GET", "/api/v1/accounts/{uid}")],
+    params={"uid": arg(help="Account UID to fetch")},
+)
+async def get_account(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Get an account by UID.
+
+    Returns your own account freely; fetching another account's profile
+    requires a superuser token (the backend 403s otherwise).
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Account UID to fetch
+
+    Returns:
+        Account dict
+    """
+    return await client.get(f"/api/v1/accounts/{uid}")
+
+
+@operation(
+    cli="accounts update",
+    summary="Update the current account's profile. Only provided fields change.",
+    covers=[("PUT", "/api/v1/accounts/me")],
+    params={
+        "username": opt("--username", help="New username (3+ chars, alnum/_/-)."),
+        "full_name": opt("--full-name", help="Display name."),
+        "description": opt("--description", help="Profile description (<=1000)."),
+        "phone": opt("--phone", help="Phone number (<=30 chars)."),
+        "address": opt("--address", help="Address (<=500 chars)."),
+        "timezone": opt("--timezone",
+                        help="IANA timezone, e.g. 'America/Denver'."),
+        "details": opt("--details", json=True,
+                       help="Free-form details object as a JSON dict."),
+        "unit_system": opt("--unit-system", choices=["imperial", "metric"],
+                           help="Distance/elevation render preference."),
+    },
+)
+async def update_my_account(
+    client: TetraClient,
+    *,
+    username: str | None = None,
+    full_name: str | None = None,
+    description: str | None = None,
+    phone: str | None = None,
+    address: str | None = None,
+    timezone: str | None = None,
+    details: dict[str, Any] | None = None,
+    geotag_events: bool | None = None,
+    unit_system: str | None = None,
+) -> dict[str, Any]:
+    """Update the current account's profile. Only provided fields are changed.
+
+    Each non-None field is forwarded to the API; omitted fields keep their
+    stored value (the backend update is a partial merge).
+
+    Args:
+        client: Authenticated TetraClient
+        username: New username (3+ chars, letters/numbers/underscores/hyphens)
+        full_name: Display name
+        description: Profile description (max 1000 chars)
+        phone: Phone number (max 30 chars)
+        address: Address (max 500 chars)
+        timezone: IANA timezone string (e.g. 'America/Denver')
+        details: Free-form details object merged onto the account
+        geotag_events: Whether to opt into passive geotagging of events
+        unit_system: 'imperial' or 'metric' render preference
+
+    Returns:
+        Updated account dict
+    """
+    body: dict[str, Any] = {}
+    if username is not None:
+        body["username"] = username
+    if full_name is not None:
+        body["full_name"] = full_name
+    if description is not None:
+        body["description"] = description
+    if phone is not None:
+        body["phone"] = phone
+    if address is not None:
+        body["address"] = address
+    if timezone is not None:
+        body["timezone"] = timezone
+    if details is not None:
+        body["details"] = details
+    if geotag_events is not None:
+        body["geotag_events"] = geotag_events
+    if unit_system is not None:
+        body["unit_system"] = unit_system
+    return await client.put("/api/v1/accounts/me", json=body)
+
+
+@operation(
+    cli="accounts check-username",
+    summary="Check whether a username is available and valid.",
+    covers=[("GET", "/api/v1/accounts/check-username/{username}")],
+    params={"username": arg(help="Username to check")},
+)
+async def check_username(client: TetraClient, username: str) -> dict[str, Any]:
+    """Check whether a username is available and valid.
+
+    Validation mirrors the signup rules (3+ chars, alphanumeric plus
+    underscore/hyphen) and the availability check excludes your own account,
+    so checking your current username reports it as available.
+
+    Args:
+        client: Authenticated TetraClient
+        username: Username to check
+
+    Returns:
+        Dict with ``available``, ``valid``, and a human-readable ``message``.
+    """
+    return await client.get(f"/api/v1/accounts/check-username/{username}")
+
+
+@operation(
+    cli="accounts recording-get",
+    summary="Get the current active recording session.",
+    covers=[("GET", "/api/v1/accounts/me/recording")],
+)
+async def get_active_recording(client: TetraClient) -> dict[str, Any]:
+    """Get the current active recording session.
+
+    Returns the in-progress recording stored on the account. The backend
+    404s (surfaced as a "Not found" error) when there is no active session.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Active recording dict with ``start_time``, ``pending_events``, and
+        ``last_modified``.
+    """
+    return await client.get("/api/v1/accounts/me/recording")
+
+
+@operation(
+    cli="accounts recording-start",
+    summary="Start a new active recording session.",
+    covers=[("POST", "/api/v1/accounts/me/recording")],
+    params={
+        "start_time": arg(help="Session start time as an ISO-8601 datetime."),
+        "pending_events": opt("--pending-events", json=True,
+                              help="List of pending-event objects (JSON array)."),
+        "last_modified": opt("--last-modified",
+                             help="Conflict-resolution timestamp (ISO-8601)."),
+    },
+)
+async def create_active_recording(
+    client: TetraClient,
+    *,
+    start_time: str,
+    pending_events: list[dict[str, Any]] | None = None,
+    last_modified: str | None = None,
+) -> dict[str, Any]:
+    """Start a new active recording session.
+
+    Overwrites any existing active recording. ``start_time`` is required;
+    ``pending_events`` defaults to an empty list when omitted.
+
+    Args:
+        client: Authenticated TetraClient
+        start_time: Session start time as an ISO-8601 datetime string
+        pending_events: Pending-event objects captured so far (defaults to [])
+        last_modified: Conflict-resolution timestamp as ISO-8601
+
+    Returns:
+        The created active recording dict
+    """
+    body: dict[str, Any] = {
+        "start_time": start_time,
+        "pending_events": pending_events if pending_events is not None else [],
+    }
+    if last_modified is not None:
+        body["last_modified"] = last_modified
+    return await client.post("/api/v1/accounts/me/recording", json=body)
+
+
+@operation(
+    cli="accounts recording-update",
+    summary="Update or create the active recording session. Only provided fields change.",
+    covers=[("PUT", "/api/v1/accounts/me/recording")],
+    params={
+        "start_time": opt("--start-time",
+                          help="Session start time as an ISO-8601 datetime."),
+        "pending_events": opt("--pending-events", json=True,
+                              help="List of pending-event objects (JSON array)."),
+        "last_modified": opt("--last-modified",
+                             help="Conflict-resolution timestamp (ISO-8601)."),
+    },
+)
+async def update_active_recording(
+    client: TetraClient,
+    *,
+    start_time: str | None = None,
+    pending_events: list[dict[str, Any]] | None = None,
+    last_modified: str | None = None,
+) -> dict[str, Any]:
+    """Update (or create) the active recording session.
+
+    Only non-None fields are sent; the backend merges them onto the existing
+    recording state, so this is a partial update.
+
+    Args:
+        client: Authenticated TetraClient
+        start_time: New session start time as ISO-8601
+        pending_events: Replacement pending-event objects
+        last_modified: Conflict-resolution timestamp as ISO-8601
+
+    Returns:
+        The updated active recording dict
+    """
+    body: dict[str, Any] = {}
+    if start_time is not None:
+        body["start_time"] = start_time
+    if pending_events is not None:
+        body["pending_events"] = pending_events
+    if last_modified is not None:
+        body["last_modified"] = last_modified
+    return await client.put("/api/v1/accounts/me/recording", json=body)
+
+
+@operation(
+    cli="accounts recording-clear",
+    summary="Clear the active recording session.",
+    covers=[("DELETE", "/api/v1/accounts/me/recording")],
+)
+async def delete_active_recording(client: TetraClient) -> dict[str, Any]:
+    """Clear the active recording session.
+
+    Idempotent: succeeds whether or not a recording is currently active.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Status dict (``{"status": "ok"}``)
+    """
+    return await client.delete("/api/v1/accounts/me/recording")
+
+
+@operation(
+    cli="accounts app-request",
+    summary="Record a request for native-app (TestFlight) access for a platform.",
+    covers=[("POST", "/api/v1/accounts/me/app-request/{platform}")],
+    params={"platform": arg(help="Target platform (e.g. ios). ios is tracked; others no-op.")},
+)
+async def request_mobile_app(
+    client: TetraClient, platform: str,
+) -> dict[str, Any]:
+    """Record a request for native-app access on a platform.
+
+    Only iOS is tracked (sets ``ios_requested_at``; idempotent — first request
+    wins) so an admin can add the account to TestFlight. Any non-iOS platform
+    is accepted and returns the account unchanged.
+
+    Args:
+        client: Authenticated TetraClient
+        platform: Target platform (e.g. ``ios``).
+
+    Returns:
+        The (possibly unchanged) account dict.
+    """
+    return await client.post(f"/api/v1/accounts/me/app-request/{platform}")