fix: context tests, handle UTC, vitals

Author: izadoesdev

packages/tracker/src/core/tracker.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from "./client";
-import type { BaseEvent, EventContext, TrackerOptions } from "./types";
+import type { BaseEvent, EventContext, TrackerOptions, WebVitalEvent } from "./types";
 import { generateUUIDv4, logger } from "./utils";
 
 const HEADLESS_CHROME_REGEX = /\bHeadlessChrome\b/i;
@@ -33,15 +33,20 @@ export class BaseTracker {
 	batchTimer: Timer | null = null;
 	private isFlushing = false;
 
+	// Vitals Queue
+	vitalsQueue: WebVitalEvent[] = [];
+	vitalsTimer: Timer | null = null;
+	private isFlushingVitals = false;
+
 	constructor(options: TrackerOptions) {
 		this.options = {
 			disabled: false,
 			trackPerformance: true,
 			samplingRate: 1.0,
-			enableRetries: true,
+			enableRetries: false,
 			maxRetries: 3,
 			initialRetryDelay: 500,
-			enableBatching: false,
+			enableBatching: true,
 			batchSize: 10,
 			batchTimeout: 2000,
 			sdk: "web",
@@ -391,6 +396,58 @@ export class BaseTracker {
 		}
 	}
 
+	sendVital(event: WebVitalEvent): Promise<void> {
+		if (this.shouldSkipTracking()) {
+			return Promise.resolve();
+		}
+
+		logger.log("Queueing vital", event);
+		return this.addToVitalsQueue(event);
+	}
+
+	addToVitalsQueue(event: WebVitalEvent): Promise<void> {
+		this.vitalsQueue.push(event);
+		if (this.vitalsTimer === null) {
+			this.vitalsTimer = setTimeout(
+				() => this.flushVitals(),
+				this.options.batchTimeout
+			);
+		}
+		if (this.vitalsQueue.length >= 6) {
+			this.flushVitals();
+		}
+		return Promise.resolve();
+	}
+
+	async flushVitals() {
+		if (this.vitalsTimer) {
+			clearTimeout(this.vitalsTimer);
+			this.vitalsTimer = null;
+		}
+		if (this.vitalsQueue.length === 0 || this.isFlushingVitals) {
+			return;
+		}
+
+		this.isFlushingVitals = true;
+		const vitals = [...this.vitalsQueue];
+		this.vitalsQueue = [];
+
+		logger.log("Flushing vitals", vitals.length);
+
+		try {
+			const result = await this.api.fetch("/vitals", vitals, {
+				keepalive: true,
+			});
+			logger.log("Vitals sent", result);
+			return result;
+		} catch (error) {
+			logger.error("Vitals batch failed", error);
+			return null;
+		} finally {
+			this.isFlushingVitals = false;
+		}
+	}
+
 	sendBeacon(data: unknown, endpoint = "/vitals"): boolean {
 		if (this.isServer()) {
 			return false;

packages/tracker/src/core/types.ts

@@ -66,6 +66,14 @@ export type TrackEvent = BaseEvent & {
 	name: string;
 };
 
+export type WebVitalMetricName = "FCP" | "LCP" | "CLS" | "INP" | "TTFB" | "FPS";
+
+export type WebVitalEvent = BaseEvent & {
+	name: "web_vital";
+	metricName: WebVitalMetricName;
+	metricValue: number;
+};
+
 export type DatabuddyGlobal = {
 	track: (name: string, props?: Record<string, unknown>) => void;
 	screenView: (props?: Record<string, unknown>) => void;

packages/tracker/src/plugins/vitals.ts

@@ -1,17 +1,8 @@
 import { type Metric, onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
 import type { BaseTracker } from "../core/tracker";
+import type { WebVitalMetricName } from "../core/types";
 import { logger } from "../core/utils";
 
-type WebVitalMetricName = "FCP" | "LCP" | "CLS" | "INP" | "TTFB" | "FPS";
-
-type WebVitalSpan = {
-	sessionId: string;
-	timestamp: number;
-	path: string;
-	metricName: WebVitalMetricName;
-	metricValue: number;
-};
-
 type FPSMetric = {
 	name: "FPS";
 	value: number;
@@ -49,30 +40,24 @@ export function initWebVitalsTracking(tracker: BaseTracker) {
 
 	const sentMetrics = new Set<WebVitalMetricName>();
 
-	const sendVitalSpan = (metricName: WebVitalMetricName, metricValue: number) => {
-		if (sentMetrics.has(metricName)) {
+	const handleMetric = (metric: Metric | FPSMetric) => {
+		const name = metric.name as WebVitalMetricName;
+		if (sentMetrics.has(name)) {
 			return;
 		}
-		sentMetrics.add(metricName);
-
-		const span: WebVitalSpan = {
-			sessionId: tracker.sessionId ?? "",
-			timestamp: Date.now(),
-			path: window.location.pathname,
-			metricName,
-			metricValue,
-		};
+		sentMetrics.add(name);
 
-		logger.log(`Sending web vital span: ${metricName}`, span);
-		tracker.sendBeacon(span);
-	};
-
-	const handleMetric = (metric: Metric | FPSMetric) => {
-		const name = metric.name as WebVitalMetricName;
 		const value = name === "CLS" ? metric.value : Math.round(metric.value);
-
 		logger.log(`Web Vital captured: ${name}`, value);
-		sendVitalSpan(name, value);
+
+		tracker.sendVital({
+			name: "web_vital",
+			eventId: crypto.randomUUID(),
+			timestamp: Date.now(),
+			path: window.location.pathname,
+			metricName: name,
+			metricValue: value,
+		});
 	};
 
 	onFCP(handleMetric);

packages/tracker/tests/api-methods.spec.ts

@@ -372,7 +372,7 @@ test.describe("API Methods", () => {
                     ignoreBotDetection: true,
                     enableBatching: true,
                     batchSize: 100, // Large size so it won't auto-flush
-                    batchTimeout: 60000, // Long timeout
+                    batchTimeout: 60_000, // Long timeout
                 };
             });
             await page.addScriptTag({ url: "/dist/databuddy.js" });
@@ -418,7 +418,7 @@ test.describe("API Methods", () => {
                     ignoreBotDetection: true,
                     enableBatching: true,
                     batchSize: 100,
-                    batchTimeout: 60000,
+                    batchTimeout: 60_000,
                 };
             });
             await page.addScriptTag({ url: "/dist/databuddy.js" });
@@ -505,4 +505,3 @@ test.describe("API Methods", () => {
         });
     });
 });
-

packages/tracker/tests/context.spec.ts

@@ -109,8 +109,8 @@ test.describe("Event Context", () => {
             const payload = request.postDataJSON();
 
             expect(payload.timezone).toBeTruthy();
-            // Timezone should be a valid IANA timezone string
-            expect(payload.timezone).toMatch(/^[A-Za-z_]+\/[A-Za-z_]+$/);
+            // Timezone should be a valid IANA timezone string (UTC, GMT, or Area/Location format)
+            expect(payload.timezone).toMatch(/^([A-Za-z_]+\/[A-Za-z_]+|UTC|GMT)$/);
         });
     });
 

packages/tracker/tests/vitals.spec.ts

@@ -1,7 +1,8 @@
 import { expect, test } from "@playwright/test";
 
-type VitalSpan = {
-	sessionId: string;
+type WebVitalEvent = {
+	name: "web_vital";
+	eventId: string;
 	timestamp: number;
 	path: string;
 	metricName: string;
@@ -25,13 +26,13 @@ test.describe("Web Vitals Tracking", () => {
 		});
 	});
 
-	test("sends each vital as individual span", async ({ page }) => {
-		const vitalsReceived: VitalSpan[] = [];
+	test("batches vitals and sends to /vitals endpoint", async ({ page }) => {
+		const vitalBatches: WebVitalEvent[][] = [];
 
 		page.on("request", (req) => {
 			if (req.url().includes("/basket.databuddy.cc/vitals") && req.method() === "POST") {
-				const payload = req.postDataJSON() as VitalSpan;
-				vitalsReceived.push(payload);
+				const payload = req.postDataJSON() as WebVitalEvent[];
+				vitalBatches.push(payload);
 			}
 		});
 
@@ -46,38 +47,34 @@ test.describe("Web Vitals Tracking", () => {
 		});
 		await page.addScriptTag({ url: "/dist/vitals.js" });
 
-		// Wait for FPS measurement (2 seconds) plus buffer
-		await page.waitForTimeout(3000);
+		// Wait for FPS measurement (2 seconds) + batch timeout (2 seconds) + buffer
+		await page.waitForTimeout(5000);
 
-		// Should have received at least one vital span
-		if (vitalsReceived.length > 0) {
-			const span = vitalsReceived.at(0);
-			expect(span?.metricName).toBeDefined();
-			expect(span?.metricValue).toBeDefined();
-			expect(span?.sessionId).toBeDefined();
-			expect(span?.path).toBeDefined();
-			expect(span?.timestamp).toBeDefined();
+		if (vitalBatches.length > 0) {
+			const allVitals = vitalBatches.flat();
+			expect(allVitals.length).toBeGreaterThan(0);
 
-			// Check metric names are valid
 			const validMetrics = ["FCP", "LCP", "CLS", "INP", "TTFB", "FPS"];
-			for (const vital of vitalsReceived) {
+			for (const vital of allVitals) {
+				expect(vital.name).toBe("web_vital");
+				expect(vital.eventId).toBeDefined();
 				expect(validMetrics).toContain(vital.metricName);
 				expect(typeof vital.metricValue).toBe("number");
 			}
 
-			console.table(vitalsReceived.map((v) => ({ metric: v.metricName, value: v.metricValue })));
+			console.table(allVitals.map((v) => ({ metric: v.metricName, value: v.metricValue })));
 		} else {
 			console.log("No vitals captured - this can happen in test environments");
 		}
 	});
 
 	test("captures FPS metric", async ({ page }) => {
-		const vitalsReceived: VitalSpan[] = [];
+		const vitalBatches: WebVitalEvent[][] = [];
 
 		page.on("request", (req) => {
 			if (req.url().includes("/basket.databuddy.cc/vitals") && req.method() === "POST") {
-				const payload = req.postDataJSON() as VitalSpan;
-				vitalsReceived.push(payload);
+				const payload = req.postDataJSON() as WebVitalEvent[];
+				vitalBatches.push(payload);
 			}
 		});
 
@@ -92,26 +89,27 @@ test.describe("Web Vitals Tracking", () => {
 		});
 		await page.addScriptTag({ url: "/dist/vitals.js" });
 
-		// FPS measurement takes 2 seconds
-		await page.waitForTimeout(3000);
+		// FPS measurement takes 2 seconds + batch timeout
+		await page.waitForTimeout(5000);
 
-		const fpsVital = vitalsReceived.find((v) => v.metricName === "FPS");
+		const allVitals = vitalBatches.flat();
+		const fpsVital = allVitals.find((v) => v.metricName === "FPS");
 		if (fpsVital) {
 			expect(fpsVital.metricValue).toBeGreaterThan(0);
-			expect(fpsVital.metricValue).toBeLessThanOrEqual(120);
+			expect(fpsVital.metricValue).toBeLessThanOrEqual(240); // High refresh rate displays
 			console.log("FPS captured:", fpsVital.metricValue);
 		} else {
 			console.log("FPS not captured - this can happen in headless browsers");
 		}
 	});
 
 	test("does not send duplicate metrics", async ({ page }) => {
-		const vitalsReceived: VitalSpan[] = [];
+		const vitalBatches: WebVitalEvent[][] = [];
 
 		page.on("request", (req) => {
 			if (req.url().includes("/basket.databuddy.cc/vitals") && req.method() === "POST") {
-				const payload = req.postDataJSON() as VitalSpan;
-				vitalsReceived.push(payload);
+				const payload = req.postDataJSON() as WebVitalEvent[];
+				vitalBatches.push(payload);
 			}
 		});
 
@@ -126,10 +124,10 @@ test.describe("Web Vitals Tracking", () => {
 		});
 		await page.addScriptTag({ url: "/dist/vitals.js" });
 
-		await page.waitForTimeout(3000);
+		await page.waitForTimeout(5000);
 
-		// Check no duplicate metric names
-		const metricNames = vitalsReceived.map((v) => v.metricName);
+		const allVitals = vitalBatches.flat();
+		const metricNames = allVitals.map((v) => v.metricName);
 		const uniqueNames = [...new Set(metricNames)];
 		expect(metricNames.length).toBe(uniqueNames.length);
 	});