@decocms/apps-vtex 7.21.0 → 7.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-vtex",
-  "version": "7.21.0",
+  "version": "7.22.0",
   "type": "module",
   "description": "Deco commerce app: VTEX integration",
   "repository": {
@@ -51,10 +51,10 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.21.0",
-    "@decocms/apps-commerce": "7.21.0",
-    "@decocms/apps-website": "7.21.0",
-    "@decocms/tanstack": "7.21.0"
+    "@decocms/blocks": "7.22.0",
+    "@decocms/apps-commerce": "7.22.0",
+    "@decocms/apps-website": "7.22.0",
+    "@decocms/tanstack": "7.22.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/loaders/cart/shipping.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureVtex } from "../../client";
+
+const simulateCartMock = vi.fn(async (props: any) => ({
+	logisticsInfo: [{ slas: [{ id: "sla-1" }] }],
+	echo: props,
+}));
+
+vi.mock("../../actions/checkout", () => ({
+	simulateCart: (props: any) => simulateCartMock(props),
+}));
+
+import { getShippingSimulation } from "./shipping";
+import { __resetSimulationCacheForTests } from "../../utils/simulationCache";
+
+describe("getShippingSimulation (#373)", () => {
+	beforeEach(() => {
+		configureVtex({ account: "acme", salesChannel: "1" });
+		__resetSimulationCacheForTests();
+		simulateCartMock.mockClear();
+	});
+
+	afterEach(() => {
+		__resetSimulationCacheForTests();
+	});
+
+	const props = {
+		items: [{ id: "1", quantity: 1, seller: "1" }],
+		postalCode: "01310-100",
+	};
+
+	it("calls simulateCart on a cache MISS and caches the response body", async () => {
+		const result = await getShippingSimulation(props);
+		expect(simulateCartMock).toHaveBeenCalledTimes(1);
+		expect(result).toEqual({ logisticsInfo: [{ slas: [{ id: "sla-1" }] }], echo: expect.anything() });
+	});
+
+	it("serves the cached response on a second call with the same tuple — no 2nd simulateCart call", async () => {
+		await getShippingSimulation(props);
+		await getShippingSimulation(props);
+		expect(simulateCartMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("calls simulateCart again for a different postalCode (different cache key)", async () => {
+		await getShippingSimulation(props);
+		await getShippingSimulation({ ...props, postalCode: "20040-020" });
+		expect(simulateCartMock).toHaveBeenCalledTimes(2);
+	});
+
+	it("calls simulateCart again for a different items composition", async () => {
+		await getShippingSimulation(props);
+		await getShippingSimulation({ ...props, items: [{ id: "2", quantity: 1, seller: "1" }] });
+		expect(simulateCartMock).toHaveBeenCalledTimes(2);
+	});
+
+	it("is order-insensitive for the items array (same composition, different order)", async () => {
+		const twoItems = {
+			...props,
+			items: [
+				{ id: "1", quantity: 1, seller: "1" },
+				{ id: "2", quantity: 2, seller: "1" },
+			],
+		};
+		const reordered = {
+			...props,
+			items: [
+				{ id: "2", quantity: 2, seller: "1" },
+				{ id: "1", quantity: 1, seller: "1" },
+			],
+		};
+		await getShippingSimulation(twoItems);
+		await getShippingSimulation(reordered);
+		expect(simulateCartMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("varies the cache key by salesChannel (different sc → different simulation)", async () => {
+		await getShippingSimulation(props);
+		configureVtex({ account: "acme", salesChannel: "2" });
+		await getShippingSimulation(props);
+		expect(simulateCartMock).toHaveBeenCalledTimes(2);
+	});
+
+	it("the cached response never carries cookies — only the plain JSON body", async () => {
+		const result = await getShippingSimulation(props);
+		expect(result).not.toHaveProperty("headers");
+		expect(JSON.stringify(result)).not.toContain("set-cookie");
+	});
+});

package/src/loaders/cart/shipping.ts

@@ -0,0 +1,70 @@
+/**
+ * Cached shipping simulation loader (#373).
+ *
+ * Wraps `simulateCart` (a POST to `/api/checkout/pub/orderForms/simulation`)
+ * with a cache keyed only on the non-personalized inputs — items,
+ * postalCode, country, and salesChannel. See `../../utils/simulationCache.ts`
+ * for why this can't just be `vtexCachedFetch` (POST + cookie-rotation).
+ *
+ * On a cache MISS, `simulateCart` still goes through `vtexFetchWithCookies`
+ * as normal — cookies rotate exactly as before. Only the response BODY
+ * (SLAs + logistics info) is cached; cookies are never stored or replayed.
+ */
+import { djb2 } from "@decocms/blocks/sdk/djb2";
+import { simulateCart, type SimulateCartProps, type SimulationItem } from "../../actions/checkout";
+import { getVtexConfig } from "../../client";
+import { getSimulationCache } from "../../utils/simulationCache";
+
+/** Shipping SLAs can shift with promotions/stock — keep the TTL short. */
+const DEFAULT_TTL_SECONDS = 5 * 60;
+
+export interface ShippingSimulationProps {
+	items: SimulationItem[];
+	postalCode: string;
+	country?: string;
+	/** Override the cache TTL (seconds). Defaults to 5 minutes. */
+	ttlSeconds?: number;
+}
+
+function buildCacheKey(props: ShippingSimulationProps): string {
+	const config = getVtexConfig();
+	const normalizedItems = [...props.items]
+		.map((item) => ({ id: String(item.id), quantity: item.quantity, seller: item.seller }))
+		.sort((a, b) => (a.id === b.id ? a.seller.localeCompare(b.seller) : a.id.localeCompare(b.id)));
+
+	const raw = JSON.stringify({
+		account: config.account,
+		salesChannel: config.salesChannel ?? null,
+		items: normalizedItems,
+		postalCode: props.postalCode,
+		country: props.country ?? config.country ?? "BRA",
+	});
+	return `shipping-sim:${djb2(raw)}`;
+}
+
+/**
+ * Fetch shipping SLAs for a cart, serving a cached response body when
+ * available for the same `{items, postalCode, salesChannel}` tuple.
+ */
+export async function getShippingSimulation(props: ShippingSimulationProps): Promise<unknown> {
+	const cache = getSimulationCache();
+	const key = buildCacheKey(props);
+
+	const cached = await cache.get(key);
+	if (cached != null) {
+		try {
+			return JSON.parse(cached);
+		} catch {
+			// Corrupted cache entry — fall through to a fresh simulation.
+		}
+	}
+
+	const simulateProps: SimulateCartProps = {
+		items: props.items,
+		postalCode: props.postalCode,
+		country: props.country,
+	};
+	const result = await simulateCart(simulateProps);
+	await cache.put(key, JSON.stringify(result), props.ttlSeconds ?? DEFAULT_TTL_SECONDS);
+	return result;
+}

package/src/loaders/index.ts

@@ -1,6 +1,7 @@
 export * from "./address";
 export * from "./brands";
 export * from "./cart";
+export * from "./cart/shipping";
 export * from "./catalog";
 export * from "./collections";
 export * from "./legacy";

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { mapLabelledFuzzyToFuzzy } from "../productListingPage";
+import { mapLabelledFuzzyToFuzzy, resolvePage } from "../productListingPage";
 
 describe("mapLabelledFuzzyToFuzzy", () => {
 	it("translates 'automatic' to 'auto'", () => {
@@ -18,3 +18,34 @@ describe("mapLabelledFuzzyToFuzzy", () => {
 		expect(mapLabelledFuzzyToFuzzy(undefined)).toBeUndefined();
 	});
 });
+
+describe("resolvePage (#391)", () => {
+	it("defaults to page 0 with no props.page and no URL page", () => {
+		expect(resolvePage(undefined, undefined)).toBe(0);
+	});
+
+	it("converts a 1-indexed URL ?page= to the 0-indexed internal page", () => {
+		expect(resolvePage(undefined, "3")).toBe(2);
+	});
+
+	it("uses props.page directly (already 0-indexed) over the URL", () => {
+		expect(resolvePage(5, "3")).toBe(5);
+	});
+
+	it("coerces a string props.page instead of silently falling back to 0", () => {
+		expect(resolvePage("3", undefined)).toBe(3);
+	});
+
+	it("falls through to the URL page when props.page is a non-finite string", () => {
+		expect(resolvePage("not-a-number", "3")).toBe(2);
+	});
+
+	it("resets a malformed ?page= to 0 instead of propagating NaN", () => {
+		expect(resolvePage(undefined, "abc")).toBe(0);
+	});
+
+	it("floors a fractional page and never returns a negative page", () => {
+		expect(resolvePage(2.7, undefined)).toBe(2);
+		expect(resolvePage(-1, undefined)).toBe(0);
+	});
+});

package/src/loaders/intelligentSearch/productListingPage.ts

@@ -28,6 +28,28 @@ export type LabelledFuzzy = "automatic" | "disabled" | "enabled";
  * @example
  *   intelligentSearch({ fuzzy: mapLabelledFuzzyToFuzzy(props.fuzzy) })
  */
+/**
+ * Resolve the 0-indexed internal `page` from the CMS prop and/or the
+ * 1-indexed URL `?page=` param.
+ *
+ * `props.page` may arrive as a string (e.g. auto-injected from a URL search
+ * param upstream) — `Number.isFinite` does NOT coerce, so a bare
+ * `Number.isFinite(propsPage)` check would silently treat `"3"` as invalid
+ * and hard-default to page 0 (see #391). Coerce first, and treat a
+ * non-finite coerced value as "absent" so it falls through to the URL
+ * parse instead of hard-defaulting.
+ */
+export function resolvePage(propsPage: number | string | undefined, pageFromUrl: string | null | undefined): number {
+	const coercedPropsPage = propsPage !== undefined ? Number(propsPage) : undefined;
+	const rawPage =
+		coercedPropsPage !== undefined && Number.isFinite(coercedPropsPage)
+			? coercedPropsPage
+			: pageFromUrl
+				? Number(pageFromUrl) - 1
+				: 0;
+	return Number.isFinite(rawPage) && rawPage >= 0 ? Math.floor(rawPage) : 0;
+}
+
 export const mapLabelledFuzzyToFuzzy = (label?: LabelledFuzzy): "0" | "1" | "auto" | undefined => {
 	switch (label) {
 		case "automatic":
@@ -333,9 +355,7 @@ export default async function vtexProductListingPage(props: PLPProps): Promise<a
 	// raw IS API value. The URL param is already a raw value, so it passes through.
 	const fuzzy =
 		mapLabelledFuzzyToFuzzy(props.fuzzy) ?? pageUrl?.searchParams.get("fuzzy") ?? undefined;
-	const pageFromUrl = pageUrl?.searchParams.get("page");
-	const rawPage = props.page ?? (pageFromUrl ? Number(pageFromUrl) - 1 : 0);
-	const page = Number.isFinite(rawPage) && rawPage >= 0 ? Math.floor(rawPage) : 0;
+	const page = resolvePage(props.page, pageUrl?.searchParams.get("page"));
 
 	const { selectedFacets: cmsSelectedFacets, hideUnavailableItems = false, __pagePath } = props;
 

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

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	__resetSimulationCacheForTests,
+	getSimulationCache,
+	setSimulationCache,
+} from "../simulationCache";
+
+describe("simulationCache (#373)", () => {
+	afterEach(() => {
+		__resetSimulationCacheForTests();
+	});
+
+	it("default in-process cache: returns null on miss, then the value after put", async () => {
+		const cache = getSimulationCache();
+		expect(await cache.get("k")).toBeNull();
+		await cache.put("k", "v", 60);
+		expect(await cache.get("k")).toBe("v");
+	});
+
+	it("expires an entry past its TTL", async () => {
+		const cache = getSimulationCache();
+		await cache.put("k", "v", 0); // already expired
+		await new Promise((r) => setTimeout(r, 5));
+		expect(await cache.get("k")).toBeNull();
+	});
+
+	it("setSimulationCache injects a custom implementation", async () => {
+		const store = new Map<string, string>();
+		setSimulationCache({
+			get: (k) => store.get(k) ?? null,
+			put: (k, v) => {
+				store.set(k, v);
+			},
+		});
+		const cache = getSimulationCache();
+		await cache.put("k", "custom-value", 60);
+		expect(await cache.get("k")).toBe("custom-value");
+		expect(store.get("k")).toBe("custom-value");
+	});
+});

package/src/utils/simulationCache.ts

@@ -0,0 +1,73 @@
+/**
+ * Injectable cache for shipping simulation responses (#373).
+ *
+ * `simulateCart`'s POST to `/api/checkout/pub/orderForms/simulation` is not
+ * user-personalized for a given `{items, postalCode, salesChannel}` tuple —
+ * every shopper with the same cart composition and zip code gets the same
+ * SLAs — but it goes through `vtexFetchWithCookies` (cookies can rotate on
+ * this endpoint), so caching the raw response risks replaying a stale
+ * session's cookies onto a different user.
+ *
+ * This cache stores ONLY the response body (SLAs/logistics info) — never
+ * cookies or session state. The default is an in-process Map (works in both
+ * `@decocms/tanstack` and `@decocms/nextjs`, no infra required, but is only
+ * warm within a single Worker isolate's lifetime). Sites that want a shared
+ * edge cache (Cloudflare Cache API, KV) inject their own implementation via
+ * `setSimulationCache` — mirrors the `setFastDeployKVGetter` pattern in
+ * `@decocms/blocks-admin/src/admin/decofile.ts`.
+ */
+
+export interface SimulationCache {
+	get(key: string): Promise<string | null> | string | null;
+	put(key: string, value: string, ttlSeconds: number): Promise<void> | void;
+}
+
+interface InProcessEntry {
+	value: string;
+	expiresAt: number;
+}
+
+const DEFAULT_MAX_ENTRIES = 500;
+
+function createInProcessCache(): SimulationCache {
+	const store = new Map<string, InProcessEntry>();
+
+	function evictIfNeeded() {
+		if (store.size <= DEFAULT_MAX_ENTRIES) return;
+		const oldestKey = store.keys().next().value;
+		if (oldestKey !== undefined) store.delete(oldestKey);
+	}
+
+	return {
+		get(key) {
+			const entry = store.get(key);
+			if (!entry) return null;
+			if (Date.now() > entry.expiresAt) {
+				store.delete(key);
+				return null;
+			}
+			return entry.value;
+		},
+		put(key, value, ttlSeconds) {
+			store.delete(key); // re-insert for Map's insertion-order-based eviction
+			store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+			evictIfNeeded();
+		},
+	};
+}
+
+let cache: SimulationCache = createInProcessCache();
+
+/** Inject a custom simulation cache (e.g. Cloudflare Cache API or KV-backed). */
+export function setSimulationCache(custom: SimulationCache): void {
+	cache = custom;
+}
+
+export function getSimulationCache(): SimulationCache {
+	return cache;
+}
+
+/** @internal exported for tests */
+export function __resetSimulationCacheForTests(): void {
+	cache = createInProcessCache();
+}