@tdhftw/emdash-plugin-umami 0.0.0-stage → 0.1.2

package/src/admin/Widget.tsx

@@ -0,0 +1,75 @@
+import { Loader } from "@cloudflare/kumo";
+
+import type { Overview } from "../shared/stats.js";
+import { change, formatNumber } from "./format.js";
+import { useActive, useOverview } from "./hooks.js";
+
+/** Tiny dependency-free sparkline, so the dashboard never loads the charting library. */
+function Sparkline({ values }: { values: number[] }) {
+	const w = 240;
+	const h = 40;
+	const max = Math.max(1, ...values);
+	const step = values.length > 1 ? w / (values.length - 1) : w;
+	const points = values.map((v, i) => `${(i * step).toFixed(1)},${(h - (v / max) * (h - 2) - 1).toFixed(1)}`).join(" ");
+	return (
+		<svg viewBox={`0 0 ${w} ${h}`} width="100%" height={h} preserveAspectRatio="none" aria-hidden>
+			<polyline points={points} fill="none" stroke="var(--color-kumo-brand)" strokeWidth={2} vectorEffect="non-scaling-stroke" />
+		</svg>
+	);
+}
+
+function Stat({ label, value, previous }: { label: string; value: number; previous: number }) {
+	const c = change(value, previous);
+	const pct = c === null ? null : Math.round(c * 100);
+	return (
+		<div>
+			<div className="text-xs text-kumo-subtle">{label}</div>
+			<div className="text-xl font-semibold tabular-nums">{formatNumber(value)}</div>
+			{pct !== null && pct !== 0 ? (
+				<div className={`text-xs tabular-nums ${pct > 0 ? "text-kumo-success" : "text-kumo-danger"}`}>
+					{pct > 0 ? "▲" : "▼"} {Math.abs(pct)}%
+				</div>
+			) : null}
+		</div>
+	);
+}
+
+function Summary({ overview }: { overview: Overview }) {
+	const active = useActive();
+	return (
+		<div className="space-y-3">
+			<div style={{ display: "grid", gap: 12, gridTemplateColumns: "repeat(3, minmax(0, 1fr))" }}>
+				<Stat label="Visitors" value={overview.totals.visitors} previous={overview.previous.visitors} />
+				<Stat label="Pageviews" value={overview.totals.pageviews} previous={overview.previous.pageviews} />
+				<div>
+					<div className="text-xs text-kumo-subtle">Active now</div>
+					<div className="text-xl font-semibold tabular-nums">{active.data ? active.data.visitors : "–"}</div>
+				</div>
+			</div>
+			<Sparkline values={overview.series.map((p) => p.visitors)} />
+			<div className="flex items-center justify-between text-xs text-kumo-subtle">
+				<span>Visitors, last 7 days</span>
+				<a href={`/_emdash/admin/plugins/umami/`} className="underline">
+					Open Analytics
+				</a>
+			</div>
+		</div>
+	);
+}
+
+export function OverviewWidget() {
+	const overview = useOverview("7d");
+	if (overview.data) return <Summary overview={overview.data} />;
+	if (overview.error) {
+		return (
+			<p className="text-sm text-kumo-subtle">
+				{(overview.error as Error).message}{" "}
+				<a href="/_emdash/admin/plugins/umami/#settings" className="underline">
+					Settings
+				</a>
+			</p>
+		);
+	}
+	return <Loader />;
+}
+

package/src/admin/api.ts

@@ -0,0 +1,14 @@
+import { apiFetch, parseApiResponse } from "emdash/plugin-utils";
+
+import { API_BASE } from "../shared/constants.js";
+
+/** GET or POST a plugin route and unwrap EmDash's `{ success, data }` envelope. */
+export async function callRoute<T>(route: string, body?: unknown): Promise<T> {
+	const response = await apiFetch(
+		`${API_BASE}/${route}`,
+		body === undefined
+			? undefined
+			: { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) },
+	);
+	return parseApiResponse<T>(response, "The Umami plugin did not answer");
+}

package/src/admin/chartOptions.ts

@@ -0,0 +1,54 @@
+// Kept free of ECharts and Kumo imports so it can be unit-tested and stays out of shared chunks.
+import type { Overview } from "../shared/stats.js";
+
+const dayLabel = new Intl.DateTimeFormat(undefined, { timeZone: "UTC", day: "numeric", month: "short" });
+
+/**
+ * Axis label for a series bucket. Bucket labels are already in the site's zone ("2026-10-21" or
+ * "2026-10-21 14:00"), so they are reformatted as text rather than from `t`, which a time axis
+ * would place in the browser's zone.
+ */
+export function bucketLabel(label: string, unit: Overview["unit"]): string {
+	if (unit === "hour") return label.slice(11, 16);
+	const [y, m, d] = label.split("-").map(Number);
+	return dayLabel.format(Date.UTC(y!, m! - 1, d!));
+}
+
+/**
+ * ECharts options for the Overview chart. A category axis with one bar slot per bucket, and the
+ * two series drawn over each other (`barGap: "-100%"`) rather than stacked: visitors never exceed
+ * pageviews, so each bar's height is its real count, as in Umami's own chart.
+ */
+export function chartOptions(overview: Overview, colors: { pageviews: string; visitors: string }) {
+	const series = (name: string, color: string, values: number[]) => ({
+		type: "bar" as const,
+		name,
+		color,
+		data: values,
+		barGap: "-100%",
+		barMaxWidth: 24,
+		emphasis: { focus: "series" as const },
+	});
+	return {
+		aria: { enabled: true, label: { description: `Pageviews and visitors per ${overview.unit}` } },
+		backgroundColor: "transparent",
+		legend: { top: 0, right: 0, icon: "roundRect", itemWidth: 10, itemHeight: 10 },
+		tooltip: { trigger: "axis" as const, axisPointer: { type: "shadow" as const } },
+		grid: { left: 8, right: 8, top: 32, bottom: 0, containLabel: true },
+		xAxis: {
+			type: "category" as const,
+			data: overview.series.map((p) => bucketLabel(p.label, overview.unit)),
+			axisTick: { alignWithLabel: true },
+			axisLabel: { hideOverlap: true },
+		},
+		yAxis: {
+			type: "value" as const,
+			minInterval: 1,
+			splitLine: { lineStyle: { type: "dashed" as const } },
+		},
+		series: [
+			series("Pageviews", colors.pageviews, overview.series.map((p) => p.pageviews)),
+			series("Visitors", colors.visitors, overview.series.map((p) => p.visitors)),
+		],
+	};
+}

package/src/admin/format.ts

@@ -0,0 +1,119 @@
+import type { MetricType, Range, Totals } from "../shared/stats.js";
+
+const whole = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 });
+const compact = new Intl.NumberFormat(undefined, { notation: "compact", maximumFractionDigits: 1 });
+
+export function formatNumber(n: number): string {
+	return n >= 10_000 ? compact.format(n) : whole.format(n);
+}
+
+export function formatDuration(seconds: number): string {
+	const s = Math.round(seconds);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+	return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
+}
+
+export function formatPercent(ratio: number): string {
+	return `${Math.round(ratio * 100)}%`;
+}
+
+export interface Kpi {
+	key: string;
+	label: string;
+	value: number;
+	previous: number;
+	format: (n: number) => string;
+	/** Bounce rate going down is good. */
+	lowerIsBetter?: boolean;
+}
+
+export function kpis(t: Totals, p: Totals): Kpi[] {
+	const bounceRate = (x: Totals) => (x.visits > 0 ? Math.min(x.bounces, x.visits) / x.visits : 0);
+	const avgVisit = (x: Totals) => (x.visits > 0 ? x.totaltime / x.visits : 0);
+	return [
+		{ key: "visitors", label: "Visitors", value: t.visitors, previous: p.visitors, format: formatNumber },
+		{ key: "visits", label: "Visits", value: t.visits, previous: p.visits, format: formatNumber },
+		{ key: "pageviews", label: "Pageviews", value: t.pageviews, previous: p.pageviews, format: formatNumber },
+		{ key: "bounce", label: "Bounce rate", value: bounceRate(t), previous: bounceRate(p), format: formatPercent, lowerIsBetter: true },
+		{ key: "duration", label: "Visit duration", value: avgVisit(t), previous: avgVisit(p), format: formatDuration },
+	];
+}
+
+/** Relative change, or null when there is nothing to compare against. */
+export function change(value: number, previous: number): number | null {
+	if (previous <= 0) return null;
+	return (value - previous) / previous;
+}
+
+export const RANGE_LABELS: Record<Range, string> = {
+	"24h": "24 hours",
+	"7d": "7 days",
+	"30d": "30 days",
+	"90d": "90 days",
+};
+
+export const METRIC_TITLES: Record<MetricType, string> = {
+	path: "Pages",
+	referrer: "Referrers",
+	country: "Countries",
+	browser: "Browsers",
+	os: "Operating systems",
+	device: "Devices",
+	event: "Events",
+};
+
+const regionNames = (() => {
+	try {
+		return new Intl.DisplayNames(undefined, { type: "region" });
+	} catch {
+		return null;
+	}
+})();
+
+const BROWSERS: Record<string, string> = {
+	chrome: "Chrome",
+	crios: "Chrome (iOS)",
+	firefox: "Firefox",
+	fxios: "Firefox (iOS)",
+	safari: "Safari",
+	ios: "Safari (iOS)",
+	"ios-webview": "iOS web view",
+	edge: "Edge",
+	"edge-chromium": "Edge",
+	"edge-ios": "Edge (iOS)",
+	opera: "Opera",
+	samsung: "Samsung Internet",
+	"chromium-webview": "Android web view",
+	facebook: "Facebook",
+	instagram: "Instagram",
+	brave: "Brave",
+};
+
+function capitalize(s: string) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function metricLabel(type: MetricType, label: string): string {
+	if (label === "(none)") {
+		return type === "referrer" ? "Direct or unknown" : "Unknown";
+	}
+	if (type === "country") {
+		try {
+			return regionNames?.of(label.toUpperCase()) ?? label;
+		} catch {
+			return label;
+		}
+	}
+	if (type === "browser") return BROWSERS[label] ?? capitalize(label);
+	if (type === "device") return capitalize(label);
+	return label;
+}
+
+export function relativeTime(t: number, now = Date.now()): string {
+	const seconds = Math.max(0, Math.round((now - t) / 1000));
+	if (seconds < 60) return "just now";
+	const minutes = Math.round(seconds / 60);
+	return minutes === 1 ? "1 minute ago" : `${minutes} minutes ago`;
+}

package/src/admin/hooks.ts

@@ -0,0 +1,74 @@
+import { useQuery } from "@tanstack/react-query";
+import * as React from "react";
+
+import type { StatsResult } from "../shared/api-types.js";
+import { RANGES, type Active, type Overview, type Range } from "../shared/stats.js";
+import { callRoute } from "./api.js";
+
+export function viewerTimeZone(): string {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+	} catch {
+		return "UTC";
+	}
+}
+
+/** Unwraps `{ ok: false }` results into errors so React Query sees them as failures. */
+async function unwrap<T>(route: string): Promise<T> {
+	const result = await callRoute<StatsResult<T>>(route);
+	if (!result.ok) throw Object.assign(new Error(result.message), { code: result.code });
+	return result.data;
+}
+
+export function useOverview(range: Range) {
+	const tz = viewerTimeZone();
+	return useQuery({
+		queryKey: ["plugin-umami", "overview", range, tz],
+		queryFn: () => unwrap<Overview>(`overview?range=${range}&tz=${encodeURIComponent(tz)}`),
+		placeholderData: (previous) => previous,
+	});
+}
+
+export function useActive() {
+	return useQuery({
+		queryKey: ["plugin-umami", "active"],
+		queryFn: () => unwrap<Active>("active"),
+		refetchInterval: 30_000,
+		refetchIntervalInBackground: false,
+	});
+}
+
+const RANGE_KEY = "plugin-umami:range";
+
+/** Selected range, remembered per browser. */
+export function useRange(): [Range, (range: Range) => void] {
+	const [range, setRange] = React.useState<Range>(() => {
+		try {
+			const saved = window.localStorage.getItem(RANGE_KEY);
+			return (RANGES as readonly string[]).includes(saved ?? "") ? (saved as Range) : "7d";
+		} catch {
+			return "7d";
+		}
+	});
+	const choose = React.useCallback((next: Range) => {
+		setRange(next);
+		try {
+			window.localStorage.setItem(RANGE_KEY, next);
+		} catch {
+			// Storage can be unavailable; the choice then lasts for this page view.
+		}
+	}, []);
+	return [range, choose];
+}
+
+/** Follows the admin's light/dark switch, which lives on <html data-mode>. */
+export function useDarkMode(): boolean {
+	const read = () => typeof document !== "undefined" && document.documentElement.getAttribute("data-mode") === "dark";
+	const [dark, setDark] = React.useState(read);
+	React.useEffect(() => {
+		const observer = new MutationObserver(() => setDark(read()));
+		observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-mode", "class"] });
+		return () => observer.disconnect();
+	}, []);
+	return dark;
+}

package/src/admin/index.tsx

@@ -0,0 +1,13 @@
+import type { PluginAdminExports } from "emdash";
+
+import { AnalyticsPage } from "./AnalyticsPage.js";
+import { withQueryClient } from "./query.js";
+import { OverviewWidget } from "./Widget.js";
+
+export const pages: PluginAdminExports["pages"] = {
+	"/": withQueryClient(AnalyticsPage),
+};
+
+export const widgets: PluginAdminExports["widgets"] = {
+	"umami-overview": withQueryClient(OverviewWidget),
+};

package/src/admin/query.tsx

@@ -0,0 +1,29 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ComponentType } from "react";
+
+/**
+ * The plugin brings its own QueryClient instead of using the admin's.
+ *
+ * In `astro dev`, EmDash pre-bundles @emdash-cms/admin with private copies of @tanstack/react-query
+ * and @lingui/react, so a plugin that imports those packages gets different module instances and
+ * cannot see the admin's providers ("useLingui hook was used without I18nProvider"). A production
+ * build shares one copy, but relying on that would break local development. So: no host-context
+ * hooks in plugin components; wrap each exported page and widget with this provider instead.
+ */
+const queryClient = new QueryClient({
+	defaultOptions: {
+		queries: { staleTime: 60_000, retry: 1, refetchOnWindowFocus: false },
+	},
+});
+
+export function withQueryClient<P extends object>(Component: ComponentType<P>): ComponentType<P> {
+	function WithQueryClient(props: P) {
+		return (
+			<QueryClientProvider client={queryClient}>
+				<Component {...props} />
+			</QueryClientProvider>
+		);
+	}
+	WithQueryClient.displayName = `WithQueryClient(${Component.displayName ?? Component.name})`;
+	return WithQueryClient;
+}

package/src/shared/api-types.ts

@@ -0,0 +1,43 @@
+/** Route payloads shared by the server routes and the admin UI (which ships as source). */
+import type { UmamiSettingsValues } from "./settings-types.js";
+
+export type UmamiErrorCode =
+	| "not-configured"
+	| "unauthorized"
+	| "forbidden"
+	| "not-found"
+	| "rate-limited"
+	| "unreachable"
+	| "upstream";
+
+export interface UmamiWebsite {
+	id: string;
+	name: string;
+	domain: string | null;
+}
+
+/** Settings as the admin sees them: everything except secret values. */
+export interface SettingsView {
+	values: UmamiSettingsValues;
+	secretsSet: { apiKey: boolean; password: boolean };
+}
+
+export type ConnectionTestResult =
+	| { ok: true; websites: UmamiWebsite[]; website: UmamiWebsite | null }
+	| { ok: false; code: UmamiErrorCode; message: string };
+
+export type StatsResult<T> = { ok: true; data: T } | { ok: false; code: UmamiErrorCode; message: string };
+
+/** Body of `settings/save`. Secrets: a string replaces, null clears, omitted keeps. */
+export interface SaveSettingsInput {
+	hosting?: "self-hosted" | "cloud";
+	baseUrl?: string | null;
+	region?: "default" | "us" | "eu";
+	authMode?: "apiKey" | "password";
+	apiKey?: string | null;
+	username?: string | null;
+	password?: string | null;
+	websiteId?: string | null;
+	injectScript?: boolean;
+	scriptUrl?: string | null;
+}

package/src/shared/constants.ts

@@ -0,0 +1,35 @@
+/** Plugin id. One URL segment: routes mount at /_emdash/api/plugins/umami/<route>. */
+export const PLUGIN_ID = "umami";
+
+/** Keep in sync with package.json; test/plugin.test.ts enforces it. */
+export const PLUGIN_VERSION = "0.1.2";
+
+export const PACKAGE_NAME = "@tdhftw/emdash-plugin-umami";
+
+export const API_BASE = `/_emdash/api/plugins/${PLUGIN_ID}`;
+
+export type Hosting = "self-hosted" | "cloud";
+
+/**
+ * Umami Cloud support is implemented but not yet verified against a Cloud account, so it is
+ * switched off for 0.1.x: the option shows as disabled and the server refuses to save it.
+ * Planned for 0.2.0.
+ */
+export const CLOUD_ENABLED = false;
+export type AuthMode = "apiKey" | "password";
+export type CloudRegion = "default" | "us" | "eu";
+
+/** Shape returned by the `status` route. Shared by server and admin. */
+export interface StatusResponse {
+	configured: boolean;
+	/** Settings that still need a value before the plugin can query Umami. */
+	missing: string[];
+	hosting: Hosting;
+	authMode: AuthMode;
+	websiteId: string | null;
+	/** Origin of the Umami dashboard, for "open in Umami" links. Never contains credentials. */
+	dashboardUrl: string | null;
+	injectScript: boolean;
+	/** Whether the host handed this plugin a ctx.http client. */
+	hasHttp: boolean;
+}

package/src/shared/settings-types.ts

@@ -0,0 +1,17 @@
+import type { AuthMode, CloudRegion, Hosting } from "./constants.js";
+
+export interface UmamiSettingsValues {
+	hosting: Hosting;
+	baseUrl: string | null;
+	region: CloudRegion;
+	authMode: AuthMode;
+	username: string | null;
+	websiteId: string | null;
+	injectScript: boolean;
+	scriptUrl: string | null;
+}
+
+export interface UmamiSettings extends UmamiSettingsValues {
+	apiKey: string | null;
+	password: string | null;
+}

package/src/shared/stats.ts

@@ -0,0 +1,52 @@
+/** Stats shapes shared by the server routes and the admin UI. */
+
+export const RANGES = ["24h", "7d", "30d", "90d"] as const;
+export type Range = (typeof RANGES)[number];
+
+export const METRIC_TYPES = ["path", "referrer", "country", "browser", "os", "device", "event"] as const;
+export type MetricType = (typeof METRIC_TYPES)[number];
+
+export interface Totals {
+	pageviews: number;
+	visitors: number;
+	visits: number;
+	bounces: number;
+	/** Total visit duration in seconds. */
+	totaltime: number;
+}
+
+export interface SeriesPoint {
+	/** Bucket start as a wall-clock label in the requested time zone: "2026-09-28" or "2026-09-28 14:00". */
+	label: string;
+	/** Bucket start as epoch milliseconds (UTC instant), for charting. */
+	t: number;
+	pageviews: number;
+	visitors: number;
+}
+
+export interface MetricRow {
+	label: string;
+	value: number;
+}
+
+export interface Overview {
+	websiteId: string;
+	range: Range;
+	unit: "hour" | "day";
+	timezone: string;
+	startAt: number;
+	endAt: number;
+	totals: Totals;
+	/** Same-length period immediately before this one. */
+	previous: Totals;
+	series: SeriesPoint[];
+	top: Record<MetricType, MetricRow[]>;
+	fetchedAt: number;
+	/** True when Umami could not be reached and this is an older cached copy. */
+	stale: boolean;
+}
+
+export interface Active {
+	visitors: number;
+	fetchedAt: number;
+}

package/src/shared/tracker.ts

@@ -0,0 +1,10 @@
+import type { Hosting } from "./constants.js";
+
+export const CLOUD_SCRIPT_URL = "https://cloud.umami.is/script.js";
+
+/** The tracker script a site should load: the custom URL if set, else the hosting default. */
+export function defaultScriptUrl(hosting: Hosting, baseUrl: string | null, scriptUrl: string | null): string | null {
+	if (scriptUrl) return scriptUrl;
+	if (hosting === "cloud") return CLOUD_SCRIPT_URL;
+	return baseUrl ? `${baseUrl.replace(/\/+$/, "").replace(/\/api$/, "")}/script.js` : null;
+}