@decocms/apps-vtex 8.0.0 → 8.1.0-next.0

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

@@ -23,6 +23,7 @@ import {
 	toAdditionalPropertySpecification,
 	toBrand,
 	toPostalAddress,
+	toProduct,
 	toProductShelf,
 	toProductVariant,
 } from "../transform";
@@ -648,17 +649,19 @@ describe("toProductVariant", () => {
 		expect(offer.inventoryLevel?.value).toBe(0);
 	});
 
-	it("filters additionalProperty to variant-differentiating names only", () => {
+	it("filters spec additionalProperty to variant-differentiating names only", () => {
 		const product = makeISProduct({ items: [makeISSku()] });
 		const sku = makeISSku();
 		const result = toProductVariant(product, sku, baseOptions);
 
-		const propNames = result.additionalProperty?.map((p) => p.name) ?? [];
+		const specNames = (result.additionalProperty ?? [])
+			.filter((p) => p.valueReference !== "ReferenceID")
+			.map((p) => p.name);
 		// Should only contain Cor, Voltagem, Tamanho (from VARIANT_PROPERTY_NAMES)
-		for (const name of propNames) {
+		for (const name of specNames) {
 			expect(["Cor", "Voltagem", "Tamanho"]).toContain(name);
 		}
-		expect(propNames.length).toBeGreaterThan(0);
+		expect(specNames.length).toBeGreaterThan(0);
 	});
 
 	it("respects custom variantPropertyNames", () => {
@@ -669,8 +672,32 @@ describe("toProductVariant", () => {
 			variantPropertyNames: new Set(["Cor"]),
 		});
 
-		const propNames = result.additionalProperty?.map((p) => p.name) ?? [];
-		expect(propNames).toEqual(["Cor"]);
+		const specNames = (result.additionalProperty ?? [])
+			.filter((p) => p.valueReference !== "ReferenceID")
+			.map((p) => p.name);
+		expect(specNames).toEqual(["Cor"]);
+	});
+
+	// Analytics reads the SKU RefId off additionalProperty for GA4 dimension2
+	// (view_item_list / select_item) and its productImpression / productClick
+	// equivalents. It lives in `referenceId`, not `variations`, so the
+	// variantProps filter used to drop it and blank the dimension.
+	it("keeps the SKU reference ids (RefId) alongside the variant specs", () => {
+		const product = makeISProduct({ items: [makeISSku()] });
+		const sku = { ...makeISSku(), referenceId: [{ Key: "RefId", Value: "010276949803" }] };
+		const result = toProductVariant(product, sku, baseOptions);
+
+		const refId = result.additionalProperty?.find((p) => p.name === "RefId");
+		expect(refId?.value).toBe("010276949803");
+		expect(refId?.valueReference).toBe("ReferenceID");
+	});
+
+	it("omits RefId when the SKU carries no referenceId", () => {
+		const product = makeISProduct({ items: [makeISSku()] });
+		const sku = { ...makeISSku(), referenceId: undefined };
+		const result = toProductVariant(product, sku, baseOptions);
+
+		expect(result.additionalProperty?.some((p) => p.name === "RefId")).toBe(false);
 	});
 
 	it("produces lean offers with availability but no priceSpecification details", () => {
@@ -722,10 +749,11 @@ describe("toProductShelf", () => {
 				},
 			],
 			variations: [{ name: "Cor", values: ["Preto"] }],
+			...overrides,
 		}) as any;
 
 	// Campanha is a PRODUCT specification (in specificationGroups), NOT a sku.variation.
-	// It is the marker MonteCarlo uses to tag launches ("Lançamentos").
+	// It is the marker one storefront uses to tag launches ("Lançamentos").
 	const makeProduct = (overrides: Record<string, unknown> = {}) =>
 		({
 			origin: "intelligent-search",
@@ -766,4 +794,318 @@ describe("toProductShelf", () => {
 		);
 		expect(result.isVariantOf?.additionalProperty).toEqual([]);
 	});
+
+	// Analytics reads the product reference off isVariantOf.model for GA4
+	// dimension1 (view_item_list / select_item) and its productImpression /
+	// productClick equivalents. toProductShelf used to drop it, blanking the
+	// dimension on every shelf, PLP and search result.
+	it("carries productReference on isVariantOf.model (analytics dimension1)", () => {
+		const result = toProductShelf(
+			makeProduct({ productReference: "0102769498" }),
+			makeSku(),
+			0,
+			options,
+		);
+		expect(result.isVariantOf?.model).toBe("0102769498");
+	});
+
+	it("keeps the SKU RefId reachable on the complete-variants shelf (dimension2)", () => {
+		const result = toProductShelf(makeProduct(), makeSku(), 0, {
+			...options,
+			shelfCompleteVariants: true,
+		});
+		const variantProps = result.isVariantOf?.hasVariant?.[0]?.additionalProperty ?? [];
+		expect(variantProps).toEqual(
+			expect.arrayContaining([expect.objectContaining({ name: "RefId", value: "REF-SKU1" })]),
+		);
+	});
+
+	// A real catalog registers the packshot and the colour thumbnail LAST:
+	// measured on a live store, `secondary` sits at index 6 and `color-thumbnail`
+	// at index 7 of 8. A card that selects either BY NAME gets nothing from a
+	// positional cap and silently falls back to the first photo (the model
+	// wearing the piece).
+	const labelledImages = [
+		...Array.from({ length: 6 }, (_, i) => ({
+			imageUrl: `https://img.com/photo-${i}.jpg`,
+			imageText: `Photo ${i}`,
+			imageLabel: `product-photo-${i}`,
+		})),
+		{ imageUrl: "https://img.com/still.jpg", imageText: "Still", imageLabel: "secondary" },
+		{ imageUrl: "https://img.com/thumb.jpg", imageText: "Thumb", imageLabel: "color-thumbnail" },
+	];
+	const skuWithLabels = () => makeSku({ images: labelledImages });
+	const labelledProduct = () => makeProduct({ items: [skuWithLabels()] });
+
+	it("keeps the 2-image cap when keepImageNames is absent", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, options);
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("keepImageNames adds back labelled images that fall outside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["secondary", "color-thumbnail"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+			"color-thumbnail",
+		]);
+	});
+
+	it("keepImageNames does not duplicate a label already inside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["product-photo-0", "secondary"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+		]);
+	});
+
+	it("keepImageNames listing a label the SKU does not have changes nothing", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["vira"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("maxImages overrides the shelf default cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			maxImages: 3,
+		});
+		expect(result.image).toHaveLength(3);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// 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("keepImageNames rescues a labelled image from the maxImages cap", () => {
+		const capped = toProduct(product, items[0], 0, {
+			...options,
+			maxImages: 2,
+			keepImageNames: ["label3"],
+		});
+		expect(capped.image?.map((i) => i.name)).toEqual(["label0", "label1", "label3"]);
+	});
+
+	it("keepImageNames without maxImages is a no-op — every image is already there", () => {
+		const before = toProduct(product, items[0], 0, options);
+		const after = toProduct(product, items[0], 0, { ...options, keepImageNames: ["label3"] });
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+
+	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,
+			keepImageNames: undefined,
+			priceSpecifications: undefined,
+		});
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
 });

package/src/utils/buildOfferShelf.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import type { AggregateOffer, Offer, UnitPriceSpecification } from "@decocms/apps-commerce/types";
+import { useOffer } from "@decocms/apps-commerce/sdk/useOffer";
+import { buildOfferShelf } from "./transform";
+
+const installment = (
+	over: Partial<UnitPriceSpecification>,
+): UnitPriceSpecification =>
+	({
+		"@type": "UnitPriceSpecification",
+		priceType: "https://schema.org/SalePrice",
+		priceComponentType: "https://schema.org/Installment",
+		...over,
+	}) as UnitPriceSpecification;
+
+const offerWith = (specs: UnitPriceSpecification[]): Offer =>
+	({
+		"@type": "Offer",
+		price: 100,
+		priceSpecification: [
+			{ "@type": "UnitPriceSpecification", priceType: "https://schema.org/ListPrice", price: 120 },
+			{ "@type": "UnitPriceSpecification", priceType: "https://schema.org/SalePrice", price: 100 },
+			...specs,
+		],
+	}) as Offer;
+
+const pickInstallment = (offer: Offer) =>
+	useOffer({ "@type": "AggregateOffer", offers: [offer] } as AggregateOffer).installment;
+
+describe("buildOfferShelf installment selection", () => {
+	it("keeps the same installment useOffer picks on PLP/PDP (shelf == detail)", () => {
+		// 12x whose stated total (100) is the lowest and duration the highest, but VTEX
+		// rounding makes 12 * 8.34 = 100.08 — the old 1-cent isNoInterest check rejected
+		// it and the shelf fell back to 10x, diverging from the detail page's 12x.
+		const full = offerWith([
+			installment({ name: "PIX", billingDuration: 1, billingIncrement: 100, price: 100 }),
+			installment({ name: "Visa", billingDuration: 10, billingIncrement: 10, price: 100 }),
+			installment({ name: "Visa", billingDuration: 12, billingIncrement: 8.34, price: 100 }),
+			installment({ name: "Visa", billingDuration: 6, billingIncrement: 17.67, price: 106 }),
+		]);
+
+		const lean = buildOfferShelf(full);
+
+		expect(pickInstallment(lean)).toEqual(pickInstallment(full));
+		expect(pickInstallment(lean)?.billingDuration).toBe(12);
+	});
+
+	it("keeps the lowest-total plan even when every installment has interest", () => {
+		const full = offerWith([
+			installment({ name: "Visa", billingDuration: 3, billingIncrement: 34, price: 102 }),
+			installment({ name: "Visa", billingDuration: 6, billingIncrement: 18, price: 108 }),
+		]);
+
+		const lean = buildOfferShelf(full);
+
+		expect(pickInstallment(lean)).toEqual(pickInstallment(full));
+		expect(pickInstallment(lean)?.price).toBe(102);
+	});
+});

package/src/utils/enrichment.ts

@@ -24,7 +24,7 @@
  */
 
 import type { Product, ProductLeaf } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexFetch, vtexIOGraphQL } from "../client";
+import { getVtexConfig, storefrontBaseUrl, vtexFetch, vtexIOGraphQL } from "../client";
 import { listBrands } from "../loaders/brands";
 import { batch } from "./batch";
 import { withIsSimilarTo } from "./similars";
@@ -372,9 +372,7 @@ export function withKitItems(): ProductEnricher {
 		if (!productIDs.size) return products;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const batches = batch([...productIDs], KIT_ITEMS_BATCH_SIZE);
 		const productsById = new Map<string, ProductLeaf>();
@@ -428,9 +426,7 @@ export function withVariants(): ProductEnricher {
 		if (!productIDs.size) return products;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const batches = batch([...productIDs], VARIANTS_BATCH_SIZE);
 		const productsById = new Map<string, Product>();

package/src/utils/fetch.ts

@@ -15,6 +15,10 @@
  * the platform.
  */
 
+import { withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
+
+const timeoutFetch = withFetchTimeout();
+
 type CachingMode = "stale-while-revalidate";
 
 type DecoInit = {
@@ -88,7 +92,7 @@ export async function fetchSafe(
 	init?: DecoRequestInit,
 ): Promise<Response> {
 	const sanitized = sanitizeUrl(input);
-	const response = await fetch(sanitized as RequestInfo, init);
+	const response = await timeoutFetch(sanitized as RequestInfo, init);
 	if (!response.ok) {
 		throw new HttpError(response);
 	}