@revenexx/cover 0.1.0

package/server/utils/productService.ts

@@ -0,0 +1,28 @@
+import type { H3Event } from "h3";
+
+import type { IProductService } from "../interfaces/product";
+import { ApiProductService } from "../services/ApiProductService";
+import { LocalFileProductService } from "../services/LocalFileProductService";
+
+const serviceRegistry: Record<string, IProductService> = {
+	mock: new LocalFileProductService("product-list.json", "product-detail.json"),
+	api: new ApiProductService(),
+};
+
+export function getProductService(event?: H3Event): IProductService {
+	const key = resolveServiceKey(event, {
+		domain: "productService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+	return serviceRegistry[key] ?? serviceRegistry["mock"]!;
+}
+
+/** Resolved registry key — search endpoints branch between local index and live API. */
+export function resolveProductServiceKey(event?: H3Event): string {
+	return resolveServiceKey(event, {
+		domain: "productService",
+		mockKey: "mock",
+		liveKey: "api",
+	});
+}

package/server/utils/productsSchema.ts

@@ -0,0 +1,30 @@
+import type { CollectionCreateSchema } from "typesense/lib/Typesense/Collections";
+
+export const PRODUCTS_COLLECTION = "products";
+
+export const productsSchema = {
+	name: PRODUCTS_COLLECTION,
+	enable_nested_fields: true,
+	fields: [
+		{ name: "name", type: "string" as const },
+		{ name: "sku", type: "string" as const },
+		{ name: "manufacturer", type: "string" as const, facet: true },
+		{ name: "available", type: "bool" as const, facet: true },
+		{ name: "stockQuantity", type: "int32" as const },
+		{ name: "price", type: "int32" as const },
+		{ name: "prices", type: "object" as const },
+		{ name: "description", type: "string" as const, optional: true },
+		{ name: "category", type: "string" as const, facet: true },
+		{ name: "categorySlug", type: "string" as const, facet: true },
+		{ name: "subcategory", type: "string" as const, facet: true, optional: true },
+		{ name: "subcategorySlug", type: "string" as const, facet: true, optional: true },
+		{ name: "slug", type: "string" as const },
+		{ name: "image", type: "string" as const, optional: true },
+		{ name: "taxRate", type: "float" as const },
+	],
+	default_sorting_field: "price",
+} satisfies CollectionCreateSchema;
+
+export const FACET_FIELDS: string[] = productsSchema.fields
+	.filter(f => "facet" in f && f.facet === true)
+	.map(f => f.name);

package/server/utils/revenexxApi.ts

@@ -0,0 +1,136 @@
+/**
+ * Mini client for the public revenexx gateway (api.revenexx.com) — the
+ * stand-in for the generated web SDKs that do not exist yet. Every live
+ * "api"-keyed BFF implementation goes through this client; once the real
+ * SDKs land, only the service implementations swap, the BFF contracts stay.
+ *
+ * Auth model: tenant API key (server-side only, never reaches the client).
+ * Configure via runtime config / env:
+ *   NUXT_REVENEXX_API_URL   (default https://api.revenexx.com)
+ *   NUXT_REVENEXX_TENANT    (tenant slug, e.g. "revenexx")
+ *   NUXT_REVENEXX_API_KEY   (rvxk_… gateway key)
+ */
+
+export class RevenexxApiError extends Error {
+	readonly statusCode: number;
+	readonly type: string;
+
+	constructor(statusCode: number, type: string, message: string) {
+		super(message);
+		this.name = "RevenexxApiError";
+		this.statusCode = statusCode;
+		this.type = type;
+	}
+}
+
+/**
+ * Expected user-facing failures (wrong credentials, duplicate email, …) are
+ * forwarded to the client as-is; everything else is an infrastructure error.
+ */
+const API_USER_ERROR_STATUS = new Set([400, 401, 404, 409, 429]);
+
+export function isApiUserError(err: unknown): err is RevenexxApiError {
+	return err instanceof RevenexxApiError && API_USER_ERROR_STATUS.has(err.statusCode);
+}
+
+/**
+ * The customers app's auth passthrough answers with a generic error envelope
+ * (no machine type). Map the HTTP status onto the platform error types the
+ * client-side auth store already translates, so mock/sdk/api modes produce
+ * identical UX for the standard failures.
+ */
+export function apiAuthErrorType(err: RevenexxApiError): string {
+	switch (err.statusCode) {
+		case 401: return "user_invalid_credentials";
+		case 404: return "user_not_found";
+		case 409: return "user_email_already_exists";
+		case 429: return "general_rate_limit_exceeded";
+		default: return err.type;
+	}
+}
+
+/** Diagnostic fields for structured logs — never includes the API key. */
+export function apiErrorContext(err: unknown): Record<string, unknown> {
+	if (err instanceof RevenexxApiError) {
+		return { apiStatus: err.statusCode, apiType: err.type, apiMessage: err.message };
+	}
+	return { errorMessage: err instanceof Error ? err.message : String(err) };
+}
+
+export interface RevenexxApiRequest {
+	readonly method?: "GET" | "POST" | "PUT" | "DELETE";
+	readonly query?: Record<string, string | number | boolean | undefined>;
+	readonly body?: unknown;
+}
+
+export interface RevenexxApiClient {
+	request<T>(path: string, options?: RevenexxApiRequest): Promise<T>;
+	get<T>(path: string, query?: RevenexxApiRequest["query"]): Promise<T>;
+	post<T>(path: string, body?: unknown): Promise<T>;
+	put<T>(path: string, body?: unknown): Promise<T>;
+}
+
+let client: RevenexxApiClient | null = null;
+
+export function useRevenexxApi(): RevenexxApiClient {
+	if (client) {
+		return client;
+	}
+
+	const config = useRuntimeConfig();
+	const baseUrl = String(config.revenexxApiUrl || "https://api.revenexx.com").replace(/\/+$/, "");
+	const tenant = String(config.revenexxTenant || "");
+	const apiKey = String(config.revenexxApiKey || "");
+
+	async function request<T>(path: string, options: RevenexxApiRequest = {}): Promise<T> {
+		if (!tenant || !apiKey) {
+			throw new RevenexxApiError(503, "api_not_configured", "revenexx API credentials are not configured (NUXT_REVENEXX_TENANT / NUXT_REVENEXX_API_KEY)");
+		}
+
+		const url = new URL(baseUrl + path);
+		for (const [key, value] of Object.entries(options.query ?? {})) {
+			if (value !== undefined) {
+				url.searchParams.set(key, String(value));
+			}
+		}
+
+		const response = await fetch(url, {
+			method: options.method ?? "GET",
+			headers: {
+				"X-Revenexx-Tenant": tenant,
+				"X-Revenexx-Api-Key": apiKey,
+				"Accept": "application/json",
+				...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+			},
+			...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+		});
+
+		const text = await response.text();
+		let payload: unknown = null;
+		try {
+			payload = text ? JSON.parse(text) : null;
+		}
+		catch {
+			payload = null;
+		}
+
+		if (!response.ok) {
+			const envelope = (payload ?? {}) as { type?: string; message?: string; error?: string };
+			throw new RevenexxApiError(
+				response.status,
+				envelope.type ?? "api_error",
+				envelope.message ?? envelope.error ?? `revenexx API responded with ${response.status}`,
+			);
+		}
+
+		return payload as T;
+	}
+
+	client = {
+		request,
+		get: (path, query) => request(path, { query }),
+		post: (path, body) => request(path, { method: "POST", body }),
+		put: (path, body) => request(path, { method: "PUT", body }),
+	};
+	return client;
+}

package/server/utils/schemaService.ts

@@ -0,0 +1,25 @@
+import type { H3Event } from "h3";
+
+import type { ISchemaService } from "../interfaces/schema";
+import { LocalFileSchemaService } from "../services/LocalFileSchemaService";
+
+/**
+ * Registry of available schema service implementations.
+ * The active implementation is selected by the `schemaService` key in app.config.ts.
+ * Add new entries here when additional providers (CMS, remote API, etc.) are implemented.
+ */
+const serviceRegistry: Record<string, ISchemaService> = {
+	"local-file": new LocalFileSchemaService("forms/checkout"),
+};
+
+/**
+ * Returns the schema service registered for the current app configuration.
+ * Falls back to "local-file" if the configured key is not found.
+ */
+export function getSchemaService(event?: H3Event): ISchemaService {
+	const key = resolveServiceKey(event, {
+		domain: "schemaService",
+		mockKey: "local-file",
+	});
+	return serviceRegistry[key] ?? serviceRegistry["local-file"]!;
+}

package/server/utils/serviceMode.ts

@@ -0,0 +1,70 @@
+import type { H3Event } from "h3";
+
+/**
+ * Per-request service mode resolution — the demo/live switch.
+ *
+ * Selection order for every BFF domain:
+ *   1. per-domain override from the dev-mode cookie (set by the dev panel)
+ *   2. global mode from the dev-mode cookie ("live" picks the domain's live
+ *      key when one exists, "mock" forces the mock key)
+ *   3. the app.config registry key (layer default: mock)
+ *
+ * The cookie is intentionally readable client-side so the demo shop's dev
+ * panel can render the current state without an extra endpoint.
+ */
+
+export const DEV_MODE_COOKIE = "cover-dev-mode";
+
+export type DevMode = "mock" | "live";
+
+export interface DevModeState {
+	mode?: DevMode;
+	/** Per-domain registry-key overrides, e.g. { accountService: "sdk" } */
+	overrides?: Record<string, string>;
+}
+
+export interface ServiceDomain {
+	/** app.config registry key name, e.g. "accountService" */
+	domain: string;
+	/** Registry key serving bundled demo data */
+	mockKey: string;
+	/** Registry key of the live implementation, once one exists */
+	liveKey?: string;
+}
+
+export function readDevModeState(event?: H3Event): DevModeState {
+	if (!event) {
+		return {};
+	}
+	const raw = getCookie(event, DEV_MODE_COOKIE);
+	if (!raw) {
+		return {};
+	}
+	try {
+		const parsed = JSON.parse(raw) as DevModeState;
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	}
+	catch {
+		return {};
+	}
+}
+
+export function resolveServiceKey(event: H3Event | undefined, def: ServiceDomain): string {
+	const state = readDevModeState(event);
+
+	const override = state.overrides?.[def.domain];
+	if (override) {
+		return override;
+	}
+
+	if (state.mode === "live" && def.liveKey) {
+		return def.liveKey;
+	}
+	if (state.mode === "mock") {
+		return def.mockKey;
+	}
+
+	const config = useAppConfig() as Record<string, unknown>;
+	const configured = config[def.domain];
+	return typeof configured === "string" ? configured : def.mockKey;
+}

package/server/utils/shippingService.ts

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

package/server/utils/shopSdk.ts

@@ -0,0 +1,88 @@
+import { Account, Client, RevenexxException } from "@revenexx/sdk";
+
+let baseClient: Client | null = null;
+
+function getBaseClient(): Client {
+	if (baseClient) {
+		return baseClient;
+	}
+	const config = useRuntimeConfig();
+	baseClient = new Client();
+	baseClient
+		.setEndpoint(config.webSdkApiUrl as string)
+		.setProject(config.webSdkProject as string)
+		.setDevKey(config.webSdkDevKey as string);
+	return baseClient;
+}
+
+export function useShopSdkAccount(): Account {
+	return new Account(getBaseClient());
+}
+
+export function useAuthenticatedAccount(fallbackCookie: string): Account {
+	const config = useRuntimeConfig();
+	const client = new Client();
+	client
+		.setEndpoint(config.webSdkApiUrl as string)
+		.setProject(config.webSdkProject as string)
+		.setDevKey(config.webSdkDevKey as string);
+	client.headers["X-Fallback-Cookies"] = fallbackCookie;
+	return new Account(client);
+}
+
+const SDK_USER_ERROR_TYPES = new Set([
+	"user_invalid_credentials",
+	"user_not_found",
+	"user_blocked",
+	"general_rate_limit_exceeded",
+	"user_session_already_exists",
+	"user_email_already_exists",
+	"user_invalid_token",
+	"general_argument_invalid",
+	"password_recently_used",
+]);
+
+/**
+ * Returns true for expected user-facing errors (wrong credentials, rate limit, etc.)
+ * that should be forwarded to the client as-is without server-side logging.
+ * Everything else is treated as an infrastructure error.
+ */
+export function isSdkUserError(err: unknown): err is RevenexxException {
+	return err instanceof RevenexxException && SDK_USER_ERROR_TYPES.has(err.type);
+}
+
+/**
+ * Extracts diagnostic fields from an SDK error for structured log entries.
+ * Does not include secrets (API key is never logged).
+ */
+export function sdkErrorContext(err: unknown): Record<string, unknown> {
+	if (err instanceof RevenexxException) {
+		return { sdkCode: err.code, sdkType: err.type, sdkMessage: err.message };
+	}
+	return { errorMessage: err instanceof Error ? err.message : String(err) };
+}
+
+export async function withCookieCapture<T>(
+	fn: () => Promise<T>,
+): Promise<{ result: T; fallbackCookie: string }> {
+	let fallbackCookie = "";
+	const origFetch = globalThis.fetch;
+	globalThis.fetch = async (
+		input: RequestInfo | URL,
+		init?: RequestInit,
+	) => {
+		const res = await origFetch(input, init);
+		const header = res.headers.get("x-fallback-cookies");
+		if (header) {
+			fallbackCookie = header;
+		}
+		return res;
+	};
+	try {
+		const result = await fn();
+		return { result, fallbackCookie };
+	}
+	finally {
+		globalThis.fetch = origFetch;
+	}
+}

package/server/utils/themeService.ts

@@ -0,0 +1,16 @@
+import type { H3Event } from "h3";
+
+import type { IThemeService } from "../interfaces/theme";
+import { LocalFileThemeService } from "../services/LocalFileThemeService";
+
+const serviceRegistry: Record<string, IThemeService> = {
+	mock: new LocalFileThemeService("themes.json"),
+};
+
+export function getThemeService(event?: H3Event): IThemeService {
+	const key = resolveServiceKey(event, {
+		domain: "themeService",
+		mockKey: "mock",
+	});
+	return serviceRegistry[key] ?? serviceRegistry["mock"]!;
+}

package/server/utils/typesense.ts

@@ -0,0 +1,27 @@
+import { Client } from "typesense";
+import type { ConfigurationOptions } from "typesense";
+
+let client: Client | null = null;
+
+export function useTypesense(): Client {
+	if (client) {
+		return client;
+	}
+
+	const config = useRuntimeConfig();
+
+	const options: ConfigurationOptions = {
+		apiKey: config.typesenseApiKey as string,
+		nodes: [
+			{
+				host: config.typesenseHost as string,
+				port: config.typesensePort as number,
+				protocol: config.typesenseProtocol as string,
+			},
+		],
+		connectionTimeoutSeconds: 5,
+	};
+
+	client = new Client(options);
+	return client;
+}