@decocms/apps 0.29.0 → 1.1.0

package/commerce/sdk/analytics.ts

@@ -1,24 +1,165 @@
-import type { AnalyticsEvent } from "../types/commerce";
-
-declare global {
-	interface Window {
-		DECO: { events: { dispatch: (event: any) => void } };
-		DECO_SITES_STD: {
-			sendAnalyticsEvent: (args: AnalyticsEvent) => void;
-		};
-	}
+/**
+ * Analytics mappers — convert schema.org Product to GA4 AnalyticsItem.
+ *
+ * These are the generic, platform-independent mappers. Sites can wrap them
+ * to add custom fields (sellerP, etc.) via the `extend` option.
+ */
+import type { BreadcrumbList, Product } from "../types";
+
+export interface AnalyticsItem {
+  item_id?: string;
+  item_name?: string;
+  affiliation?: string;
+  coupon?: string;
+  discount?: number;
+  index?: number;
+  item_group_id?: string;
+  item_url?: string;
+  item_brand?: string;
+  item_category?: string;
+  item_category2?: string;
+  item_category3?: string;
+  item_category4?: string;
+  item_category5?: string;
+  item_list_id?: string;
+  item_list_name?: string;
+  item_variant?: string;
+  location_id?: string;
+  price?: number;
+  quantity: number;
+  [key: string]: unknown;
+}
+
+export function mapCategoriesToAnalyticsCategories(
+  categories: string[],
+): Record<string, string> {
+  return categories.slice(0, 5).reduce(
+    (result, category, index) => {
+      result[`item_category${index === 0 ? "" : index + 1}`] = category;
+      return result;
+    },
+    {} as Record<string, string>,
+  );
+}
+
+export function mapProductCategoryToAnalyticsCategories(category: string): Record<string, string> {
+  return category.split(">").reduce(
+    (result, cat, index) => {
+      result[`item_category${index === 0 ? "" : index}`] = cat.trim();
+      return result;
+    },
+    {} as Record<string, string>,
+  );
+}
+
+export interface MapProductToAnalyticsItemOptions {
+  product: Product;
+  breadcrumbList?: BreadcrumbList;
+  price?: number;
+  lowPrice?: number;
+  listPrice?: number;
+  index?: number;
+  quantity?: number;
+  coupon?: string;
+  /** Extend the result with custom fields (e.g., sellerP, sellerName) */
+  extend?: (product: Product, base: AnalyticsItem) => Record<string, unknown>;
+}
+
+export function mapProductToAnalyticsItem(opts: MapProductToAnalyticsItemOptions): AnalyticsItem {
+  const {
+    product,
+    breadcrumbList,
+    price,
+    lowPrice,
+    listPrice,
+    index = 0,
+    quantity = 1,
+    coupon = "",
+    extend,
+  } = opts;
+
+  const { name, productID, inProductGroupWithID, isVariantOf, url, sku } = product;
+
+  const categories = breadcrumbList?.itemListElement
+    ? mapCategoriesToAnalyticsCategories(
+        breadcrumbList.itemListElement
+          .map(({ name: n }) => n ?? "")
+          .filter(Boolean),
+      )
+    : mapProductCategoryToAnalyticsCategories(product.category ?? "");
+
+  const base: AnalyticsItem = {
+    item_id: productID,
+    item_group_id: inProductGroupWithID,
+    quantity,
+    coupon,
+    price: lowPrice,
+    index,
+    item_variant: sku,
+    discount: Number((price && listPrice ? listPrice - price : 0).toFixed(2)),
+    item_name: isVariantOf?.name ?? name ?? "",
+    item_brand: product.brand?.name ?? "",
+    item_url: url,
+    ...categories,
+  };
+
+  if (extend) {
+    return { ...base, ...extend(product, base) };
+  }
+
+  return base;
+}
+
+export interface MapProductToAnalyticsItemListOptions {
+  product: Product;
+  breadcrumbList?: BreadcrumbList;
+  price?: number;
+  listPrice?: number;
+  index?: number;
+  quantity?: number;
+  coupon?: string;
 }
 
-export const sendEvent = <E extends AnalyticsEvent>(event: E) => {
-	if (typeof globalThis.window?.DECO?.events?.dispatch === "function") {
-		globalThis.window.DECO.events.dispatch(event);
-		return;
-	}
+export function mapProductToAnalyticsItemList(opts: MapProductToAnalyticsItemListOptions): AnalyticsItem {
+  const {
+    product,
+    breadcrumbList,
+    price,
+    listPrice,
+    index = 0,
+    quantity = 1,
+    coupon = "",
+  } = opts;
+
+  const { name, productID, inProductGroupWithID, isVariantOf, url } = product;
+
+  const categories = breadcrumbList?.itemListElement
+    ? mapCategoriesToAnalyticsCategories(
+        breadcrumbList.itemListElement
+          .map(({ name: n }) => n ?? "")
+          .filter(Boolean),
+      )
+    : mapProductCategoryToAnalyticsCategories(product.category ?? "");
 
-	if (typeof globalThis.window?.DECO_SITES_STD?.sendAnalyticsEvent === "function") {
-		globalThis.window.DECO_SITES_STD.sendAnalyticsEvent(event);
-		return;
-	}
+  const finalPrice = typeof price === "number" ? price : 0;
+  const discount =
+    typeof listPrice === "number" && typeof price === "number"
+      ? Math.max(0, listPrice - price)
+      : 0;
 
-	console.info("[analytics] No event dispatcher found. Event not sent:", event.name);
-};
+  const itemId = inProductGroupWithID ?? isVariantOf?.productGroupID ?? productID;
+
+  return {
+    item_id: itemId,
+    item_group_id: inProductGroupWithID,
+    quantity,
+    coupon,
+    price: finalPrice,
+    index,
+    discount: Number(discount.toFixed(2)),
+    item_name: isVariantOf?.name ?? name ?? "",
+    item_brand: product.brand?.name ?? "",
+    item_url: url,
+    ...categories,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "0.29.0",
+  "version": "1.1.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/actions/address.ts

@@ -209,3 +209,33 @@ export async function updateAddress(
 	);
 	return result;
 }
+
+// ---------------------------------------------------------------------------
+// Request-aware wrappers (for COMMERCE_LOADERS / invoke proxy)
+// Handle cookie extraction, postalCode sanitization, and field defaults.
+// ---------------------------------------------------------------------------
+
+import { getVtexCookies, ensureUnsuffixedAuthCookie } from "../utils/cookies";
+
+function sanitizeAddressInput(props: Record<string, any>): Record<string, any> {
+	if (props.postalCode) props.postalCode = props.postalCode.replace(/\D/g, "");
+	if (!props.addressName) props.addressName = props.receiverName || `Address ${Date.now()}`;
+	if (!props.addressType) props.addressType = "residential";
+	return props;
+}
+
+export async function createAddressFromRequest(props: Record<string, any>, request: Request): Promise<SavedAddress> {
+	const cookie = ensureUnsuffixedAuthCookie(getVtexCookies(request));
+	return createAddress(sanitizeAddressInput(props) as AddressInput, cookie);
+}
+
+export async function updateAddressFromRequest(props: Record<string, any>, request: Request): Promise<UpdateAddressResult> {
+	const cookie = ensureUnsuffixedAuthCookie(getVtexCookies(request));
+	const { addressId, ...fields } = props;
+	return updateAddress(addressId, fields, cookie);
+}
+
+export async function deleteAddressFromRequest(props: Record<string, any>, request: Request): Promise<DeleteAddressResult> {
+	const cookie = ensureUnsuffixedAuthCookie(getVtexCookies(request));
+	return deleteAddress(props.addressId, cookie);
+}

package/vtex/actions/profile.ts

@@ -117,3 +117,72 @@ export async function updateProfile(
 	);
 	return profile;
 }
+
+// ---------------------------------------------------------------------------
+// Request-aware wrappers (for COMMERCE_LOADERS / invoke proxy)
+// ---------------------------------------------------------------------------
+
+import { getVtexCookies } from "../utils/cookies";
+import { updateNewsletterOptIn } from "./newsletter";
+import { deletePaymentToken } from "./misc";
+import { getCurrentProfile } from "../loaders/profile";
+
+/**
+ * Normalize birthDate strings to ISO 8601.
+ * Handles dd/mm/yyyy (Brazilian format), yyyy-mm-dd, and full ISO.
+ */
+function normalizeBirthDate(profile: Record<string, any>): void {
+	if (!profile.birthDate || typeof profile.birthDate !== "string") return;
+	const ddmmyyyy = profile.birthDate.match(/^(\d{2})\/(\d{2})\/(\d{4})$/);
+	if (ddmmyyyy) {
+		profile.birthDate = `${ddmmyyyy[3]}-${ddmmyyyy[2]}-${ddmmyyyy[1]}T00:00:00.000Z`;
+	} else if (!profile.birthDate.includes("T")) {
+		const isoMatch = profile.birthDate.match(/(\d{4})-(\d{2})-(\d{2})/);
+		if (isoMatch) {
+			profile.birthDate = `${isoMatch[0]}T00:00:00.000Z`;
+		}
+	}
+}
+
+/**
+ * Update user profile via VTEX IO GraphQL. Handles cookie extraction,
+ * birthDate normalization, and undefined-key cleanup.
+ */
+export async function updateProfileFromRequest(props: Record<string, any>, request: Request): Promise<any> {
+	const { account } = getVtexConfig();
+	const cookie = getVtexCookies(request);
+	const profile = { ...props };
+	normalizeBirthDate(profile);
+	for (const key of Object.keys(profile)) {
+		if (profile[key] === undefined) delete profile[key];
+	}
+	const QUERY = `mutation UpdateProfile($profile: ProfileInput!) {
+		updateProfile(fields: $profile) @context(provider: "vtex.store-graphql@2.x") {
+			cacheId firstName lastName email document gender homePhone
+			businessPhone birthDate isCorporate corporateName
+			corporateDocument tradeName stateRegistration
+		}
+	}`;
+	const res = await fetch(`https://${account}.myvtex.com/_v/private/graphql/v1`, {
+		method: "POST",
+		body: JSON.stringify({ query: QUERY, variables: { profile } }),
+		headers: { "Content-Type": "application/json", cookie },
+	});
+	return res.json();
+}
+
+export async function newsletterProfileFromRequest(props: Record<string, any>, request: Request): Promise<any> {
+	const cookie = request.headers.get("cookie") ?? "";
+	return updateNewsletterOptIn(props.isNewsletterOptIn, props.email, cookie);
+}
+
+export async function deletePaymentFromRequest(props: Record<string, any>, request: Request): Promise<any> {
+	const cookie = getVtexCookies(request);
+	return deletePaymentToken(props.id, cookie);
+}
+
+export async function getPasswordLastUpdate(_props: Record<string, any>, request: Request): Promise<string | null> {
+	const cookie = getVtexCookies(request);
+	const profile = await getCurrentProfile(cookie);
+	return profile?.passwordLastUpdate ?? null;
+}

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/autocomplete.ts

@@ -0,0 +1,58 @@
+/**
+ * VTEX Intelligent Search autocomplete — suggestions + product results.
+ *
+ * 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 { pickSku, toProduct as toSchemaProduct } from "../utils/transform";
+
+export interface AutocompleteProps {
+  query: string;
+  count?: number;
+  showSponsored?: boolean;
+  placement?: string;
+  fuzzy?: string;
+}
+
+export interface AutocompleteResult {
+  searches: Array<{ term: string; count: number; attributes?: any[] }>;
+  products: any[];
+}
+
+export async function autocompleteSearch(props: AutocompleteProps): Promise<AutocompleteResult> {
+  const query = props.query || "";
+  const count = props.count ?? 4;
+  if (!query.trim()) return { searches: [], products: [] };
+
+  try {
+    const [suggestionsData, productsData] = await Promise.all([
+      vtexIS<{
+        searches: Array<{ term: string; count: number; attributes?: any[] }>;
+      }>("/autocomplete_suggestions/", { query }),
+      vtexIS<{ products: any[] }>("/product_search/", {
+        query,
+        count: String(count),
+        showSponsored: props.showSponsored !== false ? "true" : "false",
+        placement: props.placement ?? "top-search",
+        fuzzy: props.fuzzy ?? "0",
+      }),
+    ]);
+
+    const config = getVtexConfig();
+    const baseUrl = config.publicUrl
+      ? `https://${config.publicUrl}`
+      : `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+    return {
+      searches: suggestionsData.searches ?? [],
+      products: (productsData.products ?? []).slice(0, count).map((p: any) => {
+        const sku = pickSku(p);
+        return toSchemaProduct(p, sku, 0, { baseUrl, priceCurrency: "BRL" });
+      }),
+    };
+  } catch (error) {
+    console.error("[vtex] autocompleteSearch error:", error);
+    return { searches: [], products: [] };
+  }
+}

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/authHelpers.ts

@@ -0,0 +1,97 @@
+/**
+ * VTEX auth helpers — pure functions for cookie extraction, JWT parsing,
+ * Set-Cookie forwarding, and logout.
+ *
+ * These are consumed by site-level createServerFn wrappers in invoke.ts.
+ * createServerFn itself must live in site source (not node_modules) because
+ * TanStack Start's Vite plugin only transforms source files.
+ */
+import { getVtexConfig } from "../client";
+
+const DOMAIN_RE = /;\s*domain=[^;]*/gi;
+
+const VTEX_COOKIE_PREFIXES = [
+  "vtex_session=",
+  "vtex_segment=",
+  "VtexIdclientAutCookie",
+  "checkout.vtex.com",
+  "CheckoutOrderFormOwnership",
+];
+
+/**
+ * Extract VTEX-relevant cookies from a raw Cookie header string.
+ * Filters out analytics/CF cookies that can cause VTEX 503 errors.
+ */
+export function extractVtexCookiesFromHeader(raw: string): string {
+  return raw
+    .split(";")
+    .map((c) => c.trim())
+    .filter((c) => VTEX_COOKIE_PREFIXES.some((prefix) => c.startsWith(prefix)))
+    .join("; ");
+}
+
+/**
+ * Strip Domain= from Set-Cookie headers so cookies are associated
+ * with the storefront domain instead of the VTEX domain.
+ */
+export function stripCookieDomain(cookies: string[]): string[] {
+  return cookies.map((c) => c.replace(DOMAIN_RE, ""));
+}
+
+/** Standard VTEX cookies to expire on logout. */
+export const VTEX_LOGOUT_COOKIES = [
+  "checkout.vtex.com=; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Lax",
+  "CheckoutOrderFormOwnership=; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Lax",
+  "checkout.vtex.com__orderFormId=; Path=/; Max-Age=0",
+  "vtex_session=; Path=/; Max-Age=0",
+  "vtex_segment=; Path=/; Max-Age=0",
+];
+
+/**
+ * Perform VTEX logout — calls the VTEX ID logout endpoint and returns
+ * the Set-Cookie headers (with domain stripped) to expire auth cookies.
+ */
+export async function performVtexLogout(cookies: string): Promise<{ setCookies: string[] }> {
+  const config = getVtexConfig();
+  const domain = config.domain ?? "com.br";
+  const logoutUrl = `https://${config.account}.vtexcommercestable.${domain}/api/vtexid/pub/logout?scope=${config.account}&returnUrl=/`;
+
+  const res = await fetch(logoutUrl, {
+    method: "GET",
+    headers: { cookie: cookies },
+    redirect: "manual",
+  });
+
+  const upstreamCookies = res.headers.getSetCookie?.() ?? [];
+
+  return {
+    setCookies: [
+      ...stripCookieDomain(upstreamCookies),
+      ...VTEX_LOGOUT_COOKIES,
+    ],
+  };
+}
+
+/**
+ * Parse VTEX auth JWT to extract email and userId.
+ * Reads the VtexIdclientAutCookie_* cookie from a raw Cookie header.
+ */
+export function parseVtexAuthJwt(rawCookies: string): { email: string; userId: string } | null {
+  try {
+    const match = rawCookies.match(/VtexIdclientAutCookie_[^=]+=([^;]+)/);
+    if (!match) return null;
+    const token = match[1];
+    const parts = token.split(".");
+    if (parts.length < 2) return null;
+    const payload = JSON.parse(
+      Buffer.from(
+        parts[1].replace(/-/g, "+").replace(/_/g, "/"),
+        "base64",
+      ).toString("utf-8"),
+    );
+    if (!payload.sub) return null;
+    return { email: payload.sub, userId: payload.userId ?? "" };
+  } catch {
+    return null;
+  }
+}

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,
+		});
+	};
+}