Metadata-Version: 2.4
Name: corsa-sdk
Version: 1.1.1
Summary: Python SDK for the Corsa compliance and risk API
Project-URL: Homepage, https://github.com/corsa-labs/corsa-python-sdk
Project-URL: Repository, https://github.com/corsa-labs/corsa-python-sdk
Project-URL: Issues, https://github.com/corsa-labs/corsa-python-sdk/issues
Author-email: Corsa Labs <engineering@corsa.finance>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: attrs>=23.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Corsa Python SDK

Python client for the [Corsa](https://corsa.finance) compliance and risk API.

Auto-generated from the Corsa OpenAPI specification using [openapi-python-client](https://github.com/openapi-generators/openapi-python-client), with typed Pydantic v2 models and both sync/async httpx clients.

## Installation

```bash
pip install corsa-sdk
```

## Quick Start

### Sync

```python
from corsa_sdk import CorsaClient
from corsa_sdk.models.create_alert_dto import CreateAlertDto

client = CorsaClient(
    base_url="https://api.corsa.finance",
    token="your-api-token",
)

alert = client.alerts.create_alert(body=CreateAlertDto(
    name="Suspicious activity",
    description="Large transfer flagged",
))

client.close()
```

### Async

```python
from corsa_sdk import AsyncCorsaClient
from corsa_sdk.models.create_alert_dto import CreateAlertDto

async with AsyncCorsaClient(
    base_url="https://api.corsa.finance",
    token="your-api-token",
) as client:
    alert = await client.alerts.create_alert(body=CreateAlertDto(
        name="Suspicious activity",
        description="Large transfer flagged",
    ))
```

### Context Manager (sync)

```python
with CorsaClient(base_url="https://api.corsa.finance", token="your-api-token") as client:
    case = client.cases.get_case(case_id="abc-123")
```

## API Namespaces

The client exposes each API tag as an attribute. Endpoint names match the generated module names.

| Namespace | Examples |
|-----------|----------|
| `client.alerts` | `create_alert`, `get_alert`, `update_alert`, `bulk_assign_alert` |
| `client.cases` | `create_case`, `get_case`, `update_case`, `bulk_update_case_status` |
| `client.clients` | `create_individual_client`, `create_corporate_client`, `get_individual_client` |
| `client.transactions` | `get_transaction_by_id`, `update_transaction`, `update_transaction_status` |
| `client.blockchain_wallets` | `create_blockchain_wallet`, `get_blockchain_wallet` |
| `client.bank_accounts` | `create_bank_account`, `get_bank_account` |
| `client.rules` | `create_rule`, `list_rules`, `activate_rule`, `disable_rule` |
| `client.rule_templates` | `list_rule_templates`, `get_rule_template`, `copy_rule_template` |
| `client.deposits` | `create_deposit`, `get_deposit` |
| `client.withdrawals` | `create_withdrawal`, `get_withdrawal` |
| `client.trades` | `create_trade`, `get_trade`, `add_transaction` |
| `client.sessions` | `create_session`, `get_session`, `get_client_sessions` |
| `client.members` | `create_individual_member`, `create_corporate_member` |
| `client.attachments` | `upload_attachments`, `get_attachments_by_entity` |
| `client.checklists` | `create_checklist_template`, `update_checklist_item` |
| `client.evaluation` | `evaluate`, `get_rule_evaluations` |
| `client.platform` | `get_encryption_configuration` |

## Advanced Usage

### Direct module access

For full control over the response (status code, headers), use the generated modules directly:

```python
from corsa_sdk import AuthenticatedClient
from corsa_sdk.api.alerts import create_alert
from corsa_sdk.models.create_alert_dto import CreateAlertDto

client = AuthenticatedClient(base_url="https://api.corsa.finance", token="your-api-token")

# Returns a Response object with status_code, headers, and parsed body
response = create_alert.sync_detailed(client=client, body=CreateAlertDto(...))
print(response.status_code, response.headers)
alert = response.parsed
```

### Custom headers and timeout

```python
client = CorsaClient(
    base_url="https://api.corsa.finance",
    token="your-api-token",
    timeout=60.0,
    headers={"X-Custom-Header": "value"},
)
```

### Access the underlying httpx client

```python
raw = client.raw_client.get_httpx_client()
```

## Webhook Verification

Verify incoming webhook signatures using HMAC-SHA256:

```python
from corsa_sdk import verify_webhook_signature, sign_webhook_payload

# Verify a webhook from Corsa
is_valid = verify_webhook_signature(
    secret="your-webhook-secret",
    event_payload=request.body,
    signature=request.headers["X-Signature"],
)

# Sign a payload (for testing)
sig = sign_webhook_payload("your-webhook-secret", '{"event":"alert.created"}')
```

## Error Handling

```python
from corsa_sdk.errors import UnexpectedStatus

try:
    alert = client.alerts.get_alert(alert_id="nonexistent")
except UnexpectedStatus as e:
    print(f"HTTP {e.status_code}: {e.content}")
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Type check
mypy corsa_sdk/
```

## How the SDK is Generated

This SDK is auto-generated from the Corsa API Gateway OpenAPI specification:

1. A GitHub Actions workflow runs hourly and fetches the latest `api-spec.json` from staging
2. `openapi-python-client` generates typed Python models and API modules
3. Generated code is merged into the repo (preserving manual modules like `webhooks/` and `corsa_client.py`)
4. A PR is opened for review; on merge, `python-semantic-release` publishes to PyPI

## License

MIT
