react-shopwave-connect 0.2.0 → 0.4.0

package/dist/core/index.cjs

@@ -1,87 +1,200 @@
 
+//#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
@@ -93,11 +206,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
@@ -109,9 +220,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
@@ -129,10 +239,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
@@ -144,11 +253,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
@@ -184,11 +291,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
@@ -197,10 +302,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
@@ -212,9 +318,8 @@ 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
@@ -269,10 +374,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}`.
@@ -282,13 +389,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 = {
@@ -433,35 +709,574 @@ function buildConsumerMap(consumers) {
 	return map;
 }
 
+//#endregion
+//#region src/core/resources.ts
+/**
+* - merchant: `GET /merchant`; `POST /merchant` with `{ merchant: { id, … } }`
+*   updates it (without an `id` the API would create a second merchant, so the
+*   route requires one).
+* - user: `GET /user` (read-only here; the API's `POST /user` invites users and
+*   needs the admin scope).
+*/
+const SHOPWAVE_RESOURCES = Object.freeze({
+	merchant: {
+		route: "merchant",
+		key: "merchant",
+		upstream: "merchant",
+		writable: true
+	},
+	user: {
+		route: "user",
+		key: "user",
+		upstream: "user",
+		writable: false
+	}
+});
+/** `UploadKind` → the API's `contentType` value. */
+const UPLOAD_KINDS = Object.freeze({
+	merchant: "merchant",
+	merchantFeature: "merchantFeature",
+	product: "product",
+	user: "user",
+	applicationLogo: "applicaionLogo",
+	applicationImages: "applicaionImages"
+});
+/** How uploads are addressed (app route and Shopwave uploader). */
+const SHOPWAVE_UPLOAD = Object.freeze({
+	route: "upload",
+	upstream: "uploader",
+	kindHeader: "contentType",
+	fileField: "file",
+	kindField: "kind"
+});
+function isUploadKind(value) {
+	return typeof value === "string" && Object.prototype.hasOwnProperty.call(UPLOAD_KINDS, value);
+}
+
+//#endregion
+//#region src/core/imageFit.ts
+/**
+* The centred part of a `srcWidth × srcHeight` image with the aspect ratio of
+* `dstWidth × dstHeight` (like CSS `object-fit: cover`).
+*/
+function coverCrop(srcWidth, srcHeight, dstWidth, dstHeight) {
+	if (![
+		srcWidth,
+		srcHeight,
+		dstWidth,
+		dstHeight
+	].every((n) => Number.isFinite(n) && n > 0)) throw new Error("coverCrop: sizes must be positive numbers");
+	const srcRatio = srcWidth / srcHeight;
+	const dstRatio = dstWidth / dstHeight;
+	if (srcRatio > dstRatio) {
+		const sw = Math.round(srcHeight * dstRatio);
+		return {
+			sx: Math.round((srcWidth - sw) / 2),
+			sy: 0,
+			sw,
+			sh: srcHeight
+		};
+	}
+	const sh = Math.round(srcWidth / dstRatio);
+	return {
+		sx: 0,
+		sy: Math.round((srcHeight - sh) / 2),
+		sw: srcWidth,
+		sh
+	};
+}
+function requireBrowserImages(fn) {
+	if (typeof createImageBitmap !== "function") throw new Error(`${fn} needs a browser (createImageBitmap is not available)`);
+}
+/** Reads an image file's pixel size (browser only). */
+async function readImageSize(file) {
+	requireBrowserImages("readImageSize");
+	const bitmap = await createImageBitmap(file);
+	try {
+		return {
+			width: bitmap.width,
+			height: bitmap.height
+		};
+	} finally {
+		bitmap.close?.();
+	}
+}
+/**
+* Returns the image at exactly `width × height`: scaled and centre-cropped
+* (never stretched). Browser only. The result is a `File` named like the
+* input, with the output type's extension.
+*/
+async function fitImageToSize(file, width, height, options = {}) {
+	requireBrowserImages("fitImageToSize");
+	const { type = "image/png", quality, keepIfExact = true } = options;
+	const name = file.name || "image";
+	const ext = type === "image/jpeg" ? "jpg" : type.split("/")[1];
+	const outName = `${name.replace(/\.[^.]+$/, "")}.${ext}`;
+	const bitmap = await createImageBitmap(file);
+	try {
+		if (keepIfExact && bitmap.width === width && bitmap.height === height && file.type === type) return file instanceof File ? file : new File([file], outName, { type });
+		const { sx, sy, sw, sh } = coverCrop(bitmap.width, bitmap.height, width, height);
+		let blob;
+		if (typeof OffscreenCanvas === "function") {
+			const canvas = new OffscreenCanvas(width, height);
+			const ctx = canvas.getContext("2d");
+			if (!ctx) throw new Error("fitImageToSize: no 2D canvas context");
+			ctx.imageSmoothingQuality = "high";
+			ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+			blob = await canvas.convertToBlob({
+				type,
+				quality
+			});
+		} else {
+			const canvas = document.createElement("canvas");
+			canvas.width = width;
+			canvas.height = height;
+			const ctx = canvas.getContext("2d");
+			if (!ctx) throw new Error("fitImageToSize: no 2D canvas context");
+			ctx.imageSmoothingQuality = "high";
+			ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+			blob = await new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(/* @__PURE__ */ new Error("fitImageToSize: encoding failed")), type, quality));
+		}
+		return new File([blob], outName, { type });
+	} finally {
+		bitmap.close?.();
+	}
+}
+
+//#endregion
+//#region src/core/upload.ts
+/**
+* HTTPS host that serves the Shopwave CDN's images. The API returns
+* `http://static.merchantstack.com/images/…`, which has no HTTPS endpoint
+* (checked Sep 2026), so pages served over HTTPS can't show it.
+*/
+const SHOPWAVE_IMAGE_BASE_URL = "https://s3-eu-west-1.amazonaws.com/static.merchantstack.com/images";
+const STATIC_HOST = /^https?:\/\/static\.merchantstack\.com\/images\//i;
+/**
+* Turns an image path from the API into a URL a page can load over HTTPS:
+* `http://static.merchantstack.com/images/x.png` → `<base>/x.png`, and a
+* relative path (`merchant/5644/logo/x.png`) → `<base>/merchant/5644/logo/x.png`.
+* Other absolute URLs are returned unchanged; empty input gives `""`.
+*/
+function getImageUrl(path, base = SHOPWAVE_IMAGE_BASE_URL) {
+	if (!path) return "";
+	const root = base.replace(/\/+$/, "");
+	if (STATIC_HOST.test(path)) return `${root}/${path.replace(STATIC_HOST, "")}`;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith("//")) return path;
+	return `${root}/${path.replace(/^\/+/, "")}`;
+}
+/**
+* Uploads one image to the Shopwave CDN through the app's `/api/upload` route
+* (`createShopwaveApi(...).upload()`), and returns its id and URL.
+*
+* The file only lands on the CDN (under `…/images/<kind>/<merchantId>/…`); a
+* record has to point at it to use it. Live API (Sep 2026): the upload answers
+* 201 `{ fileName, path }`.
+*/
+async function uploadImage(file, params, options = {}) {
+	if (!file || typeof file.size !== "number") throw new Error("uploadImage: file must be a File or Blob");
+	if (!isUploadKind(params?.kind)) throw new Error(`uploadImage: unknown kind "${params?.kind}"`);
+	const name = params.fileName ?? file.name ?? "upload";
+	const form = new FormData();
+	form.append(SHOPWAVE_UPLOAD.fileField, file, name);
+	form.append(SHOPWAVE_UPLOAD.kindField, params.kind);
+	const { status, body: raw } = await apiRequest(`/api/${SHOPWAVE_UPLOAD.route}`, {
+		method: "POST",
+		body: form
+	}, options);
+	const body = raw;
+	assertNoApiErrors(body, status);
+	const id = typeof body?.fileName === "string" ? body.fileName : "";
+	const path = typeof body?.path === "string" ? body.path : "";
+	if (!id) throw new ShopwaveApiError(status, `Shopwave API error (${status}): the upload response has no fileName`, { body });
+	return {
+		id,
+		url: getImageUrl(path),
+		path
+	};
+}
+
+//#endregion
+//#region src/core/merchantImages.ts
+/** The three image slots on the merchant settings page. */
+const MERCHANT_IMAGE_SLOT_KEYS = [
+	"receipt",
+	"square",
+	"featured"
+];
+/**
+* Where each slot lives, its upload kind and its exact size (from adminV1's
+* merchant settings page).
+*/
+const MERCHANT_IMAGE_SLOTS = Object.freeze({
+	receipt: {
+		field: "logo.receipt",
+		uploadKind: "merchant",
+		width: 576,
+		height: 325
+	},
+	square: {
+		field: "logo.square",
+		uploadKind: "merchant",
+		width: 1e3,
+		height: 1e3
+	},
+	featured: {
+		field: "feature[0]",
+		uploadKind: "merchantFeature",
+		width: 1200,
+		height: 600
+	}
+});
+/**
+* The file name in an image value: `"http://…/logo/abc.png"` → `"abc.png"`,
+* `"abc.png"` → `"abc.png"`. Query strings and fragments are ignored.
+* Returns `null` for empty or non-string values.
+*/
+function imageFileName(value) {
+	if (typeof value !== "string") return null;
+	const last = value.trim().replace(/[?#].*$/, "").split("/").pop() ?? "";
+	return last ? decodeURIComponent(last) : null;
+}
+/** The stored value for a slot (a URL when read from the API; a file name right after an upload). */
+function getMerchantImage(imageIds, slot) {
+	if (!imageIds || typeof imageIds !== "object") return null;
+	let value;
+	if (slot === "featured") value = Array.isArray(imageIds.feature) ? imageIds.feature[0] : void 0;
+	else {
+		const logo = imageIds.logo;
+		value = logo && typeof logo === "object" ? logo[slot] : void 0;
+	}
+	return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+/**
+* An HTTPS URL for a slot's stored image, or `""` when the slot is empty or
+* holds only a file name (a fresh upload not yet saved; use the upload's `url`).
+*/
+function getMerchantImageUrl(imageIds, slot, base) {
+	const value = getMerchantImage(imageIds, slot);
+	if (!value || !value.includes("/")) return "";
+	return getImageUrl(value, base);
+}
+/**
+* Returns a copy of `imageIds` with one slot set to `fileName` (or cleared
+* with `null`). Other slots and unknown keys are kept; an empty `logo` or
+* `feature` is removed.
+*/
+function setMerchantImage(imageIds, slot, fileName) {
+	const next = { ...imageIds && typeof imageIds === "object" ? imageIds : {} };
+	if (slot === "featured") {
+		const rest = Array.isArray(next.feature) ? next.feature.slice(1) : [];
+		const feature = fileName ? [fileName, ...rest] : rest;
+		if (feature.length > 0) next.feature = feature;
+		else delete next.feature;
+	} else {
+		const logo = { ...next.logo && typeof next.logo === "object" ? next.logo : {} };
+		if (fileName) logo[slot] = fileName;
+		else delete logo[slot];
+		if (Object.keys(logo).length > 0) next.logo = logo;
+		else delete next.logo;
+	}
+	return next;
+}
+function toStored(value) {
+	if (typeof value === "string") return imageFileName(value) ?? void 0;
+	if (Array.isArray(value)) {
+		const items = value.map(toStored).filter((v) => v !== void 0 && v !== null && v !== "");
+		return items.length > 0 ? items : void 0;
+	}
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [k, v] of Object.entries(value)) {
+			const stored = toStored(v);
+			if (stored !== void 0 && stored !== null && stored !== "") out[k] = stored;
+		}
+		return Object.keys(out).length > 0 ? out : void 0;
+	}
+}
+/**
+* The `imageIds` to send on a save: every URL is turned back into its file
+* name (what adminV1 does with images you didn't change) and empty values
+* are dropped. No images gives `{}`.
+*/
+function toStoredImageIds(imageIds) {
+	return toStored(imageIds) ?? {};
+}
+/**
+* Uploads an image for a merchant slot: fits it to the slot's size, uploads
+* it with the slot's kind, and returns `{ id, url, path }`. Put `id` into
+* `imageIds` with {@link setMerchantImage} and save with `updateMerchant`.
+*/
+async function uploadMerchantImage(file, slot, options = {}) {
+	const def = MERCHANT_IMAGE_SLOTS[slot];
+	if (!def) throw new Error(`uploadMerchantImage: unknown slot "${slot}"`);
+	const { fit = true, fitOptions,...requestOptions } = options;
+	return uploadImage(fit ? await fitImageToSize(file, def.width, def.height, fitOptions) : file, { kind: def.uploadKind }, requestOptions);
+}
+
+//#endregion
+//#region src/core/merchant.ts
+const MERCHANT_PATH = `/api/${SHOPWAVE_RESOURCES.merchant.route}`;
+/** Colour keys inside `colours.primary`, in display order. */
+const MERCHANT_COLOUR_KEYS = [
+	"main",
+	"highlight",
+	"contrast"
+];
+/** Flat link fields a form edits, in display order. */
+const MERCHANT_LINK_KEYS = [
+	"website",
+	"twitter",
+	"facebook",
+	"instagram"
+];
+/** Where each flat link field lives in `merchant.links`. */
+const MERCHANT_LINK_PATHS = Object.freeze({
+	website: ["website", "home"],
+	twitter: ["social", "twitter"],
+	facebook: ["social", "facebook"],
+	instagram: ["social", "instagram"]
+});
+function trimmed(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+/**
+* Reads `merchant.links` as flat fields (`{ website, twitter, facebook,
+* instagram }`), whatever shape it was saved in:
+* - the nested shape adminV1 saves (`{ website: { home }, social: { … } }`);
+* - flat keys (`{ website: "…" }`, what SDK 0.4.0 pre-releases sent);
+* - an array in {@link MERCHANT_LINK_KEYS} order (older AdminUI versions).
+* Empty values are dropped.
+*/
+function merchantLinksToForm(links) {
+	const out = {};
+	if (Array.isArray(links)) {
+		links.forEach((value, i) => {
+			const key = MERCHANT_LINK_KEYS[i];
+			const v = trimmed(value);
+			if (key && v) out[key] = v;
+		});
+		return out;
+	}
+	if (!links || typeof links !== "object") return out;
+	const obj = links;
+	for (const key of MERCHANT_LINK_KEYS) {
+		const [group, field] = MERCHANT_LINK_PATHS[key];
+		const nested = obj[group];
+		const v = nested && typeof nested === "object" && !Array.isArray(nested) ? trimmed(nested[field]) : trimmed(obj[key]);
+		if (v) out[key] = v;
+	}
+	return out;
+}
+/**
+* Builds the stored `links` object from flat fields. Empty values are left
+* out, and so is a group with nothing in it; no links gives `{}`.
+*/
+function merchantLinksFromForm(form) {
+	const out = {};
+	for (const key of MERCHANT_LINK_KEYS) {
+		const v = trimmed(form[key]);
+		if (!v) continue;
+		const [group, field] = MERCHANT_LINK_PATHS[key];
+		(out[group] ??= {})[field] = v;
+	}
+	return out;
+}
+/** Reads any stored or older `links` value into the nested shape adminV1 saves. */
+function normalizeMerchantLinks(links) {
+	return merchantLinksFromForm(merchantLinksToForm(links));
+}
+/**
+* Object fields of the merchant. The API keeps one you leave out, and
+* replaces it as a whole when you send it.
+*/
+const MERCHANT_OBJECT_FIELDS = [
+	"colours",
+	"links",
+	"imageIds"
+];
+/** Fields the API sets itself; `updateMerchant` never sends them back. */
+const MERCHANT_READ_ONLY_FIELDS = ["createdDate", "modifiedDate"];
+/**
+* Longest values the API stores. Longer values are cut off silently
+* (live API, Sep 2026), so `updateMerchant` rejects them instead.
+* `vatNumber` fits a UK VAT number without the `GB` prefix.
+*/
+const MERCHANT_FIELD_MAX_LENGTH = Object.freeze({
+	companyNumber: 11,
+	vatNumber: 9
+});
+/** Returns `"<field> is longer than <n> characters"` messages for over-long fields. */
+function validateMerchant(merchant) {
+	const problems = [];
+	for (const [field, max] of Object.entries(MERCHANT_FIELD_MAX_LENGTH)) {
+		const value = merchant[field];
+		if (typeof value === "string" && value.length > max) problems.push(`${field} is longer than ${max} characters`);
+	}
+	return problems;
+}
+/**
+* Reads the logged-in user's merchant (a user has exactly one), or `null`
+* when the API returns none.
+*/
+async function fetchMerchant(options = {}) {
+	const json = await apiGet(MERCHANT_PATH, {}, options);
+	assertNoApiErrors(json, 200);
+	return json?.merchant ?? null;
+}
+/**
+* Updates the merchant and returns it as stored.
+*
+* Shopwave's `POST /merchant` replaces the whole record: a scalar field you
+* leave out (`companyNumber`, `vatNumber`, `note`, …) is set to null, while
+* an object field you leave out (`colours`, `links`, `imageIds`) is kept and
+* one you send replaces the stored one; sending `{}` clears it (live API,
+* Sep 2026). So by default the
+* current merchant is read first and the patch is merged over it.
+*
+* `imageIds` is always sent as file names ({@link toStoredImageIds}), so you
+* can pass back what you read. See `MerchantImageIds` for the shape.
+*
+* The API answers 205 with an empty body, so the merchant is read again after
+* the save and that is what's returned (it shows exactly what was kept).
+* Throws before sending when a value is longer than the API stores
+* ({@link MERCHANT_FIELD_MAX_LENGTH}).
+*/
+async function updateMerchant(patch, options = {}) {
+	const { merge = true,...requestOptions } = options;
+	let merchant = { ...patch };
+	if (merge) {
+		const current = await fetchMerchant(requestOptions);
+		if (!current) throw new ShopwaveApiError(404, "Shopwave API error (404): no merchant to update");
+		if (patch.id != null && String(patch.id) !== String(current.id)) throw new Error(`Merchant id ${patch.id} is not the logged-in merchant (${current.id})`);
+		merchant = {
+			...current,
+			...patch,
+			id: current.id
+		};
+		for (const field of MERCHANT_OBJECT_FIELDS) if (!(field in patch)) delete merchant[field];
+	}
+	if (merchant.imageIds && typeof merchant.imageIds === "object") merchant.imageIds = toStoredImageIds(merchant.imageIds);
+	if (merchant.id == null || merchant.id === "") throw new Error("merchant id is missing");
+	for (const field of MERCHANT_READ_ONLY_FIELDS) delete merchant[field];
+	const problems = validateMerchant(merchant);
+	if (problems.length > 0) throw new Error(`Invalid merchant: ${problems.join("; ")}`);
+	const { status, body: raw } = await apiRequest(MERCHANT_PATH, {
+		method: "PUT",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ merchant })
+	}, requestOptions);
+	const body = raw;
+	assertNoApiErrors(body, status);
+	const echoed = body?.merchant && typeof body.merchant === "object" ? body.merchant : null;
+	if (echoed) return {
+		...merchant,
+		...echoed,
+		id: Number(echoed.id ?? merchant.id)
+	};
+	return await fetchMerchant(requestOptions) ?? {
+		...merchant,
+		id: Number(merchant.id)
+	};
+}
+
+//#endregion
+//#region src/core/user.ts
+/** Reads the logged-in user, or `null` when the API returns none. */
+async function fetchUser(options = {}) {
+	const json = await apiGet(`/api/${SHOPWAVE_RESOURCES.user.route}`, {}, options);
+	assertNoApiErrors(json, 200);
+	return json?.user ?? null;
+}
+
 //#endregion
 exports.DEFAULT_BASKET_FILTERS = DEFAULT_BASKET_FILTERS;
 exports.DEFAULT_PAGINATION = DEFAULT_PAGINATION;
+exports.MERCHANT_COLOUR_KEYS = MERCHANT_COLOUR_KEYS;
+exports.MERCHANT_FIELD_MAX_LENGTH = MERCHANT_FIELD_MAX_LENGTH;
+exports.MERCHANT_IMAGE_SLOTS = MERCHANT_IMAGE_SLOTS;
+exports.MERCHANT_IMAGE_SLOT_KEYS = MERCHANT_IMAGE_SLOT_KEYS;
+exports.MERCHANT_LINK_KEYS = MERCHANT_LINK_KEYS;
+exports.MERCHANT_LINK_PATHS = MERCHANT_LINK_PATHS;
+exports.MERCHANT_OBJECT_FIELDS = MERCHANT_OBJECT_FIELDS;
+exports.MERCHANT_READ_ONLY_FIELDS = MERCHANT_READ_ONLY_FIELDS;
 exports.PromotionRuleSet = PromotionRuleSet;
+exports.SHOPWAVE_ENTITIES = SHOPWAVE_ENTITIES;
+exports.SHOPWAVE_IMAGE_BASE_URL = SHOPWAVE_IMAGE_BASE_URL;
+exports.SHOPWAVE_RESOURCES = SHOPWAVE_RESOURCES;
+exports.SHOPWAVE_UPLOAD = SHOPWAVE_UPLOAD;
+exports.ShopwaveApiError = ShopwaveApiError;
+exports.UPLOAD_KINDS = UPLOAD_KINDS;
 exports.apiDelete = apiDelete;
 exports.apiGet = apiGet;
+exports.apiRequest = apiRequest;
 exports.apiSend = apiSend;
+exports.assertNoApiErrors = assertNoApiErrors;
+exports.authorizationFor = authorizationFor;
 exports.buildBasketReportQuery = buildBasketReportQuery;
 exports.buildConsumerMap = buildConsumerMap;
 exports.collectConsumerIds = collectConsumerIds;
 exports.collectProductIds = collectProductIds;
 exports.combineBasketRows = combineBasketRows;
 exports.computeBasketSummary = computeBasketSummary;
+exports.coverCrop = coverCrop;
+exports.deleteCategory = deleteCategory;
+exports.deleteEmployee = deleteEmployee;
 exports.deleteEntity = deleteEntity;
+exports.deleteEntityById = deleteEntityById;
+exports.deleteProduct = deleteProduct;
+exports.deletePromotion = deletePromotion;
+exports.deleteStore = deleteStore;
 exports.fetchCategories = fetchCategories;
+exports.fetchCategory = fetchCategory;
+exports.fetchConsumer = fetchConsumer;
 exports.fetchConsumers = fetchConsumers;
+exports.fetchEmployee = fetchEmployee;
 exports.fetchEmployees = fetchEmployees;
+exports.fetchEntityById = fetchEntityById;
+exports.fetchMerchant = fetchMerchant;
+exports.fetchProduct = fetchProduct;
 exports.fetchProducts = fetchProducts;
 exports.fetchProductsMap = fetchProductsMap;
+exports.fetchPromotion = fetchPromotion;
 exports.fetchPromotions = fetchPromotions;
 exports.fetchReport = fetchReport;
 exports.fetchSession = fetchSession;
+exports.fetchStore = fetchStore;
 exports.fetchStores = fetchStores;
+exports.fetchUser = fetchUser;
+exports.fitImageToSize = fitImageToSize;
 exports.formatDateForQuery = formatDateForQuery;
+exports.getApiErrorMap = getApiErrorMap;
 exports.getApiErrors = getApiErrors;
+exports.getImageUrl = getImageUrl;
+exports.getMerchantImage = getMerchantImage;
+exports.getMerchantImageUrl = getMerchantImageUrl;
+exports.imageFileName = imageFileName;
+exports.isUploadKind = isUploadKind;
 exports.loginPath = loginPath;
 exports.logout = logout;
 exports.logoutPath = logoutPath;
+exports.merchantLinksFromForm = merchantLinksFromForm;
+exports.merchantLinksToForm = merchantLinksToForm;
+exports.normalizeMerchantLinks = normalizeMerchantLinks;
 exports.parseBasketReportData = parseBasketReportData;
+exports.readImageSize = readImageSize;
 exports.rolesById = rolesById;
+exports.saveCategory = saveCategory;
+exports.saveEmployee = saveEmployee;
+exports.saveEntities = saveEntities;
+exports.saveEntity = saveEntity;
+exports.saveProduct = saveProduct;
+exports.savePromotion = savePromotion;
+exports.saveStore = saveStore;
+exports.setMerchantImage = setMerchantImage;
 exports.submitEntity = submitEntity;
+exports.toShopwaveApiError = toShopwaveApiError;
+exports.toStoredImageIds = toStoredImageIds;
+exports.updateMerchant = updateMerchant;
+exports.uploadImage = uploadImage;
+exports.uploadMerchantImage = uploadMerchantImage;
+exports.validateMerchant = validateMerchant;
+exports.withToken = withToken;
 //# sourceMappingURL=index.cjs.map