@mehdad67/apitogo 0.1.24

package/src/config/resolve-modules.ts

@@ -0,0 +1,260 @@
+import {
+  type ResolvedModulesConfig,
+  ModulesSchema,
+  type LandingContentConfig,
+  type ResolvedLandingContent,
+  type DashboardContentConfig,
+  type ProfileContentConfig,
+  type PlansContentConfig,
+  type ResolvedDashboardContent,
+  type ResolvedProfileContent,
+  type ResolvedPlansContent,
+} from "./validators/ModulesSchema.js";
+import type { ZudokuConfig } from "./validators/ZudokuConfig.js";
+
+const DEFAULT_DOCS_FILES = "/pages/**/*.{md,mdx}";
+
+const hasExplicitModules = (config: ZudokuConfig) =>
+  config.modules !== undefined;
+
+export const joinPanelPath = (basePath: string, routePath: string): string => {
+  if (routePath.startsWith("/")) {
+    return routePath.replace(/\/+$/, "") || "/";
+  }
+
+  const base = basePath.replace(/\/+$/, "");
+  const route = routePath.replace(/^\/+/, "");
+
+  if (!base) {
+    return `/${route}`;
+  }
+
+  return `/${`${base}/${route}`.replace(/^\/+/, "")}`;
+};
+
+const DEFAULT_LANDING_FEATURES: ResolvedLandingContent["features"] = [
+  {
+    title: "Documentation",
+    description:
+      "Write guides and references in Markdown or MDX with full navigation and search.",
+  },
+  {
+    title: "API Reference",
+    description:
+      "Publish interactive OpenAPI docs with a built-in playground and code samples.",
+  },
+  {
+    title: "Developer Portal",
+    description:
+      "Extend with landing pages, authentication, API keys, and subscription modules.",
+  },
+];
+
+export const resolveLandingContent = (
+  config: ZudokuConfig,
+  content?: LandingContentConfig,
+): ResolvedLandingContent => {
+  const siteTitle =
+    config.metadata?.applicationName ?? config.site?.title ?? "APIToGo";
+
+  return {
+    hero: {
+      title: content?.hero?.title ?? siteTitle,
+      subtitle: content?.hero?.subtitle ?? "Developer portal",
+      description:
+        content?.hero?.description ??
+        config.metadata?.description ??
+        "Ship beautiful API documentation and developer experiences with APIToGo.",
+    },
+    features: content?.features ?? DEFAULT_LANDING_FEATURES,
+    primaryAction: content?.primaryAction ?? {
+      label: "Get started",
+      href: "/introduction",
+    },
+    secondaryAction: content?.secondaryAction ?? {
+      label: "API Reference",
+      href: "/api",
+    },
+    showPoweredBy: content?.showPoweredBy,
+  };
+};
+
+const DEFAULT_DASHBOARD_QUICK_LINKS: ResolvedDashboardContent["quickLinks"] = [
+  { label: "Documentation", href: "/introduction" },
+  { label: "API Reference", href: "/api" },
+];
+
+export const resolveDashboardContent = (
+  content?: DashboardContentConfig,
+): ResolvedDashboardContent => ({
+  title: content?.title ?? "Dashboard",
+  subtitle: content?.subtitle ?? "Account",
+  description:
+    content?.description ??
+    "Overview of your account activity, documentation shortcuts, and next steps.",
+  quickLinks: content?.quickLinks ?? DEFAULT_DASHBOARD_QUICK_LINKS,
+});
+
+export const resolveProfileContent = (
+  content?: ProfileContentConfig,
+): ResolvedProfileContent => ({
+  title: content?.title ?? "Profile",
+  description:
+    content?.description ??
+    "View your account details and manage profile settings.",
+});
+
+export const resolvePlansContent = (
+  content?: PlansContentConfig,
+): ResolvedPlansContent => ({
+  title: content?.title ?? "Plans & billing",
+  description:
+    content?.description ??
+    "Manage subscription tiers, billing details, and usage limits.",
+  tiers: content?.tiers,
+});
+
+export const resolveModulesConfig = (
+  config: ZudokuConfig,
+): ResolvedModulesConfig => {
+  const parsedModules = ModulesSchema.parse(config.modules);
+  const modules = parsedModules ?? {};
+  const explicit = hasExplicitModules(config);
+
+  const docsModule = modules.docs;
+  const docsEnabled = explicit ? (docsModule?.enabled ?? true) : true;
+
+  const landingModule = modules.landing;
+  const landingEnabled = landingModule?.enabled ?? false;
+
+  const userPanelModule = modules.userPanel;
+  const dashboardConfig = userPanelModule?.dashboard;
+  const userManagementConfig = userPanelModule?.userManagement;
+  const apiKeysModuleConfig = userPanelModule?.apiKeys;
+  const plansConfig = userPanelModule?.plans;
+
+  const dashboardEnabled =
+    dashboardConfig?.enabled ?? (explicit ? false : false);
+
+  const userManagementEnabled = explicit
+    ? (userManagementConfig?.enabled ?? !!config.authentication)
+    : !!config.authentication;
+
+  const apiKeysEnabled = explicit
+    ? (apiKeysModuleConfig?.enabled ?? config.apiKeys?.enabled ?? false)
+    : (config.apiKeys?.enabled ?? false);
+
+  const plansEnabled = plansConfig?.enabled ?? false;
+
+  const userPanelEnabled =
+    userPanelModule?.enabled ??
+    (dashboardEnabled ||
+      userManagementEnabled ||
+      apiKeysEnabled ||
+      plansEnabled);
+
+  const basePath = userPanelModule?.basePath ?? "/account";
+
+  return {
+    docs: {
+      enabled: docsEnabled,
+      files: docsModule?.files ?? config.docs?.files,
+      publishMarkdown:
+        docsModule?.publishMarkdown ?? config.docs?.publishMarkdown,
+      defaultOptions: docsModule?.defaultOptions ?? config.docs?.defaultOptions,
+      llms: docsModule?.llms ?? config.docs?.llms,
+    },
+    landing: {
+      enabled: landingEnabled,
+      path: landingModule?.path ?? "/",
+      component: landingModule?.component,
+      layout: landingModule?.layout ?? "landing",
+      content: resolveLandingContent(config, landingModule?.content),
+    },
+    userPanel: {
+      enabled: userPanelEnabled,
+      basePath,
+      dashboard: {
+        enabled: dashboardEnabled,
+        path: joinPanelPath(basePath, dashboardConfig?.path ?? "dashboard"),
+        content: resolveDashboardContent(dashboardConfig?.content),
+      },
+      userManagement: {
+        enabled: userManagementEnabled,
+        routes: {
+          login: userManagementConfig?.routes?.login ?? "/signin",
+          register: userManagementConfig?.routes?.register ?? "/signup",
+          profile: joinPanelPath(
+            basePath,
+            userManagementConfig?.routes?.profile ?? "profile",
+          ),
+          logout: userManagementConfig?.routes?.logout ?? "/signout",
+        },
+        content: resolveProfileContent(userManagementConfig?.content),
+      },
+      apiKeys: {
+        enabled: apiKeysEnabled,
+        path: joinPanelPath(
+          basePath,
+          apiKeysModuleConfig?.path ?? "settings/api-keys",
+        ),
+      },
+      plans: {
+        enabled: plansEnabled,
+        path: joinPanelPath(basePath, plansConfig?.path ?? "plans"),
+        content: resolvePlansContent(plansConfig?.content),
+      },
+    },
+  };
+};
+
+export const getEffectiveRedirects = (
+  config: ZudokuConfig,
+  resolved: ResolvedModulesConfig,
+) => {
+  const redirects = config.redirects ?? [];
+
+  if (!resolved.landing.enabled) {
+    return redirects;
+  }
+
+  const landingPath = normalizePath(resolved.landing.path);
+
+  return redirects.filter(
+    (redirect) => normalizePath(redirect.from) !== landingPath,
+  );
+};
+
+const normalizePath = (path: string) => {
+  if (path === "/") {
+    return "/";
+  }
+
+  return path.replace(/\/+$/, "") || "/";
+};
+
+export const getEffectiveDocsConfig = (
+  config: ZudokuConfig,
+  resolved: ResolvedModulesConfig,
+) => {
+  if (!resolved.docs.enabled) {
+    return undefined;
+  }
+
+  return {
+    files: resolved.docs.files ?? config.docs?.files ?? [DEFAULT_DOCS_FILES],
+    publishMarkdown:
+      resolved.docs.publishMarkdown ?? config.docs?.publishMarkdown ?? false,
+    defaultOptions: resolved.docs.defaultOptions ?? config.docs?.defaultOptions,
+    llms: resolved.docs.llms ?? config.docs?.llms,
+  };
+};
+
+export const isDocsModuleEnabled = (config: ZudokuConfig) =>
+  resolveModulesConfig(config).docs.enabled;
+
+export const isLandingModuleEnabled = (config: ZudokuConfig) =>
+  resolveModulesConfig(config).landing.enabled;
+
+export const isUserPanelModuleEnabled = (config: ZudokuConfig) =>
+  resolveModulesConfig(config).userPanel.enabled;

package/src/config/validators/BuildSchema.ts

@@ -0,0 +1,95 @@
+import path from "node:path";
+import type { PluggableList } from "unified";
+import { runnerImport } from "vite";
+import { z } from "zod";
+import type { OpenAPIDocument } from "../../lib/oas/graphql/index.js";
+import { fileExists } from "../file-exists.js";
+import { getCurrentConfig } from "../loader.js";
+
+// Schema for build processors
+export const BuildProcessorSchema = z.custom<
+  (data: {
+    file: string;
+    schema: OpenAPIDocument;
+    params: Record<string, string>;
+    dereference: (schema: OpenAPIDocument) => Promise<OpenAPIDocument>;
+  }) => OpenAPIDocument | Promise<OpenAPIDocument>
+>((val) => typeof val === "function");
+
+export type Processor = z.infer<typeof BuildProcessorSchema>;
+export type ProcessorArg = Parameters<Processor>[0];
+
+const PluginConfigSchema = z
+  .custom<PluggableList>()
+  .or(
+    z.custom<(defaultPlugins: PluggableList) => PluggableList>(
+      (val) => typeof val === "function",
+    ),
+  );
+
+export const BuildConfigSchema = z.object({
+  processors: z.array(BuildProcessorSchema).optional(),
+  remarkPlugins: PluginConfigSchema.optional(),
+  rehypePlugins: PluginConfigSchema.optional(),
+  prerender: z.object({ workers: z.number().optional() }).optional(),
+});
+
+const buildConfigFiles = [
+  "apitogo.build.js",
+  "apitogo.build.jsx",
+  "apitogo.build.ts",
+  "apitogo.build.tsx",
+  "apitogo.build.mjs",
+  "zudoku.build.js",
+  "zudoku.build.jsx",
+  "zudoku.build.ts",
+  "zudoku.build.tsx",
+  "zudoku.build.mjs",
+];
+
+async function getBuildConfigFilePath(rootDir: string) {
+  for (const fileName of buildConfigFiles) {
+    const filepath = path.join(rootDir, fileName);
+    if (await fileExists(filepath)) {
+      return filepath;
+    }
+  }
+  return undefined;
+}
+
+export const getBuildConfig = async () => {
+  const initialConfig = getCurrentConfig();
+  const buildFilePath = await getBuildConfigFilePath(
+    initialConfig.__meta.rootDir,
+  );
+
+  if (!buildFilePath) return undefined;
+
+  const buildModule = await runnerImport<{ default: BuildConfig }>(
+    buildFilePath,
+  ).then((m) => m.module.default);
+
+  return validateBuildConfig(buildModule);
+};
+
+export type BuildConfig = z.infer<typeof BuildConfigSchema>;
+
+export function validateBuildConfig(config: unknown): BuildConfig | undefined {
+  const validationResult = BuildConfigSchema.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(z.prettifyError(validationResult.error));
+    }
+
+    // In development mode, log warnings but don't fail
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.warn("Build config validation errors:");
+    // biome-ignore lint/suspicious/noConsole: Logging allowed here
+    console.warn(z.prettifyError(validationResult.error));
+    return;
+  }
+
+  return validationResult.data;
+}

package/src/config/validators/HeaderNavigationSchema.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { IconNames } from "./icon-types.js";
+
+const IconSchema = z.enum(IconNames);
+
+const HeaderNavLinkItemSchema = z.object({
+  label: z.string(),
+  icon: IconSchema.optional(),
+  description: z.string().optional(),
+  to: z.string(),
+  target: z.enum(["_self", "_blank"]).optional(),
+});
+
+const HeaderNavGroupSchema = z.object({
+  label: z.string(),
+  items: z.array(HeaderNavLinkItemSchema),
+});
+
+const HeaderNavItemSchema = z.union([
+  z.object({
+    label: z.string(),
+    icon: IconSchema.optional(),
+    to: z.string(),
+    target: z.enum(["_self", "_blank"]).optional(),
+  }),
+  z.object({
+    label: z.string(),
+    items: z.array(z.union([HeaderNavLinkItemSchema, HeaderNavGroupSchema])),
+  }),
+]);
+
+export const HeaderNavigationSchema = z.array(HeaderNavItemSchema);
+
+export const isHeaderNavGroup = (
+  item: HeaderNavItem | HeaderNavLinkItem | HeaderNavGroup,
+): item is HeaderNavGroup => "items" in item;
+
+export type HeaderNavLinkItem = z.infer<typeof HeaderNavLinkItemSchema>;
+export type HeaderNavGroup = z.infer<typeof HeaderNavGroupSchema>;
+export type HeaderNavItem = z.infer<typeof HeaderNavItemSchema>;
+export type HeaderNavigation = z.infer<typeof HeaderNavigationSchema>;

package/src/config/validators/InputNavigationSchema.test-d.ts

@@ -0,0 +1,178 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: Allow any type
+// biome-ignore-all lint/style/noNonNullAssertion: Allow it
+import { assertType, describe, expectTypeOf, it } from "vitest";
+import type {
+  InputNavigation,
+  InputNavigationCategory,
+  InputNavigationCustomPage,
+  InputNavigationDoc,
+  InputNavigationItem,
+  InputNavigationLink,
+} from "./InputNavigationSchema.js";
+
+describe("InputNavigationSchema types", () => {
+  it("infers correct types for navigation items", () => {
+    // Test that TypeScript correctly infers the types using satisfies
+    const docString = "path/to/doc.md" satisfies InputNavigationItem;
+    const docObject = {
+      type: "doc",
+      file: "path/to/doc.md",
+      label: "My Doc",
+      icon: "book",
+      badge: { label: "New", color: "green" },
+      display: "always",
+    } satisfies InputNavigationItem;
+    const linkObject = {
+      type: "link",
+      label: "External Link",
+      to: "https://example.com",
+      icon: "external-link",
+      badge: { label: "External", color: "blue" },
+      display: "auth",
+    } satisfies InputNavigationItem;
+    const customPage = {
+      type: "custom-page",
+      path: "/custom",
+      label: "Custom Page",
+      element: null,
+      icon: "star",
+      badge: { label: "Custom", color: "purple" },
+      display: "anon",
+    } satisfies InputNavigationItem;
+
+    // Test that these are assignable to InputNavigationItem
+    assertType<InputNavigationItem>(docString);
+    assertType<InputNavigationItem>(docObject);
+    assertType<InputNavigationItem>(linkObject);
+    assertType<InputNavigationItem>(customPage);
+  });
+
+  it("prevents items array from being unknown[]", () => {
+    // Core test: ensure items are properly typed
+    const category = {
+      type: "category",
+      label: "Test Category",
+      items: [
+        "doc.md",
+        { type: "doc", file: "test.md" },
+        { type: "link", label: "Link", to: "https://example.com" },
+        { type: "category", label: "Nested", items: ["nested.md"] },
+      ],
+    } satisfies InputNavigationCategory;
+
+    // Key assertions - items must be InputNavigationItem[], not unknown[]
+    assertType<InputNavigationItem[]>(category.items);
+    expectTypeOf(category.items).not.toEqualTypeOf<unknown[]>();
+    expectTypeOf(category.items).not.toEqualTypeOf<any[]>();
+  });
+
+  it("validates nested structure maintains type safety", () => {
+    const navigation = [
+      {
+        type: "category",
+        label: "Parent",
+        items: [
+          {
+            type: "category",
+            label: "Child",
+            items: ["nested.md", { type: "doc", file: "nested.md" }],
+          },
+        ],
+      },
+    ] satisfies InputNavigation;
+
+    const parent = navigation[0]!;
+    assertType<InputNavigationItem[]>(parent.items);
+
+    const child = parent.items[0]!;
+    assertType<InputNavigationItem[]>(child.items);
+    expectTypeOf(child.items).not.toEqualTypeOf<unknown[]>();
+  });
+
+  it("validates union types work correctly", () => {
+    // Test that all valid types are assignable
+    assertType<InputNavigationItem>("doc.md");
+    assertType<InputNavigationItem>({ type: "doc", file: "test.md" });
+    assertType<InputNavigationItem>({ type: "link", label: "Link", to: "/" });
+    assertType<InputNavigationItem>({
+      type: "category",
+      label: "C",
+      items: [],
+    });
+
+    // Test type constraints
+    expectTypeOf<InputNavigationCategory["items"]>().toEqualTypeOf<
+      InputNavigationItem[]
+    >();
+    expectTypeOf<InputNavigationCategory["items"]>().not.toEqualTypeOf<
+      unknown[]
+    >();
+    expectTypeOf<InputNavigationCategory["items"]>().not.toEqualTypeOf<any[]>();
+  });
+
+  it("validates individual type exports", () => {
+    const doc = {
+      type: "doc",
+      file: "test.md",
+      label: "Test Doc",
+    } satisfies InputNavigationDoc;
+    assertType<InputNavigationDoc>(doc);
+
+    const link = {
+      type: "link",
+      label: "Test Link",
+      to: "https://example.com",
+    } satisfies InputNavigationLink;
+    assertType<InputNavigationLink>(link);
+
+    const customPage = {
+      type: "custom-page",
+      path: "/test",
+      label: "Test Page",
+      element: null,
+    } satisfies InputNavigationCustomPage;
+    assertType<InputNavigationCustomPage>(customPage);
+
+    const category = {
+      type: "category",
+      label: "Test Category",
+      items: ["test.md"] satisfies InputNavigationItem[],
+    } satisfies InputNavigationCategory;
+
+    assertType<InputNavigationCategory>(category);
+    assertType<InputNavigationItem[]>(category.items);
+  });
+
+  it("validates constrained properties", () => {
+    const validDisplayValues = ["auth", "anon", "always", "hide"] as const;
+
+    for (const display of validDisplayValues) {
+      const item = {
+        type: "doc",
+        file: "test.md",
+        display,
+      } satisfies InputNavigationItem;
+      assertType<InputNavigationItem>(item);
+    }
+  });
+
+  it("rejects invalid types", () => {
+    // Test that invalid values fail at compile time
+
+    // @ts-expect-error - number not assignable to InputNavigationItem
+    assertType<InputNavigationItem>(0);
+
+    // @ts-expect-error - missing required 'file' property
+    assertType<InputNavigationItem>({ type: "doc" });
+
+    // @ts-expect-error - missing required 'href' property
+    assertType<InputNavigationItem>({ type: "link", label: "Invalid Link" });
+
+    assertType<InputNavigationCategory>({
+      type: "category",
+      label: "Test",
+      // @ts-expect-error - items should not accept unknown[]
+      items: [] as unknown[],
+    });
+  });
+});