@decocms/apps-vtex 7.2.0

package/src/loaders/logistics.ts

@@ -0,0 +1,111 @@
+/**
+ * VTEX Logistics & Sales-Channel API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/logistics/getSalesChannelById.ts
+ *   vtex/loaders/logistics/listPickupPoints.ts
+ *   vtex/loaders/logistics/listPickupPointsByLocation.ts
+ *   vtex/loaders/logistics/listSalesChannelById.ts  (actually lists all)
+ *   vtex/loaders/logistics/listStockByStore.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api
+ */
+import { vtexFetch } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProductBalance {
+	warehouseId: string;
+	warehouseName: string;
+	totalQuantity: number;
+	reservedQuantity: number;
+	hasUnlimitedQuantity: boolean;
+}
+
+export interface PickupPointsByLocationOpts {
+	geoCoordinates?: number[];
+	postalCode?: string;
+	countryCode?: string;
+}
+
+export interface PickupPointsResponse<T = any> {
+	paging: { page: number; pageSize: number; total: number; pages: number };
+	items: Array<{ distance: number; pickupPoint: T }>;
+}
+
+// ---------------------------------------------------------------------------
+// Sales Channels
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a single sales channel by ID (public API).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/saleschannel/-salesChannelId-
+ */
+export async function getSalesChannelById<T = any>(id: string): Promise<T> {
+	return vtexFetch<T>(`/api/catalog_system/pub/saleschannel/${id}`);
+}
+
+/**
+ * List all sales channels (private API — requires appKey/appToken).
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pvt/saleschannel/list
+ */
+export async function listSalesChannels<T = any>(): Promise<T[]> {
+	return vtexFetch<T[]>("/api/catalog_system/pvt/saleschannel/list");
+}
+
+// ---------------------------------------------------------------------------
+// Pickup Points
+// ---------------------------------------------------------------------------
+
+/**
+ * List all configured pickup points (private API — requires appKey/appToken).
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api#get-/api/logistics/pvt/configuration/pickuppoints
+ */
+export async function listPickupPoints<T = any>(): Promise<T[]> {
+	return vtexFetch<T[]>("/api/logistics/pvt/configuration/pickuppoints");
+}
+
+/**
+ * Search pickup points near a geographic location (public API).
+ * Pass either `geoCoordinates` (lon/lat array) **or** `postalCode` + `countryCode`.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/pickup-points
+ */
+export async function listPickupPointsByLocation<T = any>(
+	opts: PickupPointsByLocationOpts,
+): Promise<PickupPointsResponse<T>> {
+	const params = new URLSearchParams();
+	if (opts.geoCoordinates) {
+		params.set("geoCoordinates", opts.geoCoordinates.join(","));
+	} else {
+		if (opts.postalCode) params.set("postalCode", opts.postalCode);
+		if (opts.countryCode) params.set("countryCode", opts.countryCode);
+	}
+
+	return vtexFetch<PickupPointsResponse<T>>(`/api/checkout/pub/pickup-points?${params}`);
+}
+
+// ---------------------------------------------------------------------------
+// Stock / Inventory
+// ---------------------------------------------------------------------------
+
+/**
+ * List inventory balances for a SKU across all warehouses.
+ * @see https://developers.vtex.com/docs/api-reference/logistics-api#get-/api/logistics/pvt/inventory/skus/-skuId-
+ */
+export async function listStockByStore(skuId: number): Promise<ProductBalance[]> {
+	try {
+		const result = await vtexFetch<{
+			skuId?: string;
+			balance?: ProductBalance[];
+		}>(`/api/logistics/pvt/inventory/skus/${skuId}`);
+
+		return result.balance ?? [];
+	} catch (error) {
+		console.error("[listStockByStore]", error);
+		return [];
+	}
+}

package/src/loaders/minicart.ts

@@ -0,0 +1,78 @@
+/**
+ * SSR loader returning the canonical `Minicart` for the current request.
+ *
+ * Reads `orderFormId` from the `checkout.vtex.com__orderFormId` cookie and
+ * fetches the corresponding OrderForm via `getOrCreateCart`. When no
+ * orderFormId cookie exists (first-time visitor, no items added yet), returns
+ * an empty `Minicart` shell — we deliberately avoid creating a new OrderForm
+ * server-side to prevent zero-item carts on every page view.
+ *
+ * Configurable via Props (free-shipping target, locale, checkout URL).
+ *
+ * @example
+ * ```ts
+ * // setup/commerce-loaders.ts
+ * import minicart from "@decocms/apps/vtex/loaders/minicart";
+ * registerInlineLoader("vtex/loaders/minicart", minicart);
+ * ```
+ */
+
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import type { Minicart } from "@decocms/apps-commerce/types";
+import { getOrCreateCart } from "../actions/checkout";
+import type { OrderForm } from "../types";
+import { vtexOrderFormToMinicart } from "../utils/minicart";
+
+const ORDER_FORM_COOKIE = "checkout.vtex.com__orderFormId";
+
+export interface MinicartProps {
+	/** Free-shipping threshold in major units. `0` disables the progress bar. */
+	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 the UI should expose the coupon input. Default: `true`. */
+	enableCoupon?: boolean;
+}
+
+function readOrderFormIdFromRequest(): string | undefined {
+	const ctx = RequestContext.current;
+	const cookieHeader = ctx?.request.headers.get("cookie");
+	if (!cookieHeader) return undefined;
+	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ORDER_FORM_COOKIE}=([^;]+)`));
+	return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+}
+
+/** Empty cart shell returned when no orderFormId is yet associated with the visitor. */
+function emptyMinicart(opts: MinicartProps): Minicart<OrderForm | null> {
+	return {
+		original: null,
+		storefront: {
+			items: [],
+			subtotal: 0,
+			discounts: 0,
+			total: 0,
+			locale: opts.locale ?? "pt-BR",
+			currency: "BRL",
+			enableCoupon: opts.enableCoupon ?? true,
+			freeShippingTarget: opts.freeShippingTarget ?? 0,
+			checkoutHref: opts.checkoutHref ?? "/checkout",
+		},
+	};
+}
+
+export default async function vtexMinicart(
+	props: MinicartProps = {},
+): Promise<Minicart<OrderForm | null>> {
+	const orderFormId = readOrderFormIdFromRequest();
+	if (!orderFormId) return emptyMinicart(props);
+
+	const orderForm = await getOrCreateCart({ orderFormId });
+	return vtexOrderFormToMinicart(orderForm, {
+		freeShippingTarget: props.freeShippingTarget,
+		locale: props.locale,
+		checkoutHref: props.checkoutHref,
+		enableCoupon: props.enableCoupon,
+	});
+}

package/src/loaders/navbar.ts

@@ -0,0 +1,26 @@
+/**
+ * VTEX Navbar (category tree) loader.
+ * Pure async function — requires configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/navbar.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/category/tree/-categoryLevels-
+ */
+
+import type { SiteNavigationElement } from "@decocms/apps-commerce/types";
+import { vtexFetch } from "../client";
+import { categoryTreeToNavbar } from "../utils/transform";
+import type { Category } from "../utils/types";
+
+/**
+ * Fetch the category tree and transform it into an array of
+ * `SiteNavigationElement` nodes suitable for navigation menus.
+ *
+ * @param levels - Depth of the category tree (default: 2)
+ */
+export async function getNavbar(levels: number = 2): Promise<SiteNavigationElement[]> {
+	const tree = await vtexFetch<Category[]>(`/api/catalog_system/pub/category/tree/${levels}`);
+
+	return categoryTreeToNavbar(tree);
+}

package/src/loaders/orders.ts

@@ -0,0 +1,92 @@
+/**
+ * VTEX Orders API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/orders/getById.ts
+ *   vtex/loaders/orders/list.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api
+ */
+import { vtexFetch } from "../client";
+
+// ---------------------------------------------------------------------------
+// getOrderById (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single user order by its ID.
+ * The user must be authenticated or the caller must have OMS permissions.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders/-orderId-
+ */
+export async function getOrderById<T = any>(orderId: string, authCookie: string): Promise<T> {
+	return vtexFetch<T>(`/api/oms/user/orders/${orderId}`, {
+		headers: { cookie: authCookie },
+	});
+}
+
+// ---------------------------------------------------------------------------
+// listOrders (authenticated — REST)
+// ---------------------------------------------------------------------------
+
+export interface ListOrdersOpts {
+	clientEmail: string;
+	page?: string;
+	perPage?: string;
+}
+
+/**
+ * List orders for a given client e-mail.
+ * The user must be authenticated or the caller must have OMS permissions.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders
+ */
+export async function listOrders<T = any>(opts: ListOrdersOpts, authCookie: string): Promise<T> {
+	const { clientEmail, page = "0", perPage = "15" } = opts;
+	const params = new URLSearchParams({
+		clientEmail,
+		page,
+		per_page: perPage,
+	});
+
+	return vtexFetch<T>(`/api/oms/user/orders?${params}`, {
+		headers: { cookie: authCookie },
+	});
+}
+
+// ---------------------------------------------------------------------------
+// getOrderPlaced (order confirmation — Checkout API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch order details for the order-placed / confirmation page.
+ *
+ * Accepts either:
+ *  - An **order group ID** (no hyphen) → returns all orders in the group
+ *  - A single **order ID** (contains hyphen) → returns that order wrapped in an array
+ *
+ * The caller must supply an `authCookie` containing at least the
+ * VtexIdclientAutCookie, CheckoutDataAccess, and Vtex_CHKO_Auth cookies
+ * that VTEX sets after checkout.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/orderplaced.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orders/order-group/-orderGroupId-
+ */
+export async function getOrderPlaced<T = any>(orderId: string, authCookie: string): Promise<T[]> {
+	const isOrderGroup = !orderId.includes("-");
+
+	if (isOrderGroup) {
+		return vtexFetch<T[]>(`/api/checkout/pub/orders/order-group/${orderId}`, {
+			headers: { cookie: authCookie },
+		});
+	}
+
+	const order = await vtexFetch<T>(`/api/checkout/pub/orders/${orderId}`, {
+		headers: { cookie: authCookie },
+	});
+
+	return [order];
+}

package/src/loaders/pageType.ts

@@ -0,0 +1,68 @@
+/**
+ * VTEX page type resolver.
+ *
+ * Given a URL path, determines if it corresponds to a product, category,
+ * brand, department, collection, search, or 404 in VTEX's catalog.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api#get-/api/catalog_system/pub/portal/pagetype/-path-
+ */
+import { type PageType, vtexFetch } from "../client";
+
+export type { PageType };
+
+export type VtexPageKind =
+	| "product"
+	| "category"
+	| "department"
+	| "subcategory"
+	| "brand"
+	| "collection"
+	| "search"
+	| "fulltext"
+	| "notfound";
+
+/**
+ * Resolve a URL path to a VTEX page type.
+ *
+ * @param urlPath - The path to resolve (e.g., "/shoes/running")
+ * @returns The page type with kind normalization, or null on error
+ */
+export async function resolvePageType(
+	urlPath: string,
+): Promise<{ pageType: PageType; kind: VtexPageKind } | null> {
+	const cleanPath = urlPath.replace(/^\//, "").replace(/\/$/, "");
+	if (!cleanPath) return null;
+
+	try {
+		const pt = await vtexFetch<PageType>(`/api/catalog_system/pub/portal/pagetype/${cleanPath}`);
+
+		const kind = normalizeKind(pt.pageType);
+		return { pageType: pt, kind };
+	} catch {
+		return null;
+	}
+}
+
+function normalizeKind(pageType: PageType["pageType"]): VtexPageKind {
+	switch (pageType) {
+		case "Product":
+			return "product";
+		case "Category":
+			return "category";
+		case "Department":
+			return "department";
+		case "SubCategory":
+			return "subcategory";
+		case "Brand":
+			return "brand";
+		case "Collection":
+		case "Cluster":
+			return "collection";
+		case "Search":
+			return "search";
+		case "FullText":
+			return "fulltext";
+		default:
+			return "notfound";
+	}
+}

package/src/loaders/payment.ts

@@ -0,0 +1,97 @@
+/**
+ * VTEX Payment API loaders.
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/payment/paymentSystems.ts
+ *   vtex/loaders/payment/userPayments.ts
+ */
+import { vtexIOGraphQL } from "../client";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PaymentSystem {
+	name: string;
+	groupName: string;
+	requiresDocument: boolean;
+	displayDocument: boolean;
+	validator: {
+		regex: string | null;
+		mask: string | null;
+		cardCodeMask: string | null;
+		cardCodeRegex: string | null;
+	};
+}
+
+export interface Payment {
+	accountStatus: string | null;
+	cardNumber: string;
+	expirationDate: string;
+	id: string;
+	isExpired: boolean;
+	paymentSystem: string;
+	paymentSystemName: string;
+}
+
+// ---------------------------------------------------------------------------
+// getPaymentSystems (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const PAYMENT_SYSTEMS_QUERY = `query getPaymentSystems {
+  paymentSystems {
+    name
+    groupName
+    requiresDocument
+    displayDocument
+    validator {
+      regex
+      mask
+      cardCodeMask
+      cardCodeRegex
+    }
+  }
+}`;
+
+/**
+ * List available payment systems for the authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getPaymentSystems(authCookie: string): Promise<PaymentSystem[]> {
+	const { paymentSystems } = await vtexIOGraphQL<{
+		paymentSystems: PaymentSystem[];
+	}>({ query: PAYMENT_SYSTEMS_QUERY }, { cookie: authCookie });
+
+	return paymentSystems;
+}
+
+// ---------------------------------------------------------------------------
+// getUserPayments (authenticated — VTEX IO GraphQL)
+// ---------------------------------------------------------------------------
+
+const USER_PAYMENTS_QUERY = `query getUserPayments {
+  profile {
+    payments {
+      accountStatus
+      cardNumber
+      expirationDate
+      id
+      isExpired
+      paymentSystem
+      paymentSystemName
+    }
+  }
+}`;
+
+/**
+ * List saved payment methods for the authenticated user.
+ * Requires a valid VTEX auth cookie.
+ */
+export async function getUserPayments(authCookie: string): Promise<Payment[]> {
+	const data = await vtexIOGraphQL<{
+		profile: { payments: Payment[] } | null;
+	}>({ query: USER_PAYMENTS_QUERY }, { cookie: authCookie });
+
+	return data.profile?.payments ?? [];
+}

package/src/loaders/productListFull.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 type { Product } from "@decocms/apps-commerce/types";
+import { getVtexConfig, intelligentSearch, toFacetPath } from "../client";
+import { pickSku, sortProducts, toProduct } from "../utils/transform";
+import type { Product as ProductVTEX } from "../utils/types";
+
+export interface ProductListProps {
+	props?: CollectionProps | QueryProps | ProductIDProps | FacetsProps;
+}
+
+/** @title Collection ID */
+export interface CollectionProps {
+	/** VTEX product cluster id (e.g. `"150"`). */
+	collection: string;
+	count?: number;
+	sort?: string;
+	hideUnavailableItems?: boolean;
+}
+
+/** @title Keyword Search */
+export interface QueryProps {
+	query: string;
+	count?: number;
+	sort?: string;
+	/** Pass either a raw IS fuzzy value (`"0" | "1" | "auto"`) or call `mapLabelledFuzzyToFuzzy()`. */
+	fuzzy?: string;
+	hideUnavailableItems?: boolean;
+}
+
+/** @title Product IDs */
+export interface ProductIDProps {
+	ids: string[];
+	hideUnavailableItems?: boolean;
+}
+
+/** @title Advanced Facets */
+export interface FacetsProps {
+	query?: string;
+	/** Facets path (e.g. `category-1/moda-feminina/category-2/calcados`). */
+	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;
+	}
+}