autosignly 0.1.0.dev0__tar.gz → 0.1.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: autosignly
-Version: 0.1.0.dev0
+Version: 0.1.3
 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
@@ -95,17 +140,63 @@ 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.
 
+## Parties
+
+A party is the other side of a document — a business or a natural person the company signs with.
+
+```python
+from autosignly import Party, PartyAddress, PartyType
+
+acme = client.create_party(Party(
+    type=PartyType.COMPANY,
+    name="Acme Sp. z o.o.",
+    tax_id="5842831253",
+    email="kontakt@acme.pl",
+    address=PartyAddress(street="Marszalkowska", number="12/34",
+                         postal_code="00-001", city="Warszawa", country_code="PL"),
+))
+
+for party in client.list_parties(name="acme", type=PartyType.COMPANY):
+    print(party.id, party.name, party.tax_id)
+
+client.update_party(acme.id, Party(type=PartyType.COMPANY, name="Acme Renamed",
+                                   tax_id="5842831253"))
+client.delete_party(acme.id)
+```
+
+A `COMPANY` needs a `tax_id` and an `address`; a `PERSON` needs a `firstname` and an `email`. A
+Polish address makes the tax id subject to the NIP checksum.
+
+`update_party` replaces the whole party, so send every field you want to keep. Creating a party
+that already exists — same tax id for a `COMPANY`, same e-mail for a `PERSON` — is rejected rather
+than deduplicated, so look the party up before retrying a failed create.
+
+Parties belong to the environment of the key that created them: a sandbox key never sees a
+production party. Listing has no `sort` — the searchable fields are stored encrypted, so the
+server cannot order by them.
+
 ## 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.3/README.md

@@ -0,0 +1,218 @@
+# 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)
+```
+
+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
+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.
+
+## 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
+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.
+
+## Parties
+
+A party is the other side of a document — a business or a natural person the company signs with.
+
+```python
+from autosignly import Party, PartyAddress, PartyType
+
+acme = client.create_party(Party(
+    type=PartyType.COMPANY,
+    name="Acme Sp. z o.o.",
+    tax_id="5842831253",
+    email="kontakt@acme.pl",
+    address=PartyAddress(street="Marszalkowska", number="12/34",
+                         postal_code="00-001", city="Warszawa", country_code="PL"),
+))
+
+for party in client.list_parties(name="acme", type=PartyType.COMPANY):
+    print(party.id, party.name, party.tax_id)
+
+client.update_party(acme.id, Party(type=PartyType.COMPANY, name="Acme Renamed",
+                                   tax_id="5842831253"))
+client.delete_party(acme.id)
+```
+
+A `COMPANY` needs a `tax_id` and an `address`; a `PERSON` needs a `firstname` and an `email`. A
+Polish address makes the tax id subject to the NIP checksum.
+
+`update_party` replaces the whole party, so send every field you want to keep. Creating a party
+that already exists — same tax id for a `COMPANY`, same e-mail for a `PERSON` — is rejected rather
+than deduplicated, so look the party up before retrying a failed create.
+
+Parties belong to the environment of the key that created them: a sandbox key never sees a
+production party. Listing has no `sort` — the searchable fields are stored encrypted, so the
+server cannot order by them.
+
+## 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.dev0 → autosignly-0.1.3}/src/autosignly/__init__.py

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

autosignly-0.1.3/src/autosignly/_version.py

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

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import mimetypes
 import random
 import time
 import uuid
@@ -13,9 +14,12 @@ import httpx
 from . import errors
 from ._version import __version__
 from .models import (
+    Attachment,
+    Credentials,
     Document,
     DocumentSummary,
     Page,
+    Party,
     Signer,
     SigningRequestResult,
     Tag,
@@ -87,23 +91,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 +133,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 +166,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 +235,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 +251,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 +261,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 +271,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 +288,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:
@@ -222,6 +305,58 @@ class AutosignlyClient:
         payload = self._request("POST", "/documents/signings", files=files)
         return payload.get("documentId", "")
 
+    # -- parties -------------------------------------------------------------
+
+    def list_parties(
+        self,
+        *,
+        name: str | None = None,
+        type: str | None = None,
+        page: int = 0,
+        size: int = 20,
+    ) -> Page[Party]:
+        """Return one page of the company parties for this environment.
+
+        ``name`` matches a fragment of the name, given name, tax id, e-mail or
+        phone. ``type`` narrows the page to ``COMPANY`` or ``PERSON``. There is no sort: the searchable fields are stored
+        encrypted, so the server cannot order by them.
+        """
+        params: list[tuple[str, Any]] = [("page", page), ("size", size)]
+        if name:
+            params.append(("name", name))
+        if type:
+            params.append(("type", type))
+        payload = self._request("GET", "/parties", params=params)
+        return _to_page(payload, Party.from_payload)
+
+    def get_party(self, party_id: str) -> Party:
+        """Return one party. Unknown in this environment raises ``NotFoundError``."""
+        payload = self._request("GET", f"/parties/{party_id}")
+        return Party.from_payload(payload)
+
+    def create_party(self, party: Party) -> Party:
+        """Add a party to the company in this environment.
+
+        A party with the same tax id (``COMPANY``) or e-mail (``PERSON``) is
+        rejected rather than duplicated, so this call is not safe to repeat
+        blindly — look the party up first when retrying.
+        """
+        payload = self._request("POST", "/parties", json_body=party.to_payload())
+        return Party.from_payload(payload)
+
+    def update_party(self, party_id: str, party: Party) -> Party:
+        """Replace the party data.
+
+        Every field is taken from ``party``, so send the whole party, not only
+        what changed.
+        """
+        payload = self._request("PUT", f"/parties/{party_id}", json_body=party.to_payload())
+        return Party.from_payload(payload)
+
+    def delete_party(self, party_id: str) -> None:
+        """Remove the party. Documents already signed keep their copy of the data."""
+        self._request("DELETE", f"/parties/{party_id}")
+
     # -- tags ----------------------------------------------------------------
 
     def list_tags(self, *, name: str | None = None, page: int = 0, size: int = 20) -> Page[Tag]:
@@ -266,6 +401,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 +457,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.