@devries-cameron20 / composio Mirror · read-only / commits / 88fad0a90
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 12:00 UTC

feat(ts/cli): validate invalid toolkit version overrides

jkomyno committed Jan 28, 2026 at 17:32 UTC 88fad0a90beb7739ad78a0f8398991d39ade81ab
11 files changed +714 -60
ts/packages/cli/.cursor/rules/composio-clients.mdc new
+73
@@ -0,0 +1,73 @@
1 +---
2 +description: Rule for keeping composio-clients.ts and composio-clients-cached.ts in sync
3 +globs:
4 + - "src/services/composio-clients.ts"
5 + - "src/services/composio-clients-cached.ts"
6 +alwaysApply: true
7 +---
8 +
9 +# ComposioClients Service Sync Rule
10 +
11 +## Critical Requirement
12 +
13 +When modifying `src/services/composio-clients.ts`, you MUST also update `src/services/composio-clients-cached.ts`.
14 +
15 +## Why This Matters
16 +
17 +The `ComposioToolkitsRepositoryCached` in `composio-clients-cached.ts` is a Layer wrapper that provides file-based caching around `ComposioToolkitsRepository`. It must implement the EXACT SAME interface.
18 +
19 +If you add, remove, or modify methods in `ComposioToolkitsRepository`, the cached layer will:
20 +- **Fail at runtime** if a method is missing
21 +- **Behave incorrectly** if method signatures don't match
22 +- **Cause type errors** if the interface is out of sync
23 +
24 +## Checklist When Modifying composio-clients.ts
25 +
26 +1. [ ] **New method added?** → Add corresponding entry in `ComposioToolkitsRepositoryCached`
27 + - Decide if it should be cached or passthrough
28 + - Validation methods: usually passthrough (no caching)
29 + - Data fetch methods: usually cached
30 +
31 +2. [ ] **Method signature changed?** → Update in both files
32 +
33 +3. [ ] **Method removed?** → Remove from both files
34 +
35 +4. [ ] **New error type added?** → Export from both files if needed
36 +
37 +## Example: Adding a New Method
38 +
39 +**In composio-clients.ts:**
40 +```typescript
41 +export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsRepository>()(...) {
42 + // ...
43 + newMethod: (arg: string) => Effect.Effect<Result, Error>,
44 +}
45 +```
46 +
47 +**In composio-clients-cached.ts:**
48 +```typescript
49 +return ComposioToolkitsRepository.make({
50 + // ... existing methods ...
51 +
52 + // For passthrough (no caching):
53 + newMethod: arg => underlyingRepository.newMethod(arg),
54 +
55 + // OR for cached:
56 + newMethod: arg => createCachedEffect(
57 + 'new-method.json',
58 + decoder,
59 + encoder,
60 + underlyingRepository.newMethod(arg)
61 + ),
62 +});
63 +```
64 +
65 +## Testing
66 +
67 +After modifying either file, run:
68 +```bash
69 +pnpm build:packages
70 +pnpm test
71 +```
72 +
73 +Build errors or failing tests often indicate a sync issue between these files.
ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
+19 -12
@@ -13,6 +13,7 @@ import {
13 getToolkitVersionOverrides,
14 type ToolkitVersionOverrides,
15 } from 'src/effects/toolkit-version-overrides';
16 +import { validateToolkitVersionOverrides } from 'src/effects/validate-toolkit-versions';
17
18 export const outputOpt = Options.optional(
19 Options.directory('output-dir', {
@@ -32,7 +33,10 @@ export const toolkitsOpt = Options.text('toolkits').pipe(
33
34 const _pyCmd$Generate = Command.make('generate', { outputOpt, toolkitsOpt }).pipe(
35 Command.withDescription(
35 - 'Generate Python type stubs for toolkits, tools, and triggers from the Composio API'
36 + 'Generate Python type stubs for toolkits, tools, and triggers from the Composio API.\n\n' +
37 + 'Environment Variables:\n' +
38 + ' COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)\n' +
39 + ' Use "latest" or unset to use the latest version.'
40 )
41 );
42
@@ -65,19 +69,22 @@ export function generatePythonTypeStubs({
69 // Read toolkit version overrides from environment variables
70 const versionOverrides = yield* getToolkitVersionOverrides;
71
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 - }
72 + // Validate toolkit slugs if specified
73 + const hasToolkitsFilter = Array.isNonEmptyArray(toolkitsOpt);
74 + const toolkitSlugsFilter = hasToolkitsFilter ? toolkitsOpt.map(s => s.toLowerCase()) : null;
75 +
76 + // Validate toolkit version overrides before fetching data
77 + // This will log detected overrides, validate them against API, and warn about unused ones
78 + const { validatedOverrides } = yield* validateToolkitVersionOverrides({
79 + versionOverrides,
80 + toolkitSlugsFilter,
81 + client,
82 + });
83
84 // Fetch data from Composio API
85 yield* Console.log('Fetching latest data from Composio API. This may take a while...');
86
79 - // Validate toolkit slugs if specified
80 - const hasToolkitsFilter = Array.isNonEmptyArray(toolkitsOpt);
87 + // Validate toolkit slugs if specified (separate from version validation)
88 const validatedToolkitSlugs = hasToolkitsFilter
89 ? yield* client
90 .validateToolkits(toolkitsOpt)
@@ -115,10 +122,10 @@ export function generatePythonTypeStubs({
122 );
123 }
124
118 - // Build version map for toolkits being generated
125 + // Build version map for toolkits being generated (using validated overrides)
126 const versionMap: ToolkitVersionOverrides = new Map();
127 for (const toolkit of toolkits) {
121 - const version = versionOverrides.get(toolkit.slug.toLowerCase() as Lowercase<string>);
128 + const version = validatedOverrides.get(toolkit.slug.toLowerCase() as Lowercase<string>);
129 if (version && version !== 'latest') {
130 versionMap.set(toolkit.slug.toLowerCase() as Lowercase<string>, version);
131 }
ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
+18 -23
@@ -35,8 +35,10 @@ import type { Tool, ToolsAsEnums } from 'src/models/tools';
35 import {
36 getToolkitVersionOverrides,
37 buildToolkitVersionSpecs,
38 + buildVersionMapFromSpecs,
39 type ToolkitVersionOverrides,
40 } from 'src/effects/toolkit-version-overrides';
41 +import { validateToolkitVersionOverrides } from 'src/effects/validate-toolkit-versions';
42
43 export const outputOpt = Options.optional(
44 Options.directory('output-dir', {
@@ -79,7 +81,10 @@ const _tsCmd$Generate = Command.make('generate', {
81 toolkitsOpt,
82 }).pipe(
83 Command.withDescription(
82 - 'Generate TypeScript types for toolkits, tools, and triggers from the Composio API'
84 + 'Generate TypeScript types for toolkits, tools, and triggers from the Composio API.\n\n' +
85 + 'Environment Variables:\n' +
86 + ' COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)\n' +
87 + ' Use "latest" or unset to use the latest version.'
88 )
89 );
90
@@ -113,12 +118,7 @@ function fetchFilteredData(
118 const versionSpecs = buildToolkitVersionSpecs(slugs, versionOverrides);
119
120 // 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 - }
121 + const versionMap = buildVersionMapFromSpecs(versionSpecs);
122
123 const [filteredToolkits, filteredTriggerTypes, filteredTypeableTools] = yield* Effect.all(
124 [
@@ -249,12 +249,7 @@ function fetchAllDataWithOverrides(
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 - }
252 + const versionMap = buildVersionMapFromSpecs(versionSpecs);
253
254 // 3. Fetch trigger types and tools in parallel
255 const [allTriggerTypes, allTypeableTools] = yield* Effect.all(
@@ -377,23 +372,23 @@ export function generateTypescriptTypeStubs({
372 // Read toolkit version overrides from environment variables
373 const versionOverrides = yield* getToolkitVersionOverrides;
374
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 -
375 // Normalize toolkit slugs if specified (lowercase for API filtering)
376 const toolkitSlugsFilter = Array.isNonEmptyArray(toolkitsOpt)
377 ? toolkitsOpt.map(s => s.toLowerCase())
378 : null;
379
380 + // Validate toolkit version overrides before fetching data
381 + // This will log detected overrides, validate them against API, and warn about unused ones
382 + const { validatedOverrides } = yield* validateToolkitVersionOverrides({
383 + versionOverrides,
384 + toolkitSlugsFilter,
385 + client,
386 + });
387 +
388 // Fetch data using two distinct strategies based on whether --toolkits filter is provided
389 const { toolkits, triggerTypes, typeableTools, versionMap } = yield* toolkitSlugsFilter !== null
395 - ? fetchFilteredData(client, toolkitSlugsFilter, typeTools, versionOverrides)
396 - : fetchAllData(client, typeTools, versionOverrides);
390 + ? fetchFilteredData(client, toolkitSlugsFilter, typeTools, validatedOverrides)
391 + : fetchAllData(client, typeTools, validatedOverrides);
392
393 yield* Console.log('Writing TypeScript type stubs to disk...');
394 const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes, versionMap });
ts/packages/cli/src/effects/toolkit-version-overrides.ts
+57 -3
@@ -32,6 +32,32 @@ export const TOOLKIT_VERSION_OVERRIDES_CONFIG = pipe(
32 */
33 export type ToolkitVersionOverrides = Map<Lowercase<string>, string>;
34
35 +/**
36 + * Regex pattern for valid version strings.
37 + * Only allows: alphanumeric characters (a-z, A-Z, 0-9), hyphens, underscores, and dots.
38 + */
39 +const VALID_VERSION_PATTERN = /^[a-zA-Z0-9._-]+$/;
40 +
41 +/**
42 + * Sanitizes a version string by removing invalid characters.
43 + * Only keeps: alphanumeric characters (a-z, A-Z, 0-9), hyphens, underscores, and dots.
44 + *
45 + * @param version - The version string to sanitize
46 + * @returns The sanitized version string, or null if it becomes empty after sanitization
47 + */
48 +export const sanitizeVersionString = (version: string): string | null => {
49 + // If the version already matches the valid pattern, return as-is
50 + if (VALID_VERSION_PATTERN.test(version)) {
51 + return version;
52 + }
53 +
54 + // Remove invalid characters
55 + const sanitized = version.replace(/[^a-zA-Z0-9._-]/g, '');
56 +
57 + // Return null if the sanitized version is empty
58 + return sanitized.length > 0 ? sanitized : null;
59 +};
60 +
61 /**
62 * Reads toolkit version overrides from environment variables.
63 *
@@ -61,7 +87,11 @@ export const getToolkitVersionOverrides: Effect.Effect<
87 for (const [key, value] of HashMap.toEntries(hashMap)) {
88 // Normalize toolkit name to lowercase and skip 'latest' values
89 if (value && value !== 'latest') {
64 - result.set(String.toLowerCase(key), value);
90 + // Sanitize version string to only allow valid characters
91 + const sanitizedVersion = sanitizeVersionString(value);
92 + if (sanitizedVersion) {
93 + result.set(String.toLowerCase(key), sanitizedVersion);
94 + }
95 }
96 }
97 return result;
@@ -105,8 +135,32 @@ export const groupByVersion = (
135 ): Map<string, Lowercase<string>[]> => {
136 const grouped = new Map<string, Lowercase<string>[]>();
137 for (const spec of specs) {
108 - const existing = grouped.get(spec.toolkitVersion) ?? [];
109 - grouped.set(spec.toolkitVersion, [...existing, spec.toolkitSlug]);
138 + const existing = grouped.get(spec.toolkitVersion);
139 + if (existing) {
140 + existing.push(spec.toolkitSlug);
141 + } else {
142 + grouped.set(spec.toolkitVersion, [spec.toolkitSlug]);
143 + }
144 }
145 return grouped;
146 };
147 +
148 +/**
149 + * Builds a ToolkitVersionOverrides map from version specs, excluding 'latest' versions.
150 + * This is the single source of truth for building version maps from specs.
151 + *
152 + * @example
153 + * // Given specs: [{ toolkitSlug: 'gmail', toolkitVersion: '20250901_00' }, { toolkitSlug: 'slack', toolkitVersion: 'latest' }]
154 + * // Returns: Map { "gmail" => "20250901_00" }
155 + */
156 +export const buildVersionMapFromSpecs = (
157 + specs: ReadonlyArray<ToolkitVersionSpec>
158 +): ToolkitVersionOverrides => {
159 + const versionMap = new Map<Lowercase<string>, string>();
160 + for (const spec of specs) {
161 + if (spec.toolkitVersion !== 'latest') {
162 + versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
163 + }
164 + }
165 + return versionMap;
166 +};
ts/packages/cli/src/effects/validate-toolkit-versions.ts new
+190
@@ -0,0 +1,190 @@
1 +import { Console, Effect } from 'effect';
2 +import colors from 'picocolors';
3 +import { S_BAR, unicodeOr } from '@clack/prompts';
4 +import type {
5 + ComposioToolkitsRepository,
6 + InvalidVersionDetail,
7 +} from 'src/services/composio-clients';
8 +import type { ToolkitVersionOverrides } from './toolkit-version-overrides';
9 +
10 +/**
11 + * Custom error class for invalid toolkit versions that preserves structured data.
12 + * This allows consumers to access both the human-readable message and the machine-readable data.
13 + */
14 +export class InvalidToolkitVersionsValidationError extends Error {
15 + readonly invalidVersions: ReadonlyArray<InvalidVersionDetail>;
16 +
17 + constructor(invalidVersions: ReadonlyArray<InvalidVersionDetail>) {
18 + super(formatInvalidVersionsError(invalidVersions));
19 + this.name = 'InvalidToolkitVersionsValidationError';
20 + this.invalidVersions = invalidVersions;
21 + }
22 +
23 + /**
24 + * Returns a JSON-serializable representation of the error for programmatic access.
25 + */
26 + toJSON(): { error: string; invalidVersions: ReadonlyArray<InvalidVersionDetail> } {
27 + return {
28 + error: this.name,
29 + invalidVersions: this.invalidVersions,
30 + };
31 + }
32 +}
33 +
34 +const MAX_VERSIONS_TO_SHOW = 5;
35 +const S_CORNER_TOP_LEFT = unicodeOr('╭', '+');
36 +const S_CORNER_BOTTOM_LEFT = unicodeOr('╰', '+');
37 +const S_STEP_ERROR = unicodeOr('▲', 'x');
38 +
39 +/**
40 + * Formats an InvalidToolkitVersionsError into a user-friendly error message.
41 + *
42 + * NOTE: We avoid using `: ` (colon-space) in the error message because effect-errors
43 + * splits on that pattern and converts the result to an array, which then renders
44 + * with commas instead of colons when converted back to string.
45 + */
46 +export function formatInvalidVersionsError(
47 + invalidVersions: ReadonlyArray<InvalidVersionDetail>
48 +): string {
49 + const lines: string[] = [];
50 +
51 + // Header
52 + lines.push(
53 + `${colors.red(S_STEP_ERROR)} ${colors.red('Invalid toolkit version override')}${invalidVersions.length > 1 ? 's' : ''}`
54 + );
55 + lines.push('');
56 +
57 + for (let i = 0; i < invalidVersions.length; i++) {
58 + const { toolkit, requestedVersion, availableVersions } = invalidVersions[i];
59 + const isLast = i === invalidVersions.length - 1;
60 + const connector = isLast ? S_CORNER_BOTTOM_LEFT : S_BAR;
61 +
62 + // Toolkit header with version
63 + lines.push(
64 + `${colors.gray(connector)} ${colors.cyan(toolkit.toUpperCase())} ${colors.dim('→')} version ${colors.yellow(`"${requestedVersion}"`)} ${colors.red('not found')}`
65 + );
66 +
67 + // Available versions (use → instead of : to avoid effect-errors split issue)
68 + if (availableVersions.length === 0) {
69 + lines.push(
70 + `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('No versions available (toolkit may not support versioning)')}`
71 + );
72 + } else {
73 + const versionsToShow = availableVersions.slice(0, MAX_VERSIONS_TO_SHOW);
74 + const remaining = availableVersions.length - MAX_VERSIONS_TO_SHOW;
75 +
76 + let versionList = versionsToShow.map(v => colors.green(v)).join(colors.dim(', '));
77 + if (remaining > 0) {
78 + versionList += colors.dim(` (+${remaining} more)`);
79 + }
80 +
81 + lines.push(
82 + `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('Available →')} ${versionList}`
83 + );
84 + }
85 +
86 + // Tip (use → instead of : to avoid effect-errors split issue)
87 + const envVarName = `COMPOSIO_TOOLKIT_VERSION_${toolkit.toUpperCase()}`;
88 + lines.push(
89 + `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('Tip →')} Use ${colors.cyan('"latest"')} or unset ${colors.cyan(envVarName)}`
90 + );
91 +
92 + // Add spacing between toolkits (except for the last one)
93 + if (!isLast) {
94 + lines.push(colors.gray(S_BAR));
95 + }
96 + }
97 +
98 + return lines.join('\n');
99 +}
100 +
101 +/**
102 + * Options for validateToolkitVersionOverrides
103 + */
104 +export interface ValidateVersionsOptions {
105 + /** Map of toolkit slug to requested version */
106 + readonly versionOverrides: ToolkitVersionOverrides;
107 + /** Optional array of toolkit slugs to filter (from --toolkits flag) */
108 + readonly toolkitSlugsFilter: ReadonlyArray<string> | null;
109 + /** The ComposioToolkitsRepository client */
110 + readonly client: ComposioToolkitsRepository;
111 +}
112 +
113 +/**
114 + * Result of version validation
115 + */
116 +export interface ValidateVersionsResult {
117 + /** The validated overrides (only includes relevant toolkits) */
118 + readonly validatedOverrides: ToolkitVersionOverrides;
119 +}
120 +
121 +/**
122 + * Validates toolkit version overrides before fetching data.
123 + *
124 + * This function should be called early in the generate command flow,
125 + * before any tool/trigger data is fetched. It will:
126 + * 1. Log detected version overrides
127 + * 2. Validate versions against the API's available_versions
128 + * 3. Warn about unused overrides (when --toolkits filter excludes them)
129 + * 4. Fail with a descriptive error if any versions are invalid
130 + *
131 + * @example
132 + * ```typescript
133 + * const { validatedOverrides } = yield* validateToolkitVersionOverrides({
134 + * versionOverrides,
135 + * toolkitSlugsFilter,
136 + * client,
137 + * });
138 + * ```
139 + */
140 +export const validateToolkitVersionOverrides = ({
141 + versionOverrides,
142 + toolkitSlugsFilter,
143 + client,
144 +}: ValidateVersionsOptions): Effect.Effect<ValidateVersionsResult, Error> =>
145 + Effect.gen(function* () {
146 + // Skip if no overrides
147 + if (versionOverrides.size === 0) {
148 + return { validatedOverrides: versionOverrides };
149 + }
150 +
151 + // Log detected overrides
152 + yield* Console.log('Detected toolkit version overrides:');
153 + for (const [toolkit, version] of versionOverrides) {
154 + yield* Console.log(` - ${toolkit}: ${version}`);
155 + }
156 +
157 + yield* Console.log('Validating toolkit version overrides...');
158 +
159 + const { validatedOverrides, warnings } = yield* client
160 + .validateToolkitVersions(versionOverrides, toolkitSlugsFilter ?? undefined)
161 + .pipe(
162 + Effect.catchTag('services/InvalidToolkitVersionsError', error =>
163 + Effect.fail(new InvalidToolkitVersionsValidationError(error.invalidVersions))
164 + ),
165 + Effect.catchTag('services/InvalidToolkitsError', error =>
166 + Effect.fail(
167 + new Error(
168 + `Invalid toolkit(s) in version overrides: ${error.invalidToolkits.join(', ')}. ` +
169 + `Check that the toolkit slug is correct (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL, not COMPOSIO_TOOLKIT_VERSION_GMAL).`
170 + )
171 + )
172 + ),
173 + Effect.catchTag('services/HttpServerError', error =>
174 + Effect.fail(new Error(`Failed to validate toolkit versions: ${error.cause}`))
175 + ),
176 + Effect.catchTag('services/HttpDecodingError', error =>
177 + Effect.fail(new Error(`Failed to decode toolkit response: ${error.cause}`))
178 + ),
179 + Effect.catchTag('NoSuchElementException', () =>
180 + Effect.fail(new Error('API client not initialized'))
181 + )
182 + );
183 +
184 + // Log warnings for unused overrides
185 + for (const warning of warnings) {
186 + yield* Console.warn(`Warning: ${warning}`);
187 + }
188 +
189 + return { validatedOverrides };
190 + });
ts/packages/cli/src/models/toolkits.ts
+1
@@ -12,6 +12,7 @@ export const Toolkit = Schema.Struct({
12 categories: Schema.Array(Schema.Unknown),
13 created_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
14 updated_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
15 + available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
16 }),
17 no_auth: Schema.Boolean,
18 }).annotations({ identifier: 'Toolkit' });
ts/packages/cli/src/services/composio-clients-cached.ts
+6
@@ -232,6 +232,12 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
232 validateToolkits: toolkitSlugs => underlyingRepository.validateToolkits(toolkitSlugs),
233 filterToolkitsBySlugs: (toolkits, toolkitSlugs) =>
234 underlyingRepository.filterToolkitsBySlugs(toolkits, toolkitSlugs),
235 + // Version validation should NOT be cached because:
236 + // 1. available_versions can change frequently as new versions are released
237 + // 2. Validation should always reflect the current API state
238 + // 3. Caching validation results could cause false positives/negatives
239 + validateToolkitVersions: (overrides, relevantToolkits) =>
240 + underlyingRepository.validateToolkitVersions(overrides, relevantToolkits),
241 });
242 })
243 ).pipe(
ts/packages/cli/src/services/composio-clients.ts
+190 -20
@@ -15,7 +15,11 @@ 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';
18 +import {
19 + groupByVersion,
20 + type ToolkitVersionSpec,
21 + type ToolkitVersionOverrides,
22 +} from 'src/effects/toolkit-version-overrides';
23 import { Session, RetrievedSession } from 'src/models/session';
24 import { TriggerType, TriggerTypes, TriggerTypesAsEnums } from 'src/models/trigger-types';
25 import { ComposioUserContext, ComposioUserContextLive } from './user-context';
@@ -42,6 +46,24 @@ export class InvalidToolkitsError extends Data.TaggedError('services/InvalidTool
46 readonly availableToolkits: ReadonlyArray<string>;
47 }> {}
48
49 +/**
50 + * Details about a single invalid version override.
51 + */
52 +export interface InvalidVersionDetail {
53 + readonly toolkit: string;
54 + readonly requestedVersion: string;
55 + readonly availableVersions: ReadonlyArray<string>;
56 +}
57 +
58 +/**
59 + * Error thrown when one or more toolkit version overrides are invalid.
60 + */
61 +export class InvalidToolkitVersionsError extends Data.TaggedError(
62 + 'services/InvalidToolkitVersionsError'
63 +)<{
64 + readonly invalidVersions: ReadonlyArray<InvalidVersionDetail>;
65 +}> {}
66 +
67 /**
68 * Error thrown when a HTTP response doesn't match the expected response schema.
69 */
@@ -51,6 +73,131 @@ export class HttpDecodingError extends Data.TaggedError('services/HttpDecodingEr
73
74 export type HttpError = HttpServerError | HttpDecodingError;
75
76 +const validateToolkitVersionsImpl = (
77 + client: {
78 + toolkits: {
79 + retrieve: (slug: string) => Effect.Effect<Toolkit, HttpError | NoSuchElementException, never>;
80 + };
81 + },
82 + overrides: ToolkitVersionOverrides,
83 + relevantToolkits?: ReadonlyArray<string>
84 +): Effect.Effect<
85 + {
86 + validatedOverrides: ToolkitVersionOverrides;
87 + warnings: ReadonlyArray<string>;
88 + },
89 + InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
90 +> =>
91 + Effect.gen(function* () {
92 + const determineOverridesToValidate = (
93 + overrides: ToolkitVersionOverrides,
94 + relevantToolkits?: ReadonlyArray<string>
95 + ): {
96 + overridesToValidate: Array<[toolkit: string, requestedVersion: string]>;
97 + warnings: Array<string>;
98 + } => {
99 + const warnings: string[] = [];
100 + const overridesToValidate: Array<[toolkit: string, requestedVersion: string]> = [];
101 +
102 + if (relevantToolkits) {
103 + const relevantSet = new Set(relevantToolkits.map(s => String.toLowerCase(s)));
104 +
105 + for (const [toolkit, version] of overrides) {
106 + if (relevantSet.has(toolkit)) {
107 + overridesToValidate.push([toolkit, version]);
108 + } else {
109 + warnings.push(
110 + `Version override for "${toolkit}" will be ignored (toolkit not in --toolkits filter)`
111 + );
112 + }
113 + }
114 + } else {
115 + overridesToValidate.push(...overrides.entries());
116 + }
117 +
118 + return { overridesToValidate, warnings };
119 + };
120 +
121 + const fetchToolkitVersionValidationResults = (
122 + overridesToValidate: ReadonlyArray<[toolkit: string, requestedVersion: string]>
123 + ): Effect.Effect<
124 + ReadonlyArray<{
125 + toolkit: string;
126 + requestedVersion: string;
127 + availableVersions: ReadonlyArray<string>;
128 + isValid: boolean;
129 + }>,
130 + InvalidToolkitsError | HttpError | NoSuchElementException
131 + > =>
132 + Effect.all(
133 + overridesToValidate.map(([toolkit, requestedVersion]) =>
134 + client.toolkits.retrieve(toolkit).pipe(
135 + Effect.map(toolkitData => ({
136 + toolkit,
137 + requestedVersion,
138 + availableVersions: toolkitData.meta.available_versions,
139 + isValid: toolkitData.meta.available_versions.includes(requestedVersion),
140 + })),
141 + Effect.catchTag('services/HttpServerError', e =>
142 + Effect.if(e.status === 404, {
143 + onTrue: () =>
144 + Effect.fail(
145 + new InvalidToolkitsError({
146 + invalidToolkits: [toolkit],
147 + availableToolkits: [],
148 + })
149 + ),
150 + onFalse: () => Effect.fail(e),
151 + })
152 + )
153 + )
154 + ),
155 + { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
156 + );
157 +
158 + const collectInvalidVersions = (
159 + validationResults: ReadonlyArray<{
160 + toolkit: string;
161 + requestedVersion: string;
162 + availableVersions: ReadonlyArray<string>;
163 + isValid: boolean;
164 + }>
165 + ): ReadonlyArray<InvalidVersionDetail> =>
166 + validationResults
167 + .filter(result => !result.isValid)
168 + .map(result => ({
169 + toolkit: result.toolkit,
170 + requestedVersion: result.requestedVersion,
171 + availableVersions: result.availableVersions,
172 + }));
173 +
174 + if (overrides.size === 0) {
175 + return { validatedOverrides: overrides, warnings: [] as ReadonlyArray<string> };
176 + }
177 +
178 + const { overridesToValidate, warnings } = determineOverridesToValidate(
179 + overrides,
180 + relevantToolkits
181 + );
182 +
183 + if (overridesToValidate.length === 0) {
184 + return {
185 + validatedOverrides: new Map() as ToolkitVersionOverrides,
186 + warnings: warnings as ReadonlyArray<string>,
187 + };
188 + }
189 +
190 + const validationResults = yield* fetchToolkitVersionValidationResults(overridesToValidate);
191 + const invalidVersions = collectInvalidVersions(validationResults);
192 +
193 + if (invalidVersions.length > 0) {
194 + return yield* Effect.fail(new InvalidToolkitVersionsError({ invalidVersions }));
195 + }
196 +
197 + const validatedOverrides = new Map(overridesToValidate) as ToolkitVersionOverrides;
198 + return { validatedOverrides, warnings: warnings as ReadonlyArray<string> };
199 + });
200 +
201 /**
202 * Response schemas
203 */
@@ -82,6 +229,7 @@ export const ToolkitRetrieveResponse = Schema.Struct({
229 categories: Schema.optionalWith(Schema.Array(Schema.Unknown), { default: () => [] }),
230 created_at: Schema.DateTimeUtc,
231 updated_at: Schema.DateTimeUtc,
232 + available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
233 }),
234 }).annotations({ identifier: 'ToolkitRetrieveResponse' });
235 export type ToolkitRetrieveResponse = Schema.Schema.Type<typeof ToolkitRetrieveResponse>;
@@ -531,32 +679,36 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
679 ),
680 /**
681 * Retrieve tools for multiple toolkits, grouped by version.
534 - * Makes separate API calls for each version group, then merges results.
682 + * Makes parallel API calls for each version group, then merges results.
683 * @param specs - Array of toolkit version specifications
684 */
685 listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
686 Effect.gen(function* () {
687 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
688 + const versionGroups = [...grouped.entries()];
689 +
690 + // Fetch all version groups in parallel with bounded concurrency
691 + const responses = yield* Effect.all(
692 + versionGroups.map(([version, slugs]) =>
693 + withMetrics(
694 + callClientWithPagination(
695 + clientSingleton,
696 + (client, cursor, limit) =>
697 + client.tools.list({
698 + cursor,
699 + toolkit_slug: slugs.join(','),
700 + toolkit_versions: version,
701 + limit,
702 + }),
703 + ToolsResponse
704 + )
705 )
556 - );
557 - allTools.push(...response.items);
558 - }
706 + ),
707 + { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
708 + );
709
710 + // Merge all tools from all version groups
711 + const allTools = responses.flatMap(response => response.items);
712 return { items: allTools };
713 }),
714 },
@@ -781,6 +933,24 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
933 const normalizedSlugs = new Set(toolkitSlugs.map(slug => String.toLowerCase(slug)));
934 return toolkits.filter(toolkit => normalizedSlugs.has(String.toLowerCase(toolkit.slug)));
935 },
936 + /**
937 + * Validates that the requested toolkit versions exist in the API's available_versions.
938 + * Makes parallel API calls to fetch toolkit metadata for validation.
939 + *
940 + * @param overrides - Map of toolkit slug to requested version
941 + * @param relevantToolkits - Optional array of toolkit slugs to validate (if --toolkits filter is used)
942 + * @returns Effect that succeeds with the validated overrides and warnings, or fails with InvalidToolkitVersionsError
943 + */
944 + validateToolkitVersions: (
945 + overrides: ToolkitVersionOverrides,
946 + relevantToolkits?: ReadonlyArray<string>
947 + ): Effect.Effect<
948 + {
949 + validatedOverrides: ToolkitVersionOverrides;
950 + warnings: ReadonlyArray<string>;
951 + },
952 + InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
953 + > => validateToolkitVersionsImpl(client, overrides, relevantToolkits),
954 };
955 }),
956 dependencies: [ComposioClientLive.Default],
ts/packages/cli/test/__utils__/services/test-layer.ts
+52
@@ -23,7 +23,10 @@ import {
23 ComposioSessionRepository,
24 ComposioToolkitsRepository,
25 InvalidToolkitsError,
26 + InvalidToolkitVersionsError,
27 + type InvalidVersionDetail,
28 } from 'src/services/composio-clients';
29 +import type { ToolkitVersionOverrides } from 'src/effects/toolkit-version-overrides';
30 import { EnvLangDetector } from 'src/services/env-lang-detector';
31 import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
32 import type { Tools } from 'src/models/tools';
@@ -160,6 +163,55 @@ export const TestLayer = (input?: TestLiveInput) =>
163 );
164 return Effect.succeed(tools);
165 },
166 + validateToolkitVersions: (
167 + overrides: ToolkitVersionOverrides,
168 + relevantToolkits?: ReadonlyArray<string>
169 + ) => {
170 + // Mock implementation that validates against test fixture
171 + const invalidVersions: InvalidVersionDetail[] = [];
172 + const warnings: string[] = [];
173 +
174 + for (const [toolkit, version] of overrides) {
175 + // Check if toolkit should be validated
176 + if (relevantToolkits && !relevantToolkits.map(s => s.toLowerCase()).includes(toolkit)) {
177 + warnings.push(`Version override for "${toolkit}" will be ignored`);
178 + continue;
179 + }
180 +
181 + // Check if toolkit exists in the fixture
182 + const toolkitExists = toolkitsData.toolkits.some(
183 + t => String.toLowerCase(t.slug) === toolkit
184 + );
185 +
186 + if (!toolkitExists) {
187 + return Effect.fail(
188 + new InvalidToolkitsError({
189 + invalidToolkits: [toolkit],
190 + availableToolkits: toolkitsData.toolkits.map(t => t.slug),
191 + })
192 + );
193 + }
194 +
195 + // Mock: only accept 'latest' or versions matching pattern YYYYMMDD_NN
196 + const validPattern = /^\d{8}_\d{2}$/;
197 + if (version !== 'latest' && !validPattern.test(version)) {
198 + invalidVersions.push({
199 + toolkit,
200 + requestedVersion: version,
201 + availableVersions: ['20250901_00', '20250815_00', '20250710_00'],
202 + });
203 + }
204 + }
205 +
206 + if (invalidVersions.length > 0) {
207 + return Effect.fail(new InvalidToolkitVersionsError({ invalidVersions }));
208 + }
209 +
210 + return Effect.succeed({
211 + validatedOverrides: overrides,
212 + warnings: warnings as ReadonlyArray<string>,
213 + });
214 + },
215 })
216 );
217 const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
ts/packages/cli/test/src/commands/$default.cmd.test.ts
+10 -2
@@ -72,11 +72,19 @@ describe('CLI: composio', () => {
72
73 - py Handle Python projects.
74
75 - - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API
75 + - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
76 +
77 + Environment Variables:
78 + COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
79 + Use "latest" or unset to use the latest version.
80
81 - ts Handle TypeScript projects.
82
79 - - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API
83 + - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
84 +
85 + Environment Variables:
86 + COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
87 + Use "latest" or unset to use the latest version.
88 "
89 `);
90 })
ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts
+98
@@ -4,6 +4,8 @@ import {
4 getToolkitVersionOverrides,
5 buildToolkitVersionSpecs,
6 groupByVersion,
7 + sanitizeVersionString,
8 + buildVersionMapFromSpecs,
9 type ToolkitVersionOverrides,
10 type ToolkitVersionSpec,
11 } from 'src/effects/toolkit-version-overrides';
@@ -202,4 +204,100 @@ describe('toolkit-version-overrides', () => {
204 expect(grouped.get('latest')).toEqual(['gmail', 'slack', 'github', 'notion']);
205 });
206 });
207 +
208 + describe('sanitizeVersionString', () => {
209 + it('should return valid version strings unchanged', () => {
210 + expect(sanitizeVersionString('20250901_00')).toBe('20250901_00');
211 + expect(sanitizeVersionString('v1.2.3')).toBe('v1.2.3');
212 + expect(sanitizeVersionString('latest')).toBe('latest');
213 + expect(sanitizeVersionString('1.0.0-beta.1')).toBe('1.0.0-beta.1');
214 + });
215 +
216 + it('should remove invalid characters', () => {
217 + expect(sanitizeVersionString('20250901_00!')).toBe('20250901_00');
218 + expect(sanitizeVersionString('version@123')).toBe('version123');
219 + expect(sanitizeVersionString('v1.2.3#tag')).toBe('v1.2.3tag');
220 + });
221 +
222 + it('should handle unicode and special characters', () => {
223 + expect(sanitizeVersionString('版本1.0')).toBe('1.0');
224 + expect(sanitizeVersionString('v1.0\n\t')).toBe('v1.0');
225 + expect(sanitizeVersionString('$version$')).toBe('version');
226 + });
227 +
228 + it('should return null for empty or all-invalid strings', () => {
229 + expect(sanitizeVersionString('')).toBe(null);
230 + expect(sanitizeVersionString('$$$')).toBe(null);
231 + expect(sanitizeVersionString(' ')).toBe(null);
232 + });
233 +
234 + it('should allow alphanumeric, hyphens, underscores, and dots', () => {
235 + expect(sanitizeVersionString('abc-123_456.789')).toBe('abc-123_456.789');
236 + expect(sanitizeVersionString('ABC-XYZ_000.999')).toBe('ABC-XYZ_000.999');
237 + });
238 + });
239 +
240 + describe('buildVersionMapFromSpecs', () => {
241 + it('should build version map excluding latest versions', () => {
242 + const specs: ToolkitVersionSpec[] = [
243 + { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
244 + { toolkitSlug: 'slack', toolkitVersion: 'latest' },
245 + { toolkitSlug: 'github', toolkitVersion: '20250815_00' },
246 + ];
247 + const versionMap = buildVersionMapFromSpecs(specs);
248 +
249 + expect(versionMap.size).toBe(2);
250 + expect(versionMap.get('gmail')).toBe('20250901_00');
251 + expect(versionMap.get('github')).toBe('20250815_00');
252 + expect(versionMap.has('slack')).toBe(false);
253 + });
254 +
255 + it('should return empty map when all versions are latest', () => {
256 + const specs: ToolkitVersionSpec[] = [
257 + { toolkitSlug: 'gmail', toolkitVersion: 'latest' },
258 + { toolkitSlug: 'slack', toolkitVersion: 'latest' },
259 + ];
260 + const versionMap = buildVersionMapFromSpecs(specs);
261 +
262 + expect(versionMap.size).toBe(0);
263 + });
264 +
265 + it('should return empty map for empty specs', () => {
266 + const versionMap = buildVersionMapFromSpecs([]);
267 + expect(versionMap.size).toBe(0);
268 + });
269 +
270 + it('should include all non-latest versions', () => {
271 + const specs: ToolkitVersionSpec[] = [
272 + { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
273 + { toolkitSlug: 'slack', toolkitVersion: '20250815_00' },
274 + { toolkitSlug: 'github', toolkitVersion: '20250710_00' },
275 + ];
276 + const versionMap = buildVersionMapFromSpecs(specs);
277 +
278 + expect(versionMap.size).toBe(3);
279 + expect(versionMap.get('gmail')).toBe('20250901_00');
280 + expect(versionMap.get('slack')).toBe('20250815_00');
281 + expect(versionMap.get('github')).toBe('20250710_00');
282 + });
283 + });
284 +
285 + describe('getToolkitVersionOverrides with sanitization', () => {
286 + it.effect('should sanitize version strings with invalid characters', () =>
287 + Effect.gen(function* () {
288 + vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00!@#');
289 + const result = yield* getToolkitVersionOverrides;
290 + expect(result.get('gmail')).toBe('20250901_00');
291 + expect(result.size).toBe(1);
292 + })
293 + );
294 +
295 + it.effect('should ignore version strings that become empty after sanitization', () =>
296 + Effect.gen(function* () {
297 + vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '$$$');
298 + const result = yield* getToolkitVersionOverrides;
299 + expect(result.size).toBe(0);
300 + })
301 + );
302 + });
303 });