Metadata-Version: 2.5
Name: cadenya
Version: 1.0.0
Summary: The official Python SDK for the Cadenya API
Project-URL: Homepage, https://cadenya.com
License: UNLICENSED
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.0
Description-Content-Type: text/markdown

# Cadenya Python SDK

The official Python client for the Cadenya API. Generated by redwood.
Built on httpx; typed with dataclass models, TypedDict request shapes, and
a `py.typed` marker.

## Install

```sh
pip install cadenya
```

## Getting started

```python
from cadenya import Cadenya

# Reads CADENYA_API_KEY (and CADENYA_WORKSPACE_ID) from the environment when
# arguments are omitted. Explicit blank values raise ValueError and never
# fall back to the environment.
with Cadenya() as client:
    result = client.accounts.retrieve()
```

`Cadenya` is a context manager; `close()` releases the internally owned
httpx client (a caller-supplied `http_client` is never closed).

## Requests are snake_case throughout

Nested request objects take snake_case keys and are translated to wire
names at the HTTP boundary. Wire-format keys also pass through for raw
payloads; your own data inside JSON/map fields is never rewritten.

```python
client.api_keys.create(
    metadata={"name": "sample"},
    spec={},
)
```

## Errors

Non-2xx responses raise `APIError` (google.rpc Status: `status_code`,
`code`, `message`, `details`). Protocol surprises (unfollowed redirects,
non-JSON success bodies) raise `APIResponseError`; connection failures
raise `APIConnectionError`.

## Retries

Automatic retries apply only to idempotent methods (GET/HEAD/PUT/DELETE)
and default to 0; counts normalize to a bounded 0–10 integer. Streaming
requests never auto-retry and their read timeout is unlimited (connect/
write/pool stay bounded).


## Pagination

```python
for item in client.api_keys.list():
    ...  # iterating a page auto-fetches every page
```

## Streaming (SSE)

Streams are context managers — early exits close the response
deterministically:

```python
with client.objectives.stream_events(objective_id) as stream:
    for event in stream:
        ...

# Resume after a disconnect: the checkpoint persists per the SSE spec.
with client.objectives.stream_events(objective_id, last_event_id=stream.last_event_id) as resumed:
    for event in resumed:
        ...
```

## Webhooks (no API key required)

```python
import os

from cadenya import unwrap_webhook

event = unwrap_webhook(payload, headers, secret=os.environ["CADENYA_WEBHOOK_SECRET"])
```

Verification follows Standard Webhooks (24–64 byte decoded secrets,
integer timestamps, bounded tolerance).

## Reference

The full method reference ships with the package as `cadenya/api.md`
(importlib.resources reads it; it is also in the repository).
