@sjolystinnovation/app-kit 0.6.0 → 0.7.0

package/README.md

@@ -260,6 +260,55 @@ export const getRecipe = (id: number) =>
   request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
 ```
 
+`requestRevalidate(target, endpoint?)` asks the app's revalidate route to purge the pages behind
+`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.
+
+### `@sjolystinnovation/app-kit/server`
+
+For server components and route handlers only. It imports `next/cache` and `next/server`.
+
+`createPublicApi(baseUrl, options?)` returns cached GETs against the API's anonymous endpoints:
+
+- `publicGet(path, { tags? })` gives the data, or null when the API answers 404. An unreachable or
+  failing API throws `PublicApiError`, so a failed fetch is never cached as an empty page in place
+  of a working one.
+- `publicGetOptional(path, { tags? })` gives null on any failure, for data a page can do without.
+- `publicGetWithMeta(path, { tags? })` also gives `lastModified`, from the `Last-Modified` header.
+
+Responses stay fresh for 60 seconds unless `options.revalidate` says otherwise. An empty `baseUrl`
+throws. Each path starts with a single `/`, or the call throws. A path with a `.` or `..` segment,
+encoded or not, gives null without a request, the same as a 404. Run a slug or other user input
+through `encodeURIComponent` before putting it in a path.
+
+```ts
+// src/lib/publicApi.ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createPublicApi } from "@sjolystinnovation/app-kit/server";
+
+export const { publicGet, publicGetOptional, publicGetWithMeta } = createPublicApi(
+  requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+);
+```
+
+`createRevalidateRoute({ targets, role })` returns a `POST` handler for `app/api/revalidate/route.ts`.
+Each target maps to the page paths it purges. A path with a dynamic segment, such as
+`/builds/[slug]`, purges every page of that route. The target name is purged as a cache tag too, so
+tag the fetches behind it with the same name. The handler answers 403 unless the caller has a live
+session with `role`: signed in within the last seven days, with no refused refresh and an access
+token that has not expired. It answers 415 unless the body is sent as JSON, which
+`requestRevalidate` does, and 400 for a target it does not know.
+
+```ts
+// src/app/api/revalidate/route.ts
+import { createRevalidateRoute } from "@sjolystinnovation/app-kit/server";
+
+export const POST = createRevalidateRoute({
+  role: "Admin",
+  targets: { builds: ["/builds", "/builds/[slug]", "/sitemap.xml"], legal: ["/terms", "/privacy"] },
+});
+```
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
@@ -368,6 +417,21 @@ layout that needs its own decision, such as a role check, so it agrees with the
 
 `SessionGate` is the type of the result.
 
+### `AppSessionProvider`
+
+From `@sjolystinnovation/app-kit/session/react`. next-auth's `SessionProvider`, reading the session
+again every four minutes. Each read lets the jwt callback renew the access token before it expires,
+so an open tab does not find a dead session on the next save. It also keeps what `useSession`
+reports in this tab up to date. next-auth polls only once a session exists.
+
+```tsx
+<AppSessionProvider>{children}</AppSessionProvider>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `refetchInterval` | `number` | Seconds between reads. Defaults to 240. Keep it under five minutes, the time before expiry when a refresh falls due. |
+
 ### `ProtectedGate`
 
 From `@sjolystinnovation/app-kit/session/react`. Wraps the protected part of the app. It renders the
@@ -385,6 +449,25 @@ arrival to `loginHref`. It never redirects while the re-sign-in prompt is open.
 | `loginHref` | `string` | Where the redirect goes. An app with a locale in the path builds it for the current locale. |
 | `fallback` | `ReactNode` | What shows while the page may not render yet. Defaults to nothing. |
 
+### `RoleGate`
+
+From `@sjolystinnovation/app-kit/session/react`. Renders its children only for a user with `role`.
+Place it inside `ProtectedGate`. While the re-sign-in prompt recovers a signed-out session there is
+no user and so no roles. The page stays up only on the path where the session last had the role.
+
+```tsx
+<RoleGate role="Admin" fallback={<p>Loading…</p>} denied={<p>You do not have access.</p>}>
+  {children}
+</RoleGate>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `role` | `string` | The role the page needs, as it appears in `session.user.roles`. |
+| `fallback` | `ReactNode` | What shows while the session or its roles are not known yet. Defaults to nothing. |
+| `denied` | `ReactNode` | What a signed-in user without the role sees. Give this or `deniedHref`. |
+| `deniedHref` | `string` | Where a signed-in user without the role is sent instead. |
+
 ### `SessionExpiryGuard`
 
 From `@sjolystinnovation/app-kit/session/react`. Render it once, inside the `SessionProvider`. It
@@ -520,6 +603,16 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
+### `toast`
+
+From `@sjolystinnovation/app-kit/toast`. sonner's `toast`, except that `toast.error` shows nothing
+while the re-sign-in prompt is open. The prompt already says why the request failed. Every other
+toast passes through, and so do the error states of `toast.promise`.
+
+```ts
+import { toast } from "@sjolystinnovation/app-kit/toast";
+```
+
 ## Theming
 
 The components draw every colour, corner radius and label size from theme variables with a light
@@ -587,6 +680,8 @@ with it and has to set the ones it uses itself.
 
 - Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
   app installs itself.
+- For `@sjolystinnovation/app-kit/toast`: sonner 2, as an optional peer dependency. Install a single
+  copy, because two copies keep two separate toast stores.
 - `jsonwebtoken` comes with the package. `@sjolystinnovation/app-kit/auth` uses it on the server.
 - For `@sjolystinnovation/app-kit/ui` and the components in `session/react`: Tailwind CSS 4 and
   `@heroicons/react` 2. The focus ring and the primary button use the theme's `primary` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -21,7 +21,9 @@
     "./forms": "./src/forms/index.ts",
     "./auth": "./src/auth/index.ts",
     "./api": "./src/api/index.ts",
+    "./server": "./src/server/index.ts",
     "./ui": "./src/ui/index.ts",
+    "./toast": "./src/toast/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -41,7 +43,13 @@
     "next": "^16",
     "next-auth": "^4.24",
     "react": "^19",
-    "react-dom": "^19"
+    "react-dom": "^19",
+    "sonner": "^2"
+  },
+  "peerDependenciesMeta": {
+    "sonner": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@heroicons/react": "^2.2.0",
@@ -57,6 +65,7 @@
     "next-auth": "^4.24.15",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "sonner": "^2.0.8",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3"
   },

package/src/api/index.ts

@@ -1,2 +1,3 @@
 export { createApiClient } from "./createApiClient";
 export { request } from "./request";
+export { requestRevalidate } from "./requestRevalidate";

package/src/api/requestRevalidate.ts

@@ -0,0 +1,15 @@
+/**
+ * Asks the app's revalidate route to purge the pages behind `target`, so an admin edit shows at
+ * once. Best effort: on failure the pages' revalidate window is the fallback.
+ */
+export async function requestRevalidate(target: string, endpoint = "/api/revalidate"): Promise<void> {
+  try {
+    await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ target }),
+    });
+  } catch {
+    // Best effort, see above.
+  }
+}

package/src/auth/createAuthOptions.ts

@@ -4,7 +4,7 @@ import type { NextAuthOptions, Session, User } from "next-auth";
 import CredentialsProvider from "next-auth/providers/credentials";
 import type { JWT } from "next-auth/jwt";
 import { resolveJwtSecret, type SessionConfig } from "../config";
-import { SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
+import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
 
 /** The signed-in user, as the session carries it. */
 export interface SessionUser {
@@ -60,8 +60,6 @@ export type AuthOptionsSettings = {
     }
 );
 
-const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
-
 // Refresh ahead of expiry, so the token is still fresh when the user saves.
 const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
 
@@ -72,9 +70,6 @@ const MIN_REFRESH_GAP_MS = 30 * 1000;
 // How long a refresh result is remembered. It is also the wait before a failed refresh is retried.
 const REMEMBER_ROTATION_MS = 60 * 1000;
 
-// How far this server's clock may differ from the API's when a token's times are checked.
-const CLOCK_TOLERANCE_S = 60;
-
 // Sign-in and session reads wait for the API, so a hung connection must not hold them forever.
 const API_TIMEOUT_MS = 10_000;
 

package/src/server/index.ts

@@ -0,0 +1,4 @@
+export { createPublicApi, PublicApiError } from "./publicApi";
+export type { PublicApiOptions, PublicGetOptions, PublicResponse } from "./publicApi";
+export { createRevalidateRoute } from "./revalidateRoute";
+export type { RevalidateRouteOptions } from "./revalidateRoute";

package/src/server/publicApi.ts

@@ -0,0 +1,104 @@
+export interface PublicResponse<T> {
+  data: T;
+  /** From the `Last-Modified` header, when the endpoint reports one. */
+  lastModified: Date | null;
+}
+
+export interface PublicGetOptions {
+  /** Cache tags, so a revalidate route can purge this fetch by tag. */
+  tags?: string[] | undefined;
+}
+
+export interface PublicApiOptions {
+  /** Seconds a cached response stays fresh. Defaults to 60. */
+  revalidate?: number | undefined;
+}
+
+/** The API could not be reached, or answered with no usable content. */
+export class PublicApiError extends Error {
+  readonly path: string;
+  readonly status: number | null;
+
+  constructor(path: string, status: number | null, options?: { cause?: unknown }) {
+    super(`GET ${path} failed${status == null ? "" : ` with ${status}`}`, options);
+    this.name = "PublicApiError";
+    this.path = path;
+    this.status = status;
+  }
+}
+
+/** Reads `Last-Modified`, ignoring a header that is missing or not a date. */
+function lastModifiedOf(response: Response): Date | null {
+  const header = response.headers.get("last-modified");
+  if (!header) return null;
+  const date = new Date(header);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/**
+ * Cached GETs against the API's anonymous endpoints, for server components and route handlers.
+ *
+ * A 404 gives null. An unreachable or failing API throws `PublicApiError`, so a failed fetch is
+ * never cached as an empty page in place of a working one.
+ */
+export function createPublicApi(baseUrl: string, options: PublicApiOptions = {}) {
+  if (!baseUrl) {
+    throw new Error("createPublicApi needs the API base URL, and baseUrl is empty.");
+  }
+  const revalidate = options.revalidate ?? 60;
+  const base = new URL(baseUrl);
+  const basePath = base.pathname.replace(/\/$/, "");
+
+  // The path is joined onto the base URL. A path that does not start with a single "/" is a bug in
+  // the caller, so it throws. A path with a dot segment, often a slug from the URL, names no resource,
+  // so it gives null, the same as a 404. A slug goes through encodeURIComponent first.
+  function urlFor(path: string): string | null {
+    if (!path.startsWith("/") || path.startsWith("//")) {
+      throw new Error(`Public API path must start with a single "/" under the base URL: ${path}`);
+    }
+    const segments = path.split(/[?#]/, 1)[0]!.replace(/%2e/gi, ".").split("/");
+    if (segments.some((segment) => segment === "." || segment === "..")) return null;
+    const url = new URL(`${baseUrl.replace(/\/$/, "")}${path}`);
+    if (url.origin !== base.origin || !url.pathname.startsWith(`${basePath}/`)) return null;
+    return url.toString();
+  }
+
+  async function publicGetWithMeta<T>(path: string, opts: PublicGetOptions = {}): Promise<PublicResponse<T> | null> {
+    const url = urlFor(path);
+    if (url == null) return null;
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        next: opts.tags ? { revalidate, tags: opts.tags } : { revalidate },
+      });
+    } catch (cause) {
+      throw new PublicApiError(path, null, { cause });
+    }
+
+    if (response.status === 404) return null;
+    if (!response.ok) throw new PublicApiError(path, response.status);
+
+    try {
+      return { data: (await response.json()) as T, lastModified: lastModifiedOf(response) };
+    } catch (cause) {
+      throw new PublicApiError(path, response.status, { cause });
+    }
+  }
+
+  /** The data alone. Null when the resource does not exist. */
+  async function publicGet<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
+    return (await publicGetWithMeta<T>(path, opts))?.data ?? null;
+  }
+
+  /** For data a page can do without. Null on any failure, so the page still renders. */
+  async function publicGetOptional<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
+    try {
+      return await publicGet<T>(path, opts);
+    } catch (error) {
+      if (error instanceof PublicApiError) return null;
+      throw error;
+    }
+  }
+
+  return { publicGet, publicGetOptional, publicGetWithMeta };
+}

package/src/server/revalidateRoute.ts

@@ -0,0 +1,77 @@
+import { revalidatePath, revalidateTag } from "next/cache";
+import { NextResponse, type NextRequest } from "next/server";
+import jwt from "jsonwebtoken";
+import { getToken, type JWT } from "next-auth/jwt";
+import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, isTerminalSessionError } from "../session/expiry";
+
+export interface RevalidateRouteOptions {
+  /**
+   * Each target the client may send, with the page paths it purges. A path with a dynamic segment,
+   * such as `/builds/[slug]`, purges every page of that route. The target name is also purged as a
+   * cache tag, so tag fetches with it.
+   */
+  targets: Record<string, readonly string[]>;
+  /** The role allowed to purge, as it appears in the session user's roles. */
+  role: string;
+}
+
+type Token = JWT | null;
+
+const rolesOf = (token: Token): string[] => (token?.user as { roles?: string[] } | undefined)?.roles ?? [];
+
+// getToken only decrypts the cookie, without the jwt callback. So the checks that callback makes are
+// made here: a refused refresh still carries its roles, and the cookie outlives the seven days. The
+// roles must also come from an access token that has not expired, so a copied cookie of a user who
+// lost the role stops working within the token's lifetime.
+function isLive(token: Token): boolean {
+  if (!token || isTerminalSessionError(token.error as string | undefined)) return false;
+  const loginAt = token.loginAt;
+  if (typeof loginAt !== "number" || Date.now() - loginAt > ABSOLUTE_SESSION_MAX_AGE) return false;
+  return accessTokenValid(token.accessToken);
+}
+
+// The cookie is encrypted and authenticated with NEXTAUTH_SECRET, so the access token in it is the
+// one the API issued, and its expiry can be read without verifying the signature again.
+function accessTokenValid(accessToken: unknown): boolean {
+  if (typeof accessToken !== "string") return false;
+  const claims = jwt.decode(accessToken);
+  const exp = claims && typeof claims === "object" ? claims.exp : undefined;
+  return typeof exp === "number" && exp * 1000 + CLOCK_TOLERANCE_S * 1000 > Date.now();
+}
+
+/**
+ * A `POST` route handler that purges cached pages after an edit, for `app/api/revalidate/route.ts`.
+ * It answers 403 unless the caller has a live session with `role`, 415 unless the body is JSON, and
+ * 400 for a target it does not know.
+ */
+export function createRevalidateRoute({ targets, role }: RevalidateRouteOptions) {
+  return async function POST(req: NextRequest): Promise<NextResponse> {
+    // getToken reads NEXTAUTH_SECRET itself, the same way next-auth does. It is asked for both cookie
+    // names, because behind a TLS proxy next-auth can sign in with the secure cookie while getToken
+    // would look for the plain one.
+    const token = (await getToken({ req, secureCookie: true })) ?? (await getToken({ req, secureCookie: false }));
+    if (!isLive(token) || !rolesOf(token).includes(role)) {
+      return NextResponse.json({ message: "Forbidden" }, { status: 403 });
+    }
+
+    // JSON only, so a plain form on a sibling subdomain cannot post here with the session cookie.
+    if (!req.headers.get("content-type")?.toLowerCase().startsWith("application/json")) {
+      return NextResponse.json({ message: "Expected JSON" }, { status: 415 });
+    }
+
+    const body: unknown = await req.json().catch(() => null);
+    const target = (body as { target?: unknown } | null)?.target;
+    if (typeof target !== "string" || !Object.hasOwn(targets, target)) {
+      return NextResponse.json({ message: "Unknown target" }, { status: 400 });
+    }
+
+    for (const path of targets[target] ?? []) {
+      if (path.includes("[")) revalidatePath(path, "page");
+      else revalidatePath(path);
+    }
+    // By tag as well, because a path purge misses fetches that another route rendered. expire 0
+    // makes them stale at once.
+    revalidateTag(target, { expire: 0 });
+    return NextResponse.json({ revalidated: true, target });
+  };
+}

package/src/session/expiry.ts

@@ -1,3 +1,9 @@
+/** How long a session lasts after sign-in, however often it is refreshed. Seven days. */
+export const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+
+/** How far this server's clock may differ from the API's when a token's times are checked. */
+export const CLOCK_TOLERANCE_S = 60;
+
 /**
  * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
  * transient refresh failure, such as a network error or an API restart, sets no error, so the

package/src/session/react/AppSessionProvider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { SessionProvider } from "next-auth/react";
+import type { ReactNode } from "react";
+
+/** Four minutes, shorter than the five minutes before expiry when a refresh falls due. */
+const SESSION_POLL_SECONDS = 4 * 60;
+
+export interface AppSessionProviderProps {
+  /** Seconds between session reads. Defaults to four minutes. */
+  refetchInterval?: number | undefined;
+  children: ReactNode;
+}
+
+/**
+ * next-auth's `SessionProvider`, reading the session again on a timer. Each read lets the jwt
+ * callback renew the access token ahead of expiry, so an open tab stays usable and does not find a
+ * dead session on the next save. It also keeps what `useSession` reports in this tab up to date.
+ * next-auth polls only once a session exists, so signed-out visitors cost nothing.
+ */
+export function AppSessionProvider({ refetchInterval = SESSION_POLL_SECONDS, children }: AppSessionProviderProps) {
+  return <SessionProvider refetchInterval={refetchInterval}>{children}</SessionProvider>;
+}

package/src/session/react/RoleGate.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { usePathname, useRouter } from "next/navigation";
+import { useEffect, useState, type ReactNode } from "react";
+import { useSessionGate } from "./useSessionGate";
+
+interface RoleGateBase {
+  /** The role the page needs, as it appears in `session.user.roles`. */
+  role: string;
+  /** What shows while the session or its roles are not known yet. */
+  fallback?: ReactNode | undefined;
+  children: ReactNode;
+}
+
+/** Shows `denied` to a signed-in user without the role. */
+interface RoleGateWithDenied extends RoleGateBase {
+  denied: ReactNode;
+  deniedHref?: never;
+}
+
+/** Sends a signed-in user without the role to `deniedHref`. */
+interface RoleGateWithDeniedHref extends RoleGateBase {
+  deniedHref: string;
+  denied?: never;
+}
+
+export type RoleGateProps = RoleGateWithDenied | RoleGateWithDeniedHref;
+
+/**
+ * Renders its children only for a user with `role`. Place it inside `ProtectedGate`, which decides
+ * whether the session may render at all.
+ *
+ * While the re-sign-in prompt recovers a signed-out session there is no user, so the roles are
+ * unknown. The page stays up only on the path where the session last had the role.
+ */
+export function RoleGate(props: RoleGateProps) {
+  const { role, fallback = null, children } = props;
+  const { session, recovering, mayRender } = useSessionGate();
+  const pathname = usePathname();
+  const router = useRouter();
+
+  const roles = (session?.user as { roles?: string[] } | undefined)?.roles ?? [];
+  const hasRole = roles.includes(role);
+  const rolesKnown = session?.user != null;
+
+  // The path where the session last had the role. A user without it clears the pass. Set during
+  // render, the same way useSessionGate tracks the path it last passed. It starts as undefined, not
+  // null, because usePathname can return null.
+  const [roleAt, setRoleAt] = useState<string | null | undefined>(undefined);
+  if (hasRole && roleAt !== pathname) setRoleAt(pathname);
+  if (rolesKnown && !hasRole && roleAt !== undefined) setRoleAt(undefined);
+  const keepThroughRecovery = recovering && roleAt === pathname;
+
+  const allowed = hasRole || keepThroughRecovery;
+  const denied = mayRender && rolesKnown && !allowed;
+  const deniedHref = "deniedHref" in props ? props.deniedHref : undefined;
+
+  useEffect(() => {
+    // replace, so Back does not return to a page that only redirects again.
+    if (denied && deniedHref != null) router.replace(deniedHref);
+  }, [denied, deniedHref, router]);
+
+  if (mayRender && allowed) return children;
+  if (denied && "denied" in props) return props.denied;
+  return fallback;
+}

package/src/session/react/index.ts

@@ -6,3 +6,7 @@ export { defaultSessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
 export type { SessionExpiryGuardStrings } from "./sessionExpiryGuardStrings";
 export { useSessionGate } from "./useSessionGate";
 export type { SessionGate } from "./useSessionGate";
+export { AppSessionProvider } from "./AppSessionProvider";
+export type { AppSessionProviderProps } from "./AppSessionProvider";
+export { RoleGate } from "./RoleGate";
+export type { RoleGateProps } from "./RoleGate";

package/src/toast/index.ts

@@ -0,0 +1,11 @@
+import { toast as sonnerToast } from "sonner";
+import { getSessionPromptOpen } from "../session/expiry";
+
+// While the re-sign-in prompt is open it already tells the user why a request failed, so error
+// toasts stay quiet. Every other toast passes through.
+const error: typeof sonnerToast.error = (...args) => (getSessionPromptOpen() ? "" : sonnerToast.error(...args));
+
+/** sonner's `toast`, except that error toasts stay quiet while the re-sign-in prompt is open. */
+export const toast: typeof sonnerToast = new Proxy(sonnerToast, {
+  get: (target, property, receiver) => (property === "error" ? error : Reflect.get(target, property, receiver)),
+});