@devries-cameron20 / composio-1 / commits / 64f4c0692
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.

feat(docs): filter Instant toolkits and match dashboard icons

palash-c committed Oct 8, 2026 at 01:46 UTC 64f4c0692dfe162d0d5f0edbc10122474add1d7b
9 files changed +224 -23
docs/app/api/toolkits/instant/route.ts new
+12
@@ -0,0 +1,12 @@
1 +import { fetchInstantToolkitSlugs } from '@/lib/instant-toolkit-api';
2 +
3 +export async function GET() {
4 + const apiKey = process.env.COMPOSIO_API_KEY;
5 + if (!apiKey) return Response.json({ error: 'Instant toolkit availability is temporarily unavailable.' }, { status: 503 });
6 + try {
7 + const slugs = await fetchInstantToolkitSlugs(apiKey);
8 + return Response.json({ slugs }, { headers: { 'Cache-Control': 'public, s-maxage=300, stale-while-revalidate=600' } });
9 + } catch {
10 + return Response.json({ error: 'Instant toolkit availability is temporarily unavailable.' }, { status: 503 });
11 + }
12 +}
docs/components/toolkits/instant-badge.tsx
+4 -1
@@ -1,6 +1,9 @@
1 +import { InstantBolt } from './instant-bolt';
2 +
3 export function InstantBadge() {
4 return (
3 - <span className="shrink-0 rounded bg-fd-accent px-1.5 py-0.5 text-xs font-medium text-fd-foreground" title="Instant is supported on the latest version">
5 + <span className="inline-flex shrink-0 items-center gap-1 text-xs font-medium text-fd-muted-foreground" title="Instant is supported on the latest version">
6 + <InstantBolt className="size-3.5" />
7 Instant
8 </span>
9 );
docs/components/toolkits/instant-bolt.tsx new
+14
@@ -0,0 +1,14 @@
1 +import type { SVGProps } from 'react';
2 +
3 +// Exact Nucleo IconBoltOutline18 / IconBoltFill18 paths used by the dashboard.
4 +export function InstantBolt({ filled = false, ...props }: SVGProps<SVGSVGElement> & { filled?: boolean }) {
5 + return (
6 + <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" aria-hidden="true" {...props}>
7 + {filled ? (
8 + <path d="M15.6449 7.0522C15.474 6.7114 15.1317 6.5 14.7504 6.5H10.2948L10.559 2.0312C10.5844 1.6025 10.3305 1.2148 9.9272 1.0668C9.5244 0.920302 9.0791 1.0507 8.8222 1.3949L2.4492 9.9008C2.2207 10.206 2.185 10.6069 2.3554 10.9477C2.5258 11.2885 2.8686 11.4999 3.2494 11.4999H7.705L7.4408 15.9687C7.4154 16.3974 7.6693 16.7851 8.0726 16.9331C8.1825 16.9731 8.2957 16.9927 8.4076 16.9927C8.705 16.9927 8.9906 16.855 9.1776 16.605L15.5511 8.0991C15.7791 7.7944 15.8153 7.393 15.6449 7.0522Z" fill="currentColor" />
9 + ) : (
10 + <path d="M14.7505 7.25H9.49905L9.81065 1.9868C9.82325 1.7732 9.55085 1.6734 9.42255 1.8446L3.04965 10.3501C2.92615 10.5149 3.04376 10.75 3.24976 10.75H8.50115L8.18955 16.0132C8.17695 16.2268 8.44935 16.3266 8.57765 16.1554L14.9506 7.6499C15.0741 7.4851 14.9565 7.25 14.7505 7.25Z" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" fill="none" />
11 + )}
12 + </svg>
13 + );
14 +}
docs/components/toolkits/toolkits-landing.tsx
+49 -21
@@ -1,16 +1,18 @@
1 'use client';
2
3 import { InstantBadge } from './instant-badge';
4 +import { InstantBolt } from './instant-bolt';
5 +import { filterToolkits, instantToolkitSlugsSchema, withInstantEligibility } from '@/lib/instant-toolkit-filter';
6
5 -import { useState, useMemo, useDeferredValue } from 'react';
7 +import { useState, useMemo, useDeferredValue, useEffect } from 'react';
8 import Link from 'next/link';
7 -import { Search, Sparkles, Wrench, Zap, Copy, Check, ExternalLink, Grip, ShieldCheck } from 'lucide-react';
9 +import { Search, Wrench, Zap, Copy, Check, ExternalLink, Grip, ShieldCheck } from 'lucide-react';
10 import { Card, Cards } from 'fumadocs-ui/components/card';
11 import toolkitsData from '@/public/data/toolkits-list.json';
12 import type { ToolkitSummary } from '@/types/toolkit';
13 import { PageActions } from '@/components/page-actions';
14
13 -const toolkits = toolkitsData as ToolkitSummary[];
15 +const snapshot: ToolkitSummary[] = toolkitsData;
16
17 // Popular toolkit slugs (shown at top when no filters)
18 const POPULAR_SLUGS = [
@@ -101,6 +103,24 @@ function ToolkitRow({ toolkit, lazy = true }: { toolkit: ToolkitSummary; lazy?:
103
104 export function ToolkitsLanding() {
105 const [search, setSearch] = useState('');
106 + const [instantOnly, setInstantOnly] = useState(false);
107 + const [eligibility, setEligibility] = useState<string[] | null>(null);
108 + const [eligibilityFailed, setEligibilityFailed] = useState(false);
109 + const [retry, setRetry] = useState(0);
110 + useEffect(() => {
111 + const controller = new AbortController();
112 + fetch('/api/toolkits/instant', { signal: controller.signal })
113 + .then(async response => {
114 + if (!response.ok) throw new Error('Availability unavailable');
115 + return instantToolkitSlugsSchema.parse(await response.json());
116 + })
117 + .then(data => setEligibility(data.slugs))
118 + .catch(() => { if (!controller.signal.aborted) setEligibilityFailed(true); });
119 + return () => controller.abort();
120 + }, [retry]);
121 + const toolkits = useMemo(() => eligibility === null ? snapshot : withInstantEligibility(snapshot, eligibility), [eligibility]);
122 + const instantUnavailable = instantOnly && eligibility === null;
123 + const clearFilters = () => { setSearch(''); setInstantOnly(false); };
124 const deferredSearch = useDeferredValue(search);
125
126 // Get popular toolkits
@@ -108,18 +128,11 @@ export function ToolkitsLanding() {
128 return POPULAR_SLUGS
129 .map((slug) => toolkits.find((t) => t.slug === slug))
130 .filter((t): t is ToolkitSummary => t !== undefined);
111 - }, []);
131 + }, [toolkits]);
132
133 const filteredToolkits = useMemo(() => {
114 - if (!deferredSearch) return toolkits;
115 -
116 - const searchLower = deferredSearch.toLowerCase();
117 - return toolkits.filter(
118 - (toolkit) =>
119 - toolkit.name.toLowerCase().includes(searchLower) ||
120 - toolkit.slug.toLowerCase().includes(searchLower)
121 - );
122 - }, [deferredSearch]);
134 + return filterToolkits(toolkits, deferredSearch, instantOnly);
135 + }, [toolkits, deferredSearch, instantOnly]);
136
137 // Group by first letter (numbers at end)
138 const groupedToolkits = useMemo(() => {
@@ -185,9 +198,19 @@ export function ToolkitsLanding() {
198 {/* Cards */}
199 <Cards>
200 <Card icon={<ShieldCheck />} title="Managed OAuth apps" href="/toolkits/managed-auth" description="Check which toolkits have managed OAuth" />
188 - <Card icon={<Sparkles />} title="Instant Tools" href="/docs/instant-tools" description="Run supported tools on Composio accounts" />
201 + <button
202 + type="button"
203 + aria-pressed={instantOnly}
204 + onClick={() => setInstantOnly(value => !value)}
205 + className={`not-prose rounded-xl border p-4 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 ${instantOnly ? 'border-blue-500 bg-blue-500/10' : 'border-fd-border bg-fd-card hover:bg-fd-accent'}`}
206 + >
207 + <InstantBolt filled={instantOnly} className={`mb-2 size-5 ${instantOnly ? 'text-blue-500' : 'text-fd-muted-foreground'}`} />
208 + <span className="block font-medium text-fd-card-foreground">Instant Tools</span>
209 + <span className="mt-1 block text-sm text-fd-muted-foreground">Show toolkits with Instant tools</span>
210 + </button>
211 <Card icon={<Wrench />} title="Meta Tools" href="/toolkits/meta-tools" description="The system tools every session gives your agent" />
212 </Cards>
213 + <Link href="/docs/instant-tools" className="inline-flex text-sm text-fd-primary hover:underline">Read the Instant Tools guide →</Link>
214
215 {/* Search */}
216 <div className="relative">
@@ -205,13 +228,18 @@ export function ToolkitsLanding() {
228 </div>
229
230 {/* Results count */}
208 - <p className="text-sm text-fd-muted-foreground">
231 + {!instantUnavailable && <p className="text-sm text-fd-muted-foreground" role="status">
232 {filteredToolkits.length} toolkit{filteredToolkits.length !== 1 ? 's' : ''}
233 + {instantOnly && ' with Instant tools'}
234 {deferredSearch && ` matching "${deferredSearch}"`}
211 - </p>
235 + </p>}
236 + {(instantOnly || search) && <button type="button" onClick={clearFilters} className="text-sm text-fd-primary hover:underline">Clear filters</button>}
237 + {instantUnavailable && <div role="status" className="py-8 text-center text-sm text-fd-muted-foreground">
238 + {eligibilityFailed ? <><p>Instant toolkit availability could not be loaded.</p><button type="button" onClick={() => { setEligibilityFailed(false); setRetry(value => value + 1); }} className="mt-2 text-fd-primary hover:underline">Try again</button></> : 'Loading Instant toolkits…'}
239 + </div>}
240
241 {/* Popular Toolkits - only show when no search */}
214 - {!deferredSearch && popularToolkits.length > 0 && (
242 + {!instantOnly && !deferredSearch && popularToolkits.length > 0 && (
243 <div>
244 <h2 className="mb-2 text-sm font-semibold text-fd-muted-foreground">Popular</h2>
245 <div className="divide-y divide-fd-border">
@@ -223,7 +251,7 @@ export function ToolkitsLanding() {
251 )}
252
253 {/* Alphabetically grouped list - table style */}
226 - {groupedToolkits.length > 0 ? (
254 + {!instantUnavailable && (groupedToolkits.length > 0 ? (
255 <div className="space-y-6">
256 {groupedToolkits.map(([letter, items]) => (
257 <div key={letter}>
@@ -240,13 +268,13 @@ export function ToolkitsLanding() {
268 <div className="py-12 text-center">
269 <p className="text-fd-muted-foreground">No toolkits found.</p>
270 <button
243 - onClick={() => setSearch('')}
271 + onClick={clearFilters}
272 className="mt-2 text-sm text-fd-primary hover:underline"
273 >
246 - Clear search
274 + Clear filters
275 </button>
276 </div>
249 - )}
277 + ))}
278 </div>
279 );
280 }
docs/decisions/README.md
+1 -1
@@ -11,5 +11,5 @@ Read these when a docs change touches an existing architecture, generated-data p
11 search, and Composio For You snapshot rules.
12 - `toolkit-page-availability.md` - docs-sync permissions, optional KB isolation,
13 and snapshot-miss toolkit page fallback.
14 -- `toolkits.md` - toolkit page data and rendering decisions.
14 +- `toolkits.md` - toolkit page data, rendering, and live Instant eligibility filter decisions.
15 - `cookbooks-revamp-plan.md` - historical cookbook revamp tracker.
docs/decisions/toolkits.md
+7
@@ -21,6 +21,13 @@
21 - Landing page shows search + category filter + cards
22 - Don't render all 855 cards upfront
23 - Filter client-side from pre-generated JSON
24 +- The Instant Tools card toggles an eligibility filter and intersects with search.
25 + The guide remains a separate link. Instant eligibility is refreshed through the
26 + server-only `/api/toolkits/instant` route from the paginated production catalog,
27 + cached for five minutes and merged only into existing snapshot rows. Missing
28 + eligibility or failed requests show a retry state, not a false empty catalog.
29 + The API key stays on the server. Neutral Nucleo outline bolts match the
30 + dashboard; a filled bolt denotes the selected filter, not project access.
31
32 ### Build-Time Generation
33 - `bun run generate:toolkits` - separate command
docs/lib/instant-toolkit-api.ts new
+44
@@ -0,0 +1,44 @@
1 +import { z } from 'zod';
2 +import { PRODUCTION_API_V3_URL } from '../scripts/production-api.mjs';
3 +import { isPublicToolkitSlug } from './public-toolkit-policy';
4 +
5 +const pageSchema = z.object({
6 + items: z.array(z.object({
7 + slug: z.string().min(1),
8 + instant: z.object({ supported: z.boolean() }).nullish(),
9 + })),
10 + next_cursor: z.string().nullish(),
11 +});
12 +
13 +// Called only by the server route. Never return partial pages as a complete list.
14 +export async function fetchInstantToolkitSlugs(apiKey: string, fetcher: typeof fetch = fetch): Promise<string[]> {
15 + const slugs = new Set<string>();
16 + const cursors = new Set<string>();
17 + let cursor: string | undefined;
18 + let hasEligibility = false;
19 + const signal = AbortSignal.timeout(15000);
20 + for (let page = 0; page < 12; page++) {
21 + const params = new URLSearchParams({ limit: '1000', include_pricing: 'true' });
22 + if (cursor) params.set('cursor', cursor);
23 + const response = await fetcher(`${PRODUCTION_API_V3_URL}/toolkits?${params}`, {
24 + headers: { 'x-api-key': apiKey },
25 + next: { revalidate: 300 },
26 + signal,
27 + });
28 + if (!response.ok) throw new Error('Toolkit eligibility unavailable');
29 + const data = pageSchema.parse(await response.json());
30 + for (const toolkit of data.items) {
31 + if (toolkit.instant != null) hasEligibility = true;
32 + const slug = toolkit.slug.toLowerCase();
33 + if (toolkit.instant?.supported === true && isPublicToolkitSlug(slug)) slugs.add(slug);
34 + }
35 + if (!data.next_cursor) {
36 + if (!hasEligibility) throw new Error('Toolkit eligibility missing');
37 + return [...slugs];
38 + }
39 + if (cursors.has(data.next_cursor)) throw new Error('Repeated toolkit cursor');
40 + cursors.add(data.next_cursor);
41 + cursor = data.next_cursor;
42 + }
43 + throw new Error('Toolkit eligibility pagination incomplete');
44 +}
docs/lib/instant-toolkit-filter.ts new
+17
@@ -0,0 +1,17 @@
1 +import { z } from 'zod';
2 +import type { ToolkitSummary } from '../types/toolkit';
3 +
4 +export const instantToolkitSlugsSchema = z.object({ slugs: z.array(z.string()) });
5 +
6 +export function filterToolkits(toolkits: ToolkitSummary[], search: string, instantOnly: boolean) {
7 + const query = search.trim().toLowerCase();
8 + return toolkits.filter(toolkit =>
9 + (!instantOnly || toolkit.instant?.supported === true) &&
10 + (!query || toolkit.name.toLowerCase().includes(query) || toolkit.slug.toLowerCase().includes(query))
11 + );
12 +}
13 +
14 +export function withInstantEligibility(toolkits: ToolkitSummary[], slugs: string[]): ToolkitSummary[] {
15 + const supported = new Set(slugs.map(slug => slug.toLowerCase()));
16 + return toolkits.map(toolkit => ({ ...toolkit, instant: { supported: supported.has(toolkit.slug.toLowerCase()) } }));
17 +}
docs/tests/static/instant-toolkit-filter.test.tsx new
+76
@@ -0,0 +1,76 @@
1 +import { describe, expect, test, mock } from 'bun:test';
2 +import { renderToStaticMarkup } from 'react-dom/server';
3 +import { readFileSync } from 'node:fs';
4 +import { filterToolkits, withInstantEligibility } from '../../lib/instant-toolkit-filter';
5 +import { fetchInstantToolkitSlugs } from '../../lib/instant-toolkit-api';
6 +import { InstantBolt } from '../../components/toolkits/instant-bolt';
7 +import { InstantBadge } from '../../components/toolkits/instant-badge';
8 +
9 +const toolkits = [
10 + { slug: 'alpha', name: 'Alpha search', instant: { supported: true } },
11 + { slug: 'beta', name: 'Beta search', instant: { supported: false } },
12 + { slug: 'gamma', name: 'Gamma' },
13 +].map(toolkit => ({ ...toolkit, logo: null, category: null, toolCount: 1, triggerCount: 0 }));
14 +
15 +describe('Instant catalog filter', () => {
16 + test('strict eligibility intersects name/slug search; clearing restores all', () => {
17 + expect(filterToolkits(toolkits, '', true).map(t => t.slug)).toEqual(['alpha']);
18 + expect(filterToolkits(toolkits, ' SEARCH ', true).map(t => t.slug)).toEqual(['alpha']);
19 + expect(filterToolkits(toolkits, 'beta', true)).toEqual([]);
20 + expect(filterToolkits(toolkits, 'GAMMA', false).map(t => t.slug)).toEqual(['gamma']);
21 + expect(filterToolkits(toolkits, '', false)).toEqual(toolkits);
22 + });
23 +
24 + test('live eligibility updates only existing public snapshot rows, replacing stale support', () => {
25 + const merged = withInstantEligibility(toolkits, ['GAMMA', 'not-in-snapshot']);
26 + expect(filterToolkits(merged, '', true).map(t => t.slug)).toEqual(['gamma']);
27 + expect(merged).toHaveLength(toolkits.length);
28 + });
29 +
30 + test('the card is a toggle, guide is separate, popular rows hide during filtering', () => {
31 + const source = readFileSync(new URL('../../components/toolkits/toolkits-landing.tsx', import.meta.url), 'utf8');
32 + expect(source).toContain('aria-pressed={instantOnly}');
33 + expect(source).toContain('href="/docs/instant-tools"');
34 + expect(source).toContain('setSearch(\'\'); setInstantOnly(false)');
35 + expect(source).toContain('!instantOnly && !deferredSearch');
36 + expect(source).toContain('Instant toolkit availability could not be loaded.');
37 + });
38 +
39 + test('uses the exact dashboard Nucleo bolt geometry, with neutral outline badges', () => {
40 + const outline = renderToStaticMarkup(<InstantBolt />);
41 + const filled = renderToStaticMarkup(<InstantBolt filled />);
42 + expect(outline).toContain('viewBox="0 0 18 18"');
43 + expect(outline).toContain('M14.7505 7.25H9.49905');
44 + expect(outline).toContain('stroke-width="1.5"');
45 + expect(filled).toContain('M15.6449 7.0522C15.474');
46 + expect(filled).not.toContain('stroke-width');
47 + expect(renderToStaticMarkup(<InstantBadge />)).toContain('M14.7505 7.25H9.49905');
48 + });
49 +});
50 +
51 +describe('live Instant eligibility', () => {
52 + const item = (slug: string, supported = true) => ({ slug, type: 'native', enabled: true, instant: { supported } });
53 + const fakeFetch = (fn: (input: Parameters<typeof fetch>[0], init?: RequestInit) => Promise<Response>) => Object.assign(mock(fn), { preconnect: fetch.preconnect });
54 +
55 + test('follows cursors, requests pricing, deduplicates and only accepts explicit support', async () => {
56 + const fetcher = fakeFetch(async input => String(input).includes('cursor=next')
57 + ? Response.json({ items: [item('ALPHA'), item('beta'), item('no', false)], next_cursor: null })
58 + : Response.json({ items: [item('alpha'), { slug: 'null', instant: null }, { slug: 'missing' }], next_cursor: 'next' }));
59 + expect(await fetchInstantToolkitSlugs('test-key', fetcher)).toEqual(['alpha', 'beta']);
60 + expect(fetcher).toHaveBeenCalledTimes(2);
61 + expect(String(fetcher.mock.calls[0][0])).toContain('include_pricing=true');
62 + expect(fetcher.mock.calls[0][1]?.headers).toEqual({ 'x-api-key': 'test-key' });
63 + });
64 +
65 + test('partial responses, missing eligibility, malformed data and repeated cursors fail rather than imply no results', async () => {
66 + for (const payload of [{ items: [{ slug: 'alpha' }] }, { items: [{ slug: 'alpha', instant: { supported: 'true' } }] }, { items: [item('alpha')], next_cursor: 'loop' }]) {
67 + await expect(fetchInstantToolkitSlugs('test-key', fakeFetch(async () => Response.json(payload)))).rejects.toThrow();
68 + }
69 + let calls = 0;
70 + await expect(fetchInstantToolkitSlugs('test-key', fakeFetch(async () => ++calls === 1 ? Response.json({ items: [item('alpha')], next_cursor: 'next' }) : new Response('', { status: 503 })))).rejects.toThrow();
71 + });
72 +
73 + test('explicit all-false metadata is a genuine empty result', async () => {
74 + expect(await fetchInstantToolkitSlugs('test-key', fakeFetch(async () => Response.json({ items: [item('alpha', false)] })))).toEqual([]);
75 + });
76 +});