@supatent/supatent-docs 0.1.0

package/runtime/src/docs.config.ts

@@ -0,0 +1,91 @@
+import { defineDocsConfig } from "./framework/config";
+import type { DocsDataMode } from "./framework/types";
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+
+  return value;
+}
+
+function resolveDataMode(
+  value: string | undefined,
+  apiKey: string | undefined,
+): DocsDataMode {
+  if (value === "draft" || value === "published") {
+    return value;
+  }
+
+  if (process.env.NODE_ENV !== "production" && apiKey) {
+    return "draft";
+  }
+
+  return "published";
+}
+
+function parseLocales(value: string | undefined, defaultLocale: string): string[] {
+  if (!value) {
+    return [defaultLocale];
+  }
+
+  const locales = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  if (locales.length === 0) {
+    return [defaultLocale];
+  }
+
+  return locales;
+}
+
+function parseNonNegativeInteger(
+  value: string | undefined,
+  fallback: number,
+): number {
+  if (!value) {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+
+  return Math.trunc(parsed);
+}
+
+const defaultLocale = process.env.DOCS_DEFAULT_LOCALE?.trim() || "en";
+const fallbackMode = process.env.DOCS_FALLBACK_MODE === "none" ? "none" : "defaultLocale";
+const apiKey = process.env.SUPATENT_API_KEY;
+const dataMode = resolveDataMode(process.env.DOCS_DATA_MODE, apiKey);
+
+export const docsConfig = defineDocsConfig({
+  supatent: {
+    baseUrl: process.env.SUPATENT_BASE_URL || "https://app.supatent.ai",
+    apiKey,
+    dataMode,
+    projectSlug: requiredEnv("SUPATENT_PROJECT_SLUG"),
+    cache: {
+      maxAge: parseNonNegativeInteger(process.env.DOCS_CACHE_MAX_AGE, 60),
+      staleWhileRevalidate: parseNonNegativeInteger(
+        process.env.DOCS_CACHE_STALE_WHILE_REVALIDATE,
+        300,
+      ),
+    },
+  },
+  schemas: {
+    settings: requiredEnv("DOCS_SCHEMA_SETTINGS"),
+    page: requiredEnv("DOCS_SCHEMA_PAGE"),
+    category: requiredEnv("DOCS_SCHEMA_CATEGORY"),
+  },
+  routing: {
+    basePath: process.env.DOCS_BASE_PATH || "/docs",
+    defaultLocale,
+    locales: parseLocales(process.env.DOCS_LOCALES, defaultLocale),
+    fallbackMode,
+  },
+});

package/runtime/src/framework/config.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import type { DocsFrameworkConfig } from "./types";
+import { DocsFrameworkError } from "./errors";
+
+const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function normalizeBasePath(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return "/docs";
+  }
+
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/docs";
+}
+
+const configSchema = z
+  .object({
+    supatent: z.object({
+      baseUrl: z.string().url(),
+      apiKey: z.string().min(1, "supatent.apiKey must not be empty").optional(),
+      dataMode: z.enum(["published", "draft"]).default("published"),
+      projectSlug: z
+        .string()
+        .regex(slugPattern, "supatent.projectSlug must be a valid slug"),
+      cache: z.object({
+        maxAge: z.number().int().nonnegative(),
+        staleWhileRevalidate: z.number().int().nonnegative(),
+      }),
+    }),
+    schemas: z.object({
+      settings: z
+        .string()
+        .regex(slugPattern, "schemas.settings must be a valid slug"),
+      page: z.string().regex(slugPattern, "schemas.page must be a valid slug"),
+      category: z
+        .string()
+        .regex(slugPattern, "schemas.category must be a valid slug"),
+    }),
+    routing: z.object({
+      basePath: z.string().transform(normalizeBasePath),
+      defaultLocale: z.string().min(2),
+      locales: z.array(z.string().min(2)).min(1),
+      fallbackMode: z.enum(["none", "defaultLocale"]).default("defaultLocale"),
+    }),
+  })
+  .superRefine((value, ctx) => {
+    if (value.supatent.dataMode === "draft" && !value.supatent.apiKey) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "supatent.apiKey is required when supatent.dataMode is \"draft\"",
+        path: ["supatent", "apiKey"],
+      });
+    }
+
+    if (!value.routing.locales.includes(value.routing.defaultLocale)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "routing.defaultLocale must be included in routing.locales",
+        path: ["routing", "defaultLocale"],
+      });
+    }
+  });
+
+export function defineDocsConfig(input: unknown): DocsFrameworkConfig {
+  const parsed = configSchema.safeParse(input);
+
+  if (!parsed.success) {
+    const issueList = parsed.error.issues
+      .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+      .join("; ");
+    throw new DocsFrameworkError("CONFIG_ERROR", `Invalid docs config: ${issueList}`);
+  }
+
+  return parsed.data;
+}

package/runtime/src/framework/errors.ts

@@ -0,0 +1,34 @@
+export type DocsErrorCode =
+  | "CONFIG_ERROR"
+  | "DATA_ERROR"
+  | "NOT_FOUND"
+  | "UPSTREAM_ERROR";
+
+export class DocsFrameworkError extends Error {
+  public readonly code: DocsErrorCode;
+
+  public readonly causeError?: unknown;
+
+  constructor(code: DocsErrorCode, message: string, causeError?: unknown) {
+    super(message);
+    this.name = "DocsFrameworkError";
+    this.code = code;
+    this.causeError = causeError;
+  }
+}
+
+export function toDocsFrameworkError(
+  error: unknown,
+  defaultCode: DocsErrorCode = "UPSTREAM_ERROR",
+): DocsFrameworkError {
+  if (error instanceof DocsFrameworkError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new DocsFrameworkError(defaultCode, error.message, error);
+  }
+
+  return new DocsFrameworkError(defaultCode, "Unknown docs framework error", error);
+}
+

package/runtime/src/framework/locales.ts

@@ -0,0 +1,45 @@
+import type { DocsFrameworkConfig, DocsLocaleRuntimeConfig } from "./types";
+
+type LocaleConfigLike =
+  | DocsFrameworkConfig
+  | {
+      routing: DocsLocaleRuntimeConfig;
+    }
+  | DocsLocaleRuntimeConfig;
+
+function toLocaleConfig(config: LocaleConfigLike): DocsLocaleRuntimeConfig {
+  if ("routing" in config) {
+    return config.routing;
+  }
+
+  return config;
+}
+
+export function isSupportedLocale(
+  locale: string,
+  config: LocaleConfigLike,
+): boolean {
+  return toLocaleConfig(config).locales.includes(locale);
+}
+
+export function resolveLocaleCandidates(
+  requestedLocale: string,
+  config: LocaleConfigLike,
+): string[] {
+  const localeConfig = toLocaleConfig(config);
+  const candidates: string[] = [];
+
+  if (isSupportedLocale(requestedLocale, localeConfig)) {
+    candidates.push(requestedLocale);
+  }
+
+  if (
+    localeConfig.fallbackMode === "defaultLocale" &&
+    localeConfig.defaultLocale !== requestedLocale &&
+    isSupportedLocale(localeConfig.defaultLocale, localeConfig)
+  ) {
+    candidates.push(localeConfig.defaultLocale);
+  }
+
+  return candidates;
+}

package/runtime/src/framework/markdown-search-text.ts

@@ -0,0 +1,11 @@
+export function markdownToSearchText(markdown: string): string {
+  return markdown
+    .replace(/^:::[^\n]*$/gm, " ")
+    .replace(/^(```|~~~)[^\n]*$/gm, " ")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/!\[[^\]]*]\([^)]*\)/g, " ")
+    .replace(/\[([^\]]+)]\(([^)]+)\)/g, "$1")
+    .replace(/[#>*_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/runtime/src/framework/navigation.ts

@@ -0,0 +1,58 @@
+import type {
+  DocsCategory,
+  DocsFrameworkConfig,
+  DocsNavNode,
+  DocsPage,
+} from "./types";
+import { toDocsPagePath } from "./url";
+
+function sortPages(pages: DocsPage[]): DocsPage[] {
+  return [...pages].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+
+function sortCategories(categories: DocsCategory[]): DocsCategory[] {
+  return [...categories].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+
+export function buildNavigationTree(
+  pages: DocsPage[],
+  categories: DocsCategory[],
+  locale: string,
+  config: DocsFrameworkConfig,
+): DocsNavNode[] {
+  const pagesByCategory = new Map<string, DocsPage[]>();
+  for (const page of sortPages(pages)) {
+    const list = pagesByCategory.get(page.category);
+    if (list) {
+      list.push(page);
+    } else {
+      pagesByCategory.set(page.category, [page]);
+    }
+  }
+
+  return sortCategories(categories).map((category) => ({
+    id: `category:${category.slug}`,
+    title: category.title,
+    slug: null,
+    path: null,
+    order: category.order,
+    children: (pagesByCategory.get(category.slug) ?? []).map((page) => ({
+      id: `page:${page.slug}`,
+      title: page.title,
+      slug: page.slug,
+      path: toDocsPagePath(config, locale, page.slug),
+      order: page.order,
+      children: [],
+    })),
+  }));
+}

package/runtime/src/framework/next-config.ts

@@ -0,0 +1,160 @@
+import type { NextConfig } from "next";
+import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
+import type { DocsFrameworkConfig } from "./types";
+import { generateStaticSearchIndexes } from "./search-index";
+import { DEFAULT_SEARCH_INDEX_OUTPUT_DIR } from "./search-index-types";
+
+type NextConfigContext = {
+  defaultConfig: NextConfig;
+};
+
+type NextConfigFactory = (
+  phase: string,
+  context: NextConfigContext,
+) => NextConfig | Promise<NextConfig>;
+
+type NextConfigInput = NextConfig | NextConfigFactory;
+
+export type SupatentDocsSearchIndexOptions = {
+  enabled?: boolean;
+  outputDir?: string;
+  cwd?: string;
+};
+
+export type SupatentDocsNextConfigOptions = {
+  docsConfig?: DocsFrameworkConfig;
+  searchIndex?: SupatentDocsSearchIndexOptions;
+};
+
+let buildPromise: Promise<void> | null = null;
+
+function shouldBuildIndex(
+  phase: string,
+  options: SupatentDocsSearchIndexOptions | undefined,
+): boolean {
+  if (phase !== PHASE_PRODUCTION_BUILD) {
+    return false;
+  }
+
+  if (options?.enabled === false) {
+    return false;
+  }
+
+  if (process.env.SUPATENT_DOCS_SKIP_INDEX_BUILD === "1") {
+    return false;
+  }
+
+  return true;
+}
+
+async function resolveConfig(
+  input: NextConfigInput,
+  phase: string,
+  context: NextConfigContext,
+): Promise<NextConfig> {
+  if (typeof input === "function") {
+    return input(phase, context);
+  }
+
+  return input;
+}
+
+async function ensureSearchIndexBuilt(
+  options: SupatentDocsNextConfigOptions,
+): Promise<void> {
+  if (!buildPromise) {
+    const searchIndexOptions = options.searchIndex ?? {};
+    const docsConfig = options.docsConfig ?? resolveDocsConfigFromEnv();
+    buildPromise = generateStaticSearchIndexes({
+      config: docsConfig,
+      cwd: searchIndexOptions.cwd,
+      outputDir: searchIndexOptions.outputDir ?? DEFAULT_SEARCH_INDEX_OUTPUT_DIR,
+      logger: (message) => {
+        // eslint-disable-next-line no-console
+        console.log(`[supatent-docs] ${message}`);
+      },
+    }).then(() => undefined);
+  }
+
+  return buildPromise;
+}
+
+export function withSupatentDocs(
+  input: NextConfigInput = {},
+  options: SupatentDocsNextConfigOptions = {},
+): NextConfigFactory {
+  return async (phase, context) => {
+    if (shouldBuildIndex(phase, options.searchIndex)) {
+      await ensureSearchIndexBuilt(options);
+    }
+
+    return resolveConfig(input, phase, context);
+  };
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value || value.trim().length === 0) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+
+  return value.trim();
+}
+
+function parseNonNegativeInteger(value: string | undefined, fallback: number): number {
+  if (!value) {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+
+  return Math.trunc(parsed);
+}
+
+function parseLocales(value: string | undefined, fallback: string): string[] {
+  if (!value) {
+    return [fallback];
+  }
+
+  const locales = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return locales.length > 0 ? locales : [fallback];
+}
+
+function resolveDocsConfigFromEnv(): DocsFrameworkConfig {
+  const defaultLocale = process.env.DOCS_DEFAULT_LOCALE?.trim() || "en";
+  const apiKey = process.env.SUPATENT_API_KEY;
+
+  return {
+    supatent: {
+      baseUrl: process.env.SUPATENT_BASE_URL || "https://app.supatent.ai",
+      projectSlug: requireEnv("SUPATENT_PROJECT_SLUG"),
+      apiKey,
+      dataMode: "published",
+      cache: {
+        maxAge: parseNonNegativeInteger(process.env.DOCS_CACHE_MAX_AGE, 60),
+        staleWhileRevalidate: parseNonNegativeInteger(
+          process.env.DOCS_CACHE_STALE_WHILE_REVALIDATE,
+          300,
+        ),
+      },
+    },
+    schemas: {
+      settings: requireEnv("DOCS_SCHEMA_SETTINGS"),
+      page: requireEnv("DOCS_SCHEMA_PAGE"),
+      category: requireEnv("DOCS_SCHEMA_CATEGORY"),
+    },
+    routing: {
+      basePath: process.env.DOCS_BASE_PATH || "/docs",
+      defaultLocale,
+      locales: parseLocales(process.env.DOCS_LOCALES, defaultLocale),
+      fallbackMode: process.env.DOCS_FALLBACK_MODE === "none" ? "none" : "defaultLocale",
+    },
+  };
+}