easycontract 0.1.1__tar.gz → 0.1.7__tar.gz

{easycontract-0.1.1 → easycontract-0.1.7}/CHANGELOG.md

@@ -2,6 +2,132 @@
 
 All notable changes to the `easycontract` Python SDK.
 
+## 0.1.7 (2026-11-10)
+
+**Features**
+
+- Template versioning: envelopes are created from the latest APPROVED
+  version of a template, never from its draft.
+  `client.templates.list_versions/approve_version/get_version`;
+  `create_envelope` on a template with no approved version raises the
+  `template_not_approved` error (409). Templates and envelopes carry the
+  version (`current_version`, `envelope["template"]["version"]`).
+- `client.templates.update_role` (a new key rewrites the role's tokens in
+  the documents; `adopt_tokens_of` gives a role the tokens of a key no role
+  has, listed in the template's `unknown_roles` with `expand=roles`) and
+  `client.templates.delete_role`.
+- `client.templates.set_margin_image` / `delete_margin_image`: a logo or
+  seal in the header or footer of an authored document (PNG, JPEG or WebP,
+  2 MB at most; `align` start, center or end). A new image is checked at
+  once (400 if refused), then waits for the malware scan before it is
+  published: the template document carries `header_image` /
+  `footer_image` (the published one: type, size, SHA-256, place) and
+  `header_image_upload` / `footer_image_upload` (one still in the scan, or
+  refused).
+- `client.templates.preview(technical=True)`: the technical view of the
+  template draft (every fillable field explained, highlighted in the
+  documents with example values and how the API passes each one).
+- `client.templates.compare_versions` (what changed between two versions,
+  or a version and the draft) and `client.templates.restore_version` (copy
+  an earlier version into the draft; approving it makes a new version).
+- `client.organization.group()`: the organization group (Enterprise,
+  read only), its members and the invitations received; `features` gains
+  `organization_groups`. `client.organization.group_templates()` and
+  `copy_group_template()`: templates the other organizations of the group
+  offer, copied as a draft of your own; `templates.update(group_shared=...)`
+  offers one, and templates carry `group_shared` and `copied_from`.
+  A copy follows its source: `client.templates.upstream()` (newer approved
+  version?), `compare_upstream()` and `pull_upstream()` (into the draft);
+  `templates.update(follow_updates=...)` switches the e-mail notices.
+- Attention points in other languages: `client.templates.list_attention_translations`,
+  `get_attention_translation`, `set_attention_translation` (drafts),
+  `delete_attention_translation` and `autotranslate_attention_points` (a
+  machine draft; a document's autotranslation drafts them too). Template
+  points carry `translations` (status per language), translation jobs
+  carry `scope`, and the version comparison `attention_point_translations`.
+  A template is usable in a language only when its attention points are
+  approved in it too (approval stays in the panel).
+- `templates.request_countersign_authorization(scope=...)`: `"version"`
+  (default) or `"future_versions"` (the authorization also covers the
+  versions approved later). Authorizations carry `template_version` and
+  `scope`.
+
+## 0.1.6 (2026-11-08)
+
+**Features**
+
+- Attention points: parts of the contract the signer must notice, shown on
+  the signing page before the documents (never stamped in the PDF).
+  `client.templates.list_attention_points/add_attention_point/
+  update_attention_point/delete_attention_point` (the defaults of every
+  envelope created from the template) and the same four on
+  `client.envelopes` (draft envelopes; on one created from a template, Pro
+  and Enterprise). `requires_ack=True` makes the signer confirm it before
+  signing. `templates.create_envelope(attention_points=[…])` replaces the
+  template's for that envelope only (Pro and Enterprise).
+
+## 0.1.5 (2026-10-23)
+
+**Features**
+
+- Automatic countersignature of the organization (Pro+):
+  `client.templates.request_countersign_authorization(template_id,
+  authorizer_email=…, authorizer_title=…, valid_until="YYYY-MM-DD",
+  max_uses=None, variables={…})` (the authorizer signs it by e-mail),
+  `client.templates.list_countersign_authorizations`,
+  `client.countersign_authorizations.list/get/revoke`,
+  `client.envelopes.retry_countersign` and
+  `client.envelopes.skip_countersign(reason=…)`. `templates.create_envelope`
+  accepts `countersign="none"`; envelopes carry `countersign`.
+
+## 0.1.4 (2026-10-20)
+
+**Features**
+
+- Projects (paid plans): `client.projects.list/create/get/update`. An
+  organization key sees everything; a project key only its project.
+  `project=` on `envelopes.create`, `envelopes.list`, `templates.create_envelope`
+  and `webhooks.create` (organization keys only). `client.whoami()` now returns
+  `project` (null = organization key) and `key`.
+- Webhooks: `client.webhooks.get`, `update` (url, event_types, is_active,
+  description) and `rotate_secret(grace_period_hours=24)`, which returns the
+  new `secret` once.
+
+**Fixes**
+
+- `easycontract.webhooks.verify_signature` accepts ANY `v1=` in the header
+  and `secret` may be a list: after a rotation, during the grace period,
+  deliveries carry `v1=<new>,v1=<old>`. 0.1.3 and earlier only checked the
+  last `v1` (the old secret), so they failed once you switched to the new one
+  before the grace period ended.
+
+## 0.1.3 (2026-10-20)
+
+**Features**
+
+- Cryptographic restrictions: `client.organization.update(seal_profile=
+  "hybrid" | "classic", acknowledge=True)` chooses how the platform seals
+  the certificate, the final PDFs and the evidence package (hybrid ECDSA +
+  ML-DSA-87, or ECDSA only). `client.organization.get()["cryptography"]`
+  shows the choice and what each option implies; every envelope reports the
+  profile frozen at send in `seal_profile`.
+- The evidence package (`client.envelopes.download_evidence(...)`) is now an ASiC-E
+  container (still a `.zip`) signed by the platform.
+
+## 0.1.2 (2026-10-19)
+
+**Features**
+
+- Machine-drafted template translations: `client.templates.autotranslate(
+  template_id, document_id, language, acknowledge=True)` queues a draft made
+  by the platform's translators and reviewed by a panel with quorum;
+  `client.templates.get_translation_job(job_id)` returns its progress,
+  `verdict` (`consensus`, `quorum`, `no_quorum`, `unreviewed`, `simulated`)
+  and the reviewers' notes with English back-translations. The result is
+  always a draft that a person approves in the panel.
+- The platform now has 16 languages (es, en, ca, gl, eu, ast, an, oc, pt, fr,
+  it, de, ru, zh-hans, ar, he) for `language` everywhere.
+
 ## 0.1.1 (2026-10-07)
 
 **Security (audit 2026-10-07)**

{easycontract-0.1.1 → easycontract-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: easycontract
-Version: 0.1.1
+Version: 0.1.7
 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>

{easycontract-0.1.1 → easycontract-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "easycontract"
-version = "0.1.1"
+version = "0.1.7"
 description = "SDK oficial de Python para el API de easycontract (firma electrónica eIDAS)"
 readme = "README.md"
 requires-python = ">=3.10"

{easycontract-0.1.1 → easycontract-0.1.7}/src/easycontract/__init__.py

@@ -6,7 +6,7 @@ client = EasyContract(api_key="ec_test_...")
 envelope = client.envelopes.create(title="Contrato", retention_period_months=72)
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.7"
 
 from . import webhooks
 from .client import EasyContract

{easycontract-0.1.1 → easycontract-0.1.7}/src/easycontract/client.py

@@ -23,12 +23,14 @@ import requests
 from . import __version__
 from .errors import APIError, error_from_response
 from .resources import (
+    CountersignAuthorizations,
     Envelopes,
     Events,
     Identity,
     Invitations,
     Members,
     Organization,
+    Projects,
     Retention,
     Templates,
     Webhooks,
@@ -108,7 +110,9 @@ class EasyContract:
         self.identity = Identity(self)
         self.retention = Retention(self)
         self.templates = Templates(self)
+        self.countersign_authorizations = CountersignAuthorizations(self)
         self.webhooks = Webhooks(self)
+        self.projects = Projects(self)
         self.events = Events(self)
         self.organization = Organization(self)
         self.members = Members(self)

{easycontract-0.1.1 → easycontract-0.1.7}/src/easycontract/resources.py

@@ -14,6 +14,15 @@ from urllib.parse import quote
 from .errors import EasyContractError
 
 
+def _attention_body(title, body, document_id, page, requires_ack) -> dict:
+    payload: dict = {"title": title, "body": body, "requires_ack": requires_ack}
+    if document_id is not None:
+        payload["document_id"] = document_id
+    if page is not None:
+        payload["page"] = page
+    return payload
+
+
 def _id(value) -> str:
     """A resource identifier as a path segment: it must be a UUID (every
     resource id of the API is). Anything else — "../webhooks/x", "a?b",
@@ -38,6 +47,12 @@ def _seg(value) -> str:
 OPERATIONS: dict[tuple[str, str], str] = {
     ("GET", "/whoami/"): "client.whoami",
     ("GET", "/organization/"): "client.organization.get",
+    ("GET", "/organization/group/"): "client.organization.group",
+    ("GET", "/organization/group/templates/"): "client.organization.group_templates",
+    (
+        "POST",
+        "/organization/group/templates/{template_id}/copy/",
+    ): "client.organization.copy_group_template",
     ("GET", "/members/"): "client.members.list",
     ("PATCH", "/members/{membership_id}/"): "client.members.change_role",
     ("DELETE", "/members/{membership_id}/"): "client.members.remove",
@@ -59,6 +74,31 @@ OPERATIONS: dict[tuple[str, str], str] = {
         "/envelopes/{envelope_id}/signers/{signer_id}/embedded-session/",
     ): "client.envelopes.create_embedded_session",
     ("POST", "/envelopes/{envelope_id}/void/"): "client.envelopes.void",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/countersign/retry/",
+    ): "client.envelopes.retry_countersign",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/countersign/skip/",
+    ): "client.envelopes.skip_countersign",
+    ("GET", "/countersign-authorizations/"): "client.countersign_authorizations.list",
+    (
+        "GET",
+        "/countersign-authorizations/{authorization_id}/",
+    ): "client.countersign_authorizations.get",
+    (
+        "POST",
+        "/countersign-authorizations/{authorization_id}/revoke/",
+    ): "client.countersign_authorizations.revoke",
+    (
+        "GET",
+        "/templates/{template_id}/countersign-authorizations/",
+    ): "client.templates.list_countersign_authorizations",
+    (
+        "POST",
+        "/templates/{template_id}/countersign-authorizations/",
+    ): "client.templates.request_countersign_authorization",
     ("GET", "/envelopes/{envelope_id}/certificate/"): "client.envelopes.download_certificate",
     (
         "POST",
@@ -135,15 +175,103 @@ OPERATIONS: dict[tuple[str, str], str] = {
         "DELETE",
         "/templates/{template_id}/documents/{document_id}/translations/{language}/",
     ): "client.templates.delete_translation",
+    (
+        "POST",
+        "/templates/{template_id}/documents/{document_id}/translations/{language}/autotranslate/",
+    ): "client.templates.autotranslate",
+    ("GET", "/translation-jobs/{job_id}/"): "client.templates.get_translation_job",
     ("POST", "/templates/{template_id}/preview/"): "client.templates.preview",
+    (
+        "POST",
+        "/templates/{template_id}/documents/{document_id}/margin-images/{slot}/",
+    ): "client.templates.set_margin_image",
+    (
+        "DELETE",
+        "/templates/{template_id}/documents/{document_id}/margin-images/{slot}/",
+    ): "client.templates.delete_margin_image",
     ("POST", "/templates/{template_id}/duplicate/"): "client.templates.duplicate",
     ("POST", "/templates/{template_id}/roles/"): "client.templates.add_role",
+    ("PATCH", "/templates/{template_id}/roles/{role_id}/"): "client.templates.update_role",
+    ("DELETE", "/templates/{template_id}/roles/{role_id}/"): "client.templates.delete_role",
+    ("GET", "/templates/{template_id}/versions/"): "client.templates.list_versions",
+    ("POST", "/templates/{template_id}/versions/"): "client.templates.approve_version",
+    ("GET", "/templates/{template_id}/versions/{number}/"): "client.templates.get_version",
+    ("GET", "/templates/{template_id}/versions/compare/"): "client.templates.compare_versions",
+    (
+        "POST",
+        "/templates/{template_id}/versions/{number}/restore/",
+    ): "client.templates.restore_version",
     ("POST", "/templates/{template_id}/fields/"): "client.templates.add_field",
+    ("GET", "/templates/{template_id}/upstream/"): "client.templates.upstream",
+    (
+        "GET",
+        "/templates/{template_id}/upstream/compare/",
+    ): "client.templates.compare_upstream",
+    ("POST", "/templates/{template_id}/upstream/pull/"): "client.templates.pull_upstream",
+    (
+        "GET",
+        "/templates/{template_id}/attention-points/",
+    ): "client.templates.list_attention_points",
+    (
+        "POST",
+        "/templates/{template_id}/attention-points/",
+    ): "client.templates.add_attention_point",
+    (
+        "PATCH",
+        "/templates/{template_id}/attention-points/{point_id}/",
+    ): "client.templates.update_attention_point",
+    (
+        "DELETE",
+        "/templates/{template_id}/attention-points/{point_id}/",
+    ): "client.templates.delete_attention_point",
+    (
+        "GET",
+        "/templates/{template_id}/attention-points/translations/",
+    ): "client.templates.list_attention_translations",
+    (
+        "GET",
+        "/templates/{template_id}/attention-points/translations/{language}/",
+    ): "client.templates.get_attention_translation",
+    (
+        "PUT",
+        "/templates/{template_id}/attention-points/translations/{language}/",
+    ): "client.templates.set_attention_translation",
+    (
+        "DELETE",
+        "/templates/{template_id}/attention-points/translations/{language}/",
+    ): "client.templates.delete_attention_translation",
+    (
+        "POST",
+        "/templates/{template_id}/attention-points/translations/{language}/autotranslate/",
+    ): "client.templates.autotranslate_attention_points",
+    (
+        "GET",
+        "/envelopes/{envelope_id}/attention-points/",
+    ): "client.envelopes.list_attention_points",
+    (
+        "POST",
+        "/envelopes/{envelope_id}/attention-points/",
+    ): "client.envelopes.add_attention_point",
+    (
+        "PATCH",
+        "/envelopes/{envelope_id}/attention-points/{point_id}/",
+    ): "client.envelopes.update_attention_point",
+    (
+        "DELETE",
+        "/envelopes/{envelope_id}/attention-points/{point_id}/",
+    ): "client.envelopes.delete_attention_point",
     ("POST", "/templates/{template_id}/envelopes/"): "client.templates.create_envelope",
     ("GET", "/events/"): "client.events.list",
     ("GET", "/webhooks/"): "client.webhooks.list",
     ("POST", "/webhooks/"): "client.webhooks.create",
+    ("GET", "/webhooks/{endpoint_id}/"): "client.webhooks.get",
+    ("PATCH", "/webhooks/{endpoint_id}/"): "client.webhooks.update",
     ("DELETE", "/webhooks/{endpoint_id}/"): "client.webhooks.delete",
+    ("POST", "/webhooks/{endpoint_id}/rotate-secret/"): "client.webhooks.rotate_secret",
+    ("GET", "/projects/"): "client.projects.list",
+    ("POST", "/projects/"): "client.projects.create",
+    ("GET", "/projects/{project_id}/"): "client.projects.get",
+    ("PATCH", "/projects/{project_id}/"): "client.projects.update",
     ("POST", "/webhooks/deliveries/{delivery_id}/redeliver/"): "client.webhooks.redeliver",
 }
 
@@ -161,6 +289,36 @@ def _file_tuple(file, name: str | None, content_type: str = "application/pdf"):
     return (name or getattr(file, "name", "document.pdf"), file, content_type)
 
 
+def _image_mime(file, name: str | None) -> str:
+    """Content type of an image upload, from its first bytes when it can be
+    read without consuming it, else from the file name (the server decides
+    anyway: it decodes and re-encodes every image)."""
+    head = b""
+    if isinstance(file, bytes):
+        head = file[:12]
+    elif isinstance(file, (str, Path)):
+        with Path(file).open("rb") as fh:
+            head = fh.read(12)
+    if head.startswith(b"\x89PNG"):
+        return "image/png"
+    if head.startswith(b"\xff\xd8"):
+        return "image/jpeg"
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "image/webp"
+    if name:
+        label = name
+    elif isinstance(file, (str, Path)):
+        label = str(file)
+    else:
+        label = str(getattr(file, "name", "") or "")
+    lower = label.lower()
+    if lower.endswith((".jpg", ".jpeg")):
+        return "image/jpeg"
+    if lower.endswith(".webp"):
+        return "image/webp"
+    return "image/png"
+
+
 class _Resource:
     def __init__(self, client):
         self._client = client
@@ -198,9 +356,12 @@ class Envelopes(_Resource):
         biometrics: bool = False,
         document_type: str | None = None,
         kyc_images_retention: str | None = None,
+        project: str | None = None,
         idempotency_key: str | None = None,
     ) -> dict:
-        """`biometrics=True` offers signers the OPTIONAL stroke capture (only
+        """`project` (organization keys only): create inside that project; a
+        project key always creates in its own.
+        `biometrics=True` offers signers the OPTIONAL stroke capture (only
         effective when the organization enabled it: Enterprise + DPIA).
         `document_type` is a key of `client.retention.document_types()`.
         `kyc_images_retention`: "after_review" (default) or
@@ -220,17 +381,25 @@ class Envelopes(_Resource):
             body["document_type"] = document_type
         if kyc_images_retention:
             body["kyc_images_retention"] = kyc_images_retention
+        if project:
+            body["project"] = project
         return self._client.request(
             "POST", "/envelopes/", json=body, idempotency_key=idempotency_key
         )
 
     def list(
-        self, *, status: str | None = None, limit: int | None = None, cursor: str | None = None
+        self,
+        *,
+        status: str | None = None,
+        project: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
     ) -> dict:
         params = {
             k: v
             for k, v in {
                 "status": status,
+                "project": project,
                 "limit": limit,
                 "cursor": cursor,
             }.items()
@@ -349,11 +518,64 @@ class Envelopes(_Resource):
     def release_legal_hold(self, envelope_id: str) -> dict:
         return self._client.request("DELETE", f"/envelopes/{_id(envelope_id)}/legal-hold/")
 
+    def list_attention_points(self, envelope_id: str) -> dict:
+        """Attention points shown to the signers before the documents, with
+        who confirmed each one."""
+        return self._client.request("GET", f"/envelopes/{_id(envelope_id)}/attention-points/")
+
+    def add_attention_point(
+        self,
+        envelope_id: str,
+        *,
+        title: str,
+        body: str = "",
+        document_id: str | None = None,
+        page: int | None = None,
+        requires_ack: bool = False,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Draft envelopes only. On an envelope created from a template it is
+        Pro and Enterprise (403 feature_not_available otherwise)."""
+        return self._client.request(
+            "POST",
+            f"/envelopes/{_id(envelope_id)}/attention-points/",
+            json=_attention_body(title, body, document_id, page, requires_ack),
+            idempotency_key=idempotency_key,
+        )
+
+    def update_attention_point(self, envelope_id: str, point_id: str, **changes) -> dict:
+        """title, body, document_id, page, requires_ack (drafts only)."""
+        return self._client.request(
+            "PATCH",
+            f"/envelopes/{_id(envelope_id)}/attention-points/{_id(point_id)}/",
+            json=changes,
+        )
+
+    def delete_attention_point(self, envelope_id: str, point_id: str):
+        return self._client.request(
+            "DELETE", f"/envelopes/{_id(envelope_id)}/attention-points/{_id(point_id)}/"
+        )
+
     def void(self, envelope_id: str, *, reason: str = "") -> dict:
         return self._client.request(
             "POST", f"/envelopes/{_id(envelope_id)}/void/", json={"reason": reason}
         )
 
+    def retry_countersign(self, envelope_id: str) -> dict:
+        """Signed by everybody and waiting (countersign.status == "failed"):
+        try the organization's countersignature again, e.g. after a new
+        authorization was signed."""
+        return self._client.request("POST", f"/envelopes/{_id(envelope_id)}/countersign/retry/")
+
+    def skip_countersign(self, envelope_id: str, *, reason: str) -> dict:
+        """Complete it WITHOUT the organization's countersignature (the
+        reason is required and stated in the certificate)."""
+        return self._client.request(
+            "POST",
+            f"/envelopes/{_id(envelope_id)}/countersign/skip/",
+            json={"reason": reason},
+        )
+
     def download_certificate(self, envelope_id: str, *, to: str | Path | None = None) -> bytes:
         content = self._client.request(
             "GET", f"/envelopes/{_id(envelope_id)}/certificate/", raw=True
@@ -402,7 +624,9 @@ class Envelopes(_Resource):
         include_biometrics: bool = False,
         include_identity_proofs: bool = False,
     ) -> bytes:
-        """The full evidence ZIP — what a tenant would take to court."""
+        """The full evidence ZIP — what a tenant would take to court. With the
+        platform seal on, it is an ASiC-E container signed by the platform
+        (manifest.json → `container` describes it)."""
         content = self._client.request(
             "GET",
             f"/envelopes/{_id(envelope_id)}/evidence/",
@@ -450,7 +674,9 @@ class Templates(_Resource):
 
     def update(self, template_id: str, **changes) -> dict:
         """PATCH settings: name, description, signing_order,
-        retention_period_months, variables (schema list), metadata."""
+        retention_period_months, variables (schema list), metadata,
+        group_shared (offer it to the organization group), follow_updates
+        (a group copy: notices of the source's new versions)."""
         return self._client.request("PATCH", f"/templates/{_id(template_id)}/", json=changes)
 
     def catalog(self, *, language: str | None = None) -> dict:
@@ -578,6 +804,34 @@ class Templates(_Resource):
             f"/templates/{_id(template_id)}/documents/{_id(document_id)}/translations/{_seg(language)}/",
         )
 
+    def autotranslate(
+        self,
+        template_id: str,
+        document_id: str,
+        language: str,
+        *,
+        acknowledge: bool,
+        overwrite: bool = False,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Queue a MACHINE DRAFT of a language version: translators plus a
+        reviewer panel with quorum. Returns the job (202); poll
+        `get_translation_job`. `acknowledge=True` is required: the result is
+        a draft that a person reviews and approves in the panel. `overwrite`
+        replaces a translation that already has its own text."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/translations/{_seg(language)}/autotranslate/",
+            json={"acknowledge": acknowledge, "overwrite": overwrite},
+            idempotency_key=idempotency_key,
+        )
+
+    def get_translation_job(self, job_id: str) -> dict:
+        """Status of a machine translation: `verdict` (consensus, quorum,
+        no_quorum, unreviewed, simulated) and, when done, the reviewers'
+        `notes` with an English back-translation."""
+        return self._client.request("GET", f"/translation-jobs/{_id(job_id)}/")
+
     def download_docx(
         self, template_id: str, document_id: str, *, to: str | Path | None = None
     ) -> bytes:
@@ -600,6 +854,47 @@ class Templates(_Resource):
             data={"name": name} if name else None,
         )
 
+    def set_margin_image(
+        self,
+        template_id: str,
+        document_id: str,
+        slot: str,
+        *,
+        file=None,
+        align: str | None = None,
+        name: str | None = None,
+    ) -> dict:
+        """Put, replace or move the image of the ``slot`` margin (``"header"``
+        or ``"footer"``) of an authored document of the template draft: a
+        PNG, JPEG or WebP of 2 MB at most (``file``: path, bytes or file
+        object) and/or ``align`` (``"start"``, ``"center"``, ``"end"``).
+        A new image is published after its malware scan (see
+        ``header_image_upload`` / ``footer_image_upload`` in the returned
+        document); approving a new version then puts it in new envelopes."""
+        if slot not in ("header", "footer"):
+            raise ValueError("slot must be 'header' or 'footer'")
+        path = f"/templates/{_id(template_id)}/documents/{_id(document_id)}/margin-images/{slot}/"
+        if file is None:
+            if align is None:
+                raise ValueError("give file, align or both")
+            return self._client.request("POST", path, json={"align": align})
+        mime = _image_mime(file, name)
+        return self._client.request(
+            "POST",
+            path,
+            files={"file": _file_tuple(file, name or f"{slot}.{mime.split('/')[1]}", mime)},
+            data={"align": align} if align else None,
+        )
+
+    def delete_margin_image(self, template_id: str, document_id: str, slot: str) -> dict:
+        """Remove the image of the ``slot`` margin (``"header"`` or ``"footer"``)."""
+        if slot not in ("header", "footer"):
+            raise ValueError("slot must be 'header' or 'footer'")
+        return self._client.request(
+            "DELETE",
+            f"/templates/{_id(template_id)}/documents/{_id(document_id)}/margin-images/{slot}/",
+        )
+
     def preview(
         self,
         template_id: str,
@@ -609,11 +904,16 @@ class Templates(_Resource):
         signers: dict[str, dict] | None = None,
         title: str = "",
         language: str | None = None,
+        technical: bool = False,
         to: str | Path | None = None,
     ) -> bytes:
         """PDF preview of the authored documents (sample values where
-        none are given). Nothing is persisted."""
+        none are given). ``technical=True``: the technical view of the
+        draft instead (every fillable field explained, with examples and
+        how the API passes each one). Nothing is persisted."""
         body: dict = {"variables": variables or {}, "signers": signers or {}, "title": title}
+        if technical:
+            body["technical"] = True
         if document_id:
             body["document_id"] = document_id
         if language:
@@ -666,6 +966,186 @@ class Templates(_Resource):
             body["auth_methods"] = auth_methods
         return self._client.request("POST", f"/templates/{_id(template_id)}/roles/", json=body)
 
+    def update_role(
+        self,
+        template_id: str,
+        role_id: str,
+        *,
+        key: str | None = None,
+        label: str | None = None,
+        order: int | None = None,
+        auth_methods: list[str] | None = None,
+        adopt_tokens_of: str | None = None,
+    ) -> dict:
+        """Edit a role of the template draft. A new ``key`` rewrites the
+        role's tokens in every authored document and translation (changed
+        translations go back to draft); ``adopt_tokens_of`` gives the role
+        the tokens of a key no role has (``unknown_roles`` of the template
+        with ``expand=roles``); ``renamed_in`` says where."""
+        body: dict = {}
+        for name, value in (
+            ("key", key),
+            ("label", label),
+            ("order", order),
+            ("auth_methods", auth_methods),
+            ("adopt_tokens_of", adopt_tokens_of),
+        ):
+            if value is not None:
+                body[name] = value
+        return self._client.request(
+            "PATCH", f"/templates/{_id(template_id)}/roles/{_id(role_id)}/", json=body
+        )
+
+    def delete_role(self, template_id: str, role_id: str) -> None:
+        """Remove a role from the draft (refused while a document uses its tokens)."""
+        self._client.request("DELETE", f"/templates/{_id(template_id)}/roles/{_id(role_id)}/")
+
+    def list_versions(self, template_id: str) -> dict:
+        """Approved versions kept, newest first, plus ``current_version`` and
+        ``has_unapproved_changes`` (the draft differs from the version in use)."""
+        return self._client.request("GET", f"/templates/{_id(template_id)}/versions/")
+
+    def approve_version(
+        self, template_id: str, *, note: str = "", idempotency_key: str | None = None
+    ) -> dict:
+        """Approve the draft as the next version: envelopes created from now
+        on use it. Raises on 409 ``template_unchanged`` when nothing changed."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/versions/",
+            json={"note": note} if note else {},
+            idempotency_key=idempotency_key,
+        )
+
+    def compare_versions(
+        self, template_id: str, *, from_: int | str | None = None, to: int | str = "draft"
+    ) -> dict:
+        """What changed from ``from_`` to ``to`` (a version number or
+        ``"draft"``). Default: from the version in use to the draft."""
+        params: dict = {"to": str(to)}
+        if from_ is not None:
+            params["from"] = str(from_)
+        return self._client.request(
+            "GET", f"/templates/{_id(template_id)}/versions/compare/", params=params
+        )
+
+    def restore_version(
+        self, template_id: str, number: int, *, idempotency_key: str | None = None
+    ) -> dict:
+        """Copy version ``number`` into the draft (unapproved draft work is
+        lost). Approve the draft afterwards: it becomes a new version."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/versions/{int(number)}/restore/",
+            idempotency_key=idempotency_key,
+        )
+
+    def get_version(self, template_id: str, number: int) -> dict:
+        return self._client.request("GET", f"/templates/{_id(template_id)}/versions/{int(number)}/")
+
+    def list_attention_points(self, template_id: str) -> dict:
+        return self._client.request("GET", f"/templates/{_id(template_id)}/attention-points/")
+
+    def add_attention_point(
+        self,
+        template_id: str,
+        *,
+        title: str,
+        body: str = "",
+        document_id: str | None = None,
+        page: int | None = None,
+        requires_ack: bool = False,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Default attention point of every envelope created from the template."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/attention-points/",
+            json=_attention_body(title, body, document_id, page, requires_ack),
+            idempotency_key=idempotency_key,
+        )
+
+    def update_attention_point(self, template_id: str, point_id: str, **changes) -> dict:
+        """title, body, document_id, page, requires_ack."""
+        return self._client.request(
+            "PATCH",
+            f"/templates/{_id(template_id)}/attention-points/{_id(point_id)}/",
+            json=changes,
+        )
+
+    def delete_attention_point(self, template_id: str, point_id: str):
+        return self._client.request(
+            "DELETE", f"/templates/{_id(template_id)}/attention-points/{_id(point_id)}/"
+        )
+
+    def upstream(self, template_id: str) -> dict:
+        """A copy of a group template: its source and whether it has a newer
+        approved version (`update_available`)."""
+        return self._client.request("GET", f"/templates/{_id(template_id)}/upstream/")
+
+    def compare_upstream(self, template_id: str) -> dict:
+        """What pulling the source's latest approved version would change."""
+        return self._client.request("GET", f"/templates/{_id(template_id)}/upstream/compare/")
+
+    def pull_upstream(self, template_id: str, *, idempotency_key: str | None = None) -> dict:
+        """The source's latest approved version replaces the copy's draft
+        (translations as drafts); approve the draft to use it."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/upstream/pull/",
+            json={},
+            idempotency_key=idempotency_key,
+        )
+
+    def list_attention_translations(self, template_id: str) -> dict:
+        """Per language: how many attention points are approved, stale, draft
+        or missing. `complete` = usable for envelopes in that language."""
+        return self._client.request(
+            "GET", f"/templates/{_id(template_id)}/attention-points/translations/"
+        )
+
+    def get_attention_translation(self, template_id: str, language: str) -> dict:
+        """The attention points in one language, with their source text."""
+        return self._client.request(
+            "GET", f"/templates/{_id(template_id)}/attention-points/translations/{_seg(language)}/"
+        )
+
+    def set_attention_translation(self, template_id: str, language: str, points: list) -> dict:
+        """Write the text of one or more points in a language, as drafts:
+        `points=[{"point_id": ..., "title": ..., "body": ...}]`. Approval is
+        a human act in the panel."""
+        return self._client.request(
+            "PUT",
+            f"/templates/{_id(template_id)}/attention-points/translations/{_seg(language)}/",
+            json={"points": points},
+        )
+
+    def delete_attention_translation(self, template_id: str, language: str):
+        return self._client.request(
+            "DELETE",
+            f"/templates/{_id(template_id)}/attention-points/translations/{_seg(language)}/",
+        )
+
+    def autotranslate_attention_points(
+        self,
+        template_id: str,
+        language: str,
+        *,
+        acknowledge: bool,
+        overwrite: bool = False,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        """Queue a MACHINE DRAFT of the attention points in `language` (202,
+        poll `get_translation_job`). A document's autotranslation drafts
+        them too. `overwrite` also replaces points with their own or an
+        approved text."""
+        return self._client.request(
+            "POST",
+            f"/templates/{_id(template_id)}/attention-points/translations/{_seg(language)}/autotranslate/",
+            json={"acknowledge": acknowledge, "overwrite": overwrite},
+            idempotency_key=idempotency_key,
+        )
+
     def add_field(
         self,
         template_id: str,
@@ -714,12 +1194,20 @@ class Templates(_Resource):
         language: str | None = None,
         kyc_images_retention: str | None = None,
         biometrics: bool = False,
+        project: str | None = None,
+        countersign: str | None = None,
+        attention_points: list[dict] | 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."""
+        the source or an approved translation. `countersign="none"` creates it
+        without the organization's automatic countersignature (default
+        "auto": countersigned when the template has an active authorization;
+        other values than the authorized ones give 409). `attention_points`
+        replaces the template's for this envelope only (Pro and Enterprise;
+        None = the template's, [] = none)."""
         body: dict = {
             "signers": signers,
             "title": title,
@@ -736,6 +1224,12 @@ class Templates(_Resource):
             body["biometrics"] = True
         if expires_in_days is not None:
             body["expires_in_days"] = expires_in_days
+        if project:
+            body["project"] = project
+        if countersign:
+            body["countersign"] = countersign
+        if attention_points is not None:
+            body["attention_points"] = attention_points
         return self._client.request(
             "POST",
             f"/templates/{_id(template_id)}/envelopes/",
@@ -743,22 +1237,125 @@ class Templates(_Resource):
             idempotency_key=idempotency_key,
         )
 
+    def request_countersign_authorization(
+        self,
+        template_id: str,
+        *,
+        authorizer_email: str,
+        authorizer_title: str,
+        valid_until: str,
+        max_uses: int | None = None,
+        variables: dict | None = None,
+        project: str | None = None,
+        scope: str | None = None,
+    ) -> dict:
+        """Ask an owner/admin to sign the standing authorization for the
+        organization's automatic countersignature (Pro+). The signing link
+        goes to the authorizer by e-mail only; it becomes active when signed.
+        ``scope``: ``"version"`` (default, the approved version in use only) or
+        ``"future_versions"`` (also the versions approved later, except one
+        adding variables whose values it does not fix)."""
+        body: dict = {
+            "authorizer_email": authorizer_email,
+            "authorizer_title": authorizer_title,
+            "valid_until": valid_until,
+            "variables": variables or {},
+        }
+        if max_uses is not None:
+            body["max_uses"] = max_uses
+        if project:
+            body["project"] = project
+        if scope:
+            body["scope"] = scope
+        return self._client.request(
+            "POST", f"/templates/{_id(template_id)}/countersign-authorizations/", json=body
+        )
 
-class Webhooks(_Resource):
-    def create(
-        self, *, url: str, event_types: list[str] | None = None, description: str = ""
+    def list_countersign_authorizations(
+        self, template_id: str, *, limit: int | None = None, cursor: str | None = None
     ) -> dict:
-        """The response includes `secret` (whsec_…) ONCE — store it now."""
+        params = {k: v for k, v in {"limit": limit, "cursor": cursor}.items() if v is not None}
+        return self._client.request(
+            "GET", f"/templates/{_id(template_id)}/countersign-authorizations/", params=params
+        )
+
+
+class CountersignAuthorizations(_Resource):
+    """Standing authorizations for the organization's automatic
+    countersignature (docs: «Contrafirma automática»)."""
+
+    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 is not None}
+        return self._client.request("GET", "/countersign-authorizations/", params=params)
+
+    def get(self, authorization_id: str) -> dict:
+        return self._client.request("GET", f"/countersign-authorizations/{_id(authorization_id)}/")
+
+    def revoke(self, authorization_id: str, *, reason: str = "") -> dict:
+        """Revoke an active one (what was countersigned stays) or cancel a
+        pending one (its signing envelope is voided)."""
         return self._client.request(
             "POST",
-            "/webhooks/",
-            json={"url": url, "event_types": event_types or [], "description": description},
+            f"/countersign-authorizations/{_id(authorization_id)}/revoke/",
+            json={"reason": reason},
         )
 
+
+class Webhooks(_Resource):
+    def create(
+        self,
+        *,
+        url: str,
+        event_types: list[str] | None = None,
+        description: str = "",
+        project: str | None = None,
+    ) -> dict:
+        """The response includes `secret` (whsec_…) ONCE — store it now.
+        Mode = the key's. `project` (organization keys only): receive only
+        that project's events; a project key always registers for its own."""
+        body: dict = {"url": url, "event_types": event_types or [], "description": description}
+        if project:
+            body["project"] = project
+        return self._client.request("POST", "/webhooks/", json=body)
+
     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 get(self, endpoint_id: str) -> dict:
+        return self._client.request("GET", f"/webhooks/{_id(endpoint_id)}/")
+
+    def update(
+        self,
+        endpoint_id: str,
+        *,
+        url: str | None = None,
+        event_types: list[str] | None = None,
+        is_active: bool | None = None,
+        description: str | None = None,
+    ) -> dict:
+        """Change only what you pass. Reactivating counts against the plan."""
+        body = {
+            k: v
+            for k, v in {
+                "url": url,
+                "event_types": event_types,
+                "is_active": is_active,
+                "description": description,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("PATCH", f"/webhooks/{_id(endpoint_id)}/", json=body)
+
+    def rotate_secret(self, endpoint_id: str, *, grace_period_hours: int = 24) -> dict:
+        """New `secret` returned ONCE. For `grace_period_hours` (0-72) deliveries
+        carry both signatures: verify with [new, old] until you switch."""
+        return self._client.request(
+            "POST",
+            f"/webhooks/{_id(endpoint_id)}/rotate-secret/",
+            json={"grace_period_hours": grace_period_hours},
+        )
+
     def delete(self, endpoint_id: str) -> None:
         self._client.request("DELETE", f"/webhooks/{_id(endpoint_id)}/")
 
@@ -766,6 +1363,69 @@ class Webhooks(_Resource):
         return self._client.request("POST", f"/webhooks/deliveries/{_id(delivery_id)}/redeliver/")
 
 
+class Projects(_Resource):
+    """Projects inside the organization (paid plans). An organization key
+    manages them all; a project key only reads its own."""
+
+    def list(
+        self,
+        *,
+        is_active: bool | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict:
+        params = {
+            k: v
+            for k, v in {
+                "is_active": None if is_active is None else str(is_active).lower(),
+                "limit": limit,
+                "cursor": cursor,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("GET", "/projects/", params=params)
+
+    def create(
+        self,
+        *,
+        name: str,
+        description: str = "",
+        embed_allowed_origins: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> dict:
+        body: dict = {"name": name, "description": description}
+        if embed_allowed_origins is not None:
+            body["embed_allowed_origins"] = list(embed_allowed_origins)
+        return self._client.request(
+            "POST", "/projects/", json=body, idempotency_key=idempotency_key
+        )
+
+    def get(self, project_id: str) -> dict:
+        return self._client.request("GET", f"/projects/{_id(project_id)}/")
+
+    def update(
+        self,
+        project_id: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        is_active: bool | None = None,
+        embed_allowed_origins: list[str] | None = None,
+    ) -> dict:
+        """`is_active=False` archives: its keys and webhooks stop working."""
+        body = {
+            k: v
+            for k, v in {
+                "name": name,
+                "description": description,
+                "is_active": is_active,
+                "embed_allowed_origins": embed_allowed_origins,
+            }.items()
+            if v is not None
+        }
+        return self._client.request("PATCH", f"/projects/{_id(project_id)}/", json=body)
+
+
 class Events(_Resource):
     """The consultable event log — reconciliation source when a webhook is
     lost (poll `list` and compare against what you received)."""
@@ -870,20 +1530,54 @@ class Organization(_Resource):
         """Org info including plan limits and features."""
         return self._client.request("GET", "/organization/")
 
+    def group(self) -> dict:
+        """The organization group (Enterprise): the group, its members and the
+        invitations received. Read only: the acts happen in the panel."""
+        return self._client.request("GET", "/organization/group/")
+
+    def group_templates(self) -> dict:
+        """Templates the other organizations of the group offer (approved
+        version, names only)."""
+        return self._client.request("GET", "/organization/group/templates/")
+
+    def copy_group_template(
+        self, template_id: str, *, name: str = "", idempotency_key: str | None = None
+    ) -> dict:
+        """Copy an offered template into this organization as a new DRAFT
+        (translations too): approve it and request its own countersign."""
+        return self._client.request(
+            "POST",
+            f"/organization/group/templates/{_id(template_id)}/copy/",
+            json={"name": name} if name else {},
+            idempotency_key=idempotency_key,
+        )
+
     def update(
         self,
         *,
         retention_policies: dict | None = None,
         embed_allowed_origins: list[str] | None = None,
+        seal_profile: str | None = None,
+        acknowledge: bool = False,
     ) -> dict:
         """Organization settings an API key may change: retention policy per
-        document type (months within the plan's range) and the web origins
-        allowed to embed the signer flow (the FULL list; [] disables it)."""
+        document type (months within the plan's range), the web origins
+        allowed to embed the signer flow (the FULL list; [] disables it) and
+        the cryptographic restrictions of the platform seal.
+
+        `seal_profile`: "hybrid" (ECDSA P-384 + ML-DSA-87, quantum resistant;
+        readers without ML-DSA show that signature as unknown) or "classic"
+        (ECDSA only, no warnings, not quantum resistant). Changing it needs
+        `acknowledge=True`: you confirm the trade-off described in
+        `get()["cryptography"]["options"]`. It applies to envelopes sent
+        afterwards."""
         body: dict = {}
         if retention_policies is not None:
             body["retention_policies"] = retention_policies
         if embed_allowed_origins is not None:
             body["embed_allowed_origins"] = list(embed_allowed_origins)
+        if seal_profile is not None:
+            body["cryptography"] = {"seal_profile": seal_profile, "acknowledge": acknowledge}
         return self._client.request("PATCH", "/organization/", json=body)
 
 

{easycontract-0.1.1 → easycontract-0.1.7}/src/easycontract/webhooks.py

@@ -5,12 +5,16 @@ 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):
+whsec_… secret (shown once at creation or rotation):
 
     event = easycontract.webhooks.verify_signature(
         payload=request.body, header=request.headers["X-EasyContract-Signature"],
         secret=WEBHOOK_SECRET,
     )
+
+After a secret rotation, during the grace period, the header carries one v1
+per valid secret (`t=…,v1=<new>,v1=<old>`): the delivery is valid if ANY v1
+matches. `secret` may also be a list (e.g. [new, old]) while you switch.
 """
 
 from __future__ import annotations
@@ -29,7 +33,7 @@ def verify_signature(
     *,
     payload: bytes | str,
     header: str,
-    secret: bytes | str,
+    secret: bytes | str | list | tuple,
     tolerance: int | None = DEFAULT_TOLERANCE_SECONDS,
 ) -> dict:
     """Verify a delivery and return the parsed event. Raises
@@ -51,20 +55,34 @@ def verify_signature(
         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")
+    secrets = list(secret) if isinstance(secret, (list, tuple)) else [secret]
+    if not secrets:
+        raise SignatureVerificationError("no secret given")
+    secret_keys = [
+        s if isinstance(s, (bytes, bytearray)) else str(s).encode("utf-8") for s in secrets
+    ]
 
     try:
-        parts = dict(part.split("=", 1) for part in header.split(","))
-        timestamp = int(parts["t"])
-        signature = parts["v1"]
+        pairs = [part.split("=", 1) for part in header.split(",")]
+        timestamps = [value for key, value in pairs if key.strip() == "t"]
+        signatures = [value.strip() for key, value in pairs if key.strip() == "v1"]
+        if len(timestamps) != 1 or not signatures:
+            raise KeyError("t/v1")
+        timestamp = int(timestamps[0])
     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()):
+    signed = b"%d." % timestamp + body
+    matched = False
+    for key in secret_keys:
+        expected = hmac.new(key, signed, hashlib.sha256).hexdigest().encode()
+        for signature in signatures:
+            # no early exit: constant work whatever matches
+            matched |= hmac.compare_digest(expected, signature.encode())
+    if not matched:
         raise SignatureVerificationError("signature mismatch")
     try:
         return json.loads(body.decode("utf-8"))