softsolz 0.1.0__tar.gz

softsolz-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.tsbuildinfo
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+coverage/
+.DS_Store

softsolz-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: softsolz
+Version: 0.1.0
+Summary: Official Python SDK for the SoftSolz platform API.
+Project-URL: Homepage, https://developer.softsolz.uk
+Project-URL: Documentation, https://developer.softsolz.uk
+Project-URL: Repository, https://github.com/soft-solz/sdk
+Author: SoftSolz
+License-Expression: MIT
+Keywords: api,forms,invoicing,payments,sdk,softsolz,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.26
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# softsolz
+
+Official Python SDK for the [SoftSolz platform API](https://developer.softsolz.uk).
+
+```bash
+pip install softsolz
+```
+
+Requires Python 3.9 or later. Fully type-annotated (`py.typed`).
+
+## Usage
+
+```python
+import os
+from softsolz import SoftSolz
+
+client = SoftSolz(api_key=os.environ["SOFTSOLZ_API_KEY"])
+
+me = client.whoami()
+
+form = client.forms.create_form({"name": "Contact Us", "status": "published"})
+client.forms.submit_form(form["slug"], {"data": {"full_name": "Jane Doe", "email": "jane@example.com"}})
+
+invoice = client.invoicing.create_invoice({
+    "customer_id": 42,
+    "lines": [{"description": "Design work", "quantity": 1, "unit_price_cents": 50000}],
+})
+client.invoicing.send_invoice(invoice["id"])
+```
+
+Use an `sk_test_*` key to run against your sandbox workspace; swap to `sk_live_*` in production. No other configuration changes.
+
+### Services
+
+`client.blogs`, `client.customer_auth`, `client.forms`, `client.invoicing`, `client.payments`, `client.smart_chat`, `client.social`, `client.workflows` - one method per API operation, generated from the platform's service manifests.
+
+### Pagination
+
+List methods return a `Page` you can iterate; extra pages are fetched automatically:
+
+```python
+for invoice in client.invoicing.list_invoices({"status": "overdue"}):
+    print(invoice["invoice_number"])
+```
+
+Or page manually with `page.data`, `page.has_more`, and `page.next_page()`.
+
+### Errors
+
+All API failures raise a typed subclass of `SoftSolzError` carrying `status`, `code`, `message`, `details`, and `request_id`:
+
+```python
+from softsolz import NotFoundError
+
+try:
+    client.forms.get_form(999)
+except NotFoundError as err:
+    print(err.code, err.request_id)
+```
+
+Classes: `InvalidRequestError` (400/422), `AuthenticationError` (401), `PaymentRequiredError` (402), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `retry_after_seconds`), `APIConnectionError` (network).
+
+### Retries and idempotency
+
+429 and 5xx responses are retried automatically with exponential backoff (default 2 retries), honouring `Retry-After`. Every mutating request carries an auto-generated `Idempotency-Key`, so retries are always safe. Pass your own to control replays:
+
+```python
+client.invoicing.create_invoice(body, idempotency_key="order-1234")
+```
+
+Configure per client: `SoftSolz(api_key=..., max_retries=3, timeout=60.0)`.
+
+### Webhooks
+
+Verify the `Softsolz-Signature` header on incoming webhooks using the raw request body:
+
+```python
+from softsolz import webhooks
+
+webhooks.assert_valid(
+    raw_body=request.get_data(),
+    header_value=request.headers.get("Softsolz-Signature"),
+    secret=os.environ["SOFTSOLZ_WEBHOOK_SECRET"],
+)
+```
+
+`webhooks.verify(...)` returns `{"valid": False, "reason": ...}` if you prefer not to raise.
+
+### Escape hatch
+
+Call any endpoint directly while keeping auth, retries, and errors:
+
+```python
+client.request("GET", "/api/v1/services/forms/forms", query={"limit": 10})
+```
+
+## Documentation
+
+- API reference: https://developer.softsolz.uk/api-reference.html
+- Webhooks: https://developer.softsolz.uk/webhooks.html
+- Playground: https://playground.softsolz.uk
+
+## License
+
+MIT

softsolz-0.1.0/README.md

@@ -0,0 +1,105 @@
+# softsolz
+
+Official Python SDK for the [SoftSolz platform API](https://developer.softsolz.uk).
+
+```bash
+pip install softsolz
+```
+
+Requires Python 3.9 or later. Fully type-annotated (`py.typed`).
+
+## Usage
+
+```python
+import os
+from softsolz import SoftSolz
+
+client = SoftSolz(api_key=os.environ["SOFTSOLZ_API_KEY"])
+
+me = client.whoami()
+
+form = client.forms.create_form({"name": "Contact Us", "status": "published"})
+client.forms.submit_form(form["slug"], {"data": {"full_name": "Jane Doe", "email": "jane@example.com"}})
+
+invoice = client.invoicing.create_invoice({
+    "customer_id": 42,
+    "lines": [{"description": "Design work", "quantity": 1, "unit_price_cents": 50000}],
+})
+client.invoicing.send_invoice(invoice["id"])
+```
+
+Use an `sk_test_*` key to run against your sandbox workspace; swap to `sk_live_*` in production. No other configuration changes.
+
+### Services
+
+`client.blogs`, `client.customer_auth`, `client.forms`, `client.invoicing`, `client.payments`, `client.smart_chat`, `client.social`, `client.workflows` - one method per API operation, generated from the platform's service manifests.
+
+### Pagination
+
+List methods return a `Page` you can iterate; extra pages are fetched automatically:
+
+```python
+for invoice in client.invoicing.list_invoices({"status": "overdue"}):
+    print(invoice["invoice_number"])
+```
+
+Or page manually with `page.data`, `page.has_more`, and `page.next_page()`.
+
+### Errors
+
+All API failures raise a typed subclass of `SoftSolzError` carrying `status`, `code`, `message`, `details`, and `request_id`:
+
+```python
+from softsolz import NotFoundError
+
+try:
+    client.forms.get_form(999)
+except NotFoundError as err:
+    print(err.code, err.request_id)
+```
+
+Classes: `InvalidRequestError` (400/422), `AuthenticationError` (401), `PaymentRequiredError` (402), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429, with `retry_after_seconds`), `APIConnectionError` (network).
+
+### Retries and idempotency
+
+429 and 5xx responses are retried automatically with exponential backoff (default 2 retries), honouring `Retry-After`. Every mutating request carries an auto-generated `Idempotency-Key`, so retries are always safe. Pass your own to control replays:
+
+```python
+client.invoicing.create_invoice(body, idempotency_key="order-1234")
+```
+
+Configure per client: `SoftSolz(api_key=..., max_retries=3, timeout=60.0)`.
+
+### Webhooks
+
+Verify the `Softsolz-Signature` header on incoming webhooks using the raw request body:
+
+```python
+from softsolz import webhooks
+
+webhooks.assert_valid(
+    raw_body=request.get_data(),
+    header_value=request.headers.get("Softsolz-Signature"),
+    secret=os.environ["SOFTSOLZ_WEBHOOK_SECRET"],
+)
+```
+
+`webhooks.verify(...)` returns `{"valid": False, "reason": ...}` if you prefer not to raise.
+
+### Escape hatch
+
+Call any endpoint directly while keeping auth, retries, and errors:
+
+```python
+client.request("GET", "/api/v1/services/forms/forms", query={"limit": 10})
+```
+
+## Documentation
+
+- API reference: https://developer.softsolz.uk/api-reference.html
+- Webhooks: https://developer.softsolz.uk/webhooks.html
+- Playground: https://playground.softsolz.uk
+
+## License
+
+MIT

softsolz-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "softsolz"
+version = "0.1.0"
+description = "Official Python SDK for the SoftSolz platform API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "SoftSolz" }]
+keywords = ["softsolz", "sdk", "api", "forms", "invoicing", "payments", "webhooks"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "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",
+]
+dependencies = ["httpx>=0.26,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://developer.softsolz.uk"
+Documentation = "https://developer.softsolz.uk"
+Repository = "https://github.com/soft-solz/sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/softsolz"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

softsolz-0.1.0/src/softsolz/__init__.py

@@ -0,0 +1,35 @@
+from . import webhooks
+from ._client import SoftSolz
+from ._http import DEFAULT_BASE_URL
+from ._version import __version__
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    ConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    SoftSolzError,
+    WebhookSignatureError,
+)
+from .pagination import Page
+
+__all__ = [
+    "SoftSolz",
+    "Page",
+    "webhooks",
+    "DEFAULT_BASE_URL",
+    "SoftSolzError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "PaymentRequiredError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "APIConnectionError",
+    "WebhookSignatureError",
+    "__version__",
+]

softsolz-0.1.0/src/softsolz/_client.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, HttpClient
+from .resources import build_resources
+
+
+class SoftSolz:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._http = HttpClient(
+            api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            transport=transport,
+        )
+        for name, resource in build_resources(self._http).items():
+            setattr(self, name, resource)
+
+    def whoami(self, **options: Any) -> Any:
+        return self._http.request("GET", "/api/v1/whoami", options=options or None)
+
+    def services(self, **options: Any) -> Any:
+        return self._http.request("GET", "/api/v1/services", options=options or None)
+
+    def service_health(self, service_id: str, **options: Any) -> Any:
+        from ._http import _q
+
+        return self._http.request(
+            "GET", f"/api/v1/services/{_q(service_id)}/health", options=options or None
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        **options: Any,
+    ) -> Any:
+        return self._http.request(method, path, query=query, body=body, options=options or None)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SoftSolz":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()

softsolz-0.1.0/src/softsolz/_http.py

@@ -0,0 +1,153 @@
+import random
+import time
+import uuid
+from typing import Any, Dict, Optional
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from .errors import APIConnectionError, error_from_response
+from .pagination import Page
+
+DEFAULT_BASE_URL = "https://app.softsolz.uk"
+
+_MUTATING_METHODS = {"POST", "PUT", "PATCH", "DELETE"}
+
+
+def _q(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
+def _backoff_seconds(attempt: int) -> float:
+    return min(8.0, 0.5 * (2**attempt)) + random.random() * 0.25
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key or not isinstance(api_key, str):
+            raise ValueError('SoftSolz: api_key is required, e.g. SoftSolz(api_key="sk_test_...")')
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "authorization": f"Bearer {api_key}",
+                "accept": "application/json",
+                "user-agent": f"softsolz-python/{__version__}",
+            },
+        )
+
+    def envelope(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        response_kind: str = "json",
+        options: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        options = options or {}
+        method = method.upper()
+        headers: Dict[str, str] = {}
+        if options.get("request_id"):
+            headers["x-request-id"] = str(options["request_id"])
+        if method in _MUTATING_METHODS:
+            headers["idempotency-key"] = str(options.get("idempotency_key") or uuid.uuid4())
+        params = {k: v for k, v in (query or {}).items() if v is not None}
+        max_retries = int(options.get("max_retries", self._max_retries))
+        timeout = options.get("timeout")
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    json=body,
+                    headers=headers,
+                    timeout=timeout if timeout is not None else httpx.USE_CLIENT_DEFAULT,
+                )
+            except httpx.HTTPError as exc:
+                if attempt < max_retries:
+                    time.sleep(_backoff_seconds(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(str(exc)) from exc
+            request_id = response.headers.get("softsolz-request-id")
+            if response.is_success:
+                if response_kind == "none" or response.status_code == 204:
+                    return {"data": None, "meta": None, "request_id": request_id}
+                if response_kind == "text":
+                    return {"data": response.text, "meta": None, "request_id": request_id}
+                if response_kind == "binary":
+                    return {"data": response.content, "meta": None, "request_id": request_id}
+                payload = self._safe_json(response)
+                if isinstance(payload, dict) and "data" in payload:
+                    data = payload.get("data")
+                    meta = payload.get("meta") if isinstance(payload.get("meta"), dict) else None
+                else:
+                    data = payload
+                    meta = None
+                return {"data": data, "meta": meta, "request_id": request_id}
+            retryable = response.status_code == 429 or response.status_code >= 500
+            if retryable and attempt < max_retries:
+                retry_after = response.headers.get("retry-after")
+                if retry_after and retry_after.isdigit() and int(retry_after) > 0:
+                    delay = float(retry_after)
+                else:
+                    delay = _backoff_seconds(attempt)
+                time.sleep(delay)
+                attempt += 1
+                continue
+            raise error_from_response(response.status_code, self._safe_json(response), request_id)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Optional[Dict[str, Any]] = None,
+        response_kind: str = "json",
+        options: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return self.envelope(
+            method, path, query=query, body=body, response_kind=response_kind, options=options
+        )["data"]
+
+    def page(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        options: Optional[Dict[str, Any]] = None,
+    ) -> Page:
+        def fetch_page(offset: Optional[int]) -> Dict[str, Any]:
+            merged = dict(query or {})
+            if offset is not None:
+                merged["offset"] = offset
+            return self.envelope(method, path, query=merged, options=options)
+
+        return Page.create(fetch_page)
+
+    @staticmethod
+    def _safe_json(response: httpx.Response) -> Any:
+        try:
+            return response.json()
+        except ValueError:
+            return None
+
+    def close(self) -> None:
+        self._client.close()

softsolz-0.1.0/src/softsolz/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

softsolz-0.1.0/src/softsolz/errors.py

@@ -0,0 +1,91 @@
+from typing import Any, Dict, Optional
+
+
+class SoftSolzError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "unknown_error",
+        details: Optional[Dict[str, Any]] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.details = details
+        self.request_id = request_id
+
+
+class InvalidRequestError(SoftSolzError):
+    pass
+
+
+class AuthenticationError(SoftSolzError):
+    pass
+
+
+class PermissionDeniedError(SoftSolzError):
+    pass
+
+
+class PaymentRequiredError(SoftSolzError):
+    pass
+
+
+class NotFoundError(SoftSolzError):
+    pass
+
+
+class ConflictError(SoftSolzError):
+    pass
+
+
+class RateLimitError(SoftSolzError):
+    def __init__(self, message: str, *, retry_after_seconds: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class APIConnectionError(SoftSolzError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, status=0, code="connection_error")
+
+
+class WebhookSignatureError(Exception):
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"Webhook signature verification failed: {reason}")
+        self.reason = reason
+
+
+_STATUS_TO_ERROR = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: InvalidRequestError,
+}
+
+
+def error_from_response(status: int, body: Any, request_id: Optional[str] = None) -> SoftSolzError:
+    err = body.get("error") if isinstance(body, dict) else None
+    err = err if isinstance(err, dict) else {}
+    code = err.get("code") if isinstance(err.get("code"), str) else "unknown_error"
+    message = err.get("message") if isinstance(err.get("message"), str) else f"HTTP {status}"
+    details = err.get("details") if isinstance(err.get("details"), dict) else None
+    if status == 429:
+        retry_after = details.get("retry_after_seconds") if details else None
+        return RateLimitError(
+            message,
+            status=status,
+            code=code,
+            details=details,
+            request_id=request_id,
+            retry_after_seconds=retry_after if isinstance(retry_after, int) else None,
+        )
+    error_class = _STATUS_TO_ERROR.get(status, SoftSolzError)
+    return error_class(message, status=status, code=code, details=details, request_id=request_id)

softsolz-0.1.0/src/softsolz/pagination.py

@@ -0,0 +1,39 @@
+from typing import Any, Callable, Dict, Iterator, List, Optional
+
+
+class Page:
+    def __init__(
+        self,
+        data: List[Any],
+        meta: Optional[Dict[str, Any]],
+        fetch_page: Callable[[Optional[int]], Dict[str, Any]],
+    ) -> None:
+        self.data = data
+        self.meta = meta
+        self._fetch_page = fetch_page
+
+    @classmethod
+    def create(cls, fetch_page: Callable[[Optional[int]], Dict[str, Any]]) -> "Page":
+        envelope = fetch_page(None)
+        return cls(envelope.get("data") or [], envelope.get("meta"), fetch_page)
+
+    @property
+    def has_more(self) -> bool:
+        return bool(self.meta) and self.meta.get("has_more") is True
+
+    def next_page(self) -> Optional["Page"]:
+        if not self.has_more or not self.meta:
+            return None
+        offset = int(self.meta.get("offset", 0)) + int(self.meta.get("limit", len(self.data)))
+        envelope = self._fetch_page(offset)
+        return Page(envelope.get("data") or [], envelope.get("meta"), self._fetch_page)
+
+    def __iter__(self) -> Iterator[Any]:
+        page: Optional[Page] = self
+        while page is not None:
+            for item in page.data:
+                yield item
+            page = page.next_page()
+
+    def auto_paging_iter(self) -> Iterator[Any]:
+        return iter(self)