@sjolystinnovation/app-kit 0.22.0 → 1.0.1

package/src/admin/adminUsersPanelStrings.ts

@@ -1,5 +1,47 @@
 // Plain values, with no "use client", so a server component can import 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.
@@ -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 {
@@ -15,6 +34,8 @@ export interface LegalPagesEditorStrings {
   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/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";
+
+/**
+ * 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 or the response body. Returns null when
- * there are no field errors, so the caller falls back to one message for the whole form.
+ * `{ 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/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/api/index.ts

@@ -1,3 +1,4 @@
+export { apiErrorCode } from "./apiErrorCode";
 export { apiFieldErrors } from "./apiFieldErrors";
 export { formatOrgNumber, mergeCompanyInfo } from "./company";
 export type { CompanyFallback, CompanyInfo } from "./company";
@@ -14,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 { 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 canceled 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;
   }
 }

package/src/api/services.ts

@@ -1,6 +1,8 @@
 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";
 
 /**
@@ -124,26 +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;
 }
 
 /**
- * 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.
+ * 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;
@@ -165,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;
@@ -183,6 +210,9 @@ export function createAdminUsersService(api: AxiosInstance) {
     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"),
 

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";
 
@@ -102,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) {
@@ -242,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));
           }
         },
       }),