@raystack/chronicle 0.3.0 → 0.4.0

package/src/lib/source.ts

@@ -1,67 +1,143 @@
-import { docs } from '@/.source/server'
-import { loader } from 'fumadocs-core/source'
-import type { PageTree, PageTreeItem, Frontmatter } from '@/types'
-
-export const source = loader({
-  baseUrl: '/',
-  source: docs.toFumadocsSource(),
-})
-
-export function sortByOrder<T extends { frontmatter?: Frontmatter }>(
-  items: T[]
-): T[] {
-  return [...items].sort((a, b) => {
-    const orderA = a.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    const orderB = b.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    return orderA - orderB
-  })
-}
+import { loader } from 'fumadocs-core/source';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+import type { MDXContent } from 'mdx/types';
+import type { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
+
+const CONTENT_PREFIX = '../../.content/';
+
+const frontmatterGlob: Record<string, Record<string, unknown>> = import.meta.glob(
+  '../../.content/**/*.{mdx,md}',
+  { eager: true, import: 'frontmatter' }
+);
 
-export function buildPageTree(): PageTree {
-  const pages = source.getPages()
-  const folders = new Map<string, PageTreeItem[]>()
-  const rootPages: PageTreeItem[] = []
+const metaGlob: Record<string, Record<string, unknown>> = import.meta.glob(
+  '../../.content/**/meta.json',
+  { eager: true }
+);
 
-  pages.forEach((page) => {
-    const data = page.data as { title?: string; order?: number }
-    const isIndex = page.url === '/'
-    const item: PageTreeItem = {
+function buildFiles() {
+  const files: {
+    type: 'page' | 'meta';
+    path: string;
+    data: Record<string, unknown>;
+  }[] = [];
+
+  for (const [key, data] of Object.entries(frontmatterGlob)) {
+    const originalPath = key.slice(CONTENT_PREFIX.length);
+    const relativePath = originalPath.replace(/readme\.(mdx?)$/i, 'index.$1');
+    files.push({
       type: 'page',
-      name: data.title ?? page.slugs.join('/') ?? 'Untitled',
-      url: page.url,
-      order: data.order ?? (isIndex ? 0 : undefined),
-    }
-
-    if (page.slugs.length > 1) {
-      const folder = page.slugs[0]
-      if (!folders.has(folder)) {
-        folders.set(folder, [])
-      }
-      folders.get(folder)?.push(item)
-    } else {
-      rootPages.push(item)
-    }
-  })
-
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
-
-  const children: PageTreeItem[] = sortByOrder(rootPages)
-
-  const folderItems: PageTreeItem[] = []
-  folders.forEach((items, folder) => {
-    const sorted = sortByOrder(items)
-    const indexPage = items.find(item => item.url === `/${folder}`)
-    const folderOrder = indexPage?.order ?? sorted[0]?.order
-    folderItems.push({
-      type: 'folder',
-      name: folder.charAt(0).toUpperCase() + folder.slice(1),
-      order: folderOrder,
-      children: sorted,
-    })
-  })
-
-  children.push(...sortByOrder(folderItems))
-
-  return { name: 'root', children }
+      path: relativePath,
+      data: { ...data, _relativePath: relativePath, _originalPath: originalPath }
+    });
+  }
+
+  for (const [key, data] of Object.entries(metaGlob)) {
+    const relativePath = key.slice(CONTENT_PREFIX.length);
+    files.push({ type: 'meta', path: relativePath, data: data ?? {} });
+  }
+
+  return files;
+}
+
+let cachedSource: ReturnType<typeof loader> | null = null;
+
+async function getSource() {
+  if (cachedSource) return cachedSource;
+  const files = buildFiles();
+  cachedSource = loader({
+    source: { files },
+    baseUrl: '/'
+  });
+  return cachedSource;
+}
+
+export { getSource as source };
+
+export function invalidate() {
+  cachedSource = null;
+}
+
+function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return orderMap.get(node.url);
+  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+  return undefined;
+}
+
+function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+  return [...nodes]
+    .map(n =>
+      n.type === 'folder'
+        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        : n
+    )
+    .sort(
+      (a, b) =>
+        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+    );
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
+  const orderMap = new Map<string, number>();
+  for (const page of pages) {
+    const d = page.data as Record<string, unknown>;
+    const order = d.order as number | undefined;
+    if (order !== undefined) orderMap.set(page.url, order);
+    if (page.url === '/') orderMap.set('/', order ?? 0);
+  }
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
+}
+
+export async function getPageTree(): Promise<Root> {
+  const s = await getSource();
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
+
+export async function getPages() {
+  const s = await getSource();
+  return s.getPages();
+}
+
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
+}
+
+export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
+  const d = page.data as Record<string, unknown>;
+  return {
+    title: (d.title as string) ?? fallbackTitle ?? 'Untitled',
+    description: d.description as string | undefined,
+    order: d.order as number | undefined,
+    icon: d.icon as string | undefined,
+    lastModified: d.lastModified as string | undefined,
+  };
+}
+
+export function getRelativePath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
+}
+
+export function getOriginalPath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._originalPath as string) ?? '';
+}
+
+const ssrModules = import.meta.glob<{ default?: MDXContent; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+export async function loadPageModule(
+  relativePath: string
+): Promise<{ default: MDXContent | null; toc: TableOfContents }> {
+  if (!relativePath || relativePath.includes('..')) return { default: null, toc: [] };
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = ssrModules[key];
+  if (!loader) return { default: null, toc: [] };
+  const mod = await loader();
+  return { default: mod.default ?? null, toc: mod.toc ?? [] };
 }

package/src/pages/ApiLayout.tsx

@@ -0,0 +1,33 @@
+import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
+import { Search } from '@/components/ui/search';
+import { buildApiPageTree } from '@/lib/api-routes';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import styles from './ApiLayout.module.css';
+
+interface ApiLayoutProps {
+  children: ReactNode;
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+  const { config, apiSpecs } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+  const tree = buildApiPageTree(apiSpecs);
+
+  return (
+    <Layout
+      config={config}
+      tree={tree}
+      classNames={{
+        layout: cx(styles.layout, className),
+        body: styles.body,
+        sidebar: styles.sidebar,
+        content: styles.content
+      }}
+    >
+      <Search className={styles.hiddenSearch} />
+      {children}
+    </Layout>
+  );
+}

package/src/pages/ApiPage.tsx

@@ -0,0 +1,73 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+import type { OpenAPIV3 } from 'openapi-types';
+import { EndpointPage } from '@/components/api';
+import { findApiOperation } from '@/lib/api-routes';
+import { Head } from '@/lib/head';
+import type { ApiSpec } from '@/lib/openapi';
+import { usePageContext } from '@/lib/page-context';
+
+interface ApiPageProps {
+  slug: string[];
+}
+
+export function ApiPage({ slug }: ApiPageProps) {
+  const { config, apiSpecs } = usePageContext();
+
+  if (slug.length === 0) {
+    return (
+      <>
+        <Head
+          title='API Reference'
+          description={`API documentation for ${config.title}`}
+          config={config}
+        />
+        <ApiLanding specs={apiSpecs} />
+      </>
+    );
+  }
+
+  const match = findApiOperation(apiSpecs, slug);
+  if (!match) return null;
+
+  const operation = match.operation as OpenAPIV3.OperationObject;
+  const title =
+    operation.summary ?? `${match.method.toUpperCase()} ${match.path}`;
+
+  return (
+    <>
+      <Head title={title} description={operation.description} config={config} />
+      <EndpointPage
+        method={match.method}
+        path={match.path}
+        operation={match.operation}
+        serverUrl={match.spec.server.url}
+        specName={match.spec.name}
+        auth={match.spec.auth}
+      />
+    </>
+  );
+}
+
+function ApiLanding({ specs }: { specs: ApiSpec[] }) {
+  return (
+    <Flex
+      direction='column'
+      gap='large'
+      style={{ padding: 'var(--rs-space-7)' }}
+    >
+      <Headline size='medium' as='h1'>
+        API Reference
+      </Headline>
+      {specs.map(spec => (
+        <Flex key={spec.name} direction='column' gap='small'>
+          <Headline size='small' as='h2'>
+            {spec.name}
+          </Headline>
+          {spec.document.info.description && (
+            <Text size={3}>{spec.document.info.description}</Text>
+          )}
+        </Flex>
+      ))}
+    </Flex>
+  );
+}

package/src/pages/DocsLayout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsLayoutProps {
+  children: ReactNode;
+}
+
+export function DocsLayout({ children }: DocsLayoutProps) {
+  const { config, tree } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+
+  return (
+    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+      {children}
+    </Layout>
+  );
+}

package/src/pages/DocsPage.tsx

@@ -0,0 +1,43 @@
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsPageProps {
+  slug: string[];
+}
+
+export function DocsPage({ slug }: DocsPageProps) {
+  const { config, tree, page } = usePageContext();
+
+  if (!page) return null;
+
+  const { Page } = getTheme(config.theme?.name);
+  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
+
+  return (
+    <>
+      <Head
+        title={page.frontmatter.title}
+        description={page.frontmatter.description}
+        config={config}
+        jsonLd={{
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: page.frontmatter.title,
+          description: page.frontmatter.description,
+          ...(pageUrl && { url: pageUrl })
+        }}
+      />
+      <Page
+        page={{
+          slug,
+          frontmatter: page.frontmatter,
+          content: page.content,
+          toc: page.toc
+        }}
+        config={config}
+        tree={tree}
+      />
+    </>
+  );
+}

package/src/pages/NotFound.tsx

@@ -0,0 +1,17 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+
+export function NotFound() {
+  return (
+    <Flex
+      direction='column'
+      align='center'
+      justify='center'
+      style={{ minHeight: '60vh' }}
+    >
+      <Headline size='large' as='h1'>
+        404
+      </Headline>
+      <Text size={3}>Page not found</Text>
+    </Flex>
+  );
+}

package/src/server/App.tsx

@@ -0,0 +1,72 @@
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import { ThemeProvider } from '@raystack/apsara';
+import { useLocation } from 'react-router';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { ApiLayout } from '@/pages/ApiLayout';
+import { ApiPage } from '@/pages/ApiPage';
+import { DocsLayout } from '@/pages/DocsLayout';
+import { DocsPage } from '@/pages/DocsPage';
+import type { ChronicleConfig } from '@/types';
+import { getThemeConfig } from '@/themes/registry';
+
+function resolveRoute(pathname: string) {
+  if (pathname.startsWith('/apis')) {
+    const slug = pathname
+      .replace(/^\/apis\/?/, '')
+      .split('/')
+      .filter(Boolean);
+    return { type: 'api' as const, slug };
+  }
+
+  const slug =
+    pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+  return { type: 'docs' as const, slug };
+}
+
+export function App() {
+  const { pathname } = useLocation();
+  const { config } = usePageContext();
+  const route = resolveRoute(pathname);
+  const themeConfig = getThemeConfig(config.theme?.name);
+
+  return (
+    <ThemeProvider
+      enableSystem={themeConfig.enableSystem}
+      forcedTheme={themeConfig.forcedTheme}
+    >
+      <RootHead config={config} />
+      {route.type === 'api' ? (
+        <ApiLayout>
+          <ApiPage slug={route.slug} />
+        </ApiLayout>
+      ) : (
+        <DocsLayout>
+          <DocsPage slug={route.slug} />
+        </DocsLayout>
+      )}
+    </ThemeProvider>
+  );
+}
+
+function RootHead({ config }: { config: ChronicleConfig }) {
+  return (
+    <Head
+      title={config.title}
+      description={config.description}
+      config={config}
+      jsonLd={
+        config.url
+          ? {
+              '@context': 'https://schema.org',
+              '@type': 'WebSite',
+              name: config.title,
+              description: config.description,
+              url: config.url
+            }
+          : undefined
+      }
+    />
+  );
+}

package/src/server/api/apis-proxy.ts

@@ -0,0 +1,69 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+interface ProxyRequest {
+  specName: string;
+  method: string;
+  path: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export default defineHandler(async event => {
+  if (event.req.method !== 'POST') {
+    throw new HTTPError({ status: 405, message: 'Method not allowed' });
+  }
+
+  const { specName, method, path, headers, body } =
+    (await event.req.json()) as ProxyRequest;
+
+  if (!specName || !method || !path) {
+    throw new HTTPError({
+      status: 400,
+      message: 'Missing specName, method, or path'
+    });
+  }
+
+  const config = loadConfig();
+  const specs = await loadApiSpecs(config.api ?? []);
+  const spec = specs.find(s => s.name === specName);
+
+  if (!spec) {
+    throw new HTTPError({ status: 404, message: `Unknown spec: ${specName}` });
+  }
+
+  if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
+    throw new HTTPError({ status: 400, message: 'Invalid path' });
+  }
+
+  const url = spec.server.url + path;
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined
+    });
+
+    const contentType = response.headers.get('content-type') ?? '';
+    const responseBody = contentType.includes('application/json')
+      ? await response.json()
+      : await response.text();
+
+    return {
+      status: response.status,
+      statusText: response.statusText,
+      body: responseBody
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ''}`
+        : 'Request failed';
+    throw new HTTPError({
+      status: 502,
+      message: `Could not reach ${url}\n${message}`
+    });
+  }
+});

package/src/server/api/health.ts

@@ -0,0 +1,5 @@
+import { defineHandler } from 'nitro';
+
+export default defineHandler(() => {
+  return { status: 'ok' };
+});

package/src/server/api/page/[...slug].ts

@@ -0,0 +1,18 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { getPage, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const slugParam = event.context.params?.slug ?? '';
+  const slug = slugParam ? slugParam.split('/') : [];
+  const page = await getPage(slug);
+
+  if (!page) {
+    throw new HTTPError({ status: 404, message: 'Page not found' });
+  }
+
+  return {
+    frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+    relativePath: getRelativePath(page),
+    originalPath: getOriginalPath(page),
+  };
+});

package/src/server/api/search.ts

@@ -0,0 +1,118 @@
+import MiniSearch from 'minisearch';
+import { defineHandler } from 'nitro';
+import type { OpenAPIV3 } from 'openapi-types';
+import { getSpecSlug } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { getPages, extractFrontmatter } from '@/lib/source';
+
+interface SearchDocument {
+  id: string;
+  url: string;
+  title: string;
+  content: string;
+  type: 'page' | 'api';
+}
+
+let searchIndex: MiniSearch<SearchDocument> | null = null;
+let cachedDocs: SearchDocument[] | null = null;
+
+function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
+  const index = new MiniSearch<SearchDocument>({
+    fields: ['title', 'content'],
+    storeFields: ['url', 'title', 'type'],
+    searchOptions: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true
+    }
+  });
+  index.addAll(docs);
+  return index;
+}
+
+async function scanContent(): Promise<SearchDocument[]> {
+  const pages = await getPages();
+  return pages.map(p => {
+    const fm = extractFrontmatter(p);
+    return {
+      id: p.url,
+      url: p.url,
+      title: fm.title,
+      content: fm.description ?? '',
+      type: 'page' as const
+    };
+  });
+}
+
+async function buildApiDocs(): Promise<SearchDocument[]> {
+  const config = loadConfig();
+  if (!config.api?.length) return [];
+
+  const docs: SearchDocument[] = [];
+  const specs = await loadApiSpecs(config.api);
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec);
+    const paths = spec.document.paths ?? {};
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue;
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+        if (!op?.operationId) continue;
+        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`;
+        docs.push({
+          id: url,
+          url,
+          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
+          content: op.description ?? '',
+          type: 'api'
+        });
+      }
+    }
+  }
+
+  return docs;
+}
+
+async function getDocs(): Promise<SearchDocument[]> {
+  if (cachedDocs) return cachedDocs;
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(),
+    buildApiDocs()
+  ]);
+  cachedDocs = [...contentDocs, ...apiDocs];
+  return cachedDocs;
+}
+
+async function getIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (searchIndex) return searchIndex;
+  const docs = await getDocs();
+  searchIndex = createIndex(docs);
+  return searchIndex;
+}
+
+export default defineHandler(async event => {
+  const query = event.url.searchParams.get('query') ?? '';
+  const index = await getIndex();
+
+  if (!query) {
+    const docs = await getDocs();
+    return docs
+      .filter(d => d.type === 'page')
+      .slice(0, 8)
+      .map(d => ({
+        id: d.id,
+        url: d.url,
+        type: d.type,
+        content: d.title
+      }));
+  }
+
+  return index.search(query).map(r => ({
+    id: r.id,
+    url: r.url,
+    type: r.type,
+    content: r.title
+  }));
+});