@decocms/apps 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -122,6 +122,7 @@
     "@tanstack/react-query": "^5.90.21",
     "@types/react": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "happy-dom": "^20.9.0",
     "knip": "^5.86.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

package/vtex/utils/sitemap.ts

@@ -1,9 +1,14 @@
 /**
- * VTEX Sitemap utility.
+ * VTEX Sitemap utilities.
  *
- * Fetches product and category URLs from VTEX's sitemap API
- * and converts them to SitemapEntry format for composition
- * with the CMS sitemap generator.
+ * Two flavors:
+ * - `getVtexSitemapEntries()` — flatten VTEX sub-sitemaps into a single
+ *   `SitemapEntry[]` list, for composition with the CMS sitemap generator.
+ * - `createVtexSitemapProxy()` — proxy `/sitemap.xml` and `/sitemap/*`
+ *   straight from VTEX's commerce-stable origin, preserving the sitemap-index
+ *   shape (so crawlers stay within Google's per-file size limit). This is the
+ *   right choice when the storefront has no native sitemap renderer and just
+ *   needs to expose VTEX's existing crawl tree to the public hostname.
  */
 
 import { getVtexConfig, vtexFetchResponse, vtexHost } from "../client";
@@ -131,3 +136,147 @@ function rewriteUrl(url: string, vtexSitemapHost: string, origin: string): strin
 		return url.replace(`https://${vtexSitemapHost}`, origin);
 	}
 }
+
+// ---------------------------------------------------------------------------
+// VTEX sitemap proxy factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if `pathname` is one of the proxied sitemap paths
+ * (`/sitemap.xml` or any `/sitemap/*` sub-sitemap).
+ */
+export function isVtexSitemapPath(pathname: string): boolean {
+	return pathname === "/sitemap.xml" || pathname.startsWith("/sitemap/");
+}
+
+export interface VtexSitemapProxyConfig {
+	/**
+	 * Extra `<sitemap>` entries to inject into the root sitemap index
+	 * (`/sitemap.xml` only — sub-sitemaps are passed through untouched).
+	 *
+	 * Useful for site-managed sitemaps such as a static search-result
+	 * index (`sitemap-busca.xml`) that VTEX doesn't generate.
+	 *
+	 * Each value is normalized to an absolute URL on the storefront
+	 * origin: leading-slash paths become `${origin}${path}`, and bare
+	 * names become `${origin}/${name}`. Absolute URLs are used as-is.
+	 *
+	 * @example ["/sitemap-busca.xml"]
+	 */
+	extraSitemaps?: string[];
+
+	/**
+	 * VTEX environment for the upstream sitemap fetch.
+	 * @default "vtexcommercestable"
+	 */
+	environment?: "vtexcommercestable" | "vtexcommercebeta";
+
+	/**
+	 * `Cache-Control` header to set on proxied responses. The default
+	 * favors edge caching (Cloudflare honors `s-maxage`) with a long
+	 * stale-while-revalidate window so a slow VTEX origin never blocks
+	 * crawlers.
+	 *
+	 * @default "public, s-maxage=3600, stale-while-revalidate=86400"
+	 */
+	cacheControl?: string;
+
+	/**
+	 * Optional fetch override — primarily for tests. Defaults to the
+	 * platform `fetch`.
+	 */
+	fetchImpl?: typeof fetch;
+}
+
+const DEFAULT_SITEMAP_CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400";
+
+function normalizeExtraSitemap(entry: string, origin: string): string {
+	if (entry.startsWith("http://") || entry.startsWith("https://")) return entry;
+	const path = entry.startsWith("/") ? entry : `/${entry}`;
+	return `${origin}${path}`;
+}
+
+/**
+ * Creates a sitemap proxy handler that mirrors VTEX's `/sitemap.xml`
+ * (and sub-sitemaps) onto the storefront origin.
+ *
+ * Returns a function compatible with `createDecoWorkerEntry`'s
+ * `proxyHandler`: it returns `null` for non-sitemap paths, so it
+ * composes naturally with other proxy handlers
+ * (`createVtexCheckoutProxy`, custom logic, etc.).
+ *
+ * The VTEX account is read from the `configureVtex(...)` call done at
+ * worker startup — no per-call account configuration is needed.
+ *
+ * @example
+ * ```ts
+ * import { createVtexSitemapProxy } from "@decocms/apps/vtex/utils/sitemap";
+ * import {
+ *   createVtexCheckoutProxy,
+ *   shouldProxyToVtex,
+ * } from "@decocms/apps/vtex/utils/proxy";
+ *
+ * const proxySitemap = createVtexSitemapProxy({
+ *   extraSitemaps: ["/sitemap-busca.xml"], // optional, site-managed
+ * });
+ * const proxyCheckout = createVtexCheckoutProxy({ ... });
+ *
+ * createDecoWorkerEntry(serverEntry, {
+ *   proxyHandler: async (request, url) => {
+ *     const sitemap = await proxySitemap(request, url);
+ *     if (sitemap) return sitemap;
+ *
+ *     if (!shouldProxyToVtex(url.pathname)) return null;
+ *     return proxyCheckout(request, url);
+ *   },
+ * });
+ * ```
+ */
+export function createVtexSitemapProxy(
+	config: VtexSitemapProxyConfig = {},
+): (request: Request, url: URL) => Promise<Response | null> {
+	const environment = config.environment ?? "vtexcommercestable";
+	const cacheControl = config.cacheControl ?? DEFAULT_SITEMAP_CACHE_CONTROL;
+	const extraSitemaps = config.extraSitemaps ?? [];
+	const fetchImpl = config.fetchImpl ?? fetch;
+
+	return async (_request: Request, url: URL): Promise<Response | null> => {
+		if (!isVtexSitemapPath(url.pathname)) return null;
+
+		// vtexHost() reads the configured account from configureVtex().
+		const vtexSitemapHost = vtexHost(environment);
+		const target = `https://${vtexSitemapHost}${url.pathname}`;
+
+		try {
+			const resp = await fetchImpl(target);
+			if (!resp.ok) {
+				console.error(`[vtex-sitemap] VTEX returned ${resp.status} for ${url.pathname}`);
+				return new Response("Sitemap temporarily unavailable", { status: 502 });
+			}
+
+			let xml = await resp.text();
+			xml = xml.replaceAll(`https://${vtexSitemapHost}`, url.origin);
+
+			if (url.pathname === "/sitemap.xml" && extraSitemaps.length > 0) {
+				const extraEntries = extraSitemaps
+					.map(
+						(s) =>
+							`  <sitemap>\n    <loc>${normalizeExtraSitemap(s, url.origin)}</loc>\n  </sitemap>`,
+					)
+					.join("\n");
+				xml = xml.replace("</sitemapindex>", `${extraEntries}\n</sitemapindex>`);
+			}
+
+			return new Response(xml, {
+				status: 200,
+				headers: {
+					"Content-Type": "application/xml; charset=utf-8",
+					"Cache-Control": cacheControl,
+				},
+			});
+		} catch (err) {
+			console.error("[vtex-sitemap] Failed to proxy VTEX sitemap:", err);
+			return new Response("Sitemap temporarily unavailable", { status: 502 });
+		}
+	};
+}

package/website/components/OneDollarStats.tsx

@@ -1,10 +1,9 @@
 /**
  * OneDollarStats — deco's lightweight in-house analytics.
  *
- * Pings the lilstts collector with pageviews (initial load + SPA navigations)
- * and forwards custom DECO events as `stonks.event(name, params)`.
- *
- * Mount in the site's `__root.tsx` as a child of `DecoRootLayout`:
+ * Posts pageviews (initial load + SPA navigations) and forwards DECO
+ * events to the lilstts collector. Mount once in `__root.tsx` as a child
+ * of `DecoRootLayout`:
  *
  * ```tsx
  * <DecoRootLayout … >
@@ -12,25 +11,53 @@
  * </DecoRootLayout>
  * ```
  *
- * No CMS wiring is needed — the component is env-gated and self-mounting.
+ * The component is env-gated and self-mounting — no CMS wiring needed.
+ *
+ * ## Why this design
+ *
+ * 1. **We own pageviews.** The lilstts SDK has its own auto-pageview path
+ *    (driven by `history.pushState` wrapping). We disable it via
+ *    `data-autocollect="false"` and call `window.stonks.view(flags)`
+ *    ourselves. This is the only way to attach `deco_segment` cookie
+ *    flags to pageviews — the SDK's auto-path doesn't know about them.
+ *
+ * 2. **`useEffect` for client logic.** All side-effects (initial pageview,
+ *    pushState wrap, DECO event subscribe) run inside a `useEffect`,
+ *    which fires after hydration. By then `<ScriptOnce>` in
+ *    `DecoRootLayout` has bootstrapped `window.DECO.events`, and the SDK
+ *    `<script>` (rendered as a sibling) has loaded and set
+ *    `window.stonks`. No inline `dangerouslySetInnerHTML` snippet, no
+ *    fragile script-execution-order dependency.
+ *
+ * 3. **Module-level guards.** `window.DECO.events.subscribe()` returns no
+ *    unsubscribe handle, so we cannot clean up on unmount. We use a
+ *    module-level `initialized` flag to ensure init runs exactly once
+ *    per page lifetime, surviving HMR and React StrictMode double-mount.
  *
- * Behavioral notes vs the Fresh deco-cx/apps OneDollarStats:
- *   - The initial pageview fires unconditionally (mirrors the Path B
- *     `analytics/loaders/OneDollarScript.ts` script-loader from Fresh).
- *     The Fresh component variant relied on a synthesised `{ name: "deco" }`
- *     event from `Events.tsx`'s subscribe-replay, which has no equivalent
- *     in TanStack — so we do not depend on it.
- *   - Flag enrichment continues to work via client-side parsing of the
- *     `deco_segment` cookie (same code path as the script-loader version).
- *   - `pageId` enrichment is intentionally dropped — no deco-admin dashboard
- *     consumes it. Add later if a flag-segmented dashboard needs it.
+ * 4. **Bounded readiness polling.** `window.stonks` and `window.DECO`
+ *    might not be ready the instant our effect fires (race with script
+ *    load). We poll every 50 ms for up to 10 s. Production: resolves
+ *    within one tick.
+ *
+ * ## Behavioural parity vs Fresh `deco-cx/apps`
+ *
+ * Mirrors the Path B snippet (`analytics/loaders/OneDollarScript.ts`):
+ * unconditional first pageview with flag enrichment, SPA nav tracking,
+ * and DECO event forwarding. Diverges from the Fresh component variant
+ * (which depended on a synthesised `{ name: "deco" }` event from
+ * `Events.tsx`'s subscribe-replay — no equivalent in TanStack).
+ *
+ * `pageId` enrichment is intentionally dropped — no admin dashboard
+ * consumes it. Add later if a flag-segmented dashboard needs it.
  */
 
+import { useEffect } from "react";
+
 declare global {
 	interface Window {
 		stonks?: {
-			view?: (params: Record<string, string | boolean>) => void;
-			event?: (name: string, params: Record<string, string | boolean>) => void;
+			view?: (params?: Record<string, string | boolean | number>) => void;
+			event?: (name: string, params?: Record<string, string | boolean | number>) => void;
 		};
 	}
 }
@@ -46,81 +73,13 @@ export const DEFAULT_COLLECTOR_ADDRESS = "https://d.lilstts.com/events";
 export const DEFAULT_ANALYTICS_SCRIPT_URL = "https://s.lilstts.com/deco.js";
 
 /**
- * `false` when `ONEDOLLAR_ENABLED=false` is set on the Worker. Default: enabled.
+ * Set `ONEDOLLAR_ENABLED=false` on the Worker to disable. Default: enabled.
  * Matches the Fresh-side Deno env contract.
  */
 const ONEDOLLAR_ENABLED = process.env.ONEDOLLAR_ENABLED !== "false";
 const ONEDOLLAR_COLLECTOR = process.env.ONEDOLLAR_COLLECTOR;
 const ONEDOLLAR_STATIC_SCRIPT = process.env.ONEDOLLAR_STATIC_SCRIPT;
 
-/**
- * Inline subscriber snippet — kept as a plain string constant (not a
- * `useScript(fn)` serialisation) because `fn.toString()` produces different
- * output in SSR vs client Vite builds under React Compiler, causing
- * hydration mismatches on `dangerouslySetInnerHTML`. See
- * `@decocms/start/sdk/useScript` for the deprecation note.
- *
- * Mirrors the Path B (`analytics/loaders/OneDollarScript.ts`) snippet from
- * deco-cx/apps: parse `deco_segment` cookie for flags, fire first pageview
- * unconditionally, patch `history.pushState` + `popstate` for SPA navs,
- * subscribe to `window.DECO.events` to forward non-`deco` events.
- */
-const ONEDOLLAR_SNIPPET = `(function(){
-	function parseCookies(str){
-		var out = {};
-		str.split(";").forEach(function(c){
-			var idx = c.indexOf("=");
-			if (idx < 0) return;
-			out[c.slice(0, idx).trim()] = c.slice(idx + 1).trim();
-		});
-		return out;
-	}
-	function tryOrDefault(fn, d){ try { return fn(); } catch(e) { return d; } }
-	function getFlags(cookies){
-		var out = [];
-		var raw = cookies["deco_segment"];
-		var seg = raw ? tryOrDefault(function(){ return JSON.parse(decodeURIComponent(atob(raw))); }, {}) : {};
-		(seg.active || []).forEach(function(name){ out.push({ name: name, value: true }); });
-		(seg.inactiveDrawn || []).forEach(function(name){ out.push({ name: name, value: false }); });
-		return out;
-	}
-	function truncate(v){ return ("" + v).slice(0, 990); }
-	var flagList = getFlags(parseCookies(document.cookie || ""));
-	var flags = {};
-	flagList.forEach(function(f){ flags[f.name] = f.value; });
-	function trackPageview(){
-		if (window.stonks && typeof window.stonks.view === "function") {
-			window.stonks.view(flags);
-		}
-	}
-	trackPageview();
-	var origPush = history.pushState;
-	if (origPush) {
-		history.pushState = function(){
-			origPush.apply(this, arguments);
-			trackPageview();
-		};
-		addEventListener("popstate", trackPageview);
-	}
-	if (window.DECO && window.DECO.events && typeof window.DECO.events.subscribe === "function") {
-		window.DECO.events.subscribe(function(event){
-			if (!event || !event.name || event.name === "deco") return;
-			var values = {};
-			for (var k in flags) values[k] = flags[k];
-			var params = event.params || {};
-			for (var key in params) {
-				var v = params[key];
-				if (v !== null && v !== undefined) {
-					values[key] = truncate(typeof v !== "object" ? v : JSON.stringify(v));
-				}
-			}
-			if (window.stonks && typeof window.stonks.event === "function") {
-				window.stonks.event(event.name, values);
-			}
-		});
-	}
-})();`;
-
 function OneDollarStats({ collectorAddress, staticScriptUrl }: Props) {
 	if (!ONEDOLLAR_ENABLED) return null;
 
@@ -132,15 +91,193 @@ function OneDollarStats({ collectorAddress, staticScriptUrl }: Props) {
 			<link rel="dns-prefetch" href={collector} />
 			<link rel="preconnect" href={collector} crossOrigin="anonymous" />
 			<script
-				id="tracker"
+				id="onedollarstats-tracker"
 				data-autocollect="false"
 				data-hash-routing="true"
 				data-url={collector}
 				src={staticScript}
+				defer
 			/>
-			<script defer dangerouslySetInnerHTML={{ __html: ONEDOLLAR_SNIPPET }} />
+			<OneDollarStatsClient />
 		</>
 	);
 }
 
+/**
+ * Client-only side-effects. Mounted as a child of {@link OneDollarStats};
+ * does not render any DOM.
+ */
+function OneDollarStatsClient() {
+	useEffect(() => {
+		initOneDollarStats();
+	}, []);
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Module-level state — survives StrictMode double-mount and HMR remounts.
+// ---------------------------------------------------------------------------
+
+let initialized = false;
+let cachedFlags: Record<string, boolean> | null = null;
+
+interface DecoSegmentCookie {
+	active?: string[];
+	inactiveDrawn?: string[];
+}
+
+/**
+ * Read A/B test flags from the `deco_segment` cookie. Cached after first
+ * read for the lifetime of the page — flags are baked at request time
+ * server-side and don't change mid-session.
+ *
+ * Exported for testing.
+ */
+export function readFlagsFromCookie(
+	cookieString: string = typeof document !== "undefined" ? document.cookie : "",
+): Record<string, boolean> {
+	if (cachedFlags && cookieString === (typeof document !== "undefined" ? document.cookie : "")) {
+		return cachedFlags;
+	}
+	const flags: Record<string, boolean> = {};
+	try {
+		const cookies = parseCookies(cookieString);
+		const raw = cookies.deco_segment;
+		if (raw) {
+			const seg = JSON.parse(decodeURIComponent(atob(raw))) as DecoSegmentCookie;
+			for (const name of seg.active ?? []) flags[name] = true;
+			for (const name of seg.inactiveDrawn ?? []) flags[name] = false;
+		}
+	} catch {
+		// Malformed cookie — proceed with empty flags rather than crashing analytics.
+	}
+	cachedFlags = flags;
+	return flags;
+}
+
+function parseCookies(cookieString: string): Record<string, string> {
+	return cookieString.split(";").reduce<Record<string, string>>((acc, c) => {
+		const idx = c.indexOf("=");
+		if (idx > 0) acc[c.slice(0, idx).trim()] = c.slice(idx + 1).trim();
+		return acc;
+	}, {});
+}
+
+/**
+ * Truncate any value to the lilstts payload limit (~1 KB per field).
+ * Exported for testing.
+ */
+export function truncate(v: unknown): string {
+	const s = typeof v === "string" ? v : typeof v === "object" ? JSON.stringify(v) : String(v);
+	return s.slice(0, 990);
+}
+
+/**
+ * Poll for a global to become available, then invoke `cb` exactly once.
+ * Bounded by `maxAttempts * intervalMs` (default ~10 s). On timeout, no-op.
+ */
+function whenReady<T>(
+	check: () => T | undefined,
+	cb: (value: T) => void,
+	{ intervalMs = 50, maxAttempts = 200 }: { intervalMs?: number; maxAttempts?: number } = {},
+): void {
+	const initial = check();
+	if (initial !== undefined) {
+		cb(initial);
+		return;
+	}
+	let attempts = 0;
+	const iv = setInterval(() => {
+		attempts++;
+		const v = check();
+		if (v !== undefined) {
+			clearInterval(iv);
+			cb(v);
+		} else if (attempts >= maxAttempts) {
+			clearInterval(iv);
+		}
+	}, intervalMs);
+}
+
+/**
+ * Wire up the analytics integration. Idempotent — only the first call has
+ * any effect.
+ *
+ * @internal exported for tests; do not call from app code.
+ */
+export function initOneDollarStats(): void {
+	if (initialized) return;
+	initialized = true;
+
+	const flags = readFlagsFromCookie();
+
+	// 1) Initial pageview + SPA nav tracking, with flag enrichment.
+	whenReady(
+		() =>
+			typeof window.stonks?.view === "function"
+				? window.stonks.view.bind(window.stonks)
+				: undefined,
+		(view) => {
+			view(flags);
+			wrapHistoryPushState(() => view(flags));
+			addEventListener("popstate", () => view(flags));
+		},
+	);
+
+	// 2) Forward DECO events to stonks.event with flag enrichment.
+	whenReady(
+		() =>
+			typeof window.DECO?.events?.subscribe === "function"
+				? window.DECO.events.subscribe.bind(window.DECO.events)
+				: undefined,
+		(subscribe) => {
+			subscribe((event: { name?: string; params?: Record<string, unknown> } | null | undefined) => {
+				if (!event || !event.name || event.name === "deco") return;
+				if (typeof window.stonks?.event !== "function") return;
+				const values: Record<string, string | boolean | number> = { ...flags };
+				for (const [k, v] of Object.entries(event.params ?? {})) {
+					if (v == null) continue;
+					values[k] = truncate(v);
+				}
+				window.stonks.event(event.name, values);
+			});
+		},
+	);
+}
+
+/**
+ * Wrap `history.pushState` to invoke `onPush` after each call. Idempotent
+ * via a marker property on the wrapper. The lilstts SDK installs its own
+ * wrapper too — with `data-autocollect="false"` its handler is a no-op,
+ * so we don't double-fire.
+ */
+function wrapHistoryPushState(onPush: () => void): void {
+	const ANY_HISTORY = history as History & { __onedollarstats_wrapped?: true };
+	if (ANY_HISTORY.__onedollarstats_wrapped) return;
+	const original = history.pushState;
+	const wrapped = function (this: History, ...args: Parameters<History["pushState"]>): void {
+		original.apply(this, args);
+		try {
+			onPush();
+		} catch (err) {
+			console.error("[OneDollarStats] pushState handler", err);
+		}
+	} as History["pushState"];
+	(wrapped as unknown as { __onedollarstats_wrapped: true }).__onedollarstats_wrapped = true;
+	history.pushState = wrapped;
+	ANY_HISTORY.__onedollarstats_wrapped = true;
+}
+
+/**
+ * @internal — reset module state for tests. NEVER call from app code.
+ */
+export function __resetForTests(): void {
+	initialized = false;
+	cachedFlags = null;
+	if (typeof history !== "undefined") {
+		const h = history as History & { __onedollarstats_wrapped?: true };
+		delete h.__onedollarstats_wrapped;
+	}
+}
+
 export default OneDollarStats;