@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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

Synced Nov 21, 04:45 UTC

next
ts 269 lines 9.67 KB
Raw
1 /**
2 * @fileoverview `composio.customToolkits`: register and manage
3 * project-owned custom toolkits.
4 *
5 * @module CustomToolkits
6 */
7 import ComposioClient from '@composio/client';
8 import {
9 CustomToolkitCreateParams,
10 CustomToolkitCreateParamsSchema,
11 CustomToolkitCreateResponse,
12 CustomToolkitDeleteResponse,
13 CustomToolkitSyncParams,
14 CustomToolkitSyncParamsSchema,
15 CustomToolkitSyncResponse,
16 CustomToolkitUpdateParams,
17 CustomToolkitUpdateParamsSchema,
18 CustomToolkitUpdateResponse,
19 CustomToolkitUpsertParams,
20 CustomToolkitUpsertParamsSchema,
21 CustomToolkitUpsertResponse,
22 } from '../types/customToolkits.types';
23 import { ComposioRequestOptions } from '../types/requestOptions.types';
24 import { ValidationError } from '../errors/ValidationErrors';
25 import { telemetry } from '../telemetry/Telemetry';
26 import { withCancellation } from '../utils/cancellation';
27 import logger from '../utils/logger';
28 import {
29 transformCustomToolkitCreateParams,
30 transformCustomToolkitCreateResponse,
31 transformCustomToolkitDeleteResponse,
32 transformCustomToolkitSyncParams,
33 transformCustomToolkitSyncResponse,
34 transformCustomToolkitUpdateParams,
35 transformCustomToolkitUpdateResponse,
36 transformCustomToolkitUpsertParams,
37 transformCustomToolkitUpsertResponse,
38 } from '../utils/transformers/customToolkits';
39
40 const UPSERT_DEPRECATION =
41 '[Deprecation] composio.customToolkits.upsert() is deprecated. ' +
42 'Use create() for a new toolkit and update(slug, ...) to change its name, logo or API key field.';
43 let _upsertDeprecationWarned = false;
44
45 /**
46 * `composio.customToolkits` — toolkits your project registers
47 * from its own app or MCP server, with their own auth configs and connected
48 * accounts.
49 *
50 * These live on the Composio platform. They are unrelated to the in-process
51 * toolkits built with `experimental_createToolkit()`, which run inside your
52 * application.
53 *
54 * @example
55 * ```typescript
56 * const { slug } = await composio.customToolkits.create({
57 * name: 'My Toolkit',
58 * mcpUrl: 'https://mcp.example.com/mcp',
59 * authSchemes: [{ mode: 'DCR_OAUTH', discoveryUrl: 'https://mcp.example.com/.well-known/oauth-authorization-server' }],
60 * userId: 'all',
61 * });
62 * await composio.customToolkits.update(slug, { name: 'My Renamed Toolkit' });
63 * ```
64 */
65 export class CustomToolkits {
66 private client: ComposioClient;
67
68 constructor(client: ComposioClient) {
69 this.client = client;
70 telemetry.instrument(this, 'CustomToolkits');
71 }
72
73 /**
74 * Creates a custom MCP toolkit and returns its generated slug.
75 *
76 * Set `userId` to `'all'` to share the toolkit with every user in the
77 * project, or to a user ID to make it private to that user. `mcpUrl`,
78 * `authSchemes` and `userId` cannot change later: delete and re-create the
79 * toolkit instead. For a private toolkit, `connectLink` is where to send
80 * that user to connect.
81 *
82 * @param {CustomToolkitCreateParams} params - The toolkit to create
83 * @returns {Promise<CustomToolkitCreateResponse>} The toolkit's slug and, for a private toolkit, a connect link
84 * @throws {ValidationError} If the params fail validation
85 *
86 * @example
87 * ```typescript
88 * const { slug, connectLink } = await composio.customToolkits.create({
89 * name: 'Internal API',
90 * mcpUrl: 'https://mcp.internal.example.com/mcp',
91 * authSchemes: [
92 * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
93 * ],
94 * userId: 'user_123',
95 * });
96 * ```
97 */
98 async create(
99 params: CustomToolkitCreateParams,
100 requestOptions?: ComposioRequestOptions
101 ): Promise<CustomToolkitCreateResponse> {
102 const parsedParams = CustomToolkitCreateParamsSchema.safeParse(params);
103 if (!parsedParams.success) {
104 throw new ValidationError('Failed to parse custom toolkit create params', {
105 cause: parsedParams.error,
106 });
107 }
108 const body = transformCustomToolkitCreateParams(parsedParams.data);
109 const result = await withCancellation(
110 () => this.client.custom.createToolkit(body, requestOptions),
111 requestOptions?.signal
112 );
113 return transformCustomToolkitCreateResponse(result);
114 }
115
116 /**
117 * Updates a custom toolkit's name, logo or API key field copy. Omitted
118 * fields keep their current value.
119 *
120 * On a project with 2FA enabled, updating a private toolkit requires the
121 * `userId` it is private to.
122 *
123 * @param {string} slug - The custom toolkit slug returned by `create()`
124 * @param {CustomToolkitUpdateParams} params - At least one of `name`, `logoFile`, `apiKeyField`
125 * @returns {Promise<CustomToolkitUpdateResponse>} `{ success: true }`
126 * @throws {ValidationError} If the params fail validation
127 *
128 * @example
129 * ```typescript
130 * await composio.customToolkits.update('CUSTOM_INTERNAL_API_K7F2Q', {
131 * name: 'Internal API (prod)',
132 * userId: 'user_123',
133 * });
134 * ```
135 */
136 async update(
137 slug: string,
138 params: CustomToolkitUpdateParams,
139 requestOptions?: ComposioRequestOptions
140 ): Promise<CustomToolkitUpdateResponse> {
141 const parsedParams = CustomToolkitUpdateParamsSchema.safeParse(params);
142 if (!parsedParams.success) {
143 throw new ValidationError('Failed to parse custom toolkit update params', {
144 cause: parsedParams.error,
145 });
146 }
147 const body = transformCustomToolkitUpdateParams(parsedParams.data);
148 const result = await withCancellation(
149 () => this.client.custom.updateToolkits(slug, body, requestOptions),
150 requestOptions?.signal
151 );
152 return transformCustomToolkitUpdateResponse(result);
153 }
154
155 /**
156 * Creates a custom toolkit, or updates its display metadata (name, API key
157 * field copy) when the project already owns a toolkit with this slug.
158 *
159 * `mcpUrl` and `authSchemes` cannot change on an existing toolkit:
160 * re-sending them unchanged is a no-op, and changing them fails with a 409.
161 * Delete and re-register the toolkit instead, which revokes its connections.
162 *
163 * @param {CustomToolkitUpsertParams} params - The slug and toolkit configuration
164 * @returns {Promise<CustomToolkitUpsertResponse>} The toolkit's slug
165 * @throws {ValidationError} If the params fail validation
166 *
167 * @example
168 * ```typescript
169 * await composio.customToolkits.upsert({
170 * slug: 'INTERNAL_API',
171 * toolkitConfig: {
172 * name: 'Internal API',
173 * mcpUrl: 'https://mcp.internal.example.com/mcp',
174 * authSchemes: [
175 * { mode: 'API_KEY', headers: { Authorization: 'Bearer {{generic_api_key}}' } },
176 * ],
177 * },
178 * });
179 * ```
180 *
181 * @deprecated Use `create()` for a new toolkit and `update(slug, ...)` to change
182 * its name, logo or API key field. `create()` generates the slug, so store the
183 * slug it returns.
184 */
185 async upsert(
186 params: CustomToolkitUpsertParams,
187 requestOptions?: ComposioRequestOptions
188 ): Promise<CustomToolkitUpsertResponse> {
189 if (!_upsertDeprecationWarned) {
190 _upsertDeprecationWarned = true;
191 logger.warn(UPSERT_DEPRECATION);
192 }
193 const parsedParams = CustomToolkitUpsertParamsSchema.safeParse(params);
194 if (!parsedParams.success) {
195 throw new ValidationError('Failed to parse custom toolkit upsert params', {
196 cause: parsedParams.error,
197 });
198 }
199 const body = transformCustomToolkitUpsertParams(parsedParams.data);
200 const result = await withCancellation(
201 () => this.client.custom.upsert(body, requestOptions),
202 requestOptions?.signal
203 );
204 return transformCustomToolkitUpsertResponse(result);
205 }
206
207 /**
208 * Re-fetches the tool definitions of a custom toolkit from its remote MCP
209 * server. Call it when automatic sync fails or the remote tools change.
210 *
211 * @param {string} slug - The custom toolkit slug (`CUSTOM_...`)
212 * @param {CustomToolkitSyncParams} [params] - Optional connected account to fetch the definitions with
213 * @returns {Promise<CustomToolkitSyncResponse>} The toolkit version and number of tools synced
214 * @throws {ValidationError} If the params fail validation
215 *
216 * @example
217 * ```typescript
218 * const { version, syncedCount } = await composio.customToolkits.sync(
219 * 'CUSTOM_MY_TOOLKIT',
220 * { connectedAccountId: 'ca_abc123' }
221 * );
222 * ```
223 */
224 async sync(
225 slug: string,
226 params?: CustomToolkitSyncParams,
227 requestOptions?: ComposioRequestOptions
228 ): Promise<CustomToolkitSyncResponse> {
229 const parsedParams = CustomToolkitSyncParamsSchema.safeParse(params ?? {});
230 if (!parsedParams.success) {
231 throw new ValidationError('Failed to parse custom toolkit sync params', {
232 cause: parsedParams.error,
233 });
234 }
235 const body = transformCustomToolkitSyncParams(slug, parsedParams.data);
236 const result = await withCancellation(
237 () => this.client.custom.sync(body, requestOptions),
238 requestOptions?.signal
239 );
240 return transformCustomToolkitSyncResponse(result);
241 }
242
243 /**
244 * Deletes a custom toolkit owned by the project, with its tools, auth
245 * configs and connected accounts. The credentials behind those connected
246 * accounts are revoked in background jobs (`revokeJobIds`).
247 *
248 * Composio-managed toolkits cannot be deleted; the API answers 403.
249 *
250 * @param {string} slug - The custom toolkit slug (`CUSTOM_...`)
251 * @returns {Promise<CustomToolkitDeleteResponse>} What was deleted
252 *
253 * @example
254 * ```typescript
255 * const result = await composio.customToolkits.delete('CUSTOM_MY_TOOLKIT');
256 * console.log(result.connectedAccountsDeleted);
257 * ```
258 */
259 async delete(
260 slug: string,
261 requestOptions?: ComposioRequestOptions
262 ): Promise<CustomToolkitDeleteResponse> {
263 const result = await withCancellation(
264 () => this.client.custom.deleteToolkit(slug, {}, requestOptions),
265 requestOptions?.signal
266 );
267 return transformCustomToolkitDeleteResponse(result);
268 }
269 }