kctl-api 0.2.0__py3-none-any.whl

kctl_api/core/client.py

@@ -0,0 +1,190 @@
+"""REST API client using httpx.
+
+Synchronous client for api-main and ai-main endpoints.
+Supports JWT bearer token and API key authentication.
+
+Subclasses :class:`kctl_lib.api_client.APIClient` and keeps dual-auth
+(JWT + API key) as a service-specific override of ``_build_auth_header``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from kctl_lib.api_client import APIClient
+from kctl_lib.exceptions import AuthenticationError
+from kctl_lib.exceptions import ConnectionError as KctlConnectionError
+
+from kctl_api.core.exceptions import APIError
+
+
+class ApiClient(APIClient):
+    """Synchronous httpx client for Kodemeio REST APIs.
+
+    Extends the kctl-lib base with dual-auth support (JWT bearer token
+    **or** API key via ``X-API-Key`` header) and service-specific helpers
+    such as ``login``, ``refresh``, ``upload``, and ``stream_sse``.
+    """
+
+    AUTH_HEADER: str = "Authorization"
+    AUTH_PREFIX: str = "Bearer"
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str = "",
+        jwt_token: str = "",
+        timeout: float = 30.0,
+    ):
+        # Resolve the primary credential for the base class.
+        # JWT takes precedence; fall back to API key.
+        credential = jwt_token or api_key or "none"
+
+        # Store extras *before* super().__init__ since _build_auth_header
+        # is called during construction.
+        self._api_key = api_key
+        self._jwt_token = jwt_token
+        self._refresh_token: str = ""
+
+        if not base_url:
+            raise KctlConnectionError(
+                "(not configured)",
+                ValueError("No API URL configured. Run: kctl-api config init"),
+            )
+
+        super().__init__(
+            base_url=base_url,
+            credential=credential,
+            timeout=timeout,
+        )
+
+        # Override follow_redirects (base class doesn't set it)
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=self._build_auth_header(),
+            timeout=timeout,
+            follow_redirects=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Auth override — dual-auth (JWT or API key)
+    # ------------------------------------------------------------------
+
+    def _build_auth_header(self) -> dict[str, str]:
+        """Build authentication headers supporting JWT and API key."""
+        if self._jwt_token:
+            return {"Authorization": f"Bearer {self._jwt_token}"}
+        if self._api_key:
+            return {"X-API-Key": self._api_key}
+        return {}
+
+    # ------------------------------------------------------------------
+    # Error mapping override — use local APIError that wraps httpx.Response
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, endpoint: str, **kwargs: Any) -> httpx.Response:
+        """Override to use kctl-api's APIError (wraps httpx.Response)."""
+        try:
+            return super()._request(method, endpoint, **kwargs)
+        except KctlConnectionError:
+            raise
+        except AuthenticationError:
+            raise
+        except Exception as exc:
+            # Re-raise kctl-lib APIError as the local response-aware variant
+            from kctl_lib.exceptions import APIError as BaseAPIError
+
+            if isinstance(exc, BaseAPIError):
+                raise APIError(detail=exc.detail) from exc
+            raise
+
+    # ------------------------------------------------------------------
+    # Service-specific methods
+    # ------------------------------------------------------------------
+
+    def upload(self, path: str, file_path: str, **kwargs: Any) -> Any:
+        """Upload a file via multipart POST."""
+        url = path
+        headers = self._build_auth_header()
+        # Remove Content-Type for multipart — httpx sets it automatically
+        headers.pop("Content-Type", None)
+
+        with open(file_path, "rb") as f:
+            try:
+                response = self._client.post(
+                    url,
+                    headers=headers,
+                    files={"file": f},
+                    **kwargs,
+                )
+            except httpx.ConnectError as e:
+                raise KctlConnectionError(self._base_url, e) from e
+
+        if response.status_code == 401:
+            raise AuthenticationError("Authentication failed.")
+        if response.status_code >= 400:
+            raise APIError(response)
+
+        return response.json()
+
+    def stream_sse(self, path: str, **kwargs: Any) -> Any:
+        """Open an SSE stream. Returns a context manager -- use with ``with``.
+
+        Usage::
+
+            with client.stream_sse("/api/v1/ai/chat/stream") as response:
+                for line in response.iter_lines():
+                    ...
+        """
+        url = path
+        headers = {**self._build_auth_header(), "Accept": "text/event-stream"}
+
+        try:
+            return self._client.stream("GET", url, headers=headers, **kwargs)
+        except httpx.ConnectError as e:
+            raise KctlConnectionError(self._base_url, e) from e
+
+    def login(self, email: str, password: str) -> dict[str, str]:
+        """Authenticate and obtain JWT tokens.
+
+        Returns: {"access_token": "...", "refresh_token": "..."}
+        """
+        data = self.post(
+            "/api/v1/auth/login",
+            json={"email": email, "password": password},
+        )
+        self._jwt_token = data.get("access_token", "")
+        self._refresh_token = data.get("refresh_token", "")
+        # Update client headers with new token
+        self._client.headers.update(self._build_auth_header())
+        return data
+
+    def refresh(self) -> dict[str, str]:
+        """Refresh JWT access token using the refresh token."""
+        if not self._refresh_token:
+            raise AuthenticationError("No refresh token available. Run: kctl-api auth login")
+        data = self.post(
+            "/api/v1/auth/refresh",
+            json={"refresh_token": self._refresh_token},
+        )
+        self._jwt_token = data.get("access_token", self._jwt_token)
+        # Update client headers with new token
+        self._client.headers.update(self._build_auth_header())
+        return data
+
+    def health_check(self) -> tuple[bool, dict]:
+        """Check API health. Returns (is_healthy, details)."""
+        try:
+            data = self.get("/api/v1/health")
+            return data.get("status") == "ok", data
+        except Exception as e:
+            return False, {"status": "error", "error": str(e)}
+
+    def for_url(self, base_url: str) -> ApiClient:
+        """Create a new client for a different base URL (same auth)."""
+        return ApiClient(
+            base_url=base_url,
+            api_key=self._api_key,
+            jwt_token=self._jwt_token,
+        )

kctl_api/core/config.py

@@ -0,0 +1,260 @@
+"""Profile management and configuration resolution for kctl-api.
+
+ServiceConfig and resolve_connection() are API-specific and kept here.
+Profile framework functions delegate to kctl-lib.config; low-level I/O
+(load_raw_config, save_raw_config) are kept locally so that the module-level
+CONFIG_FILE / CONFIG_DIR names can be patched in tests.
+
+Config format:
+  profiles:
+    production:
+      api:                   # <- kctl-api reads this
+        url: https://api.kodeme.io
+        ai_url: https://ai.kodeme.io
+        api_key: <key>
+        database_url: postgresql+asyncpg://...
+        redis_url: redis://...
+      odoo:                  # <- kctl-odoo reads this
+        url: https://erp.kodeme.io
+        ...
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import kctl_lib.config as _common
+import yaml
+from kctl_lib.config import (
+    ConfigFile,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    remove_profile,
+    set_default_profile,
+)
+from kctl_lib.config import (
+    is_service_scoped as _is_service_scoped,
+)
+from pydantic import BaseModel
+
+__all__ = [
+    "CONFIG_DIR",
+    "CONFIG_FILE",
+    "SERVICE_KEY",
+    "ConfigFile",
+    "ServiceConfig",
+    "_is_service_scoped",
+    "get_all_services_in_profile",
+    "get_default_profile",
+    "get_profile_names",
+    "get_project_root_from_config",
+    "get_service_config",
+    "load_config",
+    "load_raw_config",
+    "remove_profile",
+    "resolve_active_profile_name",
+    "resolve_connection",
+    "save_raw_config",
+    "set_default_profile",
+    "set_service_config",
+]
+
+CONFIG_DIR: Path = _common.CONFIG_DIR
+CONFIG_FILE: Path = _common.CONFIG_FILE
+
+# This CLI's service key.
+SERVICE_KEY = "api"
+
+# Env-prefix used for KCTL_API_PROFILE / KCTL_API_URL etc.
+_ENV_PREFIX = "KCTL_API"
+
+
+class ServiceConfig(BaseModel):
+    """API-specific service config within a profile."""
+
+    url: str = ""
+    ai_url: str = ""
+    api_key: str = ""
+    database_url: str = ""
+    redis_url: str = ""
+    project_root: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Low-level I/O — kept local so CONFIG_FILE/CONFIG_DIR are patchable in tests.
+# ---------------------------------------------------------------------------
+
+
+def load_raw_config() -> dict[str, Any]:
+    """Load raw YAML config from disk."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(CONFIG_FILE) as f:
+            return yaml.safe_load(f) or {}
+    except (yaml.YAMLError, OSError) as e:
+        print(f"WARN: Cannot read {CONFIG_FILE}: {e}", file=sys.stderr)
+        return {}
+
+
+def save_raw_config(data: dict[str, Any]) -> None:
+    """Write raw config dict to YAML file."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def load_config() -> ConfigFile:
+    """Load and validate the config file."""
+    data = load_raw_config()
+    return ConfigFile(
+        default_profile=data.get("default_profile", "default"),
+        profiles=data.get("profiles", {}),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Profile framework — delegates to kctl-lib where possible.
+# ---------------------------------------------------------------------------
+
+
+def get_service_config(profile_name: str) -> ServiceConfig:
+    """Get this CLI's service config from a profile."""
+    cfg = load_config()
+    profile_data = cfg.profiles.get(profile_name, {})
+    if not profile_data:
+        return ServiceConfig()
+
+    if _is_service_scoped(profile_data):
+        svc_data = profile_data.get(SERVICE_KEY, {})
+        if not isinstance(svc_data, dict):
+            return ServiceConfig()
+        raw: dict[str, Any] = dict(svc_data)
+    else:
+        raw = dict(profile_data)
+
+    # Expand env vars
+    for k, v in raw.items():
+        if isinstance(v, str):
+            raw[k] = _common.expand_env(v)
+
+    valid = list(ServiceConfig.model_fields)
+    raw = {k: v for k, v in raw.items() if k in valid}
+    return ServiceConfig(**raw) if raw else ServiceConfig()
+
+
+def set_service_config(profile_name: str, svc_config: ServiceConfig) -> None:
+    """Write this CLI's service config into a profile (always scoped format)."""
+    data = load_raw_config()
+    if "profiles" not in data:
+        data["profiles"] = {}
+    if profile_name not in data["profiles"]:
+        data["profiles"][profile_name] = {}
+
+    profile = data["profiles"][profile_name]
+
+    if not _is_service_scoped(profile):
+        old_data = dict(profile)
+        profile.clear()
+        profile[SERVICE_KEY] = old_data
+
+    svc_data = svc_config.model_dump(exclude_defaults=False)
+    svc_data = {k: v for k, v in svc_data.items() if v}
+    profile[SERVICE_KEY] = svc_data
+    save_raw_config(data)
+
+
+def get_project_root_from_config(profile_name: str | None = None) -> Path | None:
+    """Read project_root from the active config profile.
+
+    Returns None if not configured or the directory does not exist.
+    """
+    pname = resolve_active_profile_name(profile_name)
+    svc = get_service_config(pname)
+    if svc.project_root:
+        root = Path(_common.expand_env(svc.project_root)).expanduser()
+        if root.is_dir():
+            return root
+    # Also check env var
+    if env_root := os.environ.get("KCTL_API_REPO"):
+        root = Path(env_root)
+        if root.is_dir():
+            return root
+    return None
+
+
+def resolve_active_profile_name(profile_name: str | None = None) -> str:
+    """Resolve the active profile name from all sources."""
+    if profile_name:
+        return profile_name
+    if env := os.environ.get("KCTL_API_PROFILE"):
+        return env
+    return get_default_profile()
+
+
+def resolve_connection(
+    profile_name: str | None = None,
+    url_override: str | None = None,
+    ai_url_override: str | None = None,
+    api_key_override: str | None = None,
+    database_url_override: str | None = None,
+    redis_url_override: str | None = None,
+) -> tuple[str, str, str, str, str]:
+    """Resolve API URL, AI URL, API key, database URL, and Redis URL.
+
+    Returns: (url, ai_url, api_key, database_url, redis_url)
+
+    Priority:
+    1. CLI flags (overrides)
+    2. KCTL_API_URL / KCTL_API_AI_URL / KCTL_API_KEY / KCTL_API_DATABASE_URL / KCTL_API_REDIS_URL
+    3. Profile's api service config
+    """
+    url = ""
+    ai_url = ""
+    api_key = ""
+    database_url = ""
+    redis_url = ""
+
+    # 3. Config file profile (service-scoped)
+    pname = resolve_active_profile_name(profile_name)
+    svc = get_service_config(pname)
+    if svc.url:
+        url = svc.url
+    if svc.ai_url:
+        ai_url = svc.ai_url
+    if svc.api_key:
+        api_key = svc.api_key
+    if svc.database_url:
+        database_url = svc.database_url
+    if svc.redis_url:
+        redis_url = svc.redis_url
+
+    # 2. Environment variables
+    if env_url := os.environ.get("KCTL_API_URL"):
+        url = env_url
+    if env_ai_url := os.environ.get("KCTL_API_AI_URL"):
+        ai_url = env_ai_url
+    if env_key := os.environ.get("KCTL_API_KEY"):
+        api_key = env_key
+    if env_db := os.environ.get("KCTL_API_DATABASE_URL"):
+        database_url = env_db
+    if env_redis := os.environ.get("KCTL_API_REDIS_URL"):
+        redis_url = env_redis
+
+    # 1. CLI flags
+    if url_override:
+        url = url_override
+    if ai_url_override:
+        ai_url = ai_url_override
+    if api_key_override:
+        api_key = api_key_override
+    if database_url_override:
+        database_url = database_url_override
+    if redis_url_override:
+        redis_url = redis_url_override
+
+    return url, ai_url, api_key, database_url, redis_url

kctl_api/core/db.py

@@ -0,0 +1,65 @@
+"""Lazy async SQLAlchemy engine for direct database access.
+
+Requires the ``db`` extra: ``pip install kctl-api[db]``
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_engines: dict[str, Any] = {}
+
+
+def get_engine(database_url: str) -> Any:
+    """Get or create an async engine keyed by URL.
+
+    Raises ImportError if sqlalchemy/asyncpg are not installed.
+    """
+    if database_url in _engines:
+        return _engines[database_url]
+
+    try:
+        from sqlalchemy.ext.asyncio import create_async_engine
+    except ImportError as e:
+        raise ImportError("Database support requires the 'db' extra. Install with: pip install kctl-api[db]") from e
+
+    engine = create_async_engine(
+        database_url,
+        pool_size=1,
+        max_overflow=0,
+        echo=False,
+    )
+    _engines[database_url] = engine
+    return engine
+
+
+async def dispose_engine() -> None:
+    """Dispose all cached engines (call during cleanup)."""
+    for engine in _engines.values():
+        await engine.dispose()
+    _engines.clear()
+
+
+_VALID_IDENTIFIER = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def validate_identifier(name: str) -> str:
+    """Validate a SQL identifier (table/column name) to prevent injection.
+
+    Returns the name if valid, raises ValueError otherwise.
+    """
+    if not _VALID_IDENTIFIER.match(name):
+        raise ValueError(f"Invalid SQL identifier: {name!r}")
+    return name
+
+
+async def execute_query(database_url: str, query: str) -> list[dict]:
+    """Execute a raw SQL query and return rows as list of dicts."""
+    from sqlalchemy import text
+
+    engine = get_engine(database_url)
+    async with engine.connect() as conn:
+        result = await conn.execute(text(query))
+        columns = list(result.keys())
+        return [dict(zip(columns, row, strict=False)) for row in result.fetchall()]

kctl_api/core/exceptions.py

@@ -0,0 +1,43 @@
+"""Exception hierarchy for kctl-api — thin re-exports from kctl-lib.
+
+APIError is kept locally because it wraps httpx.Response.
+"""
+
+from __future__ import annotations
+
+import httpx
+from kctl_lib.exceptions import (
+    AuthenticationError,
+    ConfigError,
+    ConnectionError,
+    KctlError,
+    NotFoundError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConfigError",
+    "ConnectionError",
+    "KctlError",
+    "NotFoundError",
+]
+
+
+class APIError(KctlError):
+    """REST API error with response details."""
+
+    def __init__(self, response: httpx.Response | None = None, detail: str = ""):
+        if response is not None:
+            self.status_code = response.status_code
+            self.response = response
+            try:
+                body = response.json()
+                self.detail = body.get("error", "") or body.get("detail", "") or str(body)
+            except Exception:
+                self.detail = response.text or f"HTTP {self.status_code}"
+        else:
+            self.status_code = 0
+            self.response = None
+            self.detail = detail
+        super().__init__(f"API error: {self.detail}")

kctl_api/core/output.py

@@ -0,0 +1,5 @@
+"""Output handler — re-exported from kctl-lib."""
+
+from kctl_lib.output import Output
+
+__all__ = ["Output"]

kctl_api/core/plugins.py

@@ -0,0 +1,26 @@
+"""Plugin discovery for kctl-api — thin wrapper over kctl-lib.
+
+Third-party packages register kctl-api plugins via the ``kctl_api.plugins``
+entry point group.  Each entry point must resolve to a class implementing
+:class:`KctlPlugin`.
+
+Example ``pyproject.toml`` snippet for a plugin package::
+
+    [project.entry-points."kctl_api.plugins"]
+    my_plugin = "my_package.plugin:MyPlugin"
+"""
+
+from __future__ import annotations
+
+import typer
+from kctl_lib.plugins import KctlPlugin
+from kctl_lib.plugins import discover_and_load_plugins as _discover
+
+__all__ = ["ENTRY_POINT_GROUP", "KctlPlugin", "discover_and_load_plugins"]
+
+ENTRY_POINT_GROUP = "kctl_api.plugins"
+
+
+def discover_and_load_plugins(app: typer.Typer) -> list[str]:
+    """Discover kctl-api plugins via entry points and register them."""
+    return _discover(app, ENTRY_POINT_GROUP)

kctl_api/core/redis.py

@@ -0,0 +1,35 @@
+"""Lazy Redis client for direct Redis access.
+
+Requires the ``redis`` extra: ``pip install kctl-api[redis]``
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_redis_clients: dict[str, Any] = {}
+
+
+def get_redis(redis_url: str) -> Any:
+    """Get or create a Redis client keyed by URL.
+
+    Raises ImportError if redis is not installed.
+    """
+    if redis_url in _redis_clients:
+        return _redis_clients[redis_url]
+
+    try:
+        from redis.asyncio import Redis
+    except ImportError as e:
+        raise ImportError("Redis support requires the 'redis' extra. Install with: pip install kctl-api[redis]") from e
+
+    client = Redis.from_url(redis_url, decode_responses=True)
+    _redis_clients[redis_url] = client
+    return client
+
+
+async def close_redis() -> None:
+    """Close all cached Redis clients."""
+    for client in _redis_clients.values():
+        await client.aclose()
+    _redis_clients.clear()

kctl_api/core/resolve.py

@@ -0,0 +1,47 @@
+"""Shared identifier resolution utilities for API resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from kctl_api.core.client import ApiClient
+
+
+def resolve_user(
+    client: ApiClient,
+    identifier: str,
+) -> dict:
+    """Resolve a user by numeric ID or email.
+
+    Returns the full user dict from the API.
+    Raises ``typer.Exit(1)`` when the user cannot be found.
+    """
+    # Try numeric ID first
+    if identifier.isdigit():
+        try:
+            return client.get(f"/api/v1/users/{identifier}")
+        except Exception as exc:
+            typer.echo(f"User not found: {identifier}", err=True)
+            raise typer.Exit(1) from exc
+
+    # Search by email via list endpoint
+    data = client.get("/api/v1/users", params={"search": identifier, "per_page": 1})
+    items = data.get("items", []) if isinstance(data, dict) else []
+    if not items:
+        typer.echo(f"User not found: {identifier}", err=True)
+        raise typer.Exit(1)
+    return items[0]
+
+
+def resolve_user_id(
+    client: ApiClient,
+    identifier: str,
+) -> int:
+    """Resolve a user identifier to a numeric ID."""
+    if identifier.isdigit():
+        return int(identifier)
+    user = resolve_user(client, identifier)
+    return user["id"]