Metadata-Version: 2.4
Name: circle-so-python-sdk
Version: 0.1.4
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
```

## Token Types

Circle uses two different API tokens. Which one you need depends on what you want to access:

| Token | Source | Use for |
|-------|--------|---------|
| **Admin API token** | Circle Admin > Settings > API | `client.admin.*` -- manage members, spaces, posts as admin |
| **Headless Auth token** | Circle Admin > Developers > Headless Auth | `client.auth.*` + `client.headless.*` -- DMs, notifications, posts as a user |

These are **not interchangeable**. Admin endpoints return 401 with a headless token and vice versa.

## Quick Start

```python
from circle import CircleClient

# --- Admin API (server-side management) ---
# Requires: Admin API token
admin_client = CircleClient(api_token="YOUR_ADMIN_TOKEN")
community = admin_client.admin.get_community()
members = admin_client.admin.list_community_members()

# --- Creating posts (admin API) ---
# tiptap_body MUST be wrapped in a "body" key, and uses camelCase node types
tiptap_body = {
    "body": {
        "type": "doc",
        "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": "Hello world"}]},
            {"type": "bulletList", "content": [
                {"type": "listItem", "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Item one"}]}]},
            ]},
        ]
    }
}
post = admin_client.admin.posts.create_post(
    space_id=123456,
    name="My Post Title",
    tiptap_body=tiptap_body,
    status="published",
)

# --- Headless API (user-scoped: DMs, notifications, posts) ---
# Requires: Headless Auth token
headless_client = CircleClient(api_token="YOUR_HEADLESS_TOKEN")

# Option 1: Convenience method (recommended)
user = headless_client.headless_as_user(email="you@example.com")
rooms = user.chat_notif_members.list_chat_rooms()
unread = user.chat_notif_members.get_unread_chat_rooms()

# Option 2: Manual two-step flow
token = headless_client.auth.create_auth_token(email="you@example.com")
user_client = CircleClient(api_token=token.access_token, community_url="https://your-community.circle.so")
spaces = user_client.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
- [Limitations](docs/limitations.md) -- known Circle API limitations (mentions, polls, moderators)

## 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
