easycontract 0.1.0__py3-none-any.whl

easycontract/__init__.py

@@ -0,0 +1,40 @@
+"""easycontract — SDK oficial de Python.
+
+from easycontract import EasyContract
+
+client = EasyContract(api_key="ec_test_...")
+envelope = client.envelopes.create(title="Contrato", retention_period_months=72)
+"""
+
+__version__ = "0.1.0"
+
+from . import webhooks
+from .client import EasyContract
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    EasyContractError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SignatureVerificationError,
+)
+
+__all__ = [
+    "EasyContract",
+    "EasyContractError",
+    "APIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "InvalidRequestError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "SignatureVerificationError",
+    "webhooks",
+    "__version__",
+]

easycontract/client.py

@@ -0,0 +1,212 @@
+"""The easycontract API client (transport layer).
+
+- Auth via X-Api-Key (ec_live_… / ec_test_… — test keys see only test data).
+- Automatic Idempotency-Key on every POST (override or disable per call).
+- Retries with backoff on 429 (honoring Retry-After) and on 5xx for GETs.
+- RFC 7807 errors mapped to a typed exception hierarchy (errors.py).
+
+File objects passed in `files` are re-wound before every retry (a retry
+re-uploads the full document, not an empty body) and are closed once the
+request finishes, whatever the outcome. A non-seekable stream (pipe, socket)
+is sent once and never retried: an empty re-upload would be worse than the
+error.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+import uuid
+
+import requests
+
+from . import __version__
+from .errors import APIError, error_from_response
+from .resources import (
+    Envelopes,
+    Events,
+    Invitations,
+    Members,
+    Organization,
+    Templates,
+    Webhooks,
+)
+
+DEFAULT_BASE_URL = "https://api.easycontract.online/api/v1"
+DEFAULT_TIMEOUT = 30
+DEFAULT_MAX_RETRIES = 3
+_MAX_RETRY_SLEEP = 30
+
+
+def _retry_after_seconds(response) -> int:
+    """Parse a delta-seconds Retry-After header; fall back to 1 for anything
+    else (HTTP-date form, garbage, missing)."""
+    try:
+        return max(0, int(response.headers.get("Retry-After", "")))
+    except (TypeError, ValueError):
+        return 1
+
+
+def _file_handles(files):
+    """Yield the file objects inside a requests-style `files` mapping."""
+    if not files:
+        return
+    for value in files.values():
+        candidate = value[1] if isinstance(value, tuple) and len(value) > 1 else value
+        if hasattr(candidate, "read"):
+            yield candidate
+
+
+def _rewind(handle) -> bool:
+    """Put a file object back at its start. False if it cannot be rewound."""
+    try:
+        if hasattr(handle, "seekable") and not handle.seekable():
+            return False
+        handle.seek(0)
+    except (AttributeError, OSError, ValueError):
+        return False
+    return True
+
+
+class EasyContract:
+    """Entry point:
+
+    >>> client = EasyContract(api_key="ec_test_...", base_url="http://localhost:8000/api/v1")
+    >>> envelope = client.envelopes.create(title="Contrato", retention_period_months=72)
+
+    Usable as a context manager to release the connection pool:
+
+    >>> with EasyContract(api_key="ec_test_...") as client:
+    ...     client.whoami()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "X-Api-Key": api_key,
+                "User-Agent": f"easycontract-python/{__version__}",
+            }
+        )
+
+        self.envelopes = Envelopes(self)
+        self.templates = Templates(self)
+        self.webhooks = Webhooks(self)
+        self.events = Events(self)
+        self.organization = Organization(self)
+        self.members = Members(self)
+        self.invitations = Invitations(self)
+
+    # ------------------------------------------------------------------ core
+
+    def close(self) -> None:
+        """Close the underlying HTTP session and release its connections."""
+        self._session.close()
+
+    def __enter__(self) -> EasyContract:
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        files: dict | None = None,
+        data: dict | None = None,
+        idempotency_key: str | bool | None = None,
+        raw: bool = False,
+    ):
+        url = f"{self.base_url}{path}"
+        headers = {}
+        if method == "POST" and idempotency_key is not False:
+            if idempotency_key is None or idempotency_key is True or idempotency_key == "":
+                idempotency_key = str(uuid.uuid4())  # "generate one for me"
+            headers["Idempotency-Key"] = str(idempotency_key)  # e.g. a uuid.UUID
+
+        try:
+            response = self._send_with_retries(
+                method, url, json=json, params=params, files=files, data=data, headers=headers
+            )
+        finally:
+            for handle in _file_handles(files):
+                with contextlib.suppress(Exception):
+                    handle.close()
+
+        if response.status_code >= 400:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {"title": response.reason, "detail": response.text[:300]}
+            retry_after = None
+            if response.headers.get("Retry-After") is not None:
+                try:
+                    retry_after = max(0, int(response.headers["Retry-After"]))
+                except ValueError:
+                    retry_after = None
+            raise error_from_response(
+                response.status_code,
+                payload,
+                retry_after=retry_after,
+            )
+
+        if raw:
+            return response.content
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise APIError(
+                status=response.status_code,
+                code="invalid_response",
+                title="Non-JSON response",
+                detail="The API returned a body that is not valid JSON",
+            ) from exc
+
+    def _send_with_retries(self, method: str, url: str, *, headers: dict, **kwargs):
+        """GETs and 429s are retried with backoff (bounded by Retry-After).
+
+        File uploads are re-wound before every retry so it re-sends the whole
+        document; if any upload cannot be rewound the request is not retried.
+        """
+        handles = list(_file_handles(kwargs.get("files")))
+        attempt = 0
+        while True:
+            attempt += 1
+            response = self._session.request(
+                method,
+                url,
+                headers=headers,
+                timeout=self.timeout,
+                **kwargs,
+            )
+            retryable_429 = response.status_code == 429
+            retryable_5xx = response.status_code >= 500 and method == "GET"
+            if not (retryable_429 or retryable_5xx) or attempt >= self.max_retries:
+                return response
+            if not all(_rewind(handle) for handle in handles):
+                return response
+            time.sleep(min(_retry_after_seconds(response), _MAX_RETRY_SLEEP))
+
+    # ------------------------------------------------------------- shortcuts
+
+    def whoami(self) -> dict:
+        """GET /whoami/ — identifies the key's organization and mode."""
+        return self.request("GET", "/whoami/")

easycontract/errors.py

@@ -0,0 +1,80 @@
+"""Error hierarchy mapped from the API's RFC 7807 responses.
+
+Every error carries the stable machine-readable `code` documented in the
+OpenAPI spec, plus `status`, `title` and `detail`.
+"""
+
+from __future__ import annotations
+
+
+class EasyContractError(Exception):
+    """Base for everything raised by this SDK."""
+
+
+class APIError(EasyContractError):
+    def __init__(self, *, status: int, code: str = "", title: str = "", detail: str = ""):
+        self.status = status
+        self.code = code
+        self.title = title
+        self.detail = detail
+        super().__init__(f"[{status}] {code or title}: {detail or title}")
+
+
+class AuthenticationError(APIError):
+    """401 — missing or invalid API key."""
+
+
+class ForbiddenError(APIError):
+    """403 — plan quota/feature or membership rule (see .code)."""
+
+
+class NotFoundError(APIError):
+    """404 — no such resource in this organization (or wrong mode)."""
+
+
+class InvalidRequestError(APIError):
+    """400 — validation failed (see .detail)."""
+
+
+class ConflictError(APIError):
+    """409 — invalid lifecycle state for the operation."""
+
+
+class RateLimitError(APIError):
+    """429 — plan rate limit exceeded. .retry_after seconds when available."""
+
+    def __init__(self, *, retry_after: int | None = None, **kwargs):
+        super().__init__(**kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(APIError):
+    """5xx — easycontract-side failure."""
+
+
+class SignatureVerificationError(EasyContractError):
+    """Webhook payload signature could not be verified."""
+
+
+def error_from_response(status: int, payload, retry_after: int | None = None) -> APIError:
+    if not isinstance(payload, dict):
+        payload = {"detail": str(payload)[:300]} if payload else {}
+    kwargs = {
+        "status": status,
+        "code": str(payload.get("code") or ""),
+        "title": str(payload.get("title") or ""),
+        "detail": str(payload.get("detail") or ""),
+    }
+    if status == 401:
+        return AuthenticationError(**kwargs)
+    if status == 403:
+        return ForbiddenError(**kwargs)
+    if status == 404:
+        return NotFoundError(**kwargs)
+    if status == 409:
+        return ConflictError(**kwargs)
+    if status == 429:
+        return RateLimitError(retry_after=retry_after, **kwargs)
+    if status >= 500:
+        return ServerError(**kwargs)
+    return InvalidRequestError(**kwargs)

easycontract/resources.py

@@ -0,0 +1,653 @@
+"""Resource namespaces — a 1:1 mirror of docs/api/openapi.yaml.
+
+OPERATIONS maps every spec operation to its SDK method; CI in the main repo
+asserts full coverage, so the SDK cannot drift from the API contract.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from .errors import EasyContractError
+
+# (HTTP method, spec path) → dotted SDK method. CI-enforced coverage.
+OPERATIONS: dict[tuple[str, str], str] = {
+    ("GET", "/whoami/"): "client.whoami",
+    ("GET", "/organization/"): "client.organization.get",
+    ("GET", "/members/"): "client.members.list",
+    ("PATCH", "/members/{membership_id}/"): "client.members.change_role",
+    ("DELETE", "/members/{membership_id}/"): "client.members.remove",
+    ("GET", "/invitations/"): "client.invitations.list",
+    ("POST", "/invitations/"): "client.invitations.create",
+    ("DELETE", "/invitations/{invite_id}/"): "client.invitations.cancel",
+    ("GET", "/envelopes/"): "client.envelopes.list",
+    ("POST", "/envelopes/"): "client.envelopes.create",
+    ("GET", "/envelopes/{envelope_id}/"): "client.envelopes.get",
+    ("POST", "/envelopes/{envelope_id}/documents/"): "client.envelopes.add_document",
+    ("POST", "/envelopes/{envelope_id}/signers/"): "client.envelopes.add_signer",
+    ("POST", "/envelopes/{envelope_id}/send/"): "client.envelopes.send",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/signers/{signer_id}/remind/",
+    ): "client.envelopes.remind_signer",
+    ("POST", "/envelopes/{envelope_id}/void/"): "client.envelopes.void",
+    ("GET", "/envelopes/{envelope_id}/certificate/"): "client.envelopes.download_certificate",
+    ("GET", "/envelopes/{envelope_id}/evidence/"): "client.envelopes.download_evidence",
+    ("GET", "/templates/"): "client.templates.list",
+    ("POST", "/templates/"): "client.templates.create",
+    ("GET", "/templates/catalog/"): "client.templates.catalog",
+    ("POST", "/templates/catalog/{catalog_key}/clone/"): "client.templates.clone_from_catalog",
+    ("GET", "/templates/{template_id}/"): "client.templates.get",
+    ("PATCH", "/templates/{template_id}/"): "client.templates.update",
+    ("DELETE", "/templates/{template_id}/"): "client.templates.delete",
+    ("POST", "/templates/{template_id}/documents/"): "client.templates.add_document",
+    (
+        "GET",
+        "/templates/{template_id}/documents/{document_id}/",
+    ): "client.templates.get_document",
+    (
+        "PATCH",
+        "/templates/{template_id}/documents/{document_id}/",
+    ): "client.templates.update_document",
+    (
+        "DELETE",
+        "/templates/{template_id}/documents/{document_id}/",
+    ): "client.templates.delete_document",
+    (
+        "GET",
+        "/templates/{template_id}/documents/{document_id}/docx/",
+    ): "client.templates.download_docx",
+    (
+        "POST",
+        "/templates/{template_id}/documents/{document_id}/docx/",
+    ): "client.templates.upload_docx",
+    (
+        "GET",
+        "/templates/{template_id}/documents/{document_id}/translations/{language}/",
+    ): "client.templates.get_translation",
+    (
+        "PUT",
+        "/templates/{template_id}/documents/{document_id}/translations/{language}/",
+    ): "client.templates.put_translation",
+    (
+        "DELETE",
+        "/templates/{template_id}/documents/{document_id}/translations/{language}/",
+    ): "client.templates.delete_translation",
+    ("POST", "/templates/{template_id}/preview/"): "client.templates.preview",
+    ("POST", "/templates/{template_id}/duplicate/"): "client.templates.duplicate",
+    ("POST", "/templates/{template_id}/roles/"): "client.templates.add_role",
+    ("POST", "/templates/{template_id}/fields/"): "client.templates.add_field",
+    ("POST", "/templates/{template_id}/envelopes/"): "client.templates.create_envelope",
+    ("GET", "/events/"): "client.events.list",
+    ("GET", "/webhooks/"): "client.webhooks.list",
+    ("POST", "/webhooks/"): "client.webhooks.create",
+    ("DELETE", "/webhooks/{endpoint_id}/"): "client.webhooks.delete",
+    ("POST", "/webhooks/deliveries/{delivery_id}/redeliver/"): "client.webhooks.redeliver",
+}
+
+
+DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+
+
+def _file_tuple(file, name: str | None, content_type: str = "application/pdf"):
+    """Accept a path, bytes, or a file-like object."""
+    if isinstance(file, (str, Path)):
+        path = Path(file)
+        return (name or path.name, path.open("rb"), content_type)
+    if isinstance(file, bytes):
+        return (name or "document.pdf", io.BytesIO(file), content_type)
+    return (name or getattr(file, "name", "document.pdf"), file, content_type)
+
+
+class _Resource:
+    def __init__(self, client):
+        self._client = client
+
+    def _auto_paging(self, path: str, **params):
+        """Iterate every item across cursor pages. Guards against a server
+        that keeps advertising more pages without advancing the cursor
+        (would loop forever)."""
+        cursor = None
+        seen = set()
+        while True:
+            page = self._client.request(
+                "GET", path, params={**params, **({"cursor": cursor} if cursor else {})}
+            )
+            if not isinstance(page, dict) or not isinstance(page.get("data"), list):
+                raise EasyContractError("malformed page: missing 'data' list")
+            yield from page["data"]
+            if not page.get("has_more"):
+                return
+            cursor = page.get("next_cursor")
+            if cursor is None or cursor in seen:
+                raise EasyContractError("pagination cursor did not advance")
+            seen.add(cursor)
+
+
+class Envelopes(_Resource):
+    def create(
+        self,
+        *,
+        title: str,
+        retention_period_months: int,
+        signing_order: str = "parallel",
+        metadata: dict | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            "/envelopes/",
+            json={
+                "title": title,
+                "retention_period_months": retention_period_months,
+                "signing_order": signing_order,
+                "metadata": metadata or {},
+            },
+            idempotency_key=idempotency_key,
+        )
+
+    def list(
+        self, *, status: str | None = None, limit: int | None = None, cursor: str | None = None
+    ) -> dict:
+        params = {
+            k: v
+            for k, v in {
+                "status": status,
+                "limit": limit,
+                "cursor": cursor,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("GET", "/envelopes/", params=params)
+
+    def auto_paging_iter(self, *, status: str | None = None):
+        params = {"status": status} if status else {}
+        return self._auto_paging("/envelopes/", **params)
+
+    def get(self, envelope_id: str, *, expand: list[str] | None = None) -> dict:
+        params = {"expand": ",".join(expand)} if expand else None
+        return self._client.request("GET", f"/envelopes/{envelope_id}/", params=params)
+
+    def add_document(
+        self,
+        envelope_id: str,
+        *,
+        file,
+        name: str | None = None,
+        content_type: str = "application/pdf",
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            f"/envelopes/{envelope_id}/documents/",
+            files={"file": _file_tuple(file, name, content_type)},
+        )
+
+    def add_signer(
+        self,
+        envelope_id: str,
+        *,
+        full_name: str,
+        email: str,
+        phone: str = "",
+        order: int | None = None,
+        auth_methods: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        body = {"full_name": full_name, "email": email, "phone": phone}
+        if order is not None:
+            body["order"] = order
+        if auth_methods is not None:
+            body["auth_methods"] = auth_methods
+        return self._client.request(
+            "POST",
+            f"/envelopes/{envelope_id}/signers/",
+            json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def send(
+        self,
+        envelope_id: str,
+        *,
+        expires_in_days: int | None = None,
+        deliver_emails: bool = True,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        body: dict = {"deliver_emails": deliver_emails}
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        return self._client.request(
+            "POST",
+            f"/envelopes/{envelope_id}/send/",
+            json=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def remind_signer(self, envelope_id: str, signer_id: str) -> dict:
+        """Re-send the signing link (a FRESH one; previous links die)."""
+        return self._client.request("POST", f"/envelopes/{envelope_id}/signers/{signer_id}/remind/")
+
+    def void(self, envelope_id: str, *, reason: str = "") -> dict:
+        return self._client.request(
+            "POST", f"/envelopes/{envelope_id}/void/", json={"reason": reason}
+        )
+
+    def download_certificate(self, envelope_id: str, *, to: str | Path | None = None) -> bytes:
+        content = self._client.request("GET", f"/envelopes/{envelope_id}/certificate/", raw=True)
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+    def download_evidence(self, envelope_id: str, *, to: str | Path | None = None) -> bytes:
+        """The full evidence ZIP — what a tenant would take to court."""
+        content = self._client.request("GET", f"/envelopes/{envelope_id}/evidence/", raw=True)
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+
+class Templates(_Resource):
+    def create(
+        self,
+        *,
+        name: str,
+        retention_period_months: int,
+        description: str = "",
+        signing_order: str = "parallel",
+        metadata: dict | None = None,
+        variables: list[dict] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            "/templates/",
+            json={
+                "name": name,
+                "retention_period_months": retention_period_months,
+                "description": description,
+                "signing_order": signing_order,
+                "metadata": metadata or {},
+                "variables": variables or [],
+            },
+            idempotency_key=idempotency_key,
+        )
+
+    def update(self, template_id: str, **changes) -> dict:
+        """PATCH settings: name, description, signing_order,
+        retention_period_months, variables (schema list), metadata."""
+        return self._client.request("PATCH", f"/templates/{template_id}/", json=changes)
+
+    def catalog(self, *, language: str | None = None) -> dict:
+        """Starter templates shipped with the platform (house drafts)."""
+        params = {"language": language} if language else None
+        return self._client.request("GET", "/templates/catalog/", params=params)
+
+    def clone_from_catalog(
+        self, catalog_key: str, *, name: str = "", idempotency_key: str | None = None
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            f"/templates/catalog/{catalog_key}/clone/",
+            json={"name": name},
+            idempotency_key=idempotency_key,
+        )
+
+    def duplicate(
+        self, template_id: str, *, name: str = "", idempotency_key: str | None = None
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            f"/templates/{template_id}/duplicate/",
+            json={"name": name},
+            idempotency_key=idempotency_key,
+        )
+
+    def add_authored_document(
+        self,
+        template_id: str,
+        *,
+        name: str,
+        body_html: str,
+        header_text: str | None = None,
+        footer_text: str | None = None,
+        page_numbers: bool | None = None,
+    ) -> dict:
+        """Add an AUTHORED document (rich-text HTML with {{ tokens }}) that is
+        rendered to PDF at instantiation; signature fields are the
+        {{ signature:role }} / {{ date:role }} tokens in the text. Page
+        header/footer are plain text with tokens ({{ page }}/{{ pages }} too)."""
+        body: dict = {"name": name, "body_html": body_html}
+        for key, value in (
+            ("header_text", header_text),
+            ("footer_text", footer_text),
+            ("page_numbers", page_numbers),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._client.request("POST", f"/templates/{template_id}/documents/", json=body)
+
+    def get_document(self, template_id: str, document_id: str) -> dict:
+        return self._client.request("GET", f"/templates/{template_id}/documents/{document_id}/")
+
+    def update_document(
+        self,
+        template_id: str,
+        document_id: str,
+        *,
+        name: str | None = None,
+        body_html: str | None = None,
+        header_text: str | None = None,
+        footer_text: str | None = None,
+        page_numbers: bool | None = None,
+    ) -> dict:
+        body = {
+            k: v
+            for k, v in {
+                "name": name,
+                "body_html": body_html,
+                "header_text": header_text,
+                "footer_text": footer_text,
+                "page_numbers": page_numbers,
+            }.items()
+            if v is not None
+        }
+        return self._client.request(
+            "PATCH", f"/templates/{template_id}/documents/{document_id}/", json=body
+        )
+
+    def delete_document(self, template_id: str, document_id: str) -> None:
+        self._client.request("DELETE", f"/templates/{template_id}/documents/{document_id}/")
+
+    def get_translation(self, template_id: str, document_id: str, language: str) -> dict:
+        return self._client.request(
+            "GET", f"/templates/{template_id}/documents/{document_id}/translations/{language}/"
+        )
+
+    def put_translation(
+        self,
+        template_id: str,
+        document_id: str,
+        language: str,
+        *,
+        body_html: str | None = None,
+        header_text: str | None = None,
+        footer_text: str | None = None,
+    ) -> dict:
+        """Create or replace a language version (always a DRAFT). Approval is
+        a human act done in the panel; only approved, fresh translations can
+        be used when instantiating (`language`)."""
+        body = {
+            k: v
+            for k, v in {
+                "body_html": body_html,
+                "header_text": header_text,
+                "footer_text": footer_text,
+            }.items()
+            if v is not None
+        }
+        return self._client.request(
+            "PUT",
+            f"/templates/{template_id}/documents/{document_id}/translations/{language}/",
+            json=body,
+        )
+
+    def delete_translation(self, template_id: str, document_id: str, language: str) -> None:
+        self._client.request(
+            "DELETE",
+            f"/templates/{template_id}/documents/{document_id}/translations/{language}/",
+        )
+
+    def download_docx(
+        self, template_id: str, document_id: str, *, to: str | Path | None = None
+    ) -> bytes:
+        """Editable DOCX of an authored document (edit in Word, upload back)."""
+        content = self._client.request(
+            "GET", f"/templates/{template_id}/documents/{document_id}/docx/", raw=True
+        )
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+    def upload_docx(
+        self, template_id: str, document_id: str, *, file, name: str | None = None
+    ) -> dict:
+        """Replace an authored document's text with the uploaded DOCX."""
+        return self._client.request(
+            "POST",
+            f"/templates/{template_id}/documents/{document_id}/docx/",
+            files={"file": _file_tuple(file, name or "document.docx", DOCX_MIME)},
+            data={"name": name} if name else None,
+        )
+
+    def preview(
+        self,
+        template_id: str,
+        *,
+        document_id: str | None = None,
+        variables: dict | None = None,
+        signers: dict[str, dict] | None = None,
+        title: str = "",
+        language: str | None = None,
+        to: str | Path | None = None,
+    ) -> bytes:
+        """PDF preview of the authored documents (sample values where
+        none are given). Nothing is persisted."""
+        body: dict = {"variables": variables or {}, "signers": signers or {}, "title": title}
+        if document_id:
+            body["document_id"] = document_id
+        if language:
+            body["language"] = language
+        content = self._client.request(
+            "POST", f"/templates/{template_id}/preview/", json=body, raw=True
+        )
+        if to is not None:
+            Path(to).write_bytes(content)
+        return content
+
+    def list(self, *, limit: int | None = None, cursor: str | None = None) -> dict:
+        params = {k: v for k, v in {"limit": limit, "cursor": cursor}.items() if v}
+        return self._client.request("GET", "/templates/", params=params)
+
+    def get(self, template_id: str, *, expand: list[str] | None = None) -> dict:
+        params = {"expand": ",".join(expand)} if expand else None
+        return self._client.request("GET", f"/templates/{template_id}/", params=params)
+
+    def delete(self, template_id: str) -> None:
+        self._client.request("DELETE", f"/templates/{template_id}/")
+
+    def add_document(
+        self,
+        template_id: str,
+        *,
+        file,
+        name: str | None = None,
+        content_type: str = "application/pdf",
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            f"/templates/{template_id}/documents/",
+            files={"file": _file_tuple(file, name, content_type)},
+        )
+
+    def add_role(
+        self,
+        template_id: str,
+        *,
+        key: str,
+        label: str = "",
+        order: int | None = None,
+        auth_methods: list[str] | None = None,
+    ) -> dict:
+        body: dict = {"key": key, "label": label}
+        if order is not None:
+            body["order"] = order
+        if auth_methods is not None:
+            body["auth_methods"] = auth_methods
+        return self._client.request("POST", f"/templates/{template_id}/roles/", json=body)
+
+    def add_field(
+        self,
+        template_id: str,
+        *,
+        document_id: str,
+        role: str,
+        kind: str = "signature",
+        page: int = 1,
+        x: float = 0,
+        y: float = 0,
+        width: float = 160,
+        height: float = 50,
+        anchor_text: str = "",
+        anchor_offset_x: float = 0,
+        anchor_offset_y: float = -55,
+    ) -> dict:
+        return self._client.request(
+            "POST",
+            f"/templates/{template_id}/fields/",
+            json={
+                "document_id": document_id,
+                "role": role,
+                "kind": kind,
+                "page": page,
+                "x": x,
+                "y": y,
+                "width": width,
+                "height": height,
+                "anchor_text": anchor_text,
+                "anchor_offset_x": anchor_offset_x,
+                "anchor_offset_y": anchor_offset_y,
+            },
+        )
+
+    def create_envelope(
+        self,
+        template_id: str,
+        *,
+        signers: dict[str, dict],
+        title: str = "",
+        metadata: dict | None = None,
+        variables: dict | None = None,
+        send: bool = False,
+        expires_in_days: int | None = None,
+        deliver_emails: bool = True,
+        language: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """The one-call automation flow (§10.4): instantiate and optionally
+        send, getting each signer's sign_url back for embedded flows.
+        `variables` fills the tokens of authored documents; `language` picks
+        the source or an approved translation."""
+        body: dict = {
+            "signers": signers,
+            "title": title,
+            "metadata": metadata or {},
+            "variables": variables or {},
+            "send": send,
+            "deliver_emails": deliver_emails,
+        }
+        if language is not None:
+            body["language"] = language
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        return self._client.request(
+            "POST",
+            f"/templates/{template_id}/envelopes/",
+            json=body,
+            idempotency_key=idempotency_key,
+        )
+
+
+class Webhooks(_Resource):
+    def create(
+        self, *, url: str, event_types: list[str] | None = None, description: str = ""
+    ) -> dict:
+        """The response includes `secret` (whsec_…) ONCE — store it now."""
+        return self._client.request(
+            "POST",
+            "/webhooks/",
+            json={"url": url, "event_types": event_types or [], "description": description},
+        )
+
+    def list(self, *, limit: int | None = None, cursor: str | None = None) -> dict:
+        params = {k: v for k, v in {"limit": limit, "cursor": cursor}.items() if v}
+        return self._client.request("GET", "/webhooks/", params=params)
+
+    def delete(self, endpoint_id: str) -> None:
+        self._client.request("DELETE", f"/webhooks/{endpoint_id}/")
+
+    def redeliver(self, delivery_id: str) -> dict:
+        return self._client.request("POST", f"/webhooks/deliveries/{delivery_id}/redeliver/")
+
+
+class Events(_Resource):
+    """The consultable event log — reconciliation source when a webhook is
+    lost (poll `list` and compare against what you received)."""
+
+    def list(
+        self,
+        *,
+        type: str | None = None,
+        envelope_id: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict:
+        params = {
+            k: v
+            for k, v in {
+                "type": type,
+                "envelope_id": envelope_id,
+                "limit": limit,
+                "cursor": cursor,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("GET", "/events/", params=params)
+
+    def auto_paging_iter(self, *, type: str | None = None):
+        params = {"type": type} if type else {}
+        return self._auto_paging("/events/", **params)
+
+
+class Organization(_Resource):
+    def get(self) -> dict:
+        """Org info including plan limits and features."""
+        return self._client.request("GET", "/organization/")
+
+
+class Members(_Resource):
+    def list(self) -> dict:
+        return self._client.request("GET", "/members/")
+
+    def change_role(self, membership_id: str, *, role: str) -> dict:
+        return self._client.request("PATCH", f"/members/{membership_id}/", json={"role": role})
+
+    def remove(self, membership_id: str) -> None:
+        self._client.request("DELETE", f"/members/{membership_id}/")
+
+
+class Invitations(_Resource):
+    def create(self, *, email: str, role: str = "member", deliver_email: bool = True) -> dict:
+        """The response includes `accept_url` ONCE, at creation."""
+        return self._client.request(
+            "POST",
+            "/invitations/",
+            json={"email": email, "role": role, "deliver_email": deliver_email},
+        )
+
+    def list(
+        self, *, status: str | None = None, limit: int | None = None, cursor: str | None = None
+    ) -> dict:
+        params = {
+            k: v
+            for k, v in {
+                "status": status,
+                "limit": limit,
+                "cursor": cursor,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("GET", "/invitations/", params=params)
+
+    def cancel(self, invite_id: str) -> None:
+        self._client.request("DELETE", f"/invitations/{invite_id}/")

easycontract/webhooks.py

@@ -0,0 +1,72 @@
+"""Receiver-side webhook signature verification.
+
+easycontract signs every delivery with
+
+    X-EasyContract-Signature: t=<unix>,v1=<hex>
+
+where v1 = HMAC-SHA256(secret, f"{t}.{body}"). Verify with your endpoint's
+whsec_… secret (shown once at creation):
+
+    event = easycontract.webhooks.verify_signature(
+        payload=request.body, header=request.headers["X-EasyContract-Signature"],
+        secret=WEBHOOK_SECRET,
+    )
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+
+from .errors import SignatureVerificationError
+
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def verify_signature(
+    *,
+    payload: bytes | str,
+    header: str,
+    secret: bytes | str,
+    tolerance: int | None = DEFAULT_TOLERANCE_SECONDS,
+) -> dict:
+    """Verify a delivery and return the parsed event. Raises
+    SignatureVerificationError on ANY problem (never a raw parse/decode
+    exception).
+
+    `tolerance` is the allowed clock skew in seconds. Pass None to skip the
+    timestamp check entirely (not recommended: it disables replay
+    protection).
+    """
+    if not isinstance(header, str):
+        raise SignatureVerificationError("malformed signature header")
+
+    # Verify over the RAW bytes: nothing is decoded or parsed before the HMAC
+    # check passes, so hostile input can only ever produce our own exception.
+    if isinstance(payload, (bytes, bytearray)):
+        body = bytes(payload)
+    elif isinstance(payload, str):
+        body = payload.encode("utf-8")
+    else:
+        raise SignatureVerificationError("payload must be bytes or str")
+    secret_bytes = secret if isinstance(secret, (bytes, bytearray)) else str(secret).encode("utf-8")
+
+    try:
+        parts = dict(part.split("=", 1) for part in header.split(","))
+        timestamp = int(parts["t"])
+        signature = parts["v1"]
+    except (ValueError, KeyError) as exc:
+        raise SignatureVerificationError("malformed signature header") from exc
+
+    if tolerance is not None and abs(time.time() - timestamp) > tolerance:
+        raise SignatureVerificationError("timestamp outside tolerance (possible replay)")
+
+    expected = hmac.new(secret_bytes, b"%d." % timestamp + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected.encode(), signature.encode()):
+        raise SignatureVerificationError("signature mismatch")
+    try:
+        return json.loads(body.decode("utf-8"))
+    except ValueError as exc:  # UnicodeDecodeError is a ValueError too
+        raise SignatureVerificationError("payload is not valid JSON") from exc

easycontract-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: easycontract
+Version: 0.1.0
+Summary: SDK oficial de Python para el API de easycontract (firma electrónica eIDAS)
+Project-URL: Documentation, https://easycontract.online/docs/api
+Author-email: Román Ramírez <roman@easycontract.online>
+License-Expression: LicenseRef-easycontract-proprietary
+License-File: LICENSE.txt
+Keywords: audit-trail,contract,e-signature,eidas,esign,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: requests<3,>=2.31
+Description-Content-Type: text/markdown
+
+# easycontract — SDK de Python
+
+SDK oficial del API de firma electrónica de easycontract (SES/AdES bajo eIDAS,
+con paquete de evidencias defendible en litigio).
+
+```bash
+pip install easycontract
+```
+
+```python
+from easycontract import EasyContract
+
+client = EasyContract(api_key="ec_test_...")  # ec_live_... en producción
+print(client.whoami())
+```
+
+- **Modo test de primera clase**: una clave `ec_test_…` opera sobre datos
+  aislados (TSA/PAdES simulados). Nadie debería firmar un documento real para
+  probar la integración.
+- **Idempotencia automática**: todo POST lleva `Idempotency-Key` (uuid4);
+  pásala tú misma para reintentos seguros de tu lado.
+- **Reintentos**: 429 (respetando `Retry-After`) y 5xx en GETs.
+- **Errores tipados** con el `code` estable del API:
+  `AuthenticationError`, `RateLimitError`, `ForbiddenError` (cuota/feature/
+  regla de membresía), `InvalidRequestError`, `NotFoundError`,
+  `ConflictError`, `ServerError`.
+
+---
+
+## Receta 1 — Enviar un envelope desde plantilla (el flujo RootedCON)
+
+Una sola llamada: cubre los roles, envía, y recibe los enlaces de firma.
+
+```python
+result = client.templates.create_envelope(
+    template_id,
+    signers={"ponente": {"full_name": "Ada Lovelace", "email": "ada@example.com"}},
+    title="Contrato ponencia RootedCON 2027 — Ada Lovelace",
+    send=True,  # congela hashes, plan y retención, y acuña enlaces
+    deliver_emails=True,  # easycontract envía los emails con los enlaces
+)
+envelope_id = result["envelope"]["id"]
+```
+
+Creación de la plantilla (una vez):
+
+```python
+template = client.templates.create(name="Contrato ponente", retention_period_months=72)
+doc = client.templates.add_document(template["id"], file="contrato-ponente.pdf")
+client.templates.add_role(template["id"], key="ponente", label="Ponente")
+client.templates.add_field(
+    template["id"],
+    document_id=doc["id"],
+    role="ponente",
+    anchor_text="Fdo. el ponente:",  # la firma se estampa donde el PDF lo dice
+)
+```
+
+## Receta 2 — Firma embebida (embedded signing)
+
+Con `deliver_emails=False` recibes el `sign_url` de un solo uso por firmante y
+lo integras en tu propia aplicación (redirect o iframe):
+
+```python
+result = client.templates.create_envelope(
+    template_id,
+    signers={...},
+    send=True,
+    deliver_emails=False,
+)
+sign_url = result["signers"][0]["sign_url"]
+# → redirige al ponente a sign_url sin salir de tu flujo
+```
+
+El enlace es personal, caduca (14 días por defecto, `expires_in_days` para
+cambiarlo) y queda invalidado al firmar o rechazar.
+
+## Receta 3 — Webhooks vs. polling
+
+**Webhooks** (recomendado): registra un endpoint y verifica CADA entrega.
+
+```python
+endpoint = client.webhooks.create(url="https://miapp.com/hooks/easycontract")
+WEBHOOK_SECRET = endpoint["secret"]  # whsec_… — se muestra UNA sola vez
+
+# En tu receptor (Django/Flask/FastAPI):
+from easycontract import webhooks
+
+event = webhooks.verify_signature(
+    payload=request.body,
+    header=request.headers["X-EasyContract-Signature"],
+    secret=WEBHOOK_SECRET,
+)
+if event["type"] == "envelope.completed":
+    ...
+```
+
+**Reconciliación / polling**: los webhooks son la proyección de un event log
+consultable; si pierdes una entrega, reconcilia:
+
+```python
+for event in client.events.auto_paging_iter(type="envelope.completed"):
+    ...
+```
+
+## Receta 4 — Descargar el paquete de evidencias
+
+El ZIP completo (documentos, certificado, audit trail JSON verificable
+offline, sellos TSA) — lo que un tenant llevaría a un juzgado:
+
+```python
+client.envelopes.download_evidence(envelope_id, to="evidencias.zip")
+client.envelopes.download_certificate(envelope_id, to="certificado.pdf")
+```
+
+## Receta 5 — Gestión de plantillas
+
+```python
+for template in client.templates.list()["data"]:
+    print(template["name"])
+
+detail = client.templates.get(template_id, expand=["documents", "roles", "fields"])
+client.templates.delete(old_template_id)
+```
+
+---
+
+## Envelope manual (sin plantilla)
+
+```python
+envelope = client.envelopes.create(
+    title="NDA",
+    retention_period_months=60,  # retención SIEMPRE explícita
+)
+client.envelopes.add_document(envelope["id"], file="nda.pdf")
+client.envelopes.add_signer(
+    envelope["id"],
+    full_name="Grace Hopper",
+    email="grace@example.com",
+    auth_methods=["email_link", "sms_otp"],
+    phone="+34600111222",  # OTP: plan Pro+
+)
+sent = client.envelopes.send(envelope["id"])
+```
+
+## Organización, miembros e invitaciones
+
+```python
+org = client.organization.get()  # plan, límites y features del plan
+members = client.members.list()
+invite = client.invitations.create(email="colega@example.com", role="member")
+# invite["accept_url"] — entrégalo tú o deja que easycontract lo envíe por email
+```

easycontract-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+easycontract/__init__.py,sha256=QUYWwECa8TWCBaNQXg1LWZIiLG4TZkUZJqg_TWe__Ds,835
+easycontract/client.py,sha256=geTUooai3vrsLCBKOJFi_AuPCI1MwmsTo04EtFqTUXM,7102
+easycontract/errors.py,sha256=6YTbJ5hlQKYCFLINznyqT0zlieyjTF82eaYxkOSkomY,2388
+easycontract/resources.py,sha256=Ahl5IhmH1deWturaJxg4Rckf6gXN9oNV1xAfi3ZO5KI,23944
+easycontract/webhooks.py,sha256=f03kjRFJu14eIdKn4iV4p1aYQSX-dOT8XiPaIKeSJLU,2557
+easycontract-0.1.0.dist-info/METADATA,sha256=AmY_Q3w7a0UQSsttbr5V73-DVuyaoV-fptEiNw9wK-s,5740
+easycontract-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+easycontract-0.1.0.dist-info/licenses/LICENSE.txt,sha256=7L_OK7dZHSR7Rw4Q8MmAgBEFl_Gfm51ji4-TNWRXjD0,874
+easycontract-0.1.0.dist-info/RECORD,,

easycontract-0.1.0.dist-info/WHEEL

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

easycontract-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,18 @@
+easycontract Python SDK
+
+Copyright (c) 2026 Román Ramírez — roman@easycontract.online
+
+Proprietary. All rights reserved.
+
+This software and its documentation are proprietary to easycontract. No
+rights are granted to use, modify, reproduce, distribute, or create
+derivative works of this software, except as expressly agreed in writing
+with easycontract (for example, under an applicable customer agreement).
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.