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

package/src/utils/transform.ts

@@ -20,6 +20,7 @@ import type {
 	SiteNavigationElement,
 	UnitPriceSpecification,
 } from "@decocms/apps-commerce/types";
+import { bestInstallment } from "@decocms/apps-commerce/sdk/useOffer";
 import { DEFAULT_IMAGE } from "@decocms/apps-commerce/utils/constants";
 import { formatRange } from "@decocms/apps-commerce/utils/filters";
 import { pick } from "./pickAndOmit";
@@ -98,7 +99,7 @@ const getProductURL = (origin: string, product: { linkText: string }, skuId?: st
 const nonEmptyArray = <T>(array: T[] | null | undefined) =>
 	Array.isArray(array) && array.length > 0 ? array : null;
 
-interface ProductOptions {
+export interface ProductOptions {
 	baseUrl: string;
 	/** Price coded currency, e.g.: USD, BRL */
 	priceCurrency: string;
@@ -107,14 +108,121 @@ interface ProductOptions {
 	includeOriginalAttributes?: string[];
 	/** Use lean toProductVariant for hasVariant[] instead of full toProduct at level=1 */
 	leanVariants?: boolean;
+	/**
+	 * With `leanVariants`, keep the payment ladder on the ONE variant the card
+	 * actually renders. Receives the raw SKU list and returns that SKU's
+	 * `itemId` (or undefined to leave every variant lean).
+	 *
+	 * Why this exists: `leanVariants` assumes the card renders the ROOT sku, so
+	 * `buildOfferVariant` empties `priceSpecification` on every entry. Cards that
+	 * instead pick a representative variant out of `isVariantOf.hasVariant` (e.g.
+	 * "cheapest in stock") read that variant's own offer for list price and
+	 * installments — with the ladder emptied, those render blank.
+	 *
+	 * The kept entry stays on the LEAN variant shape and only its offer is
+	 * upgraded, to {@link buildOfferShelf} (ListPrice/SalePrice/SRP + PIX + the
+	 * one installment `useOffer` would pick). A full `toProduct` here would
+	 * instead re-emit `description` and the whole 48-entry ladder the parent
+	 * already carries: measured on a real listing, 17.5 KB of the 53.5 KB in
+	 * every product, for a card that reads price and installment only.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	displayedVariantId?: (items: Array<LegacySkuVTEX | SkuVTEX>) => string | undefined;
+	/**
+	 * Rewrite `priceSpecification` on the offers this transform emits. Runs on
+	 * the ROOT offer and on the offer of the variant `displayedVariantId` picks.
+	 *
+	 * A listing renders ONE installment string per card, while the Catalog API
+	 * returns every payment method the store accepts: measured on a real page,
+	 * 48 `UnitPriceSpecification` entries = 12.0 KB per product, 22% of the
+	 * listing payload — built, cached and re-serialized in full.
+	 *
+	 * Deliberately a caller-supplied function and not a boolean: WHICH rungs a
+	 * card reads is store policy, not ours. {@link buildOfferShelf} keeps the
+	 * `bestInstallment` one (lowest total, tie-broken by highest
+	 * `billingDuration`) — and on a store with a boleto discount that resolves to
+	 * "Boleto Bancário 1x", measured against a storefront that renders
+	 * "Visa 10x" on all 36 cards of the page. Same data, different string. Pass
+	 * `(specs) => [buildOfferShelf({ ...offer, priceSpecification: specs }).…]`-style
+	 * logic, or your own predicate; the transform only applies it.
+	 *
+	 * Undefined (default) keeps the full ladder — a PDP needs it.
+	 */
+	priceSpecifications?: (specs: UnitPriceSpecification[]) => UnitPriceSpecification[];
+	/**
+	 * Internal: set by `toProduct`/`toProductShelf` on the ONE variant
+	 * `displayedVariantId` picked, so `toProductVariant` emits a real ladder for
+	 * it instead of `buildOfferVariant`'s empty one. Not meant for callers.
+	 */
+	variantKeepLadder?: boolean;
+	/**
+	 * Cap `image[]` to the first N entries, in path order. Undefined (default)
+	 * keeps every image.
+	 *
+	 * Listings render at most a couple of images per card, while the Catalog API
+	 * returns every asset registered on the SKU (3 on average, up to 5 measured).
+	 *
+	 * NOTE: this truncates by POSITION, so images the consumer selects BY NAME
+	 * can fall outside the cap. Measured on a real listing page: the `vira`
+	 * (hover) image sits at index 1 in only 5 of the 19 products that have one —
+	 * index 2 in 12 of them, index 3 in 2. A cap of 2 therefore drops the hover
+	 * image on most cards that use one. Callers that select by name should keep
+	 * the named entries through {@link keepImageNames}.
+	 */
+	maxImages?: number;
+	/**
+	 * `imageLabel`s that survive the positional cap. An image whose label is
+	 * listed here is kept even when it falls outside {@link maxImages} (and
+	 * outside the shelf transform's own default cap), in its original order.
+	 *
+	 * This is the escape hatch the `maxImages` note asks for. A storefront that
+	 * picks the card image BY NAME — a "still"/packshot asset, a colour
+	 * thumbnail — cannot use a positional cap on its own: those assets are
+	 * registered last on the SKU, so any cap drops them and the card silently
+	 * falls back to the first photo. Pass the labels the card selects and the
+	 * payload stays lean everywhere else.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	keepImageNames?: string[];
 	/** Property names to keep on lean variant additionalProperty. Defaults to VARIANT_PROPERTY_NAMES. */
 	variantPropertyNames?: Set<string>;
 	/** When leanVariants is true, still include image[0] on each variant entry. Default true. */
 	variantIncludeImage?: boolean;
 	/** When leanVariants is true, still include inventoryLevel on each variant offer. Default true. */
 	variantIncludeInventory?: boolean;
+	/**
+	 * Shelf: include every SKU as a lean variant in isVariantOf.hasVariant[] (via
+	 * toProductVariant) instead of a single in-stock one. Lets shelf cards render
+	 * the full size/color grid without pulling the heavy toProduct payload.
+	 * Default false — preserves the lean single-variant shelf other sites rely on.
+	 */
+	shelfCompleteVariants?: boolean;
 }
 
+/**
+ * Apply the positional image cap, then add back the entries the caller selects
+ * by name. Order is preserved: the capped head first, then the named tail in
+ * catalog order. No cap means no work.
+ */
+const capImages = <I extends { imageLabel?: string | null }>(
+	images: I[] | null | undefined,
+	maxImages: number | undefined,
+	keepImageNames: string[] | undefined,
+): I[] | null | undefined => {
+	if (!images || typeof maxImages !== "number") return images;
+
+	const capped = images.slice(0, maxImages);
+
+	if (!keepImageNames?.length) return capped;
+
+	const keep = new Set(keepImageNames);
+	const named = images.slice(maxImages).filter((image) => keep.has(image.imageLabel ?? ""));
+
+	return named.length > 0 ? [...capped, ...named] : capped;
+};
+
 /** Returns first available sku */
 const findFirstAvailable = (items: Array<LegacySkuVTEX | SkuVTEX>) =>
 	items?.find((item) =>
@@ -388,17 +496,31 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 		: toAdditionalProperties(sku);
 	const referenceIdAdditionalProperty = toAdditionalPropertyReferenceIds(referenceId);
 	const images = nonEmptyArray(sku.images);
-	const offers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
-
-	const variantOptions =
-		imagesByKey !== options.imagesByKey ? { ...options, imagesByKey } : options;
+	const rawOffers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
+	const offers = applyPriceSpecifications(rawOffers, options);
+
+	// `variantKeepLadder` must NOT be inherited: while it leaked through, every
+	// lean variant emitted a ladder instead of an empty one — measured on a real
+	// listing, `isVariantOf` GREW from 38.6 KB to 49.6 KB, so the option made
+	// the payload bigger. Only the entry `displayedVariantId` picks turns it on,
+	// explicitly, below.
+	const variantOptions = { ...options, imagesByKey, variantKeepLadder: false };
 	const isVariantOf =
 		level < 1
 			? ({
 					"@type": "ProductGroup",
 					productGroupID: productId,
 					hasVariant: options.leanVariants
-						? items.map((sku) => toProductVariant(product, sku, variantOptions))
+						? ((keepId) =>
+								items.map((sku) =>
+									toProductVariant(
+										product,
+										sku,
+										keepId !== undefined && sku.itemId === keepId
+											? { ...variantOptions, variantKeepLadder: true }
+											: variantOptions,
+									),
+								))(options.displayedVariantId?.(items))
 						: items.map((sku) => toProduct(product, sku, 1, variantOptions)),
 					url: getProductGroupURL(baseUrl, product).href,
 					name: product.productName,
@@ -410,7 +532,8 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 				} satisfies ProductGroup)
 			: undefined;
 
-	const finalImages = images?.map(({ imageUrl, imageText, imageLabel }) => {
+	const cappedImages = capImages(images, options.maxImages, options.keepImageNames);
+	const finalImages = cappedImages?.map(({ imageUrl, imageText, imageLabel }) => {
 		const url = imagesByKey.get(getImageKey(imageUrl)) ?? imageUrl;
 		const alternateName = imageText || imageLabel || "";
 		const name = imageLabel || "";
@@ -502,61 +625,48 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 	};
 };
 
-/**
- * Determines if an installment has no interest by checking if
- * billingDuration * billingIncrement ≈ total price (within 1 cent tolerance).
- */
-const isNoInterest = (spec: UnitPriceSpecification): boolean => {
-	if (spec.billingDuration == null || spec.billingIncrement == null || spec.price == null) {
-		return false;
-	}
-	return Math.abs(spec.billingDuration * spec.billingIncrement - spec.price) < 0.01;
-};
-
 /**
  * Build a lean offer for shelf display. Keeps only:
  * - ListPrice, SalePrice, SRP price types
  * - PIX installment (name?.toUpperCase() === "PIX")
- * - Best no-interest installment (highest billingDuration)
+ * - Best installment, chosen with the SAME `bestInstallment` heuristic `useOffer`
+ *   applies on PLP/PDP (lowest total price, tie-broken by highest billingDuration).
+ *   Reusing it means shelf cards and detail pages always show the same installment.
  * Drops: inventoryLevel, giftSkuIds, priceValidUntil
  */
-const buildOfferShelf = (offer: Offer): Offer => {
+export const buildOfferShelf = (offer: Offer): Offer => {
 	const leanSpecs: UnitPriceSpecification[] = [];
-
-	let bestNoInterest: UnitPriceSpecification | null = null;
+	const installmentSpecs: UnitPriceSpecification[] = [];
 
 	for (const spec of offer.priceSpecification ?? []) {
-		// Keep base price types
+		// Keep base (non-installment) price types
 		if (
-			spec.priceType === SCHEMA_LIST_PRICE ||
-			spec.priceType === SCHEMA_SALE_PRICE ||
-			spec.priceType === SCHEMA_SRP
+			(spec.priceType === SCHEMA_LIST_PRICE ||
+				spec.priceType === SCHEMA_SALE_PRICE ||
+				spec.priceType === SCHEMA_SRP) &&
+			spec.priceComponentType !== SCHEMA_INSTALLMENT
 		) {
-			if (spec.priceComponentType !== SCHEMA_INSTALLMENT) {
-				leanSpecs.push(spec);
-				continue;
-			}
+			leanSpecs.push(spec);
+			continue;
 		}
 
-		// Keep PIX installment
+		// Keep PIX installment (also feeds the bestInstallment reducer below via leanSpecs)
 		if (spec.priceComponentType === SCHEMA_INSTALLMENT && spec.name?.toUpperCase() === "PIX") {
 			leanSpecs.push(spec);
 			continue;
 		}
 
-		// Track best no-interest installment (highest billingDuration)
-		if (
-			spec.priceComponentType === SCHEMA_INSTALLMENT &&
-			isNoInterest(spec) &&
-			(bestNoInterest == null ||
-				(spec.billingDuration ?? 0) > (bestNoInterest.billingDuration ?? 0))
-		) {
-			bestNoInterest = spec;
+		if (spec.priceComponentType === SCHEMA_INSTALLMENT) {
+			installmentSpecs.push(spec);
 		}
 	}
 
-	if (bestNoInterest) {
-		leanSpecs.push(bestNoInterest);
+	// Keep the single installment useOffer would pick from the full list. PIX is kept
+	// separately above, so useOffer on the lean offer still reduces over {PIX, best}
+	// and matches the detail page's reduce over the full set.
+	const best = installmentSpecs.reduce(bestInstallment, null as UnitPriceSpecification | null);
+	if (best) {
+		leanSpecs.push(best);
 	}
 
 	return {
@@ -572,6 +682,22 @@ const buildOfferShelf = (offer: Offer): Offer => {
 	};
 };
 
+/**
+ * Apply `options.priceSpecifications` to every offer, if the caller supplied it.
+ * Identity (same array reference) when absent, so the default output is
+ * byte-for-byte unchanged.
+ */
+const applyPriceSpecifications = (offers: Offer[], options: ProductOptions): Offer[] =>
+	options.priceSpecifications
+		? offers.map((offer) => ({
+				...offer,
+				priceSpecification: options.priceSpecifications!(offer.priceSpecification ?? []),
+			}))
+		: offers;
+
+/** Default positional image cap for the shelf transform (front + back). */
+const SHELF_MAX_IMAGES = 2;
+
 /** Property names commonly used by ProductCard/Shelf components */
 const SHELF_PROPERTY_NAMES = new Set([
 	"category",
@@ -587,11 +713,12 @@ const SHELF_PROPERTY_NAMES = new Set([
  * Lean product transform for shelf/card display. Same signature as toProduct().
  *
  * Differences from toProduct():
- * - Images: capped at 2 per SKU (front + back)
+ * - Images: capped at 2 per SKU (front + back), overridable via `maxImages`;
+ *   `keepImageNames` adds back labelled assets that fall outside the cap
  * - Offers: best seller only (in-stock first, then cheapest), stripped installments (keeps ListPrice, SalePrice, SRP, PIX, best no-interest)
  * - isVariantOf: single in-stock variant at level 0
  * - additionalProperty: filtered to known-used property names
- * - Drops: description, video, isAccessoryOrSparePartFor, alternateName, gtin, releaseDate, model
+ * - Drops: description, video, isAccessoryOrSparePartFor, alternateName, gtin, releaseDate
  */
 export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 	product: P,
@@ -600,12 +727,14 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 	options: ProductOptions,
 ): Product => {
 	const { baseUrl, priceCurrency } = options;
-	const { productId, items } = product;
+	const { productId, items, productReference } = product;
 	const { name, itemId: skuId } = sku;
 
-	// Images: cap at 2
+	// Images: cap at 2, keeping any label the caller selects by name
 	const rawImages = nonEmptyArray(sku.images);
-	const mappedImages = (rawImages ?? []).slice(0, 2).map(({ imageUrl, imageText, imageLabel }) => ({
+	const cappedImages =
+		capImages(rawImages, options.maxImages ?? SHELF_MAX_IMAGES, options.keepImageNames) ?? [];
+	const mappedImages = cappedImages.map(({ imageUrl, imageText, imageLabel }) => ({
 		"@type": "ImageObject" as const,
 		alternateName: imageText || imageLabel || "",
 		url: imageUrl,
@@ -649,17 +778,38 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 		level < 1
 			? (() => {
 					const inStockSku = findFirstAvailable(items) ?? items[0];
-					const singleVariant = inStockSku ? [toProductShelf(product, inStockSku, 1, options)] : [];
+					// Opt-in: every SKU as a lean variant (size/color grid on shelf cards).
+					// Default: a single in-stock variant (lean shelf payload).
+					const keepId = options.displayedVariantId?.(items);
+					const hasVariant = options.shelfCompleteVariants
+						? items.map((variantSku) =>
+								toProductVariant(
+									product,
+									variantSku,
+									keepId !== undefined && variantSku.itemId === keepId
+										? { ...options, variantKeepLadder: true }
+										: options,
+								),
+							)
+						: inStockSku
+							? [toProductShelf(product, inStockSku, 1, options)]
+							: [];
 					return {
 						"@type": "ProductGroup" as const,
 						productGroupID: productId,
-						hasVariant: singleVariant,
+						hasVariant,
 						url: getProductGroupURL(baseUrl, product).href,
 						name: product.productName,
 						// Carry the shelf-safe group specs (incl. "Campanha") so ProductCard
 						// flags that read isVariantOf.additionalProperty (e.g. ReleaseFlag ->
 						// "Lançamento") still fire on shelf/carousel cards.
 						additionalProperty: groupAdditionalProperty,
+						// The product reference (VTEX `productReference`). Analytics reads it
+						// off `isVariantOf.model` — GA4 `dimension1` on view_item_list /
+						// select_item, and the equivalent on productImpression /
+						// productClick. Dropping it silently blanked that dimension on every
+						// shelf, PLP and search result. One short string per product.
+						model: productReference,
 					} satisfies ProductGroup;
 				})()
 			: undefined;
@@ -726,19 +876,38 @@ export const toProductVariant = <P extends LegacyProductVTEX | ProductVTEX>(
 	const includeImage = options.variantIncludeImage !== false;
 	const includeInventory = options.variantIncludeInventory !== false;
 
-	// additionalProperty: only variant-differentiating specs
+	// additionalProperty: variant-differentiating specs, plus the SKU reference
+	// ids. Analytics reads the SKU's `RefId` off this list — GA4 `dimension2` on
+	// view_item_list / select_item, and the equivalent on productImpression /
+	// productClick. It lives in `referenceId`, not in `variations`, so the
+	// `variantProps` filter dropped it and blanked that dimension on every shelf
+	// card rendered with `shelfCompleteVariants`. One short string per SKU.
 	const specificationsAdditionalProperty = isLegacySku(sku)
 		? toAdditionalPropertiesLegacy(sku)
 		: toAdditionalProperties(sku);
-	const additionalProperty = specificationsAdditionalProperty.filter((prop) =>
-		variantProps.has(prop.name ?? ""),
-	);
+	const additionalProperty = [
+		...specificationsAdditionalProperty.filter((prop) => variantProps.has(prop.name ?? "")),
+		...(toAdditionalPropertyReferenceIds(sku.referenceId ?? []) ?? []),
+	];
 
 	// Offers: best seller, lean (availability + seller; optional inventoryLevel)
 	const offerConverter = isLegacyProduct(product) ? toOfferLegacy : toOffer;
 	const allOffers = (sku.sellers ?? []).map(offerConverter).sort(bestOfferFirst);
 	const bestOffer = allOffers[0];
-	const leanOffers = bestOffer ? [buildOfferVariant(bestOffer, includeInventory)] : [];
+	// `variantKeepLadder` marks the ONE variant the card renders (see
+	// displayedVariantId): it keeps the LEAN shape but needs a real ladder,
+	// through the same `priceSpecifications` hook the root offer uses.
+	const leanOffers = bestOffer
+		? [
+				options.variantKeepLadder
+					? {
+							...buildOfferVariant(bestOffer, includeInventory),
+							priceSpecification: applyPriceSpecifications([bestOffer], options)[0]
+								.priceSpecification,
+						}
+					: buildOfferVariant(bestOffer, includeInventory),
+			]
+		: [];
 
 	// image[0] only — selectors render a single thumbnail. Reuse the same
 	// imagesByKey lookup toProduct uses so URLs stay consistent across variants.

package/src/utils/vtexId.ts

@@ -20,9 +20,17 @@ const VTEX_AUTH_COOKIE = "VtexIdclientAutCookie";
 
 /**
  * Extract the VtexIdclientAutCookie value from a cookie string.
+ *
+ * Matches BOTH the base cookie `VtexIdclientAutCookie=` and the account-suffixed
+ * variant `VtexIdclientAutCookie_{account}=`. VTEX frequently sets ONLY the
+ * suffixed variant on the storefront domain — matching just the base name makes
+ * genuinely logged-in users look anonymous, which defeats any logged-in cache
+ * bypass built on top of this and can leak personalized/cached responses.
  */
 export function extractVtexAuthCookie(cookieHeader: string): string | null {
-	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${VTEX_AUTH_COOKIE}=([^;]+)`));
+	const match = cookieHeader.match(
+		new RegExp(`(?:^|;\\s*)${VTEX_AUTH_COOKIE}(?:_[^=;\\s]+)?=([^;]+)`),
+	);
 	return match?.[1] ?? null;
 }
 
@@ -48,7 +56,12 @@ function decodeJwtPayload(token: string): Record<string, unknown> | null {
 export function parseVtexAuthToken(token: string): VtexAuthInfo {
 	const payload = decodeJwtPayload(token);
 	if (!payload) {
-		return { isLoggedIn: false, isExpired: true };
+		// Opaque (non-JWT) token. VTEX auth cookies are frequently opaque strings
+		// rather than JWTs — we cannot read `exp`, but the mere presence of the
+		// cookie means the user IS authenticated. Treating it as logged-out (the
+		// previous behavior) makes real sessions look anonymous and defeats any
+		// logged-in cache bypass. Fail towards "logged in" (i.e. do-not-cache).
+		return { isLoggedIn: true, isExpired: false };
 	}
 
 	const exp = typeof payload.exp === "number" ? payload.exp : undefined;

package/src/vtexClient.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment node
+/**
+ * The VTEX upstream client (/next/upstream-clients): typed calls over the
+ * framework's instrumented fetch, labeled provider "vtex" with a named
+ * operation, retries and a circuit breaker on by default, per-shopper inputs
+ * as arguments, and errors that carry no body, URL, token or cookie.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const instrumented = vi.hoisted(() => ({
+	options: [] as Record<string, unknown>[],
+	operations: [] as (string | undefined)[],
+}));
+
+vi.mock("@decocms/blocks/fetch", async (importActual) => {
+	const actual = await importActual<typeof import("@decocms/blocks/fetch")>();
+	return {
+		...actual,
+		createInstrumentedFetch: (options: Parameters<typeof actual.createInstrumentedFetch>[0]) => {
+			instrumented.options.push(options as unknown as Record<string, unknown>);
+			const request = actual.createInstrumentedFetch(options);
+			return (input: string | URL | Request, init?: RequestInit & { operation?: string }) => {
+				instrumented.operations.push(init?.operation);
+				return request(input, init);
+			};
+		},
+	};
+});
+
+import { createVtexClient, VtexError } from ".";
+
+type Call = { url: string; init: RequestInit };
+
+/** An upstream answering with `statuses` in order, recording each request. */
+function upstream(statuses: number[] = [], headers: Record<string, string | string[]> = {}) {
+	const calls: Call[] = [];
+	const fetch = vi.fn(async (input: string | URL | Request, init: RequestInit = {}) => {
+		calls.push({ url: String(input), init });
+		const response = new Response('{"secret-body":"token-123"}', { status: statuses.shift() ?? 200 });
+		for (const [name, value] of Object.entries(headers)) {
+			for (const v of Array.isArray(value) ? value : [value]) response.headers.append(name, v);
+		}
+		return response;
+	});
+	return { calls, fetch: fetch as unknown as typeof globalThis.fetch };
+}
+
+const header = (call: Call | undefined, name: string) => new Headers(call?.init.headers).get(name);
+
+afterEach(() => {
+	instrumented.options.length = 0;
+	instrumented.operations.length = 0;
+});
+
+describe("createVtexClient", () => {
+	it("uses the instrumented fetch as provider vtex, with retries and a circuit breaker on", () => {
+		createVtexClient({ account: "store" });
+		expect(instrumented.options[0]).toMatchObject({
+			provider: "vtex",
+			retry: { attempts: 2, backoffMs: 150 },
+			circuitBreaker: { failures: 5, cooldownMs: 5000 },
+		});
+	});
+
+	it("turns retries and the circuit breaker off when asked", () => {
+		createVtexClient({ account: "store", retry: false, circuitBreaker: false });
+		expect(instrumented.options[0]?.retry).toBeUndefined();
+		expect(instrumented.options[0]?.circuitBreaker).toBeUndefined();
+	});
+
+	it("searches Intelligent Search with facets, region, locale and sales channel as arguments", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({
+			account: "store",
+			appKey: "key",
+			appToken: "token",
+			salesChannel: "2",
+			locale: "pt-BR",
+			fetch,
+		});
+		await vtex.search.products({
+			query: "linen shirt",
+			count: 12,
+			facets: [{ key: "category-1", value: "shirts" }],
+			regionId: "v2.ABC",
+		});
+		const url = new URL(calls[0]!.url);
+		expect(url.origin).toBe("https://store.vtexcommercestable.com.br");
+		expect(url.pathname).toBe("/api/io/_v/api/intelligent-search/product_search/category-1/shirts");
+		expect(Object.fromEntries(url.searchParams)).toEqual({
+			query: "linen shirt",
+			count: "12",
+			locale: "pt-BR",
+			regionId: "v2.ABC",
+			sc: "2",
+		});
+		expect(header(calls[0], "x-vtex-api-appkey")).toBe("key");
+		expect(header(calls[0], "x-vtex-api-apptoken")).toBe("token");
+		expect(header(calls[0], "cookie")).toBeNull();
+		expect(instrumented.operations).toEqual(["intelligent-search.product_search"]);
+	});
+
+	it("names every operation from the VTEX API, never a URL", async () => {
+		const { fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", fetch });
+		await vtex.catalog.pageType("/shirts/linen");
+		await vtex.catalog.products({ fq: ["productId:1", "productId:2"], from: 0, to: 9 });
+		await vtex.checkout.simulation({ items: [{ id: "1", quantity: 1, seller: "1" }] });
+		await vtex.checkout.regions({ postalCode: "01000-000", country: "BRA" });
+		await vtex.sessions.get();
+		expect(instrumented.operations).toEqual([
+			"catalog.pagetype",
+			"catalog.products.search",
+			"checkout.simulation",
+			"checkout.regions",
+			"sessions.get",
+		]);
+	});
+
+	it("retries an idempotent call and fails fast once the breaker opens", async () => {
+		const { calls, fetch } = upstream([503, 200]);
+		const vtex = createVtexClient({ account: "store", fetch, retry: { attempts: 1, backoffMs: 0 } });
+		await expect(vtex.catalog.categoryTree()).resolves.toBeDefined();
+		expect(calls).toHaveLength(2);
+
+		const down = upstream([500, 500, 500]);
+		const failing = createVtexClient({
+			account: "store",
+			fetch: down.fetch,
+			retry: false,
+			circuitBreaker: { failures: 2, cooldownMs: 60_000 },
+		});
+		await expect(failing.catalog.categoryTree()).rejects.toBeInstanceOf(VtexError);
+		await expect(failing.catalog.categoryTree()).rejects.toBeInstanceOf(VtexError);
+		await expect(failing.catalog.categoryTree()).rejects.toThrow(/circuit open/);
+		expect(down.calls).toHaveLength(2);
+	});
+
+	it("never retries a cart write", async () => {
+		const { calls, fetch } = upstream([503, 200]);
+		const vtex = createVtexClient({ account: "store", fetch, retry: { attempts: 3, backoffMs: 0 } });
+		await expect(vtex.checkout.addItems("of1", [{ id: 1, quantity: 1, seller: "1" }])).rejects.toThrow(
+			VtexError,
+		);
+		expect(calls).toHaveLength(1);
+	});
+
+	it("forwards the shopper's cookie, sanitized, and hands back VTEX's Set-Cookie values", async () => {
+		const { calls, fetch } = upstream([], {
+			"set-cookie": ["checkout.vtex.com=__ofid=of1; Domain=store.vtexcommercestable.com.br; Path=/"],
+		});
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token", fetch });
+		const result = await vtex.checkout.orderForm({
+			cookie: "checkout.vtex.com=__ofid=of1; tag=cateçoria",
+		});
+		expect(header(calls[0], "cookie")).toBe("checkout.vtex.com=__ofid=of1");
+		expect(calls[0]?.init.method).toBe("POST");
+		// Every orderForm section, and no app credentials next to a shopper's cookie.
+		expect(calls[0]?.init.body).toBe("{}");
+		expect(header(calls[0], "x-vtex-api-appkey")).toBeNull();
+		expect(header(calls[0], "x-vtex-api-apptoken")).toBeNull();
+		expect(result.setCookies).toEqual([
+			"checkout.vtex.com=__ofid=of1; Domain=store.vtexcommercestable.com.br; Path=/",
+		]);
+		expect(result.data).toEqual({ "secret-body": "token-123" });
+	});
+
+	it("throws errors that carry the operation and status, never the body, URL or credentials", async () => {
+		const { fetch } = upstream([400]);
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token-123", fetch });
+		const error = await vtex.search.products({ query: "q" }).catch((e: unknown) => e);
+		expect(error).toBeInstanceOf(VtexError);
+		expect(error).toMatchObject({ operation: "intelligent-search.product_search", status: 400 });
+		expect((error as Error).message).toBe("vtex intelligent-search.product_search failed with HTTP 400");
+	});
+
+	it("narrows the orderForm sections only when asked", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", fetch });
+		await vtex.checkout.orderForm({ sections: ["items", "totalizers"] });
+		expect(calls[0]?.init.body).toBe('{"expectedOrderFormSections":["items","totalizers"]}');
+	});
+
+	it("keeps caller paths inside their endpoint", async () => {
+		const { calls, fetch } = upstream();
+		const vtex = createVtexClient({ account: "store", appKey: "key", appToken: "token", fetch });
+		for (const path of [
+			"../../api/dataentities/CL/search",
+			"/shirts/%2e%2e/%2E%2E/api/dataentities/CL/search",
+			"shirts/./linen",
+		]) {
+			await expect(vtex.catalog.pageType(path)).rejects.toThrow(/invalid path segment/);
+		}
+		await expect(vtex.catalog.products({ term: "a/../../../api/x" })).rejects.toThrow(
+			/invalid path segment/,
+		);
+		expect(calls).toHaveLength(0);
+
+		await vtex.catalog.pageType("/shirts/linen?_where=x#y");
+		const url = new URL(calls[0]!.url);
+		expect(url.pathname).toBe("/api/catalog_system/pub/portal/pagetype/shirts/linen%3F_where%3Dx%23y");
+		expect(url.search).toBe("");
+	});
+});