@decocms/apps-vtex 7.2.0

package/src/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 { useMutation, useQuery, 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/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * VTEX app entry point for @decocms/apps.
+ * Re-exports client config + initializer + app contract.
+ *
+ * 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";
+export { configure, type VtexState } from "./mod";
+export { type CreateVtexFetchOptions, createVtexFetch } from "./utils/instrumentedFetch";
+export { vtexOperationRouter } from "./utils/operationRouter";

package/src/invoke.ts

@@ -0,0 +1,181 @@
+/**
+ * Typed `invoke.vtex.actions.*` object — generator contract.
+ *
+ * This file is the source of truth that `@decocms/start/scripts/generate-invoke.ts`
+ * scans to emit the site-local `src/server/invoke.gen.ts`. The generator:
+ *
+ *   1. parses the imports in this file to learn which action lives where,
+ *   2. walks `invoke.vtex.actions.*` and extracts each entry's:
+ *      - validated input type (the arrow function's first parameter),
+ *      - imported action function (matched against the import map by name),
+ *      - output type (the outermost `as` cast's `Promise<...>` payload),
+ *   3. emits a top-level `createServerFn` per action so TanStack Start's
+ *      compiler can transform `.handler()` into client RPC stubs (the
+ *      compiler only walks top-level decls, not factory-returned ones).
+ *
+ * Every action gets a `forwardResponseCookies()` call in the generated
+ * handler — that bridges `Set-Cookie` headers captured by
+ * `vtexFetchWithCookies` into TanStack Start's HTTP response. Without it,
+ * `checkout.vtex.com` and `CheckoutOrderFormOwnership` never reach the
+ * browser, and the storefront's mini-cart drifts away from VTEX's
+ * server-side orderForm.
+ *
+ * To add a new action:
+ *   1. Add an entry below with the input/output types and the action call,
+ *   2. From a site repo: `npm run generate:invoke`.
+ */
+import { createInvokeFn } from "@decocms/tanstack";
+import {
+	addCouponToCart,
+	addItemsToCart,
+	getOrCreateCart,
+	getSellersByRegion,
+	type RegionResult,
+	type SimulationItem,
+	setShippingPostalCode,
+	simulateCart,
+	updateCartItems,
+	updateOrderFormAttachment,
+} from "./actions/checkout";
+import {
+	type CreateDocumentResult,
+	createDocument,
+	getDocument,
+	patchDocument,
+	searchDocuments,
+	type UploadAttachmentOpts,
+	uploadAttachment,
+} from "./actions/masterData";
+import { type NotifyMeProps, notifyMe } from "./actions/misc";
+import { type SubscribeProps, subscribe } from "./actions/newsletter";
+import { createSession, editSession, type SessionData } from "./actions/session";
+import type { OrderForm } from "./types";
+
+// ---------------------------------------------------------------------------
+// invoke.vtex.actions — typed server functions callable from client
+//
+// Action bodies receive the validated input object directly and pass it
+// straight to the action function (which expects a single `props` object).
+// The arrow function body is what the generator parses for "which action
+// is this entry calling" — keep the call site shaped as `actionName(data)`
+// so the matcher in `generate-invoke.ts` picks the right importedFn.
+// ---------------------------------------------------------------------------
+
+export const invoke = {
+	vtex: {
+		actions: {
+			// -- Cart (OrderForm CRUD) --------------------------------------------
+
+			getOrCreateCart: createInvokeFn((data: { orderFormId?: string }) =>
+				getOrCreateCart(data),
+			) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+
+			addItemsToCart: createInvokeFn(
+				(data: {
+					orderFormId: string;
+					orderItems: Array<{
+						id: string;
+						seller: string;
+						quantity: number;
+					}>;
+				}) => addItemsToCart(data),
+			) as unknown as (ctx: {
+				data: {
+					orderFormId: string;
+					orderItems: Array<{
+						id: string;
+						seller: string;
+						quantity: number;
+					}>;
+				};
+			}) => Promise<OrderForm>,
+
+			updateCartItems: createInvokeFn(
+				(data: { orderFormId: string; orderItems: Array<{ index: number; quantity: number }> }) =>
+					updateCartItems(data),
+			) as unknown as (ctx: {
+				data: { orderFormId: string; orderItems: Array<{ index: number; quantity: number }> };
+			}) => Promise<OrderForm>,
+
+			addCouponToCart: createInvokeFn((data: { orderFormId: string; text: string }) =>
+				addCouponToCart(data),
+			) as unknown as (ctx: { data: { orderFormId: string; text: string } }) => Promise<OrderForm>,
+
+			simulateCart: createInvokeFn(
+				(data: { items: SimulationItem[]; postalCode: string; country?: string }) =>
+					simulateCart(data),
+			),
+
+			// -- Shipping / Region ------------------------------------------------
+
+			getSellersByRegion: createInvokeFn((data: { postalCode: string; salesChannel?: string }) =>
+				getSellersByRegion(data),
+			) as unknown as (ctx: {
+				data: { postalCode: string; salesChannel?: string };
+			}) => Promise<RegionResult | null>,
+
+			setShippingPostalCode: createInvokeFn(
+				(data: { orderFormId: string; postalCode: string; country?: string }) =>
+					setShippingPostalCode(data),
+			) as unknown as (ctx: {
+				data: { orderFormId: string; postalCode: string; country?: string };
+			}) => Promise<boolean>,
+
+			updateOrderFormAttachment: createInvokeFn(
+				(data: { orderFormId: string; attachment: string; body: Record<string, unknown> }) =>
+					updateOrderFormAttachment(data),
+			) as unknown as (ctx: {
+				data: { orderFormId: string; attachment: string; body: Record<string, unknown> };
+			}) => Promise<OrderForm>,
+
+			// -- Session ----------------------------------------------------------
+
+			createSession: createInvokeFn((data: Record<string, any>) => createSession({ data })),
+
+			editSession: createInvokeFn((data: { public: Record<string, { value: string }> }) =>
+				editSession(data),
+			) as unknown as (ctx: {
+				data: { public: Record<string, { value: string }> };
+			}) => Promise<SessionData>,
+
+			// -- MasterData -------------------------------------------------------
+
+			createDocument: createInvokeFn((data: { entity: string; data: Record<string, any> }) =>
+				createDocument(data),
+			) as unknown as (ctx: {
+				data: { entity: string; data: Record<string, any> };
+			}) => Promise<CreateDocumentResult>,
+
+			getDocument: createInvokeFn((data: { entity: string; documentId: string }) =>
+				getDocument(data),
+			),
+
+			patchDocument: createInvokeFn(
+				(data: { entity: string; documentId: string; data: Record<string, any> }) =>
+					patchDocument(data),
+			) as unknown as (ctx: {
+				data: { entity: string; documentId: string; data: Record<string, any> };
+			}) => Promise<void>,
+
+			searchDocuments: createInvokeFn((data: { entity: string; filter: string }) =>
+				searchDocuments(data),
+			),
+
+			uploadAttachment: createInvokeFn((data: UploadAttachmentOpts) =>
+				uploadAttachment(data),
+			) as unknown as (ctx: { data: UploadAttachmentOpts }) => Promise<{ ok: true }>,
+
+			// -- Newsletter -------------------------------------------------------
+
+			subscribe: createInvokeFn((data: SubscribeProps) => subscribe(data)) as unknown as (ctx: {
+				data: SubscribeProps;
+			}) => Promise<void>,
+
+			// -- Misc -------------------------------------------------------------
+
+			notifyMe: createInvokeFn((data: NotifyMeProps) => notifyMe(data)) as unknown as (ctx: {
+				data: NotifyMeProps;
+			}) => Promise<void>,
+		},
+	},
+} as const;

package/src/loaders/ProductDetailsPage.ts

@@ -0,0 +1 @@
+export { default, type PDPProps } from "./intelligentSearch/productDetailsPage";

package/src/loaders/ProductList.ts

@@ -0,0 +1 @@
+export { default, type ProductListProps } from "./intelligentSearch/productList";

package/src/loaders/ProductListingPage.ts

@@ -0,0 +1 @@
+export { default, type PLPProps } from "./intelligentSearch/productListingPage";

package/src/loaders/address.ts

@@ -0,0 +1,115 @@
+/**
+ * VTEX Address API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/address/getAddressByPostalCode.ts
+ *   vtex/loaders/address/getUserAddresses.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api
+ */
+import { vtexFetch, vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PostalAddress {
+	"@type": "PostalAddress";
+	postalCode?: string;
+	addressLocality?: string;
+	addressRegion?: string;
+	addressCountry?: string;
+	streetAddress?: string;
+	identifier?: string;
+	areaServed?: string;
+	description?: string;
+	disambiguatingDescription?: string;
+	latitude?: number;
+	longitude?: number;
+}
+
+export interface VtexAddress {
+	addressId: string;
+	addressType: string;
+	addressName: string;
+	city: string;
+	complement: string;
+	country: string;
+	neighborhood: string;
+	number: string;
+	postalCode: string;
+	geoCoordinates: number[];
+	receiverName: string;
+	state: string;
+	street: string;
+}
+
+// ---------------------------------------------------------------------------
+// getAddressByPostalCode
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up a postal address by country + postal code (public API).
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/postal-code/-countryCode-/-postalCode-
+ */
+export async function getAddressByPostalCode(
+	countryCode: string,
+	postalCode: string,
+): Promise<PostalAddress> {
+	const data = await vtexFetch<Record<string, any>>(
+		`/api/checkout/pub/postal-code/${countryCode}/${postalCode}`,
+	);
+
+	return {
+		"@type": "PostalAddress",
+		postalCode: data.postalCode,
+		addressLocality: data.city,
+		addressRegion: data.state,
+		addressCountry: data.country,
+		streetAddress: data.street || undefined,
+		identifier: data.number || undefined,
+		areaServed: data.neighborhood || undefined,
+		description: data.complement || undefined,
+		disambiguatingDescription: data.reference || undefined,
+		latitude: data.geoCoordinates?.[0] ?? undefined,
+		longitude: data.geoCoordinates?.[1] ?? undefined,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// getUserAddresses (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const USER_ADDRESSES_QUERY = `query Addresses @context(scope: "private") {
+  profile {
+    cacheId
+    addresses {
+      addressId: id
+      addressType
+      addressName
+      city
+      complement
+      country
+      neighborhood
+      number
+      postalCode
+      geoCoordinates
+      receiverName
+      state
+      street
+    }
+  }
+}`;
+
+/**
+ * Fetch addresses for the currently authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getUserAddresses(authCookie: string): Promise<VtexAddress[]> {
+	const { profile } = await vtexIOGraphQL<{
+		profile: { addresses: VtexAddress[] };
+	}>({ query: USER_ADDRESSES_QUERY }, { cookie: authCookie });
+
+	return profile?.addresses ?? [];
+}

package/src/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/src/loaders/brands.ts

@@ -0,0 +1,44 @@
+/**
+ * VTEX brand loaders.
+ * Returns schema.org Brand[] matching the original deco-cx/apps format.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/brand/list
+ */
+
+import type { Brand } from "@decocms/apps-commerce/types";
+import { getVtexConfig, vtexFetch } from "../client";
+import { toBrand } from "../utils/transform";
+import type { Brand as BrandVTEX } from "../utils/types";
+
+export interface ListBrandsOpts {
+	/** When true, only returns active brands. @default false */
+	filterInactive?: boolean;
+}
+
+/**
+ * List brands from the VTEX catalog, transformed to schema.org Brand format.
+ */
+export async function listBrands(opts?: ListBrandsOpts): Promise<Brand[]> {
+	const config = getVtexConfig();
+	const baseUrl = `https://${config.account}.vteximg.com.br/arquivos/ids`;
+
+	const brands = await vtexFetch<BrandVTEX[]>("/api/catalog_system/pub/brand/list");
+
+	const filtered = opts?.filterInactive ? brands.filter((b) => b.isActive) : brands;
+
+	return filtered.map((b) => toBrand(b, baseUrl));
+}
+
+/**
+ * Get a single brand by ID, as schema.org Brand.
+ */
+export async function getBrandById(brandId: number): Promise<Brand | null> {
+	try {
+		const config = getVtexConfig();
+		const baseUrl = `https://${config.account}.vteximg.com.br/arquivos/ids`;
+		const brand = await vtexFetch<BrandVTEX>(`/api/catalog_system/pub/brand/${brandId}`);
+		return toBrand(brand, baseUrl);
+	} catch {
+		return null;
+	}
+}

package/src/loaders/cart.ts

@@ -0,0 +1,52 @@
+/**
+ * VTEX Cart (OrderForm) loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/cart.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm
+ */
+
+import { DEFAULT_EXPECTED_SECTIONS } from "../actions/checkout";
+import { getVtexConfig, vtexFetch } from "../client";
+import { forceHttpsOnAssets } from "../utils/transform";
+import type { OrderForm } from "../utils/types";
+
+/**
+ * Fetch the current cart (OrderForm).
+ *
+ * When `orderFormId` is provided the existing cart is retrieved;
+ * otherwise a fresh OrderForm is created via POST.
+ *
+ * @param orderFormId - Optional existing orderForm ID (from checkout cookie)
+ * @param salesChannel - Optional sales channel override
+ * @param authCookie - Optional cookie string for authenticated requests
+ */
+export async function getCart(
+	orderFormId?: string,
+	opts?: { salesChannel?: string; authCookie?: string },
+): Promise<OrderForm> {
+	const { salesChannel } = getVtexConfig();
+	const sc = opts?.salesChannel ?? salesChannel;
+	const headers: Record<string, string> = {};
+	if (opts?.authCookie) headers.cookie = opts.authCookie;
+
+	const scParam = sc ? `?sc=${sc}` : "";
+
+	const body = JSON.stringify({ expectedOrderFormSections: DEFAULT_EXPECTED_SECTIONS });
+
+	const cart = orderFormId
+		? await vtexFetch<OrderForm>(`/api/checkout/pub/orderForm/${orderFormId}${scParam}`, {
+				method: "POST",
+				headers,
+				body,
+			})
+		: await vtexFetch<OrderForm>(`/api/checkout/pub/orderForm${scParam}`, {
+				method: "POST",
+				headers,
+				body,
+			});
+
+	return forceHttpsOnAssets(cart);
+}