@usequark/quark-create-app 1.23.11

package/templates/base-project/apps/web/src/lib/analytics/umami-marketing.js

@@ -0,0 +1,131 @@
+const CAMPAIGN_PARAM_NAMES = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_term",
+	"utm_content",
+];
+
+const RELATIVE_URL_BASE = "https://quark.invalid";
+
+function getTrimmedString(value) {
+	return typeof value === "string" ? value.trim() : "";
+}
+
+function escapeHtml(value) {
+	return String(value)
+		.replaceAll("&", "&")
+		.replaceAll("<", "&lt;")
+		.replaceAll(">", "&gt;")
+		.replaceAll('"', "&quot;")
+		.replaceAll("'", "&#39;");
+}
+
+function normalizeAbsoluteHttpUrl(value) {
+	const trimmed = getTrimmedString(value);
+	if (!trimmed) return "";
+
+	try {
+		const parsed = new URL(trimmed);
+		if (!["http:", "https:"].includes(parsed.protocol)) {
+			return "";
+		}
+
+		return parsed.toString();
+	} catch {
+		return "";
+	}
+}
+
+function parseCampaignUrl(value) {
+	const trimmed = getTrimmedString(value);
+	if (!trimmed) return null;
+
+	const absoluteUrl = normalizeAbsoluteHttpUrl(trimmed);
+	if (absoluteUrl) {
+		return {
+			isAbsolute: true,
+			url: new URL(absoluteUrl),
+		};
+	}
+
+	if (
+		trimmed.startsWith("/") ||
+		trimmed.startsWith("?") ||
+		trimmed.startsWith("#")
+	) {
+		return {
+			isAbsolute: false,
+			url: new URL(trimmed, RELATIVE_URL_BASE),
+		};
+	}
+
+	return null;
+}
+
+export function buildCampaignUrl(href, campaign = {}) {
+	const parsed = parseCampaignUrl(href);
+	if (!parsed) return "";
+
+	for (const [key, value] of Object.entries(campaign)) {
+		if (!CAMPAIGN_PARAM_NAMES.includes(key)) continue;
+
+		const trimmed = getTrimmedString(value);
+		if (!trimmed) continue;
+
+		parsed.url.searchParams.set(key, trimmed);
+	}
+
+	if (parsed.isAbsolute) {
+		return parsed.url.toString();
+	}
+
+	return `${parsed.url.pathname}${parsed.url.search}${parsed.url.hash}`;
+}
+
+function normalizeLinkHref(value) {
+	const parsed = parseCampaignUrl(value);
+	if (!parsed) return "";
+
+	if (parsed.isAbsolute) {
+		return parsed.url.toString();
+	}
+
+	return `${parsed.url.pathname}${parsed.url.search}${parsed.url.hash}`;
+}
+
+export function resolveUmamiLinkHref({ href = "", trackingHref = "" } = {}) {
+	return normalizeAbsoluteHttpUrl(trackingHref) || normalizeLinkHref(href);
+}
+
+export function getUmamiPixelProps(
+	pixelUrl,
+	{ alt = "", width = 1, height = 1 } = {},
+) {
+	const normalizedPixelUrl = normalizeAbsoluteHttpUrl(pixelUrl);
+	if (!normalizedPixelUrl) return null;
+
+	return {
+		src: normalizedPixelUrl,
+		alt: getTrimmedString(alt),
+		width,
+		height,
+		decoding: "async",
+		"aria-hidden": "true",
+		referrerPolicy: "strict-origin-when-cross-origin",
+		style: {
+			border: 0,
+			display: "none",
+			height: "1px",
+			overflow: "hidden",
+			width: "1px",
+		},
+	};
+}
+
+export function getUmamiEmailPixelHtml(pixelUrl) {
+	const normalizedPixelUrl = normalizeAbsoluteHttpUrl(pixelUrl);
+	if (!normalizedPixelUrl) return "";
+
+	return `<img src="${escapeHtml(normalizedPixelUrl)}" alt="" width="1" height="1" decoding="async" aria-hidden="true" style="display:none !important;width:1px;height:1px;overflow:hidden;border:0;" />`;
+}

package/templates/base-project/apps/web/src/lib/analytics/umami-replay.js

@@ -0,0 +1,204 @@
+import { createLogger } from "@techstream/quark-core/logger";
+import { getUmamiConfig, normalizeUmamiUrl } from "./umami-config.js";
+
+const log = createLogger("umami-replay");
+
+export const UMAMI_REPLAY_DEFAULTS = Object.freeze({
+	// Validate end-to-end at 100% before lowering sampling (see REPLAY.md).
+	sampleRate: 1,
+	flushIntervalMs: 10000,
+	flushEventCount: 100,
+	maxDurationMs: 300000,
+	sessionPollIntervalMs: 100,
+	// Wait indefinitely for the session cache: the token only appears after
+	// the first /api/send round-trip, which can be delayed on slow networks.
+	// Cancellation is handled via AbortSignal from the recorder.
+	sessionPollAttempts: Infinity,
+	maskLevel: "moderate",
+	blockSelector: "[data-umami-block]",
+});
+
+export function shouldSampleReplay(
+	randomValue = Math.random(),
+	sampleRate = UMAMI_REPLAY_DEFAULTS.sampleRate,
+) {
+	if (sampleRate >= 1) return true;
+	if (sampleRate <= 0) return false;
+	return randomValue <= sampleRate;
+}
+
+export function getReplayMaskConfig(
+	maskLevel = UMAMI_REPLAY_DEFAULTS.maskLevel,
+) {
+	if (maskLevel === "strict") {
+		return {
+			maskAllInputs: true,
+			maskTextSelector: "*",
+		};
+	}
+
+	return {
+		maskAllInputs: true,
+	};
+}
+
+export function createReplayBuffer() {
+	let events = [];
+
+	return {
+		push(event) {
+			events.push(event);
+			return events.length;
+		},
+		drain() {
+			const drained = events;
+			events = [];
+			return drained;
+		},
+		restore(drainedEvents) {
+			if (!Array.isArray(drainedEvents) || !drainedEvents.length)
+				return events.length;
+			events = [...drainedEvents, ...events];
+			return events.length;
+		},
+		size() {
+			return events.length;
+		},
+	};
+}
+
+export function buildReplayEndpoint(env = process.env) {
+	const url =
+		typeof env === "string" ? normalizeUmamiUrl(env) : getUmamiConfig(env).url;
+
+	return url ? `${url}/api/record` : "";
+}
+
+export function getUmamiSessionCache(umami = globalThis.window?.umami) {
+	const session = umami?.getSession?.();
+	return session?.cache || "";
+}
+
+export function resolveUmamiSessionCache({
+	cache = "",
+	getUmami = () => globalThis.window?.umami,
+} = {}) {
+	return getUmamiSessionCache(getUmami()) || cache;
+}
+
+export function waitForUmamiSessionCache({
+	getUmami = () => globalThis.window?.umami,
+	pollIntervalMs = UMAMI_REPLAY_DEFAULTS.sessionPollIntervalMs,
+	maxAttempts = UMAMI_REPLAY_DEFAULTS.sessionPollAttempts,
+	signal,
+} = {}) {
+	return new Promise((resolve) => {
+		if (signal?.aborted) {
+			resolve("");
+			return;
+		}
+
+		let timer = null;
+		const onAbort = () => {
+			cleanup();
+			resolve("");
+		};
+		const cleanup = () => {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			signal?.removeEventListener("abort", onAbort);
+		};
+
+		const poll = (attempts = 0) => {
+			const cache = getUmamiSessionCache(getUmami());
+			if (cache) {
+				cleanup();
+				resolve(cache);
+				return;
+			}
+
+			if (attempts >= maxAttempts) {
+				cleanup();
+				resolve("");
+				return;
+			}
+
+			timer = setTimeout(() => poll(attempts + 1), pollIntervalMs);
+		};
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+		poll();
+	});
+}
+
+export function buildReplayBody({ websiteId, events, timestamp }) {
+	return JSON.stringify({
+		type: "record",
+		payload: {
+			website: websiteId,
+			events,
+			timestamp,
+		},
+	});
+}
+
+export async function postReplayBatch({
+	endpoint,
+	cache,
+	websiteId,
+	events,
+	timestamp = Math.floor(Date.now() / 1000),
+	useKeepalive = false,
+	getUmami = () => globalThis.window?.umami,
+	fetchImpl = globalThis.fetch?.bind(globalThis),
+} = {}) {
+	const sessionCache = resolveUmamiSessionCache({ cache, getUmami });
+
+	if (
+		!endpoint ||
+		!sessionCache ||
+		!websiteId ||
+		!events?.length ||
+		!fetchImpl
+	) {
+		return false;
+	}
+
+	const body = buildReplayBody({ websiteId, events, timestamp });
+	const keepalive = useKeepalive && body.length < 60000;
+
+	try {
+		const response = await fetchImpl(endpoint, {
+			keepalive,
+			method: "POST",
+			body,
+			headers: {
+				"Content-Type": "application/json",
+				"x-umami-cache": sessionCache,
+			},
+			credentials: "omit",
+		});
+
+		if (!response?.ok) return false;
+
+		// Umami answers 200 with { ok: false, reason } when replay is disabled
+		// server-side. Treat that as a failure so events are restored instead
+		// of silently dropped.
+		const responseBody =
+			typeof response.json === "function"
+				? await response.json().catch(() => null)
+				: null;
+		if (responseBody && responseBody.ok === false) {
+			log.warn(
+				`batch rejected by server: ${responseBody.reason ?? "unknown reason"}`,
+			);
+			return false;
+		}
+
+		return true;
+	} catch {
+		return false;
+	}
+}

package/templates/base-project/apps/web/src/lib/analytics/umami-web-vitals.js

@@ -0,0 +1,237 @@
+/**
+ * Anonymous Real User Monitoring (RUM) — Core Web Vitals Pipeline
+ *
+ * Observes browser performance metrics (LCP, FID, CLS, INP, TTFB) and
+ * dispatches them to the unified Umami instance as anonymous custom events
+ * (event_type = 2).  No user identifiers, session tokens, or PII are ever
+ * included in the payload.
+ *
+ * Privacy guarantees:
+ *  - Zero user data: no email, name, ID, token, or cookie values.
+ *  - Layout timings only: metric name, numeric value, rating string,
+ *    and a sanitised URL path (origin stripped, never full URL with query).
+ *  - No referrer, no user-agent, no IP collected by this script.
+ *  - Uses sendBeacon for reliable delivery without blocking the page.
+ *
+ * Integration:
+ *  Import and call `observeWebVitals()` once from a client component
+ *  (e.g. a "use client" wrapper in the root layout).
+ *
+ * Environment:
+ *  Controlled by NEXT_PUBLIC_UMAMI_URL and NEXT_PUBLIC_UMAMI_WEBSITE_ID.
+ *  When Umami analytics is not configured, the observer is a no-op.
+ */
+
+import { getUmamiConfig } from "./umami-config.js";
+
+// ── Initialization guard ──────────────────────────────────────
+
+/**
+ * Returns true when the browser supports PerformanceObserver.
+ * @returns {boolean}
+ */
+function isSupported() {
+	return (
+		typeof window !== "undefined" &&
+		"PerformanceObserver" in window &&
+		"performance" in window
+	);
+}
+
+/**
+ * Strips the origin and query string from a URL, returning only the
+ * pathname.  This ensures no PII (query params, hash fragments) or
+ * internal hostnames leak to the analytics pipeline.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function sanitiseUrl(url) {
+	try {
+		const parsed = new URL(url, "http://localhost");
+		return parsed.pathname;
+	} catch {
+		return "/";
+	}
+}
+
+/**
+ * Dispatches a single CWV observation to the Umami collect endpoint
+ * as a custom event (event_type = 2).  The payload is fully anonymous.
+ *
+ * @param {{ name: string, value: number, rating: string, navigationType?: string }} metric
+ */
+function dispatchMetric(metric) {
+	const config = getUmamiConfig();
+	if (!config.enabled) return;
+
+	const payload = {
+		type: "event",
+		payload: {
+			website: config.websiteId,
+			event_name: "cwv",
+			event_type: 2, // custom event
+			url: sanitiseUrl(window.location.href),
+			event_data: {
+				metric_name: metric.name,
+				metric_value: Math.round(metric.value * 1000) / 1000, // round to 3dp
+				metric_rating: metric.rating,
+				navigation_type: metric.navigationType || "navigate",
+			},
+		},
+	};
+
+	const body = JSON.stringify(payload);
+
+	// Use sendBeacon for reliability during page lifecycle transitions.
+	if (navigator.sendBeacon) {
+		const blob = new Blob([body], { type: "application/json" });
+		navigator.sendBeacon(`${config.url}/api/collect`, blob);
+	} else {
+		// Fallback to fetch with keepalive.
+		fetch(`${config.url}/api/collect`, {
+			method: "POST",
+			body,
+			keepalive: true,
+			credentials: "omit",
+			headers: { "Content-Type": "application/json" },
+		}).catch(() => {
+			// Best-effort — swallow network errors silently.
+		});
+	}
+}
+
+/**
+ * Starts observing Core Web Vitals and dispatching them to Umami.
+ * Safe to call multiple times — internal guards prevent double registration.
+ *
+ * Call this once from a "use client" component mounted in the root layout.
+ *
+ * @returns {() => void} Cleanup function that disconnects all observers.
+ */
+export function observeWebVitals() {
+	if (!isSupported()) return () => {};
+
+	/** @type {PerformanceObserver[]} */
+	const observers = [];
+
+	// ── Largest Contentful Paint ──────────────────────────────────
+	try {
+		const lcpObserver = new PerformanceObserver((list) => {
+			const entries = list.getEntries();
+			if (entries.length === 0) return;
+
+			const entry = entries[entries.length - 1];
+			const value = entry.startTime;
+			dispatchMetric({
+				name: "LCP",
+				value,
+				rating:
+					value < 2500 ? "good" : value < 4000 ? "needs-improvement" : "poor",
+				navigationType: /** @type {any} */ (entry).navigationType,
+			});
+		});
+		lcpObserver.observe({ type: "largest-contentful-paint", buffered: true });
+		observers.push(lcpObserver);
+	} catch {
+		// LCP not supported.
+	}
+
+	// ── First Input Delay ─────────────────────────────────────────
+	try {
+		const fidObserver = new PerformanceObserver((list) => {
+			const entry = list.getEntries()[0];
+			if (!entry) return;
+
+			const value = entry.processingStart - entry.startTime;
+			dispatchMetric({
+				name: "FID",
+				value,
+				rating:
+					value < 100 ? "good" : value < 300 ? "needs-improvement" : "poor",
+			});
+		});
+		fidObserver.observe({ type: "first-input", buffered: true });
+		observers.push(fidObserver);
+	} catch {
+		// FID not supported.
+	}
+
+	// ── Cumulative Layout Shift (reported on page hide) ───────────
+	let clsValue = 0;
+	try {
+		const clsObserver = new PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				if (!entry.hadRecentInput) clsValue += entry.value;
+			}
+		});
+		clsObserver.observe({ type: "layout-shift", buffered: true });
+		observers.push(clsObserver);
+
+		const reportCls = () => {
+			dispatchMetric({
+				name: "CLS",
+				value: clsValue,
+				rating:
+					clsValue < 0.1
+						? "good"
+						: clsValue < 0.25
+							? "needs-improvement"
+							: "poor",
+			});
+		};
+
+		window.addEventListener("visibilitychange", reportCls, { once: true });
+		window.addEventListener("pagehide", reportCls, { once: true });
+	} catch {
+		// CLS not supported.
+	}
+
+	// ── Interaction to Next Paint ─────────────────────────────────
+	try {
+		if (PerformanceObserver.supportedEntryTypes?.includes("interaction")) {
+			const inpObserver = new PerformanceObserver((list) => {
+				for (const entry of list.getEntries()) {
+					const value = entry.duration;
+					dispatchMetric({
+						name: "INP",
+						value,
+						rating:
+							value < 200 ? "good" : value < 500 ? "needs-improvement" : "poor",
+					});
+				}
+			});
+			inpObserver.observe({ type: "interaction", buffered: true });
+			observers.push(inpObserver);
+		}
+	} catch {
+		// INP not supported.
+	}
+
+	// ── Time to First Byte (from Navigation Timing API) ───────────
+	try {
+		if (performance.getEntriesByType?.("navigation").length > 0) {
+			const navEntry = performance.getEntriesByType("navigation")[0];
+			const value = navEntry.responseStart - navEntry.requestStart;
+			dispatchMetric({
+				name: "TTFB",
+				value,
+				rating:
+					value < 800 ? "good" : value < 1800 ? "needs-improvement" : "poor",
+			});
+		}
+	} catch {
+		// TTFB not available.
+	}
+
+	// Return a cleanup function that disconnects all observers.
+	return () => {
+		for (const observer of observers) {
+			try {
+				observer.disconnect();
+			} catch {
+				// Ignore disconnect errors.
+			}
+		}
+	};
+}

package/templates/base-project/apps/web/src/lib/analytics/umami.js

@@ -0,0 +1,57 @@
+import { getUmamiConfig } from "./umami-config.js";
+
+/**
+ * Read the Umami user role cookie set by the admin layout.
+ * Returns the role string ("admin", "client_admin", etc.) or null.
+ * The inline before-send script in layout.js duplicates this regex
+ * because it runs before any module code.
+ */
+export function getUmamiUserRole() {
+	if (typeof document === "undefined") return null;
+	return (document.cookie.match(/umami_user_role=([^;]+)/) || [])[1] || null;
+}
+
+/** True when any staff role cookie is present (any value = staff). */
+export function isUmamiStaff() {
+	return Boolean(getUmamiUserRole());
+}
+
+function getUmamiClient() {
+	if (typeof window === "undefined") return null;
+	if (!getUmamiConfig().enabled) return null;
+	return window.umami ?? null;
+}
+
+export function isUmamiEnabled(env = process.env) {
+	return getUmamiConfig(env).enabled;
+}
+
+export function track(name, data) {
+	const umami = getUmamiClient();
+	if (!umami?.track) return false;
+
+	if (typeof name === "string") {
+		umami.track(name, data);
+		return true;
+	}
+
+	if (name && typeof name === "object") {
+		umami.track(name);
+		return true;
+	}
+
+	return false;
+}
+
+export function identify(data) {
+	const umami = getUmamiClient();
+	if (!umami?.identify) return false;
+
+	umami.identify(data);
+	return true;
+}
+
+export function trackRevenue(amount, currency = "USD", data = {}) {
+	if (typeof amount !== "number" || Number.isNaN(amount)) return false;
+	return track("revenue", { revenue: amount, currency, ...data });
+}

package/templates/base-project/apps/web/src/lib/auth-middleware.js

@@ -0,0 +1,82 @@
+import { ForbiddenError, UnauthorizedError } from "@techstream/quark-core";
+import { auth } from "./auth";
+
+const UNAUTHENTICATED = "You must be logged in to access this resource";
+
+/**
+ * Whether `value` is a session that identifies a real, signed-in user.
+ *
+ * Truthiness is not enough. `@auth/core` answers a misconfigured provider with
+ * a 500, and a client that returns the error body as though it were a session
+ * would sail through `if (!session)`. That is not hypothetical: it is exactly
+ * what next-auth 5.0.0-beta.31 did, which is why beta.32 added
+ * `parseSessionResponse`. An error object is truthy, so the old guard treated a
+ * server-side misconfiguration as an authenticated request and handed callers a
+ * session with `user === undefined`.
+ *
+ * beta.32 fixes the source, but the defence belongs here too: a guard that
+ * depends on a pre-release library behaving correctly is one beta bump away from
+ * failing open again. Requiring a user with an `id` means an error body, a
+ * partially-populated session, or a `{}` all fail closed regardless of what the
+ * client returns.
+ *
+ * @param {unknown} value
+ * @returns {value is import("next-auth").Session}
+ */
+function isAuthenticatedSession(value) {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+
+	const sessionUser = /** @type {{ user?: unknown }} */ (value).user;
+	if (typeof sessionUser !== "object" || sessionUser === null) {
+		return false;
+	}
+
+	const id = /** @type {{ id?: unknown, sub?: unknown }} */ (sessionUser).id;
+	const subject = /** @type {{ id?: unknown, sub?: unknown }} */ (sessionUser)
+		.sub;
+
+	return (
+		(typeof id === "string" && id.length > 0) ||
+		(typeof subject === "string" && subject.length > 0)
+	);
+}
+
+/**
+ * Assert that a session identifies a real, signed-in user, or throw.
+ *
+ * @param {unknown} session
+ * @returns {Promise<import("next-auth").Session>}
+ */
+export async function requireAuth(session) {
+	if (session === undefined) {
+		session = await auth();
+	}
+
+	if (!isAuthenticatedSession(session)) {
+		throw new UnauthorizedError(UNAUTHENTICATED);
+	}
+
+	return session;
+}
+
+/**
+ * Require the current user to have one of the specified roles.
+ *
+ * @param {string | string[]} role - Required role(s) (e.g. "admin" or ["admin", "editor"])
+ * @param {unknown} [session] - Injectable for tests; read from `auth()` when omitted.
+ * @returns {Promise<import("next-auth").Session>}
+ */
+export async function requireRole(role, session) {
+	const authenticated = await requireAuth(session);
+
+	const allowed = Array.isArray(role) ? role : [role];
+	if (!allowed.includes(authenticated.user?.role)) {
+		throw new ForbiddenError(
+			"You do not have permission to access this resource",
+		);
+	}
+
+	return authenticated;
+}