Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

10.6 KB
Raw Blame
/**
 * OpenAPI 3.1 description of remocn.dev's public HTTP API, served at
 * `/openapi.json`. Every path here maps to a route under `app/`;
 * lib/openapi.test.ts fails the build if one drifts from the file tree.
 *
 * The MCP server at `/mcp` speaks JSON-RPC (Model Context Protocol), not REST,
 * so it is described in `info.description` rather than as operations.
 */

const SITE_URL = "https://remocn.dev";

const ERROR_RESPONSE = (description: string) => ({
  description,
  content: {
    "application/json": { schema: { $ref: "#/components/schemas/Error" } },
  },
});

export const OPENAPI_SPEC = {
  openapi: "3.1.0",
  info: {
    title: "Remocn API",
    version: "1.0.0",
    summary:
      "Registry items, docs search and GitHub stargazers for Remocn, the shadcn registry of Remotion components.",
    description: [
      "Public, unauthenticated HTTP API behind remocn.dev.",
      "",
      "- **Install components** with the shadcn CLI (`npx shadcn@latest add @remocn/<name>`); it fetches `getRegistryItem` for you.",
      "- **Find components** with `getComponentIndex` (one Markdown table of every component) or `searchDocs`.",
      "- **Get a repository's stargazers** with `getStargazers`, e.g. as props for the `github-stars` component.",
      "",
      `Agents can also use the remote MCP server at ${SITE_URL}/mcp (Streamable HTTP, JSON-RPC, no auth) with the tools \`search_components\`, \`get_component\`, \`plan_video\` and \`preview_component\`.`,
      "",
      "Every error is JSON: `{ error, code }`, where `code` is a stable machine-readable string and `error` a human-readable message.",
    ].join("\n"),
    contact: {
      name: "Remocn",
      url: `${SITE_URL}/contact`,
      email: "[email protected]",
    },
    license: { name: "MIT", identifier: "MIT" },
  },
  externalDocs: {
    description: "Docs index for LLMs",
    url: `${SITE_URL}/llms.txt`,
  },
  servers: [{ url: SITE_URL }],
  tags: [
    { name: "Registry", description: "shadcn registry items." },
    { name: "Docs", description: "Documentation for people and agents." },
    {
      name: "GitHub",
      description: "GitHub data for the `github-stars` component.",
    },
  ],
  paths: {
    "/r/{file}": {
      get: {
        operationId: "getRegistryItem",
        tags: ["Registry"],
        summary: "Get a registry item",
        description:
          "Returns one shadcn registry item (the component's source files and dependencies) as JSON, the format the shadcn CLI installs from. Use `registry.json` for the whole registry index.",
        parameters: [
          {
            name: "file",
            in: "path",
            required: true,
            description:
              "Component name plus `.json`, e.g. `soft-blur-in.json`, or `registry.json` for the index.",
            schema: {
              type: "string",
              pattern: "^[a-z0-9][a-z0-9-]*\\.json$",
            },
          },
        ],
        responses: {
          "200": {
            description:
              "The registry item, as defined by https://ui.shadcn.com/schema/registry-item.json.",
            content: {
              "application/json": {
                schema: { $ref: "#/components/schemas/RegistryItem" },
              },
            },
          },
          "404": ERROR_RESPONSE("No registry item with that name."),
        },
      },
    },
    "/api/search": {
      get: {
        operationId: "searchDocs",
        tags: ["Docs"],
        summary: "Search the docs",
        description:
          "Search the docs by words and components by need. Full-text matches over every docs page, heading and paragraph, with the components that fit the query by meaning placed among them (`show that setup takes five minutes` finds a clock scene; the query can be in any language). Returns an empty array when `query` is missing.",
        parameters: [
          {
            name: "query",
            in: "query",
            required: true,
            description:
              "Search text: a name, a keyword or a described need, e.g. `blur transition`.",
            schema: { type: "string", minLength: 1 },
          },
          {
            name: "limit",
            in: "query",
            required: false,
            description: "Maximum number of results.",
            schema: { type: "integer", minimum: 1 },
          },
          {
            name: "tag",
            in: "query",
            required: false,
            description: "Comma-separated tags to filter by.",
            schema: { type: "string" },
          },
        ],
        responses: {
          "200": {
            description: "Matches, best first.",
            content: {
              "application/json": {
                schema: {
                  type: "array",
                  items: { $ref: "#/components/schemas/SearchResult" },
                },
              },
            },
          },
        },
      },
    },
    "/llms.txt": {
      get: {
        operationId: "getLlmsIndex",
        tags: ["Docs"],
        summary: "Get the docs index for LLMs",
        description:
          "llms.txt (https://llmstxt.org): when to use Remocn, how to call it, and a link to the Markdown of every docs page.",
        responses: {
          "200": {
            description: "The index, in llms.txt Markdown.",
            content: { "text/plain": { schema: { type: "string" } } },
          },
        },
      },
    },
    "/llms-components.txt": {
      get: {
        operationId: "getComponentIndex",
        tags: ["Docs"],
        summary: "Get the component index",
        description:
          "Every installable component in one Markdown table: when to use and avoid it, natural length, vibe, dependencies and a link to its page.",
        responses: {
          "200": {
            description: "The component index, in Markdown.",
            content: { "text/plain": { schema: { type: "string" } } },
          },
        },
      },
    },
    "/api/stargazers": {
      get: {
        operationId: "getStargazers",
        tags: ["GitHub"],
        summary: "Get a repository's stargazers",
        description:
          "Fetches a GitHub repository's stargazers server-side and returns a downsampled list ready to pass to the `github-stars` component.",
        parameters: [
          {
            name: "repo",
            in: "query",
            required: true,
            description:
              "`owner/name` or a github.com URL, e.g. `Remocn/remocn`.",
            schema: { type: "string", minLength: 1 },
          },
        ],
        responses: {
          "200": {
            description: "The repository's stargazers.",
            content: {
              "application/json": {
                schema: { $ref: "#/components/schemas/StargazersResult" },
              },
            },
          },
          "400": ERROR_RESPONSE(
            "Missing or malformed `repo` (code `invalid_repo`). Pass `owner/name` or a github.com URL.",
          ),
          "404": ERROR_RESPONSE(
            "Repository not found or its stargazers are private (code `not_found`).",
          ),
          "429": ERROR_RESPONSE(
            "GitHub rate limit reached (code `rate_limited`). Retry later.",
          ),
          "502": ERROR_RESPONSE(
            "GitHub request failed (code `fetch_failed`). Retry later.",
          ),
        },
      },
    },
  },
  components: {
    schemas: {
      Error: {
        type: "object",
        required: ["error", "code"],
        properties: {
          error: {
            type: "string",
            description: "Human-readable message.",
          },
          code: {
            type: "string",
            description:
              "Stable machine-readable code, e.g. `not_found`, `invalid_input`, `rate_limited`.",
          },
          hint: {
            type: "string",
            description: "What to do next, when the API knows.",
          },
          docs: {
            type: "string",
            format: "uri",
            description: "Where the API is described.",
          },
        },
      },
      RegistryItem: {
        type: "object",
        description:
          "A shadcn registry item. Full schema: https://ui.shadcn.com/schema/registry-item.json",
        required: ["name", "type"],
        properties: {
          $schema: { type: "string", format: "uri" },
          name: { type: "string" },
          type: { type: "string", examples: ["registry:component"] },
          title: { type: "string" },
          description: { type: "string" },
          dependencies: { type: "array", items: { type: "string" } },
          registryDependencies: { type: "array", items: { type: "string" } },
          files: {
            type: "array",
            items: {
              type: "object",
              required: ["path", "type"],
              properties: {
                path: { type: "string" },
                type: { type: "string" },
                target: { type: "string" },
                content: { type: "string" },
              },
            },
          },
        },
        additionalProperties: true,
      },
      SearchResult: {
        type: "object",
        required: ["id", "url", "type", "content"],
        properties: {
          id: { type: "string" },
          url: {
            type: "string",
            description: "Site-relative URL of the match.",
          },
          type: { type: "string", enum: ["page", "heading", "text"] },
          content: {
            type: "string",
            description: "Matched text, with hits wrapped in `<mark>`.",
          },
          breadcrumbs: { type: "array", items: { type: "string" } },
        },
      },
      Stargazer: {
        type: "object",
        required: ["login", "avatarUrl", "starredAt"],
        properties: {
          login: { type: "string" },
          avatarUrl: {
            type: "string",
            format: "uri",
            description: "Must be on avatars.githubusercontent.com.",
          },
          starredAt: {
            type: "string",
            description: "ISO 8601 date or timestamp.",
          },
        },
      },
      StargazersResult: {
        type: "object",
        required: ["owner", "repo", "totalStars", "truncated", "stargazers"],
        properties: {
          owner: { type: "string" },
          repo: { type: "string" },
          totalStars: { type: "integer", minimum: 0 },
          truncated: {
            type: "boolean",
            description:
              "True when the repo is past GitHub's ~40k-star listing ceiling.",
          },
          stargazers: {
            type: "array",
            items: { $ref: "#/components/schemas/Stargazer" },
          },
        },
      },
    },
  },
} as const;