@devries-cameron20 / composio Mirror · read-only / commits / 3fb74d5c9
Fork 0

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, 14:45 UTC

fix(docs): render KB identifier URLs as code spans, not dead links

Nightly external-link sweeps (#4205) failed on four KB URLs that are machine identifiers, not documents: Google OAuth scope URIs (googleapis.com/auth/meetings.space.*) and Ahrefs API surface roots (api.ahrefs.com/v3, the wrong-host ahrefs.com/v3). Support prose cites them bare, the KB generator copied them verbatim, and GFM autolinks published them as links that 404 by design — unfixable by pointing them anywhere. The generation layer now demotes bare citations and <url> autolinks of these identifier shapes to inline code spans, matching the convention sibling KB articles already use. Explicit markdown links keep their authored form. Regenerated the two affected guides. Verified: bun run test (506 pass), bun run lint:links, bun run lint:links:external (0 errors — the failing nightly command), bun run types:check, bun run generate:kb --check. Follow-up: docs/kb/semantic-index.json needs a rebuild with OPENAI_API_KEY (bun run build:kb-semantic) because four embedded record chunks changed.

jkomyno committed Aug 26, 2026 at 01:22 UTC 3fb74d5c989d87198a0e17f9746189268c5fdad8
5 files changed +89 -8
docs/content/kb/guide/toolkits-ahrefs.mdx
+1 -1
@@ -13,4 +13,4 @@ aliases: ["/kb/toolkits/ahrefs-actions-use-the-api-host","ahrefs-actions-use-the
13 ---
14 ## Ahrefs actions must call api.ahrefs.com, not ahrefs.com
15
16 -Ahrefs API calls should use the API host https://api.ahrefs.com/v3. If Ahrefs actions or connection checks are hitting https://ahrefs.com/v3 and returning 404 HTML, treat it as a connector base-URL configuration problem rather than an API-key or request-payload issue. Confirm the failing request is using api.ahrefs.com; if it is not, contact Composio support with the redacted request or log ID for connector review.
16 +Ahrefs API calls should use the API host `https://api.ahrefs.com/v3`. If Ahrefs actions or connection checks are hitting `https://ahrefs.com/v3` and returning 404 HTML, treat it as a connector base-URL configuration problem rather than an API-key or request-payload issue. Confirm the failing request is using api.ahrefs.com; if it is not, contact Composio support with the redacted request or log ID for connector review.
docs/content/kb/guide/toolkits-googlemeet.mdx
+1 -1
@@ -17,7 +17,7 @@ Google Super is a separate toolkit with its own tool slugs. If the connected acc
17
18 ## Configure Meet scopes and enable the Google Meet API before creating Meet spaces
19
20 -For Meet space creation/settings through Google Super, include the Meet scopes https://www.googleapis.com/auth/meetings.space.created and https://www.googleapis.com/auth/meetings.space.settings in the auth config, then initiate a new connection so the new scopes are granted. Also enable the Google Meet API in the Google Cloud Console project backing the OAuth app.
20 +For Meet space creation/settings through Google Super, include the Meet scopes `https://www.googleapis.com/auth/meetings.space.created` and `https://www.googleapis.com/auth/meetings.space.settings` in the auth config, then initiate a new connection so the new scopes are granted. Also enable the Google Meet API in the Google Cloud Console project backing the OAuth app.
21
22 ## Fetch transcript entries by first resolving the conference record
23
docs/decisions/public-knowledge-base.md
+12
@@ -110,6 +110,18 @@ gap that is not already answered by current docs or a published KB guide.
110 Volatile pricing, entitlement, and security claims require an authoritative
111 public source and are not copied from dashboard FAQ prose by default.
112
113 +### Identifier URLs
114 +
115 +KB prose cites machine identifiers that happen to look like URLs: OAuth
116 +scope URIs such as `https://www.googleapis.com/auth/…` and API surface roots
117 +such as `https://api.ahrefs.com/v3`. These are not documents; fetching them
118 +404s by design, so they can never survive the nightly external-link sweep as
119 +links. The generation layer therefore demotes bare citations and `<url>`
120 +autolinks of these two shapes to inline code spans. Explicit markdown links
121 +keep their authored form — if one points at an identifier URL, the nightly
122 +sweep flags it for an upstream fix instead of the pipeline silently rewriting
123 +navigation the author wrote.
124 +
125 ## Routes and Navigation
126
127 - `/kb` is the knowledge-base landing page.
docs/lib/kb/generate.ts
+51 -6
@@ -89,12 +89,56 @@ function relatedFrontmatter(
89 ];
90 }
91
92 +/**
93 + * Identifier URLs cite machine identifiers — OAuth scope URIs and API
94 + * surface roots such as `https://api.example.com/v3` — not documents. They
95 + * respond 404 by design, so they must never publish as links the nightly
96 + * external-link sweep would have to keep alive: they render as code spans.
97 + */
98 +export function isIdentifierUrl(raw: string): boolean {
99 + let url: URL;
100 + try {
101 + url = new URL(raw);
102 + } catch {
103 + return false;
104 + }
105 + if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.search || url.hash) {
106 + return false;
107 + }
108 + // Google OAuth scope URIs (https://www.googleapis.com/auth/…) identify a
109 + // permission; the namespace serves no pages.
110 + if (url.hostname === 'www.googleapis.com' && url.pathname.startsWith('/auth/')) {
111 + return true;
112 + }
113 + // An API surface root: a version-only path such as `/v3` or `/v1beta/`.
114 + // Deep paths (`/v3/tools/X`) stay links because they name real resources.
115 + return /^\/v\d[\w.-]*\/?$/.test(url.pathname);
116 +}
117 +
118 +/**
119 + * Wraps bare identifier URLs in code spans. URLs already presented as links —
120 + * markdown link labels `[url](…)`, link targets `](url)`, and anything
121 + * adjacent to a code span — keep their form; only bare citations and
122 + * `<url>` autolinks (normalized earlier) become code.
123 + */
124 +function identifierUrlsToCodeSpans(segment: string): string {
125 + return segment.replace(/(?<![`(\]\[])https?:\/\/[^\s`<>\[\]()]+/g, match => {
126 + // GFM autolinks drop trailing punctuation; keep it outside the code span.
127 + const url = match.replace(/[.,;:!?'"]+$/, '');
128 + if (!isIdentifierUrl(url)) return match;
129 + return `\`${url}\`${match.slice(url.length)}`;
130 + });
131 +}
132 +
133 function escapeMdxProse(line: string): string {
93 - const escapeSegment = (segment: string): string => segment
94 - .replace(/<(https?:\/\/[^>\s]+)>/g, '[$1]($1)')
95 - .replace(/<([^>\n]+)>/g, '&lt;$1&gt;')
96 - .replace(/\{/g, '&#123;')
97 - .replace(/\}/g, '&#125;');
134 + const escapeSegment = (segment: string): string => identifierUrlsToCodeSpans(
135 + segment
136 + .replace(/<(https?:\/\/[^>\s]+)>/g, (match, url: string) =>
137 + isIdentifierUrl(url) ? `\`${url}\`` : `[${url}](${url})`)
138 + .replace(/<([^>\n]+)>/g, '&lt;$1&gt;')
139 + .replace(/\{/g, '&#123;')
140 + .replace(/\}/g, '&#125;'),
141 + );
142
143 let result = '';
144 let cursor = 0;
@@ -117,7 +161,8 @@ function escapeMdxProse(line: string): string {
161 /**
162 * Converts authoritative CommonMark into MDX-safe Markdown. The source and
163 * article snapshots stay verbatim; only the generated presentation escapes MDX
120 - * expressions, normalizes autolinks, and opts support snippets out of Twoslash.
164 + * expressions, normalizes autolinks, demotes identifier URLs to code spans,
165 + * and opts support snippets out of Twoslash.
166 */
167 export function markdownForMdx(markdown: string): string {
168 let fence: { marker: string; length: number } | null = null;
docs/tests/static/kb-generation.test.ts
+24
@@ -38,6 +38,30 @@ describe('public KB content generation', () => {
38 ].join('\n'));
39 });
40
41 + test('demotes bare identifier URLs to code spans so they never publish as dead links', () => {
42 + expect(markdownForMdx([
43 + 'Ahrefs API calls should use the API host https://api.ahrefs.com/v3. If actions are hitting https://ahrefs.com/v3 and returning 404 HTML, treat it as a configuration problem.',
44 + 'Include the Meet scopes https://www.googleapis.com/auth/meetings.space.created and https://www.googleapis.com/auth/meetings.space.settings in the auth config.',
45 + 'Read https://developers.google.com/identity/protocols/oauth2 and [the policy](https://developers.google.com/identity/protocols/oauth2/policies) for details.',
46 + 'Explicit syntax keeps its form: <https://developers.google.com/identity/protocols/oauth2> stays a link, [scope](https://www.googleapis.com/auth/gmail.send) and <https://www.googleapis.com/auth/gmail.send> cite identifiers, so only the first remains a link.',
47 + 'Already code: `https://www.googleapis.com/auth/drive` and deep API paths such as https://backend.composio.dev/api/v3/tools/X remain links.',
48 + '',
49 + '```text',
50 + 'const scope = "https://www.googleapis.com/auth/drive";',
51 + '```',
52 + ].join('\n'))).toBe([
53 + 'Ahrefs API calls should use the API host `https://api.ahrefs.com/v3`. If actions are hitting `https://ahrefs.com/v3` and returning 404 HTML, treat it as a configuration problem.',
54 + 'Include the Meet scopes `https://www.googleapis.com/auth/meetings.space.created` and `https://www.googleapis.com/auth/meetings.space.settings` in the auth config.',
55 + 'Read https://developers.google.com/identity/protocols/oauth2 and [the policy](https://developers.google.com/identity/protocols/oauth2/policies) for details.',
56 + 'Explicit syntax keeps its form: [https://developers.google.com/identity/protocols/oauth2](https://developers.google.com/identity/protocols/oauth2) stays a link, [scope](https://www.googleapis.com/auth/gmail.send) and `https://www.googleapis.com/auth/gmail.send` cite identifiers, so only the first remains a link.',
57 + 'Already code: `https://www.googleapis.com/auth/drive` and deep API paths such as https://backend.composio.dev/api/v3/tools/X remain links.',
58 + '',
59 + '```text',
60 + 'const scope = "https://www.googleapis.com/auth/drive";',
61 + '```',
62 + ].join('\n'));
63 + });
64 +
65 test('defines multi-source provenance in the KB frontmatter schema', () => {
66 const sourceConfig = readFileSync(join(process.cwd(), 'source.config.ts'), 'utf8');
67