@btst/stack 5.1.0 → 5.2.0

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

@@ -0,0 +1,155 @@
+/** Transport configuration for tracking outside a resolved BTST client stack. */
+export interface AnalyticsTrackerOptions {
+	/** API origin; omitted for same-origin collection. */
+	apiBaseURL?: string;
+	/** API mount path, matching createBackendStack(). Defaults to /api/data. */
+	apiBasePath?: string;
+	/** Explicit Fetch credentials policy. Uses Fetch instead of a beacon when set. */
+	credentials?: RequestCredentials;
+	/** Explicit browser-safe headers. Nonempty headers require Fetch instead of a beacon. */
+	headers?: HeadersInit;
+}
+
+/** Cookie-free tracker with a session identifier held only in memory. */
+export interface AnalyticsTracker {
+	/** Record a page view, excluding query strings and fragments. */
+	pageView(path?: string): Promise<boolean>;
+	/** Record a custom event. Properties should never contain personal data. */
+	track(
+		name: string,
+		properties?: Record<string, string | number | boolean | null>,
+	): Promise<boolean>;
+}
+
+const SESSION_TIMEOUT = 30 * 60 * 1000;
+
+/** Create a tracker without React, cookies, localStorage, or third-party scripts. */
+export function createAnalyticsTracker(
+	options: AnalyticsTrackerOptions = {},
+): AnalyticsTracker {
+	let sessionId: string | undefined;
+	let lastActivity = 0;
+	let lastView: { path: string; at: number } | undefined;
+	const collectionHeaders = new Headers(options.headers);
+	const credentials = options.credentials;
+	const basePath = (options.apiBasePath ?? "/api/data").replace(
+		/^\/+|\/+$/g,
+		"",
+	);
+	const endpoint = `${(options.apiBaseURL ?? "").replace(/\/+$/, "")}${basePath ? `/${basePath}` : ""}/analytics`;
+
+	async function send(
+		kind: "pageviews" | "events",
+		data: Record<string, unknown>,
+	): Promise<boolean> {
+		if (typeof window === "undefined" || typeof navigator === "undefined")
+			return false;
+		if (navigator.doNotTrack === "1") return false;
+		try {
+			const now = Date.now();
+			if (!sessionId || now - lastActivity > SESSION_TIMEOUT)
+				sessionId = Array.from(
+					globalThis.crypto.getRandomValues(new Uint8Array(16)),
+					(byte) => byte.toString(16).padStart(2, "0"),
+				).join("");
+			lastActivity = now;
+			const body = JSON.stringify({ ...data, sessionId });
+			const headers = new Headers(collectionHeaders);
+			const hasCustomHeaders = !headers.keys().next().done;
+			headers.set("Content-Type", "application/json");
+			if (
+				credentials === undefined &&
+				!hasCustomHeaders &&
+				navigator.sendBeacon?.(
+					`${endpoint}/${kind}`,
+					new Blob([body], { type: "application/json" }),
+				)
+			)
+				return true;
+			const response = await fetch(`${endpoint}/${kind}`, {
+				method: "POST",
+				headers,
+				body,
+				keepalive: true,
+				credentials: credentials ?? "omit",
+			});
+			return response.ok;
+		} catch {
+			// Tracking must not interrupt navigation or the action being measured.
+			return false;
+		}
+	}
+
+	function pathname(path?: string): string {
+		return new URL(path || window.location.href, window.location.origin)
+			.pathname;
+	}
+
+	return {
+		async pageView(path) {
+			if (typeof window === "undefined") return false;
+			let cleanPath: string;
+			let referrer: string;
+			try {
+				cleanPath = pathname(path);
+				const referrerOrigin = document.referrer
+					? new URL(document.referrer).origin
+					: "";
+				referrer =
+					referrerOrigin === window.location.origin ? "" : referrerOrigin;
+			} catch {
+				return false;
+			}
+			const now = Date.now();
+			// Nested route boundaries and React Strict Mode can report the same render.
+			if (lastView?.path === cleanPath && now - lastView.at < 1000)
+				return false;
+			lastView = { path: cleanPath, at: now };
+			return send("pageviews", { path: cleanPath, referrer });
+		},
+		async track(name, properties) {
+			if (typeof window === "undefined") return false;
+			return send("events", { name, path: pathname(), properties });
+		},
+	};
+}
+
+let defaultTracker: AnalyticsTracker | undefined;
+const configuredTrackers = new Map<string, AnalyticsTracker>();
+
+/** @internal Share browser sessions across equivalent client stack resolutions. */
+export function getConfiguredAnalyticsTracker(
+	options: AnalyticsTrackerOptions,
+): AnalyticsTracker {
+	if (typeof window === "undefined") return createAnalyticsTracker(options);
+	const key = JSON.stringify([
+		options.apiBaseURL,
+		options.apiBasePath,
+		options.credentials,
+		[...new Headers(options.headers)],
+	]);
+	let tracker = configuredTrackers.get(key);
+	if (!tracker) {
+		tracker = createAnalyticsTracker(options);
+		configuredTrackers.set(key, tracker);
+	}
+	return tracker;
+}
+
+/** @internal Bind the browser's default track() helper to the resolved API endpoint. */
+export function setDefaultAnalyticsTracker(tracker: AnalyticsTracker): void {
+	if (typeof window !== "undefined") defaultTracker = tracker;
+}
+
+/** Track a custom event using the analytics plugin, or an explicit standalone endpoint. */
+export function track(
+	name: string,
+	properties?: Record<string, string | number | boolean | null>,
+	options?: AnalyticsTrackerOptions,
+): Promise<boolean> {
+	if (options) {
+		return getConfiguredAnalyticsTracker(options).track(name, properties);
+	}
+	defaultTracker ??= createAnalyticsTracker();
+	return defaultTracker.track(name, properties);
+}

package/src/plugins/analytics/client.css

@@ -0,0 +1,282 @@
+.analytics-dashboard {
+	--analytics-accent: #0f766e;
+	color: var(--foreground, #18181b);
+	background: var(--background, #fff);
+	max-width: 1200px;
+	margin: 0 auto;
+	padding: 32px 24px;
+	font-family: inherit;
+	font-size: 14px;
+	line-height: 1.5;
+}
+.dark .analytics-dashboard {
+	--analytics-accent: #5eead4;
+}
+.analytics-dashboard h1 {
+	margin: 0;
+	font-size: 28px;
+	font-weight: 650;
+	letter-spacing: -0.025em;
+}
+.analytics-dashboard h2 {
+	margin: 0;
+	font-size: 16px;
+	font-weight: 600;
+}
+.analytics-dashboard p {
+	margin: 6px 0 0;
+}
+.analytics-header,
+.analytics-toolbar,
+.analytics-section-heading {
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	gap: 16px;
+}
+.analytics-header p,
+.analytics-live,
+.analytics-section-heading span,
+.analytics-note,
+.analytics-chart-labels,
+.analytics-custom-range > span {
+	color: var(--muted-foreground, #71717a);
+}
+.analytics-live strong {
+	color: var(--analytics-accent);
+	font-variant-numeric: tabular-nums;
+}
+.analytics-toolbar {
+	margin-top: 28px;
+	flex-wrap: wrap;
+}
+.analytics-dashboard button {
+	border: 1px solid var(--border, #e4e4e7);
+	background: var(--background, #fff);
+	color: inherit;
+	border-radius: 6px;
+	padding: 8px 14px;
+	font: inherit;
+	cursor: pointer;
+	min-height: 40px;
+}
+.analytics-dashboard button:hover {
+	background: var(--muted, #f4f4f5);
+}
+.analytics-dashboard button:disabled {
+	opacity: 0.6;
+	cursor: wait;
+}
+.analytics-dashboard :is(button, input, summary):focus-visible {
+	outline: 2px solid var(--analytics-accent);
+	outline-offset: 3px;
+}
+.analytics-ranges {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 4px;
+}
+.analytics-ranges button {
+	border-color: transparent;
+}
+.analytics-ranges button[aria-pressed="true"] {
+	background: var(--foreground, #18181b);
+	color: var(--background, #fff);
+}
+.analytics-custom-range {
+	margin-top: 16px;
+	display: flex;
+	align-items: end;
+	flex-wrap: wrap;
+	gap: 12px;
+}
+.analytics-custom-range label {
+	display: grid;
+	gap: 5px;
+}
+.analytics-custom-range input {
+	min-height: 40px;
+	min-width: 0;
+	padding: 7px 10px;
+	border: 1px solid var(--border, #e4e4e7);
+	border-radius: 6px;
+	color: inherit;
+	background: inherit;
+	font: inherit;
+}
+.analytics-error {
+	color: var(--destructive, #b91c1c);
+}
+.analytics-metrics {
+	margin: 24px 0 32px;
+	padding: 20px 0;
+	display: grid;
+	grid-template-columns: repeat(4, minmax(0, 1fr));
+	border-block: 1px solid var(--border, #e4e4e7);
+}
+.analytics-metrics > div {
+	padding-inline: 24px;
+	border-inline-start: 1px solid var(--border, #e4e4e7);
+}
+.analytics-metrics > div:first-child {
+	padding-inline-start: 0;
+	border-inline-start: 0;
+}
+.analytics-metrics dt {
+	color: var(--muted-foreground, #71717a);
+}
+.analytics-metrics dd {
+	margin: 5px 0 0;
+	font-size: 30px;
+	font-weight: 600;
+	font-variant-numeric: tabular-nums;
+	letter-spacing: -0.035em;
+}
+.analytics-traffic {
+	margin-bottom: 32px;
+}
+.analytics-section-heading {
+	margin-bottom: 16px;
+	align-items: baseline;
+}
+.analytics-section-heading span {
+	font-size: 12px;
+}
+.analytics-chart {
+	width: 100%;
+	height: auto;
+	min-height: 160px;
+	max-height: 250px;
+	display: block;
+	overflow: visible;
+	color: var(--analytics-accent);
+}
+.analytics-chart-area {
+	fill: var(--analytics-accent);
+	opacity: 0.1;
+}
+.analytics-chart-rule {
+	stroke: var(--border, #e4e4e7);
+}
+.analytics-chart-labels {
+	display: flex;
+	justify-content: space-between;
+	font-size: 12px;
+}
+.analytics-chart-data {
+	margin-top: 12px;
+	font-size: 12px;
+}
+.analytics-chart-data summary {
+	cursor: pointer;
+	width: fit-content;
+}
+.analytics-table-section {
+	min-width: 0;
+	margin-bottom: 28px;
+}
+.analytics-table-scroll {
+	overflow-x: auto;
+}
+.analytics-dashboard table {
+	border-collapse: collapse;
+	width: 100%;
+	font-variant-numeric: tabular-nums;
+}
+.analytics-dashboard th,
+.analytics-dashboard td {
+	padding: 12px 10px;
+	border-bottom: 1px solid var(--border, #e4e4e7);
+	text-align: right;
+}
+.analytics-dashboard :is(th, td):first-child {
+	padding-left: 0;
+	text-align: left;
+}
+.analytics-dashboard :is(th, td):last-child {
+	padding-right: 0;
+}
+.analytics-dashboard thead th {
+	color: var(--muted-foreground, #71717a);
+	font-weight: 400;
+	font-size: 12px;
+}
+.analytics-dashboard tbody th {
+	font-weight: 500;
+}
+.analytics-path {
+	overflow-wrap: anywhere;
+	max-width: 28rem;
+}
+.analytics-sparkline {
+	color: var(--analytics-accent);
+	width: 96px;
+	height: 28px;
+	display: inline-block;
+	vertical-align: middle;
+}
+.analytics-bottom-tables {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	gap: 40px;
+}
+.analytics-empty {
+	padding: 20px;
+	margin-bottom: 24px;
+	background: var(--muted, #f4f4f5);
+	border-radius: 8px;
+}
+.analytics-note {
+	font-size: 12px;
+	max-width: 75ch;
+}
+.analytics-sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip-path: inset(50%);
+	white-space: nowrap;
+	border: 0;
+}
+@media (max-width: 640px) {
+	.analytics-dashboard {
+		padding: 24px 16px;
+	}
+	.analytics-header {
+		align-items: start;
+		flex-direction: column;
+		gap: 10px;
+	}
+	.analytics-metrics {
+		grid-template-columns: repeat(2, minmax(0, 1fr));
+		gap: 24px 0;
+	}
+	.analytics-metrics > div {
+		padding-inline: 16px;
+	}
+	.analytics-metrics > div:nth-child(odd) {
+		padding-inline-start: 0;
+		border-inline-start: 0;
+	}
+	.analytics-metrics dd {
+		font-size: 26px;
+	}
+	.analytics-bottom-tables {
+		grid-template-columns: minmax(0, 1fr);
+		gap: 0;
+	}
+	.analytics-section-heading {
+		flex-wrap: wrap;
+		gap: 4px;
+	}
+	.analytics-sparkline {
+		width: 64px;
+	}
+	.analytics-dashboard td,
+	.analytics-dashboard th {
+		padding: 10px 6px;
+	}
+}

package/src/plugins/analytics/db.ts

@@ -0,0 +1,27 @@
+import { createDbPlugin } from "@btst/db";
+
+/** Analytics stores no cookies, raw IP addresses, or raw user-agent strings. */
+export const analyticsSchema = createDbPlugin("analytics", {
+	pageView: {
+		modelName: "pageView",
+		fields: {
+			path: { type: "string", required: true },
+			referrer: { type: "string", required: false },
+			country: { type: "string", required: false },
+			device: { type: "string", required: false },
+			browser: { type: "string", required: false },
+			sessionId: { type: "string", required: true },
+			timestamp: { type: "date", defaultValue: () => new Date() },
+		},
+	},
+	customEvent: {
+		modelName: "customEvent",
+		fields: {
+			name: { type: "string", required: true },
+			path: { type: "string", required: true },
+			properties: { type: "string", required: false },
+			sessionId: { type: "string", required: true },
+			timestamp: { type: "date", defaultValue: () => new Date() },
+		},
+	},
+});

package/src/plugins/analytics/permissions.ts

@@ -0,0 +1,14 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+/** Browser-safe permission descriptors for public ingestion and private analytics. */
+export const analyticsPermissions = definePermissions("analytics", {
+	events: {
+		ingest: permission(z.object({ kind: z.enum(["pageview", "event"]) })),
+		cleanup: permission(z.object({})),
+	},
+	dashboard: {
+		read: permission(z.object({})),
+		export: permission(z.object({})),
+	},
+});

package/src/plugins/analytics/query-keys.ts

@@ -0,0 +1,71 @@
+import {
+	createResourceQueryKeys,
+	type ResourceClient,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type {
+	AnalyticsDashboardStats,
+	AnalyticsRangeParams,
+	AnalyticsTopPage,
+	AnalyticsTopReferrer,
+	AnalyticsTopEvent,
+} from "./types";
+
+const rangeQuery = (
+	params: AnalyticsRangeParams = {},
+	_partition?: unknown,
+) => ({ ...params, range: params.range ?? "7d" });
+const rangeKey = (params: AnalyticsRangeParams = {}, partition?: unknown) => [
+	params,
+	partition,
+];
+
+/** Shared declarations for dynamic dashboard hooks and server query consumers. */
+export const analyticsResources = {
+	analyticsDashboard: {
+		queries: {
+			stats: {
+				path: "/analytics/dashboard",
+				query: rangeQuery,
+				key: rangeKey,
+				select: (data: unknown): AnalyticsDashboardStats =>
+					data as AnalyticsDashboardStats,
+			},
+			realtime: {
+				path: "/analytics/realtime",
+				key: (partition?: unknown) => [partition],
+				select: (data: unknown): { visitors: number } =>
+					data as { visitors: number },
+			},
+			pages: {
+				path: "/analytics/pages",
+				query: rangeQuery,
+				key: rangeKey,
+				select: (data: unknown): AnalyticsTopPage[] =>
+					data as AnalyticsTopPage[],
+			},
+			referrers: {
+				path: "/analytics/referrers",
+				query: rangeQuery,
+				key: rangeKey,
+				select: (data: unknown): AnalyticsTopReferrer[] =>
+					data as AnalyticsTopReferrer[],
+			},
+			events: {
+				path: "/analytics/events",
+				query: rangeQuery,
+				key: rangeKey,
+				select: (data: unknown): AnalyticsTopEvent[] =>
+					data as AnalyticsTopEvent[],
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+/** Construct analytics query options using the same keys as the browser hooks. */
+export function createAnalyticsQueryKeys(
+	client: ResourceClient,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, analyticsResources, headers);
+}

package/src/plugins/analytics/schemas.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+
+const pathSchema = z
+	.string()
+	.min(1)
+	.max(2048)
+	.startsWith("/")
+	.refine(
+		(path) => !path.startsWith("//") && !/[\\\u0000-\u001f]/.test(path),
+		"Use a local pathname",
+	)
+	.transform((path) => path.split(/[?#]/)[0]!);
+const dateSchema = z.union([z.iso.date(), z.iso.datetime({ offset: true })]);
+
+/** Validated ingestion body. Server time, device, browser and hashed session are authoritative. */
+export const AnalyticsPageViewSchema = z.object({
+	path: pathSchema,
+	referrer: z.string().max(2048).optional(),
+	sessionId: z.string().min(16).max(128),
+});
+
+/** Custom properties are flat JSON values with bounded size. */
+export const AnalyticsEventSchema = AnalyticsPageViewSchema.omit({
+	referrer: true,
+}).extend({
+	name: z.string().trim().min(1).max(100),
+	properties: z
+		.record(
+			z.string().max(100),
+			z.union([
+				z.string().max(1000),
+				z.number().finite(),
+				z.boolean(),
+				z.null(),
+			]),
+		)
+		.refine(
+			(value) => JSON.stringify(value).length <= 4096,
+			"Properties exceed 4096 characters",
+		)
+		.optional(),
+});
+
+/** Analytics queries use inclusive start and exclusive end; date-only end includes that day. */
+export const AnalyticsRangeSchema = z
+	.object({
+		range: z.enum(["today", "7d", "30d", "custom"]).default("7d"),
+		start: dateSchema.optional(),
+		end: dateSchema.optional(),
+		path: pathSchema.optional(),
+		limit: z.coerce.number().int().min(1).max(100).default(10),
+	})
+	.superRefine((value, ctx) => {
+		if (value.range === "custom" && (!value.start || !value.end))
+			ctx.addIssue({
+				code: "custom",
+				message: "Custom ranges require start and end",
+				path: ["start"],
+			});
+		if (
+			value.start &&
+			value.end &&
+			Date.parse(value.start) > Date.parse(value.end)
+		)
+			ctx.addIssue({
+				code: "custom",
+				message: "Start must be before end",
+				path: ["end"],
+			});
+		if (
+			value.start &&
+			value.end &&
+			Date.parse(value.end) - Date.parse(value.start) > 366 * 86400000
+		)
+			ctx.addIssue({
+				code: "custom",
+				message: "Date range cannot exceed 366 days",
+				path: ["end"],
+			});
+	});

package/src/plugins/analytics/style.css

@@ -0,0 +1,2 @@
+@import "./client.css";
+@source "./client/**/*.{ts,tsx}";

package/src/plugins/analytics/types.ts

@@ -0,0 +1,70 @@
+/** Date filters shared by the dashboard and embeddable aggregation API. Dates use UTC. */
+export type AnalyticsRangeParams = {
+	range?: "today" | "7d" | "30d" | "custom";
+	start?: string;
+	end?: string;
+	path?: string;
+	limit?: number;
+};
+
+/** One UTC day of traffic. */
+export type AnalyticsSeriesPoint = {
+	date: string;
+	pageViews: number;
+	visitors: number;
+};
+
+/** Page traffic and daily page-view counts for a sparkline. */
+export type AnalyticsTopPage = {
+	path: string;
+	views: number;
+	visitors: number;
+	trend: number[];
+};
+
+/** External referrer host and its traffic. */
+export type AnalyticsTopReferrer = {
+	referrer: string;
+	views: number;
+	visitors: number;
+};
+
+/** Custom event name and number of occurrences. */
+export type AnalyticsTopEvent = {
+	name: string;
+	count: number;
+};
+
+/** Aggregated traffic. Duration is in seconds and bounce rate is a percentage. */
+export type AnalyticsDashboardStats = {
+	uniqueVisitors: number;
+	pageViews: number;
+	bounceRate: number;
+	sessionDuration: number;
+	series: AnalyticsSeriesPoint[];
+	topPages: AnalyticsTopPage[];
+	topReferrers: AnalyticsTopReferrer[];
+	topEvents: AnalyticsTopEvent[];
+};
+
+/** Raw page-view record. Session IDs are irreversibly hashed before insertion. */
+export type AnalyticsPageView = {
+	id: string;
+	path: string;
+	referrer?: string | null;
+	country?: string | null;
+	device?: string | null;
+	browser?: string | null;
+	sessionId: string;
+	timestamp: Date;
+};
+
+/** Raw custom-event record. Properties contain serialized JSON. */
+export type AnalyticsCustomEvent = {
+	id: string;
+	name: string;
+	path: string;
+	properties?: string | null;
+	sessionId: string;
+	timestamp: Date;
+};