@supatent/supatent-docs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { D as DocsFrameworkConfig } from './types-Cf4pRODK.js';
+export { a as DocsCategory, b as DocsDataMode, c as DocsLocaleRuntimeConfig, d as DocsNavNode, e as DocsPage, f as DocsPageResolution, L as LocaleFallbackMode } from './types-Cf4pRODK.js';
+
+declare function defineDocsConfig(input: unknown): DocsFrameworkConfig;
+
+export { DocsFrameworkConfig, defineDocsConfig };

package/dist/index.js

@@ -0,0 +1,75 @@
+import {
+  external_exports
+} from "./chunk-QVZFIUSH.js";
+
+// runtime/src/framework/errors.ts
+var DocsFrameworkError = class extends Error {
+  code;
+  causeError;
+  constructor(code, message, causeError) {
+    super(message);
+    this.name = "DocsFrameworkError";
+    this.code = code;
+    this.causeError = causeError;
+  }
+};
+
+// runtime/src/framework/config.ts
+var slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function normalizeBasePath(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return "/docs";
+  }
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/docs";
+}
+var configSchema = external_exports.object({
+  supatent: external_exports.object({
+    baseUrl: external_exports.string().url(),
+    apiKey: external_exports.string().min(1, "supatent.apiKey must not be empty").optional(),
+    dataMode: external_exports.enum(["published", "draft"]).default("published"),
+    projectSlug: external_exports.string().regex(slugPattern, "supatent.projectSlug must be a valid slug"),
+    cache: external_exports.object({
+      maxAge: external_exports.number().int().nonnegative(),
+      staleWhileRevalidate: external_exports.number().int().nonnegative()
+    })
+  }),
+  schemas: external_exports.object({
+    settings: external_exports.string().regex(slugPattern, "schemas.settings must be a valid slug"),
+    page: external_exports.string().regex(slugPattern, "schemas.page must be a valid slug"),
+    category: external_exports.string().regex(slugPattern, "schemas.category must be a valid slug")
+  }),
+  routing: external_exports.object({
+    basePath: external_exports.string().transform(normalizeBasePath),
+    defaultLocale: external_exports.string().min(2),
+    locales: external_exports.array(external_exports.string().min(2)).min(1),
+    fallbackMode: external_exports.enum(["none", "defaultLocale"]).default("defaultLocale")
+  })
+}).superRefine((value, ctx) => {
+  if (value.supatent.dataMode === "draft" && !value.supatent.apiKey) {
+    ctx.addIssue({
+      code: external_exports.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: external_exports.ZodIssueCode.custom,
+      message: "routing.defaultLocale must be included in routing.locales",
+      path: ["routing", "defaultLocale"]
+    });
+  }
+});
+function defineDocsConfig(input) {
+  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;
+}
+export {
+  defineDocsConfig
+};

package/dist/next-config.d.ts

@@ -0,0 +1,20 @@
+import { NextConfig } from 'next';
+import { D as DocsFrameworkConfig } from './types-Cf4pRODK.js';
+
+type NextConfigContext = {
+    defaultConfig: NextConfig;
+};
+type NextConfigFactory = (phase: string, context: NextConfigContext) => NextConfig | Promise<NextConfig>;
+type NextConfigInput = NextConfig | NextConfigFactory;
+type SupatentDocsSearchIndexOptions = {
+    enabled?: boolean;
+    outputDir?: string;
+    cwd?: string;
+};
+type SupatentDocsNextConfigOptions = {
+    docsConfig?: DocsFrameworkConfig;
+    searchIndex?: SupatentDocsSearchIndexOptions;
+};
+declare function withSupatentDocs(input?: NextConfigInput, options?: SupatentDocsNextConfigOptions): NextConfigFactory;
+
+export { type SupatentDocsNextConfigOptions, type SupatentDocsSearchIndexOptions, withSupatentDocs };

package/dist/next-config.js

@@ -0,0 +1,305 @@
+import {
+  external_exports
+} from "./chunk-QVZFIUSH.js";
+
+// runtime/src/framework/next-config.ts
+import { PHASE_PRODUCTION_BUILD } from "next/constants.js";
+
+// runtime/src/framework/search-index.ts
+import { createHash } from "crypto";
+import { mkdir, readdir, unlink, writeFile } from "fs/promises";
+import path from "path";
+import {
+  createClient
+} from "@supatent/client";
+
+// runtime/src/framework/search-index-types.ts
+var DEFAULT_SEARCH_INDEX_OUTPUT_DIR = "public/.supatent-docs/search";
+
+// runtime/src/framework/markdown-search-text.ts
+function markdownToSearchText(markdown) {
+  return markdown.replace(/^:::[^\n]*$/gm, " ").replace(/^(```|~~~)[^\n]*$/gm, " ").replace(/`([^`]+)`/g, "$1").replace(/!\[[^\]]*]\([^)]*\)/g, " ").replace(/\[([^\]]+)]\(([^)]+)\)/g, "$1").replace(/[#>*_-]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+// runtime/src/framework/search-index.ts
+var MANIFEST_FILENAME = "manifest.json";
+var pageFieldsSchema = external_exports.object({
+  title: external_exports.string().min(1),
+  body: external_exports.string(),
+  category: external_exports.string().min(1),
+  order: external_exports.preprocess(
+    (value) => {
+      if (typeof value === "string") {
+        return Number(value);
+      }
+      return value;
+    },
+    external_exports.number().finite()
+  )
+});
+function normalizeLocales(locales) {
+  const unique = /* @__PURE__ */ new Set();
+  for (const locale of locales) {
+    const normalized = locale.trim();
+    if (normalized) {
+      unique.add(normalized);
+    }
+  }
+  return [...unique];
+}
+function resolveConfiguredRuntimeLocales(config) {
+  const locales = normalizeLocales(config.routing.locales);
+  const fallbackDefault = config.routing.defaultLocale;
+  const hasDefault = locales.includes(fallbackDefault);
+  const defaultLocale = hasDefault ? fallbackDefault : locales[0] ?? fallbackDefault;
+  return {
+    defaultLocale,
+    locales: locales.length > 0 ? locales : [fallbackDefault]
+  };
+}
+function sanitizeLocaleForFileName(locale) {
+  const normalized = locale.trim().toLowerCase();
+  return normalized.replace(/[^a-z0-9-]/g, "-");
+}
+function normalizeSlugPart(value) {
+  return value.replace(/^\/+|\/+$/g, "");
+}
+function joinPath(...segments) {
+  const clean = segments.map(normalizeSlugPart).filter(Boolean);
+  return `/${clean.join("/")}`;
+}
+function toDocsPagePath(config, locale, slug) {
+  return joinPath(locale, config.routing.basePath, slug);
+}
+function normalizePage(item) {
+  const parsed = pageFieldsSchema.safeParse(item.data);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((issue) => issue.message).join("; ");
+    throw new Error(`Invalid page shape for slug "${item.slug}": ${issues}`);
+  }
+  return {
+    slug: item.slug,
+    title: parsed.data.title,
+    body: parsed.data.body,
+    category: parsed.data.category,
+    order: parsed.data.order,
+    locale: item.locale
+  };
+}
+function sortPages(pages) {
+  return [...pages].sort((a, b) => {
+    if (a.order === b.order) {
+      return a.slug.localeCompare(b.slug);
+    }
+    return a.order - b.order;
+  });
+}
+function buildDocument(page, config, locale) {
+  return {
+    id: `${locale}:${page.slug}`,
+    locale,
+    slug: page.slug,
+    title: page.title,
+    path: toDocsPagePath(config, locale, page.slug),
+    order: page.order,
+    plainText: markdownToSearchText(page.body)
+  };
+}
+function toStableJson(value) {
+  return JSON.stringify(value);
+}
+function buildIndexFileName(locale, payloadJson) {
+  const hash = createHash("sha256").update(payloadJson).digest("hex").slice(0, 12);
+  const fileName = `index.${sanitizeLocaleForFileName(locale)}.${hash}.json`;
+  return { fileName, hash };
+}
+function createLocaleClient(config, locale) {
+  return createClient({
+    baseUrl: config.supatent.baseUrl,
+    projectSlug: config.supatent.projectSlug,
+    apiKey: config.supatent.apiKey,
+    preview: false,
+    locale,
+    cache: config.supatent.cache
+  });
+}
+async function fetchRuntimeLocales(config) {
+  try {
+    const response = await createLocaleClient(config).getLocales();
+    const locales = normalizeLocales(response.locales.map((entry) => entry.code));
+    if (locales.length === 0) {
+      throw new Error("Supatent returned no locales.");
+    }
+    const defaultLocale = locales.includes(response.default) ? response.default : locales[0];
+    return {
+      defaultLocale,
+      locales
+    };
+  } catch {
+    return resolveConfiguredRuntimeLocales(config);
+  }
+}
+async function fetchPublishedPagesForLocale(config, locale) {
+  const items = await createLocaleClient(config, locale).schema(config.schemas.page).all();
+  const published = items.filter((item) => item.publishedAt !== null);
+  return sortPages(published.map(normalizePage));
+}
+async function clearGeneratedIndexFiles(outputDir) {
+  const entries = await readdir(outputDir, { withFileTypes: true });
+  await Promise.all(
+    entries.filter(
+      (entry) => entry.isFile() && (entry.name === MANIFEST_FILENAME || entry.name.startsWith("index.") && entry.name.endsWith(".json"))
+    ).map((entry) => unlink(path.join(outputDir, entry.name)))
+  );
+}
+function createLocaleSearchIndexPayload(locale, pages, config, generatedAt) {
+  return {
+    locale,
+    generatedAt,
+    documents: pages.map((page) => buildDocument(page, config, locale))
+  };
+}
+async function generateStaticSearchIndexes(options) {
+  const { config, logger } = options;
+  const cwd = options.cwd ?? process.cwd();
+  const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_SEARCH_INDEX_OUTPUT_DIR);
+  await mkdir(outputDir, { recursive: true });
+  await clearGeneratedIndexFiles(outputDir);
+  const runtimeLocales = await fetchRuntimeLocales(config);
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const manifestEntries = [];
+  for (const locale of runtimeLocales.locales) {
+    const pages = await fetchPublishedPagesForLocale(config, locale);
+    const payload = createLocaleSearchIndexPayload(locale, pages, config, generatedAt);
+    const payloadJson = toStableJson(payload);
+    const { fileName, hash } = buildIndexFileName(locale, payloadJson);
+    await writeFile(path.join(outputDir, fileName), payloadJson, "utf8");
+    manifestEntries.push({
+      locale,
+      file: fileName,
+      hash,
+      documentCount: payload.documents.length
+    });
+    logger?.(
+      `Built search index locale=${locale} docs=${payload.documents.length} file=${fileName}`
+    );
+  }
+  const manifest = {
+    version: 1,
+    generatedAt,
+    defaultLocale: runtimeLocales.defaultLocale,
+    basePath: config.routing.basePath,
+    outputDir: options.outputDir ?? DEFAULT_SEARCH_INDEX_OUTPUT_DIR,
+    entries: manifestEntries
+  };
+  const manifestPath = path.join(outputDir, MANIFEST_FILENAME);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+  logger?.(`Wrote search index manifest: ${manifestPath}`);
+  return {
+    outputDir,
+    manifestPath,
+    manifest
+  };
+}
+
+// runtime/src/framework/next-config.ts
+var buildPromise = null;
+function shouldBuildIndex(phase, options) {
+  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, phase, context) {
+  if (typeof input === "function") {
+    return input(phase, context);
+  }
+  return input;
+}
+async function ensureSearchIndexBuilt(options) {
+  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) => {
+        console.log(`[supatent-docs] ${message}`);
+      }
+    }).then(() => void 0);
+  }
+  return buildPromise;
+}
+function withSupatentDocs(input = {}, options = {}) {
+  return async (phase, context) => {
+    if (shouldBuildIndex(phase, options.searchIndex)) {
+      await ensureSearchIndexBuilt(options);
+    }
+    return resolveConfig(input, phase, context);
+  };
+}
+function requireEnv(name) {
+  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, fallback) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return Math.trunc(parsed);
+}
+function parseLocales(value, fallback) {
+  if (!value) {
+    return [fallback];
+  }
+  const locales = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return locales.length > 0 ? locales : [fallback];
+}
+function resolveDocsConfigFromEnv() {
+  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"
+    }
+  };
+}
+export {
+  withSupatentDocs
+};

package/dist/types-Cf4pRODK.d.ts

@@ -0,0 +1,60 @@
+type LocaleFallbackMode = "none" | "defaultLocale";
+type DocsDataMode = "published" | "draft";
+type DocsFrameworkConfig = {
+    supatent: {
+        baseUrl: string;
+        apiKey?: string;
+        dataMode: DocsDataMode;
+        projectSlug: string;
+        cache: {
+            maxAge: number;
+            staleWhileRevalidate: number;
+        };
+    };
+    schemas: {
+        settings: string;
+        page: string;
+        category: string;
+    };
+    routing: {
+        basePath: string;
+        defaultLocale: string;
+        locales: string[];
+        fallbackMode: LocaleFallbackMode;
+    };
+};
+type DocsPage = {
+    slug: string;
+    title: string;
+    body: string;
+    category: string;
+    order: number;
+    locale: string;
+};
+type DocsCategory = {
+    slug: string;
+    title: string;
+    order: number;
+    locale: string;
+};
+type DocsNavNode = {
+    id: string;
+    title: string;
+    slug: string | null;
+    path: string | null;
+    order: number;
+    children: DocsNavNode[];
+};
+type DocsPageResolution = {
+    page: DocsPage;
+    requestedLocale: string;
+    resolvedLocale: string;
+    usedFallback: boolean;
+};
+type DocsLocaleRuntimeConfig = {
+    defaultLocale: string;
+    locales: string[];
+    fallbackMode: LocaleFallbackMode;
+};
+
+export type { DocsFrameworkConfig as D, LocaleFallbackMode as L, DocsCategory as a, DocsDataMode as b, DocsLocaleRuntimeConfig as c, DocsNavNode as d, DocsPage as e, DocsPageResolution as f };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@supatent/supatent-docs",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "runtime"
+  ],
+  "scripts": {
+    "prepare:runtime": "node scripts/prepare-runtime.mjs",
+    "build": "pnpm run prepare:runtime && tsup --config tsup.config.ts",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run build"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./src/next.ts",
+      "import": "./src/next.ts",
+      "default": "./src/next.ts"
+    },
+    "./next-config": {
+      "types": "./dist/next-config.d.ts",
+      "import": "./dist/next-config.js",
+      "default": "./dist/next-config.js"
+    },
+    "./styles.css": "./runtime/src/app/globals.css",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@supatent/client": "^0.3.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "next": "^16.1.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  }
+}

package/runtime/middleware.ts

@@ -0,0 +1,52 @@
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+import { docsConfig } from "./src/docs.config";
+import { INTERNAL_DOCS_SEGMENT, toInternalDocsPath } from "./src/framework/url";
+
+const INTERNAL_PREFIX = `/${INTERNAL_DOCS_SEGMENT}`;
+
+function getLocaleFromPathname(pathname: string): string | null {
+  const firstSegment = pathname.split("/").filter(Boolean)[0];
+  return firstSegment || null;
+}
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+  const requestHeaders = new Headers(request.headers);
+  const locale = getLocaleFromPathname(pathname);
+
+  if (locale) {
+    requestHeaders.set("x-docs-request-locale", locale);
+  } else {
+    requestHeaders.delete("x-docs-request-locale");
+  }
+
+  if (pathname.includes(INTERNAL_PREFIX)) {
+    return NextResponse.next({
+      request: {
+        headers: requestHeaders,
+      },
+    });
+  }
+
+  const internalPath = toInternalDocsPath(pathname, docsConfig);
+  if (!internalPath) {
+    return NextResponse.next({
+      request: {
+        headers: requestHeaders,
+      },
+    });
+  }
+
+  const rewrittenUrl = request.nextUrl.clone();
+  rewrittenUrl.pathname = internalPath;
+  return NextResponse.rewrite(rewrittenUrl, {
+    request: {
+      headers: requestHeaders,
+    },
+  });
+}
+
+export const config = {
+  matcher: ["/((?!_next|api|favicon.ico|robots.txt|sitemap.xml).*)"],
+};

package/runtime/src/app/[locale]/docs-internal/[[...slug]]/page.tsx

@@ -0,0 +1,91 @@
+import { notFound } from "next/navigation";
+import { DocsShell } from "../../../../components/docs-shell";
+import { docsConfig } from "../../../../docs.config";
+import { isSupportedLocale } from "../../../../framework/locales";
+import { renderMarkdownToHtml } from "../../../../framework/rendering";
+import { createDocsService } from "../../../../framework/service";
+import { getRuntimeLocales } from "../../../../framework/runtime-locales";
+
+type RouteParams = {
+  locale: string;
+  slug?: string[];
+};
+
+export const dynamic = "force-dynamic";
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[`*_~()[\]]/g, "")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-");
+}
+
+function extractToc(markdown: string): Array<{ id: string; label: string; depth: number }> {
+  const items = [{ id: "overview", label: "Overview", depth: 1 }];
+
+  for (const line of markdown.split("\n")) {
+    const match = line.match(/^(##|###)\s+(.+)$/);
+    if (!match) continue;
+
+    items.push({
+      id: slugify(match[2]),
+      label: match[2].trim(),
+      depth: match[1].length,
+    });
+  }
+
+  return items;
+}
+
+export default async function DocsPage({
+  params,
+}: {
+  params: Promise<RouteParams> | RouteParams;
+}) {
+  const resolvedParams = await Promise.resolve(params);
+  const locale = resolvedParams.locale;
+  const runtimeLocales = await getRuntimeLocales({
+    dataMode: docsConfig.supatent.dataMode,
+  });
+  const localeConfig = {
+    defaultLocale: runtimeLocales.defaultLocale,
+    locales: runtimeLocales.locales,
+    fallbackMode: docsConfig.routing.fallbackMode,
+  };
+  const docsService = createDocsService(docsConfig, {
+    dataMode: docsConfig.supatent.dataMode,
+    localeConfig,
+  });
+
+  if (!isSupportedLocale(locale, localeConfig)) {
+    notFound();
+  }
+
+  const slug = resolvedParams.slug?.join("/") ?? "";
+
+  const [pageResult, navResult] = await Promise.all([
+    docsService.getPage(locale, slug),
+    docsService.getNavigation(locale),
+  ]);
+
+  if (!pageResult || !navResult) {
+    notFound();
+  }
+
+  const pageHtml = await renderMarkdownToHtml(pageResult.page.body);
+  const tocItems = extractToc(pageResult.page.body);
+
+  return (
+    <DocsShell
+      pageHtml={pageHtml}
+      navigation={navResult.navigation}
+      activeSlug={pageResult.page.slug}
+      locales={runtimeLocales.locales}
+      defaultLocale={runtimeLocales.defaultLocale}
+      basePath={docsConfig.routing.basePath}
+      tocItems={tocItems}
+    />
+  );
+}