Metadata-Version: 2.4
Name: softsolz
Version: 0.1.2
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
- Developer hub: https://developer.softsolz.uk

## License

MIT
