@blaaiz/docs-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1182 @@
+import { A as AiConfig, T as ThemeConfig, D as DocsConfig, N as Navigation } from './navigation-CGqFIPlP.cjs';
+export { a as AI_PROVIDER_MODELS, b as AI_PROVIDER_NAMES, c as AiConfigError, d as AiProviderModels, e as AiProviderName, f as AuthConfig, g as DocPage, h as DocsConfigError, F as FeaturesConfig, G as GoogleProviderConfig, i as NavGroup, j as NavItem, k as NavMethod, l as NavPage, m as NavTab, O as OpenApiPage, P as ProxyConfig, R as ResolvedAiConfig, S as SecretProviderConfig, n as SeoConfig, o as ThemeLogo, p as ThemePalette, W as WorkspaceAuthConfig, q as WorkspaceProviders, r as defineDocsConfig, s as resolveAiConfig, v as validateDocsConfig } from './navigation-CGqFIPlP.cjs';
+import { b as OpenApiDocument, O as OpenApiInfo, a as OpenApiServer } from './openapi-types-CJ6p5Cux.cjs';
+export { c as OpenApiComponents, d as OpenApiOperation, e as OpenApiPathItem, f as OpenApiTag } from './openapi-types-CJ6p5Cux.cjs';
+
+/**
+ * The try-it proxy.
+ *
+ * The interactive playground cannot call an API directly from the browser
+ * (cross-origin). Instead it posts an envelope to a same-origin route, which
+ * forwards the request server-side. This module builds that forwarder in a
+ * framework-agnostic way, using the Web `Request`/`Response` types so it drops
+ * into a Next.js route handler, an edge function, or any Fetch-based runtime.
+ *
+ * Security model: the proxy forwards the caller's own credentials and injects
+ * none of its own. It only reaches an origin the site has allow-listed, and it
+ * refuses private, loopback, and link-local hosts so it cannot be turned into
+ * an SSRF relay. Every forward is rate-limited per client IP, so a public
+ * playground cannot be used to hammer the site's own API.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A minimal fetch signature, so a test can inject a fake upstream.
+ *
+ * @public
+ */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Options for {@link createTryItProxy}.
+ *
+ * @public
+ */
+interface CreateTryItProxyOptions {
+    /** Exhaustive list of upstream origins the proxy may forward to. */
+    readonly allowedOrigins: readonly string[];
+    /**
+     * Forwards per minute per client IP. Default 60 — pass
+     * `config.proxy.rateLimitPerMinute` to let the site set it.
+     */
+    readonly rateLimitPerMinute?: number;
+    /** Fetch implementation. Defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /** Clock for the rate limiter, for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Thrown when a forward target is missing, malformed, blocked, or not allow-listed.
+ *
+ * @public
+ */
+declare class ProxyTargetError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a forward target against the allow-list and the host block rules.
+ *
+ * @param target - the requested upstream URL
+ * @param allowedOrigins - allow-listed origins
+ * @returns the parsed, approved URL
+ * @throws {@link ProxyTargetError} when the target is invalid, blocked, or not allow-listed
+ * @public
+ */
+declare function assertAllowedTarget(target: string, allowedOrigins: readonly string[]): URL;
+/**
+ * The request envelope the playground posts to the proxy route.
+ *
+ * @public
+ */
+interface TryItEnvelope {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string | null;
+}
+/**
+ * Build a same-origin try-it proxy handler.
+ *
+ * Every request is rate-limited per client IP before anything is forwarded. A
+ * caller over the limit gets `429` with a `Retry-After` header and the same JSON
+ * body the Ask AI route returns.
+ *
+ * @param options - the allow-list, the rate limit, and an optional fetch implementation
+ * @returns a handler mapping an incoming `Request` to a forwarded `Response`
+ * @public
+ */
+declare function createTryItProxy(options: CreateTryItProxyOptions): (request: Request) => Promise<Response>;
+/**
+ * A set of HTTP method handlers for a try-it proxy route, ready to re-export
+ * from a framework route file (e.g. a Next.js `route.ts`).
+ *
+ * @public
+ */
+interface TryItProxyRoute {
+    readonly GET: (request: Request) => Promise<Response>;
+    readonly POST: (request: Request) => Promise<Response>;
+    readonly PUT: (request: Request) => Promise<Response>;
+    readonly PATCH: (request: Request) => Promise<Response>;
+    readonly DELETE: (request: Request) => Promise<Response>;
+    readonly OPTIONS: () => Response;
+}
+/**
+ * Build a drop-in try-it proxy route that speaks the query-parameter protocol
+ * API playgrounds use: the target URL arrives in a query parameter, with the
+ * caller's own method, headers, and body.
+ *
+ * Two parameter names are accepted, because two playgrounds disagree. `url` is
+ * preferred and is the name {@link unwrapProxyTarget} decodes for display;
+ * `scalar_url` is what the Scalar playground sends. Passing both uses `url`.
+ *
+ * The route validates the target with {@link assertAllowedTarget} (allow-list +
+ * SSRF guard), rate-limits per client IP, strips inbound infra headers, and
+ * forwards server-side. Export its handlers directly from a route file:
+ *
+ * @example
+ * ```ts
+ * export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = createTryItProxyRoute({
+ *   allowedOrigins: config.proxy.allowedOrigins,
+ *   rateLimitPerMinute: config.proxy.rateLimitPerMinute,
+ * });
+ * ```
+ *
+ * @param options - the allow-list, the rate limit, and an optional fetch implementation
+ * @returns the method handlers for the route
+ * @public
+ */
+declare function createTryItProxyRoute(options: CreateTryItProxyOptions): TryItProxyRoute;
+/**
+ * Recover the real target URL from a try-it proxy URL, for display.
+ *
+ * The playground fetches through the same-origin proxy, so a response's URL is
+ * the proxy URL (`.../api/proxy?url=<encoded target>&...`). This returns the
+ * decoded target so the response panel shows the real endpoint, not the proxy.
+ * Any URL that is not a proxy URL is returned unchanged.
+ *
+ * It reads the same two parameter names {@link createTryItProxyRoute} accepts,
+ * `url` first and `scalar_url` second, so a Scalar-shaped proxy URL is decoded
+ * too.
+ *
+ * @param url - a proxy URL, or any URL
+ * @returns the decoded target URL, or the input unchanged
+ * @public
+ */
+declare function unwrapProxyTarget(url: string): string;
+
+/**
+ * The provider seam.
+ *
+ * Every provider is reduced to one shape: an async generator of three event
+ * kinds — text, done, error. Nothing above this layer knows whether Anthropic
+ * or OpenAI answered, which is what lets the route treat them as equals and
+ * lets a test script a stream without a network.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * One turn of the conversation. Only the two roles a reader can produce: the
+ * system prompt is built by the framework and travels outside `messages`.
+ */
+interface AiMessage {
+    readonly role: 'user' | 'assistant';
+    readonly content: string;
+}
+
+/**
+ * Lightweight client-shippable search.
+ *
+ * The framework builds a compact term index from a site's pages and scores
+ * queries against it with BM25: term frequency, inverse document frequency,
+ * and document-length normalization. IDF is what keeps ranking honest — a
+ * word that appears in every page ("how", "the", "a") carries almost no
+ * weight, so a query like "how do I deploy" is decided by "deploy", not by
+ * its stopwords. A light, symmetric stemmer is applied to both the index and
+ * the query, so "wallets" finds "wallet" and "authentication" finds
+ * "authenticate".
+ *
+ * It is intentionally simple — good for the hundreds-to-low-thousands of
+ * pages a docs site has — and ships to the browser as plain JSON, so search
+ * needs no server round-trip. A site provides the input UI.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A page to index.
+ *
+ * @public
+ */
+interface SearchDocument {
+    readonly id: string;
+    readonly title: string;
+    readonly path: string;
+    /** Optional grouping label, e.g. the section or tab name. */
+    readonly section?: string;
+    /** Free text to index (body, description). Not retained in the index. */
+    readonly body?: string;
+}
+/**
+ * One indexed page. Part of the serialized {@link SearchIndex} wire format.
+ *
+ * @public
+ */
+interface IndexedDocument {
+    readonly id: string;
+    readonly title: string;
+    readonly path: string;
+    readonly section?: string;
+    /** Stemmed term → occurrence count across title, section, and body. */
+    readonly terms: Readonly<Record<string, number>>;
+    /** Total token count, for length normalization. */
+    readonly length: number;
+    /** The title's stemmed terms, precomputed for the per-query title bonus. */
+    readonly titleTerms: readonly string[];
+    /** The section label's stemmed terms, when a section is set. */
+    readonly sectionTerms?: readonly string[];
+}
+/**
+ * A built, serializable search index.
+ *
+ * @public
+ */
+interface SearchIndex {
+    readonly documents: readonly IndexedDocument[];
+    /** Stemmed term → number of documents containing it. */
+    readonly documentFrequency: Readonly<Record<string, number>>;
+    /** Every indexed term, sorted, for binary-searched prefix matching. */
+    readonly vocabulary: readonly string[];
+    /** Mean token count per document, for length normalization. */
+    readonly averageLength: number;
+}
+/**
+ * A ranked search hit.
+ *
+ * @public
+ */
+interface SearchResult {
+    readonly id: string;
+    readonly title: string;
+    readonly path: string;
+    readonly section?: string;
+    readonly score: number;
+}
+/**
+ * Build a search index from a list of documents.
+ *
+ * @public
+ */
+declare function buildSearchIndex(documents: readonly SearchDocument[]): SearchIndex;
+/**
+ * Search an index with BM25 scoring. Rare words dominate common ones, term
+ * repetition saturates, long pages get no volume advantage, and a term that
+ * also appears in the title (as a whole token, never a substring) or the
+ * section label earns a bonus. A stemmed term that matches nothing exactly
+ * falls back to prefix matching at reduced weight — including the title and
+ * section bonuses, so a half-typed word still ranks the page it names first.
+ * Ties break deterministically by title, then path, independent of locale.
+ *
+ * Returns up to `limit` results, best first.
+ *
+ * @public
+ */
+declare function searchIndex(index: SearchIndex, query: string, limit?: number): SearchResult[];
+
+/**
+ * The Ask AI route.
+ *
+ * One handler, framework-agnostic, built on the Web `Request`/`Response` types
+ * so it drops into a Next.js route file, an edge function, or any Fetch-based
+ * runtime. It runs the whole question pipeline: validate the body, rate-limit
+ * the caller, retrieve the grounding pages, build the prompt, stream the
+ * provider, and re-emit a provider-agnostic SSE stream to the browser.
+ *
+ * Two deliberate choices:
+ *
+ * - **Configuration is resolved eagerly.** {@link createAskAiRoute} validates
+ *   the `ai` block when the route is built, so a typo in `docs.config.ts` fails
+ *   the build. Deferring it to the first request would turn a site's typo into a
+ *   reader's error message.
+ * - **The API key is read lazily, per request.** An edge runtime binds its
+ *   environment per invocation, not at module load, so the key is looked up when
+ *   it is needed. It is never logged; a missing key is reported by env var name.
+ *
+ * The browser protocol is three event names — `sources`, `text`, `done` — with
+ * `error` replacing the tail of the stream on failure. See
+ * {@link createAskAiRoute} for the exact payloads.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Where the route gets the site's pages: the array itself, or a loader for a
+ * site that builds it at runtime. Either way it is read once and treated as
+ * immutable build-time content.
+ *
+ * @public
+ */
+type AskAiDocumentsSource = readonly SearchDocument[] | (() => Promise<readonly SearchDocument[]>);
+/**
+ * Options for {@link createAskAiRoute}.
+ *
+ * @public
+ */
+interface AskAiRouteOptions {
+    /** The site's raw `ai` block. Validated when the route is built. */
+    readonly config: AiConfig;
+    /** Display name used in the system prompt, normally `theme.name`. */
+    readonly siteName: string;
+    /**
+     * The API key value. Supply it only when the server resolves the key itself;
+     * otherwise leave it out and the route reads `ai.apiKeyEnv` per request.
+     */
+    readonly apiKey?: string;
+    /** Reads an environment variable. Defaults to `process.env`, looked up per request. */
+    readonly env?: (name: string) => string | undefined;
+    /** The site's pages, for retrieval. */
+    readonly documents: AskAiDocumentsSource;
+    /** Loads a page's Markdown by its URL. Returns `null` when there is none. */
+    readonly loadPageMarkdown: (url: string) => Promise<string | null>;
+    /** Fetch implementation passed to the provider. Defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /** Clock for the rate limiter, for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Upper bound on one answer, in tokens. Default 2048. */
+    readonly maxOutputTokens?: number;
+}
+/**
+ * A citation sent to the browser before the answer streams.
+ *
+ * @public
+ */
+interface AskAiSource {
+    readonly url: string;
+    readonly title: string;
+}
+/**
+ * The Ask AI route's handlers, ready to re-export from a framework route file.
+ *
+ * @public
+ */
+interface AskAiRoute {
+    readonly POST: (request: Request) => Promise<Response>;
+}
+/**
+ * Build the Ask AI route.
+ *
+ * The route answers `POST` with `{ "messages": [{ "role": "user", "content": "…" }] }`
+ * and streams `text/event-stream`:
+ *
+ * | Event     | Payload                    | When                                  |
+ * | --------- | -------------------------- | ------------------------------------- |
+ * | `sources` | `[{ url, title }]`         | Once, first — the retrieved pages.    |
+ * | `text`    | `{ text }`                 | Per delta, appended in order.         |
+ * | `done`    | `{}`                       | Last event of a successful answer.    |
+ * | `error`   | `{ message }`              | Replaces the tail; one readable line. |
+ *
+ * Failures before the stream starts are plain JSON, not SSE: `400` for a bad
+ * body (the message names the offending field), `429` with `Retry-After` when
+ * the caller is over the limit, and `500` when the API key is not set on the
+ * server.
+ *
+ * @example
+ * ```ts
+ * // app/api/ask-ai/route.ts
+ * export const { POST } = createAskAiRoute({
+ *   config: docsConfig.ai!,
+ *   siteName: docsConfig.theme.name,
+ *   documents: searchDocuments,
+ *   loadPageMarkdown: readPageMarkdown,
+ * });
+ * ```
+ *
+ * @param options - the site's `ai` block, its pages, and the Markdown loader
+ * @returns the route's `POST` handler
+ * @throws {@link AiConfigError} when the `ai` block or the wiring is invalid
+ * @public
+ */
+declare function createAskAiRoute(options: AskAiRouteOptions): AskAiRoute;
+
+/**
+ * Theme → CSS.
+ *
+ * A site declares its palette in config; the framework turns it into CSS custom
+ * properties. This is the seam that lets each organization brand its docs
+ * without touching the framework: the values live in the site, the mapping
+ * lives here.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build the CSS that applies a site's theme colours. Inject the returned string
+ * into a `<style>` tag so it overrides the framework defaults.
+ *
+ * @param theme - the site's theme configuration
+ * @returns a CSS string (empty when no colours are declared)
+ * @public
+ */
+declare function buildThemeCss(theme: ThemeConfig): string;
+
+/**
+ * SEO metadata, derived from {@link DocsConfig}.
+ *
+ * The framework owns *how* metadata is shaped — the title template, the
+ * canonical URL, the Open Graph and Twitter cards, the robots policy — so every
+ * site gets correct, consistent tags from its config alone. A site owns only
+ * the facts: its public origin, its sharing image, its description.
+ *
+ * These functions return plain objects that are structurally assignable to
+ * Next's `Metadata` and `MetadataRoute.*` types, so the framework needs no
+ * dependency on `next`. A site uses them directly:
+ *
+ * ```ts
+ * export const metadata: Metadata = buildMetadata(config);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The subset of Next's `Metadata` the framework produces. Literal types are
+ * used where Next expects them (`openGraph.type`, `twitter.card`) so the result
+ * assigns to `Metadata` without a cast.
+ *
+ * @public
+ */
+interface DocsMetadata {
+    readonly metadataBase?: URL;
+    readonly title: string | {
+        readonly default: string;
+        readonly template: string;
+    };
+    readonly description?: string;
+    readonly keywords?: string[];
+    readonly alternates?: {
+        readonly canonical?: string;
+    };
+    /**
+     * The site icon, from {@link ThemeConfig.favicon}. Shaped as Next's `Icons`
+     * object so the result assigns to `Metadata` without a cast.
+     */
+    readonly icons?: {
+        readonly icon: string;
+    };
+    readonly robots?: {
+        readonly index: boolean;
+        readonly follow: boolean;
+    };
+    readonly openGraph?: {
+        readonly type: 'website';
+        readonly siteName: string;
+        readonly title: string;
+        readonly description?: string;
+        readonly url?: string;
+        readonly images?: {
+            readonly url: string;
+        }[];
+    };
+    readonly twitter?: {
+        readonly card: 'summary' | 'summary_large_image';
+        readonly title: string;
+        readonly description?: string;
+        readonly site?: string;
+        readonly images?: string[];
+    };
+}
+/**
+ * Per-page metadata inputs. Omit everything for the site-wide default (the home
+ * document): the title is then {@link ThemeConfig.name} verbatim and the
+ * template is exposed for inner pages.
+ *
+ * @public
+ */
+interface PageSeo {
+    /** The page title, before the template is applied. */
+    readonly title?: string;
+    /** The page description; falls back to {@link SeoConfig.description}. */
+    readonly description?: string;
+    /** The page path for the canonical URL, e.g. `/docs/guides/refunds`. */
+    readonly path?: string;
+    /** Override the sharing image for this page. */
+    readonly ogImage?: string;
+    /** Extra keywords for this page, merged with the site-wide set. */
+    readonly keywords?: readonly string[];
+    /** Keep this page out of the index while the rest stays indexable. */
+    readonly noindex?: boolean;
+}
+/**
+ * Build a page's (or the site's) metadata from config.
+ *
+ * Call it with no page for the root layout — you get the default title plus the
+ * template inner pages inherit. Call it with a {@link PageSeo} in a page's
+ * `generateMetadata` for that page's title, canonical URL, and cards.
+ *
+ * {@link ThemeConfig.favicon} becomes the `icons` field, so declaring the
+ * favicon in config is all a site does — no `<link rel="icon">` by hand.
+ *
+ * @param config - the site configuration
+ * @param page - the page's metadata inputs; omit for the site default
+ * @returns metadata assignable to Next's `Metadata`
+ * @public
+ */
+declare function buildMetadata(config: DocsConfig, page?: PageSeo): DocsMetadata;
+/**
+ * A robots policy, assignable to Next's `MetadataRoute.Robots`.
+ *
+ * @public
+ */
+interface DocsRobots {
+    readonly rules: {
+        readonly userAgent: string;
+        readonly allow?: string;
+        readonly disallow?: string | string[];
+    };
+    readonly sitemap?: string;
+    readonly host?: string;
+}
+/**
+ * Build the robots policy. A `noindex` (or auth-gated) site disallows crawling
+ * entirely; a public site allows everything except the sign-in and API routes,
+ * which carry no indexable content. Points crawlers at the sitemap when a
+ * `siteUrl` is set.
+ *
+ * @param config - the site configuration
+ * @returns robots rules for `app/robots.ts`
+ * @public
+ */
+declare function buildRobots(config: DocsConfig): DocsRobots;
+/**
+ * One sitemap entry a site supplies (typically from the page tree).
+ *
+ * @public
+ */
+interface SitemapEntry {
+    /** Site-relative path, e.g. `/docs/guides/refunds`. */
+    readonly path: string;
+    /** Last-modified date, if known. */
+    readonly lastModified?: Date | string;
+}
+/**
+ * How often a crawler should revisit a page. The values Google documents for
+ * `<changefreq>`.
+ *
+ * @public
+ */
+type SitemapChangeFrequency = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+/**
+ * A resolved sitemap row, assignable to Next's `MetadataRoute.Sitemap[number]`.
+ *
+ * @public
+ */
+interface DocsSitemapEntry {
+    readonly url: string;
+    readonly lastModified?: Date | string;
+    readonly changeFrequency: SitemapChangeFrequency;
+    readonly priority: number;
+}
+/**
+ * Overrides for {@link buildSitemap}. Every field is optional, and the defaults
+ * suit a documentation site that publishes continuously.
+ *
+ * @public
+ */
+interface BuildSitemapOptions {
+    /** Revisit hint for every row. Default `'weekly'`. */
+    readonly changeFrequency?: SitemapChangeFrequency;
+    /** Priority for every page except the home path. Default `0.7`. */
+    readonly priority?: number;
+    /** Priority for the home path (`/`). Default `1`. */
+    readonly homePriority?: number;
+}
+/**
+ * Build sitemap rows from the site's pages. The home path gets top priority;
+ * everything else a shade lower. Absolute URLs need a `siteUrl` in config;
+ * without one the paths are emitted relative, which most crawlers still accept.
+ *
+ * A site that publishes on a slower cycle, or that wants its guides to outrank
+ * its generated reference pages, overrides the defaults:
+ *
+ * @example
+ * ```ts
+ * buildSitemap(entries, config, { changeFrequency: 'monthly', priority: 0.5 });
+ * ```
+ *
+ * @param entries - the site's page paths (and optional modified dates)
+ * @param config - the site configuration, for the origin
+ * @param options - override the revisit hint and the priorities
+ * @returns sitemap rows for `app/sitemap.ts`
+ * @public
+ */
+declare function buildSitemap(entries: readonly SitemapEntry[], config: DocsConfig, options?: BuildSitemapOptions): DocsSitemapEntry[];
+
+/**
+ * Turns the normalized navigation into a content-tree plan: which folders and
+ * `meta.json` files encode the navigation, and where each API page belongs.
+ * The site's `docs.json` stays the single source of truth — authors reorganize
+ * routes and groups by editing one file, never by moving generated files.
+ *
+ * The planner is pure; `@blaaiz/docs-core/generator` executes the plan.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A planned API reference page: one operation and the folder it belongs to.
+ *
+ * @public
+ */
+interface PlannedApiPage {
+    /** Spec file reference from `docs.json`, relative to the content directory. */
+    readonly file: string;
+    /** The operation's HTTP method. */
+    readonly method: string;
+    /** The operation's API route. */
+    readonly apiPath: string;
+    /** Output folder, relative to the docs output directory (e.g. `api/authentication`). */
+    readonly dir: string;
+    /** Position within the group. */
+    readonly order: number;
+}
+/**
+ * A planned API group folder. The generator fills its page order once the
+ * operation slugs are known.
+ *
+ * @public
+ */
+interface PlannedApiGroup {
+    readonly dir: string;
+    readonly title: string;
+}
+/**
+ * A `meta.json` file the plan wants written.
+ *
+ * @public
+ */
+interface PlannedMeta {
+    /** Path relative to the docs output directory, e.g. `guides/meta.json`. */
+    readonly path: string;
+    readonly content: Record<string, unknown>;
+}
+/**
+ * The complete content-tree plan for one navigation.
+ *
+ * @public
+ */
+interface DocsTreePlan {
+    /** Unique spec files referenced by the navigation, in order of appearance. */
+    readonly specs: readonly string[];
+    readonly apiPages: readonly PlannedApiPage[];
+    readonly apiGroups: readonly PlannedApiGroup[];
+    /** Fully-known meta files: the root, tab folders, and doc groups. */
+    readonly metas: readonly PlannedMeta[];
+}
+/**
+ * Options for {@link planDocsTree}.
+ *
+ * @public
+ */
+interface PlanDocsTreeOptions {
+    /** Folder for generated API pages. Default `api`. */
+    readonly apiDir?: string;
+}
+/**
+ * Plan the content tree for a navigation.
+ *
+ * Conventions (Mintlify-shaped):
+ * - A tab whose items reference OpenAPI files becomes the API tab; its groups
+ *   become folders under `apiDir`, named by slugified group title.
+ * - A tab of doc pages becomes the folder its pages share (their first path
+ *   segment); a doc group's pages must share one directory.
+ * - Root-level doc pages (no `/` in the path) are listed in the root meta.
+ * - Tab folders get `root: true`, so the sidebar scopes to the active tab.
+ *
+ * @param navigation - the parsed navigation
+ * @param options - the API folder name
+ * @returns the plan the generator executes
+ * @public
+ */
+declare function planDocsTree(navigation: Navigation, options?: PlanDocsTreeOptions): DocsTreePlan;
+
+/**
+ * Page-to-Markdown conversion for the "Copy page / View as Markdown" feature.
+ *
+ * A docs page is authored in MDX: frontmatter, prose, and JSX components. An
+ * LLM wants none of that machinery — it wants clean Markdown. This module turns
+ * a raw MDX source into readable Markdown, and builds a runtime-agnostic route
+ * that serves it as `text/plain`.
+ *
+ * The transform is pure (string in, string out) and the route takes the content
+ * reader as an injected function, so `core` never touches a filesystem or a
+ * framework: the consuming site decides where its MDX lives.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Reads the raw MDX source for a page, addressed by its route slug segments
+ * (`undefined` or `[]` for the index). Returns `null` when no such page exists.
+ *
+ * The site owns this: it knows where its content directory is.
+ *
+ * @public
+ */
+type MdxReader = (slug: readonly string[] | undefined) => Promise<string | null>;
+/**
+ * Options for {@link mdxToMarkdown}.
+ *
+ * @public
+ */
+interface MdxToMarkdownOptions {
+    /** Heading used when the source declares no `title` in frontmatter. */
+    readonly fallbackTitle?: string;
+    /**
+     * Named OpenAPI documents, keyed by the document name the generated page
+     * references (`document="…"`). When the page's document is present, its
+     * operations are rendered in full — auth, parameters, request-body fields,
+     * and responses — instead of the bare `METHOD /path` line. When a page
+     * names no document and exactly one is supplied, that one is used.
+     */
+    readonly openApiDocuments?: Readonly<Record<string, OpenApiDocument>>;
+}
+/**
+ * Convert a raw MDX source into clean, LLM-friendly Markdown.
+ *
+ * Guide pages return their prose (frontmatter title + description prepended,
+ * JSX stripped, code fences intact). Generated OpenAPI pages return a compact
+ * summary of the endpoint. Returns `null` for empty input.
+ *
+ * @param raw - the MDX file source
+ * @param options - optional fallback title
+ * @returns the Markdown rendering, or `null` when `raw` is empty
+ * @public
+ */
+declare function mdxToMarkdown(raw: string, options?: MdxToMarkdownOptions): string | null;
+/**
+ * A Markdown route ready to re-export from a framework route file.
+ *
+ * @public
+ */
+interface MarkdownRoute {
+    readonly GET: (request: Request, context: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Response>;
+}
+/**
+ * Options for {@link createMarkdownRoute}.
+ *
+ * @public
+ */
+interface CreateMarkdownRouteOptions {
+    /** Reads the raw MDX for a page slug. Supplied by the site. */
+    readonly read: MdxReader;
+    /**
+     * Loads the site's named OpenAPI documents so generated API pages render
+     * their operations in full. Called per request — cache inside the loader
+     * when the document is expensive to build.
+     */
+    readonly loadOpenApiDocuments?: () => Readonly<Record<string, OpenApiDocument>> | Promise<Readonly<Record<string, OpenApiDocument>>>;
+}
+/**
+ * Build a drop-in route that serves a page as plain Markdown. It reads the raw
+ * MDX for the requested slug, converts it with {@link mdxToMarkdown}, and
+ * returns `text/plain` (or `404` when the page does not exist).
+ *
+ * @example
+ * ```ts
+ * // app/md/[[...slug]]/route.ts
+ * export const { GET } = createMarkdownRoute({ read: readDocMdx });
+ * ```
+ *
+ * @param options - the content reader
+ * @returns the route's `GET` handler
+ * @public
+ */
+declare function createMarkdownRoute(options: CreateMarkdownRouteOptions): MarkdownRoute;
+
+/**
+ * Allowed-domain checks.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Return whether an email address belongs to one of the allowed domains.
+ * Matching is case-insensitive and exact on the domain part.
+ *
+ * @param email - the email address to test
+ * @param allowedDomains - permitted domains, e.g. `['blaaiz.com']`
+ * @public
+ */
+declare function isAllowedEmail(email: string, allowedDomains: readonly string[]): boolean;
+
+/**
+ * The email identity provider.
+ *
+ * The simplest provider: a form posts an email; if it belongs to an allowed
+ * domain, a session is issued. It needs no external credentials, so it is ideal
+ * for local development and for organizations that gate by email domain alone.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link createEmailSignIn}.
+ *
+ * @public
+ */
+interface EmailSignInOptions {
+    readonly secret: string;
+    readonly allowedDomains: readonly string[];
+    /** Session lifetime in seconds. Default 8 hours. */
+    readonly ttlSeconds?: number;
+    /** Set the `Secure` cookie flag. Default `true`. */
+    readonly secureCookies?: boolean;
+    /** Fallback redirect after sign-in when no `from` is supplied. Default `/`. */
+    readonly defaultRedirect?: string;
+    /**
+     * Where a browser (form) submission with a disallowed domain is sent back to,
+     * carrying `?error=forbidden`. Default `/signin`. JSON clients still get a
+     * `403` instead of a redirect.
+     */
+    readonly signInPath?: string;
+}
+/**
+ * Build the email sign-in POST handler.
+ *
+ * @param options - secret, allowed domains, and session settings
+ * @returns a request handler that issues a session; a browser submission with a
+ *   disallowed domain is redirected back to the sign-in page with
+ *   `?error=forbidden`, while a JSON request gets a `403`
+ * @public
+ */
+declare function createEmailSignIn(options: EmailSignInOptions): (request: Request) => Promise<Response>;
+
+/**
+ * The Google OAuth identity provider.
+ *
+ * Implements the OAuth 2.0 authorization-code flow against Google, restricted
+ * to the allowed email domains. Credentials are passed in by the caller (which
+ * reads them from environment variables named in config), never hard-coded.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link createGoogleAuth}. `clientId` and `clientSecret` come from
+ * the environment; the config only names the variables.
+ *
+ * @public
+ */
+interface GoogleAuthOptions {
+    readonly clientId: string;
+    readonly clientSecret: string;
+    /** The full callback URL registered with Google. */
+    readonly redirectUri: string;
+    /** The session-signing secret. */
+    readonly secret: string;
+    readonly allowedDomains: readonly string[];
+    readonly ttlSeconds?: number;
+    readonly secureCookies?: boolean;
+    readonly defaultRedirect?: string;
+    /**
+     * Where a failed callback (bad state, token error, disallowed account) is
+     * sent, carrying an `?error=` code. Default `/signin`.
+     */
+    readonly signInPath?: string;
+    /** Fetch implementation for the token exchange (injectable for tests). */
+    readonly fetch?: FetchLike;
+}
+/**
+ * The two Google OAuth route handlers.
+ *
+ * @public
+ */
+interface GoogleAuthHandlers {
+    /** Redirects the browser to Google's consent screen. */
+    readonly start: (request: Request) => Response;
+    /** Handles Google's redirect back, issues a session, and redirects on. */
+    readonly callback: (request: Request) => Promise<Response>;
+}
+/**
+ * Build the Google OAuth handlers.
+ *
+ * @param options - client credentials, callback URL, and session settings
+ * @returns the `start` and `callback` route handlers
+ * @public
+ */
+declare function createGoogleAuth(options: GoogleAuthOptions): GoogleAuthHandlers;
+
+/**
+ * The auth gate — the enforcement half of authentication.
+ *
+ * Given a request, it decides: is there a valid session for an allowed email?
+ * If so the request passes (`null`); otherwise it returns a redirect to the
+ * sign-in page. The gate is identity-provider-agnostic — it does not care how
+ * the session was established, only that it is valid.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link createAuthGate}.
+ *
+ * @public
+ */
+interface AuthGateOptions {
+    /** The session-signing secret. */
+    readonly secret: string;
+    /** Email domains permitted access. */
+    readonly allowedDomains: readonly string[];
+    /** Where to send unauthenticated requests. Default `/signin`. */
+    readonly signInPath?: string;
+    /** Extra path prefixes that never require a session. */
+    readonly publicPaths?: readonly string[];
+}
+/**
+ * Build an auth gate for a Next.js middleware (or any Fetch runtime).
+ *
+ * @param options - secret, allowed domains, and sign-in path
+ * @returns a function returning `null` to allow, or a redirect `Response` to block
+ * @public
+ */
+declare function createAuthGate(options: AuthGateOptions): (request: Request) => Promise<Response | null>;
+
+/**
+ * The shared-secret identity provider.
+ *
+ * A two-step gate: an allowed-domain email, then one site-wide secret. Security
+ * lives entirely in the second step — the domain is re-checked and the secret
+ * compared in constant time — so the first step is only progressive disclosure
+ * and cannot be used to bypass anything. No client JavaScript: each step is a
+ * native form POST, the way an email → password flow works.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link createSecretSignIn}.
+ *
+ * @public
+ */
+interface SecretSignInOptions {
+    /** The session-signing secret (HMAC key), as for the other providers. */
+    readonly secret: string;
+    /** The shared access secret a reader must supply. Resolved from the env. */
+    readonly accessSecret: string;
+    readonly allowedDomains: readonly string[];
+    /** Session lifetime in seconds. Default 8 hours. */
+    readonly ttlSeconds?: number;
+    /** Set the `Secure` cookie flag. Default `true`. */
+    readonly secureCookies?: boolean;
+    /** Fallback redirect after sign-in when no `from` is supplied. Default `/`. */
+    readonly defaultRedirect?: string;
+    /** The sign-in page path, where each step and any error is shown. Default `/signin`. */
+    readonly signInPath?: string;
+    /** How long the between-steps email cookie lives. Default 15 minutes. */
+    readonly pendingTtlSeconds?: number;
+}
+/**
+ * Build the shared-secret sign-in POST handler. It serves both steps of the
+ * flow, told apart by whether the request carries a `secret` field:
+ *
+ * - **Email step** (no `secret`): validate the domain. On success, remember the
+ *   email in a short-lived cookie and advance to the secret step; on failure,
+ *   bounce back with `?error=forbidden`.
+ * - **Secret step** (`secret` present): read the remembered email, re-check its
+ *   domain, and compare the secret in constant time. On success, issue the
+ *   session; on failure, stay on the secret step with `?error=badsecret`.
+ *
+ * @param options - the two secrets, allowed domains, and session settings
+ * @returns a request handler for `/api/auth/secret`
+ * @public
+ */
+declare function createSecretSignIn(options: SecretSignInOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Signed session tokens.
+ *
+ * A session is a small JSON payload (the verified email and an expiry) encoded
+ * and signed with HMAC-SHA256 via the Web Crypto API — so it works in Node, in
+ * an edge runtime, and in a Next.js middleware without any Node-only imports.
+ * The secret never leaves the server; the browser only holds the signed token.
+ *
+ * @packageDocumentation
+ */
+/** The name of the session cookie. @public */
+declare const SESSION_COOKIE = "docs_session";
+/**
+ * The decoded session payload.
+ *
+ * @public
+ */
+interface SessionPayload {
+    /** The verified email address. */
+    readonly email: string;
+    /** Expiry, as a Unix time in seconds. */
+    readonly exp: number;
+}
+/**
+ * Sign a session payload into a `data.signature` token.
+ *
+ * @public
+ */
+declare function signSession(payload: SessionPayload, secret: string): Promise<string>;
+/**
+ * Verify a session token and return its payload, or `null` when the signature
+ * is invalid or the session has expired.
+ *
+ * @param token - the signed token
+ * @param secret - the signing secret
+ * @param nowSeconds - current Unix time; defaults to the real clock
+ * @public
+ */
+declare function verifySession(token: string, secret: string, nowSeconds?: number): Promise<SessionPayload | null>;
+/**
+ * Read a cookie value from a `Cookie` header string.
+ *
+ * @public
+ */
+declare function readCookie(cookieHeader: string | null, name: string): string | null;
+/**
+ * Build a `Set-Cookie` header value carrying the session token.
+ *
+ * @public
+ */
+declare function buildSessionCookie(token: string, options: {
+    maxAgeSeconds: number;
+    secure?: boolean;
+}): string;
+/**
+ * Build a `Set-Cookie` header value that clears the session.
+ *
+ * @public
+ */
+declare function clearSessionCookie(options?: {
+    secure?: boolean;
+}): string;
+
+/**
+ * Sign-out handler.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link createSignOut}.
+ *
+ * @public
+ */
+interface SignOutOptions {
+    readonly secureCookies?: boolean;
+    /** Where to send the browser after signing out. Default `/signin`. */
+    readonly redirectTo?: string;
+}
+/**
+ * Build a sign-out handler that clears the session cookie and redirects.
+ *
+ * @public
+ */
+declare function createSignOut(options?: SignOutOptions): () => Response;
+
+/**
+ * OpenAPI-to-Markdown rendering for LLM corpora.
+ *
+ * A generated API reference page renders its parameters, schemas, and
+ * responses at runtime from the OpenAPI document — none of that text exists in
+ * the page's MDX. Ask AI and the `/md` route need it as text, so this module
+ * renders one operation from the document into compact, deterministic
+ * Markdown: auth requirements, parameters, request-body fields with types,
+ * required markers, enums and defaults, and response shapes.
+ *
+ * The input document is site content and is never trusted: every lookup is
+ * type-checked and malformed fragments are skipped rather than thrown on.
+ * Recursion is bounded twice — a `seen` set of open `$ref` targets stops
+ * self-referencing schemas, and a depth cap bounds legitimately deep nesting
+ * with an explicit elision marker.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Addresses one operation inside an OpenAPI document.
+ *
+ * @public
+ */
+interface OpenApiOperationRef {
+    /** The path key, exactly as it appears under `paths`. */
+    readonly path: string;
+    /** The HTTP method, case-insensitive. */
+    readonly method: string;
+}
+/**
+ * Render one operation from an OpenAPI document as compact Markdown: auth,
+ * parameters, request-body fields, and response shapes. The page-level title
+ * and description are deliberately not rendered — the caller already has them
+ * from the page frontmatter.
+ *
+ * Returns `null` when the document has no such operation.
+ *
+ * @param document - the (merged) OpenAPI document
+ * @param ref - the operation's path and method
+ * @returns Markdown for the operation, or `null` when it is not found
+ * @public
+ */
+declare function openApiOperationToMarkdown(document: OpenApiDocument, ref: OpenApiOperationRef): string | null;
+
+/**
+ * `docs.json` navigation adapter.
+ *
+ * Translates a Mintlify `docs.json` navigation block into the framework's
+ * normalized {@link Navigation} tree. It understands the two page-string forms
+ * Mintlify uses — a plain content path, and an OpenAPI entry of the form
+ * `"<file> <METHOD> <route>"` — and it recurses through arbitrarily nested
+ * groups.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Thrown when a `docs.json` navigation block does not match the expected shape.
+ *
+ * @public
+ */
+declare class InvalidNavigationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a Mintlify `docs.json` object into the normalized {@link Navigation} tree.
+ *
+ * @param docsJson - the parsed contents of a `docs.json` file
+ * @returns the normalized, ordered list of tabs
+ * @throws {@link InvalidNavigationError} when the navigation shape is invalid
+ * @public
+ */
+declare function parseNavigation(docsJson: unknown): Navigation;
+
+/**
+ * OpenAPI merge adapter.
+ *
+ * A Mintlify-style API reference stores one OpenAPI file per endpoint. Renderers
+ * (Scalar, fumadocs-openapi) want a single document. `mergeOpenApiDocuments`
+ * combines many single-operation OpenAPI files into one document: it unions
+ * servers, tags, and components, and assembles the paths. A genuine conflict —
+ * the same method on the same route defined twice — is an error, not a
+ * silent overwrite.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options controlling the merge.
+ *
+ * @public
+ */
+interface MergeOpenApiOptions {
+    /** The `info` block of the merged document. */
+    readonly info: OpenApiInfo;
+    /**
+     * Servers for the merged document. When omitted, servers are unioned from
+     * the input documents (deduplicated by `url`).
+     */
+    readonly servers?: readonly OpenApiServer[];
+    /** The OpenAPI version string of the merged document. Defaults to `3.1.0`. */
+    readonly openapi?: string;
+}
+/**
+ * Thrown when an input is not a usable OpenAPI document, or when two inputs
+ * define the same operation (method + route).
+ *
+ * @public
+ */
+declare class OpenApiMergeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Merge many single-operation OpenAPI documents into one document.
+ *
+ * @param inputs - parsed OpenAPI documents, each typically holding one operation
+ * @param options - the merged document's `info`, and optional server/version overrides
+ * @returns the merged {@link OpenApiDocument}
+ * @throws {@link OpenApiMergeError} on an invalid input or a duplicate operation
+ * @public
+ */
+declare function mergeOpenApiDocuments(inputs: readonly unknown[], options: MergeOpenApiOptions): OpenApiDocument;
+
+export { AiConfig, type AiMessage, type AskAiDocumentsSource, type AskAiRoute, type AskAiRouteOptions, type AskAiSource, type AuthGateOptions, type BuildSitemapOptions, type CreateMarkdownRouteOptions, type CreateTryItProxyOptions, DocsConfig, type DocsMetadata, type DocsRobots, type DocsSitemapEntry, type DocsTreePlan, type EmailSignInOptions, type FetchLike, type GoogleAuthHandlers, type GoogleAuthOptions, type IndexedDocument, InvalidNavigationError, type MarkdownRoute, type MdxReader, type MdxToMarkdownOptions, type MergeOpenApiOptions, Navigation, OpenApiDocument, OpenApiInfo, OpenApiMergeError, type OpenApiOperationRef, OpenApiServer, type PageSeo, type PlanDocsTreeOptions, type PlannedApiGroup, type PlannedApiPage, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };