Analytics: queued events, once-per-order revenue, heatmap on product pages (#17)

Analytics: queued events, once-per-order revenue, heatmap on product pages (#17)
Co-authored-by: Michael Czechowski <mail@librete.ch>

utils/trackEvent.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+
+const sent: Array<[string, unknown]> = [];
+beforeEach(() => {
+	sent.length = 0;
+	(globalThis as any).window = {};
+});
+afterEach(async () => {
+	const { __resetTrackQueue } = await import("./trackEvent");
+	__resetTrackQueue();
+	delete (globalThis as any).window;
+});
+const umami = { track: (e: string, d: unknown) => sent.push([e, d]) };
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+test("sends immediately when umami is loaded", async () => {
+	const { trackEvent } = await import("./trackEvent");
+	(globalThis as any).window.umami = umami;
+	trackEvent("a", { x: 1 });
+	expect(sent).toEqual([["a", { x: 1 }]]);
+});
+
+test("queues until umami appears, then flushes in order and calls onSent", async () => {
+	const { trackEvent } = await import("./trackEvent");
+	let confirmed = false;
+	trackEvent("first");
+	trackEvent("purchase-completed", { revenue: 12.5, currency: "EUR" }, () => (confirmed = true));
+	expect(sent).toEqual([]);
+	await wait(300);
+	(globalThis as any).window.umami = umami;
+	await wait(400);
+	expect(sent.map((s) => s[0])).toEqual(["first", "purchase-completed"]);
+	expect(confirmed).toBe(true);
+});
+
+test("never throws and drops events when umami never loads", async () => {
+	const { trackEvent } = await import("./trackEvent");
+	let confirmed = false;
+	trackEvent("lost", undefined, () => (confirmed = true));
+	await wait(10_500);
+	(globalThis as any).window.umami = umami;
+	await wait(400);
+	expect(sent).toEqual([]);
+	expect(confirmed).toBe(false);
+}, 15_000);
+
+test("is a no-op on the server", async () => {
+	delete (globalThis as any).window;
+	const { trackEvent } = await import("./trackEvent");
+	expect(() => trackEvent("ssr")).not.toThrow();
+});

utils/trackEvent.ts

@@ -6,8 +6,51 @@ declare global {
 	}
 }
 
-export const trackEvent = (event: string, data?: Record<string, unknown>) => {
-	if (import.meta.client && window.umami) {
-		window.umami.track(event, data);
+type Pending = { event: string; data?: Record<string, unknown>; onSent?: () => void };
+
+// Events fired during page setup (onMounted) often run before the deferred
+// Umami script has loaded; they used to be dropped silently. Queue them and
+// flush once the tracker exists. If it never appears (blocked, offline),
+// they are discarded after ~10 s without throwing.
+const queue: Pending[] = [];
+let timer: ReturnType<typeof setInterval> | null = null;
+let attempts = 0;
+const MAX_ATTEMPTS = 40;
+const INTERVAL_MS = 250;
+
+function send(item: Pending) {
+	try {
+		window.umami!.track(item.event, item.data);
+		item.onSent?.();
+	} catch {
+		// tracking must never break the shop
 	}
+}
+
+function flush() {
+	if (window.umami) {
+		while (queue.length) send(queue.shift()!);
+	}
+	if (window.umami || ++attempts >= MAX_ATTEMPTS) {
+		queue.length = 0;
+		if (timer) clearInterval(timer);
+		timer = null;
+		attempts = 0;
+	}
+}
+
+export const trackEvent = (event: string, data?: Record<string, unknown>, onSent?: () => void) => {
+	if (typeof window === "undefined") return;
+	const item = { event, data, onSent };
+	if (window.umami) return send(item);
+	queue.push(item);
+	if (!timer) timer = setInterval(flush, INTERVAL_MS);
+};
+
+// Test hook: reset module state between cases.
+export const __resetTrackQueue = () => {
+	queue.length = 0;
+	if (timer) clearInterval(timer);
+	timer = null;
+	attempts = 0;
 };