@btst/stack 5.1.0 → 5.2.0

package/src/plugins/analytics/__tests__/query-partition.test.tsx

@@ -0,0 +1,168 @@
+// @vitest-environment jsdom
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+	type MockInstance,
+} from "vitest";
+import { StackProvider } from "@btst/stack/context";
+import { createClientStack } from "../../../client";
+import { createIdentityTestAuth } from "../../../__tests__/auth-test-utils";
+import { analyticsClientPlugin } from "../client/plugin";
+import {
+	useDashboardStats,
+	useRealtimeVisitors,
+	useTopEvents,
+	useTopPages,
+	useTopReferrers,
+} from "../client/hooks";
+
+(
+	globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+function Probe() {
+	const stats = useDashboardStats();
+	const pages = useTopPages();
+	const referrers = useTopReferrers();
+	const events = useTopEvents();
+	const realtime = useRealtimeVisitors();
+	return (
+		<output>
+			{[
+				stats.data?.uniqueVisitors,
+				pages.data?.[0]?.views,
+				referrers.data?.[0]?.views,
+				events.data?.[0]?.count,
+				realtime.data?.visitors,
+			].join("|")}
+		</output>
+	);
+}
+
+function responseFor(input: string | URL | Request, value: number) {
+	const path = new URL(input instanceof Request ? input.url : String(input))
+		.pathname;
+	const data = path.endsWith("/dashboard")
+		? { uniqueVisitors: value }
+		: path.endsWith("/realtime")
+			? { visitors: value }
+			: [{ views: value, count: value }];
+	return new Response(JSON.stringify(data), {
+		headers: { "content-type": "application/json" },
+	});
+}
+
+async function waitFor(check: () => boolean) {
+	const deadline = Date.now() + 3000;
+	while (!check()) {
+		if (Date.now() > deadline)
+			throw new Error("Analytics query did not settle");
+		await act(async () => new Promise((resolve) => setTimeout(resolve, 10)));
+	}
+}
+
+describe("analytics public transport partition", () => {
+	let container: HTMLDivElement;
+	let root: Root;
+	let queryClient: QueryClient;
+	let fetchMock: MockInstance<typeof fetch>;
+	const identity = { id: "same-admin" };
+	const auth = createIdentityTestAuth(() => identity);
+
+	beforeEach(() => {
+		container = document.createElement("div");
+		document.body.append(container);
+		root = createRoot(container);
+		queryClient = new QueryClient();
+		fetchMock = vi.spyOn(globalThis, "fetch");
+	});
+	afterEach(async () => {
+		await act(async () => root.unmount());
+		queryClient.clear();
+		container.remove();
+		vi.restoreAllMocks();
+	});
+
+	async function render(
+		tenant: string,
+		credentials?: RequestCredentials,
+		headerName = "x-tenant",
+	) {
+		const stack = createClientStack({
+			api: { baseURL: "https://site.test", basePath: "/api/data" },
+			site: { baseURL: "https://site.test", basePath: "/pages" },
+			queryClient,
+			plugins: { analytics: analyticsClientPlugin({ tracking: false }) },
+			endpoints: {
+				analytics: {
+					api: {
+						basePath: "/api/data",
+						browserHeaders: { [headerName]: tenant },
+						credentials,
+					},
+				},
+			},
+		});
+		await act(async () =>
+			root.render(
+				<StackProvider stack={stack} auth={auth} initialIdentity={identity}>
+					<QueryClientProvider client={queryClient}>
+						<Probe />
+					</QueryClientProvider>
+				</StackProvider>,
+			),
+		);
+	}
+
+	it("fetches separate tenant data with one identity and QueryClient, normalizing header names", async () => {
+		fetchMock.mockImplementation(async (input, init) =>
+			responseFor(
+				input,
+				new Headers(init?.headers).get("x-tenant") === "A" ? 1 : 2,
+			),
+		);
+		await render("A");
+		await waitFor(() => container.textContent === "1|1|1|1|1");
+		await render("B");
+		expect(container.textContent).not.toContain("1");
+		await waitFor(() => container.textContent === "2|2|2|2|2");
+		expect(fetchMock).toHaveBeenCalledTimes(10);
+		await render("A", undefined, "X-TENANT");
+		await waitFor(() => container.textContent === "1|1|1|1|1");
+		expect(fetchMock).toHaveBeenCalledTimes(10);
+		await render("A", "include");
+		await waitFor(
+			() =>
+				fetchMock.mock.calls.length === 15 &&
+				container.textContent === "1|1|1|1|1",
+		);
+	});
+
+	it("does not apply the prior tenant's in-flight responses after a header switch", async () => {
+		const finishA: Array<() => void> = [];
+		fetchMock.mockImplementation((input, init) =>
+			new Headers(init?.headers).get("x-tenant") === "A"
+				? new Promise<Response>((resolve) =>
+						finishA.push(() => resolve(responseFor(input, 1))),
+					)
+				: Promise.resolve(responseFor(input, 2)),
+		);
+		await render("A");
+		await waitFor(() => finishA.length === 5);
+		await render("B");
+		await waitFor(() => container.textContent === "2|2|2|2|2");
+		await act(async () => {
+			finishA.forEach((finish) => finish());
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		});
+		expect(container.textContent).toBe("2|2|2|2|2");
+		expect(fetchMock).toHaveBeenCalledTimes(10);
+	});
+});

package/src/plugins/analytics/__tests__/tracker.test.ts

@@ -0,0 +1,230 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAnalyticsTracker, track } from "../client/tracker";
+
+const beacon = vi.fn((_url: string, _body: Blob) => true);
+const fetchMock = vi.fn(
+	async (_url: string, _init: RequestInit) =>
+		new Response(null, { status: 204 }),
+);
+
+beforeEach(() => {
+	vi.useFakeTimers();
+	vi.setSystemTime(new Date("2026-11-03T12:00:00Z"));
+	beacon.mockReset().mockReturnValue(true);
+	fetchMock.mockReset().mockResolvedValue(new Response(null, { status: 204 }));
+	vi.stubGlobal("window", {
+		location: {
+			href: "https://site.test/pricing?email=private#details",
+			origin: "https://site.test",
+		},
+	});
+	vi.stubGlobal("document", {
+		referrer: "https://search.test/results?private=secret",
+	});
+	vi.stubGlobal("navigator", { sendBeacon: beacon, doNotTrack: "0" });
+	vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+	vi.useRealTimers();
+});
+
+async function beaconBody(index = 0) {
+	return JSON.parse(await (beacon.mock.calls[index]![1] as Blob).text());
+}
+
+describe("analytics tracker", () => {
+	it("tracks on HTTP origins without randomUUID using cryptographic session IDs", async () => {
+		const getRandomValues = globalThis.crypto.getRandomValues.bind(
+			globalThis.crypto,
+		);
+		vi.stubGlobal("crypto", { getRandomValues, randomUUID: undefined });
+		const tracker = createAnalyticsTracker();
+		expect(await tracker.pageView()).toBe(true);
+		expect(await tracker.track("clicked")).toBe(true);
+		expect(await createAnalyticsTracker().track("another_visit")).toBe(true);
+		const first = (await beaconBody()).sessionId;
+		expect(first).toMatch(/^[a-f0-9]{32}$/);
+		expect((await beaconBody(1)).sessionId).toBe(first);
+		expect((await beaconBody(2)).sessionId).not.toBe(first);
+	});
+
+	it("sends private page paths and referrer origins using a beacon, without storage", async () => {
+		const tracker = createAnalyticsTracker({ apiBasePath: "/api/data/" });
+		expect(await tracker.pageView()).toBe(true);
+		expect(beacon.mock.calls[0]![0]).toBe("/api/data/analytics/pageviews");
+		expect(await beaconBody()).toEqual({
+			path: "/pricing",
+			referrer: "https://search.test",
+			sessionId: expect.any(String),
+		});
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("shares one in-memory session for page views and events, then expires after inactivity", async () => {
+		const tracker = createAnalyticsTracker();
+		await tracker.pageView();
+		await tracker.track("signup_completed", { plan: "pro" });
+		const first = await beaconBody();
+		expect(await beaconBody(1)).toMatchObject({
+			name: "signup_completed",
+			path: "/pricing",
+			properties: { plan: "pro" },
+			sessionId: first.sessionId,
+		});
+		vi.advanceTimersByTime(31 * 60000);
+		await tracker.track("returned");
+		expect((await beaconBody(2)).sessionId).not.toBe(first.sessionId);
+	});
+
+	it.each(["", "https://site.test/blog?private=secret"])(
+		"marks direct and internal visits explicitly without a self-referrer: %s",
+		async (referrer) => {
+			vi.stubGlobal("document", { referrer });
+			await createAnalyticsTracker({
+				apiBaseURL: "https://api.test",
+			}).pageView();
+			expect((await beaconBody()).referrer).toBe("");
+		},
+	);
+
+	it.each([undefined, "https://api.test/"])(
+		"keeps a root API mount on its configured origin: %s",
+		async (apiBaseURL) => {
+			await createAnalyticsTracker({ apiBaseURL, apiBasePath: "/" }).pageView();
+			expect(beacon.mock.calls[0]![0]).toBe(
+				`${apiBaseURL?.replace(/\/$/, "") ?? ""}/analytics/pageviews`,
+			);
+		},
+	);
+
+	it("deduplicates nested render notifications but counts a return visit", async () => {
+		const tracker = createAnalyticsTracker();
+		await tracker.pageView("/blog?private=value");
+		await tracker.pageView("/blog");
+		expect(beacon).toHaveBeenCalledTimes(1);
+		await tracker.pageView("/pricing");
+		await tracker.pageView("/blog");
+		expect(beacon).toHaveBeenCalledTimes(3);
+	});
+
+	it("falls back when beacon is unavailable and respects explicit credentials", async () => {
+		beacon.mockReturnValue(false);
+		await createAnalyticsTracker({ apiBaseURL: "https://collect.test/" }).track(
+			"clicked",
+		);
+		expect(fetchMock).toHaveBeenCalledWith(
+			"https://collect.test/api/data/analytics/events",
+			expect.objectContaining({
+				method: "POST",
+				keepalive: true,
+				credentials: "omit",
+			}),
+		);
+		await createAnalyticsTracker({ credentials: "include" }).track("clicked");
+		expect(beacon).toHaveBeenCalledTimes(1);
+		expect(fetchMock).toHaveBeenLastCalledWith(
+			"/api/data/analytics/events",
+			expect.objectContaining({ credentials: "include" }),
+		);
+	});
+
+	it("does not send with Do Not Track or during server rendering", async () => {
+		vi.stubGlobal("navigator", { sendBeacon: beacon, doNotTrack: "1" });
+		expect(await createAnalyticsTracker().track("clicked")).toBe(false);
+		vi.stubGlobal("window", undefined);
+		expect(await createAnalyticsTracker().pageView()).toBe(false);
+		expect(beacon).not.toHaveBeenCalled();
+	});
+
+	it("uses Fetch for explicit headers and preserves JSON content type case-insensitively", async () => {
+		await createAnalyticsTracker({
+			headers: { "X-Tenant": "public-tenant", "content-type": "text/plain" },
+		}).pageView();
+		expect(beacon).not.toHaveBeenCalled();
+		const init = fetchMock.mock.calls[0]![1] as RequestInit;
+		const headers = new Headers(init.headers);
+		expect(headers.get("x-tenant")).toBe("public-tenant");
+		expect(headers.get("content-type")).toBe("application/json");
+		expect(
+			[...headers].filter(([name]) => name === "content-type"),
+		).toHaveLength(1);
+		expect(init.keepalive).toBe(true);
+	});
+
+	it("separates standalone tracker sessions by header values and normalizes header names", async () => {
+		await track(
+			"first",
+			{},
+			{ apiBasePath: "/tenant", headers: { "X-Tenant": "one" } },
+		);
+		await track(
+			"second",
+			{},
+			{ apiBasePath: "/tenant", headers: new Headers({ "x-tenant": "one" }) },
+		);
+		await track(
+			"third",
+			{},
+			{ apiBasePath: "/tenant", headers: { "x-tenant": "two" } },
+		);
+		const bodies = fetchMock.mock.calls.map((call) =>
+			JSON.parse(String((call[1] as RequestInit).body)),
+		);
+		expect(bodies[0].sessionId).toBe(bodies[1].sessionId);
+		expect(bodies[2].sessionId).not.toBe(bodies[0].sessionId);
+	});
+
+	it("keeps cached transport stable when the caller mutates headers and credentials", async () => {
+		const headers = new Headers({ "x-tenant": "one" });
+		const options = {
+			apiBasePath: "/mutable-tenant",
+			headers,
+			credentials: "omit" as RequestCredentials,
+		};
+		await track("first", {}, options);
+		headers.set("x-tenant", "two");
+		options.credentials = "include";
+		await track("second", {}, options);
+		await track(
+			"third",
+			{},
+			{
+				apiBasePath: "/mutable-tenant",
+				headers: { "x-tenant": "one" },
+				credentials: "omit",
+			},
+		);
+		expect(
+			fetchMock.mock.calls.map(([, init]) =>
+				new Headers(init.headers).get("x-tenant"),
+			),
+		).toEqual(["one", "two", "one"]);
+		expect(fetchMock.mock.calls.map(([, init]) => init.credentials)).toEqual([
+			"omit",
+			"include",
+			"omit",
+		]);
+	});
+
+	it("never interrupts navigation on invalid paths, network failure or cyclic properties", async () => {
+		const tracker = createAnalyticsTracker({ credentials: "omit" });
+		expect(await tracker.pageView("http://[")).toBe(false);
+		fetchMock.mockRejectedValue(new Error("offline"));
+		expect(await tracker.track("clicked")).toBe(false);
+		const cyclic: Record<string, unknown> = {};
+		cyclic.self = cyclic;
+		expect(
+			await tracker.track("clicked", cyclic as Record<string, string>),
+		).toBe(false);
+	});
+
+	it("reuses a session across standalone track calls with equivalent options", async () => {
+		await track("first", {}, { apiBasePath: "/standalone" });
+		await track("second", {}, { apiBasePath: "/standalone" });
+		expect((await beaconBody(1)).sessionId).toBe(
+			(await beaconBody()).sessionId,
+		);
+	});
+});

package/src/plugins/analytics/api/getters.ts

@@ -0,0 +1,298 @@
+import type { DBAdapter as Adapter } from "@btst/db";
+import type {
+	AnalyticsCustomEvent,
+	AnalyticsDashboardStats,
+	AnalyticsPageView,
+	AnalyticsRangeParams,
+} from "../types";
+
+const DAY = 86400000;
+
+/** Resolve UTC boundaries; callers own input validation and authorization. */
+export function analyticsDateRange(
+	params: AnalyticsRangeParams,
+	now = new Date(),
+	retentionDays = 90,
+) {
+	const today = new Date(now);
+	today.setUTCHours(0, 0, 0, 0);
+	let start =
+		params.range === "custom" && params.start
+			? new Date(params.start)
+			: new Date(
+					today.getTime() -
+						((params.range === "30d" ? 30 : params.range === "today" ? 1 : 7) -
+							1) *
+							DAY,
+				);
+	const end =
+		params.range === "custom" && params.end
+			? new Date(Date.parse(params.end) + (params.end.length === 10 ? DAY : 0))
+			: now;
+	start = new Date(
+		Math.max(start.getTime(), now.getTime() - retentionDays * DAY),
+	);
+	return { start, end };
+}
+
+/** Read retained raw rows in batches. Callers own validation and access control. */
+export async function getAnalyticsRows<
+	T extends AnalyticsPageView | AnalyticsCustomEvent,
+>(
+	adapter: Adapter,
+	model: "pageView" | "customEvent",
+	params: AnalyticsRangeParams,
+	now = new Date(),
+	retentionDays = 90,
+): Promise<T[]> {
+	const { start, end } = analyticsDateRange(params, now, retentionDays);
+	const where = [
+		{ field: "timestamp", operator: "gte" as const, value: start },
+		{ field: "timestamp", operator: "lt" as const, value: end },
+		...(params.path
+			? [{ field: "path", operator: "eq" as const, value: params.path }]
+			: []),
+	];
+	const rows: T[] = [];
+	for (let offset = 0; ; offset += 1000) {
+		const batch = await adapter.findMany<T>({
+			model,
+			where,
+			limit: 1000,
+			offset,
+			sortBy: { field: "timestamp", direction: "asc" },
+		});
+		rows.push(...batch);
+		if (batch.length < 1000) return rows;
+	}
+}
+
+/** Aggregate retained traffic. Pure DB read; callers own authorization. */
+export async function getDashboardStats(
+	adapter: Adapter,
+	params: AnalyticsRangeParams = {},
+	now = new Date(),
+	retentionDays = 90,
+): Promise<AnalyticsDashboardStats> {
+	const [views, events] = await Promise.all([
+		getAnalyticsRows<AnalyticsPageView>(
+			adapter,
+			"pageView",
+			params,
+			now,
+			retentionDays,
+		),
+		getAnalyticsRows<AnalyticsCustomEvent>(
+			adapter,
+			"customEvent",
+			params,
+			now,
+			retentionDays,
+		),
+	]);
+	const { start, end } = analyticsDateRange(params, now, retentionDays);
+	const days: string[] = [];
+	const cursor = new Date(start);
+	cursor.setUTCHours(0, 0, 0, 0);
+	for (
+		;
+		cursor.getTime() < end.getTime();
+		cursor.setUTCDate(cursor.getUTCDate() + 1)
+	)
+		days.push(cursor.toISOString().slice(0, 10));
+	const sessions = new Map<string, number[]>();
+	const pageGroups = new Map<string, AnalyticsPageView[]>();
+	const referrerGroups = new Map<string, AnalyticsPageView[]>();
+	for (const view of views) {
+		const times = sessions.get(view.sessionId) ?? [];
+		times.push(new Date(view.timestamp).getTime());
+		sessions.set(view.sessionId, times);
+		const pageItems = pageGroups.get(view.path) ?? [];
+		pageItems.push(view);
+		pageGroups.set(view.path, pageItems);
+		const referrer = view.referrer || "Direct";
+		const referrerItems = referrerGroups.get(referrer) ?? [];
+		referrerItems.push(view);
+		referrerGroups.set(referrer, referrerItems);
+	}
+	const visits: number[][] = [];
+	for (const times of sessions.values()) {
+		times.sort((a, b) => a - b);
+		let visit: number[] = [];
+		for (const time of times) {
+			if (visit.length && time - visit[visit.length - 1]! > 30 * 60000) {
+				visits.push(visit);
+				visit = [];
+			}
+			visit.push(time);
+		}
+		if (visit.length) visits.push(visit);
+	}
+	const eventCounts = new Map<string, number>();
+	for (const event of events)
+		eventCounts.set(event.name, (eventCounts.get(event.name) ?? 0) + 1);
+	const limit = params.limit ?? 10;
+	return {
+		uniqueVisitors: sessions.size,
+		pageViews: views.length,
+		bounceRate: visits.length
+			? Math.round(
+					(visits.filter((visit) => visit.length === 1).length /
+						visits.length) *
+						1000,
+				) / 10
+			: 0,
+		sessionDuration: visits.length
+			? Math.round(
+					visits.reduce(
+						(sum, visit) => sum + (visit[visit.length - 1]! - visit[0]!) / 1000,
+						0,
+					) / visits.length,
+				)
+			: 0,
+		series: days.map((date) => {
+			const daily = views.filter((view) =>
+				new Date(view.timestamp).toISOString().startsWith(date),
+			);
+			return {
+				date,
+				pageViews: daily.length,
+				visitors: new Set(daily.map((view) => view.sessionId)).size,
+			};
+		}),
+		topPages: [...pageGroups]
+			.map(([path, items]) => ({
+				path,
+				views: items.length,
+				visitors: new Set(items.map((item) => item.sessionId)).size,
+				trend: days.map(
+					(date) =>
+						items.filter((item) =>
+							new Date(item.timestamp).toISOString().startsWith(date),
+						).length,
+				),
+			}))
+			.sort((a, b) => b.views - a.views || a.path.localeCompare(b.path))
+			.slice(0, limit),
+		topReferrers: [...referrerGroups]
+			.map(([referrer, items]) => ({
+				referrer,
+				views: items.length,
+				visitors: new Set(items.map((item) => item.sessionId)).size,
+			}))
+			.sort((a, b) => b.views - a.views || a.referrer.localeCompare(b.referrer))
+			.slice(0, limit),
+		topEvents: [...eventCounts]
+			.map(([name, count]) => ({ name, count }))
+			.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+			.slice(0, limit),
+	};
+}
+
+/** Top pages for server-side embedding; callers own authorization. */
+export async function getTopPages(
+	adapter: Adapter,
+	params: AnalyticsRangeParams = {},
+	now = new Date(),
+	retentionDays = 90,
+) {
+	return (await getDashboardStats(adapter, params, now, retentionDays))
+		.topPages;
+}
+
+/** Top referrers for server-side embedding; callers own authorization. */
+export async function getTopReferrers(
+	adapter: Adapter,
+	params: AnalyticsRangeParams = {},
+	now = new Date(),
+	retentionDays = 90,
+) {
+	return (await getDashboardStats(adapter, params, now, retentionDays))
+		.topReferrers;
+}
+
+/** Top custom events for server-side embedding; callers own authorization. */
+export async function getTopEvents(
+	adapter: Adapter,
+	params: AnalyticsRangeParams = {},
+	now = new Date(),
+	retentionDays = 90,
+) {
+	return (await getDashboardStats(adapter, params, now, retentionDays))
+		.topEvents;
+}
+
+/** Unique visitors with a page view in the last five minutes. Callers own authorization. */
+export async function getRealtimeVisitors(
+	adapter: Adapter,
+	now = new Date(),
+	retentionDays = 90,
+) {
+	const views = await getAnalyticsRows<AnalyticsPageView>(
+		adapter,
+		"pageView",
+		{
+			range: "custom",
+			start: new Date(now.getTime() - 5 * 60000).toISOString(),
+			end: now.toISOString(),
+		},
+		now,
+		retentionDays,
+	);
+	return { visitors: new Set(views.map((view) => view.sessionId)).size };
+}
+
+function csvCell(value: unknown): string {
+	const raw = String(value ?? "");
+	const safe = /^[\s]*[=+@\-\t\r]/.test(raw) ? `'${raw}` : raw;
+	return `"${safe.replaceAll('"', '""')}"`;
+}
+
+/** Export retained raw events. Formula-like cells are escaped. Callers own authorization. */
+export async function exportEvents(
+	adapter: Adapter,
+	params: AnalyticsRangeParams = {},
+	now = new Date(),
+	retentionDays = 90,
+): Promise<string> {
+	const [views, events] = await Promise.all([
+		getAnalyticsRows<AnalyticsPageView>(
+			adapter,
+			"pageView",
+			params,
+			now,
+			retentionDays,
+		),
+		getAnalyticsRows<AnalyticsCustomEvent>(
+			adapter,
+			"customEvent",
+			params,
+			now,
+			retentionDays,
+		),
+	]);
+	const rows = [
+		...views.map((view) => [
+			"pageview",
+			view.path,
+			"",
+			view.referrer,
+			"",
+			view.sessionId,
+			new Date(view.timestamp).toISOString(),
+		]),
+		...events.map((event) => [
+			"event",
+			event.path,
+			event.name,
+			"",
+			event.properties,
+			event.sessionId,
+			new Date(event.timestamp).toISOString(),
+		]),
+	];
+	return [
+		"type,path,name,referrer,properties,sessionId,timestamp",
+		...rows.map((row) => row.map(csvCell).join(",")),
+	].join("\r\n");
+}