@sjolystinnovation/app-kit 0.4.0 → 0.6.0

package/README.md

@@ -5,9 +5,13 @@
 
 > Building blocks for Next.js apps that sign in against a JWT API through next-auth
 
-Several apps sharing one API also share the code around it: the session plumbing, how a failed
-request becomes a message a user can read, and the form controls on the sign in page. This package
-holds that code once, so the apps install it instead of each keeping a copy.
+Several apps sharing one API also share the code around it:
+
+- the session plumbing
+- how a failed request becomes a message a user can read
+- the form controls on the sign in page
+
+This package holds that code once, and each app installs it.
 
 ## Install
 
@@ -24,8 +28,8 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui` are styled with Tailwind CSS. Import the
-package's stylesheet after Tailwind:
+The components in `@sjolystinnovation/app-kit/ui` and `session/react` are styled with Tailwind CSS.
+Import the package's stylesheet after Tailwind:
 
 ```css
 /* src/app/globals.css */
@@ -70,15 +74,23 @@ const secret = resolveJwtSecret(sessionConfig, process.env);
 
 `(config: SessionConfig) => SessionConfig`
 
-Returns the config unchanged, so TypeScript checks its shape where it is declared rather than at
-every call site. Throws when `draftStoragePrefix` is empty or contains a colon.
+Returns the config unchanged, so TypeScript checks its shape once, where it is declared. Throws
+when `draftStoragePrefix` is empty or contains a colon.
+
+### `requireEnv(name, value)`
+
+`(name: string, value: string | undefined) => string`
+
+Returns `value`, or throws `Missing <name>.` when it is unset or empty. Pass the value read in
+place, such as `process.env.NEXT_PUBLIC_API_URL`, so Next.js can inline a public variable at build
+time.
 
 ### `resolveJwtSecret(config, env)`
 
 `(config: SessionConfig, env: Record<string, string | undefined>) => string`
 
-Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty, so a
-missing secret fails at startup instead of at the first token verification.
+Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty,
+with the variable's name in the message.
 
 ```ts
 resolveJwtSecret(sessionConfig, { API_JWT_SECRET: "s3cret" });
@@ -88,8 +100,8 @@ resolveJwtSecret(sessionConfig, {});
 // Error: Missing API_JWT_SECRET. The app verifies API session tokens with it.
 ```
 
-The environment is a parameter rather than a read of `process.env`, which keeps Node types out of a
-package that also runs in the browser.
+The environment is a parameter, so the root entry point needs no Node types and works in browser
+code. `@sjolystinnovation/app-kit/auth` is server only and does load Node types.
 
 ### `formatApiError(error, fallback, statusMessages?)`
 
@@ -110,11 +122,16 @@ body can come from a proxy, such as "Bad Gateway", so the caller's own words win
 A problem details `title` is never shown. ASP.NET Core fills it with generic text, such as "Bad
 Request" or "An error occurred while processing your request.", which says less than `fallback`.
 
-Key `0` in `statusMessages` covers a request that got no response, because of a dropped connection
-or a timeout. Only text on a single line counts as a message. Axios's own message, such as "Request
-failed with status code 500", is never shown, and a cancelled request gives `fallback`. Any other
-`Error` gives its own message. A body requested as an `arraybuffer` or a `blob`, as for a file
-download, is not read, so a failed download gets `statusMessages` or `fallback`.
+A few more rules:
+
+- Key `0` in `statusMessages` covers a request that got no response, because of a dropped
+  connection or a timeout.
+- Only text on a single line 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 its own message.
+- A body requested as an `arraybuffer` or a `blob`, as for a file download, is not read. A failed
+  download gets `statusMessages` or `fallback`.
 
 ```ts
 try {
@@ -124,44 +141,185 @@ try {
 }
 ```
 
+### `createAuthOptions(config, settings)`
+
+From `@sjolystinnovation/app-kit/auth`. Server only. Builds the next-auth options for an app that
+signs in against the API with email and password:
+
+```ts
+// src/lib/authOptions.ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createAuthOptions } from "@sjolystinnovation/app-kit/auth";
+import { sessionConfig } from "@/lib/session";
+
+export const authOptions = createAuthOptions(sessionConfig, {
+  apiUrl: requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+  env: process.env,
+});
+```
+
+```ts
+// src/app/api/auth/[...nextauth]/route.ts
+import NextAuth from "next-auth/next";
+import { authOptions } from "@/lib/authOptions";
+
+const handler = NextAuth(authOptions);
+
+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. |
+| `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. |
+
+next-auth reads `NEXTAUTH_SECRET` itself and refuses to run in production without it.
+
+What the options do:
+
+- **Sign-in** posts `{ email, password }` and expects `{ token, refreshToken }`. The access token is
+  verified with the API JWT secret, allowing 60 seconds of clock difference between the server and
+  the API. Its `sub`, `unique_name` and `role` claims become the user's `id`, `name` and `roles`.
+  The log gets the status, error code and message, never the request. A failed sign-in reports one
+  of these in next-auth's `error`:
+  - `SIGN_IN_ERRORS.unavailable` when the API does not answer, or a gateway returns 502, 503 or 504.
+  - `SIGN_IN_ERRORS.invalidCredentials` for every other failure, including an unreadable token and
+    an answer without both tokens.
+- **Refresh** runs ahead of expiry: five minutes before it, or a quarter of the token's lifetime
+  before it when that is shorter. It is never scheduled sooner than 30 seconds out, so a token that
+  lives under 30 seconds is refreshed after it expires. Parallel reads of one session in one server
+  process share a single refresh. Its answer is kept for a minute, because the API rotates the
+  refresh token on every call.
+- **Failures:** a 400 or 401 from the refresh ends the session with `RefreshTokenRejected`. Any
+  other failure keeps it and tries again a minute later. A session without a refresh token ends with
+  `NoRefreshToken` when its refresh falls due.
+- **Cap:** the session ends seven days after sign-in with `AbsoluteSessionExpired`, however recently
+  it was refreshed.
+- **Session:** it carries `user`, `accessToken`, `error`, and `absoluteExpiresAt`, the end of the
+  seven days in milliseconds.
+- **Sign-in page:** `pages.signIn` is `config.loginRoute`.
+
+Two rules keep a refresh from being lost:
+
+- Read the session on the client, through `useSession` or `getSession`. In the App Router,
+  `getServerSession(authOptions)` cannot store a cookie, in server components, route handlers and
+  server actions alike. A refresh there replaces the tokens at the API and loses the new ones. The
+  next refresh then reuses the old token, and the API revokes every session the user has. On the
+  server, read the token with `getToken` from `next-auth/jwt`, which never refreshes.
+- Run the app as one server process. Parallel session reads share one refresh only within a process.
+  Two replicas can refresh the same token at once, with the same result.
+
+The package does not declare these fields on next-auth's types. The app declares them, so its own
+code can read them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    user: { id: string; name: string; email: string; roles: string[] };
+    accessToken: string;
+    error?: string | undefined;
+    absoluteExpiresAt?: number;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    accessToken?: string;
+    refreshToken?: string;
+    refreshAt?: number;
+    loginAt?: number;
+    user?: { id: string; name: string; email: string; roles: string[] };
+    error?: string | undefined;
+  }
+}
+```
+
+### `@sjolystinnovation/app-kit/api`
+
+`createApiClient(baseURL)` returns an axios instance for the signed-in API, for code that runs in
+the browser. It reads the session through next-auth's `getSession`, which has no cookies to read on
+the server. An empty `baseURL` throws. Each request carries the session's access token. A 401
+opens the re-sign-in prompt when the session is gone or has a terminal error. It does not sign
+the user out, so the page keeps its state. The error still rejects as usual.
+
+`request(call, fallback, statusMessages?)` runs a call and returns its `data`. A failure becomes an
+`Error` with the message `formatApiError` gives it. A cancelled call rethrows the cancel unchanged:
+
+```ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createApiClient, request } from "@sjolystinnovation/app-kit/api";
+
+const api = createApiClient(requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL));
+
+export const getRecipe = (id: number) =>
+  request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
+```
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
 callbacks.
 
-The gate reads `session.error`. The app's `jwt` callback sets `token.error`, and its `session`
-callback copies it across:
+The gate reads `session.error`. `SessionExpiryGuard` also reads `session.absoluteExpiresAt` for its
+countdown, `session.user.id` to keep the page with the user who opened it, and `session.user.email`
+to fill in the prompt. `createAuthOptions` sets all of these. An app with its own next-auth options sets them in its
+callbacks:
 
 ```ts
+const SESSION_LIFETIME_MS = 7 * 24 * 60 * 60 * 1000;
+
 callbacks: {
+  jwt({ token, user }) {
+    if (user) token.loginAt = Date.now();
+    // A token without a sign-in time counts as expired.
+    if (!token.loginAt || Date.now() - token.loginAt > SESSION_LIFETIME_MS) {
+      token.error = SESSION_ERRORS.absoluteExpiry;
+    }
+    // Also set token.error when a refresh is refused.
+    return token;
+  },
   session({ session, token }) {
+    session.user.id = token.sub ?? "";
     session.error = token.error;
+    session.absoluteExpiresAt = token.loginAt ? token.loginAt + SESSION_LIFETIME_MS : undefined;
     return session;
   },
 },
 ```
 
-For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+For that to compile, these fields have to be on next-auth's `Session` and `JWT` types. Add them to
 the app's existing next-auth type declarations, or create them:
 
 ```ts
 // src/types/next-auth.d.ts
 import "next-auth";
 import "next-auth/jwt";
+import type { DefaultSession } from "next-auth";
 
 declare module "next-auth" {
   interface Session {
+    user: { id: string } & DefaultSession["user"];
     error?: string | undefined;
+    absoluteExpiresAt?: number | undefined;
   }
 }
 
 declare module "next-auth/jwt" {
   interface JWT {
     error?: string | undefined;
+    loginAt?: number | undefined;
   }
 }
 ```
 
+`SIGN_IN_ERRORS` holds the two codes a failed sign-in reports: `InvalidCredentials` and
+`SignInUnavailable`. Map them to the app's own messages.
+
 `SESSION_ERRORS` holds the values the jwt callback puts in `token.error` when the session cannot be
 recovered: `AbsoluteSessionExpired`, `RefreshTokenRejected` and `NoRefreshToken`. `SessionError`
 is their union type. `isTerminalSessionError(error)` is true for those three only, so a transient
@@ -178,51 +336,26 @@ The re-sign-in prompt is a flag outside React, so an axios interceptor can raise
 
 Copies of the package installed side by side share the one flag, as long as their releases use the
 same prompt state format. A release that changes the format says so in its changelog. An app's own
-copy of these functions does not, so an app moving to them moves every import at once: the
-interceptor, the prompt and every gate.
+copy of these functions does not share the flag. So the interceptor, the prompt and every gate all
+import them from this package.
 
 ### `useSessionGate()`
 
 From `@sjolystinnovation/app-kit/session/react`. Tells a protected page whether it may render. It
 reads `useSession`, so it needs a `SessionProvider` above it.
 
-A page that rendered on a healthy session stays rendered when the session gets a terminal error,
-while the session is re-read and while the prompt recovers it, so an open form keeps its values. A
-session that turns signed out with no prompt open blanks the page. A page the user opens
-on a dead session does not render. Use `mayRender` in every gate and layout on the way down, so
-none of them blanks a page that another one kept.
+A page that rendered on a healthy session stays rendered, so an open form keeps its values:
 
-The hook does not navigate. The gate sends the user to the login page itself, and never while the
-prompt is open. The app passes the login URL in, so an app with a locale in the path can build it
-for the current locale:
+- when the session gets a terminal error
+- while the session is re-read
+- while the prompt recovers it
 
-```tsx
-"use client";
-
-import { useSessionGate } from "@sjolystinnovation/app-kit/session/react";
-import { useRouter } from "next/navigation";
-import { useEffect } from "react";
-
-export function ProtectedGate({
-  loginHref,
-  children,
-}: {
-  loginHref: string;
-  children: React.ReactNode;
-}) {
-  const router = useRouter();
-  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
-
-  useEffect(() => {
-    if (promptOpen) return;
-    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
-      router.push(loginHref);
-    }
-  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+A session that turns signed out with no prompt open blanks the page. A page the user opens on a
+dead session does not render. Use `mayRender` in every gate and layout on the way down, so none of
+them blanks a page that another one kept.
 
-  return mayRender ? children : <p>Loading…</p>;
-}
-```
+The hook does not navigate. `ProtectedGate` below adds the redirect. Use the hook directly in a
+layout that needs its own decision, such as a role check, so it agrees with the gate.
 
 | Field | Description |
 | --- | --- |
@@ -235,6 +368,50 @@ export function ProtectedGate({
 
 `SessionGate` is the type of the result.
 
+### `ProtectedGate`
+
+From `@sjolystinnovation/app-kit/session/react`. Wraps the protected part of the app. It renders the
+page only when `useSessionGate` allows it, and sends a signed-out visitor or a session dead on
+arrival to `loginHref`. It never redirects while the re-sign-in prompt is open.
+
+```tsx
+<ProtectedGate loginHref="/login" fallback={<p>Loading…</p>}>
+  {children}
+</ProtectedGate>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `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. |
+
+### `SessionExpiryGuard`
+
+From `@sjolystinnovation/app-kit/session/react`. Render it once, inside the `SessionProvider`. It
+shows:
+
+- a banner in the last 30 minutes before `session.absoluteExpiresAt`, with the minutes left. That is
+  seven days after sign-in with `createAuthOptions`.
+- a banner when the session is dead
+- the re-sign-in prompt, a dialog with `CredentialsForm`, when a request or the banner opens it
+
+A sign-in in the prompt keeps the page and its form. A sign-in in the prompt as a different user is
+signed out and sent to `loginHref`, so the prompt never hands the page to another user.
+
+```tsx
+<SessionExpiryGuard
+  loginHref="/login"
+  onRestored={() => toast.success("You are signed in again.")}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `loginHref` | `string` | Where a sign-in as a different user is sent after it is signed out. |
+| `onRestored` | `() => void` | Runs after the prompt signs the user back in, such as to show a toast. |
+| `strings` | `TextOverrides<SessionExpiryGuardStrings>` | The guard's text. `{minutes}` in `expiringSoon` becomes the minutes left. The defaults are English. |
+| `formStrings` | `TextOverrides<CredentialsFormStrings>` | The text of the form in the prompt. |
+
 ### `useFormDraft(config, options)`
 
 From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
@@ -260,15 +437,52 @@ Mount an edit form once the entity has loaded, with its values already in `value
 the values it first sees under a key as the untouched form, so values that arrive later count as an
 edit and are written over the draft being offered.
 
-It returns `pending`, the stored draft, which the page offers instead of applying. It is read when the
-owner is first known and again whenever the owner or `scope` changes, so it can appear after the form mounts. It
-also returns `dismiss()` to stop offering it, and `clear()` to drop the stored draft after a
-successful save.
+It returns:
+
+- `pending`, the stored draft. The page offers it to the user and does not apply it. It is read
+  when the owner is first known and again whenever the owner or `scope` changes, so it can appear
+  after the form mounts.
+- `dismiss()`, to stop offering it.
+- `clear()`, to drop the stored draft after a successful save.
 
 Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook throws when
 `draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
 removed when its form next reads it.
 
+### `CredentialsForm`
+
+From `@sjolystinnovation/app-kit/ui`. Email and password sign-in through next-auth's credentials
+provider, with `redirect: false`, so the page stays where it is. Use it on the login page and in
+the prompt.
+
+```tsx
+<CredentialsForm onSignedIn={() => router.push("/")} strings={{ signIn: "Logg inn" }} />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `onSignedIn` | `() => void \| Promise<void>` | Runs after next-auth accepts the credentials. Throw `SignInRejected` with a message to refuse the sign-in. |
+| `initialEmail` | `string` | The email the field starts with. |
+| `children` | `ReactNode` | Extra buttons next to the submit button. |
+| `strings` | `TextOverrides<CredentialsFormStrings>` | The form's text. The defaults are English. |
+| `onPendingChange` | `(pending: boolean) => void` | Runs when a sign-in starts and ends, such as to keep a dialog open until it finishes. |
+
+A failed sign-in shows `signInUnavailable` for `SIGN_IN_ERRORS.unavailable` and
+`invalidCredentials` for any other error code. A request next-auth refuses without an error code,
+or one that throws, shows `somethingWentWrong`.
+
+`TextOverrides<T>`, from `@sjolystinnovation/app-kit/ui`, is the type of every `strings` prop. Each
+key is optional and may be `undefined`, and a missing or undefined key shows the English default.
+
+### `TextInput`
+
+From `@sjolystinnovation/app-kit/ui`. A labelled text field with the same look and props as
+`PasswordInput`, apart from the show and hide toggle. It takes the other `<input>` attributes too.
+
+```tsx
+<TextInput label="Email" name="email" type="email" required error={errors.email} />
+```
+
 ### `Alert`
 
 ```tsx
@@ -280,8 +494,8 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `variant` | `"error" \| "success" \| "info" \| "warning"` | `"info"` | Colour of the box. |
-| `role` | `"alert" \| "status"` | `"alert"` | Use `status` for text that keeps changing, such as a countdown, so a screen reader does not announce every change. |
-| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables instead, since whether a clashing class wins depends on the order Tailwind emits them in. |
+| `role` | `"alert" \| "status" \| "none"` | `"alert"` | A screen reader announces `status` without interrupting, on every change of its text. Use `none` when a separate live region announces the text. |
+| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables. A clashing class wins or loses by the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
 ### `PasswordInput`
@@ -302,7 +516,7 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 | `error` | `string` | | Message shown under the field. It turns the border red, marks the input invalid and is read out with it by screen readers. |
 | `showPasswordLabel` | `string` | `"Show password"` | Accessible name of the toggle while the value is hidden. |
 | `hidePasswordLabel` | `string` | `"Hide password"` | Accessible name of the toggle while the value is visible. |
-| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables instead. |
+| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables. |
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
@@ -349,25 +563,40 @@ selector such as `.dark` for a scoped theme:
 | `--input-focus-ring-width` | `2px` |
 | `--color-input-toggle` | gray 400, the show password icon |
 | `--color-input-toggle-hover` | gray 600 |
-
-A default that points at another variable, such as `--color-input-focus-ring` at `--color-primary`,
-is read once for the whole page. A scoped theme that changes `--color-primary` should set
-`--color-input-focus-ring` in the same selector.
+| `--radius-button` | `var(--radius-lg)` |
+| `--color-button-primary-bg` | `var(--color-primary)` |
+| `--color-button-primary-text` | `var(--color-primary-foreground)` |
+| `--color-button-secondary-border` | gray 300 |
+| `--color-button-secondary-text` | gray 700 |
+| `--color-button-secondary-hover-bg` | gray 50 |
+| `--radius-dialog` | `var(--radius-xl)` |
+| `--color-dialog-backdrop` | black at 40% |
+| `--color-dialog-bg` | white |
+| `--color-dialog-title` | gray 900 |
+| `--color-dialog-text` | gray 600 |
+
+A default that points at another variable is read once for the whole page. The focus ring and the
+primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that
+changes those also sets `--color-input-focus-ring`, `--color-button-primary-bg` and
+`--color-button-primary-text` in the same selector.
 
 An app that clears a whole Tailwind namespace, such as `--color-*: initial`, clears these variables
 with it and has to set the ones it uses itself.
 
 ## Requirements
 
-- Next.js 16, React 19, next-auth 4 and axios 1, as peer dependencies the app installs itself.
-- For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring uses
-  the theme's `primary` colour unless `--color-input-focus-ring` is set.
+- Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
+  app installs itself.
+- `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
+  `primary-foreground` colours, unless their own variables are set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 
-There is no build output. Shipping source is what keeps the `"use client"` directives intact, since
-bundlers strip or relocate them. The consumer therefore compiles this source with its own
-`compilerOptions`, and `skipLibCheck` does not exempt it.
+There is no build output. Bundlers strip or relocate `"use client"` directives, and shipping source
+keeps them intact. The consumer compiles this source with its own `compilerOptions`, and
+`skipLibCheck` does not exempt it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -19,6 +19,8 @@
     "./session": "./src/session/index.ts",
     "./session/react": "./src/session/react/index.ts",
     "./forms": "./src/forms/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./api": "./src/api/index.ts",
     "./ui": "./src/ui/index.ts",
     "./styles.css": "./src/styles.css"
   },
@@ -35,7 +37,7 @@
   },
   "peerDependencies": {
     "@heroicons/react": "^2",
-    "axios": "^1",
+    "axios": "^1.20.0",
     "next": "^16",
     "next-auth": "^4.24",
     "react": "^19",
@@ -49,7 +51,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^6.1.2",
-    "axios": "^1.19.0",
+    "axios": "^1.20.0",
     "jsdom": "^30.1.1",
     "next": "^16.3.6",
     "next-auth": "^4.24.15",
@@ -65,5 +67,9 @@
     "jwt",
     "react",
     "tailwindcss"
-  ]
+  ],
+  "dependencies": {
+    "@types/jsonwebtoken": "^9.0.8",
+    "jsonwebtoken": "^9.0.2"
+  }
 }

package/src/api/createApiClient.ts

@@ -0,0 +1,43 @@
+import axios, { type AxiosInstance } from "axios";
+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.
+ */
+export function createApiClient(baseURL: string): AxiosInstance {
+  if (!baseURL) {
+    throw new Error("createApiClient needs the API base URL, and baseURL is empty.");
+  }
+  // allowAbsoluteUrls: false joins every URL onto baseURL, so the token only goes to the API.
+  const client = axios.create({ baseURL, allowAbsoluteUrls: false });
+
+  // broadcast: false, so a request does not make every other open tab refetch its session.
+  client.interceptors.request.use(async (request) => {
+    const session = await getSession({ broadcast: false });
+    const accessToken = (session as { accessToken?: string } | null)?.accessToken;
+    if (accessToken) {
+      request.headers.Authorization = `Bearer ${accessToken}`;
+    }
+    return request;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (axios.isAxiosError(error) && error.response?.status === 401) {
+        const session = await getSession({ broadcast: false });
+        // No session also opens the prompt. The cookie is gone, or the session fetch failed. Either
+        // way there is no error field to read, and signing in again recovers both.
+        const sessionError = (session as { error?: string } | null)?.error;
+        if (!session || isTerminalSessionError(sessionError)) {
+          openSessionPrompt();
+        }
+      }
+      return Promise.reject(error);
+    },
+  );
+
+  return client;
+}

package/src/api/index.ts

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

package/src/api/request.ts

@@ -0,0 +1,22 @@
+import axios from "axios";
+import { formatApiError, type StatusMessages } from "../errors";
+
+/**
+ * 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.
+ */
+export async function request<T>(
+  call: () => Promise<{ data: T }>,
+  fallback: string,
+  statusMessages?: StatusMessages,
+): Promise<T> {
+  try {
+    const response = await call();
+    return response.data;
+  } 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));
+  }
+}