Metadata-Version: 2.4
Name: circle-so-python-sdk
Version: 0.1.1
Summary: Python SDK for Circle.so - Admin V2, Headless Auth, and Headless Client V1 APIs
Project-URL: Homepage, https://github.com/boiyelove/circle-so-python-sdk
Project-URL: Documentation, https://github.com/boiyelove/circle-so-python-sdk/tree/main/docs
Project-URL: Repository, https://github.com/boiyelove/circle-so-python-sdk
Project-URL: Changelog, https://github.com/boiyelove/circle-so-python-sdk/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/boiyelove/circle-so-python-sdk/issues
Author: Damilola Afolabi
License-Expression: MIT
License-File: LICENSE
Keywords: admin-api,api,circle,circle-api,circle-python,circle-sdk,circle-so,circle.so,community,community-management,headless-api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# circle-so-python-sdk

[![CI](https://github.com/boiyelove/circle-so-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/boiyelove/circle-so-python-sdk/actions/workflows/ci.yml)

Python SDK for [Circle.so](https://circle.so) covering three APIs:

- Headless Auth API -- token management for headless integrations
- Admin API V2 -- server-side community management (~120 endpoints)
- Headless Client API V1 -- member-facing operations (~100 endpoints)

## Installation

```bash
pip install circle-so-python-sdk
```

## Quick Start

```python
from circle import CircleClient

# Admin API usage
client = CircleClient(api_token="YOUR_ADMIN_TOKEN")
community = client.admin.get_community()

# Headless Auth -- get member tokens
token = client.auth.create_auth_token(email="member@example.com")

# Headless Client -- use member access token
headless = CircleClient(api_token=token.access_token, community_url="https://your-community.circle.so")
spaces = headless.headless.list_spaces()
```

## Async Support

```python
from circle import AsyncCircleClient

async with AsyncCircleClient(api_token="YOUR_TOKEN") as client:
    members = await client.admin.list_community_members()
```

## API Coverage

| API | Endpoints | Sync | Async |
|---|---|---|---|
| Headless Auth | 4 | Yes | Yes |
| Admin V2 | ~118 | Yes | Yes |
| Headless Client V1 | ~101 | Yes | Yes |

## Documentation

- [Quickstart](docs/quickstart.md) -- install, auth, basic usage
- [Admin API](docs/admin-api.md) -- all admin endpoints with examples
- [Headless API](docs/headless-api.md) -- all headless endpoints with examples
- [Auth API](docs/auth-api.md) -- headless auth token management
- [Models](docs/models.md) -- complete models reference
- [Webhooks](docs/webhooks.md) -- signature verification and payload parsing

## Project Structure

```
src/circle/
  __init__.py           # Public API exports
  client.py             # CircleClient / AsyncCircleClient facade
  http.py               # Sync/Async HTTP transport with retry
  exceptions.py         # Typed exceptions (401/403/404/422/429)
  pagination.py         # Auto-pagination helpers
  rate_limit.py         # Token bucket rate limiter
  validation.py         # Request body validation models
  webhooks.py           # Webhook signature verification
  models/
    auth.py             # HeadlessAuthToken, RefreshedAccessToken
    admin/              # ~35 Pydantic models for Admin API
    headless/           # ~40 Pydantic models for Headless API
  api/
    auth.py             # Headless Auth client (4 endpoints)
    admin_*.py          # 8 Admin API client modules
    headless_*.py       # 3 Headless API client modules
```

## Contributing

1. Clone the repo and install in dev mode: `pip install -e .[dev]`
2. Run tests: `pytest tests/ -v --ignore=tests/integration`
3. Follow conventional commit format for commit messages

## License

MIT
