gitcode-api 1.2.20__tar.gz → 1.3.0__tar.gz

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-api
-Version: 1.2.20
+Version: 1.3.0
 Summary: Easy to use Python SDK for the GitCode REST API. Providing builtin CLI tool, and optional LLM integration (MCP, OpenAI tool, and openJiuwen tool) for agents. Community-maintained.
 Author-email: Hugo Huang <hugo@hugohuang.com>
 License-Expression: MIT
@@ -37,9 +37,9 @@ Dynamic: license-file
 
 # GitCode-API
 
-[![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F&uuid=07b9a0e809feb403999bf97670a5d29f)](https://pypi.org/project/gitcode-api) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads&uuid=07b9a0e809feb403999bf97670a5d29f)](https://pepy.tech/projects/gitcode-api) [![CodeFactor](https://www.codefactor.io/repository/github/trenza1ore/gitcode-api/badge)](https://www.codefactor.io/repository/github/trenza1ore/gitcode-api)
+[![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F&uuid=96abf98469db4ee7bc12ded4646e76d9)](https://pypi.org/project/gitcode-api) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads&uuid=96abf98469db4ee7bc12ded4646e76d9)](https://pepy.tech/projects/gitcode-api)
 [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?logoColor=white)](https://cursor.com/en/install-mcp?name=GitCode%20API&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXRjb2RlLWFwaVttY3BdIiwiZ2l0Y29kZS1hcGkiLCJzZXJ2ZSJdLCJlbnYiOnsiR0lUQ09ERV9BQ0NFU1NfVE9LRU4iOiIke2lucHV0OmdpdGNvZGVfYWNjZXNzX3Rva2VufSJ9LCJpbnB1dHMiOlt7ImlkIjoiZ2l0Y29kZV9hY2Nlc3NfdG9rZW4iLCJ0eXBlIjoicHJvbXB0U3RyaW5nIiwiZGVzY3JpcHRpb24iOiJFbnRlciBHSVRDT0RFX0FDQ0VTU19UT0tFTiIsInBhc3N3b3JkIjp0cnVlfV19) [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=GitCode%20API&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22gitcode-api%5Bmcp%5D%22%2C%22gitcode-api%22%2C%22serve%22%5D%2C%22env%22%3A%7B%22GITCODE_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitcode_access_token%7D%22%7D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22gitcode_access_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20GITCODE_ACCESS_TOKEN%22%2C%22password%22%3Atrue%7D%5D%7D)
-[![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API)
+[![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API) [![CI Badge](https://github.com/Trenza1ore/GitCode-API/actions/workflows/check-code.yml/badge.svg?uuid=96abf98469db4ee7bc12ded4646e76d9)](https://github.com/Trenza1ore/GitCode-API/actions/workflows/check-code.yml/)
 
 [![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-Docs-cyan?style=for-the-badge&logo=readthedocs&link=https%3A%2F%2Fgitcode-api.readthedocs.io%2Fen%2Flatest%2Findex.html)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.md)
 

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/README.md

@@ -1,8 +1,8 @@
 # GitCode-API
 
-[![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F&uuid=07b9a0e809feb403999bf97670a5d29f)](https://pypi.org/project/gitcode-api) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads&uuid=07b9a0e809feb403999bf97670a5d29f)](https://pepy.tech/projects/gitcode-api) [![CodeFactor](https://www.codefactor.io/repository/github/trenza1ore/gitcode-api/badge)](https://www.codefactor.io/repository/github/trenza1ore/gitcode-api)
+[![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F&uuid=96abf98469db4ee7bc12ded4646e76d9)](https://pypi.org/project/gitcode-api) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads&uuid=96abf98469db4ee7bc12ded4646e76d9)](https://pepy.tech/projects/gitcode-api)
 [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?logoColor=white)](https://cursor.com/en/install-mcp?name=GitCode%20API&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXRjb2RlLWFwaVttY3BdIiwiZ2l0Y29kZS1hcGkiLCJzZXJ2ZSJdLCJlbnYiOnsiR0lUQ09ERV9BQ0NFU1NfVE9LRU4iOiIke2lucHV0OmdpdGNvZGVfYWNjZXNzX3Rva2VufSJ9LCJpbnB1dHMiOlt7ImlkIjoiZ2l0Y29kZV9hY2Nlc3NfdG9rZW4iLCJ0eXBlIjoicHJvbXB0U3RyaW5nIiwiZGVzY3JpcHRpb24iOiJFbnRlciBHSVRDT0RFX0FDQ0VTU19UT0tFTiIsInBhc3N3b3JkIjp0cnVlfV19) [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=GitCode%20API&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22gitcode-api%5Bmcp%5D%22%2C%22gitcode-api%22%2C%22serve%22%5D%2C%22env%22%3A%7B%22GITCODE_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitcode_access_token%7D%22%7D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22gitcode_access_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20GITCODE_ACCESS_TOKEN%22%2C%22password%22%3Atrue%7D%5D%7D)
-[![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API)
+[![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API) [![CI Badge](https://github.com/Trenza1ore/GitCode-API/actions/workflows/check-code.yml/badge.svg?uuid=96abf98469db4ee7bc12ded4646e76d9)](https://github.com/Trenza1ore/GitCode-API/actions/workflows/check-code.yml/)
 
 [![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-Docs-cyan?style=for-the-badge&logo=readthedocs&link=https%3A%2F%2Fgitcode-api.readthedocs.io%2Fen%2Flatest%2Findex.html)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.md)
 

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/gitcode_api/__init__.py

@@ -1,16 +1,18 @@
-"""Public package exports for the GitCode SDK."""
+"""GitCode API — Python clients for interactions with GitCode REST API."""
 
 import re
 from importlib.metadata import PackageNotFoundError, metadata, version
 from typing import cast
 
-from . import constants
+from . import constants, exceptions, models
 from ._client import AsyncGitCode, GitCode
 from ._exceptions import (
     GitCodeAPIError,
     GitCodeConfigurationError,
     GitCodeError,
     GitCodeHTTPStatusError,
+    GitCodeTokenError,
+    GitCodeUnauthorizedError,
 )
 from .utils import as_dict
 
@@ -43,6 +45,8 @@ __version__ = _VERSION_STR.strip()
 
 __all__ = [
     "constants",
+    "exceptions",
+    "models",
     "__version__",
     "__build_hash__",
     "AsyncGitCode",
@@ -51,5 +55,7 @@ __all__ = [
     "GitCodeConfigurationError",
     "GitCodeError",
     "GitCodeHTTPStatusError",
+    "GitCodeTokenError",
+    "GitCodeUnauthorizedError",
     "as_dict",
 ]

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/gitcode_api/_base_client.py

@@ -11,7 +11,7 @@ from urllib.parse import quote
 import httpx
 
 from ._base_resource import BaseResource
-from ._exceptions import GitCodeConfigurationError, GitCodeHTTPStatusError
+from ._exceptions import GitCodeConfigurationError, GitCodeHTTPStatusError, GitCodeTokenError, GitCodeUnauthorizedError
 from .constants import DEFAULT_BASE_URL, DEFAULT_CA_ENV, DEFAULT_TIMEOUT, DEFAULT_TOKEN_ENV
 
 
@@ -165,7 +165,12 @@ class BaseGitCodeClient:
         except ValueError:
             payload = response.text
 
-        raise GitCodeHTTPStatusError(
+        error_cls = GitCodeHTTPStatusError
+        if response.status_code == 401:
+            error_cls = GitCodeUnauthorizedError
+            if "token" in (str(payload) or message).lower():
+                error_cls = GitCodeTokenError
+        raise error_cls(
             message or f"GitCode API request failed with status {response.status_code}.",
             status_code=response.status_code,
             request_id=response.headers.get("X-Request-Id"),

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/gitcode_api/_exceptions.py

@@ -37,3 +37,11 @@ class GitCodeAPIError(GitCodeError):
 
 class GitCodeHTTPStatusError(GitCodeAPIError):
     """Raised for non-success HTTP responses from the GitCode API."""
+
+
+class GitCodeUnauthorizedError(GitCodeHTTPStatusError):
+    """Raised for 401 unauthorized HTTP responses from the GitCode API."""
+
+
+class GitCodeTokenError(GitCodeUnauthorizedError):
+    """Raised for invalid token from the GitCode API."""

gitcode_api-1.3.0/gitcode_api/exceptions.py

@@ -0,0 +1,19 @@
+"""Exception classes for the GitCode SDK."""
+
+from gitcode_api._exceptions import (
+    GitCodeAPIError,
+    GitCodeConfigurationError,
+    GitCodeError,
+    GitCodeHTTPStatusError,
+    GitCodeTokenError,
+    GitCodeUnauthorizedError,
+)
+
+__all__ = [
+    "GitCodeAPIError",
+    "GitCodeConfigurationError",
+    "GitCodeError",
+    "GitCodeHTTPStatusError",
+    "GitCodeTokenError",
+    "GitCodeUnauthorizedError",
+]

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/gitcode_api/llm/mcp.py

@@ -1,6 +1,6 @@
 """FastMCP integration for the GitCode LLM tool."""
 
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Optional, Union, cast
 
 from ._tool import (
     MCP_SERVER_INSTRUCTIONS,
@@ -25,8 +25,8 @@ def _missing_fastmcp_error() -> ImportError:
 
 def _load_fastmcp() -> tuple["type[FastMCP]", Callable[..., "Tool"]]:
     try:
-        from fastmcp import FastMCP
-        from fastmcp.tools import tool as fastmcp_tool
+        from fastmcp import FastMCP  # pylint: disable=import-outside-toplevel
+        from fastmcp.tools import tool as fastmcp_tool  # pylint: disable=import-outside-toplevel
     except ImportError as exc:
         raise _missing_fastmcp_error() from exc
     return FastMCP, fastmcp_tool  # type: ignore[return-value]
@@ -61,9 +61,9 @@ def register_mcp_gitcode_api_tool(mcp: Union["FastMCP", Any], tool: Optional[Git
     callable_tool = create_mcp_gitcode_api_tool(tool)
     if hasattr(mcp, "tool"):
         try:
-            return mcp.tool(name=TOOL_NAME, description=TOOL_DESCRIPTION)(callable_tool)
+            return cast("Tool", mcp.tool(name=TOOL_NAME, description=TOOL_DESCRIPTION)(callable_tool))
         except TypeError:
-            return mcp.tool()(callable_tool)
+            return cast("Tool", mcp.tool()(callable_tool))
     if hasattr(mcp, "add_tool"):
         _, fastmcp_tool = _load_fastmcp()
         mcp_tool = fastmcp_tool(callable_tool, name=TOOL_NAME, description=TOOL_DESCRIPTION)

gitcode_api-1.3.0/gitcode_api/models.py

@@ -0,0 +1,205 @@
+"""Response models for the GitCode SDK."""
+
+from gitcode_api._models import (
+    APIObject,
+    ApiStatusResponse,
+    Blob,
+    Branch,
+    BranchDetail,
+    BranchDetailCommit,
+    BranchListCommit,
+    Commit,
+    CommitAuthorSummary,
+    CommitComment,
+    CommitComparison,
+    CommitFile,
+    CommitIdentity,
+    CommitParent,
+    CommitPayload,
+    CommitResult,
+    CommitStats,
+    CommitSummary,
+    CommitTreeRef,
+    ContentLinks,
+    ContentObject,
+    ContentWriteCommit,
+    Contributor,
+    ContributorStatistics,
+    ContributorStatisticsEntry,
+    ContributorStatisticsOverview,
+    Email,
+    EmptyResponse,
+    EnterpriseMember,
+    EnterpriseRef,
+    Issue,
+    IssueComment,
+    IssueOperationLog,
+    Label,
+    MergeResult,
+    MergeStatus,
+    Milestone,
+    Namespace,
+    NamespaceDetails,
+    OAuthToken,
+    Organization,
+    OrganizationMembership,
+    OrganizationSummary,
+    ProtectedBranch,
+    ProtectedTag,
+    PublicKey,
+    PullRequest,
+    PullRequestApprover,
+    PullRequestAssigneeCount,
+    PullRequestBranch,
+    PullRequestComment,
+    PullRequestCount,
+    PullRequestDiffRefs,
+    PullRequestFile,
+    PullRequestOperationLog,
+    PullRequestReview,
+    PullRequestSettingDetail,
+    PullRequestSettings,
+    PullRequestTest,
+    PullRequestTimeStats,
+    Release,
+    ReleaseAsset,
+    ReleaseUploadURL,
+    RepoCollaborator,
+    RepoMember,
+    RepoMemberPermission,
+    RepoMemberPermissions,
+    Repository,
+    RepositoryCollaboratorCheck,
+    RepositoryCustomizedRole,
+    RepositoryDownloadStatistics,
+    RepositoryDownloadStatisticsDetail,
+    RepositoryGitCodeTemplate,
+    RepositoryPermission,
+    RepositoryPermissionMode,
+    RepositoryPushConfig,
+    RepositoryReviewerSettingsUpdate,
+    RepositorySettings,
+    RepositorySummary,
+    RepositoryTransferResult,
+    RepositoryUploadResult,
+    SearchIssue,
+    SearchRepository,
+    SearchResult,
+    SearchUser,
+    Tag,
+    TagCommit,
+    Tagger,
+    Tree,
+    TreeEntry,
+    User,
+    UserEvent,
+    UserEventLinks,
+    UserEventProject,
+    UserEventPushData,
+    UserEventsResponse,
+    UserRef,
+    UserSummary,
+    Webhook,
+)
+
+__all__ = [
+    "APIObject",
+    "ApiStatusResponse",
+    "Blob",
+    "Branch",
+    "BranchDetail",
+    "BranchDetailCommit",
+    "BranchListCommit",
+    "Commit",
+    "CommitAuthorSummary",
+    "CommitComment",
+    "CommitComparison",
+    "CommitFile",
+    "CommitIdentity",
+    "CommitParent",
+    "CommitPayload",
+    "CommitResult",
+    "CommitStats",
+    "CommitSummary",
+    "CommitTreeRef",
+    "ContentLinks",
+    "ContentObject",
+    "ContentWriteCommit",
+    "Contributor",
+    "ContributorStatistics",
+    "ContributorStatisticsEntry",
+    "ContributorStatisticsOverview",
+    "Email",
+    "EmptyResponse",
+    "EnterpriseMember",
+    "EnterpriseRef",
+    "Issue",
+    "IssueComment",
+    "IssueOperationLog",
+    "Label",
+    "MergeResult",
+    "MergeStatus",
+    "Milestone",
+    "Namespace",
+    "NamespaceDetails",
+    "OAuthToken",
+    "Organization",
+    "OrganizationMembership",
+    "OrganizationSummary",
+    "ProtectedBranch",
+    "ProtectedTag",
+    "PublicKey",
+    "PullRequest",
+    "PullRequestApprover",
+    "PullRequestAssigneeCount",
+    "PullRequestBranch",
+    "PullRequestComment",
+    "PullRequestCount",
+    "PullRequestDiffRefs",
+    "PullRequestFile",
+    "PullRequestOperationLog",
+    "PullRequestReview",
+    "PullRequestSettingDetail",
+    "PullRequestSettings",
+    "PullRequestTest",
+    "PullRequestTimeStats",
+    "Release",
+    "ReleaseAsset",
+    "ReleaseUploadURL",
+    "RepoCollaborator",
+    "RepoMember",
+    "RepoMemberPermission",
+    "RepoMemberPermissions",
+    "Repository",
+    "RepositoryCollaboratorCheck",
+    "RepositoryCustomizedRole",
+    "RepositoryDownloadStatistics",
+    "RepositoryDownloadStatisticsDetail",
+    "RepositoryGitCodeTemplate",
+    "RepositoryPermission",
+    "RepositoryPermissionMode",
+    "RepositoryPushConfig",
+    "RepositoryReviewerSettingsUpdate",
+    "RepositorySettings",
+    "RepositorySummary",
+    "RepositoryTransferResult",
+    "RepositoryUploadResult",
+    "SearchIssue",
+    "SearchRepository",
+    "SearchResult",
+    "SearchUser",
+    "Tag",
+    "TagCommit",
+    "Tagger",
+    "Tree",
+    "TreeEntry",
+    "User",
+    "UserEvent",
+    "UserEventLinks",
+    "UserEventProject",
+    "UserEventPushData",
+    "UserEventsResponse",
+    "UserRef",
+    "UserSummary",
+    "Webhook",
+]

{gitcode_api-1.2.20 → gitcode_api-1.3.0}/gitcode_api/resources/__init__.py

@@ -1,4 +1,4 @@
-"""Public resource group exports for the GitCode SDK."""
+"""Sync and async resource group classes for all API endpoint families."""
 
 from .account import (
     AsyncOAuthResource,

gitcode_api-1.3.0/gitcode_api/resources/_shared/__init__.py

@@ -0,0 +1,18 @@
+"""Shared resource base classes and template helpers."""
+
+from .base import AsyncResource, SyncResource
+from .fetch_template import (
+    get_gitcode_template_body_async,
+    get_gitcode_template_body_sync,
+    list_gitcode_template_rows_async,
+    list_gitcode_template_rows_sync,
+)
+
+__all__ = [
+    "AsyncResource",
+    "SyncResource",
+    "get_gitcode_template_body_sync",
+    "get_gitcode_template_body_async",
+    "list_gitcode_template_rows_sync",
+    "list_gitcode_template_rows_async",
+]

gitcode_api-1.3.0/gitcode_api/resources/_shared/base.py

@@ -0,0 +1,129 @@
+"""Synchronous and asynchronous resource base classes."""
+
+from typing import Any, Dict, List, Optional, Union
+
+from ..._base_client import AsyncAPIClient, SyncAPIClient
+from ..._base_resource import BaseResource
+from ..._models import APIObject, ModelT, as_model, as_model_list
+
+
+class SyncResource(BaseResource):
+    """Base class for synchronous resource groups."""
+
+    def __init__(self, client: SyncAPIClient) -> None:
+        """Bind the resource to a synchronous API client."""
+        self._client = client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+    ) -> Any:
+        """Dispatch a low-level request through the owning client.
+
+        :param method: HTTP verb (for example ``GET`` or ``POST``).
+        :param path: Absolute or root-relative URL path.
+        :param params: Optional query string parameters.
+        :param json: Optional JSON-serializable request body.
+        :param data: Optional form or body fields.
+        :param raw: When ``True``, return the raw response body (for example bytes).
+        :returns: Parsed JSON, raw body, or other value from the client.
+        """
+        return self._client.request(method, path, params=params, json=json, data=data, raw=raw)
+
+    def _model(self, method: str, path: str, model_type: type[ModelT], **kwargs) -> ModelT:
+        """Send a request and wrap a JSON object in ``model_type``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for the top-level JSON object.
+        :param kwargs: Forwarded to :meth:`_request` (``params``, ``json``, ``data``, ``raw``, etc.).
+        :returns: An instance of ``model_type``.
+        """
+        data = self._request(method, path, **kwargs)
+        return as_model(data, model_type)
+
+    def _models(self, method: str, path: str, model_type: type[ModelT], **kwargs) -> List[ModelT]:
+        """Send a request and wrap a JSON array in ``model_type`` instances.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for each element of the JSON array.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: A list of ``model_type`` instances.
+        """
+        data = self._request(method, path, **kwargs)
+        return as_model_list(data, model_type)
+
+    def _maybe_model(self, method: str, path: str, model_type: type[ModelT], **kwargs) -> Union[ModelT, APIObject]:
+        """Wrap dict responses as models and scalar responses as ``APIObject``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class when the response is a JSON object.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: ``model_type`` for dict bodies; otherwise ``APIObject`` wrapping a ``value`` field.
+        """
+        data = self._request(method, path, **kwargs)
+        if isinstance(data, dict):
+            return as_model(data, model_type)
+        return APIObject({"value": data})
+
+
+class AsyncResource(BaseResource):
+    """Base class for asynchronous resource groups."""
+
+    def __init__(self, client: AsyncAPIClient) -> None:
+        """Bind the resource to an asynchronous API client."""
+        self._client = client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+    ) -> Any:
+        """Dispatch a low-level async request through the owning client.
+
+        :param method: HTTP verb (for example ``GET`` or ``POST``).
+        :param path: Absolute or root-relative URL path.
+        :param params: Optional query string parameters.
+        :param json: Optional JSON-serializable request body.
+        :param data: Optional form or body fields.
+        :param raw: When ``True``, return the raw response body (for example bytes).
+        :returns: Parsed JSON, raw body, or other value from the client.
+        """
+        return await self._client.request(method, path, params=params, json=json, data=data, raw=raw)
+
+    async def _model(self, method: str, path: str, model_type: type[ModelT], **kwargs) -> ModelT:
+        """Send a request and wrap a JSON object in ``model_type``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for the top-level JSON object.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: An instance of ``model_type``.
+        """
+        data = await self._request(method, path, **kwargs)
+        return as_model(data, model_type)
+
+    async def _models(self, method: str, path: str, model_type: type[ModelT], **kwargs) -> List[ModelT]:
+        """Send a request and wrap a JSON array in ``model_type`` instances.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for each element of the JSON array.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: A list of ``model_type`` instances.
+        """
+        data = await self._request(method, path, **kwargs)
+        return as_model_list(data, model_type)