react-shopwave-connect 0.1.2 → 0.3.0

package/dist/index.js

@@ -1,88 +1,201 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useReducer, useState } from "react";
 
+//#region src/core/errors.ts
+/**
+* Thrown by every `core` function when a request fails, either at the HTTP
+* level (`status` is the HTTP status) or because the Shopwave response carried
+* `api.message.errors` (then `status` is the HTTP status of that response,
+* usually 200/201, and `errors` holds the API errors).
+*
+* Branch on `status` (e.g. `isUnauthorized` → send the user to log in) rather
+* than parsing `message`.
+*/
+var ShopwaveApiError = class extends Error {
+	/** HTTP status of the response (0 when the request never got a response). */
+	status;
+	/** Shopwave API errors, when the response carried any. */
+	errors;
+	/** Parsed response body, when there was one. */
+	body;
+	constructor(status, message, details = {}) {
+		super(message, details.cause !== void 0 ? { cause: details.cause } : void 0);
+		this.name = "ShopwaveApiError";
+		this.status = status;
+		this.errors = details.errors ?? null;
+		this.body = details.body;
+	}
+	/** 401, or the Shopwave "token expired / invalid" error 908. */
+	get isUnauthorized() {
+		if (this.status === 401) return true;
+		return !!this.errors && Object.entries(this.errors).some(([k, v]) => k === "908" || Number(v?.id) === 908);
+	}
+	get isNotFound() {
+		return this.status === 404;
+	}
+};
+/** The `api.message.errors` (or `api.message.error`) map of a Shopwave response, or `null` when there are none. */
+function getApiErrorMap(body) {
+	const message = body?.api?.message;
+	const errors = message?.errors ?? message?.error;
+	if (errors && typeof errors === "object" && Object.keys(errors).length > 0) return errors;
+	return null;
+}
+function describeErrors(errors) {
+	return Object.entries(errors).map(([code, e]) => {
+		const text = [e?.title, e?.details].filter(Boolean).join(": ");
+		return text ? `${code} ${text}` : code;
+	}).join("; ");
+}
+/**
+* Builds a {@link ShopwaveApiError} for a response. Understands the Shopwave
+* envelope (`api.message.errors`) and the `{ error, message }` bodies returned
+* by the `react-shopwave-connect/next` routes.
+*/
+function toShopwaveApiError(status, body, fallback) {
+	const errors = getApiErrorMap(body);
+	let detail = errors ? describeErrors(errors) : "";
+	if (!detail && body && typeof body === "object") {
+		const b = body;
+		if (typeof b.message === "string") detail = b.message;
+		else if (typeof b.error === "string") detail = b.error;
+	}
+	if (!detail) detail = fallback ?? (status >= 400 ? "request failed" : "API returned errors");
+	return new ShopwaveApiError(status, `Shopwave API error (${status}): ${detail}`, {
+		errors,
+		body
+	});
+}
+/** Throws a {@link ShopwaveApiError} when the response body carries API errors. */
+function assertNoApiErrors(body, status) {
+	if (getApiErrorMap(body)) throw toShopwaveApiError(status, body);
+}
+
+//#endregion
 //#region src/core/request.ts
 function resolveFetch(options) {
 	const f = options.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
 	if (!f) throw new Error("No fetch implementation available. Pass `options.fetch` (e.g. node-fetch / undici) when running outside the browser.");
 	return f;
 }
-function buildExtras(extras, options) {
+/** Options with `token` filled in from a legacy per-call `params.token`, unless `options.token` is set. */
+function withToken(options, token) {
+	return token && !options.token ? {
+		...options,
+		token
+	} : options;
+}
+/** `Authorization` header value for a token (`OAuth <token>` unless it already has a scheme). */
+function authorizationFor(token) {
+	const t = token.trim();
+	return /^(oauth|bearer)\s+\S/i.test(t) ? t : `OAuth ${t}`;
+}
+/** Headers shared by every request: Accept + the token, when one is given. */
+function baseHeaders(options) {
+	const headers = { Accept: "application/json" };
+	if (options.token) headers.Authorization = authorizationFor(options.token);
+	return headers;
+}
+function buildExtras(extras) {
 	const merged = {
 		"Content-Type": "application/json",
 		...extras
 	};
-	if (options.token != null && merged.token == null) merged.token = options.token;
+	delete merged.token;
 	return merged;
 }
+/** Parses a response body as JSON; `null` for an empty body, `{ raw }` for non-JSON. */
+async function readBody(response) {
+	const text = await response.text();
+	if (!text) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return { raw: text };
+	}
+}
+/**
+* Low-level request: resolves `{ status, body }` for 2xx responses and throws
+* {@link ShopwaveApiError} otherwise. `init.headers` are merged over the
+* standard ones (Accept + Authorization).
+*/
+async function apiRequest(path, init, options = {}) {
+	return send(path, {
+		...init,
+		headers: {
+			...baseHeaders(options),
+			...init.headers
+		}
+	}, options);
+}
+async function send(path, init, options) {
+	const doFetch = resolveFetch(options);
+	const url = (options.baseUrl ?? "") + path;
+	let response;
+	try {
+		response = await doFetch(url, {
+			...init,
+			signal: options.signal
+		});
+	} catch (error) {
+		if (error?.name === "AbortError") throw error;
+		throw new ShopwaveApiError(0, `Shopwave API request failed: ${error?.message ?? error}`, { cause: error });
+	}
+	const body = await readBody(response);
+	if (!response.ok) throw toShopwaveApiError(response.status, body, response.statusText || void 0);
+	return {
+		status: response.status,
+		body
+	};
+}
 /**
 * Returns a JSON string of API errors if the response carries any, otherwise
-* `null`. Mirrors the original `!responseJson.api.message.errors` checks.
+* `null`. Kept for backwards compatibility; prefer `ShopwaveApiError`.
 */
 function getApiErrors(api) {
-	const errors = api?.message?.errors;
-	if (errors && Object.keys(errors).length > 0) return JSON.stringify(errors);
-	return null;
+	const errors = getApiErrorMap({ api });
+	return errors ? JSON.stringify(errors) : null;
 }
 /**
-* GET helper. Sends request metadata via the `extras` header exactly like the
-* original hooks did, parses JSON, and returns the typed payload.
+* GET helper. Sends request metadata via the `extras` header, parses JSON and
+* returns the payload. Throws {@link ShopwaveApiError} for non-2xx responses.
 */
 async function apiGet(path, extras, options = {}) {
-	const doFetch = resolveFetch(options);
-	const url = (options.baseUrl ?? "") + path;
-	const headers = { extras: JSON.stringify(buildExtras(extras, options)) };
-	console.log("[API GET]", {
-		url,
-		headers
-	});
-	const response = await doFetch(url, {
+	const { body } = await send(path, {
 		method: "GET",
-		headers,
-		signal: options.signal
-	});
-	if (!response.ok) throw new Error(`Network response was not ok (${response.status})`);
-	return await response.json();
+		headers: {
+			...baseHeaders(options),
+			extras: JSON.stringify(buildExtras(extras))
+		}
+	}, options);
+	return body;
 }
 /**
-* JSON body helper for POST/PUT mutations.
+* JSON body helper for POST/PUT mutations. Returns the parsed body (`null` for
+* an empty one). Throws {@link ShopwaveApiError} for non-2xx responses.
 */
 async function apiSend(path, method, payload, options = {}) {
-	const doFetch = resolveFetch(options);
-	const url = (options.baseUrl ?? "") + path;
-	const headers = { "Content-Type": "application/json" };
-	if (options.token != null) headers.token = options.token;
-	console.log(`[API ${method}]`, {
-		url,
-		headers,
-		payload
-	});
-	const response = await doFetch(url, {
+	const { body } = await send(path, {
 		method,
-		headers,
-		body: JSON.stringify(payload),
-		signal: options.signal
-	});
-	if (!response.ok) throw new Error(`Failed to ${method.toLowerCase()}: ${response.statusText}`);
-	return await response.json();
+		headers: {
+			...baseHeaders(options),
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify(payload)
+	}, options);
+	return body;
 }
 /**
-* DELETE helper.
+* DELETE helper. Shopwave answers deletes with 205 and an empty body; if a body
+* does come back and carries API errors, they are thrown. Returns the parsed
+* body (`null` when empty).
 */
 async function apiDelete(path, options = {}) {
-	const doFetch = resolveFetch(options);
-	const url = (options.baseUrl ?? "") + path;
-	const headers = {};
-	if (options.token != null) headers.token = options.token;
-	console.log("[API DELETE]", {
-		url,
-		headers
-	});
-	const response = await doFetch(url, {
+	const { status, body } = await send(path, {
 		method: "DELETE",
-		headers,
-		signal: options.signal
-	});
-	if (!response.ok) throw new Error(`Failed to delete: ${response.statusText}`);
+		headers: baseHeaders(options)
+	}, options);
+	if (getApiErrorMap(body)) throw toShopwaveApiError(status, body);
+	return body;
 }
 
 //#endregion
@@ -94,11 +207,9 @@ async function apiDelete(path, options = {}) {
 async function fetchCategories(params = {}, options = {}) {
 	const extras = { deleted: params.deleted ?? false };
 	if (params.categoryIds) extras.categoryIds = params.categoryIds;
-	if (params.token) extras.token = params.token;
-	const json = await apiGet("/api/categories", extras, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.categories ?? {});
+	const json = await apiGet("/api/categories", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.categories ?? {});
 }
 
 //#endregion
@@ -110,9 +221,8 @@ async function fetchCategories(params = {}, options = {}) {
 async function fetchConsumers(consumerIds, options = {}) {
 	if (!consumerIds || consumerIds.length === 0) return [];
 	const json = await apiGet("/api/consumer", { ids: consumerIds.join(",") }, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.consumers ?? {});
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.consumers ?? {});
 }
 
 //#endregion
@@ -130,10 +240,9 @@ const rolesById = {
 async function fetchEmployees(params = {}, options = {}) {
 	const extras = { deleted: params.deleted ?? false };
 	if (params.employeeIds) extras.employeeIds = params.employeeIds;
-	const json = await apiGet("/api/employees", extras, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.employees ?? {});
+	const json = await apiGet("/api/employees", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.employees ?? {});
 }
 
 //#endregion
@@ -145,11 +254,9 @@ async function fetchProducts(params = {}, options = {}) {
 	const extras = { deleted: params.deleted ?? false };
 	if (params.productIds) extras.productIds = params.productIds;
 	if (params.storeId) extras.storeId = params.storeId;
-	if (params.token) extras.token = params.token;
-	const json = await apiGet("/api/products", extras, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.products ?? {});
+	const json = await apiGet("/api/products", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.products ?? {});
 }
 /**
 * Fetches products by id and returns them keyed by id, transparently batching
@@ -185,11 +292,9 @@ async function fetchPromotions(params = {}, options = {}) {
 	if (params.imminent !== void 0) extras.imminent = params.imminent;
 	if (params.active !== void 0) extras.active = params.active;
 	if (params.expired !== void 0) extras.expired = params.expired;
-	if (params.token) extras.token = params.token;
-	const json = await apiGet("/api/promotions", extras, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.promotions ?? {});
+	const json = await apiGet("/api/promotions", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.promotions ?? {});
 }
 
 //#endregion
@@ -198,10 +303,11 @@ async function fetchPromotions(params = {}, options = {}) {
 * Fetches stores. Returns the flattened `Store[]`.
 */
 async function fetchStores(params = {}, options = {}) {
-	const json = await apiGet("/api/stores", { deleted: params.deleted ?? false }, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return Object.values(json.stores ?? {});
+	const extras = { deleted: params.deleted ?? false };
+	if (params.storeIds) extras.storeIds = params.storeIds;
+	const json = await apiGet("/api/stores", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.stores ?? {});
 }
 
 //#endregion
@@ -213,20 +319,54 @@ async function fetchStores(params = {}, options = {}) {
 */
 async function fetchReport(query, options = {}) {
 	const json = await apiGet("/api/report", { query: JSON.stringify(query) }, options);
-	const error = getApiErrors(json.api);
-	if (error) throw new Error(error);
-	return json.reports ?? {};
+	assertNoApiErrors(json, 200);
+	return json?.reports ?? {};
 }
 
 //#endregion
 //#region src/core/session.ts
 /**
-* Ends the current server session.
+* Reads the current login status from `GET /api/session`.
+*
+* Works with the new `react-shopwave-connect/next` session route
+* (`{ loggedIn }`) and with older routes that returned the raw session
+* (`{ token: {...} }`) — in that case only a boolean is surfaced.
+*/
+async function fetchSession(options = {}) {
+	const doFetch = options.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
+	if (!doFetch) throw new Error("No fetch implementation available. Pass `options.fetch`.");
+	const response = await doFetch(`${options.baseUrl ?? ""}/api/session`, {
+		method: "GET",
+		headers: { Accept: "application/json" },
+		cache: "no-store",
+		credentials: "same-origin",
+		signal: options.signal
+	});
+	if (response.status === 401) return { loggedIn: false };
+	if (!response.ok) throw new Error(`Session request failed (${response.status})`);
+	const json = await response.json();
+	if (json && typeof json.loggedIn === "boolean") return {
+		loggedIn: json.loggedIn,
+		expiresAt: typeof json.expiresAt === "number" ? json.expiresAt : void 0
+	};
+	return { loggedIn: Boolean(json && json.token) };
+}
+/**
+* Path that starts a login and returns to `returnTo` afterwards.
+* Navigate the browser to it (`window.location.href = loginPath(...)`).
+*/
+function loginPath(returnTo, authPath = "/auth") {
+	return returnTo ? `${authPath}?returnTo=${encodeURIComponent(returnTo)}` : authPath;
+}
+/** Path that logs out of the app and the Shopwave auth server. */
+function logoutPath(authPath = "/auth") {
+	return `${authPath}/logout`;
+}
+/**
+* Ends the current server session (no redirect).
 *
-* This is the framework-agnostic half of the original `useLogout` hook. The
-* Next.js-specific redirect logic (router.push to the auth server logout URL,
-* built from server actions) is intentionally NOT included here because it is
-* tied to `next/navigation` and `'use server'` actions — see the README.
+* Prefer navigating to {@link logoutPath} when using
+* `react-shopwave-connect/next`: it also signs the user out of the auth server.
 */
 async function logout(options = {}) {
 	await apiDelete("/api/session?action=logout", options);
@@ -235,10 +375,12 @@ async function logout(options = {}) {
 //#endregion
 //#region src/core/entity.ts
 /**
-* Generic CRUD-style mutations extracted from `useHandleDelete` /
-* `useHandleSubmit`. The original hooks also surfaced notistack snackbars; that
-* UI concern is deliberately left to the hooks/host layer so core stays
-* dependency-free.
+* Low-level, untyped mutations: the caller supplies the route and payload.
+*
+* Prefer the typed functions in `./entities` (`saveProduct`, `deleteCategory`,
+* …): they know each route, build the request envelope, check the response and
+* return the saved entity with its id. Keep these for routes that have no typed
+* function yet (e.g. `/api/merchant`).
 */
 /**
 * Deletes `/api/{resourcePath}/{entityId}`.
@@ -248,13 +390,182 @@ async function deleteEntity(resourcePath, entityId, options = {}) {
 	await apiDelete(`/api/${resourcePath}/${entityId}`, options);
 }
 /**
-* Sends a create/update mutation and returns the parsed `result` field
-* (matching the original `result.result` access).
+* Sends a create/update mutation. Returns the response's `result` field when it
+* has one (older app routes wrapped their answer that way), otherwise the whole
+* parsed response body. Throws `ShopwaveApiError` on HTTP or API errors.
 */
 async function submitEntity({ endpoint, method = "POST", payload }, options = {}) {
-	return (await apiSend(endpoint, method, payload, options)).result;
+	const json = await apiSend(endpoint, method, payload, options);
+	assertNoApiErrors(json, 200);
+	if (json && typeof json === "object" && "result" in json) return json.result;
+	return json ?? void 0;
 }
 
+//#endregion
+//#region src/core/entities.ts
+/**
+* Addressing per entity, following the Shopwave API reference
+* (https://developer.merchantstack.com/api-reference.html) and checked against
+* the live API where noted:
+* - category/product/store: GET filtered by `<x>Ids`, POST upsert, DELETE with `<x>Id` → 205.
+* - promotion: no DELETE; "deleting" a promotion ends it by setting `endDate` to now.
+* - employee: POST updates `roleId`, `joinedDate`, `exitDate` (names can't be
+*   changed); no DELETE (live API: "Cannot DELETE /employee") → retired via `exitDate`.
+* - consumer: read-only (`GET` with `ids`, comma-separated); live POST → 404.
+*/
+const SHOPWAVE_ENTITIES = Object.freeze({
+	product: {
+		route: "products",
+		collection: "products",
+		upstream: "product",
+		idsHeader: "productIds",
+		idHeader: "productId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	category: {
+		route: "categories",
+		collection: "categories",
+		upstream: "category",
+		idsHeader: "categoryIds",
+		idHeader: "categoryId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	store: {
+		route: "stores",
+		collection: "stores",
+		upstream: "store",
+		idsHeader: "storeIds",
+		idHeader: "storeId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	promotion: {
+		route: "promotions",
+		collection: "promotions",
+		upstream: "promotion",
+		idsHeader: "promotionIds",
+		idHeader: "promotionId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "endDate"
+	},
+	employee: {
+		route: "employees",
+		collection: "employees",
+		upstream: "employee",
+		idsHeader: "employeeIds",
+		idHeader: "employeeId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "exitDate"
+	},
+	consumer: {
+		route: "consumer",
+		collection: "consumers",
+		upstream: "consumer",
+		idsHeader: "ids",
+		idHeader: "consumerId",
+		writable: false,
+		deleteMode: "none"
+	}
+});
+function definition(kind) {
+	const def = SHOPWAVE_ENTITIES[kind];
+	if (!def) throw new Error(`Unknown Shopwave entity "${kind}"`);
+	return def;
+}
+function assertId(kind, id) {
+	const s = id == null ? "" : String(id).trim();
+	if (!s) throw new Error(`${kind} id is missing`);
+	return encodeURIComponent(s);
+}
+/**
+* Creates or updates several entities of one kind in a single request and
+* returns them as saved (with their ids), in the order given.
+*
+* The request is `{ <collection>: { "0": item0, "1": item1, … } }`. Shopwave
+* answers 201 and echoes every entity under the ref it was sent with, so each
+* result is matched back by ref. Throws {@link ShopwaveApiError} when the
+* response carries `api.message.errors` or any ref is missing from it.
+*
+* The API's partial-success semantics for multi-entity saves haven't been
+* confirmed yet; single saves (`saveProduct` etc.) are the tested path.
+*/
+async function saveEntities(kind, items, options = {}) {
+	const def = definition(kind);
+	if (items.length === 0) return [];
+	const refs = items.map((_, i) => String(i));
+	const payload = { [def.collection]: Object.fromEntries(refs.map((ref, i) => [ref, items[i]])) };
+	const { status, body: raw } = await apiRequest(`/api/${def.route}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(payload)
+	}, options);
+	const body = raw;
+	assertNoApiErrors(body, status);
+	const echoed = body?.[def.collection] ?? {};
+	return refs.map((ref, i) => {
+		const saved = echoed[ref];
+		if (!saved || saved.id == null) throw new ShopwaveApiError(status, `Shopwave API error (${status}): the saved ${kind} (ref "${ref}") was not returned`, { body });
+		return {
+			...items[i],
+			...saved,
+			id: Number(saved.id)
+		};
+	});
+}
+/** Creates (no `id`) or updates (with `id`) one entity and returns it with its id. */
+async function saveEntity(kind, item, options = {}) {
+	const [saved] = await saveEntities(kind, [item], options);
+	return saved;
+}
+/**
+* Deletes one entity (a soft delete: it stays readable with `deleted: true`).
+* Employees and promotions can't be deleted in Shopwave; for them the route
+* sets `exitDate` / `endDate` to now instead (see `SHOPWAVE_ENTITIES`).
+*
+* Shopwave answers 205 with an empty body — also for ids that don't exist — so
+* a resolved promise means "the API accepted the request", not "a record was
+* deleted".
+*/
+async function deleteEntityById(kind, id, options = {}) {
+	await apiDelete(`/api/${definition(kind).route}/${assertId(kind, id)}`, options);
+}
+/** Reads one entity by id, or `null` when there's no such (non-deleted) record. */
+async function fetchEntityById(kind, id, params = {}, options = {}) {
+	const def = definition(kind);
+	const body = await apiGet(`/api/${def.route}/${assertId(kind, id)}`, { deleted: params.deleted ?? false }, options);
+	assertNoApiErrors(body, 200);
+	const map = body?.[def.collection] ?? {};
+	return map[String(id)] ?? Object.values(map).find((e) => String(e?.id) === String(id)) ?? null;
+}
+const saveProduct = (product, options) => saveEntity("product", product, options);
+const deleteProduct = (id, options) => deleteEntityById("product", id, options);
+const fetchProduct = (id, params, options) => fetchEntityById("product", id, params, options);
+const saveCategory = (category, options) => saveEntity("category", category, options);
+const deleteCategory = (id, options) => deleteEntityById("category", id, options);
+const fetchCategory = (id, params, options) => fetchEntityById("category", id, params, options);
+const saveStore = (store, options) => saveEntity("store", store, options);
+const deleteStore = (id, options) => deleteEntityById("store", id, options);
+const fetchStore = (id, params, options) => fetchEntityById("store", id, params, options);
+const savePromotion = (promotion, options) => saveEntity("promotion", promotion, options);
+/** Ends a promotion: Shopwave has no promotion DELETE, so this sets `endDate` to now. */
+const deletePromotion = (id, options) => deleteEntityById("promotion", id, options);
+const fetchPromotion = (id, params, options) => fetchEntityById("promotion", id, params, options);
+/**
+* Creates an employee, or updates one (with `id`). On update Shopwave only
+* applies `roleId`, `joinedDate` and `exitDate` (and store roles); names and
+* email can't be changed, and the echo only carries the updated fields — re-read
+* with `fetchEmployee` if you need the stored record.
+*/
+const saveEmployee = (employee, options) => saveEntity("employee", employee, options);
+/** Retires an employee: Shopwave has no employee DELETE, so this sets `exitDate` to now. */
+const deleteEmployee = (id, options) => deleteEntityById("employee", id, options);
+const fetchEmployee = (id, params, options) => fetchEntityById("employee", id, params, options);
+const fetchConsumer = (id, params, options) => fetchEntityById("consumer", id, params, options);
+
 //#endregion
 //#region src/core/basket.ts
 const DEFAULT_BASKET_FILTERS = {
@@ -405,50 +716,127 @@ function toMessage(e) {
 	if (e instanceof Error) return e.message;
 	return String(e);
 }
+function toStatus(e) {
+	return e instanceof ShopwaveApiError ? e.status : null;
+}
+function queryReducer(state, action) {
+	switch (action.type) {
+		case "start":
+			if (action.key !== state.key) return {
+				data: null,
+				key: action.key,
+				fetching: true,
+				error: null,
+				errorStatus: null
+			};
+			return {
+				...state,
+				fetching: true,
+				error: null,
+				errorStatus: null
+			};
+		case "success":
+			if (action.key !== state.key) return state;
+			return {
+				data: action.data,
+				key: action.key,
+				fetching: false,
+				error: null,
+				errorStatus: null
+			};
+		case "failure":
+			if (action.key !== state.key) return state;
+			return {
+				...state,
+				fetching: false,
+				error: action.error,
+				errorStatus: action.errorStatus
+			};
+		case "idle": return state.fetching ? {
+			...state,
+			fetching: false
+		} : state;
+		default: return state;
+	}
+}
+/** Public view of the internal state for the params currently being rendered. */
+function selectQueryView(state, key, enabled) {
+	if (state.key !== key) return {
+		data: null,
+		loading: enabled,
+		fetching: enabled,
+		error: null,
+		errorStatus: null
+	};
+	return {
+		data: state.data,
+		loading: state.fetching && state.data === null,
+		fetching: state.fetching,
+		error: state.error,
+		errorStatus: state.errorStatus
+	};
+}
+function depsKey(deps) {
+	try {
+		return JSON.stringify(deps);
+	} catch {
+		return String(deps);
+	}
+}
 /**
 * Internal primitive powering the auto-fetch hooks. Runs `fetcher` on mount and
 * whenever `deps` change, tracks loading/error/data, cancels in-flight requests
-* on unmount or dep change, and exposes `refetch`.
+* on unmount or dep change, and exposes `refetch` (which keeps the current data
+* visible until the new data arrives).
 *
 * When `enabled` is false the fetch is skipped (used for hooks that need
 * arguments before they can run, e.g. consumers-by-id).
 */
 function useQuery(fetcher, deps, enabled = true) {
-	const [data, setData] = useState(null);
-	const [loading, setLoading] = useState(enabled);
-	const [error, setError] = useState(null);
+	const key = depsKey(deps);
+	const [state, dispatch] = useReducer(queryReducer, {
+		data: null,
+		key: enabled ? key : null,
+		fetching: enabled,
+		error: null,
+		errorStatus: null
+	});
 	const [tick, setTick] = useState(0);
 	const refetch = useCallback(() => setTick((t) => t + 1), []);
 	useEffect(() => {
 		if (!enabled) {
-			setLoading(false);
+			dispatch({ type: "idle" });
 			return;
 		}
 		const controller = new AbortController();
-		let active = true;
-		setData(null);
-		setError(null);
-		setLoading(true);
+		dispatch({
+			type: "start",
+			key
+		});
 		fetcher(controller.signal).then((result) => {
-			if (active) setData(result);
+			if (!controller.signal.aborted) dispatch({
+				type: "success",
+				key,
+				data: result
+			});
 		}).catch((e) => {
-			if (active && e?.name !== "AbortError") setError(toMessage(e));
-		}).finally(() => {
-			if (active) setLoading(false);
+			if (!controller.signal.aborted && e?.name !== "AbortError") dispatch({
+				type: "failure",
+				key,
+				error: toMessage(e),
+				errorStatus: toStatus(e)
+			});
 		});
 		return () => {
-			active = false;
 			controller.abort();
 		};
 	}, [
-		...deps,
+		key,
 		tick,
 		enabled
 	]);
 	return {
-		data,
-		loading,
-		error,
+		...selectQueryView(state, key, enabled),
 		refetch
 	};
 }
@@ -459,16 +847,19 @@ function useMutation(action, deps) {
 	const [data, setData] = useState(null);
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState(null);
+	const [errorStatus, setErrorStatus] = useState(null);
 	return {
 		mutate: useCallback(async (...args) => {
 			setLoading(true);
 			setError(null);
+			setErrorStatus(null);
 			try {
 				const result = await action(...args);
 				setData(result);
 				return result;
 			} catch (e) {
 				setError(toMessage(e));
+				setErrorStatus(toStatus(e));
 				return null;
 			} finally {
 				setLoading(false);
@@ -476,7 +867,8 @@ function useMutation(action, deps) {
 		}, deps),
 		data,
 		loading,
-		error
+		error,
+		errorStatus
 	};
 }
 
@@ -658,6 +1050,23 @@ function useLogout(options) {
 	return useMutation(() => logout(options), [options?.baseUrl, options?.token]);
 }
 
+//#endregion
+//#region src/hooks/useSession.ts
+/**
+* Current login status (`{ loggedIn, expiresAt }`) from `GET /api/session`.
+* Tokens are never exposed to the browser.
+*
+* @example
+* const { data: session, loading } = useSession();
+* if (!loading && !session?.loggedIn) window.location.href = loginPath(location.pathname);
+*/
+function useSession(options) {
+	return useQuery((signal) => fetchSession({
+		...options,
+		signal
+	}), [options?.baseUrl]);
+}
+
 //#endregion
 //#region src/hooks/useBasketReport.ts
 /**
@@ -762,5 +1171,5 @@ function useBasketReport(options) {
 }
 
 //#endregion
-export { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, PromotionRuleSet, apiDelete, apiGet, apiSend, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, deleteEntity, fetchCategories, fetchConsumers, fetchEmployees, fetchProducts, fetchProductsMap, fetchPromotions, fetchReport, fetchStores, formatDateForQuery, getApiErrors, logout, parseBasketReportData, rolesById, submitEntity, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useStore, useSubmit };
+export { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, PromotionRuleSet, SHOPWAVE_ENTITIES, ShopwaveApiError, apiDelete, apiGet, apiRequest, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchProduct, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, formatDateForQuery, getApiErrorMap, getApiErrors, loginPath, logout, logoutPath, parseBasketReportData, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, submitEntity, toShopwaveApiError, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, withToken };
 //# sourceMappingURL=index.js.map