Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(ts/cli): add support for COMPOSIO_TOOLKIT_VERSION_$TOOLKIT override
jkomyno committed
Jan 28, 2026 at 14:43 UTC
0a43d39c5c8040e02e947227424bc680484a74c9
15 files changed
+1753
-73
ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
+25
-1
@@ -9,6 +9,10 @@ import { createToolkitIndex } from 'src/generation/create-toolkit-index';
9
import { pyFindComposioCoreGenerated } from 'src/effects/find-composio-core-generated';
10
import { BANNER } from 'src/generation/constants';
11
import { generatePythonSources } from 'src/generation/python/generate';
12
+import {
13
+ getToolkitVersionOverrides,
14
+ type ToolkitVersionOverrides,
15
+} from 'src/effects/toolkit-version-overrides';
16
17
export const outputOpt = Options.optional(
18
Options.directory('output-dir', {
@@ -58,6 +62,17 @@ export function generatePythonTypeStubs({
62
yield* Effect.log(`Writing type stubs to ${outputDir}...`);
63
yield* fs.makeDirectory(outputDir, { recursive: true });
64
65
+ // Read toolkit version overrides from environment variables
66
+ const versionOverrides = yield* getToolkitVersionOverrides;
67
+
68
+ // Log detected overrides for debugging
69
+ if (versionOverrides.size > 0) {
70
+ yield* Console.log('Detected toolkit version overrides:');
71
+ for (const [toolkit, version] of versionOverrides) {
72
+ yield* Console.log(` - ${toolkit}: ${version}`);
73
+ }
74
+ }
75
+
76
// Fetch data from Composio API
77
yield* Console.log('Fetching latest data from Composio API. This may take a while...');
78
@@ -100,9 +115,18 @@ export function generatePythonTypeStubs({
115
);
116
}
117
118
+ // Build version map for toolkits being generated
119
+ const versionMap: ToolkitVersionOverrides = new Map();
120
+ for (const toolkit of toolkits) {
121
+ const version = versionOverrides.get(toolkit.slug.toLowerCase() as Lowercase<string>);
122
+ if (version && version !== 'latest') {
123
+ versionMap.set(toolkit.slug.toLowerCase() as Lowercase<string>, version);
124
+ }
125
+ }
126
+
127
const typeableTools = { withTypes: false as const, tools };
128
105
- const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes });
129
+ const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes, versionMap });
130
131
// Generate Python sources
132
const sources = generatePythonSources({
ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
+127
-12
@@ -32,6 +32,11 @@ import { BANNER } from 'src/generation/constants';
32
import type { Toolkit } from 'src/models/toolkits';
33
import type { TriggerType } from 'src/models/trigger-types';
34
import type { Tool, ToolsAsEnums } from 'src/models/tools';
35
+import {
36
+ getToolkitVersionOverrides,
37
+ buildToolkitVersionSpecs,
38
+ type ToolkitVersionOverrides,
39
+} from 'src/effects/toolkit-version-overrides';
40
41
export const outputOpt = Options.optional(
42
Options.directory('output-dir', {
@@ -87,6 +92,8 @@ type FetchResult = {
92
typeableTools:
93
| { withTypes: true; tools: ReadonlyArray<Tool> }
94
| { withTypes: false; tools: ToolsAsEnums };
95
+ /** Map of lowercase toolkit slug to version (only includes non-'latest' versions) */
96
+ versionMap: ToolkitVersionOverrides;
97
};
98
99
/**
@@ -96,11 +103,23 @@ type FetchResult = {
103
function fetchFilteredData(
104
client: ComposioToolkitsRepository,
105
slugs: ReadonlyArray<string>,
99
- typeTools: boolean
106
+ typeTools: boolean,
107
+ versionOverrides: ToolkitVersionOverrides
108
): Effect.Effect<FetchResult, Error, never> {
109
return Effect.gen(function* () {
110
yield* Console.log(`Fetching data for ${slugs.length} toolkit(s): ${slugs.join(', ')}...`);
111
112
+ // Build version specs for each requested toolkit
113
+ const versionSpecs = buildToolkitVersionSpecs(slugs, versionOverrides);
114
+
115
+ // Build the version map (only includes non-'latest' versions from the filtered toolkits)
116
+ const versionMap: ToolkitVersionOverrides = new Map();
117
+ for (const spec of versionSpecs) {
118
+ if (spec.toolkitVersion !== 'latest') {
119
+ versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
120
+ }
121
+ }
122
+
123
const [filteredToolkits, filteredTriggerTypes, filteredTypeableTools] = yield* Effect.all(
124
[
125
// Fetch only the specified toolkits by slug
@@ -123,16 +142,17 @@ function fetchFilteredData(
142
Effect.logDebug(`Fetching trigger types for ${slugs.length} toolkit(s)...`).pipe(
143
Effect.flatMap(() => client.getTriggerTypes(slugs))
144
),
126
- // Fetch tools for the specified toolkits
145
+ // Fetch tools for the specified toolkits (with version support when using --type-tools)
146
Match.value(typeTools).pipe(
147
Match.when(true, withTypes =>
148
Effect.logDebug(`Fetching tools with schemas for ${slugs.length} toolkit(s)...`).pipe(
130
- Effect.flatMap(() => client.getTools(slugs)),
149
+ Effect.flatMap(() => client.getToolsByVersionSpecs(versionSpecs)),
150
Effect.map(tools => ({ withTypes, tools }))
151
)
152
),
153
Match.when(false, withTypes =>
154
// Use filtered getTools() and extract slugs - more efficient than fetching ALL enums
155
+ // Note: When not using --type-tools, version overrides don't affect the output
156
Effect.logDebug(`Fetching tool names for ${slugs.length} toolkit(s)...`).pipe(
157
Effect.flatMap(() => client.getTools(slugs)),
158
Effect.map(tools => ({
@@ -155,21 +175,20 @@ function fetchFilteredData(
175
toolkits: filteredToolkits,
176
triggerTypes: filteredTriggerTypes,
177
typeableTools: filteredTypeableTools,
178
+ versionMap,
179
};
180
});
181
}
182
183
/**
163
- * Fetches all toolkit data when no --toolkits filter is provided.
164
- * Fetches everything from the API.
184
+ * Fast path for fetching all toolkit data when no version overrides are specified.
185
+ * Fetches everything in parallel without version-specific handling.
186
*/
166
-function fetchAllData(
187
+function fetchAllDataFastPath(
188
client: ComposioToolkitsRepository,
189
typeTools: boolean
190
): Effect.Effect<FetchResult, Error, never> {
191
return Effect.gen(function* () {
171
- yield* Console.log('Fetching all toolkits, tools, and triggers from Composio API...');
172
-
192
// Fetch all data in parallel
193
// Note: getToolsAsEnums is only called when typeTools === false
194
const [allToolkits, allTriggerTypes, allTypeableTools] = yield* Effect.all(
@@ -205,10 +224,95 @@ function fetchAllData(
224
toolkits: allToolkits,
225
triggerTypes: allTriggerTypes,
226
typeableTools: allTypeableTools,
227
+ versionMap: new Map() as ToolkitVersionOverrides,
228
};
229
});
230
}
231
232
+/**
233
+ * Fetches all toolkit data with version overrides applied.
234
+ * First fetches toolkit metadata, then fetches tools with version-specific handling.
235
+ */
236
+function fetchAllDataWithOverrides(
237
+ client: ComposioToolkitsRepository,
238
+ typeTools: boolean,
239
+ versionOverrides: ToolkitVersionOverrides
240
+): Effect.Effect<FetchResult, Error, never> {
241
+ return Effect.gen(function* () {
242
+ // 1. First fetch all toolkit metadata to know what's available
243
+ const allToolkits = yield* Effect.logDebug('Fetching all toolkits...').pipe(
244
+ Effect.flatMap(() => client.getToolkits())
245
+ );
246
+ const allSlugs = allToolkits.map(t => t.slug);
247
+
248
+ // 2. Build version specs (overridden toolkits get specific version, rest get 'latest')
249
+ const versionSpecs = buildToolkitVersionSpecs(allSlugs, versionOverrides);
250
+
251
+ // Build the version map (only includes non-'latest' versions)
252
+ const versionMap: ToolkitVersionOverrides = new Map();
253
+ for (const spec of versionSpecs) {
254
+ if (spec.toolkitVersion !== 'latest') {
255
+ versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
256
+ }
257
+ }
258
+
259
+ // 3. Fetch trigger types and tools in parallel
260
+ const [allTriggerTypes, allTypeableTools] = yield* Effect.all(
261
+ [
262
+ Effect.logDebug('Fetching all trigger types...').pipe(
263
+ Effect.flatMap(() => client.getTriggerTypes())
264
+ ),
265
+ Match.value(typeTools).pipe(
266
+ Match.when(true, withTypes =>
267
+ Effect.logDebug('Fetching all tools with schemas (with version overrides)...').pipe(
268
+ Effect.flatMap(() => client.getToolsByVersionSpecs(versionSpecs)),
269
+ Effect.map(tools => ({ withTypes, tools }))
270
+ )
271
+ ),
272
+ Match.when(false, withTypes =>
273
+ // When not using --type-tools, version overrides don't affect the output
274
+ Effect.logDebug('Fetching all tool names...').pipe(
275
+ Effect.flatMap(() => client.getToolsAsEnums()),
276
+ Effect.map(tools => ({ withTypes, tools }))
277
+ )
278
+ ),
279
+ Match.exhaustive
280
+ ),
281
+ ],
282
+ { concurrency: 'unbounded' }
283
+ );
284
+
285
+ yield* Console.log(`Found ${allToolkits.length} toolkit(s)`);
286
+
287
+ return {
288
+ toolkits: allToolkits,
289
+ triggerTypes: allTriggerTypes,
290
+ typeableTools: allTypeableTools,
291
+ versionMap,
292
+ };
293
+ });
294
+}
295
+
296
+/**
297
+ * Fetches all toolkit data when no --toolkits filter is provided.
298
+ * Delegates to fast path or override-aware path based on version overrides.
299
+ */
300
+function fetchAllData(
301
+ client: ComposioToolkitsRepository,
302
+ typeTools: boolean,
303
+ versionOverrides: ToolkitVersionOverrides
304
+): Effect.Effect<FetchResult, Error, never> {
305
+ return Effect.gen(function* () {
306
+ yield* Console.log('Fetching all toolkits, tools, and triggers from Composio API...');
307
+
308
+ if (versionOverrides.size === 0) {
309
+ return yield* fetchAllDataFastPath(client, typeTools);
310
+ }
311
+
312
+ return yield* fetchAllDataWithOverrides(client, typeTools, versionOverrides);
313
+ });
314
+}
315
+
316
/**
317
* Validates that the output directory is not inside node_modules
318
*/
@@ -270,18 +374,29 @@ export function generateTypescriptTypeStubs({
374
yield* Effect.log(`Writing type stubs to ${outputDir}...`);
375
yield* fs.makeDirectory(outputDir, { recursive: true });
376
377
+ // Read toolkit version overrides from environment variables
378
+ const versionOverrides = yield* getToolkitVersionOverrides;
379
+
380
+ // Log detected overrides for debugging
381
+ if (versionOverrides.size > 0) {
382
+ yield* Console.log('Detected toolkit version overrides:');
383
+ for (const [toolkit, version] of versionOverrides) {
384
+ yield* Console.log(` - ${toolkit}: ${version}`);
385
+ }
386
+ }
387
+
388
// Normalize toolkit slugs if specified (lowercase for API filtering)
389
const toolkitSlugsFilter = Array.isNonEmptyArray(toolkitsOpt)
390
? toolkitsOpt.map(s => s.toLowerCase())
391
: null;
392
393
// Fetch data using two distinct strategies based on whether --toolkits filter is provided
279
- const { toolkits, triggerTypes, typeableTools } = yield* toolkitSlugsFilter !== null
280
- ? fetchFilteredData(client, toolkitSlugsFilter, typeTools)
281
- : fetchAllData(client, typeTools);
394
+ const { toolkits, triggerTypes, typeableTools, versionMap } = yield* toolkitSlugsFilter !== null
395
+ ? fetchFilteredData(client, toolkitSlugsFilter, typeTools, versionOverrides)
396
+ : fetchAllData(client, typeTools, versionOverrides);
397
398
yield* Console.log('Writing TypeScript type stubs to disk...');
284
- const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes });
399
+ const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes, versionMap });
400
401
// Generate TypeScript sources
402
const sources = yield* generateTypeScriptSources({
ts/packages/cli/src/effects/toolkit-version-overrides.ts
new
+112
@@ -0,0 +1,112 @@
1
+import { Config, ConfigError, Effect, HashMap, Option, pipe, String } from 'effect';
2
+import { BaseConfigProviderLive } from 'src/services/config';
3
+
4
+/**
5
+ * Represents a toolkit with its version specification.
6
+ * The `toolkitSlug` is guaranteed to be lowercase at the type level.
7
+ */
8
+export interface ToolkitVersionSpec {
9
+ readonly toolkitSlug: Lowercase<string>;
10
+ readonly toolkitVersion: string;
11
+}
12
+
13
+/**
14
+ * Config that reads COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>=<version> env vars.
15
+ * Uses Effect's Config.hashMap with Config.nested to read all env vars
16
+ * `COMPOSIO_TOOLKIT_VERSION_${TOOLKIT}` with a wildcard suffix.
17
+ *
18
+ * @example
19
+ * // Given: COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
20
+ * // Returns: HashMap { "GMAIL" => "20250901_00" }
21
+ */
22
+export const TOOLKIT_VERSION_OVERRIDES_CONFIG = pipe(
23
+ Config.hashMap(Config.string()),
24
+ Config.nested('VERSION'),
25
+ Config.nested('TOOLKIT'),
26
+ Config.nested('COMPOSIO'),
27
+ Config.option // Optional, so missing env vars don't fail the config
28
+);
29
+
30
+/**
31
+ * Map type with lowercase toolkit slugs as keys.
32
+ */
33
+export type ToolkitVersionOverrides = Map<Lowercase<string>, string>;
34
+
35
+/**
36
+ * Reads toolkit version overrides from environment variables.
37
+ *
38
+ * Uses Effect's Config system to read env vars matching the pattern
39
+ * COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>=<version>.
40
+ *
41
+ * This function uses `BaseConfigProviderLive` directly (bypassing `extendConfigProvider`)
42
+ * to correctly parse the nested path structure of the environment variable names.
43
+ *
44
+ * @returns Effect that yields a Map<Lowercase<string>, string> where keys are lowercase toolkit slugs
45
+ * and values are version strings
46
+ *
47
+ * @example
48
+ * // Given: COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00
49
+ * // Returns: Map { "gmail" => "20250901_00" }
50
+ */
51
+export const getToolkitVersionOverrides: Effect.Effect<
52
+ ToolkitVersionOverrides,
53
+ ConfigError.ConfigError
54
+> = Effect.gen(function* () {
55
+ const maybeOverrides = yield* TOOLKIT_VERSION_OVERRIDES_CONFIG;
56
+
57
+ return Option.match(maybeOverrides, {
58
+ onNone: () => new Map<Lowercase<string>, string>(),
59
+ onSome: hashMap => {
60
+ const result = new Map<Lowercase<string>, string>();
61
+ for (const [key, value] of HashMap.toEntries(hashMap)) {
62
+ // Normalize toolkit name to lowercase and skip 'latest' values
63
+ if (value && value !== 'latest') {
64
+ result.set(String.toLowerCase(key), value);
65
+ }
66
+ }
67
+ return result;
68
+ },
69
+ });
70
+}).pipe(Effect.withConfigProvider(BaseConfigProviderLive));
71
+
72
+/**
73
+ * Builds an array of ToolkitVersionSpec from toolkit slugs and version overrides.
74
+ *
75
+ * @example
76
+ * // Given slugs: ['gmail', 'slack', 'github']
77
+ * // Given overrides: Map { "gmail" => "20250901_00" }
78
+ * // Returns: [
79
+ * // { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
80
+ * // { toolkitSlug: 'slack', toolkitVersion: 'latest' },
81
+ * // { toolkitSlug: 'github', toolkitVersion: 'latest' }
82
+ * // ]
83
+ */
84
+export const buildToolkitVersionSpecs = (
85
+ toolkitSlugs: ReadonlyArray<string>,
86
+ overrides: ToolkitVersionOverrides
87
+): ReadonlyArray<ToolkitVersionSpec> =>
88
+ toolkitSlugs.map(slug => {
89
+ const normalizedSlug = String.toLowerCase(slug);
90
+ return {
91
+ toolkitSlug: normalizedSlug,
92
+ toolkitVersion: overrides.get(normalizedSlug) ?? 'latest',
93
+ };
94
+ });
95
+
96
+/**
97
+ * Groups ToolkitVersionSpecs by version for efficient API batching.
98
+ *
99
+ * @example
100
+ * // Given specs with mixed versions
101
+ * // Returns: Map { "20250901_00" => ["gmail"], "latest" => ["slack", "github"] }
102
+ */
103
+export const groupByVersion = (
104
+ specs: ReadonlyArray<ToolkitVersionSpec>
105
+): Map<string, Lowercase<string>[]> => {
106
+ const grouped = new Map<string, Lowercase<string>[]>();
107
+ for (const spec of specs) {
108
+ const existing = grouped.get(spec.toolkitVersion) ?? [];
109
+ grouped.set(spec.toolkitVersion, [...existing, spec.toolkitSlug]);
110
+ }
111
+ return grouped;
112
+};
ts/packages/cli/src/generation/create-toolkit-index.ts
+12
@@ -3,6 +3,7 @@ import type { Simplify } from 'effect/Types';
3
import { Toolkit, Toolkits, ToolkitName } from 'src/models/toolkits';
4
import { ToolsAsEnums, Tools, ToolAsEnum, Tool } from 'src/models/tools';
5
import { TriggerType, TriggerTypes } from 'src/models/trigger-types';
6
+import type { ToolkitVersionOverrides } from 'src/effects/toolkit-version-overrides';
7
8
const startsWith =
9
<const P extends string>(prefix: P) =>
@@ -13,10 +14,14 @@ interface CreateToolkitIndexInput {
14
toolkits: Toolkits; // e.g., [ { slug: 'gmail', ... }]
15
typeableTools: { withTypes: false; tools: ToolsAsEnums } | { withTypes: true; tools: Tools }; // e.g., [ 'GMAIL_SEND_EMAIL' ] | [ { slug: 'GMAIL_SEND_EMAIL', ... } ]
16
triggerTypes: TriggerTypes; // e.g., [ { slug: 'GMAIL_NEW_EMAIL', ... } ]
17
+ /** Map of lowercase toolkit slug to version (only includes non-'latest' versions) */
18
+ versionMap?: ToolkitVersionOverrides;
19
}
20
21
export type ToolkitIndexData = Simplify<{
22
slug: string;
23
+ /** Version override for this toolkit (only present if not 'latest') */
24
+ version?: string;
25
typeableTools:
26
| { withTypes: false; value: Record<`${ToolkitName}_${string}`, ToolAsEnum> }
27
| { withTypes: true; value: Record<`${ToolkitName}_${string}`, Tool> };
@@ -31,6 +36,8 @@ export type ToolkitIndex = Record<ToolkitName, ToolkitIndexData>;
36
* which is found by looking at the prefix of the tool or trigger type.
37
*/
38
export function createToolkitIndex(input: CreateToolkitIndexInput): Simplify<ToolkitIndex> {
39
+ const { versionMap } = input;
40
+
41
return pipe(
42
input,
43
groupByToolkits,
@@ -40,6 +47,9 @@ export function createToolkitIndex(input: CreateToolkitIndexInput): Simplify<Too
47
48
const { slug } = value.toolkit;
49
50
+ // Look up version override for this toolkit (lowercase key lookup)
51
+ const version = versionMap?.get(String.toLowerCase(slug));
52
+
53
const typeableTools = Match.value(value.typeableTools).pipe(
54
Match.when({ withTypes: true }, ({ withTypes, tools }) => {
55
return {
@@ -64,6 +74,8 @@ export function createToolkitIndex(input: CreateToolkitIndexInput): Simplify<Too
74
key,
75
{
76
slug,
77
+ // Only include version if it's not 'latest' (i.e., was overridden)
78
+ ...(version ? { version } : {}),
79
typeableTools,
80
triggerTypes: Record.fromEntries(triggerTypes),
81
},
ts/packages/cli/src/generation/python/generate-toolkit-sources.ts
+4
-1
@@ -154,8 +154,11 @@ function generatePythonToolkitSource(banner: string) {
154
return `${spacePad}pass`;
155
};
156
157
- const filesource = `# ${banner}.
157
+ // Build version comment if version override was used
158
+ const versionComment = toolkit.version ? `# @toolkit-version: ${toolkit.version}\n` : '';
159
160
+ const filesource = `# ${banner}.
161
+${versionComment}
162
class ${toolkitName}:
163
"""Map of Composio's ${toolkitName} toolkit."""
164
ts/packages/cli/src/generation/typescript/generate-toolkit-sources.ts
+84
-55
@@ -34,6 +34,66 @@ import {
34
GenerateTypeFromJsonSchemaError,
35
} from './generate-type-from-json-schema';
36
37
+function addToolkitToolInputsTypeMap(
38
+ file: ReturnType<typeof ts.file>,
39
+ toolkitName: ToolkitName,
40
+ typeableToolsValue: Record<string, unknown>
41
+) {
42
+ const toolInputTypeEntries = pipe(
43
+ typeableToolsValue,
44
+ Record.map((_, toolName) =>
45
+ ts.property(toolName, ts.namedType(`${toolkitName}_${toolName}_INPUT`))
46
+ ),
47
+ Record.toEntries,
48
+ Arr.map(([_, value]) => value)
49
+ );
50
+
51
+ const doc = ts.docComment(
52
+ `Type map of all available tool input types for toolkit "${toolkitName}".`
53
+ );
54
+
55
+ file.add(
56
+ ts
57
+ .moduleExport(
58
+ ts.typeDeclaration(
59
+ `${toolkitName}_TOOL_INPUTS`,
60
+ ts.objectType().addMultiple(toolInputTypeEntries)
61
+ )
62
+ )
63
+ .setDocComment(doc)
64
+ );
65
+}
66
+
67
+function addToolkitToolOutputsTypeMap(
68
+ file: ReturnType<typeof ts.file>,
69
+ toolkitName: ToolkitName,
70
+ typeableToolsValue: Record<string, unknown>
71
+) {
72
+ const toolOutputTypeEntries = pipe(
73
+ typeableToolsValue,
74
+ Record.map((_, toolName) =>
75
+ ts.property(toolName, ts.namedType(`${toolkitName}_${toolName}_OUTPUT`))
76
+ ),
77
+ Record.toEntries,
78
+ Arr.map(([_, value]) => value)
79
+ );
80
+
81
+ const doc = ts.docComment(
82
+ `Type map of all available tool input types for toolkit "${toolkitName}".`
83
+ );
84
+
85
+ file.add(
86
+ ts
87
+ .moduleExport(
88
+ ts.typeDeclaration(
89
+ `${toolkitName}_TOOL_OUTPUTS`,
90
+ ts.objectType().addMultiple(toolOutputTypeEntries)
91
+ )
92
+ )
93
+ .setDocComment(doc)
94
+ );
95
+}
96
+
97
function jsValueToTsValue(value: unknown): ts.ValueBuilder {
98
if (value === null) {
99
return ts.namedValue('null');
@@ -78,7 +138,7 @@ function jsValueToTsValue(value: unknown): ts.ValueBuilder {
138
/**
139
* Generates a TypeScript object literal for a trigger type
140
*/
81
-function generateTriggerTypeObjectValue(triggerType: TriggerType): ts.ValueBuilder {
141
+function _generateTriggerTypeObjectValue(triggerType: TriggerType): ts.ValueBuilder {
142
return ts
143
.objectValue()
144
.add(ts.propertyValue('slug', ts.stringLiteral(triggerType.slug).asValue()))
@@ -116,12 +176,17 @@ export function generateTypeScriptToolkitSources(banner: string) {
176
function generateTypeScriptToolkitSource(_banner: string) {
177
return (
178
toolkitName: ToolkitName,
119
- { slug, typeableTools, triggerTypes }: ToolkitIndexData
179
+ { slug, version, typeableTools, triggerTypes }: ToolkitIndexData
180
): Effect.Effect<SourceFile, GenerateTypeFromJsonSchemaError, never> => {
181
return Effect.gen(function* () {
182
const filename = `${slug}.ts`;
183
const file = ts.file();
184
185
+ // Add toolkit version comment if a version override was used
186
+ if (version) {
187
+ file.add(ts.docSectionComment(`/* @toolkit-version: ${version} */`));
188
+ }
189
+
190
// add `import { type TriggerEvent } from "@composio/core"`, if there are trigger types
191
if (Object.keys(triggerTypes).length > 0) {
192
file.addImport(
@@ -156,69 +221,29 @@ function generateTypeScriptToolkitSource(_banner: string) {
221
file.add(
222
ts
223
.typeDeclaration(tool.slug, toolInputType)
159
- .setDocComment(ts.docComment(`Type of ${toolkitName}'s ${tool.slug} tool input.`))
224
+ .setDocComment(
225
+ ts.docComment(
226
+ `Type of ${toolkitName}'s ${tool.slug} tool input.${version ? `\n@toolkit-version: ${version}` : ''}`
227
+ )
228
+ )
229
);
230
231
file.add(
232
ts
233
.typeDeclaration(tool.slug, toolOutputType)
165
- .setDocComment(ts.docComment(`Type of ${toolkitName}'s ${tool.slug} tool output.`))
166
- );
167
- }
168
-
169
- // write the map of input tool types
170
- {
171
- const toolInputTypeEntries = pipe(
172
- typeableTools.value,
173
- Record.map((_, toolName) =>
174
- ts.property(toolName, ts.namedType(`${toolkitName}_${toolName}_INPUT`))
175
- ),
176
- Record.toEntries,
177
- Arr.map(([_, value]) => value)
178
- );
179
-
180
- const doc = ts.docComment(
181
- `Type map of all available tool input types for toolkit "${toolkitName}".`
182
- );
183
-
184
- file.add(
185
- ts
186
- .moduleExport(
187
- ts.typeDeclaration(
188
- `${toolkitName}_TOOL_INPUTS`,
189
- ts.objectType().addMultiple(toolInputTypeEntries)
234
+ .setDocComment(
235
+ ts.docComment(
236
+ `Type of ${toolkitName}'s ${tool.slug} tool output.${version ? `\n@toolkit-version: ${version}` : ''}`
237
)
238
)
192
- .setDocComment(doc)
239
);
240
}
241
196
- // write the map of output tool types
197
- {
198
- const toolOutputTypeEntries = pipe(
199
- typeableTools.value,
200
- Record.map((_, toolName) =>
201
- ts.property(toolName, ts.namedType(`${toolkitName}_${toolName}_OUTPUT`))
202
- ),
203
- Record.toEntries,
204
- Arr.map(([_, value]) => value)
205
- );
206
-
207
- const doc = ts.docComment(
208
- `Type map of all available tool input types for toolkit "${toolkitName}".`
209
- );
242
+ // write the map of input tool types
243
+ addToolkitToolInputsTypeMap(file, toolkitName, typeableTools.value);
244
211
- file.add(
212
- ts
213
- .moduleExport(
214
- ts.typeDeclaration(
215
- `${toolkitName}_TOOL_OUTPUTS`,
216
- ts.objectType().addMultiple(toolOutputTypeEntries)
217
- )
218
- )
219
- .setDocComment(doc)
220
- );
221
- }
245
+ // write the map of output tool types
246
+ addToolkitToolOutputsTypeMap(file, toolkitName, typeableTools.value);
247
}
248
249
file.add(
@@ -288,7 +313,11 @@ function generateTypeScriptToolkitSource(_banner: string) {
313
.constDeclaration(toolValueDeclaration.name as string)
314
.setValue(toolValueDeclaration.value)
315
)
291
- .setDocComment(ts.docComment(`Map of Composio's ${toolValueDeclaration.name} toolkit.`))
316
+ .setDocComment(
317
+ ts.docComment(
318
+ `Map of Composio's ${toolValueDeclaration.name} toolkit.${version ? `\n@toolkit-version: ${version}` : ''}`
319
+ )
320
+ )
321
);
322
323
// write the map of trigger payload types
ts/packages/cli/src/services/composio-clients-cached.ts
+9
@@ -5,6 +5,7 @@ import { BunFileSystem } from '@effect/platform-bun';
5
import { setupCacheDir } from 'src/effects/setup-cache-dir';
6
import { FORCE_CONFIG } from 'src/effects/force-config';
7
import { ComposioToolkitsRepository, InvalidToolkitsError } from './composio-clients';
8
+import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
9
import { NodeOs } from './node-os';
10
import { toolkitsFromJSON, toolkitsToJSON, type Toolkits } from 'src/models/toolkits';
11
import {
@@ -217,6 +218,14 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
218
);
219
},
220
221
+ // Version-specific tools bypass cache because:
222
+ // 1. Different versions = different cache keys needed
223
+ // 2. Version-specific data shouldn't pollute the main cache
224
+ // The cache is mainly useful for 'latest' during repeated dev iterations.
225
+ getToolsByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) => {
226
+ return underlyingRepository.getToolsByVersionSpecs(specs);
227
+ },
228
+
229
// These methods don't need caching as they operate on already fetched data
230
// or perform validation that should always be fresh
231
getMetrics: () => underlyingRepository.getMetrics(),
ts/packages/cli/src/services/composio-clients.ts
+54
-4
@@ -15,6 +15,7 @@ import {
15
import { Composio as _RawComposioClient, APIPromise } from '@composio/client';
16
import { Toolkit, Toolkits } from 'src/models/toolkits';
17
import { ToolsAsEnums, Tools, Tool } from 'src/models/tools';
18
+import { groupByVersion, type ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
19
import { Session, RetrievedSession } from 'src/models/session';
20
import { TriggerType, TriggerTypes, TriggerTypesAsEnums } from 'src/models/trigger-types';
21
import { ComposioUserContext, ComposioUserContextLive } from './user-context';
@@ -510,22 +511,54 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
511
),
512
/**
513
* Retrieve a list of tools, automatically handling pagination.
513
- * @param toolkitSlugs - Optional array of toolkit slugs to filter by
514
+ * It always fetches the latest version of tools for each toolkit.
515
+ * For more granular toolkit version control, use `listByVersionSpecs`.
516
+ * @param toolkitSlugs - Array of toolkit slugs to filter by
517
*/
515
- list: (toolkitSlugs?: ReadonlyArray<string>) =>
518
+ list: (toolkitSlugs: ReadonlyArray<string>) =>
519
withMetrics(
520
callClientWithPagination(
521
clientSingleton,
522
(client, cursor, limit) =>
523
client.tools.list({
524
cursor,
522
- toolkit_slug: toolkitSlugs?.length ? toolkitSlugs.join(',') : undefined,
525
+ toolkit_slug: toolkitSlugs.length > 0 ? toolkitSlugs.join(',') : undefined,
526
toolkit_versions: 'latest',
527
limit,
528
}),
529
ToolsResponse
530
)
531
),
532
+ /**
533
+ * Retrieve tools for multiple toolkits, grouped by version.
534
+ * Makes separate API calls for each version group, then merges results.
535
+ * @param specs - Array of toolkit version specifications
536
+ */
537
+ listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
538
+ Effect.gen(function* () {
539
+ const grouped = groupByVersion(specs);
540
+ const allTools: Tool[] = [];
541
+
542
+ for (const [version, slugs] of grouped) {
543
+ // Fetch all toolkits with same version in one call
544
+ const response = yield* withMetrics(
545
+ callClientWithPagination(
546
+ clientSingleton,
547
+ (client, cursor, limit) =>
548
+ client.tools.list({
549
+ cursor,
550
+ toolkit_slug: slugs.join(','),
551
+ toolkit_versions: version,
552
+ limit,
553
+ }),
554
+ ToolsResponse
555
+ )
556
+ );
557
+ allTools.push(...response.items);
558
+ }
559
+
560
+ return { items: allTools };
561
+ }),
562
},
563
triggersTypes: {
564
/**
@@ -655,7 +688,24 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
688
* @param toolkitSlugs - Optional array of toolkit slugs to filter by
689
*/
690
getTools: (toolkitSlugs?: ReadonlyArray<string>) =>
658
- client.tools.list(toolkitSlugs).pipe(
691
+ client.tools.list(toolkitSlugs ?? []).pipe(
692
+ Effect.map(response => response.items),
693
+ Effect.flatMap(
694
+ Effect.fn(function* (tools) {
695
+ // Sort apps by slug.
696
+ // TODO: make sure this happens on the server-side.
697
+ const orderBySlug = Order.mapInput(Order.string, (app: Tool) => app.slug);
698
+ return Array.sort(tools, orderBySlug) as ReadonlyArray<Tool>;
699
+ })
700
+ )
701
+ ),
702
+ /**
703
+ * Fetches tools with per-toolkit version support.
704
+ * Groups toolkits by version and makes separate API calls for each group.
705
+ * @param specs - Array of { toolkitSlug, toolkitVersion } specifications
706
+ */
707
+ getToolsByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
708
+ client.tools.listByVersionSpecs(specs).pipe(
709
Effect.map(response => response.items),
710
Effect.flatMap(
711
Effect.fn(function* (tools) {
ts/packages/cli/test/__utils__/services/test-layer.ts
+10
@@ -28,6 +28,7 @@ import { EnvLangDetector } from 'src/services/env-lang-detector';
28
import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
29
import type { Tools } from 'src/models/tools';
30
import type { TriggerTypes, TriggerTypesAsEnums } from 'src/models/trigger-types';
31
+import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
32
import { ComposioUserContextLive } from 'src/services/user-context';
33
import { UpgradeBinary } from 'src/services/upgrade-binary';
34
import { NodeOs } from 'src/services/node-os';
@@ -150,6 +151,15 @@ export const TestLayer = (input?: TestLiveInput) =>
151
const normalizedSlugs = new Set(toolkitSlugs.map(slug => String.toLowerCase(slug)));
152
return toolkits.filter(toolkit => normalizedSlugs.has(String.toLowerCase(toolkit.slug)));
153
},
154
+ getToolsByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) => {
155
+ // Filter tools based on toolkit slugs from specs
156
+ const toolkitSlugs = specs.map(s => s.toolkitSlug.toUpperCase());
157
+ const prefixes = toolkitSlugs.map(s => `${s}_`);
158
+ const tools = toolkitsData.tools.filter(t =>
159
+ prefixes.some(p => t.slug.toUpperCase().startsWith(p))
160
+ );
161
+ return Effect.succeed(tools);
162
+ },
163
})
164
);
165
const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
ts/packages/cli/test/src/commands/py/py.generate.cmd.test.ts
+128
@@ -390,5 +390,133 @@ describe('CLI: composio py generate', () => {
390
})
391
);
392
});
393
+
394
+ describe('[Given] COMPOSIO_TOOLKIT_VERSION_* env vars', () => {
395
+ it.scoped(
396
+ '[Given] COMPOSIO_TOOLKIT_VERSION_GMAIL env var [Then] it adds version comment to generated file',
397
+ () =>
398
+ Effect.gen(function* () {
399
+ const { vi } = yield* Effect.promise(() => import('vitest'));
400
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
401
+
402
+ const process = yield* NodeProcess;
403
+ const cwd = process.cwd;
404
+ const fs = yield* FileSystem.FileSystem;
405
+ const outputDir = path.join(cwd, '.generated', 'composio-py-version');
406
+
407
+ const args = ['py', 'generate', '--output-dir', outputDir];
408
+ yield* cli(args);
409
+
410
+ // Check that gmail.py contains the version comment
411
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.py'));
412
+ expect(gmailSourceCode).toContain('# @toolkit-version: 20250901_00');
413
+
414
+ // Check that slack.py does NOT contain a version comment
415
+ const slackSourceCode = yield* fs.readFileString(path.join(outputDir, 'slack.py'));
416
+ expect(slackSourceCode).not.toContain('@toolkit-version');
417
+
418
+ vi.unstubAllEnvs();
419
+ })
420
+ );
421
+
422
+ it.scoped(
423
+ '[Given] multiple COMPOSIO_TOOLKIT_VERSION_* env vars [Then] it adds version comments to both generated files',
424
+ () =>
425
+ Effect.gen(function* () {
426
+ const { vi } = yield* Effect.promise(() => import('vitest'));
427
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
428
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', '20250815_00');
429
+
430
+ const process = yield* NodeProcess;
431
+ const cwd = process.cwd;
432
+ const fs = yield* FileSystem.FileSystem;
433
+ const outputDir = path.join(cwd, '.generated', 'composio-py-multi-version');
434
+
435
+ const args = ['py', 'generate', '--output-dir', outputDir];
436
+ yield* cli(args);
437
+
438
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.py'));
439
+ expect(gmailSourceCode).toContain('# @toolkit-version: 20250901_00');
440
+
441
+ const slackSourceCode = yield* fs.readFileString(path.join(outputDir, 'slack.py'));
442
+ expect(slackSourceCode).toContain('# @toolkit-version: 20250815_00');
443
+
444
+ vi.unstubAllEnvs();
445
+ })
446
+ );
447
+
448
+ it.scoped(
449
+ '[Given] COMPOSIO_TOOLKIT_VERSION_GMAIL=latest [Then] it treats same as no override (no version comment)',
450
+ () =>
451
+ Effect.gen(function* () {
452
+ const { vi } = yield* Effect.promise(() => import('vitest'));
453
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', 'latest');
454
+
455
+ const process = yield* NodeProcess;
456
+ const cwd = process.cwd;
457
+ const fs = yield* FileSystem.FileSystem;
458
+ const outputDir = path.join(cwd, '.generated', 'composio-py-latest');
459
+
460
+ const args = ['py', 'generate', '--output-dir', outputDir];
461
+ yield* cli(args);
462
+
463
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.py'));
464
+ expect(gmailSourceCode).not.toContain('@toolkit-version');
465
+
466
+ vi.unstubAllEnvs();
467
+ })
468
+ );
469
+
470
+ it.scoped(
471
+ '[Given] --toolkits gmail and COMPOSIO_TOOLKIT_VERSION_SLACK env var [Then] it ignores env var for non-requested toolkit',
472
+ () =>
473
+ Effect.gen(function* () {
474
+ const { vi } = yield* Effect.promise(() => import('vitest'));
475
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', '20250815_00');
476
+
477
+ const process = yield* NodeProcess;
478
+ const cwd = process.cwd;
479
+ const fs = yield* FileSystem.FileSystem;
480
+ const outputDir = path.join(cwd, '.generated', 'composio-py-filtered-env');
481
+
482
+ const args = ['py', 'generate', '--toolkits', 'gmail', '--output-dir', outputDir];
483
+ yield* cli(args);
484
+
485
+ // Only gmail.py should exist
486
+ const files = yield* fs.readDirectory(outputDir);
487
+ const fileNames = files.map(file => path.basename(file));
488
+ expect(fileNames).toContain('gmail.py');
489
+ expect(fileNames).not.toContain('slack.py');
490
+
491
+ // gmail.py should NOT have version comment
492
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.py'));
493
+ expect(gmailSourceCode).not.toContain('@toolkit-version');
494
+
495
+ vi.unstubAllEnvs();
496
+ })
497
+ );
498
+
499
+ it.scoped(
500
+ '[Given] --toolkits gmail and COMPOSIO_TOOLKIT_VERSION_GMAIL env var [Then] it applies version override to filtered toolkit',
501
+ () =>
502
+ Effect.gen(function* () {
503
+ const { vi } = yield* Effect.promise(() => import('vitest'));
504
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
505
+
506
+ const process = yield* NodeProcess;
507
+ const cwd = process.cwd;
508
+ const fs = yield* FileSystem.FileSystem;
509
+ const outputDir = path.join(cwd, '.generated', 'composio-py-filtered-version');
510
+
511
+ const args = ['py', 'generate', '--toolkits', 'gmail', '--output-dir', outputDir];
512
+ yield* cli(args);
513
+
514
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.py'));
515
+ expect(gmailSourceCode).toContain('# @toolkit-version: 20250901_00');
516
+
517
+ vi.unstubAllEnvs();
518
+ })
519
+ );
520
+ });
521
});
522
});
ts/packages/cli/test/src/commands/ts/ts.generate.cmd.test.ts
+188
@@ -1057,6 +1057,194 @@ describe('CLI: composio ts generate', () => {
1057
});
1058
});
1059
1060
+ describe('[Given] COMPOSIO_TOOLKIT_VERSION_* env vars', () => {
1061
+ layer(
1062
+ TestLive({
1063
+ fixture: 'typescript-project-with-composio-core',
1064
+ toolkitsData: appClientData,
1065
+ })
1066
+ )(it => {
1067
+ it.scoped(
1068
+ '[Given] --type-tools and COMPOSIO_TOOLKIT_VERSION_GMAIL env var [Then] it adds version comment to generated file',
1069
+ () =>
1070
+ Effect.gen(function* () {
1071
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1072
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
1073
+
1074
+ const process = yield* NodeProcess;
1075
+ const cwd = process.cwd;
1076
+ const fs = yield* FileSystem.FileSystem;
1077
+ const outputDir = path.join(cwd, 'generated-version-override');
1078
+
1079
+ const args = ['ts', 'generate', '--type-tools', '--output-dir', outputDir];
1080
+ yield* cli(args);
1081
+
1082
+ // Check that gmail.ts contains the version comment
1083
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1084
+ expect(gmailSourceCode).toContain('@toolkit-version: 20250901_00');
1085
+
1086
+ // Check that slack.ts does NOT contain a version comment (no override for it)
1087
+ const slackSourceCode = yield* fs.readFileString(path.join(outputDir, 'slack.ts'));
1088
+ expect(slackSourceCode).not.toContain('@toolkit-version');
1089
+
1090
+ vi.unstubAllEnvs();
1091
+ })
1092
+ );
1093
+
1094
+ it.scoped(
1095
+ '[Given] --type-tools and multiple COMPOSIO_TOOLKIT_VERSION_* env vars [Then] it adds version comments to both generated files',
1096
+ () =>
1097
+ Effect.gen(function* () {
1098
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1099
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
1100
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', '20250815_00');
1101
+
1102
+ const process = yield* NodeProcess;
1103
+ const cwd = process.cwd;
1104
+ const fs = yield* FileSystem.FileSystem;
1105
+ const outputDir = path.join(cwd, 'generated-multi-version-override');
1106
+
1107
+ const args = ['ts', 'generate', '--type-tools', '--output-dir', outputDir];
1108
+ yield* cli(args);
1109
+
1110
+ // Check that gmail.ts contains the version comment
1111
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1112
+ expect(gmailSourceCode).toContain('@toolkit-version: 20250901_00');
1113
+
1114
+ // Check that slack.ts contains the version comment
1115
+ const slackSourceCode = yield* fs.readFileString(path.join(outputDir, 'slack.ts'));
1116
+ expect(slackSourceCode).toContain('@toolkit-version: 20250815_00');
1117
+
1118
+ vi.unstubAllEnvs();
1119
+ })
1120
+ );
1121
+
1122
+ it.scoped(
1123
+ '[Given] --type-tools and COMPOSIO_TOOLKIT_VERSION_GMAIL=latest [Then] it treats same as no override (no version comment)',
1124
+ () =>
1125
+ Effect.gen(function* () {
1126
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1127
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', 'latest');
1128
+
1129
+ const process = yield* NodeProcess;
1130
+ const cwd = process.cwd;
1131
+ const fs = yield* FileSystem.FileSystem;
1132
+ const outputDir = path.join(cwd, 'generated-latest-version');
1133
+
1134
+ const args = ['ts', 'generate', '--type-tools', '--output-dir', outputDir];
1135
+ yield* cli(args);
1136
+
1137
+ // Check that gmail.ts does NOT contain a version comment
1138
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1139
+ expect(gmailSourceCode).not.toContain('@toolkit-version');
1140
+
1141
+ vi.unstubAllEnvs();
1142
+ })
1143
+ );
1144
+
1145
+ it.scoped(
1146
+ '[Given] --toolkits gmail and COMPOSIO_TOOLKIT_VERSION_SLACK env var [Then] it ignores env var for non-requested toolkit',
1147
+ () =>
1148
+ Effect.gen(function* () {
1149
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1150
+ // Set env var for SLACK, but only request GMAIL toolkit
1151
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', '20250815_00');
1152
+
1153
+ const process = yield* NodeProcess;
1154
+ const cwd = process.cwd;
1155
+ const fs = yield* FileSystem.FileSystem;
1156
+ const outputDir = path.join(cwd, 'generated-filtered-env-ignored');
1157
+
1158
+ const args = [
1159
+ 'ts',
1160
+ 'generate',
1161
+ '--type-tools',
1162
+ '--toolkits',
1163
+ 'gmail',
1164
+ '--output-dir',
1165
+ outputDir,
1166
+ ];
1167
+ yield* cli(args);
1168
+
1169
+ // Check generated files - only gmail.ts should exist
1170
+ const files = yield* fs.readDirectory(outputDir);
1171
+ const fileNames = files.map(file => path.basename(file));
1172
+ expect(fileNames).toContain('gmail.ts');
1173
+ expect(fileNames).toContain('index.ts');
1174
+ expect(fileNames).not.toContain('slack.ts');
1175
+
1176
+ // gmail.ts should NOT have version comment (no GMAIL override set)
1177
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1178
+ expect(gmailSourceCode).not.toContain('@toolkit-version');
1179
+
1180
+ vi.unstubAllEnvs();
1181
+ })
1182
+ );
1183
+
1184
+ it.scoped(
1185
+ '[Given] --toolkits gmail and COMPOSIO_TOOLKIT_VERSION_GMAIL env var [Then] it applies version override to filtered toolkit',
1186
+ () =>
1187
+ Effect.gen(function* () {
1188
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1189
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
1190
+
1191
+ const process = yield* NodeProcess;
1192
+ const cwd = process.cwd;
1193
+ const fs = yield* FileSystem.FileSystem;
1194
+ const outputDir = path.join(cwd, 'generated-filtered-with-version');
1195
+
1196
+ const args = [
1197
+ 'ts',
1198
+ 'generate',
1199
+ '--type-tools',
1200
+ '--toolkits',
1201
+ 'gmail',
1202
+ '--output-dir',
1203
+ outputDir,
1204
+ ];
1205
+ yield* cli(args);
1206
+
1207
+ // Check generated files - only gmail.ts should exist
1208
+ const files = yield* fs.readDirectory(outputDir);
1209
+ const fileNames = files.map(file => path.basename(file));
1210
+ expect(fileNames).toContain('gmail.ts');
1211
+ expect(fileNames).not.toContain('slack.ts');
1212
+
1213
+ // gmail.ts should have version comment
1214
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1215
+ expect(gmailSourceCode).toContain('@toolkit-version: 20250901_00');
1216
+
1217
+ vi.unstubAllEnvs();
1218
+ })
1219
+ );
1220
+
1221
+ it.scoped(
1222
+ '[Given] no --type-tools and COMPOSIO_TOOLKIT_VERSION_GMAIL env var [Then] it still adds version comment for documentation purposes',
1223
+ () =>
1224
+ Effect.gen(function* () {
1225
+ const { vi } = yield* Effect.promise(() => import('vitest'));
1226
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
1227
+
1228
+ const process = yield* NodeProcess;
1229
+ const cwd = process.cwd;
1230
+ const fs = yield* FileSystem.FileSystem;
1231
+ const outputDir = path.join(cwd, 'generated-no-type-tools');
1232
+
1233
+ // Note: no --type-tools flag
1234
+ const args = ['ts', 'generate', '--output-dir', outputDir];
1235
+ yield* cli(args);
1236
+
1237
+ // Version comment is still added for documentation purposes,
1238
+ // even though the version override only affects tool schema fetching with --type-tools
1239
+ const gmailSourceCode = yield* fs.readFileString(path.join(outputDir, 'gmail.ts'));
1240
+ expect(gmailSourceCode).toContain('@toolkit-version: 20250901_00');
1241
+
1242
+ vi.unstubAllEnvs();
1243
+ })
1244
+ );
1245
+ });
1246
+ });
1247
+
1248
describe('[Given] `@composio/core` not installed', () => {
1249
layer(
1250
TestLive({
ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts
new
+205
@@ -0,0 +1,205 @@
1
+import { describe, it, expect, vi, afterEach } from '@effect/vitest';
2
+import { Effect } from 'effect';
3
+import {
4
+ getToolkitVersionOverrides,
5
+ buildToolkitVersionSpecs,
6
+ groupByVersion,
7
+ type ToolkitVersionOverrides,
8
+ type ToolkitVersionSpec,
9
+} from 'src/effects/toolkit-version-overrides';
10
+
11
+describe('toolkit-version-overrides', () => {
12
+ afterEach(() => {
13
+ // Clean up env vars after each test
14
+ vi.unstubAllEnvs();
15
+ });
16
+
17
+ describe('getToolkitVersionOverrides', () => {
18
+ it.effect('should return empty map when no env vars set', () =>
19
+ Effect.gen(function* () {
20
+ const result = yield* getToolkitVersionOverrides;
21
+ expect(result.size).toBe(0);
22
+ })
23
+ );
24
+
25
+ it.effect('should parse single env var with COMPOSIO_ prefix', () =>
26
+ Effect.gen(function* () {
27
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
28
+ const result = yield* getToolkitVersionOverrides;
29
+ expect(result.get('gmail')).toBe('20250901_00');
30
+ expect(result.size).toBe(1);
31
+ })
32
+ );
33
+
34
+ it.effect('should parse multiple env vars', () =>
35
+ Effect.gen(function* () {
36
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
37
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', '20250815_00');
38
+ const result = yield* getToolkitVersionOverrides;
39
+ expect(result.get('gmail')).toBe('20250901_00');
40
+ expect(result.get('slack')).toBe('20250815_00');
41
+ expect(result.size).toBe(2);
42
+ })
43
+ );
44
+
45
+ it.effect('should lowercase toolkit name from env var', () =>
46
+ Effect.gen(function* () {
47
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
48
+ const result = yield* getToolkitVersionOverrides;
49
+ expect(result.has('gmail')).toBe(true);
50
+ // Cast to bypass type check - we're testing runtime behavior that uppercase keys are not stored
51
+ expect(result.has('GMAIL' as Lowercase<string>)).toBe(false);
52
+ })
53
+ );
54
+
55
+ it.effect('should ignore "latest" as explicit value', () =>
56
+ Effect.gen(function* () {
57
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', 'latest');
58
+ const result = yield* getToolkitVersionOverrides;
59
+ expect(result.size).toBe(0);
60
+ })
61
+ );
62
+
63
+ it.effect('should ignore empty string values', () =>
64
+ Effect.gen(function* () {
65
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '');
66
+ const result = yield* getToolkitVersionOverrides;
67
+ expect(result.size).toBe(0);
68
+ })
69
+ );
70
+
71
+ it.effect('should not read env vars without COMPOSIO_ prefix', () =>
72
+ Effect.gen(function* () {
73
+ vi.stubEnv('TOOLKIT_VERSION_GMAIL', '20250901_00');
74
+ const result = yield* getToolkitVersionOverrides;
75
+ expect(result.size).toBe(0);
76
+ })
77
+ );
78
+
79
+ it.effect('should handle mixed valid and invalid entries', () =>
80
+ Effect.gen(function* () {
81
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00');
82
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_SLACK', 'latest'); // Should be ignored
83
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GITHUB', ''); // Should be ignored
84
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_NOTION', '20250815_00');
85
+ const result = yield* getToolkitVersionOverrides;
86
+ expect(result.size).toBe(2);
87
+ expect(result.get('gmail')).toBe('20250901_00');
88
+ expect(result.get('notion')).toBe('20250815_00');
89
+ })
90
+ );
91
+ });
92
+
93
+ describe('buildToolkitVersionSpecs', () => {
94
+ it('should apply overrides to matching toolkits', () => {
95
+ const overrides: ToolkitVersionOverrides = new Map([['gmail', '20250901_00']]);
96
+ const specs = buildToolkitVersionSpecs(['gmail', 'slack'], overrides);
97
+
98
+ expect(specs).toEqual([
99
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
100
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
101
+ ]);
102
+ });
103
+
104
+ it('should handle case-insensitive matching', () => {
105
+ const overrides: ToolkitVersionOverrides = new Map([['gmail', '20250901_00']]);
106
+ const specs = buildToolkitVersionSpecs(['GMAIL', 'Slack'], overrides);
107
+
108
+ expect(specs).toEqual([
109
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
110
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
111
+ ]);
112
+ });
113
+
114
+ it('should return all latest when no overrides', () => {
115
+ const overrides: ToolkitVersionOverrides = new Map();
116
+ const specs = buildToolkitVersionSpecs(['gmail', 'slack', 'github'], overrides);
117
+
118
+ expect(specs).toEqual([
119
+ { toolkitSlug: 'gmail', toolkitVersion: 'latest' },
120
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
121
+ { toolkitSlug: 'github', toolkitVersion: 'latest' },
122
+ ]);
123
+ });
124
+
125
+ it('should handle multiple overrides', () => {
126
+ const overrides: ToolkitVersionOverrides = new Map([
127
+ ['gmail', '20250901_00'],
128
+ ['slack', '20250815_00'],
129
+ ]);
130
+ const specs = buildToolkitVersionSpecs(['gmail', 'slack', 'github'], overrides);
131
+
132
+ expect(specs).toEqual([
133
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
134
+ { toolkitSlug: 'slack', toolkitVersion: '20250815_00' },
135
+ { toolkitSlug: 'github', toolkitVersion: 'latest' },
136
+ ]);
137
+ });
138
+
139
+ it('should handle empty slug array', () => {
140
+ const overrides: ToolkitVersionOverrides = new Map([['gmail', '20250901_00']]);
141
+ const specs = buildToolkitVersionSpecs([], overrides);
142
+
143
+ expect(specs).toEqual([]);
144
+ });
145
+ });
146
+
147
+ describe('groupByVersion', () => {
148
+ it('should group toolkits by version', () => {
149
+ const specs: ToolkitVersionSpec[] = [
150
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
151
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
152
+ { toolkitSlug: 'github', toolkitVersion: '20250901_00' },
153
+ ];
154
+ const grouped = groupByVersion(specs);
155
+
156
+ expect(grouped.get('20250901_00')).toEqual(['gmail', 'github']);
157
+ expect(grouped.get('latest')).toEqual(['slack']);
158
+ expect(grouped.size).toBe(2);
159
+ });
160
+
161
+ it('should handle all same version', () => {
162
+ const specs: ToolkitVersionSpec[] = [
163
+ { toolkitSlug: 'gmail', toolkitVersion: 'latest' },
164
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
165
+ ];
166
+ const grouped = groupByVersion(specs);
167
+
168
+ expect(grouped.size).toBe(1);
169
+ expect(grouped.get('latest')).toEqual(['gmail', 'slack']);
170
+ });
171
+
172
+ it('should handle all different versions', () => {
173
+ const specs: ToolkitVersionSpec[] = [
174
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
175
+ { toolkitSlug: 'slack', toolkitVersion: '20250815_00' },
176
+ { toolkitSlug: 'github', toolkitVersion: '20250710_00' },
177
+ ];
178
+ const grouped = groupByVersion(specs);
179
+
180
+ expect(grouped.size).toBe(3);
181
+ expect(grouped.get('20250901_00')).toEqual(['gmail']);
182
+ expect(grouped.get('20250815_00')).toEqual(['slack']);
183
+ expect(grouped.get('20250710_00')).toEqual(['github']);
184
+ });
185
+
186
+ it('should handle empty specs array', () => {
187
+ const specs: ToolkitVersionSpec[] = [];
188
+ const grouped = groupByVersion(specs);
189
+
190
+ expect(grouped.size).toBe(0);
191
+ });
192
+
193
+ it('should preserve order within version groups', () => {
194
+ const specs: ToolkitVersionSpec[] = [
195
+ { toolkitSlug: 'gmail', toolkitVersion: 'latest' },
196
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
197
+ { toolkitSlug: 'github', toolkitVersion: 'latest' },
198
+ { toolkitSlug: 'notion', toolkitVersion: 'latest' },
199
+ ];
200
+ const grouped = groupByVersion(specs);
201
+
202
+ expect(grouped.get('latest')).toEqual(['gmail', 'slack', 'github', 'notion']);
203
+ });
204
+ });
205
+});
ts/packages/cli/test/src/generation/python/generate-toolkit-source.test.ts
+267
@@ -6,6 +6,7 @@ import { makeTestToolkits } from 'test/__utils__/models/toolkits';
6
import { assertPythonIsValid } from 'test/__utils__/python-compiler';
7
import { TRIGGER_TYPES_GMAIL } from 'test/__mocks__/trigger-types-gmail';
8
import { TOOLS_GMAIL } from 'test/__mocks__/tools-gmail';
9
+import { TOOLS_TYPES_GMAIL } from 'test/__mocks__/tools-types-gmail';
10
11
describe('generatePythonToolkitSources', () => {
12
it('[Given] empty toolkits, tools, triggerTypes [Then] it returns an empty array', () => {
@@ -254,4 +255,270 @@ describe('generatePythonToolkitSources', () => {
255
256
assertPythonIsValid({ files: Object.fromEntries(sources) });
257
});
258
+
259
+ describe('[Given] versionMap with toolkit version overrides', () => {
260
+ describe('without type tools', () => {
261
+ it('[Given] a toolkit with version override [Then] it includes version comment in generated file', () => {
262
+ const toolkits = makeTestToolkits([
263
+ {
264
+ name: 'Gmail',
265
+ slug: 'gmail',
266
+ },
267
+ ]);
268
+
269
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<Lowercase<string>, string>;
270
+
271
+ const index = createToolkitIndex({
272
+ toolkits,
273
+ typeableTools: { withTypes: false, tools: [] },
274
+ triggerTypes: [],
275
+ versionMap,
276
+ });
277
+
278
+ const sources = generatePythonToolkitSources(BANNER)(index);
279
+ expect(sources).toHaveLength(1);
280
+ expect(sources[0][0]).toBe('gmail.py');
281
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
282
+
283
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
284
+ });
285
+
286
+ it('[Given] multiple toolkits with different version overrides [Then] each file includes its version comment', () => {
287
+ const toolkits = makeTestToolkits([
288
+ {
289
+ name: 'Gmail',
290
+ slug: 'gmail',
291
+ },
292
+ {
293
+ name: 'Slack Helper',
294
+ slug: 'slack',
295
+ },
296
+ ]);
297
+
298
+ const versionMap = new Map([
299
+ ['gmail', '20250901_00'],
300
+ ['slack', '20250815_00'],
301
+ ]) as Map<Lowercase<string>, string>;
302
+
303
+ const index = createToolkitIndex({
304
+ toolkits,
305
+ typeableTools: { withTypes: false, tools: [] },
306
+ triggerTypes: [],
307
+ versionMap,
308
+ });
309
+
310
+ const sources = generatePythonToolkitSources(BANNER)(index);
311
+ expect(sources).toHaveLength(2);
312
+
313
+ // Gmail should have its version comment
314
+ expect(sources[0][0]).toBe('gmail.py');
315
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
316
+
317
+ // Slack should have its version comment
318
+ expect(sources[1][0]).toBe('slack.py');
319
+ expect(sources[1][1]).toContain('# @toolkit-version: 20250815_00');
320
+
321
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
322
+ });
323
+
324
+ it('[Given] only some toolkits with version override [Then] only those files include version comment', () => {
325
+ const toolkits = makeTestToolkits([
326
+ {
327
+ name: 'Gmail',
328
+ slug: 'gmail',
329
+ },
330
+ {
331
+ name: 'Slack Helper',
332
+ slug: 'slack',
333
+ },
334
+ ]);
335
+
336
+ // Only gmail has a version override
337
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<Lowercase<string>, string>;
338
+
339
+ const index = createToolkitIndex({
340
+ toolkits,
341
+ typeableTools: { withTypes: false, tools: [] },
342
+ triggerTypes: [],
343
+ versionMap,
344
+ });
345
+
346
+ const sources = generatePythonToolkitSources(BANNER)(index);
347
+ expect(sources).toHaveLength(2);
348
+
349
+ // Gmail should have version comment
350
+ expect(sources[0][0]).toBe('gmail.py');
351
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
352
+
353
+ // Slack should NOT have version comment
354
+ expect(sources[1][0]).toBe('slack.py');
355
+ expect(sources[1][1]).not.toContain('@toolkit-version');
356
+
357
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
358
+ });
359
+
360
+ it('[Given] empty versionMap [Then] no files include version comment', () => {
361
+ const toolkits = makeTestToolkits([
362
+ {
363
+ name: 'Gmail',
364
+ slug: 'gmail',
365
+ },
366
+ ]);
367
+
368
+ const versionMap = new Map() as Map<Lowercase<string>, string>;
369
+
370
+ const index = createToolkitIndex({
371
+ toolkits,
372
+ typeableTools: { withTypes: false, tools: [] },
373
+ triggerTypes: [],
374
+ versionMap,
375
+ });
376
+
377
+ const sources = generatePythonToolkitSources(BANNER)(index);
378
+ expect(sources).toHaveLength(1);
379
+ expect(sources[0][0]).toBe('gmail.py');
380
+ expect(sources[0][1]).not.toContain('@toolkit-version');
381
+
382
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
383
+ });
384
+ });
385
+
386
+ describe('with type tools', () => {
387
+ it('[Given] a toolkit with version override [Then] it includes version comment in generated file', () => {
388
+ const toolkits = makeTestToolkits([
389
+ {
390
+ name: 'Gmail',
391
+ slug: 'gmail',
392
+ },
393
+ ]);
394
+
395
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<Lowercase<string>, string>;
396
+
397
+ const index = createToolkitIndex({
398
+ toolkits,
399
+ typeableTools: {
400
+ withTypes: true,
401
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
402
+ },
403
+ triggerTypes: [],
404
+ versionMap,
405
+ });
406
+
407
+ const sources = generatePythonToolkitSources(BANNER)(index);
408
+ expect(sources).toHaveLength(1);
409
+ expect(sources[0][0]).toBe('gmail.py');
410
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
411
+
412
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
413
+ });
414
+
415
+ it('[Given] multiple toolkits with different version overrides [Then] each file includes its version comment', () => {
416
+ const toolkits = makeTestToolkits([
417
+ {
418
+ name: 'Gmail',
419
+ slug: 'gmail',
420
+ },
421
+ {
422
+ name: 'Slack Helper',
423
+ slug: 'slack',
424
+ },
425
+ ]);
426
+
427
+ const versionMap = new Map([
428
+ ['gmail', '20250901_00'],
429
+ ['slack', '20250815_00'],
430
+ ]) as Map<Lowercase<string>, string>;
431
+
432
+ const index = createToolkitIndex({
433
+ toolkits,
434
+ typeableTools: {
435
+ withTypes: true,
436
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
437
+ },
438
+ triggerTypes: [],
439
+ versionMap,
440
+ });
441
+
442
+ const sources = generatePythonToolkitSources(BANNER)(index);
443
+ expect(sources).toHaveLength(2);
444
+
445
+ // Gmail should have its version comment
446
+ expect(sources[0][0]).toBe('gmail.py');
447
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
448
+
449
+ // Slack should have its version comment
450
+ expect(sources[1][0]).toBe('slack.py');
451
+ expect(sources[1][1]).toContain('# @toolkit-version: 20250815_00');
452
+
453
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
454
+ });
455
+
456
+ it('[Given] only some toolkits with version override [Then] only those files include version comment', () => {
457
+ const toolkits = makeTestToolkits([
458
+ {
459
+ name: 'Gmail',
460
+ slug: 'gmail',
461
+ },
462
+ {
463
+ name: 'Slack Helper',
464
+ slug: 'slack',
465
+ },
466
+ ]);
467
+
468
+ // Only gmail has a version override
469
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<Lowercase<string>, string>;
470
+
471
+ const index = createToolkitIndex({
472
+ toolkits,
473
+ typeableTools: {
474
+ withTypes: true,
475
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
476
+ },
477
+ triggerTypes: [],
478
+ versionMap,
479
+ });
480
+
481
+ const sources = generatePythonToolkitSources(BANNER)(index);
482
+ expect(sources).toHaveLength(2);
483
+
484
+ // Gmail should have version comment
485
+ expect(sources[0][0]).toBe('gmail.py');
486
+ expect(sources[0][1]).toContain('# @toolkit-version: 20250901_00');
487
+
488
+ // Slack should NOT have version comment
489
+ expect(sources[1][0]).toBe('slack.py');
490
+ expect(sources[1][1]).not.toContain('@toolkit-version');
491
+
492
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
493
+ });
494
+
495
+ it('[Given] empty versionMap [Then] no files include version comment', () => {
496
+ const toolkits = makeTestToolkits([
497
+ {
498
+ name: 'Gmail',
499
+ slug: 'gmail',
500
+ },
501
+ ]);
502
+
503
+ const versionMap = new Map() as Map<Lowercase<string>, string>;
504
+
505
+ const index = createToolkitIndex({
506
+ toolkits,
507
+ typeableTools: {
508
+ withTypes: true,
509
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
510
+ },
511
+ triggerTypes: [],
512
+ versionMap,
513
+ });
514
+
515
+ const sources = generatePythonToolkitSources(BANNER)(index);
516
+ expect(sources).toHaveLength(1);
517
+ expect(sources[0][0]).toBe('gmail.py');
518
+ expect(sources[0][1]).not.toContain('@toolkit-version');
519
+
520
+ assertPythonIsValid({ files: Object.fromEntries(sources) });
521
+ });
522
+ });
523
+ });
524
});
ts/packages/cli/test/src/generation/typescript/__snapshots__/generate-toolkit-source.test.ts.snap
new
+237
@@ -0,0 +1,237 @@
1
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
2
+
3
+exports[`generateTypeScriptToolkitSources > with a single emitted file > with banner > [Given] versionMap with toolkit version overrides > with type tools > [Given] multiple toolkits with different version overrides [Then] each file includes its version comment 1`] = `
4
+"/* @toolkit-version: 20250901_00 */
5
+
6
+
7
+// --------------- //
8
+// Tool types //
9
+// --------------- //
10
+
11
+
12
+
13
+/**
14
+ * Type map of all available tool input types for toolkit "GMAIL".
15
+ */
16
+export type GMAIL_TOOL_INPUTS = {}
17
+
18
+/**
19
+ * Type map of all available tool input types for toolkit "GMAIL".
20
+ */
21
+export type GMAIL_TOOL_OUTPUTS = {}
22
+
23
+// ------------------- //
24
+// Trigger types //
25
+// ------------------- //
26
+
27
+
28
+
29
+/**
30
+ * Map of Composio's GMAIL toolkit.
31
+ * @toolkit-version: 20250901_00
32
+ */
33
+export const GMAIL = {
34
+ slug: "gmail",
35
+ tools: {},
36
+ triggerTypes: {},
37
+}
38
+
39
+/**
40
+ * Type map of all available trigger payloads for toolkit "GMAIL".
41
+ */
42
+export type GMAIL_TRIGGER_PAYLOADS = {}
43
+
44
+/**
45
+ * Type map of all available trigger events for toolkit "GMAIL".
46
+ */
47
+export type GMAIL_TRIGGER_EVENTS = {}
48
+"
49
+`;
50
+
51
+exports[`generateTypeScriptToolkitSources > with a single emitted file > with banner > [Given] versionMap with toolkit version overrides > with type tools > [Given] multiple toolkits with different version overrides [Then] each file includes its version comment 2`] = `
52
+"/* @toolkit-version: 20250815_00 */
53
+
54
+
55
+// --------------- //
56
+// Tool types //
57
+// --------------- //
58
+
59
+
60
+
61
+/**
62
+ * Type of GITHUB's GITHUB_ACCEPT_A_REPOSITORY_INVITATION tool input.
63
+ * @toolkit-version: 20250815_00
64
+ */
65
+type GITHUB_ACCEPT_A_REPOSITORY_INVITATION_INPUT = {
66
+ /**
67
+ * Invitation Id
68
+ * @description Unique identifier of the repository invitation. Obtain by listing pending invitations for the authenticated user.
69
+ * @example 12345
70
+ * @example 67890
71
+ */
72
+ invitation_id?: number;
73
+};
74
+
75
+/**
76
+ * Type of GITHUB's GITHUB_ACCEPT_A_REPOSITORY_INVITATION tool output.
77
+ * @toolkit-version: 20250815_00
78
+ */
79
+type GITHUB_ACCEPT_A_REPOSITORY_INVITATION_OUTPUT = {
80
+ /**
81
+ * Data
82
+ * @description GitHub API response. Usually empty for a successful acceptance (HTTP 204 No Content status).
83
+ */
84
+ data?: {
85
+ [key: string]: unknown;
86
+ };
87
+ /**
88
+ * Error
89
+ * @description Error if any occurred during the execution of the action
90
+ * @default null
91
+ */
92
+ error: string | null;
93
+ /**
94
+ * Successful
95
+ * @description Whether or not the action execution was successful or not
96
+ */
97
+ successful?: boolean;
98
+};
99
+
100
+/**
101
+ * Type map of all available tool input types for toolkit "GITHUB".
102
+ */
103
+export type GITHUB_TOOL_INPUTS = {
104
+ ACCEPT_A_REPOSITORY_INVITATION: GITHUB_ACCEPT_A_REPOSITORY_INVITATION_INPUT
105
+}
106
+
107
+/**
108
+ * Type map of all available tool input types for toolkit "GITHUB".
109
+ */
110
+export type GITHUB_TOOL_OUTPUTS = {
111
+ ACCEPT_A_REPOSITORY_INVITATION: GITHUB_ACCEPT_A_REPOSITORY_INVITATION_OUTPUT
112
+}
113
+
114
+// ------------------- //
115
+// Trigger types //
116
+// ------------------- //
117
+
118
+
119
+
120
+/**
121
+ * Map of Composio's GITHUB toolkit.
122
+ * @toolkit-version: 20250815_00
123
+ */
124
+export const GITHUB = {
125
+ slug: "github",
126
+ tools: {
127
+ /**
128
+ * Accepts a pending repository invitation that has been issued to the authenticated user.
129
+ */
130
+ ACCEPT_A_REPOSITORY_INVITATION: "GITHUB_ACCEPT_A_REPOSITORY_INVITATION",
131
+ },
132
+ triggerTypes: {},
133
+}
134
+
135
+/**
136
+ * Type map of all available trigger payloads for toolkit "GITHUB".
137
+ */
138
+export type GITHUB_TRIGGER_PAYLOADS = {}
139
+
140
+/**
141
+ * Type map of all available trigger events for toolkit "GITHUB".
142
+ */
143
+export type GITHUB_TRIGGER_EVENTS = {}
144
+"
145
+`;
146
+
147
+exports[`generateTypeScriptToolkitSources > with a single emitted file > with banner > [Given] versionMap with toolkit version overrides > without type tools > [Given] multiple toolkits with different version overrides [Then] each file includes its version comment 1`] = `
148
+"/* @toolkit-version: 20250901_00 */
149
+
150
+
151
+// ------------------- //
152
+// Trigger types //
153
+// ------------------- //
154
+
155
+
156
+
157
+/**
158
+ * Map of Composio's GMAIL toolkit.
159
+ * @toolkit-version: 20250901_00
160
+ */
161
+export const GMAIL = {
162
+ slug: "gmail",
163
+ tools: {},
164
+ triggerTypes: {},
165
+}
166
+
167
+/**
168
+ * Type map of all available trigger payloads for toolkit "GMAIL".
169
+ */
170
+export type GMAIL_TRIGGER_PAYLOADS = {}
171
+
172
+/**
173
+ * Type map of all available trigger events for toolkit "GMAIL".
174
+ */
175
+export type GMAIL_TRIGGER_EVENTS = {}
176
+"
177
+`;
178
+
179
+exports[`generateTypeScriptToolkitSources > with a single emitted file > with banner > [Given] versionMap with toolkit version overrides > without type tools > [Given] multiple toolkits with different version overrides [Then] each file includes its version comment 2`] = `
180
+"/* @toolkit-version: 20250815_00 */
181
+
182
+
183
+// ------------------- //
184
+// Trigger types //
185
+// ------------------- //
186
+
187
+
188
+
189
+/**
190
+ * Map of Composio's SLACK toolkit.
191
+ * @toolkit-version: 20250815_00
192
+ */
193
+export const SLACK = {
194
+ slug: "slack",
195
+ tools: {},
196
+ triggerTypes: {},
197
+}
198
+
199
+/**
200
+ * Type map of all available trigger payloads for toolkit "SLACK".
201
+ */
202
+export type SLACK_TRIGGER_PAYLOADS = {}
203
+
204
+/**
205
+ * Type map of all available trigger events for toolkit "SLACK".
206
+ */
207
+export type SLACK_TRIGGER_EVENTS = {}
208
+"
209
+`;
210
+
211
+exports[`generateTypeScriptToolkitSources > with a single emitted file > with banner > [Given] versionMap with toolkit version overrides > without type tools > [Given] only some toolkits with version override [Then] only those files include version comment 1`] = `
212
+"// ------------------- //
213
+// Trigger types //
214
+// ------------------- //
215
+
216
+
217
+
218
+/**
219
+ * Map of Composio's SLACK toolkit.
220
+ */
221
+export const SLACK = {
222
+ slug: "slack",
223
+ tools: {},
224
+ triggerTypes: {},
225
+}
226
+
227
+/**
228
+ * Type map of all available trigger payloads for toolkit "SLACK".
229
+ */
230
+export type SLACK_TRIGGER_PAYLOADS = {}
231
+
232
+/**
233
+ * Type map of all available trigger events for toolkit "SLACK".
234
+ */
235
+export type SLACK_TRIGGER_EVENTS = {}
236
+"
237
+`;
ts/packages/cli/test/src/generation/typescript/generate-toolkit-source.test.ts
+291
@@ -1356,6 +1356,297 @@ describe('generateTypeScriptToolkitSources', () => {
1356
})
1357
);
1358
});
1359
+
1360
+ describe('[Given] versionMap with toolkit version overrides', () => {
1361
+ describe('without type tools', () => {
1362
+ it.effect(
1363
+ '[Given] a toolkit with version override [Then] it includes version comment in generated file',
1364
+ Effect.fn(function* () {
1365
+ const toolkits = makeTestToolkits([
1366
+ {
1367
+ name: 'Gmail',
1368
+ slug: 'gmail',
1369
+ },
1370
+ ]);
1371
+
1372
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<
1373
+ Lowercase<string>,
1374
+ string
1375
+ >;
1376
+
1377
+ const index = createToolkitIndex({
1378
+ toolkits,
1379
+ typeableTools: { withTypes: false, tools: [] },
1380
+ triggerTypes: [],
1381
+ versionMap,
1382
+ });
1383
+
1384
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1385
+ expect(sources).toHaveLength(1);
1386
+ expect(sources[0][0]).toBe('gmail.ts');
1387
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1388
+ })
1389
+ );
1390
+
1391
+ it.effect(
1392
+ '[Given] multiple toolkits with different version overrides [Then] each file includes its version comment',
1393
+ Effect.fn(function* () {
1394
+ const toolkits = makeTestToolkits([
1395
+ {
1396
+ name: 'Gmail',
1397
+ slug: 'gmail',
1398
+ },
1399
+ {
1400
+ name: 'Slack Helper',
1401
+ slug: 'slack',
1402
+ },
1403
+ ]);
1404
+
1405
+ const versionMap = new Map([
1406
+ ['gmail', '20250901_00'],
1407
+ ['slack', '20250815_00'],
1408
+ ]) as Map<Lowercase<string>, string>;
1409
+
1410
+ const index = createToolkitIndex({
1411
+ toolkits,
1412
+ typeableTools: { withTypes: false, tools: [] },
1413
+ triggerTypes: [],
1414
+ versionMap,
1415
+ });
1416
+
1417
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1418
+ expect(sources).toHaveLength(2);
1419
+
1420
+ // Gmail should have its version comment
1421
+ expect(sources[0][0]).toBe('gmail.ts');
1422
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1423
+ expect(sources[0][1]).toMatchSnapshot();
1424
+
1425
+ // Slack should have its version comment
1426
+ expect(sources[1][0]).toBe('slack.ts');
1427
+ expect(sources[1][1]).toContain('@toolkit-version: 20250815_00');
1428
+ expect(sources[1][1]).toMatchSnapshot();
1429
+ })
1430
+ );
1431
+
1432
+ it.effect(
1433
+ '[Given] only some toolkits with version override [Then] only those files include version comment',
1434
+ Effect.fn(function* () {
1435
+ const toolkits = makeTestToolkits([
1436
+ {
1437
+ name: 'Gmail',
1438
+ slug: 'gmail',
1439
+ },
1440
+ {
1441
+ name: 'Slack Helper',
1442
+ slug: 'slack',
1443
+ },
1444
+ ]);
1445
+
1446
+ // Only gmail has a version override
1447
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<
1448
+ Lowercase<string>,
1449
+ string
1450
+ >;
1451
+
1452
+ const index = createToolkitIndex({
1453
+ toolkits,
1454
+ typeableTools: { withTypes: false, tools: [] },
1455
+ triggerTypes: [],
1456
+ versionMap,
1457
+ });
1458
+
1459
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1460
+ expect(sources).toHaveLength(2);
1461
+
1462
+ // Gmail should have version comment
1463
+ expect(sources[0][0]).toBe('gmail.ts');
1464
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1465
+
1466
+ // Slack should NOT have version comment
1467
+ expect(sources[1][0]).toBe('slack.ts');
1468
+ expect(sources[1][1]).not.toContain('@toolkit-version');
1469
+ expect(sources[1][1]).toMatchSnapshot();
1470
+ })
1471
+ );
1472
+
1473
+ it.effect(
1474
+ '[Given] empty versionMap [Then] no files include version comment',
1475
+ Effect.fn(function* () {
1476
+ const toolkits = makeTestToolkits([
1477
+ {
1478
+ name: 'Gmail',
1479
+ slug: 'gmail',
1480
+ },
1481
+ ]);
1482
+
1483
+ const versionMap = new Map() as Map<Lowercase<string>, string>;
1484
+
1485
+ const index = createToolkitIndex({
1486
+ toolkits,
1487
+ typeableTools: { withTypes: false, tools: [] },
1488
+ triggerTypes: [],
1489
+ versionMap,
1490
+ });
1491
+
1492
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1493
+ expect(sources).toHaveLength(1);
1494
+ expect(sources[0][0]).toBe('gmail.ts');
1495
+ expect(sources[0][1]).not.toContain('@toolkit-version');
1496
+ })
1497
+ );
1498
+ });
1499
+
1500
+ describe('with type tools', () => {
1501
+ it.effect(
1502
+ '[Given] a toolkit with version override [Then] it includes version comment in generated file',
1503
+ Effect.fn(function* () {
1504
+ const toolkits = makeTestToolkits([
1505
+ {
1506
+ name: 'Gmail',
1507
+ slug: 'gmail',
1508
+ },
1509
+ ]);
1510
+
1511
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<
1512
+ Lowercase<string>,
1513
+ string
1514
+ >;
1515
+
1516
+ const index = createToolkitIndex({
1517
+ toolkits,
1518
+ typeableTools: {
1519
+ withTypes: true,
1520
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
1521
+ },
1522
+ triggerTypes: [],
1523
+ versionMap,
1524
+ });
1525
+
1526
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1527
+ expect(sources).toHaveLength(1);
1528
+ expect(sources[0][0]).toBe('gmail.ts');
1529
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1530
+ })
1531
+ );
1532
+
1533
+ it.effect(
1534
+ '[Given] multiple toolkits with different version overrides [Then] each file includes its version comment',
1535
+ Effect.fn(function* () {
1536
+ const toolkits = makeTestToolkits([
1537
+ {
1538
+ name: 'Gmail',
1539
+ slug: 'gmail',
1540
+ },
1541
+ {
1542
+ name: 'Github',
1543
+ slug: 'github',
1544
+ },
1545
+ ]);
1546
+
1547
+ const versionMap = new Map([
1548
+ ['gmail', '20250901_00'],
1549
+ ['github', '20250815_00'],
1550
+ ]) as Map<Lowercase<string>, string>;
1551
+
1552
+ const index = createToolkitIndex({
1553
+ toolkits,
1554
+ typeableTools: {
1555
+ withTypes: true,
1556
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1), ...TOOLS_TYPES_GITHUB.slice(0, 1)],
1557
+ },
1558
+ triggerTypes: [],
1559
+ versionMap,
1560
+ });
1561
+
1562
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1563
+ expect(sources).toHaveLength(2);
1564
+
1565
+ // Gmail should have its version comment
1566
+ expect(sources[0][0]).toBe('gmail.ts');
1567
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1568
+ expect(sources[0][1]).toMatchSnapshot();
1569
+
1570
+ // Github should have its version comment
1571
+ expect(sources[1][0]).toBe('github.ts');
1572
+ expect(sources[1][1]).toContain('@toolkit-version: 20250815_00');
1573
+ expect(sources[1][1]).toMatchSnapshot();
1574
+ })
1575
+ );
1576
+
1577
+ it.effect(
1578
+ '[Given] only some toolkits with version override [Then] only those files include version comment',
1579
+ Effect.fn(function* () {
1580
+ const toolkits = makeTestToolkits([
1581
+ {
1582
+ name: 'Gmail',
1583
+ slug: 'gmail',
1584
+ },
1585
+ {
1586
+ name: 'Github',
1587
+ slug: 'github',
1588
+ },
1589
+ ]);
1590
+
1591
+ // Only gmail has a version override
1592
+ const versionMap = new Map([['gmail', '20250901_00']]) as Map<
1593
+ Lowercase<string>,
1594
+ string
1595
+ >;
1596
+
1597
+ const index = createToolkitIndex({
1598
+ toolkits,
1599
+ typeableTools: {
1600
+ withTypes: true,
1601
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1), ...TOOLS_TYPES_GITHUB.slice(0, 1)],
1602
+ },
1603
+ triggerTypes: [],
1604
+ versionMap,
1605
+ });
1606
+
1607
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1608
+ expect(sources).toHaveLength(2);
1609
+
1610
+ // Gmail should have version comment
1611
+ expect(sources[0][0]).toBe('gmail.ts');
1612
+ expect(sources[0][1]).toContain('@toolkit-version: 20250901_00');
1613
+
1614
+ // Github should NOT have version comment
1615
+ expect(sources[1][0]).toBe('github.ts');
1616
+ expect(sources[1][1]).not.toContain('@toolkit-version');
1617
+ })
1618
+ );
1619
+
1620
+ it.effect(
1621
+ '[Given] empty versionMap [Then] no files include version comment',
1622
+ Effect.fn(function* () {
1623
+ const toolkits = makeTestToolkits([
1624
+ {
1625
+ name: 'Gmail',
1626
+ slug: 'gmail',
1627
+ },
1628
+ ]);
1629
+
1630
+ const versionMap = new Map() as Map<Lowercase<string>, string>;
1631
+
1632
+ const index = createToolkitIndex({
1633
+ toolkits,
1634
+ typeableTools: {
1635
+ withTypes: true,
1636
+ tools: [...TOOLS_TYPES_GMAIL.slice(0, 1)],
1637
+ },
1638
+ triggerTypes: [],
1639
+ versionMap,
1640
+ });
1641
+
1642
+ const sources = yield* generateTypeScriptToolkitSources(banner)(index);
1643
+ expect(sources).toHaveLength(1);
1644
+ expect(sources[0][0]).toBe('gmail.ts');
1645
+ expect(sources[0][1]).not.toContain('@toolkit-version');
1646
+ })
1647
+ );
1648
+ });
1649
+ });
1650
});
1651
});
1652
});