Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Fix typedocs and examples for toolkit version (#2212)
Musthaq Ahamad31521bd1a509
diff --git a/.changeset/silly-parrots-grab.md b/.changeset/silly-parrots-grab.mdnew file mode 100644index 000000000..7c561d501--- /dev/null+++ b/.changeset/silly-parrots-grab.md@@ -0,0 +1,5 @@+---+'@composio/core': patch+---++Update typedocs and examples for toolkit versionsdiff --git a/.github/workflows/ts.test.yml b/.github/workflows/ts.test.ymlindex 7f87e03ef..e74ba3664 100644--- a/.github/workflows/ts.test.yml+++ b/.github/workflows/ts.test.yml@@ -14,6 +14,8 @@ jobs:test:name: Test Typescript SDKruns-on: ubuntu-latest+ permissions:+ pull-requests: writesteps:- name: Checkout Codediff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 4f4359a53..5e448f2b4 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -15,6 +15,9 @@ catalogs:'@composio/client':specifier: 0.1.0-alpha.46version: 0.1.0-alpha.46+ '@modelcontextprotocol/sdk':+ specifier: ^1.22.0+ version: 1.23.0tsup:specifier: ^8.5.0version: 8.5.1@@ -371,7 +374,7 @@ importers:specifier: ^1.1.0version: 1.30.0(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))'@modelcontextprotocol/sdk':- specifier: ^1.18.0+ specifier: 'catalog:'version: 1.23.0(@cfworker/[email protected])([email protected])dotenv:specifier: ^16.4.1@@ -508,7 +511,7 @@ importers:specifier: workspace:*version: link:../../packages/providers/vercel'@modelcontextprotocol/sdk':- specifier: ^1.18.0+ specifier: 'catalog:'version: 1.23.0(@cfworker/[email protected])([email protected])ai:specifier: '>=5.0.102'@@ -558,7 +561,7 @@ importers:specifier: workspace:*version: link:../../packages/providers/openai-agents'@modelcontextprotocol/sdk':- specifier: ^1.18.0+ specifier: 'catalog:'version: 1.23.0(@cfworker/[email protected])([email protected])'@openai/agents':specifier: ^0.1.4@@ -729,7 +732,7 @@ importers:specifier: workspace:*version: link:../../packages/providers/vercel'@modelcontextprotocol/sdk':- specifier: ^1.18.0+ specifier: 'catalog:'version: 1.23.0(@cfworker/[email protected])([email protected])ai:specifier: '>=5.0.102'diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex f0cfb99b4..eb3ad20c3 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -16,7 +16,8 @@ catalog:'@cloudflare/vitest-pool-workers': ^0.9.2'@cloudflare/workers-types': ^4.20250917.0'@composio/client': 0.1.0-alpha.46- ai: ^5.0.102+ '@modelcontextprotocol/sdk': ^1.22.0+ ai: 5.0.52openai: ^5.20.3tsup: ^8.5.0tsx: ^4.20.5diff --git a/python/README.md b/python/README.mdindex 0ea819db0..7c83f7082 100644--- a/python/README.md+++ b/python/README.md@@ -208,7 +208,7 @@ composio = Composio(allow_tracking=True, # Enable/disable telemetry (default: True)file_download_dir="./downloads", # Directory for file downloadsprovider=OpenAIProvider(), # Custom provider (default: OpenAIProvider)- toolkit_versions="latest" # Toolkit versions to use+ toolkit_versions={ "github": "12202025_01" } # Toolkit versions to use)```diff --git a/python/composio/core/types.py b/python/composio/core/types.pyindex 20d94ef16..cfc4ced0b 100644--- a/python/composio/core/types.py+++ b/python/composio/core/types.py@@ -6,12 +6,11 @@ import typing_extensions as te# Tool versioning typesToolkitLatestVersion = te.Literal["latest"]-ToolkitVersion = str # Can be "latest" or any version string like "20250906_01"+ToolkitVersion = t.Union[+ ToolkitLatestVersion, str+] # Can be "latest" or any version string like "20250906_01"ToolkitVersions = t.Dict[str, ToolkitVersion]-ToolkitVersionParam = t.Union[- str, ToolkitVersions, None-] # String can be any global version-+ToolkitVersionParam = t.Union[ToolkitVersions, ToolkitLatestVersion, None]__all__ = ["ToolkitLatestVersion",diff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex 47b7f2f9e..d714ae565 100644--- a/python/composio/sdk.py+++ b/python/composio/sdk.py@@ -73,10 +73,10 @@ class Composio(t.Generic[TProvider], WithLogger)::param base_url: The base URL to use for the SDK.:param timeout: The timeout to use for the SDK.:param max_retries: The maximum number of retries to use for the SDK.- :param toolkit_versions: The versions of the toolkits to use. Can be:+ :param toolkit_versions: A dictionary mapping toolkit names to specific versions:+ - A dictionary mapping toolkit names to specific versions- A string (e.g., 'latest', '20250906_01') to use the same version for all toolkits- - A dict mapping toolkit names to specific versions- - None to use 'latest' as default+ - None or omitted to use 'latest' as default"""WithLogger.__init__(self)api_key = kwargs.get("api_key", os.environ.get("COMPOSIO_API_KEY"))diff --git a/python/composio/utils/toolkit_version.py b/python/composio/utils/toolkit_version.pyindex 06e92f604..1c96bdb5f 100644--- a/python/composio/utils/toolkit_version.py+++ b/python/composio/utils/toolkit_version.py@@ -38,19 +38,16 @@ def get_toolkit_versions(Gets toolkit versions configuration by merging environment variables, user-provided defaults, and fallbacks.Priority order:- 1. If default_versions is a string, use it as global version for all toolkits (e.g., "latest", "20250906_01")+ 1. If default_versions is a string, use it as a global version for all toolkits2. User-provided toolkit version mappings (default_versions dict)3. Environment variables (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>)4. Fallback to 'latest' if no versions are configured- :param default_versions: Optional default versions configuration (string for global version- or dict mapping toolkit names to versions). String can be any version- like "latest", "20250906_01", etc.- :return: Toolkit versions configuration - either a global version string,- toolkit-specific version mapping, or 'latest'+ :param default_versions: Optional default versions configuration (string for global version or dict mapping toolkit names to versions)+ :return: Toolkit versions configuration - either a string for global version or dict mapping toolkit names to versions"""- # If already set by user as a string (e.g., 'latest', '20250906_01'), use it as global version for all toolkits- if default_versions and isinstance(default_versions, str):+ # If already set by user as a string, use it as global version for all toolkits+ if isinstance(default_versions, str):return default_versions# Check if there are envs similar to COMPOSIO_TOOLKIT_VERSION_GITHUB then extract the toolkit namediff --git a/python/tests/test_core_types.py b/python/tests/test_core_types.pyindex 0827d167c..7e1e37c85 100644--- a/python/tests/test_core_types.py+++ b/python/tests/test_core_types.py@@ -16,9 +16,13 @@ class TestCoreTypes:# Should be a Literal["latest"]assert hasattr(ToolkitLatestVersion, "__origin__")- def test_toolkit_version_is_string(self):- """Test ToolkitVersion is string type."""- assert ToolkitVersion is str+ def test_toolkit_version_is_union(self):+ """Test ToolkitVersion is a Union type."""+ # ToolkitVersion should be Union[Literal["latest"], str]+ import typing++ assert hasattr(ToolkitVersion, "__origin__")+ assert ToolkitVersion.__origin__ is typing.Uniondef test_toolkit_versions_is_dict(self):"""Test ToolkitVersions is dict type."""diff --git a/python/tests/test_toolkit_version.py b/python/tests/test_toolkit_version.pyindex 2b19f89ba..30b76e1eb 100644--- a/python/tests/test_toolkit_version.py+++ b/python/tests/test_toolkit_version.py@@ -136,7 +136,7 @@ class TestToolkitVersion:with pytest.MonkeyPatch().context() as m:# Test 1: String global version overrides everythingm.setenv("COMPOSIO_TOOLKIT_VERSION_GITHUB", "env_version")- result = get_toolkit_versions("global_version")+ result = get_toolkit_version("github", "global_version")assert result == "global_version"# Test 2: User dict overrides env varsdiff --git a/ts/docs/api/tools.md b/ts/docs/api/tools.mdindex 88fcc5c13..8b8de1e37 100644--- a/ts/docs/api/tools.md+++ b/ts/docs/api/tools.md@@ -63,7 +63,7 @@ const customTool = await composio.tools.get('default', 'GITHUB_GET_REPOS', {Executes a given tool with the provided parameters manually.-> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if `'latest'` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.+> **Important:** When manually executing tools (especially in workflows), a specific version is **required**. The method will throw an error if toolkitVersion is not provided or `latest` is used as the version. This ensures there are no mismatches in tool arguments when new versions are released. You can bypass this requirement using `dangerouslySkipVersionCheck: true`, but this is **not recommended for production**.```typescript// Execute with a pinned version (REQUIRED for workflows and manual execution)diff --git a/ts/docs/api/triggers.md b/ts/docs/api/triggers.mdindex c6f68fb0e..f4bee2a06 100644--- a/ts/docs/api/triggers.md+++ b/ts/docs/api/triggers.md@@ -280,7 +280,7 @@ const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');**Behavior:**-- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)+- The method uses the global toolkit version configured in the Composio client (defaults to `'latest'` if not provided)- To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance- See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versionsdiff --git a/ts/docs/getting-started.md b/ts/docs/getting-started.mdindex 4448c446f..e85ee7d7e 100644--- a/ts/docs/getting-started.md+++ b/ts/docs/getting-started.md@@ -62,20 +62,7 @@ Example: `12082025_00` represents version 00 released on August 12, 2025.#### Configuration Options-**Option 1: Global Version for All Toolkits**--```typescript-const composio = new Composio({- toolkitVersions: 'latest' // Use latest version for all toolkits-});--// Or pin a specific version globally-const composio = new Composio({- toolkitVersions: '12082025_00' // All toolkits use this version-});-```--**Option 2: Specific Versions per Toolkit (Recommended for Production)**+**Option 1: Specific Versions per Toolkit (Recommended for Production)**```typescriptconst composio = new Composio({@@ -87,7 +74,7 @@ const composio = new Composio({});```-**Option 3: Using Environment Variables**+**Option 2: Using Environment Variables**You can set toolkit versions using environment variables:@@ -107,6 +94,16 @@ const composio = new Composio({});```+**Option 3: Latest version for all toolkits**+If omitted, SDK will use `latest` version for all the toolkits++```typescript+const composio = new Composio({+ apiKey: 'your-api-key',+ // since omitted, this will use `latest` for all toolkits+})+```+#### Version Behavior- **Tools & Triggers:** The toolkit version configuration applies to both tools and triggersdiff --git a/ts/examples/google/package.json b/ts/examples/google/package.jsonindex 07b7e745b..b73974f86 100644--- a/ts/examples/google/package.json+++ b/ts/examples/google/package.json@@ -24,7 +24,7 @@"@composio/core": "workspace:*","@composio/google": "workspace:*","@google/genai": "^1.1.0",- "@modelcontextprotocol/sdk": "^1.18.0",+ "@modelcontextprotocol/sdk": "catalog:","dotenv": "^16.4.1"},"devDependencies": {diff --git a/ts/examples/mcp/package.json b/ts/examples/mcp/package.jsonindex c791a392f..ad1e8682a 100644--- a/ts/examples/mcp/package.json+++ b/ts/examples/mcp/package.json@@ -21,7 +21,7 @@"@ai-sdk/openai": "^2.0.35","@composio/core": "workspace:*","@composio/vercel": "workspace:*",- "@modelcontextprotocol/sdk": "^1.18.0",+ "@modelcontextprotocol/sdk": "catalog:","ai": "catalog:","dotenv": "^16.4.1"},diff --git a/ts/examples/openai/package.json b/ts/examples/openai/package.jsonindex 1da3456d7..cca6c5155 100644--- a/ts/examples/openai/package.json+++ b/ts/examples/openai/package.json@@ -22,7 +22,7 @@"@composio/core": "workspace:*","@composio/openai": "workspace:*","@composio/openai-agents": "workspace:*",- "@modelcontextprotocol/sdk": "^1.18.0",+ "@modelcontextprotocol/sdk": "catalog:","@openai/agents": "^0.1.4","dotenv": "^16.4.1","openai": "^5.16.0",diff --git a/ts/examples/vercel/package.json b/ts/examples/vercel/package.jsonindex c634b13f2..786d56c53 100644--- a/ts/examples/vercel/package.json+++ b/ts/examples/vercel/package.json@@ -18,7 +18,7 @@"@ai-sdk/openai": "^2.0.16","@composio/core": "workspace:*","@composio/vercel": "workspace:*",- "@modelcontextprotocol/sdk": "^1.18.0",+ "@modelcontextprotocol/sdk": "catalog:","ai": "catalog:","dotenv": "^16.5.0","zod-to-json-schema": "^3.24.6"diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.tsindex 155891d77..690682bcd 100644--- a/ts/packages/core/src/composio.ts+++ b/ts/packages/core/src/composio.ts@@ -78,6 +78,7 @@ export type ComposioConfig<disableVersionCheck?: boolean;/*** The versions of the toolkits to use for tool execution and retrieval.+ * Omit to use 'latest' for all toolkits.** **Version Control:*** When executing tools manually (via `tools.execute()`), if this resolves to "latest",@@ -89,9 +90,9 @@ export type ComposioConfig<* Defaults to 'latest' if nothing is provided.* You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`*- * @example Global version for all toolkits+ * @example Global version for all toolkits, omit to use 'latest'* ```typescript- * const composio = new Composio({ toolkitVersions: 'latest' });+ * const composio = new Composio();* ```** @example Specific versions for different toolkits (recommended for production)diff --git a/ts/packages/core/src/types/tool.types.ts b/ts/packages/core/src/types/tool.types.tsindex b6d17c3bd..8504535ae 100644--- a/ts/packages/core/src/types/tool.types.ts+++ b/ts/packages/core/src/types/tool.types.ts@@ -142,30 +142,40 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;*/export type ToolList = Array<Tool>;+export const ToolkitLatestVersionSchema = z.literal('latest');/*** latest toolkit version param*/-export type ToolkitLatestVersion = 'latest';+export type ToolkitLatestVersion = z.infer<typeof ToolkitLatestVersionSchema>;++export const ToolkitVersionSchema = z.union([ToolkitLatestVersionSchema, z.string()]);/*** Versioning a tool based on it's toolkit version, either 'latest' or actual tool version as string '20250902_00'* @example* 'latest'* '20250902_00'*/-export type ToolkitVersion = ToolkitLatestVersion | string;+export type ToolkitVersion = z.infer<typeof ToolkitVersionSchema>;++export const ToolkitVersionsSchema = z.record(z.string(), ToolkitVersionSchema);/*** Versioning multiple toolkits* @example* { 'github': 'latest', 'slack': '20250902_00' }*/export type ToolkitVersions = Record<string, ToolkitVersion>;++export const ToolkitVersionParamSchema = z+ .union([ToolkitVersionsSchema, ToolkitLatestVersionSchema, z.undefined()])+ .describe('The versioning of the toolkits. eg: { "github": "latest", "slack": "20250902_00" }');/**- * Versioning a toolkit based on it's tool versions, either 'latest' or actual tool version as string '20250902_00'+ * Versioning a tool based on it's toolkit version* @example- * 'latest'+ * ```json* { 'github': 'latest', 'slack': '20250902_00' }+ * ```*/-export type ToolkitVersionParam = ToolkitLatestVersion | ToolkitVersions | undefined;+export type ToolkitVersionParam = z.infer<typeof ToolkitVersionParamSchema>;export const ToolListParamsSchema = z.object({tools: z.array(z.string()).optional(),