react-shopwave-connect 0.4.5 → 0.4.7

package/dist/hooks/index.cjs

@@ -203,12 +203,15 @@ async function apiSend(path, method, payload, options = {}) {
 /**
 * DELETE helper. Shopwave answers deletes with 205 and an empty body; if a body
 * does come back and carries API errors, they are thrown. Returns the parsed
-* body (`null` when empty).
+* body (`null` when empty). `extras`, when given, travel in the `extras` header
+* (the server forwards only keys its delete route allows).
 */
-async function apiDelete(path, options = {}) {
+async function apiDelete(path, options = {}, extras) {
+	const headers = baseHeaders(options);
+	if (extras) headers.extras = JSON.stringify(buildExtras(extras));
 	const { status, body } = await send(path, {
 		method: "DELETE",
-		headers: baseHeaders(options)
+		headers
 	}, options);
 	if (getApiErrorMap(body)) throw toShopwaveApiError(status, body);
 	return body;
@@ -395,115 +398,6 @@ function fetchProductInstanceTags(options = {}) {
 	return fetchLookup("productInstanceTags", options);
 }
 
-//#endregion
-//#region src/core/promotion.ts
-/**
-* Fetches promotions. Returns the flattened `Promotion[]`.
-*/
-async function fetchPromotions(params = {}, options = {}) {
-	const extras = { deleted: params.deleted ?? false };
-	if (params.promotionIds) extras.promotionIds = params.promotionIds;
-	if (params.imminent !== void 0) extras.imminent = params.imminent;
-	if (params.active !== void 0) extras.active = params.active;
-	if (params.expired !== void 0) extras.expired = params.expired;
-	const json = await apiGet("/api/promotions", extras, withToken(options, params.token));
-	assertNoApiErrors(json, 200);
-	return Object.values(json?.promotions ?? {});
-}
-
-//#endregion
-//#region src/core/store.ts
-/**
-* Fetches stores. Returns the flattened `Store[]`.
-*/
-async function fetchStores(params = {}, options = {}) {
-	const extras = { deleted: params.deleted ?? false };
-	if (params.storeIds) extras.storeIds = params.storeIds;
-	const json = await apiGet("/api/stores", extras, withToken(options, params.token));
-	assertNoApiErrors(json, 200);
-	return Object.values(json?.stores ?? {});
-}
-
-//#endregion
-//#region src/core/report.ts
-/**
-* Runs one or more report queries and returns the `reports` map keyed by query
-* name. The query is JSON-encoded into the `extras.query` header, matching the
-* original endpoint contract.
-*/
-async function fetchReport(query, options = {}) {
-	const json = await apiGet("/api/report", { query: JSON.stringify(query) }, options);
-	assertNoApiErrors(json, 200);
-	return json?.reports ?? {};
-}
-
-//#endregion
-//#region src/core/session.ts
-/**
-* Reads the current login status from `GET /api/session`.
-*
-* Works with the new `react-shopwave-connect/next` session route
-* (`{ loggedIn }`) and with older routes that returned the raw session
-* (`{ token: {...} }`) — in that case only a boolean is surfaced.
-*/
-async function fetchSession(options = {}) {
-	const doFetch = options.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
-	if (!doFetch) throw new Error("No fetch implementation available. Pass `options.fetch`.");
-	const response = await doFetch(`${options.baseUrl ?? ""}/api/session`, {
-		method: "GET",
-		headers: { Accept: "application/json" },
-		cache: "no-store",
-		credentials: "same-origin",
-		signal: options.signal
-	});
-	if (response.status === 401) return { loggedIn: false };
-	if (!response.ok) throw new Error(`Session request failed (${response.status})`);
-	const json = await response.json();
-	if (json && typeof json.loggedIn === "boolean") return {
-		loggedIn: json.loggedIn,
-		expiresAt: typeof json.expiresAt === "number" ? json.expiresAt : void 0
-	};
-	return { loggedIn: Boolean(json && json.token) };
-}
-/**
-* Ends the current server session (no redirect).
-*
-* Prefer navigating to {@link logoutPath} when using
-* `react-shopwave-connect/next`: it also signs the user out of the auth server.
-*/
-async function logout(options = {}) {
-	await apiDelete("/api/session?action=logout", options);
-}
-
-//#endregion
-//#region src/core/entity.ts
-/**
-* Low-level, untyped mutations: the caller supplies the route and payload.
-*
-* Prefer the typed functions in `./entities` (`saveProduct`, `deleteCategory`,
-* …): they know each route, build the request envelope, check the response and
-* return the saved entity with its id. Keep these for routes that have no typed
-* function yet (e.g. `/api/merchant`).
-*/
-/**
-* Deletes `/api/{resourcePath}/{entityId}`.
-*/
-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
 /**
@@ -599,7 +493,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) {
@@ -645,7 +539,7 @@ async function uploadImage(file, params, options = {}) {
 //#endregion
 //#region src/core/merchantImages.ts
 /**
-* 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({
@@ -695,7 +589,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) {
@@ -713,6 +607,245 @@ async function uploadMerchantImage(file, slot, options = {}) {
 	return uploadImage(fit ? await fitImageToSize(file, def.width, def.height, fitOptions) : file, { kind: def.uploadKind }, requestOptions);
 }
 
+//#endregion
+//#region src/core/entities.ts
+/**
+* Addressing per entity, following the Shopwave API reference
+* (https://developer.merchantstack.com/api-reference.html) and checked against
+* the live API where noted:
+* - category/product/store: GET filtered by `<x>Ids`, POST upsert, DELETE with `<x>Id` → 205.
+* - promotion: no DELETE; 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.
+* - productComponent: modifier groups, `/product/component` (live, staging, 11 Nov 2026). The
+*   API reference lists no read filters; these are what the live API does:
+*   - Reads filter by `componentIds` (group ids) or `productIds` (the parent product; option
+*     products don't match). `productComponentIds` is ignored on reads: every group comes back.
+*     `deleted: false` gives live groups only, `true` deleted groups only, no header both.
+*     No match → 204 with an empty body. No order, sort, priority or position field anywhere.
+*   - Groups are keyed by id; `products` (option products) by product id; `productInstances`
+*     (option rows) by row id. Reads reformat values: price `"100"` → `"100.0"`,
+*     vatPercentage `"0.2000"` → `"0.200"`. `tags` and `name` are stored as sent (no trimming;
+*     a `tags` array is joined with commas; `tags` null or left out → null).
+*   - POST upserts (201, echoed under the ref). For each option product in `products`, its rows
+*     are replaced: every row sent is created afresh with a new id (a row `id` is ignored, also
+*     on a price change) and rows left out are removed. Option products left out of the save
+*     are untouched, and an empty `productInstances` removes nothing. A save without `products`
+*     updates only the group's own fields. The echo isn't proof of what was stored: renames of
+*     groups created moments earlier by a test run echoed the new name but never stuck (re-read
+*     for 90 s), while older groups, and groups created in Shopwave's own admin, renamed at
+*     once. Cause not yet known.
+*   - DELETE with `productComponentIds` (plural, comma list) → 205, soft delete. Adding
+*     `productComponentInstanceIds` deletes just those rows (205); they stay in live reads with
+*     `deleteDate` set. The singular `productComponentId` hangs (504 after 60 s).
+*/
+const SHOPWAVE_ENTITIES = Object.freeze({
+	product: {
+		route: "products",
+		collection: "products",
+		upstream: "product",
+		idsHeader: "productIds",
+		idHeader: "productId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	category: {
+		route: "categories",
+		collection: "categories",
+		upstream: "category",
+		idsHeader: "categoryIds",
+		idHeader: "categoryId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	store: {
+		route: "stores",
+		collection: "stores",
+		upstream: "store",
+		idsHeader: "storeIds",
+		idHeader: "storeId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	promotion: {
+		route: "promotions",
+		collection: "promotions",
+		upstream: "promotion",
+		idsHeader: "promotionIds",
+		idHeader: "promotionId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
+	},
+	employee: {
+		route: "employees",
+		collection: "employees",
+		upstream: "employee",
+		idsHeader: "employeeIds",
+		idHeader: "employeeId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "exitDate"
+	},
+	consumer: {
+		route: "consumer",
+		collection: "consumers",
+		upstream: "consumer",
+		idsHeader: "ids",
+		idHeader: "consumerId",
+		writable: false,
+		deleteMode: "none"
+	},
+	productComponent: {
+		route: "product-components",
+		collection: "productComponents",
+		upstream: "product/component",
+		idsHeader: "componentIds",
+		idHeader: "productComponentIds",
+		writable: true,
+		deleteMode: "delete",
+		childIdsHeader: "productComponentInstanceIds"
+	}
+});
+
+//#endregion
+//#region src/core/productComponent.ts
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/**
+* Reads product components, optionally filtered by parent product and/or group id.
+* With no filter it returns every group on the merchant. Returns `[]` when nothing matches
+* (the API answers 204), and when a filter list is empty (no request is made).
+*
+* Rows deleted with {@link deleteProductComponentInstances} are still returned, with
+* `deleteDate` set; skip them when listing options.
+*/
+async function fetchProductComponents(params = {}, options = {}) {
+	const def = SHOPWAVE_ENTITIES.productComponent;
+	if (params.productIds?.length === 0 || params.productComponentIds?.length === 0) return [];
+	const extras = { deleted: params.deleted ?? false };
+	if (params.productIds) extras.productIds = params.productIds;
+	if (params.productComponentIds) extras[def.idsHeader] = params.productComponentIds;
+	const json = await apiGet(`/api/${def.route}`, extras, options);
+	assertNoApiErrors(json, 200);
+	const map = json?.[def.collection];
+	return isObject(map) ? Object.values(map) : [];
+}
+
+//#endregion
+//#region src/core/promotion.ts
+/**
+* Fetches promotions. Returns the flattened `Promotion[]`.
+*/
+async function fetchPromotions(params = {}, options = {}) {
+	const extras = { deleted: params.deleted ?? false };
+	if (params.promotionIds) extras.promotionIds = params.promotionIds;
+	if (params.imminent !== void 0) extras.imminent = params.imminent;
+	if (params.active !== void 0) extras.active = params.active;
+	if (params.expired !== void 0) extras.expired = params.expired;
+	const json = await apiGet("/api/promotions", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.promotions ?? {});
+}
+
+//#endregion
+//#region src/core/store.ts
+/**
+* Fetches stores. Returns the flattened `Store[]`.
+*/
+async function fetchStores(params = {}, options = {}) {
+	const extras = { deleted: params.deleted ?? false };
+	if (params.storeIds) extras.storeIds = params.storeIds;
+	const json = await apiGet("/api/stores", extras, withToken(options, params.token));
+	assertNoApiErrors(json, 200);
+	return Object.values(json?.stores ?? {});
+}
+
+//#endregion
+//#region src/core/report.ts
+/**
+* Runs one or more report queries and returns the `reports` map keyed by query
+* name. The query is JSON-encoded into the `extras.query` header, matching the
+* original endpoint contract.
+*/
+async function fetchReport(query, options = {}) {
+	const json = await apiGet("/api/report", { query: JSON.stringify(query) }, options);
+	assertNoApiErrors(json, 200);
+	return json?.reports ?? {};
+}
+
+//#endregion
+//#region src/core/session.ts
+/**
+* Reads the current login status from `GET /api/session`.
+*
+* Works with the new `react-shopwave-connect/next` session route
+* (`{ loggedIn }`) and with older routes that returned the raw session
+* (`{ token: {...} }`) — in that case only a boolean is surfaced.
+*/
+async function fetchSession(options = {}) {
+	const doFetch = options.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
+	if (!doFetch) throw new Error("No fetch implementation available. Pass `options.fetch`.");
+	const response = await doFetch(`${options.baseUrl ?? ""}/api/session`, {
+		method: "GET",
+		headers: { Accept: "application/json" },
+		cache: "no-store",
+		credentials: "same-origin",
+		signal: options.signal
+	});
+	if (response.status === 401) return { loggedIn: false };
+	if (!response.ok) throw new Error(`Session request failed (${response.status})`);
+	const json = await response.json();
+	if (json && typeof json.loggedIn === "boolean") return {
+		loggedIn: json.loggedIn,
+		expiresAt: typeof json.expiresAt === "number" ? json.expiresAt : void 0
+	};
+	return { loggedIn: Boolean(json && json.token) };
+}
+/**
+* Ends the current server session (no redirect).
+*
+* Prefer navigating to {@link logoutPath} when using
+* `react-shopwave-connect/next`: it also signs the user out of the auth server.
+*/
+async function logout(options = {}) {
+	await apiDelete("/api/session?action=logout", options);
+}
+
+//#endregion
+//#region src/core/entity.ts
+/**
+* Low-level, untyped mutations: the caller supplies the route and payload.
+*
+* Prefer the typed functions in `./entities` (`saveProduct`, `deleteCategory`,
+* …): they know each route, build the request envelope, check the response and
+* return the saved entity with its id. Keep these for routes that have no typed
+* function yet (e.g. `/api/merchant`).
+*/
+/**
+* Deletes `/api/{resourcePath}/{entityId}`.
+*/
+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/basket.ts
 const DEFAULT_BASKET_FILTERS = {
@@ -1227,6 +1360,25 @@ function useProductInstanceTags(options) {
 	}), [options?.baseUrl, options?.token], options?.enabled ?? true);
 }
 
+//#endregion
+//#region src/hooks/useProductComponent.ts
+/**
+* Auto-fetches product components (modifier groups) on mount and whenever the params change:
+* a product's groups with `{ productIds: [id] }`, one group with `{ productComponentIds: [id] }`,
+* or every group with no filter. Option rows with a `deleteDate` are included; skip them when
+* listing options.
+*/
+function useProductComponent(params = {}, options) {
+	return useQuery((signal) => fetchProductComponents(params, {
+		...options,
+		signal
+	}), [
+		JSON.stringify(params),
+		options?.baseUrl,
+		options?.token
+	]);
+}
+
 //#endregion
 //#region src/hooks/usePromotion.ts
 /**
@@ -1545,6 +1697,7 @@ exports.useEmployee = useEmployee;
 exports.useLogout = useLogout;
 exports.useMerchant = useMerchant;
 exports.useProduct = useProduct;
+exports.useProductComponent = useProductComponent;
 exports.useProductInstanceTags = useProductInstanceTags;
 exports.useProductTags = useProductTags;
 exports.usePromotion = usePromotion;