signingflow 0.1.0__py3-none-any.whl

signingflow/__init__.py

@@ -0,0 +1,35 @@
+"""Official Python SDK for the Signingflow calls used by skills and MCP tools."""
+
+from signingflow.client import Client
+from signingflow.errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    Error,
+    IdempotencyError,
+    InvalidRequestError,
+    PermissionError,
+    RateLimitError,
+    SignatureVerificationError,
+)
+from signingflow.version import VERSION
+from signingflow.webhook_verify import Event, construct_event
+from signingflow.webhooks import HTTPConfig, signing_secret_of
+
+__all__ = [
+    "VERSION",
+    "APIError",
+    "AuthenticationError",
+    "Client",
+    "ConnectionError",
+    "Error",
+    "Event",
+    "HTTPConfig",
+    "IdempotencyError",
+    "InvalidRequestError",
+    "PermissionError",
+    "RateLimitError",
+    "SignatureVerificationError",
+    "construct_event",
+    "signing_secret_of",
+]

signingflow/allowlist.py

@@ -0,0 +1,29 @@
+"""The 15 operations used by skills and MCP tools."""
+
+import json
+
+from importlib.resources import files
+
+from signingflow.errors import Error
+
+
+def _load():
+    try:
+        raw = files("signingflow").joinpath("resources/allowlist.json").read_text(encoding="utf-8")
+        parsed = json.loads(raw)
+        operations = parsed["operations"]
+        if len(operations) != 15:
+            raise ValueError("allowlist length")
+        return {item["operationId"]: item for item in operations}
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+        raise RuntimeError("allowlist.json is invalid") from exc
+
+
+OPERATIONS = _load()
+
+
+def operation(operation_id):
+    try:
+        return OPERATIONS[operation_id]
+    except KeyError as exc:
+        raise Error(f"Unknown operation {operation_id}.") from exc

signingflow/client.py

@@ -0,0 +1,19 @@
+"""The instance client. There is no module-level API key."""
+
+from signingflow.config import Config
+from signingflow.envelopes import Envelopes
+from signingflow.files import Files
+from signingflow.request import Sender
+from signingflow.templates import Templates
+from signingflow.webhooks import WebhookDeliveries, WebhookURLs
+
+
+class Client:
+    def __init__(self, api_key, **options):
+        self.config = Config(api_key, **options)
+        sender = Sender(self.config)
+        self.files = Files(sender)
+        self.templates = Templates(sender)
+        self.envelopes = Envelopes(sender, self.files, self.templates)
+        self.webhook_urls = WebhookURLs(sender)
+        self.webhook_deliveries = WebhookDeliveries(sender)

signingflow/clock.py

@@ -0,0 +1,13 @@
+"""Wall clock and sleep. Tests replace these."""
+
+import time
+from datetime import datetime, timezone
+
+
+def now():
+    return datetime.now(timezone.utc)
+
+
+def sleep(seconds):
+    if seconds > 0:
+        time.sleep(seconds)

signingflow/config.py

@@ -0,0 +1,105 @@
+"""Client settings. The API key stays on the instance."""
+
+from urllib.parse import urlsplit
+
+OFFICIAL_HOST = "api.signingflow.com"
+DEFAULT_BASE_URL = "https://api.signingflow.com"
+DEFAULT_TIMEOUT = 30
+DEFAULT_RETRIES = 2
+DEFAULT_UPLOAD_HOSTS = ("storage.googleapis.com",)
+
+
+class Config:
+    def __init__(
+        self,
+        api_key,
+        *,
+        workspace_id,
+        env,
+        base_url=None,
+        allow_custom_base_url=False,
+        timeout=None,
+        max_network_retries=None,
+        channel=None,
+        funnel=None,
+        upload_hosts=None,
+        upload_root=None,
+        ssl_context=None,
+    ):
+        from signingflow.errors import Error, invalid
+
+        self.api_key = (api_key or "").strip()
+        if not self.api_key:
+            raise Error("API key is required.")
+        self.workspace_id = (workspace_id or "").strip()
+        if not self.workspace_id:
+            raise Error("workspace_id is required.")
+        self.wire_env = _normalize_env(env)
+        base = (base_url or "").strip() or DEFAULT_BASE_URL
+        base = base.rstrip("/")
+        parsed = urlsplit(base)
+        if not parsed.scheme or not parsed.netloc:
+            raise Error("base_url must be an absolute URL.")
+        if parsed.scheme != "https":
+            raise Error("base_url must be https.")
+        if parsed.username is not None or parsed.password is not None:
+            raise Error("base_url must not include a username or password.")
+        if "\x00" in base:
+            raise Error("base_url must be an absolute URL.")
+        raw_host = _raw_host(parsed.netloc)
+        if raw_host != OFFICIAL_HOST and not allow_custom_base_url:
+            raise Error("base_url host must be api.signingflow.com, or set allow_custom_base_url.")
+        self.base_url = base
+        self.allow_custom_base_url = bool(allow_custom_base_url)
+        self.timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        if not isinstance(self.timeout, (int, float)) or isinstance(self.timeout, bool) or self.timeout <= 0:
+            raise Error("timeout must be positive.")
+        self.retries = DEFAULT_RETRIES if max_network_retries is None else max_network_retries
+        if isinstance(self.retries, bool) or not isinstance(self.retries, int) or self.retries < 0:
+            raise Error("max_network_retries must be a whole number of zero or more.")
+        self.upload_hosts = _upload_hosts(upload_hosts)
+        self.channel = (channel or "").strip()
+        self.funnel = (funnel or "").strip()
+        self.upload_root = (upload_root or "").strip()
+        self.ssl_context = ssl_context
+        if any(bad_header(value) for value in (self.api_key, self.workspace_id, self.channel, self.funnel)):
+            raise invalid("invalid header value")
+
+
+def bad_header(value):
+    return "\r" in value or "\n" in value
+
+
+def _normalize_env(env):
+    from signingflow.errors import Error
+
+    if env in ("sandbox", "SANDBOX"):
+        return "SANDBOX"
+    if env in ("live", "LIVE"):
+        return "LIVE"
+    raise Error("env must be sandbox or live.")
+
+
+def _raw_host(netloc):
+    host = netloc.rsplit("@", 1)[-1]
+    if host.startswith("["):
+        end = host.find("]")
+        return host[: end + 1] if end != -1 else host
+    return host.split(":", 1)[0]
+
+
+def _upload_hosts(hosts):
+    from signingflow.errors import Error
+
+    if hosts is None:
+        hosts = DEFAULT_UPLOAD_HOSTS
+    cleaned = []
+    for host in hosts:
+        host = str(host).strip().lower()
+        if not host:
+            continue
+        dots = host.count(".")
+        if dots < 2 or host.startswith(".") or host.endswith(".") or ".." in host:
+            raise Error("Each upload_hosts entry must be a specific host, not a public suffix.")
+        cleaned.append(host)
+    return tuple(cleaned)

signingflow/envelopes.py

@@ -0,0 +1,279 @@
+"""Create, send, and read envelopes."""
+
+from datetime import timedelta, timezone
+
+from signingflow import clock
+from signingflow.errors import APIError, ConnectionError, IdempotencyError, attach, invalid
+from signingflow.models import (
+    Download,
+    clean_recipients,
+    created_envelope,
+    decode_envelope,
+    envelope_state,
+    require_envelope_name,
+)
+from signingflow.pagination import List, list_items, next_token, page_size_of
+from signingflow.path import _parse_retry
+from signingflow.request import key_for
+from signingflow.status import as_map, as_str
+
+_SEND_WINDOW = timedelta(minutes=2)
+_SEND_SKEW = timedelta(minutes=1)
+
+
+class Envelopes:
+    def __init__(self, sender, files, templates):
+        self._sender = sender
+        self._files = files
+        self._templates = templates
+
+    def create(self, *, display_name, storage_id, description="", idempotency_key=""):
+        title = (display_name or "").strip()
+        if not title:
+            raise invalid("Name the draft title.")
+        storage_id = (storage_id or "").strip()
+        if not storage_id:
+            raise invalid("storage_id is required.")
+        created = self._sender.call(
+            "EnvelopeService_AddEnvelope",
+            idempotency_key=idempotency_key,
+            body={
+                "envelope": {
+                    "display_name": title,
+                    "description": (description or "").strip(),
+                    "documents": [
+                        {
+                            "display_name": title,
+                            "attachments": [{"storage_id": storage_id}],
+                            "supplemental": False,
+                        }
+                    ],
+                }
+            },
+        )
+        return created_envelope(created)
+
+    def retrieve(self, name, *, read_mask=""):
+        envelope = require_envelope_name(name)
+        viewed = self._sender.call(
+            "EnvelopeService_ViewEnvelope",
+            path_params={"name": envelope},
+            query={"readMask": read_mask},
+        )
+        decoded = decode_envelope(viewed)
+        if not decoded.name:
+            decoded.name = envelope
+        return decoded
+
+    def update(self, name, body):
+        envelope = require_envelope_name(name)
+        payload = dict(body or {})
+        if not as_str(payload.get("name")):
+            payload["name"] = envelope
+        updated = self._sender.call(
+            "EnvelopeService_UpdateEnvelope",
+            path_params={"name": envelope},
+            body=payload,
+        )
+        return decode_envelope(updated)
+
+    def send(self, name, *, idempotency_key=""):
+        envelope = require_envelope_name(name)
+        sent = self._sender.call(
+            "EnvelopeService_SendEnvelope",
+            path_params={"name": envelope},
+            idempotency_key=idempotency_key,
+            body={},
+        )
+        decoded = decode_envelope(sent)
+        if not decoded.name:
+            decoded.name = envelope
+        return decoded
+
+    def list(self, *, directory, page_size=None, page_token="", read_mask=""):
+        directory = (directory or "").strip()
+        if not directory:
+            raise invalid("directory is required.")
+        size = page_size_of(page_size)
+
+        def load(token):
+            return self._list_page(directory, size, token, read_mask)
+
+        page = load(page_token)
+        page._load = load
+        return page
+
+    def remind(self, name):
+        envelope = require_envelope_name(name)
+        reminded = self._sender.call(
+            "EnvelopeService_RemindEnvelopeSigners",
+            path_params={"name": envelope},
+            body={},
+        )
+        decoded = decode_envelope(reminded)
+        if not decoded.name:
+            decoded.name = envelope
+        return decoded
+
+    def download(self, name):
+        envelope = require_envelope_name(name)
+        downloaded = self._sender.call(
+            "EnvelopeService_DownloadEnvelope",
+            path_params={"name": envelope},
+        )
+        record = as_map(downloaded) or {}
+        return Download(
+            uri=as_str(record.get("uri")),
+            download_time=_first(record, "download_time", "downloadTime"),
+            etag=as_str(record.get("etag")),
+        )
+
+    def prepare_draft(self, *, title, file=None, path="", filename="", message=""):
+        title = (title or "").strip()
+        if not title:
+            raise invalid("Name the PDF and the draft title.")
+        stored = self._files.create(file=file, path=path, filename=filename)
+        return self.create(display_name=title, description=message, storage_id=stored.id)
+
+    def send_document(self, *, title, file=None, path="", filename="", recipients=None, message=""):
+        title = (title or "").strip()
+        if not title:
+            raise invalid("Name the PDF, the title, and the recipients.")
+        people = clean_recipients(recipients)
+        stored = self._files.create(file=file, path=path, filename=filename)
+        created = self.create(display_name=title, description=message, storage_id=stored.id)
+        return self._finish_send(created, people, message, title)
+
+    def send_from_template(self, *, template, recipients=None, message=""):
+        people = clean_recipients(recipients)
+        created = self._templates.use(template)
+        return self._finish_send(created, people, message, template)
+
+    def download_completed(self, name):
+        envelope = require_envelope_name(name)
+        viewed = self.retrieve(envelope)
+        if envelope_state(viewed).strip().upper() != "COMPLETED":
+            err = invalid("The signed file is not ready.")
+            err.envelope_name = envelope
+            raise err
+        return self.download(envelope)
+
+    def _list_page(self, directory, page_size, page_token, read_mask):
+        body = self._sender.call(
+            "EnvelopeService_ListEnvelopes",
+            path_params={"parent": "envelopes"},
+            query={
+                "directory": directory,
+                "pageSize": str(page_size),
+                "pageToken": page_token or "",
+                "readMask": read_mask or "",
+            },
+        )
+        record = as_map(body) or {}
+        data = [decode_envelope(item) for item in list_items(record, "envelopes")]
+        return List(data, next_token(record))
+
+    def _finish_send(self, created, people, message, label):
+        name = created.name
+        try:
+            require_envelope_name(name)
+        except Exception:
+            raise APIError(f"{label} was saved without an envelope name.") from None
+        try:
+            viewed = self.retrieve(name, read_mask="documents,compliance")
+        except Exception as exc:
+            raise attach(exc, name) from exc
+        patched = _with_recipients(viewed, people, message)
+        if patched is None:
+            err = invalid("The draft has no document to address.")
+            err.envelope_name = name
+            raise err
+        try:
+            self.update(name, patched)
+        except Exception as exc:
+            raise attach(exc, name) from exc
+        return self._send_or_view(name)
+
+    def _send_or_view(self, name):
+        started = clock.now()
+        try:
+            return self.send(name)
+        except IdempotencyError as exc:
+            if exc.resource_name == name:
+                try:
+                    return self.retrieve(name)
+                except Exception:
+                    raise attach(exc, name) from exc
+            raise attach(exc, name) from exc
+        except ConnectionError as exc:
+            try:
+                viewed = self.retrieve(name)
+            except Exception:
+                raise attach(exc, name) from exc
+            sent = _parse_retry(viewed.sent_time)
+            if sent is not None and _sent_during(sent, started, clock.now()):
+                return viewed
+            raise attach(exc, name) from exc
+        except Exception as exc:
+            raise attach(exc, name) from exc
+
+
+def _with_recipients(envelope, people, message):
+    refs = []
+    for item in envelope.documents:
+        uid = _first(item, "uid", "id")
+        if not uid:
+            continue
+        refs.append({"uid": uid, "display_name": _first(item, "display_name", "displayName")})
+    if not refs:
+        return None
+    participants = []
+    for index, person in enumerate(people):
+        participants.append(
+            {
+                "uid": key_for("", None),
+                "display_name": person["name"],
+                "alternate_email": person["email"],
+                "role": "SIGNER",
+                "type": "PERSONAL",
+                "action_order_type": "SERIAL",
+                "action_order_number": index + 1,
+            }
+        )
+    profile = "STANDARD"
+    if envelope.compliance and as_str(envelope.compliance.get("profile")):
+        profile = as_str(envelope.compliance.get("profile"))
+    description = (message or "").strip() or envelope.description
+    documents = []
+    for index, document in enumerate(refs):
+        item = {"uid": document["uid"], "display_name": document["display_name"]}
+        if index == 0:
+            item["participants"] = participants
+        documents.append(item)
+    return {
+        "name": envelope.name,
+        "display_name": envelope.display_name,
+        "description": description,
+        "compliance": {"profile": profile},
+        "documents": documents,
+    }
+
+
+def _sent_during(sent, started, current):
+    if sent.tzinfo is None:
+        sent = sent.replace(tzinfo=timezone.utc)
+    if started.tzinfo is None:
+        started = started.replace(tzinfo=timezone.utc)
+    if current.tzinfo is None:
+        current = current.replace(tzinfo=timezone.utc)
+    return started <= sent <= started + _SEND_WINDOW and sent <= current + _SEND_SKEW
+
+
+def _first(record, *keys):
+    if not record:
+        return ""
+    for key in keys:
+        value = record.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return ""

signingflow/errors.py

@@ -0,0 +1,79 @@
+"""SDK errors. Every specific error is also an Error."""
+
+
+class FieldViolation:
+    def __init__(self, field, description):
+        self.field = field
+        self.description = description
+
+
+class Error(Exception):
+    def __init__(
+        self,
+        message="",
+        *,
+        status_code=0,
+        grpc_code=None,
+        trace_code="",
+        request_id="",
+        idempotency_key="",
+        capability="",
+        resource_name="",
+        envelope_name="",
+        retry_after="",
+        field_violations=None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.grpc_code = grpc_code
+        self.trace_code = trace_code or ""
+        self.request_id = request_id or ""
+        self.idempotency_key = idempotency_key or ""
+        self.capability = capability or ""
+        self.resource_name = resource_name or ""
+        self.envelope_name = envelope_name or ""
+        self.retry_after = retry_after or ""
+        self.field_violations = list(field_violations or [])
+
+
+class AuthenticationError(Error):
+    """HTTP 401."""
+
+
+class PermissionError(Error):
+    """HTTP 403."""
+
+
+class IdempotencyError(Error):
+    """HTTP 409 when the body says the key was already used."""
+
+
+class RateLimitError(Error):
+    """HTTP 429."""
+
+
+class InvalidRequestError(Error):
+    """Any other HTTP 4xx, or a rejected argument."""
+
+
+class APIError(Error):
+    """HTTP 5xx, or a body the client will not parse."""
+
+
+class ConnectionError(Error):
+    """The API was not reached, including a timeout."""
+
+
+class SignatureVerificationError(Error):
+    """A webhook MAC did not match."""
+
+
+def invalid(message):
+    return InvalidRequestError(message)
+
+
+def attach(err, envelope_name):
+    if isinstance(err, Error):
+        err.envelope_name = envelope_name
+    return err

signingflow/files.py

@@ -0,0 +1,81 @@
+"""Upload one file through a pre-signed URL."""
+
+import os
+
+from signingflow.config import bad_header
+from signingflow.errors import APIError, invalid
+from signingflow.jail import read_path
+from signingflow.models import StoredFile, find_storage
+from signingflow.path import allowed_upload_url
+
+_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
+_MIME_BY_EXTENSION = {
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".txt": "text/plain",
+    ".json": "application/json",
+}
+
+
+class Files:
+    def __init__(self, sender):
+        self._sender = sender
+
+    def create(self, *, file=None, path="", filename="", mime_type="", idempotency_key=""):
+        loaded = _load_file(file=file, path=path, filename=filename, mime_type=mime_type, upload_root=self._sender.config.upload_root)
+        added = self._sender.call(
+            "StorageService_BatchAddStorage",
+            idempotency_key=idempotency_key,
+            body={
+                "storages": [
+                    {
+                        "originalName": loaded["filename"],
+                        "displayName": loaded["filename"],
+                        "size": str(len(loaded["data"])),
+                        "extension": loaded["extension"],
+                        "mimeType": loaded["mime_type"],
+                    }
+                ]
+            },
+        )
+        found = find_storage(added)
+        if found is None:
+            raise APIError("Storage did not return an upload URL.")
+        name, file_id, raw_url = found
+        upload = allowed_upload_url(raw_url, self._sender.config.upload_hosts)
+        self._sender.put_bytes(upload, loaded["mime_type"], loaded["data"])
+        self._sender.call("StorageService_BatchAcknowledgeUpload", body={"names": [name]})
+        return StoredFile(name, file_id)
+
+
+def _load_file(*, file, path, filename, mime_type, upload_root):
+    has_file = file is not None
+    has_path = bool((path or "").strip())
+    if has_file and has_path:
+        raise invalid("Pass file bytes or a path, not both.")
+    if not has_file and not has_path:
+        raise invalid("Pass file bytes or a path.")
+    if has_file:
+        if not isinstance(file, (bytes, bytearray)):
+            raise invalid("Pass file bytes or a path.")
+        data = bytes(file)
+    else:
+        data = read_path(upload_root, path)
+    if len(data) > _MAX_UPLOAD_BYTES:
+        raise invalid("The file is larger than 25 MB.")
+    filename = (filename or "").strip()
+    if not filename and has_path:
+        filename = os.path.basename(path)
+    if filename in ("", ".", "/"):
+        raise invalid("filename is required when file is not a path.")
+    extension = os.path.splitext(filename)[1].lower().lstrip(".")
+    mime_type = (mime_type or "").strip()
+    if not mime_type:
+        mime_type = _MIME_BY_EXTENSION.get("." + extension, "")
+    if not mime_type:
+        mime_type = "application/octet-stream"
+    if bad_header(mime_type):
+        raise invalid("invalid header value")
+    return {"data": data, "filename": filename, "extension": extension, "mime_type": mime_type}