@decocms/apps 1.4.1 → 1.6.0

package/commerce/types/commerce.ts

@@ -1096,3 +1096,133 @@ export type AnalyticsEvent =
 	| ViewItemListEvent
 	| ViewPromotionEvent
 	| DecoEvent;
+
+// ---------------------------------------------------------------------------
+// Minicart — platform-agnostic storefront cart contract
+// ---------------------------------------------------------------------------
+//
+// Reconciled superset of presentational shapes used across Deco storefronts.
+// Platform-specific extras (VTEX `attachments`, `seller`, etc.) live as
+// **optional** fields so future platform mappers (Shopify, VNDA, Wake, Linx,
+// Nuvemshop, ...) can populate-or-skip without breaking the contract.
+//
+// Pricing is in **major units** (e.g. `19.90` for R$19.90), not cents. This
+// matches `Intl.NumberFormat` (used by `commerce/sdk/formatPrice`) and lets
+// platform transforms convert from native units once at the boundary.
+//
+// Currently shipped with: VTEX (`vtex/utils/minicart.ts`, `vtex/inline-loaders/minicart.ts`).
+
+/** Free-form attachment payload. Platforms attach customizations or services. */
+export interface MinicartItemAttachment {
+	name: string;
+	content: unknown;
+}
+
+/** Description of an attachment slot offered by the platform for an item. */
+export interface MinicartItemAttachmentOffering {
+	name: string;
+	required: boolean;
+	// biome-ignore lint/suspicious/noExplicitAny: schema is platform-specific
+	schema?: any;
+}
+
+/**
+ * A single line in the minicart.
+ *
+ * Mirrors the fields of `AnalyticsItem` (GA4 contract) so a `MinicartItem` can
+ * be forwarded directly to `add_to_cart` / `view_cart` events. We deliberately
+ * make both `item_id` and `item_name` optional — `AnalyticsItem` enforces
+ * "one or the other" via a discriminated union, which forces consumers to
+ * narrow on every read. Storefront platforms typically populate both, and
+ * sites cast at the GA4 boundary.
+ *
+ * Required:
+ * - `image` — product image URL (storefront-hosted, https).
+ * - `listPrice` — original list price per unit (compare-at), in major units.
+ * - `price` — current selling price per unit, in major units.
+ * - `quantity` — line quantity.
+ *
+ * Optional (platform-specific):
+ * - `seller` — vendor / seller identifier (VTEX, Wake).
+ * - `attachments` — applied customizations (VTEX).
+ * - `attachmentOfferings` — offered customization slots (VTEX).
+ */
+export interface MinicartItem {
+	// --- GA4 analytics fields (compatible with `AnalyticsItem`) ---
+	item_id?: string;
+	item_name?: string;
+	item_brand?: string;
+	item_category?: string;
+	item_category2?: string;
+	item_category3?: string;
+	item_category4?: string;
+	item_category5?: string;
+	item_group_id?: string;
+	item_list_id?: string;
+	item_list_name?: string;
+	item_url?: string;
+	item_variant?: string;
+	affiliation?: string;
+	coupon?: string;
+	discount?: number;
+	index?: number;
+	location_id?: string;
+
+	// --- Cart-required fields ---
+	/** Line quantity. */
+	quantity: number;
+	/** Product image URL (https). */
+	image: string;
+	/** Original list price per unit, in major units. */
+	listPrice: number;
+	/** Selling price per unit, in major units. */
+	price: number;
+
+	// --- Platform-specific (optional) ---
+	/** Vendor / seller identifier (VTEX, Wake). Optional for platforms without sellers. */
+	seller?: string;
+	/** Applied customizations on this line (VTEX attachments). */
+	attachments?: MinicartItemAttachment[];
+	/** Customization slots offered for this line (VTEX). */
+	attachmentOfferings?: MinicartItemAttachmentOffering[];
+}
+
+/**
+ * Storefront-facing minicart. Two views:
+ * - `original` — raw platform cart (VTEX OrderForm, Shopify Cart, ...). Sites use
+ *   this as an escape hatch for platform-specific reads (GTM, pixels, custom
+ *   integrations). Generic param `TRaw` lets callers narrow the type.
+ * - `storefront` — normalized contract every UI consumes.
+ *
+ * All monetary values are in **major units** (decimal), not cents.
+ */
+export interface Minicart<TRaw = unknown> {
+	/** Raw platform cart blob — escape hatch for site-specific reads. */
+	original: TRaw;
+	/** Normalized storefront contract. */
+	storefront: {
+		items: MinicartItem[];
+		/** Total payable, in major units. */
+		total: number;
+		/** Sum of line items before discounts/shipping, in major units. */
+		subtotal: number;
+		/** Total discount applied, in major units. Always non-negative. */
+		discounts: number;
+		/** Shipping cost, in major units. Undefined when not yet calculated. */
+		shipping?: number;
+		/** Applied coupon code, if any. */
+		coupon?: string;
+		/** BCP-47 locale (e.g. `"pt-BR"`). Drives `formatPrice`. */
+		locale: string;
+		/** ISO-4217 currency code (e.g. `"BRL"`). */
+		currency: string;
+		/** Whether the UI should expose the coupon input. */
+		enableCoupon?: boolean;
+		/** Free-shipping threshold in major units. Drives the progress bar. `0` disables it. */
+		freeShippingTarget: number;
+		/** Where the checkout button sends the user. */
+		checkoutHref: string;
+		/** Postal code used for shipping simulation. */
+		postalCode?: string;
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -29,6 +29,7 @@
     "./vtex/types": "./vtex/types.ts",
     "./vtex/actions": "./vtex/actions/index.ts",
     "./vtex/actions/*": "./vtex/actions/*.ts",
+    "./vtex/actions/analytics/*": "./vtex/actions/analytics/*.ts",
     "./vtex/loaders": "./vtex/loaders/index.ts",
     "./vtex/loaders/*": "./vtex/loaders/*.ts",
     "./vtex/utils": "./vtex/utils/index.ts",
@@ -40,6 +41,7 @@
     "./vtex/inline-loaders/productListShelf": "./vtex/inline-loaders/productListShelf.ts",
     "./vtex/inline-loaders/relatedProducts": "./vtex/inline-loaders/relatedProducts.ts",
     "./vtex/inline-loaders/suggestions": "./vtex/inline-loaders/suggestions.ts",
+    "./vtex/inline-loaders/minicart": "./vtex/inline-loaders/minicart.ts",
     "./vtex/hooks": "./vtex/hooks/index.ts",
     "./vtex/hooks/*": "./vtex/hooks/*.ts",
     "./vtex/inline-loaders/workflowProducts": "./vtex/inline-loaders/workflowProducts.ts",

package/vtex/actions/analytics/sendEvent.ts

@@ -0,0 +1,85 @@
+/**
+ * VTEX Intelligent Search analytics event.
+ *
+ * Reads the IS session/anonymous cookies from the incoming request and POSTs
+ * an event to the IS event-api. The configured account is resolved via
+ * {@link getVtexConfig}.
+ *
+ * @see https://developers.vtex.com/docs/api-reference/intelligent-search-api#post-/event-api/v1/-account-/event
+ */
+
+import { getVtexConfig } from "../../client";
+import { ANONYMOUS_COOKIE, SESSION_COOKIE } from "../../utils/intelligentSearch";
+
+export type Props =
+	| {
+			type: "session.ping";
+			url: string;
+	  }
+	| {
+			type: "page.cart";
+			products: { productId: string; quantity: number }[];
+	  }
+	| {
+			type: "page.empty_cart";
+			// Empty array would serialize as an invalid JSON schema, so accept anything.
+			products: unknown;
+	  }
+	| {
+			type: "page.confirmation";
+			order: string;
+			products: { productId: string; quantity: number; price: number }[];
+	  }
+	| {
+			type: "search.click";
+			position: number;
+			text: string;
+			productId: string;
+			url: string;
+	  }
+	| {
+			type: "search.query";
+			url: string;
+			text: string;
+			misspelled: boolean;
+			match: number;
+			operator: string;
+			locale: string;
+	  };
+
+const readCookie = (cookieHeader: string, name: string): string | undefined => {
+	const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${escaped}=([^;]+)`));
+	return match?.[1];
+};
+
+/**
+ * @title Send Analytics Event
+ * @description POST a VTEX Intelligent Search analytics event for the current session.
+ */
+const action = async (props: Props, req: Request): Promise<null> => {
+	const { account } = getVtexConfig();
+	const cookieHeader = req.headers.get("cookie") ?? "";
+	const session = readCookie(cookieHeader, SESSION_COOKIE);
+	const anonymous = readCookie(cookieHeader, ANONYMOUS_COOKIE);
+
+	if (!session || !anonymous) {
+		throw new Error("Missing IS Cookies");
+	}
+
+	const url = `https://sp.vtex.com/event-api/v1/${account}/event`;
+	await fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			...props,
+			session,
+			anonymous,
+			agent: req.headers.get("user-agent") || "deco-sites/apps",
+		}),
+	});
+
+	return null;
+};
+
+export default action;

package/vtex/hooks/useCart.ts

@@ -1,36 +1,43 @@
 /**
  * Client-side cart hook for VTEX.
  *
- * Uses TanStack Query for SWR, optimistic updates, and cache
- * invalidation. Wraps the VTEX orderForm API.
+ * Uses TanStack Query for SWR, optimistic updates, and cache invalidation.
+ * Returns BOTH the raw `OrderForm` (back-compat for existing consumers) AND
+ * the canonical `Minicart` shape (preferred for new code).
  *
- * @example
+ * @example Reading the cart
  * ```tsx
  * import { useCart } from "@decocms/apps/vtex/hooks/useCart";
  *
  * function CartButton() {
- *   const { cart, addItems, isLoading } = useCart();
- *   const count = cart?.items?.length ?? 0;
+ *   const { minicart, isLoading } = useCart({ freeShippingTarget: 200 });
+ *   const count = minicart?.storefront.items.length ?? 0;
  *   return <button disabled={isLoading}>{count} items</button>;
  * }
  * ```
+ *
+ * @example Mutations
+ * ```tsx
+ * const { addItems, removeItem, addCoupons } = useCart();
+ * addItems.mutate([{ id: "123", seller: "1", quantity: 1 }]);
+ * ```
  */
 
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import type { Minicart } from "../../commerce/types/commerce";
+import type { OrderForm, OrderFormItem } from "../types";
+import { vtexOrderFormToMinicart } from "../utils/minicart";
 
-export interface CartItem {
-	id: string;
-	quantity: number;
-	seller: string;
-}
+/** Re-exported from `vtex/types` for back-compat. New code should import directly. */
+export type { OrderForm } from "../types";
 
-export interface OrderForm {
-	orderFormId: string;
-	items: CartItem[];
-	totalizers: Array<{ id: string; name: string; value: number }>;
-	value: number;
-	[key: string]: unknown;
-}
+/**
+ * Slim cart-item shape used by mutations.
+ * @deprecated Use `OrderFormItem` from `@decocms/apps/vtex/types` for full fidelity,
+ *   or `MinicartItem` from `@decocms/apps/commerce/types` for the canonical contract.
+ */
+export type CartItem = Pick<OrderFormItem, "id" | "quantity" | "seller">;
 
 const CART_QUERY_KEY = ["vtex", "cart"] as const;
 
@@ -136,6 +143,14 @@ export interface UseCartOptions {
 	enabled?: boolean;
 	/** Stale time in ms. @default 30000 */
 	staleTime?: number;
+	/** Free-shipping threshold in major units, surfaced on `minicart.storefront`. @default 0 */
+	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 to surface the coupon input. @default true */
+	enableCoupon?: boolean;
 }
 
 export function useCart(options?: UseCartOptions) {
@@ -148,6 +163,24 @@ export function useCart(options?: UseCartOptions) {
 		enabled: options?.enabled !== false,
 	});
 
+	const cart = query.data ?? null;
+
+	const minicart: Minicart<OrderForm> | null = useMemo(() => {
+		if (!cart) return null;
+		return vtexOrderFormToMinicart(cart, {
+			freeShippingTarget: options?.freeShippingTarget,
+			locale: options?.locale,
+			checkoutHref: options?.checkoutHref,
+			enableCoupon: options?.enableCoupon,
+		});
+	}, [
+		cart,
+		options?.freeShippingTarget,
+		options?.locale,
+		options?.checkoutHref,
+		options?.enableCoupon,
+	]);
+
 	const addItems = useMutation({
 		mutationFn: (items: Array<{ id: string; quantity: number; seller: string }>) => {
 			const orderFormId = query.data?.orderFormId;
@@ -193,7 +226,10 @@ export function useCart(options?: UseCartOptions) {
 	});
 
 	return {
-		cart: query.data ?? null,
+		/** Raw VTEX OrderForm — escape hatch for platform-specific reads. */
+		cart,
+		/** Canonical platform-agnostic minicart. Prefer this in new UI code. */
+		minicart,
 		isLoading: query.isLoading,
 		isError: query.isError,
 		error: query.error,
@@ -202,6 +238,6 @@ export function useCart(options?: UseCartOptions) {
 		addCoupons,
 		updateQuantity,
 		removeItem,
-		itemCount: query.data?.items?.length ?? 0,
+		itemCount: cart?.items?.length ?? 0,
 	};
 }

package/vtex/inline-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/inline-loaders/minicart";
+ * registerInlineLoader("vtex/inline-loaders/minicart", minicart);
+ * ```
+ */
+
+import { RequestContext } from "@decocms/start/sdk/requestContext";
+import type { Minicart } from "../../commerce/types/commerce";
+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/vtex/inline-loaders/productList.ts

@@ -20,28 +20,35 @@ export interface ProductListProps {
 	hideUnavailableItems?: boolean;
 }
 
-interface CollectionProps {
+/** @title Collection ID */
+export interface CollectionProps {
+	/** VTEX product cluster id (e.g. `"150"`). */
 	collection: string;
 	count?: number;
 	sort?: string;
 	hideUnavailableItems?: boolean;
 }
 
-interface QueryProps {
+/** @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;
 }
 
-interface ProductIDProps {
+/** @title Product IDs */
+export interface ProductIDProps {
 	ids: string[];
 	hideUnavailableItems?: boolean;
 }
 
-interface FacetsProps {
+/** @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;

package/vtex/inline-loaders/productListingPage.ts

@@ -14,6 +14,33 @@ export interface SelectedFacet {
 	value: string;
 }
 
+/**
+ * Friendly fuzzy labels for CMS UIs. Translate to the raw IS API value via
+ * {@link mapLabelledFuzzyToFuzzy} before passing into a loader's `fuzzy` field.
+ */
+export type LabelledFuzzy = "automatic" | "disabled" | "enabled";
+
+/**
+ * Translate a friendly fuzzy label to the value the VTEX Intelligent Search
+ * API expects. Returns `undefined` when the label is omitted so callers can
+ * skip the param entirely.
+ *
+ * @example
+ *   intelligentSearch({ fuzzy: mapLabelledFuzzyToFuzzy(props.fuzzy) })
+ */
+export const mapLabelledFuzzyToFuzzy = (label?: LabelledFuzzy): "0" | "1" | "auto" | undefined => {
+	switch (label) {
+		case "automatic":
+			return "auto";
+		case "enabled":
+			return "1";
+		case "disabled":
+			return "0";
+		default:
+			return undefined;
+	}
+};
+
 export interface PLPProps {
 	query?: string;
 	count?: number;

package/vtex/loaders/legacy.ts

@@ -305,7 +305,7 @@ const getTerm = (path: string, map: string) => {
 	return mapSegments.includes("priceFrom") ? formatPriceFromPathToFacet(term) : term;
 };
 
-const getFirstItemAvailable = (item: LegacyItem) =>
+export const getFirstItemAvailable = (item: LegacyItem) =>
 	!!item?.sellers?.find((s) => s.commertialOffer?.AvailableQuantity > 0);
 
 const getTermFallback = (url: URL, isPage: boolean, hasFilters: boolean) => {

package/vtex/manifest.gen.ts

@@ -2,6 +2,7 @@
 // This file is checked into source control and updated via: npm run generate:manifests
 
 import * as actions_address from "./actions/address";
+import * as actions_analytics_sendEvent from "./actions/analytics/sendEvent";
 import * as actions_auth from "./actions/auth";
 import * as actions_checkout from "./actions/checkout";
 import * as actions_masterData from "./actions/masterData";
@@ -59,6 +60,7 @@ const manifest = {
 	},
 	actions: {
 		"vtex/actions/address": actions_address,
+		"vtex/actions/analytics/sendEvent": actions_analytics_sendEvent,
 		"vtex/actions/auth": actions_auth,
 		"vtex/actions/checkout": actions_checkout,
 		"vtex/actions/masterData": actions_masterData,

package/vtex/utils/fetch.ts

@@ -0,0 +1,107 @@
+/**
+ * Generic VTEX fetch helpers.
+ *
+ * These are the canonical primitives for ad-hoc VTEX API calls in apps-start
+ * (custom path-resolution loaders, sitemap loaders, custom analytics, etc.).
+ * For typed catalog/IS/checkout calls prefer the {@link import("../client").vtexFetch}
+ * client which is wired into the configured account.
+ *
+ * Provides:
+ *   - {@link fetchSafe} — fetch wrapper that throws {@link HttpError} on non-2xx
+ *   - {@link fetchAPI}  — same, parsed to JSON
+ *
+ * URLs are sanitized for known XSS-prone query params (utm_*, ft, map) before
+ * dispatch. This mirrors the security posture VTEX storefronts carry across
+ * the platform.
+ */
+
+type CachingMode = "stale-while-revalidate";
+
+type DecoInit = {
+	cache: CachingMode;
+	cacheTtlByStatus?: Array<{ from: number; to: number; ttl: number }>;
+};
+
+export type DecoRequestInit = RequestInit & { deco?: DecoInit };
+
+export class HttpError extends Error {
+	readonly status: number;
+	readonly response: Response;
+
+	constructor(response: Response) {
+		super(`HTTP ${response.status} ${response.statusText} — ${response.url}`);
+		this.name = "HttpError";
+		this.status = response.status;
+		this.response = response;
+	}
+}
+
+const removeNonLatin1Chars = (str: string): string =>
+	// eslint-disable-next-line no-control-regex
+	str.replace(/[^\x00-\xFF]/g, "");
+
+const removeScriptChars = (str: string): string => str.replace(/[<>]/g, "");
+
+const QS_TO_REMOVE_PLUS = ["utm_campaign", "utm_medium", "utm_source", "map"];
+const QS_TO_REPLACE_PLUS = ["ft"];
+
+const sanitizeUrl = (input: string | URL | Request): string | Request | URL => {
+	let url: URL;
+
+	if (typeof input === "string") {
+		try {
+			url = new URL(input);
+		} catch {
+			return input;
+		}
+	} else if (input instanceof URL) {
+		url = input;
+	} else {
+		return input;
+	}
+
+	for (const key of QS_TO_REMOVE_PLUS) {
+		if (!url.searchParams.has(key)) continue;
+		const values = url.searchParams.getAll(key);
+		const cleaned = values.map((v) => removeScriptChars(removeNonLatin1Chars(v))).filter(Boolean);
+		url.searchParams.delete(key);
+		for (const v of cleaned) url.searchParams.append(key, v);
+	}
+
+	for (const key of QS_TO_REPLACE_PLUS) {
+		if (!url.searchParams.has(key)) continue;
+		const values = url.searchParams.getAll(key);
+		const cleaned = values.map((v) => encodeURIComponent(v.trim()));
+		url.searchParams.delete(key);
+		for (const v of cleaned) url.searchParams.append(key, v);
+	}
+
+	return url.toString();
+};
+
+/**
+ * Fetch wrapper that throws {@link HttpError} on non-2xx responses and
+ * sanitizes URL query strings.
+ */
+export async function fetchSafe(
+	input: string | URL | Request,
+	init?: DecoRequestInit,
+): Promise<Response> {
+	const sanitized = sanitizeUrl(input);
+	const response = await fetch(sanitized as RequestInfo, init);
+	if (!response.ok) {
+		throw new HttpError(response);
+	}
+	return response;
+}
+
+/**
+ * Fetch wrapper that parses the response as JSON. Throws on non-2xx.
+ */
+export async function fetchAPI<T = unknown>(
+	input: string | URL | Request,
+	init?: DecoRequestInit,
+): Promise<T> {
+	const response = await fetchSafe(input, init);
+	return response.json() as Promise<T>;
+}

package/vtex/utils/minicart.ts

@@ -0,0 +1,139 @@
+/**
+ * Map a VTEX OrderForm to the canonical `Minicart` contract.
+ *
+ * Pure function — no I/O, fully unit-testable. Pricing is converted from
+ * VTEX's native cents to major units (the canonical unit for `Minicart`).
+ *
+ * Locale and currency come from `orderForm.storePreferencesData` and follow
+ * VTEX's `storePreferencesData.countryCode` / `currencyCode` semantics.
+ *
+ * @example
+ * ```ts
+ * import { vtexOrderFormToMinicart } from "@decocms/apps/vtex/utils/minicart";
+ * import { getCart } from "@decocms/apps/vtex/loaders/cart";
+ *
+ * const orderForm = await getCart(orderFormId);
+ * const minicart = vtexOrderFormToMinicart(orderForm, {
+ *   freeShippingTarget: 0,
+ *   checkoutHref: "/checkout",
+ * });
+ * ```
+ */
+
+import type { Minicart, MinicartItem } from "../../commerce/types/commerce";
+import type { OrderForm, OrderFormItem, Totalizer } from "../types";
+
+export interface VtexOrderFormToMinicartOptions {
+	/** Free-shipping threshold in major units. `0` disables the progress bar. */
+	freeShippingTarget?: number;
+	/** Override the OrderForm's `clientPreferencesData.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;
+}
+
+const CENTS_PER_MAJOR = 100;
+
+/** Convert VTEX cents to major units. Always returns a finite number. */
+function fromCents(cents: number | undefined | null): number {
+	if (cents == null || !Number.isFinite(cents)) return 0;
+	return cents / CENTS_PER_MAJOR;
+}
+
+function findTotalizer(totalizers: Totalizer[] | undefined, id: string): number {
+	if (!totalizers) return 0;
+	const t = totalizers.find((x) => x.id === id);
+	return t?.value ?? 0;
+}
+
+/**
+ * Locale heuristic. VTEX exposes `clientPreferencesData.locale` when set, but
+ * otherwise we synthesize one from `storePreferencesData.countryCode` so the UI
+ * always has a usable value for `Intl.NumberFormat`.
+ */
+function inferLocale(orderForm: OrderForm, override?: string): string {
+	if (override) return override;
+	const explicit = orderForm.clientPreferencesData?.locale;
+	if (explicit) return explicit;
+
+	const country = orderForm.storePreferencesData?.countryCode;
+	if (country === "BRA" || country === "BR") return "pt-BR";
+	if (country === "USA" || country === "US") return "en-US";
+	return "en-US";
+}
+
+function vtexItemToMinicartItem(item: OrderFormItem, index: number, coupon?: string): MinicartItem {
+	const sellingPrice = fromCents(item.sellingPrice ?? item.price);
+	const listPrice = fromCents(item.listPrice ?? item.price);
+	const discount = Math.max(0, listPrice - sellingPrice);
+
+	return {
+		// AnalyticsItem identifier — VTEX uses productId; sites map to numeric SKU
+		// when needed via `Number(item.item_id)` (see bagaggio Minicart).
+		item_id: item.id,
+		item_group_id: item.productId,
+		item_name: item.name ?? item.skuName ?? "",
+		item_variant: item.skuName,
+		item_brand: item.additionalInfo?.brandName ?? undefined,
+		item_url: item.detailUrl,
+		coupon,
+		affiliation: item.seller,
+		index,
+		// Cart-required fields
+		image: item.imageUrl?.replace(/^http:/, "https:") ?? "",
+		listPrice,
+		price: sellingPrice,
+		quantity: item.quantity,
+		discount: Number(discount.toFixed(2)),
+		// Platform-specific
+		seller: item.seller,
+		attachments: item.attachments as MinicartItem["attachments"],
+		attachmentOfferings: item.attachmentOfferings as MinicartItem["attachmentOfferings"],
+	};
+}
+
+/**
+ * Map a VTEX `OrderForm` to the canonical platform-agnostic `Minicart`.
+ *
+ * @param orderForm - Result from `getCart()` or `getOrCreateCart()`.
+ * @param opts - Storefront-level overrides (free-shipping target, checkout href, ...).
+ */
+export function vtexOrderFormToMinicart(
+	orderForm: OrderForm,
+	opts: VtexOrderFormToMinicartOptions = {},
+): Minicart<OrderForm> {
+	const totalizers = orderForm.totalizers;
+	const subtotal = fromCents(findTotalizer(totalizers, "Items"));
+	const discountsRaw = findTotalizer(totalizers, "Discounts");
+	const discounts = Math.abs(fromCents(discountsRaw));
+	const shippingRaw = findTotalizer(totalizers, "Shipping");
+	const shipping = totalizers?.some((t) => t.id === "Shipping")
+		? fromCents(shippingRaw)
+		: undefined;
+	const total = fromCents(orderForm.value);
+
+	const coupon = orderForm.marketingData?.coupon;
+	const items = (orderForm.items ?? []).map((item, index) =>
+		vtexItemToMinicartItem(item, index, coupon),
+	);
+
+	return {
+		original: orderForm,
+		storefront: {
+			items,
+			subtotal,
+			discounts,
+			shipping,
+			total,
+			coupon,
+			locale: inferLocale(orderForm, opts.locale),
+			currency: orderForm.storePreferencesData?.currencyCode ?? "BRL",
+			enableCoupon: opts.enableCoupon ?? true,
+			freeShippingTarget: opts.freeShippingTarget ?? 0,
+			checkoutHref: opts.checkoutHref ?? "/checkout",
+			postalCode: orderForm.shippingData?.address?.postalCode ?? undefined,
+		},
+	};
+}