circle-so-python-sdk 0.1.0__tar.gz

circle_so_python_sdk-0.1.0/.env.example

@@ -0,0 +1,2 @@
+CIRCLE_API_TOKEN=your_token_here
+CIRCLE_COMMUNITY_URL=https://your-community.circle.so

circle_so_python_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: pytest tests/ -v --ignore=tests/integration

circle_so_python_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

circle_so_python_sdk-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.so
+.DS_Store
+scripts/

circle_so_python_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-03-14)
+
+Initial release covering all three Circle.so APIs:
+
+- Headless Auth API (4 endpoints)
+- Admin API V2 (~118 endpoints)
+- Headless Client API V1 (~101 endpoints)
+
+Features:
+- Sync and async clients via httpx
+- Pydantic V2 models for all API responses
+- Typed exceptions (AuthenticationError, NotFoundError, ValidationError, ForbiddenError, RateLimitError)
+- Auto-retry with exponential backoff and Retry-After support
+- Auto-pagination helpers (page-based and search_after cursor-based)
+- Context manager support
+- py.typed marker for PEP 561 compliance

circle_so_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 boiyelove
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

circle_so_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: circle-so-python-sdk
+Version: 0.1.0
+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
+Author: Damilola Afolabi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,circle,circle.so,community,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: 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

circle_so_python_sdk-0.1.0/README.md

@@ -0,0 +1,90 @@
+# 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

circle_so_python_sdk-0.1.0/docs/admin-api.md

@@ -0,0 +1,98 @@
+# Admin API V2
+
+Server-side community management. All methods available under `client.admin.*`.
+
+## Sub-clients
+
+| Namespace | Description |
+|---|---|
+| `client.admin.community` | Community settings, member CRUD |
+| `client.admin.access_groups` | Access groups and their members |
+| `client.admin.spaces` | Spaces, space groups, space members |
+| `client.admin.posts` | Posts, comments, topics |
+| `client.admin.events` | Events and attendees |
+| `client.admin.courses` | Course sections, lessons, progress |
+| `client.admin.tags` | Member tags, tagged members, profile fields |
+| `client.admin.misc` | Forms, segments, invitations, embeds, uploads, search, leaderboard, flagged content, live rooms |
+
+## Community
+
+```python
+community = client.admin.get_community()
+updated = client.admin.community.update_community(name="New Name")
+```
+
+## Community Members
+
+```python
+members = client.admin.community.list_community_members(page=1, per_page=20)
+member = client.admin.community.show_community_member(123)
+created = client.admin.community.create_community_member(email="new@example.com", name="New User")
+client.admin.community.update_community_member(123, headline="Updated")
+client.admin.community.deactivate_community_member(123)
+found = client.admin.community.search_community_member(email="user@example.com")
+client.admin.community.ban_community_member(123)
+```
+
+## Spaces
+
+```python
+spaces = client.admin.spaces.list_spaces(per_page=30)
+space = client.admin.spaces.show_space(1)
+new_space = client.admin.spaces.create_space(name="My Space", slug="my-space", space_group_id=1, space_type="basic")
+client.admin.spaces.update_space(1, name="Renamed")
+client.admin.spaces.delete_space(1)
+summary = client.admin.spaces.get_space_ai_summary(1)
+```
+
+## Space Groups
+
+```python
+groups = client.admin.spaces.list_space_groups()
+group = client.admin.spaces.create_space_group(name="VIP", slug="vip")
+```
+
+## Posts
+
+```python
+posts = client.admin.posts.list_posts(space_id=1)
+created = client.admin.posts.create_post(space_id=1, name="Hello", body="World")
+post = client.admin.posts.show_post(42)
+client.admin.posts.update_post(42, name="Updated Title")
+client.admin.posts.delete_post(42)
+summary = client.admin.posts.get_post_summary(42)
+```
+
+## Events
+
+```python
+events = client.admin.events.list_events(space_id=2)
+event = client.admin.events.create_event(space_id=2, name="Meetup", status="published",
+    event_setting_attributes={"starts_at": "2024-06-15T09:00:00Z", "location_type": "virtual"})
+attendees = client.admin.events.list_event_attendees(event_id=1)
+```
+
+## Courses
+
+```python
+sections = client.admin.courses.list_course_sections(space_id=3)
+lesson = client.admin.courses.create_course_lesson(name="Intro", section_id=1)
+client.admin.courses.update_course_lesson_progress(lesson_id=1, member_email="user@example.com", status="completed")
+```
+
+## Tags
+
+```python
+tags = client.admin.tags.list_member_tags()
+tag = client.admin.tags.create_member_tag(name="VIP", color="#FF0000")
+client.admin.tags.create_tagged_member(member_tag_id=1, user_email="user@example.com")
+```
+
+## Forms, Segments, and More
+
+```python
+forms = client.admin.misc.list_forms()
+segments = client.admin.misc.list_community_segments()
+results = client.admin.misc.advanced_search(query="python")
+leaderboard = client.admin.misc.get_leaderboard()
+```

circle_so_python_sdk-0.1.0/docs/auth-api.md

@@ -0,0 +1,38 @@
+# Headless Auth API
+
+Token management for headless integrations. Uses your admin API token to generate member access tokens.
+
+## Endpoints
+
+### Create Auth Token
+
+```python
+token = client.auth.create_auth_token(email="member@example.com")
+# or by SSO user ID
+token = client.auth.create_auth_token(sso_user_id="abc123")
+# or by community member ID
+token = client.auth.create_auth_token(community_member_id=42)
+
+print(token.access_token)
+print(token.refresh_token)
+print(token.community_member_id)
+```
+
+### Refresh Access Token
+
+```python
+refreshed = client.auth.refresh_access_token(refresh_token="...")
+print(refreshed.access_token)
+```
+
+### Revoke Access Token
+
+```python
+client.auth.revoke_access_token(access_token="...")
+```
+
+### Revoke Refresh Token
+
+```python
+client.auth.revoke_refresh_token(refresh_token="...")
+```

circle_so_python_sdk-0.1.0/docs/headless-api.md

@@ -0,0 +1,103 @@
+# Headless Client API V1
+
+Member-facing operations. Requires a member access token from the Headless Auth API.
+
+## Setup
+
+```python
+from circle import CircleClient
+
+# Get member token first
+admin = CircleClient(api_token="ADMIN_TOKEN")
+token = admin.auth.create_auth_token(email="member@example.com")
+
+# Create headless client with member token
+client = CircleClient(api_token=token.access_token, community_url="https://your.circle.so")
+```
+
+## Sub-clients
+
+| Namespace | Description |
+|---|---|
+| `client.headless.spaces_posts` | Spaces, posts, comments, replies, likes |
+| `client.headless.chat_notif_members` | Chat, notifications, members, events |
+| `client.headless.misc` | Courses, search, bookmarks, uploads, notification prefs |
+
+## Spaces
+
+```python
+spaces = client.headless.list_spaces()
+space = client.headless.spaces_posts.get_space(1)
+client.headless.spaces_posts.join_space(1)
+client.headless.spaces_posts.leave_space(1)
+```
+
+## Posts
+
+```python
+posts = client.headless.list_posts(1, per_page=20)
+post = client.headless.spaces_posts.get_post(1, 42)
+new_post = client.headless.spaces_posts.create_post(1, name="My Post", body="Content")
+client.headless.spaces_posts.like_post(42)
+client.headless.spaces_posts.follow_post(42)
+home = client.headless.spaces_posts.get_home_posts()
+```
+
+## Comments and Replies
+
+```python
+comments = client.headless.spaces_posts.list_comments(42)
+comment = client.headless.spaces_posts.create_comment(42, body="Nice post!")
+replies = client.headless.spaces_posts.list_replies(comment.id)
+client.headless.spaces_posts.create_reply(comment.id, body="Thanks!")
+```
+
+## Chat
+
+```python
+rooms = client.headless.chat_notif_members.list_chat_rooms()
+room = client.headless.chat_notif_members.create_chat_room(kind="direct", community_member_ids=["2"])
+messages = client.headless.chat_notif_members.list_chat_messages("room-uuid")
+client.headless.chat_notif_members.create_chat_message("room-uuid", rich_text_body={...})
+```
+
+## Notifications
+
+```python
+notifs = client.headless.chat_notif_members.list_notifications()
+client.headless.chat_notif_members.mark_notification_read(1)
+client.headless.chat_notif_members.mark_all_notifications_read()
+count = client.headless.chat_notif_members.get_new_notifications_count()
+```
+
+## Members
+
+```python
+members = client.headless.chat_notif_members.list_community_members()
+me = client.headless.chat_notif_members.get_current_member()
+profile = client.headless.chat_notif_members.get_public_profile(2)
+client.headless.chat_notif_members.update_profile(headline="New headline")
+```
+
+## Courses
+
+```python
+sections = client.headless.misc.list_course_sections(course_id=1)
+lesson = client.headless.misc.get_lesson(course_id=1, lesson_id=2)
+client.headless.misc.update_lesson_progress(1, 2, status="completed")
+```
+
+## Search
+
+```python
+results = client.headless.misc.search(search_text="python")
+advanced = client.headless.misc.advanced_search(query="python", type="posts")
+```
+
+## Bookmarks
+
+```python
+bookmarks = client.headless.misc.list_bookmarks()
+bm = client.headless.misc.create_bookmark(record_id=42, bookmark_type="post")
+client.headless.misc.delete_bookmark(bm.id)
+```

circle_so_python_sdk-0.1.0/docs/models.md

@@ -0,0 +1,40 @@
+# Models Reference
+
+All response models use Pydantic V2 with `extra="allow"` so new API fields won't break the SDK.
+
+## Base
+
+- `CircleModel` -- base for all models, allows extra fields
+- `PaginatedResponse[T]` -- generic paginated list with `page`, `per_page`, `has_next_page`, `count`, `records`
+- `ErrorResponse` -- `success`, `message`, `error_details`
+
+## Auth Models (`circle.models.auth`)
+
+- `HeadlessAuthToken` -- `access_token`, `refresh_token`, expiry timestamps, `community_member_id`, `community_id`
+- `RefreshedAccessToken` -- `access_token`, `access_token_expires_at`
+
+## Admin Models (`circle.models.admin`)
+
+| Module | Key Models |
+|---|---|
+| `community` | `Community`, `CommunitySetting`, `CommunityPrefs`, `ChatPreferences` |
+| `members` | `CommunityMember`, `CommunityMemberList`, `CommunityMemberCreated` |
+| `spaces` | `Space`, `SpaceGroup`, `SpaceMember`, `SpaceGroupMember`, `SpaceAISummary` |
+| `posts` | `BasicPost`, `ImagePost`, `Comment`, `Topic` + created/updated/deleted responses |
+| `events` | `Event`, `EventAttendee` |
+| `courses` | `CourseSection`, `CourseLesson` |
+| `tags` | `MemberTag`, `TaggedMember`, `ProfileField` |
+| `misc` | `AccessGroup`, `Form`, `FormSubmission`, `CommunitySegment`, `InvitationLink`, `Embed`, `DirectUpload`, `LiveRoom`, `FlaggedContent`, `LeaderboardMember`, `AdvancedSearchResults` |
+
+## Headless Models (`circle.models.headless`)
+
+| Module | Key Models |
+|---|---|
+| `spaces` | `HeadlessSpace`, `SpaceNotificationDetail`, `SpaceBookmark` |
+| `posts` | `HeadlessPost`, `HeadlessImagePost`, `HeadlessEventPost`, `SharedCommunityMember` |
+| `comments` | `HeadlessComment`, `UserLike` |
+| `chat` | `ChatRoom`, `ChatRoomMessage`, `ChatRoomMessages`, `ChatThread`, `ChatRoomParticipant` |
+| `notifications` | `Notification`, `NewNotificationsCount`, `MediumNotificationPreferences` |
+| `members` | `CurrentCommunityMember`, `PublicProfile`, `BasicCommunityMember`, `SearchedMember` |
+| `courses` | `Section`, `Lesson`, `LessonFile`, `QuizAttempt` |
+| `misc` | `Bookmark`, `HeadlessEventAttendee`, `RecurringEvent`, `SearchResults`, `CommunityLink`, `HeadlessDirectUpload` |

circle_so_python_sdk-0.1.0/docs/quickstart.md

@@ -0,0 +1,75 @@
+# Quickstart
+
+## Installation
+
+```bash
+pip install circle-so-python-sdk
+```
+
+## Authentication
+
+Circle.so uses different auth schemes per API:
+
+- Admin API V2: Uses `Token AUTH_TOKEN` header (server-side admin token)
+- Headless Auth: Uses `Bearer AUTH_TOKEN` header (admin token to generate member tokens)
+- Headless Client V1: Uses `Bearer ACCESS_TOKEN` header (member access token)
+
+## Basic Usage
+
+```python
+from circle import CircleClient
+
+# Create client with your admin API token
+client = CircleClient(api_token="YOUR_ADMIN_TOKEN")
+
+# Admin API -- manage your community
+community = client.admin.get_community()
+members = client.admin.list_community_members(per_page=20)
+
+# Headless Auth -- get a member access token
+token = client.auth.create_auth_token(email="member@example.com")
+
+# Headless Client -- act as a member
+member_client = CircleClient(
+    api_token=token.access_token,
+    community_url="https://your-community.circle.so"
+)
+spaces = member_client.headless.list_spaces()
+```
+
+## Async Usage
+
+```python
+from circle import AsyncCircleClient
+
+async with AsyncCircleClient(api_token="YOUR_TOKEN") as client:
+    community = await client.admin.get_community()
+    members = await client.admin.list_community_members()
+```
+
+## Auto-Pagination
+
+```python
+from circle import CircleClient
+from circle.pagination import paginate
+
+client = CircleClient(api_token="YOUR_TOKEN")
+
+# Iterate all members across all pages
+for member in paginate(client.admin.community.list_community_members, per_page=100):
+    print(member.name)
+```
+
+## Error Handling
+
+```python
+from circle import CircleClient, AuthenticationError, NotFoundError
+
+client = CircleClient(api_token="YOUR_TOKEN")
+try:
+    member = client.admin.community.show_community_member(99999)
+except NotFoundError as e:
+    print(f"Not found: {e}")
+except AuthenticationError as e:
+    print(f"Auth failed: {e}")
+```