@decocms/apps 1.5.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "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",

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

@@ -26,8 +26,8 @@
 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";
+import { vtexOrderFormToMinicart } from "../utils/minicart";
 
 /** Re-exported from `vtex/types` for back-compat. New code should import directly. */
 export type { OrderForm } from "../types";

package/vtex/inline-loaders/minicart.ts

@@ -40,9 +40,7 @@ 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}=([^;]+)`),
-	);
+	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${ORDER_FORM_COOKIE}=([^;]+)`));
 	return match?.[1] ? decodeURIComponent(match[1]) : undefined;
 }
 

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

@@ -109,7 +109,9 @@ export function vtexOrderFormToMinicart(
 	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 shipping = totalizers?.some((t) => t.id === "Shipping")
+		? fromCents(shippingRaw)
+		: undefined;
 	const total = fromCents(orderForm.value);
 
 	const coupon = orderForm.marketingData?.coupon;