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

package/dist/index.js

@@ -0,0 +1,827 @@
+import { definePlugin } from "emdash";
+import { z } from "astro/zod";
+//#region src/cache.ts
+/**
+* Returns a cached value younger than `maxAgeMs`, otherwise loads a fresh one. If loading fails and
+* any cached copy exists, that copy is returned as stale instead of failing the request.
+*/
+async function cached(kv, key, maxAgeMs, load, now = Date.now()) {
+	const entry = await kv.get(key);
+	if (entry && now - entry.at < maxAgeMs) return {
+		value: entry.value,
+		stale: false
+	};
+	try {
+		const value = await load();
+		await kv.set(key, {
+			at: now,
+			value
+		});
+		return {
+			value,
+			stale: false
+		};
+	} catch (error) {
+		if (entry) return {
+			value: entry.value,
+			stale: true
+		};
+		throw error;
+	}
+}
+//#endregion
+//#region src/shared/constants.ts
+/** Plugin id. One URL segment: routes mount at /_emdash/api/plugins/umami/<route>. */
+const PLUGIN_ID = "umami";
+/** Keep in sync with package.json; test/plugin.test.ts enforces it. */
+const PLUGIN_VERSION = "0.1.3";
+const PACKAGE_NAME = "@tdhftw/emdash-plugin-umami";
+//#endregion
+//#region src/settings.ts
+/**
+* Settings form schema. EmDash renders it under Plugins → Umami → settings; `secret` fields are
+* encrypted with EMDASH_ENCRYPTION_KEY and never sent back to the browser. Defaults only fill the
+* form, they are not persisted, so readSettings() applies the same fallbacks.
+*/
+const settingsSchema = {
+	hosting: {
+		type: "select",
+		label: "Hosting",
+		description: "Tip: Analytics → Settings in the sidebar has a guided setup with a connection test and a website picker.",
+		options: [{
+			value: "self-hosted",
+			label: "Self-hosted Umami"
+		}, ...[]],
+		default: "self-hosted"
+	},
+	baseUrl: {
+		type: "url",
+		label: "Umami URL (self-hosted)",
+		placeholder: "https://stats.example.com"
+	},
+	region: {
+		type: "select",
+		label: "Region (Umami Cloud, coming in 0.2.0)",
+		options: [
+			{
+				value: "default",
+				label: "Account default"
+			},
+			{
+				value: "us",
+				label: "United States"
+			},
+			{
+				value: "eu",
+				label: "European Union"
+			}
+		],
+		default: "default"
+	},
+	authMode: {
+		type: "select",
+		label: "Sign in with",
+		options: [{
+			value: "apiKey",
+			label: "API key"
+		}, {
+			value: "password",
+			label: "Username and password (older self-hosted Umami)"
+		}],
+		default: "apiKey"
+	},
+	apiKey: {
+		type: "secret",
+		label: "API key",
+		description: "Umami → Settings → API keys."
+	},
+	username: {
+		type: "string",
+		label: "Username (password sign-in)"
+	},
+	password: {
+		type: "secret",
+		label: "Password (password sign-in)"
+	},
+	websiteId: {
+		type: "string",
+		label: "Website ID",
+		description: "Umami → Settings → Websites → Edit. A UUID."
+	},
+	injectScript: {
+		type: "boolean",
+		label: "Add the Umami tracker to public pages",
+		default: false
+	},
+	clientRouter: {
+		type: "boolean",
+		label: "The site uses Astro's <ClientRouter /> (view transitions)",
+		description: "Counts every page change, including back and forward, once.",
+		default: false
+	},
+	scriptUrl: {
+		type: "url",
+		label: "Custom tracker script URL",
+		description: "Optional. Default: <Umami URL>/script.js.",
+		placeholder: "https://stats.example.com/script.js"
+	}
+};
+function str(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : null;
+}
+function oneOf(value, allowed, fallback) {
+	return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+/** Strips trailing slashes and a trailing /api so users can paste either form. */
+function normalizeBaseUrl(value) {
+	if (!value) return null;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+	const path = url.pathname.replace(/\/+$/, "").replace(/\/api$/, "");
+	return `${url.origin}${path}`;
+}
+async function readSettings(settings) {
+	const keys = Object.keys(settingsSchema);
+	const values = await Promise.all(keys.map((key) => settings.get(key)));
+	const raw = Object.fromEntries(keys.map((key, i) => [key, values[i]]));
+	const hosting = oneOf(raw.hosting, ["self-hosted"], "self-hosted");
+	return {
+		hosting,
+		baseUrl: normalizeBaseUrl(str(raw.baseUrl)),
+		region: oneOf(raw.region, [
+			"default",
+			"us",
+			"eu"
+		], "default"),
+		authMode: hosting === "cloud" ? "apiKey" : oneOf(raw.authMode, ["apiKey", "password"], "apiKey"),
+		apiKey: str(raw.apiKey),
+		username: str(raw.username),
+		password: typeof raw.password === "string" && raw.password.length > 0 ? raw.password : null,
+		websiteId: str(raw.websiteId),
+		injectScript: raw.injectScript === true,
+		clientRouter: raw.clientRouter === true,
+		scriptUrl: normalizeScriptUrl(str(raw.scriptUrl))
+	};
+}
+function normalizeScriptUrl(value) {
+	if (!value) return null;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:" ? url.toString() : null;
+	} catch {
+		return null;
+	}
+}
+/** Names of settings that must be filled in before Umami can be queried. */
+function missingSettings(s) {
+	const missing = [];
+	if (s.hosting === "self-hosted" && !s.baseUrl) missing.push("baseUrl");
+	if (s.authMode === "apiKey" && !s.apiKey) missing.push("apiKey");
+	if (s.authMode === "password") {
+		if (!s.username) missing.push("username");
+		if (!s.password) missing.push("password");
+	}
+	if (!s.websiteId) missing.push("websiteId");
+	return missing;
+}
+/** Where a person views this site's stats in Umami. */
+function dashboardUrl(s) {
+	const origin = s.hosting === "cloud" ? "https://cloud.umami.is" : s.baseUrl;
+	if (!origin) return null;
+	return s.websiteId ? `${origin}/websites/${encodeURIComponent(s.websiteId)}` : origin;
+}
+//#endregion
+//#region src/shared/stats.ts
+/** Stats shapes shared by the server routes and the admin UI. */
+const RANGES = [
+	"24h",
+	"7d",
+	"30d",
+	"90d"
+];
+const METRIC_TYPES = [
+	"path",
+	"referrer",
+	"country",
+	"browser",
+	"os",
+	"device",
+	"event"
+];
+//#endregion
+//#region src/umami/client.ts
+/** Error with a stable code for the UI. Messages never contain credentials. */
+var UmamiError = class extends Error {
+	code;
+	status;
+	constructor(code, message, status, options) {
+		super(message, options);
+		this.code = code;
+		this.status = status;
+		this.name = "UmamiError";
+	}
+};
+/** Server-log description of a low-level failure. Fetch errors carry URLs, never our headers. */
+function describeCause(cause) {
+	if (cause instanceof Error) {
+		const inner = cause.cause instanceof Error ? ` (${cause.cause.name}: ${cause.cause.message})` : "";
+		return `${cause.name}: ${cause.message}${inner}`;
+	}
+	return String(cause);
+}
+const TOKEN_KEY = "state:token";
+const TIMEOUT_MS = 1e4;
+/** API root: `<baseUrl>/api` when self-hosted, `https://api.umami.is/v1[/region]` on Umami Cloud. */
+function apiBase(s) {
+	if (s.hosting === "cloud") return s.region === "default" ? "https://api.umami.is/v1" : `https://api.umami.is/v1/${s.region}`;
+	return s.baseUrl ? `${s.baseUrl}/api` : null;
+}
+function describeStatus(status, what) {
+	if (status === 401) return new UmamiError("unauthorized", "Umami rejected the credentials. Check the API key, or the username and password.", status);
+	if (status === 403) return new UmamiError("forbidden", `This Umami account is not allowed to read ${what}.`, status);
+	if (status === 404) return new UmamiError("not-found", `Umami could not find ${what}. Check the Umami URL and the website.`, status);
+	if (status === 429) return new UmamiError("rate-limited", "Umami is rate limiting requests. Try again in a minute.", status);
+	return new UmamiError("upstream", `Umami answered with HTTP ${status} for ${what}.`, status);
+}
+function createUmamiClient(s, deps) {
+	const base = apiBase(s);
+	if (!base) throw new UmamiError("not-configured", "Add the Umami URL in the Umami settings.");
+	if (s.authMode === "apiKey" && !s.apiKey) throw new UmamiError("not-configured", "Add an Umami API key in the Umami settings.");
+	if (s.authMode === "password" && (!s.username || !s.password)) throw new UmamiError("not-configured", "Add the Umami username and password in the Umami settings.");
+	async function send(url, init, what) {
+		try {
+			return await deps.fetch(url, {
+				...init,
+				signal: AbortSignal.timeout(TIMEOUT_MS)
+			});
+		} catch (cause) {
+			throw new UmamiError("unreachable", `Could not reach Umami at ${new URL(url).origin} while loading ${what}.`, void 0, { cause });
+		}
+	}
+	const scope = `${base}|${s.username ?? ""}`;
+	async function login() {
+		const res = await send(`${base}/auth/login`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify({
+				username: s.username,
+				password: s.password
+			})
+		}, "the login");
+		if (!res.ok) throw describeStatus(res.status === 400 ? 401 : res.status, "the login");
+		const body = await res.json().catch(() => null);
+		if (!body || typeof body.token !== "string") throw new UmamiError("upstream", "Umami's login answer had no token. Is this an Umami server?");
+		await deps.kv.set(TOKEN_KEY, {
+			token: body.token,
+			scope
+		});
+		return body.token;
+	}
+	async function bearer(forceLogin) {
+		if (s.authMode === "apiKey") return s.apiKey;
+		if (!forceLogin) {
+			const cached = await deps.kv.get(TOKEN_KEY);
+			if (cached && cached.scope === scope) return cached.token;
+		}
+		return login();
+	}
+	return { async get(path, query = {}, what = "the data") {
+		const url = new URL(`${base}${path}`);
+		for (const [key, value] of Object.entries(query)) if (value !== void 0) url.searchParams.set(key, String(value));
+		const request = async (forceLogin) => send(url.toString(), { headers: {
+			Authorization: `Bearer ${await bearer(forceLogin)}`,
+			Accept: "application/json"
+		} }, what);
+		let res = await request(false);
+		if (res.status === 401 && s.authMode === "password") {
+			await deps.kv.delete(TOKEN_KEY);
+			res = await request(true);
+		}
+		if (!res.ok) throw describeStatus(res.status, what);
+		try {
+			return await res.json();
+		} catch {
+			throw new UmamiError("upstream", `Umami's answer for ${what} was not JSON. Is the Umami URL right?`);
+		}
+	} };
+}
+function toWebsite(w) {
+	if (typeof w.id !== "string") return null;
+	return {
+		id: w.id,
+		name: typeof w.name === "string" && w.name ? w.name : w.id,
+		domain: typeof w.domain === "string" && w.domain ? w.domain : null
+	};
+}
+/**
+* Websites the credentials can read, sorted by name: the user's own and those of teams they own or
+* manage (`/websites?includeTeams`), plus every team they belong to in any role (`/teams/{id}/websites`),
+* which covers sites shared with a plain team member.
+*/
+async function listWebsites(client) {
+	const [own, teams] = await Promise.all([client.get("/websites", {
+		includeTeams: true,
+		pageSize: 200
+	}, "the website list"), client.get("/teams", { pageSize: 100 }, "the team list").catch(() => ({ data: [] }))]);
+	const teamIds = (teams.data ?? []).map((t) => t.id).filter((id) => typeof id === "string");
+	const teamSites = await Promise.all(teamIds.map((id) => client.get(`/teams/${encodeURIComponent(id)}/websites`, { pageSize: 200 }, "a team's websites").catch(() => ({ data: [] }))));
+	const byId = /* @__PURE__ */ new Map();
+	for (const raw of [...own.data ?? [], ...teamSites.flatMap((page) => page.data ?? [])]) {
+		const site = toWebsite(raw);
+		if (site && !byId.has(site.id)) byId.set(site.id, site);
+	}
+	return [...byId.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** One website by id, or null when Umami says it does not exist or is not visible. */
+async function getWebsite(client, id) {
+	try {
+		return toWebsite(await client.get(`/websites/${encodeURIComponent(id)}`, {}, "the website"));
+	} catch (error) {
+		if (error instanceof UmamiError && (error.code === "not-found" || error.code === "forbidden")) return null;
+		throw error;
+	}
+}
+//#endregion
+//#region src/umami/stats.ts
+const HOUR = 36e5;
+const DAY = 24 * HOUR;
+/** Rolling windows ending now; hours for the last day, days otherwise. */
+function windowFor(range, now) {
+	const days = {
+		"24h": 1,
+		"7d": 7,
+		"30d": 30,
+		"90d": 90
+	}[range];
+	return {
+		range,
+		unit: range === "24h" ? "hour" : "day",
+		startAt: now - days * DAY + 1,
+		endAt: now
+	};
+}
+function isValidTimeZone(tz) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: tz });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function num(value) {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	return Number.isFinite(n) ? n : 0;
+}
+function toTotals(raw) {
+	const r = raw ?? {};
+	return {
+		pageviews: num(r.pageviews),
+		visitors: num(r.visitors),
+		visits: num(r.visits),
+		bounces: num(r.bounces),
+		totaltime: num(r.totaltime)
+	};
+}
+const formatters = /* @__PURE__ */ new Map();
+function formatter(tz) {
+	let f = formatters.get(tz);
+	if (!f) {
+		f = new Intl.DateTimeFormat("en-CA", {
+			timeZone: tz,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			hourCycle: "h23"
+		});
+		formatters.set(tz, f);
+	}
+	return f;
+}
+/** Wall-clock parts of an instant in a time zone. */
+function partsIn(t, tz) {
+	const parts = Object.fromEntries(formatter(tz).formatToParts(new Date(t)).map((p) => [p.type, p.value]));
+	return {
+		date: `${parts.year}-${parts.month}-${parts.day}`,
+		hour: parts.hour
+	};
+}
+function bucketLabel(t, unit, tz) {
+	const p = partsIn(t, tz);
+	return unit === "day" ? p.date : `${p.date} ${p.hour}:00`;
+}
+/**
+* Umami returns buckets as wall-clock strings in the requested zone ("2026-09-28 14:00:00", or an
+* ISO-like variant) and omits empty ones. Normalize to our label format.
+*/
+function labelFromUmami(x, unit) {
+	const clean = x.replace("T", " ");
+	return unit === "day" ? clean.slice(0, 10) : `${clean.slice(0, 13)}:00`;
+}
+/** Every bucket in the window, oldest first, so charts show zero days instead of skipping them. */
+function buckets(win, tz) {
+	const step = HOUR;
+	const seen = /* @__PURE__ */ new Map();
+	for (let t = Math.floor(win.startAt / HOUR) * HOUR; t <= win.endAt; t += step) {
+		const label = bucketLabel(t, win.unit, tz);
+		if (!seen.has(label)) seen.set(label, t);
+	}
+	const end = bucketLabel(win.endAt, win.unit, tz);
+	if (!seen.has(end)) seen.set(end, win.endAt);
+	return [...seen.entries()].map(([label, t]) => ({
+		label,
+		t
+	}));
+}
+function mergeSeries(win, tz, pageviews, sessions) {
+	const index = (rows) => {
+		const m = /* @__PURE__ */ new Map();
+		for (const row of rows ?? []) {
+			if (typeof row.x !== "string") continue;
+			const key = labelFromUmami(row.x, win.unit);
+			m.set(key, (m.get(key) ?? 0) + num(row.y));
+		}
+		return m;
+	};
+	const pv = index(pageviews);
+	const vis = index(sessions);
+	return buckets(win, tz).map(({ label, t }) => ({
+		label,
+		t,
+		pageviews: pv.get(label) ?? 0,
+		visitors: vis.get(label) ?? 0
+	}));
+}
+function toRows(raw, limit) {
+	if (!Array.isArray(raw)) return [];
+	return raw.map((row) => ({
+		label: row.x == null || row.x === "" ? "(none)" : String(row.x),
+		value: num(row.y)
+	})).filter((row) => row.value > 0).slice(0, limit);
+}
+const TOP_LIMIT = 10;
+async function fetchOverview(client, websiteId, range, timezone, now = Date.now()) {
+	const win = windowFor(range, now);
+	const id = encodeURIComponent(websiteId);
+	const q = {
+		startAt: win.startAt,
+		endAt: win.endAt,
+		timezone
+	};
+	const length = win.endAt - win.startAt;
+	const [stats, prev, series, ...metrics] = await Promise.all([
+		client.get(`/websites/${id}/stats`, q, "the summary"),
+		client.get(`/websites/${id}/stats`, {
+			...q,
+			startAt: win.startAt - length - 1,
+			endAt: win.startAt - 1
+		}, "the previous period"),
+		client.get(`/websites/${id}/pageviews`, {
+			...q,
+			unit: win.unit
+		}, "the chart"),
+		...METRIC_TYPES.map((type) => client.get(`/websites/${id}/metrics`, {
+			...q,
+			type,
+			limit: TOP_LIMIT
+		}, `the top ${type} list`))
+	]);
+	return {
+		websiteId,
+		range,
+		unit: win.unit,
+		timezone,
+		startAt: win.startAt,
+		endAt: win.endAt,
+		totals: toTotals(stats),
+		previous: toTotals(prev),
+		series: mergeSeries(win, timezone, series.pageviews ?? [], series.sessions ?? []),
+		top: Object.fromEntries(METRIC_TYPES.map((type, i) => [type, toRows(metrics[i], TOP_LIMIT)])),
+		fetchedAt: now,
+		stale: false
+	};
+}
+async function fetchActive(client, websiteId, now = Date.now()) {
+	return {
+		visitors: num((await client.get(`/websites/${encodeURIComponent(websiteId)}/active`, {}, "active visitors"))?.visitors),
+		fetchedAt: now
+	};
+}
+//#endregion
+//#region src/routes/stats.ts
+const overviewInput = z.object({
+	range: z.enum(RANGES).default("7d"),
+	tz: z.string().max(64).optional().transform((tz) => tz && isValidTimeZone(tz) ? tz : "UTC")
+});
+/** 24h data moves quickly; longer ranges barely change minute to minute. */
+const OVERVIEW_MAX_AGE = {
+	"24h": 6e4,
+	"7d": 3e5,
+	"30d": 6e5,
+	"90d": 9e5
+};
+const ACTIVE_MAX_AGE = 2e4;
+async function withClient(ctx, run) {
+	try {
+		const s = await readSettings(ctx.settings);
+		if (!s.websiteId) throw new UmamiError("not-configured", "Choose the Umami website in the plugin settings.");
+		const http = ctx.http;
+		if (!http) throw new UmamiError("unreachable", "EmDash did not grant this plugin network access.");
+		return {
+			ok: true,
+			data: await run(createUmamiClient(s, {
+				fetch: (url, init) => http.fetch(url, init),
+				kv: ctx.kv
+			}), s.websiteId)
+		};
+	} catch (error) {
+		if (error instanceof UmamiError) {
+			if (error.cause) ctx.log.warn("Umami request failed", {
+				code: error.code,
+				cause: describeCause(error.cause)
+			});
+			return {
+				ok: false,
+				code: error.code,
+				message: error.message
+			};
+		}
+		ctx.log.error("Umami request failed", { error: error instanceof Error ? error.message : String(error) });
+		return {
+			ok: false,
+			code: "upstream",
+			message: "Loading statistics failed unexpectedly. See the server log."
+		};
+	}
+}
+function overview(ctx) {
+	const { range, tz } = ctx.input;
+	return withClient(ctx, async (client, websiteId) => {
+		const hit = await cached(ctx.kv, `cache:overview:${websiteId}:${range}:${tz}`, OVERVIEW_MAX_AGE[range], () => fetchOverview(client, websiteId, range, tz));
+		return {
+			...hit.value,
+			stale: hit.stale
+		};
+	});
+}
+function active(ctx) {
+	return withClient(ctx, async (client, websiteId) => {
+		return (await cached(ctx.kv, `cache:active:${websiteId}`, ACTIVE_MAX_AGE, () => fetchActive(client, websiteId))).value;
+	});
+}
+//#endregion
+//#region src/routes/settings.ts
+function view(s) {
+	const { apiKey, password, ...values } = s;
+	return {
+		values,
+		secretsSet: {
+			apiKey: apiKey !== null,
+			password: password !== null
+		}
+	};
+}
+async function getSettings(ctx) {
+	return view(await readSettings(ctx.settings));
+}
+const optionalText = z.string().trim().max(2048).nullable().optional();
+/**
+* URL fields are validated in the input schema, not by throwing from the handler: in `astro dev` a
+* PluginRouteError thrown here is a different class instance from the host's and surfaces as a
+* generic INTERNAL_ERROR, while schema failures always come back as VALIDATION_ERROR.
+*/
+const optionalUrl = optionalText.refine((value) => !value || normalizeBaseUrl(value) !== null, { message: "Must be an address starting with https:// or http://" });
+/** Secrets: a string replaces the stored value, null clears it, omitted keeps it. */
+const secretInput = z.string().max(4096).nullable().optional();
+const saveSettingsInput = z.object({
+	hosting: z.enum(["self-hosted", "cloud"]).refine((h) => h !== "cloud", { message: "Umami Cloud support arrives in 0.2.0" }).optional(),
+	baseUrl: optionalUrl,
+	region: z.enum([
+		"default",
+		"us",
+		"eu"
+	]).optional(),
+	authMode: z.enum(["apiKey", "password"]).optional(),
+	apiKey: secretInput,
+	username: optionalText,
+	password: secretInput,
+	websiteId: optionalText,
+	injectScript: z.boolean().optional(),
+	clientRouter: z.boolean().optional(),
+	scriptUrl: optionalUrl
+});
+async function saveSettings(ctx) {
+	const input = ctx.input;
+	const writes = [];
+	const put = (key, value) => {
+		if (value === void 0) return;
+		if (value === null || value === "") writes.push(ctx.settings.delete(key));
+		else writes.push(ctx.settings.set(key, value));
+	};
+	put("hosting", input.hosting);
+	put("baseUrl", input.baseUrl === void 0 ? void 0 : normalizeBaseUrl(input.baseUrl ?? null));
+	put("region", input.region);
+	put("authMode", input.authMode);
+	put("apiKey", input.apiKey === void 0 ? void 0 : input.apiKey?.trim() || null);
+	put("username", input.username);
+	put("password", input.password);
+	put("websiteId", input.websiteId);
+	put("injectScript", input.injectScript);
+	put("clientRouter", input.clientRouter);
+	put("scriptUrl", input.scriptUrl);
+	await Promise.all(writes);
+	if (input.baseUrl !== void 0 || input.username !== void 0 || input.password !== void 0 || input.hosting !== void 0) await ctx.kv.delete(TOKEN_KEY);
+	return getSettings(ctx);
+}
+function clientFor(ctx, s) {
+	const http = ctx.http;
+	if (!http) throw new UmamiError("unreachable", "EmDash did not grant this plugin network access.");
+	return createUmamiClient(s, {
+		fetch: (url, init) => http.fetch(url, init),
+		kv: ctx.kv
+	});
+}
+/** Checks the saved settings against Umami. Returns failures as data so the UI can explain them. */
+async function testConnection(ctx) {
+	const s = await readSettings(ctx.settings);
+	try {
+		const client = clientFor(ctx, s);
+		const websites = await listWebsites(client);
+		let website = websites.find((w) => w.id === s.websiteId) ?? null;
+		if (!website && s.websiteId) {
+			website = await getWebsite(client, s.websiteId);
+			if (website) websites.push(website);
+		}
+		return {
+			ok: true,
+			websites,
+			website
+		};
+	} catch (error) {
+		if (error instanceof UmamiError) {
+			if (error.cause) ctx.log.warn("Umami request failed", {
+				code: error.code,
+				cause: describeCause(error.cause)
+			});
+			return {
+				ok: false,
+				code: error.code,
+				message: error.message
+			};
+		}
+		ctx.log.error("Umami connection test failed", { error: error instanceof Error ? error.message : String(error) });
+		return {
+			ok: false,
+			code: "upstream",
+			message: "The connection test failed unexpectedly. See the server log."
+		};
+	}
+}
+//#endregion
+//#region src/shared/tracker.ts
+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. */
+function defaultScriptUrl(hosting, baseUrl, scriptUrl) {
+	if (scriptUrl) return scriptUrl;
+	if (hosting === "cloud") return CLOUD_SCRIPT_URL;
+	return baseUrl ? `${baseUrl.replace(/\/+$/, "").replace(/\/api$/, "")}/script.js` : null;
+}
+//#endregion
+//#region src/tracker.ts
+/**
+* Pageviews for sites using Astro's <ClientRouter />. Umami's own tracking hooks pushState only,
+* so back and forward are missed, and a re-run tracker tag counts forward navigations twice.
+* With `data-auto-pageview="false"` this sends one pageview per `astro:page-load` instead,
+* passing the URL explicitly because Umami's stored URL is stale after a back navigation. On a
+* page without <ClientRouter /> (no `astro-view-transitions-enabled` meta) it tracks once on
+* DOMContentLoaded, so a wrong setting never stops tracking.
+*/
+const CLIENT_ROUTER_SCRIPT = `(()=>{let prev;const send=()=>{const u=window.umami;if(!u)return false;const url=location.href;u.track((p)=>({...p,url,title:document.title,...(prev?{referrer:prev}:{})}));prev=location.pathname+location.search;return true};const track=()=>{let n=0;const t=()=>{send()||++n>100||setTimeout(t,50)};t()};document.addEventListener("astro:page-load",track);document.addEventListener("DOMContentLoaded",()=>{document.querySelector('meta[name="astro-view-transitions-enabled"]')||track()})})();`;
+/**
+* The Umami tracker as page fragments, or null when tracking is off or incomplete.
+* EmDash HTML-escapes attribute values and drops on* attributes when rendering.
+*/
+async function trackerFragment(event, settings) {
+	if (event.page.path.startsWith("/_emdash")) return null;
+	if (await settings.get("injectScript") !== true) return null;
+	const s = await readSettings(settings);
+	const src = defaultScriptUrl(s.hosting, s.baseUrl, s.scriptUrl);
+	if (!src || !s.websiteId || !normalizeBaseUrl(src)) return null;
+	const tracker = {
+		kind: "external-script",
+		placement: "head",
+		src,
+		defer: true,
+		attributes: { "data-website-id": s.websiteId },
+		key: "umami-tracker"
+	};
+	if (!s.clientRouter) return tracker;
+	return [{
+		...tracker,
+		attributes: {
+			...tracker.attributes,
+			"data-auto-pageview": "false"
+		}
+	}, {
+		kind: "inline-script",
+		placement: "head",
+		code: CLIENT_ROUTER_SCRIPT,
+		key: "umami-client-router"
+	}];
+}
+//#endregion
+//#region src/index.ts
+const ADMIN_ENTRY = `${PACKAGE_NAME}/admin`;
+/**
+* Descriptor for astro.config.mjs:
+*
+*   import { umamiPlugin } from "@tdhftw/emdash-plugin-umami";
+*   emdash({ plugins: [umamiPlugin()] })
+*/
+function umamiPlugin(options = {}) {
+	return {
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		format: "native",
+		entrypoint: PACKAGE_NAME,
+		adminEntry: ADMIN_ENTRY,
+		options
+	};
+}
+async function status(ctx) {
+	const s = await readSettings(ctx.settings);
+	const missing = missingSettings(s);
+	return {
+		configured: missing.length === 0,
+		missing,
+		hosting: s.hosting,
+		authMode: s.authMode,
+		websiteId: s.websiteId,
+		dashboardUrl: dashboardUrl(s),
+		injectScript: s.injectScript,
+		hasHttp: Boolean(ctx.http)
+	};
+}
+/** Runtime definition. EmDash imports this named export from the package root. */
+function createPlugin(_options = {}) {
+	return definePlugin({
+		id: PLUGIN_ID,
+		version: PLUGIN_VERSION,
+		capabilities: ["network:request:unrestricted", "hooks.page-fragments:register"],
+		hooks: { "page:fragments": (event, ctx) => trackerFragment(event, ctx.settings) },
+		admin: {
+			entry: ADMIN_ENTRY,
+			settingsSchema,
+			pages: [{
+				path: "/",
+				label: "Analytics",
+				icon: "chart-line"
+			}],
+			widgets: [{
+				id: "umami-overview",
+				title: "Visitors",
+				size: "half"
+			}]
+		},
+		routes: {
+			status: {
+				permission: "plugins:read",
+				handler: status
+			},
+			overview: {
+				permission: "plugins:read",
+				input: overviewInput,
+				handler: overview
+			},
+			active: {
+				permission: "plugins:read",
+				handler: active
+			},
+			settings: {
+				permission: "plugins:manage",
+				handler: getSettings
+			},
+			"settings/save": {
+				permission: "plugins:manage",
+				input: saveSettingsInput,
+				handler: saveSettings
+			},
+			"connection/test": {
+				permission: "plugins:manage",
+				handler: testConnection
+			}
+		}
+	});
+}
+//#endregion
+export { PLUGIN_ID, PLUGIN_VERSION, createPlugin, createPlugin as default, umamiPlugin };