react-shopwave-connect 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -272,6 +272,64 @@ interface FetchProductsParams {
  * Fetches products. Returns the flattened `Product[]`.
  */
 declare function fetchProducts(params?: FetchProductsParams, options?: RequestOptions): Promise<Product[]>;
+/** An instance as a form or caller holds it: `id` is absent for new rows. */
+type ProductInstanceInput = {
+  id?: number | string | null;
+  price?: string | number | null;
+  taxPercentage?: string | number | null;
+  name?: string | null;
+};
+/** Instances as the API returns them (keyed by id) or as a plain list. */
+type ProductInstances<T = ProductInstanceInput> = Readonly<Record<string, T>> | Readonly<Record<number, T>> | ReadonlyArray<T>;
+/**
+ * What `saveProduct` accepts: any product fields, with `instances` either as the
+ * API returns them or as built by {@link toProductInstancesForSave}. Include `id`
+ * to update; leave it out to create.
+ */
+type ProductSaveInput = Partial<Omit<Product, "instances">> & {
+  instances?: ProductInstances;
+  [field: string]: unknown;
+};
+/** True when two instances have the same price and tax (the fields Shopwave won't update). */
+declare function isSameInstancePrice(a: ProductInstanceInput, b: ProductInstanceInput): boolean;
+/** An instance whose price or tax was edited, so saving it will give it a new id. */
+interface RepricedInstance {
+  /** Position of the instance in the list that was passed in. */
+  index: number;
+  /** The id it has now, which Shopwave will replace. */
+  id: number | string;
+  name: string;
+  before: {
+    price: string;
+    taxPercentage: string;
+  };
+  after: {
+    price: string;
+    taxPercentage: string;
+  };
+}
+/**
+ * Lists the instances whose price or tax differs from the `original` instance
+ * with the same id: saving them creates new instances with new ids, which can
+ * affect anything that stores instance ids (integrations, reports, modifiers).
+ * Use it to warn before saving. New rows (no id) aren't listed.
+ */
+declare function findRepricedInstances(instances: ProductInstances | null | undefined, original: ProductInstances | null | undefined): RepricedInstance[];
+/**
+ * Builds the `instances` map for a product save:
+ * - keyed by position (`"0"`, `"1"`, …), like every other ref in a save;
+ * - an instance keeps its `id` only when `original` has an instance with that id
+ *   and the same price and tax; otherwise the id is removed, so Shopwave creates
+ *   a new instance instead of re-pointing or rewriting someone else's;
+ * - server fields (`timestamp`) are removed.
+ *
+ * Pass the product as last read from the API as `original`. Leave it out for a
+ * new product (including a duplicate): every id is then removed.
+ * Instances left out of the list are left out of the save (removed).
+ */
+declare function toProductInstancesForSave<T extends ProductInstanceInput>(instances: ProductInstances<T> | null | undefined, original?: ProductInstances | null): Record<string, Omit<T, "id"> & {
+  id?: number | string;
+}>;
 /**
  * Fetches products by id and returns them keyed by id, transparently batching
  * the request (default 200 ids per call) to stay within API limits. Extracted
@@ -498,13 +556,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. */
@@ -516,7 +586,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.
@@ -560,7 +633,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
@@ -573,7 +647,16 @@ interface FetchByIdParams {
 }
 /** Reads one entity by id, or `null` when there's no such (non-deleted) record. */
 declare function fetchEntityById<K extends EntityKind>(kind: K, id: EntityId, params?: FetchByIdParams, options?: RequestOptions): Promise<EntityTypes[K] | null>;
-declare const saveProduct: (product: EntityInput<Product>, options?: RequestOptions) => Promise<Saved<Product>>;
+/**
+ * Creates (no `id`) or updates (with `id`) a product.
+ *
+ * Shopwave instances (prices) can't be updated, only replaced. Build
+ * `instances` with {@link toProductInstancesForSave} (passing the product as last
+ * read) so an edited price is sent as a new instance. As a safeguard, a new
+ * product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
+ * another product would otherwise point the save at that product's instances.
+ */
+declare const saveProduct: (product: ProductSaveInput, options?: RequestOptions) => Promise<Saved<Product>>;
 declare const deleteProduct: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchProduct: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Product | null>;
 declare const saveCategory: (category: EntityInput<Category>, options?: RequestOptions) => Promise<Saved<Category>>;
@@ -583,7 +666,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>;
 /**
@@ -1299,5 +1387,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, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, 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, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, 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, 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 };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -272,6 +272,64 @@ interface FetchProductsParams {
  * Fetches products. Returns the flattened `Product[]`.
  */
 declare function fetchProducts(params?: FetchProductsParams, options?: RequestOptions): Promise<Product[]>;
+/** An instance as a form or caller holds it: `id` is absent for new rows. */
+type ProductInstanceInput = {
+  id?: number | string | null;
+  price?: string | number | null;
+  taxPercentage?: string | number | null;
+  name?: string | null;
+};
+/** Instances as the API returns them (keyed by id) or as a plain list. */
+type ProductInstances<T = ProductInstanceInput> = Readonly<Record<string, T>> | Readonly<Record<number, T>> | ReadonlyArray<T>;
+/**
+ * What `saveProduct` accepts: any product fields, with `instances` either as the
+ * API returns them or as built by {@link toProductInstancesForSave}. Include `id`
+ * to update; leave it out to create.
+ */
+type ProductSaveInput = Partial<Omit<Product, "instances">> & {
+  instances?: ProductInstances;
+  [field: string]: unknown;
+};
+/** True when two instances have the same price and tax (the fields Shopwave won't update). */
+declare function isSameInstancePrice(a: ProductInstanceInput, b: ProductInstanceInput): boolean;
+/** An instance whose price or tax was edited, so saving it will give it a new id. */
+interface RepricedInstance {
+  /** Position of the instance in the list that was passed in. */
+  index: number;
+  /** The id it has now, which Shopwave will replace. */
+  id: number | string;
+  name: string;
+  before: {
+    price: string;
+    taxPercentage: string;
+  };
+  after: {
+    price: string;
+    taxPercentage: string;
+  };
+}
+/**
+ * Lists the instances whose price or tax differs from the `original` instance
+ * with the same id: saving them creates new instances with new ids, which can
+ * affect anything that stores instance ids (integrations, reports, modifiers).
+ * Use it to warn before saving. New rows (no id) aren't listed.
+ */
+declare function findRepricedInstances(instances: ProductInstances | null | undefined, original: ProductInstances | null | undefined): RepricedInstance[];
+/**
+ * Builds the `instances` map for a product save:
+ * - keyed by position (`"0"`, `"1"`, …), like every other ref in a save;
+ * - an instance keeps its `id` only when `original` has an instance with that id
+ *   and the same price and tax; otherwise the id is removed, so Shopwave creates
+ *   a new instance instead of re-pointing or rewriting someone else's;
+ * - server fields (`timestamp`) are removed.
+ *
+ * Pass the product as last read from the API as `original`. Leave it out for a
+ * new product (including a duplicate): every id is then removed.
+ * Instances left out of the list are left out of the save (removed).
+ */
+declare function toProductInstancesForSave<T extends ProductInstanceInput>(instances: ProductInstances<T> | null | undefined, original?: ProductInstances | null): Record<string, Omit<T, "id"> & {
+  id?: number | string;
+}>;
 /**
  * Fetches products by id and returns them keyed by id, transparently batching
  * the request (default 200 ids per call) to stay within API limits. Extracted
@@ -498,13 +556,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. */
@@ -516,7 +586,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.
@@ -560,7 +633,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
@@ -573,7 +647,16 @@ interface FetchByIdParams {
 }
 /** Reads one entity by id, or `null` when there's no such (non-deleted) record. */
 declare function fetchEntityById<K extends EntityKind>(kind: K, id: EntityId, params?: FetchByIdParams, options?: RequestOptions): Promise<EntityTypes[K] | null>;
-declare const saveProduct: (product: EntityInput<Product>, options?: RequestOptions) => Promise<Saved<Product>>;
+/**
+ * Creates (no `id`) or updates (with `id`) a product.
+ *
+ * Shopwave instances (prices) can't be updated, only replaced. Build
+ * `instances` with {@link toProductInstancesForSave} (passing the product as last
+ * read) so an edited price is sent as a new instance. As a safeguard, a new
+ * product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
+ * another product would otherwise point the save at that product's instances.
+ */
+declare const saveProduct: (product: ProductSaveInput, options?: RequestOptions) => Promise<Saved<Product>>;
 declare const deleteProduct: (id: EntityId, options?: RequestOptions) => Promise<void>;
 declare const fetchProduct: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Product | null>;
 declare const saveCategory: (category: EntityInput<Category>, options?: RequestOptions) => Promise<Saved<Category>>;
@@ -583,7 +666,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>;
 /**
@@ -1299,5 +1387,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, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, 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, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, 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, 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 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -42,8 +42,8 @@ function getApiErrorMap(body) {
 }
 function describeErrors(errors) {
 	return Object.entries(errors).map(([code, e]) => {
-		const text = [e?.title, e?.details].filter(Boolean).join(": ");
-		return text ? `${code} ${text}` : code;
+		const text$1 = [e?.title, e?.details].filter(Boolean).join(": ");
+		return text$1 ? `${code} ${text$1}` : code;
 	}).join("; ");
 }
 /**
@@ -105,12 +105,12 @@ function buildExtras(extras) {
 }
 /** Parses a response body as JSON; `null` for an empty body, `{ raw }` for non-JSON. */
 async function readBody(response) {
-	const text = await response.text();
-	if (!text) return null;
+	const text$1 = await response.text();
+	if (!text$1) return null;
 	try {
-		return JSON.parse(text);
+		return JSON.parse(text$1);
 	} catch {
-		return { raw: text };
+		return { raw: text$1 };
 	}
 }
 /**
@@ -258,6 +258,83 @@ async function fetchProducts(params = {}, options = {}) {
 	assertNoApiErrors(json, 200);
 	return Object.values(json?.products ?? {});
 }
+/** Fields the server sets on an instance; never sent back. */
+const SERVER_INSTANCE_FIELDS = ["timestamp"];
+function instanceList(instances) {
+	if (!instances) return [];
+	return (Array.isArray(instances) ? [...instances] : Object.values(instances)).filter((inst) => inst != null && typeof inst === "object");
+}
+function hasId(id) {
+	return id != null && String(id).trim() !== "";
+}
+/** Same number, so `"422.0"`, `"422"` and `422` are equal; blanks equal each other. */
+function sameAmount(a, b) {
+	const blank = (v) => v == null || String(v).trim() === "";
+	if (blank(a) || blank(b)) return blank(a) && blank(b);
+	const x = Number(a);
+	const y = Number(b);
+	return Number.isNaN(x) || Number.isNaN(y) ? String(a).trim() === String(b).trim() : x === y;
+}
+/** True when two instances have the same price and tax (the fields Shopwave won't update). */
+function isSameInstancePrice(a, b) {
+	return sameAmount(a.price, b.price) && sameAmount(a.taxPercentage, b.taxPercentage);
+}
+const text = (v) => v == null ? "" : String(v);
+/**
+* Lists the instances whose price or tax differs from the `original` instance
+* with the same id: saving them creates new instances with new ids, which can
+* affect anything that stores instance ids (integrations, reports, modifiers).
+* Use it to warn before saving. New rows (no id) aren't listed.
+*/
+function findRepricedInstances(instances, original) {
+	const byId = new Map(instanceList(original).filter((o) => hasId(o.id)).map((o) => [String(o.id), o]));
+	const result = [];
+	instanceList(instances).forEach((inst, index) => {
+		if (!hasId(inst.id)) return;
+		const before = byId.get(String(inst.id));
+		if (!before || isSameInstancePrice(inst, before)) return;
+		result.push({
+			index,
+			id: inst.id,
+			name: text(inst.name),
+			before: {
+				price: text(before.price),
+				taxPercentage: text(before.taxPercentage)
+			},
+			after: {
+				price: text(inst.price),
+				taxPercentage: text(inst.taxPercentage)
+			}
+		});
+	});
+	return result;
+}
+/**
+* Builds the `instances` map for a product save:
+* - keyed by position (`"0"`, `"1"`, …), like every other ref in a save;
+* - an instance keeps its `id` only when `original` has an instance with that id
+*   and the same price and tax; otherwise the id is removed, so Shopwave creates
+*   a new instance instead of re-pointing or rewriting someone else's;
+* - server fields (`timestamp`) are removed.
+*
+* Pass the product as last read from the API as `original`. Leave it out for a
+* new product (including a duplicate): every id is then removed.
+* Instances left out of the list are left out of the save (removed).
+*/
+function toProductInstancesForSave(instances, original) {
+	const keep = new Map(instanceList(original).filter((o) => hasId(o.id)).map((o) => [String(o.id), o]));
+	const out = {};
+	instanceList(instances).forEach((inst, index) => {
+		const { id,...rest } = inst;
+		for (const field of SERVER_INSTANCE_FIELDS) delete rest[field];
+		const before = hasId(id) ? keep.get(String(id)) : void 0;
+		out[String(index)] = before && isSameInstancePrice(inst, before) ? {
+			id,
+			...rest
+		} : rest;
+	});
+	return out;
+}
 /**
 * Fetches products by id and returns them keyed by id, transparently batching
 * the request (default 200 ids per call) to stay within API limits. Extracted
@@ -408,7 +485,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.
@@ -449,7 +529,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -524,7 +606,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
@@ -541,7 +624,21 @@ async function fetchEntityById(kind, id, params = {}, options = {}) {
 	const map = body?.[def.collection] ?? {};
 	return map[String(id)] ?? Object.values(map).find((e) => String(e?.id) === String(id)) ?? null;
 }
-const saveProduct = (product, options) => saveEntity("product", product, options);
+/**
+* Creates (no `id`) or updates (with `id`) a product.
+*
+* Shopwave instances (prices) can't be updated, only replaced. Build
+* `instances` with {@link toProductInstancesForSave} (passing the product as last
+* read) so an edited price is sent as a new instance. As a safeguard, a new
+* product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
+* another product would otherwise point the save at that product's instances.
+*/
+const saveProduct = (product, options) => {
+	return saveEntity("product", (product.id == null || String(product.id).trim() === "") && product.instances != null ? {
+		...product,
+		instances: toProductInstancesForSave(product.instances)
+	} : product, options);
+};
 const deleteProduct = (id, options) => deleteEntityById("product", id, options);
 const fetchProduct = (id, params, options) => fetchEntityById("product", id, params, options);
 const saveCategory = (category, options) => saveEntity("category", category, options);
@@ -551,7 +648,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);
 /**
@@ -1730,5 +1832,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, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, 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_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 };
 //# sourceMappingURL=index.js.map