Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

feat(py): expose the owned client surface on composio-client 2.0.0rc7

jkomyno43ebe6c24ef1
diff --git a/python/composio/__init__.py b/python/composio/__init__.py
index 32b369257..beb674a80 100644
--- a/python/composio/__init__.py
+++ b/python/composio/__init__.py
@@ -22,6 +22,7 @@ from .core.models.webhook_events import (
WebhookEventType,
is_connection_expired_event,
)
+from .exceptions import ComposioDeprecationWarning
from .core.types import (
ToolkitLatestVersion,
ToolkitVersion,
@@ -32,6 +33,7 @@ from .sdk import Composio
__all__ = (
"Composio",
+ "ComposioDeprecationWarning",
"CustomTool",
"ExperimentalToolkit",
"RemoteFile",
diff --git a/python/composio/client/__init__.py b/python/composio/client/__init__.py
index 65db19e3e..f72bdb514 100644
--- a/python/composio/client/__init__.py
+++ b/python/composio/client/__init__.py
@@ -3,6 +3,7 @@ This module is a light wrapper around the auto-generated composio client.
"""
import contextvars
+import logging
import os
import platform
import typing as t
@@ -15,16 +16,74 @@ from composio_client import (
NOT_GIVEN,
APIError,
NotGiven,
- _base_client,
)
from composio_client import Composio as BaseComposio
from httpx import URL, Client, Request, Timeout
-from composio.utils.logging import WithLogger
+from composio.utils.logging import LogLevel, WithLogger, _VerbosityWrapper
ComposioAPIError = APIError
APIEnvironment = te.Literal["production", "staging", "local"]
+CLIENT_LOGGER_NAME = "composio_client"
+"""Name of the logger the generated ``composio_client`` package writes to."""
+
+
+class _ClientLogForwarder(logging.Handler):
+ """Forward ``composio_client`` records into the SDK logger.
+
+ The generated client logs request/response lifecycle through
+ ``logging.getLogger("composio_client")``. Routing those records through
+ the SDK's :class:`_VerbosityWrapper` keeps one destination for SDK users
+ and applies the same credential redaction and line truncation the SDK's
+ own records get. The client's INFO records (per-request lifecycle) are
+ forwarded as DEBUG.
+ """
+
+ def __init__(self, wrapper: _VerbosityWrapper) -> None:
+ super().__init__()
+ self.wrapper = wrapper
+
+ def emit(self, record: logging.LogRecord) -> None:
+ try:
+ message = record.getMessage()
+ if record.levelno >= logging.ERROR:
+ self.wrapper.error(message, exc_info=record.exc_info)
+ elif record.levelno >= logging.WARNING:
+ self.wrapper.warning(message, exc_info=record.exc_info)
+ else:
+ self.wrapper.debug(message, exc_info=record.exc_info)
+ except Exception: # noqa: BLE001 - logging must never fail the call
+ self.handleError(record)
+
+
+def _install_client_log_forwarder(wrapper: _VerbosityWrapper) -> logging.Logger:
+ """Attach a single forwarder for ``wrapper`` to the client logger.
+
+ Idempotent: a forwarder already bound to ``wrapper`` is kept; forwarders
+ bound to another wrapper (an earlier SDK instance with a different logger)
+ are replaced so records are delivered once, to the most recent logger.
+ """
+ client_logger = logging.getLogger(CLIENT_LOGGER_NAME)
+ installed = False
+ for handler in list(client_logger.handlers):
+ if not isinstance(handler, _ClientLogForwarder):
+ continue
+ if handler.wrapper is wrapper and not installed:
+ installed = True
+ continue
+ client_logger.removeHandler(handler)
+ if not installed:
+ client_logger.addHandler(_ClientLogForwarder(wrapper))
+ # The client's INFO records are forwarded as DEBUG, so only let the client
+ # produce them when the SDK logger is at DEBUG.
+ level = wrapper.logger.getEffectiveLevel()
+ client_logger.setLevel(
+ level if level <= logging.DEBUG else max(level, logging.WARNING)
+ )
+ client_logger.propagate = False
+ return client_logger
+
def _get_python_implementation() -> str:
"""
@@ -144,12 +203,16 @@ class HttpClient(BaseComposio, WithLogger):
default_headers: t.Optional[t.Mapping[str, str]] = None,
default_query: t.Optional[t.Mapping[str, object]] = None,
http_client: t.Optional[Client] = None,
+ logger: t.Optional[logging.Logger] = None,
+ logging_level: t.Optional[LogLevel] = None,
_strict_response_validation: bool = False,
) -> None:
"""
Initialize the client.
:param provider: The provider to use for the client.
+ :param logger: Logger that receives SDK and ``composio_client`` records.
+ :param logging_level: Level applied to the SDK and ``composio_client`` loggers.
:param api_key: The API key to use for the client.
:param environment: The environment to use for the client.
:param base_url: The base URL to use for the client.
@@ -159,7 +222,7 @@ class HttpClient(BaseComposio, WithLogger):
:param default_query: The default query parameters to use for the client.
:param http_client: The HTTP client to use for the client.
"""
- WithLogger.__init__(self)
+ WithLogger.__init__(self, logger=logger, logging_level=logging_level)
BaseComposio.__init__(
self,
api_key=api_key,
@@ -172,8 +235,7 @@ class HttpClient(BaseComposio, WithLogger):
http_client=http_client,
_strict_response_validation=_strict_response_validation,
)
- # TOFIX: Verbosity wrapper impl
- _base_client.log = self._logger # type: ignore
+ _install_client_log_forwarder(self._logger)
self.provider = provider
self.request_ctx = contextvars.ContextVar[RequestContext](
"request_ctx",
diff --git a/python/composio/client/types.py b/python/composio/client/types.py
index cb25d07af..85474627b 100644
--- a/python/composio/client/types.py
+++ b/python/composio/client/types.py
@@ -13,14 +13,26 @@ from composio_client.types import (
auth_config_retrieve_response,
auth_config_update_params,
connected_account_create_params,
+ connected_account_complete_auth_response,
connected_account_create_response,
connected_account_list_params,
connected_account_list_response,
connected_account_patch_params,
connected_account_patch_response,
+ connected_account_refresh_params,
+ connected_account_refresh_response,
connected_account_retrieve_response,
+ connected_account_revoke_response,
connected_account_update_status_response,
+ custom_delete_toolkit_response,
+ custom_sync_response,
+ custom_upsert_params,
+ custom_upsert_response,
+ keyring_list_transfer_keys_response,
link_create_params,
+ log_create_tool_execution_params,
+ log_create_tool_execution_response,
+ log_retrieve_tool_execution_response,
tool_execute_params,
tool_execute_response,
tool_list_response,
@@ -28,8 +40,44 @@ from composio_client.types import (
tool_proxy_response,
toolkit_list_params,
toolkit_list_response,
+ toolkit_recommend_scopes_params,
+ toolkit_recommend_scopes_response,
+ toolkit_retrieve_changelog_response,
+ toolkit_retrieve_multi_params,
+ toolkit_retrieve_multi_response,
toolkit_retrieve_response,
+ toolkit_retrieve_scopes_grant_context_params,
+ toolkit_retrieve_scopes_grant_context_response,
trigger_instance_upsert_response,
+ webhook_endpoint_create_params,
+ webhook_endpoint_create_response,
+ webhook_endpoint_list_params,
+ webhook_endpoint_list_response,
+ webhook_endpoint_replace_params,
+ webhook_endpoint_replace_response,
+ webhook_endpoint_retrieve_response,
+ webhook_endpoint_update_params,
+ webhook_endpoint_update_response,
+ webhook_subscription_create_params,
+ webhook_subscription_create_response,
+ webhook_subscription_delete_response,
+ webhook_subscription_list_event_types_response,
+ webhook_subscription_list_params,
+ webhook_subscription_list_response,
+ webhook_subscription_retrieve_response,
+ webhook_subscription_rotate_secret_response,
+ webhook_subscription_update_params,
+ webhook_subscription_update_response,
+)
+from composio_client.types.project import (
+ usage_retrieve_params,
+ usage_retrieve_response,
+ usage_retrieve_summary_params,
+ usage_retrieve_summary_response,
+)
+from composio_client.types.tool_router import (
+ session_config_history_params,
+ session_config_history_response,
)
Tool: t.TypeAlias = tool_list_response.Item
@@ -71,15 +119,29 @@ __all__ = (
"auth_config_list_response",
"auth_config_retrieve_response",
"auth_config_update_params",
+ "connected_account_complete_auth_response",
"connected_account_create_params",
"connected_account_create_response",
"connected_account_list_params",
"connected_account_list_response",
"connected_account_patch_params",
"connected_account_patch_response",
+ "connected_account_refresh_params",
+ "connected_account_refresh_response",
"connected_account_retrieve_response",
+ "connected_account_revoke_response",
"connected_account_update_status_response",
+ "custom_delete_toolkit_response",
+ "custom_sync_response",
+ "custom_upsert_params",
+ "custom_upsert_response",
+ "keyring_list_transfer_keys_response",
"link_create_params",
+ "log_create_tool_execution_params",
+ "log_create_tool_execution_response",
+ "log_retrieve_tool_execution_response",
+ "session_config_history_params",
+ "session_config_history_response",
"trigger_instance_upsert_response",
"tool_execute_params",
"tool_execute_response",
@@ -88,7 +150,37 @@ __all__ = (
"tool_proxy_response",
"toolkit_list_params",
"toolkit_list_response",
+ "toolkit_recommend_scopes_params",
+ "toolkit_recommend_scopes_response",
+ "toolkit_retrieve_changelog_response",
+ "toolkit_retrieve_multi_params",
+ "toolkit_retrieve_multi_response",
"toolkit_retrieve_response",
+ "toolkit_retrieve_scopes_grant_context_params",
+ "toolkit_retrieve_scopes_grant_context_response",
+ "usage_retrieve_params",
+ "usage_retrieve_response",
+ "usage_retrieve_summary_params",
+ "usage_retrieve_summary_response",
+ "webhook_endpoint_create_params",
+ "webhook_endpoint_create_response",
+ "webhook_endpoint_list_params",
+ "webhook_endpoint_list_response",
+ "webhook_endpoint_replace_params",
+ "webhook_endpoint_replace_response",
+ "webhook_endpoint_retrieve_response",
+ "webhook_endpoint_update_params",
+ "webhook_endpoint_update_response",
+ "webhook_subscription_create_params",
+ "webhook_subscription_create_response",
+ "webhook_subscription_delete_response",
+ "webhook_subscription_list_event_types_response",
+ "webhook_subscription_list_params",
+ "webhook_subscription_list_response",
+ "webhook_subscription_retrieve_response",
+ "webhook_subscription_rotate_secret_response",
+ "webhook_subscription_update_params",
+ "webhook_subscription_update_response",
"Tool",
"ToolkitMinimal",
"AuthConfig",
diff --git a/python/composio/core/models/__init__.py b/python/composio/core/models/__init__.py
index 645f52d0d..6adcacc0a 100644
--- a/python/composio/core/models/__init__.py
+++ b/python/composio/core/models/__init__.py
@@ -9,7 +9,13 @@ from .custom_tool_types import (
SessionContext,
ToolRouterSessionProxyExecuteResponse,
)
-from .experimental import ExperimentalAPI
+from .experimental import (
+ ExperimentalAPI,
+ ExperimentalCustomToolkits,
+ ExperimentalUsage,
+)
+from .keyring import Keyring
+from .logs import Logs
from .mcp import MCP
from .tool_router import ToolRouter
from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
@@ -29,6 +35,13 @@ from .webhook_events import (
WebhookEventType,
is_connection_expired_event,
)
+from .webhooks import (
+ WebhookEndpoints,
+ Webhooks,
+ WebhookSubscription,
+ WebhookSubscriptions,
+ WebhookVersion,
+)
__all__ = [
"AuthConfigs",
@@ -38,7 +51,11 @@ __all__ = [
"ConnectionStatusEnum",
"CustomTool",
"ExperimentalAPI",
+ "ExperimentalCustomToolkits",
"ExperimentalToolkit",
+ "ExperimentalUsage",
+ "Keyring",
+ "Logs",
"MCP",
"ProxyExecuteBinaryData",
"RegisteredCustomTool",
@@ -56,7 +73,12 @@ __all__ = [
"Tools",
"Triggers",
"WebhookConnectionMetadata",
+ "WebhookEndpoints",
"WebhookEvent",
"WebhookEventType",
+ "WebhookSubscription",
+ "WebhookSubscriptions",
+ "WebhookVersion",
+ "Webhooks",
"is_connection_expired_event",
]
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index b6e59b85a..6756152db 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -7,15 +7,19 @@ import typing as t
import warnings
import typing_extensions as te
-from composio_client import BadRequestError, omit
+from composio_client import BadRequestError, ConflictError, omit
from composio import exceptions
from composio.client import HttpClient
from composio.client.types import (
+ connected_account_complete_auth_response,
connected_account_create_params,
connected_account_patch_params,
connected_account_patch_response,
+ connected_account_refresh_params,
+ connected_account_refresh_response,
connected_account_retrieve_response,
+ connected_account_revoke_response,
connected_account_update_status_response,
link_create_params,
)
@@ -35,6 +39,17 @@ _TERMINAL_CONNECTION_STATES: t.FrozenSet[str] = frozenset(
# warning on every initiate() call.
_legacy_initiate_warning_emitted = False
+_REFRESH_DEPRECATION = (
+ "connected_accounts.refresh() is deprecated: the API marks "
+ "POST /connected_accounts/{id}/refresh as deprecated. Re-initiate "
+ "auth with connected_accounts.link() or toolkits.authorize() instead."
+)
+
+_REFRESH_VALIDATE_CREDENTIALS_IGNORED = (
+ "connected_accounts.refresh(): the API no longer accepts "
+ "validate_credentials; the argument is ignored."
+)
+
class ConnectionRequest(Resource):
"""
@@ -368,7 +383,6 @@ class ConnectedAccounts:
self.list = self._client.connected_accounts.list
self.delete = self._client.connected_accounts.delete
self.update_status = self._client.connected_accounts.update_status
- self.refresh = self._client.connected_accounts.refresh
self.enable = functools.partial(
self._client.connected_accounts.update_status,
enabled=True,
@@ -378,6 +392,103 @@ class ConnectedAccounts:
enabled=False,
)
+ @te.deprecated(_REFRESH_DEPRECATION, category=None)
+ def refresh(
+ self,
+ nanoid: str,
+ **params: te.Unpack[
+ connected_account_refresh_params.ConnectedAccountRefreshParams
+ ],
+ ) -> connected_account_refresh_response.ConnectedAccountRefreshResponse:
+ """
+ Refresh the credentials of a connected account.
+
+ .. deprecated::
+ The API marks ``POST /connected_accounts/{id}/refresh`` as
+ deprecated. Re-initiate authentication with
+ :meth:`link` or ``composio.toolkits.authorize()`` instead.
+
+ :param nanoid: The connected account ID (``ca_xxx``).
+ :return: The refresh response.
+
+ Example:
+ composio.connected_accounts.refresh("ca_abc123")
+ """
+ warnings.warn(
+ _REFRESH_DEPRECATION, exceptions.ComposioDeprecationWarning, stacklevel=2
+ )
+ # The API no longer accepts validate_credentials; forward every other
+ # kwarg (timeout, extra_headers, ...) unchanged.
+ forwarded: t.Dict[str, t.Any] = dict(params)
+ if forwarded.pop("validate_credentials", None) is not None:
+ warnings.warn(
+ _REFRESH_VALIDATE_CREDENTIALS_IGNORED,
+ exceptions.ComposioDeprecationWarning,
+ stacklevel=2,
+ )
+ return self._client.connected_accounts.refresh(nanoid, **forwarded)
+
+ def revoke(
+ self, nanoid: str
+ ) -> connected_account_revoke_response.ConnectedAccountRevokeResponse:
+ """
+ Revoke a connected account's upstream tokens (best effort) and mark
+ the connection ``REVOKED``.
+
+ Raises :class:`composio.exceptions.ComposioConnectedAccountRevocationNotSupportedError`
+ when the toolkit does not support programmatic revocation (API 400)
+ and :class:`composio.exceptions.ComposioConnectedAccountNotRevokableError`
+ when the connection is not in a revokable state (API 409).
+
+ :param nanoid: The connected account ID (``ca_xxx``).
+ :return: The revoked tokens and the updated connected account.
+
+ Example:
+ result = composio.connected_accounts.revoke("ca_abc123")
+ print(result.connected_account.status) # "REVOKED"
+ """
+ try:
+ return self._client.connected_accounts.revoke(nanoid)
+ except BadRequestError as error:
+ raise exceptions.ComposioConnectedAccountRevocationNotSupportedError(
+ f"Connected account {nanoid!r} cannot be revoked programmatically: "
+ f"the toolkit does not support token revocation ({error})"
+ ) from error
+ except ConflictError as error:
+ raise exceptions.ComposioConnectedAccountNotRevokableError(
+ f"Connected account {nanoid!r} is not in a revokable state ({error})"
+ ) from error
+
+ def complete_auth(
+ self, *, user_id: str, session_uri: str
+ ) -> connected_account_complete_auth_response.ConnectedAccountCompleteAuthResponse:
+ """
+ Complete a deferred OAuth connection once you have verified the
+ user's identity.
+
+ When your project has an OAuth callback verifier configured, Composio
+ does not activate a new OAuth connection by itself: it redirects to
+ your verifier with a single-use session URI. After confirming who the
+ user is, redeem it here; Composio checks that your project owns the
+ pending connection and that ``user_id`` is its owner, completes the
+ token exchange, and the connection becomes ``ACTIVE``. Redeeming a
+ session twice, or after it expires, fails with a 404 from the API.
+
+ :param user_id: The user the connection was initiated for.
+ :param session_uri: The session URI from the verifier redirect.
+ :return: The completed ``connected_account_id`` and its ``toolkit_slug``.
+
+ Example:
+ result = composio.connected_accounts.complete_auth(
+ user_id="user_123",
+ session_uri=session_uri, # from the verifier redirect
+ )
+ print(result.connected_account_id)
+ """
+ return self._client.connected_accounts.complete_auth(
+ user_id=user_id, session_uri=session_uri
+ )
+
def update(
self,
nanoid: str,
@@ -609,7 +720,7 @@ class ConnectedAccounts:
"composio.connected_accounts.link() — same return shape, "
"same allow_multiple semantics. "
"https://docs.composio.dev/docs/changelog/2026/04/24",
- DeprecationWarning,
+ exceptions.ComposioDeprecationWarning,
stacklevel=2,
)
diff --git a/python/composio/core/models/experimental.py b/python/composio/core/models/experimental.py
index 7e66ab2ab..7daf555d6 100644
--- a/python/composio/core/models/experimental.py
+++ b/python/composio/core/models/experimental.py
@@ -18,10 +18,22 @@ from __future__ import annotations
import typing as t
+import typing_extensions as te
from pydantic import BaseModel
from composio.client import HttpClient
-from composio.client.types import connected_account_patch_response
+from composio.utils.pydantic import none_to_omit
+from composio.client.types import (
+ connected_account_patch_response,
+ custom_delete_toolkit_response,
+ custom_sync_response,
+ custom_upsert_params,
+ custom_upsert_response,
+ usage_retrieve_params,
+ usage_retrieve_response,
+ usage_retrieve_summary_params,
+ usage_retrieve_summary_response,
+)
from .custom_tool import (
CustomTool,
@@ -37,6 +49,176 @@ from .custom_tool import (
ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT = "acl_config_for_shared is only valid on SHARED"
+class ExperimentalUsage:
+ """Project usage metering, accessed via ``composio.experimental.usage``.
+
+ Experimental — the response shape may change in future releases. Scoped
+ to the project the API key belongs to.
+ """
+
+ def __init__(self, client: t.Optional[HttpClient] = None) -> None:
+ self._client = client
+
+ def _require_client(self) -> HttpClient:
+ from composio import exceptions
+
+ if self._client is None:
+ raise exceptions.ValidationError(
+ "experimental.usage requires a Composio client. Access it via "
+ "composio.experimental.usage.summary(...)."
+ )
+ return self._client
+
+ def summary(
+ self,
+ **params: te.Unpack[usage_retrieve_summary_params.UsageRetrieveSummaryParams],
+ ) -> usage_retrieve_summary_response.UsageRetrieveSummaryResponse:
+ """
+ Fetch a usage summary for the project. Experimental — shape may change.
+
+ :param from_: Start of the window (Unix epoch milliseconds).
+ :param to: End of the window (Unix epoch milliseconds).
+ :param entity_types: Restrict the summary to these entity types.
+ :param filters: Additional server-side filters.
+ :return: Usage totals keyed by entity type under ``.entities``.
+
+ Example:
+ summary = composio.experimental.usage.summary(
+ entity_types=["tool_calls"],
+ )
+ """
+ return self._require_client().project.usage.retrieve_summary(**params)
+
+ def breakdown(
+ self,
+ entity_type: str,
+ **params: te.Unpack[usage_retrieve_params.UsageRetrieveParams],
+ ) -> usage_retrieve_response.UsageRetrieveResponse:
+ """
+ Fetch a grouped usage breakdown for one entity type. Experimental —
+ shape may change.
+
+ :param entity_type: The metered entity type, e.g. ``tool_calls`` or ``sessions``.
+ :param from_: Start of the window (Unix epoch milliseconds).
+ :param to: End of the window (Unix epoch milliseconds).
+ :param group_by: Field to group the breakdown by (API default: ``tool_slug``
+ for ``tool_calls``, ``user_id`` for ``sessions``).
+ :param order_by: Sort key (``key``, ``total_quantity`` or ``event_count``).
+ :param order_direction: ``asc`` or ``desc``.
+ :param limit: Maximum number of groups to return.
+ :param filters: Additional server-side filters.
+ :return: The usage totals and per-group breakdown.
+
+ Example:
+ breakdown = composio.experimental.usage.breakdown(
+ "tool_calls",
+ group_by="tool_slug",
+ )
+ """
+ return self._require_client().project.usage.retrieve(entity_type, **params)
+
+
+class ExperimentalCustomToolkits:
+ """Project-owned custom toolkits, accessed via
+ ``composio.experimental.custom_toolkits``.
+
+ Experimental — custom toolkits are in pilot and the shape may change.
+ These toolkits are registered in your Composio project from your own app
+ or MCP server, with their own auth configs and connected accounts. They
+ are unrelated to the in-process toolkits built with
+ ``composio.experimental.Toolkit``.
+ """
+
+ def __init__(self, client: t.Optional[HttpClient] = None) -> None:
+ self._client = client
+
+ def _require_client(self) -> HttpClient:
+ from composio import exceptions
+
+ if self._client is None:
+ raise exceptions.ValidationError(
+ "experimental.custom_toolkits requires a Composio client. Access "
+ "it via composio.experimental.custom_toolkits.upsert(...)."
+ )
+ return self._client
+
+ def upsert(
+ self,
+ **params: te.Unpack[custom_upsert_params.CustomUpsertParams],
+ ) -> custom_upsert_response.CustomUpsertResponse:
+ """
+ Create a custom toolkit, or update its display metadata (name, API key
+ field copy) when the project already owns one with this slug.
+ Experimental — shape may change.
+
+ ``app_url`` and ``auth_schemes`` cannot change on an existing
+ toolkit: re-sending them unchanged is a no-op, and changing them fails
+ with a 409. Delete and re-register the toolkit instead, which revokes
+ its connections.
+
+ :param slug: Letters, digits, underscores or spaces (max 30). The API
+ prefixes it with ``CUSTOM_`` and turns spaces into underscores.
+ :param toolkit_config: ``name``, ``app_url`` (the MCP URL for MCP
+ apps), ``auth_schemes`` and an optional base64 ``logo_file``.
+ :return: The toolkit's ``slug``.
+
+ Example:
+ composio.experimental.custom_toolkits.upsert(
+ slug="INTERNAL_API",
+ toolkit_config={
+ "name": "Internal API",
+ "app_url": "https://mcp.internal.example.com/mcp",
+ "auth_schemes": [
+ {
+ "mode": "API_KEY",
+ "headers": {"Authorization": "Bearer {{generic_api_key}}"},
+ }
+ ],
+ },
+ )
+ """
+ return self._require_client().custom.upsert(**params)
+
+ def sync(
+ self, slug: str, *, connected_account_id: t.Optional[str] = None
+ ) -> custom_sync_response.CustomSyncResponse:
+ """
+ Re-fetch a custom toolkit's tool definitions from its remote MCP
+ server. Call it when automatic sync fails or the remote tools change.
+ Experimental — shape may change.
+
+ :param slug: The custom toolkit slug (``CUSTOM_...``).
+ :param connected_account_id: Connected account to use when fetching
+ the remote tool definitions.
+ :return: The toolkit ``version`` and ``synced_count``.
+
+ Example:
+ result = composio.experimental.custom_toolkits.sync("CUSTOM_MY_TOOLKIT")
+ print(result.synced_count)
+ """
+ return self._require_client().custom.sync(
+ slug=slug, connected_account_id=none_to_omit(connected_account_id)
+ )
+
+ def delete(
+ self, slug: str
+ ) -> custom_delete_toolkit_response.CustomDeleteToolkitResponse:
+ """
+ Delete a custom toolkit owned by the project, with its tools, auth
+ configs and connected accounts. The credentials behind those
+ connected accounts are revoked in background jobs
+ (``revoke_job_ids``). Composio-managed toolkits cannot be deleted
+ (API 403). Experimental — shape may change.
+
+ :param slug: The custom toolkit slug (``CUSTOM_...``).
+ :return: What was deleted.
+
+ Example:
+ composio.experimental.custom_toolkits.delete("CUSTOM_MY_TOOLKIT")
+ """
+ return self._require_client().custom.delete_toolkit(slug)
+
+
class ExperimentalAPI:
"""Experimental APIs accessed via ``composio.experimental``.
@@ -47,8 +229,16 @@ class ExperimentalAPI:
Toolkit = ExperimentalToolkit
+ usage: ExperimentalUsage
+ """Project usage metering. Experimental — shape may change."""
+
+ custom_toolkits: ExperimentalCustomToolkits
+ """Project-owned custom toolkits. Experimental — shape may change."""
+
def __init__(self, client: t.Optional[HttpClient] = None) -> None:
self._client = client
+ self.usage = ExperimentalUsage(client=client)
+ self.custom_toolkits = ExperimentalCustomToolkits(client=client)
def update_acl(
self,
diff --git a/python/composio/core/models/keyring.py b/python/composio/core/models/keyring.py
new file mode 100644
index 000000000..66c6a9b8b
--- /dev/null
+++ b/python/composio/core/models/keyring.py
@@ -0,0 +1,39 @@
+"""
+Keyring module for the Composio SDK.
+
+Exposes ``composio.keyring`` for the organization's customer-managed keyring.
+"""
+
+from __future__ import annotations
+
+from composio.client.types import keyring_list_transfer_keys_response
+from composio.core.models.base import Resource
+
+
+class Keyring(Resource):
+ """The organization's customer-managed keyring."""
+
+ def list_transfer_keys(
+ self,
+ ) -> keyring_list_transfer_keys_response.KeyringListTransferKeysResponse:
+ """
+ List the public transfer keys of the organization's active customer
+ keyring, the keys a secret is sealed to before it is sent to Composio.
+
+ Seal new secrets to the key whose ``kid`` is ``active_kid``: a JWE
+ with ``RSA-OAEP-256`` key management, ``A256GCM`` content
+ encryption, and the ``kid`` in the protected header. Older keys stay
+ listed so values sealed to them remain openable. The API answers 404
+ when the organization has no ACTIVE keyring instance.
+
+ :return: ``active_kid`` and every accepted public JWK under ``keys``,
+ newest first.
+
+ Example:
+ transfer_keys = composio.keyring.list_transfer_keys()
+ jwk = next(
+ key for key in transfer_keys.keys
+ if key.kid == transfer_keys.active_kid
+ )
+ """
+ return self._client.keyring.list_transfer_keys()
diff --git a/python/composio/core/models/logs.py b/python/composio/core/models/logs.py
new file mode 100644
index 000000000..29c6436a8
--- /dev/null
+++ b/python/composio/core/models/logs.py
@@ -0,0 +1,63 @@
+"""
+Logs module for the Composio SDK.
+
+Exposes ``composio.logs`` for searching and retrieving tool execution logs.
+"""
+
+from __future__ import annotations
+
+import typing_extensions as te
+
+from composio.client.types import (
+ log_create_tool_execution_params,
+ log_create_tool_execution_response,
+ log_retrieve_tool_execution_response,
+)
+from composio.core.models.base import Resource
+
+
+class Logs(Resource):
+ """Search and retrieve tool execution logs."""
+
+ def search(
+ self,
+ **params: te.Unpack[
+ log_create_tool_execution_params.LogCreateToolExecutionParams
+ ],
+ ) -> log_create_tool_execution_response.LogCreateToolExecutionResponse:
+ """
+ Search tool execution logs with filters, pagination, and a time range.
+
+ Despite the underlying ``POST`` verb this is a read-only search.
+
+ :param limit: Maximum number of logs to return.
+ :param cursor: Pagination cursor from a previous response.
+ :param filters: Filter clauses to narrow the search.
+ :param time_range: Time window to search within.
+ :return: Matching logs plus a ``next_cursor`` for pagination.
+
+ Example:
+ page = composio.logs.search(
+ limit=20,
+ filters=[
+ {"field": "toolkit_slug", "operator": "==", "value": "github"}
+ ],
+ )
+ for log in page.logs:
+ print(log.id)
+ """
+ return self._client.logs.create_tool_execution(**params)
+
+ def get(
+ self, id: str
+ ) -> log_retrieve_tool_execution_response.LogRetrieveToolExecutionResponse:
+ """
+ Retrieve a single tool execution log by id.
+
+ :param id: The log id.
+ :return: The full log entry.
+
+ Example:
+ log = composio.logs.get("log_123")
+ """
+ return self._client.logs.retrieve_tool_execution(id)
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index 832094ff6..e269b27d6 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -12,6 +12,7 @@ import typing as t
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass
+import typing_extensions as te
from composio_client import BadRequestError, Omit, omit
from composio_client._types import SequenceNotStr
from composio_client.types.tool_list_response import (
@@ -29,7 +30,11 @@ from composio_client.types.tool_router.session_search_response import (
from composio import exceptions
from composio.client import HttpClient
-from composio.client.types import Tool
+from composio.client.types import (
+ Tool,
+ session_config_history_params,
+ session_config_history_response,
+)
from composio.core.models._modifiers import Modifiers, apply_modifier_by_type
from composio.core.models.connected_accounts import ConnectionRequest
from composio.core.models.custom_tool import (
@@ -948,6 +953,30 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
)
self.preload = _session_preload_config(response.config.preload)
+ def config_history(
+ self,
+ **query: te.Unpack[session_config_history_params.SessionConfigHistoryParams],
+ ) -> session_config_history_response.SessionConfigHistoryResponse:
+ """
+ List the configuration history of this session, newest first.
+
+ Every ``update()`` records a new config version; this returns those
+ versions with cursor-based pagination.
+
+ :param cursor: Pagination cursor from a previous response.
+ :param limit: Number of items per page (max 100).
+ :return: The config versions under ``.items`` plus pagination fields.
+
+ Example:
+ history = session.config_history(limit=10)
+ for entry in history.items:
+ print(entry.version, entry.is_current)
+ """
+ return self._client.tool_router.session.config_history(
+ session_id=self.session_id,
+ **query,
+ )
+
def delete(self) -> ToolRouterSessionDeleteResponse:
"""
Delete this session.
diff --git a/python/composio/core/models/toolkits.py b/python/composio/core/models/toolkits.py
index 43a20f38b..8ae1e0982 100644
--- a/python/composio/core/models/toolkits.py
+++ b/python/composio/core/models/toolkits.py
@@ -2,13 +2,20 @@ from __future__ import annotations
import typing as t
+import typing_extensions as te
+
from composio import exceptions
from composio.client import HttpClient
from composio.client.types import (
AuthSchemeL,
toolkit_list_params,
toolkit_list_response,
+ toolkit_recommend_scopes_params,
+ toolkit_recommend_scopes_response,
+ toolkit_retrieve_changelog_response,
toolkit_retrieve_response,
+ toolkit_retrieve_scopes_grant_context_params,
+ toolkit_retrieve_scopes_grant_context_response,
)
from composio.core.models.connected_accounts import ConnectedAccounts
from composio.utils.pydantic import none_to_omit
@@ -84,6 +91,115 @@ class Toolkits(Resource):
return self._client.toolkits.retrieve(slug=slug)
return self._client.toolkits.list(**(query or {})).items
+ def get_many(
+ self,
+ slugs: t.Sequence[str],
+ *,
+ category: t.Optional[str] = None,
+ managed_by: t.Optional[t.Literal["composio", "all", "project"]] = None,
+ sort_by: t.Optional[t.Literal["usage", "alphabetically"]] = None,
+ limit: t.Optional[float] = None,
+ cursor: t.Optional[str] = None,
+ ) -> t.List[t.Any]:
+ """
+ Fetch several toolkits by slug in one request.
+
+ :param slugs: The toolkit slugs to fetch.
+ :param category: Only return toolkits in this category.
+ :param managed_by: Filter by who manages the toolkit.
+ :param sort_by: Sort order of the returned toolkits.
+ :param limit: Maximum number of toolkits to return.
+ :param cursor: Pagination cursor from a previous response.
+ :return: The matching toolkits.
+
+ Example:
+ toolkits = composio.toolkits.get_many(["github", "slack"])
+ for toolkit in toolkits:
+ print(toolkit.slug, toolkit.name)
+ """
+ return self._client.toolkits.retrieve_multi(
+ toolkits=list(slugs),
+ category=none_to_omit(category),
+ managed_by=none_to_omit(managed_by),
+ sort_by=none_to_omit(sort_by),
+ limit=none_to_omit(limit),
+ cursor=none_to_omit(cursor),
+ ).items
+
+ def changelog(
+ self,
+ ) -> toolkit_retrieve_changelog_response.ToolkitRetrieveChangelogResponse:
+ """
+ Retrieve the toolkit changelog (the last 10 versions per toolkit).
+
+ :return: The changelog entries under ``.items``.
+
+ Example:
+ changelog = composio.toolkits.changelog()
+ for entry in changelog.items:
+ print(entry.slug, [v.version for v in entry.versions])
+ """
+ return self._client.toolkits.retrieve_changelog()
+
+ def recommend_scopes(
+ self,
+ toolkit_slug: str,
+ **params: te.Unpack[
+ toolkit_recommend_scopes_params.ToolkitRecommendScopesParams
+ ],
+ ) -> toolkit_recommend_scopes_response.ToolkitRecommendScopesResponse:
+ """
+ Recommend the OAuth scopes to request so a connection can run the
+ given tools. Experimental — the API marks this endpoint beta.
+
+ :param toolkit_slug: The toolkit to recommend scopes for.
+ :param tools: Tool slugs to cover; ``[]`` covers every tool in the toolkit.
+ :param auth_scheme: Auth scheme the connection will use (API default ``OAUTH2``).
+ :param toolkit_version: Toolkit version to compute from (API default: latest).
+ :param grant_context: Dimension to selected value, e.g.
+ ``{"account_type": "Google Workspace"}``. See :meth:`list_grant_contexts`.
+ :param include: Scopes the recommendation must include.
+ :param exclude: Scopes the recommendation must not include.
+ :param available_scopes: Scopes your OAuth app can request; the
+ recommendation never goes outside this list.
+ :return: The ``least_privilege`` and ``fewest`` scope sets plus the
+ ``conditional`` scopes, under ``.scopes``.
+
+ Example:
+ recommendation = composio.toolkits.recommend_scopes(
+ "gmail",
+ tools=["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],
+ )
+ print(recommendation.scopes.least_privilege)
+ """
+ return self._client.toolkits.recommend_scopes(toolkit_slug, **params)
+
+ def list_grant_contexts(
+ self,
+ toolkit_slug: str,
+ **params: te.Unpack[
+ toolkit_retrieve_scopes_grant_context_params.ToolkitRetrieveScopesGrantContextParams
+ ],
+ ) -> toolkit_retrieve_scopes_grant_context_response.ToolkitRetrieveScopesGrantContextResponse:
+ """
+ List the grant-context dimensions a toolkit's scope recommendation
+ depends on, with their allowed values and the default the API
+ assumes. Experimental — the API marks this endpoint beta.
+
+ :param toolkit_slug: The toolkit to list grant contexts for.
+ :param auth_scheme: Auth scheme the connection will use (API default ``OAUTH2``).
+ :param toolkit_version: Toolkit version to read from (API default: latest).
+ :return: ``grant_context_dimensions`` and ``default_grant_context``.
+
+ Example:
+ contexts = composio.toolkits.list_grant_contexts("gmail")
+ for dimension in contexts.grant_context_dimensions:
+ print(dimension.dimension, dimension.values)
+ """
+ return self._client.toolkits.retrieve_scopes_grant_context(
+ toolkit_slug, **params
+ )
+
def list_categories(self):
"""List all categories of toolkits."""
return self._client.toolkits.retrieve_categories().items
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index 90a62c5a0..37290f7e6 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -238,7 +238,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
tools_list.extend(
self._client.tools.list(
toolkit_slug=none_to_omit(",".join(toolkits) if toolkits else None),
- search=none_to_omit(search),
+ query=none_to_omit(search),
scopes=scopes,
limit=limit,
toolkit_versions=none_to_omit(self._toolkit_versions),
diff --git a/python/composio/core/models/triggers.py b/python/composio/core/models/triggers.py
index b2b0f3adf..9606b4720 100644
--- a/python/composio/core/models/triggers.py
+++ b/python/composio/core/models/triggers.py
@@ -13,7 +13,6 @@ import traceback
import typing as t
import uuid
from concurrent.futures import ThreadPoolExecutor
-from enum import Enum
import requests
import typing_extensions as te
@@ -28,6 +27,12 @@ from composio.client import HttpClient
from composio.client.types import trigger_instance_upsert_response
from composio.core.models.base import Resource
from composio.core.models.internal import Internal
+from composio.core.models.webhooks import (
+ DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS,
+ WebhookSubscription,
+ WebhookSubscriptions,
+ WebhookVersion,
+)
from composio.core.types import ToolkitVersionParam
from composio.exceptions import ComposioSDKTimeoutError
from composio.utils.logging import WithLogger
@@ -102,14 +107,6 @@ class _TriggerData(te.TypedDict):
originalPayload: t.Dict
-class WebhookVersion(str, Enum):
- """Webhook payload version."""
-
- V1 = "V1"
- V2 = "V2"
- V3 = "V3"
-
-
class WebhookPayloadV1(te.TypedDict):
"""V1 webhook payload structure."""
@@ -206,20 +203,14 @@ class VerifyWebhookResult(t.TypedDict):
raw_payload: WebhookPayload # The original parsed payload
-class WebhookSubscription(t.TypedDict, total=False):
- """Webhook subscription returned by the Composio API."""
-
- id: str
- webhook_url: str
- version: str
- enabled_events: t.List[str]
- secret: str
- created_at: str
- updated_at: str
-
-
-DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS = ("composio.trigger.message",)
-WEBHOOK_SUBSCRIPTIONS_PATH = "/api/v3.1/webhook_subscriptions"
+# Re-exported for backwards compatibility; the definitions live in
+# :mod:`composio.core.models.webhooks`.
+__all__ = [
+ "DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS",
+ "Triggers",
+ "WebhookSubscription",
+ "WebhookVersion",
+]
_ = {
@@ -1106,110 +1097,12 @@ class Triggers(Resource):
webhook_url=f"{APP_URL}/webhooks/composio",
)
"""
- if not webhook_url:
- raise exceptions.ValidationError("please provide a valid `webhook_url`")
-
- events = list(
- DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS
- if enabled_events is None
- else enabled_events
- )
- if len(events) == 0:
- raise exceptions.ValidationError(
- "please provide at least one enabled event"
- )
-
- version_value = (
- version.value if isinstance(version, WebhookVersion) else version
- )
- body = {
- "webhook_url": webhook_url,
- "enabled_events": events,
- "version": version_value,
- }
-
- existing = self._client.get(
- WEBHOOK_SUBSCRIPTIONS_PATH,
- cast_to=object,
- options={"params": {"limit": 1}},
- )
- subscription_id = self._first_webhook_subscription_id(existing)
-
- if subscription_id:
- return self._normalize_webhook_subscription(
- self._client.patch(
- f"{WEBHOOK_SUBSCRIPTIONS_PATH}/{subscription_id}",
- cast_to=object,
- body=body,
- )
- )
-
- return self._normalize_webhook_subscription(
- self._client.post(
- WEBHOOK_SUBSCRIPTIONS_PATH,
- cast_to=object,
- body=body,
- ),
+ return WebhookSubscriptions(client=self._client).set(
+ webhook_url=webhook_url,
+ enabled_events=enabled_events,
+ version=version,
)
- @staticmethod
- def _normalize_webhook_subscription(raw: object) -> WebhookSubscription:
- """Build a typed :class:`WebhookSubscription` from the raw API response.
-
- Maps explicitly (accepting either snake_case or camelCase wire keys)
- instead of ``cast``-ing the raw object, so the returned dict always
- matches the declared shape and a shift in the wire format surfaces as a
- normalized field rather than a ``KeyError`` at the call site.
- """
- data = raw if isinstance(raw, dict) else {}
-
- def _first_str(*keys: str) -> t.Optional[str]:
- for key in keys:
- value = data.get(key)
- if isinstance(value, str) and value:
- return value
- return None
-
- def _str_list(*keys: str) -> t.List[str]:
- for key in keys:
- value = data.get(key)
- if isinstance(value, list):
- return [item for item in value if isinstance(item, str)]
- return []
-
- result: WebhookSubscription = {
- "id": _first_str("id") or "",
- "webhook_url": _first_str("webhook_url", "webhookUrl") or "",
- "version": _first_str("version") or WebhookVersion.V3.value,
- "enabled_events": _str_list("enabled_events", "enabledEvents"),
- }
- secret = _first_str("secret")
- if secret is not None:
- result["secret"] = secret
- created_at = _first_str("created_at", "createdAt")
- if created_at is not None:
- result["created_at"] = created_at
- updated_at = _first_str("updated_at", "updatedAt")
- if updated_at is not None:
- result["updated_at"] = updated_at
- return result
-
- @staticmethod
- def _first_webhook_subscription_id(response: object) -> t.Optional[str]:
- if not isinstance(response, dict):
- return None
-
- items = response.get("items")
- if not isinstance(items, list) or len(items) == 0:
- return None
-
- first = items[0]
- if not isinstance(first, dict):
- return None
-
- subscription_id = first.get("id")
- return subscription_id if isinstance(subscription_id, str) else None
-
def get_type(self, slug: str) -> TriggersTypeRetrieveResponse:
"""
Get a trigger type by its slug
diff --git a/python/composio/core/models/webhooks.py b/python/composio/core/models/webhooks.py
new file mode 100644
index 000000000..30800a001
--- /dev/null
+++ b/python/composio/core/models/webhooks.py
@@ -0,0 +1,438 @@
+"""
+Webhooks module for the Composio SDK.
+
+Exposes ``composio.webhooks.subscriptions`` (the project-level webhook
+subscription used for event delivery) and ``composio.webhooks.endpoints``
+(per toolkit + OAuth app inbound ingress URLs).
+"""
+
+from __future__ import annotations
+
+import typing as t
+from enum import Enum
+
+import pydantic
+
+from composio import exceptions
+from composio.client import HttpClient
+from composio.client.types import (
+ webhook_endpoint_create_response,
+ webhook_endpoint_list_response,
+ webhook_endpoint_replace_response,
+ webhook_endpoint_retrieve_response,
+ webhook_endpoint_update_response,
+ webhook_subscription_delete_response,
+ webhook_subscription_list_event_types_response,
+ webhook_subscription_list_response,
+ webhook_subscription_retrieve_response,
+ webhook_subscription_rotate_secret_response,
+ webhook_subscription_update_response,
+)
+from composio.core.models.base import Resource
+from composio.utils.pydantic import none_to_omit
+
+
+class WebhookVersion(str, Enum):
+ """Webhook payload version."""
+
+ V1 = "V1"
+ V2 = "V2"
+ V3 = "V3"
+
+
+WebhookVersionL = t.Literal["V1", "V2", "V3"]
+
+_WEBHOOK_VERSIONS: t.Dict[str, WebhookVersionL] = {"V1": "V1", "V2": "V2", "V3": "V3"}
+
+
+def _webhook_version(version: t.Union[WebhookVersion, str]) -> WebhookVersionL:
+ """Narrow a caller-supplied version to the literal the client accepts."""
+ value = version.value if isinstance(version, WebhookVersion) else version
+ literal = _WEBHOOK_VERSIONS.get(value)
+ if literal is None:
+ raise exceptions.ValidationError(
+ f"unsupported webhook version {value!r}; expected one of V1, V2, V3"
+ )
+ return literal
+
+
+class WebhookSubscription(t.TypedDict, total=False):
+ """Webhook subscription returned by the Composio API."""
+
+ id: str
+ webhook_url: str
+ version: str
+ enabled_events: t.List[str]
+ secret: str
+ created_at: str
+ updated_at: str
+
+
+DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS = ("composio.trigger.message",)
+
+
+def normalize_webhook_subscription(raw: object) -> WebhookSubscription:
+ """Build a typed :class:`WebhookSubscription` from an API response.
+
+ Accepts either the client's pydantic response models or a plain dict.
+ Maps explicitly (accepting either snake_case or camelCase wire keys)
+ instead of ``cast``-ing the raw object, so the returned dict always
+ matches the declared shape and a shift in the wire format surfaces as a
+ normalized field rather than a ``KeyError`` at the call site.
+ """
+ if isinstance(raw, pydantic.BaseModel):
+ # The client builds response models without validation, so enum
+ # fields hold plain strings; silence pydantic's serializer warnings.
+ data: t.Dict[str, t.Any] = raw.model_dump(mode="json", warnings=False)
+ elif isinstance(raw, dict):
+ data = raw
+ else:
+ data = {}
+
+ def _first_str(*keys: str) -> t.Optional[str]:
+ for key in keys:
+ value = data.get(key)
+ if isinstance(value, str) and value:
+ return value
+ return None
+
+ def _str_list(*keys: str) -> t.List[str]:
+ for key in keys:
+ value = data.get(key)
+ if isinstance(value, list):
+ return [item for item in value if isinstance(item, str)]
+ return []
+
+ result: WebhookSubscription = {
+ "id": _first_str("id") or "",
+ "webhook_url": _first_str("webhook_url", "webhookUrl") or "",
+ "version": _first_str("version") or WebhookVersion.V3.value,
+ "enabled_events": _str_list("enabled_events", "enabledEvents"),
+ }
+ secret = _first_str("secret")
+ if secret is not None:
+ result["secret"] = secret
+ created_at = _first_str("created_at", "createdAt")
+ if created_at is not None:
+ result["created_at"] = created_at
+ updated_at = _first_str("updated_at", "updatedAt")
+ if updated_at is not None:
+ result["updated_at"] = updated_at
+ return result
+
+
+def first_webhook_subscription_id(response: object) -> t.Optional[str]:
+ """Return the id of the first subscription in a list response.
+
+ Accepts the client's typed list response (``.items`` of models with an
+ ``.id``) as well as a plain dict of the same shape.
+ """
+ items = (
+ response.get("items")
+ if isinstance(response, dict)
+ else getattr(response, "items", None)
+ )
+ if not isinstance(items, list) or len(items) == 0:
+ return None
+
+ first = items[0]
+ subscription_id = (
+ first.get("id") if isinstance(first, dict) else getattr(first, "id", None)
+ )
+ return subscription_id if isinstance(subscription_id, str) else None
+
+
+class WebhookSubscriptions(Resource):
+ """Manage the project webhook subscription.
+
+ The API allows one subscription per project; the signing secret is
+ returned in responses.
+ """
+
+ def list(
+ self,
+ *,
+ limit: t.Optional[float] = None,
+ cursor: t.Optional[str] = None,
+ ) -> webhook_subscription_list_response.WebhookSubscriptionListResponse:
+ """
+ List webhook subscriptions for the project.
+
+ :param limit: Maximum number of subscriptions to return.
+ :param cursor: Pagination cursor from a previous response.
+ :return: Paginated list of subscriptions.
+
+ Example:
+ subscriptions = composio.webhooks.subscriptions.list()
+ """
+ return self._client.webhook_subscriptions.list(
+ limit=none_to_omit(limit),
+ cursor=none_to_omit(cursor),
+ )
+
+ def get(
+ self, id: str
+ ) -> webhook_subscription_retrieve_response.WebhookSubscriptionRetrieveResponse:
+ """
+ Retrieve a webhook subscription by id.
+
+ :param id: The subscription id.
+ :return: The subscription, including its signing secret.
+
+ Example:
+ subscription = composio.webhooks.subscriptions.get("sub_123")
+ """
+ return self._client.webhook_subscriptions.retrieve(id)
+
+ def set(
+ self,
+ *,
+ webhook_url: str,
+ enabled_events: t.Optional[t.Sequence[str]] = None,
+ version: t.Union[WebhookVersion, str] = WebhookVersion.V3,
+ ) -> WebhookSubscription:
+ """
+ Create or update the project webhook subscription used for webhook delivery.
+
+ If a subscription already exists, the first subscription is updated. Otherwise a
+ new subscription is created. By default this subscribes to V3 trigger message
+ events.
+
+ :param webhook_url: The URL Composio delivers events to.
+ :param enabled_events: Event types to subscribe to. Defaults to
+ ``composio.trigger.message``.
+ :param version: Webhook payload version. Defaults to ``V3``.
+ :return: The normalized subscription.
+
+ Example:
+ composio.webhooks.subscriptions.set(
+ webhook_url=f"{APP_URL}/webhooks/composio",
+ )
+ """
+ if not webhook_url:
+ raise exceptions.ValidationError("please provide a valid `webhook_url`")
+
+ events = list(
+ DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS
+ if enabled_events is None
+ else enabled_events
+ )
+ if len(events) == 0:
+ raise exceptions.ValidationError(
+ "please provide at least one enabled event"
+ )
+
+ version_value = _webhook_version(version)
+
+ existing = self._client.webhook_subscriptions.list(limit=1)
+ subscription_id = first_webhook_subscription_id(existing)
+
+ if subscription_id:
+ return normalize_webhook_subscription(
+ self._client.webhook_subscriptions.update(
+ subscription_id,
+ webhook_url=webhook_url,
+ enabled_events=events,
+ version=version_value,
+ )
+ )
+
+ return normalize_webhook_subscription(
+ self._client.webhook_subscriptions.create(
+ webhook_url=webhook_url,
+ enabled_events=events,
+ version=version_value,
+ )
+ )
+
+ def update(
+ self,
+ id: str,
+ *,
+ webhook_url: t.Optional[str] = None,
+ enabled_events: t.Optional[t.Sequence[str]] = None,
+ version: t.Union[WebhookVersion, str, None] = None,
+ ) -> webhook_subscription_update_response.WebhookSubscriptionUpdateResponse:
+ """
+ Update an existing webhook subscription. Omitted fields are preserved.
+
+ :param id: The subscription id.
+ :param webhook_url: New delivery URL.
+ :param enabled_events: New list of subscribed event types.
+ :param version: New webhook payload version.
+ :return: The updated subscription.
+
+ Example:
+ composio.webhooks.subscriptions.update(
+ "sub_123",
+ enabled_events=["composio.trigger.message"],
+ )
+ """
+ version_value = None if version is None else _webhook_version(version)
+ return self._client.webhook_subscriptions.update(
+ id,
+ webhook_url=none_to_omit(webhook_url),
+ enabled_events=none_to_omit(
+ list(enabled_events) if enabled_events is not None else None
+ ),
+ version=none_to_omit(version_value),
+ )
+
+ def delete(
+ self, id: str
+ ) -> webhook_subscription_delete_response.WebhookSubscriptionDeleteResponse:
+ """
+ Delete a webhook subscription.
+
+ :param id: The subscription id.
+ :return: The deletion response.
+
+ Example:
+ composio.webhooks.subscriptions.delete("sub_123")
+ """
+ return self._client.webhook_subscriptions.delete(id)
+
+ def rotate_secret(
+ self, id: str
+ ) -> webhook_subscription_rotate_secret_response.WebhookSubscriptionRotateSecretResponse:
+ """
+ Rotate the signing secret of a webhook subscription.
+
+ :param id: The subscription id.
+ :return: The subscription with its new signing secret.
+
+ Example:
+ rotated = composio.webhooks.subscriptions.rotate_secret("sub_123")
+ new_secret = rotated.secret
+ """
+ return self._client.webhook_subscriptions.rotate_secret(id)
+
+ def list_event_types(
+ self,
+ ) -> webhook_subscription_list_event_types_response.WebhookSubscriptionListEventTypesResponse:
+ """
+ List the event types a subscription can be enabled for.
+
+ :return: The available event types.
+
+ Example:
+ event_types = composio.webhooks.subscriptions.list_event_types()
+ """
+ return self._client.webhook_subscriptions.list_event_types()
+
+
+class WebhookEndpoints(Resource):
+ """Manage inbound webhook endpoints (per toolkit + OAuth app ingress URLs)."""
+
+ def list(
+ self,
+ *,
+ toolkit_slug: t.Optional[str] = None,
+ ) -> webhook_endpoint_list_response.WebhookEndpointListResponse:
+ """
+ List webhook endpoints, optionally filtered by toolkit.
+
+ :param toolkit_slug: Only return endpoints for this toolkit.
+ :return: The list of endpoints.
+
+ Example:
+ endpoints = composio.webhooks.endpoints.list(toolkit_slug="github")
+ """
+ return self._client.webhook_endpoints.list(
+ toolkit_slug=none_to_omit(toolkit_slug),
+ )
+
+ def get(
+ self, nano_id: str
+ ) -> webhook_endpoint_retrieve_response.WebhookEndpointRetrieveResponse:
+ """
+ Retrieve a webhook endpoint by id.
+
+ :param nano_id: The endpoint id.
+ :return: The endpoint.
+
+ Example:
+ endpoint = composio.webhooks.endpoints.get("we_123")
+ """
+ return self._client.webhook_endpoints.retrieve(nano_id)
+
+ def create(
+ self,
+ *,
+ toolkit_slug: str,
+ client_id: str,
+ ) -> webhook_endpoint_create_response.WebhookEndpointCreateResponse:
+ """
+ Create a webhook endpoint for a toolkit and OAuth app.
+
+ :param toolkit_slug: The toolkit the endpoint receives events for.
+ :param client_id: The OAuth app client id the endpoint is bound to.
+ :return: The created endpoint, including its ingress ``webhook_url``.
+
+ Example:
+ endpoint = composio.webhooks.endpoints.create(
+ toolkit_slug="github",
+ client_id="Iv1.abc123",
+ )
+ """
+ return self._client.webhook_endpoints.create(
+ toolkit_slug=toolkit_slug,
+ client_id=client_id,
+ )
+
+ def replace(
+ self,
+ nano_id: str,
+ *,
+ data: t.Dict[str, t.Any],
+ ) -> webhook_endpoint_replace_response.WebhookEndpointReplaceResponse:
+ """
+ Replace the stored data of a webhook endpoint (full replacement).
+
+ :param nano_id: The endpoint id.
+ :param data: The complete new endpoint data.
+ :return: The updated endpoint.
+
+ Example:
+ composio.webhooks.endpoints.replace(
+ "we_123",
+ data={"secret": "new-signing-secret"},
+ )
+ """
+ return self._client.webhook_endpoints.replace(nano_id, data=data)
+
+ def update(
+ self,
+ nano_id: str,
+ *,
+ data: t.Dict[str, t.Any],
+ ) -> webhook_endpoint_update_response.WebhookEndpointUpdateResponse:
+ """
+ Merge new data into a webhook endpoint (partial update).
+
+ :param nano_id: The endpoint id.
+ :param data: The fields to merge into the endpoint data.
+ :return: The updated endpoint.
+
+ Example:
+ composio.webhooks.endpoints.update(
+ "we_123",
+ data={"secret": "new-signing-secret"},
+ )
+ """
+ return self._client.webhook_endpoints.update(nano_id, data=data)
+
+
+class Webhooks(Resource):
+ """Webhooks namespace, exposed as ``composio.webhooks``."""
+
+ subscriptions: WebhookSubscriptions
+ """Project webhook subscription used for event delivery."""
+
+ endpoints: WebhookEndpoints
+ """Inbound webhook endpoints (per toolkit + OAuth app)."""
+
+ def __init__(self, client: HttpClient):
+ super().__init__(client)
+ self.subscriptions = WebhookSubscriptions(client)
+ self.endpoints = WebhookEndpoints(client)
diff --git a/python/composio/exceptions.py b/python/composio/exceptions.py
index daf9c2606..107ba2050 100644
--- a/python/composio/exceptions.py
+++ b/python/composio/exceptions.py
@@ -5,6 +5,8 @@ Composio exceptions.
import difflib
import typing as t
+from composio_client import ComposioDeprecationWarning as ComposioDeprecationWarning
+
ENV_COMPOSIO_API_KEY = "COMPOSIO_API_KEY"
@@ -389,6 +391,27 @@ class ComposioLegacyConnectedAccountsEndpointRetiredError(ConnectedAccountError)
pass
+class ComposioConnectedAccountRevocationNotSupportedError(ConnectedAccountError):
+ """Raised by ``composio.connected_accounts.revoke()`` when the toolkit
+ behind the connected account does not support programmatic token
+ revocation (API ``400``).
+
+ Fix: delete or disable the connected account instead, and revoke the
+ grant from the provider's own settings page.
+ """
+
+ pass
+
+
+class ComposioConnectedAccountNotRevokableError(ConnectedAccountError):
+ """Raised by ``composio.connected_accounts.revoke()`` when the connected
+ account is not in a state that can be revoked (API ``409``), for
+ example because it was already revoked or never became ``ACTIVE``.
+ """
+
+ pass
+
+
class ComposioAclOnlyForSharedError(ConnectedAccountError):
"""Raised when ACL fields (``allow_all_users``, ``allowed_user_ids``,
``not_allowed_user_ids``) are sent on a ``PRIVATE`` connection. ACL
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index 09286a344..b1ad08a35 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -1,8 +1,11 @@
from __future__ import annotations
+import logging
import os
import typing as t
+import warnings
+import httpx
import typing_extensions as te
from composio import exceptions
@@ -10,10 +13,13 @@ from composio.client import DEFAULT_MAX_RETRIES, APIEnvironment, HttpClient
from composio.core.models import (
AuthConfigs,
ConnectedAccounts,
+ Keyring,
+ Logs,
Toolkits,
ToolRouter,
Tools,
Triggers,
+ Webhooks,
)
from composio.core.models.base import allow_tracking
from composio.core.models.mcp import MCP
@@ -25,9 +31,14 @@ from composio.core.provider._openai import (
)
from composio.core.provider.base import BaseProvider
from composio.core.types import ToolkitVersionParam
-from composio.utils.logging import WithLogger
+from composio.utils.logging import LogLevel, WithLogger
from composio.utils.toolkit_version import get_toolkit_versions
+_TOOL_ROUTER_DEPRECATION = (
+ "`composio.tool_router` is deprecated; use `composio.sessions` instead "
+ "(or the `composio.create` / `composio.use` shortcuts). It returns the same object."
+)
+
class SDKConfig(te.TypedDict):
environment: te.NotRequired[APIEnvironment]
@@ -42,6 +53,9 @@ class SDKConfig(te.TypedDict):
sensitive_file_upload_protection: te.NotRequired[bool]
file_upload_path_deny_segments: te.NotRequired[t.Sequence[str]]
file_upload_dirs: te.NotRequired[t.Union[t.Sequence[str], t.Literal[False]]]
+ http_client: te.NotRequired[httpx.Client]
+ logger: te.NotRequired[logging.Logger]
+ logging_level: te.NotRequired[LogLevel]
class Composio(t.Generic[TTool, TToolCollection], WithLogger):
@@ -122,8 +136,24 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
- Providing a value REPLACES the default. Include ``~/.composio/temp`` in
your list if you want the default staging dir to keep working.
- On Windows, entries are compared case-insensitively.
+ :param http_client: An ``httpx.Client`` the SDK sends every API request
+ through (custom transports, proxies, or mocked transports in tests).
+ :param logger: A ``logging.Logger`` that receives the ``Composio``
+ instance's log records and the records the underlying
+ ``composio_client`` emits (its per-request lifecycle records at
+ DEBUG). Sensitive values are redacted and long lines truncated
+ before a record reaches it. Other SDK components still log to the
+ shared ``composio`` logger, and deprecation notices are raised as
+ ``ComposioDeprecationWarning`` warnings rather than log records.
+ Defaults to the shared ``composio`` logger.
+ :param logging_level: The :class:`composio.utils.logging.LogLevel` applied
+ to the SDK logger and to the ``composio_client`` logger. Defaults to
+ ``LogLevel.INFO`` (``COMPOSIO_LOGGING_LEVEL`` overrides the default
+ when no ``logger`` is passed).
"""
- WithLogger.__init__(self)
+ logger = kwargs.get("logger")
+ logging_level = kwargs.get("logging_level")
+ WithLogger.__init__(self, logger=logger, logging_level=logging_level)
api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
if not api_key:
raise exceptions.ApiKeyNotProvidedError()
@@ -146,6 +176,9 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
base_url=kwargs.get("base_url") or os.environ.get("COMPOSIO_BASE_URL"),
timeout=kwargs.get("timeout"),
max_retries=kwargs.get("max_retries", DEFAULT_MAX_RETRIES),
+ http_client=kwargs.get("http_client"),
+ logger=logger,
+ logging_level=logging_level,
)
self.provider = actual_provider
sensitive_file_upload_protection: bool = kwargs.get(
@@ -175,6 +208,9 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
self.auth_configs = AuthConfigs(client=self._client)
self.connected_accounts = ConnectedAccounts(client=self._client)
self.mcp = MCP(client=self._client)
+ self.webhooks = Webhooks(client=self._client)
+ self.logs = Logs(client=self._client)
+ self.keyring = Keyring(client=self._client)
# experimental API — decorators for custom tools and toolkits,
# plus experimental SDK methods (e.g. update_acl)
@@ -221,10 +257,7 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
return self._sessions
@property
- @te.deprecated(
- "`composio.tool_router` is deprecated; use `composio.sessions` instead "
- "(or the `composio.create` / `composio.use` shortcuts). It returns the same object."
- )
+ @te.deprecated(_TOOL_ROUTER_DEPRECATION, category=None)
def tool_router(self) -> ToolRouter[TTool, TToolCollection]:
"""Deprecated alias for :attr:`sessions`.
@@ -232,6 +265,11 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):
Use :attr:`sessions` instead. ``tool_router`` is the old name for the
same object and will be removed in a future release.
"""
+ warnings.warn(
+ _TOOL_ROUTER_DEPRECATION,
+ exceptions.ComposioDeprecationWarning,
+ stacklevel=2,
+ )
return self._sessions
@property
diff --git a/python/composio/utils/logging.py b/python/composio/utils/logging.py
index 5f0a33e1d..8481b920b 100644
--- a/python/composio/utils/logging.py
+++ b/python/composio/utils/logging.py
@@ -201,7 +201,7 @@ class WithLogger:
self,
logger: t.Optional[logging.Logger] = None,
logger_name: str = _DEFAULT_LOGGER_NAME,
- logging_level: LogLevel = LogLevel.INFO,
+ logging_level: t.Optional[LogLevel] = None,
verbosity_level: t.Optional[int] = None,
) -> None:
"""
@@ -209,12 +209,17 @@ class WithLogger:
:param logger: the logger object.
:param logger_name: the default logger name, if a logger is not provided.
+ :param logging_level: when given, applied to the logger in use (the
+ provided ``logger`` or the shared default one).
"""
self._logger = (
_VerbosityWrapper(logger, verbosity_level=verbosity_level)
if logger is not None
- else get(name=logger_name, level=logging_level)
+ else get(name=logger_name, level=logging_level or LogLevel.INFO)
)
+ if logging_level is not None:
+ self._logger.logger.setLevel(_LEVELS[logging_level])
+ self._logger.level = self._logger.logger.level
self._logger.setup(verbosity_level=verbosity_level)
self._logging_level = logging._levelToName[self._logger.level]
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 921fdb36e..0a29f32af 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -7,7 +7,7 @@ requires-python = ">=3.10,<4"
dependencies = [
"pysher>=1.0.8",
"pydantic>=2.11.9",
- "composio-client==1.43.0",
+ "composio-client==2.0.0rc7",
"typing-extensions>=4.16.0",
"openai>=2.48.0",
"json-schema-to-pydantic>=0.4.11",
diff --git a/python/setup.py b/python/setup.py
index 10dca2ca6..71750663b 100644
--- a/python/setup.py
+++ b/python/setup.py
@@ -25,7 +25,7 @@ setup(
install_requires=[
"pysher>=1.0.8",
"pydantic>=2.11.9",
- "composio-client==2.0.0rc6",
+ "composio-client==2.0.0rc7",
"typing-extensions>=4.16.0",
"openai>=2.48.0",
"json-schema-to-pydantic>=0.4.11",
diff --git a/python/tests/test_connected_accounts.py b/python/tests/test_connected_accounts.py
index 9616a8f00..a1d51ccb1 100644
--- a/python/tests/test_connected_accounts.py
+++ b/python/tests/test_connected_accounts.py
@@ -1,10 +1,11 @@
import logging
import time
+import typing as t
import warnings
from unittest.mock import Mock, patch
import pytest
-from composio_client import omit
+from composio_client import BadRequestError, ConflictError, omit
from composio import exceptions
from composio.core.models.connected_accounts import (
@@ -300,7 +301,96 @@ class TestConnectedAccounts:
connected_accounts.update_status
is mock_client.connected_accounts.update_status
)
- assert connected_accounts.refresh is mock_client.connected_accounts.refresh
+
+ def test_refresh_is_deprecated_and_delegates(self, connected_accounts, mock_client):
+ mock_client.connected_accounts.refresh.return_value = {"status": "ok"}
+
+ with pytest.warns(
+ exceptions.ComposioDeprecationWarning, match="refresh\\(\\) is deprecated"
+ ):
+ result = connected_accounts.refresh(
+ "conn-1", query_redirect_url="https://example.com/callback"
+ )
+
+ assert result == {"status": "ok"}
+ mock_client.connected_accounts.refresh.assert_called_once_with(
+ "conn-1", query_redirect_url="https://example.com/callback"
+ )
+
+ def test_refresh_forwards_request_options(self, connected_accounts, mock_client):
+ with pytest.warns(exceptions.ComposioDeprecationWarning):
+ connected_accounts.refresh("conn-1", timeout=3) # type: ignore[call-arg]
+
+ mock_client.connected_accounts.refresh.assert_called_once_with(
+ "conn-1", timeout=3
+ )
+
+ def test_refresh_ignores_removed_validate_credentials(
+ self, connected_accounts, mock_client
+ ):
+ with pytest.warns(exceptions.ComposioDeprecationWarning) as record:
+ connected_accounts.refresh("conn-1", validate_credentials=True)
+
+ assert any("validate_credentials" in str(w.message) for w in record)
+ mock_client.connected_accounts.refresh.assert_called_once_with("conn-1")
+
+ def test_revoke_delegates_to_client(self, connected_accounts, mock_client):
+ mock_client.connected_accounts.revoke.return_value = {"revoked_tokens": []}
+
+ result = connected_accounts.revoke("conn-1")
+
+ assert result == {"revoked_tokens": []}
+ mock_client.connected_accounts.revoke.assert_called_once_with("conn-1")
+
+ def test_revoke_maps_400_to_not_supported(self, connected_accounts, mock_client):
+ mock_client.connected_accounts.revoke.side_effect = _make_status_error(
+ BadRequestError, "toolkit does not support revocation"
+ )
+
+ with pytest.raises(
+ exceptions.ComposioConnectedAccountRevocationNotSupportedError
+ ) as info:
+ connected_accounts.revoke("conn-1")
+
+ assert "conn-1" in str(info.value)
+ assert "toolkit does not support revocation" in str(info.value)
+ assert isinstance(info.value.__cause__, BadRequestError)
+
+ def test_revoke_maps_409_to_not_revokable(self, connected_accounts, mock_client):
+ mock_client.connected_accounts.revoke.side_effect = _make_status_error(
+ ConflictError, "connection is not ACTIVE"
+ )
+
+ with pytest.raises(
+ exceptions.ComposioConnectedAccountNotRevokableError
+ ) as info:
+ connected_accounts.revoke("conn-1")
+
+ assert "not in a revokable state" in str(info.value)
+ assert isinstance(info.value.__cause__, ConflictError)
+
+ def test_revoke_does_not_swallow_other_errors(
+ self, connected_accounts, mock_client
+ ):
+ mock_client.connected_accounts.revoke.side_effect = RuntimeError("boom")
+
+ with pytest.raises(RuntimeError):
+ connected_accounts.revoke("conn-1")
+
+ def test_complete_auth_delegates_to_client(self, connected_accounts, mock_client):
+ mock_client.connected_accounts.complete_auth.return_value = {
+ "connected_account_id": "ca_1",
+ "toolkit_slug": "github",
+ }
+
+ result = connected_accounts.complete_auth(
+ user_id="user-1", session_uri="session-abc"
+ )
+
+ assert result == {"connected_account_id": "ca_1", "toolkit_slug": "github"}
+ mock_client.connected_accounts.complete_auth.assert_called_once_with(
+ user_id="user-1", session_uri="session-abc"
+ )
def test_enable_and_disable_partials(self, connected_accounts, mock_client):
connected_accounts.enable("conn-1")
@@ -526,22 +616,27 @@ class TestConnectedAccounts:
assert result == "connected"
-def _make_bad_request_error(message: str):
- """Build a BadRequestError instance for testing the error mapper.
+def _make_status_error(error_type: t.Type[Exception], message: str):
+ """Build an ``APIStatusError`` subclass instance for testing error mappers.
- The composio_client BadRequestError constructor signature is internal —
- rather than depend on it, we stub a minimal object that ``str(error)``
- surfaces the message and which is recognized as the BadRequestError type
- by ``isinstance``. This mirrors how production responses arrive: the
- error class with a message body.
+ The composio_client error constructor signatures are internal — rather
+ than depend on them, we stub a minimal object that ``str(error)``
+ surfaces the message and which is recognized as the given type by
+ ``isinstance``. This mirrors how production responses arrive: the error
+ class with a message body.
"""
- from composio_client import BadRequestError
-
- error = BadRequestError.__new__(BadRequestError)
+ error = error_type.__new__(error_type)
Exception.__init__(error, message)
return error
+def _make_bad_request_error(message: str):
+ """Build a BadRequestError instance for testing the error mapper."""
+ from composio_client import BadRequestError
+
+ return _make_status_error(BadRequestError, message)
+
+
class TestConnectedAccountsAcl:
"""Tests for SHARED accounts surface on ``link()`` and
``composio.experimental.update_acl()``."""
@@ -749,7 +844,7 @@ class TestConnectedAccountsAcl:
)
-# SEC-339: initiate() must gate its DeprecationWarning on the response
+# SEC-339: initiate() must gate its ComposioDeprecationWarning on the response
# `Deprecation` HTTP header (RFC 9745) that apollo emits only on the
# retiring branch (Composio-managed + redirectable OAuth). These tests pin
# that contract so the previous false-positive behavior — warning purely
@@ -788,7 +883,7 @@ class TestInitiateDeprecationHeaderGate:
def test_warns_once_when_response_carries_deprecation_header(self, mock_client):
"""Managed + redirectable-OAuth path: apollo sets `Deprecation`,
- SDK emits a `DeprecationWarning` pointing callers at link()."""
+ SDK emits a `ComposioDeprecationWarning` pointing callers at link()."""
self._no_existing_accounts(mock_client)
body = self._make_response()
_set_initiate_response(
@@ -810,7 +905,11 @@ class TestInitiateDeprecationHeaderGate:
req = connected_accounts.initiate(user_id="user-1", auth_config_id="auth-1")
assert isinstance(req, ConnectionRequest)
- deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+ deprecations = [
+ w
+ for w in caught
+ if issubclass(w.category, exceptions.ComposioDeprecationWarning)
+ ]
assert len(deprecations) == 1
message = str(deprecations[0].message)
assert "composio.connected_accounts.link()" in message
@@ -828,7 +927,11 @@ class TestInitiateDeprecationHeaderGate:
warnings.simplefilter("always")
connected_accounts.initiate(user_id="user-1", auth_config_id="auth-1")
- deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+ deprecations = [
+ w
+ for w in caught
+ if issubclass(w.category, exceptions.ComposioDeprecationWarning)
+ ]
assert deprecations == []
def test_warns_at_most_once_per_process_across_calls(self, mock_client):
@@ -852,5 +955,9 @@ class TestInitiateDeprecationHeaderGate:
mock_client.connected_accounts.list.return_value = empty
connected_accounts.initiate(user_id="user-1", auth_config_id="auth-1")
- deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+ deprecations = [
+ w
+ for w in caught
+ if issubclass(w.category, exceptions.ComposioDeprecationWarning)
+ ]
assert len(deprecations) == 1
diff --git a/python/tests/test_experimental_custom_toolkits.py b/python/tests/test_experimental_custom_toolkits.py
new file mode 100644
index 000000000..231e7f86f
--- /dev/null
+++ b/python/tests/test_experimental_custom_toolkits.py
@@ -0,0 +1,91 @@
+"""Tests for ``composio.experimental.custom_toolkits``."""
+
+from unittest.mock import Mock
+
+import pytest
+from composio_client import omit
+
+from composio import exceptions
+from composio.client.types import custom_upsert_params
+from composio.core.models.experimental import (
+ ExperimentalAPI,
+ ExperimentalCustomToolkits,
+)
+
+TOOLKIT_CONFIG: custom_upsert_params.ToolkitConfig = {
+ "name": "My Toolkit",
+ "app_url": "https://mcp.example.com/mcp",
+ "auth_schemes": [
+ {
+ "mode": "API_KEY",
+ "headers": {"Authorization": "Bearer {{generic_api_key}}"},
+ }
+ ],
+}
+
+
+def mock_client() -> Mock:
+ client = Mock()
+ client.custom = Mock()
+ return client
+
+
+def custom_toolkits(mock_client: Mock) -> ExperimentalCustomToolkits:
+ return ExperimentalCustomToolkits(client=mock_client)
+
+
+class TestExperimentalCustomToolkits:
+ def test_mounted_on_experimental_api(self, mock_client):
+ experimental = ExperimentalAPI(client=mock_client)
+
+ assert isinstance(experimental.custom_toolkits, ExperimentalCustomToolkits)
+ assert experimental.custom_toolkits._client is mock_client
+
+ def test_upsert_passes_params_through(self, custom_toolkits, mock_client):
+ mock_client.custom.upsert.return_value = "upserted"
+
+ result = custom_toolkits.upsert(
+ slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG
+ )
+
+ assert result == "upserted"
+ mock_client.custom.upsert.assert_called_once_with(
+ slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG
+ )
+
+ def test_sync_with_connected_account(self, custom_toolkits, mock_client):
+ mock_client.custom.sync.return_value = "synced"
+
+ result = custom_toolkits.sync("CUSTOM_MY_TOOLKIT", connected_account_id="ca_1")
+
+ assert result == "synced"
+ mock_client.custom.sync.assert_called_once_with(
+ slug="CUSTOM_MY_TOOLKIT", connected_account_id="ca_1"
+ )
+
+ def test_sync_without_connected_account(self, custom_toolkits, mock_client):
+ custom_toolkits.sync("CUSTOM_MY_TOOLKIT")
+
+ mock_client.custom.sync.assert_called_once_with(
+ slug="CUSTOM_MY_TOOLKIT", connected_account_id=omit
+ )
+
+ def test_delete(self, custom_toolkits, mock_client):
+ mock_client.custom.delete_toolkit.return_value = "deleted"
+
+ result = custom_toolkits.delete("CUSTOM_MY_TOOLKIT")
+
+ assert result == "deleted"
+ mock_client.custom.delete_toolkit.assert_called_once_with("CUSTOM_MY_TOOLKIT")
+
+ def test_requires_client(self):
+ custom_toolkits = ExperimentalCustomToolkits(client=None)
+
+ with pytest.raises(exceptions.ValidationError):
+ custom_toolkits.upsert(slug="MY_TOOLKIT", toolkit_config=TOOLKIT_CONFIG)
+ with pytest.raises(exceptions.ValidationError):
+ custom_toolkits.sync("CUSTOM_MY_TOOLKIT")
+ with pytest.raises(exceptions.ValidationError):
+ custom_toolkits.delete("CUSTOM_MY_TOOLKIT")
diff --git a/python/tests/test_experimental_usage.py b/python/tests/test_experimental_usage.py
new file mode 100644
index 000000000..b0824f79a
--- /dev/null
+++ b/python/tests/test_experimental_usage.py
@@ -0,0 +1,80 @@
+"""Tests for ``composio.experimental.usage``."""
+
+from unittest.mock import Mock
+
+import pytest
+
+from composio import exceptions
+from composio.core.models.experimental import ExperimentalAPI, ExperimentalUsage
+
+
+def mock_client() -> Mock:
+ client = Mock()
+ client.project = Mock()
+ client.project.usage = Mock()
+ return client
+
+
+def usage(mock_client: Mock) -> ExperimentalUsage:
+ return ExperimentalUsage(client=mock_client)
+
+
+class TestExperimentalUsage:
+ def test_mounted_on_experimental_api(self, mock_client):
+ experimental = ExperimentalAPI(client=mock_client)
+
+ assert isinstance(experimental.usage, ExperimentalUsage)
+ assert experimental.usage._client is mock_client
+
+ def test_summary_passes_params_through(self, usage, mock_client):
+ mock_client.project.usage.retrieve_summary.return_value = "summary"
+
+ result = usage.summary(
+ from_=1.0,
+ to=2.0,
+ entity_types=["tool_execution"],
+ filters={"toolkit_slug": "github"},
+ )
+
+ assert result == "summary"
+ mock_client.project.usage.retrieve_summary.assert_called_once_with(
+ from_=1.0,
+ to=2.0,
+ entity_types=["tool_execution"],
+ filters={"toolkit_slug": "github"},
+ )
+
+ def test_summary_without_params(self, usage, mock_client):
+ usage.summary()
+
+ mock_client.project.usage.retrieve_summary.assert_called_once_with()
+
+ def test_breakdown_passes_entity_type_and_params(self, usage, mock_client):
+ mock_client.project.usage.retrieve.return_value = "breakdown"
+
+ result = usage.breakdown(
+ "tool_execution",
+ group_by="toolkit_slug",
+ order_by="total_quantity",
+ order_direction="desc",
+ limit=5,
+ )
+
+ assert result == "breakdown"
+ mock_client.project.usage.retrieve.assert_called_once_with(
+ "tool_execution",
+ group_by="toolkit_slug",
+ order_by="total_quantity",
+ order_direction="desc",
+ limit=5,
+ )
+
+ def test_requires_client(self):
+ usage = ExperimentalUsage(client=None)
+
+ with pytest.raises(exceptions.ValidationError):
+ usage.summary()
+ with pytest.raises(exceptions.ValidationError):
+ usage.breakdown("tool_execution")
diff --git a/python/tests/test_keyring.py b/python/tests/test_keyring.py
new file mode 100644
index 000000000..47256dd0e
--- /dev/null
+++ b/python/tests/test_keyring.py
@@ -0,0 +1,24 @@
+"""Tests for ``composio.keyring``."""
+
+from unittest.mock import Mock
+
+import pytest
+
+from composio.core.models.keyring import Keyring
+from tests.conftest import mock_http_client
+
+
+def mock_client() -> Mock:
+ client = mock_http_client()
+ client.keyring = Mock()
+ return client
+
+
+def test_list_transfer_keys_delegates_to_client(mock_client):
+ mock_client.keyring.list_transfer_keys.return_value = "transfer-keys"
+
+ result = Keyring(client=mock_client).list_transfer_keys()
+
+ assert result == "transfer-keys"
+ mock_client.keyring.list_transfer_keys.assert_called_once_with()
diff --git a/python/tests/test_logs.py b/python/tests/test_logs.py
new file mode 100644
index 000000000..5753699b2
--- /dev/null
+++ b/python/tests/test_logs.py
@@ -0,0 +1,51 @@
+"""Tests for the ``composio.logs`` namespace."""
+
+from unittest.mock import Mock
+
+import pytest
+
+from composio.core.models.logs import Logs
+from tests.conftest import mock_http_client
+
+
+def mock_client() -> Mock:
+ client = mock_http_client()
+ client.logs = Mock()
+ return client
+
+
+def logs(mock_client: Mock) -> Logs:
+ return Logs(client=mock_client)
+
+
+class TestLogs:
+ def test_search_passes_params_through(self, logs, mock_client):
+ mock_client.logs.create_tool_execution.return_value = "page"
+
+ result = logs.search(
+ limit=20,
+ cursor="c1",
+ filters=[{"field": "toolkit_slug", "value": "github"}],
+ time_range={"from": 1, "to": 2},
+ )
+
+ assert result == "page"
+ mock_client.logs.create_tool_execution.assert_called_once_with(
+ limit=20,
+ cursor="c1",
+ filters=[{"field": "toolkit_slug", "value": "github"}],
+ time_range={"from": 1, "to": 2},
+ )
+
+ def test_search_without_params(self, logs, mock_client):
+ logs.search()
+
+ mock_client.logs.create_tool_execution.assert_called_once_with()
+
+ def test_get(self, logs, mock_client):
+ mock_client.logs.retrieve_tool_execution.return_value = "log"
+
+ assert logs.get("log_123") == "log"
+ mock_client.logs.retrieve_tool_execution.assert_called_once_with("log_123")
diff --git a/python/tests/test_sdk.py b/python/tests/test_sdk.py
index 0b8bd1d38..3eeef1096 100644
--- a/python/tests/test_sdk.py
+++ b/python/tests/test_sdk.py
@@ -61,6 +61,9 @@ class TestComposioSDK:
"sensitive_file_upload_protection",
"file_upload_path_deny_segments",
"file_upload_dirs",
+ "http_client",
+ "logger",
+ "logging_level",
}
assert set(SDKConfig.__annotations__.keys()) == expected_fields
@@ -78,6 +81,28 @@ class TestComposioSDK:
assert ToolkitVersions is not None
assert ToolkitVersionParam is not None
+ def test_sdk_mounts_webhooks_and_logs(self):
+ from composio.core.models import Logs, Webhooks
+
+ composio = Composio(api_key="test-key")
+
+ assert isinstance(composio.webhooks, Webhooks)
+ assert isinstance(composio.logs, Logs)
+ assert composio.webhooks._client is composio._client
+ assert composio.logs._client is composio._client
+
+ def test_sdk_mounts_keyring_and_custom_toolkits(self):
+ from composio.core.models import ExperimentalCustomToolkits, Keyring
+
+ composio = Composio(api_key="test-key")
+
+ assert isinstance(composio.keyring, Keyring)
+ assert composio.keyring._client is composio._client
+ assert isinstance(
+ composio.experimental.custom_toolkits, ExperimentalCustomToolkits
+ )
+ assert composio.experimental.custom_toolkits._client is composio._client
+
def test_sdk_has_required_attributes(self):
"""Test that SDK has required attributes after initialization."""
with patch.dict(os.environ, {"COMPOSIO_API_KEY": "test-key"}):
diff --git a/python/tests/test_sdk_logging.py b/python/tests/test_sdk_logging.py
new file mode 100644
index 000000000..fd1d21bca
--- /dev/null
+++ b/python/tests/test_sdk_logging.py
@@ -0,0 +1,244 @@
+"""SDK-owned logging and deprecation surface.
+
+``Composio(...)`` accepts ``logger`` / ``logging_level`` and routes the
+generated ``composio_client`` logger through the SDK's redacting wrapper.
+Runtime deprecations (the client's response-driven ones and the SDK's own)
+all surface as :class:`ComposioDeprecationWarning`.
+"""
+
+import io
+import logging
+import typing as t
+import warnings
+
+import httpx
+import pytest
+
+from composio import Composio, ComposioDeprecationWarning, exceptions
+from composio.client import CLIENT_LOGGER_NAME, _ClientLogForwarder
+from composio.core.models.base import allow_tracking
+from composio.utils.logging import LogLevel
+
+_LIST_BODY: dict[str, t.Any] = {
+ "items": [],
+ "next_cursor": None,
+ "total_pages": 1,
+ "current_page": 1,
+ "total_items": 0,
+}
+
+
[email protected](autouse=True)
+def disable_telemetry():
+ token = allow_tracking.set(False)
+ yield
+ allow_tracking.reset(token)
+
+
+def custom_logger() -> t.Iterator[tuple[logging.Logger, io.StringIO]]:
+ output = io.StringIO()
+ logger = logging.getLogger("composio-test-sdk-owned-logger")
+ logger.handlers = [logging.StreamHandler(output)]
+ logger.propagate = False
+ logger.setLevel(logging.DEBUG)
+ yield logger, output
+ logger.handlers = []
+
+
+def _mock_transport(
+ headers: t.Optional[dict[str, str]] = None,
+ seen: t.Optional[list[httpx.Request]] = None,
+) -> httpx.Client:
+ def handler(request: httpx.Request) -> httpx.Response:
+ if seen is not None:
+ seen.append(request)
+ return httpx.Response(200, json=_LIST_BODY, headers=headers or {})
+
+ return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def _forwarders() -> list[_ClientLogForwarder]:
+ return [
+ handler
+ for handler in logging.getLogger(CLIENT_LOGGER_NAME).handlers
+ if isinstance(handler, _ClientLogForwarder)
+ ]
+
+
+class TestCustomLogger:
+ def test_sdk_logs_use_custom_logger_with_redaction(self, custom_logger):
+ logger, output = custom_logger
+ composio = Composio(api_key="test-key", logger=logger)
+
+ assert composio.logger.logger is logger
+ composio.logger.info("sdk record api_key=sdk-secret")
+
+ text = output.getvalue()
+ assert "sdk record" in text
+ assert "sdk-secret" not in text
+ assert "[REDACTED]" in text
+
+ def test_client_records_are_forwarded_with_redaction(self, custom_logger):
+ logger, output = custom_logger
+ Composio(api_key="test-key", logger=logger)
+
+ logging.getLogger(CLIENT_LOGGER_NAME).info(
+ "Authorization: Bearer client-secret-token"
+ )
+
+ text = output.getvalue()
+ assert "Authorization" in text
+ assert "client-secret-token" not in text
+ assert "[REDACTED]" in text
+
+ def test_client_request_lifecycle_reaches_custom_logger(self, custom_logger):
+ logger, output = custom_logger
+ composio = Composio(
+ api_key="test-key", http_client=_mock_transport(), logger=logger
+ )
+
+ composio.client.toolkits.list()
+
+ text = output.getvalue()
+ assert "path=/api/v3.1/toolkits" in text
+ assert "status=200" in text
+
+ def test_client_request_lifecycle_stays_out_of_info(self, custom_logger):
+ logger, output = custom_logger
+ logger.setLevel(logging.INFO)
+ composio = Composio(
+ api_key="test-key", http_client=_mock_transport(), logger=logger
+ )
+
+ composio.client.toolkits.list()
+
+ assert logging.getLogger(CLIENT_LOGGER_NAME).level == logging.WARNING
+ assert "path=/api/v3.1/toolkits" not in output.getvalue()
+
+ def test_client_logger_does_not_propagate_to_root(self, custom_logger):
+ logger, _ = custom_logger
+ Composio(api_key="test-key", logger=logger)
+
+ client_logger = logging.getLogger(CLIENT_LOGGER_NAME)
+ assert client_logger.propagate is False
+
+ def test_forwarder_is_installed_once_per_logger(self, custom_logger):
+ logger, _ = custom_logger
+ Composio(api_key="test-key", logger=logger)
+ Composio(api_key="test-key", logger=logger)
+
+ forwarders = _forwarders()
+ assert len(forwarders) == 1
+ assert forwarders[0].wrapper.logger is logger
+
+ def test_forwarder_is_replaced_for_a_different_logger(self, custom_logger):
+ logger, output = custom_logger
+ other = logging.getLogger("composio-test-sdk-owned-logger-other")
+ other_output = io.StringIO()
+ other.handlers = [logging.StreamHandler(other_output)]
+ other.propagate = False
+ other.setLevel(logging.DEBUG)
+ try:
+ Composio(api_key="test-key", logger=other)
+ Composio(api_key="test-key", logger=logger)
+
+ forwarders = _forwarders()
+ assert len(forwarders) == 1
+ assert forwarders[0].wrapper.logger is logger
+
+ logging.getLogger(CLIENT_LOGGER_NAME).info("delivered once")
+ assert "delivered once" in output.getvalue()
+ assert "delivered once" not in other_output.getvalue()
+ finally:
+ other.handlers = []
+
+
+class TestLoggingLevel:
+ def test_logging_level_applies_to_sdk_and_client_loggers(self, custom_logger):
+ logger, output = custom_logger
+ composio = Composio(
+ api_key="test-key", logger=logger, logging_level=LogLevel.WARNING
+ )
+
+ assert logger.level == logging.WARNING
+ assert logging.getLogger(CLIENT_LOGGER_NAME).level == logging.WARNING
+ assert composio._logging_level == "WARNING"
+
+ composio.logger.info("sdk info dropped")
+ logging.getLogger(CLIENT_LOGGER_NAME).info("client info dropped")
+ composio.logger.warning("sdk warning kept")
+ logging.getLogger(CLIENT_LOGGER_NAME).warning("client warning kept")
+
+ text = output.getvalue()
+ assert "dropped" not in text
+ assert "sdk warning kept" in text
+ assert "client warning kept" in text
+
+ def test_logging_level_debug_enables_debug_records(self, custom_logger):
+ logger, output = custom_logger
+ logger.setLevel(logging.WARNING)
+ composio = Composio(
+ api_key="test-key", logger=logger, logging_level=LogLevel.DEBUG
+ )
+
+ composio.logger.debug("sdk debug kept")
+ logging.getLogger(CLIENT_LOGGER_NAME).debug("client debug kept")
+
+ text = output.getvalue()
+ assert "sdk debug kept" in text
+ assert "client debug kept" in text
+
+
+class TestDeprecationWarnings:
+ def test_category_is_re_exported(self):
+ assert exceptions.ComposioDeprecationWarning is ComposioDeprecationWarning
+ assert issubclass(ComposioDeprecationWarning, UserWarning)
+ assert not issubclass(ComposioDeprecationWarning, DeprecationWarning)
+
+ def test_client_deprecation_header_reaches_caller(self, custom_logger):
+ logger, _ = custom_logger
+ composio = Composio(
+ api_key="test-key",
+ http_client=_mock_transport(headers={"Deprecation": "@1688169599"}),
+ logger=logger,
+ )
+
+ with pytest.warns(ComposioDeprecationWarning, match="toolkits.list"):
+ composio.client.toolkits.list()
+
+ def test_no_warning_without_deprecation_header(self, custom_logger):
+ logger, _ = custom_logger
+ composio = Composio(
+ api_key="test-key", http_client=_mock_transport(), logger=logger
+ )
+
+ with warnings.catch_warnings():
+ warnings.simplefilter("error", ComposioDeprecationWarning)
+ composio.client.toolkits.list()
+
+ def test_tool_router_alias_warns_with_sdk_category(self):
+ composio = Composio(api_key="test-key")
+
+ with pytest.warns(ComposioDeprecationWarning, match="tool_router"):
+ alias = composio.tool_router
+
+ assert alias is composio.sessions
+
+
+class TestToolsListWireParams:
+ def test_search_is_sent_as_query(self, custom_logger):
+ logger, _ = custom_logger
+ seen: list[httpx.Request] = []
+ composio = Composio(
+ api_key="test-key", http_client=_mock_transport(seen=seen), logger=logger
+ )
+
+ with warnings.catch_warnings():
+ warnings.simplefilter("error", ComposioDeprecationWarning)
+ composio.tools.get_raw_composio_tools(search="github issues")
+
+ assert len(seen) == 1
+ params = seen[0].url.params
+ assert params["query"] == "github issues"
+ assert "search" not in params
diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.py
index 2046b21b8..a7450d4b1 100644
--- a/python/tests/test_tool_router.py
+++ b/python/tests/test_tool_router.py
@@ -124,6 +124,22 @@ class TestToolRouter:
assert tool_router._client == mock_client
assert tool_router._provider == mock_provider
+ def test_session_config_history(self, tool_router, mock_client):
+ """``session.config_history`` passes the session id and pagination."""
+ session = tool_router.create(user_id="user_123")
+ mock_client.tool_router.session.config_history.return_value = "history"
+
+ assert session.config_history() == "history"
+ mock_client.tool_router.session.config_history.assert_called_once_with(
+ session_id="session_123"
+ )
+
+ mock_client.tool_router.session.config_history.reset_mock()
+ session.config_history(limit=10, cursor="c1")
+ mock_client.tool_router.session.config_history.assert_called_once_with(
+ session_id="session_123", limit=10, cursor="c1"
+ )
+
def test_create_basic_session(self, tool_router, mock_client):
"""Test creating a basic session with minimal configuration."""
session = tool_router.create(user_id="user_123")
diff --git a/python/tests/test_toolkits.py b/python/tests/test_toolkits.py
new file mode 100644
index 000000000..d42cfb158
--- /dev/null
+++ b/python/tests/test_toolkits.py
@@ -0,0 +1,107 @@
+"""Tests for ``composio.toolkits.get_many`` and ``composio.toolkits.changelog``."""
+
+from unittest.mock import Mock
+
+import pytest
+from composio_client import omit
+
+from composio.core.models.toolkits import Toolkits
+from tests.conftest import mock_http_client
+
+
+def mock_client() -> Mock:
+ client = mock_http_client()
+ client.toolkits = Mock()
+ client.connected_accounts = Mock()
+ return client
+
+
+def toolkits(mock_client: Mock) -> Toolkits:
+ return Toolkits(client=mock_client)
+
+
+class TestToolkitsGetMany:
+ def test_get_many_by_slugs(self, toolkits, mock_client):
+ mock_client.toolkits.retrieve_multi.return_value = Mock(items=["gh", "sl"])
+
+ result = toolkits.get_many(("github", "slack"))
+
+ assert result == ["gh", "sl"]
+ mock_client.toolkits.retrieve_multi.assert_called_once_with(
+ toolkits=["github", "slack"],
+ category=omit,
+ managed_by=omit,
+ sort_by=omit,
+ limit=omit,
+ cursor=omit,
+ )
+
+ def test_get_many_forwards_filters(self, toolkits, mock_client):
+ toolkits.get_many(
+ ["github"],
+ category="developer-tools",
+ managed_by="composio",
+ sort_by="usage",
+ limit=10,
+ cursor="c1",
+ )
+
+ mock_client.toolkits.retrieve_multi.assert_called_once_with(
+ toolkits=["github"],
+ category="developer-tools",
+ managed_by="composio",
+ sort_by="usage",
+ limit=10,
+ cursor="c1",
+ )
+
+
+class TestToolkitsChangelog:
+ def test_changelog(self, toolkits, mock_client):
+ mock_client.toolkits.retrieve_changelog.return_value = "changelog"
+
+ assert toolkits.changelog() == "changelog"
+ mock_client.toolkits.retrieve_changelog.assert_called_once_with()
+
+
+class TestToolkitsScopes:
+ def test_recommend_scopes_passes_params_through(self, toolkits, mock_client):
+ mock_client.toolkits.recommend_scopes.return_value = "recommendation"
+
+ result = toolkits.recommend_scopes(
+ "gmail",
+ tools=["GMAIL_SEND_EMAIL"],
+ auth_scheme="OAUTH2",
+ grant_context={"account_type": "Google Workspace"},
+ available_scopes=["openid"],
+ )
+
+ assert result == "recommendation"
+ mock_client.toolkits.recommend_scopes.assert_called_once_with(
+ "gmail",
+ tools=["GMAIL_SEND_EMAIL"],
+ auth_scheme="OAUTH2",
+ grant_context={"account_type": "Google Workspace"},
+ available_scopes=["openid"],
+ )
+
+ def test_list_grant_contexts_passes_params_through(self, toolkits, mock_client):
+ mock_client.toolkits.retrieve_scopes_grant_context.return_value = "contexts"
+
+ result = toolkits.list_grant_contexts(
+ "gmail", auth_scheme="OAUTH2", toolkit_version="20250909_00"
+ )
+
+ assert result == "contexts"
+ mock_client.toolkits.retrieve_scopes_grant_context.assert_called_once_with(
+ "gmail", auth_scheme="OAUTH2", toolkit_version="20250909_00"
+ )
+
+ def test_list_grant_contexts_without_params(self, toolkits, mock_client):
+ toolkits.list_grant_contexts("gmail")
+
+ mock_client.toolkits.retrieve_scopes_grant_context.assert_called_once_with(
+ "gmail"
+ )
diff --git a/python/tests/test_triggers.py b/python/tests/test_triggers.py
index 56d487ee5..f4acdd584 100644
--- a/python/tests/test_triggers.py
+++ b/python/tests/test_triggers.py
@@ -116,26 +116,18 @@ class TestTriggers:
"version": "V3",
"enabled_events": ["composio.trigger.message"],
}
- mock_client.get.return_value = {"items": []}
- mock_client.post.return_value = raw_subscription
+ mock_client.webhook_subscriptions.list.return_value = Mock(items=[])
+ mock_client.webhook_subscriptions.create.return_value = raw_subscription
result = triggers.set_webhook_subscription(webhook_url=webhook_url)
- mock_client.get.assert_called_once_with(
- "/api/v3.1/webhook_subscriptions",
- cast_to=object,
- options={"params": {"limit": 1}},
- )
- mock_client.post.assert_called_once_with(
- "/api/v3.1/webhook_subscriptions",
- cast_to=object,
- body={
- "webhook_url": webhook_url,
- "enabled_events": ["composio.trigger.message"],
- "version": "V3",
- },
+ mock_client.webhook_subscriptions.list.assert_called_once_with(limit=1)
+ mock_client.webhook_subscriptions.create.assert_called_once_with(
+ webhook_url=webhook_url,
+ enabled_events=["composio.trigger.message"],
+ version="V3",
)
- mock_client.patch.assert_not_called()
+ mock_client.webhook_subscriptions.update.assert_not_called()
assert result == raw_subscription
def test_set_webhook_subscription_updates_first_existing(
@@ -152,8 +144,10 @@ class TestTriggers:
"composio.connected_account.expired",
],
}
- mock_client.get.return_value = {"items": [{"id": "sub_123"}]}
- mock_client.patch.return_value = raw_subscription
+ mock_client.webhook_subscriptions.list.return_value = Mock(
+ items=[Mock(id="sub_123")]
+ )
+ mock_client.webhook_subscriptions.update.return_value = raw_subscription
result = triggers.set_webhook_subscription(
webhook_url=webhook_url,
@@ -164,19 +158,17 @@ class TestTriggers:
version="V3",
)
- mock_client.patch.assert_called_once_with(
- "/api/v3.1/webhook_subscriptions/sub_123",
- cast_to=object,
- body={
- "webhook_url": webhook_url,
- "enabled_events": [
- "composio.trigger.message",
- "composio.connected_account.expired",
- ],
- "version": "V3",
- },
+ mock_client.webhook_subscriptions.list.assert_called_once_with(limit=1)
+ mock_client.webhook_subscriptions.update.assert_called_once_with(
+ "sub_123",
+ webhook_url=webhook_url,
+ enabled_events=[
+ "composio.trigger.message",
+ "composio.connected_account.expired",
+ ],
+ version="V3",
)
- mock_client.post.assert_not_called()
+ mock_client.webhook_subscriptions.create.assert_not_called()
assert result == raw_subscription
def test_set_webhook_subscription_rejects_empty_events(self, triggers):
diff --git a/python/tests/test_webhooks.py b/python/tests/test_webhooks.py
new file mode 100644
index 000000000..e5f583119
--- /dev/null
+++ b/python/tests/test_webhooks.py
@@ -0,0 +1,345 @@
+"""Tests for the ``composio.webhooks`` namespace."""
+
+import warnings
+from unittest.mock import Mock
+
+import pytest
+from composio_client import omit
+from composio_client.types import (
+ WebhookSubscriptionCreateResponse,
+ WebhookSubscriptionListResponse,
+)
+
+from composio import exceptions
+from composio.core.models.triggers import Triggers
+from composio.core.models.triggers import WebhookVersion as TriggersWebhookVersion
+from composio.core.models.webhooks import (
+ WebhookEndpoints,
+ Webhooks,
+ WebhookSubscriptions,
+ WebhookVersion,
+)
+from tests.conftest import mock_http_client
+
+
+def mock_client() -> Mock:
+ client = mock_http_client()
+ client.webhook_subscriptions = Mock()
+ client.webhook_endpoints = Mock()
+ return client
+
+
+def subscriptions(mock_client: Mock) -> WebhookSubscriptions:
+ return WebhookSubscriptions(client=mock_client)
+
+
+def endpoints(mock_client: Mock) -> WebhookEndpoints:
+ return WebhookEndpoints(client=mock_client)
+
+
+class TestWebhooksNamespace:
+ def test_mounts_sub_namespaces(self, mock_client):
+ webhooks = Webhooks(client=mock_client)
+
+ assert isinstance(webhooks.subscriptions, WebhookSubscriptions)
+ assert isinstance(webhooks.endpoints, WebhookEndpoints)
+ assert webhooks.subscriptions._client is mock_client
+ assert webhooks.endpoints._client is mock_client
+
+ def test_webhook_version_is_shared_with_triggers(self):
+ assert TriggersWebhookVersion is WebhookVersion
+
+
+class TestWebhookSubscriptions:
+ def test_list(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.list.return_value = "listed"
+
+ assert subscriptions.list() == "listed"
+ mock_client.webhook_subscriptions.list.assert_called_once_with(
+ limit=omit, cursor=omit
+ )
+
+ def test_list_forwards_pagination(self, subscriptions, mock_client):
+ subscriptions.list(limit=5, cursor="abc")
+
+ mock_client.webhook_subscriptions.list.assert_called_once_with(
+ limit=5, cursor="abc"
+ )
+
+ def test_get(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.retrieve.return_value = "sub"
+
+ assert subscriptions.get("sub_123") == "sub"
+ mock_client.webhook_subscriptions.retrieve.assert_called_once_with("sub_123")
+
+ def test_update_omits_absent_fields(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.update.return_value = "updated"
+
+ assert subscriptions.update("sub_123", webhook_url="https://x") == "updated"
+ mock_client.webhook_subscriptions.update.assert_called_once_with(
+ "sub_123", webhook_url="https://x", enabled_events=omit, version=omit
+ )
+
+ def test_update_normalizes_events_and_version(self, subscriptions, mock_client):
+ subscriptions.update(
+ "sub_123",
+ enabled_events=("composio.trigger.message",),
+ version=WebhookVersion.V2,
+ )
+
+ mock_client.webhook_subscriptions.update.assert_called_once_with(
+ "sub_123",
+ webhook_url=omit,
+ enabled_events=["composio.trigger.message"],
+ version="V2",
+ )
+
+ def test_delete(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.delete.return_value = "deleted"
+
+ assert subscriptions.delete("sub_123") == "deleted"
+ mock_client.webhook_subscriptions.delete.assert_called_once_with("sub_123")
+
+ def test_rotate_secret(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.rotate_secret.return_value = "rotated"
+
+ assert subscriptions.rotate_secret("sub_123") == "rotated"
+ mock_client.webhook_subscriptions.rotate_secret.assert_called_once_with(
+ "sub_123"
+ )
+
+ def test_list_event_types(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.list_event_types.return_value = "types"
+
+ assert subscriptions.list_event_types() == "types"
+ mock_client.webhook_subscriptions.list_event_types.assert_called_once_with()
+
+
+class TestWebhookSubscriptionsSet:
+ def test_creates_when_none_exists(self, subscriptions, mock_client):
+ webhook_url = "https://example.com/webhooks/composio"
+ raw = {
+ "id": "sub_123",
+ "webhook_url": webhook_url,
+ "version": "V3",
+ "enabled_events": ["composio.trigger.message"],
+ "secret": "whsec_abc",
+ }
+ mock_client.webhook_subscriptions.list.return_value = Mock(items=[])
+ mock_client.webhook_subscriptions.create.return_value = raw
+
+ result = subscriptions.set(webhook_url=webhook_url)
+
+ mock_client.webhook_subscriptions.list.assert_called_once_with(limit=1)
+ mock_client.webhook_subscriptions.create.assert_called_once_with(
+ webhook_url=webhook_url,
+ enabled_events=["composio.trigger.message"],
+ version="V3",
+ )
+ mock_client.webhook_subscriptions.update.assert_not_called()
+ assert result == raw
+
+ def test_updates_first_existing(self, subscriptions, mock_client):
+ webhook_url = "https://example.com/webhooks/composio"
+ raw = {
+ "id": "sub_123",
+ "webhook_url": webhook_url,
+ "version": "V2",
+ "enabled_events": ["composio.connected_account.expired"],
+ }
+ mock_client.webhook_subscriptions.list.return_value = Mock(
+ items=[Mock(id="sub_123")]
+ )
+ mock_client.webhook_subscriptions.update.return_value = raw
+
+ result = subscriptions.set(
+ webhook_url=webhook_url,
+ enabled_events=["composio.connected_account.expired"],
+ version=WebhookVersion.V2,
+ )
+
+ mock_client.webhook_subscriptions.list.assert_called_once_with(limit=1)
+ mock_client.webhook_subscriptions.update.assert_called_once_with(
+ "sub_123",
+ webhook_url=webhook_url,
+ enabled_events=["composio.connected_account.expired"],
+ version="V2",
+ )
+ mock_client.webhook_subscriptions.create.assert_not_called()
+ assert result == raw
+
+ def test_normalizes_pydantic_response_models(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.list.return_value = (
+ WebhookSubscriptionListResponse.model_validate(
+ {
+ "items": [],
+ "total_pages": 0,
+ "current_page": 1,
+ "total_items": 0,
+ }
+ )
+ )
+ mock_client.webhook_subscriptions.create.return_value = (
+ WebhookSubscriptionCreateResponse.model_validate(
+ {
+ "id": "sub_1",
+ "webhook_url": "https://x",
+ "version": "V3",
+ "enabled_events": ["composio.trigger.message"],
+ "secret": "whsec_abc",
+ "created_at": "2026-01-01",
+ "updated_at": "2026-01-02",
+ }
+ )
+ )
+
+ result = subscriptions.set(webhook_url="https://x")
+
+ assert result == {
+ "id": "sub_1",
+ "webhook_url": "https://x",
+ "version": "V3",
+ "enabled_events": ["composio.trigger.message"],
+ "secret": "whsec_abc",
+ "created_at": "2026-01-01",
+ "updated_at": "2026-01-02",
+ }
+ assert isinstance(result["version"], str)
+ assert type(result["version"]) is str
+
+ def test_normalizes_unvalidated_response_models_without_warnings(
+ self, subscriptions, mock_client
+ ):
+ # The client builds response models without validation, so enum fields
+ # hold plain strings.
+ mock_client.webhook_subscriptions.list.return_value = (
+ WebhookSubscriptionListResponse.model_construct(items=[])
+ )
+ mock_client.webhook_subscriptions.create.return_value = (
+ WebhookSubscriptionCreateResponse.model_construct(
+ id="sub_1",
+ webhook_url="https://x",
+ version="V3",
+ enabled_events=["composio.trigger.message"],
+ secret="whsec_abc",
+ created_at="2026-01-01",
+ updated_at="2026-01-02",
+ )
+ )
+
+ with warnings.catch_warnings():
+ warnings.simplefilter("error")
+ result = subscriptions.set(webhook_url="https://x")
+
+ assert result["version"] == "V3"
+
+ def test_normalizes_camel_case_wire_keys(self, subscriptions, mock_client):
+ mock_client.webhook_subscriptions.list.return_value = Mock(items=[])
+ mock_client.webhook_subscriptions.create.return_value = {
+ "id": "sub_1",
+ "webhookUrl": "https://x",
+ "enabledEvents": ["composio.trigger.message", 42],
+ "createdAt": "2026-01-01",
+ }
+
+ result = subscriptions.set(webhook_url="https://x")
+
+ assert result == {
+ "id": "sub_1",
+ "webhook_url": "https://x",
+ "version": "V3",
+ "enabled_events": ["composio.trigger.message"],
+ "created_at": "2026-01-01",
+ }
+
+ def test_rejects_empty_webhook_url(self, subscriptions, mock_client):
+ with pytest.raises(exceptions.ValidationError):
+ subscriptions.set(webhook_url="")
+ mock_client.webhook_subscriptions.list.assert_not_called()
+
+ def test_rejects_empty_events(self, subscriptions, mock_client):
+ with pytest.raises(exceptions.ValidationError):
+ subscriptions.set(webhook_url="https://x", enabled_events=[])
+ mock_client.webhook_subscriptions.list.assert_not_called()
+
+
+class TestTriggersDelegation:
+ def test_set_webhook_subscription_delegates_to_webhooks(self, mock_client):
+ """``triggers.set_webhook_subscription`` issues the same call sequence
+ as ``webhooks.subscriptions.set`` and returns the same shape."""
+ mock_client.triggers_types = Mock()
+ mock_client.trigger_instances = Mock()
+ resource = mock_client.webhook_subscriptions
+ resource.list.return_value = Mock(items=[Mock(id="sub_9")])
+ resource.update.return_value = {"id": "sub_9", "webhook_url": "https://x"}
+
+ via_triggers = Triggers(client=mock_client).set_webhook_subscription(
+ webhook_url="https://x"
+ )
+ triggers_calls = (
+ resource.list.call_args_list,
+ resource.update.call_args_list,
+ resource.create.call_args_list,
+ )
+ mock_client.reset_mock()
+ resource.list.return_value = Mock(items=[Mock(id="sub_9")])
+ resource.update.return_value = {"id": "sub_9", "webhook_url": "https://x"}
+
+ via_webhooks = WebhookSubscriptions(client=mock_client).set(
+ webhook_url="https://x"
+ )
+
+ assert via_triggers == via_webhooks
+ assert triggers_calls == (
+ resource.list.call_args_list,
+ resource.update.call_args_list,
+ resource.create.call_args_list,
+ )
+
+
+class TestWebhookEndpoints:
+ def test_list(self, endpoints, mock_client):
+ mock_client.webhook_endpoints.list.return_value = "listed"
+
+ assert endpoints.list() == "listed"
+ mock_client.webhook_endpoints.list.assert_called_once_with(toolkit_slug=omit)
+
+ def test_list_with_toolkit_filter(self, endpoints, mock_client):
+ endpoints.list(toolkit_slug="github")
+
+ mock_client.webhook_endpoints.list.assert_called_once_with(
+ toolkit_slug="github"
+ )
+
+ def test_get(self, endpoints, mock_client):
+ mock_client.webhook_endpoints.retrieve.return_value = "endpoint"
+
+ assert endpoints.get("we_1") == "endpoint"
+ mock_client.webhook_endpoints.retrieve.assert_called_once_with("we_1")
+
+ def test_create(self, endpoints, mock_client):
+ mock_client.webhook_endpoints.create.return_value = "created"
+
+ assert endpoints.create(toolkit_slug="github", client_id="cid") == "created"
+ mock_client.webhook_endpoints.create.assert_called_once_with(
+ toolkit_slug="github", client_id="cid"
+ )
+
+ def test_replace(self, endpoints, mock_client):
+ mock_client.webhook_endpoints.replace.return_value = "replaced"
+
+ assert endpoints.replace("we_1", data={"secret": "s"}) == "replaced"
+ mock_client.webhook_endpoints.replace.assert_called_once_with(
+ "we_1", data={"secret": "s"}
+ )
+
+ def test_update(self, endpoints, mock_client):
+ mock_client.webhook_endpoints.update.return_value = "updated"
+
+ assert endpoints.update("we_1", data={"secret": "s"}) == "updated"
+ mock_client.webhook_endpoints.update.assert_called_once_with(
+ "we_1", data={"secret": "s"}
+ )
diff --git a/uv.lock b/uv.lock
index b49d3f40f..9badb3657 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
version = 1
-revision = 2
+revision = 3
requires-python = ">=3.10, <4"
resolution-markers = [
"python_full_version >= '3.15'",
@@ -25,7 +25,7 @@ members = [
]
[manifest.dependency-groups]
-dev = [{ name = "composio", virtual = "python" }]
+dev = [{ name = "composio", editable = "python" }]
[[package]]
name = "aiofiles"
@@ -787,7 +787,7 @@ wheels = [
[[package]]
name = "composio"
version = "2.0.0b0"
-source = { virtual = "python" }
+source = { editable = "python" }
dependencies = [
{ name = "composio-client" },
{ name = "json-schema-to-pydantic" },
@@ -820,7 +820,7 @@ dev = [
[package.metadata]
requires-dist = [
- { name = "composio-client", specifier = "==1.43.0" },
+ { name = "composio-client", specifier = "==2.0.0rc7" },
{ name = "json-schema-to-pydantic", specifier = ">=0.4.11" },
{ name = "jsonschema", specifier = ">=4.23.0" },
{ name = "openai", specifier = ">=2.48.0" },
@@ -834,7 +834,7 @@ requires-dist = [
[package.metadata.requires-dev]
dev = [
{ name = "click", specifier = ">=8.4.2" },
- { name = "composio", virtual = "python" },
+ { name = "composio", editable = "python" },
{ name = "fastapi", specifier = ">=0.140.0" },
{ name = "hypothesis", specifier = ">=6.140.3" },
{ name = "langchain-openai", specifier = "==1.6.0" },
@@ -852,7 +852,7 @@ dev = [
[[package]]
name = "composio-anthropic"
version = "0.21.1"
-source = { virtual = "python/providers/anthropic" }
+source = { editable = "python/providers/anthropic" }
dependencies = [
{ name = "anthropic" },
{ name = "composio" },
@@ -866,25 +866,22 @@ requires-dist = [
[[package]]
name = "composio-client"
-version = "1.43.0"
+version = "2.0.0rc7"
source = { registry = "https://pypi.org/simple" }
dependencies = [
- { name = "anyio" },
- { name = "distro" },
{ name = "httpx" },
{ name = "pydantic" },
- { name = "sniffio" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/b9/4b/3789f4c1347fd01349b66ecaeffb5ef623434c3b1fa4f5c5993fddb69c68/composio_client-1.43.0.tar.gz", hash = "sha256:bb96700da0c2aabc394cebc954be0ebf419557cc42b40f5d148aac52a5aff6f9", size = 246767, upload-time = "2026-07-08T09:06:02.42Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/fc/02/fa3f6d4859fca44cf72b2698162c403007052853437617b8d12e5a5556c9/composio_client-2.0.0rc7.tar.gz", hash = "sha256:52df705896e3aa256ab4498139dc89f2439eee3ae73c040d15ac6b5b16bb38b6", size = 579105, upload-time = "2026-09-11T16:10:04.685Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/07/a2/3ae1f5471a52189ac558de6b0e088dc3575d695a0f91278cddf464274694/composio_client-1.43.0-py3-none-any.whl", hash = "sha256:3274d965b9efb6be90a51977f4c068ed24e2cad9160de4d40d3176d8bb4ce2d9", size = 277716, upload-time = "2026-07-08T09:06:01.007Z" },
+ { url = "https://files.pythonhosted.org/packages/af/4b/e6b12f57f20c94f1cbd19b9f899ef0c9c0097bd8eff346079a9df27e266e/composio_client-2.0.0rc7-py3-none-any.whl", hash = "sha256:094ba51fb0d03e01956ecefd4e0bee298126c9792af547293cd9598cb2c14256", size = 421008, upload-time = "2026-09-11T16:10:02.625Z" },
]
[[package]]
name = "composio-crewai"
version = "0.21.1"
-source = { virtual = "python/providers/crewai" }
+source = { editable = "python/providers/crewai" }
dependencies = [
{ name = "composio" },
{ name = "crewai" },
@@ -914,7 +911,7 @@ requires-dist = [
[[package]]
name = "composio-google"
version = "0.21.1"
-source = { virtual = "python/providers/google" }
+source = { editable = "python/providers/google" }
dependencies = [
{ name = "composio" },
{ name = "google-cloud-aiplatform" },
@@ -929,7 +926,7 @@ requires-dist = [
[[package]]
name = "composio-google-adk"
version = "0.21.1"
-source = { virtual = "python/providers/google_adk" }
+source = { editable = "python/providers/google_adk" }
dependencies = [
{ name = "composio" },
{ name = "google-adk" },
@@ -944,7 +941,7 @@ requires-dist = [
[[package]]
name = "composio-langchain"
version = "0.21.1"
-source = { virtual = "python/providers/langchain" }
+source = { editable = "python/providers/langchain" }
dependencies = [
{ name = "composio" },
{ name = "langchain" },
@@ -959,7 +956,7 @@ requires-dist = [
[[package]]
name = "composio-openai"
version = "0.21.1"
-source = { virtual = "python/providers/openai" }
+source = { editable = "python/providers/openai" }
dependencies = [
{ name = "composio" },
{ name = "openai" },
@@ -974,7 +971,7 @@ requires-dist = [
[[package]]
name = "composio-openai-agents"
version = "0.21.1"
-source = { virtual = "python/providers/openai_agents" }
+source = { editable = "python/providers/openai_agents" }
dependencies = [
{ name = "composio" },
{ name = "openai-agents" },