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 336 lines 13.6 KB
Raw
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, '&#x22;');
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('&#x22;');
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 });