react-shopwave-connect 0.4.3 → 0.4.5

package/dist/index.cjs

@@ -407,17 +407,29 @@ const UPLOAD_KINDS = Object.freeze({
 	applicationLogo: "applicaionLogo",
 	applicationImages: "applicaionImages"
 });
+/** Every `UploadPrefix`, longest first so a name check never takes `product` for `product_thumbnail`. */
+const UPLOAD_PREFIXES = Object.freeze([
+	"product_thumbnail",
+	"variant_thumbnail",
+	"product",
+	"variant"
+]);
 /** How uploads are addressed (app route and Shopwave uploader). */
 const SHOPWAVE_UPLOAD = Object.freeze({
 	route: "upload",
 	upstream: "uploader",
 	kindHeader: "contentType",
+	prefixHeader: "prefix",
 	fileField: "file",
-	kindField: "kind"
+	kindField: "kind",
+	prefixField: "prefix"
 });
 function isUploadKind(value) {
 	return typeof value === "string" && Object.prototype.hasOwnProperty.call(UPLOAD_KINDS, value);
 }
+function isUploadPrefix(value) {
+	return typeof value === "string" && UPLOAD_PREFIXES.includes(value);
+}
 const SHOPWAVE_LOOKUPS = Object.freeze({
 	productTags: {
 		route: "products/tags",
@@ -584,22 +596,503 @@ async function logout(options = {}) {
 * function yet (e.g. `/api/merchant`).
 */
 /**
-* Deletes `/api/{resourcePath}/{entityId}`.
+* Deletes `/api/{resourcePath}/{entityId}`.
+*/
+async function deleteEntity(resourcePath, entityId, options = {}) {
+	if (entityId == null || entityId === "") throw new Error("entityId is missing");
+	await apiDelete(`/api/${resourcePath}/${entityId}`, options);
+}
+/**
+* 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 = {}) {
+	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/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?.();
+	}
+}
+/** Draws `crop` of the bitmap at `width × height` and encodes it (one resample). */
+async function drawCrop(bitmap, crop, width, height, type, quality, fn) {
+	const { sx, sy, sw, sh } = crop;
+	if (typeof OffscreenCanvas === "function") {
+		const canvas$1 = new OffscreenCanvas(width, height);
+		const ctx$1 = canvas$1.getContext("2d");
+		if (!ctx$1) throw new Error(`${fn}: no 2D canvas context`);
+		ctx$1.imageSmoothingQuality = "high";
+		ctx$1.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+		return canvas$1.convertToBlob({
+			type,
+			quality
+		});
+	}
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error(`${fn}: no 2D canvas context`);
+	ctx.imageSmoothingQuality = "high";
+	ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+	return new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(/* @__PURE__ */ new Error(`${fn}: encoding failed`)), type, quality));
+}
+/** The input's name with the output type's extension. */
+function outputName(file, type) {
+	const name = file.name || "image";
+	const ext = type === "image/jpeg" ? "jpg" : type.split("/")[1];
+	return `${name.replace(/\.[^.]+$/, "")}.${ext}`;
+}
+/**
+* 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 outName = outputName(file, type);
+	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 blob = await drawCrop(bitmap, coverCrop(bitmap.width, bitmap.height, width, height), width, height, type, quality, "fitImageToSize");
+		return new File([blob], outName, { type });
+	} finally {
+		bitmap.close?.();
+	}
+}
+/** A rule that can't be met by any image (a mistake in the rule, not the image). */
+var ImageRuleError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ImageRuleError";
+	}
+};
+/** The image is smaller than the rule's minimum (and `allowUpscale` is off). */
+var ImageTooSmallError = class extends Error {
+	/** The smallest size the rule accepts. */
+	required;
+	/** The largest area of the right shape the image could give. */
+	actual;
+	constructor(required, actual) {
+		super(`The image is too small: it needs to be at least ${required.width} × ${required.height}, and it's ${actual.width} × ${actual.height}`);
+		this.name = "ImageTooSmallError";
+		this.required = required;
+		this.actual = actual;
+	}
+};
+const isPositive = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/**
+* An aspect ratio as width ÷ height: `"100:77"`, `"100/77"`, `[100, 77]` →
+* 1.2987…; `1.3` → 1.3. Throws {@link ImageRuleError} for anything else.
+*/
+function parseAspectRatio(value) {
+	let parts = null;
+	if (typeof value === "number") return isPositive(value) ? value : badRatio(value);
+	if (Array.isArray(value)) parts = [value[0], value[1]];
+	else if (typeof value === "string") {
+		const text$1 = value.trim();
+		const match = /^(\d+(?:\.\d+)?)\s*[:/x×]\s*(\d+(?:\.\d+)?)$/i.exec(text$1);
+		if (match) parts = [Number(match[1]), Number(match[2])];
+		else if (/^\d+(?:\.\d+)?$/.test(text$1)) return isPositive(Number(text$1)) ? Number(text$1) : badRatio(value);
+	}
+	if (parts && isPositive(parts[0]) && isPositive(parts[1])) return parts[0] / parts[1];
+	return badRatio(value);
+}
+function badRatio(value) {
+	throw new ImageRuleError(`Not an aspect ratio: ${JSON.stringify(value)} (use e.g. "100:77", [100, 77] or 1.3)`);
+}
+/** Throws {@link ImageRuleError} when the rule contradicts itself. */
+function checkImageRule(rule) {
+	if (!rule || typeof rule !== "object") throw new ImageRuleError("An image rule must be an object");
+	for (const key of [
+		"width",
+		"height",
+		"minWidth",
+		"minHeight",
+		"maxWidth",
+		"maxHeight",
+		"maxLongSide"
+	]) if (rule[key] != null && !isPositive(rule[key])) throw new ImageRuleError(`${key} must be a positive number`);
+	if (rule.width != null || rule.height != null) {
+		if (rule.width == null || rule.height == null) throw new ImageRuleError("An exact size needs both width and height");
+		if (rule.aspectRatio != null) throw new ImageRuleError("Give an exact size or an aspectRatio, not both (the size sets the ratio)");
+		const extra = [
+			"minWidth",
+			"minHeight",
+			"maxWidth",
+			"maxHeight",
+			"maxLongSide"
+		].filter((key) => rule[key] != null);
+		if (extra.length > 0) throw new ImageRuleError(`An exact size is already the minimum and the maximum; remove ${extra.join(", ")}`);
+		return;
+	}
+	if (rule.aspectRatio != null) parseAspectRatio(rule.aspectRatio);
+	if (rule.minWidth != null && rule.maxWidth != null && rule.minWidth > rule.maxWidth) throw new ImageRuleError("minWidth is larger than maxWidth");
+	if (rule.minHeight != null && rule.maxHeight != null && rule.minHeight > rule.maxHeight) throw new ImageRuleError("minHeight is larger than maxHeight");
+	if (rule.maxLongSide != null && Math.max(rule.minWidth ?? 0, rule.minHeight ?? 0) > rule.maxLongSide) throw new ImageRuleError("The minimum size is larger than maxLongSide");
+}
+/**
+* Works out what to do to a `source`-sized image to meet `rule`: the centred
+* crop of the right shape (the largest one), then the output size (scaled
+* down to the maximum, never below the minimum). Pure: no browser needed.
+*
+* Throws {@link ImageTooSmallError} when the crop is below the minimum (or
+* the exact size) and `allowUpscale` is off, and {@link ImageRuleError} for a
+* contradictory rule.
+*
+* @example
+* planImageFit({ width: 6000, height: 4000 }, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 })
+* // → crop { sx: 403, sy: 0, sw: 5194, sh: 4000 }, 2000 × 1540
+*/
+function planImageFit(source, rule) {
+	checkImageRule(rule);
+	const { width: W, height: H } = source ?? {};
+	if (!isPositive(W) || !isPositive(H)) throw new Error("planImageFit: the image has no size");
+	const exact = rule.width != null && rule.height != null;
+	const ratio = exact ? rule.width / rule.height : rule.aspectRatio != null ? parseAspectRatio(rule.aspectRatio) : null;
+	const crop = ratio == null ? {
+		sx: 0,
+		sy: 0,
+		sw: W,
+		sh: H
+	} : coverCrop(W, H, ratio, 1);
+	const { sw, sh } = crop;
+	const kept = {
+		width: sw,
+		height: sh
+	};
+	let width;
+	let height;
+	if (exact) {
+		width = rule.width;
+		height = rule.height;
+		if ((sw < width || sh < height) && !rule.allowUpscale) throw new ImageTooSmallError({
+			width,
+			height
+		}, kept);
+	} else {
+		const minW = rule.minWidth ?? 0;
+		const minH = rule.minHeight ?? 0;
+		if ((sw < minW || sh < minH) && !rule.allowUpscale) throw new ImageTooSmallError(requiredSize(minW, minH, ratio), kept);
+		let scale = 1;
+		if (rule.maxWidth != null) scale = Math.min(scale, rule.maxWidth / sw);
+		if (rule.maxHeight != null) scale = Math.min(scale, rule.maxHeight / sh);
+		if (rule.maxLongSide != null) scale = Math.min(scale, rule.maxLongSide / Math.max(sw, sh));
+		scale = Math.max(scale, minW / sw, minH / sh);
+		width = Math.max(1, Math.round(sw * scale));
+		height = Math.max(1, Math.round(sh * scale));
+	}
+	const unchanged = crop.sx === 0 && crop.sy === 0 && sw === W && sh === H && width === W && height === H;
+	return {
+		crop,
+		width,
+		height,
+		unchanged
+	};
+}
+/** The minimum as a full size: a ratio rule with only one minimum implies the other. */
+function requiredSize(minW, minH, ratio) {
+	if (ratio == null) return {
+		width: minW,
+		height: minH
+	};
+	return {
+		width: Math.max(minW, Math.ceil(minH * ratio)),
+		height: Math.max(minH, Math.ceil(minW / ratio))
+	};
+}
+const OUTPUT_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp"
+];
+/**
+* Returns the image meeting `rule` ({@link planImageFit}): centre-cropped to
+* the right shape and scaled in a single draw. An image that already fits is
+* returned untouched (same bytes). Browser only.
+*
+* Throws {@link ImageTooSmallError} (show `required` and `actual` to the
+* person) or {@link ImageRuleError}; an unreadable file rejects with the
+* browser's decoding error.
+*
+* @example
+* const ready = await prepareImage(file, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 });
+* await uploadImage(ready, { kind: "product", prefix: "product" });
+*/
+async function prepareImage(file, rule, options = {}) {
+	checkImageRule(rule);
+	requireBrowserImages("prepareImage");
+	const sourceType = file.type && OUTPUT_TYPES.includes(file.type) ? file.type : "image/png";
+	const type = options.type ?? sourceType;
+	const quality = options.quality ?? (type === "image/png" ? void 0 : .9);
+	const bitmap = await createImageBitmap(file);
+	try {
+		const plan = planImageFit({
+			width: bitmap.width,
+			height: bitmap.height
+		}, rule);
+		if (plan.unchanged && type === file.type) return file instanceof File ? file : new File([file], outputName(file, type), { type });
+		const blob = await drawCrop(bitmap, plan.crop, plan.width, plan.height, type, quality, "prepareImage");
+		return new File([blob], outputName(file, type), { 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}"`);
+	if (params.prefix != null && !isUploadPrefix(params.prefix)) throw new Error(`uploadImage: unknown prefix "${params.prefix}"`);
+	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);
+	if (params.prefix != null) form.append(SHOPWAVE_UPLOAD.prefixField, params.prefix);
+	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/productImages.ts
+/**
+* Product images, as the live API stores them (merchant 5644, 4 Nov 2026):
+* - A product's `images` is a list. **Reads return full URLs**
+*   (`http://static.merchantstack.com/images/merchant/<id>/product/<file>`);
+*   **writes take the uploader's file names** ({@link toStoredProductImages};
+*   `saveProduct` does this for you).
+* - The uploader takes one file per request. With a `prefix` (see
+*   `UploadPrefix`) it names the file `<prefix>_<hash>.<ext>`
+*   (`product_thumbnail_1bdd…41090b.png`); without one, `<hash>.<ext>`. So an
+*   image's role can be read back from its name ({@link productImageRole}).
+*/
+/**
+* The role in an image's file name or URL, from the uploader's `prefix`:
+* `"…/product_thumbnail_1bdd.png"` → `"product_thumbnail"`. `null` for a name
+* without one (images uploaded without a prefix, e.g. before prefixes existed).
 */
-async function deleteEntity(resourcePath, entityId, options = {}) {
-	if (entityId == null || entityId === "") throw new Error("entityId is missing");
-	await apiDelete(`/api/${resourcePath}/${entityId}`, options);
+function productImageRole(value) {
+	const name = imageFileName(value);
+	if (!name) return null;
+	return UPLOAD_PREFIXES.find((prefix) => name.startsWith(`${prefix}_`)) ?? null;
 }
 /**
-* 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.
+* A product's `images` as the API takes them on a save: file names, not the
+* URLs a read returns. Non-strings, blanks and duplicates are dropped; the
+* order is kept.
 */
-async function submitEntity({ endpoint, method = "POST", payload }, options = {}) {
-	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;
+function toStoredProductImages(images) {
+	if (!Array.isArray(images)) return [];
+	const names = images.map(imageFileName).filter((name) => Boolean(name));
+	return Array.from(new Set(names));
 }
 
 //#endregion
@@ -756,12 +1249,20 @@ async function fetchEntityById(kind, id, params = {}, options = {}) {
 * read) so an edited price is sent as a new instance. As a safeguard, a new
 * product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
 * another product would otherwise point the save at that product's instances.
+*
+* `images` is sent as file names ({@link toStoredProductImages}), so the URLs a
+* read returns can be passed straight back; leaving `images` out keeps them.
 */
 const saveProduct = (product, options) => {
-	return saveEntity("product", (product.id == null || String(product.id).trim() === "") && product.instances != null ? {
+	let toSave = (product.id == null || String(product.id).trim() === "") && product.instances != null ? {
 		...product,
 		instances: toProductInstancesForSave(product.instances)
-	} : product, options);
+	} : product;
+	if (Array.isArray(toSave.images)) toSave = {
+		...toSave,
+		images: toStoredProductImages(toSave.images)
+	};
+	return saveEntity("product", toSave, options);
 };
 const deleteProduct = (id, options) => deleteEntityById("product", id, options);
 const fetchProduct = (id, params, options) => fetchEntityById("product", id, params, options);
@@ -936,267 +1437,6 @@ function buildConsumerMap(consumers) {
 	return map;
 }
 
-//#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}`;
@@ -1941,6 +2181,8 @@ function useBasketReport(options) {
 //#endregion
 exports.DEFAULT_BASKET_FILTERS = DEFAULT_BASKET_FILTERS;
 exports.DEFAULT_PAGINATION = DEFAULT_PAGINATION;
+exports.ImageRuleError = ImageRuleError;
+exports.ImageTooSmallError = ImageTooSmallError;
 exports.MERCHANT_COLOUR_KEYS = MERCHANT_COLOUR_KEYS;
 exports.MERCHANT_FIELD_MAX_LENGTH = MERCHANT_FIELD_MAX_LENGTH;
 exports.MERCHANT_IMAGE_SLOTS = MERCHANT_IMAGE_SLOTS;
@@ -1957,6 +2199,7 @@ exports.SHOPWAVE_RESOURCES = SHOPWAVE_RESOURCES;
 exports.SHOPWAVE_UPLOAD = SHOPWAVE_UPLOAD;
 exports.ShopwaveApiError = ShopwaveApiError;
 exports.UPLOAD_KINDS = UPLOAD_KINDS;
+exports.UPLOAD_PREFIXES = UPLOAD_PREFIXES;
 exports.apiDelete = apiDelete;
 exports.apiGet = apiGet;
 exports.apiRequest = apiRequest;
@@ -1965,6 +2208,7 @@ exports.assertNoApiErrors = assertNoApiErrors;
 exports.authorizationFor = authorizationFor;
 exports.buildBasketReportQuery = buildBasketReportQuery;
 exports.buildConsumerMap = buildConsumerMap;
+exports.checkImageRule = checkImageRule;
 exports.collectConsumerIds = collectConsumerIds;
 exports.collectProductIds = collectProductIds;
 exports.combineBasketRows = combineBasketRows;
@@ -2008,6 +2252,7 @@ exports.getMerchantImageUrl = getMerchantImageUrl;
 exports.imageFileName = imageFileName;
 exports.isSameInstancePrice = isSameInstancePrice;
 exports.isUploadKind = isUploadKind;
+exports.isUploadPrefix = isUploadPrefix;
 exports.loginPath = loginPath;
 exports.logout = logout;
 exports.logoutPath = logoutPath;
@@ -2015,7 +2260,11 @@ exports.merchantLinksFromForm = merchantLinksFromForm;
 exports.merchantLinksToForm = merchantLinksToForm;
 exports.normalizeMerchantLinks = normalizeMerchantLinks;
 exports.normalizeTagList = normalizeTagList;
+exports.parseAspectRatio = parseAspectRatio;
 exports.parseBasketReportData = parseBasketReportData;
+exports.planImageFit = planImageFit;
+exports.prepareImage = prepareImage;
+exports.productImageRole = productImageRole;
 exports.readImageSize = readImageSize;
 exports.rolesById = rolesById;
 exports.saveCategory = saveCategory;
@@ -2030,6 +2279,7 @@ exports.submitEntity = submitEntity;
 exports.toProductInstancesForSave = toProductInstancesForSave;
 exports.toShopwaveApiError = toShopwaveApiError;
 exports.toStoredImageIds = toStoredImageIds;
+exports.toStoredProductImages = toStoredProductImages;
 exports.updateMerchant = updateMerchant;
 exports.uploadImage = uploadImage;
 exports.uploadMerchantImage = uploadMerchantImage;