react-shopwave-connect 0.4.4 → 0.4.6

package/README.md

@@ -191,18 +191,18 @@ await updateMerchant({ imageIds: setMerchantImage(merchant?.imageIds, "square",
 getMerchantImageUrl(saved.imageIds, "square");                     // HTTPS URL for <img src>
 ```
 
-The shapes below are the ones adminV1 saves and adminV2 reads, so all three admins share one record (confirmed on the live API with merchant 5644, 30 Sep 2026):
+The shapes below are the ones Shopwave's existing admin apps save and read, so every client shares one record (confirmed on the live API, 30 Sep 2026):
 
 | Field | Shape |
 |---|---|
 | `imageIds` | `{ logo: { receipt, square }, feature: [ … ] }` — **file names** on write (the uploader's `fileName`), **full `http://static.merchantstack.com/…` URLs** on read |
-| `colours` | `{ primary: { main, highlight, contrast } }` (hex strings; adminV2 uses `primary.main` behind the logo) |
+| `colours` | `{ primary: { main, highlight, contrast } }` (hex strings; `primary.main` is the colour shown behind the logo) |
 | `links` | `{ website: { home }, social: { twitter, facebook, instagram } }` |
 
 - **Merchant fields** (`GET`/`POST /merchant`): `id`, `name`, `description`, `companyNumber`, `vatNumber`, `categoryId`, `estAnnualRevenue`, `note`, and the three objects above. The API returns `{}` for an empty object.
 - **What the live API does on `POST /merchant`** (checked 30 Sep 2026): it replaces the record. A scalar field left out (`companyNumber`, `vatNumber`, `note`, …) becomes `null`; an object field left out (`colours`, `links`, `imageIds`) is kept, and one that is sent replaces the stored one (`{}` clears it). It answers **205 with an empty body**. It silently cuts `companyNumber` to 11 characters and `vatNumber` to 9 (a UK VAT number without `GB`).
 - **`updateMerchant(patch, { merge })`**: `merge` (default `true`) reads first and merges the scalar fields, so nothing is wiped. Object fields (`MERCHANT_OBJECT_FIELDS`) are sent only when the patch has them, and then replace the stored one — to change one image, pass the whole `imageIds` (`setMerchantImage` does that). `imageIds` is always sent as file names (`toStoredImageIds`), so you can pass back what you read. It refuses a different merchant `id`, never sends `createdDate`/`modifiedDate`, rejects values longer than `MERCHANT_FIELD_MAX_LENGTH` (`validateMerchant(m)` lists them) instead of letting the API cut them, and returns the merchant **read back after the save**, so you see exactly what was kept. `merge: false` sends only the patch (which must include `id`, and clears the scalar fields you leave out).
-- **Merchant image slots** (`MERCHANT_IMAGE_SLOTS`): the API doesn't resize, and adminV1 accepts only these exact sizes.
+- **Merchant image slots** (`MERCHANT_IMAGE_SLOTS`): the API doesn't resize, and Shopwave's existing admin accepts only these exact sizes.
 
   | Slot | Stored at | Upload kind | Size |
   |---|---|---|---|
@@ -210,15 +210,40 @@ The shapes below are the ones adminV1 saves and adminV2 reads, so all three admi
   | `square` | `imageIds.logo.square` | `merchant` | 1000 × 1000 |
   | `featured` | `imageIds.feature[0]` | `merchantFeature` | 1200 × 600 |
 
-  The API builds each image URL from its key, not from where the file was uploaded (`logo.*` → `…/merchant/<id>/logo/<file>`, `feature` → `…/feature/<file>`), so the featured image must be uploaded as `merchantFeature`. `POST /merchant` stores all three objects with the SDK's `{ merchant: … }` body; adminV1's `{ merchants: { "0": … } }` form isn't needed.
+  The API builds each image URL from its key, not from where the file was uploaded (`logo.*` → `…/merchant/<id>/logo/<file>`, `feature` → `…/feature/<file>`), so the featured image must be uploaded as `merchantFeature`. `POST /merchant` stores all three objects with the SDK's `{ merchant: … }` body; the existing admin's `{ merchants: { "0": … } }` form isn't needed.
 
   `uploadMerchantImage(file, slot, { fit = true })` scales and centre-crops the image to the slot's size in the browser (`fitImageToSize`, `coverCrop`) and uploads it with the slot's kind; `fit: false` sends the file as-is. `getMerchantImage` / `getMerchantImageUrl` / `setMerchantImage` read and write a slot; `imageFileName(url)` gives the file name in a URL. Hook: `useUploadMerchantImage()`.
 - **Links:** `merchantLinksToForm(links)` gives flat fields (`website`, `twitter`, `facebook`, `instagram`) from the stored shape, flat keys or the old array form; `merchantLinksFromForm(fields)` builds the stored shape; `normalizeMerchantLinks(links)` converts any of them to the stored shape. Colour keys: `MERCHANT_COLOUR_KEYS`.
-- **User** (`GET /user`): the live API returns `id`, `firstName`, `lastName`, `email` and `employee: { merchantId, roleId, stores }` — no `createdDate` and **no `merchant`**, although the reference lists them. There's no option to include it (adminV1 also reads `GET /merchant` separately and attaches it to its session). Read the merchant with `fetchMerchant()`.
+- **User** (`GET /user`): the live API returns `id`, `firstName`, `lastName`, `email` and `employee: { merchantId, roleId, stores }` — no `createdDate` and **no `merchant`**, although the reference lists them. There's no option to include it (Shopwave's existing admin also reads `GET /merchant` separately and attaches it to its session). Read the merchant with `fetchMerchant()`.
 - **`uploadImage(file, { kind, prefix?, fileName? })`** posts the file to `/api/upload`, which `PUT`s it to Shopwave's `/uploader` (multipart `file`, header `contentType: <kind>`). Kinds: `merchant`, `merchantFeature`, `product`, `user`, `applicationLogo`, `applicationImages` (the last two sent as the API's own spelling, `applicaionLogo`/`applicaionImages`). Live: 201 `{ fileName, path }`. Returns `{ id, url, path }`: `id` is the generated file name (what records store), `path` the URL as the API gave it (`http://static.merchantstack.com/images/…`, which has no HTTPS endpoint), and `url` the same file over HTTPS via `getImageUrl(path)` (`SHOPWAVE_IMAGE_BASE_URL`, the S3 bucket behind the CDN). The upload alone changes no record.
-  - **`prefix`** (optional) is the image's role, sent as the uploader's `prefix` header: `product`, `product_thumbnail`, `variant`, `variant_thumbnail` (`UPLOAD_PREFIXES`). The uploader then names the file `<prefix>_<hash>.<ext>` (live, 5644, 4 Nov 2026: `product_thumbnail_1bdd….png`), so the role travels with the file; `productImageRole(nameOrUrl)` reads it back (`null` for a name without one). Leave it out for images without a role (merchant logos). An unknown prefix throws before any request; the route answers 400 to one.
+  - **`prefix`** (optional) is the image's role, sent as the uploader's `prefix` header: `product`, `product_thumbnail`, `variant`, `variant_thumbnail` (`UPLOAD_PREFIXES`). The uploader then names the file `<prefix>_<hash>.<ext>` (live, 4 Nov 2026: `product_thumbnail_<hash>.png`), so the role travels with the file; `productImageRole(nameOrUrl)` reads it back (`null` for a name without one). Leave it out for images without a role (merchant logos). An unknown prefix throws before any request; the route answers 400 to one.
 - **Product images:** `images` is a list — **full URLs on read** (`http://static.merchantstack.com/images/merchant/<id>/product/<file>`), **file names on write**. The uploader takes one file per request, so upload each file on its own (`uploadImage(file, { kind: "product", prefix })`) and save the product with all the names. `saveProduct` sends `images` as file names (`toStoredProductImages`), so URLs read back can be passed straight in; leaving `images` out keeps them.
 
+- **Image rules (browser).** Shopwave doesn't resize uploads, so prepare each image before `uploadImage` with `prepareImage(file, rule, { type?, quality? })`. A rule is an exact size or a shape plus limits; the image is scaled down and centre-cropped in one draw (never stretched), and one that already fits is returned untouched.
+
+  ```ts
+  import { prepareImage, ImageTooSmallError, uploadImage } from "react-shopwave-connect";
+
+  const rule = { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 };
+  try {
+    const ready = await prepareImage(file, rule);          // 6000 × 4000 → 2000 × 1540
+    await uploadImage(ready, { kind: "product", prefix: "product" });
+  } catch (error) {
+    if (error instanceof ImageTooSmallError) showWarning(error.required, error.actual); // e.g. 600 × 462 vs 500 × 385
+    else throw error;
+  }
+  ```
+
+  | Rule field | Meaning |
+  |---|---|
+  | `width` + `height` | Exact output size (the ratio follows); can't be combined with the others |
+  | `aspectRatio` | Shape to crop to: `"100:77"`, `"100/77"`, `[100, 77]` or `1.3` |
+  | `minWidth`, `minHeight` | Smaller crops are refused with `ImageTooSmallError` (`required`, `actual`) |
+  | `maxWidth`, `maxHeight`, `maxLongSide` | Larger crops are scaled down to fit |
+  | `allowUpscale` | Enlarge a too-small image instead of refusing it (default `false`) |
+
+  Output keeps the source type when it's PNG, JPEG or WebP (JPEG/WebP at quality 0.9), else PNG. `planImageFit(size, rule)` gives the crop and output size without touching an image (pure); `checkImageRule(rule)` and `parseAspectRatio(value)` throw `ImageRuleError` for a rule that contradicts itself.
+
 `SHOPWAVE_RESOURCES` (merchant, user) and `SHOPWAVE_UPLOAD` are shared with the server routes, like `SHOPWAVE_ENTITIES`.
 
 ### Available `core` functions
@@ -234,7 +259,7 @@ The shapes below are the ones adminV1 saves and adminV2 reads, so all three admi
 | report    | `fetchReport`                                           |
 | merchant  | `fetchMerchant`, `updateMerchant`, `validateMerchant`; links `merchantLinksToForm`, `merchantLinksFromForm`, `normalizeMerchantLinks`; images `MERCHANT_IMAGE_SLOTS`, `uploadMerchantImage`, `getMerchantImage`, `getMerchantImageUrl`, `setMerchantImage`, `toStoredImageIds`, `imageFileName` |
 | user      | `fetchUser`                                              |
-| upload    | `uploadImage`, `getImageUrl`, `fitImageToSize`, `readImageSize`, `coverCrop`; `UPLOAD_KINDS`, `UPLOAD_PREFIXES`, `isUploadPrefix` |
+| upload    | `uploadImage`, `getImageUrl`, `fitImageToSize`, `readImageSize`, `coverCrop`; `UPLOAD_KINDS`, `UPLOAD_PREFIXES`, `isUploadPrefix`; image rules `prepareImage`, `planImageFit`, `checkImageRule`, `parseAspectRatio`, `ImageTooSmallError`, `ImageRuleError` |
 | session   | `fetchSession`, `loginPath`, `logoutPath`, `logout`     |
 | entity    | `saveEntity`, `saveEntities`, `deleteEntityById`, `fetchEntityById`; low-level `submitEntity` / `deleteEntity` (raw endpoint) |
 | errors    | `ShopwaveApiError`, `getApiErrorMap`, `assertNoApiErrors` |
@@ -505,7 +530,7 @@ Options: `apiVersion` (default `"2.0"`), `fetch`, `entities` (override a route/h
 
 ### Moving an existing app over
 
-- Keep `redirectUri` equal to the URL already registered on the auth server (AdminUI: `…/auth`) and mount `handlers.auth` at that path.
+- Keep `redirectUri` equal to the URL already registered on the auth server and mount `handlers.auth` at that path.
 - Keep `cookieName` the same and use the same `SESSION_SECRET` value as the old iron-session password — current users stay logged in; their old token shape is read and upgraded on the next refresh.
 - Per-tool auth routes can go: link to `auth.loginPath("/tools/where-to-next")` instead.
 - `core.logout()` / `useLogout()` still work (`DELETE /api/session`), but prefer linking to `logoutPath()` so the auth-server session ends too.
@@ -536,7 +561,7 @@ Unit tests (offline, no credentials) cover the OAuth client, token handling, the
 npm test            # = npm run test:unit
 ```
 
-Integration tests use [Vitest](https://vitest.dev) and run against **an app that mounts the SDK routes** (e.g. AdminUI on `npm run dev`), which forwards to the Shopwave API. They cover create → read (by id and by filter) → update → delete with the typed functions for Products and Categories, create → read → role update → retire for Employees, read-only checks for Consumers, plus unknown ids and the legacy `submitEntity` body. They create and delete real records on the account behind the token.
+Integration tests use [Vitest](https://vitest.dev) and run against **an app that mounts the SDK routes** (for example your app on `npm run dev`), which forwards to the Shopwave API. They cover create → read (by id and by filter) → update → delete with the typed functions for Products and Categories, create → read → role update → retire for Employees, read-only checks for Consumers, plus unknown ids and the legacy `submitEntity` body. They create and delete real records on the account behind the token.
 
 ### Environment Variables
 
@@ -549,7 +574,7 @@ Integration tests use [Vitest](https://vitest.dev) and run against **an app that
 
 ```bash
 # Set environment variables
-# with the app running (AdminUI: npm run dev)
+# with the app running (npm run dev)
 export API_URL=http://localhost:3000
 export API_TOKEN=<bare access token>
 

package/dist/core/index.cjs

@@ -637,6 +637,35 @@ async function readImageSize(file) {
 		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
@@ -645,39 +674,194 @@ async function readImageSize(file) {
 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 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 { 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));
-		}
+		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
@@ -691,7 +875,7 @@ 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`.
+* relative path (`merchant/123/logo/x.png`) → `<base>/merchant/123/logo/x.png`.
 * Other absolute URLs are returned unchanged; empty input gives `""`.
 */
 function getImageUrl(path, base = SHOPWAVE_IMAGE_BASE_URL) {
@@ -743,7 +927,7 @@ const MERCHANT_IMAGE_SLOT_KEYS = [
 	"featured"
 ];
 /**
-* Where each slot lives, its upload kind and its exact size (from adminV1's
+* Where each slot lives, its upload kind and its exact size (from the existing admin's
 * merchant settings page).
 */
 const MERCHANT_IMAGE_SLOTS = Object.freeze({
@@ -834,7 +1018,7 @@ function toStored(value) {
 }
 /**
 * 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
+* name (what the existing admin does with images you didn't change) and empty values
 * are dropped. No images gives `{}`.
 */
 function toStoredImageIds(imageIds) {
@@ -855,7 +1039,7 @@ async function uploadMerchantImage(file, slot, options = {}) {
 //#endregion
 //#region src/core/productImages.ts
 /**
-* Product images, as the live API stores them (merchant 5644, 4 Nov 2026):
+* Product images, as the live API stores them (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};
@@ -1257,9 +1441,9 @@ function trimmed(value) {
 /**
 * Reads `merchant.links` as flat fields (`{ website, twitter, facebook,
 * instagram }`), whatever shape it was saved in:
-* - the nested shape adminV1 saves (`{ website: { home }, social: { … } }`);
+* - the nested shape the existing admin 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).
+* - an array in {@link MERCHANT_LINK_KEYS} order (older app versions).
 * Empty values are dropped.
 */
 function merchantLinksToForm(links) {
@@ -1296,7 +1480,7 @@ function merchantLinksFromForm(form) {
 	}
 	return out;
 }
-/** Reads any stored or older `links` value into the nested shape adminV1 saves. */
+/** Reads any stored or older `links` value into the nested shape the existing admin saves. */
 function normalizeMerchantLinks(links) {
 	return merchantLinksFromForm(merchantLinksToForm(links));
 }
@@ -1406,6 +1590,8 @@ async function fetchUser(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;
@@ -1431,6 +1617,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;
@@ -1482,7 +1669,10 @@ 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;