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

package/src/utils/fetchCache.ts

@@ -1,55 +0,0 @@
-/**
- * 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/graphql-types.ts

@@ -1,99 +0,0 @@
-/**
- * Magento GraphQL request input types used by the product loaders.
- *
- * Subset of `deco-cx/apps/magento/utils/clientGraphql/types.ts` that the
- * port has reached so far — extended as more loaders land. These mirror
- * Magento's GraphQL schema for product search/sort/filter so the
- * storefront's URL params translate cleanly into GraphQL variables.
- */
-
-/**
- * Magento ProductAttributeFilterInput shape — keys are Magento
- * attribute codes; values are one of the three filter-type unions.
- * Maps to: `filter: ProductAttributeFilterInput!`
- */
-export interface ProductFilterInput {
-	[key: string]: FilterEqualTypeInput | FilterMatchTypeInput | FilterRangeTypeInput;
-}
-
-/**
- * Magento `FilterEqualTypeInput` — for exact-match attributes (sku,
- * sale, color, size, etc.). `in` lets you OR multiple values; the
- * single-value `eq` form is also accepted by the Magento schema and is
- * the shape `transformFilterValueGraphQL` emits.
- */
-export interface FilterEqualTypeInput {
-	in?: string[];
-	eq?: string;
-}
-
-/**
- * Magento `FilterMatchTypeInput` — substring-match attributes (name,
- * description, short_description).
- */
-export interface FilterMatchTypeInput {
-	match: string;
-}
-
-/**
- * Magento `FilterRangeTypeInput` — numeric ranges (price). Both bounds
- * are strings in the schema; ranges in URL params come as `from_to`.
- */
-export interface FilterRangeTypeInput {
-	from: string;
-	to: string;
-}
-
-/**
- * Magento `ProductAttributeSortInput` — one entry per sortable
- * attribute keyed by attribute code, ordered ASC or DESC.
- */
-export interface ProductSortInput {
-	[key: string]: "ASC" | "DESC";
-}
-
-/**
- * Built-in sort options surfaced in the CMS admin. Custom options can
- * be added by sites via `CustomProductSortOption`.
- */
-export interface DefaultProductSortOption {
-	value: "name" | "position" | "price" | "relevance";
-}
-
-export interface CustomProductSortOption {
-	value: string;
-}
-
-/**
- * Shared sort-prop shape used by PLP / list / relatedProducts loaders.
- */
-export interface ProductSort {
-	/** @title Order by */
-	sortBy: DefaultProductSortOption | CustomProductSortOption;
-	/** @title Sequency */
-	order: "ASC" | "DESC";
-}
-
-/**
- * Loader-supplied filter (vs URL-derived). The site can hard-code
- * filters in the CMS section config and they layer on top of whatever
- * the user picked from URL params.
- */
-export interface FilterProps {
-	name: string;
-	type: FilterEqualTypeInput | FilterMatchTypeInput | FilterRangeTypeInput;
-}
-
-/**
- * Custom-fields toggle used by `getCustomFields()` to decide which
- * Magento product attributes to project from a query.
- */
-export interface CustomFields {
-	/**
-	 * @description Search for global custom fields defined in App settings
-	 * @default false
-	 */
-	active: boolean;
-	/** @description Will override global custom fields defined in App settings */
-	overrideList?: string[];
-}

package/src/utils/graphql.ts

@@ -1,155 +0,0 @@
-/**
- * GraphQL helpers for Magento product loaders.
- *
- * Ported from `deco-cx/apps/magento/utils/graphql.ts` (Fresh/Deno
- * prod). Pure functions — no I/O, no client state — so behavior is
- * pinned by `__tests__/graphql.test.ts` and shared across PDP, PLP,
- * list, and relatedProducts loaders.
- *
- *  - `transformSortGraphQL(ProductSort)` → `ProductSortInput`
- *  - `transformFilterGraphQL(url, customFilters, fromLoader)` →
- *    `ProductFilterInput` — merges URL-derived + loader-derived filters.
- *  - `transformFilterValueGraphQL(value, type)` → typed Filter*Input.
- *  - `formatUrlSuffix(str)` → ensures a path ends with `/` (used as
- *    `defaultPath` for the Magento URL rewrite resolver).
- *  - `getCustomFields(CustomFields, fallback)` → resolved custom
- *    attribute list for product projection.
- */
-
-import type { FiltersGraphQL } from "../client";
-import { DEFAULT_GRAPHQL_FILTERS } from "./constants";
-import type {
-	CustomFields,
-	FilterEqualTypeInput,
-	FilterMatchTypeInput,
-	FilterProps,
-	FilterRangeTypeInput,
-	ProductFilterInput,
-	ProductSort,
-	ProductSortInput,
-} from "./graphql-types";
-
-export const typeChecker = <T extends object>(v: T, prop: keyof T): boolean => prop in v;
-
-export const transformSortGraphQL = ({
-	sortBy,
-	order,
-}: Partial<ProductSort>): ProductSortInput | undefined => {
-	if (!sortBy) {
-		return undefined;
-	}
-	return {
-		[sortBy.value]: order ?? "ASC",
-	};
-};
-
-/**
- * Compose the GraphQL `filter` payload from two sources, in order:
- *
- *   1. URL search params crossed against `DEFAULT_GRAPHQL_FILTERS`
- *      (+ any `customFilters` the site extends with).
- *   2. Explicit `fromLoader` filters the CMS section pinned at config
- *      time.
- *
- * Loader-derived filters shadow URL-derived ones on key collisions
- * (intentional — a section that hard-codes `sale=true` should ignore
- * any conflicting URL hint).
- */
-export const transformFilterGraphQL = (
-	url: URL,
-	customFilters?: Array<FiltersGraphQL>,
-	fromLoader?: Array<FilterProps>,
-): ProductFilterInput | undefined => ({
-	...filtersFromUrlGraphQL(url, customFilters),
-	...filtersFromLoaderGraphQL(fromLoader),
-});
-
-export const filtersFromLoaderGraphQL = (
-	fromLoader?: Array<FilterProps>,
-): ProductFilterInput | undefined =>
-	fromLoader?.reduce<ProductFilterInput>(
-		(acc, f) => ({
-			...acc,
-			[f.name]: f.type,
-		}),
-		{},
-	) ?? {};
-
-export const filtersFromUrlGraphQL = (
-	url: URL,
-	customFilters?: Array<FiltersGraphQL>,
-): ProductFilterInput =>
-	DEFAULT_GRAPHQL_FILTERS.concat(customFilters ?? []).reduce<ProductFilterInput>(
-		(acc, { type, value }) => {
-			const fromUrl = url.searchParams.get(value);
-			if (!fromUrl) {
-				return acc;
-			}
-			return {
-				...acc,
-				[value]: transformFilterValueGraphQL(fromUrl, type),
-			};
-		},
-		{},
-	);
-
-export const transformFilterValueGraphQL = (
-	value: string,
-	type: "EQUAL" | "MATCH" | "RANGE",
-): FilterEqualTypeInput | FilterMatchTypeInput | FilterRangeTypeInput => {
-	if (type === "EQUAL") {
-		return { eq: value } as FilterEqualTypeInput;
-	}
-
-	if (type === "MATCH") {
-		return { match: value } as FilterMatchTypeInput;
-	}
-
-	if (type === "RANGE") {
-		const splitterIndex = value.indexOf("_");
-		return {
-			from: value.substring(0, splitterIndex),
-			to: value.substring(splitterIndex + 1),
-		} as FilterRangeTypeInput;
-	}
-
-	return {} as FilterEqualTypeInput;
-};
-
-/**
- * Normalize a URL path into the form Magento's
- * `urlResolver(url: "<path>/")` expects:
- *   - Strip a single leading slash (the resolver doesn't want it).
- *   - Ensure the path ends with `/`.
- *
- * Used by PLP / PDP / list / relatedProducts loaders as `defaultPath`
- * when `useSuffix` is enabled.
- */
-export const formatUrlSuffix = (str: string): string => {
-	let s = str;
-	if (s.startsWith("/")) s = s.slice(1);
-	if (!s.endsWith("/")) s = `${s}/`;
-	return s;
-};
-
-/**
- * Resolve which custom-attribute list a loader should request:
- *
- *  - disabled (`active: false`) → undefined (loader projects nothing custom).
- *  - explicit override list set → return that list as-is.
- *  - otherwise → fall back to the global list provided by the loader.
- */
-export const getCustomFields = (
-	{ active, overrideList }: CustomFields = { active: false, overrideList: [] },
-	customFields?: Array<string>,
-): Array<string> | undefined => {
-	if (!active) {
-		return undefined;
-	}
-
-	if (overrideList && overrideList.length > 0) {
-		return overrideList;
-	}
-
-	return customFields;
-};

package/src/utils/instrumentedFetch.ts

@@ -1,57 +0,0 @@
-/**
- * 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

@@ -1,43 +0,0 @@
-/**
- * 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/stringifySearchCriteria.ts

@@ -1,62 +0,0 @@
-/**
- * Flatten a Magento REST `searchCriteria` object into a bracketed
- * query-string key/value map.
- *
- * Magento's search-criteria payload is deeply nested (filterGroups →
- * filters → field/value), but the REST API accepts it only as flat
- * `searchCriteria[filterGroups][0][filters][0][field]=name` style
- * query parameters. This helper walks the tree once and emits that
- * shape.
- *
- * Ported verbatim from `deco-cx/apps/magento/utils/stringifySearchCriteria.ts`
- * — the Fresh implementation is self-contained (no Deno-isms) and
- * produces output that prod consumers already depend on. Behavior
- * pinned by `__tests__/stringifySearchCriteria.test.ts`.
- *
- * @example
- *   stringifySearchCriteria({
- *     filterGroups: [{ filters: [{ field: "sku", value: "ABC" }] }],
- *   })
- *   // ⇒ { "searchCriteria[filterGroups][0][filters][0][field]": "sku",
- *   //     "searchCriteria[filterGroups][0][filters][0][value]": "ABC" }
- */
-interface Filter {
-	field: string;
-	value: string;
-}
-
-interface FilterGroup {
-	[key: string]: Filter[];
-}
-
-interface SearchCriteria {
-	[key: string]: string | number | FilterGroup[];
-}
-
-type Path = string;
-type TraverseObj = SearchCriteria | FilterGroup[];
-
-function traverse(data: TraverseObj, result: Record<Path, string>, path: Path) {
-	if (Array.isArray(data)) {
-		data.forEach((item, index) => {
-			traverse(item as unknown as TraverseObj, result, `${path}[${index}]`);
-		});
-	} else if (typeof data === "object" && data !== null) {
-		for (const key in data) {
-			if (Object.hasOwn(data, key)) {
-				// @ts-expect-error recursive function with heterogeneous values
-				traverse(data[key], result, `${path}[${key}]`);
-			}
-		}
-	} else {
-		result[path] = data;
-	}
-}
-
-export default function stringifySearchCriteria(
-	searchCriteriaObj: SearchCriteria,
-): Record<Path, string> {
-	const result: Record<Path, string> = {};
-	traverse(searchCriteriaObj, result, "searchCriteria");
-	return result;
-}