@nbtca/docs

Typed GitHub client for the NBTCA documents repository. It lists Markdown documents, reads raw content, caches successful responses, and falls back to stale data after transient failures. Rendering remains the consumer's responsibility.

Install

npm install @nbtca/docs

Usage

import { createDocsClient } from '@nbtca/docs';

const docs = createDocsClient();

const sections = await docs.listDir();
const documents = await docs.listAll();
const markdown = await docs.getFile('repair/guide.md');
const page = await docs.getDocument('repair/index.md');
const matches = await docs.search('repair', { pathPrefix: 'repair' });

API

createDocsClient(options?)

Option	Default	Description
owner	'nbtca'	GitHub owner
repo	'documents'	Repository name
branch	'main'	Branch name or ref
token	GITHUB_TOKEN or GH_TOKEN	GitHub token
cacheTtlMs.dir	300000	Directory and tree cache TTL
cacheTtlMs.file	600000	File cache TTL

docs.listDir(path?)

Lists directories and Markdown files at a repository-relative path. The root path is used when path is omitted.

docs.getFile(path)

Returns raw file content.

docs.listAll()

Lists every Markdown file through GitHub's recursive tree API.

docs.listSections()

Returns top-level content sections with document counts and optional index paths.

docs.getDocument(path)

Returns content with its route, section, title, summary, and semantic component attributes. Component metadata covers PageHero, FactStrip, LinkCard, Split, TimelineEntry, and Figure without imposing a renderer.

docs.search(query, options?)

Searches paths, titles, summaries, Markdown text, and semantic component attributes. Results are ranked and include excerpts. Use pathPrefix to scope a search and limit to cap results.

docs.clear()

Clears all cached values and in-flight request bookkeeping.

DocsFetchError

Thrown when a request fails without usable stale data. Exposes path and HTTP status.

License

MIT