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

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 0.1.2 (2026-10-28)
+
+First release on npm. No code changes since 0.1.1.
+
+- README: current status, tested versions, and a link to the upstream dev-mode issue.
+- Package description no longer mentions Umami Cloud, which is still switched off.
+
+## 0.1.1 (2026-10-28)
+
+- Chart bars show real counts: pageviews and visitors are drawn over each other instead of
+  stacked, which made each bar the sum of both.
+- Chart x-axis labels follow the site's timezone and no longer repeat or overlap around the
+  start of a month (seen on the 90-day range).
+- Chart y-axis shows whole numbers only, so a range without data no longer reads 1, 1, 1, 0, 0, 0.
+- The chart has a legend for the two series.
+
+## 0.1.0 (2026-09-28)
+
+First version.
+
+- Analytics page in the EmDash admin, with KPI tiles compared against the previous period,
+  active visitors, a pageviews and visitors chart, and top pages, referrers, countries,
+  browsers, operating systems, devices and events. Ranges are 24 hours, 7, 30 and 90 days.
+- Dashboard widget with the last 7 days and a sparkline.
+- Guided settings for self-hosted Umami, with API key or username and password sign-in, a
+  connection test and a website picker that includes team-shared sites.
+- Umami Cloud support is implemented but disabled (shown as "coming in 0.2.0") until it has
+  been tested against a Cloud account.
+- Optional tracker injection into public pages through `page:fragments`.
+- Statistics cached in plugin storage, with the saved copy shown when Umami is unreachable.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thord D. Hedengren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @tdhftw/emdash-plugin-umami
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Umami](https://umami.is) analytics inside the [EmDash](https://emdashcms.com) admin, for
+self-hosted Umami. Umami Cloud support is built but switched off until it has been tested against
+a Cloud account; it is planned for 0.2.0.
+
+- **Analytics page.** Visitors, visits, pageviews, bounce rate and visit duration, each compared
+  with the previous period. It also shows active visitors, a chart, and the top pages,
+  referrers, countries, browsers, operating systems, devices and custom events for the last 24
+  hours, 7, 30 or 90 days.
+- **Dashboard widget.** The last 7 days at a glance, with a sparkline and active visitors.
+- **Guided setup.** It checks the connection and lists the Umami websites you can pick from.
+- **Optional tracker.** It can add the Umami script to your public pages, so the theme doesn't
+  need to.
+
+> Status: 0.1.x, self-hosted Umami only. Tested with EmDash 1.0.1 to 1.3.1 and Umami 3.4.
+
+## Requirements
+
+- EmDash 1.0 or later, with Astro 7.
+- A self-hosted Umami and an API key for it. Umami 3.x has API keys under Settings → API keys.
+  Older versions can sign in with a username and password instead.
+- `EMDASH_ENCRYPTION_KEY` set on the site, which EmDash needs to store the API key or password
+  encrypted. Generate one with `npx emdash secrets generate`. On Cloudflare, store it with
+  `wrangler secret put EMDASH_ENCRYPTION_KEY`.
+
+## Install
+
+```bash
+npm install @tdhftw/emdash-plugin-umami
+```
+
+```js
+// astro.config.mjs
+import { umamiPlugin } from "@tdhftw/emdash-plugin-umami";
+
+export default defineConfig({
+	integrations: [
+		emdash({
+			// ...database, storage and the rest of your config
+			plugins: [umamiPlugin()],
+		}),
+	],
+});
+```
+
+This is a native EmDash plugin, so it goes in `plugins`, not `sandboxed`. Deploy the site after
+adding it.
+
+## Set up
+
+1. Open **Analytics** in the admin sidebar. Until Umami is connected, it opens on **Settings**.
+2. Enter the address you open Umami at, for example `https://stats.example.com`. The Umami Cloud
+   option is shown but disabled until 0.2.0.
+3. Paste an API key, or on older self-hosted versions, a username and password.
+4. Select **Save and test connection**. When it connects, the websites the key can see appear
+   under **Website**, including sites shared with you through a team.
+5. Pick the website, then save again.
+
+The key and password are encrypted with `EMDASH_ENCRYPTION_KEY` and never sent back to the
+browser. The same settings are also available from the gear on the plugin's card under
+**Plugins**, as a plain form.
+
+## Adding the tracker (optional)
+
+Turning on **Add the Umami tracker to public pages** adds the Umami script to the `<head>` of
+every public page:
+
+```html
+<script src="https://stats.example.com/script.js" defer data-website-id="…"></script>
+```
+
+- **Theme requirement.** Your theme must render EmDash's `<EmDashHead>` component, as the EmDash
+  templates do.
+- **Avoid double counting.** Remove any Umami script the theme already includes, or every visit
+  is counted twice.
+- **Custom script URL.** Set one if you serve a renamed tracker or proxy it.
+- **Cached pages.** If your site caches pages, cached copies change over only when their cache
+  expires.
+- **Admin pages** are never tracked.
+
+## Permissions
+
+| Capability | Why |
+| --- | --- |
+| `network:request:unrestricted` | Umami's address is configured by you, so no fixed host list is possible. The plugin only calls the Umami URL you set. |
+| `hooks.page-fragments:register` | Needed only for the optional tracker. |
+
+Reading statistics requires the `plugins:read` permission. Changing settings requires
+`plugins:manage`.
+
+## Caching and rate limits
+
+- **Statistics** are cached in the plugin's storage for 1 minute on the 24-hour range, and up to
+  15 minutes on longer ranges. If Umami can't be reached, the last saved copy is shown and
+  marked as such.
+- **Active visitors** are cached for 20 seconds.
+- **One overview load** makes 10 requests to Umami. That matters for Umami Cloud, which allows
+  50 requests per 15 seconds per key.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+`src/index.ts` holds the plugin definition, settings schema, routes and hooks. It is compiled to
+`dist/`. `src/admin/` is the React admin UI. It ships as source because the site's own build
+compiles it.
+
+To try the plugin in a local EmDash site, install a packed tarball rather than a folder link. A
+linked folder brings along a second copy of React.
+
+```bash
+npm run build && npm pack --pack-destination /tmp
+cd ../your-site && npm install --no-save /tmp/tdhftw-emdash-plugin-umami-<version>.tgz
+```
+
+**Two EmDash quirks to know about under `astro dev`** (still present in 1.3.1):
+
+- **Host-context hooks crash.** Plugin components can't use the admin's Lingui or React Query
+  providers, because dev mode loads a second copy of those libraries
+  ([emdash#3587](https://github.com/emdash-cms/emdash/issues/3587)). This plugin brings its own
+  React Query client and doesn't use Lingui.
+- **The dev admin can look off.** It may pick up the site's own stylesheet. Production builds
+  don't.
+
+## License
+
+MIT © Thord D. Hedengren

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import { PluginDescriptor } from "emdash";
+import { z } from "astro/zod";
+//#region src/shared/constants.d.ts
+/** Plugin id. One URL segment: routes mount at /_emdash/api/plugins/umami/<route>. */
+export declare const PLUGIN_ID = "umami";
+/** Keep in sync with package.json; test/plugin.test.ts enforces it. */
+export declare const PLUGIN_VERSION = "0.1.2";
+type Hosting = "self-hosted" | "cloud";
+type AuthMode = "apiKey" | "password";
+type CloudRegion = "default" | "us" | "eu";
+/** Shape returned by the `status` route. Shared by server and admin. */
+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;
+}
+//#endregion
+//#region src/shared/stats.d.ts
+/** Stats shapes shared by the server routes and the admin UI. */
+declare const RANGES: readonly ["24h", "7d", "30d", "90d"];
+type Range = (typeof RANGES)[number];
+declare const METRIC_TYPES: readonly ["path", "referrer", "country", "browser", "os", "device", "event"];
+type MetricType = (typeof METRIC_TYPES)[number];
+interface Totals {
+  pageviews: number;
+  visitors: number;
+  visits: number;
+  bounces: number;
+  /** Total visit duration in seconds. */
+  totaltime: number;
+}
+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;
+}
+interface MetricRow {
+  label: string;
+  value: number;
+}
+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;
+}
+interface Active {
+  visitors: number;
+  fetchedAt: number;
+}
+//#endregion
+//#region src/shared/settings-types.d.ts
+interface UmamiSettingsValues {
+  hosting: Hosting;
+  baseUrl: string | null;
+  region: CloudRegion;
+  authMode: AuthMode;
+  username: string | null;
+  websiteId: string | null;
+  injectScript: boolean;
+  scriptUrl: string | null;
+}
+//#endregion
+//#region src/shared/api-types.d.ts
+type UmamiErrorCode = "not-configured" | "unauthorized" | "forbidden" | "not-found" | "rate-limited" | "unreachable" | "upstream";
+interface UmamiWebsite {
+  id: string;
+  name: string;
+  domain: string | null;
+}
+/** Settings as the admin sees them: everything except secret values. */
+interface SettingsView {
+  values: UmamiSettingsValues;
+  secretsSet: {
+    apiKey: boolean;
+    password: boolean;
+  };
+}
+type ConnectionTestResult = {
+  ok: true;
+  websites: UmamiWebsite[];
+  website: UmamiWebsite | null;
+} | {
+  ok: false;
+  code: UmamiErrorCode;
+  message: string;
+};
+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. */
+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;
+}
+//#endregion
+//#region src/index.d.ts
+/** Constructor options. Everything user-facing lives in the admin settings form instead. */
+export type UmamiPluginOptions = Record<string, never>;
+/**
+ * Descriptor for astro.config.mjs:
+ *
+ *   import { umamiPlugin } from "@tdhftw/emdash-plugin-umami";
+ *   emdash({ plugins: [umamiPlugin()] })
+ */
+export declare function umamiPlugin(options?: UmamiPluginOptions): PluginDescriptor<UmamiPluginOptions>;
+/** Runtime definition. EmDash imports this named export from the package root. */
+export declare function createPlugin(_options?: UmamiPluginOptions): import("emdash").ResolvedPlugin<import("emdash").PluginStorageConfig>;
+//#endregion
+export { type Active, type ConnectionTestResult, type METRIC_TYPES, type MetricRow, type MetricType, type Overview, type RANGES, type Range, type SaveSettingsInput, type SeriesPoint, type SettingsView, type StatsResult, type StatusResponse, type Totals, createPlugin as default };