spreadspace 0.1.0__tar.gz

spreadspace-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Generated OpenAPI core — produced by scripts/generate.sh in CI. DO NOT EDIT,
+# never commit (regenerated every run from the spec).
+src/spreadspace/_generated/
+
+# Python build / test artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+build/
+dist/
+.venv/

spreadspace-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: spreadspace
+Version: 0.1.0
+Summary: Official Python SDK for the SpreadSpace API.
+Project-URL: Homepage, https://spreadspace.ai
+Project-URL: Documentation, https://docs.spreadspace.ai
+Project-URL: Source, https://github.com/spreadspace
+Author: SpreadSpace
+License: MIT
+Keywords: api,document,extraction,lending,sdk,spreadspace
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpreadSpace Python SDK
+
+Official Python client for the [SpreadSpace API](https://docs.spreadspace.ai) —
+document extraction and financial spreading for lending.
+
+> Some examples below require the generated core (built in CI) or a live sandbox
+> key. They are marked **[needs sandbox key]** / **[needs generated core]**.
+
+## Install
+
+```bash
+pip install spreadspace
+```
+
+Requires Python 3.9+.
+
+## Authentication
+
+```python
+from spreadspace import SpreadSpace
+
+client = SpreadSpace(api_key="ss_test_...")   # or omit and set SPREADSPACE_API_KEY
+```
+
+The key prefix selects the environment:
+
+- `ss_test_...` — routes to your **sandbox tenant** (seed data, safe to experiment).
+- `ss_live_...` — routes to your live tenant (real data).
+
+If `api_key` is omitted, the client reads `SPREADSPACE_API_KEY` from the
+environment. Never hard-code a live key; never commit any key.
+
+## Client options
+
+```python
+client = SpreadSpace(
+    api_key="ss_test_...",
+    base_url="https://api.spreadspace.ai",   # override for a private deployment
+    api_version="2026-05-03",                # pins the SpreadSpace-Version header
+    timeout=60.0,                            # seconds, per request
+    max_retries=2,                           # 429 + 5xx + transport errors
+)
+```
+
+### API version pinning
+
+Every request sends a dated `SpreadSpace-Version` header. The SDK pins a default
+version per release (decoupled from the SDK's own semver). Pin it explicitly to
+insulate your integration from server-side changes, and override per call when
+you need a newer surface:
+
+```python
+client.borrowers.list(api_version="2026-06-01")   # one call on a newer version
+```
+
+## Pagination (lazy, auto cursor)
+
+List endpoints return a lazy iterator that walks cursors for you — it fetches the
+next page only as you consume it.
+
+```python
+for borrower in client.borrowers.list():
+    print(borrower["id"])
+
+# Filters pass straight through and persist across pages:
+for job in client.jobs.list(status="completed", limit=50):
+    print(job["id"])
+```
+
+## Async export + wait
+
+Exports are asynchronous operations. `create` returns a handle; `wait` polls to
+completion (or raises on timeout).
+
+```python
+op = client.exports.create(borrower_id="...", format="xlsx")
+result = op.wait(timeout=300)   # seconds
+print(result["download_url"])
+```
+
+## Upload a document + wait for processing
+
+```python
+job = client.documents.upload("statement.pdf", borrower_id="...")
+final = job.wait(timeout=600)   # seconds
+print(final["status"])
+```
+
+The upload helper requests a presigned URL, PUTs the file bytes directly to
+storage with the matching `Content-Type` (part of the V4 signature), then returns
+a job handle you can `wait` on.
+
+## Error handling
+
+All errors derive from `SpreadSpaceError`. Match on the typed subclass, never on
+the message string:
+
+```python
+from spreadspace import (
+    SpreadSpaceError,       # base
+    NetworkError,           # transport failure, no HTTP response
+    BadRequestError,        # 400
+    AuthenticationError,    # 401
+    PermissionDeniedError,  # 403
+    NotFoundError,          # 404
+    ConflictError,          # 409
+    RateLimitError,         # 429
+    InternalServerError,    # 5xx
+)
+
+try:
+    client.borrowers.get("missing-id")
+except RateLimitError as e:
+    print("retry after", e.retry_after, "seconds")
+except NotFoundError as e:
+    print("not found")
+except SpreadSpaceError as e:
+    # Every error carries request_id — quote it in support tickets.
+    print(e.message, e.status_code, e.request_id)
+```
+
+`request_id` comes from the `X-Request-ID` response header (falling back to the
+error body). Transient failures (429, 5xx, transport errors) are retried
+automatically up to `max_retries` with exponential backoff + full jitter,
+honoring `Retry-After`.
+
+## Money is exact
+
+Monetary values decode as `decimal.Decimal`, not `float` — the SDK reads the
+literal digits off the wire, so amounts are exact with no float rounding:
+
+```python
+b = client.borrowers.get("...")          # [needs sandbox key]
+assert b["total_revenue"] == Decimal("1234.56")   # never 1234.5600000000001
+```
+
+## Development
+
+The generated OpenAPI core lives in `src/spreadspace/_generated/` and is built in
+CI (`scripts/generate.sh`, Java-based — not run locally). It is **gitignored and
+must never be hand-edited**. The hand-written ergonomic layer (transport,
+helpers, typed errors) is the only code committed by hand.
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+## License
+
+MIT

spreadspace-0.1.0/README.md

@@ -0,0 +1,151 @@
+# SpreadSpace Python SDK
+
+Official Python client for the [SpreadSpace API](https://docs.spreadspace.ai) —
+document extraction and financial spreading for lending.
+
+> Some examples below require the generated core (built in CI) or a live sandbox
+> key. They are marked **[needs sandbox key]** / **[needs generated core]**.
+
+## Install
+
+```bash
+pip install spreadspace
+```
+
+Requires Python 3.9+.
+
+## Authentication
+
+```python
+from spreadspace import SpreadSpace
+
+client = SpreadSpace(api_key="ss_test_...")   # or omit and set SPREADSPACE_API_KEY
+```
+
+The key prefix selects the environment:
+
+- `ss_test_...` — routes to your **sandbox tenant** (seed data, safe to experiment).
+- `ss_live_...` — routes to your live tenant (real data).
+
+If `api_key` is omitted, the client reads `SPREADSPACE_API_KEY` from the
+environment. Never hard-code a live key; never commit any key.
+
+## Client options
+
+```python
+client = SpreadSpace(
+    api_key="ss_test_...",
+    base_url="https://api.spreadspace.ai",   # override for a private deployment
+    api_version="2026-05-03",                # pins the SpreadSpace-Version header
+    timeout=60.0,                            # seconds, per request
+    max_retries=2,                           # 429 + 5xx + transport errors
+)
+```
+
+### API version pinning
+
+Every request sends a dated `SpreadSpace-Version` header. The SDK pins a default
+version per release (decoupled from the SDK's own semver). Pin it explicitly to
+insulate your integration from server-side changes, and override per call when
+you need a newer surface:
+
+```python
+client.borrowers.list(api_version="2026-06-01")   # one call on a newer version
+```
+
+## Pagination (lazy, auto cursor)
+
+List endpoints return a lazy iterator that walks cursors for you — it fetches the
+next page only as you consume it.
+
+```python
+for borrower in client.borrowers.list():
+    print(borrower["id"])
+
+# Filters pass straight through and persist across pages:
+for job in client.jobs.list(status="completed", limit=50):
+    print(job["id"])
+```
+
+## Async export + wait
+
+Exports are asynchronous operations. `create` returns a handle; `wait` polls to
+completion (or raises on timeout).
+
+```python
+op = client.exports.create(borrower_id="...", format="xlsx")
+result = op.wait(timeout=300)   # seconds
+print(result["download_url"])
+```
+
+## Upload a document + wait for processing
+
+```python
+job = client.documents.upload("statement.pdf", borrower_id="...")
+final = job.wait(timeout=600)   # seconds
+print(final["status"])
+```
+
+The upload helper requests a presigned URL, PUTs the file bytes directly to
+storage with the matching `Content-Type` (part of the V4 signature), then returns
+a job handle you can `wait` on.
+
+## Error handling
+
+All errors derive from `SpreadSpaceError`. Match on the typed subclass, never on
+the message string:
+
+```python
+from spreadspace import (
+    SpreadSpaceError,       # base
+    NetworkError,           # transport failure, no HTTP response
+    BadRequestError,        # 400
+    AuthenticationError,    # 401
+    PermissionDeniedError,  # 403
+    NotFoundError,          # 404
+    ConflictError,          # 409
+    RateLimitError,         # 429
+    InternalServerError,    # 5xx
+)
+
+try:
+    client.borrowers.get("missing-id")
+except RateLimitError as e:
+    print("retry after", e.retry_after, "seconds")
+except NotFoundError as e:
+    print("not found")
+except SpreadSpaceError as e:
+    # Every error carries request_id — quote it in support tickets.
+    print(e.message, e.status_code, e.request_id)
+```
+
+`request_id` comes from the `X-Request-ID` response header (falling back to the
+error body). Transient failures (429, 5xx, transport errors) are retried
+automatically up to `max_retries` with exponential backoff + full jitter,
+honoring `Retry-After`.
+
+## Money is exact
+
+Monetary values decode as `decimal.Decimal`, not `float` — the SDK reads the
+literal digits off the wire, so amounts are exact with no float rounding:
+
+```python
+b = client.borrowers.get("...")          # [needs sandbox key]
+assert b["total_revenue"] == Decimal("1234.56")   # never 1234.5600000000001
+```
+
+## Development
+
+The generated OpenAPI core lives in `src/spreadspace/_generated/` and is built in
+CI (`scripts/generate.sh`, Java-based — not run locally). It is **gitignored and
+must never be hand-edited**. The hand-written ergonomic layer (transport,
+helpers, typed errors) is the only code committed by hand.
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+## License
+
+MIT

spreadspace-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spreadspace"
+version = "0.1.0"
+description = "Official Python SDK for the SpreadSpace API."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "SpreadSpace" }]
+keywords = ["spreadspace", "api", "sdk", "document", "extraction", "lending"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://spreadspace.ai"
+Documentation = "https://docs.spreadspace.ai"
+Source = "https://github.com/spreadspace"
+
+# The generated OpenAPI core lands in src/spreadspace/_generated/ at build time
+# (see scripts/generate.sh). The hand-written ergonomic layer lives alongside it
+# and is the only code committed by hand.
+[tool.hatch.build.targets.wheel]
+packages = ["src/spreadspace"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+files = ["src/spreadspace"]

spreadspace-0.1.0/scripts/generate.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Regenerate the Python SDK's generated OpenAPI core.
+#
+# Self-hosted pipeline (no paid SDK vendor): we drive OpenAPI Generator directly.
+# The hand-written ergonomic layer (transport, helpers, typed errors) lives in
+# src/spreadspace/ and is committed; the machine-generated models + low-level
+# api client land in src/spreadspace/_generated/ and are GITIGNORED — they are
+# regenerated from the spec every run and must NEVER be hand-edited.
+#
+# Java is required (OpenAPI Generator is a JVM tool). Local dev has no JRE, so
+# this is CI-only — see .github/workflows/sdk.yml. Author/verify here, run there.
+#
+# Idempotent + safe to re-run: it rebuilds the public spec, re-validates, and
+# overwrites _generated/ from scratch each time.
+set -euo pipefail
+
+# -- pinned versions --------------------------------------------------------
+# CLI wrapper (npx) and the generator JAR are pinned to EXACT versions so the
+# generated output is reproducible across CI runs and machines.
+OPENAPI_GENERATOR_CLI_VERSION="2.20.0"            # @openapitools/openapi-generator-cli (npm wrapper)
+OPENAPI_GENERATOR_VERSION="${OPENAPI_GENERATOR_VERSION:-7.13.0}"  # the generator JAR (recent 7.x)
+export OPENAPI_GENERATOR_VERSION
+
+# Generator target. NOTE: the exact `-g` name MUST be confirmed against the
+# pinned JAR with `npx @openapitools/openapi-generator-cli@${OPENAPI_GENERATOR_CLI_VERSION} list`
+# before trusting it — do NOT assume. In 7.x the maintained Python generator is
+# `python` (the legacy `python-legacy` is separate). We pin `python`.
+GENERATOR_NAME="python"
+
+# -- paths ------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SDK_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"          # sdk/python
+REPO_ROOT="$(cd "${SDK_DIR}/../.." && pwd)"        # repo root
+PUBLIC_SPEC="${REPO_ROOT}/fern/api-public.json"
+OUT_DIR="${SDK_DIR}/src/spreadspace/_generated"
+
+OPENAPI_CLI="npx --yes @openapitools/openapi-generator-cli@${OPENAPI_GENERATOR_CLI_VERSION}"
+
+echo "==> Refreshing public spec via fern/build-public-spec.sh"
+# Reuse the ONE shared spec producer: strips /api/admin, /api/internal,
+# /api/portfolios + localhost servers, writes fern/api-public.json. Needs jq + python3.
+bash "${REPO_ROOT}/fern/build-public-spec.sh"
+
+echo "==> Validating spec"
+${OPENAPI_CLI} validate -i "${PUBLIC_SPEC}"
+
+echo "==> Generating Python core into ${OUT_DIR}"
+# --package-name spreadspace._generated keeps the generated package nested under
+# the hand-written `spreadspace` package, so it can never collide with it. But
+# the generator writes the package as a PATH under -o (i.e. <out>/spreadspace/
+# _generated/), so we generate into a throwaway stage dir and move just the
+# generated subtree into place — never touching the hand-written src/spreadspace.
+# library=urllib3: the generated low-level client uses urllib3 (the default,
+# zero extra deps in the generated tree). Our hand-written transport is httpx;
+# the generated client is the typed-model + raw-call substrate the ergonomic
+# layer sits on top of — we don't ship its HTTP path on the hot calls.
+STAGE="$(mktemp -d)"
+trap 'rm -rf "${STAGE}"' EXIT
+${OPENAPI_CLI} generate \
+  -i "${PUBLIC_SPEC}" \
+  -g "${GENERATOR_NAME}" \
+  -o "${STAGE}" \
+  --package-name spreadspace._generated \
+  --additional-properties=library=urllib3,packageVersion=0.1.0,generateSourceCodeOnly=true
+
+# Wipe first so removed models/operations don't linger (idempotent regen).
+rm -rf "${OUT_DIR}"
+mkdir -p "$(dirname "${OUT_DIR}")"
+mv "${STAGE}/spreadspace/_generated" "${OUT_DIR}"
+
+echo "==> Done."
+echo "NOTE: ${OUT_DIR} is gitignored (see sdk/python/.gitignore) and is"
+echo "      regenerated from the spec on every run — NEVER hand-edit it."

spreadspace-0.1.0/src/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",
+]