Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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__.pyindex 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 ComposioDeprecationWarningfrom .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__.pyindex 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 loggingimport osimport platformimport typing as t@@ -15,16 +16,74 @@ from composio_client import (NOT_GIVEN,APIError,NotGiven,- _base_client,)from composio_client import Composio as BaseComposiofrom httpx import URL, Client, Request, Timeout-from composio.utils.logging import WithLogger+from composio.utils.logging import LogLevel, WithLogger, _VerbosityWrapperComposioAPIError = APIErrorAPIEnvironment = 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 = providerself.request_ctx = contextvars.ContextVar[RequestContext]("request_ctx",diff --git a/python/composio/client/types.py b/python/composio/client/types.pyindex 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__.pyindex 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 Logsfrom .mcp import MCPfrom .tool_router import ToolRouterfrom .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.pyindex 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 timport warningsimport typing_extensions as te-from composio_client import BadRequestError, omit+from composio_client import BadRequestError, ConflictError, omitfrom composio import exceptionsfrom composio.client import HttpClientfrom 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.listself.delete = self._client.connected_accounts.deleteself.update_status = self._client.connected_accounts.update_status- self.refresh = self._client.connected_accounts.refreshself.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.pyindex 7e66ab2ab..7daf555d6 100644--- a/python/composio/core/models/experimental.py+++ b/python/composio/core/models/experimental.py@@ -18,10 +18,22 @@ from __future__ import annotationsimport typing as t+import typing_extensions as tefrom pydantic import BaseModelfrom 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 tfrom concurrent.futures import ThreadPoolExecutorfrom dataclasses import dataclass+import typing_extensions as tefrom composio_client import BadRequestError, Omit, omitfrom composio_client._types import SequenceNotStrfrom composio_client.types.tool_list_response import (@@ -29,7 +30,11 @@ from composio_client.types.tool_router.session_search_response import (from composio import exceptionsfrom 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_typefrom composio.core.models.connected_accounts import ConnectionRequestfrom 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.pyindex 43a20f38b..8ae1e0982 100644--- a/python/composio/core/models/toolkits.py+++ b/python/composio/core/models/toolkits.py@@ -2,13 +2,20 @@ from __future__ import annotationsimport typing as t+import typing_extensions as te+from composio import exceptionsfrom composio.client import HttpClientfrom 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 ConnectedAccountsfrom 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().itemsdiff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.pyindex 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.pyindex b2b0f3adf..9606b4720 100644--- a/python/composio/core/models/triggers.py+++ b/python/composio/core/models/triggers.py@@ -13,7 +13,6 @@ import tracebackimport typing as timport uuidfrom concurrent.futures import ThreadPoolExecutor-from enum import Enumimport requestsimport typing_extensions as te@@ -28,6 +27,12 @@ from composio.client import HttpClientfrom composio.client.types import trigger_instance_upsert_responsefrom composio.core.models.base import Resourcefrom composio.core.models.internal import Internal+from composio.core.models.webhooks import (+ DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS,+ WebhookSubscription,+ WebhookSubscriptions,+ WebhookVersion,+)from composio.core.types import ToolkitVersionParamfrom composio.exceptions import ComposioSDKTimeoutErrorfrom 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 slugdiff --git a/python/composio/core/models/webhooks.py b/python/composio/core/models/webhooks.pynew file mode 100644index 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.pyindex daf9c2606..107ba2050 100644--- a/python/composio/exceptions.py+++ b/python/composio/exceptions.py@@ -5,6 +5,8 @@ Composio exceptions.import difflibimport 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. ACLdiff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex 09286a344..b1ad08a35 100644--- a/python/composio/sdk.py+++ b/python/composio/sdk.py@@ -1,8 +1,11 @@from __future__ import annotations+import loggingimport osimport typing as t+import warnings+import httpximport typing_extensions as tefrom composio import exceptions@@ -10,10 +13,13 @@ from composio.client import DEFAULT_MAX_RETRIES, APIEnvironment, HttpClientfrom composio.core.models import (AuthConfigs,ConnectedAccounts,+ Keyring,+ Logs,Toolkits,ToolRouter,Tools,Triggers,+ Webhooks,)from composio.core.models.base import allow_trackingfrom composio.core.models.mcp import MCP@@ -25,9 +31,14 @@ from composio.core.provider._openai import ()from composio.core.provider.base import BaseProviderfrom composio.core.types import ToolkitVersionParam-from composio.utils.logging import WithLogger+from composio.utils.logging import LogLevel, WithLoggerfrom 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`` inyour 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_providersensitive_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 thesame object and will be removed in a future release."""+ warnings.warn(+ _TOOL_ROUTER_DEPRECATION,+ exceptions.ComposioDeprecationWarning,+ stacklevel=2,+ )return self._sessions@propertydiff --git a/python/composio/utils/logging.py b/python/composio/utils/logging.pyindex 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.levelself._logger.setup(verbosity_level=verbosity_level)self._logging_level = logging._levelToName[self._logger.level]diff --git a/python/pyproject.toml b/python/pyproject.tomlindex 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.pyindex 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.pyindex 9616a8f00..a1d51ccb1 100644--- a/python/tests/test_connected_accounts.py+++ b/python/tests/test_connected_accounts.py@@ -1,10 +1,11 @@import loggingimport time+import typing as timport warningsfrom unittest.mock import Mock, patchimport pytest-from composio_client import omit+from composio_client import BadRequestError, ConflictError, omitfrom composio import exceptionsfrom composio.core.models.connected_accounts import (@@ -300,7 +301,96 @@ class TestConnectedAccounts:connected_accounts.update_statusis 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) == 1message = 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 = emptyconnected_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) == 1diff --git a/python/tests/test_experimental_custom_toolkits.py b/python/tests/test_experimental_custom_toolkits.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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 Noneassert 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.pynew file mode 100644index 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 paramsdiff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex 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_clientassert 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.pynew file mode 100644index 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.pyindex 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_subscriptionresult = 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_subscriptiondef 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_subscriptionresult = 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_subscriptiondef test_set_webhook_subscription_rejects_empty_events(self, triggers):diff --git a/python/tests/test_webhooks.py b/python/tests/test_webhooks.pynew file mode 100644index 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.lockindex b49d3f40f..9badb3657 100644--- a/uv.lock+++ b/uv.lock@@ -1,5 +1,5 @@version = 1-revision = 2+revision = 3requires-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" },