signingflow 0.1.0__tar.gz

signingflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Signingflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

signingflow-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: signingflow
+Version: 0.1.0
+Summary: Official Python SDK for sending a document, reading envelope status, and verifying webhooks with the Signingflow API.
+Author: Signingflow
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: coverage>=7.6; extra == "dev"
+Dynamic: license-file
+
+# signingflow
+
+[![CI](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Signingflow/signingflow-python/badges/coverage.json)](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Python SDK for the Signingflow calls used to send a document, read envelope status, and receive webhooks.
+
+The package talks to `https://api.signingflow.com`. Keep the API key on your server. Python 3.11 or newer is required.
+
+```bash
+pip install "signingflow @ git+https://github.com/Signingflow/signingflow-python.git"
+```
+
+The package name is `signingflow`. Install it from [GitHub](https://github.com/Signingflow/signingflow-python) until it is published on PyPI.
+
+```python
+import os
+import signingflow
+
+client = signingflow.Client(
+    os.environ["SIGNINGFLOW_API_KEY"],
+    workspace_id=os.environ["SIGNINGFLOW_WORKSPACE_ID"],
+    env="sandbox",
+)
+
+envelope = client.envelopes.send_document(
+    title="NDA",
+    file=pdf_bytes,
+    filename="contract.pdf",
+    recipients=[{"name": "Ada Lovelace", "email": "ada@example.com"}],
+    message="Please sign",
+)
+```
+
+`file` is the raw bytes. `b""` is an empty file. A disk path is `path`, and it is read only from `upload_root`. That directory must be one this process writes. The open refuses a symlink, a hard link, an absolute path, and a path that leaves the directory. If this runtime cannot open a path without following a symlink, the read is refused. Do not pass a path from a request field.
+
+`env` is `sandbox` or `live`. The client always sends `X-Request-Env`. A missing environment header is treated as live by the API, so the client rejects a missing environment.
+
+`base_url` must be `https`. The host is `api.signingflow.com` unless `allow_custom_base_url` is set. A username or password on the URL is rejected. The host comparison is case-sensitive. There is no module-level API key.
+
+The client sends `Accept-Encoding: identity`, does not follow redirects, and stops reading once an API response passes 8 MB.
+
+## Send and read
+
+`envelopes.prepare_draft` stores one PDF and creates a draft. It does not email anyone.
+
+`envelopes.send_document` stores the PDF, creates the draft, adds the recipients to the first document, and sends. `envelopes.send_from_template` starts from `templates/{id}`.
+
+If update or send fails, the error includes `envelope_name` for the draft that was saved. After a timeout, the client returns the envelope only when `sent_time` is within two minutes after the call started and not more than a minute ahead of this clock. An older or far-future timestamp is an error.
+
+`envelopes.list(directory="needAction")` reads pages of 10. `page_size` can be from 1 to 1000. Omitting it selects 10. `0` is rejected. `all()` walks later pages and stops after 100 follow-up pages or a repeated token.
+
+`envelopes.download_completed(name)` reads the envelope first. It requests the download URL only when the state is `COMPLETED`. The download call returns `uri`, `download_time`, and `etag`. This client does not GET `uri`. Treat that URL as untrusted until your application checks the host. Do not send the API key to it.
+
+`envelopes.remind(name)` notifies people who can still sign. The call is not idempotent.
+
+## Idempotency
+
+Creates and sends send a UUID `idempotencyKey` in the JSON body. The same key is stored for the whole environment. A repeat returns HTTP 409 and does not return the original resource. The SDK raises `signingflow.IdempotencyError` with `resource_name` when the error includes one. It does not treat that response as success.
+
+Pass the same `idempotency_key` only to retry one request after a timeout. `update` and `remind` are not retried automatically. A query value that contains the API key is rejected, including when that key is percent-encoded.
+
+## Webhooks
+
+```python
+destination = client.webhook_urls.create(
+    display_name="Envelope events",
+    http_request_uri="https://example.com/webhooks/signingflow",
+    events=["DOC_ENVELOPE_COMPLETED"],
+)
+secret = signingflow.signing_secret_of(destination)
+```
+
+Store that secret from the create response. A later `retrieve` does not include it. Do not set `http_config`. `auth` `NONE` is rejected.
+
+```python
+event = signingflow.construct_event(
+    raw_body,
+    signature_header,
+    secret,
+    previous_secret=previous_secret,
+    previous_signature=previous_signature,
+)
+event.payload
+event.body_sha256
+```
+
+`raw_body` must be the original `bytes`. The signature is lowercase hex HMAC-SHA256 of those bytes. There is no timestamp. Compare `X-Signingflow-Signature` or `X-Webhook-Signature`. During a grace window, also pass the previous header and secret. Parse JSON only after the MAC matches. `body_sha256` is the SHA-256 of those raw bytes. Store it and reject a delivery you have already seen.
+
+## Errors
+
+Every SDK error is a `signingflow.Error`.
+
+| Type | When |
+| --- | --- |
+| `AuthenticationError` | HTTP 401 |
+| `PermissionError` | HTTP 403 |
+| `IdempotencyError` | HTTP 409 whose body says the key was already used |
+| `RateLimitError` | HTTP 429 |
+| `InvalidRequestError` | Any other HTTP 4xx, or a rejected argument |
+| `APIError` | HTTP 5xx, or a body the client will not parse |
+| `ConnectionError` | The API was not reached, including a timeout |
+| `SignatureVerificationError` | A webhook MAC did not match |

signingflow-0.1.0/README.md

@@ -0,0 +1,104 @@
+# signingflow
+
+[![CI](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml/badge.svg)](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Signingflow/signingflow-python/badges/coverage.json)](https://github.com/Signingflow/signingflow-python/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Python SDK for the Signingflow calls used to send a document, read envelope status, and receive webhooks.
+
+The package talks to `https://api.signingflow.com`. Keep the API key on your server. Python 3.11 or newer is required.
+
+```bash
+pip install "signingflow @ git+https://github.com/Signingflow/signingflow-python.git"
+```
+
+The package name is `signingflow`. Install it from [GitHub](https://github.com/Signingflow/signingflow-python) until it is published on PyPI.
+
+```python
+import os
+import signingflow
+
+client = signingflow.Client(
+    os.environ["SIGNINGFLOW_API_KEY"],
+    workspace_id=os.environ["SIGNINGFLOW_WORKSPACE_ID"],
+    env="sandbox",
+)
+
+envelope = client.envelopes.send_document(
+    title="NDA",
+    file=pdf_bytes,
+    filename="contract.pdf",
+    recipients=[{"name": "Ada Lovelace", "email": "ada@example.com"}],
+    message="Please sign",
+)
+```
+
+`file` is the raw bytes. `b""` is an empty file. A disk path is `path`, and it is read only from `upload_root`. That directory must be one this process writes. The open refuses a symlink, a hard link, an absolute path, and a path that leaves the directory. If this runtime cannot open a path without following a symlink, the read is refused. Do not pass a path from a request field.
+
+`env` is `sandbox` or `live`. The client always sends `X-Request-Env`. A missing environment header is treated as live by the API, so the client rejects a missing environment.
+
+`base_url` must be `https`. The host is `api.signingflow.com` unless `allow_custom_base_url` is set. A username or password on the URL is rejected. The host comparison is case-sensitive. There is no module-level API key.
+
+The client sends `Accept-Encoding: identity`, does not follow redirects, and stops reading once an API response passes 8 MB.
+
+## Send and read
+
+`envelopes.prepare_draft` stores one PDF and creates a draft. It does not email anyone.
+
+`envelopes.send_document` stores the PDF, creates the draft, adds the recipients to the first document, and sends. `envelopes.send_from_template` starts from `templates/{id}`.
+
+If update or send fails, the error includes `envelope_name` for the draft that was saved. After a timeout, the client returns the envelope only when `sent_time` is within two minutes after the call started and not more than a minute ahead of this clock. An older or far-future timestamp is an error.
+
+`envelopes.list(directory="needAction")` reads pages of 10. `page_size` can be from 1 to 1000. Omitting it selects 10. `0` is rejected. `all()` walks later pages and stops after 100 follow-up pages or a repeated token.
+
+`envelopes.download_completed(name)` reads the envelope first. It requests the download URL only when the state is `COMPLETED`. The download call returns `uri`, `download_time`, and `etag`. This client does not GET `uri`. Treat that URL as untrusted until your application checks the host. Do not send the API key to it.
+
+`envelopes.remind(name)` notifies people who can still sign. The call is not idempotent.
+
+## Idempotency
+
+Creates and sends send a UUID `idempotencyKey` in the JSON body. The same key is stored for the whole environment. A repeat returns HTTP 409 and does not return the original resource. The SDK raises `signingflow.IdempotencyError` with `resource_name` when the error includes one. It does not treat that response as success.
+
+Pass the same `idempotency_key` only to retry one request after a timeout. `update` and `remind` are not retried automatically. A query value that contains the API key is rejected, including when that key is percent-encoded.
+
+## Webhooks
+
+```python
+destination = client.webhook_urls.create(
+    display_name="Envelope events",
+    http_request_uri="https://example.com/webhooks/signingflow",
+    events=["DOC_ENVELOPE_COMPLETED"],
+)
+secret = signingflow.signing_secret_of(destination)
+```
+
+Store that secret from the create response. A later `retrieve` does not include it. Do not set `http_config`. `auth` `NONE` is rejected.
+
+```python
+event = signingflow.construct_event(
+    raw_body,
+    signature_header,
+    secret,
+    previous_secret=previous_secret,
+    previous_signature=previous_signature,
+)
+event.payload
+event.body_sha256
+```
+
+`raw_body` must be the original `bytes`. The signature is lowercase hex HMAC-SHA256 of those bytes. There is no timestamp. Compare `X-Signingflow-Signature` or `X-Webhook-Signature`. During a grace window, also pass the previous header and secret. Parse JSON only after the MAC matches. `body_sha256` is the SHA-256 of those raw bytes. Store it and reject a delivery you have already seen.
+
+## Errors
+
+Every SDK error is a `signingflow.Error`.
+
+| Type | When |
+| --- | --- |
+| `AuthenticationError` | HTTP 401 |
+| `PermissionError` | HTTP 403 |
+| `IdempotencyError` | HTTP 409 whose body says the key was already used |
+| `RateLimitError` | HTTP 429 |
+| `InvalidRequestError` | Any other HTTP 4xx, or a rejected argument |
+| `APIError` | HTTP 5xx, or a body the client will not parse |
+| `ConnectionError` | The API was not reached, including a timeout |
+| `SignatureVerificationError` | A webhook MAC did not match |

signingflow-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "signingflow"
+version = "0.1.0"
+description = "Official Python SDK for sending a document, reading envelope status, and verifying webhooks with the Signingflow API."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Signingflow" }]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["coverage>=7.6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+signingflow = ["resources/allowlist.json"]
+
+[tool.coverage.run]
+branch = true
+source = ["signingflow"]
+
+[tool.coverage.report]
+show_missing = true

signingflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

signingflow-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)