serva 0.1.0__tar.gz

serva-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Servamind. All Rights Reserved.
+
+This software and associated files are proprietary to Servamind. Unauthorized
+copying, modification, distribution, or use of this software, via any medium,
+is strictly prohibited without prior written permission.

serva-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: serva
+Version: 0.1.0
+Summary: Official Python client for the Serva encode/decode API
+Author: Servamind
+License: Proprietary - All Rights Reserved
+Project-URL: Homepage, https://serva.servamind.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Dynamic: license-file
+
+# serva
+
+Official Python client for the Serva encode/decode API.
+
+## Install
+
+```bash
+pip install serva
+```
+
+## Usage
+
+Generate an API key from [serva.servamind.com](https://serva.servamind.com), then:
+
+```python
+from serva import Serva
+
+client = Serva(api_key="sk_live_...")   # or set SERVA_API_KEY
+
+# Encode a file to the .serva format
+result = client.encode("photo.raw", password="my-secret")
+print(result.output_path, result.savings_percent)
+
+# Decode it back
+client.decode("photo.serva", password="my-secret", output="photo.raw")
+```
+
+## Configuration
+
+| Setting | How | Default |
+|---|---|---|
+| API key | `Serva(api_key=...)` or `SERVA_API_KEY` | — (required) |
+| Base URL | `Serva(base_url=...)` or `SERVA_BASE_URL` | `https://serva.servamind.com` |
+
+
+
+## Errors
+
+All failures raise a subclass of `ServaError`: `AuthError` (401),
+`PaymentRequiredError` (403), `FileTooLargeError` (413), `RateLimitError` (429).
+
+## Versioning
+
+Semantic versioning. The current version is available as `serva.__version__`.

serva-0.1.0/README.md

@@ -0,0 +1,44 @@
+# serva
+
+Official Python client for the Serva encode/decode API.
+
+## Install
+
+```bash
+pip install serva
+```
+
+## Usage
+
+Generate an API key from [serva.servamind.com](https://serva.servamind.com), then:
+
+```python
+from serva import Serva
+
+client = Serva(api_key="sk_live_...")   # or set SERVA_API_KEY
+
+# Encode a file to the .serva format
+result = client.encode("photo.raw", password="my-secret")
+print(result.output_path, result.savings_percent)
+
+# Decode it back
+client.decode("photo.serva", password="my-secret", output="photo.raw")
+```
+
+## Configuration
+
+| Setting | How | Default |
+|---|---|---|
+| API key | `Serva(api_key=...)` or `SERVA_API_KEY` | — (required) |
+| Base URL | `Serva(base_url=...)` or `SERVA_BASE_URL` | `https://serva.servamind.com` |
+
+
+
+## Errors
+
+All failures raise a subclass of `ServaError`: `AuthError` (401),
+`PaymentRequiredError` (403), `FileTooLargeError` (413), `RateLimitError` (429).
+
+## Versioning
+
+Semantic versioning. The current version is available as `serva.__version__`.

serva-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serva"
+version = "0.1.0"
+description = "Official Python client for the Serva encode/decode API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary - All Rights Reserved" }
+authors = [{ name = "Servamind" }]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+]
+
+[project.urls]
+Homepage = "https://serva.servamind.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+serva = ["py.typed"]

serva-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serva-0.1.0/src/serva/__init__.py

@@ -0,0 +1,23 @@
+from serva.client import Serva
+from serva.models import DecodeResult, EncodeResult
+from serva.exceptions import (
+    AuthError,
+    FileTooLargeError,
+    PaymentRequiredError,
+    RateLimitError,
+    ServaError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Serva",
+    "EncodeResult",
+    "DecodeResult",
+    "ServaError",
+    "AuthError",
+    "PaymentRequiredError",
+    "FileTooLargeError",
+    "RateLimitError",
+    "__version__",
+]

serva-0.1.0/src/serva/_decode.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from serva._http import HttpClient
+from serva.models import DecodeResult
+
+
+def decode_file(
+    http: HttpClient, path: str, password: str, output: str | None = None
+) -> DecodeResult:
+    """Decode a .serva file back to the original. Returns where it was written."""
+    source = Path(path)
+    size = source.stat().st_size
+    file_reference = str(uuid.uuid4())
+
+    init = http.post_json(
+        "/api/decode",
+        {
+            "file_reference": file_reference,
+            "file_size_bytes": size,
+            "user_password": password,
+        },
+    )
+
+    result = http.post_bytes(
+        "/api/decode",
+        source,
+        {
+            "X-Streaming-Token": init["streaming_token"],
+            "X-Decode-Password": password,
+        },
+    )
+
+    original_filename = result.get("original_filename", "decoded.out")
+    destination = Path(output) if output else source.parent / original_filename
+    http.download_to(f"/download/{result['file_id']}", destination)
+
+    return DecodeResult(
+        output_path=destination,
+        file_id=result["file_id"],
+        original_filename=original_filename,
+        size_bytes=result.get("file_size_bytes", 0),
+    )

serva-0.1.0/src/serva/_encode.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from serva._http import HttpClient
+from serva.models import EncodeResult
+
+
+def encode_file(
+    http: HttpClient, path: str, password: str, output: str | None = None
+) -> EncodeResult:
+    """Encode a file to the .serva format. Returns where it was written."""
+    source = Path(path)
+    size = source.stat().st_size
+    file_reference = str(uuid.uuid4())
+
+    init = http.post_json(
+        "/api/encode",
+        {
+            "file_reference": file_reference,
+            "idempotency_key": str(uuid.uuid4()),
+            "file_size_bytes": size,
+            "file_extension": source.suffix[:10],
+            "original_filename": source.name[:512],
+            "user_password": password,
+        },
+    )
+
+    stats = http.post_bytes(
+        f"/api/stream/{file_reference}",
+        source,
+        {"X-Streaming-Token": init["streaming_token"]},
+    )
+
+    destination = Path(output) if output else source.with_suffix(".serva")
+    http.download_to(f"/download/{init['file_id']}", destination)
+
+    return EncodeResult(
+        output_path=destination,
+        file_id=init["file_id"],
+        original_size_bytes=stats.get("original_size_bytes", size),
+        encoded_size_bytes=stats.get("encoded_size_bytes", 0),
+        savings_percent=stats.get("savings_percent", 0.0),
+        roundtrip_ok=stats.get("roundtrip_hashes_match", False),
+    )

serva-0.1.0/src/serva/_http.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Iterator, Mapping
+
+import httpx
+
+from serva.exceptions import AuthError, error_from_response
+
+DEFAULT_BASE_URL = "https://serva.servamind.com"
+UPLOAD_CHUNK_SIZE = 1024 * 1024
+DOWNLOAD_CHUNK_SIZE = 1024 * 1024
+
+
+class HttpClient:
+    """Thin wrapper over httpx that carries auth and maps errors."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("SERVA_API_KEY")
+        if not api_key:
+            raise AuthError("No API key provided. Pass api_key=... or set SERVA_API_KEY.")
+        base = base_url or os.environ.get("SERVA_BASE_URL") or DEFAULT_BASE_URL
+        self._client = httpx.Client(
+            base_url=base.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    def post_json(self, path: str, payload: Mapping[str, Any]) -> dict:
+        resp = self._client.post(path, json=payload)
+        return self._json_or_raise(resp)
+
+    def post_bytes(
+        self, path: str, source: Path, headers: Mapping[str, str]
+    ) -> dict:
+        merged = {"Content-Type": "application/octet-stream", **headers}
+        resp = self._client.post(path, content=_file_chunks(source), headers=merged)
+        return self._json_or_raise(resp)
+
+    def download_to(self, path: str, destination: Path) -> None:
+        with self._client.stream("GET", path) as resp:
+            if resp.status_code >= 400:
+                resp.read()
+                self._raise(resp)
+            with open(destination, "wb") as out:
+                for chunk in resp.iter_bytes(DOWNLOAD_CHUNK_SIZE):
+                    out.write(chunk)
+
+    def close(self) -> None:
+        self._client.close()
+
+    @staticmethod
+    def _json_or_raise(resp: httpx.Response) -> dict:
+        if resp.status_code >= 400:
+            HttpClient._raise(resp)
+        return resp.json()
+
+    @staticmethod
+    def _raise(resp: httpx.Response) -> None:
+        try:
+            detail = resp.json()
+        except Exception:
+            detail = resp.text
+        raise error_from_response(resp.status_code, detail)
+
+
+def _file_chunks(source: Path) -> Iterator[bytes]:
+    with open(source, "rb") as f:
+        while True:
+            chunk = f.read(UPLOAD_CHUNK_SIZE)
+            if not chunk:
+                break
+            yield chunk

serva-0.1.0/src/serva/client.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from serva._decode import decode_file
+from serva._encode import encode_file
+from serva._http import HttpClient
+from serva.models import DecodeResult, EncodeResult
+
+
+class Serva:
+    """Client for the Serva encode/decode API.
+
+    Usage:
+        client = Serva(api_key="sk_live_...")
+        client.encode("photo.raw", password="secret")
+        client.decode("photo.serva", password="secret")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self._http = HttpClient(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def encode(
+        self, path: str, password: str, output: str | None = None
+    ) -> EncodeResult:
+        """Encode a file to the .serva format. Returns where it was written."""
+        return encode_file(self._http, path, password, output)
+
+    def decode(
+        self, path: str, password: str, output: str | None = None
+    ) -> DecodeResult:
+        """Decode a .serva file back to the original. Returns where it was written."""
+        return decode_file(self._http, path, password, output)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Serva":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

serva-0.1.0/src/serva/exceptions.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class ServaError(Exception):
+    """Base error for all Serva client failures."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(ServaError):
+    """The API key is missing, invalid, or expired (HTTP 401)."""
+
+
+class PaymentRequiredError(ServaError):
+    """A payment method is required to continue (HTTP 403)."""
+
+
+class FileTooLargeError(ServaError):
+    """The input file exceeds the maximum allowed size (HTTP 413)."""
+
+
+class RateLimitError(ServaError):
+    """The request was rate limited (HTTP 429)."""
+
+
+def error_from_response(status_code: int, detail: object) -> ServaError:
+    """Map an HTTP status code to the matching typed error."""
+    message = f"Serva API error {status_code}: {detail}"
+    if status_code == 401:
+        return AuthError(message, status_code)
+    if status_code == 403:
+        return PaymentRequiredError(message, status_code)
+    if status_code == 413:
+        return FileTooLargeError(message, status_code)
+    if status_code == 429:
+        return RateLimitError(message, status_code)
+    return ServaError(message, status_code)

serva-0.1.0/src/serva/models.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class EncodeResult:
+    output_path: Path
+    file_id: str
+    original_size_bytes: int
+    encoded_size_bytes: int
+    savings_percent: float
+    roundtrip_ok: bool
+
+
+@dataclass
+class DecodeResult:
+    output_path: Path
+    file_id: str
+    original_filename: str
+    size_bytes: int

serva-0.1.0/src/serva.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: serva
+Version: 0.1.0
+Summary: Official Python client for the Serva encode/decode API
+Author: Servamind
+License: Proprietary - All Rights Reserved
+Project-URL: Homepage, https://serva.servamind.com
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Dynamic: license-file
+
+# serva
+
+Official Python client for the Serva encode/decode API.
+
+## Install
+
+```bash
+pip install serva
+```
+
+## Usage
+
+Generate an API key from [serva.servamind.com](https://serva.servamind.com), then:
+
+```python
+from serva import Serva
+
+client = Serva(api_key="sk_live_...")   # or set SERVA_API_KEY
+
+# Encode a file to the .serva format
+result = client.encode("photo.raw", password="my-secret")
+print(result.output_path, result.savings_percent)
+
+# Decode it back
+client.decode("photo.serva", password="my-secret", output="photo.raw")
+```
+
+## Configuration
+
+| Setting | How | Default |
+|---|---|---|
+| API key | `Serva(api_key=...)` or `SERVA_API_KEY` | — (required) |
+| Base URL | `Serva(base_url=...)` or `SERVA_BASE_URL` | `https://serva.servamind.com` |
+
+
+
+## Errors
+
+All failures raise a subclass of `ServaError`: `AuthError` (401),
+`PaymentRequiredError` (403), `FileTooLargeError` (413), `RateLimitError` (429).
+
+## Versioning
+
+Semantic versioning. The current version is available as `serva.__version__`.

serva-0.1.0/src/serva.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/serva/__init__.py
+src/serva/_decode.py
+src/serva/_encode.py
+src/serva/_http.py
+src/serva/client.py
+src/serva/exceptions.py
+src/serva/models.py
+src/serva/py.typed
+src/serva.egg-info/PKG-INFO
+src/serva.egg-info/SOURCES.txt
+src/serva.egg-info/dependency_links.txt
+src/serva.egg-info/requires.txt
+src/serva.egg-info/top_level.txt
+tests/test_client.py

serva-0.1.0/src/serva.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

serva-0.1.0/src/serva.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.27
+
+[dev]
+pytest>=7.4

serva-0.1.0/src/serva.egg-info/top_level.txt

@@ -0,0 +1 @@
+serva

serva-0.1.0/tests/test_client.py

@@ -0,0 +1,20 @@
+import pytest
+
+import serva
+from serva import AuthError, Serva
+
+
+def test_version():
+    assert serva.__version__ == "0.1.0"
+
+
+def test_requires_api_key(monkeypatch):
+    monkeypatch.delenv("SERVA_API_KEY", raising=False)
+    with pytest.raises(AuthError):
+        Serva(api_key=None)
+
+
+def test_reads_key_from_env(monkeypatch):
+    monkeypatch.setenv("SERVA_API_KEY", "sk_live_test")
+    client = Serva(base_url="http://localhost")
+    client.close()