@decocms/apps-magento 7.2.0

package/src/utils/graphql.ts

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

@@ -0,0 +1,62 @@
+/**
+ * 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;
+}

package/src/utils/transform.ts

@@ -0,0 +1,283 @@
+/**
+ * Magento product transform helpers — maps the REST/GraphQL payloads
+ * into schema.org `Product` / `Offer` / `Seo` shapes that
+ * `@decocms/apps-commerce` consumers expect.
+ *
+ * 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
+ * excluded — they land in separate follow-up PRs alongside the loaders
+ * that consume them.
+ *
+ * Behavior is pinned by `__tests__/transform.test.ts`. Every change to
+ * this file should ship a regression test.
+ */
+
+import type {
+	ImageObject,
+	ListItem,
+	Offer,
+	Product,
+	PropertyValue,
+	Seo,
+	UnitPriceSpecification,
+} from "@decocms/apps-commerce/types";
+import type { CustomAttribute, MagentoCategory, MagentoProduct } from "./client/types";
+import { IN_STOCK, OUT_OF_STOCK } from "./constants";
+
+// ---------------------------------------------------------------------------
+// Product → schema.org Product
+// ---------------------------------------------------------------------------
+
+export const toProduct = ({
+	product,
+	options,
+}: {
+	product: MagentoProduct;
+	options: {
+		currencyCode?: string;
+		imagesUrl?: string;
+		maxInstallments: number;
+		minInstallmentValue: number;
+	};
+}): Product => {
+	const offers = toOffer(product, options.minInstallmentValue, options.maxInstallments);
+	const sku = product.sku;
+	const productID = product.id.toString();
+	const productPrice = product.price_info;
+
+	const additionalProperty: PropertyValue[] = product.custom_attributes?.map((attr) => ({
+		"@type": "PropertyValue",
+		name: attr.attribute_code,
+		value: String(attr.value),
+	}));
+
+	return {
+		"@type": "Product",
+		productID,
+		sku,
+		url: product.url,
+		name: product.name,
+		gtin: sku,
+		isVariantOf: {
+			"@type": "ProductGroup",
+			productGroupID: productID,
+			url: product.url,
+			name: product.name,
+			model: "",
+			additionalProperty: additionalProperty,
+			hasVariant: [
+				{
+					"@type": "Product",
+					productID,
+					sku,
+					url: product.url,
+					name: product.name,
+					gtin: sku,
+					offers: {
+						"@type": "AggregateOffer",
+						// biome-ignore lint/style/noNonNullAssertion: matches prod fallback to price
+						highPrice: productPrice?.max_price ?? product.price!,
+						// biome-ignore lint/style/noNonNullAssertion: matches prod fallback to price
+						lowPrice: productPrice?.minimal_price ?? product.price!,
+						offerCount: offers.length,
+						offers: offers,
+					},
+				},
+			],
+		},
+		additionalProperty: additionalProperty,
+		image: toImages(product, options.imagesUrl ?? ""),
+		offers: {
+			"@type": "AggregateOffer",
+			// biome-ignore lint/style/noNonNullAssertion: matches prod fallback to price
+			highPrice: productPrice?.max_price ?? product.price!,
+			// biome-ignore lint/style/noNonNullAssertion: matches prod fallback to price
+			lowPrice: productPrice?.minimal_price ?? product.price!,
+			offerCount: offers.length,
+			offers: offers,
+		},
+	};
+};
+
+// ---------------------------------------------------------------------------
+// Product → Offer[]
+// ---------------------------------------------------------------------------
+
+export const toOffer = (
+	{ price_info, extension_attributes, sku, currency_code }: MagentoProduct,
+	minInstallmentValue: number,
+	maxInstallments: number,
+): Offer[] => {
+	if (!price_info) {
+		return [];
+	}
+	const { final_price, max_price, max_regular_price } = price_info;
+	const { stock_item } = extension_attributes;
+	const inStock = stock_item?.is_in_stock;
+	const qtyStock = stock_item?.qty ?? 0;
+
+	return [
+		{
+			"@type": "Offer",
+			availability: inStock ? IN_STOCK : OUT_OF_STOCK,
+			inventoryLevel: {
+				value: inStock ? qtyStock || 999 : 0,
+			},
+			itemCondition: "https://schema.org/NewCondition",
+			price: final_price,
+			priceCurrency: currency_code,
+			priceSpecification: [
+				{
+					"@type": "UnitPriceSpecification",
+					priceType: "https://schema.org/ListPrice",
+					price: max_price ?? max_regular_price,
+				},
+				{
+					"@type": "UnitPriceSpecification",
+					priceType: "https://schema.org/SalePrice",
+					price: final_price,
+				},
+				...calculateInstallments(final_price, minInstallmentValue, maxInstallments),
+			],
+			sku: sku,
+		},
+	];
+};
+
+/**
+ * Build the installment ladder for a sale price. `À vista` is always
+ * the first entry, then 2x..Nx where N is bounded by
+ * `min(floor(finalPrice/minInstallmentValue), maxInstallments)`.
+ * Each entry is a `UnitPriceSpecification` so storefront UIs render
+ * "10x de R$ 12,50 sem juros" without further math.
+ */
+const calculateInstallments = (
+	finalPrice: number,
+	minInstallmentValue: number,
+	maxInstallments: number,
+): UnitPriceSpecification[] => {
+	const possibleInstallmentsCount = Math.floor(finalPrice / minInstallmentValue) || 1;
+	const actualInstallmentsCount = Array.from(
+		{ length: Math.min(possibleInstallmentsCount, maxInstallments) },
+		(_v, i) => +(finalPrice / (i + 1)).toFixed(2),
+	);
+
+	return actualInstallmentsCount.map<UnitPriceSpecification>((value, i) => {
+		const [description, billingIncrement] = !i
+			? ["À vista", finalPrice]
+			: [`${i + 1}x sem juros`, value];
+		return {
+			"@type": "UnitPriceSpecification",
+			priceType: "https://schema.org/SalePrice",
+			priceComponentType: "https://schema.org/Installment",
+			description,
+			billingDuration: i + 1,
+			billingIncrement,
+			price: finalPrice,
+		};
+	});
+};
+
+// ---------------------------------------------------------------------------
+// Product → ImageObject[]
+// ---------------------------------------------------------------------------
+
+export const toImages = (product: MagentoProduct, imageUrl: string): ImageObject[] | undefined => {
+	if (imageUrl) {
+		return product.media_gallery_entries?.map((img) => ({
+			"@type": "ImageObject" as const,
+			encodingFormat: "image",
+			alternateName: `${img.file}`,
+			url: `${toURL(imageUrl)}${img.file}`,
+			disabled: img.disabled || false,
+		}));
+	}
+
+	return product.images?.map((img) => ({
+		"@type": "ImageObject" as const,
+		encodingFormat: "image",
+		alternateName: `${img.label}`,
+		disabled: img.disabled || false,
+		url: `${img.url}`,
+	}));
+};
+
+/**
+ * Protocol-relative URLs (`//cdn.magento.example/...`) come back from
+ * some Magento installations. Promote to https so the browser doesn't
+ * try to inherit a non-https scheme.
+ */
+export const toURL = (src: string): string => (src.startsWith("//") ? `https:${src}` : src);
+
+// ---------------------------------------------------------------------------
+// Categories → ListItem[] (breadcrumb)
+// ---------------------------------------------------------------------------
+
+export const toBreadcrumbList = (
+	categories: (MagentoCategory | null)[],
+	isBreadcrumbProductName: boolean,
+	product: Product,
+	url: URL,
+): ListItem<string>[] => {
+	if (isBreadcrumbProductName && categories?.length === 0) {
+		return [
+			{
+				"@type": "ListItem",
+				name: product.name,
+				position: 1,
+				item: new URL(`/${product.name}`, url).href,
+			},
+		];
+	}
+
+	const itemListElement = categories
+		.map((category) => {
+			if (!category || !category.name || !category.position) {
+				return null;
+			}
+			return {
+				"@type": "ListItem",
+				name: category.name,
+				position: category.position,
+				item: new URL(`/${category.name}`, url).href,
+			};
+		})
+		.filter(Boolean) as ListItem<string>[];
+
+	return itemListElement;
+};
+
+// ---------------------------------------------------------------------------
+// Custom attributes → Seo
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `Seo` block from a product's custom_attributes. Magento
+ * exposes title/meta_title/meta_description as separate attribute_code
+ * entries; this maps them with explicit fallback (meta_title wins over
+ * title; description is meta_description only — there's no fallback
+ * field in the legacy code).
+ */
+export const toSeo = (customAttributes: CustomAttribute[], productURL: string): Seo => {
+	const findAttribute = (attrCode: string): string => {
+		const attribute = customAttributes.find((attr) => attr.attribute_code === attrCode);
+		if (!attribute) return "";
+		if (Array.isArray(attribute.value)) {
+			return attribute.value.join(", ");
+		}
+		return attribute.value;
+	};
+
+	const title = findAttribute("title");
+	const metaTitle = findAttribute("meta_title");
+	const metaDescription = findAttribute("meta_description");
+
+	return {
+		title: metaTitle || title || "",
+		description: metaDescription || "",
+		canonical: productURL,
+	};
+};

package/src/utils/user.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads the Magento PHP session cookie from a request's headers.
+ * Returns undefined when the cookie is absent (anonymous visitor).
+ *
+ * Mirrors `deco-cx/apps/magento/utils/user.ts` — the Fresh version
+ * used Deno's `std/http/cookie` getCookies; the port goes through
+ * `@decocms/blocks/sdk/cookie` so it works on Cloudflare Workers and
+ * Node alike.
+ */
+import { getCookies } from "@decocms/blocks/sdk/cookie";
+import { SESSION_COOKIE } from "./constants";
+
+export const getUserCookie = (headers: Headers): string | undefined => {
+	const cookies = getCookies(headers);
+	return cookies[SESSION_COOKIE];
+};

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}