@decocms/apps 0.20.1

package/vtex/hooks/useCart.ts

@@ -0,0 +1,219 @@
+/**
+ * Client-side cart hook for VTEX.
+ *
+ * Uses TanStack Query for SWR, optimistic updates, and cache
+ * invalidation. Wraps the VTEX orderForm API.
+ *
+ * @example
+ * ```tsx
+ * import { useCart } from "@decocms/apps/vtex/hooks/useCart";
+ *
+ * function CartButton() {
+ *   const { cart, addItems, isLoading } = useCart();
+ *   const count = cart?.items?.length ?? 0;
+ *   return <button disabled={isLoading}>{count} items</button>;
+ * }
+ * ```
+ */
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+export interface CartItem {
+  id: string;
+  quantity: number;
+  seller: string;
+}
+
+export interface OrderForm {
+  orderFormId: string;
+  items: CartItem[];
+  totalizers: Array<{ id: string; name: string; value: number }>;
+  value: number;
+  [key: string]: unknown;
+}
+
+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 0 (always refetch) */
+  staleTime?: number;
+}
+
+export function useCart(options?: UseCartOptions) {
+  const queryClient = useQueryClient();
+
+  const query = useQuery({
+    queryKey: CART_QUERY_KEY,
+    queryFn: fetchCart,
+    staleTime: options?.staleTime ?? 0,
+    enabled: options?.enabled !== false,
+  });
+
+  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 {
+    cart: query.data ?? null,
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error,
+    refetch: query.refetch,
+    addItems,
+    addCoupons,
+    updateQuantity,
+    removeItem,
+    itemCount: query.data?.items?.length ?? 0,
+  };
+}

package/vtex/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,
+  };
+}

package/vtex/hooks/useWishlist.ts

@@ -0,0 +1,119 @@
+/**
+ * Client-side wishlist hook for VTEX.
+ *
+ * Reads the wishlist via the invoke proxy and provides
+ * add/remove mutations with automatic cache invalidation.
+ *
+ * @example
+ * ```tsx
+ * import { useWishlist } from "@decocms/apps/vtex/hooks/useWishlist";
+ *
+ * function WishlistButton({ productId, sku }: Props) {
+ *   const { isInWishlist, toggle, isLoading } = useWishlist();
+ *   const wishlisted = isInWishlist(productId);
+ *   return (
+ *     <button onClick={() => toggle({ productId, sku })} disabled={isLoading}>
+ *       {wishlisted ? "♥" : "♡"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+
+export interface WishlistItem {
+  id: string;
+  productId: string;
+  sku: string;
+}
+
+const WISHLIST_QUERY_KEY = ["vtex", "wishlist"] as const;
+
+async function fetchWishlist(): Promise<WishlistItem[]> {
+  const res = await fetch("/deco/invoke/vtex/loaders/wishlist", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({}),
+    credentials: "include",
+  });
+  if (!res.ok) {
+    if (res.status === 401) return [];
+    throw new Error(`Wishlist fetch failed: ${res.status}`);
+  }
+  return res.json();
+}
+
+async function addToWishlist(item: { productId: string; sku: string }): Promise<void> {
+  const res = await fetch("/deco/invoke/vtex/actions/wishlist/addItem", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(item),
+    credentials: "include",
+  });
+  if (!res.ok) throw new Error(`Add to wishlist failed: ${res.status}`);
+}
+
+async function removeFromWishlist(id: string): Promise<void> {
+  const res = await fetch("/deco/invoke/vtex/actions/wishlist/removeItem", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ id }),
+    credentials: "include",
+  });
+  if (!res.ok) throw new Error(`Remove from wishlist failed: ${res.status}`);
+}
+
+export interface UseWishlistOptions {
+  enabled?: boolean;
+  staleTime?: number;
+}
+
+export function useWishlist(options?: UseWishlistOptions) {
+  const queryClient = useQueryClient();
+
+  const query = useQuery({
+    queryKey: WISHLIST_QUERY_KEY,
+    queryFn: fetchWishlist,
+    staleTime: options?.staleTime ?? 60_000,
+    enabled: options?.enabled !== false,
+  });
+
+  const items = query.data ?? [];
+  const productIdSet = new Set(items.map((i) => i.productId));
+
+  const addMutation = useMutation({
+    mutationFn: addToWishlist,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: WISHLIST_QUERY_KEY }),
+  });
+
+  const removeMutation = useMutation({
+    mutationFn: removeFromWishlist,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: WISHLIST_QUERY_KEY }),
+  });
+
+  function isInWishlist(productId: string): boolean {
+    return productIdSet.has(productId);
+  }
+
+  function toggle(item: { productId: string; sku: string }) {
+    const existing = items.find((i) => i.productId === item.productId);
+    if (existing) {
+      removeMutation.mutate(existing.id);
+    } else {
+      addMutation.mutate(item);
+    }
+  }
+
+  return {
+    items,
+    isLoading: query.isLoading || addMutation.isPending || removeMutation.isPending,
+    isError: query.isError,
+    isInWishlist,
+    toggle,
+    add: addMutation,
+    remove: removeMutation,
+    refetch: query.refetch,
+    count: items.length,
+  };
+}

package/vtex/index.ts

@@ -0,0 +1,14 @@
+/**
+ * VTEX app entry point for @decocms/apps.
+ * Re-exports client config + initializer.
+ *
+ * For actions/loaders/utils, use sub-path imports:
+ *   import { addItemsToCart } from "@decocms/apps/vtex/actions/checkout"
+ *   import { searchProducts }  from "@decocms/apps/vtex/loaders/catalog"
+ *   import { slugify }         from "@decocms/apps/vtex/utils/slugify"
+ *
+ * Or barrel imports:
+ *   import { addItemsToCart } from "@decocms/apps/vtex/actions"
+ *   import { searchProducts }  from "@decocms/apps/vtex/loaders"
+ */
+export * from "./client";

package/vtex/inline-loaders/productDetailsPage.ts

@@ -0,0 +1,75 @@
+/**
+ * PDP loader using Legacy Catalog API + shared transform pipeline.
+ * Maps VTEX catalog response to schema.org ProductDetailsPage
+ * following the same pattern as deco-cx/apps.
+ */
+
+import type { ProductDetailsPage } from "../../commerce/types/commerce";
+import { getVtexConfig, vtexCachedFetch } from "../client";
+import { searchBySlug } from "../utils/slugCache";
+import { pickSku, toProductPage } from "../utils/transform";
+import type { LegacyProduct } from "../utils/types";
+
+export interface PDPProps {
+	slug?: string;
+	skuId?: string;
+	/** When true, PDP pages with ?skuId remain indexable */
+	indexingSkus?: boolean;
+	/** Use product.description instead of metaTagDescription for SEO */
+	preferDescription?: boolean;
+}
+
+export default async function vtexProductDetailsPage(
+	props: PDPProps,
+): Promise<ProductDetailsPage | null> {
+	const { slug, skuId, indexingSkus, preferDescription } = props;
+	if (!slug) return null;
+
+	try {
+		const linkText = slug.replace(/\/p$/, "").replace(/^\//, "").toLowerCase();
+		const config = getVtexConfig();
+		const sc = config.salesChannel;
+
+		const products = await searchBySlug(linkText);
+
+		if (!products || products.length === 0) {
+			return null;
+		}
+
+		const product = products[0];
+		const baseUrl = config.publicUrl
+			? `https://${config.publicUrl}`
+			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+		const sku = pickSku(product, skuId);
+
+		const kitItems: LegacyProduct[] =
+			Array.isArray(sku.kitItems) && sku.kitItems.length > 0
+				? ((await vtexCachedFetch<LegacyProduct[]>(
+						`/api/catalog_system/pub/products/search/?fq=${sku.kitItems.map((item: any) => `skuId:${item.itemId}`).join("&fq=")}&_from=0&_to=49${sc ? `&sc=${sc}` : ""}`,
+					)) ?? [])
+				: [];
+
+		const page = toProductPage(product, sku, kitItems, {
+			baseUrl,
+			priceCurrency: "BRL",
+		});
+
+		return {
+			...page,
+			seo: {
+				title: product.productTitle || product.productName,
+				description: preferDescription
+					? product.description
+					: product.metaTagDescription ||
+						product.description?.substring(0, 160) ||
+						"",
+				canonical: `/${product.linkText}/p`,
+				noIndexing: indexingSkus ? false : !!skuId,
+			},
+		};
+	} catch (error) {
+		console.error("[VTEX] PDP error:", error);
+		return null;
+	}
+}

package/vtex/inline-loaders/productList.ts

@@ -0,0 +1,163 @@
+/**
+ * Product list loader using VTEX Intelligent Search + shared transform pipeline.
+ * Maps IS response to schema.org Product[] following deco-cx/apps pattern.
+ *
+ * Supports: query search, collection IDs, SKU IDs, facets, sort, and
+ * hideUnavailableItems — matching the original productList.ts behavior.
+ */
+import { intelligentSearch, getVtexConfig, toFacetPath } from "../client";
+import { toProduct, pickSku, sortProducts } from "../utils/transform";
+import type { Product as ProductVTEX } from "../utils/types";
+import type { Product } from "../../commerce/types/commerce";
+
+export interface ProductListProps {
+  props?: CollectionProps | QueryProps | ProductIDProps | FacetsProps;
+  query?: string;
+  count?: number;
+  sort?: string;
+  collection?: string;
+  hideUnavailableItems?: boolean;
+}
+
+interface CollectionProps {
+  collection: string;
+  count?: number;
+  sort?: string;
+  hideUnavailableItems?: boolean;
+}
+
+interface QueryProps {
+  query: string;
+  count?: number;
+  sort?: string;
+  fuzzy?: string;
+  hideUnavailableItems?: boolean;
+}
+
+interface ProductIDProps {
+  ids: string[];
+  hideUnavailableItems?: boolean;
+}
+
+interface FacetsProps {
+  query?: string;
+  facets: string;
+  count?: number;
+  sort?: string;
+  hideUnavailableItems?: boolean;
+}
+
+function isCollectionProps(p: any): p is CollectionProps {
+  return typeof p?.collection === "string";
+}
+function isProductIDProps(p: any): p is ProductIDProps {
+  return Array.isArray(p?.ids) && p.ids.length > 0;
+}
+function isFacetsProps(p: any): p is FacetsProps {
+  return typeof p?.facets === "string";
+}
+
+function resolveParams(props: ProductListProps): {
+  query: string;
+  count: number;
+  sort: string;
+  facetPath: string;
+  fuzzy?: string;
+  hideUnavailableItems: boolean;
+  ids?: string[];
+} {
+  const inner = props.props ?? props;
+
+  if (isProductIDProps(inner)) {
+    return {
+      query: `sku:${inner.ids.join(";")}`,
+      count: inner.ids.length,
+      sort: "",
+      facetPath: "",
+      hideUnavailableItems: inner.hideUnavailableItems ?? false,
+      ids: inner.ids,
+    };
+  }
+
+  if (isFacetsProps(inner)) {
+    return {
+      query: inner.query ?? "",
+      count: inner.count ?? 12,
+      sort: inner.sort ?? "",
+      facetPath: inner.facets,
+      hideUnavailableItems: inner.hideUnavailableItems ?? false,
+    };
+  }
+
+  if (isCollectionProps(inner)) {
+    return {
+      query: "",
+      count: inner.count ?? 12,
+      sort: inner.sort ?? "",
+      facetPath: toFacetPath([{ key: "productClusterIds", value: inner.collection }]),
+      hideUnavailableItems: inner.hideUnavailableItems ?? false,
+    };
+  }
+
+  return {
+    query: (inner as any).query ?? "",
+    count: (inner as any).count ?? 12,
+    sort: (inner as any).sort ?? "",
+    facetPath: "",
+    fuzzy: (inner as any).fuzzy,
+    hideUnavailableItems: (inner as any).hideUnavailableItems ?? false,
+  };
+}
+
+export default async function vtexProductList(
+  props: ProductListProps,
+): Promise<Product[] | null> {
+  try {
+    const { query, count, sort, facetPath, fuzzy, hideUnavailableItems, ids } =
+      resolveParams(props);
+
+    const config = getVtexConfig();
+    const locale = config.locale ?? "pt-BR";
+
+    const params: Record<string, string> = {
+      page: "1",
+      count: String(count),
+      locale,
+      hideUnavailableItems: String(hideUnavailableItems),
+    };
+    if (query) params.query = query;
+    if (sort) params.sort = sort;
+    if (fuzzy) params.fuzzy = fuzzy;
+
+    const endpoint = facetPath
+      ? `/product_search/${facetPath}`
+      : "/product_search/";
+
+    const data = await intelligentSearch<{ products: ProductVTEX[] }>(
+      endpoint,
+      params,
+    );
+
+    const vtexProducts = data.products ?? [];
+    const baseUrl = config.publicUrl
+      ? `https://${config.publicUrl}`
+      : `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+    let products = vtexProducts.map((p) => {
+      const fetchedSkus = ids ? new Set(ids) : null;
+      const preferredSku = fetchedSkus
+        ? p.items.find((item) => fetchedSkus.has(item.itemId)) ?? pickSku(p)
+        : pickSku(p);
+      return toProduct(p, preferredSku, 0, { baseUrl, priceCurrency: "BRL" });
+    });
+
+    if (ids) {
+      products = sortProducts(products, ids, "sku");
+    }
+
+    return products;
+  } catch (error) {
+    console.error("[VTEX] ProductList error:", error);
+    return null;
+  }
+}