Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 20:45 UTC
[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: {