@solutiondesk/changelog 0.0.0 → 1.0.0-9fc05ac

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * 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;
+    /** 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;
+}
+
+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>;
+}
+/**
+ * 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" });
+ * 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. Uses the key
+ * `sd-changelog-seen:<workspace>` — the same one the SolutionDesk widget uses,
+ * so a visitor who opened either sees no badge in the other.
+ */
+declare function createSeenTracker(workspace: string, storage?: SeenStorage | null): 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 RequestOptions, type SeenStorage, type SeenTracker, SolutionDeskError, browserStorage, categoryLabel, createChangelogClient, createMemoryEtagCache, createSeenTracker };

package/dist/index.js

@@ -0,0 +1,245 @@
+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 http = createHttp(options);
+  const base = `/changelog/${seg(workspace)}`;
+  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,
+    list,
+    allEntries,
+    getEntry: (slug, requestOptions) => http.request({
+      method: "GET",
+      path: `${base}/entries/${seg(required(slug, "slug"))}`,
+      options: requestOptions
+    })
+  };
+}
+
+// src/seen.ts
+function browserStorage() {
+  try {
+    const storage = globalThis.localStorage;
+    return storage ?? null;
+  } catch {
+    return null;
+  }
+}
+function createSeenTracker(workspace, storage = browserStorage()) {
+  const key = `sd-changelog-seen:${workspace.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];
+}
+
+export { CATEGORY_COLORS, CATEGORY_LABELS, DEFAULT_BASE_URL, SolutionDeskError, browserStorage, categoryLabel, createChangelogClient, createMemoryEtagCache, createSeenTracker };