Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
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
+});