@btst/stack 5.0.0 → 5.2.0

package/src/plugins/analytics/client/components/pages/dashboard-page.internal.tsx

@@ -0,0 +1,435 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import { PermissionAccess, useStack } from "@btst/stack/context";
+import { analyticsPermissions } from "../../../permissions";
+import type {
+	AnalyticsRangeParams,
+	AnalyticsSeriesPoint,
+} from "../../../types";
+import { useRealtimeVisitors, useSuspenseDashboardStats } from "../../hooks";
+import { ANALYTICS_PLUGIN_ID } from "../../constants";
+
+const number = new Intl.NumberFormat("en");
+const dateLabel = (date: string) =>
+	new Intl.DateTimeFormat("en", {
+		month: "short",
+		day: "numeric",
+		timeZone: "UTC",
+	}).format(new Date(date));
+const presets = [
+	{ value: "today", label: "Today" },
+	{ value: "7d", label: "7 days" },
+	{ value: "30d", label: "30 days" },
+] as const;
+
+function Sparkline({ values }: { values: number[] }) {
+	const max = Math.max(1, ...values);
+	return (
+		<svg className="analytics-sparkline" viewBox="0 0 96 28" aria-hidden="true">
+			<polyline
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="2"
+				points={values
+					.map(
+						(value, index) =>
+							`${(index * 96) / Math.max(1, values.length - 1)},${26 - (value / max) * 24}`,
+					)
+					.join(" ")}
+			/>
+		</svg>
+	);
+}
+
+function TrafficChart({ series }: { series: AnalyticsSeriesPoint[] }) {
+	const max = Math.max(1, ...series.map((point) => point.pageViews));
+	const points = series.map(
+		(point, index) =>
+			`${(index * 960) / Math.max(1, series.length - 1)},${180 - (point.pageViews / max) * 160}`,
+	);
+	return (
+		<section
+			className="analytics-traffic"
+			aria-labelledby="analytics-traffic-title"
+		>
+			<div className="analytics-section-heading">
+				<h2 id="analytics-traffic-title">Traffic over time</h2>
+				<span>Page views per day · UTC</span>
+			</div>
+			<svg
+				className="analytics-chart"
+				viewBox="-5 0 970 200"
+				role="img"
+				aria-label={`Daily page views from ${series[0]?.date ?? "start"} to ${series.at(-1)?.date ?? "end"}. Peak ${max} page views.`}
+			>
+				<line
+					x1="0"
+					x2="960"
+					y1="180"
+					y2="180"
+					className="analytics-chart-rule"
+				/>
+				{points.length > 0 && (
+					<>
+						<polygon
+							points={`0,180 ${points.join(" ")} ${points.length > 1 ? "960" : "0"},180`}
+							className="analytics-chart-area"
+						/>
+						<polyline
+							points={points.join(" ")}
+							fill="none"
+							stroke="currentColor"
+							strokeWidth="3"
+							vectorEffect="non-scaling-stroke"
+						/>
+						{series.length === 1 && (
+							<circle
+								cx="0"
+								cy={180 - (series[0]!.pageViews / max) * 160}
+								r="4"
+								fill="currentColor"
+							/>
+						)}
+					</>
+				)}
+			</svg>
+			<div className="analytics-chart-labels">
+				<span>{series[0] ? dateLabel(series[0].date) : ""}</span>
+				<span>{series.at(-1) ? dateLabel(series.at(-1)!.date) : ""}</span>
+			</div>
+			<details className="analytics-chart-data">
+				<summary>View daily counts</summary>
+				<div className="analytics-table-scroll">
+					<table>
+						<thead>
+							<tr>
+								<th scope="col">Date (UTC)</th>
+								<th scope="col">Page views</th>
+								<th scope="col">Visitors</th>
+							</tr>
+						</thead>
+						<tbody>
+							{series.map((point) => (
+								<tr key={point.date}>
+									<th scope="row">{point.date}</th>
+									<td>{number.format(point.pageViews)}</td>
+									<td>{number.format(point.visitors)}</td>
+								</tr>
+							))}
+						</tbody>
+					</table>
+				</div>
+			</details>
+		</section>
+	);
+}
+
+/** Dynamic dashboard; all displayed counts come from the authenticated API. */
+export function AnalyticsDashboardPage() {
+	const [params, setParams] = useState<AnalyticsRangeParams>({ range: "7d" });
+	const [custom, setCustom] = useState(false);
+	const [start, setStart] = useState(() =>
+		new Date(Date.now() - 6 * 86400000).toISOString().slice(0, 10),
+	);
+	const [end, setEnd] = useState(() => new Date().toISOString().slice(0, 10));
+	const [rangeError, setRangeError] = useState("");
+	const [exportError, setExportError] = useState("");
+	const [exporting, setExporting] = useState(false);
+	const { data: stats, isFetching } = useSuspenseDashboardStats(params);
+	const realtime = useRealtimeVisitors();
+	const { plugins } = useStack();
+	const api = plugins?.[ANALYTICS_PLUGIN_ID]?.api;
+
+	function applyRange(event: FormEvent) {
+		event.preventDefault();
+		if (!start || !end || start > end) {
+			setRangeError("Choose a start date on or before the end date.");
+			return;
+		}
+		if (Date.parse(end) - Date.parse(start) > 366 * 86400000) {
+			setRangeError("Choose a range of 366 days or fewer.");
+			return;
+		}
+		setRangeError("");
+		setParams({ range: "custom", start, end });
+	}
+
+	async function exportCSV() {
+		setExporting(true);
+		setExportError("");
+		try {
+			const query = new URLSearchParams();
+			for (const [key, value] of Object.entries(params))
+				if (value !== undefined) query.set(key, String(value));
+			const url = `${api?.baseURL ?? ""}${(api?.basePath ?? "/api/data").replace(/\/$/, "")}/analytics/export?${query}`;
+			const response = await fetch(url, {
+				headers: api?.browserHeaders,
+				credentials: api?.credentials ?? "same-origin",
+			});
+			if (!response.ok) throw new Error("Export failed");
+			const download = URL.createObjectURL(await response.blob());
+			const link = document.createElement("a");
+			link.href = download;
+			link.download = "analytics-events.csv";
+			link.click();
+			setTimeout(() => URL.revokeObjectURL(download), 1000);
+		} catch {
+			setExportError(
+				"Events could not be exported. Check your export access and try again.",
+			);
+		} finally {
+			setExporting(false);
+		}
+	}
+
+	const duration = `${Math.floor(stats.sessionDuration / 60)}m ${Math.round(stats.sessionDuration % 60)}s`;
+	return (
+		<main
+			className="analytics-dashboard"
+			data-testid="analytics-dashboard"
+			aria-busy={isFetching}
+		>
+			<header className="analytics-header">
+				<div>
+					<h1>Analytics</h1>
+					<p>Understand how people use your site.</p>
+				</div>
+				<div className="analytics-live" aria-live="polite">
+					{realtime.isError ? (
+						"Live count unavailable"
+					) : realtime.data ? (
+						<>
+							<strong>{number.format(realtime.data.visitors)}</strong> active in
+							the last 5 minutes
+						</>
+					) : (
+						"Loading live count…"
+					)}
+				</div>
+			</header>
+			<div className="analytics-toolbar">
+				<div className="analytics-ranges" role="group" aria-label="Date range">
+					{presets.map((preset) => (
+						<button
+							type="button"
+							key={preset.value}
+							aria-pressed={!custom && params.range === preset.value}
+							onClick={() => {
+								setCustom(false);
+								setRangeError("");
+								setParams({ range: preset.value });
+							}}
+						>
+							{preset.label}
+						</button>
+					))}
+					<button
+						type="button"
+						aria-pressed={custom}
+						onClick={() => setCustom(true)}
+					>
+						Custom
+					</button>
+				</div>
+				<PermissionAccess
+					permission={analyticsPermissions.dashboard.export({})}
+				>
+					<button
+						type="button"
+						disabled={exporting}
+						onClick={() => {
+							void exportCSV();
+						}}
+					>
+						{exporting ? "Exporting…" : "Export CSV"}
+					</button>
+				</PermissionAccess>
+			</div>
+			{custom && (
+				<form className="analytics-custom-range" onSubmit={applyRange}>
+					<label>
+						Start date
+						<input
+							type="date"
+							value={start}
+							max={end || undefined}
+							onChange={(event) => setStart(event.target.value)}
+							required
+						/>
+					</label>
+					<label>
+						End date
+						<input
+							type="date"
+							value={end}
+							min={start || undefined}
+							onChange={(event) => setEnd(event.target.value)}
+							required
+						/>
+					</label>
+					<button type="submit">Apply dates</button>
+					<span>Dates use UTC.</span>
+				</form>
+			)}
+			{rangeError && (
+				<p role="alert" className="analytics-error">
+					{rangeError}
+				</p>
+			)}
+			{exportError && (
+				<p role="alert" className="analytics-error">
+					{exportError}
+				</p>
+			)}
+			<dl className="analytics-metrics">
+				<div>
+					<dt>Unique visitors</dt>
+					<dd>{number.format(stats.uniqueVisitors)}</dd>
+				</div>
+				<div>
+					<dt>Page views</dt>
+					<dd>{number.format(stats.pageViews)}</dd>
+				</div>
+				<div>
+					<dt>Bounce rate</dt>
+					<dd>{stats.bounceRate.toFixed(1)}%</dd>
+				</div>
+				<div>
+					<dt>Session duration</dt>
+					<dd>{duration}</dd>
+				</div>
+			</dl>
+			{stats.pageViews === 0 && (
+				<div className="analytics-empty" role="status">
+					<h2>No page views in this range</h2>
+					<p>
+						Visit a tracked page or choose another date range. Custom events
+						appear below.
+					</p>
+				</div>
+			)}
+			<TrafficChart series={stats.series} />
+			<section
+				className="analytics-table-section"
+				aria-labelledby="analytics-pages-title"
+			>
+				<div className="analytics-section-heading">
+					<h2 id="analytics-pages-title">Top pages</h2>
+					<span>Most viewed paths</span>
+				</div>
+				<div className="analytics-table-scroll">
+					<table>
+						<thead>
+							<tr>
+								<th scope="col">Page</th>
+								<th scope="col">Visitors</th>
+								<th scope="col">Page views</th>
+								<th scope="col">Trend</th>
+							</tr>
+						</thead>
+						<tbody>
+							{stats.topPages.length ? (
+								stats.topPages.map((page) => (
+									<tr key={page.path}>
+										<th scope="row" className="analytics-path">
+											{page.path}
+										</th>
+										<td>{number.format(page.visitors)}</td>
+										<td>{number.format(page.views)}</td>
+										<td>
+											<Sparkline values={page.trend} />
+											<span className="analytics-sr-only">
+												{page.trend.join(", ")} page views by day
+											</span>
+										</td>
+									</tr>
+								))
+							) : (
+								<tr>
+									<td colSpan={4}>No page traffic in this range.</td>
+								</tr>
+							)}
+						</tbody>
+					</table>
+				</div>
+			</section>
+			<div className="analytics-bottom-tables">
+				<section
+					className="analytics-table-section"
+					aria-labelledby="analytics-referrers-title"
+				>
+					<div className="analytics-section-heading">
+						<h2 id="analytics-referrers-title">Top referrers</h2>
+						<span>Where visitors came from</span>
+					</div>
+					<div className="analytics-table-scroll">
+						<table>
+							<thead>
+								<tr>
+									<th scope="col">Source</th>
+									<th scope="col">Page views</th>
+								</tr>
+							</thead>
+							<tbody>
+								{stats.topReferrers.length ? (
+									stats.topReferrers.map((referrer) => (
+										<tr key={referrer.referrer}>
+											<th scope="row" className="analytics-path">
+												{referrer.referrer || "Direct"}
+											</th>
+											<td>{number.format(referrer.views)}</td>
+										</tr>
+									))
+								) : (
+									<tr>
+										<td colSpan={2}>No referrers in this range.</td>
+									</tr>
+								)}
+							</tbody>
+						</table>
+					</div>
+				</section>
+				<section
+					className="analytics-table-section"
+					aria-labelledby="analytics-events-title"
+				>
+					<div className="analytics-section-heading">
+						<h2 id="analytics-events-title">Top custom events</h2>
+						<span>Actions visitors took</span>
+					</div>
+					<div className="analytics-table-scroll">
+						<table>
+							<thead>
+								<tr>
+									<th scope="col">Event</th>
+									<th scope="col">Count</th>
+								</tr>
+							</thead>
+							<tbody>
+								{stats.topEvents.length ? (
+									stats.topEvents.map((event) => (
+										<tr key={event.name}>
+											<th scope="row" className="analytics-path">
+												{event.name}
+											</th>
+											<td>{number.format(event.count)}</td>
+										</tr>
+									))
+								) : (
+									<tr>
+										<td colSpan={2}>No custom events in this range.</td>
+									</tr>
+								)}
+							</tbody>
+						</table>
+					</div>
+				</section>
+			</div>
+			<p className="analytics-note">
+				Anonymous sessions are held in memory. No analytics cookies are created.
+				Single-page sessions have a recorded duration of zero.
+			</p>
+		</main>
+	);
+}

package/src/plugins/analytics/client/components/pages/dashboard-page.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { lazy, useEffect, useState } from "react";
+import { ComposedRoute } from "@btst/stack/client/components";
+import { analyticsPermissions } from "../../../permissions";
+
+const Dashboard = lazy(() =>
+	import("./dashboard-page.internal").then((module) => ({
+		default: module.AnalyticsDashboardPage,
+	})),
+);
+
+function Loading() {
+	return (
+		<div className="analytics-dashboard" role="status" aria-live="polite">
+			<h1>Analytics</h1>
+			<p>Loading traffic…</p>
+		</div>
+	);
+}
+
+function BrowserDashboard() {
+	const [mounted, setMounted] = useState(false);
+	useEffect(() => setMounted(true), []);
+	return mounted ? <Dashboard /> : <Loading />;
+}
+
+function ErrorState({
+	resetErrorBoundary,
+}: {
+	resetErrorBoundary: () => void;
+}) {
+	return (
+		<div className="analytics-dashboard" role="alert">
+			<h1>Analytics unavailable</h1>
+			<p>Traffic could not be loaded. Check your access and try again.</p>
+			<button type="button" onClick={resetErrorBoundary}>
+				Try again
+			</button>
+		</div>
+	);
+}
+
+/** Dashboard route with authorization, loading and error boundaries. */
+export function AnalyticsDashboardPageComponent() {
+	return (
+		<ComposedRoute
+			path="/analytics"
+			permission={analyticsPermissions.dashboard.read({})}
+			PageComponent={BrowserDashboard}
+			ErrorComponent={ErrorState}
+			LoadingComponent={Loading}
+			onError={(error) => console.error("Analytics dashboard failed:", error)}
+		/>
+	);
+}

package/src/plugins/analytics/client/constants.ts

@@ -0,0 +1,2 @@
+/** Canonical identifier for the analytics client plugin. */
+export const ANALYTICS_PLUGIN_ID = "analytics" as const;

package/src/plugins/analytics/client/hooks/index.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { useEffect } from "react";
+import {
+	useIdentity,
+	useIdentitySourceGeneration,
+	useStack,
+} from "@btst/stack/context";
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { analyticsResources } from "../../query-keys";
+import type { AnalyticsRangeParams } from "../../types";
+import { ANALYTICS_PLUGIN_ID } from "../constants";
+
+const analytics = createResource({
+	plugin: ANALYTICS_PLUGIN_ID,
+	resources: analyticsResources,
+});
+
+function useAnalyticsPartition() {
+	const { identity, isPending, error } = useIdentity();
+	const generation = useIdentitySourceGeneration();
+	const { plugins } = useStack();
+	const api = plugins?.[ANALYTICS_PLUGIN_ID]?.api;
+	return {
+		identity,
+		generation,
+		isPending,
+		error: !!error,
+		endpoint: [api?.baseURL, api?.basePath],
+		headers: [...new Headers(api?.browserHeaders)],
+		credentials: api?.credentials,
+	};
+}
+
+/** Dashboard metrics and ranked traffic for the selected UTC range. */
+export function useDashboardStats(params: AnalyticsRangeParams = {}) {
+	const partition = useAnalyticsPartition();
+	return analytics.analyticsDashboard.stats.use([params, partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+}
+
+/** Suspense dashboard query; refetch errors reach the route's error boundary. */
+export function useSuspenseDashboardStats(params: AnalyticsRangeParams = {}) {
+	return analytics.analyticsDashboard.stats.useSuspense([
+		params,
+		useAnalyticsPartition(),
+	]);
+}
+
+/** Top pages, suitable for embedding page traffic in another plugin. */
+export function useTopPages(params: AnalyticsRangeParams = {}) {
+	const partition = useAnalyticsPartition();
+	return analytics.analyticsDashboard.pages.use([params, partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+}
+
+/** External referrers for the selected range. */
+export function useTopReferrers(params: AnalyticsRangeParams = {}) {
+	const partition = useAnalyticsPartition();
+	return analytics.analyticsDashboard.referrers.use([params, partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+}
+
+/** Custom event counts for the selected range. */
+export function useTopEvents(params: AnalyticsRangeParams = {}) {
+	const partition = useAnalyticsPartition();
+	return analytics.analyticsDashboard.events.use([params, partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+}
+
+/** Visitors active in the last five minutes, refreshed every fifteen seconds. */
+export function useRealtimeVisitors() {
+	const partition = useAnalyticsPartition();
+	const result = analytics.analyticsDashboard.realtime.use([partition], {
+		enabled: !partition.isPending && !partition.error,
+	});
+	const { refetch } = result;
+	useEffect(() => {
+		if (partition.isPending || partition.error) return;
+		const interval = setInterval(() => {
+			if (document.visibilityState === "visible") void refetch();
+		}, 15000);
+		return () => clearInterval(interval);
+	}, [refetch, partition.isPending, partition.error]);
+	return result;
+}

package/src/plugins/analytics/client/index.ts

@@ -0,0 +1,7 @@
+export { analyticsClientPlugin, type AnalyticsClientConfig } from "./plugin";
+export {
+	createAnalyticsTracker,
+	track,
+	type AnalyticsTracker,
+	type AnalyticsTrackerOptions,
+} from "./tracker";

package/src/plugins/analytics/client/plugin.tsx

@@ -0,0 +1,69 @@
+import { lazy, type ComponentType } from "react";
+import {
+	defineClientPlugin,
+	defineRoute,
+	defineRoutes,
+} from "@btst/stack/plugins/client";
+import { ANALYTICS_PLUGIN_ID } from "./constants";
+import {
+	getConfiguredAnalyticsTracker,
+	setDefaultAnalyticsTracker,
+} from "./tracker";
+
+const DashboardPage = lazy(() =>
+	import("./components/pages/dashboard-page").then((module) => ({
+		default: module.AnalyticsDashboardPageComponent,
+	})),
+);
+
+/** Options specific to the analytics client plugin. API/site settings belong on createClientStack(). */
+export interface AnalyticsClientConfig {
+	/** Automatically track rendered BTST routes. Defaults to true. */
+	tracking?: boolean;
+	/** Replace the dashboard while retaining the analytics route. */
+	pageComponents?: { dashboard?: ComponentType };
+}
+
+/** First-party page tracking and a protected, dynamic analytics dashboard. */
+export const analyticsClientPlugin = (config: AnalyticsClientConfig = {}) =>
+	defineClientPlugin({
+		id: ANALYTICS_PLUGIN_ID,
+		resolve: (runtime) => {
+			const tracker = getConfiguredAnalyticsTracker({
+				apiBaseURL: runtime.api.baseURL,
+				apiBasePath: runtime.api.basePath,
+				credentials: runtime.api.credentials,
+				// Browser runtimes contain only explicit public headers; never retain SSR request headers.
+				headers:
+					typeof window === "undefined" ? undefined : runtime.api.headers,
+			});
+			setDefaultAnalyticsTracker(tracker);
+			return {
+				hooks: {
+					onRouteRender: ({ path }: { path: string }) =>
+						config.tracking === false
+							? undefined
+							: tracker
+									.pageView(
+										typeof window === "undefined"
+											? path
+											: window.location.pathname,
+									)
+									.then(() => {}),
+				},
+				routes: () =>
+					defineRoutes(
+						{
+							analyticsDashboard: defineRoute("/analytics", {
+								page: DashboardPage,
+								meta: () => [
+									{ title: "Analytics" },
+									{ name: "robots", content: "noindex, nofollow" },
+								],
+							}),
+						},
+						{ pages: { analyticsDashboard: config.pageComponents?.dashboard } },
+					),
+			};
+		},
+	});