geopera-cli 0.1.0__py3-none-any.whl

geopera_cli/__init__.py

@@ -0,0 +1,8 @@
+"""geopera-cli — command-line interface for the Geopera platform.
+
+A thin auth + dispatch shell over the published `geopera` SDK. Every capability
+is reached through /v1/op/{operation_id}; the only CLI-resident logic is auth
+(device flow, token refresh, and the Bearer / X-API-Key choice).
+"""
+
+__version__ = "0.1.0"

geopera_cli/__main__.py

@@ -0,0 +1,398 @@
+"""geopera — command-line interface for the Geopera geospatial data platform.
+
+The CLI is a thin auth + dispatch shell over the published `geopera` SDK. The
+only CLI-resident logic is auth: the device flow, token refresh, and the
+Bearer / X-API-Key choice. Every capability is reached through
+/v1/op/{operation_id}, so a new backend operation is instantly usable as
+`geopera op <new.op>` with zero CLI changes.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import itertools
+import json
+import os
+import secrets
+import sys
+import threading
+import time
+import webbrowser
+from typing import Optional
+
+import typer
+
+from . import auth, client, config
+
+app = typer.Typer(
+    name="geopera",
+    help="Command-line interface for the Geopera geospatial data platform.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+err = typer.echo
+
+
+# ---------------------------------------------------------------------------
+# Shared options
+# ---------------------------------------------------------------------------
+
+ProfileOpt = typer.Option(
+    None,
+    "--profile",
+    help="Stored identity to use (env: GEOPERA_PROFILE). Default: 'default'.",
+)
+ApiUrlOpt = typer.Option(
+    None,
+    "--api-url",
+    help=f"API base URL override (env: GEOPERA_API_URL). Default: {config.DEFAULT_API_URL}.",
+)
+
+
+def _fail(message: str, code: int = 1) -> None:
+    """Print an error to stderr and exit non-zero."""
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(code)
+
+
+def _print_json(value) -> None:
+    typer.echo(json.dumps(value, indent=2, sort_keys=False, default=str))
+
+
+def _pkce_pair() -> tuple[str, str]:
+    """Generate a PKCE (verifier, S256 challenge) pair."""
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+class _Spinner:
+    """A tiny stderr spinner used while polling for device authorization."""
+
+    def __init__(self, message: str):
+        self.message = message
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def _run(self) -> None:
+        for frame in itertools.cycle("|/-\\"):
+            if self._stop.is_set():
+                break
+            sys.stderr.write(f"\r{self.message} {frame}")
+            sys.stderr.flush()
+            time.sleep(0.1)
+
+    def __enter__(self) -> "_Spinner":
+        if sys.stderr.isatty():
+            self._thread.start()
+        return self
+
+    def __exit__(self, *args) -> None:
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout=0.3)
+        if sys.stderr.isatty():
+            sys.stderr.write("\r" + " " * (len(self.message) + 4) + "\r")
+            sys.stderr.flush()
+
+
+# ---------------------------------------------------------------------------
+# login
+# ---------------------------------------------------------------------------
+
+@app.command()
+def login(
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        help="Skip the device flow and store an API key. Use '-' to read from stdin.",
+    ),
+    api_url: Optional[str] = ApiUrlOpt,
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Do not auto-open the verification URL."
+    ),
+    scope: str = typer.Option(
+        config.DEFAULT_SCOPE, "--scope", help="OAuth scope to request."
+    ),
+    profile: Optional[str] = ProfileOpt,
+):
+    """Authenticate. Device flow by default; --api-key for headless use."""
+    profile = config.resolve_profile(profile)
+    stored = auth.load_profile(profile)
+    resolved_url = config.resolve_api_url(api_url, stored.get("api_url"))
+
+    if api_key is not None:
+        _login_api_key(profile, resolved_url, api_key)
+        return
+
+    _login_device(profile, resolved_url, scope, no_browser)
+
+
+def _login_api_key(profile: str, api_url: str, api_key: str) -> None:
+    """Validate and store an API key (kept out of shell history when piped)."""
+    if api_key == "-":
+        api_key = sys.stdin.readline().strip()
+    if not api_key:
+        _fail("No API key provided.")
+
+    if not api_key.startswith("gpra_"):
+        typer.secho(
+            "Note: this key has no 'gpra_' prefix. It will still work, but new "
+            "Geopera keys are expected to start with 'gpra_'.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+
+    ctx = auth.AuthContext(profile, api_url, {"type": "api_key", "api_key": api_key})
+    try:
+        info = client.userinfo(ctx)
+    except client.OpError as exc:
+        _fail(f"API key validation failed: {exc.message}")
+
+    auth.save_profile(
+        profile,
+        {"api_url": api_url, "auth": {"type": "api_key", "api_key": api_key}},
+    )
+    who = info.get("geopera_principal_id") or info.get("sub") or "api key"
+    typer.secho(f"Logged in as {who} (API key, profile '{profile}').", fg=typer.colors.GREEN)
+
+
+def _login_device(profile: str, api_url: str, scope: str, no_browser: bool) -> None:
+    """RFC 8628 device authorization grant with PKCE."""
+    verifier, challenge = _pkce_pair()
+    try:
+        device = client.device_authorize(api_url, scope, challenge)
+    except client.OpError as exc:
+        _fail(exc.message)
+
+    user_code = device.get("user_code", "")
+    verification_uri = device.get("verification_uri", "")
+    complete = device.get("verification_uri_complete") or verification_uri
+
+    typer.echo()
+    typer.secho("  To sign in, visit:", bold=True)
+    typer.secho(f"    {complete}", fg=typer.colors.CYAN)
+    typer.echo()
+    typer.secho("  And confirm this code:", bold=True)
+    typer.secho(f"    {user_code}", fg=typer.colors.GREEN, bold=True)
+    typer.echo()
+
+    if not no_browser and complete:
+        try:
+            webbrowser.open(complete)
+        except Exception:  # noqa: BLE001 - browser launch is best-effort
+            pass
+
+    with _Spinner("Waiting for authorization..."):
+        try:
+            token = client.wait_for_device_authorization(api_url, device, verifier)
+        except client.OpError as exc:
+            _fail(exc.message)
+
+    auth_entry = auth._auth_from_token_response(api_url, token)
+    auth.save_profile(profile, {"api_url": api_url, "auth": auth_entry})
+
+    # Confirm with a userinfo round-trip.
+    ctx = auth.AuthContext(profile, api_url, auth_entry)
+    try:
+        info = client.userinfo(ctx)
+        who = info.get("sub") or "user"
+    except client.OpError:
+        who = "user"
+    typer.secho(f"Logged in as {who} (profile '{profile}').", fg=typer.colors.GREEN)
+
+
+# ---------------------------------------------------------------------------
+# logout
+# ---------------------------------------------------------------------------
+
+@app.command()
+def logout(profile: Optional[str] = ProfileOpt):
+    """Clear the active profile's stored credentials."""
+    profile = config.resolve_profile(profile)
+    entry = auth.load_profile(profile)
+    auth_entry = entry.get("auth", {})
+
+    if auth_entry.get("type") == "oauth":
+        client.logout_oauth(entry.get("api_url", config.DEFAULT_API_URL), auth_entry)
+
+    if auth.clear_profile(profile):
+        typer.secho(f"Logged out (profile '{profile}').", fg=typer.colors.GREEN)
+    else:
+        typer.echo(f"No stored credentials for profile '{profile}'.")
+
+
+# ---------------------------------------------------------------------------
+# whoami
+# ---------------------------------------------------------------------------
+
+@app.command()
+def whoami(
+    api_url: Optional[str] = ApiUrlOpt,
+    profile: Optional[str] = ProfileOpt,
+    raw: bool = typer.Option(False, "--json", help="Print the raw userinfo JSON."),
+):
+    """Show the authenticated principal, org, and scopes."""
+    try:
+        ctx = auth.load_context(profile, api_url)
+        info = client.userinfo(ctx)
+    except (auth.AuthError, client.OpError) as exc:
+        _fail(str(getattr(exc, "message", exc)))
+
+    if raw:
+        _print_json(info)
+        return
+
+    typer.secho(f"sub:             {info.get('sub', '-')}", fg=typer.colors.GREEN)
+    typer.echo(f"principal_type:  {info.get('geopera_principal_type', '-')}")
+    typer.echo(f"org_id:          {info.get('geopera_org_id', '-')}")
+    typer.echo(f"scope:           {info.get('scope', '-')}")
+    typer.echo(f"api_url:         {ctx.api_url}")
+    typer.echo(f"profile:         {ctx.profile}")
+
+
+# ---------------------------------------------------------------------------
+# op — generic operation dispatch
+# ---------------------------------------------------------------------------
+
+@app.command()
+def op(
+    operation_id: Optional[str] = typer.Argument(
+        None, help="Operation id, e.g. orders.estimate or catalog.federated_search."
+    ),
+    body: Optional[str] = typer.Argument(
+        None, help="JSON request body. Use '-' to read from stdin."
+    ),
+    file: Optional[str] = typer.Option(
+        None, "--file", "-f", help="Read the JSON body from a file."
+    ),
+    list_ops: bool = typer.Option(
+        False, "--list", help="List available operation ids and exit."
+    ),
+    api_url: Optional[str] = ApiUrlOpt,
+    profile: Optional[str] = ProfileOpt,
+):
+    """Invoke any operation: POST /v1/op/OPERATION_ID with a JSON body."""
+    if list_ops:
+        _list_operations(api_url, profile)
+        return
+
+    if not operation_id:
+        _fail("OPERATION_ID is required (or use --list).")
+
+    payload = _resolve_body(body, file)
+
+    try:
+        ctx = auth.load_context(profile, api_url)
+        result = client.invoke_op(ctx, operation_id, payload)
+    except auth.AuthError as exc:
+        _fail(str(exc))
+    except client.OpError as exc:
+        # problem+json -> readable message + non-zero exit.
+        detail = exc.detail.get("detail") or exc.detail.get("title")
+        msg = f"[{exc.status}] {exc.message}"
+        if detail and detail != exc.message:
+            msg += f" — {detail}"
+        _fail(msg, code=2)
+
+    _print_json(result)
+
+
+def _resolve_body(body: Optional[str], file: Optional[str]):
+    """Resolve the JSON body from --file, stdin ('-'), positional arg, or {}."""
+    if file:
+        try:
+            with open(file, encoding="utf-8") as fh:
+                raw = fh.read()
+        except OSError as exc:
+            _fail(f"Cannot read --file: {exc}")
+    elif body == "-":
+        raw = sys.stdin.read()
+    elif body:
+        raw = body
+    else:
+        return {}
+
+    raw = raw.strip()
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        _fail(f"Invalid JSON body: {exc}")
+
+
+def _list_operations(api_url: Optional[str], profile: Optional[str]) -> None:
+    """List operation ids from the live OpenAPI document."""
+    try:
+        ctx_url = config.resolve_api_url(
+            api_url, auth.load_profile(config.resolve_profile(profile)).get("api_url")
+        )
+    except Exception:  # noqa: BLE001
+        ctx_url = config.resolve_api_url(api_url, None)
+
+    import httpx
+
+    try:
+        resp = httpx.get(f"{ctx_url}/openapi.json", timeout=30.0)
+        resp.raise_for_status()
+        paths = resp.json().get("paths", {})
+    except (httpx.HTTPError, ValueError) as exc:
+        _fail(f"Could not fetch operation list: {exc}")
+
+    ops = sorted(
+        p[len("/v1/op/") :] for p in paths if p.startswith("/v1/op/")
+    )
+    for op_id in ops:
+        typer.echo(op_id)
+    typer.secho(f"\n{len(ops)} operations.", fg=typer.colors.BLUE, err=True)
+
+
+# ---------------------------------------------------------------------------
+# orders — curated subcommand (thin alias over `op`)
+# ---------------------------------------------------------------------------
+
+orders_app = typer.Typer(help="Curated order commands (thin aliases over `op`).")
+app.add_typer(orders_app, name="orders")
+
+
+@orders_app.command("list")
+def orders_list(
+    api_url: Optional[str] = ApiUrlOpt,
+    profile: Optional[str] = ProfileOpt,
+    raw: bool = typer.Option(False, "--json", help="Print raw JSON instead of a table."),
+):
+    """List your orders (alias for `op orders.list`)."""
+    try:
+        ctx = auth.load_context(profile, api_url)
+        result = client.invoke_op(ctx, "orders.list", {})
+    except auth.AuthError as exc:
+        _fail(str(exc))
+    except client.OpError as exc:
+        _fail(f"[{exc.status}] {exc.message}", code=2)
+
+    rows = result.get("orders", result) if isinstance(result, dict) else result
+    if raw or not isinstance(rows, list):
+        _print_json(result)
+        return
+
+    if not rows:
+        typer.echo("No orders.")
+        return
+
+    for row in rows:
+        oid = row.get("id", "-")
+        name = row.get("display_name") or row.get("name") or "-"
+        status = row.get("status", "-")
+        typer.echo(f"{oid:<38}  {status:<14}  {name}")
+
+
+def main() -> None:  # console-script-friendly entry (pyproject uses `app`)
+    app()
+
+
+if __name__ == "__main__":
+    main()

geopera_cli/auth.py

@@ -0,0 +1,269 @@
+"""Credential store + auth context.
+
+The store is a single JSON file at ~/.config/geopera/credentials.json. Multiple
+identities are namespaced as top-level keys by *profile* name, e.g.::
+
+    {
+      "default": {
+        "api_url": "https://api.geopera.com",
+        "auth": {"type": "oauth", "access_token": "...", "refresh_token": "...",
+                 "expires_at": 1234567890, "scope": "openid profile",
+                 "issuer": "https://api.geopera.com"}
+      },
+      "staging": {
+        "api_url": "https://staging.api.geopera.com",
+        "auth": {"type": "api_key", "api_key": "gpra_..."}
+      }
+    }
+
+load_client() turns the active profile into a geopera.AuthenticatedClient,
+transparently refreshing an OAuth access token that is at/near expiry.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any
+
+import httpx
+
+from . import config
+
+try:
+    # The published SDK. The CLI is a thin shell over its AuthenticatedClient.
+    from geopera import AuthenticatedClient
+except ImportError as exc:  # pragma: no cover - import guard
+    raise RuntimeError(
+        "The 'geopera' SDK is required. Install it with: pip install geopera"
+    ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Store read / write (mode-hardened)
+# ---------------------------------------------------------------------------
+
+def _ensure_dir() -> None:
+    """Create ~/.config/geopera with mode 0700 (owner-only)."""
+    os.makedirs(config.CONFIG_DIR, mode=0o700, exist_ok=True)
+    # makedirs honours `mode` only for the leaf it creates and is subject to
+    # umask; chmod unconditionally to guarantee 0700.
+    try:
+        os.chmod(config.CONFIG_DIR, 0o700)
+    except OSError:
+        pass
+
+
+def _read_store() -> dict[str, Any]:
+    """Load the full credentials.json (all profiles). Empty dict if absent."""
+    if not config.CREDENTIALS_PATH.exists():
+        return {}
+    try:
+        with open(config.CREDENTIALS_PATH, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _write_store(store: dict[str, Any]) -> None:
+    """Atomically write the full store with file mode 0600."""
+    _ensure_dir()
+    tmp = config.CREDENTIALS_PATH.with_suffix(".json.tmp")
+    # Open with 0600 from the start so the secret is never briefly world-readable.
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(store, fh, indent=2, sort_keys=True)
+            fh.write("\n")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, config.CREDENTIALS_PATH)
+        os.chmod(config.CREDENTIALS_PATH, 0o600)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def load_profile(profile: str) -> dict[str, Any]:
+    """Return the stored entry for a profile (api_url + auth), or {} if none."""
+    return _read_store().get(profile, {})
+
+
+def save_profile(profile: str, entry: dict[str, Any]) -> None:
+    """Persist a profile entry, leaving other profiles untouched."""
+    store = _read_store()
+    store[profile] = entry
+    _write_store(store)
+
+
+def clear_profile(profile: str) -> bool:
+    """Remove a profile's auth (keeps api_url). Returns True if anything changed."""
+    store = _read_store()
+    entry = store.get(profile)
+    if not entry or "auth" not in entry:
+        return False
+    entry.pop("auth", None)
+    store[profile] = entry
+    _write_store(store)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Token refresh (OAuth)
+# ---------------------------------------------------------------------------
+
+def _needs_refresh(auth: dict[str, Any]) -> bool:
+    """True if the OAuth access token is missing or within the leeway window."""
+    expires_at = auth.get("expires_at")
+    if not expires_at:
+        return False
+    return time.time() >= (float(expires_at) - config.REFRESH_LEEWAY_SECONDS)
+
+
+def refresh_oauth(api_url: str, auth: dict[str, Any]) -> dict[str, Any]:
+    """Exchange the stored refresh_token for a fresh access (and refresh) token.
+
+    The backend rotates the refresh token on every use, so BOTH tokens are
+    replaced. Returns the updated auth dict (caller persists it).
+    """
+    refresh_token = auth.get("refresh_token")
+    if not refresh_token:
+        raise AuthError("Session expired and no refresh token is stored. Run 'geopera login'.")
+
+    resp = httpx.post(
+        config.realm_url(api_url, "token"),
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": config.CLIENT_ID,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=30.0,
+    )
+    if resp.status_code != 200:
+        raise AuthError(
+            "Token refresh failed (your session may have been revoked). "
+            "Run 'geopera login' to sign in again."
+        )
+
+    payload = resp.json()
+    return _auth_from_token_response(api_url, payload, fallback=auth)
+
+
+def _auth_from_token_response(
+    api_url: str, payload: dict[str, Any], fallback: dict[str, Any] | None = None
+) -> dict[str, Any]:
+    """Build an oauth auth entry from a token endpoint response."""
+    fallback = fallback or {}
+    expires_in = payload.get("expires_in")
+    expires_at = time.time() + float(expires_in) if expires_in else None
+    return {
+        "type": "oauth",
+        "access_token": payload["access_token"],
+        # The backend rotates the refresh token; keep the old one only if the
+        # response omits a new one.
+        "refresh_token": payload.get("refresh_token", fallback.get("refresh_token")),
+        "expires_at": expires_at,
+        "scope": payload.get("scope", fallback.get("scope", config.DEFAULT_SCOPE)),
+        "issuer": api_url,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Building the SDK client
+# ---------------------------------------------------------------------------
+
+class AuthError(Exception):
+    """Raised when no usable credentials are available."""
+
+
+class AuthContext:
+    """Resolved auth for the active profile + a ready-to-use SDK client."""
+
+    def __init__(self, profile: str, api_url: str, auth: dict[str, Any]):
+        self.profile = profile
+        self.api_url = api_url
+        self.auth = auth
+
+    @property
+    def is_api_key(self) -> bool:
+        return self.auth.get("type") == "api_key"
+
+    def client(self) -> AuthenticatedClient:
+        """Construct the SDK AuthenticatedClient for this auth context.
+
+        - api_key  -> X-API-Key header, no prefix (API accepts X-API-Key)
+        - oauth    -> Authorization: Bearer <access_token>
+        """
+        if self.is_api_key:
+            return AuthenticatedClient(
+                base_url=self.api_url,
+                token=self.auth["api_key"],
+                prefix="",
+                auth_header_name="X-API-Key",
+            )
+        return AuthenticatedClient(
+            base_url=self.api_url,
+            token=self.auth["access_token"],
+            prefix="Bearer",
+            auth_header_name="Authorization",
+        )
+
+    def bearer_headers(self) -> dict[str, str]:
+        """Raw auth header for direct httpx calls (userinfo, logout, op)."""
+        if self.is_api_key:
+            return {"X-API-Key": self.auth["api_key"]}
+        return {"Authorization": f"Bearer {self.auth['access_token']}"}
+
+
+def load_context(
+    profile: str | None = None, api_url_flag: str | None = None
+) -> AuthContext:
+    """Load the active profile, refreshing the OAuth token if near expiry.
+
+    Honours the GEOPERA_API_TOKEN env override (opaque bearer/api-key) so an
+    ephemeral CI token can be used without writing to the store.
+    """
+    profile = config.resolve_profile(profile)
+    entry = load_profile(profile)
+
+    # Env-token escape hatch: use an opaque token straight from the environment.
+    env_token = os.environ.get(config.ENV_API_TOKEN)
+    if env_token:
+        api_url = config.resolve_api_url(api_url_flag, entry.get("api_url"))
+        # A 'gpra_' value is an API key; anything else is treated as a bearer.
+        if env_token.startswith("gpra_"):
+            auth = {"type": "api_key", "api_key": env_token}
+        else:
+            auth = {"type": "oauth", "access_token": env_token, "expires_at": None}
+        return AuthContext(profile, api_url, auth)
+
+    auth = entry.get("auth")
+    if not auth:
+        raise AuthError(
+            f"Not logged in (profile '{profile}'). Run 'geopera login' first."
+        )
+
+    api_url = config.resolve_api_url(api_url_flag, entry.get("api_url"))
+
+    # Proactive refresh for OAuth tokens near expiry.
+    if auth.get("type") == "oauth" and _needs_refresh(auth):
+        auth = refresh_oauth(api_url, auth)
+        entry["auth"] = auth
+        entry.setdefault("api_url", api_url)
+        save_profile(profile, entry)
+
+    return AuthContext(profile, api_url, auth)
+
+
+def force_refresh(ctx: AuthContext) -> AuthContext:
+    """Refresh after a 401 and persist. Raises AuthError if not refreshable."""
+    if ctx.is_api_key:
+        raise AuthError("API key rejected (401). Check the key or create a new one.")
+    new_auth = refresh_oauth(ctx.api_url, ctx.auth)
+    entry = load_profile(ctx.profile)
+    entry["auth"] = new_auth
+    entry.setdefault("api_url", ctx.api_url)
+    save_profile(ctx.profile, entry)
+    return AuthContext(ctx.profile, ctx.api_url, new_auth)

geopera_cli/client.py

@@ -0,0 +1,236 @@
+"""Wire-level calls layered over the SDK's AuthenticatedClient.
+
+Two kinds of call live here:
+
+  * Operation dispatch (`invoke_op`) — POST /v1/op/{operation_id}. This goes
+    through the SDK's AuthenticatedClient.get_httpx_client(), which already
+    attaches the right auth header (Bearer or X-API-Key). A single helper
+    therefore reaches every one of the ~227 operations with zero
+    per-op code, honouring the backend-first principle: the CLI sends params,
+    the backend produces output.
+
+  * Identity / OAuth wire (`userinfo`, `device_authorize`, `poll_token`,
+    `logout`) — these are the only endpoints outside the generated op surface,
+    so they are issued with plain httpx against the realm path.
+
+invoke_op transparently refreshes an expired OAuth token once on a 401 and
+retries, so refresh is automatic for every command.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from . import auth, config
+
+
+class OpError(Exception):
+    """An operation returned a problem+json error or other non-2xx response."""
+
+    def __init__(self, status: int, message: str, detail: dict[str, Any] | None = None):
+        self.status = status
+        self.message = message
+        self.detail = detail or {}
+        super().__init__(message)
+
+
+# ---------------------------------------------------------------------------
+# Operation dispatch
+# ---------------------------------------------------------------------------
+
+def invoke_op(ctx: auth.AuthContext, operation_id: str, body: Any) -> Any:
+    """POST /v1/op/{operation_id} with `body`, returning the parsed JSON.
+
+    Uses the SDK's authenticated httpx client. On a 401 with OAuth creds, the
+    token is refreshed once and the call retried.
+    """
+    sdk = ctx.client()
+    url = f"/v1/op/{operation_id}"
+
+    response = sdk.get_httpx_client().request(
+        "post", url, json=body, headers={"Content-Type": "application/json"}
+    )
+
+    if response.status_code == 401 and not ctx.is_api_key:
+        # Token might have expired between proactive check and the call.
+        ctx = auth.force_refresh(ctx)
+        sdk = ctx.client()
+        response = sdk.get_httpx_client().request(
+            "post", url, json=body, headers={"Content-Type": "application/json"}
+        )
+
+    return _parse(response, operation_id)
+
+
+def _parse(response: httpx.Response, operation_id: str) -> Any:
+    """Return parsed JSON on 2xx; raise OpError (problem+json aware) otherwise."""
+    if 200 <= response.status_code < 300:
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+    # Error path — surface problem+json detail/title when present.
+    detail: dict[str, Any] = {}
+    try:
+        detail = response.json()
+    except ValueError:
+        detail = {"raw": response.text}
+
+    message = (
+        detail.get("detail")
+        or detail.get("title")
+        or detail.get("message")
+        or detail.get("error_description")
+        or detail.get("error")
+        or f"{operation_id} failed with HTTP {response.status_code}"
+    )
+    raise OpError(response.status_code, str(message), detail)
+
+
+# ---------------------------------------------------------------------------
+# Identity / OAuth wire (outside the op surface)
+# ---------------------------------------------------------------------------
+
+def userinfo(ctx: auth.AuthContext) -> dict[str, Any]:
+    """GET userinfo with the loaded credentials. Refreshes once on a 401."""
+    url = config.realm_url(ctx.api_url, "userinfo")
+    resp = httpx.get(url, headers=ctx.bearer_headers(), timeout=30.0)
+    if resp.status_code == 401 and not ctx.is_api_key:
+        ctx = auth.force_refresh(ctx)
+        resp = httpx.get(url, headers=ctx.bearer_headers(), timeout=30.0)
+    if resp.status_code != 200:
+        raise OpError(resp.status_code, "userinfo failed — credentials may be invalid")
+    return resp.json()
+
+
+def device_authorize(
+    api_url: str, scope: str, pkce_challenge: str | None = None
+) -> dict[str, Any]:
+    """Start the RFC 8628 device flow. Returns the device authorization response."""
+    data: dict[str, str] = {"client_id": config.CLIENT_ID, "scope": scope}
+    if pkce_challenge:
+        data["code_challenge"] = pkce_challenge
+        data["code_challenge_method"] = "S256"
+
+    resp = httpx.post(
+        config.realm_url(api_url, "auth/device"),
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=30.0,
+    )
+    if resp.status_code != 200:
+        raise OpError(
+            resp.status_code,
+            "Device authorization failed. The server may not support the device "
+            "flow yet — try 'geopera login --api-key <key>' instead.",
+        )
+    return resp.json()
+
+
+# Sentinel returns for poll_token so the caller's loop can branch cleanly.
+PENDING = "authorization_pending"
+SLOW_DOWN = "slow_down"
+
+
+def poll_token(
+    api_url: str,
+    device_code: str,
+    pkce_verifier: str | None = None,
+) -> dict[str, Any] | str:
+    """Poll the token endpoint once.
+
+    Returns the token payload on success, or one of the sentinel strings
+    PENDING / SLOW_DOWN to keep polling. Raises OpError on a terminal error
+    (access_denied, expired_token, ...).
+    """
+    data: dict[str, str] = {
+        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+        "device_code": device_code,
+        "client_id": config.CLIENT_ID,
+    }
+    if pkce_verifier:
+        data["code_verifier"] = pkce_verifier
+
+    resp = httpx.post(
+        config.realm_url(api_url, "token"),
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=30.0,
+    )
+    if resp.status_code == 200:
+        return resp.json()
+
+    try:
+        payload = resp.json()
+    except ValueError:
+        payload = {}
+    err = payload.get("error", "")
+
+    if err == "authorization_pending":
+        return PENDING
+    if err == "slow_down":
+        return SLOW_DOWN
+    if err in ("access_denied", "expired_token"):
+        raise OpError(
+            resp.status_code,
+            {
+                "access_denied": "Login was denied in the browser.",
+                "expired_token": "The login request expired. Run 'geopera login' again.",
+            }[err],
+        )
+    raise OpError(
+        resp.status_code,
+        payload.get("error_description") or err or "Device login failed.",
+    )
+
+
+def logout_oauth(api_url: str, auth_entry: dict[str, Any]) -> None:
+    """Best-effort RP-initiated logout for an OAuth session (ignore failures)."""
+    refresh_token = auth_entry.get("refresh_token")
+    if not refresh_token:
+        return
+    try:
+        httpx.post(
+            config.realm_url(api_url, "logout"),
+            data={"client_id": config.CLIENT_ID, "refresh_token": refresh_token},
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=10.0,
+        )
+    except httpx.HTTPError:
+        pass
+
+
+def wait_for_device_authorization(
+    api_url: str,
+    device: dict[str, Any],
+    pkce_verifier: str | None,
+    on_tick=None,
+) -> dict[str, Any]:
+    """Poll until the user authorizes, the request expires, or it is denied.
+
+    `on_tick` (if given) is called once per poll so the caller can render a
+    spinner. Honours `interval`, `slow_down`, and `expires_in` as the deadline.
+    """
+    interval = int(device.get("interval", 5))
+    deadline = time.time() + int(device.get("expires_in", 600))
+    device_code = device["device_code"]
+
+    while time.time() < deadline:
+        if on_tick:
+            on_tick()
+        time.sleep(interval)
+        result = poll_token(api_url, device_code, pkce_verifier)
+        if result == PENDING:
+            continue
+        if result == SLOW_DOWN:
+            interval += 5
+            continue
+        return result  # token payload
+
+    raise OpError(408, "Login timed out before authorization completed.")

geopera_cli/config.py

@@ -0,0 +1,62 @@
+"""Configuration: defaults, env vars, and the credential store location.
+
+Resolution precedence for the API base URL (highest first):
+    1. an explicit --api-url flag (passed into resolve_api_url)
+    2. the GEOPERA_API_URL environment variable
+    3. the api_url stored in the active profile of credentials.json
+    4. the built-in default (https://api.geopera.com)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Built-in default — the production Geopera API.
+DEFAULT_API_URL = "https://api.geopera.com"
+
+# OAuth realm path prefix. The backend mounts the Keycloak-shaped endpoints
+# at /realms/public/protocol/openid-connect/* (see auth_keycloak.py).
+REALM_PATH = "/realms/public/protocol/openid-connect"
+
+# Public client id the CLI identifies as during the device flow. There is no
+# client secret — this is a public (native) client per RFC 8628.
+CLIENT_ID = "geopera-cli"
+
+# Default OAuth scope requested at login.
+DEFAULT_SCOPE = "openid profile"
+
+# Refresh the access token this many seconds before it actually expires so a
+# command never fires a request with a token that dies mid-flight.
+REFRESH_LEEWAY_SECONDS = 30
+
+# Environment variable names.
+ENV_API_URL = "GEOPERA_API_URL"
+ENV_API_TOKEN = "GEOPERA_API_TOKEN"  # opaque bearer/api-key override (no store)
+ENV_PROFILE = "GEOPERA_PROFILE"
+
+# Credential store: ~/.config/geopera/credentials.json (dir 0700, file 0600).
+CONFIG_DIR = Path(os.path.expanduser("~")) / ".config" / "geopera"
+CREDENTIALS_PATH = CONFIG_DIR / "credentials.json"
+
+DEFAULT_PROFILE = "default"
+
+
+def resolve_profile(flag_profile: str | None = None) -> str:
+    """Resolve the active profile name: --profile > GEOPERA_PROFILE > default."""
+    return flag_profile or os.environ.get(ENV_PROFILE) or DEFAULT_PROFILE
+
+
+def resolve_api_url(flag_api_url: str | None, stored_api_url: str | None) -> str:
+    """Resolve the API base URL by precedence (see module docstring)."""
+    return (
+        flag_api_url
+        or os.environ.get(ENV_API_URL)
+        or stored_api_url
+        or DEFAULT_API_URL
+    ).rstrip("/")
+
+
+def realm_url(api_url: str, endpoint: str) -> str:
+    """Build a full OAuth endpoint URL, e.g. realm_url(api, 'token')."""
+    return f"{api_url.rstrip('/')}{REALM_PATH}/{endpoint.lstrip('/')}"

geopera_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: geopera-cli
+Version: 0.1.0
+Summary: Command-line interface for the Geopera geospatial data platform
+Project-URL: Homepage, https://docs.geopera.com
+Project-URL: Documentation, https://docs.geopera.com/cli
+Project-URL: Source, https://github.com/geo-pera/geopera-cli
+Author-email: Geopera <support@geopera.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,earth-observation,geopera,geospatial,satellite,stac
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: geopera>=2.0.0
+Requires-Dist: httpx<0.29.0,>=0.23.1
+Requires-Dist: typer[all]>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# geopera-cli
+
+Command-line interface for the [Geopera](https://docs.geopera.com) geospatial
+data platform.
+
+`geopera-cli` is a **thin auth + dispatch shell** over the published
+[`geopera` Python SDK](https://github.com/geo-pera/geopera-python). The only
+logic that lives in the CLI is authentication — the OAuth device flow, token
+refresh, and the choice between a `Bearer` token and an `X-API-Key` header.
+Every actual capability is reached through the generic API endpoint
+`POST /v1/op/{operation_id}`, so any of the ~227 operations is callable with no
+per-command code, and a new backend operation is instantly usable as
+`geopera op <new.op>` with zero CLI changes.
+
+## Install
+
+```bash
+pip install geopera-cli
+```
+
+This pulls in the `geopera` SDK, `typer`, and `httpx`.
+
+## Quick start
+
+```bash
+# Sign in (opens your browser; RFC 8628 device flow)
+geopera login
+
+# Who am I?
+geopera whoami
+
+# Price-preview an order (generic op dispatch)
+geopera op orders.estimate '{"aoi": {...}, "product": "..."}'
+
+# Search across every registered public data source
+geopera op catalog.federated_search '{"bbox": [...], "datetime": "..."}'
+
+# List every available operation id
+geopera op --list
+
+# Curated alias with table output
+geopera orders list
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `geopera login` | Device-flow login (default). `--api-key KEY` stores a key instead (`-` reads from stdin). `--api-url URL`, `--no-browser`, `--scope`. |
+| `geopera logout` | Clear the active profile's stored credentials (best-effort OAuth logout). |
+| `geopera whoami` | Show principal / org / scope (validates the session). `--json` for raw output. |
+| `geopera op OPERATION_ID [JSON]` | Generic operation dispatch. Body from positional arg, `--file`, or `-` (stdin). `--list` enumerates operations. |
+| `geopera orders list` | Curated alias over `op orders.list` with table formatting. |
+
+Global flags `--profile NAME` (env `GEOPERA_PROFILE`) and `--api-url URL`
+(env `GEOPERA_API_URL`) are accepted on every command.
+
+## Authentication
+
+### Device flow (default)
+
+`geopera login` performs the OAuth 2.0 Device Authorization Grant
+([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)) with PKCE:
+
+1. Requests a device + user code from
+   `{api_url}/realms/public/protocol/openid-connect/auth/device`.
+2. Prints the user code and opens the verification URL in your browser
+   (skip with `--no-browser`).
+3. Polls the token endpoint until you approve, then stores the access and
+   refresh tokens.
+
+Access tokens are refreshed automatically — proactively when within 30s of
+expiry, and reactively on any `401` — using the stored refresh token. The
+backend rotates the refresh token, so both tokens are rewritten on each
+refresh.
+
+### API key (headless)
+
+```bash
+geopera login --api-key gpra_xxxxxxxx
+# or, keeping the key out of shell history:
+printf '%s' "$GEOPERA_KEY" | geopera login --api-key -
+```
+
+API keys are sent as `X-API-Key`, which the Geopera API accepts on every
+authenticated endpoint.
+
+### Profiles
+
+Multiple identities are namespaced by profile:
+
+```bash
+geopera login --profile staging --api-url https://staging.api.geopera.com
+geopera --help                      # default profile
+GEOPERA_PROFILE=staging geopera whoami
+geopera whoami --profile staging
+```
+
+## Credential store
+
+Credentials live in `~/.config/geopera/credentials.json` (directory `0700`,
+file `0600`). Each top-level key is a profile:
+
+```json
+{
+  "default": {
+    "api_url": "https://api.geopera.com",
+    "auth": {
+      "type": "oauth",
+      "access_token": "...",
+      "refresh_token": "...",
+      "expires_at": 1750000000,
+      "scope": "openid profile",
+      "issuer": "https://api.geopera.com"
+    }
+  }
+}
+```
+
+For an API key profile the `auth` block is
+`{"type": "api_key", "api_key": "gpra_..."}`.
+
+### Environment overrides
+
+- `GEOPERA_API_URL` — base URL override (below `--api-url`, above the stored value).
+- `GEOPERA_PROFILE` — active profile name.
+- `GEOPERA_API_TOKEN` — opaque bearer/API-key for ephemeral (e.g. CI) use,
+  bypassing the store. A value starting with `gpra_` is treated as an API key.
+
+## Configuration precedence
+
+API base URL: `--api-url` flag → `GEOPERA_API_URL` → stored `api_url` →
+`https://api.geopera.com`.
+
+## License
+
+[MIT](./LICENSE)

geopera_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+geopera_cli/__init__.py,sha256=71Q9Wo9NP-hf96zJxPrM1a2iRQ38sXBRXIpRTXH_6RM,319
+geopera_cli/__main__.py,sha256=ltXT9i1VjiI4O_zLeK7eR3b7mm2wDBq2UrPSNJJZ-WE,13048
+geopera_cli/auth.py,sha256=6tDHlOaEqSvQsLNVZvFe5HtI1KNhGFh1tizz4VJKhb8,9592
+geopera_cli/client.py,sha256=JrYfixGVASARxzvo0XY228m8WpQG3XiLuHAApWjlakA,8010
+geopera_cli/config.py,sha256=HMN2Gjj521rQ2Bu8kaxJz_dPmc2HhwNIjpDToR36NQE,2280
+geopera_cli-0.1.0.dist-info/METADATA,sha256=yPKePVHuDWtBqDyHY9esO1OKf8QUTXg4A0bEXw2vgvk,5608
+geopera_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+geopera_cli-0.1.0.dist-info/entry_points.txt,sha256=9G1qBmi1YwTZQFqHdk0XC1oJ-tnSsstLo8GfqSLagFE,53
+geopera_cli-0.1.0.dist-info/licenses/LICENSE,sha256=5_TRQYmq2hkTIf7YKP9NeurTh9GhCpxzpAkxRTGBcGs,1064
+geopera_cli-0.1.0.dist-info/RECORD,,

geopera_cli-0.1.0.dist-info/WHEEL

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

geopera_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+geopera = geopera_cli.__main__:app

geopera_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geopera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.