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

next
ts 515 lines 17.2 KB
Raw
1 import { describe, it, expect, vi, afterEach } from 'vitest';
2 import ComposioClient, { APIError, Auth, createFetchTransport } from '@composio/client';
3 import { Tools } from '../../src/models/Tools';
4 import { ComposioRequestCancelledError } from '../../src/errors/SDKErrors';
5 import { MockProvider } from '../utils/mocks/provider.mock';
6 import { toolMocks } from '../utils/mocks/data.mock';
7 import { ComposioConnectedAccountNotFoundError } from '../../src/errors/ConnectedAccountsErrors';
8 import {
9 ComposioToolExecutionError,
10 ComposioToolExecutionRateLimitError,
11 ComposioToolFetchError,
12 ComposioToolFetchRateLimitError,
13 ComposioToolNotFoundError,
14 handleToolExecutionError,
15 isComposioRateLimitError,
16 } from '../../src/errors/ToolErrors';
17
18 vi.mock('../../src/telemetry/Telemetry', () => ({
19 telemetry: { instrument: vi.fn() },
20 }));
21
22 const SLUG = 'GITHUB_GET_REPOS';
23 const json = (body: unknown, status = 200, headers: Record<string, string> = {}) =>
24 new Response(JSON.stringify(body), {
25 status,
26 headers: { 'content-type': 'application/json', ...headers },
27 });
28 const rateLimited = () =>
29 json({ error: { message: 'slow down' } }, 429, { 'retry-after': '7', 'retry-after-ms': '1' });
30
31 /** A real client whose schema and execute responses come from the given handlers. */
32 const createTools = (
33 options: {
34 retrieve?: () => Response;
35 execute?: () => Response;
36 toolkitVersions?: Record<string, string>;
37 } = {}
38 ) => {
39 const retrieve = vi.fn(options.retrieve ?? (() => json(toolMocks.rawTool)));
40 const execute = vi.fn(options.execute ?? (() => json(toolMocks.rawToolExecuteResponse)));
41 const fetch = vi.fn<typeof globalThis.fetch>(async (input, init) => {
42 const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
43 return method === 'GET' ? retrieve() : execute();
44 });
45 const client = new ComposioClient({
46 auth: Auth.project('test-api-key'),
47 baseURL: 'https://backend.invalid',
48 transport: createFetchTransport({ fetch }),
49 });
50 const tools = new Tools(client, {
51 provider: new MockProvider(),
52 toolkitVersions: options.toolkitVersions,
53 });
54 return { tools, retrieve, execute };
55 };
56
57 const run = (tools: ReturnType<typeof createTools>['tools'], version?: string) =>
58 tools.execute(SLUG, {
59 userId: 'user_1',
60 arguments: {},
61 version,
62 dangerouslySkipVersionCheck: true,
63 });
64
65 describe('tools.execute schema cache', () => {
66 afterEach(() => {
67 vi.useRealTimers();
68 });
69
70 it('fetches the schema once across executions of one tool', async () => {
71 const { tools, retrieve, execute } = createTools();
72
73 await run(tools);
74 await run(tools);
75 await run(tools);
76
77 expect(retrieve).toHaveBeenCalledTimes(1);
78 expect(execute).toHaveBeenCalledTimes(3);
79 });
80
81 it('keeps a separate entry per version', async () => {
82 const { tools, retrieve } = createTools();
83
84 await run(tools, '20250909_00');
85 await run(tools, '20250910_00');
86 await run(tools, '20250909_00');
87
88 expect(retrieve).toHaveBeenCalledTimes(2);
89 });
90
91 it('refetches a latest schema after 5 minutes', async () => {
92 vi.useFakeTimers({ toFake: ['Date'] });
93 const { tools, retrieve } = createTools();
94
95 await run(tools);
96 vi.advanceTimersByTime(5 * 60 * 1000 - 1);
97 await run(tools);
98 expect(retrieve).toHaveBeenCalledTimes(1);
99
100 vi.advanceTimersByTime(1);
101 await run(tools);
102 expect(retrieve).toHaveBeenCalledTimes(2);
103 });
104
105 it('keeps a pinned schema for an hour', async () => {
106 vi.useFakeTimers({ toFake: ['Date'] });
107 const { tools, retrieve } = createTools();
108
109 await run(tools, '20250909_00');
110 vi.advanceTimersByTime(60 * 60 * 1000 - 1);
111 await run(tools, '20250909_00');
112 expect(retrieve).toHaveBeenCalledTimes(1);
113
114 vi.advanceTimersByTime(1);
115 await run(tools, '20250909_00');
116 expect(retrieve).toHaveBeenCalledTimes(2);
117 });
118
119 it('uses the pinned lifetime for a version set in toolkitVersions', async () => {
120 vi.useFakeTimers({ toFake: ['Date'] });
121 const { tools, retrieve } = createTools({
122 toolkitVersions: { [toolMocks.rawTool.toolkit.slug]: '20250909_00' },
123 });
124
125 await run(tools);
126 vi.advanceTimersByTime(60 * 60 * 1000 - 1);
127 await run(tools);
128 expect(retrieve).toHaveBeenCalledTimes(1);
129
130 vi.advanceTimersByTime(1);
131 await run(tools);
132 expect(retrieve).toHaveBeenCalledTimes(2);
133 });
134
135 it('drops the oldest schema past 500 entries', async () => {
136 const { tools, retrieve } = createTools();
137
138 for (let i = 0; i <= 500; i++) {
139 await run(tools, `v${i}`);
140 }
141 expect(retrieve).toHaveBeenCalledTimes(501);
142
143 // The newest entry is still cached, and the oldest was dropped.
144 await run(tools, 'v500');
145 expect(retrieve).toHaveBeenCalledTimes(501);
146 await run(tools, 'v0');
147 expect(retrieve).toHaveBeenCalledTimes(502);
148 });
149
150 it('does not cache a failed fetch', async () => {
151 const retrieve = vi
152 .fn<() => Response>()
153 .mockReturnValueOnce(json({ error: { message: 'bad' } }, 400))
154 .mockReturnValue(json(toolMocks.rawTool));
155 const { tools } = createTools({ retrieve });
156
157 await expect(run(tools)).rejects.toThrow();
158 await expect(run(tools)).resolves.toBeDefined();
159 expect(retrieve).toHaveBeenCalledTimes(2);
160 });
161
162 it('still honors an aborted signal on a cache hit', async () => {
163 const { tools, execute } = createTools();
164 await run(tools);
165
166 const error = await tools
167 .execute(
168 SLUG,
169 { userId: 'user_1', arguments: {}, dangerouslySkipVersionCheck: true },
170 { signal: AbortSignal.abort() }
171 )
172 .catch(e => e);
173
174 expect(error).toBeInstanceOf(ComposioRequestCancelledError);
175 expect(execute).toHaveBeenCalledTimes(1);
176 });
177
178 it('leaves getRawComposioToolBySlug uncached', async () => {
179 const { tools, retrieve } = createTools();
180
181 await tools.getRawComposioToolBySlug(SLUG);
182 await tools.getRawComposioToolBySlug(SLUG);
183
184 expect(retrieve).toHaveBeenCalledTimes(2);
185 });
186 });
187
188 describe('rate limit errors', () => {
189 it('reports a rejected schema fetch as a rate limit, not a bad slug', async () => {
190 const { tools, execute } = createTools({ retrieve: rateLimited });
191
192 const error = await run(tools).catch(e => e);
193
194 expect(error).toBeInstanceOf(ComposioToolFetchRateLimitError);
195 expect(error).toBeInstanceOf(ComposioToolFetchError);
196 expect(isComposioRateLimitError(error)).toBe(true);
197 expect(error.retryAfterSeconds).toBe(7);
198 expect(error.statusCode).toBe(429);
199 expect(error.message).toBe(`Rate limited while retrieving tool with slug ${SLUG}`);
200 expect(error.possibleFixes).toEqual([
201 'Wait 7 seconds, then retry',
202 'Reduce how many requests your organization sends per minute',
203 ]);
204 expect(execute).not.toHaveBeenCalled();
205 });
206
207 it('reports a rejected execution as a rate limit, once', async () => {
208 const { tools, execute } = createTools({ execute: rateLimited });
209
210 const error = await run(tools).catch(e => e);
211
212 expect(error).toBeInstanceOf(ComposioToolExecutionRateLimitError);
213 expect(error).toBeInstanceOf(ComposioToolExecutionError);
214 expect(isComposioRateLimitError(error)).toBe(true);
215 expect(error.retryAfterSeconds).toBe(7);
216 expect(error.statusCode).toBe(429);
217 expect(error.message).toBe(`Rate limited while executing the tool ${toolMocks.rawTool.slug}`);
218 expect(execute).toHaveBeenCalledTimes(1);
219 });
220
221 it('leaves out retryAfterSeconds when the response gives no wait', async () => {
222 const { tools } = createTools({
223 retrieve: () => json({ error: { message: 'slow down' } }, 429, { 'retry-after-ms': '1' }),
224 });
225
226 const error = await run(tools).catch(e => e);
227
228 expect(isComposioRateLimitError(error)).toBe(true);
229 expect(Object.keys(error)).not.toContain('retryAfterSeconds');
230 expect(error.possibleFixes[0]).toBe('Wait before retrying');
231 });
232
233 it('does not report other failures as rate limits', async () => {
234 const { tools } = createTools({
235 retrieve: () => json({ error: { message: 'bad key' } }, 401),
236 });
237
238 const error = await run(tools).catch(e => e);
239
240 expect(error).toBeInstanceOf(ComposioToolFetchError);
241 expect(isComposioRateLimitError(error)).toBe(false);
242 });
243 });
244
245 describe('transport metadata on errors', () => {
246 it('reads the status and request id of a rejected schema fetch from its cause', async () => {
247 const { tools } = createTools({
248 retrieve: () =>
249 json(
250 { error: { message: 'bad key', code: 1001, slug: 'UNAUTHORIZED', status: 401 } },
251 401,
252 { 'x-request-id': 'req_fetch_401' }
253 ),
254 });
255
256 const error = await run(tools).catch(e => e);
257
258 expect(error).toBeInstanceOf(ComposioToolFetchError);
259 expect(error.statusCode).toBe(401);
260 expect(error.requestId).toBe('req_fetch_401');
261 expect(error.cause).toBeInstanceOf(APIError);
262 });
263 });
264
265 describe('tool execution errors', () => {
266 const rejected = (
267 status: number,
268 error: Record<string, unknown>,
269 headers: Record<string, string> = {}
270 ) => json({ error: { slug: 'ERROR', status, ...error } }, status, headers);
271 const SLUG_FIX = 'Ensure the tool slug is correct and the input arguments for the tool is valid';
272
273 it('surfaces the server message, suggested fix and codes of a 410', async () => {
274 const { tools } = createTools({
275 execute: () =>
276 rejected(
277 410,
278 {
279 message: 'Toolkit version 20250101_00 is retired',
280 code: 1410,
281 suggested_fix: 'Pin 20250909_00',
282 },
283 { 'x-request-id': 'req_410' }
284 ),
285 });
286
287 const error = await run(tools).catch(e => e);
288
289 expect(error).toBeInstanceOf(ComposioToolExecutionError);
290 expect(error.message).toBe(
291 `Error executing the tool ${toolMocks.rawTool.slug}: Toolkit version 20250101_00 is retired`
292 );
293 expect(error.code).toBe('TS-SDK::TOOL_EXECUTION_ERROR');
294 expect(error.statusCode).toBe(410);
295 expect(error.apiErrorCode).toBe(1410);
296 expect(error.requestId).toBe('req_410');
297 expect(error.possibleFixes).toEqual(['Pin 20250909_00']);
298 expect(error.cause).toBeInstanceOf(APIError);
299 expect(error.cause.status).toBe(410);
300 });
301
302 it('falls back to a status-specific fix for a 403 without a suggested fix', async () => {
303 const { tools } = createTools({
304 execute: () =>
305 rejected(403, { message: 'Connected account belongs to another project', code: 1403 }),
306 });
307
308 const error = await run(tools).catch(e => e);
309
310 expect(error).toBeInstanceOf(ComposioToolExecutionError);
311 expect(error.message).toBe(
312 `Error executing the tool ${toolMocks.rawTool.slug}: Connected account belongs to another project`
313 );
314 expect(error.statusCode).toBe(403);
315 expect(error.apiErrorCode).toBe(1403);
316 expect(error.possibleFixes).toEqual([
317 'Ensure your API key and the connected account are allowed to run this tool',
318 ]);
319 expect(error.cause).toBeInstanceOf(APIError);
320 });
321
322 it.each([402, 410, 500, 503])('never blames the slug or arguments for a %i', async status => {
323 const { tools } = createTools({ execute: () => rejected(status, { message: 'no', code: 1 }) });
324
325 const error = await run(tools).catch(e => e);
326
327 expect(error.statusCode).toBe(status);
328 expect(error.possibleFixes).not.toContain(SLUG_FIX);
329 });
330
331 it('keeps the tool context alone when the body is not the error envelope', async () => {
332 const { tools } = createTools({ execute: () => json({ unexpected: true }, 400) });
333
334 const error = await run(tools).catch(e => e);
335
336 expect(error).toBeInstanceOf(ComposioToolExecutionError);
337 expect(error.message).toBe(`Error executing the tool ${toolMocks.rawTool.slug}`);
338 expect(error.statusCode).toBe(400);
339 expect(Object.keys(error)).not.toContain('apiErrorCode');
340 expect(error.possibleFixes).toEqual([SLUG_FIX]);
341 });
342
343 it('strips terminal escapes and line breaks from server text', async () => {
344 const { tools } = createTools({
345 execute: () =>
346 rejected(403, {
347 message: 'denied\u001b[31m\n[!] run: evil',
348 code: 1403,
349 suggested_fix: 'retry\u001b]0;owned\u0007 now',
350 }),
351 });
352
353 const error = await run(tools).catch(e => e);
354
355 expect(error.message).toBe(
356 `Error executing the tool ${toolMocks.rawTool.slug}: denied [!] run: evil`
357 );
358 expect(error.possibleFixes).toEqual(['retry now']);
359 expect(error.message).not.toMatch(/[\u0000-\u001f\u007f-\u009f]/);
360 });
361
362 it('keeps the original reason when the failure never reached the API', () => {
363 const error = handleToolExecutionError(SLUG, new Error('socket hang up\n\u001b[31m'));
364
365 expect(error.message).toBe(`Error executing the tool ${SLUG}: socket hang up`);
366 });
367
368 it('surfaces the server details of a rate limit', async () => {
369 const { tools } = createTools({
370 execute: () =>
371 rejected(
372 429,
373 { message: 'slow down', code: 1429, suggested_fix: 'Wait an hour' },
374 { 'retry-after': '7' }
375 ),
376 });
377
378 const error = await run(tools).catch(e => e);
379
380 expect(error).toBeInstanceOf(ComposioToolExecutionRateLimitError);
381 expect(error.message).toBe(
382 `Rate limited while executing the tool ${toolMocks.rawTool.slug}: slow down`
383 );
384 expect(error.statusCode).toBe(429);
385 expect(error.apiErrorCode).toBe(1429);
386 expect(error.possibleFixes).toEqual(['Wait an hour']);
387 expect(error.retryAfterSeconds).toBe(7);
388 });
389
390 it('strips terminal escapes from the missing-account message', async () => {
391 const { tools } = createTools({
392 execute: () =>
393 rejected(400, {
394 message: 'No connected account\u001b[31m\n[!] connect',
395 code: 1803,
396 }),
397 });
398
399 const error = await run(tools).catch(e => e);
400
401 expect(error).toBeInstanceOf(ComposioConnectedAccountNotFoundError);
402 expect(error.message).toBe('No connected account [!] connect');
403 expect(error.message).not.toMatch(/[\u0000-\u001f\u007f-\u009f]/);
404 });
405
406 it('keeps the server status, fix and code of a missing connected account', async () => {
407 const { tools } = createTools({
408 execute: () =>
409 rejected(400, {
410 message: 'No connected account found',
411 code: 1803,
412 suggested_fix: 'Connect Gmail first',
413 }),
414 });
415
416 const error = await run(tools).catch(e => e);
417
418 expect(error).toBeInstanceOf(ComposioConnectedAccountNotFoundError);
419 expect(error.message).toBe('No connected account found');
420 expect(error.statusCode).toBe(400);
421 expect(error.apiErrorCode).toBe(1803);
422 expect(error.possibleFixes).toEqual(['Connect Gmail first']);
423 expect(error.cause).toBeInstanceOf(APIError);
424 expect(error.cause.status).toBe(400);
425 });
426 });
427
428 describe('tool fetch errors', () => {
429 it('surfaces the server details of a 429', async () => {
430 const { tools } = createTools({
431 retrieve: () =>
432 json(
433 {
434 error: {
435 message: 'slow down',
436 code: 1429,
437 slug: 'RATE_LIMITED',
438 status: 429,
439 suggested_fix: 'Wait an hour',
440 },
441 },
442 429,
443 { 'retry-after': '7', 'retry-after-ms': '1' }
444 ),
445 });
446
447 const error = await run(tools).catch(e => e);
448
449 expect(error).toBeInstanceOf(ComposioToolFetchRateLimitError);
450 expect(error.message).toBe(`Rate limited while retrieving tool with slug ${SLUG}: slow down`);
451 expect(error.statusCode).toBe(429);
452 expect(error.apiErrorCode).toBe(1429);
453 expect(error.possibleFixes).toEqual(['Wait an hour']);
454 expect(error.retryAfterSeconds).toBe(7);
455 });
456
457 it('surfaces the server details of a 410', async () => {
458 const { tools, execute } = createTools({
459 retrieve: () =>
460 json(
461 {
462 error: {
463 message: 'Toolkit version 20250101_00 is retired',
464 code: 1410,
465 slug: 'TOOLKIT_VERSION_RETIRED',
466 status: 410,
467 suggested_fix: 'Pin 20250909_00',
468 },
469 },
470 410,
471 { 'x-request-id': 'req_fetch_410' }
472 ),
473 });
474
475 const error = await tools.getRawComposioToolBySlug(SLUG).catch(e => e);
476
477 expect(error).toBeInstanceOf(ComposioToolFetchError);
478 expect(error.message).toBe(
479 `Unable to retrieve tool with slug ${SLUG}: Toolkit version 20250101_00 is retired`
480 );
481 expect(error.statusCode).toBe(410);
482 expect(error.apiErrorCode).toBe(1410);
483 expect(error.requestId).toBe('req_fetch_410');
484 expect(error.possibleFixes).toEqual(['Pin 20250909_00']);
485 expect(execute).not.toHaveBeenCalled();
486 });
487
488 it('surfaces the server details of a 404', async () => {
489 const { tools } = createTools({
490 retrieve: () =>
491 json(
492 {
493 error: {
494 message: 'No tool with that slug in the pinned version',
495 code: 1404,
496 slug: 'TOOL_NOT_FOUND',
497 status: 404,
498 suggested_fix: 'Use the latest version',
499 },
500 },
501 404
502 ),
503 });
504
505 const error = await tools.getRawComposioToolBySlug(SLUG).catch(e => e);
506
507 expect(error).toBeInstanceOf(ComposioToolNotFoundError);
508 expect(error.message).toBe(
509 `Tool with slug ${SLUG} not found: No tool with that slug in the pinned version`
510 );
511 expect(error.statusCode).toBe(404);
512 expect(error.apiErrorCode).toBe(1404);
513 expect(error.possibleFixes).toEqual(['Use the latest version']);
514 });
515 });