react-shopwave-connect 0.4.3 → 0.4.4

package/dist/hooks/index.d.cts

@@ -354,6 +354,19 @@ interface BasketPagination {
  * the correctly spelt names here and the server maps them.
  */
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
+/**
+ * The role an image plays, sent to Shopwave as the uploader's `prefix` header.
+ * The uploader names the file `<prefix>_<hash>.<ext>`, so the role travels with
+ * the file wherever a record stores it (a product's `images`). Live, merchant
+ * 5644, 4 Nov 2026: all four values answered 201.
+ * - `product`: a product gallery image;
+ * - `product_thumbnail`: the product's lead image, shown in lists;
+ * - `variant` / `variant_thumbnail`: a variant's own image and its lead image
+ *   (used by the Connect integrations).
+ *
+ * Values are the ones Connect's `uploadFileToShopwave` sends.
+ */
+type UploadPrefix = "product" | "product_thumbnail" | "variant" | "variant_thumbnail";
 //#endregion
 //#region src/core/imageFit.d.ts
 interface FitImageOptions {
@@ -369,6 +382,12 @@ interface FitImageOptions {
 interface UploadImageParams {
   /** What the image is for (sent to Shopwave as the uploader's `contentType`). */
   kind: UploadKind;
+  /**
+   * The image's role (sent to Shopwave as the uploader's `prefix` header), e.g.
+   * `product_thumbnail` for a product's lead image. Leave it out for images
+   * without a role (merchant logos).
+   */
+  prefix?: UploadPrefix;
   /** File name to send when `file` is a Blob without one. Defaults to `File.name`, else `"upload"`. */
   fileName?: string;
 }

package/dist/hooks/index.d.ts

@@ -354,6 +354,19 @@ interface BasketPagination {
  * the correctly spelt names here and the server maps them.
  */
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
+/**
+ * The role an image plays, sent to Shopwave as the uploader's `prefix` header.
+ * The uploader names the file `<prefix>_<hash>.<ext>`, so the role travels with
+ * the file wherever a record stores it (a product's `images`). Live, merchant
+ * 5644, 4 Nov 2026: all four values answered 201.
+ * - `product`: a product gallery image;
+ * - `product_thumbnail`: the product's lead image, shown in lists;
+ * - `variant` / `variant_thumbnail`: a variant's own image and its lead image
+ *   (used by the Connect integrations).
+ *
+ * Values are the ones Connect's `uploadFileToShopwave` sends.
+ */
+type UploadPrefix = "product" | "product_thumbnail" | "variant" | "variant_thumbnail";
 //#endregion
 //#region src/core/imageFit.d.ts
 interface FitImageOptions {
@@ -369,6 +382,12 @@ interface FitImageOptions {
 interface UploadImageParams {
   /** What the image is for (sent to Shopwave as the uploader's `contentType`). */
   kind: UploadKind;
+  /**
+   * The image's role (sent to Shopwave as the uploader's `prefix` header), e.g.
+   * `product_thumbnail` for a product's lead image. Leave it out for images
+   * without a role (merchant logos).
+   */
+  prefix?: UploadPrefix;
   /** File name to send when `file` is a Blob without one. Defaults to `File.name`, else `"upload"`. */
   fileName?: string;
 }

package/dist/hooks/index.js

@@ -291,17 +291,29 @@ const UPLOAD_KINDS = Object.freeze({
 	applicationLogo: "applicaionLogo",
 	applicationImages: "applicaionImages"
 });
+/** Every `UploadPrefix`, longest first so a name check never takes `product` for `product_thumbnail`. */
+const UPLOAD_PREFIXES = Object.freeze([
+	"product_thumbnail",
+	"variant_thumbnail",
+	"product",
+	"variant"
+]);
 /** How uploads are addressed (app route and Shopwave uploader). */
 const SHOPWAVE_UPLOAD = Object.freeze({
 	route: "upload",
 	upstream: "uploader",
 	kindHeader: "contentType",
+	prefixHeader: "prefix",
 	fileField: "file",
-	kindField: "kind"
+	kindField: "kind",
+	prefixField: "prefix"
 });
 function isUploadKind(value) {
 	return typeof value === "string" && Object.prototype.hasOwnProperty.call(UPLOAD_KINDS, value);
 }
+function isUploadPrefix(value) {
+	return typeof value === "string" && UPLOAD_PREFIXES.includes(value);
+}
 const SHOPWAVE_LOOKUPS = Object.freeze({
 	productTags: {
 		route: "products/tags",
@@ -468,150 +480,6 @@ async function submitEntity({ endpoint, method = "POST", payload }, options = {}
 	return json ?? void 0;
 }
 
-//#endregion
-//#region src/core/basket.ts
-const DEFAULT_BASKET_FILTERS = {
-	search: "",
-	dateRange: {
-		start: null,
-		end: null
-	},
-	consumerId: null,
-	status: "all"
-};
-const DEFAULT_PAGINATION = {
-	page: 0,
-	pageSize: 25,
-	total: 0
-};
-/** Formats a date as `YYYY-MM-DD HH:mm:ss` for the report query. */
-function formatDateForQuery(date, isEndOfDay = false) {
-	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")} ${isEndOfDay ? "23:59:59" : "00:00:00"}`;
-}
-/** Builds the `Basket` report query from a set of filters. */
-function buildBasketReportQuery(filters) {
-	const whereConditions = [];
-	const today = /* @__PURE__ */ new Date();
-	const startDate = filters.dateRange.start ?? today;
-	const endDate = filters.dateRange.end ?? today;
-	whereConditions.push(`Basket.completeDate > '${formatDateForQuery(startDate, false)}'`);
-	whereConditions.push(`Basket.completeDate < '${formatDateForQuery(endDate, true)}'`);
-	if (filters.consumerId) whereConditions.push(`Basket.consumerId = ${filters.consumerId}`);
-	if (filters.status !== "all") whereConditions.push(`Basket.status = '${filters.status}'`);
-	return { baskets: {
-		FROM: "Basket",
-		WHERE: whereConditions.length > 0 ? { AND: whereConditions } : void 0
-	} };
-}
-/** Flattens the raw report rows/keys into structured baskets. */
-function parseBasketReportData(reports) {
-	if (!reports?.baskets?.data || !reports?.baskets?.keys) return [];
-	const { keys, data } = reports.baskets;
-	const keyIndices = {};
-	keys.forEach((key, index) => {
-		keyIndices[key.name] = index;
-	});
-	const productKey = keys.find((k) => k.name === "Basket.Product");
-	const productSubKeys = {};
-	if (productKey?.item) productKey.item.forEach((subKey, index) => {
-		productSubKeys[subKey.name] = index;
-	});
-	return data.map((row) => {
-		const products = (row[keyIndices["Basket.Product"]] || []).map((productRow) => ({
-			productId: productRow[productSubKeys["Basket.Product.productId"]],
-			productName: `Product #${productRow[productSubKeys["Basket.Product.productId"]]}`,
-			quantity: productRow[productSubKeys["Basket.Product.quantity"]] || 1,
-			price: productRow[productSubKeys["Basket.Product.productPrice"]] || 0,
-			tax: productRow[productSubKeys["Basket.Product.productTaxPercentage"]] || 0
-		}));
-		const total = products.reduce((sum, p) => sum + p.price * p.quantity, 0);
-		const taxTotal = products.reduce((sum, p) => sum + p.price * p.quantity * p.tax, 0);
-		const completeDateTimestamp = row[keyIndices["Basket.completeDate"]];
-		const completeDate = completeDateTimestamp ? new Date(completeDateTimestamp).toISOString() : "";
-		return {
-			id: row[keyIndices["Basket.id"]],
-			name: row[keyIndices["Basket.name"]],
-			consumerId: row[keyIndices["Basket.consumerId"]],
-			products,
-			total,
-			taxTotal,
-			status: "completed",
-			completeDate
-		};
-	});
-}
-/** Unique non-null consumer ids referenced by a set of baskets. */
-function collectConsumerIds(baskets) {
-	if (!baskets.length) return null;
-	const ids = baskets.map((b) => b.consumerId).filter((id) => id != null);
-	return ids.length > 0 ? [...new Set(ids)] : null;
-}
-/** Unique product ids referenced by a set of baskets. */
-function collectProductIds(baskets) {
-	if (!baskets.length) return null;
-	const ids = /* @__PURE__ */ new Set();
-	baskets.forEach((basket) => {
-		basket.products.forEach((product) => {
-			if (product.productId) ids.add(product.productId);
-		});
-	});
-	return ids.size > 0 ? [...ids] : null;
-}
-/** Joins baskets with consumer + product lookups, applies search, sorts. */
-function combineBasketRows({ baskets, consumerMap, productMap, search }) {
-	if (!baskets.length) return [];
-	let combinedRows = baskets.map((basket) => {
-		const consumer = basket.consumerId ? consumerMap[basket.consumerId] : null;
-		const productsWithNames = basket.products.map((p) => {
-			const product = productMap[p.productId];
-			return {
-				...p,
-				productName: product?.name || `Product #${p.productId}`
-			};
-		});
-		return {
-			id: basket.id,
-			basketId: basket.id,
-			basketName: basket.name || `Basket #${basket.id}`,
-			consumerId: basket.consumerId,
-			consumerName: consumer ? `${consumer.firstName} ${consumer.lastName}` : "Unknown",
-			consumerEmail: consumer?.email || "-",
-			products: productsWithNames,
-			basketTotal: (basket.total || 0) / 100,
-			tax: basket.taxTotal || 0,
-			dateTime: basket.completeDate,
-			status: basket.status || "pending"
-		};
-	});
-	if (search) {
-		const searchLower = search.toLowerCase();
-		combinedRows = combinedRows.filter((row) => row.basketId.toString().includes(searchLower) || row.basketName.toLowerCase().includes(searchLower) || row.consumerName.toLowerCase().includes(searchLower) || row.consumerEmail.toLowerCase().includes(searchLower));
-	}
-	combinedRows.sort((a, b) => {
-		const dateA = new Date(a.dateTime).getTime();
-		return new Date(b.dateTime).getTime() - dateA;
-	});
-	return combinedRows;
-}
-/** Aggregate totals for a set of report rows. */
-function computeBasketSummary(rows) {
-	const uniqueConsumerIds = new Set(rows.map((row) => row.consumerId));
-	return {
-		totalBaskets: rows.length,
-		totalRevenue: rows.reduce((sum, row) => sum + row.basketTotal, 0),
-		totalTax: rows.reduce((sum, row) => sum + row.tax, 0),
-		uniqueConsumers: uniqueConsumerIds.size
-	};
-}
-/** Builds a consumer id → consumer lookup. */
-function buildConsumerMap(consumers) {
-	const map = {};
-	if (consumers) consumers.forEach((consumer) => {
-		map[consumer.id] = consumer;
-	});
-	return map;
-}
-
 //#endregion
 //#region src/core/imageFit.ts
 /**
@@ -722,10 +590,12 @@ function getImageUrl(path, base = SHOPWAVE_IMAGE_BASE_URL) {
 async function uploadImage(file, params, options = {}) {
 	if (!file || typeof file.size !== "number") throw new Error("uploadImage: file must be a File or Blob");
 	if (!isUploadKind(params?.kind)) throw new Error(`uploadImage: unknown kind "${params?.kind}"`);
+	if (params.prefix != null && !isUploadPrefix(params.prefix)) throw new Error(`uploadImage: unknown prefix "${params.prefix}"`);
 	const name = params.fileName ?? file.name ?? "upload";
 	const form = new FormData();
 	form.append(SHOPWAVE_UPLOAD.fileField, file, name);
 	form.append(SHOPWAVE_UPLOAD.kindField, params.kind);
+	if (params.prefix != null) form.append(SHOPWAVE_UPLOAD.prefixField, params.prefix);
 	const { status, body: raw } = await apiRequest(`/api/${SHOPWAVE_UPLOAD.route}`, {
 		method: "POST",
 		body: form
@@ -813,6 +683,150 @@ async function uploadMerchantImage(file, slot, options = {}) {
 	return uploadImage(fit ? await fitImageToSize(file, def.width, def.height, fitOptions) : file, { kind: def.uploadKind }, requestOptions);
 }
 
+//#endregion
+//#region src/core/basket.ts
+const DEFAULT_BASKET_FILTERS = {
+	search: "",
+	dateRange: {
+		start: null,
+		end: null
+	},
+	consumerId: null,
+	status: "all"
+};
+const DEFAULT_PAGINATION = {
+	page: 0,
+	pageSize: 25,
+	total: 0
+};
+/** Formats a date as `YYYY-MM-DD HH:mm:ss` for the report query. */
+function formatDateForQuery(date, isEndOfDay = false) {
+	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")} ${isEndOfDay ? "23:59:59" : "00:00:00"}`;
+}
+/** Builds the `Basket` report query from a set of filters. */
+function buildBasketReportQuery(filters) {
+	const whereConditions = [];
+	const today = /* @__PURE__ */ new Date();
+	const startDate = filters.dateRange.start ?? today;
+	const endDate = filters.dateRange.end ?? today;
+	whereConditions.push(`Basket.completeDate > '${formatDateForQuery(startDate, false)}'`);
+	whereConditions.push(`Basket.completeDate < '${formatDateForQuery(endDate, true)}'`);
+	if (filters.consumerId) whereConditions.push(`Basket.consumerId = ${filters.consumerId}`);
+	if (filters.status !== "all") whereConditions.push(`Basket.status = '${filters.status}'`);
+	return { baskets: {
+		FROM: "Basket",
+		WHERE: whereConditions.length > 0 ? { AND: whereConditions } : void 0
+	} };
+}
+/** Flattens the raw report rows/keys into structured baskets. */
+function parseBasketReportData(reports) {
+	if (!reports?.baskets?.data || !reports?.baskets?.keys) return [];
+	const { keys, data } = reports.baskets;
+	const keyIndices = {};
+	keys.forEach((key, index) => {
+		keyIndices[key.name] = index;
+	});
+	const productKey = keys.find((k) => k.name === "Basket.Product");
+	const productSubKeys = {};
+	if (productKey?.item) productKey.item.forEach((subKey, index) => {
+		productSubKeys[subKey.name] = index;
+	});
+	return data.map((row) => {
+		const products = (row[keyIndices["Basket.Product"]] || []).map((productRow) => ({
+			productId: productRow[productSubKeys["Basket.Product.productId"]],
+			productName: `Product #${productRow[productSubKeys["Basket.Product.productId"]]}`,
+			quantity: productRow[productSubKeys["Basket.Product.quantity"]] || 1,
+			price: productRow[productSubKeys["Basket.Product.productPrice"]] || 0,
+			tax: productRow[productSubKeys["Basket.Product.productTaxPercentage"]] || 0
+		}));
+		const total = products.reduce((sum, p) => sum + p.price * p.quantity, 0);
+		const taxTotal = products.reduce((sum, p) => sum + p.price * p.quantity * p.tax, 0);
+		const completeDateTimestamp = row[keyIndices["Basket.completeDate"]];
+		const completeDate = completeDateTimestamp ? new Date(completeDateTimestamp).toISOString() : "";
+		return {
+			id: row[keyIndices["Basket.id"]],
+			name: row[keyIndices["Basket.name"]],
+			consumerId: row[keyIndices["Basket.consumerId"]],
+			products,
+			total,
+			taxTotal,
+			status: "completed",
+			completeDate
+		};
+	});
+}
+/** Unique non-null consumer ids referenced by a set of baskets. */
+function collectConsumerIds(baskets) {
+	if (!baskets.length) return null;
+	const ids = baskets.map((b) => b.consumerId).filter((id) => id != null);
+	return ids.length > 0 ? [...new Set(ids)] : null;
+}
+/** Unique product ids referenced by a set of baskets. */
+function collectProductIds(baskets) {
+	if (!baskets.length) return null;
+	const ids = /* @__PURE__ */ new Set();
+	baskets.forEach((basket) => {
+		basket.products.forEach((product) => {
+			if (product.productId) ids.add(product.productId);
+		});
+	});
+	return ids.size > 0 ? [...ids] : null;
+}
+/** Joins baskets with consumer + product lookups, applies search, sorts. */
+function combineBasketRows({ baskets, consumerMap, productMap, search }) {
+	if (!baskets.length) return [];
+	let combinedRows = baskets.map((basket) => {
+		const consumer = basket.consumerId ? consumerMap[basket.consumerId] : null;
+		const productsWithNames = basket.products.map((p) => {
+			const product = productMap[p.productId];
+			return {
+				...p,
+				productName: product?.name || `Product #${p.productId}`
+			};
+		});
+		return {
+			id: basket.id,
+			basketId: basket.id,
+			basketName: basket.name || `Basket #${basket.id}`,
+			consumerId: basket.consumerId,
+			consumerName: consumer ? `${consumer.firstName} ${consumer.lastName}` : "Unknown",
+			consumerEmail: consumer?.email || "-",
+			products: productsWithNames,
+			basketTotal: (basket.total || 0) / 100,
+			tax: basket.taxTotal || 0,
+			dateTime: basket.completeDate,
+			status: basket.status || "pending"
+		};
+	});
+	if (search) {
+		const searchLower = search.toLowerCase();
+		combinedRows = combinedRows.filter((row) => row.basketId.toString().includes(searchLower) || row.basketName.toLowerCase().includes(searchLower) || row.consumerName.toLowerCase().includes(searchLower) || row.consumerEmail.toLowerCase().includes(searchLower));
+	}
+	combinedRows.sort((a, b) => {
+		const dateA = new Date(a.dateTime).getTime();
+		return new Date(b.dateTime).getTime() - dateA;
+	});
+	return combinedRows;
+}
+/** Aggregate totals for a set of report rows. */
+function computeBasketSummary(rows) {
+	const uniqueConsumerIds = new Set(rows.map((row) => row.consumerId));
+	return {
+		totalBaskets: rows.length,
+		totalRevenue: rows.reduce((sum, row) => sum + row.basketTotal, 0),
+		totalTax: rows.reduce((sum, row) => sum + row.tax, 0),
+		uniqueConsumers: uniqueConsumerIds.size
+	};
+}
+/** Builds a consumer id → consumer lookup. */
+function buildConsumerMap(consumers) {
+	const map = {};
+	if (consumers) consumers.forEach((consumer) => {
+		map[consumer.id] = consumer;
+	});
+	return map;
+}
+
 //#endregion
 //#region src/core/merchant.ts
 const MERCHANT_PATH = `/api/${SHOPWAVE_RESOURCES.merchant.route}`;