@solutiondesk/changelog 0.0.0 → 1.0.0-9fc05ac

package/dist/react.d.cts

@@ -0,0 +1,288 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * The answers of the public changelog API (`GET /v1/changelog/{workspace}/…`).
+ * 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.
+ */
+type ChangelogCategory = "new" | "improved" | "fixed" | "announcement";
+type ChangelogWidgetPosition = "bottom-right" | "bottom-left";
+/** A published entry. */
+interface PublicChangelogEntry {
+    slug: string;
+    title: string;
+    /** One or two sentences — what a "What's new" panel shows. May be empty. */
+    summary: string;
+    category: ChangelogCategory;
+    /** ISO 8601. The list is sorted by it, newest first. */
+    publishedAt: string;
+    /** The details as the team wrote them (Markdown). */
+    markdown: string;
+    /**
+     * The details as safe HTML: raw HTML in the text is escaped, links are only
+     * http(s)/mailto/relative, images only from https addresses. Ready for
+     * `innerHTML` / `dangerouslySetInnerHTML`. Empty when there are no details.
+     */
+    html: string;
+    /** The entry on the workspace's hosted changelog page. */
+    url: string;
+}
+/** `GET /v1/changelog/{workspace}` — settings and one page of entries. */
+interface PublicChangelogPayload {
+    /** The workspace as the hosted page shows it; `logoUrl` is relative to the API. */
+    workspace: {
+        name: string;
+        slug: string;
+        logoUrl: string | null;
+    };
+    /** The heading the team chose; empty ⇒ use your own ("What's new"). */
+    title: string;
+    /** The team's settings for the "What's new" button (empty label ⇒ your own). */
+    widget: {
+        label: string;
+        position: ChangelogWidgetPosition;
+    };
+    /** The hosted changelog page. */
+    pageUrl: string;
+    entries: PublicChangelogEntry[];
+    /** Pass as `cursor` for the next page; null on the last one. */
+    nextCursor: string | null;
+}
+/** `GET /v1/changelog/{workspace}/entries/{slug}`. */
+interface PublicChangelogEntryPayload {
+    entry: PublicChangelogEntry;
+}
+
+/** 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>;
+}
+
+interface ChangelogClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/changelog/acme`. */
+    workspace: string;
+}
+interface ListEntriesParams {
+    /** Only entries of this category. */
+    category?: ChangelogCategory;
+    /** Page size, 1–50 (default 20). */
+    limit?: number;
+    /** `nextCursor` of the previous page. */
+    cursor?: string | null;
+}
+interface ChangelogClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /**
+     * The team's settings and one page of published entries, newest first
+     * (`GET /v1/changelog/{workspace}`). Throws a `SolutionDeskError` with status
+     * 404 when the workspace doesn't exist or its changelog is turned off.
+     */
+    list(params?: ListEntriesParams, options?: RequestOptions): Promise<PublicChangelogPayload>;
+    /** Every published entry, page by page — e.g. for a sitemap, an RSS feed or a static build. */
+    allEntries(params?: Omit<ListEntriesParams, "cursor">, options?: RequestOptions): AsyncGenerator<PublicChangelogEntry, void, undefined>;
+    /**
+     * One published entry (`GET /v1/changelog/{workspace}/entries/{slug}`).
+     * Throws a `SolutionDeskError` with status 404 for an unknown or unpublished entry.
+     */
+    getEntry(slug: string, options?: RequestOptions): Promise<PublicChangelogEntryPayload>;
+}
+
+/** Where "last seen" is kept — `window.localStorage`, `sessionStorage` or your own. */
+interface SeenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+interface UseChangelogOptions extends Partial<Omit<ChangelogClientOptions, "workspace">> {
+    /** Your workspace's slug. */
+    workspace: string;
+    /** Use this client instead of making one (e.g. one shared by your whole app). */
+    client?: ChangelogClient;
+    /** Entries per page (1–50, default 10). */
+    limit?: number;
+    /** Only entries of this category. */
+    category?: ChangelogCategory;
+    /**
+     * Count entries the visitor hasn't seen yet (`unseen`), kept in `storage`.
+     * Default true. On the first visit nothing counts: the newest entry becomes
+     * the starting point.
+     */
+    trackSeen?: boolean;
+    /** Where "last seen" lives (default the browser's `localStorage`). */
+    storage?: SeenStorage | null;
+    /** Server-rendered or cached first page: shown at once, refreshed in the background. */
+    initialData?: PublicChangelogPayload;
+}
+interface UseChangelogResult {
+    status: "loading" | "ready" | "error";
+    /** Every entry loaded so far, newest first. */
+    entries: PublicChangelogEntry[];
+    /** The last page's answer (title, button settings, page address), or null while loading. */
+    data: PublicChangelogPayload | null;
+    /**
+     * Why loading failed (a `SolutionDeskError`; 404 = unknown workspace or changelog off).
+     * A failed {@link UseChangelogResult.loadMore} sets it too, but keeps `status` "ready".
+     */
+    error: unknown;
+    /** Entries newer than what the visitor last saw. */
+    unseen: number;
+    /** Remember everything loaded as seen (call it when the visitor opens your panel). */
+    markAllSeen(): void;
+    /** Whether there are older entries to load. */
+    hasMore: boolean;
+    /** Whether an older page is loading right now. */
+    loadingMore: boolean;
+    /** Load the next (older) page and append it. Never rejects; failures land in `error`. */
+    loadMore(): Promise<void>;
+    /** Load the first page again. */
+    reload(): Promise<void>;
+}
+/**
+ * The published changelog entries of a workspace, with an unseen count for a
+ * "new" badge. Fetches in the browser (no key needed); pass `initialData` from
+ * your server for a first paint without loading.
+ */
+declare function useChangelog(options: UseChangelogOptions): UseChangelogResult;
+
+/** "October 28, 2026" / "28. Oktober 2026" in the visitor's language. */
+declare function formatChangelogDate(iso: string, locale?: string): string;
+/**
+ * An entry's details. `html` comes sanitised from SolutionDesk (raw HTML in the
+ * team's text is escaped, links and images are allow-listed), so it can be set
+ * as HTML directly.
+ */
+declare function ChangelogEntryBody({ html, className }: {
+    html: string;
+    className?: string;
+}): react.JSX.Element | null;
+interface ChangelogEntryClassNames {
+    entry?: string;
+    meta?: string;
+    date?: string;
+    category?: string;
+    title?: string;
+    summary?: string;
+    body?: string;
+}
+/** One entry: date, category, title (linking to the hosted page), summary and details. */
+declare function ChangelogEntryView({ entry, locale, showBody, classNames, titleAs: Title, }: {
+    entry: PublicChangelogEntry;
+    /** Language of the date and the category name (`de*` → German, else English). */
+    locale?: string;
+    /** Show the details too (default) or only title and summary. */
+    showBody?: boolean;
+    classNames?: ChangelogEntryClassNames;
+    titleAs?: "h2" | "h3" | "h4";
+}): react.JSX.Element;
+interface ChangelogFeedProps extends UseChangelogOptions {
+    /** Language of dates, categories and the few fixed words. */
+    locale?: string;
+    /** Show each entry's details (default) or only title and summary. */
+    showBody?: boolean;
+    className?: string;
+    entryClassNames?: ChangelogEntryClassNames;
+    /** Render an entry yourself instead of {@link ChangelogEntryView}. */
+    renderEntry?: (entry: PublicChangelogEntry) => ReactNode;
+    /** Shown while the first page loads. */
+    loading?: ReactNode;
+    /** Shown when there are no entries yet. */
+    empty?: ReactNode;
+    /** Shown when the changelog can't be loaded (default: nothing). */
+    fallback?: ReactNode;
+    /** The "load older" button's text (default "Older updates" / "Ältere Neuigkeiten"). */
+    moreLabel?: string;
+    moreClassName?: string;
+}
+/** A full changelog feed: the published entries, newest first, with "load older". */
+declare function ChangelogFeed(props: ChangelogFeedProps): react.JSX.Element;
+interface WhatsNewClassNames {
+    root?: string;
+    button?: string;
+    badge?: string;
+    panel?: string;
+    header?: string;
+    list?: string;
+    footer?: string;
+}
+interface WhatsNewProps extends UseChangelogOptions {
+    locale?: string;
+    /** The button's content (default: the team's label, else "What's new"). */
+    label?: ReactNode;
+    /** The panel's heading (default: the team's title, else "What's new"). */
+    title?: ReactNode;
+    classNames?: WhatsNewClassNames;
+    entryClassNames?: ChangelogEntryClassNames;
+    /** Render the badge yourself (default: the number in a `<span>`). */
+    renderBadge?: (unseen: number) => ReactNode;
+}
+/**
+ * A "What's new" button for your app's header or menu: shows how many entries
+ * the visitor hasn't seen and opens a panel with the latest ones (title and
+ * summary, linking to the hosted page). Closes on Escape and outside clicks.
+ * Renders nothing when the changelog can't be loaded.
+ */
+declare function WhatsNew(props: WhatsNewProps): react.JSX.Element | null;
+
+export { ChangelogEntryBody, type ChangelogEntryClassNames, ChangelogEntryView, ChangelogFeed, type ChangelogFeedProps, type UseChangelogOptions, type UseChangelogResult, WhatsNew, type WhatsNewClassNames, type WhatsNewProps, formatChangelogDate, useChangelog };

package/dist/react.d.ts

@@ -0,0 +1,288 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * The answers of the public changelog API (`GET /v1/changelog/{workspace}/…`).
+ * 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.
+ */
+type ChangelogCategory = "new" | "improved" | "fixed" | "announcement";
+type ChangelogWidgetPosition = "bottom-right" | "bottom-left";
+/** A published entry. */
+interface PublicChangelogEntry {
+    slug: string;
+    title: string;
+    /** One or two sentences — what a "What's new" panel shows. May be empty. */
+    summary: string;
+    category: ChangelogCategory;
+    /** ISO 8601. The list is sorted by it, newest first. */
+    publishedAt: string;
+    /** The details as the team wrote them (Markdown). */
+    markdown: string;
+    /**
+     * The details as safe HTML: raw HTML in the text is escaped, links are only
+     * http(s)/mailto/relative, images only from https addresses. Ready for
+     * `innerHTML` / `dangerouslySetInnerHTML`. Empty when there are no details.
+     */
+    html: string;
+    /** The entry on the workspace's hosted changelog page. */
+    url: string;
+}
+/** `GET /v1/changelog/{workspace}` — settings and one page of entries. */
+interface PublicChangelogPayload {
+    /** The workspace as the hosted page shows it; `logoUrl` is relative to the API. */
+    workspace: {
+        name: string;
+        slug: string;
+        logoUrl: string | null;
+    };
+    /** The heading the team chose; empty ⇒ use your own ("What's new"). */
+    title: string;
+    /** The team's settings for the "What's new" button (empty label ⇒ your own). */
+    widget: {
+        label: string;
+        position: ChangelogWidgetPosition;
+    };
+    /** The hosted changelog page. */
+    pageUrl: string;
+    entries: PublicChangelogEntry[];
+    /** Pass as `cursor` for the next page; null on the last one. */
+    nextCursor: string | null;
+}
+/** `GET /v1/changelog/{workspace}/entries/{slug}`. */
+interface PublicChangelogEntryPayload {
+    entry: PublicChangelogEntry;
+}
+
+/** 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>;
+}
+
+interface ChangelogClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/changelog/acme`. */
+    workspace: string;
+}
+interface ListEntriesParams {
+    /** Only entries of this category. */
+    category?: ChangelogCategory;
+    /** Page size, 1–50 (default 20). */
+    limit?: number;
+    /** `nextCursor` of the previous page. */
+    cursor?: string | null;
+}
+interface ChangelogClient {
+    /** The workspace this client reads. */
+    readonly workspace: string;
+    /**
+     * The team's settings and one page of published entries, newest first
+     * (`GET /v1/changelog/{workspace}`). Throws a `SolutionDeskError` with status
+     * 404 when the workspace doesn't exist or its changelog is turned off.
+     */
+    list(params?: ListEntriesParams, options?: RequestOptions): Promise<PublicChangelogPayload>;
+    /** Every published entry, page by page — e.g. for a sitemap, an RSS feed or a static build. */
+    allEntries(params?: Omit<ListEntriesParams, "cursor">, options?: RequestOptions): AsyncGenerator<PublicChangelogEntry, void, undefined>;
+    /**
+     * One published entry (`GET /v1/changelog/{workspace}/entries/{slug}`).
+     * Throws a `SolutionDeskError` with status 404 for an unknown or unpublished entry.
+     */
+    getEntry(slug: string, options?: RequestOptions): Promise<PublicChangelogEntryPayload>;
+}
+
+/** Where "last seen" is kept — `window.localStorage`, `sessionStorage` or your own. */
+interface SeenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+
+interface UseChangelogOptions extends Partial<Omit<ChangelogClientOptions, "workspace">> {
+    /** Your workspace's slug. */
+    workspace: string;
+    /** Use this client instead of making one (e.g. one shared by your whole app). */
+    client?: ChangelogClient;
+    /** Entries per page (1–50, default 10). */
+    limit?: number;
+    /** Only entries of this category. */
+    category?: ChangelogCategory;
+    /**
+     * Count entries the visitor hasn't seen yet (`unseen`), kept in `storage`.
+     * Default true. On the first visit nothing counts: the newest entry becomes
+     * the starting point.
+     */
+    trackSeen?: boolean;
+    /** Where "last seen" lives (default the browser's `localStorage`). */
+    storage?: SeenStorage | null;
+    /** Server-rendered or cached first page: shown at once, refreshed in the background. */
+    initialData?: PublicChangelogPayload;
+}
+interface UseChangelogResult {
+    status: "loading" | "ready" | "error";
+    /** Every entry loaded so far, newest first. */
+    entries: PublicChangelogEntry[];
+    /** The last page's answer (title, button settings, page address), or null while loading. */
+    data: PublicChangelogPayload | null;
+    /**
+     * Why loading failed (a `SolutionDeskError`; 404 = unknown workspace or changelog off).
+     * A failed {@link UseChangelogResult.loadMore} sets it too, but keeps `status` "ready".
+     */
+    error: unknown;
+    /** Entries newer than what the visitor last saw. */
+    unseen: number;
+    /** Remember everything loaded as seen (call it when the visitor opens your panel). */
+    markAllSeen(): void;
+    /** Whether there are older entries to load. */
+    hasMore: boolean;
+    /** Whether an older page is loading right now. */
+    loadingMore: boolean;
+    /** Load the next (older) page and append it. Never rejects; failures land in `error`. */
+    loadMore(): Promise<void>;
+    /** Load the first page again. */
+    reload(): Promise<void>;
+}
+/**
+ * The published changelog entries of a workspace, with an unseen count for a
+ * "new" badge. Fetches in the browser (no key needed); pass `initialData` from
+ * your server for a first paint without loading.
+ */
+declare function useChangelog(options: UseChangelogOptions): UseChangelogResult;
+
+/** "October 28, 2026" / "28. Oktober 2026" in the visitor's language. */
+declare function formatChangelogDate(iso: string, locale?: string): string;
+/**
+ * An entry's details. `html` comes sanitised from SolutionDesk (raw HTML in the
+ * team's text is escaped, links and images are allow-listed), so it can be set
+ * as HTML directly.
+ */
+declare function ChangelogEntryBody({ html, className }: {
+    html: string;
+    className?: string;
+}): react.JSX.Element | null;
+interface ChangelogEntryClassNames {
+    entry?: string;
+    meta?: string;
+    date?: string;
+    category?: string;
+    title?: string;
+    summary?: string;
+    body?: string;
+}
+/** One entry: date, category, title (linking to the hosted page), summary and details. */
+declare function ChangelogEntryView({ entry, locale, showBody, classNames, titleAs: Title, }: {
+    entry: PublicChangelogEntry;
+    /** Language of the date and the category name (`de*` → German, else English). */
+    locale?: string;
+    /** Show the details too (default) or only title and summary. */
+    showBody?: boolean;
+    classNames?: ChangelogEntryClassNames;
+    titleAs?: "h2" | "h3" | "h4";
+}): react.JSX.Element;
+interface ChangelogFeedProps extends UseChangelogOptions {
+    /** Language of dates, categories and the few fixed words. */
+    locale?: string;
+    /** Show each entry's details (default) or only title and summary. */
+    showBody?: boolean;
+    className?: string;
+    entryClassNames?: ChangelogEntryClassNames;
+    /** Render an entry yourself instead of {@link ChangelogEntryView}. */
+    renderEntry?: (entry: PublicChangelogEntry) => ReactNode;
+    /** Shown while the first page loads. */
+    loading?: ReactNode;
+    /** Shown when there are no entries yet. */
+    empty?: ReactNode;
+    /** Shown when the changelog can't be loaded (default: nothing). */
+    fallback?: ReactNode;
+    /** The "load older" button's text (default "Older updates" / "Ältere Neuigkeiten"). */
+    moreLabel?: string;
+    moreClassName?: string;
+}
+/** A full changelog feed: the published entries, newest first, with "load older". */
+declare function ChangelogFeed(props: ChangelogFeedProps): react.JSX.Element;
+interface WhatsNewClassNames {
+    root?: string;
+    button?: string;
+    badge?: string;
+    panel?: string;
+    header?: string;
+    list?: string;
+    footer?: string;
+}
+interface WhatsNewProps extends UseChangelogOptions {
+    locale?: string;
+    /** The button's content (default: the team's label, else "What's new"). */
+    label?: ReactNode;
+    /** The panel's heading (default: the team's title, else "What's new"). */
+    title?: ReactNode;
+    classNames?: WhatsNewClassNames;
+    entryClassNames?: ChangelogEntryClassNames;
+    /** Render the badge yourself (default: the number in a `<span>`). */
+    renderBadge?: (unseen: number) => ReactNode;
+}
+/**
+ * A "What's new" button for your app's header or menu: shows how many entries
+ * the visitor hasn't seen and opens a panel with the latest ones (title and
+ * summary, linking to the hosted page). Closes on Escape and outside clicks.
+ * Renders nothing when the changelog can't be loaded.
+ */
+declare function WhatsNew(props: WhatsNewProps): react.JSX.Element | null;
+
+export { ChangelogEntryBody, type ChangelogEntryClassNames, ChangelogEntryView, ChangelogFeed, type ChangelogFeedProps, type UseChangelogOptions, type UseChangelogResult, WhatsNew, type WhatsNewClassNames, type WhatsNewProps, formatChangelogDate, useChangelog };