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.

[WIP] Feat: Add versioning support for tools (#1926)

Musthaq Ahamad7077cee688e8
diff --git a/.changeset/red-walls-sniff.md b/.changeset/red-walls-sniff.md
new file mode 100644
index 000000000..238bd3911
--- /dev/null
+++ b/.changeset/red-walls-sniff.md
@@ -0,0 +1,13 @@
+---
+'@composio/core': patch
+'@composio/anthropic': patch
+'@composio/cloudflare': patch
+'@composio/google': patch
+'@composio/langchain': patch
+'@composio/mastra': patch
+'@composio/openai': patch
+'@composio/openai-agents': patch
+'@composio/vercel': patch
+---
+
+Add tool versioning support
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 73fabea22..bb9aff1ff 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -546,6 +546,22 @@ importers:
specifier: ^5.8.3
version: 5.8.3
+ ts/examples/versioning:
+ dependencies:
+ '@composio/core':
+ specifier: workspace:*
+ version: link:../../packages/core
+ dotenv:
+ specifier: ^16.4.1
+ version: 16.6.1
+ devDependencies:
+ '@types/bun':
+ specifier: ^1.2.9
+ version: 1.2.16
+ typescript:
+ specifier: ^5.8.3
+ version: 5.8.3
+
ts/packages/cli:
dependencies:
'@clack/prompts':
@@ -646,8 +662,8 @@ importers:
ts/packages/core:
dependencies:
'@composio/client':
- specifier: 0.1.0-alpha.35
- version: 0.1.0-alpha.35
+ specifier: 0.1.0-alpha.36
+ version: 0.1.0-alpha.36
'@composio/json-schema-to-zod':
specifier: 0.1.15
version: 0.1.15
@@ -1273,8 +1289,8 @@ packages:
'@composio/[email protected]':
resolution: {integrity: sha512-DVPVCMDXzoQn1aUZx38e8s5+gA/J/c6FpVfS1rzUnMKCRSuXXrOoKXFAvoRME5pcaKN2Wjux5ARyvIPBugNoMA==}
- '@composio/[email protected]':
- resolution: {integrity: sha512-Db40bfq4BqVdjWf7JXzXH0zH9LtRPikZkF8+GoVFYRrDJXfHzNkhXIb+7xksCDb0mLww4LEa1cDw8jX5prA3nA==}
+ '@composio/[email protected]':
+ resolution: {integrity: sha512-YRsx5rRWFoT2kyzYTsJ5lDd6dZI2KmkLxdnaQdACc7A/DkFHzhZraSROaYLElYUP+2ScK4WynVU6+IaHzYn2KA==}
'@composio/[email protected]':
resolution: {integrity: sha512-GaeFd60EozDN4zHZUU4mLp+kqO11ZzUyMaljKbdBNHUsq+TYgomWvoZESyUcDqyvqHx+4+V4Smg91s8Rd7bB4Q==}
@@ -7960,7 +7976,7 @@ snapshots:
'@composio/[email protected]': {}
- '@composio/[email protected]': {}
+ '@composio/[email protected]': {}
'@composio/[email protected]':
dependencies:
@@ -11188,6 +11204,14 @@ snapshots:
chai: 5.2.0
tinyrainbow: 2.0.0
+ dependencies:
+ '@vitest/spy': 3.2.4
+ estree-walker: 3.0.3
+ magic-string: 0.30.17
+ optionalDependencies:
+
dependencies:
'@vitest/spy': 3.2.4
@@ -11196,6 +11220,14 @@ snapshots:
optionalDependencies:
+ dependencies:
+ '@vitest/spy': 3.2.4
+ estree-walker: 3.0.3
+ magic-string: 0.30.17
+ optionalDependencies:
+
'@vitest/[email protected]':
dependencies:
tinyrainbow: 2.0.0
@@ -11225,7 +11257,7 @@ snapshots:
sirv: 3.0.1
tinyglobby: 0.2.14
tinyrainbow: 2.0.0
'@vitest/[email protected]':
dependencies:
@@ -14392,7 +14424,7 @@ snapshots:
dependencies:
'@types/chai': 5.2.2
'@vitest/expect': 3.2.4
'@vitest/pretty-format': 3.2.4
'@vitest/runner': 3.2.4
'@vitest/snapshot': 3.2.4
@@ -14476,7 +14508,7 @@ snapshots:
dependencies:
'@types/chai': 5.2.2
'@vitest/expect': 3.2.4
'@vitest/pretty-format': 3.2.4
'@vitest/runner': 3.2.4
'@vitest/snapshot': 3.2.4
diff --git a/python/composio/__init__.py b/python/composio/__init__.py
index fa9adfb03..d05c59572 100644
--- a/python/composio/__init__.py
+++ b/python/composio/__init__.py
@@ -5,6 +5,12 @@ from .core.models.tools import (
schema_modifier,
)
from .sdk import Composio
+from .types import (
+ ToolkitLatestVersion,
+ ToolkitVersion,
+ ToolkitVersionParam,
+ ToolkitVersions,
+)
__all__ = (
"Composio",
@@ -12,4 +18,8 @@ __all__ = (
"before_execute",
"schema_modifier",
"__version__",
+ "ToolkitLatestVersion",
+ "ToolkitVersion",
+ "ToolkitVersions",
+ "ToolkitVersionParam",
)
diff --git a/python/composio/core/models/tools.py b/python/composio/core/models/tools.py
index 4e3a6baa9..4b91c6c28 100644
--- a/python/composio/core/models/tools.py
+++ b/python/composio/core/models/tools.py
@@ -24,6 +24,8 @@ from composio.core.provider.none_agentic import (
NoneAgenticProviderExecuteFn,
)
from composio.exceptions import InvalidParams, NotFoundError
+from composio.types import ToolkitVersionParam
+from composio.utils.toolkit_version import get_toolkit_version
from ._modifiers import (
Modifiers,
@@ -56,6 +58,7 @@ class Tools(Resource, t.Generic[TProvider]):
client: HttpClient,
provider: TProvider,
file_download_dir: t.Optional[str] = None,
+ toolkit_versions: t.Optional[ToolkitVersionParam] = None,
):
"""
Initialize the tools resource.
@@ -63,11 +66,13 @@ class Tools(Resource, t.Generic[TProvider]):
:param client: The client to use for the tools resource.
:param provider: The provider to use for the tools resource.
:param file_download_dir: Output directory for downloadable files
+ :param toolkit_versions: The versions of the toolkits to use. Defaults to 'latest' if not provided.
"""
self._client = client
self._custom_tools = CustomTools(client)
self._tool_schemas: t.Dict[str, Tool] = {}
self._file_helper = FileHelper(client=self._client, outdir=file_download_dir)
+ self._toolkit_versions = toolkit_versions or "latest"
self.custom_tool = self._custom_tools.register
self.provider = provider
@@ -92,7 +97,12 @@ class Tools(Resource, t.Generic[TProvider]):
try:
return t.cast(Tool, self._custom_tools[slug])
except KeyError:
- return t.cast(Tool, self._client.tools.retrieve(tool_slug=slug))
+ return t.cast(
+ Tool,
+ self._client.tools.retrieve(
+ tool_slug=slug, toolkit_versions=self._toolkit_versions
+ ),
+ )
def get_raw_composio_tools(
self,
@@ -116,7 +126,10 @@ class Tools(Resource, t.Generic[TProvider]):
tools_list.extend(custom_tools)
if len(tools):
tools_list.extend(
- self._client.tools.list(tool_slugs=",".join(tools)).items
+ self._client.tools.list(
+ tool_slugs=",".join(tools),
+ toolkit_versions=self._toolkit_versions,
+ ).items
)
# Search tools by toolkit slugs and search term
@@ -129,6 +142,7 @@ class Tools(Resource, t.Generic[TProvider]):
search=search if search else self._client.not_given,
scopes=scopes,
limit=limit,
+ toolkit_versions=self._toolkit_versions,
).items
)
return tools_list
@@ -321,6 +335,7 @@ class Tools(Resource, t.Generic[TProvider]):
user_id: t.Optional[str] = None,
text: t.Optional[str] = None,
version: t.Optional[str] = None,
+ toolkit_versions: t.Optional[ToolkitVersionParam] = None,
) -> ToolExecutionResponse:
"""Execute a tool"""
return t.cast(
@@ -346,6 +361,9 @@ class Tools(Resource, t.Generic[TProvider]):
user_id=user_id if user_id is not None else self._client.not_given,
text=text if text is not None else self._client.not_given,
version=version if version is not None else self._client.not_given,
+ toolkit_versions=toolkit_versions
+ if toolkit_versions is not None
+ else self._client.not_given,
).model_dump(
exclude={
"log_id",
@@ -367,6 +385,7 @@ class Tools(Resource, t.Generic[TProvider]):
user_id: t.Optional[str] = None,
text: t.Optional[str] = None,
version: t.Optional[str] = None,
+ toolkit_versions: t.Optional[ToolkitVersionParam] = None,
modifiers: t.Optional[Modifiers] = None,
) -> ToolExecutionResponse:
"""
@@ -384,16 +403,25 @@ class Tools(Resource, t.Generic[TProvider]):
:param user_id: The ID of the user to execute the tool for.
:param text: The text to pass to the tool.
:param version: The version of the tool to execute.
+ :param toolkit_versions: Toolkit versions to use for execution, overrides the SDK-level configuration.
:param modifiers: The modifiers to apply to the tool.
:return: The response from the tool.
"""
+ # Use provided toolkit_versions or fall back to instance-level versions
+ effective_toolkit_versions = toolkit_versions or self._toolkit_versions
+
tool = self._tool_schemas.get(slug)
if tool is None and self._custom_tools.get(slug=slug) is not None:
tool = self._custom_tools[slug].info
self._tool_schemas[slug] = tool
if tool is None:
- tool = t.cast(Tool, self._client.tools.retrieve(tool_slug=slug))
+ tool = t.cast(
+ Tool,
+ self._client.tools.retrieve(
+ tool_slug=slug, toolkit_versions=effective_toolkit_versions
+ ),
+ )
self._tool_schemas[slug] = tool
if modifiers is not None:
@@ -440,6 +468,7 @@ class Tools(Resource, t.Generic[TProvider]):
user_id=user_id,
text=text,
version=version,
+ toolkit_versions=effective_toolkit_versions,
)
)
response = self._file_helper.substitute_file_downloads(
diff --git a/python/composio/sdk.py b/python/composio/sdk.py
index 3fc2d9c30..f89a01c3f 100644
--- a/python/composio/sdk.py
+++ b/python/composio/sdk.py
@@ -17,7 +17,9 @@ from composio.core.models import (
from composio.core.models.base import allow_tracking
from composio.core.provider import TProvider
from composio.core.provider._openai import OpenAIProvider
+from composio.types import ToolkitVersionParam
from composio.utils.logging import WithLogger
+from composio.utils.toolkit_version import get_toolkit_versions
_DEFAULT_PROVIDER = OpenAIProvider()
@@ -30,6 +32,7 @@ class SDKConfig(te.TypedDict):
max_retries: te.NotRequired[int]
allow_tracking: te.NotRequired[bool]
file_download_dir: te.NotRequired[str]
+ toolkit_versions: te.NotRequired[ToolkitVersionParam]
class Composio(t.Generic[TProvider], WithLogger):
@@ -53,12 +56,19 @@ class Composio(t.Generic[TProvider], WithLogger):
:param base_url: The base URL to use for the SDK.
:param timeout: The timeout to use for the SDK.
:param max_retries: The maximum number of retries to use for the SDK.
+ :param toolkit_versions: The versions of the toolkits to use. Can be:
+ - A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits
+ - A dict mapping toolkit names to specific versions
+ - None to use 'latest' as default
"""
WithLogger.__init__(self)
api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
if not api_key:
raise exceptions.ApiKeyNotProvidedError()
+ # Process toolkit versions
+ toolkit_versions = get_toolkit_versions(kwargs.get("toolkit_versions"))
+
allow_tracking.set(kwargs.get("allow_tracking", True))
self._client = HttpClient(
environment=kwargs.get("environment", "production"),
@@ -73,6 +83,7 @@ class Composio(t.Generic[TProvider], WithLogger):
client=self._client,
provider=self.provider,
file_download_dir=kwargs.get("file_download_dir"),
+ toolkit_versions=toolkit_versions,
)
self.toolkits = Toolkits(client=self._client)
self.triggers = Triggers(client=self._client)
diff --git a/python/composio/types.py b/python/composio/types.py
index 315fc24e3..977c493c1 100644
--- a/python/composio/types.py
+++ b/python/composio/types.py
@@ -1,3 +1,7 @@
+import typing as t
+
+import typing_extensions as te
+
from composio.client.types import Tool
from composio.core.models.connected_accounts import auth_scheme
from composio.core.models.custom_tools import ExecuteRequestFn
@@ -9,7 +13,16 @@ from composio.core.models.tools import (
from composio.core.models.triggers import TriggerEvent
from composio.core.provider.base import TTool, TToolCollection
+# Tool versioning types
+ToolkitLatestVersion = te.Literal["latest"]
+ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"
+ToolkitVersions = t.Dict[str, ToolkitVersion]
+ToolkitVersionParam = t.Union[
+ str, ToolkitVersions, None
+] # String can be any global version
+
__all__ = [
+ # Existing types
"Tool",
"TTool",
"TToolCollection",
@@ -19,4 +32,9 @@ __all__ = [
"TriggerEvent",
"Modifiers",
"auth_scheme",
+ # New tool versioning types
+ "ToolkitLatestVersion",
+ "ToolkitVersion",
+ "ToolkitVersions",
+ "ToolkitVersionParam",
]
diff --git a/python/composio/utils/toolkit_version.py b/python/composio/utils/toolkit_version.py
new file mode 100644
index 000000000..989da8557
--- /dev/null
+++ b/python/composio/utils/toolkit_version.py
@@ -0,0 +1,81 @@
+"""
+Utilities for handling toolkit versions.
+"""
+
+import os
+import typing as t
+
+from composio.types import ToolkitVersion, ToolkitVersionParam, ToolkitVersions
+
+
+def get_toolkit_version(
+ toolkit_slug: str, toolkit_versions: t.Optional[ToolkitVersionParam] = None
+) -> ToolkitVersion:
+ """
+ Gets the version for a specific toolkit based on the provided toolkit versions configuration.
+
+ :param toolkit_slug: The slug/name of the toolkit to get the version for
+ :param toolkit_versions: Optional toolkit versions configuration (string for global version
+ or dict mapping toolkit slugs to versions)
+ :return: The toolkit version to use - either the specific version from config, or 'latest' as fallback
+ """
+ # If toolkit_versions is a string, use it as a global version for all toolkits
+ if isinstance(toolkit_versions, str):
+ return toolkit_versions
+
+ # If toolkit_versions is a dict mapping, look up the specific toolkit version
+ if isinstance(toolkit_versions, dict) and len(toolkit_versions) > 0:
+ return toolkit_versions.get(toolkit_slug, "latest")
+
+ # Else use 'latest'
+ return "latest"
+
+
+def get_toolkit_versions(
+ default_versions: t.Optional[ToolkitVersionParam] = None,
+) -> ToolkitVersionParam:
+ """
+ Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
+
+ Priority order:
+ 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")
+ 2. User-provided toolkit version mappings (default_versions dict)
+ 3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
+ 4. Fallback to 'latest' if no versions are configured
+
+ :param default_versions: Optional default versions configuration (string for global version
+ or dict mapping toolkit names to versions). String can be any version
+ like "latest", "20250906_01", etc.
+ :return: Toolkit versions configuration - either a global version string,
+ toolkit-specific version mapping, or 'latest'
+ """
+ # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits
+ if default_versions and isinstance(default_versions, str):
+ return default_versions
+
+ # Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
+ toolkit_versions_from_env: ToolkitVersions = {}
+ for key, value in os.environ.items():
+ if key.startswith("COMPOSIO_TOOLKIT_VERSION_"):
+ toolkit_name = key.replace("COMPOSIO_TOOLKIT_VERSION_", "")
+ toolkit_versions_from_env[toolkit_name.lower()] = value
+
+ # If the provided default versions is a dict, normalize the keys to be lower case
+ # Use user provided values as overrides
+ user_provided_toolkit_versions: ToolkitVersions = {}
+ if default_versions and isinstance(default_versions, dict):
+ user_provided_toolkit_versions = {
+ key.lower(): value for key, value in default_versions.items()
+ }
+
+ # Final toolkit versions
+ toolkit_versions = {
+ **toolkit_versions_from_env,
+ **user_provided_toolkit_versions,
+ }
+
+ # If the toolkit_versions are empty, use 'latest'
+ if len(toolkit_versions) == 0:
+ return "latest"
+
+ return toolkit_versions
diff --git a/python/providers/anthropic/pyproject.toml b/python/providers/anthropic/pyproject.toml
index 73e603f2a..596456b49 100644
--- a/python/providers/anthropic/pyproject.toml
+++ b/python/providers/anthropic/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-anthropic"
-version = "0.8.10"
+version = "0.8.11"
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 85e1521fe..853a43d60 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.8.10",
+ version="0.8.11",
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 167ce6b1d..5d9544bb9 100644
--- a/python/providers/autogen/pyproject.toml
+++ b/python/providers/autogen/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-autogen"
-version = "0.8.10"
+version = "0.8.11"
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 0bb14f372..53b47a6c2 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.8.10",
+ version="0.8.11",
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 45c2821cc..176f96214 100644
--- a/python/providers/crewai/pyproject.toml
+++ b/python/providers/crewai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-crewai"
-version = "0.8.10"
+version = "0.8.11"
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 fbe67df7e..d30c3bbed 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.8.10",
+ version="0.8.11",
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 3351f680b..0883ea807 100644
--- a/python/providers/gemini/pyproject.toml
+++ b/python/providers/gemini/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-gemini"
-version = "0.8.10"
+version = "0.8.11"
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 460871c79..aea9a448d 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.8.10",
+ version="0.8.11",
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 419d9bfad..cb7f44e30 100644
--- a/python/providers/google/pyproject.toml
+++ b/python/providers/google/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-google"
-version = "0.8.10"
+version = "0.8.11"
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 e38bbc1a8..43c67d511 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.8.10",
+ version="0.8.11",
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 886d09302..ed108d8c3 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.8.10"
+version = "0.8.11"
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 4b5a34789..90bced3b9 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.8.10",
+ version="0.8.11",
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 a84218964..862d8f39d 100644
--- a/python/providers/langchain/pyproject.toml
+++ b/python/providers/langchain/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langchain"
-version = "0.8.10"
+version = "0.8.11"
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 dc78b94b3..cb20142a9 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.8.10",
+ version="0.8.11",
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 2c31c1413..87a35be14 100644
--- a/python/providers/langgraph/pyproject.toml
+++ b/python/providers/langgraph/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-langgraph"
-version = "0.8.10"
+version = "0.8.11"
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 6715fdfb7..8178239c1 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.8.10",
+ version="0.8.11",
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 be2af9073..d700dc131 100644
--- a/python/providers/llamaindex/pyproject.toml
+++ b/python/providers/llamaindex/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-llamaindex"
-version = "0.8.10"
+version = "0.8.11"
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 9ba2de43c..83b7e87df 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.8.10",
+ version="0.8.11",
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 436499fbb..e1170524a 100644
--- a/python/providers/openai/pyproject.toml
+++ b/python/providers/openai/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio-openai"
-version = "0.8.10"
+version = "0.8.11"
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 1026cb6a3..62698e2dc 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.8.10",
+ version="0.8.11",
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 0f95aa329..4fe64e0cb 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.8.10"
+version = "0.8.11"
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 215f0e93d..e06c53561 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.8.10",
+ version="0.8.11",
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 de3d11b33..49988e623 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "composio"
-version = "0.8.12"
+version = "0.8.13"
description = "SDK for integrating Composio with your applications."
readme = "README.md"
requires-python = ">=3.10,<4"
diff --git a/ts/README.md b/ts/README.md
index 7b019a674..b256bc5c3 100644
--- a/ts/README.md
+++ b/ts/README.md
@@ -78,6 +78,9 @@ const tools = await composio.tools.get('default', {
toolkits: ['github'],
});
+// Get a specific tool
+const specificTool = await composio.tools.get('default', 'GITHUB_GET_REPOS');
+
// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
userId: 'default',
@@ -110,6 +113,7 @@ const tools = await composio.tools.get('default', {
toolkits: ['github'],
});
+
// Create a chat completion with the tools
const completion = await openai.chat.completions.create({
model: 'gpt-4',
@@ -294,6 +298,7 @@ For detailed information about both automated and manual release processes, plea
- `COMPOSIO_BASE_URL`: Custom API base URL (optional)
- `COMPOSIO_LOG_LEVEL`: Logging level (silent, error, warn, info, debug)
- `COMPOSIO_DISABLE_TELEMETRY`: Disable telemetry when set to "true"
+- `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>`: Specific version for a toolkit (e.g., `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`)
- `DEVELOPMENT`: Development mode flag
- `CI`: CI environment flag
diff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.md
index 54d259f1f..e25be556d 100644
--- a/ts/docs/api/tools.md
+++ b/ts/docs/api/tools.md
@@ -6,39 +6,58 @@ The `Tools` class provides methods to list, retrieve, and execute tools from var
### get(userId, filters, options?)
-Retrieves tools based on the provided filters.
+Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration.
+
+#### Overload 1: Get multiple tools with filters
```typescript
// Get tools from a specific toolkit
const githubTools = await composio.tools.get('default', {
toolkits: ['github'],
- limit: 10,
+ limit: 10
});
// Get tools with search
const searchTools = await composio.tools.get('default', {
- search: 'user',
+ search: 'user'
+});
+
+// Get tools with schema modifications
+const customizedTools = await composio.tools.get('default', {
+ toolkits: ['github'],
+ limit: 5
+}, {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return { ...schema, description: 'Custom description' };
+ }
});
+```
+**Parameters:**
+- `userId` (string): The user ID to get the tools for
+- `filters` (ToolListParams): Filters object to specify which tools to retrieve
+- `options` (ProviderOptions): Optional provider options including modifiers
+
+#### Overload 2: Get a specific tool by slug
+
+```typescript
// Get a specific tool by slug
const tool = await composio.tools.get('default', 'GITHUB_GET_REPO');
// Get a tool with schema modifications
-const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
- modifySchema: (toolSlug, toolkitSlug, schema) => {
- // Customize the tool schema
- return { ...schema, description: 'Custom description' };
- },
+const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return { ...schema, description: 'Enhanced GitHub repository tool' };
+ }
});
```
**Parameters:**
-
-- `userId` (string): The user ID to get the tools for
-- `filters` (ToolListParams | string): Either a slug string or filters object
+- `userId` (string): The user ID to get the tool for
+- `slug` (string): The slug of the specific tool to fetch
- `options` (ProviderOptions): Optional provider options including modifiers
-**Returns:** The wrapped tools collection, formatted according to the provider
+**Returns:** The wrapped tools collection, formatted according to the provider being used
### execute(slug, body, modifiers?)
@@ -118,48 +137,99 @@ const customTool = await composio.tools.createCustomTool({
**Returns:** Promise<Tool> - The created custom tool
-### getRawComposioTools(query?, modifier?)
+### getRawComposioTools(query, options?)
-Lists all tools available in the Composio SDK including custom tools.
+Lists all tools available in the Composio SDK including custom tools. This method provides direct access to tool data without provider-specific wrapping.
```typescript
-// Get all tools
-const tools = await composio.tools.getRawComposioTools();
+// Get tools from specific toolkits
+const githubTools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ limit: 10
+});
-// Get tools with filters
+// Get specific tools by slug
+const specificTools = await composio.tools.getRawComposioTools({
+ tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
+});
+
+// Get tools from specific toolkits
const githubTools = await composio.tools.getRawComposioTools({
toolkits: ['github'],
- important: true,
+ limit: 10
});
// Get tools with schema transformation
-const tools = await composio.tools.getRawComposioTools({}, (toolSlug, toolkitSlug, tool) => {
- // Add custom properties to tool schema
- return { ...tool, customProperty: 'value' };
+const customizedTools = await composio.tools.getRawComposioTools({
+ toolkits: ['github'],
+ limit: 5
+}, {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return {
+ ...schema,
+ customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
+ tags: [...(schema.tags || []), 'customized']
+ };
+ }
+});
+
+// Search for tools
+const searchResults = await composio.tools.getRawComposioTools({
+ search: 'user management'
});
```
**Parameters:**
-- `query` (ToolListParams): Optional query parameters to filter the tools
-- `modifier` (TransformToolSchemaModifier): Optional function to transform tool schemas
+- `query` (ToolListParams): Query parameters to filter the tools (required)
+- `options` (GetRawComposioToolsOptions): Optional configuration for tool retrieval
+ - `modifySchema` (TransformToolSchemaModifier): Function to transform tool schemas
**Returns:** Promise<ToolList> - List of tools matching the query criteria
-### getRawComposioToolBySlug(slug, modifier?)
+### getRawComposioToolBySlug(slug, options?)
-Retrieves a tool by its Slug.
+Retrieves a specific tool by its slug from the Composio API. This method provides direct access to tool schema and metadata without provider-specific wrapping.
```typescript
-const tool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
+// Get a tool by slug
+const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
+
+// Get a tool with schema transformation
+const customizedTool = await composio.tools.getRawComposioToolBySlug(
+ 'SLACK_SEND_MESSAGE',
+ {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return {
+ ...schema,
+ description: `Enhanced ${schema.description} with custom modifications`,
+ customMetadata: {
+ lastModified: new Date().toISOString(),
+ toolkit: toolkitSlug
+ }
+ };
+ }
+ }
+);
+
+// Access tool properties
+const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
+console.log({
+ slug: githubTool.slug,
+ name: githubTool.name,
+ toolkit: githubTool.toolkit?.name,
+ version: githubTool.version,
+ availableVersions: githubTool.availableVersions
+});
```
**Parameters:**
-- `slug` (string): The ID of the tool to be retrieved
-- `modifier` (TransformToolSchemaModifier): Optional function to transform tool schema
+- `slug` (string): The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
+- `options` (GetRawComposioToolBySlugOptions): Optional configuration for tool retrieval
+ - `modifySchema` (TransformToolSchemaModifier): Function to transform the tool schema
-**Returns:** Promise<Tool> - The tool
+**Returns:** Promise<Tool> - The requested tool with its complete schema and metadata
## Types
@@ -282,3 +352,4 @@ interface CustomToolOptions {
handler: (params: ToolExecuteParams, context: ExecuteMetadata) => Promise<ToolExecuteResponse>; // Handler function
}
```
+
diff --git a/ts/docs/core-concepts.md b/ts/docs/core-concepts.md
index f7ac3b9eb..45c916ec0 100644
--- a/ts/docs/core-concepts.md
+++ b/ts/docs/core-concepts.md
@@ -28,6 +28,7 @@ const tools = await composio.tools.get('default', {
toolkits: ['github'],
});
+
// ❌ This could expose other users' data
const result = await composio.tools.execute('GITHUB_GET_REPO', {
userId: 'default',
@@ -49,6 +50,11 @@ const tools = await composio.tools.get(userId, {
toolkits: ['github'],
});
+// Get tools for a specific user
+const userTools = await composio.tools.get(userId, {
+ toolkits: ['github'],
+});
+
const result = await composio.tools.execute('GITHUB_GET_REPO', {
userId: userId,
arguments: { owner: 'example', repo: 'repo' },
diff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.md
index 03367749f..c737ad162 100644
--- a/ts/docs/getting-started.md
+++ b/ts/docs/getting-started.md
@@ -42,6 +42,7 @@ 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
});
```
diff --git a/ts/examples/tools/src/versioning.ts b/ts/examples/tools/src/versioning.ts
new file mode 100644
index 000000000..77adc6307
--- /dev/null
+++ b/ts/examples/tools/src/versioning.ts
@@ -0,0 +1,124 @@
+import { Composio } from '@composio/core';
+
+const composio = new Composio();
+
+async function demonstrateRawToolFetching() {
+ console.log('=== Raw Composio Tool Fetching Examples ===\n');
+
+ // Example 1: Get a single tool by slug (latest version)
+ console.log('1. Getting latest version of HACKERNEWS_GET_USER:');
+ const latestTool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
+ console.log(`Tool: ${latestTool.name} (v${latestTool.version})`);
+ console.log(`Available versions: ${latestTool.availableVersions?.join(', ')}\n`);
+
+ // Example 2: Get a specific version of a tool
+ console.log('2. Getting specific version of a tool:');
+ try {
+ const specificVersionTool = await composio.tools.getRawComposioToolBySlug(
+ 'HACKERNEWS_GET_USER',
+ '20250909_00' // specific version
+ );
+ console.log(`Tool: ${specificVersionTool.name} (v${specificVersionTool.version})\n`);
+ } catch (error) {
+ console.log('Note: Specific version may not be available, using latest instead\n');
+ }
+
+ // Example 3: Get a tool with schema transformation
+ console.log('3. Getting tool with schema transformation:');
+ const customizedTool = await composio.tools.getRawComposioToolBySlug(
+ 'HACKERNEWS_GET_USER',
+ 'latest',
+ {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return {
+ ...schema,
+ description: `Enhanced ${schema.description} - Modified at ${new Date().toISOString()}`,
+ customMetadata: {
+ toolkit: toolkitSlug,
+ modifiedBy: 'versioning-example',
+ features: ['enhanced-logging', 'custom-validation']
+ }
+ };
+ }
+ }
+ );
+ console.log(`Modified tool description: ${customizedTool.description}`);
+ console.log(`Custom metadata:`, (customizedTool as any).customMetadata);
+ console.log();
+
+ // Example 4: Get multiple tools with filters
+ console.log('4. Getting multiple tools with filters:');
+ const hackerNewsTools = await composio.tools.getRawComposioTools({
+ toolkits: ['hackernews'],
+ limit: 3
+ });
+ console.log(`Found ${hackerNewsTools.length} HackerNews tools:`);
+ hackerNewsTools.forEach(tool => {
+ console.log(`- ${tool.slug}: ${tool.name} (v${tool.version})`);
+ });
+ console.log();
+
+ // Example 5: Get tools with version control
+ console.log('5. Getting tools with version control:');
+ const versionedTools = await composio.tools.getRawComposioTools({
+ toolkits: ['hackernews'],
+ toolkitVersions: 'latest' // or specify specific versions: { hackernews: '20250909_00' }
+ });
+ console.log(`Found ${versionedTools.length} versioned tools:`);
+ versionedTools.forEach(tool => {
+ console.log(`- ${tool.slug} (v${tool.version})`);
+ });
+ console.log();
+
+ // Example 6: Get tools with schema transformation
+ console.log('6. Getting multiple tools with schema transformation:');
+ const enhancedTools = await composio.tools.getRawComposioTools({
+ toolkits: ['hackernews'],
+ limit: 2
+ }, {
+ modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ return {
+ ...schema,
+ tags: [...(schema.tags || []), 'enhanced', 'example'],
+ customProperties: {
+ lastFetched: new Date().toISOString(),
+ exampleUsage: `This tool (${toolSlug}) is from the ${toolkitSlug} toolkit`
+ }
+ };
+ }
+ });
+
+ console.log('Enhanced tools with custom properties:');
+ enhancedTools.forEach(tool => {
+ console.log(`- ${tool.slug}:`);
+ console.log(` Tags: ${tool.tags?.join(', ')}`);
+ console.log(` Custom properties:`, (tool as any).customProperties);
+ });
+ console.log();
+
+ // Example 7: Search for tools
+ console.log('7. Searching for tools:');
+ try {
+ const searchResults = await composio.tools.getRawComposioTools({
+ search: 'user'
+ });
+ console.log(`Found ${searchResults.length} tools matching 'user':`);
+ searchResults.slice(0, 3).forEach(tool => {
+ console.log(`- ${tool.slug}: ${tool.name}`);
+ });
+ } catch (error) {
+ console.log('Search might require additional parameters');
+ }
+ console.log();
+
+ // Example 8: Using the wrapped tools (comparison)
+ console.log('8. Comparison with wrapped tools:');
+ const wrappedTools = await composio.tools.get('default', {
+ tools: ['HACKERNEWS_GET_USER']
+ });
+ console.log('Wrapped tools (provider-specific format):');
+ console.log(typeof wrappedTools, Object.keys(wrappedTools));
+}
+
+// Run the demonstration
+demonstrateRawToolFetching().catch(console.error);
diff --git a/ts/examples/versioning/.env.example b/ts/examples/versioning/.env.example
new file mode 100644
index 000000000..666ba5c77
--- /dev/null
+++ b/ts/examples/versioning/.env.example
@@ -0,0 +1,7 @@
+# Composio API Key - Get it from https://app.composio.dev
+COMPOSIO_API_KEY=your_composio_api_key_here
+COMPOSIO_TOOLKIT_VERSION_HACKERNEWS=20250911_00
+
+# Add other environment variables as needed for your example
+# OPENAI_API_KEY=your_openai_api_key_here
+# ANTHROPIC_API_KEY=your_anthropic_api_key_here
diff --git a/ts/examples/versioning/README.md b/ts/examples/versioning/README.md
new file mode 100644
index 000000000..0550b8595
--- /dev/null
+++ b/ts/examples/versioning/README.md
@@ -0,0 +1,53 @@
+# Versioning Example
+
+This example demonstrates how to use Composio SDK for versioning.
+
+## Setup
+
+1. **Install dependencies:**
+ ```bash
+ pnpm install
+ ```
+
+2. **Configure environment:**
+ ```bash
+ cp .env.example .env
+ ```
+
+ Then edit `.env` and add your API keys:
+ - `COMPOSIO_API_KEY`: Get it from [Composio Dashboard](https://app.composio.dev)
+
+## Running the Example
+
+```bash
+# Run the example
+pnpm start
+
+# Run in development mode (with file watching)
+pnpm dev
+```
+
+## What This Example Does
+
+- Initializes Composio SDK
+- Fetches available tools
+- Demonstrates basic usage patterns
+
+## Customization
+
+Edit `src/index.ts` to:
+- Add specific apps you want to integrate with
+- Implement your business logic
+- Add error handling and logging
+
+## Related Examples
+
+- [OpenAI Example](../openai) - Shows integration with OpenAI
+- [LangChain Example](../langchain) - Shows integration with LangChain
+- [More Examples](../) - Browse all available examples
+
+## Support
+
+- [Documentation](https://docs.composio.dev)
+- [Discord Community](https://discord.gg/composio)
+- [GitHub Issues](https://github.com/composio/composio/issues)
diff --git a/ts/examples/versioning/package.json b/ts/examples/versioning/package.json
new file mode 100644
index 000000000..eb8711c4c
--- /dev/null
+++ b/ts/examples/versioning/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "versioning-example",
+ "private": true,
+ "version": "0.1.0",
+ "description": "Example project for Versioning",
+ "main": "src/index.ts",
+ "scripts": {
+ "start": "bun src/index.ts",
+ "dev": "bun --watch src/index.ts",
+ "test": "echo \"Error: no test specified\" && exit 1"
+ },
+ "keywords": ["composio", "example", "versioning"],
+ "author": "",
+ "license": "ISC",
+ "packageManager": "[email protected]",
+ "dependencies": {
+ "@composio/core": "workspace:*",
+ "dotenv": "^16.4.1"
+ },
+ "devDependencies": {
+ "@types/bun": "^1.2.9",
+ "typescript": "^5.8.3"
+ }
+}
diff --git a/ts/examples/versioning/src/index.ts b/ts/examples/versioning/src/index.ts
new file mode 100644
index 000000000..d93eac858
--- /dev/null
+++ b/ts/examples/versioning/src/index.ts
@@ -0,0 +1,49 @@
+/**
+ * Versioning Example
+ *
+ * This example demonstrates how to use Composio SDK for versioning.
+ *
+ * Prerequisites:
+ * 1. Set up your COMPOSIO_API_KEY in the .env file
+ * 3. Run the example: pnpm start
+ */
+
+import { Composio } from '@composio/core';
+import 'dotenv/config';
+
+/**
+ * Initialize Composio
+ */
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+});
+
+const config = composio.getConfig()
+console.log(JSON.stringify(config, null, 2))
+
+/**
+ * Main function to run the example
+ */
+async function main() {
+ try {
+ console.log('🚀 Starting Versioning Example...');
+
+ // Get available tools
+ const tools = await composio.tools.get('default', {
+ // Specify the apps you want to use
+ toolkits: ['gmail', 'googlecalendar'],
+ limit: 10,
+ });
+
+ console.log(`✅ Found ${tools.length} tools`);
+
+ // TODO: Add your example implementation here
+ console.log('📝 Implement your versioning logic here!');
+
+ } catch (error) {
+ console.error('❌ Error running example:', error);
+ }
+}
+
+// Run the example
+main().catch(console.error);
diff --git a/ts/examples/versioning/tsconfig.json b/ts/examples/versioning/tsconfig.json
new file mode 100644
index 000000000..158c157c8
--- /dev/null
+++ b/ts/examples/versioning/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "ESNext",
+ "module": "ESNext",
+ "declaration": true,
+ "declarationDir": "./dist",
+ "outDir": "./dist",
+ "rootDir": "./src",
+ "strict": true,
+ "esModuleInterop": true,
+ "moduleResolution": "node",
+ "skipLibCheck": true,
+ "resolveJsonModule": true
+ },
+ "include": ["src"]
+}
diff --git a/ts/packages/core/README.md b/ts/packages/core/README.md
index 13bba5158..baeae8679 100644
--- a/ts/packages/core/README.md
+++ b/ts/packages/core/README.md
@@ -288,6 +288,7 @@ Composio supports various authentication schemes:
- `COMPOSIO_BASE_URL`: Custom API base URL
- `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)
- `DEVELOPMENT`: Development mode flag
+- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific tool
- `CI`: CI environment flag
## Contributing
diff --git a/ts/packages/core/package.json b/ts/packages/core/package.json
index 83c9e9254..bb26c985d 100644
--- a/ts/packages/core/package.json
+++ b/ts/packages/core/package.json
@@ -44,7 +44,7 @@
"vitest": "^3.1.4"
},
"dependencies": {
- "@composio/client": "0.1.0-alpha.35",
+ "@composio/client": "0.1.0-alpha.36",
"@composio/json-schema-to-zod": "0.1.15",
"@types/json-schema": "^7.0.15",
"chalk": "^4.1.2",
diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.ts
index ba7f3b120..04719d25f 100644
--- a/ts/packages/core/src/composio.ts
+++ b/ts/packages/core/src/composio.ts
@@ -7,7 +7,7 @@ import { AuthConfigs } from './models/AuthConfigs';
import { ConnectedAccounts } from './models/ConnectedAccounts';
import { MCP } from './models/MCP';
import { telemetry } from './telemetry/Telemetry';
-import { getSDKConfig } from './utils/sdk';
+import { getSDKConfig, getToolkitVersionsFromEnv } from './utils/sdk';
import logger from './utils/logger';
import { COMPOSIO_LOG_LEVEL, IS_DEVELOPMENT_OR_CI } from './utils/constants';
import { checkForLatestVersionFromNPM } from './utils/version';
@@ -16,7 +16,8 @@ import { version } from '../package.json';
import type { ComposioRequestHeaders } from './types/composio.types';
import { McpServerGetResponse } from './types/mcp.types';
import { Files } from './models/Files';
-import { getDefaultHeaders, getSessionHeaders } from './utils/session';
+import { getDefaultHeaders } from './utils/session';
+import { ToolkitVersionParam } from './types/tool.types';
export type ComposioConfig<
TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider,
@@ -73,6 +74,15 @@ export type ComposioConfig<
* @default false
*/
disableVersionCheck?: boolean;
+ /**
+ * The versions of the toolkits to fetch.
+ * Defaults to latest is nothing is provided.
+ * Alternatively you can specify individual toolkit versions in the env `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
+ * @example
+ * { 'github': 'latest', 'slack': '20250902_00' }
+ * 'latest'
+ */
+ toolkitVersions?: ToolkitVersionParam;
};
/**
@@ -161,7 +171,11 @@ export class Composio<
*/
this.config = {
...config,
+ baseURL: baseURLParsed,
+ apiKey: apiKeyParsed,
+ toolkitVersions: getToolkitVersionsFromEnv(config?.toolkitVersions),
allowTracking: config?.allowTracking ?? true,
+ autoUploadDownloadFiles: config?.autoUploadDownloadFiles ?? true,
};
/**
@@ -182,9 +196,7 @@ export class Composio<
logLevel: COMPOSIO_LOG_LEVEL,
});
- this.tools = new Tools(this.client, this.provider, {
- autoUploadDownloadFiles: config?.autoUploadDownloadFiles ?? true,
- });
+ this.tools = new Tools(this.client, this.provider, this.config);
this.mcp = new MCP(this.client, this.provider);
this.toolkits = new Toolkits(this.client);
@@ -231,6 +243,14 @@ export class Composio<
return this.client;
}
+ /**
+ * Get the configuration SDK is initialized with
+ * @returns {ComposioConfig<TProvider>} The configuration SDK is initialized with
+ */
+ getConfig(): ComposioConfig<TProvider> {
+ return this.config;
+ }
+
/**
* Creates a new instance of the Composio SDK with custom request options while preserving the existing configuration.
* This method is particularly useful when you need to:
diff --git a/ts/packages/core/src/models/Tools.ts b/ts/packages/core/src/models/Tools.ts
index 333f41215..30c17e29b 100644
--- a/ts/packages/core/src/models/Tools.ts
+++ b/ts/packages/core/src/models/Tools.ts
@@ -10,6 +10,9 @@ import {
ToolExecuteResponseSchema,
ToolProxyParamsSchema,
ToolProxyParams,
+ ToolExecuteParamsSchema,
+ ToolkitVersionParam,
+ SchemaModifierOptions,
} from '../types/tool.types';
import {
ToolGetInputParams,
@@ -44,8 +47,9 @@ import {
import { ValidationError } from '../errors/ValidationErrors';
import { telemetry } from '../telemetry/Telemetry';
import { FileToolModifier } from '../utils/modifiers/FileToolModifier';
-import { CustomConnectionDataSchema } from '../types/connectedAccountAuthStates.types';
import { AuthSchemeTypes } from '../types/authConfigs.types';
+import { ComposioConfig } from '../composio';
+import { getToolkitVersion } from '../utils/toolkitVersion';
/**
* This class is used to manage tools in the Composio SDK.
* It provides methods to list, get, and execute tools.
@@ -59,12 +63,9 @@ export class Tools<
private readonly customTools: CustomTools;
private provider: TProvider;
private autoUploadDownloadFiles: boolean;
+ private toolkitVersions: ToolkitVersionParam;
- constructor(
- client: ComposioClient,
- provider: TProvider,
- options?: { autoUploadDownloadFiles: boolean }
- ) {
+ constructor(client: ComposioClient, provider: TProvider, config?: ComposioConfig<TProvider>) {
if (!client) {
throw new Error('ComposioClient is required');
}
@@ -75,12 +76,12 @@ export class Tools<
this.client = client;
this.customTools = new CustomTools(client);
this.provider = provider;
- this.autoUploadDownloadFiles = options?.autoUploadDownloadFiles ?? true;
+ this.autoUploadDownloadFiles = config?.autoUploadDownloadFiles ?? true;
+ this.toolkitVersions = config?.toolkitVersions ?? 'latest';
// Bind the execute method to ensure correct 'this' context
this.execute = this.execute.bind(this);
// Set the execute method for the provider
this.provider._setExecuteToolFn(this.execute);
-
// Bind methods that use customTools to ensure correct 'this' context
this.getRawComposioToolBySlug = this.getRawComposioToolBySlug.bind(this);
this.getRawComposioTools = this.getRawComposioTools.bind(this);
@@ -106,6 +107,7 @@ export class Tools<
...tool,
inputParameters: tool.input_parameters,
outputParameters: tool.output_parameters,
+ availableVersions: tool.available_versions,
});
}
@@ -130,60 +132,6 @@ export class Tools<
});
}
- /**
- * Check if the connected account exists for the given tools.
- * @param {string} userId - The user id.
- * @param {ToolList} tools - The tools to check.
- * @returns {Promise<boolean>} True if the connected account exists for the given tools, false otherwise.
- */
- private async checkIfConnectedAccountExistsForTools(
- userIds: string[],
- tools: ToolList
- ): Promise<boolean> {
- // @TODO: Filter out tools that don't require a connected account
-
- // if no tools, return true as no connections needed
- if (!tools.length) {
- return true;
- }
- const connectedAccounts = await this.client.connectedAccounts.list({
- user_ids: userIds,
- });
- // if no connected accounts, return false
- if (connectedAccounts.items.length === 0) {
- return false;
- }
-
- // create a map of toolkit slugs that have connected accounts
- const connectedToolkitSlugs = connectedAccounts.items.reduce(
- (acc, account) => {
- if (account.toolkit.slug) {
- acc[account.toolkit.slug] = true;
- }
- return acc;
- },
- {} as Record<string, boolean>
- );
-
- // create a map of tool slugs
- const toolSlugs = tools.reduce(
- (acc, tool) => {
- acc[tool.slug] = true;
- return acc;
- },
- {} as Record<string, boolean>
- );
-
- // check if each tool's toolkit has a connected account
- for (const tool of Object.keys(toolSlugs)) {
- if (!connectedToolkitSlugs[tool]) {
- logger.warn(`Tool ${tool} requires a connected account but no connected account was found`);
- return false;
- }
- }
- return true;
- }
-
/**
* Get the connected account id for a given tool
* @param {string} userId - The user id
@@ -345,34 +293,61 @@ export class Tools<
*
* This method fetches tools from the Composio API in raw format and combines them with
* any registered custom tools. The response can be filtered and modified as needed.
+ * It provides access to the underlying tool data without provider-specific wrapping.
*
- * @param {ToolListParams} [query={}] - Optional query parameters to filter the tools
- * @param {TransformToolSchemaModifier} [modifier] - Optional function to transform tool schemas
+ * @param {ToolListParams} query - Query parameters to filter the tools (required)
+ * @param {GetRawComposioToolsOptions} [options] - Optional configuration for tool retrieval
+ * @param {TransformToolSchemaModifier} [options.modifySchema] - Function to transform tool schemas
* @returns {Promise<ToolList>} List of tools matching the query criteria
*
* @example
* ```typescript
- * // Get all tools
- * const tools = await composio.tools.getRawComposioTools();
+ * // Get tools from specific toolkits
+ * const githubTools = await composio.tools.getRawComposioTools({
+ * toolkits: ['github'],
+ * limit: 10
+ * });
*
- * // Get tools with filters
+ * // Get specific tools by slug
+ * const specificTools = await composio.tools.getRawComposioTools({
+ * tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
+ * });
+ *
+ * // Get tools from specific toolkits
* const githubTools = await composio.tools.getRawComposioTools({
* toolkits: ['github'],
* limit: 10
* });
*
* // Get tools with schema transformation
- * const tools = await composio.tools.getRawComposioTools({},
- * (toolSlug, toolkitSlug, tool) => {
+ * const customizedTools = await composio.tools.getRawComposioTools({
+ * toolkits: ['github'],
+ * limit: 5
+ * }, {
+ * modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
* // Add custom properties to tool schema
- * return {...tool, customProperty: 'value'};
+ * return {
+ * ...schema,
+ * customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
+ * tags: [...(schema.tags || []), 'customized']
+ * };
* }
- * );
+ * });
+ *
+ * // Search for tools
+ * const searchResults = await composio.tools.getRawComposioTools({
+ * search: 'user management'
+ * });
+ *
+ * // Get tools by authentication config
+ * const authSpecificTools = await composio.tools.getRawComposioTools({
+ * authConfigIds: ['auth_config_123']
+ * });
* ```
*/
async getRawComposioTools(
query: ToolListParams,
- modifier?: TransformToolSchemaModifier
+ options?: SchemaModifierOptions
): Promise<ToolList> {
if ('tools' in query && 'toolkits' in query) {
throw new ValidationError(
@@ -419,6 +394,7 @@ export class Tools<
...('authConfigIds' in queryParams.data
? { auth_config_ids: queryParams.data.authConfigIds }
: {}),
+ ...{ toolkit_versions: this.toolkitVersions },
};
logger.debug(`Fetching tools with filters: ${JSON.stringify(filters, null, 2)}`);
@@ -440,7 +416,8 @@ export class Tools<
]);
// apply local modifiers if they are provided
- if (modifier) {
+ if (options?.modifySchema) {
+ const modifier = options.modifySchema;
if (typeof modifier === 'function') {
const modifiedPromises = modifiedTools.map(tool =>
modifier({
@@ -459,20 +436,56 @@ export class Tools<
}
/**
- * Retrieves a tool by its Slug.
- * This method is used to get the raw tools from the composio API.
- * @param slug The ID of the tool to be retrieved
- * @returns {Promise<Tool>} The tool
+ * Retrieves a specific tool by its slug from the Composio API.
+ *
+ * This method fetches a single tool in raw format without provider-specific wrapping,
+ * providing direct access to the tool's schema and metadata. Tool versions are controlled
+ * at the Composio SDK initialization level through the `toolkitVersions` configuration.
+ *
+ * @param {string} slug - The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
+ * @param {GetRawComposioToolBySlugOptions} [options] - Optional configuration for tool retrieval
+ * @param {TransformToolSchemaModifier} [options.modifySchema] - Function to transform the tool schema
+ * @returns {Promise<Tool>} The requested tool with its complete schema and metadata
*
* @example
- * ```ts
- * const tool = await composio.tools.getRawComposioToolBySlug('github');
+ * ```typescript
+ * // Get a tool by slug
+ * const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
+ * console.log(tool.name, tool.description);
+ *
+ * // Get a tool with schema transformation
+ * const customizedTool = await composio.tools.getRawComposioToolBySlug(
+ * 'SLACK_SEND_MESSAGE',
+ * {
+ * modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
+ * return {
+ * ...schema,
+ * description: `Enhanced ${schema.description} with custom modifications`,
+ * customMetadata: {
+ * lastModified: new Date().toISOString(),
+ * toolkit: toolkitSlug
+ * }
+ * };
+ * }
+ * }
+ * );
+ *
+ * // Get a custom tool (will check custom tools first)
+ * const customTool = await composio.tools.getRawComposioToolBySlug('MY_CUSTOM_TOOL');
+ *
+ * // Access tool properties
+ * const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
+ * console.log({
+ * slug: githubTool.slug,
+ * name: githubTool.name,
+ * toolkit: githubTool.toolkit?.name,
+ * version: githubTool.version,
+ * availableVersions: githubTool.availableVersions,
+ * inputParameters: githubTool.inputParameters
+ * });
* ```
*/
- async getRawComposioToolBySlug(
- slug: string,
- modifier?: TransformToolSchemaModifier
- ): Promise<Tool> {
+ async getRawComposioToolBySlug(slug: string, options?: SchemaModifierOptions): Promise<Tool> {
// check if the tool is a custom tool
const customTool = await this.customTools.getCustomToolBySlug(slug);
if (customTool) {
@@ -484,7 +497,9 @@ export class Tools<
// if not, fetch the tool from the Composio API
let tool: ToolRetrieveResponse;
try {
- tool = await this.client.tools.retrieve(slug);
+ tool = await this.client.tools.retrieve(slug, {
+ toolkit_versions: this.toolkitVersions,
+ });
} catch (error) {
throw new ComposioToolNotFoundError(`Unable to retrieve tool with slug ${slug}`, {
cause: error,
@@ -494,7 +509,8 @@ export class Tools<
// change the case of the tool to camel case and apply default modifiers
let [modifiedTool] = await this.applyDefaultSchemaModifiers([this.transformToolCases(tool)]);
// apply local modifiers if they are provided
- if (modifier) {
+ if (options?.modifySchema) {
+ const modifier = options.modifySchema;
if (typeof modifier === 'function') {
modifiedTool = await modifier({
toolSlug: slug,
@@ -580,27 +596,34 @@ export class Tools<
/**
* Get a tool or list of tools based on the provided arguments.
- * This is an implementation method that handles both overloads.
+ * This is an implementation method that handles all overloads.
*
* @param {string} userId - The user id to get the tool(s) for
* @param {ToolListParams | string} arg2 - Either a slug string or filters object
- * @param {ProviderOptions<TProvider>} [options] - Optional provider options
+ * @param {ProviderOptions<TProvider> | ToolkitVersion} [arg3] - Optional provider options or version string
+ * @param {ProviderOptions<TProvider>} [arg4] - Optional provider options (when arg3 is version)
* @returns {Promise<TToolCollection>} The tool collection
*/
async get(
userId: string,
arg2: ToolListParams | string,
- options?: ProviderOptions<TProvider>
+ arg3?: ProviderOptions<TProvider>
): Promise<TToolCollection> {
- // create the execute tool function
+ // Handle the two-parameter overloads
+ const options = arg3 as ProviderOptions<TProvider>;
const executeToolFn = this.createExecuteToolFn(userId, options as ExecuteToolModifiers);
- // if the first argument is a string, get a single tool
+
+ // if the second argument is a string, get a single tool
if (typeof arg2 === 'string') {
- const tool = await this.getRawComposioToolBySlug(arg2, options?.modifySchema);
+ const tool = await this.getRawComposioToolBySlug(arg2, {
+ modifySchema: options?.modifySchema as TransformToolSchemaModifier,
+ });
return this.provider.wrapTools([tool], executeToolFn) as TToolCollection;
} else {
- // if the first argument is an object, get a list of tools
- const tools = await this.getRawComposioTools(arg2, options?.modifySchema);
+ // if the second argument is an object, get a list of tools
+ const tools = await this.getRawComposioTools(arg2, {
+ modifySchema: options?.modifySchema as TransformToolSchemaModifier,
+ });
return this.provider.wrapTools(tools, executeToolFn) as TToolCollection;
}
}
@@ -709,12 +732,12 @@ export class Tools<
custom_connection_data: body.customConnectionData,
arguments: body.arguments,
user_id: body.userId,
- version: body.version,
+ version:
+ body.version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions),
text: body.text,
});
// apply transformations to the response
result = this.transformToolExecuteResponse(result);
-
result = await this.applyAfterExecuteModifiers(
tool,
{
@@ -777,27 +800,37 @@ export class Tools<
);
}
+ const executeParams = ToolExecuteParamsSchema.safeParse(body);
+ if (!executeParams.success) {
+ throw new ValidationError('Invalid tool execute parameters', { cause: executeParams.error });
+ }
+
try {
const customTool = await this.customTools.getCustomToolBySlug(slug);
if (customTool) {
// handle custom tool execution
- return this.handleCustomToolExecution(customTool, body, modifiers);
+ return this.handleCustomToolExecution(customTool, executeParams.data, modifiers);
} else {
// handle composio tool execution
const composioTool = await this.getRawComposioToolBySlug(slug);
if (!composioTool) {
- throw new ComposioToolNotFoundError(`Tool with slug ${slug} not found`);
+ throw new ComposioToolNotFoundError(
+ `Tool with slug ${slug} version:${executeParams.data.version} not found`
+ );
}
- return this.handleComposioToolExecution(composioTool, body, modifiers);
+ return this.handleComposioToolExecution(composioTool, executeParams.data, modifiers);
}
} catch (error) {
- throw new ComposioToolExecutionError(`Error executing tool ${slug}`, {
- originalError: error as Error,
- meta: {
- toolSlug: slug,
- body,
- },
- });
+ throw new ComposioToolExecutionError(
+ `Error executing tool ${slug} version:${executeParams.data.version}`,
+ {
+ originalError: error as Error,
+ meta: {
+ toolSlug: slug,
+ body,
+ },
+ }
+ );
}
}
diff --git a/ts/packages/core/src/types/provider.types.ts b/ts/packages/core/src/types/provider.types.ts
index a788b7763..0d62b473d 100644
--- a/ts/packages/core/src/types/provider.types.ts
+++ b/ts/packages/core/src/types/provider.types.ts
@@ -4,6 +4,7 @@ import {
Tool,
ToolExecuteParams,
ToolExecuteResponse,
+ ToolkitVersion,
ToolListParams,
} from './tool.types';
import { CustomConnectionData } from './connectedAccountAuthStates.types';
diff --git a/ts/packages/core/src/types/tool.types.ts b/ts/packages/core/src/types/tool.types.ts
index d6e3a5e07..ed8d97e64 100644
--- a/ts/packages/core/src/types/tool.types.ts
+++ b/ts/packages/core/src/types/tool.types.ts
@@ -1,5 +1,6 @@
import { z } from 'zod';
import { CustomConnectionDataSchema } from './connectedAccountAuthStates.types';
+import { TransformToolSchemaModifier } from './modifiers.types';
/**
* Toolkit is the collection of tools,
@@ -112,10 +113,15 @@ export const ToolSchema = z.object({
description: z.string().optional().describe('The description of the tool'),
inputParameters: ParametersSchema.optional().describe('The input parameters of the tool'),
outputParameters: ParametersSchema.optional().describe('The output parameters of the tool'),
- tags: z.optional(z.array(z.string())).describe('The tags of the tool. eg: Important').default([]),
- toolkit: z.optional(ToolkitSchema).describe('The toolkit of the tool'),
- version: z.optional(z.string()).describe('The version of the tool, e.g. "1.0.0"'),
- scopes: z.optional(z.array(z.string())).describe('The scopes of the tool. eg: ["task:add"]'),
+ tags: z.array(z.string()).describe('The tags of the tool. eg: Important').default([]).optional(),
+ toolkit: ToolkitSchema.describe('The toolkit of the tool').optional(),
+ version: z.string().describe('The version of the tool, e.g. "20250909_00"').optional(),
+ availableVersions: z
+ .array(z.string())
+ .describe('Available versions of the tool.')
+ .default([])
+ .optional(),
+ scopes: z.array(z.string()).describe('The scopes of the tool. eg: ["task:add"]').optional(),
});
export type Tool = z.infer<typeof ToolSchema>;
@@ -134,6 +140,31 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
*/
export type ToolList = Array<Tool>;
+/**
+ * latest toolkit version param
+ */
+export type ToolkitLatestVersion = 'latest';
+/**
+ * Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'
+ * @example
+ * 'latest'
+ * '20250902_00'
+ */
+export type ToolkitVersion = ToolkitLatestVersion | string;
+/**
+ * Versioning multiple toolkits
+ * @example
+ * { 'github': 'latest', 'slack': '20250902_00' }
+ */
+export type ToolkitVersions = Record<string, ToolkitVersion>;
+/**
+ * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'
+ * @example
+ * 'latest'
+ * { 'github': 'latest', 'slack': '20250902_00' }
+ */
+export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;
+
export const ToolListParamsSchema = z.object({
tools: z.array(z.string()).optional(),
toolkits: z.array(z.string()).optional(),
@@ -159,7 +190,6 @@ type ToolsOnlyParams = {
search?: never;
tags?: never;
};
-
// toolkits only
type ToolkitsOnlyParams = {
toolkits: string[];
@@ -184,11 +214,11 @@ type TagsOnlyParams = {
// search only
type SearchOnlyParams = {
+ search: string;
tools?: never;
toolkits?: never;
scopes?: never;
limit?: never;
- search: string;
tags?: never;
};
@@ -235,8 +265,8 @@ export const ToolExecuteParamsSchema = z.object({
customAuthParams: CustomAuthParamsSchema.optional(),
customConnectionData: CustomConnectionDataSchema.optional(),
arguments: z.record(z.string(), z.unknown()).optional(),
- userId: z.string().optional(), //
- version: z.string().optional(),
+ userId: z.string().optional(), // we have no auth apps which can be execute
+ version: z.union([z.literal('latest'), z.string()]).optional(),
text: z.string().optional(),
});
export type ToolExecuteParams = z.infer<typeof ToolExecuteParamsSchema>;
@@ -270,3 +300,7 @@ export const ToolProxyParamsSchema = z.object({
customConnectionData: CustomConnectionDataSchema.optional(),
});
export type ToolProxyParams = z.infer<typeof ToolProxyParamsSchema>;
+
+export type SchemaModifierOptions = {
+ modifySchema: TransformToolSchemaModifier;
+};
diff --git a/ts/packages/core/src/utils/env.ts b/ts/packages/core/src/utils/env.ts
index 470b4fca5..df336b0b7 100644
--- a/ts/packages/core/src/utils/env.ts
+++ b/ts/packages/core/src/utils/env.ts
@@ -8,3 +8,27 @@ export const getEnvVariable = (
return defaultValue;
}
};
+
+/**
+ * Method to return all the envs based on a specific prefix
+ * @param prefix
+ * @example
+ * COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
+ * COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
+ * COMPOSIO_TOOLKIT_VERSION_GMAIL=latest
+ * @returns {Record<string, unknown>}
+ * @returns
+ */
+export const getEnvsWithPrefix = (prefix: string): Record<string, unknown> => {
+ try {
+ if (process && process.env) {
+ return Object.fromEntries(
+ Object.entries(process.env).filter(([key]) => key.startsWith(prefix))
+ );
+ } else {
+ return {};
+ }
+ } catch (error) {
+ return {};
+ }
+};
diff --git a/ts/packages/core/src/utils/sdk.ts b/ts/packages/core/src/utils/sdk.ts
index 41d846859..cf8134bba 100644
--- a/ts/packages/core/src/utils/sdk.ts
+++ b/ts/packages/core/src/utils/sdk.ts
@@ -1,8 +1,9 @@
import { ComposioNoAPIKeyError } from '../errors/SDKErrors';
import { COMPOSIO_DIR, DEFAULT_BASE_URL, USER_DATA_FILE_NAME } from './constants';
-import { getEnvVariable } from './env';
+import { getEnvsWithPrefix, getEnvVariable } from './env';
import logger from './logger';
import { ComposioError } from '../errors/ComposioError';
+import { ToolkitVersion, ToolkitVersionParam, ToolkitVersions } from '../types/tool.types';
// File path helpers
export const userDataPath = () => {
@@ -18,6 +19,11 @@ export const userDataPath = () => {
}
};
+/**
+ * Reads and parses the user data JSON file from the Composio directory.
+ *
+ * @returns The parsed user data object containing user configuration (api_key, base_url, etc.), or empty object if file doesn't exist or can't be read
+ */
export const getUserDataJson = () => {
try {
// eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -50,3 +56,54 @@ export function getSDKConfig(baseUrl?: string | null, apiKey?: string | null) {
return { baseURL: baseURLParsed, apiKey: apiKeyParsed };
}
+
+/**
+ * Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
+ *
+ * Priority order:
+ * 1. If defaultVersions is a string, use it as global version for all toolkits
+ * 2. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
+ * 3. User-provided toolkit version mappings (defaultVersions object)
+ * 4. Fallback to 'latest' if no versions are configured
+ *
+ * @param defaultVersions - Optional default versions configuration (string for global version or object mapping toolkit names to versions)
+ * @returns Toolkit versions configuration - either a global version string, toolkit-specific version mapping, or 'latest'
+ */
+export function getToolkitVersionsFromEnv(
+ defaultVersions?: ToolkitVersionParam
+): ToolkitVersionParam {
+ // if already set by user either a single version or 'latest' use that as is / override everything else
+ if (defaultVersions && typeof defaultVersions === 'string') {
+ return defaultVersions;
+ }
+
+ // check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
+ const envPrefixedVersions = getEnvsWithPrefix(`COMPOSIO_TOOLKIT_VERSION_`);
+ const toolkitVersionsFromEnv = Object.entries(envPrefixedVersions).reduce((acc, [key, value]) => {
+ const toolkitName = key.replace('COMPOSIO_TOOLKIT_VERSION_', '');
+ acc[toolkitName.toLowerCase()] = value as ToolkitVersion;
+ return acc;
+ }, {} as ToolkitVersions);
+
+ // if the provided default versions is an object, normalize the keys to be lower case
+ // use user provided values as overrides
+ let userProvidedToolkitVersions = {};
+ if (defaultVersions && typeof defaultVersions === 'object') {
+ userProvidedToolkitVersions = Object.fromEntries(
+ Object.entries(defaultVersions).map(([key, value]) => [key.toLowerCase(), value])
+ );
+ }
+
+ // final toolkit versions
+ const toolkitVersions = {
+ ...toolkitVersionsFromEnv,
+ ...userProvidedToolkitVersions,
+ };
+
+ // if the toolkitVersions are empty, use 'latest'
+ if (Object.keys(toolkitVersions).length === 0) {
+ return 'latest';
+ }
+
+ return toolkitVersions;
+}
diff --git a/ts/packages/core/src/utils/toolkitVersion.ts b/ts/packages/core/src/utils/toolkitVersion.ts
new file mode 100644
index 000000000..87488dbb8
--- /dev/null
+++ b/ts/packages/core/src/utils/toolkitVersion.ts
@@ -0,0 +1,26 @@
+import { ToolkitVersion, ToolkitVersionParam } from '../types/tool.types';
+
+/**
+ * Gets the version for a specific toolkit based on the provided toolkit versions configuration.
+ *
+ * @param toolkitSlug - The slug/name of the toolkit to get the version for
+ * @param toolkitVersions - Optional toolkit versions configuration (string for global version or object mapping toolkit slugs to versions)
+ * @returns The toolkit version to use - either the specific version from config, or 'latest' as fallback
+ */
+export const getToolkitVersion = (
+ toolkitSlug: string,
+ toolkitVersions?: ToolkitVersionParam
+): ToolkitVersion => {
+ // If toolkitVersions is a string, use it as a global version for all toolkits
+ if (typeof toolkitVersions === 'string') {
+ return toolkitVersions;
+ }
+ // If toolkitVersions is an object mapping, look up the specific toolkit version
+ const hasToolkitVersion = toolkitVersions && Object.keys(toolkitVersions).length > 0;
+ if (hasToolkitVersion) {
+ return toolkitVersions[toolkitSlug] ?? 'latest';
+ }
+
+ // Else use 'latest'
+ return 'latest';
+};
diff --git a/ts/packages/core/test/core/versions.test.ts b/ts/packages/core/test/core/versions.test.ts
new file mode 100644
index 000000000..f2d53c899
--- /dev/null
+++ b/ts/packages/core/test/core/versions.test.ts
@@ -0,0 +1,413 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { getToolkitVersionsFromEnv } from '../../src/utils/sdk';
+import { getToolkitVersion } from '../../src/utils/toolkitVersion';
+import { getEnvsWithPrefix } from '../../src/utils/env';
+import { ToolkitVersions } from '../../src/types/tool.types';
+
+describe('Version Management', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ // Reset environment variables before each test
+ vi.resetModules();
+ process.env = { ...originalEnv };
+ });
+
+ afterEach(() => {
+ // Restore original environment
+ process.env = originalEnv;
+ vi.clearAllMocks();
+ });
+
+ describe('getEnvsWithPrefix', () => {
+ it('should return environment variables with the specified prefix', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250902_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+ process.env.COMPOSIO_TOOLKIT_VERSION_GMAIL = '20250901_01';
+ process.env.OTHER_ENV_VAR = 'should_not_be_included';
+
+ const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
+
+ expect(result).toEqual({
+ COMPOSIO_TOOLKIT_VERSION_GITHUB: '20250902_00',
+ COMPOSIO_TOOLKIT_VERSION_SLACK: 'latest',
+ COMPOSIO_TOOLKIT_VERSION_GMAIL: '20250901_01',
+ });
+ expect(result).not.toHaveProperty('OTHER_ENV_VAR');
+ });
+
+ it('should return empty object when no matching environment variables exist', () => {
+ process.env.SOME_OTHER_VAR = 'value';
+
+ const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
+
+ expect(result).toEqual({});
+ });
+
+ it('should return empty object when prefix is empty', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250902_00';
+
+ const result = getEnvsWithPrefix('');
+
+ // Should return all env vars when prefix is empty
+ expect(Object.keys(result).length).toBeGreaterThan(0);
+ expect(result).toHaveProperty('COMPOSIO_TOOLKIT_VERSION_GITHUB');
+ });
+
+ it('should handle process.env being undefined gracefully', () => {
+ const originalProcess = process;
+ // @ts-expect-error: Intentionally testing edge case
+ global.process = undefined;
+
+ const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
+
+ expect(result).toEqual({});
+
+ // Restore process
+ global.process = originalProcess;
+ });
+
+ it('should handle errors gracefully', () => {
+ // Mock process.env to throw an error
+ const mockProcess = {
+ env: new Proxy(
+ {},
+ {
+ get() {
+ throw new Error('Test error');
+ },
+ }
+ ),
+ };
+
+ vi.stubGlobal('process', mockProcess);
+
+ const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
+
+ expect(result).toEqual({});
+
+ vi.unstubAllGlobals();
+ });
+ });
+
+ describe('getToolkitVersionsFromEnv', () => {
+ describe('when user provides string version (global version)', () => {
+ it('should return the string version as-is when user provides "latest"', () => {
+ const result = getToolkitVersionsFromEnv('latest');
+ expect(result).toBe('latest');
+ });
+
+ it('should return the string version as-is when user provides specific version', () => {
+ const result = getToolkitVersionsFromEnv('20250902_00' as any);
+ expect(result).toBe('20250902_00');
+ });
+
+ it('should ignore environment variables when user provides string version', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_01';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const result = getToolkitVersionsFromEnv('20250902_00' as any);
+ expect(result).toBe('20250902_00');
+ });
+ });
+
+ describe('when user provides object version mapping', () => {
+ it('should normalize toolkit names to lowercase', () => {
+ const userVersions = {
+ GITHUB: '20250902_00',
+ Slack: 'latest',
+ gmail: '20250901_01',
+ };
+
+ const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ });
+ });
+
+ it('should merge environment variables with user-provided versions', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_NOTION = 'latest';
+
+ const userVersions = {
+ slack: '20250902_00',
+ gmail: 'latest',
+ };
+
+ const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250901_00', // from env
+ notion: 'latest', // from env
+ slack: '20250902_00', // from user
+ gmail: 'latest', // from user
+ });
+ });
+
+ it('should prioritize user-provided versions over environment variables', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = '20250901_01';
+
+ const userVersions = {
+ github: '20250902_00', // should override env
+ slack: 'latest', // should override env
+ gmail: '20250902_01', // new toolkit
+ };
+
+ const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250902_00', // user version takes precedence
+ slack: 'latest', // user version takes precedence
+ gmail: '20250902_01', // from user
+ });
+ });
+
+ it('should handle mixed case environment variables correctly', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const result = getToolkitVersionsFromEnv({}) as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250901_00', // normalized to lowercase
+ slack: 'latest', // normalized to lowercase
+ });
+ });
+ });
+
+ describe('when no user versions provided', () => {
+ it('should return environment variables only', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const result = getToolkitVersionsFromEnv() as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250901_00',
+ slack: 'latest',
+ });
+ });
+
+ it('should return "latest" when no environment variables or user versions exist', () => {
+ const result = getToolkitVersionsFromEnv();
+ expect(result).toBe('latest');
+ });
+
+ it('should return "latest" when empty object is provided and no env vars exist', () => {
+ const result = getToolkitVersionsFromEnv({});
+ expect(result).toBe('latest');
+ });
+
+ it('should handle undefined input correctly', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+
+ const result = getToolkitVersionsFromEnv(undefined) as ToolkitVersions;
+
+ expect(result).toEqual({
+ github: '20250901_00',
+ });
+ });
+ });
+
+ describe('environment variable parsing', () => {
+ it('should extract toolkit names correctly from environment variables', () => {
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB_ENTERPRISE = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_GOOGLE_WORKSPACE = 'latest';
+ process.env.COMPOSIO_TOOLKIT_VERSION_MS_TEAMS = '20250902_00';
+
+ const result = getToolkitVersionsFromEnv() as ToolkitVersions;
+
+ expect(result).toEqual({
+ github_enterprise: '20250901_00',
+ google_workspace: 'latest',
+ ms_teams: '20250902_00',
+ });
+ });
+
+ it('should handle environment variables with special characters', () => {
+ process.env['COMPOSIO_TOOLKIT_VERSION_MY-TOOLKIT'] = '20250901_00';
+ process.env['COMPOSIO_TOOLKIT_VERSION_ANOTHER_TOOLKIT'] = 'latest';
+
+ const result = getToolkitVersionsFromEnv() as ToolkitVersions;
+
+ expect(result).toEqual({
+ 'my-toolkit': '20250901_00',
+ another_toolkit: 'latest',
+ });
+ });
+ });
+ });
+
+ describe('getToolkitVersion', () => {
+ describe('when toolkitVersions is a string (global version)', () => {
+ it('should return the global version for any toolkit', () => {
+ const result1 = getToolkitVersion('github', 'latest');
+ const result2 = getToolkitVersion('slack', 'latest');
+ const result3 = getToolkitVersion('gmail', 'latest');
+
+ expect(result1).toBe('latest');
+ expect(result2).toBe('latest');
+ expect(result3).toBe('latest');
+ });
+ });
+
+ describe('when toolkitVersions is an object mapping', () => {
+ it('should return specific version for toolkit when available', () => {
+ const toolkitVersions = {
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ };
+
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
+ expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250901_01');
+ });
+
+ it('should return "latest" for toolkit not in the mapping', () => {
+ const toolkitVersions = {
+ github: '20250902_00',
+ slack: 'latest',
+ };
+
+ const result = getToolkitVersion('notion', toolkitVersions);
+ expect(result).toBe('latest');
+ });
+
+ it('should handle empty object mapping', () => {
+ const result = getToolkitVersion('github', {});
+ expect(result).toBe('latest');
+ });
+
+ it('should be case-sensitive for toolkit slugs', () => {
+ const toolkitVersions = {
+ github: '20250902_00',
+ GITHUB: 'latest',
+ };
+
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('GITHUB', toolkitVersions)).toBe('latest');
+ expect(getToolkitVersion('GitHub', toolkitVersions)).toBe('latest'); // not found
+ });
+ });
+
+ describe('when toolkitVersions is undefined or null', () => {
+ it('should return "latest" when toolkitVersions is undefined', () => {
+ const result = getToolkitVersion('github', undefined);
+ expect(result).toBe('latest');
+ });
+
+ it('should return "latest" when toolkitVersions is null', () => {
+ const result = getToolkitVersion('github', null as any);
+ expect(result).toBe('latest');
+ });
+ });
+
+ describe('edge cases', () => {
+ it('should handle empty toolkit slug', () => {
+ const toolkitVersions = {
+ '': '20250902_00',
+ github: 'latest',
+ };
+
+ expect(getToolkitVersion('', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('latest');
+ });
+
+ it('should handle toolkit slug with special characters', () => {
+ const toolkitVersions = {
+ 'my-toolkit': '20250902_00',
+ another_toolkit: 'latest',
+ 'toolkit.with.dots': '20250901_00',
+ };
+
+ expect(getToolkitVersion('my-toolkit', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('another_toolkit', toolkitVersions)).toBe('latest');
+ expect(getToolkitVersion('toolkit.with.dots', toolkitVersions)).toBe('20250901_00');
+ });
+
+ it('should handle version values that are not strings', () => {
+ const toolkitVersions = {
+ github: '20250902_00',
+ slack: 'latest',
+ } as any;
+
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
+ });
+ });
+ });
+
+ describe('Integration tests', () => {
+ it('should work together: getToolkitVersionsFromEnv + getToolkitVersion', () => {
+ // Set up environment
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ // User provides additional versions
+ const userVersions = {
+ GMAIL: '20250902_00', // will be normalized to lowercase
+ notion: 'latest',
+ };
+
+ // Get toolkit versions configuration
+ const toolkitVersions = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
+
+ // Test individual toolkit version retrieval
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('20250901_00'); // from env
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest'); // from env
+ expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250902_00'); // from user
+ expect(getToolkitVersion('notion', toolkitVersions)).toBe('latest'); // from user
+ expect(getToolkitVersion('unknown', toolkitVersions)).toBe('latest'); // fallback
+ });
+
+ it('should handle global version override correctly', () => {
+ // Set up environment (should be ignored)
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ // User provides global version
+ const toolkitVersions = getToolkitVersionsFromEnv('20250902_00' as any);
+
+ // All toolkits should get the global version
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250902_00');
+ expect(getToolkitVersion('any-toolkit', toolkitVersions)).toBe('20250902_00');
+ });
+
+ it('should fall back to "latest" when no configuration is provided', () => {
+ // No environment variables, no user input
+ const toolkitVersions = getToolkitVersionsFromEnv();
+
+ expect(toolkitVersions).toBe('latest');
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('latest');
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
+ expect(getToolkitVersion('any-toolkit', toolkitVersions)).toBe('latest');
+ });
+
+ it('should demonstrate priority order: user object > env vars > fallback', () => {
+ // Environment variables
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = 'env_version';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'env_slack_version';
+
+ // User provides partial override
+ const userVersions = {
+ github: 'user_version', // overrides env
+ gmail: 'user_gmail_version', // new toolkit
+ // slack not specified, should use env
+ };
+
+ const toolkitVersions = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
+
+ expect(getToolkitVersion('github', toolkitVersions)).toBe('user_version'); // user wins
+ expect(getToolkitVersion('slack', toolkitVersions)).toBe('env_slack_version'); // from env
+ expect(getToolkitVersion('gmail', toolkitVersions)).toBe('user_gmail_version'); // from user
+ expect(getToolkitVersion('notion', toolkitVersions)).toBe('latest'); // fallback
+ });
+ });
+});
diff --git a/ts/packages/core/test/tools/fileModifiers.test.ts b/ts/packages/core/test/tools/fileModifiers.test.ts
index 5905d9cde..c8e9f04ca 100644
--- a/ts/packages/core/test/tools/fileModifiers.test.ts
+++ b/ts/packages/core/test/tools/fileModifiers.test.ts
@@ -37,6 +37,8 @@ describe('FileToolModifier', () => {
name: 'Test Tool',
description: 'A test tool',
tags: ['test'],
+ version: '20250902_00',
+ availableVersions: ['20250902_00'],
};
const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);
@@ -49,6 +51,8 @@ describe('FileToolModifier', () => {
name: 'Test Tool',
description: 'A test tool',
tags: ['test'],
+ version: '20250902_00',
+ availableVersions: ['20250902_00'],
inputParameters: {
type: 'object',
properties: {
@@ -87,6 +91,8 @@ describe('FileToolModifier', () => {
},
},
},
+ version: '20250902_00',
+ availableVersions: ['20250902_00'],
};
it('should upload file for file_uploadable parameters', async () => {
@@ -180,6 +186,8 @@ describe('FileToolModifier', () => {
name: 'Test Tool',
description: 'A test tool',
tags: ['test'],
+ availableVersions: ['20250902_00'],
+ version: '20250902_00',
};
it('should download file from S3 URL', async () => {
@@ -314,6 +322,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
},
additionalProperties: false,
},
+ version: '20250902_00',
+ availableVersions: ['20250902_00'],
};
const mockRawToolWithFileUpload = {
@@ -352,6 +362,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
},
additionalProperties: false,
},
+ version: '20250902_00',
+ availableVersions: ['20250902_00'],
};
describe('when autoUploadDownloadFiles is false', () => {
@@ -419,7 +431,7 @@ describe('Tools with autoUploadDownloadFiles', () => {
custom_connection_data: undefined,
text: undefined,
user_id: 'test-user',
- version: undefined,
+ version: 'latest',
});
});
diff --git a/ts/packages/core/test/tools/modifiers.test.ts b/ts/packages/core/test/tools/modifiers.test.ts
index 0ab202adc..32f89962c 100644
--- a/ts/packages/core/test/tools/modifiers.test.ts
+++ b/ts/packages/core/test/tools/modifiers.test.ts
@@ -26,7 +26,9 @@ describe('Tools Modifiers', () => {
// mock client to send back the tool
mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
- const result = await context.tools.getRawComposioToolBySlug(slug, schemaModifier);
+ const result = await context.tools.getRawComposioToolBySlug(slug, {
+ modifySchema: schemaModifier,
+ });
expect(schemaModifier).toHaveBeenCalledTimes(1);
expect(schemaModifier).toHaveBeenCalledWith(
@@ -57,7 +59,7 @@ describe('Tools Modifiers', () => {
const result = await context.tools.getRawComposioTools(
{ tools: ['TOOL1', 'TOOL2'] },
- schemaModifier
+ { modifySchema: schemaModifier }
);
expect(schemaModifier).toHaveBeenCalledTimes(2);
@@ -237,7 +239,9 @@ describe('Tools Modifiers', () => {
});
// Verify schema modification
- expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, schemaModifier);
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
+ modifySchema: schemaModifier,
+ });
expect(mockTool.description).toBe('Enhanced GITHUB_GET_REPOS for better context');
expect(mockTool.tags).toContain('enhanced');
expect(mockTool.tags).toContain('modified');
diff --git a/ts/packages/core/test/tools/tools.test.ts b/ts/packages/core/test/tools/tools.test.ts
index d373d15bb..902136b0d 100644
--- a/ts/packages/core/test/tools/tools.test.ts
+++ b/ts/packages/core/test/tools/tools.test.ts
@@ -1,7 +1,7 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { mockClient } from '../utils/mocks/client.mock';
import { toolMocks } from '../utils/mocks/data.mock';
-import { Tool, ToolListParams } from '../../src/types/tool.types';
+import { Tool, ToolListParams, ToolExecuteParams } from '../../src/types/tool.types';
import { Tools } from '../../src/models/Tools';
import ComposioClient from '@composio/client';
import {
@@ -10,6 +10,7 @@ import {
mockToolExecution,
createSchemaModifier,
} from '../utils/toolExecuteUtils';
+import { MockProvider } from '../utils/mocks/provider.mock';
import { ValidationError } from '../../src/errors/ValidationErrors';
describe('Tools', () => {
@@ -67,8 +68,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
tool_slugs: 'TOOL1,TOOL2',
limit: 9999,
- search: undefined,
- toolkit_slug: undefined,
+ toolkit_versions: 'latest',
});
});
@@ -87,10 +87,9 @@ describe('Tools', () => {
await context.tools.getRawComposioTools(query);
expect(mockClient.tools.list).toHaveBeenCalledWith({
- tool_slugs: undefined,
toolkit_slug: 'github',
limit: 10,
- search: undefined,
+ toolkit_versions: 'latest',
});
});
@@ -110,10 +109,10 @@ describe('Tools', () => {
await context.tools.getRawComposioTools(query);
expect(mockClient.tools.list).toHaveBeenCalledWith({
- tool_slugs: undefined,
toolkit_slug: 'github',
limit: 10,
search: 'test',
+ toolkit_versions: 'latest',
});
});
@@ -133,11 +132,10 @@ describe('Tools', () => {
await context.tools.getRawComposioTools(query);
expect(mockClient.tools.list).toHaveBeenCalledWith({
- tool_slugs: undefined,
toolkit_slug: 'todoist',
limit: 10,
- search: undefined,
scopes: ['task:add', 'task:read'],
+ toolkit_versions: 'latest',
});
});
@@ -158,11 +156,11 @@ describe('Tools', () => {
await context.tools.getRawComposioTools(query);
expect(mockClient.tools.list).toHaveBeenCalledWith({
- tool_slugs: undefined,
toolkit_slug: 'todoist',
limit: 10,
search: 'add task',
scopes: ['task:add'],
+ toolkit_versions: 'latest',
});
});
@@ -221,7 +219,7 @@ describe('Tools', () => {
const result = await context.tools.getRawComposioTools(
{ tools: ['TEST_TOOL'] },
- schemaModifier
+ { modifySchema: schemaModifier }
);
expect(schemaModifier).toHaveBeenCalled();
@@ -242,7 +240,7 @@ describe('Tools', () => {
{
toolkits: ['invalid'],
},
- invalidModifier
+ { modifySchema: invalidModifier }
)
).rejects.toThrow('Invalid schema modifier. Not a function.');
});
@@ -276,7 +274,7 @@ describe('Tools', () => {
const result = await context.tools.getRawComposioToolBySlug(slug);
- expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug);
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, { toolkit_versions: 'latest' });
expect(result.slug).toEqual(toolMocks.transformedTool.slug);
});
@@ -316,7 +314,9 @@ describe('Tools', () => {
mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
- const result = await context.tools.getRawComposioToolBySlug(slug, schemaModifier);
+ const result = await context.tools.getRawComposioToolBySlug(slug, {
+ modifySchema: schemaModifier,
+ });
expect(schemaModifier).toHaveBeenCalled();
expect(result.description).toEqual('Modified description');
@@ -337,7 +337,9 @@ describe('Tools', () => {
const result = await context.tools.get(userId, slug);
- expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, undefined);
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
+ modifySchema: undefined,
+ });
expect(context.mockProvider.wrapTools).toHaveBeenCalledWith(
[toolMocks.transformedTool],
expect.any(Function)
@@ -356,7 +358,7 @@ describe('Tools', () => {
const result = await context.tools.get(userId, filters);
- expect(getRawComposioToolsSpy).toHaveBeenCalledWith(filters, undefined);
+ expect(getRawComposioToolsSpy).toHaveBeenCalledWith(filters, { modifySchema: undefined });
expect(context.mockProvider.wrapTools).toHaveBeenCalled();
expect(result).toEqual('wrapped-tools-collection');
});
@@ -375,7 +377,9 @@ describe('Tools', () => {
await context.tools.get(userId, slug, { modifySchema: schemaModifier });
- expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, schemaModifier);
+ expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
+ modifySchema: schemaModifier,
+ });
});
});
@@ -417,7 +421,7 @@ describe('Tools', () => {
custom_connection_data: undefined,
arguments: body.arguments,
user_id: body.userId,
- version: undefined,
+ version: 'latest',
text: undefined,
});
expect(result).toEqual(toolMocks.toolExecuteResponse);
@@ -442,7 +446,7 @@ describe('Tools', () => {
custom_connection_data: undefined,
arguments: body.arguments,
user_id: body.userId,
- version: undefined,
+ version: 'latest',
text: undefined,
});
expect(result).toEqual(toolMocks.toolExecuteResponse);
@@ -714,4 +718,459 @@ describe('Tools', () => {
);
});
});
+
+ describe('Version Integration Tests', () => {
+ describe('toolkit versions in tool fetching', () => {
+ it('should pass default "latest" version when no version is configured', async () => {
+ const context = createTestContext();
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools({ tools: ['TEST_TOOL'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ tool_slugs: 'TEST_TOOL',
+ limit: 9999,
+ toolkit_versions: 'latest',
+ });
+ });
+
+ it('should pass global version string when configured', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: '20250902_00' as any,
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ toolkits: ['github'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ toolkit_versions: '20250902_00',
+ });
+ });
+
+ it('should pass toolkit-specific versions when configured as object', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ },
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ toolkits: ['github'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ toolkit_versions: {
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ },
+ });
+ });
+
+ it('should pass versions when fetching tools by tool slugs', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ slack: 'latest',
+ },
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ tools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ tool_slugs: 'GITHUB_CREATE_ISSUE,SLACK_SEND_MESSAGE',
+ limit: 9999,
+ toolkit_versions: {
+ github: '20250902_00',
+ slack: 'latest',
+ },
+ });
+ });
+
+ it('should pass versions when searching tools', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: 'latest',
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ search: 'create issue' });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ search: 'create issue',
+ toolkit_versions: 'latest',
+ });
+ });
+ });
+
+ describe('toolkit versions in individual tool retrieval', () => {
+ it('should pass default "latest" version when retrieving single tool', async () => {
+ const context = createTestContext();
+
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
+
+ await context.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
+
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith('GITHUB_CREATE_ISSUE', {
+ toolkit_versions: 'latest',
+ });
+ });
+
+ it('should pass global version when retrieving single tool', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: '20250902_00' as any,
+ });
+
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
+
+ await tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
+
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith('GITHUB_CREATE_ISSUE', {
+ toolkit_versions: '20250902_00',
+ });
+ });
+
+ it('should pass toolkit-specific versions when retrieving single tool', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ },
+ });
+
+ mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
+
+ await tools.getRawComposioToolBySlug('SLACK_SEND_MESSAGE');
+
+ expect(mockClient.tools.retrieve).toHaveBeenCalledWith('SLACK_SEND_MESSAGE', {
+ toolkit_versions: {
+ github: '20250902_00',
+ slack: 'latest',
+ gmail: '20250901_01',
+ },
+ });
+ });
+ });
+
+ describe('toolkit versions in tool execution', () => {
+ it('should use default "latest" version when executing tool without explicit version', async () => {
+ const context = createTestContext();
+ const spies = await mockToolExecution(context.tools);
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { title: 'Test Issue' },
+ connectedAccountId: 'test-account',
+ };
+
+ await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { title: 'Test Issue' },
+ user_id: undefined,
+ version: 'latest', // should use latest as default
+ text: undefined,
+ });
+ });
+
+ it('should use global version when configured', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: '20250902_00' as any,
+ });
+ const spies = await mockToolExecution(tools);
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { title: 'Test Issue' },
+ connectedAccountId: 'test-account',
+ };
+
+ await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { title: 'Test Issue' },
+ user_id: undefined,
+ version: '20250902_00', // should use global version
+ text: undefined,
+ });
+ });
+
+ it('should use toolkit-specific version when configured as object', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ 'test-toolkit': '20250902_00', // Use the actual toolkit slug from mock
+ slack: 'latest',
+ gmail: '20250901_01',
+ },
+ });
+
+ // Mock the tool with test-toolkit (matching the mock data)
+ const testTool = {
+ ...toolMocks.transformedTool,
+ toolkit: { slug: 'test-toolkit', name: 'Test Toolkit' }, // Use actual mock toolkit
+ };
+
+ const spies = await mockToolExecution(tools);
+ // Override the mock to return our custom tool with the correct toolkit
+ spies.getRawComposioToolBySlugSpy.mockReset();
+ spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(testTool as unknown as Tool);
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { title: 'Test Issue' },
+ connectedAccountId: 'test-account',
+ };
+
+ await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { title: 'Test Issue' },
+ user_id: undefined,
+ version: '20250902_00', // should use test-toolkit-specific version
+ text: undefined,
+ });
+ });
+
+ it('should use fallback to "latest" when toolkit not in version mapping', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ slack: 'latest',
+ },
+ });
+
+ // Mock the tool with notion toolkit (not in version mapping)
+ const notionTool = {
+ ...toolMocks.transformedTool,
+ toolkit: { slug: 'notion', name: 'Notion' },
+ };
+
+ const spies = await mockToolExecution(tools);
+ spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(notionTool as unknown as Tool);
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { title: 'Test Page' },
+ connectedAccountId: 'test-account',
+ };
+
+ await tools.execute('NOTION_CREATE_PAGE', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { title: 'Test Page' },
+ user_id: undefined,
+ version: 'latest', // should fallback to latest for unknown toolkit
+ text: undefined,
+ });
+ });
+
+ it('should prioritize explicit version parameter over configured versions', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ slack: 'latest',
+ },
+ });
+
+ const spies = await mockToolExecution(tools);
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { title: 'Test Issue' },
+ connectedAccountId: 'test-account',
+ version: '20250903_00', // explicit version should override config
+ };
+
+ await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { title: 'Test Issue' },
+ user_id: undefined,
+ version: '20250903_00', // explicit version takes precedence
+ text: undefined,
+ });
+ });
+
+ it('should handle tool without toolkit gracefully', async () => {
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250902_00',
+ },
+ });
+
+ // Mock the tool without toolkit
+ const toolWithoutToolkit = {
+ ...toolMocks.transformedTool,
+ toolkit: undefined,
+ };
+
+ const spies = await mockToolExecution(tools);
+ spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(
+ toolWithoutToolkit as unknown as Tool
+ );
+
+ const executeParams: ToolExecuteParams = {
+ arguments: { query: 'test' },
+ connectedAccountId: 'test-account',
+ };
+
+ await tools.execute('SOME_CUSTOM_TOOL', executeParams);
+
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
+ allow_tracing: undefined,
+ connected_account_id: 'test-account',
+ custom_auth_params: undefined,
+ custom_connection_data: undefined,
+ arguments: { query: 'test' },
+ user_id: undefined,
+ version: 'latest', // should fallback to latest for unknown toolkit
+ text: undefined,
+ });
+ });
+ });
+
+ describe('environment variable integration', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = { ...originalEnv };
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('should use environment variable versions when no user config provided', async () => {
+ // Set environment variables
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const mockProvider = new MockProvider();
+ // Pass the processed environment variables to the Tools constructor
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250903_00',
+ slack: 'latest',
+ },
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ toolkits: ['github'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ toolkit_versions: {
+ github: '20250903_00',
+ slack: 'latest',
+ },
+ });
+ });
+
+ it('should prioritize user config over environment variables', async () => {
+ // Set environment variables
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: {
+ github: '20250904_00', // should override env
+ gmail: '20250902_00', // new toolkit not in env
+ },
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ toolkits: ['github'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ toolkit_versions: {
+ github: '20250904_00', // user config wins
+ gmail: '20250902_00', // from user config
+ },
+ });
+ });
+
+ it('should use global version string to override everything', async () => {
+ // Set environment variables
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
+ process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
+
+ const mockProvider = new MockProvider();
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
+ toolkitVersions: '20250905_00' as any, // global version overrides everything
+ });
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await tools.getRawComposioTools({ toolkits: ['github'] });
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ toolkit_slug: 'github',
+ toolkit_versions: '20250905_00', // global version ignores env vars
+ });
+ });
+ });
+ });
});
diff --git a/ts/packages/providers/langchain/README.md b/ts/packages/providers/langchain/README.md
index 332efafbf..76a30e0d0 100644
--- a/ts/packages/providers/langchain/README.md
+++ b/ts/packages/providers/langchain/README.md
@@ -52,6 +52,12 @@ const tools = await composio.tools.get('user123', {
limit: 10,
});
+// Get tools with version control
+const versionedTools = await composio.tools.get('user123', {
+ toolkits: ['gmail'],
+ toolkitVersions: { gmail: '20250909_00' },
+});
+
// Get a specific tool
const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');
```
diff --git a/ts/packages/providers/langchain/test/langchain.test.ts b/ts/packages/providers/langchain/test/langchain.test.ts
index 0838e3455..bd7764d09 100644
--- a/ts/packages/providers/langchain/test/langchain.test.ts
+++ b/ts/packages/providers/langchain/test/langchain.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
import { LangchainProvider } from '../src';
import { Tool } from '@composio/core';
import { DynamicStructuredTool } from '@langchain/core/tools';
@@ -6,30 +6,30 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
describe('LangchainProvider', () => {
let provider: LangchainProvider;
let sampleTool: Tool;
- let executeToolFn: (
- toolSlug: string,
- params: Record<string, unknown>,
- modifiers?: any
- ) => Promise<any>;
+ let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<any>;
beforeEach(() => {
provider = new LangchainProvider();
// Create a real execute function that simulates tool execution
- executeToolFn = async (toolSlug: string, params: Record<string, unknown>) => {
- // Simulate actual tool execution with realistic response
- return {
- data: { toolSlug, params },
- error: null,
- successful: true,
- };
- };
+ executeToolFn = vi
+ .fn()
+ .mockImplementation(async (toolSlug: string, params: Record<string, unknown>) => {
+ // Simulate actual tool execution with realistic response
+ return {
+ data: { toolSlug, params },
+ error: null,
+ successful: true,
+ };
+ });
// Create a real sample tool that matches actual tool structure
sampleTool = {
slug: 'SEARCH_TOOL',
name: 'Search Tool',
description: 'Search for information in the knowledge base',
+ version: '20250909_00',
+ availableVersions: ['20250909_00', '20250901_00'],
inputParameters: {
type: 'object',
properties: {
diff --git a/ts/packages/providers/mastra/test/mastra.test.ts b/ts/packages/providers/mastra/test/mastra.test.ts
index c045f6120..d2ecf5f92 100644
--- a/ts/packages/providers/mastra/test/mastra.test.ts
+++ b/ts/packages/providers/mastra/test/mastra.test.ts
@@ -84,6 +84,8 @@ describe('MastraProvider', () => {
slug: 'test-toolkit',
name: 'Test Toolkit',
},
+ version: '20250909_00',
+ availableVersions: ['20250909_00', '20250901_00'],
tags: [],
};
@@ -202,6 +204,34 @@ describe('MastraProvider', () => {
});
});
+ it('should preserve and pass tool version information when executing', async () => {
+ const toolWithVersion = { ...mockTool, version: '20250101_01' };
+ provider.wrapTool(toolWithVersion, mockExecuteToolFn) as unknown as MockedMastraTool;
+
+ // Extract the execute function from the call to createTool()
+ const executeFunction = (createTool as any).mock.calls[0][0].execute;
+
+ // Test that the version is passed correctly
+ const context = { input: 'version-test' };
+ await executeFunction({ context });
+
+ expect(mockExecuteToolFn).toHaveBeenCalledWith(toolWithVersion.slug, context);
+ });
+
+ it('should handle tools without version information', async () => {
+ const toolWithoutVersion = { ...mockTool, version: undefined };
+ provider.wrapTool(toolWithoutVersion, mockExecuteToolFn) as unknown as MockedMastraTool;
+
+ // Extract the execute function from the call to createTool()
+ const executeFunction = (createTool as any).mock.calls[0][0].execute;
+
+ // Test that undefined version is passed correctly
+ const context = { input: 'no-version-test' };
+ await executeFunction({ context });
+
+ expect(mockExecuteToolFn).toHaveBeenCalledWith(toolWithoutVersion.slug, context);
+ });
+
it('should handle empty context parameter', async () => {
provider.wrapTool(mockTool, mockExecuteToolFn) as unknown as MockedMastraTool;
diff --git a/ts/packages/providers/openai-agents/test/openai-agents.test.ts b/ts/packages/providers/openai-agents/test/openai-agents.test.ts
index 615c2b784..1b9362f71 100644
--- a/ts/packages/providers/openai-agents/test/openai-agents.test.ts
+++ b/ts/packages/providers/openai-agents/test/openai-agents.test.ts
@@ -45,6 +45,8 @@ describe('OpenAIAgentsProvider', () => {
slug: 'test-tool',
name: 'Test Tool',
description: 'A tool for testing',
+ version: '20250909_00',
+ availableVersions: ['20250909_00', '20250901_00'],
inputParameters: {
type: 'object',
properties: {
@@ -110,26 +112,6 @@ describe('OpenAIAgentsProvider', () => {
expect(wrapped._isMockedOpenAIAgentTool).toBe(true);
});
-
- it('should create a function that executes the tool with the right parameters', async () => {
- provider.wrapTool(mockTool, mockExecuteToolFn) as unknown as MockedOpenAIAgentTool;
-
- // Extract the execute function from the call to tool()
- const executeFunction = (createOpenAIAgentTool as any).mock.calls[0][0].execute;
-
- // Test the execute function with an object parameter
- const params = { input: 'test-value' };
- await executeFunction(params);
-
- expect(mockExecuteToolFn).toHaveBeenCalledWith(mockTool.slug, params);
-
- // Reset and test with a JSON string parameter
- vi.clearAllMocks();
- const stringParams = JSON.stringify(params);
- await executeFunction(stringParams);
-
- expect(mockExecuteToolFn).toHaveBeenCalledWith(mockTool.slug, params);
- });
});
describe('wrapTools', () => {
diff --git a/ts/packages/providers/vercel/README.md b/ts/packages/providers/vercel/README.md
index dad7fb19c..bdb0d9fc3 100644
--- a/ts/packages/providers/vercel/README.md
+++ b/ts/packages/providers/vercel/README.md
@@ -51,6 +51,12 @@ const tools = await composio.tools.get('user123', {
limit: 10,
});
+// Get tools with version control
+const versionedTools = await composio.tools.get('user123', {
+ toolkits: ['gmail'],
+ toolkitVersions: { gmail: '20250909_00' },
+});
+
// Get a specific tool
const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');
```
diff --git a/ts/packages/providers/vercel/test/vercel.test.ts b/ts/packages/providers/vercel/test/vercel.test.ts
index d90de0835..160893afb 100644
--- a/ts/packages/providers/vercel/test/vercel.test.ts
+++ b/ts/packages/providers/vercel/test/vercel.test.ts
@@ -45,6 +45,8 @@ describe('VercelProvider', () => {
slug: 'test-tool',
name: 'Test Tool',
description: 'A tool for testing',
+ version: '20250909_00',
+ availableVersions: ['20250909_00', '20250901_00'],
inputParameters: {
type: 'object',
properties: {