Metadata-Version: 2.4
Name: volga-sdk
Version: 1.0.0
Summary: Official Python SDK for the Volga Public API (conversations, messages, outbound webhooks).
Project-URL: Homepage, https://hooks.volga-ai.com/v1/docs
Project-URL: Source, https://github.com/volga-ai/volga-core-lite
Author: Volga
License: MIT
Keywords: api,instagram,sdk,volga,webhooks,whatsapp
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# volga

Official Python SDK for the [Volga Public API](https://hooks.volga-ai.com/v1/docs) — conversations, messages, and outbound webhooks.

- Zero dependencies (standard library only)
- Automatic retries (429 + 5xx + network) with `Retry-After` support
- Cursor auto-pagination via generators
- Built-in webhook signature verification
- Python 3.8+

## Install

```bash
pip install volga-sdk
```

(The distribution is `volga-sdk`; you still `import volga`.)

## Quickstart

```python
import os
from volga import VolgaClient

volga = VolgaClient(api_key=os.environ["VOLGA_API_KEY"])

# List conversations
page = volga.conversations.list(channel="whatsapp", limit=25)

# Send a reply (idempotent retries)
import uuid
volga.messages.send(
    conversation_id=page["data"][0]["id"],
    text="Thanks for reaching out!",
    idempotency_key=str(uuid.uuid4()),
)
```

## Pagination

```python
# One page at a time
page = volga.messages.list(conversation_id="c_123")
print(page["data"], page["has_more"], page["next_cursor"])

# Or auto-paginate every item
for message in volga.messages.iterate(conversation_id="c_123"):
    print(message["id"], message["text"])
```

## Webhooks

Register an endpoint (the signing `secret` is returned **once**):

```python
endpoint = volga.webhook_endpoints.create(
    url="https://example.com/volga/webhooks",
    event_types=["message.received", "conversation.created"],
)
# store endpoint["secret"] securely
```

Verify and parse incoming deliveries (pass the **raw** request body):

```python
from volga import construct_event, VolgaSignatureVerificationError

@app.post("/volga/webhooks")
def handle(request):
    try:
        event = construct_event(
            secret=os.environ["VOLGA_WEBHOOK_SECRET"],
            payload=request.get_data(),  # raw bytes, not parsed JSON
            signature_header=request.headers.get("Volga-Signature"),
        )
    except VolgaSignatureVerificationError:
        return "", 400
    # handle event["type"] / event["data"] ...
    return "", 200
```

Deliveries are **at-least-once** — deduplicate on the event `id` (or the
`Volga-Delivery-Id` header).

## Errors

```python
from volga import VolgaRateLimitError, VolgaPermissionError, VolgaApiError

try:
    volga.messages.send(conversation_id=cid, text=text)
except VolgaRateLimitError as e:
    time.sleep(e.retry_after_sec or 1)
except VolgaPermissionError:
    ...  # the key is missing a scope
except VolgaApiError as e:
    print(e.status, e.code, e.message, e.trace_id)
```

| Class | Status |
| --- | --- |
| `VolgaInvalidRequestError` | 400 / 422 |
| `VolgaAuthenticationError` | 401 |
| `VolgaPaymentRequiredError` | 402 |
| `VolgaPermissionError` | 403 |
| `VolgaNotFoundError` | 404 |
| `VolgaConflictError` | 409 |
| `VolgaRateLimitError` | 429 |
| `VolgaServerError` | 5xx |
| `VolgaConnectionError` / `VolgaTimeoutError` | no response |

## Configuration

```python
VolgaClient(
    api_key="vk_live_…",
    base_url="https://hooks.volga-ai.com/v1",  # default
    timeout=30.0,        # default
    max_retries=2,       # default
    retry_base_delay=0.5,
    retry_max_delay=8.0,
)
```

## License

MIT
