Metadata-Version: 2.4
Name: agentref
Version: 1.0.1
Summary: Official Python SDK for the AgentRef Affiliate API
Author-email: AgentRef <hi@agentref.dev>
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# AgentRef Python SDK

Official Python SDK for the AgentRef REST API v1.

## Install

```bash
pip install agentref
```

## Quickstart

```python
from agentref import AgentRef

client = AgentRef(api_key="ak_live_...")
programs = client.programs.list()
print(programs.meta.request_id)
```

## Async quickstart

```python
from agentref import AsyncAgentRef

async with AsyncAgentRef(api_key="ak_live_...") as client:
    programs = await client.programs.list()
```

## Authentication

- Uses `Authorization: Bearer <key>`.
- Supports `ak_live_*`, `ak_aff_*`, `ak_onb_*`.
- Provide `api_key` directly or set `AGENTREF_API_KEY`.

## Resources

- `client.programs`: `list`, `list_all`, `get`, `create`, `update`, `delete`, `stats`, `list_affiliates`, `list_coupons`, `create_coupon`, `create_invite`
- `client.affiliates`: `list`, `get`, `approve`, `block`, `unblock`
- `client.conversions`: `list`, `stats`, `recent`
- `client.payouts`: `list`, `list_pending`, `stats`
- `client.flags`: `list`, `stats`, `resolve`
- `client.billing`: `current`, `tiers`, `subscribe`
- `client.merchant`: `get`, `domain_status`

## Pagination

List endpoints return `PaginatedResponse[T]` with:

- `meta.total`
- `meta.page`
- `meta.page_size`
- `meta.has_more`
- `meta.next_cursor`
- `meta.request_id`

Auto-pagination (`list_all`) stops on `has_more is False`.

## Idempotency and retry behavior

- GET/HEAD: auto-retry on 429/5xx.
- POST: auto-retry only when `idempotency_key` is provided.
- PATCH/DELETE: never auto-retry.
- `Idempotency-Key` header is sent only for POST requests.

## Error handling

```python
from agentref import AgentRef
from agentref.errors import ForbiddenError, NotFoundError, RateLimitError, AgentRefError

client = AgentRef(api_key="ak_live_...")

try:
    client.programs.get("missing-id")
except ForbiddenError as e:
    print(e.code, e.request_id)
except NotFoundError as e:
    print(e.request_id)
except RateLimitError as e:
    print(e.retry_after)
except AgentRefError as e:
    print(e.status)
```
