signyu 0.1.0__tar.gz

signyu-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.tgz
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/

signyu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BN Habitat Pvt Ltd (SignYu)
+
+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.

signyu-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: signyu
+Version: 0.1.0
+Summary: Official Python SDK for the SignYu Aadhaar eSign API
+Project-URL: Homepage, https://signyu.com/api
+Project-URL: Documentation, https://signyu.com/docs
+Project-URL: Bug Tracker, https://signyu.com/contact
+Author-email: SignYu <contact@mail.signyu.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aadhaar,aadhaar-esign,digital-signature,e-signature,emudhra,esign,india,signyu
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# SignYu Python SDK
+
+Official Python SDK for the [SignYu](https://signyu.com) Aadhaar eSign API. Upload a PDF, add signers, and send it for legally valid Aadhaar OTP based eSignature under the IT Act 2000, all from your backend.
+
+- Python 3.9 or newer, built on `httpx`
+- Fully typed (`py.typed`, TypedDict responses)
+- Webhook signature verification with constant time comparison
+
+API docs: https://signyu.com/docs. API overview and pricing: https://signyu.com/api (signatures from ₹15 each on credit packs of 10 or more).
+
+## Install
+
+```bash
+pip install signyu
+```
+
+## Quickstart
+
+```python
+from signyu import SignYu
+
+client = SignYu(api_key="sk_live_...")  # or set SIGNYU_API_KEY
+
+# 1. Upload the PDF (a path, bytes, or a binary file object)
+doc = client.documents.create(file="agreement.pdf", name="Service Agreement")
+
+# 2. Add signers (they sign in this order, up to 6 per document)
+client.documents.add_signers(doc["documentId"], [
+    {"name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com"},
+    {"name": "Vikram Nair", "phone": "9812345678", "email": "vikram@example.com"},
+])
+
+# 3. Send: deducts one credit per signer and emails each signer a link
+sent = client.documents.send(doc["documentId"])
+print([s["signUrl"] for s in sent["signers"]])
+
+# 4. Check progress (or use webhooks)
+status = client.documents.get(doc["documentId"])
+print(status["status"])  # PENDING, SENT or COMPLETED
+```
+
+Responses are plain dicts with the API's camelCase keys, typed as `TypedDict`s in `signyu.types`.
+
+Get your API key from the dashboard under Developers (https://signyu.com/app/developers). Keep it on your server.
+
+## Configuration
+
+```python
+client = SignYu(
+    api_key="sk_live_...",          # or the SIGNYU_API_KEY environment variable
+    base_url="https://signyu.com",  # optional
+    timeout=60.0,                   # optional, seconds
+    http_client=None,               # optional, your own httpx.Client
+)
+```
+
+The client can be used as a context manager (`with SignYu(...) as client:`) or closed with `client.close()`.
+
+## Methods
+
+### `client.documents.create(file, name=None, file_name=None)`
+
+`POST /api/v1/documents`. Uploads a PDF (at most 10MB) and creates a document in `PENDING` state. `file` can be a path (`str` or `pathlib.Path`), `bytes`, or a binary file object. It is always sent as `application/pdf`. `name` defaults to the file name.
+
+Returns `{"documentId", "name", "status"}`.
+
+### `client.documents.list(limit=None, offset=None)`
+
+`GET /api/v1/documents`. Your documents, most recent first. `limit` is 1 to 100 (default 20), `offset` defaults to 0.
+
+Returns `{"documents": [{"documentId", "name", "status", "createdAt", "signers": {"total", "signed"}}], "limit", "offset"}`.
+
+### `client.documents.get(document_id)`
+
+`GET /api/v1/documents/{documentId}`. Status and per-signer progress. Once `COMPLETED`, `downloadUrl` is a temporary presigned link to the signed PDF and `certificateUrl` points at the certificate endpoint. Each signer's `signUrl` is `None` until the document is sent.
+
+### `client.documents.add_signers(document_id, signers)`
+
+`POST /api/v1/documents/{documentId}/signers`. Only while the document is `PENDING`. Each signer needs `name`, `phone` (digits only, at least 10) and `email`. At most 6 signers per document.
+
+Optional custom stamp placement (PDF points, origin at the bottom-left of the page, box at least 140 x 110, one box per page):
+
+```python
+client.documents.add_signers(document_id, [{
+    "name": "Asha Rao",
+    "phone": "9876543210",
+    "email": "asha@example.com",
+    "advanced": {
+        "signaturePlacement": {
+            "positions": [{"page": 2, "x": 31, "y": 257, "width": 253, "height": 110}],
+        },
+    },
+}])
+```
+
+### `client.documents.send(document_id)`
+
+`POST /api/v1/documents/{documentId}/send`. Deducts one credit per signer, marks the document `SENT`, emails each signer a signing link and returns the links. Call it once per document.
+
+Returns `{"documentId", "status": "SENT", "creditsRemaining", "signers": [{"signerId", "name", "email", "signingOrder", "signUrl"}]}`.
+
+### `client.documents.get_certificate(document_id)`
+
+`GET /api/v1/documents/{documentId}/certificate`. Returns the completion certificate and audit trail PDF as `bytes`. Only available once the document is `COMPLETED`, otherwise it raises `SignYuError` with code `invalid_state` (409).
+
+```python
+with open("certificate.pdf", "wb") as fh:
+    fh.write(client.documents.get_certificate(document_id))
+```
+
+## Webhooks
+
+SignYu sends `signer.signed` and `document.completed` events as a JSON `POST`. Each request carries an `X-SignSetu-Signature: sha256=<hex>` header, an HMAC-SHA256 of the raw request body keyed with your endpoint's signing secret (`whsec_...`, shown in the dashboard). Always verify against the raw body bytes.
+
+```python
+import os
+from flask import Flask, request, abort
+import signyu
+
+app = Flask(__name__)
+
+@app.post("/webhooks/signyu")
+def signyu_webhook():
+    try:
+        event = signyu.webhooks.construct_event(
+            request.get_data(),  # raw bytes
+            request.headers.get("X-SignSetu-Signature"),
+            os.environ["SIGNYU_WEBHOOK_SECRET"],
+        )
+    except signyu.WebhookSignatureError:
+        abort(400)
+
+    if event["event"] == "document.completed":
+        ...  # event["certificateUrl"], event["signers"]
+    return "", 200
+```
+
+`signyu.webhooks.verify_signature(raw_body, header, secret)` returns a bool if you prefer to handle it yourself. Deliveries can repeat, so make your handler idempotent.
+
+## Errors
+
+Every non-2xx response raises `signyu.SignYuError`:
+
+```python
+from signyu import SignYuError
+
+try:
+    client.documents.send(document_id)
+except SignYuError as err:
+    print(err.status)   # 402
+    print(err.code)     # "insufficient_credits"
+    print(err.message)  # "You need 2 credits to send this document."
+```
+
+| Status | `code` | Meaning |
+| --- | --- | --- |
+| 400 | `invalid_content_type`, `invalid_request`, `invalid_file`, `no_signers`, `signer_limit_reached` | The request is invalid. |
+| 401 | `unauthorized` | Missing or invalid API key. |
+| 402 | `insufficient_credits` | Not enough credits to send. |
+| 403 | `api_access_not_enabled` | The account has no API access subscription. |
+| 404 | `not_found` | The document does not exist or is not yours. |
+| 409 | `invalid_state` | Not allowed in the document's current state. |
+| 413 | `file_too_large` | The PDF is over 10MB. |
+| 429 | `rate_limited` | Too many requests, retry with backoff. |
+| 500 | `internal_error` | Something went wrong on our side. |
+| 0 | `connection_error`, `timeout` | The request never got a response. |
+
+Retry `429` and `5xx` with backoff. Do not blindly retry `send`, since a successful send that timed out on your side would charge credits again.
+
+## Links
+
+- Docs: https://signyu.com/docs
+- API: https://signyu.com/api
+- OpenAPI spec: https://signyu.com/openapi.yaml
+- Support: contact@mail.signyu.com
+
+## License
+
+MIT

signyu-0.1.0/README.md

@@ -0,0 +1,179 @@
+# SignYu Python SDK
+
+Official Python SDK for the [SignYu](https://signyu.com) Aadhaar eSign API. Upload a PDF, add signers, and send it for legally valid Aadhaar OTP based eSignature under the IT Act 2000, all from your backend.
+
+- Python 3.9 or newer, built on `httpx`
+- Fully typed (`py.typed`, TypedDict responses)
+- Webhook signature verification with constant time comparison
+
+API docs: https://signyu.com/docs. API overview and pricing: https://signyu.com/api (signatures from ₹15 each on credit packs of 10 or more).
+
+## Install
+
+```bash
+pip install signyu
+```
+
+## Quickstart
+
+```python
+from signyu import SignYu
+
+client = SignYu(api_key="sk_live_...")  # or set SIGNYU_API_KEY
+
+# 1. Upload the PDF (a path, bytes, or a binary file object)
+doc = client.documents.create(file="agreement.pdf", name="Service Agreement")
+
+# 2. Add signers (they sign in this order, up to 6 per document)
+client.documents.add_signers(doc["documentId"], [
+    {"name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com"},
+    {"name": "Vikram Nair", "phone": "9812345678", "email": "vikram@example.com"},
+])
+
+# 3. Send: deducts one credit per signer and emails each signer a link
+sent = client.documents.send(doc["documentId"])
+print([s["signUrl"] for s in sent["signers"]])
+
+# 4. Check progress (or use webhooks)
+status = client.documents.get(doc["documentId"])
+print(status["status"])  # PENDING, SENT or COMPLETED
+```
+
+Responses are plain dicts with the API's camelCase keys, typed as `TypedDict`s in `signyu.types`.
+
+Get your API key from the dashboard under Developers (https://signyu.com/app/developers). Keep it on your server.
+
+## Configuration
+
+```python
+client = SignYu(
+    api_key="sk_live_...",          # or the SIGNYU_API_KEY environment variable
+    base_url="https://signyu.com",  # optional
+    timeout=60.0,                   # optional, seconds
+    http_client=None,               # optional, your own httpx.Client
+)
+```
+
+The client can be used as a context manager (`with SignYu(...) as client:`) or closed with `client.close()`.
+
+## Methods
+
+### `client.documents.create(file, name=None, file_name=None)`
+
+`POST /api/v1/documents`. Uploads a PDF (at most 10MB) and creates a document in `PENDING` state. `file` can be a path (`str` or `pathlib.Path`), `bytes`, or a binary file object. It is always sent as `application/pdf`. `name` defaults to the file name.
+
+Returns `{"documentId", "name", "status"}`.
+
+### `client.documents.list(limit=None, offset=None)`
+
+`GET /api/v1/documents`. Your documents, most recent first. `limit` is 1 to 100 (default 20), `offset` defaults to 0.
+
+Returns `{"documents": [{"documentId", "name", "status", "createdAt", "signers": {"total", "signed"}}], "limit", "offset"}`.
+
+### `client.documents.get(document_id)`
+
+`GET /api/v1/documents/{documentId}`. Status and per-signer progress. Once `COMPLETED`, `downloadUrl` is a temporary presigned link to the signed PDF and `certificateUrl` points at the certificate endpoint. Each signer's `signUrl` is `None` until the document is sent.
+
+### `client.documents.add_signers(document_id, signers)`
+
+`POST /api/v1/documents/{documentId}/signers`. Only while the document is `PENDING`. Each signer needs `name`, `phone` (digits only, at least 10) and `email`. At most 6 signers per document.
+
+Optional custom stamp placement (PDF points, origin at the bottom-left of the page, box at least 140 x 110, one box per page):
+
+```python
+client.documents.add_signers(document_id, [{
+    "name": "Asha Rao",
+    "phone": "9876543210",
+    "email": "asha@example.com",
+    "advanced": {
+        "signaturePlacement": {
+            "positions": [{"page": 2, "x": 31, "y": 257, "width": 253, "height": 110}],
+        },
+    },
+}])
+```
+
+### `client.documents.send(document_id)`
+
+`POST /api/v1/documents/{documentId}/send`. Deducts one credit per signer, marks the document `SENT`, emails each signer a signing link and returns the links. Call it once per document.
+
+Returns `{"documentId", "status": "SENT", "creditsRemaining", "signers": [{"signerId", "name", "email", "signingOrder", "signUrl"}]}`.
+
+### `client.documents.get_certificate(document_id)`
+
+`GET /api/v1/documents/{documentId}/certificate`. Returns the completion certificate and audit trail PDF as `bytes`. Only available once the document is `COMPLETED`, otherwise it raises `SignYuError` with code `invalid_state` (409).
+
+```python
+with open("certificate.pdf", "wb") as fh:
+    fh.write(client.documents.get_certificate(document_id))
+```
+
+## Webhooks
+
+SignYu sends `signer.signed` and `document.completed` events as a JSON `POST`. Each request carries an `X-SignSetu-Signature: sha256=<hex>` header, an HMAC-SHA256 of the raw request body keyed with your endpoint's signing secret (`whsec_...`, shown in the dashboard). Always verify against the raw body bytes.
+
+```python
+import os
+from flask import Flask, request, abort
+import signyu
+
+app = Flask(__name__)
+
+@app.post("/webhooks/signyu")
+def signyu_webhook():
+    try:
+        event = signyu.webhooks.construct_event(
+            request.get_data(),  # raw bytes
+            request.headers.get("X-SignSetu-Signature"),
+            os.environ["SIGNYU_WEBHOOK_SECRET"],
+        )
+    except signyu.WebhookSignatureError:
+        abort(400)
+
+    if event["event"] == "document.completed":
+        ...  # event["certificateUrl"], event["signers"]
+    return "", 200
+```
+
+`signyu.webhooks.verify_signature(raw_body, header, secret)` returns a bool if you prefer to handle it yourself. Deliveries can repeat, so make your handler idempotent.
+
+## Errors
+
+Every non-2xx response raises `signyu.SignYuError`:
+
+```python
+from signyu import SignYuError
+
+try:
+    client.documents.send(document_id)
+except SignYuError as err:
+    print(err.status)   # 402
+    print(err.code)     # "insufficient_credits"
+    print(err.message)  # "You need 2 credits to send this document."
+```
+
+| Status | `code` | Meaning |
+| --- | --- | --- |
+| 400 | `invalid_content_type`, `invalid_request`, `invalid_file`, `no_signers`, `signer_limit_reached` | The request is invalid. |
+| 401 | `unauthorized` | Missing or invalid API key. |
+| 402 | `insufficient_credits` | Not enough credits to send. |
+| 403 | `api_access_not_enabled` | The account has no API access subscription. |
+| 404 | `not_found` | The document does not exist or is not yours. |
+| 409 | `invalid_state` | Not allowed in the document's current state. |
+| 413 | `file_too_large` | The PDF is over 10MB. |
+| 429 | `rate_limited` | Too many requests, retry with backoff. |
+| 500 | `internal_error` | Something went wrong on our side. |
+| 0 | `connection_error`, `timeout` | The request never got a response. |
+
+Retry `429` and `5xx` with backoff. Do not blindly retry `send`, since a successful send that timed out on your side would charge credits again.
+
+## Links
+
+- Docs: https://signyu.com/docs
+- API: https://signyu.com/api
+- OpenAPI spec: https://signyu.com/openapi.yaml
+- Support: contact@mail.signyu.com
+
+## License
+
+MIT

signyu-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "signyu"
+version = "0.1.0"
+description = "Official Python SDK for the SignYu Aadhaar eSign API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "SignYu", email = "contact@mail.signyu.com" }]
+keywords = [
+  "aadhaar",
+  "esign",
+  "aadhaar-esign",
+  "e-signature",
+  "digital-signature",
+  "india",
+  "emudhra",
+  "signyu",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.24,<1",
+  "typing_extensions>=4.5; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://signyu.com/api"
+Documentation = "https://signyu.com/docs"
+"Bug Tracker" = "https://signyu.com/contact"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/signyu"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/signyu", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

signyu-0.1.0/src/signyu/__init__.py

@@ -0,0 +1,17 @@
+"""Official Python SDK for the SignYu Aadhaar eSign API (https://signyu.com/api)."""
+
+from . import types, webhooks
+from ._client import DEFAULT_BASE_URL, Documents, SignYu
+from ._errors import SignYuError, WebhookSignatureError
+from ._version import __version__
+
+__all__ = [
+    "SignYu",
+    "Documents",
+    "SignYuError",
+    "WebhookSignatureError",
+    "DEFAULT_BASE_URL",
+    "webhooks",
+    "types",
+    "__version__",
+]

signyu-0.1.0/src/signyu/_client.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import IO, Any, Dict, List, Mapping, Optional, Sequence, Union, cast
+from urllib.parse import quote
+
+import httpx
+
+from . import webhooks as _webhooks
+from ._errors import SignYuError
+from ._version import __version__
+from .types import (
+    AddSignersResponse,
+    CreatedDocument,
+    Document,
+    DocumentList,
+    SendDocumentResponse,
+    SignerInput,
+)
+
+DEFAULT_BASE_URL = "https://signyu.com"
+DEFAULT_TIMEOUT = 60.0
+
+FileInput = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, IO[bytes]]
+
+
+def _doc_path(document_id: str, suffix: str = "") -> str:
+    return f"/api/v1/documents/{quote(document_id, safe='')}{suffix}"
+
+
+def _read_file(file: FileInput, file_name: Optional[str]) -> "tuple[str, bytes]":
+    if isinstance(file, (bytes, bytearray, memoryview)):
+        return file_name or "document.pdf", bytes(file)
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        with open(path, "rb") as fh:
+            return file_name or os.path.basename(path), fh.read()
+    if hasattr(file, "read"):
+        data = file.read()
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError("File objects must be opened in binary mode ('rb').")
+        default_name = os.path.basename(str(getattr(file, "name", ""))) or "document.pdf"
+        return file_name or default_name, bytes(data)
+    raise TypeError("file must be a path, bytes, or a binary file object.")
+
+
+class Documents:
+    """The ``/api/v1/documents`` resource."""
+
+    def __init__(self, client: "SignYu") -> None:
+        self._client = client
+
+    def create(
+        self,
+        file: FileInput,
+        name: Optional[str] = None,
+        file_name: Optional[str] = None,
+    ) -> CreatedDocument:
+        """Upload a PDF (at most 10MB) and create a ``PENDING`` document.
+
+        ``file`` can be a path, bytes, or a binary file object. ``name``
+        defaults to the file name.
+        """
+        fname, content = _read_file(file, file_name)
+        data: Dict[str, str] = {}
+        if name is not None:
+            data["name"] = name
+        return cast(
+            CreatedDocument,
+            self._client._request(
+                "POST",
+                "/api/v1/documents",
+                files={"file": (fname, content, "application/pdf")},
+                data=data or None,
+            ),
+        )
+
+    def list(self, limit: Optional[int] = None, offset: Optional[int] = None) -> DocumentList:
+        """Your documents, most recent first. ``limit`` 1 to 100 (default 20)."""
+        params: Dict[str, int] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        return cast(DocumentList, self._client._request("GET", "/api/v1/documents", params=params or None))
+
+    def get(self, document_id: str) -> Document:
+        """Document status and per-signer progress."""
+        return cast(Document, self._client._request("GET", _doc_path(document_id)))
+
+    def add_signers(
+        self, document_id: str, signers: Sequence[Union[SignerInput, Mapping[str, Any]]]
+    ) -> AddSignersResponse:
+        """Add signers while the document is ``PENDING`` (max 6 per document)."""
+        return cast(
+            AddSignersResponse,
+            self._client._request(
+                "POST", _doc_path(document_id, "/signers"), json={"signers": [dict(s) for s in signers]}
+            ),
+        )
+
+    def send(self, document_id: str) -> SendDocumentResponse:
+        """Deduct one credit per signer, email signing links and return them.
+
+        Not idempotent: call it once per document.
+        """
+        return cast(SendDocumentResponse, self._client._request("POST", _doc_path(document_id, "/send")))
+
+    def get_certificate(self, document_id: str) -> bytes:
+        """Completion certificate and audit trail PDF bytes (only once ``COMPLETED``)."""
+        return cast(
+            bytes,
+            self._client._request("GET", _doc_path(document_id, "/certificate"), binary=True),
+        )
+
+
+class SignYu:
+    """SignYu API client.
+
+    >>> client = SignYu(api_key="sk_live_...")
+    >>> client.documents.list()
+    """
+
+    webhooks = _webhooks
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("SIGNYU_API_KEY")
+        if not api_key:
+            raise ValueError("SignYu requires an api_key (or the SIGNYU_API_KEY environment variable).")
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.documents = Documents(self)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "SignYu":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+        data: Optional[Mapping[str, str]] = None,
+        files: Optional[Mapping[str, Any]] = None,
+        binary: bool = False,
+    ) -> Any:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/pdf" if binary else "application/json",
+            "User-Agent": f"signyu-python/{__version__}",
+        }
+        try:
+            res = self._http.request(
+                method,
+                self.base_url + path,
+                params=params,
+                json=json,
+                data=data,
+                files=files,
+                headers=headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise SignYuError(0, "timeout", f"Request timed out: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise SignYuError(0, "connection_error", f"Could not reach the SignYu API: {exc}") from exc
+
+        if res.status_code >= 400:
+            raise _error_from_response(res)
+        if binary:
+            return res.content
+        return res.json()
+
+
+def _error_from_response(res: httpx.Response) -> SignYuError:
+    body: Any = None
+    try:
+        body = res.json()
+    except (json.JSONDecodeError, ValueError):
+        body = res.text or None
+    code = "rate_limited" if res.status_code == 429 else "http_error"
+    message = f"SignYu API request failed with status {res.status_code}."
+    if isinstance(body, dict):
+        if isinstance(body.get("error"), str):
+            code = body["error"]
+        if isinstance(body.get("message"), str):
+            message = body["message"]
+    return SignYuError(res.status_code, code, message, body)
+
+
+__all__: List[str] = ["SignYu", "Documents", "DEFAULT_BASE_URL"]

signyu-0.1.0/src/signyu/_errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SignYuError(Exception):
+    """Raised for any non-2xx API response, network failure or timeout.
+
+    ``code`` is the API's machine readable ``error`` field (for example
+    ``insufficient_credits``). For responses without a JSON error body it is
+    ``rate_limited`` (429) or ``http_error``. Network failures use
+    ``connection_error`` and timeouts ``timeout``, both with ``status`` 0.
+    """
+
+    def __init__(self, status: int, code: str, message: str, body: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.body = body
+
+    def __repr__(self) -> str:
+        return f"SignYuError(status={self.status!r}, code={self.code!r}, message={self.message!r})"
+
+
+class WebhookSignatureError(Exception):
+    """Raised by ``signyu.webhooks.construct_event`` when the signature does not match."""
+
+    def __init__(self, message: str = "Webhook signature verification failed.") -> None:
+        super().__init__(message)

signyu-0.1.0/src/signyu/_version.py

@@ -0,0 +1,2 @@
+# Keep in sync with pyproject.toml "version".
+__version__ = "0.1.0"

signyu-0.1.0/src/signyu/types.py

@@ -0,0 +1,154 @@
+"""TypedDicts mirroring the SignYu REST API JSON (camelCase keys, as returned).
+
+Timestamps are ISO 8601 strings.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional, Union
+
+if sys.version_info >= (3, 11):
+    from typing import Literal, NotRequired, TypedDict
+else:  # pragma: no cover
+    from typing import Literal
+
+    from typing_extensions import NotRequired, TypedDict
+
+# PENDING, SENT, COMPLETED (FAILED and CANCELLED are reserved).
+DocumentStatus = str
+
+
+class SignaturePosition(TypedDict):
+    page: int
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+class SignaturePlacement(TypedDict):
+    positions: List[SignaturePosition]
+
+
+class SignerAdvanced(TypedDict, total=False):
+    signaturePlacement: SignaturePlacement
+
+
+class SignerInput(TypedDict):
+    name: str
+    phone: str
+    email: str
+    advanced: NotRequired[SignerAdvanced]
+
+
+class CreatedDocument(TypedDict):
+    documentId: str
+    name: str
+    status: DocumentStatus
+
+
+class SignerCounts(TypedDict):
+    total: int
+    signed: int
+
+
+class DocumentSummary(TypedDict):
+    documentId: str
+    name: str
+    status: DocumentStatus
+    createdAt: str
+    signers: SignerCounts
+
+
+class DocumentList(TypedDict):
+    documents: List[DocumentSummary]
+    limit: int
+    offset: int
+
+
+class _PlacementEcho(TypedDict):
+    signaturePlacement: SignaturePlacement
+
+
+class DocumentSigner(TypedDict):
+    signerId: str
+    name: str
+    email: Optional[str]
+    phone: str
+    signingOrder: int
+    openedAt: Optional[str]
+    signedAt: Optional[str]
+    hasSigned: bool
+    signUrl: Optional[str]
+    advanced: NotRequired[_PlacementEcho]
+
+
+class Document(TypedDict):
+    documentId: str
+    name: str
+    status: DocumentStatus
+    createdAt: str
+    updatedAt: str
+    completedAt: Optional[str]
+    downloadUrl: Optional[str]
+    certificateUrl: Optional[str]
+    signers: List[DocumentSigner]
+
+
+class AddedSigner(TypedDict):
+    signerId: str
+    name: str
+    email: Optional[str]
+    signingOrder: int
+    advanced: NotRequired[_PlacementEcho]
+
+
+class AddSignersResponse(TypedDict):
+    signers: List[AddedSigner]
+
+
+class SentSigner(TypedDict):
+    signerId: str
+    name: str
+    email: Optional[str]
+    signingOrder: int
+    signUrl: str
+
+
+class SendDocumentResponse(TypedDict):
+    documentId: str
+    status: Literal["SENT"]
+    creditsRemaining: int
+    signers: List[SentSigner]
+
+
+class WebhookSigner(TypedDict):
+    signerId: str
+    name: str
+    email: Optional[str]
+    signingOrder: int
+    signedAt: Optional[str]
+    hasSigned: bool
+
+
+class SignerSignedEvent(TypedDict):
+    event: Literal["signer.signed"]
+    documentId: str
+    status: DocumentStatus
+    occurredAt: str
+    signer: Optional[WebhookSigner]
+    signers: List[WebhookSigner]
+
+
+class DocumentCompletedEvent(TypedDict):
+    event: Literal["document.completed"]
+    documentId: str
+    status: DocumentStatus
+    occurredAt: str
+    completedAt: Optional[str]
+    certificateUrl: str
+    signers: List[WebhookSigner]
+
+
+WebhookEvent = Union[SignerSignedEvent, DocumentCompletedEvent]

signyu-0.1.0/src/signyu/webhooks.py

@@ -0,0 +1,63 @@
+"""Webhook signature verification.
+
+SignYu signs every delivery with HMAC-SHA256 over the raw request body using
+the endpoint's signing secret, and sends it as ``X-SignSetu-Signature:
+sha256=<hex>``. There is no timestamp in the signed payload.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Optional, Union, cast
+
+from ._errors import WebhookSignatureError
+from .types import WebhookEvent
+
+SIGNATURE_HEADER = "X-SignSetu-Signature"
+EVENT_HEADER = "X-SignSetu-Event"
+
+Payload = Union[bytes, bytearray, memoryview, str]
+
+
+def _to_bytes(payload: Payload) -> bytes:
+    if isinstance(payload, str):
+        return payload.encode("utf-8")
+    return bytes(payload)
+
+
+def compute_signature(payload: Payload, secret: str) -> str:
+    """Return the ``sha256=<hex>`` header value SignYu sends for ``payload``."""
+    digest = hmac.new(secret.encode("utf-8"), _to_bytes(payload), hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+def verify_signature(payload: Payload, signature_header: Optional[str], secret: str) -> bool:
+    """Return True if ``signature_header`` is valid for the raw body ``payload``.
+
+    Pass the raw request body exactly as received. Comparison is constant time.
+    """
+    if not signature_header or not secret:
+        return False
+    expected = compute_signature(payload, secret)
+    return hmac.compare_digest(expected.encode("utf-8"), signature_header.strip().encode("utf-8"))
+
+
+def construct_event(payload: Payload, signature_header: Optional[str], secret: str) -> WebhookEvent:
+    """Verify the signature and return the parsed event dict.
+
+    Raises ``WebhookSignatureError`` if the signature is missing or invalid.
+    """
+    if not verify_signature(payload, signature_header, secret):
+        raise WebhookSignatureError()
+    return cast(WebhookEvent, json.loads(_to_bytes(payload).decode("utf-8")))
+
+
+__all__ = [
+    "SIGNATURE_HEADER",
+    "EVENT_HEADER",
+    "compute_signature",
+    "verify_signature",
+    "construct_event",
+]

signyu-0.1.0/tests/fixtures/webhook.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "Generated by running the exact algorithm in src/lib/webhooks/dispatch.ts (HMAC-SHA256 hex over JSON.stringify({ event, ...payload })). Do not hand-edit.",
+  "secret": "whsec_test_9d2Kq7xVbN4mP1sR8tYuW3zA6cE5fH0j",
+  "body": "{\"event\":\"document.completed\",\"documentId\":\"b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c\",\"status\":\"COMPLETED\",\"occurredAt\":\"2026-07-17T07:15:00.000Z\",\"completedAt\":\"2026-07-17T07:15:00.000Z\",\"certificateUrl\":\"https://signyu.com/api/v1/documents/b6b1f0e2-1c9a-4a1e-9b1a-2f3d4e5a6b7c/certificate\",\"signers\":[{\"signerId\":\"s_1\",\"name\":\"Asha Rao\",\"email\":\"asha@example.com\",\"signingOrder\":1,\"signedAt\":\"2026-07-17T07:05:00.000Z\",\"hasSigned\":true}]}",
+  "header": "sha256=6e87c8c0b0765af4a6531143cc46099ebb5e00a18e4b98ffe18b5f8bf84a9bb5"
+}

signyu-0.1.0/tests/test_client.py

@@ -0,0 +1,143 @@
+import io
+import json
+
+import httpx
+import pytest
+
+from signyu import SignYu, SignYuError
+
+# Every request goes through httpx.MockTransport; nothing touches the network.
+
+
+def make_client(handler, **kwargs):
+    calls = []
+
+    def wrapped(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return handler(request)
+
+    http = httpx.Client(transport=httpx.MockTransport(wrapped))
+    return SignYu(api_key="sk_live_abc", http_client=http, **kwargs), calls
+
+
+def test_requires_api_key(monkeypatch):
+    monkeypatch.delenv("SIGNYU_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        SignYu()
+
+
+def test_create_sends_multipart_pdf(tmp_path):
+    client, calls = make_client(
+        lambda r: httpx.Response(201, json={"documentId": "doc_1", "name": "Service Agreement", "status": "PENDING"})
+    )
+    res = client.documents.create(file=b"%PDF-1.4 test", name="Service Agreement", file_name="agreement.pdf")
+    assert res == {"documentId": "doc_1", "name": "Service Agreement", "status": "PENDING"}
+
+    req = calls[0]
+    assert req.method == "POST"
+    assert str(req.url) == "https://signyu.com/api/v1/documents"
+    assert req.headers["authorization"] == "Bearer sk_live_abc"
+    assert req.headers["content-type"].startswith("multipart/form-data; boundary=")
+    body = req.content
+    assert b'name="file"; filename="agreement.pdf"' in body
+    assert b"Content-Type: application/pdf" in body
+    assert b"%PDF-1.4 test" in body
+    assert b'name="name"' in body and b"Service Agreement" in body
+
+
+def test_create_accepts_path_and_file_object(tmp_path):
+    pdf = tmp_path / "contract.pdf"
+    pdf.write_bytes(b"%PDF-path")
+    client, calls = make_client(lambda r: httpx.Response(201, json={"documentId": "d", "name": "x", "status": "PENDING"}))
+
+    client.documents.create(file=str(pdf))
+    assert b'filename="contract.pdf"' in calls[0].content
+    assert b"%PDF-path" in calls[0].content
+    assert b'name="name"' not in calls[0].content
+
+    client.documents.create(file=pdf)
+    assert b'filename="contract.pdf"' in calls[1].content
+
+    client.documents.create(file=io.BytesIO(b"%PDF-stream"))
+    assert b'filename="document.pdf"' in calls[2].content
+    assert b"%PDF-stream" in calls[2].content
+
+
+def test_list_params_and_base_url():
+    client, calls = make_client(
+        lambda r: httpx.Response(200, json={"documents": [], "limit": 5, "offset": 10}),
+        base_url="http://localhost:3000/",
+    )
+    client.documents.list(limit=5, offset=10)
+    assert str(calls[0].url) == "http://localhost:3000/api/v1/documents?limit=5&offset=10"
+    client.documents.list()
+    assert str(calls[1].url) == "http://localhost:3000/api/v1/documents"
+
+
+def test_get_add_signers_send_urls_and_bodies():
+    client, calls = make_client(lambda r: httpx.Response(200, json={"ok": True}))
+
+    client.documents.get("doc 1")
+    assert calls[0].url.raw_path == b"/api/v1/documents/doc%201"
+
+    signers = [
+        {"name": "Asha Rao", "phone": "9876543210", "email": "asha@example.com"},
+        {
+            "name": "Vikram Nair",
+            "phone": "9812345678",
+            "email": "vikram@example.com",
+            "advanced": {"signaturePlacement": {"positions": [{"page": 1, "x": 31, "y": 239, "width": 253, "height": 110}]}},
+        },
+    ]
+    client.documents.add_signers("doc_1", signers)
+    req = calls[1]
+    assert req.method == "POST"
+    assert str(req.url) == "https://signyu.com/api/v1/documents/doc_1/signers"
+    assert req.headers["content-type"] == "application/json"
+    assert json.loads(req.content) == {"signers": signers}
+
+    client.documents.send("doc_1")
+    req = calls[2]
+    assert req.method == "POST"
+    assert str(req.url) == "https://signyu.com/api/v1/documents/doc_1/send"
+    assert req.content == b""
+
+
+def test_get_certificate_returns_bytes():
+    client, calls = make_client(
+        lambda r: httpx.Response(200, content=b"%PDF", headers={"Content-Type": "application/pdf"})
+    )
+    assert client.documents.get_certificate("doc_1") == b"%PDF"
+    assert str(calls[0].url) == "https://signyu.com/api/v1/documents/doc_1/certificate"
+
+
+def test_api_error_shape():
+    client, _ = make_client(
+        lambda r: httpx.Response(
+            402, json={"error": "insufficient_credits", "message": "You need 2 credits to send this document."}
+        )
+    )
+    with pytest.raises(SignYuError) as exc:
+        client.documents.send("doc_1")
+    assert exc.value.status == 402
+    assert exc.value.code == "insufficient_credits"
+    assert exc.value.message == "You need 2 credits to send this document."
+
+
+def test_non_json_429():
+    client, _ = make_client(lambda r: httpx.Response(429, text="Too Many Requests"))
+    with pytest.raises(SignYuError) as exc:
+        client.documents.list()
+    assert exc.value.status == 429
+    assert exc.value.code == "rate_limited"
+
+
+def test_connection_error():
+    def boom(request):
+        raise httpx.ConnectError("refused", request=request)
+
+    client, _ = make_client(boom)
+    with pytest.raises(SignYuError) as exc:
+        client.documents.get("x")
+    assert exc.value.status == 0
+    assert exc.value.code == "connection_error"

signyu-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,50 @@
+import json
+from pathlib import Path
+
+import pytest
+
+import signyu
+from signyu import SignYu, WebhookSignatureError
+from signyu.webhooks import SIGNATURE_HEADER, compute_signature, construct_event, verify_signature
+
+# Generated with the exact algorithm in src/lib/webhooks/dispatch.ts.
+FIXTURE = json.loads((Path(__file__).parent / "fixtures" / "webhook.json").read_text())
+BODY = FIXTURE["body"]
+SECRET = FIXTURE["secret"]
+HEADER = FIXTURE["header"]
+
+
+def test_matches_server_fixture():
+    assert SIGNATURE_HEADER == "X-SignSetu-Signature"
+    assert compute_signature(BODY, SECRET) == HEADER
+    assert verify_signature(BODY, HEADER, SECRET)
+    assert verify_signature(BODY.encode(), HEADER, SECRET)
+    assert signyu.webhooks.verify_signature(BODY, HEADER, SECRET)
+
+
+@pytest.mark.parametrize(
+    "body,header,secret",
+    [
+        (BODY + " ", HEADER, SECRET),
+        (BODY, HEADER, "whsec_wrong"),
+        (BODY, "sha256=abc", SECRET),
+        (BODY, None, SECRET),
+        (BODY, HEADER.replace("sha256=", ""), SECRET),
+    ],
+)
+def test_rejects_invalid(body, header, secret):
+    assert verify_signature(body, header, secret) is False
+
+
+def test_construct_event():
+    event = construct_event(BODY, HEADER, SECRET)
+    assert event["event"] == "document.completed"
+    assert event["signers"][0]["signerId"] == "s_1"
+    with pytest.raises(WebhookSignatureError):
+        construct_event(BODY, "sha256=00", SECRET)
+
+
+def test_client_exposes_webhooks():
+    client = SignYu(api_key="sk_live_test")
+    assert client.webhooks.verify_signature(BODY, HEADER, SECRET)
+    client.close()