@decocms/apps-magento 8.1.0-next.0 → 8.1.0-next.2

package/src/client.ts

@@ -1,252 +0,0 @@
-/**
- * Magento API client config — module-global, set once at app boot.
- *
- * Mirrors `vtex/client.ts`'s configureVtex/getVtexConfig pattern so the
- * same wiring contract works across commerce apps. Sites should call
- * `configureMagento(...)` once from their setup phase before any
- * loader/action runs; loaders consume `getMagentoConfig()` to pick up
- * baseUrl, auth, and feature toggles.
- *
- * Two reasons we don't pass config explicitly to every loader:
- *  1. CMS-resolved loader instances don't know where the config block
- *     lives; the site's `initMagentoFromBlocks(blocks)` adapter is the
- *     single source of truth.
- *  2. Matches the rest of @decocms/apps so a site touching VTEX and
- *     Magento has consistent muscle memory.
- */
-
-import { type FetchFn, withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
-
-// ---------------------------------------------------------------------------
-// Config shapes
-// ---------------------------------------------------------------------------
-
-/**
- * URL-search-param filter mapping consumed by GraphQL product loaders.
- * Each entry pairs a Magento attribute slug (`value`) with the
- * comparison operator the storefront's URL filters use (`type`). The
- * default mapping lives in `utils/constants.ts:DEFAULT_GRAPHQL_FILTERS`;
- * sites extend it via the `customFilters` prop on PLP/list loaders.
- */
-export interface FiltersGraphQL {
-	value: string;
-	type: "EQUAL" | "MATCH" | "RANGE";
-}
-
-export interface MagentoFeatures {
-	dangerouslyDisableWishlist?: boolean;
-	dangerouslyDisableOnLoadUpdate?: boolean;
-	dangerouslyReturnNullAfterAction?: boolean;
-	dangerouslyDontReturnCartAfterAction?: boolean;
-	dangerouslyDisableOnVisibilityChangeUpdate?: boolean;
-}
-
-export interface MagentoImagesConfig {
-	imagesQtd: number;
-	imagesUrl: string;
-}
-
-export interface MagentoPricingConfig {
-	maxInstallments: number;
-	minInstallmentValue: number;
-}
-
-export interface MagentoCartConfigs {
-	countProductImageInCart?: number;
-	changeCardIdAfterCheckout?: boolean;
-	cartErrorMessages?: string[];
-}
-
-export interface MagentoConfig {
-	/** Magento storefront base URL, e.g. `https://loja.acme.com.br/` */
-	baseUrl: string;
-	/** Bearer token for `Authorization` header on admin REST calls */
-	apiKey: string;
-	/** Store ID used in headers + path prefixes */
-	storeId: number;
-	/** Site/site-code used in path segments */
-	site: string;
-	/** Which Store header to send (default: "site") */
-	storeHeader?: string;
-	/** Optional opaque header value sent as `x-origin-header` */
-	originHeader?: string;
-	/** Currency code (e.g. "BRL") */
-	currencyCode?: string;
-	/** Whether to append `_suffix` to admin endpoints */
-	useSuffix?: boolean;
-	/** Behavior toggles surfaced to client hooks */
-	features?: MagentoFeatures;
-	/** Cart-specific tunables */
-	cartConfigs?: MagentoCartConfigs;
-	/** Images CDN config */
-	imagesConfig?: MagentoImagesConfig;
-	/** Pricing rules for installments display */
-	pricingConfig?: MagentoPricingConfig;
-}
-
-// ---------------------------------------------------------------------------
-// Module-global state
-// ---------------------------------------------------------------------------
-
-let config: MagentoConfig | null = null;
-
-/**
- * Underlying fetch used by {@link magentoFetch}. Defaults to `globalThis.fetch`;
- * override once at boot with {@link setMagentoFetch} to plug in the instrumented
- * fetch (spans + `http.client.request.duration` histogram, `provider:"magento"`).
- * Mirrors VTEX's `setVtexFetch` / Shopify's `setShopifyFetch` so every commerce
- * app funnels egress through a single instrumented `_fetch`.
- */
-let _fetch: FetchFn = withFetchTimeout();
-
-/**
- * Override the fetch used by every Magento egress call.
- *
- * @example
- * ```ts
- * import { createMagentoFetch, setMagentoFetch } from "@decocms/apps/magento";
- * setMagentoFetch(createMagentoFetch());
- * ```
- */
-export function setMagentoFetch(fetchFn: FetchFn): void {
-	_fetch = fetchFn;
-}
-
-export function configureMagento(c: MagentoConfig): void {
-	config = c;
-}
-
-export function getMagentoConfig(): MagentoConfig {
-	if (!config) {
-		throw new Error(
-			"[Magento] configureMagento() must be called before loaders run. " +
-				"Wire it in your site's setup, e.g. configureMagento(blocks.magento).",
-		);
-	}
-	return config;
-}
-
-/**
- * Best-effort init from a CMS block — mirrors `initVtexFromBlocks`.
- *
- * Resolves secret references stored in the CMS block (`apiKey`,
- * `originHeader`) in this priority:
- *   1. Plain string                                              (dev override)
- *   2. `{ get: () => string }` object                            (legacy)
- *   3. `{ encrypted: "<hex>" }` decrypted via `DECO_CRYPTO_KEY`   (prod)
- *   4. `{ name: "ENV_VAR" }` → `process.env[name]`               (fallback)
- *
- * (3) is what the production Deco CMS actually stores — admin
- * encrypts the secret with the site's `DECO_CRYPTO_KEY` so the value
- * never leaves the worker in plain text. Previously this init only
- * read `process.env[name]`, which silently produced `apiKey: ""` for
- * any site that hadn't *also* set the named env var as a CF Worker
- * secret. Result: `Authorization: Bearer ` header missing on every
- * request → Magento 401 → minicart/cart-related loaders dead. The
- * shared `resolveSecret` helper from `@decocms/blocks/sdk/crypto`
- * handles the full chain, matching how VTEX and Shopify configure
- * themselves.
- *
- * Because the AES-CBC decrypt step is async, this function is now
- * `Promise<void>` — site setups must `await` the call before any
- * loader fires.
- */
-export async function initMagentoFromBlocks(blocks: Record<string, unknown>): Promise<void> {
-	// Lazy-imported to keep `@decocms/blocks/sdk/crypto` out of the
-	// import graph for sites that wire Magento manually via
-	// `configureMagento({ apiKey: "..." })` without ever calling this
-	// helper (e.g. unit tests, CLI tools).
-	const { resolveSecret } = await import("@decocms/blocks/sdk/crypto");
-
-	const block = blocks.magento as Record<string, any> | undefined;
-	if (!block) {
-		console.warn("[Magento] No `magento` block found in CMS; skipping init.");
-		return;
-	}
-
-	const apiConfig = block.apiConfig ?? {};
-
-	// The env-var fallback names match the Secret block's `name` field
-	// when present. `resolveSecret` cycles through the chain documented
-	// above; an empty string here means every layer was empty, which we
-	// pass through verbatim so `buildHeaders` can detect it.
-	const extractEnvName = (value: unknown): string => {
-		if (value && typeof value === "object") {
-			const name = (value as { name?: unknown }).name;
-			if (typeof name === "string") return name;
-		}
-		return "";
-	};
-	const apiKeyEnvName = extractEnvName(apiConfig.apiKey);
-	const originHeaderEnvName = extractEnvName(apiConfig.originHeader);
-
-	const apiKey = (await resolveSecret(apiConfig.apiKey, apiKeyEnvName)) ?? "";
-	const originHeader = (await resolveSecret(apiConfig.originHeader, originHeaderEnvName)) ?? "";
-
-	configureMagento({
-		baseUrl: apiConfig.baseUrl ?? "",
-		apiKey,
-		storeId: apiConfig.storeId ?? 1,
-		site: apiConfig.site ?? "",
-		storeHeader: apiConfig.storeHeader,
-		originHeader,
-		currencyCode: apiConfig.currencyCode,
-		useSuffix: apiConfig.useSuffix,
-		features: block.features,
-		cartConfigs: block.cartConfigs,
-		imagesConfig: block.imagesConfig,
-		pricingConfig: block.pricingConfig,
-	});
-}
-
-// ---------------------------------------------------------------------------
-// HTTP helpers (thin wrappers over fetch with auth pre-applied)
-// ---------------------------------------------------------------------------
-
-export interface MagentoFetchOpts extends RequestInit {
-	/** Whether to attach the admin Bearer token. Default true. */
-	authenticated?: boolean;
-}
-
-function buildHeaders(
-	opts: MagentoFetchOpts,
-	c: MagentoConfig,
-	attachMagentoIdentity: boolean,
-): Headers {
-	const headers = new Headers(opts.headers ?? {});
-	// `attachMagentoIdentity` is false when the request is going to a host
-	// that isn't the configured Magento backend. None of the Magento-only
-	// headers below should leak in that case: the Bearer is privileged, the
-	// `x-origin-header` is a secret that third parties shouldn't see, and a
-	// forced `Referer` would broadcast our Magento storefront URL.
-	if (!attachMagentoIdentity) return headers;
-
-	if (opts.authenticated !== false && c.apiKey) {
-		headers.set("Authorization", `Bearer ${c.apiKey}`);
-	}
-	if (c.originHeader) {
-		headers.set("x-origin-header", c.originHeader);
-	}
-	if (!headers.has("Referer")) {
-		headers.set("Referer", c.baseUrl);
-	}
-	return headers;
-}
-
-export function magentoFetch(path: string, opts: MagentoFetchOpts = {}): Promise<Response> {
-	const c = getMagentoConfig();
-	const baseUrl = new URL(c.baseUrl);
-	const target = path.startsWith("http")
-		? new URL(path)
-		: new URL(path.startsWith("/") ? path : `/${path}`, baseUrl);
-
-	// Only attach Magento identity (Bearer, x-origin-header, forced Referer)
-	// when the request is going to the configured Magento host. An absolute
-	// URL to a different origin would otherwise leak the admin token *and*
-	// our origin/Referer secrets to that third party. Callers that genuinely
-	// want a third-party call must still pass `authenticated: false` for
-	// clarity at the call site.
-	const sameOrigin = target.origin === baseUrl.origin;
-
-	return _fetch(target, { ...opts, headers: buildHeaders(opts, c, sameOrigin) });
-}

package/src/loaders/cart.ts

@@ -1,64 +0,0 @@
-/**
- * Magento cart loader — fetches the customer's active cart by cookie.
- *
- * Reads the `dataservices_cart_id` cookie from the request, calls the
- * Magento admin REST endpoint, and returns the cart payload. Returns
- * `null` when no cart cookie is present (anonymous visitor — expected).
- *
- * This is a minimal port of `deco-cx/apps/magento/loaders/cart.ts`.
- * It omits, for now, the image-handling pipeline (`handleCartImages`)
- * and the cart-items-with-images transform. Those depend on
- * `utils/cache.ts` and `utils/cart.ts` from the original — both
- * pending ports (see magento/README.md).
- */
-import { getCookies } from "@decocms/blocks/sdk/cookie";
-import { getMagentoConfig, magentoFetch } from "../client";
-import type { MagentoCart } from "../types";
-
-const CART_COOKIE = "dataservices_cart_id";
-
-function readCartIdFromCookie(headers: Headers): string | null {
-	const cookies = getCookies(headers);
-	const raw = cookies[CART_COOKIE];
-	if (!raw) return null;
-	// Magento sets the cookie as `"<id>"` (JSON-encoded). Try to parse;
-	// fall back to the raw string if it isn't quoted.
-	try {
-		const parsed = JSON.parse(raw);
-		return typeof parsed === "string" ? parsed : raw;
-	} catch {
-		return raw;
-	}
-}
-
-export interface CartLoaderProps {
-	/** Override the cart id (used by checkout flows that already know it). */
-	cartId?: string;
-}
-
-export default async function cart(
-	props: CartLoaderProps | undefined,
-	req: Request,
-): Promise<MagentoCart | null> {
-	const cartId = props?.cartId ?? readCartIdFromCookie(req.headers);
-	if (!cartId) return null;
-
-	const { site } = getMagentoConfig();
-	// Magento exposes the cart endpoint at /rest/:site/V1/carts/:cartId — the
-	// /rest/ prefix is mandatory and matches the Fresh/Deno original
-	// (deco-cx/apps/magento/loaders/cart.ts uses
-	// clientAdmin["GET /rest/:site/V1/carts/:cartId"]).
-	//
-	// cartId comes from the request cookie and is user-controlled. Both
-	// `site` and `cartId` are URL-encoded so neither can break out of its
-	// path segment and hit a different endpoint while the privileged
-	// Bearer token is still attached.
-	const path = `/rest/${encodeURIComponent(site)}/V1/carts/${encodeURIComponent(cartId)}`;
-
-	const res = await magentoFetch(path);
-	if (!res.ok) {
-		if (res.status === 404) return null; // expired/invalid cart cookie
-		throw new Error(`[Magento] cart loader: ${res.status} ${res.statusText}`);
-	}
-	return (await res.json()) as MagentoCart;
-}

package/src/loaders/features.ts

@@ -1,16 +0,0 @@
-/**
- * Magento feature flags — returns the `features` block from the resolved
- * Magento config. Sites read this to gate optional client-side behavior
- * (cart on-load update, wishlist visibility, on-visibility-change update,
- * etc.) without re-deploying.
- *
- * In the legacy deco-cx/apps shape this lived as a 3-arg loader
- * `(_props, _req, ctx) => ctx.features`. The TanStack/Node port uses
- * the module-global config set by `configureMagento(...)` instead of a
- * per-request ctx, which matches the rest of @decocms/apps.
- */
-import { getMagentoConfig, type MagentoFeatures } from "../client";
-
-export default function features(): MagentoFeatures {
-	return getMagentoConfig().features ?? {};
-}

package/src/loaders/user.ts

@@ -1,60 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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 a production Magento storefront
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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/__tests__/instrumentation.test.ts

@@ -1,59 +0,0 @@
-/**
- * Coverage for the Magento observability wiring added so cache/upstream
- * telemetry flows automatically:
- *   - `magentoOperationRouter` names REST resources + GraphQL.
- *   - `setMagentoFetch` actually reroutes `magentoFetch`'s egress (the hook
- *     that lets `createMagentoFetch()`'s instrumentation take effect).
- */
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { magentoOperationRouter } from "../operationRouter";
-
-describe("magentoOperationRouter", () => {
-  it("names REST resources by their first V1 segment", () => {
-    expect(magentoOperationRouter("https://x.com/rest/default/V1/products/42", "GET")).toBe(
-      "rest.products",
-    );
-    expect(magentoOperationRouter("https://x.com/rest/V1/carts/mine", "POST")).toBe("rest.carts");
-  });
-
-  it("names GraphQL calls `graphql`", () => {
-    expect(magentoOperationRouter("https://x.com/graphql", "POST")).toBe("graphql");
-  });
-
-  it("returns undefined when nothing matches (framework falls back)", () => {
-    expect(magentoOperationRouter("https://x.com/media/logo.png", "GET")).toBeUndefined();
-  });
-
-  it("tolerates non-absolute URLs", () => {
-    expect(magentoOperationRouter("/rest/default/V1/orders?x=1", "GET")).toBe("rest.orders");
-  });
-});
-
-describe("setMagentoFetch routing", () => {
-  beforeEach(() => {
-    vi.resetModules();
-  });
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("routes magentoFetch egress through the fetch set via setMagentoFetch", async () => {
-    const { configureMagento, setMagentoFetch, magentoFetch } = await import("../../client");
-    configureMagento({
-      baseUrl: "https://loja.example.com/",
-      apiKey: "k",
-      storeId: 1,
-      site: "example",
-    });
-    const custom = vi
-      .fn()
-      .mockResolvedValue(new Response("{}", { status: 200 })) as unknown as typeof fetch;
-    const globalSpy = vi.spyOn(globalThis, "fetch");
-    setMagentoFetch(custom);
-
-    await magentoFetch("/rest/default/V1/products/1");
-
-    expect(custom).toHaveBeenCalledOnce();
-    expect(globalSpy).not.toHaveBeenCalled(); // did NOT hit the default fetch
-  });
-});

package/src/utils/cacheTimeControl.ts

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