autosignly 0.1.0.dev0__tar.gz → 0.1.2__tar.gz

{autosignly-0.1.0.dev0 → autosignly-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: autosignly
-Version: 0.1.0.dev0
+Version: 0.1.2
 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/
@@ -69,6 +69,13 @@ for summary in client.iter_documents(status="SIGNED"):
     print(summary.id, summary.name)
 ```
 
+Both listing calls take `tag_id` as well. Several tags narrow the result — a document has to
+carry all of them — and a tag that does not exist gives an empty page rather than an error:
+
+```python
+page = client.list_documents(tag_id=["contracts", "2026"], status="SIGNED")
+```
+
 ## Downloading the file
 
 A document carries a short-lived link to its file. The link expires, so fetch the document again
@@ -85,6 +92,44 @@ 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.
 
+## Attachments
+
+Files attached to a document are converted to PDF and merged into it when it is sent for
+signing, behind an index page listing each one with its checksum — so a single signature
+covers the document and everything attached to it.
+
+Attachments can only be added before the document is sent, so upload it first and send it
+afterwards instead of using `upload_and_sign`:
+
+```python
+document_id = client.upload_pdf(
+    pdf=open("protocol.pdf", "rb").read(),
+    document_name="Handover protocol",
+)
+
+attachment = client.add_attachment(
+    document_id,
+    content=open("site-photo.jpg", "rb").read(),
+    file_name="site-photo.jpg",
+)
+print(attachment.order_index, attachment.sha256)
+
+for existing in client.list_attachments(document_id):
+    print(existing.file_name, existing.page_count)
+
+client.send_for_signing(document_id, signers=[signer])
+```
+
+An attachment can be dropped again while the document is still unsent:
+
+```python
+client.delete_attachment(document_id, attachment.id)
+```
+
+PDF, JPEG and PNG are accepted, recognised from the content rather than the file name.
+Attachments merge in the order they were added, and can only be changed before the document
+is sent for signing.
+
 ## Tags
 
 ```python
@@ -97,15 +142,26 @@ added to the company tag pool.
 
 ## Verifying webhooks
 
-Autosignly signs every webhook 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.
+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)
+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.
 

{autosignly-0.1.0.dev0 → autosignly-0.1.2}/README.md

@@ -49,6 +49,13 @@ for summary in client.iter_documents(status="SIGNED"):
     print(summary.id, summary.name)
 ```
 
+Both listing calls take `tag_id` as well. Several tags narrow the result — a document has to
+carry all of them — and a tag that does not exist gives an empty page rather than an error:
+
+```python
+page = client.list_documents(tag_id=["contracts", "2026"], status="SIGNED")
+```
+
 ## Downloading the file
 
 A document carries a short-lived link to its file. The link expires, so fetch the document again
@@ -65,6 +72,44 @@ 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.
 
+## Attachments
+
+Files attached to a document are converted to PDF and merged into it when it is sent for
+signing, behind an index page listing each one with its checksum — so a single signature
+covers the document and everything attached to it.
+
+Attachments can only be added before the document is sent, so upload it first and send it
+afterwards instead of using `upload_and_sign`:
+
+```python
+document_id = client.upload_pdf(
+    pdf=open("protocol.pdf", "rb").read(),
+    document_name="Handover protocol",
+)
+
+attachment = client.add_attachment(
+    document_id,
+    content=open("site-photo.jpg", "rb").read(),
+    file_name="site-photo.jpg",
+)
+print(attachment.order_index, attachment.sha256)
+
+for existing in client.list_attachments(document_id):
+    print(existing.file_name, existing.page_count)
+
+client.send_for_signing(document_id, signers=[signer])
+```
+
+An attachment can be dropped again while the document is still unsent:
+
+```python
+client.delete_attachment(document_id, attachment.id)
+```
+
+PDF, JPEG and PNG are accepted, recognised from the content rather than the file name.
+Attachments merge in the order they were added, and can only be changed before the document
+is sent for signing.
+
 ## Tags
 
 ```python
@@ -77,15 +122,26 @@ added to the company tag pool.
 
 ## Verifying webhooks
 
-Autosignly signs every webhook 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.
+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)
+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.
 

{autosignly-0.1.0.dev0 → autosignly-0.1.2}/src/autosignly/__init__.py

@@ -26,10 +26,16 @@ from .errors import (
     ValidationError,
 )
 from .models import (
+    Attachment,
+    AttachmentFormat,
+    AttachmentStatus,
+    Credentials,
     Document,
     DocumentStatus,
+    EnvironmentType,
     DocumentSummary,
     Page,
+    SignatureMode,
     SignatureType,
     Signer,
     SignerDetails,
@@ -53,10 +59,16 @@ __all__ = [
     "RateLimitError",
     "ServerError",
     "ValidationError",
+    "Attachment",
+    "AttachmentFormat",
+    "AttachmentStatus",
+    "Credentials",
     "Document",
     "DocumentStatus",
+    "EnvironmentType",
     "DocumentSummary",
     "Page",
+    "SignatureMode",
     "SignatureType",
     "Signer",
     "SignerDetails",

autosignly-0.1.2/src/autosignly/_version.py

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

{autosignly-0.1.0.dev0 → autosignly-0.1.2}/src/autosignly/client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import mimetypes
 import random
 import time
 import uuid
@@ -13,6 +14,8 @@ import httpx
 from . import errors
 from ._version import __version__
 from .models import (
+    Attachment,
+    Credentials,
     Document,
     DocumentSummary,
     Page,
@@ -87,23 +90,40 @@ class AutosignlyClient:
         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,
+        tag_id: 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."""
+        """Return one page of documents belonging to this environment.
+
+        Several tags narrow the result: a document has to carry all of them. A
+        tag that does not exist yields an empty page rather than an error.
+        """
         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)
+        if tag_id:
+            tags = [tag_id] if isinstance(tag_id, str) else list(tag_id)
+            params.extend(("tagId", tag) for tag in tags)
 
         payload = self._request("GET", "/documents", params=params)
         return _to_page(payload, DocumentSummary.from_payload)
@@ -112,13 +132,15 @@ class AutosignlyClient:
         self,
         *,
         status: str | Sequence[str] | None = None,
+        tag_id: 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)
+            page = self.list_documents(
+                status=status, tag_id=tag_id, page=page_number, size=size, sort=sort)
             yield from page.content
             if not page.has_next:
                 return
@@ -143,14 +165,68 @@ class AutosignlyClient:
                 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
+        return self._download(document.file_url, document_id)
 
-        if response.status_code >= 400:
-            raise _to_error(response)
-        return response.content
+    def upload_pdf(self, *, pdf: bytes, document_name: str, file_name: str = "document.pdf") -> str:
+        """Store a PDF as a document without sending it to anyone.
+
+        Returns the identifier of the created document. Use this when the
+        document needs attachments before it goes out: upload it, attach the
+        files with :meth:`add_attachment`, then call :meth:`send_for_signing`.
+        A document that has already been sent can no longer take attachments.
+        """
+        files = {
+            "file": (file_name, pdf, "application/pdf"),
+            "request": (None, json.dumps({"documentName": document_name}), "application/json"),
+        }
+        payload = self._request("POST", "/documents", files=files)
+        return payload.get("documentId", "")
+
+    # -- attachments ---------------------------------------------------------
+
+    def list_attachments(self, document_id: str) -> list[Attachment]:
+        """Return the attachments of a document, in the order they will merge."""
+        payload = self._request("GET", f"/documents/{document_id}/attachments")
+        return [Attachment.from_payload(item) for item in payload or []]
+
+    def add_attachment(
+        self,
+        document_id: str,
+        *,
+        content: bytes,
+        file_name: str,
+    ) -> Attachment:
+        """Attach a file to a document that has not been sent for signing yet.
+
+        The file is converted to PDF and merged into the document when it is
+        sent, behind an index page carrying its checksum, so one signature
+        covers the document and everything attached to it. PDF, JPEG and PNG
+        are accepted, recognised from the content rather than the file name.
+        Attachments merge in the order they were added.
+        """
+        files = {"file": (file_name, content, _content_type(file_name))}
+        payload = self._request("POST", f"/documents/{document_id}/attachments", files=files)
+        return Attachment.from_payload(payload)
+
+    def delete_attachment(self, document_id: str, attachment_id: str) -> None:
+        """Remove an attachment from a document not yet sent for signing."""
+        self._request("DELETE", f"/documents/{document_id}/attachments/{attachment_id}")
+
+    def download_attachment(self, document_id: str, attachment_id: str) -> bytes:
+        """Fetch one attachment converted to PDF — the rendition that gets merged."""
+        for attachment in self.list_attachments(document_id):
+            if attachment.id != attachment_id:
+                continue
+            if not attachment.file_url:
+                raise errors.NotFoundError(
+                    f"Attachment {attachment_id} is not converted yet",
+                    status_code=404,
+                )
+            return self._download(attachment.file_url, attachment_id)
+        raise errors.NotFoundError(
+            f"Document {document_id} has no attachment {attachment_id}",
+            status_code=404,
+        )
 
     def send_for_signing(
         self,
@@ -158,6 +234,7 @@ class AutosignlyClient:
         *,
         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,
@@ -173,6 +250,8 @@ class AutosignlyClient:
             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:
@@ -181,7 +260,7 @@ class AutosignlyClient:
                 "locale": initiator_locale,
             }
 
-        payload = self._request("POST", f"/documents/{document_id}/send-for-signing", json_body=body)
+        payload = self._request("POST", f"/documents/{document_id}/signings", json_body=body)
         return SigningRequestResult.from_payload(payload)
 
     def upload_and_sign(
@@ -191,6 +270,7 @@ class AutosignlyClient:
         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,
@@ -207,6 +287,8 @@ class AutosignlyClient:
         }
         if signature_type:
             request["signatureType"] = signature_type
+        if signature_mode:
+            request["signatureMode"] = signature_mode
         if verification_method:
             request["verificationMethod"] = verification_method
         if initiator_email:
@@ -266,6 +348,16 @@ class AutosignlyClient:
 
     # -- transport -----------------------------------------------------------
 
+    def _download(self, url: str, subject: str) -> bytes:
+        try:
+            response = self._http.get(url)
+        except httpx.TransportError as exc:
+            raise errors.ConnectionError(f"Could not download {subject}: {exc}") from exc
+
+        if response.status_code >= 400:
+            raise _to_error(response)
+        return response.content
+
     def _request(
         self,
         method: str,
@@ -312,6 +404,12 @@ class AutosignlyClient:
         raise errors.ConnectionError(f"Could not reach {url}: {last_error}")
 
 
+def _content_type(file_name: str) -> str:
+    """The server detects the real format from the bytes; this is only a hint."""
+    guessed, _ = mimetypes.guess_type(file_name)
+    return guessed or "application/octet-stream"
+
+
 def _backoff(attempt: int) -> float:
     """Exponential backoff with jitter.
 

{autosignly-0.1.0.dev0 → autosignly-0.1.2}/src/autosignly/models.py

@@ -30,6 +30,22 @@ class VerificationMethod:
     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."""
 
@@ -48,6 +64,23 @@ class DocumentStatus:
     CANCELLED = "CANCELLED"
 
 
+class AttachmentFormat:
+    """Format of an attached file, detected from its content."""
+
+    PDF = "PDF"
+    JPEG = "JPEG"
+    PNG = "PNG"
+
+
+class AttachmentStatus:
+    """Whether an attachment is ready to be merged into the document."""
+
+    #: Converted to PDF and ready to be merged.
+    READY = "READY"
+    #: Conversion failed; the attachment is skipped when the document is signed.
+    FAILED = "FAILED"
+
+
 class SigningStatus:
     """State of an individual signer within a signing request."""
 
@@ -55,6 +88,29 @@ class SigningStatus:
     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."""
@@ -145,6 +201,40 @@ class SignerDetails:
         )
 
 
+@dataclass(slots=True)
+class Attachment:
+    """A file attached to a document.
+
+    Attachments are converted to PDF and merged into the document when it is
+    sent for signing, behind an index page listing each one with its checksum,
+    so a single signature covers the document and everything attached to it.
+    """
+
+    id: str
+    order_index: int = 0
+    file_name: str | None = None
+    format: str | None = None
+    size_bytes: int = 0
+    sha256: str | None = None
+    page_count: int | None = None
+    status: str | None = None
+    file_url: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> "Attachment":
+        return cls(
+            id=payload["id"],
+            order_index=payload.get("orderIndex", 0),
+            file_name=payload.get("fileName"),
+            format=payload.get("format"),
+            size_bytes=payload.get("sizeBytes", 0),
+            sha256=payload.get("sha256"),
+            page_count=payload.get("pageCount"),
+            status=payload.get("status"),
+            file_url=payload.get("fileUrl"),
+        )
+
+
 @dataclass(slots=True)
 class Document:
     """Full details of a document, including its signers and a link to its file.

autosignly-0.1.2/src/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.dev0 → autosignly-0.1.2}/tests/test_client.py

@@ -28,6 +28,30 @@ def build_client(handler, **kwargs):
     )
 
 
+def test_describe_credentials_reports_the_environment():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return httpx.Response(
+            200,
+            json={
+                "valid": True,
+                "companyId": "co-1",
+                "environmentId": "env-1",
+                "environmentType": "SANDBOX",
+            },
+        )
+
+    with build_client(handler) as client:
+        credentials = client.describe_credentials()
+
+    assert seen["url"] == "https://api.test/api/publics/v1/credentials"
+    assert credentials.valid is True
+    assert credentials.company_id == "co-1"
+    assert credentials.environment_type == "SANDBOX"
+
+
 def test_sends_credentials_as_headers():
     seen = {}
 
@@ -79,6 +103,34 @@ def test_list_documents_parses_page_and_sends_filters():
     assert ("status", "GENERATED") in seen["params"]
 
 
+def test_list_documents_repeats_the_tag_filter():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json={"content": [], "page": {"number": 0, "size": 20, "totalElements": 0, "totalPages": 0}})
+
+    with build_client(handler) as client:
+        client.list_documents(tag_id=["tag-1", "tag-2"], status="SIGNED")
+
+    assert "tagId=tag-1" in seen["url"]
+    assert "tagId=tag-2" in seen["url"]
+    assert "status=SIGNED" in seen["url"]
+
+
+def test_list_documents_accepts_a_single_tag():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json={"content": [], "page": {"number": 0, "size": 20, "totalElements": 0, "totalPages": 0}})
+
+    with build_client(handler) as client:
+        client.list_documents(tag_id="tag-1")
+
+    assert seen["url"].count("tagId=") == 1
+
+
 def test_iter_documents_follows_pages():
     pages = {
         "0": {
@@ -148,6 +200,116 @@ def test_upload_and_sign_posts_multipart_with_json_part():
     assert seen["idempotency"]
 
 
+def test_upload_pdf_stores_the_document_without_sending_it():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["body"] = request.content
+        return httpx.Response(200, json={"documentId": "doc-7"})
+
+    with build_client(handler) as client:
+        document_id = client.upload_pdf(pdf=b"%PDF-1.4 fake", document_name="Umowa", file_name="umowa.pdf")
+
+    assert document_id == "doc-7"
+    assert seen["url"].endswith("/documents")
+    assert b'name="request"' in seen["body"]
+    assert b"Umowa" in seen["body"]
+    assert b"signers" not in seen["body"]
+
+
+def test_list_attachments_parses_the_merge_order():
+    payload = [
+        {
+            "id": "att-1",
+            "orderIndex": 0,
+            "fileName": "photo.jpg",
+            "format": "JPEG",
+            "sizeBytes": 482913,
+            "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+            "pageCount": 1,
+            "status": "READY",
+            "fileUrl": "https://files.example/att-1.pdf",
+        },
+        {"id": "att-2", "orderIndex": 1, "fileName": "annex.pdf", "format": "PDF", "status": "READY"},
+    ]
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return httpx.Response(200, json=payload)
+
+    with build_client(handler) as client:
+        attachments = client.list_attachments("doc-1")
+
+    assert seen["url"].endswith("/documents/doc-1/attachments")
+    assert [a.id for a in attachments] == ["att-1", "att-2"]
+    assert [a.order_index for a in attachments] == [0, 1]
+    assert attachments[0].file_name == "photo.jpg"
+    assert attachments[0].page_count == 1
+    assert attachments[0].sha256.startswith("9f86d081")
+    assert attachments[1].page_count is None
+
+
+def test_add_attachment_posts_the_file_as_multipart():
+    seen = {}
+
+    def handler(request):
+        seen["method"] = request.method
+        seen["url"] = str(request.url)
+        seen["content_type"] = request.headers.get("content-type", "")
+        seen["body"] = request.content
+        return httpx.Response(200, json={"id": "att-1", "orderIndex": 0, "fileName": "photo.jpg"})
+
+    with build_client(handler) as client:
+        attachment = client.add_attachment("doc-1", content=b"\xff\xd8\xff fake jpeg", file_name="photo.jpg")
+
+    assert attachment.id == "att-1"
+    assert seen["method"] == "POST"
+    assert seen["url"].endswith("/documents/doc-1/attachments")
+    assert seen["content_type"].startswith("multipart/form-data")
+    assert b'name="file"' in seen["body"]
+    assert b"image/jpeg" in seen["body"]
+    assert b"fake jpeg" in seen["body"]
+
+
+def test_delete_attachment_targets_the_attachment():
+    seen = {}
+
+    def handler(request):
+        seen["method"] = request.method
+        seen["url"] = str(request.url)
+        return httpx.Response(204)
+
+    with build_client(handler) as client:
+        client.delete_attachment("doc-1", "att-1")
+
+    assert seen["method"] == "DELETE"
+    assert seen["url"].endswith("/documents/doc-1/attachments/att-1")
+
+
+def test_download_attachment_follows_the_converted_file_url():
+    def handler(request):
+        if request.url.path.endswith("/attachments"):
+            return httpx.Response(
+                200,
+                json=[{"id": "att-1", "fileUrl": "https://files.example/att-1.pdf"}],
+            )
+        return httpx.Response(200, content=b"%PDF converted")
+
+    with build_client(handler) as client:
+        assert client.download_attachment("doc-1", "att-1") == b"%PDF converted"
+
+
+def test_download_attachment_before_conversion_raises():
+    def handler(request):
+        return httpx.Response(200, json=[{"id": "att-1", "status": "FAILED"}])
+
+    with build_client(handler) as client:
+        with pytest.raises(NotFoundError):
+            client.download_attachment("doc-1", "att-1")
+
+
 def test_signer_payload_omits_empty_fields():
     payload = Signer(
         first_name="Anna", last_name="Nowak", email="anna@example.com", country="PL"

autosignly-0.1.2/tests/test_contract.py

@@ -0,0 +1,137 @@
+"""Contract test: every field name this client reads or sends must exist in the
+published OpenAPI schema.
+
+The field lists are not written by hand. Each parser is called with a mapping
+that records which keys it asks for, so a parser that starts reading a different
+key is checked automatically — which a hand-kept list would never do.
+
+Runs offline against ``spec/autodocuments-v1.yaml``: no environment, no network.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+import pytest
+import yaml
+
+from autosignly.client import _to_page
+from autosignly.models import (
+    Attachment,
+    Credentials,
+    Document,
+    DocumentSummary,
+    Signer,
+    SignerDetails,
+    SignerStatus,
+    SigningRequestResult,
+    Tag,
+)
+
+SPEC = yaml.safe_load(
+    (Path(__file__).resolve().parents[3] / "spec" / "autodocuments-v1.yaml").read_text()
+)
+
+
+def properties_of(schema: str) -> set[str]:
+    found = SPEC["components"]["schemas"].get(schema)
+    assert found is not None, f"schema {schema} is missing from the spec"
+    return set(found.get("properties") or {})
+
+
+class Recorder(dict):
+    """A payload that remembers every key asked of it."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.seen: set[str] = set()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        self.seen.add(key)
+        return default
+
+    def __getitem__(self, key: str) -> Any:
+        self.seen.add(key)
+        raise KeyError(key)
+
+
+def keys_read_by(parse: Callable[[dict], Any]) -> set[str]:
+    recorder = Recorder()
+    try:
+        parse(recorder)
+    except KeyError:
+        pass
+    return recorder.seen
+
+
+PARSERS = [
+    ("Attachment", "AttachmentResponse", Attachment.from_payload),
+    ("Document", "DocumentInfoResponse", Document.from_payload),
+    ("DocumentSummary", "DocumentListItemResponse", DocumentSummary.from_payload),
+    ("SignerDetails", "SignerResponse", SignerDetails.from_payload),
+    ("SignerStatus", "SignerStatusResponse", SignerStatus.from_payload),
+    ("Credentials", "CredentialsResponse", Credentials.from_payload),
+    ("SigningRequestResult", "SendForSigningResponse", SigningRequestResult.from_payload),
+    ("Tag", "TagResponse", Tag.from_payload),
+]
+
+
+@pytest.mark.parametrize(("name", "schema", "parse"), PARSERS, ids=[p[0] for p in PARSERS])
+def test_parser_only_reads_declared_fields(name: str, schema: str, parse) -> None:
+    unknown = sorted(keys_read_by(parse) - properties_of(schema))
+    assert unknown == [], f"{name} reads fields the API does not send: {', '.join(unknown)}"
+
+
+def test_page_reads_the_envelope_the_api_sends() -> None:
+    envelope = properties_of("PageResponseDocumentListItemResponseV1")
+    unknown = sorted(keys_read_by(lambda payload: _to_page(payload, lambda item: None)) - envelope)
+    assert unknown == []
+
+    info = properties_of("PageInfo")
+    for counter in ("number", "size", "totalElements", "totalPages"):
+        assert counter in info, f"PageInfo lost {counter}"
+
+
+def test_signer_sends_only_fields_the_api_accepts() -> None:
+    payload = Signer(
+        first_name="Anna",
+        last_name="Nowak",
+        email="anna@example.com",
+        country="PL",
+        phone_number="+48123456789",
+        locale="pl",
+        order=1,
+        signature_type="AES",
+        signature_verification_method="SMS",
+    ).to_payload()
+
+    unknown = sorted(set(payload) - properties_of("ExternalSignerRequest"))
+    assert unknown == [], f"unknown signer fields: {', '.join(unknown)}"
+
+
+def test_document_filters_the_client_sends_exist() -> None:
+    declared = {
+        param["name"]
+        for param in SPEC["paths"]["/api/publics/v1/documents"]["get"]["parameters"]
+    }
+
+    assert {"status", "tagId", "page", "size", "sort"} <= declared
+
+
+def test_every_endpoint_the_client_calls_exists() -> None:
+    called = {
+        "/api/publics/v1/api-key",
+        "/api/publics/v1/credentials",
+        "/api/publics/v1/documents",
+        "/api/publics/v1/documents/{documentId}",
+        "/api/publics/v1/documents/{documentId}/attachments",
+        "/api/publics/v1/documents/{documentId}/attachments/{attachmentId}",
+        "/api/publics/v1/documents/signings",
+        "/api/publics/v1/documents/{documentId}/signings",
+        "/api/publics/v1/documents/{documentId}/tags",
+        "/api/publics/v1/tags",
+        "/api/publics/v1/tags/{tagId}",
+    }
+    missing = sorted(called - set(SPEC["paths"]))
+    assert missing == [], f"endpoints gone from the API: {', '.join(missing)}"

autosignly-0.1.2/tests/test_webhooks.py

@@ -0,0 +1,74 @@
+import hashlib
+import hmac
+import time
+
+import pytest
+
+from autosignly import InvalidSignatureError
+from autosignly import webhooks
+
+SECRET = "wh_secret"
+PAYLOAD = b'{"eventId":"1","eventType":"document.signed"}'
+
+
+def now():
+    return str(int(time.time()))
+
+
+def signed(payload=PAYLOAD, secret=SECRET, timestamp=None):
+    timestamp = timestamp or now()
+    content = timestamp.encode() + b"." + payload
+    return hmac.new(secret.encode(), content, hashlib.sha256).hexdigest()
+
+
+def test_accepts_a_matching_signature():
+    ts = now()
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(timestamp=ts)}", SECRET, ts) is True
+
+
+def test_signature_covers_the_timestamp():
+    ts = now()
+    other = str(int(ts) - 1)
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(timestamp=other)}", SECRET, ts) is False
+
+
+def test_rejects_a_signature_for_different_bytes():
+    ts = now()
+    assert webhooks.is_valid(b'{"eventId":"2"}', f"v1={signed(timestamp=ts)}", SECRET, ts) is False
+
+
+def test_rejects_a_signature_made_with_another_secret():
+    ts = now()
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(secret='other', timestamp=ts)}", SECRET, ts) is False
+
+
+def test_accepts_when_one_of_several_signatures_matches():
+    ts = now()
+    header = f"v1=deadbeef,v1={signed(timestamp=ts)}"
+    assert webhooks.is_valid(PAYLOAD, header, SECRET, ts) is True
+
+
+def test_rejects_an_old_delivery_even_with_a_valid_signature():
+    ts = str(int(time.time()) - 3600)
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(timestamp=ts)}", SECRET, ts) is False
+
+
+def test_tolerance_can_be_disabled():
+    ts = str(int(time.time()) - 3600)
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(timestamp=ts)}", SECRET, ts, tolerance=0) is True
+
+
+def test_rejects_an_unknown_signature_version():
+    ts = now()
+    assert webhooks.is_valid(PAYLOAD, f"v2={signed(timestamp=ts)}", SECRET, ts) is False
+
+
+def test_rejects_missing_header_or_timestamp():
+    ts = now()
+    assert webhooks.is_valid(PAYLOAD, "", SECRET, ts) is False
+    assert webhooks.is_valid(PAYLOAD, f"v1={signed(timestamp=ts)}", SECRET, "") is False
+
+
+def test_verify_raises_on_mismatch():
+    with pytest.raises(InvalidSignatureError):
+        webhooks.verify(PAYLOAD, "v1=deadbeef", SECRET, now())

autosignly-0.1.0.dev0/src/autosignly/_version.py

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

autosignly-0.1.0.dev0/src/autosignly/webhooks.py

@@ -1,39 +0,0 @@
-"""Verification of webhook deliveries."""
-
-from __future__ import annotations
-
-import hashlib
-import hmac
-
-from .errors import InvalidSignatureError
-
-SIGNATURE_HEADER = "X-Webhook-Signature"
-
-
-def compute_signature(payload: bytes, secret: str) -> str:
-    """Return the hex digest Autosignly sends for this payload."""
-    return hmac.new(secret.encode("utf-8"), payload, hashlib.sha256).hexdigest()
-
-
-def is_valid(payload: bytes, signature_header: str, secret: str) -> 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.
-    """
-    if not signature_header or not secret:
-        return False
-
-    expected = compute_signature(payload, secret)
-    for candidate in signature_header.split(","):
-        candidate = candidate.strip()
-        _, _, digest = candidate.rpartition("=")
-        if digest and hmac.compare_digest(digest, expected):
-            return True
-    return False
-
-
-def verify(payload: bytes, signature_header: str, secret: str) -> None:
-    """Check a delivery and raise :class:`InvalidSignatureError` if it fails."""
-    if not is_valid(payload, signature_header, secret):
-        raise InvalidSignatureError("Webhook signature does not match the payload")

autosignly-0.1.0.dev0/tests/test_webhooks.py

@@ -1,40 +0,0 @@
-import hashlib
-import hmac
-
-import pytest
-
-from autosignly import InvalidSignatureError
-from autosignly import webhooks
-
-SECRET = "wh_secret"
-PAYLOAD = b'{"eventId":"1","eventType":"document.signed"}'
-
-
-def signed(payload=PAYLOAD, secret=SECRET):
-    return hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
-
-
-def test_accepts_a_matching_signature():
-    assert webhooks.is_valid(PAYLOAD, f"sha256={signed()}", SECRET) is True
-
-
-def test_rejects_a_signature_for_different_bytes():
-    assert webhooks.is_valid(b'{"eventId":"2"}', f"sha256={signed()}", SECRET) is False
-
-
-def test_rejects_a_signature_made_with_another_secret():
-    assert webhooks.is_valid(PAYLOAD, f"sha256={signed(secret='other')}", SECRET) is False
-
-
-def test_accepts_when_one_of_several_signatures_matches():
-    header = f"sha256=deadbeef,sha256={signed()}"
-    assert webhooks.is_valid(PAYLOAD, header, SECRET) is True
-
-
-def test_rejects_missing_header():
-    assert webhooks.is_valid(PAYLOAD, "", SECRET) is False
-
-
-def test_verify_raises_on_mismatch():
-    with pytest.raises(InvalidSignatureError):
-        webhooks.verify(PAYLOAD, "sha256=deadbeef", SECRET)