signwell-sdk-python 0.1.0__py3-none-any.whl

signwell_sdk/models/validation_error_response.py

@@ -0,0 +1,99 @@
+"""
+SignWell Developer API
+
+API for creating, managing, and tracking electronic signature workflows.
+
+The version of the OpenAPI document: v1
+Contact: support@signwell.com
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""  # noqa: E501
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Any, ClassVar, Dict, List
+from typing import Any, Optional, Set
+from typing_extensions import Self
+
+
+class ValidationErrorResponse(BaseModel):
+    """
+    Validation error response. The errors object contains field-specific error details with dynamic keys.
+    """  # noqa: E501
+
+    errors: Dict[str, Any] = Field(
+        description="Field-specific validation errors. Keys are field names (e.g., recipients, fields, files). Values can be strings, arrays of strings, or nested objects with further field-specific errors."
+    )
+    additional_properties: Dict[str, Any] = {}
+    __properties: ClassVar[List[str]] = ["errors"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self | None:
+        """Create an instance of ValidationErrorResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        * Fields in `self.additional_properties` are added to the output dict.
+        """
+        excluded_fields: Set[str] = set(
+            [
+                "additional_properties",
+            ]
+        )
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # puts key-value pairs in additional_properties in the top level
+        if self.additional_properties is not None:
+            for _key, _value in self.additional_properties.items():
+                _dict[_key] = _value
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Dict[str, Any] | None) -> Self | None:
+        """Create an instance of ValidationErrorResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({"errors": obj.get("errors")})
+        # store additional fields in additional_properties
+        for _key in obj.keys():
+            if _key not in cls.__properties:
+                _obj.additional_properties[_key] = obj.get(_key)
+
+        return _obj

signwell_sdk/models/webhook_response.py

@@ -0,0 +1,110 @@
+"""
+SignWell Developer API
+
+API for creating, managing, and tracking electronic signature workflows.
+
+The version of the OpenAPI document: v1
+Contact: support@signwell.com
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""  # noqa: E501
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, StrictStr
+from typing import Any, ClassVar, Dict, List, Optional
+from typing import Any, Optional, Set
+from typing_extensions import Self
+
+
+class WebhookResponse(BaseModel):
+    """
+    Webhook subscription
+    """  # noqa: E501
+
+    id: StrictStr
+    callback_url: StrictStr
+    api_application_id: StrictStr | None = None
+    additional_properties: Dict[str, Any] = {}
+    __properties: ClassVar[List[str]] = ["id", "callback_url", "api_application_id"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Self | None:
+        """Create an instance of WebhookResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        * Fields in `self.additional_properties` are added to the output dict.
+        """
+        excluded_fields: Set[str] = set(
+            [
+                "additional_properties",
+            ]
+        )
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        # puts key-value pairs in additional_properties in the top level
+        if self.additional_properties is not None:
+            for _key, _value in self.additional_properties.items():
+                _dict[_key] = _value
+
+        # set to None if api_application_id (nullable) is None
+        # and model_fields_set contains the field
+        if self.api_application_id is None and "api_application_id" in self.model_fields_set:
+            _dict["api_application_id"] = None
+
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Dict[str, Any] | None) -> Self | None:
+        """Create an instance of WebhookResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate(
+            {
+                "id": obj.get("id"),
+                "callback_url": obj.get("callback_url"),
+                "api_application_id": obj.get("api_application_id"),
+            }
+        )
+        # store additional fields in additional_properties
+        for _key in obj.keys():
+            if _key not in cls.__properties:
+                _obj.additional_properties[_key] = obj.get(_key)
+
+        return _obj

signwell_sdk/rest.py

@@ -0,0 +1,209 @@
+"""
+SignWell Developer API
+
+API for creating, managing, and tracking electronic signature workflows.
+
+The version of the OpenAPI document: v1
+Contact: support@signwell.com
+Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+Do not edit the class manually.
+"""  # noqa: E501
+
+import io
+import json
+import re
+import ssl
+
+import urllib3
+
+from signwell_sdk.exceptions import ApiConnectionError, ApiException, ApiTimeoutError, ApiValueError
+
+SUPPORTED_SOCKS_PROXIES = {"socks5", "socks5h", "socks4", "socks4a"}
+RESTResponseType = urllib3.HTTPResponse
+
+
+def is_socks_proxy_url(url):
+    if url is None:
+        return False
+    split_section = url.split("://")
+    if len(split_section) < 2:
+        return False
+    else:
+        return split_section[0].lower() in SUPPORTED_SOCKS_PROXIES
+
+
+class RESTResponse(io.IOBase):
+    def __init__(self, resp) -> None:
+        self.response = resp
+        self.status = resp.status
+        self.reason = resp.reason
+        self.data = None
+
+    def read(self):
+        if self.data is None:
+            self.data = self.response.data
+        return self.data
+
+    def getheaders(self):
+        """Returns a dictionary of the response headers."""
+        return self.response.headers
+
+    def getheader(self, name, default=None):
+        """Returns a given response header."""
+        return self.response.headers.get(name, default)
+
+
+class RESTClientObject:
+    def __init__(self, configuration) -> None:
+        # urllib3.PoolManager will pass all kw parameters to connectionpool
+        # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75  # noqa: E501
+        # https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680  # noqa: E501
+        # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html  # noqa: E501
+
+        # cert_reqs
+        if configuration.verify_ssl:
+            cert_reqs = ssl.CERT_REQUIRED
+        else:
+            cert_reqs = ssl.CERT_NONE
+
+        pool_args = {
+            "cert_reqs": cert_reqs,
+            "ca_certs": configuration.ssl_ca_cert,
+            "cert_file": configuration.cert_file,
+            "key_file": configuration.key_file,
+            "ca_cert_data": configuration.ca_cert_data,
+        }
+        if configuration.assert_hostname is not None:
+            pool_args["assert_hostname"] = configuration.assert_hostname
+
+        if configuration.retries is not None:
+            pool_args["retries"] = configuration.retries
+
+        if configuration.tls_server_name:
+            pool_args["server_hostname"] = configuration.tls_server_name
+
+        if configuration.socket_options is not None:
+            pool_args["socket_options"] = configuration.socket_options
+
+        if configuration.connection_pool_maxsize is not None:
+            pool_args["maxsize"] = configuration.connection_pool_maxsize
+
+        # https pool manager
+        self.pool_manager: urllib3.PoolManager
+
+        if configuration.proxy:
+            if is_socks_proxy_url(configuration.proxy):
+                from urllib3.contrib.socks import SOCKSProxyManager
+
+                pool_args["proxy_url"] = configuration.proxy
+                pool_args["headers"] = configuration.proxy_headers
+                self.pool_manager = SOCKSProxyManager(**pool_args)
+            else:
+                pool_args["proxy_url"] = configuration.proxy
+                pool_args["proxy_headers"] = configuration.proxy_headers
+                self.pool_manager = urllib3.ProxyManager(**pool_args)
+        else:
+            self.pool_manager = urllib3.PoolManager(**pool_args)
+
+    def request(self, method, url, headers=None, body=None, post_params=None, _request_timeout=None):
+        """Perform requests.
+
+        :param method: http request method
+        :param url: http request url
+        :param headers: http request headers
+        :param body: request json body, for `application/json`
+        :param post_params: request post parameters,
+                            `application/x-www-form-urlencoded`
+                            and `multipart/form-data`
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        """
+        method = method.upper()
+        if method not in ["GET", "HEAD", "DELETE", "POST", "PUT", "PATCH", "OPTIONS"]:
+            raise ApiValueError(f"Unsupported HTTP method: {method}")
+
+        if post_params and body:
+            raise ApiValueError("body parameter cannot be used with post_params parameter.")
+
+        post_params = post_params or {}
+        headers = headers or {}
+
+        timeout = None
+        if _request_timeout:
+            if isinstance(_request_timeout, (int, float)):
+                timeout = urllib3.Timeout(total=_request_timeout)
+            elif isinstance(_request_timeout, tuple) and len(_request_timeout) == 2:
+                timeout = urllib3.Timeout(connect=_request_timeout[0], read=_request_timeout[1])
+
+        try:
+            # For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE`
+            if method in ["POST", "PUT", "PATCH", "OPTIONS", "DELETE"]:
+                # no content type provided or payload is json
+                content_type = headers.get("Content-Type")
+                if not content_type or re.search("json", content_type, re.IGNORECASE):
+                    request_body = None
+                    if body is not None:
+                        request_body = json.dumps(body)
+                    r = self.pool_manager.request(
+                        method, url, body=request_body, timeout=timeout, headers=headers, preload_content=False
+                    )
+                elif content_type == "application/x-www-form-urlencoded":
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        fields=post_params,
+                        encode_multipart=False,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                elif content_type == "multipart/form-data":
+                    # must del headers['Content-Type'], or the correct
+                    # Content-Type which generated by urllib3 will be
+                    # overwritten.
+                    del headers["Content-Type"]
+                    # Ensures that dict objects are serialized
+                    post_params = [(a, json.dumps(b)) if isinstance(b, dict) else (a, b) for a, b in post_params]
+                    r = self.pool_manager.request(
+                        method,
+                        url,
+                        fields=post_params,
+                        encode_multipart=True,
+                        timeout=timeout,
+                        headers=headers,
+                        preload_content=False,
+                    )
+                # Pass a `string` parameter directly in the body to support
+                # other content types than JSON when `body` argument is
+                # provided in serialized form.
+                elif isinstance(body, str) or isinstance(body, bytes):
+                    r = self.pool_manager.request(
+                        method, url, body=body, timeout=timeout, headers=headers, preload_content=False
+                    )
+                elif headers["Content-Type"].startswith("text/") and isinstance(body, bool):
+                    request_body = "true" if body else "false"
+                    r = self.pool_manager.request(
+                        method, url, body=request_body, preload_content=False, timeout=timeout, headers=headers
+                    )
+                else:
+                    # Cannot generate the request from given parameters
+                    msg = """Cannot prepare a request message for provided
+                             arguments. Please check that your arguments match
+                             declared content type."""
+                    raise ApiException(status=0, reason=msg)
+            # For `GET`, `HEAD`
+            else:
+                r = self.pool_manager.request(
+                    method, url, fields={}, timeout=timeout, headers=headers, preload_content=False
+                )
+        except urllib3.exceptions.TimeoutError as e:
+            msg = "\n".join([type(e).__name__, str(e)])
+            raise ApiTimeoutError(status=0, reason=msg) from e
+        except urllib3.exceptions.HTTPError as e:
+            msg = "\n".join([type(e).__name__, str(e)])
+            raise ApiConnectionError(status=0, reason=msg) from e
+
+        return RESTResponse(r)

signwell_sdk/webhook.py

@@ -0,0 +1,214 @@
+# Source: signwell-sdk-generator/extras/python/overlay/signwell_sdk/webhook.py
+# Do not edit the generated SDK copy directly.
+
+from __future__ import annotations
+
+import hmac
+import time as time_module
+from collections.abc import Callable, Mapping
+from threading import Lock
+from typing import Any, Protocol
+
+
+class ReplayStore(Protocol):
+    def add(self, key: str, expires_at_unix_seconds: float) -> bool:
+        """Atomically store key until expires_at_unix_seconds if it does not exist."""
+
+
+class MemoryReplayStore:
+    """Small replay store for local development and single-process apps.
+
+    When capacity is exhausted by still-live entries, new events fail closed
+    instead of evicting active replay keys.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_entries: int = 10_000,
+        now: Callable[[], float] | None = None,
+    ) -> None:
+        if not isinstance(max_entries, int) or max_entries <= 0:
+            raise ValueError("max_entries must be a positive integer")
+
+        self._max_entries = max_entries
+        self._now = now or _current_unix_time
+        self._entries: dict[str, float] = {}
+        self._lock = Lock()
+
+    def add(self, key: str, expires_at_unix_seconds: float) -> bool:
+        with self._lock:
+            current_time = self._now()
+            expired = [entry_key for entry_key, expires_at in self._entries.items() if expires_at < current_time]
+            for entry_key in expired:
+                del self._entries[entry_key]
+
+            if key in self._entries:
+                return False
+
+            if len(self._entries) >= self._max_entries:
+                return False
+
+            self._entries[key] = float(expires_at_unix_seconds)
+            return True
+
+
+def verify_event(
+    *,
+    event: Mapping[str, Any],
+    webhook_id: str,
+    tolerance_seconds: float | None = None,
+    now: Callable[[], float] | None = None,
+) -> bool:
+    try:
+        verify_event_or_raise(
+            event=event,
+            webhook_id=webhook_id,
+            tolerance_seconds=tolerance_seconds,
+            now=now,
+        )
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def verify_event_once(
+    *,
+    event: Mapping[str, Any],
+    webhook_id: str,
+    replay_store: ReplayStore,
+    tolerance_seconds: float | None,
+    now: Callable[[], float] | None = None,
+) -> bool:
+    try:
+        verify_event_once_or_raise(
+            event=event,
+            webhook_id=webhook_id,
+            replay_store=replay_store,
+            tolerance_seconds=tolerance_seconds,
+            now=now,
+        )
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def verify_event_once_or_raise(
+    *,
+    event: Mapping[str, Any],
+    webhook_id: str,
+    replay_store: ReplayStore,
+    tolerance_seconds: float | None,
+    now: Callable[[], float] | None = None,
+) -> bool:
+    if tolerance_seconds is None:
+        raise ValueError("tolerance_seconds is required for replay protection")
+    if replay_store is None or not callable(getattr(replay_store, "add", None)):
+        raise TypeError("replay_store with an atomic add method is required")
+
+    parsed = _verify_event_data(
+        event=event,
+        webhook_id=webhook_id,
+        tolerance_seconds=tolerance_seconds,
+        now=now,
+    )
+    expires_at = float(parsed["time"]) + float(tolerance_seconds)
+    if not replay_store.add(_replay_key_from_parsed(parsed), expires_at):
+        raise ValueError("webhook event has already been processed or replay store capacity was exceeded")
+    return True
+
+
+def verify_event_or_raise(
+    *,
+    event: Mapping[str, Any],
+    webhook_id: str,
+    tolerance_seconds: float | None = None,
+    now: Callable[[], float] | None = None,
+) -> bool:
+    _verify_event_data(
+        event=event,
+        webhook_id=webhook_id,
+        tolerance_seconds=tolerance_seconds,
+        now=now,
+    )
+    return True
+
+
+def replay_key(event: Mapping[str, Any]) -> str:
+    return _replay_key_from_parsed(_parse_event(event))
+
+
+def _verify_event_data(
+    *,
+    event: Mapping[str, Any],
+    webhook_id: str,
+    tolerance_seconds: float | None,
+    now: Callable[[], float] | None,
+) -> dict[str, Any]:
+    if not isinstance(webhook_id, str) or not webhook_id:
+        raise ValueError("webhook_id must be a non-empty string")
+
+    parsed = _parse_event(event)
+    if tolerance_seconds is not None:
+        _verify_fresh_timestamp(parsed["time"], tolerance_seconds, now or _current_unix_time)
+
+    signed_data = f"{parsed['type']}@{parsed['time']}".encode()
+    calculated = hmac.new(webhook_id.encode(), signed_data, "sha256").hexdigest()
+    if not hmac.compare_digest(calculated, parsed["hash"]):
+        raise ValueError("webhook signature is invalid")
+
+    return parsed
+
+
+def _parse_event(event: Mapping[str, Any]) -> dict[str, Any]:
+    if not isinstance(event, Mapping):
+        raise TypeError("event must be a mapping")
+
+    event_type = event.get("type")
+    event_time = event.get("time")
+    event_hash = event.get("hash")
+    missing = [
+        key
+        for key, value in (
+            ("type", event_type),
+            ("time", event_time),
+            ("hash", event_hash),
+        )
+        if value is None or value == ""
+    ]
+    if missing:
+        raise ValueError(
+            "event is missing required keys: "
+            + ", ".join(missing)
+            + ". Make sure you pass payload['event'], not the full webhook payload"
+        )
+    if not isinstance(event_hash, str):
+        raise TypeError("event.hash must be a string")
+
+    return {"type": event_type, "time": event_time, "hash": event_hash}
+
+
+def _verify_fresh_timestamp(
+    event_time: Any,
+    tolerance_seconds: float,
+    now: Callable[[], float],
+) -> None:
+    if not isinstance(tolerance_seconds, int | float) or tolerance_seconds < 0:
+        raise ValueError("tolerance_seconds must be a non-negative number")
+
+    try:
+        timestamp = float(event_time)
+        current_time = float(now())
+    except (TypeError, ValueError) as exc:
+        raise ValueError("event.time must be a Unix timestamp when tolerance_seconds is provided") from exc
+
+    if abs(current_time - timestamp) > float(tolerance_seconds):
+        raise ValueError("webhook timestamp is outside the allowed tolerance")
+
+
+def _replay_key_from_parsed(event: Mapping[str, Any]) -> str:
+    return f"signwell:{event['type']}:{event['time']}:{event['hash']}"
+
+
+def _current_unix_time() -> float:
+    return time_module.time()