react-shopwave-connect 0.4.1 → 0.4.3

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,7 +158,7 @@ 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.
@@ -226,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`; prices `toProductInstancesForSave`, `findRepricedInstances`, `isSameInstancePrice` |
+| product   | `fetchProducts`, `fetchProductsMap` (batched, keyed), `fetchProduct`, `saveProduct`, `deleteProduct`; prices `toProductInstancesForSave`, `findRepricedInstances`, `isSameInstancePrice`; tag lists `fetchProductTags`, `fetchProductInstanceTags` (`string[]`), `normalizeTagList` |
 | promotion | `fetchPromotions`, `fetchPromotion`, `savePromotion`, `deletePromotion` |
 | store     | `fetchStores` (now with `storeIds`), `fetchStore`, `saveStore`, `deleteStore` |
 | report    | `fetchReport`                                           |
@@ -281,7 +281,7 @@ const { data } = useProduct({ storeId }, { baseUrl: "https://api.merchantstack.c
 
 ### Auto-fetch hooks (`useEffect`-based)
 
-`useCategory`, `useConsumer`, `useEmployee`, `useProduct`, `usePromotion`, `useStore`, `useReport`, `useSession`, `useMerchant`, `useUser` (`useUser({ enabled: false })` stays idle).
+`useCategory`, `useConsumer`, `useEmployee`, `useProduct`, `useProductTags`, `useProductInstanceTags`, `usePromotion`, `useStore`, `useReport`, `useSession`, `useMerchant`, `useUser` (`useUser({ enabled: false })` stays idle; so do the tag hooks, so a tag field can load its list the first time it opens).
 They fetch on mount and re-run when their arguments change. `useConsumer` and `useReport` stay idle until you pass ids / a query (they return `loading: false`, `data: null` until then). `refetch()` replaces the old `reloadFlag` argument.
 
 ### Manually-triggered hooks (`useCallback`-based)
@@ -467,12 +467,19 @@ export const { GET } = shopwave.resource("user");
 
 // app/api/upload/route.ts         — image upload (uploadImage)
 export const { POST } = shopwave.upload();              // or upload({ maxBytes, accept })
+
+// app/api/products/tags/route.ts           — the merchant's product tags (fetchProductTags)
+export const { GET } = shopwave.lookup("productTags");
+// app/api/products/instance-tags/route.ts  — price-instance (channel) tags (fetchProductInstanceTags)
+export const { GET } = shopwave.lookup("productInstanceTags");
 ```
 
+- `lookup(kind)`: the read-only lists in `SHOPWAVE_LOOKUPS`. `productTags` → `GET /product/tags`, `productInstanceTags` → `GET /product/instance/tags`; both answer `{ tags: string[] }`. They take no parameters, so `extras` aren't forwarded. The app routes are `products/tags` and `products/instance-tags`: static segments, so they sit beside `products/[id]`.
+
 - `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:
 
@@ -503,6 +510,11 @@ Options: `apiVersion` (default `"2.0"`), `fetch`, `entities` (override a route/h
 
 ---
 
+## Contributing
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the package is built and the rules for changing it: layers, request flow, contract tables, endpoint kinds (and how to choose one), a checklist for adding an endpoint, code rules, known gaps, and versioning.
+- [CLAUDE.md](CLAUDE.md): the short rules for coding agents working in this repo.
+
 ## Build
 
 Built with [`tsdown`](https://tsdown.dev) into dual ESM + CJS with `.d.ts` types, via separate entries: `core` (no externals), `hooks` (`react`/`react-dom` external), `server` (no externals) and `next` (`next`/`iron-session` external — optional peer dependencies). `server` and `next` are never re-exported from the root entry, so they can't end up in client bundles.

package/dist/core/index.cjs

@@ -350,6 +350,106 @@ async function fetchProductsMap(productIds, options = {}, batchSize = 200) {
 	return result;
 }
 
+//#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);
+}
+const SHOPWAVE_LOOKUPS = Object.freeze({
+	productTags: {
+		route: "products/tags",
+		key: "tags",
+		upstream: "product/tags"
+	},
+	productInstanceTags: {
+		route: "products/instance-tags",
+		key: "tags",
+		upstream: "product/instance/tags"
+	}
+});
+
+//#endregion
+//#region src/core/productTags.ts
+/**
+* Turns a tag list from the API into clean strings: trims each tag, drops
+* blanks and anything that isn't text, and removes exact duplicates (first one
+* wins). The API's own order is kept. A map is accepted too (its values are
+* used), in case the API ever answers keyed by id.
+*/
+function normalizeTagList(value) {
+	const list = Array.isArray(value) ? value : value && typeof value === "object" ? Object.values(value) : [];
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const item of list) {
+		if (typeof item !== "string" && typeof item !== "number") continue;
+		const tag = String(item).trim();
+		if (!tag || seen.has(tag)) continue;
+		seen.add(tag);
+		out.push(tag);
+	}
+	return out;
+}
+async function fetchLookup(kind, options) {
+	const def = SHOPWAVE_LOOKUPS[kind];
+	if (!def) throw new Error(`Unknown Shopwave lookup "${kind}"`);
+	const json = await apiGet(`/api/${def.route}`, {}, options);
+	assertNoApiErrors(json, 200);
+	return normalizeTagList(json?.[def.key]);
+}
+/**
+* Every distinct tag used on the merchant's products (`GET /product/tags`),
+* for a tag field's suggestions. Returns `[]` when there are none.
+*/
+function fetchProductTags(options = {}) {
+	return fetchLookup("productTags", options);
+}
+/**
+* Every distinct tag used on the merchant's price instances
+* (`GET /product/instance/tags`): the channel names (Eat In, Takeout, …).
+* Returns `[]` when there are none.
+*/
+function fetchProductInstanceTags(options = {}) {
+	return fetchLookup("productInstanceTags", options);
+}
+
 //#endregion
 //#region src/core/promotion.ts
 /** Promotion rule identifiers as stored by the Shopwave API. */
@@ -484,7 +584,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.
@@ -525,7 +628,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -600,7 +705,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
@@ -641,7 +747,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);
 /**
@@ -800,50 +911,6 @@ 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
 /**
@@ -1294,6 +1361,7 @@ exports.MERCHANT_READ_ONLY_FIELDS = MERCHANT_READ_ONLY_FIELDS;
 exports.PromotionRuleSet = PromotionRuleSet;
 exports.SHOPWAVE_ENTITIES = SHOPWAVE_ENTITIES;
 exports.SHOPWAVE_IMAGE_BASE_URL = SHOPWAVE_IMAGE_BASE_URL;
+exports.SHOPWAVE_LOOKUPS = SHOPWAVE_LOOKUPS;
 exports.SHOPWAVE_RESOURCES = SHOPWAVE_RESOURCES;
 exports.SHOPWAVE_UPLOAD = SHOPWAVE_UPLOAD;
 exports.ShopwaveApiError = ShopwaveApiError;
@@ -1327,6 +1395,8 @@ exports.fetchEmployees = fetchEmployees;
 exports.fetchEntityById = fetchEntityById;
 exports.fetchMerchant = fetchMerchant;
 exports.fetchProduct = fetchProduct;
+exports.fetchProductInstanceTags = fetchProductInstanceTags;
+exports.fetchProductTags = fetchProductTags;
 exports.fetchProducts = fetchProducts;
 exports.fetchProductsMap = fetchProductsMap;
 exports.fetchPromotion = fetchPromotion;
@@ -1353,6 +1423,7 @@ exports.logoutPath = logoutPath;
 exports.merchantLinksFromForm = merchantLinksFromForm;
 exports.merchantLinksToForm = merchantLinksToForm;
 exports.normalizeMerchantLinks = normalizeMerchantLinks;
+exports.normalizeTagList = normalizeTagList;
 exports.parseBasketReportData = parseBasketReportData;
 exports.readImageSize = readImageSize;
 exports.rolesById = rolesById;