@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Okafor Obinna Kingsley
+
+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,3 +1,81 @@
-# Temporary Holding Version
+# @kingsleyweb/bun-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Every bun-node browser UI in one package, each behind its own subpath. A UI is
+a React app prebuilt into `dist/<ui>/` and served by a bun-common router you
+mount on any bun-common `BunHttpAdapter`, `BunRouter` or bun-nest's
+`BunHttpAdapter`: hash-named immutable assets, computed Subresource Integrity
+and a strict Content-Security-Policy. React and TanStack Query are bundled, so
+the host installs neither and has no build step.
+
+| Subpath | What | Needs |
+|---|---|---|
+| `@kingsleyweb/bun-ui/jobs` | `jobsUi()`: the management UI for the `@kingsleyweb/bun-jobs` management API. [Guide](guides/jobs.md) | `@kingsleyweb/bun-jobs` |
+| `@kingsleyweb/bun-ui/jobs/browser` | the jobs UI's browser-safe config contract (`JobsUiConfig`, `JOBS_UI_CONFIG_ELEMENT_ID`, …) | nothing |
+| `@kingsleyweb/bun-ui/docs` | `docsUi()`: a self-hosted viewer for one OpenAPI 3.1 or AsyncAPI 3.0 document. [Guide](guides/docs.md) | nothing |
+| `@kingsleyweb/bun-ui/docs/browser` | the docs viewer's browser-safe config contract and the `unauthorized` helpers | nothing |
+| `@kingsleyweb/bun-ui/docs/hosted` | what bun-common's `docsRouter` `"self-hosted"` viewer loads to serve the viewer itself | nothing |
+| `@kingsleyweb/bun-ui/docs/embed`, `/docs/embed/{routing,router,context,permissions,client,errors,unauthorized}` | the viewer's screens as source, for a React app that bundles them into its own UI | the host's `react` and `@tanstack/react-query` |
+| `@kingsleyweb/bun-ui` | what every UI shares, browser-safe: `UiTheme`, the `unauthorized` option's types and defaults, `ASSET_CACHE_CONTROL` | nothing |
+
+Each UI's domain package is an **optional** peer that only its own subpath
+needs: install `@kingsleyweb/bun-jobs` to use `/jobs`. An app that mounts one
+UI never loads another's code or bundle.
+
+## Install
+
+```bash
+bun add @kingsleyweb/bun-ui                          # for /docs
+bun add @kingsleyweb/bun-ui @kingsleyweb/bun-jobs   # for /jobs
+```
+
+Requires Bun >= 1.4.2. Bun runs the shipped TypeScript source in `lib/`; your
+type checker reads the built declarations in `dts/`, which describe `lib/`
+only, so no React or TanStack type reaches your project.
+
+## Quick start: the jobs UI
+
+```ts
+import { BunHttpAdapter } from "@kingsleyweb/bun-common";
+import { createJobsApi } from "@kingsleyweb/bun-jobs";
+import { jobsUi } from "@kingsleyweb/bun-ui/jobs";
+
+const api = createJobsApi({ jobs, basePath: "/admin/jobs-api", authorize });
+const ui = jobsUi({ api, basePath: "/admin/jobs" });
+
+const app = new BunHttpAdapter();
+app.use(api.basePath, api.router);
+app.use(ui.basePath, ui.router);
+await app.listen(3000);
+```
+
+[guides/jobs.md](guides/jobs.md) has every option, the screens, the
+permissions each element needs and the security notes.
+
+## Quick start: the docs viewer
+
+```ts
+import { BunRouter } from "@kingsleyweb/bun-common";
+import { docsUi } from "@kingsleyweb/bun-ui/docs";
+
+const app = new BunRouter();
+const ui = docsUi({ document: "/api/openapi.json", basePath: "/docs" });
+app.use(ui.basePath, ui.router);
+```
+
+bun-common's `docsRouter({ viewer: { openapi: "self-hosted" } })` serves the
+same viewer from your own origin once `@kingsleyweb/bun-ui` is installed.
+[guides/docs.md](guides/docs.md) has every option and the embedding guide.
+
+## Layout
+
+The package is layered: `lib/<ui>/` is a UI's server (and `lib/<ui>/browser/`
+its browser-safe half), `app/<ui>/` its React app, `__tests__/<ui>/` its tests
+and `dist/<ui>/` its prebuilt bundle. `lib/kit/` holds what the UIs share; it
+never imports a domain package.
+
+## Building
+
+`bun scripts/build.ts` writes each UI's bundle into `dist/<ui>/` and
+`bun run build:types` the declarations into `dts/`; `prepack` runs both, so a
+pack publishes both. Both directories are gitignored. In the repo, a UI with
+no `dist/<ui>/` builds in memory on its first request.

package/app/docs/App.tsx

@@ -0,0 +1,72 @@
+import { QueryClientProvider } from "@tanstack/react-query";
+import type { QueryClient } from "@tanstack/react-query";
+import type { FetchLike } from "./api/client";
+import type { DocsUiConfig } from "../../lib/docs/browser/config.ts";
+import { useEffect, useMemo } from "react";
+import { DocsFetchContext, DocsUiConfigContext } from "./context";
+import { RouterProvider } from "./router";
+import {
+  createUnauthorizedRedirect,
+  watchAuthFailures,
+} from "../kit/unauthorized";
+import { DocsViewer } from "./screens/docs/viewer";
+import { findSearchBox, shortcutFor } from "./shortcuts";
+
+/** Props of {@link App}. */
+export interface AppProps {
+  /** The injected configuration. */
+  config: DocsUiConfig;
+  /** The query client (tests pass one without retries). */
+  queryClient: QueryClient;
+  /** The `fetch` every request goes through (tests inject one). Defaults to `globalThis.fetch`. */
+  fetch?: FetchLike;
+}
+
+/** The `/` shortcut: focus the screen's search box. */
+function useSearchShortcut() {
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (shortcutFor(event) === "focus-search") {
+        const box = findSearchBox(document);
+        if (box) {
+          event.preventDefault();
+          box.focus();
+        }
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+}
+
+/**
+ * The whole viewer: providers, routing, the document. With
+ * `config.unauthorized`, a failed document read whose status it lists sends
+ * the browser to the sign-in target, once (`unauthorized.ts`). Only the
+ * viewer's own queries reach the cache: the try-it panel's calls do not, so
+ * the documented API's 401 to a tried request never redirects.
+ */
+export function App({ config, queryClient, fetch }: AppProps) {
+  useSearchShortcut();
+  const unauthorized = useMemo(
+    () => createUnauthorizedRedirect(config.unauthorized, config.basePath),
+    [config.unauthorized, config.basePath],
+  );
+  useEffect(
+    () => watchAuthFailures(queryClient, unauthorized),
+    [queryClient, unauthorized],
+  );
+  return (
+    <DocsUiConfigContext value={config}>
+      <DocsFetchContext value={fetch ?? null}>
+        <QueryClientProvider client={queryClient}>
+          <RouterProvider basePath={config.basePath}>
+            <div className="docs-viewer">
+              <DocsViewer />
+            </div>
+          </RouterProvider>
+        </QueryClientProvider>
+      </DocsFetchContext>
+    </DocsUiConfigContext>
+  );
+}

package/app/docs/api/client.ts

@@ -0,0 +1,303 @@
+import { JSON_METHODS, MUTATING_METHODS } from "./contract";
+import { ApiError, isProblem } from "./errors";
+
+/**
+ * The viewer's HTTP client: it fetches the document, and sends the try-it
+ * panel's requests. Same-origin credentials, `Accept: application/json`
+ * always, `Content-Type: application/json` on POST/PUT/PATCH (bodiless ones
+ * included), and the configured CSRF header on every mutation.
+ */
+
+/** An HTTP method the client sends. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** A scalar query value. */
+export type QueryScalar = string | number | boolean;
+
+/**
+ * A query-string value: arrays become repeated keys (`state=a&state=b`), an
+ * empty array becomes `key=`, and `undefined`/`null` are left out.
+ */
+export type QueryValue =
+  QueryScalar | readonly QueryScalar[] | null | undefined;
+
+/** The query of one request. */
+export type QueryParams = Readonly<Record<string, QueryValue>>;
+
+/** Options of one {@link DocsClient.request}. */
+export interface RequestOptions {
+  /** Query parameters; see {@link QueryValue}. */
+  query?: QueryParams;
+  /** A JSON body. `undefined` sends none (the `Content-Type` still goes on POST/PUT/PATCH). */
+  body?: unknown;
+  /** Aborts the request (TanStack Query passes one). An abort rejects with the fetch's own `AbortError`, never an {@link ApiError}. */
+  signal?: AbortSignal;
+}
+
+/** One response as {@link DocsClient.requestRaw} resolves it. */
+export interface RawResponse {
+  /** Whether the status is 2xx. */
+  ok: boolean;
+  /** The HTTP status received. */
+  status: number;
+  /** The status text received (often `""` over HTTP/2). */
+  statusText: string;
+  /** The response headers the caller can see, lower-cased names in alphabetical order. A browser hides `Set-Cookie`, and cross-origin ones not in `Access-Control-Expose-Headers`. */
+  headers: Record<string, string>;
+  /** The body: parsed JSON when the `Content-Type` is JSON and it parses, the text otherwise, `undefined` when empty. */
+  body: unknown;
+  /** For a non-2xx status, the {@link ApiError} `request` would have thrown (a problem's fields verbatim); `undefined` on success. */
+  error: ApiError | undefined;
+  /** Milliseconds from sending to the body having been read. */
+  durationMs: number;
+}
+
+/** The `fetch` the client calls; injectable for tests. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+/** A client for the one server the viewer talks to. */
+export interface DocsClient {
+  /** The base URL requests are prefixed with. */
+  readonly base: string;
+  /** Sends one request; resolves the parsed JSON (or `undefined` for a 204), rejects with an {@link ApiError}. */
+  request: <T>(
+    method: HttpMethod,
+    path: string,
+    options?: RequestOptions,
+  ) => Promise<T>;
+  /**
+   * Sends one request like {@link DocsClient.request}, with the same headers,
+   * credentials and problem+json parsing, and resolves the whole response
+   * instead of only its body. An error status **resolves** (with `ok: false`
+   * and the {@link ApiError} `request` would have thrown in `error`); only a
+   * network failure rejects (an {@link ApiError} of kind `network`), and an
+   * abort rejects with the fetch's own `AbortError`.
+   */
+  requestRaw: (
+    method: HttpMethod,
+    path: string,
+    options?: RequestOptions,
+  ) => Promise<RawResponse>;
+}
+
+/** The value sent in the CSRF header. An API accepts any non-empty value. */
+export const CSRF_HEADER_VALUE = "1";
+
+/** Serialises a query: repeated keys for arrays, `undefined`/`null` skipped. Returns `""` or `"?…"`. */
+export function serializeQuery(query: QueryParams | undefined): string {
+  if (!query) {
+    return "";
+  }
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const items = value as readonly QueryScalar[];
+      if (items.length === 0) {
+        params.append(key, "");
+      }
+      for (const item of items) {
+        params.append(key, String(item));
+      }
+      continue;
+    }
+    params.append(key, String(value));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+
+/** Percent-encodes one path segment (`/` becomes `%2F`). */
+export function segment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/** Whether a `Content-Type` names JSON (`application/json` or any `+json`). */
+function isJsonType(contentType: string): boolean {
+  const media = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return media === "application/json" || media.endsWith("+json");
+}
+
+/** Whether an error is the fetch's abort, which must propagate untouched. */
+function isAbort(error: unknown, signal: AbortSignal | undefined): boolean {
+  return (
+    signal?.aborted === true ||
+    (error instanceof Error && error.name === "AbortError") ||
+    (typeof DOMException !== "undefined" &&
+      error instanceof DOMException &&
+      error.name === "AbortError")
+  );
+}
+
+/** Parses JSON text, or returns `undefined` when it is not JSON. */
+function tryParse(text: string): { value: unknown } | undefined {
+  try {
+    return { value: JSON.parse(text) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Turns an error response into an {@link ApiError}. */
+function errorFromResponse(response: Response, text: string, path: string) {
+  const parsed = isJsonType(response.headers.get("content-type") ?? "")
+    ? tryParse(text)
+    : undefined;
+  if (parsed && isProblem(parsed.value)) {
+    return ApiError.fromProblem({ ...parsed.value, status: response.status });
+  }
+  const snippet = text.trim().slice(0, 300);
+  return new ApiError({
+    kind: "http",
+    status: response.status,
+    code: `HTTP_${response.status}`,
+    title: response.statusText || `Request failed (${response.status})`,
+    detail: snippet || undefined,
+    instance: path,
+  });
+}
+
+/** Options of {@link createDocsClient}. */
+export interface DocsClientOptions {
+  /** The base URL requests are prefixed with (the document's resolved server, or the document's own URL for the document fetch). */
+  base: string;
+  /** The CSRF header mutations carry, or `null`. */
+  csrfHeader: string | null;
+  /** The `fetch` to use. Defaults to `globalThis.fetch`, looked up per call so a test can replace it. */
+  fetch?: FetchLike;
+}
+
+/**
+ * Creates the client for one base URL. A relative `path` joins the base; a
+ * `path` that is itself an absolute URL is sent as it is (a document URL the
+ * operator configured).
+ */
+export function createDocsClient(options: DocsClientOptions): DocsClient {
+  const base = options.base.replace(/\/+$/, "");
+
+  /** Builds the URL and `RequestInit` of one request: every header rule lives here. */
+  function prepare(
+    method: HttpMethod,
+    path: string,
+    { query, body, signal }: RequestOptions,
+  ): { url: string; init: RequestInit } {
+    const target = /^https?:\/\//.test(path) ? path : `${base}${path}`;
+    const url = `${target}${serializeQuery(query)}`;
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (JSON_METHODS.has(method)) {
+      headers["Content-Type"] = "application/json";
+    }
+    if (options.csrfHeader && MUTATING_METHODS.has(method)) {
+      headers[options.csrfHeader] = CSRF_HEADER_VALUE;
+    }
+    const init: RequestInit = {
+      method,
+      headers,
+      credentials: "same-origin",
+    };
+    if (body !== undefined) {
+      init.body = JSON.stringify(body);
+    }
+    if (signal) {
+      init.signal = signal;
+    }
+    return { url, init };
+  }
+
+  /** Calls `fetch`; a failure other than an abort becomes a `network` {@link ApiError}. */
+  async function send(
+    url: string,
+    init: RequestInit,
+    path: string,
+  ): Promise<Response> {
+    const fetcher = options.fetch ?? globalThis.fetch;
+    try {
+      return await fetcher(url, init);
+    } catch (error) {
+      if (isAbort(error, init.signal ?? undefined)) {
+        throw error;
+      }
+      throw new ApiError({
+        kind: "network",
+        status: 0,
+        code: "NETWORK_ERROR",
+        title: "The server could not be reached",
+        detail: error instanceof Error ? error.message : String(error),
+        instance: path,
+        cause: error,
+      });
+    }
+  }
+
+  async function request<T>(
+    method: HttpMethod,
+    path: string,
+    requestOptions: RequestOptions = {},
+  ): Promise<T> {
+    const { url, init } = prepare(method, path, requestOptions);
+    const response = await send(url, init, path);
+
+    if (response.status === 204 || response.status === 205) {
+      return undefined as T;
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw errorFromResponse(response, text, path);
+    }
+    if (text === "") {
+      return undefined as T;
+    }
+    const parsed = isJsonType(response.headers.get("content-type") ?? "")
+      ? tryParse(text)
+      : undefined;
+    if (!parsed) {
+      throw new ApiError({
+        kind: "parse",
+        status: response.status,
+        code: "INVALID_RESPONSE",
+        title: "The server answered something other than JSON",
+        detail: text.trim().slice(0, 300) || undefined,
+        instance: path,
+      });
+    }
+    return parsed.value as T;
+  }
+
+  async function requestRaw(
+    method: HttpMethod,
+    path: string,
+    requestOptions: RequestOptions = {},
+  ): Promise<RawResponse> {
+    const { url, init } = prepare(method, path, requestOptions);
+    const started = performance.now();
+    const response = await send(url, init, path);
+    const text =
+      response.status === 204 || response.status === 205
+        ? ""
+        : await response.text();
+    const durationMs = performance.now() - started;
+    const parsed =
+      text !== "" && isJsonType(response.headers.get("content-type") ?? "")
+        ? tryParse(text)
+        : undefined;
+    const headers: Record<string, string> = {};
+    for (const [name, value] of [...response.headers.entries()].sort(
+      ([a, b]) => (a < b ? -1 : a > b ? 1 : 0),
+    )) {
+      headers[name.toLowerCase()] = value;
+    }
+    return {
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+      body: parsed ? parsed.value : text === "" ? undefined : text,
+      error: response.ok ? undefined : errorFromResponse(response, text, path),
+      durationMs,
+    };
+  }
+
+  return { base, request, requestRaw };
+}

package/app/docs/api/contract.ts

@@ -0,0 +1,24 @@
+/**
+ * Constants of the viewer's own HTTP layer: which methods mutate (a try-it
+ * confirms them), and which must carry `Content-Type: application/json` even
+ * when bodiless. Generic HTTP, shared with no one: the documented API's own
+ * constants are its own.
+ */
+
+/** HTTP methods treated as mutations: every one but `GET`/`HEAD`/`OPTIONS`. */
+export const MUTATING_METHODS: ReadonlySet<string> = new Set([
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+]);
+
+/** Methods that carry `Content-Type: application/json` even when bodiless. */
+export const JSON_METHODS: ReadonlySet<string> = new Set([
+  "POST",
+  "PUT",
+  "PATCH",
+]);
+
+/** The last instant a `Date` holds. */
+export const MAX_DATE_MS = 8_640_000_000_000_000;

package/app/docs/api/docs.ts

@@ -0,0 +1,38 @@
+import type { DocsClient } from "./client";
+
+/**
+ * A spec document as JSON. The viewers narrow the parts they render with
+ * their own models.
+ */
+export type SpecDocument = Record<string, unknown>;
+
+/** Query keys of the document read, under `["docs"]`. */
+export const docsKeys = {
+  /** Every docs read. */
+  all: ["docs"] as const,
+  /** The one document at a URL. */
+  document: (url: string) => ["docs", "document", url] as const,
+} satisfies Record<string, unknown>;
+
+/** The document's kind, read from its own marker field. */
+export type DocumentKind = "openapi" | "asyncapi";
+
+/** What the document is: OpenAPI 3.1 when it carries `openapi`, AsyncAPI 3.0 for `asyncapi`, `null` when neither. */
+export function documentKind(doc: SpecDocument): DocumentKind | null {
+  if (typeof doc.asyncapi === "string") {
+    return "asyncapi";
+  }
+  if (typeof doc.openapi === "string") {
+    return "openapi";
+  }
+  return null;
+}
+
+/** `GET <documentUrl>`: the one document the viewer shows. */
+export function getDocument(
+  client: DocsClient,
+  url: string,
+  signal?: AbortSignal,
+): Promise<SpecDocument> {
+  return client.request<SpecDocument>("GET", url, { signal });
+}

package/app/docs/api/errors.ts

@@ -0,0 +1,144 @@
+/**
+ * Every failed request the viewer makes, whatever went wrong. An RFC 9457
+ * problem response keeps its fields verbatim; anything else is mapped onto
+ * the same shape so a screen has one thing to render.
+ */
+
+/** A validation issue inside a problem. */
+export interface ProblemIssueDto {
+  /** Which part of the request failed. */
+  target: string;
+  /** Dotted path within the target, or `""` for the target itself. */
+  path: string;
+  /** Human-readable description. */
+  message: string;
+}
+
+/** An `application/problem+json` body, as far as the viewer reads it. */
+export interface ProblemDto {
+  /** The HTTP status. */
+  status: number;
+  /** The machine code. */
+  code: string;
+  /** The short title. */
+  title: string;
+  /** The human detail, when there is one. */
+  detail?: string;
+  /** The problem's `type` URI, when there is one. */
+  type?: string;
+  /** Validation issues. */
+  issues?: ProblemIssueDto[];
+  /** Safe, whitelisted context. */
+  context?: Record<string, unknown>;
+  /** The request path that failed. */
+  instance?: string;
+}
+
+/** Where an {@link ApiError} came from. */
+export type ApiErrorKind =
+  /** The API answered with an `application/problem+json` body. */
+  | "problem"
+  /** The API (or something in front of it) answered an error that was not problem+json. */
+  | "http"
+  /** No response arrived: offline, DNS, CORS, connection reset. */
+  | "network"
+  /** A 2xx whose body was not the JSON it should have been. */
+  | "parse";
+
+/** Fields an {@link ApiError} is built from. */
+export interface ApiErrorInit {
+  /** Where the error came from. */
+  kind: ApiErrorKind;
+  /** HTTP status, or `0` for a network error. */
+  status: number;
+  /** Machine code: the problem's `code`, or `NETWORK_ERROR` / `HTTP_<status>` / `INVALID_RESPONSE`. */
+  code: string;
+  /** Short title. */
+  title: string;
+  /** Human detail, when there is one. */
+  detail?: string;
+  /** The problem's `type` URI, when it was a problem. */
+  type?: string;
+  /** Validation issues. */
+  issues?: ProblemIssueDto[];
+  /** The problem's whitelisted context. */
+  context?: Record<string, unknown>;
+  /** The request path that failed. */
+  instance?: string;
+  /** The underlying error (network/parse failures). */
+  cause?: unknown;
+}
+
+/** One failed request. */
+export class ApiError extends Error {
+  /** Where the error came from. */
+  readonly kind: ApiErrorKind;
+  /** HTTP status, or `0` for a network error. */
+  readonly status: number;
+  /** Machine code, e.g. `HTTP_404`. */
+  readonly code: string;
+  /** Short, stable title. */
+  readonly title: string;
+  /** Human detail for this occurrence. */
+  readonly detail: string | undefined;
+  /** The problem's `type` URI, when it was a problem. */
+  readonly type: string | undefined;
+  /** Validation issues. */
+  readonly issues: ProblemIssueDto[];
+  /** Whitelisted context. */
+  readonly context: Record<string, unknown>;
+  /** The request path that failed. */
+  readonly instance: string | undefined;
+
+  constructor(init: ApiErrorInit) {
+    super(init.detail ?? init.title, { cause: init.cause });
+    this.name = "ApiError";
+    this.kind = init.kind;
+    this.status = init.status;
+    this.code = init.code;
+    this.title = init.title;
+    this.detail = init.detail;
+    this.type = init.type;
+    this.issues = init.issues ?? [];
+    this.context = init.context ?? {};
+    this.instance = init.instance;
+  }
+
+  /** Builds one from a problem body. */
+  static fromProblem(problem: ProblemDto): ApiError {
+    return new ApiError({
+      kind: "problem",
+      status: problem.status,
+      code: problem.code,
+      title: problem.title,
+      detail: problem.detail,
+      type: problem.type,
+      issues: problem.issues,
+      context: problem.context,
+      instance: problem.instance,
+    });
+  }
+
+  /** Whether the caller is not signed in or not allowed (401/403). */
+  get isAuth(): boolean {
+    return this.status === 401 || this.status === 403;
+  }
+}
+
+/** Whether a value is an {@link ApiError}. */
+export function isApiError(value: unknown): value is ApiError {
+  return value instanceof ApiError;
+}
+
+/** Whether a parsed body has the fields a problem must carry. */
+export function isProblem(value: unknown): value is ProblemDto {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.status === "number" &&
+    typeof record.code === "string" &&
+    typeof record.title === "string"
+  );
+}