@decocms/apps-vtex 7.2.0

package/src/hooks/createUseWishlist.ts

@@ -0,0 +1,242 @@
+/**
+ * Factory for the legacy invoke-based `useWishlist` hook.
+ *
+ * Mirrors the deco-cx/apps signal-based wishlist API used by migrated
+ * Fresh sites: `wishlist.addItem(productId, productGroupId)`,
+ * `removeItem(productId)`, `getItem(productId): boolean`.
+ *
+ * It is intentionally separate from the canonical `useWishlist` in
+ * `vtex/hooks/useWishlist.ts`, which is built on TanStack Query and exposes
+ * `{ items, isInWishlist, toggle, add, remove }`. Both can coexist.
+ *
+ * ## VTEX wishlist arg conventions
+ *
+ * The legacy hook's `addItem(productId, productGroupId)` argument names
+ * are misleading because they were originally derived from analytics
+ * `item_id` / `item_group_id`:
+ *
+ * - `productId` arg → analytics `item_id` → VTEX `sku` field on the wishlist
+ * - `productGroupId` arg → analytics `item_group_id` → VTEX `productId`
+ *
+ * The factory swaps them on the wire so the canonical
+ * `vtex/actions/wishlist.addItem` gets the right shape.
+ *
+ * @example
+ * ```ts
+ * // src/hooks/useWishlist.ts
+ * import { createUseWishlist } from "@decocms/apps/vtex/hooks/createUseWishlist";
+ * import { invoke } from "~/server/invoke";
+ *
+ * export const { useWishlist, resetWishlist } = createUseWishlist({ invoke });
+ * export type { WishlistItem } from "@decocms/apps/vtex/loaders/wishlist";
+ * ```
+ */
+
+import { useEffect, useState } from "react";
+import type { WishlistItem } from "../loaders/wishlist";
+
+/**
+ * Pure helper: find a wishlist entry by either the SKU id (legacy
+ * `productId` arg) or the VTEX productId. Exported for unit testability.
+ */
+export function findWishlistEntry(
+	items: readonly WishlistItem[],
+	productId: string,
+): WishlistItem | undefined {
+	return items.find((it) => it.sku === productId || it.productId === productId);
+}
+
+/**
+ * Pure helper: convert legacy `addItem(productId, productGroupId)` args
+ * into the canonical `{ productId, sku }` shape expected by
+ * `vtex/actions/wishlist.addItem`. Exported for unit testability.
+ */
+export function legacyAddArgsToCanonical(
+	legacyProductId: string,
+	legacyProductGroupId: string,
+): { productId: string; sku: string } {
+	// See arg conventions in the file header. The legacy `productId` is
+	// the SKU; the legacy `productGroupId` is the VTEX productId.
+	return {
+		productId: legacyProductGroupId,
+		sku: legacyProductId,
+	};
+}
+
+/** Minimal structural shape of the invoke proxy this hook needs. */
+export interface CreateUseWishlistInvoke {
+	vtex: {
+		loaders: {
+			wishlist: () => Promise<WishlistItem[]>;
+		};
+		actions: {
+			addToWishlist: (args: {
+				data: { productId: string; sku: string; title?: string };
+			}) => Promise<WishlistItem[]>;
+			removeFromWishlist: (args: { data: { id: string } }) => Promise<WishlistItem[]>;
+		};
+	};
+}
+
+export interface CreateUseWishlistOptions {
+	invoke: CreateUseWishlistInvoke;
+}
+
+/** Build a per-site `useWishlist` plus its companions. */
+export function createUseWishlist(opts: CreateUseWishlistOptions) {
+	const { invoke } = opts;
+
+	let _items: WishlistItem[] = [];
+	let _loading = false;
+	let _initStarted = false;
+	let _initFailed = false;
+	const _listeners = new Set<() => void>();
+
+	function notify() {
+		for (const fn of _listeners) fn();
+	}
+	function setItems(items: WishlistItem[]) {
+		_items = items;
+		notify();
+	}
+	function setLoading(v: boolean) {
+		_loading = v;
+		notify();
+	}
+
+	function getItem(productId: string): boolean {
+		return !!findWishlistEntry(_items, productId);
+	}
+
+	async function addItem(productId: string, productGroupId: string): Promise<void> {
+		setLoading(true);
+		try {
+			const updated = await invoke.vtex.actions.addToWishlist({
+				data: legacyAddArgsToCanonical(productId, productGroupId),
+			});
+			setItems(updated);
+		} catch (err) {
+			console.error("[useWishlist] addItem failed:", err);
+			throw err;
+		} finally {
+			setLoading(false);
+		}
+	}
+
+	async function removeItem(productId: string): Promise<void> {
+		const entry = findWishlistEntry(_items, productId);
+		if (!entry?.id) {
+			// Either the wishlist hasn't loaded yet or the item isn't there.
+			// Either way, nothing to remove.
+			return;
+		}
+		setLoading(true);
+		try {
+			const updated = await invoke.vtex.actions.removeFromWishlist({
+				data: { id: entry.id },
+			});
+			setItems(updated);
+		} catch (err) {
+			console.error("[useWishlist] removeItem failed:", err);
+			throw err;
+		} finally {
+			setLoading(false);
+		}
+	}
+
+	async function refresh(): Promise<WishlistItem[]> {
+		setLoading(true);
+		try {
+			const items = await invoke.vtex.loaders.wishlist();
+			setItems(items);
+			_initFailed = false;
+			return items;
+		} catch (err) {
+			console.error("[useWishlist] refresh failed:", err);
+			_initFailed = true;
+			notify();
+			return [];
+		} finally {
+			setLoading(false);
+		}
+	}
+
+	/** Reset module-level wishlist state so the next useWishlist() re-fetches. */
+	function resetWishlist() {
+		_items = [];
+		_loading = false;
+		_initStarted = false;
+		_initFailed = false;
+		notify();
+	}
+
+	function useWishlist() {
+		const [, forceRender] = useState(0);
+
+		useEffect(() => {
+			const listener = () => forceRender((n) => n + 1);
+			_listeners.add(listener);
+
+			if (_items.length === 0 && !_initStarted) {
+				_initStarted = true;
+				setLoading(true);
+				invoke.vtex.loaders
+					.wishlist()
+					.then((items) => {
+						setItems(items);
+					})
+					.catch((err: unknown) => {
+						// 401 / unauthenticated is normal — user just isn't logged in.
+						// Real errors get logged.
+						console.error("[useWishlist] init failed:", err);
+						_initFailed = true;
+						notify();
+					})
+					.finally(() => setLoading(false));
+			}
+
+			return () => {
+				_listeners.delete(listener);
+			};
+		}, []);
+
+		return {
+			items: {
+				get value() {
+					return _items;
+				},
+				set value(v: WishlistItem[]) {
+					setItems(v);
+				},
+			},
+
+			loading: {
+				get value() {
+					return _loading;
+				},
+			},
+
+			initFailed: {
+				get value() {
+					return _initFailed;
+				},
+			},
+
+			count: {
+				get value() {
+					return _items.length;
+				},
+			},
+
+			addItem,
+			removeItem,
+			getItem,
+			refresh,
+		};
+	}
+
+	return {
+		useWishlist,
+		resetWishlist,
+	};
+}

package/src/hooks/index.ts

@@ -0,0 +1,19 @@
+export {
+	type CreateUseCartInvoke,
+	type CreateUseCartOptions,
+	createUseCart,
+} from "./createUseCart";
+export {
+	type CreateUseUserInvoke,
+	type CreateUseUserOptions,
+	createUseUser,
+} from "./createUseUser";
+export {
+	type CreateUseWishlistInvoke,
+	type CreateUseWishlistOptions,
+	createUseWishlist,
+} from "./createUseWishlist";
+export { type UseAutocompleteOptions, useAutocomplete } from "./useAutocomplete";
+export { type CartItem, type OrderForm, type UseCartOptions, useCart } from "./useCart";
+export { type UseUserOptions, useUser, type VtexUser } from "./useUser";
+export { type UseWishlistOptions, useWishlist, type WishlistItem } from "./useWishlist";

package/src/hooks/useAutocomplete.ts

@@ -0,0 +1,83 @@
+/**
+ * Client-side autocomplete hook for VTEX Intelligent Search.
+ *
+ * Uses TanStack Query with debounced input to fetch search suggestions.
+ * Ported from deco-cx/apps vtex/hooks/useAutocomplete.ts
+ *
+ * @example
+ * ```tsx
+ * import { useAutocomplete } from "@decocms/apps/vtex/hooks/useAutocomplete";
+ *
+ * function SearchBar() {
+ *   const { setSearch, suggestions, loading } = useAutocomplete();
+ *   return (
+ *     <input
+ *       onChange={(e) => setSearch(e.target.value)}
+ *       placeholder="Search..."
+ *     />
+ *   );
+ * }
+ * ```
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useCallback, useEffect, useState } from "react";
+import type { Suggestion } from "@decocms/apps-commerce/types";
+
+export interface UseAutocompleteOptions {
+	/** Debounce delay in ms @default 250 */
+	debounceMs?: number;
+	/** Max products to return @default 4 */
+	count?: number;
+	/** Custom fetch function — defaults to calling the inline-loader on the server */
+	fetchSuggestions?: (query: string, count: number) => Promise<Suggestion | null>;
+}
+
+const AUTOCOMPLETE_QUERY_KEY = "vtex-autocomplete";
+
+function useDebounce<T>(value: T, delay: number): T {
+	const [debounced, setDebounced] = useState(value);
+	useEffect(() => {
+		const timer = setTimeout(() => setDebounced(value), delay);
+		return () => clearTimeout(timer);
+	}, [value, delay]);
+	return debounced;
+}
+
+async function defaultFetchSuggestions(query: string, _count: number): Promise<Suggestion | null> {
+	const params = new URLSearchParams({ query });
+	const res = await fetch(`/api/vtex/suggestions?${params}`);
+	if (!res.ok) return null;
+	return res.json();
+}
+
+export function useAutocomplete(opts?: UseAutocompleteOptions) {
+	const debounceMs = opts?.debounceMs ?? 250;
+	const count = opts?.count ?? 4;
+	const fetchFn = opts?.fetchSuggestions ?? defaultFetchSuggestions;
+
+	const [rawQuery, setRawQuery] = useState("");
+	const debouncedQuery = useDebounce(rawQuery.trim(), debounceMs);
+
+	const { data, isLoading, isFetching } = useQuery({
+		queryKey: [AUTOCOMPLETE_QUERY_KEY, debouncedQuery, count],
+		queryFn: () => fetchFn(debouncedQuery, count),
+		enabled: debouncedQuery.length > 0,
+		staleTime: 60_000,
+	});
+
+	const setSearch = useCallback((query: string) => {
+		setRawQuery(query);
+	}, []);
+
+	return {
+		/** Set the search query (will be debounced automatically) */
+		setSearch,
+		/** Current raw (un-debounced) query */
+		query: rawQuery,
+		/** Suggestion result (searches + products) */
+		suggestions: data ?? null,
+		/** True while initial fetch is in progress */
+		loading: isLoading || isFetching,
+	};
+}

package/src/hooks/useCart.ts

@@ -0,0 +1,243 @@
+/**
+ * Client-side cart hook for VTEX.
+ *
+ * Uses TanStack Query for SWR, optimistic updates, and cache invalidation.
+ * Returns BOTH the raw `OrderForm` (back-compat for existing consumers) AND
+ * the canonical `Minicart` shape (preferred for new code).
+ *
+ * @example Reading the cart
+ * ```tsx
+ * import { useCart } from "@decocms/apps/vtex/hooks/useCart";
+ *
+ * function CartButton() {
+ *   const { minicart, isLoading } = useCart({ freeShippingTarget: 200 });
+ *   const count = minicart?.storefront.items.length ?? 0;
+ *   return <button disabled={isLoading}>{count} items</button>;
+ * }
+ * ```
+ *
+ * @example Mutations
+ * ```tsx
+ * const { addItems, removeItem, addCoupons } = useCart();
+ * addItems.mutate([{ id: "123", seller: "1", quantity: 1 }]);
+ * ```
+ */
+
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import type { Minicart } from "@decocms/apps-commerce/types";
+import type { OrderForm, OrderFormItem } from "../types";
+import { vtexOrderFormToMinicart } from "../utils/minicart";
+
+/** Re-exported from `vtex/types` for back-compat. New code should import directly. */
+export type { OrderForm } from "../types";
+
+/**
+ * Slim cart-item shape used by mutations.
+ * @deprecated Use `OrderFormItem` from `@decocms/apps/vtex/types` for full fidelity,
+ *   or `MinicartItem` from `@decocms/apps/commerce/types` for the canonical contract.
+ */
+export type CartItem = Pick<OrderFormItem, "id" | "quantity" | "seller">;
+
+const CART_QUERY_KEY = ["vtex", "cart"] as const;
+
+const DEFAULT_EXPECTED_SECTIONS = [
+	"items",
+	"totalizers",
+	"clientProfileData",
+	"shippingData",
+	"paymentData",
+	"sellers",
+	"messages",
+	"marketingData",
+	"clientPreferencesData",
+	"storePreferencesData",
+	"giftRegistryData",
+	"ratesAndBenefitsData",
+	"openTextField",
+	"commercialConditionData",
+	"customData",
+];
+
+function getScParam(): string {
+	if (typeof window !== "undefined") {
+		const match = document.cookie.match(/(?:^|;\s*)VTEXSC=([^;]+)/);
+		return match?.[1] ?? "";
+	}
+	return "";
+}
+
+function appendSc(url: string): string {
+	const sc = getScParam();
+	if (!sc) return url;
+	return url.includes("?") ? `${url}&sc=${sc}` : `${url}?sc=${sc}`;
+}
+
+async function fetchCart(): Promise<OrderForm> {
+	const res = await fetch(appendSc("/api/checkout/pub/orderForm"), {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ expectedOrderFormSections: DEFAULT_EXPECTED_SECTIONS }),
+		credentials: "include",
+	});
+	if (!res.ok) throw new Error(`Cart fetch failed: ${res.status}`);
+	return res.json();
+}
+
+async function addItemsToCart(
+	orderFormId: string,
+	items: Array<{ id: string; quantity: number; seller: string }>,
+): Promise<OrderForm> {
+	const params = new URLSearchParams();
+	params.append("allowedOutdatedData", "paymentData");
+	const sc = getScParam();
+	if (sc) params.set("sc", sc);
+
+	const res = await fetch(`/api/checkout/pub/orderForm/${orderFormId}/items?${params}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ orderItems: items }),
+		credentials: "include",
+	});
+	if (!res.ok) throw new Error(`Add to cart failed: ${res.status}`);
+	return res.json();
+}
+
+async function addCouponsToCart(orderFormId: string, text: string): Promise<OrderForm> {
+	const params = new URLSearchParams();
+	const sc = getScParam();
+	if (sc) params.set("sc", sc);
+
+	const res = await fetch(`/api/checkout/pub/orderForm/${orderFormId}/coupons?${params}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ text }),
+		credentials: "include",
+	});
+	if (!res.ok) throw new Error(`Add coupon failed: ${res.status}`);
+	return res.json();
+}
+
+async function updateItemQuantity(
+	orderFormId: string,
+	index: number,
+	quantity: number,
+): Promise<OrderForm> {
+	const params = new URLSearchParams();
+	params.append("allowedOutdatedData", "paymentData");
+	const sc = getScParam();
+	if (sc) params.set("sc", sc);
+
+	const res = await fetch(`/api/checkout/pub/orderForm/${orderFormId}/items/update?${params}`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ orderItems: [{ index, quantity }] }),
+		credentials: "include",
+	});
+	if (!res.ok) throw new Error(`Update quantity failed: ${res.status}`);
+	return res.json();
+}
+
+export interface UseCartOptions {
+	/** Enable automatic refetching. @default true */
+	enabled?: boolean;
+	/** Stale time in ms. @default 30000 */
+	staleTime?: number;
+	/** Free-shipping threshold in major units, surfaced on `minicart.storefront`. @default 0 */
+	freeShippingTarget?: number;
+	/** Override the OrderForm's locale (BCP-47, e.g. `"pt-BR"`). */
+	locale?: string;
+	/** Where the checkout button sends the user. @default "/checkout" */
+	checkoutHref?: string;
+	/** Whether to surface the coupon input. @default true */
+	enableCoupon?: boolean;
+}
+
+export function useCart(options?: UseCartOptions) {
+	const queryClient = useQueryClient();
+
+	const query = useQuery({
+		queryKey: CART_QUERY_KEY,
+		queryFn: fetchCart,
+		staleTime: options?.staleTime ?? 30_000,
+		enabled: options?.enabled !== false,
+	});
+
+	const cart = query.data ?? null;
+
+	const minicart: Minicart<OrderForm> | null = useMemo(() => {
+		if (!cart) return null;
+		return vtexOrderFormToMinicart(cart, {
+			freeShippingTarget: options?.freeShippingTarget,
+			locale: options?.locale,
+			checkoutHref: options?.checkoutHref,
+			enableCoupon: options?.enableCoupon,
+		});
+	}, [
+		cart,
+		options?.freeShippingTarget,
+		options?.locale,
+		options?.checkoutHref,
+		options?.enableCoupon,
+	]);
+
+	const addItems = useMutation({
+		mutationFn: (items: Array<{ id: string; quantity: number; seller: string }>) => {
+			const orderFormId = query.data?.orderFormId;
+			if (!orderFormId) throw new Error("Cart not loaded");
+			return addItemsToCart(orderFormId, items);
+		},
+		onSuccess: (data) => {
+			queryClient.setQueryData(CART_QUERY_KEY, data);
+		},
+	});
+
+	const updateQuantity = useMutation({
+		mutationFn: ({ index, quantity }: { index: number; quantity: number }) => {
+			const orderFormId = query.data?.orderFormId;
+			if (!orderFormId) throw new Error("Cart not loaded");
+			return updateItemQuantity(orderFormId, index, quantity);
+		},
+		onSuccess: (data) => {
+			queryClient.setQueryData(CART_QUERY_KEY, data);
+		},
+	});
+
+	const removeItem = useMutation({
+		mutationFn: (index: number) => {
+			const orderFormId = query.data?.orderFormId;
+			if (!orderFormId) throw new Error("Cart not loaded");
+			return updateItemQuantity(orderFormId, index, 0);
+		},
+		onSuccess: (data) => {
+			queryClient.setQueryData(CART_QUERY_KEY, data);
+		},
+	});
+
+	const addCoupons = useMutation({
+		mutationFn: (text: string) => {
+			const orderFormId = query.data?.orderFormId;
+			if (!orderFormId) throw new Error("Cart not loaded");
+			return addCouponsToCart(orderFormId, text);
+		},
+		onSuccess: (data) => {
+			queryClient.setQueryData(CART_QUERY_KEY, data);
+		},
+	});
+
+	return {
+		/** Raw VTEX OrderForm — escape hatch for platform-specific reads. */
+		cart,
+		/** Canonical platform-agnostic minicart. Prefer this in new UI code. */
+		minicart,
+		isLoading: query.isLoading,
+		isError: query.isError,
+		error: query.error,
+		refetch: query.refetch,
+		addItems,
+		addCoupons,
+		updateQuantity,
+		removeItem,
+		itemCount: cart?.items?.length ?? 0,
+	};
+}

package/src/hooks/useUser.ts

@@ -0,0 +1,78 @@
+/**
+ * Client-side user/session hook for VTEX.
+ *
+ * Detects login state via the VTEX Sessions API (server-side accessible).
+ * Does NOT attempt to read VtexIdclientAutCookie client-side — that cookie
+ * is HttpOnly and inaccessible via document.cookie.
+ *
+ * @example
+ * ```tsx
+ * import { useUser } from "@decocms/apps/vtex/hooks/useUser";
+ *
+ * function UserGreeting() {
+ *   const { user, isLoggedIn } = useUser();
+ *   if (!isLoggedIn) return <a href="/account">Sign In</a>;
+ *   return <span>Hello, {user?.email}</span>;
+ * }
+ * ```
+ */
+
+import { useQuery } from "@tanstack/react-query";
+
+export interface VtexUser {
+	email?: string;
+	firstName?: string;
+	lastName?: string;
+	userId?: string;
+	isLoggedIn: boolean;
+}
+
+const USER_QUERY_KEY = ["vtex", "user"] as const;
+
+async function fetchUser(): Promise<VtexUser> {
+	try {
+		const res = await fetch(
+			"/api/sessions?items=profile.email,profile.firstName,profile.lastName,profile.id",
+			{ credentials: "include" },
+		);
+		if (!res.ok) return { isLoggedIn: false };
+
+		const data = await res.json();
+		const profile = data?.namespaces?.profile;
+
+		const email = profile?.email?.value;
+		if (!email) return { isLoggedIn: false };
+
+		return {
+			email,
+			firstName: profile?.firstName?.value,
+			lastName: profile?.lastName?.value,
+			userId: profile?.id?.value,
+			isLoggedIn: true,
+		};
+	} catch {
+		return { isLoggedIn: false };
+	}
+}
+
+export interface UseUserOptions {
+	enabled?: boolean;
+	staleTime?: number;
+}
+
+export function useUser(options?: UseUserOptions) {
+	const query = useQuery({
+		queryKey: USER_QUERY_KEY,
+		queryFn: fetchUser,
+		staleTime: options?.staleTime ?? 30_000,
+		enabled: options?.enabled !== false,
+	});
+
+	return {
+		user: query.data ?? null,
+		isLoggedIn: query.data?.isLoggedIn ?? false,
+		isLoading: query.isLoading,
+		isError: query.isError,
+		refetch: query.refetch,
+	};
+}