mirror of
https://github.com/ComposioHQ/composio.git
synced 2026-09-22 11:46:35 +08:00
Alberto Schiabel
6e0a9db3c7
This PR: - fixes [UXE-233](https://linear.app/composio/issue/UXE-233/docs-should-explicitly-direct-agents-to-use-v31-apis) - makes the agent-facing Markdown channels publish concrete REST v3.1 base URLs and endpoint tables while preserving the supported v3.0 reference tree - centralizes `REST_VERSION_GUIDANCE`, `TOOL_VERSION_GUIDANCE`, and raw-spec path matching in `lib/api-version-guidance.ts` - renders `ApiBaseUrl` and `ApiEndpointsTable` in authored MDX and adds an explicit version pointer to generated OpenAPI operation Markdown - separates current and legacy REST references in `llms.txt`, excludes v3.0 page bodies from `llms-full.txt`, and adds v3.1 selection guidance to Context7 - validates serialized `ApiEndpointsTable` payloads with Zod before generation while preserving forward-compatible fields - addresses review feedback for the renamed authentication page, SDK-reference pointer scope, generator validation behavior, and stale OpenAPI tool-version descriptions ## Context REST v3.0 is superseded but remains supported for existing integrations. This PR changes what new agent-generated code discovers first; it does not require existing v3.0 callers to migrate. Authenticated read-only probes against the deployed API confirmed that the affected v3 endpoints default to `00000000_00`, while their v3.1 counterparts default to `latest`. `POST /tools/scopes/required` is available only on v3.1 and defaults to `latest`. This PR does not move public URLs. A future `/reference/v3/` to `/reference/v3.0/` migration remains separate because it has independent compatibility and search-indexing risk. ## Verification - `bun test tests/static/` - `bun run build` - `bun run test:integration` - `bun run types:check` - `bun run lint` ## Review follow-up The version-default guidance is intentionally limited to the five verified tool endpoints. v3.1 is a structural superset of v3, so this PR does not claim route parity. Static coverage rejects broad non-tool parity wording in both the shared guidance and Context7 rules.
35 lines
1.3 KiB
TypeScript
35 lines
1.3 KiB
TypeScript
import { z } from 'zod';
|
|
|
|
/**
|
|
* The `endpoints={[...]}` prop of `<ApiEndpointsTable />`.
|
|
*
|
|
* `scripts/generate-api-index.ts` serializes this array into MDX as a JSON
|
|
* string, so every reader — the React component, the `.md` converter in
|
|
* `lib/source.ts`, and the route guard in
|
|
* `tests/static/api-reference-routes.test.ts` — is reading external data and
|
|
* parses it here once, with `z.infer` flowing downstream.
|
|
*
|
|
* Deliberately non-strict: unknown keys are stripped rather than rejected, so
|
|
* adding a field to the generator does not break rendering on pages generated
|
|
* before the field existed.
|
|
*/
|
|
export const apiEndpointSchema = z.object({
|
|
method: z.string(),
|
|
/** Path under the current prefix, e.g. `/api/v3.1/tools/{tool_slug}`. */
|
|
pathV31: z.string(),
|
|
/** Same operation under the previous prefix, e.g. `/api/v3/tools/{tool_slug}`. */
|
|
pathV3: z.string(),
|
|
summary: z.string(),
|
|
href: z.string(),
|
|
/**
|
|
* Set by the generator for operations flagged `deprecated` in the OpenAPI
|
|
* spec. Surfaced with the existing "Legacy" tag (see
|
|
* `components/legacy-badge.tsx`).
|
|
*/
|
|
legacy: z.boolean().optional(),
|
|
});
|
|
|
|
export const apiEndpointsSchema = z.array(apiEndpointSchema);
|
|
|
|
export type ApiEndpoint = z.infer<typeof apiEndpointSchema>;
|