@solutiondesk/help 0.0.0 → 1.0.0-239896d

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wemogy GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,299 @@
 # @solutiondesk/help
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Typed client for the public [SolutionDesk](https://solutiondesk.io) help center API, plus a ready-made adapter for [Fumadocs](https://fumadocs.dev). Your team writes the documentation in SolutionDesk; your docs website reads it with this package.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+- The client has no dependencies: ESM and CommonJS, full TypeScript types, Node.js 18+, Deno, Bun, edge runtimes and browsers.
+- No key and no login: the API only ever returns pages that are published, public and placed in the navigation.
+- `@solutiondesk/help/fumadocs` turns a help site into a Fumadocs source and renders its pages with Fumadocs UI.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @solutiondesk/help
+```
 
-## Purpose
+The guide [Help center on your website](https://help.solutiondesk.io/docs/team/help-center-website) explains the API behind this package and where to set it up in SolutionDesk.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@solutiondesk/help`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Quick start
 
-## What is OIDC Trusted Publishing?
+```ts
+import { createHelpClient } from "@solutiondesk/help";
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+const help = createHelpClient({ workspace: "acme", site: "docs", lang: "en" });
 
-## Setup Instructions
+const { site, tree } = await help.site(); // the navigation
+const { page } = await help.page("guides/login"); // one page with its text
+```
 
-To properly configure OIDC trusted publishing for this package:
+`workspace` is your workspace's slug and `site` the doc site's slug, the `acme` and `docs` in `https://api.solutiondesk.io/v1/help/acme/docs`.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+## What you can read
 
-## DO NOT USE THIS PACKAGE
+| Method | API | Returns |
+| --- | --- | --- |
+| `site({ lang })` | `GET …/site` | The site (`name`, `languages`, `websiteUrl`, its own building `blocks`) and its navigation tree: pages, folders (with index page, `listIndex`, `root` tab, `description`, `group`, `defaultOpen`, `collapsible`), separators and links. Empty folders are left out. |
+| `pages({ lang })` | `GET …/pages` | Every visible page without its text, in reading order (for builds and sitemaps). |
+| `page(path, { lang, redirect })` | `GET …/page?path=` | One page: `markdown`, `html`, `headings`, `blocks`, `customBlocks`, `breadcrumbs`, `previous`/`next`. The home page has the path `""`. |
+| `pageMarkdown(path, { lang })` | `GET …/page.md?path=` | One page as plain Markdown. |
+| `search(query, { lang, limit })` | `GET …/search?q=` | Up to 20 hits: title hits before heading hits before text hits, with an `excerpt` and the best `heading`. |
+| `preview(token, { lang })` | `GET …/preview?token=` | A page in any state (drafts too) for your preview route. |
+| `llmsTxt({ lang })` / `llmsFullTxt({ lang })` | `GET …/llms.txt`, `…/llms-full.txt` | The site for language models: the index, or every page as Markdown. |
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+`html` is safe to insert as it is: raw HTML in the Markdown is shown as text, links only go to web addresses, `mailto:`, paths and anchors, images only come from your help center. Headings carry the `id`s listed in `headings`, made the way GitHub and Fumadocs make them (umlauts kept, `-1` for a repeat), so a site moved from Fumadocs keeps its `#links`; a step's title is a heading too.
 
-## More Information
+### Moved pages
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+When the team renames or moves a page, its old path answers with a `301` to the new one.
 
----
+- Default (`redirect: "follow"`): you get the page; `movedFrom` holds the path you asked for (else `null`). Redirect your visitor to `page.path`.
+- `redirect: "manual"`: you get `{ redirectTo: "new/path" }` instead.
 
-**Maintained for OIDC setup purposes only**
+### Languages
+
+Pass `lang` to the client (default for every call) or per call. A page that doesn't exist in that language comes in the site's main language. Every answer names the language it is really in (`locale`) and the site's languages (`languages`, main language first).
+
+### Errors, caching, options
+
+Every failed request rejects with a `SolutionDeskError` (`status`, `message`, `body`, `url`, `isNotFound`, `isRateLimited`); `status` is `0` when no answer arrived. A missing page, a hidden page, a turned-off module and an unknown site all answer `404`, on purpose alike.
+
+Answers carry `Cache-Control: public, max-age=60, must-revalidate` and an `ETag`. `etagCache: true` makes the client revalidate with `If-None-Match`. Per call, `fetchOptions` goes to `fetch` unchanged, e.g. Next.js `{ next: { tags: ["solutiondesk-help"], revalidate: 3600 } }` or `{ cache: "no-store" }` for previews.
+
+```ts
+createHelpClient({
+  workspace: "acme", // required
+  site: "docs", // required
+  lang: "en", // default language
+  baseUrl: "https://api.solutiondesk.io", // the API origin
+  fetch: customFetch,
+  headers: { "x-request-id": "…" },
+  etagCache: true,
+});
+```
+
+## Fumadocs
+
+`@solutiondesk/help/fumadocs` needs `fumadocs-core`, `fumadocs-ui` (16.x) and `react` 19, which a Fumadocs site has anyway. It is ESM only and tested against Fumadocs 16.14.
+
+### The source
+
+```ts
+// lib/help.ts
+import { createHelpClient } from "@solutiondesk/help";
+import { createHelpSource } from "@solutiondesk/help/fumadocs";
+import { loader } from "fumadocs-core/source";
+import { lucideIconsPlugin } from "fumadocs-core/source/plugins/lucide-icons";
+import { cache } from "react";
+
+export const HELP_TAG = "solutiondesk-help";
+export const help = createHelpClient({ workspace: "acme", site: "docs" });
+
+// Built per request from the cached navigation: after the webhook revalidates
+// the tag, the next request sees the new tree.
+export const getSource = cache(async () =>
+  loader({
+    baseUrl: "/docs",
+    source: await createHelpSource(help, {
+      requestOptions: { fetchOptions: { next: { tags: [HELP_TAG], revalidate: 3600 } } },
+    }),
+    plugins: [lucideIconsPlugin()], // the icons are Lucide names
+  }),
+);
+```
+
+The navigation becomes the files Fumadocs knows from a content folder:
+
+| SolutionDesk | Fumadocs |
+| --- | --- |
+| page `guides/login` | `guides/login.mdx` (`slugs: ["guides", "login"]`) |
+| home page | `index.mdx` at the top, or `(core)/index.mdx` when it is a top-level group's own page |
+| folder `guides` | `guides/meta.json` with `title`, `description` (shown under a tab's name), `pagesIndex` — or, with `listIndex`, `"index"` first in `pages` (after a leading separator), so the page is an entry and the name only opens the folder —, `icon`, `root`, `defaultOpen`, `collapsible`, `pages` |
+| group folder `core` (adds no address part) | `(core)/` — a Fumadocs folder group, so `(core)/sign-up/index.mdx` is still `sign-up` |
+| folder's own page | `guides/index.mdx` (`pagesIndex: "index"`, so it also works for `root` tabs) |
+| any other page with the slug `index` | `guides/index_.mdx` (`slugs: ["guides", "index"]`), so it never collides with the folder's own page |
+| order of the top level | `meta.json` (`title` = site name) |
+| separator | `"---[Icon]Title---"` (a separator without a title is `"---"`) |
+| link | `"[Icon][Title](url)"`, `"external:[Icon][Title](url)"` |
+
+Every page's `data` holds `title`, `description`, `icon`, `path`, `lang`, `blocks` (the site's own building blocks, for `HelpBody`), `load()` (the page with its text, or `null` when the page was taken offline after the source was built — answer with a 404) and `structuredData()` (for Fumadocs search; empty for such a page, so it never breaks the search index).
+
+**Lazy or eager.** The page list has no texts, so by default (`pages: "lazy"`) building the source costs one request per language, and `page.data.load()` fetches a page's text when it is rendered. Cache that with your framework (the tags above). With `pages: "eager"` every page is fetched while building (`concurrency`, default 6) and kept in `page.data.page`: slower to build, nothing fetched later, best for a fully static export.
+
+**Several languages.** Pass the languages of your Fumadocs i18n config. The source then holds one set of files per language with Fumadocs' default `dot` naming (`guides/login.en.mdx`, `guides/meta.en.json`):
+
+```ts
+loader({
+  baseUrl: "/docs",
+  i18n: defineI18n({ languages: ["de", "en"], defaultLanguage: "de" }),
+  source: await createHelpSource(help, { languages: ["de", "en"] }),
+});
+```
+
+`helpDynamicSource(help, options)` is the same for `dynamicLoader()` from `fumadocs-core/source/dynamic`.
+
+### The page
+
+```tsx
+// app/docs/[[...slug]]/page.tsx
+import { getHelpToc, HelpBody } from "@solutiondesk/help/fumadocs";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
+import { icons } from "lucide-react";
+import { notFound } from "next/navigation";
+import { getSource } from "@/lib/help";
+
+const icon = (name: string) => {
+  const Icon = icons[name as keyof typeof icons];
+  return Icon ? <Icon /> : null;
+};
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const entry = (await getSource()).getPage((await params).slug);
+  if (!entry) notFound();
+  const page = await entry.data.load();
+  if (!page) notFound(); // taken offline since the navigation was cached
+  return (
+    <DocsPage toc={getHelpToc(page.headings)}>
+      <DocsTitle>{page.title}</DocsTitle>
+      <DocsDescription>{page.description}</DocsDescription>
+      <DocsBody>
+        <HelpBody page={page} blocks={entry.data.blocks} icon={icon} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return (await getSource()).generateParams();
+}
+```
+
+`page` gives `HelpBody` the page's `markdown`, `headings` and `locale`; you can also pass `markdown`, `headings` and `lang` yourself. `HelpBody` renders the Markdown with Fumadocs UI: `:::callout` → `Callout`, `::::steps`/`:::step` → `Steps`/`Step`, `::::tabs`/`:::tab` → `Tabs`/`Tab`, `::::cards`/`:::card` → `Cards`/`Card`, a code fence with `title="…"` → `CodeBlock`. Pass `headings` (or `page`) so the anchors match `getHelpToc`. Replace any part with `components`, for example syntax highlighting:
+
+```tsx
+import { DynamicCodeBlock } from "fumadocs-ui/components/dynamic-codeblock";
+
+<HelpBody
+  page={page}
+  components={{ Code: ({ code, lang, title }) => <DynamicCodeBlock lang={lang ?? "text"} code={code} codeblock={{ title }} /> }}
+/>;
+```
+
+The same safety rules as the API's `html` apply: raw HTML is shown as text, links only go to `http(s)`, `mailto:`, `/paths` and `#anchors`, images only come from `http(s)` or `/paths` — never to another host through `//`, `/\`, `\\` or control characters hidden in the address. A directive SolutionDesk doesn't know stays the text it was written as.
+
+### Your own building blocks
+
+In SolutionDesk, a doc site can define its own building blocks: what a block is called, whether it sits in a sentence, on its own line or around content, and which fields it has. How it looks is up to your website. Map each block's name to one of your components:
+
+```tsx
+import { type HelpBlockProps, HelpBody } from "@solutiondesk/help/fumadocs";
+import { icons } from "lucide-react";
+
+// :app-button{icon="Palette" label="Your team"} — in a sentence
+function AppButton({ icon, label }: HelpBlockProps<{ icon: string; label: string }>) {
+  const Icon = icon ? icons[icon as keyof typeof icons] : undefined;
+  return <kbd className="app-button">{Icon ? <Icon /> : null}{label}</kbd>;
+}
+
+// ::paid-addon{name="Events"} — on its own line
+function PaidAddon({ name, lang }: HelpBlockProps<{ name: string }>) {
+  return <aside className="paid-addon">{lang === "de" ? "Kostenpflichtig" : "Paid add-on"}: {name}</aside>;
+}
+
+// :::download-buttons{title="UXP installer" versionsHref="#versions"} … ::: — around content
+function DownloadButtons({ title, versionsHref, children }: HelpBlockProps<{ title: string; versionsHref: string }>) {
+  return (
+    <section className="downloads">
+      <h4>{title}</h4>
+      {children}
+      {versionsHref ? <a href={versionsHref}>Older versions</a> : null}
+    </section>
+  );
+}
+
+<HelpBody
+  page={page}
+  blocks={entry.data.blocks} // or `site.blocks` from `help.site()`
+  components={{ "app-button": AppButton, "paid-addon": PaidAddon, "download-buttons": DownloadButtons }}
+/>;
+```
+
+A component gets:
+
+- the block's **fields**, already checked the way SolutionDesk checks them: text fields as strings, on/off fields as `true`/`false`. A value that isn't valid (an unsafe address such as `javascript:`, a picture or video address that isn't allowed, an icon name that isn't one, an option that isn't offered) is left out, so every field may be missing — `HelpBlockProps<Fields>` types them as optional.
+- `lang`: the page's language (`page.locale`, or the `lang` you pass) — no need to store it in the block.
+- `block`: the block's name.
+- `children`: for a block in a sentence or on its own line, its text in `[brackets]` (`:app-button[Share]{icon="Share2"}`); for a block around content, that content, rendered like the rest of the page (built-in and own blocks inside included).
+
+`block`, `lang` and `children` always mean the above; SolutionDesk doesn't allow fields with these names. A block the site defines but you have no component for shows its **text version** (set in SolutionDesk, e.g. `Paid add-on: Events`) in a neutral `<span class="sd-block" data-block="…" data-props="…">` (in a sentence) or `<div class="sd-block">` (on its own line; around content with `<p class="sd-block-text">` and `<div class="sd-block-body">`) — the same as the API's `html`. A name the site doesn't define, or a block written in the wrong form, stays the text it was written as. Without `blocks`, every one of them stays text. Search data (`structuredData()`) and heading anchors use the text version as well, like the API's search.
+
+`helpBlockValues(definition, attributes)` and `helpBlockText(definition, values, label?)` expose the same rules if you render blocks yourself.
+
+### Refresh when something changes
+
+In SolutionDesk set the site's webhook to a route on your website and copy the signing secret. The handler checks the `X-SolutionDesk-Signature` header and answers `401` when it doesn't match (or is older than 5 minutes) and `400` for a signed body that isn't a help webhook:
+
+```ts
+// app/api/solutiondesk/help/route.ts
+import { createHelpRevalidateHandler } from "@solutiondesk/help/fumadocs";
+import { revalidateTag } from "next/cache";
+import { HELP_TAG } from "@/lib/help";
+
+export const POST = createHelpRevalidateHandler({
+  secret: process.env.SOLUTIONDESK_HELP_WEBHOOK_SECRET ?? "",
+  revalidate: () => revalidateTag(HELP_TAG, "max"),
+});
+```
+
+The handler works with any framework that has `Request` and `Response`. Events: `page.published`, `page.updated`, `page.unpublished`, `page.deleted`, `navigation.updated` and `ping` (the test call, which doesn't call `revalidate`). Without the handler, check calls yourself with `verifyHelpWebhook(secret, rawBody, header)`, which returns the body or `null`.
+
+### Preview with Draft Mode
+
+Set the site's preview address to `https://help.acme.com/api/preview?token={token}&path={path}`:
+
+```ts
+// app/api/preview/route.ts
+import { cookies, draftMode } from "next/headers";
+import { redirect } from "next/navigation";
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const token = url.searchParams.get("token");
+  if (!token) return new Response("Missing token", { status: 400 });
+  (await draftMode()).enable();
+  (await cookies()).set("sd-help-preview", token, { httpOnly: true, sameSite: "lax", maxAge: 3600 });
+  redirect(`/docs/${(url.searchParams.get("path") ?? "").replace(/[^a-z0-9/-]/g, "")}`);
+}
+```
+
+In the page, read the page from the preview while Draft Mode is on:
+
+```ts
+if ((await draftMode()).isEnabled) {
+  const token = (await cookies()).get("sd-help-preview")?.value;
+  if (token) return (await help.preview(token, {}, { fetchOptions: { cache: "no-store" } })).page;
+}
+```
+
+A complete Next.js app with these files is in [`examples/fumadocs-next`](./examples/fumadocs-next).
+
+## Any other website
+
+Without Fumadocs, use `page.html` and style its stable classes:
+
+```ts
+const { page, movedFrom } = await help.page(path);
+if (movedFrom) redirect(`/docs/${page.path}`);
+document.querySelector("article")!.innerHTML = page.html;
+```
+
+| Block | HTML |
+| --- | --- |
+| callout | `<div class="sd-callout" data-type="info\|warn\|error\|success\|idea" role="note">` with `<p class="sd-callout-title">` and `<div class="sd-callout-body">` |
+| steps | `<ol class="sd-steps">` of `<li class="sd-step">` with `<h3 class="sd-step-title" id="…">` and `<div class="sd-step-body">` |
+| tabs | `<div class="sd-tabs">` of `<section class="sd-tab" data-title="…">` (build the tab buttons from `data-title`; `page.blocks` says when a page has tabs) |
+| cards | `<div class="sd-cards">` of `<a class="sd-card" href="…" data-icon="Rocket">` (or `<div class="sd-card">`) with `<p class="sd-card-title">` and `<div class="sd-card-body">` |
+| titled code | `<figure class="sd-code"><figcaption>client.ts</figcaption><pre><code class="language-ts">` |
+| the site's own block | `<span class="sd-block" data-block="app-button" data-props="{…}">` in a sentence, `<div class="sd-block">` on its own line or around content (`<p class="sd-block-text">`, `<div class="sd-block-body">`); the text is the block's text version, `data-props` its checked values as JSON — hydrate your own component from it |
+
+Build the table of contents from `page.headings` (`#id`), the breadcrumb from `page.breadcrumbs` and the footer links from `page.previous`/`page.next`.
+
+## License
+
+MIT © wemogy GmbH