@decocms/apps-magento 7.2.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@decocms/apps-magento",
+  "version": "7.2.0",
+  "type": "module",
+  "description": "Deco commerce app: Magento integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-magento"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./types": "./src/types.ts",
+    "./middleware": "./src/middleware.ts",
+    "./loaders/*": "./src/loaders/*.ts",
+    "./actions/*": "./src/actions/*.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./hooks/*": "./src/hooks/*.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-magento/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.2.0",
+    "@decocms/apps-commerce": "7.2.0",
+    "@decocms/tanstack": "7.2.0"
+  },
+  "peerDependencies": {
+    "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/README.md

@@ -0,0 +1,65 @@
+# Magento app — initial scaffold
+
+This folder ports the Magento integration from `deco-cx/apps/magento`
+(Fresh/Deno) to `@decocms/apps/magento` (TanStack Start/Node), following
+the same shape as the existing `vtex/` and `shopify/` packages.
+
+## Status
+
+**Initial scaffold** — covers the configure/client surface and 2 reference
+loaders (`features`, `cart`) so that downstream sites can wire magento at
+all. The remaining 20+ loaders/actions exist as production-grade code in
+the original deco-cx/apps repo and need adaptation passes (Deno → Node,
+ctx-based to client-based state access, cookie helpers from
+`@decocms/start/sdk/cookie`).
+
+A real-world consumer (deco-sites/granadobr-tanstack) is wiring magento
+in-site today using a thin adapter that wraps the legacy `magento/mod.ts`
+shape. Their adapter is the migration target — once this package covers
+the surface area they need, the in-site copy goes away.
+
+## What's here
+
+- `client.ts` — `configureMagento({ baseUrl, apiKey, storeId, ... })` +
+  `getMagentoConfig()` global accessor. Mirrors the `configureVtex`
+  pattern.
+- `types.ts` — request/response shapes shared between loaders.
+- `loaders/features.ts` — returns the feature flags block. The simplest
+  loader, used as a smoke test.
+- `loaders/cart.ts` — fetches the customer's active cart by cookie.
+  Pulls cookies via `@decocms/start/sdk/cookie`.
+- `middleware.ts` — passthrough today; real-world cart-id reconciliation
+  lives in the consumer site for now.
+- `index.ts` — re-export entry.
+
+## Pending port (PR follow-ups)
+
+| Path | Original location |
+|---|---|
+| `loaders/product/{detailsPage,detailsPageGQL,listingPage,list,relatedProducts}.ts` | `deco-cx/apps/magento/loaders/product/*` |
+| `loaders/{proxy,user,wishlist}.ts` | `deco-cx/apps/magento/loaders/*` |
+| `loaders/routes/getRouteType.ts` | idem |
+| `actions/cart/{addCoupon,addItem,removeCoupon,removeItem,setSimulation,simulation,updateItem}.ts` | `deco-cx/apps/magento/actions/cart/*` |
+| `actions/newsletter/subscribe.ts` | idem |
+| `actions/product/stockAlert.ts` | idem |
+| `actions/wishlist/{addItem,removeItem}.ts` | idem |
+| `utils/{clientGraphql,client,transform,cache,graphql,cart}.ts` | `deco-cx/apps/magento/utils/*` |
+| `hooks/{useCart,useUser,useWishlist}.ts` | `deco-cx/apps/magento/hooks/*` (refactor to react-query, like `vtex/hooks/`) |
+| `inline-loaders/*` | new, follow `vtex/inline-loaders/` shape |
+
+**Site-specific extensions (Livelo, Amasty)** in the deco-cx/apps repo
+should stay out of this package — they belong in consumer sites via the
+`ExtensionOf` pattern. Preserving that pattern in the generic loaders
+above is a hard requirement of this port.
+
+## Why a stub now
+
+The deco-sites/granadobr-tanstack migration hit a HIGH parity finding:
+
+```
+invoke(magento/loaders/features) failed: handler not found
+```
+
+…because no `@decocms/apps/magento/*` resolver existed. The site is
+working around it locally; this PR begins the upstream fix so future
+magento sites don't have to repeat the in-site adapter.

package/src/__tests__/cart.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for the cart loader.
+ *
+ * Parity goals against deco-cx/apps/magento/loaders/cart.ts (Fresh/Deno,
+ * prod):
+ *
+ *   - Reads `dataservices_cart_id` cookie when caller doesn't supply
+ *     `cartId` in props (matches `getCartCookie(req.headers)` in prod).
+ *   - Honors props.cartId override (matches `_cartId ?? getCartCookie()`).
+ *   - Hits /rest/:site/V1/carts/:cartId — the /rest/ prefix is what the
+ *     Magento REST API exposes; the legacy clientAdmin's typed key was
+ *     "GET /rest/:site/V1/carts/:cartId".
+ *   - Encodes site + cartId so a malicious cookie can't escape the path
+ *     segment and reach another admin endpoint with the Bearer token.
+ *   - Returns null when no cookie (anonymous visitor — matches prod's
+ *     `if (!cartId) return null`).
+ *   - Returns null on 404 (expired cookie — prod hits this via the same
+ *     branch but throws on other non-2xx; we surface a plain Error).
+ *
+ * NOT covered by this initial port (and intentionally not tested here):
+ *   - Pre-cart `GET /rest/:site/V1/carts/mine` warm-up for logged-in
+ *     users (the original does it inside a try/catch and discards the
+ *     result — it's a cache primer, not a correctness invariant).
+ *   - Parallel /totals fetch + image-pipeline transform — those land in
+ *     follow-up PRs that port utils/cart.ts + utils/cache.ts.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMagento } from "../client";
+import cart from "../loaders/cart";
+
+function mockResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" },
+	});
+}
+
+function requestWithCookie(cookie: string): Request {
+	const r = new Request("http://localhost/");
+	// Headers in a freshly-constructed Request enter "request" guard mode
+	// which silently drops `cookie`. Build a Headers manually then attach.
+	const headers = new Headers();
+	headers.set("cookie", cookie);
+	Object.defineProperty(r, "headers", { value: headers, configurable: true });
+	return r;
+}
+
+describe("cart loader", () => {
+	let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		configureMagento({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "secret",
+			storeId: 1,
+			site: "example",
+		});
+		fetchSpy = vi.spyOn(globalThis, "fetch");
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("returns null when no cart cookie is present", async () => {
+		const req = new Request("http://localhost/");
+		const result = await cart(undefined, req);
+		expect(result).toBeNull();
+		expect(fetchSpy).not.toHaveBeenCalled();
+	});
+
+	it("reads cartId from the dataservices_cart_id cookie (JSON-encoded)", async () => {
+		fetchSpy.mockResolvedValue(mockResponse({ id: "abc123", items: [] }));
+		const req = requestWithCookie('dataservices_cart_id="abc123"');
+		await cart(undefined, req);
+		const [target] = fetchSpy.mock.calls[0] as [URL];
+		expect(target.toString()).toBe("https://loja.example.com/rest/example/V1/carts/abc123");
+	});
+
+	it("reads cartId from the cookie when it's not JSON-quoted", async () => {
+		fetchSpy.mockResolvedValue(mockResponse({ id: "raw-id", items: [] }));
+		const req = requestWithCookie("dataservices_cart_id=raw-id");
+		await cart(undefined, req);
+		const [target] = fetchSpy.mock.calls[0] as [URL];
+		expect(target.toString()).toBe("https://loja.example.com/rest/example/V1/carts/raw-id");
+	});
+
+	it("honors props.cartId override (cookie ignored)", async () => {
+		fetchSpy.mockResolvedValue(mockResponse({ id: "from-props", items: [] }));
+		const req = requestWithCookie('dataservices_cart_id="from-cookie"');
+		await cart({ cartId: "from-props" }, req);
+		const [target] = fetchSpy.mock.calls[0] as [URL];
+		expect(target.toString()).toContain("/rest/example/V1/carts/from-props");
+	});
+
+	it("URL-encodes the cartId to prevent path injection", async () => {
+		// A malicious cookie value tries to break out of the path segment
+		// and reach a different admin endpoint with the Bearer attached.
+		fetchSpy.mockResolvedValue(mockResponse(null, 404));
+		const req = requestWithCookie('dataservices_cart_id="../admin/leak?secret=1"');
+		await cart(undefined, req);
+		const [target] = fetchSpy.mock.calls[0] as [URL];
+		// Encoded: %2F (slash), %3F (?), %3D (=). The trailing
+		// "/admin/leak?secret=1" stays inside the path segment.
+		expect(target.pathname).toMatch(
+			/^\/rest\/example\/V1\/carts\/(\.\.|%2E%2E)%2Fadmin%2Fleak%3Fsecret%3D1$/i,
+		);
+	});
+
+	it("returns null on 404 (expired cart cookie)", async () => {
+		fetchSpy.mockResolvedValue(mockResponse(null, 404));
+		const req = requestWithCookie('dataservices_cart_id="stale"');
+		const result = await cart(undefined, req);
+		expect(result).toBeNull();
+	});
+
+	it("throws on non-404 errors", async () => {
+		fetchSpy.mockResolvedValue(mockResponse(null, 500));
+		const req = requestWithCookie('dataservices_cart_id="abc"');
+		await expect(cart(undefined, req)).rejects.toThrow(/cart loader: 500/);
+	});
+
+	it("attaches Bearer + x-origin-header (same-origin) on the cart fetch", async () => {
+		configureMagento({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "secret",
+			storeId: 1,
+			site: "example",
+			originHeader: "origin-secret",
+		});
+		fetchSpy.mockResolvedValue(mockResponse({ id: "abc", items: [] }));
+		const req = requestWithCookie('dataservices_cart_id="abc"');
+		await cart(undefined, req);
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("authorization")).toBe("Bearer secret");
+		expect(headers.get("x-origin-header")).toBe("origin-secret");
+	});
+});

package/src/__tests__/client.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Tests for the Magento client config + magentoFetch wrapper.
+ *
+ * Parity goals — behavior these tests pin down so the port stays aligned
+ * with deco-cx/apps/magento (Fresh/Deno, prod):
+ *
+ *  - configureMagento / getMagentoConfig is a write-once-read-many global
+ *    (mirrors configureVtex). getMagentoConfig() throws before configure().
+ *  - magentoFetch:
+ *      • Same-origin: attaches Authorization (Bearer apiKey),
+ *        x-origin-header (when configured), and a forced Referer pointing
+ *        at baseUrl — exactly the headers the Fresh `clientAdmin` was
+ *        built with at App() time.
+ *      • Cross-origin: strips ALL Magento-only identity headers so the
+ *        admin Bearer + origin secret never leak to a third party. Caller
+ *        headers pass through.
+ *      • authenticated:false opt-out drops Bearer even on same-origin.
+ *      • Relative paths resolve against baseUrl with proper "/" handling.
+ *      • Absolute https://… paths bypass baseUrl entirely.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureMagento, getMagentoConfig, magentoFetch } from "../client";
+
+// Reset module-global config between tests by re-importing.
+beforeEach(() => {
+	vi.resetModules();
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe("configureMagento / getMagentoConfig", () => {
+	it("throws before configureMagento() is called", async () => {
+		const { getMagentoConfig: freshGet } = await import("../client");
+		expect(() => freshGet()).toThrow(/configureMagento\(\) must be called/);
+	});
+
+	it("returns the configured value after configureMagento()", async () => {
+		const { configureMagento: c, getMagentoConfig: g } = await import("../client");
+		c({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "test-key",
+			storeId: 1,
+			site: "example",
+		});
+		expect(g().baseUrl).toBe("https://loja.example.com/");
+		expect(g().apiKey).toBe("test-key");
+	});
+});
+
+describe("magentoFetch — same-origin (configured baseUrl)", () => {
+	const baseUrl = "https://loja.example.com/";
+	let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		configureMagento({
+			baseUrl,
+			apiKey: "secret-bearer",
+			storeId: 1,
+			site: "example",
+			originHeader: "origin-secret",
+		});
+		fetchSpy = vi
+			.spyOn(globalThis, "fetch")
+			.mockResolvedValue(
+				new Response("{}", { status: 200, headers: { "content-type": "application/json" } }),
+			);
+	});
+
+	it("attaches Authorization, x-origin-header, and forced Referer", async () => {
+		await magentoFetch("/rest/example/V1/carts/123");
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("authorization")).toBe("Bearer secret-bearer");
+		expect(headers.get("x-origin-header")).toBe("origin-secret");
+		expect(headers.get("referer")).toBe(baseUrl);
+	});
+
+	it("resolves relative path against baseUrl with correct slash handling", async () => {
+		await magentoFetch("rest/example/V1/carts/123"); // no leading slash
+		const [target] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		expect(target.toString()).toBe("https://loja.example.com/rest/example/V1/carts/123");
+	});
+
+	it("authenticated:false suppresses Bearer even on same-origin", async () => {
+		await magentoFetch("/rest/example/V1/carts/123", { authenticated: false });
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("authorization")).toBeNull();
+		// Same-origin still gets the other Magento-identity headers.
+		expect(headers.get("x-origin-header")).toBe("origin-secret");
+	});
+
+	it("preserves caller-supplied Referer (no force-overwrite when caller set one)", async () => {
+		await magentoFetch("/rest/example/V1/carts/123", {
+			headers: { Referer: "https://caller.example/page" },
+		});
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("referer")).toBe("https://caller.example/page");
+	});
+});
+
+describe("magentoFetch — cross-origin guard", () => {
+	let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		configureMagento({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "secret-bearer",
+			storeId: 1,
+			site: "example",
+			originHeader: "origin-secret",
+		});
+		fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response("{}", { status: 200 }));
+	});
+
+	it("strips Bearer when fetching a non-Magento host", async () => {
+		await magentoFetch("https://attacker.example/api");
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("authorization")).toBeNull();
+	});
+
+	it("strips x-origin-header when fetching a non-Magento host", async () => {
+		// Regression for cubic review: the previous fix only dropped Bearer
+		// while x-origin-header and Referer still leaked.
+		await magentoFetch("https://attacker.example/api");
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("x-origin-header")).toBeNull();
+	});
+
+	it("strips forced Referer when fetching a non-Magento host", async () => {
+		await magentoFetch("https://attacker.example/api");
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		// Referer to https://loja.example.com/ would broadcast the Magento
+		// host to the third party — must not be set by us.
+		expect(headers.get("referer")).toBeNull();
+	});
+
+	it("still forwards caller-supplied headers cross-origin", async () => {
+		await magentoFetch("https://partner.example/api", {
+			headers: { "x-correlation-id": "abc123" },
+		});
+		const [, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		const headers = init.headers as Headers;
+		expect(headers.get("x-correlation-id")).toBe("abc123");
+	});
+
+	it("treats an absolute URL with the same origin as same-origin", async () => {
+		await magentoFetch("https://loja.example.com/rest/example/V1/carts/123");
+		const [target, init] = fetchSpy.mock.calls[0] as [URL, RequestInit];
+		expect(target.toString()).toBe("https://loja.example.com/rest/example/V1/carts/123");
+		expect((init.headers as Headers).get("authorization")).toBe("Bearer secret-bearer");
+	});
+});
+
+describe("initMagentoFromBlocks — secret resolution", () => {
+	beforeEach(() => {
+		vi.resetModules();
+	});
+
+	it("returns early when the `magento` block is absent", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		const { initMagentoFromBlocks, getMagentoConfig } = await import("../client");
+		await initMagentoFromBlocks({});
+		expect(warn).toHaveBeenCalledWith(expect.stringContaining("No `magento` block"));
+		expect(() => getMagentoConfig()).toThrow(/configureMagento\(\) must be called/);
+	});
+
+	it("reads plain-string apiKey directly", async () => {
+		const { initMagentoFromBlocks, getMagentoConfig } = await import("../client");
+		await initMagentoFromBlocks({
+			magento: {
+				apiConfig: {
+					baseUrl: "https://loja.example.com/",
+					apiKey: "plain-string-key",
+					site: "example",
+					storeId: 1,
+				},
+			},
+		});
+		expect(getMagentoConfig().apiKey).toBe("plain-string-key");
+	});
+
+	it("dereferences a Secret-shaped apiKey via process.env (the env fallback path)", async () => {
+		process.env.TEST_MAGENTO_KEY = "from-env";
+		const { initMagentoFromBlocks, getMagentoConfig } = await import("../client");
+		await initMagentoFromBlocks({
+			magento: {
+				apiConfig: {
+					baseUrl: "https://loja.example.com/",
+					apiKey: {
+						__resolveType: "website/loaders/secret.ts",
+						name: "TEST_MAGENTO_KEY",
+					},
+					site: "example",
+					storeId: 1,
+				},
+			},
+		});
+		expect(getMagentoConfig().apiKey).toBe("from-env");
+		delete process.env.TEST_MAGENTO_KEY;
+	});
+
+	it("falls back to empty string when secret is unresolvable", async () => {
+		// no DECO_CRYPTO_KEY, no env var with this name, no decrypt
+		// → resolveSecret returns null → init writes "".
+		delete process.env.DECO_CRYPTO_KEY;
+		const { initMagentoFromBlocks, getMagentoConfig } = await import("../client");
+		await initMagentoFromBlocks({
+			magento: {
+				apiConfig: {
+					baseUrl: "https://loja.example.com/",
+					apiKey: {
+						__resolveType: "website/loaders/secret.ts",
+						encrypted: "deadbeef",
+						name: "UNDEFINED_ENV_VAR_DO_NOT_SET",
+					},
+					site: "example",
+					storeId: 1,
+				},
+			},
+		});
+		expect(getMagentoConfig().apiKey).toBe("");
+	});
+
+	it("resolves both apiKey and originHeader independently", async () => {
+		process.env.TEST_API_KEY = "api-from-env";
+		process.env.TEST_ORIGIN = "origin-from-env";
+		const { initMagentoFromBlocks, getMagentoConfig } = await import("../client");
+		await initMagentoFromBlocks({
+			magento: {
+				apiConfig: {
+					baseUrl: "https://loja.example.com/",
+					apiKey: { name: "TEST_API_KEY" },
+					originHeader: { name: "TEST_ORIGIN" },
+					site: "example",
+					storeId: 1,
+				},
+			},
+		});
+		const cfg = getMagentoConfig();
+		expect(cfg.apiKey).toBe("api-from-env");
+		expect(cfg.originHeader).toBe("origin-from-env");
+		delete process.env.TEST_API_KEY;
+		delete process.env.TEST_ORIGIN;
+	});
+});

package/src/__tests__/features.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Tests for the features loader.
+ *
+ * Parity with deco-cx/apps/magento/loaders/features.ts (Fresh/Deno, prod):
+ * the legacy loader was a 3-arg `(_props, _req, ctx) => ctx.features`.
+ * The ported version uses the module-global config instead of a per-
+ * request ctx, but the surface area downstream is the same — a plain
+ * object pulled from the resolved magento CMS block.
+ */
+import { beforeEach, describe, expect, it } from "vitest";
+import { configureMagento } from "../client";
+import features from "../loaders/features";
+
+describe("features loader", () => {
+	beforeEach(() => {
+		configureMagento({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "key",
+			storeId: 1,
+			site: "example",
+			features: {
+				dangerouslyDisableWishlist: false,
+				dangerouslyDisableOnLoadUpdate: true,
+				dangerouslyReturnNullAfterAction: true,
+				dangerouslyDontReturnCartAfterAction: true,
+				dangerouslyDisableOnVisibilityChangeUpdate: true,
+			},
+		});
+	});
+
+	it("returns the feature flags object from the config", () => {
+		expect(features()).toEqual({
+			dangerouslyDisableWishlist: false,
+			dangerouslyDisableOnLoadUpdate: true,
+			dangerouslyReturnNullAfterAction: true,
+			dangerouslyDontReturnCartAfterAction: true,
+			dangerouslyDisableOnVisibilityChangeUpdate: true,
+		});
+	});
+
+	it("returns an empty object when features are not configured", () => {
+		configureMagento({
+			baseUrl: "https://loja.example.com/",
+			apiKey: "key",
+			storeId: 1,
+			site: "example",
+			// features omitted
+		});
+		expect(features()).toEqual({});
+	});
+});