appliku 0.1.0__py3-none-any.whl

appliku/__init__.py

@@ -0,0 +1,108 @@
+"""Appliku — Python CLI and SDK for the Appliku platform."""
+
+from appliku._exceptions import (
+    AplikuError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from appliku._main import Appliku
+from appliku._models import (
+    AdvancedLogsResponse,
+    App,
+    AppCreate,
+    AppLogsRequest,
+    AppUpdate,
+    Cluster,
+    ClusterCreate,
+    ConfigVarsResponse,
+    CronJob,
+    CronJobCreate,
+    CronJobUpdate,
+    Datastore,
+    DatastoreCreate,
+    DatastoreLogsResponse,
+    Deployment,
+    Domain,
+    DomainCreate,
+    Invite,
+    InviteCreate,
+    LogEntry,
+    LogsRequestResponse,
+    Migration,
+    MigrationRun,
+    NginxLogsRequest,
+    NginxLogsResponse,
+    PaginatedResponse,
+    Server,
+    ServerCreateCustom,
+    ServerCreateDO,
+    ServerCreateEC2,
+    ServiceLogsResponse,
+    Team,
+    TeamCreate,
+    TeamUpdate,
+    UserInfo,
+    Volume,
+    VolumeCreate,
+    VolumeUpdate,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main client
+    "Appliku",
+    # Exceptions
+    "AplikuError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Models — Resources
+    "Team",
+    "TeamCreate",
+    "TeamUpdate",
+    "App",
+    "AppCreate",
+    "AppUpdate",
+    "ConfigVarsResponse",
+    "Deployment",
+    "LogEntry",
+    "Datastore",
+    "DatastoreCreate",
+    "Domain",
+    "DomainCreate",
+    "Volume",
+    "VolumeCreate",
+    "VolumeUpdate",
+    "CronJob",
+    "CronJobCreate",
+    "CronJobUpdate",
+    "Cluster",
+    "ClusterCreate",
+    "Server",
+    "ServerCreateDO",
+    "ServerCreateEC2",
+    "ServerCreateCustom",
+    "Invite",
+    "InviteCreate",
+    "Migration",
+    "MigrationRun",
+    # Models — Logs
+    "AdvancedLogsResponse",
+    "AppLogsRequest",
+    "DatastoreLogsResponse",
+    "LogsRequestResponse",
+    "NginxLogsRequest",
+    "NginxLogsResponse",
+    "ServiceLogsResponse",
+    # Models — Common
+    "PaginatedResponse",
+    "UserInfo",
+]

appliku/_auth.py

@@ -0,0 +1,167 @@
+"""Token resolution and config persistence."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+import webbrowser
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import httpx
+import tomli_w
+
+CONFIG_PATH = Path.home() / ".config" / "appliku" / "config.toml"
+API_BASE_URL = "https://api.appliku.com"
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    """Load a TOML file, compatible with Python 3.10+."""
+    if sys.version_info >= (3, 11):
+        import tomllib
+
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    else:
+        import tomli  # type: ignore[import-not-found]
+
+        with open(path, "rb") as f:
+            return tomli.load(f)  # type: ignore[no-any-return]
+
+
+def resolve_token(explicit_token: str | None = None) -> str | None:
+    """Priority: explicit param > APPLIKU_TOKEN env > config file."""
+    if explicit_token:
+        return explicit_token
+    env = os.environ.get("APPLIKU_TOKEN")
+    if env:
+        return env
+    return _read_config_token()
+
+
+def _read_config_token() -> str | None:
+    """Read token from ~/.config/appliku/config.toml."""
+    if not CONFIG_PATH.exists():
+        return None
+    try:
+        data = _load_toml(CONFIG_PATH)
+        auth_section = data.get("auth", {})
+        token = auth_section.get("token") if isinstance(auth_section, dict) else None
+        return str(token) if token is not None else None
+    except Exception:
+        return None
+
+
+def save_token(token: str) -> None:
+    """Persist token to config file."""
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data: dict[str, Any] = {"auth": {"token": token}}
+    with open(CONFIG_PATH, "wb") as f:
+        tomli_w.dump(data, f)
+
+
+class DeviceAuthFlow:
+    """Handles the browser-based device authorization flow."""
+
+    def __init__(self, base_url: str | None = None) -> None:
+        self.base_url = base_url or API_BASE_URL
+        self.device_code: str | None = None
+        self.user_code: str | None = None
+        self.verification_url: str | None = None
+        self.verification_url_complete: str | None = None
+        self.expires_in: int = 0
+        self.interval: int = 5
+        self._client = httpx.Client(base_url=self.base_url, timeout=30.0)
+
+    def initiate(self) -> None:
+        """Start the device authorization flow."""
+        response = self._client.post(
+            "/api/cli/auth/initiate/",
+            json={"client_name": "Appliku CLI"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        self.device_code = data["device_code"]
+        self.user_code = data["user_code"]
+        self.verification_url = data["verification_url"]
+        self.verification_url_complete = data["verification_url_complete"]
+        self.expires_in = data["expires_in"]
+        self.interval = data.get("interval", 5)
+
+    def open_browser(self) -> bool:
+        """Attempt to open the browser. Returns True if successful."""
+        if self.verification_url_complete:
+            try:
+                webbrowser.open(self.verification_url_complete)
+                return True
+            except Exception:
+                return False
+        return False
+
+    def poll(self) -> tuple[str, str | None]:
+        """
+        Poll for authorization status.
+        Returns (status, api_token).
+        Status: 'pending', 'authorized', 'denied', 'expired'
+        """
+        if not self.device_code:
+            raise RuntimeError("Must call initiate() first")
+
+        response = self._client.post(
+            "/api/cli/auth/poll/",
+            json={"device_code": self.device_code},
+        )
+
+        if response.status_code == 202:
+            return ("pending", None)
+        elif response.status_code == 200:
+            data = response.json()
+            return (data["status"], data.get("api_token"))
+        elif response.status_code == 410:
+            return ("expired", None)
+        elif response.status_code == 403:
+            return ("denied", None)
+        elif response.status_code == 404:
+            return ("expired", None)
+        else:
+            response.raise_for_status()
+            return ("error", None)
+
+    def wait_for_authorization(
+        self,
+        on_pending: Callable[[int], None] | None = None,
+        timeout: int | None = None,
+    ) -> str | None:
+        """
+        Poll until authorized, denied, or expired.
+        Returns the API token if authorized, None otherwise.
+        on_pending is called with seconds_elapsed on each poll.
+        """
+        start_time = time.time()
+        effective_timeout = timeout or self.expires_in
+
+        while True:
+            elapsed = int(time.time() - start_time)
+
+            if elapsed > effective_timeout:
+                return None
+
+            status, token = self.poll()
+
+            if status == "authorized":
+                return token
+            elif status in ("denied", "expired"):
+                return None
+            elif status == "pending":
+                if on_pending:
+                    on_pending(elapsed)
+                time.sleep(self.interval)
+            else:
+                return None
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()

appliku/_client.py

@@ -0,0 +1,142 @@
+"""Core HTTP client — the backbone of the SDK."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterator
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+import httpx
+
+from ._exceptions import AplikuError, parse_error_response
+from ._models import PaginatedResponse
+
+
+@runtime_checkable
+class _Validatable(Protocol):
+    @classmethod
+    def model_validate(cls, data: Any) -> Any: ...
+
+
+T = TypeVar("T", bound=_Validatable)
+BASE_URL = "https://api.appliku.com"
+MAX_RETRIES = 3
+
+
+class AplikuClient:
+    """Low-level HTTP client. Handles auth, retries, error parsing."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+        self._session = httpx.Client(
+            base_url=BASE_URL,
+            timeout=30.0,
+            headers={
+                "Authorization": f"Token {token}",
+                "Accept": "application/json",
+            },
+        )
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Execute request with retry logic (429 + 5xx).
+
+        Retry strategy: up to MAX_RETRIES attempts. On 429, respect Retry-After header.
+        On 5xx, exponential backoff (1s, 2s, 4s). Raises on final failure.
+        """
+        last_exc: AplikuError | None = None
+
+        for attempt in range(MAX_RETRIES):
+            response = self._session.request(method, path, **kwargs)
+
+            if response.status_code < 400:
+                return response
+
+            # Try to parse JSON body for error details
+            try:
+                body = response.json()
+            except Exception:
+                body = {"detail": response.text}
+
+            exc = parse_error_response(response.status_code, body)
+
+            if response.status_code == 429:
+                retry_after = int(response.headers.get("retry-after", "1"))
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep(retry_after)
+                    last_exc = exc
+                    continue
+                raise exc
+
+            if response.status_code >= 500:
+                if attempt < MAX_RETRIES - 1:
+                    time.sleep(2**attempt)  # 1s, 2s, 4s
+                    last_exc = exc
+                    continue
+                raise exc
+
+            # 4xx (except 429) — don't retry
+            raise exc
+
+        # Should not reach here, but just in case
+        if last_exc:
+            raise last_exc
+        raise AplikuError("Request failed after retries")  # pragma: no cover
+
+    def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._request("GET", path, **kwargs)
+        return response.json()  # type: ignore[no-any-return]
+
+    def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._request("POST", path, **kwargs)
+        return response.json()  # type: ignore[no-any-return]
+
+    def put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._request("PUT", path, **kwargs)
+        return response.json()  # type: ignore[no-any-return]
+
+    def patch(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        response = self._request("PATCH", path, **kwargs)
+        return response.json()  # type: ignore[no-any-return]
+
+    def delete(self, path: str) -> None:
+        self._request("DELETE", path)
+
+    def paginate(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        response_type: type[T] = ...,  # type: ignore[assignment]
+    ) -> PaginatedResponse[T]:
+        """Fetch one page, return PaginatedResponse with parsed models."""
+        data = self.get(path, params=params)
+        results = [response_type.model_validate(item) for item in data.get("results", [])]
+        return PaginatedResponse(
+            count=data.get("count", len(results)),
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=results,
+        )
+
+    def paginate_all(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        response_type: type[T] = ...,  # type: ignore[assignment]
+    ) -> Iterator[T]:
+        """Auto-follow pagination, yield individual items."""
+        current_path: str | None = path
+        current_params = params
+        while current_path is not None:
+            data = self.get(current_path, params=current_params)
+            for item in data.get("results", []):
+                yield response_type.model_validate(item)
+            next_url = data.get("next")
+            if next_url:
+                # Next URL is absolute; strip base to get relative path + query
+                current_path = next_url.replace(BASE_URL, "")
+                current_params = None  # params are in the URL now
+            else:
+                current_path = None
+
+    def close(self) -> None:
+        self._session.close()

appliku/_exceptions.py

@@ -0,0 +1,84 @@
+"""Exception hierarchy for the Appliku SDK."""
+
+from __future__ import annotations
+
+
+class AplikuError(Exception):
+    """Base exception for all Appliku errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response: dict[str, object] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(AplikuError):
+    """Authentication failed (401)."""
+
+
+class AuthorizationError(AplikuError):
+    """Access denied (403)."""
+
+
+class NotFoundError(AplikuError):
+    """Resource not found (404)."""
+
+
+class ValidationError(AplikuError):
+    """Request validation failed (400)."""
+
+
+class RateLimitError(AplikuError):
+    """Rate limit exceeded (429)."""
+
+
+class ServerError(AplikuError):
+    """Server-side error (5xx)."""
+
+
+def parse_error_response(status_code: int, body: dict[str, object]) -> AplikuError:
+    """Factory: maps status code + DRF error shapes to the right exception.
+
+    Handles three DRF shapes:
+    - {"detail": "message"}
+    - {"non_field_errors": ["msg"]}
+    - {"field": ["error1", ...]}
+    """
+    # Extract human-readable message
+    if "detail" in body:
+        message = str(body["detail"])
+    elif "non_field_errors" in body:
+        errors = body["non_field_errors"]
+        message = "; ".join(str(e) for e in errors) if isinstance(errors, list) else str(errors)
+    else:
+        # Field-level errors: {"field": ["error1", ...]}
+        parts: list[str] = []
+        for key, value in body.items():
+            if isinstance(value, list):
+                parts.append(f"{key}: {', '.join(str(v) for v in value)}")
+            else:
+                parts.append(f"{key}: {value}")
+        message = "; ".join(parts) if parts else str(body)
+
+    exc_class: type[AplikuError]
+    if status_code == 400:
+        exc_class = ValidationError
+    elif status_code == 401:
+        exc_class = AuthenticationError
+    elif status_code == 403:
+        exc_class = AuthorizationError
+    elif status_code == 404:
+        exc_class = NotFoundError
+    elif status_code == 429:
+        exc_class = RateLimitError
+    elif status_code >= 500:
+        exc_class = ServerError
+    else:
+        exc_class = AplikuError
+
+    return exc_class(message, status_code=status_code, response=body)

appliku/_main.py

@@ -0,0 +1,122 @@
+"""The Appliku class — the user-facing SDK entry point."""
+
+from __future__ import annotations
+
+from ._auth import resolve_token
+from ._client import AplikuClient
+from ._exceptions import AuthenticationError
+from .resources.apps import AppsResource
+from .resources.clusters import ClustersResource
+from .resources.cron_jobs import CronJobsResource
+from .resources.datastores import DatastoresResource
+from .resources.deployments import DeploymentsResource
+from .resources.domains import DomainsResource
+from .resources.invites import InvitesResource
+from .resources.migrations import MigrationsResource
+from .resources.servers import ServersResource
+from .resources.teams import TeamsResource
+from .resources.volumes import VolumesResource
+
+
+class Appliku:
+    """Main SDK client. All resources are accessed as properties.
+
+    Usage:
+        client = Appliku(token="tok_...")       # explicit
+        client = Appliku()                       # reads APPLIKU_TOKEN env var or config file
+    """
+
+    def __init__(self, token: str | None = None) -> None:
+        resolved = resolve_token(token)
+        if not resolved:
+            raise AuthenticationError(
+                "No token found. Pass token=, set APPLIKU_TOKEN env var, or run `appliku login`."
+            )
+        self._client = AplikuClient(token=resolved)
+
+        self._teams: TeamsResource | None = None
+        self._apps: AppsResource | None = None
+        self._deployments: DeploymentsResource | None = None
+        self._datastores: DatastoresResource | None = None
+        self._domains: DomainsResource | None = None
+        self._volumes: VolumesResource | None = None
+        self._cron_jobs: CronJobsResource | None = None
+        self._clusters: ClustersResource | None = None
+        self._servers: ServersResource | None = None
+        self._invites: InvitesResource | None = None
+        self._migrations: MigrationsResource | None = None
+
+    @property
+    def teams(self) -> TeamsResource:
+        if self._teams is None:
+            self._teams = TeamsResource(self._client)
+        return self._teams
+
+    @property
+    def apps(self) -> AppsResource:
+        if self._apps is None:
+            self._apps = AppsResource(self._client)
+        return self._apps
+
+    @property
+    def deployments(self) -> DeploymentsResource:
+        if self._deployments is None:
+            self._deployments = DeploymentsResource(self._client)
+        return self._deployments
+
+    @property
+    def datastores(self) -> DatastoresResource:
+        if self._datastores is None:
+            self._datastores = DatastoresResource(self._client)
+        return self._datastores
+
+    @property
+    def domains(self) -> DomainsResource:
+        if self._domains is None:
+            self._domains = DomainsResource(self._client)
+        return self._domains
+
+    @property
+    def volumes(self) -> VolumesResource:
+        if self._volumes is None:
+            self._volumes = VolumesResource(self._client)
+        return self._volumes
+
+    @property
+    def cron_jobs(self) -> CronJobsResource:
+        if self._cron_jobs is None:
+            self._cron_jobs = CronJobsResource(self._client)
+        return self._cron_jobs
+
+    @property
+    def clusters(self) -> ClustersResource:
+        if self._clusters is None:
+            self._clusters = ClustersResource(self._client)
+        return self._clusters
+
+    @property
+    def servers(self) -> ServersResource:
+        if self._servers is None:
+            self._servers = ServersResource(self._client)
+        return self._servers
+
+    @property
+    def invites(self) -> InvitesResource:
+        if self._invites is None:
+            self._invites = InvitesResource(self._client)
+        return self._invites
+
+    @property
+    def migrations(self) -> MigrationsResource:
+        if self._migrations is None:
+            self._migrations = MigrationsResource(self._client)
+        return self._migrations
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Appliku:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()