@decocms/apps-magento 7.2.0

package/src/loaders/user.ts

@@ -0,0 +1,60 @@
+/**
+ * Resolves the current customer into a schema.org `Person` from
+ * Magento's `/customer/section/load?sections=customer,carbono-customer`
+ * endpoint, scoped by the visitor's PHPSESSID cookie.
+ *
+ * Ported from `deco-cx/apps/magento/loaders/user.ts`. The Fresh
+ * version used `clientAdmin["GET /:site/customer/section/load"]` with
+ * typed indexed routes — the TanStack/Node port uses `magentoFetch`
+ * (which already applies auth/origin headers for same-origin) plus an
+ * explicit `Cookie: PHPSESSID=…` header so Magento associates the
+ * request with the logged-in customer.
+ *
+ * Returns null when:
+ *  - the session cookie is absent (anonymous visitor — expected),
+ *  - the customer slice is missing or has no data_id (Magento returns
+ *    {} for guest sessions),
+ *  - the HTTP call throws or returns a non-2xx (defensive — the
+ *    storefront just renders the logged-out UI).
+ */
+import type { Person } from "@decocms/apps-commerce/types";
+import { getMagentoConfig, magentoFetch } from "../client";
+import type { CustomerSectionLoad } from "../utils/client/types";
+import { SESSION_COOKIE } from "../utils/constants";
+import { getUserCookie } from "../utils/user";
+
+export default async function user(_props: unknown, req: Request): Promise<Person | null> {
+	const sessionId = getUserCookie(req.headers);
+	if (!sessionId) return null;
+
+	const { site } = getMagentoConfig();
+	const path = `/${encodeURIComponent(site)}/customer/section/load?sections=customer,carbono-customer`;
+
+	try {
+		const res = await magentoFetch(path, {
+			headers: { Cookie: `${SESSION_COOKIE}=${sessionId}` },
+		});
+		if (!res.ok) return null;
+
+		const response = (await res.json()) as CustomerSectionLoad;
+		const carbono = response["carbono-customer"];
+		const customer = response.customer;
+
+		if (!carbono?.data_id || !customer) return null;
+
+		const { customerId, email } = carbono;
+		const { fullname, firstname } = customer;
+
+		return {
+			"@id": customerId,
+			email: email,
+			givenName: firstname,
+			...(firstname &&
+				fullname && {
+					familyName: fullname.replace(firstname, "").trim(),
+				}),
+		};
+	} catch {
+		return null;
+	}
+}

package/src/loaders/wishlist.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolves the visitor's saved wishlist via Magento's
+ * `/customer/section/load?sections=wishlist` endpoint, scoped by the
+ * PHPSESSID cookie.
+ *
+ * Ported from `deco-cx/apps/magento/loaders/wishlist.ts`. Returns null
+ * when the session cookie is absent or Magento reports no wishlist
+ * (e.g. a logged-in customer who never saved an item).
+ */
+import { getMagentoConfig, magentoFetch } from "../client";
+import type { CustomerSectionLoad, Wishlist } from "../utils/client/types";
+import { SESSION_COOKIE } from "../utils/constants";
+import { getUserCookie } from "../utils/user";
+
+export default async function wishlist(_props: unknown, req: Request): Promise<Wishlist | null> {
+	const sessionId = getUserCookie(req.headers);
+	if (!sessionId) return null;
+
+	const { site } = getMagentoConfig();
+	const path = `/${encodeURIComponent(site)}/customer/section/load?sections=wishlist`;
+
+	const res = await magentoFetch(path, {
+		headers: { Cookie: `${SESSION_COOKIE}=${sessionId}` },
+	});
+	if (!res.ok) return null;
+
+	const { wishlist } = (await res.json()) as CustomerSectionLoad;
+	return wishlist ?? null;
+}

package/src/middleware.ts

@@ -0,0 +1,19 @@
+/**
+ * Magento middleware — currently a passthrough.
+ *
+ * The legacy deco-cx/apps middleware reconciled the cart id cookie
+ * 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.
+ *
+ * Shape matches `@decocms/apps-commerce/app-types` so it can be
+ * plugged into the autoconfig pipeline once magento is registered
+ * there.
+ */
+import type { AppMiddleware } from "@decocms/apps-commerce/app-types";
+
+export const magentoMiddleware: AppMiddleware = async (_request, next) => {
+	return next();
+};

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared types for the Magento app — kept minimal in this initial port.
+ * Loader/action ports should extend this file rather than duplicating
+ * inline types.
+ */
+import type { MagentoFeatures } from "./client";
+
+export interface MagentoCart {
+	id: string | null;
+	items: MagentoCartItem[];
+	totals?: {
+		subtotal?: number;
+		grand_total?: number;
+		discount_amount?: number;
+		shipping_amount?: number;
+	};
+	coupon_code?: string | null;
+}
+
+export interface MagentoCartItem {
+	item_id: number;
+	sku: string;
+	name?: string;
+	qty: number;
+	price?: number;
+	row_total?: number;
+}
+
+export type Features = MagentoFeatures;
+
+/**
+ * Magento newsletter subscription response shape — what
+ * `actions/newsletter/subscribe` returns to the storefront.
+ */
+export interface NewsletterData {
+	success: boolean;
+	message: string;
+}
+
+/**
+ * Stock-alert mutation response from Magento's GraphQL endpoint —
+ * `actions/product/stockAlert` returns this (or `{ error }`).
+ */
+export interface ProductStockAlertResponse {
+	data?: {
+		productStockAlert: {
+			message: string;
+			status: boolean;
+		};
+	};
+}

package/src/utils/cacheTimeControl.ts

@@ -0,0 +1,69 @@
+/**
+ * Cache-time-control helpers — verbatim port of
+ * `deco-cx/apps/magento/utils/cacheTimeControl.ts`.
+ *
+ * Magento product loaders pass the request URL through
+ * `filterSearchParamsFromURL` before using it as a cache key, so that
+ * tracking parameters (utm_*, gclid, fbclid, etc.) don't fragment the
+ * cache across thousands of variants for what is conceptually the
+ * same page.
+ */
+
+export const DEFAULT_CACHE_MAX_AGE = 3600; // 1h
+
+/**
+ * Pattern list (each entry is a regex source) of URL search-param
+ * keys that get stripped before a Magento URL goes into the cache key
+ * or downstream search-criteria. Mirrors prod byte-for-byte — the
+ * `.*` suffixes intentionally match `utm_source`, `utm_medium`, etc.
+ */
+export const SEARCH_PARAMS_TO_IGNORE = [
+	"gclid",
+	"gbraid",
+	"gdftrk",
+	"_ga",
+	"mc_.*",
+	"trk_.*",
+	"utm_.*",
+	"sc_.*",
+	"dm_i",
+	"_ke",
+	"fbclid",
+	"qitc",
+	"queryID",
+	"indexName",
+	"objectID",
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"gad_.*",
+];
+
+/**
+ * Filter an array of [key, value] pairs, dropping any whose key matches
+ * one of the `SEARCH_PARAMS_TO_IGNORE` regex patterns. Pure function so
+ * callers can sort/transform after.
+ */
+export const filterSearchParams = (params: [string, string][]): [string, string][] => {
+	return params.filter(
+		([key]) => !SEARCH_PARAMS_TO_IGNORE.find((matchKey) => new RegExp(matchKey).test(key)),
+	);
+};
+
+/**
+ * Strip the tracking params from a URL (or URL string) and return the
+ * cleaned `href`. Used by Magento PDP/PLP loaders as the cache key
+ * basis so cache lookups don't depend on the visitor's referer chain.
+ */
+export const filterSearchParamsFromURL = (defaultURL: string | URL): string => {
+	const url = new URL(defaultURL);
+	const paramsArray = Array.from(url.searchParams.entries());
+	const filteredParams = filterSearchParams(paramsArray);
+
+	url.search = "";
+	for (const [key, value] of filteredParams) {
+		url.searchParams.append(key, value);
+	}
+
+	return url.href;
+};

package/src/utils/client/types.ts

@@ -0,0 +1,270 @@
+/**
+ * Magento REST API response shapes — the subset of types from
+ * `deco-cx/apps/magento/utils/client/types.ts` that the port has
+ * reached so far. Extended as more loaders/actions land.
+ *
+ * Keep field names **exactly** as Magento returns them (mostly
+ * snake_case, occasional camelCase from carbono-customer). Consumer
+ * sites already render against these shapes — any rename is a
+ * breaking change at the storefront, not just the API boundary.
+ */
+
+// ---------------------------------------------------------------------------
+// Customer / user section payloads (added by the user+wishlist port)
+// ---------------------------------------------------------------------------
+
+/**
+ * `customer` slice of `/customer/section/load?sections=customer,…`.
+ * Magento returns this on every authenticated section call.
+ */
+export interface Customer {
+	data_id: number;
+	fullname?: string;
+	firstname?: string;
+}
+
+/**
+ * `carbono-customer` slice. Granado-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.
+ */
+export interface CarbonoCustomer {
+	websiteId?: string;
+	email?: string;
+	customerId?: string;
+	data_id: number;
+}
+
+/**
+ * `cart` slice of the customer section bundle — minimal projection of
+ * the cart that the minicart island renders before the full cart loader
+ * has resolved. Not the same as the full Cart payload from
+ * `/V1/carts/:cartId` (which lives in MagentoCart in types.ts).
+ */
+export interface CartUser {
+	summary_count: number;
+	subtotalAmount: number | null;
+	subtotal: string;
+	possible_onepage_checkout: boolean;
+	items: [];
+	isGuestCheckoutAllowed: boolean;
+	website_id: string;
+	storeId: string;
+	adyen_payment_methods: unknown[];
+	extra_actions: string;
+	cart_empty_message: string;
+	subtotal_incl_tax: string;
+	subtotal_excl_tax: string;
+	mpFSBCartTotal: unknown | null;
+	data_id: number;
+	minicart_improvements: MinicartImprovements;
+}
+
+export interface MinicartImprovements {
+	coupon_code: string | null;
+	country_id: string;
+	api_base_url: string;
+	is_logged_in: boolean;
+	quote_id: string;
+	base_url: string;
+}
+
+/**
+ * Bundle shape returned by
+ * `GET /:site/customer/section/load?sections=customer,carbono-customer,wishlist,…`.
+ * Keys are optional because the caller picks which sections to request.
+ */
+export interface CustomerSectionLoad {
+	customer?: Customer;
+	"carbono-customer"?: CarbonoCustomer;
+	cart?: CartUser;
+	wishlist?: Wishlist;
+}
+
+// ---------------------------------------------------------------------------
+// Wishlist payloads
+// ---------------------------------------------------------------------------
+
+export interface Wishlist {
+	counter: string;
+	items: WishlistItem[];
+	counter_number: number;
+	data_id: number;
+}
+
+export interface WishlistItem {
+	image: WishlistItemImage;
+	product_sku: string;
+	product_id: string;
+	product_url: string;
+	product_name: string;
+	product_price: string;
+	product_is_saleable_and_visible: boolean;
+	product_has_required_options: boolean;
+	add_to_cart_params: string;
+	delete_item_params: string;
+}
+
+export interface WishlistItemImage {
+	template: string;
+	src: string;
+	width: number;
+	height: number;
+	alt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shared attribute/category shapes (added by the transform port)
+// ---------------------------------------------------------------------------
+
+export interface CustomAttribute {
+	attribute_code: string;
+	value: string | string[];
+}
+
+export interface CategoryLink {
+	position: number;
+	category_id: string;
+}
+
+export interface MagentoCategory {
+	id: number;
+	parent_id: number;
+	name: string;
+	is_active: boolean;
+	position: number;
+	level: number;
+	children: string;
+	created_at: string;
+	updated_at: string;
+	path: string;
+	include_in_menu: boolean;
+	custom_attributes: CustomAttribute[];
+}
+
+// ---------------------------------------------------------------------------
+// Product detail shapes (used by PDP / PLP / list loaders)
+// ---------------------------------------------------------------------------
+
+export interface MagentoPriceInfo {
+	final_price: number;
+	max_price: number;
+	max_regular_price: number;
+	minimal_regular_price: number;
+	special_price: number | null;
+	minimal_price: number;
+	regular_price: number;
+	formatted_prices: {
+		final_price: string;
+		max_price: string;
+		minimal_price: string;
+		max_regular_price: string;
+		minimal_regular_price: string | null;
+		special_price: string | null;
+		regular_price: string;
+	};
+	extension_attributes: {
+		msrp: {
+			msrp_price: string;
+			is_applicable: string;
+			is_shown_price_on_gesture: string;
+			msrp_message: string;
+			explanation_message: string;
+		};
+		tax_adjustments: {
+			final_price: number;
+			max_price: number;
+			max_regular_price: number;
+			minimal_regular_price: number;
+			special_price: number;
+			minimal_price: number;
+			regular_price: number;
+			formatted_prices: {
+				final_price: string;
+				max_price: string;
+				minimal_price: string;
+				max_regular_price: string;
+				minimal_regular_price: string | null;
+				special_price: string;
+				regular_price: string;
+			};
+		};
+		weee_attributes: unknown[];
+		weee_adjustment: string;
+	};
+}
+
+export interface MagentoStock {
+	item_id: number;
+	product_id: number;
+	stock_id: number;
+	qty?: number;
+	is_in_stock?: boolean;
+	is_qty_decimal?: boolean;
+	show_default_notification_message?: boolean;
+	use_config_min_qty?: boolean;
+	min_qty?: number;
+	use_config_min_sale_qty?: boolean;
+	min_sale_qty?: number;
+	use_config_max_sale_qty?: boolean;
+	max_sale_qty?: number;
+	use_config_backorders?: boolean;
+	backorders?: number;
+	use_config_notify_stock_qty?: boolean;
+	notify_stock_qty?: number;
+	use_config_qty_increments?: boolean;
+	qty_increments?: number;
+	use_config_enable_qty_inc?: boolean;
+	enable_qty_increments?: boolean;
+	use_config_manage_stock?: boolean;
+	manage_stock?: boolean;
+	low_stock_date?: string | null;
+	is_decimal_divided?: boolean;
+	stock_status_changed_auto?: number;
+}
+
+export interface MagentoImage {
+	url: string;
+	code: string;
+	height: number;
+	width: number;
+	label: string;
+	resized_width: number;
+	resized_height: number;
+	disabled: boolean;
+}
+
+export interface MediaEntry {
+	id: number;
+	media_type: string;
+	label: string | null;
+	position: number;
+	disabled: boolean;
+	types: string[];
+	file: string;
+}
+
+export interface MagentoProduct {
+	id: number;
+	sku: string;
+	name: string;
+	price: number;
+	status: number;
+	visibility: number;
+	type_id: string;
+	created_at: string;
+	updated_at: string;
+	weight: number;
+	url: string;
+	extension_attributes: {
+		website_ids?: number[];
+		category_links: CategoryLink[];
+		stock_item?: MagentoStock;
+	};
+	custom_attributes: CustomAttribute[];
+	price_info?: MagentoPriceInfo;
+	currency_code?: string;
+	images?: MagentoImage[];
+	media_gallery_entries?: MediaEntry[];
+}

package/src/utils/constants.ts

@@ -0,0 +1,101 @@
+/**
+ * Magento constants — ported verbatim from
+ * `deco-cx/apps/magento/utils/constants.ts`.
+ *
+ * Keep this file boring and append-only. Magento's REST and GraphQL
+ * payloads rely on these identifiers as-is (URL_KEY for PDP slug
+ * matching, GRAND_TOTAL/SUBTOTAL/… for the totals composition that
+ * cart.ts pulls, IN_STOCK/OUT_OF_STOCK for schema.org availability).
+ * Mutating any of these values would silently break consumer sites
+ * that already render against them.
+ */
+
+import type { FiltersGraphQL } from "../client";
+
+export const URL_KEY = "url_key";
+
+// Schema.org availability mapping (used by utils/transform.ts to
+// produce Offer.availability — kept here so transform doesn't import
+// schema.org strings as magic literals).
+export const IN_STOCK = "https://schema.org/InStock";
+export const OUT_OF_STOCK = "https://schema.org/OutOfStock";
+
+// Rating bounds used by `utils/transform.ts` (and the review/rating
+// loaders that follow) when mapping Magento's integer-rating scale
+// into schema.org `AggregateRating`'s 1–5 range.
+export const MAX_RATING_VALUE = 5;
+export const MIN_RATING_VALUE = 1;
+
+/**
+ * Default filter mapping consumed by `utils/graphql.ts:filtersFromUrlGraphQL`.
+ * Each entry pairs a Magento attribute slug with the comparison operator
+ * the storefront's URL filters use. Sites can extend this via the
+ * `customFilters` prop on PLP/list loaders without forking the array.
+ */
+export const DEFAULT_GRAPHQL_FILTERS: FiltersGraphQL[] = [
+	{ value: "activity", type: "EQUAL" },
+	{ value: "category_gear", type: "EQUAL" },
+	{ value: "category_id", type: "EQUAL" },
+	{ value: "category_uid", type: "EQUAL" },
+	{ value: "category_url_path", type: "EQUAL" },
+	{ value: "climate", type: "EQUAL" },
+	{ value: "collar", type: "EQUAL" },
+	{ value: "color", type: "EQUAL" },
+	{ value: "description", type: "MATCH" },
+	{ value: "eco_collection", type: "EQUAL" },
+	{ value: "erin_recommends", type: "EQUAL" },
+	{ value: "features_bags", type: "EQUAL" },
+	{ value: "format", type: "EQUAL" },
+	{ value: "gender", type: "EQUAL" },
+	{ value: "material", type: "EQUAL" },
+	{ value: "name", type: "MATCH" },
+	{ value: "new", type: "EQUAL" },
+	{ value: "pattern", type: "EQUAL" },
+	{ value: "performance_fabric", type: "EQUAL" },
+	{ value: "price", type: "RANGE" },
+	{ value: "purpose", type: "EQUAL" },
+	{ value: "sale", type: "EQUAL" },
+	{ value: "short_description", type: "MATCH" },
+	{ value: "size", type: "EQUAL" },
+	{ value: "sku", type: "EQUAL" },
+	{ value: "sleeve", type: "EQUAL" },
+	{ value: "strap_bags", type: "EQUAL" },
+	{ value: "style_bags", type: "EQUAL" },
+	{ value: "style_bottom", type: "EQUAL" },
+	{ value: "style_general", type: "EQUAL" },
+	{ value: "url_key", type: "EQUAL" },
+];
+
+/**
+ * Query-string keys that should be stripped before forwarding a request
+ * URL to Magento (e.g. when computing a cache key or building a
+ * paginated request). Mirrors the Fresh-era REMOVABLE_URL_SEARCHPARAMS.
+ */
+export const REMOVABLE_URL_SEARCHPARAMS = ["p", "product_list_order"];
+
+// ---------------------------------------------------------------------------
+// Cart totals composition — field names sent to Magento's
+// /V1/carts/:cartId/totals?fields=… endpoint. The cart loader joins
+// these into the `fields` query param to keep the response narrow.
+// ---------------------------------------------------------------------------
+
+export const GRAND_TOTAL = "grand_total";
+export const SUBTOTAL = "subtotal";
+export const DISCOUNT_AMOUNT = "discount_amount";
+export const BASE_DISCOUNT_AMOUNT = "base_discount_amount";
+export const SHIPPING_AMOUNT = "shipping_amount";
+export const BASE_SHIPPING_AMOUNT = "base_shipping_amount";
+export const SHIPPING_DISCOUNT_AMOUNT = "shipping_discount_amount";
+export const COUPON_CODE = "coupon_code";
+export const BASE_CURRENCY_CODE = "base_currency_code";
+
+// ---------------------------------------------------------------------------
+// Cookie names — single source of truth so loaders/actions/middleware
+// don't drift on string literals (Magento is case-sensitive about
+// these and a typo produces a silent anonymous-session bug).
+// ---------------------------------------------------------------------------
+
+export const SESSION_COOKIE = "PHPSESSID";
+export const CUSTOMER_COOKIE = "dataservices_customer_id";
+export const CART_COOKIE = "dataservices_cart_id";
+export const FORM_KEY_COOKIE = "form_key";

package/src/utils/graphql-types.ts

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