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

package/src/utils/fetchCache.ts

@@ -1,12 +1,20 @@
 /**
- * SWR in-memory fetch cache for VTEX API responses.
+ * VTEX SWR fetch cache — a thin binding over the shared, instrumented
+ * `createFetchCache` in `@decocms/blocks/sdk/fetchCache`.
  *
- * Inspired by deco-cx/deco runtime/fetch/fetchCache.ts.
- * Provides in-flight deduplication + stale-while-revalidate for GET requests.
- *
- * Only caches on the server side. Keyed by full URL string.
+ * The implementation (in-flight dedup, stale-while-revalidate, stale-if-error,
+ * inflight backstop) now lives ONCE in the framework so every commerce app
+ * shares it and emits `deco.cache.requests{layer="swr"}` automatically. This
+ * module just wires VTEX's tuning constants (`./constants`) and the
+ * `provider: "vtex"` label into a single module-level instance, preserving the
+ * public surface (`fetchWithCache` / `clearFetchCache` / `getFetchCacheStats` /
+ * `FetchCacheOptions`) that `client.ts` and existing tests depend on.
  */
 
+import {
+  createFetchCache,
+  type FetchCacheOptions as SharedFetchCacheOptions,
+} from "@decocms/blocks/sdk/fetchCache";
 import {
   FETCH_CACHE_FRESH_TTL_MS,
   FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
@@ -14,186 +22,34 @@ import {
   FETCH_CACHE_STALE_IF_ERROR_MS,
 } from "./constants";
 
-interface CacheEntry {
-  body: unknown;
-  status: number;
-  createdAt: number;
-  refreshing: boolean;
-}
-
-function freshTtlForStatus(status: number): number {
-  if (status >= 200 && status < 300) return FETCH_CACHE_FRESH_TTL_MS.success;
-  if (status === 404) return FETCH_CACHE_FRESH_TTL_MS.notFound;
-  if (status >= 500) return FETCH_CACHE_FRESH_TTL_MS.serverError;
-  return 0;
-}
-
-const store = new Map<string, CacheEntry>();
-const inflight = new Map<string, Promise<CacheEntry>>();
-
-function evictIfNeeded() {
-  if (store.size <= FETCH_CACHE_MAX_ENTRIES) return;
-  const sorted = [...store.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
-  const toRemove = sorted.slice(0, store.size - FETCH_CACHE_MAX_ENTRIES);
-  for (const [key] of toRemove) store.delete(key);
-}
-
-/**
- * Race a Promise against a timeout so callers' `.finally()` always runs.
- * Critical for evicting the inflight Map entry when a `fetch()` hangs —
- * without this, a never-settling Promise leaks the Map slot forever and
- * every subsequent request for the same key joins the zombie Promise.
- */
-function withTimeout<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      reject(new Error(`${label} timed out after ${ms}ms`));
-    }, ms);
-  });
-  return Promise.race([work, timeout]).finally(() => {
-    clearTimeout(timer);
-  });
-}
-
-async function executeFetch(url: string, doFetch: () => Promise<Response>): Promise<CacheEntry> {
-  // Single attempt on purpose. The resilience layer (`createResilientFetch`,
-  // wired as the VTEX fetch's baseFetch) owns retries, backoff+jitter, the
-  // per-host retry budget, and the circuit breaker. Retrying here would:
-  //   - double-retry network errors (resilience 3× × fetchCache 3× = up to 9
-  //     upstream calls per logical request — the retry storm the budget
-  //     prevents), and
-  //   - re-enter the breaker on every 5xx retry, opening it ~3× too fast.
-  const response = await doFetch();
+export type FetchCacheOptions = SharedFetchCacheOptions;
 
-  if (response.status >= 500) {
-    throw new Error(`fetchWithCache: ${response.status} ${response.statusText} — ${url}`);
-  }
-
-  const body = response.ok ? await response.json() : null;
-  return {
-    body,
-    status: response.status,
-    createdAt: Date.now(),
-    refreshing: false,
-  };
-}
-
-export interface FetchCacheOptions {
-  /**
-   * Custom TTL in ms. If provided, overrides status-based TTL.
-   */
-  ttl?: number;
-  /**
-   * Stale-if-error window in ms. How long past the freshness TTL a last-good
-   * entry may still be served while the origin is failing. Defaults to
-   * {@link FETCH_CACHE_STALE_IF_ERROR_MS} (24h). Set to 0 to disable stale
-   * serving.
-   */
-  sieMs?: number;
-}
+const cache = createFetchCache({
+  provider: "vtex",
+  maxEntries: FETCH_CACHE_MAX_ENTRIES,
+  freshTtlMs: FETCH_CACHE_FRESH_TTL_MS,
+  staleIfErrorMs: FETCH_CACHE_STALE_IF_ERROR_MS,
+  inflightBackstopMs: FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
+});
 
 /**
  * Wrap a GET fetch call with SWR caching and in-flight dedup.
  *
  * Returns `null` for non-2xx responses that are cached (e.g. 404).
  * 5xx responses throw so the caller can handle them explicitly.
- *
- * @param cacheKey - Unique key (typically the full URL)
- * @param doFetch - The actual fetch call to execute
- * @param opts - Optional overrides
- * @returns Parsed JSON body, or null for cacheable error responses (e.g. 404)
  */
 export function fetchWithCache<T>(
   cacheKey: string,
   doFetch: () => Promise<Response>,
   opts?: FetchCacheOptions,
 ): Promise<T | null> {
-  const now = Date.now();
-  const entry = store.get(cacheKey);
-
-  if (entry) {
-    const maxAge = opts?.ttl ?? freshTtlForStatus(entry.status);
-    const age = now - entry.createdAt;
-    const isStale = age > maxAge;
-
-    if (!isStale) return Promise.resolve(entry.body as T | null);
-
-    // Beyond the stale-if-error window the last-good entry is too old to keep
-    // serving during an outage: drop it and fall through to a foreground
-    // refetch (cold path). On a healthy origin this is never reached because
-    // the background refresh below keeps resetting `createdAt`.
-    const sieMs = opts?.sieMs ?? FETCH_CACHE_STALE_IF_ERROR_MS;
-    const tooStale = age > maxAge + sieMs;
-
-    if (!tooStale) {
-      if (!entry.refreshing) {
-        entry.refreshing = true;
-        // Background refresh: no retry — stale data is already being served.
-        // Timeout guards against a hung VTEX response leaving `refreshing`
-        // stuck true forever (which would silently disable revalidation).
-        withTimeout(
-          executeFetch(cacheKey, doFetch),
-          FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
-          `fetchCache stale-refresh ${cacheKey}`,
-        )
-          .then((fresh) => {
-            const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
-            const existingWasSuccess = entry.status >= 200 && entry.status < 300;
-            const freshIsError = fresh.status >= 400;
-            const wouldDowngrade = existingWasSuccess && freshIsError;
-            if (ttl > 0 && !wouldDowngrade) {
-              store.set(cacheKey, fresh);
-            } else {
-              entry.refreshing = false;
-            }
-          })
-          .catch(() => {
-            entry.refreshing = false;
-          });
-      }
-      // Serve last-good while it is within the SIE window (stale-if-error).
-      return Promise.resolve(entry.body as T | null);
-    }
-
-    store.delete(cacheKey);
-    // fall through to the cold path below with the dead entry removed
-  }
-
-  const existing = inflight.get(cacheKey);
-  if (existing) return existing.then((e) => e.body as T | null);
-
-  // Wrap with a timeout so the `.finally()` below always runs and evicts
-  // the inflight slot — even if `executeFetch` never settles. See the
-  // FETCH_CACHE_INFLIGHT_BACKSTOP_MS doc comment (constants.ts) for the leak
-  // this guards against.
-  const promise = withTimeout(
-    executeFetch(cacheKey, doFetch),
-    FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
-    `fetchCache ${cacheKey}`,
-  )
-    .then((fresh) => {
-      const ttl = opts?.ttl ?? freshTtlForStatus(fresh.status);
-      if (ttl > 0) {
-        store.set(cacheKey, fresh);
-        evictIfNeeded();
-      }
-      return fresh;
-    })
-    .finally(() => inflight.delete(cacheKey));
-
-  inflight.set(cacheKey, promise);
-  return promise.then((e) => e.body as T | null);
+  return cache.fetchWithCache<T>(cacheKey, doFetch, opts);
 }
 
 export function clearFetchCache() {
-  store.clear();
-  inflight.clear();
+  cache.clear();
 }
 
 export function getFetchCacheStats() {
-  return {
-    entries: store.size,
-    inflight: inflight.size,
-  };
+  return cache.getStats();
 }

package/src/utils/instrumentedFetch.ts

@@ -30,6 +30,7 @@
  * behavior.
  */
 
+import type { FetchFn } from "@decocms/blocks/sdk/fetchTimeout";
 import {
   createInstrumentedFetch,
   type InstrumentedFetch,
@@ -45,7 +46,7 @@ export interface CreateVtexFetchOptions {
    * or routes through a proxy) to preserve its behavior while adding
    * the VTEX instrumentation layer on top.
    */
-  baseFetch?: typeof fetch;
+  baseFetch?: FetchFn;
   /**
    * Disable the `http.client.request.duration` histogram emission for
    * VTEX calls. The framework's span and structured logs still emit.

package/src/utils/minicart.ts

@@ -71,7 +71,7 @@ function vtexItemToMinicartItem(item: OrderFormItem, index: number, coupon?: str
 
 	return {
 		// AnalyticsItem identifier — VTEX uses productId; sites map to numeric SKU
-		// when needed via `Number(item.item_id)` (see bagaggio Minicart).
+		// when needed via `Number(item.item_id)` (see a production Minicart).
 		item_id: item.id,
 		item_group_id: item.productId,
 		item_name: item.name ?? item.skuName ?? "",

package/src/utils/operationRouter.ts

@@ -118,16 +118,10 @@ const MATCHERS: ReadonlyArray<Matcher> = [
  * });
  * ```
  */
+import { extractPathname } from "@decocms/blocks/sdk/urlUtils";
+
 export function vtexOperationRouter(url: string, method: string): string | undefined {
-	let pathname: string;
-	try {
-		pathname = new URL(url).pathname;
-	} catch {
-		const qs = url.indexOf("?");
-		const hash = url.indexOf("#");
-		const end = [qs, hash].filter((i) => i >= 0).sort((a, b) => a - b)[0];
-		pathname = end === undefined ? url : url.slice(0, end);
-	}
+	const pathname = extractPathname(url);
 
 	const upperMethod = method.toUpperCase();
 	for (const { pattern, operation } of MATCHERS) {

package/src/utils/proxy.ts

@@ -45,6 +45,14 @@ export interface VtexProxyOptions {
 	 * Custom headers to inject into every proxied request.
 	 */
 	extraHeaders?: Record<string, string>;
+
+	/**
+	 * Force `Cache-Control: private, no-store` + `CDN-Cache-Control: no-store`
+	 * on authenticated proxy responses (everything except static assets), so a
+	 * personalized VTEX response can never be cached and served across users.
+	 * @default true
+	 */
+	hardenAuthenticatedCache?: boolean;
 }
 
 const DEFAULT_PROXY_PATHS = [
@@ -79,6 +87,42 @@ const HOP_BY_HOP_HEADERS = new Set([
 	"upgrade",
 ]);
 
+/**
+ * Path prefixes whose proxied responses are safe to cache publicly — genuinely
+ * public static assets (media files, VTEX store-theme bundles). Everything else
+ * routed through the VTEX proxy is authenticated/personalized by nature
+ * (account, checkout, /api/sessions, orders, graphql, VTEX ID) and MUST NOT be
+ * cached by shared/edge layers.
+ */
+const PUBLIC_PROXY_ASSET_PREFIXES = [
+	"/files/",
+	"/arquivos/",
+	"/assets/vtex",
+	"/XMLData/",
+];
+
+function isPublicProxyAsset(pathname: string): boolean {
+	return PUBLIC_PROXY_ASSET_PREFIXES.some((p) => pathname.startsWith(p));
+}
+
+/**
+ * Force authenticated proxy responses to be non-cacheable on every shared layer.
+ *
+ * VTEX marks some endpoints `no-store` (e.g. `/api/sessions`) but not all
+ * (`/account` comes back `public`), and the raw origin `Cache-Control` must
+ * never let a personalized response be cached across users. Without this, a
+ * logged-in user's response can be stored at the edge and served to another
+ * user — the root cause of a cross-customer data leak (see decocms/blocks#412).
+ * Static assets are exempt so store-theme/media caching is preserved.
+ */
+function hardenProxyCacheHeaders(headers: Headers, pathname: string): void {
+	if (isPublicProxyAsset(pathname)) return;
+	headers.set("Cache-Control", "private, no-store, no-cache, must-revalidate");
+	// CDN-Cache-Control takes precedence for Cloudflare's CDN layer.
+	headers.set("CDN-Cache-Control", "no-store");
+	headers.delete("Surrogate-Control");
+}
+
 /**
  * Returns all path prefixes that should be proxied to VTEX.
  */
@@ -199,6 +243,10 @@ export async function proxyToVtex(request: Request, options?: VtexProxyOptions):
 		}
 	}
 
+	if (options?.hardenAuthenticatedCache !== false) {
+		hardenProxyCacheHeaders(responseHeaders, requestUrl.pathname);
+	}
+
 	return new Response(originResponse.body, {
 		status: originResponse.status,
 		statusText: originResponse.statusText,
@@ -211,11 +259,11 @@ export async function proxyToVtex(request: Request, options?: VtexProxyOptions):
 // ---------------------------------------------------------------------------
 
 export interface VtexCheckoutProxyConfig {
-	/** VTEX account name (e.g. "casaevideonewio"). */
+	/** VTEX account name (e.g. "acme"). */
 	account: string;
 
 	/**
-	 * Store's public checkout domain (e.g. "secure.casaevideo.com.br").
+	 * Store's public checkout domain (e.g. "secure.acme.com.br").
 	 * Checkout UI, /files/, and /_v/private/graphql are routed here.
 	 */
 	checkoutOrigin: string;
@@ -254,6 +302,14 @@ export interface VtexCheckoutProxyConfig {
 	 * Receives the full HTML string and should return the modified version.
 	 */
 	htmlTransform?: (html: string) => string;
+
+	/**
+	 * Force `Cache-Control: private, no-store` + `CDN-Cache-Control: no-store`
+	 * on authenticated proxy responses (everything except static assets), so a
+	 * personalized VTEX response can never be cached and served across users.
+	 * @default true
+	 */
+	hardenAuthenticatedCache?: boolean;
 }
 
 const CF_INTERNAL_HEADERS = new Set([
@@ -316,8 +372,8 @@ function rewriteSetCookieDomain(from: Headers, to: Headers, toHostname: string)
  * @example
  * ```ts
  * const vtexProxy = createVtexCheckoutProxy({
- *   account: "casaevideonewio",
- *   checkoutOrigin: "secure.casaevideo.com.br",
+ *   account: "acme",
+ *   checkoutOrigin: "secure.acme.com.br",
  *   expireCookiesOnPaths: [
  *     { pathPrefix: "/api/vtexid/pub/logout", cookies: ["checkout.vtex.com"] },
  *   ],
@@ -414,6 +470,10 @@ export function createVtexCheckoutProxy(
 			}
 		}
 
+		if (config.hardenAuthenticatedCache !== false) {
+			hardenProxyCacheHeaders(resHeaders, url.pathname);
+		}
+
 		// HTML transform for checkout pages
 		const ct = originRes.headers.get("content-type") ?? "";
 		if (config.htmlTransform && ct.includes("text/html")) {

package/src/utils/similars.ts

@@ -1,5 +1,5 @@
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexFetch } from "../client";
+import { getVtexConfig, storefrontBaseUrl, vtexFetch } from "../client";
 import { pickSku, toProduct } from "./transform";
 import type { LegacyProduct } from "./types";
 
@@ -18,9 +18,7 @@ export const withIsSimilarTo = async (product: Product): Promise<Product> => {
 		if (!rawSimilars?.length) return product;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const similars = rawSimilars.map((p) => {
 			const sku = pickSku(p);

package/src/utils/sitemap.ts

@@ -11,6 +11,7 @@
  *   needs to expose VTEX's existing crawl tree to the public hostname.
  */
 
+import { type FetchFn, withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
 import { getVtexConfig, vtexFetchResponse, vtexHost } from "../client";
 
 export interface SitemapEntry {
@@ -185,7 +186,7 @@ export interface VtexSitemapProxyConfig {
 	 * Optional fetch override — primarily for tests. Defaults to the
 	 * platform `fetch`.
 	 */
-	fetchImpl?: typeof fetch;
+	fetchImpl?: FetchFn;
 }
 
 const DEFAULT_SITEMAP_CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400";
@@ -238,7 +239,7 @@ export function createVtexSitemapProxy(
 	const environment = config.environment ?? "vtexcommercestable";
 	const cacheControl = config.cacheControl ?? DEFAULT_SITEMAP_CACHE_CONTROL;
 	const extraSitemaps = config.extraSitemaps ?? [];
-	const fetchImpl = config.fetchImpl ?? fetch;
+	const fetchImpl = config.fetchImpl ?? withFetchTimeout();
 
 	return async (_request: Request, url: URL): Promise<Response | null> => {
 		if (!isVtexSitemapPath(url.pathname)) return null;