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

package/package.json

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

package/src/__conformance__/upstream.test.ts

@@ -0,0 +1,158 @@
+// @vitest-environment node
+/**
+ * Conformance: upstream-clients.mdx (Calling APIs) against the next-major
+ * client packages. Only the v8 client modules are checked; the v7 app
+ * surfaces that still ship beside them are out of scope until v7 is removed.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAlgoliaClient } from "@decocms/apps-algolia";
+import { createVtexClient } from "@decocms/apps-vtex";
+import { describe, expect, it, vi } from "vitest";
+
+const PACKAGES = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+/** The next-major client module of each platform package. */
+const V8_CLIENTS: Record<string, string[]> = {
+  "apps-vtex": ["src/vtexClient.ts"],
+  "apps-shopify": ["src/v8/client.ts", "src/v8/graphqlOperationName.ts"],
+  "apps-wake": ["src/wakeClient.ts"],
+  "apps-magento": ["src/magentoClient.ts"],
+  "apps-algolia": ["src/index.ts"],
+  "apps-resend": ["src/emails.ts"],
+  "apps-sfmc-personalization": ["src/index.ts"],
+};
+
+/** The source without comments, so doc examples (`process.env.X!` in a JSDoc) don't count. */
+function code(pkg: string, file: string): string {
+  return fs
+    .readFileSync(path.join(PACKAGES, pkg, file), "utf8")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:"'`])\/\/.*$/gm, "$1");
+}
+
+describe("what a client is (upstream-clients.mdx)", () => {
+  it("up-01: VTEX, Shopify, Wake, Magento, Algolia, Resend (and others) ship a client built on createInstrumentedFetch", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      expect(fs.existsSync(path.join(PACKAGES, pkg, "package.json"))).toBe(true);
+      expect([pkg, code(pkg, files[0]!)]).toEqual([
+        pkg,
+        expect.stringMatching(/import \{[^}]*createInstrumentedFetch[^}]*\} from "@decocms\/blocks\/fetch"/),
+      ]);
+    }
+  });
+
+  it("up-02: clients take settings as arguments: no environment reads inside a client", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        expect([pkg, file, /process\.env|import\.meta\.env|Deno\.env/.test(code(pkg, file))]).toEqual(
+          [pkg, file, false],
+        );
+      }
+    }
+  });
+
+  it("up-03: no React hooks, client components or shared-commerce converters in a client", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        const text = code(pkg, file);
+        const found = [
+          /["']use client["']/,
+          /from ["']react["']/,
+          /\buse(Cart|User|Wishlist)\b/,
+          /@decocms\/apps-commerce/,
+          /from ["']\.\/(loaders|actions|hooks)\//,
+        ].filter((pattern) => pattern.test(text));
+        expect([pkg, file, found]).toEqual([pkg, file, []]);
+      }
+    }
+  });
+
+  it("up-05: the Salesforce client is @decocms/apps-sfmc-personalization; @decocms/apps-salesforce is gone", () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(PACKAGES, "apps-sfmc-personalization/package.json"), "utf8"),
+    );
+    expect(pkg.name).toBe("@decocms/apps-sfmc-personalization");
+    const names = fs
+      .readdirSync(PACKAGES)
+      .filter((dir) => fs.existsSync(path.join(PACKAGES, dir, "package.json")))
+      .map((dir) => JSON.parse(fs.readFileSync(path.join(PACKAGES, dir, "package.json"), "utf8")).name);
+    expect(names).not.toContain("@decocms/apps-salesforce");
+  });
+
+  it("up-07: clients don't cache upstream responses", () => {
+    for (const [pkg, files] of Object.entries(V8_CLIENTS)) {
+      for (const file of files) {
+        expect([
+          pkg,
+          file,
+          /createFetchCache|fetchWithCache|fetchCache|caches\.default|caches\.open|cachedLoader/.test(
+            code(pkg, file),
+          ),
+        ]).toEqual([pkg, file, false]);
+      }
+    }
+  });
+});
+
+describe("call a client (upstream-clients.mdx)", () => {
+  it("up-06: createVtexClient({ account, appKey, appToken }) and vtex.search.products({ query, count })", async () => {
+    const fetch = vi.fn(
+      async (_input: string | URL | Request, _init?: RequestInit) =>
+        new Response(JSON.stringify({ products: [] }), { status: 200 }),
+    );
+    const vtex = createVtexClient({
+      account: "mystore",
+      appKey: "key",
+      appToken: "token",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    const products = await vtex.search.products({ query: "linen shirt", count: 12 });
+    expect(products).toEqual({ products: [] });
+    const url = new URL(String(fetch.mock.calls[0]![0]));
+    expect(url.host).toBe("mystore.vtexcommercestable.com.br");
+    expect(url.pathname).toContain("product_search");
+    expect(url.searchParams.get("query")).toBe("linen shirt");
+    expect(url.searchParams.get("count")).toBe("12");
+  });
+});
+
+describe("retries and failures (upstream-clients.mdx)", () => {
+  it("up-08: the VTEX client retries by default", async () => {
+    const statuses = [503, 200];
+    const fetch = vi.fn(
+      async () => new Response("{}", { status: statuses.shift() ?? 200 }),
+    );
+    const vtex = createVtexClient({
+      account: "mystore",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    await vtex.search.products({ query: "shirt" });
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("up-08: the VTEX client's circuit breaker fails fast after repeated failures", async () => {
+    const fetch = vi.fn(async () => new Response("{}", { status: 503 }));
+    const vtex = createVtexClient({
+      account: "mystore",
+      fetch: fetch as unknown as typeof globalThis.fetch,
+    });
+    for (let i = 0; i < 5; i++) await expect(vtex.search.products({ query: "shirt" })).rejects.toThrow();
+    const before = fetch.mock.calls.length;
+    await expect(vtex.search.products({ query: "shirt" })).rejects.toThrow();
+    expect(fetch.mock.calls.length).toBe(before);
+  }, 20_000);
+
+  it("up-08: other clients leave retries off (one attempt on a 503)", async () => {
+    const fetch = vi.fn(async () => new Response("{}", { status: 503 }));
+    const algolia = createAlgoliaClient(
+      { applicationId: "APP123", apiKey: "k" },
+      { fetch: fetch as unknown as typeof globalThis.fetch },
+    );
+    await expect(algolia.search([{ indexName: "products", query: "shirt" }] as never)).rejects.toThrow(
+      "algolia search failed with HTTP 503",
+    );
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/client-set-cookie-forward.test.ts

@@ -129,11 +129,11 @@ describe("vtexFetchWithCookies — inbound Set-Cookie capture", () => {
 				await vtexFetchWithCookies("/api/checkout/pub/orderForm");
 				return responseHeaders.getSetCookie();
 			},
-			"https://www.casaevideo.com.br/api/checkout/pub/orderForm",
+			"https://www.acme.com.br/api/checkout/pub/orderForm",
 		);
 
 		// domain-scoped to the storefront host, NOT the original VTEX domain
-		expect(captured[0]).toMatch(/Domain=www\.casaevideo\.com\.br/);
+		expect(captured[0]).toMatch(/Domain=www\.acme\.com\.br/);
 		expect(captured[0]).not.toMatch(/vtexcommercestable/i);
 		expect(captured[0]).toContain("checkout.vtex.com=__ofid=abc");
 	});
@@ -155,12 +155,12 @@ describe("vtexFetchWithCookies — inbound Set-Cookie capture", () => {
 				await vtexFetchWithCookies("/api/checkout/pub/orderForm");
 				return responseHeaders.getSetCookie();
 			},
-			"https://www.casaevideo.com.br/api/checkout/pub/orderForm",
+			"https://www.acme.com.br/api/checkout/pub/orderForm",
 		);
 
 		// the value's `domain=keep` is untouched; the attribute is rewritten
 		expect(captured[0]).toContain("__ofid=domain=keep");
-		expect(captured[0]).toMatch(/;\s*Domain=www\.casaevideo\.com\.br/);
+		expect(captured[0]).toMatch(/;\s*Domain=www\.acme\.com\.br/);
 		expect(captured[0]).not.toMatch(/vtexcommercestable/i);
 	});
 

package/src/client.ts

@@ -3,6 +3,7 @@
  * Uses VTEX's public REST APIs (Intelligent Search + Catalog + Checkout).
  */
 
+import { type FetchFn, withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
 import type {
 	InstrumentedFetch,
 	InstrumentedFetchInit,
@@ -47,7 +48,7 @@ function getRequestHost(): string | null {
  * host AND so it lands at the SAME cookie scope as the checkout proxy.
  *
  * VTEX sets `checkout.vtex.com` / `CheckoutOrderFormOwnership` with
- * `domain=<vtex-host>` (e.g. `casaevideonewio.vtexcommercestable.com.br`),
+ * `domain=<vtex-host>` (e.g. `acme.vtexcommercestable.com.br`),
  * which the browser would reject on the storefront host. There are two ways
  * to make it acceptable:
  *
@@ -147,7 +148,7 @@ export interface VtexConfig {
 }
 
 let _config: VtexConfig | null = null;
-let _fetch: typeof fetch | InstrumentedFetch = globalThis.fetch;
+let _fetch: FetchFn | InstrumentedFetch = withFetchTimeout();
 
 export function configureVtex(config: VtexConfig) {
 	_config = config;
@@ -169,7 +170,7 @@ export function configureVtex(config: VtexConfig) {
  * uninstrumented (useful for tests + sites that haven't onboarded
  * the observability stack yet).
  */
-export function setVtexFetch(fetchFn: typeof fetch | InstrumentedFetch) {
+export function setVtexFetch(fetchFn: FetchFn | InstrumentedFetch) {
 	_fetch = fetchFn;
 }
 
@@ -205,6 +206,55 @@ export function vtexHost(environment: string = "vtexcommercestable", config?: Vt
 	return `${c.account}.${environment}.${domain}`;
 }
 
+/**
+ * Origin every product/SKU/breadcrumb URL in the schema.org payload is built
+ * from.
+ *
+ * Order matters, and the first branch is the whole point: a storefront answers
+ * on the host the shopper actually typed, and that is the host its canonical
+ * URLs, JSON-LD and sitemap entries have to name. deco-cx/apps got this from
+ * the request too (`vtex/loaders/intelligentSearch/productList.ts` passes
+ * `baseUrl: url`), and dropping it here is what made a migrated storefront
+ * publish structured data pointing somewhere else.
+ *
+ * `publicUrl` is only a fallback. It is the VTEX *checkout* host
+ * (`secure.<brand>.com`), which is a different site from the storefront, and
+ * it is stored with whatever shape the admin typed — commonly a full URL
+ * (`https://secure.example.com/`). Interpolating that into `https://${...}`
+ * produced `https://https://secure.example.com/`, which `new URL()` parses
+ * with host `https`, so every product ended up at `https://https/<slug>/p`.
+ * Normalising through `URL` removes that whole class of bug.
+ *
+ * Returns no trailing slash, so `new URL(path, baseUrl)` behaves the same for
+ * every branch.
+ */
+export function storefrontBaseUrl(config?: VtexConfig): string {
+	const c = config ?? getVtexConfig();
+
+	// 1. The host serving this request -- the storefront's own origin.
+	const request = RequestContext.current?.request;
+	if (request) {
+		try {
+			return new URL(request.url).origin;
+		} catch {
+			// Fall through: a synthetic Request may carry an unparseable url.
+		}
+	}
+
+	// 2. Configured public URL, normalised whether or not it carries a scheme.
+	if (c.publicUrl) {
+		const normalised = /^https?:\/\//i.test(c.publicUrl) ? c.publicUrl : `https://${c.publicUrl}`;
+		try {
+			return new URL(normalised).origin;
+		} catch {
+			// Fall through to the account host rather than publish a broken origin.
+		}
+	}
+
+	// 3. The account's VTEX host. Always well-formed; never the public brand.
+	return `https://${vtexHost("vtexcommercestable", c)}`;
+}
+
 function baseUrl(): string {
 	return `https://${vtexHost()}`;
 }
@@ -325,7 +375,14 @@ export async function vtexFetchResponse(
 		headers: mergeHeaders(authHeaders(), segmentCookie, init?.headers),
 	});
 	if (!response.ok) {
-		throw new Error(`VTEX API error: ${response.status} ${response.statusText} - ${url}`);
+		// Include the response body: VTEX returns actionable detail here
+		// (e.g. MasterData "duplicated entry"), and without it callers can't
+		// distinguish error kinds and are forced to reimplement the fetch to
+		// read the body themselves. Safe to consume — we throw, not return.
+		const body = await response.text().catch(() => "");
+		throw new Error(
+			`VTEX API error: ${response.status} ${response.statusText} - ${url}${body ? ` - ${body}` : ""}`,
+		);
 	}
 	return response;
 }

package/src/index.ts

@@ -1,6 +1,11 @@
 /**
- * VTEX app entry point for @decocms/apps.
- * Re-exports client config + initializer + app contract.
+ * VTEX app entry point.
+ *
+ * Next major: `createVtexClient` is the thin, instrumented VTEX client
+ * (see ./vtexClient.ts and /next/upstream-clients). Everything else below is
+ * the v7 app surface, kept exported for v7 consumers until v7 is dropped.
+ *
+ * v7: re-exports client config + initializer + app contract.
  *
  * For actions/loaders/utils, use sub-path imports:
  *   import { addItemsToCart } from "@decocms/apps/vtex/actions/checkout"
@@ -15,3 +20,13 @@ export * from "./client";
 export { configure, type VtexState } from "./mod";
 export { type CreateVtexFetchOptions, createVtexFetch } from "./utils/instrumentedFetch";
 export { vtexOperationRouter } from "./utils/operationRouter";
+export {
+	createVtexClient,
+	type VtexCatalogSearchArgs,
+	type VtexClient,
+	type VtexClientConfig,
+	VtexError,
+	type VtexRequestOptions,
+	type VtexResponse,
+	type VtexSearchArgs,
+} from "./vtexClient";

package/src/loaders/__tests__/legacyProductList.test.ts

@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// `legacyProductList` is the SHELF loader. It accepted no payload-shaping
+// options, so every shelf paid the full product for every entry — measured on a
+// real home shelf (`count: 28`): 1095 KB, 39.1 KB per product, of which
+// `isVariantOf` 19.1 KB and the 48-rung `offers.priceSpecification` 12.8 KB.
+// `legacyProductListingPage` already took them; this file pins the pass-through,
+// because declaring the options WITHOUT forwarding them is exactly the bug the
+// PLP loader had.
+
+vi.mock("../../client", () => ({
+	getVtexConfig: () => ({ account: "test", salesChannel: "1" }),
+	vtexFetch: vi.fn(),
+	vtexFetchResponse: vi.fn(),
+}));
+
+import { vtexFetch } from "../../client";
+import { legacyProductList } from "../legacy";
+
+const sellers = (price: number) => [
+	{
+		sellerId: "1",
+		sellerName: "Seller One",
+		sellerDefault: true,
+		commertialOffer: {
+			AvailableQuantity: 5,
+			Price: price,
+			ListPrice: price + 30,
+			PriceWithoutDiscount: price + 30,
+			spotPrice: price,
+			PriceValidUntil: "2025-12-31",
+			// A real ladder: every method the store accepts, every installment count.
+			Installments: ["Visa", "Master", "Amex", "Boleto"].flatMap((method) =>
+				Array.from({ length: 4 }, (_, i) => ({
+					Value: price / (i + 1),
+					NumberOfInstallments: i + 1,
+					Name: `${method} ${i + 1}x`,
+					InterestRate: 0,
+					TotalValuePlusInterestRate: price,
+					PaymentSystemName: method,
+				})),
+			),
+			GiftSkuIds: [],
+			teasers: [],
+		},
+	},
+];
+
+const sku = (itemId: string, price: number) => ({
+	itemId,
+	name: `SKU ${itemId}`,
+	nameComplete: `SKU ${itemId}`,
+	complementName: "",
+	ean: "1234567890123",
+	referenceId: [{ Key: "RefId", Value: `REF-${itemId}` }],
+	images: Array.from({ length: 4 }, (_, i) => ({
+		imageId: `${itemId}-${i}`,
+		imageUrl: `https://img.com/${itemId}-${i}.jpg`,
+		imageText: `img${i}`,
+		imageLabel: `label${i}`,
+	})),
+	sellers: sellers(price),
+	Videos: [],
+	estimatedDateArrival: null,
+	measurementUnit: "un",
+	unitMultiplier: 1,
+	variations: [],
+	attachments: [],
+	isKit: false,
+});
+
+const legacyProduct = () => ({
+	productId: "PROD1",
+	productName: "Test Product",
+	brand: "TestBrand",
+	brandId: 1,
+	brandImageUrl: null,
+	linkText: "test-product",
+	productReference: "REF1",
+	categoryId: "1",
+	productTitle: "Test Product",
+	metaTagDescription: "meta",
+	clusterHighlights: {},
+	productClusters: {},
+	searchableClusters: {},
+	categories: ["/Electronics/"],
+	categoriesIds: ["/1/"],
+	link: "https://test/test-product/p",
+	description: "x".repeat(2000),
+	items: [sku("SKU1", 90), sku("SKU2", 60), sku("SKU3", 120)],
+	allSpecifications: [],
+	allSpecificationsGroups: [],
+	skuSpecifications: [],
+	releaseDate: "2024-01-01",
+});
+
+const opts = { query: { count: 1 } as any, baseUrl: "https://example.com" };
+const ladderOf = (p: any) => p?.offers?.offers?.[0]?.priceSpecification ?? [];
+
+describe("legacyProductList — payload-shaping options reach toProduct", () => {
+	beforeEach(() => {
+		(vtexFetch as any).mockReset();
+		(vtexFetch as any).mockResolvedValue([legacyProduct()]);
+	});
+
+	it("no options: full product, full ladder, every variant, every image", async () => {
+		const [p] = (await legacyProductList(opts)) as any[];
+		expect(ladderOf(p).length).toBeGreaterThan(10);
+		expect(p.isVariantOf.hasVariant).toHaveLength(3);
+		expect(ladderOf(p.isVariantOf.hasVariant[0]).length).toBeGreaterThan(10);
+		expect(p.image).toHaveLength(4);
+		expect(p.description).toBeTruthy();
+	});
+
+	it("leanVariants empties the ladder on every variant", async () => {
+		const [p] = (await legacyProductList({ ...opts, leanVariants: true })) as any[];
+		for (const v of p.isVariantOf.hasVariant) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("displayedVariantId keeps the ladder on the one variant the card renders", async () => {
+		const [p] = (await legacyProductList({
+			...opts,
+			leanVariants: true,
+			displayedVariantId: (items: any[]) => items[1].itemId,
+		})) as any[];
+		const kept = p.isVariantOf.hasVariant.find((v: any) => v.sku === "SKU2");
+		expect(ladderOf(kept).length).toBeGreaterThan(0);
+		// ...and it is the LEAN shape, not a second full product.
+		expect(kept.description).toBeUndefined();
+	});
+
+	it("priceSpecifications rewrites the root ladder with the caller's rule", async () => {
+		const [p] = (await legacyProductList({
+			...opts,
+			priceSpecifications: (specs) => specs.filter((s) => !s.priceComponentType),
+		})) as any[];
+		expect(ladderOf(p).every((s: any) => !s.priceComponentType)).toBe(true);
+		expect(ladderOf(p).length).toBeLessThan(10);
+	});
+
+	it("maxImages caps image[] by position", async () => {
+		const [p] = (await legacyProductList({ ...opts, maxImages: 2 })) as any[];
+		expect(p.image).toHaveLength(2);
+	});
+
+	it("every option absent is byte-for-byte the previous output", async () => {
+		const [before] = (await legacyProductList(opts)) as any[];
+		const [after] = (await legacyProductList({
+			...opts,
+			leanVariants: undefined,
+			displayedVariantId: undefined,
+			maxImages: undefined,
+			priceSpecifications: undefined,
+		})) as any[];
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+});

package/src/loaders/autocomplete.ts

@@ -4,7 +4,7 @@
  * Combines /autocomplete_suggestions/ and /product_search/ in parallel,
  * transforms IS products to schema.org via pickSku + toProduct.
  */
-import { getVtexConfig, intelligentSearch as vtexIS } from "../client";
+import { getVtexConfig, intelligentSearch as vtexIS, storefrontBaseUrl } from "../client";
 import { pickSku, toProduct as toSchemaProduct } from "../utils/transform";
 
 export interface AutocompleteProps {
@@ -40,9 +40,7 @@ export async function autocompleteSearch(props: AutocompleteProps): Promise<Auto
 		]);
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		return {
 			searches: suggestionsData.searches ?? [],

package/src/loaders/intelligentSearch/productDetailsPage.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProductDetailsPage } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexCachedFetch } from "../../client";
+import { getVtexConfig, storefrontBaseUrl, vtexCachedFetch } from "../../client";
 import PDPDefaultPath from "../paths/PDPDefaultPath";
 import { searchBySlug } from "../../utils/slugCache";
 import { pickSku, toProductPage } from "../../utils/transform";
@@ -74,9 +74,7 @@ export default async function vtexProductDetailsPage(
 		}
 
 		const product = products[0];
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const sku = pickSku(product, skuId);
 

package/src/loaders/intelligentSearch/productList.ts

@@ -7,12 +7,25 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch, toFacetPath } from "../../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl, 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;
+	/**
+	 * Include every SKU as a lean variant in each product's isVariantOf.hasVariant[]
+	 * so shelf cards can render the full size/color grid. Default false (lean shelf:
+	 * a single in-stock variant per product).
+	 */
+	completeVariants?: boolean;
+	/**
+	 * `imageLabel`s that survive the shelf transform's 2-image cap. Storefronts
+	 * that pick the card image by name (a still/packshot asset, a colour
+	 * thumbnail) need this: those assets are registered last on the SKU, so the
+	 * positional cap drops them and the card falls back to the first photo.
+	 */
+	keepImageNames?: string[];
 }
 
 interface CollectionProps {
@@ -130,16 +143,19 @@ export default async function vtexProductListShelf(
 		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"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		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" });
+			return toProductShelf(p, preferredSku, 0, {
+				baseUrl,
+				priceCurrency: "BRL",
+				shelfCompleteVariants: props.completeVariants,
+				keepImageNames: props.keepImageNames,
+			});
 		});
 
 		if (ids) {

package/src/loaders/intelligentSearch/productListingPage.ts

@@ -4,6 +4,7 @@ import {
 	intelligentSearch,
 	type PageType,
 	pageTypesFromPath,
+	storefrontBaseUrl,
 	toFacetPath,
 } from "../../client";
 import { pickSku, toProduct } from "../../utils/transform";
@@ -441,9 +442,7 @@ export default async function vtexProductListingPage(props: PLPProps): Promise<a
 		const { products: vtexProducts, pagination, recordsFiltered } = productsResult;
 
 		// 3. Transform products using shared transform pipeline (same as deco-cx/apps)
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.com.br`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const schemaProducts = (vtexProducts as ProductVTEX[]).map((p) => {
 			const sku = pickSku(p);

package/src/loaders/intelligentSearch/suggestions.ts

@@ -4,7 +4,7 @@
  */
 
 import type { Product, Suggestion } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch } from "../../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl } from "../../client";
 import { pickSku, toProduct } from "../../utils/transform";
 import type { Product as ProductVTEX } from "../../utils/types";
 
@@ -29,9 +29,7 @@ export default async function vtexSuggestions(props: SuggestionsProps): Promise<
 		}));
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const products: Product[] = (data.products ?? []).slice(0, props.count ?? 4).map((p) => {
 			const sku = pickSku(p);

package/src/loaders/legacy/relatedProductsLoader.ts

@@ -8,7 +8,7 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexCachedFetch } from "../../client";
+import { getVtexConfig, storefrontBaseUrl, vtexCachedFetch } from "../../client";
 import { resolveProductIdBySlug } from "../../utils/slugCache";
 import { pickSku, toProduct } from "../../utils/transform";
 import type { LegacyProduct } from "../../utils/types";
@@ -58,9 +58,7 @@ export default async function vtexRelatedProducts(
 		if (!related?.length) return [];
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		let result = related.slice(0, count).map((p) => {
 			const sku = pickSku(p);