Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | } |