react-shopwave-connect 0.3.0 → 0.4.1

package/dist/hooks/index.cjs

@@ -137,6 +137,20 @@ async function readBody(response) {
 		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;
@@ -522,6 +536,364 @@ 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)`);
+}
+/**
+* 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
+/**
+* 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;
+}
+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}`;
+/** 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"]
+});
+/**
+* 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
 //#region src/hooks/shared.ts
 function toMessage(e) {
@@ -879,6 +1251,85 @@ function useSession(options) {
 	}), [options?.baseUrl]);
 }
 
+//#endregion
+//#region src/hooks/useMerchant.ts
+/**
+* The logged-in user's merchant, fetched on mount. `data` is `null` while
+* loading or when the API has no merchant.
+*
+* @example
+* const { data: merchant, loading, refetch } = useMerchant();
+*/
+function useMerchant(options) {
+	return useQuery((signal) => fetchMerchant({
+		...options,
+		signal
+	}), [options?.baseUrl, options?.token]);
+}
+/**
+* Manually-triggered merchant update (see `updateMerchant`: the patch is merged
+* over the current merchant by default). Resolves to the saved merchant, or
+* `null` on error (then `error` / `errorStatus` are set).
+*
+* @example
+* const { mutate: saveMerchant, loading: saving } = useUpdateMerchant();
+* const saved = await saveMerchant({ vatNumber: "GB123" });
+*/
+function useUpdateMerchant(options) {
+	return useMutation((patch) => updateMerchant(patch, options), [
+		options?.baseUrl,
+		options?.token,
+		options?.merge
+	]);
+}
+
+//#endregion
+//#region src/hooks/useUser.ts
+/**
+* The logged-in user, fetched on mount. `errorStatus` is 401 when logged out.
+*
+* @example
+* const { data: user } = useUser();
+*/
+function useUser(options) {
+	const enabled = options?.enabled ?? true;
+	return useQuery((signal) => fetchUser({
+		...options,
+		signal
+	}), [options?.baseUrl, options?.token], enabled);
+}
+
+//#endregion
+//#region src/hooks/useUploadImage.ts
+/**
+* Manually-triggered image upload. Resolves to `{ id, url }`, or `null` on
+* error (then `error` / `errorStatus` are set).
+*
+* @example
+* const { mutate: upload, loading: uploading } = useUploadImage();
+* const image = await upload(file, { kind: "merchant" });
+*/
+function useUploadImage(options) {
+	return useMutation((file, params) => uploadImage(file, params, options), [options?.baseUrl, options?.token]);
+}
+/**
+* Manually-triggered upload for a merchant image slot (`receipt`, `square`,
+* `featured`): fits the image to the slot's exact size, uploads it with the
+* slot's kind, and resolves to `{ id, url }`. Put `id` into `imageIds` with
+* `setMerchantImage`.
+*
+* @example
+* const { mutate: upload } = useUploadMerchantImage();
+* const image = await upload(file, "square");
+*/
+function useUploadMerchantImage(options) {
+	return useMutation((file, slot) => uploadMerchantImage(file, slot, options), [
+		options?.baseUrl,
+		options?.token,
+		options?.fit
+	]);
+}
+
 //#endregion
 //#region src/hooks/useBasketReport.ts
 /**
@@ -989,10 +1440,15 @@ exports.useConsumer = useConsumer;
 exports.useDelete = useDelete;
 exports.useEmployee = useEmployee;
 exports.useLogout = useLogout;
+exports.useMerchant = useMerchant;
 exports.useProduct = useProduct;
 exports.usePromotion = usePromotion;
 exports.useReport = useReport;
 exports.useSession = useSession;
 exports.useStore = useStore;
 exports.useSubmit = useSubmit;
+exports.useUpdateMerchant = useUpdateMerchant;
+exports.useUploadImage = useUploadImage;
+exports.useUploadMerchantImage = useUploadMerchantImage;
+exports.useUser = useUser;
 //# sourceMappingURL=index.cjs.map