Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 1,435 lines 51.2 KB
Raw
1 import { instantDiscount, instantPricingDescription, toolkitSupportsInstant } from '@/lib/instant';
2 import {
3 source,
4 getReferenceSource,
5 examplesSource,
6 toolkitsSource,
7 knowledgeBaseSource,
8 changelogEntries,
9 slugToDate,
10 formatDate,
11 getLLMText,
12 mdxToCleanMarkdown,
13 type LLMPage,
14 } from '@/lib/source';
15 import { dereferenceDocument } from '@/lib/openapi-deref';
16 import {
17 REST_VERSION_GUIDANCE,
18 TOOL_VERSION_GUIDANCE,
19 apiVersionPointer,
20 isToolVersionPath,
21 toolVersionParameterDescription,
22 } from '@/lib/api-version-guidance';
23 import { getPageLastUpdated } from '@/lib/content-freshness';
24 import { missingMarkdownResponse, withMarkdownMetadata } from '@/lib/markdown-response';
25 import { readFile } from 'fs/promises';
26 import { join } from 'path';
27 import { getAllToolkits, getToolkitBySlug } from '@/lib/toolkit-data';
28 import { getAllMetaTools, getMetaToolBySlug } from '@/lib/meta-tools-data';
29 import { encodeMarkdownTableCell } from '@/lib/markdown-escaping';
30 import type { MetaTool, MetaToolParameter } from '@/lib/meta-tools-data';
31 import type { Toolkit, Tool, Trigger, ParameterSchema } from '@/types/toolkit';
32 import { apiToolListSchema, apiTriggerListSchema } from '@/lib/toolkit-schema';
33 import {
34 createComposioClientFromEnv,
35 LIVE_TRAVERSAL_TIMEOUT_MS,
36 listToolkitTools,
37 listToolkitTriggers,
38 } from '@/lib/composio-api';
39 import { z } from 'zod';
40 import {
41 getKnowledgeByProductArea,
42 getKnowledgeByToolkit,
43 getKnowledgeToolkitSummaries,
44 type KnowledgeLink,
45 } from '@/lib/knowledge/catalog';
46 import { getProductArea, isProductAreaSlug, PRODUCT_AREAS } from '@/lib/knowledge/taxonomy';
47 import {
48 getToolkitKnowledgeMarkdownHref,
49 getToolkitKnowledgeRedirect,
50 } from '@/lib/knowledge/toolkit-routing';
51
52 export const revalidate = false;
53
54 // COMPOSIO_BASE_URL selects the API host; production by default.
55 const client = process.env.COMPOSIO_API_KEY
56 ? createComposioClientFromEnv(process.env, { revalidate: 3600 })
57 : null;
58
59 // Fetch detailed tool info from Composio API
60 async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
61 if (!client) {
62 return null;
63 }
64
65 try {
66 return apiToolListSchema.parse(await listToolkitTools(client, toolkitSlug, { signal: AbortSignal.timeout(LIVE_TRAVERSAL_TIMEOUT_MS) }));
67 } catch (error) {
68 console.warn(`[LLM Markdown] Failed to fetch tools for ${toolkitSlug}:`, error);
69 return null;
70 }
71 }
72
73 // Fetch detailed trigger info from Composio API
74 async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | null> {
75 if (!client) {
76 return null;
77 }
78
79 try {
80 return apiTriggerListSchema.parse(await listToolkitTriggers(client, toolkitSlug, { signal: AbortSignal.timeout(LIVE_TRAVERSAL_TIMEOUT_MS) }));
81 } catch (error) {
82 console.warn(`[LLM Markdown] Failed to fetch triggers for ${toolkitSlug}:`, error);
83 return null;
84 }
85 }
86
87 // Types for OpenAPI structures (from dereferenced document)
88 interface OpenAPISchema {
89 type?: string;
90 format?: string;
91 description?: string;
92 properties?: Record<string, OpenAPISchema>;
93 items?: OpenAPISchema;
94 required?: string[];
95 enum?: string[];
96 oneOf?: OpenAPISchema[];
97 anyOf?: OpenAPISchema[];
98 allOf?: OpenAPISchema[];
99 default?: unknown;
100 example?: unknown;
101 minimum?: number;
102 maximum?: number;
103 minLength?: number;
104 maxLength?: number;
105 additionalProperties?: OpenAPISchema | boolean;
106 }
107
108 interface OpenAPIParameter {
109 name: string;
110 in: 'query' | 'path' | 'header' | 'cookie';
111 description?: string;
112 required?: boolean;
113 schema?: OpenAPISchema;
114 example?: unknown;
115 }
116
117 interface OpenAPIRequestBody {
118 description?: string;
119 required?: boolean;
120 content?: Record<string, { schema?: OpenAPISchema; example?: unknown }>;
121 }
122
123 interface OpenAPIResponse {
124 description?: string;
125 content?: Record<string, { schema?: OpenAPISchema; example?: unknown }>;
126 }
127
128 interface OpenAPISecurityScheme {
129 type: string;
130 description?: string;
131 name?: string;
132 in?: string;
133 scheme?: string;
134 bearerFormat?: string;
135 }
136
137 interface OpenAPIOperation {
138 summary?: string;
139 description?: string;
140 operationId?: string;
141 parameters?: OpenAPIParameter[];
142 requestBody?: OpenAPIRequestBody;
143 responses?: Record<string, OpenAPIResponse>;
144 security?: Array<Record<string, string[]>>;
145 tags?: string[];
146 }
147
148 interface OpenAPIPageData {
149 title: string;
150 description?: string;
151 getOpenAPIPageProps: () => {
152 payload: { bundled: Record<string, unknown> };
153 operations?: Array<{ method: string; path: string; tags?: string[] }>;
154 webhooks?: Array<{ name: string; method: string }>;
155 };
156 }
157
158 // Fumadocs page data is untyped across the mixed sources this route serves, so
159 // each candidate page is parsed once against the shape its renderer needs.
160 const openAPIPageSchema = z.object({
161 url: z.string(),
162 data: z.object({
163 title: z.string(),
164 description: z.string().optional().catch(undefined),
165 getOpenAPIPageProps: z.custom<OpenAPIPageData['getOpenAPIPageProps']>(
166 value => typeof value === 'function'
167 ),
168 }),
169 });
170
171 const llmPageSchema: z.ZodType<LLMPage> = z.object({
172 url: z.string(),
173 data: z.object({
174 title: z.string(),
175 description: z.string().optional().catch(undefined),
176 getText: z
177 .custom<NonNullable<LLMPage['data']['getText']>>(value => typeof value === 'function')
178 .optional()
179 .catch(undefined),
180 legacy: z.boolean().optional().catch(undefined),
181 written: z.string().optional().catch(undefined),
182 llmGuardrails: z.enum(['direct-execution', 'none']).optional().catch(undefined),
183 }),
184 });
185
186 const degradedPageSchema = z.object({
187 url: z.unknown().optional(),
188 data: z
189 .object({
190 title: z.unknown().optional(),
191 description: z.unknown().optional(),
192 })
193 .catch({}),
194 });
195
196 export function degradedPageToMarkdown(value: unknown): string | null {
197 const parsed = degradedPageSchema.safeParse(value);
198 if (!parsed.success) return null;
199
200 const title = parsed.data.data.title || 'Documentation';
201 const description = parsed.data.data.description || '';
202 const url = parsed.data.url || '';
203 return `# ${String(title)} (${String(url)})\n\n${String(description)}`;
204 }
205
206 // Generate sample value for a schema
207 function generateSampleValue(schema: OpenAPISchema, depth = 0): unknown {
208 if (depth > 3) return '...'; // Prevent infinite recursion
209
210 if (schema.example !== undefined) return schema.example;
211 if (schema.default !== undefined) return schema.default;
212 if (schema.enum && schema.enum.length > 0) return schema.enum[0];
213 const alternatives = schema.oneOf ?? schema.anyOf;
214 if (alternatives?.length) {
215 // An alternative applies alongside its parent, so merge it instead of
216 // discarding the parent's type and properties. Unions can be circular.
217 const { oneOf: _oneOf, anyOf: _anyOf, ...parent } = schema;
218 const alternative = alternatives[0];
219 const properties = parent.properties || alternative.properties
220 ? { ...parent.properties, ...alternative.properties }
221 : undefined;
222 return generateSampleValue({ ...parent, ...alternative, properties }, depth + 1);
223 }
224
225 switch (schema.type) {
226 case 'string':
227 if (schema.format === 'email') return 'user@example.com';
228 if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com';
229 if (schema.format === 'date') return '2024-01-15';
230 if (schema.format === 'date-time') return '2024-01-15T10:30:00Z';
231 if (schema.format === 'uuid') return '550e8400-e29b-41d4-a716-446655440000';
232 return 'string';
233 case 'integer':
234 case 'number':
235 return schema.minimum ?? 1;
236 case 'boolean':
237 return true;
238 case 'array':
239 if (schema.items) {
240 return [generateSampleValue(schema.items, depth + 1)];
241 }
242 return [];
243 case 'object':
244 if (schema.properties) {
245 const obj: Record<string, unknown> = {};
246 for (const [key, prop] of Object.entries(schema.properties)) {
247 obj[key] = generateSampleValue(prop, depth + 1);
248 }
249 if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
250 obj['key'] = generateSampleValue(schema.additionalProperties, depth + 1);
251 }
252 return obj;
253 }
254 if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
255 return { key: generateSampleValue(schema.additionalProperties, depth + 1) };
256 }
257 return {};
258 default:
259 return null;
260 }
261 }
262
263 /**
264 * Renders object properties, dictionaries, and composed schemas as nested
265 * Markdown list items.
266 *
267 * `indent` controls the emitted list indentation, while `depth` independently
268 * tracks recursion because `allOf` expands without increasing indentation. An
269 * ellipsis is emitted when either value exceeds `maxDepth`.
270 */
271 function renderSchema(schema: OpenAPISchema, indent = 0, maxDepth = 4, depth = 0): string[] {
272 if (indent > maxDepth || depth > maxDepth) {
273 return [' '.repeat(indent) + '- ...'];
274 }
275
276 const lines: string[] = [];
277 const prefix = ' '.repeat(indent);
278 const required = schema.required || [];
279
280 if (
281 schema.type === 'object' &&
282 (schema.properties ||
283 (schema.additionalProperties && typeof schema.additionalProperties === 'object'))
284 ) {
285 if (schema.properties) {
286 for (const [name, prop] of Object.entries(schema.properties)) {
287 const isRequired = required.includes(name);
288 const reqMark = isRequired ? ' *(required)*' : '';
289 const typeStr = getTypeString(prop);
290 const desc = prop.description ? `: ${prop.description}` : '';
291
292 lines.push(`${prefix}- \`${name}\` (${typeStr})${reqMark}${desc}`);
293
294 // Recurse for nested objects/arrays
295 if (
296 prop.type === 'object' &&
297 (prop.properties ||
298 (prop.additionalProperties && typeof prop.additionalProperties === 'object'))
299 ) {
300 lines.push(...renderSchema(prop, indent + 1, maxDepth, depth + 1));
301 } else if (
302 prop.type === 'array' &&
303 prop.items?.type === 'object' &&
304 (prop.items.properties ||
305 (prop.items.additionalProperties &&
306 typeof prop.items.additionalProperties === 'object'))
307 ) {
308 lines.push(`${prefix} - Array items:`);
309 lines.push(...renderSchema(prop.items, indent + 2, maxDepth, depth + 1));
310 }
311 }
312 }
313
314 // Render additionalProperties as [key: string]
315 if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
316 const ap = schema.additionalProperties;
317 const typeStr = getTypeString(ap);
318 const desc = ap.description ? `: ${ap.description}` : '';
319 lines.push(`${prefix}- \`[key: string]\` (${typeStr})${desc}`);
320 if (
321 ap.type === 'object' &&
322 (ap.properties || (ap.additionalProperties && typeof ap.additionalProperties === 'object'))
323 ) {
324 lines.push(...renderSchema(ap, indent + 1, maxDepth, depth + 1));
325 } else if (
326 ap.type === 'array' &&
327 ap.items?.type === 'object' &&
328 (ap.items.properties ||
329 (ap.items.additionalProperties && typeof ap.items.additionalProperties === 'object'))
330 ) {
331 lines.push(`${prefix} - Array items:`);
332 lines.push(...renderSchema(ap.items, indent + 2, maxDepth, depth + 1));
333 }
334 }
335 } else if (schema.oneOf || schema.anyOf) {
336 const variants = schema.oneOf || schema.anyOf || [];
337 lines.push(`${prefix}*One of:*`);
338 for (const variant of variants.slice(0, 3)) {
339 if (variant.type === 'object' && variant.properties) {
340 lines.push(...renderSchema(variant, indent + 1, maxDepth, depth + 1));
341 } else {
342 lines.push(`${prefix} - ${getTypeString(variant)}`);
343 }
344 }
345 if (variants.length > 3) {
346 lines.push(`${prefix} - ... and ${variants.length - 3} more`);
347 }
348 } else if (schema.allOf) {
349 for (const part of schema.allOf) {
350 if (part.type === 'object' && part.properties) {
351 lines.push(...renderSchema(part, indent, maxDepth, depth + 1));
352 }
353 }
354 }
355
356 return lines;
357 }
358
359 /** Overrides only the top-level request-body version field for affected tool operations. */
360 function withToolVersionDescription(rawSpecPath: string, schema: OpenAPISchema): OpenAPISchema {
361 const versionProperty = schema.properties?.version;
362 if (!versionProperty || !isToolVersionPath(rawSpecPath)) return schema;
363
364 return {
365 ...schema,
366 properties: {
367 ...schema.properties,
368 version: {
369 ...versionProperty,
370 description: toolVersionParameterDescription(rawSpecPath, versionProperty.description),
371 },
372 },
373 };
374 }
375
376 // Get a readable type string
377 function getTypeString(schema: OpenAPISchema, depth = 0, maxDepth = 4): string {
378 if (depth > maxDepth) return '...';
379
380 if (schema.enum) {
381 return `enum: ${schema.enum
382 .slice(0, 3)
383 .map(e => `"${e}"`)
384 .join(' | ')}${schema.enum.length > 3 ? ' | ...' : ''}`;
385 }
386 if (schema.type === 'array' && schema.items) {
387 return `array<${getTypeString(schema.items, depth + 1, maxDepth)}>`;
388 }
389 if (schema.format) {
390 return `${schema.type} (${schema.format})`;
391 }
392 return schema.type || 'any';
393 }
394
395 // Generate equivalent raw HTTP examples from the same URL, headers, and JSON body.
396 function generateRequestExamples(
397 method: string,
398 path: string,
399 baseUrl: string,
400 parameters: OpenAPIParameter[] = [],
401 requestBody?: OpenAPIRequestBody,
402 authHeaders: { name: string; env: string }[] = [],
403 ): Record<'Python' | 'TypeScript' | 'API', string> {
404 // Build path with sample values
405 let url = path;
406 const queryParams: string[] = [];
407
408 for (const param of parameters) {
409 const sample = param.example ?? generateSampleValue(param.schema || { type: 'string' });
410 if (param.in === 'path') {
411 url = url.replace(`{${param.name}}`, String(sample));
412 } else if (param.in === 'query' && param.required) {
413 queryParams.push(`${param.name}=${encodeURIComponent(String(sample))}`);
414 }
415 }
416
417 if (queryParams.length > 0) {
418 url += '?' + queryParams.join('&');
419 }
420
421 let curl = `curl -X ${method.toUpperCase()} "${baseUrl}${url}"`;
422 for (const header of authHeaders) curl += ` \\\n -H "${header.name}: $${header.env}"`;
423
424 const headers: Record<string, string> = {};
425 let body: unknown;
426 // Add request body
427 if (requestBody?.content?.['application/json']) {
428 curl += ` \\\n -H "Content-Type: application/json"`;
429 const schema = requestBody.content['application/json'].schema;
430 const example = requestBody.content['application/json'].example;
431 body = example ?? (schema ? generateSampleValue(schema) : {});
432 curl += ` \\\n -d '${JSON.stringify(body, null, 2).replaceAll("'", "'\\''").split('\n').join('\n ')}'`;
433 headers['Content-Type'] = 'application/json';
434 }
435
436 const python = [
437 'import os',
438 'import requests',
439 ...(body === undefined ? [] : ['import json']),
440 '',
441 `response = requests.request(${JSON.stringify(method.toUpperCase())}, ${JSON.stringify(baseUrl + url)},`,
442 ` headers={${[...Object.entries(headers).map(([name, value]) => `${JSON.stringify(name)}: ${JSON.stringify(value)}`), ...authHeaders.map((header) => `${JSON.stringify(header.name)}: os.environ[${JSON.stringify(header.env)}]`)].join(', ')}}${body === undefined ? ')' : ','}`,
443 ...(body === undefined ? [] : [` json=json.loads(${JSON.stringify(JSON.stringify(body))}))`]),
444 'response.raise_for_status()',
445 'print(response.text)',
446 ].join('\n');
447 const typescript = [
448 `const response = await fetch(${JSON.stringify(baseUrl + url)}, {`,
449 ` method: ${JSON.stringify(method.toUpperCase())},`,
450 ` headers: { ${[...Object.entries(headers).map(([name, value]) => `${JSON.stringify(name)}: ${JSON.stringify(value)}`), ...authHeaders.map((header) => `${JSON.stringify(header.name)}: process.env[${JSON.stringify(header.env)}]!`)].join(', ')} },`,
451 ...(body === undefined ? [] : [` body: JSON.stringify(${JSON.stringify(body, null, 2)}),`]),
452 '});',
453 'if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);',
454 'console.log(await response.text());',
455 ].join('\n');
456 return { Python: python, TypeScript: typescript, API: curl };
457 }
458
459 // Convert OpenAPI page to comprehensive markdown
460 export async function openapiPageToMarkdown(page: {
461 url: string;
462 data: OpenAPIPageData;
463 }): Promise<string> {
464 const { title, description } = page.data;
465 const props = page.data.getOpenAPIPageProps();
466
467 // The renderers read schema fields directly, so inline local references first.
468 const spec = dereferenceDocument(props.payload.bundled);
469 const paths = spec.paths as Record<string, Record<string, OpenAPIOperation>> | undefined;
470 const webhooks = spec.webhooks as Record<string, Record<string, OpenAPIOperation>> | undefined;
471 const securitySchemes = (spec.components as Record<string, unknown>)?.securitySchemes as
472 Record<string, OpenAPISecurityScheme> | undefined;
473 const servers = spec.servers as Array<{ url: string; description?: string }> | undefined;
474 const baseUrl = servers?.[0]?.url || 'https://backend.composio.dev';
475
476 const lines: string[] = [`# ${title}`, ''];
477 lines.push(`**Documentation:** ${page.url}`, '');
478
479 // Which REST version this page documents, emitted above the `**Endpoint:**`
480 // line below so a truncating reader still sees it. These pages publish a
481 // complete working curl example and never touch mdxToCleanMarkdown, so
482 // without this the strongest v3 signal in the corpus stays unlabelled.
483 const versionPointer = apiVersionPointer(page.url);
484 if (versionPointer) {
485 lines.push(versionPointer.trim(), '');
486 }
487
488 if (description) {
489 lines.push(description, '');
490 }
491
492 const selectedOperations: Array<{
493 method: string;
494 name: string;
495 operation: OpenAPIOperation;
496 isWebhook: boolean;
497 }> = [];
498
499 for (const op of props.operations ?? []) {
500 const operation = paths?.[op.path]?.[op.method.toLowerCase()];
501 if (operation) {
502 selectedOperations.push({
503 method: op.method,
504 name: op.path,
505 operation,
506 isWebhook: false,
507 });
508 }
509 }
510
511 for (const webhook of props.webhooks ?? []) {
512 const operation = webhooks?.[webhook.name]?.[webhook.method.toLowerCase()];
513 if (operation) {
514 selectedOperations.push({
515 method: webhook.method,
516 name: webhook.name,
517 operation,
518 isWebhook: true,
519 });
520 }
521 }
522
523 // Process API operations and webhook deliveries through the same schema
524 // renderer. Fumadocs exposes them as separate page-prop collections.
525 for (const selected of selectedOperations) {
526 const { method, name, operation, isWebhook } = selected;
527 lines.push('---', '');
528 lines.push(`## ${method.toUpperCase()} \`${name}\``, '');
529 if (isWebhook) {
530 lines.push(`**Event type:** \`${name}\``, '');
531 } else {
532 lines.push(`**Endpoint:** \`${baseUrl}${name}\``, '');
533 }
534
535 if (operation.summary) {
536 lines.push(`**Summary:** ${operation.summary}`, '');
537 }
538
539 if (operation.description) {
540 lines.push(operation.description, '');
541 }
542
543 // Authentication
544 const security = operation.security;
545 if (security && security.length > 0 && securitySchemes) {
546 lines.push('### Authentication', '');
547 const authMethods: string[] = [];
548 for (const secReq of security) {
549 for (const schemeName of Object.keys(secReq)) {
550 const scheme = securitySchemes[schemeName];
551 if (scheme) {
552 if (scheme.type === 'apiKey') {
553 authMethods.push(
554 `**${schemeName}** - API Key in \`${scheme.in}\` header \`${scheme.name}\``
555 );
556 } else if (scheme.type === 'http' && scheme.scheme === 'bearer') {
557 authMethods.push(`**${schemeName}** - Bearer token in Authorization header`);
558 } else {
559 authMethods.push(`**${schemeName}** - ${scheme.type}`);
560 }
561 }
562 }
563 }
564 lines.push(authMethods.join(' OR '), '');
565 }
566
567 // Path Parameters
568 const pathParams = operation.parameters?.filter(p => p.in === 'path') || [];
569 if (pathParams.length > 0) {
570 lines.push('### Path Parameters', '');
571 for (const param of pathParams) {
572 const typeStr = getTypeString(param.schema || { type: 'string' });
573 lines.push(`- \`${param.name}\` (${typeStr}) *(required)*: ${param.description || ''}`);
574 }
575 lines.push('');
576 }
577
578 // Query Parameters
579 const queryParams = operation.parameters?.filter(p => p.in === 'query') || [];
580 if (queryParams.length > 0) {
581 lines.push('### Query Parameters', '');
582 for (const param of queryParams) {
583 const typeStr = getTypeString(param.schema || { type: 'string' });
584 const reqMark = param.required ? ' *(required)*' : '';
585 const description =
586 (param.name === 'version' || param.name === 'toolkit_versions') &&
587 isToolVersionPath(name)
588 ? toolVersionParameterDescription(name, param.description)
589 : param.description || '';
590 lines.push(`- \`${param.name}\` (${typeStr})${reqMark}: ${description}`);
591 }
592 lines.push('');
593 }
594
595 // Webhook delivery headers
596 const headerParams = operation.parameters?.filter(p => p.in === 'header') || [];
597 if (isWebhook && headerParams.length > 0) {
598 lines.push('### Delivery Headers', '');
599 for (const param of headerParams) {
600 const typeStr = getTypeString(param.schema || { type: 'string' });
601 const reqMark = param.required ? ' *(required)*' : '';
602 lines.push(`- \`${param.name}\` (${typeStr})${reqMark}: ${param.description || ''}`);
603 }
604 lines.push('');
605 }
606
607 // Request Body
608 if (operation.requestBody?.content?.['application/json']) {
609 lines.push('### Request Body', '');
610 if (operation.requestBody.description) {
611 lines.push(operation.requestBody.description, '');
612 }
613 const schema = operation.requestBody.content['application/json'].schema;
614 if (schema) {
615 const renderedSchema = withToolVersionDescription(name, schema);
616 lines.push('**Schema:**', '');
617 lines.push(...renderSchema(renderedSchema));
618 lines.push('');
619
620 // Example
621 const example =
622 operation.requestBody.content['application/json'].example ?? generateSampleValue(schema);
623 lines.push('**Example:**', '');
624 lines.push('```json');
625 lines.push(JSON.stringify(example, null, 2));
626 lines.push('```', '');
627 }
628 }
629
630 // Responses
631 if (operation.responses) {
632 lines.push('### Responses', '');
633
634 for (const [status, response] of Object.entries(operation.responses)) {
635 lines.push(`#### ${status} - ${response.description || ''}`, '');
636
637 const jsonContent = response.content?.['application/json'];
638 if (jsonContent?.schema) {
639 lines.push('**Response Schema:**', '');
640 lines.push(...renderSchema(jsonContent.schema));
641 lines.push('');
642
643 // Only show example for success responses
644 if (status.startsWith('2')) {
645 const example = jsonContent.example ?? generateSampleValue(jsonContent.schema);
646 if (example && Object.keys(example as object).length > 0) {
647 lines.push('**Example Response:**', '');
648 lines.push('```json');
649 lines.push(JSON.stringify(example, null, 2));
650 lines.push('```', '');
651 }
652 }
653 }
654 }
655 }
656
657 // Webhook operations describe inbound deliveries rather than API calls.
658 if (!isWebhook) {
659 const requirement = operation.security?.find((alternative) => Object.keys(alternative).every((key) => {
660 if (key === 'no_auth') return true;
661 const scheme = securitySchemes?.[key];
662 return scheme?.type === 'apiKey' && scheme.in === 'header' && Boolean(scheme.name);
663 }));
664 if (operation.security?.length && !requirement) throw new Error(`Unsupported request-example authentication for ${method} ${name}`);
665 const authHeaders = Object.keys(requirement ?? {}).filter((key) => key !== 'no_auth').map((key) => {
666 const header = securitySchemes![key].name!;
667 return { name: header, env: header.toUpperCase().replace(/^X-/, 'COMPOSIO_').replaceAll('-', '_') };
668 });
669 lines.push('### Example requests', '', 'Python uses `requests`; TypeScript uses Node.js fetch. Replace sample IDs and values before sending these requests.', '');
670 if (authHeaders.length) lines.push(`Set ${authHeaders.map((header) => `\`${header.env}\``).join(', ')} before running these requests.`, '');
671 const examples = generateRequestExamples(method, name, baseUrl, operation.parameters, operation.requestBody, authHeaders);
672 for (const [label, language] of [['Python', 'python'], ['TypeScript', 'typescript'], ['API', 'bash']] as const) {
673 lines.push(`#### ${label}`, '', `\`\`\`${language}`, examples[label], '```', '');
674 }
675 }
676 }
677
678 // Guidance goes after the operation body. Operation pages deliberately do
679 // NOT receive SESSION_GUARDRAILS: that block is about SDK code generation,
680 // it would be noise on a REST operation page, and — because it composes
681 // TOOL_VERSION_GUIDANCE — it would force the tool-version text onto every
682 // operation regardless of scope.
683 //
684 // The baseline applies to every operation. The tool-version note applies to
685 // exactly the five endpoints whose version default changes, decided by
686 // isToolVersionPath on the RAW spec path key (`/api/v3.1/tools/{tool_slug}`)
687 // — normalization belongs to the predicate, so nothing is stripped here and
688 // nothing keys off the page URL.
689 if (selectedOperations.length > 0) {
690 lines.push('---', '', REST_VERSION_GUIDANCE);
691 if (selectedOperations.some(selected => isToolVersionPath(selected.name))) {
692 lines.push('', TOOL_VERSION_GUIDANCE);
693 }
694 }
695
696 return lines.join('\n').trim();
697 }
698
699 // Map URL prefixes to their sources
700 // Note: 'reference' is handled specially below with async getReferenceSource()
701 interface PageSource {
702 getPage(slugs: string[] | undefined): unknown;
703 }
704
705 const sources: Array<{ prefix: string; source: PageSource }> = [
706 { prefix: 'docs', source },
707 { prefix: 'kb', source: knowledgeBaseSource },
708 { prefix: 'examples', source: examplesSource },
709 { prefix: 'toolkits', source: toolkitsSource },
710 ];
711
712 /**
713 * Generate a changelog index with links to all changelog entries.
714 */
715 function generateChangelogIndex(): string {
716 // Group entries by date and sort by date descending (newest first)
717 const entriesByDate = new Map<string, typeof changelogEntries>();
718
719 for (const entry of changelogEntries) {
720 const existing = entriesByDate.get(entry.date) || [];
721 entriesByDate.set(entry.date, [...existing, entry]);
722 }
723
724 const sortedDates = Array.from(entriesByDate.keys()).sort((a, b) => b.localeCompare(a));
725
726 const lines: string[] = [
727 '# Changelog',
728 '',
729 'All updates and announcements for Composio.',
730 '',
731 '| Date | Updates |',
732 '|------|---------|',
733 ];
734
735 for (const date of sortedDates) {
736 const entries = entriesByDate.get(date) || [];
737 const [year, month, day] = date.split('-');
738 const mdUrl = `https://docs.composio.dev/docs/changelog/${year}/${month}/${day}.md`;
739 const formattedDate = formatDate(date);
740 const titles = entries.map(e => e.title).join(', ');
741 lines.push(`| [${formattedDate}](${mdUrl}) | ${titles} |`);
742 }
743
744 lines.push('');
745 lines.push('---');
746 lines.push('');
747 lines.push('For the full changelog with details, visit each date above.');
748
749 return lines.join('\n');
750 }
751
752 /**
753 * Generate markdown for changelog entries matching a specific date.
754 * Multiple entries on the same date are combined into one document.
755 */
756 async function changelogToMarkdown(dateStr: string): Promise<string | null> {
757 const matchingEntries = changelogEntries.filter(entry => entry.date === dateStr);
758
759 if (matchingEntries.length === 0) {
760 return null;
761 }
762
763 const formattedDate = formatDate(dateStr);
764 const lines: string[] = [
765 `# Changelog - ${formattedDate}`,
766 '',
767 `**Documentation:** https://docs.composio.dev/docs/changelog/${dateStr.replace(/-/g, '/')}`,
768 '',
769 ];
770
771 for (const entry of matchingEntries) {
772 lines.push(`## ${entry.title}`, '');
773
774 if (entry.description) {
775 lines.push(entry.description, '');
776 }
777
778 // Try to get the processed text if available
779 if (typeof entry.getText === 'function') {
780 try {
781 const text = await entry.getText('processed');
782 if (text) {
783 lines.push(mdxToCleanMarkdown(text), '');
784 }
785 } catch {
786 // getText not available, try raw
787 try {
788 const text = await entry.getText('raw');
789 if (text) {
790 lines.push(mdxToCleanMarkdown(text), '');
791 }
792 } catch {
793 // No text available, just use title/description
794 }
795 }
796 }
797
798 lines.push('---', '');
799 }
800
801 return lines.join('\n').trim();
802 }
803
804 // Format parameter type with enum values if available
805 function formatParamType(param: ParameterSchema): string {
806 let typeStr = param.type || 'string';
807 if (param.enum && param.enum.length > 0) {
808 const enumValues = param.enum.map(v => `"${v}"`).join(' | ');
809 typeStr = `${typeStr} (${enumValues})`;
810 }
811 return typeStr;
812 }
813
814 // Render parameters as markdown table
815 function renderParamsMarkdown(params: Record<string, ParameterSchema>): string[] {
816 const lines: string[] = [];
817 lines.push('| Parameter | Type | Required | Description |');
818 lines.push('|-----------|------|----------|-------------|');
819
820 for (const [name, param] of Object.entries(params)) {
821 const typeStr = formatParamType(param);
822 const required = param.required ? 'Yes' : 'No';
823 const desc = encodeMarkdownTableCell(param.description || '');
824 lines.push(`| \`${name}\` | ${typeStr} | ${required} | ${desc} |`);
825 }
826
827 return lines;
828 }
829
830 // Read FAQ markdown for a toolkit (returns raw markdown or null)
831 async function readToolkitFaqMarkdown(slug: string): Promise<string | null> {
832 try {
833 const filePath = join(process.cwd(), 'content/toolkits/faq', `${slug}.md`);
834 return await readFile(filePath, 'utf-8');
835 } catch {
836 return null;
837 }
838 }
839
840 // Generate markdown from toolkit with detailed tools and triggers
841 function toolkitToMarkdown(
842 toolkit: Toolkit,
843 detailedTools?: Tool[],
844 detailedTriggers?: Trigger[],
845 faqMarkdown?: string | null
846 ): string {
847 const tools = detailedTools || toolkit.tools;
848 const triggers = detailedTriggers || toolkit.triggers;
849
850 const lines: string[] = [
851 `# ${toolkit.name.trim()}`,
852 '',
853 toolkit.description,
854 '',
855 `- **Category:** ${toolkit.category || 'Uncategorized'}`,
856 `- **Auth:** ${toolkit.authSchemes.join(', ') || 'None'}`,
857 `- **Composio-managed OAuth available?** ${
858 toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
859 ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
860 ? 'Yes'
861 : 'No'
862 : 'N/A'
863 }`,
864 `- **Tools:** ${toolkit.toolCount}`,
865 `- **Triggers:** ${toolkit.triggerCount}`,
866 `- **Slug:** \`${toolkit.slug.toUpperCase()}\``,
867 ];
868
869 if (toolkit.version) {
870 lines.push(`- **Version:** ${toolkit.version}`);
871 }
872
873 if (toolkitSupportsInstant(toolkit.instant, tools)) {
874 lines.push('- **Instant:** Supported on the latest version. Support varies by tool.');
875 }
876
877 if (faqMarkdown && faqMarkdown.trim()) {
878 lines.push('', '## Frequently Asked Questions', '');
879 // Bump ## headings to ### so FAQ questions are children of the FAQ section
880 lines.push(faqMarkdown.trim().replace(/^## /gm, '### '));
881 }
882
883 if (tools.length > 0) {
884 lines.push('', '## Tools', '');
885 for (const tool of tools) {
886 lines.push(`### ${tool.name}`, '');
887 lines.push(`**Slug:** \`${tool.slug}\``, '');
888 lines.push(tool.description, '');
889 if (tool.instant?.supported === true) {
890 lines.push('**Instant:** Supported on the latest version.', '',
891 `**Instant pricing:** ${instantPricingDescription(tool.instant)}`, '');
892 const discount = instantDiscount(tool.instant);
893 if (discount !== undefined) lines.push(`**Discount:** ${discount}`, '');
894 }
895
896 // Input parameters
897 if (tool.input_parameters && Object.keys(tool.input_parameters).length > 0) {
898 lines.push('#### Input Parameters', '');
899 lines.push(...renderParamsMarkdown(tool.input_parameters));
900 lines.push('');
901 }
902
903 // Output parameters
904 if (tool.output_parameters && Object.keys(tool.output_parameters).length > 0) {
905 lines.push('#### Output', '');
906 lines.push(...renderParamsMarkdown(tool.output_parameters));
907 lines.push('');
908 }
909 }
910 }
911
912 if (triggers.length > 0) {
913 lines.push('', '## Triggers', '');
914 for (const trigger of triggers) {
915 lines.push(`### ${trigger.name}`, '');
916 lines.push(`**Slug:** \`${trigger.slug}\``, '');
917
918 // Trigger type (webhook/poll)
919 if (trigger.type) {
920 lines.push(`**Type:** ${trigger.type}`, '');
921 }
922
923 lines.push(trigger.description, '');
924
925 // Config parameters
926 if (trigger.config && Object.keys(trigger.config).length > 0) {
927 lines.push('#### Configuration', '');
928 lines.push(...renderParamsMarkdown(trigger.config));
929 lines.push('');
930 }
931
932 // Payload parameters
933 if (trigger.payload && Object.keys(trigger.payload).length > 0) {
934 lines.push('#### Payload', '');
935 lines.push(...renderParamsMarkdown(trigger.payload));
936 lines.push('');
937 }
938 }
939 }
940
941 return lines.join('\n');
942 }
943
944 // Generate markdown for /toolkits/managed-auth.md
945 async function generateManagedAuthIndex(): Promise<string> {
946 const toolkits = await getAllToolkits();
947
948 // Only include OAuth toolkits
949 const oauthToolkits = toolkits.filter(t =>
950 t.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'))
951 );
952
953 const managed = oauthToolkits
954 .filter(t => t.composioManagedAuthSchemes && t.composioManagedAuthSchemes.length > 0)
955 .sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
956
957 const unmanaged = oauthToolkits
958 .filter(t => !t.composioManagedAuthSchemes || t.composioManagedAuthSchemes.length === 0)
959 .sort((a, b) => (a.name?.trim() || '').localeCompare(b.name?.trim() || ''));
960
961 const lines: string[] = [
962 '# Managed OAuth apps',
963 '',
964 'Composio can provide the OAuth app that your users authorize when they connect a toolkit. You do not need to register an OAuth app or supply its client ID and client secret.',
965 '',
966 'This catalog identifies who provides the OAuth app, not which execution framework you must use. For per-user OAuth with application-owned tools, follow [Managed authentication for your own tools](/docs/authentication/managed-auth-for-custom-tools.md). Call provider endpoints through the authenticated proxy without predefined tools, MCP, or an LLM.',
967 '',
968 'This list covers only toolkits that support OAuth. It does not include toolkits that use only API keys, bearer tokens, Basic auth, or no authentication.',
969 '',
970 'Call the toolkit endpoint and read `composio_managed_auth_schemes`:',
971 '',
972 '```bash',
973 "curl 'https://backend.composio.dev/api/v3.1/toolkits/gmail' \\",
974 " -H 'x-api-key: YOUR_API_KEY'",
975 '```',
976 '',
977 'If `composio_managed_auth_schemes` contains the toolkit\'s OAuth method, Composio provides the OAuth app. If the field does not contain that method, register your own OAuth app and supply its client ID and client secret.',
978 '',
979 'Some toolkits support more than one authentication method. A toolkit appears under **Composio-managed OAuth available** when Composio manages at least one OAuth method. Open the toolkit page to check each method.',
980 '',
981 'See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app.md) for setup steps and trade-offs.',
982 '',
983 `## Composio-managed OAuth available (${managed.length})`,
984 '',
985 '| Toolkit | Slug |',
986 '|---------|------|',
987 ];
988
989 for (const t of managed) {
990 lines.push(
991 `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
992 );
993 }
994
995 lines.push('');
996 lines.push(`## Bring your own OAuth app (${unmanaged.length})`);
997 lines.push('');
998 lines.push('| Toolkit | Slug |');
999 lines.push('|---------|------|');
1000
1001 for (const t of unmanaged) {
1002 lines.push(
1003 `| [${t.name?.trim() || t.slug}](/toolkits/${t.slug}.md) | \`${t.slug.toUpperCase()}\` |`
1004 );
1005 }
1006
1007 return lines.join('\n');
1008 }
1009
1010 // Generate a comprehensive toolkits index for /toolkits.md
1011 async function generateToolkitsIndex(): Promise<string> {
1012 const toolkits = await getAllToolkits();
1013
1014 // Sort alphabetically by name
1015 const sorted = [...toolkits].sort((a, b) =>
1016 (a.name?.trim() || '').localeCompare(b.name?.trim() || '')
1017 );
1018
1019 const lines: string[] = [
1020 '# Toolkits',
1021 '',
1022 `Composio supports ${toolkits.length} toolkits for building AI agents.`,
1023 '',
1024 '- [Instant Tools](/docs/instant-tools.md) - Run supported tools on Composio accounts and control usage charges',
1025 '- [Managed OAuth apps](/toolkits/managed-auth.md) - Check whether Composio provides the OAuth app for a toolkit',
1026 '',
1027 '## All Toolkits',
1028 '',
1029 '| Toolkit | Slug | Tools | Triggers | Auth | Managed App |',
1030 '|---------|------|-------|----------|------|-------------|',
1031 ];
1032
1033 for (const toolkit of sorted) {
1034 const name = toolkit.name?.trim() || toolkit.slug;
1035 const auth = toolkit.authSchemes?.join(', ') || 'None';
1036 const hasOAuth = toolkit.authSchemes?.some(s => s.toUpperCase().includes('OAUTH'));
1037 const managedApp = hasOAuth
1038 ? toolkit.composioManagedAuthSchemes && toolkit.composioManagedAuthSchemes.length > 0
1039 ? 'Yes'
1040 : 'No'
1041 : '—';
1042 lines.push(
1043 `| [${name}](/toolkits/${toolkit.slug}.md) | \`${toolkit.slug.toUpperCase()}\` | ${toolkit.toolCount} | ${toolkit.triggerCount} | ${auth} | ${managedApp} |`
1044 );
1045 }
1046
1047 lines.push('', '## Toolkit Details', '');
1048 lines.push(
1049 'For detailed information about each toolkit including all tools and triggers, visit the individual toolkit pages listed above.'
1050 );
1051
1052 return lines.join('\n');
1053 }
1054
1055 const LLM_FOOTER =
1056 '\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)';
1057
1058 function knowledgeLinksToMarkdown(links: KnowledgeLink[]): string {
1059 return links
1060 .map((link) => `- [${link.title}](${link.href}) — ${link.description} (${link.sourceLabel})`)
1061 .join('\n');
1062 }
1063
1064 async function knowledgeBrowseToMarkdown(rest: string[]): Promise<string | null> {
1065 if (rest.length === 0) {
1066 const areas = PRODUCT_AREAS.filter((area) => area.defaultBrowse)
1067 .map((area) => `- [${area.title}](https://docs.composio.dev/kb/topic/${area.slug}) — ${area.description}`)
1068 .join('\n');
1069 return `# Composio Knowledge Base\n\nSearch and browse public Composio knowledge across docs, verified support answers, OAuth guides, toolkits, examples, reference, and changelog.\n\n- [Search support knowledge](https://docs.composio.dev/kb/search)\n- [Browse all toolkits](https://docs.composio.dev/kb/toolkits)\n\n## Support topics\n\n${areas}${LLM_FOOTER}`;
1070 }
1071
1072 if (rest.length === 1 && rest[0] === 'search') {
1073 return `# Search Composio support knowledge\n\nUse the [Knowledge Base search](https://docs.composio.dev/kb/search) to find canonical public support answers and toolkit-specific fixes.${LLM_FOOTER}`;
1074 }
1075
1076 if (rest.length === 1 && rest[0] === 'toolkits') {
1077 const toolkits = await getKnowledgeToolkitSummaries();
1078 const rows = toolkits
1079 .map((toolkit) => `- [${toolkit.name}](https://docs.composio.dev${getToolkitKnowledgeMarkdownHref(toolkit)}) — ${toolkit.knowledgeCount} resource${toolkit.knowledgeCount === 1 ? '' : 's'}`)
1080 .join('\n');
1081 return `# Toolkit knowledge\n\nBrowse canonical public knowledge by provider.\n\n${rows}${LLM_FOOTER}`;
1082 }
1083
1084 if (rest.length === 2 && rest[0] === 'topic' && isProductAreaSlug(rest[1])) {
1085 const area = getProductArea(rest[1]);
1086 const links = await getKnowledgeByProductArea(rest[1]);
1087 if (!area.defaultBrowse && links.length === 0) return null;
1088 return `# ${area.title}\n\n${area.description}\n\n${knowledgeLinksToMarkdown(links)}${LLM_FOOTER}`;
1089 }
1090
1091 if (rest.length === 2 && rest[0] === 'toolkit') {
1092 const toolkits = await getKnowledgeToolkitSummaries();
1093 const toolkit = toolkits.find((candidate) => candidate.slug === rest[1]);
1094 if (!toolkit) return null;
1095 const links = await getKnowledgeByToolkit(toolkit.slug);
1096 return `# ${toolkit.name} knowledge\n\nCanonical public Composio information for ${toolkit.name}.\n\n${knowledgeLinksToMarkdown(links)}${LLM_FOOTER}`;
1097 }
1098
1099 return null;
1100 }
1101
1102 // Render meta tool parameters as markdown
1103 function renderMetaToolParams(
1104 properties: Record<string, MetaToolParameter>,
1105 requiredFields: string[] = [],
1106 indent = 0
1107 ): string[] {
1108 const lines: string[] = [];
1109 const prefix = ' '.repeat(indent);
1110
1111 for (const [name, param] of Object.entries(properties)) {
1112 const reqMark = requiredFields.includes(name) ? ' *(required)*' : '';
1113 const desc = param.description
1114 ? `: ${param.description}`
1115 : '';
1116 const defaultStr =
1117 param.defaultLabel !== null
1118 ? ` (default: \`${param.defaultLabel}\`)`
1119 : '';
1120 const enumStr =
1121 param.enum.length > 0
1122 ? ` — values: ${param.enum.map(v => `\`${v}\``).join(', ')}`
1123 : '';
1124
1125 lines.push(`${prefix}- \`${name}\` (${param.typeLabel})${reqMark}${desc}${defaultStr}${enumStr}`);
1126
1127 if (Object.keys(param.properties).length > 0) {
1128 lines.push(...renderMetaToolParams(param.properties, param.required, indent + 1));
1129 }
1130
1131 const items = param.items;
1132 if (items && Object.keys(items.properties).length > 0) {
1133 lines.push(`${prefix} - Array items:`);
1134 lines.push(
1135 ...renderMetaToolParams(
1136 items.properties,
1137 items.required,
1138 indent + 2
1139 )
1140 );
1141 }
1142 }
1143
1144 return lines;
1145 }
1146
1147 // Generate markdown for a single meta tool
1148 function metaToolToMarkdown(tool: MetaTool): string {
1149 const lines: string[] = [`# ${tool.displayName}`, '', `**Slug:** \`${tool.slug}\``];
1150
1151 if (tool.tags.length > 0) {
1152 lines.push(`**Tags:** ${tool.tags.join(', ')}`);
1153 }
1154
1155 lines.push('');
1156
1157 lines.push(tool.summary, '');
1158 if (tool.whenToUse) {
1159 lines.push('## When to use it', '', tool.whenToUse, '');
1160 }
1161 if (tool.usageNote) {
1162 lines.push(tool.usageNote, '');
1163 }
1164
1165 const inputProps = tool.inputParameters.properties;
1166 if (Object.keys(inputProps).length > 0) {
1167 lines.push('## Input Parameters', '');
1168 lines.push(...renderMetaToolParams(inputProps, tool.inputParameters.required));
1169 lines.push('');
1170 }
1171
1172 const responseProps = tool.responseSchema.properties;
1173 if (Object.keys(responseProps).length > 0) {
1174 lines.push('## Response', '');
1175 lines.push(...renderMetaToolParams(responseProps, tool.responseSchema.required));
1176 lines.push('');
1177 }
1178
1179 return lines.join('\n') + LLM_FOOTER;
1180 }
1181
1182 // Generate markdown index for all meta tools
1183 function metaToolsIndexToMarkdown(tools: MetaTool[]): string {
1184 const lines: string[] = [
1185 '# Meta Tools',
1186 '',
1187 'Meta tools are system-level tools available in sessions. They handle tool discovery, execution, authentication, and sandboxing.',
1188 '',
1189 '| Tool | Tags |',
1190 '|------|------|',
1191 ];
1192
1193 for (const tool of tools) {
1194 const tags = tool.tags.length > 0 ? tool.tags.join(', ') : '—';
1195 lines.push(
1196 `| [\`${tool.slug}\`](/toolkits/meta-tools/${tool.slug.toLowerCase().replace('composio_', '')}.md) | ${tags} |`
1197 );
1198 }
1199
1200 return lines.join('\n') + LLM_FOOTER;
1201 }
1202
1203 export async function GET(req: Request, context: { params: Promise<{ slug?: string[] }> }) {
1204 const { slug = [] } = await context.params;
1205 const pathname = `/${slug.join('/')}`;
1206 const response = await renderMarkdown(req, context);
1207 if (!response.headers.get('Content-Type')?.startsWith('text/markdown')) {
1208 response.headers.set('Vary', 'Accept');
1209 return response;
1210 }
1211 return withMarkdownMetadata(
1212 await response.text(),
1213 pathname,
1214 response.ok ? await getPageLastUpdated(pathname) : null,
1215 { status: response.status, statusText: response.statusText, headers: response.headers },
1216 );
1217 }
1218
1219 async function renderMarkdown(_req: Request, { params }: { params: Promise<{ slug?: string[] }> }) {
1220 try {
1221 const { slug = [] } = await params;
1222 const [prefix, ...rest] = slug;
1223
1224 if (prefix === 'kb') {
1225 if (rest.length === 2 && rest[0] === 'toolkit') {
1226 const toolkits = await getKnowledgeToolkitSummaries();
1227 const toolkit = toolkits.find((candidate) => candidate.slug === rest[1]);
1228 const redirectPath = toolkit ? getToolkitKnowledgeRedirect(toolkit) : null;
1229 if (redirectPath) {
1230 return new Response(null, {
1231 status: 307,
1232 headers: { Location: `${redirectPath}.md` },
1233 });
1234 }
1235 }
1236 const browseMarkdown = await knowledgeBrowseToMarkdown(rest);
1237 if (browseMarkdown) {
1238 return new Response(browseMarkdown, {
1239 headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
1240 });
1241 }
1242 }
1243
1244 // Special handling for toolkits index - generate comprehensive list
1245 if (prefix === 'toolkits' && rest.length === 0) {
1246 const toolkitsIndex = await generateToolkitsIndex();
1247 return new Response(toolkitsIndex, {
1248 headers: {
1249 'Content-Type': 'text/markdown; charset=utf-8',
1250 },
1251 });
1252 }
1253
1254 // Special handling for managed auth page - generate server-side list
1255 if (prefix === 'toolkits' && rest.length === 1 && rest[0] === 'managed-auth') {
1256 const managedAuthIndex = await generateManagedAuthIndex();
1257 return new Response(managedAuthIndex, {
1258 headers: {
1259 'Content-Type': 'text/markdown; charset=utf-8',
1260 },
1261 });
1262 }
1263
1264 // Special handling for changelog index - /docs/changelog
1265 if (prefix === 'docs' && rest[0] === 'changelog' && rest.length === 1) {
1266 const changelogIndex = generateChangelogIndex();
1267 return new Response(changelogIndex, {
1268 headers: {
1269 'Content-Type': 'text/markdown; charset=utf-8',
1270 },
1271 });
1272 }
1273
1274 // Special handling for changelog pages - /docs/changelog/YYYY/MM/DD
1275 if (prefix === 'docs' && rest[0] === 'changelog' && rest.length === 4) {
1276 // rest = ['changelog', '2026', '01', '07']
1277 const [, year, month, day] = rest;
1278 const dateStr = slugToDate([year, month, day]);
1279
1280 if (dateStr) {
1281 const markdown = await changelogToMarkdown(dateStr);
1282 if (markdown) {
1283 return new Response(markdown, {
1284 headers: {
1285 'Content-Type': 'text/markdown; charset=utf-8',
1286 },
1287 });
1288 }
1289 }
1290 return missingMarkdownResponse();
1291 }
1292
1293 // Special handling for meta tools - /toolkits/meta-tools and /toolkits/meta-tools/{slug}.
1294 // Must run before the generic toolkits page resolution and the JSON toolkit block
1295 // below, since the meta-tool MDX is just a <MetaToolDetailServer /> shell that can't
1296 // render to useful markdown — the content is generated from the JSON data instead.
1297 if (prefix === 'toolkits' && rest[0] === 'meta-tools') {
1298 if (rest.length === 1) {
1299 // Index page
1300 const tools = await getAllMetaTools();
1301 return new Response(metaToolsIndexToMarkdown(tools), {
1302 headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
1303 });
1304 }
1305 if (rest.length === 2) {
1306 // Individual tool page — match by page slug (e.g., "search_tools" or "search_tools.md")
1307 const pageSlug = rest[1].replace(/\.md$/, '');
1308 const tools = await getAllMetaTools();
1309 const tool = tools.find(t => t.slug.toLowerCase().replace('composio_', '') === pageSlug);
1310 if (tool) {
1311 return new Response(metaToolToMarkdown(tool), {
1312 headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
1313 });
1314 }
1315 }
1316 }
1317
1318 // Handle 'reference' specially - uses async getReferenceSource() for OpenAPI pages
1319 let pageSource: PageSource;
1320 if (prefix === 'reference') {
1321 try {
1322 pageSource = await getReferenceSource();
1323 } catch (e) {
1324 console.error('Error loading reference source:', e);
1325 // Fall back to MDX-only reference source if OpenAPI loading fails
1326 const { referenceSource } = await import('@/lib/source');
1327 pageSource = referenceSource;
1328 }
1329 } else {
1330 const match = sources.find(s => s.prefix === prefix);
1331 if (!match) return missingMarkdownResponse();
1332 pageSource = match.source;
1333 }
1334
1335 // Get the page from that source (MDX pages)
1336 let page;
1337 try {
1338 page = pageSource.getPage(rest.length > 0 ? rest : undefined);
1339 } catch (e) {
1340 console.error('Error in getPage:', e);
1341 page = null;
1342 }
1343
1344 if (page) {
1345 // Check if this is an OpenAPI page
1346 const openapiPage = openAPIPageSchema.safeParse(page);
1347 if (openapiPage.success) {
1348 try {
1349 const markdown = await openapiPageToMarkdown(openapiPage.data);
1350 return new Response(markdown, {
1351 headers: {
1352 'Content-Type': 'text/markdown; charset=utf-8',
1353 },
1354 });
1355 } catch (e) {
1356 console.error('Error generating OpenAPI markdown:', e);
1357 const title = openapiPage.data.data.title || 'API Reference';
1358 const description = openapiPage.data.data.description || '';
1359 return new Response(`# ${title}\n\n${description}`, {
1360 headers: {
1361 'Content-Type': 'text/markdown; charset=utf-8',
1362 },
1363 });
1364 }
1365 }
1366
1367 // Regular MDX page
1368 const llmPage = llmPageSchema.safeParse(page);
1369 if (llmPage.success) {
1370 try {
1371 return new Response(await getLLMText(llmPage.data), {
1372 headers: {
1373 'Content-Type': 'text/markdown; charset=utf-8',
1374 },
1375 });
1376 } catch (e) {
1377 console.error('Error generating LLM text:', e);
1378 const title = llmPage.data.data.title || 'Documentation';
1379 const description = llmPage.data.data.description || '';
1380 return new Response(`# ${title} (${llmPage.data.url})\n\n${description}`, {
1381 headers: {
1382 'Content-Type': 'text/markdown; charset=utf-8',
1383 },
1384 });
1385 }
1386 }
1387
1388 const degradedMarkdown = degradedPageToMarkdown(page);
1389 if (degradedMarkdown !== null) {
1390 return new Response(degradedMarkdown, {
1391 headers: {
1392 'Content-Type': 'text/markdown; charset=utf-8',
1393 },
1394 });
1395 }
1396 }
1397
1398 // Special handling for JSON toolkit pages
1399 if (prefix === 'toolkits' && rest.length === 1) {
1400 const toolkit = await getToolkitBySlug(rest[0]);
1401 if (toolkit) {
1402 // Fetch detailed tool/trigger info and FAQ content in parallel
1403 const [detailedTools, detailedTriggers, faqMarkdown] = await Promise.all([
1404 fetchDetailedTools(rest[0]),
1405 fetchDetailedTriggers(rest[0]),
1406 readToolkitFaqMarkdown(rest[0]),
1407 ]);
1408
1409 return new Response(
1410 toolkitToMarkdown(
1411 toolkit,
1412 detailedTools !== null ? detailedTools : undefined,
1413 detailedTriggers !== null ? detailedTriggers : undefined,
1414 faqMarkdown
1415 ),
1416 {
1417 headers: {
1418 'Content-Type': 'text/markdown; charset=utf-8',
1419 },
1420 }
1421 );
1422 }
1423 }
1424
1425 return missingMarkdownResponse();
1426 } catch (e) {
1427 console.error('Unexpected error in llms.mdx route:', e);
1428 return new Response(`# Error\n\nAn error occurred while generating the markdown content.`, {
1429 status: 500,
1430 headers: {
1431 'Content-Type': 'text/markdown; charset=utf-8',
1432 },
1433 });
1434 }
1435 }