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

package/dist/index.d.cts

@@ -0,0 +1,433 @@
+/**
+ * The HTTP part shared by the public SolutionDesk SDKs. Runs on any runtime with
+ * a WHATWG `fetch` (Node ≥ 18, Deno, Bun, edge runtimes, browsers) — and on
+ * purpose names no DOM or Node type, so the published `.d.ts` files need neither
+ * `lib: ["dom"]` nor `@types/node`.
+ */
+/** The production API. */
+declare const DEFAULT_BASE_URL = "https://api.solutiondesk.io";
+/** The response parts the SDK reads — what every `fetch` implementation returns. */
+interface FetchResponseLike {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** What the SDK passes to `fetch` (plus whatever you set in `fetchOptions`). */
+interface FetchInitLike {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+/**
+ * A `fetch` implementation. The global `fetch` fits, so do `undici`, `node-fetch`
+ * and wrappers (e.g. one that adds tracing). Declared bivariantly so a fetch with
+ * a richer `init` type is accepted.
+ */
+type FetchLike = {
+    bivarianceHack(input: string, init?: FetchInitLike): Promise<FetchResponseLike>;
+}["bivarianceHack"];
+/** A response kept for `If-None-Match` revalidation. */
+interface CachedResponse {
+    etag: string;
+    body: unknown;
+}
+/**
+ * Where the client keeps answers for ETag revalidation. Any `Map` fits; bring
+ * your own to share it between clients or to bound it differently.
+ */
+interface EtagCache {
+    get(key: string): CachedResponse | undefined;
+    set(key: string, value: CachedResponse): unknown;
+}
+/** Options every client factory takes. */
+interface BaseClientOptions {
+    /** The API origin, without `/v1`. Defaults to `https://api.solutiondesk.io`. */
+    baseUrl?: string;
+    /** A `fetch` implementation; defaults to the global one. */
+    fetch?: FetchLike;
+    /** Headers sent with every request (e.g. `accept-language` forwarded from your visitor). */
+    headers?: Record<string, string>;
+    /**
+     * Revalidate with `If-None-Match`: the client remembers each answer's `ETag`
+     * and, when the API answers `304 Not Modified`, returns the remembered body.
+     * `true` keeps up to 500 answers in memory; or pass your own {@link EtagCache}.
+     * Off by default (your framework's fetch cache may already do this).
+     */
+    etagCache?: boolean | EtagCache;
+}
+/** 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>;
+}
+/** Any non-2xx answer of the API (and a failed network request, with `status` 0). */
+declare class SolutionDeskError extends Error {
+    /** The HTTP status; `0` when no answer arrived (network error, aborted). */
+    readonly status: number;
+    /** The parsed JSON body of the error answer (usually `{ error: string }`), else its text. */
+    readonly body: unknown;
+    /** The requested URL. */
+    readonly url: string;
+    /** Messages per input field on a `400` (e.g. `{ email: "Enter a valid email address." }`). */
+    readonly fields: Record<string, string>;
+    constructor(message: string, init: {
+        status: number;
+        body?: unknown;
+        url: string;
+        cause?: unknown;
+    });
+    /** `404`: unknown workspace, module turned off or unknown item — on purpose indistinguishable. */
+    get isNotFound(): boolean;
+    /** `429`: over the rate limit; try again later. */
+    get isRateLimited(): boolean;
+}
+/** A bounded in-memory {@link EtagCache} (oldest entry dropped first). */
+declare function createMemoryEtagCache(maxEntries?: number): EtagCache;
+
+/**
+ * Webhook signature check with Web Crypto only — the same code runs in Node,
+ * Deno, Bun, edge runtimes and browsers. The header SolutionDesk sends is
+ * `X-SolutionDesk-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>`.
+ */
+/** The header that carries the signature. */
+declare const SIGNATURE_HEADER = "x-solutiondesk-signature";
+/** The header that names the event (also in the body as `event`). */
+declare const EVENT_HEADER = "x-solutiondesk-event";
+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;
+    };
+}
+/** The raw request body, exactly as received. */
+type WebhookBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Check a SolutionDesk webhook signature. `true` only when the header is well
+ * formed, its time lies within the tolerance and the HMAC matches — anything
+ * else (missing, tampered, expired, malformed) is `false`, never an exception.
+ *
+ * @param secret The webhook's signing secret (`whsec_…`), shown once in SolutionDesk.
+ * @param rawBody The request body exactly as received — not re-serialized JSON.
+ * @param header The `X-SolutionDesk-Signature` header.
+ */
+declare function verifyWebhookSignature(secret: string, rawBody: WebhookBody, header: string | null | undefined, options?: VerifyWebhookOptions): Promise<boolean>;
+
+/**
+ * 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;
+}
+/** 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;
+    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;
+    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`, …). */
+    markdown: string;
+    /** Safe server-rendered HTML of `markdown` (stable `sd-*` classes for the directives). */
+    html: string;
+    headings: HelpPublicHeading[];
+    blocks: HelpPublicBlock[];
+    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;
+}
+
+interface HelpClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/help/acme/docs`. */
+    workspace: string;
+    /** The doc site's slug — the `docs` in `https://api.solutiondesk.io/v1/help/acme/docs`. */
+    site: string;
+    /**
+     * The language to ask for by default (`de`, `en`, `de-AT` …). Each answer
+     * says in `locale` which language it really is in. Override per call.
+     */
+    lang?: string;
+}
+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>;
+}
+/** A path as the API writes it: no leading or trailing slash, lower case. */
+declare function normalizeHelpPath(path: string): string;
+/**
+ * A client for the public help center API — no key, no login; only pages
+ * that are published, public and placed in the navigation. Safe in the
+ * browser and on the server.
+ *
+ * @example
+ * const help = createHelpClient({ workspace: "acme", site: "docs", lang: "en" });
+ * const { tree } = await help.site();
+ * const { page } = await help.page("guides/login");
+ */
+declare function createHelpClient(options: HelpClientOptions): HelpClient;
+/**
+ * Verify a help webhook call and return its body — or `null` when the
+ * `X-SolutionDesk-Signature` header doesn't match (wrong secret, changed body,
+ * older than 5 minutes, malformed). Pass the raw body exactly as received.
+ */
+declare function verifyHelpWebhook(secret: string, rawBody: WebhookBody, signatureHeader: string | null | undefined, options?: VerifyWebhookOptions): Promise<HelpWebhookBody | null>;
+
+export { type BaseClientOptions, type CachedResponse, DEFAULT_BASE_URL, EVENT_HEADER, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type GetPageParams, type HelpClient, type HelpClientOptions, type HelpPageResult, type HelpPublicBlock, type HelpPublicBreadcrumb, type HelpPublicHeading, type HelpPublicPage, type HelpPublicPageLink, type HelpPublicPagePayload, type HelpPublicPageSummary, type HelpPublicPagesPayload, type HelpPublicPreviewPage, type HelpPublicPreviewPayload, type HelpPublicRedirect, type HelpPublicSearchHit, type HelpPublicSearchPayload, type HelpPublicSite, type HelpPublicSitePayload, type HelpPublicTreeFolder, type HelpPublicTreeLink, type HelpPublicTreeNode, type HelpPublicTreePage, type HelpPublicTreeSeparator, type HelpWebhookBody, type HelpWebhookEvent, type LangParams, type RequestOptions, SIGNATURE_HEADER, type SearchParams, SolutionDeskError, type VerifyWebhookOptions, type WebhookBody, createHelpClient, createMemoryEtagCache, normalizeHelpPath, verifyHelpWebhook, verifyWebhookSignature };