vecsnap 0.1.0__py3-none-any.whl

vecsnap/__init__.py

@@ -0,0 +1,217 @@
+"""``vecsnap`` — the VecSnap API from Python (``developers.md`` § 8; audit ``developer-platform-2026-10-23`` § 13).
+
+    from vecsnap import VecSnap
+    vecsnap = VecSnap()                                  # reads VECSNAP_API_KEY
+    result = vecsnap.vectorize(file=open("logo.png", "rb").read(), filename="logo.png")
+    open("logo.svg", "wb").write(vecsnap.download(result))
+
+Every operation a key may call is GENERATED from the API's own document (``vecsnap._generated``, never edited by hand —
+``npm --prefix web run gen:clients``) and reachable through ``vecsnap.api`` (its ``Client``, the key set). This module adds
+what generation cannot: ``vectorize`` sends a file as a form and WAITS through a 202, every refusal is a ``VecSnapError``
+with its code, and ``verify_webhook`` checks an event your server received.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import re
+import time
+import uuid
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from ._generated import AuthenticatedClient
+
+__all__ = ["VecSnap", "VecSnapError", "WebhookVerificationError", "verify_webhook", "sign_webhook", "DEFAULT_BASE_URL"]
+
+DEFAULT_BASE_URL = "https://api.vecsnap.com/v1"
+ENDED = {"completed", "failed", "expired", "canceled"}
+#: How far ``webhook-timestamp`` may be from now: the reference libraries' five minutes, either way.
+WEBHOOK_TOLERANCE_SECONDS = 5 * 60
+
+
+class VecSnapError(Exception):
+    """A refusal of the API: its ``code`` (branch on it — every code is on vecsnap.com/docs/errors), its HTTP ``status``,
+    the ``message`` for a person, the ``request_id`` to quote, and for 429 how many seconds to wait (``retry_after``)."""
+
+    def __init__(self, code: str, message: str, status: int = 0, request_id: Optional[str] = None, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.retry_after = retry_after
+        #: For a ``vectorize`` that stopped part way: the conversion it made and the key it sent — call again with it.
+        self.conversion_id: Optional[str] = None
+        self.idempotency_key: Optional[str] = None
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> "VecSnapError":
+        try:
+            retry_after: Optional[float] = float(response.headers["retry-after"])
+        except (KeyError, ValueError):
+            retry_after = None
+        try:
+            error = response.json().get("error") or {}
+        except ValueError:
+            error = {}
+        if isinstance(error.get("code"), str):
+            return cls(error["code"], str(error.get("message", error["code"])), response.status_code, error.get("requestId") or response.headers.get("x-request-id"), retry_after)
+        return cls("unexpected_response", f"the API answered {response.status_code} without an error body", response.status_code, response.headers.get("x-request-id"), retry_after)
+
+
+class VecSnap:
+    """A client for one API key — ``vs_test_…`` (free: a sample result) or ``vs_live_…``."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, http: Optional[httpx.Client] = None, timeout: float = 90.0):
+        key = api_key or os.environ.get("VECSNAP_API_KEY")
+        if not key:
+            raise VecSnapError("missing_api_key", "no API key: pass api_key= or set VECSNAP_API_KEY (vecsnap.com/app/developers)")
+        # A proxy or a test server: base_url=, else VECSNAP_BASE_URL, else the API.
+        self._base_url = (base_url or os.environ.get("VECSNAP_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = http or httpx.Client(timeout=timeout)
+        self._headers = {"authorization": f"Bearer {key}", "accept": "application/json"}
+        #: The generated client, the key set: ``from vecsnap._generated.api.conversions import get_conversion``,
+        #: then ``get_conversion.sync(id=…, client=vecsnap.api)``.
+        self.api = AuthenticatedClient(base_url=self._base_url, token=key, timeout=httpx.Timeout(timeout))
+
+    def vectorize(
+        self,
+        *,
+        file: Optional[bytes] = None,
+        url: Optional[str] = None,
+        input_key: Optional[str] = None,
+        filename: Optional[str] = None,
+        preset: Optional[str] = None,
+        options: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+        wait: int = 30,
+        timeout_seconds: float = 600,
+    ) -> dict:
+        """Convert one image and wait for its SVG: the conversion and a link to each SVG file (``files``). A conversion that
+        outlasts one call (202) is waited for here — read again with backoff, its files then asked for. Raises
+        ``VecSnapError`` (``insufficient_credits``, ``timeout``, …) — past the 202 with ``conversion_id`` and
+        ``idempotency_key``: call again with that key to pick the same conversion up."""
+        if sum(x is not None for x in (file, url, input_key)) != 1:
+            raise VecSnapError("invalid_request", 'give exactly one of "file", "url" or "input_key"')
+        key = idempotency_key or str(uuid.uuid4())
+        sent = dict(file=file, url=url, input_key=input_key, filename=filename, preset=preset, options=options)
+        deadline = time.monotonic() + timeout_seconds
+        status, body = self._vectorize_once(sent, key, wait)
+        if status == 200:
+            return body
+        # A 202: the conversion exists and finishes on its own. Wait for it — and if this call cannot, say which
+        # conversion and which key, so a retry picks the SAME one up (never a second charge).
+        conversion_id = body["id"]
+        try:
+            delay = 1.0
+            while True:
+                if time.monotonic() + delay > deadline:
+                    raise VecSnapError("timeout", f"conversion {conversion_id} had not ended within the time given")
+                time.sleep(delay)
+                delay = min(delay * 1.6, 10.0)
+                try:
+                    conversion = self.conversion(conversion_id)
+                except VecSnapError as error:
+                    if error.status == 429 or error.status >= 500:  # wait longer; never give the conversion up for it
+                        delay = max(delay, error.retry_after or 0)
+                        continue
+                    raise
+                if conversion["status"] in ENDED:
+                    # Its files from the conversion itself — never the request sent again, whose URL may be gone.
+                    return self._with_files(conversion)
+        except VecSnapError as error:
+            error.conversion_id, error.idempotency_key = conversion_id, key
+            raise
+
+    def conversion(self, conversion_id: str) -> dict:
+        """One conversion as it stands. Raises ``VecSnapError`` ``not_found``."""
+        response = self._http.get(f"{self._base_url}/conversions/{conversion_id}", headers=self._headers)
+        if response.status_code != 200:
+            raise VecSnapError.from_response(response)
+        return response.json()
+
+    def _with_files(self, conversion: dict) -> dict:
+        """An ended conversion with a link to each of its files (an image not unlocked has none), as ``vectorize`` answers."""
+        files: dict = {}
+        expires_in = None
+        if conversion["status"] == "completed" and conversion.get("unlocked"):
+            for fmt in (conversion.get("result") or {}).get("formats") or []:
+                response = self._http.get(f"{self._base_url}/conversions/{conversion['id']}/download", headers=self._headers, params={"format": fmt["id"]})
+                if response.status_code != 200:
+                    raise VecSnapError.from_response(response)
+                link = response.json()
+                files[fmt["id"]] = link["url"]
+                expires_in = link["expiresIn"] if expires_in is None else min(expires_in, link["expiresIn"])
+        expires_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(time.time() + (expires_in or 0)))
+        return {**conversion, "files": files, "filesExpireAt": expires_at}
+
+    def download(self, result: Mapping[str, Any], format: str = "web") -> bytes:
+        """The bytes of a vectorized image's SVG (``web`` by default; ``design``, …: each of ``files``)."""
+        link = (result.get("files") or {}).get(format)
+        if not link:
+            raise VecSnapError("format_unavailable", f'no "{format}" file: {", ".join(result.get("files") or {}) or "none"} (an image not unlocked has none)')
+        response = self._http.get(link)
+        if response.status_code != 200:
+            raise VecSnapError("download_failed", f"the file answered {response.status_code} (links last until filesExpireAt)", response.status_code)
+        return response.content
+
+    def _vectorize_once(self, sent: Mapping[str, Any], key: str, wait: int) -> tuple[int, dict]:
+        headers = {**self._headers, "idempotency-key": key}
+        if sent["file"] is not None:
+            data = {"wait": str(wait)}
+            for field in ("filename", "preset"):
+                if sent[field] is not None:
+                    data[field] = sent[field]
+            if sent["options"] is not None:
+                data["options"] = json.dumps(dict(sent["options"]))
+            files = {"file": (sent["filename"] or "image", sent["file"])}
+            response = self._http.post(f"{self._base_url}/vectorize", headers=headers, data=data, files=files)
+        else:
+            payload = {"wait": wait, "url": sent["url"], "inputKey": sent["input_key"], "filename": sent["filename"], "preset": sent["preset"], "options": sent["options"]}
+            response = self._http.post(f"{self._base_url}/vectorize", headers=headers, json={k: v for k, v in payload.items() if v is not None})
+        if response.status_code in (200, 202):
+            return response.status_code, response.json()
+        raise VecSnapError.from_response(response)
+
+
+class WebhookVerificationError(Exception):
+    """Why an event was refused: ``missing_headers``, ``malformed_timestamp``, ``stale``, ``bad_signature`` or ``bad_secret``."""
+
+    def __init__(self, reason: str, message: str):
+        super().__init__(message)
+        self.reason = reason
+
+
+def _secret_key(secret: str) -> bytes:
+    match = re.fullmatch(r"(?:v1,)?whsec_([A-Za-z0-9+/]+={0,2})", secret.strip())
+    if not match:
+        raise WebhookVerificationError("bad_secret", "a webhook secret is whsec_ followed by base64")
+    return base64.b64decode(match.group(1))
+
+
+def sign_webhook(body: str, secret: str, webhook_id: str, timestamp: int) -> str:
+    """``v1,<base64>`` of an event signed with ``secret`` — what VecSnap sends; your tests can sign their own with it."""
+    mac = hmac.new(_secret_key(secret), f"{webhook_id}.{timestamp}.{body}".encode(), hashlib.sha256).digest()
+    return "v1," + base64.b64encode(mac).decode()
+
+
+def verify_webhook(body: str, headers: Mapping[str, str], secret: str, now: Optional[float] = None) -> dict:
+    """The event, once its Standard Webhooks signature and timestamp are checked — or ``WebhookVerificationError``.
+    Pass the RAW body, as it arrived. Dedupe on ``event["id"]``: an event may come more than once."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    webhook_id, timestamp, signatures = lower.get("webhook-id"), lower.get("webhook-timestamp"), lower.get("webhook-signature")
+    if not webhook_id or not timestamp or not signatures:
+        raise WebhookVerificationError("missing_headers", "webhook-id, webhook-timestamp and webhook-signature are required")
+    if not re.fullmatch(r"\d{1,12}", timestamp):
+        raise WebhookVerificationError("malformed_timestamp", "webhook-timestamp is not a number of seconds")
+    if abs(int(now if now is not None else time.time()) - int(timestamp)) > WEBHOOK_TOLERANCE_SECONDS:
+        raise WebhookVerificationError("stale", "webhook-timestamp is more than 5 minutes from now: a replay, or a clock to set")
+    expected = sign_webhook(body, secret, webhook_id, int(timestamp))
+    if not any(hmac.compare_digest(given, expected) for given in signatures.split(" ")):
+        raise WebhookVerificationError("bad_signature", "no webhook-signature matches this secret: a forged event, or another endpoint's secret")
+    return json.loads(body)

vecsnap/_generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing VecSnap API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

vecsnap/_generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

vecsnap/_generated/api/account/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

vecsnap/_generated/api/account/get_credits.py

@@ -0,0 +1,180 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error import Error
+from ...models.get_credits_response_200 import GetCreditsResponse200
+from ...types import Response
+
+
+def _get_kwargs() -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/credits",
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Error | GetCreditsResponse200 | None:
+    if response.status_code == 200:
+        response_200 = GetCreditsResponse200.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 401:
+        response_401 = Error.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = Error.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 409:
+        response_409 = Error.from_dict(response.json())
+
+        return response_409
+
+    if response.status_code == 422:
+        response_422 = Error.from_dict(response.json())
+
+        return response_422
+
+    if response.status_code == 429:
+        response_429 = Error.from_dict(response.json())
+
+        return response_429
+
+    if response.status_code == 500:
+        response_500 = Error.from_dict(response.json())
+
+        return response_500
+
+    if response.status_code == 503:
+        response_503 = Error.from_dict(response.json())
+
+        return response_503
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Error | GetCreditsResponse200]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | GetCreditsResponse200]:
+    """Retrieve the credit balance
+
+     Derived from the ledger on every call: there is no balance column, since a cached total drifts under
+    partial failure and the customer is the one who finds out. `unlockCost` is what unlocking one image
+    costs, published so a client never hardcodes it; `tier` says which caps apply.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | GetCreditsResponse200]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+) -> Error | GetCreditsResponse200 | None:
+    """Retrieve the credit balance
+
+     Derived from the ledger on every call: there is no balance column, since a cached total drifts under
+    partial failure and the customer is the one who finds out. `unlockCost` is what unlocking one image
+    costs, published so a client never hardcodes it; `tier` says which caps apply.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | GetCreditsResponse200
+    """
+
+    return sync_detailed(
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | GetCreditsResponse200]:
+    """Retrieve the credit balance
+
+     Derived from the ledger on every call: there is no balance column, since a cached total drifts under
+    partial failure and the customer is the one who finds out. `unlockCost` is what unlocking one image
+    costs, published so a client never hardcodes it; `tier` says which caps apply.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | GetCreditsResponse200]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+) -> Error | GetCreditsResponse200 | None:
+    """Retrieve the credit balance
+
+     Derived from the ledger on every call: there is no balance column, since a cached total drifts under
+    partial failure and the customer is the one who finds out. `unlockCost` is what unlocking one image
+    costs, published so a client never hardcodes it; `tier` says which caps apply.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | GetCreditsResponse200
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+        )
+    ).parsed

vecsnap/_generated/api/account/get_limits.py

@@ -0,0 +1,180 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error import Error
+from ...models.get_limits_response_200 import GetLimitsResponse200
+from ...types import Response
+
+
+def _get_kwargs() -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/limits",
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Error | GetLimitsResponse200 | None:
+    if response.status_code == 200:
+        response_200 = GetLimitsResponse200.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 401:
+        response_401 = Error.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = Error.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 409:
+        response_409 = Error.from_dict(response.json())
+
+        return response_409
+
+    if response.status_code == 422:
+        response_422 = Error.from_dict(response.json())
+
+        return response_422
+
+    if response.status_code == 429:
+        response_429 = Error.from_dict(response.json())
+
+        return response_429
+
+    if response.status_code == 500:
+        response_500 = Error.from_dict(response.json())
+
+        return response_500
+
+    if response.status_code == 503:
+        response_503 = Error.from_dict(response.json())
+
+        return response_503
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Error | GetLimitsResponse200]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | GetLimitsResponse200]:
+    """Retrieve today's limits
+
+     The caps that apply to the caller (a guest, a free account or a customer) and how much of today is
+    used: the same count the create refuses by. `usedToday` counts free conversions (waiting ones
+    included) and refunded holds; a stopped one never ran and is not counted.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | GetLimitsResponse200]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient,
+) -> Error | GetLimitsResponse200 | None:
+    """Retrieve today's limits
+
+     The caps that apply to the caller (a guest, a free account or a customer) and how much of today is
+    used: the same count the create refuses by. `usedToday` counts free conversions (waiting ones
+    included) and refunded holds; a stopped one never ran and is not counted.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | GetLimitsResponse200
+    """
+
+    return sync_detailed(
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient,
+) -> Response[Error | GetLimitsResponse200]:
+    """Retrieve today's limits
+
+     The caps that apply to the caller (a guest, a free account or a customer) and how much of today is
+    used: the same count the create refuses by. `usedToday` counts free conversions (waiting ones
+    included) and refunded holds; a stopped one never ran and is not counted.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[Error | GetLimitsResponse200]
+    """
+
+    kwargs = _get_kwargs()
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient,
+) -> Error | GetLimitsResponse200 | None:
+    """Retrieve today's limits
+
+     The caps that apply to the caller (a guest, a free account or a customer) and how much of today is
+    used: the same count the create refuses by. `usedToday` counts free conversions (waiting ones
+    included) and refunded holds; a stopped one never ran and is not counted.
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Error | GetLimitsResponse200
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+        )
+    ).parsed

vecsnap/_generated/api/colors/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""