@decocms/apps 0.20.1

package/vtex/actions/wishlist.ts

@@ -0,0 +1,116 @@
+/**
+ * VTEX Wishlist actions (wish-list graphql app).
+ * Ported from deco-cx/apps:
+ *   - vtex/actions/wishlist/addItem.ts
+ *   - vtex/actions/wishlist/removeItem.ts
+ * @see https://developers.vtex.com/docs/apps/vtex.wish-list
+ */
+import { vtexFetch, getVtexConfig, vtexIOGraphQL } from "../client";
+import { buildAuthCookieHeader } from "../utils/vtexId";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WishlistItem {
+  id?: string;
+  productId: string;
+  sku: string;
+  title?: string;
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL helper (myvtex.com private graphql)
+// ---------------------------------------------------------------------------
+
+interface GqlResponse<T> {
+  data: T;
+  errors?: Array<{ message: string }>;
+}
+
+function buildCookieHeader(authCookie: string): string {
+  return buildAuthCookieHeader(authCookie, getVtexConfig().account);
+}
+
+// ---------------------------------------------------------------------------
+// Queries & Mutations
+// ---------------------------------------------------------------------------
+
+const ADD_TO_WISHLIST = `mutation AddToWishlist($listItem: ListItemInputType!, $shopperId: String!, $name: String!, $public: Boolean) {
+  addToList(listItem: $listItem, shopperId: $shopperId, name: $name, public: $public) @context(provider: "vtex.wish-list@1.x")
+}`;
+
+const REMOVE_FROM_WISHLIST = `mutation RemoveFromList($id: ID!, $shopperId: String!, $name: String) {
+  removeFromList(id: $id, shopperId: $shopperId, name: $name) @context(provider: "vtex.wish-list@1.x")
+}`;
+
+const VIEW_WISHLIST = `query ViewList($shopperId: String!, $name: String!, $from: Int!, $to: Int!) {
+  viewList(shopperId: $shopperId, name: $name, from: $from, to: $to) @context(provider: "vtex.wish-list@1.x") {
+    data { id productId sku title }
+  }
+}`;
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+async function fetchWishlist(shopperId: string, authCookie: string): Promise<WishlistItem[]> {
+  const data = await vtexIOGraphQL<{
+    viewList: { data: WishlistItem[] | null };
+  }>(
+    {
+      query: VIEW_WISHLIST,
+      variables: { shopperId, name: "Wishlist", from: 0, to: 500 },
+    },
+    { Cookie: buildCookieHeader(authCookie) },
+  );
+  return data.viewList?.data ?? [];
+}
+
+/**
+ * Add an item to the user's wishlist.
+ * Returns the updated full wishlist.
+ */
+export async function addItem(
+  item: { productId: string; sku: string; title?: string },
+  shopperId: string,
+  authCookie: string,
+): Promise<WishlistItem[]> {
+  if (!authCookie) throw new Error("User must be logged in to add to wishlist");
+  await vtexIOGraphQL<unknown>(
+    {
+      query: ADD_TO_WISHLIST,
+      variables: {
+        name: "Wishlist",
+        shopperId,
+        listItem: item,
+      },
+    },
+    { Cookie: buildCookieHeader(authCookie) },
+  );
+  return fetchWishlist(shopperId, authCookie);
+}
+
+/**
+ * Remove an item from the user's wishlist by its list-entry ID.
+ * Returns the updated full wishlist.
+ */
+export async function removeItem(
+  id: string,
+  shopperId: string,
+  authCookie: string,
+): Promise<WishlistItem[]> {
+  if (!authCookie) throw new Error("User must be logged in to remove from wishlist");
+  await vtexIOGraphQL<unknown>(
+    {
+      query: REMOVE_FROM_WISHLIST,
+      variables: {
+        id,
+        name: "Wishlist",
+        shopperId,
+      },
+    },
+    { Cookie: buildCookieHeader(authCookie) },
+  );
+  return fetchWishlist(shopperId, authCookie);
+}

package/vtex/client.ts

@@ -0,0 +1,423 @@
+/**
+ * VTEX API Client for TanStack Start.
+ * Uses VTEX's public REST APIs (Intelligent Search + Catalog + Checkout).
+ */
+
+import { type FetchCacheOptions, fetchWithCache } from "./utils/fetchCache";
+
+// ---------------------------------------------------------------------------
+// URL sanitization (ported from deco-cx/apps vtex/utils/fetchVTEX.ts)
+// ---------------------------------------------------------------------------
+
+const removeNonLatin1Chars = (str: string): string =>
+	str.replace(/[^\x00-\x7F]|["']/g, "");
+
+const removeScriptChars = (str: string): string => {
+	return str
+		.replace(/\+/g, "")
+		.replaceAll(" ", "")
+		.replace(/[[\]{}()<>]/g, "")
+		.replace(/[/\\]/g, "")
+		.replace(/\./g, "")
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "");
+};
+
+function sanitizeUrl(input: string): string {
+	let url: URL;
+	try {
+		url = new URL(input);
+	} catch {
+		return input;
+	}
+
+	const QS_TO_SANITIZE = ["utm_campaign", "utm_medium", "utm_source", "map"];
+	for (const qs of QS_TO_SANITIZE) {
+		if (url.searchParams.has(qs)) {
+			const values = url.searchParams.getAll(qs);
+			url.searchParams.delete(qs);
+			for (const v of values) {
+				const sanitized = removeScriptChars(removeNonLatin1Chars(v));
+				if (sanitized) url.searchParams.append(qs, sanitized);
+			}
+		}
+	}
+
+	const QS_TO_ENCODE = ["ft"];
+	for (const qs of QS_TO_ENCODE) {
+		if (url.searchParams.has(qs)) {
+			const values = url.searchParams.getAll(qs);
+			url.searchParams.delete(qs);
+			for (const v of values) {
+				url.searchParams.append(qs, encodeURIComponent(v.trim()));
+			}
+		}
+	}
+
+	return url.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface VtexConfig {
+	account: string;
+	publicUrl?: string;
+	salesChannel?: string;
+	locale?: string;
+	appKey?: string;
+	appToken?: string;
+	/**
+	 * ISO 3166-1 alpha-3 country code used for simulation/checkout.
+	 * @default "BRA"
+	 */
+	country?: string;
+	/**
+	 * VTEX domain suffix. Override for non-standard VTEX environments.
+	 * @default "com.br"
+	 */
+	domain?: string;
+}
+
+let _config: VtexConfig | null = null;
+let _fetch: typeof fetch = globalThis.fetch;
+
+export function configureVtex(config: VtexConfig) {
+	_config = config;
+	console.log(`[VTEX] Configured: ${config.account}.vtexcommercestable.com.br`);
+}
+
+/**
+ * Override the fetch function used by all VTEX client calls.
+ * Use this to plug in instrumented fetch for logging/tracing.
+ *
+ * @example
+ * ```ts
+ * import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
+ * import { setVtexFetch } from "@decocms/apps/vtex";
+ * setVtexFetch(createInstrumentedFetch("vtex"));
+ * ```
+ */
+export function setVtexFetch(fetchFn: typeof fetch) {
+	_fetch = fetchFn;
+}
+
+export function getVtexConfig(): VtexConfig {
+	if (!_config)
+		throw new Error("VTEX not configured. Call configureVtex() first.");
+	return _config;
+}
+
+/**
+ * Build the VTEX hostname for a given environment.
+ * Centralizes `{account}.{env}.{domain}` so nothing is hardcoded.
+ */
+export function vtexHost(
+	environment: string = "vtexcommercestable",
+	config?: VtexConfig,
+): string {
+	const c = config ?? getVtexConfig();
+	const domain = c.domain ?? "com.br";
+	return `${c.account}.${environment}.${domain}`;
+}
+
+function baseUrl(): string {
+	return `https://${vtexHost()}`;
+}
+
+function isUrl(): string {
+	return `https://${vtexHost()}/api/io/_v/api/intelligent-search`;
+}
+
+function authHeaders(): Record<string, string> {
+	const c = getVtexConfig();
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+		Accept: "application/json",
+	};
+	if (c.appKey && c.appToken) {
+		headers["X-VTEX-API-AppKey"] = c.appKey;
+		headers["X-VTEX-API-AppToken"] = c.appToken;
+	}
+	return headers;
+}
+
+export async function vtexFetchResponse(
+	path: string,
+	init?: RequestInit,
+): Promise<Response> {
+	const raw = path.startsWith("http") ? path : `${baseUrl()}${path}`;
+	const url = sanitizeUrl(raw);
+	const response = await _fetch(url, {
+		...init,
+		headers: { ...authHeaders(), ...init?.headers },
+	});
+	if (!response.ok) {
+		throw new Error(
+			`VTEX API error: ${response.status} ${response.statusText} - ${url}`,
+		);
+	}
+	return response;
+}
+
+export async function vtexFetch<T>(
+	path: string,
+	init?: RequestInit,
+): Promise<T> {
+	const response = await vtexFetchResponse(path, init);
+	return response.json();
+}
+
+export interface VtexCachedFetchOptions {
+	/** SWR cache TTL override in ms */
+	cacheTTL?: number;
+}
+
+/**
+ * Like vtexFetch but routes GET requests through the SWR in-memory cache.
+ * Uses in-flight dedup + stale-while-revalidate.
+ * Non-GET requests fall through to regular vtexFetch.
+ */
+export async function vtexCachedFetch<T>(
+	path: string,
+	init?: RequestInit,
+	cacheOpts?: VtexCachedFetchOptions,
+): Promise<T | null> {
+	const method = (init?.method ?? "GET").toUpperCase();
+	if (method !== "GET") return vtexFetch<T>(path, init);
+
+	const raw = path.startsWith("http") ? path : `${baseUrl()}${path}`;
+	const url = sanitizeUrl(raw);
+	const opts: FetchCacheOptions | undefined = cacheOpts?.cacheTTL
+		? { ttl: cacheOpts.cacheTTL }
+		: undefined;
+
+	return fetchWithCache<T>(
+		url,
+		() =>
+			_fetch(url, {
+				...init,
+				headers: { ...authHeaders(), ...init?.headers },
+			}),
+		opts,
+	);
+}
+
+/**
+ * Result type for actions that need to propagate VTEX Set-Cookie headers.
+ * In TanStack Start, the caller (server function) is responsible for
+ * forwarding these cookies to the client via `setCookie` from vinxi/http.
+ */
+export interface VtexFetchResult<T> {
+	data: T;
+	setCookies: string[];
+}
+
+/**
+ * Like vtexFetch, but also returns Set-Cookie headers from the response.
+ * Use for checkout, session, and auth actions that set cookies.
+ */
+export async function vtexFetchWithCookies<T>(
+	path: string,
+	init?: RequestInit,
+): Promise<VtexFetchResult<T>> {
+	const response = await vtexFetchResponse(path, init);
+	const data = (await response.json()) as T;
+	const setCookies: string[] = [];
+	if (typeof response.headers.getSetCookie === "function") {
+		setCookies.push(...response.headers.getSetCookie());
+	} else {
+		response.headers.forEach((value, key) => {
+			if (key.toLowerCase() === "set-cookie") {
+				setCookies.push(value);
+			}
+		});
+	}
+	return { data, setCookies };
+}
+
+export async function intelligentSearch<T>(
+	path: string,
+	params?: Record<string, string>,
+	opts?: { cookieHeader?: string; locale?: string },
+): Promise<T> {
+	const url = new URL(`${isUrl()}${path}`);
+	if (params) {
+		for (const [k, v] of Object.entries(params)) {
+			url.searchParams.set(k, v);
+		}
+	}
+	const c = getVtexConfig();
+	if (c.salesChannel) url.searchParams.set("sc", c.salesChannel);
+
+	const locale = opts?.locale ?? c.locale;
+	if (locale && !url.searchParams.has("locale")) {
+		url.searchParams.set("locale", locale);
+	}
+
+	const headers: Record<string, string> = { ...authHeaders() };
+	if (opts?.cookieHeader) {
+		headers.cookie = opts.cookieHeader;
+	}
+
+	const fullUrl = url.toString();
+
+	// IS GET requests go through SWR cache (3 min TTL via status-based defaults).
+	// The doFetch callback throws on non-ok responses, so null is never returned.
+	return fetchWithCache<T>(fullUrl, async () => {
+		const response = await _fetch(fullUrl, { headers });
+		if (!response.ok) {
+			throw new Error(`VTEX IS error: ${response.status} - ${fullUrl}`);
+		}
+		return response;
+	}) as Promise<T>;
+}
+
+/**
+ * Execute a GraphQL query against the VTEX IO Runtime (myvtex.com).
+ * Used for private profile/session/wishlist/payment queries that the
+ * original Deco loaders called via `ctx.io.query(...)`.
+ */
+export async function vtexIOGraphQL<T>(
+	body: {
+		query: string;
+		variables?: Record<string, unknown> | null;
+		operationName?: string;
+	},
+	headers?: Record<string, string>,
+): Promise<T> {
+	const { account } = getVtexConfig();
+	const res = await vtexFetch<{ data: T; errors?: Array<{ message: string }> }>(
+		`https://${account}.myvtex.com/_v/private/graphql/v1`,
+		{
+			method: "POST",
+			headers,
+			body: JSON.stringify(body),
+		},
+	);
+	if (res.errors?.length) {
+		throw new Error(
+			`VTEX IO GraphQL error: ${res.errors.map((e) => e.message).join(", ")}`,
+		);
+	}
+	return res.data;
+}
+
+// -- Page Type API (used by PLP to derive category facets from URL path) --
+
+export interface PageType {
+	id: string;
+	name: string;
+	url: string;
+	title: string;
+	metaTagDescription: string;
+	pageType:
+		| "Brand"
+		| "Category"
+		| "Department"
+		| "SubCategory"
+		| "Collection"
+		| "Cluster"
+		| "Search"
+		| "Product"
+		| "NotFound"
+		| "FullText";
+}
+
+const PAGE_TYPE_TO_MAP_PARAM: Record<string, string | null> = {
+	Brand: "brand",
+	Collection: "productClusterIds",
+	Cluster: "productClusterIds",
+	Search: null,
+	Product: null,
+	NotFound: null,
+	FullText: null,
+};
+
+function pageTypeToMapParam(
+	type: PageType["pageType"],
+	index: number,
+): string | null {
+	if (type === "Category" || type === "Department" || type === "SubCategory") {
+		return `category-${index + 1}`;
+	}
+	return PAGE_TYPE_TO_MAP_PARAM[type] ?? null;
+}
+
+function cachedPageType(term: string): Promise<PageType | null> {
+	return vtexCachedFetch<PageType>(
+		`/api/catalog_system/pub/portal/pagetype/${term}`,
+	);
+}
+
+/**
+ * Query VTEX Page Type API for each path segment (cumulative).
+ * Mirrors deco-cx/apps `pageTypesFromUrl`.
+ * Uses in-flight deduplication to avoid duplicate calls for the same segment.
+ */
+export async function pageTypesFromPath(pagePath: string): Promise<PageType[]> {
+	const segments = pagePath.split("/").filter(Boolean);
+	const results = await Promise.all(
+		segments.map((_, index) => {
+			const term = segments.slice(0, index + 1).join("/");
+			return cachedPageType(term);
+		}),
+	);
+	return results.filter((pt): pt is PageType => pt !== null);
+}
+
+const slugify = (str: string) =>
+	str
+		.replace(/,/g, "")
+		.replace(/[·/_,:]/g, "-")
+		.replace(/[*+~.()'"!:@&[\]`/ %$#?{}|><=_^]/g, "-")
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.toLowerCase();
+
+/**
+ * Convert page types to selectedFacets with correct IS facet keys.
+ * Mirrors deco-cx/apps `filtersFromPathname`.
+ */
+export function filtersFromPageTypes(
+	pageTypes: PageType[],
+): Array<{ key: string; value: string }> {
+	return pageTypes
+		.map((page, index) => {
+			const key = pageTypeToMapParam(page.pageType, index);
+			if (!key || !page.name) return null;
+			return { key, value: slugify(page.name) };
+		})
+		.filter((f): f is { key: string; value: string } => f !== null);
+}
+
+/**
+ * Build the IS facet path string from selectedFacets.
+ * Mirrors deco-cx/apps `toPath`.
+ */
+export function toFacetPath(
+	facets: Array<{ key: string; value: string }>,
+): string {
+	return facets
+		.map(({ key, value }) => (key ? `${key}/${value}` : value))
+		.join("/");
+}
+
+export function initVtexFromBlocks(blocks: Record<string, any>) {
+	const vtexBlock = blocks.vtex || blocks["deco-vtex"];
+	if (!vtexBlock) {
+		console.warn("[VTEX] No vtex.json block found.");
+		return;
+	}
+	configureVtex({
+		account: vtexBlock.account,
+		publicUrl: vtexBlock.publicUrl,
+		salesChannel: vtexBlock.salesChannel || "1",
+		locale: vtexBlock.locale || vtexBlock.defaultLocale,
+		appKey: vtexBlock.appKey,
+		appToken: vtexBlock.appToken,
+		country: vtexBlock.country,
+		domain: vtexBlock.domain,
+	});
+}

package/vtex/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useCart, type UseCartOptions, type OrderForm, type CartItem } from "./useCart";
+export { useUser, type UseUserOptions, type VtexUser } from "./useUser";
+export { useWishlist, type UseWishlistOptions, type WishlistItem } from "./useWishlist";
+export { useAutocomplete, type UseAutocompleteOptions } from "./useAutocomplete";

package/vtex/hooks/useAutocomplete.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { useState, useCallback, useRef, useEffect } from "react";
+import { useQuery } from "@tanstack/react-query";
+import type { Suggestion } from "../../commerce/types/commerce";
+
+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,
+  };
+}