@sjolystinnovation/app-kit 0.16.0 → 0.18.0

package/README.md

@@ -264,6 +264,35 @@ export const getRecipe = (id: number) =>
 `target`, so an edit shows at once. It posts to `/api/revalidate` unless `endpoint` says otherwise.
 It never throws. On failure the pages' own revalidate window is the fallback.
 
+`apiFieldErrors(error)` reads the per-field messages of an ASP.NET validation problem from a failed
+call or its body, keyed in camelCase to match the form: `{ errors: { OrgNumber: ["..."] } }` becomes
+`{ orgNumber: ["..."] }`. It answers null when there are none, so the form falls back to one message.
+
+`createPublicClient(baseURL)` is the same without the session, for the API's anonymous endpoints. An
+empty `baseURL` throws, and requests only go to `baseURL`.
+
+The services below call the endpoints the SjolystInnovation.AppKit .NET packages map, so an app does
+not write them. `api` is a `createApiClient` instance and `publicApi` a `createPublicClient` one.
+Failures throw an `Error` with the API's message, or with the service's own English fallback.
+`onSaved` runs after a save succeeds, such as `() => requestRevalidate("branding")`.
+
+| Factory | Methods | .NET package |
+| --- | --- | --- |
+| `createUserService(api, publicApi)` | `requestPasswordReset`, `resetPassword`, and for the signed-in user `getProfile`, `updateProfile`, `changePassword`, `exportData`, `deleteAccount` | Auth |
+| `createAdminUsersService(api)` | `getUsers(includeDeleted?)`, `addRole`, `removeRole`, `deleteUser`, `invite` | Auth |
+| `createSettingsService(api, { onSaved? })` | `get`, `update` | SiteSettings |
+| `createBrandingService(api, publicApi, { onSaved? })` | `get`, which answers `{}` when the API cannot be read, and `update(form)` | SiteSettings |
+| `createLegalService<Key>(api, publicApi, { onSaved? })` | `get(key, locale)`, which answers `null` for a missing page, `listAll`, `save` | SiteSettings |
+
+```ts
+import { createApiClient, createPublicClient, createUserService } from "@sjolystinnovation/app-kit/api";
+
+const apiUrl = requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL);
+export default createUserService(createApiClient(apiUrl), createPublicClient(apiUrl));
+```
+
+The response types are exported too: `UserProfile`, `AdminUser`, `SiteSettings` and `LegalPage`.
+
 ### `@sjolystinnovation/app-kit/server`
 
 For server components and route handlers only. It imports `next/cache` and `next/server`.
@@ -991,6 +1020,20 @@ const gargeRule = passwordSchema().max(128, "Be at most 128 characters long.");
 
 `PASSWORD_MIN_LENGTH` holds the minimum, for hint text.
 
+### `zodFieldErrors(error, options?)`
+
+From `@sjolystinnovation/app-kit/validation`. A failed parse's issues by the top-level field they
+belong to, for showing beside each input. Each field gets its first issue's message, or every message
+in order with `all: true`. `message` replaces zod's text, such as with the app's own translations.
+Issues that belong to no field are left out.
+
+```ts
+import { zodFieldErrors } from "@sjolystinnovation/app-kit/validation";
+
+const parsed = contactSchema.safeParse(form);
+if (!parsed.success) setErrors(zodFieldErrors(parsed.error, { message: (issue) => issueMessage(issue, dict) }));
+```
+
 ## Theming
 
 The components draw every colour, corner radius and label size from theme variables with a light

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",

package/src/api/apiFieldErrors.ts

@@ -0,0 +1,23 @@
+import axios from "axios";
+
+/**
+ * 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.
+ */
+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;
+
+  // 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 field = key.charAt(0).toLowerCase() + key.slice(1);
+    fields.set(field, [...(fields.get(field) ?? []), ...messages]);
+  }
+  return fields.size > 0 ? Object.fromEntries(fields) : null;
+}

package/src/api/index.ts

@@ -1,3 +1,13 @@
+export { apiFieldErrors } from "./apiFieldErrors";
 export { createApiClient } from "./createApiClient";
 export { request } from "./request";
 export { requestRevalidate } from "./requestRevalidate";
+export {
+  createPublicClient,
+  createUserService,
+  createSettingsService,
+  createBrandingService,
+  createLegalService,
+  createAdminUsersService,
+} from "./services";
+export type { OnSaved, UserProfile, SiteSettings, LegalPage, AdminUser } from "./services";

package/src/api/services.ts

@@ -0,0 +1,197 @@
+import axios, { type AxiosInstance } from "axios";
+import { getSession } from "next-auth/react";
+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
+ * `createApiClient`, it only sends requests to `baseURL`.
+ */
+export function createPublicClient(baseURL: string): AxiosInstance {
+  if (!baseURL) {
+    throw new Error("createPublicClient needs the API base URL, and baseURL is empty.");
+  }
+  return axios.create({ baseURL, allowAbsoluteUrls: false });
+}
+
+/** 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> {
+  const session = await getSession();
+  const id = (session?.user as { id?: string } | undefined)?.id;
+  if (!id) throw new Error("Not signed in.");
+  return id;
+}
+
+/** The signed-in user's account, as SjolystInnovation.AppKit.Auth's account endpoints return it. */
+export interface UserProfile {
+  id: string;
+  userName: string;
+  firstName: string;
+  lastName: string;
+  email: string;
+  createdAt: string;
+}
+
+/**
+ * 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.
+ */
+export function createUserService(api: AxiosInstance, publicApi: AxiosInstance) {
+  return {
+    requestPasswordReset: (data: { email: string }) =>
+      request(() => publicApi.post<{ message: string }>("/auth/request-password-reset", data), "Failed to request password reset code"),
+
+    resetPassword: (data: { email: string; code: string; newPassword: string }) =>
+      request(() => publicApi.post<{ message: string }>("/auth/reset-password", data), "Failed to reset password"),
+
+    async changePassword(data: { currentPassword: string; newPassword: string }) {
+      const id = await currentUserId();
+      return request(() => api.put<{ message: string }>(`/users/${encodeURIComponent(id)}/password`, data), "Failed to change password");
+    },
+
+    async getProfile() {
+      const id = await currentUserId();
+      return request(() => api.get<UserProfile>(`/users/${encodeURIComponent(id)}/profile`), "Failed to load profile");
+    },
+
+    async updateProfile(data: { firstName: string; lastName: string }) {
+      const id = await currentUserId();
+      return request(() => api.put<UserProfile>(`/users/${encodeURIComponent(id)}/profile`, data), "Failed to update profile");
+    },
+
+    async exportData() {
+      const id = await currentUserId();
+      return request(() => api.get<unknown>(`/users/${encodeURIComponent(id)}/export`), "Failed to export data");
+    },
+
+    async deleteAccount() {
+      const id = await currentUserId();
+      await request(() => api.delete(`/users/${encodeURIComponent(id)}/account`), "Failed to delete account");
+    },
+  };
+}
+
+/** The company settings, as SjolystInnovation.AppKit.SiteSettings's `/settings` endpoint holds them. */
+export interface SiteSettings {
+  contactRecipientEmail: string;
+  companyName: string;
+  companyLegalName: string;
+  orgNumber: string;
+  vatRegistered: boolean;
+  streetAddress: string;
+  postalCode: string;
+  addressLocality: string;
+  addressRegion: string;
+  publicEmail: string;
+  publicPhone: string;
+}
+
+/** The admin's 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"),
+
+    async update(data: SiteSettings) {
+      const saved = await request(() => api.put<SiteSettings>("/settings", data), "Failed to update settings");
+      await options.onSaved?.();
+      return saved;
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function createBrandingService(api: AxiosInstance, publicApi: AxiosInstance, options: { onSaved?: OnSaved } = {}) {
+  return {
+    async get(): Promise<Branding> {
+      try {
+        return (await publicApi.get<Branding>("/branding")).data;
+      } catch {
+        return {};
+      }
+    },
+
+    /** 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?.();
+      return saved;
+    },
+  };
+}
+
+/** 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;
+}
+
+/**
+ * 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.
+ */
+export function createLegalService<Key extends string = "terms" | "privacy" | "cookies">(
+  api: AxiosInstance,
+  publicApi: AxiosInstance,
+  options: { onSaved?: OnSaved } = {},
+) {
+  return {
+    async get(key: Key, locale: string): Promise<LegalPage<Key> | null> {
+      try {
+        return (await publicApi.get<LegalPage<Key>>(`/content/legal/${encodeURIComponent(key)}`, { params: { locale } })).data;
+      } catch {
+        return null;
+      }
+    },
+
+    listAll: () => request(() => api.get<LegalPage<Key>[]>("/content/legal"), "Failed to load legal pages"),
+
+    async save(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",
+      );
+      await options.onSaved?.();
+      return page;
+    },
+  };
+}
+
+/** A user in the admin list, as SjolystInnovation.AppKit.Auth's user admin endpoints return it. */
+export interface AdminUser {
+  id: string;
+  userName: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  createdAt: string;
+  isDeleted: boolean;
+  roles: string[];
+}
+
+/** User administration 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"),
+
+    addRole: (userId: string, role: string) =>
+      request(() => api.post(`/users/${encodeURIComponent(userId)}/roles`, { role }), "Failed to assign role"),
+
+    removeRole: (userId: string, role: string) =>
+      request(() => api.delete(`/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(role)}`), "Failed to remove role"),
+
+    deleteUser: (userId: string) =>
+      request(() => api.delete(`/users/${encodeURIComponent(userId)}/account`), "Failed to delete user"),
+
+    invite: (email: string, firstName: string, lastName: string, role: string) =>
+      request(() => api.post("/users/invite", { email, firstName, lastName, role }), "Failed to send invitation"),
+  };
+}

package/src/validation/fieldErrors.ts

@@ -0,0 +1,34 @@
+import type { z } from "zod";
+
+/** Picks the text shown for an issue, such as a translated message by the issue's code. */
+export type IssueMessage = (issue: z.core.$ZodIssue) => string;
+
+/**
+ * A failed parse's issues by the top-level field they belong to, for showing beside each input. By
+ * default each field gets its first issue's message. With `all: true` it gets every message, in order.
+ * `message` replaces zod's text, such as with the app's own translations. Issues without a field,
+ * from a refinement of the whole object, are left out.
+ */
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options?: { all?: false; message?: IssueMessage },
+): Partial<Record<Extract<keyof T, string>, string>>;
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options: { all: true; message?: IssueMessage },
+): Partial<Record<Extract<keyof T, string>, string[]>>;
+export function zodFieldErrors<T>(
+  error: z.ZodError<T>,
+  options: { all?: boolean; message?: IssueMessage } = {},
+): object {
+  // A Map, so a field named like an Object property such as "constructor" is still just a field.
+  const errors = new Map<string, string[]>();
+  for (const issue of error.issues) {
+    const field = issue.path[0];
+    if (typeof field !== "string") continue;
+    const messages = errors.get(field) ?? [];
+    messages.push(options.message ? options.message(issue) : issue.message);
+    errors.set(field, messages);
+  }
+  return Object.fromEntries([...errors].map(([field, messages]) => [field, options.all ? messages : messages[0]]));
+}

package/src/validation/index.ts

@@ -1,2 +1,4 @@
 export { PASSWORD_MIN_LENGTH, defaultPasswordStrings, passwordSchema } from "./password";
 export type { PasswordStrings } from "./password";
+export { zodFieldErrors } from "./fieldErrors";
+export type { IssueMessage } from "./fieldErrors";