@raystack/chronicle 0.5.3 → 0.6.0

package/src/types/config.ts

@@ -1,3 +1,4 @@
+import uniqBy from 'lodash/uniqBy.js'
 import { z } from 'zod'
 
 const logoSchema = z.object({
@@ -45,19 +46,11 @@ const apiSchema = z.object({
   name: z.string(),
   spec: z.string(),
   basePath: z.string(),
+  icon: z.string().optional(),
   server: apiServerSchema,
   auth: apiAuthSchema.optional(),
 })
 
-const footerSchema = z.object({
-  copyright: z.string().optional(),
-  links: z.array(navLinkSchema).optional(),
-})
-
-const llmsSchema = z.object({
-  enabled: z.boolean().optional(),
-})
-
 const googleAnalyticsSchema = z.object({
   measurementId: z.string(),
 })
@@ -70,26 +63,158 @@ const analyticsSchema = z.object({
 const telemetrySchema = z.object({
   enabled: z.boolean().optional(),
   serviceName: z.string().optional(),
+  port: z.number().int().min(1).max(65535).default(9090),
 })
 
-export const chronicleConfigSchema = z.object({
+const siteSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
-  url: z.string().optional(),
-  content: z.string().optional(),
-  preset: z.string().optional(),
-  logo: logoSchema.optional(),
-  theme: themeSchema.optional(),
-  navigation: navigationSchema.optional(),
-  search: searchSchema.optional(),
-  footer: footerSchema.optional(),
+})
+
+const DIR_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+const dirNameSchema = z
+  .string()
+  .min(1)
+  .refine((s) => DIR_NAME_PATTERN.test(s) && s !== '.' && s !== '..', {
+    message:
+      'dir must start with a letter or digit and contain only letters, digits, ".", "_", or "-"',
+  })
+
+const contentEntrySchema = z.object({
+  dir: dirNameSchema,
+  label: z.string().min(1),
+  icon: z.string().optional(),
+})
+
+// Variants map to Apsara Badge color prop.
+// https://apsara.raystack.org/docs/components/badge
+const badgeVariantSchema = z.enum([
+  'accent',
+  'warning',
+  'danger',
+  'success',
+  'neutral',
+  'gradient',
+])
+
+const badgeSchema = z.object({
+  label: z.string().min(1),
+  variant: badgeVariantSchema.default('accent'),
+})
+
+const latestSchema = z.object({
+  label: z.string().min(1),
+  landing: z.boolean().optional(),
+})
+
+const versionSchema = z.object({
+  dir: dirNameSchema,
+  label: z.string().min(1),
+  badge: badgeSchema.optional(),
+  landing: z.boolean().optional(),
+  content: z.array(contentEntrySchema).min(1),
   api: z.array(apiSchema).optional(),
-  llms: llmsSchema.optional(),
-  analytics: analyticsSchema.optional(),
-  telemetry: telemetrySchema.optional(),
 })
 
+const allUnique = <T>(items: T[], key: (item: T) => string): boolean =>
+  uniqBy(items, key).length === items.length
+
+const RESERVED_ROUTE_SEGMENTS = [
+  'api',
+  'apis',
+  'og',
+  'llms.txt',
+  'robots.txt',
+  'sitemap.xml',
+] as const
+
+export const chronicleConfigSchema = z
+  .object({
+    site: siteSchema,
+    url: z.string().optional(),
+    content: z.array(contentEntrySchema).min(1),
+    latest: latestSchema.optional(),
+    versions: z.array(versionSchema).optional(),
+    preset: z.string().optional(),
+    logo: logoSchema.optional(),
+    theme: themeSchema.optional(),
+    navigation: navigationSchema.optional(),
+    search: searchSchema.optional(),
+    api: z.array(apiSchema).optional(),
+    analytics: analyticsSchema.optional(),
+    telemetry: telemetrySchema.optional(),
+  })
+  .strict()
+  .refine((cfg) => allUnique(cfg.content, (c) => c.dir), {
+    message: 'content[].dir must be unique',
+    path: ['content'],
+  })
+  .refine((cfg) => !cfg.versions || allUnique(cfg.versions, (v) => v.dir), {
+    message: 'versions[].dir must be unique',
+    path: ['versions'],
+  })
+  .refine(
+    (cfg) =>
+      !cfg.versions ||
+      cfg.versions.every((v) => allUnique(v.content, (c) => c.dir)),
+    {
+      message: 'versions[].content[].dir must be unique within each version',
+      path: ['versions'],
+    },
+  )
+  .refine((cfg) => !cfg.versions || cfg.versions.length === 0 || !!cfg.latest, {
+    message: 'latest is required when versions are declared',
+    path: ['latest'],
+  })
+  .refine(
+    (cfg) => {
+      if (!cfg.versions) return true
+      const contentDirs = new Set(cfg.content.map((c) => c.dir))
+      return !cfg.versions.some((v) => contentDirs.has(v.dir))
+    },
+    {
+      message:
+        'versions[].dir must not overlap with content[].dir — the URL segment would be shadowed',
+      path: ['versions'],
+    },
+  )
+  .superRefine((cfg, ctx) => {
+    const reserved = new Set<string>(RESERVED_ROUTE_SEGMENTS)
+    const message = `dir must not be a reserved route segment: ${RESERVED_ROUTE_SEGMENTS.join(', ')}`
+
+    cfg.content.forEach((c, i) => {
+      if (reserved.has(c.dir)) {
+        ctx.addIssue({ code: 'custom', message, path: ['content', i, 'dir'] })
+      }
+    })
+    cfg.versions?.forEach((v, vi) => {
+      if (reserved.has(v.dir)) {
+        ctx.addIssue({
+          code: 'custom',
+          message,
+          path: ['versions', vi, 'dir'],
+        })
+      }
+      v.content.forEach((c, ci) => {
+        if (reserved.has(c.dir)) {
+          ctx.addIssue({
+            code: 'custom',
+            message,
+            path: ['versions', vi, 'content', ci, 'dir'],
+          })
+        }
+      })
+    })
+  })
+
 export type ChronicleConfig = z.infer<typeof chronicleConfigSchema>
+export type SiteConfig = z.infer<typeof siteSchema>
+export type ContentEntry = z.infer<typeof contentEntrySchema>
+export type BadgeConfig = z.infer<typeof badgeSchema>
+export type BadgeVariant = z.infer<typeof badgeVariantSchema>
+export type LatestConfig = z.infer<typeof latestSchema>
+export type VersionConfig = z.infer<typeof versionSchema>
 export type LogoConfig = z.infer<typeof logoSchema>
 export type ThemeConfig = z.infer<typeof themeSchema>
 export type NavigationConfig = z.infer<typeof navigationSchema>
@@ -99,8 +224,6 @@ export type SearchConfig = z.infer<typeof searchSchema>
 export type ApiConfig = z.infer<typeof apiSchema>
 export type ApiServerConfig = z.infer<typeof apiServerSchema>
 export type ApiAuthConfig = z.infer<typeof apiAuthSchema>
-export type FooterConfig = z.infer<typeof footerSchema>
-export type LlmsConfig = z.infer<typeof llmsSchema>
 export type AnalyticsConfig = z.infer<typeof analyticsSchema>
 export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>
 export type TelemetryConfig = z.infer<typeof telemetrySchema>

package/src/types/content.ts

@@ -12,7 +12,17 @@ export interface Frontmatter {
   lastModified?: string
 }
 
-export interface Page {
+export interface PageNavLink {
+  url: string
+  title: string
+}
+
+export interface PageNav {
+  prev: PageNavLink | null
+  next: PageNavLink | null
+}
+
+export interface Page extends PageNav {
   slug: string[]
   frontmatter: Frontmatter
   content: ReactNode

package/src/types/theme.ts

@@ -7,6 +7,7 @@ export interface ThemeLayoutProps {
   children: ReactNode
   config: ChronicleConfig
   tree: Root
+  hideSidebar?: boolean
   classNames?: { layout?: string; body?: string; sidebar?: string; content?: string }
 }
 

package/src/components/ui/footer.module.css

@@ -1,27 +0,0 @@
-.footer {
-  border-top: 1px solid var(--rs-color-border-base-primary);
-  padding: var(--rs-space-5) var(--rs-space-7);
-}
-
-.container {
-  max-width: 1200px;
-  margin: 0 auto;
-  width: 100%;
-}
-
-.copyright {
-  color: var(--rs-color-foreground-base-secondary);
-}
-
-.links {
-  flex-wrap: wrap;
-}
-
-.link {
-  color: var(--rs-color-foreground-base-secondary);
-  font-size: 14px;
-}
-
-.link:hover {
-  color: var(--rs-color-foreground-base-primary);
-}

package/src/components/ui/footer.tsx

@@ -1,30 +0,0 @@
-import { Flex, Link, Text } from "@raystack/apsara";
-import type { FooterConfig } from "@/types";
-import styles from "./footer.module.css";
-
-interface FooterProps {
-  config?: FooterConfig;
-}
-
-export function Footer({ config }: FooterProps) {
-  return (
-    <footer className={styles.footer}>
-      <Flex align="center" justify="between" className={styles.container}>
-        {config?.copyright && (
-          <Text size={2} className={styles.copyright}>
-            {config.copyright}
-          </Text>
-        )}
-        {config?.links && config.links.length > 0 && (
-          <Flex gap="medium" className={styles.links}>
-            {config.links.map((link) => (
-              <Link key={link.href} href={link.href} className={styles.link}>
-                {link.label}
-              </Link>
-            ))}
-          </Flex>
-        )}
-      </Flex>
-    </footer>
-  );
-}

package/src/server/api/metrics.ts

@@ -1,23 +0,0 @@
-import type { IncomingMessage, ServerResponse } from 'node:http'
-import { defineHandler } from 'nitro'
-import { getExporter } from '../telemetry'
-
-export default defineHandler(async () => {
-  const exporter = getExporter()
-  if (!exporter) {
-    return new Response('Telemetry not enabled', { status: 404 })
-  }
-
-  const metricsString = await new Promise<string>((resolve) => {
-    const mockRes = {
-      setHeader: () => mockRes,
-      end: (data: string) => resolve(data),
-    } as unknown as ServerResponse
-
-    exporter.getMetricsRequestHandler({} as unknown as IncomingMessage, mockRes)
-  })
-
-  return new Response(metricsString, {
-    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-  })
-})

package/src/server/api/page/index.ts

@@ -1 +0,0 @@
-export { default } from './[...slug]';

package/src/server/telemetry.ts

@@ -1,49 +0,0 @@
-import type { Counter, Histogram } from '@opentelemetry/api'
-import sdkMetrics from '@opentelemetry/sdk-metrics'
-import prometheusExporter from '@opentelemetry/exporter-prometheus'
-import resources from '@opentelemetry/resources'
-import semconv from '@opentelemetry/semantic-conventions'
-import type { ChronicleConfig } from '@/types/config'
-
-const { MeterProvider } = sdkMetrics
-const { PrometheusExporter } = prometheusExporter
-const { resourceFromAttributes } = resources
-const { ATTR_SERVICE_NAME } = semconv
-
-let exporter: PrometheusExporter
-let requestCounter: Counter
-let requestDuration: Histogram
-let ssrRenderDuration: Histogram
-
-export function initTelemetry(config: ChronicleConfig) {
-  const resource = resourceFromAttributes({
-    [ATTR_SERVICE_NAME]: config.telemetry?.serviceName ?? 'chronicle',
-  })
-
-  exporter = new PrometheusExporter({ preventServerStart: true })
-  const provider = new MeterProvider({ resource, readers: [exporter] })
-  const meter = provider.getMeter('chronicle')
-
-  requestCounter = meter.createCounter('http_server_request_total', {
-    description: 'Total HTTP requests',
-  })
-  requestDuration = meter.createHistogram('http_server_request_duration_ms', {
-    description: 'HTTP request duration in ms',
-  })
-  ssrRenderDuration = meter.createHistogram('http_server_ssr_render_duration_ms', {
-    description: 'SSR render duration in ms',
-  })
-}
-
-export function getExporter() {
-  return exporter
-}
-
-export function recordRequest(method: string, route: string, status: number, durationMs: number) {
-  requestCounter?.add(1, { method, route, status })
-  requestDuration?.record(durationMs, { method, route, status })
-}
-
-export function recordSSRRender(route: string, status: number, durationMs: number) {
-  ssrRenderDuration?.record(durationMs, { route, status })
-}