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 | * Toolkit version deprecation warnings. |
| 3 | * |
| 4 | * When a request resolves to a deprecated toolkit version, the API adds a |
| 5 | * `Composio-Deprecated-Toolkits` response header (an RFC 9651 structured-field |
| 6 | * list). This module parses that header below the generated client, through a |
| 7 | * `fetch` wrapper, and warns once per process for each deprecated toolkit |
| 8 | * version it sees. The response itself is never read, cloned or altered. |
| 9 | * |
| 10 | * Example header: |
| 11 | * |
| 12 | * "GMAIL";version="20250114_00";deprecated=@1779840000;sunset=@1787788800;reason="lifecycle" |
| 13 | */ |
| 14 | import { z } from 'zod'; |
| 15 | import logger from './logger'; |
| 16 | import { normalizeToolkitSlug } from './toolkitVersion'; |
| 17 | |
| 18 | /** Response header name. `Headers.get` is case-insensitive. */ |
| 19 | export const TOOLKIT_DEPRECATION_HEADER = 'composio-deprecated-toolkits'; |
| 20 | |
| 21 | /** Anchor of the docs section every warning points at. */ |
| 22 | export const TOOLKIT_DEPRECATION_DOCS_URL = |
| 23 | 'https://docs.composio.dev/docs/tools-direct/toolkit-versioning#deprecation-and-sunset'; |
| 24 | |
| 25 | /** Versions named per toolkit before the formatter collapses the rest into "and N more". */ |
| 26 | const MAX_VERSIONS_PER_LINE = 5; |
| 27 | |
| 28 | /** |
| 29 | * The three limits below mirror the `@composio/client` deprecation module, |
| 30 | * which reads the same kind of server-controlled header. |
| 31 | */ |
| 32 | /** A header longer than this is ignored whole rather than parsed. */ |
| 33 | const MAX_HEADER_LENGTH = 2048; |
| 34 | /** A header holding any of these is ignored whole, so nothing partially cleaned reaches the log. */ |
| 35 | const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/; |
| 36 | /** Keys the process will ever record; past this, new versions are neither recorded nor warned about. */ |
| 37 | const MAX_TRACKED_VERSIONS = 1024; |
| 38 | |
| 39 | const DeprecatedToolkitEntrySchema = z.object({ |
| 40 | slug: z.string().min(1), |
| 41 | version: z.string().min(1), |
| 42 | deprecatedAt: z.date().optional(), |
| 43 | sunsetAt: z.date().optional(), |
| 44 | reason: z.string().min(1).optional(), |
| 45 | }); |
| 46 | |
| 47 | export type DeprecatedToolkitEntry = z.infer<typeof DeprecatedToolkitEntrySchema>; |
| 48 | |
| 49 | /** Keys (`UPPER(slug)@version`) already warned about in this process. */ |
| 50 | const warnedToolkitVersions = new Set<string>(); |
| 51 | |
| 52 | const dedupeKey = (entry: Pick<DeprecatedToolkitEntry, 'slug' | 'version'>): string => |
| 53 | `${entry.slug.toUpperCase()}@${entry.version}`; |
| 54 | |
| 55 | /** |
| 56 | * Splits `value` on `delimiter` characters that sit outside double-quoted |
| 57 | * strings, honouring backslash escapes inside the quotes. Empty pieces are |
| 58 | * dropped and the rest are trimmed. |
| 59 | */ |
| 60 | const splitOutsideQuotes = (value: string, delimiter: string): string[] => { |
| 61 | const pieces: string[] = []; |
| 62 | let current = ''; |
| 63 | let inString = false; |
| 64 | for (let index = 0; index < value.length; index++) { |
| 65 | const char = value[index]; |
| 66 | if (inString) { |
| 67 | current += char; |
| 68 | if (char === '\\' && index + 1 < value.length) { |
| 69 | index += 1; |
| 70 | current += value[index]; |
| 71 | } else if (char === '"') { |
| 72 | inString = false; |
| 73 | } |
| 74 | } else if (char === '"') { |
| 75 | inString = true; |
| 76 | current += char; |
| 77 | } else if (char === delimiter) { |
| 78 | pieces.push(current); |
| 79 | current = ''; |
| 80 | } else { |
| 81 | current += char; |
| 82 | } |
| 83 | } |
| 84 | pieces.push(current); |
| 85 | return pieces.map(piece => piece.trim()).filter(piece => piece.length > 0); |
| 86 | }; |
| 87 | |
| 88 | /** |
| 89 | * Decodes an sf-string (`"..."` with `\"` and `\\` escapes). Returns |
| 90 | * `undefined` for anything that is not a complete, validly escaped sf-string. |
| 91 | */ |
| 92 | const decodeSfString = (raw: string): string | undefined => { |
| 93 | const match = /^"((?:[^"\\]|\\.)*)"$/.exec(raw); |
| 94 | if (match === null) return undefined; |
| 95 | let invalidEscape = false; |
| 96 | const decoded = match[1].replace(/\\(.)/g, (_whole, escaped: string) => { |
| 97 | if (escaped === '"' || escaped === '\\') return escaped; |
| 98 | invalidEscape = true; |
| 99 | return ''; |
| 100 | }); |
| 101 | return invalidEscape ? undefined : decoded; |
| 102 | }; |
| 103 | |
| 104 | /** Decodes an sf-date (`@` followed by Unix seconds). */ |
| 105 | const decodeSfDate = (raw: string): Date | undefined => { |
| 106 | const match = /^@(-?\d{1,15})$/.exec(raw); |
| 107 | if (match === null) return undefined; |
| 108 | const date = new Date(Number(match[1]) * 1000); |
| 109 | return Number.isNaN(date.getTime()) ? undefined : date; |
| 110 | }; |
| 111 | |
| 112 | /** Header parameters the SDK understands, by wire name. */ |
| 113 | const KNOWN_PARAMETERS = new Map< |
| 114 | string, |
| 115 | { name: Exclude<keyof DeprecatedToolkitEntry, 'slug'>; kind: 'string' | 'date' } |
| 116 | >([ |
| 117 | ['version', { name: 'version', kind: 'string' }], |
| 118 | ['reason', { name: 'reason', kind: 'string' }], |
| 119 | ['deprecated', { name: 'deprecatedAt', kind: 'date' }], |
| 120 | ['sunset', { name: 'sunsetAt', kind: 'date' }], |
| 121 | ]); |
| 122 | |
| 123 | /** |
| 124 | * Parses one list item: an sf-string slug followed by `;key=value` parameters. |
| 125 | * Unknown parameters are ignored; a known parameter with the wrong type drops |
| 126 | * the item. |
| 127 | */ |
| 128 | const parseItem = (item: string): DeprecatedToolkitEntry | undefined => { |
| 129 | const [head, ...params] = splitOutsideQuotes(item, ';'); |
| 130 | if (head === undefined) return undefined; |
| 131 | const candidate: Record<string, unknown> = { slug: decodeSfString(head) }; |
| 132 | for (const param of params) { |
| 133 | const separator = param.indexOf('='); |
| 134 | if (separator === -1) continue; |
| 135 | const key = param.slice(0, separator).trim(); |
| 136 | const rawValue = param.slice(separator + 1).trim(); |
| 137 | const field = KNOWN_PARAMETERS.get(key); |
| 138 | if (field === undefined) continue; |
| 139 | const decoded = field.kind === 'string' ? decodeSfString(rawValue) : decodeSfDate(rawValue); |
| 140 | if (decoded === undefined) return undefined; |
| 141 | candidate[field.name] = decoded; |
| 142 | } |
| 143 | const parsed = DeprecatedToolkitEntrySchema.safeParse(candidate); |
| 144 | return parsed.success ? parsed.data : undefined; |
| 145 | }; |
| 146 | |
| 147 | /** |
| 148 | * Parses a `Composio-Deprecated-Toolkits` header value. Items that fail to |
| 149 | * parse are dropped silently; garbage input yields an empty array. Never throws. |
| 150 | */ |
| 151 | export function parseDeprecatedToolkitsHeader(value: string): DeprecatedToolkitEntry[] { |
| 152 | try { |
| 153 | const entries: DeprecatedToolkitEntry[] = []; |
| 154 | for (const item of splitOutsideQuotes(value, ',')) { |
| 155 | const entry = parseItem(item); |
| 156 | if (entry !== undefined) entries.push(entry); |
| 157 | } |
| 158 | return entries; |
| 159 | } catch { |
| 160 | return []; |
| 161 | } |
| 162 | } |
| 163 | |
| 164 | const isoDate = (date: Date): string => date.toISOString().slice(0, 10); |
| 165 | |
| 166 | const pinHint = (slug: string, docsUrl: string): string => { |
| 167 | const configKey = normalizeToolkitSlug(slug); |
| 168 | const envVar = `COMPOSIO_TOOLKIT_VERSION_${slug.toUpperCase()}`; |
| 169 | return `Pin a newer version with toolkitVersions: { ${configKey}: '<version>' } or ${envVar}. See ${docsUrl}.`; |
| 170 | }; |
| 171 | |
| 172 | const formatSingle = (entry: DeprecatedToolkitEntry, docsUrl: string): string => { |
| 173 | let sentence = `[Deprecation] Toolkit ${entry.slug.toUpperCase()} version ${entry.version} was deprecated`; |
| 174 | if (entry.deprecatedAt !== undefined) sentence += ` on ${isoDate(entry.deprecatedAt)}`; |
| 175 | if (entry.reason !== undefined) sentence += ` (${entry.reason})`; |
| 176 | if (entry.sunsetAt !== undefined) |
| 177 | sentence += ` and will stop working on ${isoDate(entry.sunsetAt)}`; |
| 178 | return `${sentence}. ${pinHint(entry.slug, docsUrl)}`; |
| 179 | }; |
| 180 | |
| 181 | const formatGroup = (slug: string, entries: DeprecatedToolkitEntry[], docsUrl: string): string => { |
| 182 | const versions = entries.map(entry => entry.version); |
| 183 | const named = versions.slice(0, MAX_VERSIONS_PER_LINE).join(', '); |
| 184 | const remaining = versions.length - MAX_VERSIONS_PER_LINE; |
| 185 | const list = remaining > 0 ? `${named} and ${remaining} more` : named; |
| 186 | let sentence = `[Deprecation] Toolkit ${slug} versions ${list} are deprecated`; |
| 187 | const sunsets = entries |
| 188 | .map(entry => entry.sunsetAt) |
| 189 | .filter((date): date is Date => date !== undefined) |
| 190 | .sort((a, b) => a.getTime() - b.getTime()); |
| 191 | if (sunsets.length > 0) { |
| 192 | sentence += ` and the earliest will stop working on ${isoDate(sunsets[0])}`; |
| 193 | } |
| 194 | return `${sentence}. ${pinHint(slug, docsUrl)}`; |
| 195 | }; |
| 196 | |
| 197 | /** |
| 198 | * Renders one warning line per toolkit slug. A slug with a single deprecated |
| 199 | * version gets the full sentence with its dates and reason; a slug with several |
| 200 | * names at most five versions and collapses the rest into "and N more". |
| 201 | */ |
| 202 | export function formatToolkitDeprecationWarnings( |
| 203 | entries: DeprecatedToolkitEntry[], |
| 204 | docsUrl: string = TOOLKIT_DEPRECATION_DOCS_URL |
| 205 | ): string[] { |
| 206 | const groups = new Map<string, DeprecatedToolkitEntry[]>(); |
| 207 | for (const entry of entries) { |
| 208 | const slug = entry.slug.toUpperCase(); |
| 209 | const group = groups.get(slug); |
| 210 | if (group === undefined) groups.set(slug, [entry]); |
| 211 | else group.push(entry); |
| 212 | } |
| 213 | return Array.from(groups, ([slug, group]) => |
| 214 | group.length === 1 ? formatSingle(group[0], docsUrl) : formatGroup(slug, group, docsUrl) |
| 215 | ); |
| 216 | } |
| 217 | |
| 218 | /** |
| 219 | * Parses the header on `response`, drops versions already warned about in this |
| 220 | * process, records the new ones and warns once per formatted line. |
| 221 | */ |
| 222 | const warnDeprecatedToolkits = (response: Response): void => { |
| 223 | const value = response.headers.get(TOOLKIT_DEPRECATION_HEADER); |
| 224 | if (value === null || value.length === 0) return; |
| 225 | if (value.length > MAX_HEADER_LENGTH || CONTROL_CHARACTERS.test(value)) return; |
| 226 | if (warnedToolkitVersions.size >= MAX_TRACKED_VERSIONS) return; |
| 227 | const fresh: DeprecatedToolkitEntry[] = []; |
| 228 | for (const entry of parseDeprecatedToolkitsHeader(value)) { |
| 229 | const key = dedupeKey(entry); |
| 230 | if (warnedToolkitVersions.has(key) || warnedToolkitVersions.size >= MAX_TRACKED_VERSIONS) |
| 231 | continue; |
| 232 | warnedToolkitVersions.add(key); |
| 233 | fresh.push(entry); |
| 234 | } |
| 235 | for (const line of formatToolkitDeprecationWarnings(fresh)) { |
| 236 | logger.warn(line); |
| 237 | } |
| 238 | }; |
| 239 | |
| 240 | /** |
| 241 | * Wraps a `fetch` implementation so every response is checked for the |
| 242 | * `Composio-Deprecated-Toolkits` header. The wrapper is `this`-independent, |
| 243 | * returns the response unchanged on every path and never fails a call over |
| 244 | * the header: any error while inspecting it is logged at debug and swallowed. |
| 245 | * |
| 246 | * When no `baseFetch` is given, `globalThis.fetch` is resolved per call so a |
| 247 | * runtime that installs or replaces `fetch` after construction still works. |
| 248 | */ |
| 249 | export function createToolkitDeprecationFetch( |
| 250 | baseFetch?: typeof globalThis.fetch |
| 251 | ): typeof globalThis.fetch { |
| 252 | return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => { |
| 253 | const target = baseFetch ?? globalThis.fetch; |
| 254 | const response = await target(input, init); |
| 255 | try { |
| 256 | warnDeprecatedToolkits(response); |
| 257 | } catch (error) { |
| 258 | try { |
| 259 | logger.debug('Failed to inspect the toolkit deprecation header', error); |
| 260 | } catch { |
| 261 | // The fallback is best-effort too: a sink that throws must not fail the call. |
| 262 | } |
| 263 | } |
| 264 | return response; |
| 265 | }; |
| 266 | } |
| 267 | |
| 268 | /** Clears the once-per-process record. Tests only. */ |
| 269 | export function _resetToolkitDeprecationWarningsForTests(): void { |
| 270 | warnedToolkitVersions.clear(); |
| 271 | } |