feat: better analytic safety

Author: Rieranthony

apps/web/src/components/inbox-analytics/inbox-analytics-display.test.tsx

@@ -9,14 +9,14 @@ const analyticsData = {
 		medianResolutionTimeSeconds: 3600,
 		aiHandledRate: 80,
 		satisfactionIndex: 73,
-		uniqueVisitors: 42,
+		uniqueVisitors: 987,
 	},
 	previous: {
 		medianResponseTimeSeconds: 250,
 		medianResolutionTimeSeconds: 5400,
 		aiHandledRate: 60,
 		satisfactionIndex: 68,
-		uniqueVisitors: 21,
+		uniqueVisitors: 321,
 	},
 } as InboxAnalyticsResponse;
 
@@ -59,6 +59,7 @@ describe("InboxAnalyticsDisplay", () => {
 		expect(html).toContain('data-slot="inbox-analytics-live-dot-pulse"');
 		expect(html).toContain("bg-emerald-600");
 		expect(html).toContain("1,234");
+		expect(html).toContain("987");
 		expect(html).toContain("Median response time");
 		expect(
 			html.indexOf('data-slot="inbox-analytics-live-presence"')
@@ -79,6 +80,7 @@ describe("InboxAnalyticsDisplay", () => {
 		expect(html).toContain("1h");
 		expect(html).toContain("80%");
 		expect(html).toContain('aria-label="Analytics date range"');
+		expect(html).toContain(">30d<");
 		expect(html).toContain("shrink-0");
 	});
 

apps/web/src/components/inbox-analytics/inbox-analytics-display.tsx

@@ -58,7 +58,7 @@ const numberFormatter = new Intl.NumberFormat("en-US", {
 const rangeOptions = [
 	{ value: "7", label: "7d" },
 	{ value: "14", label: "14d" },
-	{ value: "30", label: "Month" },
+	{ value: "30", label: "30d" },
 ] as const satisfies readonly SegmentedControlOption<string>[];
 
 const formatDuration = (value: number | null): string => {
@@ -149,7 +149,8 @@ const metricConfigs: MetricConfig[] = [
 	{
 		key: "uniqueVisitors",
 		label: "Unique visitors",
-		description: "Number of distinct widget visitors active in this period.",
+		description:
+			"Number of distinct website visitors who loaded the widget during this period.",
 		higherIsBetter: true,
 		formatValue: formatCount,
 	},

apps/web/src/components/inbox-analytics/inbox-analytics-range-control.test.tsx

@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+
+let capturedSegmentedControlProps: {
+	"aria-label": string;
+	onValueChange: (value: string) => void;
+	options: Array<{ value: string; label: string }>;
+	value: string;
+} | null = null;
+
+mock.module("@/components/ui/segmented-control", () => ({
+	SegmentedControl: (props: {
+		"aria-label": string;
+		onValueChange: (value: string) => void;
+		options: Array<{ value: string; label: string }>;
+		value: string;
+	}) => {
+		capturedSegmentedControlProps = props;
+		return <div data-slot="mock-segmented-control" />;
+	},
+}));
+
+const modulePromise = import("./inbox-analytics-display");
+
+describe("InboxAnalyticsRangeControl", () => {
+	beforeEach(() => {
+		capturedSegmentedControlProps = null;
+	});
+
+	it("maps segmented-control selections to supported analytics ranges", async () => {
+		const onRangeChange = mock(((_rangeDays: number) => {}) as (
+			value: number
+		) => void);
+		const { InboxAnalyticsRangeControl } = await modulePromise;
+
+		renderToStaticMarkup(
+			<InboxAnalyticsRangeControl
+				onRangeChange={onRangeChange}
+				rangeDays={14}
+			/>
+		);
+
+		expect(capturedSegmentedControlProps).not.toBeNull();
+		expect(capturedSegmentedControlProps?.["aria-label"]).toBe(
+			"Analytics date range"
+		);
+		expect(capturedSegmentedControlProps?.value).toBe("14");
+		expect(capturedSegmentedControlProps?.options).toEqual([
+			{ value: "7", label: "7d" },
+			{ value: "14", label: "14d" },
+			{ value: "30", label: "30d" },
+		]);
+
+		capturedSegmentedControlProps?.onValueChange("30");
+		capturedSegmentedControlProps?.onValueChange("999");
+
+		expect(onRangeChange).toHaveBeenCalledTimes(1);
+		expect(onRangeChange).toHaveBeenCalledWith(30);
+	});
+});

apps/web/src/components/inbox-analytics/inbox-analytics.test.tsx

@@ -17,8 +17,25 @@ let onlineNowQueryState = {
 	isLoading: false,
 };
 
+const useInboxAnalyticsMock = mock(
+	((_: { websiteSlug: string; rangeDays: number; enabled?: boolean }) =>
+		inboxAnalyticsQueryState) as (args: {
+		websiteSlug: string;
+		rangeDays: number;
+		enabled?: boolean;
+	}) => typeof inboxAnalyticsQueryState
+);
+const useOnlineNowMock = mock(
+	((_: { websiteSlug: string; minutes?: number; enabled?: boolean }) =>
+		onlineNowQueryState) as (args: {
+		websiteSlug: string;
+		minutes?: number;
+		enabled?: boolean;
+	}) => typeof onlineNowQueryState
+);
+
 mock.module("@/data/use-inbox-analytics", () => ({
-	useInboxAnalytics: () => inboxAnalyticsQueryState,
+	useInboxAnalytics: useInboxAnalyticsMock,
 }));
 
 mock.module("@/data/use-online-now", () => ({
@@ -27,14 +44,16 @@ mock.module("@/data/use-online-now", () => ({
 		["tinybird", "online-now", websiteSlug] as const,
 	isVisitorOnlineEntity: (entity: { entity_type: string }) =>
 		entity.entity_type === "visitor",
-	useOnlineNow: () => onlineNowQueryState,
+	useOnlineNow: useOnlineNowMock,
 }));
 
 const modulePromise = import("./inbox-analytics");
 
 describe("InboxAnalytics", () => {
 	beforeEach(() => {
 		capturedControllerState = null;
+		useInboxAnalyticsMock.mockClear();
+		useOnlineNowMock.mockClear();
 		inboxAnalyticsQueryState = {
 			data: null,
 			isError: false,
@@ -78,4 +97,88 @@ describe("InboxAnalytics", () => {
 			isLoading: false,
 		});
 	});
+
+	it("keeps unique visitors separate from the live presence count", async () => {
+		inboxAnalyticsQueryState = {
+			data: {
+				range: {
+					rangeDays: 7,
+					currentStart: "2026-03-21T00:00:00.000Z",
+					currentEnd: "2026-03-28T00:00:00.000Z",
+					previousStart: "2026-03-14T00:00:00.000Z",
+					previousEnd: "2026-03-21T00:00:00.000Z",
+				},
+				current: {
+					medianResponseTimeSeconds: 120,
+					medianResolutionTimeSeconds: 1800,
+					aiHandledRate: 60,
+					satisfactionIndex: 75,
+					uniqueVisitors: 987,
+				},
+				previous: {
+					medianResponseTimeSeconds: 150,
+					medianResolutionTimeSeconds: 2100,
+					aiHandledRate: 55,
+					satisfactionIndex: 70,
+					uniqueVisitors: 654,
+				},
+			},
+			isError: false,
+			isFetching: false,
+			isLoading: false,
+		};
+		onlineNowQueryState = {
+			data: [
+				{ entity_id: "entity_1", entity_type: "visitor" },
+				{ entity_id: "entity_2", entity_type: "visitor" },
+				{ entity_id: "entity_3", entity_type: "user" },
+			],
+			isFetching: false,
+			isLoading: false,
+		};
+
+		const { useInboxAnalyticsController } = await modulePromise;
+
+		function ControllerProbe() {
+			capturedControllerState = useInboxAnalyticsController({
+				websiteSlug: "acme",
+			}) as Record<string, unknown>;
+			return null;
+		}
+
+		renderToStaticMarkup(<ControllerProbe />);
+
+		const inboxAnalyticsArgs = useInboxAnalyticsMock.mock.calls[0]?.[0] as
+			| {
+					websiteSlug: string;
+					rangeDays: number;
+					enabled: boolean;
+			  }
+			| undefined;
+		const onlineNowArgs = useOnlineNowMock.mock.calls[0]?.[0] as
+			| {
+					websiteSlug: string;
+					enabled: boolean;
+			  }
+			| undefined;
+
+		expect(inboxAnalyticsArgs).toEqual({
+			websiteSlug: "acme",
+			rangeDays: 7,
+			enabled: true,
+		});
+		expect(onlineNowArgs).toEqual({
+			websiteSlug: "acme",
+			enabled: true,
+		});
+		expect(
+			(capturedControllerState?.data as InboxAnalyticsResponse | null)?.current
+				.uniqueVisitors
+		).toBe(987);
+		expect(capturedControllerState?.livePresence).toEqual({
+			count: 2,
+			isFetching: false,
+			isLoading: false,
+		});
+	});
 });