@decocms/apps-vtex 7.59.0 → 7.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-vtex",
-  "version": "7.59.0",
+  "version": "7.60.0",
   "type": "module",
   "description": "Deco commerce app: VTEX integration",
   "repository": {
@@ -51,10 +51,10 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.59.0",
-    "@decocms/apps-commerce": "7.59.0",
-    "@decocms/apps-website": "7.59.0",
-    "@decocms/tanstack": "7.59.0"
+    "@decocms/blocks": "7.60.0",
+    "@decocms/apps-commerce": "7.60.0",
+    "@decocms/apps-website": "7.60.0",
+    "@decocms/tanstack": "7.60.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/loaders/legacy.ts

@@ -33,6 +33,7 @@ import {
 	toProduct,
 	toProductPage,
 } from "../utils/transform";
+import type { ProductOptions } from "../utils/transform";
 import type { LegacyFacet, LegacyItem, LegacyProduct, LegacySort, PageType } from "../utils/types";
 
 // ---------------------------------------------------------------------------
@@ -342,6 +343,28 @@ export interface LegacyPLPOptions {
 	/** Ignore case when checking if a facet is selected */
 	ignoreCaseSelected?: boolean;
 	includeOriginalAttributes?: string[];
+	/**
+	 * Build `isVariantOf.hasVariant[]` with the lean variant transform instead of
+	 * a full nested `toProduct` per SKU. Off by default (unchanged behaviour).
+	 *
+	 * `productDetailsPage` (intelligent search) already exposes this, but the
+	 * legacy PLP never plumbed it — so a listing always paid the full variant
+	 * tree. Measured on a real store (36 products, 26 variants each): ~9.6 MB
+	 * per page, 96% of each product in `isVariantOf.hasVariant`, because every
+	 * variant carries the whole 48-entry payment ladder plus a copy of the
+	 * parent `description` — none of which a listing card reads.
+	 */
+	leanVariants?: boolean;
+	/** Keep the ladder on the ONE variant the card renders — see ProductOptions.displayedVariantId. */
+	displayedVariantId?: ProductOptions["displayedVariantId"];
+	/** Forwarded to the lean variant transform. */
+	variantPropertyNames?: Set<string>;
+	variantIncludeImage?: boolean;
+	variantIncludeInventory?: boolean;
+	/** Cap image[] to the first N entries — see ProductOptions.maxImages. */
+	maxImages?: number;
+	/** Rewrite priceSpecification on emitted offers — see ProductOptions.priceSpecifications. */
+	priceSpecifications?: ProductOptions["priceSpecifications"];
 }
 
 /**
@@ -362,6 +385,13 @@ export async function legacyProductListingPage(
 		ignoreCaseSelected,
 		useCollectionName,
 		includeOriginalAttributes,
+		leanVariants,
+		displayedVariantId,
+		variantPropertyNames,
+		variantIncludeImage,
+		variantIncludeInventory,
+		maxImages,
+		priceSpecifications,
 	} = opts;
 
 	const currentPageOffset = opts.pageOffset ?? 1;
@@ -447,6 +477,13 @@ export async function legacyProductListingPage(
 			baseUrl,
 			priceCurrency,
 			includeOriginalAttributes,
+			leanVariants,
+			displayedVariantId,
+			variantPropertyNames,
+			variantIncludeImage,
+			variantIncludeInventory,
+			maxImages,
+			priceSpecifications,
 		}),
 	);
 

package/src/utils/__tests__/transform.test.ts

@@ -23,6 +23,7 @@ import {
 	toAdditionalPropertySpecification,
 	toBrand,
 	toPostalAddress,
+	toProduct,
 	toProductShelf,
 	toProductVariant,
 } from "../transform";
@@ -767,3 +768,213 @@ describe("toProductShelf", () => {
 		expect(result.isVariantOf?.additionalProperty).toEqual([]);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// toProduct — escape hatches for leanVariants listings
+// ---------------------------------------------------------------------------
+//
+// `leanVariants` assumes the card renders the ROOT sku, so `buildOfferVariant`
+// empties `priceSpecification` on every `hasVariant[]` entry. A card that picks
+// a representative variant instead (e.g. "cheapest in stock") reads that
+// entry's own offer for list price and installments — blank with the ladder
+// emptied. `displayedVariantId` keeps exactly that one entry full.
+//
+// `maxImages` caps `image[]` by POSITION. Both default to undefined, which
+// preserves the previous output byte for byte — that is what the last two cases
+// pin down.
+
+describe("toProduct — displayedVariantId / maxImages", () => {
+	const sellers = (price: number) => [
+		{
+			sellerId: "1",
+			sellerName: "Seller One",
+			commertialOffer: {
+				AvailableQuantity: 5,
+				Price: price,
+				ListPrice: price + 30,
+				spotPrice: price,
+				PriceValidUntil: "2025-12-31",
+				// A real ladder: every payment method the store accepts, every
+				// installment count. Measured on a live listing: 46 rungs per SKU,
+				// 12.0 KB — the thing `leanOffer` exists to drop.
+				Installments: ["Visa", "Master", "Amex", "PIX"].flatMap((method) =>
+					Array.from({ length: 3 }, (_, i) => ({
+						Value: price / (i + 1),
+						NumberOfInstallments: i + 1,
+						Name: `${method} ${i + 1}x`,
+						InterestRate: 0,
+						TotalValuePlusInterestRate: price,
+						PaymentSystemName: method,
+					})),
+				),
+				GiftSkuIds: [],
+				teasers: [],
+			},
+		},
+	];
+
+	const makeSku = (itemId: string, price: number, imageCount = 4) =>
+		({
+			itemId,
+			name: `SKU ${itemId}`,
+			ean: "1234567890123",
+			referenceId: [{ Key: "RefId", Value: `REF-${itemId}` }],
+			images: Array.from({ length: imageCount }, (_, i) => ({
+				imageUrl: `https://img.com/${itemId}-${i}.jpg`,
+				imageText: `img${i}`,
+				imageLabel: `label${i}`,
+			})),
+			videos: [],
+			sellers: sellers(price),
+			variations: [{ name: "Cor", values: ["Preto"] }],
+			kitItems: [],
+			complementName: "",
+			estimatedDateArrival: null,
+			modalType: null,
+		}) as any;
+
+	const makeProduct = (items: any[]) =>
+		({
+			origin: "intelligent-search",
+			productId: "PROD1",
+			productName: "Test Product",
+			brand: "TestBrand",
+			brandId: 1,
+			brandImageUrl: null,
+			productReference: "REF1",
+			description: "desc",
+			releaseDate: "2024-01-01",
+			linkText: "test-product",
+			categories: ["/Electronics/"],
+			categoriesIds: ["/1/"],
+			categoryId: "1",
+			productClusters: [],
+			clusterHighlights: [],
+			items,
+		}) as any;
+
+	const options = { baseUrl: "https://example.com", priceCurrency: "BRL" };
+	const items = [makeSku("SKU1", 90), makeSku("SKU2", 60), makeSku("SKU3", 120)];
+	const product = makeProduct(items);
+
+	const ladderOf = (variant: any) => variant?.offers?.offers?.[0]?.priceSpecification ?? [];
+
+	/** Regra do caller: só os tipos base, nenhuma parcela. */
+	const onlyListAndSale = (specs: any[]) =>
+		specs.filter((s) => !s.priceComponentType);
+
+	it("leanVariants alone empties the payment ladder on every variant", () => {
+		const result = toProduct(product, items[0], 0, { ...options, leanVariants: true });
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		expect(variants).toHaveLength(3);
+		for (const v of variants) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("displayedVariantId keeps the ladder on the ONE variant the card renders", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: (skus) => skus.find((s: any) => s.itemId === "SKU2")?.itemId,
+		});
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		const kept = variants.find((v: any) => v.sku === "SKU2");
+		const lean = variants.filter((v: any) => v.sku !== "SKU2");
+
+		expect(ladderOf(kept).length).toBeGreaterThan(0);
+		for (const v of lean) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("the kept variant stays LEAN — only its offer is upgraded", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => "SKU2",
+		});
+		const kept: any = (result.isVariantOf?.hasVariant ?? []).find((v: any) => v.sku === "SKU2");
+
+		// A full toProduct here would re-emit these; the lean shape must not.
+		expect(kept.description).toBeUndefined();
+		expect(kept.brand).toBeUndefined();
+		expect(kept.gtin).toBeUndefined();
+		expect(kept.isVariantOf).toBeUndefined();
+		// ...but the ladder is real. Without a `priceSpecifications` rule it is
+		// the FULL one — dropping description/brand/isVariantOf is the win here,
+		// and the ladder stays whatever the caller asked for.
+		const full = ladderOf(toProduct(product, items[1], 0, options));
+		expect(ladderOf(kept).length).toBe(full.length);
+	});
+
+	it("the kept variant keeps its real inventoryLevel (selectors read it per SKU)", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => "SKU2",
+		});
+		const kept: any = (result.isVariantOf?.hasVariant ?? []).find((v: any) => v.sku === "SKU2");
+		// buildOfferShelf hard-zeroes inventoryLevel; the variant path must not
+		// inherit that, or every variant reads as out of stock.
+		expect(kept.offers?.offers?.[0]?.inventoryLevel?.value).toBe(5);
+	});
+
+	it("the ladder flag does NOT leak into the lean variants", () => {
+		// Regression: the internal `variantKeepLadder` reached `variantOptions`,
+		// so every lean variant emitted a ladder instead of an empty one and the
+		// option made the payload BIGGER — measured on a real listing,
+		// isVariantOf 38.6 -> 49.6 KB.
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			priceSpecifications: onlyListAndSale,
+			displayedVariantId: () => "SKU2",
+		});
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		for (const v of variants.filter((v: any) => v.sku !== "SKU2")) {
+			expect(ladderOf(v)).toEqual([]);
+		}
+		expect(ladderOf(variants.find((v: any) => v.sku === "SKU2")).length).toBeGreaterThan(0);
+	});
+
+	it("priceSpecifications rewrites the ROOT ladder with the caller's own rule", () => {
+		const full = toProduct(product, items[0], 0, options);
+		const lean = toProduct(product, items[0], 0, {
+			...options,
+			priceSpecifications: onlyListAndSale,
+		});
+
+		expect(ladderOf(full).length).toBeGreaterThan(ladderOf(lean).length);
+		const types = new Set(ladderOf(lean).map((s: any) => s.priceType));
+		expect(types.has("https://schema.org/ListPrice")).toBe(true);
+		expect(types.has("https://schema.org/SalePrice")).toBe(true);
+	});
+
+	it("displayedVariantId returning undefined leaves every variant lean", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => undefined,
+		});
+		for (const v of result.isVariantOf?.hasVariant ?? []) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("maxImages caps image[] by position", () => {
+		const full = toProduct(product, items[0], 0, options);
+		expect(full.image).toHaveLength(4);
+
+		const capped = toProduct(product, items[0], 0, { ...options, maxImages: 2 });
+		expect(capped.image).toHaveLength(2);
+		expect(capped.image?.map((i) => i.url)).toEqual(
+			full.image?.slice(0, 2).map((i) => i.url),
+		);
+	});
+
+	it("every option absent is byte-for-byte the previous output", () => {
+		const before = toProduct(product, items[0], 0, options);
+		const after = toProduct(product, items[0], 0, {
+			...options,
+			displayedVariantId: undefined,
+			maxImages: undefined,
+			priceSpecifications: undefined,
+		});
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+});

package/src/utils/transform.ts

@@ -99,7 +99,7 @@ const getProductURL = (origin: string, product: { linkText: string }, skuId?: st
 const nonEmptyArray = <T>(array: T[] | null | undefined) =>
 	Array.isArray(array) && array.length > 0 ? array : null;
 
-interface ProductOptions {
+export interface ProductOptions {
 	baseUrl: string;
 	/** Price coded currency, e.g.: USD, BRL */
 	priceCurrency: string;
@@ -108,6 +108,69 @@ interface ProductOptions {
 	includeOriginalAttributes?: string[];
 	/** Use lean toProductVariant for hasVariant[] instead of full toProduct at level=1 */
 	leanVariants?: boolean;
+	/**
+	 * With `leanVariants`, keep the payment ladder on the ONE variant the card
+	 * actually renders. Receives the raw SKU list and returns that SKU's
+	 * `itemId` (or undefined to leave every variant lean).
+	 *
+	 * Why this exists: `leanVariants` assumes the card renders the ROOT sku, so
+	 * `buildOfferVariant` empties `priceSpecification` on every entry. Cards that
+	 * instead pick a representative variant out of `isVariantOf.hasVariant` (e.g.
+	 * "cheapest in stock") read that variant's own offer for list price and
+	 * installments — with the ladder emptied, those render blank.
+	 *
+	 * The kept entry stays on the LEAN variant shape and only its offer is
+	 * upgraded, to {@link buildOfferShelf} (ListPrice/SalePrice/SRP + PIX + the
+	 * one installment `useOffer` would pick). A full `toProduct` here would
+	 * instead re-emit `description` and the whole 48-entry ladder the parent
+	 * already carries: measured on a real listing, 17.5 KB of the 53.5 KB in
+	 * every product, for a card that reads price and installment only.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	displayedVariantId?: (items: Array<LegacySkuVTEX | SkuVTEX>) => string | undefined;
+	/**
+	 * Rewrite `priceSpecification` on the offers this transform emits. Runs on
+	 * the ROOT offer and on the offer of the variant `displayedVariantId` picks.
+	 *
+	 * A listing renders ONE installment string per card, while the Catalog API
+	 * returns every payment method the store accepts: measured on a real page,
+	 * 48 `UnitPriceSpecification` entries = 12.0 KB per product, 22% of the
+	 * listing payload — built, cached and re-serialized in full.
+	 *
+	 * Deliberately a caller-supplied function and not a boolean: WHICH rungs a
+	 * card reads is store policy, not ours. {@link buildOfferShelf} keeps the
+	 * `bestInstallment` one (lowest total, tie-broken by highest
+	 * `billingDuration`) — and on a store with a boleto discount that resolves to
+	 * "Boleto Bancário 1x", measured against a storefront that renders
+	 * "Visa 10x" on all 36 cards of the page. Same data, different string. Pass
+	 * `(specs) => [buildOfferShelf({ ...offer, priceSpecification: specs }).…]`-style
+	 * logic, or your own predicate; the transform only applies it.
+	 *
+	 * Undefined (default) keeps the full ladder — a PDP needs it.
+	 */
+	priceSpecifications?: (specs: UnitPriceSpecification[]) => UnitPriceSpecification[];
+	/**
+	 * Internal: set by `toProduct`/`toProductShelf` on the ONE variant
+	 * `displayedVariantId` picked, so `toProductVariant` emits a real ladder for
+	 * it instead of `buildOfferVariant`'s empty one. Not meant for callers.
+	 */
+	variantKeepLadder?: boolean;
+	/**
+	 * Cap `image[]` to the first N entries, in path order. Undefined (default)
+	 * keeps every image.
+	 *
+	 * Listings render at most a couple of images per card, while the Catalog API
+	 * returns every asset registered on the SKU (3 on average, up to 5 measured).
+	 *
+	 * NOTE: this truncates by POSITION, so images the consumer selects BY NAME
+	 * can fall outside the cap. Measured on a real listing page: the `vira`
+	 * (hover) image sits at index 1 in only 5 of the 19 products that have one —
+	 * index 2 in 12 of them, index 3 in 2. A cap of 2 therefore drops the hover
+	 * image on most cards that use one. Callers that select by name should keep
+	 * the named entries instead of using this option.
+	 */
+	maxImages?: number;
 	/** Property names to keep on lean variant additionalProperty. Defaults to VARIANT_PROPERTY_NAMES. */
 	variantPropertyNames?: Set<string>;
 	/** When leanVariants is true, still include image[0] on each variant entry. Default true. */
@@ -396,17 +459,31 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 		: toAdditionalProperties(sku);
 	const referenceIdAdditionalProperty = toAdditionalPropertyReferenceIds(referenceId);
 	const images = nonEmptyArray(sku.images);
-	const offers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
-
-	const variantOptions =
-		imagesByKey !== options.imagesByKey ? { ...options, imagesByKey } : options;
+	const rawOffers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
+	const offers = applyPriceSpecifications(rawOffers, options);
+
+	// `variantKeepLadder` must NOT be inherited: while it leaked through, every
+	// lean variant emitted a ladder instead of an empty one — measured on a real
+	// listing, `isVariantOf` GREW from 38.6 KB to 49.6 KB, so the option made
+	// the payload bigger. Only the entry `displayedVariantId` picks turns it on,
+	// explicitly, below.
+	const variantOptions = { ...options, imagesByKey, variantKeepLadder: false };
 	const isVariantOf =
 		level < 1
 			? ({
 					"@type": "ProductGroup",
 					productGroupID: productId,
 					hasVariant: options.leanVariants
-						? items.map((sku) => toProductVariant(product, sku, variantOptions))
+						? ((keepId) =>
+								items.map((sku) =>
+									toProductVariant(
+										product,
+										sku,
+										keepId !== undefined && sku.itemId === keepId
+											? { ...variantOptions, variantKeepLadder: true }
+											: variantOptions,
+									),
+								))(options.displayedVariantId?.(items))
 						: items.map((sku) => toProduct(product, sku, 1, variantOptions)),
 					url: getProductGroupURL(baseUrl, product).href,
 					name: product.productName,
@@ -418,7 +495,9 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 				} satisfies ProductGroup)
 			: undefined;
 
-	const finalImages = images?.map(({ imageUrl, imageText, imageLabel }) => {
+	const cappedImages =
+		typeof options.maxImages === "number" ? images?.slice(0, options.maxImages) : images;
+	const finalImages = cappedImages?.map(({ imageUrl, imageText, imageLabel }) => {
 		const url = imagesByKey.get(getImageKey(imageUrl)) ?? imageUrl;
 		const alternateName = imageText || imageLabel || "";
 		const name = imageLabel || "";
@@ -567,6 +646,19 @@ export const buildOfferShelf = (offer: Offer): Offer => {
 	};
 };
 
+/**
+ * Apply `options.priceSpecifications` to every offer, if the caller supplied it.
+ * Identity (same array reference) when absent, so the default output is
+ * byte-for-byte unchanged.
+ */
+const applyPriceSpecifications = (offers: Offer[], options: ProductOptions): Offer[] =>
+	options.priceSpecifications
+		? offers.map((offer) => ({
+				...offer,
+				priceSpecification: options.priceSpecifications!(offer.priceSpecification ?? []),
+			}))
+		: offers;
+
 /** Property names commonly used by ProductCard/Shelf components */
 const SHELF_PROPERTY_NAMES = new Set([
 	"category",
@@ -646,9 +738,16 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 					const inStockSku = findFirstAvailable(items) ?? items[0];
 					// Opt-in: every SKU as a lean variant (size/color grid on shelf cards).
 					// Default: a single in-stock variant (lean shelf payload).
+					const keepId = options.displayedVariantId?.(items);
 					const hasVariant = options.shelfCompleteVariants
 						? items.map((variantSku) =>
-								toProductVariant(product, variantSku, options),
+								toProductVariant(
+									product,
+									variantSku,
+									keepId !== undefined && variantSku.itemId === keepId
+										? { ...options, variantKeepLadder: true }
+										: options,
+								),
 							)
 						: inStockSku
 							? [toProductShelf(product, inStockSku, 1, options)]
@@ -741,7 +840,20 @@ export const toProductVariant = <P extends LegacyProductVTEX | ProductVTEX>(
 	const offerConverter = isLegacyProduct(product) ? toOfferLegacy : toOffer;
 	const allOffers = (sku.sellers ?? []).map(offerConverter).sort(bestOfferFirst);
 	const bestOffer = allOffers[0];
-	const leanOffers = bestOffer ? [buildOfferVariant(bestOffer, includeInventory)] : [];
+	// `variantKeepLadder` marks the ONE variant the card renders (see
+	// displayedVariantId): it keeps the LEAN shape but needs a real ladder,
+	// through the same `priceSpecifications` hook the root offer uses.
+	const leanOffers = bestOffer
+		? [
+				options.variantKeepLadder
+					? {
+							...buildOfferVariant(bestOffer, includeInventory),
+							priceSpecification: applyPriceSpecifications([bestOffer], options)[0]
+								.priceSpecification,
+						}
+					: buildOfferVariant(bestOffer, includeInventory),
+			]
+		: [];
 
 	// image[0] only — selectors render a single thumbnail. Reuse the same
 	// imagesByKey lookup toProduct uses so URLs stay consistent across variants.