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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-magento",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco commerce app: Magento integration",
   "repository": {
@@ -26,9 +26,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
-    "@decocms/apps-commerce": "8.0.0",
-    "@decocms/tanstack": "8.0.0"
+    "@decocms/blocks": "8.1.0-next.0",
+    "@decocms/apps-commerce": "8.1.0-next.0",
+    "@decocms/tanstack": "8.1.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/README.md

@@ -13,7 +13,7 @@ the original deco-cx/apps repo and need adaptation passes (Deno → Node,
 ctx-based to client-based state access, cookie helpers from
 `@decocms/start/sdk/cookie`).
 
-A real-world consumer (deco-sites/granadobr-tanstack) is wiring magento
+A real-world consumer (a production Magento storefront) is wiring magento
 in-site today using a thin adapter that wraps the legacy `magento/mod.ts`
 shape. Their adapter is the migration target — once this package covers
 the surface area they need, the in-site copy goes away.
@@ -54,7 +54,7 @@ above is a hard requirement of this port.
 
 ## Why a stub now
 
-The deco-sites/granadobr-tanstack migration hit a HIGH parity finding:
+A production Magento storefront's migration hit a HIGH parity finding:
 
 ```
 invoke(magento/loaders/features) failed: handler not found

package/src/__tests__/graphql.test.ts

@@ -148,15 +148,15 @@ describe("transformFilterGraphQL — merge order", () => {
 
 describe("formatUrlSuffix", () => {
 	it("strips a single leading slash", () => {
-		expect(formatUrlSuffix("/granado/")).toBe("granado/");
+		expect(formatUrlSuffix("/acme/")).toBe("acme/");
 	});
 
 	it("appends trailing slash when missing", () => {
-		expect(formatUrlSuffix("granado")).toBe("granado/");
+		expect(formatUrlSuffix("acme")).toBe("acme/");
 	});
 
 	it("leaves trailing slash alone", () => {
-		expect(formatUrlSuffix("granado/")).toBe("granado/");
+		expect(formatUrlSuffix("acme/")).toBe("acme/");
 	});
 });
 

package/src/__tests__/magentoClient.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment node
+/**
+ * The v8 Magento client (/next/upstream-clients): every request goes through
+ * the instrumented fetch as provider "magento", named by its operation; the
+ * store's credentials only go to the store; errors never carry bodies.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const instrumented = vi.hoisted(() => ({
+  providers: [] as string[],
+  operations: [] as (string | undefined)[],
+}));
+
+vi.mock("@decocms/blocks/fetch", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@decocms/blocks/fetch")>();
+  return {
+    createInstrumentedFetch: (options: Parameters<typeof real.createInstrumentedFetch>[0]) => {
+      instrumented.providers.push(options.provider);
+      const request = real.createInstrumentedFetch(options);
+      return (input: string | URL | Request, init?: RequestInit & { operation?: string }) => {
+        instrumented.operations.push(init?.operation);
+        return request(input, init);
+      };
+    },
+  };
+});
+
+import { createMagentoClient, MagentoError } from "../magentoClient";
+
+/** The error a call rejects with (fails the test if it resolves). */
+const failure = (call: Promise<unknown>): Promise<Error> =>
+  call.then(
+    () => {
+      throw new Error("expected the call to fail");
+    },
+    (error: Error) => error,
+  );
+
+function upstream(body: unknown, status = 200) {
+  return vi.fn(
+    async (_input: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+}
+
+const config = { baseUrl: "https://store.example.com/", apiKey: "key", originHeader: "origin" };
+
+beforeEach(() => {
+  instrumented.providers.length = 0;
+  instrumented.operations.length = 0;
+});
+
+describe("createMagentoClient", () => {
+  it("calls REST with the store credentials, labeled by operation", async () => {
+    const fetch = upstream({ id: 7 });
+    const magento = createMagentoClient(config, { fetch });
+
+    expect(
+      await magento.rest<{ id: number }>("/rest/default/V1/carts/7", { operation: "getCart" }),
+    ).toEqual({ id: 7 });
+    expect(instrumented.providers).toEqual(["magento"]);
+    expect(instrumented.operations).toEqual(["getCart"]);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://store.example.com/rest/default/V1/carts/7");
+    const headers = new Headers(init?.headers);
+    expect(headers.get("authorization")).toBe("Bearer key");
+    expect(headers.get("x-origin-header")).toBe("origin");
+  });
+
+  it("omits the token when a call opts out", async () => {
+    const fetch = upstream({});
+    const magento = createMagentoClient(config, { fetch });
+    await magento.request("/customer/section/load", {
+      operation: "loadSections",
+      authenticated: false,
+    });
+    expect(new Headers(fetch.mock.calls[0]![1]?.headers).get("authorization")).toBeNull();
+  });
+
+  it("refuses URLs on another origin, so the token never leaves the store", async () => {
+    const fetch = upstream({});
+    const magento = createMagentoClient(config, { fetch });
+    await expect(magento.request("https://evil.example/steal", { operation: "x" })).rejects.toThrow(
+      /only paths on the configured store/,
+    );
+    await expect(magento.request("//evil.example/steal", { operation: "x" })).rejects.toThrow(
+      /only paths on the configured store/,
+    );
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("keeps a customer Authorization header instead of the store's token", async () => {
+    const fetch = upstream({ data: { customer: { email: "a" } }, items: [] });
+    const magento = createMagentoClient(config, { fetch });
+    await magento.graphql("query Customer { customer { email } }", undefined, {
+      operationName: "Customer",
+      headers: { Authorization: "Bearer customer" },
+    });
+    await magento.rest("/rest/default/V1/carts/mine", {
+      operation: "getCart",
+      headers: { Authorization: "Bearer customer" },
+    });
+    for (const [, init] of fetch.mock.calls) {
+      expect(new Headers(init?.headers).get("authorization")).toBe("Bearer customer");
+    }
+  });
+
+  it("sends GraphQL without the store's token unless asked, and keeps the JSON content type", async () => {
+    const fetch = upstream({ data: {} });
+    const magento = createMagentoClient(config, { fetch });
+    await magento.graphql("query Q { a }", undefined, {
+      operationName: "Q",
+      headers: { "Content-Type": "text/plain" },
+    });
+    await magento.graphql("query Q { a }", undefined, { operationName: "Q", authenticated: true });
+    const [first, second] = fetch.mock.calls.map(([, init]) => new Headers(init?.headers));
+    expect(first!.get("authorization")).toBeNull();
+    expect(first!.get("content-type")).toBe("application/json");
+    expect(second!.get("authorization")).toBe("Bearer key");
+  });
+
+  it("returns undefined for a 204 REST response", async () => {
+    const fetch = vi.fn(async () => new Response(null, { status: 204 }));
+    const magento = createMagentoClient(config, { fetch });
+    await expect(
+      magento.rest("/rest/default/V1/carts/mine/items/1", {
+        operation: "removeCartItem",
+        method: "DELETE",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("sends GraphQL with its operationName, which is the label", async () => {
+    const fetch = upstream({ data: { productStockAlert: { status: true } } });
+    const magento = createMagentoClient(config, { fetch });
+    const data = await magento.graphql<{ productStockAlert: { status: boolean } }>(
+      "mutation ProductStockAlert($sku: String!) { productStockAlert(sku: $sku) { status } }",
+      { sku: "A1" },
+      { operationName: "ProductStockAlert", headers: { Store: "default" } },
+    );
+    expect(data.productStockAlert.status).toBe(true);
+    expect(instrumented.operations).toEqual(["ProductStockAlert"]);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://store.example.com/graphql");
+    expect(new Headers(init?.headers).get("store")).toBe("default");
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      operationName: "ProductStockAlert",
+      variables: { sku: "A1" },
+    });
+  });
+
+  it("throws a MagentoError without the body", async () => {
+    const magento = createMagentoClient(config, {
+      fetch: upstream({ message: "token key invalid" }, 401),
+    });
+    const error = await failure(magento.rest("/rest/V1/carts/mine", { operation: "getCart" }));
+    expect(error).toBeInstanceOf(MagentoError);
+    expect(error.message).toBe("magento getCart failed with HTTP 401");
+
+    const gql = createMagentoClient(config, {
+      fetch: upstream({ errors: [{ message: "x@example.com" }] }),
+    });
+    const gqlError = await failure(gql.graphql("query Q { a }", undefined, { operationName: "Q" }));
+    expect(gqlError.message).toBe("magento Q returned 1 GraphQL error(s)");
+  });
+});

package/src/client.ts

@@ -15,6 +15,8 @@
  *     Magento has consistent muscle memory.
  */
 
+import { type FetchFn, withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
+
 // ---------------------------------------------------------------------------
 // Config shapes
 // ---------------------------------------------------------------------------
@@ -56,7 +58,7 @@ export interface MagentoCartConfigs {
 }
 
 export interface MagentoConfig {
-	/** Magento storefront base URL, e.g. `https://loja.granado.com.br/` */
+	/** Magento storefront base URL, e.g. `https://loja.acme.com.br/` */
 	baseUrl: string;
 	/** Bearer token for `Authorization` header on admin REST calls */
 	apiKey: string;
@@ -88,6 +90,28 @@ export interface MagentoConfig {
 
 let config: MagentoConfig | null = null;
 
+/**
+ * Underlying fetch used by {@link magentoFetch}. Defaults to `globalThis.fetch`;
+ * override once at boot with {@link setMagentoFetch} to plug in the instrumented
+ * fetch (spans + `http.client.request.duration` histogram, `provider:"magento"`).
+ * Mirrors VTEX's `setVtexFetch` / Shopify's `setShopifyFetch` so every commerce
+ * app funnels egress through a single instrumented `_fetch`.
+ */
+let _fetch: FetchFn = withFetchTimeout();
+
+/**
+ * Override the fetch used by every Magento egress call.
+ *
+ * @example
+ * ```ts
+ * import { createMagentoFetch, setMagentoFetch } from "@decocms/apps/magento";
+ * setMagentoFetch(createMagentoFetch());
+ * ```
+ */
+export function setMagentoFetch(fetchFn: FetchFn): void {
+	_fetch = fetchFn;
+}
+
 export function configureMagento(c: MagentoConfig): void {
 	config = c;
 }
@@ -224,5 +248,5 @@ export function magentoFetch(path: string, opts: MagentoFetchOpts = {}): Promise
 	// clarity at the call site.
 	const sameOrigin = target.origin === baseUrl.origin;
 
-	return fetch(target, { ...opts, headers: buildHeaders(opts, c, sameOrigin) });
+	return _fetch(target, { ...opts, headers: buildHeaders(opts, c, sameOrigin) });
 }

package/src/index.ts

@@ -1,3 +1,6 @@
+// v8: the thin Magento client (see /next/upstream-clients).
+
+// v7 (kept for v7 consumers until the v7 modules are dropped)
 /**
  * Magento app entry point for @decocms/apps.
  * Re-exports client config + initializer.
@@ -8,4 +11,26 @@
  *   import { magentoFetch } from "@decocms/apps/magento/client"
  */
 export * from "./client";
+export {
+  createMagentoClient,
+  type MagentoClient,
+  type MagentoClientConfig,
+  type MagentoClientOptions,
+  MagentoError,
+  type MagentoRequestInit,
+} from "./magentoClient";
 export type { MagentoCart } from "./types";
+export {
+  clearFetchCache,
+  type FetchCacheOptions,
+  getFetchCacheStats,
+  magentoCachedFetch,
+} from "./utils/fetchCache";
+// Observability wiring — sites call `setMagentoFetch(createMagentoFetch())` at
+// boot to route every Magento egress call through the instrumented fetch
+// (upstream latency/status), and use `magentoCachedFetch` for cacheable GETs
+// (SWR hit/miss → `deco.cache.requests{layer="swr",profile="magento"}`).
+export {
+  type CreateMagentoFetchOptions,
+  createMagentoFetch,
+} from "./utils/instrumentedFetch";

package/src/magentoClient.ts

@@ -0,0 +1,129 @@
+/**
+ * The Magento client: a thin client for a Magento store's REST and GraphQL
+ * APIs, over the framework's instrumented fetch (provider "magento"). See
+ * /next/upstream-clients.
+ *
+ * Configuration comes in as arguments; the site reads its environment (or a
+ * `secret` block) where it creates the client. Converters, hooks, cart and
+ * session flows, caching and feature toggles belong to the site (platform
+ * templates), not here.
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+
+export interface MagentoClientConfig {
+  /** The store's origin, e.g. `https://store.example.com`. Every request goes here. */
+  baseUrl: string;
+  /** Integration access token, sent as `Authorization: Bearer` unless a call opts out. */
+  apiKey?: string;
+  /** Optional value sent as `x-origin-header`, for stores behind an origin guard. */
+  originHeader?: string;
+}
+
+export interface MagentoClientOptions {
+  /** The fetch underneath, e.g. a fake in tests. Defaults to `globalThis.fetch`. */
+  fetch?: Parameters<typeof createInstrumentedFetch>[0]["fetch"];
+}
+
+export interface MagentoRequestInit extends RequestInit {
+  /** The operation label, the API's own name for the call (e.g. `getCart`), never a URL. */
+  operation: string;
+  /**
+   * Send the `apiKey` bearer token. Default true for `request`/`rest`, false
+   * for `graphql`. Never replaces an `Authorization` header the call sets
+   * (e.g. a customer token).
+   */
+  authenticated?: boolean;
+}
+
+/** Thrown on a non-2xx response or a GraphQL `errors` payload. Never carries bodies or tokens. */
+export class MagentoError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly status: number,
+    /** How many GraphQL errors the response carried (0 for an HTTP failure). */
+    readonly graphqlErrors = 0,
+  ) {
+    super(
+      graphqlErrors > 0
+        ? `magento ${operation} returned ${graphqlErrors} GraphQL error(s)`
+        : `magento ${operation} failed with HTTP ${status}`,
+    );
+    this.name = "MagentoError";
+  }
+}
+
+export type MagentoClient = ReturnType<typeof createMagentoClient>;
+
+export function createMagentoClient(
+  config: MagentoClientConfig,
+  options: MagentoClientOptions = {},
+) {
+  const instrumented = createInstrumentedFetch({ provider: "magento", fetch: options.fetch });
+  const origin = new URL(config.baseUrl).origin;
+
+  /**
+   * A request to a path on the store, e.g. `/rest/default/V1/carts/mine` or
+   * `/customer/section/load`, returning the raw response. Paths only: the
+   * store's credentials never go to another origin.
+   */
+  async function request(path: string, init: MagentoRequestInit): Promise<Response> {
+    const { operation, authenticated = true, ...rest } = init;
+    const url = new URL(path, origin);
+    if (url.origin !== origin) {
+      throw new Error(`magento ${operation}: only paths on the configured store are allowed`);
+    }
+    const headers = new Headers(rest.headers);
+    if (authenticated && config.apiKey && !headers.has("authorization")) {
+      headers.set("authorization", `Bearer ${config.apiKey}`);
+    }
+    if (config.originHeader) headers.set("x-origin-header", config.originHeader);
+    return instrumented(url, { ...rest, headers, operation });
+  }
+
+  return {
+    request,
+
+    /** A REST call (`/rest/<store>/V1/...`) returning its parsed JSON body. */
+    async rest<T>(path: string, init: MagentoRequestInit): Promise<T> {
+      const headers = new Headers(init.headers);
+      if (init.body !== undefined && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+      const response = await request(path, { ...init, headers });
+      if (!response.ok) throw new MagentoError(init.operation, response.status);
+      if (response.status === 204) return undefined as T;
+      return (await response.json()) as T;
+    },
+
+    /**
+     * A GraphQL operation on `/graphql`. `operationName` is sent with the
+     * request and is the operation label. `headers` adds per-call headers,
+     * such as `Store` or a customer `Authorization` token. Storefront
+     * GraphQL is public, so the `apiKey` is sent only with
+     * `authenticated: true`, and never over a customer token.
+     */
+    async graphql<TData, TVariables = Record<string, unknown>>(
+      query: string,
+      variables: TVariables | undefined,
+      init: { operationName: string; headers?: Record<string, string>; authenticated?: boolean },
+    ): Promise<TData> {
+      const { operationName, ...rest } = init;
+      const headers = new Headers(rest.headers);
+      headers.set("content-type", "application/json");
+      const response = await request("/graphql", {
+        operation: operationName,
+        authenticated: rest.authenticated ?? false,
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query, variables, operationName }),
+      });
+      if (!response.ok) throw new MagentoError(operationName, response.status);
+      const body = (await response.json()) as { data?: TData; errors?: unknown[] };
+      if (body.errors?.length) {
+        throw new MagentoError(operationName, response.status, body.errors.length);
+      }
+      if (body.data === undefined) throw new MagentoError(operationName, response.status);
+      return body.data;
+    },
+  };
+}

package/src/middleware.ts

@@ -5,8 +5,8 @@
  * after checkout (`changeCardIdAfterCheckout`) and seeded the
  * `form_key` for anonymous sessions. Both flows touched response
  * headers and `customer/section/load` endpoints — non-trivial port,
- * deferred to a follow-up PR. Today the consumer site (granadobr-
- * tanstack) handles cart reconciliation on the client.
+ * deferred to a follow-up PR. Today a production Magento storefront
+ * handles cart reconciliation on the client.
  *
  * Shape matches `@decocms/apps-commerce/app-types` so it can be
  * plugged into the autoconfig pipeline once magento is registered

package/src/utils/__tests__/instrumentation.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Coverage for the Magento observability wiring added so cache/upstream
+ * telemetry flows automatically:
+ *   - `magentoOperationRouter` names REST resources + GraphQL.
+ *   - `setMagentoFetch` actually reroutes `magentoFetch`'s egress (the hook
+ *     that lets `createMagentoFetch()`'s instrumentation take effect).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { magentoOperationRouter } from "../operationRouter";
+
+describe("magentoOperationRouter", () => {
+  it("names REST resources by their first V1 segment", () => {
+    expect(magentoOperationRouter("https://x.com/rest/default/V1/products/42", "GET")).toBe(
+      "rest.products",
+    );
+    expect(magentoOperationRouter("https://x.com/rest/V1/carts/mine", "POST")).toBe("rest.carts");
+  });
+
+  it("names GraphQL calls `graphql`", () => {
+    expect(magentoOperationRouter("https://x.com/graphql", "POST")).toBe("graphql");
+  });
+
+  it("returns undefined when nothing matches (framework falls back)", () => {
+    expect(magentoOperationRouter("https://x.com/media/logo.png", "GET")).toBeUndefined();
+  });
+
+  it("tolerates non-absolute URLs", () => {
+    expect(magentoOperationRouter("/rest/default/V1/orders?x=1", "GET")).toBe("rest.orders");
+  });
+});
+
+describe("setMagentoFetch routing", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("routes magentoFetch egress through the fetch set via setMagentoFetch", async () => {
+    const { configureMagento, setMagentoFetch, magentoFetch } = await import("../../client");
+    configureMagento({
+      baseUrl: "https://loja.example.com/",
+      apiKey: "k",
+      storeId: 1,
+      site: "example",
+    });
+    const custom = vi
+      .fn()
+      .mockResolvedValue(new Response("{}", { status: 200 })) as unknown as typeof fetch;
+    const globalSpy = vi.spyOn(globalThis, "fetch");
+    setMagentoFetch(custom);
+
+    await magentoFetch("/rest/default/V1/products/1");
+
+    expect(custom).toHaveBeenCalledOnce();
+    expect(globalSpy).not.toHaveBeenCalled(); // did NOT hit the default fetch
+  });
+});

package/src/utils/client/types.ts

@@ -24,7 +24,7 @@ export interface Customer {
 }
 
 /**
- * `carbono-customer` slice. Granado-specific overlay that mirrors the
+ * `carbono-customer` slice. A storefront-specific overlay that mirrors the
  * `customer` slice plus a website/store id pair and a normalized email.
  * Other magento sites that don't run the Carbono module will get this
  * absent; loaders/user.ts checks for it before mapping to a Person.

package/src/utils/constants.ts

@@ -12,6 +12,31 @@
 
 import type { FiltersGraphQL } from "../client";
 
+// ---------------------------------------------------------------------------
+// SWR fetch-cache tuning (consumed by utils/fetchCache.ts via the shared
+// `createFetchCache` in @decocms/blocks/sdk/fetchCache). Mirrors the shape of
+// VTEX's constants so Magento's cache posture is tuned in one place.
+// ---------------------------------------------------------------------------
+
+/** Max distinct cache keys kept in memory; oldest `createdAt` evicted first. */
+export const FETCH_CACHE_MAX_ENTRIES = 500;
+
+/** How long a cached Magento response stays FRESH, keyed by status class. */
+export const FETCH_CACHE_FRESH_TTL_MS = {
+	/** 2xx — 3 min. Catalog/price data doesn't need to be second-fresh. */
+	success: 180_000,
+	/** 404 — 10s. A just-published product shouldn't 404 for long. */
+	notFound: 10_000,
+	/** 5xx — never treated as a good cache hit. */
+	serverError: 0,
+} as const;
+
+/** Stale-if-error window: serve last-good this long past freshness on outage. */
+export const FETCH_CACHE_STALE_IF_ERROR_MS = 86_400_000; // 24h
+
+/** Inflight-slot backstop: bounds how long one hung fetch holds a dedup slot. */
+export const FETCH_CACHE_INFLIGHT_BACKSTOP_MS = 15_000;
+
 export const URL_KEY = "url_key";
 
 // Schema.org availability mapping (used by utils/transform.ts to

package/src/utils/fetchCache.ts

@@ -0,0 +1,55 @@
+/**
+ * Magento SWR fetch cache — a thin binding over the shared, instrumented
+ * `createFetchCache` in `@decocms/blocks/sdk/fetchCache`.
+ *
+ * Same shared implementation VTEX uses (in-flight dedup, stale-while-
+ * revalidate, stale-if-error, inflight backstop), wired with Magento's tuning
+ * constants and the `provider: "magento"` label. Every call emits
+ * `deco.cache.requests{layer="swr",profile="magento"}` automatically.
+ *
+ * Cache key is caller-supplied (not required to be a URL): REST GETs key by
+ * their URL; GraphQL POSTs can key by a hash of `query + variables`. Callers
+ * pass the closure that performs the actual `magentoFetch`, so a HIT never
+ * touches the network.
+ */
+
+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: "magento",
+  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 Magento GET with SWR caching + in-flight dedup. Returns the parsed
+ * JSON body, or `null` for cacheable non-2xx responses (e.g. 404). 5xx throw.
+ */
+export function magentoCachedFetch<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/instrumentedFetch.ts

@@ -0,0 +1,57 @@
+/**
+ * Pre-wired instrumented fetch factory for Magento.
+ *
+ * Mirrors `vtex/utils/instrumentedFetch.ts` and `shopify/utils/instrumentedFetch.ts`.
+ * Bundles:
+ *
+ *   1. `createInstrumentedFetch` from `@decocms/blocks/sdk/instrumentedFetch`
+ *      (spans, traceparent injection, URL redaction, cache-header span attrs).
+ *   2. `magentoOperationRouter` as the URL→operation fallback.
+ *   3. An `onComplete` that records the canonical
+ *      `http.client.request.duration` histogram via the framework's
+ *      `recordCommerceMetric(...)` helper with `provider: "magento"`.
+ *
+ * Sites opt in once at startup:
+ *
+ *   ```ts
+ *   import { createMagentoFetch, setMagentoFetch } from "@decocms/apps/magento";
+ *   setMagentoFetch(createMagentoFetch());
+ *   ```
+ *
+ * With this wired, every Magento egress call (GraphQL + REST) funnels through
+ * one instrumented boundary, so upstream latency/status lands in ClickHouse.
+ * SWR hit/miss for cached GETs is emitted separately by
+ * `@decocms/blocks/sdk/fetchCache` (see `./fetchCache.ts`).
+ */
+
+import {
+  createInstrumentedFetch,
+  type InstrumentedFetch,
+} from "@decocms/blocks/sdk/instrumentedFetch";
+import { recordCommerceMetric, statusClassFor } from "@decocms/blocks/sdk/observability";
+import { magentoOperationRouter } from "./operationRouter";
+
+export interface CreateMagentoFetchOptions {
+  /** Underlying fetch to wrap. Defaults to `globalThis.fetch`. */
+  baseFetch?: typeof fetch;
+  /**
+   * Disable the `http.client.request.duration` histogram for Magento calls.
+   * Spans + structured logs still emit. Default: false.
+   */
+  disableHistogram?: boolean;
+}
+
+/**
+ * Construct a pre-wired Magento `InstrumentedFetch`. Pass the result to
+ * `setMagentoFetch(...)`.
+ */
+export function createMagentoFetch(options: CreateMagentoFetchOptions = {}): InstrumentedFetch {
+  const { baseFetch, disableHistogram = false } = options;
+  return createInstrumentedFetch({
+    name: "magento",
+    baseFetch,
+    resolveOperation: magentoOperationRouter,
+    onComplete: disableHistogram ? undefined : (r) =>
+      recordCommerceMetric(r.durationMs, { provider: "magento", operation: r.operation, status_class: statusClassFor(r.status), cached: r.cached }),
+  });
+}

package/src/utils/operationRouter.ts

@@ -0,0 +1,43 @@
+/**
+ * URL-derived operation name router for Magento API calls.
+ *
+ * Plugged into `@decocms/blocks/sdk/instrumentedFetch`'s `resolveOperation`
+ * option. Mirrors the VTEX/Shopify routers. Magento's surface from this repo is
+ * a mix of GraphQL (`/graphql`) and REST (`/rest/<store>/V1/...`); the URL alone
+ * can name the REST resource, while GraphQL calls fall back to a single
+ * `graphql` operation (the semantic name lives in the document body, which
+ * callers may stamp as `init.operation` to override this router).
+ */
+
+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(/\/graphql\b/, "graphql"),
+  // REST: /rest/<storeCode>/V1/<resource>/... — name by the first resource segment.
+  m(/\/rest\/[^/]+\/V1\/([^/?#]+)/, (match) => `rest.${match[1]}`),
+  m(/\/rest\/V1\/([^/?#]+)/, (match) => `rest.${match[1]}`),
+];
+
+/**
+ * Resolve an operation name for a Magento URL. Returns `undefined` when no
+ * matcher fires, so the framework falls back to `magento.fetch`.
+ */
+import { extractPathname } from "@decocms/blocks/sdk/urlUtils";
+
+export function magentoOperationRouter(url: string, _method: string): string | undefined {
+  const pathname = extractPathname(url);
+
+  for (const { pattern, operation } of MATCHERS) {
+    const match = pathname.match(pattern);
+    if (!match) continue;
+    return typeof operation === "function" ? operation(match, _method) : operation;
+  }
+  return undefined;
+}

package/src/utils/transform.ts

@@ -6,8 +6,8 @@
  * Subset of `deco-cx/apps/magento/utils/transform.ts` — only the
  * functions the PDP loader needs (toProduct, toOffer, toImages, toURL,
  * toBreadcrumbList, toSeo). The GraphQL-side helpers (toProductGraphQL,
- * toAggOfferGraphQL, toProductListingPageGraphQL, …) and the Granado-
- * specific helpers (toReviewAmasty, toLiveloPoints) are intentionally
+ * toAggOfferGraphQL, toProductListingPageGraphQL, …) and the
+ * storefront-specific helpers (toReviewAmasty, toLiveloPoints) are intentionally
  * excluded — they land in separate follow-up PRs alongside the loaders
  * that consume them.
  *