@revenexx/cover 0.1.0

package/server/utils/liveCatalog.ts

@@ -0,0 +1,234 @@
+import type { ProductCategory, ProductSubcategory } from "../../app/config/navigation";
+import type { Product } from "../../app/composables/useProducts";
+import type { ProductDetail } from "../../app/interfaces/product-detail";
+import type { Locale } from "./locale";
+
+/**
+ * Live catalog access — products and categories from the public revenexx
+ * API. Product reads go against the platform's real Typesense index (the
+ * products app's search collection, exposed at /v1/search/*), categories
+ * come from the products app's category tree (/v1/products/categories).
+ *
+ * The live index has no prices, stocks or images yet — the mapping fills
+ * the storefront contracts with explicit neutral defaults so every surface
+ * (cards, detail, cart) renders without special-casing.
+ */
+
+/** Document shape of the products search collection (search.json v2). */
+export interface LiveProductDoc {
+	id: string;
+	entity_id: string;
+	sku: string;
+	kind: string;
+	enabled: boolean;
+	name: string;
+	description?: string;
+	manufacturer?: string;
+	ean?: string;
+	categories?: string[];
+	category_labels?: string[];
+	attrs?: Record<string, unknown>;
+	locale: string;
+	updated_at?: number;
+}
+
+export interface LiveSearchResponse {
+	found: number;
+	page: number;
+	hits?: { document: LiveProductDoc; highlight?: unknown }[];
+	facet_counts?: { field_name: string; counts?: { value: string; count: number }[] }[];
+}
+
+export interface LiveSearchParams {
+	q: string;
+	queryBy?: string;
+	filterBy?: string;
+	facetBy?: string;
+	sortBy?: string;
+	page?: number;
+	perPage?: number;
+}
+
+const PRODUCT_PLACEHOLDER_IMAGE = "/img/product-placeholder.svg";
+
+/** TODO(markets): resolve from the market's tax classes instead of a constant. */
+const LIVE_DEFAULT_TAX_RATE = 19;
+
+/** The live index has no stock data — treat everything as orderable. */
+const LIVE_DEFAULT_STOCK = { quantity: 9999, maxOrderQuantity: 999999 };
+
+export async function searchLiveProducts(params: LiveSearchParams): Promise<LiveSearchResponse> {
+	return useRevenexxApi().get<LiveSearchResponse>(
+		"/v1/search/collections/products/documents/search",
+		{
+			q: params.q,
+			query_by: params.queryBy ?? "name,sku,description,manufacturer",
+			filter_by: params.filterBy,
+			facet_by: params.facetBy,
+			sort_by: params.sortBy,
+			page: params.page ?? 1,
+			per_page: params.perPage ?? 24,
+		},
+	);
+}
+
+/** Escape a value for a Typesense `filter_by` exact-match clause. */
+export function tsFilterValue(value: string): string {
+	return "`" + value.replace(/`/g, "") + "`";
+}
+
+export function mapLiveDocToProduct(doc: LiveProductDoc): Product {
+	const categorySlug = doc.categories?.[0] ?? "";
+	const category = doc.category_labels?.[0] ?? categorySlug;
+
+	return {
+		id: doc.entity_id,
+		name: doc.name,
+		sku: doc.sku,
+		available: doc.enabled,
+		isOutOfStock: false,
+		prices: [],
+		stocks: [LIVE_DEFAULT_STOCK],
+		tax: { rate: LIVE_DEFAULT_TAX_RATE },
+		image: PRODUCT_PLACEHOLDER_IMAGE,
+		category,
+		categorySlug,
+	};
+}
+
+export function mapLiveDocToDetail(doc: LiveProductDoc): ProductDetail {
+	const syncedAt = doc.updated_at ? new Date(doc.updated_at * 1000).toISOString() : new Date().toISOString();
+
+	return {
+		product: [{
+			id: doc.entity_id,
+			version: 1,
+			name: doc.name,
+			sku: doc.sku,
+			manufacturer: doc.manufacturer ?? "",
+			createdAt: syncedAt,
+			updatedAt: syncedAt,
+			deletedAt: null,
+			available: doc.enabled,
+		}],
+		stocks: [LIVE_DEFAULT_STOCK],
+		tax: { rate: LIVE_DEFAULT_TAX_RATE },
+		descriptions: doc.description
+			? [{ type: "long", content: doc.description }]
+			: [],
+		categories: [
+			...(doc.category_labels?.[0] ? [{ type: "main", name: doc.category_labels[0] }] : []),
+			...(doc.categories?.[0] ? [{ type: "slug", name: doc.categories[0] }] : []),
+		],
+		images: [],
+		attributes: Object.entries(doc.attrs ?? {}).map(([name, value], index) => ({
+			id: index + 1,
+			name,
+			value: String(value),
+		})),
+		prices: [],
+	};
+}
+
+/**
+ * Fetch one product document (`{entity_id}:{locale}`) from the live index.
+ * Uses a filtered search instead of the document-GET route — the search
+ * proxy's document endpoint currently rejects gateway-trust calls
+ * (responds 401 "x-typesense-api-key"), and `id` is filterable anyway.
+ */
+export async function getLiveProductDoc(entityId: string, locale: Locale): Promise<LiveProductDoc | null> {
+	const result = await searchLiveProducts({
+		q: "*",
+		queryBy: "name",
+		filterBy: `id:=${tsFilterValue(`${entityId}:${locale}`)}`,
+		perPage: 1,
+	});
+	return result.hits?.[0]?.document ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Categories — products app tree, cached briefly (it changes rarely and the
+// storefront asks on every navigation render).
+// ---------------------------------------------------------------------------
+
+interface LiveCategoryRow {
+	id: string;
+	code: string;
+	parent_id: string | null;
+	position: number;
+	labels?: Record<string, string> | null;
+}
+
+interface LiveCategoryPage {
+	items: LiveCategoryRow[];
+	page: { total: number; returned: number; hasMore: boolean };
+}
+
+const CATEGORY_CACHE_TTL_MS = 5 * 60 * 1000;
+const CATEGORY_PAGE_LIMIT = 200;
+
+let categoryCache: { rows: LiveCategoryRow[]; loadedAt: number } | null = null;
+
+async function loadLiveCategoryRows(): Promise<LiveCategoryRow[]> {
+	if (categoryCache && Date.now() - categoryCache.loadedAt < CATEGORY_CACHE_TTL_MS) {
+		return categoryCache.rows;
+	}
+
+	const api = useRevenexxApi();
+	const rows: LiveCategoryRow[] = [];
+	let offset = 0;
+	// Paginate defensively — the demo tenant has a few hundred categories.
+	for (let pageIndex = 0; pageIndex < 25; pageIndex++) {
+		const page = await api.get<LiveCategoryPage>("/v1/products/categories", {
+			limit: CATEGORY_PAGE_LIMIT,
+			offset,
+		});
+		rows.push(...page.items);
+		if (!page.page.hasMore) {
+			break;
+		}
+		offset += page.page.returned;
+	}
+
+	categoryCache = { rows, loadedAt: Date.now() };
+	return rows;
+}
+
+function categoryLabel(row: LiveCategoryRow, locale: Locale): string {
+	return row.labels?.[locale] ?? row.labels?.de ?? row.labels?.en ?? row.code;
+}
+
+/**
+ * Build the storefront's two-level category tree from the flat live rows.
+ * A single artificial root (e.g. an imported "web catalog" node) is skipped
+ * so its children become the top-level categories.
+ */
+export async function getLiveCategories(locale: Locale): Promise<ProductCategory[]> {
+	const rows = await loadLiveCategoryRows();
+
+	const byParent = new Map<string | null, LiveCategoryRow[]>();
+	for (const row of rows) {
+		const list = byParent.get(row.parent_id) ?? [];
+		list.push(row);
+		byParent.set(row.parent_id, list);
+	}
+	for (const list of byParent.values()) {
+		list.sort((a, b) => a.position - b.position || a.code.localeCompare(b.code));
+	}
+
+	let roots = byParent.get(null) ?? [];
+	if (roots.length === 1) {
+		roots = byParent.get(roots[0]!.id) ?? [];
+	}
+
+	return roots.map((root): ProductCategory => ({
+		label: categoryLabel(root, locale),
+		slug: root.code,
+		icon: "case",
+		subcategories: (byParent.get(root.id) ?? []).map((child): ProductSubcategory => ({
+			label: categoryLabel(child, locale),
+			slug: child.code,
+			icon: "box",
+		})),
+	}));
+}

package/server/utils/liveInventories.ts

@@ -0,0 +1,76 @@
+import type { H3Event } from "h3";
+
+import type { Product } from "../../app/composables/useProducts";
+import type { ProductDetail } from "../../app/interfaces/product-detail";
+
+/**
+ * Live availability from the inventories app — THE stock call (and the
+ * designated gateway override point for ERP stock). Tracked items get
+ * their real `available` quantity and `orderable` flag; items unknown to
+ * inventory (`tracked: false`) keep selling freely — that is the
+ * storefront's call, and the demo shop makes it permissive.
+ */
+
+const UNTRACKED_STOCK = { quantity: 9999, maxOrderQuantity: 999999 };
+
+interface ItemAvailability {
+	product_id: string | null;
+	sku: string | null;
+	available: number;
+	tracked: boolean;
+	orderable: boolean;
+}
+
+function toStock(entry: ItemAvailability): { quantity: number; maxOrderQuantity: number } {
+	if (!entry.tracked) {
+		return UNTRACKED_STOCK;
+	}
+	const available = Math.max(0, Math.floor(entry.available));
+	return { quantity: available, maxOrderQuantity: available };
+}
+
+async function fetchAvailability(items: Array<{ product_id?: string; sku?: string }>): Promise<Map<string, ItemAvailability>> {
+	const { availability } = await useRevenexxApi().post<{ availability: ItemAvailability[] }>(
+		"/v1/inventories/availability",
+		{ items },
+	);
+	const byKey = new Map<string, ItemAvailability>();
+	for (const entry of availability) {
+		if (entry.product_id) byKey.set(entry.product_id, entry);
+		else if (entry.sku) byKey.set(entry.sku, entry);
+	}
+	return byKey;
+}
+
+/** Batch-enrich live catalog products with real stock (cards, lists, search). */
+export async function enrichProductsWithLiveAvailability(event: H3Event, products: Product[]): Promise<Product[]> {
+	if (products.length === 0) {
+		return products;
+	}
+	const byKey = await fetchAvailability(products.map(p => ({ product_id: p.id, sku: p.sku })));
+	return products.map((product) => {
+		const entry = byKey.get(product.id) ?? byKey.get(product.sku);
+		if (!entry) {
+			return product;
+		}
+		return {
+			...product,
+			stocks: [toStock(entry)],
+			isOutOfStock: entry.tracked && !entry.orderable,
+		};
+	});
+}
+
+/** Single-product variant for the PDP detail payload. */
+export async function enrichDetailWithLiveAvailability(event: H3Event, detail: ProductDetail): Promise<ProductDetail> {
+	const product = detail.product[0];
+	if (!product) {
+		return detail;
+	}
+	const byKey = await fetchAvailability([{ product_id: product.id, sku: product.sku }]);
+	const entry = byKey.get(product.id) ?? byKey.get(product.sku);
+	if (!entry) {
+		return detail;
+	}
+	return { ...detail, stocks: [toStock(entry)] };
+}

package/server/utils/liveOrders.ts

@@ -0,0 +1,139 @@
+import type { H3Event } from "h3";
+
+import type { StoredSession } from "../../app/interfaces/auth";
+import type { AccountOrder, AccountOrderPosition, AccountOrderStatus, AccountOrderPaymentStatus } from "../../app/interfaces/account/order-list";
+
+/**
+ * Live orders via the orders app — placing from the checkout snapshot and
+ * mapping the order aggregate back into the account history contracts.
+ */
+
+export interface LiveOrderItem {
+	id: string;
+	position: number;
+	product_id: string | null;
+	sku: string | null;
+	name: string;
+	product: Record<string, unknown> | null;
+	quantity: number;
+	unit_price: number;
+	line_total: number;
+	quantity_shipped: number;
+}
+
+export interface LiveOrder {
+	id: string;
+	number: string;
+	customer_order_number: string | null;
+	status: "pending" | "placed" | "in_fulfillment" | "completed" | "cancelled";
+	payment_status: string;
+	fulfillment_status: string;
+	currency: string;
+	grand_total: number;
+	billing_address: Record<string, unknown> | null;
+	shipping_address: Record<string, unknown> | null;
+	payment: { method?: string } | null;
+	placed_at: string | null;
+	created_at: string;
+	acknowledged_at: string | null;
+	completed_at: string | null;
+	items?: LiveOrderItem[];
+	shipments?: Array<{ number: string; carrier: string | null; tracking_code: string | null; shipped_at: string }>;
+}
+
+/** The buyer's identity refs from the session cookie (guests place openly). */
+export function sessionOrderRefs(event: H3Event): { contact_id?: string; organization_id?: string } {
+	const raw = getCookie(event, SESSION_COOKIE_NAME);
+	if (!raw) {
+		return {};
+	}
+	try {
+		const parsed = JSON.parse(raw) as StoredSession;
+		return {
+			...(parsed.contactId ? { contact_id: parsed.contactId } : {}),
+			...(parsed.organizationId ? { organization_id: parsed.organizationId } : {}),
+		};
+	}
+	catch {
+		return {};
+	}
+}
+
+function mapStatus(order: LiveOrder): AccountOrderStatus {
+	if (order.status === "cancelled") return "cancelled";
+	if (order.status === "completed") return "shipped";
+	return "processing";
+}
+
+function mapPaymentStatus(status: string): AccountOrderPaymentStatus {
+	if (status === "paid") return "paid";
+	if (status === "refunded") return "refunded";
+	return "open";
+}
+
+const addressLine = (a: Record<string, unknown> | null | undefined): string =>
+	[a?.companyName, a?.street, `${a?.postalCode ?? ""} ${a?.city ?? ""}`.trim()]
+		.filter(Boolean).join(" · ");
+
+function mapPositions(items: LiveOrderItem[] | undefined): AccountOrderPosition[] {
+	return (items ?? []).map((item) => {
+		const snapshot = (item.product ?? {}) as Record<string, unknown>;
+		return {
+			id: item.product_id ?? item.sku ?? item.id,
+			sku: item.sku ?? "",
+			name: item.name,
+			...(snapshot.image ? { image: String(snapshot.image) } : {}),
+			quantity: Number(item.quantity),
+			unitPrice: Number(item.unit_price),
+			lineTotal: Number(item.line_total),
+			...(snapshot.categorySlug ? { categorySlug: String(snapshot.categorySlug) } : {}),
+			...(snapshot.subcategorySlug ? { subcategorySlug: String(snapshot.subcategorySlug) } : {}),
+		};
+	});
+}
+
+/** Live order aggregate → the account history contract. */
+export function mapLiveOrderToAccount(order: LiveOrder): AccountOrder {
+	const placed = order.placed_at ?? order.created_at;
+	const day = (iso: string | null | undefined): string => (iso ?? placed).slice(0, 10);
+	const shipments = order.shipments ?? [];
+	const lastTracked = [...shipments].reverse().find(s => s.tracking_code);
+	const shippedAt = shipments[0]?.shipped_at;
+
+	const progress: NonNullable<AccountOrder["progress"]> = [{ step: "ordered", date: day(placed) }];
+	if (order.status !== "pending" && order.status !== "cancelled") {
+		progress.push({ step: "processing", date: day(order.acknowledged_at ?? placed) });
+	}
+	if (shipments.length > 0) {
+		progress.push({ step: "shipped", date: day(shippedAt) });
+	}
+
+	return {
+		id: order.number,
+		date: day(placed),
+		status: mapStatus(order),
+		paymentStatus: mapPaymentStatus(order.payment_status),
+		total: Number(order.grand_total),
+		currency: order.currency,
+		...(order.customer_order_number ? { orderNumber: order.customer_order_number } : {}),
+		positions: mapPositions(order.items),
+		deliveryAddress: addressLine(order.shipping_address),
+		billingAddress: addressLine(order.billing_address),
+		...(order.payment?.method ? { paymentMethod: order.payment.method } : {}),
+		...(lastTracked
+			? { tracking: { carrier: lastTracked.carrier ?? "", trackingNumber: lastTracked.tracking_code ?? "" } }
+			: {}),
+		progress,
+	};
+}
+
+/** Fetch one live order by its display number (the account history id). */
+export async function getLiveOrderByNumber(number: string): Promise<LiveOrder | null> {
+	const api = useRevenexxApi();
+	const { items } = await api.get<{ items: LiveOrder[] }>("/v1/orders", { number, limit: 1 });
+	const row = items[0];
+	if (!row) {
+		return null;
+	}
+	return api.get<LiveOrder>(`/v1/orders/${row.id}`);
+}

package/server/utils/livePrices.ts

@@ -0,0 +1,93 @@
+import type { H3Event } from "h3";
+
+import type { StoredSession } from "../../app/interfaces/auth";
+import type { Product } from "../../app/composables/useProducts";
+import type { ProductDetail } from "../../app/interfaces/product-detail";
+
+/**
+ * Live prices from the prices app — THE live price call. The storefront's
+ * price shape is the tier map (`prices: [{ "<qty>": totalCents }]`), so the
+ * resolve response (unit prices per tier) converts to total cents per tier
+ * quantity. A product the prices app answers `on_request` for keeps an
+ * EMPTY prices array — the UI renders "price on request", never €0.
+ */
+
+interface ResolvedPrice {
+	product_id: string | null;
+	sku: string | null;
+	on_request: boolean;
+	unit_price: number | null;
+	tiers: Array<{ quantity_min: number; unit_price: number }>;
+}
+
+/** The buyer's price scope from the session (guests resolve openly). */
+function priceContext(event: H3Event): { contact_id?: string; organization_id?: string } {
+	const raw = getCookie(event, SESSION_COOKIE_NAME);
+	if (!raw) {
+		return {};
+	}
+	try {
+		const parsed = JSON.parse(raw) as StoredSession;
+		return {
+			...(parsed.contactId ? { contact_id: parsed.contactId } : {}),
+			...(parsed.organizationId ? { organization_id: parsed.organizationId } : {}),
+		};
+	}
+	catch {
+		return {};
+	}
+}
+
+/** Resolve tier ladder → the storefront tier map (quantity → TOTAL cents). */
+function toPriceMap(resolved: ResolvedPrice): { [key: string]: number }[] {
+	if (resolved.on_request || resolved.unit_price === null) {
+		return [];
+	}
+	const tiers = resolved.tiers.length
+		? resolved.tiers
+		: [{ quantity_min: 1, unit_price: resolved.unit_price }];
+	const map: { [key: string]: number } = {};
+	for (const tier of tiers) {
+		map[String(tier.quantity_min)] = Math.round(tier.unit_price * tier.quantity_min * 100);
+	}
+	return [map];
+}
+
+/**
+ * Batch-enrich live catalog products with resolved prices. Products the
+ * prices app does not price keep `prices: []` (→ price on request).
+ */
+export async function enrichProductsWithLivePrices(event: H3Event, products: Product[]): Promise<Product[]> {
+	if (products.length === 0) {
+		return products;
+	}
+	const { prices } = await useRevenexxApi().post<{ prices: ResolvedPrice[] }>("/v1/prices/resolve", {
+		items: products.map(p => ({ product_id: p.id, sku: p.sku, quantity: 1 })),
+		...priceContext(event),
+	});
+
+	const byKey = new Map<string, ResolvedPrice>();
+	for (const price of prices) {
+		if (price.product_id) byKey.set(price.product_id, price);
+		else if (price.sku) byKey.set(price.sku, price);
+	}
+
+	return products.map((product) => {
+		const resolved = byKey.get(product.id) ?? byKey.get(product.sku);
+		return resolved ? { ...product, prices: toPriceMap(resolved) } : { ...product, prices: [] };
+	});
+}
+
+/** Single-product variant for the PDP detail payload. */
+export async function enrichDetailWithLivePrices(event: H3Event, detail: ProductDetail): Promise<ProductDetail> {
+	const product = detail.product[0];
+	if (!product) {
+		return detail;
+	}
+	const { prices } = await useRevenexxApi().post<{ prices: ResolvedPrice[] }>("/v1/prices/resolve", {
+		items: [{ product_id: product.id, sku: product.sku, quantity: 1 }],
+		...priceContext(event),
+	});
+	const resolved = prices[0];
+	return { ...detail, prices: resolved ? toPriceMap(resolved) : [] };
+}

package/server/utils/locale.ts

@@ -0,0 +1,39 @@
+import { getCookie, getHeader, type H3Event } from "h3";
+
+// Update when adding/removing locale subdirectories in i18n/locales/
+const SUPPORTED = new Set(["de", "en"] as const);
+export type Locale = "de" | "en";
+export interface LocalizedText {
+	de?: string;
+	en?: string;
+}
+
+function normalizeLocale(input?: string | null): Locale | null {
+	if (!input) {
+		return null;
+	}
+
+	const code = input.toLowerCase().split("-")[0];
+	return SUPPORTED.has(code as Locale) ? (code as Locale) : null;
+}
+
+export function resolveLocale(event: H3Event): Locale {
+	const fromHeader = normalizeLocale(getHeader(event, "x-locale"));
+	if (fromHeader) {
+		return fromHeader;
+	}
+
+	const fromCookie = normalizeLocale(getCookie(event, "cover-locale"));
+	if (fromCookie) {
+		return fromCookie;
+	}
+
+	const accept = getHeader(event, "accept-language");
+	const fromAccept = normalizeLocale(accept?.split(",")[0] ?? null);
+	if (fromAccept) {
+		return fromAccept;
+	}
+
+	const configDefault = useRuntimeConfig().public.defaultLocale;
+	return (SUPPORTED.has(configDefault as Locale) ? configDefault : "de") as Locale;
+}

package/server/utils/logService.ts

@@ -0,0 +1,19 @@
+import { resolve } from "node:path";
+
+import type { ILogService } from "../interfaces/log";
+import { LogService } from "../services/LogService";
+
+const logService: ILogService = new LogService(
+	resolve(process.cwd(), "logs/server.log"),
+);
+
+export function getLogService(): ILogService {
+	return logService;
+}
+
+export function toErrorContext(err: unknown): Record<string, unknown> {
+	if (err instanceof Error) {
+		return { errorMessage: err.message };
+	}
+	return { errorMessage: String(err) };
+}

package/server/utils/marketService.ts

@@ -0,0 +1,24 @@
+import type { H3Event } from "h3";
+
+import type { IMarketService } from "../interfaces/market";
+import { ApiMarketService } from "../services/ApiMarketService";
+import { MockMarketService } from "../services/MockMarketService";
+
+/**
+ * Registry of available market implementations:
+ * - "mock" — bundled demo markets (markets.json)
+ * - "api"  — live markets via the public revenexx API (markets app)
+ */
+const serviceRegistry: Record<string, IMarketService> = {
+	mock: new MockMarketService("markets.json"),
+	api: new ApiMarketService(),
+};
+
+export function getMarketService(event?: H3Event): IMarketService {
+	const key = resolveServiceKey(event, {
+		domain: "marketService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+	return serviceRegistry[key] ?? serviceRegistry["mock"]!;
+}

package/server/utils/orderService.ts

@@ -0,0 +1,14 @@
+import type { H3Event } from "h3";
+
+/**
+ * The orders domain has no service class — endpoints branch on the
+ * resolved registry key ("mock" = demo order ids + mutable JSON history,
+ * "api" = the orders app via the public revenexx API).
+ */
+export function resolveOrderServiceKey(event?: H3Event): string {
+	return resolveServiceKey(event, {
+		domain: "orderService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+}

package/server/utils/paymentService.ts

@@ -0,0 +1,14 @@
+import type { H3Event } from "h3";
+
+/**
+ * The payments domain has no service class — the BFF endpoints branch on
+ * the resolved registry key ("mock" = demo profile methods, "api" = the
+ * payments app via the public revenexx API).
+ */
+export function resolvePaymentServiceKey(event?: H3Event): string {
+	return resolveServiceKey(event, {
+		domain: "paymentService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+}

package/server/utils/priceService.ts

@@ -0,0 +1,14 @@
+import type { H3Event } from "h3";
+
+/**
+ * The prices domain has no service class — endpoints branch on the
+ * resolved registry key ("mock" = demo data already carries prices,
+ * "api" = the prices app via the public revenexx API).
+ */
+export function resolvePriceServiceKey(event?: H3Event): string {
+	return resolveServiceKey(event, {
+		domain: "priceService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+}