@devries-cameron20 / composio-1 / commits / 7077cee68
Fork 0

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)

Co-authored-by: Jayesh Sharma <wjayesh@outlook.com>

Musthaq Ahamad committed Sep 16, 2025 at 12:15 UTC 7077cee688e80d0a262a7f61fe5324e79be3aca4
59 files changed +1900 -240
.changeset/red-walls-sniff.md new
+13
@@ -0,0 +1,13 @@
1 +---
2 +'@composio/core': patch
3 +'@composio/anthropic': patch
4 +'@composio/cloudflare': patch
5 +'@composio/google': patch
6 +'@composio/langchain': patch
7 +'@composio/mastra': patch
8 +'@composio/openai': patch
9 +'@composio/openai-agents': patch
10 +'@composio/vercel': patch
11 +---
12 +
13 +Add tool versioning support
pnpm-lock.yaml
+40 -8
@@ -546,6 +546,22 @@ importers:
546 specifier: ^5.8.3
547 version: 5.8.3
548
549 + ts/examples/versioning:
550 + dependencies:
551 + '@composio/core':
552 + specifier: workspace:*
553 + version: link:../../packages/core
554 + dotenv:
555 + specifier: ^16.4.1
556 + version: 16.6.1
557 + devDependencies:
558 + '@types/bun':
559 + specifier: ^1.2.9
560 + version: 1.2.16
561 + typescript:
562 + specifier: ^5.8.3
563 + version: 5.8.3
564 +
565 ts/packages/cli:
566 dependencies:
567 '@clack/prompts':
@@ -646,8 +662,8 @@ importers:
662 ts/packages/core:
663 dependencies:
664 '@composio/client':
649 - specifier: 0.1.0-alpha.35
650 - version: 0.1.0-alpha.35
665 + specifier: 0.1.0-alpha.36
666 + version: 0.1.0-alpha.36
667 '@composio/json-schema-to-zod':
668 specifier: 0.1.15
669 version: 0.1.15
@@ -1273,8 +1289,8 @@ packages:
1289 '@composio/client@0.1.0-alpha.31':
1290 resolution: {integrity: sha512-DVPVCMDXzoQn1aUZx38e8s5+gA/J/c6FpVfS1rzUnMKCRSuXXrOoKXFAvoRME5pcaKN2Wjux5ARyvIPBugNoMA==}
1291
1276 - '@composio/client@0.1.0-alpha.35':
1277 - resolution: {integrity: sha512-Db40bfq4BqVdjWf7JXzXH0zH9LtRPikZkF8+GoVFYRrDJXfHzNkhXIb+7xksCDb0mLww4LEa1cDw8jX5prA3nA==}
1292 + '@composio/client@0.1.0-alpha.36':
1293 + resolution: {integrity: sha512-YRsx5rRWFoT2kyzYTsJ5lDd6dZI2KmkLxdnaQdACc7A/DkFHzhZraSROaYLElYUP+2ScK4WynVU6+IaHzYn2KA==}
1294
1295 '@composio/json-schema-to-zod@0.1.15':
1296 resolution: {integrity: sha512-GaeFd60EozDN4zHZUU4mLp+kqO11ZzUyMaljKbdBNHUsq+TYgomWvoZESyUcDqyvqHx+4+V4Smg91s8Rd7bB4Q==}
@@ -7960,7 +7976,7 @@ snapshots:
7976
7977 '@composio/client@0.1.0-alpha.31': {}
7978
7963 - '@composio/client@0.1.0-alpha.35': {}
7979 + '@composio/client@0.1.0-alpha.36': {}
7980
7981 '@composio/json-schema-to-zod@0.1.15':
7982 dependencies:
@@ -11188,6 +11204,14 @@ snapshots:
11204 chai: 5.2.0
11205 tinyrainbow: 2.0.0
11206
11207 + '@vitest/mocker@3.2.4(vite@6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
11208 + dependencies:
11209 + '@vitest/spy': 3.2.4
11210 + estree-walker: 3.0.3
11211 + magic-string: 0.30.17
11212 + optionalDependencies:
11213 + vite: 6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
11214 +
11215 '@vitest/mocker@3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
11216 dependencies:
11217 '@vitest/spy': 3.2.4
@@ -11196,6 +11220,14 @@ snapshots:
11220 optionalDependencies:
11221 vite: 6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
11222
11223 + '@vitest/mocker@3.2.4(vite@6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))':
11224 + dependencies:
11225 + '@vitest/spy': 3.2.4
11226 + estree-walker: 3.0.3
11227 + magic-string: 0.30.17
11228 + optionalDependencies:
11229 + vite: 6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
11230 +
11231 '@vitest/pretty-format@3.2.4':
11232 dependencies:
11233 tinyrainbow: 2.0.0
@@ -11225,7 +11257,7 @@ snapshots:
11257 sirv: 3.0.1
11258 tinyglobby: 0.2.14
11259 tinyrainbow: 2.0.0
11228 - vitest: 3.2.4(@types/node@22.15.32)(@vitest/ui@3.2.4)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
11260 + vitest: 3.2.4(@types/node@24.0.3)(@vitest/ui@3.2.4)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0)
11261
11262 '@vitest/utils@3.2.4':
11263 dependencies:
@@ -14392,7 +14424,7 @@ snapshots:
14424 dependencies:
14425 '@types/chai': 5.2.2
14426 '@vitest/expect': 3.2.4
14395 - '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
14427 + '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@20.19.1)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
14428 '@vitest/pretty-format': 3.2.4
14429 '@vitest/runner': 3.2.4
14430 '@vitest/snapshot': 3.2.4
@@ -14476,7 +14508,7 @@ snapshots:
14508 dependencies:
14509 '@types/chai': 5.2.2
14510 '@vitest/expect': 3.2.4
14479 - '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@22.15.32)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
14511 + '@vitest/mocker': 3.2.4(vite@6.3.5(@types/node@24.0.3)(jiti@1.21.7)(tsx@4.20.3)(yaml@2.8.0))
14512 '@vitest/pretty-format': 3.2.4
14513 '@vitest/runner': 3.2.4
14514 '@vitest/snapshot': 3.2.4
python/composio/__init__.py
+10
@@ -5,6 +5,12 @@ from .core.models.tools import (
5 schema_modifier,
6 )
7 from .sdk import Composio
8 +from .types import (
9 + ToolkitLatestVersion,
10 + ToolkitVersion,
11 + ToolkitVersionParam,
12 + ToolkitVersions,
13 +)
14
15 __all__ = (
16 "Composio",
@@ -12,4 +18,8 @@ __all__ = (
18 "before_execute",
19 "schema_modifier",
20 "__version__",
21 + "ToolkitLatestVersion",
22 + "ToolkitVersion",
23 + "ToolkitVersions",
24 + "ToolkitVersionParam",
25 )
python/composio/core/models/tools.py
+32 -3
@@ -24,6 +24,8 @@ from composio.core.provider.none_agentic import (
24 NoneAgenticProviderExecuteFn,
25 )
26 from composio.exceptions import InvalidParams, NotFoundError
27 +from composio.types import ToolkitVersionParam
28 +from composio.utils.toolkit_version import get_toolkit_version
29
30 from ._modifiers import (
31 Modifiers,
@@ -56,6 +58,7 @@ class Tools(Resource, t.Generic[TProvider]):
58 client: HttpClient,
59 provider: TProvider,
60 file_download_dir: t.Optional[str] = None,
61 + toolkit_versions: t.Optional[ToolkitVersionParam] = None,
62 ):
63 """
64 Initialize the tools resource.
@@ -63,11 +66,13 @@ class Tools(Resource, t.Generic[TProvider]):
66 :param client: The client to use for the tools resource.
67 :param provider: The provider to use for the tools resource.
68 :param file_download_dir: Output directory for downloadable files
69 + :param toolkit_versions: The versions of the toolkits to use. Defaults to 'latest' if not provided.
70 """
71 self._client = client
72 self._custom_tools = CustomTools(client)
73 self._tool_schemas: t.Dict[str, Tool] = {}
74 self._file_helper = FileHelper(client=self._client, outdir=file_download_dir)
75 + self._toolkit_versions = toolkit_versions or "latest"
76
77 self.custom_tool = self._custom_tools.register
78 self.provider = provider
@@ -92,7 +97,12 @@ class Tools(Resource, t.Generic[TProvider]):
97 try:
98 return t.cast(Tool, self._custom_tools[slug])
99 except KeyError:
95 - return t.cast(Tool, self._client.tools.retrieve(tool_slug=slug))
100 + return t.cast(
101 + Tool,
102 + self._client.tools.retrieve(
103 + tool_slug=slug, toolkit_versions=self._toolkit_versions
104 + ),
105 + )
106
107 def get_raw_composio_tools(
108 self,
@@ -116,7 +126,10 @@ class Tools(Resource, t.Generic[TProvider]):
126 tools_list.extend(custom_tools)
127 if len(tools):
128 tools_list.extend(
119 - self._client.tools.list(tool_slugs=",".join(tools)).items
129 + self._client.tools.list(
130 + tool_slugs=",".join(tools),
131 + toolkit_versions=self._toolkit_versions,
132 + ).items
133 )
134
135 # Search tools by toolkit slugs and search term
@@ -129,6 +142,7 @@ class Tools(Resource, t.Generic[TProvider]):
142 search=search if search else self._client.not_given,
143 scopes=scopes,
144 limit=limit,
145 + toolkit_versions=self._toolkit_versions,
146 ).items
147 )
148 return tools_list
@@ -321,6 +335,7 @@ class Tools(Resource, t.Generic[TProvider]):
335 user_id: t.Optional[str] = None,
336 text: t.Optional[str] = None,
337 version: t.Optional[str] = None,
338 + toolkit_versions: t.Optional[ToolkitVersionParam] = None,
339 ) -> ToolExecutionResponse:
340 """Execute a tool"""
341 return t.cast(
@@ -346,6 +361,9 @@ class Tools(Resource, t.Generic[TProvider]):
361 user_id=user_id if user_id is not None else self._client.not_given,
362 text=text if text is not None else self._client.not_given,
363 version=version if version is not None else self._client.not_given,
364 + toolkit_versions=toolkit_versions
365 + if toolkit_versions is not None
366 + else self._client.not_given,
367 ).model_dump(
368 exclude={
369 "log_id",
@@ -367,6 +385,7 @@ class Tools(Resource, t.Generic[TProvider]):
385 user_id: t.Optional[str] = None,
386 text: t.Optional[str] = None,
387 version: t.Optional[str] = None,
388 + toolkit_versions: t.Optional[ToolkitVersionParam] = None,
389 modifiers: t.Optional[Modifiers] = None,
390 ) -> ToolExecutionResponse:
391 """
@@ -384,16 +403,25 @@ class Tools(Resource, t.Generic[TProvider]):
403 :param user_id: The ID of the user to execute the tool for.
404 :param text: The text to pass to the tool.
405 :param version: The version of the tool to execute.
406 + :param toolkit_versions: Toolkit versions to use for execution, overrides the SDK-level configuration.
407 :param modifiers: The modifiers to apply to the tool.
408 :return: The response from the tool.
409 """
410 + # Use provided toolkit_versions or fall back to instance-level versions
411 + effective_toolkit_versions = toolkit_versions or self._toolkit_versions
412 +
413 tool = self._tool_schemas.get(slug)
414 if tool is None and self._custom_tools.get(slug=slug) is not None:
415 tool = self._custom_tools[slug].info
416 self._tool_schemas[slug] = tool
417
418 if tool is None:
396 - tool = t.cast(Tool, self._client.tools.retrieve(tool_slug=slug))
419 + tool = t.cast(
420 + Tool,
421 + self._client.tools.retrieve(
422 + tool_slug=slug, toolkit_versions=effective_toolkit_versions
423 + ),
424 + )
425 self._tool_schemas[slug] = tool
426
427 if modifiers is not None:
@@ -440,6 +468,7 @@ class Tools(Resource, t.Generic[TProvider]):
468 user_id=user_id,
469 text=text,
470 version=version,
471 + toolkit_versions=effective_toolkit_versions,
472 )
473 )
474 response = self._file_helper.substitute_file_downloads(
python/composio/sdk.py
+11
@@ -17,7 +17,9 @@ from composio.core.models import (
17 from composio.core.models.base import allow_tracking
18 from composio.core.provider import TProvider
19 from composio.core.provider._openai import OpenAIProvider
20 +from composio.types import ToolkitVersionParam
21 from composio.utils.logging import WithLogger
22 +from composio.utils.toolkit_version import get_toolkit_versions
23
24 _DEFAULT_PROVIDER = OpenAIProvider()
25
@@ -30,6 +32,7 @@ class SDKConfig(te.TypedDict):
32 max_retries: te.NotRequired[int]
33 allow_tracking: te.NotRequired[bool]
34 file_download_dir: te.NotRequired[str]
35 + toolkit_versions: te.NotRequired[ToolkitVersionParam]
36
37
38 class Composio(t.Generic[TProvider], WithLogger):
@@ -53,12 +56,19 @@ class Composio(t.Generic[TProvider], WithLogger):
56 :param base_url: The base URL to use for the SDK.
57 :param timeout: The timeout to use for the SDK.
58 :param max_retries: The maximum number of retries to use for the SDK.
59 + :param toolkit_versions: The versions of the toolkits to use. Can be:
60 + - A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits
61 + - A dict mapping toolkit names to specific versions
62 + - None to use 'latest' as default
63 """
64 WithLogger.__init__(self)
65 api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))
66 if not api_key:
67 raise exceptions.ApiKeyNotProvidedError()
68
69 + # Process toolkit versions
70 + toolkit_versions = get_toolkit_versions(kwargs.get("toolkit_versions"))
71 +
72 allow_tracking.set(kwargs.get("allow_tracking", True))
73 self._client = HttpClient(
74 environment=kwargs.get("environment", "production"),
@@ -73,6 +83,7 @@ class Composio(t.Generic[TProvider], WithLogger):
83 client=self._client,
84 provider=self.provider,
85 file_download_dir=kwargs.get("file_download_dir"),
86 + toolkit_versions=toolkit_versions,
87 )
88 self.toolkits = Toolkits(client=self._client)
89 self.triggers = Triggers(client=self._client)
python/composio/types.py
+18
@@ -1,3 +1,7 @@
1 +import typing as t
2 +
3 +import typing_extensions as te
4 +
5 from composio.client.types import Tool
6 from composio.core.models.connected_accounts import auth_scheme
7 from composio.core.models.custom_tools import ExecuteRequestFn
@@ -9,7 +13,16 @@ from composio.core.models.tools import (
13 from composio.core.models.triggers import TriggerEvent
14 from composio.core.provider.base import TTool, TToolCollection
15
16 +# Tool versioning types
17 +ToolkitLatestVersion = te.Literal["latest"]
18 +ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"
19 +ToolkitVersions = t.Dict[str, ToolkitVersion]
20 +ToolkitVersionParam = t.Union[
21 + str, ToolkitVersions, None
22 +] # String can be any global version
23 +
24 __all__ = [
25 + # Existing types
26 "Tool",
27 "TTool",
28 "TToolCollection",
@@ -19,4 +32,9 @@ __all__ = [
32 "TriggerEvent",
33 "Modifiers",
34 "auth_scheme",
35 + # New tool versioning types
36 + "ToolkitLatestVersion",
37 + "ToolkitVersion",
38 + "ToolkitVersions",
39 + "ToolkitVersionParam",
40 ]
python/composio/utils/toolkit_version.py new
+81
@@ -0,0 +1,81 @@
1 +"""
2 +Utilities for handling toolkit versions.
3 +"""
4 +
5 +import os
6 +import typing as t
7 +
8 +from composio.types import ToolkitVersion, ToolkitVersionParam, ToolkitVersions
9 +
10 +
11 +def get_toolkit_version(
12 + toolkit_slug: str, toolkit_versions: t.Optional[ToolkitVersionParam] = None
13 +) -> ToolkitVersion:
14 + """
15 + Gets the version for a specific toolkit based on the provided toolkit versions configuration.
16 +
17 + :param toolkit_slug: The slug/name of the toolkit to get the version for
18 + :param toolkit_versions: Optional toolkit versions configuration (string for global version
19 + or dict mapping toolkit slugs to versions)
20 + :return: The toolkit version to use - either the specific version from config, or 'latest' as fallback
21 + """
22 + # If toolkit_versions is a string, use it as a global version for all toolkits
23 + if isinstance(toolkit_versions, str):
24 + return toolkit_versions
25 +
26 + # If toolkit_versions is a dict mapping, look up the specific toolkit version
27 + if isinstance(toolkit_versions, dict) and len(toolkit_versions) > 0:
28 + return toolkit_versions.get(toolkit_slug, "latest")
29 +
30 + # Else use 'latest'
31 + return "latest"
32 +
33 +
34 +def get_toolkit_versions(
35 + default_versions: t.Optional[ToolkitVersionParam] = None,
36 +) -> ToolkitVersionParam:
37 + """
38 + Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
39 +
40 + Priority order:
41 + 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")
42 + 2. User-provided toolkit version mappings (default_versions dict)
43 + 3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
44 + 4. Fallback to 'latest' if no versions are configured
45 +
46 + :param default_versions: Optional default versions configuration (string for global version
47 + or dict mapping toolkit names to versions). String can be any version
48 + like "latest", "20250906_01", etc.
49 + :return: Toolkit versions configuration - either a global version string,
50 + toolkit-specific version mapping, or 'latest'
51 + """
52 + # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits
53 + if default_versions and isinstance(default_versions, str):
54 + return default_versions
55 +
56 + # Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
57 + toolkit_versions_from_env: ToolkitVersions = {}
58 + for key, value in os.environ.items():
59 + if key.startswith("COMPOSIO_TOOLKIT_VERSION_"):
60 + toolkit_name = key.replace("COMPOSIO_TOOLKIT_VERSION_", "")
61 + toolkit_versions_from_env[toolkit_name.lower()] = value
62 +
63 + # If the provided default versions is a dict, normalize the keys to be lower case
64 + # Use user provided values as overrides
65 + user_provided_toolkit_versions: ToolkitVersions = {}
66 + if default_versions and isinstance(default_versions, dict):
67 + user_provided_toolkit_versions = {
68 + key.lower(): value for key, value in default_versions.items()
69 + }
70 +
71 + # Final toolkit versions
72 + toolkit_versions = {
73 + **toolkit_versions_from_env,
74 + **user_provided_toolkit_versions,
75 + }
76 +
77 + # If the toolkit_versions are empty, use 'latest'
78 + if len(toolkit_versions) == 0:
79 + return "latest"
80 +
81 + return toolkit_versions
python/providers/anthropic/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-anthropic"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your Anthropic LLMs."
5 readme = "README.md"
6 requires-python = ">=3.10,<4"
python/providers/anthropic/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_anthropic",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Anthropic LLMs.",
python/providers/autogen/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-autogen"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your autogen agent."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/autogen/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_autogen",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Autogen agent.",
python/providers/crewai/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-crewai"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your CrewAI agent."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/crewai/setup.py
+1 -1
@@ -6,7 +6,7 @@ from setuptools import setup
6
7 setup(
8 name="composio_crewai",
9 - version="0.8.10",
9 + version="0.8.11",
10 author="Composio",
11 author_email="tech@composio.dev",
12 description="Use Composio to get an array of tools with your CrewAI agent.",
python/providers/gemini/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-gemini"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your Gemini agent."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/gemini/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_gemini",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Gemini agent.",
python/providers/google/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-google"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/google/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_google",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
python/providers/google_adk/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-google-adk"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/google_adk/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_google_adk",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
python/providers/langchain/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-langchain"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your Langchain agent."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/langchain/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_langchain",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your Langchain agent.",
python/providers/langgraph/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-langgraph"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get array of tools with LangGraph Agent Workflows."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/langgraph/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_langgraph",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get array of tools with LangGraph Agent Workflows",
python/providers/llamaindex/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-llamaindex"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get array of tools with LlamaIndex Agent Workflows."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/llamaindex/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_llamaindex",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get array of tools with LlamaIndex Agent Workflows",
python/providers/openai/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-openai"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get an array of tools with your OpenAI Function Call."
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/openai/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9 setup(
10 name="composio_openai",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get an array of tools with your OpenAI Function Call.",
python/providers/openai_agents/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio-openai-agents"
3 -version = "0.8.10"
3 +version = "0.8.11"
4 description = "Use Composio to get array of strongly typed tools for OpenAI Agents"
5 readme = "README.md"
6 requires-python = ">=3.9,<4"
python/providers/openai_agents/setup.py
+1 -1
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
8
9 setup(
10 name="composio_openai_agents",
11 - version="0.8.10",
11 + version="0.8.11",
12 author="Composio",
13 author_email="tech@composio.dev",
14 description="Use Composio to get array of strongly typed tools for OpenAI Agents",
python/pyproject.toml
+1 -1
@@ -1,6 +1,6 @@
1 [project]
2 name = "composio"
3 -version = "0.8.12"
3 +version = "0.8.13"
4 description = "SDK for integrating Composio with your applications."
5 readme = "README.md"
6 requires-python = ">=3.10,<4"
ts/README.md
+5
@@ -78,6 +78,9 @@ const tools = await composio.tools.get('default', {
78 toolkits: ['github'],
79 });
80
81 +// Get a specific tool
82 +const specificTool = await composio.tools.get('default', 'GITHUB_GET_REPOS');
83 +
84 // Execute a tool
85 const result = await composio.tools.execute('GITHUB_GET_REPO', {
86 userId: 'default',
@@ -110,6 +113,7 @@ const tools = await composio.tools.get('default', {
113 toolkits: ['github'],
114 });
115
116 +
117 // Create a chat completion with the tools
118 const completion = await openai.chat.completions.create({
119 model: 'gpt-4',
@@ -294,6 +298,7 @@ For detailed information about both automated and manual release processes, plea
298 - `COMPOSIO_BASE_URL`: Custom API base URL (optional)
299 - `COMPOSIO_LOG_LEVEL`: Logging level (silent, error, warn, info, debug)
300 - `COMPOSIO_DISABLE_TELEMETRY`: Disable telemetry when set to "true"
301 +- `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>`: Specific version for a toolkit (e.g., `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`)
302 - `DEVELOPMENT`: Development mode flag
303 - `CI`: CI environment flag
304
ts/docs/api/tools.md
+100 -29
@@ -6,39 +6,58 @@ The `Tools` class provides methods to list, retrieve, and execute tools from var
6
7 ### get(userId, filters, options?)
8
9 -Retrieves tools based on the provided filters.
9 +Retrieves and wraps tools based on the provided filters. Tool versions are controlled at the Composio SDK initialization level through the `toolkitVersions` configuration.
10 +
11 +#### Overload 1: Get multiple tools with filters
12
13 ```typescript
14 // Get tools from a specific toolkit
15 const githubTools = await composio.tools.get('default', {
16 toolkits: ['github'],
15 - limit: 10,
17 + limit: 10
18 });
19
20 // Get tools with search
21 const searchTools = await composio.tools.get('default', {
20 - search: 'user',
22 + search: 'user'
23 +});
24 +
25 +// Get tools with schema modifications
26 +const customizedTools = await composio.tools.get('default', {
27 + toolkits: ['github'],
28 + limit: 5
29 +}, {
30 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
31 + return { ...schema, description: 'Custom description' };
32 + }
33 });
34 +```
35
36 +**Parameters:**
37 +- `userId` (string): The user ID to get the tools for
38 +- `filters` (ToolListParams): Filters object to specify which tools to retrieve
39 +- `options` (ProviderOptions): Optional provider options including modifiers
40 +
41 +#### Overload 2: Get a specific tool by slug
42 +
43 +```typescript
44 // Get a specific tool by slug
45 const tool = await composio.tools.get('default', 'GITHUB_GET_REPO');
46
47 // Get a tool with schema modifications
27 -const tool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
28 - modifySchema: (toolSlug, toolkitSlug, schema) => {
29 - // Customize the tool schema
30 - return { ...schema, description: 'Custom description' };
31 - },
48 +const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {
49 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
50 + return { ...schema, description: 'Enhanced GitHub repository tool' };
51 + }
52 });
53 ```
54
55 **Parameters:**
36 -
37 -- `userId` (string): The user ID to get the tools for
38 -- `filters` (ToolListParams | string): Either a slug string or filters object
56 +- `userId` (string): The user ID to get the tool for
57 +- `slug` (string): The slug of the specific tool to fetch
58 - `options` (ProviderOptions): Optional provider options including modifiers
59
41 -**Returns:** The wrapped tools collection, formatted according to the provider
60 +**Returns:** The wrapped tools collection, formatted according to the provider being used
61
62 ### execute(slug, body, modifiers?)
63
@@ -118,48 +137,99 @@ const customTool = await composio.tools.createCustomTool({
137
138 **Returns:** Promise<Tool> - The created custom tool
139
121 -### getRawComposioTools(query?, modifier?)
140 +### getRawComposioTools(query, options?)
141
123 -Lists all tools available in the Composio SDK including custom tools.
142 +Lists all tools available in the Composio SDK including custom tools. This method provides direct access to tool data without provider-specific wrapping.
143
144 ```typescript
126 -// Get all tools
127 -const tools = await composio.tools.getRawComposioTools();
145 +// Get tools from specific toolkits
146 +const githubTools = await composio.tools.getRawComposioTools({
147 + toolkits: ['github'],
148 + limit: 10
149 +});
150
129 -// Get tools with filters
151 +// Get specific tools by slug
152 +const specificTools = await composio.tools.getRawComposioTools({
153 + tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
154 +});
155 +
156 +// Get tools from specific toolkits
157 const githubTools = await composio.tools.getRawComposioTools({
158 toolkits: ['github'],
132 - important: true,
159 + limit: 10
160 });
161
162 // Get tools with schema transformation
136 -const tools = await composio.tools.getRawComposioTools({}, (toolSlug, toolkitSlug, tool) => {
137 - // Add custom properties to tool schema
138 - return { ...tool, customProperty: 'value' };
163 +const customizedTools = await composio.tools.getRawComposioTools({
164 + toolkits: ['github'],
165 + limit: 5
166 +}, {
167 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
168 + return {
169 + ...schema,
170 + customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
171 + tags: [...(schema.tags || []), 'customized']
172 + };
173 + }
174 +});
175 +
176 +// Search for tools
177 +const searchResults = await composio.tools.getRawComposioTools({
178 + search: 'user management'
179 });
180 ```
181
182 **Parameters:**
183
144 -- `query` (ToolListParams): Optional query parameters to filter the tools
145 -- `modifier` (TransformToolSchemaModifier): Optional function to transform tool schemas
184 +- `query` (ToolListParams): Query parameters to filter the tools (required)
185 +- `options` (GetRawComposioToolsOptions): Optional configuration for tool retrieval
186 + - `modifySchema` (TransformToolSchemaModifier): Function to transform tool schemas
187
188 **Returns:** Promise<ToolList> - List of tools matching the query criteria
189
149 -### getRawComposioToolBySlug(slug, modifier?)
190 +### getRawComposioToolBySlug(slug, options?)
191
151 -Retrieves a tool by its Slug.
192 +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.
193
194 ```typescript
154 -const tool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
195 +// Get a tool by slug
196 +const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
197 +
198 +// Get a tool with schema transformation
199 +const customizedTool = await composio.tools.getRawComposioToolBySlug(
200 + 'SLACK_SEND_MESSAGE',
201 + {
202 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
203 + return {
204 + ...schema,
205 + description: `Enhanced ${schema.description} with custom modifications`,
206 + customMetadata: {
207 + lastModified: new Date().toISOString(),
208 + toolkit: toolkitSlug
209 + }
210 + };
211 + }
212 + }
213 +);
214 +
215 +// Access tool properties
216 +const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
217 +console.log({
218 + slug: githubTool.slug,
219 + name: githubTool.name,
220 + toolkit: githubTool.toolkit?.name,
221 + version: githubTool.version,
222 + availableVersions: githubTool.availableVersions
223 +});
224 ```
225
226 **Parameters:**
227
159 -- `slug` (string): The ID of the tool to be retrieved
160 -- `modifier` (TransformToolSchemaModifier): Optional function to transform tool schema
228 +- `slug` (string): The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
229 +- `options` (GetRawComposioToolBySlugOptions): Optional configuration for tool retrieval
230 + - `modifySchema` (TransformToolSchemaModifier): Function to transform the tool schema
231
162 -**Returns:** Promise<Tool> - The tool
232 +**Returns:** Promise<Tool> - The requested tool with its complete schema and metadata
233
234 ## Types
235
@@ -282,3 +352,4 @@ interface CustomToolOptions {
352 handler: (params: ToolExecuteParams, context: ExecuteMetadata) => Promise<ToolExecuteResponse>; // Handler function
353 }
354 ```
355 +
ts/docs/core-concepts.md
+6
@@ -28,6 +28,7 @@ const tools = await composio.tools.get('default', {
28 toolkits: ['github'],
29 });
30
31 +
32 // ❌ This could expose other users' data
33 const result = await composio.tools.execute('GITHUB_GET_REPO', {
34 userId: 'default',
@@ -49,6 +50,11 @@ const tools = await composio.tools.get(userId, {
50 toolkits: ['github'],
51 });
52
53 +// Get tools for a specific user
54 +const userTools = await composio.tools.get(userId, {
55 + toolkits: ['github'],
56 +});
57 +
58 const result = await composio.tools.execute('GITHUB_GET_REPO', {
59 userId: userId,
60 arguments: { owner: 'example', repo: 'repo' },
ts/docs/getting-started.md
+1
@@ -42,6 +42,7 @@ const composio = new Composio({
42 baseURL: 'https://api.composio.dev', // Optional: Custom API endpoint
43 allowTracking: true, // Optional: Enable/disable telemetry
44 provider: new OpenAIProvider(), // Optional: Custom provider
45 + toolkitVersions: { github: '20250909_00', slack: 'latest' }, // Optional: Toolkit versions
46 });
47 ```
48
ts/examples/tools/src/versioning.ts new
+124
@@ -0,0 +1,124 @@
1 +import { Composio } from '@composio/core';
2 +
3 +const composio = new Composio();
4 +
5 +async function demonstrateRawToolFetching() {
6 + console.log('=== Raw Composio Tool Fetching Examples ===\n');
7 +
8 + // Example 1: Get a single tool by slug (latest version)
9 + console.log('1. Getting latest version of HACKERNEWS_GET_USER:');
10 + const latestTool = await composio.tools.getRawComposioToolBySlug('HACKERNEWS_GET_USER');
11 + console.log(`Tool: ${latestTool.name} (v${latestTool.version})`);
12 + console.log(`Available versions: ${latestTool.availableVersions?.join(', ')}\n`);
13 +
14 + // Example 2: Get a specific version of a tool
15 + console.log('2. Getting specific version of a tool:');
16 + try {
17 + const specificVersionTool = await composio.tools.getRawComposioToolBySlug(
18 + 'HACKERNEWS_GET_USER',
19 + '20250909_00' // specific version
20 + );
21 + console.log(`Tool: ${specificVersionTool.name} (v${specificVersionTool.version})\n`);
22 + } catch (error) {
23 + console.log('Note: Specific version may not be available, using latest instead\n');
24 + }
25 +
26 + // Example 3: Get a tool with schema transformation
27 + console.log('3. Getting tool with schema transformation:');
28 + const customizedTool = await composio.tools.getRawComposioToolBySlug(
29 + 'HACKERNEWS_GET_USER',
30 + 'latest',
31 + {
32 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
33 + return {
34 + ...schema,
35 + description: `Enhanced ${schema.description} - Modified at ${new Date().toISOString()}`,
36 + customMetadata: {
37 + toolkit: toolkitSlug,
38 + modifiedBy: 'versioning-example',
39 + features: ['enhanced-logging', 'custom-validation']
40 + }
41 + };
42 + }
43 + }
44 + );
45 + console.log(`Modified tool description: ${customizedTool.description}`);
46 + console.log(`Custom metadata:`, (customizedTool as any).customMetadata);
47 + console.log();
48 +
49 + // Example 4: Get multiple tools with filters
50 + console.log('4. Getting multiple tools with filters:');
51 + const hackerNewsTools = await composio.tools.getRawComposioTools({
52 + toolkits: ['hackernews'],
53 + limit: 3
54 + });
55 + console.log(`Found ${hackerNewsTools.length} HackerNews tools:`);
56 + hackerNewsTools.forEach(tool => {
57 + console.log(`- ${tool.slug}: ${tool.name} (v${tool.version})`);
58 + });
59 + console.log();
60 +
61 + // Example 5: Get tools with version control
62 + console.log('5. Getting tools with version control:');
63 + const versionedTools = await composio.tools.getRawComposioTools({
64 + toolkits: ['hackernews'],
65 + toolkitVersions: 'latest' // or specify specific versions: { hackernews: '20250909_00' }
66 + });
67 + console.log(`Found ${versionedTools.length} versioned tools:`);
68 + versionedTools.forEach(tool => {
69 + console.log(`- ${tool.slug} (v${tool.version})`);
70 + });
71 + console.log();
72 +
73 + // Example 6: Get tools with schema transformation
74 + console.log('6. Getting multiple tools with schema transformation:');
75 + const enhancedTools = await composio.tools.getRawComposioTools({
76 + toolkits: ['hackernews'],
77 + limit: 2
78 + }, {
79 + modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
80 + return {
81 + ...schema,
82 + tags: [...(schema.tags || []), 'enhanced', 'example'],
83 + customProperties: {
84 + lastFetched: new Date().toISOString(),
85 + exampleUsage: `This tool (${toolSlug}) is from the ${toolkitSlug} toolkit`
86 + }
87 + };
88 + }
89 + });
90 +
91 + console.log('Enhanced tools with custom properties:');
92 + enhancedTools.forEach(tool => {
93 + console.log(`- ${tool.slug}:`);
94 + console.log(` Tags: ${tool.tags?.join(', ')}`);
95 + console.log(` Custom properties:`, (tool as any).customProperties);
96 + });
97 + console.log();
98 +
99 + // Example 7: Search for tools
100 + console.log('7. Searching for tools:');
101 + try {
102 + const searchResults = await composio.tools.getRawComposioTools({
103 + search: 'user'
104 + });
105 + console.log(`Found ${searchResults.length} tools matching 'user':`);
106 + searchResults.slice(0, 3).forEach(tool => {
107 + console.log(`- ${tool.slug}: ${tool.name}`);
108 + });
109 + } catch (error) {
110 + console.log('Search might require additional parameters');
111 + }
112 + console.log();
113 +
114 + // Example 8: Using the wrapped tools (comparison)
115 + console.log('8. Comparison with wrapped tools:');
116 + const wrappedTools = await composio.tools.get('default', {
117 + tools: ['HACKERNEWS_GET_USER']
118 + });
119 + console.log('Wrapped tools (provider-specific format):');
120 + console.log(typeof wrappedTools, Object.keys(wrappedTools));
121 +}
122 +
123 +// Run the demonstration
124 +demonstrateRawToolFetching().catch(console.error);
ts/examples/versioning/.env.example new
+7
@@ -0,0 +1,7 @@
1 +# Composio API Key - Get it from https://app.composio.dev
2 +COMPOSIO_API_KEY=your_composio_api_key_here
3 +COMPOSIO_TOOLKIT_VERSION_HACKERNEWS=20250911_00
4 +
5 +# Add other environment variables as needed for your example
6 +# OPENAI_API_KEY=your_openai_api_key_here
7 +# ANTHROPIC_API_KEY=your_anthropic_api_key_here
ts/examples/versioning/README.md new
+53
@@ -0,0 +1,53 @@
1 +# Versioning Example
2 +
3 +This example demonstrates how to use Composio SDK for versioning.
4 +
5 +## Setup
6 +
7 +1. **Install dependencies:**
8 + ```bash
9 + pnpm install
10 + ```
11 +
12 +2. **Configure environment:**
13 + ```bash
14 + cp .env.example .env
15 + ```
16 +
17 + Then edit `.env` and add your API keys:
18 + - `COMPOSIO_API_KEY`: Get it from [Composio Dashboard](https://app.composio.dev)
19 +
20 +## Running the Example
21 +
22 +```bash
23 +# Run the example
24 +pnpm start
25 +
26 +# Run in development mode (with file watching)
27 +pnpm dev
28 +```
29 +
30 +## What This Example Does
31 +
32 +- Initializes Composio SDK
33 +- Fetches available tools
34 +- Demonstrates basic usage patterns
35 +
36 +## Customization
37 +
38 +Edit `src/index.ts` to:
39 +- Add specific apps you want to integrate with
40 +- Implement your business logic
41 +- Add error handling and logging
42 +
43 +## Related Examples
44 +
45 +- [OpenAI Example](../openai) - Shows integration with OpenAI
46 +- [LangChain Example](../langchain) - Shows integration with LangChain
47 +- [More Examples](../) - Browse all available examples
48 +
49 +## Support
50 +
51 +- [Documentation](https://docs.composio.dev)
52 +- [Discord Community](https://discord.gg/composio)
53 +- [GitHub Issues](https://github.com/composio/composio/issues)
ts/examples/versioning/package.json new
+24
@@ -0,0 +1,24 @@
1 +{
2 + "name": "versioning-example",
3 + "private": true,
4 + "version": "0.1.0",
5 + "description": "Example project for Versioning",
6 + "main": "src/index.ts",
7 + "scripts": {
8 + "start": "bun src/index.ts",
9 + "dev": "bun --watch src/index.ts",
10 + "test": "echo \"Error: no test specified\" && exit 1"
11 + },
12 + "keywords": ["composio", "example", "versioning"],
13 + "author": "",
14 + "license": "ISC",
15 + "packageManager": "pnpm@10.8.0",
16 + "dependencies": {
17 + "@composio/core": "workspace:*",
18 + "dotenv": "^16.4.1"
19 + },
20 + "devDependencies": {
21 + "@types/bun": "^1.2.9",
22 + "typescript": "^5.8.3"
23 + }
24 +}
ts/examples/versioning/src/index.ts new
+49
@@ -0,0 +1,49 @@
1 +/**
2 + * Versioning Example
3 + *
4 + * This example demonstrates how to use Composio SDK for versioning.
5 + *
6 + * Prerequisites:
7 + * 1. Set up your COMPOSIO_API_KEY in the .env file
8 + * 3. Run the example: pnpm start
9 + */
10 +
11 +import { Composio } from '@composio/core';
12 +import 'dotenv/config';
13 +
14 +/**
15 + * Initialize Composio
16 + */
17 +const composio = new Composio({
18 + apiKey: process.env.COMPOSIO_API_KEY,
19 +});
20 +
21 +const config = composio.getConfig()
22 +console.log(JSON.stringify(config, null, 2))
23 +
24 +/**
25 + * Main function to run the example
26 + */
27 +async function main() {
28 + try {
29 + console.log('🚀 Starting Versioning Example...');
30 +
31 + // Get available tools
32 + const tools = await composio.tools.get('default', {
33 + // Specify the apps you want to use
34 + toolkits: ['gmail', 'googlecalendar'],
35 + limit: 10,
36 + });
37 +
38 + console.log(`✅ Found ${tools.length} tools`);
39 +
40 + // TODO: Add your example implementation here
41 + console.log('📝 Implement your versioning logic here!');
42 +
43 + } catch (error) {
44 + console.error('❌ Error running example:', error);
45 + }
46 +}
47 +
48 +// Run the example
49 +main().catch(console.error);
ts/examples/versioning/tsconfig.json new
+16
@@ -0,0 +1,16 @@
1 +{
2 + "compilerOptions": {
3 + "target": "ESNext",
4 + "module": "ESNext",
5 + "declaration": true,
6 + "declarationDir": "./dist",
7 + "outDir": "./dist",
8 + "rootDir": "./src",
9 + "strict": true,
10 + "esModuleInterop": true,
11 + "moduleResolution": "node",
12 + "skipLibCheck": true,
13 + "resolveJsonModule": true
14 + },
15 + "include": ["src"]
16 +}
ts/packages/core/README.md
+1
@@ -288,6 +288,7 @@ Composio supports various authentication schemes:
288 - `COMPOSIO_BASE_URL`: Custom API base URL
289 - `COMPOSIO_LOGGING_LEVEL`: Logging level (silent, error, warn, info, debug)
290 - `DEVELOPMENT`: Development mode flag
291 +- `COMPOSIO_TOOLKIT_VERSION_<TOOLKITNAME>`: Version of the specific tool
292 - `CI`: CI environment flag
293
294 ## Contributing
ts/packages/core/package.json
+1 -1
@@ -44,7 +44,7 @@
44 "vitest": "^3.1.4"
45 },
46 "dependencies": {
47 - "@composio/client": "0.1.0-alpha.35",
47 + "@composio/client": "0.1.0-alpha.36",
48 "@composio/json-schema-to-zod": "0.1.15",
49 "@types/json-schema": "^7.0.15",
50 "chalk": "^4.1.2",
ts/packages/core/src/composio.ts
+25 -5
@@ -7,7 +7,7 @@ import { AuthConfigs } from './models/AuthConfigs';
7 import { ConnectedAccounts } from './models/ConnectedAccounts';
8 import { MCP } from './models/MCP';
9 import { telemetry } from './telemetry/Telemetry';
10 -import { getSDKConfig } from './utils/sdk';
10 +import { getSDKConfig, getToolkitVersionsFromEnv } from './utils/sdk';
11 import logger from './utils/logger';
12 import { COMPOSIO_LOG_LEVEL, IS_DEVELOPMENT_OR_CI } from './utils/constants';
13 import { checkForLatestVersionFromNPM } from './utils/version';
@@ -16,7 +16,8 @@ import { version } from '../package.json';
16 import type { ComposioRequestHeaders } from './types/composio.types';
17 import { McpServerGetResponse } from './types/mcp.types';
18 import { Files } from './models/Files';
19 -import { getDefaultHeaders, getSessionHeaders } from './utils/session';
19 +import { getDefaultHeaders } from './utils/session';
20 +import { ToolkitVersionParam } from './types/tool.types';
21
22 export type ComposioConfig<
23 TProvider extends BaseComposioProvider<unknown, unknown, unknown> = OpenAIProvider,
@@ -73,6 +74,15 @@ export type ComposioConfig<
74 * @default false
75 */
76 disableVersionCheck?: boolean;
77 + /**
78 + * The versions of the toolkits to fetch.
79 + * Defaults to latest is nothing is provided.
80 + * Alternatively you can specify individual toolkit versions in the env `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
81 + * @example
82 + * { 'github': 'latest', 'slack': '20250902_00' }
83 + * 'latest'
84 + */
85 + toolkitVersions?: ToolkitVersionParam;
86 };
87
88 /**
@@ -161,7 +171,11 @@ export class Composio<
171 */
172 this.config = {
173 ...config,
174 + baseURL: baseURLParsed,
175 + apiKey: apiKeyParsed,
176 + toolkitVersions: getToolkitVersionsFromEnv(config?.toolkitVersions),
177 allowTracking: config?.allowTracking ?? true,
178 + autoUploadDownloadFiles: config?.autoUploadDownloadFiles ?? true,
179 };
180
181 /**
@@ -182,9 +196,7 @@ export class Composio<
196 logLevel: COMPOSIO_LOG_LEVEL,
197 });
198
185 - this.tools = new Tools(this.client, this.provider, {
186 - autoUploadDownloadFiles: config?.autoUploadDownloadFiles ?? true,
187 - });
199 + this.tools = new Tools(this.client, this.provider, this.config);
200 this.mcp = new MCP(this.client, this.provider);
201
202 this.toolkits = new Toolkits(this.client);
@@ -231,6 +243,14 @@ export class Composio<
243 return this.client;
244 }
245
246 + /**
247 + * Get the configuration SDK is initialized with
248 + * @returns {ComposioConfig<TProvider>} The configuration SDK is initialized with
249 + */
250 + getConfig(): ComposioConfig<TProvider> {
251 + return this.config;
252 + }
253 +
254 /**
255 * Creates a new instance of the Composio SDK with custom request options while preserving the existing configuration.
256 * This method is particularly useful when you need to:
ts/packages/core/src/models/Tools.ts
+138 -105
@@ -10,6 +10,9 @@ import {
10 ToolExecuteResponseSchema,
11 ToolProxyParamsSchema,
12 ToolProxyParams,
13 + ToolExecuteParamsSchema,
14 + ToolkitVersionParam,
15 + SchemaModifierOptions,
16 } from '../types/tool.types';
17 import {
18 ToolGetInputParams,
@@ -44,8 +47,9 @@ import {
47 import { ValidationError } from '../errors/ValidationErrors';
48 import { telemetry } from '../telemetry/Telemetry';
49 import { FileToolModifier } from '../utils/modifiers/FileToolModifier';
47 -import { CustomConnectionDataSchema } from '../types/connectedAccountAuthStates.types';
50 import { AuthSchemeTypes } from '../types/authConfigs.types';
51 +import { ComposioConfig } from '../composio';
52 +import { getToolkitVersion } from '../utils/toolkitVersion';
53 /**
54 * This class is used to manage tools in the Composio SDK.
55 * It provides methods to list, get, and execute tools.
@@ -59,12 +63,9 @@ export class Tools<
63 private readonly customTools: CustomTools;
64 private provider: TProvider;
65 private autoUploadDownloadFiles: boolean;
66 + private toolkitVersions: ToolkitVersionParam;
67
63 - constructor(
64 - client: ComposioClient,
65 - provider: TProvider,
66 - options?: { autoUploadDownloadFiles: boolean }
67 - ) {
68 + constructor(client: ComposioClient, provider: TProvider, config?: ComposioConfig<TProvider>) {
69 if (!client) {
70 throw new Error('ComposioClient is required');
71 }
@@ -75,12 +76,12 @@ export class Tools<
76 this.client = client;
77 this.customTools = new CustomTools(client);
78 this.provider = provider;
78 - this.autoUploadDownloadFiles = options?.autoUploadDownloadFiles ?? true;
79 + this.autoUploadDownloadFiles = config?.autoUploadDownloadFiles ?? true;
80 + this.toolkitVersions = config?.toolkitVersions ?? 'latest';
81 // Bind the execute method to ensure correct 'this' context
82 this.execute = this.execute.bind(this);
83 // Set the execute method for the provider
84 this.provider._setExecuteToolFn(this.execute);
83 -
85 // Bind methods that use customTools to ensure correct 'this' context
86 this.getRawComposioToolBySlug = this.getRawComposioToolBySlug.bind(this);
87 this.getRawComposioTools = this.getRawComposioTools.bind(this);
@@ -106,6 +107,7 @@ export class Tools<
107 ...tool,
108 inputParameters: tool.input_parameters,
109 outputParameters: tool.output_parameters,
110 + availableVersions: tool.available_versions,
111 });
112 }
113
@@ -130,60 +132,6 @@ export class Tools<
132 });
133 }
134
133 - /**
134 - * Check if the connected account exists for the given tools.
135 - * @param {string} userId - The user id.
136 - * @param {ToolList} tools - The tools to check.
137 - * @returns {Promise<boolean>} True if the connected account exists for the given tools, false otherwise.
138 - */
139 - private async checkIfConnectedAccountExistsForTools(
140 - userIds: string[],
141 - tools: ToolList
142 - ): Promise<boolean> {
143 - // @TODO: Filter out tools that don't require a connected account
144 -
145 - // if no tools, return true as no connections needed
146 - if (!tools.length) {
147 - return true;
148 - }
149 - const connectedAccounts = await this.client.connectedAccounts.list({
150 - user_ids: userIds,
151 - });
152 - // if no connected accounts, return false
153 - if (connectedAccounts.items.length === 0) {
154 - return false;
155 - }
156 -
157 - // create a map of toolkit slugs that have connected accounts
158 - const connectedToolkitSlugs = connectedAccounts.items.reduce(
159 - (acc, account) => {
160 - if (account.toolkit.slug) {
161 - acc[account.toolkit.slug] = true;
162 - }
163 - return acc;
164 - },
165 - {} as Record<string, boolean>
166 - );
167 -
168 - // create a map of tool slugs
169 - const toolSlugs = tools.reduce(
170 - (acc, tool) => {
171 - acc[tool.slug] = true;
172 - return acc;
173 - },
174 - {} as Record<string, boolean>
175 - );
176 -
177 - // check if each tool's toolkit has a connected account
178 - for (const tool of Object.keys(toolSlugs)) {
179 - if (!connectedToolkitSlugs[tool]) {
180 - logger.warn(`Tool ${tool} requires a connected account but no connected account was found`);
181 - return false;
182 - }
183 - }
184 - return true;
185 - }
186 -
135 /**
136 * Get the connected account id for a given tool
137 * @param {string} userId - The user id
@@ -345,34 +293,61 @@ export class Tools<
293 *
294 * This method fetches tools from the Composio API in raw format and combines them with
295 * any registered custom tools. The response can be filtered and modified as needed.
296 + * It provides access to the underlying tool data without provider-specific wrapping.
297 *
349 - * @param {ToolListParams} [query={}] - Optional query parameters to filter the tools
350 - * @param {TransformToolSchemaModifier} [modifier] - Optional function to transform tool schemas
298 + * @param {ToolListParams} query - Query parameters to filter the tools (required)
299 + * @param {GetRawComposioToolsOptions} [options] - Optional configuration for tool retrieval
300 + * @param {TransformToolSchemaModifier} [options.modifySchema] - Function to transform tool schemas
301 * @returns {Promise<ToolList>} List of tools matching the query criteria
302 *
303 * @example
304 * ```typescript
355 - * // Get all tools
356 - * const tools = await composio.tools.getRawComposioTools();
305 + * // Get tools from specific toolkits
306 + * const githubTools = await composio.tools.getRawComposioTools({
307 + * toolkits: ['github'],
308 + * limit: 10
309 + * });
310 *
358 - * // Get tools with filters
311 + * // Get specific tools by slug
312 + * const specificTools = await composio.tools.getRawComposioTools({
313 + * tools: ['GITHUB_GET_REPOS', 'HACKERNEWS_GET_USER']
314 + * });
315 + *
316 + * // Get tools from specific toolkits
317 * const githubTools = await composio.tools.getRawComposioTools({
318 * toolkits: ['github'],
319 * limit: 10
320 * });
321 *
322 * // Get tools with schema transformation
365 - * const tools = await composio.tools.getRawComposioTools({},
366 - * (toolSlug, toolkitSlug, tool) => {
323 + * const customizedTools = await composio.tools.getRawComposioTools({
324 + * toolkits: ['github'],
325 + * limit: 5
326 + * }, {
327 + * modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
328 * // Add custom properties to tool schema
368 - * return {...tool, customProperty: 'value'};
329 + * return {
330 + * ...schema,
331 + * customProperty: `Modified ${toolSlug} from ${toolkitSlug}`,
332 + * tags: [...(schema.tags || []), 'customized']
333 + * };
334 * }
370 - * );
335 + * });
336 + *
337 + * // Search for tools
338 + * const searchResults = await composio.tools.getRawComposioTools({
339 + * search: 'user management'
340 + * });
341 + *
342 + * // Get tools by authentication config
343 + * const authSpecificTools = await composio.tools.getRawComposioTools({
344 + * authConfigIds: ['auth_config_123']
345 + * });
346 * ```
347 */
348 async getRawComposioTools(
349 query: ToolListParams,
375 - modifier?: TransformToolSchemaModifier
350 + options?: SchemaModifierOptions
351 ): Promise<ToolList> {
352 if ('tools' in query && 'toolkits' in query) {
353 throw new ValidationError(
@@ -419,6 +394,7 @@ export class Tools<
394 ...('authConfigIds' in queryParams.data
395 ? { auth_config_ids: queryParams.data.authConfigIds }
396 : {}),
397 + ...{ toolkit_versions: this.toolkitVersions },
398 };
399
400 logger.debug(`Fetching tools with filters: ${JSON.stringify(filters, null, 2)}`);
@@ -440,7 +416,8 @@ export class Tools<
416 ]);
417
418 // apply local modifiers if they are provided
443 - if (modifier) {
419 + if (options?.modifySchema) {
420 + const modifier = options.modifySchema;
421 if (typeof modifier === 'function') {
422 const modifiedPromises = modifiedTools.map(tool =>
423 modifier({
@@ -459,20 +436,56 @@ export class Tools<
436 }
437
438 /**
462 - * Retrieves a tool by its Slug.
463 - * This method is used to get the raw tools from the composio API.
464 - * @param slug The ID of the tool to be retrieved
465 - * @returns {Promise<Tool>} The tool
439 + * Retrieves a specific tool by its slug from the Composio API.
440 + *
441 + * This method fetches a single tool in raw format without provider-specific wrapping,
442 + * providing direct access to the tool's schema and metadata. Tool versions are controlled
443 + * at the Composio SDK initialization level through the `toolkitVersions` configuration.
444 + *
445 + * @param {string} slug - The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
446 + * @param {GetRawComposioToolBySlugOptions} [options] - Optional configuration for tool retrieval
447 + * @param {TransformToolSchemaModifier} [options.modifySchema] - Function to transform the tool schema
448 + * @returns {Promise<Tool>} The requested tool with its complete schema and metadata
449 *
450 * @example
468 - * ```ts
469 - * const tool = await composio.tools.getRawComposioToolBySlug('github');
451 + * ```typescript
452 + * // Get a tool by slug
453 + * const tool = await composio.tools.getRawComposioToolBySlug('GITHUB_GET_REPOS');
454 + * console.log(tool.name, tool.description);
455 + *
456 + * // Get a tool with schema transformation
457 + * const customizedTool = await composio.tools.getRawComposioToolBySlug(
458 + * 'SLACK_SEND_MESSAGE',
459 + * {
460 + * modifySchema: ({ toolSlug, toolkitSlug, schema }) => {
461 + * return {
462 + * ...schema,
463 + * description: `Enhanced ${schema.description} with custom modifications`,
464 + * customMetadata: {
465 + * lastModified: new Date().toISOString(),
466 + * toolkit: toolkitSlug
467 + * }
468 + * };
469 + * }
470 + * }
471 + * );
472 + *
473 + * // Get a custom tool (will check custom tools first)
474 + * const customTool = await composio.tools.getRawComposioToolBySlug('MY_CUSTOM_TOOL');
475 + *
476 + * // Access tool properties
477 + * const githubTool = await composio.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
478 + * console.log({
479 + * slug: githubTool.slug,
480 + * name: githubTool.name,
481 + * toolkit: githubTool.toolkit?.name,
482 + * version: githubTool.version,
483 + * availableVersions: githubTool.availableVersions,
484 + * inputParameters: githubTool.inputParameters
485 + * });
486 * ```
487 */
472 - async getRawComposioToolBySlug(
473 - slug: string,
474 - modifier?: TransformToolSchemaModifier
475 - ): Promise<Tool> {
488 + async getRawComposioToolBySlug(slug: string, options?: SchemaModifierOptions): Promise<Tool> {
489 // check if the tool is a custom tool
490 const customTool = await this.customTools.getCustomToolBySlug(slug);
491 if (customTool) {
@@ -484,7 +497,9 @@ export class Tools<
497 // if not, fetch the tool from the Composio API
498 let tool: ToolRetrieveResponse;
499 try {
487 - tool = await this.client.tools.retrieve(slug);
500 + tool = await this.client.tools.retrieve(slug, {
501 + toolkit_versions: this.toolkitVersions,
502 + });
503 } catch (error) {
504 throw new ComposioToolNotFoundError(`Unable to retrieve tool with slug ${slug}`, {
505 cause: error,
@@ -494,7 +509,8 @@ export class Tools<
509 // change the case of the tool to camel case and apply default modifiers
510 let [modifiedTool] = await this.applyDefaultSchemaModifiers([this.transformToolCases(tool)]);
511 // apply local modifiers if they are provided
497 - if (modifier) {
512 + if (options?.modifySchema) {
513 + const modifier = options.modifySchema;
514 if (typeof modifier === 'function') {
515 modifiedTool = await modifier({
516 toolSlug: slug,
@@ -580,27 +596,34 @@ export class Tools<
596
597 /**
598 * Get a tool or list of tools based on the provided arguments.
583 - * This is an implementation method that handles both overloads.
599 + * This is an implementation method that handles all overloads.
600 *
601 * @param {string} userId - The user id to get the tool(s) for
602 * @param {ToolListParams | string} arg2 - Either a slug string or filters object
587 - * @param {ProviderOptions<TProvider>} [options] - Optional provider options
603 + * @param {ProviderOptions<TProvider> | ToolkitVersion} [arg3] - Optional provider options or version string
604 + * @param {ProviderOptions<TProvider>} [arg4] - Optional provider options (when arg3 is version)
605 * @returns {Promise<TToolCollection>} The tool collection
606 */
607 async get(
608 userId: string,
609 arg2: ToolListParams | string,
593 - options?: ProviderOptions<TProvider>
610 + arg3?: ProviderOptions<TProvider>
611 ): Promise<TToolCollection> {
595 - // create the execute tool function
612 + // Handle the two-parameter overloads
613 + const options = arg3 as ProviderOptions<TProvider>;
614 const executeToolFn = this.createExecuteToolFn(userId, options as ExecuteToolModifiers);
597 - // if the first argument is a string, get a single tool
615 +
616 + // if the second argument is a string, get a single tool
617 if (typeof arg2 === 'string') {
599 - const tool = await this.getRawComposioToolBySlug(arg2, options?.modifySchema);
618 + const tool = await this.getRawComposioToolBySlug(arg2, {
619 + modifySchema: options?.modifySchema as TransformToolSchemaModifier,
620 + });
621 return this.provider.wrapTools([tool], executeToolFn) as TToolCollection;
622 } else {
602 - // if the first argument is an object, get a list of tools
603 - const tools = await this.getRawComposioTools(arg2, options?.modifySchema);
623 + // if the second argument is an object, get a list of tools
624 + const tools = await this.getRawComposioTools(arg2, {
625 + modifySchema: options?.modifySchema as TransformToolSchemaModifier,
626 + });
627 return this.provider.wrapTools(tools, executeToolFn) as TToolCollection;
628 }
629 }
@@ -709,12 +732,12 @@ export class Tools<
732 custom_connection_data: body.customConnectionData,
733 arguments: body.arguments,
734 user_id: body.userId,
712 - version: body.version,
735 + version:
736 + body.version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions),
737 text: body.text,
738 });
739 // apply transformations to the response
740 result = this.transformToolExecuteResponse(result);
717 -
741 result = await this.applyAfterExecuteModifiers(
742 tool,
743 {
@@ -777,27 +800,37 @@ export class Tools<
800 );
801 }
802
803 + const executeParams = ToolExecuteParamsSchema.safeParse(body);
804 + if (!executeParams.success) {
805 + throw new ValidationError('Invalid tool execute parameters', { cause: executeParams.error });
806 + }
807 +
808 try {
809 const customTool = await this.customTools.getCustomToolBySlug(slug);
810 if (customTool) {
811 // handle custom tool execution
784 - return this.handleCustomToolExecution(customTool, body, modifiers);
812 + return this.handleCustomToolExecution(customTool, executeParams.data, modifiers);
813 } else {
814 // handle composio tool execution
815 const composioTool = await this.getRawComposioToolBySlug(slug);
816 if (!composioTool) {
789 - throw new ComposioToolNotFoundError(`Tool with slug ${slug} not found`);
817 + throw new ComposioToolNotFoundError(
818 + `Tool with slug ${slug} version:${executeParams.data.version} not found`
819 + );
820 }
791 - return this.handleComposioToolExecution(composioTool, body, modifiers);
821 + return this.handleComposioToolExecution(composioTool, executeParams.data, modifiers);
822 }
823 } catch (error) {
794 - throw new ComposioToolExecutionError(`Error executing tool ${slug}`, {
795 - originalError: error as Error,
796 - meta: {
797 - toolSlug: slug,
798 - body,
799 - },
800 - });
824 + throw new ComposioToolExecutionError(
825 + `Error executing tool ${slug} version:${executeParams.data.version}`,
826 + {
827 + originalError: error as Error,
828 + meta: {
829 + toolSlug: slug,
830 + body,
831 + },
832 + }
833 + );
834 }
835 }
836
ts/packages/core/src/types/provider.types.ts
+1
@@ -4,6 +4,7 @@ import {
4 Tool,
5 ToolExecuteParams,
6 ToolExecuteResponse,
7 + ToolkitVersion,
8 ToolListParams,
9 } from './tool.types';
10 import { CustomConnectionData } from './connectedAccountAuthStates.types';
ts/packages/core/src/types/tool.types.ts
+42 -8
@@ -1,5 +1,6 @@
1 import { z } from 'zod';
2 import { CustomConnectionDataSchema } from './connectedAccountAuthStates.types';
3 +import { TransformToolSchemaModifier } from './modifiers.types';
4
5 /**
6 * Toolkit is the collection of tools,
@@ -112,10 +113,15 @@ export const ToolSchema = z.object({
113 description: z.string().optional().describe('The description of the tool'),
114 inputParameters: ParametersSchema.optional().describe('The input parameters of the tool'),
115 outputParameters: ParametersSchema.optional().describe('The output parameters of the tool'),
115 - tags: z.optional(z.array(z.string())).describe('The tags of the tool. eg: Important').default([]),
116 - toolkit: z.optional(ToolkitSchema).describe('The toolkit of the tool'),
117 - version: z.optional(z.string()).describe('The version of the tool, e.g. "1.0.0"'),
118 - scopes: z.optional(z.array(z.string())).describe('The scopes of the tool. eg: ["task:add"]'),
116 + tags: z.array(z.string()).describe('The tags of the tool. eg: Important').default([]).optional(),
117 + toolkit: ToolkitSchema.describe('The toolkit of the tool').optional(),
118 + version: z.string().describe('The version of the tool, e.g. "20250909_00"').optional(),
119 + availableVersions: z
120 + .array(z.string())
121 + .describe('Available versions of the tool.')
122 + .default([])
123 + .optional(),
124 + scopes: z.array(z.string()).describe('The scopes of the tool. eg: ["task:add"]').optional(),
125 });
126 export type Tool = z.infer<typeof ToolSchema>;
127
@@ -134,6 +140,31 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
140 */
141 export type ToolList = Array<Tool>;
142
143 +/**
144 + * latest toolkit version param
145 + */
146 +export type ToolkitLatestVersion = 'latest';
147 +/**
148 + * Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'
149 + * @example
150 + * 'latest'
151 + * '20250902_00'
152 + */
153 +export type ToolkitVersion = ToolkitLatestVersion | string;
154 +/**
155 + * Versioning multiple toolkits
156 + * @example
157 + * { 'github': 'latest', 'slack': '20250902_00' }
158 + */
159 +export type ToolkitVersions = Record<string, ToolkitVersion>;
160 +/**
161 + * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'
162 + * @example
163 + * 'latest'
164 + * { 'github': 'latest', 'slack': '20250902_00' }
165 + */
166 +export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;
167 +
168 export const ToolListParamsSchema = z.object({
169 tools: z.array(z.string()).optional(),
170 toolkits: z.array(z.string()).optional(),
@@ -159,7 +190,6 @@ type ToolsOnlyParams = {
190 search?: never;
191 tags?: never;
192 };
162 -
193 // toolkits only
194 type ToolkitsOnlyParams = {
195 toolkits: string[];
@@ -184,11 +214,11 @@ type TagsOnlyParams = {
214
215 // search only
216 type SearchOnlyParams = {
217 + search: string;
218 tools?: never;
219 toolkits?: never;
220 scopes?: never;
221 limit?: never;
191 - search: string;
222 tags?: never;
223 };
224
@@ -235,8 +265,8 @@ export const ToolExecuteParamsSchema = z.object({
265 customAuthParams: CustomAuthParamsSchema.optional(),
266 customConnectionData: CustomConnectionDataSchema.optional(),
267 arguments: z.record(z.string(), z.unknown()).optional(),
238 - userId: z.string().optional(), //
239 - version: z.string().optional(),
268 + userId: z.string().optional(), // we have no auth apps which can be execute
269 + version: z.union([z.literal('latest'), z.string()]).optional(),
270 text: z.string().optional(),
271 });
272 export type ToolExecuteParams = z.infer<typeof ToolExecuteParamsSchema>;
@@ -270,3 +300,7 @@ export const ToolProxyParamsSchema = z.object({
300 customConnectionData: CustomConnectionDataSchema.optional(),
301 });
302 export type ToolProxyParams = z.infer<typeof ToolProxyParamsSchema>;
303 +
304 +export type SchemaModifierOptions = {
305 + modifySchema: TransformToolSchemaModifier;
306 +};
ts/packages/core/src/utils/env.ts
+24
@@ -8,3 +8,27 @@ export const getEnvVariable = (
8 return defaultValue;
9 }
10 };
11 +
12 +/**
13 + * Method to return all the envs based on a specific prefix
14 + * @param prefix
15 + * @example
16 + * COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
17 + * COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
18 + * COMPOSIO_TOOLKIT_VERSION_GMAIL=latest
19 + * @returns {Record<string, unknown>}
20 + * @returns
21 + */
22 +export const getEnvsWithPrefix = (prefix: string): Record<string, unknown> => {
23 + try {
24 + if (process && process.env) {
25 + return Object.fromEntries(
26 + Object.entries(process.env).filter(([key]) => key.startsWith(prefix))
27 + );
28 + } else {
29 + return {};
30 + }
31 + } catch (error) {
32 + return {};
33 + }
34 +};
ts/packages/core/src/utils/sdk.ts
+58 -1
@@ -1,8 +1,9 @@
1 import { ComposioNoAPIKeyError } from '../errors/SDKErrors';
2 import { COMPOSIO_DIR, DEFAULT_BASE_URL, USER_DATA_FILE_NAME } from './constants';
3 -import { getEnvVariable } from './env';
3 +import { getEnvsWithPrefix, getEnvVariable } from './env';
4 import logger from './logger';
5 import { ComposioError } from '../errors/ComposioError';
6 +import { ToolkitVersion, ToolkitVersionParam, ToolkitVersions } from '../types/tool.types';
7
8 // File path helpers
9 export const userDataPath = () => {
@@ -18,6 +19,11 @@ export const userDataPath = () => {
19 }
20 };
21
22 +/**
23 + * Reads and parses the user data JSON file from the Composio directory.
24 + *
25 + * @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
26 + */
27 export const getUserDataJson = () => {
28 try {
29 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -50,3 +56,54 @@ export function getSDKConfig(baseUrl?: string | null, apiKey?: string | null) {
56
57 return { baseURL: baseURLParsed, apiKey: apiKeyParsed };
58 }
59 +
60 +/**
61 + * Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.
62 + *
63 + * Priority order:
64 + * 1. If defaultVersions is a string, use it as global version for all toolkits
65 + * 2. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)
66 + * 3. User-provided toolkit version mappings (defaultVersions object)
67 + * 4. Fallback to 'latest' if no versions are configured
68 + *
69 + * @param defaultVersions - Optional default versions configuration (string for global version or object mapping toolkit names to versions)
70 + * @returns Toolkit versions configuration - either a global version string, toolkit-specific version mapping, or 'latest'
71 + */
72 +export function getToolkitVersionsFromEnv(
73 + defaultVersions?: ToolkitVersionParam
74 +): ToolkitVersionParam {
75 + // if already set by user either a single version or 'latest' use that as is / override everything else
76 + if (defaultVersions && typeof defaultVersions === 'string') {
77 + return defaultVersions;
78 + }
79 +
80 + // check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit name
81 + const envPrefixedVersions = getEnvsWithPrefix(`COMPOSIO_TOOLKIT_VERSION_`);
82 + const toolkitVersionsFromEnv = Object.entries(envPrefixedVersions).reduce((acc, [key, value]) => {
83 + const toolkitName = key.replace('COMPOSIO_TOOLKIT_VERSION_', '');
84 + acc[toolkitName.toLowerCase()] = value as ToolkitVersion;
85 + return acc;
86 + }, {} as ToolkitVersions);
87 +
88 + // if the provided default versions is an object, normalize the keys to be lower case
89 + // use user provided values as overrides
90 + let userProvidedToolkitVersions = {};
91 + if (defaultVersions && typeof defaultVersions === 'object') {
92 + userProvidedToolkitVersions = Object.fromEntries(
93 + Object.entries(defaultVersions).map(([key, value]) => [key.toLowerCase(), value])
94 + );
95 + }
96 +
97 + // final toolkit versions
98 + const toolkitVersions = {
99 + ...toolkitVersionsFromEnv,
100 + ...userProvidedToolkitVersions,
101 + };
102 +
103 + // if the toolkitVersions are empty, use 'latest'
104 + if (Object.keys(toolkitVersions).length === 0) {
105 + return 'latest';
106 + }
107 +
108 + return toolkitVersions;
109 +}
ts/packages/core/src/utils/toolkitVersion.ts new
+26
@@ -0,0 +1,26 @@
1 +import { ToolkitVersion, ToolkitVersionParam } from '../types/tool.types';
2 +
3 +/**
4 + * Gets the version for a specific toolkit based on the provided toolkit versions configuration.
5 + *
6 + * @param toolkitSlug - The slug/name of the toolkit to get the version for
7 + * @param toolkitVersions - Optional toolkit versions configuration (string for global version or object mapping toolkit slugs to versions)
8 + * @returns The toolkit version to use - either the specific version from config, or 'latest' as fallback
9 + */
10 +export const getToolkitVersion = (
11 + toolkitSlug: string,
12 + toolkitVersions?: ToolkitVersionParam
13 +): ToolkitVersion => {
14 + // If toolkitVersions is a string, use it as a global version for all toolkits
15 + if (typeof toolkitVersions === 'string') {
16 + return toolkitVersions;
17 + }
18 + // If toolkitVersions is an object mapping, look up the specific toolkit version
19 + const hasToolkitVersion = toolkitVersions && Object.keys(toolkitVersions).length > 0;
20 + if (hasToolkitVersion) {
21 + return toolkitVersions[toolkitSlug] ?? 'latest';
22 + }
23 +
24 + // Else use 'latest'
25 + return 'latest';
26 +};
ts/packages/core/test/core/versions.test.ts new
+413
@@ -0,0 +1,413 @@
1 +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2 +import { getToolkitVersionsFromEnv } from '../../src/utils/sdk';
3 +import { getToolkitVersion } from '../../src/utils/toolkitVersion';
4 +import { getEnvsWithPrefix } from '../../src/utils/env';
5 +import { ToolkitVersions } from '../../src/types/tool.types';
6 +
7 +describe('Version Management', () => {
8 + const originalEnv = process.env;
9 +
10 + beforeEach(() => {
11 + // Reset environment variables before each test
12 + vi.resetModules();
13 + process.env = { ...originalEnv };
14 + });
15 +
16 + afterEach(() => {
17 + // Restore original environment
18 + process.env = originalEnv;
19 + vi.clearAllMocks();
20 + });
21 +
22 + describe('getEnvsWithPrefix', () => {
23 + it('should return environment variables with the specified prefix', () => {
24 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250902_00';
25 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
26 + process.env.COMPOSIO_TOOLKIT_VERSION_GMAIL = '20250901_01';
27 + process.env.OTHER_ENV_VAR = 'should_not_be_included';
28 +
29 + const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
30 +
31 + expect(result).toEqual({
32 + COMPOSIO_TOOLKIT_VERSION_GITHUB: '20250902_00',
33 + COMPOSIO_TOOLKIT_VERSION_SLACK: 'latest',
34 + COMPOSIO_TOOLKIT_VERSION_GMAIL: '20250901_01',
35 + });
36 + expect(result).not.toHaveProperty('OTHER_ENV_VAR');
37 + });
38 +
39 + it('should return empty object when no matching environment variables exist', () => {
40 + process.env.SOME_OTHER_VAR = 'value';
41 +
42 + const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
43 +
44 + expect(result).toEqual({});
45 + });
46 +
47 + it('should return empty object when prefix is empty', () => {
48 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250902_00';
49 +
50 + const result = getEnvsWithPrefix('');
51 +
52 + // Should return all env vars when prefix is empty
53 + expect(Object.keys(result).length).toBeGreaterThan(0);
54 + expect(result).toHaveProperty('COMPOSIO_TOOLKIT_VERSION_GITHUB');
55 + });
56 +
57 + it('should handle process.env being undefined gracefully', () => {
58 + const originalProcess = process;
59 + // @ts-expect-error: Intentionally testing edge case
60 + global.process = undefined;
61 +
62 + const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
63 +
64 + expect(result).toEqual({});
65 +
66 + // Restore process
67 + global.process = originalProcess;
68 + });
69 +
70 + it('should handle errors gracefully', () => {
71 + // Mock process.env to throw an error
72 + const mockProcess = {
73 + env: new Proxy(
74 + {},
75 + {
76 + get() {
77 + throw new Error('Test error');
78 + },
79 + }
80 + ),
81 + };
82 +
83 + vi.stubGlobal('process', mockProcess);
84 +
85 + const result = getEnvsWithPrefix('COMPOSIO_TOOLKIT_VERSION_');
86 +
87 + expect(result).toEqual({});
88 +
89 + vi.unstubAllGlobals();
90 + });
91 + });
92 +
93 + describe('getToolkitVersionsFromEnv', () => {
94 + describe('when user provides string version (global version)', () => {
95 + it('should return the string version as-is when user provides "latest"', () => {
96 + const result = getToolkitVersionsFromEnv('latest');
97 + expect(result).toBe('latest');
98 + });
99 +
100 + it('should return the string version as-is when user provides specific version', () => {
101 + const result = getToolkitVersionsFromEnv('20250902_00' as any);
102 + expect(result).toBe('20250902_00');
103 + });
104 +
105 + it('should ignore environment variables when user provides string version', () => {
106 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_01';
107 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
108 +
109 + const result = getToolkitVersionsFromEnv('20250902_00' as any);
110 + expect(result).toBe('20250902_00');
111 + });
112 + });
113 +
114 + describe('when user provides object version mapping', () => {
115 + it('should normalize toolkit names to lowercase', () => {
116 + const userVersions = {
117 + GITHUB: '20250902_00',
118 + Slack: 'latest',
119 + gmail: '20250901_01',
120 + };
121 +
122 + const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
123 +
124 + expect(result).toEqual({
125 + github: '20250902_00',
126 + slack: 'latest',
127 + gmail: '20250901_01',
128 + });
129 + });
130 +
131 + it('should merge environment variables with user-provided versions', () => {
132 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
133 + process.env.COMPOSIO_TOOLKIT_VERSION_NOTION = 'latest';
134 +
135 + const userVersions = {
136 + slack: '20250902_00',
137 + gmail: 'latest',
138 + };
139 +
140 + const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
141 +
142 + expect(result).toEqual({
143 + github: '20250901_00', // from env
144 + notion: 'latest', // from env
145 + slack: '20250902_00', // from user
146 + gmail: 'latest', // from user
147 + });
148 + });
149 +
150 + it('should prioritize user-provided versions over environment variables', () => {
151 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
152 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = '20250901_01';
153 +
154 + const userVersions = {
155 + github: '20250902_00', // should override env
156 + slack: 'latest', // should override env
157 + gmail: '20250902_01', // new toolkit
158 + };
159 +
160 + const result = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
161 +
162 + expect(result).toEqual({
163 + github: '20250902_00', // user version takes precedence
164 + slack: 'latest', // user version takes precedence
165 + gmail: '20250902_01', // from user
166 + });
167 + });
168 +
169 + it('should handle mixed case environment variables correctly', () => {
170 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
171 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
172 +
173 + const result = getToolkitVersionsFromEnv({}) as ToolkitVersions;
174 +
175 + expect(result).toEqual({
176 + github: '20250901_00', // normalized to lowercase
177 + slack: 'latest', // normalized to lowercase
178 + });
179 + });
180 + });
181 +
182 + describe('when no user versions provided', () => {
183 + it('should return environment variables only', () => {
184 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
185 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
186 +
187 + const result = getToolkitVersionsFromEnv() as ToolkitVersions;
188 +
189 + expect(result).toEqual({
190 + github: '20250901_00',
191 + slack: 'latest',
192 + });
193 + });
194 +
195 + it('should return "latest" when no environment variables or user versions exist', () => {
196 + const result = getToolkitVersionsFromEnv();
197 + expect(result).toBe('latest');
198 + });
199 +
200 + it('should return "latest" when empty object is provided and no env vars exist', () => {
201 + const result = getToolkitVersionsFromEnv({});
202 + expect(result).toBe('latest');
203 + });
204 +
205 + it('should handle undefined input correctly', () => {
206 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
207 +
208 + const result = getToolkitVersionsFromEnv(undefined) as ToolkitVersions;
209 +
210 + expect(result).toEqual({
211 + github: '20250901_00',
212 + });
213 + });
214 + });
215 +
216 + describe('environment variable parsing', () => {
217 + it('should extract toolkit names correctly from environment variables', () => {
218 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB_ENTERPRISE = '20250901_00';
219 + process.env.COMPOSIO_TOOLKIT_VERSION_GOOGLE_WORKSPACE = 'latest';
220 + process.env.COMPOSIO_TOOLKIT_VERSION_MS_TEAMS = '20250902_00';
221 +
222 + const result = getToolkitVersionsFromEnv() as ToolkitVersions;
223 +
224 + expect(result).toEqual({
225 + github_enterprise: '20250901_00',
226 + google_workspace: 'latest',
227 + ms_teams: '20250902_00',
228 + });
229 + });
230 +
231 + it('should handle environment variables with special characters', () => {
232 + process.env['COMPOSIO_TOOLKIT_VERSION_MY-TOOLKIT'] = '20250901_00';
233 + process.env['COMPOSIO_TOOLKIT_VERSION_ANOTHER_TOOLKIT'] = 'latest';
234 +
235 + const result = getToolkitVersionsFromEnv() as ToolkitVersions;
236 +
237 + expect(result).toEqual({
238 + 'my-toolkit': '20250901_00',
239 + another_toolkit: 'latest',
240 + });
241 + });
242 + });
243 + });
244 +
245 + describe('getToolkitVersion', () => {
246 + describe('when toolkitVersions is a string (global version)', () => {
247 + it('should return the global version for any toolkit', () => {
248 + const result1 = getToolkitVersion('github', 'latest');
249 + const result2 = getToolkitVersion('slack', 'latest');
250 + const result3 = getToolkitVersion('gmail', 'latest');
251 +
252 + expect(result1).toBe('latest');
253 + expect(result2).toBe('latest');
254 + expect(result3).toBe('latest');
255 + });
256 + });
257 +
258 + describe('when toolkitVersions is an object mapping', () => {
259 + it('should return specific version for toolkit when available', () => {
260 + const toolkitVersions = {
261 + github: '20250902_00',
262 + slack: 'latest',
263 + gmail: '20250901_01',
264 + };
265 +
266 + expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
267 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
268 + expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250901_01');
269 + });
270 +
271 + it('should return "latest" for toolkit not in the mapping', () => {
272 + const toolkitVersions = {
273 + github: '20250902_00',
274 + slack: 'latest',
275 + };
276 +
277 + const result = getToolkitVersion('notion', toolkitVersions);
278 + expect(result).toBe('latest');
279 + });
280 +
281 + it('should handle empty object mapping', () => {
282 + const result = getToolkitVersion('github', {});
283 + expect(result).toBe('latest');
284 + });
285 +
286 + it('should be case-sensitive for toolkit slugs', () => {
287 + const toolkitVersions = {
288 + github: '20250902_00',
289 + GITHUB: 'latest',
290 + };
291 +
292 + expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
293 + expect(getToolkitVersion('GITHUB', toolkitVersions)).toBe('latest');
294 + expect(getToolkitVersion('GitHub', toolkitVersions)).toBe('latest'); // not found
295 + });
296 + });
297 +
298 + describe('when toolkitVersions is undefined or null', () => {
299 + it('should return "latest" when toolkitVersions is undefined', () => {
300 + const result = getToolkitVersion('github', undefined);
301 + expect(result).toBe('latest');
302 + });
303 +
304 + it('should return "latest" when toolkitVersions is null', () => {
305 + const result = getToolkitVersion('github', null as any);
306 + expect(result).toBe('latest');
307 + });
308 + });
309 +
310 + describe('edge cases', () => {
311 + it('should handle empty toolkit slug', () => {
312 + const toolkitVersions = {
313 + '': '20250902_00',
314 + github: 'latest',
315 + };
316 +
317 + expect(getToolkitVersion('', toolkitVersions)).toBe('20250902_00');
318 + expect(getToolkitVersion('github', toolkitVersions)).toBe('latest');
319 + });
320 +
321 + it('should handle toolkit slug with special characters', () => {
322 + const toolkitVersions = {
323 + 'my-toolkit': '20250902_00',
324 + another_toolkit: 'latest',
325 + 'toolkit.with.dots': '20250901_00',
326 + };
327 +
328 + expect(getToolkitVersion('my-toolkit', toolkitVersions)).toBe('20250902_00');
329 + expect(getToolkitVersion('another_toolkit', toolkitVersions)).toBe('latest');
330 + expect(getToolkitVersion('toolkit.with.dots', toolkitVersions)).toBe('20250901_00');
331 + });
332 +
333 + it('should handle version values that are not strings', () => {
334 + const toolkitVersions = {
335 + github: '20250902_00',
336 + slack: 'latest',
337 + } as any;
338 +
339 + expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
340 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
341 + });
342 + });
343 + });
344 +
345 + describe('Integration tests', () => {
346 + it('should work together: getToolkitVersionsFromEnv + getToolkitVersion', () => {
347 + // Set up environment
348 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
349 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
350 +
351 + // User provides additional versions
352 + const userVersions = {
353 + GMAIL: '20250902_00', // will be normalized to lowercase
354 + notion: 'latest',
355 + };
356 +
357 + // Get toolkit versions configuration
358 + const toolkitVersions = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
359 +
360 + // Test individual toolkit version retrieval
361 + expect(getToolkitVersion('github', toolkitVersions)).toBe('20250901_00'); // from env
362 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest'); // from env
363 + expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250902_00'); // from user
364 + expect(getToolkitVersion('notion', toolkitVersions)).toBe('latest'); // from user
365 + expect(getToolkitVersion('unknown', toolkitVersions)).toBe('latest'); // fallback
366 + });
367 +
368 + it('should handle global version override correctly', () => {
369 + // Set up environment (should be ignored)
370 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250901_00';
371 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
372 +
373 + // User provides global version
374 + const toolkitVersions = getToolkitVersionsFromEnv('20250902_00' as any);
375 +
376 + // All toolkits should get the global version
377 + expect(getToolkitVersion('github', toolkitVersions)).toBe('20250902_00');
378 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('20250902_00');
379 + expect(getToolkitVersion('gmail', toolkitVersions)).toBe('20250902_00');
380 + expect(getToolkitVersion('any-toolkit', toolkitVersions)).toBe('20250902_00');
381 + });
382 +
383 + it('should fall back to "latest" when no configuration is provided', () => {
384 + // No environment variables, no user input
385 + const toolkitVersions = getToolkitVersionsFromEnv();
386 +
387 + expect(toolkitVersions).toBe('latest');
388 + expect(getToolkitVersion('github', toolkitVersions)).toBe('latest');
389 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('latest');
390 + expect(getToolkitVersion('any-toolkit', toolkitVersions)).toBe('latest');
391 + });
392 +
393 + it('should demonstrate priority order: user object > env vars > fallback', () => {
394 + // Environment variables
395 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = 'env_version';
396 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'env_slack_version';
397 +
398 + // User provides partial override
399 + const userVersions = {
400 + github: 'user_version', // overrides env
401 + gmail: 'user_gmail_version', // new toolkit
402 + // slack not specified, should use env
403 + };
404 +
405 + const toolkitVersions = getToolkitVersionsFromEnv(userVersions) as ToolkitVersions;
406 +
407 + expect(getToolkitVersion('github', toolkitVersions)).toBe('user_version'); // user wins
408 + expect(getToolkitVersion('slack', toolkitVersions)).toBe('env_slack_version'); // from env
409 + expect(getToolkitVersion('gmail', toolkitVersions)).toBe('user_gmail_version'); // from user
410 + expect(getToolkitVersion('notion', toolkitVersions)).toBe('latest'); // fallback
411 + });
412 + });
413 +});
ts/packages/core/test/tools/fileModifiers.test.ts
+13 -1
@@ -37,6 +37,8 @@ describe('FileToolModifier', () => {
37 name: 'Test Tool',
38 description: 'A test tool',
39 tags: ['test'],
40 + version: '20250902_00',
41 + availableVersions: ['20250902_00'],
42 };
43
44 const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);
@@ -49,6 +51,8 @@ describe('FileToolModifier', () => {
51 name: 'Test Tool',
52 description: 'A test tool',
53 tags: ['test'],
54 + version: '20250902_00',
55 + availableVersions: ['20250902_00'],
56 inputParameters: {
57 type: 'object',
58 properties: {
@@ -87,6 +91,8 @@ describe('FileToolModifier', () => {
91 },
92 },
93 },
94 + version: '20250902_00',
95 + availableVersions: ['20250902_00'],
96 };
97
98 it('should upload file for file_uploadable parameters', async () => {
@@ -180,6 +186,8 @@ describe('FileToolModifier', () => {
186 name: 'Test Tool',
187 description: 'A test tool',
188 tags: ['test'],
189 + availableVersions: ['20250902_00'],
190 + version: '20250902_00',
191 };
192
193 it('should download file from S3 URL', async () => {
@@ -314,6 +322,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
322 },
323 additionalProperties: false,
324 },
325 + version: '20250902_00',
326 + availableVersions: ['20250902_00'],
327 };
328
329 const mockRawToolWithFileUpload = {
@@ -352,6 +362,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
362 },
363 additionalProperties: false,
364 },
365 + version: '20250902_00',
366 + availableVersions: ['20250902_00'],
367 };
368
369 describe('when autoUploadDownloadFiles is false', () => {
@@ -419,7 +431,7 @@ describe('Tools with autoUploadDownloadFiles', () => {
431 custom_connection_data: undefined,
432 text: undefined,
433 user_id: 'test-user',
422 - version: undefined,
434 + version: 'latest',
435 });
436 });
437
ts/packages/core/test/tools/modifiers.test.ts
+7 -3
@@ -26,7 +26,9 @@ describe('Tools Modifiers', () => {
26 // mock client to send back the tool
27 mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
28
29 - const result = await context.tools.getRawComposioToolBySlug(slug, schemaModifier);
29 + const result = await context.tools.getRawComposioToolBySlug(slug, {
30 + modifySchema: schemaModifier,
31 + });
32
33 expect(schemaModifier).toHaveBeenCalledTimes(1);
34 expect(schemaModifier).toHaveBeenCalledWith(
@@ -57,7 +59,7 @@ describe('Tools Modifiers', () => {
59
60 const result = await context.tools.getRawComposioTools(
61 { tools: ['TOOL1', 'TOOL2'] },
60 - schemaModifier
62 + { modifySchema: schemaModifier }
63 );
64
65 expect(schemaModifier).toHaveBeenCalledTimes(2);
@@ -237,7 +239,9 @@ describe('Tools Modifiers', () => {
239 });
240
241 // Verify schema modification
240 - expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, schemaModifier);
242 + expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
243 + modifySchema: schemaModifier,
244 + });
245 expect(mockTool.description).toBe('Enhanced GITHUB_GET_REPOS for better context');
246 expect(mockTool.tags).toContain('enhanced');
247 expect(mockTool.tags).toContain('modified');
ts/packages/core/test/tools/tools.test.ts
+478 -19
@@ -1,7 +1,7 @@
1 -import { describe, it, expect, vi } from 'vitest';
1 +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2 import { mockClient } from '../utils/mocks/client.mock';
3 import { toolMocks } from '../utils/mocks/data.mock';
4 -import { Tool, ToolListParams } from '../../src/types/tool.types';
4 +import { Tool, ToolListParams, ToolExecuteParams } from '../../src/types/tool.types';
5 import { Tools } from '../../src/models/Tools';
6 import ComposioClient from '@composio/client';
7 import {
@@ -10,6 +10,7 @@ import {
10 mockToolExecution,
11 createSchemaModifier,
12 } from '../utils/toolExecuteUtils';
13 +import { MockProvider } from '../utils/mocks/provider.mock';
14 import { ValidationError } from '../../src/errors/ValidationErrors';
15
16 describe('Tools', () => {
@@ -67,8 +68,7 @@ describe('Tools', () => {
68 expect(mockClient.tools.list).toHaveBeenCalledWith({
69 tool_slugs: 'TOOL1,TOOL2',
70 limit: 9999,
70 - search: undefined,
71 - toolkit_slug: undefined,
71 + toolkit_versions: 'latest',
72 });
73 });
74
@@ -87,10 +87,9 @@ describe('Tools', () => {
87 await context.tools.getRawComposioTools(query);
88
89 expect(mockClient.tools.list).toHaveBeenCalledWith({
90 - tool_slugs: undefined,
90 toolkit_slug: 'github',
91 limit: 10,
93 - search: undefined,
92 + toolkit_versions: 'latest',
93 });
94 });
95
@@ -110,10 +109,10 @@ describe('Tools', () => {
109 await context.tools.getRawComposioTools(query);
110
111 expect(mockClient.tools.list).toHaveBeenCalledWith({
113 - tool_slugs: undefined,
112 toolkit_slug: 'github',
113 limit: 10,
114 search: 'test',
115 + toolkit_versions: 'latest',
116 });
117 });
118
@@ -133,11 +132,10 @@ describe('Tools', () => {
132 await context.tools.getRawComposioTools(query);
133
134 expect(mockClient.tools.list).toHaveBeenCalledWith({
136 - tool_slugs: undefined,
135 toolkit_slug: 'todoist',
136 limit: 10,
139 - search: undefined,
137 scopes: ['task:add', 'task:read'],
138 + toolkit_versions: 'latest',
139 });
140 });
141
@@ -158,11 +156,11 @@ describe('Tools', () => {
156 await context.tools.getRawComposioTools(query);
157
158 expect(mockClient.tools.list).toHaveBeenCalledWith({
161 - tool_slugs: undefined,
159 toolkit_slug: 'todoist',
160 limit: 10,
161 search: 'add task',
162 scopes: ['task:add'],
163 + toolkit_versions: 'latest',
164 });
165 });
166
@@ -221,7 +219,7 @@ describe('Tools', () => {
219
220 const result = await context.tools.getRawComposioTools(
221 { tools: ['TEST_TOOL'] },
224 - schemaModifier
222 + { modifySchema: schemaModifier }
223 );
224
225 expect(schemaModifier).toHaveBeenCalled();
@@ -242,7 +240,7 @@ describe('Tools', () => {
240 {
241 toolkits: ['invalid'],
242 },
245 - invalidModifier
243 + { modifySchema: invalidModifier }
244 )
245 ).rejects.toThrow('Invalid schema modifier. Not a function.');
246 });
@@ -276,7 +274,7 @@ describe('Tools', () => {
274
275 const result = await context.tools.getRawComposioToolBySlug(slug);
276
279 - expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug);
277 + expect(mockClient.tools.retrieve).toHaveBeenCalledWith(slug, { toolkit_versions: 'latest' });
278 expect(result.slug).toEqual(toolMocks.transformedTool.slug);
279 });
280
@@ -316,7 +314,9 @@ describe('Tools', () => {
314
315 mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
316
319 - const result = await context.tools.getRawComposioToolBySlug(slug, schemaModifier);
317 + const result = await context.tools.getRawComposioToolBySlug(slug, {
318 + modifySchema: schemaModifier,
319 + });
320
321 expect(schemaModifier).toHaveBeenCalled();
322 expect(result.description).toEqual('Modified description');
@@ -337,7 +337,9 @@ describe('Tools', () => {
337
338 const result = await context.tools.get(userId, slug);
339
340 - expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, undefined);
340 + expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
341 + modifySchema: undefined,
342 + });
343 expect(context.mockProvider.wrapTools).toHaveBeenCalledWith(
344 [toolMocks.transformedTool],
345 expect.any(Function)
@@ -356,7 +358,7 @@ describe('Tools', () => {
358
359 const result = await context.tools.get(userId, filters);
360
359 - expect(getRawComposioToolsSpy).toHaveBeenCalledWith(filters, undefined);
361 + expect(getRawComposioToolsSpy).toHaveBeenCalledWith(filters, { modifySchema: undefined });
362 expect(context.mockProvider.wrapTools).toHaveBeenCalled();
363 expect(result).toEqual('wrapped-tools-collection');
364 });
@@ -375,7 +377,9 @@ describe('Tools', () => {
377
378 await context.tools.get(userId, slug, { modifySchema: schemaModifier });
379
378 - expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, schemaModifier);
380 + expect(getRawComposioToolBySlugSpy).toHaveBeenCalledWith(slug, {
381 + modifySchema: schemaModifier,
382 + });
383 });
384 });
385
@@ -417,7 +421,7 @@ describe('Tools', () => {
421 custom_connection_data: undefined,
422 arguments: body.arguments,
423 user_id: body.userId,
420 - version: undefined,
424 + version: 'latest',
425 text: undefined,
426 });
427 expect(result).toEqual(toolMocks.toolExecuteResponse);
@@ -442,7 +446,7 @@ describe('Tools', () => {
446 custom_connection_data: undefined,
447 arguments: body.arguments,
448 user_id: body.userId,
445 - version: undefined,
449 + version: 'latest',
450 text: undefined,
451 });
452 expect(result).toEqual(toolMocks.toolExecuteResponse);
@@ -714,4 +718,459 @@ describe('Tools', () => {
718 );
719 });
720 });
721 +
722 + describe('Version Integration Tests', () => {
723 + describe('toolkit versions in tool fetching', () => {
724 + it('should pass default "latest" version when no version is configured', async () => {
725 + const context = createTestContext();
726 +
727 + mockClient.tools.list.mockResolvedValueOnce({
728 + items: [toolMocks.rawTool],
729 + totalPages: 1,
730 + });
731 +
732 + await context.tools.getRawComposioTools({ tools: ['TEST_TOOL'] });
733 +
734 + expect(mockClient.tools.list).toHaveBeenCalledWith({
735 + tool_slugs: 'TEST_TOOL',
736 + limit: 9999,
737 + toolkit_versions: 'latest',
738 + });
739 + });
740 +
741 + it('should pass global version string when configured', async () => {
742 + const mockProvider = new MockProvider();
743 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
744 + toolkitVersions: '20250902_00' as any,
745 + });
746 +
747 + mockClient.tools.list.mockResolvedValueOnce({
748 + items: [toolMocks.rawTool],
749 + totalPages: 1,
750 + });
751 +
752 + await tools.getRawComposioTools({ toolkits: ['github'] });
753 +
754 + expect(mockClient.tools.list).toHaveBeenCalledWith({
755 + toolkit_slug: 'github',
756 + toolkit_versions: '20250902_00',
757 + });
758 + });
759 +
760 + it('should pass toolkit-specific versions when configured as object', async () => {
761 + const mockProvider = new MockProvider();
762 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
763 + toolkitVersions: {
764 + github: '20250902_00',
765 + slack: 'latest',
766 + gmail: '20250901_01',
767 + },
768 + });
769 +
770 + mockClient.tools.list.mockResolvedValueOnce({
771 + items: [toolMocks.rawTool],
772 + totalPages: 1,
773 + });
774 +
775 + await tools.getRawComposioTools({ toolkits: ['github'] });
776 +
777 + expect(mockClient.tools.list).toHaveBeenCalledWith({
778 + toolkit_slug: 'github',
779 + toolkit_versions: {
780 + github: '20250902_00',
781 + slack: 'latest',
782 + gmail: '20250901_01',
783 + },
784 + });
785 + });
786 +
787 + it('should pass versions when fetching tools by tool slugs', async () => {
788 + const mockProvider = new MockProvider();
789 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
790 + toolkitVersions: {
791 + github: '20250902_00',
792 + slack: 'latest',
793 + },
794 + });
795 +
796 + mockClient.tools.list.mockResolvedValueOnce({
797 + items: [toolMocks.rawTool],
798 + totalPages: 1,
799 + });
800 +
801 + await tools.getRawComposioTools({ tools: ['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'] });
802 +
803 + expect(mockClient.tools.list).toHaveBeenCalledWith({
804 + tool_slugs: 'GITHUB_CREATE_ISSUE,SLACK_SEND_MESSAGE',
805 + limit: 9999,
806 + toolkit_versions: {
807 + github: '20250902_00',
808 + slack: 'latest',
809 + },
810 + });
811 + });
812 +
813 + it('should pass versions when searching tools', async () => {
814 + const mockProvider = new MockProvider();
815 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
816 + toolkitVersions: 'latest',
817 + });
818 +
819 + mockClient.tools.list.mockResolvedValueOnce({
820 + items: [toolMocks.rawTool],
821 + totalPages: 1,
822 + });
823 +
824 + await tools.getRawComposioTools({ search: 'create issue' });
825 +
826 + expect(mockClient.tools.list).toHaveBeenCalledWith({
827 + search: 'create issue',
828 + toolkit_versions: 'latest',
829 + });
830 + });
831 + });
832 +
833 + describe('toolkit versions in individual tool retrieval', () => {
834 + it('should pass default "latest" version when retrieving single tool', async () => {
835 + const context = createTestContext();
836 +
837 + mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
838 +
839 + await context.tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
840 +
841 + expect(mockClient.tools.retrieve).toHaveBeenCalledWith('GITHUB_CREATE_ISSUE', {
842 + toolkit_versions: 'latest',
843 + });
844 + });
845 +
846 + it('should pass global version when retrieving single tool', async () => {
847 + const mockProvider = new MockProvider();
848 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
849 + toolkitVersions: '20250902_00' as any,
850 + });
851 +
852 + mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
853 +
854 + await tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
855 +
856 + expect(mockClient.tools.retrieve).toHaveBeenCalledWith('GITHUB_CREATE_ISSUE', {
857 + toolkit_versions: '20250902_00',
858 + });
859 + });
860 +
861 + it('should pass toolkit-specific versions when retrieving single tool', async () => {
862 + const mockProvider = new MockProvider();
863 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
864 + toolkitVersions: {
865 + github: '20250902_00',
866 + slack: 'latest',
867 + gmail: '20250901_01',
868 + },
869 + });
870 +
871 + mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
872 +
873 + await tools.getRawComposioToolBySlug('SLACK_SEND_MESSAGE');
874 +
875 + expect(mockClient.tools.retrieve).toHaveBeenCalledWith('SLACK_SEND_MESSAGE', {
876 + toolkit_versions: {
877 + github: '20250902_00',
878 + slack: 'latest',
879 + gmail: '20250901_01',
880 + },
881 + });
882 + });
883 + });
884 +
885 + describe('toolkit versions in tool execution', () => {
886 + it('should use default "latest" version when executing tool without explicit version', async () => {
887 + const context = createTestContext();
888 + const spies = await mockToolExecution(context.tools);
889 +
890 + const executeParams: ToolExecuteParams = {
891 + arguments: { title: 'Test Issue' },
892 + connectedAccountId: 'test-account',
893 + };
894 +
895 + await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
896 +
897 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
898 + allow_tracing: undefined,
899 + connected_account_id: 'test-account',
900 + custom_auth_params: undefined,
901 + custom_connection_data: undefined,
902 + arguments: { title: 'Test Issue' },
903 + user_id: undefined,
904 + version: 'latest', // should use latest as default
905 + text: undefined,
906 + });
907 + });
908 +
909 + it('should use global version when configured', async () => {
910 + const mockProvider = new MockProvider();
911 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
912 + toolkitVersions: '20250902_00' as any,
913 + });
914 + const spies = await mockToolExecution(tools);
915 +
916 + const executeParams: ToolExecuteParams = {
917 + arguments: { title: 'Test Issue' },
918 + connectedAccountId: 'test-account',
919 + };
920 +
921 + await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
922 +
923 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
924 + allow_tracing: undefined,
925 + connected_account_id: 'test-account',
926 + custom_auth_params: undefined,
927 + custom_connection_data: undefined,
928 + arguments: { title: 'Test Issue' },
929 + user_id: undefined,
930 + version: '20250902_00', // should use global version
931 + text: undefined,
932 + });
933 + });
934 +
935 + it('should use toolkit-specific version when configured as object', async () => {
936 + const mockProvider = new MockProvider();
937 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
938 + toolkitVersions: {
939 + 'test-toolkit': '20250902_00', // Use the actual toolkit slug from mock
940 + slack: 'latest',
941 + gmail: '20250901_01',
942 + },
943 + });
944 +
945 + // Mock the tool with test-toolkit (matching the mock data)
946 + const testTool = {
947 + ...toolMocks.transformedTool,
948 + toolkit: { slug: 'test-toolkit', name: 'Test Toolkit' }, // Use actual mock toolkit
949 + };
950 +
951 + const spies = await mockToolExecution(tools);
952 + // Override the mock to return our custom tool with the correct toolkit
953 + spies.getRawComposioToolBySlugSpy.mockReset();
954 + spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(testTool as unknown as Tool);
955 +
956 + const executeParams: ToolExecuteParams = {
957 + arguments: { title: 'Test Issue' },
958 + connectedAccountId: 'test-account',
959 + };
960 +
961 + await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
962 +
963 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
964 + allow_tracing: undefined,
965 + connected_account_id: 'test-account',
966 + custom_auth_params: undefined,
967 + custom_connection_data: undefined,
968 + arguments: { title: 'Test Issue' },
969 + user_id: undefined,
970 + version: '20250902_00', // should use test-toolkit-specific version
971 + text: undefined,
972 + });
973 + });
974 +
975 + it('should use fallback to "latest" when toolkit not in version mapping', async () => {
976 + const mockProvider = new MockProvider();
977 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
978 + toolkitVersions: {
979 + github: '20250902_00',
980 + slack: 'latest',
981 + },
982 + });
983 +
984 + // Mock the tool with notion toolkit (not in version mapping)
985 + const notionTool = {
986 + ...toolMocks.transformedTool,
987 + toolkit: { slug: 'notion', name: 'Notion' },
988 + };
989 +
990 + const spies = await mockToolExecution(tools);
991 + spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(notionTool as unknown as Tool);
992 +
993 + const executeParams: ToolExecuteParams = {
994 + arguments: { title: 'Test Page' },
995 + connectedAccountId: 'test-account',
996 + };
997 +
998 + await tools.execute('NOTION_CREATE_PAGE', executeParams);
999 +
1000 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1001 + allow_tracing: undefined,
1002 + connected_account_id: 'test-account',
1003 + custom_auth_params: undefined,
1004 + custom_connection_data: undefined,
1005 + arguments: { title: 'Test Page' },
1006 + user_id: undefined,
1007 + version: 'latest', // should fallback to latest for unknown toolkit
1008 + text: undefined,
1009 + });
1010 + });
1011 +
1012 + it('should prioritize explicit version parameter over configured versions', async () => {
1013 + const mockProvider = new MockProvider();
1014 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1015 + toolkitVersions: {
1016 + github: '20250902_00',
1017 + slack: 'latest',
1018 + },
1019 + });
1020 +
1021 + const spies = await mockToolExecution(tools);
1022 +
1023 + const executeParams: ToolExecuteParams = {
1024 + arguments: { title: 'Test Issue' },
1025 + connectedAccountId: 'test-account',
1026 + version: '20250903_00', // explicit version should override config
1027 + };
1028 +
1029 + await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
1030 +
1031 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1032 + allow_tracing: undefined,
1033 + connected_account_id: 'test-account',
1034 + custom_auth_params: undefined,
1035 + custom_connection_data: undefined,
1036 + arguments: { title: 'Test Issue' },
1037 + user_id: undefined,
1038 + version: '20250903_00', // explicit version takes precedence
1039 + text: undefined,
1040 + });
1041 + });
1042 +
1043 + it('should handle tool without toolkit gracefully', async () => {
1044 + const mockProvider = new MockProvider();
1045 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1046 + toolkitVersions: {
1047 + github: '20250902_00',
1048 + },
1049 + });
1050 +
1051 + // Mock the tool without toolkit
1052 + const toolWithoutToolkit = {
1053 + ...toolMocks.transformedTool,
1054 + toolkit: undefined,
1055 + };
1056 +
1057 + const spies = await mockToolExecution(tools);
1058 + spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(
1059 + toolWithoutToolkit as unknown as Tool
1060 + );
1061 +
1062 + const executeParams: ToolExecuteParams = {
1063 + arguments: { query: 'test' },
1064 + connectedAccountId: 'test-account',
1065 + };
1066 +
1067 + await tools.execute('SOME_CUSTOM_TOOL', executeParams);
1068 +
1069 + expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1070 + allow_tracing: undefined,
1071 + connected_account_id: 'test-account',
1072 + custom_auth_params: undefined,
1073 + custom_connection_data: undefined,
1074 + arguments: { query: 'test' },
1075 + user_id: undefined,
1076 + version: 'latest', // should fallback to latest for unknown toolkit
1077 + text: undefined,
1078 + });
1079 + });
1080 + });
1081 +
1082 + describe('environment variable integration', () => {
1083 + const originalEnv = process.env;
1084 +
1085 + beforeEach(() => {
1086 + process.env = { ...originalEnv };
1087 + });
1088 +
1089 + afterEach(() => {
1090 + process.env = originalEnv;
1091 + });
1092 +
1093 + it('should use environment variable versions when no user config provided', async () => {
1094 + // Set environment variables
1095 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1096 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1097 +
1098 + const mockProvider = new MockProvider();
1099 + // Pass the processed environment variables to the Tools constructor
1100 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1101 + toolkitVersions: {
1102 + github: '20250903_00',
1103 + slack: 'latest',
1104 + },
1105 + });
1106 +
1107 + mockClient.tools.list.mockResolvedValueOnce({
1108 + items: [toolMocks.rawTool],
1109 + totalPages: 1,
1110 + });
1111 +
1112 + await tools.getRawComposioTools({ toolkits: ['github'] });
1113 +
1114 + expect(mockClient.tools.list).toHaveBeenCalledWith({
1115 + toolkit_slug: 'github',
1116 + toolkit_versions: {
1117 + github: '20250903_00',
1118 + slack: 'latest',
1119 + },
1120 + });
1121 + });
1122 +
1123 + it('should prioritize user config over environment variables', async () => {
1124 + // Set environment variables
1125 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1126 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1127 +
1128 + const mockProvider = new MockProvider();
1129 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1130 + toolkitVersions: {
1131 + github: '20250904_00', // should override env
1132 + gmail: '20250902_00', // new toolkit not in env
1133 + },
1134 + });
1135 +
1136 + mockClient.tools.list.mockResolvedValueOnce({
1137 + items: [toolMocks.rawTool],
1138 + totalPages: 1,
1139 + });
1140 +
1141 + await tools.getRawComposioTools({ toolkits: ['github'] });
1142 +
1143 + expect(mockClient.tools.list).toHaveBeenCalledWith({
1144 + toolkit_slug: 'github',
1145 + toolkit_versions: {
1146 + github: '20250904_00', // user config wins
1147 + gmail: '20250902_00', // from user config
1148 + },
1149 + });
1150 + });
1151 +
1152 + it('should use global version string to override everything', async () => {
1153 + // Set environment variables
1154 + process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1155 + process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1156 +
1157 + const mockProvider = new MockProvider();
1158 + const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1159 + toolkitVersions: '20250905_00' as any, // global version overrides everything
1160 + });
1161 +
1162 + mockClient.tools.list.mockResolvedValueOnce({
1163 + items: [toolMocks.rawTool],
1164 + totalPages: 1,
1165 + });
1166 +
1167 + await tools.getRawComposioTools({ toolkits: ['github'] });
1168 +
1169 + expect(mockClient.tools.list).toHaveBeenCalledWith({
1170 + toolkit_slug: 'github',
1171 + toolkit_versions: '20250905_00', // global version ignores env vars
1172 + });
1173 + });
1174 + });
1175 + });
1176 });
ts/packages/providers/langchain/README.md
+6
@@ -52,6 +52,12 @@ const tools = await composio.tools.get('user123', {
52 limit: 10,
53 });
54
55 +// Get tools with version control
56 +const versionedTools = await composio.tools.get('user123', {
57 + toolkits: ['gmail'],
58 + toolkitVersions: { gmail: '20250909_00' },
59 +});
60 +
61 // Get a specific tool
62 const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');
63 ```
ts/packages/providers/langchain/test/langchain.test.ts
+14 -14
@@ -1,4 +1,4 @@
1 -import { describe, it, expect, beforeEach } from 'vitest';
1 +import { describe, it, expect, beforeEach, vi } from 'vitest';
2 import { LangchainProvider } from '../src';
3 import { Tool } from '@composio/core';
4 import { DynamicStructuredTool } from '@langchain/core/tools';
@@ -6,30 +6,30 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
6 describe('LangchainProvider', () => {
7 let provider: LangchainProvider;
8 let sampleTool: Tool;
9 - let executeToolFn: (
10 - toolSlug: string,
11 - params: Record<string, unknown>,
12 - modifiers?: any
13 - ) => Promise<any>;
9 + let executeToolFn: (toolSlug: string, params: Record<string, unknown>) => Promise<any>;
10
11 beforeEach(() => {
12 provider = new LangchainProvider();
13
14 // Create a real execute function that simulates tool execution
19 - executeToolFn = async (toolSlug: string, params: Record<string, unknown>) => {
20 - // Simulate actual tool execution with realistic response
21 - return {
22 - data: { toolSlug, params },
23 - error: null,
24 - successful: true,
25 - };
26 - };
15 + executeToolFn = vi
16 + .fn()
17 + .mockImplementation(async (toolSlug: string, params: Record<string, unknown>) => {
18 + // Simulate actual tool execution with realistic response
19 + return {
20 + data: { toolSlug, params },
21 + error: null,
22 + successful: true,
23 + };
24 + });
25
26 // Create a real sample tool that matches actual tool structure
27 sampleTool = {
28 slug: 'SEARCH_TOOL',
29 name: 'Search Tool',
30 description: 'Search for information in the knowledge base',
31 + version: '20250909_00',
32 + availableVersions: ['20250909_00', '20250901_00'],
33 inputParameters: {
34 type: 'object',
35 properties: {
ts/packages/providers/mastra/test/mastra.test.ts
+30
@@ -84,6 +84,8 @@ describe('MastraProvider', () => {
84 slug: 'test-toolkit',
85 name: 'Test Toolkit',
86 },
87 + version: '20250909_00',
88 + availableVersions: ['20250909_00', '20250901_00'],
89 tags: [],
90 };
91
@@ -202,6 +204,34 @@ describe('MastraProvider', () => {
204 });
205 });
206
207 + it('should preserve and pass tool version information when executing', async () => {
208 + const toolWithVersion = { ...mockTool, version: '20250101_01' };
209 + provider.wrapTool(toolWithVersion, mockExecuteToolFn) as unknown as MockedMastraTool;
210 +
211 + // Extract the execute function from the call to createTool()
212 + const executeFunction = (createTool as any).mock.calls[0][0].execute;
213 +
214 + // Test that the version is passed correctly
215 + const context = { input: 'version-test' };
216 + await executeFunction({ context });
217 +
218 + expect(mockExecuteToolFn).toHaveBeenCalledWith(toolWithVersion.slug, context);
219 + });
220 +
221 + it('should handle tools without version information', async () => {
222 + const toolWithoutVersion = { ...mockTool, version: undefined };
223 + provider.wrapTool(toolWithoutVersion, mockExecuteToolFn) as unknown as MockedMastraTool;
224 +
225 + // Extract the execute function from the call to createTool()
226 + const executeFunction = (createTool as any).mock.calls[0][0].execute;
227 +
228 + // Test that undefined version is passed correctly
229 + const context = { input: 'no-version-test' };
230 + await executeFunction({ context });
231 +
232 + expect(mockExecuteToolFn).toHaveBeenCalledWith(toolWithoutVersion.slug, context);
233 + });
234 +
235 it('should handle empty context parameter', async () => {
236 provider.wrapTool(mockTool, mockExecuteToolFn) as unknown as MockedMastraTool;
237
ts/packages/providers/openai-agents/test/openai-agents.test.ts
+2 -20
@@ -45,6 +45,8 @@ describe('OpenAIAgentsProvider', () => {
45 slug: 'test-tool',
46 name: 'Test Tool',
47 description: 'A tool for testing',
48 + version: '20250909_00',
49 + availableVersions: ['20250909_00', '20250901_00'],
50 inputParameters: {
51 type: 'object',
52 properties: {
@@ -110,26 +112,6 @@ describe('OpenAIAgentsProvider', () => {
112
113 expect(wrapped._isMockedOpenAIAgentTool).toBe(true);
114 });
113 -
114 - it('should create a function that executes the tool with the right parameters', async () => {
115 - provider.wrapTool(mockTool, mockExecuteToolFn) as unknown as MockedOpenAIAgentTool;
116 -
117 - // Extract the execute function from the call to tool()
118 - const executeFunction = (createOpenAIAgentTool as any).mock.calls[0][0].execute;
119 -
120 - // Test the execute function with an object parameter
121 - const params = { input: 'test-value' };
122 - await executeFunction(params);
123 -
124 - expect(mockExecuteToolFn).toHaveBeenCalledWith(mockTool.slug, params);
125 -
126 - // Reset and test with a JSON string parameter
127 - vi.clearAllMocks();
128 - const stringParams = JSON.stringify(params);
129 - await executeFunction(stringParams);
130 -
131 - expect(mockExecuteToolFn).toHaveBeenCalledWith(mockTool.slug, params);
132 - });
115 });
116
117 describe('wrapTools', () => {
ts/packages/providers/vercel/README.md
+6
@@ -51,6 +51,12 @@ const tools = await composio.tools.get('user123', {
51 limit: 10,
52 });
53
54 +// Get tools with version control
55 +const versionedTools = await composio.tools.get('user123', {
56 + toolkits: ['gmail'],
57 + toolkitVersions: { gmail: '20250909_00' },
58 +});
59 +
60 // Get a specific tool
61 const sendEmailTool = await composio.tools.get('user123', 'GMAIL_SEND_EMAIL');
62 ```
ts/packages/providers/vercel/test/vercel.test.ts
+2
@@ -45,6 +45,8 @@ describe('VercelProvider', () => {
45 slug: 'test-tool',
46 name: 'Test Tool',
47 description: 'A tool for testing',
48 + version: '20250909_00',
49 + availableVersions: ['20250909_00', '20250901_00'],
50 inputParameters: {
51 type: 'object',
52 properties: {