@blaaiz/docs-core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -617,15 +617,33 @@ interface PlannedApiPage {
     /** Position within the group. */
     readonly order: number;
 }
+/**
+ * A child folder of a planned API group, at its position among the group's
+ * pages. The generator merges these with the resolved page slugs to write the
+ * group's `meta.json` in declared order.
+ *
+ * @public
+ */
+interface PlannedGroupChild {
+    readonly order: number;
+    /** The child folder's name within the group directory. */
+    readonly folder: string;
+}
 /**
  * A planned API group folder. The generator fills its page order once the
- * operation slugs are known.
+ * operation slugs are known, interleaving {@link PlannedGroupChild} folders at
+ * their declared positions. A group with `root: true` is an API tab's folder.
  *
  * @public
  */
 interface PlannedApiGroup {
     readonly dir: string;
     readonly title: string;
+    readonly children: readonly PlannedGroupChild[];
+    /** Set on an API tab's own folder, so the sidebar scopes to the tab. */
+    readonly root?: boolean;
+    /** The tab's icon, on a `root` group. */
+    readonly icon?: string;
 }
 /**
  * A `meta.json` file the plan wants written.
@@ -647,8 +665,14 @@ interface DocsTreePlan {
     readonly specs: readonly string[];
     readonly apiPages: readonly PlannedApiPage[];
     readonly apiGroups: readonly PlannedApiGroup[];
-    /** Fully-known meta files: the root, tab folders, and doc groups. */
+    /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
+    /**
+     * Doc pages declared inside API tabs. The plan cannot place them in the
+     * generated folders, so the generator reports them instead of dropping them
+     * silently; they stay reachable at their own URLs.
+     */
+    readonly apiTabDocPages: readonly string[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -656,23 +680,27 @@ interface DocsTreePlan {
  * @public
  */
 interface PlanDocsTreeOptions {
-    /** Folder for generated API pages. Default `api`. */
+    /** Folder for generated API pages when one tab publishes them. 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 whose items reference OpenAPI files becomes an API tab. With one API
+ *   tab its folder is `apiDir`; with several, each tab's folder is its
+ *   slugified title, so tabs never collide. Groups become nested folders named
+ *   by slugified group title, to any depth.
  * - A tab of doc pages becomes the folder its pages share (their first path
- *   segment); a doc group's pages must share one directory.
+ *   segment); a doc group's pages must share one directory. Doc groups nest.
  * - 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.
+ * - Sidebar order is declaration order, pages and groups interleaved.
  *
  * @param navigation - the parsed navigation
  * @param options - the API folder name
  * @returns the plan the generator executes
+ * @throws when two sibling groups slugify to the same folder
  * @public
  */
 declare function planDocsTree(navigation: Navigation, options?: PlanDocsTreeOptions): DocsTreePlan;
@@ -1055,6 +1083,79 @@ interface SignOutOptions {
  */
 declare function createSignOut(options?: SignOutOptions): () => Response;
 
+/**
+ * The whole of a site's auth, assembled from `docs.config.ts`.
+ *
+ * A site mounts the same five files whatever its access mode — middleware,
+ * the sign-in page, and the provider routes — and `createSiteAuth` decides
+ * what they do. On a public site the gate passes everything and the handlers
+ * answer `501`, so the files cost nothing; switching to workspace mode is a
+ * config edit and two environment variables, never new files.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link createSiteAuth}.
+ *
+ * @public
+ */
+interface SiteAuthOptions {
+    /**
+     * Path prefixes the gate never blocks, besides the built-in ones. Defaults
+     * to `['/api/proxy']`: the try-it proxy is allow-list-bounded and injects
+     * no secrets, so it needs no session.
+     */
+    readonly publicPaths?: readonly string[];
+    /** Reads an environment variable. Defaults to `process.env`. */
+    readonly env?: (name: string) => string | undefined;
+}
+/**
+ * Everything a site's auth files mount, in both access modes.
+ *
+ * @public
+ */
+interface SiteAuth {
+    /** Whether the site is in workspace mode. */
+    readonly enabled: boolean;
+    /** Where the gate sends blocked requests. */
+    readonly signInPath: string;
+    /** Whether the shared-secret form should be offered. */
+    readonly secretEnabled: boolean;
+    /** Whether the Google button should be offered. */
+    readonly googleEnabled: boolean;
+    /** `null` to allow a request, a redirect `Response` to block it. */
+    readonly gate: (request: Request) => Promise<Response | null>;
+    /** The email provider's endpoint. `501` when not offered. */
+    readonly emailSignIn: (request: Request) => Promise<Response>;
+    /** The shared-secret provider's endpoint. `501` when not offered. */
+    readonly secretSignIn: (request: Request) => Promise<Response>;
+    /** The Google OAuth endpoints. `501` when not offered. */
+    readonly google: {
+        readonly start: (request: Request) => Response;
+        readonly callback: (request: Request) => Promise<Response>;
+    };
+    /** Clears the session and redirects to the sign-in path. */
+    readonly signOut: () => Response;
+}
+/**
+ * Assemble a site's gate, sign-in handlers, and sign-out from its `auth`
+ * config. Accepts both access modes, so the mounting files never change:
+ * `'public'` yields a pass-everything gate and `501` handlers, a workspace
+ * block yields the live flows for exactly the providers it declares.
+ *
+ * In workspace mode the session-signing secret is required and read from the
+ * environment variable named by `sessionSecretEnv` (default
+ * `DOCS_SESSION_SECRET`); a missing value fails at startup with the variable's
+ * name rather than signing sessions with a guessable fallback.
+ *
+ * @param auth - the `auth` field of `docs.config.ts`
+ * @param options - extra public paths and the environment reader
+ * @returns the assembled handlers
+ * @public
+ */
+declare function createSiteAuth(auth: DocsConfig['auth'], options?: SiteAuthOptions): SiteAuth;
+
 /**
  * OpenAPI-to-Markdown rendering for LLM corpora.
  *
@@ -1179,4 +1280,4 @@ declare class OpenApiMergeError extends Error {
  */
 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 };
+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 PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.d.ts

@@ -617,15 +617,33 @@ interface PlannedApiPage {
     /** Position within the group. */
     readonly order: number;
 }
+/**
+ * A child folder of a planned API group, at its position among the group's
+ * pages. The generator merges these with the resolved page slugs to write the
+ * group's `meta.json` in declared order.
+ *
+ * @public
+ */
+interface PlannedGroupChild {
+    readonly order: number;
+    /** The child folder's name within the group directory. */
+    readonly folder: string;
+}
 /**
  * A planned API group folder. The generator fills its page order once the
- * operation slugs are known.
+ * operation slugs are known, interleaving {@link PlannedGroupChild} folders at
+ * their declared positions. A group with `root: true` is an API tab's folder.
  *
  * @public
  */
 interface PlannedApiGroup {
     readonly dir: string;
     readonly title: string;
+    readonly children: readonly PlannedGroupChild[];
+    /** Set on an API tab's own folder, so the sidebar scopes to the tab. */
+    readonly root?: boolean;
+    /** The tab's icon, on a `root` group. */
+    readonly icon?: string;
 }
 /**
  * A `meta.json` file the plan wants written.
@@ -647,8 +665,14 @@ interface DocsTreePlan {
     readonly specs: readonly string[];
     readonly apiPages: readonly PlannedApiPage[];
     readonly apiGroups: readonly PlannedApiGroup[];
-    /** Fully-known meta files: the root, tab folders, and doc groups. */
+    /** Fully-known meta files: the root, doc tab folders, and doc groups. */
     readonly metas: readonly PlannedMeta[];
+    /**
+     * Doc pages declared inside API tabs. The plan cannot place them in the
+     * generated folders, so the generator reports them instead of dropping them
+     * silently; they stay reachable at their own URLs.
+     */
+    readonly apiTabDocPages: readonly string[];
 }
 /**
  * Options for {@link planDocsTree}.
@@ -656,23 +680,27 @@ interface DocsTreePlan {
  * @public
  */
 interface PlanDocsTreeOptions {
-    /** Folder for generated API pages. Default `api`. */
+    /** Folder for generated API pages when one tab publishes them. 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 whose items reference OpenAPI files becomes an API tab. With one API
+ *   tab its folder is `apiDir`; with several, each tab's folder is its
+ *   slugified title, so tabs never collide. Groups become nested folders named
+ *   by slugified group title, to any depth.
  * - A tab of doc pages becomes the folder its pages share (their first path
- *   segment); a doc group's pages must share one directory.
+ *   segment); a doc group's pages must share one directory. Doc groups nest.
  * - 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.
+ * - Sidebar order is declaration order, pages and groups interleaved.
  *
  * @param navigation - the parsed navigation
  * @param options - the API folder name
  * @returns the plan the generator executes
+ * @throws when two sibling groups slugify to the same folder
  * @public
  */
 declare function planDocsTree(navigation: Navigation, options?: PlanDocsTreeOptions): DocsTreePlan;
@@ -1055,6 +1083,79 @@ interface SignOutOptions {
  */
 declare function createSignOut(options?: SignOutOptions): () => Response;
 
+/**
+ * The whole of a site's auth, assembled from `docs.config.ts`.
+ *
+ * A site mounts the same five files whatever its access mode — middleware,
+ * the sign-in page, and the provider routes — and `createSiteAuth` decides
+ * what they do. On a public site the gate passes everything and the handlers
+ * answer `501`, so the files cost nothing; switching to workspace mode is a
+ * config edit and two environment variables, never new files.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for {@link createSiteAuth}.
+ *
+ * @public
+ */
+interface SiteAuthOptions {
+    /**
+     * Path prefixes the gate never blocks, besides the built-in ones. Defaults
+     * to `['/api/proxy']`: the try-it proxy is allow-list-bounded and injects
+     * no secrets, so it needs no session.
+     */
+    readonly publicPaths?: readonly string[];
+    /** Reads an environment variable. Defaults to `process.env`. */
+    readonly env?: (name: string) => string | undefined;
+}
+/**
+ * Everything a site's auth files mount, in both access modes.
+ *
+ * @public
+ */
+interface SiteAuth {
+    /** Whether the site is in workspace mode. */
+    readonly enabled: boolean;
+    /** Where the gate sends blocked requests. */
+    readonly signInPath: string;
+    /** Whether the shared-secret form should be offered. */
+    readonly secretEnabled: boolean;
+    /** Whether the Google button should be offered. */
+    readonly googleEnabled: boolean;
+    /** `null` to allow a request, a redirect `Response` to block it. */
+    readonly gate: (request: Request) => Promise<Response | null>;
+    /** The email provider's endpoint. `501` when not offered. */
+    readonly emailSignIn: (request: Request) => Promise<Response>;
+    /** The shared-secret provider's endpoint. `501` when not offered. */
+    readonly secretSignIn: (request: Request) => Promise<Response>;
+    /** The Google OAuth endpoints. `501` when not offered. */
+    readonly google: {
+        readonly start: (request: Request) => Response;
+        readonly callback: (request: Request) => Promise<Response>;
+    };
+    /** Clears the session and redirects to the sign-in path. */
+    readonly signOut: () => Response;
+}
+/**
+ * Assemble a site's gate, sign-in handlers, and sign-out from its `auth`
+ * config. Accepts both access modes, so the mounting files never change:
+ * `'public'` yields a pass-everything gate and `501` handlers, a workspace
+ * block yields the live flows for exactly the providers it declares.
+ *
+ * In workspace mode the session-signing secret is required and read from the
+ * environment variable named by `sessionSecretEnv` (default
+ * `DOCS_SESSION_SECRET`); a missing value fails at startup with the variable's
+ * name rather than signing sessions with a guessable fallback.
+ *
+ * @param auth - the `auth` field of `docs.config.ts`
+ * @param options - extra public paths and the environment reader
+ * @returns the assembled handlers
+ * @public
+ */
+declare function createSiteAuth(auth: DocsConfig['auth'], options?: SiteAuthOptions): SiteAuth;
+
 /**
  * OpenAPI-to-Markdown rendering for LLM corpora.
  *
@@ -1179,4 +1280,4 @@ declare class OpenApiMergeError extends Error {
  */
 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 };
+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 PlannedGroupChild, type PlannedMeta, ProxyTargetError, SESSION_COOKIE, type SearchDocument, type SearchIndex, type SearchResult, type SecretSignInOptions, type SessionPayload, type SignOutOptions, type SiteAuth, type SiteAuthOptions, type SitemapChangeFrequency, type SitemapEntry, ThemeConfig, type TryItEnvelope, type TryItProxyRoute, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, searchIndex, signSession, unwrapProxyTarget, verifySession };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createTryItProxy, createTryItProxyRoute, defineDocsConfig, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-3ZX4WIE3.js';
+export { AI_PROVIDER_MODELS, AI_PROVIDER_NAMES, AiConfigError, DocsConfigError, InvalidNavigationError, OpenApiMergeError, ProxyTargetError, SESSION_COOKIE, assertAllowedTarget, buildMetadata, buildRobots, buildSearchIndex, buildSessionCookie, buildSitemap, buildThemeCss, clearSessionCookie, createAskAiRoute, createAuthGate, createEmailSignIn, createGoogleAuth, createMarkdownRoute, createSecretSignIn, createSignOut, createSiteAuth, createTryItProxy, createTryItProxyRoute, defineDocsConfig, isAllowedEmail, mdxToMarkdown, mergeOpenApiDocuments, openApiOperationToMarkdown, parseNavigation, planDocsTree, readCookie, resolveAiConfig, searchIndex, signSession, unwrapProxyTarget, validateDocsConfig, verifySession } from './chunk-JHN5XQPU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/ui.cjs

@@ -61,7 +61,7 @@ function apiMethodBadges(methods) {
         name: /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "api-nav-item", children: [
           /* @__PURE__ */ jsxRuntime.jsx(MethodBadge, { method }),
           /* @__PURE__ */ jsxRuntime.jsx("span", { className: "api-nav-text", children: node.name })
-        ] })
+        ] }, node.url)
       };
     }
   };