circle-so-python-sdk 0.1.0__py3-none-any.whl

circle/api/headless_spaces_posts.py

@@ -0,0 +1,279 @@
+"""Headless Client API -- Spaces, Posts, Comments."""
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+from circle.constants import HEADLESS_V1_PREFIX as _P
+from circle.http import AsyncTransport, SyncTransport
+from circle.models.headless.spaces import (
+    HeadlessSpace, HeadlessSpaceList, SpaceNotificationDetail, SpaceBookmarkList, HeadlessSpaceTopicList,
+)
+from circle.models.headless.posts import HeadlessPost, HeadlessPostList, HeadlessImagePost
+from circle.models.headless.comments import HeadlessComment, HeadlessCommentList, UserLikeList
+
+
+def _list_posts_params(page=1, per_page=10, sort=None, status=None, topics=None, **kw):
+    p: Dict[str, Any] = {"page": page, "per_page": per_page, **kw}
+    if sort: p["sort"] = sort
+    if status: p["status"] = status
+    if topics: p["topics"] = topics
+    return p
+
+
+def _comment_params(page=1, per_page=60, sort=None):
+    p: Dict[str, Any] = {"page": page, "per_page": per_page}
+    if sort: p["sort"] = sort
+    return p
+
+
+def _home_params(page=1, per_page=10, sort=None):
+    p: Dict[str, Any] = {"page": page, "per_page": per_page}
+    if sort: p["sort"] = sort
+    return p
+
+
+class HeadlessSpacesPostsClient:
+    def __init__(self, transport: SyncTransport) -> None:
+        self._t = transport
+
+    def list_spaces(self) -> List[HeadlessSpace]:
+        return [HeadlessSpace.model_validate(s) for s in self._t.request("GET", f"{_P}/spaces")]
+
+    def get_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(self._t.request("GET", f"{_P}/spaces/{space_id}"))
+
+    def get_home_space(self) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(self._t.request("GET", f"{_P}/spaces/home"))
+
+    def join_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(self._t.request("POST", f"{_P}/spaces/{space_id}/join"))
+
+    def leave_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(self._t.request("POST", f"{_P}/spaces/{space_id}/leave"))
+
+    def get_space_topics(self, space_id: int, *, page: int = 1, per_page: int = 10) -> HeadlessSpaceTopicList:
+        return HeadlessSpaceTopicList.model_validate(
+            self._t.request("GET", f"{_P}/spaces/{space_id}/topics", params={"page": page, "per_page": per_page}))
+
+    def get_space_bookmarks(self, space_id: int, *, page: int = 1, per_page: int = 10) -> SpaceBookmarkList:
+        return SpaceBookmarkList.model_validate(
+            self._t.request("GET", f"{_P}/spaces/{space_id}/bookmarks", params={"page": page, "per_page": per_page}))
+
+    def get_space_notification_details(self, *, space_ids: Optional[str] = None) -> List[SpaceNotificationDetail]:
+        p: Dict[str, Any] = {}
+        if space_ids: p["space_ids"] = space_ids
+        return [SpaceNotificationDetail.model_validate(d) for d in
+                self._t.request("GET", f"{_P}/space_notification_details", params=p)]
+
+    def list_posts(self, space_id: int, **kw: Any) -> HeadlessPostList:
+        return HeadlessPostList.model_validate(
+            self._t.request("GET", f"{_P}/spaces/{space_id}/posts", params=_list_posts_params(**kw)))
+
+    def create_post(self, space_id: int, **kw: Any) -> HeadlessPost:
+        return HeadlessPost.model_validate(self._t.request("POST", f"{_P}/spaces/{space_id}/posts", json=kw))
+
+    def get_post(self, space_id: int, post_id: int) -> HeadlessPost:
+        return HeadlessPost.model_validate(self._t.request("GET", f"{_P}/spaces/{space_id}/posts/{post_id}"))
+
+    def delete_post(self, space_id: int, post_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/spaces/{space_id}/posts/{post_id}")
+
+    def create_image_post(self, space_id: int, **kw: Any) -> HeadlessImagePost:
+        return HeadlessImagePost.model_validate(
+            self._t.request("POST", f"{_P}/spaces/{space_id}/images/posts", json=kw))
+
+    def update_image_post(self, space_id: int, post_id: int, **kw: Any) -> HeadlessImagePost:
+        return HeadlessImagePost.model_validate(
+            self._t.request("PUT", f"{_P}/spaces/{space_id}/images/posts/{post_id}", json=kw))
+
+    def follow_post(self, post_id: int) -> Dict[str, Any]:
+        return self._t.request("POST", f"{_P}/posts/{post_id}/post_followers")
+
+    def unfollow_post(self, post_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/posts/{post_id}/post_followers")
+
+    def like_post(self, post_id: int) -> Dict[str, Any]:
+        return self._t.request("POST", f"{_P}/posts/{post_id}/user_likes")
+
+    def unlike_post(self, post_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/posts/{post_id}/user_likes")
+
+    def get_post_likes(self, post_id: int, *, page: int = 1, per_page: int = 10) -> UserLikeList:
+        return UserLikeList.model_validate(
+            self._t.request("GET", f"{_P}/posts/{post_id}/user_likes", params={"page": page, "per_page": per_page}))
+
+    def get_home_posts(self, **kw: Any) -> HeadlessPostList:
+        return HeadlessPostList.model_validate(self._t.request("GET", f"{_P}/home", params=_home_params(**kw)))
+
+    def list_comments(self, post_id: int, **kw: Any) -> HeadlessCommentList:
+        return HeadlessCommentList.model_validate(
+            self._t.request("GET", f"{_P}/posts/{post_id}/comments", params=_comment_params(**kw)))
+
+    def create_comment(self, post_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("POST", f"{_P}/posts/{post_id}/comments", json={"comment": kw}))
+
+    def get_comment(self, post_id: int, comment_id: int) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("GET", f"{_P}/posts/{post_id}/comments/{comment_id}"))
+
+    def update_comment(self, post_id: int, comment_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("PATCH", f"{_P}/posts/{post_id}/comments/{comment_id}", json={"comment": kw}))
+
+    def delete_comment(self, post_id: int, comment_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/posts/{post_id}/comments/{comment_id}")
+
+    def list_replies(self, comment_id: int, **kw: Any) -> HeadlessCommentList:
+        return HeadlessCommentList.model_validate(
+            self._t.request("GET", f"{_P}/comments/{comment_id}/replies", params=_comment_params(**kw)))
+
+    def create_reply(self, comment_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("POST", f"{_P}/comments/{comment_id}/replies", json={"comment": kw}))
+
+    def get_reply(self, comment_id: int, reply_id: int) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("GET", f"{_P}/comments/{comment_id}/replies/{reply_id}"))
+
+    def update_reply(self, comment_id: int, reply_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            self._t.request("PATCH", f"{_P}/comments/{comment_id}/replies/{reply_id}", json={"comment": kw}))
+
+    def delete_reply(self, comment_id: int, reply_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/comments/{comment_id}/replies/{reply_id}")
+
+    def like_comment(self, comment_id: int) -> Dict[str, Any]:
+        return self._t.request("POST", f"{_P}/comments/{comment_id}/user_likes")
+
+    def unlike_comment(self, comment_id: int) -> Dict[str, Any]:
+        return self._t.request("DELETE", f"{_P}/comments/{comment_id}/user_likes")
+
+    def get_comment_likes(self, comment_id: int, *, page: int = 1, per_page: int = 10) -> UserLikeList:
+        return UserLikeList.model_validate(
+            self._t.request("GET", f"{_P}/comments/{comment_id}/user_likes",
+                            params={"page": page, "per_page": per_page}))
+
+
+class AsyncHeadlessSpacesPostsClient:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._t = transport
+
+    async def list_spaces(self) -> List[HeadlessSpace]:
+        return [HeadlessSpace.model_validate(s) for s in await self._t.request("GET", f"{_P}/spaces")]
+
+    async def get_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(await self._t.request("GET", f"{_P}/spaces/{space_id}"))
+
+    async def get_home_space(self) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(await self._t.request("GET", f"{_P}/spaces/home"))
+
+    async def join_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(await self._t.request("POST", f"{_P}/spaces/{space_id}/join"))
+
+    async def leave_space(self, space_id: int) -> HeadlessSpace:
+        return HeadlessSpace.model_validate(await self._t.request("POST", f"{_P}/spaces/{space_id}/leave"))
+
+    async def get_space_topics(self, space_id: int, *, page: int = 1, per_page: int = 10) -> HeadlessSpaceTopicList:
+        return HeadlessSpaceTopicList.model_validate(
+            await self._t.request("GET", f"{_P}/spaces/{space_id}/topics",
+                                  params={"page": page, "per_page": per_page}))
+
+    async def get_space_bookmarks(self, space_id: int, *, page: int = 1, per_page: int = 10) -> SpaceBookmarkList:
+        return SpaceBookmarkList.model_validate(
+            await self._t.request("GET", f"{_P}/spaces/{space_id}/bookmarks",
+                                  params={"page": page, "per_page": per_page}))
+
+    async def get_space_notification_details(self, *, space_ids: Optional[str] = None) -> List[SpaceNotificationDetail]:
+        p: Dict[str, Any] = {}
+        if space_ids: p["space_ids"] = space_ids
+        return [SpaceNotificationDetail.model_validate(d) for d in
+                await self._t.request("GET", f"{_P}/space_notification_details", params=p)]
+
+    async def list_posts(self, space_id: int, **kw: Any) -> HeadlessPostList:
+        return HeadlessPostList.model_validate(
+            await self._t.request("GET", f"{_P}/spaces/{space_id}/posts", params=_list_posts_params(**kw)))
+
+    async def create_post(self, space_id: int, **kw: Any) -> HeadlessPost:
+        return HeadlessPost.model_validate(await self._t.request("POST", f"{_P}/spaces/{space_id}/posts", json=kw))
+
+    async def get_post(self, space_id: int, post_id: int) -> HeadlessPost:
+        return HeadlessPost.model_validate(await self._t.request("GET", f"{_P}/spaces/{space_id}/posts/{post_id}"))
+
+    async def delete_post(self, space_id: int, post_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/spaces/{space_id}/posts/{post_id}")
+
+    async def create_image_post(self, space_id: int, **kw: Any) -> HeadlessImagePost:
+        return HeadlessImagePost.model_validate(
+            await self._t.request("POST", f"{_P}/spaces/{space_id}/images/posts", json=kw))
+
+    async def update_image_post(self, space_id: int, post_id: int, **kw: Any) -> HeadlessImagePost:
+        return HeadlessImagePost.model_validate(
+            await self._t.request("PUT", f"{_P}/spaces/{space_id}/images/posts/{post_id}", json=kw))
+
+    async def follow_post(self, post_id: int) -> Dict[str, Any]:
+        return await self._t.request("POST", f"{_P}/posts/{post_id}/post_followers")
+
+    async def unfollow_post(self, post_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/posts/{post_id}/post_followers")
+
+    async def like_post(self, post_id: int) -> Dict[str, Any]:
+        return await self._t.request("POST", f"{_P}/posts/{post_id}/user_likes")
+
+    async def unlike_post(self, post_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/posts/{post_id}/user_likes")
+
+    async def get_post_likes(self, post_id: int, *, page: int = 1, per_page: int = 10) -> UserLikeList:
+        return UserLikeList.model_validate(
+            await self._t.request("GET", f"{_P}/posts/{post_id}/user_likes",
+                                  params={"page": page, "per_page": per_page}))
+
+    async def get_home_posts(self, **kw: Any) -> HeadlessPostList:
+        return HeadlessPostList.model_validate(await self._t.request("GET", f"{_P}/home", params=_home_params(**kw)))
+
+    async def list_comments(self, post_id: int, **kw: Any) -> HeadlessCommentList:
+        return HeadlessCommentList.model_validate(
+            await self._t.request("GET", f"{_P}/posts/{post_id}/comments", params=_comment_params(**kw)))
+
+    async def create_comment(self, post_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("POST", f"{_P}/posts/{post_id}/comments", json={"comment": kw}))
+
+    async def get_comment(self, post_id: int, comment_id: int) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("GET", f"{_P}/posts/{post_id}/comments/{comment_id}"))
+
+    async def update_comment(self, post_id: int, comment_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("PATCH", f"{_P}/posts/{post_id}/comments/{comment_id}", json={"comment": kw}))
+
+    async def delete_comment(self, post_id: int, comment_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/posts/{post_id}/comments/{comment_id}")
+
+    async def list_replies(self, comment_id: int, **kw: Any) -> HeadlessCommentList:
+        return HeadlessCommentList.model_validate(
+            await self._t.request("GET", f"{_P}/comments/{comment_id}/replies", params=_comment_params(**kw)))
+
+    async def create_reply(self, comment_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("POST", f"{_P}/comments/{comment_id}/replies", json={"comment": kw}))
+
+    async def get_reply(self, comment_id: int, reply_id: int) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("GET", f"{_P}/comments/{comment_id}/replies/{reply_id}"))
+
+    async def update_reply(self, comment_id: int, reply_id: int, **kw: Any) -> HeadlessComment:
+        return HeadlessComment.model_validate(
+            await self._t.request("PATCH", f"{_P}/comments/{comment_id}/replies/{reply_id}", json={"comment": kw}))
+
+    async def delete_reply(self, comment_id: int, reply_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/comments/{comment_id}/replies/{reply_id}")
+
+    async def like_comment(self, comment_id: int) -> Dict[str, Any]:
+        return await self._t.request("POST", f"{_P}/comments/{comment_id}/user_likes")
+
+    async def unlike_comment(self, comment_id: int) -> Dict[str, Any]:
+        return await self._t.request("DELETE", f"{_P}/comments/{comment_id}/user_likes")
+
+    async def get_comment_likes(self, comment_id: int, *, page: int = 1, per_page: int = 10) -> UserLikeList:
+        return UserLikeList.model_validate(
+            await self._t.request("GET", f"{_P}/comments/{comment_id}/user_likes",
+                                  params={"page": page, "per_page": per_page}))

circle/client.py

@@ -0,0 +1,197 @@
+"""Top-level CircleClient and AsyncCircleClient facade."""
+from __future__ import annotations
+import os
+from typing import Optional
+
+from circle.http import DEFAULT_BASE_URL, AsyncTransport, SyncTransport
+from circle.api.auth import AsyncHeadlessAuthClient, HeadlessAuthClient
+from circle.api.admin_access_groups import AccessGroupsClient, AsyncAccessGroupsClient
+from circle.api.admin_community import CommunityClient, AsyncCommunityClient
+from circle.api.admin_spaces import SpacesClient, AsyncSpacesClient
+from circle.api.admin_posts import PostsClient, AsyncPostsClient
+from circle.api.admin_events import EventsClient, AsyncEventsClient
+from circle.api.admin_courses import CoursesClient, AsyncCoursesClient
+from circle.api.admin_tags import TagsClient, AsyncTagsClient
+from circle.api.admin_misc import AdminMiscClient, AsyncAdminMiscClient
+from circle.api.headless_spaces_posts import HeadlessSpacesPostsClient, AsyncHeadlessSpacesPostsClient
+from circle.api.headless_chat_notif_members import HeadlessChatNotifMembersClient, AsyncHeadlessChatNotifMembersClient
+from circle.api.headless_misc import HeadlessMiscClient, AsyncHeadlessMiscClient
+
+
+class _AdminNamespace:
+    """Groups all Admin API V2 sub-clients under client.admin.*"""
+    def __init__(self, transport: SyncTransport) -> None:
+        self.access_groups = AccessGroupsClient(transport)
+        self.community = CommunityClient(transport)
+        self.spaces = SpacesClient(transport)
+        self.posts = PostsClient(transport)
+        self.events = EventsClient(transport)
+        self.courses = CoursesClient(transport)
+        self.tags = TagsClient(transport)
+        self.misc = AdminMiscClient(transport)
+
+    # Convenience delegates to community sub-client
+    def get_community(self, **kw):
+        return self.community.get_community(**kw)
+
+    def list_community_members(self, **kw):
+        return self.community.list_community_members(**kw)
+
+
+class _AsyncAdminNamespace:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self.access_groups = AsyncAccessGroupsClient(transport)
+        self.community = AsyncCommunityClient(transport)
+        self.spaces = AsyncSpacesClient(transport)
+        self.posts = AsyncPostsClient(transport)
+        self.events = AsyncEventsClient(transport)
+        self.courses = AsyncCoursesClient(transport)
+        self.tags = AsyncTagsClient(transport)
+        self.misc = AsyncAdminMiscClient(transport)
+
+    async def get_community(self, **kw):
+        return await self.community.get_community(**kw)
+
+    async def list_community_members(self, **kw):
+        return await self.community.list_community_members(**kw)
+
+
+class _HeadlessNamespace:
+    """Groups all Headless Client V1 sub-clients under client.headless.*"""
+    def __init__(self, transport: SyncTransport) -> None:
+        self.spaces_posts = HeadlessSpacesPostsClient(transport)
+        self.chat_notif_members = HeadlessChatNotifMembersClient(transport)
+        self.misc = HeadlessMiscClient(transport)
+
+    # Convenience delegates
+    def list_spaces(self, **kw):
+        return self.spaces_posts.list_spaces(**kw)
+
+    def list_posts(self, space_id, **kw):
+        return self.spaces_posts.list_posts(space_id, **kw)
+
+
+class _AsyncHeadlessNamespace:
+    def __init__(self, transport: AsyncTransport) -> None:
+        self.spaces_posts = AsyncHeadlessSpacesPostsClient(transport)
+        self.chat_notif_members = AsyncHeadlessChatNotifMembersClient(transport)
+        self.misc = AsyncHeadlessMiscClient(transport)
+
+    async def list_spaces(self, **kw):
+        return await self.spaces_posts.list_spaces(**kw)
+
+    async def list_posts(self, space_id, **kw):
+        return await self.spaces_posts.list_posts(space_id, **kw)
+
+
+class CircleClient:
+    """Synchronous Circle SDK client composing all three APIs.
+
+    Provides access to the Headless Auth, Admin V2, and Headless Client V1
+    APIs through the ``auth``, ``admin``, and ``headless`` namespaces.
+
+    Args:
+        api_token: Circle API token. Falls back to the ``CIRCLE_API_TOKEN``
+            environment variable if not provided.
+        base_url: Base URL for the Circle API. Falls back to the
+            ``CIRCLE_BASE_URL`` environment variable, then the default
+            ``https://app.circle.so``.
+        community_url: Optional community-specific URL. Falls back to the
+            ``CIRCLE_COMMUNITY_URL`` environment variable.
+        rate_limit: Optional requests-per-second limit. When set, the client
+            proactively throttles to avoid 429 responses.
+
+    Raises:
+        ValueError: If no api_token is provided and ``CIRCLE_API_TOKEN`` is
+            not set.
+
+    Examples:
+        >>> client = CircleClient(api_token="YOUR_TOKEN")
+        >>> community = client.admin.get_community()
+
+        >>> # Using environment variables (CIRCLE_API_TOKEN must be set)
+        >>> client = CircleClient()
+
+        >>> # With rate limiting
+        >>> client = CircleClient(api_token="YOUR_TOKEN", rate_limit=10)
+    """
+
+    def __init__(
+        self,
+        api_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        community_url: Optional[str] = None,
+        rate_limit: Optional[float] = None,
+    ) -> None:
+        token = api_token or os.environ.get("CIRCLE_API_TOKEN")
+        if not token:
+            raise ValueError(
+                "api_token is required. Pass it directly or set the CIRCLE_API_TOKEN environment variable."
+            )
+        resolved_base = base_url or os.environ.get("CIRCLE_BASE_URL", DEFAULT_BASE_URL)
+        resolved_community = community_url or os.environ.get("CIRCLE_COMMUNITY_URL")
+        url = (resolved_community or resolved_base).rstrip("/")
+        self._admin_transport = SyncTransport(api_token=token, base_url=url, auth_scheme="Token", rate_limit=rate_limit)
+        self._bearer_transport = SyncTransport(api_token=token, base_url=url, auth_scheme="Bearer", rate_limit=rate_limit)
+        self.auth = HeadlessAuthClient(self._bearer_transport)
+        self.admin = _AdminNamespace(self._admin_transport)
+        self.headless = _HeadlessNamespace(self._bearer_transport)
+
+    def close(self) -> None:
+        self._admin_transport.close()
+        self._bearer_transport.close()
+
+    def __enter__(self) -> CircleClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncCircleClient:
+    """Asynchronous Circle SDK client composing all three APIs.
+
+    Args:
+        api_token: Circle API token. Falls back to ``CIRCLE_API_TOKEN`` env var.
+        base_url: Base URL. Falls back to ``CIRCLE_BASE_URL`` env var.
+        community_url: Community URL. Falls back to ``CIRCLE_COMMUNITY_URL`` env var.
+        rate_limit: Optional requests-per-second limit.
+
+    Raises:
+        ValueError: If no api_token is provided and ``CIRCLE_API_TOKEN`` is not set.
+
+    Examples:
+        >>> async with AsyncCircleClient(api_token="YOUR_TOKEN") as client:
+        ...     members = await client.admin.list_community_members()
+    """
+
+    def __init__(
+        self,
+        api_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        community_url: Optional[str] = None,
+        rate_limit: Optional[float] = None,
+    ) -> None:
+        token = api_token or os.environ.get("CIRCLE_API_TOKEN")
+        if not token:
+            raise ValueError(
+                "api_token is required. Pass it directly or set the CIRCLE_API_TOKEN environment variable."
+            )
+        resolved_base = base_url or os.environ.get("CIRCLE_BASE_URL", DEFAULT_BASE_URL)
+        resolved_community = community_url or os.environ.get("CIRCLE_COMMUNITY_URL")
+        url = (resolved_community or resolved_base).rstrip("/")
+        self._admin_transport = AsyncTransport(api_token=token, base_url=url, auth_scheme="Token", rate_limit=rate_limit)
+        self._bearer_transport = AsyncTransport(api_token=token, base_url=url, auth_scheme="Bearer", rate_limit=rate_limit)
+        self.auth = AsyncHeadlessAuthClient(self._bearer_transport)
+        self.admin = _AsyncAdminNamespace(self._admin_transport)
+        self.headless = _AsyncHeadlessNamespace(self._bearer_transport)
+
+    async def close(self) -> None:
+        await self._admin_transport.close()
+        await self._bearer_transport.close()
+
+    async def __aenter__(self) -> AsyncCircleClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

circle/constants.py

@@ -0,0 +1,5 @@
+"""Centralized constants for Circle API endpoints."""
+
+ADMIN_V2_PREFIX = "/api/admin/v2"
+HEADLESS_V1_PREFIX = "/api/headless/v1"
+HEADLESS_AUTH_PREFIX = "/api/v1/headless"

circle/exceptions.py

@@ -0,0 +1,34 @@
+"""Typed exceptions for Circle API errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CircleAPIError(Exception):
+    """Base exception for all Circle API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, error_details: Any = None) -> None:
+        self.status_code = status_code
+        self.error_details = error_details
+        super().__init__(message)
+
+
+class AuthenticationError(CircleAPIError):
+    """401 Unauthorized."""
+
+
+class ForbiddenError(CircleAPIError):
+    """403 Forbidden."""
+
+
+class NotFoundError(CircleAPIError):
+    """404 Not Found."""
+
+
+class ValidationError(CircleAPIError):
+    """422 Unprocessable Entity."""
+
+
+class RateLimitError(CircleAPIError):
+    """429 Too Many Requests."""