Skip to content

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

Chore: Update client dependencies and types for triggers (#2150)

Musthaq Ahamad97c4138cbb05
diff --git a/.changeset/brown-months-visit.md b/.changeset/brown-months-visit.md
new file mode 100644
index 000000000..9fe36b5f1
--- /dev/null
+++ b/.changeset/brown-months-visit.md
@@ -0,0 +1,5 @@
+---
+'@composio/core': patch
+---
+
+Update composio client version and add support for toolkit version in fetching trigger types
diff --git a/.github/workflows/py.test.yml b/.github/workflows/py.test.yml
index 453897c0a..ee0f67209 100644
--- a/.github/workflows/py.test.yml
+++ b/.github/workflows/py.test.yml
@@ -213,8 +213,10 @@ jobs:
working-directory: ./python
run: |
echo "🧪 Running Integration Tests..."
- uv run pytest composio/integration_test/ -v --tb=short --maxfail=3
- timeout-minutes: 15
+ # Run with per-test timeout of 2 minutes and overall timeout
+ # pytest-timeout should be installed via pyproject.toml dev dependencies
+ uv run pytest composio/integration_test/ -v --tb=short --maxfail=3 --timeout=120 --timeout-method=thread
+ timeout-minutes: 10
- name: Upload Test Results
if: always()
diff --git a/fern/pages/src/triggers/using-triggers.mdx b/fern/pages/src/triggers/using-triggers.mdx
index fdfb1e822..42f124478 100644
--- a/fern/pages/src/triggers/using-triggers.mdx
+++ b/fern/pages/src/triggers/using-triggers.mdx
@@ -53,7 +53,8 @@ Some triggers require additional configuration. The dashboard will prompt you fo
</Frame>
### Using SDK
-Create triggers programmatically by providing the trigger type and any required configuration.
+Create triggers programmatically by providing the trigger type and any required configuration. The trigger instance will be created using the toolkit version configured during Composio initialization (defaults to `'latest'`).
+
<CodeGroup>
<SnippetCode
src="fern/snippets/triggers/python/triggers.py"
@@ -74,6 +75,10 @@ Create triggers programmatically by providing the trigger type and any required
/>
</CodeGroup>
+<Note>
+To use a specific toolkit version when creating triggers, configure `toolkitVersions` during initialization. See [Toolkit Versioning](/docs/toolkit-versioning) for more details.
+</Note>
+
## Subscribing to triggers
@@ -211,8 +216,4 @@ await composio.triggers.enable('ti_abcd123');
## Troubleshooting
-View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).
-
-```
-
-```
+View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).
\ No newline at end of file
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 68da5715d..ba72c0d4c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -13,8 +13,8 @@ catalogs:
specifier: ^4.20250917.0
version: 4.20250917.0
'@composio/client':
- specifier: 0.1.0-alpha.38
- version: 0.1.0-alpha.38
+ specifier: 0.1.0-alpha.40
+ version: 0.1.0-alpha.40
ai:
specifier: 5.0.44
version: 5.0.44
@@ -442,16 +442,16 @@ importers:
version: link:../../packages/providers/llamaindex
'@llamaindex/openai':
specifier: ^0.4.20
- version: 0.4.20(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
+ version: 0.4.20(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
'@llamaindex/workflow':
specifier: ^1.1.24
dotenv:
specifier: ^16.4.1
version: 16.6.1
llamaindex:
specifier: ^0.12.0
devDependencies:
'@types/bun':
specifier: ^1.2.9
@@ -711,7 +711,7 @@ importers:
version: 1.0.0-alpha.1
'@composio/client':
specifier: 'catalog:'
- version: 0.1.0-alpha.38
+ version: 0.1.0-alpha.40
'@composio/core':
specifier: workspace:*
version: link:../core
@@ -805,7 +805,7 @@ importers:
dependencies:
'@composio/client':
specifier: 'catalog:'
- version: 0.1.0-alpha.38
+ version: 0.1.0-alpha.40
'@composio/json-schema-to-zod':
specifier: workspace:*
version: link:../json-schema-to-zod
@@ -986,7 +986,7 @@ importers:
dependencies:
llamaindex:
specifier: ^0.12.0
devDependencies:
'@composio/core':
specifier: workspace:*
@@ -1399,8 +1399,8 @@ packages:
'@cloudflare/[email protected]':
resolution: {integrity: sha512-Lsn9dZoRYZZCXXHZNa50cMP8kWhQZG9M7WjxNSiXFzC8bk4Wh/0SYYo4YINxEjEt6h2o69LmAhFaJ+qgaJTh8Q==}
- '@composio/[email protected]':
- resolution: {integrity: sha512-+Gm5EQdFCu408YqPb9rKdVK7QD9eLS5wJTeYw1QH9eA6hfLmTBKVHFLc32tbLlY9nFwmClyF7KIB6y4NUfYcQw==}
+ '@composio/[email protected]':
+ resolution: {integrity: sha512-xkd+LseCiuFLxiXXtjFgON0bO4M/1AsBQD4omhf2nl5tXJI0sXj72wCf1EXhT2jIu5pgJqJ4H64ZzwoM0fHDvg==}
'@composio/[email protected]':
resolution: {integrity: sha512-IpbfST0SSs/CEv+PIf6+EL0feNuJhQyUrOHJLPge8NhyLLrCyVqvujRIPyRUUjy0NDsked/Mm5VpJmYM6OACbg==}
@@ -7334,7 +7334,7 @@ snapshots:
'@cloudflare/[email protected]': {}
- '@composio/[email protected]': {}
+ '@composio/[email protected]': {}
'@composio/[email protected]': {}
@@ -8203,15 +8203,6 @@ snapshots:
tree-sitter: 0.22.4
web-tree-sitter: 0.24.7
- dependencies:
- '@llamaindex/core': 0.6.22
- '@llamaindex/env': 0.1.30
- transitivePeerDependencies:
- - ws
- - zod
-
dependencies:
'@llamaindex/core': 0.6.22
@@ -8229,13 +8220,13 @@ snapshots:
rxjs: 7.8.2
zod: 4.1.12
optionalDependencies:
'@modelcontextprotocol/sdk': 1.18.0
hono: 4.9.7
rxjs: 7.8.2
- zod: 3.25.76
+ zod: 4.1.12
dependencies:
@@ -8250,11 +8241,11 @@ snapshots:
- rxjs
- zod
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
transitivePeerDependencies:
- '@modelcontextprotocol/sdk'
- hono
@@ -11516,34 +11507,12 @@ snapshots:
rfdc: 1.4.1
wrap-ansi: 9.0.0
- dependencies:
- '@llamaindex/core': 0.6.22
- '@llamaindex/env': 0.1.30
- '@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
- '@types/lodash': 4.17.20
- '@types/node': 24.6.2
- lodash: 4.17.21
- magic-bytes.js: 1.12.1
- transitivePeerDependencies:
- - '@huggingface/transformers'
- - '@modelcontextprotocol/sdk'
- - gpt-tokenizer
- - hono
- - next
- - p-retry
- - rxjs
- - tree-sitter
- - web-tree-sitter
- - zod
-
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
'@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])
'@types/lodash': 4.17.20
'@types/node': 24.6.2
lodash: 4.17.21
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 3d0f89f4d..64ac5db4d 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -15,7 +15,7 @@ packages:
catalog:
'@cloudflare/vitest-pool-workers': ^0.9.2
'@cloudflare/workers-types': ^4.20250917.0
- '@composio/client': 0.1.0-alpha.38
+ '@composio/client': 0.1.0-alpha.40
ai: 5.0.44
openai: ^5.20.3
tsup: ^8.5.0
diff --git a/python/composio/core/models/_telemetry.py b/python/composio/core/models/_telemetry.py
index dadd687b2..1c8e18e11 100644
--- a/python/composio/core/models/_telemetry.py
+++ b/python/composio/core/models/_telemetry.py
@@ -123,25 +123,34 @@ def _setup():
def _teardown(queue: EventQueue, event: tr.Event, thread: tr.Thread):
- while queue.qsize():
+ # Wait max 2 seconds for queue to empty
+ deadline = time.time() + 2.0
+ while queue.qsize() and time.time() < deadline:
time.sleep(0.1)
event.set()
- thread.join()
+ # Join with timeout to prevent infinite waiting
+ thread.join(timeout=3.0)
def _push(event: Event):
- _ = (
- httpx.post(
- url=METRIC_ENDPOINT,
- json=[event[1]],
- )
- if event[0] == "metric"
- else httpx.post(
- url=ERROR_ENDPOINT,
- json=event[1],
+ try:
+ _ = (
+ httpx.post(
+ url=METRIC_ENDPOINT,
+ json=[event[1]],
+ timeout=2.0, # 2 second timeout to prevent hanging
+ )
+ if event[0] == "metric"
+ else httpx.post(
+ url=ERROR_ENDPOINT,
+ json=event[1],
+ timeout=2.0, # 2 second timeout to prevent hanging
+ )
)
- )
+ except (httpx.TimeoutException, httpx.HTTPError, Exception):
+ # Silently fail - telemetry shouldn't break the application
+ pass
def _thread_loop(queue: EventQueue, event: tr.Event):
diff --git a/python/composio/core/models/triggers.py b/python/composio/core/models/triggers.py
index 413fbc842..04b724828 100644
--- a/python/composio/core/models/triggers.py
+++ b/python/composio/core/models/triggers.py
@@ -9,6 +9,7 @@ import uuid
from concurrent.futures import ThreadPoolExecutor
from unittest import mock
+from composio_client.types import TriggersTypeRetrieveResponse
import typing_extensions as te
from composio_client import omit
from pysher import Pusher
@@ -645,7 +646,6 @@ class Triggers(Resource):
self._client = client
self._toolkit_versions = toolkit_versions
self.list_enum = self._client.triggers_types.retrieve_enum
- self.get_type = self._client.triggers_types.retrieve
self.delete = self._client.trigger_instances.manage.delete
self.enable = functools.partial(
self._client.trigger_instances.manage.update,
@@ -656,6 +656,18 @@ class Triggers(Resource):
status="disable",
)
+ def get_type(self, slug: str) -> TriggersTypeRetrieveResponse:
+ """
+ Get a trigger type by its slug
+ Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version
+
+ :param slug: The slug of the trigger type
+ :return: The trigger type
+ """
+ return self._client.triggers_types.retrieve(
+ slug=slug, toolkit_versions=none_to_omit(self._toolkit_versions)
+ )
+
def list_active(
self,
trigger_ids: t.Optional[list[str]] = None,
@@ -758,6 +770,7 @@ class Triggers(Resource):
return self._client.trigger_instances.upsert(
slug=slug,
connected_account_id=connected_account_id,
+ toolkit_versions=self._toolkit_versions,
body_trigger_config_1=(
trigger_config if trigger_config is not None else omit
),
diff --git a/python/composio/integration_test/conftest.py b/python/composio/integration_test/conftest.py
index 433dcb75e..48441fd0a 100644
--- a/python/composio/integration_test/conftest.py
+++ b/python/composio/integration_test/conftest.py
@@ -91,3 +91,31 @@ def sample_mcp_config_data():
def test_user_id():
"""Provide a consistent test user ID."""
return "pytest_integration_user_123"
+
+
+# Track created resources for cleanup
+_created_mcp_servers = []
+
+
+def mcp_server_cleanup(composio_client):
+ """Fixture to track and cleanup MCP servers created during tests."""
+ created_servers = []
+
+ yield created_servers
+
+ # Cleanup after test
+ for server_id in created_servers:
+ try:
+ composio_client.mcp.delete(server_id)
+ print(f"✅ Cleaned up MCP server: {server_id}")
+ except Exception as e:
+ print(f"⚠️ Failed to cleanup MCP server {server_id}: {e}")
+
+
+def pytest_configure(config):
+ """Configure pytest with custom settings."""
+ # Add timeout marker
+ config.addinivalue_line(
+ "markers", "timeout: mark test to run with a specific timeout"
+ )
diff --git a/python/composio/integration_test/pytest.ini b/python/composio/integration_test/pytest.ini
index 5e5be929d..3f0a47c63 100644
--- a/python/composio/integration_test/pytest.ini
+++ b/python/composio/integration_test/pytest.ini
@@ -6,4 +6,11 @@ python_files = test_*.py
python_classes = Test*
python_functions = test_*
-addopts = -v --tb=short
+# Add timeout and other options
+# --timeout=120: Each test gets max 2 minutes
+# --timeout-method=thread: Use thread-based timeout (works cross-platform)
+addopts = -v --tb=short --timeout=120 --timeout-method=thread
+
+markers =
+ slow: marks tests as slow (deselect with '-m "not slow"')
+ integration: marks tests as integration tests
diff --git a/python/composio/integration_test/test_mcp.py b/python/composio/integration_test/test_mcp.py
index c8595ba31..ce1bfd0a0 100644
--- a/python/composio/integration_test/test_mcp.py
+++ b/python/composio/integration_test/test_mcp.py
@@ -383,27 +383,27 @@ class TestMCPNoAuthToolkits:
mcp_url = server_instance["url"]
try:
- # Test with SSE-appropriate headers
+ # Just verify the URL is valid and endpoint exists
+ # Don't try to read the stream as SSE endpoints can hang indefinitely
headers = {
"Accept": "text/event-stream, application/json, */*",
"Cache-Control": "no-cache",
"User-Agent": "Composio-Python-MCP-Test",
}
- response = requests.get(mcp_url, headers=headers, timeout=5, stream=True)
+ # Use HEAD request if supported, otherwise quick GET with immediate close
+ response = requests.head(mcp_url, headers=headers, timeout=3)
+
+ if response.status_code == 405: # Method not allowed for HEAD
+ # Try GET but immediately close without reading stream
+ response = requests.get(
+ mcp_url, headers=headers, timeout=3, stream=True
+ )
+ response.close() # Close immediately without reading
print("✅ MCP URL is accessible!")
print(f" Status Code: {response.status_code}")
- print(f" Content-Type: {response.headers.get('Content-Type', 'N/A')}")
-
- # Try to read first event
- try:
- chunk = next(
- response.iter_content(chunk_size=1024, decode_unicode=True)
- )
- print(f" First Event: {chunk.strip()[:100]}...")
- except StopIteration:
- print(" No initial content received")
+ print(f" URL: {mcp_url[:50]}...")
except requests.exceptions.Timeout:
print("⚠️ MCP URL timeout (normal for SSE endpoints)")
diff --git a/python/providers/anthropic/pyproject.toml b/python/providers/anthropic/pyproject.toml
index 1e7e92bd9..568321a90 100644
--- a/python/providers/anthropic/pyproject.toml
+++ b/python/providers/anthropic/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-anthropic"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your Anthropic LLMs."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/python/providers/anthropic/setup.py b/python/providers/anthropic/setup.py
index 9d0253803..a2010ad83 100644
--- a/python/providers/anthropic/setup.py
+++ b/python/providers/anthropic/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_anthropic",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Anthropic LLMs.",
diff --git a/python/providers/autogen/pyproject.toml b/python/providers/autogen/pyproject.toml
index 32d79e29b..3eec3f916 100644
--- a/python/providers/autogen/pyproject.toml
+++ b/python/providers/autogen/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-autogen"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your autogen agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/autogen/setup.py b/python/providers/autogen/setup.py
index ca60e34b7..6247fd8a2 100644
--- a/python/providers/autogen/setup.py
+++ b/python/providers/autogen/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_autogen",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Autogen agent.",
diff --git a/python/providers/crewai/pyproject.toml b/python/providers/crewai/pyproject.toml
index 63e3771d1..d8bbaaf7c 100644
--- a/python/providers/crewai/pyproject.toml
+++ b/python/providers/crewai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-crewai"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your CrewAI agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/crewai/setup.py b/python/providers/crewai/setup.py
index b9b36e502..cf43c4b3a 100644
--- a/python/providers/crewai/setup.py
+++ b/python/providers/crewai/setup.py
@@ -6,7 +6,7 @@ from setuptools import setup
setup(
name="composio_crewai",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your CrewAI agent.",
diff --git a/python/providers/gemini/pyproject.toml b/python/providers/gemini/pyproject.toml
index 6a93bc062..c38425621 100644
--- a/python/providers/gemini/pyproject.toml
+++ b/python/providers/gemini/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-gemini"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your Gemini agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/gemini/setup.py b/python/providers/gemini/setup.py
index d935e3ad7..1fe814561 100644
--- a/python/providers/gemini/setup.py
+++ b/python/providers/gemini/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_gemini",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Gemini agent.",
diff --git a/python/providers/google/pyproject.toml b/python/providers/google/pyproject.toml
index 5641eb262..69ec0b54a 100644
--- a/python/providers/google/pyproject.toml
+++ b/python/providers/google/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google/setup.py b/python/providers/google/setup.py
index 00fb19fe7..3be7c0f03 100644
--- a/python/providers/google/setup.py
+++ b/python/providers/google/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/google_adk/pyproject.toml b/python/providers/google_adk/pyproject.toml
index ddb54da3a..04e938b98 100644
--- a/python/providers/google_adk/pyproject.toml
+++ b/python/providers/google_adk/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google-adk"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/google_adk/setup.py b/python/providers/google_adk/setup.py
index aa1ddd60c..238a6087d 100644
--- a/python/providers/google_adk/setup.py
+++ b/python/providers/google_adk/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_google_adk",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
diff --git a/python/providers/langchain/pyproject.toml b/python/providers/langchain/pyproject.toml
index 4797bd24b..4110e72c8 100644
--- a/python/providers/langchain/pyproject.toml
+++ b/python/providers/langchain/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langchain"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your Langchain agent."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langchain/setup.py b/python/providers/langchain/setup.py
index 1be5ce475..ff08b2454 100644
--- a/python/providers/langchain/setup.py
+++ b/python/providers/langchain/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langchain",
- version="0.9.1",
+ version="0.9.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your Langchain agent.",
diff --git a/python/providers/langgraph/pyproject.toml b/python/providers/langgraph/pyproject.toml
index 31aa43991..cfba28068 100644
--- a/python/providers/langgraph/pyproject.toml
+++ b/python/providers/langgraph/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langgraph"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get array of tools with LangGraph Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/langgraph/setup.py b/python/providers/langgraph/setup.py
index a126f5ac1..39aa2df89 100644
--- a/python/providers/langgraph/setup.py
+++ b/python/providers/langgraph/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_langgraph",
- version="0.9.1",
+ version="0.9.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LangGraph Agent Workflows",
diff --git a/python/providers/llamaindex/pyproject.toml b/python/providers/llamaindex/pyproject.toml
index 1e52f7dbf..52f6edb38 100644
--- a/python/providers/llamaindex/pyproject.toml
+++ b/python/providers/llamaindex/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-llamaindex"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get array of tools with LlamaIndex Agent Workflows."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/llamaindex/setup.py b/python/providers/llamaindex/setup.py
index c691ac97e..de6829492 100644
--- a/python/providers/llamaindex/setup.py
+++ b/python/providers/llamaindex/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_llamaindex",
- version="0.9.1",
+ version="0.9.2",
author="composio",
author_email="[email protected]",
description="Use Composio to get array of tools with LlamaIndex Agent Workflows",
diff --git a/python/providers/openai/pyproject.toml b/python/providers/openai/pyproject.toml
index b1408b285..707921fc5 100644
--- a/python/providers/openai/pyproject.toml
+++ b/python/providers/openai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get an array of tools with your OpenAI Function Call."
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai/setup.py b/python/providers/openai/setup.py
index 6f40216ee..cb60dd7ed 100644
--- a/python/providers/openai/setup.py
+++ b/python/providers/openai/setup.py
@@ -8,7 +8,7 @@ from setuptools import setup
setup(
name="composio_openai",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get an array of tools with your OpenAI Function Call.",
diff --git a/python/providers/openai_agents/pyproject.toml b/python/providers/openai_agents/pyproject.toml
index a82eafb6c..235d7834b 100644
--- a/python/providers/openai_agents/pyproject.toml
+++ b/python/providers/openai_agents/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai-agents"
-version = "0.9.1"
+version = "0.9.2"
description = "Use Composio to get array of strongly typed tools for OpenAI Agents"
readme = "README.md"
requires-python = ">=3.9,<4"
diff --git a/python/providers/openai_agents/setup.py b/python/providers/openai_agents/setup.py
index 706ceafab..7c6bae61d 100644
--- a/python/providers/openai_agents/setup.py
+++ b/python/providers/openai_agents/setup.py
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
setup(
name="composio_openai_agents",
- version="0.9.1",
+ version="0.9.2",
author="Composio",
author_email="[email protected]",
description="Use Composio to get array of strongly typed tools for OpenAI Agents",
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 7dddcedc9..39284bfa2 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -1,13 +1,13 @@
[project]
name = "composio"
-version = "0.9.1"
+version = "0.9.2"
description = "SDK for integrating Composio with your applications."
readme = "README.md"
requires-python = ">=3.10,<4"
dependencies = [
"pysher>=1.0.8",
"pydantic>=2.6.4",
- "composio-client>=1.11.0",
+ "composio-client>=1.13.0",
"typing-extensions>=4.0.0",
"openai",
]
@@ -22,6 +22,9 @@ dev = [
"composio",
"nox>=2025.5.1",
"pytest>=8.4.0",
+ "pytest-timeout>=2.2.0",
+ "pytest-mock>=3.12.0",
+ "requests>=2.31.0",
"ruff>=0.11.13",
# Langchain provider demo
"langchain_openai",
diff --git a/python/tests/test_triggers.py b/python/tests/test_triggers.py
new file mode 100644
index 000000000..4a4053423
--- /dev/null
+++ b/python/tests/test_triggers.py
@@ -0,0 +1,425 @@
+"""Tests for Triggers class."""
+
+import pytest
+from unittest.mock import Mock, patch
+from composio_client import omit
+from composio.core.models.triggers import Triggers
+from composio import exceptions
+
+
+class TestTriggers:
+ """Test cases for Triggers class."""
+
+ @pytest.fixture
+ def mock_client(self):
+ """Create a mock HTTP client."""
+ client = Mock()
+ client.triggers_types = Mock()
+ client.trigger_instances = Mock()
+ client.trigger_instances.manage = Mock()
+ client.connected_accounts = Mock()
+ return client
+
+ @pytest.fixture
+ def triggers(self, mock_client):
+ """Create a Triggers instance with default toolkit versions."""
+ return Triggers(client=mock_client)
+
+ @pytest.fixture
+ def triggers_with_versions(self, mock_client):
+ """Create a Triggers instance with custom toolkit versions."""
+ return Triggers(
+ client=mock_client,
+ toolkit_versions={"github": "12082025_00", "slack": "10082025_01"},
+ )
+
+ @pytest.fixture
+ def mock_trigger_type(self):
+ """Mock trigger type response."""
+ mock_type = Mock()
+ mock_type.slug = "GITHUB_COMMIT_EVENT"
+ mock_type.name = "GitHub Commit Event"
+ mock_type.description = "Triggered when a commit is pushed"
+ mock_type.toolkit = Mock()
+ mock_type.toolkit.slug = "github"
+ mock_type.toolkit.name = "GitHub"
+ return mock_type
+
+ @pytest.fixture
+ def mock_trigger_instances(self):
+ """Mock trigger instances list response."""
+ mock_response = Mock()
+ mock_response.items = [
+ Mock(
+ id="trigger-1",
+ connected_account_id="conn-123",
+ disabled_at=None,
+ state={"lastRun": "2024-01-01T00:00:00Z"},
+ trigger_config={"webhook_url": "https://example.com/webhook"},
+ trigger_name="GITHUB_COMMIT_EVENT",
+ updated_at="2024-01-01T00:00:00Z",
+ trigger_data='{"event":"push"}',
+ ),
+ ]
+ mock_response.next_cursor = None
+ mock_response.total_pages = 1
+ return mock_response
+
+ def test_init_with_default_versions(self, mock_client):
+ """Test Triggers initialization with default toolkit versions."""
+ triggers = Triggers(client=mock_client)
+
+ assert triggers._client == mock_client
+ assert triggers._toolkit_versions is None
+ assert callable(triggers.list_enum)
+ assert callable(triggers.delete)
+ assert callable(triggers.enable)
+ assert callable(triggers.disable)
+
+ def test_init_with_custom_versions(self, mock_client):
+ """Test Triggers initialization with custom toolkit versions."""
+ custom_versions = {"github": "12082025_00", "slack": "10082025_01"}
+ triggers = Triggers(client=mock_client, toolkit_versions=custom_versions)
+
+ assert triggers._toolkit_versions == custom_versions
+
+ def test_get_type_with_default_versions(
+ self, triggers, mock_client, mock_trigger_type
+ ):
+ """Test get_type with default toolkit versions."""
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+
+ result = triggers.get_type("GITHUB_COMMIT_EVENT")
+
+ # When toolkit_versions is None, it should be converted to omit
+ call_kwargs = mock_client.triggers_types.retrieve.call_args.kwargs
+ assert call_kwargs["slug"] == "GITHUB_COMMIT_EVENT"
+ assert call_kwargs["toolkit_versions"] is omit
+ assert result == mock_trigger_type
+
+ def test_get_type_with_custom_versions(
+ self, triggers_with_versions, mock_client, mock_trigger_type
+ ):
+ """Test get_type with custom toolkit versions."""
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+ custom_versions = {"github": "12082025_00", "slack": "10082025_01"}
+
+ result = triggers_with_versions.get_type("GITHUB_COMMIT_EVENT")
+
+ mock_client.triggers_types.retrieve.assert_called_once_with(
+ slug="GITHUB_COMMIT_EVENT",
+ toolkit_versions=custom_versions,
+ )
+ assert result == mock_trigger_type
+
+ def test_list_active_without_filters(
+ self, triggers, mock_client, mock_trigger_instances
+ ):
+ """Test list_active without any filters."""
+ mock_client.trigger_instances.list_active.return_value = mock_trigger_instances
+
+ result = triggers.list_active()
+
+ mock_client.trigger_instances.list_active.assert_called_once()
+ assert result == mock_trigger_instances
+
+ def test_list_active_with_filters(
+ self, triggers, mock_client, mock_trigger_instances
+ ):
+ """Test list_active with filters."""
+ mock_client.trigger_instances.list_active.return_value = mock_trigger_instances
+
+ result = triggers.list_active(
+ trigger_ids=["trigger-1"],
+ trigger_names=["GITHUB_COMMIT_EVENT"],
+ auth_config_ids=["auth-123"],
+ connected_account_ids=["conn-123"],
+ show_disabled=False,
+ limit=10,
+ page=1,
+ )
+
+ mock_client.trigger_instances.list_active.assert_called_once()
+ call_kwargs = mock_client.trigger_instances.list_active.call_args.kwargs
+ assert call_kwargs["query_trigger_ids_1"] == ["trigger-1"]
+ assert call_kwargs["query_trigger_names_1"] == ["GITHUB_COMMIT_EVENT"]
+ assert call_kwargs["query_auth_config_ids_1"] == ["auth-123"]
+ assert call_kwargs["query_connected_account_ids_1"] == ["conn-123"]
+ assert call_kwargs["query_show_disabled_1"] is False
+ assert call_kwargs["limit"] == 10
+ assert call_kwargs["page"] == 1
+ assert result == mock_trigger_instances
+
+ def test_list_trigger_types_without_filters(self, triggers, mock_client):
+ """Test list trigger types without filters."""
+ mock_response = Mock()
+ mock_client.triggers_types.list.return_value = mock_response
+
+ result = triggers.list()
+
+ mock_client.triggers_types.list.assert_called_once()
+ assert result == mock_response
+
+ def test_list_trigger_types_with_filters(self, triggers_with_versions, mock_client):
+ """Test list trigger types with filters and custom versions."""
+ mock_response = Mock()
+ mock_client.triggers_types.list.return_value = mock_response
+ custom_versions = {"github": "12082025_00", "slack": "10082025_01"}
+
+ result = triggers_with_versions.list(
+ cursor="cursor-123",
+ limit=10,
+ toolkit_slugs=["github", "slack"],
+ )
+
+ mock_client.triggers_types.list.assert_called_once()
+ call_kwargs = mock_client.triggers_types.list.call_args.kwargs
+ assert call_kwargs["cursor"] == "cursor-123"
+ assert call_kwargs["limit"] == 10
+ assert call_kwargs["toolkit_slugs"] == ["github", "slack"]
+ assert call_kwargs["toolkit_versions"] == custom_versions
+ assert result == mock_response
+
+ def test_create_with_connected_account_id(self, triggers, mock_client):
+ """Test create trigger with connected_account_id."""
+ mock_response = Mock()
+ mock_response.trigger_id = "trigger-123"
+ mock_client.trigger_instances.upsert.return_value = mock_response
+
+ result = triggers.create(
+ slug="GITHUB_COMMIT_EVENT",
+ connected_account_id="conn-123",
+ trigger_config={"webhook_url": "https://example.com/webhook"},
+ )
+
+ mock_client.trigger_instances.upsert.assert_called_once()
+ call_kwargs = mock_client.trigger_instances.upsert.call_args.kwargs
+ assert call_kwargs["slug"] == "GITHUB_COMMIT_EVENT"
+ assert call_kwargs["connected_account_id"] == "conn-123"
+ assert call_kwargs["body_trigger_config_1"] == {
+ "webhook_url": "https://example.com/webhook"
+ }
+ assert call_kwargs["toolkit_versions"] is None
+ assert result == mock_response
+
+ def test_create_with_user_id(self, triggers, mock_client, mock_trigger_type):
+ """Test create trigger with user_id."""
+ mock_response = Mock()
+ mock_response.trigger_id = "trigger-123"
+ mock_client.trigger_instances.upsert.return_value = mock_response
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+
+ # Mock connected accounts list
+ mock_accounts = Mock()
+ mock_account = Mock()
+ mock_account.id = "conn-456"
+ mock_account.created_at = "2024-01-01T00:00:00Z"
+ mock_accounts.items = [mock_account]
+ mock_client.connected_accounts.list.return_value = mock_accounts
+
+ result = triggers.create(
+ slug="GITHUB_COMMIT_EVENT",
+ user_id="user-123",
+ trigger_config={"webhook_url": "https://example.com/webhook"},
+ )
+
+ # Verify get_type was called to get toolkit
+ # Note: toolkit_versions=None gets converted to omit
+ call_kwargs = mock_client.triggers_types.retrieve.call_args.kwargs
+ assert call_kwargs["slug"] == "GITHUB_COMMIT_EVENT"
+ assert call_kwargs["toolkit_versions"] is omit
+
+ # Verify connected accounts were fetched
+ mock_client.connected_accounts.list.assert_called_once_with(
+ toolkit_slugs=["github"],
+ user_ids=["user-123"],
+ )
+
+ # Verify trigger was created with found connected account
+ mock_client.trigger_instances.upsert.assert_called_once()
+ call_kwargs = mock_client.trigger_instances.upsert.call_args.kwargs
+ assert call_kwargs["connected_account_id"] == "conn-456"
+ assert call_kwargs["toolkit_versions"] is None
+ assert result == mock_response
+
+ def test_create_with_custom_toolkit_versions(
+ self, triggers_with_versions, mock_client
+ ):
+ """Test create trigger with custom toolkit versions."""
+ mock_response = Mock()
+ mock_response.trigger_id = "trigger-123"
+ mock_client.trigger_instances.upsert.return_value = mock_response
+ custom_versions = {"github": "12082025_00", "slack": "10082025_01"}
+
+ result = triggers_with_versions.create(
+ slug="GITHUB_COMMIT_EVENT",
+ connected_account_id="conn-123",
+ trigger_config={"webhook_url": "https://example.com/webhook"},
+ )
+
+ mock_client.trigger_instances.upsert.assert_called_once()
+ call_kwargs = mock_client.trigger_instances.upsert.call_args.kwargs
+ assert call_kwargs["slug"] == "GITHUB_COMMIT_EVENT"
+ assert call_kwargs["connected_account_id"] == "conn-123"
+ assert call_kwargs["body_trigger_config_1"] == {
+ "webhook_url": "https://example.com/webhook"
+ }
+ assert call_kwargs["toolkit_versions"] == custom_versions
+ assert result == mock_response
+
+ def test_create_without_user_id_or_connected_account_raises_error(
+ self, triggers, mock_client
+ ):
+ """Test create trigger without user_id or connected_account_id raises error."""
+ with pytest.raises(exceptions.InvalidParams) as exc_info:
+ triggers.create(
+ slug="GITHUB_COMMIT_EVENT",
+ trigger_config={"webhook_url": "https://example.com/webhook"},
+ )
+
+ assert "please provide valid `connected_account` or `user_id`" in str(
+ exc_info.value
+ )
+
+ def test_create_with_user_id_no_connected_accounts_raises_error(
+ self, triggers, mock_client, mock_trigger_type
+ ):
+ """Test create trigger with user_id but no connected accounts raises error."""
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+
+ # Mock empty connected accounts list
+ mock_accounts = Mock()
+ mock_accounts.items = []
+ mock_client.connected_accounts.list.return_value = mock_accounts
+
+ with pytest.raises(exceptions.NoItemsFound) as exc_info:
+ triggers.create(
+ slug="GITHUB_COMMIT_EVENT",
+ user_id="user-123",
+ )
+
+ assert "No connected accounts found" in str(exc_info.value)
+
+ def test_get_connected_account_for_user(
+ self, triggers, mock_client, mock_trigger_type
+ ):
+ """Test _get_connected_account_for_user method."""
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+
+ # Mock connected accounts
+ mock_accounts = Mock()
+ mock_account1 = Mock()
+ mock_account1.id = "conn-old"
+ mock_account1.created_at = "2024-01-01T00:00:00Z"
+ mock_account2 = Mock()
+ mock_account2.id = "conn-new"
+ mock_account2.created_at = "2024-01-02T00:00:00Z"
+ mock_accounts.items = [mock_account1, mock_account2]
+ mock_client.connected_accounts.list.return_value = mock_accounts
+
+ result = triggers._get_connected_account_for_user(
+ trigger="GITHUB_COMMIT_EVENT",
+ user_id="user-123",
+ )
+
+ # Should return the most recent account
+ assert result == "conn-new"
+
+ def test_get_connected_account_for_user_no_accounts(
+ self, triggers, mock_client, mock_trigger_type
+ ):
+ """Test _get_connected_account_for_user with no accounts raises error."""
+ mock_client.triggers_types.retrieve.return_value = mock_trigger_type
+
+ # Mock empty connected accounts
+ mock_accounts = Mock()
+ mock_accounts.items = []
+ mock_client.connected_accounts.list.return_value = mock_accounts
+
+ with pytest.raises(exceptions.NoItemsFound) as exc_info:
+ triggers._get_connected_account_for_user(
+ trigger="GITHUB_COMMIT_EVENT",
+ user_id="user-123",
+ )
+
+ assert "No connected accounts found" in str(exc_info.value)
+
+ def test_enable_trigger(self, triggers, mock_client):
+ """Test enable trigger."""
+ mock_response = Mock()
+ mock_client.trigger_instances.manage.update.return_value = mock_response
+
+ result = triggers.enable(trigger_id="trigger-123")
+
+ mock_client.trigger_instances.manage.update.assert_called_once_with(
+ trigger_id="trigger-123",
+ status="enable",
+ )
+ assert result == mock_response
+
+ def test_disable_trigger(self, triggers, mock_client):
+ """Test disable trigger."""
+ mock_response = Mock()
+ mock_client.trigger_instances.manage.update.return_value = mock_response
+
+ result = triggers.disable(trigger_id="trigger-123")
+
+ mock_client.trigger_instances.manage.update.assert_called_once_with(
+ trigger_id="trigger-123",
+ status="disable",
+ )
+ assert result == mock_response
+
+ def test_delete_trigger(self, triggers, mock_client):
+ """Test delete trigger."""
+ mock_response = Mock()
+ mock_client.trigger_instances.manage.delete.return_value = mock_response
+
+ result = triggers.delete(trigger_id="trigger-123")
+
+ mock_client.trigger_instances.manage.delete.assert_called_once_with(
+ trigger_id="trigger-123"
+ )
+ assert result == mock_response
+
+ def test_list_enum(self, triggers, mock_client):
+ """Test list_enum method."""
+ mock_response = Mock()
+ mock_response.enum = ["GITHUB_COMMIT_EVENT", "SLACK_MESSAGE_RECEIVED"]
+ mock_client.triggers_types.retrieve_enum.return_value = mock_response
+
+ result = triggers.list_enum()
+
+ mock_client.triggers_types.retrieve_enum.assert_called_once()
+ assert result == mock_response
+
+ def test_subscribe(self, triggers, mock_client):
+ """Test subscribe method."""
+ with patch(
+ "composio.core.models.triggers._SubcriptionBuilder"
+ ) as mock_builder_class:
+ mock_builder = Mock()
+ mock_subscription = Mock()
+ mock_builder.connect.return_value = mock_subscription
+ mock_builder_class.return_value = mock_builder
+
+ result = triggers.subscribe(timeout=20.0)
+
+ mock_builder_class.assert_called_once_with(client=mock_client)
+ mock_builder.connect.assert_called_once_with(timeout=20.0)
+ assert result == mock_subscription
+
+ def test_subscribe_with_default_timeout(self, triggers, mock_client):
+ """Test subscribe method with default timeout."""
+ with patch(
+ "composio.core.models.triggers._SubcriptionBuilder"
+ ) as mock_builder_class:
+ mock_builder = Mock()
+ mock_subscription = Mock()
+ mock_builder.connect.return_value = mock_subscription
+ mock_builder_class.return_value = mock_builder
+
+ result = triggers.subscribe()
+
+ mock_builder.connect.assert_called_once_with(timeout=15.0)
+ assert result == mock_subscription
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index e25be556d..88fcc5c13 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -6,7 +6,7 @@ The `Tools` class provides methods to list, retrieve, and execute tools from var
### get(userId, filters, options?)
-Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration.
+Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration. See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details on version management.
#### Overload 1: Get multiple tools with filters
@@ -61,13 +61,38 @@ const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
### execute(slug, body, modifiers?)
-Executes a given tool with the provided parameters.
+Executes a given tool with the provided parameters manually.
+
+> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if `'latest'` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.
```typescript
-// Execute a Composio API tool
-const result = await composio.tools.execute('HACKERNEWS_GET_USER', {
+// Execute with a pinned version (REQUIRED for workflows and manual execution)
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+ userId: 'default',
+ arguments: { owner: 'composio', repo: 'sdk' },
+ version: '12082025_00', // Specific version required
+});
+
+// Or configure versions at initialization (RECOMMENDED)
+const composio = new Composio({
+ toolkitVersions: {
+ github: '12082025_00',
+ slack: '10082025_01'
+ }
+});
+
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+ userId: 'default',
+ arguments: { owner: 'composio', repo: 'sdk' },
+ // Uses pinned version from initialization
+});
+
+// Execute with dangerouslySkipVersionCheck (NOT recommended for production)
+// This allows using 'latest' version and bypasses version validation
+const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
userId: 'default',
- arguments: { userId: 'pg' },
+ arguments: { channel: '#general', text: 'Hello!' },
+ dangerouslySkipVersionCheck: true, // Skip version validation (use with caution)
});
// Execute with modifiers
@@ -76,6 +101,7 @@ const result = await composio.tools.execute(
{
userId: 'default',
arguments: { owner: 'composio', repo: 'sdk' },
+ version: '12082025_00', // Always specify version
},
{
beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
@@ -96,6 +122,54 @@ const result = await composio.tools.execute(
- `body` (ToolExecuteParams): The parameters to be passed to the tool
- `modifiers` (ExecuteToolModifiers): Optional modifiers to transform the request or response
+#### Version Requirements for Manual Tool Execution
+
+When building workflows that require manually executing tools, **a specific pinned version is mandatory**. Using `'latest'` is not allowed and will throw an error. This strict requirement prevents argument mismatches that can occur when tool schemas change in newer versions.
+
+**Why Version Pinning is Required:**
+- Tool argument schemas can change between versions
+- Using `'latest'` in workflows can cause runtime errors when tools are updated
+- Pinned versions ensure workflow stability and predictability
+- Version validation prevents production issues from schema mismatches
+
+**Three Approaches to Handle Versions:**
+
+**1. Specify a concrete version in the execute call** (Recommended):
+```typescript
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+ userId: 'default',
+ arguments: { owner: 'composio', repo: 'sdk' },
+ version: '12082025_00', // Explicit version for this tool
+});
+```
+
+**2. Configure toolkit versions at initialization** (Recommended for production):
+```typescript
+const composio = new Composio({
+ toolkitVersions: {
+ github: '12082025_00',
+ slack: '10082025_01'
+ }
+});
+
+// Now execute without version parameter - uses pinned version from config
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+ userId: 'default',
+ arguments: { owner: 'composio', repo: 'sdk' },
+});
+```
+
+**3. Use `dangerouslySkipVersionCheck: true`** (NOT recommended for production):
+```typescript
+const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
+ userId: 'default',
+ arguments: { owner: 'composio', repo: 'sdk' },
+ dangerouslySkipVersionCheck: true, // Bypasses version validation and uses 'latest'
+});
+```
+
+> ⚠️ **Warning:** Using `dangerouslySkipVersionCheck: true` bypasses version validation and allows the use of `'latest'` version. This can lead to unexpected behavior and argument mismatches when tool schemas change. **Only use this flag during development or testing.** Always pin specific versions in production environments to ensure workflow stability.
+
**Returns:** Promise<ToolExecuteResponse> - The response from the tool execution
**Throws:**
@@ -322,12 +396,19 @@ interface ToolExecuteParams {
customAuthParams?: CustomAuthParams; // Custom auth parameters
customConnectionData?: CustomConnectionData; // Custom connection data
arguments?: Record<string, unknown>; // Tool arguments
- userId: string; // User ID
- version?: string; // Tool version
+ userId: string; // User ID (required)
+ version?: string; // Tool version (e.g., '12082025_00') - overrides global toolkit version
+ dangerouslySkipVersionCheck?: boolean; // Skip version validation (NOT recommended for production)
text?: string; // Text input
}
```
+**Parameter Details:**
+
+- **`version`** (string, conditionally required): Specifies the toolkit version to use for this tool execution. **Required when manually executing tools** unless a specific version is configured at initialization or `dangerouslySkipVersionCheck` is set to `true`. Using `'latest'` will throw a `ValidationError` to prevent schema mismatches in workflows. Format: `'DDMMYYYY_NN'` (e.g., `'12082025_00'`). See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for more details.
+
+- **`dangerouslySkipVersionCheck`** (boolean, optional): When set to `true`, bypasses version validation during tool execution and allows using `'latest'` version. This is useful for development and testing but **NOT recommended for production** as it can lead to unexpected behavior and argument mismatches when tool schemas change. Always pin specific toolkit versions at initialization or pass a `version` parameter in production environments.
+
### ToolExecuteResponse
```typescript
diff --git a/ts/docs/api/triggers.md b/ts/docs/api/triggers.md
index 20f132211..c6f68fb0e 100644
--- a/ts/docs/api/triggers.md
+++ b/ts/docs/api/triggers.md
@@ -33,7 +33,7 @@ const triggers = await composio.triggers.listActive({
### Create Trigger Instance
-Create a new trigger instance for a specific user and trigger type. If a connected account ID is not provided, the SDK will automatically use the first available connected account for the user and toolkit.
+Create a new trigger instance for a specific user and trigger type. The trigger instance version is determined by the global `toolkitVersions` configuration set during Composio initialization (defaults to `'latest'`). If a connected account ID is not provided, the SDK will automatically use the first available connected account for the user and toolkit.
**With Connected Account ID:**
@@ -78,12 +78,42 @@ const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSA
}
```
+**Behavior:**
+
+- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
+- To use a specific toolkit version for trigger creation, configure `toolkitVersions` when initializing the Composio instance
+- See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
+
**Throws:**
- `ValidationError`: If the provided parameters are invalid
- `ComposioTriggerTypeNotFoundError`: If the trigger type with the given slug is not found
- `ComposioConnectedAccountNotFoundError`: If no connected account is found for the user, or if the specified connected account ID is not found
+**Example with Specific Toolkit Version:**
+
+```typescript
+// Configure toolkit versions at initialization
+const composio = new Composio({
+ apiKey: 'your-api-key',
+ toolkitVersions: {
+ gmail: '12082025_00',
+ github: '10082025_01'
+ }
+});
+
+// Now create will use the configured version for Gmail
+const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSAGE', {
+ connectedAccountId: 'ca_jjYIG9L40LDIS',
+ triggerConfig: {
+ labelIds: 'INBOX',
+ userId: 'me',
+ interval: 60,
+ },
+});
+// This will create the trigger instance using version '12082025_00' for Gmail
+```
+
**Example with Error Handling:**
```typescript
@@ -200,17 +230,83 @@ await composio.triggers.unsubscribe();
### Manage Trigger Types
-List and retrieve available trigger types:
+#### List Trigger Types
+
+List all available trigger types with optional filtering:
```typescript
-// List all trigger types
const triggerTypes = await composio.triggers.listTypes({
- toolkits: ['github']
+ toolkits: ['github'],
+ cursor: 'cursor-string',
+ limit: 10
});
+```
+
+**Parameters:**
+
+- `toolkits` (string[], optional): Filter trigger types by toolkit slugs
+- `cursor` (string, optional): Pagination cursor for fetching the next page
+- `limit` (number, optional): Maximum number of trigger types to return
+
+**Returns:** Promise<TriggersTypeListResponse> - A paginated list of trigger types
-// Get details of a specific trigger type
-const triggerType = await composio.triggers.getType('trigger-slug');
+#### Get Trigger Type
-// Get enum of all available triggers
+Retrieve details of a specific trigger type by its slug. The trigger type version is determined by the global `toolkitVersions` configuration set during Composio initialization.
+
+```typescript
+// Get trigger type using the globally configured toolkit version
+const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
+```
+
+**Parameters:**
+
+- `slug` (string, required): The slug of the trigger type to retrieve
+
+**Returns:** Promise<TriggersTypeRetrieveResponse> - The trigger type object containing details such as:
+
+```typescript
+{
+ slug: string;
+ name: string;
+ description: string;
+ toolkit: {
+ slug: string;
+ name: string;
+ };
+ // ... other trigger type properties
+}
+```
+
+**Behavior:**
+
+- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
+- To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance
+- See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
+
+**Example with Specific Toolkit Version:**
+
+```typescript
+// Configure toolkit versions at initialization
+const composio = new Composio({
+ apiKey: 'your-api-key',
+ toolkitVersions: {
+ gmail: '12082025_00',
+ github: '10082025_01'
+ }
+});
+
+// Now getType will use the configured version for Gmail
+const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
+// This will fetch the trigger type using version '12082025_00' for Gmail
+```
+
+#### Get Trigger Enums
+
+Fetch the list of all available trigger enums:
+
+```typescript
const triggerEnum = await composio.triggers.listEnum();
```
+
+This method returns an enumeration of all available trigger types and is primarily used by the CLI.
diff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.md
index e43854c01..4448c446f 100644
--- a/ts/docs/getting-started.md
+++ b/ts/docs/getting-started.md
@@ -42,7 +42,102 @@ const composio = new Composio({
baseURL: 'https://api.composio.dev', // Optional: Custom API endpoint
allowTracking: true, // Optional: Enable/disable telemetry
provider: new OpenAIProvider(), // Optional: Custom provider
- toolkitVersions: { github: '20250909_00', slack: 'latest' }, // Optional: Toolkit versions
+ toolkitVersions: { github: '12082025_00', slack: 'latest' }, // Optional: Toolkit versions
+});
+```
+
+### Toolkit Versions
+
+Toolkit versions allow you to pin specific versions of tools and triggers, ensuring consistency across your application. By default, Composio uses the `'latest'` version for all toolkits, but you can specify exact versions for production stability.
+
+#### Version Format
+
+Toolkit versions follow the format `DDMMYYYY_NN`, where:
+- `DD` = Day (01-31)
+- `MM` = Month (01-12)
+- `YYYY` = Year
+- `NN` = Version number for that day (00, 01, 02, etc.)
+
+Example: `12082025_00` represents version 00 released on August 12, 2025.
+
+#### Configuration Options
+
+**Option 1: Global Version for All Toolkits**
+
+```typescript
+const composio = new Composio({
+ toolkitVersions: 'latest' // Use latest version for all toolkits
+});
+
+// Or pin a specific version globally
+const composio = new Composio({
+ toolkitVersions: '12082025_00' // All toolkits use this version
+});
+```
+
+**Option 2: Specific Versions per Toolkit (Recommended for Production)**
+
+```typescript
+const composio = new Composio({
+ toolkitVersions: {
+ github: '12082025_00',
+ slack: '10082025_01',
+ gmail: 'latest', // You can mix specific versions with 'latest'
+ }
+});
+```
+
+**Option 3: Using Environment Variables**
+
+You can set toolkit versions using environment variables:
+
+```bash
+# Set specific versions for individual toolkits
+export COMPOSIO_TOOLKIT_VERSION_GITHUB=12082025_00
+export COMPOSIO_TOOLKIT_VERSION_SLACK=10082025_01
+export COMPOSIO_TOOLKIT_VERSION_GMAIL=latest
+```
+
+Then initialize Composio without specifying `toolkitVersions`:
+
+```typescript
+const composio = new Composio({
+ apiKey: 'your-api-key'
+ // Will automatically use environment variables
+});
+```
+
+#### Version Behavior
+
+- **Tools & Triggers:** The toolkit version configuration applies to both tools and triggers
+- **Override Support:** Tools can override the global version for specific operations:
+ - When executing tools: Pass a `version` parameter in the execute call to override the configured version
+- **Defaults:** If no version is specified, the SDK defaults to `'latest'`
+- **Triggers:** Trigger types always use the global toolkit version configured at initialization. To use a specific version for triggers, set it in the `toolkitVersions` configuration when creating the Composio instance.
+
+#### Best Practices
+
+1. **Use `'latest'` for Development:** Get the newest features and improvements automatically
+2. **Pin Versions in Production:** Use specific version numbers to prevent unexpected changes
+3. **Test Before Upgrading:** When moving to a new version, test thoroughly before deploying
+4. **Version Per Toolkit:** Different toolkits can use different versions based on your needs
+
+#### Example: Production Configuration
+
+```typescript
+import { Composio } from '@composio/core';
+
+// Production setup with pinned versions
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ toolkitVersions: {
+ // Pin critical toolkits to stable versions
+ github: '12082025_00',
+ slack: '10082025_01',
+ gmail: '15082025_00',
+ // Use latest for non-critical toolkits
+ hackernews: 'latest'
+ }
});
```
diff --git a/ts/docs/internal/triggers.md b/ts/docs/internal/triggers.md
index 60cee167b..385b3b9e1 100644
--- a/ts/docs/internal/triggers.md
+++ b/ts/docs/internal/triggers.md
@@ -49,6 +49,7 @@ The SDK interacts with the following Composio API endpoints for trigger manageme
- `GET /api/v3/trigger_instances/active` - List active triggers
- `POST /api/v3/trigger_instances/{slug}` - Create/update trigger instance
+ - Includes `toolkit_versions` parameter to specify the toolkit version for the trigger instance (defaults to global configuration)
- `PATCH /api/v3/trigger_instances/manage/{id}` - Update trigger instance
- `DELETE /api/v3/trigger_instances/manage/{id}` - Delete trigger instance
diff --git a/ts/packages/core/src/models/Triggers.ts b/ts/packages/core/src/models/Triggers.ts
index c437fac8c..5ceba5742 100644
--- a/ts/packages/core/src/models/Triggers.ts
+++ b/ts/packages/core/src/models/Triggers.ts
@@ -31,7 +31,7 @@ import {
transformTriggerTypeListResponse,
transformTriggerTypeRetrieveResponse,
} from '../utils/transformers/triggers';
-import { ToolkitVersionParam } from '../types/tool.types';
+import { ToolkitVersion, ToolkitVersionParam } from '../types/tool.types';
import { ComposioConfig } from '../composio';
import { BaseComposioProvider } from '../provider/BaseProvider';
/**
@@ -132,6 +132,7 @@ export class Triggers<TProvider extends BaseComposioProvider<unknown, unknown, u
cause: error,
possibleFixes: [
`Please check the trigger slug`,
+ `Please check the provided version of toolkit has the trigger`,
`Visit the toolkit page to see the available triggers`,
],
});
@@ -199,6 +200,7 @@ export class Triggers<TProvider extends BaseComposioProvider<unknown, unknown, u
const result = await this.client.triggerInstances.upsert(slug, {
connected_account_id: connectedAccountId,
trigger_config: parsedBody.data.triggerConfig,
+ toolkit_versions: this.toolkitVersions,
});
return {
@@ -283,14 +285,17 @@ export class Triggers<TProvider extends BaseComposioProvider<unknown, unknown, u
}
/**
- * Retrieve a trigger type by its slug
+ * Retrieve a trigger type by its slug for the provided version of the app
+ * Use the global toolkit versions param when initializing composio to pass a toolkitversion
*
* @param {string} slug - The slug of the trigger type
- * @param {RequestOptions} options - request options
* @returns {Promise<TriggersTypeRetrieveResponse>} The trigger type object
*/
async getType(slug: string): Promise<TriggersTypeRetrieveResponse> {
- const result = await this.client.triggersTypes.retrieve(slug);
+ const result = await this.client.triggersTypes.retrieve(slug, {
+ // if the version is provided override the global version
+ toolkit_versions: this.toolkitVersions,
+ });
return transformTriggerTypeRetrieveResponse(result);
}
@@ -298,7 +303,6 @@ export class Triggers<TProvider extends BaseComposioProvider<unknown, unknown, u
* Fetches the list of all the available trigger enums
*
* This method is used by the CLI where filters are not required.
- * @param options
* @returns
*/
async listEnum(): Promise<TriggersTypeRetrieveEnumResponse> {
diff --git a/ts/packages/core/test/models/triggers.test.ts b/ts/packages/core/test/models/triggers.test.ts
index 1cf8a5911..500c3110c 100644
--- a/ts/packages/core/test/models/triggers.test.ts
+++ b/ts/packages/core/test/models/triggers.test.ts
@@ -309,7 +309,9 @@ describe('Triggers', () => {
const result = await triggers.create(userId, slug, body);
- expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug);
+ expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug, {
+ toolkit_versions: 'latest',
+ });
expect(mockClient.connectedAccounts.list).toHaveBeenCalledWith({
user_ids: [userId],
toolkit_slugs: [mockTriggerType.toolkit.slug],
@@ -317,6 +319,7 @@ describe('Triggers', () => {
expect(mockClient.triggerInstances.upsert).toHaveBeenCalledWith(slug, {
connected_account_id: body.connectedAccountId,
trigger_config: body.triggerConfig,
+ toolkit_versions: 'latest',
});
expect(result).toEqual({ triggerId: mockTriggerUpsertResponse.trigger_id });
});
@@ -334,6 +337,7 @@ describe('Triggers', () => {
expect(mockClient.triggerInstances.upsert).toHaveBeenCalledWith(slug, {
connected_account_id: 'conn-456',
trigger_config: bodyWithoutConnectedAccount.triggerConfig,
+ toolkit_versions: 'latest',
});
expect(logger.warn).toHaveBeenCalledWith(
`[Warn] Multiple connected accounts found for user ${userId}, using the first one. Pass connectedAccountId to select a specific account.`
@@ -494,13 +498,44 @@ describe('Triggers', () => {
});
describe('getType', () => {
- it('should retrieve a trigger type by slug', async () => {
+ it('should retrieve a trigger type by slug with default global toolkit versions', async () => {
const slug = 'github_webhook';
mockClient.triggersTypes.retrieve.mockResolvedValue(mockTriggerType);
const result = await triggers.getType(slug);
- expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug);
+ expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug, {
+ toolkit_versions: 'latest', // Uses global default
+ });
+ expect(result).toEqual(mockTriggerType);
+ });
+
+ it('should use custom global toolkit versions when configured', async () => {
+ // Create a new triggers instance with custom toolkit versions
+ const customToolkitVersions = { github: '01012025_00', slack: '15012025_01' };
+ const customTriggers = new Triggers(mockClient as unknown as ComposioClient, {
+ toolkitVersions: customToolkitVersions,
+ });
+ const slug = 'github_webhook';
+ mockClient.triggersTypes.retrieve.mockResolvedValue(mockTriggerType);
+
+ const result = await customTriggers.getType(slug);
+
+ expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug, {
+ toolkit_versions: customToolkitVersions, // Uses configured global versions
+ });
+ expect(result).toEqual(mockTriggerType);
+ });
+
+ it('should use "latest" as default when no toolkit versions are configured', async () => {
+ const slug = 'github_webhook';
+ mockClient.triggersTypes.retrieve.mockResolvedValue(mockTriggerType);
+
+ const result = await triggers.getType(slug);
+
+ expect(mockClient.triggersTypes.retrieve).toHaveBeenCalledWith(slug, {
+ toolkit_versions: 'latest', // Default to latest
+ });
expect(result).toEqual(mockTriggerType);
});
});
diff --git a/uv.lock b/uv.lock
index 2a078e431..6729e2edf 100644
--- a/uv.lock
+++ b/uv.lock
@@ -468,7 +468,7 @@ wheels = [
[[package]]
name = "composio"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python" }
dependencies = [
{ name = "composio-client" },
@@ -486,6 +486,9 @@ dev = [
{ name = "langchain-openai" },
{ name = "nox" },
{ name = "pytest" },
+ { name = "pytest-mock" },
+ { name = "pytest-timeout" },
+ { name = "requests" },
{ name = "ruff" },
{ name = "semver" },
{ name = "tomli" },
@@ -494,7 +497,7 @@ dev = [
[package.metadata]
requires-dist = [
- { name = "composio-client", specifier = ">=1.11.0" },
+ { name = "composio-client", specifier = ">=1.13.0" },
{ name = "openai" },
{ name = "pydantic", specifier = ">=2.6.4" },
{ name = "pysher", specifier = ">=1.0.8" },
@@ -509,6 +512,9 @@ dev = [
{ name = "langchain-openai" },
{ name = "nox", specifier = ">=2025.5.1" },
{ name = "pytest", specifier = ">=8.4.0" },
+ { name = "pytest-mock", specifier = ">=3.12.0" },
+ { name = "pytest-timeout", specifier = ">=2.2.0" },
+ { name = "requests", specifier = ">=2.31.0" },
{ name = "ruff", specifier = ">=0.11.13" },
{ name = "semver", specifier = ">=3.0.4" },
{ name = "tomli", specifier = ">=2.2.1" },
@@ -517,7 +523,7 @@ dev = [
[[package]]
name = "composio-anthropic"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/anthropic" }
dependencies = [
{ name = "anthropic" },
@@ -532,7 +538,7 @@ requires-dist = [
[[package]]
name = "composio-client"
-version = "1.11.0"
+version = "1.13.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "anyio" },
@@ -542,14 +548,14 @@ dependencies = [
{ name = "sniffio" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/f7/00/743270d00550134968c6189ea18d66655c7685970876321bc99e8ebcaaad/composio_client-1.11.0.tar.gz", hash = "sha256:1da2e817f24b6d51ae99ab8f54e2d2aa7286e9af811b21886241998589f3e533", size = 169798 }
+sdist = { url = "https://files.pythonhosted.org/packages/e0/fd/44f8efd598a038ebd6ad05351ac56723cb2ade6b45ffd2252a03d3c046be/composio_client-1.13.0.tar.gz", hash = "sha256:5df08f5a1db5973811a11b2778b0d9b3e8e919d60800e1069a39ce7e478ec138", size = 169964 }
wheels = [
- { url = "https://files.pythonhosted.org/packages/d3/11/d25cf9981d6b0697f4e7ad2e467563960ad84be31b3b034ca7d85cb2f470/composio_client-1.11.0-py3-none-any.whl", hash = "sha256:0491a008394d1e36d936d3b8d75341a35334629b23394fa13ef2adda08ae203c", size = 179628 },
+ { url = "https://files.pythonhosted.org/packages/fc/cd/e3c2c6191dc73a6f4d265d5a9c5ab83d120dd2a5be0225a7f396b1c0d614/composio_client-1.13.0-py3-none-any.whl", hash = "sha256:e9471bcb9337c04ee5e9fa0267a1a480dc7d46ec83ed1258d92b5cb7abc7ea6d", size = 179889 },
]
[[package]]
name = "composio-crewai"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/crewai" }
dependencies = [
{ name = "composio" },
@@ -564,7 +570,7 @@ requires-dist = [
[[package]]
name = "composio-gemini"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/gemini" }
dependencies = [
{ name = "composio" },
@@ -579,7 +585,7 @@ requires-dist = [
[[package]]
name = "composio-google"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/google" }
dependencies = [
{ name = "composio" },
@@ -594,7 +600,7 @@ requires-dist = [
[[package]]
name = "composio-google-adk"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/google_adk" }
dependencies = [
{ name = "composio" },
@@ -609,7 +615,7 @@ requires-dist = [
[[package]]
name = "composio-langchain"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/langchain" }
dependencies = [
{ name = "composio" },
@@ -624,7 +630,7 @@ requires-dist = [
[[package]]
name = "composio-openai"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/openai" }
dependencies = [
{ name = "composio" },
@@ -639,7 +645,7 @@ requires-dist = [
[[package]]
name = "composio-openai-agents"
-version = "0.9.1"
+version = "0.9.2"
source = { virtual = "python/providers/openai_agents" }
dependencies = [
{ name = "composio" },
@@ -3147,6 +3153,30 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/29/16/c8a903f4c4dffe7a12843191437d7cd8e32751d5de349d45d3fe69544e87/pytest-8.4.1-py3-none-any.whl", hash = "sha256:539c70ba6fcead8e78eebbf1115e8b589e7565830d7d006a8723f19ac8a0afb7", size = 365474 },
]
+[[package]]
+name = "pytest-mock"
+version = "3.15.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/68/14/eb014d26be205d38ad5ad20d9a80f7d201472e08167f0bb4361e251084a9/pytest_mock-3.15.1.tar.gz", hash = "sha256:1849a238f6f396da19762269de72cb1814ab44416fa73a8686deac10b0d87a0f", size = 34036 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/5a/cc/06253936f4a7fa2e0f48dfe6d851d9c56df896a9ab09ac019d70b760619c/pytest_mock-3.15.1-py3-none-any.whl", hash = "sha256:0a25e2eb88fe5168d535041d09a4529a188176ae608a6d249ee65abc0949630d", size = 10095 },
+]
+
+[[package]]
+name = "pytest-timeout"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/82/4c9ecabab13363e72d880f2fb504c5f750433b2b6f16e99f4ec21ada284c/pytest_timeout-2.4.0.tar.gz", hash = "sha256:7e68e90b01f9eff71332b25001f85c75495fc4e3a836701876183c4bcfd0540a", size = 17973 }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl", hash = "sha256:c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2", size = 14382 },
+]
+
[[package]]
name = "python-dateutil"
version = "2.9.0.post0"