@btst/stack 5.0.0 → 5.2.0

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

@@ -0,0 +1,284 @@
+import { createMemoryAdapter } from "@btst/adapter-memory";
+import { type DBAdapter, defineDb } from "@btst/db";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { createBackendStack } from "../../../api";
+import { defineAuthorization } from "../../../authorization";
+import { createServerAuth } from "../../../authorization/server";
+import { analyticsBackendPlugin } from "../api/plugin";
+import { analyticsSchema } from "../db";
+import { analyticsPermissions } from "../permissions";
+import { AnalyticsRangeSchema } from "../schemas";
+import {
+	exportEvents,
+	getDashboardStats,
+	getRealtimeVisitors,
+} from "../api/getters";
+import {
+	cleanupExpiredEvents,
+	recordEvent,
+	recordPageView,
+} from "../api/mutations";
+import type { AnalyticsBackendOptions } from "../api/operations";
+import type { AnalyticsPageView } from "../types";
+
+const browserAgent = "Mozilla/5.0 Chrome/131.0.0.0 Safari/537.36";
+const sessionId = "anonymous-browser-session-123";
+const now = new Date("2026-11-03T12:00:00Z");
+
+function setup(options: AnalyticsBackendOptions = {}, withAuth = true) {
+	let adapter!: DBAdapter;
+	const authorization = defineAuthorization({
+		identity: z.object({ id: z.string() }),
+		permissions: [analyticsPermissions],
+		rules: () => [],
+	});
+	const stack = createBackendStack({
+		basePath: "/api",
+		...(withAuth
+			? { auth: createServerAuth({ authorization, getIdentity: () => null }) }
+			: {}),
+		plugins: {
+			analytics: analyticsBackendPlugin({
+				sessionSecret: "analytics-server-secret-123",
+				...options,
+			}),
+		},
+		adapter: (db) => {
+			adapter = createMemoryAdapter(db)({});
+			return adapter;
+		},
+	});
+	return { stack, adapter: () => adapter, operations: stack.trusted.analytics };
+}
+
+function request(path: string, body?: unknown, userAgent = browserAgent) {
+	return new Request(`https://example.test/api/analytics/${path}`, {
+		method: body ? "POST" : "GET",
+		headers: {
+			"user-agent": userAgent,
+			"content-type": "application/json",
+			"x-forwarded-for": "192.168.1.234",
+		},
+		...(body ? { body: JSON.stringify(body) } : {}),
+	});
+}
+
+describe("analytics backend", () => {
+	it("accepts anonymous browser ingestion, strips query/referrer details, and stores only daily session hashes", async () => {
+		const before = vi.fn();
+		const after = vi.fn();
+		const { stack, adapter } = setup({
+			hooks: { onBeforeIngest: before, onAfterIngest: after },
+		});
+		const response = await stack.handler(
+			request("pageviews", {
+				path: "/docs?token=secret#fragment",
+				referrer: "https://search.example/query?private=yes",
+				sessionId,
+			}),
+		);
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({ accepted: true });
+		const rows = await adapter().findMany<AnalyticsPageView>({
+			model: "pageView",
+		});
+		expect(rows).toHaveLength(1);
+		expect(rows[0]).toMatchObject({
+			path: "/docs",
+			referrer: "search.example",
+			sessionId: expect.stringMatching(/^[a-f0-9]{64}$/),
+			device: "desktop",
+			browser: "Chrome",
+		});
+		expect(JSON.stringify(rows)).not.toMatch(
+			/192\.168|anonymous-browser|token=|private=yes|Mozilla/,
+		);
+		expect(before).toHaveBeenCalledOnce();
+		expect(after).toHaveBeenCalledOnce();
+		expect(before.mock.calls[0]?.[0].sessionId).toBe(rows[0]?.sessionId);
+	});
+
+	it("filters crawlers and non-browser agents and validates public ingestion", async () => {
+		const { stack, adapter } = setup();
+		for (const agent of [
+			"Googlebot",
+			"curl/8",
+			"Mozilla/5.0 compatible; bingbot/2.0",
+			"Mozilla/5.0 HeadlessChrome/131.0",
+		]) {
+			const response = await stack.handler(
+				request("pageviews", { path: "/", sessionId }, agent),
+			);
+			expect(await response.json()).toEqual({ accepted: false });
+		}
+		expect(await adapter().findMany({ model: "pageView" })).toEqual([]);
+		expect(
+			(
+				await stack.handler(
+					request("pageviews", { path: "https://private.example", sessionId }),
+				)
+			).status,
+		).toBe(400);
+		expect(
+			(
+				await stack.handler(
+					request("events", {
+						path: "/",
+						sessionId,
+						name: "click",
+						properties: { payload: "x".repeat(5000) },
+					}),
+				)
+			).status,
+		).toBe(400);
+	});
+
+	it("protects all reads, CSV and retention even when no stack auth is configured", async () => {
+		for (const withAuth of [true, false]) {
+			const { stack, operations } = setup({}, withAuth);
+			for (const path of [
+				"dashboard",
+				"pages",
+				"referrers",
+				"events",
+				"realtime",
+				"export",
+			])
+				expect((await stack.handler(request(path))).status).toBe(401);
+			expect((await stack.handler(request("retention", {}))).status).toBe(401);
+			expect(await operations.getDashboardStats({})).toMatchObject({
+				uniqueVisitors: 0,
+				pageViews: 0,
+				bounceRate: 0,
+			});
+		}
+	});
+
+	it("aggregates unique visitors, UTC day buckets, session gaps, top traffic and custom events", async () => {
+		const adapter = createMemoryAdapter(defineDb({}).use(analyticsSchema))({});
+		for (const view of [
+			{
+				path: "/docs",
+				sessionId: "a",
+				timestamp: new Date("2026-11-03T10:00:00Z"),
+				referrer: "search.example",
+			},
+			{
+				path: "/guide",
+				sessionId: "a",
+				timestamp: new Date("2026-11-03T10:02:00Z"),
+			},
+			{
+				path: "/docs",
+				sessionId: "a",
+				timestamp: new Date("2026-11-03T11:00:00Z"),
+			},
+			{
+				path: "/docs",
+				sessionId: "b",
+				timestamp: new Date("2026-11-02T23:50:00Z"),
+			},
+		])
+			await recordPageView(adapter, view);
+		await recordEvent(adapter, {
+			name: "signup",
+			path: "/docs",
+			sessionId: "a",
+			timestamp: new Date("2026-11-03T10:01:00Z"),
+			properties: '{"plan":"pro"}',
+		});
+		const stats = await getDashboardStats(adapter, { range: "7d" }, now);
+		expect(stats).toMatchObject({
+			uniqueVisitors: 2,
+			pageViews: 4,
+			bounceRate: 66.7,
+			sessionDuration: 40,
+			topEvents: [{ name: "signup", count: 1 }],
+		});
+		expect(stats.series).toHaveLength(7);
+		expect(stats.series.at(-1)).toEqual({
+			date: "2026-11-03",
+			pageViews: 3,
+			visitors: 1,
+		});
+		expect(stats.topPages[0]).toMatchObject({
+			path: "/docs",
+			views: 3,
+			visitors: 2,
+			trend: [0, 0, 0, 0, 0, 1, 2],
+		});
+		expect(stats.topReferrers).toContainEqual({
+			referrer: "search.example",
+			views: 1,
+			visitors: 1,
+		});
+		expect(
+			(
+				await getDashboardStats(
+					adapter,
+					{ range: "today", path: "/guide" },
+					now,
+				)
+			).pageViews,
+		).toBe(1);
+	});
+
+	it("enforces retention on reads and ingestion and escapes CSV formula cells", async () => {
+		const { adapter, operations } = setup({ retentionDays: 1 });
+		await recordPageView(adapter(), {
+			path: "/old",
+			sessionId: "old",
+			timestamp: new Date(Date.now() - 3 * 86400000),
+		});
+		await recordEvent(adapter(), {
+			name: '=HYPERLINK("https://example.test")',
+			path: "/",
+			sessionId: "new",
+			timestamp: new Date(Date.now() - 1000),
+		});
+		expect(
+			(await operations.getDashboardStats({ range: "30d" })).pageViews,
+		).toBe(0);
+		const csv = await exportEvents(adapter(), {}, new Date());
+		expect(csv).toContain('"\'=HYPERLINK(""https://example.test"")"');
+		await operations.recordPageView({ path: "/new", sessionId });
+		expect(await adapter().findMany({ model: "pageView" })).toHaveLength(1);
+		expect(await cleanupExpiredEvents(adapter(), 1)).toMatchObject({
+			pageViews: 0,
+			customEvents: 0,
+		});
+	});
+
+	it("counts only the last five minutes as realtime and validates custom calendar dates", async () => {
+		const adapter = createMemoryAdapter(defineDb({}).use(analyticsSchema))({});
+		for (const [id, minutes] of [
+			["a", 1],
+			["a", 2],
+			["b", 6],
+		] as const)
+			await recordPageView(adapter, {
+				path: "/",
+				sessionId: id,
+				timestamp: new Date(now.getTime() - minutes * 60000),
+			});
+		expect(await getRealtimeVisitors(adapter, now)).toEqual({ visitors: 1 });
+		expect(
+			AnalyticsRangeSchema.safeParse({
+				range: "custom",
+				start: "2026-02-31",
+				end: "2026-03-02",
+			}).success,
+		).toBe(false);
+		expect(
+			AnalyticsRangeSchema.safeParse({
+				range: "custom",
+				start: "2026-11-03",
+				end: "2026-11-02",
+			}).success,
+		).toBe(false);
+		expect(AnalyticsRangeSchema.safeParse({ range: "custom" }).success).toBe(
+			false,
+		);
+	});
+});

package/src/plugins/analytics/__tests__/client-plugin.test.ts

@@ -0,0 +1,179 @@
+import { QueryClient } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createClientStack } from "../../../client";
+import { defineClientPlugin, defineRoute } from "../../../plugins/client";
+import { analyticsClientPlugin } from "../client/plugin";
+import { setDefaultAnalyticsTracker, track } from "../client/tracker";
+
+afterEach(() => vi.unstubAllGlobals());
+
+function browserGlobals() {
+	vi.stubGlobal("window", {
+		location: {
+			href: "https://site.test/pages/pricing",
+			origin: "https://site.test",
+			pathname: "/pages/pricing",
+		},
+	});
+	vi.stubGlobal("document", { referrer: "" });
+}
+
+describe("analytics client composition", () => {
+	it("keeps the analytics route alongside another plugin's dashboard route", () => {
+		const stack = createClientStack({
+			api: { baseURL: "https://site.test", basePath: "/api/data" },
+			site: { baseURL: "https://site.test", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: {
+				analytics: analyticsClientPlugin(),
+				cms: defineClientPlugin({
+					id: "cms",
+					resolve: () => ({
+						routes: () => ({
+							dashboard: defineRoute("/cms", { page: () => null }),
+						}),
+					}),
+				}),
+			},
+		});
+		expect(stack.router.getRoute("/analytics")?.PageComponent).toBeDefined();
+		expect(stack.router.getRoute("/cms")?.PageComponent).toBeDefined();
+	});
+
+	it("forwards configured public headers for automatic views and the default track helper", async () => {
+		browserGlobals();
+		const beacon = vi.fn(() => true);
+		const fetchMock = vi.fn(
+			async (_url: string, _init: RequestInit) =>
+				new Response(null, { status: 204 }),
+		);
+		vi.stubGlobal("navigator", { doNotTrack: "0", sendBeacon: beacon });
+		vi.stubGlobal("fetch", fetchMock);
+		const stack = createClientStack({
+			api: { baseURL: "https://site.test", basePath: "/api/data" },
+			site: { baseURL: "https://site.test", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { analytics: analyticsClientPlugin() },
+			endpoints: {
+				analytics: {
+					api: {
+						basePath: "/api/analytics",
+						browserHeaders: { "X-Tenant": "public-tenant" },
+					},
+				},
+			},
+		});
+		await stack.context.plugins.analytics!.hooks?.onRouteRender?.({
+			path: "/pricing",
+		});
+		await track("signup_completed");
+		expect(beacon).not.toHaveBeenCalled();
+		expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([
+			"https://site.test/api/analytics/analytics/pageviews",
+			"https://site.test/api/analytics/analytics/events",
+		]);
+		for (const [, init] of fetchMock.mock.calls) {
+			const headers = new Headers(init.headers);
+			expect(headers.get("x-tenant")).toBe("public-tenant");
+			expect(headers.get("content-type")).toBe("application/json");
+		}
+		const [view, event] = fetchMock.mock.calls.map(([, init]) =>
+			JSON.parse(String(init.body)),
+		);
+		expect(event.sessionId).toBe(view.sessionId);
+	});
+
+	it("never retains server request credentials in a collection tracker", async () => {
+		browserGlobals();
+		const existingDefault = vi.fn(async () => true);
+		setDefaultAnalyticsTracker({
+			pageView: async () => false,
+			track: existingDefault,
+		});
+		vi.stubGlobal("window", undefined);
+		const beacon = vi.fn(() => true);
+		const fetchMock = vi.fn();
+		vi.stubGlobal("navigator", { doNotTrack: "0", sendBeacon: beacon });
+		vi.stubGlobal("fetch", fetchMock);
+		const stack = createClientStack({
+			api: {
+				baseURL: "https://site.test",
+				basePath: "/api/data",
+				headers: {
+					Authorization: "Bearer server-only-secret",
+					Cookie: "session=private",
+				},
+			},
+			site: { baseURL: "https://site.test", basePath: "/pages" },
+			queryClient: new QueryClient(),
+			plugins: { analytics: analyticsClientPlugin() },
+		});
+		await stack.context.plugins.analytics!.hooks?.onRouteRender?.({
+			path: "/pricing",
+		});
+		expect(beacon).not.toHaveBeenCalled();
+		expect(fetchMock).not.toHaveBeenCalled();
+		browserGlobals();
+		await track("default_preserved_after_ssr");
+		expect(existingDefault).toHaveBeenCalledWith(
+			"default_preserved_after_ssr",
+			undefined,
+		);
+		await stack.context.plugins.analytics!.hooks?.onRouteRender?.({
+			path: "/pricing",
+		});
+		expect(beacon).toHaveBeenCalledOnce();
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("keeps one browser session across provider and navigation-loader stack resolutions", async () => {
+		browserGlobals();
+		vi.stubGlobal("navigator", { doNotTrack: "0" });
+		const fetchMock = vi.fn(
+			async (_url: string, _init: RequestInit) =>
+				new Response(null, { status: 204 }),
+		);
+		vi.stubGlobal("fetch", fetchMock);
+		const queryClient = new QueryClient();
+		function resolve(headers: HeadersInit) {
+			return createClientStack({
+				api: { baseURL: "https://site.test", basePath: "/lifecycle-api" },
+				site: { baseURL: "https://site.test", basePath: "/pages" },
+				queryClient,
+				plugins: { analytics: analyticsClientPlugin() },
+				endpoints: {
+					analytics: {
+						api: {
+							basePath: "/lifecycle-api",
+							credentials: "omit",
+							browserHeaders: headers,
+						},
+					},
+				},
+			});
+		}
+		const provider = resolve({ "X-Tenant": "one" });
+		await provider.context.plugins.analytics!.hooks?.onRouteRender?.({
+			path: "/pricing",
+		});
+		resolve({ "x-tenant": "one" });
+		await track("first_navigation");
+		window.location.pathname = "/pages/docs";
+		await provider.context.plugins.analytics!.hooks?.onRouteRender?.({
+			path: "/docs",
+		});
+		resolve(new Headers({ "X-TENANT": "one" }));
+		await track("second_navigation");
+		const bodies = () =>
+			fetchMock.mock.calls.map(([, init]) => JSON.parse(String(init.body)));
+		expect(bodies()).toHaveLength(4);
+		const sessionId = bodies()[0].sessionId;
+		expect(new Set(bodies().map((body) => body.sessionId)).size).toBe(1);
+		resolve({ "x-tenant": "two" });
+		await track("other_tenant");
+		expect(bodies()[4].sessionId).not.toBe(sessionId);
+		resolve({ "x-tenant": "one" });
+		await track("back_to_first_tenant");
+		expect(bodies()[5].sessionId).toBe(sessionId);
+	});
+});

package/src/plugins/analytics/__tests__/dashboard-ssr.test.tsx

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { AnalyticsDashboardPageComponent } from "../client/components/pages/dashboard-page";
+
+const mocks = vi.hoisted(() => ({ protectedQuery: vi.fn() }));
+vi.mock("../client/components/pages/dashboard-page.internal", () => ({
+	AnalyticsDashboardPage: () => {
+		mocks.protectedQuery();
+		return <div>Loaded dashboard</div>;
+	},
+}));
+(
+	globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("analytics dynamic dashboard", () => {
+	it("defers protected dashboard queries until browser hydration", async () => {
+		const html = renderToString(<AnalyticsDashboardPageComponent />);
+		expect(html).toContain("Loading traffic");
+		expect(mocks.protectedQuery).not.toHaveBeenCalled();
+		const container = document.createElement("div");
+		container.innerHTML = html;
+		document.body.append(container);
+		const errors: unknown[] = [];
+		let root: ReturnType<typeof hydrateRoot>;
+		await act(async () => {
+			root = hydrateRoot(container, <AnalyticsDashboardPageComponent />, {
+				onRecoverableError: (error) => errors.push(error),
+			});
+		});
+		expect(container.textContent).toContain("Loaded dashboard");
+		expect(mocks.protectedQuery).toHaveBeenCalled();
+		expect(errors).toEqual([]);
+		await act(async () => root!.unmount());
+		container.remove();
+	});
+});

package/src/plugins/analytics/__tests__/dashboard.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+import { act, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AnalyticsDashboardPage } from "../client/components/pages/dashboard-page.internal";
+import type { AnalyticsDashboardStats } from "../types";
+
+const stats: AnalyticsDashboardStats = {
+	uniqueVisitors: 2,
+	pageViews: 3,
+	bounceRate: 50,
+	sessionDuration: 65,
+	series: [{ date: "2026-11-03", pageViews: 3, visitors: 2 }],
+	topPages: [{ path: "/pricing", views: 3, visitors: 2, trend: [3] }],
+	topReferrers: [{ referrer: "search.test", views: 2, visitors: 1 }],
+	topEvents: [{ name: "signup_completed", count: 1 }],
+};
+const mocks = vi.hoisted(() => ({ dashboard: vi.fn(), fetch: vi.fn() }));
+vi.mock("../client/hooks", () => ({
+	useSuspenseDashboardStats: (...args: unknown[]) => mocks.dashboard(...args),
+	useRealtimeVisitors: () => ({ data: { visitors: 1 }, isError: false }),
+}));
+vi.mock("@btst/stack/context", () => ({
+	useStack: () => ({
+		plugins: {
+			analytics: {
+				api: {
+					baseURL: "https://site.test",
+					basePath: "/api/data",
+					credentials: "include",
+				},
+			},
+		},
+	}),
+	PermissionAccess: ({ children }: { children: ReactNode }) => children,
+}));
+
+(
+	globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(async () => {
+	mocks.dashboard
+		.mockReset()
+		.mockReturnValue({ data: stats, isFetching: false });
+	mocks.fetch.mockReset().mockResolvedValue(
+		new Response("type,path\npageview,/pricing", {
+			headers: { "content-type": "text/csv" },
+		}),
+	);
+	vi.stubGlobal("fetch", mocks.fetch);
+	vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+	vi.stubGlobal(
+		"URL",
+		class extends URL {
+			static createObjectURL = vi.fn(() => "blob:export");
+			static revokeObjectURL = vi.fn();
+		},
+	);
+	container = document.createElement("div");
+	document.body.append(container);
+	root = createRoot(container);
+	await act(async () => root.render(<AnalyticsDashboardPage />));
+});
+afterEach(async () => {
+	await act(async () => root.unmount());
+	container.remove();
+	vi.restoreAllMocks();
+	vi.unstubAllGlobals();
+});
+
+async function click(label: string) {
+	const button = [...container.querySelectorAll("button")].find(
+		(element) => element.textContent === label,
+	);
+	expect(button).toBeDefined();
+	await act(async () => button!.click());
+}
+
+describe("analytics dashboard", () => {
+	it("uses the chosen date range and submits explicit UTC dates for a custom range", async () => {
+		expect(container.textContent).toContain("signup_completed");
+		expect(container.textContent).toContain("1m 5s");
+		await click("30 days");
+		expect(mocks.dashboard).toHaveBeenLastCalledWith({ range: "30d" });
+		await click("Custom");
+		const inputs = container.querySelectorAll("input");
+		await act(async () => {
+			const setValue = Object.getOwnPropertyDescriptor(
+				HTMLInputElement.prototype,
+				"value",
+			)!.set!;
+			setValue.call(inputs[0], "2026-10-01");
+			inputs[0]!.dispatchEvent(new Event("input", { bubbles: true }));
+			inputs[0]!.dispatchEvent(new Event("change", { bubbles: true }));
+			setValue.call(inputs[1], "2026-10-31");
+			inputs[1]!.dispatchEvent(new Event("input", { bubbles: true }));
+			inputs[1]!.dispatchEvent(new Event("change", { bubbles: true }));
+		});
+		await act(async () =>
+			container
+				.querySelector("form")!
+				.dispatchEvent(
+					new Event("submit", { bubbles: true, cancelable: true }),
+				),
+		);
+		expect(mocks.dashboard).toHaveBeenLastCalledWith({
+			range: "custom",
+			start: "2026-10-01",
+			end: "2026-10-31",
+		});
+	});
+
+	it("exports the selected range with the resolved credentials and reports export failures", async () => {
+		await click("Today");
+		await click("Export CSV");
+		expect(mocks.fetch).toHaveBeenCalledWith(
+			"https://site.test/api/data/analytics/export?range=today",
+			expect.objectContaining({ credentials: "include" }),
+		);
+		expect(URL.createObjectURL).toHaveBeenCalled();
+		mocks.fetch.mockResolvedValue(new Response(null, { status: 403 }));
+		await click("Export CSV");
+		expect(container.querySelector('[role="alert"]')?.textContent).toContain(
+			"Check your export access",
+		);
+	});
+});