treinta-previews 0.1.0__py3-none-any.whl

previews/__init__.py

@@ -0,0 +1,88 @@
+"""Python SDK for the Propie / Previews VM-as-a-Service platform.
+
+Quick start::
+
+    from previews import PreviewsClient
+
+    with PreviewsClient() as client:            # api key from env
+        vm = client.vms.create(repo_url="https://github.com/owner/repo", stack="node20")
+        vm = client.vms.wait_until_running(vm.id)
+        print(vm.url)
+
+Async::
+
+    from previews import AsyncPreviewsClient
+
+    async with AsyncPreviewsClient() as client:
+        vms = await client.vms.list()
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .archive import MAX_ZIP_BYTES, ZipResult, zip_directory
+from .async_client import AsyncPreviewsClient
+from .client import PreviewsClient
+from .errors import (
+    PreviewsApiError,
+    PreviewsConfigError,
+    PreviewsError,
+    PreviewsTimeoutError,
+)
+from .models import (
+    VM,
+    Account,
+    ApiKeyRef,
+    BandwidthResponse,
+    BandwidthSample,
+    CacheStat,
+    CurrentPrincipal,
+    DatabaseIntegration,
+    DetectionResult,
+    Drive,
+    EnvVarHint,
+    LogEvent,
+    Preview,
+    Project,
+    RunCommandResult,
+    SystemStatus,
+    UploadResult,
+    VMSnapshot,
+    WidgetToken,
+)
+
+__all__ = [
+    "__version__",
+    # Clients
+    "PreviewsClient",
+    "AsyncPreviewsClient",
+    # Errors
+    "PreviewsError",
+    "PreviewsApiError",
+    "PreviewsTimeoutError",
+    "PreviewsConfigError",
+    # Archive
+    "zip_directory",
+    "ZipResult",
+    "MAX_ZIP_BYTES",
+    # Models
+    "Preview",
+    "VM",
+    "RunCommandResult",
+    "VMSnapshot",
+    "LogEvent",
+    "EnvVarHint",
+    "DetectionResult",
+    "BandwidthSample",
+    "BandwidthResponse",
+    "Account",
+    "Project",
+    "ApiKeyRef",
+    "CurrentPrincipal",
+    "DatabaseIntegration",
+    "Drive",
+    "CacheStat",
+    "SystemStatus",
+    "WidgetToken",
+    "UploadResult",
+]

previews/_case.py

@@ -0,0 +1,48 @@
+"""camelCase <-> snake_case conversion helpers.
+
+The platform wire format is camelCase (mirrors ``web/src/lib/api.ts``). The
+Python SDK exposes snake_case names. These helpers translate between the two.
+
+IMPORTANT: only *field names* are converted. Free-form dict *values* (env-var
+maps, file contents) must never be key-mangled — callers convert the top-level
+keys they know about and pass value dicts through untouched.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_CAMEL_BOUNDARY_1 = re.compile(r"(.)([A-Z][a-z]+)")
+_CAMEL_BOUNDARY_2 = re.compile(r"([a-z0-9])([A-Z])")
+
+
+def camel_to_snake(name: str) -> str:
+    """``repoUrl`` -> ``repo_url``, ``memoryMib`` -> ``memory_mib``."""
+    s = _CAMEL_BOUNDARY_1.sub(r"\1_\2", name)
+    s = _CAMEL_BOUNDARY_2.sub(r"\1_\2", s)
+    return s.lower()
+
+
+def snake_to_camel(name: str) -> str:
+    """``repo_url`` -> ``repoUrl``, ``drive_read_only`` -> ``driveReadOnly``.
+
+    Idempotent for names that are already camelCase (``repoUrl`` -> ``repoUrl``).
+    Uses ``p[:1].upper() + p[1:]`` (not ``.title()``) so segments like ``mib``
+    become ``Mib`` while preserving any already-upper trailing characters.
+    """
+    parts = name.split("_")
+    if len(parts) == 1:
+        return name
+    head = parts[0]
+    tail = "".join(p[:1].upper() + p[1:] for p in parts[1:] if p != "")
+    return head + tail
+
+
+def keys_to_snake(data: Any) -> Any:
+    """Recursively convert every mapping key to snake_case (values untouched)."""
+    if isinstance(data, dict):
+        return {camel_to_snake(str(k)): keys_to_snake(v) for k, v in data.items()}
+    if isinstance(data, (list, tuple)):
+        return [keys_to_snake(v) for v in data]
+    return data

previews/_config.py

@@ -0,0 +1,45 @@
+"""Configuration resolution: base URL + API key from args or the environment."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+# Default production base. Mirrors cli/client.ts.
+DEFAULT_BASE_URL = "https://previews.amapola.treinta.ai/api"
+
+# Env var precedence mirrors the CLI: primary name first, then aliases.
+API_KEY_ENV_VARS = ("TREINTA_PREVIEWS_API_KEY", "PROPIE_API_KEY", "PREVIEWS_API_KEY")
+BASE_URL_ENV_VARS = ("TREINTA_PREVIEWS_API_URL", "PROPIE_API_URL")
+
+# Canonical terminal VM statuses (single source of truth mirrors
+# api/src/lib/constants.ts::TERMINAL_STATUSES).
+TERMINAL_STATUSES = frozenset({"error", "stopped", "deleted"})
+
+# Non-terminal but compute-free (scale-to-zero permanent previews).
+DORMANT_STATUSES = frozenset({"sleeping"})
+
+
+def resolve_api_key(explicit: Optional[str]) -> Optional[str]:
+    """Explicit arg wins; otherwise the first non-empty env var in precedence."""
+    if explicit:
+        return explicit
+    for name in API_KEY_ENV_VARS:
+        val = os.environ.get(name)
+        if val:
+            return val
+    return None
+
+
+def resolve_base_url(explicit: Optional[str]) -> str:
+    """Explicit arg wins, then env vars, then the default. Trailing slash stripped."""
+    base = explicit
+    if not base:
+        for name in BASE_URL_ENV_VARS:
+            val = os.environ.get(name)
+            if val:
+                base = val
+                break
+    if not base:
+        base = DEFAULT_BASE_URL
+    return base.rstrip("/")

previews/_http.py

@@ -0,0 +1,62 @@
+"""Transport-agnostic HTTP helpers shared by the sync and async clients.
+
+These are pure functions (no I/O) so the sync client, the async client, and the
+SSE layer all raise the identical error envelope and parse bodies identically.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any, Dict, Mapping, Optional
+from urllib.parse import quote
+
+from .errors import PreviewsApiError
+
+
+def build_headers(api_key: str, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+    """Authorization header + any extras. Never sets Content-Type (httpx does)."""
+    headers: Dict[str, str] = {"Authorization": f"Bearer {api_key}"}
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def parse_json(text: str) -> Any:
+    """Parse a response body. Empty -> ``{}``; non-JSON -> ``{"raw": text}``."""
+    if not text:
+        return {}
+    try:
+        return _json.loads(text)
+    except ValueError:
+        return {"raw": text}
+
+
+def raise_for_status(status_code: int, reason: str, body: Any) -> None:
+    """Raise :class:`PreviewsApiError` from a parsed error envelope.
+
+    Envelope shape: ``{ error: { code, message } }``. Fallback code ``"UNKNOWN"``,
+    fallback message ``"<status> <reason>"``.
+    """
+    err = body.get("error") if isinstance(body, Mapping) else None
+    err = err if isinstance(err, Mapping) else {}
+    code = err.get("code") or "UNKNOWN"
+    message = err.get("message") or f"{status_code} {reason}".strip()
+    raise PreviewsApiError(status_code, code, message)
+
+
+def process_response(status_code: int, reason: str, text: str, is_success: bool) -> Any:
+    """Parse + (on non-2xx) raise. Returns the parsed body on success."""
+    body = parse_json(text)
+    if not is_success:
+        raise_for_status(status_code, reason, body)
+    return body
+
+
+def drop_none(data: Mapping[str, Any]) -> Dict[str, Any]:
+    """Return a copy of ``data`` with ``None`` values removed (top level only)."""
+    return {k: v for k, v in data.items() if v is not None}
+
+
+def quote_id(value: Any) -> str:
+    """URL-encode a path segment (mirrors ``encodeURIComponent``)."""
+    return quote(str(value), safe="")

previews/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version (read by hatchling)."""
+
+__version__ = "0.1.0"

previews/archive.py

@@ -0,0 +1,271 @@
+"""Zip a local project directory for upload to the Previews API.
+
+Faithful port of ``mcp/src/archive.ts``:
+
+* honors ``.gitignore`` when the folder is a git repo (``git ls-files`` union of
+  tracked + untracked-not-ignored), otherwise a pruned filesystem walk;
+* force-includes the ``.env.example`` family (needed for stack detection) even
+  when the repo gitignores the whole ``.env*`` family;
+* always strips secret-bearing files (``.env``, ``*.pem``/``*.key``, ``id_rsa``,
+  ``credentials.json``, ``.ssh``/``.aws``/``.gnupg`` dirs, ...) regardless of
+  source — secrets must travel via ``environment_variables``, never the archive;
+* enforces the 50 MiB *compressed* upload cap and a 384 MiB *uncompressed*
+  tripwire (catches "deploying the wrong folder");
+* caches the produced archive per absolute root, keyed by a cheap content
+  fingerprint, so detect-then-create on an unchanged folder reuses the bytes.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import re
+import subprocess
+import zipfile
+from dataclasses import dataclass, field, replace
+from typing import Dict, List, Optional, Tuple
+
+# Matches the server's MAX_CODE_ARCHIVE_BYTES. Checked on the COMPRESSED zip.
+MAX_ZIP_BYTES = 50 * 1024 * 1024
+# Peak-memory tripwire on the UNCOMPRESSED total (whole archive built in memory).
+UNCOMPRESSED_TRIPWIRE = 384 * 1024 * 1024
+
+# Basenames pruned in the non-git fallback walk (unused when .gitignore drives it).
+DEFAULT_IGNORES = {
+    ".git", "node_modules", ".next", "dist", "build", "out", ".turbo", ".cache",
+    ".vercel", ".netlify", "coverage", "__pycache__", ".venv", "venv",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".pnpm-store", ".yarn",
+    ".svelte-kit", ".parcel-cache", ".gradle", "target", "vendor", "tmp",
+    ".idea", ".vscode", ".DS_Store", "Thumbs.db",
+}
+
+# Credential-store directories, always stripped even from git-tracked files.
+SECRET_DIRS = {".ssh", ".aws", ".gnupg"}
+
+# .env variants that carry NO secrets — kept for the server's detector.
+ENV_ALLOWLIST = {".env.example", ".env.sample", ".env.template", ".env.dist"}
+
+_SECRET_FILE_RE = [
+    re.compile(r"\.(pem|key|p12|pfx|keystore|asc)$", re.IGNORECASE),
+    re.compile(r"^id_(rsa|ed25519|ecdsa|dsa)\b", re.IGNORECASE),
+    re.compile(r"(^|[._-])credentials?([._-].*)?\.json$", re.IGNORECASE),
+    re.compile(r"^service[-_]?account.*\.json$", re.IGNORECASE),
+]
+_SECRET_FILE_NAMES = {".npmrc", ".netrc", ".git-credentials", ".pgpass"}
+
+
+@dataclass(frozen=True)
+class ZipResult:
+    zip: bytes
+    file_count: int
+    bytes: int
+    root: str
+    warnings: List[str] = field(default_factory=list)
+
+
+# Per-absolute-root cache, validated by a content fingerprint.
+_cache: Dict[str, Tuple[str, ZipResult]] = {}
+
+
+def _is_secret_file(base: str) -> bool:
+    if base == ".env":
+        return True
+    if base.startswith(".env.") and base not in ENV_ALLOWLIST:
+        return True
+    if base in _SECRET_FILE_NAMES:
+        return True
+    return any(rx.search(base) for rx in _SECRET_FILE_RE)
+
+
+def _classify_secret(rel: str) -> Optional[str]:
+    parts = rel.split("/")
+    for p in parts:
+        if p in SECRET_DIRS:
+            return f"credential dir '{p}/'"
+    if _is_secret_file(parts[-1]):
+        return "secret/credential file"
+    return None
+
+
+def _is_git_repo(root_abs: str) -> bool:
+    try:
+        out = subprocess.run(
+            ["git", "-C", root_abs, "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+        )
+        return out.returncode == 0 and out.stdout.strip() == "true"
+    except (FileNotFoundError, OSError):
+        return False
+
+
+def _git_files(root_abs: str, extra_args: List[str]) -> List[str]:
+    out = subprocess.run(
+        ["git", "-C", root_abs, "ls-files", "-z", *extra_args],
+        capture_output=True,
+    )
+    if out.returncode != 0:
+        return []
+    return [p for p in out.stdout.decode("utf-8", "replace").split("\0") if p]
+
+
+def _list_via_git(root_abs: str) -> List[str]:
+    tracked = _git_files(root_abs, [])
+    untracked = _git_files(root_abs, ["--others", "--exclude-standard"])
+    # Union preserving first-seen order.
+    return list(dict.fromkeys([*tracked, *untracked]))
+
+
+def _rel_posix(root_abs: str, abs_path: str) -> str:
+    return os.path.relpath(abs_path, root_abs).replace(os.sep, "/")
+
+
+def _list_via_walk(root_abs: str, warnings: List[str]) -> List[str]:
+    out: List[str] = []
+
+    def walk(dir_abs: str) -> None:
+        try:
+            entries = list(os.scandir(dir_abs))
+        except OSError as err:
+            rel = _rel_posix(root_abs, dir_abs) or "."
+            warnings.append(f"skipped unreadable dir {rel}: {err}")
+            return
+        for e in entries:
+            if e.name in DEFAULT_IGNORES:
+                continue
+            abs_path = os.path.join(dir_abs, e.name)
+            rel = _rel_posix(root_abs, abs_path)
+            if e.is_symlink():
+                try:
+                    if os.path.isdir(abs_path):  # follows link
+                        warnings.append(f"skipped symlinked dir {rel}")
+                    elif os.path.isfile(abs_path):
+                        out.append(rel)
+                    else:
+                        warnings.append(f"skipped broken symlink {rel}")
+                except OSError:
+                    warnings.append(f"skipped broken symlink {rel}")
+            elif e.is_dir(follow_symlinks=False):
+                walk(abs_path)
+            elif e.is_file(follow_symlinks=False):
+                out.append(rel)
+
+    walk(root_abs)
+    return out
+
+
+def _collect_env_examples(root_abs: str) -> List[str]:
+    out: List[str] = []
+
+    def walk(dir_abs: str) -> None:
+        try:
+            entries = list(os.scandir(dir_abs))
+        except OSError:
+            return
+        for e in entries:
+            if e.name in DEFAULT_IGNORES or e.name in SECRET_DIRS:
+                continue
+            abs_path = os.path.join(dir_abs, e.name)
+            if e.is_dir(follow_symlinks=False):
+                walk(abs_path)
+            elif (e.is_file(follow_symlinks=False) or e.is_symlink()) and e.name in ENV_ALLOWLIST:
+                out.append(_rel_posix(root_abs, abs_path))
+
+    walk(root_abs)
+    return out
+
+
+def zip_directory(root_abs: str) -> ZipResult:
+    """Zip ``root_abs`` into an in-memory archive. See module docstring."""
+    if not os.path.isabs(root_abs):
+        raise ValueError(f'path must be absolute, got "{root_abs}"')
+    if not os.path.exists(root_abs):
+        raise FileNotFoundError(f"path not found: {root_abs}")
+    if not os.path.isdir(root_abs):
+        raise NotADirectoryError(f"path is not a directory: {root_abs}")
+
+    warnings: List[str] = []
+
+    # 1) Candidate files (root-relative posix), honoring .gitignore when possible,
+    #    plus force-included .env.example-style files.
+    candidates = _list_via_git(root_abs) if _is_git_repo(root_abs) else _list_via_walk(root_abs, warnings)
+    all_files = set(candidates)
+    for ex in _collect_env_examples(root_abs):
+        all_files.add(ex)
+
+    # 2) Strip secrets/credentials regardless of source.
+    kept: List[str] = []
+    for rel in all_files:
+        reason = _classify_secret(rel)
+        if reason:
+            warnings.append(
+                f"omitted {reason}: {rel} — pass secrets via environment_variables, not the archive"
+            )
+        else:
+            kept.append(rel)
+    kept.sort()
+
+    if not kept:
+        raise ValueError(f"no files to deploy from {root_abs} after applying ignore + secret filters")
+
+    # 3) Stat pass -> size guard + fingerprint (before reading any bytes).
+    stats: List[Tuple[str, int, int]] = []  # (rel, size, mtime_ms)
+    uncompressed = 0
+    for rel in kept:
+        abs_path = os.path.join(root_abs, rel)
+        try:
+            st = os.stat(abs_path)  # follows symlinked files
+        except OSError as err:
+            warnings.append(f"skipped {rel}: {err}")
+            continue
+        if not os.path.isfile(abs_path):
+            warnings.append(f"skipped {rel}: not a regular file")
+            continue
+        uncompressed += st.st_size
+        if uncompressed > UNCOMPRESSED_TRIPWIRE:
+            raise ValueError(
+                f"directory too large to archive (uncompressed > "
+                f"{round(UNCOMPRESSED_TRIPWIRE / 1024 / 1024)} MiB). "
+                f"Are you running this on the wrong folder? Deploy a specific project directory."
+            )
+        stats.append((rel, st.st_size, round(st.st_mtime * 1000)))
+    if not stats:
+        raise ValueError(f"no readable files to deploy from {root_abs}")
+
+    fingerprint = json.dumps([[rel, size, mtime] for rel, size, mtime in stats])
+    hit = _cache.get(root_abs)
+    if hit and hit[0] == fingerprint:
+        # Reuse the cached bytes but report this call's warnings.
+        return replace(hit[1], warnings=warnings)
+
+    # 4) Read bytes -> entries (root-relative posix keys, no wrapper dir).
+    entries: List[Tuple[str, bytes]] = []
+    for rel, _size, _mtime in stats:
+        try:
+            with open(os.path.join(root_abs, rel), "rb") as fh:
+                entries.append((rel, fh.read()))
+        except OSError as err:
+            warnings.append(f"skipped {rel}: {err}")
+    if not entries:
+        raise ValueError(f"no readable files to deploy from {root_abs}")
+
+    # 5) Compress (DEFLATE level 6, posix arcnames).
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
+        for rel, data in entries:
+            zf.writestr(rel, data)
+    zipped = buf.getvalue()
+
+    if len(zipped) > MAX_ZIP_BYTES:
+        raise ValueError(
+            f"zipped project is {len(zipped) / 1024 / 1024:.1f} MiB, over the "
+            f"{MAX_ZIP_BYTES // 1024 // 1024} MiB upload limit. "
+            f"Trim large files or deploy from a git repo_url instead."
+        )
+
+    result = ZipResult(
+        zip=zipped, file_count=len(entries), bytes=len(zipped), root=root_abs, warnings=warnings
+    )
+    _cache[root_abs] = (fingerprint, result)
+    return result

previews/async_client.py

@@ -0,0 +1,122 @@
+"""Asynchronous :class:`AsyncPreviewsClient` — mirror of the sync client."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Mapping, Optional
+
+import httpx
+
+from ._config import resolve_api_key, resolve_base_url
+from ._http import build_headers, process_response
+from .errors import PreviewsConfigError
+from .resources.accounts import AsyncAccountsResource
+from .resources.detect import AsyncDetectResource
+from .resources.drives import AsyncDrivesResource
+from .resources.integrations import AsyncIntegrationsResource
+from .resources.snapshots import AsyncSnapshotsResource
+from .resources.vms import AsyncVMsResource
+from .sse import Frame, ensure_stream_ok_async, parse_named_sse_async
+
+
+class AsyncPreviewsClient:
+    """Asynchronous client for the Propie / Previews API. See
+    :class:`~previews.client.PreviewsClient` for config resolution semantics."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        key = resolve_api_key(api_key)
+        if not key:
+            raise PreviewsConfigError(
+                "No API key. Pass api_key=... or set TREINTA_PREVIEWS_API_KEY "
+                "(aliases: PROPIE_API_KEY, PREVIEWS_API_KEY)."
+            )
+        self._api_key = key
+        self._base_url = resolve_base_url(base_url)
+        self._timeout = timeout
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+        self.vms = AsyncVMsResource(self)
+        self.snapshots = AsyncSnapshotsResource(self)
+        self.drives = AsyncDrivesResource(self)
+        self.integrations = AsyncIntegrationsResource(self)
+        self.detect = AsyncDetectResource(self)
+        self.accounts = AsyncAccountsResource(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        content: Any = None,
+        data: Optional[Mapping[str, Any]] = None,
+        files: Any = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        resp = await self._http.request(
+            method,
+            self._url(path),
+            json=json,
+            params=params,
+            headers=build_headers(self._api_key, headers),
+            content=content,
+            data=data,
+            files=files,
+            timeout=timeout if timeout is not None else self._timeout,
+        )
+        return process_response(resp.status_code, resp.reason_phrase, resp.text, resp.is_success)
+
+    async def _aiter_sse(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        files: Any = None,
+        data: Optional[Mapping[str, Any]] = None,
+    ) -> AsyncIterator[Frame]:
+        timeout = httpx.Timeout(self._timeout, read=None)
+        headers = build_headers(self._api_key, {"Accept": "text/event-stream"})
+        async with self._http.stream(
+            method,
+            self._url(path),
+            json=json,
+            params=params,
+            files=files,
+            data=data,
+            headers=headers,
+            timeout=timeout,
+        ) as resp:
+            await ensure_stream_ok_async(resp)
+            async for frame in parse_named_sse_async(resp):
+                yield frame
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncPreviewsClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+__all__ = ["AsyncPreviewsClient"]