@decocms/apps-vtex 7.2.0

package/src/loaders/profile.ts

@@ -0,0 +1,138 @@
+/**
+ * VTEX Profile API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/profile/getCurrentProfile.ts
+ *   vtex/loaders/profile/getProfileByEmail.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api
+ */
+import { vtexFetch, vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+const ADDRESS_FIELDS = `
+  addressType
+  receiverName
+  addressId
+  postalCode
+  city
+  state
+  country
+  street
+  number
+  neighborhood
+  complement
+  reference
+  geoCoordinates
+`;
+
+export interface Profile {
+	id: string;
+	cacheId: string;
+	email: string;
+	firstName: string;
+	lastName: string;
+	document: string;
+	userId: string;
+	birthDate: string;
+	gender: string;
+	homePhone: string;
+	businessPhone: string;
+	addresses: Record<string, unknown>[];
+	isCorporate: boolean;
+	tradeName: string;
+	corporateName: string;
+	corporateDocument: string;
+	stateRegistration: string;
+	payments: Record<string, unknown>[];
+	customFields: Array<{ key: string; value: string }>;
+	passwordLastUpdate: string;
+}
+
+// ---------------------------------------------------------------------------
+// getCurrentProfile (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const PROFILE_QUERY = `query getUserProfile($customFields: String) {
+  profile(customFields: $customFields) {
+    id
+    cacheId
+    email
+    firstName
+    lastName
+    document
+    userId
+    birthDate
+    gender
+    homePhone
+    businessPhone
+    addresses { ${ADDRESS_FIELDS} }
+    isCorporate
+    tradeName
+    corporateName
+    corporateDocument
+    stateRegistration
+    payments {
+      cacheId
+      id
+      paymentSystem
+      paymentSystemName
+      cardNumber
+      address { ${ADDRESS_FIELDS} }
+      isExpired
+      expirationDate
+      accountStatus
+    }
+    customFields {
+      key
+      value
+    }
+    passwordLastUpdate
+  }
+}`;
+
+/**
+ * Fetch the full profile for the currently authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getCurrentProfile(
+	authCookie: string,
+	customFields?: string[],
+): Promise<Profile> {
+	const { profile } = await vtexIOGraphQL<{ profile: Profile }>(
+		{
+			query: PROFILE_QUERY,
+			variables: { customFields: customFields?.join(",") },
+		},
+		{ cookie: authCookie },
+	);
+
+	return profile;
+}
+
+// ---------------------------------------------------------------------------
+// getProfileByEmail (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a checkout profile by e-mail.
+ * Requires a valid VTEX auth cookie.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles
+ */
+export async function getProfileByEmail<T = any>(
+	email: string,
+	authCookie: string,
+	ensureComplete?: boolean,
+): Promise<T> {
+	const params = new URLSearchParams({ email });
+	if (ensureComplete) params.set("ensureComplete", "true");
+
+	return vtexFetch<T>(`/api/checkout/pub/profiles?${params}`, {
+		headers: { cookie: authCookie },
+	});
+}

package/src/loaders/promotion.ts

@@ -0,0 +1,30 @@
+/**
+ * VTEX Promotion loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/getPromotionById.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/promotions-and-taxes-api
+ */
+import { vtexFetch } from "../client";
+import type { Document } from "../utils/types";
+
+/**
+ * Fetch a promotion / calculator-configuration by its ID.
+ *
+ * Note: uses the **pvt** (private) endpoint — requires appKey/appToken
+ * or a valid authentication cookie.
+ *
+ * @param promotionId - The `idCalculatorConfiguration` of the promotion
+ * @param authCookie  - Optional cookie string for authenticated requests
+ */
+export async function getPromotionById(
+	promotionId: string,
+	authCookie?: string,
+): Promise<Document[]> {
+	const headers: Record<string, string> = {};
+	if (authCookie) headers.cookie = authCookie;
+
+	return vtexFetch<Document[]>(`/api/rnb/pvt/calculatorconfiguration/${promotionId}`, { headers });
+}

package/src/loaders/search.ts

@@ -0,0 +1,124 @@
+/**
+ * VTEX search-related loaders (Intelligent Search + Catalog).
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/intelligentSearch/topsearches.ts
+ *   vtex/loaders/intelligentSearch/productSearchValidator.ts
+ *   vtex/loaders/options/productIdByTerm.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/intelligent-search-api
+ */
+import { getVtexConfig, intelligentSearch } from "../client";
+import type { Suggestion } from "../utils/types";
+
+// ---------------------------------------------------------------------------
+// getTopSearches
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the top searches from Intelligent Search.
+ *
+ * @param locale - BCP-47 locale (defaults to the configured locale or "pt-BR")
+ */
+export async function getTopSearches(locale?: string): Promise<Suggestion> {
+	const cfg = getVtexConfig();
+	const effectiveLocale = locale ?? cfg.locale ?? "pt-BR";
+
+	return intelligentSearch<Suggestion>("/top_searches", {
+		locale: effectiveLocale,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// validateProductSearch
+// ---------------------------------------------------------------------------
+
+export interface FacetsSearchProps {
+	query?: string;
+	facets?: string;
+	sort?: string;
+	count?: number;
+	page?: number;
+	locale?: string;
+}
+
+/**
+ * Validate whether a product search returns results.
+ *
+ * Runs the given search parameters against Intelligent Search.
+ * If no results are found and the props include facets, retries
+ * the search without facets.
+ *
+ * Returns the raw IS response or `null` when nothing is found.
+ */
+export async function validateProductSearch<T = unknown>(
+	props: FacetsSearchProps,
+	fetcher: (props: FacetsSearchProps) => Promise<T[] | null>,
+): Promise<T[] | null> {
+	const results = await fetcher(props);
+	if (results !== null && results.length > 0) return results;
+
+	if (props.facets) {
+		return fetcher({ ...props, facets: "" });
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// getProductIdByTerm
+// ---------------------------------------------------------------------------
+
+interface ProductIdOption {
+	value: string;
+	label: string;
+	image?: string;
+}
+
+interface ISSuggestionProduct {
+	productId: string;
+	productName: string;
+	brand: string;
+	linkText: string;
+	items: Array<{
+		itemId: string;
+		name: string;
+		images: Array<{ imageUrl: string; imageText: string }>;
+		sellers: Array<{
+			commertialOffer: { Price: number; ListPrice: number };
+		}>;
+	}>;
+}
+
+interface ISSuggestionResponse {
+	searches: Array<{ term: string; count: number }>;
+	products: ISSuggestionProduct[];
+}
+
+/**
+ * Search for products by free-text term and return a list of
+ * `{ value (SKU ID), label, image }` options.
+ *
+ * Hits the IS autocomplete_suggestions endpoint.
+ */
+export async function getProductIdByTerm(term?: string): Promise<ProductIdOption[]> {
+	const query = (term ?? "").trim();
+	if (!query) return [];
+
+	const data = await intelligentSearch<ISSuggestionResponse>("/autocomplete_suggestions/", {
+		query,
+	});
+
+	if (!data.products?.length) {
+		return [{ value: "No products found", label: "No products found" }];
+	}
+
+	return data.products.flatMap((product) =>
+		(product.items ?? []).map((item) => ({
+			value: item.itemId,
+			label: `${item.itemId} - ${product.productName} ${item.name} - ${product.productId}`,
+			image: item.images?.[0]?.imageUrl,
+		})),
+	);
+}

package/src/loaders/session.ts

@@ -0,0 +1,83 @@
+/**
+ * VTEX Session API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/session/getSession.ts
+ *   vtex/loaders/session/getUserSessions.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/session-manager-api
+ */
+import { vtexFetch, vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// getSession (REST)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the current session data.
+ *
+ * @param items - Keys to retrieve, e.g. `["public.variable1", "profile.email"]`.
+ *                Pass `["*"]` (or omit) to retrieve all keys.
+ * @param authCookie - The raw `cookie` header value forwarded from the user request.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/session-manager-api#get-/api/sessions
+ */
+export async function getSession<T = any>(items: string[] = ["*"], authCookie: string): Promise<T> {
+	const qs = new URLSearchParams({ items: items.join(",") });
+	return vtexFetch<T>(`/api/sessions?${qs}`, {
+		headers: { cookie: authCookie },
+	});
+}
+
+// ---------------------------------------------------------------------------
+// getUserSessions (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+export interface LoginSession {
+	id: string;
+	cacheId: string;
+	deviceType: string;
+	city: string;
+	lastAccess: string;
+	browser: string;
+	os: string;
+	ip: string;
+	fullAddress: string;
+	firstAccess: string;
+}
+
+export interface LoginSessionsInfo {
+	currentLoginSessionId: string;
+	loginSessions: LoginSession[];
+}
+
+const USER_SESSIONS_QUERY = `query getUserSessions {
+  loginSessionsInfo {
+    currentLoginSessionId
+    loginSessions {
+      id
+      cacheId
+      deviceType
+      city
+      lastAccess
+      browser
+      os
+      ip
+      fullAddress
+      firstAccess
+    }
+  }
+}`;
+
+/**
+ * Fetch all active login sessions for the currently authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getUserSessions(authCookie: string): Promise<LoginSessionsInfo> {
+	const { loginSessionsInfo } = await vtexIOGraphQL<{
+		loginSessionsInfo: LoginSessionsInfo;
+	}>({ query: USER_SESSIONS_QUERY }, { cookie: authCookie });
+
+	return loginSessionsInfo;
+}

package/src/loaders/user.ts

@@ -0,0 +1,87 @@
+/**
+ * VTEX User API loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/user.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api
+ */
+import { vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface Person {
+	"@id": string;
+	email: string;
+	givenName?: string;
+	familyName?: string;
+	taxID?: string;
+	gender?: string;
+	telephone?: string;
+}
+
+interface VtexUser {
+	id: string;
+	userId: string;
+	email: string;
+	firstName?: string;
+	lastName?: string;
+	profilePicture?: string;
+	gender?: string;
+	document?: string;
+	homePhone?: string;
+	businessPhone?: string;
+}
+
+// ---------------------------------------------------------------------------
+// getUser (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const USER_QUERY = `query getUserProfile {
+  profile {
+    id
+    userId
+    email
+    firstName
+    lastName
+    profilePicture
+    gender
+    document
+    homePhone
+    businessPhone
+  }
+}`;
+
+/**
+ * Fetch the authenticated user as a Schema.org-style `Person`.
+ * Returns `null` when no valid session exists or the query fails.
+ *
+ * @param authCookie - Raw `cookie` header value from the user request.
+ */
+export async function getUser(authCookie: string): Promise<Person | null> {
+	try {
+		const { profile: user } = await vtexIOGraphQL<{ profile: VtexUser }>(
+			{ query: USER_QUERY },
+			{ cookie: authCookie },
+		);
+
+		return {
+			"@id": user.userId ?? user.id,
+			email: user.email,
+			givenName: user.firstName,
+			familyName: user.lastName,
+			taxID: user.document?.replace(/[^\d]/g, ""),
+			gender: user.gender
+				? user.gender === "f"
+					? "https://schema.org/Female"
+					: "https://schema.org/Male"
+				: undefined,
+			telephone: user.homePhone ?? user.businessPhone,
+		};
+	} catch {
+		return null;
+	}
+}

package/src/loaders/wishlist.ts

@@ -0,0 +1,89 @@
+/**
+ * VTEX Wishlist API loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/wishlist.ts
+ *
+ * @see https://developers.vtex.com/docs/guides/vtex-wish-list
+ */
+import { vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface WishlistItem {
+	id: string;
+	productId: string;
+	sku: string;
+	title: string;
+}
+
+export interface GetWishlistOpts {
+	shopperId: string;
+	count?: number;
+	page?: number;
+	allRecords?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// getWishlist (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const WISHLIST_QUERY = `query GetWishlist($shopperId: String!, $name: String!, $from: Int, $to: Int) {
+  viewList(shopperId: $shopperId, name: $name, from: $from, to: $to)
+    @context(provider: "vtex.wish-list@1.x") {
+    name
+    data {
+      id
+      productId
+      sku
+      title
+    }
+  }
+}`;
+
+/**
+ * Fetch the wishlist for a given shopper.
+ * Requires a valid VTEX auth cookie.
+ *
+ * @param authCookie - Raw `cookie` header value from the user request.
+ * @param opts.shopperId - The shopper identifier (usually the e-mail from the JWT `sub` claim).
+ * @param opts.count - Items per page (default: all).
+ * @param opts.page - Zero-based page index (default: 0).
+ * @param opts.allRecords - When true, ignores pagination and returns every item.
+ */
+export async function getWishlist(
+	authCookie: string,
+	opts: GetWishlistOpts,
+): Promise<WishlistItem[]> {
+	try {
+		const { viewList } = await vtexIOGraphQL<{
+			viewList: { name?: string; data: WishlistItem[] };
+		}>(
+			{
+				operationName: "GetWishlist",
+				query: WISHLIST_QUERY,
+				variables: {
+					name: "Wishlist",
+					shopperId: opts.shopperId,
+				},
+			},
+			{ cookie: authCookie },
+		);
+
+		const data = viewList.data ?? [];
+
+		if (opts.allRecords) return data;
+
+		const count = opts.count ?? Infinity;
+		const page = opts.page ?? 0;
+		return data.slice(count * page, count * (page + 1));
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "AbortError") {
+			throw error;
+		}
+		return [];
+	}
+}

package/src/loaders/wishlistProducts.ts

@@ -0,0 +1,69 @@
+/**
+ * Wishlist Products loader.
+ * Returns a ProductListingPage built from the user's wishlist items.
+ *
+ * Ported from deco-cx/apps vtex/loaders/product/wishlist.ts
+ */
+import type { Product, ProductListingPage } from "@decocms/apps-commerce/types";
+import { getWishlist } from "./wishlist";
+
+export interface WishlistProductsProps {
+	/** Items per page @default 12 */
+	count?: number;
+	/** 1 to start from index 1 @default 0 */
+	offset?: 0 | 1;
+	/** The user's auth cookie string */
+	authCookie: string;
+	/** The user's shopper ID (email) */
+	shopperId: string;
+	/** Current page URL (for pagination links) */
+	url: string;
+}
+
+function withPage(baseUrl: string, page: number): string {
+	const url = new URL(baseUrl);
+	url.searchParams.set("page", `${page}`);
+	return `?${url.searchParams}`;
+}
+
+export async function wishlistProducts(
+	props: WishlistProductsProps,
+): Promise<ProductListingPage | null> {
+	const { count: recordPerPage = 12, offset = 0, authCookie, shopperId, url: rawUrl } = props;
+
+	const url = new URL(rawUrl);
+	const page = Math.max(0, Number(url.searchParams.get("page") ?? offset) - offset);
+	const items = await getWishlist(authCookie, { shopperId, allRecords: true });
+	const records = items.length;
+	const start = page * recordPerPage;
+	const end = (page + 1) * recordPerPage;
+
+	const products: Product[] = items
+		.map(({ sku, productId }) => ({
+			"@type": "Product" as const,
+			inProductGroupWithID: productId,
+			productID: sku,
+			sku,
+		}))
+		.slice(start, end);
+
+	return {
+		"@type": "ProductListingPage",
+		breadcrumb: {
+			"@type": "BreadcrumbList",
+			itemListElement: [],
+			numberOfItems: 0,
+		},
+		filters: [],
+		products,
+		pageInfo: {
+			currentPage: page + offset,
+			nextPage: records > end ? withPage(rawUrl, page + 1 + offset) : undefined,
+			previousPage: page > 0 ? withPage(rawUrl, page - 1 + offset) : undefined,
+			recordPerPage,
+			records,
+		},
+		sortOptions: [],
+		seo: null,
+	};
+}

package/src/loaders/workflow/products.ts

@@ -0,0 +1,64 @@
+/**
+ * Workflow/collection products loader using Intelligent Search + shared transform.
+ * Maps IS response to schema.org Product[] following deco-cx/apps pattern.
+ */
+
+import type { Product } from "@decocms/apps-commerce/types";
+import { getVtexConfig, intelligentSearch, toFacetPath } from "../../client";
+import { pickSku, toProduct } from "../../utils/transform";
+import type { Product as ProductVTEX } from "../../utils/types";
+
+export interface WorkflowProductsProps {
+	props?: {
+		query?: string;
+		count?: number;
+		sort?: string;
+		collection?: string;
+	};
+	page?: number;
+	pagesize?: number;
+}
+
+export default async function vtexWorkflowProducts(
+	props: WorkflowProductsProps,
+): Promise<Product[] | null> {
+	const inner = props.props ?? props;
+	const collection = (inner as any).collection;
+	const query = (inner as any).query ?? "";
+	const count = (inner as any).count ?? props.pagesize ?? 12;
+	const sort = (inner as any).sort ?? "";
+
+	try {
+		const config = getVtexConfig();
+		const locale = config.locale ?? "pt-BR";
+
+		const params: Record<string, string> = {
+			count: String(count),
+			locale,
+			page: String((props.page ?? 0) + 1),
+		};
+		if (query) params.query = query;
+		if (sort) params.sort = sort;
+
+		const facetPath = collection
+			? toFacetPath([{ key: "productClusterIds", value: collection }])
+			: "";
+
+		const endpoint = facetPath ? `/product_search/${facetPath}` : "/product_search/";
+
+		const data = await intelligentSearch<{ products: ProductVTEX[] }>(endpoint, params);
+
+		const products = data.products ?? [];
+		const baseUrl = config.publicUrl
+			? `https://${config.publicUrl}`
+			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+
+		return products.map((p) => {
+			const sku = pickSku(p);
+			return toProduct(p, sku, 0, { baseUrl, priceCurrency: "BRL" });
+		});
+	} catch (error) {
+		console.error("[VTEX] Workflow products error:", error);
+		return null;
+	}
+}