Skip to content

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

jkomyno88fad0a90beb
diff --git a/ts/packages/cli/.cursor/rules/composio-clients.mdc b/ts/packages/cli/.cursor/rules/composio-clients.mdc
new file mode 100644
index 000000000..86129ae1b
--- /dev/null
+++ b/ts/packages/cli/.cursor/rules/composio-clients.mdc
@@ -0,0 +1,73 @@
+---
+description: Rule for keeping composio-clients.ts and composio-clients-cached.ts in sync
+globs:
+ - "src/services/composio-clients.ts"
+ - "src/services/composio-clients-cached.ts"
+alwaysApply: true
+---
+
+# ComposioClients Service Sync Rule
+
+## Critical Requirement
+
+When modifying `src/services/composio-clients.ts`, you MUST also update `src/services/composio-clients-cached.ts`.
+
+## Why This Matters
+
+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.
+
+If you add, remove, or modify methods in `ComposioToolkitsRepository`, the cached layer will:
+- **Fail at runtime** if a method is missing
+- **Behave incorrectly** if method signatures don't match
+- **Cause type errors** if the interface is out of sync
+
+## Checklist When Modifying composio-clients.ts
+
+1. [ ] **New method added?** → Add corresponding entry in `ComposioToolkitsRepositoryCached`
+ - Decide if it should be cached or passthrough
+ - Validation methods: usually passthrough (no caching)
+ - Data fetch methods: usually cached
+
+2. [ ] **Method signature changed?** → Update in both files
+
+3. [ ] **Method removed?** → Remove from both files
+
+4. [ ] **New error type added?** → Export from both files if needed
+
+## Example: Adding a New Method
+
+**In composio-clients.ts:**
+```typescript
+export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsRepository>()(...) {
+ // ...
+ newMethod: (arg: string) => Effect.Effect<Result, Error>,
+}
+```
+
+**In composio-clients-cached.ts:**
+```typescript
+return ComposioToolkitsRepository.make({
+ // ... existing methods ...
+
+ // For passthrough (no caching):
+ newMethod: arg => underlyingRepository.newMethod(arg),
+
+ // OR for cached:
+ newMethod: arg => createCachedEffect(
+ 'new-method.json',
+ decoder,
+ encoder,
+ underlyingRepository.newMethod(arg)
+ ),
+});
+```
+
+## Testing
+
+After modifying either file, run:
+```bash
+pnpm build:packages
+pnpm test
+```
+
+Build errors or failing tests often indicate a sync issue between these files.
diff --git a/ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts b/ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
index 8526293b4..075034d12 100644
--- a/ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
+++ b/ts/packages/cli/src/commands/py/commands/py.generate.cmd.ts
@@ -13,6 +13,7 @@ import {
getToolkitVersionOverrides,
type ToolkitVersionOverrides,
} from 'src/effects/toolkit-version-overrides';
+import { validateToolkitVersionOverrides } from 'src/effects/validate-toolkit-versions';
export const outputOpt = Options.optional(
Options.directory('output-dir', {
@@ -32,7 +33,10 @@ export const toolkitsOpt = Options.text('toolkits').pipe(
const _pyCmd$Generate = Command.make('generate', { outputOpt, toolkitsOpt }).pipe(
Command.withDescription(
- 'Generate Python type stubs for toolkits, tools, and triggers from the Composio API'
+ 'Generate Python type stubs for toolkits, tools, and triggers from the Composio API.\n\n' +
+ 'Environment Variables:\n' +
+ ' COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)\n' +
+ ' Use "latest" or unset to use the latest version.'
)
);
@@ -65,19 +69,22 @@ export function generatePythonTypeStubs({
// Read toolkit version overrides from environment variables
const versionOverrides = yield* getToolkitVersionOverrides;
- // Log detected overrides for debugging
- if (versionOverrides.size > 0) {
- yield* Console.log('Detected toolkit version overrides:');
- for (const [toolkit, version] of versionOverrides) {
- yield* Console.log(` - ${toolkit}: ${version}`);
- }
- }
+ // Validate toolkit slugs if specified
+ const hasToolkitsFilter = Array.isNonEmptyArray(toolkitsOpt);
+ const toolkitSlugsFilter = hasToolkitsFilter ? toolkitsOpt.map(s => s.toLowerCase()) : null;
+
+ // Validate toolkit version overrides before fetching data
+ // This will log detected overrides, validate them against API, and warn about unused ones
+ const { validatedOverrides } = yield* validateToolkitVersionOverrides({
+ versionOverrides,
+ toolkitSlugsFilter,
+ client,
+ });
// Fetch data from Composio API
yield* Console.log('Fetching latest data from Composio API. This may take a while...');
- // Validate toolkit slugs if specified
- const hasToolkitsFilter = Array.isNonEmptyArray(toolkitsOpt);
+ // Validate toolkit slugs if specified (separate from version validation)
const validatedToolkitSlugs = hasToolkitsFilter
? yield* client
.validateToolkits(toolkitsOpt)
@@ -115,10 +122,10 @@ export function generatePythonTypeStubs({
);
}
- // Build version map for toolkits being generated
+ // Build version map for toolkits being generated (using validated overrides)
const versionMap: ToolkitVersionOverrides = new Map();
for (const toolkit of toolkits) {
- const version = versionOverrides.get(toolkit.slug.toLowerCase() as Lowercase<string>);
+ const version = validatedOverrides.get(toolkit.slug.toLowerCase() as Lowercase<string>);
if (version && version !== 'latest') {
versionMap.set(toolkit.slug.toLowerCase() as Lowercase<string>, version);
}
diff --git a/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts b/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
index 7b4a7eefd..6508fdd21 100644
--- a/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
+++ b/ts/packages/cli/src/commands/ts/commands/ts.generate.cmd.ts
@@ -35,8 +35,10 @@ import type { Tool, ToolsAsEnums } from 'src/models/tools';
import {
getToolkitVersionOverrides,
buildToolkitVersionSpecs,
+ buildVersionMapFromSpecs,
type ToolkitVersionOverrides,
} from 'src/effects/toolkit-version-overrides';
+import { validateToolkitVersionOverrides } from 'src/effects/validate-toolkit-versions';
export const outputOpt = Options.optional(
Options.directory('output-dir', {
@@ -79,7 +81,10 @@ const _tsCmd$Generate = Command.make('generate', {
toolkitsOpt,
}).pipe(
Command.withDescription(
- 'Generate TypeScript types for toolkits, tools, and triggers from the Composio API'
+ 'Generate TypeScript types for toolkits, tools, and triggers from the Composio API.\n\n' +
+ 'Environment Variables:\n' +
+ ' COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)\n' +
+ ' Use "latest" or unset to use the latest version.'
)
);
@@ -113,12 +118,7 @@ function fetchFilteredData(
const versionSpecs = buildToolkitVersionSpecs(slugs, versionOverrides);
// Build the version map (only includes non-'latest' versions from the filtered toolkits)
- const versionMap: ToolkitVersionOverrides = new Map();
- for (const spec of versionSpecs) {
- if (spec.toolkitVersion !== 'latest') {
- versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
- }
- }
+ const versionMap = buildVersionMapFromSpecs(versionSpecs);
const [filteredToolkits, filteredTriggerTypes, filteredTypeableTools] = yield* Effect.all(
[
@@ -249,12 +249,7 @@ function fetchAllDataWithOverrides(
const versionSpecs = buildToolkitVersionSpecs(allSlugs, versionOverrides);
// Build the version map (only includes non-'latest' versions)
- const versionMap: ToolkitVersionOverrides = new Map();
- for (const spec of versionSpecs) {
- if (spec.toolkitVersion !== 'latest') {
- versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
- }
- }
+ const versionMap = buildVersionMapFromSpecs(versionSpecs);
// 3. Fetch trigger types and tools in parallel
const [allTriggerTypes, allTypeableTools] = yield* Effect.all(
@@ -377,23 +372,23 @@ export function generateTypescriptTypeStubs({
// Read toolkit version overrides from environment variables
const versionOverrides = yield* getToolkitVersionOverrides;
- // Log detected overrides for debugging
- if (versionOverrides.size > 0) {
- yield* Console.log('Detected toolkit version overrides:');
- for (const [toolkit, version] of versionOverrides) {
- yield* Console.log(` - ${toolkit}: ${version}`);
- }
- }
-
// Normalize toolkit slugs if specified (lowercase for API filtering)
const toolkitSlugsFilter = Array.isNonEmptyArray(toolkitsOpt)
? toolkitsOpt.map(s => s.toLowerCase())
: null;
+ // Validate toolkit version overrides before fetching data
+ // This will log detected overrides, validate them against API, and warn about unused ones
+ const { validatedOverrides } = yield* validateToolkitVersionOverrides({
+ versionOverrides,
+ toolkitSlugsFilter,
+ client,
+ });
+
// Fetch data using two distinct strategies based on whether --toolkits filter is provided
const { toolkits, triggerTypes, typeableTools, versionMap } = yield* toolkitSlugsFilter !== null
- ? fetchFilteredData(client, toolkitSlugsFilter, typeTools, versionOverrides)
- : fetchAllData(client, typeTools, versionOverrides);
+ ? fetchFilteredData(client, toolkitSlugsFilter, typeTools, validatedOverrides)
+ : fetchAllData(client, typeTools, validatedOverrides);
yield* Console.log('Writing TypeScript type stubs to disk...');
const index = createToolkitIndex({ toolkits, typeableTools, triggerTypes, versionMap });
diff --git a/ts/packages/cli/src/effects/toolkit-version-overrides.ts b/ts/packages/cli/src/effects/toolkit-version-overrides.ts
index 140fe0b2d..6f344c5d4 100644
--- a/ts/packages/cli/src/effects/toolkit-version-overrides.ts
+++ b/ts/packages/cli/src/effects/toolkit-version-overrides.ts
@@ -32,6 +32,32 @@ export const TOOLKIT_VERSION_OVERRIDES_CONFIG = pipe(
*/
export type ToolkitVersionOverrides = Map<Lowercase<string>, string>;
+/**
+ * Regex pattern for valid version strings.
+ * Only allows: alphanumeric characters (a-z, A-Z, 0-9), hyphens, underscores, and dots.
+ */
+const VALID_VERSION_PATTERN = /^[a-zA-Z0-9._-]+$/;
+
+/**
+ * Sanitizes a version string by removing invalid characters.
+ * Only keeps: alphanumeric characters (a-z, A-Z, 0-9), hyphens, underscores, and dots.
+ *
+ * @param version - The version string to sanitize
+ * @returns The sanitized version string, or null if it becomes empty after sanitization
+ */
+export const sanitizeVersionString = (version: string): string | null => {
+ // If the version already matches the valid pattern, return as-is
+ if (VALID_VERSION_PATTERN.test(version)) {
+ return version;
+ }
+
+ // Remove invalid characters
+ const sanitized = version.replace(/[^a-zA-Z0-9._-]/g, '');
+
+ // Return null if the sanitized version is empty
+ return sanitized.length > 0 ? sanitized : null;
+};
+
/**
* Reads toolkit version overrides from environment variables.
*
@@ -61,7 +87,11 @@ export const getToolkitVersionOverrides: Effect.Effect<
for (const [key, value] of HashMap.toEntries(hashMap)) {
// Normalize toolkit name to lowercase and skip 'latest' values
if (value && value !== 'latest') {
- result.set(String.toLowerCase(key), value);
+ // Sanitize version string to only allow valid characters
+ const sanitizedVersion = sanitizeVersionString(value);
+ if (sanitizedVersion) {
+ result.set(String.toLowerCase(key), sanitizedVersion);
+ }
}
}
return result;
@@ -105,8 +135,32 @@ export const groupByVersion = (
): Map<string, Lowercase<string>[]> => {
const grouped = new Map<string, Lowercase<string>[]>();
for (const spec of specs) {
- const existing = grouped.get(spec.toolkitVersion) ?? [];
- grouped.set(spec.toolkitVersion, [...existing, spec.toolkitSlug]);
+ const existing = grouped.get(spec.toolkitVersion);
+ if (existing) {
+ existing.push(spec.toolkitSlug);
+ } else {
+ grouped.set(spec.toolkitVersion, [spec.toolkitSlug]);
+ }
}
return grouped;
};
+
+/**
+ * Builds a ToolkitVersionOverrides map from version specs, excluding 'latest' versions.
+ * This is the single source of truth for building version maps from specs.
+ *
+ * @example
+ * // Given specs: [{ toolkitSlug: 'gmail', toolkitVersion: '20250901_00' }, { toolkitSlug: 'slack', toolkitVersion: 'latest' }]
+ * // Returns: Map { "gmail" => "20250901_00" }
+ */
+export const buildVersionMapFromSpecs = (
+ specs: ReadonlyArray<ToolkitVersionSpec>
+): ToolkitVersionOverrides => {
+ const versionMap = new Map<Lowercase<string>, string>();
+ for (const spec of specs) {
+ if (spec.toolkitVersion !== 'latest') {
+ versionMap.set(spec.toolkitSlug, spec.toolkitVersion);
+ }
+ }
+ return versionMap;
+};
diff --git a/ts/packages/cli/src/effects/validate-toolkit-versions.ts b/ts/packages/cli/src/effects/validate-toolkit-versions.ts
new file mode 100644
index 000000000..70973b505
--- /dev/null
+++ b/ts/packages/cli/src/effects/validate-toolkit-versions.ts
@@ -0,0 +1,190 @@
+import { Console, Effect } from 'effect';
+import colors from 'picocolors';
+import { S_BAR, unicodeOr } from '@clack/prompts';
+import type {
+ ComposioToolkitsRepository,
+ InvalidVersionDetail,
+} from 'src/services/composio-clients';
+import type { ToolkitVersionOverrides } from './toolkit-version-overrides';
+
+/**
+ * Custom error class for invalid toolkit versions that preserves structured data.
+ * This allows consumers to access both the human-readable message and the machine-readable data.
+ */
+export class InvalidToolkitVersionsValidationError extends Error {
+ readonly invalidVersions: ReadonlyArray<InvalidVersionDetail>;
+
+ constructor(invalidVersions: ReadonlyArray<InvalidVersionDetail>) {
+ super(formatInvalidVersionsError(invalidVersions));
+ this.name = 'InvalidToolkitVersionsValidationError';
+ this.invalidVersions = invalidVersions;
+ }
+
+ /**
+ * Returns a JSON-serializable representation of the error for programmatic access.
+ */
+ toJSON(): { error: string; invalidVersions: ReadonlyArray<InvalidVersionDetail> } {
+ return {
+ error: this.name,
+ invalidVersions: this.invalidVersions,
+ };
+ }
+}
+
+const MAX_VERSIONS_TO_SHOW = 5;
+const S_CORNER_TOP_LEFT = unicodeOr('╭', '+');
+const S_CORNER_BOTTOM_LEFT = unicodeOr('╰', '+');
+const S_STEP_ERROR = unicodeOr('▲', 'x');
+
+/**
+ * Formats an InvalidToolkitVersionsError into a user-friendly error message.
+ *
+ * NOTE: We avoid using `: ` (colon-space) in the error message because effect-errors
+ * splits on that pattern and converts the result to an array, which then renders
+ * with commas instead of colons when converted back to string.
+ */
+export function formatInvalidVersionsError(
+ invalidVersions: ReadonlyArray<InvalidVersionDetail>
+): string {
+ const lines: string[] = [];
+
+ // Header
+ lines.push(
+ `${colors.red(S_STEP_ERROR)} ${colors.red('Invalid toolkit version override')}${invalidVersions.length > 1 ? 's' : ''}`
+ );
+ lines.push('');
+
+ for (let i = 0; i < invalidVersions.length; i++) {
+ const { toolkit, requestedVersion, availableVersions } = invalidVersions[i];
+ const isLast = i === invalidVersions.length - 1;
+ const connector = isLast ? S_CORNER_BOTTOM_LEFT : S_BAR;
+
+ // Toolkit header with version
+ lines.push(
+ `${colors.gray(connector)} ${colors.cyan(toolkit.toUpperCase())} ${colors.dim('→')} version ${colors.yellow(`"${requestedVersion}"`)} ${colors.red('not found')}`
+ );
+
+ // Available versions (use → instead of : to avoid effect-errors split issue)
+ if (availableVersions.length === 0) {
+ lines.push(
+ `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('No versions available (toolkit may not support versioning)')}`
+ );
+ } else {
+ const versionsToShow = availableVersions.slice(0, MAX_VERSIONS_TO_SHOW);
+ const remaining = availableVersions.length - MAX_VERSIONS_TO_SHOW;
+
+ let versionList = versionsToShow.map(v => colors.green(v)).join(colors.dim(', '));
+ if (remaining > 0) {
+ versionList += colors.dim(` (+${remaining} more)`);
+ }
+
+ lines.push(
+ `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('Available →')} ${versionList}`
+ );
+ }
+
+ // Tip (use → instead of : to avoid effect-errors split issue)
+ const envVarName = `COMPOSIO_TOOLKIT_VERSION_${toolkit.toUpperCase()}`;
+ lines.push(
+ `${colors.gray(isLast ? ' ' : S_BAR)} ${colors.dim('Tip →')} Use ${colors.cyan('"latest"')} or unset ${colors.cyan(envVarName)}`
+ );
+
+ // Add spacing between toolkits (except for the last one)
+ if (!isLast) {
+ lines.push(colors.gray(S_BAR));
+ }
+ }
+
+ return lines.join('\n');
+}
+
+/**
+ * Options for validateToolkitVersionOverrides
+ */
+export interface ValidateVersionsOptions {
+ /** Map of toolkit slug to requested version */
+ readonly versionOverrides: ToolkitVersionOverrides;
+ /** Optional array of toolkit slugs to filter (from --toolkits flag) */
+ readonly toolkitSlugsFilter: ReadonlyArray<string> | null;
+ /** The ComposioToolkitsRepository client */
+ readonly client: ComposioToolkitsRepository;
+}
+
+/**
+ * Result of version validation
+ */
+export interface ValidateVersionsResult {
+ /** The validated overrides (only includes relevant toolkits) */
+ readonly validatedOverrides: ToolkitVersionOverrides;
+}
+
+/**
+ * Validates toolkit version overrides before fetching data.
+ *
+ * This function should be called early in the generate command flow,
+ * before any tool/trigger data is fetched. It will:
+ * 1. Log detected version overrides
+ * 2. Validate versions against the API's available_versions
+ * 3. Warn about unused overrides (when --toolkits filter excludes them)
+ * 4. Fail with a descriptive error if any versions are invalid
+ *
+ * @example
+ * ```typescript
+ * const { validatedOverrides } = yield* validateToolkitVersionOverrides({
+ * versionOverrides,
+ * toolkitSlugsFilter,
+ * client,
+ * });
+ * ```
+ */
+export const validateToolkitVersionOverrides = ({
+ versionOverrides,
+ toolkitSlugsFilter,
+ client,
+}: ValidateVersionsOptions): Effect.Effect<ValidateVersionsResult, Error> =>
+ Effect.gen(function* () {
+ // Skip if no overrides
+ if (versionOverrides.size === 0) {
+ return { validatedOverrides: versionOverrides };
+ }
+
+ // Log detected overrides
+ yield* Console.log('Detected toolkit version overrides:');
+ for (const [toolkit, version] of versionOverrides) {
+ yield* Console.log(` - ${toolkit}: ${version}`);
+ }
+
+ yield* Console.log('Validating toolkit version overrides...');
+
+ const { validatedOverrides, warnings } = yield* client
+ .validateToolkitVersions(versionOverrides, toolkitSlugsFilter ?? undefined)
+ .pipe(
+ Effect.catchTag('services/InvalidToolkitVersionsError', error =>
+ Effect.fail(new InvalidToolkitVersionsValidationError(error.invalidVersions))
+ ),
+ Effect.catchTag('services/InvalidToolkitsError', error =>
+ Effect.fail(
+ new Error(
+ `Invalid toolkit(s) in version overrides: ${error.invalidToolkits.join(', ')}. ` +
+ `Check that the toolkit slug is correct (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL, not COMPOSIO_TOOLKIT_VERSION_GMAL).`
+ )
+ )
+ ),
+ Effect.catchTag('services/HttpServerError', error =>
+ Effect.fail(new Error(`Failed to validate toolkit versions: ${error.cause}`))
+ ),
+ Effect.catchTag('services/HttpDecodingError', error =>
+ Effect.fail(new Error(`Failed to decode toolkit response: ${error.cause}`))
+ ),
+ Effect.catchTag('NoSuchElementException', () =>
+ Effect.fail(new Error('API client not initialized'))
+ )
+ );
+
+ // Log warnings for unused overrides
+ for (const warning of warnings) {
+ yield* Console.warn(`Warning: ${warning}`);
+ }
+
+ return { validatedOverrides };
+ });
diff --git a/ts/packages/cli/src/models/toolkits.ts b/ts/packages/cli/src/models/toolkits.ts
index 0643c480f..3df5b7328 100644
--- a/ts/packages/cli/src/models/toolkits.ts
+++ b/ts/packages/cli/src/models/toolkits.ts
@@ -12,6 +12,7 @@ export const Toolkit = Schema.Struct({
categories: Schema.Array(Schema.Unknown),
created_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
updated_at: Schema.DateTimeUtc, // "2024-05-03T11:44:32.061Z"
+ available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
}),
no_auth: Schema.Boolean,
}).annotations({ identifier: 'Toolkit' });
diff --git a/ts/packages/cli/src/services/composio-clients-cached.ts b/ts/packages/cli/src/services/composio-clients-cached.ts
index 39e8f7e00..583d6b937 100644
--- a/ts/packages/cli/src/services/composio-clients-cached.ts
+++ b/ts/packages/cli/src/services/composio-clients-cached.ts
@@ -232,6 +232,12 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
validateToolkits: toolkitSlugs => underlyingRepository.validateToolkits(toolkitSlugs),
filterToolkitsBySlugs: (toolkits, toolkitSlugs) =>
underlyingRepository.filterToolkitsBySlugs(toolkits, toolkitSlugs),
+ // Version validation should NOT be cached because:
+ // 1. available_versions can change frequently as new versions are released
+ // 2. Validation should always reflect the current API state
+ // 3. Caching validation results could cause false positives/negatives
+ validateToolkitVersions: (overrides, relevantToolkits) =>
+ underlyingRepository.validateToolkitVersions(overrides, relevantToolkits),
});
})
).pipe(
diff --git a/ts/packages/cli/src/services/composio-clients.ts b/ts/packages/cli/src/services/composio-clients.ts
index b09b06cb2..598e617c2 100644
--- a/ts/packages/cli/src/services/composio-clients.ts
+++ b/ts/packages/cli/src/services/composio-clients.ts
@@ -15,7 +15,11 @@ import {
import { Composio as _RawComposioClient, APIPromise } from '@composio/client';
import { Toolkit, Toolkits } from 'src/models/toolkits';
import { ToolsAsEnums, Tools, Tool } from 'src/models/tools';
-import { groupByVersion, type ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
+import {
+ groupByVersion,
+ type ToolkitVersionSpec,
+ type ToolkitVersionOverrides,
+} from 'src/effects/toolkit-version-overrides';
import { Session, RetrievedSession } from 'src/models/session';
import { TriggerType, TriggerTypes, TriggerTypesAsEnums } from 'src/models/trigger-types';
import { ComposioUserContext, ComposioUserContextLive } from './user-context';
@@ -42,6 +46,24 @@ export class InvalidToolkitsError extends Data.TaggedError('services/InvalidTool
readonly availableToolkits: ReadonlyArray<string>;
}> {}
+/**
+ * Details about a single invalid version override.
+ */
+export interface InvalidVersionDetail {
+ readonly toolkit: string;
+ readonly requestedVersion: string;
+ readonly availableVersions: ReadonlyArray<string>;
+}
+
+/**
+ * Error thrown when one or more toolkit version overrides are invalid.
+ */
+export class InvalidToolkitVersionsError extends Data.TaggedError(
+ 'services/InvalidToolkitVersionsError'
+)<{
+ readonly invalidVersions: ReadonlyArray<InvalidVersionDetail>;
+}> {}
+
/**
* Error thrown when a HTTP response doesn't match the expected response schema.
*/
@@ -51,6 +73,131 @@ export class HttpDecodingError extends Data.TaggedError('services/HttpDecodingEr
export type HttpError = HttpServerError | HttpDecodingError;
+const validateToolkitVersionsImpl = (
+ client: {
+ toolkits: {
+ retrieve: (slug: string) => Effect.Effect<Toolkit, HttpError | NoSuchElementException, never>;
+ };
+ },
+ overrides: ToolkitVersionOverrides,
+ relevantToolkits?: ReadonlyArray<string>
+): Effect.Effect<
+ {
+ validatedOverrides: ToolkitVersionOverrides;
+ warnings: ReadonlyArray<string>;
+ },
+ InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
+> =>
+ Effect.gen(function* () {
+ const determineOverridesToValidate = (
+ overrides: ToolkitVersionOverrides,
+ relevantToolkits?: ReadonlyArray<string>
+ ): {
+ overridesToValidate: Array<[toolkit: string, requestedVersion: string]>;
+ warnings: Array<string>;
+ } => {
+ const warnings: string[] = [];
+ const overridesToValidate: Array<[toolkit: string, requestedVersion: string]> = [];
+
+ if (relevantToolkits) {
+ const relevantSet = new Set(relevantToolkits.map(s => String.toLowerCase(s)));
+
+ for (const [toolkit, version] of overrides) {
+ if (relevantSet.has(toolkit)) {
+ overridesToValidate.push([toolkit, version]);
+ } else {
+ warnings.push(
+ `Version override for "${toolkit}" will be ignored (toolkit not in --toolkits filter)`
+ );
+ }
+ }
+ } else {
+ overridesToValidate.push(...overrides.entries());
+ }
+
+ return { overridesToValidate, warnings };
+ };
+
+ const fetchToolkitVersionValidationResults = (
+ overridesToValidate: ReadonlyArray<[toolkit: string, requestedVersion: string]>
+ ): Effect.Effect<
+ ReadonlyArray<{
+ toolkit: string;
+ requestedVersion: string;
+ availableVersions: ReadonlyArray<string>;
+ isValid: boolean;
+ }>,
+ InvalidToolkitsError | HttpError | NoSuchElementException
+ > =>
+ Effect.all(
+ overridesToValidate.map(([toolkit, requestedVersion]) =>
+ client.toolkits.retrieve(toolkit).pipe(
+ Effect.map(toolkitData => ({
+ toolkit,
+ requestedVersion,
+ availableVersions: toolkitData.meta.available_versions,
+ isValid: toolkitData.meta.available_versions.includes(requestedVersion),
+ })),
+ Effect.catchTag('services/HttpServerError', e =>
+ Effect.if(e.status === 404, {
+ onTrue: () =>
+ Effect.fail(
+ new InvalidToolkitsError({
+ invalidToolkits: [toolkit],
+ availableToolkits: [],
+ })
+ ),
+ onFalse: () => Effect.fail(e),
+ })
+ )
+ )
+ ),
+ { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
+ );
+
+ const collectInvalidVersions = (
+ validationResults: ReadonlyArray<{
+ toolkit: string;
+ requestedVersion: string;
+ availableVersions: ReadonlyArray<string>;
+ isValid: boolean;
+ }>
+ ): ReadonlyArray<InvalidVersionDetail> =>
+ validationResults
+ .filter(result => !result.isValid)
+ .map(result => ({
+ toolkit: result.toolkit,
+ requestedVersion: result.requestedVersion,
+ availableVersions: result.availableVersions,
+ }));
+
+ if (overrides.size === 0) {
+ return { validatedOverrides: overrides, warnings: [] as ReadonlyArray<string> };
+ }
+
+ const { overridesToValidate, warnings } = determineOverridesToValidate(
+ overrides,
+ relevantToolkits
+ );
+
+ if (overridesToValidate.length === 0) {
+ return {
+ validatedOverrides: new Map() as ToolkitVersionOverrides,
+ warnings: warnings as ReadonlyArray<string>,
+ };
+ }
+
+ const validationResults = yield* fetchToolkitVersionValidationResults(overridesToValidate);
+ const invalidVersions = collectInvalidVersions(validationResults);
+
+ if (invalidVersions.length > 0) {
+ return yield* Effect.fail(new InvalidToolkitVersionsError({ invalidVersions }));
+ }
+
+ const validatedOverrides = new Map(overridesToValidate) as ToolkitVersionOverrides;
+ return { validatedOverrides, warnings: warnings as ReadonlyArray<string> };
+ });
+
/**
* Response schemas
*/
@@ -82,6 +229,7 @@ export const ToolkitRetrieveResponse = Schema.Struct({
categories: Schema.optionalWith(Schema.Array(Schema.Unknown), { default: () => [] }),
created_at: Schema.DateTimeUtc,
updated_at: Schema.DateTimeUtc,
+ available_versions: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
}),
}).annotations({ identifier: 'ToolkitRetrieveResponse' });
export type ToolkitRetrieveResponse = Schema.Schema.Type<typeof ToolkitRetrieveResponse>;
@@ -531,32 +679,36 @@ export class ComposioClientLive extends Effect.Service<ComposioClientLive>()(
),
/**
* Retrieve tools for multiple toolkits, grouped by version.
- * Makes separate API calls for each version group, then merges results.
+ * Makes parallel API calls for each version group, then merges results.
* @param specs - Array of toolkit version specifications
*/
listByVersionSpecs: (specs: ReadonlyArray<ToolkitVersionSpec>) =>
Effect.gen(function* () {
const grouped = groupByVersion(specs);
- const allTools: Tool[] = [];
-
- for (const [version, slugs] of grouped) {
- // Fetch all toolkits with same version in one call
- const response = yield* withMetrics(
- callClientWithPagination(
- clientSingleton,
- (client, cursor, limit) =>
- client.tools.list({
- cursor,
- toolkit_slug: slugs.join(','),
- toolkit_versions: version,
- limit,
- }),
- ToolsResponse
+ const versionGroups = [...grouped.entries()];
+
+ // Fetch all version groups in parallel with bounded concurrency
+ const responses = yield* Effect.all(
+ versionGroups.map(([version, slugs]) =>
+ withMetrics(
+ callClientWithPagination(
+ clientSingleton,
+ (client, cursor, limit) =>
+ client.tools.list({
+ cursor,
+ toolkit_slug: slugs.join(','),
+ toolkit_versions: version,
+ limit,
+ }),
+ ToolsResponse
+ )
)
- );
- allTools.push(...response.items);
- }
+ ),
+ { concurrency: MAX_CONCURRENT_REQUESTS_PER_ENDPOINT }
+ );
+ // Merge all tools from all version groups
+ const allTools = responses.flatMap(response => response.items);
return { items: allTools };
}),
},
@@ -781,6 +933,24 @@ export class ComposioToolkitsRepository extends Effect.Service<ComposioToolkitsR
const normalizedSlugs = new Set(toolkitSlugs.map(slug => String.toLowerCase(slug)));
return toolkits.filter(toolkit => normalizedSlugs.has(String.toLowerCase(toolkit.slug)));
},
+ /**
+ * Validates that the requested toolkit versions exist in the API's available_versions.
+ * Makes parallel API calls to fetch toolkit metadata for validation.
+ *
+ * @param overrides - Map of toolkit slug to requested version
+ * @param relevantToolkits - Optional array of toolkit slugs to validate (if --toolkits filter is used)
+ * @returns Effect that succeeds with the validated overrides and warnings, or fails with InvalidToolkitVersionsError
+ */
+ validateToolkitVersions: (
+ overrides: ToolkitVersionOverrides,
+ relevantToolkits?: ReadonlyArray<string>
+ ): Effect.Effect<
+ {
+ validatedOverrides: ToolkitVersionOverrides;
+ warnings: ReadonlyArray<string>;
+ },
+ InvalidToolkitVersionsError | InvalidToolkitsError | HttpError | NoSuchElementException
+ > => validateToolkitVersionsImpl(client, overrides, relevantToolkits),
};
}),
dependencies: [ComposioClientLive.Default],
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index cba9d19dd..ef4c21d20 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -23,7 +23,10 @@ import {
ComposioSessionRepository,
ComposioToolkitsRepository,
InvalidToolkitsError,
+ InvalidToolkitVersionsError,
+ type InvalidVersionDetail,
} from 'src/services/composio-clients';
+import type { ToolkitVersionOverrides } from 'src/effects/toolkit-version-overrides';
import { EnvLangDetector } from 'src/services/env-lang-detector';
import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
import type { Tools } from 'src/models/tools';
@@ -160,6 +163,55 @@ export const TestLayer = (input?: TestLiveInput) =>
);
return Effect.succeed(tools);
},
+ validateToolkitVersions: (
+ overrides: ToolkitVersionOverrides,
+ relevantToolkits?: ReadonlyArray<string>
+ ) => {
+ // Mock implementation that validates against test fixture
+ const invalidVersions: InvalidVersionDetail[] = [];
+ const warnings: string[] = [];
+
+ for (const [toolkit, version] of overrides) {
+ // Check if toolkit should be validated
+ if (relevantToolkits && !relevantToolkits.map(s => s.toLowerCase()).includes(toolkit)) {
+ warnings.push(`Version override for "${toolkit}" will be ignored`);
+ continue;
+ }
+
+ // Check if toolkit exists in the fixture
+ const toolkitExists = toolkitsData.toolkits.some(
+ t => String.toLowerCase(t.slug) === toolkit
+ );
+
+ if (!toolkitExists) {
+ return Effect.fail(
+ new InvalidToolkitsError({
+ invalidToolkits: [toolkit],
+ availableToolkits: toolkitsData.toolkits.map(t => t.slug),
+ })
+ );
+ }
+
+ // Mock: only accept 'latest' or versions matching pattern YYYYMMDD_NN
+ const validPattern = /^\d{8}_\d{2}$/;
+ if (version !== 'latest' && !validPattern.test(version)) {
+ invalidVersions.push({
+ toolkit,
+ requestedVersion: version,
+ availableVersions: ['20250901_00', '20250815_00', '20250710_00'],
+ });
+ }
+ }
+
+ if (invalidVersions.length > 0) {
+ return Effect.fail(new InvalidToolkitVersionsError({ invalidVersions }));
+ }
+
+ return Effect.succeed({
+ validatedOverrides: overrides,
+ warnings: warnings as ReadonlyArray<string>,
+ });
+ },
})
);
const ComposioSessionRepositoryTest = yield* setupComposioSessionRepository();
diff --git a/ts/packages/cli/test/src/commands/$default.cmd.test.ts b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
index b9f79d135..d203bf9a3 100644
--- a/ts/packages/cli/test/src/commands/$default.cmd.test.ts
+++ b/ts/packages/cli/test/src/commands/$default.cmd.test.ts
@@ -72,11 +72,19 @@ describe('CLI: composio', () => {
- py Handle Python projects.
- - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API
+ - py generate [(-o, --output-dir directory)] --toolkits text... Generate Python type stubs for toolkits, tools, and triggers from the Composio API.
+
+ Environment Variables:
+ COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
+ Use "latest" or unset to use the latest version.
- ts Handle TypeScript projects.
- - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API
+ - ts generate [(-o, --output-dir directory)] [--compact] [--transpiled] [--type-tools] --toolkits text... Generate TypeScript types for toolkits, tools, and triggers from the Composio API.
+
+ Environment Variables:
+ COMPOSIO_TOOLKIT_VERSION_<TOOLKIT> Override toolkit version (e.g., COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00)
+ Use "latest" or unset to use the latest version.
"
`);
})
diff --git a/ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts b/ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts
index 4094c6b8d..e71f872bb 100644
--- a/ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts
+++ b/ts/packages/cli/test/src/effects/toolkit-version-overrides.test.ts
@@ -4,6 +4,8 @@ import {
getToolkitVersionOverrides,
buildToolkitVersionSpecs,
groupByVersion,
+ sanitizeVersionString,
+ buildVersionMapFromSpecs,
type ToolkitVersionOverrides,
type ToolkitVersionSpec,
} from 'src/effects/toolkit-version-overrides';
@@ -202,4 +204,100 @@ describe('toolkit-version-overrides', () => {
expect(grouped.get('latest')).toEqual(['gmail', 'slack', 'github', 'notion']);
});
});
+
+ describe('sanitizeVersionString', () => {
+ it('should return valid version strings unchanged', () => {
+ expect(sanitizeVersionString('20250901_00')).toBe('20250901_00');
+ expect(sanitizeVersionString('v1.2.3')).toBe('v1.2.3');
+ expect(sanitizeVersionString('latest')).toBe('latest');
+ expect(sanitizeVersionString('1.0.0-beta.1')).toBe('1.0.0-beta.1');
+ });
+
+ it('should remove invalid characters', () => {
+ expect(sanitizeVersionString('20250901_00!')).toBe('20250901_00');
+ expect(sanitizeVersionString('version@123')).toBe('version123');
+ expect(sanitizeVersionString('v1.2.3#tag')).toBe('v1.2.3tag');
+ });
+
+ it('should handle unicode and special characters', () => {
+ expect(sanitizeVersionString('版本1.0')).toBe('1.0');
+ expect(sanitizeVersionString('v1.0\n\t')).toBe('v1.0');
+ expect(sanitizeVersionString('$version$')).toBe('version');
+ });
+
+ it('should return null for empty or all-invalid strings', () => {
+ expect(sanitizeVersionString('')).toBe(null);
+ expect(sanitizeVersionString('$$$')).toBe(null);
+ expect(sanitizeVersionString(' ')).toBe(null);
+ });
+
+ it('should allow alphanumeric, hyphens, underscores, and dots', () => {
+ expect(sanitizeVersionString('abc-123_456.789')).toBe('abc-123_456.789');
+ expect(sanitizeVersionString('ABC-XYZ_000.999')).toBe('ABC-XYZ_000.999');
+ });
+ });
+
+ describe('buildVersionMapFromSpecs', () => {
+ it('should build version map excluding latest versions', () => {
+ const specs: ToolkitVersionSpec[] = [
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
+ { toolkitSlug: 'github', toolkitVersion: '20250815_00' },
+ ];
+ const versionMap = buildVersionMapFromSpecs(specs);
+
+ expect(versionMap.size).toBe(2);
+ expect(versionMap.get('gmail')).toBe('20250901_00');
+ expect(versionMap.get('github')).toBe('20250815_00');
+ expect(versionMap.has('slack')).toBe(false);
+ });
+
+ it('should return empty map when all versions are latest', () => {
+ const specs: ToolkitVersionSpec[] = [
+ { toolkitSlug: 'gmail', toolkitVersion: 'latest' },
+ { toolkitSlug: 'slack', toolkitVersion: 'latest' },
+ ];
+ const versionMap = buildVersionMapFromSpecs(specs);
+
+ expect(versionMap.size).toBe(0);
+ });
+
+ it('should return empty map for empty specs', () => {
+ const versionMap = buildVersionMapFromSpecs([]);
+ expect(versionMap.size).toBe(0);
+ });
+
+ it('should include all non-latest versions', () => {
+ const specs: ToolkitVersionSpec[] = [
+ { toolkitSlug: 'gmail', toolkitVersion: '20250901_00' },
+ { toolkitSlug: 'slack', toolkitVersion: '20250815_00' },
+ { toolkitSlug: 'github', toolkitVersion: '20250710_00' },
+ ];
+ const versionMap = buildVersionMapFromSpecs(specs);
+
+ expect(versionMap.size).toBe(3);
+ expect(versionMap.get('gmail')).toBe('20250901_00');
+ expect(versionMap.get('slack')).toBe('20250815_00');
+ expect(versionMap.get('github')).toBe('20250710_00');
+ });
+ });
+
+ describe('getToolkitVersionOverrides with sanitization', () => {
+ it.effect('should sanitize version strings with invalid characters', () =>
+ Effect.gen(function* () {
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '20250901_00!@#');
+ const result = yield* getToolkitVersionOverrides;
+ expect(result.get('gmail')).toBe('20250901_00');
+ expect(result.size).toBe(1);
+ })
+ );
+
+ it.effect('should ignore version strings that become empty after sanitization', () =>
+ Effect.gen(function* () {
+ vi.stubEnv('COMPOSIO_TOOLKIT_VERSION_GMAIL', '$$$');
+ const result = yield* getToolkitVersionOverrides;
+ expect(result.size).toBe(0);
+ })
+ );
+ });
});