clovrix 0.1.0__tar.gz

clovrix-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Node
+node_modules/
+node/dist/
+*.tsbuildinfo
+npm-debug.log*
+
+# Go
+go/bin/
+
+# Python
+__pycache__/
+*.py[cod]
+python/.venv/
+python/dist/
+python/build/
+python/*.egg-info/
+.pytest_cache/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

clovrix-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: clovrix
+Version: 0.1.0
+Summary: Official Python SDK for the Clovrix Public API
+Project-URL: Homepage, https://github.com/clovrix/sdk/tree/main/python
+Project-URL: Repository, https://github.com/clovrix/sdk
+Author: Clovrix
+License: MIT
+Keywords: clovrix,config,environment-variables,sdk,secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clovrix
+
+Official Python SDK for the [Clovrix](https://clovrix.com) Public API. Sync and async clients
+built on [httpx](https://www.python-httpx.org/), fully typed.
+
+## Install
+
+```bash
+pip install clovrix
+```
+
+Requires Python 3.9+.
+
+## Authentication
+
+Create an API token from your organization's **Settings → API tokens** page, then either pass it
+to the client or expose it as an environment variable:
+
+```bash
+export CLOVRIX_TOKEN="icr_xxxxxxxx…"
+```
+
+Resolution order: `token=` argument → `CLOVRIX_TOKEN` env var → otherwise a `ClovrixConfigError`
+is raised. The host defaults to `https://app.clovrix.com`; override with `base_url=` or
+`CLOVRIX_API_URL` (scheme + host only — the `/api/public/v1` path is added for you).
+
+## Usage
+
+```python
+from clovrix import Client
+
+clovrix = Client()  # token from CLOVRIX_TOKEN
+
+# Fetch every entry in an environment as a dict.
+config = clovrix.get_entries("backend", "production")
+print(config["DATABASE_URL"])
+
+# Fetch a single entry (raises NotFoundError if unset).
+entry = clovrix.get_entry("backend", "production", "DATABASE_URL")
+print(entry.key, entry.value, entry.is_secret)
+
+# Write one entry. is_secret applies only when the key is first created.
+result = clovrix.set_entry("backend", "production", "API_KEY", "s3cr3t", is_secret=True)
+print(result.created)  # True if newly created, False if a new version
+
+# Write up to 100 entries atomically; returns the number written.
+from clovrix import WriteItem
+
+written = clovrix.set_entries("backend", "production", [
+    WriteItem(key="FEATURE_X", value="on"),
+    {"key": "API_KEY", "value": "s3cr3t", "is_secret": True},  # mappings work too
+])
+```
+
+Use it as a context manager to close the underlying HTTP connection pool:
+
+```python
+with Client() as clovrix:
+    config = clovrix.get_entries("backend", "production")
+```
+
+Load straight into the process environment:
+
+```python
+import os
+os.environ.update(clovrix.get_entries("backend", "production"))
+```
+
+### Async
+
+```python
+import asyncio
+from clovrix import AsyncClient
+
+async def main():
+    async with AsyncClient() as clovrix:
+        config = await clovrix.get_entries("backend", "production")
+        print(config)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+Client(
+    token="icr_…",            # default: CLOVRIX_TOKEN
+    base_url="https://…",     # default: CLOVRIX_API_URL or https://app.clovrix.com
+    timeout=30.0,             # per-request timeout (seconds)
+    user_agent="my-app/1.0",
+    http_client=my_httpx_client,  # bring your own httpx.Client / httpx.AsyncClient
+)
+```
+
+## Error handling
+
+Every failed request raises a subclass of `ClovrixError`. API errors expose `.status_code`; a
+billing block also exposes `.billing_status`.
+
+| Exception | Cause |
+| --- | --- |
+| `ClovrixConfigError` | Missing token / misconfiguration |
+| `ClovrixConnectionError` | Network failure or timeout (no HTTP response) |
+| `AuthenticationError` | `401` — missing/invalid/expired token |
+| `BillingError` | `402` — billing pending or restricted (`.billing_status`) |
+| `ForbiddenError` | `403` — token role lacks access |
+| `NotFoundError` | `404` — project/environment/key not found |
+| `ValidationError` | `400` / `413` / `422` — invalid request, nothing written |
+| `ServerError` | `5xx` |
+
+```python
+from clovrix import NotFoundError, BillingError
+
+try:
+    entry = clovrix.get_entry("backend", "production", "MAYBE")
+except NotFoundError:
+    ...  # key isn't set
+except BillingError as err:
+    print("billing:", err.billing_status)
+```
+
+## Limits
+
+- Keys match `^[A-Z_][A-Z0-9_]*$`, max 128 chars.
+- Values are UTF-8 up to 32 KiB.
+- Bulk write ≤ 100 keys (atomic); bulk fetch ≤ 500 entries per project.
+- `is_secret` is fixed at creation and cannot be changed afterwards.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

clovrix-0.1.0/README.md

@@ -0,0 +1,135 @@
+# clovrix
+
+Official Python SDK for the [Clovrix](https://clovrix.com) Public API. Sync and async clients
+built on [httpx](https://www.python-httpx.org/), fully typed.
+
+## Install
+
+```bash
+pip install clovrix
+```
+
+Requires Python 3.9+.
+
+## Authentication
+
+Create an API token from your organization's **Settings → API tokens** page, then either pass it
+to the client or expose it as an environment variable:
+
+```bash
+export CLOVRIX_TOKEN="icr_xxxxxxxx…"
+```
+
+Resolution order: `token=` argument → `CLOVRIX_TOKEN` env var → otherwise a `ClovrixConfigError`
+is raised. The host defaults to `https://app.clovrix.com`; override with `base_url=` or
+`CLOVRIX_API_URL` (scheme + host only — the `/api/public/v1` path is added for you).
+
+## Usage
+
+```python
+from clovrix import Client
+
+clovrix = Client()  # token from CLOVRIX_TOKEN
+
+# Fetch every entry in an environment as a dict.
+config = clovrix.get_entries("backend", "production")
+print(config["DATABASE_URL"])
+
+# Fetch a single entry (raises NotFoundError if unset).
+entry = clovrix.get_entry("backend", "production", "DATABASE_URL")
+print(entry.key, entry.value, entry.is_secret)
+
+# Write one entry. is_secret applies only when the key is first created.
+result = clovrix.set_entry("backend", "production", "API_KEY", "s3cr3t", is_secret=True)
+print(result.created)  # True if newly created, False if a new version
+
+# Write up to 100 entries atomically; returns the number written.
+from clovrix import WriteItem
+
+written = clovrix.set_entries("backend", "production", [
+    WriteItem(key="FEATURE_X", value="on"),
+    {"key": "API_KEY", "value": "s3cr3t", "is_secret": True},  # mappings work too
+])
+```
+
+Use it as a context manager to close the underlying HTTP connection pool:
+
+```python
+with Client() as clovrix:
+    config = clovrix.get_entries("backend", "production")
+```
+
+Load straight into the process environment:
+
+```python
+import os
+os.environ.update(clovrix.get_entries("backend", "production"))
+```
+
+### Async
+
+```python
+import asyncio
+from clovrix import AsyncClient
+
+async def main():
+    async with AsyncClient() as clovrix:
+        config = await clovrix.get_entries("backend", "production")
+        print(config)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+Client(
+    token="icr_…",            # default: CLOVRIX_TOKEN
+    base_url="https://…",     # default: CLOVRIX_API_URL or https://app.clovrix.com
+    timeout=30.0,             # per-request timeout (seconds)
+    user_agent="my-app/1.0",
+    http_client=my_httpx_client,  # bring your own httpx.Client / httpx.AsyncClient
+)
+```
+
+## Error handling
+
+Every failed request raises a subclass of `ClovrixError`. API errors expose `.status_code`; a
+billing block also exposes `.billing_status`.
+
+| Exception | Cause |
+| --- | --- |
+| `ClovrixConfigError` | Missing token / misconfiguration |
+| `ClovrixConnectionError` | Network failure or timeout (no HTTP response) |
+| `AuthenticationError` | `401` — missing/invalid/expired token |
+| `BillingError` | `402` — billing pending or restricted (`.billing_status`) |
+| `ForbiddenError` | `403` — token role lacks access |
+| `NotFoundError` | `404` — project/environment/key not found |
+| `ValidationError` | `400` / `413` / `422` — invalid request, nothing written |
+| `ServerError` | `5xx` |
+
+```python
+from clovrix import NotFoundError, BillingError
+
+try:
+    entry = clovrix.get_entry("backend", "production", "MAYBE")
+except NotFoundError:
+    ...  # key isn't set
+except BillingError as err:
+    print("billing:", err.billing_status)
+```
+
+## Limits
+
+- Keys match `^[A-Z_][A-Z0-9_]*$`, max 128 chars.
+- Values are UTF-8 up to 32 KiB.
+- Bulk write ≤ 100 keys (atomic); bulk fetch ≤ 500 entries per project.
+- `is_secret` is fixed at creation and cannot be changed afterwards.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

clovrix-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clovrix"
+version = "0.1.0"
+description = "Official Python SDK for the Clovrix Public API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Clovrix" }]
+keywords = ["clovrix", "secrets", "config", "environment-variables", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://github.com/clovrix/sdk/tree/main/python"
+Repository = "https://github.com/clovrix/sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clovrix"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

clovrix-0.1.0/src/clovrix/__init__.py

@@ -0,0 +1,39 @@
+"""Official Python SDK for the Clovrix Public API."""
+
+from __future__ import annotations
+
+from ._models import Entry, WriteItem, WriteResult
+from .client import AsyncClient, Client
+from .errors import (
+    APIError,
+    AuthenticationError,
+    BillingError,
+    ClovrixConfigError,
+    ClovrixConnectionError,
+    ClovrixError,
+    ForbiddenError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "Entry",
+    "WriteItem",
+    "WriteResult",
+    "ClovrixError",
+    "ClovrixConfigError",
+    "ClovrixConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "BillingError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "__version__",
+]

clovrix-0.1.0/src/clovrix/_models.py

@@ -0,0 +1,42 @@
+"""Data models returned by and submitted to the Clovrix API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Entry:
+    """A single configuration/secret entry.
+
+    ``value`` is the current value for the requested environment; secret values
+    are returned decrypted.
+    """
+
+    key: str
+    value: str
+    is_secret: bool
+
+
+@dataclass
+class WriteItem:
+    """One key/value pair to write.
+
+    ``is_secret`` is honoured only when the key is first created; it cannot be
+    changed on an existing key. Leave it ``None`` to default a new key to a plain
+    config value.
+    """
+
+    key: str
+    value: str
+    is_secret: Optional[bool] = None
+
+
+@dataclass(frozen=True)
+class WriteResult:
+    """The result of writing a single entry."""
+
+    key: str
+    #: True if a new entry was created; False if a new version was appended.
+    created: bool

clovrix-0.1.0/src/clovrix/client.py

@@ -0,0 +1,280 @@
+"""Synchronous and asynchronous clients for the Clovrix Public API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple, Union
+from urllib.parse import quote
+
+import httpx
+
+from ._models import Entry, WriteItem, WriteResult
+from .errors import ClovrixConfigError, ClovrixConnectionError, error_from_response
+
+DEFAULT_BASE_URL = "https://app.clovrix.com"
+API_PREFIX = "/api/public/v1"
+DEFAULT_TIMEOUT = 30.0
+SDK_VERSION = "0.1.0"
+
+#: A write item may be a WriteItem or a plain mapping with key/value/is_secret.
+WriteInput = Union[WriteItem, Mapping[str, Any]]
+
+
+def _resolve_token(token: Optional[str]) -> str:
+    token = token or os.environ.get("CLOVRIX_TOKEN")
+    if not token:
+        raise ClovrixConfigError(
+            "No Clovrix API token provided. Pass token=... or set the CLOVRIX_TOKEN "
+            "environment variable."
+        )
+    return token
+
+
+def _resolve_base_url(base_url: Optional[str]) -> str:
+    base = (base_url or os.environ.get("CLOVRIX_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+    if not base.endswith(API_PREFIX):
+        base += API_PREFIX
+    return base
+
+
+def _make_headers(token: str, user_agent: Optional[str]) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+        "User-Agent": user_agent or f"clovrix-sdk-python/{SDK_VERSION}",
+    }
+
+
+def _entry_segments(
+    project: str, environment: str, key: Optional[str] = None
+) -> Tuple[str, ...]:
+    segments = ("projects", project, "environments", environment, "entries")
+    if key is not None:
+        segments += (key,)
+    return segments
+
+
+def _write_body(value: str, is_secret: Optional[bool]) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"value": value}
+    if is_secret is not None:
+        body["is_secret"] = is_secret
+    return body
+
+
+def _serialize_items(items: Iterable[WriteInput]) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    for item in items:
+        if isinstance(item, WriteItem):
+            key, value, is_secret = item.key, item.value, item.is_secret
+        elif isinstance(item, Mapping):
+            key, value, is_secret = item["key"], item["value"], item.get("is_secret")
+        else:  # pragma: no cover - defensive
+            raise TypeError("write items must be WriteItem instances or mappings")
+        entry: Dict[str, Any] = {"key": key, "value": value}
+        if is_secret is not None:
+            entry["is_secret"] = is_secret
+        out.append(entry)
+    return out
+
+
+def _entry_from_data(data: Mapping[str, Any]) -> Entry:
+    return Entry(key=data["key"], value=data["value"], is_secret=data["is_secret"])
+
+
+def _result_from_data(data: Mapping[str, Any]) -> WriteResult:
+    return WriteResult(key=data["key"], created=data["created"])
+
+
+def _encode_segment(segment: str) -> str:
+    return quote(segment, safe="")
+
+
+def _build_url(api_root: str, segments: Sequence[str]) -> str:
+    path = "/".join(_encode_segment(s) for s in segments)
+    return f"{api_root}/{path}"
+
+
+def _parse_error(response: httpx.Response) -> Exception:
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = None
+    return error_from_response(response.status_code, body, response.text)
+
+
+class Client:
+    """Synchronous client for the Clovrix Public API.
+
+    The token resolves from ``token`` then the ``CLOVRIX_TOKEN`` environment
+    variable; the host from ``base_url`` then ``CLOVRIX_API_URL`` then
+    ``https://app.clovrix.com``.
+
+    Usable as a context manager to close the underlying HTTP client::
+
+        with Client() as clovrix:
+            config = clovrix.get_entries("backend", "production")
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: Optional[str] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._api_root = _resolve_base_url(base_url)
+        resolved_token = _resolve_token(token)
+        self._headers = _make_headers(resolved_token, user_agent)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    def _request(
+        self,
+        method: str,
+        segments: Sequence[str],
+        json_body: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = _build_url(self._api_root, segments)
+        try:
+            response = self._http.request(method, url, headers=self._headers, json=json_body)
+        except httpx.TimeoutException as exc:
+            raise ClovrixConnectionError(f"Request to {url} timed out") from exc
+        except httpx.HTTPError as exc:
+            raise ClovrixConnectionError(f"Request to {url} failed") from exc
+
+        if not response.is_success:
+            raise _parse_error(response)
+        if not response.content:
+            return {}
+        return response.json()
+
+    def get_entry(self, project: str, environment: str, key: str) -> Entry:
+        """Fetch a single entry's value (raises ``NotFoundError`` if unset)."""
+        data = self._request("GET", _entry_segments(project, environment, key))
+        return _entry_from_data(data)
+
+    def get_entries(self, project: str, environment: str) -> Dict[str, str]:
+        """Fetch every entry for an environment as a ``key -> value`` dict."""
+        data = self._request("GET", _entry_segments(project, environment))
+        entries = data.get("entries")
+        return entries if isinstance(entries, dict) else {}
+
+    def set_entry(
+        self,
+        project: str,
+        environment: str,
+        key: str,
+        value: str,
+        *,
+        is_secret: Optional[bool] = None,
+    ) -> WriteResult:
+        """Write a single entry, creating it if it does not exist."""
+        body = _write_body(value, is_secret)
+        data = self._request("POST", _entry_segments(project, environment, key), body)
+        return _result_from_data(data)
+
+    def set_entries(
+        self, project: str, environment: str, items: Iterable[WriteInput]
+    ) -> int:
+        """Write up to 100 entries atomically; returns the number written."""
+        body = {"entries": _serialize_items(items)}
+        data = self._request("POST", _entry_segments(project, environment), body)
+        return data["written"]
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Asynchronous client for the Clovrix Public API.
+
+    Mirrors :class:`Client` with ``async`` methods::
+
+        async with AsyncClient() as clovrix:
+            config = await clovrix.get_entries("backend", "production")
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        user_agent: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._api_root = _resolve_base_url(base_url)
+        resolved_token = _resolve_token(token)
+        self._headers = _make_headers(resolved_token, user_agent)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def _request(
+        self,
+        method: str,
+        segments: Sequence[str],
+        json_body: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = _build_url(self._api_root, segments)
+        try:
+            response = await self._http.request(
+                method, url, headers=self._headers, json=json_body
+            )
+        except httpx.TimeoutException as exc:
+            raise ClovrixConnectionError(f"Request to {url} timed out") from exc
+        except httpx.HTTPError as exc:
+            raise ClovrixConnectionError(f"Request to {url} failed") from exc
+
+        if not response.is_success:
+            raise _parse_error(response)
+        if not response.content:
+            return {}
+        return response.json()
+
+    async def get_entry(self, project: str, environment: str, key: str) -> Entry:
+        data = await self._request("GET", _entry_segments(project, environment, key))
+        return _entry_from_data(data)
+
+    async def get_entries(self, project: str, environment: str) -> Dict[str, str]:
+        data = await self._request("GET", _entry_segments(project, environment))
+        entries = data.get("entries")
+        return entries if isinstance(entries, dict) else {}
+
+    async def set_entry(
+        self,
+        project: str,
+        environment: str,
+        key: str,
+        value: str,
+        *,
+        is_secret: Optional[bool] = None,
+    ) -> WriteResult:
+        body = _write_body(value, is_secret)
+        data = await self._request("POST", _entry_segments(project, environment, key), body)
+        return _result_from_data(data)
+
+    async def set_entries(
+        self, project: str, environment: str, items: Iterable[WriteInput]
+    ) -> int:
+        body = {"entries": _serialize_items(items)}
+        data = await self._request("POST", _entry_segments(project, environment), body)
+        return data["written"]
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

clovrix-0.1.0/src/clovrix/errors.py

@@ -0,0 +1,92 @@
+"""Exception hierarchy for the Clovrix SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class ClovrixError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class ClovrixConfigError(ClovrixError):
+    """The client is misconfigured (e.g. no API token could be resolved)."""
+
+
+class ClovrixConnectionError(ClovrixError):
+    """A transport-level failure (DNS, connection, timeout) with no HTTP response."""
+
+
+class APIError(ClovrixError):
+    """A non-2xx response from the API.
+
+    ``billing_status`` is populated only for a 402 response
+    (``"pending_payment"`` or ``"restricted"``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        billing_status: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.billing_status = billing_status
+
+
+class AuthenticationError(APIError):
+    """401 — the token is missing, malformed, or expired."""
+
+
+class BillingError(APIError):
+    """402 — the organization's billing is pending setup or restricted."""
+
+
+class ForbiddenError(APIError):
+    """403 — the token's role lacks the required read/write access."""
+
+
+class NotFoundError(APIError):
+    """404 — the project, environment, or key was not found (or is out of scope)."""
+
+
+class ValidationError(APIError):
+    """400 / 413 / 422 — the request was rejected; nothing was written."""
+
+
+class ServerError(APIError):
+    """5xx — the server failed to process an otherwise valid request."""
+
+
+_STATUS_TO_CLASS = {
+    401: AuthenticationError,
+    402: BillingError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    400: ValidationError,
+    413: ValidationError,
+    422: ValidationError,
+}
+
+
+def error_from_response(status_code: int, body: Any, raw: str) -> APIError:
+    """Map an HTTP status + parsed body onto the most specific error class."""
+    message: Optional[str] = None
+    billing_status: Optional[str] = None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, str) and err:
+            message = err
+        bs = body.get("billing_status")
+        if isinstance(bs, str):
+            billing_status = bs
+    if not message:
+        message = raw or f"HTTP {status_code}"
+
+    cls = _STATUS_TO_CLASS.get(status_code)
+    if cls is None:
+        cls = ServerError if status_code >= 500 else APIError
+    return cls(message, status_code=status_code, billing_status=billing_status)

clovrix-0.1.0/tests/test_client.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from clovrix import (
+    AsyncClient,
+    BillingError,
+    Client,
+    ClovrixConfigError,
+    NotFoundError,
+    ValidationError,
+    WriteItem,
+)
+
+TOKEN = "icr_test_token"
+
+
+class MockAPI:
+    """A configurable httpx MockTransport handler that records requests."""
+
+    def __init__(self, status: int = 200, body: object | None = None) -> None:
+        self.status = status
+        self.body = {} if body is None else body
+        self.requests: list[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return httpx.Response(self.status, json=self.body)
+
+    def sync_client(self, token: str | None = TOKEN, **kwargs: object) -> Client:
+        http = httpx.Client(transport=httpx.MockTransport(self))
+        return Client(token=token, base_url="https://app.clovrix.com", http_client=http, **kwargs)
+
+    def async_client(self, token: str | None = TOKEN) -> AsyncClient:
+        http = httpx.AsyncClient(transport=httpx.MockTransport(self))
+        return AsyncClient(token=token, base_url="https://app.clovrix.com", http_client=http)
+
+
+def test_requires_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLOVRIX_TOKEN", raising=False)
+    with pytest.raises(ClovrixConfigError):
+        Client()
+
+
+def test_reads_env_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLOVRIX_TOKEN", TOKEN)
+    api = MockAPI(body={"entries": {}})
+    http = httpx.Client(transport=httpx.MockTransport(api))
+    client = Client(base_url="https://app.clovrix.com", http_client=http)
+    client.get_entries("backend", "production")
+    assert api.requests[0].headers["authorization"] == f"Bearer {TOKEN}"
+
+
+def test_default_base_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CLOVRIX_API_URL", raising=False)
+    api = MockAPI(body={"entries": {}})
+    http = httpx.Client(transport=httpx.MockTransport(api))
+    client = Client(token=TOKEN, http_client=http)
+    client.get_entries("backend", "production")
+    assert str(api.requests[0].url) == (
+        "https://app.clovrix.com/api/public/v1/projects/backend/environments/production/entries"
+    )
+
+
+def test_get_entry() -> None:
+    api = MockAPI(body={"key": "DATABASE_URL", "value": "postgres://x", "is_secret": True})
+    client = api.sync_client()
+    entry = client.get_entry("backend", "production", "DATABASE_URL")
+    assert (entry.key, entry.value, entry.is_secret) == ("DATABASE_URL", "postgres://x", True)
+    req = api.requests[0]
+    assert req.method == "GET"
+    assert req.url.path == (
+        "/api/public/v1/projects/backend/environments/production/entries/DATABASE_URL"
+    )
+    assert req.headers["authorization"] == f"Bearer {TOKEN}"
+
+
+def test_get_entries() -> None:
+    api = MockAPI(body={"entries": {"A": "1", "B": "2"}})
+    client = api.sync_client()
+    assert client.get_entries("backend", "production") == {"A": "1", "B": "2"}
+
+
+def test_get_entries_tolerates_missing_field() -> None:
+    api = MockAPI(body={})
+    client = api.sync_client()
+    assert client.get_entries("backend", "production") == {}
+
+
+def test_set_entry_created() -> None:
+    api = MockAPI(status=201, body={"key": "API_KEY", "created": True})
+    client = api.sync_client()
+    result = client.set_entry("backend", "production", "API_KEY", "secret", is_secret=True)
+    assert result.key == "API_KEY"
+    assert result.created is True
+    sent = json.loads(api.requests[0].content)
+    assert sent == {"value": "secret", "is_secret": True}
+
+
+def test_set_entry_update_omits_is_secret() -> None:
+    api = MockAPI(status=200, body={"key": "API_KEY", "created": False})
+    client = api.sync_client()
+    result = client.set_entry("backend", "production", "API_KEY", "v2")
+    assert result.created is False
+    assert json.loads(api.requests[0].content) == {"value": "v2"}
+
+
+def test_set_entries() -> None:
+    api = MockAPI(body={"written": 2})
+    client = api.sync_client()
+    written = client.set_entries(
+        "backend",
+        "production",
+        [WriteItem(key="A", value="1"), WriteItem(key="B", value="2", is_secret=True)],
+    )
+    assert written == 2
+    assert json.loads(api.requests[0].content) == {
+        "entries": [
+            {"key": "A", "value": "1"},
+            {"key": "B", "value": "2", "is_secret": True},
+        ]
+    }
+
+
+def test_set_entries_accepts_mappings() -> None:
+    api = MockAPI(body={"written": 1})
+    client = api.sync_client()
+    assert client.set_entries("backend", "production", [{"key": "A", "value": "1"}]) == 1
+
+
+def test_url_encodes_segments() -> None:
+    api = MockAPI(body={"key": "A_KEY", "value": "1", "is_secret": False})
+    client = api.sync_client()
+    client.get_entry("my project", "production", "A_KEY")
+    assert b"/projects/my%20project/environments/production/entries/A_KEY" in api.requests[0].url.raw_path
+
+
+def test_not_found() -> None:
+    api = MockAPI(status=404, body={"error": "not found"})
+    client = api.sync_client()
+    with pytest.raises(NotFoundError) as exc:
+        client.get_entry("backend", "production", "MISSING")
+    assert exc.value.status_code == 404
+    assert str(exc.value) == "not found"
+
+
+def test_billing_error() -> None:
+    api = MockAPI(status=402, body={"error": "billing restricted", "billing_status": "restricted"})
+    client = api.sync_client()
+    with pytest.raises(BillingError) as exc:
+        client.get_entries("backend", "production")
+    assert exc.value.status_code == 402
+    assert exc.value.billing_status == "restricted"
+
+
+def test_validation_error() -> None:
+    api = MockAPI(status=422, body={"error": "invalid key"})
+    client = api.sync_client()
+    with pytest.raises(ValidationError):
+        client.set_entries("backend", "production", [WriteItem("bad key", "x")])
+
+
+def test_async_round_trip() -> None:
+    api = MockAPI(body={"entries": {"A": "1"}})
+
+    async def run() -> dict[str, str]:
+        async with api.async_client() as client:
+            return await client.get_entries("backend", "production")
+
+    assert asyncio.run(run()) == {"A": "1"}
+    assert api.requests[0].headers["authorization"] == f"Bearer {TOKEN}"