@better-forge/ui 0.0.0-stage → 0.1.0

package/dist/shell/AdminShell.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Fragment, Suspense, useCallback, useEffect, useRef, useState } from 'react';
+import { Outlet, NavLink, useNavigate, useLocation, Link } from 'react-router-dom';
+import { api, clearSession, getCurrentUser } from '../api/client';
+import { LoadingState } from '../components/ui/StateViews';
+import { WhatsNew, markWhatsNewSeen, pendingWhatsNew } from '../components/WhatsNew';
+import { useDarkMode } from '../hooks/useDarkMode';
+import { useDatePrefs } from '../lib/dateFormat';
+const ICON_STYLE = { fontSize: '20px' };
+function Brand({ brand }) {
+    return (_jsxs("div", { className: "flex items-center gap-3 min-w-0", children: [_jsx("img", { src: brand.iconUrl, alt: brand.name, style: { width: '40px', height: '40px', objectFit: 'contain', flexShrink: 0 } }), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "font-headline font-bold text-base leading-none", style: { color: 'var(--m3-on-surface)' }, children: brand.title }), _jsx("p", { className: "text-xs leading-none mt-1", style: { color: 'var(--m3-secondary)' }, children: brand.subtitle })] })] }));
+}
+/** Section links plus the Settings / theme / logout footer, shared by the desktop sidebar and the mobile drawer. */
+function NavContent({ config, sections, isDark, onToggleDark, onLogout }) {
+    return (_jsxs(_Fragment, { children: [_jsx("nav", { "aria-label": "Main", className: "flex-1 px-3 overflow-y-auto pb-2", children: sections.map((section, si) => (_jsxs("div", { className: si > 0 ? 'mt-4' : '', children: [_jsx("p", { className: "px-4 pb-1 font-mono uppercase tracking-widest", style: { fontSize: '10px', color: 'var(--m3-outline)', letterSpacing: '0.1em' }, children: section.label }), _jsx("div", { className: "space-y-0.5", children: section.items.map((item) => (_jsx(NavLink, { to: item.to, end: item.to === config.homePath, className: "admin-nav-item", children: ({ isActive }) => (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined flex-shrink-0", style: { ...ICON_STYLE, fontVariationSettings: isActive ? "'FILL' 1" : "'FILL' 0" }, children: item.icon }), _jsx("span", { className: "font-sans", children: item.label })] })) }, item.to))) })] }, section.label))) }), _jsxs("div", { className: "px-3 pb-4 pt-4 space-y-0.5", style: { borderTop: '1px solid var(--m3-outline-variant)' }, children: [config.externalLinks.map((link) => (_jsxs("a", { href: link.href(), target: "_blank", rel: "noopener", className: "admin-nav-item", children: [_jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined flex-shrink-0", style: ICON_STYLE, children: link.icon }), _jsx("span", { className: "font-sans", children: link.label })] }, link.label))), _jsxs(Link, { to: config.settingsPath, className: "admin-nav-item", children: [_jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined flex-shrink-0", style: ICON_STYLE, children: "manage_accounts" }), _jsx("span", { className: "font-sans", children: "Settings" })] }), _jsxs("button", { type: "button", onClick: onToggleDark, className: "admin-nav-item", children: [_jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined flex-shrink-0", style: ICON_STYLE, children: isDark ? 'light_mode' : 'dark_mode' }), _jsx("span", { className: "font-sans", children: isDark ? 'Light Mode' : 'Dark Mode' })] }), _jsxs("button", { type: "button", onClick: onLogout, className: "admin-nav-item admin-nav-danger", children: [_jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined flex-shrink-0", style: ICON_STYLE, children: "logout" }), _jsx("span", { className: "font-sans", children: "Logout" })] })] })] }));
+}
+function MobileDrawer({ onClose, returnFocusRef, ...nav }) {
+    const closeRef = useRef(null);
+    useEffect(() => {
+        closeRef.current?.focus();
+        const returnTo = returnFocusRef.current;
+        const onKeyDown = (event) => { if (event.key === 'Escape')
+            onClose(); };
+        document.addEventListener('keydown', onKeyDown);
+        return () => {
+            document.removeEventListener('keydown', onKeyDown);
+            returnTo?.focus();
+        };
+    }, [onClose, returnFocusRef]);
+    return (_jsxs("div", { className: "md:hidden fixed inset-0 z-50", children: [_jsx("div", { "data-testid": "nav-drawer-overlay", className: "admin-drawer-overlay absolute inset-0", style: { background: 'rgba(0,0,0,0.55)' }, onClick: onClose }), _jsxs("div", { id: "admin-nav-drawer", role: "dialog", "aria-modal": "true", "aria-label": "Navigation", className: "admin-drawer-panel absolute inset-y-0 left-0 flex flex-col w-72 max-w-[85vw]", style: { background: 'var(--m3-surface-container-low)', boxShadow: '0 8px 32px rgba(0,0,0,0.18)' }, children: [_jsxs("div", { className: "flex items-center justify-between gap-2 px-4 pt-4 mb-4", children: [_jsx(Brand, { brand: nav.config.brand }), _jsx("button", { ref: closeRef, type: "button", onClick: onClose, "aria-label": "Close navigation", className: "btn-icon", children: _jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined", children: "close" }) })] }), _jsx(NavContent, { ...nav })] })] }));
+}
+/**
+ * The signed-in shell of an admin interface: a sidebar (a drawer on a phone) with the sections the user's role may see,
+ * the footer links, the theme switch and logout, and the page below it. The sections, roles, brand and links are the
+ * application's; the page is whatever the router renders in the `Outlet`.
+ */
+export function createAdminShell(config) {
+    return function AdminShell() {
+        const navigate = useNavigate();
+        const location = useLocation();
+        const [isDark, toggleDark] = useDarkMode();
+        const datePrefs = useDatePrefs();
+        const currentUser = getCurrentUser();
+        const userRank = config.roleRank[currentUser?.role ?? ''] ?? 0;
+        // The drawer remembers the path it was opened on, so navigating anywhere closes it without an effect.
+        const [drawerPath, setDrawerPath] = useState(null);
+        const drawerOpen = drawerPath === location.pathname;
+        const menuButtonRef = useRef(null);
+        const closeDrawer = useCallback(() => setDrawerPath(null), []);
+        const navSections = config.sections
+            .map((section) => ({
+            ...section,
+            items: section.items.filter((item) => userRank >= (config.roleRank[item.minRole] ?? 99)),
+        }))
+            .filter((section) => section.items.length > 0);
+        const { changelog, version, docsUrl } = config.whatsNew;
+        const userId = currentUser?.userId;
+        const [whatsNew, setWhatsNew] = useState(() => userId !== undefined ? pendingWhatsNew(userId, changelog, version) : []);
+        const closeWhatsNew = useCallback(() => {
+            setWhatsNew([]);
+            if (userId !== undefined)
+                markWhatsNewSeen(userId, version);
+        }, [userId, version]);
+        async function handleLogout() {
+            try {
+                await api.post('/auth/logout');
+            }
+            catch { /* local logout still proceeds */ }
+            clearSession();
+            navigate(config.loginPath);
+        }
+        const nav = { config, sections: navSections, isDark, onToggleDark: toggleDark, onLogout: () => void handleLogout() };
+        return (_jsxs("div", { className: "flex flex-col md:flex-row h-screen", style: { background: 'var(--m3-surface-container-low)' }, children: [_jsxs("header", { className: "md:hidden flex items-center justify-between gap-3 px-4 py-3 flex-shrink-0", style: { background: 'var(--m3-surface-container-low)', borderBottom: '1px solid var(--m3-outline-variant)' }, children: [_jsx(Brand, { brand: config.brand }), _jsx("button", { ref: menuButtonRef, type: "button", onClick: () => setDrawerPath(location.pathname), "aria-label": "Open navigation", "aria-expanded": drawerOpen, "aria-controls": "admin-nav-drawer", className: "btn-icon", children: _jsx("span", { "aria-hidden": "true", className: "material-symbols-outlined", children: "menu" }) })] }), whatsNew.length > 0 && _jsx(WhatsNew, { releases: whatsNew, docsUrl: docsUrl, onClose: closeWhatsNew }), drawerOpen && _jsx(MobileDrawer, { ...nav, onClose: closeDrawer, returnFocusRef: menuButtonRef }), _jsxs("aside", { className: "hidden md:flex flex-col h-screen w-64 sticky top-0 flex-shrink-0", style: { background: 'var(--m3-surface-container-low)' }, children: [_jsx("div", { className: "mb-6 px-4 pt-5", children: _jsx(Brand, { brand: config.brand }) }), _jsx(NavContent, { ...nav })] }), _jsx("main", { className: "flex-1 min-h-0 min-w-0 overflow-auto", style: { background: 'var(--m3-surface-container-low)' }, children: _jsx(Suspense, { fallback: _jsx(LoadingState, {}), children: _jsx(Fragment, { children: _jsx(Outlet, {}) }, `${datePrefs.date}-${datePrefs.time}`) }) })] }));
+    };
+}
+//# sourceMappingURL=AdminShell.js.map

package/dist/shell/AdminShell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdminShell.js","sourceRoot":"","sources":["../../src/shell/AdminShell.tsx"],"names":[],"mappings":"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"}

package/dist/shell/guards.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from 'react';
+/** Sends a first visit to the setup page, while the application has no administrator yet. */
+export declare function SetupGate({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Renders its children for a signed-in user. Someone who is not signed in goes to the sign-in page; someone the
+ * application sends elsewhere (`redirectAfterSignIn`) leaves the interface for that address.
+ */
+export declare function RequireAuth({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** Keeps a user who has to replace a temporary password on the page where they do it. */
+export declare function RequirePasswordChanged({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A guard for pages that need a role: a user whose rank is below the page's goes to the home page of their role.
+ * `roleRank` lists the roles by rank (higher sees more); a role it does not know ranks lowest.
+ */
+export declare function createRoleGuard(options: {
+    roleRank: Readonly<Record<string, number>>;
+    homeOf: (role?: string) => string;
+}): ({ minRole, children }: {
+    minRole: string;
+    children: ReactNode;
+}) => import("react").JSX.Element;
+//# sourceMappingURL=guards.d.ts.map

package/dist/shell/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/shell/guards.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAM3D,6FAA6F;AAC7F,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAiC9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,sCAsBhE;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAG3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,IAC5F,uBAAuB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,iCAM5F"}

package/dist/shell/guards.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Navigate } from 'react-router-dom';
+import { api, clearSession, getCurrentUser, mustChangePassword, setSession } from '../api/client';
+import { uiConfig } from '../config';
+import { navigation } from '../navigation';
+/** Sends a first visit to the setup page, while the application has no administrator yet. */
+export function SetupGate({ children }) {
+    const [state, setState] = useState('loading');
+    useEffect(() => {
+        fetch(`${uiConfig().apiBase}/setup/status`)
+            .then((r) => r.json())
+            .then((data) => {
+            setState(data.needsSetup ? 'setup' : 'ready');
+        })
+            .catch(() => setState('ready'));
+    }, []);
+    if (state === 'loading') {
+        return (_jsx("div", { className: "min-h-screen flex items-center justify-center", style: { background: 'var(--m3-surface)' }, children: _jsxs("div", { className: "flex flex-col items-center gap-4", children: [_jsx("div", { className: "w-10 h-10 rounded-2xl flex items-center justify-center", style: { background: 'var(--m3-primary-fixed)' }, children: _jsxs("svg", { width: "20", height: "20", viewBox: "0 0 20 20", fill: "none", children: [_jsx("circle", { cx: "10", cy: "10", r: "3.5", fill: "var(--m3-primary)" }), _jsx("circle", { cx: "10", cy: "10", r: "8.5", stroke: "var(--m3-primary)", strokeWidth: "1.2", strokeOpacity: "0.35", fill: "none" })] }) }), _jsx("span", { className: "font-sans text-sm", style: { color: 'var(--m3-secondary)' }, children: "Starting\u2026" })] }) }));
+    }
+    if (state === 'setup')
+        return _jsx(Navigate, { to: `${uiConfig().basePath}/setup`, replace: true });
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * Renders its children for a signed-in user. Someone who is not signed in goes to the sign-in page; someone the
+ * application sends elsewhere (`redirectAfterSignIn`) leaves the interface for that address.
+ */
+export function RequireAuth({ children }) {
+    const [state, setState] = useState('checking');
+    const [elsewhere, setElsewhere] = useState(null);
+    useEffect(() => {
+        api.get('/auth/session')
+            .then((user) => {
+            setSession(user);
+            const target = uiConfig().redirectAfterSignIn?.(user) ?? null;
+            setElsewhere(target);
+            setState(target ? 'elsewhere' : 'authenticated');
+        })
+            .catch(() => { clearSession(); setState('anonymous'); });
+    }, []);
+    useEffect(() => {
+        if (state === 'elsewhere' && elsewhere)
+            navigation.assign(elsewhere);
+    }, [state, elsewhere]);
+    if (state === 'checking' || state === 'elsewhere')
+        return null;
+    if (state === 'anonymous')
+        return _jsx(Navigate, { to: `${uiConfig().basePath}/login`, replace: true });
+    return _jsx(_Fragment, { children: children });
+}
+/** Keeps a user who has to replace a temporary password on the page where they do it. */
+export function RequirePasswordChanged({ children }) {
+    if (mustChangePassword())
+        return _jsx(Navigate, { to: `${uiConfig().basePath}/change-password`, replace: true });
+    return _jsx(_Fragment, { children: children });
+}
+/**
+ * A guard for pages that need a role: a user whose rank is below the page's goes to the home page of their role.
+ * `roleRank` lists the roles by rank (higher sees more); a role it does not know ranks lowest.
+ */
+export function createRoleGuard(options) {
+    return function RequireRole({ minRole, children }) {
+        const user = getCurrentUser();
+        const rank = options.roleRank[user?.role ?? ''] ?? 0;
+        if (rank < (options.roleRank[minRole] ?? 99))
+            return _jsx(Navigate, { to: options.homeOf(user?.role), replace: true });
+        return _jsx(_Fragment, { children: children });
+    };
+}
+//# sourceMappingURL=guards.js.map

package/dist/shell/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/shell/guards.tsx"],"names":[],"mappings":"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"}

package/icons.json

@@ -0,0 +1,170 @@
+[
+  "accessible",
+  "add",
+  "add_link",
+  "animation",
+  "api",
+  "archive",
+  "article",
+  "backup",
+  "badge",
+  "block",
+  "box",
+  "call",
+  "cancel",
+  "celebration",
+  "check",
+  "check_circle",
+  "circle",
+  "class",
+  "clear",
+  "close",
+  "cloud",
+  "cloud_off",
+  "code",
+  "colors",
+  "compare",
+  "content_copy",
+  "cookie",
+  "create",
+  "cut",
+  "dark_mode",
+  "data_object",
+  "database",
+  "delete",
+  "description",
+  "details",
+  "dialogs",
+  "docs",
+  "done",
+  "download",
+  "dropdown",
+  "email",
+  "enable",
+  "error",
+  "event",
+  "expand",
+  "expand_more",
+  "explicit",
+  "feedback",
+  "files",
+  "filter",
+  "function",
+  "gradient",
+  "group",
+  "groups",
+  "height",
+  "help",
+  "hide",
+  "history",
+  "home",
+  "host",
+  "html",
+  "http",
+  "https",
+  "inbox",
+  "info",
+  "input",
+  "join",
+  "keep",
+  "key",
+  "key_off",
+  "label",
+  "light_mode",
+  "link",
+  "list",
+  "lists",
+  "lock",
+  "lock_reset",
+  "login",
+  "logout",
+  "mail",
+  "manage_accounts",
+  "map",
+  "markdown",
+  "menu",
+  "message",
+  "mobile",
+  "mode",
+  "more",
+  "moving",
+  "navigation",
+  "network_check",
+  "no_encryption",
+  "note",
+  "notes",
+  "opacity",
+  "pace",
+  "package",
+  "padding",
+  "pages",
+  "passkey",
+  "password",
+  "pending",
+  "person",
+  "person_add",
+  "phone",
+  "place",
+  "post",
+  "progress_activity",
+  "public",
+  "radio_button_checked",
+  "refresh",
+  "remove",
+  "repeat",
+  "resize",
+  "restore",
+  "router",
+  "save",
+  "scan",
+  "schedule",
+  "script",
+  "search",
+  "security",
+  "select",
+  "send",
+  "settings",
+  "shadow",
+  "share",
+  "shield_lock",
+  "shift",
+  "sort",
+  "source",
+  "stack",
+  "start",
+  "step",
+  "steps",
+  "stop",
+  "storage",
+  "store",
+  "style",
+  "summarize",
+  "switch",
+  "tab",
+  "table",
+  "tabs",
+  "target",
+  "timer",
+  "title",
+  "toast",
+  "token",
+  "toolbar",
+  "transform",
+  "translate",
+  "trip",
+  "try",
+  "tune",
+  "unfold_more",
+  "update",
+  "upload",
+  "uppercase",
+  "variables",
+  "verified",
+  "visibility",
+  "visibility_off",
+  "vpn_key",
+  "warning",
+  "width",
+  "window",
+  "work"
+]

package/package.json

@@ -1,6 +1,71 @@
-{
-  "name": "@better-forge/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@better-forge/ui",
+  "version": "0.1.0",
+  "description": "React admin shell, UI components, API client and shared pages.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/ui#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./styles/base.css",
+    "./icons.css": "./styles/icons.css",
+    "./icons.json": "./icons.json",
+    "./tailwind-preset": "./tailwind-preset.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*",
+    "!src/testing",
+    "styles",
+    "tailwind-preset.js",
+    "icons.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "clsx": "^2.1.1",
+    "react-router-dom": "^7.5.0",
+    "@tanstack/react-query": "^5.74.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "clsx": "^2.1.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.5.0",
+    "@tanstack/react-query": "^5.74.4"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "dependencies": {
+    "@better-forge/contracts": "0.1.0"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,139 @@
+import { safeSessionStorage } from '@better-forge/contracts'
+import { storageKey, uiConfig } from '../config'
+import { navigation } from '../navigation'
+
+const userKey = () => storageKey('auth-user')
+
+export interface AuthUser {
+  userId: number
+  email: string
+  role: string
+  mustChangePassword: boolean
+  twoFactorEnabled: boolean
+  authMethod?: 'password' | 'oidc'
+}
+
+export function setSession(user: AuthUser): void {
+  safeSessionStorage.set(userKey(), JSON.stringify(user))
+  window.dispatchEvent(new CustomEvent(storageKey('auth-change')))
+}
+
+export function clearSession(): void {
+  safeSessionStorage.remove(userKey())
+  window.dispatchEvent(new CustomEvent(storageKey('auth-change')))
+}
+
+export function getCurrentUser(): AuthUser | null {
+  try {
+    const stored = safeSessionStorage.get(userKey())
+    return stored ? JSON.parse(stored) as AuthUser : null
+  } catch { return null }
+}
+
+export function isAuthenticated(): boolean {
+  return getCurrentUser() !== null
+}
+
+/**
+ * Where a signed-in user starts. One who does not belong in this interface goes where the application sends them
+ * (which may also have them replace a temporary password); everyone else replaces it here first.
+ */
+export function enterAfterSignIn(user: AuthUser, navigate: (path: string) => void): void {
+  const elsewhere = uiConfig().redirectAfterSignIn?.(user) ?? null
+  if (elsewhere) navigation.assign(elsewhere)
+  else if (user.mustChangePassword) navigate(`${uiConfig().basePath}/change-password`)
+  else navigate(`${uiConfig().basePath}/`)
+}
+
+export function mustChangePassword(): boolean {
+  return !!getCurrentUser()?.mustChangePassword
+}
+
+/**
+ * A failed API call: `message` is the server's error text, `code` its machine-readable code when it sent one, and
+ * `body` the whole JSON answer, for the endpoints that say more than a message (a list of problems, say).
+ */
+export class ApiError extends Error {
+  constructor(message: string, readonly status: number, readonly code?: string, readonly body?: unknown) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+function cookie(name: string): string | null {
+  const prefix = `${encodeURIComponent(name)}=`
+  const part = document.cookie.split('; ').find((item) => item.startsWith(prefix))
+  return part ? decodeURIComponent(part.slice(prefix.length)) : null
+}
+
+async function request<T>(
+  method: string,
+  path: string,
+  body?: unknown,
+  isFormData = false,
+  /** Sends `body` (a string) as it is with this content type, instead of as JSON. */
+  contentType?: string,
+  /** Reads the answer as text instead of JSON. */
+  asText = false,
+): Promise<T> {
+  const headers: Record<string, string> = {}
+  if (contentType) headers['Content-Type'] = contentType
+  else if (!isFormData && body !== undefined) headers['Content-Type'] = 'application/json'
+  if (!['GET', 'HEAD', 'OPTIONS'].includes(method)) {
+    const csrf = cookie(uiConfig().csrfCookie)
+    if (csrf) headers['X-CSRF-Token'] = csrf
+  }
+
+  const fetchBody = contentType ? (body as string) : isFormData ? (body as FormData) : body !== undefined ? JSON.stringify(body) : null
+  const res = await fetch(`${uiConfig().apiBase}${path}`, {
+    method,
+    headers,
+    credentials: 'same-origin',
+    ...(fetchBody !== null ? { body: fetchBody } : {}),
+  })
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: res.statusText })) as { error?: string; code?: string }
+    if (res.status === 403 && err.code === 'PASSWORD_CHANGE_REQUIRED') {
+      const user = getCurrentUser()
+      if (user && !user.mustChangePassword) setSession({ ...user, mustChangePassword: true })
+      if (!window.location.pathname.includes('/change-password')) {
+        window.location.href = `${uiConfig().basePath}/change-password`
+      }
+    }
+    if (res.status === 401) {
+      clearSession()
+      const isLoginRequest = path === '/auth/login' || path === '/auth/2fa/verify'
+      if (!isLoginRequest && !window.location.pathname.includes('/login')) {
+        window.location.href = `${uiConfig().basePath}/login`
+      }
+    }
+    throw new ApiError(err.error ?? res.statusText, res.status, err.code, err)
+  }
+
+  if (res.status === 204) return undefined as T
+  return (asText ? res.text() : res.json()) as Promise<T>
+}
+
+export const api = {
+  get: <T>(path: string) => request<T>('GET', path),
+  /** GET an answer that is text, for example a YAML document. */
+  getText: (path: string) => request<string>('GET', path, undefined, false, undefined, true),
+  post: <T>(path: string, body: unknown = {}) => request<T>('POST', path, body),
+  patch: <T>(path: string, body: unknown) => request<T>('PATCH', path, body),
+  put: <T>(path: string, body: unknown) => request<T>('PUT', path, body),
+  delete: (path: string) => request<void>('DELETE', path),
+  upload: <T>(path: string, formData: FormData) => request<T>('POST', path, formData, true),
+  /** POST a text body as it is, for example a YAML file, with the given content type. */
+  postText: <T>(path: string, text: string, contentType: string) => request<T>('POST', path, text, false, contentType),
+  download: async (path: string, filename: string) => {
+    const res = await fetch(`${uiConfig().apiBase}${path}`, { credentials: 'same-origin' })
+    if (!res.ok) throw new Error('Download failed')
+    const url = URL.createObjectURL(await res.blob())
+    const link = document.createElement('a')
+    link.href = url
+    link.download = filename
+    link.click()
+    URL.revokeObjectURL(url)
+  },
+}