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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; |
| 2 | import logger from '../../src/utils/logger'; |
| 3 | import { |
| 4 | _resetToolkitDeprecationWarningsForTests, |
| 5 | createToolkitDeprecationFetch, |
| 6 | formatToolkitDeprecationWarnings, |
| 7 | parseDeprecatedToolkitsHeader, |
| 8 | TOOLKIT_DEPRECATION_DOCS_URL, |
| 9 | TOOLKIT_DEPRECATION_HEADER, |
| 10 | type DeprecatedToolkitEntry, |
| 11 | } from '../../src/utils/toolkitDeprecation'; |
| 12 | |
| 13 | const FULL_ITEM = |
| 14 | '"GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle"'; |
| 15 | const BARE_ITEM = '"STRAVA";version="20240902_00"'; |
| 16 | const DOCS_URL = 'https://docs.example/deprecation'; |
| 17 | |
| 18 | const entry = (overrides: Partial<DeprecatedToolkitEntry> = {}): DeprecatedToolkitEntry => ({ |
| 19 | slug: 'GMAIL', |
| 20 | version: '20250114_00', |
| 21 | ...overrides, |
| 22 | }); |
| 23 | |
| 24 | describe('parseDeprecatedToolkitsHeader', () => { |
| 25 | it('parses an item with every parameter', () => { |
| 26 | expect(parseDeprecatedToolkitsHeader(FULL_ITEM)).toEqual([ |
| 27 | { |
| 28 | slug: 'GMAIL', |
| 29 | version: '20250114_00', |
| 30 | deprecatedAt: new Date(1779840000 * 1000), |
| 31 | sunsetAt: new Date(1787788800 * 1000), |
| 32 | reason: 'lifecycle', |
| 33 | }, |
| 34 | ]); |
| 35 | }); |
| 36 | |
| 37 | it('parses a bare item that carries only the version', () => { |
| 38 | expect(parseDeprecatedToolkitsHeader(BARE_ITEM)).toEqual([ |
| 39 | { slug: 'STRAVA', version: '20240902_00' }, |
| 40 | ]); |
| 41 | }); |
| 42 | |
| 43 | it('parses a two item list', () => { |
| 44 | const entries = parseDeprecatedToolkitsHeader(`${FULL_ITEM}, ${BARE_ITEM}`); |
| 45 | expect(entries.map(item => `${item.slug}@${item.version}`)).toEqual([ |
| 46 | 'GMAIL@20250114_00', |
| 47 | 'STRAVA@20240902_00', |
| 48 | ]); |
| 49 | }); |
| 50 | |
| 51 | it('decodes escaped quotes and backslashes inside a slug', () => { |
| 52 | const entries = parseDeprecatedToolkitsHeader( |
| 53 | '"ODD\\"SLUG\\\\";version="20250101_00", "GMAIL";version="20250114_00"' |
| 54 | ); |
| 55 | expect(entries.map(item => item.slug)).toEqual(['ODD"SLUG\\', 'GMAIL']); |
| 56 | }); |
| 57 | |
| 58 | it('tolerates whitespace around separators', () => { |
| 59 | const entries = parseDeprecatedToolkitsHeader( |
| 60 | ' "GMAIL" ; version = "20250114_00" ; sunset = @1787788800 ,"STRAVA";version="20240902_00" ' |
| 61 | ); |
| 62 | expect(entries).toEqual([ |
| 63 | { slug: 'GMAIL', version: '20250114_00', sunsetAt: new Date(1787788800 * 1000) }, |
| 64 | { slug: 'STRAVA', version: '20240902_00' }, |
| 65 | ]); |
| 66 | }); |
| 67 | |
| 68 | it('returns an empty list for garbage and for an empty string', () => { |
| 69 | expect(parseDeprecatedToolkitsHeader('')).toEqual([]); |
| 70 | expect(parseDeprecatedToolkitsHeader(' ')).toEqual([]); |
| 71 | expect(parseDeprecatedToolkitsHeader('not a structured field')).toEqual([]); |
| 72 | expect(parseDeprecatedToolkitsHeader('GMAIL;version=20250114_00')).toEqual([]); |
| 73 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version="unterminated')).toEqual([]); |
| 74 | expect(parseDeprecatedToolkitsHeader(',,,;;;===')).toEqual([]); |
| 75 | }); |
| 76 | |
| 77 | it('ignores unknown parameters', () => { |
| 78 | expect( |
| 79 | parseDeprecatedToolkitsHeader('"GMAIL";version="20250114_00";severity=3;flag;note="x"') |
| 80 | ).toEqual([{ slug: 'GMAIL', version: '20250114_00' }]); |
| 81 | }); |
| 82 | |
| 83 | it('ignores a parameter named after an inherited object property', () => { |
| 84 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version="1";constructor="x"')).toEqual([ |
| 85 | { slug: 'GMAIL', version: '1' }, |
| 86 | ]); |
| 87 | }); |
| 88 | |
| 89 | it('drops an empty item but keeps its siblings', () => { |
| 90 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version="1", ;;')).toEqual([ |
| 91 | { slug: 'GMAIL', version: '1' }, |
| 92 | ]); |
| 93 | }); |
| 94 | |
| 95 | it('drops an item without a version but keeps its siblings', () => { |
| 96 | expect(parseDeprecatedToolkitsHeader(`"GMAIL";deprecated=@1779840000, ${BARE_ITEM}`)).toEqual([ |
| 97 | { slug: 'STRAVA', version: '20240902_00' }, |
| 98 | ]); |
| 99 | }); |
| 100 | |
| 101 | it('drops an item whose known parameter has the wrong type', () => { |
| 102 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version=20250114_00')).toEqual([]); |
| 103 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version="1";deprecated="2026-05-27"')).toEqual( |
| 104 | [] |
| 105 | ); |
| 106 | expect(parseDeprecatedToolkitsHeader('"GMAIL";version="1";reason=lifecycle')).toEqual([]); |
| 107 | }); |
| 108 | |
| 109 | it('rejects invalid escapes in an sf-string', () => { |
| 110 | expect(parseDeprecatedToolkitsHeader('"GM\\nAIL";version="1"')).toEqual([]); |
| 111 | }); |
| 112 | }); |
| 113 | |
| 114 | describe('formatToolkitDeprecationWarnings', () => { |
| 115 | it('renders the full message with dates and reason', () => { |
| 116 | const [line] = formatToolkitDeprecationWarnings( |
| 117 | parseDeprecatedToolkitsHeader(FULL_ITEM), |
| 118 | DOCS_URL |
| 119 | ); |
| 120 | expect(line).toBe( |
| 121 | '[Deprecation] Toolkit GMAIL version 20250114_00 was deprecated on 2026-05-27 (lifecycle) ' + |
| 122 | 'and will stop working on 2026-08-27. ' + |
| 123 | "Pin a newer version with toolkitVersions: { gmail: '<version>' } or " + |
| 124 | `COMPOSIO_TOOLKIT_VERSION_GMAIL. See ${DOCS_URL}.` |
| 125 | ); |
| 126 | }); |
| 127 | |
| 128 | it('omits the reason and sunset clauses when the header omits them', () => { |
| 129 | const [line] = formatToolkitDeprecationWarnings( |
| 130 | [entry({ slug: 'STRAVA', version: '20240902_00' })], |
| 131 | DOCS_URL |
| 132 | ); |
| 133 | expect(line).toBe( |
| 134 | '[Deprecation] Toolkit STRAVA version 20240902_00 was deprecated. ' + |
| 135 | "Pin a newer version with toolkitVersions: { strava: '<version>' } or " + |
| 136 | `COMPOSIO_TOOLKIT_VERSION_STRAVA. See ${DOCS_URL}.` |
| 137 | ); |
| 138 | }); |
| 139 | |
| 140 | it('keeps the deprecation date when only the sunset is missing', () => { |
| 141 | const [line] = formatToolkitDeprecationWarnings( |
| 142 | [entry({ deprecatedAt: new Date(1779840000 * 1000), reason: 'security' })], |
| 143 | DOCS_URL |
| 144 | ); |
| 145 | expect(line).toContain('was deprecated on 2026-05-27 (security). Pin'); |
| 146 | expect(line).not.toContain('stop working'); |
| 147 | }); |
| 148 | |
| 149 | it('defaults to the published docs anchor', () => { |
| 150 | const [line] = formatToolkitDeprecationWarnings([entry()]); |
| 151 | expect(line).toContain(`See ${TOOLKIT_DEPRECATION_DOCS_URL}.`); |
| 152 | expect(TOOLKIT_DEPRECATION_DOCS_URL).toBe( |
| 153 | 'https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset' |
| 154 | ); |
| 155 | }); |
| 156 | |
| 157 | it('groups six versions of one slug into one line naming five', () => { |
| 158 | const entries = ['01', '02', '03', '04', '05', '06'].map(suffix => |
| 159 | entry({ |
| 160 | version: `202501${suffix}_00`, |
| 161 | sunsetAt: new Date(Date.UTC(2026, 7, Number(suffix) + 20)), |
| 162 | }) |
| 163 | ); |
| 164 | const lines = formatToolkitDeprecationWarnings(entries, DOCS_URL); |
| 165 | expect(lines).toHaveLength(1); |
| 166 | expect(lines[0]).toBe( |
| 167 | '[Deprecation] Toolkit GMAIL versions 20250101_00, 20250102_00, 20250103_00, 20250104_00, ' + |
| 168 | '20250105_00 and 1 more are deprecated and the earliest will stop working on 2026-08-21. ' + |
| 169 | "Pin a newer version with toolkitVersions: { gmail: '<version>' } or " + |
| 170 | `COMPOSIO_TOOLKIT_VERSION_GMAIL. See ${DOCS_URL}.` |
| 171 | ); |
| 172 | }); |
| 173 | |
| 174 | it('renders one line per slug, grouping case-insensitively', () => { |
| 175 | const lines = formatToolkitDeprecationWarnings( |
| 176 | [ |
| 177 | entry({ slug: 'GMAIL', version: '1' }), |
| 178 | entry({ slug: 'STRAVA', version: '1' }), |
| 179 | entry({ slug: 'gmail', version: '2' }), |
| 180 | ], |
| 181 | DOCS_URL |
| 182 | ); |
| 183 | expect(lines).toHaveLength(2); |
| 184 | expect(lines[0]).toContain('Toolkit GMAIL versions 1, 2 are deprecated.'); |
| 185 | expect(lines[1]).toContain('Toolkit STRAVA version 1 was deprecated.'); |
| 186 | }); |
| 187 | |
| 188 | it('returns no lines for no entries', () => { |
| 189 | expect(formatToolkitDeprecationWarnings([], DOCS_URL)).toEqual([]); |
| 190 | }); |
| 191 | }); |
| 192 | |
| 193 | describe('createToolkitDeprecationFetch', () => { |
| 194 | const response = (headers: Record<string, string> = {}): Response => |
| 195 | new Response('{"ok":true}', { status: 200, headers }); |
| 196 | |
| 197 | beforeEach(() => { |
| 198 | _resetToolkitDeprecationWarningsForTests(); |
| 199 | vi.spyOn(logger, 'warn').mockImplementation(() => undefined); |
| 200 | vi.spyOn(logger, 'debug').mockImplementation(() => undefined); |
| 201 | }); |
| 202 | |
| 203 | afterEach(() => { |
| 204 | vi.restoreAllMocks(); |
| 205 | _resetToolkitDeprecationWarningsForTests(); |
| 206 | }); |
| 207 | |
| 208 | it('warns once per toolkit version across calls and returns the response unchanged', async () => { |
| 209 | const base = vi.fn(async () => response({ [TOOLKIT_DEPRECATION_HEADER]: FULL_ITEM })); |
| 210 | const wrapped = createToolkitDeprecationFetch(base); |
| 211 | |
| 212 | const first = await wrapped('https://backend.composio.test/api/v3/toolkits/gmail'); |
| 213 | const second = await wrapped('https://backend.composio.test/api/v3/toolkits/gmail'); |
| 214 | |
| 215 | expect(base).toHaveBeenCalledTimes(2); |
| 216 | expect(logger.warn).toHaveBeenCalledTimes(1); |
| 217 | expect(String(vi.mocked(logger.warn).mock.calls[0]?.[0])).toContain( |
| 218 | 'GMAIL version 20250114_00' |
| 219 | ); |
| 220 | expect(await first.json()).toEqual({ ok: true }); |
| 221 | expect(await second.json()).toEqual({ ok: true }); |
| 222 | }); |
| 223 | |
| 224 | it('matches the header name case-insensitively', async () => { |
| 225 | const wrapped = createToolkitDeprecationFetch(async () => |
| 226 | response({ 'Composio-Deprecated-Toolkits': BARE_ITEM }) |
| 227 | ); |
| 228 | await wrapped('https://backend.composio.test/api/v3/toolkits/strava'); |
| 229 | expect(logger.warn).toHaveBeenCalledTimes(1); |
| 230 | }); |
| 231 | |
| 232 | it('warns for a second toolkit version even after the first was deduped', async () => { |
| 233 | const wrapped = createToolkitDeprecationFetch(async () => |
| 234 | response({ [TOOLKIT_DEPRECATION_HEADER]: `${FULL_ITEM}, ${BARE_ITEM}` }) |
| 235 | ); |
| 236 | await wrapped('https://backend.composio.test/a'); |
| 237 | expect(logger.warn).toHaveBeenCalledTimes(2); |
| 238 | |
| 239 | const next = createToolkitDeprecationFetch(async () => |
| 240 | response({ [TOOLKIT_DEPRECATION_HEADER]: '"GMAIL";version="20250201_00"' }) |
| 241 | ); |
| 242 | await next('https://backend.composio.test/b'); |
| 243 | expect(logger.warn).toHaveBeenCalledTimes(3); |
| 244 | }); |
| 245 | |
| 246 | it('does nothing without the header and swallows a malformed value', async () => { |
| 247 | const plain = createToolkitDeprecationFetch(async () => response()); |
| 248 | const garbage = createToolkitDeprecationFetch(async () => |
| 249 | response({ [TOOLKIT_DEPRECATION_HEADER]: '%%% nope' }) |
| 250 | ); |
| 251 | expect(await (await plain('https://backend.composio.test/a')).json()).toEqual({ ok: true }); |
| 252 | expect(await (await garbage('https://backend.composio.test/b')).json()).toEqual({ ok: true }); |
| 253 | expect(logger.warn).not.toHaveBeenCalled(); |
| 254 | }); |
| 255 | |
| 256 | it('warns again after the test reset helper clears the record', async () => { |
| 257 | const wrapped = createToolkitDeprecationFetch(async () => |
| 258 | response({ [TOOLKIT_DEPRECATION_HEADER]: BARE_ITEM }) |
| 259 | ); |
| 260 | await wrapped('https://backend.composio.test/a'); |
| 261 | _resetToolkitDeprecationWarningsForTests(); |
| 262 | await wrapped('https://backend.composio.test/a'); |
| 263 | expect(logger.warn).toHaveBeenCalledTimes(2); |
| 264 | }); |
| 265 | |
| 266 | it('resolves the global fetch per call when no base fetch is given', async () => { |
| 267 | const wrapped = createToolkitDeprecationFetch(); |
| 268 | const stub = vi.fn(async () => response({ [TOOLKIT_DEPRECATION_HEADER]: BARE_ITEM })); |
| 269 | vi.stubGlobal('fetch', stub); |
| 270 | try { |
| 271 | const result = await wrapped('https://backend.composio.test/a', { method: 'GET' }); |
| 272 | expect(stub).toHaveBeenCalledWith('https://backend.composio.test/a', { method: 'GET' }); |
| 273 | expect(result.status).toBe(200); |
| 274 | expect(logger.warn).toHaveBeenCalledTimes(1); |
| 275 | } finally { |
| 276 | vi.unstubAllGlobals(); |
| 277 | } |
| 278 | }); |
| 279 | |
| 280 | it('propagates a rejection from the underlying fetch untouched', async () => { |
| 281 | const failure = new TypeError('fetch failed'); |
| 282 | const wrapped = createToolkitDeprecationFetch(async () => { |
| 283 | throw failure; |
| 284 | }); |
| 285 | await expect(wrapped('https://backend.composio.test/a')).rejects.toBe(failure); |
| 286 | expect(logger.warn).not.toHaveBeenCalled(); |
| 287 | }); |
| 288 | |
| 289 | it('ignores a header longer than 2048 characters and still returns the body', async () => { |
| 290 | const oversized = `"GMAIL";version="1";reason="${'x'.repeat(2048)}"`; |
| 291 | const wrapped = createToolkitDeprecationFetch(async () => |
| 292 | response({ [TOOLKIT_DEPRECATION_HEADER]: oversized }) |
| 293 | ); |
| 294 | const result = await wrapped('https://backend.composio.test/a'); |
| 295 | expect(await result.json()).toEqual({ ok: true }); |
| 296 | expect(logger.warn).not.toHaveBeenCalled(); |
| 297 | }); |
| 298 | |
| 299 | it('ignores a header carrying a control character and still returns the body', async () => { |
| 300 | const wrapped = createToolkitDeprecationFetch(async () => |
| 301 | response({ [TOOLKIT_DEPRECATION_HEADER]: '"GMAIL";version="1";reason="\u001b[2J"' }) |
| 302 | ); |
| 303 | const result = await wrapped('https://backend.composio.test/a'); |
| 304 | expect(await result.json()).toEqual({ ok: true }); |
| 305 | expect(logger.warn).not.toHaveBeenCalled(); |
| 306 | }); |
| 307 | |
| 308 | it('stops recording new versions after 1024 keys without evicting the old ones', async () => { |
| 309 | let version = 0; |
| 310 | const wrapped = createToolkitDeprecationFetch(async () => |
| 311 | response({ [TOOLKIT_DEPRECATION_HEADER]: `"GMAIL";version="${version}"` }) |
| 312 | ); |
| 313 | const send = async (next: number) => { |
| 314 | version = next; |
| 315 | await wrapped('https://backend.composio.test/a'); |
| 316 | }; |
| 317 | |
| 318 | for (let next = 1; next <= 1024; next++) await send(next); |
| 319 | expect(logger.warn).toHaveBeenCalledTimes(1024); |
| 320 | |
| 321 | await send(1025); |
| 322 | expect(logger.warn).toHaveBeenCalledTimes(1024); |
| 323 | |
| 324 | for (let next = 1; next <= 1024; next++) await send(next); |
| 325 | expect(logger.warn).toHaveBeenCalledTimes(1024); |
| 326 | }); |
| 327 | |
| 328 | it('still resolves when the logger sink throws from both warn and debug', async () => { |
| 329 | vi.restoreAllMocks(); |
| 330 | const throwing = () => { |
| 331 | throw new Error('sink is broken'); |
| 332 | }; |
| 333 | const sink = { error: vi.fn(), warn: vi.fn(throwing), info: vi.fn(), debug: vi.fn(throwing) }; |
| 334 | logger.configure({ level: 'debug', sink }); |
| 335 | const wrapped = createToolkitDeprecationFetch(async () => |
| 336 | response({ [TOOLKIT_DEPRECATION_HEADER]: BARE_ITEM }) |
| 337 | ); |
| 338 | try { |
| 339 | const result = await wrapped('https://backend.composio.test/a'); |
| 340 | expect(await result.json()).toEqual({ ok: true }); |
| 341 | expect(sink.warn).toHaveBeenCalledTimes(1); |
| 342 | expect(sink.debug).toHaveBeenCalledTimes(1); |
| 343 | } finally { |
| 344 | logger.configure({ level: 'info', sink: console }); |
| 345 | } |
| 346 | }); |
| 347 | |
| 348 | it('logs at debug and still returns the response when inspecting the header throws', async () => { |
| 349 | const broken = response({ [TOOLKIT_DEPRECATION_HEADER]: BARE_ITEM }); |
| 350 | Object.defineProperty(broken, 'headers', { |
| 351 | get() { |
| 352 | throw new Error('headers unavailable'); |
| 353 | }, |
| 354 | }); |
| 355 | const wrapped = createToolkitDeprecationFetch(async () => broken); |
| 356 | const result = await wrapped('https://backend.composio.test/a'); |
| 357 | expect(result).toBe(broken); |
| 358 | expect(logger.debug).toHaveBeenCalledTimes(1); |
| 359 | expect(logger.warn).not.toHaveBeenCalled(); |
| 360 | }); |
| 361 | }); |