@decocms/apps-commerce 7.2.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@decocms/apps-commerce",
+  "version": "7.2.0",
+  "type": "module",
+  "description": "Deco commerce apps: shared types, app-registry, and portable commerce utilities",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-commerce"
+  },
+  "main": "./src/types/commerce.ts",
+  "exports": {
+    "./types": "./src/types/commerce.ts",
+    "./app-types": "./src/app-types.ts",
+    "./resolve": "./src/resolve.ts",
+    "./manifest-utils": "./src/manifest-utils.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./sdk/*": "./src/sdk/*.ts",
+    "./registry": "./src/registry.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-commerce/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "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/app-types.ts

@@ -0,0 +1,62 @@
+/**
+ * Core types for the Deco app system on TanStack Start.
+ *
+ * Each app (vtex, shopify, resend, etc.) exports a `configure` function
+ * from its `mod.ts` that returns an `AppDefinition`.
+ *
+ * The framework's `autoconfigApps()` calls these generically.
+ */
+
+import type { ComponentType } from "react";
+
+export type AppHandler = (props: any, request: Request) => Promise<any>;
+
+export interface SectionModule {
+	default: ComponentType<Record<string, unknown>>;
+	loader?: (...args: unknown[]) => Promise<unknown> | unknown;
+	LoadingFallback?: ComponentType;
+	ErrorFallback?: ComponentType<{ error: Error }>;
+}
+
+export interface AppManifest {
+	name: string;
+	/** Module namespace imports keyed by manifest path (e.g. "vtex/loaders/catalog"). */
+	loaders: Record<string, Record<string, unknown>>;
+	/** Module namespace imports keyed by manifest path (e.g. "vtex/actions/checkout"). */
+	actions: Record<string, Record<string, unknown>>;
+	/** Lazy-loaded section components keyed by manifest path (e.g. "vtex/sections/Analytics/Vtex"). */
+	sections?: Record<string, () => Promise<SectionModule>>;
+}
+
+export type AppMiddleware = (request: Request, next: () => Promise<Response>) => Promise<Response>;
+
+export interface AppDefinition<TState = unknown> {
+	name: string;
+	manifest: AppManifest;
+	state: TState;
+	middleware?: AppMiddleware;
+	dependencies?: AppDefinition[];
+	resolvables?: Record<string, { __resolveType: string; [key: string]: unknown }>;
+}
+
+export type ResolveSecretFn = (value: unknown, envKey: string) => Promise<string | null>;
+
+export interface AppPreview {
+	Component: ComponentType<Record<string, unknown>>;
+	props: Record<string, unknown>;
+}
+
+/**
+ * Standard contract for Deco apps with auto-configuration.
+ *
+ * Each app exports `configure` from its `mod.ts`.
+ * Apps that need invoke handlers (e.g. resend) also export a `handlers` map.
+ * The framework discovers and calls these generically.
+ */
+export interface AppModContract<TState = unknown> {
+	configure: (
+		blockData: any,
+		resolveSecret: ResolveSecretFn,
+	) => Promise<AppDefinition<TState> | null>;
+	handlers?: Record<string, AppHandler>;
+}

package/src/manifest-utils.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import type { AppManifest } from "./app-types";
+import { extractHandlers } from "./manifest-utils";
+
+describe("extractHandlers", () => {
+	it("flattens module namespaces into individual handler entries", () => {
+		const searchProducts = () => {};
+		const getProductById = () => {};
+		const addItem = () => {};
+
+		const manifest: AppManifest = {
+			name: "test",
+			loaders: {
+				"test/loaders/catalog": {
+					searchProducts,
+					getProductById,
+					SOME_CONSTANT: "not a function",
+				},
+			},
+			actions: {
+				"test/actions/cart": {
+					addItem,
+				},
+			},
+		};
+
+		const handlers = extractHandlers(manifest);
+
+		expect(handlers["test/loaders/catalog/searchProducts"]).toBe(searchProducts);
+		expect(handlers["test/loaders/catalog/getProductById"]).toBe(getProductById);
+		expect(handlers).not.toHaveProperty("test/loaders/catalog/SOME_CONSTANT");
+		expect(handlers["test/actions/cart/addItem"]).toBe(addItem);
+	});
+
+	it("returns empty object for empty manifest", () => {
+		const manifest: AppManifest = { name: "empty", loaders: {}, actions: {} };
+		expect(extractHandlers(manifest)).toEqual({});
+	});
+
+	it("handles multiple modules per category", () => {
+		const fn1 = () => {};
+		const fn2 = () => {};
+
+		const manifest: AppManifest = {
+			name: "multi",
+			loaders: {
+				"app/loaders/a": { fn1 },
+				"app/loaders/b": { fn2 },
+			},
+			actions: {},
+		};
+
+		const handlers = extractHandlers(manifest);
+		expect(handlers["app/loaders/a/fn1"]).toBe(fn1);
+		expect(handlers["app/loaders/b/fn2"]).toBe(fn2);
+	});
+});

package/src/manifest-utils.ts

@@ -0,0 +1,38 @@
+/**
+ * Utilities for extracting individual handlers from app manifests.
+ *
+ * Used by the framework to flatten module namespace imports into
+ * individual handler functions for setInvokeLoaders() / setInvokeActions().
+ */
+
+import type { AppManifest } from "./app-types";
+
+/**
+ * Extract individual handler functions from a manifest's module namespaces.
+ *
+ * Given a manifest with:
+ *   loaders: { "vtex/loaders/catalog": { searchProducts, getProductByIdOrSku } }
+ *
+ * Returns:
+ *   { "vtex/loaders/catalog/searchProducts": searchProducts, ... }
+ */
+type AnyFn = (...args: never[]) => unknown;
+
+export function extractHandlers(manifest: AppManifest): Record<string, AnyFn> {
+	const result: Record<string, AnyFn> = {};
+
+	for (const category of ["loaders", "actions"] as const) {
+		const modules = manifest[category];
+		for (const [moduleKey, moduleNamespace] of Object.entries(modules)) {
+			for (const [exportName, handler] of Object.entries(
+				moduleNamespace as Record<string, unknown>,
+			)) {
+				if (typeof handler === "function") {
+					result[`${moduleKey}/${exportName}`] = handler as AnyFn;
+				}
+			}
+		}
+	}
+
+	return result;
+}

package/src/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared types for the app-registry pattern consumed by
+ * `@decocms/blocks-admin/apps/autoconfig`'s `autoconfigApps()`.
+ *
+ * Each platform package with a registrable app (e.g. `@decocms/apps-vtex`)
+ * exports its own single-entry registry from its own `./registry` subpath —
+ * sites import only the platform entries they actually use and compose their
+ * own array. This file holds only the shared shape, not a static catalogue
+ * (previously it was — see git history — but that required every platform to
+ * live in one package; split by platform, no single package can hold a
+ * complete static array without depending on every other platform package).
+ *
+ * Import path: `@decocms/apps-commerce/registry`
+ *
+ * NOTE: the type is inlined rather than imported from
+ * `@decocms/blocks-admin/apps` so this file ships in `@decocms/apps-commerce`
+ * against any installed `@decocms/blocks-admin` version. Once callers pin a
+ * blocks-admin version that exposes `AppRegistry`, the type can be swapped.
+ */
+
+interface AppRegistryEntry {
+	/** Block key in the decofile, e.g. "deco-shopify". */
+	blockKey: string;
+	/** Lazy dynamic import of the app's mod module. */
+	module: () => Promise<any>;
+	/** Human-readable name shown in admin install UI. */
+	displayName?: string;
+	/** Icon URL (absolute or site-relative) shown in admin install UI. */
+	icon?: string;
+	/** Grouping label, e.g. "commerce", "email", "analytics". */
+	category?: string;
+	/** Short summary shown in admin install UI. */
+	description?: string;
+}
+
+type AppRegistry = readonly AppRegistryEntry[];
+
+export type { AppRegistryEntry, AppRegistry };

package/src/resolve.ts

@@ -0,0 +1,114 @@
+/**
+ * App composition utilities.
+ *
+ * Merges manifests and chains middleware from multiple AppDefinitions
+ * into a single resolved structure.
+ *
+ * @example
+ * ```ts
+ * import { resolveApps } from "@decocms/apps/commerce/resolve";
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ * import * as resendApp from "@decocms/apps/resend/mod";
+ *
+ * const apps = await Promise.all([
+ *   vtexApp.configure(blocks.vtex, resolveSecret),
+ *   resendApp.configure(blocks.resend, resolveSecret),
+ * ]);
+ *
+ * const resolved = resolveApps(apps.filter(Boolean));
+ * // resolved.manifest — merged manifest from all apps
+ * // resolved.middleware — chained middleware (or undefined)
+ * ```
+ */
+
+import type { AppDefinition, AppManifest, AppMiddleware } from "./app-types";
+
+export interface ResolvedApps {
+	manifest: AppManifest;
+	middleware: AppMiddleware | undefined;
+	resolvables: Record<string, { __resolveType: string; [key: string]: unknown }>;
+}
+
+/**
+ * Resolve an array of app definitions into a single merged structure.
+ *
+ * - Manifests are merged (loaders/actions from all apps).
+ * - Middleware is chained in array order (first app runs outermost).
+ */
+export function resolveApps(apps: AppDefinition[]): ResolvedApps {
+	const mergedManifest: AppManifest = {
+		name: "resolved",
+		loaders: {},
+		actions: {},
+		sections: {},
+	};
+
+	const middlewares: AppMiddleware[] = [];
+	const resolvables: Record<string, { __resolveType: string; [key: string]: unknown }> = {};
+
+	for (const app of flattenDependencies(apps)) {
+		Object.assign(mergedManifest.loaders, app.manifest.loaders);
+		Object.assign(mergedManifest.actions, app.manifest.actions);
+
+		if (app.manifest.sections) {
+			Object.assign(mergedManifest.sections!, app.manifest.sections);
+		}
+
+		if (app.resolvables) {
+			Object.assign(resolvables, app.resolvables);
+		}
+
+		if (app.middleware) {
+			middlewares.push(app.middleware);
+		}
+	}
+
+	return {
+		manifest: mergedManifest,
+		middleware: middlewares.length > 0 ? chainMiddleware(middlewares) : undefined,
+		resolvables,
+	};
+}
+
+/**
+ * Flatten the dependency graph (depth-first, dependencies before dependents).
+ * Deduplicates by app name.
+ */
+function flattenDependencies(apps: AppDefinition[]): AppDefinition[] {
+	const seen = new Set<string>();
+	const result: AppDefinition[] = [];
+
+	function visit(app: AppDefinition) {
+		if (seen.has(app.name)) return;
+		seen.add(app.name);
+
+		if (app.dependencies) {
+			for (const dep of app.dependencies) {
+				visit(dep);
+			}
+		}
+
+		result.push(app);
+	}
+
+	for (const app of apps) {
+		visit(app);
+	}
+
+	return result;
+}
+
+/**
+ * Chain multiple middleware functions into a single one.
+ * First middleware in the array runs outermost (wraps the rest).
+ */
+function chainMiddleware(middlewares: AppMiddleware[]): AppMiddleware {
+	return async (request, next) => {
+		const run = async (i: number): Promise<Response> => {
+			if (i < 0) return next();
+			return middlewares[i](request, () => run(i - 1));
+		};
+
+		return run(middlewares.length - 1);
+	};
+}

package/src/sdk/analytics.ts

@@ -0,0 +1,151 @@
+/**
+ * Analytics mappers — convert schema.org Product to GA4 AnalyticsItem.
+ *
+ * These are the generic, platform-independent mappers. Sites can wrap them
+ * to add custom fields (sellerP, etc.) via the `extend` option.
+ */
+import type { BreadcrumbList, Product } from "../types/commerce";
+
+export interface AnalyticsItem {
+	item_id?: string;
+	item_name?: string;
+	affiliation?: string;
+	coupon?: string;
+	discount?: number;
+	index?: number;
+	item_group_id?: string;
+	item_url?: string;
+	item_brand?: string;
+	item_category?: string;
+	item_category2?: string;
+	item_category3?: string;
+	item_category4?: string;
+	item_category5?: string;
+	item_list_id?: string;
+	item_list_name?: string;
+	item_variant?: string;
+	location_id?: string;
+	price?: number;
+	quantity: number;
+	[key: string]: unknown;
+}
+
+export function mapCategoriesToAnalyticsCategories(categories: string[]): Record<string, string> {
+	return categories.slice(0, 5).reduce(
+		(result, category, index) => {
+			result[`item_category${index === 0 ? "" : index + 1}`] = category;
+			return result;
+		},
+		{} as Record<string, string>,
+	);
+}
+
+export function mapProductCategoryToAnalyticsCategories(category: string): Record<string, string> {
+	return category.split(">").reduce(
+		(result, cat, index) => {
+			result[`item_category${index === 0 ? "" : index}`] = cat.trim();
+			return result;
+		},
+		{} as Record<string, string>,
+	);
+}
+
+export interface MapProductToAnalyticsItemOptions {
+	product: Product;
+	breadcrumbList?: BreadcrumbList;
+	price?: number;
+	lowPrice?: number;
+	listPrice?: number;
+	index?: number;
+	quantity?: number;
+	coupon?: string;
+	/** Extend the result with custom fields (e.g., sellerP, sellerName) */
+	extend?: (product: Product, base: AnalyticsItem) => Record<string, unknown>;
+}
+
+export function mapProductToAnalyticsItem(opts: MapProductToAnalyticsItemOptions): AnalyticsItem {
+	const {
+		product,
+		breadcrumbList,
+		price,
+		lowPrice,
+		listPrice,
+		index = 0,
+		quantity = 1,
+		coupon = "",
+		extend,
+	} = opts;
+
+	const { name, productID, inProductGroupWithID, isVariantOf, url, sku } = product;
+
+	const categories = breadcrumbList?.itemListElement
+		? mapCategoriesToAnalyticsCategories(
+				breadcrumbList.itemListElement.map(({ name: n }) => n ?? "").filter(Boolean),
+			)
+		: mapProductCategoryToAnalyticsCategories(product.category ?? "");
+
+	const base: AnalyticsItem = {
+		item_id: productID,
+		item_group_id: inProductGroupWithID,
+		quantity,
+		coupon,
+		price: lowPrice,
+		index,
+		item_variant: sku,
+		discount: Number((price && listPrice ? listPrice - price : 0).toFixed(2)),
+		item_name: isVariantOf?.name ?? name ?? "",
+		item_brand: product.brand?.name ?? "",
+		item_url: url,
+		...categories,
+	};
+
+	if (extend) {
+		return { ...base, ...extend(product, base) };
+	}
+
+	return base;
+}
+
+export interface MapProductToAnalyticsItemListOptions {
+	product: Product;
+	breadcrumbList?: BreadcrumbList;
+	price?: number;
+	listPrice?: number;
+	index?: number;
+	quantity?: number;
+	coupon?: string;
+}
+
+export function mapProductToAnalyticsItemList(
+	opts: MapProductToAnalyticsItemListOptions,
+): AnalyticsItem {
+	const { product, breadcrumbList, price, listPrice, index = 0, quantity = 1, coupon = "" } = opts;
+
+	const { name, productID, inProductGroupWithID, isVariantOf, url } = product;
+
+	const categories = breadcrumbList?.itemListElement
+		? mapCategoriesToAnalyticsCategories(
+				breadcrumbList.itemListElement.map(({ name: n }) => n ?? "").filter(Boolean),
+			)
+		: mapProductCategoryToAnalyticsCategories(product.category ?? "");
+
+	const finalPrice = typeof price === "number" ? price : 0;
+	const discount =
+		typeof listPrice === "number" && typeof price === "number" ? Math.max(0, listPrice - price) : 0;
+
+	const itemId = inProductGroupWithID ?? isVariantOf?.productGroupID ?? productID;
+
+	return {
+		item_id: itemId,
+		item_group_id: inProductGroupWithID,
+		quantity,
+		coupon,
+		price: finalPrice,
+		index,
+		discount: Number(discount.toFixed(2)),
+		item_name: isVariantOf?.name ?? name ?? "",
+		item_brand: product.brand?.name ?? "",
+		item_url: url,
+		...categories,
+	};
+}

package/src/sdk/formatPrice.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { formatPrice, formatPriceRange } from "./formatPrice";
+
+describe("formatPrice", () => {
+	it("formats a number to BRL by default", () => {
+		const result = formatPrice(123.45);
+		// Intl-formatted with NBSP between "R$" and the number; just check the
+		// digits are present.
+		expect(result).toMatch(/123,45/);
+		expect(result).toMatch(/R\$/);
+	});
+
+	it("returns null for undefined/null", () => {
+		expect(formatPrice(undefined)).toBeNull();
+		expect(formatPrice(null)).toBeNull();
+	});
+
+	it("returns null for non-finite numbers", () => {
+		expect(formatPrice(Number.NaN)).toBeNull();
+		expect(formatPrice(Number.POSITIVE_INFINITY)).toBeNull();
+	});
+
+	it("respects currency + locale overrides", () => {
+		const result = formatPrice(99, "USD", "en-US");
+		expect(result).toMatch(/\$99/);
+	});
+});
+
+describe("formatPriceRange", () => {
+	it("formats a min:max string with the default currency", () => {
+		const result = formatPriceRange("10:50");
+		expect(result).toMatch(/10,00/);
+		expect(result).toMatch(/50,00/);
+		expect(result).toContain(" - ");
+	});
+
+	it("respects currency / locale overrides", () => {
+		const result = formatPriceRange("10:50", "USD", "en-US");
+		expect(result).toMatch(/\$10/);
+		expect(result).toMatch(/\$50/);
+	});
+
+	it("respects a custom separator", () => {
+		const result = formatPriceRange("10:50", "BRL", "pt-BR", " a ");
+		expect(result).toContain(" a ");
+	});
+
+	it("returns the input unchanged when there's no colon", () => {
+		expect(formatPriceRange("not-a-range")).toBe("not-a-range");
+	});
+
+	it("returns the input unchanged when bounds aren't numeric", () => {
+		expect(formatPriceRange("foo:bar")).toBe("foo:bar");
+	});
+
+	it("returns the input unchanged for non-string input", () => {
+		expect(formatPriceRange(undefined as unknown as string)).toBeUndefined();
+	});
+});

package/src/sdk/formatPrice.ts

@@ -0,0 +1,44 @@
+const formatters = new Map<string, Intl.NumberFormat>();
+
+const formatter = (currency: string, locale: string) => {
+	const key = `${currency}::${locale}`;
+
+	if (!formatters.has(key)) {
+		formatters.set(
+			key,
+			new Intl.NumberFormat(locale, {
+				style: "currency",
+				currency,
+			}),
+		);
+	}
+
+	return formatters.get(key)!;
+};
+
+export const formatPrice = (
+	price: number | undefined | null,
+	currency = "BRL",
+	locale = "pt-BR",
+) => (price != null && Number.isFinite(price) ? formatter(currency, locale).format(price) : null);
+
+/**
+ * Formats a "min:max" range string (as VTEX/Shopify Intelligent Search
+ * facets emit) into a localised price range like "R$ 10,00 - R$ 50,00".
+ *
+ * Returns the original input untouched if either bound fails to parse,
+ * so this never crashes a filter UI on a bad facet value.
+ */
+export const formatPriceRange = (
+	value: string,
+	currency = "BRL",
+	locale = "pt-BR",
+	separator = " - ",
+): string => {
+	if (typeof value !== "string" || !value.includes(":")) return value;
+	const [rawMin, rawMax] = value.split(":");
+	const min = formatPrice(Number(rawMin), currency, locale);
+	const max = formatPrice(Number(rawMax), currency, locale);
+	if (min == null || max == null) return value;
+	return `${min}${separator}${max}`;
+};