@sjolystinnovation/app-kit 0.21.0 → 1.0.0

package/src/admin/StatHistoryChart.tsx

@@ -9,10 +9,11 @@ export interface StatSeries<T> {
   /** The field of each day's row the line plots. A missing or non-numeric value counts as zero. */
   key: keyof T & string;
   label: string;
-  /** The line's colour. Defaults to the next colour in `STAT_SERIES_COLORS`. */
+  /** The line's color. Defaults to the next color in `STAT_SERIES_COLORS`. */
   color?: string | undefined;
 }
 
+/** Props for `StatHistoryChart`. */
 export interface StatHistoryChartProps<T extends { date: string }> {
   /** One row per day, oldest first, with `date` as `YYYY-MM-DD`. */
   data: readonly T[];
@@ -25,8 +26,8 @@ const H = 240;
 const PAD = { top: 16, right: 16, bottom: 28, left: 32 };
 
 /**
- * A line per series over the days, with the scale from zero to the highest shown value. The legend
- * buttons hide and show a line, and the scale follows the lines that are shown.
+ * Renders a line per series over the days, with the scale from zero to the highest shown value. The
+ * legend buttons hide and show a line, and the scale follows the lines that are shown.
  */
 export function StatHistoryChart<T extends { date: string }>({ data, series, strings }: StatHistoryChartProps<T>) {
   const text = withDefaults(defaultStatHistoryChartStrings, strings);

package/src/admin/adminUsersPanelStrings.ts

@@ -1,8 +1,50 @@
 // Plain values, with no "use client", so a server component can import them.
 
 /**
- * The users panel's text. Pass the app's own language. The defaults are English. `{name}` and `{role}`
- * are filled in where a text names them.
+ * The panel's text for each field error code of SjolystInnovation.AppKit.Auth's invite endpoint,
+ * shown under the field. `{max}` in `tooLong` becomes the field's character limit. The panel shows
+ * the API's own message for a code that is not here.
+ */
+export interface AdminUsersValidationStrings {
+  required: string;
+  tooLong: string;
+  invalidEmail: string;
+  /** The chosen role is not one the API lets an admin give. */
+  unknownRole: string;
+  /** Another account took the email while the invite was sent. */
+  emailTaken: string;
+}
+
+/**
+ * The panel's text for each code of SjolystInnovation.AppKit.Auth's role and invite endpoints that
+ * is not about one field. The panel shows the API's own message for a code that is not here.
+ */
+export interface AdminUsersErrorStrings {
+  unknownRole: string;
+  /** An admin tried to take away their own admin role. */
+  ownAdminRole: string;
+  /** Taking the admin role from the last active admin. */
+  lastAdmin: string;
+  roleAssignFailed: string;
+  roleRemoveFailed: string;
+  /** The invited email already has an account. */
+  emailTaken: string;
+}
+
+/**
+ * The panel's text for each code SjolystInnovation.AppKit.Auth gives when deleting an account. The
+ * panel shows the API's own message for a code that is not here.
+ */
+export interface AdminUsersDeleteErrorStrings {
+  /** Deleting the last active admin. */
+  lastAdmin: string;
+  /** Another account change happened at the same time. Trying again may work. */
+  accountChangeConflict: string;
+}
+
+/**
+ * The users panel's text. Pass the app's own language. The defaults are English. The panel fills in
+ * `{name}` and `{role}` where a text names them.
  */
 export interface AdminUsersPanelStrings {
   users: string;
@@ -19,7 +61,7 @@ export interface AdminUsersPanelStrings {
   /** The tag after a deleted user's name. */
   deleted: string;
   delete: string;
-  /** Before the role name on the button that takes a role away. */
+  /** The text before the role name on the button that takes a role away. */
   remove: string;
   noRoles: string;
   addRole: string;
@@ -37,6 +79,12 @@ export interface AdminUsersPanelStrings {
   inviteIncomplete: string;
   inviteSent: string;
   inviteFailed: string;
+  /** The invite field error texts, by code. Any code left out keeps its default. */
+  validation: AdminUsersValidationStrings;
+  /** The role and invite refusal texts, by code. Any code left out keeps its default. */
+  errors: AdminUsersErrorStrings;
+  /** The delete refusal texts, by code. Any code left out keeps its default. */
+  deleteErrors: AdminUsersDeleteErrorStrings;
 }
 
 export const defaultAdminUsersPanelStrings: AdminUsersPanelStrings = {
@@ -70,4 +118,23 @@ export const defaultAdminUsersPanelStrings: AdminUsersPanelStrings = {
   inviteIncomplete: "Fill in the name and email",
   inviteSent: "Invitation sent. The user gets a code to set a password.",
   inviteFailed: "Failed to send the invitation",
+  validation: {
+    required: "Required.",
+    tooLong: "At most {max} characters.",
+    invalidEmail: "Not a valid email address.",
+    unknownRole: "Unknown role.",
+    emailTaken: "That email already has an account.",
+  },
+  errors: {
+    unknownRole: "Unknown role.",
+    ownAdminRole: "You cannot remove your own admin role.",
+    lastAdmin: "The last admin keeps the admin role. Give someone else the role first.",
+    roleAssignFailed: "Failed to assign role.",
+    roleRemoveFailed: "Failed to remove role.",
+    emailTaken: "That email already has an account.",
+  },
+  deleteErrors: {
+    lastAdmin: "The last admin account cannot be deleted. Give someone else the admin role first.",
+    accountChangeConflict: "Another change to the accounts happened at the same time. Try again.",
+  },
 };

package/src/admin/companySettingsFormStrings.ts

@@ -1,5 +1,20 @@
 // Plain values, with no "use client", so a server component can import them.
 
+/**
+ * The form's text for each field error code of SjolystInnovation.AppKit.SiteSettings. `{max}` in
+ * `tooLong` becomes the field's character limit. The form shows the API's own message for a code
+ * that is not here.
+ */
+export interface CompanySettingsValidationStrings {
+  required: string;
+  tooLong: string;
+  invalidEmail: string;
+  orgNumberRequiredForVat: string;
+  invalidOrgNumber: string;
+  invalidPostalCode: string;
+  placeRequired: string;
+}
+
 /** The company settings form's text. Pass the app's own language. The defaults are English. */
 export interface CompanySettingsFormStrings {
   contactRecipient: string;
@@ -23,6 +38,8 @@ export interface CompanySettingsFormStrings {
   loadFailed: string;
   saved: string;
   saveFailed: string;
+  /** The field error texts, by code. Any code left out keeps its default. */
+  validation: CompanySettingsValidationStrings;
 }
 
 export const defaultCompanySettingsFormStrings: CompanySettingsFormStrings = {
@@ -47,4 +64,13 @@ export const defaultCompanySettingsFormStrings: CompanySettingsFormStrings = {
   loadFailed: "Failed to load settings",
   saved: "Settings saved",
   saveFailed: "Failed to save",
+  validation: {
+    required: "Required.",
+    tooLong: "At most {max} characters.",
+    invalidEmail: "Not a valid email address.",
+    orgNumberRequiredForVat: "An organisation number is required when the business is VAT registered.",
+    invalidOrgNumber: "Not a valid organisation number. It has nine digits and ends in a check digit.",
+    invalidPostalCode: "A Norwegian postal code is four digits.",
+    placeRequired: "A postal code needs the place name that goes with it.",
+  },
 };

package/src/admin/emailStatsPanelStrings.ts

@@ -0,0 +1,29 @@
+// Plain values, with no "use client", so a server component can import them.
+
+/**
+ * The email stats panel's text. Pass the app's own language. The defaults are English. The panel
+ * fills in `{days}` in `title`.
+ */
+export interface EmailStatsPanelStrings {
+  title: string;
+  /** The emails the app asked Brevo to send. */
+  sent: string;
+  delivered: string;
+  /** Hard and soft bounces together. */
+  bounces: string;
+  /** Blocked emails and spam reports together. */
+  blocked: string;
+  loading: string;
+  /** The text shown when the stats could not load, such as when Brevo does not answer. */
+  unavailable: string;
+}
+
+export const defaultEmailStatsPanelStrings: EmailStatsPanelStrings = {
+  title: "Email (last {days} days)",
+  sent: "Sent",
+  delivered: "Delivered",
+  bounces: "Bounces",
+  blocked: "Blocked / spam",
+  loading: "Loading…",
+  unavailable: "Unavailable.",
+};

package/src/admin/index.ts

@@ -1,20 +1,29 @@
 export { CompanySettingsForm } from "./CompanySettingsForm";
 export type { CompanySettingsFormProps } from "./CompanySettingsForm";
 export { defaultCompanySettingsFormStrings } from "./companySettingsFormStrings";
-export type { CompanySettingsFormStrings } from "./companySettingsFormStrings";
+export type { CompanySettingsFormStrings, CompanySettingsValidationStrings } from "./companySettingsFormStrings";
 export { AdminShell } from "./AdminShell";
 export type { AdminShellProps, AdminTab } from "./AdminShell";
 export { StatHistoryChart } from "./StatHistoryChart";
-export { STAT_SERIES_COLORS, defaultStatHistoryChartStrings } from "./statHistoryChartStrings";
+export { defaultStatHistoryChartStrings } from "./statHistoryChartStrings";
 export type { StatHistoryChartProps, StatSeries } from "./StatHistoryChart";
 export type { StatHistoryChartStrings } from "./statHistoryChartStrings";
+export { EmailStatsPanel } from "./EmailStatsPanel";
+export type { EmailStatsPanelProps } from "./EmailStatsPanel";
+export { defaultEmailStatsPanelStrings } from "./emailStatsPanelStrings";
+export type { EmailStatsPanelStrings } from "./emailStatsPanelStrings";
 export { AdminUsersPanel } from "./AdminUsersPanel";
 export type { AdminUsersPanelProps } from "./AdminUsersPanel";
 export { defaultAdminUsersPanelStrings } from "./adminUsersPanelStrings";
-export type { AdminUsersPanelStrings } from "./adminUsersPanelStrings";
+export type {
+  AdminUsersDeleteErrorStrings,
+  AdminUsersErrorStrings,
+  AdminUsersPanelStrings,
+  AdminUsersValidationStrings,
+} from "./adminUsersPanelStrings";
 export { LegalPagesEditor } from "./LegalPagesEditor";
 export type { LegalPagesEditorProps } from "./LegalPagesEditor";
-export { defaultLegalPagesEditorStrings } from "./legalPagesEditorStrings";
-export type { LegalPagesEditorStrings } from "./legalPagesEditorStrings";
+export { defaultLegalPageKeyLabels, defaultLegalPagesEditorStrings } from "./legalPagesEditorStrings";
+export type { LegalPagesEditorStrings, LegalPagesValidationStrings } from "./legalPagesEditorStrings";
 export { LocaleTabs } from "./LocaleTabs";
 export type { LocaleTabsProps } from "./LocaleTabs";

package/src/admin/legalPagesEditorStrings.ts

@@ -1,4 +1,23 @@
 // Plain values, with no "use client", so a server component can import them.
+import type { DefaultLegalPageKey } from "../legal/keys";
+
+/**
+ * The editor's text for each field error code of SjolystInnovation.AppKit.SiteSettings that saving a
+ * legal page can give. `{max}` in `tooLong` becomes the title's character limit. The editor shows the
+ * API's own message for a code that is not here.
+ */
+export interface LegalPagesValidationStrings {
+  /** A blank title or content. The editor also shows it under a blank field before it calls the API. */
+  required: string;
+  tooLong: string;
+}
+
+/** The tab labels of the default legal pages, in English. */
+export const defaultLegalPageKeyLabels: Record<DefaultLegalPageKey, string> = {
+  terms: "Terms",
+  privacy: "Privacy",
+  cookies: "Cookies",
+};
 
 /** The legal pages editor's text. Pass the app's own language. The defaults are English. */
 export interface LegalPagesEditorStrings {
@@ -11,10 +30,12 @@ export interface LegalPagesEditorStrings {
   save: string;
   saving: string;
   loadFailed: string;
-  /** When the title or the content is blank. */
+  /** The message shown when the title or the content is blank. */
   required: string;
   saved: string;
   saveFailed: string;
+  /** The field error texts, by code. Any code left out keeps its default. */
+  validation: LegalPagesValidationStrings;
 }
 
 export const defaultLegalPagesEditorStrings: LegalPagesEditorStrings = {
@@ -29,4 +50,8 @@ export const defaultLegalPagesEditorStrings: LegalPagesEditorStrings = {
   required: "Fill in the title and the content",
   saved: "Page saved",
   saveFailed: "Failed to save the page",
+  validation: {
+    required: "Required.",
+    tooLong: "At most {max} characters.",
+  },
 };

package/src/admin/statHistoryChartStrings.ts

@@ -1,7 +1,8 @@
 // Plain values, with no "use client", so a server component can import them.
 
+/** The chart's text. Pass the app's own language. The defaults are English. */
 export interface StatHistoryChartStrings {
-  /** Shown instead of the chart when there are no days yet. */
+  /** The text shown instead of the chart when there are no days yet. */
   empty: string;
   /** The chart's accessible name. */
   chart: string;
@@ -12,5 +13,5 @@ export const defaultStatHistoryChartStrings: StatHistoryChartStrings = {
   chart: "Stats over time",
 };
 
-/** The default line colours, in order: blue, green, amber, teal and purple. */
+/** The default line colors, in order: blue, green, amber, teal, and purple. */
 export const STAT_SERIES_COLORS = ["#2563eb", "#16a34a", "#d97706", "#0d9488", "#9333ea"] as const;

package/src/api/apiErrorCode.ts

@@ -0,0 +1,28 @@
+import { failureBody } from "./failureBody";
+
+/**
+ * Gets the stable code of a failure that is not about one field, such as `lockedOut` or
+ * `invalidResetCode` from `{ "message": "...", "code": "invalidResetCode" }`, for showing the app's
+ * own text. Takes the failed axios call, the response body, or the `Error` that `request` throws.
+ * Returns undefined when the failure has no code, so the caller shows the API's message.
+ */
+export function apiErrorCode(error: unknown): string | undefined {
+  const data = failureBody(error);
+  // An axios error is read through its body above. Its own `code`, such as ERR_NETWORK, is not the API's.
+  const code = data instanceof Error ? (data as { errorCode?: unknown }).errorCode : bodyCode(data);
+  return typeof code === "string" && code !== "" ? code : undefined;
+}
+
+/** Reads `code` from a JSON body, also when axios left the body as text. */
+function bodyCode(data: unknown): unknown {
+  let body = data;
+  if (typeof data === "string") {
+    try {
+      body = JSON.parse(data);
+    } catch {
+      return undefined;
+    }
+  }
+  // A text, number or list has no `code` of its own, so only a JSON object gives one.
+  return (body as { code?: unknown } | null | undefined)?.code;
+}

package/src/api/apiFieldErrors.ts

@@ -1,23 +1,94 @@
-import axios from "axios";
+import { failureBody } from "./failureBody";
 
 /**
- * The per-field messages of an ASP.NET validation problem, keyed by the field's name in camelCase so
- * they match the form's own names: `{ errors: { OrgNumber: ["..."] } }` becomes
- * `{ orgNumber: ["..."] }`. Takes the failed axios call or the response body. Answers null when there
- * are no field errors, so the caller falls back to one message for the whole form.
+ * One field error of an ASP.NET validation problem. `message` is the API's text. `code` is the stable
+ * code from the problem's `codes` extension, such as `invalidOrgNumber`, for showing the app's own
+ * text. `limit` is the field's number from the `limits` extension, such as the most characters for
+ * the code `tooLong`.
+ */
+export interface ApiFieldError {
+  message: string;
+  code?: string;
+  limit?: number;
+}
+
+/**
+ * Gets the per-field messages of an ASP.NET validation problem, keyed by the field's name in
+ * camelCase so they match the form's own names: `{ errors: { OrgNumber: ["..."] } }` becomes
+ * `{ orgNumber: ["..."] }`. Takes the failed axios call, the response body, or the `Error` that
+ * `request` throws. Returns null when there are no field errors, so the caller falls back to one
+ * message for the whole form.
  */
 export function apiFieldErrors(error: unknown): Record<string, string[]> | null {
-  const data = axios.isAxiosError(error) ? error.response?.data : error;
-  const errors = data && typeof data === "object" ? (data as { errors?: unknown }).errors : undefined;
-  if (!errors || typeof errors !== "object" || Array.isArray(errors)) return null;
+  const details = apiFieldErrorDetails(error);
+  if (!details) return null;
+  return Object.fromEntries(Object.entries(details).map(([field, list]) => [field, list.map(d => d.message)]));
+}
 
+/**
+ * Gets the same field errors as `apiFieldErrors`, each with its code and limit when the problem has
+ * the `codes` and `limits` extensions: `{ errors: { OrgNumber: ["..."] }, codes: { OrgNumber:
+ * ["invalidOrgNumber"] } }` becomes `{ orgNumber: [{ message: "...", code: "invalidOrgNumber" }] }`.
+ * A code lines up with the message at the same place in its field's list.
+ */
+export function apiFieldErrorDetails(error: unknown): Record<string, ApiFieldError[]> | null {
   // A Map, so a field named like an Object property such as "constructor" is still just a field.
-  const fields = new Map<string, string[]>();
-  for (const [key, value] of Object.entries(errors as Record<string, unknown>)) {
-    const messages = (Array.isArray(value) ? value : [value]).filter((m): m is string => typeof m === "string" && m !== "");
-    if (messages.length === 0) continue;
+  const fields = new Map<string, ApiFieldError[]>();
+  for (const [key, list] of problemEntries(error)) {
+    if (list.length === 0) continue;
     const field = key.charAt(0).toLowerCase() + key.slice(1);
-    fields.set(field, [...(fields.get(field) ?? []), ...messages]);
+    fields.set(field, [...(fields.get(field) ?? []), ...list]);
   }
   return fields.size > 0 ? Object.fromEntries(fields) : null;
 }
+
+type Entries = [string, ApiFieldError[]][];
+
+/**
+ * Reads the field errors as they come, from a problem body or from the `Error` that `request` throws.
+ * Gives none for anything else.
+ */
+function problemEntries(error: unknown): Entries {
+  const data = failureBody(error);
+  if (data instanceof Error) {
+    const kept = data as { fieldErrorDetails?: unknown; fieldErrors?: unknown };
+    if (isRecord(kept.fieldErrorDetails)) return keptEntries(kept.fieldErrorDetails);
+    return isRecord(kept.fieldErrors) ? bodyEntries(kept.fieldErrors, {}, {}) : [];
+  }
+  if (!isRecord(data) || !isRecord(data.errors)) return [];
+  return bodyEntries(data.errors, isRecord(data.codes) ? data.codes : {}, isRecord(data.limits) ? data.limits : {});
+}
+
+function bodyEntries(errors: Record<string, unknown>, codes: Record<string, unknown>, limits: Record<string, unknown>): Entries {
+  return Object.entries(errors).map(([key, value]) => {
+    // A key named like an Object property reads something that is not text or a number, which toError drops.
+    const fieldCodes = codes[key];
+    const codeList = Array.isArray(fieldCodes) ? fieldCodes : [fieldCodes];
+    const limit = limits[key];
+    const messages = Array.isArray(value) ? value : [value];
+    return [key, messages.flatMap((message, i) => toError({ message, code: codeList[i], limit }))];
+  });
+}
+
+function keptEntries(details: Record<string, unknown>): Entries {
+  return Object.entries(details).map(([key, value]) => [
+    key,
+    (Array.isArray(value) ? value : []).flatMap(item => (isRecord(item) ? toError(item) : [])),
+  ]);
+}
+
+/** Keeps a non-empty text message, with its code and limit only when they have the right types. */
+function toError({ message, code, limit }: Record<string, unknown>): ApiFieldError[] {
+  if (typeof message !== "string" || message === "") return [];
+  return [
+    {
+      message,
+      ...(typeof code === "string" && code !== "" ? { code } : {}),
+      ...(typeof limit === "number" && Number.isFinite(limit) ? { limit } : {}),
+    },
+  ];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/src/api/company.ts

@@ -18,8 +18,9 @@ export interface CompanyInfo {
 export type CompanyFallback = Partial<CompanyInfo> & { name: string };
 
 /**
- * The company details for public pages: 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.
+ * 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;
@@ -39,7 +40,7 @@ export function mergeCompanyInfo(data: Partial<CompanyInfo> | null | undefined,
   };
 }
 
-/** The org number with the Norwegian ` MVA` suffix once the business is VAT registered. Empty without a number. */
+/** 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/api/failureBody.ts

@@ -0,0 +1,10 @@
+/**
+ * The response body of a failed axios call, or the value itself when it is not one. It checks the
+ * axios flag like `axios.isAxiosError` does, without importing axios, so the `ui` entry can read a
+ * failure's codes while axios stays an optional peer.
+ */
+export function failureBody(error: unknown): unknown {
+  if (!error || typeof error !== "object") return error;
+  const failed = error as { isAxiosError?: unknown; response?: { data?: unknown } };
+  return failed.isAxiosError === true ? failed.response?.data : error;
+}

package/src/api/fieldErrorText.ts

@@ -0,0 +1,32 @@
+import { apiErrorCode } from "./apiErrorCode";
+import { apiFieldErrorDetails, type ApiFieldError } from "./apiFieldErrors";
+
+/**
+ * The app's text for a field error when `validation` has text for the error's code, with `{max}`
+ * filled in from the error's limit. Otherwise the API's message.
+ */
+export function fieldErrorText(error: ApiFieldError, validation: object): string {
+  const code = error.code ?? "";
+  const template = Object.hasOwn(validation, code) ? (validation as Record<string, string>)[code] : undefined;
+  if (template === undefined) return error.message;
+  if (!template.includes("{max}")) return template;
+  return error.limit === undefined ? error.message : template.replaceAll("{max}", String(error.limit));
+}
+
+/**
+ * The text for each field error of a failed call, keyed by field like `apiFieldErrors`, from
+ * `fieldErrorText`. Empty when the call has no field errors.
+ */
+export function fieldErrorTexts(error: unknown, validation: object): Record<string, string[]> {
+  const details = apiFieldErrorDetails(error) ?? {};
+  return Object.fromEntries(Object.entries(details).map(([field, list]) => [field, list.map(e => fieldErrorText(e, validation))]));
+}
+
+/**
+ * The app's text for a failed call's code that is not about one field, such as `lockedOut`, when
+ * `errors` has text for it. Otherwise the failure's own message, or `fallback` when it has none.
+ */
+export function errorText(error: unknown, errors: object, fallback: string): string {
+  const message = error instanceof Error && error.message ? error.message : fallback;
+  return fieldErrorText({ message, code: apiErrorCode(error) ?? "" }, errors);
+}

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,9 +1,11 @@
+export { apiErrorCode } from "./apiErrorCode";
 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 {
@@ -13,5 +15,8 @@ export {
   createBrandingService,
   createLegalService,
   createAdminUsersService,
+  createEmailStatsService,
 } from "./services";
-export type { OnSaved, UserProfile, SiteSettings, LegalPage, AdminUser } from "./services";
+export type { LegalServiceOptions } from "./services";
+export type { OnSaved, UserProfile, SiteSettings, AdminUser, EmailStats } from "./services";
+export type { LegalPage } from "./legalPage";

package/src/api/legalPage.ts

@@ -0,0 +1,10 @@
+// Types only, with no imports, so the legal page view can use them without axios or next-auth.
+
+/** 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;
+}

package/src/api/request.ts

@@ -1,9 +1,14 @@
 import axios from "axios";
-import { formatApiError, type StatusMessages } from "../errors";
+import { apiErrorCode } from "./apiErrorCode";
+import { apiFieldErrorDetails, apiFieldErrors } from "./apiFieldErrors";
+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`. When the API answers with a validation problem, the error also carries its
+ * per-field messages with their codes, which `apiFieldErrors` and the forms' field errors read. When
+ * the API answers with a code for the whole call, the error carries it for `apiErrorCode`. A
+ * canceled call rethrows the cancel as it is, so the caller can ignore it.
  */
 export async function request<T>(
   call: () => Promise<{ data: T }>,
@@ -16,7 +21,12 @@ export async function request<T>(
   } catch (error: unknown) {
     if (axios.isCancel(error)) throw error;
     // No cause. Errors get logged, and the axios error carries the access token and request body.
-    // eslint-disable-next-line preserve-caught-error
-    throw new Error(formatApiError(error, fallback, statusMessages));
+    const failure = new Error(formatApiError(error, fallback, statusMessages));
+    // Only the field messages with their codes, never the response, for the same reason.
+    const fieldErrors = apiFieldErrors(error);
+    if (fieldErrors) Object.assign(failure, { fieldErrors, fieldErrorDetails: apiFieldErrorDetails(error) });
+    const errorCode = apiErrorCode(error);
+    if (errorCode) Object.assign(failure, { errorCode });
+    throw failure;
   }
 }