@nano-app/frontend 0.5.0 → 0.6.1

package/README.md

@@ -1,6 +1,11 @@
 # @nano-app/frontend
 
-Frontend of [nano-app](https://github.com/Nano-Nathan/nano-app) for Next.js apps: UI state in stores, and controllers whose methods the views use. Work in progress.
+[![frontend](https://img.shields.io/npm/v/@nano-app/frontend?label=frontend)](https://www.npmjs.com/package/@nano-app/frontend)
+
+Frontend of [nano-app](https://github.com/Nano-Nathan/nano-app) for Next.js apps: UI state in stores, and controllers whose methods the views use.
+
+- Node.js 22.23.4, 24.22.1 or 26.12.1 and newer. ESM only.
+- Next.js 16.3 and React 19 or newer, as peer dependencies.
 
 ## Quick start
 
@@ -78,6 +83,8 @@ export default counterController.extend(({ stores: { app } }) => ({
 }));
 ```
 
+The types of a controller and its views come from `@nano-app/frontend`: `Controller`, `View`, `ComponentContext` (`props` and `stores`) and `ComponentProps`.
+
 ## Backend
 
 A store of type `api` connects the app to a backend. The browser never talks to the backend: it calls `/api/<store>/...` on the Next server, and the proxy sends the request there.
@@ -99,48 +106,61 @@ The backend URL is read at runtime from `API_<STORE>_URL` (`backend` → `API_BA
 
 ### Reading and writing
 
-An `api` store reads and writes its backend, and keeps what it read. It also has its own state like any store (`get`, `set`, and `data` in its file), apart from what it read: UI state about that backend (a page, an order) can live next to it.
+An `api` store reads and writes its backend. The controllers read and write; the views get what a read kept. It also has its own state like any store (`get`, `set`, and `data` in its file): UI state about that backend (a page, an order) can live next to it.
 
 ```ts
 // src/controllers/users.controller.ts
 export default createController(({ stores: { backend } }) => ({
-  add: (sName: string) => backend.create('/users', { name: sName }),
-  rename: (iId: number, sName: string) => backend.update(`/users/${iId}`, { name: sName }),
-  remove: (iId: number) => backend.delete(`/users/${iId}`),
+  load: () => backend.read('/users'),
+  add: async (sName: string) => {
+    await backend.create('/users', { name: sName });
+    return backend.read('/users');
+  },
 }));
 ```
 
 ```tsx
 // src/components/Users.tsx
-export default usersController.bindView(({ stores: { backend }, rename }) => (
-  <ul>
-    {(backend.read('/users') ?? []).map(oUser => (
-      <li key={oUser.id} onClick={() => rename(oUser.id, 'Bruno')}>{oUser.name}</li>
-    ))}
-  </ul>
-));
+export default usersController.bindView(({ stores: { backend }, load, add }) => {
+  useEffect(() => {
+    load();
+  }, []);
+
+  return (
+    <ul onClick={() => add('Bruno')}>
+      {(backend.get('/users')?.result ?? []).map(oUser => (
+        <li key={oUser.id}>{oUser.name}</li>
+      ))}
+    </ul>
+  );
+});
 ```
 
-- `read(path, query?)` returns the `result` it keeps for that path and query, `undefined` until it arrives. It works in the render: the first read, or a read after its entity changed, asks the backend (`GET`, or `QUERY` with the query as JSON body), and the view renders again when the answer comes. Each path and query is asked once per change of its entity.
-- The entity is the first segment of the path (`/users/7` → `/users`). `create` (`POST <path>`), `update` (`PUT <path>`) and `delete` (`DELETE <path>`) return the `ApiResponse`, and when it comes back every read of the entity asks again the next time it renders, whatever its query. Other entities keep what they have.
-- On the server (the first HTML that Next renders) `read` asks nothing and returns `undefined`: the browser asks when it hydrates.
-- `busy` counts the requests in progress (`backend.busy ? 'Loading…' : …`).
-- A read keeps the `result` of its answer, `undefined` when it failed, and is not asked again until a write on its entity. A request that fails (no answer, or not JSON) rejects: the errors module will show it.
-- What another user changes is seen after a write on the same entity.
-- Every path and query read stays kept while the page is open.
+- `read(path, query?)` returns a promise of the `ApiResponse` and keeps it in the store for that path and query, over what the store had there (a field the new answer does not bring stays from the last one). The view gets it with `get(path, query?)`, and renders again when a read keeps a new one.
+- Each path has a version that its writes raise. A read answers from the store while it was kept at the current version of its path; otherwise it asks the backend (`GET`, or `QUERY` with the query as JSON body). An answer that comes back after a write on its path is returned but not kept.
+- `create` (`POST <path>`), `update` (`PUT <path>`) and `delete` (`DELETE <path>`) return a promise of the `ApiResponse` and raise the version of their path and its parents (`update('/users/7')` raises `/users/7` and `/users`), so their next reads ask the backend, whatever their query. Other paths keep what they have.
+- A successful `update` also keeps its `ApiResponse` at its path, over what the store had there, with the new version of the path: its next read answers from the store. `create` and `delete` keep nothing.
+- A read or a write always resolves with an `ApiResponse`. When the backend fails it is the backend's (`success: false`, `message`); an answer that is not JSON becomes `{ success: false, message: 'Request failed', result: <the text> }`, and no answer `{ success: false, message: 'Request failed' }`.
+- Each failed request adds its `ApiResponse` to the store's `/error/list` as an `ApiError`, with `message` set to `'Request failed'` when the backend brings none and `timestamp` (`Date.now()`) of when it failed. The views get it with `get('/error/list')`, or through the `error` component of `@nano-app/components`.
+- On the server (the first HTML that Next renders) `read` asks nothing and resolves with an empty `ApiResponse` (`{}`).
+- `/busy` is `true` while a request of the store is out (`backend.get('/busy') ? 'Loading…' : …`).
+- What another user changes is seen after a write on the same path.
 
-To ask only when the user stops typing, keep the text in the `app` store and copy it to the query after a pause:
+To ask only when the user stops typing, keep the text in the `app` store and read after a pause:
 
 ```ts
 let oTimer: ReturnType<typeof setTimeout>;
-export default createController(({ stores: { app } }) => ({
+export default createController(({ stores: { app, backend } }) => ({
   type: (sText: string) => {
     app.set('/search/text', sText);
     clearTimeout(oTimer);
-    oTimer = setTimeout(() => app.set('/search/applied', sText), 300);
+    oTimer = setTimeout(() => {
+      app.set('/search/applied', sText);
+      backend.read('/users', { filter: { name: { contains: sText } } });
+    }, 300);
   },
 }));
-// The view reads backend.read('/users', { filter: { name: { contains: app.get('/search/applied') } } })
+// The view gets backend.get('/users', { filter: { name: { contains: app.get('/search/applied') } } })
 ```
 
 ### Headers per backend
@@ -155,9 +175,63 @@ export default { type: 'api', headers: { 'x-api-key': 'STRIPE_KEY' } };
 The proxy sends `x-api-key` with the value of `API_STRIPE_KEY_HEADER` (the name in upper case) on every request to that store; a missing variable answers 500 with its name.
 
 - A store header wins over a browser header with the same name: the browser cannot replace or guess the key.
+- The proxy adds the key to every request to that store, from any visitor, with or without a session: anyone who reaches the app can call any path and method of that backend with it. Declare a key only for a backend whose every endpoint may be called by your visitors, and keep the rest protected there.
+- The proxy sends every header of the browser to the backend, cookies included: point a store only at a backend you trust with your users' cookies.
 - The user's own credentials (the session cookie, `Authorization`) still go as the browser sends them. Do not declare a header the user needs in the store, or every user goes with the store's value.
 - Without a `matcher`, Next runs the proxy on every request; to skip the rest, add `export const config = { matcher: '/api/:path*' };` to `proxy.ts` (Next reads it only when it is written there).
 
+### Sessions
+
+With [Better Auth](../backend/README.md#better-auth) on in the backend, its store declares `auth`, the `basePath` of Better Auth there. Without it the store stays as is.
+
+```ts
+// src/stores/backend.store.ts
+export default { type: 'api', auth: '/api/auth' };
+```
+
+```ts
+// src/controllers/session.controller.ts
+export default createController(({ stores: { backend } }) => ({
+  load: () => backend.readSession(),
+  signIn: (sEmail: string, sPassword: string) =>
+    backend.signIn('email', { email: sEmail, password: sPassword }),
+  signOut: () => backend.signOut(),
+}));
+```
+
+- `signIn(kind, body)` and `signUp(kind, body)` send `POST <auth>/sign-in/<kind>` and `POST <auth>/sign-up/<kind>`: `kind` is the method of Better Auth (`email`, ...), and `body` what it asks. `signOut()` sends `POST <auth>/sign-out`.
+- They return Better Auth's answer inside an `ApiResponse`: `{ success, result, message }`, with `success` when the backend answered 2xx and its `message` when it failed.
+- `readSession()` asks `GET <auth>/get-session` and keeps `{ user, session }` at `/session`, or `null` without a session. It answers from the store until a `signIn`, `signUp` or `signOut` succeeds, which reads it again. On the server it asks nothing and resolves with `{}`.
+- Any 401 of the store's backend sets `/session` to `null`, and the next `readSession()` asks again.
+- The session lives in Better Auth's cookie, which the proxy passes as any other: a refresh reads it again with `readSession()`.
+- Better Auth checks the `Origin` of every `POST`: add the URL of the frontend to its `trustedOrigins` in the backend.
+- With two backends with Better Auth, their cookies get the same name on the frontend's domain: give one of them another `advanced.cookiePrefix`.
+
+A page that needs a session gets a layout bound to the session controller: it renders nothing until the session is read, and goes to the login without one, also after a 401.
+
+```tsx
+// src/components/Private.tsx
+'use client';
+
+export default sessionController.bindView(({ props, stores: { backend }, load }) => {
+  const oRouter = useRouter();
+  const oSession = backend.get('/session');
+
+  useEffect(() => {
+    load();
+  }, []);
+
+  useEffect(() => {
+    if (oSession === null) oRouter.replace('/login');
+  }, [oSession]);
+
+  return oSession ? props.children : null;
+});
+// app/private/layout.tsx renders <Private>{children}</Private>
+```
+
+The data stays protected by the backend: the layout only keeps the page from showing.
+
 ### With a proxy of your own
 
 Next takes one `proxy.ts`. To keep yours, call nano-app's from it for `/api` and include `/api/:path*` in your `matcher`:
@@ -188,8 +262,18 @@ pnpm --filter nano-frontend-test-app build
 pnpm --filter nano-frontend-test-app start   # http://localhost:3100
 ```
 
-The `Users` component reads and writes `/users` of the `backend` store: point it at any backend that answers `GET`, `POST`, `PUT` and `DELETE` on `/users` with an `ApiResponse`, and give it the key its store declares:
+The `Users` component reads and writes `/users` of the `backend` store, and `UsersList` pages and sorts it with `list` of [`@nano-app/components`](../components): point it at any backend that answers `GET`, `QUERY` (`skip`, `top`, `orderby`), `POST`, `PUT` and `DELETE` on `/users` with an `ApiResponse`, and give it the key its store declares:
 
 ```bash
 API_BACKEND_URL=http://localhost:3000 API_BACKEND_KEY_HEADER=dev pnpm --filter nano-frontend-test-app start
 ```
+
+The `backend` store declares `auth: '/api/auth'`: the backend has Better Auth with `emailAndPassword`, and the URL of the app (`http://localhost:3100`) in its `trustedOrigins`. `/login` signs in, `/` shows the session with a button to sign out, and `/private` shows only with a session.
+
+## Design
+
+- The browser never talks to the backend: only the Next server does, and the backend URL never reaches the client bundle.
+- The frontend has no credential of its own and does not depend on any backend plugin. What the backend exposes and how it is protected is decided in the backend.
+- No `glob` or `jiti` in the client bundle, and no generated files in `node_modules`: build data goes through Next's `env`.
+- Rejected, not coming back: `useStore`, `createComponent`, `StoreManager`, controllers as classes, a `set` guard during render, a static (server) mode of the creator.
+- Not yet, until real controllers ask for it: `onInit`/`onExit` in the controller, inheritance between controllers, a debounce of the framework, dropping old reads, reading what other users change, `PATCH`, the React Compiler.

package/build/core/const.js

@@ -1,9 +1,19 @@
 //#region ../core/const.ts
+/** HTTP methods a route can handle */
+const HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"DELETE",
+	"QUERY"
+];
 /** Whether the code runs on the server, where Next renders each component once for the HTML */
 const IS_SERVER = typeof window === "undefined";
 /** Env var that carries the stores to the bundle. Read as `process.env.NANO_APP_STORES`, literal */
 const STORES_ENV = "NANO_APP_STORES";
+/** Message of a failed request whose answer brings none */
+const REQUEST_FAILED = "Request failed";
 /** Error of a component outside the provider */
 const MISSING_PROVIDER = "[nano-app] [ERROR] A component has no stores. Wrap the root layout with NanoAppProvider.";
 //#endregion
-export { IS_SERVER, MISSING_PROVIDER, STORES_ENV };
+export { HTTP_METHODS, IS_SERVER, MISSING_PROVIDER, REQUEST_FAILED, STORES_ENV };

package/build/core/loader/FileReader.js

@@ -4,6 +4,7 @@ import { createJiti } from "jiti";
 //#region ../core/loader/FileReader.ts
 /** Reads and loads files from disk, resolved from `cwd` */
 var FileReader = class {
+	/** Loader of the consumer's modules; the Prisma runtime is loaded natively */
 	static oJiti = createJiti(import.meta.url, { nativeModules: ["@prisma/client"] });
 	/** Loads a module via jiti */
 	static async loadModule(sFilePath, oOptions = {}) {

package/build/core/loader/Validator.js

@@ -1,11 +1,5 @@
+import { HTTP_METHODS } from "../const.js";
 //#region ../core/loader/Validator.ts
-const HTTP_METHODS = [
-	"GET",
-	"POST",
-	"PUT",
-	"DELETE",
-	"QUERY"
-];
 const STORE_TYPES = ["app", "api"];
 /** Checks the consumer's files: invalid ones are warned about and discarded */
 var Validator = class Validator {
@@ -24,15 +18,12 @@ var Validator = class Validator {
 		if (oEntry && typeof oEntry === "object") return true;
 		return Validator.warn(sFilePath, "the default export is not an object.");
 	}
-	/**
-	* Type guard for a `*.route.ts` entry.
-	*/
+	/** Type guard for a `*.route.ts` entry */
 	static isRoute(oEntry, sFilePath) {
 		if (!Validator.isObject(oEntry, sFilePath)) return false;
-		const oRoute = oEntry;
-		if (oRoute.expression && typeof oRoute.expression !== "string") return Validator.warn(sFilePath, "\"expression\" must be a string.");
-		for (const sMethod of HTTP_METHODS) if (oRoute[sMethod] && typeof oRoute[sMethod] !== "function") return Validator.warn(sFilePath, `"${String(sMethod)}" must be a function.`);
-		if (!HTTP_METHODS.some((sMethod) => oRoute[sMethod])) return Validator.warn(sFilePath, "defines no HTTP method.");
+		if (oEntry.expression && typeof oEntry.expression !== "string") return Validator.warn(sFilePath, "\"expression\" must be a string.");
+		for (const sMethod of HTTP_METHODS) if (oEntry[sMethod] && typeof oEntry[sMethod] !== "function") return Validator.warn(sFilePath, `"${sMethod}" must be a function.`);
+		if (!HTTP_METHODS.some((sMethod) => oEntry[sMethod])) return Validator.warn(sFilePath, "defines no HTTP method.");
 		return true;
 	}
 	/** Type guard for a `*.store.ts` entry */
@@ -41,11 +32,10 @@ var Validator = class Validator {
 		if (!STORE_TYPES.includes(oEntry.type)) return Validator.warn(sFilePath, `its type must be "app" or "api".`);
 		if (oEntry.data !== void 0 && (!oEntry.data || typeof oEntry.data !== "object")) return Validator.warn(sFilePath, "\"data\" must be an object.");
 		if (oEntry.headers !== void 0 && (!Validator.isObject(oEntry.headers, sFilePath) || Object.values(oEntry.headers).some((sValue) => typeof sValue !== "string"))) return Validator.warn(sFilePath, "\"headers\" must be an object of strings.");
+		if (oEntry.auth !== void 0 && typeof oEntry.auth !== "string") return Validator.warn(sFilePath, "\"auth\" must be a string: the base path of Better Auth.");
 		return true;
 	}
-	/**
-	* Type guard for a `.prisma` entry: the contents of the file, without comments.
-	*/
+	/** Type guard for a `.prisma` entry: the contents of the file, without comments */
 	static isPrisma(oEntry, sFilePath) {
 		if (typeof oEntry !== "string") return Validator.warn(sFilePath, "the contents are not a string.");
 		const sProvider = oEntry.match(/datasource\s+\w+\s*\{[^}]*provider\s*=\s*["']([^"']+)["']/s)?.[1];

package/build/core/types/api.d.ts

@@ -0,0 +1,10 @@
+//#region ../core/types/api.d.ts
+/** API response */
+export type ApiResponse<T = any> = {
+  status?: number;
+  success?: boolean;
+  result?: T;
+  message?: string;
+  warning?: boolean;
+};
+//#endregion

package/build/core/utils/Formatter.js

@@ -3,7 +3,8 @@
 var Formatter = class {
 	/** Message of anything thrown: its `message` when it has one, else the value itself */
 	static error(oError) {
-		return String(oError?.message ?? oError);
+		if (oError && typeof oError === "object" && "message" in oError) return String(oError.message ?? oError);
+		return String(oError);
 	}
 	/** Formats a date for the request log, in UTC: `2026-10-19 12:03:10` */
 	static logDate(oDate = /* @__PURE__ */ new Date()) {

package/build/creators/createStores.js

@@ -1,15 +1,20 @@
 import Store from "../stores/Store.js";
 import ApiStore from "../stores/ApiStore.js";
+import AuthStore from "../stores/AuthStore.js";
+import STORE_FILES from "../stores/storeFiles.js";
 //#region src/creators/createStores.ts
 /** Stores of one React tree, from the ones `withNanoApp` inlined at build time */
 function createStores() {
-	const oFiles = JSON.parse(process.env.NANO_APP_STORES ?? "{}");
 	return {
-		...Object.fromEntries(Object.entries(oFiles).map(([sName, oFile]) => {
-			return [sName, oFile.type === "api" ? new ApiStore(sName, oFile.data) : new Store(oFile.data)];
-		})),
-		["app"]: new Store(oFiles["app"]?.data)
+		...Object.fromEntries(Object.entries(STORE_FILES).map(([sName, oFile]) => [sName, createStore(sName, oFile)])),
+		["app"]: new Store(STORE_FILES["app"]?.data)
 	};
 }
+/** Store of one file: an api store reads its backend, with Better Auth when it declares `auth` */
+function createStore(sName, oFile) {
+	if (oFile.type !== "api") return new Store(oFile.data);
+	if (oFile.auth) return new AuthStore(sName, oFile.auth, oFile.data);
+	return new ApiStore(sName, oFile.data);
+}
 //#endregion
 export { createStores as default };

package/build/index.d.ts

@@ -1,4 +1,5 @@
+import { ApiError } from "./types/store.js";
 import { NanoAppProvider } from "./react/NanoAppProvider.js";
 import { ComponentContext, ComponentProps, Controller, View } from "./types/component.js";
 import createController from "./creators/createController.js";
-export { type ComponentContext, type ComponentProps, type Controller, NanoAppProvider, type View, createController };
+export { type ApiError, type ComponentContext, type ComponentProps, type Controller, NanoAppProvider, type View, createController };

package/build/proxy.js

@@ -1,12 +1,12 @@
+import STORE_FILES from "./stores/storeFiles.js";
 import { NextResponse } from "next/server";
 //#region src/proxy.ts
 /** Sends `/api/<store>/<path>` to the backend of `<store>`, in `API_<STORE>_URL`, with its headers */
 async function proxy(oReq) {
 	const [, sPrefix, sName, ...aPath] = oReq.nextUrl.pathname.split("/");
 	if (sPrefix !== "api" || !sName) return NextResponse.next();
-	const oFiles = JSON.parse(process.env.NANO_APP_STORES ?? "{}");
 	const sUrlEnv = `API_${sName.toUpperCase()}_URL`;
-	const aHeaders = Object.entries(oFiles[sName]?.headers ?? {}).map(([sHeader, sValue]) => [sHeader, `API_${sValue.toUpperCase()}_HEADER`]);
+	const aHeaders = Object.entries(STORE_FILES[sName]?.headers ?? {}).map(([sHeader, sValue]) => [sHeader, `API_${sValue.toUpperCase()}_HEADER`]);
 	const sMissing = [sUrlEnv, ...aHeaders.map(([, sEnvName]) => sEnvName)].find((sEnvName) => !process.env[sEnvName]);
 	if (sMissing) return NextResponse.json({
 		success: false,

package/build/stores/ApiStore.js

@@ -1,80 +1,115 @@
-import { IS_SERVER } from "../core/const.js";
+import { IS_SERVER, REQUEST_FAILED } from "../core/const.js";
 import Store from "./Store.js";
-import { observable, runInAction } from "mobx";
 //#region src/stores/ApiStore.ts
-/**
-* Backend data of an `api` store, through its proxy (`/api/<name>/...`), by path and query.
-* Its own state (`get`/`set`) is the one of a `Store`; what it read stays apart.
-*/
+/** Backend of an `api` store through its proxy; each read keeps its `ApiResponse` in the store */
 var ApiStore = class ApiStore extends Store {
 	sName;
-	oCache = observable({
-		iBusy: 0,
-		oResults: {},
-		oVersions: {}
-	});
-	oRead = {};
+	oVersions = {};
+	oKept = {};
+	iCount = 0;
 	/** Store of the backend `API_<NAME>_URL`, with the initial data of its file */
 	constructor(sName, oData) {
 		super(oData);
 		this.sName = sName;
 	}
-	/** Requests in progress */
-	get busy() {
-		return this.oCache.iBusy;
+	/** Value at a path, with the query of the read that kept it */
+	get(sPath, oQuery) {
+		return super.get(ApiStore.key(sPath, oQuery));
 	}
-	/** Result at a path: from local, asked to the backend when never read or its entity changed */
-	read(sPath, oQuery) {
-		if (IS_SERVER) return void 0;
-		const sKey = oQuery ? `${sPath}?${JSON.stringify(oQuery)}` : sPath;
-		const iVersion = this.oCache.oVersions[ApiStore.entity(sPath)] ?? 0;
-		if (this.oRead[sKey] !== iVersion) {
-			this.oRead[sKey] = iVersion;
-			const oInit = oQuery ? {
-				method: "QUERY",
-				body: JSON.stringify(oQuery)
-			} : { method: "GET" };
-			queueMicrotask(() => this.request(sPath, oInit).then((oResponse) => runInAction(() => this.oCache.oResults[sKey] = oResponse.result)));
-		}
-		return this.oCache.oResults[sKey];
+	/** `ApiResponse` of a path and query, from the store while it was kept at its path's version */
+	async read(sPath, oQuery) {
+		if (IS_SERVER) return {};
+		const sKey = ApiStore.key(sPath, oQuery);
+		const iVersion = this.oVersions[sPath] ?? 0;
+		if (this.oKept[sKey] === iVersion) return this.get(sPath, oQuery);
+		const oInit = oQuery ? {
+			method: "QUERY",
+			body: JSON.stringify(oQuery)
+		} : { method: "GET" };
+		const oResponse = await this.request(sPath, oInit);
+		if ((this.oVersions[sPath] ?? 0) !== iVersion) return oResponse;
+		this.keep(oResponse, sPath, oQuery);
+		return oResponse;
 	}
 	/** `POST <path>` */
 	create(sPath, oBody) {
 		return this.write("POST", sPath, oBody);
 	}
-	/** `PUT <path>` */
-	update(sPath, oBody) {
-		return this.write("PUT", sPath, oBody);
+	/** `PUT <path>`, keeping a successful answer at its path with its new version */
+	async update(sPath, oBody) {
+		const oResponse = await this.write("PUT", sPath, oBody);
+		if (!oResponse.success) return oResponse;
+		this.keep(oResponse, sPath);
+		return oResponse;
 	}
 	/** `DELETE <path>` */
 	delete(sPath) {
 		return this.write("DELETE", sPath);
 	}
-	/** Sends a write and changes the version of its entity when the answer comes back */
-	write(sMethod, sPath, oBody) {
-		return this.request(sPath, {
+	/** Sends a write and raises the version of its path and its parents */
+	async write(sMethod, sPath, oBody) {
+		const oResponse = await this.request(sPath, {
 			method: sMethod,
 			body: JSON.stringify(oBody)
-		}).finally(() => runInAction(() => {
-			const sEntity = ApiStore.entity(sPath);
-			this.oCache.oVersions[sEntity] = (this.oCache.oVersions[sEntity] ?? 0) + 1;
-		}));
+		});
+		for (const sParent of ApiStore.parents(sPath)) this.oVersions[sParent] = (this.oVersions[sParent] ?? 0) + 1;
+		return oResponse;
 	}
-	/** Sends a request to the proxy and returns its JSON answer, counting it as busy */
+	/** Sends a request, keeping `/busy` while it is out and a failed answer in `/error/list` */
 	async request(sPath, oInit) {
-		runInAction(() => this.oCache.iBusy++);
+		this.iCount++;
+		this.set("/busy", true);
+		let sText;
+		let oResponse = {
+			success: false,
+			message: REQUEST_FAILED
+		};
 		try {
-			return await (await fetch(`/api/${this.sName}${sPath}`, {
+			const oRes = await fetch(`/api/${this.sName}${sPath}`, {
 				...oInit,
 				headers: { "content-type": "application/json" }
-			})).json();
-		} finally {
-			runInAction(() => this.oCache.iBusy--);
+			});
+			sText = await oRes.text();
+			oResponse = this.receive(sPath, oRes, JSON.parse(sText));
+		} catch {
+			if (sText !== void 0) oResponse = {
+				...oResponse,
+				result: sText
+			};
+		}
+		if (!oResponse.success) {
+			const oError = {
+				...oResponse,
+				message: oResponse.message || "Request failed",
+				timestamp: Date.now()
+			};
+			this.set("/error/list", [...this.get("/error/list") ?? [], oError]);
 		}
+		this.iCount--;
+		this.set("/busy", this.iCount > 0);
+		return oResponse;
+	}
+	/** `ApiResponse` of an answer of the proxy, from its JSON */
+	receive(_sPath, _oRes, oResponse) {
+		return oResponse;
+	}
+	/** Keeps an answer at its path and query, over what was there, with its path's version */
+	keep(oResponse, sPath, oQuery) {
+		const sKey = ApiStore.key(sPath, oQuery);
+		this.set(sKey, {
+			...this.get(sPath, oQuery),
+			...oResponse
+		});
+		this.oKept[sKey] = this.oVersions[sPath] ?? 0;
+	}
+	/** A path and each of its parents */
+	static parents(sPath) {
+		const aKeys = sPath.split("/").filter(Boolean);
+		return aKeys.map((_sKey, iIndex) => `/${aKeys.slice(0, iIndex + 1).join("/")}`);
 	}
-	/** Entity of a path: its first segment (`/users/7` → `/users`) */
-	static entity(sPath) {
-		return `/${sPath.split("/").filter(Boolean)[0] ?? ""}`;
+	/** Key of a read: its path, with its query when it has one */
+	static key(sPath, oQuery) {
+		return oQuery ? `${sPath}?${JSON.stringify(oQuery)}` : sPath;
 	}
 };
 //#endregion

package/build/stores/AuthStore.js

@@ -0,0 +1,60 @@
+import { IS_SERVER } from "../core/const.js";
+import ApiStore from "./ApiStore.js";
+//#region src/stores/AuthStore.ts
+/** Api store of a backend with Better Auth: signs in and out, and keeps the session */
+var AuthStore = class extends ApiStore {
+	sBasePath;
+	oSession;
+	/** Store of the backend `API_<NAME>_URL`, with Better Auth at its base path */
+	constructor(sName, sBasePath, oData) {
+		super(sName, oData);
+		this.sBasePath = sBasePath;
+	}
+	/** `POST <basePath>/sign-in/<kind>` (`email`...), reading the session again on success */
+	signIn(sKind, oBody) {
+		return this.post(`/sign-in/${sKind}`, oBody);
+	}
+	/** `POST <basePath>/sign-up/<kind>`, reading the session again on success */
+	signUp(sKind, oBody) {
+		return this.post(`/sign-up/${sKind}`, oBody);
+	}
+	/** `POST <basePath>/sign-out`, reading the session again on success */
+	signOut() {
+		return this.post("/sign-out", {});
+	}
+	/** `GET <basePath>/get-session` into `/session`, kept until the next sign-in, -up or -out */
+	async readSession() {
+		if (IS_SERVER) return {};
+		if (this.oSession) return this.oSession;
+		const oResponse = await this.request(`${this.sBasePath}/get-session`, { method: "GET" });
+		this.oSession = oResponse;
+		this.set("/session", oResponse.result ?? null);
+		return oResponse;
+	}
+	/** Better Auth's answer inside an `ApiResponse`; a 401 of the backend clears the session */
+	receive(sPath, oRes, oBody) {
+		if (oRes.status === 401) {
+			this.oSession = void 0;
+			this.set("/session", null);
+		}
+		if (!sPath.startsWith(`${this.sBasePath}/`)) return oBody;
+		return {
+			success: oRes.ok,
+			result: oBody,
+			message: oBody?.message
+		};
+	}
+	/** Sends a `POST` to Better Auth and, on success, reads the session again */
+	async post(sPath, oBody) {
+		const oResponse = await this.request(`${this.sBasePath}${sPath}`, {
+			method: "POST",
+			body: JSON.stringify(oBody)
+		});
+		if (!oResponse.success) return oResponse;
+		this.oSession = void 0;
+		await this.readSession();
+		return oResponse;
+	}
+};
+//#endregion
+export { AuthStore as default };

package/build/stores/storeFiles.js

@@ -0,0 +1,5 @@
+//#region src/stores/storeFiles.ts
+/** Store files that `withNanoApp` inlined at build time, read once when the app loads */
+const STORE_FILES = JSON.parse(process.env.NANO_APP_STORES ?? "{}");
+//#endregion
+export { STORE_FILES as default };

package/build/types/store.d.ts

@@ -1,7 +1,13 @@
 import { APP_NAME } from "../core/const.js";
 import { NanoObject } from "../core/types/objects.js";
+import { ApiResponse } from "../core/types/api.js";
 import Store from "../stores/Store.js";
 //#region src/types/store.d.ts
+/** A failed request in the `/error/list` of its api store: its `ApiResponse` and when it failed */
+export type ApiError = ApiResponse & {
+  /** Milliseconds since the epoch, from `Date.now()` */
+  timestamp: number;
+};
 /** Stores of a React tree by name: a `Store` per `app` file, an `ApiStore` per `api` file */
 export type Stores = NanoObject<any> & {
   [APP_NAME]: Store;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-app/frontend",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "React provider for Next.js apps on top of @nano-app/backend",
   "type": "module",
   "exports": {
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
   },
   "peerDependencies": {
     "next": ">=16.3.0",