react-shopwave-connect 0.1.2 → 0.3.0

package/README.md

@@ -4,6 +4,12 @@ Shopwave API client split into two clearly separated layers:
 
 - **`core`** — framework-agnostic async API functions + all TypeScript types. No React anywhere. Works in any TS/JS project (Node script, Vue, Angular, CLI, …).
 - **`hooks`** — thin React wrappers around `core`, with a consistent `{ data, loading, error, refetch }` shape. React is a **peer dependency** and is never bundled.
+- **`server` / `next`** — the other half of the contract: OAuth login and the `/api/*` route handlers that `core` calls, so an app's API routes are one line each.
+
+```
+browser / Node ──core──▶ your app's /api/<route> ──next route handlers──▶ Shopwave API
+                         (session cookie or Authorization: OAuth <token>)
+```
 
 ```
 src/
@@ -28,6 +34,8 @@ npm install react react-dom
 | `react-shopwave-connect/core`         | Framework-agnostic functions + types only     |
 | `react-shopwave-connect/hooks`        | React hooks only                              |
 | `react-shopwave-connect`              | Both (re-exports `core` + `hooks`)            |
+| `react-shopwave-connect/server`       | **Server-only.** Framework-agnostic Shopwave OAuth client + token helpers |
+| `react-shopwave-connect/next`         | **Server-only.** Next.js login/callback/logout/session handlers, token refresh, proxy guard, and the `/api/*` route handlers (`createShopwaveApi`) |
 
 Prefer the subpath imports when you want a hard boundary — e.g. a Node service should import from `/core` so React never enters the dependency graph.
 
@@ -39,13 +47,18 @@ Every `core` function (and every hook) accepts an optional `options` argument:
 interface RequestOptions {
   baseUrl?: string;        // prefix for every path; omit in the browser to use
                            // relative URLs like "/api/products"
-  token?: string;          // forwarded as the `token` request header
+  token?: string;          // sent as `Authorization: OAuth <token>` on every
+                           // request (GET, POST, PUT, DELETE alike)
   fetch?: typeof fetch;    // custom fetch (Node < 18, tests, interceptors)
   signal?: AbortSignal;    // cancellation (hooks pass this automatically)
 }
 ```
 
-In the browser / Next.js you can usually omit `options` entirely (relative URLs resolve against the current origin). Outside the browser, pass an absolute `baseUrl` and a `token`.
+In the browser / Next.js you can usually omit `options` entirely (relative URLs resolve against the current origin, and the app's routes use the session cookie). Outside the browser, pass the absolute `baseUrl` of an app that mounts the SDK routes (see [API routes](#4-api-routes-nextjs)) and a `token`.
+
+`core` always calls `/api/<route>` paths with the request metadata in an `extras` header, so `baseUrl` must point at such an app, not at the Shopwave API itself.
+
+> **0.3 change:** the token used to travel in `extras.token` for reads and a separate `token` header for writes. It is now always the `Authorization` header. The 0.3 route handlers still accept both old forms, so older clients keep working.
 
 ---
 
@@ -62,8 +75,8 @@ import {
 } from "react-shopwave-connect/core";
 
 const options = {
-  baseUrl: "https://api.shopwave.example",
-  token: process.env.SHOPWAVE_TOKEN,
+  baseUrl: "https://admin.example.com", // an app with the SDK's /api routes
+  token: process.env.SHOPWAVE_TOKEN,    // bare access token
 };
 
 async function main() {
@@ -92,23 +105,80 @@ On Node < 18 (no global `fetch`), inject one:
 import { fetchStores } from "react-shopwave-connect/core";
 import fetch from "node-fetch";
 
-await fetchStores({}, { baseUrl: "https://api.merchantstack.com", fetch });
+await fetchStores({}, { baseUrl: "https://admin.example.com", token, fetch });
+```
+
+Functions **throw** `ShopwaveApiError` on failure:
+
+```ts
+import { saveProduct, ShopwaveApiError } from "react-shopwave-connect/core";
+
+try {
+  await saveProduct({ name: "Tea", barcode: "123" });
+} catch (e) {
+  if (e instanceof ShopwaveApiError) {
+    e.status;          // HTTP status (0 = no response). 200/201 when the API answered with errors.
+    e.errors;          // api.message.errors, e.g. { 908: { id: 908, title: … } }
+    e.isUnauthorized;  // 401 or error 908 → send the user to log in
+  }
+}
+```
+
+The SDK never logs requests (older versions `console.log`ged headers, including tokens).
+
+### Saving and deleting (typed)
+
+Each entity has `save…`, `delete…` and `fetch…(id)`:
+
+```ts
+import { saveCategory, deleteCategory, fetchCategory } from "react-shopwave-connect/core";
+
+const created = await saveCategory({ title: "Drinks", parentId: null }); // no id → create
+created.id;                                                              // the new id, straight from the save
+
+const updated = await saveCategory({ id: created.id, title: "Hot drinks" }); // id → update
+
+await fetchCategory(created.id);                     // Category | null
+await fetchCategory(created.id, { deleted: true });  // include soft-deleted
+
+await deleteCategory(created.id);
 ```
 
-Functions **throw** on network failure or API errors (the error message contains the serialized API errors), so wrap calls in `try/catch`.
+| Entity    | Save / delete / read one                                  | App routes                    |
+| --------- | --------------------------------------------------------- | ----------------------------- |
+| product   | `saveProduct`, `deleteProduct`, `fetchProduct`             | `/api/products[/:id]`         |
+| category  | `saveCategory`, `deleteCategory`, `fetchCategory`          | `/api/categories[/:id]`       |
+| store     | `saveStore`, `deleteStore`, `fetchStore`                   | `/api/stores[/:id]`           |
+| promotion | `savePromotion`, `deletePromotion` (ends it), `fetchPromotion` | `/api/promotions[/:id]`       |
+| employee  | `saveEmployee`, `deleteEmployee` (retires), `fetchEmployee` | `/api/employees[/:id]`        |
+| consumer  | `fetchConsumer` only — read-only in the API                | `/api/consumer[/:id]` (GET)   |
+
+How they behave (matches what the Shopwave API does):
+
+- **Save** sends `{ <collection>: { "0": entity } }`. Shopwave upserts (an `id` means update), answers **201** and echoes the entity under the same ref with its `id` and server fields. The function checks `api.message.errors` and that the ref came back, and returns the saved entity (fields the echo leaves out are kept from your input). `saveEntities(kind, [a, b])` saves several at once and matches results back by ref.
+- **Delete** is a soft delete (read it back with `deleted: true`). Shopwave answers **205 with an empty body — also for ids that don't exist**, so a resolved promise means "accepted", not "a record was deleted".
+- **Read one** calls `GET /api/<route>/:id` and returns the record or `null`. List reads return `[]` when nothing matches (Shopwave answers with an empty body).
+- **Promotions:** Shopwave has no promotion DELETE; `deletePromotion` (and `DELETE /api/promotions/:id`) ends the promotion by setting `endDate` to now.
+- **Employees:** Shopwave has no employee DELETE, so `deleteEmployee` (and `DELETE /api/employees/:id`) retires the employee by setting `exitDate`. Updating an existing employee only changes `roleId`, `joinedDate` and `exitDate` — names and email are fixed — and the echo carries only those fields, so re-read with `fetchEmployee` if you need the stored record.
+- **Consumers** are read-only (`GET /consumer` by `ids`); their write/delete routes answer 405.
+- Errors are read from `api.message.errors` and also `api.message.error` (the name used in the [API reference](https://developer.merchantstack.com/api-reference.html)).
+
+The generic forms are `saveEntity(kind, item)`, `deleteEntityById(kind, id)` and `fetchEntityById(kind, id)`; `SHOPWAVE_ENTITIES` lists each entity's route, collection key, Shopwave path and id headers.
 
 ### Available `core` functions
 
 | Domain    | Function(s)                                              |
 | --------- | ------------------------------------------------------- |
-| category  | `fetchCategories`                                       |
-| consumer  | `fetchConsumers`                                        |
-| employee  | `fetchEmployees`                                        |
-| product   | `fetchProducts`, `fetchProductsMap` (batched, keyed)    |
-| store     | `fetchStores`                                           |
+| category  | `fetchCategories`, `fetchCategory`, `saveCategory`, `deleteCategory` |
+| consumer  | `fetchConsumers`, `fetchConsumer` (read-only)            |
+| employee  | `fetchEmployees`, `fetchEmployee`, `saveEmployee`, `deleteEmployee` |
+| product   | `fetchProducts`, `fetchProductsMap` (batched, keyed), `fetchProduct`, `saveProduct`, `deleteProduct` |
+| promotion | `fetchPromotions`, `fetchPromotion`, `savePromotion`, `deletePromotion` |
+| store     | `fetchStores` (now with `storeIds`), `fetchStore`, `saveStore`, `deleteStore` |
 | report    | `fetchReport`                                           |
-| session   | `logout`                                                |
-| entity    | `deleteEntity`, `submitEntity`                          |
+| session   | `fetchSession`, `loginPath`, `logoutPath`, `logout`     |
+| entity    | `saveEntity`, `saveEntities`, `deleteEntityById`, `fetchEntityById`; low-level `submitEntity` / `deleteEntity` (raw endpoint) |
+| errors    | `ShopwaveApiError`, `getApiErrorMap`, `assertNoApiErrors` |
 | basket    | `buildBasketReportQuery`, `parseBasketReportData`, `combineBasketRows`, `computeBasketSummary`, … (pure transforms) |
 
 All types/interfaces (`Product`, `Store`, `Category`, `Consumer`, `Employee`, `ReportQueryMap`, `Basket*`, `apiResponse`, …) are exported from `core` too.
@@ -120,9 +190,13 @@ All types/interfaces (`Product`, `Store`, `Category`, `Consumer`, `Employee`, `R
 Every auto-fetching hook returns the same shape:
 
 ```ts
-{ data, loading, error, refetch }
+{ data, loading, fetching, error, errorStatus, refetch }
 ```
 
+- `loading` is true only while there's nothing to show yet (first load, or the params changed).
+- `refetch()` keeps the current `data` on screen until the new data arrives (`fetching` is true meanwhile), so lists don't flash a skeleton after every save. A failed refetch keeps the old data and sets `error`.
+- `errorStatus` is the HTTP status of the last error.
+
 ```tsx
 "use client";
 import { useProduct, useStore } from "react-shopwave-connect/hooks";
@@ -150,12 +224,14 @@ const { data } = useProduct({ storeId }, { baseUrl: "https://api.merchantstack.c
 
 ### Auto-fetch hooks (`useEffect`-based)
 
-`useCategory`, `useConsumer`, `useEmployee`, `useProduct`, `useStore`, `useReport`.
+`useCategory`, `useConsumer`, `useEmployee`, `useProduct`, `usePromotion`, `useStore`, `useReport`, `useSession`.
 They fetch on mount and re-run when their arguments change. `useConsumer` and `useReport` stay idle until you pass ids / a query (they return `loading: false`, `data: null` until then). `refetch()` replaces the old `reloadFlag` argument.
 
 ### Manually-triggered hooks (`useCallback`-based)
 
-`useDelete`, `useSubmit`, `useLogout` return `{ mutate, data, loading, error }` — nothing fires until you call `mutate`:
+For saves and deletes, prefer calling the typed `core` functions (`saveProduct`, `deleteStore`, …) from your event handlers — they return the saved entity with its id.
+
+`useDelete`, `useSubmit`, `useLogout` return `{ mutate, data, loading, error, errorStatus }` — nothing fires until you call `mutate`:
 
 ```tsx
 import { useDelete, useSubmit } from "react-shopwave-connect/hooks";
@@ -179,37 +255,188 @@ const saved = await save({
 
 ---
 
-## Auth & Next.js note
+## 3. Authentication (Shopwave OAuth)
+
+Login is the same for every Shopwave app; only the **config** differs (client id/secret, redirect URL, session secret). The Shopwave auth server uses the authorization-code flow **with a client secret** (no PKCE), so the exchange must happen on a server — the browser only follows redirects and never sees a token.
+
+```
+browser ──/auth?returnTo=/products──▶ your app ──302──▶ {authServer}/login?…&state=…
+        ◀──────────── user signs in on Shopwave ─────────────┘
+browser ──/auth?code=…&state=…──▶ your app ──POST /oauth/token (secret)──▶ auth server
+        ◀──302 /products + encrypted httpOnly cookie (tokens stay server-side)
+```
+
+What the SDK handles for you:
+
+- `state` check (login-CSRF protection) and a safe `returnTo` (same-origin paths only).
+- One callback URL per app: `returnTo` rides along in the session, so tools/sub-sections don't need their own redirect URIs.
+- Tokens stored as `{ accessToken, refreshToken, tokenType, expiresAt }` in an **iron-session** cookie (httpOnly, SameSite=Lax, Secure in production).
+- Refresh when the access token has expired (Shopwave issues a new one only after expiry; the refresh token is not rotated), de-duplicated across concurrent requests. A rejected refresh token logs the user out.
+- `GET /api/session` returns `{ loggedIn, expiresAt }` — **never tokens**.
+- Sessions written by older apps (raw `{ access_token, refresh_token, … }` in `session.token`) keep working.
+
+### Next.js (App Router) setup
+
+Install the peer dependencies once: `npm install react-shopwave-connect iron-session`.
 
-The original `useLogin` / `useLogout` were tightly coupled to Next.js (`next/navigation` router + `'use server'` actions) and **cannot** be framework-agnostic, so they are **not** shipped here. Instead:
+**1. One config file per app**
 
-- `core.logout()` / `useLogout()` end the server session (`DELETE /api/session?action=logout`) — no redirect.
-- The redirect to the auth server's login/logout URL stays in your app, since it depends on your server actions and router:
+```ts
+// lib/auth.ts
+import { createShopwaveAuth } from "react-shopwave-connect/next";
+
+export const auth = createShopwaveAuth({
+  authServerUrl: process.env.SHOPWAVE_AUTH_SERVER_URL!, // e.g. https://secure.merchantstack.com
+  clientId:      process.env.SHOPWAVE_CLIENT_ID!,
+  clientSecret:  process.env.SHOPWAVE_CLIENT_SECRET!,
+  redirectUri:   process.env.SHOPWAVE_REDIRECT_URL!,    // e.g. https://admin.example.com/auth (registered on the auth server)
+  session: {
+    password:   process.env.SESSION_SECRET!,            // ≥ 32 random chars
+    cookieName: "shopwave_session_cookie",              // keep your existing name to keep users logged in
+  },
+  // authPath: "/auth", logoutPath: "/auth/logout", sessionPath: "/api/session",
+  // defaultReturnTo: "/", requireState: true, refreshSkewSeconds: 0,
+});
+```
+
+Config is validated on first use, so a missing env var doesn't break `next build`.
+
+**2. Three route files**
+
+```ts
+// app/auth/route.ts          — the redirect-URI path: starts login AND receives the callback
+import { auth } from "@/lib/auth";
+export const GET = auth.handlers.auth;
+
+// app/auth/logout/route.ts   — clears the session, then logs out of the auth server
+import { auth } from "@/lib/auth";
+export const GET = auth.handlers.logout;
+
+// app/api/session/route.ts   — { loggedIn, expiresAt } for the browser; DELETE ends the session
+import { auth } from "@/lib/auth";
+export const { GET, DELETE } = auth.handlers.session;
+```
+
+**3. Protect pages and APIs** (`proxy.ts` in Next 16, `middleware.ts` before that)
+
+```ts
+import { NextResponse, type NextRequest } from "next/server";
+import { auth } from "@/lib/auth";
+
+export async function proxy(request: NextRequest) {
+  return (await auth.protect(request, { publicPaths: ["/tools/tag-joiner"] })) ?? NextResponse.next();
+}
+
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+```
+
+Logged-out page requests are redirected to `/auth?returnTo=<page>`; paths under `/api` get a `401` JSON instead. The auth, logout and session paths are always public. `protect` only reads the cookie — it never calls the auth server.
+
+**4. Use the token in route handlers**
+
+```ts
+import { auth } from "@/lib/auth";
+import { isExpiredTokenResponse } from "react-shopwave-connect/next";
+
+export const GET = auth.withAuth(async (request, context, { authorization }) => {
+  const call = (header: string) =>
+    fetch(`${process.env.SHOPWAVE_API_SERVER_URL}/product`, {
+      headers: { Authorization: header, "x-accept-version": "2.0" },
+    });
+
+  let res = await call(authorization);
+  let body = await res.json();
+
+  // Clock said valid but the API says expired (HTTP 401 / API error 908): refresh once and retry.
+  if (isExpiredTokenResponse(res.status, body)) {
+    const fresh = await auth.getAuthorizationHeader({ forceRefresh: true });
+    if (!fresh) return Response.json({ error: "unauthorized" }, { status: 401 });
+    res = await call(fresh);
+    body = await res.json();
+  }
+  return Response.json(body, { status: res.status });
+});
+```
+
+Also available: `auth.getAccessToken()`, `auth.getAuthorizationHeader()`, `auth.getToken()`, `auth.getStatus()`, `auth.loginPath(returnTo)`, `auth.logoutPath`, `auth.isAuthenticated(request)`. Refreshed tokens are saved automatically from route handlers, server actions and proxy (Server Components can read tokens but can't write cookies).
+
+**5. In the browser**
 
 ```tsx
 "use client";
-import { useRouter } from "next/navigation";
-import { useLogout } from "react-shopwave-connect/hooks";
-import { getLogoutUrl } from "@/app/actions";
+import { useSession, loginPath, logoutPath } from "react-shopwave-connect";
+
+export function AccountButton() {
+  const { data: session, loading } = useSession();
+  if (loading) return null;
+  return session?.loggedIn
+    ? <a href={logoutPath()}>Log out</a>
+    : <a href={loginPath(window.location.pathname)}>Log in</a>;
+}
+```
 
-export function LogoutButton() {
-  const router = useRouter();
-  const { mutate: endSession } = useLogout();
+Use plain links / `window.location` for login and logout — they are full-page redirects to the auth server, not client-side navigations.
 
-  const onClick = async () => {
-    await endSession();
-    router.push(await getLogoutUrl(window.location.origin + "/auth"));
-  };
+### 4. API routes (Next.js)
 
-  return <button onClick={onClick}>Log out</button>;
-}
+`core` calls `/api/<route>` on your app. `createShopwaveApi` provides those routes, using the session from step 1:
+
+```ts
+// lib/shopwave.ts
+import { createShopwaveApi } from "react-shopwave-connect/next";
+import { auth } from "@/lib/auth";
+
+export const shopwave = createShopwaveApi({ auth, apiUrl: process.env.SHOPWAVE_API_SERVER_URL! });
 ```
 
+```ts
+// app/api/products/route.ts       — list/filter, create/update
+import { shopwave } from "@/lib/shopwave";
+export const { GET, POST, PUT } = shopwave.collection("product");
+
+// app/api/products/[id]/route.ts  — read one, update, delete
+import { shopwave } from "@/lib/shopwave";
+export const { GET, PUT, DELETE } = shopwave.item("product");
+
+// app/api/report/route.ts         — any other Shopwave path, read-only
+import { shopwave } from "@/lib/shopwave";
+export const { GET } = shopwave.passthrough("report");
+```
+
+Entities: `product`, `category`, `store`, `promotion`, `employee` (DELETE retires via `exitDate`), `promotion` (DELETE ends it via `endDate`), `consumer` (mounted at `/api/consumer`; GET only, writes answer 405). For anything else, `shopwave.forward(request, { method, path, headers, postBody })` does the same token/refresh/encoding work for a custom handler.
+
+Every handler:
+
+- uses the caller's `Authorization: OAuth <token>` when present (also the legacy `token` header / `extras.token`), otherwise the logged-in user's token; `401` when there's neither. Turn caller tokens off with `allowRequestToken: false`.
+- turns the `extras` JSON header into upstream headers, dropping `Authorization`, `token`, `Cookie`, `Host`, `x-accept-version` and other transport headers; `400` if it isn't a JSON object.
+- sends writes as the form field `postBody=<JSON>`, accepting the SDK shape `{ products: { "0": {…} } }`, the older `{ products: { new | updated: {…} } }`, or a bare entity. Item `PUT` forces the id from the URL.
+- on HTTP 401 or API error 908 with the session token, refreshes once and retries.
+- answers with Shopwave's own status and body (201 + echo for saves, 205 + empty body for deletes, error envelopes as-is); `502` if the API can't be reached. Only the method and path are ever logged.
+
+For calls that bring their own token (scripts, the integration tests), let them past the proxy guard:
+
+```ts
+await auth.protect(request, { publicPaths: [...], allowRequestToken: true });
+```
+
+Options: `apiVersion` (default `"2.0"`), `fetch`, `entities` (override a route/header, e.g. `{ employee: { idHeader: "userId" } }`), `blockedExtras`, `onError`.
+
+### Other frameworks
+
+`react-shopwave-connect/server` has the same building blocks without Next.js: `createShopwaveOAuth(config)` → `buildLoginUrl({ state })`, `exchangeCode(code)`, `refreshToken(token)`, `buildLogoutUrl()`, plus `createState`, `sanitizeReturnTo`, `isTokenExpired`, `isExpiredTokenResponse` and `authorizationHeader`. The API routes are `createShopwaveApiHandlers({ apiUrl, getAuthorization })` — plain `Request → Response` handlers, the same ones `createShopwaveApi` wraps. Store the token in your framework's session (Express `express-session`, iron-session's `getIronSession(req, res)`, …).
+
+### Moving an existing app over
+
+- Keep `redirectUri` equal to the URL already registered on the auth server (AdminUI: `…/auth`) and mount `handlers.auth` at that path.
+- Keep `cookieName` the same and use the same `SESSION_SECRET` value as the old iron-session password — current users stay logged in; their old token shape is read and upgraded on the next refresh.
+- Per-tool auth routes can go: link to `auth.loginPath("/tools/where-to-next")` instead.
+- `core.logout()` / `useLogout()` still work (`DELETE /api/session`), but prefer linking to `logoutPath()` so the auth-server session ends too.
+
 ---
 
 ## Build
 
-Built with [`tsdown`](https://tsdown.dev) into dual ESM + CJS with `.d.ts` types, via two separate entries (`core` with no externals, `hooks` with `react`/`react-dom` marked external so they're never bundled).
+Built with [`tsdown`](https://tsdown.dev) into dual ESM + CJS with `.d.ts` types, via separate entries: `core` (no externals), `hooks` (`react`/`react-dom` external), `server` (no externals) and `next` (`next`/`iron-session` external — optional peer dependencies). `server` and `next` are never re-exported from the root entry, so they can't end up in client bundles.
 
 ```bash
 npm run build       # emit dist/
@@ -220,26 +447,33 @@ npm run typecheck   # tsc --noEmit
 
 ## Testing
 
-Integration tests run against a live API using [Vitest](https://vitest.dev). Tests are located in `tests/integration/` and cover full CRUD lifecycles for Products, Categories, Consumers, and Employees.
+Unit tests (offline, no credentials) cover the OAuth client, token handling, the Next.js handlers (with an in-memory cookie store), the session client, the request layer (token header, errors, no logging), the typed save/delete/read functions, the API route handlers (extras filtering, refresh-and-retry, body normalisation, 205 pass-through) and the hooks' query state:
+
+```bash
+npm test            # = npm run test:unit
+```
+
+Integration tests use [Vitest](https://vitest.dev) and run against **an app that mounts the SDK routes** (e.g. AdminUI on `npm run dev`), which forwards to the Shopwave API. They cover create → read (by id and by filter) → update → delete with the typed functions for Products and Categories, create → read → role update → retire for Employees, read-only checks for Consumers, plus unknown ids and the legacy `submitEntity` body. They create and delete real records on the account behind the token.
 
 ### Environment Variables
 
 | Variable    | Description                          | Example                                   |
 |-------------|--------------------------------------|-------------------------------------------|
-| `API_URL`   | Base URL for the API                 | `https://api.staging.merchantstack.com`   |
-| `API_TOKEN` | Authentication token                 | `your-staging-token`                      |
+| `API_URL`   | Origin of the app with the SDK routes | `http://localhost:3000`                  |
+| `API_TOKEN` | Bare Shopwave access token (no `OAuth`/`Bearer` prefix) | `111ad…`                |
 
 ### Running Tests
 
 ```bash
 # Set environment variables
-export API_URL=https://api.staging.merchantstack.com
-export API_TOKEN=your-staging-token
+# with the app running (AdminUI: npm run dev)
+export API_URL=http://localhost:3000
+export API_TOKEN=<bare access token>
 
 # Run all integration tests
 npm run test:integration
 
-# Run tests in watch mode
+# Run unit tests
 npm test
 ```
 
@@ -247,6 +481,14 @@ npm test
 
 ```
 tests/
+  unit/
+    server.test.ts                 # OAuth client, tokens, returnTo/state
+    next.test.ts                   # Next.js handlers, refresh, proxy guard
+    session-client.test.ts         # fetchSession / loginPath / logoutPath
+    request.test.ts                # token header, ShopwaveApiError, no logging
+    entities.test.ts               # save/delete/fetch-by-id per entity
+    api-routes.test.ts             # /api route handlers
+    query-state.test.ts            # useQuery keeps data while refetching
   integration/
     setup.ts                       # Shared config and helpers
     products.integration.test.ts   # Products CRUD lifecycle