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
+});