@devries-cameron20 / composio-1 / commits / 0a43d39c5
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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 });