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

refactor(docs): parse untyped data with zod and forbid explicit any (#3967)

This PR: - builds on top of https://github.com/ComposioHQ/composio/pull/3966 - enables `typescript/no-explicit-any` (error, `fixToUnknown`) for docs in `docs/.oxlintrc.json` and removes every remaining explicit `any` in docs code - parses untyped/external data once at the boundary with zod v4 schemas and lets `z.infer` types flow downstream — no hand-rolled `'x' in obj` guard chains, no `as`-casts of untyped page data, no `docs/lib/unknown-value.ts` - adds domain schema modules: `docs/lib/toolkit-schema.ts` (recursive JSON-Schema node, raw tool/trigger payloads, list envelopes) and `docs/lib/reference-page-data.ts` (fumadocs reference page data for both reference routes) - rewrites `validate-links.ts`, `generate-toolkits.ts`, `generate-meta-tools.ts`, the `llms.mdx` route, and `deprecated-api-sidebar.tsx` on those schemas with identical validation outcomes - carries the pure typing improvements from the earlier attempt (typed reference source in `source.ts`, `LLMPage`/`PageLike`, typed `ClientLogo[]` in `logo-bar.tsx`, component `any` removals) - adds `tests/static/toolkit-schema.test.ts` and `tests/static/generate-toolkits.test.ts` pinning the transform shapes; no changeset (docs is not published) ## Context Second of the three-PR split of #3958, replacing its rejected structural-guard approach with zod schemas at the data boundaries. Verified with `bun run lint`, `bun run types:check`, `bun test tests/static/` (125 pass), `bun run lint:links`, and a full `next build`. ## Review follow-up Addressed the regressions reported in [the Zod boundary re-review](https://github.com/ComposioHQ/composio/pull/3967#issuecomment-5105279224): scalar JSON Schema enums and auth defaults are preserved as strings, malformed toolkit page envelopes abort generation, and the pre-refactor empty-string fallbacks are restored. Regression coverage lives in `tests/static/toolkit-schema.test.ts` and `tests/static/generate-toolkits.test.ts`. Verified on `2f26c40be` with `bun test tests/static/` (125 pass), `bun run types:check`, and `bun run lint` (0 errors; existing warnings only).

Alberto Schiabel committed Aug 3, 2026 at 19:52 UTC 61aafbc9d341bbf5b3bd1eb58dc7f414d523096b
27 files changed +1728 -620
docs/.oxlintrc.json
+8 -8
@@ -5,7 +5,7 @@
5 // rules, plus the two classic hooks rules (rules-of-hooks, exhaustive-deps).
6 // Dashboard-link policy uses the same ESLint-compatible no-restricted-syntax
7 // plugin as the root workspace config.
8 - "plugins": ["nextjs", "react", "import", "jsx-a11y"],
8 + "plugins": ["typescript", "nextjs", "react", "import", "jsx-a11y"],
9 "jsPlugins": [{ "name": "eslint-js", "specifier": "oxlint-plugin-eslint" }],
10 "categories": {
11 "correctness": "off"
@@ -13,14 +13,14 @@
13 "env": {
14 "builtin": true
15 },
16 - "ignorePatterns": [
17 - ".next/**",
18 - "out/**",
19 - "build/**",
20 - "next-env.d.ts",
21 - ".source/**"
22 - ],
16 + "ignorePatterns": [".next/**", "out/**", "build/**", "next-env.d.ts", ".source/**"],
17 "rules": {
18 + "typescript/no-explicit-any": [
19 + "error",
20 + {
21 + "fixToUnknown": true
22 + }
23 + ],
24 "nextjs/google-font-display": "warn",
25 "nextjs/google-font-preconnect": "warn",
26 "nextjs/next-script-for-ga": "warn",
docs/app/(home)/docs/[[...slug]]/page.tsx
+3 -9
@@ -1,9 +1,5 @@
1 import { getOgImageUrl, source } from '@/lib/source';
2 -import {
3 - DocsBody,
4 - DocsPage,
5 - DocsTitle,
6 -} from 'fumadocs-ui/layouts/docs/page';
2 +import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
3 import { notFound } from 'next/navigation';
4 import { getMDXComponents } from '@/mdx-components';
5 import type { Metadata } from 'next';
@@ -19,7 +15,7 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
15 const page = source.getPage(params.slug);
16 if (!page) notFound();
17
22 - const data = page.data as any;
18 + const data = page.data;
19 const MDX = data.body;
20 const isLanding = !params.slug || params.slug.length === 0;
21
@@ -67,9 +63,7 @@ export async function generateStaticParams() {
63 return source.generateParams();
64 }
65
70 -export async function generateMetadata(
71 - props: PageProps<'/docs/[[...slug]]'>,
72 -): Promise<Metadata> {
66 +export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise<Metadata> {
67 const params = await props.params;
68 const page = source.getPage(params.slug);
69 if (!page) notFound();
docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
+25 -30
@@ -1,41 +1,30 @@
1 import { getReferenceSource, getOgImageUrl } from '@/lib/source';
2 import { APIPage } from '@/components/api-page';
3 -import {
4 - DocsBody,
5 - DocsPage,
6 - DocsTitle,
7 -} from 'fumadocs-ui/layouts/docs/page';
3 +import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
4 import { notFound } from 'next/navigation';
5 import { getMDXComponents } from '@/mdx-components';
6 import type { Metadata } from 'next';
7 import { createRelativeLink } from 'fumadocs-ui/mdx';
12 -import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
8 import { PageActions } from '@/components/page-actions';
9 import { EditOnGitHub } from '@/components/edit-on-github';
10 import { extractVersionFromPath } from '@/components/version-badge';
11 import { ApiPageTitle } from '@/components/api-page-title';
12 import { isApiPageDeprecated } from '@/lib/api-deprecation';
13 import { sliceApiPageProps } from '@/lib/openapi-slice';
19 -import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
20 -
21 -interface OpenAPIPageData extends OpenApiSchemaPageData {
22 - title: string;
23 - description?: string;
24 - getOpenAPIPageProps: () => OpenAPIPageProps;
25 -}
14 +import {
15 + openApiReferencePageDataSchema,
16 + referenceMdxPageDataSchema,
17 +} from '@/lib/reference-page-data';
18
27 -export default async function Page({
28 - params,
29 -}: {
30 - params: Promise<{ slug?: string[] }>;
31 -}) {
19 +export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
20 const { slug } = await params;
21 const referenceSource = await getReferenceSource();
22 const page = referenceSource.getPage(slug);
23 if (!page) notFound();
24
37 - if ('getOpenAPIPageProps' in page.data) {
38 - const pageData = page.data as OpenAPIPageData;
25 + const openApiData = openApiReferencePageDataSchema.safeParse(page.data);
26 + if (openApiData.success) {
27 + const pageData = openApiData.data;
28 const apiProps = pageData.getOpenAPIPageProps();
29 const detectedVersion = apiProps.operations?.[0]?.path
30 ? extractVersionFromPath(apiProps.operations[0].path)
@@ -44,11 +33,7 @@ export default async function Page({
33 return (
34 <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
35 <div className="mb-4 flex items-start justify-between gap-4">
47 - <ApiPageTitle
48 - title={pageData.title}
49 - version={detectedVersion}
50 - deprecated={deprecated}
51 - />
36 + <ApiPageTitle title={pageData.title} version={detectedVersion} deprecated={deprecated} />
37 <PageActions path={page.url} variant="inline" />
38 </div>
39 <DocsBody>
@@ -59,17 +44,22 @@ export default async function Page({
44 );
45 }
46
62 - const mdxData = page.data as any;
47 + const mdxData = referenceMdxPageDataSchema.parse(page.data);
48 const MDX = mdxData.body;
49
50 return (
66 - <DocsPage toc={mdxData.toc} full={mdxData.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
51 + <DocsPage
52 + toc={mdxData.toc}
53 + full={mdxData.full}
54 + footer={{ enabled: false }}
55 + tableOfContentPopover={{ enabled: false }}
56 + >
57 <DocsTitle>{mdxData.title}</DocsTitle>
58 <PageActions path={page.url} />
59 <DocsBody>
60 <MDX
61 components={getMDXComponents({
72 - a: createRelativeLink(referenceSource as any, page),
62 + a: createRelativeLink(referenceSource, page),
63 })}
64 />
65 <EditOnGitHub path={`docs/content/reference/${page.path}`} />
@@ -82,7 +72,7 @@ export async function generateStaticParams() {
72 const referenceSource = await getReferenceSource();
73 const allParams: { slug: string[] }[] = referenceSource.generateParams();
74 // Exclude v3 pages — those are handled by the /reference/v3/ route
85 - return allParams.filter((p) => p.slug[0] !== 'v3');
75 + return allParams.filter(p => p.slug[0] !== 'v3');
76 }
77
78 export async function generateMetadata({
@@ -93,7 +83,12 @@ export async function generateMetadata({
83 const { slug } = await params;
84
85 if (!slug || slug.length === 0) {
96 - const ogImage = getOgImageUrl('reference', [], 'API Reference', 'REST API and SDK reference for Composio');
86 + const ogImage = getOgImageUrl(
87 + 'reference',
88 + [],
89 + 'API Reference',
90 + 'REST API and SDK reference for Composio'
91 + );
92 return {
93 title: 'API Reference',
94 description: 'REST API and SDK reference for Composio',
docs/app/(home)/reference/(v31)/layout.tsx
+1 -1
@@ -9,7 +9,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
9 const changelogPage = { type: 'page' as const, name: 'Changelog', url: '/reference/changelog' };
10 // Pin Changelog directly beneath Overview (the first/top entry) in the sidebar.
11 const overviewIdx = tree.children.findIndex(
12 - (child: { type: string; name?: string }) => child.type === 'page' && child.name === 'Overview'
12 + child => child.type === 'page' && child.name === 'Overview'
13 );
14 const insertIdx = overviewIdx === -1 ? Math.min(1, tree.children.length) : overviewIdx + 1;
15 const pageTree = {
docs/app/(home)/reference/v3/[[...slug]]/page.tsx
+25 -32
@@ -1,28 +1,20 @@
1 import { getReferenceSource, getOgImageUrl } from '@/lib/source';
2 import { APIPage } from '@/components/api-page';
3 -import {
4 - DocsBody,
5 - DocsPage,
6 - DocsTitle,
7 -} from 'fumadocs-ui/layouts/docs/page';
3 +import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
4 import { notFound } from 'next/navigation';
5 import { getMDXComponents } from '@/mdx-components';
6 import type { Metadata } from 'next';
7 import { createRelativeLink } from 'fumadocs-ui/mdx';
12 -import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
8 import { PageActions } from '@/components/page-actions';
9 import { EditOnGitHub } from '@/components/edit-on-github';
10 import { extractVersionFromPath } from '@/components/version-badge';
11 import { ApiPageTitle } from '@/components/api-page-title';
12 import { isApiPageDeprecated } from '@/lib/api-deprecation';
13 import { sliceApiPageProps } from '@/lib/openapi-slice';
19 -import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
20 -
21 -interface OpenAPIPageData extends OpenApiSchemaPageData {
22 - title: string;
23 - description?: string;
24 - getOpenAPIPageProps: () => OpenAPIPageProps;
25 -}
14 +import {
15 + openApiReferencePageDataSchema,
16 + referenceMdxPageDataSchema,
17 +} from '@/lib/reference-page-data';
18
19 /**
20 * Prepend 'v3' to the slug array since Next.js strips the /v3/ route segment
@@ -32,18 +24,15 @@ function toSourceSlug(slug?: string[]): string[] {
24 return ['v3', ...(slug || [])];
25 }
26
35 -export default async function Page({
36 - params,
37 -}: {
38 - params: Promise<{ slug?: string[] }>;
39 -}) {
27 +export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
28 const { slug } = await params;
29 const referenceSource = await getReferenceSource();
30 const page = referenceSource.getPage(toSourceSlug(slug));
31 if (!page) notFound();
32
45 - if ('getOpenAPIPageProps' in page.data) {
46 - const pageData = page.data as OpenAPIPageData;
33 + const openApiData = openApiReferencePageDataSchema.safeParse(page.data);
34 + if (openApiData.success) {
35 + const pageData = openApiData.data;
36 const apiProps = pageData.getOpenAPIPageProps();
37 const detectedVersion = apiProps.operations?.[0]?.path
38 ? extractVersionFromPath(apiProps.operations[0].path)
@@ -52,11 +41,7 @@ export default async function Page({
41 return (
42 <DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
43 <div className="mb-4 flex items-start justify-between gap-4">
55 - <ApiPageTitle
56 - title={pageData.title}
57 - version={detectedVersion}
58 - deprecated={deprecated}
59 - />
44 + <ApiPageTitle title={pageData.title} version={detectedVersion} deprecated={deprecated} />
45 <PageActions path={page.url} variant="inline" />
46 </div>
47 <DocsBody>
@@ -67,17 +52,22 @@ export default async function Page({
52 );
53 }
54
70 - const mdxData = page.data as any;
55 + const mdxData = referenceMdxPageDataSchema.parse(page.data);
56 const MDX = mdxData.body;
57
58 return (
74 - <DocsPage toc={mdxData.toc} full={mdxData.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
59 + <DocsPage
60 + toc={mdxData.toc}
61 + full={mdxData.full}
62 + footer={{ enabled: false }}
63 + tableOfContentPopover={{ enabled: false }}
64 + >
65 <DocsTitle>{mdxData.title}</DocsTitle>
66 <PageActions path={page.url} />
67 <DocsBody>
68 <MDX
69 components={getMDXComponents({
80 - a: createRelativeLink(referenceSource as any, page),
70 + a: createRelativeLink(referenceSource, page),
71 })}
72 />
73 <EditOnGitHub path={`docs/content/reference/${page.path}`} />
@@ -90,9 +80,7 @@ export async function generateStaticParams() {
80 const referenceSource = await getReferenceSource();
81 const allParams: { slug: string[] }[] = referenceSource.generateParams();
82 // Only return params that start with 'v3', with the prefix stripped
93 - return allParams
94 - .filter((p) => p.slug[0] === 'v3')
95 - .map((p) => ({ slug: p.slug.slice(1) }));
83 + return allParams.filter(p => p.slug[0] === 'v3').map(p => ({ slug: p.slug.slice(1) }));
84 }
85
86 export async function generateMetadata({
@@ -104,7 +92,12 @@ export async function generateMetadata({
92 const sourceSlug = toSourceSlug(slug);
93
94 if (!slug || slug.length === 0) {
107 - const ogImage = getOgImageUrl('reference', [], 'API Reference (v3)', 'REST API reference for Composio v3');
95 + const ogImage = getOgImageUrl(
96 + 'reference',
97 + [],
98 + 'API Reference (v3)',
99 + 'REST API reference for Composio v3'
100 + );
101 return {
102 title: 'API Reference (v3)',
103 description: 'REST API reference for Composio v3',
docs/app/(home)/toolkits/[[...slug]]/page.tsx
+31 -27
@@ -16,14 +16,17 @@ import { toHtml } from 'hast-util-to-html';
16 import type { Metadata } from 'next';
17 import type { Tool, Trigger } from '@/types/toolkit';
18 import type { FaqItem } from '@/components/toolkits/faq-section';
19 -import { processSchema, toolFromApi } from '@/lib/toolkit-schema';
19 +import { apiToolListSchema, apiTriggerListSchema } from '@/lib/toolkit-schema';
20
21 const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
22 const API_KEY = process.env.COMPOSIO_API_KEY;
23
24 // Fetch detailed tool info from Composio API (server-side only)
25 // Returns null on failure, empty array if toolkit has no tools
26 -async function fetchDetailedTools(toolkitSlug: string, version?: string | null): Promise<Tool[] | null> {
26 +async function fetchDetailedTools(
27 + toolkitSlug: string,
28 + version?: string | null
29 +): Promise<Tool[] | null> {
30 if (!API_KEY) {
31 console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed tool fetch');
32 return null;
@@ -46,11 +49,8 @@ async function fetchDetailedTools(toolkitSlug: string, version?: string | null):
49 return null;
50 }
51
49 - const data = await response.json();
50 - const rawItems = data.items || data;
51 - const items = Array.isArray(rawItems) ? rawItems : [];
52 -
53 - return items.filter((tool: any) => tool && typeof tool === 'object').map(toolFromApi);
52 + const parsed = apiToolListSchema.safeParse(await response.json());
53 + return parsed.success ? parsed.data : [];
54 } catch (error) {
55 console.error(`[Toolkits] Error fetching detailed tools for ${toolkitSlug}:`, error);
56 return null;
@@ -59,7 +59,10 @@ async function fetchDetailedTools(toolkitSlug: string, version?: string | null):
59
60 // Fetch detailed trigger info from Composio API (server-side only)
61 // Returns null on failure, empty array if toolkit has no triggers
62 -async function fetchDetailedTriggers(toolkitSlug: string, version?: string | null): Promise<Trigger[] | null> {
62 +async function fetchDetailedTriggers(
63 + toolkitSlug: string,
64 + version?: string | null
65 +): Promise<Trigger[] | null> {
66 if (!API_KEY) {
67 console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed trigger fetch');
68 return null;
@@ -82,21 +85,8 @@ async function fetchDetailedTriggers(toolkitSlug: string, version?: string | nul
85 return null;
86 }
87
85 - const data = await response.json();
86 - const rawItems = data.items || data;
87 - const items = Array.isArray(rawItems) ? rawItems : [];
88 -
89 - return items.filter((trigger: any) => trigger && typeof trigger === 'object').map((trigger: any) => {
90 - return {
91 - slug: trigger.slug || '',
92 - name: trigger.name || trigger.display_name || trigger.slug || '',
93 - description: trigger.description || '',
94 - type: trigger.type || undefined,
95 - config: processSchema(trigger.config),
96 - payload: processSchema(trigger.payload),
97 - instructions: trigger.instructions || undefined,
98 - };
99 - });
88 + const parsed = apiTriggerListSchema.safeParse(await response.json());
89 + return parsed.success ? parsed.data : [];
90 } catch (error) {
91 console.error(`[Toolkits] Error fetching detailed triggers for ${toolkitSlug}:`, error);
92 return null;
@@ -141,19 +131,28 @@ export async function generateStaticParams() {
131
132 // JSON toolkit pages
133 const toolkits = await getAllToolkits();
144 - const jsonParams = toolkits.map((toolkit) => ({
134 + const jsonParams = toolkits.map(toolkit => ({
135 slug: [toolkit.slug],
136 }));
137
138 return [indexParam, ...mdxParams, ...jsonParams];
139 }
140
151 -export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }): Promise<Metadata> {
141 +export async function generateMetadata({
142 + params,
143 +}: {
144 + params: Promise<{ slug?: string[] }>;
145 +}): Promise<Metadata> {
146 const { slug } = await params;
147
148 // Index page
149 if (!slug || slug.length === 0) {
156 - const ogImage = getOgImageUrl('toolkits', [], 'Toolkits', 'Browse all toolkits supported by Composio');
150 + const ogImage = getOgImageUrl(
151 + 'toolkits',
152 + [],
153 + 'Toolkits',
154 + 'Browse all toolkits supported by Composio'
155 + );
156 return {
157 title: 'Toolkits',
158 description: 'Browse all toolkits supported by Composio',
@@ -210,7 +209,12 @@ export default async function ToolkitsPage({ params }: { params: Promise<{ slug?
209 const MDXContent = page.data.body;
210 return (
211 <div>
213 - <Link href="/toolkits" className="text-sm text-fd-muted-foreground no-underline hover:text-fd-foreground hover:underline">← All Toolkits</Link>
212 + <Link
213 + href="/toolkits"
214 + className="text-sm text-fd-muted-foreground no-underline hover:text-fd-foreground hover:underline"
215 + >
216 + ← All Toolkits
217 + </Link>
218 <div className="mt-2 flex items-start justify-between gap-4">
219 <h1 className="text-3xl font-bold text-fd-foreground">{page.data.title}</h1>
220 <PageActions path={page.url} variant="inline" />
docs/app/llms-full.txt/route.ts
+18 -15
@@ -1,4 +1,11 @@
1 -import { getLLMText, source, examplesSource, referenceSource, toolkitsSource } from '@/lib/source';
1 +import {
2 + getLLMText,
3 + source,
4 + examplesSource,
5 + referenceSource,
6 + toolkitsSource,
7 + type LLMPage,
8 +} from '@/lib/source';
9 import { SESSION_GUARDRAILS } from '@/lib/llm-guardrails';
10 import type { ReactNode } from 'react';
11
@@ -26,14 +33,7 @@ interface FolderNode {
33 type TreeNode = PageNode | SeparatorNode | FolderNode;
34
35 // Generic page type that works for all sources
29 -interface PageLike {
30 - url: string;
31 - slugs: string[];
32 - data: {
33 - title: string;
34 - description?: string;
35 - };
36 -}
36 +type PageLike = LLMPage & { slugs: string[] };
37
38 /**
39 * Collect page URLs from the page tree in sidebar order.
@@ -115,9 +115,12 @@ function orderDocPages(pages: PageLike[], treeNodes: TreeNode[]): PageLike[] {
115
116 async function getTextForPages(pages: PageLike[]) {
117 return Promise.all(
118 - pages.map(async (page) => {
118 + pages.map(async page => {
119 try {
120 - return await getLLMText(page as any, { includeFooter: false, includeGuardrails: false });
120 + return await getLLMText(page, {
121 + includeFooter: false,
122 + includeGuardrails: false,
123 + });
124 } catch {
125 // Graceful fallback if getText fails
126 return `# ${page.data.title} (${page.url})\n\n${page.data.description || ''}`;
@@ -131,15 +134,15 @@ export async function GET() {
134 const treeChildren = source.pageTree.children as TreeNode[];
135 const legacyUrls = collectLegacyUrls(treeChildren);
136 const orderedDocsPages = orderDocPages(
134 - (source.getPages() as PageLike[]).filter((page) => !legacyUrls.has(page.url)),
137 + source.getPages().filter(page => !legacyUrls.has(page.url)),
138 treeChildren
139 );
140
141 const [docsResults, examplesResults, referenceResults, toolkitsResults] = await Promise.all([
142 getTextForPages(orderedDocsPages),
140 - getTextForPages(examplesSource.getPages() as PageLike[]),
141 - getTextForPages(referenceSource.getPages() as PageLike[]),
142 - getTextForPages(toolkitsSource.getPages() as PageLike[]),
143 + getTextForPages(examplesSource.getPages()),
144 + getTextForPages(referenceSource.getPages()),
145 + getTextForPages(toolkitsSource.getPages()),
146 ]);
147
148 const results = [
docs/app/llms.mdx/[[...slug]]/route.ts
+224 -124
@@ -8,6 +8,7 @@ import {
8 formatDate,
9 getLLMText,
10 mdxToCleanMarkdown,
11 + type LLMPage,
12 } from '@/lib/source';
13 import { dereferenceDocument } from '@/lib/openapi-deref';
14 import { notFound } from 'next/navigation';
@@ -17,7 +18,8 @@ import { getAllToolkits, getToolkitBySlug } from '@/lib/toolkit-data';
18 import { getAllMetaTools, getMetaToolBySlug } from '@/lib/meta-tools-data';
19 import type { MetaTool, MetaToolParameter } from '@/lib/meta-tools-data';
20 import type { Toolkit, Tool, Trigger, ParameterSchema } from '@/types/toolkit';
20 -import { processSchema, toolFromApi } from '@/lib/toolkit-schema';
21 +import { apiToolListSchema, apiTriggerListSchema } from '@/lib/toolkit-schema';
22 +import { z } from 'zod';
23
24 export const revalidate = false;
25
@@ -48,20 +50,19 @@ async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
50 return null;
51 }
52
51 - const data = await response.json();
52 - if (!data || typeof data !== 'object') {
53 + const parsed = apiToolListSchema.safeParse(await response.json());
54 + if (!parsed.success) {
55 console.warn(`[LLM Markdown] Invalid API response format for toolkit ${toolkitSlug}`);
56 return null;
57 }
58
57 - const rawItems = data.items || data;
58 - const items = Array.isArray(rawItems) ? rawItems : [];
59 -
60 - if (items.length >= API_FETCH_LIMIT) {
61 - console.warn(`[LLM Markdown] Toolkit ${toolkitSlug} has ${items.length}+ tools, results may be truncated`);
59 + if (parsed.data.length >= API_FETCH_LIMIT) {
60 + console.warn(
61 + `[LLM Markdown] Toolkit ${toolkitSlug} has ${parsed.data.length}+ tools, results may be truncated`
62 + );
63 }
64
64 - return items.filter((tool: any) => tool && typeof tool === 'object').map(toolFromApi);
65 + return parsed.data;
66 } catch {
67 return null;
68 }
@@ -86,32 +87,25 @@ async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | n
87 );
88
89 if (!response.ok) {
89 - console.warn(`[LLM Markdown] Failed to fetch triggers for ${toolkitSlug}: ${response.status}`);
90 + console.warn(
91 + `[LLM Markdown] Failed to fetch triggers for ${toolkitSlug}: ${response.status}`
92 + );
93 return null;
94 }
95
93 - const data = await response.json();
94 - if (!data || typeof data !== 'object') {
96 + const parsed = apiTriggerListSchema.safeParse(await response.json());
97 + if (!parsed.success) {
98 console.warn(`[LLM Markdown] Invalid API response format for triggers ${toolkitSlug}`);
99 return null;
100 }
101
99 - const rawItems = data.items || data;
100 - const items = Array.isArray(rawItems) ? rawItems : [];
101 -
102 - if (items.length >= API_FETCH_LIMIT) {
103 - console.warn(`[LLM Markdown] Toolkit ${toolkitSlug} has ${items.length}+ triggers, results may be truncated`);
102 + if (parsed.data.length >= API_FETCH_LIMIT) {
103 + console.warn(
104 + `[LLM Markdown] Toolkit ${toolkitSlug} has ${parsed.data.length}+ triggers, results may be truncated`
105 + );
106 }
107
106 - return items.filter((trigger: any) => trigger && typeof trigger === 'object').map((trigger: any) => ({
107 - slug: trigger.slug || '',
108 - name: trigger.name || trigger.display_name || trigger.slug || '',
109 - description: trigger.description || '',
110 - type: trigger.type,
111 - config: processSchema(trigger.config),
112 - payload: processSchema(trigger.payload),
113 - instructions: trigger.instructions,
114 - }));
108 + return parsed.data;
109 } catch {
110 return null;
111 }
@@ -188,6 +182,54 @@ interface OpenAPIPageData {
182 };
183 }
184
185 +// Fumadocs page data is untyped across the mixed sources this route serves, so
186 +// each candidate page is parsed once against the shape its renderer needs.
187 +const openAPIPageSchema = z.object({
188 + url: z.string(),
189 + data: z.object({
190 + title: z.string(),
191 + description: z.string().optional().catch(undefined),
192 + getOpenAPIPageProps: z.custom<OpenAPIPageData['getOpenAPIPageProps']>(
193 + value => typeof value === 'function'
194 + ),
195 + }),
196 +});
197 +
198 +const llmPageSchema: z.ZodType<LLMPage> = z.object({
199 + url: z.string(),
200 + data: z.object({
201 + title: z.string(),
202 + description: z.string().optional().catch(undefined),
203 + getText: z
204 + .custom<NonNullable<LLMPage['data']['getText']>>(value => typeof value === 'function')
205 + .optional()
206 + .catch(undefined),
207 + legacy: z.boolean().optional().catch(undefined),
208 + written: z.string().optional().catch(undefined),
209 + llmGuardrails: z.enum(['direct-execution', 'none']).optional().catch(undefined),
210 + }),
211 +});
212 +
213 +const degradedPageSchema = z.object({
214 + url: z.unknown().optional(),
215 + data: z
216 + .object({
217 + title: z.unknown().optional(),
218 + description: z.unknown().optional(),
219 + })
220 + .catch({}),
221 +});
222 +
223 +export function degradedPageToMarkdown(value: unknown): string | null {
224 + const parsed = degradedPageSchema.safeParse(value);
225 + if (!parsed.success) return null;
226 +
227 + const title = parsed.data.data.title || 'Documentation';
228 + const description = parsed.data.data.description || '';
229 + const url = parsed.data.url || '';
230 + return `# ${String(title)} (${String(url)})\n\n${String(description)}`;
231 +}
232 +
233 // Generate sample value for a schema
234 function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
235 if (depth > 3) return '...'; // Prevent infinite recursion
@@ -242,12 +284,7 @@ function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
284 * tracks recursion because `allOf` expands without increasing indentation. An
285 * ellipsis is emitted when either value exceeds `maxDepth`.
286 */
245 -function renderSchema(
246 - schema: OpenAPISchema,
247 - indent = 0,
248 - maxDepth = 4,
249 - depth = 0
250 -): string[] {
287 +function renderSchema(schema: OpenAPISchema, indent = 0, maxDepth = 4, depth = 0): string[] {
288 if (indent > maxDepth || depth > maxDepth) {
289 return [' '.repeat(indent) + '- ...'];
290 }
@@ -256,7 +293,11 @@ function renderSchema(
293 const prefix = ' '.repeat(indent);
294 const required = schema.required || [];
295
259 - if (schema.type === 'object' && (schema.properties || (schema.additionalProperties && typeof schema.additionalProperties === 'object'))) {
296 + if (
297 + schema.type === 'object' &&
298 + (schema.properties ||
299 + (schema.additionalProperties && typeof schema.additionalProperties === 'object'))
300 + ) {
301 if (schema.properties) {
302 for (const [name, prop] of Object.entries(schema.properties)) {
303 const isRequired = required.includes(name);
@@ -267,9 +308,19 @@ function renderSchema(
308 lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}`);
309
310 // Recurse for nested objects/arrays
270 - if (prop.type === 'object' && (prop.properties || (prop.additionalProperties && typeof prop.additionalProperties === 'object'))) {
311 + if (
312 + prop.type === 'object' &&
313 + (prop.properties ||
314 + (prop.additionalProperties && typeof prop.additionalProperties === 'object'))
315 + ) {
316 lines.push(...renderSchema(prop, indent + 1, maxDepth, depth + 1));
272 - } else if (prop.type === 'array' && prop.items?.type === 'object' && (prop.items.properties || (prop.items.additionalProperties && typeof prop.items.additionalProperties === 'object'))) {
317 + } else if (
318 + prop.type === 'array' &&
319 + prop.items?.type === 'object' &&
320 + (prop.items.properties ||
321 + (prop.items.additionalProperties &&
322 + typeof prop.items.additionalProperties === 'object'))
323 + ) {
324 lines.push(`${prefix} - Array items:`);
325 lines.push(...renderSchema(prop.items, indent + 2, maxDepth, depth + 1));
326 }
@@ -282,9 +333,17 @@ function renderSchema(
333 const typeStr = getTypeString(ap);
334 const desc = ap.description ? `: ${ap.description}` : '';
335 lines.push(`${prefix}- \`[key: string]\` (${typeStr})${desc}`);
285 - if (ap.type === 'object' && (ap.properties || (ap.additionalProperties && typeof ap.additionalProperties === 'object'))) {
336 + if (
337 + ap.type === 'object' &&
338 + (ap.properties || (ap.additionalProperties && typeof ap.additionalProperties === 'object'))
339 + ) {
340 lines.push(...renderSchema(ap, indent + 1, maxDepth, depth + 1));
287 - } else if (ap.type === 'array' && ap.items?.type === 'object' && (ap.items.properties || (ap.items.additionalProperties && typeof ap.items.additionalProperties === 'object'))) {
341 + } else if (
342 + ap.type === 'array' &&
343 + ap.items?.type === 'object' &&
344 + (ap.items.properties ||
345 + (ap.items.additionalProperties && typeof ap.items.additionalProperties === 'object'))
346 + ) {
347 lines.push(`${prefix} - Array items:`);
348 lines.push(...renderSchema(ap.items, indent + 2, maxDepth, depth + 1));
349 }
@@ -318,7 +377,10 @@ function getTypeString(schema: OpenAPISchema, depth = 0, maxDepth = 4): string {
377 if (depth > maxDepth) return '...';
378
379 if (schema.enum) {
321 - return `enum: ${schema.enum.slice(0, 3).map(e => `"${e}"`).join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;
380 + return `enum: ${schema.enum
381 + .slice(0, 3)
382 + .map(e => `"${e}"`)
383 + .join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;
384 }
385 if (schema.type === 'array' && schema.items) {
386 return `array<${getTypeString(schema.items, depth + 1, maxDepth)}>`;
@@ -370,9 +432,10 @@ function generateCurl(
432 }
433
434 // Convert OpenAPI page to comprehensive markdown
373 -export async function openapiPageToMarkdown(
374 - page: { url: string; data: OpenAPIPageData }
375 -): Promise<string> {
435 +export async function openapiPageToMarkdown(page: {
436 + url: string;
437 + data: OpenAPIPageData;
438 +}): Promise<string> {
439 const { title, description } = page.data;
440 const props = page.data.getOpenAPIPageProps();
441
@@ -380,7 +443,8 @@ export async function openapiPageToMarkdown(
443 const spec = dereferenceDocument(props.payload.bundled);
444 const paths = spec.paths as Record<string, Record<string, OpenAPIOperation>> | undefined;
445 const webhooks = spec.webhooks as Record<string, Record<string, OpenAPIOperation>> | undefined;
383 - const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as Record<string, OpenAPISecurityScheme> | undefined;
446 + const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as
447 + Record<string, OpenAPISecurityScheme> | undefined;
448 const servers = spec.servers as Array<{ url: string; description?: string }> | undefined;
449 const baseUrl = servers?.[0]?.url || 'https://backend.composio.dev';
450
@@ -564,7 +628,11 @@ export async function openapiPageToMarkdown(
628
629 // Map URL prefixes to their sources
630 // Note: 'reference' is handled specially below with async getReferenceSource()
567 -const sources = [
631 +interface PageSource {
632 + getPage(slugs: string[] | undefined): unknown;
633 +}
634 +
635 +const sources: Array<{ prefix: string; source: PageSource }> = [
636 { prefix: 'docs', source },
637 { prefix: 'examples', source: examplesSource },
638 { prefix: 'toolkits', source: toolkitsSource },
@@ -615,9 +683,7 @@ function generateChangelogIndex(): string {
683 * Multiple entries on the same date are combined into one document.
684 */
685 async function changelogToMarkdown(dateStr: string): Promise<string | null> {
618 - const matchingEntries = changelogEntries.filter(
619 - (entry) => entry.date === dateStr
620 - );
686 + const matchingEntries = changelogEntries.filter(entry => entry.date === dateStr);
687
688 if (matchingEntries.length === 0) {
689 return null;
@@ -701,7 +767,12 @@ async function readToolkitFaqMarkdown(slug: string): Promise<string | null> {
767 }
768
769 // Generate markdown from toolkit with detailed tools and triggers
704 -function toolkitToMarkdown(toolkit: Toolkit, detailedTools?: Tool[], detailedTriggers?: Trigger[], faqMarkdown?: string | null): string {
770 +function toolkitToMarkdown(
771 + toolkit: Toolkit,
772 + detailedTools?: Tool[],
773 + detailedTriggers?: Trigger[],
774 + faqMarkdown?: string | null
775 +): string {
776 const tools = detailedTools || toolkit.tools;
777 const triggers = detailedTriggers || toolkit.triggers;
778
@@ -713,10 +784,10 @@ function toolkitToMarkdown(toolkit: Toolkit, detailedTools?: Tool[], detailedTri
784 `- **Category:** ${toolkit.category || 'Uncategorized'}`,
785 `- **Auth:** ${toolkit.authSchemes.join(', ') || 'None'}`,
786 `- **Composio Managed App Available?** ${
716 - toolkit.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'))
717 - ? (toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
718 - ? 'Yes'
719 - : 'No')
787 + toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
788 + ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
789 + ? 'Yes'
790 + : 'No'
791 : 'N/A'
792 }`,
793 `- **Tools:** ${toolkit.toolCount}`,
@@ -794,16 +865,16 @@ async function generateManagedAuthIndex(): Promise<string> {
865 const toolkits = await getAllToolkits();
866
867 // Only include OAuth toolkits
797 - const oauthToolkits = toolkits.filter((t) =>
798 - t.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'))
868 + const oauthToolkits = toolkits.filter(t =>
869 + t.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
870 );
871
872 const managed = oauthToolkits
802 - .filter((t) => t.composioManagedAuthSchemes && t.composioManagedAuthSchemes.length > 0)
873 + .filter(t => t.composioManagedAuthSchemes && t.composioManagedAuthSchemes.length > 0)
874 .sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
875
876 const unmanaged = oauthToolkits
806 - .filter((t) => !t.composioManagedAuthSchemes || t.composioManagedAuthSchemes.length === 0)
877 + .filter(t => !t.composioManagedAuthSchemes || t.composioManagedAuthSchemes.length === 0)
878 .sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
879
880 const lines: string[] = [
@@ -827,7 +898,9 @@ async function generateManagedAuthIndex(): Promise<string> {
898 ];
899
900 for (const t of managed) {
830 - lines.push(`| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`);
901 + lines.push(
902 + `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
903 + );
904 }
905
906 lines.push('');
@@ -837,7 +910,9 @@ async function generateManagedAuthIndex(): Promise<string> {
910 lines.push('|---------|------|');
911
912 for (const t of unmanaged) {
840 - lines.push(`| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`);
913 + lines.push(
914 + `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
915 + );
916 }
917
918 return lines.join('\n');
@@ -869,9 +944,11 @@ async function generateToolkitsIndex(): Promise<string> {
944 for (const toolkit of sorted) {
945 const name = toolkit.name?.trim() || toolkit.slug;
946 const auth = toolkit.authSchemes?.join(', ') || 'None';
872 - const hasOAuth = toolkit.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'));
947 + const hasOAuth = toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'));
948 const managedApp = hasOAuth
874 - ? (toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0 ? 'Yes' : 'No')
949 + ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
950 + ? 'Yes'
951 + : 'No'
952 : '—';
953 lines.push(
954 `| [${name}](/toolkits/${toolkit.slug}.md) | \`${toolkit.slug.toUpperCase()}\` | ${toolkit.toolCount} | ${toolkit.triggerCount} | ${auth} | ${managedApp} |`
@@ -879,32 +956,45 @@ async function generateToolkitsIndex(): Promise<string> {
956 }
957
958 lines.push('', '## Toolkit Details', '');
882 - lines.push('For detailed information about each toolkit including all tools and triggers, visit the individual toolkit pages listed above.');
959 + lines.push(
960 + 'For detailed information about each toolkit including all tools and triggers, visit the individual toolkit pages listed above.'
961 + );
962
963 return lines.join('\n');
964 }
965
887 -const LLM_FOOTER = '\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference)';
966 +const LLM_FOOTER =
967 + '\n\n---\n\n📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference)';
968
969 // Render meta tool parameters as markdown
890 -function renderMetaToolParams(properties: Record<string, MetaToolParameter>, requiredFields: string[] = [], indent = 0): string[] {
970 +function renderMetaToolParams(
971 + properties: Record<string, MetaToolParameter>,
972 + requiredFields: string[] = [],
973 + indent = 0
974 +): string[] {
975 const lines: string[] = [];
976 const prefix = ' '.repeat(indent);
977
978 for (const [name, param] of Object.entries(properties)) {
895 - const typeStr = param.type === 'array' && param.items && typeof param.items === 'object' && (param.items as Record<string, unknown>).type
896 - ? `array<${(param.items as Record<string, unknown>).type}>`
897 - : param.type;
979 + const typeStr =
980 + param.type === 'array' &&
981 + param.items &&
982 + typeof param.items === 'object' &&
983 + (param.items as Record<string, unknown>).type
984 + ? `array<${(param.items as Record<string, unknown>).type}>`
985 + : param.type;
986 const reqMark = requiredFields.includes(name) ? ' *(required)*' : '';
987 const desc = param.description
988 ? `: ${param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}`
989 : '';
902 - const defaultStr = param.default !== undefined && param.default !== null && param.default !== ''
903 - ? ` (default: \`${String(param.default)}\`)`
904 - : '';
905 - const enumStr = param.enum && param.enum.length > 0
906 - ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
907 - : '';
990 + const defaultStr =
991 + param.default !== undefined && param.default !== null && param.default !== ''
992 + ? ` (default: \`${String(param.default)}\`)`
993 + : '';
994 + const enumStr =
995 + param.enum && param.enum.length > 0
996 + ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
997 + : '';
998
999 lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}${defaultStr}${enumStr}`);
1000
@@ -913,11 +1003,24 @@ function renderMetaToolParams(properties: Record<string, MetaToolParameter>, req
1003 lines.push(...renderMetaToolParams(param.properties, nestedRequired, indent + 1));
1004 }
1005
916 - const items = param.items && typeof param.items === 'object' ? param.items as Record<string, unknown> : null;
917 - if (items?.properties && typeof items.properties === 'object' && Object.keys(items.properties as object).length > 0) {
918 - const itemsRequired = Array.isArray(items.required) ? items.required as string[] : [];
1006 + const items =
1007 + param.items && typeof param.items === 'object'
1008 + ? (param.items as Record<string, unknown>)
1009 + : null;
1010 + if (
1011 + items?.properties &&
1012 + typeof items.properties === 'object' &&
1013 + Object.keys(items.properties as object).length > 0
1014 + ) {
1015 + const itemsRequired = Array.isArray(items.required) ? (items.required as string[]) : [];
1016 lines.push(`${prefix} - Array items:`);
920 - lines.push(...renderMetaToolParams(items.properties as Record<string, MetaToolParameter>, itemsRequired, indent + 2));
1017 + lines.push(
1018 + ...renderMetaToolParams(
1019 + items.properties as Record<string, MetaToolParameter>,
1020 + itemsRequired,
1021 + indent + 2
1022 + )
1023 + );
1024 }
1025 }
1026
@@ -926,11 +1029,7 @@ function renderMetaToolParams(properties: Record<string, MetaToolParameter>, req
1029
1030 // Generate markdown for a single meta tool
1031 function metaToolToMarkdown(tool: MetaTool): string {
929 - const lines: string[] = [
930 - `# ${tool.displayName}`,
931 - '',
932 - `**Slug:** \`${tool.slug}\``,
933 - ];
1032 + const lines: string[] = [`# ${tool.displayName}`, '', `**Slug:** \`${tool.slug}\``];
1033
1034 if (tool.tags.length > 0) {
1035 lines.push(`**Tags:** ${tool.tags.join(', ')}`);
@@ -968,16 +1067,15 @@ function metaToolsIndexToMarkdown(tools: MetaTool[]): string {
1067
1068 for (const tool of tools) {
1069 const tags = tool.tags.length > 0 ? tool.tags.join(', ') : '—';
971 - lines.push(`| [\`${tool.slug}\`](/toolkits/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`);
1070 + lines.push(
1071 + `| [\`${tool.slug}\`](/toolkits/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`
1072 + );
1073 }
1074
1075 return lines.join('\n') + LLM_FOOTER;
1076 }
1077
977 -export async function GET(
978 - _req: Request,
979 - { params }: { params: Promise<{ slug?: string[] }> }
980 -) {
1078 +export async function GET(_req: Request, { params }: { params: Promise<{ slug?: string[] }> }) {
1079 try {
1080 const { slug = [] } = await params;
1081 const [prefix, ...rest] = slug;
@@ -1058,7 +1156,7 @@ export async function GET(
1156 }
1157
1158 // Handle 'reference' specially - uses async getReferenceSource() for OpenAPI pages
1061 - let pageSource: any;
1159 + let pageSource: PageSource;
1160 if (prefix === 'reference') {
1161 try {
1162 pageSource = await getReferenceSource();
@@ -1069,7 +1167,7 @@ export async function GET(
1167 pageSource = referenceSource;
1168 }
1169 } else {
1072 - const match = sources.find((s) => s.prefix === prefix);
1170 + const match = sources.find(s => s.prefix === prefix);
1171 if (!match) notFound();
1172 pageSource = match.source;
1173 }
@@ -1085,11 +1183,10 @@ export async function GET(
1183
1184 if (page) {
1185 // Check if this is an OpenAPI page
1088 - if ('getOpenAPIPageProps' in page.data) {
1186 + const openapiPage = openAPIPageSchema.safeParse(page);
1187 + if (openapiPage.success) {
1188 try {
1090 - const markdown = await openapiPageToMarkdown(
1091 - page as unknown as { url: string; data: OpenAPIPageData }
1092 - );
1189 + const markdown = await openapiPageToMarkdown(openapiPage.data);
1190 return new Response(markdown, {
1191 headers: {
1192 'Content-Type': 'text/markdown; charset=utf-8',
@@ -1097,38 +1194,44 @@ export async function GET(
1194 });
1195 } catch (e) {
1196 console.error('Error generating OpenAPI markdown:', e);
1100 - const title = page.data?.title || 'API Reference';
1101 - const description = page.data?.description || '';
1102 - return new Response(
1103 - `# ${title}\n\n${description}`,
1104 - {
1105 - headers: {
1106 - 'Content-Type': 'text/markdown; charset=utf-8',
1107 - },
1108 - }
1109 - );
1197 + const title = openapiPage.data.data.title || 'API Reference';
1198 + const description = openapiPage.data.data.description || '';
1199 + return new Response(`# ${title}\n\n${description}`, {
1200 + headers: {
1201 + 'Content-Type': 'text/markdown; charset=utf-8',
1202 + },
1203 + });
1204 }
1205 }
1206
1207 // Regular MDX page
1114 - try {
1115 - return new Response(await getLLMText(page as any), {
1208 + const llmPage = llmPageSchema.safeParse(page);
1209 + if (llmPage.success) {
1210 + try {
1211 + return new Response(await getLLMText(llmPage.data), {
1212 + headers: {
1213 + 'Content-Type': 'text/markdown; charset=utf-8',
1214 + },
1215 + });
1216 + } catch (e) {
1217 + console.error('Error generating LLM text:', e);
1218 + const title = llmPage.data.data.title || 'Documentation';
1219 + const description = llmPage.data.data.description || '';
1220 + return new Response(`# ${title} (${llmPage.data.url})\n\n${description}`, {
1221 + headers: {
1222 + 'Content-Type': 'text/markdown; charset=utf-8',
1223 + },
1224 + });
1225 + }
1226 + }
1227 +
1228 + const degradedMarkdown = degradedPageToMarkdown(page);
1229 + if (degradedMarkdown !== null) {
1230 + return new Response(degradedMarkdown, {
1231 headers: {
1232 'Content-Type': 'text/markdown; charset=utf-8',
1233 },
1234 });
1120 - } catch (e) {
1121 - console.error('Error generating LLM text:', e);
1122 - const title = page.data?.title || 'Documentation';
1123 - const description = page.data?.description || '';
1124 - return new Response(
1125 - `# ${title} (${page.url || ''})\n\n${description}`,
1126 - {
1127 - headers: {
1128 - 'Content-Type': 'text/markdown; charset=utf-8',
1129 - },
1130 - }
1131 - );
1235 }
1236 }
1237
@@ -1166,14 +1269,11 @@ export async function GET(
1269 throw e;
1270 }
1271 console.error('Unexpected error in llms.mdx route:', e);
1169 - return new Response(
1170 - `# Error\n\nAn error occurred while generating the markdown content.`,
1171 - {
1172 - status: 500,
1173 - headers: {
1174 - 'Content-Type': 'text/markdown; charset=utf-8',
1175 - },
1176 - }
1177 - );
1272 + return new Response(`# Error\n\nAn error occurred while generating the markdown content.`, {
1273 + status: 500,
1274 + headers: {
1275 + 'Content-Type': 'text/markdown; charset=utf-8',
1276 + },
1277 + });
1278 }
1279 }
docs/app/llms.txt/route.ts
+5 -2
@@ -89,10 +89,13 @@ function walkPageTree(nodes: TreeNode[], depth = 2): string {
89 }
90 }
91
92 - return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
92 + return lines
93 + .join('\n')
94 + .replace(/\n{3,}/g, '\n\n')
95 + .trim();
96 }
97
95 -function formatPage(page: any) {
98 +function formatPage(page: { url: string }) {
99 return `- https://docs.composio.dev${page.url}.md`;
100 }
101
docs/components/file-buildup.tsx
+2 -1
@@ -1,6 +1,7 @@
1 import { createPatch } from 'diff';
2 import { getSingularPatch } from '@pierre/diffs';
3 import { preloadFileDiff } from '@pierre/diffs/ssr';
4 +import type { FileDiffProps } from '@pierre/diffs/react';
5 import { DiffView, HIDE_DIFF_STATS_CSS } from './diff-view';
6 import { FILE_BUILDS } from '@/lib/file-builds';
7
@@ -27,7 +28,7 @@ function StepCard({
28 file: string;
29 description?: string;
30
30 - fileDiff: any;
31 + fileDiff: FileDiffProps<undefined>['fileDiff'];
32 prerenderedHTML: string;
33 code: string;
34 }) {
docs/components/landing-hero/logo-bar.tsx
+25 -20
@@ -1,17 +1,23 @@
1 -"use client";
1 +'use client';
2
3 -import Image from "next/image";
4 -import { useIsMobile } from "./use-is-mobile";
5 -import { LogoLoop } from "./logo-loop";
3 +import Image from 'next/image';
4 +import { useIsMobile } from './use-is-mobile';
5 +import { LogoLoop } from './logo-loop';
6
7 -const LOGOS = [
8 - { src: "/clients/logo-agentai.svg", alt: "agent.ai", h: 34 },
9 - { src: "/clients/logo-context.svg", alt: "Context", h: 30 },
10 - { src: "/clients/logo-zoom.png", alt: "Zoom", h: 25 },
11 - { src: "/clients/logo-letta.svg", alt: "Letta", h: 27 },
12 - { src: "/clients/logo-glean.svg", alt: "Glean", h: 34 },
13 - { src: "/clients/logo-hubspot.svg", alt: "HubSpot", h: 34 },
14 - { src: "/clients/logo-wabi.svg", alt: "Wabi", h: 27 },
7 +interface ClientLogo {
8 + src: string;
9 + alt: string;
10 + h: number;
11 +}
12 +
13 +const LOGOS: ClientLogo[] = [
14 + { src: '/clients/logo-agentai.svg', alt: 'agent.ai', h: 34 },
15 + { src: '/clients/logo-context.svg', alt: 'Context', h: 30 },
16 + { src: '/clients/logo-zoom.png', alt: 'Zoom', h: 25 },
17 + { src: '/clients/logo-letta.svg', alt: 'Letta', h: 27 },
18 + { src: '/clients/logo-glean.svg', alt: 'Glean', h: 34 },
19 + { src: '/clients/logo-hubspot.svg', alt: 'HubSpot', h: 34 },
20 + { src: '/clients/logo-wabi.svg', alt: 'Wabi', h: 27 },
21 ];
22
23 const MOBILE_SCALE = 0.75;
@@ -25,9 +31,9 @@ export function LogoBar() {
31 className="w-full max-w-[800px] overflow-hidden px-4 py-[14px] grayscale"
32 style={{
33 maskImage:
28 - "linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)",
34 + 'linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)',
35 WebkitMaskImage:
30 - "linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)",
36 + 'linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)',
37 }}
38 >
39 <LogoLoop
@@ -35,18 +41,17 @@ export function LogoBar() {
41 gap={isMobile ? 40 : 64}
42 logoHeight={isMobile ? 18 : 26}
43 logos={LOGOS}
38 - renderItem={(item: any) => {
39 - const logo = item as { src: string; alt: string; h: number };
40 - const h = isMobile ? logo.h * MOBILE_SCALE : logo.h;
44 + renderItem={item => {
45 + const h = isMobile ? item.h * MOBILE_SCALE : item.h;
46 return (
47 <Image
43 - alt={logo.alt}
48 + alt={item.alt}
49 draggable={false}
50 height={Math.ceil(h)}
46 - src={logo.src}
51 + src={item.src}
52 style={{
53 height: h,
49 - width: "auto",
54 + width: 'auto',
55 }}
56 width={Math.ceil(h * 3)}
57 />
docs/components/landing-hero/logo-loop/index.d.ts
+6 -4
@@ -20,8 +20,8 @@ interface LogoNodeItem {
20
21 type LogoItem = LogoImageItem | LogoNodeItem;
22
23 -interface LogoLoopProps {
24 - logos: LogoItem[];
23 +interface LogoLoopProps<Item extends LogoItem = LogoItem> {
24 + logos: Item[];
25 speed?: number;
26 direction?: "left" | "right" | "up" | "down";
27 width?: string | number;
@@ -32,11 +32,13 @@ interface LogoLoopProps {
32 fadeOut?: boolean;
33 fadeOutColor?: string;
34 scaleOnHover?: boolean;
35 - renderItem?: (item: LogoItem, key: string) => ReactNode;
35 + renderItem?: (item: Item, key: string) => ReactNode;
36 ariaLabel?: string;
37 className?: string;
38 style?: CSSProperties;
39 }
40
41 -export const LogoLoop: React.MemoExoticComponent<React.FC<LogoLoopProps>>;
41 +export const LogoLoop: <Item extends LogoItem = LogoItem>(
42 + props: LogoLoopProps<Item>
43 +) => ReactNode;
44 export default LogoLoop;
docs/lib/create-docs-layout.tsx
+1 -1
@@ -1,7 +1,7 @@
1 import { DocsLayout } from 'fumadocs-ui/layouts/docs';
2 import type { ReactNode } from 'react';
3
4 -type Source = any;
4 +type Source = typeof import('./source').examplesSource;
5
6 export function createDocsLayout(source: Source) {
7 return function Layout({ children }: { children: ReactNode }) {
docs/lib/create-docs-page.tsx
+8 -7
@@ -1,8 +1,4 @@
1 -import {
2 - DocsBody,
3 - DocsPage,
4 - DocsTitle,
5 -} from 'fumadocs-ui/layouts/docs/page';
1 +import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
2 import { notFound } from 'next/navigation';
3 import { getMDXComponents } from '@/mdx-components';
4 import type { Metadata } from 'next';
@@ -11,7 +7,7 @@ import { PageActions } from '@/components/page-actions';
7 import { EditOnGitHub } from '@/components/edit-on-github';
8 import { getOgImageUrl } from '@/lib/source';
9
14 -type Source = any;
10 +type Source = typeof import('./source').examplesSource;
11
12 export function createDocsPage(source: Source, contentDir: string = 'content/docs') {
13 return async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
@@ -22,7 +18,12 @@ export function createDocsPage(source: Source, contentDir: string = 'content/doc
18 const MDX = page.data.body;
19
20 return (
25 - <DocsPage toc={page.data.toc} full={page.data.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
21 + <DocsPage
22 + toc={page.data.toc}
23 + full={page.data.full}
24 + footer={{ enabled: false }}
25 + tableOfContentPopover={{ enabled: false }}
26 + >
27 <DocsTitle>{page.data.title}</DocsTitle>
28 <PageActions path={page.url} />
29 <DocsBody>
docs/lib/deprecated-api-sidebar.tsx
+31 -34
@@ -1,27 +1,21 @@
1 import type { ReactNode } from 'react';
2 import type { Item } from 'fumadocs-core/page-tree';
3 -import type { PageTreeTransformer } from 'fumadocs-core/source';
3 +import type { ContentStorage } from 'fumadocs-core/source';
4 +import { z } from 'zod';
5 import { DeprecatedApiSidebarLegacyBadge } from '@/components/legacy-badge';
6 import { getApiDisplayTitle, isApiPageDeprecated } from '@/lib/api-deprecation';
7 import type { ApiPageOperation, OpenApiSchemaPageData } from '@/lib/api-deprecation';
8
8 -interface OpenApiSidebarPageData extends OpenApiSchemaPageData {
9 - title: string;
10 - getOpenAPIPageProps: () => {
11 - operations?: ApiPageOperation[];
12 - };
13 -}
14 -
15 -function isOpenApiSidebarPageData(data: unknown): data is OpenApiSidebarPageData {
16 - if (!data || typeof data !== 'object') return false;
17 -
18 - const candidate = data as Partial<OpenApiSidebarPageData>;
19 - return (
20 - typeof candidate.title === 'string' &&
21 - typeof candidate.getSchema === 'function' &&
22 - typeof candidate.getOpenAPIPageProps === 'function'
23 - );
24 -}
9 +// Page data attached by fumadocs-openapi to generated operation pages. MDX
10 +// pages in the same tree lack these members, so the data is parsed once here
11 +// and non-OpenAPI pages simply fail the parse.
12 +const openApiSidebarPageDataSchema = z.object({
13 + title: z.string(),
14 + getSchema: z.custom<OpenApiSchemaPageData['getSchema']>(value => typeof value === 'function'),
15 + getOpenAPIPageProps: z.custom<() => { operations?: ApiPageOperation[] }>(
16 + value => typeof value === 'function'
17 + ),
18 +});
19
20 export function getDeprecatedApiSidebarName(
21 title: string,
@@ -41,19 +35,22 @@ export function getDeprecatedApiSidebarName(
35 * Replaces a deprecated OpenAPI operation's textual title suffix with a
36 * compact lifecycle badge before fumadocs-openapi appends its method label.
37 */
44 -export const deprecatedApiSidebarTransformer: PageTreeTransformer = {
45 - file(node: Item, filePath?: string): Item {
46 - if (!filePath) return node;
47 -
48 - const file = this.storage.read(filePath);
49 - if (!file || file.format !== 'page' || !isOpenApiSidebarPageData(file.data)) {
50 - return node;
51 - }
52 -
53 - const apiProps = file.data.getOpenAPIPageProps();
54 - return {
55 - ...node,
56 - name: getDeprecatedApiSidebarName(file.data.title, file.data, apiProps.operations),
57 - };
58 - },
59 -};
38 +export function transformDeprecatedApiSidebarNode(
39 + node: Item,
40 + filePath: string | undefined,
41 + storage: ContentStorage
42 +): Item {
43 + if (!filePath) return node;
44 +
45 + const file = storage.read(filePath);
46 + if (!file || file.format !== 'page') return node;
47 +
48 + const pageData = openApiSidebarPageDataSchema.safeParse(file.data);
49 + if (!pageData.success) return node;
50 +
51 + const apiProps = pageData.data.getOpenAPIPageProps();
52 + return {
53 + ...node,
54 + name: getDeprecatedApiSidebarName(pageData.data.title, pageData.data, apiProps.operations),
55 + };
56 +}
docs/lib/filter-api-version.ts
+7 -10
@@ -13,12 +13,11 @@ interface PageTreeNode {
13 url?: string;
14 children?: PageTreeNode[];
15 index?: PageTreeNode;
16 - [key: string]: unknown;
16 }
17
18 interface PageTreeRoot {
19 + name: unknown;
20 children: PageTreeNode[];
21 - [key: string]: unknown;
21 }
22
23 /**
@@ -70,11 +69,11 @@ function isHiddenTagNode(node: PageTreeNode): boolean {
69 /** Recursively drops folders/pages whose tag slug is in HIDDEN_API_TAGS. */
70 function filterHiddenTags(nodes: PageTreeNode[]): PageTreeNode[] {
71 return nodes
73 - .filter((node) => !isHiddenTagNode(node))
74 - .map((node) =>
72 + .filter(node => !isHiddenTagNode(node))
73 + .map(node =>
74 node.type === 'folder' && node.children
75 ? { ...node, children: filterHiddenTags(node.children) }
77 - : node,
76 + : node
77 );
78 }
79
@@ -115,19 +114,17 @@ export function prepareTree<T extends PageTreeRoot>(tree: T, version: string): T
114 // Just hide the V3 folder
115 return {
116 ...tree,
118 - children: children.filter((node) => !isV3Node(node)),
117 + children: children.filter(node => !isV3Node(node)),
118 };
119 }
120
121 // v3.0: lift V3 folder contents, keep version-independent folders (SDK Reference, Meta Tools)
123 - const v3Folder = children.find(
124 - (node) => node.type === 'folder' && isV3Node(node),
125 - );
122 + const v3Folder = children.find(node => node.type === 'folder' && isV3Node(node));
123
124 // Nodes that should appear in both versions (exclude v3 nodes, v3.1 API Reference folder,
125 // and top-level pages which are version-specific — both versions have their own copies)
126 const sharedNodes = children.filter(
130 - (node) => node.type !== 'page' && !isV3Node(node) && !isV31ApiFolder(node),
127 + node => node.type !== 'page' && !isV3Node(node) && !isV31ApiFolder(node)
128 );
129
130 if (v3Folder?.children) {
docs/lib/reference-page-data.ts new
+33
@@ -0,0 +1,33 @@
1 +import type { ReactNode } from 'react';
2 +import type { TOCItemType } from 'fumadocs-core/toc';
3 +import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
4 +import { z } from 'zod';
5 +import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
6 +import type { ReferenceMdxPageData } from '@/lib/source';
7 +
8 +// The combined reference source mixes MDX and fumadocs-openapi pages, so page
9 +// data is parsed once against the shape each renderer needs instead of being
10 +// narrowed with `in` guards and casts. Function-valued members use z.custom
11 +// with a typeof check because zod cannot otherwise validate functions.
12 +export const openApiReferencePageDataSchema = z.object({
13 + title: z.string(),
14 + getOpenAPIPageProps: z.custom<() => OpenAPIPageProps>(value => typeof value === 'function'),
15 + getSchema: z.custom<OpenApiSchemaPageData['getSchema']>(value => typeof value === 'function'),
16 +});
17 +
18 +// A TOC entry's `title` is a ReactNode, which admits nearly any runtime value
19 +// (string, number, element, fragment, null, ...), so it is not runtime-checkable;
20 +// the structural fields are validated. looseObject keeps extra members such as
21 +// remark-steps' `_step` intact.
22 +const tocItemSchema: z.ZodType<TOCItemType> = z.looseObject({
23 + title: z.custom<ReactNode>(() => true),
24 + url: z.string(),
25 + depth: z.number(),
26 +});
27 +
28 +export const referenceMdxPageDataSchema = z.object({
29 + title: z.string(),
30 + full: z.boolean().optional().catch(undefined),
31 + toc: z.array(tocItemSchema),
32 + body: z.custom<ReferenceMdxPageData['body']>(value => typeof value === 'function'),
33 +});
docs/lib/source.ts
+120 -78
@@ -7,7 +7,7 @@ import { getGuardrails } from './llm-guardrails';
7 import { HIDDEN_API_TAGS } from './filter-api-version';
8 import { FILE_BUILDS } from './file-builds';
9 import { replaceRepoBrowserMarkdown } from './repo-browser-markdown';
10 -import { deprecatedApiSidebarTransformer } from './deprecated-api-sidebar';
10 +import { transformDeprecatedApiSidebarNode } from './deprecated-api-sidebar';
11
12 /**
13 * True if a reference URL belongs to an intentionally-hidden API tag
@@ -30,35 +30,28 @@ function isHiddenReferenceUrl(url: string): boolean {
30 return false;
31 }
32
33 -/**
34 - * Transformer to set defaultOpen: true for specific folders in the reference sidebar.
35 - */
36 -const defaultOpenTransformer = {
37 - folder(node: { name: string; defaultOpen?: boolean }, folderPath: string) {
38 - if (folderPath === 'api-reference' || folderPath === 'sdk-reference' || folderPath === 'v3/api-reference') {
39 - return { ...node, defaultOpen: true };
40 - }
41 - return node;
42 - },
43 -};
44 -
33 export const source = loader({
34 baseUrl: '/docs',
35 source: docs.toFumadocsSource(),
36 plugins: [lucideIconsPlugin()],
37 });
38
39 +function loadOpenapiPages() {
40 + return Promise.all([
41 + openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
42 + openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
43 + ]);
44 +}
45 +
46 +type OpenapiPages = Awaited<ReturnType<typeof loadOpenapiPages>>;
47 +
48 // One combined reference source with both v3.1 and v3.0 OpenAPI pages.
49 // v3.1 at api-reference/, v3.0 at api-reference/v3/
53 -let _referenceSource: any = null;
54 -let _openapiPagesPromise: Promise<any> | null = null;
50 +let _openapiPagesPromise: ReturnType<typeof loadOpenapiPages> | null = null;
51
52 async function getOpenapiPages() {
53 if (!_openapiPagesPromise) {
58 - _openapiPagesPromise = Promise.all([
59 - openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
60 - openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
61 - ]).catch((e) => {
54 + _openapiPagesPromise = loadOpenapiPages().catch(e => {
55 // Don't permanently cache a failed load (e.g. a transient OpenAPI spec
56 // resolution error in a serverless instance). Clearing the memo lets the
57 // next request retry instead of re-throwing the same cached rejection.
@@ -69,36 +62,56 @@ async function getOpenapiPages() {
62 return _openapiPagesPromise;
63 }
64
65 +function createReferenceSource(openapiLatest: OpenapiPages[0], openapiV3Pages: OpenapiPages[1]) {
66 + const loaded = loader({
67 + baseUrl: '/reference',
68 + source: multiple({
69 + mdx: reference.toFumadocsSource(),
70 + openapi: openapiLatest,
71 + 'openapi-v3': openapiV3Pages,
72 + }),
73 + plugins: [lucideIconsPlugin(), openapiPlugin()],
74 + pageTree: {
75 + transformers: [
76 + {
77 + folder(node, folderPath) {
78 + if (
79 + folderPath === 'api-reference' ||
80 + folderPath === 'sdk-reference' ||
81 + folderPath === 'v3/api-reference'
82 + ) {
83 + return { ...node, defaultOpen: true };
84 + }
85 + return node;
86 + },
87 + },
88 + {
89 + file(node, filePath) {
90 + return transformDeprecatedApiSidebarNode(node, filePath, this.storage);
91 + },
92 + },
93 + ],
94 + },
95 + });
96 +
97 + // Exclude intentionally-hidden API tags (consumer, invite-codes) from the
98 + // flat page list so validate-links, llms.mdx, llms.txt, and sitemap skip
99 + // their fumadocs-openapi operation pages. The sidebar tree is filtered
100 + // separately via prepareTree (lib/filter-api-version.ts).
101 + const originalGetPages = loaded.getPages.bind(loaded);
102 + loaded.getPages = (...args: Parameters<typeof originalGetPages>) =>
103 + originalGetPages(...args).filter((page: { url: string }) => !isHiddenReferenceUrl(page.url));
104 +
105 + return loaded;
106 +}
107 +
108 +type ReferenceSource = ReturnType<typeof createReferenceSource>;
109 +let _referenceSource: ReferenceSource | null = null;
110 +
111 export async function getReferenceSource() {
112 if (!_referenceSource) {
113 const [openapiLatest, openapiV3Pages] = await getOpenapiPages();
75 - const loaded = loader({
76 - baseUrl: '/reference',
77 - source: multiple({
78 - mdx: reference.toFumadocsSource(),
79 - openapi: openapiLatest,
80 - 'openapi-v3': openapiV3Pages,
81 - }),
82 - plugins: [lucideIconsPlugin(), openapiPlugin()],
83 - pageTree: {
84 - transformers: [
85 - defaultOpenTransformer as any,
86 - deprecatedApiSidebarTransformer as any,
87 - ],
88 - },
89 - });
90 -
91 - // Exclude intentionally-hidden API tags (consumer, invite-codes) from the
92 - // flat page list so validate-links, llms.mdx, llms.txt, and sitemap skip
93 - // their fumadocs-openapi operation pages. The sidebar tree is filtered
94 - // separately via prepareTree (lib/filter-api-version.ts).
95 - const originalGetPages = loaded.getPages.bind(loaded);
96 - (loaded as any).getPages = (...args: Parameters<typeof originalGetPages>) =>
97 - originalGetPages(...args).filter(
98 - (page: { url: string }) => !isHiddenReferenceUrl(page.url),
99 - );
100 -
101 - _referenceSource = loaded;
114 + _referenceSource = createReferenceSource(openapiLatest, openapiV3Pages);
115 }
116 return _referenceSource;
117 }
@@ -110,6 +123,8 @@ export const referenceSource = loader({
123 plugins: [lucideIconsPlugin()],
124 });
125
126 +export type ReferenceMdxPageData = InferPageType<typeof referenceSource>['data'];
127 +
128 export const examplesSource = loader({
129 baseUrl: '/examples',
130 source: examples.toFumadocsSource(),
@@ -124,7 +139,12 @@ export const toolkitsSource = loader({
139
140 export const changelogEntries = changelog;
141
127 -export function getOgImageUrl(_section: string, _slugs: string[], title?: string, _description?: string): string {
142 +export function getOgImageUrl(
143 + _section: string,
144 + _slugs: string[],
145 + title?: string,
146 + _description?: string
147 +): string {
148 const encodedTitle = encodeURIComponent(title ?? 'Composio Docs');
149 return `https://og.composio.dev/api/og?title=${encodedTitle}`;
150 }
@@ -180,11 +200,20 @@ export function mdxToCleanMarkdown(content: string): string {
200
201 result = result.replace(/<TabsList>[\s\S]*?<\/TabsList>/g, '');
202 result = result.replace(/<TabsTrigger[^>]*>[^<]*<\/TabsTrigger>/g, '');
183 - result = result.replace(/<TabsContent[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/TabsContent>/g, '\n**$1:**\n$2');
184 - result = result.replace(/<Tab[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Tab>/g, '\n**$1:**\n$2');
203 + result = result.replace(
204 + /<TabsContent[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/TabsContent>/g,
205 + '\n**$1:**\n$2'
206 + );
207 + result = result.replace(
208 + /<Tab[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Tab>/g,
209 + '\n**$1:**\n$2'
210 + );
211
212 result = result.replace(/<StepTitle>([\s\S]*?)<\/StepTitle>/g, (_, title) => {
187 - const cleanTitle = title.replace(/^[\s#]*#\s*/, '').replace(/\s+$/, '').trim();
213 + const cleanTitle = title
214 + .replace(/^[\s#]*#\s*/, '')
215 + .replace(/\s+$/, '')
216 + .trim();
217 return cleanTitle ? `#### ${cleanTitle}` : '';
218 });
219 result = result.replace(/<Step>\s*###\s*(.+)/g, '#### $1');
@@ -193,10 +222,7 @@ export function mdxToCleanMarkdown(content: string): string {
222 result = result.replace(/^(\s*#{1,6})\s*#\s+(.+)$/gm, '$1 $2');
223 result = result.replace(/^\s*#\s*$/gm, '');
224
196 - result = result.replace(
197 - /<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,
198 - '\n## $1\n'
199 - );
225 + result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
226 result = result.replace(/<\/FrameworkOption>/g, '');
227
228 const tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };
@@ -236,10 +262,7 @@ export function mdxToCleanMarkdown(content: string): string {
262 '![$2]($1)'
263 );
264
239 - result = result.replace(
240 - /<ToolTypeOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,
241 - '\n### $1\n'
242 - );
265 + result = result.replace(/<ToolTypeOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n### $1\n');
266 result = result.replace(/<\/ToolTypeOption>/g, '');
267
268 result = result.replace(
@@ -259,15 +282,15 @@ export function mdxToCleanMarkdown(content: string): string {
282 result = result.replace(
283 /<AIToolsBanner\s*\/>/g,
284 '### For AI tools\n\n' +
262 - '**Skills:**\n' +
263 - '```bash\nnpx skills add composiohq/skills\n```\n' +
264 - '[Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)\n\n' +
265 - '**CLI:**\n' +
266 - '```bash\ncurl -fsSL https://composio.dev/install | bash\n```\n' +
267 - '[CLI Reference](/docs/cli)\n\n' +
268 - '**Context:**\n' +
269 - '- [llms.txt](/llms.txt) — Documentation index with links\n' +
270 - '- [llms-full.txt](/llms-full.txt) — Complete documentation in one file'
285 + '**Skills:**\n' +
286 + '```bash\nnpx skills add composiohq/skills\n```\n' +
287 + '[Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)\n\n' +
288 + '**CLI:**\n' +
289 + '```bash\ncurl -fsSL https://composio.dev/install | bash\n```\n' +
290 + '[CLI Reference](/docs/cli)\n\n' +
291 + '**Context:**\n' +
292 + '- [llms.txt](/llms.txt) — Documentation index with links\n' +
293 + '- [llms-full.txt](/llms-full.txt) — Complete documentation in one file'
294 );
295
296 result = result.replace(
@@ -300,7 +323,10 @@ export function mdxToCleanMarkdown(content: string): string {
323
324 result = replaceRepoBrowserMarkdown(result);
325
303 - result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');
326 + result = result.replace(
327 + /<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g,
328 + ''
329 + );
330
331 result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');
332 result = result.replace(/<\/?[A-Z][a-zA-Z]*[^>]*>/g, '');
@@ -313,9 +339,10 @@ export function mdxToCleanMarkdown(content: string): string {
339 const flushCodeBlock = () => {
340 if (codeBlockLines.length > 0) {
341 const nonEmptyLines = codeBlockLines.filter(l => l.trim().length > 0);
316 - const minIndent = nonEmptyLines.length > 0
317 - ? Math.min(...nonEmptyLines.map(l => l.match(/^(\s*)/)?.[1]?.length || 0))
318 - : 0;
342 + const minIndent =
343 + nonEmptyLines.length > 0
344 + ? Math.min(...nonEmptyLines.map(l => l.match(/^(\s*)/)?.[1]?.length || 0))
345 + : 0;
346 for (const codeLine of codeBlockLines) {
347 normalizedLines.push(codeLine.slice(minIndent));
348 }
@@ -376,7 +403,22 @@ function stripTwoslashFromCodeBlocks(content: string): string {
403 });
404 }
405
379 -export async function getLLMText(page: InferPageType<typeof source>, options?: { includeFooter?: boolean; includeGuardrails?: boolean }) {
406 +export interface LLMPage {
407 + url: string;
408 + data: {
409 + title: string;
410 + description?: string;
411 + getText?: (mode: 'processed' | 'raw') => Promise<string>;
412 + legacy?: boolean;
413 + written?: string;
414 + llmGuardrails?: Parameters<typeof getGuardrails>[0];
415 + };
416 +}
417 +
418 +export async function getLLMText(
419 + page: LLMPage,
420 + options?: { includeFooter?: boolean; includeGuardrails?: boolean }
421 +) {
422 const includeFooter = options?.includeFooter ?? true;
423 const includeGuardrails = options?.includeGuardrails ?? true;
424 if (typeof page.data.getText !== 'function') {
@@ -420,7 +462,10 @@ ${page.data.description || ''}`;
462 const cleanSegments = segments.map(s => mdxToCleanMarkdown(s));
463 let cleanContent = cleanSegments[0];
464 for (let i = 0; i < mermaidCharts.length; i++) {
423 - const chart = mermaidCharts[i].replace(/&#x22;/g, '"').replace(/&#x27;/g, "'").replace(/&amp;/g, '&');
465 + const chart = mermaidCharts[i]
466 + .replace(/&#x22;/g, '"')
467 + .replace(/&#x27;/g, "'")
468 + .replace(/&amp;/g, '&');
469 cleanContent += `\n\n\`\`\`mermaid\n${chart}\n\`\`\`\n\n${cleanSegments[i + 1]}`;
470 }
471
@@ -440,8 +485,7 @@ ${page.data.description || ''}`;
485 ? `\n> _Written ${written}._\n`
486 : '';
487
443 - const guardrails =
444 - includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';
488 + const guardrails = includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';
489
490 return `# ${page.data.title} (${page.url})
491 ${topNote}
@@ -460,9 +504,7 @@ const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
504
505 function validateDateFormat(dateStr: string): void {
506 if (!DATE_REGEX.test(dateStr)) {
463 - throw new Error(
464 - `Invalid date format: "${dateStr}". Expected YYYY-MM-DD (e.g., "2025-12-29")`
465 - );
507 + throw new Error(`Invalid date format: "${dateStr}". Expected YYYY-MM-DD (e.g., "2025-12-29")`);
508 }
509 }
510
docs/lib/standup-bot-build.ts
+8 -1
@@ -223,6 +223,13 @@ const buttons2 = `import { verifySlackSignature, readRawBody, updateMessage, pos
223 import { generateDraft } from './_utils/agent';
224 import { draftMessage, connectMenu } from './_utils/blocks';
225
226 +type SlackInteractionPayload = {
227 + actions?: Array<{
228 + action_id?: string;
229 + value?: string;
230 + }>;
231 +};
232 +
233 // Slack POSTs here every time someone clicks a button. Verify it really came
234 // from Slack, then ack within 3 seconds (Slack retries if you're slow).
235 export default async function handler(req: Request, res: Response) {
@@ -236,7 +243,7 @@ export default async function handler(req: Request, res: Response) {
243
244 // Each button carried its context in \`value\`, so the handler knows exactly what
245 // to do. No model decides anything here: the flow is fixed.
239 -async function handleClick(payload: any) {
246 +async function handleClick(payload: SlackInteractionPayload) {
247 const action = payload.actions?.[0];
248 const ctx = JSON.parse(action?.value ?? '{}');
249
docs/lib/toolkit-schema.ts
+193 -36
@@ -1,57 +1,214 @@
1 -import type { ParameterSchema, Tool } from '@/types/toolkit';
1 +import { z } from 'zod';
2 +import type { ParameterSchema, Tool, Trigger } from '@/types/toolkit';
3 +
4 +// Zod schemas for the untyped tool/trigger payloads the Composio API returns.
5 +// Each boundary parses once (leniently — malformed fields degrade to the same
6 +// fallbacks the UI applied by hand before) and lets the inferred types flow.
7 +
8 +/** Keep only the array members that satisfy `schema`; junk entries are dropped. */
9 +function filteredArray<T>(schema: z.ZodType<T>) {
10 + return z
11 + .array(z.unknown())
12 + .catch([])
13 + .transform(items =>
14 + items.flatMap(item => {
15 + const parsed = schema.safeParse(item);
16 + return parsed.success ? [parsed.data] : [];
17 + })
18 + );
19 +}
20 +
21 +const lenientString = z.string().catch('');
22 +const optionalString = z.string().optional().catch(undefined);
23 +const stringArray = filteredArray(z.string());
24 +const scalarStringArray = filteredArray(
25 + z.union([z.string(), z.number(), z.boolean()]).transform(value => String(value))
26 +);
27 +
28 +// --- JSON-Schema parameter nodes -------------------------------------------
29 +
30 +// Recursive JSON-Schema property node. Nested properties, items, and
31 +// object-valued additionalProperties survive whole (the toolkit detail UI
32 +// reads items.additionalProperties and additionalProperties.properties to
33 +// synthesize the "[key: string]" row). Tuple-form `items` arrays are not
34 +// object nodes and parse to undefined instead of spreading into numeric keys.
35 +interface RawSchemaNode {
36 + type: string;
37 + description?: string;
38 + default?: unknown;
39 + example?: unknown;
40 + enum: string[];
41 + properties?: Record<string, unknown>;
42 + required?: string[];
43 + items?: RawSchemaNode;
44 + additionalProperties?: boolean | RawSchemaNode;
45 +}
46 +
47 +const rawSchemaNodeSchema: z.ZodType<RawSchemaNode> = z.object({
48 + type: lenientString,
49 + description: optionalString,
50 + default: z.unknown().optional(),
51 + example: z.unknown().optional(),
52 + enum: scalarStringArray,
53 + properties: z.record(z.string(), z.unknown()).optional().catch(undefined),
54 + required: filteredArray(z.string()).optional().catch(undefined),
55 + get items(): z.ZodType<RawSchemaNode | undefined> {
56 + return rawSchemaNodeSchema.optional().catch(undefined);
57 + },
58 + get additionalProperties(): z.ZodType<boolean | RawSchemaNode | undefined> {
59 + return z.union([z.boolean(), rawSchemaNodeSchema]).optional().catch(undefined);
60 + },
61 +});
62 +
63 +function toParameterSchema(node: RawSchemaNode): ParameterSchema {
64 + const param: ParameterSchema = {
65 + type: node.type,
66 + description: node.description,
67 + default: node.default,
68 + example: node.example,
69 + enum: node.enum.length > 0 ? node.enum : undefined,
70 + };
71 +
72 + if (node.properties) {
73 + param.properties = processParams(node.properties, node.required ?? []);
74 + }
75 + if (node.required) {
76 + param.requiredFields = node.required;
77 + }
78 + if (node.items) {
79 + param.items = toParameterSchema(node.items);
80 + }
81 + if (typeof node.additionalProperties === 'boolean') {
82 + param.additionalProperties = node.additionalProperties;
83 + } else if (node.additionalProperties) {
84 + param.additionalProperties = toParameterSchema(node.additionalProperties);
85 + }
86 +
87 + return param;
88 +}
89
90 // Add required flag to each property based on the required array
91 // Preserves nested properties/items for object and array types
5 -function processParams(props: any, requiredList: string[]): Record<string, ParameterSchema> | undefined {
6 - if (!props || typeof props !== 'object') return undefined;
92 +function processParams(
93 + props: Record<string, unknown>,
94 + requiredList: string[]
95 +): Record<string, ParameterSchema> | undefined {
96 const result: Record<string, ParameterSchema> = {};
97 for (const [key, value] of Object.entries(props)) {
9 - if (typeof value === 'object' && value !== null) {
10 - const param = value as any;
98 + const parsed = rawSchemaNodeSchema.safeParse(value);
99 + if (parsed.success) {
100 result[key] = {
12 - type: param.type,
13 - description: param.description,
14 - default: param.default,
15 - example: param.example,
16 - enum: param.enum,
101 + ...toParameterSchema(parsed.data),
102 required: requiredList.includes(key),
18 - ...(param.properties ? { properties: param.properties } : {}),
19 - ...(Array.isArray(param.required) ? { requiredFields: param.required } : {}),
20 - ...(param.items ? { items: {
21 - ...param.items,
22 - ...(Array.isArray(param.items.required) ? { requiredFields: param.items.required } : {}),
23 - } } : {}),
24 - ...(param.additionalProperties && typeof param.additionalProperties === 'object'
25 - ? { additionalProperties: param.additionalProperties }
26 - : {}),
103 };
104 }
105 }
106 return Object.keys(result).length > 0 ? result : undefined;
107 }
108
109 +const rawSchemaRootSchema = z.object({
110 + properties: z.record(z.string(), z.unknown()).optional().catch(undefined),
111 + required: stringArray,
112 +});
113 +
114 // Process a raw JSON Schema (with top-level properties + required) into ParameterSchema records
34 -export function processSchema(schema: any): Record<string, ParameterSchema> | undefined {
35 - if (!schema) return undefined;
36 - const props = schema.properties || schema;
37 - const required = schema.required || [];
38 - if (!props || typeof props !== 'object') return undefined;
39 - return processParams(props, required);
115 +export function processSchema(schema: unknown): Record<string, ParameterSchema> | undefined {
116 + const record = z.record(z.string(), z.unknown()).safeParse(schema);
117 + if (!record.success) return undefined;
118 + const root = rawSchemaRootSchema.parse(record.data);
119 + return processParams(root.properties ?? record.data, root.required);
120 +}
121 +
122 +// --- Tools ------------------------------------------------------------------
123 +
124 +const rawApiToolSchema = z.object({
125 + slug: lenientString,
126 + name: optionalString,
127 + display_name: optionalString,
128 + description: lenientString,
129 + input_parameters: z.unknown().optional(),
130 + parameters: z.unknown().optional(),
131 + output_parameters: z.unknown().optional(),
132 + response: z.unknown().optional(),
133 + scopes: stringArray,
134 + tags: stringArray,
135 + is_deprecated: z.boolean().catch(false),
136 +});
137 +
138 +type RawApiTool = z.infer<typeof rawApiToolSchema>;
139 +
140 +function toolFromRaw(raw: RawApiTool): Tool {
141 + return {
142 + slug: raw.slug,
143 + name: raw.name || raw.display_name || raw.slug,
144 + description: raw.description,
145 + input_parameters: processSchema(raw.input_parameters || raw.parameters),
146 + output_parameters: processSchema(raw.output_parameters || raw.response),
147 + scopes: raw.scopes.length > 0 ? raw.scopes : undefined,
148 + tags: raw.tags.length > 0 ? raw.tags : undefined,
149 + is_deprecated: raw.is_deprecated,
150 + };
151 }
152
153 // Convert a raw API tool object into our Tool type
43 -export function toolFromApi(tool: any): Tool {
44 - const inputSchema = tool.input_parameters || tool.parameters;
45 - const outputSchema = tool.output_parameters || tool.response;
154 +export function toolFromApi(tool: unknown): Tool {
155 + const parsed = rawApiToolSchema.safeParse(tool);
156 + return toolFromRaw(parsed.success ? parsed.data : rawApiToolSchema.parse({}));
157 +}
158 +
159 +// --- Triggers ---------------------------------------------------------------
160
161 +const rawApiTriggerSchema = z.object({
162 + slug: lenientString,
163 + name: optionalString,
164 + display_name: optionalString,
165 + description: lenientString,
166 + type: z.enum(['webhook', 'poll']).optional().catch(undefined),
167 + config: z.unknown().optional(),
168 + payload: z.unknown().optional(),
169 + instructions: optionalString,
170 +});
171 +
172 +type RawApiTrigger = z.infer<typeof rawApiTriggerSchema>;
173 +
174 +function triggerFromRaw(raw: RawApiTrigger): Trigger {
175 return {
48 - slug: tool.slug || '',
49 - name: tool.name || tool.display_name || tool.slug || '',
50 - description: tool.description || '',
51 - input_parameters: processSchema(inputSchema),
52 - output_parameters: processSchema(outputSchema),
53 - scopes: tool.scopes || undefined,
54 - tags: tool.tags || undefined,
55 - is_deprecated: tool.is_deprecated || false,
176 + slug: raw.slug,
177 + name: raw.name || raw.display_name || raw.slug,
178 + description: raw.description,
179 + type: raw.type,
180 + config: processSchema(raw.config),
181 + payload: processSchema(raw.payload),
182 + instructions: raw.instructions,
183 };
184 }
185 +
186 +// Convert a raw API trigger object into our Trigger type
187 +export function triggerFromApi(trigger: unknown): Trigger {
188 + const parsed = rawApiTriggerSchema.safeParse(trigger);
189 + return triggerFromRaw(parsed.success ? parsed.data : rawApiTriggerSchema.parse({}));
190 +}
191 +
192 +// --- List responses ---------------------------------------------------------
193 +
194 +// Paged API responses arrive either as a bare array or as an { items } envelope.
195 +const listEnvelopeSchema = z.union([
196 + z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
197 + z.array(z.unknown()),
198 +]);
199 +
200 +/** Parses a /tools list response into Tool records, dropping non-object entries. */
201 +export const apiToolListSchema = listEnvelopeSchema.transform(items =>
202 + items.flatMap(item => {
203 + const parsed = rawApiToolSchema.safeParse(item);
204 + return parsed.success ? [toolFromRaw(parsed.data)] : [];
205 + })
206 +);
207 +
208 +/** Parses a /triggers_types list response into Trigger records, dropping non-object entries. */
209 +export const apiTriggerListSchema = listEnvelopeSchema.transform(items =>
210 + items.flatMap(item => {
211 + const parsed = rawApiTriggerSchema.safeParse(item);
212 + return parsed.success ? [triggerFromRaw(parsed.data)] : [];
213 + })
214 +);
docs/mdx-components.tsx
+15 -6
@@ -71,11 +71,20 @@ import {
71 } from 'lucide-react';
72
73 function slugify(text: string): string {
74 - return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
74 + return text
75 + .toLowerCase()
76 + .replace(/[^a-z0-9]+/g, '-')
77 + .replace(/(^-|-$)/g, '');
78 }
79
80 export function Accordion({ id, title, ...props }: ComponentProps<typeof BaseAccordion>) {
78 - return <BaseAccordion id={id ?? (typeof title === 'string' ? slugify(title) : undefined)} title={title} {...props} />;
81 + return (
82 + <BaseAccordion
83 + id={id ?? (typeof title === 'string' ? slugify(title) : undefined)}
84 + title={title}
85 + {...props}
86 + />
87 + );
88 }
89
90 export { Accordions };
@@ -83,10 +92,10 @@ export { Accordions };
92 export function getMDXComponents(components?: MDXComponents): MDXComponents {
93 return {
94 ...defaultMdxComponents,
86 - h2: (props) => <Heading as="h2" {...props} />,
87 - h3: (props) => <Heading as="h3" {...props} />,
88 - h4: (props) => <Heading as="h4" {...props} />,
89 - img: (props) => <ImageZoom {...(props as any)} />,
95 + h2: props => <Heading as="h2" {...props} />,
96 + h3: props => <Heading as="h3" {...props} />,
97 + h4: props => <Heading as="h4" {...props} />,
98 + img: props => <ImageZoom {...(props as ComponentProps<typeof ImageZoom>)} />,
99 YouTube,
100 Tabs,
101 Tab,
docs/scripts/generate-meta-tools.ts
+93 -35
@@ -21,18 +21,62 @@ import { join } from 'path';
21 import { fetchWithRetry } from './fetch-with-retry';
22 import { META_TOOL_OVERRIDES } from '../lib/meta-tool-overrides';
23 import { requireProductionApiV3Url, stripStagingHosts } from './production-api.mjs';
24 +import { z } from 'zod';
25
26 const API_BASE = requireProductionApiV3Url(process.env.COMPOSIO_API_BASE);
27 const API_KEY = process.env.COMPOSIO_API_KEY;
28
28 -if (!API_KEY) {
29 - console.error('Error: COMPOSIO_API_KEY environment variable is required');
30 - process.exit(1);
31 -}
32 -
29 const DATA_DIR = join(process.cwd(), 'public/data');
30 const CONTENT_DIR = join(process.cwd(), 'content/toolkits/meta-tools');
31
32 +interface GeneratedMetaTool {
33 + slug: string;
34 + name: string;
35 + displayName: string;
36 + description: string;
37 + tags: string[];
38 + toolkit: string | null;
39 + inputParameters: Record<string, unknown>;
40 + responseSchema: Record<string, unknown>;
41 +}
42 +
43 +// Zod schemas for the Tool Router payloads this script consumes. Parsing is
44 +// lenient: malformed fields degrade to empty fallbacks instead of aborting.
45 +
46 +const stringArraySchema = z
47 + .array(z.unknown())
48 + .catch([])
49 + .transform(items =>
50 + items.flatMap(item => {
51 + const parsed = z.string().safeParse(item);
52 + return parsed.success ? [parsed.data] : [];
53 + })
54 + );
55 +
56 +const recordSchema = z.record(z.string(), z.unknown()).catch({});
57 +
58 +const sessionResponseSchema = z
59 + .object({
60 + session_id: z.string().optional().catch(undefined),
61 + tool_router_tools: stringArraySchema,
62 + })
63 + .catch({ session_id: undefined, tool_router_tools: [] });
64 +
65 +const metaToolListSchema = z.union([
66 + z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
67 + z.array(z.unknown()),
68 +]);
69 +
70 +const rawMetaToolSchema = z.object({
71 + slug: z.string().catch(''),
72 + name: z.string().catch(''),
73 + description: z.string().catch(''),
74 + tags: stringArraySchema,
75 + toolkit: z.string().optional().catch(undefined),
76 + input_parameters: recordSchema,
77 + output_parameters: recordSchema,
78 +});
79 +
80 async function createSession(): Promise<string> {
81 console.log('Creating session...');
82
@@ -57,7 +101,7 @@ async function createSession(): Promise<string> {
101 throw new Error(`Failed to create session: ${response.status} ${response.statusText}\n${body}`);
102 }
103
60 - const data = await response.json();
104 + const data = sessionResponseSchema.parse(await response.json());
105 const sessionId = data.session_id;
106
107 if (!sessionId) {
@@ -65,11 +109,11 @@ async function createSession(): Promise<string> {
109 }
110
111 console.log(` Session created: ${sessionId}`);
68 - console.log(` Tools available: ${(data.tool_router_tools || []).join(', ')}`);
112 + console.log(` Tools available: ${data.tool_router_tools.join(', ')}`);
113 return sessionId;
114 }
115
72 -async function fetchMetaTools(sessionId: string): Promise<any[]> {
116 +async function fetchMetaTools(sessionId: string): Promise<unknown[]> {
117 console.log('Fetching meta tools with schemas...');
118
119 const response = await fetchWithRetry(`${API_BASE}/tool_router/session/${sessionId}/tools`, {
@@ -80,42 +124,44 @@ async function fetchMetaTools(sessionId: string): Promise<any[]> {
124
125 if (!response.ok) {
126 const body = await response.text();
83 - throw new Error(`Failed to fetch meta tools: ${response.status} ${response.statusText}\n${body}`);
127 + throw new Error(
128 + `Failed to fetch meta tools: ${response.status} ${response.statusText}\n${body}`
129 + );
130 }
131
86 - const data = await response.json();
87 - const tools = data.items || data;
88 -
89 - if (!Array.isArray(tools)) {
132 + const parsed = metaToolListSchema.safeParse(await response.json());
133 + if (!parsed.success) {
134 throw new Error('Expected array of tools in response');
135 }
136
93 - console.log(` Found ${tools.length} meta tools`);
94 - return tools;
137 + console.log(` Found ${parsed.data.length} meta tools`);
138 + return parsed.data;
139 }
140
97 -function transformTool(raw: any) {
98 - const slug: string = raw.slug || '';
141 +export function transformTool(value: unknown): GeneratedMetaTool {
142 + const parsed = rawMetaToolSchema.safeParse(value);
143 + const raw = parsed.success ? parsed.data : rawMetaToolSchema.parse({});
144 + const { slug, name } = raw;
145
146 return {
147 slug,
102 - name: raw.name || '',
103 - displayName: raw.name?.replace(/_/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase()) || slug,
104 - description: raw.description || '',
105 - tags: raw.tags || [],
148 + name,
149 + displayName: name.replace(/_/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase()) || slug,
150 + description: raw.description,
151 + tags: raw.tags,
152 toolkit: raw.toolkit || null,
107 - inputParameters: raw.input_parameters || {},
108 - responseSchema: raw.output_parameters || {},
153 + inputParameters: raw.input_parameters,
154 + responseSchema: raw.output_parameters,
155 };
156 }
157
158 /** Derive a short page slug from the tool slug: COMPOSIO_SEARCH_TOOLS -> search_tools */
113 -function pageSlug(toolSlug: string): string {
159 +export function pageSlug(toolSlug: string): string {
160 return toolSlug.toLowerCase().replace('composio_', '');
161 }
162
163 /** Truncate description to first sentence for index table */
118 -function briefDescription(description: string): string {
164 +export function briefDescription(description: string): string {
165 // Strip markdown and leading whitespace
166 const cleaned = description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim();
167 const firstSentence = cleaned.split(/\.(\s|$)/)[0];
@@ -126,7 +172,7 @@ function briefDescription(description: string): string {
172 }
173
174 /** One-line summary for the index table. Prefer hand-written override copy, fall back to the API description. */
129 -function indexLine(tool: any): string {
175 +function indexLine(tool: GeneratedMetaTool): string {
176 const override = META_TOOL_OVERRIDES[tool.slug];
177 if (override) {
178 // First sentence of the hand-written summary keeps the table tight.
@@ -137,7 +183,7 @@ function indexLine(tool: any): string {
183 }
184
185 /** Generate the index.mdx overview page — Modal-voice intro plus a one-line-per-tool table */
140 -function generateIndexMdx(tools: any[]): string {
186 +function generateIndexMdx(tools: GeneratedMetaTool[]): string {
187 let content = `---
188 title: Meta Tools
189 description: The system tools every Composio session gives your agent to discover, authenticate, execute, and process tools at runtime.
@@ -172,7 +218,7 @@ These schemas are for reference only. We do not guarantee backward compatibility
218 }
219
220 /** Generate an individual tool MDX page */
175 -function generateToolMdx(tool: any): string {
221 +function generateToolMdx(tool: GeneratedMetaTool): string {
222 const desc = briefDescription(tool.description).replace(/"/g, '\\"');
223
224 return `---
@@ -190,7 +236,7 @@ import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';
236 }
237
238 /** Generate meta.json for sidebar navigation — index.mdx is the folder page */
193 -function generateMetaJson(tools: any[]): string {
239 +function generateMetaJson(tools: GeneratedMetaTool[]): string {
240 const pages = tools.map(t => pageSlug(t.slug));
241 return JSON.stringify({ title: 'Meta Tools', defaultOpen: true, pages }, null, 2) + '\n';
242 }
@@ -222,8 +268,13 @@ async function main() {
268 metaTools.sort((a, b) => a.slug.localeCompare(b.slug));
269
270 // 1. Write JSON data
225 - await writeFile(join(DATA_DIR, 'meta-tools.json'), stripStagingHosts(JSON.stringify(metaTools, null, 2)));
226 - console.log(`\nWrote public/data/meta-tools.json (~${Math.round(JSON.stringify(metaTools).length / 1024)}KB)`);
271 + await writeFile(
272 + join(DATA_DIR, 'meta-tools.json'),
273 + stripStagingHosts(JSON.stringify(metaTools, null, 2))
274 + );
275 + console.log(
276 + `\nWrote public/data/meta-tools.json (~${Math.round(JSON.stringify(metaTools).length / 1024)}KB)`
277 + );
278
279 // 2. Clean old generated MDX files and regenerate
280 await cleanGeneratedMdx();
@@ -247,7 +298,14 @@ async function main() {
298 console.log(`Tools: ${metaTools.map(t => t.slug).join(', ')}`);
299 }
300
250 -main().catch((error) => {
251 - console.error('Fatal error:', error);
252 - process.exit(1);
253 -});
301 +if (import.meta.main) {
302 + if (!API_KEY) {
303 + console.error('Error: COMPOSIO_API_KEY environment variable is required');
304 + process.exit(1);
305 + }
306 +
307 + main().catch(error => {
308 + console.error('Fatal error:', error);
309 + process.exit(1);
310 + });
311 +}
docs/scripts/generate-toolkits.ts
+239 -105
@@ -13,15 +13,11 @@ import { join } from 'path';
13 import { fetchWithRetry } from './fetch-with-retry';
14 import { requireProductionApiV3Url, stripStagingHosts } from './production-api.mjs';
15 import { applyToolkitVersions, fetchProductionToolkitVersions } from './toolkit-versions';
16 +import { z } from 'zod';
17
18 const API_BASE = requireProductionApiV3Url(process.env.COMPOSIO_API_BASE);
19 const API_KEY = process.env.COMPOSIO_API_KEY;
20
20 -if (!API_KEY) {
21 - console.error('Error: COMPOSIO_API_KEY environment variable is required');
22 - process.exit(1);
23 -}
24 -
21 const OUTPUT_DIR = join(process.cwd(), 'public/data');
22
23 interface Tool {
@@ -76,6 +72,124 @@ interface Toolkit {
72 authConfigDetails?: AuthConfigDetail[];
73 }
74
75 +// Zod schemas for the raw API payloads this script consumes. Parsing is
76 +// lenient on purpose: malformed fields degrade to the same fallbacks the
77 +// hand-written mapping used to apply, so a partially bad catalog entry never
78 +// aborts a full generation run.
79 +
80 +/** Optional lenient string array: undefined when absent/non-array, junk members dropped. */
81 +const optionalStringArraySchema = z
82 + .array(z.unknown())
83 + .optional()
84 + .catch(undefined)
85 + .transform(items =>
86 + items?.flatMap(item => {
87 + const parsed = z.string().safeParse(item);
88 + return parsed.success ? [parsed.data] : [];
89 + })
90 + );
91 +
92 +const rawToolkitSchema = z.object({
93 + slug: z.string().catch(''),
94 + name: z.string().optional().catch(undefined),
95 + logo: z.string().optional().catch(undefined),
96 + description: z.string().catch(''),
97 + meta: z
98 + .object({
99 + logo: z.string().optional().catch(undefined),
100 + description: z.string().optional().catch(undefined),
101 + categories: z.array(z.unknown()).catch([]),
102 + })
103 + .catch({ logo: undefined, description: undefined, categories: [] }),
104 + auth_schemes: optionalStringArraySchema,
105 + authSchemes: optionalStringArraySchema,
106 + composio_managed_auth_schemes: optionalStringArraySchema,
107 + composioManagedAuthSchemes: optionalStringArraySchema,
108 + tool_count: z.number().optional().catch(undefined),
109 + toolCount: z.number().optional().catch(undefined),
110 + trigger_count: z.number().optional().catch(undefined),
111 + triggerCount: z.number().optional().catch(undefined),
112 +});
113 +
114 +const categoryEntrySchema = z.union([
115 + z.string(),
116 + z.object({ name: z.string() }).transform(entry => entry.name),
117 +]);
118 +
119 +// A paged toolkits response: { items, next_cursor } envelope or a bare array.
120 +const toolkitsPageSchema = z.union([
121 + z.object({
122 + items: z.array(z.unknown()),
123 + next_cursor: z.string().optional().catch(undefined),
124 + }),
125 + z.array(z.unknown()).transform(items => ({ items, next_cursor: undefined })),
126 +]);
127 +
128 +const slugItemSchema = z.object({ slug: z.string() });
129 +
130 +// Tools/triggers list entries share the slug/name/description shape.
131 +const rawNamedItemSchema = z.object({
132 + slug: z.string().catch(''),
133 + name: z.string().optional().catch(undefined),
134 + display_name: z.string().optional().catch(undefined),
135 + description: z.string().catch(''),
136 +});
137 +
138 +const namedItemListSchema = z
139 + .union([
140 + z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
141 + z.array(z.unknown()),
142 + ])
143 + .catch([])
144 + .transform(items =>
145 + items.flatMap(item => {
146 + const parsed = rawNamedItemSchema.safeParse(item);
147 + if (!parsed.success) return [];
148 + const { slug, name, display_name, description } = parsed.data;
149 + return [{ slug, name: name || display_name || slug, description }];
150 + })
151 + );
152 +
153 +const requirementListsSchema = z
154 + .object({
155 + required: z.array(z.unknown()).catch([]),
156 + optional: z.array(z.unknown()).catch([]),
157 + })
158 + .catch({ required: [], optional: [] });
159 +
160 +const authConfigFieldsSchema = z
161 + .object({
162 + auth_config_creation: requirementListsSchema,
163 + connected_account_initiation: requirementListsSchema,
164 + })
165 + .catch({
166 + auth_config_creation: { required: [], optional: [] },
167 + connected_account_initiation: { required: [], optional: [] },
168 + });
169 +
170 +const rawAuthConfigFieldSchema = z.object({
171 + name: z.string().catch(''),
172 + displayName: z.string().optional().catch(undefined),
173 + type: z.string().catch('string'),
174 + description: z.string().catch(''),
175 + required: z.boolean().optional().catch(undefined),
176 + default: z
177 + .union([z.string(), z.number(), z.boolean()])
178 + .transform(value => String(value))
179 + .nullable()
180 + .optional()
181 + .catch(undefined),
182 +});
183 +
184 +const rawAuthConfigDetailSchema = z.object({
185 + mode: z.string().catch(''),
186 + name: z.string().optional().catch(undefined),
187 +});
188 +
189 +const authConfigDetailsResponseSchema = z
190 + .object({ auth_config_details: z.array(z.unknown()).catch([]) })
191 + .catch({ auth_config_details: [] });
192 +
193 // The backend silently caps `limit` at 1000 per page and defaults to usage
194 // ordering, so a single request returns only the top-1000 toolkits — about half
195 // the catalog. Request the cap and follow `next_cursor` until exhausted.
@@ -83,10 +197,18 @@ interface Toolkit {
197 const TOOLKITS_PAGE_LIMIT = 1000;
198 const TOOLKITS_MAX_PAGES = 12;
199
86 -async function fetchToolkits(): Promise<any[]> {
200 +export function parseToolkitsPage(value: unknown) {
201 + return toolkitsPageSchema.parse(value);
202 +}
203 +
204 +export function parseNamedItems(value: unknown) {
205 + return namedItemListSchema.parse(value);
206 +}
207 +
208 +async function fetchToolkits(): Promise<unknown[]> {
209 console.log('Fetching toolkits from API...');
210
89 - const items: any[] = [];
211 + const items: unknown[] = [];
212 // Pages can overlap when the catalog shifts between cursor fetches; keep the
213 // first occurrence so API-provided ordering stays stable.
214 const seen = new Set<string>();
@@ -107,10 +229,10 @@ async function fetchToolkits(): Promise<any[]> {
229 throw new Error(`Failed to fetch toolkits: ${response.status} ${response.statusText}`);
230 }
231
110 - const data = await response.json();
111 - const pageItems: any[] = data.items || data;
112 - for (const item of pageItems) {
113 - const slug = item?.slug?.toLowerCase();
232 + const pageData = parseToolkitsPage(await response.json());
233 + for (const item of pageData.items) {
234 + const parsedSlug = slugItemSchema.safeParse(item);
235 + const slug = parsedSlug.success ? parsedSlug.data.slug.toLowerCase() : undefined;
236 if (slug) {
237 if (seen.has(slug)) continue;
238 seen.add(slug);
@@ -118,7 +240,7 @@ async function fetchToolkits(): Promise<any[]> {
240 items.push(item);
241 }
242
121 - cursor = data.next_cursor ?? undefined;
243 + cursor = pageData.next_cursor;
244 if (!cursor) return items;
245 }
246
@@ -130,45 +252,81 @@ async function fetchToolkits(): Promise<any[]> {
252 }
253
254 async function fetchToolsForToolkit(slug: string): Promise<Tool[]> {
133 - const response = await fetchWithRetry(`${API_BASE}/tools?toolkit_slug=${slug}&toolkit_versions=latest&limit=1000`, {
134 - headers: {
135 - 'Content-Type': 'application/json',
136 - 'x-api-key': API_KEY!,
137 - },
138 - });
255 + const response = await fetchWithRetry(
256 + `${API_BASE}/tools?toolkit_slug=${slug}&toolkit_versions=latest&limit=1000`,
257 + {
258 + headers: {
259 + 'Content-Type': 'application/json',
260 + 'x-api-key': API_KEY!,
261 + },
262 + }
263 + );
264
265 if (!response.ok) return [];
266
142 - const data = await response.json();
143 - const rawItems = data.items || data;
144 - const items = Array.isArray(rawItems) ? rawItems : [];
145 -
146 - return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
147 - slug: raw.slug || '',
148 - name: raw.name || raw.display_name || raw.slug || '',
149 - description: raw.description || '',
150 - }));
267 + return parseNamedItems(await response.json());
268 }
269
270 async function fetchTriggersForToolkit(slug: string): Promise<Trigger[]> {
154 - const response = await fetchWithRetry(`${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`, {
155 - headers: {
156 - 'Content-Type': 'application/json',
157 - 'x-api-key': API_KEY!,
158 - },
159 - });
271 + const response = await fetchWithRetry(
272 + `${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`,
273 + {
274 + headers: {
275 + 'Content-Type': 'application/json',
276 + 'x-api-key': API_KEY!,
277 + },
278 + }
279 + );
280
281 if (!response.ok) return [];
282
163 - const data = await response.json();
164 - const rawItems = data.items || data;
165 - const items = Array.isArray(rawItems) ? rawItems : [];
283 + return parseNamedItems(await response.json());
284 +}
285
167 - return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
168 - slug: raw.slug || '',
169 - name: raw.name || raw.display_name || raw.slug || '',
170 - description: raw.description || '',
171 - }));
286 +export function transformAuthConfigField(value: unknown, required: boolean): AuthConfigField {
287 + const parsed = rawAuthConfigFieldSchema.safeParse(value);
288 + const field = parsed.success ? parsed.data : rawAuthConfigFieldSchema.parse({});
289 +
290 + return {
291 + name: field.name,
292 + displayName: field.displayName || field.name,
293 + type: field.type,
294 + description: field.description,
295 + required: field.required ?? required,
296 + default: field.default ?? null,
297 + };
298 +}
299 +
300 +export function authConfigFields(
301 + raw: Record<string, unknown>,
302 + phase: 'auth_config_creation' | 'connected_account_initiation',
303 + requirement: 'required' | 'optional'
304 +): AuthConfigField[] {
305 + const fields = authConfigFieldsSchema.parse(raw.fields);
306 + return fields[phase][requirement].map(field =>
307 + transformAuthConfigField(field, requirement === 'required')
308 + );
309 +}
310 +
311 +export function transformAuthConfigDetail(value: unknown): AuthConfigDetail | null {
312 + const raw = z.record(z.string(), z.unknown()).safeParse(value);
313 + if (!raw.success) return null;
314 +
315 + const { mode, name } = rawAuthConfigDetailSchema.parse(raw.data);
316 + return {
317 + mode,
318 + name: name || mode,
319 + fields: {
320 + auth_config_creation: {
321 + required: authConfigFields(raw.data, 'auth_config_creation', 'required'),
322 + optional: authConfigFields(raw.data, 'auth_config_creation', 'optional'),
323 + },
324 + connected_account_initiation: {
325 + required: authConfigFields(raw.data, 'connected_account_initiation', 'required'),
326 + optional: authConfigFields(raw.data, 'connected_account_initiation', 'optional'),
327 + },
328 + },
329 + };
330 }
331
332 async function fetchAuthConfigDetails(slug: string): Promise<AuthConfigDetail[]> {
@@ -181,67 +339,34 @@ async function fetchAuthConfigDetails(slug: string): Promise<AuthConfigDetail[]>
339
340 if (!response.ok) return [];
341
184 - const data = await response.json();
185 - const authConfigDetails = data.auth_config_details || [];
342 + const data = authConfigDetailsResponseSchema.parse(await response.json());
343
187 - return authConfigDetails.map((raw: any) => ({
188 - mode: raw.mode || '',
189 - name: raw.name || raw.mode || '',
190 - fields: {
191 - auth_config_creation: {
192 - required: (raw.fields?.auth_config_creation?.required || []).map((f: any) => ({
193 - name: f.name || '',
194 - displayName: f.displayName || f.name || '',
195 - type: f.type || 'string',
196 - description: f.description || '',
197 - required: f.required ?? true,
198 - default: f.default ?? null,
199 - })),
200 - optional: (raw.fields?.auth_config_creation?.optional || []).map((f: any) => ({
201 - name: f.name || '',
202 - displayName: f.displayName || f.name || '',
203 - type: f.type || 'string',
204 - description: f.description || '',
205 - required: f.required ?? false,
206 - default: f.default ?? null,
207 - })),
208 - },
209 - connected_account_initiation: {
210 - required: (raw.fields?.connected_account_initiation?.required || []).map((f: any) => ({
211 - name: f.name || '',
212 - displayName: f.displayName || f.name || '',
213 - type: f.type || 'string',
214 - description: f.description || '',
215 - required: f.required ?? true,
216 - default: f.default ?? null,
217 - })),
218 - optional: (raw.fields?.connected_account_initiation?.optional || []).map((f: any) => ({
219 - name: f.name || '',
220 - displayName: f.displayName || f.name || '',
221 - type: f.type || 'string',
222 - description: f.description || '',
223 - required: f.required ?? false,
224 - default: f.default ?? null,
225 - })),
226 - },
227 - },
228 - }));
344 + return data.auth_config_details.flatMap(item => {
345 + const detail = transformAuthConfigDetail(item);
346 + return detail ? [detail] : [];
347 + });
348 }
349
231 -function transformToolkit(raw: any): Toolkit {
232 - const authSchemes = raw.auth_schemes || raw.authSchemes || [];
233 - const composioManaged = raw.composio_managed_auth_schemes || raw.composioManagedAuthSchemes || [];
350 +export function transformToolkit(raw: unknown): Toolkit {
351 + const parsed = rawToolkitSchema.safeParse(raw);
352 + const toolkit = parsed.success ? parsed.data : rawToolkitSchema.parse({});
353 + const slug = toolkit.slug.toLowerCase();
354 + const firstCategory = categoryEntrySchema.safeParse(toolkit.meta.categories[0]);
355 + const category = firstCategory.success ? firstCategory.data : null;
356 + const authSchemes = toolkit.auth_schemes ?? toolkit.authSchemes ?? [];
357 + const composioManaged =
358 + toolkit.composio_managed_auth_schemes ?? toolkit.composioManagedAuthSchemes ?? [];
359
360 return {
236 - slug: raw.slug?.toLowerCase() || '',
237 - name: raw.name || raw.slug || '',
238 - logo: raw.meta?.logo || raw.logo || null,
239 - description: raw.meta?.description || raw.description || '',
240 - category: raw.meta?.categories?.[0]?.name || raw.meta?.categories?.[0] || null,
361 + slug,
362 + name: toolkit.name || toolkit.slug,
363 + logo: toolkit.meta.logo || toolkit.logo || null,
364 + description: toolkit.meta.description || toolkit.description,
365 + category: category || null,
366 authSchemes,
367 ...(composioManaged.length > 0 ? { composioManagedAuthSchemes: composioManaged } : {}),
243 - toolCount: raw.tool_count || raw.toolCount || 0,
244 - triggerCount: raw.trigger_count || raw.triggerCount || 0,
368 + toolCount: toolkit.tool_count || toolkit.toolCount || 0,
369 + triggerCount: toolkit.trigger_count || toolkit.triggerCount || 0,
370 version: null,
371 tools: [],
372 triggers: [],
@@ -279,7 +404,7 @@ async function main() {
404 const batch = toolkits.slice(i, i + batchSize);
405
406 await Promise.all(
282 - batch.map(async (toolkit) => {
407 + batch.map(async toolkit => {
408 const [tools, triggers, authConfigDetails] = await Promise.all([
409 fetchToolsForToolkit(toolkit.slug.toUpperCase()),
410 fetchTriggersForToolkit(toolkit.slug.toUpperCase()),
@@ -312,12 +437,14 @@ async function main() {
437 // Write light file (for landing page - imported in client component)
438 // Excludes tools and triggers arrays to keep bundle size small
439 const toolkitsLight = toolkits.map(({ slug, name, logo, category, toolCount, triggerCount }) => ({
315 - slug, name, logo, category, toolCount, triggerCount,
440 + slug,
441 + name,
442 + logo,
443 + category,
444 + toolCount,
445 + triggerCount,
446 }));
317 - await writeFile(
318 - join(OUTPUT_DIR, 'toolkits-list.json'),
319 - JSON.stringify(toolkitsLight, null, 2)
320 - );
447 + await writeFile(join(OUTPUT_DIR, 'toolkits-list.json'), JSON.stringify(toolkitsLight, null, 2));
448
449 const fullSizeKB = Math.round(JSON.stringify(toolkits).length / 1024);
450 const lightSizeKB = Math.round(JSON.stringify(toolkitsLight).length / 1024);
@@ -327,7 +454,14 @@ async function main() {
454 console.log(` Toolkits: ${toolkits.length}`);
455 }
456
330 -main().catch((error) => {
331 - console.error('Fatal error:', error);
332 - process.exit(1);
333 -});
457 +if (import.meta.main) {
458 + if (!API_KEY) {
459 + console.error('Error: COMPOSIO_API_KEY environment variable is required');
460 + process.exit(1);
461 + }
462 +
463 + main().catch(error => {
464 + console.error('Fatal error:', error);
465 + process.exit(1);
466 + });
467 +}
docs/scripts/validate-links.ts
+43 -33
@@ -1,19 +1,10 @@
1 import { readFile } from 'node:fs/promises';
2 import { glob } from 'node:fs/promises';
3 import { resolve } from 'node:path';
4 -import {
5 - type FileObject,
6 - printErrors,
7 - scanURLs,
8 - validateFiles,
9 -} from 'next-validate-link';
4 +import { type FileObject, printErrors, scanURLs, validateFiles } from 'next-validate-link';
5 import GithubSlugger from 'github-slugger';
11 -import {
12 - source,
13 - getReferenceSource,
14 - examplesSource,
15 - toolkitsSource,
16 -} from '../lib/source';
6 +import { z } from 'zod';
7 +import { source, getReferenceSource, examplesSource, toolkitsSource } from '../lib/source';
8
9 /**
10 * `--external` additionally HEAD/GET-checks every external URL. Slow and
@@ -53,16 +44,31 @@ function extractHeadingsFromContent(content: string): string[] {
44 return headings;
45 }
46
47 +// Page data differs per source (MDX pages carry toc/getText, OpenAPI pages do
48 +// not), so the pieces this script walks are parsed instead of guarded by hand.
49 +const tocEntrySchema = z.object({ url: z.string() });
50 +const tocPageDataSchema = z.object({ toc: z.array(z.unknown()) });
51 +const textPageDataSchema = z.object({
52 + getText: z.custom<(mode: 'processed' | 'raw') => Promise<string>>(
53 + value => typeof value === 'function'
54 + ),
55 +});
56 +
57 /**
58 * Get headings for a page, trying data.toc first then falling back to raw content parsing.
59 */
60 async function getHeadingsForPage(page: PageOf): Promise<string[]> {
60 - if (page.data.toc?.length) {
61 - return page.data.toc.map((item: { url: string }) => item.url.slice(1));
61 + const tocData = tocPageDataSchema.safeParse(page.data);
62 + if (tocData.success && tocData.data.toc.length > 0) {
63 + return tocData.data.toc.flatMap(item => {
64 + const entry = tocEntrySchema.safeParse(item);
65 + return entry.success ? [entry.data.url.slice(1)] : [];
66 + });
67 }
63 - if ('getText' in page.data) {
68 + const textData = textPageDataSchema.safeParse(page.data);
69 + if (textData.success) {
70 try {
65 - const content = await (page.data as { getText: (mode: string) => Promise<string> }).getText('raw');
71 + const content = await textData.data.getText('raw');
72 return extractHeadingsFromContent(content);
73 } catch {
74 // fall through
@@ -87,14 +93,16 @@ async function buildPopulateEntries(src: AnySource) {
93 src.getPages().map(async (page: PageOf) => ({
94 value: { slug: page.slugs },
95 hashes: await getHeadingsForPage(page),
90 - })),
96 + }))
97 );
98 }
99
100 +const toolkitSlugsSchema = z.array(z.object({ slug: z.string() }));
101 +
102 async function getDynamicToolkitEntries() {
103 const raw = await readFile('public/data/toolkits.json', 'utf-8');
96 - const toolkits: { slug: string }[] = JSON.parse(raw);
97 - return toolkits.map((t) => ({ value: { slug: [t.slug] }, hashes: [] as string[] }));
104 + const toolkits = toolkitSlugsSchema.parse(JSON.parse(raw));
105 + return toolkits.map(t => ({ value: { slug: [t.slug] }, hashes: [] as string[] }));
106 }
107
108 const EXTERNAL_FETCH_HEADERS = {
@@ -160,13 +168,14 @@ function validateExternalUrl(url: URL) {
168
169 async function checkLinks() {
170 const referenceSource = await getReferenceSource();
163 - const [docsEntries, refEntries, exampleEntries, toolkitEntries, dynamicToolkitEntries] = await Promise.all([
164 - buildPopulateEntries(source),
165 - buildPopulateEntries(referenceSource),
166 - buildPopulateEntries(examplesSource),
167 - buildPopulateEntries(toolkitsSource),
168 - getDynamicToolkitEntries(),
169 - ]);
171 + const [docsEntries, refEntries, exampleEntries, toolkitEntries, dynamicToolkitEntries] =
172 + await Promise.all([
173 + buildPopulateEntries(source),
174 + buildPopulateEntries(referenceSource),
175 + buildPopulateEntries(examplesSource),
176 + buildPopulateEntries(toolkitsSource),
177 + getDynamicToolkitEntries(),
178 + ]);
179
180 const scanned = await scanURLs({
181 preset: 'next',
@@ -193,12 +202,12 @@ async function checkLinks() {
202 // Filter out API route URLs (these are valid but not detected as pages)
203 const ignoredUrls = ['/llms.txt', '/llms-full.txt'];
204 const filteredErrors = errors
196 - .map((fileError) => ({
205 + .map(fileError => ({
206 ...fileError,
198 - errors: fileError.errors.filter((e) => !ignoredUrls.includes(e.url)),
199 - detected: fileError.detected.filter((d) => !ignoredUrls.includes(d[0] as string)),
207 + errors: fileError.errors.filter(e => !ignoredUrls.includes(e.url)),
208 + detected: fileError.detected.filter(d => !ignoredUrls.includes(d[0] as string)),
209 }))
201 - .filter((fileError) => fileError.errors.length > 0);
210 + .filter(fileError => fileError.errors.length > 0);
211
212 printErrors(filteredErrors, true);
213 if (filteredErrors.length > 0) {
@@ -217,11 +226,12 @@ async function getFiles(): Promise<FileObject[]> {
226 if (!page.absolutePath) continue;
227 if (!page.absolutePath.endsWith('.mdx') && !page.absolutePath.endsWith('.md')) continue;
228 // Skip OpenAPI-generated pages (they don't have getText)
220 - if (!('getText' in page.data)) continue;
229 + const textData = textPageDataSchema.safeParse(page.data);
230 + if (!textData.success) continue;
231
232 allFiles.push({
233 path: page.absolutePath,
224 - content: await (page.data as { getText: (mode: string) => Promise<string> }).getText('raw'),
234 + content: await textData.data.getText('raw'),
235 url: page.url,
236 data: page.data,
237 });
@@ -229,7 +239,7 @@ async function getFiles(): Promise<FileObject[]> {
239 }
240
241 // Scan any .md files under content/ not already covered by Fumadocs sources
232 - const coveredPaths = new Set(allFiles.map((f) => resolve(f.path)));
242 + const coveredPaths = new Set(allFiles.map(f => resolve(f.path)));
243 const extraMdFiles = await Array.fromAsync(glob('content/**/*.md'));
244 for (const filePath of extraMdFiles) {
245 if (coveredPaths.has(resolve(filePath))) continue;
docs/tests/static/generate-toolkits.test.ts new
+361
@@ -0,0 +1,361 @@
1 +/**
2 + * Regression tests for the raw-API-to-Toolkit transformation in
3 + * scripts/generate-toolkits.ts.
4 + *
5 + * The zod-based rewrite of transformToolkit/authConfigFields/
6 + * transformAuthConfigField parses raw API payloads leniently and rebuilds the
7 + * toolkit catalog field by field, so these tests pin the shapes
8 + * public/data/toolkits.json is expected to carry (see toolkit-schema.test.ts
9 + * for the sibling API-schema coverage).
10 + *
11 + * Only the pure transforms are exercised here — fetchToolkits,
12 + * fetchToolsForToolkit, fetchTriggersForToolkit, fetchAuthConfigDetails, and
13 + * main() all perform network I/O and are intentionally not covered by this
14 + * suite.
15 + */
16 +import { describe, test, expect } from "bun:test";
17 +import {
18 + authConfigFields,
19 + parseNamedItems,
20 + parseToolkitsPage,
21 + transformAuthConfigField,
22 + transformAuthConfigDetail,
23 + transformToolkit,
24 +} from "../../scripts/generate-toolkits";
25 +import { transformTool } from "../../scripts/generate-meta-tools";
26 +
27 +describe("transformToolkit", () => {
28 + test("maps a representative full toolkit object end to end", () => {
29 + const toolkit = transformToolkit({
30 + slug: "GITHUB",
31 + name: "GitHub",
32 + description: "toolkit-level description",
33 + meta: {
34 + logo: "https://logo.example/github.png",
35 + description: "meta description wins over toolkit description",
36 + categories: [{ name: "dev-tools" }, "productivity"],
37 + },
38 + auth_schemes: ["OAUTH2", "API_KEY", 123],
39 + composio_managed_auth_schemes: ["OAUTH2"],
40 + tool_count: 42,
41 + trigger_count: 3,
42 + });
43 +
44 + expect(toolkit.slug).toBe("github");
45 + expect(toolkit.name).toBe("GitHub");
46 + expect(toolkit.logo).toBe("https://logo.example/github.png");
47 + expect(toolkit.description).toBe("meta description wins over toolkit description");
48 + expect(toolkit.category).toBe("dev-tools");
49 + expect(toolkit.authSchemes).toEqual(["OAUTH2", "API_KEY"]);
50 + expect(toolkit.composioManagedAuthSchemes).toEqual(["OAUTH2"]);
51 + expect(toolkit.toolCount).toBe(42);
52 + expect(toolkit.triggerCount).toBe(3);
53 + expect(toolkit.version).toBeNull();
54 + expect(toolkit.tools).toEqual([]);
55 + expect(toolkit.triggers).toEqual([]);
56 + });
57 +
58 + test("slug is lowercased regardless of API casing", () => {
59 + const toolkit = transformToolkit({ slug: "SlAcK" });
60 + expect(toolkit.slug).toBe("slack");
61 + });
62 +
63 + test("falls back to logo/description/auth_schemes on toolkit root when meta is absent", () => {
64 + const toolkit = transformToolkit({
65 + slug: "notion",
66 + logo: "https://logo.example/notion.png",
67 + description: "root description",
68 + authSchemes: ["OAUTH2"],
69 + composioManagedAuthSchemes: ["OAUTH2"],
70 + });
71 +
72 + expect(toolkit.logo).toBe("https://logo.example/notion.png");
73 + expect(toolkit.description).toBe("root description");
74 + expect(toolkit.authSchemes).toEqual(["OAUTH2"]);
75 + expect(toolkit.composioManagedAuthSchemes).toEqual(["OAUTH2"]);
76 + });
77 +
78 + test("omits composioManagedAuthSchemes entirely when empty (not an empty array)", () => {
79 + const toolkit = transformToolkit({ slug: "test" });
80 + expect(toolkit).not.toHaveProperty("composioManagedAuthSchemes");
81 + });
82 +
83 + test("empty-string name falls back to the original-casing slug", () => {
84 + const toolkit = transformToolkit({ slug: "GitHub", name: "" });
85 + expect(toolkit.name).toBe("GitHub");
86 + });
87 +
88 + test("missing name falls back to the original-casing slug", () => {
89 + const toolkit = transformToolkit({ slug: "GitHub" });
90 + expect(toolkit.name).toBe("GitHub");
91 + });
92 +
93 + test("empty meta values fall back to root logo and description", () => {
94 + const toolkit = transformToolkit({
95 + slug: "github",
96 + logo: "https://logo.example/github.png",
97 + description: "root description",
98 + meta: { logo: "", description: "" },
99 + });
100 +
101 + expect(toolkit.logo).toBe("https://logo.example/github.png");
102 + expect(toolkit.description).toBe("root description");
103 + });
104 +
105 + test("non-string tool_count/trigger_count are dropped in favor of the numeric fallback", () => {
106 + const toolkit = transformToolkit({
107 + slug: "test",
108 + tool_count: "42",
109 + trigger_count: null,
110 + });
111 + expect(toolkit.toolCount).toBe(0);
112 + expect(toolkit.triggerCount).toBe(0);
113 + });
114 +
115 + test("non-string auth_schemes members are filtered out of the array", () => {
116 + const toolkit = transformToolkit({
117 + slug: "test",
118 + auth_schemes: ["OAUTH2", 42, null, "API_KEY", { scheme: "x" }],
119 + });
120 + expect(toolkit.authSchemes).toEqual(["OAUTH2", "API_KEY"]);
121 + });
122 +
123 + test("non-array auth_schemes yields an empty array, never a non-array value", () => {
124 + const toolkit = transformToolkit({ slug: "test", auth_schemes: "OAUTH2" });
125 + expect(Array.isArray(toolkit.authSchemes)).toBe(true);
126 + expect(toolkit.authSchemes).toEqual([]);
127 + });
128 +
129 + test("category falls back to null when the first category entry has no string name", () => {
130 + const toolkit = transformToolkit({
131 + slug: "test",
132 + meta: { categories: [{ notName: "x" }] },
133 + });
134 + expect(toolkit.category).toBeNull();
135 + });
136 +
137 + test("category is null when categories is absent or not an array", () => {
138 + expect(transformToolkit({ slug: "test" }).category).toBeNull();
139 + expect(transformToolkit({ slug: "test", meta: { categories: "dev-tools" } }).category).toBeNull();
140 + });
141 +
142 + test("empty category names fall back to null", () => {
143 + expect(transformToolkit({ slug: "test", meta: { categories: [""] } }).category).toBeNull();
144 + expect(
145 + transformToolkit({ slug: "test", meta: { categories: [{ name: "" }] } }).category
146 + ).toBeNull();
147 + });
148 +
149 + test("malformed/empty input objects do not throw", () => {
150 + expect(() => transformToolkit({})).not.toThrow();
151 + expect(() => transformToolkit(null)).not.toThrow();
152 + expect(() => transformToolkit(undefined)).not.toThrow();
153 + expect(() => transformToolkit("not-an-object")).not.toThrow();
154 + expect(() => transformToolkit(42)).not.toThrow();
155 + expect(() => transformToolkit([])).not.toThrow();
156 +
157 + const toolkit = transformToolkit(null);
158 + expect(toolkit.slug).toBe("");
159 + expect(toolkit.name).toBe("");
160 + expect(toolkit.logo).toBeNull();
161 + expect(toolkit.description).toBe("");
162 + expect(toolkit.authSchemes).toEqual([]);
163 + expect(toolkit.toolCount).toBe(0);
164 + expect(toolkit.triggerCount).toBe(0);
165 + });
166 +});
167 +
168 +describe("transformAuthConfigField", () => {
169 + test("maps a representative required field", () => {
170 + const field = transformAuthConfigField(
171 + {
172 + name: "api_key",
173 + displayName: "API Key",
174 + type: "string",
175 + description: "Your API key",
176 + required: true,
177 + default: "fallback-value",
178 + },
179 + false
180 + );
181 +
182 + expect(field).toEqual({
183 + name: "api_key",
184 + displayName: "API Key",
185 + type: "string",
186 + description: "Your API key",
187 + required: true,
188 + default: "fallback-value",
189 + });
190 + });
191 +
192 + test("displayName falls back to name when absent", () => {
193 + const field = transformAuthConfigField({ name: "client_id" }, true);
194 + expect(field.displayName).toBe("client_id");
195 + });
196 +
197 + test("empty displayName falls back to name", () => {
198 + const field = transformAuthConfigField({ name: "client_id", displayName: "" }, true);
199 + expect(field.displayName).toBe("client_id");
200 + });
201 +
202 + test("required falls back to the caller-supplied requirement when the API omits it", () => {
203 + const required = transformAuthConfigField({ name: "x" }, true);
204 + const optional = transformAuthConfigField({ name: "x" }, false);
205 + expect(required.required).toBe(true);
206 + expect(optional.required).toBe(false);
207 + });
208 +
209 + test("type defaults to 'string' when missing or non-string", () => {
210 + expect(transformAuthConfigField({ name: "x" }, false).type).toBe("string");
211 + expect(transformAuthConfigField({ name: "x", type: 7 }, false).type).toBe("string");
212 + });
213 +
214 + test("scalar defaults are preserved as strings while structured values are dropped", () => {
215 + expect(transformAuthConfigField({ name: "x", default: 5 }, false).default).toBe("5");
216 + expect(transformAuthConfigField({ name: "x", default: false }, false).default).toBe("false");
217 + expect(transformAuthConfigField({ name: "x", default: { a: 1 } }, false).default).toBeNull();
218 + expect(transformAuthConfigField({ name: "x", default: ["a"] }, false).default).toBeNull();
219 + expect(transformAuthConfigField({ name: "x", default: null }, false).default).toBeNull();
220 + expect(transformAuthConfigField({ name: "x" }, false).default).toBeNull();
221 + });
222 +
223 + test("malformed/empty input does not throw", () => {
224 + expect(() => transformAuthConfigField(null, false)).not.toThrow();
225 + expect(() => transformAuthConfigField(undefined, true)).not.toThrow();
226 + expect(() => transformAuthConfigField("nope", false)).not.toThrow();
227 + expect(() => transformAuthConfigField(42, false)).not.toThrow();
228 +
229 + const field = transformAuthConfigField(null, true);
230 + expect(field.name).toBe("");
231 + expect(field.displayName).toBe("");
232 + expect(field.type).toBe("string");
233 + expect(field.description).toBe("");
234 + expect(field.required).toBe(true);
235 + expect(field.default).toBeNull();
236 + });
237 +});
238 +
239 +describe("transformAuthConfigDetail", () => {
240 + test("empty names fall back to the auth mode", () => {
241 + const detail = transformAuthConfigDetail({ mode: "oauth2", name: "" });
242 + expect(detail?.name).toBe("oauth2");
243 + });
244 +
245 + test("non-object entries are dropped", () => {
246 + expect(transformAuthConfigDetail(null)).toBeNull();
247 + expect(transformAuthConfigDetail("oauth2")).toBeNull();
248 + });
249 +});
250 +
251 +describe("authConfigFields", () => {
252 + const rawAuthConfig = {
253 + fields: {
254 + auth_config_creation: {
255 + required: [{ name: "client_id" }, { name: "client_secret" }],
256 + optional: [{ name: "redirect_url" }],
257 + },
258 + connected_account_initiation: {
259 + required: [{ name: "code" }],
260 + optional: "not-an-array",
261 + },
262 + },
263 + };
264 +
265 + test("extracts the required/optional field lists for a given phase", () => {
266 + const required = authConfigFields(rawAuthConfig, "auth_config_creation", "required");
267 + const optional = authConfigFields(rawAuthConfig, "auth_config_creation", "optional");
268 +
269 + expect(required.map(f => f.name)).toEqual(["client_id", "client_secret"]);
270 + expect(required.every(f => f.required)).toBe(true);
271 + expect(optional.map(f => f.name)).toEqual(["redirect_url"]);
272 + expect(optional.every(f => f.required)).toBe(false);
273 + });
274 +
275 + test("non-array requirement lists always yield an array, never throwing", () => {
276 + const optional = authConfigFields(rawAuthConfig, "connected_account_initiation", "optional");
277 + expect(Array.isArray(optional)).toBe(true);
278 + expect(optional).toEqual([]);
279 + });
280 +
281 + test("malformed/empty input objects do not throw and yield an empty array", () => {
282 + expect(() => authConfigFields({}, "auth_config_creation", "required")).not.toThrow();
283 + expect(authConfigFields({}, "auth_config_creation", "required")).toEqual([]);
284 + expect(authConfigFields({ fields: null }, "auth_config_creation", "required")).toEqual([]);
285 + });
286 +});
287 +
288 +// generate-meta-tools.ts's transformTool is a cheap, pure sibling transform
289 +// built on the same lenient zod parsing; a couple of cases here mirror the
290 +// coverage above without pulling in createSession/fetchMetaTools (network).
291 +describe("transformTool (generate-meta-tools.ts)", () => {
292 + test("maps a representative full meta tool object end to end", () => {
293 + const tool = transformTool({
294 + slug: "COMPOSIO_SEARCH_TOOLS",
295 + name: "composio_search_tools",
296 + description: "Searches for tools",
297 + tags: ["discovery", "search", 42],
298 + toolkit: "meta",
299 + input_parameters: { type: "object" },
300 + output_parameters: { type: "object" },
301 + });
302 +
303 + expect(tool.slug).toBe("COMPOSIO_SEARCH_TOOLS");
304 + expect(tool.name).toBe("composio_search_tools");
305 + expect(tool.displayName).toBe("Composio Search Tools");
306 + expect(tool.description).toBe("Searches for tools");
307 + expect(tool.tags).toEqual(["discovery", "search"]);
308 + expect(tool.toolkit).toBe("meta");
309 + expect(tool.inputParameters).toEqual({ type: "object" });
310 + expect(tool.responseSchema).toEqual({ type: "object" });
311 + });
312 +
313 + test("toolkit falls back to null when absent or non-string", () => {
314 + expect(transformTool({ slug: "x", name: "x" }).toolkit).toBeNull();
315 + expect(transformTool({ slug: "x", name: "x", toolkit: "" }).toolkit).toBeNull();
316 + expect(transformTool({ slug: "x", name: "x", toolkit: 7 }).toolkit).toBeNull();
317 + });
318 +
319 + test("displayName falls back to the slug when name is empty", () => {
320 + const tool = transformTool({ slug: "COMPOSIO_X", name: "" });
321 + expect(tool.displayName).toBe("COMPOSIO_X");
322 + });
323 +
324 + test("malformed/empty input objects do not throw", () => {
325 + expect(() => transformTool({})).not.toThrow();
326 + expect(() => transformTool(null)).not.toThrow();
327 + expect(() => transformTool(undefined)).not.toThrow();
328 +
329 + const tool = transformTool({});
330 + expect(tool.slug).toBe("");
331 + expect(tool.name).toBe("");
332 + expect(tool.displayName).toBe("");
333 + expect(tool.tags).toEqual([]);
334 + expect(tool.toolkit).toBeNull();
335 + expect(tool.inputParameters).toEqual({});
336 + expect(tool.responseSchema).toEqual({});
337 + });
338 +});
339 +
340 +describe("parseToolkitsPage", () => {
341 + test("rejects malformed page envelopes instead of returning an empty page", () => {
342 + expect(() => parseToolkitsPage({ error: "rate limited" })).toThrow();
343 + expect(() => parseToolkitsPage({ items: null })).toThrow();
344 + expect(() => parseToolkitsPage("not a page")).toThrow();
345 + });
346 +});
347 +
348 +describe("parseNamedItems", () => {
349 + test("empty names fall back to display names", () => {
350 + expect(
351 + parseNamedItems([
352 + {
353 + slug: "GMAIL_SEND_EMAIL",
354 + name: "",
355 + display_name: "Send email",
356 + description: "Sends an email",
357 + },
358 + ])[0]?.name
359 + ).toBe("Send email");
360 + });
361 +});
docs/tests/static/llms-openapi.test.ts
+13 -1
@@ -33,9 +33,10 @@ mock.module("@/lib/toolkit-schema", () => ({
33 }));
34
35 let openapiPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").openapiPageToMarkdown;
36 +let degradedPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").degradedPageToMarkdown;
37
38 beforeAll(async () => {
38 - ({ openapiPageToMarkdown } = await import(
39 + ({ openapiPageToMarkdown, degradedPageToMarkdown } = await import(
40 "../../app/llms.mdx/[[...slug]]/route"
41 ));
42 });
@@ -183,3 +184,14 @@ describe("LLM OpenAPI markdown", () => {
184 );
185 });
186 });
187 +
188 +describe("LLM page degradation", () => {
189 + test("keeps a readable response when typed page parsing fails", () => {
190 + expect(
191 + degradedPageToMarkdown({
192 + url: "/docs/example",
193 + data: { title: 42, description: "Fallback copy" },
194 + })
195 + ).toBe("# 42 (/docs/example)\n\nFallback copy");
196 + });
197 +});
docs/tests/static/toolkit-schema.test.ts new
+190
@@ -0,0 +1,190 @@
1 +/**
2 + * Regression tests for the raw-API-to-ParameterSchema transformation.
3 + *
4 + * The zod-based rewrite of processSchema/toolFromApi parses raw JSON-Schema
5 + * nodes recursively and rebuilds them field by field, so these tests pin the
6 + * shapes the toolkit detail UI depends on (toolkit-detail.tsx reads
7 + * additionalProperties and items.additionalProperties, including their
8 + * nested properties, to synthesize the "[key: string]" row).
9 + */
10 +import { describe, test, expect } from "bun:test";
11 +import { processSchema, toolFromApi, triggerFromApi } from "../../lib/toolkit-schema";
12 +
13 +describe("processSchema", () => {
14 + test("dictionary-of-object param keeps nested additionalProperties subschema", () => {
15 + const params = processSchema({
16 + type: "object",
17 + properties: {
18 + metadata: {
19 + type: "object",
20 + additionalProperties: {
21 + type: "object",
22 + required: ["label"],
23 + properties: {
24 + label: { type: "string", description: "Display label" },
25 + weight: { type: "number" },
26 + },
27 + },
28 + },
29 + },
30 + });
31 +
32 + const additional = params?.metadata.additionalProperties;
33 + expect(additional).toBeDefined();
34 + expect(typeof additional).toBe("object");
35 + if (typeof additional === "object") {
36 + expect(additional.type).toBe("object");
37 + expect(additional.requiredFields).toEqual(["label"]);
38 + expect(additional.properties?.label.type).toBe("string");
39 + expect(additional.properties?.label.description).toBe("Display label");
40 + expect(additional.properties?.weight.type).toBe("number");
41 + }
42 + });
43 +
44 + test("array-of-dictionary param keeps items.additionalProperties", () => {
45 + const params = processSchema({
46 + type: "object",
47 + properties: {
48 + rows: {
49 + type: "array",
50 + items: {
51 + type: "object",
52 + additionalProperties: { type: "string", description: "cell value" },
53 + },
54 + },
55 + },
56 + });
57 +
58 + const itemsAdditional = params?.rows.items?.additionalProperties;
59 + expect(itemsAdditional).toBeDefined();
60 + expect(typeof itemsAdditional).toBe("object");
61 + if (typeof itemsAdditional === "object") {
62 + expect(itemsAdditional.type).toBe("string");
63 + expect(itemsAdditional.description).toBe("cell value");
64 + }
65 + });
66 +
67 + test("boolean additionalProperties passes through unchanged", () => {
68 + const params = processSchema({
69 + type: "object",
70 + properties: {
71 + strict: { type: "object", additionalProperties: false },
72 + },
73 + });
74 +
75 + expect(params?.strict.additionalProperties).toBe(false);
76 + });
77 +
78 + test("array items keep the required-to-requiredFields remap and nested properties", () => {
79 + const params = processSchema({
80 + type: "object",
81 + required: ["records"],
82 + properties: {
83 + records: {
84 + type: "array",
85 + items: {
86 + type: "object",
87 + required: ["id"],
88 + properties: {
89 + id: { type: "string" },
90 + note: { type: "string" },
91 + },
92 + },
93 + },
94 + },
95 + });
96 +
97 + expect(params?.records.required).toBe(true);
98 + expect(params?.records.items?.requiredFields).toEqual(["id"]);
99 + expect(params?.records.items?.properties?.id.type).toBe("string");
100 + });
101 +
102 + test("tuple-form items array is not spread into numeric keys", () => {
103 + const params = processSchema({
104 + type: "object",
105 + properties: {
106 + pair: { type: "array", items: [{ type: "string" }, { type: "number" }] },
107 + },
108 + });
109 +
110 + expect(params?.pair.items).toBeUndefined();
111 + });
112 +
113 + test("scalar enum values are preserved as strings", () => {
114 + const params = processSchema({
115 + type: "object",
116 + properties: {
117 + priority: { type: "integer", enum: [1, 2, 3, true, { invalid: "object" }] },
118 + },
119 + });
120 +
121 + expect(params?.priority.enum).toEqual(["1", "2", "3", "true"]);
122 + });
123 +
124 + test("omits empty enum arrays from the serialized parameter shape", () => {
125 + const params = processSchema({
126 + type: "object",
127 + properties: { query: { type: "string" } },
128 + });
129 +
130 + expect(params?.query.enum).toBeUndefined();
131 + expect(JSON.stringify(params?.query)).not.toContain('"enum"');
132 + });
133 +});
134 +
135 +describe("toolFromApi", () => {
136 + test("maps slug fallback and nested schemas end to end", () => {
137 + const tool = toolFromApi({
138 + slug: "TEST_TOOL",
139 + description: "A test tool",
140 + input_parameters: {
141 + type: "object",
142 + properties: {
143 + config: {
144 + type: "object",
145 + additionalProperties: {
146 + type: "object",
147 + properties: { enabled: { type: "boolean" } },
148 + },
149 + },
150 + },
151 + },
152 + });
153 +
154 + expect(tool.name).toBe("TEST_TOOL");
155 + const additional = tool.input_parameters?.config.additionalProperties;
156 + expect(typeof additional).toBe("object");
157 + if (typeof additional === "object") {
158 + expect(additional.properties?.enabled.type).toBe("boolean");
159 + }
160 + });
161 +
162 + test("empty names fall back to display names", () => {
163 + expect(
164 + toolFromApi({
165 + slug: "TEST_TOOL",
166 + name: "",
167 + display_name: "Test tool",
168 + description: "A test tool",
169 + }).name
170 + ).toBe("Test tool");
171 +
172 + expect(
173 + triggerFromApi({
174 + slug: "TEST_TRIGGER",
175 + name: "",
176 + display_name: "Test trigger",
177 + description: "A test trigger",
178 + }).name
179 + ).toBe("Test trigger");
180 + });
181 +
182 + test("omits empty scope and tag arrays from the serialized tool shape", () => {
183 + const tool = toolFromApi({ slug: "TEST_TOOL" });
184 +
185 + expect(tool.scopes).toBeUndefined();
186 + expect(tool.tags).toBeUndefined();
187 + expect(JSON.stringify(tool)).not.toContain('"scopes"');
188 + expect(JSON.stringify(tool)).not.toContain('"tags"');
189 + });
190 +});