@solutiondesk/help 0.0.0-stage → 1.0.0-1a5deb7

package/dist/fumadocs.d.ts

@@ -0,0 +1,780 @@
+import { JSXElementConstructor, ReactNode, ComponentType } from 'react';
+import { MetaData, PageData, StaticSource, VirtualFile, DynamicSource } from 'fumadocs-core/source';
+import { TOCItemType } from 'fumadocs-core/toc';
+
+/**
+ * The answers of the public help center API (`GET /v1/help/{workspace}/{site}/…`).
+ * Written by hand so the package has no dependencies; a drift test in the
+ * SolutionDesk repository keeps them identical to the API's own contracts.
+ *
+ * Only what is publicly visible ever appears here: a page that is published,
+ * public and placed in the site's navigation — except the one page a valid
+ * preview token names. Absent values are `null`, never a missing key.
+ *
+ * Paths: a page's path is its folder slugs plus its slug, without leading or
+ * trailing slash (`guides/login`) — a `group` folder adds no slug; the site's
+ * home page has the path `""`.
+ */
+/** The doc site itself. */
+interface HelpPublicSite {
+    /** The site's handle in the URL (`hilfe`). */
+    slug: string;
+    name: string;
+    /** Main language (BCP 47 code, e.g. `de`). */
+    language: string;
+    /** Every language the site is offered in, main language first. */
+    languages: string[];
+    /** The docs website's base address (`https://help.acme.com/docs`), if set. */
+    websiteUrl: string | null;
+    /** The site's own building blocks pages may use (empty when it defines none). */
+    blocks: HelpPublicBlockDefinition[];
+}
+/** What a field of a site's own block holds (see {@link HelpPublicBlockField}). */
+type HelpPublicBlockFieldType = "text" | "longText" | "icon" | "url" | "choice" | "image" | "video" | "boolean";
+/**
+ * One field of a site's own block: an attribute of its directive
+ * (`key="value"`). `boolean` fields are on when written bare (`key`) or as
+ * `key="true"`; every other value is a string. `options` lists a `choice`
+ * field's values (null for other types).
+ */
+interface HelpPublicBlockField {
+    key: string;
+    label: string;
+    type: HelpPublicBlockFieldType;
+    required: boolean;
+    options: string[] | null;
+}
+/**
+ * A building block the site defines itself — WHAT it is; how it looks is the
+ * website's own component. Written in Markdown as `:name[label]{…}` in running
+ * text (`inline`), `::name[label]{…}` alone on a line (`block`) or
+ * `:::name{…}` … `:::` around Markdown content (`container`). `text` is the
+ * template of its text version (`{key}` = a field's value, a `boolean` field's
+ * label when on; `{{`/`}}` = a brace) — what to show without a component.
+ */
+interface HelpPublicBlockDefinition {
+    /** The directive name (`app-button`). */
+    name: string;
+    /** Display name. */
+    label: string;
+    kind: "inline" | "block" | "container";
+    fields: HelpPublicBlockField[];
+    text: string;
+}
+/** A page in the navigation. */
+interface HelpPublicTreePage {
+    type: "page";
+    /** The page's own slug (the last path segment; `index` for the home page). */
+    slug: string;
+    path: string;
+    title: string;
+    description: string | null;
+    /** A Lucide icon name (`BookOpen`). */
+    icon: string | null;
+}
+/** A folder (Fumadocs: a directory with `meta.json`). Empty folders are left out. */
+interface HelpPublicTreeFolder {
+    type: "folder";
+    /** Stable node id. */
+    id: string;
+    slug: string;
+    /** The folder's path (its index page, if any, lives here; a group's is its parent's). */
+    path: string;
+    title: string;
+    /** A short line under a tab's name in the tab menu (Fumadocs `description`); null without one. */
+    description: string | null;
+    icon: string | null;
+    /** A tab (top level only; Fumadocs `root`). */
+    root: boolean;
+    /**
+     * Adds no segment to its pages' paths (Fumadocs `(name)` folder): `path` is
+     * the parent's, a top-level group's index page is the home (`""`).
+     */
+    group: boolean;
+    defaultOpen: boolean;
+    collapsible: boolean;
+    /** The folder's own page, shown at the folder's path; null without one. */
+    index: HelpPublicTreePage | null;
+    /**
+     * List `index` as the folder's first entry (after a section title it starts
+     * with); the folder's name then only opens it (Fumadocs: `index` in `pages`).
+     */
+    listIndex: boolean;
+    children: HelpPublicTreeNode[];
+}
+/** A labelled divider between entries (Fumadocs `---Title---`). */
+interface HelpPublicTreeSeparator {
+    type: "separator";
+    id: string;
+    title: string | null;
+    icon: string | null;
+}
+/** A menu entry pointing elsewhere: an https address or a path on the docs website. */
+interface HelpPublicTreeLink {
+    type: "link";
+    id: string;
+    title: string;
+    url: string;
+    icon: string | null;
+    /** Open as an external link (Fumadocs `external:`). */
+    external: boolean;
+}
+/** One entry of the navigation tree, discriminated by `type`. */
+type HelpPublicTreeNode = HelpPublicTreePage | HelpPublicTreeFolder | HelpPublicTreeSeparator | HelpPublicTreeLink;
+/** `GET site?lang=` — the site and its navigation in one language. */
+interface HelpPublicSitePayload {
+    site: HelpPublicSite;
+    /** The language the labels are in (`?lang=`: exact, base language, else the main one). */
+    locale: string;
+    /** The site's languages, main first (same as `site.languages`). */
+    languages: string[];
+    tree: HelpPublicTreeNode[];
+}
+/** A visible page without its text (`GET pages`: builds and sitemaps). */
+interface HelpPublicPageSummary {
+    path: string;
+    slug: string;
+    title: string;
+    description: string | null;
+    icon: string | null;
+    /** The language this page's texts are in (falls back to the main language per page). */
+    locale: string;
+    /** The languages this page is offered in, main language first. */
+    languages: string[];
+    /** When it was first published (ISO 8601). */
+    publishedAt: string | null;
+    /** "Updated on", set deliberately by the authors; null when never set. */
+    contentUpdatedAt: string | null;
+    /** The last change of any kind (ISO 8601) — for sitemaps and caches. */
+    updatedAt: string;
+    /** The page on the docs website (`websiteUrl` + path), null without a website address. */
+    url: string | null;
+}
+/** `GET pages?lang=` — every visible page in reading order. */
+interface HelpPublicPagesPayload {
+    locale: string;
+    languages: string[];
+    pages: HelpPublicPageSummary[];
+}
+/** A heading of the page, with the anchor id the `html` gives it. */
+interface HelpPublicHeading {
+    level: number;
+    text: string;
+    id: string;
+}
+/** The directives a page uses (a website loads tab scripts only when needed). */
+type HelpPublicBlock = "callout" | "steps" | "step" | "tabs" | "tab" | "cards" | "card";
+/** A folder above a page, outermost first; `path` only when the folder has its own page. */
+interface HelpPublicBreadcrumb {
+    title: string;
+    path: string | null;
+}
+/** The page before or after, in the tree's reading order (never across tabs). */
+interface HelpPublicPageLink {
+    path: string;
+    title: string;
+}
+/** One page with its text. */
+interface HelpPublicPage extends HelpPublicPageSummary {
+    /**
+     * The page's Markdown with directives (`:::callout`, `::::steps`, …, and the
+     * site's own blocks as written — see `site.blocks`).
+     */
+    markdown: string;
+    /** Safe server-rendered HTML of `markdown` (stable `sd-*` classes for the directives). */
+    html: string;
+    headings: HelpPublicHeading[];
+    blocks: HelpPublicBlock[];
+    /** The site's own building blocks the page uses, by name (in the site's order). */
+    customBlocks: string[];
+    breadcrumbs: HelpPublicBreadcrumb[];
+    previous: HelpPublicPageLink | null;
+    next: HelpPublicPageLink | null;
+}
+/**
+ * `GET page?path=&lang=`. A path the page had before answers `301` with
+ * `Location` pointing at the new `page?path=` and the body {@link HelpPublicRedirect}.
+ */
+interface HelpPublicPagePayload {
+    page: HelpPublicPage;
+}
+/** The body of a `301` for a moved page. */
+interface HelpPublicRedirect {
+    /** The page's current path. */
+    redirectTo: string;
+}
+/**
+ * A page as its preview shows it: any status, any visibility, translations as
+ * soon as they have a title. `path` is null while the page isn't placed in the
+ * navigation (then without breadcrumbs and neighbours).
+ */
+interface HelpPublicPreviewPage extends Omit<HelpPublicPage, "path"> {
+    path: string | null;
+    status: "draft" | "published" | "archived";
+    visibility: "public" | "internal";
+}
+/** `GET preview?token=&lang=` — never cached. */
+interface HelpPublicPreviewPayload {
+    page: HelpPublicPreviewPage;
+}
+/** One search hit. Title hits rank above heading hits above text hits. */
+interface HelpPublicSearchHit {
+    path: string;
+    title: string;
+    description: string | null;
+    /** Plain text around the first match (escape it before putting it into HTML). */
+    excerpt: string;
+    /** The best matching heading, for a `path#id` link. */
+    heading: {
+        id: string;
+        text: string;
+    } | null;
+    /** The page on the docs website, null without a website address. */
+    url: string | null;
+}
+/** `GET search?q=&lang=&limit=` — at most 20 hits, best first. */
+interface HelpPublicSearchPayload {
+    query: string;
+    locale: string;
+    languages: string[];
+    hits: HelpPublicSearchHit[];
+}
+/** What a help webhook announces. */
+type HelpWebhookEvent = "page.published" | "page.updated" | "page.unpublished" | "page.deleted" | "navigation.updated" | "ping";
+/** The body of a help webhook call (verify it first — see `verifyHelpWebhook`). */
+interface HelpWebhookBody {
+    event: HelpWebhookEvent;
+    /** The workspace slug, as in the public API path. */
+    workspace: string;
+    /** The doc site's slug, as in the public API path. */
+    site: string;
+    /** The page's path (null for `navigation.updated` and `ping`). */
+    path: string | null;
+    /** Earlier paths — their pages are stale too (for `navigation.updated`: every path that moved). */
+    previousPaths: string[];
+    /** The languages the page is offered in after the change (the site's for navigation). */
+    locales: string[];
+    occurredAt: string;
+}
+
+/**
+ * Parsing the help center's Markdown the way the API renders it
+ * (`packages/db/src/help-markdown.ts`): GFM plus container directives in the
+ * generic syntax of `remark-directive`. Only the directive names below mean
+ * something, plus the site's own blocks (`blocks.ts`); every other directive
+ * is printed back as the text it was written as.
+ */
+/** The directive names the help center knows. */
+declare const HELP_BLOCKS: readonly ["callout", "steps", "step", "tabs", "tab", "cards", "card"];
+type HelpBlockName = (typeof HELP_BLOCKS)[number];
+/** `callout` types (anything else is shown as `info`). */
+declare const HELP_CALLOUT_TYPES: readonly ["info", "warn", "error", "success", "idea"];
+type HelpCalloutType = (typeof HELP_CALLOUT_TYPES)[number];
+/**
+ * The link target if it is one a reader may follow (http(s), mailto, `/path`,
+ * `#anchor`), else null. The same rule as the API's `safeMarkdownHref`:
+ *
+ * 1. Surrounding whitespace is trimmed.
+ * 2. Any ASCII control character anywhere → unsafe.
+ * 3. A target starting with `//`, `/\`, `\/` or `\\` (protocol-relative) → unsafe.
+ * 4. Otherwise allowed: `http://…` / `https://…`, `mailto:…`, `/…` and `#…`,
+ *    each without whitespace inside.
+ */
+declare function safeHelpHref(raw: string | null | undefined): string | null;
+
+/**
+ * A doc site's own building blocks (`site.blocks`) in the page Markdown — the
+ * same rules as the API (`packages/db/src/help-blocks.ts`, `help-markdown.ts`,
+ * contract in `docs/help/06-eigene-bausteine.md`), copied so the package has no
+ * dependency on the API's code; `test/blocks.test.tsx` holds both in step.
+ *
+ * The Markdown parser (micromark's directive extension) finds the directives;
+ * a use only counts when its name is defined, it is written in its kind's form
+ * (`:name` inline, `::name` alone on a line, `:::name` around content) and its
+ * source re-reads under the API's stricter syntax (label and attributes on one
+ * line, the basic character references) — otherwise it stays literal text.
+ */
+/** A field's checked value: `boolean` fields are true/false, every other type a string. */
+type HelpBlockValue = string | boolean;
+/** A block's checked field values, in the definition's field order. */
+type HelpBlockValues = Record<string, HelpBlockValue>;
+/**
+ * A block's attributes as checked field values, by the API's rules: only
+ * defined fields; an absent `boolean` is `false`; an empty value counts as
+ * absent; invalid values (a `javascript:` link, a malformed icon, a choice
+ * not offered) and attributes without a field are left out.
+ */
+declare function helpBlockValues(block: Pick<HelpPublicBlockDefinition, "fields">, attributes: Readonly<Record<string, string>>): HelpBlockValues;
+/**
+ * A block's text version: its template with every `{key}` replaced by the
+ * field's value (a `boolean` by its label when on, else nothing; a missing
+ * value by nothing), `{{`/`}}` as braces, then `label` after a space;
+ * whitespace collapsed. What `HelpBody` shows without a component, and what
+ * search and the outline read.
+ */
+declare function helpBlockText(block: Pick<HelpPublicBlockDefinition, "fields" | "text">, values: Readonly<HelpBlockValues>, label?: string): string;
+
+interface HelpCalloutProps {
+    /** `info`, `warn`, `error`, `success` or `idea` (an unknown type arrives as `info`). */
+    type: HelpCalloutType;
+    title?: string;
+    children: ReactNode;
+}
+interface HelpStepsProps {
+    children: ReactNode;
+}
+interface HelpStepProps {
+    title?: string;
+    /** The title's anchor id (a step's title is a heading of the page, level 3). */
+    id?: string;
+    children: ReactNode;
+}
+interface HelpTabsProps {
+    /** The tab titles, in order (unique). */
+    items: string[];
+    children: ReactNode;
+}
+interface HelpTabProps {
+    /** The tab's entry in `items`. */
+    value: string;
+    children: ReactNode;
+}
+interface HelpCardsProps {
+    children: ReactNode;
+}
+interface HelpCardProps {
+    title: string;
+    /** A safe link target (http(s), mailto, `/path`, `#anchor`), else absent. */
+    href?: string;
+    /** The rendered icon (see `HelpBodyProps.icon`). */
+    icon?: ReactNode;
+    children: ReactNode;
+}
+interface HelpCodeProps {
+    code: string;
+    /** The fence's language (`ts`), if any. */
+    lang?: string;
+    /** `title="…"` of the fence, if any. */
+    title?: string;
+}
+interface HelpHeadingProps {
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    /** The anchor id (the same the API's `headings` name). */
+    id: string;
+    children: ReactNode;
+}
+interface HelpLinkProps {
+    /** Already checked: http(s), mailto, `/path` or `#anchor`. */
+    href: string;
+    title?: string;
+    children: ReactNode;
+}
+interface HelpImageProps {
+    src: string;
+    alt: string;
+    title?: string;
+}
+/** A field value of a site's own block, as its component receives it. */
+type HelpBlockFieldValue = string | boolean | undefined;
+/**
+ * The props of a component for one of the site's own blocks
+ * (`docs/help/06`). `Fields` names the block's fields: a `boolean` field is
+ * always there (`true`/`false`); any other field is a string, or absent when
+ * the page leaves it out or its value isn't valid (a `javascript:` link, an
+ * icon name that isn't one, a choice not offered) — even a required one, so
+ * every field is optional here.
+ *
+ * @example
+ * type AppButtonProps = HelpBlockProps<{ icon: string; label: string }>;
+ * function AppButton({ icon, label, children, lang }: AppButtonProps) { … }
+ */
+type HelpBlockProps<Fields extends {
+    [K in keyof Fields]: HelpBlockFieldValue;
+} = Record<never, never>> = {
+    [K in Exclude<keyof Fields, "block" | "lang" | "children">]?: Fields[K];
+} & {
+    /** The block's name (`app-button`). */
+    block: string;
+    /** The page's language (`page.locale`, or `HelpBody`'s `lang`). */
+    lang: string;
+    /**
+     * `inline`/`block`: the `[label]` (rendered Markdown), if written;
+     * `container`: the rendered content — built-in and own blocks included.
+     */
+    children?: ReactNode;
+};
+/**
+ * A component for a site's own block. Typed loosely so any component fits;
+ * type yours with {@link HelpBlockProps}.
+ */
+type HelpBlockComponent = JSXElementConstructor<never>;
+/** Everything `HelpBody` renders through a component — replace any of them. */
+interface HelpBodyComponents {
+    Callout: ComponentType<HelpCalloutProps>;
+    Steps: ComponentType<HelpStepsProps>;
+    Step: ComponentType<HelpStepProps>;
+    Tabs: ComponentType<HelpTabsProps>;
+    Tab: ComponentType<HelpTabProps>;
+    Cards: ComponentType<HelpCardsProps>;
+    Card: ComponentType<HelpCardProps>;
+    /** A code fence — e.g. swap in Fumadocs' `DynamicCodeBlock` for syntax highlighting. */
+    Code: ComponentType<HelpCodeProps>;
+    Heading: ComponentType<HelpHeadingProps>;
+    Link: ComponentType<HelpLinkProps>;
+    Image: ComponentType<HelpImageProps>;
+}
+/** The Fumadocs UI defaults. */
+declare const helpBodyComponents: HelpBodyComponents;
+/**
+ * `HelpBody`'s components: any of the built-in ones by their (capitalised)
+ * name, and a component per site block by the block's name (`app-button`).
+ */
+interface HelpBodyComponentMap extends Partial<HelpBodyComponents> {
+    [block: string]: HelpBlockComponent | undefined;
+}
+interface HelpBodyProps {
+    /**
+     * The page from the API (`page.data.load()`, `help.page()`, `help.preview()`):
+     * its `markdown`, `headings` and `locale` (passed to block components as
+     * `lang`). Or pass `markdown` (and `headings`, `lang`) yourself.
+     */
+    page?: {
+        markdown: string;
+        headings?: readonly HelpPublicHeading[];
+        locale?: string;
+    };
+    /** The page's Markdown with directives (`page.markdown` from the API); wins over `page`. */
+    markdown?: string;
+    /**
+     * The page's `headings` from the API: their ids become the headings' anchors,
+     * so they always match `getHelpToc(page.headings)`. Without them the ids are
+     * computed the API's way.
+     */
+    headings?: readonly HelpPublicHeading[];
+    /** The page's language for block components (default `page.locale`, else `""`). */
+    lang?: string;
+    /**
+     * The site's own blocks (`page.data.blocks` of a help source, or
+     * `site.blocks` from `help.site()`). Without them every such directive stays
+     * the text it was written as.
+     */
+    blocks?: readonly HelpPublicBlockDefinition[];
+    /**
+     * Replace any of the default Fumadocs UI components (`Callout`, `Code`, …),
+     * and render the site's own blocks with your components, keyed by the
+     * block's name: `{ "app-button": AppButton }`. A defined block without a
+     * component shows its text version.
+     */
+    components?: HelpBodyComponentMap;
+    /**
+     * Turn a card's Lucide icon name (`Rocket`) into an element, e.g. with
+     * `lucide-react`: `(name) => { const Icon = icons[name as keyof typeof icons]; return Icon ? <Icon /> : null; }`.
+     * Without it cards show no icon.
+     */
+    icon?: (name: string) => ReactNode;
+}
+/**
+ * A help page's Markdown with its blocks (callout, steps, tabs, cards, titled
+ * code fences) as Fumadocs UI components — a React Server Component, also fine
+ * on the client. The site's own blocks (`blocks`) render with your
+ * `components`, or as their text version. The API's safety rules apply: raw
+ * HTML is shown as text, links only to http(s), mailto, `/paths` and
+ * `#anchors`, images only from http(s) or `/paths`; unknown directives stay
+ * the text they were written as.
+ *
+ * @example
+ * const entry = source.getPage(slugs);
+ * const page = await entry.data.load();
+ * <DocsBody>
+ *   <HelpBody page={page} blocks={entry.data.blocks} components={{ "app-button": AppButton }} />
+ * </DocsBody>
+ */
+declare function HelpBody(props: HelpBodyProps): ReactNode;
+
+/** Per-call options. */
+interface RequestOptions {
+    /** Cancels the request (an `AbortSignal`). */
+    signal?: unknown;
+    /** Extra headers for this request. */
+    headers?: Record<string, string>;
+    /**
+     * Extra `fetch` options for this request, passed through unchanged — e.g.
+     * Next.js `{ next: { revalidate: 60, tags: ["legal"] } }` or `{ cache: "no-store" }`.
+     */
+    fetchOptions?: Record<string, unknown>;
+}
+
+interface VerifyWebhookOptions {
+    /** How old (or how far in the future) the signed time may be. Default 300 (5 minutes). */
+    toleranceSeconds?: number;
+    /** "Now" in milliseconds (or a `Date`) — for tests. Default `Date.now()`. */
+    now?: number | Date;
+    /**
+     * A Web Crypto implementation. Default `globalThis.crypto`. On Node 18 pass
+     * `require("node:crypto").webcrypto` (Node 19+ has it globally).
+     */
+    crypto?: {
+        subtle: object;
+    };
+}
+
+interface HelpRevalidateOptions {
+    /** The webhook's signing secret (`whsec_…`), shown once in SolutionDesk. */
+    secret: string;
+    /**
+     * Called with every verified change (not for `ping`, the test call) —
+     * e.g. `revalidateTag("solutiondesk-help")` in Next.js. Throwing answers
+     * `500`, so SolutionDesk retries the call.
+     */
+    revalidate: (body: HelpWebhookBody) => unknown;
+    /** Also call `revalidate` for `ping` (default false). */
+    includePing?: boolean;
+    /** For tests: the signature check's options (clock, Web Crypto). */
+    verifyOptions?: VerifyWebhookOptions;
+}
+/** The request parts the handler reads — what every `Request` has. */
+interface HelpWebhookRequest {
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/**
+ * A webhook endpoint for any framework with `Request`/`Response` (Next.js
+ * route handlers, Remix, Astro, Hono, Bun, Deno …): checks the
+ * `X-SolutionDesk-Signature`, then calls `revalidate`. Answers `204` when
+ * done, `401` for a wrong, missing or expired signature, `400` for a signed
+ * body that isn't a help webhook, `500` while no secret is set.
+ *
+ * @example
+ * // app/api/solutiondesk/help/route.ts
+ * import { revalidateTag } from "next/cache";
+ * export const POST = createHelpRevalidateHandler({
+ *   secret: process.env.SOLUTIONDESK_HELP_WEBHOOK_SECRET!,
+ *   revalidate: () => revalidateTag("solutiondesk-help", "max"),
+ * });
+ */
+declare function createHelpRevalidateHandler(options: HelpRevalidateOptions): (request: HelpWebhookRequest) => Promise<Response>;
+
+interface LangParams {
+    /** The language to ask for; overrides the client's `lang`. */
+    lang?: string;
+}
+interface GetPageParams extends LangParams {
+    /**
+     * What to do when the path is an earlier address of a page (the API answers
+     * `301` with `{ redirectTo }`):
+     * - `"follow"` (default): return the page; `movedFrom` holds the path you asked for.
+     * - `"manual"`: return `{ redirectTo }` with the current path instead.
+     */
+    redirect?: "follow" | "manual";
+}
+interface SearchParams extends LangParams {
+    /** At most this many hits, 1–20 (default 20). */
+    limit?: number;
+}
+/** A page fetched with `redirect: "follow"`. */
+interface HelpPageResult extends HelpPublicPagePayload {
+    /**
+     * The path you asked for when the page has moved to `page.path` since
+     * (redirect your page there, e.g. with a 301); null when it hasn't.
+     */
+    movedFrom: string | null;
+}
+interface HelpClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /** The doc site this client reads (its slug). */
+    readonly siteSlug: string;
+    /** The site and its navigation tree in one language (`GET …/site`). */
+    site(params?: LangParams, options?: RequestOptions): Promise<HelpPublicSitePayload>;
+    /** Every visible page without its text, in reading order (`GET …/pages`) — builds and sitemaps. */
+    pages(params?: LangParams, options?: RequestOptions): Promise<HelpPublicPagesPayload>;
+    /**
+     * One visible page with its Markdown, HTML, headings, breadcrumbs and
+     * neighbours (`GET …/page?path=`). The home page has the path `""`.
+     * Throws a `SolutionDeskError` with status 404 for an unknown or hidden page.
+     */
+    page(path: string, params?: GetPageParams & {
+        redirect?: "follow";
+    }, options?: RequestOptions): Promise<HelpPageResult>;
+    page(path: string, params: GetPageParams & {
+        redirect: "manual";
+    }, options?: RequestOptions): Promise<HelpPublicPagePayload | HelpPublicRedirect>;
+    /** One visible page as plain Markdown (`GET …/page.md?path=`), title and source on top. */
+    pageMarkdown(path: string, params?: LangParams, options?: RequestOptions): Promise<string>;
+    /** Search the visible pages (`GET …/search?q=`): title hits before heading hits before text hits. */
+    search(query: string, params?: SearchParams, options?: RequestOptions): Promise<HelpPublicSearchPayload>;
+    /**
+     * The current state of a page (also a draft or an internal page) for your
+     * preview route — the `token` from your preview address (valid for one hour).
+     * The API sends it with `Cache-Control: no-store`; in Next.js also pass
+     * `fetchOptions: { cache: "no-store" }`.
+     */
+    preview(token: string, params?: LangParams, options?: RequestOptions): Promise<HelpPublicPreviewPayload>;
+    /** The site's index in the llms.txt format (`GET …/llms.txt`). */
+    llmsTxt(params?: LangParams, options?: RequestOptions): Promise<string>;
+    /** Every visible page as Markdown, one after the other (`GET …/llms-full.txt`). */
+    llmsFullTxt(params?: LangParams, options?: RequestOptions): Promise<string>;
+}
+
+/** Fumadocs' search data of a page (the shape of `remark-structure`). */
+interface HelpStructuredData {
+    headings: {
+        id: string;
+        content: string;
+    }[];
+    contents: {
+        heading: string | undefined;
+        content: string;
+    }[];
+}
+/**
+ * A page's search data for Fumadocs (`createFromSource`): every heading with
+ * its anchor, and every paragraph, quote and table cell under the heading it
+ * belongs to — code is left out, as in Fumadocs' own `remark-structure`. The
+ * site's own `blocks` count as their text version (like the API's search): a
+ * container's text version is an entry of its own, followed by its content.
+ */
+declare function helpStructuredData(markdown: string, headings?: readonly HelpPublicHeading[], blocks?: readonly HelpPublicBlockDefinition[]): HelpStructuredData;
+
+/** What every page of a help source carries in `page.data`. */
+interface HelpPageData extends PageData {
+    title: string;
+    description?: string;
+    /** A Lucide icon name (`BookOpen`) — add `lucideIconsPlugin()` to `loader()` to render it. */
+    icon?: string;
+    /** The page's path in the help center (`guides/login`, `""` for the home page). */
+    path: string;
+    /** The language this file was built for (the `lang` asked for; the API falls back per page). */
+    lang: string;
+    /**
+     * The site's own building blocks (`site.blocks`) — pass them to `HelpBody`
+     * (`blocks={page.data.blocks}`) so pages render them with your components.
+     */
+    blocks: HelpPublicBlockDefinition[];
+    /**
+     * The page with its text (`markdown`, `html`, `headings`, `breadcrumbs`,
+     * `previous`/`next`). Fetched when called — or right away with
+     * `pages: "eager"`, then it resolves to the prefetched page.
+     * `null` when the page is gone (taken offline since the source was built,
+     * the API answers 404) — render your framework's 404, e.g. `notFound()`.
+     */
+    load: () => Promise<HelpPublicPage | null>;
+    /**
+     * Fumadocs search (`createFromSource`) reads this; built from the page's
+     * Markdown. Empty for a page that is gone, so one missing page doesn't
+     * break the search index.
+     */
+    structuredData: () => Promise<HelpStructuredData>;
+    /** The page with its text — only with `pages: "eager"`. */
+    page?: HelpPublicPage;
+}
+/** What every folder's `meta.json` of a help source carries. */
+interface HelpMetaData extends MetaData {
+    title?: string;
+    /** Shown under a tab's name in Fumadocs' tab menu. */
+    description?: string;
+    icon?: string;
+    root?: boolean;
+    defaultOpen?: boolean;
+    collapsible?: boolean;
+    pages: string[];
+    pagesIndex?: string;
+}
+type HelpSourceConfig = {
+    pageData: HelpPageData;
+    metaData: HelpMetaData;
+};
+type HelpSource = StaticSource<HelpSourceConfig>;
+type HelpVirtualFile = VirtualFile<HelpSourceConfig>;
+interface HelpSourceOptions {
+    /**
+     * Build one set of files per language, for a `loader()` with `i18n` (the
+     * default `dot` parser: `guides/login.en.mdx`, `guides/meta.en.json`). Use
+     * exactly the `languages` of your `defineI18n()` config. Without it the
+     * source holds one language — the client's `lang`, else the site's main
+     * language — and file names carry no language.
+     */
+    languages?: readonly string[];
+    /**
+     * `"lazy"` (default): only the navigation is fetched (one request per
+     * language); a page's text is fetched when `page.data.load()` is called —
+     * cheap to build, one request per rendered page (cache it with your
+     * framework's fetch cache, see `requestOptions`).
+     * `"eager"`: every page is fetched while building (bounded by `concurrency`)
+     * and kept in `page.data.page` — slower to build, nothing fetched later;
+     * best for fully static exports.
+     */
+    pages?: "lazy" | "eager";
+    /** With `pages: "eager"`: at most this many page requests at once (default 6). */
+    concurrency?: number;
+    /**
+     * Passed to every request, e.g. Next.js
+     * `{ fetchOptions: { next: { tags: ["solutiondesk-help"], revalidate: 300 } } }`.
+     */
+    requestOptions?: RequestOptions;
+}
+/**
+ * The entry of a tree node in its folder's `meta.json` `pages` (Fumadocs
+ * syntax): a page or folder name, `---[Icon]Title---`, `[Icon][Title](url)`,
+ * `external:[Title](url)`.
+ */
+declare function helpMetaEntry(node: HelpPublicTreeNode): string;
+interface HelpFilesOptions {
+    /** Append `.<lang>` to every file name (Fumadocs' `dot` i18n parser). */
+    suffix?: string;
+    /** The language the files are for (`page.data.lang`). */
+    lang: string;
+    /** Loads a page's text (`page.data.load`); `null` when the page is gone. */
+    load: (path: string) => Promise<HelpPublicPage | null>;
+    /** Prefetched pages by path (`pages: "eager"`); `null` for a page that was gone. */
+    prefetched?: ReadonlyMap<string, HelpPublicPage | null>;
+}
+/**
+ * The Fumadocs virtual files for one language of the site: a `.mdx` page file
+ * per page (a folder's own page as `<folder>/index.mdx`, the home page as
+ * `index.mdx` at the top or in a top-level group, any other page named `index`
+ * as `index_.mdx`) and a `meta.json` per folder plus one at the top that fixes
+ * the order. A group folder is a `(slug)/` directory, so Fumadocs gives its
+ * pages the same addresses as the tree (no segment for the group). Every file
+ * path is unique. Exported for custom setups; `createHelpSource` uses it.
+ */
+declare function helpTreeToFiles(payload: HelpPublicSitePayload, options: HelpFilesOptions): HelpVirtualFile[];
+/** Every page path of a tree (index pages included), in reading order. */
+declare function helpTreePaths(tree: readonly HelpPublicTreeNode[]): string[];
+/**
+ * A Fumadocs source of a help site, for `loader()`:
+ *
+ * ```ts
+ * const help = createHelpClient({ workspace: "acme", site: "docs" });
+ * export const source = loader({ baseUrl: "/docs", source: await createHelpSource(help) });
+ * ```
+ *
+ * One `site` request per language builds the navigation; texts come with
+ * `page.data.load()` (or all at once with `pages: "eager"`). The tree is a
+ * snapshot — rebuild the loader to pick up changes (see the README).
+ */
+declare function createHelpSource(client: HelpClient, options?: HelpSourceOptions): Promise<HelpSource>;
+/**
+ * The same as a Fumadocs dynamic source, for `dynamicLoader()` from
+ * `fumadocs-core/source/dynamic`: built on first use, rebuilt after
+ * `loader.revalidate()` (e.g. from your webhook route).
+ */
+declare function helpDynamicSource(client: HelpClient, options?: HelpSourceOptions): DynamicSource<HelpSourceConfig>;
+
+interface HelpTocOptions {
+    /** Leave out headings below this level (default 1 — all). */
+    minLevel?: number;
+    /** Leave out headings above this level (default 6 — all). */
+    maxLevel?: number;
+}
+/**
+ * The page's table of contents for Fumadocs (`<DocsPage toc={…}>`), from the
+ * API's `headings` — the same ids `HelpBody` gives the headings.
+ */
+declare function getHelpToc(headings: readonly HelpPublicHeading[] | {
+    headings: readonly HelpPublicHeading[];
+}, options?: HelpTocOptions): TOCItemType[];
+
+export { HELP_BLOCKS, HELP_CALLOUT_TYPES, type HelpBlockComponent, type HelpBlockFieldValue, type HelpBlockName, type HelpBlockProps, type HelpBlockValue, type HelpBlockValues, HelpBody, type HelpBodyComponentMap, type HelpBodyComponents, type HelpBodyProps, type HelpCalloutProps, type HelpCalloutType, type HelpCardProps, type HelpCardsProps, type HelpCodeProps, type HelpFilesOptions, type HelpHeadingProps, type HelpImageProps, type HelpLinkProps, type HelpMetaData, type HelpPageData, type HelpRevalidateOptions, type HelpSource, type HelpSourceConfig, type HelpSourceOptions, type HelpStepProps, type HelpStepsProps, type HelpStructuredData, type HelpTabProps, type HelpTabsProps, type HelpTocOptions, type HelpVirtualFile, type HelpWebhookRequest, createHelpRevalidateHandler, createHelpSource, getHelpToc, helpBlockText, helpBlockValues, helpBodyComponents, helpDynamicSource, helpMetaEntry, helpStructuredData, helpTreePaths, helpTreeToFiles, safeHelpHref };