@decocms/apps-salesforce 7.2.0

package/src/loaders/products/list.ts

@@ -0,0 +1,139 @@
+/**
+ * Salesforce Marketing Cloud Personalization — campaign list loader.
+ *
+ * Hits `POST {baseUrl}/api2/event/:dataset` with the user identifier
+ * extracted from the Evergage cookie and returns the products attached
+ * to the matching campaign payload. When no cookie exists (first visit
+ * / parity bot / SSR), `parseUserCookie` falls back to the literal
+ * `anonymous` so Evergage still responds with a default campaign
+ * instead of erroring.
+ *
+ * Cookies are read via `getCookies()` from `@tanstack/react-start/server`
+ * — the request object isn't propagated through the framework's
+ * `commerceLoader(resolvedProps)` call, so we rely on AsyncLocalStorage
+ * to recover the original request from inside the deferred section
+ * server function context.
+ */
+import type { Product } from "@decocms/apps-commerce/types";
+import type {
+	CampaignResponse,
+	PersonalizationBody,
+	PersonalizationResponse,
+	SalesforceProduct,
+} from "../../types";
+import { createHttpClient } from "../../utils/httpClient";
+import { parseUserCookie } from "../../utils/parseUserCookie";
+import { createProductTransformer, type PropertyMapper } from "../../utils/transform";
+
+export interface SalesforceListLoaderProps {
+	/**
+	 * @title Personalization Base URL
+	 * @description e.g. `https://<account>.us-5.evergage.com`
+	 */
+	baseUrl: string;
+	/** @title Personalization Dataset */
+	dataset: string;
+	/** @title Campaign Id */
+	campaignId: string;
+	/**
+	 * @title Cookie Name
+	 * @description Cookie name Evergage drops on the browser
+	 *   (e.g. `_evga_<accountSlug>`)
+	 */
+	cookieName: string;
+	/** @title Currency Code (ISO 4217) */
+	currencyCode?: string;
+	/** Custom property mapper passed by site wrappers. */
+	propertyMapper?: PropertyMapper;
+}
+
+export interface SalesforceListResult {
+	"@type": "ProductList";
+	list: Product[];
+	additionalData: {
+		title?: string;
+		campaignId: string;
+		experienceId?: string;
+		userGroup?: string;
+	};
+}
+
+/**
+ * Read the named cookie from the in-flight request. Imported lazily so
+ * the loader stays runtime-agnostic for unit tests (a manual cookie
+ * value can be passed via `__testCookieOverride`).
+ */
+async function readCookie(cookieName: string): Promise<string | undefined> {
+	try {
+		const { getCookies } = await import("@tanstack/react-start/server");
+		const cookies = getCookies();
+		return cookies?.[cookieName];
+	} catch {
+		return undefined;
+	}
+}
+
+export default async function salesforceListLoader(
+	props: SalesforceListLoaderProps,
+	_req?: Request,
+): Promise<SalesforceListResult | null> {
+	const { baseUrl, dataset, campaignId, cookieName, currencyCode, propertyMapper } = props;
+
+	try {
+		const rawCookie = await readCookie(cookieName);
+		const userData = parseUserCookie(rawCookie);
+
+		const client = createHttpClient({
+			base: baseUrl,
+			headers: { "x-requested-with": "XMLHttpRequest" },
+		});
+
+		const requestBody: PersonalizationBody = {
+			source: { channel: "WebServer", url: `mcp_campaign=${campaignId}` },
+			interaction: { name: "Personalization Campaigns" },
+			user: userData,
+			flags: { nonInteractive: true, doNotTrack: false },
+			pageView: false,
+		};
+
+		const response = (await client["POST /api2/event/:dataset"](
+			{ dataset },
+			{ body: requestBody },
+		).then((res: { json: () => Promise<PersonalizationResponse> }) =>
+			res.json(),
+		)) as PersonalizationResponse;
+
+		const payload =
+			response.campaignResponses?.find((item: CampaignResponse) => item.campaignId === campaignId)
+				?.payload ?? response.campaignResponses?.[0]?.payload;
+
+		if (!payload?.products?.length) {
+			return null;
+		}
+
+		const transform = createProductTransformer({ propertyMapper });
+
+		return {
+			"@type": "ProductList",
+			list: payload.products.map((product: SalesforceProduct) =>
+				transform({
+					product,
+					options: { currencyCode: currencyCode ?? product.currency },
+				}),
+			),
+			additionalData: {
+				title: payload.headerText,
+				campaignId,
+				experienceId: payload.experience,
+				userGroup: payload.userGroup,
+			},
+		};
+	} catch (err) {
+		// The legacy Deno loader swallowed errors and returned null. We
+		// keep the same return shape (so consumers don't have to handle
+		// rejections) but log the failure — silent null hides API outages
+		// and CORS regressions during parity validation.
+		console.error("[salesforce/products/list] failed:", (err as Error)?.message);
+		return null;
+	}
+}

package/src/loaders/products/listCart.ts

@@ -0,0 +1,151 @@
+/**
+ * Salesforce Marketing Cloud Personalization — cart-aware recommendations.
+ *
+ * Same wire format as `list.ts`, but the interaction name is
+ * `"Replace Cart"` and the request body carries the current cart's line
+ * items so Evergage can seed cross-sell / "frequently bought together"
+ * campaigns from the items already in the basket.
+ *
+ * Sites typically call this loader from a "cart drawer" / "cart side panel"
+ * section. The cart state itself isn't read from cookies here — sites
+ * resolve their own cart (Magento, Shopify, custom) and pass `items` as
+ * a flat array. When `items` is empty, the loader short-circuits and
+ * returns `null` (no cart → no cross-sell).
+ */
+import type { Product } from "@decocms/apps-commerce/types";
+import type {
+	CampaignResponse,
+	PersonalizationBody,
+	PersonalizationResponse,
+	SalesforceProduct,
+} from "../../types";
+import { createHttpClient } from "../../utils/httpClient";
+import { parseUserCookie } from "../../utils/parseUserCookie";
+import { createProductTransformer, type PropertyMapper } from "../../utils/transform";
+
+export interface SalesforceListCartItem {
+	sku: string;
+	qty: number;
+	price: number;
+}
+
+export interface SalesforceListCartProps {
+	/**
+	 * @title Cart Items
+	 * @description Items currently in the user's cart. Site loaders resolve
+	 *   this from their commerce backend (Magento, Shopify, etc.) and pass
+	 *   it through.
+	 */
+	items: SalesforceListCartItem[];
+	/** @title Personalization Base URL */
+	baseUrl: string;
+	/** @title Personalization Dataset */
+	dataset: string;
+	/** @title Campaign Id */
+	campaignId: string;
+	/** @title Cookie Name */
+	cookieName: string;
+	/** @title Currency Code (ISO 4217) */
+	currencyCode?: string;
+	/**
+	 * @title Fallback Title
+	 * @description Shown when the campaign payload has no `headerText`
+	 *   (e.g. Granado uses the configured `label` from the CMS block).
+	 */
+	title?: string;
+	/** Custom property mapper. */
+	propertyMapper?: PropertyMapper;
+}
+
+export interface SalesforceListCartResult {
+	"@type": "ProductList";
+	list: Product[];
+	additionalData: {
+		title?: string;
+		campaignId: string;
+		experienceId?: string;
+		userGroup?: string;
+	};
+}
+
+async function readCookie(cookieName: string): Promise<string | undefined> {
+	try {
+		const { getCookies } = await import("@tanstack/react-start/server");
+		const cookies = getCookies();
+		return cookies?.[cookieName];
+	} catch {
+		return undefined;
+	}
+}
+
+export default async function salesforceListCartLoader(
+	props: SalesforceListCartProps,
+	_req?: Request,
+): Promise<SalesforceListCartResult | null> {
+	const { items, baseUrl, dataset, campaignId, cookieName, currencyCode, title, propertyMapper } =
+		props;
+
+	if (!items?.length) return null;
+
+	try {
+		const rawCookie = await readCookie(cookieName);
+		const userData = parseUserCookie(rawCookie);
+
+		const client = createHttpClient({
+			base: baseUrl,
+			headers: { "x-requested-with": "XMLHttpRequest" },
+		});
+
+		const requestBody: PersonalizationBody = {
+			source: { channel: "WebServer", url: `mcp_campaign=${campaignId}` },
+			interaction: {
+				name: "Replace Cart",
+				lineItems: items.map(({ sku, qty, price }) => ({
+					catalogObjectType: "Product",
+					catalogObjectId: sku,
+					quantity: qty,
+					price,
+				})),
+			},
+			user: userData,
+			flags: { nonInteractive: true, doNotTrack: false },
+			pageView: false,
+		};
+
+		const response = (await client["POST /api2/event/:dataset"](
+			{ dataset },
+			{ body: requestBody },
+		).then((res: { json: () => Promise<PersonalizationResponse> }) =>
+			res.json(),
+		)) as PersonalizationResponse;
+
+		const payload =
+			response.campaignResponses?.find((item: CampaignResponse) => item.campaignId === campaignId)
+				?.payload ?? response.campaignResponses?.[0]?.payload;
+
+		if (!payload?.products?.length) {
+			return null;
+		}
+
+		const transform = createProductTransformer({ propertyMapper });
+
+		return {
+			"@type": "ProductList",
+			list: payload.products.map((product: SalesforceProduct) =>
+				transform({
+					product,
+					options: { currencyCode: currencyCode ?? product.currency },
+				}),
+			),
+			additionalData: {
+				title: payload.headerText || title,
+				campaignId,
+				experienceId: payload.experience,
+				userGroup: payload.userGroup,
+			},
+		};
+	} catch (err) {
+		console.error("[salesforce/products/listCart] failed:", (err as Error)?.message);
+		return null;
+	}
+}

package/src/loaders/products/listRecomended.ts

@@ -0,0 +1,121 @@
+/**
+ * Salesforce Marketing Cloud Personalization — recommendations loader.
+ *
+ * Same wire format as `list.ts`, but the campaign Evergage runs is the
+ * "related products" one and the request body includes the
+ * `viewedProductId` attribute so Evergage can use the in-context PDP
+ * to seed its recommendation model.
+ *
+ * Used on PDP / PDC pages; the upstream site passes the resolved
+ * `ProductDetailsPage` so we can read `product.sku`. When no product
+ * context is available the loader still sends the campaign request —
+ * Evergage will return its default fallback list.
+ */
+import type { Product, ProductDetailsPage } from "@decocms/apps-commerce/types";
+import type { CampaignResponse, PersonalizationResponse, SalesforceProduct } from "../../types";
+import { createHttpClient } from "../../utils/httpClient";
+import { parseUserCookie } from "../../utils/parseUserCookie";
+import { createProductTransformer, type PropertyMapper } from "../../utils/transform";
+
+export interface SalesforceListRecommendedProps {
+	/** @title Product Id (resolved PDP) */
+	productId: ProductDetailsPage | null;
+	/** @title Personalization Base URL */
+	baseUrl: string;
+	/** @title Personalization Dataset */
+	dataset: string;
+	/** @title Campaign Id */
+	campaignId: string;
+	/** @title Cookie Name */
+	cookieName: string;
+	/** @title Currency Code (ISO 4217) */
+	currencyCode?: string;
+	/** Custom property mapper. */
+	propertyMapper?: PropertyMapper;
+}
+
+export interface SalesforceListRecommendedResult {
+	"@type": "ProductList";
+	list: Product[];
+	additionalData: {
+		title?: string;
+		campaignId: string;
+		experienceId?: string;
+		userGroup?: string;
+	};
+}
+
+async function readCookie(cookieName: string): Promise<string | undefined> {
+	try {
+		const { getCookies } = await import("@tanstack/react-start/server");
+		const cookies = getCookies();
+		return cookies?.[cookieName];
+	} catch {
+		return undefined;
+	}
+}
+
+export default async function salesforceListRecommendedLoader(
+	props: SalesforceListRecommendedProps,
+	_req?: Request,
+): Promise<SalesforceListRecommendedResult | null> {
+	const { baseUrl, dataset, productId, cookieName, campaignId, currencyCode, propertyMapper } =
+		props;
+
+	try {
+		const rawCookie = await readCookie(cookieName);
+		const userData = parseUserCookie(rawCookie);
+
+		const client = createHttpClient({
+			base: baseUrl,
+			headers: { "x-requested-with": "XMLHttpRequest" },
+		});
+
+		const requestBody = {
+			source: { channel: "WebServer", url: `mcp_campaign=${campaignId}` },
+			interaction: { name: "Personalization Campaigns" },
+			user: {
+				...userData,
+				attributes: { viewedProductId: productId?.product?.sku ?? "" },
+			},
+			flags: { nonInteractive: true, doNotTrack: false },
+			pageView: false,
+		};
+
+		const response = (await client["POST /api2/event/:dataset"](
+			{ dataset },
+			{ body: requestBody },
+		).then((res: { json: () => Promise<PersonalizationResponse> }) =>
+			res.json(),
+		)) as PersonalizationResponse;
+
+		const payload =
+			response.campaignResponses?.find((item: CampaignResponse) => item.campaignId === campaignId)
+				?.payload ?? response.campaignResponses?.[0]?.payload;
+
+		if (!payload?.products?.length) {
+			return null;
+		}
+
+		const transform = createProductTransformer({ propertyMapper });
+
+		return {
+			"@type": "ProductList",
+			list: payload.products.map((product: SalesforceProduct) =>
+				transform({
+					product,
+					options: { currencyCode: currencyCode ?? product.currency },
+				}),
+			),
+			additionalData: {
+				title: payload.headerText,
+				campaignId,
+				experienceId: payload.experience,
+				userGroup: payload.userGroup,
+			},
+		};
+	} catch (err) {
+		console.error("[salesforce/products/listRecomended] failed:", (err as Error)?.message);
+		return null;
+	}
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Salesforce Marketing Cloud Personalization (Evergage) — request/response
+ * shapes for the campaign personalization API.
+ *
+ * The Evergage product schema is configurable per dataset (each customer
+ * chooses which fields to expose), so `SalesforceProduct` keeps a minimal
+ * required surface and accepts arbitrary extras via index signature.
+ * Site-level transformers can downcast to their own product shape to
+ * read store-specific custom fields (e.g. `marca`, `linha`, brand-tags).
+ */
+
+export interface SalesforceProduct {
+	/** Internal Evergage id (string token, often a SKU or catalog id). */
+	id: string;
+	/** Display name. */
+	name: string;
+	/** Base price (list). */
+	price: number;
+	/** Discounted price; falls back to `price` when no promotion is active. */
+	salePrice?: number;
+	/** Stock count from Evergage's catalog feed. */
+	inventoryCount: number;
+	/** Pre-built absolute URLs of product images. */
+	imageUrls: string[];
+	/** Canonical product URL (full origin + path). */
+	url: string;
+	/** ISO 4217 currency code (e.g. "BRL"). */
+	currency: string;
+	/** Common Evergage column — short product description. */
+	description?: string;
+	/** Optional cross-system identifier (e.g. Magento `entity_id`). */
+	idMagento?: string;
+	/** Item type tag (e.g. "configurable", "simple"). */
+	itemType?: string;
+	/** Generic category trail (Evergage stores these as arrays). */
+	categories?: string[];
+	/** Site-specific extras — Evergage exposes whatever the dataset schema
+	 *  defines (e.g. `Marca`, `Volume`, `Linha`, `freeShipping`). The
+	 *  product transformer can read these via the attributeMapper hook. */
+	[customField: string]: unknown;
+}
+
+/**
+ * Single line item in a cart-interaction request body. Evergage uses
+ * these to seed cart-aware recommendations ("people who bought X also
+ * bought Y") and abandoned-cart campaigns.
+ */
+export interface PersonalizationLineItem {
+	catalogObjectType: string;
+	catalogObjectId: string;
+	quantity: number;
+	price: number;
+}
+
+/**
+ * Body sent to `POST {baseUrl}/api2/event/:dataset`. The Evergage API is
+ * "interaction"-based — every request describes an interaction the user
+ * had, and the response contains the campaigns triggered by that
+ * interaction (recommendations, popups, etc.).
+ *
+ * `interaction.lineItems` is only used by cart-aware campaigns; PDP /
+ * homepage requests omit it. `user.attributes` carries page-context
+ * hints (e.g. `viewedProductId` for related-product campaigns).
+ */
+export interface PersonalizationBody {
+	source: {
+		channel: string;
+		url: string;
+	};
+	interaction: {
+		name: string;
+		lineItems?: PersonalizationLineItem[];
+	};
+	user: {
+		anonymousId?: string;
+		encryptedId?: string;
+		attributes?: Record<string, unknown>;
+	};
+	flags: {
+		nonInteractive: boolean;
+		doNotTrack: boolean;
+	};
+	pageView: boolean;
+}
+
+export interface CampaignResponse {
+	campaignId: string;
+	payload: {
+		experience?: string;
+		headerText?: string;
+		products?: SalesforceProduct[];
+		userGroup?: string;
+	};
+}
+
+export interface PersonalizationResponse {
+	campaignResponses?: CampaignResponse[];
+}
+
+/**
+ * Cookie shape Evergage drops on the browser (`puid` = persistent user
+ * id after sign-in, `uuid` = anonymous device id). The site loaders
+ * read this cookie to send the right user identifier on each request.
+ */
+export interface ParsedUserCookie {
+	encryptedId?: string;
+	anonymousId?: string;
+}

package/src/utils/httpClient.ts

@@ -0,0 +1,154 @@
+/**
+ * Typed HTTP client compatible with deco-cx/apps' `createHttpClient`
+ * signature. Accepts both the simple `.get(path)` / `.post(path, body)`
+ * shape and the indexed-route shape used by legacy Deno loaders:
+ *
+ * ```ts
+ * const client = createHttpClient({ base: "https://api.example.com" });
+ * await client["POST /api2/event/:dataset"]({ dataset: "prod" }, { body });
+ * await client.get("/healthcheck");
+ * ```
+ *
+ * Runtime-agnostic: only requires the global `fetch`. Works on
+ * Cloudflare Workers, Bun, Deno, and modern Node — no `node:http`
+ * dependency. Returns `{ json, ok, status, headers }` from indexed
+ * routes (mirrors the legacy `apps/utils/http.ts` shape so existing
+ * loaders that call `.then(res => res.json())` keep working).
+ */
+
+export interface HttpClientOptions {
+	base: string;
+	headers?: Record<string, string> | Headers;
+	fetcher?: typeof fetch;
+}
+
+interface IndexedRouteResponse {
+	json: <T = unknown>() => Promise<T>;
+	ok: boolean;
+	status: number;
+	headers: Headers;
+}
+
+export function createHttpClient<_Routes = unknown>(options: HttpClientOptions) {
+	const base = options.base.replace(/\/$/, "");
+	const fetchImpl = options.fetcher ?? fetch;
+	const defaultHeaders: Record<string, string> =
+		options.headers instanceof Headers
+			? Object.fromEntries(options.headers.entries())
+			: (options.headers ?? {});
+
+	const handler: ProxyHandler<Record<string, unknown>> = {
+		get(_target, prop) {
+			if (prop === "get") {
+				return async <R = unknown>(path: string, init?: RequestInit): Promise<R> => {
+					const res = await fetchImpl(`${base}${path}`, {
+						...init,
+						headers: {
+							...defaultHeaders,
+							...((init?.headers as Record<string, string>) ?? {}),
+						},
+					});
+					return res.json() as Promise<R>;
+				};
+			}
+			if (prop === "post") {
+				return async <R = unknown>(path: string, body: unknown, init?: RequestInit): Promise<R> => {
+					const res = await fetchImpl(`${base}${path}`, {
+						method: "POST",
+						...init,
+						headers: {
+							"Content-Type": "application/json",
+							...defaultHeaders,
+							...((init?.headers as Record<string, string>) ?? {}),
+						},
+						body: JSON.stringify(body),
+					});
+					return res.json() as Promise<R>;
+				};
+			}
+			if (typeof prop === "string" && /^(GET|POST|PUT|PATCH|DELETE)\s+/.test(prop)) {
+				const spaceIdx = prop.indexOf(" ");
+				const method = prop.slice(0, spaceIdx);
+				let apiPath = prop.slice(spaceIdx + 1);
+
+				return async (
+					params: Record<string, unknown> = {},
+					init?: RequestInit & { body?: unknown },
+				): Promise<IndexedRouteResponse> => {
+					const cleanParams = { ...params };
+
+					// `:name` path placeholders — replaced with the matching
+					// param value, then removed from the body/query object.
+					for (const [key, value] of Object.entries(cleanParams)) {
+						const placeholder = `:${key}`;
+						if (apiPath.includes(placeholder) && value != null) {
+							apiPath = apiPath.replace(placeholder, encodeURIComponent(String(value)));
+							delete cleanParams[key];
+						}
+					}
+
+					// Legacy `*name` placeholders (Deno-era convention).
+					const starMatch = apiPath.match(/\*(\w+)/);
+					if (starMatch) {
+						const paramName = starMatch[1];
+						if (cleanParams[paramName] != null) {
+							apiPath = apiPath.replace(`*${paramName}`, String(cleanParams[paramName]));
+							delete cleanParams[paramName];
+						} else {
+							apiPath = apiPath.replace(/\/\*\w+/, "");
+						}
+					}
+
+					let url = `${base}${apiPath}`;
+
+					if (method === "GET") {
+						const sp = new URLSearchParams();
+						for (const [k, v] of Object.entries(cleanParams)) {
+							if (v !== undefined && v !== null) sp.set(k, String(v));
+						}
+						const qs = sp.toString();
+						if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+					}
+
+					// Indexed-route callers can either embed the body in the
+					// remaining params (legacy style) OR pass `{ body }` in the
+					// second arg (newer call sites). The `body` key in init
+					// takes precedence when present.
+					const explicitBody = init && "body" in init ? init.body : undefined;
+					const fetchBody =
+						method === "GET"
+							? undefined
+							: explicitBody !== undefined
+								? JSON.stringify(explicitBody)
+								: Object.keys(cleanParams).length > 0
+									? JSON.stringify(cleanParams)
+									: undefined;
+
+					const fetchInit: RequestInit = {
+						method,
+						...(init ?? {}),
+						headers: {
+							"Content-Type": "application/json",
+							...defaultHeaders,
+							...(init?.headers instanceof Headers
+								? Object.fromEntries(init.headers.entries())
+								: ((init?.headers as Record<string, string>) ?? {})),
+						},
+						...(fetchBody !== undefined ? { body: fetchBody } : {}),
+					};
+
+					const res = await fetchImpl(url, fetchInit);
+					return {
+						json: <T = unknown>() => res.json() as Promise<T>,
+						ok: res.ok,
+						status: res.status,
+						headers: res.headers,
+					};
+				};
+			}
+			return undefined;
+		},
+	};
+
+	return new Proxy({} as Record<string, unknown>, handler) as Record<string, any>;
+}