@lukoweb/apitogo 0.1.23 → 0.1.37

package/src/config/validators/ZudokuConfig.ts

@@ -1,729 +1,766 @@
-import type { Options } from "@mdx-js/rollup";
-import colors from "picocolors";
-import type { ComponentType, ReactNode } from "react";
-import { isValidElement } from "react";
-import type { BundledLanguage, BundledTheme } from "shiki";
-import { z } from "zod";
-import type { UseAuthReturn } from "../../lib/authentication/hook.js";
-import type { AuthState } from "../../lib/authentication/state.js";
-import type { SlotType } from "../../lib/components/context/SlotProvider.js";
-import type { ApitogoPlugin } from "../../lib/core/plugins.js";
-import type { ZudokuContext } from "../../lib/core/ZudokuContext.js";
-import type { FilterCatalogItemsFn } from "../../lib/plugins/api-catalog/index.js";
-import type { ApiConsumer } from "../../lib/plugins/api-keys/index.js";
-import type {
-  GenerateCodeSnippetFn,
-  TransformExamplesFn,
-} from "../../lib/plugins/openapi/interfaces.js";
-import type { PagefindSearchFragment } from "../../lib/plugins/search-pagefind/types.js";
-import type { MdxComponentsType } from "../../lib/util/MdxComponents.js";
-import type { ExposedComponentProps } from "../../lib/util/useExposedProps.js";
-import { GOOGLE_FONTS } from "../../vite/plugin-theme.js";
-import { HeaderNavigationSchema } from "./HeaderNavigationSchema.js";
-import {
-  InputNavigationSchema,
-  NavigationRulesSchema,
-} from "./InputNavigationSchema.js";
-import { ProtectedRoutesSchema } from "./ProtectedRoutesSchema.js";
-
-const ThemeSchema = z
-  .object({
-    background: z.string(),
-    foreground: z.string(),
-    card: z.string(),
-    cardForeground: z.string(),
-    popover: z.string(),
-    popoverForeground: z.string(),
-    primary: z.string(),
-    primaryForeground: z.string(),
-    secondary: z.string(),
-    secondaryForeground: z.string(),
-    muted: z.string(),
-    mutedForeground: z.string(),
-    accent: z.string(),
-    accentForeground: z.string(),
-    destructive: z.string(),
-    destructiveForeground: z.string(),
-    border: z.string(),
-    input: z.string(),
-    ring: z.string(),
-    radius: z.string(),
-  })
-  .partial();
-
-const ApiCatalogCategorySchema = z.object({
-  label: z.string(),
-  tags: z.array(z.string()),
-});
-
-const LanguageOption = z.object({
-  value: z.string().min(1),
-  label: z.string().min(1),
-});
-
-const AiAssistantCustomSchema = z.object({
-  label: z.string(),
-  icon: z.custom<ReactNode>().optional(),
-  url: z.union([
-    z.string(),
-    z.custom<
-      (context: { pageUrl: string; type: "docs" | "openapi" }) => string
-    >((val) => typeof val === "function"),
-  ]),
-});
-
-export type AiAssistantCustom = z.infer<typeof AiAssistantCustomSchema>;
-
-const AiAssistantPresets = ["claude", "chatgpt"] as const;
-
-const AiAssistantsSchema = z
-  .union([
-    z.literal(false),
-    z.array(z.union([z.enum(AiAssistantPresets), AiAssistantCustomSchema])),
-  ])
-  .optional();
-
-export type AiAssistantsConfig = z.infer<typeof AiAssistantsSchema>;
-
-const ApiOptionsSchema = z
-  .object({
-    examplesLanguage: z.string(),
-    supportedLanguages: z.array(LanguageOption),
-    disablePlayground: z.boolean(),
-    disableSidecar: z.boolean(),
-    showVersionSelect: z.enum(["always", "if-available", "hide"]),
-    expandAllTags: z.boolean(),
-    showInfoPage: z.boolean(),
-    schemaDownload: z.object({ enabled: z.boolean() }).partial(),
-    transformExamples: z.custom<TransformExamplesFn>(
-      (val) => typeof val === "function",
-    ),
-    generateCodeSnippet: z.custom<GenerateCodeSnippetFn>(
-      (val) => typeof val === "function",
-    ),
-  })
-  .partial();
-
-const ApiConfigSchema = z
-  .object({
-    server: z.string(),
-    path: z.string(),
-    categories: z.array(ApiCatalogCategorySchema),
-    options: ApiOptionsSchema,
-  })
-  .partial();
-
-const VersionConfigSchema = z.object({
-  path: z.string(),
-  input: z.string(),
-  label: z.string().optional(),
-});
-
-const ApiSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("url"),
-    input: z.union([z.string(), z.array(VersionConfigSchema)]),
-    ...ApiConfigSchema.shape,
-  }),
-  z.object({
-    type: z.literal("file"),
-    input: z.union([
-      z.string(),
-      z.array(z.union([z.string(), VersionConfigSchema])),
-    ]),
-    ...ApiConfigSchema.shape,
-  }),
-  z.object({
-    type: z.literal("raw"),
-    input: z.string(),
-    ...ApiConfigSchema.shape,
-  }),
-]);
-
-const ApiKeysSchema = z.object({
-  enabled: z.boolean(),
-  getConsumers: z
-    .custom<(context: ZudokuContext) => Promise<ApiConsumer[]>>(
-      (val) => typeof val === "function",
-    )
-    .optional(),
-  rollKey: z
-    .custom<(id: string, context: ZudokuContext) => Promise<void>>(
-      (val) => typeof val === "function",
-    )
-    .optional(),
-  deleteKey: z
-    .custom<
-      (
-        consumerId: string,
-        keyId: string,
-        context: ZudokuContext,
-      ) => Promise<void>
-    >((val) => typeof val === "function")
-    .optional(),
-  updateKeyDescription: z
-    .custom<
-      (
-        apiKey: { id: string; description: string },
-        context: ZudokuContext,
-      ) => Promise<void>
-    >((val) => typeof val === "function")
-    .optional(),
-  createKey: z
-    .custom<
-      ({
-        apiKey,
-        context,
-        auth,
-      }: {
-        apiKey: { description: string; expiresOn?: string };
-        context: ZudokuContext;
-        auth: UseAuthReturn;
-      }) => Promise<void>
-    >((val) => typeof val === "function")
-    .optional(),
-});
-
-export type ApiKeysOptions = z.infer<typeof ApiKeysSchema>;
-
-const LogoSchema = z.object({
-  src: z.object({ light: z.string(), dark: z.string() }),
-  alt: z.string().optional(),
-  width: z.string().or(z.number()).optional(),
-  href: z.string().optional(),
-  reloadDocument: z.boolean().optional(),
-});
-
-export const FooterSocialIcons = [
-  "reddit",
-  "discord",
-  "github",
-  "x",
-  "linkedin",
-  "facebook",
-  "instagram",
-  "youtube",
-  "tiktok",
-  "twitch",
-  "pinterest",
-  "snapchat",
-  "whatsapp",
-  "telegram",
-] as const;
-
-export const FooterSocialSchema = z.object({
-  label: z.string().optional(),
-  href: z.string(),
-  icon: z
-    .union([
-      z.enum(FooterSocialIcons),
-      z.custom<ReactNode>((val) => isValidElement(val)),
-    ])
-    .optional(),
-});
-
-export const FooterSchema = z
-  .object({
-    columns: z
-      .array(
-        z.object({
-          position: z.enum(["start", "center", "end"]).optional(),
-          title: z.string(),
-          links: z.array(z.object({ label: z.string(), href: z.string() })),
-        }),
-      )
-      .optional(),
-    social: z.array(FooterSocialSchema).optional(),
-    copyright: z.string().optional(),
-    logo: LogoSchema.optional(),
-    position: z.enum(["start", "center", "end"]).optional(),
-  })
-  .optional();
-
-const SiteMapSchema = z
-  .object({
-    /**
-     * Base url of your website
-     */
-    siteUrl: z.string(),
-    /**
-     * Change frequency.
-     * @default 'daily'
-     */
-    changefreq: z.optional(
-      z.enum([
-        "always",
-        "hourly",
-        "daily",
-        "weekly",
-        "monthly",
-        "yearly",
-        "never",
-      ]),
-    ),
-    /**
-     * Priority
-     * @default 0.7
-     */
-    priority: z.optional(z.number()),
-    outDir: z.string().optional(),
-    /**
-     * Add <lastmod/> property.
-     * @default true
-     */
-    autoLastmod: z.boolean().optional(),
-    /**
-     * Array of relative paths to exclude from listing on sitemap.xml or sitemap-*.xml.
-     * @example ['/page-0', '/page/example']
-     */
-    exclude: z
-      .union([
-        z.custom<() => Promise<string[]>>((val) => typeof val === "function"),
-        z.array(z.string()),
-      ])
-      .optional(),
-  })
-  .optional();
-
-const DEFAULT_DOCS_FILES = "/pages/**/*.{md,mdx}";
-
-const LlmsConfigSchema = z
-  .object({
-    llmsTxt: z
-      .boolean()
-      .default(false)
-      .describe(
-        "When enabled, generates an llms.txt file following the spec at https://llmstxt.org/. This file provides a summary with links to all documentation.",
-      ),
-    llmsTxtFull: z
-      .boolean()
-      .default(false)
-      .describe(
-        "When enabled, generates an llms-full.txt file with the complete content of all markdown documents for LLM consumption.",
-      ),
-    includeProtected: z
-      .boolean()
-      .default(false)
-      .describe(
-        "When enabled, includes content from protected routes in the generated .md files and llms.txt files. By default, protected routes are excluded.",
-      ),
-  })
-  .partial();
-
-export const DocsConfigSchema = z.object({
-  files: z
-    .union([z.string(), z.array(z.string())])
-    .transform((val) => (typeof val === "string" ? [val] : val))
-    .default([DEFAULT_DOCS_FILES]),
-  publishMarkdown: z
-    .boolean()
-    .default(false)
-    .describe(
-      "When enabled, generates .md files for each document during build. Access documents at their URL path with .md extension (e.g., /foo/hello.md). Markdown files are generated without frontmatter.",
-    ),
-  defaultOptions: z
-    .object({
-      toc: z.boolean(),
-      copyPage: z.boolean().optional(),
-      disablePager: z.boolean(),
-      showLastModified: z.boolean(),
-      suggestEdit: z
-        .object({
-          url: z.string(),
-          text: z.string().optional(),
-        })
-        .optional(),
-    })
-    .partial()
-    .optional(),
-  llms: LlmsConfigSchema.optional(),
-});
-
-const Redirect = z.object({
-  from: z.string(),
-  to: z.string(),
-});
-
-const SearchSchema = z
-  .discriminatedUnion("type", [
-    // looseObject to allow additional properties so the
-    // user can set other inkeep settings
-    z.looseObject({
-      type: z.literal("inkeep"),
-      apiKey: z.string(),
-      integrationId: z.string(),
-      organizationId: z.string(),
-      primaryBrandColor: z.string(),
-      organizationDisplayName: z.string(),
-    }),
-    z.object({
-      type: z.literal("pagefind"),
-
-      ranking: z
-        .object({
-          termFrequency: z.number(),
-          pageLength: z.number(),
-          termSimilarity: z.number(),
-          termSaturation: z.number(),
-        })
-        .optional(),
-      maxResults: z.number().optional(),
-      maxSubResults: z.number().optional(),
-      transformResults: z
-        .custom<
-          (data: {
-            result: PagefindSearchFragment;
-            auth: AuthState;
-            context: ZudokuContext;
-          }) => PagefindSearchFragment | boolean | undefined | void
-        >((val) => typeof val === "function")
-        .optional(),
-    }),
-  ])
-  .optional();
-
-const AuthenticationSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("clerk"),
-    clerkPubKey: z
-      .custom<`pk_test_${string}` | `pk_live_${string}`>()
-      .refine((val) => /^pk_(test|live)_\w+$/.test(val), {
-        message: "Clerk public key invalid, must start with pk_test or pk_live",
-      }),
-    jwtTemplateName: z.string().optional().default("dev-portal"),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal("firebase"),
-    apiKey: z.string(),
-    authDomain: z.string(),
-    projectId: z.string(),
-    storageBucket: z.string().optional(),
-    messagingSenderId: z.string().optional(),
-    appId: z.string(),
-    measurementId: z.string().optional(),
-    providers: z
-      .array(
-        z.enum([
-          "google",
-          "facebook",
-          "twitter",
-          "github",
-          "microsoft",
-          "apple",
-          "yahoo",
-          "password",
-          "phone",
-          "emailLink",
-        ]),
-      )
-      .optional(),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal("openid"),
-    basePath: z.string().optional(),
-    clientId: z.string(),
-    issuer: z.string(),
-    audience: z.string().optional(),
-    scopes: z.array(z.string()).optional(),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-  }),
-  z.object({
-    type: z.literal("azureb2c"),
-    basePath: z.string().optional(),
-    clientId: z.string(),
-    tenantName: z.string(),
-    policyName: z.string(),
-    scopes: z.array(z.string()).optional(),
-    issuer: z.string(),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-  }),
-
-  z.object({
-    type: z.literal("auth0"),
-    clientId: z.string(),
-    domain: z.string().refine(
-      (val) => {
-        if (val.startsWith("http://") || val.startsWith("https://")) {
-          return false;
-        }
-        if (val.includes("/")) {
-          return false;
-        }
-        return val.includes(".") && val.length > 0;
-      },
-      {
-        message:
-          "Domain must be a host only (e.g., 'example.com') without protocol or slashes",
-      },
-    ),
-    audience: z.string().optional(),
-    scopes: z.array(z.string()).optional(),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-    options: z
-      .object({
-        alwaysPromptLogin: z.boolean().optional(),
-        prompt: z.string().optional(),
-      })
-      .optional(),
-  }),
-  z.object({
-    type: z.literal("supabase"),
-    basePath: z.string().optional(),
-    supabaseUrl: z.string(),
-    supabaseKey: z.string(),
-    provider: z.string().optional(),
-    providers: z.array(z.string()).optional(),
-    onlyThirdPartyProviders: z.boolean().optional(),
-    redirectToAfterSignUp: z.string().optional(),
-    redirectToAfterSignIn: z.string().optional(),
-    redirectToAfterSignOut: z.string().optional(),
-  }),
-]);
-
-const MetadataSchema = z
-  .object({
-    title: z.string(),
-    defaultTitle: z.string().optional(),
-    description: z.string(),
-    logo: z.string(),
-    favicon: z.string(),
-    generator: z.string(),
-    applicationName: z.string(),
-    referrer: z.string(),
-    keywords: z.array(z.string()),
-    authors: z.array(z.string()),
-    creator: z.string(),
-    publisher: z.string(),
-  })
-  .partial();
-
-const FontConfigSchema = z.union([
-  z.enum(GOOGLE_FONTS),
-  z.object({
-    url: z.string(),
-    fontFamily: z.string().optional(),
-  }),
-]);
-
-export type FontConfig = z.infer<typeof FontConfigSchema>;
-
-const FontsConfigSchema = z.object({
-  sans: FontConfigSchema.optional(),
-  serif: FontConfigSchema.optional(),
-  mono: FontConfigSchema.optional(),
-});
-
-const CssObject = z.record(
-  z.string(),
-  z.lazy(() =>
-    z.union([
-      z.string(),
-      z.record(
-        z.string(),
-        z.union([z.string(), z.record(z.string(), z.string())]),
-      ),
-    ]),
-  ),
-);
-
-const ThemeConfigSchema = z.object({
-  registryUrl: z.string().url().optional(),
-  customCss: z.union([z.string(), CssObject]).optional(),
-  light: ThemeSchema.optional(),
-  dark: ThemeSchema.optional(),
-  fonts: FontsConfigSchema.optional(),
-  noDefaultTheme: z.boolean().optional(),
-});
-
-const SiteSchema = z
-  .object({
-    title: z.string(),
-    logoUrl: z.string(),
-    dir: z.enum(["ltr", "rtl"]).optional(),
-    logo: LogoSchema,
-    banner: z.object({
-      message: z.custom<NonNullable<ReactNode>>(),
-      color: z
-        .custom<"note" | "tip" | "info" | "caution" | "danger" | (string & {})>(
-          (val) => typeof val === "string",
-        )
-        .optional(),
-      dismissible: z.boolean().optional(),
-    }),
-    footer: FooterSchema,
-  })
-  .partial();
-
-const PlacementPosition = z.enum(["start", "center", "end"]);
-
-const HeaderConfigSchema = z
-  .object({
-    navigation: HeaderNavigationSchema,
-    placements: z
-      .object({
-        navigation: PlacementPosition,
-        search: PlacementPosition,
-        auth: z.enum(["start", "center", "end", "navigation"]),
-      })
-      .partial()
-      .optional(),
-  })
-  .partial();
-
-const ApiCatalogSchema = z.object({
-  path: z.string(),
-  label: z.string(),
-  items: z.array(z.string()).optional(),
-  filterItems: z
-    .custom<FilterCatalogItemsFn>((val) => typeof val === "function")
-    .optional(),
-});
-
-export const CdnUrlSchema = z
-  .union([
-    z.string(),
-    z.object({
-      base: z.string().optional(),
-      media: z.string().optional(),
-    }),
-  ])
-  .transform((val) => {
-    if (typeof val === "string") {
-      return { base: val, media: val };
-    }
-    return { base: val.base, media: val.media };
-  })
-  .optional();
-
-const BaseConfigSchema = z.object({
-  slots: z.record(z.string(), z.custom<SlotType>()),
-  /**
-   * @deprecated Use `slots` instead
-   */
-  UNSAFE_slotlets: z.record(z.string(), z.custom<SlotType>()),
-  mdx: z
-    .object({
-      components: z.custom<MdxComponentsType>(),
-    })
-    .partial(),
-  customPages: z.array(
-    z.object({
-      path: z.string(),
-      element: z.custom<NonNullable<ReactNode>>().optional(),
-      render: z.custom<ComponentType<ExposedComponentProps>>().optional(),
-      prose: z.boolean().optional(),
-    }),
-  ),
-  plugins: z.array(z.custom<ApitogoPlugin>()),
-  build: z.custom<{
-    remarkPlugins?: Options["remarkPlugins"];
-    rehypePlugins?: Options["rehypePlugins"];
-  }>(),
-  protectedRoutes: ProtectedRoutesSchema,
-  basePath: z.string().optional(),
-  canonicalUrlOrigin: z.string().optional(),
-  cdnUrl: CdnUrlSchema.optional(),
-  port: z.number().optional(),
-  https: z
-    .object({
-      key: z.string(),
-      cert: z.string(),
-      ca: z.string().optional(),
-    })
-    .optional(),
-  site: SiteSchema,
-  header: HeaderConfigSchema.optional(),
-  navigation: InputNavigationSchema,
-  navigationRules: NavigationRulesSchema.optional(),
-  theme: ThemeConfigSchema,
-  syntaxHighlighting: z
-    .object({
-      languages: z.array(z.custom<BundledLanguage>()),
-      themes: z.object({
-        light: z.custom<BundledTheme>(),
-        dark: z.custom<BundledTheme>(),
-      }),
-    })
-    .partial()
-    .optional(),
-  metadata: MetadataSchema,
-  authentication: AuthenticationSchema,
-  search: SearchSchema,
-  docs: DocsConfigSchema.optional(),
-  apis: z.union([ApiSchema, z.array(ApiSchema)]),
-  catalogs: z.union([ApiCatalogSchema, z.array(ApiCatalogSchema)]),
-  apiKeys: ApiKeysSchema,
-  aiAssistants: AiAssistantsSchema,
-  redirects: z.array(Redirect),
-  sitemap: SiteMapSchema,
-  enableStatusPages: z.boolean().optional(),
-  defaults: z.object({
-    apis: ApiOptionsSchema,
-    /**
-     * @deprecated Use `apis.examplesLanguage` or `defaults.apis.examplesLanguage` instead
-     */
-    examplesLanguage: z.string().optional(),
-  }),
-  // Internal: populated by plugins via `transformConfig` to track plugin directories
-  __pluginDirs: z.array(z.string()),
-});
-
-export const ZudokuConfig = BaseConfigSchema.partial();
-
-export type ZudokuApiConfig = z.infer<typeof ApiSchema>;
-export type VersionConfig = z.infer<typeof VersionConfigSchema>;
-export type ZudokuSiteMapConfig = z.infer<typeof SiteMapSchema>;
-export type ZudokuDocsConfig = z.infer<typeof DocsConfigSchema>;
-export type ZudokuLlmsConfig = z.infer<typeof LlmsConfigSchema>;
-export type ZudokuRedirect = z.infer<typeof Redirect>;
-export type AuthenticationConfig = z.infer<typeof AuthenticationSchema>;
-
-// Use `z.input` type for flexibility with transforms,
-// but override navigation with `z.infer` for strict validation
-type BaseZudokuConfig = z.input<typeof ZudokuConfig>;
-export type ZudokuConfig = Omit<
-  BaseZudokuConfig,
-  "header" | "navigation" | "navigationRules"
-> & {
-  header?: {
-    navigation?: z.infer<typeof HeaderNavigationSchema>;
-    placements?: {
-      navigation?: "start" | "center" | "end";
-      search?: "start" | "center" | "end";
-      auth?: "start" | "center" | "end" | "navigation";
-    };
-  };
-  navigation?: z.infer<typeof InputNavigationSchema>;
-  navigationRules?: z.infer<typeof NavigationRulesSchema>;
-};
-
-export function validateConfig(config: unknown, configPath?: string) {
-  const validationResult = ZudokuConfig.safeParse(config);
-
-  if (!validationResult.success) {
-    // In production (build mode), throw an error to fail the build
-    if (process.env.NODE_ENV === "production") {
-      throw new Error(
-        `Whoops, looks like there's an issue with your ${configPath ?? "config"}:\n${z.prettifyError(validationResult.error)}`,
-      );
-    }
-
-    // In development mode, log warnings but don't fail
-    // biome-ignore lint/suspicious/noConsole: Logging allowed here
-    console.log(colors.yellow("Validation errors:"));
-    // biome-ignore lint/suspicious/noConsole: Logging allowed here
-    console.log(colors.yellow(z.prettifyError(validationResult.error)));
-  }
-}
+import type { Options } from "@mdx-js/rollup";
+import colors from "picocolors";
+import type { ComponentType, ReactNode } from "react";
+import { isValidElement } from "react";
+import type { BundledLanguage, BundledTheme } from "shiki";
+import { z } from "zod";
+import type { UseAuthReturn } from "../../lib/authentication/hook.js";
+import type { AuthState } from "../../lib/authentication/state.js";
+import type { SlotType } from "../../lib/components/context/SlotProvider.js";
+import type { ApitogoPlugin } from "../../lib/core/plugins.js";
+import type { ZudokuContext } from "../../lib/core/ZudokuContext.js";
+import type { FilterCatalogItemsFn } from "../../lib/plugins/api-catalog/index.js";
+import type { ApiConsumer } from "../../lib/plugins/api-keys/index.js";
+import type {
+  GenerateCodeSnippetFn,
+  TransformExamplesFn,
+} from "../../lib/plugins/openapi/interfaces.js";
+import type { PagefindSearchFragment } from "../../lib/plugins/search-pagefind/types.js";
+import type { MdxComponentsType } from "../../lib/util/MdxComponents.js";
+import type { ExposedComponentProps } from "../../lib/util/useExposedProps.js";
+import { GOOGLE_FONTS } from "../../vite/plugin-theme.js";
+import { HeaderNavigationSchema } from "./HeaderNavigationSchema.js";
+import {
+  InputNavigationSchema,
+  NavigationRulesSchema,
+} from "./InputNavigationSchema.js";
+import { ModulesSchema } from "./ModulesSchema.js";
+import { ProtectedRoutesSchema } from "./ProtectedRoutesSchema.js";
+
+const ThemeSchema = z
+  .object({
+    background: z.string(),
+    foreground: z.string(),
+    card: z.string(),
+    cardForeground: z.string(),
+    popover: z.string(),
+    popoverForeground: z.string(),
+    primary: z.string(),
+    primaryForeground: z.string(),
+    secondary: z.string(),
+    secondaryForeground: z.string(),
+    muted: z.string(),
+    mutedForeground: z.string(),
+    accent: z.string(),
+    accentForeground: z.string(),
+    destructive: z.string(),
+    destructiveForeground: z.string(),
+    border: z.string(),
+    input: z.string(),
+    ring: z.string(),
+    radius: z.string(),
+  })
+  .partial();
+
+const ApiCatalogCategorySchema = z.object({
+  label: z.string(),
+  tags: z.array(z.string()),
+});
+
+const LanguageOption = z.object({
+  value: z.string().min(1),
+  label: z.string().min(1),
+});
+
+const AiAssistantCustomSchema = z.object({
+  label: z.string(),
+  icon: z.custom<ReactNode>().optional(),
+  url: z.union([
+    z.string(),
+    z.custom<
+      (context: { pageUrl: string; type: "docs" | "openapi" }) => string
+    >((val) => typeof val === "function"),
+  ]),
+});
+
+export type AiAssistantCustom = z.infer<typeof AiAssistantCustomSchema>;
+
+const AiAssistantPresets = ["claude", "chatgpt"] as const;
+
+const AiAssistantsSchema = z
+  .union([
+    z.literal(false),
+    z.array(z.union([z.enum(AiAssistantPresets), AiAssistantCustomSchema])),
+  ])
+  .optional();
+
+export type AiAssistantsConfig = z.infer<typeof AiAssistantsSchema>;
+
+const ApiOptionsSchema = z
+  .object({
+    examplesLanguage: z.string(),
+    supportedLanguages: z.array(LanguageOption),
+    disablePlayground: z.boolean(),
+    disableSidecar: z.boolean(),
+    showVersionSelect: z.enum(["always", "if-available", "hide"]),
+    expandAllTags: z.boolean(),
+    showInfoPage: z.boolean(),
+    schemaDownload: z.object({ enabled: z.boolean() }).partial(),
+    transformExamples: z.custom<TransformExamplesFn>(
+      (val) => typeof val === "function",
+    ),
+    generateCodeSnippet: z.custom<GenerateCodeSnippetFn>(
+      (val) => typeof val === "function",
+    ),
+  })
+  .partial();
+
+const ApiConfigSchema = z
+  .object({
+    server: z.string(),
+    path: z.string(),
+    categories: z.array(ApiCatalogCategorySchema),
+    options: ApiOptionsSchema,
+  })
+  .partial();
+
+const VersionConfigSchema = z.object({
+  path: z.string(),
+  input: z.string(),
+  label: z.string().optional(),
+});
+
+const ApiSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("url"),
+    input: z.union([z.string(), z.array(VersionConfigSchema)]),
+    ...ApiConfigSchema.shape,
+  }),
+  z.object({
+    type: z.literal("file"),
+    input: z.union([
+      z.string(),
+      z.array(z.union([z.string(), VersionConfigSchema])),
+    ]),
+    ...ApiConfigSchema.shape,
+  }),
+  z.object({
+    type: z.literal("raw"),
+    input: z.string(),
+    ...ApiConfigSchema.shape,
+  }),
+]);
+
+const ApiKeysSchema = z.object({
+  enabled: z.boolean(),
+  getConsumers: z
+    .custom<(context: ZudokuContext) => Promise<ApiConsumer[]>>(
+      (val) => typeof val === "function",
+    )
+    .optional(),
+  rollKey: z
+    .custom<(id: string, context: ZudokuContext) => Promise<void>>(
+      (val) => typeof val === "function",
+    )
+    .optional(),
+  deleteKey: z
+    .custom<
+      (
+        consumerId: string,
+        keyId: string,
+        context: ZudokuContext,
+      ) => Promise<void>
+    >((val) => typeof val === "function")
+    .optional(),
+  updateKeyDescription: z
+    .custom<
+      (
+        apiKey: { id: string; description: string },
+        context: ZudokuContext,
+      ) => Promise<void>
+    >((val) => typeof val === "function")
+    .optional(),
+  createKey: z
+    .custom<
+      ({
+        apiKey,
+        context,
+        auth,
+      }: {
+        apiKey: { description: string; expiresOn?: string };
+        context: ZudokuContext;
+        auth: UseAuthReturn;
+      }) => Promise<void>
+    >((val) => typeof val === "function")
+    .optional(),
+});
+
+export type ApiKeysOptions = z.infer<typeof ApiKeysSchema>;
+
+const LogoSchema = z.object({
+  src: z.object({ light: z.string(), dark: z.string() }),
+  alt: z.string().optional(),
+  width: z.string().or(z.number()).optional(),
+  href: z.string().optional(),
+  reloadDocument: z.boolean().optional(),
+});
+
+export const FooterSocialIcons = [
+  "reddit",
+  "discord",
+  "github",
+  "x",
+  "linkedin",
+  "facebook",
+  "instagram",
+  "youtube",
+  "tiktok",
+  "twitch",
+  "pinterest",
+  "snapchat",
+  "whatsapp",
+  "telegram",
+] as const;
+
+export const FooterSocialSchema = z.object({
+  label: z.string().optional(),
+  href: z.string(),
+  icon: z
+    .union([
+      z.enum(FooterSocialIcons),
+      z.custom<ReactNode>((val) => isValidElement(val)),
+    ])
+    .optional(),
+});
+
+export const FooterSchema = z
+  .object({
+    columns: z
+      .array(
+        z.object({
+          position: z.enum(["start", "center", "end"]).optional(),
+          title: z.string(),
+          links: z.array(z.object({ label: z.string(), href: z.string() })),
+        }),
+      )
+      .optional(),
+    social: z.array(FooterSocialSchema).optional(),
+    copyright: z.string().optional(),
+    logo: LogoSchema.optional(),
+    position: z.enum(["start", "center", "end"]).optional(),
+  })
+  .optional();
+
+const SiteMapSchema = z
+  .object({
+    /**
+     * Base url of your website
+     */
+    siteUrl: z.string(),
+    /**
+     * Change frequency.
+     * @default 'daily'
+     */
+    changefreq: z.optional(
+      z.enum([
+        "always",
+        "hourly",
+        "daily",
+        "weekly",
+        "monthly",
+        "yearly",
+        "never",
+      ]),
+    ),
+    /**
+     * Priority
+     * @default 0.7
+     */
+    priority: z.optional(z.number()),
+    outDir: z.string().optional(),
+    /**
+     * Add <lastmod/> property.
+     * @default true
+     */
+    autoLastmod: z.boolean().optional(),
+    /**
+     * Array of relative paths to exclude from listing on sitemap.xml or sitemap-*.xml.
+     * @example ['/page-0', '/page/example']
+     */
+    exclude: z
+      .union([
+        z.custom<() => Promise<string[]>>((val) => typeof val === "function"),
+        z.array(z.string()),
+      ])
+      .optional(),
+  })
+  .optional();
+
+const DEFAULT_DOCS_FILES = "/pages/**/*.{md,mdx}";
+
+const LlmsConfigSchema = z
+  .object({
+    llmsTxt: z
+      .boolean()
+      .default(false)
+      .describe(
+        "When enabled, generates an llms.txt file following the spec at https://llmstxt.org/. This file provides a summary with links to all documentation.",
+      ),
+    llmsTxtFull: z
+      .boolean()
+      .default(false)
+      .describe(
+        "When enabled, generates an llms-full.txt file with the complete content of all markdown documents for LLM consumption.",
+      ),
+    includeProtected: z
+      .boolean()
+      .default(false)
+      .describe(
+        "When enabled, includes content from protected routes in the generated .md files and llms.txt files. By default, protected routes are excluded.",
+      ),
+  })
+  .partial();
+
+export const DocsConfigSchema = z.object({
+  files: z
+    .union([z.string(), z.array(z.string())])
+    .transform((val) => (typeof val === "string" ? [val] : val))
+    .default([DEFAULT_DOCS_FILES]),
+  publishMarkdown: z
+    .boolean()
+    .default(false)
+    .describe(
+      "When enabled, generates .md files for each document during build. Access documents at their URL path with .md extension (e.g., /foo/hello.md). Markdown files are generated without frontmatter.",
+    ),
+  defaultOptions: z
+    .object({
+      toc: z.boolean(),
+      copyPage: z.boolean().optional(),
+      disablePager: z.boolean(),
+      showLastModified: z.boolean(),
+      suggestEdit: z
+        .object({
+          url: z.string(),
+          text: z.string().optional(),
+        })
+        .optional(),
+    })
+    .partial()
+    .optional(),
+  llms: LlmsConfigSchema.optional(),
+});
+
+const Redirect = z.object({
+  from: z.string(),
+  to: z.string(),
+});
+
+const SearchSchema = z
+  .discriminatedUnion("type", [
+    // looseObject to allow additional properties so the
+    // user can set other inkeep settings
+    z.looseObject({
+      type: z.literal("inkeep"),
+      apiKey: z.string(),
+      integrationId: z.string(),
+      organizationId: z.string(),
+      primaryBrandColor: z.string(),
+      organizationDisplayName: z.string(),
+    }),
+    z.object({
+      type: z.literal("pagefind"),
+
+      ranking: z
+        .object({
+          termFrequency: z.number(),
+          pageLength: z.number(),
+          termSimilarity: z.number(),
+          termSaturation: z.number(),
+        })
+        .optional(),
+      maxResults: z.number().optional(),
+      maxSubResults: z.number().optional(),
+      transformResults: z
+        .custom<
+          (data: {
+            result: PagefindSearchFragment;
+            auth: AuthState;
+            context: ZudokuContext;
+          }) => PagefindSearchFragment | boolean | undefined | void
+        >((val) => typeof val === "function")
+        .optional(),
+    }),
+  ])
+  .optional();
+
+const AuthenticationSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("clerk"),
+    clerkPubKey: z
+      .custom<`pk_test_${string}` | `pk_live_${string}`>()
+      .refine((val) => /^pk_(test|live)_\w+$/.test(val), {
+        message: "Clerk public key invalid, must start with pk_test or pk_live",
+      }),
+    jwtTemplateName: z.string().optional().default("dev-portal"),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("firebase"),
+    apiKey: z.string(),
+    authDomain: z.string(),
+    projectId: z.string(),
+    storageBucket: z.string().optional(),
+    messagingSenderId: z.string().optional(),
+    appId: z.string(),
+    measurementId: z.string().optional(),
+    providers: z
+      .array(
+        z.enum([
+          "google",
+          "facebook",
+          "twitter",
+          "github",
+          "microsoft",
+          "apple",
+          "yahoo",
+          "password",
+          "phone",
+          "emailLink",
+        ]),
+      )
+      .optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("openid"),
+    basePath: z.string().optional(),
+    clientId: z.string(),
+    issuer: z.string(),
+    audience: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("azureb2c"),
+    basePath: z.string().optional(),
+    clientId: z.string(),
+    tenantName: z.string(),
+    policyName: z.string(),
+    scopes: z.array(z.string()).optional(),
+    issuer: z.string(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+
+  z.object({
+    type: z.literal("auth0"),
+    clientId: z.string(),
+    domain: z.string().refine(
+      (val) => {
+        if (val.startsWith("http://") || val.startsWith("https://")) {
+          return false;
+        }
+        if (val.includes("/")) {
+          return false;
+        }
+        return val.includes(".") && val.length > 0;
+      },
+      {
+        message:
+          "Domain must be a host only (e.g., 'example.com') without protocol or slashes",
+      },
+    ),
+    audience: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+    options: z
+      .object({
+        alwaysPromptLogin: z.boolean().optional(),
+        prompt: z.string().optional(),
+      })
+      .optional(),
+  }),
+  z.object({
+    type: z.literal("supabase"),
+    basePath: z.string().optional(),
+    supabaseUrl: z.string(),
+    supabaseKey: z.string(),
+    provider: z.string().optional(),
+    providers: z.array(z.string()).optional(),
+    onlyThirdPartyProviders: z.boolean().optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal("dev-portal"),
+    apiBaseUrl: z.string().optional(),
+    redirectToAfterSignUp: z.string().optional(),
+    redirectToAfterSignIn: z.string().optional(),
+    redirectToAfterSignOut: z.string().optional(),
+  }),
+]);
+
+const MetadataSchema = z
+  .object({
+    title: z.string(),
+    defaultTitle: z.string().optional(),
+    description: z.string(),
+    logo: z.string(),
+    favicon: z.string(),
+    generator: z.string(),
+    applicationName: z.string(),
+    referrer: z.string(),
+    keywords: z.array(z.string()),
+    authors: z.array(z.string()),
+    creator: z.string(),
+    publisher: z.string(),
+  })
+  .partial();
+
+const FontConfigSchema = z.union([
+  z.enum(GOOGLE_FONTS),
+  z.object({
+    url: z.string(),
+    fontFamily: z.string().optional(),
+  }),
+]);
+
+export type FontConfig = z.infer<typeof FontConfigSchema>;
+
+const FontsConfigSchema = z.object({
+  sans: FontConfigSchema.optional(),
+  serif: FontConfigSchema.optional(),
+  mono: FontConfigSchema.optional(),
+});
+
+const CssObject = z.record(
+  z.string(),
+  z.lazy(() =>
+    z.union([
+      z.string(),
+      z.record(
+        z.string(),
+        z.union([z.string(), z.record(z.string(), z.string())]),
+      ),
+    ]),
+  ),
+);
+
+const ThemeConfigSchema = z.object({
+  registryUrl: z.string().url().optional(),
+  customCss: z.union([z.string(), CssObject]).optional(),
+  light: ThemeSchema.optional(),
+  dark: ThemeSchema.optional(),
+  fonts: FontsConfigSchema.optional(),
+  noDefaultTheme: z.boolean().optional(),
+});
+
+const SiteSchema = z
+  .object({
+    title: z.string(),
+    logoUrl: z.string(),
+    dir: z.enum(["ltr", "rtl"]).optional(),
+    logo: LogoSchema,
+    banner: z.object({
+      message: z.custom<NonNullable<ReactNode>>(),
+      color: z
+        .custom<"note" | "tip" | "info" | "caution" | "danger" | (string & {})>(
+          (val) => typeof val === "string",
+        )
+        .optional(),
+      dismissible: z.boolean().optional(),
+    }),
+    footer: FooterSchema,
+  })
+  .partial();
+
+const PlacementPosition = z.enum(["start", "center", "end"]);
+
+const HeaderConfigSchema = z
+  .object({
+    navigation: HeaderNavigationSchema,
+    placements: z
+      .object({
+        navigation: PlacementPosition,
+        search: PlacementPosition,
+        auth: z.enum(["start", "center", "end", "navigation"]),
+      })
+      .partial()
+      .optional(),
+  })
+  .partial();
+
+const ApiCatalogSchema = z.object({
+  path: z.string(),
+  label: z.string(),
+  items: z.array(z.string()).optional(),
+  filterItems: z
+    .custom<FilterCatalogItemsFn>((val) => typeof val === "function")
+    .optional(),
+});
+
+export const CdnUrlSchema = z
+  .union([
+    z.string(),
+    z.object({
+      base: z.string().optional(),
+      media: z.string().optional(),
+    }),
+  ])
+  .transform((val) => {
+    if (typeof val === "string") {
+      return { base: val, media: val };
+    }
+    return { base: val.base, media: val.media };
+  })
+  .optional();
+
+const BaseConfigSchema = z.object({
+  slots: z.record(z.string(), z.custom<SlotType>()),
+  /**
+   * @deprecated Use `slots` instead
+   */
+  UNSAFE_slotlets: z.record(z.string(), z.custom<SlotType>()),
+  mdx: z
+    .object({
+      components: z.custom<MdxComponentsType>(),
+    })
+    .partial(),
+  customPages: z.array(
+    z.object({
+      path: z.string(),
+      element: z.custom<NonNullable<ReactNode>>().optional(),
+      render: z.custom<ComponentType<ExposedComponentProps>>().optional(),
+      prose: z.boolean().optional(),
+    }),
+  ),
+  plugins: z.array(z.custom<ApitogoPlugin>()),
+  build: z.custom<{
+    remarkPlugins?: Options["remarkPlugins"];
+    rehypePlugins?: Options["rehypePlugins"];
+  }>(),
+  protectedRoutes: ProtectedRoutesSchema,
+  basePath: z.string().optional(),
+  canonicalUrlOrigin: z.string().optional(),
+  cdnUrl: CdnUrlSchema.optional(),
+  port: z.number().optional(),
+  https: z
+    .object({
+      key: z.string(),
+      cert: z.string(),
+      ca: z.string().optional(),
+    })
+    .optional(),
+  site: SiteSchema,
+  header: HeaderConfigSchema.optional(),
+  navigation: InputNavigationSchema,
+  navigationRules: NavigationRulesSchema.optional(),
+  theme: ThemeConfigSchema,
+  syntaxHighlighting: z
+    .object({
+      languages: z.array(z.custom<BundledLanguage>()),
+      themes: z.object({
+        light: z.custom<BundledTheme>(),
+        dark: z.custom<BundledTheme>(),
+      }),
+    })
+    .partial()
+    .optional(),
+  metadata: MetadataSchema,
+  authentication: AuthenticationSchema,
+  search: SearchSchema,
+  docs: DocsConfigSchema.optional(),
+  modules: ModulesSchema,
+  apis: z.union([ApiSchema, z.array(ApiSchema)]),
+  catalogs: z.union([ApiCatalogSchema, z.array(ApiCatalogSchema)]),
+  apiKeys: ApiKeysSchema,
+  aiAssistants: AiAssistantsSchema,
+  redirects: z.array(Redirect),
+  sitemap: SiteMapSchema,
+  enableStatusPages: z.boolean().optional(),
+  defaults: z.object({
+    apis: ApiOptionsSchema,
+    /**
+     * @deprecated Use `apis.examplesLanguage` or `defaults.apis.examplesLanguage` instead
+     */
+    examplesLanguage: z.string().optional(),
+  }),
+  // Internal: populated by plugins via `transformConfig` to track plugin directories
+  __pluginDirs: z.array(z.string()),
+});
+
+export const ZudokuConfig = BaseConfigSchema.partial();
+
+export type ZudokuApiConfig = z.infer<typeof ApiSchema>;
+export type VersionConfig = z.infer<typeof VersionConfigSchema>;
+export type ZudokuSiteMapConfig = z.infer<typeof SiteMapSchema>;
+export type ZudokuDocsConfig = z.infer<typeof DocsConfigSchema>;
+export type { ModulesConfig } from "./ModulesSchema.js";
+export type {
+  ResolvedModulesConfig,
+  DocsModuleConfig,
+  LandingModuleConfig,
+  LandingContentConfig,
+  LandingFeatureConfig,
+  LandingLinkConfig,
+  ResolvedLandingContent,
+  ResolvedDashboardContent,
+  ResolvedProfileContent,
+  ResolvedPlansContent,
+  ResolvedLandingModule,
+  ResolvedUserPanelModule,
+  ResolvedDashboardModule,
+  ResolvedUserManagementModule,
+  ResolvedApiKeysModule,
+  ResolvedPlansModule,
+  UserPanelModuleConfig,
+  DashboardModuleConfig,
+  UserManagementModuleConfig,
+  ApiKeysModuleConfig,
+  PlansModuleConfig,
+  DashboardContentConfig,
+  ProfileContentConfig,
+  PlansContentConfig,
+  PlanTierConfig,
+} from "./ModulesSchema.js";
+export type ZudokuLlmsConfig = z.infer<typeof LlmsConfigSchema>;
+export type ZudokuRedirect = z.infer<typeof Redirect>;
+export type AuthenticationConfig = z.infer<typeof AuthenticationSchema>;
+
+// Use `z.input` type for flexibility with transforms,
+// but override navigation with `z.infer` for strict validation
+type BaseZudokuConfig = z.input<typeof ZudokuConfig>;
+export type ZudokuConfig = Omit<
+  BaseZudokuConfig,
+  "header" | "navigation" | "navigationRules"
+> & {
+  header?: {
+    navigation?: z.infer<typeof HeaderNavigationSchema>;
+    placements?: {
+      navigation?: "start" | "center" | "end";
+      search?: "start" | "center" | "end";
+      auth?: "start" | "center" | "end" | "navigation";
+    };
+  };
+  navigation?: z.infer<typeof InputNavigationSchema>;
+  navigationRules?: z.infer<typeof NavigationRulesSchema>;
+};
+
+export function validateConfig(config: unknown, configPath?: string) {
+  const validationResult = ZudokuConfig.safeParse(config);
+
+  if (!validationResult.success) {
+    // In production (build mode), throw an error to fail the build
+    if (process.env.NODE_ENV === "production") {
+      throw new Error(
+        `Whoops, looks like there's an issue with your ${configPath ?? "config"}:\n${z.prettifyError(validationResult.error)}`,
+      );
+    }
+
+    // In development mode, log warnings but don't fail
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.log(colors.yellow("Validation errors:"));
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.log(colors.yellow(z.prettifyError(validationResult.error)));
+  }
+}