react-shopwave-connect 0.4.0 → 0.4.2

package/README.md

@@ -149,7 +149,7 @@ await deleteCategory(created.id);
 | product   | `saveProduct`, `deleteProduct`, `fetchProduct`             | `/api/products[/:id]`         |
 | category  | `saveCategory`, `deleteCategory`, `fetchCategory`          | `/api/categories[/:id]`       |
 | store     | `saveStore`, `deleteStore`, `fetchStore`                   | `/api/stores[/:id]`           |
-| promotion | `savePromotion`, `deletePromotion` (ends it), `fetchPromotion` | `/api/promotions[/:id]`       |
+| promotion | `savePromotion`, `deletePromotion` (expires it), `fetchPromotion` | `/api/promotions[/:id]`       |
 | employee  | `saveEmployee`, `deleteEmployee` (retires), `fetchEmployee` | `/api/employees[/:id]`        |
 | consumer  | `fetchConsumer` only — read-only in the API                | `/api/consumer[/:id]` (GET)   |
 
@@ -158,9 +158,10 @@ How they behave (matches what the Shopwave API does):
 - **Save** sends `{ <collection>: { "0": entity } }`. Shopwave upserts (an `id` means update), answers **201** and echoes the entity under the same ref with its `id` and server fields. The function checks `api.message.errors` and that the ref came back, and returns the saved entity (fields the echo leaves out are kept from your input). `saveEntities(kind, [a, b])` saves several at once and matches results back by ref.
 - **Delete** is a soft delete (read it back with `deleted: true`). Shopwave answers **205 with an empty body — also for ids that don't exist**, so a resolved promise means "accepted", not "a record was deleted".
 - **Read one** calls `GET /api/<route>/:id` and returns the record or `null`. List reads return `[]` when nothing matches (Shopwave answers with an empty body).
-- **Promotions:** Shopwave has no promotion DELETE; `deletePromotion` (and `DELETE /api/promotions/:id`) ends the promotion by setting `endDate` to now.
+- **Promotions:** promotions are never deleted, only expired. `deletePromotion` (and `DELETE /api/promotions/:id`) reads the promotion and saves the whole record back with `endDate` set to now; one that hasn't started yet gets `startDate` = `endDate` = now. (The API rejects a partial `{ id, endDate }` save with error 899.) Dates go as UTC `YYYY-MM-DD HH:mm:ss`.
 - **Employees:** Shopwave has no employee DELETE, so `deleteEmployee` (and `DELETE /api/employees/:id`) retires the employee by setting `exitDate`. Updating an existing employee only changes `roleId`, `joinedDate` and `exitDate` — names and email are fixed — and the echo carries only those fields, so re-read with `fetchEmployee` if you need the stored record.
 - **Consumers** are read-only (`GET /consumer` by `ids`); their write/delete routes answer 405.
+- **Product prices (instances) can't be updated** — the API keeps them for history; a price change means a new instance with a new id. Build `instances` with `toProductInstancesForSave(formInstances, productAsLastRead)`: it keys them `"0"…"n"`, keeps an instance's `id` only when the original has that id with the same price and tax, and drops it otherwise (and drops server `timestamp`). `findRepricedInstances(formInstances, productAsLastRead)` lists the instances that will get new ids, so you can warn first. `saveProduct` without an `id` (a new product or a duplicate) always strips instance ids, so a copy can't point at the original's prices.
 - Errors are read from `api.message.errors` and also `api.message.error` (the name used in the [API reference](https://developer.merchantstack.com/api-reference.html)).
 
 The generic forms are `saveEntity(kind, item)`, `deleteEntityById(kind, id)` and `fetchEntityById(kind, id)`; `SHOPWAVE_ENTITIES` lists each entity's route, collection key, Shopwave path and id headers.
@@ -225,7 +226,7 @@ The shapes below are the ones adminV1 saves and adminV2 reads, so all three admi
 | category  | `fetchCategories`, `fetchCategory`, `saveCategory`, `deleteCategory` |
 | consumer  | `fetchConsumers`, `fetchConsumer` (read-only)            |
 | employee  | `fetchEmployees`, `fetchEmployee`, `saveEmployee`, `deleteEmployee` |
-| product   | `fetchProducts`, `fetchProductsMap` (batched, keyed), `fetchProduct`, `saveProduct`, `deleteProduct` |
+| product   | `fetchProducts`, `fetchProductsMap` (batched, keyed), `fetchProduct`, `saveProduct`, `deleteProduct`; prices `toProductInstancesForSave`, `findRepricedInstances`, `isSameInstancePrice` |
 | promotion | `fetchPromotions`, `fetchPromotion`, `savePromotion`, `deletePromotion` |
 | store     | `fetchStores` (now with `storeIds`), `fetchStore`, `saveStore`, `deleteStore` |
 | report    | `fetchReport`                                           |
@@ -471,7 +472,7 @@ export const { POST } = shopwave.upload();              // or upload({ maxBytes,
 - `resource("merchant")`: `PUT`/`POST` take `{ merchant: {…} }` or the bare object and send every field on as `postBody`. The `id` is required (400 without it), because a POST without one would create a second merchant. `resource("user")` answers 405 to writes.
 - `upload()`: takes multipart `file` + `kind`, checks the size (default 10 MB → 413) and type (default `image/*` → 415), and `PUT`s only the file to `/uploader` with the `contentType` header. `extras` are ignored on uploads. Shopwave's reply (201 `{ fileName, path }`) is passed through.
 
-Entities: `product`, `category`, `store`, `promotion`, `employee` (DELETE retires via `exitDate`), `promotion` (DELETE ends it via `endDate`), `consumer` (mounted at `/api/consumer`; GET only, writes answer 405). For anything else, `shopwave.forward(request, { method, path, headers, postBody })` does the same token/refresh/encoding work for a custom handler.
+Entities: `product`, `category`, `store`, `promotion`, `employee` (DELETE retires via `exitDate`), `promotion` (DELETE expires it: the whole record saved back with `endDate`, and a not-yet-started `startDate`, set to now), `consumer` (mounted at `/api/consumer`; GET only, writes answer 405). For anything else, `shopwave.forward(request, { method, path, headers, postBody })` does the same token/refresh/encoding work for a custom handler.
 
 Every handler:
 

package/dist/core/index.cjs

@@ -41,8 +41,8 @@ function getApiErrorMap(body) {
 }
 function describeErrors(errors) {
 	return Object.entries(errors).map(([code, e]) => {
-		const text = [e?.title, e?.details].filter(Boolean).join(": ");
-		return text ? `${code} ${text}` : code;
+		const text$1 = [e?.title, e?.details].filter(Boolean).join(": ");
+		return text$1 ? `${code} ${text$1}` : code;
 	}).join("; ");
 }
 /**
@@ -104,12 +104,12 @@ function buildExtras(extras) {
 }
 /** 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;
+	const text$1 = await response.text();
+	if (!text$1) return null;
 	try {
-		return JSON.parse(text);
+		return JSON.parse(text$1);
 	} catch {
-		return { raw: text };
+		return { raw: text$1 };
 	}
 }
 /**
@@ -257,6 +257,83 @@ async function fetchProducts(params = {}, options = {}) {
 	assertNoApiErrors(json, 200);
 	return Object.values(json?.products ?? {});
 }
+/** Fields the server sets on an instance; never sent back. */
+const SERVER_INSTANCE_FIELDS = ["timestamp"];
+function instanceList(instances) {
+	if (!instances) return [];
+	return (Array.isArray(instances) ? [...instances] : Object.values(instances)).filter((inst) => inst != null && typeof inst === "object");
+}
+function hasId(id) {
+	return id != null && String(id).trim() !== "";
+}
+/** Same number, so `"422.0"`, `"422"` and `422` are equal; blanks equal each other. */
+function sameAmount(a, b) {
+	const blank = (v) => v == null || String(v).trim() === "";
+	if (blank(a) || blank(b)) return blank(a) && blank(b);
+	const x = Number(a);
+	const y = Number(b);
+	return Number.isNaN(x) || Number.isNaN(y) ? String(a).trim() === String(b).trim() : x === y;
+}
+/** True when two instances have the same price and tax (the fields Shopwave won't update). */
+function isSameInstancePrice(a, b) {
+	return sameAmount(a.price, b.price) && sameAmount(a.taxPercentage, b.taxPercentage);
+}
+const text = (v) => v == null ? "" : String(v);
+/**
+* Lists the instances whose price or tax differs from the `original` instance
+* with the same id: saving them creates new instances with new ids, which can
+* affect anything that stores instance ids (integrations, reports, modifiers).
+* Use it to warn before saving. New rows (no id) aren't listed.
+*/
+function findRepricedInstances(instances, original) {
+	const byId = new Map(instanceList(original).filter((o) => hasId(o.id)).map((o) => [String(o.id), o]));
+	const result = [];
+	instanceList(instances).forEach((inst, index) => {
+		if (!hasId(inst.id)) return;
+		const before = byId.get(String(inst.id));
+		if (!before || isSameInstancePrice(inst, before)) return;
+		result.push({
+			index,
+			id: inst.id,
+			name: text(inst.name),
+			before: {
+				price: text(before.price),
+				taxPercentage: text(before.taxPercentage)
+			},
+			after: {
+				price: text(inst.price),
+				taxPercentage: text(inst.taxPercentage)
+			}
+		});
+	});
+	return result;
+}
+/**
+* Builds the `instances` map for a product save:
+* - keyed by position (`"0"`, `"1"`, …), like every other ref in a save;
+* - an instance keeps its `id` only when `original` has an instance with that id
+*   and the same price and tax; otherwise the id is removed, so Shopwave creates
+*   a new instance instead of re-pointing or rewriting someone else's;
+* - server fields (`timestamp`) are removed.
+*
+* Pass the product as last read from the API as `original`. Leave it out for a
+* new product (including a duplicate): every id is then removed.
+* Instances left out of the list are left out of the save (removed).
+*/
+function toProductInstancesForSave(instances, original) {
+	const keep = new Map(instanceList(original).filter((o) => hasId(o.id)).map((o) => [String(o.id), o]));
+	const out = {};
+	instanceList(instances).forEach((inst, index) => {
+		const { id,...rest } = inst;
+		for (const field of SERVER_INSTANCE_FIELDS) delete rest[field];
+		const before = hasId(id) ? keep.get(String(id)) : void 0;
+		out[String(index)] = before && isSameInstancePrice(inst, before) ? {
+			id,
+			...rest
+		} : rest;
+	});
+	return out;
+}
 /**
 * Fetches products by id and returns them keyed by id, transparently batching
 * the request (default 200 ids per call) to stay within API limits. Extracted
@@ -407,7 +484,10 @@ async function submitEntity({ endpoint, method = "POST", payload }, options = {}
 * (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.
+* - promotion: no DELETE; promotions are never deleted, only expired. Expiring
+*   reads the promotion and saves the whole record back with `endDate` = now (and
+*   `startDate` = now too if it hadn't started); the live API rejects a partial
+*   `{ id, endDate }` save with error 899. Dates are UTC `YYYY-MM-DD HH:mm:ss`.
 * - 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.
@@ -448,7 +528,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -523,7 +605,8 @@ async function saveEntity(kind, item, options = {}) {
 /**
 * 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`).
+* sets `exitDate` / `endDate` to now instead (see `SHOPWAVE_ENTITIES`), and a
+* promotion is saved back whole (see {@link deletePromotion}).
 *
 * 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
@@ -540,7 +623,21 @@ async function fetchEntityById(kind, id, params = {}, options = {}) {
 	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);
+/**
+* Creates (no `id`) or updates (with `id`) a product.
+*
+* Shopwave instances (prices) can't be updated, only replaced. Build
+* `instances` with {@link toProductInstancesForSave} (passing the product as last
+* 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.
+*/
+const saveProduct = (product, options) => {
+	return saveEntity("product", (product.id == null || String(product.id).trim() === "") && product.instances != null ? {
+		...product,
+		instances: toProductInstancesForSave(product.instances)
+	} : 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);
@@ -550,7 +647,12 @@ 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. */
+/**
+* Expires a promotion (Shopwave never deletes promotions). The route reads the
+* promotion and saves it back with `endDate` set to now; a promotion that hasn't
+* started yet gets `startDate` = `endDate` = now. Rejects if the promotion doesn't
+* exist or the save fails.
+*/
 const deletePromotion = (id, options) => deleteEntityById("promotion", id, options);
 const fetchPromotion = (id, params, options) => fetchEntityById("promotion", id, params, options);
 /**
@@ -1245,6 +1347,7 @@ exports.fetchSession = fetchSession;
 exports.fetchStore = fetchStore;
 exports.fetchStores = fetchStores;
 exports.fetchUser = fetchUser;
+exports.findRepricedInstances = findRepricedInstances;
 exports.fitImageToSize = fitImageToSize;
 exports.formatDateForQuery = formatDateForQuery;
 exports.getApiErrorMap = getApiErrorMap;
@@ -1253,6 +1356,7 @@ exports.getImageUrl = getImageUrl;
 exports.getMerchantImage = getMerchantImage;
 exports.getMerchantImageUrl = getMerchantImageUrl;
 exports.imageFileName = imageFileName;
+exports.isSameInstancePrice = isSameInstancePrice;
 exports.isUploadKind = isUploadKind;
 exports.loginPath = loginPath;
 exports.logout = logout;
@@ -1272,6 +1376,7 @@ exports.savePromotion = savePromotion;
 exports.saveStore = saveStore;
 exports.setMerchantImage = setMerchantImage;
 exports.submitEntity = submitEntity;
+exports.toProductInstancesForSave = toProductInstancesForSave;
 exports.toShopwaveApiError = toShopwaveApiError;
 exports.toStoredImageIds = toStoredImageIds;
 exports.updateMerchant = updateMerchant;