Content types

import type {
  ComarkContent,
  ContentOptions,
  ContentHooks,
  ContentFile,
  ContentListFile,
  ContentFileMeta,
  Manifest,
  NavigationItem,
  Source,
  Database,
  RelationalDatabase,
  CacheArtifact,
  CacheOptions,
  CacheStrategy,
  CacheArtifactOptions,
  Cache,
  SearchOptions,
  SearchResult,
  Logger,
  OnErrorMode,
} from 'comark-content'

interface ContentFile<TData = Record<string, any>, TMeta = Record<string, unknown>> {
  path: string                      // '/posts/hello'
  data: TData                       // the file's frontmatter / parsed data
  meta: TMeta & ContentFileMeta         // kind, type, key, source, extension, stem, partial (+ plugin fields)
  nodes: MarkdownDocument['nodes']      // the parsed AST
}

interface ContentFileMeta {
  kind: 'document' | 'media'        // whether it's a document or a media file
  type: string                      // mime type, e.g. 'text/markdown'
  key: string                       // 'default/posts/hello.md'
  source: string                    // the source the file belongs to
  extension: string                 // '.md' (with the leading dot)
  stem: string                      // 'posts/hello' (path without extension)
  partial: boolean                 // true when only frontmatter was parsed (body skipped)
}

type ContentListFile<TData = Record<string, any>> = Omit<ContentFile<TData>, 'nodes'>

interface Manifest {
  sources: string[]                          // source names loaded into the index
  items: Record<string, ContentListFile>         // every entry, keyed by path
  time: number                               // build timestamp (ms)
  schemas?: Record<string, JsonSchema>       // per-source `data` JSON Schema
}

interface NavigationItem {
  title: string
  description?: string
  path: string
  stem?: string
  children?: NavigationItem[]
  page?: false
  [key: string]: unknown
}

interface Source {
  prefix?: string
  keys: () => Promise<string[]> | string[]
  getItem: (key: string) => Promise<string> | string
  getItemRaw: (key: string) => Promise<unknown> | unknown
  watch?: (cb: (event: 'update' | 'remove', key: string) => void) => () => void
}

interface FSSourceOptions extends Omit<FSStorageOptions, 'base'> {
  prefix?: string
  exclude?: string[]
  schema?: JsonSchema
}

interface GithubSource extends Omit<GithubOptions, 'dir'> {
  path?: string
  prefix?: string
  exclude?: string[]
  schema?: JsonSchema
}

interface Database {
  upsert: (source: string, data: ContentFile) => void | Promise<void>
  delete: (source: string, key: string) => void | Promise<void>
  get: (source: string, key: string) => ContentFile | Promise<ContentFile>
  list: (source: string) => ContentFile[] | Promise<ContentFile[]>
  clear: (source: string) => void | Promise<void>
}

interface RelationalDatabase extends Database {
  first: <T>(query: string, params?: unknown[]) => Promise<T | undefined>
  all: <T>(query: string, params?: unknown[]) => Promise<T[]>
  execute: <T>(query: string, params?: unknown[]) => Promise<T>
}

interface CacheArtifact {
  name: string                      // 'manifest' or a source name
  data: string                      // JSON, optionally gzipped + base64
  checksum: string                  // SHA-256 of `data`
  size: number                      // bytes
}

interface CacheOptions {
  driver?: Driver                   // unstorage driver; defaults to in-memory
  ttl?: number                      // ms before an entry is stale; omit to never expire
  strategy?: CacheStrategy          // how a stale entry is served; defaults to 'swr'
  loadManifest?: () => Promise<CacheArtifact | null | undefined> | CacheArtifact | null | undefined
  loadSnapshot?: (source: string) => Promise<CacheArtifact | null | undefined> | CacheArtifact | null | undefined
}

type CacheStrategy = 'swr' | 'none'

interface CacheArtifactOptions {
  compress?: boolean                // gzip + base64 the payload; defaults to true
  fresh?: boolean                   // re-read the source (true) or build from cache (false)
}

interface Cache {
  get<T = ContentFile>(key: string): Promise<T | null>
  set<T = ContentFile>(key: string, value: T): Promise<void>
  keys(prefix?: string): Promise<string[]>
  refresh(source: string): Promise<ContentFile[]>       // re-read a source, reconcile the manifest
  invalidate(key: string): Promise<void>            // drop one entry
  expire(key: string): Promise<void>                // mark one entry stale (swr refreshes on next read)
  manifest(opts?: CacheArtifactOptions): Promise<CacheArtifact | null>   // fresh: true (default) inits first; fresh: false reads the persisted index
  snapshot(source: string, opts?: CacheArtifactOptions): Promise<CacheArtifact | null>
}

interface ContentHooks {
  'watch:file:update': (sourceName: string, key: string, file: ContentFile) => void
  'watch:file:remove': (sourceName: string, key: string) => void
  'file:parsed': (ctx: FileParsedContext) => void | Promise<void>
  'typegen:field': (ctx: TypegenFieldContext) => void | Promise<void>
  'file:upsert': (sourceName: string, key: string, file: ContentFile) => void
  'file:remove': (sourceName: string, key: string) => void
  'file:bulk:load': (sourceName: string, items: ContentFile[]) => void
}

interface SearchOptions {
  limit?: number
  fields?: ('title' | 'content')[]
  minTermLength?: number
  weights?: { title?: number; content?: number; heading?: boolean }
  snippet?: { columns?: ('title' | 'content')[]; around?: number; tag?: string }
}

interface SearchResult {
  source: string
  id: string
  title: string
  titles: string[]
  level: number
  content: string
  rank: number
  snippets?: { title?: string; content?: string }
}

interface ParserContext {
  filepath: string
  extension: string
  partial: boolean
  read: () => string | Promise<string>
}

type ParserResult = {
  kind?: 'media' | 'document'
  type?: string
  data?: ContentFile['data']
  meta?: Record<string, any>
  nodes?: ContentFile['nodes']
  partial?: boolean
}

type Parser = (ctx: ParserContext) => ParserResult | null | Promise<ParserResult | null>

interface ContentOptions {
  source?: Source
  sources?: Record<string, Source>
  cache?: CacheOptions | false
  plugins?: ReadonlyArray<ContentPlugin<any>>
  markdown?: ParserOptions
  basePath?: string          // default '/api/content'
  baseURL?: string
  logger?: Logger | false    // default console-backed; false silences output
  onError?: OnErrorMode      // default 'warn'
}

interface Logger {
  debug: (...args: unknown[]) => void
  info: (...args: unknown[]) => void
  warn: (...args: unknown[]) => void
  error: (...args: unknown[]) => void
}

type OnErrorMode =
  | 'throw'   // surface the error and abort
  | 'warn'    // log via the logger and drop the file (default)
  | 'ignore'  // silently drop the file

interface ComarkContent {
  options: ContentOptions
  status: 'created' | 'initializing' | 'initialized-partial' | 'initialized-full'
  cache: Cache
  logger: Logger
  hooks: Hookable<ContentHooks>
  init(opts?: { partial?: boolean; ignoreCache?: boolean }): Promise<void>
  loadSnapshot(sourceName: string): Promise<void>
  list: ContentList
  stat(key: string): ContentListFile | undefined
  getSource(name: string): Source | undefined
  get: ComarkGet
  navigation(sources?: string[]): Promise<NavigationItem[]>
  readonly manifest: Manifest
  handler(request: Request): Promise<Response>
  update(sourceName: string, file: ContentFile): Promise<void>
  remove(sourceName: string, key: string): Promise<void>
  watch(): Promise<() => Promise<void>>
}

interface ContentList {
  <K extends keyof ContentRegistry>(sources: K[]): Promise<ContentListFile<SourceData<K>>[]>
  <Data = RegistryData>(sources?: string[]): Promise<ContentListFile<Data>[]>
}