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 | /** |
| 2 | * API version identity in the markdown channels. |
| 3 | * |
| 4 | * Agents read `.md`, not the browser rendering path. Every signal that |
| 5 | * separates v3.1 from v3.0 used to live in client components the markdown |
| 6 | * converter dropped, so `reference.md` published an empty `Base URL` bullet |
| 7 | * and the tag pages published an empty `Endpoints` section — while the |
| 8 | * superseded v3.0 operation pages published a complete working curl example. |
| 9 | * |
| 10 | * These tests lock the three properties that fix costs the most to lose: |
| 11 | * 1. `mdxToCleanMarkdown` renders `ApiBaseUrl` and `ApiEndpointsTable` at the |
| 12 | * version the page URL implies, and degrades (no table, no throw) on a |
| 13 | * malformed payload rather than 500ing the whole `.md` response. |
| 14 | * 2. `getLLMText` emits a version pointer on `/reference/**` and nowhere else. |
| 15 | * 3. The guidance text is single-sourced in `lib/api-version-guidance.ts` — |
| 16 | * asserted by containment of the exported constant, not by matching a |
| 17 | * copied literal, which is what proves the guardrail files compose rather |
| 18 | * than restate. |
| 19 | */ |
| 20 | import { describe, expect, test } from 'bun:test'; |
| 21 | |
| 22 | import { |
| 23 | REST_VERSION_GUIDANCE, |
| 24 | TOOL_VERSION_GUIDANCE, |
| 25 | TOOL_VERSION_PATHS, |
| 26 | apiVersionPointer, |
| 27 | isToolVersionPath, |
| 28 | } from '../../lib/api-version-guidance'; |
| 29 | import { detectReferenceApiVersion, toCurrentVersionUrl } from '../../lib/api-version'; |
| 30 | import { |
| 31 | getLLMText, |
| 32 | getReferenceSource, |
| 33 | mdxToCleanMarkdown, |
| 34 | type LLMPage, |
| 35 | } from '../../lib/source'; |
| 36 | import { DIRECT_EXECUTION_GUARDRAILS, SESSION_GUARDRAILS } from '../../lib/llm-guardrails'; |
| 37 | |
| 38 | const V31_BASE = 'https://backend.composio.dev/api/v3.1'; |
| 39 | const V30_BASE = 'https://backend.composio.dev/api/v3'; |
| 40 | |
| 41 | /** A current-tree tag page and its legacy twin. */ |
| 42 | const CURRENT_URL = '/reference/api-reference/tools'; |
| 43 | const LEGACY_URL = '/reference/v3/api-reference/tools'; |
| 44 | |
| 45 | /** The authored MDX shape, which `lib/search-index.ts` reads from the file. */ |
| 46 | function endpointsTable(endpoints: unknown[]): string { |
| 47 | return `## Endpoints\n\n<ApiEndpointsTable endpoints={${JSON.stringify(endpoints)}} />\n`; |
| 48 | } |
| 49 | |
| 50 | /** |
| 51 | * The shape `getLLMText` actually receives: fumadocs' processed markdown |
| 52 | * re-serializes the JSX expression attribute as a quoted string with the inner |
| 53 | * quotes entity-escaped. Matching only the authored shape above still passes a |
| 54 | * unit test while leaving every live tag page's Endpoints section empty, which |
| 55 | * is exactly the defect this work exists to fix — so the production shape gets |
| 56 | * its own fixture. |
| 57 | */ |
| 58 | function processedEndpointsTable(endpoints: unknown[]): string { |
| 59 | const escaped = JSON.stringify(endpoints).replace(/"/g, '"'); |
| 60 | return `## Endpoints\n\n<ApiEndpointsTable endpoints="${escaped}" />\n`; |
| 61 | } |
| 62 | |
| 63 | const TOOLS_ENDPOINT = { |
| 64 | method: 'GET', |
| 65 | pathV31: '/api/v3.1/tools', |
| 66 | pathV3: '/api/v3/tools', |
| 67 | summary: 'List tools', |
| 68 | href: '/reference/api-reference/tools/getTools', |
| 69 | }; |
| 70 | |
| 71 | function llmPage(url: string, content: string, data: Partial<LLMPage['data']> = {}): LLMPage { |
| 72 | return { |
| 73 | url, |
| 74 | data: { title: 'Tools', getText: async () => content, ...data }, |
| 75 | }; |
| 76 | } |
| 77 | |
| 78 | describe('mdxToCleanMarkdown — ApiBaseUrl', () => { |
| 79 | test('renders the v3.1 base URL on a current-tree URL', () => { |
| 80 | expect(mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />', CURRENT_URL)).toContain(V31_BASE); |
| 81 | }); |
| 82 | |
| 83 | test('renders the v3 base URL on a legacy-tree URL', () => { |
| 84 | const markdown = mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />', LEGACY_URL); |
| 85 | expect(markdown).toContain(`\`${V30_BASE}\``); |
| 86 | expect(markdown).not.toContain(V31_BASE); |
| 87 | }); |
| 88 | |
| 89 | test('renders the v3.1 base URL with no url argument — the changelog call site', () => { |
| 90 | expect(mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />')).toContain(V31_BASE); |
| 91 | }); |
| 92 | }); |
| 93 | |
| 94 | describe('mdxToCleanMarkdown — ApiEndpointsTable', () => { |
| 95 | test('emits one row per endpoint using pathV31 on a current-tree URL', () => { |
| 96 | const markdown = mdxToCleanMarkdown( |
| 97 | endpointsTable([ |
| 98 | TOOLS_ENDPOINT, |
| 99 | { |
| 100 | method: 'POST', |
| 101 | pathV31: '/api/v3.1/tools/execute/{tool_slug}', |
| 102 | pathV3: '/api/v3/tools/execute/{tool_slug}', |
| 103 | summary: 'Execute a tool', |
| 104 | href: '/reference/api-reference/tools/executeTool', |
| 105 | }, |
| 106 | ]), |
| 107 | CURRENT_URL |
| 108 | ); |
| 109 | |
| 110 | expect(markdown).toContain('/api/v3.1/tools'); |
| 111 | expect(markdown).toContain('/api/v3.1/tools/execute/{tool_slug}'); |
| 112 | expect(markdown).not.toContain('/api/v3/tools'); |
| 113 | // href kept as a relative link, summary preserved |
| 114 | expect(markdown).toContain('[List tools](/reference/api-reference/tools/getTools)'); |
| 115 | expect(markdown).toContain('[Execute a tool](/reference/api-reference/tools/executeTool)'); |
| 116 | }); |
| 117 | |
| 118 | test('renders the processed-markdown shape getLLMText actually receives', () => { |
| 119 | const markdown = mdxToCleanMarkdown( |
| 120 | processedEndpointsTable([ |
| 121 | TOOLS_ENDPOINT, |
| 122 | { |
| 123 | method: 'GET', |
| 124 | pathV31: '/api/v3.1/tools/{tool_slug}', |
| 125 | pathV3: '/api/v3/tools/{tool_slug}', |
| 126 | summary: 'Get tool by slug', |
| 127 | href: '/reference/api-reference/tools/getToolsByToolSlug', |
| 128 | }, |
| 129 | ]), |
| 130 | CURRENT_URL |
| 131 | ); |
| 132 | |
| 133 | expect(markdown).toContain('[List tools](/reference/api-reference/tools/getTools)'); |
| 134 | expect(markdown).toContain('`/api/v3.1/tools/{tool_slug}`'); |
| 135 | // The escaping must actually be reversed, not carried through. |
| 136 | expect(markdown).not.toContain('"'); |
| 137 | }); |
| 138 | |
| 139 | test('uses pathV3 on a legacy-tree URL', () => { |
| 140 | const markdown = mdxToCleanMarkdown(endpointsTable([TOOLS_ENDPOINT]), LEGACY_URL); |
| 141 | expect(markdown).toContain('`/api/v3/tools`'); |
| 142 | expect(markdown).not.toContain('/api/v3.1/tools'); |
| 143 | }); |
| 144 | |
| 145 | test('renders a visible legacy marker for a deprecated endpoint', () => { |
| 146 | const markdown = mdxToCleanMarkdown( |
| 147 | endpointsTable([{ ...TOOLS_ENDPOINT, legacy: true }]), |
| 148 | CURRENT_URL |
| 149 | ); |
| 150 | expect(markdown).toContain('Legacy'); |
| 151 | }); |
| 152 | |
| 153 | test('preserves backslashes and pipes in endpoint summaries', () => { |
| 154 | const markdown = mdxToCleanMarkdown( |
| 155 | endpointsTable([{ ...TOOLS_ENDPOINT, summary: String.raw`Path \| pipe` }]), |
| 156 | CURRENT_URL |
| 157 | ); |
| 158 | |
| 159 | expect(markdown).toContain(String.raw`[Path \\\| pipe]`); |
| 160 | }); |
| 161 | |
| 162 | test('emits no table and does not throw on a truncated payload', () => { |
| 163 | const content = 'Surrounding prose.\n\n<ApiEndpointsTable endpoints={[{"method":"GET"} />\n'; |
| 164 | const markdown = mdxToCleanMarkdown(content, CURRENT_URL); |
| 165 | // The rest of the page survives — one bad table must not take the whole |
| 166 | // .md response down. |
| 167 | expect(markdown).toContain('Surrounding prose.'); |
| 168 | expect(markdown).not.toContain('| Method |'); |
| 169 | }); |
| 170 | |
| 171 | test('emits no table on a structurally invalid payload a bare JSON.parse would accept', () => { |
| 172 | // Valid JSON, pathV31 missing. |
| 173 | const markdown = mdxToCleanMarkdown( |
| 174 | `Surrounding prose.\n\n${endpointsTable([ |
| 175 | { method: 'GET', pathV3: '/api/v3/tools', summary: 'List tools', href: '/x' }, |
| 176 | ])}`, |
| 177 | CURRENT_URL |
| 178 | ); |
| 179 | expect(markdown).toContain('Surrounding prose.'); |
| 180 | expect(markdown).not.toContain('| Method |'); |
| 181 | expect(markdown).not.toContain('List tools'); |
| 182 | }); |
| 183 | }); |
| 184 | |
| 185 | describe('getLLMText — version pointer', () => { |
| 186 | test('a current /reference/** page carries the v3.1 pointer and base URL', async () => { |
| 187 | const text = await getLLMText(llmPage(CURRENT_URL, '# Tools'), { includeGuardrails: false }); |
| 188 | expect(text).toContain('**API version:**'); |
| 189 | expect(text).toContain(V31_BASE); |
| 190 | }); |
| 191 | |
| 192 | test('a legacy /reference/v3/** page carries the v3.0 pointer and links its v3.1 page', async () => { |
| 193 | const text = await getLLMText(llmPage(LEGACY_URL, '# Tools'), { includeGuardrails: false }); |
| 194 | expect(text).toContain('**API version:**'); |
| 195 | expect(text).toContain('v3.0'); |
| 196 | expect(text).toContain(V31_BASE); |
| 197 | expect(text).toContain('/reference/api-reference/tools.md'); |
| 198 | expect(text).not.toContain('https://docs.composio.dev/reference/api-reference/tools.md'); |
| 199 | }); |
| 200 | |
| 201 | test('a /docs/** page gets no API version pointer — the pointer is reference-scoped', async () => { |
| 202 | const text = await getLLMText(llmPage('/docs/quickstart', '# Quickstart')); |
| 203 | expect(text).not.toContain('**API version:**'); |
| 204 | }); |
| 205 | |
| 206 | test('an SDK reference page gets no REST version pointer', async () => { |
| 207 | const text = await getLLMText( |
| 208 | llmPage('/reference/sdk-reference/typescript/tools', '# Tools') |
| 209 | ); |
| 210 | expect(text).not.toContain('**API version:**'); |
| 211 | }); |
| 212 | |
| 213 | test('the glossary gets no REST version pointer', async () => { |
| 214 | const text = await getLLMText(llmPage('/reference/glossary', '# Glossary')); |
| 215 | expect(text).not.toContain('**API version:**'); |
| 216 | }); |
| 217 | |
| 218 | test('the legacy authentication page links to its renamed current counterpart', async () => { |
| 219 | const text = await getLLMText( |
| 220 | llmPage('/reference/v3/authentication', '# Authentication'), |
| 221 | { includeGuardrails: false } |
| 222 | ); |
| 223 | expect(text).toContain('/reference/authenticating-to-composio.md'); |
| 224 | }); |
| 225 | |
| 226 | test('every published legacy page links to an existing current-version page', async () => { |
| 227 | const reference = await getReferenceSource(); |
| 228 | const routes = new Set(reference.getPages().map(page => page.url)); |
| 229 | const legacyRoutes = [...routes].filter( |
| 230 | url => detectReferenceApiVersion(url) === '3.0' |
| 231 | ); |
| 232 | const invalidPointers = legacyRoutes.flatMap(source => { |
| 233 | const target = toCurrentVersionUrl(source); |
| 234 | const pointer = apiVersionPointer(source); |
| 235 | return routes.has(target) && |
| 236 | detectReferenceApiVersion(target) === '3.1' && |
| 237 | pointer.includes(`${target}.md`) |
| 238 | ? [] |
| 239 | : [`${source} -> ${target}`]; |
| 240 | }); |
| 241 | |
| 242 | expect(legacyRoutes.some(url => /^\/reference\/v3\/[^/]+$/.test(url))).toBe(true); |
| 243 | expect( |
| 244 | legacyRoutes.some(url => /^\/reference\/v3\/api-reference\/[^/]+$/.test(url)) |
| 245 | ).toBe(true); |
| 246 | expect( |
| 247 | legacyRoutes.some(url => /^\/reference\/v3\/api-reference\/[^/]+\/[^/]+$/.test(url)) |
| 248 | ).toBe(true); |
| 249 | expect( |
| 250 | invalidPointers, |
| 251 | `invalid current-version pointers:\n${invalidPointers.join('\n')}` |
| 252 | ).toEqual([]); |
| 253 | }); |
| 254 | |
| 255 | test('a legacy: true page keeps its legacy note and still emits no guardrails', async () => { |
| 256 | const text = await getLLMText( |
| 257 | llmPage('/docs/tools-direct/executing-tools', '# Executing tools', { legacy: true }) |
| 258 | ); |
| 259 | expect(text).toContain('**Legacy'); |
| 260 | // legacy: true gates the whole guardrail block at source.ts, before the |
| 261 | // llmGuardrails selector ever runs. Deliberate: appending "enforce the |
| 262 | // CURRENT patterns" to a point-in-time migration guide contradicts it. |
| 263 | expect(text).not.toContain('Instructions for AI Code Generators'); |
| 264 | }); |
| 265 | }); |
| 266 | |
| 267 | describe('detectReferenceApiVersion', () => { |
| 268 | test.each([ |
| 269 | ['/reference/api-reference/tools', '3.1'], |
| 270 | ['/reference/v3/api-reference/tools', '3.0'], |
| 271 | ['/reference/glossary', null], |
| 272 | ['/reference/sdk-reference', null], |
| 273 | ['/reference/sdk-reference/typescript/tools', null], |
| 274 | ] as const)('%s is classified as %s', (url, expected) => { |
| 275 | expect(detectReferenceApiVersion(url)).toBe(expected); |
| 276 | }); |
| 277 | }); |
| 278 | |
| 279 | describe('guardrail sets compose the guidance rather than restating it', () => { |
| 280 | // Containment of the exported constant, not a substring of prose. A test |
| 281 | // matching a copied literal would pass just as happily against two strings |
| 282 | // that currently agree and are free to drift. |
| 283 | test.each([ |
| 284 | ['SESSION_GUARDRAILS', SESSION_GUARDRAILS], |
| 285 | ['DIRECT_EXECUTION_GUARDRAILS', DIRECT_EXECUTION_GUARDRAILS], |
| 286 | ])('%s contains both guidance constants verbatim', (_name, guardrails) => { |
| 287 | expect(guardrails).toContain(REST_VERSION_GUIDANCE); |
| 288 | expect(guardrails).toContain(TOOL_VERSION_GUIDANCE); |
| 289 | }); |
| 290 | }); |
| 291 | |
| 292 | describe('API version guidance constants', () => { |
| 293 | test('the REST baseline names v3.1 without claiming route parity', () => { |
| 294 | expect(REST_VERSION_GUIDANCE).toContain('https://backend.composio.dev/api/v3.1'); |
| 295 | expect(TOOL_VERSION_GUIDANCE).toContain( |
| 296 | 'This version-default change is limited to the five endpoints above.' |
| 297 | ); |
| 298 | expect(TOOL_VERSION_GUIDANCE).not.toMatch(/every non-tool endpoint.*unchanged/i); |
| 299 | }); |
| 300 | |
| 301 | test('exactly five tool paths need explicit version-default guidance', () => { |
| 302 | expect(TOOL_VERSION_PATHS).toHaveLength(5); |
| 303 | }); |
| 304 | }); |
| 305 | |
| 306 | describe('isToolVersionPath normalization contract', () => { |
| 307 | // Every key below appears verbatim in a committed spec. The predicate takes |
| 308 | // the raw spec path key; no caller pre-strips anything. |
| 309 | const cases: Array<[path: string, expected: boolean, why: string]> = [ |
| 310 | ['/api/v3.1/tools', true, ''], |
| 311 | ['/api/v3.1/tools/{tool_slug}', true, 'fails if /api/v3 is stripped before /api/v3.1'], |
| 312 | ['/api/v3.1/tools/execute/{tool_slug}', true, ''], |
| 313 | ['/api/v3.1/tools/execute/{tool_slug}/input', true, ''], |
| 314 | ['/api/v3.1/tools/scopes/required', true, 'v3.1-only; has no v3 counterpart'], |
| 315 | ['/api/v3/tools', true, ''], |
| 316 | ['/api/v3/tools/{tool_slug}', true, ''], |
| 317 | ['/api/v3/tools/execute/{tool_slug}', true, ''], |
| 318 | ['/api/v3/tools/execute/{tool_slug}/input', true, ''], |
| 319 | ['/api/v3.1/tools/enum', false, 'under /tools, not affected — breaks a prefix match'], |
| 320 | ['/api/v3.1/tools/execute/proxy', false, 'under /tools/execute, not affected'], |
| 321 | [ |
| 322 | '/api/v3.1/tool_router/session/{session_id}/tools', |
| 323 | false, |
| 324 | 'ends in /tools — breaks a substring match', |
| 325 | ], |
| 326 | ['/api/v3.1/auth_configs', false, 'plain non-tool'], |
| 327 | ['/api/v3.1/triggers_types', false, 'triggers already default to latest'], |
| 328 | ['/tools/{tool_slug}', false, 'no version prefix; the predicate normalizes, it does not guess'], |
| 329 | ]; |
| 330 | |
| 331 | for (const [path, expected, why] of cases) { |
| 332 | test(`${path} -> ${expected}${why ? ` (${why})` : ''}`, () => { |
| 333 | expect(isToolVersionPath(path)).toBe(expected); |
| 334 | }); |
| 335 | } |
| 336 | }); |