Skip to content

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)

Alberto Schiabel61aafbc9d341
diff --git a/docs/.oxlintrc.json b/docs/.oxlintrc.json
index 7d08179aa..8c812eea3 100644
--- a/docs/.oxlintrc.json
+++ b/docs/.oxlintrc.json
@@ -5,7 +5,7 @@
// rules, plus the two classic hooks rules (rules-of-hooks, exhaustive-deps).
// Dashboard-link policy uses the same ESLint-compatible no-restricted-syntax
// plugin as the root workspace config.
- "plugins": ["nextjs", "react", "import", "jsx-a11y"],
+ "plugins": ["typescript", "nextjs", "react", "import", "jsx-a11y"],
"jsPlugins": [{ "name": "eslint-js", "specifier": "oxlint-plugin-eslint" }],
"categories": {
"correctness": "off"
@@ -13,14 +13,14 @@
"env": {
"builtin": true
},
- "ignorePatterns": [
- ".next/**",
- "out/**",
- "build/**",
- "next-env.d.ts",
- ".source/**"
- ],
+ "ignorePatterns": [".next/**", "out/**", "build/**", "next-env.d.ts", ".source/**"],
"rules": {
+ "typescript/no-explicit-any": [
+ "error",
+ {
+ "fixToUnknown": true
+ }
+ ],
"nextjs/google-font-display": "warn",
"nextjs/google-font-preconnect": "warn",
"nextjs/next-script-for-ga": "warn",
diff --git a/docs/app/(home)/docs/[[...slug]]/page.tsx b/docs/app/(home)/docs/[[...slug]]/page.tsx
index f79819929..2c7e2a2f8 100644
--- a/docs/app/(home)/docs/[[...slug]]/page.tsx
+++ b/docs/app/(home)/docs/[[...slug]]/page.tsx
@@ -1,9 +1,5 @@
import { getOgImageUrl, source } from '@/lib/source';
-import {
- DocsBody,
- DocsPage,
- DocsTitle,
-} from 'fumadocs-ui/layouts/docs/page';
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
@@ -19,7 +15,7 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
const page = source.getPage(params.slug);
if (!page) notFound();
- const data = page.data as any;
+ const data = page.data;
const MDX = data.body;
const isLanding = !params.slug || params.slug.length === 0;
@@ -67,9 +63,7 @@ export async function generateStaticParams() {
return source.generateParams();
}
-export async function generateMetadata(
- props: PageProps<'/docs/[[...slug]]'>,
-): Promise<Metadata> {
+export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise<Metadata> {
const params = await props.params;
const page = source.getPage(params.slug);
if (!page) notFound();
diff --git a/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
index 5ecc8bace..852e97f34 100644
--- a/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
+++ b/docs/app/(home)/reference/(v31)/[[...slug]]/page.tsx
@@ -1,41 +1,30 @@
import { getReferenceSource, getOgImageUrl } from '@/lib/source';
import { APIPage } from '@/components/api-page';
-import {
- DocsBody,
- DocsPage,
- DocsTitle,
-} from 'fumadocs-ui/layouts/docs/page';
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
import { createRelativeLink } from 'fumadocs-ui/mdx';
-import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
import { PageActions } from '@/components/page-actions';
import { EditOnGitHub } from '@/components/edit-on-github';
import { extractVersionFromPath } from '@/components/version-badge';
import { ApiPageTitle } from '@/components/api-page-title';
import { isApiPageDeprecated } from '@/lib/api-deprecation';
import { sliceApiPageProps } from '@/lib/openapi-slice';
-import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
-
-interface OpenAPIPageData extends OpenApiSchemaPageData {
- title: string;
- description?: string;
- getOpenAPIPageProps: () => OpenAPIPageProps;
-}
+import {
+ openApiReferencePageDataSchema,
+ referenceMdxPageDataSchema,
+} from '@/lib/reference-page-data';
-export default async function Page({
- params,
-}: {
- params: Promise<{ slug?: string[] }>;
-}) {
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
const { slug } = await params;
const referenceSource = await getReferenceSource();
const page = referenceSource.getPage(slug);
if (!page) notFound();
- if ('getOpenAPIPageProps' in page.data) {
- const pageData = page.data as OpenAPIPageData;
+ const openApiData = openApiReferencePageDataSchema.safeParse(page.data);
+ if (openApiData.success) {
+ const pageData = openApiData.data;
const apiProps = pageData.getOpenAPIPageProps();
const detectedVersion = apiProps.operations?.[0]?.path
? extractVersionFromPath(apiProps.operations[0].path)
@@ -44,11 +33,7 @@ export default async function Page({
return (
<DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
<div className="mb-4 flex items-start justify-between gap-4">
- <ApiPageTitle
- title={pageData.title}
- version={detectedVersion}
- deprecated={deprecated}
- />
+ <ApiPageTitle title={pageData.title} version={detectedVersion} deprecated={deprecated} />
<PageActions path={page.url} variant="inline" />
</div>
<DocsBody>
@@ -59,17 +44,22 @@ export default async function Page({
);
}
- const mdxData = page.data as any;
+ const mdxData = referenceMdxPageDataSchema.parse(page.data);
const MDX = mdxData.body;
return (
- <DocsPage toc={mdxData.toc} full={mdxData.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
+ <DocsPage
+ toc={mdxData.toc}
+ full={mdxData.full}
+ footer={{ enabled: false }}
+ tableOfContentPopover={{ enabled: false }}
+ >
<DocsTitle>{mdxData.title}</DocsTitle>
<PageActions path={page.url} />
<DocsBody>
<MDX
components={getMDXComponents({
- a: createRelativeLink(referenceSource as any, page),
+ a: createRelativeLink(referenceSource, page),
})}
/>
<EditOnGitHub path={`docs/content/reference/${page.path}`} />
@@ -82,7 +72,7 @@ export async function generateStaticParams() {
const referenceSource = await getReferenceSource();
const allParams: { slug: string[] }[] = referenceSource.generateParams();
// Exclude v3 pages — those are handled by the /reference/v3/ route
- return allParams.filter((p) => p.slug[0] !== 'v3');
+ return allParams.filter(p => p.slug[0] !== 'v3');
}
export async function generateMetadata({
@@ -93,7 +83,12 @@ export async function generateMetadata({
const { slug } = await params;
if (!slug || slug.length === 0) {
- const ogImage = getOgImageUrl('reference', [], 'API Reference', 'REST API and SDK reference for Composio');
+ const ogImage = getOgImageUrl(
+ 'reference',
+ [],
+ 'API Reference',
+ 'REST API and SDK reference for Composio'
+ );
return {
title: 'API Reference',
description: 'REST API and SDK reference for Composio',
diff --git a/docs/app/(home)/reference/(v31)/layout.tsx b/docs/app/(home)/reference/(v31)/layout.tsx
index b3ba90649..eba3a8560 100644
--- a/docs/app/(home)/reference/(v31)/layout.tsx
+++ b/docs/app/(home)/reference/(v31)/layout.tsx
@@ -9,7 +9,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
const changelogPage = { type: 'page' as const, name: 'Changelog', url: '/reference/changelog' };
// Pin Changelog directly beneath Overview (the first/top entry) in the sidebar.
const overviewIdx = tree.children.findIndex(
- (child: { type: string; name?: string }) => child.type === 'page' && child.name === 'Overview'
+ child => child.type === 'page' && child.name === 'Overview'
);
const insertIdx = overviewIdx === -1 ? Math.min(1, tree.children.length) : overviewIdx + 1;
const pageTree = {
diff --git a/docs/app/(home)/reference/v3/[[...slug]]/page.tsx b/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
index 9a2172e04..07d24f917 100644
--- a/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
+++ b/docs/app/(home)/reference/v3/[[...slug]]/page.tsx
@@ -1,28 +1,20 @@
import { getReferenceSource, getOgImageUrl } from '@/lib/source';
import { APIPage } from '@/components/api-page';
-import {
- DocsBody,
- DocsPage,
- DocsTitle,
-} from 'fumadocs-ui/layouts/docs/page';
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
import { createRelativeLink } from 'fumadocs-ui/mdx';
-import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
import { PageActions } from '@/components/page-actions';
import { EditOnGitHub } from '@/components/edit-on-github';
import { extractVersionFromPath } from '@/components/version-badge';
import { ApiPageTitle } from '@/components/api-page-title';
import { isApiPageDeprecated } from '@/lib/api-deprecation';
import { sliceApiPageProps } from '@/lib/openapi-slice';
-import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
-
-interface OpenAPIPageData extends OpenApiSchemaPageData {
- title: string;
- description?: string;
- getOpenAPIPageProps: () => OpenAPIPageProps;
-}
+import {
+ openApiReferencePageDataSchema,
+ referenceMdxPageDataSchema,
+} from '@/lib/reference-page-data';
/**
* Prepend 'v3' to the slug array since Next.js strips the /v3/ route segment
@@ -32,18 +24,15 @@ function toSourceSlug(slug?: string[]): string[] {
return ['v3', ...(slug || [])];
}
-export default async function Page({
- params,
-}: {
- params: Promise<{ slug?: string[] }>;
-}) {
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
const { slug } = await params;
const referenceSource = await getReferenceSource();
const page = referenceSource.getPage(toSourceSlug(slug));
if (!page) notFound();
- if ('getOpenAPIPageProps' in page.data) {
- const pageData = page.data as OpenAPIPageData;
+ const openApiData = openApiReferencePageDataSchema.safeParse(page.data);
+ if (openApiData.success) {
+ const pageData = openApiData.data;
const apiProps = pageData.getOpenAPIPageProps();
const detectedVersion = apiProps.operations?.[0]?.path
? extractVersionFromPath(apiProps.operations[0].path)
@@ -52,11 +41,7 @@ export default async function Page({
return (
<DocsPage full footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
<div className="mb-4 flex items-start justify-between gap-4">
- <ApiPageTitle
- title={pageData.title}
- version={detectedVersion}
- deprecated={deprecated}
- />
+ <ApiPageTitle title={pageData.title} version={detectedVersion} deprecated={deprecated} />
<PageActions path={page.url} variant="inline" />
</div>
<DocsBody>
@@ -67,17 +52,22 @@ export default async function Page({
);
}
- const mdxData = page.data as any;
+ const mdxData = referenceMdxPageDataSchema.parse(page.data);
const MDX = mdxData.body;
return (
- <DocsPage toc={mdxData.toc} full={mdxData.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
+ <DocsPage
+ toc={mdxData.toc}
+ full={mdxData.full}
+ footer={{ enabled: false }}
+ tableOfContentPopover={{ enabled: false }}
+ >
<DocsTitle>{mdxData.title}</DocsTitle>
<PageActions path={page.url} />
<DocsBody>
<MDX
components={getMDXComponents({
- a: createRelativeLink(referenceSource as any, page),
+ a: createRelativeLink(referenceSource, page),
})}
/>
<EditOnGitHub path={`docs/content/reference/${page.path}`} />
@@ -90,9 +80,7 @@ export async function generateStaticParams() {
const referenceSource = await getReferenceSource();
const allParams: { slug: string[] }[] = referenceSource.generateParams();
// Only return params that start with 'v3', with the prefix stripped
- return allParams
- .filter((p) => p.slug[0] === 'v3')
- .map((p) => ({ slug: p.slug.slice(1) }));
+ return allParams.filter(p => p.slug[0] === 'v3').map(p => ({ slug: p.slug.slice(1) }));
}
export async function generateMetadata({
@@ -104,7 +92,12 @@ export async function generateMetadata({
const sourceSlug = toSourceSlug(slug);
if (!slug || slug.length === 0) {
- const ogImage = getOgImageUrl('reference', [], 'API Reference (v3)', 'REST API reference for Composio v3');
+ const ogImage = getOgImageUrl(
+ 'reference',
+ [],
+ 'API Reference (v3)',
+ 'REST API reference for Composio v3'
+ );
return {
title: 'API Reference (v3)',
description: 'REST API reference for Composio v3',
diff --git a/docs/app/(home)/toolkits/[[...slug]]/page.tsx b/docs/app/(home)/toolkits/[[...slug]]/page.tsx
index e4b66b0d8..c5dced96a 100644
--- a/docs/app/(home)/toolkits/[[...slug]]/page.tsx
+++ b/docs/app/(home)/toolkits/[[...slug]]/page.tsx
@@ -16,14 +16,17 @@ import { toHtml } from 'hast-util-to-html';
import type { Metadata } from 'next';
import type { Tool, Trigger } from '@/types/toolkit';
import type { FaqItem } from '@/components/toolkits/faq-section';
-import { processSchema, toolFromApi } from '@/lib/toolkit-schema';
+import { apiToolListSchema, apiTriggerListSchema } from '@/lib/toolkit-schema';
const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
const API_KEY = process.env.COMPOSIO_API_KEY;
// Fetch detailed tool info from Composio API (server-side only)
// Returns null on failure, empty array if toolkit has no tools
-async function fetchDetailedTools(toolkitSlug: string, version?: string | null): Promise<Tool[] | null> {
+async function fetchDetailedTools(
+ toolkitSlug: string,
+ version?: string | null
+): Promise<Tool[] | null> {
if (!API_KEY) {
console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed tool fetch');
return null;
@@ -46,11 +49,8 @@ async function fetchDetailedTools(toolkitSlug: string, version?: string | null):
return null;
}
- const data = await response.json();
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
-
- return items.filter((tool: any) => tool && typeof tool === 'object').map(toolFromApi);
+ const parsed = apiToolListSchema.safeParse(await response.json());
+ return parsed.success ? parsed.data : [];
} catch (error) {
console.error(`[Toolkits] Error fetching detailed tools for ${toolkitSlug}:`, error);
return null;
@@ -59,7 +59,10 @@ async function fetchDetailedTools(toolkitSlug: string, version?: string | null):
// Fetch detailed trigger info from Composio API (server-side only)
// Returns null on failure, empty array if toolkit has no triggers
-async function fetchDetailedTriggers(toolkitSlug: string, version?: string | null): Promise<Trigger[] | null> {
+async function fetchDetailedTriggers(
+ toolkitSlug: string,
+ version?: string | null
+): Promise<Trigger[] | null> {
if (!API_KEY) {
console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed trigger fetch');
return null;
@@ -82,21 +85,8 @@ async function fetchDetailedTriggers(toolkitSlug: string, version?: string | nul
return null;
}
- const data = await response.json();
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
-
- return items.filter((trigger: any) => trigger && typeof trigger === 'object').map((trigger: any) => {
- return {
- slug: trigger.slug || '',
- name: trigger.name || trigger.display_name || trigger.slug || '',
- description: trigger.description || '',
- type: trigger.type || undefined,
- config: processSchema(trigger.config),
- payload: processSchema(trigger.payload),
- instructions: trigger.instructions || undefined,
- };
- });
+ const parsed = apiTriggerListSchema.safeParse(await response.json());
+ return parsed.success ? parsed.data : [];
} catch (error) {
console.error(`[Toolkits] Error fetching detailed triggers for ${toolkitSlug}:`, error);
return null;
@@ -141,19 +131,28 @@ export async function generateStaticParams() {
// JSON toolkit pages
const toolkits = await getAllToolkits();
- const jsonParams = toolkits.map((toolkit) => ({
+ const jsonParams = toolkits.map(toolkit => ({
slug: [toolkit.slug],
}));
return [indexParam, ...mdxParams, ...jsonParams];
}
-export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }): Promise<Metadata> {
+export async function generateMetadata({
+ params,
+}: {
+ params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> {
const { slug } = await params;
// Index page
if (!slug || slug.length === 0) {
- const ogImage = getOgImageUrl('toolkits', [], 'Toolkits', 'Browse all toolkits supported by Composio');
+ const ogImage = getOgImageUrl(
+ 'toolkits',
+ [],
+ 'Toolkits',
+ 'Browse all toolkits supported by Composio'
+ );
return {
title: 'Toolkits',
description: 'Browse all toolkits supported by Composio',
@@ -210,7 +209,12 @@ export default async function ToolkitsPage({ params }: { params: Promise<{ slug?
const MDXContent = page.data.body;
return (
<div>
- <Link href="/toolkits" className="text-sm text-fd-muted-foreground no-underline hover:text-fd-foreground hover:underline">← All Toolkits</Link>
+ <Link
+ href="/toolkits"
+ className="text-sm text-fd-muted-foreground no-underline hover:text-fd-foreground hover:underline"
+ >
+ ← All Toolkits
+ </Link>
<div className="mt-2 flex items-start justify-between gap-4">
<h1 className="text-3xl font-bold text-fd-foreground">{page.data.title}</h1>
<PageActions path={page.url} variant="inline" />
diff --git a/docs/app/llms-full.txt/route.ts b/docs/app/llms-full.txt/route.ts
index 1b484772d..d42a6adae 100644
--- a/docs/app/llms-full.txt/route.ts
+++ b/docs/app/llms-full.txt/route.ts
@@ -1,4 +1,11 @@
-import { getLLMText, source, examplesSource, referenceSource, toolkitsSource } from '@/lib/source';
+import {
+ getLLMText,
+ source,
+ examplesSource,
+ referenceSource,
+ toolkitsSource,
+ type LLMPage,
+} from '@/lib/source';
import { SESSION_GUARDRAILS } from '@/lib/llm-guardrails';
import type { ReactNode } from 'react';
@@ -26,14 +33,7 @@ interface FolderNode {
type TreeNode = PageNode | SeparatorNode | FolderNode;
// Generic page type that works for all sources
-interface PageLike {
- url: string;
- slugs: string[];
- data: {
- title: string;
- description?: string;
- };
-}
+type PageLike = LLMPage & { slugs: string[] };
/**
* Collect page URLs from the page tree in sidebar order.
@@ -115,9 +115,12 @@ function orderDocPages(pages: PageLike[], treeNodes: TreeNode[]): PageLike[] {
async function getTextForPages(pages: PageLike[]) {
return Promise.all(
- pages.map(async (page) => {
+ pages.map(async page => {
try {
- return await getLLMText(page as any, { includeFooter: false, includeGuardrails: false });
+ return await getLLMText(page, {
+ includeFooter: false,
+ includeGuardrails: false,
+ });
} catch {
// Graceful fallback if getText fails
return `# ${page.data.title} (${page.url})\n\n${page.data.description || ''}`;
@@ -131,15 +134,15 @@ export async function GET() {
const treeChildren = source.pageTree.children as TreeNode[];
const legacyUrls = collectLegacyUrls(treeChildren);
const orderedDocsPages = orderDocPages(
- (source.getPages() as PageLike[]).filter((page) => !legacyUrls.has(page.url)),
+ source.getPages().filter(page => !legacyUrls.has(page.url)),
treeChildren
);
const [docsResults, examplesResults, referenceResults, toolkitsResults] = await Promise.all([
getTextForPages(orderedDocsPages),
- getTextForPages(examplesSource.getPages() as PageLike[]),
- getTextForPages(referenceSource.getPages() as PageLike[]),
- getTextForPages(toolkitsSource.getPages() as PageLike[]),
+ getTextForPages(examplesSource.getPages()),
+ getTextForPages(referenceSource.getPages()),
+ getTextForPages(toolkitsSource.getPages()),
]);
const results = [
diff --git a/docs/app/llms.mdx/[[...slug]]/route.ts b/docs/app/llms.mdx/[[...slug]]/route.ts
index 84c0c64c3..3a0b45241 100644
--- a/docs/app/llms.mdx/[[...slug]]/route.ts
+++ b/docs/app/llms.mdx/[[...slug]]/route.ts
@@ -8,6 +8,7 @@ import {
formatDate,
getLLMText,
mdxToCleanMarkdown,
+ type LLMPage,
} from '@/lib/source';
import { dereferenceDocument } from '@/lib/openapi-deref';
import { notFound } from 'next/navigation';
@@ -17,7 +18,8 @@ import { getAllToolkits, getToolkitBySlug } from '@/lib/toolkit-data';
import { getAllMetaTools, getMetaToolBySlug } from '@/lib/meta-tools-data';
import type { MetaTool, MetaToolParameter } from '@/lib/meta-tools-data';
import type { Toolkit, Tool, Trigger, ParameterSchema } from '@/types/toolkit';
-import { processSchema, toolFromApi } from '@/lib/toolkit-schema';
+import { apiToolListSchema, apiTriggerListSchema } from '@/lib/toolkit-schema';
+import { z } from 'zod';
export const revalidate = false;
@@ -48,20 +50,19 @@ async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
return null;
}
- const data = await response.json();
- if (!data || typeof data !== 'object') {
+ const parsed = apiToolListSchema.safeParse(await response.json());
+ if (!parsed.success) {
console.warn(`[LLM Markdown] Invalid API response format for toolkit ${toolkitSlug}`);
return null;
}
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
-
- if (items.length >= API_FETCH_LIMIT) {
- console.warn(`[LLM Markdown] Toolkit ${toolkitSlug} has ${items.length}+ tools, results may be truncated`);
+ if (parsed.data.length >= API_FETCH_LIMIT) {
+ console.warn(
+ `[LLM Markdown] Toolkit ${toolkitSlug} has ${parsed.data.length}+ tools, results may be truncated`
+ );
}
- return items.filter((tool: any) => tool && typeof tool === 'object').map(toolFromApi);
+ return parsed.data;
} catch {
return null;
}
@@ -86,32 +87,25 @@ async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | n
);
if (!response.ok) {
- console.warn(`[LLM Markdown] Failed to fetch triggers for ${toolkitSlug}: ${response.status}`);
+ console.warn(
+ `[LLM Markdown] Failed to fetch triggers for ${toolkitSlug}: ${response.status}`
+ );
return null;
}
- const data = await response.json();
- if (!data || typeof data !== 'object') {
+ const parsed = apiTriggerListSchema.safeParse(await response.json());
+ if (!parsed.success) {
console.warn(`[LLM Markdown] Invalid API response format for triggers ${toolkitSlug}`);
return null;
}
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
-
- if (items.length >= API_FETCH_LIMIT) {
- console.warn(`[LLM Markdown] Toolkit ${toolkitSlug} has ${items.length}+ triggers, results may be truncated`);
+ if (parsed.data.length >= API_FETCH_LIMIT) {
+ console.warn(
+ `[LLM Markdown] Toolkit ${toolkitSlug} has ${parsed.data.length}+ triggers, results may be truncated`
+ );
}
- return items.filter((trigger: any) => trigger && typeof trigger === 'object').map((trigger: any) => ({
- slug: trigger.slug || '',
- name: trigger.name || trigger.display_name || trigger.slug || '',
- description: trigger.description || '',
- type: trigger.type,
- config: processSchema(trigger.config),
- payload: processSchema(trigger.payload),
- instructions: trigger.instructions,
- }));
+ return parsed.data;
} catch {
return null;
}
@@ -188,6 +182,54 @@ interface OpenAPIPageData {
};
}
+// Fumadocs page data is untyped across the mixed sources this route serves, so
+// each candidate page is parsed once against the shape its renderer needs.
+const openAPIPageSchema = z.object({
+ url: z.string(),
+ data: z.object({
+ title: z.string(),
+ description: z.string().optional().catch(undefined),
+ getOpenAPIPageProps: z.custom<OpenAPIPageData['getOpenAPIPageProps']>(
+ value => typeof value === 'function'
+ ),
+ }),
+});
+
+const llmPageSchema: z.ZodType<LLMPage> = z.object({
+ url: z.string(),
+ data: z.object({
+ title: z.string(),
+ description: z.string().optional().catch(undefined),
+ getText: z
+ .custom<NonNullable<LLMPage['data']['getText']>>(value => typeof value === 'function')
+ .optional()
+ .catch(undefined),
+ legacy: z.boolean().optional().catch(undefined),
+ written: z.string().optional().catch(undefined),
+ llmGuardrails: z.enum(['direct-execution', 'none']).optional().catch(undefined),
+ }),
+});
+
+const degradedPageSchema = z.object({
+ url: z.unknown().optional(),
+ data: z
+ .object({
+ title: z.unknown().optional(),
+ description: z.unknown().optional(),
+ })
+ .catch({}),
+});
+
+export function degradedPageToMarkdown(value: unknown): string | null {
+ const parsed = degradedPageSchema.safeParse(value);
+ if (!parsed.success) return null;
+
+ const title = parsed.data.data.title || 'Documentation';
+ const description = parsed.data.data.description || '';
+ const url = parsed.data.url || '';
+ return `# ${String(title)} (${String(url)})\n\n${String(description)}`;
+}
+
// Generate sample value for a schema
function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
if (depth > 3) return '...'; // Prevent infinite recursion
@@ -242,12 +284,7 @@ function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
* tracks recursion because `allOf` expands without increasing indentation. An
* ellipsis is emitted when either value exceeds `maxDepth`.
*/
-function renderSchema(
- schema: OpenAPISchema,
- indent = 0,
- maxDepth = 4,
- depth = 0
-): string[] {
+function renderSchema(schema: OpenAPISchema, indent = 0, maxDepth = 4, depth = 0): string[] {
if (indent > maxDepth || depth > maxDepth) {
return [' '.repeat(indent) + '- ...'];
}
@@ -256,7 +293,11 @@ function renderSchema(
const prefix = ' '.repeat(indent);
const required = schema.required || [];
- if (schema.type === 'object' && (schema.properties || (schema.additionalProperties && typeof schema.additionalProperties === 'object'))) {
+ if (
+ schema.type === 'object' &&
+ (schema.properties ||
+ (schema.additionalProperties && typeof schema.additionalProperties === 'object'))
+ ) {
if (schema.properties) {
for (const [name, prop] of Object.entries(schema.properties)) {
const isRequired = required.includes(name);
@@ -267,9 +308,19 @@ function renderSchema(
lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}`);
// Recurse for nested objects/arrays
- if (prop.type === 'object' && (prop.properties || (prop.additionalProperties && typeof prop.additionalProperties === 'object'))) {
+ if (
+ prop.type === 'object' &&
+ (prop.properties ||
+ (prop.additionalProperties && typeof prop.additionalProperties === 'object'))
+ ) {
lines.push(...renderSchema(prop, indent + 1, maxDepth, depth + 1));
- } else if (prop.type === 'array' && prop.items?.type === 'object' && (prop.items.properties || (prop.items.additionalProperties && typeof prop.items.additionalProperties === 'object'))) {
+ } else if (
+ prop.type === 'array' &&
+ prop.items?.type === 'object' &&
+ (prop.items.properties ||
+ (prop.items.additionalProperties &&
+ typeof prop.items.additionalProperties === 'object'))
+ ) {
lines.push(`${prefix} - Array items:`);
lines.push(...renderSchema(prop.items, indent + 2, maxDepth, depth + 1));
}
@@ -282,9 +333,17 @@ function renderSchema(
const typeStr = getTypeString(ap);
const desc = ap.description ? `: ${ap.description}` : '';
lines.push(`${prefix}- \`[key: string]\` (${typeStr})${desc}`);
- if (ap.type === 'object' && (ap.properties || (ap.additionalProperties && typeof ap.additionalProperties === 'object'))) {
+ if (
+ ap.type === 'object' &&
+ (ap.properties || (ap.additionalProperties && typeof ap.additionalProperties === 'object'))
+ ) {
lines.push(...renderSchema(ap, indent + 1, maxDepth, depth + 1));
- } else if (ap.type === 'array' && ap.items?.type === 'object' && (ap.items.properties || (ap.items.additionalProperties && typeof ap.items.additionalProperties === 'object'))) {
+ } else if (
+ ap.type === 'array' &&
+ ap.items?.type === 'object' &&
+ (ap.items.properties ||
+ (ap.items.additionalProperties && typeof ap.items.additionalProperties === 'object'))
+ ) {
lines.push(`${prefix} - Array items:`);
lines.push(...renderSchema(ap.items, indent + 2, maxDepth, depth + 1));
}
@@ -318,7 +377,10 @@ function getTypeString(schema: OpenAPISchema, depth = 0, maxDepth = 4): string {
if (depth > maxDepth) return '...';
if (schema.enum) {
- return `enum: ${schema.enum.slice(0, 3).map(e => `"${e}"`).join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;
+ return `enum: ${schema.enum
+ .slice(0, 3)
+ .map(e => `"${e}"`)
+ .join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;
}
if (schema.type === 'array' && schema.items) {
return `array<${getTypeString(schema.items, depth + 1, maxDepth)}>`;
@@ -370,9 +432,10 @@ function generateCurl(
}
// Convert OpenAPI page to comprehensive markdown
-export async function openapiPageToMarkdown(
- page: { url: string; data: OpenAPIPageData }
-): Promise<string> {
+export async function openapiPageToMarkdown(page: {
+ url: string;
+ data: OpenAPIPageData;
+}): Promise<string> {
const { title, description } = page.data;
const props = page.data.getOpenAPIPageProps();
@@ -380,7 +443,8 @@ export async function openapiPageToMarkdown(
const spec = dereferenceDocument(props.payload.bundled);
const paths = spec.paths as Record<string, Record<string, OpenAPIOperation>> | undefined;
const webhooks = spec.webhooks as Record<string, Record<string, OpenAPIOperation>> | undefined;
- const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as Record<string, OpenAPISecurityScheme> | undefined;
+ const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as
+ Record<string, OpenAPISecurityScheme> | undefined;
const servers = spec.servers as Array<{ url: string; description?: string }> | undefined;
const baseUrl = servers?.[0]?.url || 'https://backend.composio.dev';
@@ -564,7 +628,11 @@ export async function openapiPageToMarkdown(
// Map URL prefixes to their sources
// Note: 'reference' is handled specially below with async getReferenceSource()
-const sources = [
+interface PageSource {
+ getPage(slugs: string[] | undefined): unknown;
+}
+
+const sources: Array<{ prefix: string; source: PageSource }> = [
{ prefix: 'docs', source },
{ prefix: 'examples', source: examplesSource },
{ prefix: 'toolkits', source: toolkitsSource },
@@ -615,9 +683,7 @@ function generateChangelogIndex(): string {
* Multiple entries on the same date are combined into one document.
*/
async function changelogToMarkdown(dateStr: string): Promise<string | null> {
- const matchingEntries = changelogEntries.filter(
- (entry) => entry.date === dateStr
- );
+ const matchingEntries = changelogEntries.filter(entry => entry.date === dateStr);
if (matchingEntries.length === 0) {
return null;
@@ -701,7 +767,12 @@ async function readToolkitFaqMarkdown(slug: string): Promise<string | null> {
}
// Generate markdown from toolkit with detailed tools and triggers
-function toolkitToMarkdown(toolkit: Toolkit, detailedTools?: Tool[], detailedTriggers?: Trigger[], faqMarkdown?: string | null): string {
+function toolkitToMarkdown(
+ toolkit: Toolkit,
+ detailedTools?: Tool[],
+ detailedTriggers?: Trigger[],
+ faqMarkdown?: string | null
+): string {
const tools = detailedTools || toolkit.tools;
const triggers = detailedTriggers || toolkit.triggers;
@@ -713,10 +784,10 @@ function toolkitToMarkdown(toolkit: Toolkit, detailedTools?: Tool[], detailedTri
`- **Category:** ${toolkit.category || 'Uncategorized'}`,
`- **Auth:** ${toolkit.authSchemes.join(', ') || 'None'}`,
`- **Composio Managed App Available?** ${
- toolkit.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'))
- ? (toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
- ? 'Yes'
- : 'No')
+ toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
+ ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
+ ? 'Yes'
+ : 'No'
: 'N/A'
}`,
`- **Tools:** ${toolkit.toolCount}`,
@@ -794,16 +865,16 @@ async function generateManagedAuthIndex(): Promise<string> {
const toolkits = await getAllToolkits();
// Only include OAuth toolkits
- const oauthToolkits = toolkits.filter((t) =>
- t.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'))
+ const oauthToolkits = toolkits.filter(t =>
+ t.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
);
const managed = oauthToolkits
- .filter((t) => t.composioManagedAuthSchemes && t.composioManagedAuthSchemes.length > 0)
+ .filter(t => t.composioManagedAuthSchemes && t.composioManagedAuthSchemes.length > 0)
.sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
const unmanaged = oauthToolkits
- .filter((t) => !t.composioManagedAuthSchemes || t.composioManagedAuthSchemes.length === 0)
+ .filter(t => !t.composioManagedAuthSchemes || t.composioManagedAuthSchemes.length === 0)
.sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
const lines: string[] = [
@@ -827,7 +898,9 @@ async function generateManagedAuthIndex(): Promise<string> {
];
for (const t of managed) {
- lines.push(`| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`);
+ lines.push(
+ `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
+ );
}
lines.push('');
@@ -837,7 +910,9 @@ async function generateManagedAuthIndex(): Promise<string> {
lines.push('|---------|------|');
for (const t of unmanaged) {
- lines.push(`| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`);
+ lines.push(
+ `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
+ );
}
return lines.join('\n');
@@ -869,9 +944,11 @@ async function generateToolkitsIndex(): Promise<string> {
for (const toolkit of sorted) {
const name = toolkit.name?.trim() || toolkit.slug;
const auth = toolkit.authSchemes?.join(', ') || 'None';
- const hasOAuth = toolkit.authSchemes?.some((s) => s.toUpperCase().includes('OAUTH'));
+ const hasOAuth = toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'));
const managedApp = hasOAuth
- ? (toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0 ? 'Yes' : 'No')
+ ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
+ ? 'Yes'
+ : 'No'
: '—';
lines.push(
`| [${name}](/toolkits/${toolkit.slug}.md) | \`${toolkit.slug.toUpperCase()}\` | ${toolkit.toolCount} | ${toolkit.triggerCount} | ${auth} | ${managedApp} |`
@@ -879,32 +956,45 @@ async function generateToolkitsIndex(): Promise<string> {
}
lines.push('', '## Toolkit Details', '');
- lines.push('For detailed information about each toolkit including all tools and triggers, visit the individual toolkit pages listed above.');
+ lines.push(
+ 'For detailed information about each toolkit including all tools and triggers, visit the individual toolkit pages listed above.'
+ );
return lines.join('\n');
}
-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)';
+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)';
// Render meta tool parameters as markdown
-function renderMetaToolParams(properties: Record<string, MetaToolParameter>, requiredFields: string[] = [], indent = 0): string[] {
+function renderMetaToolParams(
+ properties: Record<string, MetaToolParameter>,
+ requiredFields: string[] = [],
+ indent = 0
+): string[] {
const lines: string[] = [];
const prefix = ' '.repeat(indent);
for (const [name, param] of Object.entries(properties)) {
- const typeStr = param.type === 'array' && param.items && typeof param.items === 'object' && (param.items as Record<string, unknown>).type
- ? `array<${(param.items as Record<string, unknown>).type}>`
- : param.type;
+ const typeStr =
+ param.type === 'array' &&
+ param.items &&
+ typeof param.items === 'object' &&
+ (param.items as Record<string, unknown>).type
+ ? `array<${(param.items as Record<string, unknown>).type}>`
+ : param.type;
const reqMark = requiredFields.includes(name) ? ' *(required)*' : '';
const desc = param.description
? `: ${param.description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim()}`
: '';
- const defaultStr = param.default !== undefined && param.default !== null && param.default !== ''
- ? ` (default: \`${String(param.default)}\`)`
- : '';
- const enumStr = param.enum && param.enum.length > 0
- ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
- : '';
+ const defaultStr =
+ param.default !== undefined && param.default !== null && param.default !== ''
+ ? ` (default: \`${String(param.default)}\`)`
+ : '';
+ const enumStr =
+ param.enum && param.enum.length > 0
+ ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
+ : '';
lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}${defaultStr}${enumStr}`);
@@ -913,11 +1003,24 @@ function renderMetaToolParams(properties: Record<string, MetaToolParameter>, req
lines.push(...renderMetaToolParams(param.properties, nestedRequired, indent + 1));
}
- const items = param.items && typeof param.items === 'object' ? param.items as Record<string, unknown> : null;
- if (items?.properties && typeof items.properties === 'object' && Object.keys(items.properties as object).length > 0) {
- const itemsRequired = Array.isArray(items.required) ? items.required as string[] : [];
+ const items =
+ param.items && typeof param.items === 'object'
+ ? (param.items as Record<string, unknown>)
+ : null;
+ if (
+ items?.properties &&
+ typeof items.properties === 'object' &&
+ Object.keys(items.properties as object).length > 0
+ ) {
+ const itemsRequired = Array.isArray(items.required) ? (items.required as string[]) : [];
lines.push(`${prefix} - Array items:`);
- lines.push(...renderMetaToolParams(items.properties as Record<string, MetaToolParameter>, itemsRequired, indent + 2));
+ lines.push(
+ ...renderMetaToolParams(
+ items.properties as Record<string, MetaToolParameter>,
+ itemsRequired,
+ indent + 2
+ )
+ );
}
}
@@ -926,11 +1029,7 @@ function renderMetaToolParams(properties: Record<string, MetaToolParameter>, req
// Generate markdown for a single meta tool
function metaToolToMarkdown(tool: MetaTool): string {
- const lines: string[] = [
- `# ${tool.displayName}`,
- '',
- `**Slug:** \`${tool.slug}\``,
- ];
+ const lines: string[] = [`# ${tool.displayName}`, '', `**Slug:** \`${tool.slug}\``];
if (tool.tags.length > 0) {
lines.push(`**Tags:** ${tool.tags.join(', ')}`);
@@ -968,16 +1067,15 @@ function metaToolsIndexToMarkdown(tools: MetaTool[]): string {
for (const tool of tools) {
const tags = tool.tags.length > 0 ? tool.tags.join(', ') : '—';
- lines.push(`| [\`${tool.slug}\`](/toolkits/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`);
+ lines.push(
+ `| [\`${tool.slug}\`](/toolkits/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`
+ );
}
return lines.join('\n') + LLM_FOOTER;
}
-export async function GET(
- _req: Request,
- { params }: { params: Promise<{ slug?: string[] }> }
-) {
+export async function GET(_req: Request, { params }: { params: Promise<{ slug?: string[] }> }) {
try {
const { slug = [] } = await params;
const [prefix, ...rest] = slug;
@@ -1058,7 +1156,7 @@ export async function GET(
}
// Handle 'reference' specially - uses async getReferenceSource() for OpenAPI pages
- let pageSource: any;
+ let pageSource: PageSource;
if (prefix === 'reference') {
try {
pageSource = await getReferenceSource();
@@ -1069,7 +1167,7 @@ export async function GET(
pageSource = referenceSource;
}
} else {
- const match = sources.find((s) => s.prefix === prefix);
+ const match = sources.find(s => s.prefix === prefix);
if (!match) notFound();
pageSource = match.source;
}
@@ -1085,11 +1183,10 @@ export async function GET(
if (page) {
// Check if this is an OpenAPI page
- if ('getOpenAPIPageProps' in page.data) {
+ const openapiPage = openAPIPageSchema.safeParse(page);
+ if (openapiPage.success) {
try {
- const markdown = await openapiPageToMarkdown(
- page as unknown as { url: string; data: OpenAPIPageData }
- );
+ const markdown = await openapiPageToMarkdown(openapiPage.data);
return new Response(markdown, {
headers: {
'Content-Type': 'text/markdown; charset=utf-8',
@@ -1097,38 +1194,44 @@ export async function GET(
});
} catch (e) {
console.error('Error generating OpenAPI markdown:', e);
- const title = page.data?.title || 'API Reference';
- const description = page.data?.description || '';
- return new Response(
- `# ${title}\n\n${description}`,
- {
- headers: {
- 'Content-Type': 'text/markdown; charset=utf-8',
- },
- }
- );
+ const title = openapiPage.data.data.title || 'API Reference';
+ const description = openapiPage.data.data.description || '';
+ return new Response(`# ${title}\n\n${description}`, {
+ headers: {
+ 'Content-Type': 'text/markdown; charset=utf-8',
+ },
+ });
}
}
// Regular MDX page
- try {
- return new Response(await getLLMText(page as any), {
+ const llmPage = llmPageSchema.safeParse(page);
+ if (llmPage.success) {
+ try {
+ return new Response(await getLLMText(llmPage.data), {
+ headers: {
+ 'Content-Type': 'text/markdown; charset=utf-8',
+ },
+ });
+ } catch (e) {
+ console.error('Error generating LLM text:', e);
+ const title = llmPage.data.data.title || 'Documentation';
+ const description = llmPage.data.data.description || '';
+ return new Response(`# ${title} (${llmPage.data.url})\n\n${description}`, {
+ headers: {
+ 'Content-Type': 'text/markdown; charset=utf-8',
+ },
+ });
+ }
+ }
+
+ const degradedMarkdown = degradedPageToMarkdown(page);
+ if (degradedMarkdown !== null) {
+ return new Response(degradedMarkdown, {
headers: {
'Content-Type': 'text/markdown; charset=utf-8',
},
});
- } catch (e) {
- console.error('Error generating LLM text:', e);
- const title = page.data?.title || 'Documentation';
- const description = page.data?.description || '';
- return new Response(
- `# ${title} (${page.url || ''})\n\n${description}`,
- {
- headers: {
- 'Content-Type': 'text/markdown; charset=utf-8',
- },
- }
- );
}
}
@@ -1166,14 +1269,11 @@ export async function GET(
throw e;
}
console.error('Unexpected error in llms.mdx route:', e);
- return new Response(
- `# Error\n\nAn error occurred while generating the markdown content.`,
- {
- status: 500,
- headers: {
- 'Content-Type': 'text/markdown; charset=utf-8',
- },
- }
- );
+ return new Response(`# Error\n\nAn error occurred while generating the markdown content.`, {
+ status: 500,
+ headers: {
+ 'Content-Type': 'text/markdown; charset=utf-8',
+ },
+ });
}
}
diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.ts
index d34f88429..5c4466965 100644
--- a/docs/app/llms.txt/route.ts
+++ b/docs/app/llms.txt/route.ts
@@ -89,10 +89,13 @@ function walkPageTree(nodes: TreeNode[], depth = 2): string {
}
}
- return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+ return lines
+ .join('\n')
+ .replace(/\n{3,}/g, '\n\n')
+ .trim();
}
-function formatPage(page: any) {
+function formatPage(page: { url: string }) {
return `- https://docs.composio.dev${page.url}.md`;
}
diff --git a/docs/components/file-buildup.tsx b/docs/components/file-buildup.tsx
index b85b9af1d..77b092710 100644
--- a/docs/components/file-buildup.tsx
+++ b/docs/components/file-buildup.tsx
@@ -1,6 +1,7 @@
import { createPatch } from 'diff';
import { getSingularPatch } from '@pierre/diffs';
import { preloadFileDiff } from '@pierre/diffs/ssr';
+import type { FileDiffProps } from '@pierre/diffs/react';
import { DiffView, HIDE_DIFF_STATS_CSS } from './diff-view';
import { FILE_BUILDS } from '@/lib/file-builds';
@@ -27,7 +28,7 @@ function StepCard({
file: string;
description?: string;
- fileDiff: any;
+ fileDiff: FileDiffProps<undefined>['fileDiff'];
prerenderedHTML: string;
code: string;
}) {
diff --git a/docs/components/landing-hero/logo-bar.tsx b/docs/components/landing-hero/logo-bar.tsx
index 38c397493..00613185f 100644
--- a/docs/components/landing-hero/logo-bar.tsx
+++ b/docs/components/landing-hero/logo-bar.tsx
@@ -1,17 +1,23 @@
-"use client";
+'use client';
-import Image from "next/image";
-import { useIsMobile } from "./use-is-mobile";
-import { LogoLoop } from "./logo-loop";
+import Image from 'next/image';
+import { useIsMobile } from './use-is-mobile';
+import { LogoLoop } from './logo-loop';
-const LOGOS = [
- { src: "/clients/logo-agentai.svg", alt: "agent.ai", h: 34 },
- { src: "/clients/logo-context.svg", alt: "Context", h: 30 },
- { src: "/clients/logo-zoom.png", alt: "Zoom", h: 25 },
- { src: "/clients/logo-letta.svg", alt: "Letta", h: 27 },
- { src: "/clients/logo-glean.svg", alt: "Glean", h: 34 },
- { src: "/clients/logo-hubspot.svg", alt: "HubSpot", h: 34 },
- { src: "/clients/logo-wabi.svg", alt: "Wabi", h: 27 },
+interface ClientLogo {
+ src: string;
+ alt: string;
+ h: number;
+}
+
+const LOGOS: ClientLogo[] = [
+ { src: '/clients/logo-agentai.svg', alt: 'agent.ai', h: 34 },
+ { src: '/clients/logo-context.svg', alt: 'Context', h: 30 },
+ { src: '/clients/logo-zoom.png', alt: 'Zoom', h: 25 },
+ { src: '/clients/logo-letta.svg', alt: 'Letta', h: 27 },
+ { src: '/clients/logo-glean.svg', alt: 'Glean', h: 34 },
+ { src: '/clients/logo-hubspot.svg', alt: 'HubSpot', h: 34 },
+ { src: '/clients/logo-wabi.svg', alt: 'Wabi', h: 27 },
];
const MOBILE_SCALE = 0.75;
@@ -25,9 +31,9 @@ export function LogoBar() {
className="w-full max-w-[800px] overflow-hidden px-4 py-[14px] grayscale"
style={{
maskImage:
- "linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)",
+ 'linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)',
WebkitMaskImage:
- "linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)",
+ 'linear-gradient(to right, transparent 0%, black 30%, black 70%, transparent 100%)',
}}
>
<LogoLoop
@@ -35,18 +41,17 @@ export function LogoBar() {
gap={isMobile ? 40 : 64}
logoHeight={isMobile ? 18 : 26}
logos={LOGOS}
- renderItem={(item: any) => {
- const logo = item as { src: string; alt: string; h: number };
- const h = isMobile ? logo.h * MOBILE_SCALE : logo.h;
+ renderItem={item => {
+ const h = isMobile ? item.h * MOBILE_SCALE : item.h;
return (
<Image
- alt={logo.alt}
+ alt={item.alt}
draggable={false}
height={Math.ceil(h)}
- src={logo.src}
+ src={item.src}
style={{
height: h,
- width: "auto",
+ width: 'auto',
}}
width={Math.ceil(h * 3)}
/>
diff --git a/docs/components/landing-hero/logo-loop/index.d.ts b/docs/components/landing-hero/logo-loop/index.d.ts
index 188a73f61..77423734e 100644
--- a/docs/components/landing-hero/logo-loop/index.d.ts
+++ b/docs/components/landing-hero/logo-loop/index.d.ts
@@ -20,8 +20,8 @@ interface LogoNodeItem {
type LogoItem = LogoImageItem | LogoNodeItem;
-interface LogoLoopProps {
- logos: LogoItem[];
+interface LogoLoopProps<Item extends LogoItem = LogoItem> {
+ logos: Item[];
speed?: number;
direction?: "left" | "right" | "up" | "down";
width?: string | number;
@@ -32,11 +32,13 @@ interface LogoLoopProps {
fadeOut?: boolean;
fadeOutColor?: string;
scaleOnHover?: boolean;
- renderItem?: (item: LogoItem, key: string) => ReactNode;
+ renderItem?: (item: Item, key: string) => ReactNode;
ariaLabel?: string;
className?: string;
style?: CSSProperties;
}
-export const LogoLoop: React.MemoExoticComponent<React.FC<LogoLoopProps>>;
+export const LogoLoop: <Item extends LogoItem = LogoItem>(
+ props: LogoLoopProps<Item>
+) => ReactNode;
export default LogoLoop;
diff --git a/docs/lib/create-docs-layout.tsx b/docs/lib/create-docs-layout.tsx
index 3fba2c715..a81d50ea1 100644
--- a/docs/lib/create-docs-layout.tsx
+++ b/docs/lib/create-docs-layout.tsx
@@ -1,7 +1,7 @@
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';
-type Source = any;
+type Source = typeof import('./source').examplesSource;
export function createDocsLayout(source: Source) {
return function Layout({ children }: { children: ReactNode }) {
diff --git a/docs/lib/create-docs-page.tsx b/docs/lib/create-docs-page.tsx
index 65d7c12f2..d0045cf09 100644
--- a/docs/lib/create-docs-page.tsx
+++ b/docs/lib/create-docs-page.tsx
@@ -1,8 +1,4 @@
-import {
- DocsBody,
- DocsPage,
- DocsTitle,
-} from 'fumadocs-ui/layouts/docs/page';
+import { DocsBody, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { notFound } from 'next/navigation';
import { getMDXComponents } from '@/mdx-components';
import type { Metadata } from 'next';
@@ -11,7 +7,7 @@ import { PageActions } from '@/components/page-actions';
import { EditOnGitHub } from '@/components/edit-on-github';
import { getOgImageUrl } from '@/lib/source';
-type Source = any;
+type Source = typeof import('./source').examplesSource;
export function createDocsPage(source: Source, contentDir: string = 'content/docs') {
return async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
@@ -22,7 +18,12 @@ export function createDocsPage(source: Source, contentDir: string = 'content/doc
const MDX = page.data.body;
return (
- <DocsPage toc={page.data.toc} full={page.data.full} footer={{ enabled: false }} tableOfContentPopover={{ enabled: false }}>
+ <DocsPage
+ toc={page.data.toc}
+ full={page.data.full}
+ footer={{ enabled: false }}
+ tableOfContentPopover={{ enabled: false }}
+ >
<DocsTitle>{page.data.title}</DocsTitle>
<PageActions path={page.url} />
<DocsBody>
diff --git a/docs/lib/deprecated-api-sidebar.tsx b/docs/lib/deprecated-api-sidebar.tsx
index 87305d6aa..7d025197f 100644
--- a/docs/lib/deprecated-api-sidebar.tsx
+++ b/docs/lib/deprecated-api-sidebar.tsx
@@ -1,27 +1,21 @@
import type { ReactNode } from 'react';
import type { Item } from 'fumadocs-core/page-tree';
-import type { PageTreeTransformer } from 'fumadocs-core/source';
+import type { ContentStorage } from 'fumadocs-core/source';
+import { z } from 'zod';
import { DeprecatedApiSidebarLegacyBadge } from '@/components/legacy-badge';
import { getApiDisplayTitle, isApiPageDeprecated } from '@/lib/api-deprecation';
import type { ApiPageOperation, OpenApiSchemaPageData } from '@/lib/api-deprecation';
-interface OpenApiSidebarPageData extends OpenApiSchemaPageData {
- title: string;
- getOpenAPIPageProps: () => {
- operations?: ApiPageOperation[];
- };
-}
-
-function isOpenApiSidebarPageData(data: unknown): data is OpenApiSidebarPageData {
- if (!data || typeof data !== 'object') return false;
-
- const candidate = data as Partial<OpenApiSidebarPageData>;
- return (
- typeof candidate.title === 'string' &&
- typeof candidate.getSchema === 'function' &&
- typeof candidate.getOpenAPIPageProps === 'function'
- );
-}
+// Page data attached by fumadocs-openapi to generated operation pages. MDX
+// pages in the same tree lack these members, so the data is parsed once here
+// and non-OpenAPI pages simply fail the parse.
+const openApiSidebarPageDataSchema = z.object({
+ title: z.string(),
+ getSchema: z.custom<OpenApiSchemaPageData['getSchema']>(value => typeof value === 'function'),
+ getOpenAPIPageProps: z.custom<() => { operations?: ApiPageOperation[] }>(
+ value => typeof value === 'function'
+ ),
+});
export function getDeprecatedApiSidebarName(
title: string,
@@ -41,19 +35,22 @@ export function getDeprecatedApiSidebarName(
* Replaces a deprecated OpenAPI operation's textual title suffix with a
* compact lifecycle badge before fumadocs-openapi appends its method label.
*/
-export const deprecatedApiSidebarTransformer: PageTreeTransformer = {
- file(node: Item, filePath?: string): Item {
- if (!filePath) return node;
-
- const file = this.storage.read(filePath);
- if (!file || file.format !== 'page' || !isOpenApiSidebarPageData(file.data)) {
- return node;
- }
-
- const apiProps = file.data.getOpenAPIPageProps();
- return {
- ...node,
- name: getDeprecatedApiSidebarName(file.data.title, file.data, apiProps.operations),
- };
- },
-};
+export function transformDeprecatedApiSidebarNode(
+ node: Item,
+ filePath: string | undefined,
+ storage: ContentStorage
+): Item {
+ if (!filePath) return node;
+
+ const file = storage.read(filePath);
+ if (!file || file.format !== 'page') return node;
+
+ const pageData = openApiSidebarPageDataSchema.safeParse(file.data);
+ if (!pageData.success) return node;
+
+ const apiProps = pageData.data.getOpenAPIPageProps();
+ return {
+ ...node,
+ name: getDeprecatedApiSidebarName(pageData.data.title, pageData.data, apiProps.operations),
+ };
+}
diff --git a/docs/lib/filter-api-version.ts b/docs/lib/filter-api-version.ts
index aac619716..edcb79259 100644
--- a/docs/lib/filter-api-version.ts
+++ b/docs/lib/filter-api-version.ts
@@ -13,12 +13,11 @@ interface PageTreeNode {
url?: string;
children?: PageTreeNode[];
index?: PageTreeNode;
- [key: string]: unknown;
}
interface PageTreeRoot {
+ name: unknown;
children: PageTreeNode[];
- [key: string]: unknown;
}
/**
@@ -70,11 +69,11 @@ function isHiddenTagNode(node: PageTreeNode): boolean {
/** Recursively drops folders/pages whose tag slug is in HIDDEN_API_TAGS. */
function filterHiddenTags(nodes: PageTreeNode[]): PageTreeNode[] {
return nodes
- .filter((node) => !isHiddenTagNode(node))
- .map((node) =>
+ .filter(node => !isHiddenTagNode(node))
+ .map(node =>
node.type === 'folder' && node.children
? { ...node, children: filterHiddenTags(node.children) }
- : node,
+ : node
);
}
@@ -115,19 +114,17 @@ export function prepareTree<T extends PageTreeRoot>(tree: T, version: string): T
// Just hide the V3 folder
return {
...tree,
- children: children.filter((node) => !isV3Node(node)),
+ children: children.filter(node => !isV3Node(node)),
};
}
// v3.0: lift V3 folder contents, keep version-independent folders (SDK Reference, Meta Tools)
- const v3Folder = children.find(
- (node) => node.type === 'folder' && isV3Node(node),
- );
+ const v3Folder = children.find(node => node.type === 'folder' && isV3Node(node));
// Nodes that should appear in both versions (exclude v3 nodes, v3.1 API Reference folder,
// and top-level pages which are version-specific — both versions have their own copies)
const sharedNodes = children.filter(
- (node) => node.type !== 'page' && !isV3Node(node) && !isV31ApiFolder(node),
+ node => node.type !== 'page' && !isV3Node(node) && !isV31ApiFolder(node)
);
if (v3Folder?.children) {
diff --git a/docs/lib/reference-page-data.ts b/docs/lib/reference-page-data.ts
new file mode 100644
index 000000000..8209418d5
--- /dev/null
+++ b/docs/lib/reference-page-data.ts
@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import type { TOCItemType } from 'fumadocs-core/toc';
+import type { OpenAPIPageProps } from 'fumadocs-openapi/ui';
+import { z } from 'zod';
+import type { OpenApiSchemaPageData } from '@/lib/api-deprecation';
+import type { ReferenceMdxPageData } from '@/lib/source';
+
+// The combined reference source mixes MDX and fumadocs-openapi pages, so page
+// data is parsed once against the shape each renderer needs instead of being
+// narrowed with `in` guards and casts. Function-valued members use z.custom
+// with a typeof check because zod cannot otherwise validate functions.
+export const openApiReferencePageDataSchema = z.object({
+ title: z.string(),
+ getOpenAPIPageProps: z.custom<() => OpenAPIPageProps>(value => typeof value === 'function'),
+ getSchema: z.custom<OpenApiSchemaPageData['getSchema']>(value => typeof value === 'function'),
+});
+
+// A TOC entry's `title` is a ReactNode, which admits nearly any runtime value
+// (string, number, element, fragment, null, ...), so it is not runtime-checkable;
+// the structural fields are validated. looseObject keeps extra members such as
+// remark-steps' `_step` intact.
+const tocItemSchema: z.ZodType<TOCItemType> = z.looseObject({
+ title: z.custom<ReactNode>(() => true),
+ url: z.string(),
+ depth: z.number(),
+});
+
+export const referenceMdxPageDataSchema = z.object({
+ title: z.string(),
+ full: z.boolean().optional().catch(undefined),
+ toc: z.array(tocItemSchema),
+ body: z.custom<ReferenceMdxPageData['body']>(value => typeof value === 'function'),
+});
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 65d4386e9..0c5b25c18 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -7,7 +7,7 @@ import { getGuardrails } from './llm-guardrails';
import { HIDDEN_API_TAGS } from './filter-api-version';
import { FILE_BUILDS } from './file-builds';
import { replaceRepoBrowserMarkdown } from './repo-browser-markdown';
-import { deprecatedApiSidebarTransformer } from './deprecated-api-sidebar';
+import { transformDeprecatedApiSidebarNode } from './deprecated-api-sidebar';
/**
* True if a reference URL belongs to an intentionally-hidden API tag
@@ -30,35 +30,28 @@ function isHiddenReferenceUrl(url: string): boolean {
return false;
}
-/**
- * Transformer to set defaultOpen: true for specific folders in the reference sidebar.
- */
-const defaultOpenTransformer = {
- folder(node: { name: string; defaultOpen?: boolean }, folderPath: string) {
- if (folderPath === 'api-reference' || folderPath === 'sdk-reference' || folderPath === 'v3/api-reference') {
- return { ...node, defaultOpen: true };
- }
- return node;
- },
-};
-
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
plugins: [lucideIconsPlugin()],
});
+function loadOpenapiPages() {
+ return Promise.all([
+ openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
+ openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
+ ]);
+}
+
+type OpenapiPages = Awaited<ReturnType<typeof loadOpenapiPages>>;
+
// One combined reference source with both v3.1 and v3.0 OpenAPI pages.
// v3.1 at api-reference/, v3.0 at api-reference/v3/
-let _referenceSource: any = null;
-let _openapiPagesPromise: Promise<any> | null = null;
+let _openapiPagesPromise: ReturnType<typeof loadOpenapiPages> | null = null;
async function getOpenapiPages() {
if (!_openapiPagesPromise) {
- _openapiPagesPromise = Promise.all([
- openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
- openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
- ]).catch((e) => {
+ _openapiPagesPromise = loadOpenapiPages().catch(e => {
// Don't permanently cache a failed load (e.g. a transient OpenAPI spec
// resolution error in a serverless instance). Clearing the memo lets the
// next request retry instead of re-throwing the same cached rejection.
@@ -69,36 +62,56 @@ async function getOpenapiPages() {
return _openapiPagesPromise;
}
+function createReferenceSource(openapiLatest: OpenapiPages[0], openapiV3Pages: OpenapiPages[1]) {
+ const loaded = loader({
+ baseUrl: '/reference',
+ source: multiple({
+ mdx: reference.toFumadocsSource(),
+ openapi: openapiLatest,
+ 'openapi-v3': openapiV3Pages,
+ }),
+ plugins: [lucideIconsPlugin(), openapiPlugin()],
+ pageTree: {
+ transformers: [
+ {
+ folder(node, folderPath) {
+ if (
+ folderPath === 'api-reference' ||
+ folderPath === 'sdk-reference' ||
+ folderPath === 'v3/api-reference'
+ ) {
+ return { ...node, defaultOpen: true };
+ }
+ return node;
+ },
+ },
+ {
+ file(node, filePath) {
+ return transformDeprecatedApiSidebarNode(node, filePath, this.storage);
+ },
+ },
+ ],
+ },
+ });
+
+ // Exclude intentionally-hidden API tags (consumer, invite-codes) from the
+ // flat page list so validate-links, llms.mdx, llms.txt, and sitemap skip
+ // their fumadocs-openapi operation pages. The sidebar tree is filtered
+ // separately via prepareTree (lib/filter-api-version.ts).
+ const originalGetPages = loaded.getPages.bind(loaded);
+ loaded.getPages = (...args: Parameters<typeof originalGetPages>) =>
+ originalGetPages(...args).filter((page: { url: string }) => !isHiddenReferenceUrl(page.url));
+
+ return loaded;
+}
+
+type ReferenceSource = ReturnType<typeof createReferenceSource>;
+let _referenceSource: ReferenceSource | null = null;
+
export async function getReferenceSource() {
if (!_referenceSource) {
const [openapiLatest, openapiV3Pages] = await getOpenapiPages();
- const loaded = loader({
- baseUrl: '/reference',
- source: multiple({
- mdx: reference.toFumadocsSource(),
- openapi: openapiLatest,
- 'openapi-v3': openapiV3Pages,
- }),
- plugins: [lucideIconsPlugin(), openapiPlugin()],
- pageTree: {
- transformers: [
- defaultOpenTransformer as any,
- deprecatedApiSidebarTransformer as any,
- ],
- },
- });
-
- // Exclude intentionally-hidden API tags (consumer, invite-codes) from the
- // flat page list so validate-links, llms.mdx, llms.txt, and sitemap skip
- // their fumadocs-openapi operation pages. The sidebar tree is filtered
- // separately via prepareTree (lib/filter-api-version.ts).
- const originalGetPages = loaded.getPages.bind(loaded);
- (loaded as any).getPages = (...args: Parameters<typeof originalGetPages>) =>
- originalGetPages(...args).filter(
- (page: { url: string }) => !isHiddenReferenceUrl(page.url),
- );
-
- _referenceSource = loaded;
+ _referenceSource = createReferenceSource(openapiLatest, openapiV3Pages);
}
return _referenceSource;
}
@@ -110,6 +123,8 @@ export const referenceSource = loader({
plugins: [lucideIconsPlugin()],
});
+export type ReferenceMdxPageData = InferPageType<typeof referenceSource>['data'];
+
export const examplesSource = loader({
baseUrl: '/examples',
source: examples.toFumadocsSource(),
@@ -124,7 +139,12 @@ export const toolkitsSource = loader({
export const changelogEntries = changelog;
-export function getOgImageUrl(_section: string, _slugs: string[], title?: string, _description?: string): string {
+export function getOgImageUrl(
+ _section: string,
+ _slugs: string[],
+ title?: string,
+ _description?: string
+): string {
const encodedTitle = encodeURIComponent(title ?? 'Composio Docs');
return `https://og.composio.dev/api/og?title=${encodedTitle}`;
}
@@ -180,11 +200,20 @@ export function mdxToCleanMarkdown(content: string): string {
result = result.replace(/<TabsList>[\s\S]*?<\/TabsList>/g, '');
result = result.replace(/<TabsTrigger[^>]*>[^<]*<\/TabsTrigger>/g, '');
- result = result.replace(/<TabsContent[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/TabsContent>/g, '\n**$1:**\n$2');
- result = result.replace(/<Tab[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Tab>/g, '\n**$1:**\n$2');
+ result = result.replace(
+ /<TabsContent[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/TabsContent>/g,
+ '\n**$1:**\n$2'
+ );
+ result = result.replace(
+ /<Tab[\s\S]*?value="([^"]*)"[\s\S]*?>([\s\S]*?)<\/Tab>/g,
+ '\n**$1:**\n$2'
+ );
result = result.replace(/<StepTitle>([\s\S]*?)<\/StepTitle>/g, (_, title) => {
- const cleanTitle = title.replace(/^[\s#]*#\s*/, '').replace(/\s+$/, '').trim();
+ const cleanTitle = title
+ .replace(/^[\s#]*#\s*/, '')
+ .replace(/\s+$/, '')
+ .trim();
return cleanTitle ? `#### ${cleanTitle}` : '';
});
result = result.replace(/<Step>\s*###\s*(.+)/g, '#### $1');
@@ -193,10 +222,7 @@ export function mdxToCleanMarkdown(content: string): string {
result = result.replace(/^(\s*#{1,6})\s*#\s+(.+)$/gm, '$1 $2');
result = result.replace(/^\s*#\s*$/gm, '');
- result = result.replace(
- /<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,
- '\n## $1\n'
- );
+ result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
result = result.replace(/<\/FrameworkOption>/g, '');
const tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };
@@ -236,10 +262,7 @@ export function mdxToCleanMarkdown(content: string): string {
'![$2]($1)'
);
- result = result.replace(
- /<ToolTypeOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g,
- '\n### $1\n'
- );
+ result = result.replace(/<ToolTypeOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n### $1\n');
result = result.replace(/<\/ToolTypeOption>/g, '');
result = result.replace(
@@ -259,15 +282,15 @@ export function mdxToCleanMarkdown(content: string): string {
result = result.replace(
/<AIToolsBanner\s*\/>/g,
'### For AI tools\n\n' +
- '**Skills:**\n' +
- '```bash\nnpx skills add composiohq/skills\n```\n' +
- '[Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)\n\n' +
- '**CLI:**\n' +
- '```bash\ncurl -fsSL https://composio.dev/install | bash\n```\n' +
- '[CLI Reference](/docs/cli)\n\n' +
- '**Context:**\n' +
- '- [llms.txt](/llms.txt) — Documentation index with links\n' +
- '- [llms-full.txt](/llms-full.txt) — Complete documentation in one file'
+ '**Skills:**\n' +
+ '```bash\nnpx skills add composiohq/skills\n```\n' +
+ '[Skills.sh](https://skills.sh/composiohq/skills/composio) · [GitHub](https://github.com/composiohq/skills)\n\n' +
+ '**CLI:**\n' +
+ '```bash\ncurl -fsSL https://composio.dev/install | bash\n```\n' +
+ '[CLI Reference](/docs/cli)\n\n' +
+ '**Context:**\n' +
+ '- [llms.txt](/llms.txt) — Documentation index with links\n' +
+ '- [llms-full.txt](/llms-full.txt) — Complete documentation in one file'
);
result = result.replace(
@@ -300,7 +323,10 @@ export function mdxToCleanMarkdown(content: string): string {
result = replaceRepoBrowserMarkdown(result);
- result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');
+ result = result.replace(
+ /<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g,
+ ''
+ );
result = result.replace(/<[A-Z][a-zA-Z]*[\s\S]*?\/>/g, '');
result = result.replace(/<\/?[A-Z][a-zA-Z]*[^>]*>/g, '');
@@ -313,9 +339,10 @@ export function mdxToCleanMarkdown(content: string): string {
const flushCodeBlock = () => {
if (codeBlockLines.length > 0) {
const nonEmptyLines = codeBlockLines.filter(l => l.trim().length > 0);
- const minIndent = nonEmptyLines.length > 0
- ? Math.min(...nonEmptyLines.map(l => l.match(/^(\s*)/)?.[1]?.length || 0))
- : 0;
+ const minIndent =
+ nonEmptyLines.length > 0
+ ? Math.min(...nonEmptyLines.map(l => l.match(/^(\s*)/)?.[1]?.length || 0))
+ : 0;
for (const codeLine of codeBlockLines) {
normalizedLines.push(codeLine.slice(minIndent));
}
@@ -376,7 +403,22 @@ function stripTwoslashFromCodeBlocks(content: string): string {
});
}
-export async function getLLMText(page: InferPageType<typeof source>, options?: { includeFooter?: boolean; includeGuardrails?: boolean }) {
+export interface LLMPage {
+ url: string;
+ data: {
+ title: string;
+ description?: string;
+ getText?: (mode: 'processed' | 'raw') => Promise<string>;
+ legacy?: boolean;
+ written?: string;
+ llmGuardrails?: Parameters<typeof getGuardrails>[0];
+ };
+}
+
+export async function getLLMText(
+ page: LLMPage,
+ options?: { includeFooter?: boolean; includeGuardrails?: boolean }
+) {
const includeFooter = options?.includeFooter ?? true;
const includeGuardrails = options?.includeGuardrails ?? true;
if (typeof page.data.getText !== 'function') {
@@ -420,7 +462,10 @@ ${page.data.description || ''}`;
const cleanSegments = segments.map(s => mdxToCleanMarkdown(s));
let cleanContent = cleanSegments[0];
for (let i = 0; i < mermaidCharts.length; i++) {
- const chart = mermaidCharts[i].replace(/&#x22;/g, '"').replace(/&#x27;/g, "'").replace(/&amp;/g, '&');
+ const chart = mermaidCharts[i]
+ .replace(/&#x22;/g, '"')
+ .replace(/&#x27;/g, "'")
+ .replace(/&amp;/g, '&');
cleanContent += `\n\n\`\`\`mermaid\n${chart}\n\`\`\`\n\n${cleanSegments[i + 1]}`;
}
@@ -440,8 +485,7 @@ ${page.data.description || ''}`;
? `\n> _Written ${written}._\n`
: '';
- const guardrails =
- includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';
+ const guardrails = includeGuardrails && !isLegacy ? getGuardrails(page.data.llmGuardrails) : '';
return `# ${page.data.title} (${page.url})
${topNote}
@@ -460,9 +504,7 @@ const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
function validateDateFormat(dateStr: string): void {
if (!DATE_REGEX.test(dateStr)) {
- throw new Error(
- `Invalid date format: "${dateStr}". Expected YYYY-MM-DD (e.g., "2025-12-29")`
- );
+ throw new Error(`Invalid date format: "${dateStr}". Expected YYYY-MM-DD (e.g., "2025-12-29")`);
}
}
diff --git a/docs/lib/standup-bot-build.ts b/docs/lib/standup-bot-build.ts
index 11c597182..764709e14 100644
--- a/docs/lib/standup-bot-build.ts
+++ b/docs/lib/standup-bot-build.ts
@@ -223,6 +223,13 @@ const buttons2 = `import { verifySlackSignature, readRawBody, updateMessage, pos
import { generateDraft } from './_utils/agent';
import { draftMessage, connectMenu } from './_utils/blocks';
+type SlackInteractionPayload = {
+ actions?: Array<{
+ action_id?: string;
+ value?: string;
+ }>;
+};
+
// Slack POSTs here every time someone clicks a button. Verify it really came
// from Slack, then ack within 3 seconds (Slack retries if you're slow).
export default async function handler(req: Request, res: Response) {
@@ -236,7 +243,7 @@ export default async function handler(req: Request, res: Response) {
// Each button carried its context in \`value\`, so the handler knows exactly what
// to do. No model decides anything here: the flow is fixed.
-async function handleClick(payload: any) {
+async function handleClick(payload: SlackInteractionPayload) {
const action = payload.actions?.[0];
const ctx = JSON.parse(action?.value ?? '{}');
diff --git a/docs/lib/toolkit-schema.ts b/docs/lib/toolkit-schema.ts
index f718cdfa2..fb16f2cc2 100644
--- a/docs/lib/toolkit-schema.ts
+++ b/docs/lib/toolkit-schema.ts
@@ -1,57 +1,214 @@
-import type { ParameterSchema, Tool } from '@/types/toolkit';
+import { z } from 'zod';
+import type { ParameterSchema, Tool, Trigger } from '@/types/toolkit';
+
+// Zod schemas for the untyped tool/trigger payloads the Composio API returns.
+// Each boundary parses once (leniently — malformed fields degrade to the same
+// fallbacks the UI applied by hand before) and lets the inferred types flow.
+
+/** Keep only the array members that satisfy `schema`; junk entries are dropped. */
+function filteredArray<T>(schema: z.ZodType<T>) {
+ return z
+ .array(z.unknown())
+ .catch([])
+ .transform(items =>
+ items.flatMap(item => {
+ const parsed = schema.safeParse(item);
+ return parsed.success ? [parsed.data] : [];
+ })
+ );
+}
+
+const lenientString = z.string().catch('');
+const optionalString = z.string().optional().catch(undefined);
+const stringArray = filteredArray(z.string());
+const scalarStringArray = filteredArray(
+ z.union([z.string(), z.number(), z.boolean()]).transform(value => String(value))
+);
+
+// --- JSON-Schema parameter nodes -------------------------------------------
+
+// Recursive JSON-Schema property node. Nested properties, items, and
+// object-valued additionalProperties survive whole (the toolkit detail UI
+// reads items.additionalProperties and additionalProperties.properties to
+// synthesize the "[key: string]" row). Tuple-form `items` arrays are not
+// object nodes and parse to undefined instead of spreading into numeric keys.
+interface RawSchemaNode {
+ type: string;
+ description?: string;
+ default?: unknown;
+ example?: unknown;
+ enum: string[];
+ properties?: Record<string, unknown>;
+ required?: string[];
+ items?: RawSchemaNode;
+ additionalProperties?: boolean | RawSchemaNode;
+}
+
+const rawSchemaNodeSchema: z.ZodType<RawSchemaNode> = z.object({
+ type: lenientString,
+ description: optionalString,
+ default: z.unknown().optional(),
+ example: z.unknown().optional(),
+ enum: scalarStringArray,
+ properties: z.record(z.string(), z.unknown()).optional().catch(undefined),
+ required: filteredArray(z.string()).optional().catch(undefined),
+ get items(): z.ZodType<RawSchemaNode | undefined> {
+ return rawSchemaNodeSchema.optional().catch(undefined);
+ },
+ get additionalProperties(): z.ZodType<boolean | RawSchemaNode | undefined> {
+ return z.union([z.boolean(), rawSchemaNodeSchema]).optional().catch(undefined);
+ },
+});
+
+function toParameterSchema(node: RawSchemaNode): ParameterSchema {
+ const param: ParameterSchema = {
+ type: node.type,
+ description: node.description,
+ default: node.default,
+ example: node.example,
+ enum: node.enum.length > 0 ? node.enum : undefined,
+ };
+
+ if (node.properties) {
+ param.properties = processParams(node.properties, node.required ?? []);
+ }
+ if (node.required) {
+ param.requiredFields = node.required;
+ }
+ if (node.items) {
+ param.items = toParameterSchema(node.items);
+ }
+ if (typeof node.additionalProperties === 'boolean') {
+ param.additionalProperties = node.additionalProperties;
+ } else if (node.additionalProperties) {
+ param.additionalProperties = toParameterSchema(node.additionalProperties);
+ }
+
+ return param;
+}
// Add required flag to each property based on the required array
// Preserves nested properties/items for object and array types
-function processParams(props: any, requiredList: string[]): Record<string, ParameterSchema> | undefined {
- if (!props || typeof props !== 'object') return undefined;
+function processParams(
+ props: Record<string, unknown>,
+ requiredList: string[]
+): Record<string, ParameterSchema> | undefined {
const result: Record<string, ParameterSchema> = {};
for (const [key, value] of Object.entries(props)) {
- if (typeof value === 'object' && value !== null) {
- const param = value as any;
+ const parsed = rawSchemaNodeSchema.safeParse(value);
+ if (parsed.success) {
result[key] = {
- type: param.type,
- description: param.description,
- default: param.default,
- example: param.example,
- enum: param.enum,
+ ...toParameterSchema(parsed.data),
required: requiredList.includes(key),
- ...(param.properties ? { properties: param.properties } : {}),
- ...(Array.isArray(param.required) ? { requiredFields: param.required } : {}),
- ...(param.items ? { items: {
- ...param.items,
- ...(Array.isArray(param.items.required) ? { requiredFields: param.items.required } : {}),
- } } : {}),
- ...(param.additionalProperties && typeof param.additionalProperties === 'object'
- ? { additionalProperties: param.additionalProperties }
- : {}),
};
}
}
return Object.keys(result).length > 0 ? result : undefined;
}
+const rawSchemaRootSchema = z.object({
+ properties: z.record(z.string(), z.unknown()).optional().catch(undefined),
+ required: stringArray,
+});
+
// Process a raw JSON Schema (with top-level properties + required) into ParameterSchema records
-export function processSchema(schema: any): Record<string, ParameterSchema> | undefined {
- if (!schema) return undefined;
- const props = schema.properties || schema;
- const required = schema.required || [];
- if (!props || typeof props !== 'object') return undefined;
- return processParams(props, required);
+export function processSchema(schema: unknown): Record<string, ParameterSchema> | undefined {
+ const record = z.record(z.string(), z.unknown()).safeParse(schema);
+ if (!record.success) return undefined;
+ const root = rawSchemaRootSchema.parse(record.data);
+ return processParams(root.properties ?? record.data, root.required);
+}
+
+// --- Tools ------------------------------------------------------------------
+
+const rawApiToolSchema = z.object({
+ slug: lenientString,
+ name: optionalString,
+ display_name: optionalString,
+ description: lenientString,
+ input_parameters: z.unknown().optional(),
+ parameters: z.unknown().optional(),
+ output_parameters: z.unknown().optional(),
+ response: z.unknown().optional(),
+ scopes: stringArray,
+ tags: stringArray,
+ is_deprecated: z.boolean().catch(false),
+});
+
+type RawApiTool = z.infer<typeof rawApiToolSchema>;
+
+function toolFromRaw(raw: RawApiTool): Tool {
+ return {
+ slug: raw.slug,
+ name: raw.name || raw.display_name || raw.slug,
+ description: raw.description,
+ input_parameters: processSchema(raw.input_parameters || raw.parameters),
+ output_parameters: processSchema(raw.output_parameters || raw.response),
+ scopes: raw.scopes.length > 0 ? raw.scopes : undefined,
+ tags: raw.tags.length > 0 ? raw.tags : undefined,
+ is_deprecated: raw.is_deprecated,
+ };
}
// Convert a raw API tool object into our Tool type
-export function toolFromApi(tool: any): Tool {
- const inputSchema = tool.input_parameters || tool.parameters;
- const outputSchema = tool.output_parameters || tool.response;
+export function toolFromApi(tool: unknown): Tool {
+ const parsed = rawApiToolSchema.safeParse(tool);
+ return toolFromRaw(parsed.success ? parsed.data : rawApiToolSchema.parse({}));
+}
+
+// --- Triggers ---------------------------------------------------------------
+const rawApiTriggerSchema = z.object({
+ slug: lenientString,
+ name: optionalString,
+ display_name: optionalString,
+ description: lenientString,
+ type: z.enum(['webhook', 'poll']).optional().catch(undefined),
+ config: z.unknown().optional(),
+ payload: z.unknown().optional(),
+ instructions: optionalString,
+});
+
+type RawApiTrigger = z.infer<typeof rawApiTriggerSchema>;
+
+function triggerFromRaw(raw: RawApiTrigger): Trigger {
return {
- slug: tool.slug || '',
- name: tool.name || tool.display_name || tool.slug || '',
- description: tool.description || '',
- input_parameters: processSchema(inputSchema),
- output_parameters: processSchema(outputSchema),
- scopes: tool.scopes || undefined,
- tags: tool.tags || undefined,
- is_deprecated: tool.is_deprecated || false,
+ slug: raw.slug,
+ name: raw.name || raw.display_name || raw.slug,
+ description: raw.description,
+ type: raw.type,
+ config: processSchema(raw.config),
+ payload: processSchema(raw.payload),
+ instructions: raw.instructions,
};
}
+
+// Convert a raw API trigger object into our Trigger type
+export function triggerFromApi(trigger: unknown): Trigger {
+ const parsed = rawApiTriggerSchema.safeParse(trigger);
+ return triggerFromRaw(parsed.success ? parsed.data : rawApiTriggerSchema.parse({}));
+}
+
+// --- List responses ---------------------------------------------------------
+
+// Paged API responses arrive either as a bare array or as an { items } envelope.
+const listEnvelopeSchema = z.union([
+ z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
+ z.array(z.unknown()),
+]);
+
+/** Parses a /tools list response into Tool records, dropping non-object entries. */
+export const apiToolListSchema = listEnvelopeSchema.transform(items =>
+ items.flatMap(item => {
+ const parsed = rawApiToolSchema.safeParse(item);
+ return parsed.success ? [toolFromRaw(parsed.data)] : [];
+ })
+);
+
+/** Parses a /triggers_types list response into Trigger records, dropping non-object entries. */
+export const apiTriggerListSchema = listEnvelopeSchema.transform(items =>
+ items.flatMap(item => {
+ const parsed = rawApiTriggerSchema.safeParse(item);
+ return parsed.success ? [triggerFromRaw(parsed.data)] : [];
+ })
+);
diff --git a/docs/mdx-components.tsx b/docs/mdx-components.tsx
index 456a82e67..94c1ceaf0 100644
--- a/docs/mdx-components.tsx
+++ b/docs/mdx-components.tsx
@@ -71,11 +71,20 @@ import {
} from 'lucide-react';
function slugify(text: string): string {
- return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+ return text
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/(^-|-$)/g, '');
}
export function Accordion({ id, title, ...props }: ComponentProps<typeof BaseAccordion>) {
- return <BaseAccordion id={id ?? (typeof title === 'string' ? slugify(title) : undefined)} title={title} {...props} />;
+ return (
+ <BaseAccordion
+ id={id ?? (typeof title === 'string' ? slugify(title) : undefined)}
+ title={title}
+ {...props}
+ />
+ );
}
export { Accordions };
@@ -83,10 +92,10 @@ export { Accordions };
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultMdxComponents,
- h2: (props) => <Heading as="h2" {...props} />,
- h3: (props) => <Heading as="h3" {...props} />,
- h4: (props) => <Heading as="h4" {...props} />,
- img: (props) => <ImageZoom {...(props as any)} />,
+ h2: props => <Heading as="h2" {...props} />,
+ h3: props => <Heading as="h3" {...props} />,
+ h4: props => <Heading as="h4" {...props} />,
+ img: props => <ImageZoom {...(props as ComponentProps<typeof ImageZoom>)} />,
YouTube,
Tabs,
Tab,
diff --git a/docs/scripts/generate-meta-tools.ts b/docs/scripts/generate-meta-tools.ts
index b48973e48..fe2bc17c8 100644
--- a/docs/scripts/generate-meta-tools.ts
+++ b/docs/scripts/generate-meta-tools.ts
@@ -21,18 +21,62 @@ import { join } from 'path';
import { fetchWithRetry } from './fetch-with-retry';
import { META_TOOL_OVERRIDES } from '../lib/meta-tool-overrides';
import { requireProductionApiV3Url, stripStagingHosts } from './production-api.mjs';
+import { z } from 'zod';
const API_BASE = requireProductionApiV3Url(process.env.COMPOSIO_API_BASE);
const API_KEY = process.env.COMPOSIO_API_KEY;
-if (!API_KEY) {
- console.error('Error: COMPOSIO_API_KEY environment variable is required');
- process.exit(1);
-}
-
const DATA_DIR = join(process.cwd(), 'public/data');
const CONTENT_DIR = join(process.cwd(), 'content/toolkits/meta-tools');
+interface GeneratedMetaTool {
+ slug: string;
+ name: string;
+ displayName: string;
+ description: string;
+ tags: string[];
+ toolkit: string | null;
+ inputParameters: Record<string, unknown>;
+ responseSchema: Record<string, unknown>;
+}
+
+// Zod schemas for the Tool Router payloads this script consumes. Parsing is
+// lenient: malformed fields degrade to empty fallbacks instead of aborting.
+
+const stringArraySchema = z
+ .array(z.unknown())
+ .catch([])
+ .transform(items =>
+ items.flatMap(item => {
+ const parsed = z.string().safeParse(item);
+ return parsed.success ? [parsed.data] : [];
+ })
+ );
+
+const recordSchema = z.record(z.string(), z.unknown()).catch({});
+
+const sessionResponseSchema = z
+ .object({
+ session_id: z.string().optional().catch(undefined),
+ tool_router_tools: stringArraySchema,
+ })
+ .catch({ session_id: undefined, tool_router_tools: [] });
+
+const metaToolListSchema = z.union([
+ z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
+ z.array(z.unknown()),
+]);
+
+const rawMetaToolSchema = z.object({
+ slug: z.string().catch(''),
+ name: z.string().catch(''),
+ description: z.string().catch(''),
+ tags: stringArraySchema,
+ toolkit: z.string().optional().catch(undefined),
+ input_parameters: recordSchema,
+ output_parameters: recordSchema,
+});
+
async function createSession(): Promise<string> {
console.log('Creating session...');
@@ -57,7 +101,7 @@ async function createSession(): Promise<string> {
throw new Error(`Failed to create session: ${response.status} ${response.statusText}\n${body}`);
}
- const data = await response.json();
+ const data = sessionResponseSchema.parse(await response.json());
const sessionId = data.session_id;
if (!sessionId) {
@@ -65,11 +109,11 @@ async function createSession(): Promise<string> {
}
console.log(` Session created: ${sessionId}`);
- console.log(` Tools available: ${(data.tool_router_tools || []).join(', ')}`);
+ console.log(` Tools available: ${data.tool_router_tools.join(', ')}`);
return sessionId;
}
-async function fetchMetaTools(sessionId: string): Promise<any[]> {
+async function fetchMetaTools(sessionId: string): Promise<unknown[]> {
console.log('Fetching meta tools with schemas...');
const response = await fetchWithRetry(`${API_BASE}/tool_router/session/${sessionId}/tools`, {
@@ -80,42 +124,44 @@ async function fetchMetaTools(sessionId: string): Promise<any[]> {
if (!response.ok) {
const body = await response.text();
- throw new Error(`Failed to fetch meta tools: ${response.status} ${response.statusText}\n${body}`);
+ throw new Error(
+ `Failed to fetch meta tools: ${response.status} ${response.statusText}\n${body}`
+ );
}
- const data = await response.json();
- const tools = data.items || data;
-
- if (!Array.isArray(tools)) {
+ const parsed = metaToolListSchema.safeParse(await response.json());
+ if (!parsed.success) {
throw new Error('Expected array of tools in response');
}
- console.log(` Found ${tools.length} meta tools`);
- return tools;
+ console.log(` Found ${parsed.data.length} meta tools`);
+ return parsed.data;
}
-function transformTool(raw: any) {
- const slug: string = raw.slug || '';
+export function transformTool(value: unknown): GeneratedMetaTool {
+ const parsed = rawMetaToolSchema.safeParse(value);
+ const raw = parsed.success ? parsed.data : rawMetaToolSchema.parse({});
+ const { slug, name } = raw;
return {
slug,
- name: raw.name || '',
- displayName: raw.name?.replace(/_/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase()) || slug,
- description: raw.description || '',
- tags: raw.tags || [],
+ name,
+ displayName: name.replace(/_/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase()) || slug,
+ description: raw.description,
+ tags: raw.tags,
toolkit: raw.toolkit || null,
- inputParameters: raw.input_parameters || {},
- responseSchema: raw.output_parameters || {},
+ inputParameters: raw.input_parameters,
+ responseSchema: raw.output_parameters,
};
}
/** Derive a short page slug from the tool slug: COMPOSIO_SEARCH_TOOLS -> search_tools */
-function pageSlug(toolSlug: string): string {
+export function pageSlug(toolSlug: string): string {
return toolSlug.toLowerCase().replace('composio_', '');
}
/** Truncate description to first sentence for index table */
-function briefDescription(description: string): string {
+export function briefDescription(description: string): string {
// Strip markdown and leading whitespace
const cleaned = description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim();
const firstSentence = cleaned.split(/\.(\s|$)/)[0];
@@ -126,7 +172,7 @@ function briefDescription(description: string): string {
}
/** One-line summary for the index table. Prefer hand-written override copy, fall back to the API description. */
-function indexLine(tool: any): string {
+function indexLine(tool: GeneratedMetaTool): string {
const override = META_TOOL_OVERRIDES[tool.slug];
if (override) {
// First sentence of the hand-written summary keeps the table tight.
@@ -137,7 +183,7 @@ function indexLine(tool: any): string {
}
/** Generate the index.mdx overview page — Modal-voice intro plus a one-line-per-tool table */
-function generateIndexMdx(tools: any[]): string {
+function generateIndexMdx(tools: GeneratedMetaTool[]): string {
let content = `---
title: Meta Tools
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
}
/** Generate an individual tool MDX page */
-function generateToolMdx(tool: any): string {
+function generateToolMdx(tool: GeneratedMetaTool): string {
const desc = briefDescription(tool.description).replace(/"/g, '\\"');
return `---
@@ -190,7 +236,7 @@ import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page';
}
/** Generate meta.json for sidebar navigation — index.mdx is the folder page */
-function generateMetaJson(tools: any[]): string {
+function generateMetaJson(tools: GeneratedMetaTool[]): string {
const pages = tools.map(t => pageSlug(t.slug));
return JSON.stringify({ title: 'Meta Tools', defaultOpen: true, pages }, null, 2) + '\n';
}
@@ -222,8 +268,13 @@ async function main() {
metaTools.sort((a, b) => a.slug.localeCompare(b.slug));
// 1. Write JSON data
- await writeFile(join(DATA_DIR, 'meta-tools.json'), stripStagingHosts(JSON.stringify(metaTools, null, 2)));
- console.log(`\nWrote public/data/meta-tools.json (~${Math.round(JSON.stringify(metaTools).length / 1024)}KB)`);
+ await writeFile(
+ join(DATA_DIR, 'meta-tools.json'),
+ stripStagingHosts(JSON.stringify(metaTools, null, 2))
+ );
+ console.log(
+ `\nWrote public/data/meta-tools.json (~${Math.round(JSON.stringify(metaTools).length / 1024)}KB)`
+ );
// 2. Clean old generated MDX files and regenerate
await cleanGeneratedMdx();
@@ -247,7 +298,14 @@ async function main() {
console.log(`Tools: ${metaTools.map(t => t.slug).join(', ')}`);
}
-main().catch((error) => {
- console.error('Fatal error:', error);
- process.exit(1);
-});
+if (import.meta.main) {
+ if (!API_KEY) {
+ console.error('Error: COMPOSIO_API_KEY environment variable is required');
+ process.exit(1);
+ }
+
+ main().catch(error => {
+ console.error('Fatal error:', error);
+ process.exit(1);
+ });
+}
diff --git a/docs/scripts/generate-toolkits.ts b/docs/scripts/generate-toolkits.ts
index b74fdd884..6da435bfb 100644
--- a/docs/scripts/generate-toolkits.ts
+++ b/docs/scripts/generate-toolkits.ts
@@ -13,15 +13,11 @@ import { join } from 'path';
import { fetchWithRetry } from './fetch-with-retry';
import { requireProductionApiV3Url, stripStagingHosts } from './production-api.mjs';
import { applyToolkitVersions, fetchProductionToolkitVersions } from './toolkit-versions';
+import { z } from 'zod';
const API_BASE = requireProductionApiV3Url(process.env.COMPOSIO_API_BASE);
const API_KEY = process.env.COMPOSIO_API_KEY;
-if (!API_KEY) {
- console.error('Error: COMPOSIO_API_KEY environment variable is required');
- process.exit(1);
-}
-
const OUTPUT_DIR = join(process.cwd(), 'public/data');
interface Tool {
@@ -76,6 +72,124 @@ interface Toolkit {
authConfigDetails?: AuthConfigDetail[];
}
+// Zod schemas for the raw API payloads this script consumes. Parsing is
+// lenient on purpose: malformed fields degrade to the same fallbacks the
+// hand-written mapping used to apply, so a partially bad catalog entry never
+// aborts a full generation run.
+
+/** Optional lenient string array: undefined when absent/non-array, junk members dropped. */
+const optionalStringArraySchema = z
+ .array(z.unknown())
+ .optional()
+ .catch(undefined)
+ .transform(items =>
+ items?.flatMap(item => {
+ const parsed = z.string().safeParse(item);
+ return parsed.success ? [parsed.data] : [];
+ })
+ );
+
+const rawToolkitSchema = z.object({
+ slug: z.string().catch(''),
+ name: z.string().optional().catch(undefined),
+ logo: z.string().optional().catch(undefined),
+ description: z.string().catch(''),
+ meta: z
+ .object({
+ logo: z.string().optional().catch(undefined),
+ description: z.string().optional().catch(undefined),
+ categories: z.array(z.unknown()).catch([]),
+ })
+ .catch({ logo: undefined, description: undefined, categories: [] }),
+ auth_schemes: optionalStringArraySchema,
+ authSchemes: optionalStringArraySchema,
+ composio_managed_auth_schemes: optionalStringArraySchema,
+ composioManagedAuthSchemes: optionalStringArraySchema,
+ tool_count: z.number().optional().catch(undefined),
+ toolCount: z.number().optional().catch(undefined),
+ trigger_count: z.number().optional().catch(undefined),
+ triggerCount: z.number().optional().catch(undefined),
+});
+
+const categoryEntrySchema = z.union([
+ z.string(),
+ z.object({ name: z.string() }).transform(entry => entry.name),
+]);
+
+// A paged toolkits response: { items, next_cursor } envelope or a bare array.
+const toolkitsPageSchema = z.union([
+ z.object({
+ items: z.array(z.unknown()),
+ next_cursor: z.string().optional().catch(undefined),
+ }),
+ z.array(z.unknown()).transform(items => ({ items, next_cursor: undefined })),
+]);
+
+const slugItemSchema = z.object({ slug: z.string() });
+
+// Tools/triggers list entries share the slug/name/description shape.
+const rawNamedItemSchema = z.object({
+ slug: z.string().catch(''),
+ name: z.string().optional().catch(undefined),
+ display_name: z.string().optional().catch(undefined),
+ description: z.string().catch(''),
+});
+
+const namedItemListSchema = z
+ .union([
+ z.object({ items: z.array(z.unknown()) }).transform(data => data.items),
+ z.array(z.unknown()),
+ ])
+ .catch([])
+ .transform(items =>
+ items.flatMap(item => {
+ const parsed = rawNamedItemSchema.safeParse(item);
+ if (!parsed.success) return [];
+ const { slug, name, display_name, description } = parsed.data;
+ return [{ slug, name: name || display_name || slug, description }];
+ })
+ );
+
+const requirementListsSchema = z
+ .object({
+ required: z.array(z.unknown()).catch([]),
+ optional: z.array(z.unknown()).catch([]),
+ })
+ .catch({ required: [], optional: [] });
+
+const authConfigFieldsSchema = z
+ .object({
+ auth_config_creation: requirementListsSchema,
+ connected_account_initiation: requirementListsSchema,
+ })
+ .catch({
+ auth_config_creation: { required: [], optional: [] },
+ connected_account_initiation: { required: [], optional: [] },
+ });
+
+const rawAuthConfigFieldSchema = z.object({
+ name: z.string().catch(''),
+ displayName: z.string().optional().catch(undefined),
+ type: z.string().catch('string'),
+ description: z.string().catch(''),
+ required: z.boolean().optional().catch(undefined),
+ default: z
+ .union([z.string(), z.number(), z.boolean()])
+ .transform(value => String(value))
+ .nullable()
+ .optional()
+ .catch(undefined),
+});
+
+const rawAuthConfigDetailSchema = z.object({
+ mode: z.string().catch(''),
+ name: z.string().optional().catch(undefined),
+});
+
+const authConfigDetailsResponseSchema = z
+ .object({ auth_config_details: z.array(z.unknown()).catch([]) })
+ .catch({ auth_config_details: [] });
+
// The backend silently caps `limit` at 1000 per page and defaults to usage
// ordering, so a single request returns only the top-1000 toolkits — about half
// the catalog. Request the cap and follow `next_cursor` until exhausted.
@@ -83,10 +197,18 @@ interface Toolkit {
const TOOLKITS_PAGE_LIMIT = 1000;
const TOOLKITS_MAX_PAGES = 12;
-async function fetchToolkits(): Promise<any[]> {
+export function parseToolkitsPage(value: unknown) {
+ return toolkitsPageSchema.parse(value);
+}
+
+export function parseNamedItems(value: unknown) {
+ return namedItemListSchema.parse(value);
+}
+
+async function fetchToolkits(): Promise<unknown[]> {
console.log('Fetching toolkits from API...');
- const items: any[] = [];
+ const items: unknown[] = [];
// Pages can overlap when the catalog shifts between cursor fetches; keep the
// first occurrence so API-provided ordering stays stable.
const seen = new Set<string>();
@@ -107,10 +229,10 @@ async function fetchToolkits(): Promise<any[]> {
throw new Error(`Failed to fetch toolkits: ${response.status} ${response.statusText}`);
}
- const data = await response.json();
- const pageItems: any[] = data.items || data;
- for (const item of pageItems) {
- const slug = item?.slug?.toLowerCase();
+ const pageData = parseToolkitsPage(await response.json());
+ for (const item of pageData.items) {
+ const parsedSlug = slugItemSchema.safeParse(item);
+ const slug = parsedSlug.success ? parsedSlug.data.slug.toLowerCase() : undefined;
if (slug) {
if (seen.has(slug)) continue;
seen.add(slug);
@@ -118,7 +240,7 @@ async function fetchToolkits(): Promise<any[]> {
items.push(item);
}
- cursor = data.next_cursor ?? undefined;
+ cursor = pageData.next_cursor;
if (!cursor) return items;
}
@@ -130,45 +252,81 @@ async function fetchToolkits(): Promise<any[]> {
}
async function fetchToolsForToolkit(slug: string): Promise<Tool[]> {
- const response = await fetchWithRetry(`${API_BASE}/tools?toolkit_slug=${slug}&toolkit_versions=latest&limit=1000`, {
- headers: {
- 'Content-Type': 'application/json',
- 'x-api-key': API_KEY!,
- },
- });
+ const response = await fetchWithRetry(
+ `${API_BASE}/tools?toolkit_slug=${slug}&toolkit_versions=latest&limit=1000`,
+ {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ }
+ );
if (!response.ok) return [];
- const data = await response.json();
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
-
- return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
- slug: raw.slug || '',
- name: raw.name || raw.display_name || raw.slug || '',
- description: raw.description || '',
- }));
+ return parseNamedItems(await response.json());
}
async function fetchTriggersForToolkit(slug: string): Promise<Trigger[]> {
- const response = await fetchWithRetry(`${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`, {
- headers: {
- 'Content-Type': 'application/json',
- 'x-api-key': API_KEY!,
- },
- });
+ const response = await fetchWithRetry(
+ `${API_BASE}/triggers_types?toolkit_slugs=${slug}&toolkit_versions=latest`,
+ {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY!,
+ },
+ }
+ );
if (!response.ok) return [];
- const data = await response.json();
- const rawItems = data.items || data;
- const items = Array.isArray(rawItems) ? rawItems : [];
+ return parseNamedItems(await response.json());
+}
- return items.filter((raw: any) => raw && typeof raw === 'object').map((raw: any) => ({
- slug: raw.slug || '',
- name: raw.name || raw.display_name || raw.slug || '',
- description: raw.description || '',
- }));
+export function transformAuthConfigField(value: unknown, required: boolean): AuthConfigField {
+ const parsed = rawAuthConfigFieldSchema.safeParse(value);
+ const field = parsed.success ? parsed.data : rawAuthConfigFieldSchema.parse({});
+
+ return {
+ name: field.name,
+ displayName: field.displayName || field.name,
+ type: field.type,
+ description: field.description,
+ required: field.required ?? required,
+ default: field.default ?? null,
+ };
+}
+
+export function authConfigFields(
+ raw: Record<string, unknown>,
+ phase: 'auth_config_creation' | 'connected_account_initiation',
+ requirement: 'required' | 'optional'
+): AuthConfigField[] {
+ const fields = authConfigFieldsSchema.parse(raw.fields);
+ return fields[phase][requirement].map(field =>
+ transformAuthConfigField(field, requirement === 'required')
+ );
+}
+
+export function transformAuthConfigDetail(value: unknown): AuthConfigDetail | null {
+ const raw = z.record(z.string(), z.unknown()).safeParse(value);
+ if (!raw.success) return null;
+
+ const { mode, name } = rawAuthConfigDetailSchema.parse(raw.data);
+ return {
+ mode,
+ name: name || mode,
+ fields: {
+ auth_config_creation: {
+ required: authConfigFields(raw.data, 'auth_config_creation', 'required'),
+ optional: authConfigFields(raw.data, 'auth_config_creation', 'optional'),
+ },
+ connected_account_initiation: {
+ required: authConfigFields(raw.data, 'connected_account_initiation', 'required'),
+ optional: authConfigFields(raw.data, 'connected_account_initiation', 'optional'),
+ },
+ },
+ };
}
async function fetchAuthConfigDetails(slug: string): Promise<AuthConfigDetail[]> {
@@ -181,67 +339,34 @@ async function fetchAuthConfigDetails(slug: string): Promise<AuthConfigDetail[]>
if (!response.ok) return [];
- const data = await response.json();
- const authConfigDetails = data.auth_config_details || [];
+ const data = authConfigDetailsResponseSchema.parse(await response.json());
- return authConfigDetails.map((raw: any) => ({
- mode: raw.mode || '',
- name: raw.name || raw.mode || '',
- fields: {
- auth_config_creation: {
- required: (raw.fields?.auth_config_creation?.required || []).map((f: any) => ({
- name: f.name || '',
- displayName: f.displayName || f.name || '',
- type: f.type || 'string',
- description: f.description || '',
- required: f.required ?? true,
- default: f.default ?? null,
- })),
- optional: (raw.fields?.auth_config_creation?.optional || []).map((f: any) => ({
- name: f.name || '',
- displayName: f.displayName || f.name || '',
- type: f.type || 'string',
- description: f.description || '',
- required: f.required ?? false,
- default: f.default ?? null,
- })),
- },
- connected_account_initiation: {
- required: (raw.fields?.connected_account_initiation?.required || []).map((f: any) => ({
- name: f.name || '',
- displayName: f.displayName || f.name || '',
- type: f.type || 'string',
- description: f.description || '',
- required: f.required ?? true,
- default: f.default ?? null,
- })),
- optional: (raw.fields?.connected_account_initiation?.optional || []).map((f: any) => ({
- name: f.name || '',
- displayName: f.displayName || f.name || '',
- type: f.type || 'string',
- description: f.description || '',
- required: f.required ?? false,
- default: f.default ?? null,
- })),
- },
- },
- }));
+ return data.auth_config_details.flatMap(item => {
+ const detail = transformAuthConfigDetail(item);
+ return detail ? [detail] : [];
+ });
}
-function transformToolkit(raw: any): Toolkit {
- const authSchemes = raw.auth_schemes || raw.authSchemes || [];
- const composioManaged = raw.composio_managed_auth_schemes || raw.composioManagedAuthSchemes || [];
+export function transformToolkit(raw: unknown): Toolkit {
+ const parsed = rawToolkitSchema.safeParse(raw);
+ const toolkit = parsed.success ? parsed.data : rawToolkitSchema.parse({});
+ const slug = toolkit.slug.toLowerCase();
+ const firstCategory = categoryEntrySchema.safeParse(toolkit.meta.categories[0]);
+ const category = firstCategory.success ? firstCategory.data : null;
+ const authSchemes = toolkit.auth_schemes ?? toolkit.authSchemes ?? [];
+ const composioManaged =
+ toolkit.composio_managed_auth_schemes ?? toolkit.composioManagedAuthSchemes ?? [];
return {
- slug: raw.slug?.toLowerCase() || '',
- name: raw.name || raw.slug || '',
- logo: raw.meta?.logo || raw.logo || null,
- description: raw.meta?.description || raw.description || '',
- category: raw.meta?.categories?.[0]?.name || raw.meta?.categories?.[0] || null,
+ slug,
+ name: toolkit.name || toolkit.slug,
+ logo: toolkit.meta.logo || toolkit.logo || null,
+ description: toolkit.meta.description || toolkit.description,
+ category: category || null,
authSchemes,
...(composioManaged.length > 0 ? { composioManagedAuthSchemes: composioManaged } : {}),
- toolCount: raw.tool_count || raw.toolCount || 0,
- triggerCount: raw.trigger_count || raw.triggerCount || 0,
+ toolCount: toolkit.tool_count || toolkit.toolCount || 0,
+ triggerCount: toolkit.trigger_count || toolkit.triggerCount || 0,
version: null,
tools: [],
triggers: [],
@@ -279,7 +404,7 @@ async function main() {
const batch = toolkits.slice(i, i + batchSize);
await Promise.all(
- batch.map(async (toolkit) => {
+ batch.map(async toolkit => {
const [tools, triggers, authConfigDetails] = await Promise.all([
fetchToolsForToolkit(toolkit.slug.toUpperCase()),
fetchTriggersForToolkit(toolkit.slug.toUpperCase()),
@@ -312,12 +437,14 @@ async function main() {
// Write light file (for landing page - imported in client component)
// Excludes tools and triggers arrays to keep bundle size small
const toolkitsLight = toolkits.map(({ slug, name, logo, category, toolCount, triggerCount }) => ({
- slug, name, logo, category, toolCount, triggerCount,
+ slug,
+ name,
+ logo,
+ category,
+ toolCount,
+ triggerCount,
}));
- await writeFile(
- join(OUTPUT_DIR, 'toolkits-list.json'),
- JSON.stringify(toolkitsLight, null, 2)
- );
+ await writeFile(join(OUTPUT_DIR, 'toolkits-list.json'), JSON.stringify(toolkitsLight, null, 2));
const fullSizeKB = Math.round(JSON.stringify(toolkits).length / 1024);
const lightSizeKB = Math.round(JSON.stringify(toolkitsLight).length / 1024);
@@ -327,7 +454,14 @@ async function main() {
console.log(` Toolkits: ${toolkits.length}`);
}
-main().catch((error) => {
- console.error('Fatal error:', error);
- process.exit(1);
-});
+if (import.meta.main) {
+ if (!API_KEY) {
+ console.error('Error: COMPOSIO_API_KEY environment variable is required');
+ process.exit(1);
+ }
+
+ main().catch(error => {
+ console.error('Fatal error:', error);
+ process.exit(1);
+ });
+}
diff --git a/docs/scripts/validate-links.ts b/docs/scripts/validate-links.ts
index 86700ff48..e1960f12d 100644
--- a/docs/scripts/validate-links.ts
+++ b/docs/scripts/validate-links.ts
@@ -1,19 +1,10 @@
import { readFile } from 'node:fs/promises';
import { glob } from 'node:fs/promises';
import { resolve } from 'node:path';
-import {
- type FileObject,
- printErrors,
- scanURLs,
- validateFiles,
-} from 'next-validate-link';
+import { type FileObject, printErrors, scanURLs, validateFiles } from 'next-validate-link';
import GithubSlugger from 'github-slugger';
-import {
- source,
- getReferenceSource,
- examplesSource,
- toolkitsSource,
-} from '../lib/source';
+import { z } from 'zod';
+import { source, getReferenceSource, examplesSource, toolkitsSource } from '../lib/source';
/**
* `--external` additionally HEAD/GET-checks every external URL. Slow and
@@ -53,16 +44,31 @@ function extractHeadingsFromContent(content: string): string[] {
return headings;
}
+// Page data differs per source (MDX pages carry toc/getText, OpenAPI pages do
+// not), so the pieces this script walks are parsed instead of guarded by hand.
+const tocEntrySchema = z.object({ url: z.string() });
+const tocPageDataSchema = z.object({ toc: z.array(z.unknown()) });
+const textPageDataSchema = z.object({
+ getText: z.custom<(mode: 'processed' | 'raw') => Promise<string>>(
+ value => typeof value === 'function'
+ ),
+});
+
/**
* Get headings for a page, trying data.toc first then falling back to raw content parsing.
*/
async function getHeadingsForPage(page: PageOf): Promise<string[]> {
- if (page.data.toc?.length) {
- return page.data.toc.map((item: { url: string }) => item.url.slice(1));
+ const tocData = tocPageDataSchema.safeParse(page.data);
+ if (tocData.success && tocData.data.toc.length > 0) {
+ return tocData.data.toc.flatMap(item => {
+ const entry = tocEntrySchema.safeParse(item);
+ return entry.success ? [entry.data.url.slice(1)] : [];
+ });
}
- if ('getText' in page.data) {
+ const textData = textPageDataSchema.safeParse(page.data);
+ if (textData.success) {
try {
- const content = await (page.data as { getText: (mode: string) => Promise<string> }).getText('raw');
+ const content = await textData.data.getText('raw');
return extractHeadingsFromContent(content);
} catch {
// fall through
@@ -87,14 +93,16 @@ async function buildPopulateEntries(src: AnySource) {
src.getPages().map(async (page: PageOf) => ({
value: { slug: page.slugs },
hashes: await getHeadingsForPage(page),
- })),
+ }))
);
}
+const toolkitSlugsSchema = z.array(z.object({ slug: z.string() }));
+
async function getDynamicToolkitEntries() {
const raw = await readFile('public/data/toolkits.json', 'utf-8');
- const toolkits: { slug: string }[] = JSON.parse(raw);
- return toolkits.map((t) => ({ value: { slug: [t.slug] }, hashes: [] as string[] }));
+ const toolkits = toolkitSlugsSchema.parse(JSON.parse(raw));
+ return toolkits.map(t => ({ value: { slug: [t.slug] }, hashes: [] as string[] }));
}
const EXTERNAL_FETCH_HEADERS = {
@@ -160,13 +168,14 @@ function validateExternalUrl(url: URL) {
async function checkLinks() {
const referenceSource = await getReferenceSource();
- const [docsEntries, refEntries, exampleEntries, toolkitEntries, dynamicToolkitEntries] = await Promise.all([
- buildPopulateEntries(source),
- buildPopulateEntries(referenceSource),
- buildPopulateEntries(examplesSource),
- buildPopulateEntries(toolkitsSource),
- getDynamicToolkitEntries(),
- ]);
+ const [docsEntries, refEntries, exampleEntries, toolkitEntries, dynamicToolkitEntries] =
+ await Promise.all([
+ buildPopulateEntries(source),
+ buildPopulateEntries(referenceSource),
+ buildPopulateEntries(examplesSource),
+ buildPopulateEntries(toolkitsSource),
+ getDynamicToolkitEntries(),
+ ]);
const scanned = await scanURLs({
preset: 'next',
@@ -193,12 +202,12 @@ async function checkLinks() {
// Filter out API route URLs (these are valid but not detected as pages)
const ignoredUrls = ['/llms.txt', '/llms-full.txt'];
const filteredErrors = errors
- .map((fileError) => ({
+ .map(fileError => ({
...fileError,
- errors: fileError.errors.filter((e) => !ignoredUrls.includes(e.url)),
- detected: fileError.detected.filter((d) => !ignoredUrls.includes(d[0] as string)),
+ errors: fileError.errors.filter(e => !ignoredUrls.includes(e.url)),
+ detected: fileError.detected.filter(d => !ignoredUrls.includes(d[0] as string)),
}))
- .filter((fileError) => fileError.errors.length > 0);
+ .filter(fileError => fileError.errors.length > 0);
printErrors(filteredErrors, true);
if (filteredErrors.length > 0) {
@@ -217,11 +226,12 @@ async function getFiles(): Promise<FileObject[]> {
if (!page.absolutePath) continue;
if (!page.absolutePath.endsWith('.mdx') && !page.absolutePath.endsWith('.md')) continue;
// Skip OpenAPI-generated pages (they don't have getText)
- if (!('getText' in page.data)) continue;
+ const textData = textPageDataSchema.safeParse(page.data);
+ if (!textData.success) continue;
allFiles.push({
path: page.absolutePath,
- content: await (page.data as { getText: (mode: string) => Promise<string> }).getText('raw'),
+ content: await textData.data.getText('raw'),
url: page.url,
data: page.data,
});
@@ -229,7 +239,7 @@ async function getFiles(): Promise<FileObject[]> {
}
// Scan any .md files under content/ not already covered by Fumadocs sources
- const coveredPaths = new Set(allFiles.map((f) => resolve(f.path)));
+ const coveredPaths = new Set(allFiles.map(f => resolve(f.path)));
const extraMdFiles = await Array.fromAsync(glob('content/**/*.md'));
for (const filePath of extraMdFiles) {
if (coveredPaths.has(resolve(filePath))) continue;
diff --git a/docs/tests/static/generate-toolkits.test.ts b/docs/tests/static/generate-toolkits.test.ts
new file mode 100644
index 000000000..5de1bbf7d
--- /dev/null
+++ b/docs/tests/static/generate-toolkits.test.ts
@@ -0,0 +1,361 @@
+/**
+ * Regression tests for the raw-API-to-Toolkit transformation in
+ * scripts/generate-toolkits.ts.
+ *
+ * The zod-based rewrite of transformToolkit/authConfigFields/
+ * transformAuthConfigField parses raw API payloads leniently and rebuilds the
+ * toolkit catalog field by field, so these tests pin the shapes
+ * public/data/toolkits.json is expected to carry (see toolkit-schema.test.ts
+ * for the sibling API-schema coverage).
+ *
+ * Only the pure transforms are exercised here — fetchToolkits,
+ * fetchToolsForToolkit, fetchTriggersForToolkit, fetchAuthConfigDetails, and
+ * main() all perform network I/O and are intentionally not covered by this
+ * suite.
+ */
+import { describe, test, expect } from "bun:test";
+import {
+ authConfigFields,
+ parseNamedItems,
+ parseToolkitsPage,
+ transformAuthConfigField,
+ transformAuthConfigDetail,
+ transformToolkit,
+} from "../../scripts/generate-toolkits";
+import { transformTool } from "../../scripts/generate-meta-tools";
+
+describe("transformToolkit", () => {
+ test("maps a representative full toolkit object end to end", () => {
+ const toolkit = transformToolkit({
+ slug: "GITHUB",
+ name: "GitHub",
+ description: "toolkit-level description",
+ meta: {
+ logo: "https://logo.example/github.png",
+ description: "meta description wins over toolkit description",
+ categories: [{ name: "dev-tools" }, "productivity"],
+ },
+ auth_schemes: ["OAUTH2", "API_KEY", 123],
+ composio_managed_auth_schemes: ["OAUTH2"],
+ tool_count: 42,
+ trigger_count: 3,
+ });
+
+ expect(toolkit.slug).toBe("github");
+ expect(toolkit.name).toBe("GitHub");
+ expect(toolkit.logo).toBe("https://logo.example/github.png");
+ expect(toolkit.description).toBe("meta description wins over toolkit description");
+ expect(toolkit.category).toBe("dev-tools");
+ expect(toolkit.authSchemes).toEqual(["OAUTH2", "API_KEY"]);
+ expect(toolkit.composioManagedAuthSchemes).toEqual(["OAUTH2"]);
+ expect(toolkit.toolCount).toBe(42);
+ expect(toolkit.triggerCount).toBe(3);
+ expect(toolkit.version).toBeNull();
+ expect(toolkit.tools).toEqual([]);
+ expect(toolkit.triggers).toEqual([]);
+ });
+
+ test("slug is lowercased regardless of API casing", () => {
+ const toolkit = transformToolkit({ slug: "SlAcK" });
+ expect(toolkit.slug).toBe("slack");
+ });
+
+ test("falls back to logo/description/auth_schemes on toolkit root when meta is absent", () => {
+ const toolkit = transformToolkit({
+ slug: "notion",
+ logo: "https://logo.example/notion.png",
+ description: "root description",
+ authSchemes: ["OAUTH2"],
+ composioManagedAuthSchemes: ["OAUTH2"],
+ });
+
+ expect(toolkit.logo).toBe("https://logo.example/notion.png");
+ expect(toolkit.description).toBe("root description");
+ expect(toolkit.authSchemes).toEqual(["OAUTH2"]);
+ expect(toolkit.composioManagedAuthSchemes).toEqual(["OAUTH2"]);
+ });
+
+ test("omits composioManagedAuthSchemes entirely when empty (not an empty array)", () => {
+ const toolkit = transformToolkit({ slug: "test" });
+ expect(toolkit).not.toHaveProperty("composioManagedAuthSchemes");
+ });
+
+ test("empty-string name falls back to the original-casing slug", () => {
+ const toolkit = transformToolkit({ slug: "GitHub", name: "" });
+ expect(toolkit.name).toBe("GitHub");
+ });
+
+ test("missing name falls back to the original-casing slug", () => {
+ const toolkit = transformToolkit({ slug: "GitHub" });
+ expect(toolkit.name).toBe("GitHub");
+ });
+
+ test("empty meta values fall back to root logo and description", () => {
+ const toolkit = transformToolkit({
+ slug: "github",
+ logo: "https://logo.example/github.png",
+ description: "root description",
+ meta: { logo: "", description: "" },
+ });
+
+ expect(toolkit.logo).toBe("https://logo.example/github.png");
+ expect(toolkit.description).toBe("root description");
+ });
+
+ test("non-string tool_count/trigger_count are dropped in favor of the numeric fallback", () => {
+ const toolkit = transformToolkit({
+ slug: "test",
+ tool_count: "42",
+ trigger_count: null,
+ });
+ expect(toolkit.toolCount).toBe(0);
+ expect(toolkit.triggerCount).toBe(0);
+ });
+
+ test("non-string auth_schemes members are filtered out of the array", () => {
+ const toolkit = transformToolkit({
+ slug: "test",
+ auth_schemes: ["OAUTH2", 42, null, "API_KEY", { scheme: "x" }],
+ });
+ expect(toolkit.authSchemes).toEqual(["OAUTH2", "API_KEY"]);
+ });
+
+ test("non-array auth_schemes yields an empty array, never a non-array value", () => {
+ const toolkit = transformToolkit({ slug: "test", auth_schemes: "OAUTH2" });
+ expect(Array.isArray(toolkit.authSchemes)).toBe(true);
+ expect(toolkit.authSchemes).toEqual([]);
+ });
+
+ test("category falls back to null when the first category entry has no string name", () => {
+ const toolkit = transformToolkit({
+ slug: "test",
+ meta: { categories: [{ notName: "x" }] },
+ });
+ expect(toolkit.category).toBeNull();
+ });
+
+ test("category is null when categories is absent or not an array", () => {
+ expect(transformToolkit({ slug: "test" }).category).toBeNull();
+ expect(transformToolkit({ slug: "test", meta: { categories: "dev-tools" } }).category).toBeNull();
+ });
+
+ test("empty category names fall back to null", () => {
+ expect(transformToolkit({ slug: "test", meta: { categories: [""] } }).category).toBeNull();
+ expect(
+ transformToolkit({ slug: "test", meta: { categories: [{ name: "" }] } }).category
+ ).toBeNull();
+ });
+
+ test("malformed/empty input objects do not throw", () => {
+ expect(() => transformToolkit({})).not.toThrow();
+ expect(() => transformToolkit(null)).not.toThrow();
+ expect(() => transformToolkit(undefined)).not.toThrow();
+ expect(() => transformToolkit("not-an-object")).not.toThrow();
+ expect(() => transformToolkit(42)).not.toThrow();
+ expect(() => transformToolkit([])).not.toThrow();
+
+ const toolkit = transformToolkit(null);
+ expect(toolkit.slug).toBe("");
+ expect(toolkit.name).toBe("");
+ expect(toolkit.logo).toBeNull();
+ expect(toolkit.description).toBe("");
+ expect(toolkit.authSchemes).toEqual([]);
+ expect(toolkit.toolCount).toBe(0);
+ expect(toolkit.triggerCount).toBe(0);
+ });
+});
+
+describe("transformAuthConfigField", () => {
+ test("maps a representative required field", () => {
+ const field = transformAuthConfigField(
+ {
+ name: "api_key",
+ displayName: "API Key",
+ type: "string",
+ description: "Your API key",
+ required: true,
+ default: "fallback-value",
+ },
+ false
+ );
+
+ expect(field).toEqual({
+ name: "api_key",
+ displayName: "API Key",
+ type: "string",
+ description: "Your API key",
+ required: true,
+ default: "fallback-value",
+ });
+ });
+
+ test("displayName falls back to name when absent", () => {
+ const field = transformAuthConfigField({ name: "client_id" }, true);
+ expect(field.displayName).toBe("client_id");
+ });
+
+ test("empty displayName falls back to name", () => {
+ const field = transformAuthConfigField({ name: "client_id", displayName: "" }, true);
+ expect(field.displayName).toBe("client_id");
+ });
+
+ test("required falls back to the caller-supplied requirement when the API omits it", () => {
+ const required = transformAuthConfigField({ name: "x" }, true);
+ const optional = transformAuthConfigField({ name: "x" }, false);
+ expect(required.required).toBe(true);
+ expect(optional.required).toBe(false);
+ });
+
+ test("type defaults to 'string' when missing or non-string", () => {
+ expect(transformAuthConfigField({ name: "x" }, false).type).toBe("string");
+ expect(transformAuthConfigField({ name: "x", type: 7 }, false).type).toBe("string");
+ });
+
+ test("scalar defaults are preserved as strings while structured values are dropped", () => {
+ expect(transformAuthConfigField({ name: "x", default: 5 }, false).default).toBe("5");
+ expect(transformAuthConfigField({ name: "x", default: false }, false).default).toBe("false");
+ expect(transformAuthConfigField({ name: "x", default: { a: 1 } }, false).default).toBeNull();
+ expect(transformAuthConfigField({ name: "x", default: ["a"] }, false).default).toBeNull();
+ expect(transformAuthConfigField({ name: "x", default: null }, false).default).toBeNull();
+ expect(transformAuthConfigField({ name: "x" }, false).default).toBeNull();
+ });
+
+ test("malformed/empty input does not throw", () => {
+ expect(() => transformAuthConfigField(null, false)).not.toThrow();
+ expect(() => transformAuthConfigField(undefined, true)).not.toThrow();
+ expect(() => transformAuthConfigField("nope", false)).not.toThrow();
+ expect(() => transformAuthConfigField(42, false)).not.toThrow();
+
+ const field = transformAuthConfigField(null, true);
+ expect(field.name).toBe("");
+ expect(field.displayName).toBe("");
+ expect(field.type).toBe("string");
+ expect(field.description).toBe("");
+ expect(field.required).toBe(true);
+ expect(field.default).toBeNull();
+ });
+});
+
+describe("transformAuthConfigDetail", () => {
+ test("empty names fall back to the auth mode", () => {
+ const detail = transformAuthConfigDetail({ mode: "oauth2", name: "" });
+ expect(detail?.name).toBe("oauth2");
+ });
+
+ test("non-object entries are dropped", () => {
+ expect(transformAuthConfigDetail(null)).toBeNull();
+ expect(transformAuthConfigDetail("oauth2")).toBeNull();
+ });
+});
+
+describe("authConfigFields", () => {
+ const rawAuthConfig = {
+ fields: {
+ auth_config_creation: {
+ required: [{ name: "client_id" }, { name: "client_secret" }],
+ optional: [{ name: "redirect_url" }],
+ },
+ connected_account_initiation: {
+ required: [{ name: "code" }],
+ optional: "not-an-array",
+ },
+ },
+ };
+
+ test("extracts the required/optional field lists for a given phase", () => {
+ const required = authConfigFields(rawAuthConfig, "auth_config_creation", "required");
+ const optional = authConfigFields(rawAuthConfig, "auth_config_creation", "optional");
+
+ expect(required.map(f => f.name)).toEqual(["client_id", "client_secret"]);
+ expect(required.every(f => f.required)).toBe(true);
+ expect(optional.map(f => f.name)).toEqual(["redirect_url"]);
+ expect(optional.every(f => f.required)).toBe(false);
+ });
+
+ test("non-array requirement lists always yield an array, never throwing", () => {
+ const optional = authConfigFields(rawAuthConfig, "connected_account_initiation", "optional");
+ expect(Array.isArray(optional)).toBe(true);
+ expect(optional).toEqual([]);
+ });
+
+ test("malformed/empty input objects do not throw and yield an empty array", () => {
+ expect(() => authConfigFields({}, "auth_config_creation", "required")).not.toThrow();
+ expect(authConfigFields({}, "auth_config_creation", "required")).toEqual([]);
+ expect(authConfigFields({ fields: null }, "auth_config_creation", "required")).toEqual([]);
+ });
+});
+
+// generate-meta-tools.ts's transformTool is a cheap, pure sibling transform
+// built on the same lenient zod parsing; a couple of cases here mirror the
+// coverage above without pulling in createSession/fetchMetaTools (network).
+describe("transformTool (generate-meta-tools.ts)", () => {
+ test("maps a representative full meta tool object end to end", () => {
+ const tool = transformTool({
+ slug: "COMPOSIO_SEARCH_TOOLS",
+ name: "composio_search_tools",
+ description: "Searches for tools",
+ tags: ["discovery", "search", 42],
+ toolkit: "meta",
+ input_parameters: { type: "object" },
+ output_parameters: { type: "object" },
+ });
+
+ expect(tool.slug).toBe("COMPOSIO_SEARCH_TOOLS");
+ expect(tool.name).toBe("composio_search_tools");
+ expect(tool.displayName).toBe("Composio Search Tools");
+ expect(tool.description).toBe("Searches for tools");
+ expect(tool.tags).toEqual(["discovery", "search"]);
+ expect(tool.toolkit).toBe("meta");
+ expect(tool.inputParameters).toEqual({ type: "object" });
+ expect(tool.responseSchema).toEqual({ type: "object" });
+ });
+
+ test("toolkit falls back to null when absent or non-string", () => {
+ expect(transformTool({ slug: "x", name: "x" }).toolkit).toBeNull();
+ expect(transformTool({ slug: "x", name: "x", toolkit: "" }).toolkit).toBeNull();
+ expect(transformTool({ slug: "x", name: "x", toolkit: 7 }).toolkit).toBeNull();
+ });
+
+ test("displayName falls back to the slug when name is empty", () => {
+ const tool = transformTool({ slug: "COMPOSIO_X", name: "" });
+ expect(tool.displayName).toBe("COMPOSIO_X");
+ });
+
+ test("malformed/empty input objects do not throw", () => {
+ expect(() => transformTool({})).not.toThrow();
+ expect(() => transformTool(null)).not.toThrow();
+ expect(() => transformTool(undefined)).not.toThrow();
+
+ const tool = transformTool({});
+ expect(tool.slug).toBe("");
+ expect(tool.name).toBe("");
+ expect(tool.displayName).toBe("");
+ expect(tool.tags).toEqual([]);
+ expect(tool.toolkit).toBeNull();
+ expect(tool.inputParameters).toEqual({});
+ expect(tool.responseSchema).toEqual({});
+ });
+});
+
+describe("parseToolkitsPage", () => {
+ test("rejects malformed page envelopes instead of returning an empty page", () => {
+ expect(() => parseToolkitsPage({ error: "rate limited" })).toThrow();
+ expect(() => parseToolkitsPage({ items: null })).toThrow();
+ expect(() => parseToolkitsPage("not a page")).toThrow();
+ });
+});
+
+describe("parseNamedItems", () => {
+ test("empty names fall back to display names", () => {
+ expect(
+ parseNamedItems([
+ {
+ slug: "GMAIL_SEND_EMAIL",
+ name: "",
+ display_name: "Send email",
+ description: "Sends an email",
+ },
+ ])[0]?.name
+ ).toBe("Send email");
+ });
+});
diff --git a/docs/tests/static/llms-openapi.test.ts b/docs/tests/static/llms-openapi.test.ts
index fb233f48e..2dc3b6930 100644
--- a/docs/tests/static/llms-openapi.test.ts
+++ b/docs/tests/static/llms-openapi.test.ts
@@ -33,9 +33,10 @@ mock.module("@/lib/toolkit-schema", () => ({
}));
let openapiPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").openapiPageToMarkdown;
+let degradedPageToMarkdown: typeof import("../../app/llms.mdx/[[...slug]]/route").degradedPageToMarkdown;
beforeAll(async () => {
- ({ openapiPageToMarkdown } = await import(
+ ({ openapiPageToMarkdown, degradedPageToMarkdown } = await import(
"../../app/llms.mdx/[[...slug]]/route"
));
});
@@ -183,3 +184,14 @@ describe("LLM OpenAPI markdown", () => {
);
});
});
+
+describe("LLM page degradation", () => {
+ test("keeps a readable response when typed page parsing fails", () => {
+ expect(
+ degradedPageToMarkdown({
+ url: "/docs/example",
+ data: { title: 42, description: "Fallback copy" },
+ })
+ ).toBe("# 42 (/docs/example)\n\nFallback copy");
+ });
+});
diff --git a/docs/tests/static/toolkit-schema.test.ts b/docs/tests/static/toolkit-schema.test.ts
new file mode 100644
index 000000000..1e7526ea8
--- /dev/null
+++ b/docs/tests/static/toolkit-schema.test.ts
@@ -0,0 +1,190 @@
+/**
+ * Regression tests for the raw-API-to-ParameterSchema transformation.
+ *
+ * The zod-based rewrite of processSchema/toolFromApi parses raw JSON-Schema
+ * nodes recursively and rebuilds them field by field, so these tests pin the
+ * shapes the toolkit detail UI depends on (toolkit-detail.tsx reads
+ * additionalProperties and items.additionalProperties, including their
+ * nested properties, to synthesize the "[key: string]" row).
+ */
+import { describe, test, expect } from "bun:test";
+import { processSchema, toolFromApi, triggerFromApi } from "../../lib/toolkit-schema";
+
+describe("processSchema", () => {
+ test("dictionary-of-object param keeps nested additionalProperties subschema", () => {
+ const params = processSchema({
+ type: "object",
+ properties: {
+ metadata: {
+ type: "object",
+ additionalProperties: {
+ type: "object",
+ required: ["label"],
+ properties: {
+ label: { type: "string", description: "Display label" },
+ weight: { type: "number" },
+ },
+ },
+ },
+ },
+ });
+
+ const additional = params?.metadata.additionalProperties;
+ expect(additional).toBeDefined();
+ expect(typeof additional).toBe("object");
+ if (typeof additional === "object") {
+ expect(additional.type).toBe("object");
+ expect(additional.requiredFields).toEqual(["label"]);
+ expect(additional.properties?.label.type).toBe("string");
+ expect(additional.properties?.label.description).toBe("Display label");
+ expect(additional.properties?.weight.type).toBe("number");
+ }
+ });
+
+ test("array-of-dictionary param keeps items.additionalProperties", () => {
+ const params = processSchema({
+ type: "object",
+ properties: {
+ rows: {
+ type: "array",
+ items: {
+ type: "object",
+ additionalProperties: { type: "string", description: "cell value" },
+ },
+ },
+ },
+ });
+
+ const itemsAdditional = params?.rows.items?.additionalProperties;
+ expect(itemsAdditional).toBeDefined();
+ expect(typeof itemsAdditional).toBe("object");
+ if (typeof itemsAdditional === "object") {
+ expect(itemsAdditional.type).toBe("string");
+ expect(itemsAdditional.description).toBe("cell value");
+ }
+ });
+
+ test("boolean additionalProperties passes through unchanged", () => {
+ const params = processSchema({
+ type: "object",
+ properties: {
+ strict: { type: "object", additionalProperties: false },
+ },
+ });
+
+ expect(params?.strict.additionalProperties).toBe(false);
+ });
+
+ test("array items keep the required-to-requiredFields remap and nested properties", () => {
+ const params = processSchema({
+ type: "object",
+ required: ["records"],
+ properties: {
+ records: {
+ type: "array",
+ items: {
+ type: "object",
+ required: ["id"],
+ properties: {
+ id: { type: "string" },
+ note: { type: "string" },
+ },
+ },
+ },
+ },
+ });
+
+ expect(params?.records.required).toBe(true);
+ expect(params?.records.items?.requiredFields).toEqual(["id"]);
+ expect(params?.records.items?.properties?.id.type).toBe("string");
+ });
+
+ test("tuple-form items array is not spread into numeric keys", () => {
+ const params = processSchema({
+ type: "object",
+ properties: {
+ pair: { type: "array", items: [{ type: "string" }, { type: "number" }] },
+ },
+ });
+
+ expect(params?.pair.items).toBeUndefined();
+ });
+
+ test("scalar enum values are preserved as strings", () => {
+ const params = processSchema({
+ type: "object",
+ properties: {
+ priority: { type: "integer", enum: [1, 2, 3, true, { invalid: "object" }] },
+ },
+ });
+
+ expect(params?.priority.enum).toEqual(["1", "2", "3", "true"]);
+ });
+
+ test("omits empty enum arrays from the serialized parameter shape", () => {
+ const params = processSchema({
+ type: "object",
+ properties: { query: { type: "string" } },
+ });
+
+ expect(params?.query.enum).toBeUndefined();
+ expect(JSON.stringify(params?.query)).not.toContain('"enum"');
+ });
+});
+
+describe("toolFromApi", () => {
+ test("maps slug fallback and nested schemas end to end", () => {
+ const tool = toolFromApi({
+ slug: "TEST_TOOL",
+ description: "A test tool",
+ input_parameters: {
+ type: "object",
+ properties: {
+ config: {
+ type: "object",
+ additionalProperties: {
+ type: "object",
+ properties: { enabled: { type: "boolean" } },
+ },
+ },
+ },
+ },
+ });
+
+ expect(tool.name).toBe("TEST_TOOL");
+ const additional = tool.input_parameters?.config.additionalProperties;
+ expect(typeof additional).toBe("object");
+ if (typeof additional === "object") {
+ expect(additional.properties?.enabled.type).toBe("boolean");
+ }
+ });
+
+ test("empty names fall back to display names", () => {
+ expect(
+ toolFromApi({
+ slug: "TEST_TOOL",
+ name: "",
+ display_name: "Test tool",
+ description: "A test tool",
+ }).name
+ ).toBe("Test tool");
+
+ expect(
+ triggerFromApi({
+ slug: "TEST_TRIGGER",
+ name: "",
+ display_name: "Test trigger",
+ description: "A test trigger",
+ }).name
+ ).toBe("Test trigger");
+ });
+
+ test("omits empty scope and tag arrays from the serialized tool shape", () => {
+ const tool = toolFromApi({ slug: "TEST_TOOL" });
+
+ expect(tool.scopes).toBeUndefined();
+ expect(tool.tags).toBeUndefined();
+ expect(JSON.stringify(tool)).not.toContain('"scopes"');
+ expect(JSON.stringify(tool)).not.toContain('"tags"');
+ });
+});