@decocms/apps-vtex 7.2.0

package/src/commerceLoaders.ts

@@ -0,0 +1,261 @@
+/**
+ * Standard VTEX commerce loader map factory for CMS block resolution.
+ *
+ * Wraps all VTEX loaders with createCachedLoader, applies universal
+ * workarounds (slug fallback, IS sort sanitization, map=productClusterIds),
+ * and registers both `.ts` and `.ts`-less aliases.
+ *
+ * Sites call `createVtexCommerceLoaders()` instead of manually wiring ~30
+ * individual loader entries. Site-specific loaders are merged via `extra`.
+ */
+
+import { createCachedLoader } from "@decocms/blocks/sdk/cachedLoader";
+import type { CacheProfileName } from "@decocms/blocks/sdk/cacheHeaders";
+import { getCategoryTree } from "./loaders/catalog";
+import vtexProductDetailsPage from "./loaders/intelligentSearch/productDetailsPage";
+import vtexProductListShelf from "./loaders/intelligentSearch/productList";
+import vtexProductListingPage from "./loaders/intelligentSearch/productListingPage";
+import vtexSuggestions from "./loaders/intelligentSearch/suggestions";
+import vtexRelatedProducts from "./loaders/legacy/relatedProductsLoader";
+import vtexProductList from "./loaders/productListFull";
+import vtexWorkflowProducts from "./loaders/workflow/products";
+import { VALID_IS_SORTS } from "./utils/intelligentSearch";
+
+export type CommerceLoaderFn = (props: any) => Promise<any>;
+
+export interface VtexCommerceLoadersOptions {
+	/** Override cache profiles per loader type. */
+	cacheProfiles?: {
+		listing?: CacheProfileName;
+		product?: CacheProfileName;
+		search?: CacheProfileName;
+		static?: CacheProfileName;
+	};
+	/** Additional loaders to merge into the map (site-specific). */
+	extra?: Record<string, CommerceLoaderFn>;
+}
+
+/**
+ * Bridge __pagePath → slug when CMS doesn't set slug explicitly.
+ * VTEX PDP pages receive __pagePath (e.g. "/produto-slug/p") but the
+ * inline loader only reads the `slug` field.
+ */
+function pdpWithSlugFallback(props: any): Promise<any> {
+	if ((!props.slug || props.slug.length === 0) && props.__pagePath) {
+		props = { ...props, slug: props.__pagePath };
+	}
+	return vtexProductDetailsPage(props);
+}
+
+/**
+ * Extract collection name from PLP product data.
+ * Products carry cluster info in additionalProperty with name="cluster".
+ */
+function extractCollectionName(result: any, collectionId: string): string | null {
+	if (!result?.products?.length) return null;
+	for (const product of result.products) {
+		const props = product.additionalProperty || product.isVariantOf?.additionalProperty || [];
+		for (const prop of props) {
+			if (prop.name === "cluster" && prop.propertyID === collectionId) {
+				return prop.value || null;
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Returns the standard VTEX commerce loader map for CMS resolution.
+ *
+ * Includes all Intelligent Search, legacy, category tree, and navbar loaders
+ * with SWR caching. Also registers `.ts`-less aliases for invoke compatibility.
+ *
+ * @example
+ * ```ts
+ * import { createVtexCommerceLoaders } from "@decocms/apps/vtex/commerceLoaders";
+ *
+ * const COMMERCE_LOADERS = {
+ *   ...createVtexCommerceLoaders(),
+ *   // site-specific only:
+ *   "site/loaders/myCustomLoader": async (props) => { ... },
+ * };
+ * registerCommerceLoaders(COMMERCE_LOADERS);
+ * ```
+ */
+export function createVtexCommerceLoaders(
+	options?: VtexCommerceLoadersOptions,
+): Record<string, CommerceLoaderFn> {
+	const profiles = {
+		listing: options?.cacheProfiles?.listing ?? "listing",
+		product: options?.cacheProfiles?.product ?? "product",
+		search: options?.cacheProfiles?.search ?? "search",
+		static: options?.cacheProfiles?.static ?? "static",
+	};
+
+	const _cachedProductList = createCachedLoader(
+		"vtex/productList",
+		vtexProductList,
+		profiles.listing,
+	);
+	const cachedProductListShelf = createCachedLoader(
+		"vtex/productListShelf",
+		vtexProductListShelf,
+		profiles.listing,
+	);
+	const cachedPDP = createCachedLoader(
+		"vtex/productDetailsPage",
+		pdpWithSlugFallback,
+		profiles.product,
+	);
+	const _cachedPLP = createCachedLoader(
+		"vtex/productListingPage",
+		vtexProductListingPage,
+		profiles.listing,
+	);
+	const cachedSuggestions = createCachedLoader(
+		"vtex/suggestions",
+		vtexSuggestions,
+		profiles.search,
+	);
+	const cachedRelatedProducts = createCachedLoader(
+		"vtex/relatedProducts",
+		vtexRelatedProducts,
+		profiles.product,
+	);
+	const cachedWorkflowProducts = createCachedLoader(
+		"vtex/workflowProducts",
+		vtexWorkflowProducts,
+		profiles.listing,
+	);
+
+	/**
+	 * PLP wrapper: handles `map=productClusterIds` legacy URLs and sanitizes
+	 * IS sort parameters that would cause VTEX API 400 errors.
+	 */
+	const cachedPLP: CommerceLoaderFn = async (props) => {
+		if (props.__pageUrl && !props.selectedFacets?.length) {
+			try {
+				const pageUrl = new URL(props.__pageUrl, "https://localhost");
+				const mapParam = pageUrl.searchParams.get("map");
+				if (mapParam && props.__pagePath) {
+					const segments = props.__pagePath.split("/").filter(Boolean);
+					const mapValues = mapParam.split(",");
+					const facets: Array<{ key: string; value: string }> = [];
+					for (let i = 0; i < Math.min(segments.length, mapValues.length); i++) {
+						const key = mapValues[i].trim();
+						const value = decodeURIComponent(segments[i]);
+						if (key && value) facets.push({ key, value });
+					}
+					if (facets.length) {
+						const rawSort = pageUrl.searchParams.get("sort") ?? "";
+						const cleanSort = VALID_IS_SORTS.has(rawSort) ? rawSort : "";
+
+						if (rawSort !== cleanSort) {
+							if (cleanSort) {
+								pageUrl.searchParams.set("sort", cleanSort);
+							} else {
+								pageUrl.searchParams.delete("sort");
+							}
+						}
+
+						const result = await _cachedPLP({
+							...props,
+							selectedFacets: facets,
+							sort: cleanSort || undefined,
+							__pageUrl: pageUrl.toString(),
+						});
+
+						const clusterFacet = facets.find((f) => f.key === "productClusterIds");
+						if (result && clusterFacet) {
+							const collectionName = extractCollectionName(result, clusterFacet.value);
+							if (collectionName) {
+								result.breadcrumb = {
+									"@type": "BreadcrumbList",
+									itemListElement: [
+										{
+											"@type": "ListItem",
+											name: collectionName,
+											item: props.__pagePath || "/",
+											position: 1,
+										},
+									],
+									numberOfItems: 1,
+								};
+								result.seo = { ...result.seo, title: collectionName };
+							}
+						}
+						return result;
+					}
+				}
+			} catch (e) {
+				console.error("[PLP] Error parsing map param:", e);
+			}
+		}
+		return _cachedPLP(props);
+	};
+
+	/**
+	 * Related products wrapper: extracts slug from __pagePath when the CMS
+	 * requestToParam stub returns null (standard in TanStack sites).
+	 */
+	const relatedWithSlugFallback: CommerceLoaderFn = (props) => {
+		if (!props.slug && props.__pagePath) {
+			const path = props.__pagePath.replace(/\/p$/, "").replace(/^\//, "");
+			props = { ...props, slug: path };
+		}
+		return cachedRelatedProducts(props);
+	};
+
+	const loaders: Record<string, CommerceLoaderFn> = {
+		// Intelligent Search loaders
+		"vtex/loaders/intelligentSearch/productListingPage.ts": cachedPLP,
+		"vtex/loaders/intelligentSearch/productList.ts": cachedProductListShelf,
+		"vtex/loaders/intelligentSearch/productDetailsPage.ts": cachedPDP,
+		"vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+		// Legacy loaders (map to same cached functions)
+		"vtex/loaders/legacy/productDetailsPage.ts": cachedPDP,
+		"vtex/loaders/legacy/productList.ts": cachedProductListShelf,
+		"vtex/loaders/legacy/relatedProductsLoader.ts": relatedWithSlugFallback,
+		// Workflow
+		"vtex/loaders/workflow/products.ts": cachedWorkflowProducts,
+		// Top-level aliases (used by some CMS block configs)
+		"vtex/loaders/ProductList.ts": cachedProductListShelf,
+		"vtex/loaders/ProductDetailsPage.ts": cachedPDP,
+		"vtex/loaders/ProductListingPage.ts": cachedPLP,
+		// Category tree
+		"vtex/loaders/categories/tree": (props: any) => getCategoryTree(props?.categoryLevels ?? 3),
+		// Commerce passthrough loaders
+		"commerce/loaders/navbar.ts": async (props: any) => props.items ?? [],
+		"commerce/loaders/product/extensions/detailsPage.ts": async (props: any) => {
+			const data = props.data;
+			if (data?.product) return data;
+			return cachedPDP({ __pagePath: props.__pagePath });
+		},
+		// requestToParam stub — unresolvable in TanStack, pdpWithSlugFallback bridges it
+		"website/functions/requestToParam.ts": async () => null,
+	};
+
+	// Register .ts-less aliases for invoke compatibility
+	const withAliases: Record<string, CommerceLoaderFn> = { ...loaders };
+	for (const key of Object.keys(loaders)) {
+		if (key.endsWith(".ts")) {
+			withAliases[key.slice(0, -3)] = loaders[key];
+		}
+	}
+
+	if (options?.extra) {
+		Object.assign(withAliases, options.extra);
+	}
+
+	return withAliases;
+}
+
+/**
+ * Exposes the cached PDP loader for site-specific section loaders that need
+ * to call it directly (e.g. ProductDescription fallback).
+ *
+ * Returns a new instance each call — sites should cache the reference.
+ */
+export function createCachedPDPLoader(profile: CacheProfileName = "product"): CommerceLoaderFn {
+	return createCachedLoader("vtex/productDetailsPage", pdpWithSlugFallback, profile);
+}

package/src/hooks/__tests__/createUseCart.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests for the `createUseCart` factory.
+ *
+ * The hook itself depends on React (useState/useEffect), and apps-start
+ * does not pull in @testing-library/react. So we test the parts of the
+ * factory that don't require a React renderer: shape, isolation, and the
+ * pure `itemToAnalyticsItem` helper. Hook semantics are exercised by the
+ * site-level integration smoke test (the template has shipped to two
+ * production sites).
+ */
+
+import { describe, expect, it } from "vitest";
+import { type CreateUseCartInvoke, createUseCart } from "../createUseCart";
+
+function makeInvoke(): CreateUseCartInvoke {
+	const noop = async () => ({ orderFormId: "of-1", items: [] }) as never;
+	return {
+		vtex: {
+			actions: {
+				getOrCreateCart: noop,
+				addItemsToCart: noop,
+				updateCartItems: noop,
+				addCouponToCart: noop,
+				updateOrderFormAttachment: noop,
+				simulateCart: noop,
+			},
+		},
+	};
+}
+
+describe("createUseCart — factory shape", () => {
+	it("returns useCart, resetCart, itemToAnalyticsItem", () => {
+		const cart = createUseCart({ invoke: makeInvoke() });
+		expect(typeof cart.useCart).toBe("function");
+		expect(typeof cart.resetCart).toBe("function");
+		expect(typeof cart.itemToAnalyticsItem).toBe("function");
+	});
+
+	it("two factory calls produce independent itemToAnalyticsItem references", () => {
+		const a = createUseCart({ invoke: makeInvoke() });
+		const b = createUseCart({ invoke: makeInvoke() });
+		// Different closures => different function identities.
+		expect(a.itemToAnalyticsItem).not.toBe(b.itemToAnalyticsItem);
+		expect(a.useCart).not.toBe(b.useCart);
+		expect(a.resetCart).not.toBe(b.resetCart);
+	});
+
+	it("accepts custom orderFormCookieName / maxAge without throwing", () => {
+		expect(() =>
+			createUseCart({
+				invoke: makeInvoke(),
+				orderFormCookieName: "custom_of_id",
+				orderFormCookieMaxAge: 3600,
+			}),
+		).not.toThrow();
+	});
+});
+
+describe("createUseCart — itemToAnalyticsItem", () => {
+	const { itemToAnalyticsItem } = createUseCart({ invoke: makeInvoke() });
+
+	it("maps the canonical fields", () => {
+		const out = itemToAnalyticsItem(
+			{
+				id: "sku-1",
+				productId: "prod-1",
+				name: "Widget",
+				skuName: "Widget Blue",
+				sellingPrice: 1990,
+				price: 2490,
+				listPrice: 2490,
+				quantity: 2,
+				seller: "1",
+				additionalInfo: { brandName: "Acme" },
+			} as never,
+			0,
+		);
+		expect(out).toEqual({
+			item_id: "prod-1",
+			item_group_id: "prod-1",
+			item_name: "Widget",
+			item_variant: "Widget Blue",
+			item_brand: "Acme",
+			price: 19.9,
+			discount: 5,
+			quantity: 2,
+			coupon: undefined,
+			affiliation: "1",
+			index: 0,
+		});
+	});
+
+	it("falls back to skuName when name is missing", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				skuName: "Fallback",
+				sellingPrice: 100,
+				listPrice: 100,
+				quantity: 1,
+				seller: "1",
+			} as never,
+			3,
+		);
+		expect(out.item_name).toBe("Fallback");
+		expect(out.index).toBe(3);
+	});
+
+	it("uses price when sellingPrice is missing", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				name: "n",
+				price: 1000,
+				listPrice: 1000,
+				quantity: 1,
+				seller: "1",
+			} as never,
+			0,
+		);
+		expect(out.price).toBe(10);
+	});
+
+	it("computes zero discount when listPrice equals sellingPrice", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				name: "n",
+				sellingPrice: 500,
+				listPrice: 500,
+				quantity: 1,
+				seller: "1",
+			} as never,
+			0,
+		);
+		expect(out.discount).toBe(0);
+	});
+
+	it("rounds discount to 2 decimal places", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				name: "n",
+				sellingPrice: 1000,
+				listPrice: 1333,
+				quantity: 1,
+				seller: "1",
+			} as never,
+			0,
+		);
+		expect(out.discount).toBe(3.33);
+	});
+
+	it("preserves coupon when supplied", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				name: "n",
+				sellingPrice: 100,
+				listPrice: 100,
+				quantity: 1,
+				seller: "1",
+				coupon: "SAVE10",
+			} as never,
+			0,
+		);
+		expect(out.coupon).toBe("SAVE10");
+	});
+
+	it("uses empty string brand when additionalInfo is missing", () => {
+		const out = itemToAnalyticsItem(
+			{
+				productId: "p",
+				name: "n",
+				sellingPrice: 100,
+				listPrice: 100,
+				quantity: 1,
+				seller: "1",
+			} as never,
+			0,
+		);
+		expect(out.item_brand).toBe("");
+	});
+});

package/src/hooks/__tests__/createUseUser.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Tests for the `createUseUser` factory.
+ *
+ * Same approach as `createUseCart.test.ts`: apps-start does not pull
+ * @testing-library/react, so we test factory shape and isolation. Hook
+ * semantics are covered by site-level smoke tests.
+ */
+
+import { describe, expect, it } from "vitest";
+import { type CreateUseUserInvoke, createUseUser } from "../createUseUser";
+
+function makeInvoke(): CreateUseUserInvoke {
+	return {
+		vtex: {
+			loaders: {
+				user: async () => null,
+			},
+		},
+	};
+}
+
+describe("createUseUser — factory shape", () => {
+	it("returns useUser, resetUser", () => {
+		const u = createUseUser({ invoke: makeInvoke() });
+		expect(typeof u.useUser).toBe("function");
+		expect(typeof u.resetUser).toBe("function");
+	});
+
+	it("two factory calls produce independent function references", () => {
+		const a = createUseUser({ invoke: makeInvoke() });
+		const b = createUseUser({ invoke: makeInvoke() });
+		expect(a.useUser).not.toBe(b.useUser);
+		expect(a.resetUser).not.toBe(b.resetUser);
+	});
+
+	it("does not throw at construction time even with a failing invoke", () => {
+		const invoke: CreateUseUserInvoke = {
+			vtex: {
+				loaders: {
+					user: async () => {
+						throw new Error("boom");
+					},
+				},
+			},
+		};
+		expect(() => createUseUser({ invoke })).not.toThrow();
+	});
+});

package/src/hooks/__tests__/createUseWishlist.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Tests for the `createUseWishlist` factory.
+ *
+ * The hook itself depends on React (useState/useEffect), and apps-start
+ * does not pull in @testing-library/react. So we test the parts that
+ * don't require a renderer: factory shape, isolation, and the pure
+ * helpers `findWishlistEntry` + `legacyAddArgsToCanonical` which encode
+ * the most error-prone invariants (id matching + legacy arg swap).
+ */
+
+import { describe, expect, it } from "vitest";
+import type { WishlistItem } from "../../loaders/wishlist";
+import {
+	type CreateUseWishlistInvoke,
+	createUseWishlist,
+	findWishlistEntry,
+	legacyAddArgsToCanonical,
+} from "../createUseWishlist";
+
+function makeInvoke(): CreateUseWishlistInvoke {
+	return {
+		vtex: {
+			loaders: {
+				wishlist: async () => [],
+			},
+			actions: {
+				addToWishlist: async () => [],
+				removeFromWishlist: async () => [],
+			},
+		},
+	};
+}
+
+describe("createUseWishlist — factory shape", () => {
+	it("returns useWishlist, resetWishlist", () => {
+		const w = createUseWishlist({ invoke: makeInvoke() });
+		expect(typeof w.useWishlist).toBe("function");
+		expect(typeof w.resetWishlist).toBe("function");
+	});
+
+	it("two factory calls produce independent function references", () => {
+		const a = createUseWishlist({ invoke: makeInvoke() });
+		const b = createUseWishlist({ invoke: makeInvoke() });
+		expect(a.useWishlist).not.toBe(b.useWishlist);
+		expect(a.resetWishlist).not.toBe(b.resetWishlist);
+	});
+});
+
+describe("legacyAddArgsToCanonical — arg swap", () => {
+	it("maps legacy (productId=sku, productGroupId=parent) to canonical { productId, sku }", () => {
+		// In analytics terms: item_id is the SKU; item_group_id is the
+		// VTEX productId. Sites destructure these from analytics objects
+		// and pass them to wishlist.addItem in that order.
+		const out = legacyAddArgsToCanonical("sku-1", "prod-100");
+		expect(out).toEqual({ productId: "prod-100", sku: "sku-1" });
+	});
+
+	it("preserves empty strings without coercing", () => {
+		const out = legacyAddArgsToCanonical("", "");
+		expect(out).toEqual({ productId: "", sku: "" });
+	});
+});
+
+describe("findWishlistEntry — id matching", () => {
+	const items: WishlistItem[] = [
+		{ id: "entry-1", productId: "prod-1", sku: "sku-1", title: "A" },
+		{ id: "entry-2", productId: "prod-2", sku: "sku-2", title: "B" },
+	];
+
+	it("matches by sku (the legacy `productId` arg passed by sites)", () => {
+		const entry = findWishlistEntry(items, "sku-1");
+		expect(entry?.id).toBe("entry-1");
+	});
+
+	it("matches by productId as a fallback", () => {
+		const entry = findWishlistEntry(items, "prod-2");
+		expect(entry?.id).toBe("entry-2");
+	});
+
+	it("returns undefined when no match", () => {
+		expect(findWishlistEntry(items, "missing")).toBeUndefined();
+	});
+
+	it("returns undefined for empty list", () => {
+		expect(findWishlistEntry([], "anything")).toBeUndefined();
+	});
+});