@decocms/apps-magento 7.31.6 → 7.32.0

package/package.json

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

package/src/client.ts

@@ -88,6 +88,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: typeof fetch | undefined;
+
+/**
+ * Override the fetch used by every Magento egress call.
+ *
+ * @example
+ * ```ts
+ * import { createMagentoFetch, setMagentoFetch } from "@decocms/apps/magento";
+ * setMagentoFetch(createMagentoFetch());
+ * ```
+ */
+export function setMagentoFetch(fetchFn: typeof fetch): void {
+	_fetch = fetchFn;
+}
+
 export function configureMagento(c: MagentoConfig): void {
 	config = c;
 }
@@ -224,5 +246,6 @@ 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) });
+	const doFetch = _fetch ?? globalThis.fetch;
+	return doFetch(target, { ...opts, headers: buildHeaders(opts, c, sameOrigin) });
 }

package/src/index.ts

@@ -9,3 +9,17 @@
  */
 export * from "./client";
 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/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/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;
+}