@decocms/apps 1.14.0 → 1.15.0-next.1

package/README.md

@@ -57,8 +57,11 @@ A working VTEX storefront needs three things: a `deco-vtex` config block, an `in
 
 ```ts
 import { createSiteSetup } from "@decocms/start/setup";
-import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
-import { initVtexFromBlocks, setVtexFetch } from "@decocms/apps/vtex/client";
+import {
+  createVtexFetch,
+  initVtexFromBlocks,
+  setVtexFetch,
+} from "@decocms/apps/vtex";
 import { createVtexCommerceLoaders } from "@decocms/apps/vtex/commerceLoaders";
 
 createSiteSetup({
@@ -69,9 +72,28 @@ createSiteSetup({
   getCommerceLoaders: () => createVtexCommerceLoaders(),
 });
 
-setVtexFetch(createInstrumentedFetch("vtex"));
+// Plumbs spans, traceparent injection, URL redaction, and the
+// `commerce_request_duration_ms` histogram into every outbound
+// VTEX call. Operation names are derived from the URL via
+// `vtexOperationRouter` (overridable per call via `init.operation`).
+setVtexFetch(createVtexFetch());
 ```
 
+For Shopify storefronts the equivalent factory is `createShopifyFetch()`:
+
+```ts
+import { createShopifyFetch, setShopifyFetch } from "@decocms/apps/shopify";
+
+setShopifyFetch(createShopifyFetch());
+```
+
+Shopify's GraphQL operation name (`query Foo { ... }` → `Foo`) is
+extracted from the document body and stamped automatically — spans
+become `shopify.Foo` instead of the generic `shopify.storefront.graphql`.
+
+> **Heads up:** the factories require `@decocms/start@>=5.3.0-rc.0`
+> for the per-call `init.operation` API used to label spans.
+
 #### 3. Hooks in components
 
 ```tsx
@@ -134,7 +156,9 @@ await sendEmail({
 | Subpath | Purpose |
 |---------|---------|
 | `@decocms/apps/vtex` | Barrel index |
-| `@decocms/apps/vtex/client` | `vtexFetch`, `vtexFetchWithCookies`, `intelligentSearch`, `setVtexFetch`, `initVtexFromBlocks`, `configureVtex` |
+| `@decocms/apps/vtex/client` | `vtexFetch`, `vtexFetchWithCookies`, `intelligentSearch`, `setVtexFetch`, `getVtexFetch`, `initVtexFromBlocks`, `configureVtex` |
+| `@decocms/apps/vtex` (barrel) | All of `client`, plus `createVtexFetch`, `vtexOperationRouter` for observability wiring |
+| `@decocms/apps/shopify` (barrel) | `createShopifyFetch`, `setShopifyFetch`, `shopifyOperationRouter`, `extractGraphqlOperationName` for observability wiring |
 | `@decocms/apps/vtex/commerceLoaders` | `createVtexCommerceLoaders` |
 | `@decocms/apps/vtex/loaders/*` | Cart, user, wishlist, search, catalog, sessions, orders, autocomplete |
 | `@decocms/apps/vtex/actions/*` | Cart mutations, auth, profile, address, wishlist, newsletter |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps",
-  "version": "1.14.0",
+  "version": "1.15.0-next.1",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
@@ -109,14 +109,14 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@decocms/start": ">=0.19.0",
+    "@decocms/start": ">=5.3.0-rc.0",
     "@tanstack/react-query": ">=5",
     "react": ">=18",
     "react-dom": ">=18"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
-    "@decocms/start": "^2.5.0",
+    "@decocms/start": "5.3.0-rc.0",
     "@semantic-release/exec": "^7.1.0",
     "@tanstack/react-query": "^5.90.21",
     "@types/react": "^19.0.0",

package/shopify/index.ts

@@ -34,4 +34,10 @@ export { default as userLoader } from "./loaders/user";
 export { getCartCookie, setCartCookie } from "./utils/cart";
 // Cookie utils
 export { getCookies, setCookie } from "./utils/cookies";
+export { extractGraphqlOperationName } from "./utils/graphqlOperationName";
+export {
+	type CreateShopifyFetchOptions,
+	createShopifyFetch,
+} from "./utils/instrumentedFetch";
+export { shopifyOperationRouter } from "./utils/operationRouter";
 export { getUserCookie, setUserCookie } from "./utils/user";

package/shopify/utils/graphql.ts

@@ -1,3 +1,6 @@
+import type { InstrumentedFetchInit } from "@decocms/start/sdk/instrumentedFetch";
+import { extractGraphqlOperationName } from "./graphqlOperationName";
+
 export function gql(strings: TemplateStringsArray, ...values: unknown[]): string {
 	return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ""), "");
 }
@@ -29,14 +32,22 @@ export function createGraphqlClient(
 		): Promise<T> {
 			const query = typeof queryOrDef === "string" ? queryOrDef : buildQuery(queryOrDef);
 
-			const response = await _fetch(endpoint, {
+			// Stamp the GraphQL operation as init.operation so the framework's
+			// span name becomes `shopify.<OperationName>` instead of the
+			// generic `shopify.storefront.graphql` from the URL router. The
+			// extra field is silently dropped by plain `fetch` and read by
+			// any `InstrumentedFetch` configured via `setShopifyFetch`.
+			const operation = extractGraphqlOperationName(query);
+			const init: InstrumentedFetchInit = {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
 					...headers,
 				},
 				body: JSON.stringify({ query, variables }),
-			});
+				...(operation ? { operation } : {}),
+			};
+			const response = await _fetch(endpoint, init);
 
 			if (!response.ok) {
 				throw new Error(`Shopify GraphQL error: ${response.status} ${response.statusText}`);

package/shopify/utils/graphqlOperationName.ts

@@ -0,0 +1,67 @@
+/**
+ * Extract a semantic operation name from a GraphQL document.
+ *
+ * Used at the Shopify GraphQL client layer to stamp `init.operation`
+ * on the outbound fetch. The framework then suffixes the integration
+ * name (`shopify.<operation>`) onto the span and uses the same string
+ * as the `fetch.operation` attribute + histogram label.
+ *
+ * Resolution order:
+ *
+ *   1. An explicit `operationName` argument (e.g. when the client
+ *      received one alongside a multi-operation document) wins.
+ *   2. If the document has exactly one named operation, that name
+ *      is used.
+ *   3. If the document has zero or many anonymous operations, we
+ *      return `undefined` so the caller can fall back (typically to
+ *      the URL-derived `storefront.graphql` / `admin.graphql`).
+ *
+ * The parser is deliberately a small regex pass, not a full GraphQL
+ * tokenizer:
+ *
+ *   - GraphQL operation definitions live at the top level of the
+ *     document, never nested inside other operations, fragments, or
+ *     selection sets, so positional context isn't required to find
+ *     them — only to not match the literal words `query` /
+ *     `mutation` / `subscription` inside string values.
+ *   - We strip block strings (`""" … """`), string literals
+ *     (`"…"`), and `# …` comments before matching, which is enough
+ *     to make false-positive matches inside comments / docs vanish.
+ *
+ * If a Shopify operation is ever sufficiently mis-named to break
+ * this (unlikely, since the storefront SDK names them deliberately),
+ * the caller can always set `init.operation` explicitly.
+ */
+
+const OPERATION_RE = /\b(?:query|mutation|subscription)\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+
+const stripCommentsAndStrings = (doc: string): string =>
+	doc
+		.replace(/"""[\s\S]*?"""/g, '""')
+		.replace(/"(?:\\.|[^"\\])*"/g, '""')
+		.replace(/#[^\n]*/g, "");
+
+export function extractGraphqlOperationName(
+	document: string,
+	explicit?: string,
+): string | undefined {
+	if (explicit) return explicit;
+	if (!document) return undefined;
+
+	const stripped = stripCommentsAndStrings(document);
+	const names: string[] = [];
+
+	OPERATION_RE.lastIndex = 0;
+	for (
+		let match = OPERATION_RE.exec(stripped);
+		match !== null;
+		match = OPERATION_RE.exec(stripped)
+	) {
+		const [, name] = match;
+		if (name) names.push(name);
+		if (names.length > 1) break;
+	}
+
+	if (names.length === 1) return names[0];
+	return undefined;
+}

package/shopify/utils/instrumentedFetch.ts

@@ -0,0 +1,57 @@
+/**
+ * Pre-wired instrumented fetch factory for Shopify.
+ *
+ * Mirrors `vtex/utils/instrumentedFetch.ts`. Bundles:
+ *
+ *   1. `createInstrumentedFetch` from `@decocms/start` (spans,
+ *      traceparent, URL redaction).
+ *   2. `shopifyOperationRouter` as the URL fallback for non-GraphQL
+ *      and unnamed-GraphQL calls.
+ *   3. An `onComplete` that records `commerce_request_duration_ms`
+ *      with `provider: "shopify"`.
+ *
+ * Sites do:
+ *
+ *   ```ts
+ *   import { setShopifyFetch, createShopifyFetch } from "@decocms/apps/shopify";
+ *   setShopifyFetch(createShopifyFetch());
+ *   ```
+ *
+ * Per-call operation names come from `extractGraphqlOperationName`
+ * (wired in `./graphql.ts`); the URL router fires only when the
+ * extractor returns `undefined`.
+ */
+
+import {
+	createInstrumentedFetch,
+	type InstrumentedFetch,
+} from "@decocms/start/sdk/instrumentedFetch";
+import { getMeter } from "@decocms/start/sdk/observability";
+import { shopifyOperationRouter } from "./operationRouter";
+
+const HISTOGRAM_NAME = "commerce_request_duration_ms";
+
+export interface CreateShopifyFetchOptions {
+	baseFetch?: typeof fetch;
+	disableHistogram?: boolean;
+}
+
+export function createShopifyFetch(options: CreateShopifyFetchOptions = {}): InstrumentedFetch {
+	const { baseFetch, disableHistogram = false } = options;
+	return createInstrumentedFetch({
+		name: "shopify",
+		baseFetch,
+		resolveOperation: shopifyOperationRouter,
+		onComplete: disableHistogram
+			? undefined
+			: ({ operation, status, durationMs, cached }) => {
+					const meter = getMeter();
+					meter?.histogramRecord?.(HISTOGRAM_NAME, durationMs, {
+						provider: "shopify",
+						operation,
+						status_code: String(status),
+						cached: cached ? "true" : "false",
+					});
+				},
+	});
+}

package/shopify/utils/operationRouter.ts

@@ -0,0 +1,70 @@
+/**
+ * URL-derived operation name router for Shopify API calls.
+ *
+ * Plugged into `@decocms/start`'s `createInstrumentedFetch` via the
+ * `resolveOperation(url, method)` option. Mirrors the shape of the
+ * VTEX router in `../../vtex/utils/operationRouter.ts`.
+ *
+ * Shopify's API surface from this repo is overwhelmingly GraphQL —
+ * a single endpoint per environment (storefront vs admin). That means
+ * the URL alone can only tell us *which GraphQL surface* a call is
+ * hitting, not what the call actually does. The semantic operation
+ * name lives in the GraphQL document itself (`query Foo { ... }`),
+ * and is extracted by `extractGraphqlOperationName` (see
+ * `./graphqlOperationName.ts`) at the client layer and stamped as
+ * `init.operation`, which always wins over this router.
+ *
+ * So this router exists for:
+ *
+ *   - non-GraphQL Shopify REST endpoints we may add later
+ *     (cart API, customer accounts, billing, etc.);
+ *   - giving the GraphQL endpoints a *fallback* operation when the
+ *     extractor can't parse a name (anonymous queries, missing body).
+ */
+
+type OperationResolver = string | ((match: RegExpMatchArray, method: string) => string);
+
+interface Matcher {
+	pattern: RegExp;
+	operation: OperationResolver;
+}
+
+const m = (pattern: RegExp, operation: OperationResolver): Matcher => ({ pattern, operation });
+
+const MATCHERS: ReadonlyArray<Matcher> = [
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/graphql\.json/, "admin.graphql"),
+	m(/^\/api\/[0-9]{4}-[0-9]{2}\/graphql\.json/, "storefront.graphql"),
+
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/products/, "admin.products"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/orders/, "admin.orders"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/customers/, "admin.customers"),
+	m(/^\/admin\/api\/[0-9]{4}-[0-9]{2}\/inventory/, "admin.inventory"),
+
+	m(/^\/api\/[0-9]{4}-[0-9]{2}\/checkouts/, "storefront.checkout"),
+	m(/^\/cart(?:\/|\.js|$)/, "storefront.cart"),
+];
+
+/**
+ * Resolve an operation name for a Shopify URL. Returns `undefined`
+ * if no matcher fires, which causes the framework to fall back to
+ * `shopify.fetch`.
+ */
+export function shopifyOperationRouter(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/vtex/actions/analytics/sendEvent.ts

@@ -8,7 +8,7 @@
  * @see https://developers.vtex.com/docs/api-reference/intelligent-search-api#post-/event-api/v1/-account-/event
  */
 
-import { getVtexConfig } from "../../client";
+import { getVtexConfig, getVtexFetch } from "../../client";
 import { ANONYMOUS_COOKIE, SESSION_COOKIE } from "../../utils/intelligentSearch";
 
 export type Props =
@@ -68,7 +68,7 @@ const action = async (props: Props, req: Request): Promise<null> => {
 	}
 
 	const url = `https://sp.vtex.com/event-api/v1/${account}/event`;
-	await fetch(url, {
+	await getVtexFetch()(url, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify({
@@ -77,6 +77,7 @@ const action = async (props: Props, req: Request): Promise<null> => {
 			anonymous,
 			agent: req.headers.get("user-agent") || "deco-sites/apps",
 		}),
+		operation: "analytics.event",
 	});
 
 	return null;

package/vtex/actions/masterData.ts

@@ -2,7 +2,7 @@
  * VTEX MasterData v2 API actions.
  * Generic CRUD operations on data entities.
  */
-import { getVtexConfig, vtexFetch, vtexFetchResponse } from "../client";
+import { getVtexConfig, getVtexFetch, vtexFetch, vtexFetchResponse } from "../client";
 
 function removeEmptyFields(obj: Record<string, any>): Record<string, any> {
 	return Object.fromEntries(
@@ -153,10 +153,11 @@ export async function uploadAttachment(opts: UploadAttachmentOpts): Promise<{ ok
 		headers["X-VTEX-API-AppToken"] = config.appToken;
 	}
 
-	const response = await fetch(url, {
+	const response = await getVtexFetch()(url, {
 		method: "POST",
 		headers,
 		body: formData,
+		operation: "masterdata.attachment.upload",
 	});
 
 	if (!response.ok) {

package/vtex/actions/misc.ts

@@ -7,7 +7,7 @@
  *   - vtex/actions/payment/deletePaymentToken.ts
  * @see https://developers.vtex.com/docs/api-reference
  */
-import { getVtexConfig, vtexFetch } from "../client";
+import { getVtexConfig, getVtexFetch, vtexFetch } from "../client";
 import { buildAuthCookieHeader, VTEX_AUTH_COOKIE } from "../utils/vtexId";
 
 // ---------------------------------------------------------------------------
@@ -127,9 +127,10 @@ export async function notifyMe(props: NotifyMeProps): Promise<void> {
 	form.append("notifymeClientEmail", email);
 	form.append("notifymeIdSku", skuId);
 
-	await fetch(`https://${account}.vtexcommercestable.com.br/no-cache/AviseMe.aspx`, {
+	await getVtexFetch()(`https://${account}.vtexcommercestable.com.br/no-cache/AviseMe.aspx`, {
 		method: "POST",
 		body: form,
+		operation: "notifyme",
 	});
 }
 
@@ -148,7 +149,7 @@ export async function sendEvent(
 ): Promise<void> {
 	const { account } = getVtexConfig();
 
-	await fetch(`https://sp.vtex.com/event-api/v1/${account}/event`, {
+	await getVtexFetch()(`https://sp.vtex.com/event-api/v1/${account}/event`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({
@@ -156,6 +157,7 @@ export async function sendEvent(
 			...isCookies,
 			agent: userAgent || "deco-sites/apps",
 		}),
+		operation: "analytics.event",
 	});
 }
 

package/vtex/actions/newsletter.ts

@@ -5,7 +5,7 @@
  *   - vtex/actions/newsletter/updateNewsletterOptIn.ts
  * @see https://developers.vtex.com/docs/guides/newsletter
  */
-import { getVtexConfig, vtexFetch } from "../client";
+import { getVtexConfig, getVtexFetch, vtexFetch } from "../client";
 import { buildAuthCookieHeader } from "../utils/vtexId";
 
 // ---------------------------------------------------------------------------
@@ -83,9 +83,10 @@ export async function subscribe(props: SubscribeProps): Promise<void> {
 	form.append("newsInternalPart", part);
 	form.append("newsInternalCampaign", campaing);
 
-	await fetch(`https://${account}.vtexcommercestable.com.br/no-cache/Newsletter.aspx`, {
+	await getVtexFetch()(`https://${account}.vtexcommercestable.com.br/no-cache/Newsletter.aspx`, {
 		method: "POST",
 		body: form,
+		operation: "newsletter.subscribe",
 	});
 }
 

package/vtex/actions/profile.ts

@@ -4,7 +4,7 @@
  *   - vtex/actions/profile/updateProfile.ts
  * @see https://developers.vtex.com/docs/guides/profile-system
  */
-import { getVtexConfig, vtexFetch } from "../client";
+import { getVtexConfig, getVtexFetch, vtexFetch } from "../client";
 import { buildAuthCookieHeader } from "../utils/vtexId";
 
 // ---------------------------------------------------------------------------
@@ -166,10 +166,11 @@ export async function updateProfileFromRequest(
 			corporateDocument tradeName stateRegistration
 		}
 	}`;
-	const res = await fetch(`https://${account}.myvtex.com/_v/private/graphql/v1`, {
+	const res = await getVtexFetch()(`https://${account}.myvtex.com/_v/private/graphql/v1`, {
 		method: "POST",
 		body: JSON.stringify({ query: QUERY, variables: { profile } }),
 		headers: { "Content-Type": "application/json", cookie },
+		operation: "io.graphql.UpdateProfile",
 	});
 	return res.json();
 }

package/vtex/client.ts

@@ -3,6 +3,10 @@
  * Uses VTEX's public REST APIs (Intelligent Search + Catalog + Checkout).
  */
 
+import type {
+	InstrumentedFetch,
+	InstrumentedFetchInit,
+} from "@decocms/start/sdk/instrumentedFetch";
 import { RequestContext } from "@decocms/start/sdk/requestContext";
 import { sanitizeOutboundCookieHeader, warnDroppedCookies } from "./utils/cookieSanitizer";
 import { type FetchCacheOptions, fetchWithCache } from "./utils/fetchCache";
@@ -96,7 +100,7 @@ export interface VtexConfig {
 }
 
 let _config: VtexConfig | null = null;
-let _fetch: typeof fetch = globalThis.fetch;
+let _fetch: typeof fetch | InstrumentedFetch = globalThis.fetch;
 
 export function configureVtex(config: VtexConfig) {
 	_config = config;
@@ -105,19 +109,40 @@ export function configureVtex(config: VtexConfig) {
 
 /**
  * Override the fetch function used by all VTEX client calls.
- * Use this to plug in instrumented fetch for logging/tracing.
+ * Pass an `InstrumentedFetch` to get spans, traceparent injection,
+ * URL redaction, and the `commerce_request_duration_ms` histogram —
+ * use the pre-wired `createVtexFetch()` factory:
  *
- * @example
  * ```ts
- * import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
- * import { setVtexFetch } from "@decocms/apps/vtex";
- * setVtexFetch(createInstrumentedFetch("vtex"));
+ * import { setVtexFetch, createVtexFetch } from "@decocms/apps/vtex";
+ * setVtexFetch(createVtexFetch());
  * ```
+ *
+ * Accepts a plain `typeof fetch` too; in that mode VTEX calls are
+ * uninstrumented (useful for tests + sites that haven't onboarded
+ * the observability stack yet).
  */
-export function setVtexFetch(fetchFn: typeof fetch) {
+export function setVtexFetch(fetchFn: typeof fetch | InstrumentedFetch) {
 	_fetch = fetchFn;
 }
 
+/**
+ * Read-only accessor for the configured VTEX fetch. Used by ad-hoc
+ * callsites that don't fit the `vtexFetch*` helpers (FormData
+ * uploads, the storefront proxies, .aspx endpoints) but still want
+ * to participate in the instrumentation set up via `setVtexFetch`.
+ *
+ * Callers can stamp a per-call operation through the init:
+ *
+ * ```ts
+ * const fetch = getVtexFetch();
+ * await fetch(url, { method: "POST", operation: "notifyme" });
+ * ```
+ */
+export function getVtexFetch(): InstrumentedFetch {
+	return _fetch as InstrumentedFetch;
+}
+
 export function getVtexConfig(): VtexConfig {
 	if (!_config) throw new Error("VTEX not configured. Call configureVtex() first.");
 	return _config;
@@ -198,7 +223,10 @@ function hasCookieHeader(headers: HeadersInit | undefined): boolean {
 	return Object.keys(headers).some((k) => k.toLowerCase() === "cookie");
 }
 
-export async function vtexFetchResponse(path: string, init?: RequestInit): Promise<Response> {
+export async function vtexFetchResponse(
+	path: string,
+	init?: InstrumentedFetchInit,
+): Promise<Response> {
 	const raw = path.startsWith("http") ? path : `${baseUrl()}${path}`;
 	const url = sanitizeUrl(raw);
 
@@ -225,7 +253,7 @@ export async function vtexFetchResponse(path: string, init?: RequestInit): Promi
 	return response;
 }
 
-export async function vtexFetch<T>(path: string, init?: RequestInit): Promise<T> {
+export async function vtexFetch<T>(path: string, init?: InstrumentedFetchInit): Promise<T> {
 	const response = await vtexFetchResponse(path, init);
 	return response.json();
 }
@@ -242,7 +270,7 @@ export interface VtexCachedFetchOptions {
  */
 export async function vtexCachedFetch<T>(
 	path: string,
-	init?: RequestInit,
+	init?: InstrumentedFetchInit,
 	cacheOpts?: VtexCachedFetchOptions,
 ): Promise<T | null> {
 	const method = (init?.method ?? "GET").toUpperCase();
@@ -276,7 +304,10 @@ export async function vtexCachedFetch<T>(
  *
  * This mirrors deco-cx/deco's `proxySetCookie(response.headers, ctx.response.headers)`.
  */
-export async function vtexFetchWithCookies<T>(path: string, init?: RequestInit): Promise<T> {
+export async function vtexFetchWithCookies<T>(
+	path: string,
+	init?: InstrumentedFetchInit,
+): Promise<T> {
 	// Auto-inject request cookies from RequestContext.
 	//
 	// We sanitize the forwarded Cookie header before sending it to VTEX:

package/vtex/index.ts

@@ -13,3 +13,5 @@
  */
 export * from "./client";
 export { configure, type VtexState } from "./mod";
+export { type CreateVtexFetchOptions, createVtexFetch } from "./utils/instrumentedFetch";
+export { vtexOperationRouter } from "./utils/operationRouter";

package/vtex/utils/authHelpers.ts

@@ -6,7 +6,7 @@
  * createServerFn itself must live in site source (not node_modules) because
  * TanStack Start's Vite plugin only transforms source files.
  */
-import { getVtexConfig } from "../client";
+import { getVtexConfig, getVtexFetch } from "../client";
 import { extractVtexCookies } from "./cookieSanitizer";
 
 const DOMAIN_RE = /;\s*domain=[^;]*/gi;
@@ -49,10 +49,11 @@ export async function performVtexLogout(cookies: string): Promise<{ setCookies:
 	const domain = config.domain ?? "com.br";
 	const logoutUrl = `https://${config.account}.vtexcommercestable.${domain}/api/vtexid/pub/logout?scope=${config.account}&returnUrl=/`;
 
-	const res = await fetch(logoutUrl, {
+	const res = await getVtexFetch()(logoutUrl, {
 		method: "GET",
 		headers: { cookie: cookies },
 		redirect: "manual",
+		operation: "vtexid.logout",
 	});
 
 	const upstreamCookies = res.headers.getSetCookie?.() ?? [];

package/vtex/utils/instrumentedFetch.ts

@@ -0,0 +1,81 @@
+/**
+ * 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
+ *      `commerce_request_duration_ms` histogram via the meter
+ *      configured by `instrumentWorker(...)` in
+ *      `@decocms/start/sdk/observability` — `provider`, `operation`,
+ *      `status_code`, 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 {
+	createInstrumentedFetch,
+	type InstrumentedFetch,
+} from "@decocms/start/sdk/instrumentedFetch";
+import { getMeter } from "@decocms/start/sdk/observability";
+import { vtexOperationRouter } from "./operationRouter";
+
+const HISTOGRAM_NAME = "commerce_request_duration_ms";
+
+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?: typeof fetch;
+	/**
+	 * Disable the `commerce_request_duration_ms` histogram emission.
+	 * 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;
+}
+
+/**
+ * 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 } = options;
+	return createInstrumentedFetch({
+		name: "vtex",
+		baseFetch,
+		resolveOperation: vtexOperationRouter,
+		onComplete: disableHistogram
+			? undefined
+			: ({ operation, status, durationMs, cached }) => {
+					const meter = getMeter();
+					meter?.histogramRecord?.(HISTOGRAM_NAME, durationMs, {
+						provider: "vtex",
+						operation,
+						status_code: String(status),
+						cached: cached ? "true" : "false",
+					});
+				},
+	});
+}

package/vtex/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/vtex/utils/proxy.ts

@@ -14,7 +14,7 @@
  * fetch handlers.
  */
 
-import { getVtexConfig, type VtexConfig, vtexHost } from "../client";
+import { getVtexConfig, getVtexFetch, type VtexConfig, vtexHost } from "../client";
 import { proxySetCookie } from "./cookies";
 
 export interface VtexProxyOptions {
@@ -173,7 +173,12 @@ export async function proxyToVtex(request: Request, options?: VtexProxyOptions):
 		init.duplex = "half";
 	}
 
-	const originResponse = await fetch(originUrl.toString(), init);
+	// 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));
 
@@ -380,7 +385,7 @@ export function createVtexCheckoutProxy(
 			init.duplex = "half";
 		}
 
-		const originRes = await fetch(originUrl.toString(), init);
+		const originRes = await getVtexFetch()(originUrl.toString(), init);
 		const resHeaders = filterHeadersStrict(new Headers(originRes.headers));
 		rewriteSetCookieDomain(originRes.headers, resHeaders, url.hostname);