autosignly 0.1.0__py3-none-any.whl

autosignly/__init__.py

@@ -0,0 +1,76 @@
+"""Python client for the Autosignly API.
+
+    from autosignly import AutosignlyClient, Signer
+
+    with AutosignlyClient(api_key="api_key_...", api_secret="api_sct_...") as client:
+        result = client.upload_and_sign(
+            pdf=open("contract.pdf", "rb").read(),
+            document_name="Contract",
+            signers=[Signer(first_name="Anna", last_name="Nowak",
+                            email="anna@example.com", country="PL")],
+        )
+        print(result.document_id)
+"""
+
+from ._version import __version__
+from .client import AutosignlyClient, PRODUCTION_BASE_URL
+from .errors import (
+    AutosignlyError,
+    AuthenticationError,
+    ConnectionError,
+    InvalidSignatureError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    Credentials,
+    Document,
+    DocumentStatus,
+    EnvironmentType,
+    DocumentSummary,
+    Page,
+    SignatureMode,
+    SignatureType,
+    Signer,
+    SignerDetails,
+    SignerStatus,
+    SigningMode,
+    SigningRequestResult,
+    SigningStatus,
+    Tag,
+    VerificationMethod,
+)
+
+__all__ = [
+    "AutosignlyClient",
+    "PRODUCTION_BASE_URL",
+    "AutosignlyError",
+    "AuthenticationError",
+    "ConnectionError",
+    "InvalidSignatureError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "Credentials",
+    "Document",
+    "DocumentStatus",
+    "EnvironmentType",
+    "DocumentSummary",
+    "Page",
+    "SignatureMode",
+    "SignatureType",
+    "Signer",
+    "SignerDetails",
+    "SignerStatus",
+    "SigningMode",
+    "SigningRequestResult",
+    "SigningStatus",
+    "Tag",
+    "VerificationMethod",
+    "webhooks",
+]

autosignly/_version.py

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

autosignly/client.py

@@ -0,0 +1,417 @@
+"""HTTP client for the Autosignly public API."""
+
+from __future__ import annotations
+
+import json
+import random
+import time
+import uuid
+from typing import Any, Iterator, Mapping, Sequence
+
+import httpx
+
+from . import errors
+from ._version import __version__
+from .models import (
+    Credentials,
+    Document,
+    DocumentSummary,
+    Page,
+    Signer,
+    SigningRequestResult,
+    Tag,
+)
+
+PRODUCTION_BASE_URL = "https://app.autosignly.eu/api"
+API_PREFIX = "/publics/v1"
+
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+_MAX_RETRY_DELAY = 60.0
+_IDEMPOTENT_METHODS = frozenset({"GET", "DELETE"})
+
+
+class AutosignlyClient:
+    """Client for the Autosignly API.
+
+    Credentials are a key and secret pair created in the Autosignly application.
+    Each environment, production or sandbox, has its own pair, and the pair
+    decides which environment a call operates on.
+
+    The secret must never reach a browser or a mobile app. This client is meant
+    to run on your own server.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        *,
+        base_url: str = PRODUCTION_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key or not api_secret:
+            raise ValueError("api_key and api_secret are required")
+
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max(0, max_retries)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._headers = {
+            "X-API-KEY": api_key,
+            "X-API-SECRET": api_secret,
+            "Accept": "application/json",
+            "User-Agent": f"autosignly-python/{__version__}",
+        }
+
+    def __enter__(self) -> "AutosignlyClient":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        if self._owns_client:
+            self._http.close()
+
+    # -- credentials ---------------------------------------------------------
+
+    def validate_credentials(self) -> bool:
+        """Report whether this key and secret pair is accepted.
+
+        Invalid credentials return ``False`` rather than raising, mirroring the
+        API, which never answers this call with an authentication error so that
+        keys cannot be probed.
+        """
+        payload = self._request("GET", "/api-key")
+        return bool(payload.get("valid", False))
+
+    def describe_credentials(self) -> Credentials:
+        """Report which company and environment this key and secret resolve to.
+
+        Useful before a first call: it says whether the pair points at
+        production or at a sandbox, without touching any document.
+        """
+        payload = self._request("GET", "/credentials")
+        return Credentials.from_payload(payload)
+
+    # -- documents -----------------------------------------------------------
+
+    def list_documents(
+        self,
+        *,
+        status: str | Sequence[str] | None = None,
+        page: int = 0,
+        size: int = 20,
+        sort: str | None = None,
+    ) -> Page[DocumentSummary]:
+        """Return one page of documents belonging to this environment."""
+        params: list[tuple[str, Any]] = [("page", page), ("size", size)]
+        if sort:
+            params.append(("sort", sort))
+        if status:
+            values = [status] if isinstance(status, str) else list(status)
+            params.extend(("status", value) for value in values)
+
+        payload = self._request("GET", "/documents", params=params)
+        return _to_page(payload, DocumentSummary.from_payload)
+
+    def iter_documents(
+        self,
+        *,
+        status: str | Sequence[str] | None = None,
+        size: int = 50,
+        sort: str | None = None,
+    ) -> Iterator[DocumentSummary]:
+        """Walk every document, fetching further pages as needed."""
+        page_number = 0
+        while True:
+            page = self.list_documents(status=status, page=page_number, size=size, sort=sort)
+            yield from page.content
+            if not page.has_next:
+                return
+            page_number += 1
+
+    def get_document(self, document_id: str) -> Document:
+        """Return one document with its signers."""
+        payload = self._request("GET", f"/documents/{document_id}")
+        return Document.from_payload(payload)
+
+    def download_document(self, document_id: str) -> bytes:
+        """Fetch the current file of a document.
+
+        Resolves a fresh link through :meth:`get_document` and downloads it. A
+        document that is still being signed can be downloaded too; it then
+        carries only the signatures collected so far.
+        """
+        document = self.get_document(document_id)
+        if not document.file_url:
+            raise errors.NotFoundError(
+                f"Document {document_id} has no file to download",
+                status_code=404,
+            )
+
+        try:
+            response = self._http.get(document.file_url)
+        except httpx.TransportError as exc:
+            raise errors.ConnectionError(f"Could not download {document_id}: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise _to_error(response)
+        return response.content
+
+    def send_for_signing(
+        self,
+        document_id: str,
+        *,
+        signers: Sequence[Signer] | None = None,
+        signature_type: str | None = None,
+        signature_mode: str | None = None,
+        verification_method: str | None = None,
+        initiator_email: str | None = None,
+        initiator_locale: str | None = None,
+    ) -> SigningRequestResult:
+        """Send an existing document to its signers.
+
+        A document in ``GENERATED`` status needs ``signers``; one already in
+        ``SIGNERS_ASSIGNED`` must be sent without them, since its signers are
+        already stored.
+        """
+        body: dict[str, Any] = {}
+        if signers:
+            body["signers"] = [signer.to_payload() for signer in signers]
+        if signature_type:
+            body["signatureType"] = signature_type
+        if signature_mode:
+            body["signatureMode"] = signature_mode
+        if verification_method:
+            body["verificationMethod"] = verification_method
+        if initiator_email:
+            body["signingInitiatorData"] = {
+                "email": initiator_email,
+                "locale": initiator_locale,
+            }
+
+        payload = self._request("POST", f"/documents/{document_id}/send-for-signing", json_body=body)
+        return SigningRequestResult.from_payload(payload)
+
+    def upload_and_sign(
+        self,
+        *,
+        pdf: bytes,
+        document_name: str,
+        signers: Sequence[Signer],
+        signature_type: str | None = None,
+        signature_mode: str | None = None,
+        verification_method: str | None = None,
+        initiator_email: str | None = None,
+        initiator_locale: str | None = None,
+        file_name: str = "document.pdf",
+    ) -> str:
+        """Upload a PDF and send it for signature in one call.
+
+        Returns the identifier of the created document. Signing links are
+        e-mailed to the signers directly.
+        """
+        request: dict[str, Any] = {
+            "documentName": document_name,
+            "signers": [signer.to_payload() for signer in signers],
+        }
+        if signature_type:
+            request["signatureType"] = signature_type
+        if signature_mode:
+            request["signatureMode"] = signature_mode
+        if verification_method:
+            request["verificationMethod"] = verification_method
+        if initiator_email:
+            request["signingInitiatorData"] = {
+                "email": initiator_email,
+                "locale": initiator_locale,
+            }
+
+        files = {
+            "file": (file_name, pdf, "application/pdf"),
+            "request": (None, json.dumps(request), "application/json"),
+        }
+        payload = self._request("POST", "/documents/signings", files=files)
+        return payload.get("documentId", "")
+
+    # -- tags ----------------------------------------------------------------
+
+    def list_tags(self, *, name: str | None = None, page: int = 0, size: int = 20) -> Page[Tag]:
+        """Return one page of the company tag pool for this environment."""
+        params: list[tuple[str, Any]] = [("page", page), ("size", size)]
+        if name:
+            params.append(("name", name))
+        payload = self._request("GET", "/tags", params=params)
+        return _to_page(payload, Tag.from_payload)
+
+    def create_tag(self, name: str) -> Tag:
+        """Add a tag, or return the existing one with the same name.
+
+        Names are matched without regard to case, so repeating this call is safe.
+        """
+        payload = self._request("POST", "/tags", json_body={"name": name})
+        return Tag.from_payload(payload)
+
+    def delete_tag(self, tag_id: str) -> None:
+        """Remove a tag from the pool and from every document carrying it."""
+        self._request("DELETE", f"/tags/{tag_id}")
+
+    def set_document_tags(
+        self,
+        document_id: str,
+        *,
+        tag_ids: Sequence[str] | None = None,
+        names: Sequence[str] | None = None,
+    ) -> list[Tag]:
+        """Replace the whole tag set of a document.
+
+        Tags left out are removed. Names that are not in the pool yet are added
+        to it. Passing neither argument clears every tag.
+        """
+        body: dict[str, Any] = {}
+        if tag_ids is not None:
+            body["tagIds"] = list(tag_ids)
+        if names is not None:
+            body["names"] = list(names)
+        payload = self._request("PUT", f"/documents/{document_id}/tags", json_body=body)
+        return [Tag.from_payload(item) for item in payload or []]
+
+    # -- transport -----------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Sequence[tuple[str, Any]] | None = None,
+        json_body: Mapping[str, Any] | None = None,
+        files: Mapping[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self._base_url}{API_PREFIX}{path}"
+        headers = dict(self._headers)
+        if method not in _IDEMPOTENT_METHODS:
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json_body,
+                    files=files,
+                    headers=headers,
+                )
+            except httpx.TransportError as exc:
+                last_error = exc
+                if attempt >= self._max_retries:
+                    raise errors.ConnectionError(f"Could not reach {url}: {exc}") from exc
+                time.sleep(_backoff(attempt))
+                continue
+
+            if response.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                delay = _retry_delay(response, attempt)
+                if delay is not None:
+                    time.sleep(delay)
+                    continue
+
+            if response.status_code >= 400:
+                raise _to_error(response)
+
+            return _decode(response)
+
+        raise errors.ConnectionError(f"Could not reach {url}: {last_error}")
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff with jitter.
+
+    The jitter matters: without it every client retrying a shared outage wakes
+    up at the same moment and pushes the service back over.
+    """
+    ceiling = min(_MAX_RETRY_DELAY, 0.5 * (2**attempt))
+    return random.uniform(ceiling / 2, ceiling)
+
+
+def _retry_delay(response: httpx.Response, attempt: int) -> float | None:
+    """How long to wait before retrying, or ``None`` to give up now.
+
+    A rate-limited response carries the delay the API wants; anything longer
+    than the cap is reported to the caller instead of blocking the thread.
+    """
+    if response.status_code != 429:
+        return _backoff(attempt)
+
+    retry_after = _retry_after_seconds(response)
+    if retry_after is None:
+        return _backoff(attempt)
+    if retry_after > _MAX_RETRY_DELAY:
+        return None
+    return retry_after
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    raw = response.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw.strip()))
+    except ValueError:
+        return None
+
+
+def _decode(response: httpx.Response) -> Any:
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise errors.AutosignlyError(
+            f"Expected JSON from {response.request.url}, got {response.headers.get('content-type')}",
+            status_code=response.status_code,
+        ) from exc
+
+
+def _to_error(response: httpx.Response) -> errors.AutosignlyError:
+    error_type = error_id = info = None
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            error_type = body.get("errorType")
+            error_id = body.get("errorId")
+            info = body.get("info")
+    except ValueError:
+        info = response.text[:200] or None
+
+    status = response.status_code
+    message = info or f"Request failed with status {status}"
+    kwargs = {"status_code": status, "error_type": error_type, "error_id": error_id}
+
+    if status == 401:
+        return errors.AuthenticationError(message, **kwargs)
+    if status == 403:
+        return errors.PermissionDeniedError(message, **kwargs)
+    if status == 404:
+        return errors.NotFoundError(message, **kwargs)
+    if status == 429:
+        return errors.RateLimitError(message, retry_after=_retry_after_seconds(response), **kwargs)
+    if status >= 500:
+        return errors.ServerError(message, **kwargs)
+    return errors.ValidationError(message, **kwargs)
+
+
+def _to_page(payload: Any, factory: Any) -> Page[Any]:
+    content = [factory(item) for item in (payload or {}).get("content") or []]
+    info = (payload or {}).get("page") or {}
+    return Page(
+        content=content,
+        number=info.get("number", 0),
+        size=info.get("size", len(content)),
+        total_elements=info.get("totalElements", len(content)),
+        total_pages=info.get("totalPages", 1 if content else 0),
+    )

autosignly/errors.py

@@ -0,0 +1,69 @@
+"""Exceptions raised by the Autosignly client."""
+
+from __future__ import annotations
+
+
+class AutosignlyError(Exception):
+    """Base class for every error raised by this library."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_type: str | None = None,
+        error_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        self.error_id = error_id
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.error_type:
+            parts.append(f"type={self.error_type}")
+        if self.error_id:
+            parts.append(f"errorId={self.error_id}")
+        return " ".join(parts)
+
+
+class AuthenticationError(AutosignlyError):
+    """The API key or secret was rejected."""
+
+
+class PermissionDeniedError(AutosignlyError):
+    """The credentials are valid but do not grant access to this resource."""
+
+
+class NotFoundError(AutosignlyError):
+    """The requested resource does not exist."""
+
+
+class ValidationError(AutosignlyError):
+    """The request was rejected as invalid."""
+
+
+class RateLimitError(AutosignlyError):
+    """Too many requests were sent in a short period.
+
+    ``retry_after`` carries the delay the API asked for, in seconds, when it
+    provided one.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(AutosignlyError):
+    """The API failed to process the request."""
+
+
+class ConnectionError(AutosignlyError):
+    """The API could not be reached."""
+
+
+class InvalidSignatureError(AutosignlyError):
+    """A webhook signature did not match the payload."""

autosignly/models.py

@@ -0,0 +1,281 @@
+"""Data types returned by and passed to the Autosignly API.
+
+Status and type values are plain strings rather than enums on purpose: the API
+may gain new values over time, and a client that raises on an unknown value
+would break on a server-side addition. The classes below list the values known
+at the time of release, for convenience and autocompletion.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Generic, Iterator, TypeVar
+
+T = TypeVar("T")
+
+
+class SignatureType:
+    """Level of the electronic signature requested for a document or signer."""
+
+    QES = "QES"
+    AES = "AES"
+    SES = "SES"
+
+
+class VerificationMethod:
+    """How an advanced signature verifies the signer's identity."""
+
+    SMS = "SMS"
+    WK = "WK"
+    BIOMETRIC = "BIOMETRIC"
+
+
+class SignatureMode:
+    """Where signatures are placed on the document."""
+
+    #: The signer places a visual stamp on the document.
+    STAMP = "STAMP"
+    #: Signatures are collected on a card appended to the document.
+    SIGNATURES_CARD = "SIGNATURES_CARD"
+
+
+class EnvironmentType:
+    """Which environment a key and secret pair belongs to."""
+
+    PROD = "PROD"
+    SANDBOX = "SANDBOX"
+
+
+class SigningMode:
+    """Whether a document still needs signatures."""
+
+    REQUIRES_SIGNATURE = "REQUIRES_SIGNATURE"
+    ALREADY_SIGNED = "ALREADY_SIGNED"
+
+
+class DocumentStatus:
+    """Lifecycle of a document."""
+
+    GENERATED = "GENERATED"
+    SIGNERS_ASSIGNED = "SIGNERS_ASSIGNED"
+    WAITING_FOR_SIGNATURE = "WAITING_FOR_SIGNATURE"
+    SIGNING_IN_PROGRESS = "SIGNING_IN_PROGRESS"
+    SIGNED = "SIGNED"
+    CANCELLED = "CANCELLED"
+
+
+class SigningStatus:
+    """State of an individual signer within a signing request."""
+
+    SENT = "SENT"
+    AWAITING_SIGNATURE = "AWAITING_SIGNATURE"
+
+
+@dataclass(slots=True)
+class Credentials:
+    """Which company and environment a key and secret pair resolves to.
+
+    Every environment — production and each sandbox — has its own pair, so this
+    is how a caller confirms which data a key will touch before using it.
+    """
+
+    valid: bool
+    company_id: str | None = None
+    environment_id: str | None = None
+    environment_type: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "Credentials":
+        return cls(
+            valid=bool(payload.get("valid", False)),
+            company_id=payload.get("companyId"),
+            environment_id=payload.get("environmentId"),
+            environment_type=payload.get("environmentType"),
+        )
+
+
+@dataclass(slots=True)
+class Signer:
+    """A person asked to sign a document."""
+
+    first_name: str
+    last_name: str
+    email: str
+    country: str
+    phone_number: str | None = None
+    locale: str | None = None
+    order: int | None = None
+    signature_type: str | None = None
+    signature_verification_method: str | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        payload = {
+            "firstName": self.first_name,
+            "lastName": self.last_name,
+            "email": self.email,
+            "country": self.country,
+            "phoneNumber": self.phone_number,
+            "locale": self.locale,
+            "order": self.order,
+            "signatureType": self.signature_type,
+            "signatureVerificationMethod": self.signature_verification_method,
+        }
+        return {key: value for key, value in payload.items() if value is not None}
+
+
+@dataclass(slots=True)
+class Tag:
+    """A company tag, used to group documents and templates."""
+
+    id: str
+    name: str
+    color: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "Tag":
+        return cls(id=payload["id"], name=payload["name"], color=payload.get("color"))
+
+
+@dataclass(slots=True)
+class SignerStatus:
+    """Where a signer stands, and the link they were given."""
+
+    email: str
+    status: str | None = None
+    sign_url: str | None = None
+    expires_at: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "SignerStatus":
+        return cls(
+            email=payload.get("email", ""),
+            status=payload.get("status"),
+            sign_url=payload.get("signUrl"),
+            expires_at=payload.get("expiresAt"),
+        )
+
+
+@dataclass(slots=True)
+class SignerDetails:
+    """A signer as stored on a document."""
+
+    email: str
+    first_name: str | None = None
+    last_name: str | None = None
+    phone_number: str | None = None
+    country: str | None = None
+    locale: str | None = None
+    signature_type: str | None = None
+    signature_verification_method: str | None = None
+    signing_order: int | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "SignerDetails":
+        return cls(
+            email=payload.get("email", ""),
+            first_name=payload.get("firstName"),
+            last_name=payload.get("lastName"),
+            phone_number=payload.get("phoneNumber"),
+            country=payload.get("country"),
+            locale=payload.get("locale"),
+            signature_type=payload.get("signatureType"),
+            signature_verification_method=payload.get("signatureVerificationMethod"),
+            signing_order=payload.get("signingOrder"),
+        )
+
+
+@dataclass(slots=True)
+class Document:
+    """Full details of a document, including its signers and a link to its file.
+
+    ``file_url`` is short-lived. Fetch the document again to obtain a fresh link
+    rather than storing it. A document that is still being signed can be
+    downloaded as well; it then carries only the signatures collected so far.
+    """
+
+    id: str
+    name: str | None = None
+    company_id: str | None = None
+    status: str | None = None
+    signing_mode: str | None = None
+    signers: list[SignerDetails] = field(default_factory=list)
+    tags: list[Tag] = field(default_factory=list)
+    file_url: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "Document":
+        return cls(
+            id=payload["id"],
+            name=payload.get("name"),
+            company_id=payload.get("companyId"),
+            status=payload.get("status"),
+            signing_mode=payload.get("signingMode"),
+            signers=[SignerDetails.from_payload(s) for s in payload.get("signerResponses") or []],
+            tags=[Tag.from_payload(t) for t in payload.get("tags") or []],
+            file_url=payload.get("fileUrl"),
+        )
+
+
+@dataclass(slots=True)
+class DocumentSummary:
+    """A document as it appears in a list."""
+
+    id: str
+    name: str | None = None
+    status: str | None = None
+    signing_mode: str | None = None
+    created_at: str | None = None
+    tags: list[Tag] = field(default_factory=list)
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "DocumentSummary":
+        return cls(
+            id=payload["id"],
+            name=payload.get("name"),
+            status=payload.get("status"),
+            signing_mode=payload.get("signingMode"),
+            created_at=payload.get("createdAt"),
+            tags=[Tag.from_payload(t) for t in payload.get("tags") or []],
+        )
+
+
+@dataclass(slots=True)
+class SigningRequestResult:
+    """Outcome of sending a document for signature.
+
+    Only the first signer receives a link immediately; the others are e-mailed
+    their link when their turn comes.
+    """
+
+    document_id: str
+    status: str | None = None
+    signers: list[SignerStatus] = field(default_factory=list)
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "SigningRequestResult":
+        return cls(
+            document_id=payload.get("documentId", ""),
+            status=payload.get("status"),
+            signers=[SignerStatus.from_payload(s) for s in payload.get("signers") or []],
+        )
+
+
+@dataclass(slots=True)
+class Page(Generic[T]):
+    """One page of a paged listing."""
+
+    content: list[T]
+    number: int = 0
+    size: int = 0
+    total_elements: int = 0
+    total_pages: int = 0
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.content)
+
+    def __len__(self) -> int:
+        return len(self.content)
+
+    @property
+    def has_next(self) -> bool:
+        return self.number + 1 < self.total_pages

autosignly/webhooks.py

@@ -0,0 +1,79 @@
+"""Verification of webhook deliveries.
+
+Every delivery carries two headers: ``X-Webhook-Timestamp`` with the moment it
+was signed, and ``X-Webhook-Signature`` with one or more signatures over
+``timestamp + "." + body``. Several signatures appear while a webhook key is
+being rotated; a delivery is genuine when any of them matches.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+from .errors import InvalidSignatureError
+
+SIGNATURE_HEADER = "X-Webhook-Signature"
+TIMESTAMP_HEADER = "X-Webhook-Timestamp"
+
+SIGNATURE_VERSION = "v1"
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def compute_signature(payload: bytes, secret: str, timestamp: str) -> str:
+    """Return the hex digest Autosignly sends for this payload and timestamp."""
+    signed_content = timestamp.encode("utf-8") + b"." + payload
+    return hmac.new(secret.encode("utf-8"), signed_content, hashlib.sha256).hexdigest()
+
+
+def is_valid(
+    payload: bytes,
+    signature_header: str,
+    secret: str,
+    timestamp: str,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+) -> bool:
+    """Check a delivery without raising.
+
+    ``payload`` must be the raw request body exactly as received. Parsing and
+    re-serialising the JSON changes the bytes and invalidates the signature.
+
+    A delivery older than ``tolerance`` seconds is rejected even when its
+    signature matches, so a captured request cannot be replayed later. Pass
+    ``tolerance=0`` to skip that check.
+    """
+    if not signature_header or not secret or not timestamp:
+        return False
+
+    if tolerance and not _is_fresh(timestamp, tolerance):
+        return False
+
+    expected = compute_signature(payload, secret, timestamp)
+    for candidate in signature_header.split(","):
+        version, _, digest = candidate.strip().partition("=")
+        if version == SIGNATURE_VERSION and digest and hmac.compare_digest(digest, expected):
+            return True
+    return False
+
+
+def verify(
+    payload: bytes,
+    signature_header: str,
+    secret: str,
+    timestamp: str,
+    *,
+    tolerance: int = DEFAULT_TOLERANCE_SECONDS,
+) -> None:
+    """Check a delivery and raise :class:`InvalidSignatureError` if it fails."""
+    if not is_valid(payload, signature_header, secret, timestamp, tolerance=tolerance):
+        raise InvalidSignatureError("Webhook signature does not match the payload")
+
+
+def _is_fresh(timestamp: str, tolerance: int) -> bool:
+    try:
+        sent_at = int(timestamp.strip())
+    except ValueError:
+        return False
+    return abs(time.time() - sent_at) <= tolerance

autosignly-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: autosignly
+Version: 0.1.0
+Summary: Python client for the Autosignly API - eIDAS electronic signatures and document workflows
+Project-URL: Homepage, https://autosignly.eu
+Project-URL: Documentation, https://docs.16it.eu/docs/intro/
+Project-URL: Source, https://github.com/16it-pl/autosignly-sdk
+Project-URL: Issues, https://github.com/16it-pl/autosignly-sdk/issues
+Author: 16it
+License-Expression: Apache-2.0
+Keywords: autosignly,eidas,electronic-signature,esignature,pades,pdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# autosignly
+
+Python client for the [Autosignly](https://autosignly.eu) API - eIDAS electronic signatures and
+document workflows.
+
+> **Not published yet.** This package is being built. Install from source for now.
+
+## Install
+
+```bash
+pip install autosignly
+```
+
+Requires Python 3.10 or newer.
+
+## Quickstart
+
+```python
+from autosignly import AutosignlyClient, Signer
+
+with AutosignlyClient(api_key="api_key_...", api_secret="api_sct_...") as client:
+    document_id = client.upload_and_sign(
+        pdf=open("contract.pdf", "rb").read(),
+        document_name="Consulting agreement",
+        signers=[
+            Signer(
+                first_name="Anna",
+                last_name="Nowak",
+                email="anna@example.com",
+                country="PL",
+            )
+        ],
+    )
+    print(document_id)
+```
+
+The key and secret decide which environment you are working in. Every environment, production or
+sandbox, has its own pair, so pointing a script at the sandbox is a matter of swapping credentials.
+
+The secret must stay on your server. It must never be shipped to a browser or a mobile app.
+
+## Reading documents
+
+```python
+document = client.get_document(document_id)
+print(document.status, [s.email for s in document.signers])
+
+for summary in client.iter_documents(status="SIGNED"):
+    print(summary.id, summary.name)
+```
+
+## Downloading the file
+
+A document carries a short-lived link to its file. The link expires, so fetch the document again
+for a fresh one rather than storing it.
+
+```python
+document = client.get_document(document_id)
+print(document.file_url)
+
+pdf = client.download_document(document_id)
+open("signed.pdf", "wb").write(pdf)
+```
+
+A document that is still being signed can be downloaded as well - it then carries only the
+signatures collected so far.
+
+## Tags
+
+```python
+tag = client.create_tag("contracts")
+client.set_document_tags(document_id, tag_ids=[tag.id], names=["2026"])
+```
+
+Setting tags replaces the whole set: tags left out are removed, and names that do not exist yet are
+added to the company tag pool.
+
+## Verifying webhooks
+
+Autosignly signs every delivery. Check the signature against the raw request body, before parsing
+it - re-serialising the JSON changes the bytes and the signature will not match.
+
+```python
+from autosignly import webhooks
+
+webhooks.verify(
+    request.body,
+    request.headers["X-Webhook-Signature"],
+    webhook_key,
+    request.headers["X-Webhook-Timestamp"],
+)
+```
+
+The signature covers the timestamp as well as the body, and a delivery older than five minutes is
+rejected even when its signature matches, so a captured request cannot be replayed later.
+
+While a webhook key is being rotated a delivery carries several signatures; it is accepted when any
+of them matches, so rotation needs no change on your side.
+
+`verify` raises `InvalidSignatureError` on a mismatch; `webhooks.is_valid(...)` returns a boolean
+instead.
+
+## Errors
+
+Every failure raises a subclass of `AutosignlyError` carrying the HTTP status and the error type
+returned by the API.
+
+```python
+from autosignly import AutosignlyError, NotFoundError
+
+try:
+    client.get_document("does-not-exist")
+except NotFoundError:
+    ...
+except AutosignlyError as error:
+    print(error.status_code, error.error_type, error.error_id)
+```
+
+Connection problems and server errors are retried automatically, with an exponential backoff and
+jitter. Client errors are not retried, since repeating a rejected request cannot change its outcome.
+
+Rate limits are retried too, honouring the delay the API asks for. When that delay is longer than a
+minute the call fails instead of blocking your thread, and `RateLimitError.retry_after` tells you
+how long to wait.
+
+The client does not implement a circuit breaker. It runs inside your process, on calls you asked
+for, so refusing to even attempt one would be surprising - and your own infrastructure is the right
+place for that policy. Pass your own `http_client` if you want to add one.
+
+## Links
+
+- Website: <https://autosignly.eu>
+- API documentation: <https://docs.16it.eu/docs/intro/>
+- Source and issues: <https://github.com/16it-pl/autosignly-sdk>
+
+## License
+
+Apache-2.0

autosignly-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+autosignly/__init__.py,sha256=NNa2OgMweqhCE7RUZBOeguPLMHzDGkk-RjVp-utzRcQ,1734
+autosignly/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+autosignly/client.py,sha256=cCgHJcP9QIPwBPyLzppX14JNx6L0GKPFJ_LOss7bfOo,14615
+autosignly/errors.py,sha256=QyKj7iS74hamgkIi1En5BJvYZNLov4SA7_mzqq4P68Q,1852
+autosignly/models.py,sha256=KytRDn6-zwuFXGzpgXNnOHvcwB8GHlADOXsmn3jC_zg,8259
+autosignly/webhooks.py,sha256=U7dGTM3AQ3bDasmRG-_vE29BrR1_OirBjwUKeHBAfkc,2557
+autosignly-0.1.0.dist-info/METADATA,sha256=pUQDeuWYPgjg6Z161QYf2nGesi_M5SzLTVdyYiWkdW8,5037
+autosignly-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+autosignly-0.1.0.dist-info/RECORD,,

autosignly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any