@decocms/apps 0.24.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -30,6 +30,7 @@
     "./vtex/inline-loaders/productDetailsPage": "./vtex/inline-loaders/productDetailsPage.ts",
     "./vtex/inline-loaders/productListingPage": "./vtex/inline-loaders/productListingPage.ts",
     "./vtex/inline-loaders/productList": "./vtex/inline-loaders/productList.ts",
+    "./vtex/inline-loaders/productListShelf": "./vtex/inline-loaders/productListShelf.ts",
     "./vtex/inline-loaders/relatedProducts": "./vtex/inline-loaders/relatedProducts.ts",
     "./vtex/inline-loaders/suggestions": "./vtex/inline-loaders/suggestions.ts",
     "./vtex/hooks": "./vtex/hooks/index.ts",

package/vtex/hooks/useCart.ts

@@ -134,7 +134,7 @@ async function updateItemQuantity(
 export interface UseCartOptions {
 	/** Enable automatic refetching. @default true */
 	enabled?: boolean;
-	/** Stale time in ms. @default 0 (always refetch) */
+	/** Stale time in ms. @default 30000 */
 	staleTime?: number;
 }
 
@@ -144,7 +144,7 @@ export function useCart(options?: UseCartOptions) {
 	const query = useQuery({
 		queryKey: CART_QUERY_KEY,
 		queryFn: fetchCart,
-		staleTime: options?.staleTime ?? 0,
+		staleTime: options?.staleTime ?? 30_000,
 		enabled: options?.enabled !== false,
 	});
 

package/vtex/inline-loaders/productListShelf.ts

@@ -0,0 +1,159 @@
+/**
+ * Lean product list loader for shelf/card display.
+ * Same API call as productList.ts but uses toProductShelf() for ~90% smaller payloads.
+ *
+ * Use this loader for ProductShelf sections where only card-level data is needed
+ * (name, URL, images, price, installments, PIX, availability, brand).
+ */
+
+import type { Product } from "../../commerce/types/commerce";
+import { getVtexConfig, intelligentSearch, toFacetPath } from "../client";
+import { pickSku, sortProducts, toProductShelf } from "../utils/transform";
+import type { Product as ProductVTEX } from "../utils/types";
+
+export interface ProductListProps {
+	props?: CollectionProps | QueryProps | ProductIDProps | FacetsProps;
+	query?: string;
+	count?: number;
+	sort?: string;
+	collection?: string;
+	hideUnavailableItems?: boolean;
+}
+
+interface CollectionProps {
+	collection: string;
+	count?: number;
+	sort?: string;
+	hideUnavailableItems?: boolean;
+}
+
+interface QueryProps {
+	query: string;
+	count?: number;
+	sort?: string;
+	fuzzy?: string;
+	hideUnavailableItems?: boolean;
+}
+
+interface ProductIDProps {
+	ids: string[];
+	hideUnavailableItems?: boolean;
+}
+
+interface FacetsProps {
+	query?: string;
+	facets: string;
+	count?: number;
+	sort?: string;
+	hideUnavailableItems?: boolean;
+}
+
+function isCollectionProps(p: any): p is CollectionProps {
+	return typeof p?.collection === "string";
+}
+function isProductIDProps(p: any): p is ProductIDProps {
+	return Array.isArray(p?.ids) && p.ids.length > 0;
+}
+function isFacetsProps(p: any): p is FacetsProps {
+	return typeof p?.facets === "string";
+}
+
+function resolveParams(props: ProductListProps): {
+	query: string;
+	count: number;
+	sort: string;
+	facetPath: string;
+	fuzzy?: string;
+	hideUnavailableItems: boolean;
+	ids?: string[];
+} {
+	const inner = props.props ?? props;
+
+	if (isProductIDProps(inner)) {
+		return {
+			query: `sku:${inner.ids.join(";")}`,
+			count: inner.ids.length,
+			sort: "",
+			facetPath: "",
+			hideUnavailableItems: inner.hideUnavailableItems ?? false,
+			ids: inner.ids,
+		};
+	}
+
+	if (isFacetsProps(inner)) {
+		return {
+			query: inner.query ?? "",
+			count: inner.count ?? 12,
+			sort: inner.sort ?? "",
+			facetPath: inner.facets,
+			hideUnavailableItems: inner.hideUnavailableItems ?? false,
+		};
+	}
+
+	if (isCollectionProps(inner)) {
+		return {
+			query: "",
+			count: inner.count ?? 12,
+			sort: inner.sort ?? "",
+			facetPath: toFacetPath([{ key: "productClusterIds", value: inner.collection }]),
+			hideUnavailableItems: inner.hideUnavailableItems ?? false,
+		};
+	}
+
+	return {
+		query: (inner as any).query ?? "",
+		count: (inner as any).count ?? 12,
+		sort: (inner as any).sort ?? "",
+		facetPath: "",
+		fuzzy: (inner as any).fuzzy,
+		hideUnavailableItems: (inner as any).hideUnavailableItems ?? false,
+	};
+}
+
+export default async function vtexProductListShelf(
+	props: ProductListProps,
+): Promise<Product[] | null> {
+	try {
+		const { query, count, sort, facetPath, fuzzy, hideUnavailableItems, ids } =
+			resolveParams(props);
+
+		const config = getVtexConfig();
+		const locale = config.locale ?? "pt-BR";
+
+		const params: Record<string, string> = {
+			page: "1",
+			count: String(count),
+			locale,
+			hideUnavailableItems: String(hideUnavailableItems),
+		};
+		if (query) params.query = query;
+		if (sort) params.sort = sort;
+		if (fuzzy) params.fuzzy = fuzzy;
+
+		const endpoint = facetPath ? `/product_search/${facetPath}` : "/product_search/";
+
+		const data = await intelligentSearch<{ products: ProductVTEX[] }>(endpoint, params);
+
+		const vtexProducts = data.products ?? [];
+		const baseUrl = config.publicUrl
+			? `https://${config.publicUrl}`
+			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+		let products = vtexProducts.map((p) => {
+			const fetchedSkus = ids ? new Set(ids) : null;
+			const preferredSku = fetchedSkus
+				? (p.items.find((item) => fetchedSkus.has(item.itemId)) ?? pickSku(p))
+				: pickSku(p);
+			return toProductShelf(p, preferredSku, 0, { baseUrl, priceCurrency: "BRL" });
+		});
+
+		if (ids) {
+			products = sortProducts(products, ids, "sku");
+		}
+
+		return products;
+	} catch (error) {
+		console.error("[VTEX] ProductListShelf error:", error);
+		return null;
+	}
+}

package/vtex/utils/transform.ts

@@ -492,6 +492,172 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 	};
 };
 
+/**
+ * Determines if an installment has no interest by checking if
+ * billingDuration * billingIncrement ≈ total price (within 1 cent tolerance).
+ */
+const isNoInterest = (spec: UnitPriceSpecification): boolean => {
+	if (spec.billingDuration == null || spec.billingIncrement == null || spec.price == null) {
+		return false;
+	}
+	return Math.abs(spec.billingDuration * spec.billingIncrement - spec.price) < 0.01;
+};
+
+/**
+ * Build a lean offer for shelf display. Keeps only:
+ * - ListPrice, SalePrice, SRP price types
+ * - PIX installment (name?.toUpperCase() === "PIX")
+ * - Best no-interest installment (highest billingDuration)
+ * Drops: inventoryLevel, giftSkuIds, priceValidUntil
+ */
+const buildOfferShelf = (offer: Offer): Offer => {
+	const leanSpecs: UnitPriceSpecification[] = [];
+
+	let bestNoInterest: UnitPriceSpecification | null = null;
+
+	for (const spec of offer.priceSpecification ?? []) {
+		// Keep base price types
+		if (
+			spec.priceType === SCHEMA_LIST_PRICE ||
+			spec.priceType === SCHEMA_SALE_PRICE ||
+			spec.priceType === SCHEMA_SRP
+		) {
+			if (spec.priceComponentType !== SCHEMA_INSTALLMENT) {
+				leanSpecs.push(spec);
+				continue;
+			}
+		}
+
+		// Keep PIX installment
+		if (spec.priceComponentType === SCHEMA_INSTALLMENT && spec.name?.toUpperCase() === "PIX") {
+			leanSpecs.push(spec);
+			continue;
+		}
+
+		// Track best no-interest installment (highest billingDuration)
+		if (
+			spec.priceComponentType === SCHEMA_INSTALLMENT &&
+			isNoInterest(spec) &&
+			(bestNoInterest == null ||
+				(spec.billingDuration ?? 0) > (bestNoInterest.billingDuration ?? 0))
+		) {
+			bestNoInterest = spec;
+		}
+	}
+
+	if (bestNoInterest) {
+		leanSpecs.push(bestNoInterest);
+	}
+
+	return {
+		"@type": "Offer",
+		identifier: offer.identifier,
+		price: offer.price,
+		seller: offer.seller,
+		sellerName: offer.sellerName,
+		teasers: offer.teasers,
+		priceSpecification: leanSpecs,
+		availability: offer.availability,
+		inventoryLevel: { value: 0 },
+	};
+};
+
+/** Property names commonly used by ProductCard/Shelf components */
+const SHELF_PROPERTY_NAMES = new Set([
+	"category",
+	"cluster",
+	"Cor",
+	"Tamanho",
+	"Voltagem",
+	"sellerId",
+]);
+
+/**
+ * Lean product transform for shelf/card display. Same signature as toProduct().
+ *
+ * Differences from toProduct():
+ * - Images: capped at 2 per SKU (front + back)
+ * - Offers: first seller only, stripped installments (keeps ListPrice, SalePrice, SRP, PIX, best no-interest)
+ * - isVariantOf: single in-stock variant at level 0
+ * - additionalProperty: filtered to known-used property names
+ * - Drops: description, video, isAccessoryOrSparePartFor, alternateName, gtin, releaseDate, model
+ */
+export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
+	product: P,
+	sku: P["items"][number],
+	level = 0,
+	options: ProductOptions,
+): Product => {
+	const { baseUrl, priceCurrency } = options;
+	const { productId, items } = product;
+	const { name, itemId: skuId } = sku;
+
+	// Images: cap at 2
+	const rawImages = nonEmptyArray(sku.images);
+	const mappedImages = (rawImages ?? []).slice(0, 2).map(({ imageUrl, imageText, imageLabel }) => ({
+		"@type": "ImageObject" as const,
+		alternateName: imageText || imageLabel || "",
+		url: imageUrl,
+		name: imageLabel || "",
+		encodingFormat: "image",
+	}));
+	const finalImages = mappedImages.length > 0 ? mappedImages : [DEFAULT_IMAGE];
+
+	// Offers: first seller only, lean
+	const firstSeller = (sku.sellers ?? [])[0];
+	const fullOffer = firstSeller
+		? (isLegacyProduct(product) ? toOfferLegacy : toOffer)(firstSeller)
+		: undefined;
+	const leanOffers = fullOffer ? [buildOfferShelf(fullOffer)] : [];
+
+	// isVariantOf: single in-stock variant at level 0
+	const isVariantOf =
+		level < 1
+			? (() => {
+					const inStockSku = findFirstAvailable(items) ?? items[0];
+					const singleVariant = inStockSku ? [toProductShelf(product, inStockSku, 1, options)] : [];
+					return {
+						"@type": "ProductGroup" as const,
+						productGroupID: productId,
+						hasVariant: singleVariant,
+						url: getProductGroupURL(baseUrl, product).href,
+						name: product.productName,
+						additionalProperty: [],
+					} satisfies ProductGroup;
+				})()
+			: undefined;
+
+	// additionalProperty: filter to known-used names
+	const specificationsAdditionalProperty = isLegacySku(sku)
+		? toAdditionalPropertiesLegacy(sku)
+		: toAdditionalProperties(sku);
+	const categoryAdditionalProperties = toAdditionalPropertyCategories(product) ?? [];
+	const clusterAdditionalProperties = toAdditionalPropertyClusters(product) ?? [];
+
+	const additionalProperty = [
+		...specificationsAdditionalProperty,
+		...categoryAdditionalProperties,
+		...clusterAdditionalProperties,
+	].filter((prop) => SHELF_PROPERTY_NAMES.has(prop.name ?? ""));
+
+	const categoriesString = splitCategory(product.categories[0]).join(DEFAULT_CATEGORY_SEPARATOR);
+
+	return {
+		"@type": "Product",
+		category: categoriesString,
+		productID: skuId,
+		url: getProductURL(baseUrl, product, sku.itemId).href,
+		name,
+		brand: { "@type": "Brand", name: product.brand },
+		inProductGroupWithID: productId,
+		sku: skuId,
+		image: finalImages,
+		offers: aggregateOffers(leanOffers, priceCurrency),
+		isVariantOf,
+		additionalProperty,
+	};
+};
+
 const toBreadcrumbList = (
 	product: ProductVTEX | LegacyProductVTEX,
 	{ baseUrl }: ProductOptions,