react-shopwave-connect 0.4.1 → 0.4.3

package/dist/next/index.d.cts

@@ -87,8 +87,9 @@ interface ShopwaveOAuthClient {
 //#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>`. */
@@ -106,13 +107,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";
 /**
@@ -120,7 +133,10 @@ type EntityKind = "product" | "category" | "store" | "promotion" | "employee" |
  * (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.
@@ -133,7 +149,7 @@ declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
  *
  * 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.
  */
@@ -166,6 +182,35 @@ declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefiniti
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
 /** `UploadKind` → the API's `contentType` value. */
 declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+/**
+ * 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/server/api.d.ts
 /**
@@ -288,6 +333,14 @@ interface ShopwaveApiHandlers {
   passthrough(path: string): {
     GET: RouteHandler;
   };
+  /**
+   * Handler for a read-only list (see `SHOPWAVE_LOOKUPS`), e.g.
+   * `app/api/products/tags/route.ts`: `export const { GET } = shopwave.lookup("productTags")`.
+   * Takes no parameters, so the caller's `extras` aren't forwarded.
+   */
+  lookup(kind: LookupKind): {
+    GET: RouteHandler;
+  };
   /** Handlers for a singleton resource: `app/api/merchant/route.ts`, `app/api/user/route.ts`. */
   resource(kind: ResourceKind): ResourceHandlers;
   /** Handler for `app/api/upload/route.ts`. */
@@ -495,9 +548,12 @@ interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorizatio
  * export const { GET } = shopwave.resource("user");
  * // app/api/upload/route.ts
  * export const { POST } = shopwave.upload();
+ * // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+ * export const { GET } = shopwave.lookup("productTags");
+ * export const { GET } = shopwave.lookup("productInstanceTags");
  * ```
  */
 declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, type LookupKind, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.cts.map

package/dist/next/index.d.ts

@@ -87,8 +87,9 @@ interface ShopwaveOAuthClient {
 //#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>`. */
@@ -106,13 +107,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";
 /**
@@ -120,7 +133,10 @@ type EntityKind = "product" | "category" | "store" | "promotion" | "employee" |
  * (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.
@@ -133,7 +149,7 @@ declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
  *
  * 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.
  */
@@ -166,6 +182,35 @@ declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefiniti
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
 /** `UploadKind` → the API's `contentType` value. */
 declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+/**
+ * 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/server/api.d.ts
 /**
@@ -288,6 +333,14 @@ interface ShopwaveApiHandlers {
   passthrough(path: string): {
     GET: RouteHandler;
   };
+  /**
+   * Handler for a read-only list (see `SHOPWAVE_LOOKUPS`), e.g.
+   * `app/api/products/tags/route.ts`: `export const { GET } = shopwave.lookup("productTags")`.
+   * Takes no parameters, so the caller's `extras` aren't forwarded.
+   */
+  lookup(kind: LookupKind): {
+    GET: RouteHandler;
+  };
   /** Handlers for a singleton resource: `app/api/merchant/route.ts`, `app/api/user/route.ts`. */
   resource(kind: ResourceKind): ResourceHandlers;
   /** Handler for `app/api/upload/route.ts`. */
@@ -495,9 +548,12 @@ interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorizatio
  * export const { GET } = shopwave.resource("user");
  * // app/api/upload/route.ts
  * export const { POST } = shopwave.upload();
+ * // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+ * export const { GET } = shopwave.lookup("productTags");
+ * export const { GET } = shopwave.lookup("productInstanceTags");
  * ```
  */
 declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, type LookupKind, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.ts.map

package/dist/next/index.js

@@ -255,7 +255,10 @@ function safeEqual(a, b) {
 * (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.
@@ -296,7 +299,9 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 		idHeader: "promotionId",
 		writable: true,
 		deleteMode: "retire",
-		retireField: "endDate"
+		retireField: "endDate",
+		retireWithRecord: true,
+		retireStartField: "startDate"
 	},
 	employee: {
 		route: "employees",
@@ -362,6 +367,18 @@ const SHOPWAVE_UPLOAD = Object.freeze({
 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/server/api.ts
@@ -495,6 +512,18 @@ function jsonError(status, error, message) {
 function shopwaveDateTime(date = /* @__PURE__ */ new Date()) {
 	return date.toISOString().slice(0, 19).replace("T", " ");
 }
+/**
+* Reads a Shopwave datetime: ISO with a zone (what reads return, e.g.
+* `2026-10-20T16:00:00.000Z`) or a zoneless `YYYY-MM-DD HH:mm:ss`, which is UTC.
+* `null` when the value isn't a date.
+*/
+function parseShopwaveDateTime(value) {
+	if (typeof value !== "string" || !value.trim()) return null;
+	const text = value.trim();
+	const zoneless = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2}(\.\d+)?)?$/.test(text);
+	const date = new Date(zoneless ? `${text.replace(" ", "T")}Z` : text);
+	return Number.isNaN(date.getTime()) ? null : date;
+}
 const NULL_BODY_STATUS = new Set([
 	101,
 	103,
@@ -694,6 +723,45 @@ function createShopwaveApiHandlers(config) {
 	function badId() {
 		return jsonError(400, "invalid_id", "Missing or invalid id");
 	}
+	/**
+	* Retires a record the API won't take a partial save for (promotions): reads it,
+	* sets `field` to now (and `def.retireStartField` to now too when the record
+	* hasn't started yet), and POSTs the whole record back. Both dates are sent as
+	* UTC `YYYY-MM-DD HH:mm:ss`; reads return them as ISO with `Z`.
+	*/
+	async function retireWithRecord(request, def, id, field) {
+		const read = await forward(request, {
+			path: def.upstream,
+			headers: { [def.idsHeader]: id },
+			forwardExtras: false
+		});
+		if (!read.ok) return read;
+		let body;
+		try {
+			body = await read.json();
+		} catch {
+			return jsonError(502, "invalid_upstream", `The Shopwave API's ${def.upstream} read wasn't JSON`);
+		}
+		const map = isPlainObject(body) && isPlainObject(body[def.collection]) ? body[def.collection] : {};
+		const record = Object.values(map).find((entry) => isPlainObject(entry) && String(entry.id) === id);
+		if (!record) return jsonError(404, "not_found", `No ${def.upstream} with id ${id}`);
+		const now = /* @__PURE__ */ new Date();
+		const retired = {
+			...record,
+			[field]: shopwaveDateTime(now)
+		};
+		const startField = def.retireStartField;
+		if (startField) {
+			const start = parseShopwaveDateTime(record[startField]);
+			if (start) retired[startField] = shopwaveDateTime(start > now ? now : start);
+		}
+		return forward(request, {
+			method: "POST",
+			path: def.upstream,
+			postBody: { [def.collection]: { 0: retired } },
+			forwardExtras: false
+		});
+	}
 	return {
 		forward,
 		entity,
@@ -729,6 +797,7 @@ function createShopwaveApiHandlers(config) {
 					if (def.deleteMode === "none") return notSupported(def, "deletes");
 					if (def.deleteMode === "retire") {
 						const field = def.retireField ?? "exitDate";
+						if (def.retireWithRecord) return retireWithRecord(request, def, id, field);
 						return forward(request, {
 							method: "POST",
 							path: def.upstream,
@@ -751,6 +820,14 @@ function createShopwaveApiHandlers(config) {
 		passthrough(path) {
 			return { GET: (request) => forward(request, { path }) };
 		},
+		lookup(kind) {
+			const def = SHOPWAVE_LOOKUPS[kind];
+			if (!def) throw new Error(`Unknown Shopwave lookup "${kind}"`);
+			return { GET: (request) => forward(request, {
+				path: def.upstream,
+				forwardExtras: false
+			}) };
+		},
 		resource(kind) {
 			const def = resourceDef(kind);
 			const save = (request) => writeResource(request, def);
@@ -1093,6 +1170,9 @@ function createShopwaveAuth(config) {
 * export const { GET } = shopwave.resource("user");
 * // app/api/upload/route.ts
 * export const { POST } = shopwave.upload();
+* // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+* export const { GET } = shopwave.lookup("productTags");
+* export const { GET } = shopwave.lookup("productInstanceTags");
 * ```
 */
 function createShopwaveApi(config) {
@@ -1105,5 +1185,5 @@ function createShopwaveApi(config) {
 }
 
 //#endregion
-export { SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+export { SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.js.map