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