@sjolystinnovation/app-kit 0.20.0 → 0.22.0

package/src/api/company.ts

@@ -0,0 +1,47 @@
+/** The business as SjolystInnovation.AppKit.SiteSettings's public `/company` endpoint describes it. */
+export interface CompanyInfo {
+  name: string;
+  legalName: string;
+  orgNumber: string;
+  vatRegistered: boolean;
+  /** The address on one line, for display. The API derives it from the parts below. */
+  address: string;
+  streetAddress: string;
+  postalCode: string;
+  addressLocality: string;
+  addressRegion: string;
+  email: string;
+  phone: string;
+}
+
+/** What the app knows about the business without the API. Only the name is required. */
+export type CompanyFallback = Partial<CompanyInfo> & { name: string };
+
+/**
+ * Builds the company details for public pages from the API's answer, with the app's own values for
+ * any field it left blank or could not give. The legal name falls back to the name, and VAT to not
+ * registered.
+ */
+export function mergeCompanyInfo(data: Partial<CompanyInfo> | null | undefined, fallback: CompanyFallback): CompanyInfo {
+  const name = data?.name || fallback.name;
+  const pick = (key: Exclude<keyof CompanyInfo, "name" | "legalName" | "vatRegistered">) => data?.[key] || fallback[key] || "";
+  return {
+    name,
+    legalName: data?.legalName || fallback.legalName || name,
+    orgNumber: pick("orgNumber"),
+    vatRegistered: data?.vatRegistered ?? fallback.vatRegistered ?? false,
+    address: pick("address"),
+    streetAddress: pick("streetAddress"),
+    postalCode: pick("postalCode"),
+    addressLocality: pick("addressLocality"),
+    addressRegion: pick("addressRegion"),
+    email: pick("email"),
+    phone: pick("phone"),
+  };
+}
+
+/** Formats the org number with the Norwegian ` MVA` suffix once the business is VAT registered. Returns `""` without a number. */
+export function formatOrgNumber({ orgNumber, vatRegistered }: { orgNumber?: string | null | undefined; vatRegistered?: boolean | null | undefined }): string {
+  if (!orgNumber) return "";
+  return vatRegistered ? `${orgNumber} MVA` : orgNumber;
+}

package/src/api/createApiClient.ts

@@ -3,8 +3,9 @@ import { getSession } from "next-auth/react";
 import { isTerminalSessionError, openSessionPrompt } from "../session/expiry";
 
 /**
- * An axios instance for the signed-in API, for browser code. Each request carries the session's
- * access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps its state.
+ * Creates an axios instance for the signed-in API, for browser code. Each request carries the
+ * session's access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps
+ * its state.
  */
 export function createApiClient(baseURL: string): AxiosInstance {
   if (!baseURL) {

package/src/{errors.ts → api/formatApiError.ts}

@@ -1,14 +1,14 @@
 import axios, { type AxiosResponse } from "axios";
 
 /**
- * Messages to show for a status code. On a 4xx they are used when the response carries no specific
- * message of its own. On a 5xx they win over the body. Key 0 covers a request that got no response,
- * because of a dropped connection or a timeout.
+ * The messages to show for a status code. On a 4xx, `formatApiError` uses them when the response
+ * carries no specific message of its own. On a 5xx, they win over the body. Key 0 covers a request
+ * that got no response, because of a dropped connection or a timeout.
  */
 export type StatusMessages = Partial<Record<number, string>>;
 
 /**
- * Axios codes for a request that never got a response from the network. A browser reports every
+ * The axios codes for a request that never got a response from the network. A browser reports every
  * network failure as ERR_NETWORK. On the server, Node reports the specific cause.
  */
 const NO_RESPONSE_CODES = new Set([
@@ -36,8 +36,8 @@ const NO_RESPONSE_CODES = new Set([
  * as "Bad Gateway". A problem details `title` is never used. ASP.NET Core fills it with generic text
  * such as "Bad Request", which says less than `fallback`.
  *
- * Only single line text counts as a message. Axios's own message, such as "Request failed with
- * status code 500", is never shown. A cancelled request gives `fallback`. Any other `Error` gives
+ * Only single-line text counts as a message. Axios's own message, such as "Request failed with
+ * status code 500", is never shown. A canceled request gives `fallback`. Any other `Error` gives
  * its message.
  */
 export function formatApiError(
@@ -60,18 +60,18 @@ export function formatApiError(
   return fallback;
 }
 
-/** The message the body carries for this failure, if it carries one. */
+/** Gets the message the body carries for this failure, if it carries one. */
 function readBody(response: AxiosResponse): string | undefined {
   const data = parseIfJson(response.data);
   if (typeof data === "string") return singleLine(data);
-  // Only a parsed JSON object has fields to read. A Document, Blob or ArrayBuffer does not.
+  // Only a parsed JSON object has fields to read. A Document, Blob, or ArrayBuffer does not.
   if (!isPlainObject(data)) return undefined;
   return firstText(data.message) ?? firstValidationError(data.errors) ?? singleLine(data.detail);
 }
 
 /**
- * Axios leaves a JSON body as a string when the request asked for text, so parse it here. Plain text
- * such as "Invalid email or password." is not valid JSON and stays as it is.
+ * Parses a JSON body that axios left as a string because the request asked for text. Plain text such
+ * as "Invalid email or password." is not valid JSON and stays as it is.
  */
 function parseIfJson(data: unknown): unknown {
   if (typeof data !== "string") return data;
@@ -98,12 +98,12 @@ function firstValidationError(errors: unknown): string | undefined {
   return undefined;
 }
 
-/** A single line of text, or the first entry when the value is a list of them. */
+/** Gets a single line of text, or the first entry when the value is a list of them. */
 function firstText(value: unknown): string | undefined {
   return singleLine(Array.isArray(value) ? value[0] : value);
 }
 
-/** The trimmed text, when it is one line of text and not HTML. */
+/** Gets the trimmed text, when it is one line of text and not HTML. */
 function singleLine(value: unknown): string | undefined {
   if (typeof value !== "string") return undefined;
   const text = value.trim();

package/src/api/index.ts

@@ -1,7 +1,12 @@
 export { apiFieldErrors } from "./apiFieldErrors";
+export { formatOrgNumber, mergeCompanyInfo } from "./company";
+export type { CompanyFallback, CompanyInfo } from "./company";
 export { createApiClient } from "./createApiClient";
+export { formatApiError } from "./formatApiError";
+export type { StatusMessages } from "./formatApiError";
 export { request } from "./request";
-export { requestRevalidate } from "./requestRevalidate";
+export { defineRevalidateTargets } from "./revalidateTargets";
+export type { RevalidateTargetPaths, RevalidateTargetsConfig } from "./revalidateTargets";
 export {
   createPublicClient,
   createUserService,

package/src/api/request.ts

@@ -1,9 +1,9 @@
 import axios from "axios";
-import { formatApiError, type StatusMessages } from "../errors";
+import { formatApiError, type StatusMessages } from "./formatApiError";
 
 /**
  * Runs an API call and returns its data. A failure throws an `Error` with a message for the user,
- * from `formatApiError`. A cancelled call rethrows the cancel as it is, so the caller can ignore it.
+ * from `formatApiError`. A canceled call rethrows the cancel as it is, so the caller can ignore it.
  */
 export async function request<T>(
   call: () => Promise<{ data: T }>,

package/src/api/revalidateTargets.ts

@@ -0,0 +1,42 @@
+import { normalizePath } from "../seo/site";
+import { requestRevalidate } from "./requestRevalidate";
+
+/** The pages one admin edit changes. */
+export interface RevalidateTargetPaths {
+  /** The paths below each locale segment, such as `/builds/[slug]`. `""` is the locale's front page. */
+  pages?: readonly string[] | undefined;
+  /** 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;
+  targets: Record<T, RevalidateTargetPaths>;
+}
+
+/**
+ * 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[];
+
+  return {
+    targets: Object.fromEntries(names.map(name => [name, name])) as { readonly [K in T]: K },
+    paths: Object.fromEntries(
+      names.map(name => {
+        const { pages = [], root = [] } = targets[name];
+        const localized =
+          locales.length > 0
+            ? locales.flatMap(locale => pages.map(page => `/${locale}${normalizePath(page)}`))
+            : pages.map(page => normalizePath(page) || "/");
+        return [name, [...localized, ...root]];
+      }),
+    ) as Record<T, string[]>,
+    revalidate: (target: T): Promise<void> => requestRevalidate(target),
+  };
+}

package/src/api/services.ts

@@ -4,7 +4,7 @@ import type { Branding } from "../branding/types";
 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 +14,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 +35,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 +88,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 +102,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 +115,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?.();
@@ -134,8 +134,9 @@ export interface LegalPage<Key extends string = string> {
 }
 
 /**
- * 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 terms, privacy, and cookie pages on
+ * SjolystInnovation.AppKit.SiteSettings. Reading is anonymous and returns null for a page that is
+ * missing or cannot be read, so a page shows its fallback.
  */
 export function createLegalService<Key extends string = "terms" | "privacy" | "cookies">(
   api: AxiosInstance,
@@ -153,7 +154,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",
@@ -176,7 +177,7 @@ 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) =>
@@ -191,7 +192,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

@@ -44,12 +44,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 +61,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
@@ -111,9 +113,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;

package/src/branding/BrandingManager.tsx

@@ -7,6 +7,7 @@ import { withDefaults, type TextOverrides } from "../ui/withDefaults";
 import { useBranding } from "./BrandingProvider";
 import { toDataUrl } from "./types";
 
+/** The branding form's text. Pass the app's own language. The defaults are English. */
 export interface BrandingManagerStrings {
   title: string;
   logo: string;
@@ -22,12 +23,14 @@ export interface BrandingManagerStrings {
   saveFailed: string;
 }
 
+const IMAGE_TYPES = "image/png,image/jpeg,image/webp,image/gif,image/x-icon,.ico";
+
 export const defaultBrandingManagerStrings: BrandingManagerStrings = {
   title: "Branding",
   logo: "Logo",
-  logoHint: "Shown in the navbar and footer. PNG/SVG, max 2 MB.",
+  logoHint: "Shown in the navbar and footer. PNG, JPEG, WebP, or GIF, max 2 MB.",
   icon: "Icon (favicon)",
-  iconHint: "Browser tab icon. Square PNG/ICO, max 2 MB.",
+  iconHint: "Browser tab icon. Square PNG or ICO, max 2 MB.",
   none: "none",
   choose: "Choose",
   remove: "Remove",
@@ -37,10 +40,11 @@ export const defaultBrandingManagerStrings: BrandingManagerStrings = {
   saveFailed: "Failed to save branding",
 };
 
+/** 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;
@@ -93,7 +97,8 @@ 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}
           className="hidden"
           onChange={e => onPick(e.target.files?.[0] ?? null)}

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/index.ts

@@ -5,10 +5,9 @@ export {
   type BrandingManagerStrings,
 } from "./BrandingManager";
 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,

package/src/forms/useFormDraft.ts

@@ -32,6 +32,7 @@ function read<T>(storageKey: string): T | null {
   }
 }
 
+/** Options for `useFormDraft`. */
 export interface FormDraftOptions<T> {
   /**
    * The signed-in user's id. A browser profile can be shared, so drafts are stored per user. That
@@ -40,27 +41,28 @@ export interface FormDraftOptions<T> {
    * known.
    */
   owner: string | undefined;
-  /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
+  /** The key for the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
   scope: string;
   /** The form's current values. They must survive `JSON.stringify`. */
   value: T;
 }
 
+/** What `useFormDraft` returns. */
 export interface FormDraft<T> {
   /**
-   * The stored draft, while it is still waiting to be restored or dismissed. Read once the owner is
-   * known and again whenever the owner or scope changes, so it can appear after mount.
+   * The stored draft, while it is still waiting to be restored or dismissed. The hook reads it once
+   * the owner is known and again whenever the owner or scope changes, so it can appear after mount.
    */
   pending: T | null;
-  /** Stop offering the draft. The caller applies the values it wants. */
+  /** Stops offering the draft. The caller applies the values it wants. */
   dismiss: () => void;
-  /** Drop the stored draft after a successful save. */
+  /** Drops the stored draft. Call it after a successful save. */
   clear: () => void;
 }
 
 /**
- * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
- * Values are written half a second after the last change, so only that last half second is at risk.
+ * Keeps a form's values in localStorage so a sign-out, reload, or closed tab does not lose them. The
+ * hook writes them half a second after the last change, so only that last half second is at risk.
  *
  * A draft found at mount is offered for restore, not applied. So an edit form never silently
  * overwrites what the API returned. Saving starts at once, whether or not the offer is answered.

package/src/index.ts

@@ -1,4 +1,2 @@
-export { defineSessionConfig, requireEnv, resolveJwtSecret } from "./config";
+export { defineSessionConfig, requireEnv } from "./config";
 export type { SessionConfig } from "./config";
-export { formatApiError } from "./errors";
-export type { StatusMessages } from "./errors";