@decocms/apps-vtex 7.2.0

package/src/loaders/catalog.ts

@@ -0,0 +1,163 @@
+/**
+ * VTEX Catalog System API loaders.
+ * Pure async functions using vtexFetch. Require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps vtex/loaders/legacy/*.ts and vtex/utils/client.ts
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api
+ */
+import { getVtexConfig, vtexFetch } from "../client";
+
+// ---------------------------------------------------------------------------
+// Product search (public)
+// ---------------------------------------------------------------------------
+
+export type LegacySort =
+	| ""
+	| "OrderByTopSaleDESC"
+	| "OrderByReleaseDateDESC"
+	| "OrderByBestDiscountDESC"
+	| "OrderByPriceDESC"
+	| "OrderByPriceASC"
+	| "OrderByNameASC"
+	| "OrderByNameDESC"
+	| "OrderByScoreDESC";
+
+export interface SearchProductsOpts {
+	fq?: string | string[];
+	ft?: string;
+	sort?: LegacySort;
+	from?: number;
+	to?: number;
+}
+
+/**
+ * Search products using the VTEX Catalog API.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/products/search
+ */
+export async function searchProducts<T = any>(opts: SearchProductsOpts = {}): Promise<T[]> {
+	const params = new URLSearchParams();
+	const fqs = Array.isArray(opts.fq) ? opts.fq : opts.fq ? [opts.fq] : [];
+	for (const f of fqs) params.append("fq", f);
+	if (opts.ft) params.set("ft", opts.ft);
+	if (opts.sort) params.set("O", opts.sort);
+	if (opts.from != null) params.set("_from", String(opts.from));
+	if (opts.to != null) params.set("_to", String(opts.to));
+
+	const { salesChannel } = getVtexConfig();
+	if (salesChannel) params.set("sc", salesChannel);
+
+	return vtexFetch<T[]>(`/api/catalog_system/pub/products/search/?${params}`);
+}
+
+/**
+ * Get a product by productId or skuId.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/products/search
+ */
+export async function getProductByIdOrSku<T = any>(opts: {
+	productId?: string;
+	skuId?: string;
+}): Promise<T | null> {
+	let fq: string;
+	if (opts.productId) fq = `productId:${opts.productId}`;
+	else if (opts.skuId) fq = `skuId:${opts.skuId}`;
+	else throw new Error("Neither productId nor skuId provided.");
+
+	const results = await searchProducts<T>({ fq });
+	return results[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Product variations (public)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get product SKU variations.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/products/variations/-productId-
+ */
+export async function getProductVariations<T = any>(productId: string): Promise<T> {
+	return vtexFetch<T>(`/api/catalog_system/pub/products/variations/${productId}`);
+}
+
+// ---------------------------------------------------------------------------
+// Product specification (private — requires appKey/appToken)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get product specifications (private API).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/products/-productId-/specification
+ */
+export async function getProductSpecification<T = any>(productId: string): Promise<T> {
+	return vtexFetch<T>(`/api/catalog_system/pvt/products/${productId}/Specification`);
+}
+
+// ---------------------------------------------------------------------------
+// Cross-selling
+// ---------------------------------------------------------------------------
+
+export type CrossSellingType =
+	| "similars"
+	| "suggestions"
+	| "accessories"
+	| "whosawalsosaw"
+	| "whosawalsobought"
+	| "whoboughtalsobought"
+	| "showtogether";
+
+/**
+ * Get cross-selling products.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/products/crossselling/-type-/-productId-
+ */
+export async function getCrossSelling<T = any>(
+	type: CrossSellingType,
+	productId: string,
+): Promise<T[]> {
+	return vtexFetch<T[]>(`/api/catalog_system/pub/products/crossselling/${type}/${productId}`);
+}
+
+// ---------------------------------------------------------------------------
+// Categories
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the category tree up to a given depth level.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/category/tree/-categoryLevels-
+ */
+export async function getCategoryTree<T = any>(levels = 3): Promise<T[]> {
+	return vtexFetch<T[]>(`/api/catalog_system/pub/category/tree/${levels}`);
+}
+
+// ---------------------------------------------------------------------------
+// Brands
+// ---------------------------------------------------------------------------
+
+/**
+ * Get all brands.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/brand/list
+ */
+export async function getBrands<T = any>(): Promise<T[]> {
+	return vtexFetch<T[]>("/api/catalog_system/pub/brand/list");
+}
+
+// ---------------------------------------------------------------------------
+// Page type
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the page type for a given term/path.
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/portal/pagetype/-term-
+ */
+export async function getPageType<T = any>(term: string): Promise<T> {
+	return vtexFetch<T>(`/api/catalog_system/pub/portal/pagetype/${term}`);
+}
+
+// ---------------------------------------------------------------------------
+// Facets (legacy)
+// ---------------------------------------------------------------------------
+
+/**
+ * Get facets/filters for a search term.
+ * @see https://developers.vtex.com/docs/api-reference/search-api#get-/api/catalog_system/pub/facets/search/-term-
+ */
+export async function getFacets<T = any>(term: string): Promise<T> {
+	return vtexFetch<T>(`/api/catalog_system/pub/facets/search/${term}`);
+}

package/src/loaders/collections.ts

@@ -0,0 +1,55 @@
+/**
+ * VTEX Collections loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/collections/list.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/collection/search
+ */
+import { vtexFetch } from "../client";
+import type { CollectionList } from "../utils/types";
+
+export interface CollectionOption {
+	value: string;
+	label: string;
+}
+
+/**
+ * Fetch collections, optionally filtering by search term.
+ *
+ * Without a term returns up to 3 000 collections; with a term
+ * returns the first 15 matches. Results are mapped to a simple
+ * `{ value, label }` list suitable for dropdowns / selectors.
+ *
+ * Note: uses the **pvt** (private) endpoint — requires appKey/appToken.
+ */
+export async function getCollections(term?: string): Promise<CollectionOption[]> {
+	const params = new URLSearchParams();
+
+	if (term) {
+		params.set("page", "1");
+		params.set("pageSize", "15");
+		const list = await vtexFetch<CollectionList>(
+			`/api/catalog_system/pvt/collection/search/${encodeURIComponent(term)}?${params}`,
+		);
+		return mapToOptions(list);
+	}
+
+	params.set("page", "1");
+	params.set("pageSize", "3000");
+	params.set("orderByAsc", "false");
+	const list = await vtexFetch<CollectionList>(
+		`/api/catalog_system/pvt/collection/search?${params}`,
+	);
+	return mapToOptions(list);
+}
+
+function mapToOptions(list: CollectionList): CollectionOption[] {
+	return (
+		list.items?.map((c) => ({
+			value: `${c.id}`,
+			label: `${c.id} - ${c.name}`,
+		})) ?? []
+	);
+}

package/src/loaders/index.ts

@@ -0,0 +1,19 @@
+export * from "./address";
+export * from "./brands";
+export * from "./cart";
+export * from "./catalog";
+export * from "./collections";
+export * from "./legacy";
+export * from "./logistics";
+export * from "./navbar";
+export * from "./orders";
+export * from "./pageType";
+export * from "./payment";
+export * from "./profile";
+export * from "./promotion";
+export * from "./search";
+export * from "./session";
+export * from "./user";
+export * from "./wishlist";
+export * from "./wishlistProducts";
+export * from "./workflow";

package/src/loaders/intelligentSearch/__tests__/productListingPage.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { mapLabelledFuzzyToFuzzy } from "../productListingPage";
+
+describe("mapLabelledFuzzyToFuzzy", () => {
+	it("translates 'automatic' to 'auto'", () => {
+		expect(mapLabelledFuzzyToFuzzy("automatic")).toBe("auto");
+	});
+
+	it("translates 'enabled' to '1'", () => {
+		expect(mapLabelledFuzzyToFuzzy("enabled")).toBe("1");
+	});
+
+	it("translates 'disabled' to '0'", () => {
+		expect(mapLabelledFuzzyToFuzzy("disabled")).toBe("0");
+	});
+
+	it("returns undefined for missing label", () => {
+		expect(mapLabelledFuzzyToFuzzy(undefined)).toBeUndefined();
+	});
+});

package/src/loaders/intelligentSearch/productDetailsPage.ts

@@ -0,0 +1,95 @@
+/**
+ * PDP loader using Legacy Catalog API + shared transform pipeline.
+ * Maps VTEX catalog response to schema.org ProductDetailsPage
+ * following the same pattern as deco-cx/apps.
+ */
+
+import type { ProductDetailsPage } from "@decocms/apps-commerce/types";
+import { getVtexConfig, vtexCachedFetch } from "../../client";
+import { searchBySlug } from "../../utils/slugCache";
+import { pickSku, toProductPage } from "../../utils/transform";
+import type { LegacyProduct } from "../../utils/types";
+
+export interface PDPProps {
+	slug?: string;
+	skuId?: string;
+	/** When true, PDP pages with ?skuId remain indexable */
+	indexingSkus?: boolean;
+	/** Use product.description instead of metaTagDescription for SEO */
+	preferDescription?: boolean;
+	/**
+	 * Use lean variant transform for hasVariant[]. Defaults to false on PDPs:
+	 * variant selectors need image[] and real inventoryLevel to render thumbnails
+	 * and per-SKU stock state, so a full toProduct(level=1) is the safe default.
+	 * Opt-in only if payload size becomes a problem.
+	 */
+	leanVariants?: boolean;
+	/** When leanVariants is true, still include image[0] on each variant. Default true. */
+	variantIncludeImage?: boolean;
+	/** When leanVariants is true, still include inventoryLevel on each variant. Default true. */
+	variantIncludeInventory?: boolean;
+}
+
+export default async function vtexProductDetailsPage(
+	props: PDPProps,
+): Promise<ProductDetailsPage | null> {
+	const {
+		slug,
+		skuId,
+		indexingSkus,
+		preferDescription,
+		leanVariants = false,
+		variantIncludeImage = true,
+		variantIncludeInventory = true,
+	} = props;
+	if (!slug) return null;
+
+	try {
+		const linkText = slug.replace(/\/p$/, "").replace(/^\//, "").toLowerCase();
+		const config = getVtexConfig();
+		const sc = config.salesChannel;
+
+		const products = await searchBySlug(linkText);
+
+		if (!products || products.length === 0) {
+			return null;
+		}
+
+		const product = products[0];
+		const baseUrl = config.publicUrl
+			? `https://${config.publicUrl}`
+			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+		const sku = pickSku(product, skuId);
+
+		const kitItems: LegacyProduct[] =
+			Array.isArray(sku.kitItems) && sku.kitItems.length > 0
+				? ((await vtexCachedFetch<LegacyProduct[]>(
+						`/api/catalog_system/pub/products/search/?fq=${sku.kitItems.map((item: any) => `skuId:${item.itemId}`).join("&fq=")}&_from=0&_to=49${sc ? `&sc=${sc}` : ""}`,
+					)) ?? [])
+				: [];
+
+		const page = toProductPage(product, sku, kitItems, {
+			baseUrl,
+			priceCurrency: "BRL",
+			leanVariants,
+			variantIncludeImage,
+			variantIncludeInventory,
+		});
+
+		return {
+			...page,
+			seo: {
+				title: product.productTitle || product.productName,
+				description: preferDescription
+					? product.description
+					: product.metaTagDescription || product.description?.substring(0, 160) || "",
+				canonical: `/${product.linkText}/p`,
+				noIndexing: indexingSkus ? false : !!skuId,
+			},
+		};
+	} catch (error) {
+		console.error("[VTEX] PDP error:", error);
+		return null;
+	}
+}

package/src/loaders/intelligentSearch/productList.ts

@@ -0,0 +1,154 @@
+/**
+ * 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 "@decocms/apps-commerce/types";
+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;
+}
+
+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;
+	}
+}