@sjolystinnovation/app-kit 0.21.0 → 1.0.0

package/src/api/revalidateTargets.ts

@@ -3,12 +3,13 @@ import { requestRevalidate } from "./requestRevalidate";
 
 /** The pages one admin edit changes. */
 export interface RevalidateTargetPaths {
-  /** Paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
+  /** The paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
   pages?: readonly string[] | undefined;
-  /** Paths outside the locale segments, such as `/sitemap.xml`. */
+  /** The paths outside the locale segments, such as `/sitemap.xml`. */
   root?: readonly string[] | undefined;
 }
 
+/** Options for `defineRevalidateTargets`. */
 export interface RevalidateTargetsConfig<T extends string> {
   /** The locale segments every page is under. A site without them omits this. */
   locales?: readonly string[] | undefined;
@@ -16,9 +17,10 @@ export interface RevalidateTargetsConfig<T extends string> {
 }
 
 /**
- * The cache targets an app's admin edits purge, in one place for both sides: `targets` names them
- * for fetch tags, `paths` is what `createRevalidateRoute` purges for each, and `revalidate` asks the
- * route to purge one after an edit. A target with no paths is purged by its tag alone.
+ * Defines the cache targets an app's admin edits purge, in one place for the client and the server.
+ * `targets` names them for fetch tags, `paths` lists what `createRevalidateRoute` purges for each,
+ * and `revalidate` asks the route to purge one after an edit. A target with no paths is purged by
+ * its tag alone.
  */
 export function defineRevalidateTargets<T extends string>({ locales = [], targets }: RevalidateTargetsConfig<T>) {
   const names = Object.keys(targets) as T[];

package/src/api/services.ts

@@ -1,10 +1,12 @@
 import axios, { type AxiosInstance } from "axios";
 import { getSession } from "next-auth/react";
 import type { Branding } from "../branding/types";
+import type { LegalPage } from "./legalPage";
+import { LEGAL_PAGE_KEYS, type DefaultLegalPageKey } from "../legal/keys";
 import { request } from "./request";
 
 /**
- * An axios instance for the API's anonymous endpoints, without the session's token. Like
+ * Creates an axios instance for the API's anonymous endpoints, without the session's token. Like
  * `createApiClient`, it only sends requests to `baseURL`.
  */
 export function createPublicClient(baseURL: string): AxiosInstance {
@@ -14,7 +16,7 @@ export function createPublicClient(baseURL: string): AxiosInstance {
   return axios.create({ baseURL, allowAbsoluteUrls: false });
 }
 
-/** Runs after an admin change saves, such as to purge the pages that show it. */
+/** A callback that runs after an admin change saves, such as to purge the pages that show it. */
 export type OnSaved = () => Promise<void> | void;
 
 async function currentUserId(): Promise<string> {
@@ -35,8 +37,8 @@ export interface UserProfile {
 }
 
 /**
- * Password reset and the signed-in user's account, on the auth and account endpoints of
- * SjolystInnovation.AppKit.Auth. `api` carries the session, `publicApi` does not.
+ * Creates the calls for password reset and the signed-in user's account, on the auth and account
+ * endpoints of SjolystInnovation.AppKit.Auth. `api` carries the session, and `publicApi` does not.
  */
 export function createUserService(api: AxiosInstance, publicApi: AxiosInstance) {
   return {
@@ -88,7 +90,7 @@ export interface SiteSettings {
   publicPhone: string;
 }
 
-/** The admin's company settings on SjolystInnovation.AppKit.SiteSettings. */
+/** Creates the admin calls for the company settings on SjolystInnovation.AppKit.SiteSettings. */
 export function createSettingsService(api: AxiosInstance, options: { onSaved?: OnSaved } = {}) {
   return {
     get: () => request(() => api.get<SiteSettings>("/settings"), "Failed to load settings"),
@@ -102,8 +104,8 @@ export function createSettingsService(api: AxiosInstance, options: { onSaved?: O
 }
 
 /**
- * The logo and favicon on SjolystInnovation.AppKit.SiteSettings. Reading is anonymous and answers
- * no branding when the API cannot be reached, so a page still renders.
+ * Creates the calls for the logo and favicon on SjolystInnovation.AppKit.SiteSettings. Reading is
+ * anonymous and returns no branding when the API cannot be reached, so a page still renders.
  */
 export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstance, options: { onSaved?: OnSaved } = {}) {
   return {
@@ -115,7 +117,7 @@ export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstan
       }
     },
 
-    /** Sends the form `BrandingManager` builds: `logo`, `icon`, `removeLogo` and `removeIcon`. */
+    /** Sends the form `BrandingManager` builds: `logo`, `icon`, `removeLogo`, and `removeIcon`. */
     async update(form: FormData): Promise<Branding> {
       const saved = await request(() => api.put<Branding>("/branding", form), "Failed to save branding");
       await options.onSaved?.();
@@ -124,25 +126,30 @@ export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstan
   };
 }
 
-/** A legal page, as SjolystInnovation.AppKit.SiteSettings's legal endpoints return it. */
-export interface LegalPage<Key extends string = string> {
-  key: Key;
-  locale: string;
-  title: string;
-  bodyMarkdown: string;
-  updatedAt: string;
+/** Options for `createLegalService`. */
+export interface LegalServiceOptions<Key extends string> {
+  /**
+   * The app's legal pages, the same keys as the API's `MapAppKitLegalPages` `Keys` option. Defaults
+   * to `LEGAL_PAGE_KEYS`. The service's key type comes from them.
+   */
+  keys?: readonly Key[] | undefined;
+  onSaved?: OnSaved | undefined;
 }
 
 /**
- * The terms, privacy and cookie pages on SjolystInnovation.AppKit.SiteSettings. Reading is anonymous
- * and answers null for a page that is missing or cannot be read, so a page shows its fallback.
+ * Creates the calls for the legal pages on SjolystInnovation.AppKit.SiteSettings, such as terms,
+ * privacy, and cookies. Reading is anonymous and returns null for a page that is missing or cannot be
+ * read, so a page shows its fallback. `keys` on the result holds the app's pages, for the editor and
+ * the sitemap.
  */
-export function createLegalService<Key extends string = "terms" | "privacy" | "cookies">(
+export function createLegalService<const Key extends string = DefaultLegalPageKey>(
   api: AxiosInstance,
   publicApi: AxiosInstance,
-  options: { onSaved?: OnSaved } = {},
+  options: LegalServiceOptions<Key> = {},
 ) {
   return {
+    keys: options.keys ?? (LEGAL_PAGE_KEYS as readonly string[] as readonly Key[]),
+
     async get(key: Key, locale: string): Promise<LegalPage<Key> | null> {
       try {
         return (await publicApi.get<LegalPage<Key>>(`/content/legal/${encodeURIComponent(key)}`, { params: { locale } })).data;
@@ -153,7 +160,7 @@ export function createLegalService<Key extends string = "terms" | "privacy" | "c
 
     listAll: () => request(() => api.get<LegalPage<Key>[]>("/content/legal"), "Failed to load legal pages"),
 
-    async save(key: Key, locale: string, title: string, bodyMarkdown: string) {
+    async save({ key, locale, title, bodyMarkdown }: { key: Key; locale: string; title: string; bodyMarkdown: string }) {
       const page = await request(
         () => api.put<LegalPage<Key>>(`/content/legal/${encodeURIComponent(key)}/${encodeURIComponent(locale)}`, { title, bodyMarkdown }),
         "Failed to save legal page",
@@ -164,6 +171,27 @@ export function createLegalService<Key extends string = "terms" | "privacy" | "c
   };
 }
 
+/** The transactional email of the last days, as SjolystInnovation.AppKit.Email's stats endpoint returns it. */
+export interface EmailStats {
+  days: number;
+  requests: number;
+  delivered: number;
+  hardBounces: number;
+  softBounces: number;
+  spamReports: number;
+  blocked: number;
+  invalid: number;
+}
+
+/** Creates the admin call for the email stats on SjolystInnovation.AppKit.Email's `MapAppKitEmailStats`. */
+export function createEmailStatsService(api: AxiosInstance) {
+  return {
+    /** The stats for the last `days` days, 30 by default. */
+    get: (days = 30) =>
+      request(() => api.get<EmailStats>("/admin/email-stats", { params: { days } }), "Failed to load email stats"),
+  };
+}
+
 /** A user in the admin list, as SjolystInnovation.AppKit.Auth's user admin endpoints return it. */
 export interface AdminUser {
   id: string;
@@ -176,12 +204,15 @@ export interface AdminUser {
   roles: string[];
 }
 
-/** User administration on SjolystInnovation.AppKit.Auth: the list, roles, invites and deletion. */
+/** Creates the user administration calls on SjolystInnovation.AppKit.Auth: the list, roles, invites, and deletion. */
 export function createAdminUsersService(api: AxiosInstance) {
   return {
     getUsers: (includeDeleted = false) =>
       request(() => api.get<AdminUser[]>("/users", { params: { includeDeleted } }), "Failed to load users"),
 
+    /** The roles an admin may give, in the order the API configures them. */
+    roles: () => request(() => api.get<string[]>("/users/roles"), "Failed to load roles"),
+
     addRole: (userId: string, role: string) =>
       request(() => api.post(`/users/${encodeURIComponent(userId)}/roles`, { role }), "Failed to assign role"),
 
@@ -191,7 +222,7 @@ export function createAdminUsersService(api: AxiosInstance) {
     deleteUser: (userId: string) =>
       request(() => api.delete(`/users/${encodeURIComponent(userId)}/account`), "Failed to delete user"),
 
-    invite: (email: string, firstName: string, lastName: string, role: string) =>
+    invite: ({ email, firstName, lastName, role }: { email: string; firstName: string; lastName: string; role: string }) =>
       request(() => api.post("/users/invite", { email, firstName, lastName, role }), "Failed to send invitation"),
   };
 }

package/src/auth/createAuthOptions.ts

@@ -3,6 +3,7 @@ import jwt from "jsonwebtoken";
 import type { NextAuthOptions, Session, User } from "next-auth";
 import CredentialsProvider from "next-auth/providers/credentials";
 import type { JWT } from "next-auth/jwt";
+import { apiErrorCode } from "../api/apiErrorCode";
 import { resolveJwtSecret, type SessionConfig } from "../config";
 import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
 
@@ -44,12 +45,13 @@ interface AuthorizedUser extends User {
   refreshToken: string;
 }
 
+/** Settings for `createAuthOptions`. Pass either `apiUrl` or `http`. */
 export type AuthOptionsSettings = {
   /** The server environment, usually `process.env`. It holds the API JWT secret. */
   env: Record<string, string | undefined>;
 } & (
   | {
-      /** Base URL of the API, such as `https://api.example.com/api`. */
+      /** The base URL of the API, such as `https://api.example.com/api`. */
       apiUrl: string;
       http?: never;
     }
@@ -60,7 +62,8 @@ export type AuthOptionsSettings = {
     }
 );
 
-// Refresh ahead of expiry, so the token is still fresh when the user saves.
+// How far ahead of expiry a refresh falls due, at most, so the token is still fresh when the user
+// saves.
 const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
 
 // The soonest a refresh can be due. The floor stops a short-lived token from refreshing on every
@@ -100,6 +103,13 @@ function apiUnavailable(error: unknown): boolean {
   return status === undefined || status === 502 || status === 503 || status === 504;
 }
 
+// The sign-in error for a failed login. Only the API's lockout code is told apart from wrong
+// credentials, because the API gives it whether the password was right or not.
+function signInError(error: unknown): string {
+  if (apiUnavailable(error)) return SIGN_IN_ERRORS.unavailable;
+  return apiErrorCode(error) === "lockedOut" ? SIGN_IN_ERRORS.lockedOut : SIGN_IN_ERRORS.invalidCredentials;
+}
+
 // What a log line may contain. The error itself carries the request, which holds the password or
 // tokens.
 function failureShape(error: unknown) {
@@ -111,9 +121,9 @@ function failureShape(error: unknown) {
 }
 
 /**
- * next-auth options for email and password sign-in against the API. The API issues a short-lived
- * access token and a refresh token that changes on every refresh. The session refreshes ahead of
- * expiry, rides out temporary API failures, and ends seven days after sign-in.
+ * Creates the next-auth options for email and password sign-in against the API. The API issues a
+ * short-lived access token and a refresh token that changes on every refresh. The session refreshes
+ * ahead of expiry, rides out temporary API failures, and ends seven days after sign-in.
  */
 export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSettings): NextAuthOptions {
   const { env } = settings;
@@ -240,9 +250,7 @@ export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSe
             console.error("Sign-in failed", failureShape(error));
             // No cause: next-auth logs this error, and the cause carries the password.
             // eslint-disable-next-line preserve-caught-error
-            throw new Error(
-              apiUnavailable(error) ? SIGN_IN_ERRORS.unavailable : SIGN_IN_ERRORS.invalidCredentials,
-            );
+            throw new Error(signInError(error));
           }
         },
       }),

package/src/branding/BrandingManager.tsx

@@ -1,49 +1,30 @@
 "use client";
 
 import { ArrowUpTrayIcon, TrashIcon } from "@heroicons/react/24/outline";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
+import { fieldErrorTexts } from "../api/fieldErrorText";
 import { toast } from "../toast";
+import { FieldError } from "../ui/field";
 import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { useBranding } from "./BrandingProvider";
+import { defaultBrandingManagerStrings, type BrandingManagerStrings, type BrandingValidationStrings } from "./brandingManagerStrings";
 import { toDataUrl } from "./types";
 
-export interface BrandingManagerStrings {
-  title: string;
-  logo: string;
-  logoHint: string;
-  icon: string;
-  iconHint: string;
-  none: string;
-  choose: string;
-  remove: string;
-  save: string;
-  saving: string;
-  saved: string;
-  saveFailed: string;
-}
-
-export const defaultBrandingManagerStrings: BrandingManagerStrings = {
-  title: "Branding",
-  logo: "Logo",
-  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
-  icon: "Icon (favicon)",
-  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
-  none: "none",
-  choose: "Choose",
-  remove: "Remove",
-  save: "Save branding",
-  saving: "Saving…",
-  saved: "Branding saved",
-  saveFailed: "Failed to save branding",
-};
+const IMAGE_TYPES = "image/png,image/jpeg,image/webp,image/gif,image/x-icon,.ico";
 
+/** Props for `BrandingManager`. */
 export interface BrandingManagerProps {
   /**
-   * Sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set to `true`. Throw
-   * to show the error's message, such as one from `formatApiError`.
+   * A function that sends the form: `logo` and `icon` files, and `removeLogo` and `removeIcon` set
+   * to `true`. Throw from it to show the error's message, such as one from `formatApiError`.
    */
   save: (form: FormData) => Promise<unknown>;
-  strings?: TextOverrides<BrandingManagerStrings> | undefined;
+  /** The form's text. `validation` may name only some codes, the rest keep their defaults. */
+  strings?:
+    | (TextOverrides<Omit<BrandingManagerStrings, "validation">> & {
+        validation?: TextOverrides<BrandingValidationStrings> | undefined;
+      })
+    | undefined;
 }
 
 /** A preview is an object URL for the chosen file or a data URL of a raster image. Anything else shows none. */
@@ -57,11 +38,15 @@ interface SlotProps {
   file: File | null;
   onPick: (file: File | null) => void;
   onClear: () => void;
+  /** Why the API refused this slot's file in the last save, if it did. */
+  error: string | undefined;
   text: BrandingManagerStrings;
 }
 
-function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProps) {
+function Slot({ label, hint, currentUrl, file, onPick, onClear, error, text }: SlotProps) {
   const inputRef = useRef<HTMLInputElement>(null);
+  const errorId = `${useId()}-error`;
+  const describedBy = error ? errorId : undefined;
   const [objectUrl, setObjectUrl] = useState<string | null>(null);
 
   // An object URL is an outside resource with a lifetime, which is what an effect is for. Creating
@@ -93,14 +78,18 @@ function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProp
         <input
           ref={inputRef}
           type="file"
-          accept="image/*"
+          // The types the API accepts, so the picker does not offer an SVG it would refuse.
+          accept={IMAGE_TYPES}
           aria-label={label}
+          aria-invalid={error ? true : undefined}
+          aria-describedby={describedBy}
           className="hidden"
           onChange={e => onPick(e.target.files?.[0] ?? null)}
         />
         <button
           type="button"
           onClick={() => inputRef.current?.click()}
+          aria-describedby={describedBy}
           className="inline-flex items-center gap-1.5 rounded-lg bg-gray-100 text-gray-700 font-medium px-3 py-2 text-sm hover:bg-gray-200"
         >
           <ArrowUpTrayIcon className="h-4 w-4" /> {text.choose}
@@ -112,19 +101,24 @@ function Slot({ label, hint, currentUrl, file, onPick, onClear, text }: SlotProp
         )}
       </div>
       <p className="mt-1 text-xs text-gray-500">{hint}</p>
+      <FieldError id={errorId} error={error} />
     </div>
   );
 }
 
 /** The admin form for uploading or removing the logo and the favicon. Needs a `BrandingProvider` above it. */
 export function BrandingManager({ save, strings }: BrandingManagerProps) {
-  const text = withDefaults(defaultBrandingManagerStrings, strings);
+  const { validation: validationOverrides, ...textOverrides } = strings ?? {};
+  const text = withDefaults(defaultBrandingManagerStrings, textOverrides);
+  const validation = withDefaults(defaultBrandingManagerStrings.validation, validationOverrides);
   const { branding, refresh } = useBranding();
   const [logo, setLogo] = useState<File | null>(null);
   const [icon, setIcon] = useState<File | null>(null);
   const [removeLogo, setRemoveLogo] = useState(false);
   const [removeIcon, setRemoveIcon] = useState(false);
   const [saving, setSaving] = useState(false);
+  // The texts for the files the API refused in the last save, keyed by `logo` and `icon`.
+  const [refusals, setRefusals] = useState<Record<string, string[]>>({});
 
   const currentLogo = removeLogo ? null : toDataUrl(branding.logoData, branding.logoContentType);
   const currentIcon = removeIcon ? null : toDataUrl(branding.iconData, branding.iconContentType);
@@ -142,10 +136,14 @@ export function BrandingManager({ save, strings }: BrandingManagerProps) {
       setIcon(null);
       setRemoveLogo(false);
       setRemoveIcon(false);
+      setRefusals({});
       refresh();
       toast.success(text.saved);
     } catch (err) {
-      toast.error(err instanceof Error && err.message ? err.message : text.saveFailed);
+      const texts = fieldErrorTexts(err, validation);
+      setRefusals(texts);
+      const first = Object.values(texts)[0]?.[0];
+      toast.error(first ?? (err instanceof Error && err.message ? err.message : text.saveFailed));
     } finally {
       setSaving(false);
     }
@@ -161,6 +159,7 @@ export function BrandingManager({ save, strings }: BrandingManagerProps) {
         file={logo}
         onPick={f => { setLogo(f); setRemoveLogo(false); }}
         onClear={() => { setLogo(null); setRemoveLogo(true); }}
+        error={refusals.logo?.join(" ")}
         text={text}
       />
       <Slot
@@ -170,6 +169,7 @@ export function BrandingManager({ save, strings }: BrandingManagerProps) {
         file={icon}
         onPick={f => { setIcon(f); setRemoveIcon(false); }}
         onClear={() => { setIcon(null); setRemoveIcon(true); }}
+        error={refusals.icon?.join(" ")}
         text={text}
       />
       <button

package/src/branding/BrandingProvider.tsx

@@ -3,6 +3,7 @@
 import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode } from "react";
 import { toDataUrl, type Branding } from "./types";
 
+/** What `useBranding` returns. */
 export interface BrandingContextValue {
   branding: Branding;
   /** The logo as a `data:` URL, or null when none is set. */
@@ -13,21 +14,22 @@ export interface BrandingContextValue {
 
 const BrandingContext = createContext<BrandingContextValue>({ branding: {}, logoUrl: null, refresh: () => {} });
 
-/** The branding from the nearest `BrandingProvider`. Empty outside one. */
+/** Gets the branding from the nearest `BrandingProvider`. Returns empty branding outside one. */
 export const useBranding = () => useContext(BrandingContext);
 
 /** How often the provider loads the branding again, so an open tab picks up a change. */
 export const BRANDING_REFRESH_MS = 5 * 60 * 1000;
 
+/** Props for `BrandingProvider`. */
 export interface BrandingProviderProps {
   children: ReactNode;
-  /** Loads the branding, such as a GET of `/branding`. A failure keeps the branding it has. */
+  /** A function that loads the branding, such as a GET of `/branding`. On a failure the provider keeps the branding it has. */
   load: () => Promise<Branding>;
   /** The branding the server rendered with. Without it, the provider loads it on mount. */
   initial?: Branding | undefined;
 }
 
-/** Holds the logo and favicon for the components below it, and loads them again every five minutes. */
+/** Provides the logo and favicon to the components below it, and loads them again every five minutes. */
 export function BrandingProvider({ children, load, initial }: BrandingProviderProps) {
   const [branding, setBranding] = useState<Branding>(initial ?? {});
   // The latest load, so an inline function does not restart the refresh timer on every render.

package/src/branding/brandingManagerStrings.ts

@@ -0,0 +1,49 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The branding form's text for each refusal code of SjolystInnovation.AppKit.SiteSettings that a
+ * chosen file can get. The form shows the API's own message for a code that is not here.
+ */
+export interface BrandingValidationStrings {
+  /** The file is not a PNG, JPEG, WebP, GIF, or ICO image. */
+  invalidImage: string;
+  /** The file is larger than 2 MB. */
+  imageTooLarge: string;
+}
+
+/** The branding form's text. Pass the app's own language. The defaults are English. */
+export interface BrandingManagerStrings {
+  title: string;
+  logo: string;
+  logoHint: string;
+  icon: string;
+  iconHint: string;
+  none: string;
+  choose: string;
+  remove: string;
+  save: string;
+  saving: string;
+  saved: string;
+  saveFailed: string;
+  /** The refusal texts, by code. Any code left out keeps its default. */
+  validation: BrandingValidationStrings;
+}
+
+export const defaultBrandingManagerStrings: BrandingManagerStrings = {
+  title: "Branding",
+  logo: "Logo",
+  logoHint: "Shown in the navbar and footer. PNG, JPEG, WebP, or GIF, max 2 MB.",
+  icon: "Icon (favicon)",
+  iconHint: "Browser tab icon. Square PNG or ICO, max 2 MB.",
+  none: "none",
+  choose: "Choose",
+  remove: "Remove",
+  save: "Save branding",
+  saving: "Saving…",
+  saved: "Branding saved",
+  saveFailed: "Failed to save branding",
+  validation: {
+    invalidImage: "The image must be a PNG, JPEG, WebP, GIF or ICO file of at most 2 MB.",
+    imageTooLarge: "The image must be a PNG, JPEG, WebP, GIF or ICO file of at most 2 MB.",
+  },
+};

package/src/branding/index.ts

@@ -1,14 +1,13 @@
+export { BrandingManager, type BrandingManagerProps } from "./BrandingManager";
 export {
-  BrandingManager,
   defaultBrandingManagerStrings,
-  type BrandingManagerProps,
   type BrandingManagerStrings,
-} from "./BrandingManager";
+  type BrandingValidationStrings,
+} from "./brandingManagerStrings";
 export {
-  BRANDING_REFRESH_MS,
   BrandingProvider,
   useBranding,
   type BrandingContextValue,
   type BrandingProviderProps,
 } from "./BrandingProvider";
-export { toDataUrl, type Branding } from "./types";
+export type { Branding } from "./types";

package/src/branding/server.ts

@@ -2,22 +2,23 @@ import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import type { Branding } from "./types";
 
+/** Options for `brandingIcon`. */
 export interface BrandingIconOptions {
-  /** Loads the branding, such as a cached GET of `/branding`. Throws when the API cannot be reached. */
+  /** A function that loads the branding, such as a cached GET of `/branding`. It throws when the API cannot be reached. */
   load: () => Promise<Branding | null | undefined>;
   /** The bundled icon for when none is set, such as `public/icon.png`. */
   fallbackPath: string;
-  /** Its content type, such as `image/png` or `image/svg+xml`. */
+  /** The bundled icon's content type, such as `image/png` or `image/svg+xml`. */
   fallbackType: string;
 }
 
 /**
- * The response for an `app/icon.ts` route: the favicon set in admin settings when it is a PNG,
- * JPEG, WebP, GIF or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox CSP
- * that a CSP header from the app's `next.config` replaces.
- * When the branding cannot be loaded it answers 503 with `no-store`, not the
- * bundled icon, since a browser would cache that in place of the one set in settings. The route
- * needs `dynamic = "force-dynamic"`, or the build bakes in the icon of the moment.
+ * Builds the response for an `app/icon.ts` route: the favicon set in admin settings when it is a
+ * PNG, JPEG, WebP, GIF, or ICO, or the bundled one otherwise. Both carry `nosniff`, and a sandbox
+ * CSP that a CSP header from the app's `next.config` replaces. When the branding cannot be loaded,
+ * it answers 503 with `no-store` instead of the bundled icon, since a browser would cache that in
+ * place of the one set in settings. The route needs `dynamic = "force-dynamic"`, or the build bakes
+ * in the icon of the moment.
  */
 export async function brandingIcon({ load, fallbackPath, fallbackType }: BrandingIconOptions): Promise<Response> {
   let branding: Branding | null | undefined;
@@ -47,7 +48,7 @@ const RASTER_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gi
 const HARDENING = { "X-Content-Type-Options": "nosniff", "Content-Security-Policy": "default-src 'none'; sandbox" };
 
 /**
- * A short digest of icon bytes, for a URL that changes when the icon does, such as
+ * Computes a short digest of icon bytes, for a URL that changes when the icon does, such as
  * `/icon?v=<digest>` in the web app manifest. Android refreshes a home screen icon only when the
  * manifest changes.
  */

package/src/branding/types.ts

@@ -1,13 +1,13 @@
 /** The logo and favicon set in admin settings, as the API's `/branding` endpoint returns them. */
 export interface Branding {
-  /** Base64 image bytes. */
+  /** The logo's image bytes, in base64. */
   logoData?: string | null | undefined;
   logoContentType?: string | null | undefined;
-  /** Base64 image bytes. */
+  /** The favicon's image bytes, in base64. */
   iconData?: string | null | undefined;
   iconContentType?: string | null | undefined;
 }
 
-/** A `data:` URL for base64 image bytes, or null when either part is missing. */
+/** Builds a `data:` URL for base64 image bytes. Returns null when either part is missing. */
 export const toDataUrl = (data?: string | null, contentType?: string | null): string | null =>
   data && contentType ? `data:${contentType};base64,${data}` : null;

package/src/config.ts

@@ -4,18 +4,18 @@
  */
 export interface SessionConfig {
   /**
-   * Name of the environment variable holding the API JWT secret, such as API_JWT_SECRET. Apps that
-   * talk to more than one API, or that deploy several apps side by side, need distinct names.
+   * The name of the environment variable holding the API JWT secret, such as `API_JWT_SECRET`. Apps
+   * that talk to more than one API, or that deploy several apps side by side, need distinct names.
    */
   jwtSecretEnvVar: string;
   /**
-   * Where an expired or rejected session sends the browser. An app with a locale prefix uses
-   * something like "/en/login". An app without one uses "/login".
+   * The path an expired or rejected session sends the browser to. An app with a locale prefix uses
+   * something like `"/en/login"`. An app without one uses `"/login"`.
    */
   loginRoute: string;
   /**
-   * Prefix for the localStorage keys holding form drafts, usually the app's name, such as
-   * "example". Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
+   * The prefix for the localStorage keys holding form drafts, usually the app's name, such as
+   * `"example"`. Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
    * has no trailing colon.
    */
   draftStoragePrefix: string;
@@ -31,8 +31,8 @@ export function defineSessionConfig(config: SessionConfig): SessionConfig {
 }
 
 /**
- * The key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
- * "app:draft::draft:", which match no draft saved under "app:draft:".
+ * Gets the key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
+ * `"app:draft::draft:"`, which match no draft saved under `"app:draft:"`.
  */
 export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
   const name = config.draftStoragePrefix;
@@ -57,8 +57,8 @@ export function requireEnv(name: string, value: string | undefined): string {
  * Reads the API JWT secret named by the config. Throws when it is missing, with a message that names
  * the variable.
  *
- * The caller passes the environment, usually `process.env`, so this entry point needs no Node
- * types and stays safe to import in browser code.
+ * The caller passes the environment, usually `process.env`, so this module needs no Node types and
+ * stays safe to import in browser code. `createAuthOptions` uses it. It is not part of the public API.
  */
 export function resolveJwtSecret(
   config: SessionConfig,