@sjolystinnovation/app-kit 0.15.0 → 0.17.0

package/README.md

@@ -170,7 +170,7 @@ export { handler as GET, handler as POST };
 
 | Setting | Type | Description |
 | --- | --- | --- |
-| `apiUrl` | `string` | Base URL of the API. Sign-in posts to `/auth/login` and refresh to `/auth/refresh-token` under it. An empty value throws. |
+| `apiUrl` | `string` | Base URL of the API. Sign-in posts to `/auth/login`, refresh to `/auth/refresh-token` and sign-out to `/auth/logout` under it. An empty value throws. |
 | `env` | `Record<string, string \| undefined>` | The server environment, usually `process.env`. It supplies the secret named by `jwtSecretEnvVar`. |
 | `http` | `AxiosInstance` | In place of `apiUrl`, for tests. The client for sign-in and refresh, with its own base URL. |
 
@@ -264,6 +264,31 @@ 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.
 
+`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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.15.0",
+  "version": "0.17.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/index.ts

@@ -1,3 +1,12 @@
 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/auth/createAuthOptions.ts

@@ -73,6 +73,10 @@ const REMEMBER_ROTATION_MS = 60 * 1000;
 // Sign-in and session reads wait for the API, so a hung connection must not hold them forever.
 const API_TIMEOUT_MS = 10_000;
 
+// Sign-out waits for the API to drop the refresh token, but only briefly, because the cookie is
+// cleared either way.
+const SIGN_OUT_TIMEOUT_MS = 3_000;
+
 function rolesOf(claims: ApiClaims): string[] {
   const raw = claims.role;
   return Array.isArray(raw) ? raw : raw ? [raw] : [];
@@ -249,6 +253,19 @@ export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSe
     session: {
       maxAge: ABSOLUTE_SESSION_MAX_AGE / 1000,
     },
+    events: {
+      // Sign-out also asks the API to delete the refresh token, so a copy of it cannot be used again.
+      // A failure leaves sign-out to the cookie alone.
+      async signOut({ token }) {
+        const refreshToken = (token as AppToken | null)?.refreshToken;
+        if (!refreshToken) return;
+        try {
+          await http.post("/auth/logout", { refreshToken }, { timeout: SIGN_OUT_TIMEOUT_MS });
+        } catch (error) {
+          console.error("Sign-out could not delete the refresh token at the API", failureShape(error));
+        }
+      },
+    },
     callbacks: {
       async jwt({ token: current, user }) {
         let token = current as AppToken;