Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(docs): resolve snapshot-miss toolkits
jkomyno3716bda4cb79
diff --git a/docs/lib/toolkit-api.ts b/docs/lib/toolkit-api.tsnew file mode 100644index 000000000..8ff72dfe9--- /dev/null+++ b/docs/lib/toolkit-api.ts@@ -0,0 +1,242 @@+import { z } from 'zod';+import { PRODUCTION_API_V3_URL } from '@/scripts/production-api.mjs';+import type { AuthConfigDetail, AuthConfigField, Toolkit } from '@/types/toolkit';++const NEGATIVE_CACHE_TTL_MS = 60_000;+const TOOLKIT_SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;++const negativeCache = new Map<string, number>();++function filteredArray<T>(schema: z.ZodType<T>) {+ return z+ .array(z.unknown())+ .catch([])+ .transform(items =>+ items.flatMap(item => {+ const parsed = schema.safeParse(item);+ return parsed.success ? [parsed.data] : [];+ })+ );+}++const optionalString = z.string().optional().catch(undefined);+const stringArray = filteredArray(z.string());++const rawAuthConfigFieldSchema = z.object({+ name: z.string().catch(''),+ displayName: optionalString,+ type: z.string().catch('string'),+ description: z.string().catch(''),+ required: z.boolean().optional().catch(undefined),+ default: z+ .union([z.string(), z.number(), z.boolean()])+ .transform(value => String(value))+ .nullable()+ .optional()+ .catch(undefined),+});++const requirementListsSchema = z+ .object({+ required: z.array(z.unknown()).catch([]),+ optional: z.array(z.unknown()).catch([]),+ })+ .catch({ required: [], optional: [] });++const authConfigFieldsSchema = z+ .object({+ auth_config_creation: requirementListsSchema,+ connected_account_initiation: requirementListsSchema,+ })+ .catch({+ auth_config_creation: { required: [], optional: [] },+ connected_account_initiation: { required: [], optional: [] },+ });++const rawAuthConfigDetailSchema = z.object({+ mode: z.string().min(1),+ name: optionalString,+ fields: authConfigFieldsSchema,+});++const categorySchema = z.union([+ z.string(),+ z.object({ name: z.string() }).transform(category => category.name),+]);++const rawToolkitSchema = z+ .object({+ slug: z.string().catch(''),+ name: optionalString,+ composio_managed_auth_schemes: stringArray,+ auth_config_details: filteredArray(rawAuthConfigDetailSchema),+ meta: z+ .object({+ description: z.string().catch(''),+ logo: optionalString,+ categories: z.array(z.unknown()).catch([]),+ tools_count: z.number().catch(0),+ triggers_count: z.number().catch(0),+ version: z.string().nullable().optional().catch(undefined),+ })+ .catch({+ description: '',+ logo: undefined,+ categories: [],+ tools_count: 0,+ triggers_count: 0,+ version: undefined,+ }),+ })+ .catch({+ slug: '',+ name: undefined,+ composio_managed_auth_schemes: [],+ auth_config_details: [],+ meta: {+ description: '',+ logo: undefined,+ categories: [],+ tools_count: 0,+ triggers_count: 0,+ version: undefined,+ },+ });++type RawAuthConfigField = z.infer<typeof rawAuthConfigFieldSchema>;+type RawAuthConfigDetail = z.infer<typeof rawAuthConfigDetailSchema>;+type RawToolkit = z.infer<typeof rawToolkitSchema>;++function normalizeAuthMode(mode: string): string {+ return mode.toUpperCase();+}++function uniqueAuthModes(modes: string[]): string[] {+ const seen = new Set<string>();+ return modes.flatMap(mode => {+ const normalized = normalizeAuthMode(mode);+ const key = normalized.toLowerCase();+ if (!normalized || seen.has(key)) return [];+ seen.add(key);+ return [normalized];+ });+}++function transformAuthConfigField(field: RawAuthConfigField, required: boolean): AuthConfigField {+ return {+ name: field.name,+ displayName: field.displayName || field.name,+ type: field.type,+ description: field.description,+ required: field.required ?? required,+ default: field.default ?? null,+ };+}++function authConfigFieldFromUnknown(value: unknown, required: boolean): AuthConfigField {+ const parsed = rawAuthConfigFieldSchema.safeParse(value);+ const field = parsed.success ? parsed.data : rawAuthConfigFieldSchema.parse({});+ return transformAuthConfigField(field, required);+}++function transformAuthConfigDetail(detail: RawAuthConfigDetail): AuthConfigDetail {+ const fields = detail.fields;+ return {+ mode: normalizeAuthMode(detail.mode),+ name: detail.name || detail.mode,+ fields: {+ auth_config_creation: {+ required: fields.auth_config_creation.required.map(field =>+ authConfigFieldFromUnknown(field, true)+ ),+ optional: fields.auth_config_creation.optional.map(field =>+ authConfigFieldFromUnknown(field, false)+ ),+ },+ connected_account_initiation: {+ required: fields.connected_account_initiation.required.map(field =>+ authConfigFieldFromUnknown(field, true)+ ),+ optional: fields.connected_account_initiation.optional.map(field =>+ authConfigFieldFromUnknown(field, false)+ ),+ },+ },+ };+}++function toolkitFromRaw(raw: RawToolkit, slug: string): Toolkit {+ const category = categorySchema.safeParse(raw.meta.categories[0]);+ const authConfigDetails = raw.auth_config_details.map(transformAuthConfigDetail);+ const composioManagedAuthSchemes = uniqueAuthModes(raw.composio_managed_auth_schemes);+ const authSchemes = uniqueAuthModes([+ ...authConfigDetails.map(detail => detail.mode),+ ...composioManagedAuthSchemes,+ ]);++ return {+ slug,+ name: raw.name || raw.slug || slug,+ logo: raw.meta.logo || null,+ description: raw.meta.description,+ category: category.success && category.data ? category.data : null,+ authSchemes,+ ...(composioManagedAuthSchemes.length > 0 ? { composioManagedAuthSchemes } : {}),+ toolCount: raw.meta.tools_count,+ triggerCount: raw.meta.triggers_count,+ version: raw.meta.version ?? null,+ tools: [],+ triggers: [],+ ...(authConfigDetails.length > 0 ? { authConfigDetails } : {}),+ };+}++function recordNegative(slug: string) {+ negativeCache.set(slug, Date.now() + NEGATIVE_CACHE_TTL_MS);+}++/** Fetch one toolkit's metadata from production after a checked-in snapshot miss. */+export async function fetchToolkitFromProduction(slug: string): Promise<Toolkit | null> {+ if (process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK === '0') return null;++ const apiKey = process.env.COMPOSIO_API_KEY;+ if (!apiKey) {+ console.warn(`[Toolkits] Production toolkit lookup skipped for "${slug}": missing API key`);+ return null;+ }++ const normalizedSlug = slug.toLowerCase();+ if (!TOOLKIT_SLUG_PATTERN.test(normalizedSlug)) return null;++ const negativeUntil = negativeCache.get(normalizedSlug);+ if (negativeUntil !== undefined) {+ if (negativeUntil > Date.now()) return null;+ negativeCache.delete(normalizedSlug);+ }++ try {+ const response = await fetch(`${PRODUCTION_API_V3_URL}/toolkits/${normalizedSlug}`, {+ headers: {+ 'Content-Type': 'application/json',+ 'x-api-key': apiKey,+ },+ next: { revalidate: 3600 },+ });++ if (!response.ok) {+ recordNegative(normalizedSlug);+ console.warn(+ `[Toolkits] Production toolkit lookup failed for "${normalizedSlug}": ${response.status}`+ );+ return null;+ }++ const payload = rawToolkitSchema.parse(await response.json());+ return toolkitFromRaw(payload, normalizedSlug);+ } catch (error) {+ recordNegative(normalizedSlug);+ const message = error instanceof Error ? error.message : String(error);+ console.warn(`[Toolkits] Production toolkit lookup failed for "${normalizedSlug}": ${message}`);+ return null;+ }+}diff --git a/docs/tests/static/toolkit-api.test.ts b/docs/tests/static/toolkit-api.test.tsnew file mode 100644index 000000000..fcd0fafb6--- /dev/null+++ b/docs/tests/static/toolkit-api.test.ts@@ -0,0 +1,298 @@+import { afterEach, describe, expect, mock, spyOn, test } from 'bun:test';+import { readFile } from 'fs/promises';+import { join } from 'path';+import { z } from 'zod';+import { fetchToolkitFromProduction } from '../../lib/toolkit-api';++const originalApiKey = process.env.COMPOSIO_API_KEY;+const originalApiBase = process.env.COMPOSIO_API_BASE;+const originalFallback = process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;+const originalFetch = globalThis.fetch;++const productionPayload = {+ slug: 'GitHub',+ name: 'GitHub',+ composio_managed_auth_schemes: ['oauth2', 'API_KEY'],+ auth_config_details: [+ {+ mode: 'OAuth2',+ name: 'github_oauth',+ fields: {+ auth_config_creation: {+ required: [+ {+ name: 'client_id',+ displayName: 'Client id',+ type: 'string',+ description: 'Client id of the app',+ },+ ],+ optional: [],+ },+ connected_account_initiation: { required: [], optional: [] },+ },+ },+ { mode: 'api_key', name: 'API key', fields: {} },+ ],+ meta: {+ logo: 'https://logos.composio.dev/api/github',+ description: 'GitHub description',+ categories: [{ name: 'developer tools' }],+ tools_count: 893,+ triggers_count: 20,+ version: '20260815_00',+ },+};++function useApiKey() {+ process.env.COMPOSIO_API_KEY = 'test-key';+ delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;+}++afterEach(() => {+ globalThis.fetch = originalFetch;+ mock.restore();++ if (originalApiKey === undefined) delete process.env.COMPOSIO_API_KEY;+ else process.env.COMPOSIO_API_KEY = originalApiKey;+ if (originalApiBase === undefined) delete process.env.COMPOSIO_API_BASE;+ else process.env.COMPOSIO_API_BASE = originalApiBase;+ if (originalFallback === undefined) delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;+ else process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK = originalFallback;+});++describe('fetchToolkitFromProduction', () => {+ test('maps the single-toolkit response and normalizes auth modes', async () => {+ useApiKey();+ const fetcher = mock(async () => Response.json(productionPayload));+ globalThis.fetch = fetcher;++ const toolkit = await fetchToolkitFromProduction('GitHub');++ expect(toolkit).toEqual({+ slug: 'github',+ name: 'GitHub',+ logo: 'https://logos.composio.dev/api/github',+ description: 'GitHub description',+ category: 'developer tools',+ authSchemes: ['OAUTH2', 'API_KEY'],+ composioManagedAuthSchemes: ['OAUTH2', 'API_KEY'],+ toolCount: 893,+ triggerCount: 20,+ version: '20260815_00',+ tools: [],+ triggers: [],+ authConfigDetails: [+ {+ mode: 'OAUTH2',+ name: 'github_oauth',+ fields: {+ auth_config_creation: {+ required: [+ {+ name: 'client_id',+ displayName: 'Client id',+ type: 'string',+ description: 'Client id of the app',+ required: true,+ default: null,+ },+ ],+ optional: [],+ },+ connected_account_initiation: { required: [], optional: [] },+ },+ },+ {+ mode: 'API_KEY',+ name: 'API key',+ fields: {+ auth_config_creation: { required: [], optional: [] },+ connected_account_initiation: { required: [], optional: [] },+ },+ },+ ],+ });+ expect(fetcher).toHaveBeenCalledTimes(1);+ expect(fetcher.mock.calls[0]?.[0]).toBe('https://backend.composio.dev/api/v3/toolkits/github');+ expect(fetcher.mock.calls[0]?.[1]).toEqual({+ headers: { 'Content-Type': 'application/json', 'x-api-key': 'test-key' },+ next: { revalidate: 3600 },+ });+ });++ test('matches the committed snapshot key set and metadata defaults', async () => {+ useApiKey();+ const snapshotSchema = z.array(+ z.object({+ slug: z.string(),+ name: z.string(),+ logo: z.string().nullable(),+ description: z.string(),+ category: z.string().nullable(),+ authSchemes: z.array(z.string()),+ composioManagedAuthSchemes: z.array(z.string()).optional(),+ toolCount: z.number(),+ triggerCount: z.number(),+ version: z.string().nullable(),+ tools: z.array(z.unknown()),+ triggers: z.array(z.unknown()),+ authConfigDetails: z.array(z.unknown()).optional(),+ })+ );+ const snapshots = snapshotSchema.parse(+ JSON.parse(await readFile(join(import.meta.dir, '../../public/data/toolkits.json'), 'utf8'))+ );+ const snapshot = snapshots.find(toolkit => toolkit.slug === 'github');+ expect(snapshot).toBeDefined();+ if (!snapshot) throw new Error('Expected committed GitHub toolkit snapshot');++ globalThis.fetch = mock(async () =>+ Response.json({+ slug: snapshot.slug,+ name: snapshot.name,+ composio_managed_auth_schemes: snapshot.composioManagedAuthSchemes,+ auth_config_details: snapshot.authConfigDetails,+ meta: {+ logo: snapshot.logo,+ description: snapshot.description,+ categories: snapshot.category ? [{ name: snapshot.category }] : [],+ tools_count: snapshot.toolCount,+ triggers_count: snapshot.triggerCount,+ version: snapshot.version,+ },+ })+ );++ const toolkit = await fetchToolkitFromProduction(snapshot.slug);+ expect(toolkit).not.toBeNull();+ expect(Object.keys(toolkit ?? {}).sort()).toEqual(+ Object.keys({ ...snapshot, tools: [], triggers: [] }).sort()+ );+ expect(toolkit?.authSchemes).toEqual(snapshot.authSchemes);+ expect(toolkit?.composioManagedAuthSchemes).toEqual(snapshot.composioManagedAuthSchemes);+ expect(toolkit?.version).toBe(snapshot.version);+ expect(toolkit?.tools).toEqual([]);+ expect(toolkit?.triggers).toEqual([]);+ });++ test('degrades missing metadata and malformed auth details without throwing', async () => {+ useApiKey();+ globalThis.fetch = mock(async () =>+ Response.json({+ slug: 'LENIENT',+ name: 'Lenient',+ auth_config_details: [+ null,+ 'junk',+ { name: 'missing mode' },+ {+ mode: 'oauth2',+ fields: {+ auth_config_creation: { required: [null], optional: [] },+ },+ },+ ],+ })+ );++ const toolkit = await fetchToolkitFromProduction('lenient');+ expect(toolkit).toMatchObject({+ slug: 'lenient',+ name: 'Lenient',+ logo: null,+ description: '',+ category: null,+ authSchemes: ['OAUTH2'],+ toolCount: 0,+ triggerCount: 0,+ version: null,+ tools: [],+ triggers: [],+ });+ expect(toolkit?.authConfigDetails).toHaveLength(1);+ expect(toolkit?.authConfigDetails?.[0]?.fields.auth_config_creation.required[0]).toEqual({+ name: '',+ displayName: '',+ type: 'string',+ description: '',+ required: true,+ default: null,+ });+ });++ test.each(['../etc', 'has space', 'A'.repeat(80), ''])(+ 'rejects invalid slug %p before fetch',+ async slug => {+ useApiKey();+ const fetcher = mock(async () => Response.json(productionPayload));+ globalThis.fetch = fetcher;++ expect(await fetchToolkitFromProduction(slug)).toBeNull();+ expect(fetcher).not.toHaveBeenCalled();+ }+ );++ test('requires an API key and warns without fetching', async () => {+ delete process.env.COMPOSIO_API_KEY;+ delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;+ const fetcher = mock(async () => Response.json(productionPayload));+ globalThis.fetch = fetcher;+ const warning = spyOn(console, 'warn').mockImplementation(() => {});++ expect(await fetchToolkitFromProduction('missing-key')).toBeNull();+ expect(fetcher).not.toHaveBeenCalled();+ expect(warning).toHaveBeenCalledTimes(1);+ });++ test('reads the kill switch on every call', async () => {+ useApiKey();+ const fetcher = mock(async () => Response.json({ ...productionPayload, slug: 'toggle' }));+ globalThis.fetch = fetcher;+ process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK = '0';++ expect(await fetchToolkitFromProduction('toggle')).toBeNull();+ delete process.env.COMPOSIO_TOOLKIT_LIVE_FALLBACK;+ expect(await fetchToolkitFromProduction('toggle')).not.toBeNull();+ expect(fetcher).toHaveBeenCalledTimes(1);+ });++ test('ignores COMPOSIO_API_BASE when building the production URL', async () => {+ useApiKey();+ process.env.COMPOSIO_API_BASE = 'https://staging-backend.composio.dev/api/v3';+ const fetcher = mock(async () => Response.json(productionPayload));+ globalThis.fetch = fetcher;++ await fetchToolkitFromProduction('github');+ expect(fetcher.mock.calls[0]?.[0]).toBe('https://backend.composio.dev/api/v3/toolkits/github');+ });++ test('negative-caches a 404 for 60 seconds, then retries', async () => {+ useApiKey();+ const fetcher = mock(async () => new Response(null, { status: 404 }));+ globalThis.fetch = fetcher;+ const warning = spyOn(console, 'warn').mockImplementation(() => {});+ const now = spyOn(Date, 'now').mockReturnValue(1_000);++ expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();+ expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();+ expect(fetcher).toHaveBeenCalledTimes(1);++ now.mockReturnValue(61_001);+ expect(await fetchToolkitFromProduction('cache-miss')).toBeNull();+ expect(fetcher).toHaveBeenCalledTimes(2);+ expect(warning).toHaveBeenCalledTimes(2);+ });++ test.each([+ ['500 response', async () => new Response(null, { status: 500 })],+ ['network error', async () => Promise.reject(new Error('offline'))],+ ['invalid JSON', async () => new Response('{', { status: 200 })],+ ])('returns null for %s without throwing', async (_label, responseFactory) => {+ useApiKey();+ globalThis.fetch = mock(responseFactory);+ spyOn(console, 'warn').mockImplementation(() => {});++ expect(await fetchToolkitFromProduction(`failure-${_label.replaceAll(' ', '-')}`)).toBeNull();+ });+});