@solutiondesk/changelog 0.0.0 → 1.0.0-2cf6d3e

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,93 @@
 # @solutiondesk/changelog
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Typed client for the public [SolutionDesk](https://solutiondesk.io) changelogs, plus React hooks and unstyled components. Your team writes the updates for each of its products in SolutionDesk; your app or website shows them 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, ships ESM and CommonJS with full TypeScript types, and runs wherever `fetch` does: Node.js 18+, Deno, Bun, edge runtimes and browsers.
+- No key and no login: the API only ever returns published entries.
+- `@solutiondesk/changelog/react`: a hook and unstyled components (`ChangelogFeed`, `WhatsNew`) that take your design system's styles. React is an optional peer dependency.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @solutiondesk/changelog
+```
 
-## Purpose
+No code at all? The [Products guide](https://help.solutiondesk.io/docs/team/changelog) shows the hosted page and the ready-made "What's new" button (two lines of HTML).
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@solutiondesk/changelog`
-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 { createChangelogClient } from "@solutiondesk/changelog";
 
-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 changelog = createChangelogClient({ workspace: "acme", product: "acme-mobile" });
 
-## Setup Instructions
+const { title, entries, nextCursor } = await changelog.list({ limit: 10 });
+const { entry } = await changelog.getEntry("export-to-csv");
+```
 
-To properly configure OIDC trusted publishing for this package:
+`workspace` and `product` are the two parts of the address shown under **Products → your product → Page & settings → For developers** (`https://api.solutiondesk.io/v1/changelog/acme/acme-mobile`). Leave `product` out to read the workspace's default product.
 
-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 |
+| --- | --- | --- |
+| `list({ category, limit, cursor })` | `GET /v1/changelog/{workspace}/{product}` | The `product`, its title and button settings, the hosted `pageUrl`, one page of entries (newest first) and `nextCursor` (`limit` 1–50, default 20). |
+| `allEntries({ category })` | the same, page by page | An async iterator over every published entry, e.g. for a sitemap or an RSS feed. |
+| `getEntry(slug)` | `GET /v1/changelog/{workspace}/{product}/entries/{slug}` | One entry and its product. |
+| `listProducts()` | `GET /v1/changelog/{workspace}/products` | Every product (name, slug, description, `pageUrl`), the default first. |
 
-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
+Each entry has `title`, `summary` (one or two sentences), `category` (`new`, `improved`, `fixed`, `announcement`), `publishedAt`, the details as `markdown` and as `html`, and `url` (the entry on the hosted page). `html` is safe to insert as it is: raw HTML in the team's text is escaped, links only go to web addresses and paths, images only come from https addresses.
 
-## More Information
+A workspace or product that doesn't exist, a changelog that is turned off and an unpublished entry all answer `404` (`SolutionDeskError` with `isNotFound`).
 
-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)
+## "New" badge
 
----
+```ts
+import { createSeenTracker } from "@solutiondesk/changelog";
 
-**Maintained for OIDC setup purposes only**
+const seen = createSeenTracker("acme", undefined, "acme-mobile"); // the browser's localStorage by default
+const unseen = seen.unseen(entries); // entries newer than the visitor's last look
+seen.markSeen(entries[0].publishedAt); // when they open your panel
+```
+
+On the very first visit nothing counts as new — remember the newest entry then, so the next one is the first that counts. The tracker uses the same key as SolutionDesk's own button, and nothing about the visitor leaves their browser.
+
+`categoryLabel(category, locale)`, `CATEGORY_LABELS` and `CATEGORY_COLORS` give you the names (German and English) and colors the hosted page uses.
+
+## React
+
+```tsx
+import { ChangelogFeed, WhatsNew } from "@solutiondesk/changelog/react";
+
+// In your app's header: a button with the unseen count that opens the latest entries.
+<WhatsNew workspace="acme" product="acme-mobile" classNames={{ button: "btn", badge: "badge", panel: "popover" }} />
+
+// A whole changelog page: entries with their details and "Older updates".
+<ChangelogFeed workspace="acme" product="acme-mobile" locale="de" entryClassNames={{ title: "text-xl font-semibold" }} />
+```
+
+The components render plain elements with `className` props and `data-sd-*` attributes (`data-sd-changelog-entry`, `data-category`, `data-sd-whats-new-badge` …) and ship no CSS. Both render nothing (or your `fallback`) when the changelog can't be loaded, so they never break your page.
+
+For your own markup, use the hook:
+
+```tsx
+import { useChangelog } from "@solutiondesk/changelog/react";
+
+function Updates() {
+  const { status, entries, unseen, markAllSeen, hasMore, loadMore } = useChangelog({
+    workspace: "acme",
+    product: "acme-mobile",
+    limit: 5,
+  });
+  if (status !== "ready") return null;
+  // …
+}
+```
+
+Pass `initialData` (a `list()` answer fetched on your server) for a first paint without loading. `ChangelogEntryView` and `ChangelogEntryBody` render a single entry or just its details.
+
+## Options
+
+`createChangelogClient` (and the hook) take `baseUrl` (default `https://api.solutiondesk.io`), `fetch`, `headers` and `etagCache` (revalidate with `If-None-Match`). Per call, `fetchOptions` is handed to `fetch` unchanged — e.g. Next.js `{ next: { revalidate: 300, tags: ["changelog"] } }`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,263 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// ../sdk-core/src/http.ts
+var DEFAULT_BASE_URL = "https://api.solutiondesk.io";
+var SolutionDeskError = class extends Error {
+  constructor(message, init) {
+    super(message);
+    /** The HTTP status; `0` when no answer arrived (network error, aborted). */
+    __publicField(this, "status");
+    /** The parsed JSON body of the error answer (usually `{ error: string }`), else its text. */
+    __publicField(this, "body");
+    /** The requested URL. */
+    __publicField(this, "url");
+    /** Messages per input field on a `400` (e.g. `{ email: "Enter a valid email address." }`). */
+    __publicField(this, "fields");
+    this.name = "SolutionDeskError";
+    this.status = init.status;
+    this.body = init.body ?? null;
+    this.url = init.url;
+    this.fields = fieldsOf(init.body);
+    if (init.cause !== void 0) {
+      Object.defineProperty(this, "cause", { value: init.cause, enumerable: false });
+    }
+  }
+  /** `404`: unknown workspace, module turned off or unknown item — on purpose indistinguishable. */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** `429`: over the rate limit; try again later. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+function fieldsOf(body) {
+  if (!body || typeof body !== "object") return {};
+  const fields = body.fields;
+  if (!fields || typeof fields !== "object") return {};
+  const out = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+function messageOf(body, status) {
+  if (body && typeof body === "object") {
+    const { error, message, statusCode } = body;
+    if (typeof statusCode === "number" && typeof message === "string" && message) return message;
+    if (typeof error === "string" && error) return error;
+    if (typeof message === "string" && message) return message;
+    if (Array.isArray(message) && typeof message[0] === "string") return message[0];
+  }
+  if (typeof body === "string" && body.trim() && body.length <= 300) return body.trim();
+  return `SolutionDesk answered ${status}.`;
+}
+function createMemoryEtagCache(maxEntries = 500) {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => entries.get(key),
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, value);
+      if (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest !== void 0) entries.delete(oldest);
+      }
+    }
+  };
+}
+function queryString(query) {
+  if (!query) return "";
+  const parts = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null || value === "") continue;
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+  }
+  return parts.length ? `?${parts.join("&")}` : "";
+}
+var seg = (value) => encodeURIComponent(String(value));
+function parseBody(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function createHttp(options = {}) {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const cache = options.etagCache === true ? createMemoryEtagCache() : options.etagCache ? options.etagCache : void 0;
+  const url = (path, query) => `${baseUrl}/v1${path}${queryString(query)}`;
+  async function requestWithMeta(req) {
+    if (!fetchImpl) {
+      throw new Error("No global fetch available: pass `fetch` to the client.");
+    }
+    const target = url(req.path, req.query);
+    const headers = {
+      accept: req.accept ?? "application/json",
+      ...options.headers,
+      ...req.options?.headers
+    };
+    if (req.body !== void 0) headers["content-type"] = "application/json";
+    if (req.apiKey) headers.authorization = `Bearer ${req.apiKey}`;
+    const cacheKey = req.method === "GET" && !req.apiKey ? target : void 0;
+    const cached = cacheKey && cache ? cache.get(cacheKey) : void 0;
+    if (cached && !Object.keys(headers).some((h) => h.toLowerCase() === "if-none-match")) {
+      headers["if-none-match"] = cached.etag;
+    }
+    const init = {
+      ...req.options?.fetchOptions,
+      method: req.method,
+      headers
+    };
+    if (req.body !== void 0) init.body = JSON.stringify(req.body);
+    if (req.options?.signal !== void 0) init.signal = req.options.signal;
+    let response;
+    try {
+      response = await fetchImpl(target, init);
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      throw new SolutionDeskError(`The request to SolutionDesk failed: ${reason}`, {
+        status: 0,
+        url: target,
+        cause
+      });
+    }
+    const finalUrl = response.url;
+    const meta = {
+      status: response.status,
+      finalUrl: typeof finalUrl === "string" && finalUrl ? finalUrl : null
+    };
+    if (response.status === 304 && cached) {
+      return { data: cached.body, ...meta };
+    }
+    const text = await response.text();
+    const body = response.ok && req.responseType === "text" ? text : parseBody(text);
+    if (!response.ok) {
+      throw new SolutionDeskError(messageOf(body, response.status), {
+        status: response.status,
+        body,
+        url: target
+      });
+    }
+    const etag = response.headers.get("etag");
+    if (cacheKey && cache && etag) cache.set(cacheKey, { etag, body });
+    return { data: body, ...meta };
+  }
+  return {
+    baseUrl,
+    url,
+    requestWithMeta,
+    request: async (req) => (await requestWithMeta(req)).data
+  };
+}
+function required(value, name) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`SolutionDesk: \`${name}\` is required.`);
+  }
+  return value;
+}
+
+// src/client.ts
+function createChangelogClient(options) {
+  const workspace = required(options.workspace, "workspace");
+  const product = options.product?.trim() || void 0;
+  const http = createHttp(options);
+  const root = `/changelog/${seg(workspace)}`;
+  const base = product ? `${root}/${seg(product)}` : root;
+  const list = (params = {}, requestOptions) => http.request({
+    method: "GET",
+    path: base,
+    query: { category: params.category, limit: params.limit, cursor: params.cursor },
+    options: requestOptions
+  });
+  async function* allEntries(params = {}, requestOptions) {
+    let cursor = null;
+    do {
+      const page = await list(
+        { ...params, limit: params.limit ?? 50, cursor },
+        requestOptions
+      );
+      yield* page.entries;
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+  return {
+    workspace,
+    product,
+    list,
+    allEntries,
+    getEntry: (slug, requestOptions) => http.request({
+      method: "GET",
+      path: `${base}/entries/${seg(required(slug, "slug"))}`,
+      options: requestOptions
+    }),
+    listProducts: (requestOptions) => http.request({
+      method: "GET",
+      path: `${root}/products`,
+      options: requestOptions
+    })
+  };
+}
+
+// src/seen.ts
+function browserStorage() {
+  try {
+    const storage = globalThis.localStorage;
+    return storage ?? null;
+  } catch {
+    return null;
+  }
+}
+function createSeenTracker(workspace, storage = browserStorage(), product) {
+  const key = `sd-changelog-seen:${workspace.toLowerCase()}${product ? `:${product.toLowerCase()}` : ""}`;
+  const lastSeen = () => {
+    try {
+      return storage?.getItem(key) ?? null;
+    } catch {
+      return null;
+    }
+  };
+  return {
+    lastSeen,
+    markSeen(publishedAt) {
+      try {
+        storage?.setItem(key, publishedAt);
+      } catch {
+      }
+    },
+    unseen(entries) {
+      const seen = lastSeen();
+      if (!seen) return 0;
+      return entries.filter((entry) => entry.publishedAt > seen).length;
+    }
+  };
+}
+var CATEGORY_LABELS = {
+  en: { new: "New", improved: "Improved", fixed: "Fixed", announcement: "Announcement" },
+  de: { new: "Neu", improved: "Verbessert", fixed: "Behoben", announcement: "Ank\xFCndigung" }
+};
+var CATEGORY_COLORS = {
+  new: "#2563eb",
+  improved: "#7c3aed",
+  fixed: "#16a34a",
+  announcement: "#d97706"
+};
+function categoryLabel(category, locale = "en") {
+  return CATEGORY_LABELS[locale.toLowerCase().startsWith("de") ? "de" : "en"][category];
+}
+
+exports.CATEGORY_COLORS = CATEGORY_COLORS;
+exports.CATEGORY_LABELS = CATEGORY_LABELS;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.SolutionDeskError = SolutionDeskError;
+exports.browserStorage = browserStorage;
+exports.categoryLabel = categoryLabel;
+exports.createChangelogClient = createChangelogClient;
+exports.createMemoryEtagCache = createMemoryEtagCache;
+exports.createSeenTracker = createSeenTracker;

package/dist/index.d.cts

@@ -0,0 +1,273 @@
+/**
+ * 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;
+
+/**
+ * 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;
+    /** The release this change ships in (`2.3.0`); empty when it isn't tied to one. */
+    releaseVersion: string;
+    /** Where the release can be downloaded (an app store page, GitHub Releases …), or null. */
+    downloadUrl: string | null;
+    /** 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 the ones uploaded to the entry (with
+     * `srcset`). Ready for `innerHTML` / `dangerouslySetInnerHTML`. Empty when
+     * there are no details.
+     */
+    html: string;
+    /** The entry on the workspace's hosted changelog page. */
+    url: string;
+}
+/** A product with its own changelog. */
+interface PublicChangelogProduct {
+    name: string;
+    slug: string;
+    /** One sentence about the product. May be empty. */
+    description: string;
+    /** The product's hosted changelog page. */
+    pageUrl: string;
+    /** The default product: addresses without a product show this one. */
+    isDefault: boolean;
+}
+/** `GET /v1/changelog/{workspace}/products` — every product, the default first. */
+interface PublicChangelogProductsPayload {
+    workspace: {
+        name: string;
+        slug: string;
+        logoUrl: string | null;
+    };
+    products: PublicChangelogProduct[];
+}
+/**
+ * `GET /v1/changelog/{workspace}/{product}` — a product's settings and one
+ * page of its entries (`GET /v1/changelog/{workspace}`: the default product).
+ */
+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 product these entries belong to. */
+    product: PublicChangelogProduct;
+    /** 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 product's 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}/{product}/entries/{slug}`. */
+interface PublicChangelogEntryPayload {
+    /** The product whose changelog shows the entry. */
+    product: PublicChangelogProduct;
+    entry: PublicChangelogEntry;
+}
+
+interface ChangelogClientOptions extends BaseClientOptions {
+    /** Your workspace's slug — the `acme` in `https://api.solutiondesk.io/v1/changelog/acme`. */
+    workspace: string;
+    /**
+     * The product whose changelog to read (its web address, e.g. `acme-mobile`).
+     * Without it, the workspace's default product.
+     */
+    product?: 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 product this client reads, or undefined for the default product. */
+    readonly product: string | undefined;
+    /**
+     * The product's settings and one page of its published entries, newest first
+     * (`GET /v1/changelog/{workspace}/{product}`). Throws a `SolutionDeskError`
+     * with status 404 when the workspace or product doesn't exist or the
+     * 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 of the product (`…/{product}/entries/{slug}`; without
+     * a product, of any product). Throws a `SolutionDeskError` with status 404
+     * for an unknown or unpublished entry.
+     */
+    getEntry(slug: string, options?: RequestOptions): Promise<PublicChangelogEntryPayload>;
+    /** Every product of the workspace, the default first (`GET /v1/changelog/{workspace}/products`). */
+    listProducts(options?: RequestOptions): Promise<PublicChangelogProductsPayload>;
+}
+/**
+ * A client for the public changelog API — no key, no login; only published
+ * entries. Safe in the browser and on the server.
+ *
+ * @example
+ * const changelog = createChangelogClient({ workspace: "acme", product: "acme-mobile" });
+ * const { entries, nextCursor } = await changelog.list({ limit: 10 });
+ */
+declare function createChangelogClient(options: ChangelogClientOptions): ChangelogClient;
+
+/** Where "last seen" is kept — `window.localStorage`, `sessionStorage` or your own. */
+interface SeenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * Remembers when a visitor last looked at the changelog, so you can show a
+ * "new" badge. It lives where you keep it (by default the browser's
+ * `localStorage`); nothing about the visitor is sent to SolutionDesk.
+ */
+interface SeenTracker {
+    /** ISO time of the newest entry the visitor has seen, or null before the first look. */
+    lastSeen(): string | null;
+    /** Remember that the visitor has seen everything up to `publishedAt`. */
+    markSeen(publishedAt: string): void;
+    /**
+     * How many of `entries` are new to the visitor. On the very first visit
+     * nothing counts as new — call {@link SeenTracker.markSeen} with the newest
+     * entry then, so the next entry is the first one that counts.
+     */
+    unseen(entries: readonly {
+        publishedAt: string;
+    }[]): number;
+}
+/** The browser's `localStorage`, or null (server rendering, privacy mode). */
+declare function browserStorage(): SeenStorage | null;
+/**
+ * A {@link SeenTracker} for one workspace's product. Uses the key
+ * `sd-changelog-seen:<workspace>` (default product) or
+ * `sd-changelog-seen:<workspace>:<product>` — the same ones the SolutionDesk
+ * widget uses, so a visitor who opened either sees no badge in the other.
+ */
+declare function createSeenTracker(workspace: string, storage?: SeenStorage | null, product?: string): SeenTracker;
+type ChangelogLocale = "de" | "en";
+/** The category names the hosted page uses, for your own UI. */
+declare const CATEGORY_LABELS: Record<ChangelogLocale, Record<ChangelogCategory, string>>;
+/** The category colors of the hosted page and the dashboard (hex). */
+declare const CATEGORY_COLORS: Record<ChangelogCategory, string>;
+/** A category's name in German (`de*`) or English (everything else). */
+declare function categoryLabel(category: ChangelogCategory, locale?: string): string;
+
+export { type BaseClientOptions, CATEGORY_COLORS, CATEGORY_LABELS, type CachedResponse, type ChangelogCategory, type ChangelogClient, type ChangelogClientOptions, type ChangelogLocale, type ChangelogWidgetPosition, DEFAULT_BASE_URL, type EtagCache, type FetchInitLike, type FetchLike, type FetchResponseLike, type ListEntriesParams, type PublicChangelogEntry, type PublicChangelogEntryPayload, type PublicChangelogPayload, type PublicChangelogProduct, type PublicChangelogProductsPayload, type RequestOptions, type SeenStorage, type SeenTracker, SolutionDeskError, browserStorage, categoryLabel, createChangelogClient, createMemoryEtagCache, createSeenTracker };