@decocms/apps-vtex 7.2.0

package/src/utils/operationRouter.ts

@@ -0,0 +1,139 @@
+/**
+ * URL-derived operation name router for VTEX API calls.
+ *
+ * Plugged into `@decocms/start`'s `createInstrumentedFetch` via the
+ * `resolveOperation(url, method)` option. The resolved string becomes the
+ * span suffix (`vtex.<operation>`) and the `fetch.operation` span +
+ * histogram label, so it must be:
+ *
+ *   - low-cardinality (no IDs, slugs, search terms, account names);
+ *   - stable across deploys (used for alerting + dashboards);
+ *   - human-debuggable in a trace view.
+ *
+ * The router is intentionally a flat ordered list of regex matchers,
+ * not a tree. Adding/auditing routes is a one-line patch and routes
+ * are evaluated in priority order (most specific first). Unknown URLs
+ * return `undefined` so the framework falls back to the generic
+ * `vtex.fetch` span name — observable, just less specific.
+ *
+ * Callers that need finer granularity than the URL can express (e.g.
+ * `POST /orderForm/{id}/items` is one URL but covers add / update /
+ * remove flows) should set `init.operation` explicitly per call; that
+ * always wins over the router.
+ */
+
+type OperationResolver = string | ((match: RegExpMatchArray, method: string) => string);
+
+interface Matcher {
+	pattern: RegExp;
+	operation: OperationResolver;
+}
+
+const m = (pattern: RegExp, operation: OperationResolver): Matcher => ({ pattern, operation });
+
+/**
+ * Ordered list of `(regex, operation)` matchers. The first match wins.
+ *
+ * Patterns match against the URL pathname (the host is ignored — VTEX
+ * spreads the same API surface across `*.vtexcommercestable.*`,
+ * `*.myvtex.com`, and storefront origins, all on identical paths).
+ *
+ * Operation strings are bare (no `vtex.` prefix) — the framework
+ * prefixes them with the integration name at span time.
+ */
+const MATCHERS: ReadonlyArray<Matcher> = [
+	m(/^\/api\/io\/_v\/api\/intelligent-search\/([a-z_-]+)/, (mm) => `intelligent-search.${mm[1]}`),
+	m(/^\/_v\/private\/graphql\/v1/, "io.graphql"),
+	m(/^\/_v\/segment\//, "io.segment"),
+
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/items\/update/, (_mm, method) =>
+		method === "POST" ? "checkout.orderform.items.update" : "checkout.orderform.items",
+	),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/items/, (_mm, method) => {
+		if (method === "DELETE") return "checkout.orderform.items.remove";
+		if (method === "PATCH" || method === "PUT") return "checkout.orderform.items.update";
+		return "checkout.orderform.items.add";
+	}),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/coupons/, "checkout.orderform.coupons"),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/profile/, "checkout.orderform.profile"),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/shippingData/, "checkout.orderform.shipping"),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+\/paymentData/, "checkout.orderform.payment"),
+	m(/^\/api\/checkout\/pub\/orderForm\/[^/]+/, (_mm, method) =>
+		method === "GET" ? "checkout.orderform.get" : "checkout.orderform.update",
+	),
+	m(/^\/api\/checkout\/pub\/orderForm(?:\/?$)/, (_mm, method) =>
+		method === "POST" ? "checkout.orderform.create" : "checkout.orderform.get",
+	),
+	m(/^\/api\/checkout\/pub\/orderForms\/simulation/, "checkout.simulation"),
+	m(/^\/api\/checkout\/pub\/regions/, "checkout.regions"),
+	m(/^\/api\/checkout\/pub\/postal-code/, "checkout.postal-code"),
+
+	m(/^\/api\/sessions/, (_mm, method) => (method === "POST" ? "sessions.update" : "sessions.get")),
+	m(/^\/api\/segments\//, "segments.get"),
+
+	m(/^\/api\/catalog_system\/pub\/portal\/pagetype\//, "catalog.pagetype"),
+	m(
+		/^\/api\/catalog_system\/pub\/products\/crossselling\/([^/]+)/,
+		(mm) => `catalog.crossselling.${mm[1]}`,
+	),
+	m(/^\/api\/catalog_system\/pub\/products\/variations\//, "catalog.products.variations"),
+	m(/^\/api\/catalog_system\/pub\/products\/search/, "catalog.products.search"),
+	m(/^\/api\/catalog_system\/pub\/facets\/search/, "catalog.facets.search"),
+	m(/^\/api\/catalog_system\/pub\/category\/tree/, "catalog.category.tree"),
+	m(/^\/api\/catalog_system\/(?:pub|pvt)\/specification/, "catalog.specification"),
+	m(/^\/api\/catalog_system\/pub\/brand/, "catalog.brand"),
+	m(/^\/api\/catalog_system\/pvt\/sku\//, "catalog.sku"),
+	m(/^\/api\/catalog_system\//, "catalog.other"),
+
+	m(/^\/api\/wishlist\//, "wishlist"),
+	m(/^\/api\/profile-system\/profile\//, "profile"),
+	m(/^\/api\/dataentities\/([^/]+)/, (mm) => `masterdata.${mm[1]}`),
+
+	m(/^\/api\/oms\/user\/orders\/[^/]+\/cancel/, "oms.orders.cancel"),
+	m(/^\/api\/oms\/user\/orders/, "oms.orders"),
+	m(/^\/api\/oms\/pvt\/orders/, "oms.orders.pvt"),
+
+	m(/^\/api\/vtexid\/pub\/logout/, "vtexid.logout"),
+	m(/^\/api\/vtexid\/pub\/authentication\/start/, "vtexid.authentication.start"),
+	m(/^\/api\/vtexid\/pub\/authentication\/[a-z]+\/validate/, "vtexid.authentication.validate"),
+	m(/^\/api\/vtexid\/pub\/authenticated\/user/, "vtexid.user"),
+	m(/^\/api\/vtexid\//, "vtexid.other"),
+
+	m(/^\/api\/events\/v1\//, "events.send"),
+	m(/^\/sitemap.*\.xml$/, "sitemap"),
+	m(/^\/api\/license-manager/, "license-manager"),
+];
+
+/**
+ * Resolve an operation name for a VTEX URL. Returns `undefined` if no
+ * matcher fires, which causes the framework to fall back to
+ * `vtex.fetch`.
+ *
+ * Designed to be passed directly to `createInstrumentedFetch`:
+ *
+ * ```ts
+ * createInstrumentedFetch({
+ *   name: "vtex",
+ *   resolveOperation: vtexOperationRouter,
+ * });
+ * ```
+ */
+export function vtexOperationRouter(url: string, method: string): string | undefined {
+	let pathname: string;
+	try {
+		pathname = new URL(url).pathname;
+	} catch {
+		const qs = url.indexOf("?");
+		const hash = url.indexOf("#");
+		const end = [qs, hash].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+		pathname = end === undefined ? url : url.slice(0, end);
+	}
+
+	const upperMethod = method.toUpperCase();
+	for (const { pattern, operation } of MATCHERS) {
+		const match = pathname.match(pattern);
+		if (!match) continue;
+		return typeof operation === "function" ? operation(match, upperMethod) : operation;
+	}
+	return undefined;
+}

package/src/utils/pickAndOmit.ts

@@ -0,0 +1,25 @@
+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>;
+}

package/src/utils/proxy.ts

@@ -0,0 +1,435 @@
+/**
+ * VTEX Proxy Utility.
+ *
+ * Proxies storefront requests for /checkout, /account, /api, /files, /arquivos
+ * to the VTEX origin. Essential for checkout and My Account pages to work.
+ *
+ * Two flavors:
+ * - `proxyToVtex()` — simple single-origin proxy (vtexcommercestable)
+ * - `createVtexCheckoutProxy()` — production-grade dual-origin proxy with
+ *   proper cookie attribute preservation, non-ASCII sanitization, and
+ *   configurable origin routing (checkout UI vs API paths)
+ *
+ * Designed to be used with TanStack Start API routes or Cloudflare Worker
+ * fetch handlers.
+ */
+
+import { getVtexConfig, getVtexFetch, type VtexConfig, vtexHost } from "../client";
+import { proxySetCookie } from "./cookies";
+
+export interface VtexProxyOptions {
+	/**
+	 * VTEX environment suffix.
+	 * @default "vtexcommercestable"
+	 */
+	environment?: "vtexcommercestable" | "vtexcommercebeta";
+
+	/**
+	 * Additional path prefixes to proxy beyond the defaults.
+	 * Example: ["/custom-api/"]
+	 */
+	extraPaths?: string[];
+
+	/**
+	 * Paths that should NOT be proxied even if they match a prefix.
+	 */
+	excludePaths?: string[];
+
+	/**
+	 * Whether to rewrite Set-Cookie domains to the storefront's domain.
+	 * @default true
+	 */
+	rewriteCookieDomain?: boolean;
+
+	/**
+	 * Custom headers to inject into every proxied request.
+	 */
+	extraHeaders?: Record<string, string>;
+}
+
+const DEFAULT_PROXY_PATHS = [
+	"/checkout",
+	"/checkout/",
+	"/account",
+	"/account/",
+	"/api/",
+	"/files/",
+	"/arquivos/",
+	"/checkout/changeToAnonymousUser/",
+	"/_v/",
+	"/no-cache/",
+	"/graphql/",
+	"/login",
+	"/login/",
+	"/logout",
+	"/logout/",
+	"/assets/vtex",
+	"/_secure/account",
+	"/XMLData/",
+] as const;
+
+const HOP_BY_HOP_HEADERS = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailers",
+	"transfer-encoding",
+	"upgrade",
+]);
+
+/**
+ * Returns all path prefixes that should be proxied to VTEX.
+ */
+export function getVtexProxyPaths(options?: VtexProxyOptions): string[] {
+	return [...DEFAULT_PROXY_PATHS, ...(options?.extraPaths ?? [])];
+}
+
+/**
+ * Check if a request path should be proxied to VTEX.
+ */
+export function shouldProxyToVtex(pathname: string, options?: VtexProxyOptions): boolean {
+	const paths = getVtexProxyPaths(options);
+	const excluded = options?.excludePaths ?? [];
+
+	if (excluded.some((ex) => pathname.startsWith(ex))) return false;
+	return paths.some((prefix) => pathname.startsWith(prefix));
+}
+
+function buildOriginUrl(request: Request, config: VtexConfig, environment: string): URL {
+	const url = new URL(request.url);
+	const originHost = vtexHost(environment, config);
+	return new URL(`https://${originHost}${url.pathname}${url.search}`);
+}
+
+/**
+ * Copy headers excluding hop-by-hop and Set-Cookie.
+ *
+ * Set-Cookie is excluded intentionally: Headers.forEach / .set() joins
+ * multiple Set-Cookie values with ", " which corrupts cookies containing
+ * commas (e.g. Expires dates). proxySetCookie handles Set-Cookie
+ * separately using Headers.getSetCookie() for correct multi-cookie support.
+ */
+function filterHeaders(headers: Headers): Headers {
+	const filtered = new Headers();
+	headers.forEach((value, key) => {
+		const lower = key.toLowerCase();
+		if (lower === "set-cookie") return;
+		if (!HOP_BY_HOP_HEADERS.has(lower)) {
+			filtered.set(key, value);
+		}
+	});
+	return filtered;
+}
+
+/**
+ * Proxy a request to VTEX origin.
+ *
+ * Forwards the request with all cookies and headers, rewrites
+ * Set-Cookie domains on the response, and strips hop-by-hop headers.
+ *
+ * @example
+ * ```ts
+ * // In a TanStack Start API route or catch-all handler
+ * if (shouldProxyToVtex(url.pathname)) {
+ *   return proxyToVtex(request);
+ * }
+ * ```
+ */
+export async function proxyToVtex(request: Request, options?: VtexProxyOptions): Promise<Response> {
+	const config = getVtexConfig();
+	const environment = options?.environment ?? "vtexcommercestable";
+
+	const originUrl = buildOriginUrl(request, config, environment);
+	const forwardHeaders = filterHeaders(new Headers(request.headers));
+
+	const requestUrl = new URL(request.url);
+	forwardHeaders.set("origin", request.headers.get("origin") ?? requestUrl.origin);
+	forwardHeaders.set("Host", originUrl.hostname);
+	forwardHeaders.set("X-Forwarded-Host", requestUrl.host);
+	forwardHeaders.set("X-Forwarded-Proto", "https");
+
+	if (options?.extraHeaders) {
+		for (const [k, v] of Object.entries(options.extraHeaders)) {
+			forwardHeaders.set(k, v);
+		}
+	}
+
+	if (typeof config.appKey === "string" && typeof config.appToken === "string") {
+		forwardHeaders.set("X-VTEX-API-AppKey", config.appKey);
+		forwardHeaders.set("X-VTEX-API-AppToken", config.appToken);
+	}
+
+	const init: RequestInit = {
+		method: request.method,
+		headers: forwardHeaders,
+		redirect: "manual",
+	};
+
+	if (request.method !== "GET" && request.method !== "HEAD") {
+		init.body = request.body;
+		// @ts-expect-error -- needed for streaming body in Workers
+		init.duplex = "half";
+	}
+
+	// Route through the configured VTEX fetch so traces / metrics / logs
+	// see the proxied origin call. The URL router classifies the call
+	// into the right `vtex.<area>.<op>` bucket (e.g. `vtex.checkout.*`,
+	// `vtex.vtexid.logout`, `vtex.io.segment`) — no per-callsite hint
+	// needed because we're a generic forwarder.
+	const originResponse = await getVtexFetch()(originUrl.toString(), init);
+
+	const responseHeaders = filterHeaders(new Headers(originResponse.headers));
+
+	proxySetCookie(
+		originResponse.headers,
+		responseHeaders,
+		options?.rewriteCookieDomain !== false ? requestUrl.origin : undefined,
+	);
+
+	if (originResponse.status >= 300 && originResponse.status < 400) {
+		const location = originResponse.headers.get("location");
+		if (location) {
+			const originVtexHost = vtexHost(environment, config);
+			const storefrontOrigin = requestUrl.origin;
+			const vtexOrigin = `https://${originVtexHost}`;
+			const rewritten = location.replace(vtexOrigin, storefrontOrigin);
+			responseHeaders.set("location", rewritten);
+		}
+	}
+
+	return new Response(originResponse.body, {
+		status: originResponse.status,
+		statusText: originResponse.statusText,
+		headers: responseHeaders,
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Production-grade checkout proxy factory
+// ---------------------------------------------------------------------------
+
+export interface VtexCheckoutProxyConfig {
+	/** VTEX account name (e.g. "casaevideonewio"). */
+	account: string;
+
+	/**
+	 * Store's public checkout domain (e.g. "secure.casaevideo.com.br").
+	 * Checkout UI, /files/, and /_v/private/graphql are routed here.
+	 */
+	checkoutOrigin: string;
+
+	/**
+	 * VTEX commerce-stable origin for API calls.
+	 * @default `https://{account}.vtexcommercestable.com.br`
+	 */
+	apiOrigin?: string;
+
+	/**
+	 * myvtex origin — used for redirect rewriting.
+	 * @default `https://{account}.myvtex.com`
+	 */
+	myvtexOrigin?: string;
+
+	/**
+	 * VTEX TLD — most accounts use `.com.br`, but some use `.com`.
+	 * @default "com.br"
+	 */
+	domain?: string;
+
+	/**
+	 * Extra paths on which to force-expire cookies.
+	 * Useful for logout: VTEX sends Max-Age=0 for auth cookies, but the
+	 * checkout orderForm cookie sometimes survives. This appends explicit
+	 * Set-Cookie: name=; Max-Age=0 entries.
+	 */
+	expireCookiesOnPaths?: Array<{
+		pathPrefix: string;
+		cookies: string[];
+	}>;
+
+	/**
+	 * Optional HTML transform for checkout pages.
+	 * Receives the full HTML string and should return the modified version.
+	 */
+	htmlTransform?: (html: string) => string;
+}
+
+const CF_INTERNAL_HEADERS = new Set([
+	"cf-connecting-ip",
+	"cf-ipcountry",
+	"cf-ray",
+	"cf-visitor",
+	"cf-ew-via",
+	"cdn-loop",
+]);
+
+const CHECKOUT_SKIP_HEADERS = new Set([
+	...HOP_BY_HOP_HEADERS,
+	"set-cookie",
+	...CF_INTERNAL_HEADERS,
+]);
+
+const toAscii = (v: string) => v.replace(/[^\x20-\x7E]/g, "");
+
+function filterHeadersStrict(headers: Headers): Headers {
+	const filtered = new Headers();
+	headers.forEach((value, key) => {
+		if (CHECKOUT_SKIP_HEADERS.has(key.toLowerCase())) return;
+		try {
+			filtered.set(key, toAscii(value));
+		} catch {
+			// skip headers that still fail after sanitization
+		}
+	});
+	return filtered;
+}
+
+/**
+ * Rewrite Set-Cookie headers: only change the Domain attribute.
+ * Unlike `proxySetCookie`, this preserves ALL attributes (Max-Age,
+ * Expires, SameSite, etc.) which is critical for logout.
+ */
+function rewriteSetCookieDomain(from: Headers, to: Headers, toHostname: string) {
+	const raw: string[] =
+		typeof from.getSetCookie === "function"
+			? from.getSetCookie()
+			: (from.get("set-cookie") ?? "").split(/,(?=[^ ]+=)/).filter(Boolean);
+
+	for (const cookie of raw) {
+		const rewritten = cookie.replace(/Domain=[^;]*/i, `Domain=${toHostname}`);
+		to.append("Set-Cookie", rewritten);
+	}
+}
+
+/**
+ * Creates a production-grade VTEX checkout proxy handler.
+ *
+ * Routes checkout UI pages to the store's public domain and API calls
+ * to vtexcommercestable. Properly rewrites Set-Cookie domains (preserving
+ * Max-Age/Expires), sanitizes non-ASCII headers, filters hop-by-hop and
+ * CF-internal headers, and rewrites Location redirects.
+ *
+ * Returns a function compatible with `createDecoWorkerEntry`'s `proxyHandler`.
+ *
+ * @example
+ * ```ts
+ * const vtexProxy = createVtexCheckoutProxy({
+ *   account: "casaevideonewio",
+ *   checkoutOrigin: "secure.casaevideo.com.br",
+ *   expireCookiesOnPaths: [
+ *     { pathPrefix: "/api/vtexid/pub/logout", cookies: ["checkout.vtex.com"] },
+ *   ],
+ *   htmlTransform: (html) =>
+ *     html.replace("</head>", "<style>.body{min-height:100vh}</style></head>"),
+ * });
+ *
+ * createDecoWorkerEntry(serverEntry, {
+ *   proxyHandler: async (request, url) => {
+ *     if (url.pathname === "/login") return null;
+ *     if (!shouldProxyToVtex(url.pathname)) return null;
+ *     return vtexProxy(request, url);
+ *   },
+ * });
+ * ```
+ */
+export function createVtexCheckoutProxy(
+	config: VtexCheckoutProxyConfig,
+): (request: Request, url: URL) => Promise<Response> {
+	const domain = config.domain ?? "com.br";
+	const checkoutOrigin = config.checkoutOrigin.startsWith("https://")
+		? config.checkoutOrigin
+		: `https://${config.checkoutOrigin}`;
+	const apiOrigin = config.apiOrigin ?? `https://${config.account}.vtexcommercestable.${domain}`;
+	const myvtexOrigin = config.myvtexOrigin ?? `https://${config.account}.myvtex.com`;
+
+	function getOrigin(pathname: string, method: string): string {
+		if (
+			pathname.startsWith("/checkout") ||
+			pathname.startsWith("/account") ||
+			pathname.startsWith("/_secure/account") ||
+			pathname.startsWith("/files/") ||
+			pathname.startsWith("/_v/private/graphql")
+		) {
+			return checkoutOrigin;
+		}
+		if (method !== "GET" && method !== "HEAD" && pathname.startsWith("/_v/")) {
+			return checkoutOrigin;
+		}
+		return apiOrigin;
+	}
+
+	return async (request: Request, url: URL): Promise<Response> => {
+		const origin = getOrigin(url.pathname, request.method);
+		const originUrl = new URL(`${origin}${url.pathname}${url.search}`);
+		const fwd = filterHeadersStrict(new Headers(request.headers));
+
+		fwd.set("Host", originUrl.hostname);
+		fwd.set("X-Forwarded-Host", url.host);
+		fwd.set("X-Forwarded-Proto", "https");
+		fwd.set("origin", request.headers.get("origin") ?? url.origin);
+
+		const isCheckoutUI =
+			url.pathname.startsWith("/checkout") || url.pathname.startsWith("/account");
+		const isLogout = url.pathname.startsWith("/api/vtexid/pub/logout");
+
+		const init: RequestInit = {
+			method: request.method,
+			headers: fwd,
+			redirect: isCheckoutUI || isLogout ? "manual" : "follow",
+		};
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			init.body = request.body;
+			// @ts-expect-error -- needed for streaming body in Workers
+			init.duplex = "half";
+		}
+
+		const originRes = await getVtexFetch()(originUrl.toString(), init);
+		const resHeaders = filterHeadersStrict(new Headers(originRes.headers));
+		rewriteSetCookieDomain(originRes.headers, resHeaders, url.hostname);
+
+		// Force-expire cookies on configured paths
+		if (config.expireCookiesOnPaths) {
+			for (const rule of config.expireCookiesOnPaths) {
+				if (url.pathname.startsWith(rule.pathPrefix)) {
+					for (const name of rule.cookies) {
+						resHeaders.append("Set-Cookie", `${name}=; Path=/; Max-Age=0; Domain=${url.hostname}`);
+					}
+				}
+			}
+		}
+
+		// Rewrite redirect Location headers from VTEX domains to storefront
+		if (originRes.status >= 300 && originRes.status < 400) {
+			const loc = originRes.headers.get("location");
+			if (loc) {
+				resHeaders.set(
+					"location",
+					loc
+						.replace(checkoutOrigin, url.origin)
+						.replace(apiOrigin, url.origin)
+						.replace(myvtexOrigin, url.origin),
+				);
+			}
+		}
+
+		// HTML transform for checkout pages
+		const ct = originRes.headers.get("content-type") ?? "";
+		if (config.htmlTransform && ct.includes("text/html")) {
+			const html = await originRes.text();
+			const patched = config.htmlTransform(html);
+			return new Response(patched, {
+				status: originRes.status,
+				statusText: originRes.statusText,
+				headers: resHeaders,
+			});
+		}
+
+		return new Response(originRes.body, {
+			status: originRes.status,
+			statusText: originRes.statusText,
+			headers: resHeaders,
+		});
+	};
+}

package/src/utils/resourceRange.ts

@@ -0,0 +1,10 @@
+/**
+ * Build REST-Range header values for VTEX paginated APIs.
+ * Ported from deco-cx/apps vtex/utils/resourceRange.ts
+ */
+export function resourceRange(skip: number, take: number) {
+	const from = Math.max(skip, 0);
+	const to = from + Math.min(100, take);
+
+	return { from, to };
+}