@decocms/apps 0.28.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "0.28.1",
+  "version": "1.0.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -22,6 +22,7 @@
     "./shopify/actions/user/*": "./shopify/actions/user/*.ts",
     "./shopify/utils/*": "./shopify/utils/*.ts",
     "./vtex": "./vtex/index.ts",
+    "./vtex/commerceLoaders": "./vtex/commerceLoaders.ts",
     "./vtex/mod": "./vtex/mod.ts",
     "./vtex/client": "./vtex/client.ts",
     "./vtex/types": "./vtex/types.ts",

package/vtex/commerceLoaders.ts

@@ -0,0 +1,285 @@
+/**
+ * Standard VTEX commerce loader map factory for CMS block resolution.
+ *
+ * Wraps all VTEX inline loaders with createCachedLoader, applies universal
+ * workarounds (slug fallback, IS sort sanitization, map=productClusterIds),
+ * and registers both `.ts` and `.ts`-less aliases.
+ *
+ * Sites call `createVtexCommerceLoaders()` instead of manually wiring ~30
+ * individual loader entries. Site-specific loaders are merged via `extra`.
+ */
+
+import { createCachedLoader } from "@decocms/start/sdk/cachedLoader";
+import type { CacheProfileName } from "@decocms/start/sdk/cacheHeaders";
+import vtexProductList from "./inline-loaders/productList";
+import vtexProductListShelf from "./inline-loaders/productListShelf";
+import vtexProductDetailsPage from "./inline-loaders/productDetailsPage";
+import vtexProductListingPage from "./inline-loaders/productListingPage";
+import vtexSuggestions from "./inline-loaders/suggestions";
+import vtexRelatedProducts from "./inline-loaders/relatedProducts";
+import vtexWorkflowProducts from "./inline-loaders/workflowProducts";
+import { getCategoryTree } from "./loaders/catalog";
+import { VALID_IS_SORTS } from "./utils/intelligentSearch";
+
+export type CommerceLoaderFn = (props: any) => Promise<any>;
+
+export interface VtexCommerceLoadersOptions {
+	/** Override cache profiles per loader type. */
+	cacheProfiles?: {
+		listing?: CacheProfileName;
+		product?: CacheProfileName;
+		search?: CacheProfileName;
+		static?: CacheProfileName;
+	};
+	/** Additional loaders to merge into the map (site-specific). */
+	extra?: Record<string, CommerceLoaderFn>;
+}
+
+/**
+ * Bridge __pagePath → slug when CMS doesn't set slug explicitly.
+ * VTEX PDP pages receive __pagePath (e.g. "/produto-slug/p") but the
+ * inline loader only reads the `slug` field.
+ */
+function pdpWithSlugFallback(props: any): Promise<any> {
+	if ((!props.slug || props.slug.length === 0) && props.__pagePath) {
+		props = { ...props, slug: props.__pagePath };
+	}
+	return vtexProductDetailsPage(props);
+}
+
+/**
+ * Extract collection name from PLP product data.
+ * Products carry cluster info in additionalProperty with name="cluster".
+ */
+function extractCollectionName(
+	result: any,
+	collectionId: string,
+): string | null {
+	if (!result?.products?.length) return null;
+	for (const product of result.products) {
+		const props =
+			product.additionalProperty ||
+			product.isVariantOf?.additionalProperty ||
+			[];
+		for (const prop of props) {
+			if (prop.name === "cluster" && prop.propertyID === collectionId) {
+				return prop.value || null;
+			}
+		}
+	}
+	return null;
+}
+
+/**
+ * Returns the standard VTEX commerce loader map for CMS resolution.
+ *
+ * Includes all Intelligent Search, legacy, category tree, and navbar loaders
+ * with SWR caching. Also registers `.ts`-less aliases for invoke compatibility.
+ *
+ * @example
+ * ```ts
+ * import { createVtexCommerceLoaders } from "@decocms/apps/vtex/commerceLoaders";
+ *
+ * const COMMERCE_LOADERS = {
+ *   ...createVtexCommerceLoaders(),
+ *   // site-specific only:
+ *   "site/loaders/myCustomLoader": async (props) => { ... },
+ * };
+ * registerCommerceLoaders(COMMERCE_LOADERS);
+ * ```
+ */
+export function createVtexCommerceLoaders(
+	options?: VtexCommerceLoadersOptions,
+): Record<string, CommerceLoaderFn> {
+	const profiles = {
+		listing: options?.cacheProfiles?.listing ?? "listing",
+		product: options?.cacheProfiles?.product ?? "product",
+		search: options?.cacheProfiles?.search ?? "search",
+		static: options?.cacheProfiles?.static ?? "static",
+	};
+
+	const cachedProductList = createCachedLoader(
+		"vtex/productList",
+		vtexProductList,
+		profiles.listing,
+	);
+	const cachedProductListShelf = createCachedLoader(
+		"vtex/productListShelf",
+		vtexProductListShelf,
+		profiles.listing,
+	);
+	const cachedPDP = createCachedLoader(
+		"vtex/productDetailsPage",
+		pdpWithSlugFallback,
+		profiles.product,
+	);
+	const _cachedPLP = createCachedLoader(
+		"vtex/productListingPage",
+		vtexProductListingPage,
+		profiles.listing,
+	);
+	const cachedSuggestions = createCachedLoader(
+		"vtex/suggestions",
+		vtexSuggestions,
+		profiles.search,
+	);
+	const cachedRelatedProducts = createCachedLoader(
+		"vtex/relatedProducts",
+		vtexRelatedProducts,
+		profiles.product,
+	);
+	const cachedWorkflowProducts = createCachedLoader(
+		"vtex/workflowProducts",
+		vtexWorkflowProducts,
+		profiles.listing,
+	);
+
+	/**
+	 * PLP wrapper: handles `map=productClusterIds` legacy URLs and sanitizes
+	 * IS sort parameters that would cause VTEX API 400 errors.
+	 */
+	const cachedPLP: CommerceLoaderFn = async (props) => {
+		if (props.__pageUrl && !props.selectedFacets?.length) {
+			try {
+				const pageUrl = new URL(props.__pageUrl, "https://localhost");
+				const mapParam = pageUrl.searchParams.get("map");
+				if (mapParam && props.__pagePath) {
+					const segments = props.__pagePath.split("/").filter(Boolean);
+					const mapValues = mapParam.split(",");
+					const facets: Array<{ key: string; value: string }> = [];
+					for (
+						let i = 0;
+						i < Math.min(segments.length, mapValues.length);
+						i++
+					) {
+						const key = mapValues[i].trim();
+						const value = decodeURIComponent(segments[i]);
+						if (key && value) facets.push({ key, value });
+					}
+					if (facets.length) {
+						const rawSort = pageUrl.searchParams.get("sort") ?? "";
+						const cleanSort = VALID_IS_SORTS.has(rawSort) ? rawSort : "";
+
+						if (rawSort !== cleanSort) {
+							if (cleanSort) {
+								pageUrl.searchParams.set("sort", cleanSort);
+							} else {
+								pageUrl.searchParams.delete("sort");
+							}
+						}
+
+						const result = await _cachedPLP({
+							...props,
+							selectedFacets: facets,
+							sort: cleanSort || undefined,
+							__pageUrl: pageUrl.toString(),
+						});
+
+						const clusterFacet = facets.find(
+							(f) => f.key === "productClusterIds",
+						);
+						if (result && clusterFacet) {
+							const collectionName = extractCollectionName(
+								result,
+								clusterFacet.value,
+							);
+							if (collectionName) {
+								result.breadcrumb = {
+									"@type": "BreadcrumbList",
+									itemListElement: [
+										{
+											"@type": "ListItem",
+											name: collectionName,
+											item: props.__pagePath || "/",
+											position: 1,
+										},
+									],
+									numberOfItems: 1,
+								};
+								result.seo = { ...result.seo, title: collectionName };
+							}
+						}
+						return result;
+					}
+				}
+			} catch (e) {
+				console.error("[PLP] Error parsing map param:", e);
+			}
+		}
+		return _cachedPLP(props);
+	};
+
+	/**
+	 * Related products wrapper: extracts slug from __pagePath when the CMS
+	 * requestToParam stub returns null (standard in TanStack sites).
+	 */
+	const relatedWithSlugFallback: CommerceLoaderFn = (props) => {
+		if (!props.slug && props.__pagePath) {
+			const path = props.__pagePath.replace(/\/p$/, "").replace(/^\//, "");
+			props = { ...props, slug: path };
+		}
+		return cachedRelatedProducts(props);
+	};
+
+	const loaders: Record<string, CommerceLoaderFn> = {
+		// Intelligent Search loaders
+		"vtex/loaders/intelligentSearch/productListingPage.ts": cachedPLP,
+		"vtex/loaders/intelligentSearch/productList.ts": cachedProductListShelf,
+		"vtex/loaders/intelligentSearch/productDetailsPage.ts": cachedPDP,
+		"vtex/loaders/intelligentSearch/suggestions.ts": cachedSuggestions,
+		// Legacy loaders (map to same cached functions)
+		"vtex/loaders/legacy/productDetailsPage.ts": cachedPDP,
+		"vtex/loaders/legacy/productList.ts": cachedProductListShelf,
+		"vtex/loaders/legacy/relatedProductsLoader.ts": relatedWithSlugFallback,
+		// Workflow
+		"vtex/loaders/workflow/products.ts": cachedWorkflowProducts,
+		// Top-level aliases (used by some CMS block configs)
+		"vtex/loaders/ProductList.ts": cachedProductListShelf,
+		"vtex/loaders/ProductDetailsPage.ts": cachedPDP,
+		"vtex/loaders/ProductListingPage.ts": cachedPLP,
+		// Category tree
+		"vtex/loaders/categories/tree": (props: any) =>
+			getCategoryTree(props?.categoryLevels ?? 3),
+		// Commerce passthrough loaders
+		"commerce/loaders/navbar.ts": async (props: any) => props.items ?? [],
+		"commerce/loaders/product/extensions/detailsPage.ts": async (
+			props: any,
+		) => {
+			const data = props.data;
+			if (data?.product) return data;
+			return cachedPDP({ __pagePath: props.__pagePath });
+		},
+		// requestToParam stub — unresolvable in TanStack, pdpWithSlugFallback bridges it
+		"website/functions/requestToParam.ts": async () => null,
+	};
+
+	// Register .ts-less aliases for invoke compatibility
+	const withAliases: Record<string, CommerceLoaderFn> = { ...loaders };
+	for (const key of Object.keys(loaders)) {
+		if (key.endsWith(".ts")) {
+			withAliases[key.slice(0, -3)] = loaders[key];
+		}
+	}
+
+	if (options?.extra) {
+		Object.assign(withAliases, options.extra);
+	}
+
+	return withAliases;
+}
+
+/**
+ * Exposes the cached PDP loader for site-specific section loaders that need
+ * to call it directly (e.g. ProductDescription fallback).
+ *
+ * Returns a new instance each call — sites should cache the reference.
+ */
+export function createCachedPDPLoader(
+	profile: CacheProfileName = "product",
+): CommerceLoaderFn {
+	return createCachedLoader(
+		"vtex/productDetailsPage",
+		pdpWithSlugFallback,
+		profile,
+	);
+}

package/vtex/loaders/legacy.ts

@@ -622,3 +622,14 @@ export async function legacySuggestions(
 
 	return { searches, products };
 }
+
+// ---------------------------------------------------------------------------
+// Short aliases — sites use invoke.vtex.loaders.legacy.productDetailsPage()
+// ---------------------------------------------------------------------------
+
+export {
+	legacyProductDetailsPage as productDetailsPage,
+	legacyProductList as productList,
+	legacyProductListingPage as productListingPage,
+	legacySuggestions as suggestions,
+};

package/vtex/utils/accountLoaders.ts

@@ -0,0 +1,202 @@
+/**
+ * Pre-built section loaders for VTEX account pages.
+ *
+ * Every VTEX site with account pages repeats the same pattern:
+ * 1. Extract VTEX cookies from request
+ * 2. Call the VTEX user/profile/address/payment API
+ * 3. Return enriched props with { device, logged, ...data }
+ * 4. Catch errors gracefully (return logged: false)
+ *
+ * These factories encapsulate that boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { vtexAccountLoaders } from "@decocms/apps/vtex/utils/accountLoaders";
+ *
+ * registerSectionLoaders({
+ *   "site/sections/Account/PersonalData.tsx": vtexAccountLoaders.personalData(),
+ *   "site/sections/Account/MyOrders.tsx":     vtexAccountLoaders.orders(),
+ *   "site/sections/Account/Cards.tsx":        vtexAccountLoaders.cards(),
+ *   "site/sections/Account/Addresses.tsx":    vtexAccountLoaders.addresses(),
+ *   "site/sections/Account/Auth.tsx":         vtexAccountLoaders.authentication(),
+ *   "site/sections/Account/Other.tsx":        vtexAccountLoaders.loggedIn(),
+ * });
+ * ```
+ */
+import { getVtexCookies } from "./cookies";
+import { getUser } from "../loaders/user";
+import { getCurrentProfile, type Profile } from "../loaders/profile";
+import { getUserAddresses, type VtexAddress } from "../loaders/address";
+import { getUserPayments, type Payment } from "../loaders/payment";
+import { detectDevice } from "@decocms/start/sdk/useDevice";
+
+type Device = "mobile" | "tablet" | "desktop";
+
+type SectionLoaderFn = (
+	props: Record<string, unknown>,
+	req: Request,
+) => Promise<Record<string, unknown>> | Record<string, unknown>;
+
+function getDevice(req: Request): Device {
+	return detectDevice(req.headers.get("user-agent") ?? "");
+}
+
+// ---------------------------------------------------------------------------
+// personalData — fetches full VTEX profile for personal data sections
+// ---------------------------------------------------------------------------
+
+export interface PersonalDataOptions {
+	/** Extra custom profile fields to request beyond the standard set. */
+	extraProfileFields?: string[];
+
+	/**
+	 * Transform the raw VTEX Profile into the shape your component expects.
+	 * When omitted, the raw Profile object is returned as `profile`.
+	 *
+	 * @example
+	 * ```ts
+	 * vtexAccountLoaders.personalData({
+	 *   mapProfile: (p) => ({
+	 *     "@id": p.userId ?? p.id,
+	 *     email: p.email,
+	 *     givenName: p.firstName ?? null,
+	 *     familyName: p.lastName ?? null,
+	 *     taxID: p.document,
+	 *   }),
+	 * })
+	 * ```
+	 */
+	mapProfile?: (profile: Profile) => Record<string, unknown>;
+}
+
+function personalData(options?: PersonalDataOptions): SectionLoaderFn {
+	const { extraProfileFields, mapProfile } = options ?? {};
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const profile = await getCurrentProfile(cookie, extraProfileFields);
+			const data = mapProfile ? mapProfile(profile) : profile;
+			return {
+				...props,
+				device: getDevice(req),
+				logged: !!profile,
+				loading: false,
+				userData: data,
+			};
+		} catch (error) {
+			console.error("[accountLoaders.personalData]", error);
+			return { ...props, device: getDevice(req), logged: false, loading: false, userData: null };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// orders — checks login status for order listing sections
+// ---------------------------------------------------------------------------
+
+function orders(): SectionLoaderFn {
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const userData = await getUser(cookie);
+			return { ...props, device: getDevice(req), logged: !!userData };
+		} catch {
+			return { ...props, device: getDevice(req), logged: false };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// cards — fetches saved payment tokens for card management sections
+// ---------------------------------------------------------------------------
+
+function cards(): SectionLoaderFn {
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const user = await getUser(cookie);
+			const logged = !!user;
+			let payments: Payment[] = [];
+			if (logged) {
+				try {
+					payments = (await getUserPayments(cookie)) ?? [];
+				} catch {
+					payments = [];
+				}
+			}
+			return { ...props, logged, payments };
+		} catch {
+			return { ...props, logged: false, payments: [] };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// addresses — fetches address list for address management sections
+// ---------------------------------------------------------------------------
+
+function addresses(): SectionLoaderFn {
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const userData = await getUser(cookie);
+			const logged = !!userData;
+			let userAddressData: VtexAddress[] | null = null;
+			if (logged) {
+				try {
+					userAddressData = await getUserAddresses(cookie);
+				} catch {
+					userAddressData = null;
+				}
+			}
+			return { ...props, device: getDevice(req), logged, userAddressData };
+		} catch {
+			return { ...props, device: getDevice(req), logged: false, userAddressData: null };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// authentication — checks login + returns user data for auth pages
+// ---------------------------------------------------------------------------
+
+function authentication(): SectionLoaderFn {
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const userData = await getUser(cookie);
+			return { ...props, device: getDevice(req), logged: !!userData, userData };
+		} catch {
+			return { ...props, device: getDevice(req), logged: false, userData: null };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// loggedIn — generic "is the user logged in?" loader
+// ---------------------------------------------------------------------------
+
+function loggedIn(): SectionLoaderFn {
+	return async (props, req) => {
+		const cookie = getVtexCookies(req);
+		try {
+			const userData = await getUser(cookie);
+			return { ...props, device: getDevice(req), logged: !!userData };
+		} catch {
+			return { ...props, device: getDevice(req), logged: false };
+		}
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const vtexAccountLoaders = {
+	personalData,
+	orders,
+	cards,
+	addresses,
+	authentication,
+	loggedIn,
+} as const;

package/vtex/utils/cookies.ts

@@ -20,13 +20,22 @@ function parseSingleSetCookie(raw: string): Cookie | null {
 		value: nameValue.slice(eqIdx + 1),
 	};
 	for (const attr of attrs) {
-		const [k, v] = attr.split("=").map((s) => s.trim());
+		const eqi = attr.indexOf("=");
+		const k = (eqi >= 0 ? attr.slice(0, eqi) : attr).trim();
+		const v = eqi >= 0 ? attr.slice(eqi + 1).trim() : "";
 		const lower = k.toLowerCase();
 		if (lower === "domain") cookie.domain = v;
 		else if (lower === "path") cookie.path = v;
 		else if (lower === "secure") cookie.secure = true;
 		else if (lower === "httponly") cookie.httpOnly = true;
 		else if (lower === "samesite") cookie.sameSite = v as Cookie["sameSite"];
+		else if (lower === "max-age") {
+			const n = Number(v);
+			if (!Number.isNaN(n)) cookie.maxAge = n;
+		} else if (lower === "expires") {
+			const d = new Date(v);
+			if (!Number.isNaN(d.getTime())) cookie.expires = d;
+		}
 	}
 	return cookie;
 }
@@ -111,3 +120,55 @@ export const proxySetCookie = (from: Headers, to: Headers, toDomain?: URL | stri
 
 export const CHECKOUT_DATA_ACCESS_COOKIE = "CheckoutDataAccess";
 export const VTEX_CHKO_AUTH = "Vtex_CHKO_Auth";
+
+/**
+ * Cookie name prefixes that are VTEX-relevant.
+ * Used by getVtexCookies() to filter request cookies before forwarding
+ * to VTEX APIs — avoids undici non-ASCII warnings from other cookies.
+ */
+export const VTEX_COOKIE_PREFIXES = [
+	"VtexIdclientAutCookie",
+	"checkout.vtex",
+	"CheckoutOrderFormOwnership",
+	"vtex_is_",
+];
+
+/**
+ * Filter a request's cookies to only VTEX-relevant ones.
+ * Prevents undici non-ASCII header warnings when forwarding cookies to VTEX APIs.
+ */
+export function getVtexCookies(request: Request): string {
+	const raw = request.headers.get("cookie") ?? "";
+	return raw
+		.split(";")
+		.map((c) => c.trim())
+		.filter((c) => VTEX_COOKIE_PREFIXES.some((p) => c.startsWith(p)))
+		.join("; ");
+}
+
+/**
+ * Ensure the unsuffixed VtexIdclientAutCookie is present alongside the
+ * account-suffixed variant (e.g. VtexIdclientAutCookie_myaccount).
+ *
+ * VTEX GraphQL requires both the suffixed AND unsuffixed cookie for
+ * authenticated mutations. The browser only stores the suffixed variant,
+ * so server-side code must synthesize the unsuffixed one.
+ */
+export function ensureUnsuffixedAuthCookie(cookieStr: string): string {
+	if (!cookieStr) return cookieStr;
+	const cookies = cookieStr.split(";").map((c) => c.trim());
+	let hasUnsuffixed = false;
+	let suffixedToken: string | null = null;
+	for (const c of cookies) {
+		const [name, ...rest] = c.split("=");
+		if (name === "VtexIdclientAutCookie") {
+			hasUnsuffixed = true;
+		} else if (name?.startsWith("VtexIdclientAutCookie_") && !suffixedToken) {
+			suffixedToken = rest.join("=");
+		}
+	}
+	if (!hasUnsuffixed && suffixedToken) {
+		return `VtexIdclientAutCookie=${suffixedToken}; ${cookieStr}`;
+	}
+	return cookieStr;
+}

package/vtex/utils/index.ts

@@ -1,3 +1,5 @@
+export { vtexAccountLoaders } from "./accountLoaders";
+export type { PersonalDataOptions } from "./accountLoaders";
 export * from "./batch";
 export * from "./cookies";
 export * from "./enrichment";

package/vtex/utils/intelligentSearch.ts

@@ -44,6 +44,27 @@ export const withDefaultParams = ({
 
 export const isFilterParam = (keyFilter: string): boolean => keyFilter.startsWith("filter.");
 
+/**
+ * Valid VTEX Intelligent Search sort values.
+ * Anything else (e.g. "orders:desc)" with a trailing paren from legacy URLs)
+ * causes IS API to return 400.
+ */
+export const VALID_IS_SORTS = new Set([
+	"",
+	"orders:desc",
+	"price:asc",
+	"price:desc",
+	"name:asc",
+	"name:desc",
+	"release:desc",
+	"discount:desc",
+]);
+
+/** Sanitize an IS sort parameter — returns empty string for invalid values. */
+export function sanitizeISSort(sort: string): string {
+	return VALID_IS_SORTS.has(sort) ? sort : "";
+}
+
 const segmentsFromTerm = (term: string) => term.split("/").filter(Boolean);
 
 const segmentsFromSearchParams = (url: string) => {

package/vtex/utils/proxy.ts

@@ -4,6 +4,12 @@
  * Proxies storefront requests for /checkout, /account, /api, /files, /arquivos
  * to the VTEX origin. Essential for checkout and My Account pages to work.
  *
+ * Two flavors:
+ * - `proxyToVtex()` — simple single-origin proxy (vtexcommercestable)
+ * - `createVtexCheckoutProxy()` — production-grade dual-origin proxy with
+ *   proper cookie attribute preservation, non-ASCII sanitization, and
+ *   configurable origin routing (checkout UI vs API paths)
+ *
  * Designed to be used with TanStack Start API routes or Cloudflare Worker
  * fetch handlers.
  */
@@ -194,3 +200,244 @@ export async function proxyToVtex(request: Request, options?: VtexProxyOptions):
 		headers: responseHeaders,
 	});
 }
+
+// ---------------------------------------------------------------------------
+// Production-grade checkout proxy factory
+// ---------------------------------------------------------------------------
+
+export interface VtexCheckoutProxyConfig {
+	/** VTEX account name (e.g. "casaevideonewio"). */
+	account: string;
+
+	/**
+	 * Store's public checkout domain (e.g. "secure.casaevideo.com.br").
+	 * Checkout UI, /files/, and /_v/private/graphql are routed here.
+	 */
+	checkoutOrigin: string;
+
+	/**
+	 * VTEX commerce-stable origin for API calls.
+	 * @default `https://{account}.vtexcommercestable.com.br`
+	 */
+	apiOrigin?: string;
+
+	/**
+	 * myvtex origin — used for redirect rewriting.
+	 * @default `https://{account}.myvtex.com`
+	 */
+	myvtexOrigin?: string;
+
+	/**
+	 * VTEX TLD — most accounts use `.com.br`, but some use `.com`.
+	 * @default "com.br"
+	 */
+	domain?: string;
+
+	/**
+	 * Extra paths on which to force-expire cookies.
+	 * Useful for logout: VTEX sends Max-Age=0 for auth cookies, but the
+	 * checkout orderForm cookie sometimes survives. This appends explicit
+	 * Set-Cookie: name=; Max-Age=0 entries.
+	 */
+	expireCookiesOnPaths?: Array<{
+		pathPrefix: string;
+		cookies: string[];
+	}>;
+
+	/**
+	 * Optional HTML transform for checkout pages.
+	 * Receives the full HTML string and should return the modified version.
+	 */
+	htmlTransform?: (html: string) => string;
+}
+
+const CF_INTERNAL_HEADERS = new Set([
+	"cf-connecting-ip",
+	"cf-ipcountry",
+	"cf-ray",
+	"cf-visitor",
+	"cf-ew-via",
+	"cdn-loop",
+]);
+
+const CHECKOUT_SKIP_HEADERS = new Set([
+	...HOP_BY_HOP_HEADERS,
+	"set-cookie",
+	...CF_INTERNAL_HEADERS,
+]);
+
+const toAscii = (v: string) => v.replace(/[^\x20-\x7E]/g, "");
+
+function filterHeadersStrict(headers: Headers): Headers {
+	const filtered = new Headers();
+	headers.forEach((value, key) => {
+		if (CHECKOUT_SKIP_HEADERS.has(key.toLowerCase())) return;
+		try {
+			filtered.set(key, toAscii(value));
+		} catch {
+			// skip headers that still fail after sanitization
+		}
+	});
+	return filtered;
+}
+
+/**
+ * Rewrite Set-Cookie headers: only change the Domain attribute.
+ * Unlike `proxySetCookie`, this preserves ALL attributes (Max-Age,
+ * Expires, SameSite, etc.) which is critical for logout.
+ */
+function rewriteSetCookieDomain(
+	from: Headers,
+	to: Headers,
+	toHostname: string,
+) {
+	const raw: string[] =
+		typeof from.getSetCookie === "function"
+			? from.getSetCookie()
+			: (from.get("set-cookie") ?? "")
+					.split(/,(?=[^ ]+=)/)
+					.filter(Boolean);
+
+	for (const cookie of raw) {
+		const rewritten = cookie.replace(/Domain=[^;]*/i, `Domain=${toHostname}`);
+		to.append("Set-Cookie", rewritten);
+	}
+}
+
+/**
+ * Creates a production-grade VTEX checkout proxy handler.
+ *
+ * Routes checkout UI pages to the store's public domain and API calls
+ * to vtexcommercestable. Properly rewrites Set-Cookie domains (preserving
+ * Max-Age/Expires), sanitizes non-ASCII headers, filters hop-by-hop and
+ * CF-internal headers, and rewrites Location redirects.
+ *
+ * Returns a function compatible with `createDecoWorkerEntry`'s `proxyHandler`.
+ *
+ * @example
+ * ```ts
+ * const vtexProxy = createVtexCheckoutProxy({
+ *   account: "casaevideonewio",
+ *   checkoutOrigin: "secure.casaevideo.com.br",
+ *   expireCookiesOnPaths: [
+ *     { pathPrefix: "/api/vtexid/pub/logout", cookies: ["checkout.vtex.com"] },
+ *   ],
+ *   htmlTransform: (html) =>
+ *     html.replace("</head>", "<style>.body{min-height:100vh}</style></head>"),
+ * });
+ *
+ * createDecoWorkerEntry(serverEntry, {
+ *   proxyHandler: async (request, url) => {
+ *     if (url.pathname === "/login") return null;
+ *     if (!shouldProxyToVtex(url.pathname)) return null;
+ *     return vtexProxy(request, url);
+ *   },
+ * });
+ * ```
+ */
+export function createVtexCheckoutProxy(
+	config: VtexCheckoutProxyConfig,
+): (request: Request, url: URL) => Promise<Response> {
+	const domain = config.domain ?? "com.br";
+	const checkoutOrigin = config.checkoutOrigin.startsWith("https://")
+		? config.checkoutOrigin
+		: `https://${config.checkoutOrigin}`;
+	const apiOrigin =
+		config.apiOrigin ??
+		`https://${config.account}.vtexcommercestable.${domain}`;
+	const myvtexOrigin =
+		config.myvtexOrigin ?? `https://${config.account}.myvtex.com`;
+
+	function getOrigin(pathname: string, method: string): string {
+		if (
+			pathname.startsWith("/checkout") ||
+			pathname.startsWith("/account") ||
+			pathname.startsWith("/_secure/account") ||
+			pathname.startsWith("/files/") ||
+			pathname.startsWith("/_v/private/graphql")
+		) {
+			return checkoutOrigin;
+		}
+		if (method !== "GET" && method !== "HEAD" && pathname.startsWith("/_v/")) {
+			return checkoutOrigin;
+		}
+		return apiOrigin;
+	}
+
+	return async (request: Request, url: URL): Promise<Response> => {
+		const origin = getOrigin(url.pathname, request.method);
+		const originUrl = new URL(`${origin}${url.pathname}${url.search}`);
+		const fwd = filterHeadersStrict(new Headers(request.headers));
+
+		fwd.set("Host", originUrl.hostname);
+		fwd.set("X-Forwarded-Host", url.host);
+		fwd.set("X-Forwarded-Proto", "https");
+		fwd.set("origin", request.headers.get("origin") ?? url.origin);
+
+		const isCheckoutUI =
+			url.pathname.startsWith("/checkout") ||
+			url.pathname.startsWith("/account");
+		const isLogout = url.pathname.startsWith("/api/vtexid/pub/logout");
+
+		const init: RequestInit = {
+			method: request.method,
+			headers: fwd,
+			redirect: isCheckoutUI || isLogout ? "manual" : "follow",
+		};
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			init.body = request.body;
+			// @ts-expect-error -- needed for streaming body in Workers
+			init.duplex = "half";
+		}
+
+		const originRes = await fetch(originUrl.toString(), init);
+		const resHeaders = filterHeadersStrict(new Headers(originRes.headers));
+		rewriteSetCookieDomain(originRes.headers, resHeaders, url.hostname);
+
+		// Force-expire cookies on configured paths
+		if (config.expireCookiesOnPaths) {
+			for (const rule of config.expireCookiesOnPaths) {
+				if (url.pathname.startsWith(rule.pathPrefix)) {
+					for (const name of rule.cookies) {
+						resHeaders.append(
+							"Set-Cookie",
+							`${name}=; Path=/; Max-Age=0; Domain=${url.hostname}`,
+						);
+					}
+				}
+			}
+		}
+
+		// Rewrite redirect Location headers from VTEX domains to storefront
+		if (originRes.status >= 300 && originRes.status < 400) {
+			const loc = originRes.headers.get("location");
+			if (loc) {
+				resHeaders.set(
+					"location",
+					loc
+						.replace(checkoutOrigin, url.origin)
+						.replace(apiOrigin, url.origin)
+						.replace(myvtexOrigin, url.origin),
+				);
+			}
+		}
+
+		// HTML transform for checkout pages
+		const ct = originRes.headers.get("content-type") ?? "";
+		if (config.htmlTransform && ct.includes("text/html")) {
+			const html = await originRes.text();
+			const patched = config.htmlTransform(html);
+			return new Response(patched, {
+				status: originRes.status,
+				statusText: originRes.statusText,
+				headers: resHeaders,
+			});
+		}
+
+		return new Response(originRes.body, {
+			status: originRes.status,
+			statusText: originRes.statusText,
+			headers: resHeaders,
+		});
+	};
+}

package/vtex/utils/vtexId.ts

@@ -97,4 +97,42 @@ export function buildAuthCookieHeader(authCookie: string, account: string): stri
 	return `${VTEX_AUTH_COOKIE}=${authCookie}; ${VTEX_AUTH_COOKIE}_${account}=${authCookie}`;
 }
 
+export interface CookiePayload {
+	sub?: string;
+	account?: string;
+	audience?: string;
+	sess?: string;
+	exp?: number;
+	userId?: string;
+}
+
+/**
+ * Parse VTEX auth cookies from request headers.
+ *
+ * Returns the serialized cookie string (for forwarding) and the decoded
+ * JWT payload. Compatible with the legacy deco-cx/apps parseCookie API.
+ */
+export function parseCookie(
+	headers: Headers,
+	account: string,
+): { cookie: string; payload: CookiePayload | undefined } {
+	const cookieHeader = headers.get("cookie") ?? "";
+
+	const base = extractVtexAuthCookie(cookieHeader);
+	const suffixedRe = new RegExp(`(?:^|;\\s*)${VTEX_AUTH_COOKIE}_${account}=([^;]+)`);
+	const suffixedMatch = cookieHeader.match(suffixedRe);
+	const suffixed = suffixedMatch?.[1] ?? null;
+
+	const token = base ?? suffixed;
+	const payload = token
+		? ((decodeJwtPayload(token) as CookiePayload | null) ?? undefined)
+		: undefined;
+
+	const parts: string[] = [];
+	if (base) parts.push(`${VTEX_AUTH_COOKIE}=${base}`);
+	if (suffixed) parts.push(`${VTEX_AUTH_COOKIE}_${account}=${suffixed}`);
+
+	return { cookie: parts.join("; "), payload };
+}
+
 export { VTEX_AUTH_COOKIE };