@decocms/apps-vtex 8.1.0-next.0 → 8.1.0-next.2

package/src/utils/fetchCache.ts

@@ -1,55 +0,0 @@
-/**
- * VTEX SWR fetch cache — a thin binding over the shared, instrumented
- * `createFetchCache` in `@decocms/blocks/sdk/fetchCache`.
- *
- * The implementation (in-flight dedup, stale-while-revalidate, stale-if-error,
- * inflight backstop) now lives ONCE in the framework so every commerce app
- * shares it and emits `deco.cache.requests{layer="swr"}` automatically. This
- * module just wires VTEX's tuning constants (`./constants`) and the
- * `provider: "vtex"` label into a single module-level instance, preserving the
- * public surface (`fetchWithCache` / `clearFetchCache` / `getFetchCacheStats` /
- * `FetchCacheOptions`) that `client.ts` and existing tests depend on.
- */
-
-import {
-  createFetchCache,
-  type FetchCacheOptions as SharedFetchCacheOptions,
-} from "@decocms/blocks/sdk/fetchCache";
-import {
-  FETCH_CACHE_FRESH_TTL_MS,
-  FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
-  FETCH_CACHE_MAX_ENTRIES,
-  FETCH_CACHE_STALE_IF_ERROR_MS,
-} from "./constants";
-
-export type FetchCacheOptions = SharedFetchCacheOptions;
-
-const cache = createFetchCache({
-  provider: "vtex",
-  maxEntries: FETCH_CACHE_MAX_ENTRIES,
-  freshTtlMs: FETCH_CACHE_FRESH_TTL_MS,
-  staleIfErrorMs: FETCH_CACHE_STALE_IF_ERROR_MS,
-  inflightBackstopMs: FETCH_CACHE_INFLIGHT_BACKSTOP_MS,
-});
-
-/**
- * Wrap a GET fetch call with SWR caching and in-flight dedup.
- *
- * Returns `null` for non-2xx responses that are cached (e.g. 404).
- * 5xx responses throw so the caller can handle them explicitly.
- */
-export function fetchWithCache<T>(
-  cacheKey: string,
-  doFetch: () => Promise<Response>,
-  opts?: FetchCacheOptions,
-): Promise<T | null> {
-  return cache.fetchWithCache<T>(cacheKey, doFetch, opts);
-}
-
-export function clearFetchCache() {
-  cache.clear();
-}
-
-export function getFetchCacheStats() {
-  return cache.getStats();
-}

package/src/utils/index.ts

@@ -1,19 +0,0 @@
-export type { PersonalDataOptions } from "./accountLoaders";
-export { vtexAccountLoaders } from "./accountLoaders";
-export * from "./batch";
-export * from "./cookies";
-export * from "./enrichment";
-export * from "./fetchCache";
-export * from "./intelligentSearch";
-export * from "./legacy";
-export * from "./pickAndOmit";
-export * from "./proxy";
-export * from "./resourceRange";
-export * from "./segment";
-export * from "./similars";
-export * from "./sitemap";
-export * from "./slugCache";
-export * from "./slugify";
-export * from "./transform";
-export * from "./types";
-export * from "./vtexId";

package/src/utils/instrumentedFetch.ts

@@ -1,98 +0,0 @@
-/**
- * Pre-wired instrumented fetch factory for VTEX.
- *
- * Bundles the three pieces a storefront would otherwise have to wire
- * by hand:
- *
- *   1. The `createInstrumentedFetch` boundary from `@decocms/start`
- *      (spans, traceparent injection, URL redaction, cache-header
- *      span attributes).
- *   2. The `vtexOperationRouter` URL→operation mapping so unannotated
- *      callsites still get semantic span names + histogram labels.
- *   3. An `onComplete` callback that records every call into the
- *      canonical `http.client.request.duration` histogram via the
- *      framework's `recordCommerceMetric(...)` helper in
- *      `@decocms/start/sdk/observability` — `provider`, `operation`,
- *      `status_class`, and `cached` labels.
- *
- * Sites opt in once at startup:
- *
- *   ```ts
- *   import { setVtexFetch } from "@decocms/apps/vtex";
- *   import { createVtexFetch } from "@decocms/apps/vtex";
- *
- *   setVtexFetch(createVtexFetch());
- *   ```
- *
- * Sites that need to wrap a custom underlying fetch (cookie passthrough,
- * proxy, retry, etc.) pass it as `baseFetch`. The instrumentation
- * still applies — `createInstrumentedFetch` preserves the wrapped
- * behavior.
- */
-
-import type { FetchFn } from "@decocms/blocks/sdk/fetchTimeout";
-import {
-  createInstrumentedFetch,
-  type InstrumentedFetch,
-} from "@decocms/blocks/sdk/instrumentedFetch";
-import { recordCommerceMetric, statusClassFor } from "@decocms/blocks/sdk/observability";
-import { vtexOperationRouter } from "./operationRouter";
-import { createResilientFetch, type ResilienceConfig } from "./resilience";
-
-export interface CreateVtexFetchOptions {
-  /**
-   * Underlying fetch to wrap. Defaults to `globalThis.fetch`.
-   * Pass an existing custom fetch (e.g. one that injects auth cookies
-   * or routes through a proxy) to preserve its behavior while adding
-   * the VTEX instrumentation layer on top.
-   */
-  baseFetch?: FetchFn;
-  /**
-   * Disable the `http.client.request.duration` histogram emission for
-   * VTEX calls. The framework's span and structured logs still emit.
-   * Useful when the consumer wants to record its own histogram with a
-   * custom shape. Default: false.
-   */
-  disableHistogram?: boolean;
-  /**
-   * Resilience layer (real abort/timeout + per-host circuit breaker +
-   * idempotent-only retry with a budget). ON by default so every VTEX
-   * consumer is protected against upstream slowness/outages without
-   * per-site wiring. Pass a partial config to tune, `false` to opt out,
-   * or flip the `VTEX_RESILIENCE_DISABLED=true` env var as a runtime
-   * kill-switch. See {@link createResilientFetch}.
-   */
-  resilience?: Partial<ResilienceConfig> | false;
-}
-
-/**
- * Construct a pre-wired VTEX `InstrumentedFetch`. Pass the result to
- * `setVtexFetch(...)`. See module docstring for details.
- */
-export function createVtexFetch(options: CreateVtexFetchOptions = {}): InstrumentedFetch {
-  const { baseFetch, disableHistogram = false, resilience } = options;
-  // Compose the resilience layer UNDER the instrumentation so spans/histograms
-  // see the real outcome (including breaker fast-fails and timeouts). A single
-  // instrumented call = one logical request, which may span several underlying
-  // attempts. Covers every VTEX egress path — cached GETs, IS, and checkout
-  // POSTs — because they all funnel through this one fetch.
-  const resilientBase =
-    resilience === false
-      ? baseFetch
-      : createResilientFetch(baseFetch ?? globalThis.fetch, resilience ?? {});
-  return createInstrumentedFetch({
-    name: "vtex",
-    baseFetch: resilientBase,
-    resolveOperation: vtexOperationRouter,
-    onComplete: disableHistogram
-      ? undefined
-      : ({ operation, status, durationMs, cached }) => {
-          recordCommerceMetric(durationMs, {
-            provider: "vtex",
-            operation,
-            status_class: statusClassFor(status),
-            cached,
-          });
-        },
-  });
-}

package/src/utils/intelligentSearch.ts

@@ -1,96 +0,0 @@
-import { vtexFetch } from "../client";
-import type { PageType, SelectedFacet, SimulationBehavior, Sort } from "./types";
-
-export const SESSION_COOKIE = "vtex_is_session";
-export const ANONYMOUS_COOKIE = "vtex_is_anonymous";
-
-export const withDefaultFacets = (allFacets: readonly SelectedFacet[]) => {
-	return [...allFacets];
-};
-
-export const toPath = (facets: SelectedFacet[]) =>
-	facets.map(({ key, value }) => (key ? `${key}/${value}` : value)).join("/");
-
-interface Params {
-	query: string;
-	page: number;
-	count: number;
-	sort: Sort;
-	fuzzy: string;
-	locale: string;
-	hideUnavailableItems: boolean;
-	simulationBehavior: SimulationBehavior;
-}
-
-export const withDefaultParams = ({
-	query = "",
-	page = 0,
-	count = 12,
-	sort = "",
-	fuzzy = "auto",
-	locale = "pt-BR",
-	hideUnavailableItems,
-	simulationBehavior = "default",
-}: Partial<Params>) => ({
-	page: page + 1,
-	count,
-	query,
-	sort,
-	...(fuzzy ? { fuzzy } : {}),
-	locale,
-	hideUnavailableItems: hideUnavailableItems ?? false,
-	simulationBehavior,
-});
-
-export const isFilterParam = (keyFilter: string): boolean => keyFilter.startsWith("filter.");
-
-/**
- * Valid VTEX Intelligent Search sort values.
- * Anything else (e.g. "orders:desc)" with a trailing paren from legacy URLs)
- * causes IS API to return 400.
- */
-export const VALID_IS_SORTS = new Set([
-	"",
-	"orders:desc",
-	"price:asc",
-	"price:desc",
-	"name:asc",
-	"name:desc",
-	"release:desc",
-	"discount:desc",
-]);
-
-/** Sanitize an IS sort parameter — returns empty string for invalid values. */
-export function sanitizeISSort(sort: string): string {
-	return VALID_IS_SORTS.has(sort) ? sort : "";
-}
-
-const segmentsFromTerm = (term: string) => term.split("/").filter(Boolean);
-
-const segmentsFromSearchParams = (url: string) => {
-	const searchParams = new URLSearchParams(url).entries();
-
-	const categories = Array.from(searchParams)
-		.sort()
-		.reduce((acc, [key, value]) => {
-			if (key.includes("filter.category")) {
-				acc.push(value);
-			}
-
-			return acc;
-		}, [] as string[]);
-
-	return categories.length ? categories : segmentsFromTerm(url);
-};
-
-export const pageTypesFromUrl = async (url: string): Promise<PageType[]> => {
-	const segments = segmentsFromSearchParams(url);
-
-	return await Promise.all(
-		segments.map((_, index) =>
-			vtexFetch<PageType>(
-				`/api/catalog_system/pub/portal/pagetype/${segments.slice(0, index + 1).join("/")}`,
-			),
-		),
-	);
-};

package/src/utils/legacy.ts

@@ -1,139 +0,0 @@
-import type { Seo } from "@decocms/apps-commerce/types";
-import { vtexFetch } from "../client";
-import type { WrappedSegment } from "./segment";
-import { slugify } from "./slugify";
-import type { PageType } from "./types";
-
-const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
-
-export const toSegmentParams = ({ payload: segment }: WrappedSegment) =>
-	Object.fromEntries(
-		Object.entries({
-			utmi_campaign: segment.utmi_campaign ?? undefined,
-			utm_campaign: segment.utm_campaign ?? undefined,
-			utm_source: segment.utm_source ?? undefined,
-			sc: segment.channel ?? undefined,
-		}).filter(([_, v]) => v !== undefined),
-	);
-
-const PAGE_TYPE_TO_MAP_PARAM = {
-	Brand: "b",
-	Category: "c",
-	Department: "c",
-	SubCategory: "c",
-	Collection: "productClusterIds",
-	Cluster: "productClusterIds",
-	Search: "ft",
-	FullText: "ft",
-	Product: "p",
-	NotFound: null,
-};
-
-const segmentsFromTerm = (term: string) => term.split("/").filter(Boolean);
-
-export const getValidTypesFromPageTypes = (pagetypes: PageType[]) => {
-	return pagetypes.filter((type) => PAGE_TYPE_TO_MAP_PARAM[type.pageType]);
-};
-
-export const pageTypesFromPathname = async (term: string): Promise<PageType[]> => {
-	const segments = segmentsFromTerm(term);
-
-	return await Promise.all(
-		segments.map((_, index) =>
-			vtexFetch<PageType>(
-				`/api/catalog_system/pub/portal/pagetype/${segments.slice(0, index + 1).join("/")}`,
-			),
-		),
-	);
-};
-
-export const getMapAndTerm = (pageTypes: PageType[]) => {
-	const term = pageTypes
-		.map((type, index) =>
-			type.url ? segmentsFromTerm(new URL(`http://${type.url}`).pathname)[index] : null,
-		)
-		.filter(Boolean)
-		.join("/");
-
-	const map = pageTypes
-		.map((type) => PAGE_TYPE_TO_MAP_PARAM[type.pageType])
-		.filter(Boolean)
-		.join(",");
-
-	if (map === "ft" && term === "s") {
-		return ["", ""];
-	}
-
-	return [map, term];
-};
-
-export const pageTypesToBreadcrumbList = (pages: PageType[], baseUrl: string) => {
-	const filteredPages = pages.filter(
-		({ pageType }) =>
-			pageType === "Category" || pageType === "Department" || pageType === "SubCategory",
-	);
-
-	return filteredPages.map((page, index) => {
-		const position = index + 1;
-		const slug = filteredPages.slice(0, position).map((x) => slugify(x.name!));
-
-		return {
-			"@type": "ListItem" as const,
-			name: page.name!,
-			item: new URL(`/${slug.join("/")}`, baseUrl).href,
-			position,
-		};
-	});
-};
-
-export const pageTypesToSeo = (
-	pages: PageType[],
-	baseUrl: string,
-	currentPage?: number,
-): Seo | null => {
-	const current = pages.at(-1);
-	const url = new URL(baseUrl);
-	const fullTextSearch = url.searchParams.get("q");
-	const hasMapTermOrSkuId = !!(url.searchParams.get("map") || url.searchParams.get("skuId"));
-
-	if (
-		(!current || current.pageType === "Search" || current.pageType === "FullText") &&
-		fullTextSearch
-	) {
-		return {
-			title: capitalize(fullTextSearch),
-			description: capitalize(fullTextSearch),
-			canonical: url.href,
-			noIndexing: hasMapTermOrSkuId,
-		};
-	}
-
-	if (!current) {
-		return null;
-	}
-
-	return {
-		title: current.title || current.name || "",
-		description: current.metaTagDescription!,
-		noIndexing: hasMapTermOrSkuId,
-		canonical: toCanonical(
-			new URL(
-				current.url && current.pageType !== "Collection"
-					? current.url.replace(/^[^/]*\//, "/").toLowerCase()
-					: url,
-				url,
-			),
-			currentPage,
-		),
-	};
-};
-
-function toCanonical(url: URL, page?: number) {
-	if (typeof page === "number") {
-		url.searchParams.set("page", `${page}`);
-	}
-
-	return url.href;
-}
-
-export { isFilterParam } from "./intelligentSearch";

package/src/utils/minicart.ts

@@ -1,139 +0,0 @@
-/**
- * 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 "@decocms/apps-commerce/types";
-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 a production 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,
-		},
-	};
-}

package/src/utils/pickAndOmit.ts

@@ -1,25 +0,0 @@
-export function pick<T extends object, K extends keyof T = keyof T>(
-	keys: K[],
-	obj: T | null | undefined,
-): Pick<T, K> | null {
-	if (!keys.length || !obj) {
-		return null;
-	}
-
-	const entries = keys.map((key) => [key, obj[key]]);
-
-	return Object.fromEntries(entries);
-}
-
-export function omit<T extends object, K extends keyof T>(
-	keys: K[],
-	obj: T | null | undefined,
-): Omit<T, K> | null {
-	if (!keys.length || !obj) {
-		return null;
-	}
-
-	const pickedKeys = (Object.keys(obj) as K[]).filter((key) => !keys.includes(key));
-
-	return pick(pickedKeys, obj) as unknown as Omit<T, K>;
-}