Metadata-Version: 2.4
Name: cavaridge
Version: 0.1.0
Summary: Official Python SDK for the Cavaridge public API.
Project-URL: Homepage, https://docs.cavaridge.app/sdks/python/
Project-URL: Documentation, https://docs.cavaridge.app/sdks/python/
Project-URL: Source, https://github.com/Cavaridge-LLC/cavaridge
Author-email: "Cavaridge, LLC" <support@cavaridge.com>
License: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# cavaridge

Official Python SDK for the Cavaridge™ public API.

## Install

```bash
pip install cavaridge
```

## Quickstart

```python
import os
from cavaridge import CavaridgeClient

client = CavaridgeClient(api_key=os.environ["CAVARIDGE_API_KEY"])

page = client.aegis.list_scans(limit=5)
for scan in page["data"]:
    print(scan["id"], scan["status"])

# Paginate everything:
for finding in client.paginate("GET", "/v2026-04-27/aegis/findings", query={"severity": "high"}):
    print(finding)
```

## Auth

- **API key**: `CavaridgeClient(api_key="sk_live_...")` (sandbox: `sk_test_...`).
- **OAuth bearer**: `CavaridgeClient(bearer_token="...")`.
- Falls back to `CAVARIDGE_API_KEY` env var when neither is provided.

## Idempotency

```python
client.cavalier.create_quote(
    client_id="ten_abc",
    line_items=[{"catalog_id": "operations_pro", "quantity": 1}],
    idempotency_key="qt_create_2026-05-04_001",
)
```

## Errors

Failures raise `CavaridgeError` with `.type`, `.status`, `.detail`, `.request_id`, and `.documentation_url`.

```python
from cavaridge import CavaridgeError

try:
    client.reclaim.execute_policy("pol_abc")
except CavaridgeError as err:
    if err.status == 403 and err.type.endswith("/insufficient_scope"):
        print("need reclaim.policies.manage scope")
    raise
```

## Retries

Default: 3 retries on `429` and 5xx with exponential backoff (250ms → 500ms → 1000ms). Override with `max_retries`.

## Sandbox

```python
CavaridgeClient(api_key=os.environ["CAVARIDGE_TEST_KEY"], base_url="https://api-sandbox.cavaridge.app")
```

## Versioning

SDK semver maps to spec dated versions:

- **major** → API dated version
- **minor** → additive features within a dated version
- **patch** → bug fixes only

## Docs

- [API overview](https://docs.cavaridge.app/api/overview/)
- [Patterns](https://github.com/Cavaridge-LLC/cavaridge/blob/main/packages/public-api-spec/PATTERNS.md)
- [Python SDK guide](https://docs.cavaridge.app/sdks/python/)
