react-shopwave-connect 0.4.1 → 0.4.3

package/dist/index.d.cts

@@ -340,6 +340,26 @@ declare function fetchProductsMap(productIds: number[] | null | undefined, optio
   [id: number]: Product;
 }>;
 //#endregion
+//#region src/core/productTags.d.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.
+ */
+declare function normalizeTagList(value: unknown): string[];
+/**
+ * Every distinct tag used on the merchant's products (`GET /product/tags`),
+ * for a tag field's suggestions. Returns `[]` when there are none.
+ */
+declare function fetchProductTags(options?: RequestOptions): Promise<string[]>;
+/**
+ * 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.
+ */
+declare function fetchProductInstanceTags(options?: RequestOptions): Promise<string[]>;
+//#endregion
 //#region src/core/promotion.d.ts
 /** Promotion rule identifiers as stored by the Shopwave API. */
 declare enum PromotionRuleSet {
@@ -537,8 +557,9 @@ declare function submitEntity<R = any>({
 //#region src/core/entities.d.ts
 /**
  * How each Shopwave entity is addressed, shared by the client functions below
- * and the server route handlers in `react-shopwave-connect/next`, so the two
- * halves of the contract can't drift apart.
+ * and the server route handlers in `react-shopwave-connect/server` (wrapped with
+ * the session by `react-shopwave-connect/next`), so the two halves of the
+ * contract can't drift apart.
  */
 interface EntityDefinition {
   /** App route segment: `/api/<route>` and `/api/<route>/<id>`. */
@@ -556,13 +577,25 @@ interface EntityDefinition {
   /**
    * How a delete is done upstream:
    * - `"delete"`: `DELETE {apiUrl}/<upstream>` with the `idHeader` (205, empty body)
-   * - `"retire"`: the API has no DELETE; the record is retired by POSTing
-   *   `{ id, [retireField]: <now> }` (employees: `exitDate`, promotions: `endDate`)
+   * - `"retire"`: the API has no DELETE; the record is retired by setting
+   *   `retireField` to now (employees: `exitDate`, promotions: `endDate`)
    * - `"none"`: can't be deleted
    */
   deleteMode: "delete" | "retire" | "none";
   /** Date field set to "now" when `deleteMode` is `"retire"`. */
   retireField?: string;
+  /**
+   * Retire by reading the record and POSTing all of it back with the date(s)
+   * changed, instead of a partial `{ id, [retireField]: <now> }`. Needed where
+   * the API rejects a partial save (promotions: error 899, live 14 Oct 2026).
+   */
+  retireWithRecord?: boolean;
+  /**
+   * Start-date field of a record retired with `retireWithRecord`. If the record
+   * hasn't started yet (start after now), the start moves to now as well, so
+   * start = end and the record is expired without ever running.
+   */
+  retireStartField?: string;
 }
 type EntityKind = "product" | "category" | "store" | "promotion" | "employee" | "consumer";
 /** Entities that can be created/updated through the API. */
@@ -574,7 +607,10 @@ type DeletableEntityKind = Exclude<EntityKind, "consumer">;
  * (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.
@@ -618,7 +654,8 @@ declare function saveEntity<K extends WritableEntityKind>(kind: K, item: EntityI
 /**
  * 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
@@ -650,7 +687,12 @@ declare const saveStore: (store: EntityInput<Store>, options?: RequestOptions) =
 declare const deleteStore: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchStore: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Store | null>;
 declare const savePromotion: (promotion: EntityInput<Promotion>, options?: RequestOptions) => Promise<Saved<Promotion>>;
-/** 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.
+ */
 declare const deletePromotion: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchPromotion: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Promotion | null>;
 /**
@@ -769,7 +811,7 @@ declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
  *
  * Like `SHOPWAVE_ENTITIES`, this table is shared by the client functions
  * (`fetchMerchant`, `fetchUser`, `uploadImage`, …) and the server route
- * handlers in `react-shopwave-connect/next`, so the two halves of the contract
+ * handlers in `react-shopwave-connect/server`, so the two halves of the contract
  * can't drift apart. These aren't in `SHOPWAVE_ENTITIES` because they aren't
  * keyed collections: `GET /merchant` answers `{ merchant: {…} }`, not a map by id.
  */
@@ -816,6 +858,35 @@ declare const SHOPWAVE_UPLOAD: Readonly<{
   kindField: "kind";
 }>;
 declare function isUploadKind(value: unknown): value is UploadKind;
+/**
+ * Read-only lists that aren't records: the merchant's distinct tags.
+ *
+ * Like `SHOPWAVE_RESOURCES`, shared by the client functions
+ * (`fetchProductTags`, `fetchProductInstanceTags`) and the server route
+ * handlers (`shopwave.lookup(kind)`), so the two halves can't drift apart.
+ *
+ * - productTags: `GET /product/tags` → `{ tags: string[] }`, every distinct tag
+ *   on the merchant's products. No parameters. The API reference says
+ *   "internal SKU tags are excluded", but the live API includes system tags
+ *   written by imports and syncs (`PID-133`, `VID-137`, `#Hash:…`, `upc-…`;
+ *   test merchant 5644, 29 Oct 2026). Apps that offer the list as suggestions
+ *   filter those themselves. Tags of deleted products drop out of the list.
+ * - productInstanceTags: `GET /product/instance/tags` → `{ tags: string[] }`,
+ *   the same for price instances (channels such as "Eat In", "Takeout").
+ *
+ * The app route for instance tags is `products/instance-tags`, one segment
+ * under `products`, so it sits beside `products/[id]` without nesting deeper.
+ */
+interface LookupDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the list in the response (`{ tags: [...] }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+}
+type LookupKind = "productTags" | "productInstanceTags";
+declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/core/imageFit.d.ts
 /**
@@ -1213,6 +1284,26 @@ declare function useEmployee(params?: FetchEmployeesParams, options?: RequestOpt
  */
 declare function useProduct(params?: FetchProductsParams, options?: RequestOptions): QueryState<Product[]>;
 //#endregion
+//#region src/hooks/useProductTags.d.ts
+type LookupOptions = RequestOptions & {
+  /** Fetch only when true (e.g. once a tag field is first opened). Defaults to true. */
+  enabled?: boolean;
+};
+/**
+ * The merchant's distinct product tags, for a tag field's suggestions.
+ * `data` is `string[]` once loaded.
+ *
+ * @example
+ * const [opened, setOpened] = useState(false);
+ * const { data: tags, loading } = useProductTags({ enabled: opened });
+ */
+declare function useProductTags(options?: LookupOptions): QueryState<string[]>;
+/**
+ * The merchant's distinct price-instance (channel) tags: Eat In, Takeout, …
+ * `data` is `string[]` once loaded.
+ */
+declare function useProductInstanceTags(options?: LookupOptions): QueryState<string[]>;
+//#endregion
 //#region src/hooks/usePromotion.d.ts
 /**
  * Auto-fetches promotions on mount and whenever the params change.
@@ -1366,5 +1457,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
+export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -340,6 +340,26 @@ declare function fetchProductsMap(productIds: number[] | null | undefined, optio
   [id: number]: Product;
 }>;
 //#endregion
+//#region src/core/productTags.d.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.
+ */
+declare function normalizeTagList(value: unknown): string[];
+/**
+ * Every distinct tag used on the merchant's products (`GET /product/tags`),
+ * for a tag field's suggestions. Returns `[]` when there are none.
+ */
+declare function fetchProductTags(options?: RequestOptions): Promise<string[]>;
+/**
+ * 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.
+ */
+declare function fetchProductInstanceTags(options?: RequestOptions): Promise<string[]>;
+//#endregion
 //#region src/core/promotion.d.ts
 /** Promotion rule identifiers as stored by the Shopwave API. */
 declare enum PromotionRuleSet {
@@ -537,8 +557,9 @@ declare function submitEntity<R = any>({
 //#region src/core/entities.d.ts
 /**
  * How each Shopwave entity is addressed, shared by the client functions below
- * and the server route handlers in `react-shopwave-connect/next`, so the two
- * halves of the contract can't drift apart.
+ * and the server route handlers in `react-shopwave-connect/server` (wrapped with
+ * the session by `react-shopwave-connect/next`), so the two halves of the
+ * contract can't drift apart.
  */
 interface EntityDefinition {
   /** App route segment: `/api/<route>` and `/api/<route>/<id>`. */
@@ -556,13 +577,25 @@ interface EntityDefinition {
   /**
    * How a delete is done upstream:
    * - `"delete"`: `DELETE {apiUrl}/<upstream>` with the `idHeader` (205, empty body)
-   * - `"retire"`: the API has no DELETE; the record is retired by POSTing
-   *   `{ id, [retireField]: <now> }` (employees: `exitDate`, promotions: `endDate`)
+   * - `"retire"`: the API has no DELETE; the record is retired by setting
+   *   `retireField` to now (employees: `exitDate`, promotions: `endDate`)
    * - `"none"`: can't be deleted
    */
   deleteMode: "delete" | "retire" | "none";
   /** Date field set to "now" when `deleteMode` is `"retire"`. */
   retireField?: string;
+  /**
+   * Retire by reading the record and POSTing all of it back with the date(s)
+   * changed, instead of a partial `{ id, [retireField]: <now> }`. Needed where
+   * the API rejects a partial save (promotions: error 899, live 14 Oct 2026).
+   */
+  retireWithRecord?: boolean;
+  /**
+   * Start-date field of a record retired with `retireWithRecord`. If the record
+   * hasn't started yet (start after now), the start moves to now as well, so
+   * start = end and the record is expired without ever running.
+   */
+  retireStartField?: string;
 }
 type EntityKind = "product" | "category" | "store" | "promotion" | "employee" | "consumer";
 /** Entities that can be created/updated through the API. */
@@ -574,7 +607,10 @@ type DeletableEntityKind = Exclude<EntityKind, "consumer">;
  * (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.
@@ -618,7 +654,8 @@ declare function saveEntity<K extends WritableEntityKind>(kind: K, item: EntityI
 /**
  * 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
@@ -650,7 +687,12 @@ declare const saveStore: (store: EntityInput<Store>, options?: RequestOptions) =
 declare const deleteStore: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchStore: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Store | null>;
 declare const savePromotion: (promotion: EntityInput<Promotion>, options?: RequestOptions) => Promise<Saved<Promotion>>;
-/** 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.
+ */
 declare const deletePromotion: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchPromotion: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Promotion | null>;
 /**
@@ -769,7 +811,7 @@ declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
  *
  * Like `SHOPWAVE_ENTITIES`, this table is shared by the client functions
  * (`fetchMerchant`, `fetchUser`, `uploadImage`, …) and the server route
- * handlers in `react-shopwave-connect/next`, so the two halves of the contract
+ * handlers in `react-shopwave-connect/server`, so the two halves of the contract
  * can't drift apart. These aren't in `SHOPWAVE_ENTITIES` because they aren't
  * keyed collections: `GET /merchant` answers `{ merchant: {…} }`, not a map by id.
  */
@@ -816,6 +858,35 @@ declare const SHOPWAVE_UPLOAD: Readonly<{
   kindField: "kind";
 }>;
 declare function isUploadKind(value: unknown): value is UploadKind;
+/**
+ * Read-only lists that aren't records: the merchant's distinct tags.
+ *
+ * Like `SHOPWAVE_RESOURCES`, shared by the client functions
+ * (`fetchProductTags`, `fetchProductInstanceTags`) and the server route
+ * handlers (`shopwave.lookup(kind)`), so the two halves can't drift apart.
+ *
+ * - productTags: `GET /product/tags` → `{ tags: string[] }`, every distinct tag
+ *   on the merchant's products. No parameters. The API reference says
+ *   "internal SKU tags are excluded", but the live API includes system tags
+ *   written by imports and syncs (`PID-133`, `VID-137`, `#Hash:…`, `upc-…`;
+ *   test merchant 5644, 29 Oct 2026). Apps that offer the list as suggestions
+ *   filter those themselves. Tags of deleted products drop out of the list.
+ * - productInstanceTags: `GET /product/instance/tags` → `{ tags: string[] }`,
+ *   the same for price instances (channels such as "Eat In", "Takeout").
+ *
+ * The app route for instance tags is `products/instance-tags`, one segment
+ * under `products`, so it sits beside `products/[id]` without nesting deeper.
+ */
+interface LookupDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the list in the response (`{ tags: [...] }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+}
+type LookupKind = "productTags" | "productInstanceTags";
+declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/core/imageFit.d.ts
 /**
@@ -1213,6 +1284,26 @@ declare function useEmployee(params?: FetchEmployeesParams, options?: RequestOpt
  */
 declare function useProduct(params?: FetchProductsParams, options?: RequestOptions): QueryState<Product[]>;
 //#endregion
+//#region src/hooks/useProductTags.d.ts
+type LookupOptions = RequestOptions & {
+  /** Fetch only when true (e.g. once a tag field is first opened). Defaults to true. */
+  enabled?: boolean;
+};
+/**
+ * The merchant's distinct product tags, for a tag field's suggestions.
+ * `data` is `string[]` once loaded.
+ *
+ * @example
+ * const [opened, setOpened] = useState(false);
+ * const { data: tags, loading } = useProductTags({ enabled: opened });
+ */
+declare function useProductTags(options?: LookupOptions): QueryState<string[]>;
+/**
+ * The merchant's distinct price-instance (channel) tags: Eat In, Takeout, …
+ * `data` is `string[]` once loaded.
+ */
+declare function useProductInstanceTags(options?: LookupOptions): QueryState<string[]>;
+//#endregion
 //#region src/hooks/usePromotion.d.ts
 /**
  * Auto-fetches promotions on mount and whenever the params change.
@@ -1366,5 +1457,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
+export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -351,6 +351,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. */
@@ -485,7 +585,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.
@@ -526,7 +629,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -601,7 +706,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
@@ -642,7 +748,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);
 /**
@@ -801,50 +912,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
 /**
@@ -1511,6 +1578,33 @@ function useProduct(params = {}, options) {
 	]);
 }
 
+//#endregion
+//#region src/hooks/useProductTags.ts
+/**
+* The merchant's distinct product tags, for a tag field's suggestions.
+* `data` is `string[]` once loaded.
+*
+* @example
+* const [opened, setOpened] = useState(false);
+* const { data: tags, loading } = useProductTags({ enabled: opened });
+*/
+function useProductTags(options) {
+	return useQuery((signal) => fetchProductTags({
+		...options,
+		signal
+	}), [options?.baseUrl, options?.token], options?.enabled ?? true);
+}
+/**
+* The merchant's distinct price-instance (channel) tags: Eat In, Takeout, …
+* `data` is `string[]` once loaded.
+*/
+function useProductInstanceTags(options) {
+	return useQuery((signal) => fetchProductInstanceTags({
+		...options,
+		signal
+	}), [options?.baseUrl, options?.token], options?.enabled ?? true);
+}
+
 //#endregion
 //#region src/hooks/usePromotion.ts
 /**
@@ -1821,5 +1915,5 @@ function useBasketReport(options) {
 }
 
 //#endregion
-export { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, PromotionRuleSet, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, ShopwaveApiError, UPLOAD_KINDS, apiDelete, apiGet, apiRequest, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
+export { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, PromotionRuleSet, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, ShopwaveApiError, UPLOAD_KINDS, apiDelete, apiGet, apiRequest, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.js.map