@devries-cameron20 / composio Mirror · read-only / commits / 3716bda4c
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, 14:45 UTC

fix(docs): resolve snapshot-miss toolkits

jkomyno committed Aug 25, 2026 at 03:26 UTC 3716bda4cb79739cfd6a62342dc5d3323c391b9e
2 files changed +540
docs/lib/toolkit-api.ts new
+242
@@ -0,0 +1,242 @@
1 +import { z } from 'zod';
2 +import { PRODUCTION_API_V3_URL } from '@/scripts/production-api.mjs';
3 +import type { AuthConfigDetail, AuthConfigField, Toolkit } from '@/types/toolkit';
4 +
5 +const NEGATIVE_CACHE_TTL_MS = 60_000;
6 +const TOOLKIT_SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
7 +
8 +const negativeCache = new Map<string, number>();
9 +
10 +function filteredArray<T>(schema: z.ZodType<T>) {
11 + return z
12 + .array(z.unknown())
13 + .catch([])
14 + .transform(items =>
15 + items.flatMap(item => {
16 + const parsed = schema.safeParse(item);
17 + return parsed.success ? [parsed.data] : [];
18 + })
19 + );
20 +}
21 +
22 +const optionalString = z.string().optional().catch(undefined);
23 +const stringArray = filteredArray(z.string());
24 +
25 +const rawAuthConfigFieldSchema = z.object({
26 + name: z.string().catch(''),
27 + displayName: optionalString,
28 + type: z.string().catch('string'),
29 + description: z.string().catch(''),
30 + required: z.boolean().optional().catch(undefined),
31 + default: z
32 + .union([z.string(), z.number(), z.boolean()])
33 + .transform(value => String(value))
34 + .nullable()
35 + .optional()
36 + .catch(undefined),
37 +});
38 +
39 +const requirementListsSchema = z
40 + .object({
41 + required: z.array(z.unknown()).catch([]),
42 + optional: z.array(z.unknown()).catch([]),
43 + })
44 + .catch({ required: [], optional: [] });
45 +
46 +const authConfigFieldsSchema = z
47 + .object({
48 + auth_config_creation: requirementListsSchema,
49 + connected_account_initiation: requirementListsSchema,
50 + })
51 + .catch({
52 + auth_config_creation: { required: [], optional: [] },
53 + connected_account_initiation: { required: [], optional: [] },
54 + });
55 +
56 +const rawAuthConfigDetailSchema = z.object({
57 + mode: z.string().min(1),
58 + name: optionalString,
59 + fields: authConfigFieldsSchema,
60 +});
61 +
62 +const categorySchema = z.union([
63 + z.string(),
64 + z.object({ name: z.string() }).transform(category => category.name),
65 +]);
66 +
67 +const rawToolkitSchema = z
68 + .object({
69 + slug: z.string().catch(''),
70 + name: optionalString,
71 + composio_managed_auth_schemes: stringArray,
72 + auth_config_details: filteredArray(rawAuthConfigDetailSchema),
73 + meta: z
74 + .object({
75 + description: z.string().catch(''),
76 + logo: optionalString,
77 + categories: z.array(z.unknown()).catch([]),
78 + tools_count: z.number().catch(0),
79 + triggers_count: z.number().catch(0),
80 + version: z.string().nullable().optional().catch(undefined),
81 + })
82 + .catch({
83 + description: '',
84 + logo: undefined,
85 + categories: [],
86 + tools_count: 0,
87 + triggers_count: 0,
88 + version: undefined,
89 + }),
90 + })
91 + .catch({
92 + slug: '',
93 + name: undefined,
94 + composio_managed_auth_schemes: [],
95 + auth_config_details: [],
96 + meta: {
97 + description: '',
98 + logo: undefined,
99 + categories: [],
100 + tools_count: 0,
101 + triggers_count: 0,
102 + version: undefined,
103 + },
104 + });
105 +
106 +type RawAuthConfigField = z.infer<typeof rawAuthConfigFieldSchema>;
107 +type RawAuthConfigDetail = z.infer<typeof rawAuthConfigDetailSchema>;
108 +type RawToolkit = z.infer<typeof rawToolkitSchema>;
109 +
110 +function normalizeAuthMode(mode: string): string {
111 + return mode.toUpperCase();
112 +}
113 +
114 +function uniqueAuthModes(modes: string[]): string[] {
115 + const seen = new Set<string>();
116 + return modes.flatMap(mode => {
117 + const normalized = normalizeAuthMode(mode);
118 + const key = normalized.toLowerCase();
119 + if (!normalized || seen.has(key)) return [];
120 + seen.add(key);
121 + return [normalized];
122 + });
123 +}
124 +
125 +function transformAuthConfigField(field: RawAuthConfigField, required: boolean): AuthConfigField {
126 + return {
127 + name: field.name,
128 + displayName: field.displayName || field.name,
129 + type: field.type,
130 + description: field.description,
131 + required: field.required ?? required,
132 + default: field.default ?? null,
133 + };
134 +}
135 +
136 +function authConfigFieldFromUnknown(value: unknown, required: boolean): AuthConfigField {
137 + const parsed = rawAuthConfigFieldSchema.safeParse(value);
138 + const field = parsed.success ? parsed.data : rawAuthConfigFieldSchema.parse({});
139 + return transformAuthConfigField(field, required);
140 +}
141 +
142 +function transformAuthConfigDetail(detail: RawAuthConfigDetail): AuthConfigDetail {
143 + const fields = detail.fields;
144 + return {
145 + mode: normalizeAuthMode(detail.mode),
146 + name: detail.name || detail.mode,
147 + fields: {
148 + auth_config_creation: {
149 + required: fields.auth_config_creation.required.map(field =>
150 + authConfigFieldFromUnknown(field, true)
151 + ),
152 + optional: fields.auth_config_creation.optional.map(field =>
153 + authConfigFieldFromUnknown(field, false)
154 + ),
155 + },
156 + connected_account_initiation: {
157 + required: fields.connected_account_initiation.required.map(field =>
158 + authConfigFieldFromUnknown(field, true)
159 + ),
160 + optional: fields.connected_account_initiation.optional.map(field =>
161 + authConfigFieldFromUnknown(field, false)
162 + ),
163 + },
164 + },
165 + };
166 +}
167 +
168 +function toolkitFromRaw(raw: RawToolkit, slug: string): Toolkit {
169 + const category = categorySchema.safeParse(raw.meta.categories[0]);
170 + const authConfigDetails = raw.auth_config_details.map(transformAuthConfigDetail);
171 + const composioManagedAuthSchemes = uniqueAuthModes(raw.composio_managed_auth_schemes);
172 + const authSchemes = uniqueAuthModes([
173 + ...authConfigDetails.map(detail => detail.mode),
174 + ...composioManagedAuthSchemes,
175 + ]);
176 +
177 + return {
178 + slug,
179 + name: raw.name || raw.slug || slug,
180 + logo: raw.meta.logo || null,
181 + description: raw.meta.description,
182 + category: category.success && category.data ? category.data : null,
183 + authSchemes,
184 + ...(composioManagedAuthSchemes.length > 0 ? { composioManagedAuthSchemes } : {}),
185 + toolCount: raw.meta.tools_count,
186 + triggerCount: raw.meta.triggers_count,
187 + version: raw.meta.version ?? null,
188 + tools: [],
189 + triggers: [],
190 + ...(authConfigDetails.length > 0 ? { authConfigDetails } : {}),
191 + };
192 +}
193 +
194 +function recordNegative(slug: string) {
195 + negativeCache.set(slug, Date.now() + NEGATIVE_CACHE_TTL_MS);
196 +}
197 +
198 +/** Fetch one toolkit's metadata from production after a checked-in snapshot miss. */
199 +export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit | null> {
200 + if (process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK === '0') return null;
201 +
202 + const apiKey = process.env.COMPOSIO_API_KEY;
203 + if (!apiKey) {
204 + console.warn(`[Toolkits] Production toolkit lookup skipped for "${slug}": missing API key`);
205 + return null;
206 + }
207 +
208 + const normalizedSlug = slug.toLowerCase();
209 + if (!TOOLKIT_SLUG_PATTERN.test(normalizedSlug)) return null;
210 +
211 + const negativeUntil = negativeCache.get(normalizedSlug);
212 + if (negativeUntil !== undefined) {
213 + if (negativeUntil > Date.now()) return null;
214 + negativeCache.delete(normalizedSlug);
215 + }
216 +
217 + try {
218 + const response = await fetch(`${PRODUCTION_API_V3_URL}/toolkits/${normalizedSlug}`, {
219 + headers: {
220 + 'Content-Type': 'application/json',
221 + 'x-api-key': apiKey,
222 + },
223 + next: { revalidate: 3600 },
224 + });
225 +
226 + if (!response.ok) {
227 + recordNegative(normalizedSlug);
228 + console.warn(
229 + `[Toolkits] Production toolkit lookup failed for "${normalizedSlug}": ${response.status}`
230 + );
231 + return null;
232 + }
233 +
234 + const payload = rawToolkitSchema.parse(await response.json());
235 + return toolkitFromRaw(payload, normalizedSlug);
236 + } catch (error) {
237 + recordNegative(normalizedSlug);
238 + const message = error instanceof Error ? error.message : String(error);
239 + console.warn(`[Toolkits] Production toolkit lookup failed for "${normalizedSlug}": ${message}`);
240 + return null;
241 + }
242 +}
docs/tests/static/toolkit-api.test.ts new
+298
@@ -0,0 +1,298 @@
1 +import { afterEach, describe, expect, mock, spyOn, test } from 'bun:test';
2 +import { readFile } from 'fs/promises';
3 +import { join } from 'path';
4 +import { z } from 'zod';
5 +import { fetchToolkitFromProduction } from '../../lib/toolkit-api';
6 +
7 +const originalApiKey = process.env.COMPOSIO_API_KEY;
8 +const originalApiBase = process.env.COMPOSIO_API_BASE;
9 +const originalFallback = process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
10 +const originalFetch = globalThis.fetch;
11 +
12 +const productionPayload = {
13 + slug: 'GitHub',
14 + name: 'GitHub',
15 + composio_managed_auth_schemes: ['oauth2', 'API_KEY'],
16 + auth_config_details: [
17 + {
18 + mode: 'OAuth2',
19 + name: 'github_oauth',
20 + fields: {
21 + auth_config_creation: {
22 + required: [
23 + {
24 + name: 'client_id',
25 + displayName: 'Client id',
26 + type: 'string',
27 + description: 'Client id of the app',
28 + },
29 + ],
30 + optional: [],
31 + },
32 + connected_account_initiation: { required: [], optional: [] },
33 + },
34 + },
35 + { mode: 'api_key', name: 'API key', fields: {} },
36 + ],
37 + meta: {
38 + logo: 'https://logos.composio.dev/api/github',
39 + description: 'GitHub description',
40 + categories: [{ name: 'developer tools' }],
41 + tools_count: 893,
42 + triggers_count: 20,
43 + version: '20260815_00',
44 + },
45 +};
46 +
47 +function useApiKey() {
48 + process.env.COMPOSIO_API_KEY = 'test-key';
49 + delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
50 +}
51 +
52 +afterEach(() => {
53 + globalThis.fetch = originalFetch;
54 + mock.restore();
55 +
56 + if (originalApiKey === undefined) delete process.env.COMPOSIO_API_KEY;
57 + else process.env.COMPOSIO_API_KEY = originalApiKey;
58 + if (originalApiBase === undefined) delete process.env.COMPOSIO_API_BASE;
59 + else process.env.COMPOSIO_API_BASE = originalApiBase;
60 + if (originalFallback === undefined) delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
61 + else process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK = originalFallback;
62 +});
63 +
64 +describe('fetchToolkitFromProduction', () => {
65 + test('maps the single-toolkit response and normalizes auth modes', async () => {
66 + useApiKey();
67 + const fetcher = mock(async () => Response.json(productionPayload));
68 + globalThis.fetch = fetcher;
69 +
70 + const toolkit = await fetchToolkitFromProduction('GitHub');
71 +
72 + expect(toolkit).toEqual({
73 + slug: 'github',
74 + name: 'GitHub',
75 + logo: 'https://logos.composio.dev/api/github',
76 + description: 'GitHub description',
77 + category: 'developer tools',
78 + authSchemes: ['OAUTH2', 'API_KEY'],
79 + composioManagedAuthSchemes: ['OAUTH2', 'API_KEY'],
80 + toolCount: 893,
81 + triggerCount: 20,
82 + version: '20260815_00',
83 + tools: [],
84 + triggers: [],
85 + authConfigDetails: [
86 + {
87 + mode: 'OAUTH2',
88 + name: 'github_oauth',
89 + fields: {
90 + auth_config_creation: {
91 + required: [
92 + {
93 + name: 'client_id',
94 + displayName: 'Client id',
95 + type: 'string',
96 + description: 'Client id of the app',
97 + required: true,
98 + default: null,
99 + },
100 + ],
101 + optional: [],
102 + },
103 + connected_account_initiation: { required: [], optional: [] },
104 + },
105 + },
106 + {
107 + mode: 'API_KEY',
108 + name: 'API key',
109 + fields: {
110 + auth_config_creation: { required: [], optional: [] },
111 + connected_account_initiation: { required: [], optional: [] },
112 + },
113 + },
114 + ],
115 + });
116 + expect(fetcher).toHaveBeenCalledTimes(1);
117 + expect(fetcher.mock.calls[0]?.[0]).toBe('https://backend.composio.dev/api/v3/toolkits/github');
118 + expect(fetcher.mock.calls[0]?.[1]).toEqual({
119 + headers: { 'Content-Type': 'application/json', 'x-api-key': 'test-key' },
120 + next: { revalidate: 3600 },
121 + });
122 + });
123 +
124 + test('matches the committed snapshot key set and metadata defaults', async () => {
125 + useApiKey();
126 + const snapshotSchema = z.array(
127 + z.object({
128 + slug: z.string(),
129 + name: z.string(),
130 + logo: z.string().nullable(),
131 + description: z.string(),
132 + category: z.string().nullable(),
133 + authSchemes: z.array(z.string()),
134 + composioManagedAuthSchemes: z.array(z.string()).optional(),
135 + toolCount: z.number(),
136 + triggerCount: z.number(),
137 + version: z.string().nullable(),
138 + tools: z.array(z.unknown()),
139 + triggers: z.array(z.unknown()),
140 + authConfigDetails: z.array(z.unknown()).optional(),
141 + })
142 + );
143 + const snapshots = snapshotSchema.parse(
144 + JSON.parse(await readFile(join(import.meta.dir, '../../public/data/toolkits.json'), 'utf8'))
145 + );
146 + const snapshot = snapshots.find(toolkit => toolkit.slug === 'github');
147 + expect(snapshot).toBeDefined();
148 + if (!snapshot) throw new Error('Expected committed GitHub toolkit snapshot');
149 +
150 + globalThis.fetch = mock(async () =>
151 + Response.json({
152 + slug: snapshot.slug,
153 + name: snapshot.name,
154 + composio_managed_auth_schemes: snapshot.composioManagedAuthSchemes,
155 + auth_config_details: snapshot.authConfigDetails,
156 + meta: {
157 + logo: snapshot.logo,
158 + description: snapshot.description,
159 + categories: snapshot.category ? [{ name: snapshot.category }] : [],
160 + tools_count: snapshot.toolCount,
161 + triggers_count: snapshot.triggerCount,
162 + version: snapshot.version,
163 + },
164 + })
165 + );
166 +
167 + const toolkit = await fetchToolkitFromProduction(snapshot.slug);
168 + expect(toolkit).not.toBeNull();
169 + expect(Object.keys(toolkit ?? {}).sort()).toEqual(
170 + Object.keys({ ...snapshot, tools: [], triggers: [] }).sort()
171 + );
172 + expect(toolkit?.authSchemes).toEqual(snapshot.authSchemes);
173 + expect(toolkit?.composioManagedAuthSchemes).toEqual(snapshot.composioManagedAuthSchemes);
174 + expect(toolkit?.version).toBe(snapshot.version);
175 + expect(toolkit?.tools).toEqual([]);
176 + expect(toolkit?.triggers).toEqual([]);
177 + });
178 +
179 + test('degrades missing metadata and malformed auth details without throwing', async () => {
180 + useApiKey();
181 + globalThis.fetch = mock(async () =>
182 + Response.json({
183 + slug: 'LENIENT',
184 + name: 'Lenient',
185 + auth_config_details: [
186 + null,
187 + 'junk',
188 + { name: 'missing mode' },
189 + {
190 + mode: 'oauth2',
191 + fields: {
192 + auth_config_creation: { required: [null], optional: [] },
193 + },
194 + },
195 + ],
196 + })
197 + );
198 +
199 + const toolkit = await fetchToolkitFromProduction('lenient');
200 + expect(toolkit).toMatchObject({
201 + slug: 'lenient',
202 + name: 'Lenient',
203 + logo: null,
204 + description: '',
205 + category: null,
206 + authSchemes: ['OAUTH2'],
207 + toolCount: 0,
208 + triggerCount: 0,
209 + version: null,
210 + tools: [],
211 + triggers: [],
212 + });
213 + expect(toolkit?.authConfigDetails).toHaveLength(1);
214 + expect(toolkit?.authConfigDetails?.[0]?.fields.auth_config_creation.required[0]).toEqual({
215 + name: '',
216 + displayName: '',
217 + type: 'string',
218 + description: '',
219 + required: true,
220 + default: null,
221 + });
222 + });
223 +
224 + test.each(['../etc', 'has space', 'A'.repeat(80), ''])(
225 + 'rejects invalid slug %p before fetch',
226 + async slug => {
227 + useApiKey();
228 + const fetcher = mock(async () => Response.json(productionPayload));
229 + globalThis.fetch = fetcher;
230 +
231 + expect(await fetchToolkitFromProduction(slug)).toBeNull();
232 + expect(fetcher).not.toHaveBeenCalled();
233 + }
234 + );
235 +
236 + test('requires an API key and warns without fetching', async () => {
237 + delete process.env.COMPOSIO_API_KEY;
238 + delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
239 + const fetcher = mock(async () => Response.json(productionPayload));
240 + globalThis.fetch = fetcher;
241 + const warning = spyOn(console, 'warn').mockImplementation(() => {});
242 +
243 + expect(await fetchToolkitFromProduction('missing-key')).toBeNull();
244 + expect(fetcher).not.toHaveBeenCalled();
245 + expect(warning).toHaveBeenCalledTimes(1);
246 + });
247 +
248 + test('reads the kill switch on every call', async () => {
249 + useApiKey();
250 + const fetcher = mock(async () => Response.json({ ...productionPayload, slug: 'toggle' }));
251 + globalThis.fetch = fetcher;
252 + process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK = '0';
253 +
254 + expect(await fetchToolkitFromProduction('toggle')).toBeNull();
255 + delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;
256 + expect(await fetchToolkitFromProduction('toggle')).not.toBeNull();
257 + expect(fetcher).toHaveBeenCalledTimes(1);
258 + });
259 +
260 + test('ignores COMPOSIO_API_BASE when building the production URL', async () => {
261 + useApiKey();
262 + process.env.COMPOSIO_API_BASE = 'https://staging-backend.composio.dev/api/v3';
263 + const fetcher = mock(async () => Response.json(productionPayload));
264 + globalThis.fetch = fetcher;
265 +
266 + await fetchToolkitFromProduction('github');
267 + expect(fetcher.mock.calls[0]?.[0]).toBe('https://backend.composio.dev/api/v3/toolkits/github');
268 + });
269 +
270 + test('negative-caches a 404 for 60 seconds, then retries', async () => {
271 + useApiKey();
272 + const fetcher = mock(async () => new Response(null, { status: 404 }));
273 + globalThis.fetch = fetcher;
274 + const warning = spyOn(console, 'warn').mockImplementation(() => {});
275 + const now = spyOn(Date, 'now').mockReturnValue(1_000);
276 +
277 + expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();
278 + expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();
279 + expect(fetcher).toHaveBeenCalledTimes(1);
280 +
281 + now.mockReturnValue(61_001);
282 + expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();
283 + expect(fetcher).toHaveBeenCalledTimes(2);
284 + expect(warning).toHaveBeenCalledTimes(2);
285 + });
286 +
287 + test.each([
288 + ['500 response', async () => new Response(null, { status: 500 })],
289 + ['network error', async () => Promise.reject(new Error('offline'))],
290 + ['invalid JSON', async () => new Response('{', { status: 200 })],
291 + ])('returns null for %s without throwing', async (_label, responseFactory) => {
292 + useApiKey();
293 + globalThis.fetch = mock(responseFactory);
294 + spyOn(console, 'warn').mockImplementation(() => {});
295 +
296 + expect(await fetchToolkitFromProduction(`failure-${_label.replaceAll(' ', '-')}`)).toBeNull();
297 + });
298 +});