useyona-einvoice 0.1.0__py3-none-any.whl

useyona/einvoice/__init__.py

@@ -0,0 +1,97 @@
+"""Official Python SDK for the Yona e-invoicing API: what an API key may call.
+
+from useyona.einvoice import EInvoice
+
+client = EInvoice(api_key=os.environ["YONA_API_KEY"])
+invoice = client.invoices.create({...})
+"""
+
+from . import types
+from ._transport import (
+    API_KEY_PATTERN,
+    DEFAULT_BASE_URL,
+    IDEMPOTENCY_KEY_PATTERN,
+    HttpClient,
+    RawResponse,
+    RetryConfig,
+    generate_idempotency_key,
+    mode_of_api_key,
+    parse_retry_after,
+)
+from ._version import __version__
+from .client import EInvoice, paginate
+from .errors import (
+    ApiErrorDetail,
+    EInvoiceApiError,
+    EInvoiceAuthenticationError,
+    EInvoiceConfigError,
+    EInvoiceConflictError,
+    EInvoiceConnectionError,
+    EInvoiceError,
+    EInvoiceInsufficientCreditsError,
+    EInvoiceNotFoundError,
+    EInvoicePermissionError,
+    EInvoiceRateLimitError,
+    EInvoiceServerError,
+    EInvoiceTimeoutError,
+    EInvoiceValidationError,
+    EInvoiceWebhookError,
+)
+from .excluded_operations import EXCLUDED_OPERATIONS, ExcludedOperation
+from .types import ApiMode, BinaryResponse, Page, Paginated, PaginationMeta, RequestOptions, WebhookEvent
+from .webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    WEBHOOK_SIGNATURE_HEADER,
+    SignatureHeader,
+    compute_webhook_signature,
+    parse_signature_header,
+    sign_webhook_payload,
+    verify_webhook,
+)
+
+__all__ = [
+    "API_KEY_PATTERN",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "EXCLUDED_OPERATIONS",
+    "IDEMPOTENCY_KEY_PATTERN",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "ApiErrorDetail",
+    "ApiMode",
+    "BinaryResponse",
+    "EInvoice",
+    "EInvoiceApiError",
+    "EInvoiceAuthenticationError",
+    "EInvoiceConfigError",
+    "EInvoiceConflictError",
+    "EInvoiceConnectionError",
+    "EInvoiceError",
+    "EInvoiceInsufficientCreditsError",
+    "EInvoiceNotFoundError",
+    "EInvoicePermissionError",
+    "EInvoiceRateLimitError",
+    "EInvoiceServerError",
+    "EInvoiceTimeoutError",
+    "EInvoiceValidationError",
+    "EInvoiceWebhookError",
+    "ExcludedOperation",
+    "HttpClient",
+    "Page",
+    "Paginated",
+    "PaginationMeta",
+    "RawResponse",
+    "RequestOptions",
+    "RetryConfig",
+    "SignatureHeader",
+    "WebhookEvent",
+    "__version__",
+    "compute_webhook_signature",
+    "generate_idempotency_key",
+    "mode_of_api_key",
+    "paginate",
+    "parse_retry_after",
+    "parse_signature_header",
+    "sign_webhook_payload",
+    "types",
+    "verify_webhook",
+]

useyona/einvoice/_base.py

@@ -0,0 +1,82 @@
+"""Shared plumbing of every service: unwraps the ``{meta, data}`` envelope."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote
+
+from ._transport import HttpClient
+from .types import EMPTY_PAGINATION, BinaryResponse, Page, Paginated, RequestOptions
+
+
+def seg(value: str | int) -> str:
+    """Encodes one path segment."""
+    return quote(str(value), safe="")
+
+
+class BaseService:
+    """Shared plumbing of every service."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = False,
+        headers: Mapping[str, str] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        """One call; returns ``data``."""
+        return self._http.request(method, path, query=query, body=body, idempotent=idempotent, headers=headers, options=options).data
+
+    def _page(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Page[Any]:
+        """A list call; returns the items and ``meta.pagination``."""
+        res = self._http.request(method, path, query=query, options=options)
+        pagination = (res.meta or {}).get("pagination") or EMPTY_PAGINATION
+        return Page(data=list(res.data) if isinstance(res.data, list) else [], pagination=pagination, request_id=res.request_id)
+
+    def _paginated(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Paginated[Any]:
+        """A call whose ``data`` is an object and whose ``meta`` also carries pagination."""
+        res = self._http.request(method, path, query=query, options=options)
+        return Paginated(data=res.data, pagination=(res.meta or {}).get("pagination"), request_id=res.request_id)
+
+    def _binary(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        idempotent: bool = False,
+        options: RequestOptions | None = None,
+    ) -> BinaryResponse:
+        """A binary download."""
+        res = self._http.request(
+            method, path, query=query, idempotent=idempotent, binary=True, headers={"Accept": "application/pdf"}, options=options
+        )
+        data = res.data
+        if isinstance(data, BinaryResponse):
+            return data
+        # The route answered JSON (e.g. a mocked transport): hand it back as bytes so the caller sees what came.
+        import json
+
+        return BinaryResponse(data=json.dumps(data).encode("utf-8"), content_type="application/json", request_id=res.request_id)

useyona/einvoice/_transport.py

@@ -0,0 +1,399 @@
+"""The transport: authentication, the envelope, errors, idempotency keys, retries and timeouts.
+Services call :meth:`HttpClient.request`; integrators normally never touch it."""
+
+from __future__ import annotations
+
+import json
+import random
+import re
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import urlencode, urlsplit
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    ApiErrorDetail,
+    EInvoiceApiError,
+    EInvoiceConfigError,
+    EInvoiceConnectionError,
+    EInvoiceTimeoutError,
+    api_error_for,
+)
+from .types import ApiMode, ApiResponseMeta, BinaryResponse, RequestOptions
+
+# ═══════════════════════════════════════════
+# Constants
+# ═══════════════════════════════════════════
+
+#: The production gateway, for sandbox and live keys alike (the key's prefix picks the mode).
+#:
+#: THIS NAME IS PERMANENT. It is compiled into every installed copy of the SDK, so infrastructure
+#: moves by repointing DNS behind it, never by changing it here.
+DEFAULT_BASE_URL = "https://gp.useyona.com"
+
+#: A Yona API key: ``sk_test_`` (sandbox) or ``sk_live_`` (live), a 16-character public id
+#: (base32, lower case), then a 43-character secret (base64url).
+API_KEY_PATTERN = re.compile(r"^sk_(test|live)_([a-z2-7]{16})_([A-Za-z0-9_-]{43})$")
+
+#: What the API accepts in ``Idempotency-Key``.
+IDEMPOTENCY_KEY_PATTERN = re.compile(r"^[A-Za-z0-9_-]{8,128}$")
+
+RETRYABLE_STATUS = frozenset({408, 429, 500, 502, 503, 504})
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "PUT", "DELETE"})
+HttpMethod = str
+
+
+# ═══════════════════════════════════════════
+# Configuration
+# ═══════════════════════════════════════════
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry behaviour."""
+
+    #: Retries after the first attempt. Only requests that are safe to repeat are retried: GET, PUT
+    #: and DELETE, and writes that carry an ``Idempotency-Key``. Retried on a network error, a
+    #: timeout, 408, 429 and 5xx.
+    max_retries: int = 2
+    #: First backoff delay in seconds; doubles each retry, with jitter.
+    base_delay: float = 0.5
+    #: Ceiling of one backoff delay in seconds.
+    max_delay: float = 8.0
+    #: The longest ``Retry-After`` (seconds) the SDK will wait on 429/503 before retrying. A longer
+    #: one is raised at once, with ``retry_after`` set.
+    max_retry_after: int = 60
+
+
+@dataclass
+class RawResponse:
+    """A successful answer: ``data``, ``meta``, status and headers."""
+
+    status: int
+    data: Any
+    meta: ApiResponseMeta | None
+    request_id: str | None
+    headers: httpx.Headers
+
+
+# ═══════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════
+
+
+def mode_of_api_key(api_key: object) -> ApiMode:
+    """The mode a key belongs to, or raises :class:`EInvoiceConfigError` for a malformed key (never echoing it)."""
+    match = API_KEY_PATTERN.match(api_key.strip()) if isinstance(api_key, str) else None
+    if not match:
+        raise EInvoiceConfigError(
+            "The API key is malformed: expected sk_test_<16 characters>_<43 characters> (sandbox) or "
+            "sk_live_… (live). Copy it again from the dashboard (API keys)."
+        )
+    return "live" if match.group(1) == "live" else "sandbox"
+
+
+def generate_idempotency_key() -> str:
+    """A fresh idempotency key (a UUID)."""
+    return str(uuid.uuid4())
+
+
+def parse_retry_after(value: str | None, now: float | None = None) -> int | None:
+    """Seconds from a ``Retry-After`` header (delta-seconds or an HTTP date)."""
+    if not value:
+        return None
+    trimmed = value.strip()
+    if re.fullmatch(r"\d+", trimmed):
+        return int(trimmed)
+    try:
+        at = parsedate_to_datetime(trimmed).timestamp()
+    except (TypeError, ValueError, IndexError):
+        return None
+    current = time.time() if now is None else now
+    return max(0, int(-(-(at - current) // 1)))  # ceil
+
+
+def _unpack_errors(errors: object) -> list[ApiErrorDetail]:
+    """``{field: message}`` wire entries → ``ApiErrorDetail(field, message)``."""
+    out: list[ApiErrorDetail] = []
+    if not isinstance(errors, list):
+        return out
+    for entry in errors:
+        if isinstance(entry, dict):
+            for field, message in entry.items():
+                out.append(ApiErrorDetail(field=str(field), message=str(message)))
+    return out
+
+
+def _parse_json(text: str) -> Any:
+    return json.loads(text) if text else None
+
+
+class _AttemptTimeout(Exception):
+    pass
+
+
+_FILENAME = re.compile(r"filename\*?=(?:UTF-8'')?\"?([^\";]+)\"?", re.IGNORECASE)
+
+
+# ═══════════════════════════════════════════
+# HTTP client
+# ═══════════════════════════════════════════
+
+
+class HttpClient:
+    """The transport. Pass an ``httpx.Client`` (e.g. with ``httpx.MockTransport``) to control the network."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        assert_mode: ApiMode | None = None,
+        timeout: float = 30.0,
+        retry: RetryConfig | None = None,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        if not api_key:
+            raise EInvoiceConfigError('An API key is required: EInvoice(api_key="sk_test_…").')
+        #: The key's mode, from its prefix.
+        self.mode: ApiMode = mode_of_api_key(api_key)
+        if assert_mode is not None and assert_mode != self.mode:
+            prefix = "sk_live_" if self.mode == "live" else "sk_test_"
+            raise EInvoiceConfigError(f"This client was asserted to be {assert_mode}, but the API key is a {self.mode} key ({prefix}…).")
+        self._api_key = api_key.strip()
+        base = base_url if base_url is not None else DEFAULT_BASE_URL
+        parts = urlsplit(base)
+        if parts.scheme not in ("http", "https") or not parts.netloc:
+            raise EInvoiceConfigError(f"base_url is not a URL: {base}")
+        #: The host requests go to.
+        self.base_url = base.rstrip("/")
+        self.timeout = float(timeout)
+        self.retry = retry or RetryConfig()
+        self._default_headers = dict(headers or {})
+        self._user_agent = user_agent or f"useyona-einvoice-python/{__version__}"
+        self._owns_client = http_client is None
+        # The SDK's own deadline covers the whole attempt (see _attempt_once); httpx's per-operation
+        # timeouts are set per request so a stalled read also ends within the deadline.
+        self._http = http_client if http_client is not None else httpx.Client(timeout=self.timeout)
+
+    # ── lifecycle ──
+
+    def close(self) -> None:
+        """Closes the underlying connection pool (only one the SDK created)."""
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ── requests ──
+
+    def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+        idempotent: bool = False,
+        binary: bool = False,
+        headers: Mapping[str, str] | None = None,
+        options: RequestOptions | None = None,
+    ) -> RawResponse:
+        """Sends one API call and returns the parsed success, or raises an :class:`EInvoiceApiError` subclass.
+
+        ``idempotent`` marks a route that honours ``Idempotency-Key``: the SDK sends one (generated
+        unless ``options.idempotency_key`` is given). ``binary`` expects a PDF instead of the JSON envelope.
+        """
+        ro = options or RequestOptions()
+        url = self._build_url(path, query)
+        timeout = ro.timeout if ro.timeout is not None else self.timeout
+        req_headers = self._build_headers(body is not None, idempotent, headers, ro)
+        keyed = "Idempotency-Key" in req_headers
+        retryable = method in IDEMPOTENT_METHODS or keyed
+        max_retries = (ro.max_retries if ro.max_retries is not None else self.retry.max_retries) if retryable else 0
+        content = None if body is None else json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+        attempt = 0
+        while True:
+            try:
+                outcome = self._attempt_once(url, method, req_headers, content, timeout, binary)
+            except EInvoiceApiError:
+                raise
+            except _AttemptTimeout:
+                if attempt < max_retries:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise EInvoiceTimeoutError(timeout) from None
+            except httpx.HTTPError as error:
+                if attempt < max_retries:
+                    self._sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise EInvoiceConnectionError(f"Could not reach {self.base_url}: {error}", error) from error
+
+            if isinstance(outcome, RawResponse):
+                return outcome
+
+            refusal = outcome
+            if attempt < max_retries and refusal.status in RETRYABLE_STATUS:
+                wait = refusal.retry_after
+                if wait is not None and refusal.status in (429, 503):
+                    if wait > self.retry.max_retry_after:
+                        raise refusal
+                    self._sleep(float(wait))
+                else:
+                    self._sleep(self._backoff(attempt))
+                attempt += 1
+                continue
+            raise refusal
+
+    def _build_headers(self, has_body: bool, idempotent: bool, extra: Mapping[str, str] | None, ro: RequestOptions) -> dict[str, str]:
+        merged: dict[str, str] = {"Accept": "application/json"}
+        for source in (self._default_headers, extra or {}, ro.headers or {}):
+            for name, value in source.items():
+                # Later sources win; names compare case-insensitively.
+                for existing in [k for k in merged if k.lower() == name.lower()]:
+                    del merged[existing]
+                merged[name] = value
+        for name in [k for k in merged if k.lower() in ("authorization", "x-api-key", "idempotency-key")]:
+            del merged[name]
+        merged["Authorization"] = f"Bearer {self._api_key}"
+        if self._user_agent and not any(k.lower() == "user-agent" for k in merged):
+            merged["User-Agent"] = self._user_agent
+        if has_body:
+            merged["Content-Type"] = "application/json"
+        if idempotent:
+            key = ro.idempotency_key if ro.idempotency_key is not None else generate_idempotency_key()
+            if not IDEMPOTENCY_KEY_PATTERN.match(key):
+                raise EInvoiceConfigError("idempotency_key must be 8–128 characters of A–Z, a–z, 0–9, _ or -.")
+            merged["Idempotency-Key"] = key
+        return merged
+
+    def _attempt_once(
+        self, url: str, method: str, headers: dict[str, str], content: bytes | None, timeout: float, binary: bool
+    ) -> RawResponse | EInvoiceApiError:
+        """One attempt: the request AND reading its body, all under one deadline, so a body that stalls
+        after the headers arrived times out like a request that never answered."""
+        deadline = time.monotonic() + timeout
+        request = self._http.build_request(method, url, headers=headers, content=content, timeout=httpx.Timeout(timeout))
+        try:
+            response = self._http.send(request, stream=True)
+        except httpx.TimeoutException as error:
+            raise _AttemptTimeout() from error
+        try:
+            try:
+                chunks: list[bytes] = []
+                for chunk in response.iter_bytes():
+                    chunks.append(chunk)
+                    if time.monotonic() > deadline:
+                        raise _AttemptTimeout()
+                payload = b"".join(chunks)
+            except httpx.TimeoutException as error:
+                raise _AttemptTimeout() from error
+        finally:
+            response.close()
+        if response.is_success:
+            return self._parse_success(response, payload, binary)
+        return self._parse_error(response, payload)
+
+    def _parse_success(self, response: httpx.Response, payload: bytes, binary: bool) -> RawResponse:
+        header_request_id = response.headers.get("x-request-id")
+        content_type = response.headers.get("content-type", "")
+        if binary and "json" not in content_type:
+            disposition = response.headers.get("content-disposition", "")
+            match = _FILENAME.search(disposition)
+            name = match.group(1) if match else None
+            if name is not None:
+                from urllib.parse import unquote
+
+                name = unquote(name)
+            file = BinaryResponse(data=payload, content_type=content_type or "application/octet-stream", file_name=name, request_id=header_request_id)
+            return RawResponse(status=response.status_code, data=file, meta=None, request_id=header_request_id, headers=response.headers)
+        if response.status_code == 204:
+            return RawResponse(status=204, data=None, meta=None, request_id=header_request_id, headers=response.headers)
+        text = payload.decode("utf-8", errors="replace")
+        try:
+            parsed = _parse_json(text)
+        except ValueError:
+            raise EInvoiceApiError(
+                status=response.status_code,
+                message=f"The API answered {response.status_code} with a body that is not JSON",
+                request_id=header_request_id,
+                body=text,
+            ) from None
+        if isinstance(parsed, dict) and "meta" in parsed and "data" in parsed:
+            meta = parsed.get("meta")
+            meta_dict: ApiResponseMeta | None = meta if isinstance(meta, dict) else None  # type: ignore[assignment]
+            request_id = (meta_dict or {}).get("requestId") or header_request_id
+            return RawResponse(status=response.status_code, data=parsed["data"], meta=meta_dict, request_id=request_id, headers=response.headers)
+        return RawResponse(status=response.status_code, data=parsed, meta=None, request_id=header_request_id, headers=response.headers)
+
+    def _parse_error(self, response: httpx.Response, payload: bytes) -> EInvoiceApiError:
+        retry_after = parse_retry_after(response.headers.get("retry-after"))
+        header_request_id = response.headers.get("x-request-id")
+        text = payload.decode("utf-8", errors="replace")
+        try:
+            parsed = _parse_json(text)
+        except ValueError:
+            parsed = None
+        meta = parsed.get("meta") if isinstance(parsed, dict) else None
+        meta = meta if isinstance(meta, dict) else {}
+        message = meta.get("message")
+        error_code = meta.get("errorCode")
+        request_id = meta.get("requestId")
+        return api_error_for(
+            status=response.status_code,
+            message=message if isinstance(message, str) and message else f"HTTP {response.status_code}",
+            error_code=error_code if isinstance(error_code, str) else None,
+            errors=_unpack_errors(meta.get("errors")),
+            request_id=request_id if isinstance(request_id, str) else header_request_id,
+            retry_after=retry_after,
+            body=parsed,
+        )
+
+    def _build_url(self, path: str, query: Mapping[str, Any] | None) -> str:
+        url = f"{self.base_url}{path}"
+        if not query:
+            return url
+        pairs: list[tuple[str, str]] = []
+        for key, value in query.items():
+            if value is None or value == "":
+                continue
+            values = value if isinstance(value, list | tuple) else [value]
+            for v in values:
+                pairs.append((key, "true" if v is True else "false" if v is False else str(v)))
+        return f"{url}?{urlencode(pairs)}" if pairs else url
+
+    def _backoff(self, attempt: int) -> float:
+        base = min(self.retry.max_delay, self.retry.base_delay * (2.0**attempt))
+        return base / 2 + random.random() * (base / 2)
+
+    def _sleep(self, seconds: float) -> None:
+        """Waits ``seconds``. Overridable in tests."""
+        time.sleep(seconds)
+
+
+__all__ = [
+    "API_KEY_PATTERN",
+    "DEFAULT_BASE_URL",
+    "IDEMPOTENCY_KEY_PATTERN",
+    "HttpClient",
+    "RawResponse",
+    "RetryConfig",
+    "generate_idempotency_key",
+    "mode_of_api_key",
+    "parse_retry_after",
+]

useyona/einvoice/_version.py

@@ -0,0 +1,3 @@
+"""The package version, read by the client's User-Agent and the guides export."""
+
+__version__ = "0.1.0"