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.

Add discriminated unions for get tools

haxzie93b9c69c8444
diff --git a/docs/api/tools.md b/docs/api/tools.md
index e346f0880..04171d72f 100644
--- a/docs/api/tools.md
+++ b/docs/api/tools.md
@@ -175,14 +175,69 @@ const tool = await composio.tools.getRawComposioToolBySlug('default', 'github');
### ToolListParams
```typescript
-interface ToolListParams {
- tools?: string[]; // List of tool slugs to filter by
+// You must provide one of the following parameter combinations:
+// 1. tools array only
+// 2. toolkits with optional important flag
+// 3. toolkits with search functionality
+
+type ToolsOnlyParams = {
+ tools: string[]; // List of tool slugs to filter by
+ toolkits?: never; // Cannot be used with tools
+ important?: never;
+ cursor?: never;
+ limit?: never;
+ search?: never;
+};
+
+type ToolkitsOnlyParams = {
+ tools?: never; // Cannot be used with toolkits
+ toolkits: string[]; // List of toolkit slugs to filter by
+ important?: boolean; // Filter for important tools
cursor?: string; // Pagination cursor
- important?: string; // Filter for important tools
- limit?: string; // Limit the number of results
- search?: string; // Search term
- toolkits?: string[]; // List of toolkit slugs to filter by
-}
+ limit?: number; // Limit the number of results
+ search?: never; // Cannot be used with important flag
+};
+
+type ToolkitSearchOnlyParams = {
+ tools?: never; // Cannot be used with search
+ toolkits?: string[]; // Optional list of toolkit slugs to filter by
+ important?: never; // Cannot be used with search
+ cursor?: string; // Pagination cursor
+ limit?: number; // Limit the number of results
+ search: string; // Search term
+};
+
+type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitSearchOnlyParams;
+```
+
+Note: The parameters are organized into three mutually exclusive combinations:
+
+1. Using `tools` array to fetch specific tools by their slugs
+2. Using `toolkits` with optional `important` flag to fetch tools from specific toolkits
+3. Using `search` with optional `toolkits` to search for tools by name/description
+
+Examples:
+
+```typescript
+// Get specific tools by slug
+const specificTools = await composio.tools.get('default', {
+ tools: ['GITHUB_GET_REPO', 'GITHUB_LIST_ISSUES'],
+});
+
+// Get all tools from specific toolkits
+const toolkitTools = await composio.tools.get('default', {
+ toolkits: ['github', 'gitlab'],
+ important: true,
+ limit: 10,
+});
+
+// Search for tools across all or specific toolkits
+const searchResults = await composio.tools.get('default', {
+ search: 'repository',
+ toolkits: ['github'], // optional
+ limit: 10,
+ cursor: 'next-page',
+});
```
### ToolExecuteParams
diff --git a/packages/core/src/models/CustomTools.ts b/packages/core/src/models/CustomTools.ts
index 0f3fc654f..5790606d9 100644
--- a/packages/core/src/models/CustomTools.ts
+++ b/packages/core/src/models/CustomTools.ts
@@ -70,7 +70,7 @@ export class CustomTools {
outputParameters: {
type: 'object',
title: `Response for ${name}`,
- properties: [],
+ properties: {},
},
tags: [],
toolkit: { name: 'custom', slug: 'custom' },
diff --git a/packages/core/src/models/Tools.ts b/packages/core/src/models/Tools.ts
index e70d981cd..7ac3d80c0 100644
--- a/packages/core/src/models/Tools.ts
+++ b/packages/core/src/models/Tools.ts
@@ -248,28 +248,47 @@ export class Tools<
*/
async getRawComposioTools(
userId: string,
- query: ToolListParams = {},
+ query: ToolListParams,
modifier?: TransformToolSchemaModifier
): Promise<ToolList> {
+ if ('tools' in query && 'toolkits' in query) {
+ throw new ValidationError(
+ 'Invalid tool list parameters. You should not use tools and toolkits filter together.'
+ );
+ }
+
const queryParams = ToolListParamsSchema.safeParse(query);
if (queryParams.error) {
throw new ValidationError('Invalid tool list parameters', {
cause: queryParams.error,
});
}
+ // check if the query params contains atleast one of the following: tools, toolkits, search
+ if (
+ !(
+ 'tools' in queryParams.data ||
+ 'toolkits' in queryParams.data ||
+ 'search' in queryParams.data
+ )
+ ) {
+ throw new ValidationError(
+ 'Invalid tool list parameters, atleast one of the following parameters is required: tools, toolkits, search'
+ );
+ }
const tools = await this.client.tools.list({
- tool_slugs: queryParams.data.tools?.join(','),
- toolkit_slug: queryParams.data.toolkits?.join(','),
- cursor: queryParams.data.cursor,
+ tool_slugs: 'tools' in queryParams.data ? queryParams.data.tools?.join(',') : undefined,
+ toolkit_slug:
+ 'toolkits' in queryParams.data ? queryParams.data.toolkits?.join(',') : undefined,
+ cursor: 'cursor' in queryParams.data ? queryParams.data.cursor : undefined,
important:
- typeof queryParams.data.important === 'undefined'
- ? undefined
- : queryParams.data.important
+ 'important' in queryParams.data
+ ? queryParams.data.important
? 'true'
- : 'false',
- limit: queryParams.data.limit?.toString(),
- search: queryParams.data.search,
+ : 'false'
+ : undefined,
+ limit: 'limit' in queryParams.data ? queryParams.data.limit?.toString() : undefined,
+ search: 'search' in queryParams.data ? queryParams.data.search : undefined,
});
if (!tools) {
@@ -285,7 +304,7 @@ export class Tools<
// console.warn('No connected accounts found for the given tools');
// }
const customTools = await this.customTools.getCustomTools({
- toolSlugs: queryParams.data.tools,
+ toolSlugs: 'tools' in queryParams.data ? queryParams.data.tools : undefined,
});
let modifiedTools = [...caseTransformedTools, ...customTools];
diff --git a/packages/core/src/types/tool.types.ts b/packages/core/src/types/tool.types.ts
index eb97f48a2..aad49ef63 100644
--- a/packages/core/src/types/tool.types.ts
+++ b/packages/core/src/types/tool.types.ts
@@ -78,18 +78,65 @@ export type ToolListResponse = z.infer<typeof ToolListResponseSchema>;
*/
export type ToolList = Array<Tool>;
-/**
- * ToolListParams is the parameters for the list of tools.
- */
-export const ToolListParamsSchema = z.object({
- tools: z.array(z.string()).optional(),
- cursor: z.string().optional(),
+export const ToolListFilterByToolsSchema = z.object({
+ tools: z.array(z.string()),
+});
+export type ToolListFilterByTools = z.infer<typeof ToolListFilterByToolsSchema>;
+
+export const ToolListFilterByToolkitsSchema = z.object({
+ toolkits: z.array(z.string()),
important: z.boolean().optional(),
+ cursor: z.string().optional(),
limit: z.number().optional(),
search: z.string().optional(),
+});
+export type ToolListFilterByToolkits = z.infer<typeof ToolListFilterByToolkitsSchema>;
+
+export const ToolListFilterBySearchSchema = z.object({
+ search: z.string(),
toolkits: z.array(z.string()).optional(),
+ cursor: z.string().optional(),
+ limit: z.number().optional(),
});
-export type ToolListParams = z.infer<typeof ToolListParamsSchema>;
+export type ToolListFilterBySearch = z.infer<typeof ToolListFilterBySearchSchema>;
+
+type ToolsOnlyParams = {
+ tools: string[];
+ toolkits?: never;
+ important?: never;
+ cursor?: never;
+ limit?: never;
+ search?: never;
+};
+
+type ToolkitsOnlyParams = {
+ tools?: never;
+ toolkits?: string[];
+ important?: boolean;
+ cursor?: string;
+ limit?: number;
+ search?: never;
+};
+
+type ToolkitSearchOnlyParams = {
+ tools?: never;
+ toolkits?: string[];
+ important?: never;
+ cursor?: string;
+ limit?: number;
+ search?: string;
+};
+/**
+ * ToolListParams is the parameters for the list of tools.
+ * You must provide either tools or toolkits, but not both.
+ */
+export type ToolListParams = ToolsOnlyParams | ToolkitsOnlyParams | ToolkitSearchOnlyParams;
+
+export const ToolListParamsSchema = z.union([
+ ToolListFilterByToolsSchema,
+ ToolListFilterByToolkitsSchema,
+ ToolListFilterBySearchSchema,
+]);
/**
* CustomAuthParams is the parameters for the custom authentication.
diff --git a/packages/core/test/tools/modifiers.test.ts b/packages/core/test/tools/modifiers.test.ts
index 91b81345d..d360a1b3d 100644
--- a/packages/core/test/tools/modifiers.test.ts
+++ b/packages/core/test/tools/modifiers.test.ts
@@ -53,7 +53,11 @@ describe('Tools Modifiers', () => {
totalPages: 1,
});
- const result = await context.tools.getRawComposioTools(userId, {}, schemaModifier);
+ const result = await context.tools.getRawComposioTools(
+ userId,
+ { tools: ['TOOL1', 'TOOL2'] },
+ schemaModifier
+ );
expect(schemaModifier).toHaveBeenCalledTimes(2);
expect(result[0].name).toContain('Modified');
diff --git a/packages/core/test/tools/tools.test.ts b/packages/core/test/tools/tools.test.ts
index ad279b170..26b04b96c 100644
--- a/packages/core/test/tools/tools.test.ts
+++ b/packages/core/test/tools/tools.test.ts
@@ -10,6 +10,7 @@ import {
mockToolExecution,
createSchemaModifier,
} from '../utils/toolExecuteUtils';
+import { ValidationError } from '../../src/errors/ValidationErrors';
describe('Tools', () => {
const context = createTestContext();
@@ -42,7 +43,7 @@ describe('Tools', () => {
totalPages: 1,
});
- const result = await context.tools.getRawComposioTools(userId);
+ const result = await context.tools.getRawComposioTools(userId, { tools: ['TEST_TOOL'] });
expect(mockClient.tools.list).toHaveBeenCalledTimes(1);
expect(result).toHaveLength(1);
@@ -54,7 +55,6 @@ describe('Tools', () => {
const userId = 'test-user';
const query = {
tools: ['TOOL1', 'TOOL2'],
- limit: 10,
};
mockClient.tools.list.mockResolvedValueOnce({
@@ -66,7 +66,7 @@ describe('Tools', () => {
expect(mockClient.tools.list).toHaveBeenCalledWith({
tool_slugs: 'TOOL1,TOOL2',
- limit: '10',
+ limit: undefined,
cursor: undefined,
important: undefined,
search: undefined,
@@ -74,6 +74,57 @@ describe('Tools', () => {
});
});
+ it('should handle toolkit query parameters correctly', async () => {
+ const userId = 'test-user';
+ const query = {
+ toolkits: ['github'],
+ limit: 10,
+ important: true,
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(userId, query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ tool_slugs: undefined,
+ toolkit_slug: 'github',
+ limit: '10',
+ cursor: undefined,
+ important: 'true',
+ search: undefined,
+ });
+ });
+
+ it('should handle toolkit search parameters correctly', async () => {
+ const userId = 'test-user';
+ const query = {
+ toolkits: ['github'],
+ search: 'test',
+ limit: 10,
+ cursor: 'next-page',
+ };
+
+ mockClient.tools.list.mockResolvedValueOnce({
+ items: [toolMocks.rawTool],
+ totalPages: 1,
+ });
+
+ await context.tools.getRawComposioTools(userId, query);
+
+ expect(mockClient.tools.list).toHaveBeenCalledWith({
+ tool_slugs: undefined,
+ toolkit_slug: 'github',
+ limit: '10',
+ cursor: 'next-page',
+ important: undefined,
+ search: 'test',
+ });
+ });
+
it('should transform tool case correctly', async () => {
const userId = 'test-user';
@@ -82,7 +133,7 @@ describe('Tools', () => {
totalPages: 1,
});
- const result = await context.tools.getRawComposioTools(userId);
+ const result = await context.tools.getRawComposioTools(userId, { tools: ['TEST_TOOL'] });
expect(result[0].inputParameters).toEqual(toolMocks.transformedTool.inputParameters);
expect(result[0].outputParameters).toEqual(toolMocks.transformedTool.outputParameters);
@@ -99,7 +150,7 @@ describe('Tools', () => {
const getCustomToolsSpy = vi.spyOn(context.tools['customTools'], 'getCustomTools');
getCustomToolsSpy.mockResolvedValueOnce([toolMocks.customTool as unknown as Tool]);
- const result = await context.tools.getRawComposioTools(userId);
+ const result = await context.tools.getRawComposioTools(userId, { tools: ['TEST_TOOL'] });
expect(result).toHaveLength(2);
expect(result[1].slug).toEqual(toolMocks.customTool.slug);
@@ -116,7 +167,11 @@ describe('Tools', () => {
totalPages: 1,
});
- const result = await context.tools.getRawComposioTools(userId, {}, schemaModifier);
+ const result = await context.tools.getRawComposioTools(
+ userId,
+ { tools: ['TEST_TOOL'] },
+ schemaModifier
+ );
expect(schemaModifier).toHaveBeenCalled();
expect(result[0].description).toEqual('Modified description');
@@ -131,8 +186,35 @@ describe('Tools', () => {
totalPages: 1,
});
- await expect(context.tools.getRawComposioTools(userId, {}, invalidModifier)).rejects.toThrow(
- 'Invalid schema modifier. Not a function.'
+ await expect(
+ context.tools.getRawComposioTools(
+ userId,
+ {
+ toolkits: ['invalid'],
+ },
+ invalidModifier
+ )
+ ).rejects.toThrow('Invalid schema modifier. Not a function.');
+ });
+
+ it('should throw a validation error when both tools and toolkits are provided', async () => {
+ const userId = 'test-user';
+ const invalidQuery = {
+ tools: ['TOOL1'],
+ toolkits: ['github'],
+ } as any;
+
+ await expect(context.tools.getRawComposioTools(userId, invalidQuery)).rejects.toThrow(
+ 'Invalid tool list parameters'
+ );
+ });
+
+ it('should throw a validation error when no required parameters are provided', async () => {
+ const userId = 'test-user';
+ const emptyQuery = {} as any;
+
+ await expect(context.tools.getRawComposioTools(userId, emptyQuery)).rejects.toThrow(
+ ValidationError
);
});
});