spreadspace 0.1.0__py3-none-any.whl

spreadspace/__init__.py

@@ -0,0 +1,75 @@
+"""SpreadSpace Python SDK.
+
+    from spreadspace import SpreadSpace
+    client = SpreadSpace(api_key="ss_test_...")
+    for borrower in client.borrowers.list():
+        ...
+"""
+
+from ._version import DEFAULT_API_VERSION, SDK_VERSION
+from .client import SpreadSpace
+from .errors import (
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SpreadSpaceError,
+)
+from .helpers.operations import (
+    AsyncOperation,
+    AsyncOperationError,
+    AsyncOperationHandle,
+    AsyncOperationTimeout,
+)
+from .helpers.pagination import PageIterator
+from .helpers.upload import JobHandle, PresignedUrl, UploadError, UploadTimeout
+from .webhooks import (
+    DEFAULT_FRESHNESS_TOLERANCE_SECONDS,
+    SIGNATURE_HEADER_NAME,
+    WEBHOOK_EVENT_TYPES,
+    WebhookEvent,
+    WebhookSignatureError,
+    verify_and_parse_webhook,
+    verify_webhook_signature,
+)
+
+__all__ = [
+    # client + version
+    "SpreadSpace",
+    "SDK_VERSION",
+    "DEFAULT_API_VERSION",
+    # errors
+    "SpreadSpaceError",
+    "NetworkError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "InternalServerError",
+    # helper types
+    "PageIterator",
+    "AsyncOperation",
+    "AsyncOperationHandle",
+    "AsyncOperationError",
+    "AsyncOperationTimeout",
+    "JobHandle",
+    "PresignedUrl",
+    "UploadError",
+    "UploadTimeout",
+    # webhooks
+    "verify_webhook_signature",
+    "verify_and_parse_webhook",
+    "WebhookSignatureError",
+    "WebhookEvent",
+    "WEBHOOK_EVENT_TYPES",
+    "SIGNATURE_HEADER_NAME",
+    "DEFAULT_FRESHNESS_TOLERANCE_SECONDS",
+]

spreadspace/_transport.py

@@ -0,0 +1,272 @@
+"""HTTP transport: auth, version header, idempotency, retries, error mapping.
+
+This is the configured client every helper and (eventually) the generated core
+sit on top of. It is hand-written, not generated. Responsibilities:
+
+* `Authorization: Bearer <key>` + `SpreadSpace-Version` on every API request.
+* Auto `Idempotency-Key` (uuid4) on non-safe methods, suppressible per call.
+* Retry 429 + 5xx + transport errors with exponential backoff + full jitter,
+  honoring `Retry-After`.
+* Decode JSON with `parse_float=Decimal` so money survives exactly (no float64
+  corruption) regardless of how the wire types it.
+* Map the canonical error envelope to typed exceptions carrying `request_id`,
+  preferring the `X-Request-ID` response header.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import random
+import time
+import uuid
+from decimal import Decimal
+from typing import Any, Callable, Mapping, Optional
+
+import httpx
+
+from . import errors
+from ._version import DEFAULT_API_VERSION, SDK_VERSION
+
+DEFAULT_BASE_URL = "https://api.spreadspace.ai"
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+# Backoff tuning, mirrored from the node SDK (base 500ms, cap 30s, full jitter).
+_BACKOFF_BASE_SECONDS = 0.5
+_BACKOFF_MAX_SECONDS = 30.0
+
+# Sentinel distinguishing "argument omitted" from an explicit None.
+_UNSET: Any = object()
+
+
+def loads(text: Optional[str]) -> Any:
+    """Decode a JSON document, materializing every fractional number as Decimal.
+
+    `parse_float=Decimal` reads the literal digits of each float-looking token,
+    so `"1234.56"` becomes `Decimal("1234.56")` exactly. Integer tokens stay
+    `int`. This is what makes money exact in Python without any wire change.
+    """
+    if not text:
+        return None
+    return json.loads(text, parse_float=Decimal)
+
+
+def _dumps(body: Any) -> bytes:
+    return json.dumps(body, separators=(",", ":")).encode("utf-8")
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[dict]:
+    if not params:
+        return None
+    out: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        else:
+            out[key] = value
+    return out or None
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except (TypeError, ValueError):
+        # HTTP-date form is unusual here; the API emits integer seconds.
+        return None
+
+
+class Transport:
+    """Configured HTTP client wrapping httpx with SpreadSpace conventions."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        api_version: str = DEFAULT_API_VERSION,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        httpx_transport: Optional[httpx.BaseTransport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("SPREADSPACE_API_KEY")
+        if not key:
+            raise ValueError(
+                "An API key is required. Pass api_key=... or set SPREADSPACE_API_KEY."
+            )
+        self._api_key = key
+        self._base_url = base_url.rstrip("/")
+        self._api_version = api_version
+        self._max_retries = max_retries
+        self._sleep = sleep
+        self._user_agent = (
+            f"spreadspace-python/{SDK_VERSION} python/{platform.python_version()}"
+        )
+        self._client = httpx.Client(timeout=timeout, transport=httpx_transport)
+
+    # -- public API ---------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        idempotency_key: Any = _UNSET,
+        api_version: Optional[str] = None,
+        max_retries: Optional[int] = None,
+    ) -> Any:
+        """Issue an API request and return the decoded JSON body (or None)."""
+        url = self._base_url + path
+        req_headers = self._default_headers(
+            method,
+            api_version=api_version,
+            idempotency_key=idempotency_key,
+            has_body=json is not None,
+        )
+        if headers:
+            req_headers.update(headers)
+        content = _dumps(json) if json is not None else None
+        request = self._client.build_request(
+            method, url, params=_clean_params(params), content=content, headers=req_headers
+        )
+        retries = self._max_retries if max_retries is None else max_retries
+        response = self._send(request, max_retries=retries)
+        return self._process(response)
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put_presigned(
+        self,
+        url: str,
+        data: Any,
+        content_type: str,
+        *,
+        max_retries: Optional[int] = None,
+    ) -> httpx.Response:
+        """PUT bytes straight to a presigned S3 URL (out-of-band, no auth).
+
+        `Content-Type` must match the value sent when minting the URL — it is
+        part of the V4 signature. No SSE headers (bucket-default KMS applies).
+        """
+        request = self._client.build_request(
+            "PUT", url, content=data, headers={"Content-Type": content_type}
+        )
+        retries = self._max_retries if max_retries is None else max_retries
+        response = self._send(request, max_retries=retries)
+        if not response.is_success:
+            raise errors.APIStatusError(
+                f"Presigned upload failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+                raw_body=response.text,
+            )
+        return response
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Transport":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # -- internals ----------------------------------------------------------
+
+    def _default_headers(
+        self,
+        method: str,
+        *,
+        api_version: Optional[str],
+        idempotency_key: Any,
+        has_body: bool,
+    ) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "SpreadSpace-Version": api_version or self._api_version,
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if method.upper() not in _SAFE_METHODS:
+            if idempotency_key is _UNSET:
+                headers["Idempotency-Key"] = str(uuid.uuid4())
+            elif idempotency_key is not None:
+                headers["Idempotency-Key"] = str(idempotency_key)
+            # idempotency_key is None -> caller explicitly suppressed the header.
+        return headers
+
+    def _send(self, request: httpx.Request, *, max_retries: int) -> httpx.Response:
+        attempt = 0
+        while True:
+            try:
+                response = self._client.send(request)
+            except httpx.TransportError as exc:
+                if attempt < max_retries:
+                    self._sleep(self._backoff(attempt, None))
+                    attempt += 1
+                    continue
+                raise errors.NetworkError(str(exc)) from exc
+            if errors.is_retryable_status(response.status_code) and attempt < max_retries:
+                retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+                response.close()
+                self._sleep(self._backoff(attempt, retry_after))
+                attempt += 1
+                continue
+            return response
+
+    @staticmethod
+    def _backoff(attempt: int, retry_after: Optional[float]) -> float:
+        ceiling = min(_BACKOFF_MAX_SECONDS, _BACKOFF_BASE_SECONDS * (2 ** attempt))
+        delay = random.uniform(0, ceiling)  # full jitter
+        if retry_after is not None:
+            delay = max(delay, retry_after)
+        return delay
+
+    def _process(self, response: httpx.Response) -> Any:
+        text = response.text
+        if response.is_success:
+            return loads(text) if text else None
+        self._raise(response, text)
+
+    @staticmethod
+    def _raise(response: httpx.Response, text: str) -> None:
+        request_id = response.headers.get("X-Request-ID")
+        err_type: Optional[str] = None
+        message: Optional[str] = None
+        details = None
+        body: Any = None
+        try:
+            body = loads(text)
+        except ValueError:
+            body = None
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, dict):
+                err_type = err.get("type")
+                message = err.get("message")
+                details = err.get("details")
+                request_id = request_id or err.get("request_id")
+        retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+        exc_cls = errors.classify(response.status_code, err_type)
+        raise exc_cls(
+            message or f"HTTP {response.status_code}",
+            type=err_type,
+            status_code=response.status_code,
+            request_id=request_id,
+            details=details,
+            raw_body=text,
+            retry_after=retry_after,
+        )

spreadspace/_version.py

@@ -0,0 +1,12 @@
+"""Version constants.
+
+`SDK_VERSION` is the published package version; `DEFAULT_API_VERSION` is the
+dated `SpreadSpace-Version` this SDK release pins by default (overridable per
+request). The SDK semver is decoupled from the dated API version on purpose.
+"""
+
+SDK_VERSION = "0.1.0"
+
+# Latest supported API version as of this SDK release. Mirrors
+# ApiVersionRegistry.Latest on the server (api/src/Models/ApiVersionRegistry.cs).
+DEFAULT_API_VERSION = "2026-05-03"

spreadspace/client.py

@@ -0,0 +1,308 @@
+"""The `SpreadSpace` client facade.
+
+Thin ergonomic namespaces over the transport + helpers. These wrap the
+cross-cutting flows a generator can't produce (pagination, the operation
+waiter, the upload sequence); the full typed method-per-endpoint surface comes
+from the generated core (`spreadspace._generated`, produced in CI).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote
+
+from ._transport import _UNSET, DEFAULT_BASE_URL, Transport
+from ._version import DEFAULT_API_VERSION
+from .helpers import operations as _ops
+from .helpers import upload as _upload
+from .helpers.pagination import PageIterator, paginate
+from .webhooks import verify_and_parse_webhook, verify_webhook_signature
+
+
+class _Borrowers:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self, *, intake: Optional[bool] = None, limit: Optional[int] = None,
+        api_version: Optional[str] = None,
+    ) -> PageIterator:
+        return paginate(
+            self._t, "/api/borrowers",
+            params={"limit": limit, "intake": intake}, api_version=api_version,
+        )
+
+
+class _Loans:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self, *, borrower_id: Optional[str] = None, limit: Optional[int] = None,
+        api_version: Optional[str] = None,
+    ) -> PageIterator:
+        path = f"/api/borrowers/{borrower_id}/loans" if borrower_id else "/api/loans"
+        return paginate(self._t, path, params={"limit": limit}, api_version=api_version)
+
+
+class _Jobs:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self, *, limit: Optional[int] = None, api_version: Optional[str] = None,
+    ) -> PageIterator:
+        return paginate(self._t, "/api/jobs", params={"limit": limit}, api_version=api_version)
+
+
+class _AsyncOperations:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self, *, kind: Optional[str] = None, status: Optional[str] = None,
+        limit: Optional[int] = None, api_version: Optional[str] = None,
+    ) -> PageIterator:
+        # Divergent envelope: items live under "operations", not "data".
+        return paginate(
+            self._t, "/api/async-operations",
+            params={"limit": limit, "kind": kind, "status": status},
+            items_key="operations", api_version=api_version,
+        )
+
+    def get(self, operation_id: str) -> _ops.AsyncOperation:
+        return _ops.get_operation(self._t, operation_id)
+
+    def cancel(self, operation_id: str) -> _ops.AsyncOperation:
+        return _ops.cancel_operation(self._t, operation_id)
+
+
+class _Exports:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self, *, borrower_id: Optional[str] = None, loan_id: Optional[str] = None,
+        document_ids: Optional[list] = None, format: Optional[str] = None,
+        delivery_mode: Optional[str] = None,
+    ) -> _ops.AsyncOperationHandle:
+        return _ops.create_extraction_export(
+            self._t, borrower_id=borrower_id, loan_id=loan_id,
+            document_ids=document_ids, format=format, delivery_mode=delivery_mode,
+        )
+
+    def get(self, operation_id: str) -> _ops.AsyncOperation:
+        return _ops.get_operation(self._t, operation_id)
+
+
+class _Documents:
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def upload(self, file: Any, **kwargs: Any) -> _upload.JobHandle:
+        return _upload.upload_document(self._t, file, **kwargs)
+
+    def status(self, job_id: str) -> dict:
+        return _upload.JobHandle(self._t, job_id).status()
+
+
+class _Webhooks:
+    """Webhook endpoint registration (`/api/admin/webhooks/*`).
+
+    The signature verifiers are exposed as static methods for discoverability;
+    they're also importable as bare functions from ``spreadspace.webhooks`` for
+    receivers that don't want the HTTP transport in scope.
+    """
+
+    # Static handles to the verifier primitives — `client.webhooks.verify_signature(...)`.
+    verify_signature = staticmethod(verify_webhook_signature)
+    verify_and_parse = staticmethod(verify_and_parse_webhook)
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def list(
+        self, *, limit: Optional[int] = None, api_version: Optional[str] = None,
+    ) -> PageIterator:
+        """List configured webhook endpoints (`GET /api/admin/webhooks`)."""
+        return paginate(
+            self._t, "/api/admin/webhooks",
+            params={"limit": limit}, api_version=api_version,
+        )
+
+    def get(self, endpoint_id: str, *, api_version: Optional[str] = None) -> Any:
+        """Retrieve one endpoint (`GET /api/admin/webhooks/{id}`)."""
+        return self._t.get(
+            f"/api/admin/webhooks/{quote(endpoint_id, safe='')}",
+            api_version=api_version,
+        )
+
+    def create(self, **params: Any) -> Any:
+        """Create an endpoint (`POST /api/admin/webhooks`).
+
+        The response carries the plaintext signing secret exactly once — store
+        it server-side, do not log it.
+        """
+        return self._t.post("/api/admin/webhooks", json=params)
+
+    def update(self, endpoint_id: str, **params: Any) -> Any:
+        """Update endpoint metadata (`PATCH /api/admin/webhooks/{id}`)."""
+        return self._t.request(
+            "PATCH", f"/api/admin/webhooks/{quote(endpoint_id, safe='')}",
+            json=params,
+        )
+
+    def delete(self, endpoint_id: str) -> Any:
+        """Delete an endpoint (`DELETE /api/admin/webhooks/{id}`)."""
+        return self._t.request(
+            "DELETE", f"/api/admin/webhooks/{quote(endpoint_id, safe='')}"
+        )
+
+    def rotate_secret(self, endpoint_id: str, **params: Any) -> Any:
+        """Rotate an endpoint's signing secret
+        (`POST /api/admin/webhooks/{id}/rotate`). Returns the new plaintext
+        secret exactly once; the old one stays valid for a grace window.
+        """
+        return self._t.post(
+            f"/api/admin/webhooks/{quote(endpoint_id, safe='')}/rotate",
+            json=params,
+        )
+
+    def deliveries(
+        self, endpoint_id: str, *, limit: Optional[int] = None,
+        api_version: Optional[str] = None,
+    ) -> PageIterator:
+        """Iterate delivery attempts
+        (`GET /api/admin/webhooks/{id}/deliveries`)."""
+        return paginate(
+            self._t,
+            f"/api/admin/webhooks/{quote(endpoint_id, safe='')}/deliveries",
+            params={"limit": limit}, api_version=api_version,
+        )
+
+    def replay_delivery(
+        self, endpoint_id: str, delivery_id: str, **params: Any
+    ) -> Any:
+        """Replay a delivery
+        (`POST /api/admin/webhooks/{id}/deliveries/{deliveryId}/replay`)."""
+        return self._t.post(
+            f"/api/admin/webhooks/{quote(endpoint_id, safe='')}"
+            f"/deliveries/{quote(delivery_id, safe='')}/replay",
+            json=params,
+        )
+
+
+class _EmbedSessions:
+    """Embed-session minting (`/api/embed/*`).
+
+    Mint short-lived `ss_embed_` tokens server-side with the integrator's API
+    key, then hand the token (or signed iframe URL) to the browser. Minted
+    tokens are locked to a single `loan_id`, capped to the embed read-only
+    scope allowlist, and cannot mint further tokens.
+    """
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create(
+        self, *, loan_id: str, scopes: Optional[list] = None,
+        expires_in_seconds: Optional[int] = None,
+    ) -> Any:
+        """Mint an embed-session token (`POST /api/embed/sessions`).
+
+        Returns ``{embed_token, session_id, expires_at, loan_id, borrower_id,
+        scopes}`` — the token is shown once, no retrieval endpoint. ``scopes``
+        omitted inherits the key's scopes capped to the embed allowlist;
+        ``expires_in_seconds`` defaults to 3600, caps at 86400.
+        """
+        body: dict[str, Any] = {"loan_id": loan_id}
+        if scopes is not None:
+            body["scopes"] = scopes
+        if expires_in_seconds is not None:
+            body["expires_in_seconds"] = expires_in_seconds
+        return self._t.post("/api/embed/sessions", json=body)
+
+    def revoke(self, session_id: str, *, idempotency_key: Any = _UNSET) -> Any:
+        """Revoke an embed session early
+        (`DELETE /api/embed/sessions/{sessionId}`). Returns ``None`` (204)."""
+        return self._t.request(
+            "DELETE", f"/api/embed/sessions/{quote(session_id, safe='')}",
+            idempotency_key=idempotency_key,
+        )
+
+    def create_iframe_url(
+        self, *, loan_id: str, surface: str, scopes: Optional[list] = None,
+        handle_lifetime_seconds: Optional[int] = None,
+        token_lifetime_seconds: Optional[int] = None,
+    ) -> Any:
+        """Mint an iframe signed-URL handle (`POST /api/embed/iframe-urls`).
+
+        Returns ``{signed_url, handle_id, expires_at, surface, loan_id,
+        borrower_id, scopes}`` — ``expires_at`` is the HANDLE expiry, not the
+        token's. ``surface`` is validated server-side (e.g. ``"spreading"``).
+        ``handle_lifetime_seconds`` defaults to 60 (cap 300);
+        ``token_lifetime_seconds`` defaults to 3600 (cap 86400).
+        """
+        body: dict[str, Any] = {"loan_id": loan_id, "surface": surface}
+        if scopes is not None:
+            body["scopes"] = scopes
+        if handle_lifetime_seconds is not None:
+            body["handle_lifetime_seconds"] = handle_lifetime_seconds
+        if token_lifetime_seconds is not None:
+            body["token_lifetime_seconds"] = token_lifetime_seconds
+        return self._t.post("/api/embed/iframe-urls", json=body)
+
+
+class _Embed:
+    """Top-level `client.embed` namespace; surfaces the `sessions` sub-resource."""
+
+    def __init__(self, transport: Transport) -> None:
+        self.sessions = _EmbedSessions(transport)
+
+
+class SpreadSpace:
+    """Entry point. `SpreadSpace(api_key=...)` or set `SPREADSPACE_API_KEY`.
+
+    An `ss_test_` key routes to the isolated sandbox tenant; `ss_live_` operates
+    on real workspace data. Both hit the same base URL.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_version: str = DEFAULT_API_VERSION,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self._transport = transport or Transport(
+            api_key=api_key, base_url=base_url, api_version=api_version,
+            timeout=timeout, max_retries=max_retries,
+        )
+        self.borrowers = _Borrowers(self._transport)
+        self.loans = _Loans(self._transport)
+        self.jobs = _Jobs(self._transport)
+        self.async_operations = _AsyncOperations(self._transport)
+        self.exports = _Exports(self._transport)
+        self.documents = _Documents(self._transport)
+        self.webhooks = _Webhooks(self._transport)
+        self.embed = _Embed(self._transport)
+
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Low-level escape hatch to any endpoint the helpers don't wrap."""
+        return self._transport.request(method, path, **kwargs)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "SpreadSpace":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()