react-shopwave-connect 0.4.5 → 0.4.7

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,13 +210,13 @@ 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.
@@ -254,6 +254,7 @@ The shapes below are the ones adminV1 saves and adminV2 reads, so all three admi
 | consumer  | `fetchConsumers`, `fetchConsumer` (read-only)            |
 | employee  | `fetchEmployees`, `fetchEmployee`, `saveEmployee`, `deleteEmployee` |
 | product   | `fetchProducts`, `fetchProductsMap` (batched, keyed), `fetchProduct`, `saveProduct`, `deleteProduct`; prices `toProductInstancesForSave`, `findRepricedInstances`, `isSameInstancePrice`; images `productImageRole`, `toStoredProductImages`; tag lists `fetchProductTags`, `fetchProductInstanceTags` (`string[]`), `normalizeTagList` |
+| product component | `fetchProductComponents` (`productIds`, `productComponentIds`, `deleted`), `fetchProductComponent`, `saveProductComponent` (body built by `toProductComponentForSave`), `deleteProductComponent`, `deleteProductComponentInstances` (option rows) |
 | promotion | `fetchPromotions`, `fetchPromotion`, `savePromotion`, `deletePromotion` |
 | store     | `fetchStores` (now with `storeIds`), `fetchStore`, `saveStore`, `deleteStore` |
 | report    | `fetchReport`                                           |
@@ -308,7 +309,7 @@ const { data } = useProduct({ storeId }, { baseUrl: "https://api.merchantstack.c
 
 ### Auto-fetch hooks (`useEffect`-based)
 
-`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).
+`useCategory`, `useConsumer`, `useEmployee`, `useProduct`, `useProductComponent`, `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)
@@ -499,6 +500,11 @@ export const { POST } = shopwave.upload();              // or upload({ maxBytes,
 export const { GET } = shopwave.lookup("productTags");
 // app/api/products/instance-tags/route.ts  — price-instance (channel) tags (fetchProductInstanceTags)
 export const { GET } = shopwave.lookup("productInstanceTags");
+
+// app/api/product-components/route.ts       — modifier groups: list/filter, create/update
+export const { GET, POST, PUT } = shopwave.collection("productComponent");
+// app/api/product-components/[id]/route.ts  — read one, update, delete the group or some option rows
+export const { GET, PUT, DELETE } = shopwave.item("productComponent");
 ```
 
 - `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]`.
@@ -506,7 +512,7 @@ export const { GET } = shopwave.lookup("productInstanceTags");
 - `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` and an optional `prefix`, checks the size (default 10 MB → 413), type (default `image/*` → 415) and prefix (one of `UPLOAD_PREFIXES`, else 400), and `PUT`s only the file to `/uploader` with the `contentType` header, plus the `prefix` header when one was given. `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 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.
+Entities: `product`, `category`, `store`, `promotion`, `productComponent` (modifier groups, mounted at `/api/product-components`; DELETE with `extras` `{ productComponentInstanceIds }` deletes just those option rows, and a non-empty list of ids is required, else 400), `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:
 
@@ -530,7 +536,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.
@@ -561,7 +567,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, a create → read → update → delete-rows → delete lifecycle for Product components, plus unknown ids and the legacy `submitEntity` body. They create and delete real records on the account behind the token.
 
 ### Environment Variables
 
@@ -574,7 +580,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>
 
@@ -596,6 +602,7 @@ tests/
     request.test.ts                # token header, ShopwaveApiError, no logging
     entities.test.ts               # save/delete/fetch-by-id per entity
     api-routes.test.ts             # /api route handlers
+    product-components.test.ts     # product component functions and handlers
     query-state.test.ts            # useQuery keeps data while refetching
   integration/
     setup.ts                       # Shared config and helpers
@@ -603,6 +610,7 @@ tests/
     categories.integration.test.ts # Categories CRUD lifecycle
     consumers.integration.test.ts  # Consumers CRUD lifecycle
     employees.integration.test.ts  # Employees CRUD lifecycle
+    product-components.integration.test.ts  # Product components: create, read, update, delete rows, delete
 ```
 
 Each test file uses `describe.sequential` to guarantee execution order (create → read → update → delete) with shared state across tests. An `afterAll` cleanup ensures created resources are deleted even if a test fails midway.

package/dist/core/index.cjs

@@ -186,12 +186,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;
@@ -462,133 +465,6 @@ function fetchProductInstanceTags(options = {}) {
 	return fetchLookup("productInstanceTags", options);
 }
 
-//#endregion
-//#region src/core/promotion.ts
-/** Promotion rule identifiers as stored by the Shopwave API. */
-let PromotionRuleSet = /* @__PURE__ */ function(PromotionRuleSet$1) {
-	PromotionRuleSet$1["Percentage"] = "|%^/";
-	PromotionRuleSet$1["Combo"] = "&%</";
-	PromotionRuleSet$1["MealDeal"] = "&=^/";
-	return PromotionRuleSet$1;
-}({});
-/**
-* 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) };
-}
-/**
-* Path that starts a login and returns to `returnTo` afterwards.
-* Navigate the browser to it (`window.location.href = loginPath(...)`).
-*/
-function loginPath(returnTo, authPath = "/auth") {
-	return returnTo ? `${authPath}?returnTo=${encodeURIComponent(returnTo)}` : authPath;
-}
-/** Path that logs out of the app and the Shopwave auth server. */
-function logoutPath(authPath = "/auth") {
-	return `${authPath}/logout`;
-}
-/**
-* 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
 /**
@@ -875,7 +751,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) {
@@ -927,7 +803,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({
@@ -1018,7 +894,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) {
@@ -1039,7 +915,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};
@@ -1084,6 +960,27 @@ function toStoredProductImages(images) {
 * - 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: {
@@ -1143,6 +1040,16 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		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"
 	}
 });
 function definition(kind) {
@@ -1268,6 +1175,237 @@ const deleteEmployee = (id, options) => deleteEntityById("employee", id, options
 const fetchEmployee = (id, params, options) => fetchEntityById("employee", id, params, options);
 const fetchConsumer = (id, params, options) => fetchEntityById("consumer", id, params, options);
 
+//#endregion
+//#region src/core/productComponent.ts
+/** Row fields the server sets; never sent back. */
+const SERVER_ROW_FIELDS = [
+	"id",
+	"activeDate",
+	"deleteDate",
+	"timestamp"
+];
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function listOf(value) {
+	if (!value) return [];
+	if (Array.isArray(value)) return value.map((v) => [null, v]);
+	return Object.entries(value);
+}
+/**
+* Builds the save body for a product component from a group as read (or as a form holds it):
+* - `products` keyed by product id (a product without `id` takes its key);
+* - each product's rows keyed `"0"`, `"1"`, …, like every other ref in a save;
+* - rows that have a `deleteDate` are left out: the API recreates every row it's sent, so
+*   sending one back would bring a deleted option back as a new row;
+* - server row fields (`id`, `activeDate`, `deleteDate`, `timestamp`) are removed, since the
+*   API gives every row it's sent a new id anyway;
+* - a `tags` list becomes a comma string.
+*
+* The API replaces the rows of every option product in the save and leaves the others alone,
+* so send all the rows to keep for each product included. To remove an option product
+* entirely, delete its rows with {@link deleteProductComponentInstances}.
+*/
+function toProductComponentForSave(input) {
+	const { products,...group } = input;
+	if (products == null) return { ...group };
+	const out = {};
+	for (const [key, product] of listOf(products)) {
+		if (!isObject(product)) continue;
+		const id = product.id ?? key;
+		if (id == null || String(id).trim() === "") continue;
+		const { productInstances,...rest } = product;
+		const rows = {};
+		let index = 0;
+		for (const [, row] of listOf(productInstances)) {
+			if (!isObject(row) || row.deleteDate) continue;
+			const copy = { ...row };
+			for (const field of SERVER_ROW_FIELDS) delete copy[field];
+			if (Array.isArray(copy.tags)) copy.tags = copy.tags.map(String).join(",");
+			rows[String(index++)] = copy;
+		}
+		out[String(id)] = {
+			...rest,
+			id,
+			productInstances: rows
+		};
+	}
+	return {
+		...group,
+		products: out
+	};
+}
+/**
+* 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) : [];
+}
+/**
+* Reads one product component by id, or `null` when there's no such live group.
+* Note that `{ deleted: true }` returns the group only if it *has* been deleted.
+*/
+const fetchProductComponent = (id, params, options) => fetchEntityById("productComponent", id, params, options);
+/**
+* Creates (no `id`) or updates (with `id`) a product component and returns it with its id.
+* The body is built with {@link toProductComponentForSave}. Every option row sent is stored
+* under a new id, so re-read with {@link fetchProductComponent} for the stored rows.
+*/
+const saveProductComponent = (input, options) => saveEntity("productComponent", toProductComponentForSave(input), options);
+/** Deletes a product component (soft delete: `deleted: true` reads still return it). */
+const deleteProductComponent = (id, options) => deleteEntityById("productComponent", id, options);
+/**
+* Deletes some option rows of a product component, leaving the group and its other rows.
+* The rows stay in reads with `deleteDate` set. Throws without calling the API when
+* `instanceIds` is empty, because a delete without them would delete the whole group.
+*/
+async function deleteProductComponentInstances(id, instanceIds, options = {}) {
+	const def = SHOPWAVE_ENTITIES.productComponent;
+	const groupId = id == null ? "" : String(id).trim();
+	if (!groupId) throw new Error("productComponent id is missing");
+	const ids = (instanceIds ?? []).map((v) => String(v).trim()).filter(Boolean);
+	if (ids.length === 0) throw new Error("productComponent instance ids are missing");
+	await apiDelete(`/api/${def.route}/${encodeURIComponent(groupId)}`, options, { [def.childIdsHeader]: ids.join(",") });
+}
+
+//#endregion
+//#region src/core/promotion.ts
+/** Promotion rule identifiers as stored by the Shopwave API. */
+let PromotionRuleSet = /* @__PURE__ */ function(PromotionRuleSet$1) {
+	PromotionRuleSet$1["Percentage"] = "|%^/";
+	PromotionRuleSet$1["Combo"] = "&%</";
+	PromotionRuleSet$1["MealDeal"] = "&=^/";
+	return PromotionRuleSet$1;
+}({});
+/**
+* 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) };
+}
+/**
+* Path that starts a login and returns to `returnTo` afterwards.
+* Navigate the browser to it (`window.location.href = loginPath(...)`).
+*/
+function loginPath(returnTo, authPath = "/auth") {
+	return returnTo ? `${authPath}?returnTo=${encodeURIComponent(returnTo)}` : authPath;
+}
+/** Path that logs out of the app and the Shopwave auth server. */
+function logoutPath(authPath = "/auth") {
+	return `${authPath}/logout`;
+}
+/**
+* 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 = {
@@ -1441,9 +1579,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) {
@@ -1480,7 +1618,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));
 }
@@ -1628,6 +1766,8 @@ exports.deleteEmployee = deleteEmployee;
 exports.deleteEntity = deleteEntity;
 exports.deleteEntityById = deleteEntityById;
 exports.deleteProduct = deleteProduct;
+exports.deleteProductComponent = deleteProductComponent;
+exports.deleteProductComponentInstances = deleteProductComponentInstances;
 exports.deletePromotion = deletePromotion;
 exports.deleteStore = deleteStore;
 exports.fetchCategories = fetchCategories;
@@ -1639,6 +1779,8 @@ exports.fetchEmployees = fetchEmployees;
 exports.fetchEntityById = fetchEntityById;
 exports.fetchMerchant = fetchMerchant;
 exports.fetchProduct = fetchProduct;
+exports.fetchProductComponent = fetchProductComponent;
+exports.fetchProductComponents = fetchProductComponents;
 exports.fetchProductInstanceTags = fetchProductInstanceTags;
 exports.fetchProductTags = fetchProductTags;
 exports.fetchProducts = fetchProducts;
@@ -1681,10 +1823,12 @@ exports.saveEmployee = saveEmployee;
 exports.saveEntities = saveEntities;
 exports.saveEntity = saveEntity;
 exports.saveProduct = saveProduct;
+exports.saveProductComponent = saveProductComponent;
 exports.savePromotion = savePromotion;
 exports.saveStore = saveStore;
 exports.setMerchantImage = setMerchantImage;
 exports.submitEntity = submitEntity;
+exports.toProductComponentForSave = toProductComponentForSave;
 exports.toProductInstancesForSave = toProductInstancesForSave;
 exports.toShopwaveApiError = toShopwaveApiError;
 exports.toStoredImageIds = toStoredImageIds;