react-shopwave-connect 0.4.1 → 0.4.2

package/dist/core/index.d.cts

@@ -556,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. */
@@ -574,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.
@@ -618,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
@@ -650,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>;
 /**

package/dist/core/index.d.ts

@@ -556,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. */
@@ -574,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.
@@ -618,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
@@ -650,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>;
 /**

package/dist/core/index.js

@@ -483,7 +483,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.
@@ -524,7 +527,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -599,7 +604,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
@@ -640,7 +646,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);
 /**