Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdcnew file mode 100644index 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.tsindex 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 variablesconst 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 APIyield* 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.tsindex 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 parallelconst [allTriggerTypes, allTypeableTools] = yield* Effect.all(@@ -377,23 +372,23 @@ export function generateTypescriptTypeStubs({// Read toolkit version overrides from environment variablesconst 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 providedconst { 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.tsindex 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' valuesif (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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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/InvalidToolreadonly 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/HttpDecodingErexport 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<ComposioToolkitsRconst 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.tsindex 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.tsindex 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.tsindex 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);+ })+ );+ });});