@decocms/apps-salesforce 7.2.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@decocms/apps-salesforce",
+  "version": "7.2.0",
+  "type": "module",
+  "description": "Deco commerce app: Salesforce Commerce Cloud integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-salesforce"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./loaders/products/*": "./src/loaders/products/*.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-salesforce/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.2.0",
+    "@decocms/apps-commerce": "7.2.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": ">=1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/__tests__/httpClient.test.ts

@@ -0,0 +1,201 @@
+/**
+ * Tests for utils/httpClient.ts.
+ *
+ * The legacy `apps/utils/http.ts` indexed-route Proxy is what every
+ * Deno-era loader called into, so this test file pins the call shapes
+ * existing site code still uses:
+ *  - `client["POST /api2/event/:dataset"]({ dataset }, { body })`
+ *  - `client.get(path)` / `client.post(path, body)` convenience methods
+ *  - `:name` placeholder substitution and `*name` legacy Deno-era syntax
+ *  - default `x-requested-with` header propagation
+ *  - `{ json, ok, status, headers }` response shape
+ *
+ * `fetch` is mocked so we never touch the network.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createHttpClient } from "../utils/httpClient";
+
+interface CallRecord {
+	url: string;
+	init: {
+		method?: string;
+		body?: string;
+		headers: Record<string, string>;
+	};
+}
+
+type MockedFetch = typeof fetch & {
+	mock: { calls: [string, CallRecord["init"]][] };
+};
+
+function makeFetch(
+	jsonBody: unknown = { ok: true },
+	init: { status?: number; headers?: Record<string, string> } = {},
+): MockedFetch {
+	return vi.fn(async () => ({
+		json: async () => jsonBody,
+		ok: (init.status ?? 200) < 400,
+		status: init.status ?? 200,
+		headers: new Headers(init.headers ?? {}),
+	})) as unknown as MockedFetch;
+}
+
+function callAt(fetcher: MockedFetch, idx: number): CallRecord {
+	const call = fetcher.mock.calls[idx];
+	return { url: call[0], init: call[1] };
+}
+
+describe("createHttpClient", () => {
+	let originalFetch: typeof fetch;
+
+	beforeEach(() => {
+		originalFetch = globalThis.fetch;
+	});
+
+	afterEach(() => {
+		globalThis.fetch = originalFetch;
+	});
+
+	it("strips trailing slash from base URL", async () => {
+		const fetcher = makeFetch();
+		const client = createHttpClient({ base: "https://api.example.com/", fetcher });
+		await client.get("/health");
+		expect(callAt(fetcher, 0).url).toBe("https://api.example.com/health");
+	});
+
+	it("uses global fetch when no fetcher is provided", async () => {
+		globalThis.fetch = makeFetch({ ok: true });
+		const client = createHttpClient({ base: "https://api.example.com" });
+		const result = await client.get("/health");
+		expect(result).toEqual({ ok: true });
+		expect(globalThis.fetch).toHaveBeenCalledOnce();
+	});
+
+	describe(".get / .post convenience methods", () => {
+		it(".get returns parsed JSON directly", async () => {
+			const fetcher = makeFetch({ items: [1, 2, 3] });
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			const result = await client.get("/things");
+			expect(result).toEqual({ items: [1, 2, 3] });
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/things");
+		});
+
+		it(".post sends JSON body with Content-Type header", async () => {
+			const fetcher = makeFetch({ created: true });
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client.post("/things", { name: "thing" });
+			const { init } = callAt(fetcher, 0);
+			expect(init.method).toBe("POST");
+			expect(init.body).toBe(JSON.stringify({ name: "thing" }));
+			expect(init.headers["Content-Type"]).toBe("application/json");
+		});
+
+		it("merges default headers from options into request", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({
+				base: "https://api.example.com",
+				fetcher,
+				headers: { "x-requested-with": "XMLHttpRequest" },
+			});
+			await client.post("/things", { name: "x" });
+			const { init } = callAt(fetcher, 0);
+			expect(init.headers["x-requested-with"]).toBe("XMLHttpRequest");
+		});
+
+		it("accepts a Headers object for default headers", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({
+				base: "https://api.example.com",
+				fetcher,
+				headers: new Headers({ "x-token": "abc" }),
+			});
+			await client.get("/things");
+			const { init } = callAt(fetcher, 0);
+			expect(init.headers["x-token"]).toBe("abc");
+		});
+	});
+
+	describe("indexed-route Proxy syntax", () => {
+		it("replaces `:name` path placeholders with the matching param", async () => {
+			const fetcher = makeFetch({ campaignResponses: [] });
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["POST /api2/event/:dataset"]({ dataset: "production" }, { body: { foo: 1 } });
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/api2/event/production");
+		});
+
+		it("url-encodes placeholder values", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["GET /catalog/:slug"]({ slug: "shoes & boots" });
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/catalog/shoes%20%26%20boots");
+		});
+
+		it("removes leftover `*name` placeholders when no value is provided", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["GET /catalog/*path"]({});
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/catalog");
+		});
+
+		it("substitutes `*name` placeholders when value is present", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["GET /catalog/*path"]({ path: "shoes/boots" });
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/catalog/shoes/boots");
+		});
+
+		it("serialises remaining params as the body on non-GET requests", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["POST /api2/event/:dataset"]({
+				dataset: "production",
+				extraField: "value",
+			});
+			const { init } = callAt(fetcher, 0);
+			expect(JSON.parse(init.body ?? "")).toEqual({ extraField: "value" });
+		});
+
+		it("prefers explicit { body } over remaining params", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["POST /api2/event/:dataset"](
+				{ dataset: "production", ignored: "yes" },
+				{ body: { real: "body" } },
+			);
+			const { init } = callAt(fetcher, 0);
+			expect(JSON.parse(init.body ?? "")).toEqual({ real: "body" });
+		});
+
+		it("encodes remaining params as querystring on GET", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["GET /search"]({ q: "shoes", limit: 12 });
+			const call = callAt(fetcher, 0);
+			expect(call.url).toBe("https://api.example.com/search?q=shoes&limit=12");
+			expect(call.init.body).toBeUndefined();
+		});
+
+		it("returns { json, ok, status, headers } from indexed routes", async () => {
+			const fetcher = makeFetch({ result: 1 }, { status: 201, headers: { etag: "abc" } });
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			const response = await client["POST /things"]({ name: "x" });
+			expect(response.status).toBe(201);
+			expect(response.ok).toBe(true);
+			expect(response.headers.get("etag")).toBe("abc");
+			expect(await response.json()).toEqual({ result: 1 });
+		});
+
+		it("appends query when no params remain but route already has `?`", async () => {
+			const fetcher = makeFetch();
+			const client = createHttpClient({ base: "https://api.example.com", fetcher });
+			await client["GET /search?fixed=1"]({ q: "shoes" });
+			expect(callAt(fetcher, 0).url).toBe("https://api.example.com/search?fixed=1&q=shoes");
+		});
+
+		it("returns undefined for unknown property accesses", () => {
+			const client = createHttpClient({ base: "https://api.example.com" });
+			// biome-ignore lint/suspicious/noExplicitAny: type-erased access for test
+			expect((client as any).somethingMadeUp).toBeUndefined();
+		});
+	});
+});

package/src/__tests__/parseUserCookie.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Tests for utils/parseUserCookie.ts.
+ *
+ * Locks the contract that downstream loaders depend on:
+ *  - puid wins over uuid (signed-in identity > anonymous device id)
+ *  - uuid is used when puid is missing
+ *  - empty / missing / malformed cookies fall back to "anonymous"
+ *
+ * The fallback is load-bearing — Evergage rejects requests with a
+ * missing user identifier, so an unparseable cookie must not surface
+ * as `{}`.
+ */
+import { describe, expect, it } from "vitest";
+import { parseUserCookie } from "../utils/parseUserCookie";
+
+const encode = (obj: unknown) => encodeURIComponent(JSON.stringify(obj));
+
+describe("parseUserCookie", () => {
+	it("returns anonymous fallback when cookie is undefined", () => {
+		expect(parseUserCookie(undefined)).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("returns anonymous fallback when cookie is null", () => {
+		expect(parseUserCookie(null)).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("returns anonymous fallback when cookie is empty string", () => {
+		expect(parseUserCookie("")).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("returns anonymous fallback when cookie is whitespace only", () => {
+		expect(parseUserCookie("   ")).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("returns anonymous fallback when cookie is not valid JSON", () => {
+		expect(parseUserCookie("not-json")).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("returns anonymous fallback when JSON value is not an object", () => {
+		expect(parseUserCookie(encode("string-value"))).toEqual({ anonymousId: "anonymous" });
+		expect(parseUserCookie(encode(42))).toEqual({ anonymousId: "anonymous" });
+		expect(parseUserCookie(encode(null))).toEqual({ anonymousId: "anonymous" });
+	});
+
+	it("maps puid to encryptedId", () => {
+		expect(parseUserCookie(encode({ puid: "user-123" }))).toEqual({
+			encryptedId: "user-123",
+		});
+	});
+
+	it("maps uuid to anonymousId", () => {
+		expect(parseUserCookie(encode({ uuid: "device-abc" }))).toEqual({
+			anonymousId: "device-abc",
+		});
+	});
+
+	it("prefers puid over uuid when both are present", () => {
+		expect(parseUserCookie(encode({ puid: "user-123", uuid: "device-abc" }))).toEqual({
+			encryptedId: "user-123",
+		});
+	});
+
+	it("returns anonymous fallback when puid is empty string", () => {
+		expect(parseUserCookie(encode({ puid: "", uuid: "device-abc" }))).toEqual({
+			anonymousId: "device-abc",
+		});
+	});
+
+	it("returns anonymous fallback when both puid and uuid are empty/missing", () => {
+		expect(parseUserCookie(encode({}))).toEqual({ anonymousId: "anonymous" });
+		expect(parseUserCookie(encode({ puid: "", uuid: "" }))).toEqual({
+			anonymousId: "anonymous",
+		});
+	});
+
+	it("returns anonymous fallback when puid/uuid are non-string types", () => {
+		expect(parseUserCookie(encode({ puid: 42, uuid: true }))).toEqual({
+			anonymousId: "anonymous",
+		});
+	});
+
+	it("decodes URL-encoded values", () => {
+		// Evergage encodes the JSON with encodeURIComponent — make sure
+		// embedded special chars (e.g. = / : in base64 ids) round-trip.
+		const puid = "abc=def+ghi/jkl";
+		const cookie = encodeURIComponent(JSON.stringify({ puid }));
+		expect(parseUserCookie(cookie)).toEqual({ encryptedId: puid });
+	});
+});

package/src/__tests__/transform.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Tests for utils/transform.ts.
+ *
+ * The Salesforce transformer is the only spot in the upstream package
+ * where consumer-specific behavior (the dataset's custom column shape)
+ * shows through, via the `propertyMapper` hook. The tests here lock:
+ *
+ *  - default mapper outputs the always-present Evergage columns
+ *    (itemType, categories) without dragging in dataset-specific
+ *    fields,
+ *  - a custom propertyMapper sees the raw Evergage product (including
+ *    custom columns via the index signature),
+ *  - schema.org shape is stable (productID precedence, AggregateOffer
+ *    surface, isVariantOf hasVariant).
+ *
+ * These match the regressions the legacy `apps/salesforce/utils/
+ * transform.ts` watched for over its lifetime.
+ */
+import { describe, expect, it } from "vitest";
+import type { SalesforceProduct } from "../types";
+import {
+	createProductTransformer,
+	type PropertyMapper,
+	toImages,
+	toOffer,
+} from "../utils/transform";
+
+const baseProduct = (overrides: Partial<SalesforceProduct> = {}): SalesforceProduct => ({
+	id: "SKU-42",
+	name: "Test Product",
+	price: 100,
+	salePrice: 80,
+	inventoryCount: 7,
+	imageUrls: ["https://cdn.example.com/p/42.jpg"],
+	url: "https://loja.example.com/p/test",
+	currency: "BRL",
+	itemType: "simple",
+	categories: ["category-a", "category-b"],
+	...overrides,
+});
+
+describe("toOffer", () => {
+	it("emits InStock when inventoryCount > 0", () => {
+		const [offer] = toOffer({ product: baseProduct(), currencyCode: "BRL" });
+		expect(offer.availability).toBe("https://schema.org/InStock");
+		expect(offer.inventoryLevel?.value).toBe(7);
+	});
+
+	it("emits OutOfStock when inventoryCount is 0", () => {
+		const [offer] = toOffer({
+			product: baseProduct({ inventoryCount: 0 }),
+			currencyCode: "BRL",
+		});
+		expect(offer.availability).toBe("https://schema.org/OutOfStock");
+	});
+
+	it("falls back to price when salePrice is missing", () => {
+		const [offer] = toOffer({
+			product: baseProduct({ salePrice: undefined }),
+			currencyCode: "BRL",
+		});
+		expect(offer.price).toBe(100);
+	});
+
+	it("uses salePrice as the primary price when present", () => {
+		const [offer] = toOffer({ product: baseProduct(), currencyCode: "BRL" });
+		expect(offer.price).toBe(80);
+	});
+
+	it("threads currencyCode into priceCurrency", () => {
+		const [offer] = toOffer({ product: baseProduct(), currencyCode: "USD" });
+		expect(offer.priceCurrency).toBe("USD");
+	});
+
+	it("emits ListPrice + SalePrice priceSpecification entries", () => {
+		const [offer] = toOffer({ product: baseProduct(), currencyCode: "BRL" });
+		expect(offer.priceSpecification).toEqual([
+			{
+				"@type": "UnitPriceSpecification",
+				priceType: "https://schema.org/ListPrice",
+				price: 100,
+			},
+			{
+				"@type": "UnitPriceSpecification",
+				priceType: "https://schema.org/SalePrice",
+				price: 80,
+			},
+		]);
+	});
+});
+
+describe("toImages", () => {
+	it("maps each imageUrl to a schema.org ImageObject", () => {
+		const images = toImages(
+			baseProduct({
+				imageUrls: ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
+			}),
+		);
+		expect(images).toEqual([
+			{
+				"@type": "ImageObject",
+				encodingFormat: "image",
+				alternateName: "https://cdn.example.com/a.jpg",
+				url: "https://cdn.example.com/a.jpg",
+			},
+			{
+				"@type": "ImageObject",
+				encodingFormat: "image",
+				alternateName: "https://cdn.example.com/b.jpg",
+				url: "https://cdn.example.com/b.jpg",
+			},
+		]);
+	});
+
+	it("returns an empty array when imageUrls is empty", () => {
+		expect(toImages(baseProduct({ imageUrls: [] }))).toEqual([]);
+	});
+});
+
+describe("createProductTransformer", () => {
+	it("uses default mapper when no propertyMapper is passed", () => {
+		const transform = createProductTransformer();
+		const out = transform({ product: baseProduct(), options: { currencyCode: "BRL" } });
+		expect(out.additionalProperty).toEqual([
+			{ "@type": "PropertyValue", name: "itemType", value: "simple" },
+			{ "@type": "PropertyValue", name: "category", value: "category-a, category-b" },
+		]);
+	});
+
+	it("default mapper skips itemType when absent", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ itemType: undefined }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.additionalProperty).toEqual([
+			{ "@type": "PropertyValue", name: "category", value: "category-a, category-b" },
+		]);
+	});
+
+	it("default mapper skips categories when empty", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ categories: [] }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.additionalProperty).toEqual([
+			{ "@type": "PropertyValue", name: "itemType", value: "simple" },
+		]);
+	});
+
+	it("custom propertyMapper sees site-specific extras via index signature", () => {
+		const granadoMapper: PropertyMapper = (product) => [
+			{ "@type": "PropertyValue", name: "marca", value: String(product.Marca ?? "") },
+			{ "@type": "PropertyValue", name: "volume", value: String(product.Volume ?? "") },
+		];
+		const transform = createProductTransformer({ propertyMapper: granadoMapper });
+		const out = transform({
+			product: baseProduct({ Marca: "Granado", Volume: "200ml" }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.additionalProperty).toEqual([
+			{ "@type": "PropertyValue", name: "marca", value: "Granado" },
+			{ "@type": "PropertyValue", name: "volume", value: "200ml" },
+		]);
+	});
+
+	it("prefers idMagento over id for productID when present", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ idMagento: "9999" }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.productID).toBe("9999");
+		expect(out.sku).toBe("SKU-42");
+	});
+
+	it("uses id for productID when idMagento is missing", () => {
+		const transform = createProductTransformer();
+		const out = transform({ product: baseProduct(), options: { currencyCode: "BRL" } });
+		expect(out.productID).toBe("SKU-42");
+	});
+
+	it("trims whitespace from name", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ name: "  Padded Name  " }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.name).toBe("Padded Name");
+		expect(out.isVariantOf?.name).toBe("Padded Name");
+	});
+
+	it("falls back to product.currency when options.currencyCode is omitted", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ currency: "EUR" }),
+			options: {},
+		});
+		const firstOffer = out.offers?.offers[0];
+		expect(firstOffer?.priceCurrency).toBe("EUR");
+	});
+
+	it("places one variant under isVariantOf.hasVariant", () => {
+		const transform = createProductTransformer();
+		const out = transform({ product: baseProduct(), options: { currencyCode: "BRL" } });
+		expect(out.isVariantOf?.hasVariant).toHaveLength(1);
+		expect(out.isVariantOf?.hasVariant?.[0].sku).toBe("SKU-42");
+	});
+
+	it("AggregateOffer surfaces high/low correctly when on sale", () => {
+		const transform = createProductTransformer();
+		const out = transform({ product: baseProduct(), options: { currencyCode: "BRL" } });
+		expect(out.offers?.highPrice).toBe(100);
+		expect(out.offers?.lowPrice).toBe(80);
+	});
+
+	it("AggregateOffer high === low when no salePrice is set", () => {
+		const transform = createProductTransformer();
+		const out = transform({
+			product: baseProduct({ salePrice: undefined }),
+			options: { currencyCode: "BRL" },
+		});
+		expect(out.offers?.highPrice).toBe(100);
+		expect(out.offers?.lowPrice).toBe(100);
+	});
+});

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Salesforce Marketing Cloud Personalization (Evergage) app entry.
+ *
+ * Unlike `magento` / `algolia`, the Salesforce loaders here are
+ * stateless — every loader takes its `baseUrl` / `dataset` /
+ * `campaignId` / `cookieName` via props so the same package can power
+ * multiple Evergage datasets in a single worker without a global
+ * configure step. Sites just import the loader(s) they need.
+ *
+ * For loaders, use sub-path imports:
+ *   import list from "@decocms/apps/salesforce/loaders/products/list"
+ *   import listRecomended from "@decocms/apps/salesforce/loaders/products/listRecomended"
+ *   import listCart from "@decocms/apps/salesforce/loaders/products/listCart"
+ *
+ * For the transformer (sites typically build their own `propertyMapper`
+ * over a dataset's custom columns):
+ *   import { createProductTransformer } from "@decocms/apps/salesforce/utils/transform"
+ */
+export type {
+	CampaignResponse,
+	ParsedUserCookie,
+	PersonalizationBody,
+	PersonalizationLineItem,
+	PersonalizationResponse,
+	SalesforceProduct,
+} from "./types";
+export { createHttpClient, type HttpClientOptions } from "./utils/httpClient";
+export { parseUserCookie } from "./utils/parseUserCookie";
+export {
+	createProductTransformer,
+	type ProductTransformerOptions,
+	type PropertyMapper,
+} from "./utils/transform";