opensettle 0.1.0__py3-none-any.whl

opensettle/__init__.py

@@ -0,0 +1,54 @@
+"""Official Python SDK for the OpenSettle API.
+
+Public surface is intentionally narrow: the high-level clients
+(:class:`OpenSettle`, :class:`AsyncOpenSettle`), the typed error
+hierarchy, and the webhook verifier. Everything else is private and may
+change without a major-version bump.
+"""
+
+from __future__ import annotations
+
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    ErrorCode,
+    ForbiddenError,
+    InvalidRequestError,
+    InvalidStateTransitionError,
+    NetworkError,
+    NotFoundError,
+    OpenSettleError,
+    RateLimitError,
+    SettlementError,
+    StepUpRequiredError,
+)
+from ._version import SDK_VERSION
+from ._webhooks import (
+    VerifiedWebhook,
+    WebhookVerificationError,
+    verify_webhook,
+)
+from .client import AsyncOpenSettle, OpenSettle
+
+__all__ = [
+    "SDK_VERSION",
+    "APIError",
+    "AsyncOpenSettle",
+    "AuthenticationError",
+    "ConflictError",
+    "ErrorCode",
+    "ForbiddenError",
+    "InvalidRequestError",
+    "InvalidStateTransitionError",
+    "NetworkError",
+    "NotFoundError",
+    "OpenSettle",
+    "OpenSettleError",
+    "RateLimitError",
+    "SettlementError",
+    "StepUpRequiredError",
+    "VerifiedWebhook",
+    "WebhookVerificationError",
+    "verify_webhook",
+]

opensettle/_errors.py

@@ -0,0 +1,255 @@
+"""Typed error hierarchy for the OpenSettle SDK.
+
+Mirrors the API's stable ``error.code`` taxonomy from
+``@opensettle/shared/errors`` and the Node SDK's ``src/errors.ts``
+character-for-character — same 12 codes, same subclasses, same fields.
+
+Catchers can either:
+  - check ``isinstance(err, OpenSettleError)`` for the broad case, then
+    branch on ``err.code`` to handle specifics, or
+  - catch the specific subclass (``InvalidRequestError``, ...) when the
+    handler only cares about that family.
+
+The base class always carries ``request_id`` so users can quote it in
+support — this is the same ``request_id`` the API echoes back in every
+error envelope.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+try:  # pragma: no cover - exercised on Python 3.9/3.10
+    from typing import Literal
+except ImportError:  # pragma: no cover
+    from typing_extensions import Literal
+
+ErrorCode = Literal[
+    "invalid_request",
+    "invalid_state_transition",
+    "unauthorized",
+    "forbidden",
+    "not_found",
+    "conflict",
+    "rate_limited",
+    "internal_error",
+    "chain_reverted",
+    "insufficient_confirmations",
+    "signing_required",
+    "aal_required",
+    "network_error",
+]
+
+
+class OpenSettleError(Exception):
+    """Base class for every typed error raised by the SDK."""
+
+    code: ErrorCode
+    status: int
+    request_id: Optional[str]
+    param: Optional[str]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: ErrorCode,
+        status: int,
+        request_id: Optional[str] = None,
+        param: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        self.param = param
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(code={self.code!r}, status={self.status!r}, "
+            f"request_id={self.request_id!r}, param={self.param!r}, "
+            f"message={self.args[0]!r})"
+        )
+
+
+class InvalidRequestError(OpenSettleError):
+    """The request payload failed validation."""
+
+
+class InvalidStateTransitionError(OpenSettleError):
+    """The resource is in a state that does not allow this operation."""
+
+
+class AuthenticationError(OpenSettleError):
+    """The API key was missing, malformed, revoked, or unrecognised."""
+
+
+class ForbiddenError(OpenSettleError):
+    """The API key authenticated but lacks permission for this route."""
+
+
+class NotFoundError(OpenSettleError):
+    """The addressed resource does not exist (or is not visible to this key)."""
+
+
+class ConflictError(OpenSettleError):
+    """The request collides with the current resource state (dup, race, FK)."""
+
+
+class RateLimitError(OpenSettleError):
+    """The caller exceeded a rate-limit bucket.
+
+    ``retry_after`` is the seconds-to-wait the API advertised in its
+    ``Retry-After`` header (numeric or HTTP-date), or ``None`` if not
+    advertised.
+    """
+
+    retry_after: Optional[float]
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        request_id: Optional[str] = None,
+        param: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="rate_limited",
+            status=status,
+            request_id=request_id,
+            param=param,
+        )
+        self.retry_after = retry_after
+
+
+class SettlementError(OpenSettleError):
+    """A chain-side or signing failure: revert, insufficient confs, missing sig."""
+
+
+class StepUpRequiredError(OpenSettleError):
+    """The route requires step-up auth (AAL=2). Re-authenticate and retry."""
+
+
+class APIError(OpenSettleError):
+    """Catch-all for unknown error codes and ``internal_error`` 5xx responses."""
+
+
+class NetworkError(OpenSettleError):
+    """Transport-level failure: timeout, DNS, connection refused, etc."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(
+            message,
+            code="network_error",
+            status=0,
+            request_id=None,
+            param=None,
+        )
+
+
+def from_envelope(
+    envelope: Any,
+    status: int,
+    retry_after: Optional[float],
+) -> OpenSettleError:
+    """Map a parsed API error envelope + HTTP status into the right subclass.
+
+    Falls back to :class:`APIError` on unknown codes so a new server-side
+    code never crashes older clients.
+    """
+
+    error = envelope.get("error") if isinstance(envelope, dict) else None
+    code = error.get("code") if isinstance(error, dict) else None
+    message = error.get("message") if isinstance(error, dict) else None
+    request_id_raw = error.get("request_id") if isinstance(error, dict) else None
+    param_raw = error.get("param") if isinstance(error, dict) else None
+
+    if not isinstance(message, str) or not message:
+        message = f"Request failed with status {status}"
+
+    req_id: Optional[str] = request_id_raw if isinstance(request_id_raw, str) else None
+    param: Optional[str] = param_raw if isinstance(param_raw, str) else None
+
+    if code == "invalid_request":
+        return InvalidRequestError(
+            message, code="invalid_request", status=status, request_id=req_id, param=param
+        )
+    if code == "invalid_state_transition":
+        return InvalidStateTransitionError(
+            message,
+            code="invalid_state_transition",
+            status=status,
+            request_id=req_id,
+            param=param,
+        )
+    if code == "unauthorized":
+        return AuthenticationError(
+            message, code="unauthorized", status=status, request_id=req_id, param=param
+        )
+    if code == "forbidden":
+        return ForbiddenError(
+            message, code="forbidden", status=status, request_id=req_id, param=param
+        )
+    if code == "not_found":
+        return NotFoundError(
+            message, code="not_found", status=status, request_id=req_id, param=param
+        )
+    if code == "conflict":
+        return ConflictError(
+            message, code="conflict", status=status, request_id=req_id, param=param
+        )
+    if code == "rate_limited":
+        return RateLimitError(
+            message,
+            status=status,
+            request_id=req_id,
+            param=param,
+            retry_after=retry_after,
+        )
+    if code == "chain_reverted":
+        return SettlementError(
+            message, code="chain_reverted", status=status, request_id=req_id, param=param
+        )
+    if code == "insufficient_confirmations":
+        return SettlementError(
+            message,
+            code="insufficient_confirmations",
+            status=status,
+            request_id=req_id,
+            param=param,
+        )
+    if code == "signing_required":
+        return SettlementError(
+            message,
+            code="signing_required",
+            status=status,
+            request_id=req_id,
+            param=param,
+        )
+    if code == "aal_required":
+        return StepUpRequiredError(
+            message, code="aal_required", status=status, request_id=req_id, param=param
+        )
+    # internal_error or anything we don't recognise → forward-compat APIError.
+    return APIError(message, code="internal_error", status=status, request_id=req_id, param=param)
+
+
+__all__ = [
+    "APIError",
+    "AuthenticationError",
+    "ConflictError",
+    "ErrorCode",
+    "ForbiddenError",
+    "InvalidRequestError",
+    "InvalidStateTransitionError",
+    "NetworkError",
+    "NotFoundError",
+    "OpenSettleError",
+    "RateLimitError",
+    "SettlementError",
+    "StepUpRequiredError",
+    "from_envelope",
+]

opensettle/_http.py

@@ -0,0 +1,204 @@
+"""Synchronous HTTP client built on ``httpx.Client``."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any, Optional, Union
+
+import httpx
+from typing_extensions import Self
+
+from ._errors import NetworkError, OpenSettleError
+from ._transport import (
+    DEFAULT_MAX_NETWORK_RETRIES,
+    DEFAULT_TIMEOUT_SECONDS,
+    assert_api_key_environment,
+    build_headers,
+    build_raw_url,
+    build_url,
+    encode_body,
+    is_retriable_error,
+    map_error,
+    normalize_base_url,
+    parse_response_body,
+    wait_seconds_for_error,
+)
+
+
+class HttpClient:
+    """Thin sync wrapper around ``httpx.Client``.
+
+    Owns the auth header, workspace URL prefix, idempotency-key
+    injection, retries with exponential backoff, and error mapping.
+    Resources call :meth:`request` (workspace-scoped) or
+    :meth:`request_raw` (everything else, rare).
+    """
+
+    api_key: str
+    workspace_id: str
+    base_url: str
+    timeout: float
+    max_network_retries: int
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        workspace_id: str,
+        base_url: Optional[str] = None,
+        test_mode: Optional[bool] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
+        transport: Optional[httpx.BaseTransport] = None,
+        _client: Optional[httpx.Client] = None,
+        _sleep: Any = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("OpenSettle: api_key is required")
+        if not workspace_id:
+            raise ValueError("OpenSettle: workspace_id is required")
+        assert_api_key_environment(api_key, test_mode)
+
+        self.api_key = api_key
+        self.workspace_id = workspace_id
+        self.base_url = normalize_base_url(base_url)
+        self.timeout = timeout
+        self.max_network_retries = max_network_retries
+        if _client is not None:
+            self._client = _client
+            self._owns_client = False
+        else:
+            self._client = httpx.Client(timeout=timeout, transport=transport)
+            self._owns_client = True
+        self._sleep = _sleep if _sleep is not None else time.sleep
+
+    # Lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # URL helpers --------------------------------------------------------
+
+    def url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        return build_url(self.base_url, self.workspace_id, path, query)
+
+    def raw_url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        return build_raw_url(self.base_url, path, query)
+
+    # Request entry points ----------------------------------------------
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Any = None,
+        query: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Union[None, str, bool] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_network_retries: Optional[int] = None,
+    ) -> Any:
+        return self._request_at(
+            self.url(path, query),
+            method=method,
+            body=body,
+            idempotency_key=idempotency_key,
+            headers=headers,
+            timeout=timeout,
+            max_network_retries=max_network_retries,
+        )
+
+    def request_raw(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Any = None,
+        query: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Union[None, str, bool] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_network_retries: Optional[int] = None,
+    ) -> Any:
+        return self._request_at(
+            self.raw_url(path, query),
+            method=method,
+            body=body,
+            idempotency_key=idempotency_key,
+            headers=headers,
+            timeout=timeout,
+            max_network_retries=max_network_retries,
+        )
+
+    # Internal -----------------------------------------------------------
+
+    def _request_at(
+        self,
+        url: str,
+        *,
+        method: str,
+        body: Any,
+        idempotency_key: Union[None, str, bool],
+        headers: Optional[Mapping[str, str]],
+        timeout: Optional[float],
+        max_network_retries: Optional[int],
+    ) -> Any:
+        body_text = encode_body(body)
+        final_headers = build_headers(
+            api_key=self.api_key,
+            extra=headers,
+            has_body=body_text is not None,
+            idempotency_key=idempotency_key,
+        )
+        request_timeout = timeout if timeout is not None else self.timeout
+        budget = (
+            max_network_retries if max_network_retries is not None else self.max_network_retries
+        )
+
+        last_error: Optional[OpenSettleError] = None
+        for attempt in range(budget + 1):
+            try:
+                resp = self._client.request(
+                    method,
+                    url,
+                    content=body_text,
+                    headers=final_headers,
+                    timeout=request_timeout,
+                )
+            except httpx.HTTPError as exc:
+                err = NetworkError(f"Network error: {exc}")
+                if attempt < budget:
+                    self._sleep(wait_seconds_for_error(err, attempt))
+                    last_error = err
+                    continue
+                raise err from exc
+
+            if resp.status_code < 400:
+                if resp.status_code == 204 or not resp.content:
+                    return None
+                data, parse_err = parse_response_body(resp.text, resp.status_code)
+                if parse_err is not None:
+                    raise parse_err
+                return data
+
+            api_err = map_error(resp.text, resp.status_code, resp.headers.get("retry-after"))
+            if is_retriable_error(api_err) and attempt < budget:
+                self._sleep(wait_seconds_for_error(api_err, attempt))
+                last_error = api_err
+                continue
+            raise api_err
+
+        # Unreachable in practice — the loop either returns or raises.
+        raise last_error or RuntimeError("OpenSettle: request loop exited unexpectedly")
+
+
+__all__ = ["HttpClient"]

opensettle/_http_async.py

@@ -0,0 +1,194 @@
+"""Asynchronous HTTP client built on ``httpx.AsyncClient``.
+
+Mirror of :mod:`opensettle._http`. The two clients share the
+transport core in :mod:`opensettle._transport` — they only differ in
+``await`` and ``asyncio.sleep`` vs ``time.sleep``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any, Optional, Union
+
+import httpx
+from typing_extensions import Self
+
+from ._errors import NetworkError, OpenSettleError
+from ._transport import (
+    DEFAULT_MAX_NETWORK_RETRIES,
+    DEFAULT_TIMEOUT_SECONDS,
+    assert_api_key_environment,
+    build_headers,
+    build_raw_url,
+    build_url,
+    encode_body,
+    is_retriable_error,
+    map_error,
+    normalize_base_url,
+    parse_response_body,
+    wait_seconds_for_error,
+)
+
+
+class AsyncHttpClient:
+    """Async sibling of :class:`opensettle._http.HttpClient`."""
+
+    api_key: str
+    workspace_id: str
+    base_url: str
+    timeout: float
+    max_network_retries: int
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        workspace_id: str,
+        base_url: Optional[str] = None,
+        test_mode: Optional[bool] = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        _client: Optional[httpx.AsyncClient] = None,
+        _sleep: Any = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("OpenSettle: api_key is required")
+        if not workspace_id:
+            raise ValueError("OpenSettle: workspace_id is required")
+        assert_api_key_environment(api_key, test_mode)
+
+        self.api_key = api_key
+        self.workspace_id = workspace_id
+        self.base_url = normalize_base_url(base_url)
+        self.timeout = timeout
+        self.max_network_retries = max_network_retries
+        if _client is not None:
+            self._client = _client
+            self._owns_client = False
+        else:
+            self._client = httpx.AsyncClient(timeout=timeout, transport=transport)
+            self._owns_client = True
+        self._sleep = _sleep if _sleep is not None else asyncio.sleep
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()
+
+    def url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        return build_url(self.base_url, self.workspace_id, path, query)
+
+    def raw_url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        return build_raw_url(self.base_url, path, query)
+
+    async def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Any = None,
+        query: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Union[None, str, bool] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_network_retries: Optional[int] = None,
+    ) -> Any:
+        return await self._request_at(
+            self.url(path, query),
+            method=method,
+            body=body,
+            idempotency_key=idempotency_key,
+            headers=headers,
+            timeout=timeout,
+            max_network_retries=max_network_retries,
+        )
+
+    async def request_raw(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: Any = None,
+        query: Optional[Mapping[str, Any]] = None,
+        idempotency_key: Union[None, str, bool] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_network_retries: Optional[int] = None,
+    ) -> Any:
+        return await self._request_at(
+            self.raw_url(path, query),
+            method=method,
+            body=body,
+            idempotency_key=idempotency_key,
+            headers=headers,
+            timeout=timeout,
+            max_network_retries=max_network_retries,
+        )
+
+    async def _request_at(
+        self,
+        url: str,
+        *,
+        method: str,
+        body: Any,
+        idempotency_key: Union[None, str, bool],
+        headers: Optional[Mapping[str, str]],
+        timeout: Optional[float],
+        max_network_retries: Optional[int],
+    ) -> Any:
+        body_text = encode_body(body)
+        final_headers = build_headers(
+            api_key=self.api_key,
+            extra=headers,
+            has_body=body_text is not None,
+            idempotency_key=idempotency_key,
+        )
+        request_timeout = timeout if timeout is not None else self.timeout
+        budget = (
+            max_network_retries if max_network_retries is not None else self.max_network_retries
+        )
+
+        last_error: Optional[OpenSettleError] = None
+        for attempt in range(budget + 1):
+            try:
+                resp = await self._client.request(
+                    method,
+                    url,
+                    content=body_text,
+                    headers=final_headers,
+                    timeout=request_timeout,
+                )
+            except httpx.HTTPError as exc:
+                err = NetworkError(f"Network error: {exc}")
+                if attempt < budget:
+                    await self._sleep(wait_seconds_for_error(err, attempt))
+                    last_error = err
+                    continue
+                raise err from exc
+
+            if resp.status_code < 400:
+                if resp.status_code == 204 or not resp.content:
+                    return None
+                data, parse_err = parse_response_body(resp.text, resp.status_code)
+                if parse_err is not None:
+                    raise parse_err
+                return data
+
+            api_err = map_error(resp.text, resp.status_code, resp.headers.get("retry-after"))
+            if is_retriable_error(api_err) and attempt < budget:
+                await self._sleep(wait_seconds_for_error(api_err, attempt))
+                last_error = api_err
+                continue
+            raise api_err
+
+        raise last_error or RuntimeError("OpenSettle: request loop exited unexpectedly")
+
+
+__all__ = ["AsyncHttpClient"]