privconvert 0.1.0__tar.gz

privconvert-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

privconvert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrivConvert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

privconvert-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: privconvert
+Version: 0.1.0
+Summary: Official Python client for the PrivConvert file conversion API. Files are processed in memory and never stored.
+Project-URL: Homepage, https://privconvert.com/developers/
+Project-URL: Documentation, https://privconvert.com/docs/
+Project-URL: Source, https://github.com/toprivHQ/privconvert-python
+Author-email: PrivConvert <contact@topriv.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,converter,file conversion,pdf,privacy,privconvert
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# PrivConvert for Python
+
+Official Python client for the [PrivConvert API](https://privconvert.com/developers/): file conversion for your app with zero data retention. Every file is processed in memory on our side and never written to disk.
+
+- No dependencies, standard library only
+- Python 3.10+
+- Large files (above 90 MB) are uploaded in parts automatically
+- Async jobs, webhook signature verification and typed errors included
+
+## Install
+
+```bash
+pip install privconvert
+```
+
+## Quick start
+
+Create a key on your [account page](https://privconvert.com/account/#apikeys) (new accounts can start a free trial of 25 conversions) and set it as an environment variable:
+
+```bash
+export PRIVCONVERT_API_KEY=pk_live_...
+```
+
+```python
+from privconvert import PrivConvert
+
+pc = PrivConvert()
+
+result = pc.convert("word-to-pdf", "contract.docx")
+result.save("contract.pdf")
+print(result.credits_remaining)
+```
+
+`file` can be a path, `bytes`, or a binary file object. Extra keyword arguments are sent as form fields:
+
+```python
+pc.convert("compress-image", open("photo.png", "rb"), quality=70).save("photo-small.png")
+pc.convert("resize-image", image_bytes, filename="in.jpg", width=800)
+```
+
+The tool id is the same slug as on the site. List them with `pc.tools()` or `pc.tools(category="document")`.
+
+## Many files at once
+
+Up to 20 files in one request, returned as a ZIP. A batch costs one slot of your per-minute rate limit.
+
+```python
+zip_result = pc.convert_batch("png-to-jpg", ["a.png", "b.png", "c.png"])
+zip_result.save("converted.zip")
+if zip_result.partial:
+    print(zip_result.failed_count, "files were skipped, see PRIVCONVERT-ERRORS.txt in the ZIP")
+```
+
+## Async jobs
+
+```python
+job = pc.submit_job("pptx-to-pdf", "deck.pptx")
+# job.key is returned once. Keep it if you need to download later or verify webhooks.
+result = pc.wait(job)          # polls, downloads, then deletes the stored result
+result.save("deck.pdf")
+```
+
+With a webhook instead of polling:
+
+```python
+job = pc.submit_job("pptx-to-pdf", "deck.pptx", webhook_url="https://example.com/hooks/privconvert")
+save_somewhere(job.id, job.key)
+# later, when the webhook arrives:
+result = pc.download_job(job)
+```
+
+## Verifying webhooks
+
+Pass the raw request bytes, not parsed JSON:
+
+```python
+from privconvert import verify_webhook
+
+@app.post("/hooks/privconvert")
+def hook():
+    job_key = load_job_key(request.json["id"])
+    if not verify_webhook(job_key, request.headers.get("X-PrivConvert-Signature"), request.get_data()):
+        abort(400)
+    ...
+```
+
+Deliveries older than 5 minutes are rejected as replays (`tolerance_s` to change it).
+
+## Errors
+
+Every error is a `PrivConvertError` with `status`, `code`, `message` and `retry_after`:
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | Missing or invalid key (401) |
+| `BadRequestError` | Bad request or unreadable input (400) |
+| `FileTooLargeError` | Above your plan's size limit (413) |
+| `UnsupportedTypeError` | Wrong input type for the tool (415) |
+| `ConversionFailedError` | File read but could not be converted (422) |
+| `RateLimitError` | Per-minute rate or monthly quota exceeded (429) |
+| `ConcurrencyLimitError` | Too many conversions at once (429) |
+| `ServerError` | Problem on our side (5xx) |
+
+Short 429 and 503 responses are retried automatically (`max_retries=2`), honouring `Retry-After`. A long `Retry-After`, which means the monthly quota is used up, raises at once instead of sleeping.
+
+## Usage and limits
+
+```python
+pc.me()
+# {'tier': 'growth', 'quota': 50000, 'used': 1234, 'remaining': 48766, 'rpm': 120, ...}
+```
+
+## Security notes
+
+- The key is read from `PRIVCONVERT_API_KEY` or passed explicitly, and never appears in `repr()` or error messages.
+- Requests go over HTTPS only. A plain `http://` base URL is refused.
+- This package writes nothing to disk except where you call `Result.save()`.
+
+## Links
+
+- [API documentation](https://privconvert.com/docs/)
+- [Pricing and free trial](https://privconvert.com/developers/)
+- Support: contact@topriv.com
+
+MIT License

privconvert-0.1.0/README.md

@@ -0,0 +1,125 @@
+# PrivConvert for Python
+
+Official Python client for the [PrivConvert API](https://privconvert.com/developers/): file conversion for your app with zero data retention. Every file is processed in memory on our side and never written to disk.
+
+- No dependencies, standard library only
+- Python 3.10+
+- Large files (above 90 MB) are uploaded in parts automatically
+- Async jobs, webhook signature verification and typed errors included
+
+## Install
+
+```bash
+pip install privconvert
+```
+
+## Quick start
+
+Create a key on your [account page](https://privconvert.com/account/#apikeys) (new accounts can start a free trial of 25 conversions) and set it as an environment variable:
+
+```bash
+export PRIVCONVERT_API_KEY=pk_live_...
+```
+
+```python
+from privconvert import PrivConvert
+
+pc = PrivConvert()
+
+result = pc.convert("word-to-pdf", "contract.docx")
+result.save("contract.pdf")
+print(result.credits_remaining)
+```
+
+`file` can be a path, `bytes`, or a binary file object. Extra keyword arguments are sent as form fields:
+
+```python
+pc.convert("compress-image", open("photo.png", "rb"), quality=70).save("photo-small.png")
+pc.convert("resize-image", image_bytes, filename="in.jpg", width=800)
+```
+
+The tool id is the same slug as on the site. List them with `pc.tools()` or `pc.tools(category="document")`.
+
+## Many files at once
+
+Up to 20 files in one request, returned as a ZIP. A batch costs one slot of your per-minute rate limit.
+
+```python
+zip_result = pc.convert_batch("png-to-jpg", ["a.png", "b.png", "c.png"])
+zip_result.save("converted.zip")
+if zip_result.partial:
+    print(zip_result.failed_count, "files were skipped, see PRIVCONVERT-ERRORS.txt in the ZIP")
+```
+
+## Async jobs
+
+```python
+job = pc.submit_job("pptx-to-pdf", "deck.pptx")
+# job.key is returned once. Keep it if you need to download later or verify webhooks.
+result = pc.wait(job)          # polls, downloads, then deletes the stored result
+result.save("deck.pdf")
+```
+
+With a webhook instead of polling:
+
+```python
+job = pc.submit_job("pptx-to-pdf", "deck.pptx", webhook_url="https://example.com/hooks/privconvert")
+save_somewhere(job.id, job.key)
+# later, when the webhook arrives:
+result = pc.download_job(job)
+```
+
+## Verifying webhooks
+
+Pass the raw request bytes, not parsed JSON:
+
+```python
+from privconvert import verify_webhook
+
+@app.post("/hooks/privconvert")
+def hook():
+    job_key = load_job_key(request.json["id"])
+    if not verify_webhook(job_key, request.headers.get("X-PrivConvert-Signature"), request.get_data()):
+        abort(400)
+    ...
+```
+
+Deliveries older than 5 minutes are rejected as replays (`tolerance_s` to change it).
+
+## Errors
+
+Every error is a `PrivConvertError` with `status`, `code`, `message` and `retry_after`:
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | Missing or invalid key (401) |
+| `BadRequestError` | Bad request or unreadable input (400) |
+| `FileTooLargeError` | Above your plan's size limit (413) |
+| `UnsupportedTypeError` | Wrong input type for the tool (415) |
+| `ConversionFailedError` | File read but could not be converted (422) |
+| `RateLimitError` | Per-minute rate or monthly quota exceeded (429) |
+| `ConcurrencyLimitError` | Too many conversions at once (429) |
+| `ServerError` | Problem on our side (5xx) |
+
+Short 429 and 503 responses are retried automatically (`max_retries=2`), honouring `Retry-After`. A long `Retry-After`, which means the monthly quota is used up, raises at once instead of sleeping.
+
+## Usage and limits
+
+```python
+pc.me()
+# {'tier': 'growth', 'quota': 50000, 'used': 1234, 'remaining': 48766, 'rpm': 120, ...}
+```
+
+## Security notes
+
+- The key is read from `PRIVCONVERT_API_KEY` or passed explicitly, and never appears in `repr()` or error messages.
+- Requests go over HTTPS only. A plain `http://` base URL is refused.
+- This package writes nothing to disk except where you call `Result.save()`.
+
+## Links
+
+- [API documentation](https://privconvert.com/docs/)
+- [Pricing and free trial](https://privconvert.com/developers/)
+- Support: contact@topriv.com
+
+MIT License

privconvert-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "privconvert"
+dynamic = ["version"]
+description = "Official Python client for the PrivConvert file conversion API. Files are processed in memory and never stored."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "PrivConvert", email = "contact@topriv.com" }]
+keywords = ["privconvert", "file conversion", "pdf", "api", "converter", "privacy"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Office/Business",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://privconvert.com/developers/"
+Documentation = "https://privconvert.com/docs/"
+Source = "https://github.com/toprivHQ/privconvert-python"
+
+[tool.hatch.version]
+path = "src/privconvert/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/privconvert"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/privconvert", "tests", "README.md", "LICENSE"]

privconvert-0.1.0/src/privconvert/__init__.py

@@ -0,0 +1,45 @@
+"""Official Python client for the PrivConvert API.
+
+    from privconvert import PrivConvert
+
+    pc = PrivConvert()  # reads PRIVCONVERT_API_KEY
+    pc.convert("word-to-pdf", "contract.docx").save("contract.pdf")
+"""
+
+from ._client import PrivConvert, Result, Job, JobStatus
+from ._errors import (
+    PrivConvertError,
+    AuthenticationError,
+    BadRequestError,
+    FileTooLargeError,
+    UnsupportedTypeError,
+    ConversionFailedError,
+    RateLimitError,
+    ConcurrencyLimitError,
+    ServerError,
+    JobExpiredError,
+    JobNotFoundError,
+)
+from ._webhooks import verify_webhook, WebhookVerificationError
+from ._version import __version__
+
+__all__ = [
+    "PrivConvert",
+    "Result",
+    "Job",
+    "JobStatus",
+    "PrivConvertError",
+    "AuthenticationError",
+    "BadRequestError",
+    "FileTooLargeError",
+    "UnsupportedTypeError",
+    "ConversionFailedError",
+    "RateLimitError",
+    "ConcurrencyLimitError",
+    "ServerError",
+    "JobExpiredError",
+    "JobNotFoundError",
+    "verify_webhook",
+    "WebhookVerificationError",
+    "__version__",
+]

privconvert-0.1.0/src/privconvert/_client.py

@@ -0,0 +1,498 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import secrets
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import IO, Any, Dict, Iterable, List, Mapping, Optional, Tuple, Union
+
+from ._errors import PrivConvertError, error_for
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://privconvert.com/api"
+
+# A single POST accepts up to 100 MB; above this the file goes through the
+# chunked upload flow. Parts stay well below the 95 MB per-part ceiling so a
+# slow link never holds one request open long enough to time out at the edge.
+DIRECT_LIMIT = 90 * 1024 * 1024
+CHUNK_SIZE = 20 * 1024 * 1024
+
+# A Retry-After longer than this means the monthly quota is used up, not a
+# momentary limit, so the call fails instead of sleeping.
+MAX_RETRY_WAIT_S = 60.0
+
+_TOOL_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+_JOB_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+_STATUS_BY_CODE = {
+    "bad_request": 400,
+    "unauthorized": 401,
+    "file_too_large": 413,
+    "unsupported_type": 415,
+    "conversion_failed": 422,
+    "rate_limited": 429,
+    "concurrency_limited": 429,
+    "server_error": 500,
+    "server_busy": 503,
+}
+
+FileInput = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, IO[bytes]]
+
+
+@dataclass
+class Result:
+    """A converted file, held in memory."""
+
+    content: bytes
+    filename: Optional[str]
+    content_type: Optional[str]
+    headers: Dict[str, str] = field(repr=False, default_factory=dict)
+
+    @property
+    def credits_remaining(self) -> Optional[int]:
+        v = self.headers.get("x-credits-remaining")
+        return int(v) if v and v.isdigit() else None
+
+    @property
+    def converted_count(self) -> Optional[int]:
+        v = self.headers.get("x-converted-count")
+        return int(v) if v and v.isdigit() else None
+
+    @property
+    def failed_count(self) -> int:
+        v = self.headers.get("x-failed-count")
+        return int(v) if v and v.isdigit() else 0
+
+    @property
+    def partial(self) -> bool:
+        return "x-partial-success" in self.headers
+
+    @property
+    def sanitize_report(self) -> Optional[Dict[str, Any]]:
+        v = self.headers.get("x-sanitize-report")
+        if not v:
+            return None
+        try:
+            return json.loads(v)
+        except ValueError:
+            return None
+
+    def save(self, path: Union[str, "os.PathLike[str]"]) -> str:
+        """Write the result to ``path`` and return the path."""
+        p = os.fspath(path)
+        with open(p, "wb") as f:
+            f.write(self.content)
+        return p
+
+
+@dataclass
+class Job:
+    """A submitted async job. ``key`` is returned exactly once: store it."""
+
+    id: str
+    key: str = field(repr=False)
+    status: str = "processing"
+
+
+@dataclass
+class JobStatus:
+    id: str
+    status: str
+    raw: Dict[str, Any] = field(repr=False)
+
+    @property
+    def done(self) -> bool:
+        return self.status in ("finished", "failed")
+
+    @property
+    def error(self) -> Optional[Dict[str, Any]]:
+        e = self.raw.get("error")
+        return e if isinstance(e, dict) else None
+
+    @property
+    def expires_at(self) -> Optional[int]:
+        return self.raw.get("expires_at")
+
+
+class PrivConvert:
+    """Client for the PrivConvert API.
+
+    The key is read from ``api_key`` or the ``PRIVCONVERT_API_KEY`` environment
+    variable. Files are read into memory and never written to disk by this
+    package; only ``Result.save`` writes, and only where you tell it to.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 300.0,
+        max_retries: int = 2,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("PRIVCONVERT_API_KEY", "")
+        key = (key or "").strip()
+        if not key:
+            raise PrivConvertError("No API key. Pass api_key=... or set PRIVCONVERT_API_KEY.")
+        if any(c.isspace() for c in key) or not key.isprintable():
+            raise PrivConvertError("The API key contains invalid characters.")
+        self._key = key
+        self.base_url = _check_base_url(base_url)
+        self.timeout = float(timeout)
+        self.max_retries = max(0, int(max_retries))
+
+    def __repr__(self) -> str:
+        return f"PrivConvert(base_url={self.base_url!r})"
+
+    # ── conversions ──────────────────────────────────────────────────────
+
+    def convert(
+        self,
+        tool: str,
+        file: FileInput,
+        *,
+        filename: Optional[str] = None,
+        **params: Any,
+    ) -> Result:
+        """Convert one file. Files above 90 MB are uploaded in parts automatically.
+
+        Extra keyword arguments are sent as form fields, e.g. ``quality=80``.
+        """
+        tool = _check_tool(tool)
+        name, data = _read_input(file, filename)
+        if len(data) > DIRECT_LIMIT:
+            return self._convert_chunked(tool, name, data, params)
+        fields = _form_params(params)
+        return self._request_file("POST", f"/convert/{tool}", fields=fields, files=[("file", name, data)])
+
+    def convert_batch(
+        self,
+        tool: str,
+        files: Iterable[FileInput],
+        **params: Any,
+    ) -> Result:
+        """Run one tool over up to 20 files; the result is a ZIP.
+
+        Check ``result.failed_count`` / ``result.partial``: a batch where some
+        files failed still succeeds with the files that converted.
+        """
+        tool = _check_tool(tool)
+        parts = []
+        for i, f in enumerate(files):
+            name, data = _read_input(f, None)
+            if name == "file":
+                name = f"file{i + 1}"
+            parts.append(("files", name, data))
+        if not parts:
+            raise PrivConvertError("convert_batch needs at least one file.")
+        if len(parts) > 20:
+            raise PrivConvertError("convert_batch takes at most 20 files per request.")
+        fields = [("tool", tool)] + _form_params(params)
+        return self._request_file("POST", "/convert-batch", fields=fields, files=parts)
+
+    # ── async jobs ───────────────────────────────────────────────────────
+
+    def submit_job(
+        self,
+        tool: str,
+        file: FileInput,
+        *,
+        filename: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        **params: Any,
+    ) -> Job:
+        """Submit an async job. Returns at once with the job id and one-time key."""
+        tool = _check_tool(tool)
+        name, data = _read_input(file, filename)
+        fields = _form_params(params)
+        if webhook_url:
+            if not str(webhook_url).startswith("https://"):
+                raise PrivConvertError("webhook_url must be an https:// URL.")
+            fields.append(("webhook_url", str(webhook_url)))
+        body = self._request_json("POST", f"/jobs/{tool}", fields=fields, files=[("file", name, data)])
+        if not isinstance(body, dict) or "id" not in body or "key" not in body:
+            raise PrivConvertError("Unexpected response when submitting the job.")
+        return Job(id=str(body["id"]), key=str(body["key"]), status=str(body.get("status", "processing")))
+
+    def get_job(self, job_id: Union[str, Job]) -> JobStatus:
+        jid = _check_job_id(job_id)
+        body = self._request_json("GET", f"/jobs/{jid}", job=True)
+        return JobStatus(id=jid, status=str(body.get("status", "")), raw=body)
+
+    def download_job(self, job: Job) -> Result:
+        jid = _check_job_id(job)
+        return self._request_file(
+            "GET", f"/jobs/{jid}/download", extra_headers={"X-Job-Key": job.key}, job=True
+        )
+
+    def delete_job(self, job_id: Union[str, Job]) -> None:
+        jid = _check_job_id(job_id)
+        self._request("DELETE", f"/jobs/{jid}", job=True)
+
+    def wait(
+        self,
+        job: Job,
+        *,
+        poll_interval: float = 2.0,
+        timeout: float = 1800.0,
+        delete_after: bool = True,
+    ) -> Result:
+        """Poll until the job finishes, then download the result.
+
+        Raises the same error a synchronous call would have raised if the job
+        failed. With ``delete_after`` the stored result is wiped right after
+        download instead of waiting out the retention window.
+        """
+        deadline = time.monotonic() + timeout
+        interval = max(0.5, poll_interval)
+        while True:
+            st = self.get_job(job)
+            if st.status == "finished":
+                break
+            if st.status == "failed":
+                e = st.error or {}
+                code = e.get("code")
+                raise error_for(
+                    _STATUS_BY_CODE.get(str(code), 422),
+                    str(e.get("message") or "The conversion failed."),
+                    code,
+                    None,
+                )
+            if time.monotonic() + interval > deadline:
+                raise PrivConvertError(f"Job {job.id} did not finish within {timeout:.0f}s.")
+            time.sleep(interval)
+            interval = min(interval * 1.5, 10.0)
+        result = self.download_job(job)
+        if delete_after:
+            try:
+                self.delete_job(job)
+            except PrivConvertError:
+                pass
+        return result
+
+    # ── account & catalog ────────────────────────────────────────────────
+
+    def me(self) -> Dict[str, Any]:
+        """Your plan, monthly quota and current usage."""
+        return self._request_json("GET", "/me")
+
+    def tools(self, category: Optional[str] = None) -> List[Dict[str, Any]]:
+        """The public catalog of every tool, optionally filtered by category."""
+        path = "/tools"
+        if category:
+            path += "?" + urllib.parse.urlencode({"category": category})
+        body = self._request_json("GET", path, auth=False)
+        return list(body.get("tools", [])) if isinstance(body, dict) else []
+
+    # ── internals ────────────────────────────────────────────────────────
+
+    def _convert_chunked(self, tool: str, name: str, data: bytes, params: Mapping[str, Any]) -> Result:
+        chunks = [data[i : i + CHUNK_SIZE] for i in range(0, len(data), CHUNK_SIZE)]
+        init = self._request_json(
+            "POST",
+            "/upload-init",
+            fields=[
+                ("total_size", str(len(data))),
+                ("total_chunks", str(len(chunks))),
+                ("filename", name),
+                ("tool", tool),
+            ],
+        )
+        upload_id = str(init.get("upload_id", ""))
+        if not upload_id:
+            raise PrivConvertError("The server did not return an upload id.")
+        for i, chunk in enumerate(chunks):
+            self._request_json(
+                "POST",
+                "/upload-chunk",
+                fields=[("upload_id", upload_id), ("chunk_index", str(i))],
+                files=[("file", "chunk", chunk)],
+            )
+        fields = [("upload_id", upload_id)] + _form_params(params)
+        return self._request_file("POST", "/convert-chunked", fields=fields)
+
+    def _request_file(self, method: str, path: str, **kw: Any) -> Result:
+        status, headers, body = self._request(method, path, **kw)
+        return Result(
+            content=body,
+            filename=_filename_from(headers.get("content-disposition", "")),
+            content_type=headers.get("content-type"),
+            headers=headers,
+        )
+
+    def _request_json(self, method: str, path: str, **kw: Any) -> Dict[str, Any]:
+        status, headers, body = self._request(method, path, **kw)
+        try:
+            out = json.loads(body.decode("utf-8")) if body else {}
+        except ValueError:
+            raise PrivConvertError("The server returned a response that is not JSON.", status=status)
+        return out if isinstance(out, dict) else {"data": out}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        fields: Optional[List[Tuple[str, str]]] = None,
+        files: Optional[List[Tuple[str, str, bytes]]] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        auth: bool = True,
+        job: bool = False,
+    ) -> Tuple[int, Dict[str, str], bytes]:
+        url = self.base_url + path
+        headers = {"User-Agent": f"privconvert-python/{__version__}", "Accept": "*/*"}
+        if auth:
+            headers["Authorization"] = f"Bearer {self._key}"
+        if extra_headers:
+            headers.update(extra_headers)
+        body: Optional[bytes] = None
+        if fields is not None or files is not None:
+            body, ctype = _multipart(fields or [], files or [])
+            headers["Content-Type"] = ctype
+        elif method in ("POST", "PUT"):
+            body = b""
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=body, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return resp.status, _lower(resp.headers.items()), resp.read()
+            except urllib.error.HTTPError as e:
+                status = e.code
+                h = _lower(e.headers.items()) if e.headers else {}
+                raw = e.read() if hasattr(e, "read") else b""
+                message, code = _parse_error(raw, status)
+                retry_after = _retry_after(h.get("retry-after"))
+                retryable = status in (429, 502, 503, 504)
+                wait = retry_after if retry_after is not None else min(2.0 * (2 ** attempt), 20.0)
+                if retryable and attempt < self.max_retries and wait <= MAX_RETRY_WAIT_S:
+                    attempt += 1
+                    time.sleep(wait)
+                    continue
+                raise error_for(status, message, code, retry_after, job=job) from None
+            except urllib.error.URLError as e:
+                raise PrivConvertError(f"Could not reach PrivConvert: {e.reason}") from None
+
+
+def _check_base_url(url: str) -> str:
+    u = urllib.parse.urlsplit(str(url).rstrip("/"))
+    if u.scheme == "https" and u.hostname:
+        return urllib.parse.urlunsplit(u)
+    if u.scheme == "http" and u.hostname in _LOCAL_HOSTS:
+        return urllib.parse.urlunsplit(u)
+    raise PrivConvertError("base_url must use https:// so the API key is never sent in clear text.")
+
+
+def _check_tool(tool: str) -> str:
+    t = str(tool or "").strip().lower()
+    if not _TOOL_RE.match(t):
+        raise PrivConvertError(f"Invalid tool id: {tool!r}")
+    return t
+
+
+def _check_job_id(job: Union[str, Job]) -> str:
+    jid = job.id if isinstance(job, Job) else str(job or "")
+    if not _JOB_ID_RE.match(jid):
+        raise PrivConvertError("Invalid job id.")
+    return jid
+
+
+def _read_input(file: FileInput, filename: Optional[str]) -> Tuple[str, bytes]:
+    if isinstance(file, (bytes, bytearray, memoryview)):
+        return (filename or "file"), bytes(file)
+    if isinstance(file, (str, os.PathLike)):
+        p = os.fspath(file)
+        with open(p, "rb") as f:
+            data = f.read()
+        return (filename or os.path.basename(p) or "file"), data
+    if hasattr(file, "read"):
+        data = file.read()
+        if isinstance(data, str):
+            raise PrivConvertError("Open the file in binary mode ('rb').")
+        name = filename or os.path.basename(str(getattr(file, "name", "") or "")) or "file"
+        return name, bytes(data)
+    raise PrivConvertError("file must be a path, bytes, or a binary file object.")
+
+
+def _form_params(params: Mapping[str, Any]) -> List[Tuple[str, str]]:
+    out: List[Tuple[str, str]] = []
+    for k, v in params.items():
+        if v is None:
+            continue
+        if isinstance(v, bool):
+            v = "true" if v else "false"
+        elif isinstance(v, (list, dict)):
+            v = json.dumps(v)
+        out.append((str(k), str(v)))
+    return out
+
+
+def _safe_header_value(s: str) -> str:
+    return re.sub(r'[\r\n"\\]', "_", s)[:255] or "file"
+
+
+def _multipart(fields: List[Tuple[str, str]], files: List[Tuple[str, str, bytes]]) -> Tuple[bytes, str]:
+    boundary = "----privconvert" + secrets.token_hex(16)
+    parts: List[bytes] = []
+    for name, value in fields:
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{_safe_header_value(name)}"\r\n\r\n'.encode()
+            + value.encode("utf-8")
+            + b"\r\n"
+        )
+    for name, fname, data in files:
+        parts.append(
+            (
+                f"--{boundary}\r\n"
+                f'Content-Disposition: form-data; name="{_safe_header_value(name)}"; filename="{_safe_header_value(fname)}"\r\n'
+                "Content-Type: application/octet-stream\r\n\r\n"
+            ).encode("utf-8")
+            + data
+            + b"\r\n"
+        )
+    parts.append(f"--{boundary}--\r\n".encode())
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+def _lower(items: Iterable[Tuple[str, str]]) -> Dict[str, str]:
+    return {k.lower(): v for k, v in items}
+
+
+def _parse_error(raw: bytes, status: int) -> Tuple[str, Optional[str]]:
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return f"HTTP {status}", None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            return str(err.get("message") or f"HTTP {status}"), err.get("code")
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail, body.get("code")
+        if isinstance(detail, dict):
+            return str(detail.get("message") or f"HTTP {status}"), detail.get("code")
+    return f"HTTP {status}", None
+
+
+def _retry_after(v: Optional[str]) -> Optional[float]:
+    if not v:
+        return None
+    try:
+        return max(0.0, float(v))
+    except ValueError:
+        return None
+
+
+def _filename_from(cd: str) -> Optional[str]:
+    m = re.search(r"filename\*=UTF-8''([^;]+)", cd, re.I)
+    if m:
+        return os.path.basename(urllib.parse.unquote(m.group(1)))
+    m = re.search(r'filename="?([^";]+)"?', cd, re.I)
+    return os.path.basename(m.group(1)) if m else None

privconvert-0.1.0/src/privconvert/_errors.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PrivConvertError(Exception):
+    """Base class for every error raised by this package."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status={self.status!r}, code={self.code!r}, message={self.message!r})"
+
+
+class AuthenticationError(PrivConvertError):
+    """401: missing, invalid or revoked API key."""
+
+
+class BadRequestError(PrivConvertError):
+    """400: malformed request, unknown tool, bad parameter or unreadable input."""
+
+
+class FileTooLargeError(PrivConvertError):
+    """413: the file is above your plan's size limit."""
+
+
+class UnsupportedTypeError(PrivConvertError):
+    """415: the input file type is not valid for this tool."""
+
+
+class ConversionFailedError(PrivConvertError):
+    """422: the file was read but could not be converted."""
+
+
+class RateLimitError(PrivConvertError):
+    """429 rate_limited: per-minute rate or monthly quota exceeded."""
+
+
+class ConcurrencyLimitError(RateLimitError):
+    """429 concurrency_limited: too many conversions running at once."""
+
+
+class ServerError(PrivConvertError):
+    """5xx: a problem on the server side. Safe to retry."""
+
+
+class JobNotFoundError(PrivConvertError):
+    """404 for a job: deleted, never existed, or lost in a service restart."""
+
+
+class JobExpiredError(PrivConvertError):
+    """410: the job result passed its retention window and was deleted."""
+
+
+_BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: AuthenticationError,
+    413: FileTooLargeError,
+    415: UnsupportedTypeError,
+    422: ConversionFailedError,
+    410: JobExpiredError,
+}
+
+
+def error_for(
+    status: int,
+    message: str,
+    code: Optional[str],
+    retry_after: Optional[float],
+    *,
+    job: bool = False,
+) -> PrivConvertError:
+    if status == 429:
+        cls = ConcurrencyLimitError if code == "concurrency_limited" else RateLimitError
+    elif status == 404 and job:
+        cls = JobNotFoundError
+    elif status >= 500:
+        cls = ServerError
+    else:
+        cls = _BY_STATUS.get(status, PrivConvertError)
+    return cls(message, status=status, code=code, retry_after=retry_after)

privconvert-0.1.0/src/privconvert/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

privconvert-0.1.0/src/privconvert/_webhooks.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import time
+from typing import Optional, Union
+
+_SIG_RE = re.compile(r"^t=(\d{1,12}),v1=([0-9a-f]{64})$")
+
+
+class WebhookVerificationError(Exception):
+    """Raised by ``verify_webhook(..., raise_on_error=True)``."""
+
+
+def verify_webhook(
+    job_key: str,
+    signature: Optional[str],
+    raw_body: Union[bytes, bytearray, memoryview],
+    *,
+    tolerance_s: int = 300,
+    now: Optional[float] = None,
+    raise_on_error: bool = False,
+) -> bool:
+    """Check an ``X-PrivConvert-Signature`` header against the raw request body.
+
+    ``raw_body`` must be the exact bytes received, not re-serialized JSON.
+    ``job_key`` is the one-time ``key`` returned when the job was submitted.
+    Deliveries older than ``tolerance_s`` seconds are rejected as replays.
+    """
+
+    def fail(reason: str) -> bool:
+        if raise_on_error:
+            raise WebhookVerificationError(reason)
+        return False
+
+    if not job_key or not isinstance(job_key, str):
+        return fail("missing job key")
+    if not signature or not isinstance(signature, str):
+        return fail("missing signature header")
+    if isinstance(raw_body, str):
+        return fail("raw_body must be bytes, not str")
+    m = _SIG_RE.match(signature.strip())
+    if not m:
+        return fail("malformed signature header")
+    ts = int(m.group(1))
+    current = time.time() if now is None else now
+    if abs(current - ts) > tolerance_s:
+        return fail("timestamp outside tolerance")
+    sig_key = hashlib.sha256(b"pc-webhook-sig-v1|" + job_key.encode("utf-8")).digest()
+    expected = hmac.new(sig_key, f"{ts}.".encode("ascii") + bytes(raw_body), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, m.group(2)):
+        return fail("signature mismatch")
+    return True

privconvert-0.1.0/tests/live_check.py

@@ -0,0 +1,72 @@
+"""Live checks against the real API. Needs PRIVCONVERT_API_KEY; spends a few credits.
+
+    PRIVCONVERT_API_KEY=pk_live_... python tests/live_check.py [--large]
+"""
+
+import io
+import os
+import sys
+import zipfile
+
+import privconvert
+from privconvert import PrivConvert
+
+
+def main() -> int:
+    pc = PrivConvert()
+    ok = True
+
+    def check(name, cond, extra=""):
+        nonlocal ok
+        ok = ok and bool(cond)
+        print(("PASS " if cond else "FAIL ") + name + (f"  {extra}" if extra else ""))
+
+    me = pc.me()
+    check("me", "remaining" in me and "tier" in me, f"tier={me.get('tier')} remaining={me.get('remaining')}")
+
+    tools = pc.tools(category="data")
+    check("tools", any(t.get("id") == "json-to-csv" for t in tools), f"{len(tools)} data tools")
+
+    r = pc.convert("json-to-csv", b'[{"a":1,"b":2},{"a":3,"b":4}]', filename="t.json")
+    check("convert", r.content.replace(b"\r", b"").startswith(b"a,b\n1,2"), f"file={r.filename} left={r.credits_remaining}")
+
+    b = pc.convert_batch("json-to-csv", [io.BytesIO(b'[{"x":1}]'), b'[{"y":2}]', b"not json"])
+    names = zipfile.ZipFile(io.BytesIO(b.content)).namelist()
+    check("batch partial", b.partial and b.failed_count == 1 and b.converted_count == 2, f"{names}")
+
+    job = pc.submit_job("json-to-csv", b'[{"j":9}]', filename="job.json")
+    res = pc.wait(job, poll_interval=1)
+    check("async job", res.content.replace(b"\r", b"").startswith(b"j\n9"), f"id={job.id}")
+    try:
+        pc.get_job(job)
+        check("job deleted after wait", False)
+    except privconvert.JobNotFoundError:
+        check("job deleted after wait", True)
+
+    try:
+        pc.convert("json-to-csv", b"this is not json at all {")
+        check("error mapping", False)
+    except privconvert.PrivConvertError as e:
+        check("error mapping", e.status in (400, 422), f"{type(e).__name__} {e.status} {e.message[:60]}")
+
+    try:
+        PrivConvert(api_key="pk_live_" + "x" * 40).me()
+        check("bad key", False)
+    except privconvert.AuthenticationError:
+        check("bad key", True)
+
+    if "--large" in sys.argv:
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", zipfile.ZIP_STORED) as z:
+            z.writestr("big.bin", os.urandom(95 * 1024 * 1024))
+        data = buf.getvalue()
+        r = pc.convert("zip-to-targz", data, filename="big.zip")
+        check("chunked upload", r.content[:2] == b"\x1f\x8b" and len(r.content) > 90 * 1024 * 1024,
+              f"in={len(data)>>20}MB out={len(r.content)>>20}MB")
+
+    print("ALL PASS" if ok else "SOME FAILED")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

privconvert-0.1.0/tests/test_offline.py

@@ -0,0 +1,147 @@
+"""Offline tests: no network, no API key needed."""
+
+import json
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import privconvert
+from privconvert import PrivConvert, verify_webhook
+from privconvert._client import _multipart, _filename_from
+
+VECTOR_KEY = "pjk_testvector_do_not_use_0000000000000000000"
+VECTOR_TS = 1760000000
+VECTOR_BODY = (
+    b'{"event":"job.finished","event_id":"evt_00000000000000000000000000000000",'
+    b'"id":"job_000000000000000000000000","status":"finished","tool":"txt-to-pdf"}'
+)
+VECTOR_SIG = "t=1760000000,v1=609fa0d5493200864ae983137780d6fa6cfd7946953052fcaf4f6d4b8792803f"
+
+
+class WebhookTests(unittest.TestCase):
+    def test_published_vector(self):
+        self.assertTrue(verify_webhook(VECTOR_KEY, VECTOR_SIG, VECTOR_BODY, now=VECTOR_TS))
+
+    def test_tampered_body(self):
+        self.assertFalse(verify_webhook(VECTOR_KEY, VECTOR_SIG, VECTOR_BODY + b" ", now=VECTOR_TS))
+
+    def test_wrong_key(self):
+        self.assertFalse(verify_webhook(VECTOR_KEY + "x", VECTOR_SIG, VECTOR_BODY, now=VECTOR_TS))
+
+    def test_stale_timestamp(self):
+        self.assertFalse(verify_webhook(VECTOR_KEY, VECTOR_SIG, VECTOR_BODY, now=VECTOR_TS + 301))
+
+    def test_malformed(self):
+        for sig in ("", "t=1,v1=zz", "v1=abc", None, "t=1760000000,v1=" + "0" * 63):
+            self.assertFalse(verify_webhook(VECTOR_KEY, sig, VECTOR_BODY, now=VECTOR_TS))
+
+    def test_str_body_rejected(self):
+        self.assertFalse(verify_webhook(VECTOR_KEY, VECTOR_SIG, VECTOR_BODY.decode(), now=VECTOR_TS))
+
+    def test_raise_on_error(self):
+        with self.assertRaises(privconvert.WebhookVerificationError):
+            verify_webhook(VECTOR_KEY, "bad", VECTOR_BODY, raise_on_error=True)
+
+
+class ClientValidationTests(unittest.TestCase):
+    def test_requires_key(self):
+        with self.assertRaises(privconvert.PrivConvertError):
+            PrivConvert(api_key="")
+
+    def test_refuses_plain_http(self):
+        with self.assertRaises(privconvert.PrivConvertError):
+            PrivConvert(api_key="pk_live_x", base_url="http://example.com/api")
+
+    def test_allows_local_http(self):
+        PrivConvert(api_key="pk_live_x", base_url="http://127.0.0.1:9/api")
+
+    def test_key_not_in_repr(self):
+        pc = PrivConvert(api_key="pk_live_supersecret")
+        self.assertNotIn("supersecret", repr(pc))
+
+    def test_job_key_not_in_repr(self):
+        self.assertNotIn("pjk_secret", repr(privconvert.Job(id="job_1", key="pjk_secret")))
+
+    def test_bad_tool(self):
+        pc = PrivConvert(api_key="pk_live_x")
+        for t in ("../me", "a/b", "", "Word To PDF"):
+            with self.assertRaises(privconvert.PrivConvertError):
+                pc.convert(t, b"x")
+
+    def test_multipart_header_injection(self):
+        body, _ = _multipart([], [("file", 'evil"\r\nX-Injected: 1', b"data")])
+        self.assertNotIn(b"\r\nX-Injected", body)
+
+    def test_filename_parse(self):
+        self.assertEqual(_filename_from('attachment; filename="a.pdf"'), "a.pdf")
+        self.assertEqual(_filename_from("attachment; filename*=UTF-8''%D7%90.pdf"), "\u05d0.pdf")
+        self.assertEqual(_filename_from('attachment; filename="../../etc/x"'), "x")
+
+
+class _Handler(BaseHTTPRequestHandler):
+    calls = []
+
+    def log_message(self, *a):
+        pass
+
+    def _reply(self, status, body, headers=None):
+        data = body if isinstance(body, bytes) else json.dumps(body).encode()
+        self.send_response(status)
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length", "0"))
+        self.rfile.read(n)
+        _Handler.calls.append((self.path, self.headers.get("Authorization")))
+        if self.path == "/api/convert/busy":
+            if sum(1 for p, _ in _Handler.calls if p == self.path) < 2:
+                return self._reply(503, {"error": {"code": "server_busy", "message": "busy"}}, {"Retry-After": "0"})
+            return self._reply(200, b"OK", {"Content-Disposition": 'attachment; filename="out.txt"'})
+        if self.path == "/api/convert/quota":
+            return self._reply(429, {"detail": "quota used"}, {"Retry-After": "86400"})
+        if self.path == "/api/convert/conc":
+            return self._reply(429, {"error": {"code": "concurrency_limited", "message": "slow"}}, {"Retry-After": "0"})
+        return self._reply(
+            200, b"%PDF-1.4", {"Content-Disposition": 'attachment; filename="x.pdf"', "X-Credits-Remaining": "41"}
+        )
+
+
+class FakeServerTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.srv = HTTPServer(("127.0.0.1", 0), _Handler)
+        threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
+        cls.pc = PrivConvert(api_key="pk_live_test", base_url=f"http://127.0.0.1:{cls.srv.server_port}/api")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.srv.shutdown()
+
+    def test_convert(self):
+        r = self.pc.convert("word-to-pdf", b"hello", filename="a.docx")
+        self.assertEqual(r.content, b"%PDF-1.4")
+        self.assertEqual(r.filename, "x.pdf")
+        self.assertEqual(r.credits_remaining, 41)
+        self.assertEqual(_Handler.calls[-1][1], "Bearer pk_live_test")
+
+    def test_retries_busy(self):
+        r = self.pc.convert("busy", b"x")
+        self.assertEqual(r.content, b"OK")
+
+    def test_no_long_sleep_on_quota(self):
+        with self.assertRaises(privconvert.RateLimitError) as cm:
+            self.pc.convert("quota", b"x")
+        self.assertEqual(cm.exception.retry_after, 86400)
+        self.assertEqual(cm.exception.message, "quota used")
+
+    def test_concurrency_error_type(self):
+        with self.assertRaises(privconvert.ConcurrencyLimitError):
+            self.pc.convert("conc", b"x")
+
+
+if __name__ == "__main__":
+    unittest.main()