Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 1 | /** Shared version guidance for agent-facing markdown. */ |
| 2 | |
| 3 | import { |
| 4 | API_BASE_URLS, |
| 5 | detectApiVersion, |
| 6 | isReferenceUrl, |
| 7 | toCurrentVersionUrl, |
| 8 | } from './api-version'; |
| 9 | |
| 10 | /** Baseline guidance for all REST operations. */ |
| 11 | export const REST_VERSION_GUIDANCE = `## REST API version |
| 12 | |
| 13 | The current REST API version is **v3.1**, served at \`${API_BASE_URLS['3.1']}\`. Prefer it for new code and new examples. |
| 14 | |
| 15 | \`${API_BASE_URLS['3.0']}\` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.`; |
| 16 | |
| 17 | /** Version-stripped tool paths whose defaults need explicit guidance. */ |
| 18 | export const TOOL_VERSION_PATHS = [ |
| 19 | '/tools', |
| 20 | '/tools/{tool_slug}', |
| 21 | '/tools/execute/{tool_slug}', |
| 22 | '/tools/execute/{tool_slug}/input', |
| 23 | '/tools/scopes/required', |
| 24 | ] as const; |
| 25 | |
| 26 | /** Guidance for the tool-endpoint defaults that differ across REST versions. */ |
| 27 | export const TOOL_VERSION_GUIDANCE = `## Tool-endpoint version defaults on v3.1 |
| 28 | |
| 29 | On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned \`00000000_00\` version. \`POST /tools/scopes/required\` is v3.1-only. |
| 30 | |
| 31 | | Endpoint | Version parameter | |
| 32 | | --- | --- | |
| 33 | | \`GET /tools\` | \`toolkit_versions\` (query) | |
| 34 | | \`GET /tools/{tool_slug}\` | \`version\` or \`toolkit_versions\` (query) | |
| 35 | | \`POST /tools/execute/{tool_slug}\` | \`version\` (body) | |
| 36 | | \`POST /tools/execute/{tool_slug}/input\` | \`version\` (body) | |
| 37 | | \`POST /tools/scopes/required\` | \`version\` (body) | |
| 38 | |
| 39 | A v3.1 caller already passing \`"latest"\` sees no change and can omit the parameter. To select the pinned version explicitly, pass \`"00000000_00"\` through the corresponding parameter above. |
| 40 | |
| 41 | This version-default change is limited to the five endpoints above.`; |
| 42 | |
| 43 | const TOOL_VERSION_PATH_SET: ReadonlySet<string> = new Set(TOOL_VERSION_PATHS); |
| 44 | |
| 45 | /** Longest prefix first to avoid matching `/api/v3` inside `/api/v3.1`. */ |
| 46 | const VERSION_PREFIXES = ['/api/v3.1', '/api/v3'] as const; |
| 47 | |
| 48 | /** |
| 49 | * Replaces stale OpenAPI default prose with the deployed REST-version default. |
| 50 | * The source specs are generated upstream, so the agent-facing renderer fixes |
| 51 | * their description without mutating the generated snapshots. |
| 52 | */ |
| 53 | export function toolVersionParameterDescription( |
| 54 | rawSpecPath: string, |
| 55 | description = 'Tool version to use' |
| 56 | ): string { |
| 57 | if (!isToolVersionPath(rawSpecPath)) return description; |
| 58 | |
| 59 | const apiVersion = rawSpecPath.startsWith('/api/v3.1') ? '3.1' : '3.0'; |
| 60 | const defaultVersion = apiVersion === '3.1' ? 'latest' : '00000000_00'; |
| 61 | const withoutDefault = description.replace(/\s*\(?defaults?\s+to\b[\s\S]*$/i, '').trim(); |
| 62 | const base = (withoutDefault || 'Tool version to use').replace(/[.:]\s*$/, ''); |
| 63 | |
| 64 | return `${base}. Defaults to \`${defaultVersion}\` when omitted on REST API v${apiVersion}.`; |
| 65 | } |
| 66 | |
| 67 | /** |
| 68 | * The short version pointer for a reference page: which version this page |
| 69 | * documents, its base URL, and — on a legacy page — the link to the same page |
| 70 | * on v3.1. Empty outside the reference tree. |
| 71 | * |
| 72 | * A pointer, not guidance: the guardrail block (MDX pages) or |
| 73 | * `REST_VERSION_GUIDANCE` (operation pages) already carries the explanation |
| 74 | * further down the same response, and repeating it would put the same |
| 75 | * paragraph twice. Both renderers call this so their pointers agree by |
| 76 | * construction. |
| 77 | */ |
| 78 | export function apiVersionPointer(pageUrl: string): string { |
| 79 | if (!isReferenceUrl(pageUrl)) return ''; |
| 80 | |
| 81 | if (detectApiVersion(pageUrl) === '3.0') { |
| 82 | const currentUrl = `${toCurrentVersionUrl(pageUrl)}.md`; |
| 83 | return `\n> **API version:** This page documents Composio REST API v3.0 at \`${API_BASE_URLS['3.0']}\`, the previous version. v3.1 is current, at \`${API_BASE_URLS['3.1']}\` — the same page on v3.1 is ${currentUrl}.\n`; |
| 84 | } |
| 85 | |
| 86 | return `\n> **API version:** This page documents Composio REST API v3.1, the current version, at \`${API_BASE_URLS['3.1']}\`. \`${API_BASE_URLS['3.0']}\` is the previous version and remains supported.\n`; |
| 87 | } |
| 88 | |
| 89 | export function isToolVersionPath(rawSpecPath: string): boolean { |
| 90 | for (const prefix of VERSION_PREFIXES) { |
| 91 | if (rawSpecPath.startsWith(prefix)) { |
| 92 | return TOOL_VERSION_PATH_SET.has(rawSpecPath.slice(prefix.length)); |
| 93 | } |
| 94 | } |
| 95 | return false; |
| 96 | } |