@mehdad67/apitogo 0.1.24

package/src/lib/plugins/openapi/util/generateSchemaExample.ts

@@ -0,0 +1,191 @@
+import type { SchemaObject } from "../../../oas/graphql/index.js";
+import { isCircularRef } from "../schema/utils.js";
+
+const isIntegerSchema = (schema: SchemaObject): boolean =>
+  schema.type === "integer" ||
+  schema.format === "int32" ||
+  schema.format === "int64";
+
+const getNumberExample = (schema: SchemaObject): number => {
+  const min =
+    typeof schema.exclusiveMinimum === "number"
+      ? schema.exclusiveMinimum
+      : typeof schema.minimum === "number"
+        ? schema.minimum
+        : undefined;
+  const max =
+    typeof schema.exclusiveMaximum === "number"
+      ? schema.exclusiveMaximum
+      : typeof schema.maximum === "number"
+        ? schema.maximum
+        : undefined;
+
+  const offset = isIntegerSchema(schema) ? 1 : 0.1;
+  const minOffset = typeof schema.exclusiveMinimum === "number" ? offset : 0;
+  const maxOffset = typeof schema.exclusiveMaximum === "number" ? offset : 0;
+
+  if (min !== undefined && min >= 0) return min + minOffset;
+  if (max !== undefined && max <= 0) return max - maxOffset;
+  return 0;
+};
+
+const getStringExample = (schema: SchemaObject, name?: string): string => {
+  const base = name || "string";
+  const minLength = schema.minLength ?? 0;
+  if (base.length >= minLength) return base;
+  return base.padEnd(minLength, "a");
+};
+
+export const generateSchemaExample = (
+  schema?: SchemaObject,
+  name?: string,
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+): any => {
+  if (!schema || isCircularRef(schema)) {
+    return null;
+  }
+
+  if (schema.example !== undefined) {
+    return schema.example;
+  }
+
+  if (
+    schema.examples &&
+    typeof schema.examples === "object" &&
+    "default" in schema.examples
+  ) {
+    const defaultExample = schema.examples.default;
+    if (defaultExample !== null) {
+      return typeof defaultExample === "object" && "value" in defaultExample
+        ? defaultExample.value
+        : defaultExample;
+    }
+  }
+
+  if (schema.const !== undefined) {
+    return schema.const;
+  }
+
+  if (schema.default !== undefined) {
+    return schema.default;
+  }
+
+  // Resolve nullable array types (e.g. ["null", "string"]) to the non-null type
+  const schemaType = Array.isArray(schema.type)
+    ? (schema.type.find((t) => t !== "null") ?? schema.type[0])
+    : schema.type;
+
+  if (
+    schema.examples &&
+    Array.isArray(schema.examples) &&
+    schema.examples.length > 0
+  ) {
+    return schema.examples[0];
+  }
+
+  if (schemaType === "object" && schema.properties) {
+    // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+    const example: Record<string, any> = {};
+
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (typeof propSchema === "object") {
+        example[key] = generateSchemaExample(propSchema, key);
+      }
+    }
+
+    return example;
+  }
+
+  if (
+    schemaType === "object" &&
+    !schema.properties &&
+    schema.additionalProperties &&
+    typeof schema.additionalProperties === "object"
+  ) {
+    return { key: generateSchemaExample(schema.additionalProperties) };
+  }
+
+  if (schemaType === "array" && "items" in schema) {
+    if (Array.isArray(schema.items)) {
+      return schema.items.map((itemSchema) =>
+        generateSchemaExample(itemSchema),
+      );
+    }
+    if (schema.items) {
+      return [generateSchemaExample(schema.items)];
+    }
+    return [];
+  }
+
+  if (schemaType === "array") {
+    return [];
+  }
+
+  if (schema.format !== undefined) {
+    switch (schema.format) {
+      case "date-time":
+        return "2024-08-25T15:00:00Z";
+      case "date":
+        return "2024-08-25";
+      case "time":
+        return "15:00:00";
+      case "email":
+        return "test@example.com";
+      case "uri":
+        return "https://www.example.com/path/to/resource";
+      case "uri-reference":
+        return "/path/to/resource";
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+      case "ipv4":
+        return "192.168.1.1";
+      case "ipv6":
+        return "2001:0db8:85a3:0000:0000:8a2e:0370:7334";
+      case "hostname":
+        return "example.com";
+      case "password":
+        return "********";
+      case "byte":
+        return "U3dhZ2dlcg==";
+      case "binary":
+        return "<binary>";
+      case "duration":
+        return "P3D";
+      case "int32":
+      case "int64":
+      case "float":
+      case "double":
+        return getNumberExample(schema);
+    }
+  }
+
+  if (schema.enum) {
+    return schema.enum[0];
+  }
+
+  if (schema.oneOf && schema.oneOf.length > 0) {
+    const nonNull = schema.oneOf.find((s) => s.type !== "null");
+    return generateSchemaExample(nonNull ?? schema.oneOf[0]);
+  }
+
+  if (schema.anyOf && schema.anyOf.length > 0) {
+    const nonNull = schema.anyOf.find((s) => s.type !== "null");
+    return generateSchemaExample(nonNull ?? schema.anyOf[0]);
+  }
+
+  switch (schemaType) {
+    case "string":
+      return getStringExample(schema, name);
+    case "number":
+    case "integer":
+      return getNumberExample(schema);
+    case "boolean":
+      return true;
+    case "null":
+      return null;
+    case "object":
+      return {};
+    default:
+      return {};
+  }
+};

package/src/lib/plugins/openapi/util/getRoutes.tsx

@@ -0,0 +1,265 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import {
+  generatePath,
+  Navigate,
+  redirect,
+  type RouteObject,
+  useLocation,
+  useParams,
+} from "react-router";
+import { joinUrl } from "../../../util/joinUrl.js";
+import type { GraphQLClient } from "../client/GraphQLClient.js";
+import { useCreateQuery } from "../client/useCreateQuery.js";
+import { useOasConfig } from "../context.js";
+import {
+  GetNavigationOperationsQuery,
+  type OpenApiPluginOptions,
+  UNTAGGED_PATH,
+} from "../index.js";
+import type { OasPluginConfig, VersionEntry } from "../interfaces.js";
+
+const createOasProvider = (opts: {
+  routePath: string;
+  basePath: string;
+  version?: string;
+  routes: RouteObject[];
+  client: GraphQLClient;
+  config: OpenApiPluginOptions;
+}): RouteObject => ({
+  path: opts.routePath,
+  async lazy() {
+    const { OasProvider } = await import("../OasProvider.js");
+    return {
+      element: (
+        <OasProvider
+          basePath={opts.basePath}
+          version={opts.version}
+          client={opts.client}
+          config={opts.config}
+        />
+      ),
+    };
+  },
+  children: opts.routes,
+});
+
+const createRoute = ({
+  path,
+  tag,
+  untagged,
+}: {
+  path: string;
+  tag?: string;
+  untagged?: boolean;
+}): RouteObject => ({
+  path,
+  async lazy() {
+    const { OperationList } = await import("../OperationList.js");
+    return { element: <OperationList tag={tag} untagged={untagged} /> };
+  },
+});
+
+// Used when tagPages is not configured (e.g. URL schemas). Resolves tags at
+// runtime via GraphQL and redirects to the first available tag.
+const NonTagPagesOperationList = ({
+  render,
+  path,
+}: {
+  render: (tag: string) => React.ReactNode;
+  path: string;
+}) => {
+  const { type, input } = useOasConfig();
+  const { tag: currentTag } = useParams();
+  const location = useLocation();
+  const query = useCreateQuery(GetNavigationOperationsQuery, { type, input });
+  const {
+    data: { schema },
+  } = useSuspenseQuery(query);
+
+  const firstTag = schema.tags.at(0);
+
+  if (!currentTag && firstTag?.slug) {
+    return (
+      <Navigate
+        to={{
+          pathname: generatePath(path, { tag: firstTag.slug }),
+          search: location.search,
+        }}
+      />
+    );
+  }
+
+  if (currentTag && schema.tags.some((t) => t.slug === currentTag)) {
+    return render(currentTag);
+  }
+
+  return null;
+};
+
+const createNonTagPagesRoute = ({ path }: { path: string }): RouteObject => ({
+  path,
+  async lazy() {
+    const { OperationList } = await import("../OperationList.js");
+    return {
+      element: (
+        <NonTagPagesOperationList
+          path={path}
+          render={(tag) => <OperationList tag={tag} />}
+        />
+      ),
+    };
+  },
+});
+
+const createAdditionalRoutes = ({
+  basePath,
+  hasUntaggedOperations = true,
+}: {
+  basePath: string;
+  hasUntaggedOperations?: boolean;
+}) => [
+  ...(hasUntaggedOperations
+    ? [
+        createRoute({
+          path: joinUrl(basePath, UNTAGGED_PATH),
+          untagged: true,
+        }),
+      ]
+    : []),
+  {
+    path: joinUrl(basePath, "~schemas"),
+    lazy: async () => {
+      const { SchemaList } = await import("../SchemaList.js");
+      return { element: <SchemaList /> };
+    },
+  },
+];
+
+const createVersionRoutes = ({
+  versionPath,
+  tagPages,
+  hasUntaggedOperations = true,
+  showInfoPage = true,
+}: {
+  versionPath: string;
+  tagPages: string[];
+  hasUntaggedOperations?: boolean;
+  showInfoPage?: boolean;
+}): RouteObject[] => {
+  const firstTag =
+    tagPages.at(0) ?? (hasUntaggedOperations ? UNTAGGED_PATH : undefined);
+
+  const indexRoute: RouteObject = showInfoPage
+    ? {
+        index: true,
+        path: versionPath,
+        lazy: async () => {
+          const { SchemaInfo } = await import("../SchemaInfo.js");
+          return { element: <SchemaInfo /> };
+        },
+      }
+    : firstTag
+      ? { index: true, loader: () => redirect(joinUrl(versionPath, firstTag)) }
+      : createRoute({ path: versionPath });
+
+  return [
+    indexRoute,
+    ...tagPages.map((tag) =>
+      createRoute({ path: joinUrl(versionPath, tag), tag }),
+    ),
+    ...createAdditionalRoutes({ basePath: versionPath, hasUntaggedOperations }),
+  ];
+};
+
+export const getVersionMetadata = (config: OasPluginConfig) => {
+  if (config.type === "raw" || !Array.isArray(config.input)) {
+    return {
+      versions: [] as string[],
+      versionMap: {} as Record<
+        string,
+        { label: string; downloadUrl?: string; tagPages?: string[] }
+      >,
+    };
+  }
+
+  return {
+    versions: config.input.map((v) => v.path),
+    versionMap: Object.fromEntries(
+      config.input.map((v) => [
+        v.path,
+        {
+          label: v.label ?? v.path,
+          downloadUrl: v.downloadUrl,
+          tagPages: v.tagPages,
+        },
+      ]),
+    ),
+  };
+};
+
+/**
+ * Build the target URL when switching versions. Preserves the current tag
+ * if it exists in the target version, otherwise navigates to the version
+ * root (which redirects to its first tag).
+ */
+export const buildVersionSwitchUrl = (
+  target: VersionEntry,
+  currentTag: string | undefined,
+) => {
+  const tagExistsInTarget =
+    currentTag && (!target.tagPages || target.tagPages.includes(currentTag));
+
+  if (!tagExistsInTarget) return target.path;
+
+  return joinUrl(target.path, currentTag);
+};
+
+export const getRoutes = ({
+  basePath,
+  config,
+  client,
+}: {
+  client: GraphQLClient;
+  config: OpenApiPluginOptions;
+  basePath: string;
+}): RouteObject[] => {
+  const tagPages = config.tagPages;
+  const { versions } = getVersionMetadata(config);
+  const inputArray = Array.isArray(config.input) ? config.input : undefined;
+
+  // undefined entry = index path that serves the latest version
+  const versionsInPath =
+    versions.length > 1 ? [undefined, ...versions] : [undefined];
+
+  return versionsInPath.map((version) => {
+    const versionPath = joinUrl(basePath, version);
+    const versionInput = version
+      ? inputArray?.find((v) => v.path === version)
+      : inputArray?.[0];
+    const hasUntaggedOperations = versionInput?.hasUntaggedOperations ?? true;
+
+    const versionTagPages = versionInput?.tagPages ?? tagPages;
+
+    return createOasProvider({
+      basePath,
+      version,
+      routePath: versionPath,
+      routes: versionTagPages
+        ? createVersionRoutes({
+            versionPath,
+            tagPages: versionTagPages,
+            hasUntaggedOperations,
+            showInfoPage: config.options?.showInfoPage !== false,
+          })
+        : [
+            createNonTagPagesRoute({ path: `${versionPath}/:tag?` }),
+            ...createAdditionalRoutes({
+              basePath: versionPath,
+              hasUntaggedOperations,
+            }),
+          ],
+      client,
+      config,
+    });
+  });
+};

package/src/lib/plugins/openapi/util/methodColorMap.tsx

@@ -0,0 +1,11 @@
+import type { ColorMap } from "../../../components/navigation/NavigationBadge.js";
+
+export const MethodColorMap: Record<string, keyof typeof ColorMap> = {
+  get: "green",
+  post: "blue",
+  put: "yellow",
+  delete: "red",
+  patch: "purple",
+  options: "gray",
+  head: "gray",
+};

package/src/lib/plugins/openapi/util/methodToColor.ts

@@ -0,0 +1,27 @@
+export const TextColorMap = {
+  green: "text-green-600",
+  blue: "text-sky-600",
+  yellow: "text-yellow-600",
+  red: "text-red-600",
+  purple: "text-purple-600",
+  indigo: "text-indigo-600",
+  gray: "text-gray-600",
+};
+
+export const methodToColor = {
+  get: TextColorMap.green,
+  post: TextColorMap.blue,
+  put: TextColorMap.yellow,
+  delete: TextColorMap.red,
+  patch: TextColorMap.purple,
+  options: TextColorMap.indigo,
+  head: TextColorMap.gray,
+  trace: TextColorMap.gray,
+};
+
+export const methodForColor = (method: string) => {
+  return (
+    methodToColor[method.toLocaleLowerCase() as keyof typeof methodToColor] ??
+    TextColorMap.gray
+  );
+};

package/src/lib/plugins/openapi/util/sanitizeMarkdownForMetatag.tsx

@@ -0,0 +1,32 @@
+export function sanitizeMarkdownForMetatag(
+  description: string,
+  maxLength: number = 160,
+): string {
+  if (!description) {
+    return "";
+  }
+
+  return (
+    description
+      // Replace Markdown links [text](url) with just "text"
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      // Remove Markdown image syntax: ![alt](url)
+      .replace(/!\[.*?\]\(.*?\)/g, "")
+      // Remove other Markdown syntax (e.g., **bold**, _italic_, `code`)
+      .replace(/[_*`~]/g, "")
+      // Remove headings (# Heading), blockquotes (> Quote), and horizontal rules (--- or ***)
+      .replace(/^(?:>|\s*#+|-{3,}|\*{3,})/gm, "")
+      // Remove any remaining formatting characters
+      .replace(/[|>{}[\]]/g, "")
+      // Collapse multiple spaces and trim the text
+      .replace(/\s+/g, " ")
+      .trim()
+      // Limit to the specified maximum length
+      .substring(0, maxLength)
+      .replace(/&/g, "&")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;")
+  );
+}

package/src/lib/plugins/openapi/util/useWarmupSchema.ts

@@ -0,0 +1,23 @@
+import { useQuery } from "@tanstack/react-query";
+import { useCreateQuery } from "../client/useCreateQuery.js";
+import { useOasConfig } from "../context.js";
+import { graphql } from "../graphql/index.js";
+
+const SchemaWarmupQuery = graphql(/* GraphQL */ `
+  query SchemaWarmup($input: JSON!, $type: SchemaType!) {
+    schema(input: $input, type: $type) {
+      openapi
+    }
+  }
+`);
+
+// Load the schema in the background on the client if schema was rendered on the server
+export const useWarmupSchema = () => {
+  const { input, type } = useOasConfig();
+  const warmupQuery = useCreateQuery(SchemaWarmupQuery, { input, type });
+  useQuery({
+    ...warmupQuery,
+    enabled: typeof window !== "undefined",
+    notifyOnChangeProps: [],
+  });
+};

package/src/lib/plugins/search-inkeep/index.tsx

@@ -0,0 +1,108 @@
+import type {
+  InkeepBaseSettings,
+  InkeepComponentInstance,
+  InkeepJS,
+  InkeepSettings,
+} from "@inkeep/cxkit-types";
+import { useEffect, useMemo, useState } from "react";
+import { ClientOnly } from "../../components/ClientOnly.js";
+import type { ApitogoPlugin } from "../../core/plugins.js";
+import {
+  aiChatSettings,
+  baseSettings,
+  modalSettings,
+  searchSettings,
+} from "./inkeep.js";
+
+declare global {
+  interface Window {
+    Inkeep: InkeepJS | undefined;
+  }
+}
+
+const InkeepSearch = ({
+  isOpen,
+  onClose,
+  settings,
+}: {
+  isOpen: boolean;
+  onClose: () => void;
+  settings: InkeepBaseSettings;
+}) => {
+  const config = useMemo<InkeepSettings>(
+    () => ({
+      baseSettings: {
+        ...baseSettings,
+        ...settings,
+        colorMode: {
+          sync: {
+            target: "html",
+            attributes: ["class"],
+            isDarkMode: (attrs) => attrs.class?.includes("dark") ?? false,
+          },
+        },
+      },
+      modalSettings: {
+        ...modalSettings,
+        onOpenChange: (newOpen: boolean) => {
+          if (!newOpen) onClose();
+        },
+      },
+      searchSettings,
+      aiChatSettings,
+    }),
+    [onClose, settings],
+  );
+  const [searchInstance, setSearchInstance] = useState<
+    InkeepComponentInstance | undefined
+  >(
+    typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat
+      ? window.Inkeep.ModalSearchAndChat(config)
+      : undefined,
+  );
+
+  useEffect(() => {
+    if (searchInstance) return;
+
+    const checkInkeep = setInterval(() => {
+      if (typeof window !== "undefined" && window.Inkeep?.ModalSearchAndChat) {
+        const inkeep = window.Inkeep.ModalSearchAndChat(config);
+        setSearchInstance(inkeep);
+        clearInterval(checkInkeep);
+      }
+    }, 100);
+
+    return () => clearInterval(checkInkeep);
+  }, [config, searchInstance]);
+
+  useEffect(() => {
+    if (!searchInstance) return;
+
+    searchInstance.update({ modalSettings: { isOpen } });
+  }, [isOpen, searchInstance]);
+
+  return null;
+};
+
+export const inkeepSearchPlugin = (
+  settings: InkeepBaseSettings,
+): ApitogoPlugin => {
+  return {
+    getHead: () => {
+      return (
+        <script
+          type="module"
+          src="https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5.90/+esm"
+          defer
+        />
+      );
+    },
+    renderSearch: ({ isOpen, onClose }) => {
+      return (
+        <ClientOnly>
+          <InkeepSearch isOpen={isOpen} onClose={onClose} settings={settings} />
+        </ClientOnly>
+      );
+    },
+  };
+};

package/src/lib/plugins/search-inkeep/inkeep.ts

@@ -0,0 +1,24 @@
+import type {
+  InkeepAIChatSettings,
+  InkeepBaseSettings,
+  InkeepModalSettings,
+  InkeepSearchSettings,
+} from "@inkeep/cxkit-types";
+
+const baseSettings: InkeepBaseSettings = {
+  primaryBrandColor: "#26D6FF",
+};
+
+const modalSettings: InkeepModalSettings = {
+  shortcutKey: "k",
+};
+
+const searchSettings: InkeepSearchSettings = {
+  placeholder: "Search...",
+};
+
+const aiChatSettings: InkeepAIChatSettings = {
+  aiAssistantName: "Assistant",
+};
+
+export { aiChatSettings, baseSettings, modalSettings, searchSettings };