@blaaiz/docs-core 0.1.0

package/dist/navigation-CGqFIPlP.d.ts

@@ -0,0 +1,498 @@
+/**
+ * The curated model registry.
+ *
+ * A docs site names a provider, and optionally a model. The framework — not the
+ * site — owns which models are known good for grounded documentation answers,
+ * which one is the default, and which environment variable holds the key. A
+ * short allow-list is deliberate: an unknown or retired model id must fail with
+ * a readable error at startup, not with a provider `404` on a reader's first
+ * question.
+ *
+ * The lists grow as providers ship models. Adding one is a one-line change here.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The AI providers `docs-core` speaks to.
+ *
+ * @public
+ */
+type AiProviderName = 'anthropic' | 'openai';
+/**
+ * What the framework knows about one provider: the models it accepts, the model
+ * it picks when a site names none, and the environment variable it reads the API
+ * key from by default.
+ *
+ * @public
+ */
+interface AiProviderModels {
+    /** Model used when `ai.model` is omitted. */
+    readonly defaultModel: string;
+    /** Exhaustive list of accepted model ids, best-first for documentation. */
+    readonly models: readonly string[];
+    /** Env var read when `ai.apiKeyEnv` is omitted. */
+    readonly defaultApiKeyEnv: string;
+}
+/**
+ * Every provider name, in a stable order — for error messages and docs tables.
+ *
+ * @public
+ */
+declare const AI_PROVIDER_NAMES: readonly AiProviderName[];
+/**
+ * The curated registry, keyed by provider.
+ *
+ * @public
+ */
+declare const AI_PROVIDER_MODELS: Readonly<Record<AiProviderName, AiProviderModels>>;
+
+/**
+ * The Ask AI configuration boundary.
+ *
+ * A site declares `ai: { provider: 'anthropic' }` and is done: every other
+ * field has a framework default. That convenience only works if the boundary is
+ * strict, so this module validates each field and fails with a message that
+ * names the field, the value it received, and the accepted values. Nothing
+ * downstream re-checks: {@link resolveAiConfig} is the single gate, and it runs
+ * when the route is built, not when a reader asks a question.
+ *
+ * Secrets never appear here. Config names the environment variable; the server
+ * reads the value at request time.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The Ask AI settings a site supplies. Only `provider` is required.
+ *
+ * @public
+ */
+interface AiConfig {
+    /** Which provider answers questions. */
+    readonly provider: AiProviderName;
+    /** Model id, validated against the provider's allow-list. Provider default when omitted. */
+    readonly model?: string;
+    /** Env var holding the API key. Provider default when omitted (e.g. `ANTHROPIC_API_KEY`). */
+    readonly apiKeyEnv?: string;
+    /** Questions per minute per client IP. Default 10. Always enforced. */
+    readonly rateLimitPerMinute?: number;
+    /** How many documentation pages are retrieved per question. Default 6. */
+    readonly maxContextPages?: number;
+    /** Extra instructions appended to the framework's grounded system prompt. */
+    readonly systemPrompt?: string;
+}
+/**
+ * An {@link AiConfig} with every default filled in and every value checked.
+ * Frozen, so a caller cannot mutate a validated configuration.
+ *
+ * @public
+ */
+interface ResolvedAiConfig {
+    readonly provider: AiProviderName;
+    readonly model: string;
+    /** The env var the server reads the key from. */
+    readonly apiKeyEnv: string;
+    /** The provider's default env var, for error messages and documentation. */
+    readonly defaultApiKeyEnv: string;
+    readonly rateLimitPerMinute: number;
+    readonly maxContextPages: number;
+    /** Present only when the site supplied extra instructions. */
+    readonly systemPrompt?: string;
+}
+/**
+ * Thrown when `ai` configuration is missing, malformed, or out of range. The
+ * message names the exact field and the accepted values.
+ *
+ * @public
+ */
+declare class AiConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a site's `ai` configuration and fill in the framework defaults.
+ *
+ * Call it once, when the route is built. It throws rather than returning an
+ * error object so a misconfigured site fails at startup — a reader must never
+ * discover a typo in `docs.config.ts` by asking a question.
+ *
+ * @param config - the raw `ai` block from a site's configuration
+ * @returns the frozen, fully defaulted configuration
+ * @throws {@link AiConfigError} when any field is missing, malformed, or out of range
+ * @public
+ */
+declare function resolveAiConfig(config: AiConfig): ResolvedAiConfig;
+
+/**
+ * The configuration seam.
+ *
+ * A consuming docs site supplies exactly one {@link DocsConfig}. It carries the
+ * per-site values that must never live in the framework: branding, the auth
+ * mode, and — critically — the allow-list of API origins the try-it proxy may
+ * forward to. `docs-core` owns the behaviour; the site owns these values.
+ *
+ * The boundary is guarded: {@link defineDocsConfig} runs
+ * {@link validateDocsConfig} on every value it is given, so a typo fails when
+ * the site builds rather than when a reader loads a page. A site's config file
+ * may be JavaScript, or built from JSON, so nothing here trusts the static
+ * types — every field is checked at runtime.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Google OAuth provider settings. Secrets never live in config: these name the
+ * environment variables the framework reads at runtime.
+ *
+ * @public
+ */
+interface GoogleProviderConfig {
+    /** Env var holding the OAuth client id. Default `GOOGLE_CLIENT_ID`. */
+    readonly clientIdEnv?: string;
+    /** Env var holding the OAuth client secret. Default `GOOGLE_CLIENT_SECRET`. */
+    readonly clientSecretEnv?: string;
+    /** OAuth callback path. Default `/api/auth/google/callback`. */
+    readonly redirectPath?: string;
+}
+/**
+ * Shared-secret provider settings. The secret is one value for the whole site,
+ * read from the environment at runtime — config only names the variable.
+ *
+ * @public
+ */
+interface SecretProviderConfig {
+    /** Env var holding the shared access secret. Default `DOCS_ACCESS_SECRET`. */
+    readonly secretEnv?: string;
+}
+/**
+ * The sign-in providers a workspace site offers. Enable any combination.
+ *
+ * @public
+ */
+interface WorkspaceProviders {
+    /** Email sign-in: a verified email in an allowed domain gets a session. */
+    readonly email?: boolean;
+    /**
+     * Shared-secret sign-in: an allowed-domain email plus one site-wide secret.
+     * Stronger than email alone, so when enabled it supersedes the email provider
+     * (offering email-only too would let a reader skip the secret).
+     */
+    readonly secret?: SecretProviderConfig;
+    /** Google OAuth sign-in, restricted to the allowed domains. */
+    readonly google?: GoogleProviderConfig;
+}
+/**
+ * Gate the docs to signed-in members of the allowed email domains.
+ *
+ * @public
+ */
+interface WorkspaceAuthConfig {
+    readonly mode: 'workspace';
+    /** Email domains permitted to sign in, e.g. `['blaaiz.com']`. */
+    readonly allowedDomains: readonly string[];
+    /** Which identity providers are offered. */
+    readonly providers: WorkspaceProviders;
+    /** Where unauthenticated requests are redirected. Default `/signin`. */
+    readonly signInPath?: string;
+    /** Env var holding the session-signing secret. Default `DOCS_SESSION_SECRET`. */
+    readonly sessionSecretEnv?: string;
+    /** Session lifetime in seconds. Default 8 hours. */
+    readonly sessionTtlSeconds?: number;
+    /** Set the `Secure` cookie flag. Default `true`; set `false` for local http. */
+    readonly secureCookies?: boolean;
+}
+/**
+ * How a docs site gates access.
+ *
+ * - `'public'` — anyone may read the docs and use the playground.
+ * - {@link WorkspaceAuthConfig} — only signed-in members of the allowed domains.
+ *
+ * @public
+ */
+type AuthConfig = 'public' | WorkspaceAuthConfig;
+/**
+ * A colour palette a site declares. Every token is optional; the framework
+ * falls back to its defaults for anything omitted. The site owns the values;
+ * the framework maps them to its CSS variables (see `buildThemeCss`).
+ *
+ * @public
+ */
+interface ThemePalette {
+    /** Primary accent — active nav, links, buttons, focus rings. */
+    readonly primary?: string;
+    /** Page background. */
+    readonly background?: string;
+    /** Body text. */
+    readonly foreground?: string;
+    /** Panel/card surfaces. */
+    readonly card?: string;
+    /** Hairline borders and dividers. */
+    readonly border?: string;
+    /** Secondary/muted text. */
+    readonly muted?: string;
+}
+/**
+ * Light and dark logo image paths, resolved by the consuming site.
+ *
+ * @public
+ */
+interface ThemeLogo {
+    readonly light: string;
+    readonly dark: string;
+}
+/**
+ * Brand configuration a site supplies. Colours and the logo live here — in the
+ * site — not in the framework.
+ *
+ * @public
+ */
+interface ThemeConfig {
+    /** Display name. */
+    readonly name: string;
+    /** Light + dark logo paths (served by the site). */
+    readonly logo?: ThemeLogo;
+    /** Absolute or site-relative path to the favicon. */
+    readonly favicon?: string;
+    /** Palette applied to the light theme (and as the base for dark). */
+    readonly colors?: ThemePalette;
+    /** Palette overrides applied to the dark theme. */
+    readonly darkColors?: ThemePalette;
+}
+/**
+ * Security-critical: the exhaustive set of upstream API origins the try-it
+ * proxy is permitted to forward requests to. Any target outside this list is
+ * rejected with `403`. This is what keeps the proxy from becoming an open
+ * relay — see {@link https://github.com/blaaiz/docs-core | the proxy design}.
+ *
+ * @public
+ */
+interface ProxyConfig {
+    /** Allowed upstream origins, e.g. `["https://api-dev.example.com"]`. */
+    readonly allowedOrigins: readonly string[];
+    /**
+     * Forwards per minute per client IP. Default 60. Enforced by both
+     * `createTryItProxy` and `createTryItProxyRoute`; pass the value through when
+     * you mount the route.
+     */
+    readonly rateLimitPerMinute?: number;
+}
+/**
+ * Search-engine and social-sharing metadata a site supplies. Everything is
+ * optional; the framework fills sensible defaults from {@link ThemeConfig.name}.
+ * The site owns these values — the canonical origin, the sharing image — because
+ * they are deployment facts, not framework behaviour.
+ *
+ * @public
+ */
+interface SeoConfig {
+    /**
+     * The canonical public origin, e.g. `https://docs.example.com`. Enables
+     * absolute canonical URLs, the sitemap, and Open Graph URLs. Without it those
+     * fall back to relative URLs, which is correct but weaker for SEO.
+     */
+    readonly siteUrl?: string;
+    /**
+     * Title template for inner pages, with `%s` standing in for the page title,
+     * e.g. `'%s | Example Docs'`. Default `'%s · <theme.name>'`. The home title is
+     * {@link ThemeConfig.name} verbatim.
+     */
+    readonly titleTemplate?: string;
+    /** Default meta description, used where a page declares none. */
+    readonly description?: string;
+    /** Site-relative or absolute path to the default Open Graph / Twitter image. */
+    readonly ogImage?: string;
+    /** `@handle` for Twitter card attribution. */
+    readonly twitter?: string;
+    /** Default keywords applied site-wide. Pages may add their own. */
+    readonly keywords?: readonly string[];
+    /**
+     * Ask crawlers not to index the site (a private or pre-launch docs site).
+     * Default `false`. Auth-gated sites usually want `true`.
+     */
+    readonly noindex?: boolean;
+}
+/**
+ * Optional features a site opts into. Every flag defaults to `false`, so a site
+ * gets a feature only by asking for it. The framework ships the behaviour; the
+ * site decides whether to switch it on.
+ *
+ * @public
+ */
+interface FeaturesConfig {
+    /**
+     * Show the "Copy page / View as Markdown" control on each doc page, and serve
+     * the plain-Markdown route it links to. Lets a reader hand the page to an LLM.
+     * Default `false`.
+     */
+    readonly copyPage?: boolean;
+}
+/**
+ * The complete, validated configuration for one docs site.
+ *
+ * @public
+ */
+interface DocsConfig {
+    readonly theme: ThemeConfig;
+    readonly auth: AuthConfig;
+    readonly proxy: ProxyConfig;
+    /** Opt-in features. Omit it entirely and every feature stays off. */
+    readonly features?: FeaturesConfig;
+    /** Search-engine and social-sharing metadata. Omit for name-only defaults. */
+    readonly seo?: SeoConfig;
+    /**
+     * Ask AI settings. Omit the block and the feature stays off. Naming a
+     * provider is a complete setup, because every other field has a framework
+     * default. The API key never lives here — config names the environment
+     * variable, and the server reads it at runtime.
+     */
+    readonly ai?: AiConfig;
+}
+/**
+ * Thrown when a site's {@link DocsConfig} is malformed. The message names the
+ * exact field, the value it received, and the accepted values.
+ *
+ * The `ai` block is the one exception: {@link validateDocsConfig} delegates it
+ * to `resolveAiConfig`, which raises an `AiConfigError` instead. Both extend
+ * `Error`, so a site's build fails the same way either way.
+ *
+ * @public
+ */
+declare class DocsConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate a site's configuration and return it.
+ *
+ * {@link defineDocsConfig} calls it, so a site rarely calls it directly. It is
+ * exported for a site that loads its configuration from somewhere else — JSON,
+ * a remote source, a JavaScript file with no type-checking — and needs the same
+ * guarantee.
+ *
+ * Every field is checked at runtime, and the message names the exact field:
+ * `auth.mode must be 'workspace', got 'workspase'.` The `ai` block is delegated
+ * to `resolveAiConfig`, the single gate for Ask AI settings, so its messages are
+ * identical to the ones the Ask AI route raises.
+ *
+ * @param config - the site configuration, from any source
+ * @returns the same object, typed as {@link DocsConfig}
+ * @throws {@link DocsConfigError} when any field outside `ai` is missing or malformed
+ * @public
+ */
+declare function validateDocsConfig(config: unknown): DocsConfig;
+/**
+ * Identity helper that gives a site's `docs.config.ts` full type-checking and
+ * editor completion without importing types by hand.
+ *
+ * It also validates: every field is checked at runtime by
+ * {@link validateDocsConfig}, so a malformed value fails when the site builds,
+ * with a message that names the field. A JavaScript config file gets the same
+ * protection as a TypeScript one.
+ *
+ * @example
+ * ```ts
+ * import { defineDocsConfig } from '@blaaiz/docs-core';
+ *
+ * export default defineDocsConfig({
+ *   theme: {
+ *     name: 'Blaaiz',
+ *     logo: { light: '/logo-light.png', dark: '/logo-dark.png' },
+ *     colors: { primary: '#4c63f5' },
+ *     darkColors: { background: '#0a0a0b', card: '#141416' },
+ *   },
+ *   auth: {
+ *     mode: 'workspace',
+ *     allowedDomains: ['blaaiz.com'],
+ *     providers: { email: true, google: {} },
+ *   },
+ *   proxy: { allowedOrigins: ['https://api-dev.blaaiz.com'] },
+ * });
+ * ```
+ *
+ * @param config - the site configuration
+ * @returns the same configuration, typed as {@link DocsConfig}
+ * @throws {@link DocsConfigError} when any field outside `ai` is missing or malformed
+ * @public
+ */
+declare function defineDocsConfig(config: DocsConfig): DocsConfig;
+
+/**
+ * The normalized navigation model.
+ *
+ * A consuming site authors navigation in a Mintlify `docs.json`. The
+ * `docs-json` adapter parses that shape into this normalized tree, which the
+ * rest of the framework (rendering, search, the API reference) consumes. Keep
+ * this model free of any Mintlify-specific detail: it is the neutral contract.
+ *
+ * @packageDocumentation
+ */
+/**
+ * An HTTP method that an API reference page documents.
+ *
+ * @public
+ */
+type NavMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
+/**
+ * A prose documentation page backed by an MDX/content file.
+ *
+ * @public
+ */
+interface DocPage {
+    readonly kind: 'doc';
+    /** Path to the content file, relative to the site root, without extension. */
+    readonly file: string;
+}
+/**
+ * An API reference page backed by a single-operation OpenAPI file.
+ *
+ * @public
+ */
+interface OpenApiPage {
+    readonly kind: 'openapi';
+    /** Path to the `*-openapi.json` file, relative to the site root. */
+    readonly file: string;
+    /** The operation's HTTP method. */
+    readonly method: NavMethod;
+    /** The operation's API route, e.g. `/api/user/login`. */
+    readonly apiPath: string;
+}
+/**
+ * A page in the navigation tree.
+ *
+ * @public
+ */
+type NavPage = DocPage | OpenApiPage;
+/**
+ * A named group of pages and/or nested groups. Groups may nest to any depth.
+ *
+ * @public
+ */
+interface NavGroup {
+    readonly kind: 'group';
+    readonly title: string;
+    readonly items: readonly NavItem[];
+}
+/**
+ * Any node inside a tab: a page or a group.
+ *
+ * @public
+ */
+type NavItem = NavPage | NavGroup;
+/**
+ * A top-level navigation tab.
+ *
+ * @public
+ */
+interface NavTab {
+    readonly kind: 'tab';
+    readonly title: string;
+    /** Optional icon name, passed through verbatim from the source. */
+    readonly icon?: string;
+    readonly items: readonly NavItem[];
+}
+/**
+ * The complete normalized navigation: an ordered list of tabs.
+ *
+ * @public
+ */
+type Navigation = readonly NavTab[];
+
+export { type AiConfig as A, type DocsConfig as D, type FeaturesConfig as F, type GoogleProviderConfig as G, type Navigation as N, type OpenApiPage as O, type ProxyConfig as P, type ResolvedAiConfig as R, type SecretProviderConfig as S, type ThemeConfig as T, type WorkspaceAuthConfig as W, AI_PROVIDER_MODELS as a, AI_PROVIDER_NAMES as b, AiConfigError as c, type AiProviderModels as d, type AiProviderName as e, type AuthConfig as f, type DocPage as g, DocsConfigError as h, type NavGroup as i, type NavItem as j, type NavMethod as k, type NavPage as l, type NavTab as m, type SeoConfig as n, type ThemeLogo as o, type ThemePalette as p, type WorkspaceProviders as q, defineDocsConfig as r, resolveAiConfig as s, validateDocsConfig as v };

package/dist/openapi-types-CJ6p5Cux.d.cts

@@ -0,0 +1,78 @@
+/**
+ * A pragmatic subset of the OpenAPI 3.x document model.
+ *
+ * The framework does not re-type the whole OpenAPI specification. It models
+ * only the top-level containers it needs to merge many single-operation files
+ * into one document — paths, servers, tags, and components. Operation and
+ * schema objects are carried through opaquely.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The `info` block of an OpenAPI document.
+ *
+ * @public
+ */
+interface OpenApiInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+}
+/**
+ * A server entry.
+ *
+ * @public
+ */
+interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * A tag entry.
+ *
+ * @public
+ */
+interface OpenApiTag {
+    readonly name: string;
+    readonly description?: string;
+}
+/**
+ * An operation object, carried through without being re-typed.
+ *
+ * @public
+ */
+type OpenApiOperation = Record<string, unknown>;
+/**
+ * A path item: a map of lower-case HTTP method to operation.
+ *
+ * @public
+ */
+type OpenApiPathItem = Record<string, OpenApiOperation>;
+/**
+ * The `components` block. Only the maps the framework merges are named; other
+ * keys are carried through.
+ *
+ * @public
+ */
+interface OpenApiComponents {
+    readonly securitySchemes?: Record<string, unknown>;
+    readonly schemas?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+/**
+ * A merged OpenAPI document.
+ *
+ * @public
+ */
+interface OpenApiDocument {
+    readonly openapi: string;
+    readonly info: OpenApiInfo;
+    readonly servers: readonly OpenApiServer[];
+    readonly tags: readonly OpenApiTag[];
+    readonly paths: Readonly<Record<string, OpenApiPathItem>>;
+    readonly components: OpenApiComponents;
+    /** Document-level security requirements, carried through opaquely. */
+    readonly security?: readonly unknown[];
+}
+
+export type { OpenApiInfo as O, OpenApiServer as a, OpenApiDocument as b, OpenApiComponents as c, OpenApiOperation as d, OpenApiPathItem as e, OpenApiTag as f };

package/dist/openapi-types-CJ6p5Cux.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A pragmatic subset of the OpenAPI 3.x document model.
+ *
+ * The framework does not re-type the whole OpenAPI specification. It models
+ * only the top-level containers it needs to merge many single-operation files
+ * into one document — paths, servers, tags, and components. Operation and
+ * schema objects are carried through opaquely.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The `info` block of an OpenAPI document.
+ *
+ * @public
+ */
+interface OpenApiInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+}
+/**
+ * A server entry.
+ *
+ * @public
+ */
+interface OpenApiServer {
+    readonly url: string;
+    readonly description?: string;
+}
+/**
+ * A tag entry.
+ *
+ * @public
+ */
+interface OpenApiTag {
+    readonly name: string;
+    readonly description?: string;
+}
+/**
+ * An operation object, carried through without being re-typed.
+ *
+ * @public
+ */
+type OpenApiOperation = Record<string, unknown>;
+/**
+ * A path item: a map of lower-case HTTP method to operation.
+ *
+ * @public
+ */
+type OpenApiPathItem = Record<string, OpenApiOperation>;
+/**
+ * The `components` block. Only the maps the framework merges are named; other
+ * keys are carried through.
+ *
+ * @public
+ */
+interface OpenApiComponents {
+    readonly securitySchemes?: Record<string, unknown>;
+    readonly schemas?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+/**
+ * A merged OpenAPI document.
+ *
+ * @public
+ */
+interface OpenApiDocument {
+    readonly openapi: string;
+    readonly info: OpenApiInfo;
+    readonly servers: readonly OpenApiServer[];
+    readonly tags: readonly OpenApiTag[];
+    readonly paths: Readonly<Record<string, OpenApiPathItem>>;
+    readonly components: OpenApiComponents;
+    /** Document-level security requirements, carried through opaquely. */
+    readonly security?: readonly unknown[];
+}
+
+export type { OpenApiInfo as O, OpenApiServer as a, OpenApiDocument as b, OpenApiComponents as c, OpenApiOperation as d, OpenApiPathItem as e, OpenApiTag as f };