@decocms/apps 1.4.0 → 1.5.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.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -40,6 +40,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",
@@ -95,6 +96,7 @@
     "vtex/",
     "resend/",
     "website/",
+    "registry.ts",
     "!**/__tests__/",
     "!scripts/"
   ],

package/registry.ts

@@ -0,0 +1,59 @@
+/**
+ * Declarative catalogue of installable apps published under `@decocms/apps`.
+ *
+ * `@decocms/start`'s `autoconfigApps()` consumes this array to wire CMS
+ * commerce loaders and admin invoke handlers for whichever apps the host
+ * site has configured in its decofile. New apps are added here — no edit
+ * to the framework or the site is required.
+ *
+ * Import path: `@decocms/apps/registry`
+ *
+ * NOTE: the type is inlined rather than imported from
+ * `@decocms/start/apps` so this file ships in `@decocms/apps@1.4.0`
+ * against any installed `@decocms/start` version. Once callers pin a
+ * start version that exposes `AppRegistry`, the type can be swapped.
+ */
+
+interface AppRegistryEntry {
+	/** Block key in the decofile, e.g. "deco-shopify". */
+	blockKey: string;
+	/** Lazy dynamic import of the app's mod module. */
+	module: () => Promise<any>;
+	/** Human-readable name shown in admin install UI. */
+	displayName?: string;
+	/** Icon URL (absolute or site-relative) shown in admin install UI. */
+	icon?: string;
+	/** Grouping label, e.g. "commerce", "email", "analytics". */
+	category?: string;
+	/** Short summary shown in admin install UI. */
+	description?: string;
+}
+
+type AppRegistry = readonly AppRegistryEntry[];
+
+export const APP_REGISTRY: AppRegistry = [
+	{
+		blockKey: "deco-shopify",
+		module: () => import("./shopify/mod"),
+		displayName: "Shopify",
+		category: "commerce",
+		description: "Shopify Storefront API commerce integration",
+	},
+	{
+		blockKey: "deco-vtex",
+		module: () => import("./vtex/mod"),
+		displayName: "VTEX",
+		category: "commerce",
+		description: "VTEX IO commerce integration",
+	},
+	{
+		blockKey: "deco-resend",
+		module: () => import("./resend/mod"),
+		displayName: "Resend",
+		category: "email",
+		description: "Transactional email via Resend",
+	},
+];
+
+export default APP_REGISTRY;
+export type { AppRegistryEntry, AppRegistry };

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 { vtexOrderFormToMinicart } from "../utils/minicart";
+import type { OrderForm, OrderFormItem } from "../types";
 
-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,80 @@
+/**
+ * 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/utils/minicart.ts

@@ -0,0 +1,137 @@
+/**
+ * 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,
+		},
+	};
+}