hearald 0.0.5 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-09
+
+### Fixed
+
+- The dashboard threw errors the first time it loaded with no data (`Cannot read properties of
+  undefined (reading 'map')` and `(reading 'users')`). It now shows zeros and empty menus when there
+  are no events, no metrics for the chosen chart context, or no `ui` layout.
+
+### Added
+
+- Tests that render the dashboard in a fake browser (happy-dom) against a real hearald router.
+
+## [0.1.0] - 2026-10-07
+
+### Security
+
+- **Breaking:** the analytics dashboard now needs an `auth` middleware (`analytics: { auth }`), or
+  `allowUnauthenticated: true` for local development. Before, anyone could read the stats.
+- Added `basicAuth({ verify })`: HTTP Basic auth with a lockout after repeated wrong guesses.
+- The data route now rejects dates that are not real calendar dates (`2026-02-31` used to be accepted
+  and moved to March) and time windows over 366 days (the date used to become part of a file path).
+- `basicAuth` counted a wrong guess only after `verify` finished, so any number of parallel guesses got
+  past the lockout. Attempts are now counted before `verify` runs. It also accepts the `Basic` scheme
+  in any letter case, answers 500 (instead of crashing an Express 4 app) when `verify` throws, and
+  forgets old addresses (`maxTrackedIps`, default 10000). Its lockout needs Express's `trust proxy`
+  set correctly, see the README.
+- A dashboard request for a huge window could use all the server's memory. Windows whose event files
+  add up to more than `maxWindowBytes` (default 64 MB) get 413 `{ "error": "window too large" }`, stats
+  are computed one request at a time, and the raw events are only kept for computed histograms.
+
+### Added
+
+- `eventEndpoint: { schema }`: allowed events and parameters for the public event endpoint. Events
+  not in the schema and parameters not listed are dropped, so the endpoint cannot store arbitrary text.
+- `eventsDir`: where event logs and cached summaries are kept (default `events`).
+- `purgeOldEvents({ days })`: deletes logs and cached summaries older than a retention period. It counts
+  days with the configured `nowFn` and in UTC; a file dated exactly `days` days ago is kept.
+- `idleCloseMs` (default 60000): how long an event file stays open after its last write.
+- `maxWindowBytes` (default 64 MB): the most event data one dashboard request may read.
+- The test suite runs on Express 5 and Express 4 (`npm test` runs both; `HEARALD_EXPRESS=4` or `5` picks one).
+- `analytics` is only created when `statDefinitions` is given.
+
+### Changed
+
+- `express` is now a peer dependency (>=4) instead of a dependency, so the host app's Express is used.
+
+### Fixed
+
+- The dashboard router could not be built on Express 5 (`Unexpected ? at index 17`: its optional
+  `:date?` route parameter is not allowed there), so `hearald({ analytics })` threw at startup. The
+  data route is now registered as two routes. Express 4 behaves as before.
+- A failed attempt to open an event file (disk full, read-only file system, wrong permissions) was
+  remembered, so every later write failed too, and 60 seconds later closing it was an unhandled
+  rejection that ended the process. A failed open is now forgotten (the next write tries again), and
+  idle timers cannot reject or keep a script alive. The timer closes the file it was set for, even if
+  the events directory changed meanwhile.
+- The error middleware could crash the process: an error that `JSON.stringify` cannot handle (a
+  circular object) or a failing write became an unhandled rejection. It now always passes the error
+  on to your own handler.
+- On Express 4, a failing read in the dashboard routes (an unreadable cache file, a missing
+  `dist/analytics.html`) crashed the process; the error now goes to your error handler.
+- The README mounted the event route at `/events` while the route inside is `/e`, so events went to
+  `/events/e` and the browser client's sends quietly got a 404. The README is fixed, and the client now
+  treats a non-2xx answer as a failure: `onError` is called (it still never throws).
+- Cached summaries are named with a hash of the metric definitions and a format version
+  (`summary:<date>:<days>:<hash>.json`), so editing a definition no longer serves numbers computed with
+  the old one. Summaries cached before this change (including those written by 0.0.5, which used the
+  old `set_of_users` meaning and the old day buckets) are no longer read; they can be deleted
+  (`purgeOldEvents` still removes them by age).
+- Histograms (raw and computed) mishandled a value named `constructor`, `toString` or `__proto__`, and
+  left out the values `0`, `false` and `""`.
+- A truncated last line (after a crash) glued itself to the next event and lost both. A new line is
+  now started when a file is opened that does not end with one.
+- `purgeOldEvents` ignored `nowFn` and used the server's local time zone.
+- `dispose()` of an old client no longer silences the client that replaced it.
+- `trackServerError` and the error middleware crashed with a ReferenceError (`ERROR_EVENT` was never
+  imported).
+- The log level setting did nothing: the logger was built from the string `"error"` instead of the
+  configuration. Levels now work (`debug`, `info`, `warn`, `error`); the default is `warn`.
+- Days with no events no longer log a warning for every missing file.
+- A computed metric with an unknown formula made `generateStats` loop forever; it now throws.
+- `nowAsPstDate` returned a Date with a forced hour and the UTC date, so day buckets were not Pacific
+  days. It now holds the real Pacific wall-clock time, with daylight saving. `defaultEndDate` uses
+  UTC date maths and follows the configured `nowFn` instead of the real clock.
+- Reading a window of days used local-time date maths, which could skip or repeat a day around
+  daylight saving changes on servers not set to UTC.
+- Stats for a window ending today were cached, so the dashboard showed stale numbers all day.
+- The client's `trackError` threw when the error event had no `.error` object, and calling
+  `hearald()` twice sent every event twice (the new `dispose()` and replacement fix both).
+- Without a schema, the event endpoint stored events with no name or with a non-object `p`.
+- A `set_of_users` metric that names an `event` now counts only users who sent that event (it used to
+  count every user, whatever the event). A `filter` on event parameters already worked.
+- Events with no parameters or no user no longer break metric computation.
+- Open event files are tracked by full path, so changing `eventsDir` cannot reuse a stale file handle.
+
 ## [0.0.5] - 2025-10-05
 
 ### Added
@@ -34,9 +129,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release of Hearald
 
-[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
-[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
-[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.3
+[Unreleased]: https://github.com/pariser/hearald/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/pariser/hearald/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/pariser/hearald/compare/v0.0.5...v0.1.0
+[0.0.5]: https://github.com/pariser/hearald/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/pariser/hearald/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/pariser/hearald/releases/tag/v0.0.3
 
 <!--
 `Added` for new features.

package/README.md

@@ -1,71 +1,145 @@
 # hearald
 
-A single server drop-in file system based metrics and analytics library.
+A single server drop-in file system based metrics and analytics library: your apps send events, they
+are appended to one log file per day, and a small dashboard turns them into counts, unique users and
+histograms. No database.
 
-## TODO
-
-- top stats histogram should/could be it's own ui-configurable data type
-- top stats histogram fields should be controlled in the ui configuration settings
-
-## Usage
+```bash
+npm test      # unit and integration tests, run against Express 5 and then Express 4
+npm run build # rebuilds dist/ (the dashboard page)
+```
 
-### Tracking User Visits (Client)
+## Server
 
 ```js
-import { trackVisit } from "hearald/client/trackVisit.js";
-trackVisit({ userId: "user-123" });
+import express from "express";
+import hearald, { basicAuth } from "hearald";
+
+const app = express();
+app.use(express.json());
+
+const h = hearald({
+  eventsDir: "/var/lib/myapp/events", // default "events", relative to the working directory
+  // idleCloseMs: 60000, // how long an event file stays open after its last write
+  // maxWindowBytes: 64 * 1024 * 1024, // dashboard windows with more event data than this get a 413
+  getUserId: (req) => req.user?.id, // used for server-side errors
+  // Strongly recommended for any endpoint open to the internet: only these events and parameters
+  // are stored, everything else is dropped (the caller still gets a 204).
+  eventEndpoint: {
+    url: "/events", // where the route listens, inside wherever you mount eventMiddleware (default "/e")
+    schema: {
+      app_open: { platform: { type: "string", enum: ["web", "ios"], required: true } },
+      purchase: { plan: { type: "string", maxLength: 32 }, cents: { type: "number", integer: true, min: 0 } },
+    },
+    // parseBody: (req) => ({ e, u, p }), for example to take the user from a session, not the body
+  },
+  analytics: {
+    statDefinitions, // see below
+    auth: basicAuth({ verify: (user, pass) => user === "admin" && passwordMatches(pass) }),
+    // allowUnauthenticated: true, // local development only
+  },
+});
+
+app.use(h.eventMiddleware); // POST /events  { e, u, p }: the route's own `url`, so mount it at the root
+app.use("/admin/analytics", h.analyticsMiddleware); // the dashboard
+app.use(h.errorMiddlware); // records errors thrown by your routes, then passes them on
+
+await h.trackServerEvent({ event: "job_done", userId: "system", params: { count: 3 } });
+await h.trackServerError({ error: new Error("boom"), userId: "u1", extraParams: { route: "/save" } });
+await h.purgeOldEvents({ days: 90 }); // run nightly to keep a retention period
+await h.shutDown(); // closes open files on exit
 ```
 
-### Tracking Errors (Client)
+The dashboard has no default password: `analytics` throws unless you pass `auth`. `basicAuth` answers 401
+with a challenge and locks an IP out (429) after 10 wrong guesses in 15 minutes. Store a hash of the
+password and compare in constant time.
 
-```js
-import { trackError } from "hearald/client/trackError.js";
-try {
-  // ...code...
-} catch (err) {
-  trackError(err);
-}
-```
+`url` is the full path of the route (`/events` above), and `eventMiddleware` is a router that serves it, so
+mount it at the root. If you mount it at `app.use("/api", h.eventMiddleware)`, events arrive at
+`/api/events`, and the browser client's `endpoint` must say so.
+
+`basicAuth` counts wrong guesses per `req.ip`. That is the visitor's address only if your app sets
+Express's `trust proxy` correctly: behind a reverse proxy without it every visitor shares the proxy's
+address, and with it set too loosely a caller can forge `X-Forwarded-For` to avoid the lockout. If
+`verify` throws, the request gets a 500 and is not counted as a wrong guess.
+
+**The event endpoint is public and has no rate limit or size cap of its own.** Anyone who can reach it
+can send events, so fake user ids can inflate "unique users" and a flood can fill the disk. Use `schema`
+(it bounds string lengths and the set of event names, not how many events arrive), keep Express's
+body limit small (`express.json({ limit: "10kb" })`), and put a rate limit (for example
+`express-rate-limit`) in front of it, or in your own route, as part of your hosting setup. Run `purgeOldEvents` too.
 
-### Tracking Errors (Server)
+Only `express` (>= 4) is a peer dependency; use your app's own. hearald is tested on Express 4 and 5.
+
+## Browser
 
 ```js
-import {
-  trackServerError,
-  errorTrackingMiddleware,
-} from "hearald/server/serverTrackError.js";
-app.use(errorTrackingMiddleware);
+import hearaldClient from "hearald/client";
+
+const h = hearaldClient({
+  endpoint: "/events",
+  getUserId: () => currentUserId, // used when an event does not name a user
+  onError: (err, eventName) => {}, // a failed send never throws; a 404 or 500 from the server counts as failed
+});
+
+h.trackEvent({ eventName: "app_open", payload: { platform: "web" } });
+h.trackVisit({ userId: "user-123" }); // adds user agent, referrer, URL and screen size
+window.addEventListener("error", (error) => h.trackError({ error })); // ErrorEvent or Error
+h.dispose(); // stop sending (calling hearaldClient again also replaces the previous one; an old
+             // instance's dispose() only stops that instance)
 ```
 
-### Analytics Helpers
+## Stat definitions
 
 ```js
-import {
-  iso,
-  getData,
-  fetchChartData,
-  fetchData,
-  numFormatter,
-} from "hearald/shared/analyticsClientHelpers.js";
+const statDefinitions = {
+  raw_metrics: {
+    // count events
+    "opens": { aggregator: "count", event: "app_open" },
+    // the set of users who sent an event, optionally only with certain parameter values
+    "users.web": { aggregator: "set_of_users", event: "app_open", filter: { platform: "web" } },
+    // [value, count] pairs for one parameter, most common first
+    "errors.by_code": { aggregator: "histogram", event: "sync_error", field: "code" },
+    // read the visits file instead of the main log
+    "visits": { aggregator: "count", event: "visit", source_file_suffix: "visits" },
+  },
+  computed_metrics: {
+    "users.web_count": { formula: "set_count", metrics: ["users.web"] },
+    "users.new": { formula: "set_difference", metrics: ["users.week", "users.before"] }, // in the first, not the others
+    "conversion": { formula: "percent", metrics: ["buyers", "users"] }, // first / second * 100
+    "opens.per_day": { formula: "rate_time_window", metrics: ["opens"] },
+  },
+  ui: { sections: [{ title: "People", fields: [{ key: "users.web_count", label: "Web users", type: "number" }] }] },
+};
 ```
 
-### Admin Stats Endpoint
+Names with dots become nested objects in the result. `hidden: true` leaves a metric out of the output
+(useful for sets that only feed a computed metric). A computed metric that names a formula that does
+not exist is an error; one whose inputs are missing is simply left out.
 
-The adminStatsEndpoint has been removed. For admin statistics, use the analytics router provided by hearald/server/analytics.js.
-Example:
+## Dashboard routes
 
-```js
-import { createAnalyticsRouter } from 'hearald/server/analytics.js';
-app.use('/admin/stats', createAnalyticsRouter({...}));
-```
+Under wherever you mounted `analyticsMiddleware`: `/` (the page), `/layout` (your `ui`), and
+`/data/:days/:endDate?` (for example `/data/7/2026-11-01`: the 7 days ending that day; `endDate`
+defaults to yesterday). `days` is 1 to 366 and `endDate` must be a real calendar date (`2026-02-31` is not),
+otherwise 400. A window whose event files add up to more than `maxWindowBytes` (64 MB by default) is
+refused with 413 `{ "error": "window too large" }`; stats are computed one request at a time, because a
+window is held in memory while it is counted. Windows that end today or later are computed on every
+request; finished windows are cached in `eventsDir` as `summary:<end date>:<days>:<hash>.json`, where the
+hash covers your metric definitions, so changing a definition recomputes instead of serving old numbers.
+Cached summaries are safe to delete at any time.
 
-### Admin Stats Client Fetcher
+## Days and time zones
 
-```js
-import { fetchAdminStats } from "hearald/client/adminStatsClient.js";
-const stats = await fetchAdminStats();
-```
+Events are bucketed into days with `nowFn` (default: the current Pacific wall-clock time, with
+daylight saving) and `isoFn` (the UTC date of what `nowFn` returns). Pass `nowFn: () => new Date()` to
+bucket by UTC days instead. Nothing depends on the server's own time zone.
+
+With the default `nowFn`, the `t` stored in each event is also the Pacific wall-clock time, written with a
+`Z` as if it were UTC (so noon UTC is stored as 05:00 or 04:00, and two instants an hour apart at the
+November clock change get the same `t`). It is right for choosing the day, wrong as an exact instant. If
+you need real instants in the logs, pass `nowFn: () => new Date()` and accept UTC days.
 
 ## Roadmap
 
-See TODO.md for next steps and roadmap.
+See TODO.md.

package/dist/analytics.html

@@ -461,7 +461,7 @@ th {
       onLoadProgress(i, n);
 
       const json = await getDataFn({ n: 1, d: iso(day) });
-      const v = json.metrics[context][field] || 0;
+      const v = json?.metrics?.[context]?.[field] || 0;
 
       data.unshift({ date: iso(day), value: v });
       max = Math.max(max, v);
@@ -687,14 +687,14 @@ th {
       fetchStats: getJson,
     });
 
-  let UI = [];
+  let UI = {};
 
   async function fetchUI() {
     try {
       const res = await fetch(window.location.href + "/layout");
-      UI = await res.json();
+      UI = (await res.json()) || {};
     } catch (e) {
-      UI = [];
+      UI = {};
     }
   }
 
@@ -830,7 +830,7 @@ th {
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             m`
                               <option
@@ -899,7 +899,7 @@ th {
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
                   return m`
                     <section class="analytics analytics--${statsSection.id}">
                       ${statsSection.menuName !== "" &&

package/dist/index.js

@@ -63,7 +63,7 @@
       onLoadProgress(i, n);
 
       const json = await getDataFn({ n: 1, d: iso(day) });
-      const v = json.metrics[context][field] || 0;
+      const v = json?.metrics?.[context]?.[field] || 0;
 
       data.unshift({ date: iso(day), value: v });
       max = Math.max(max, v);
@@ -289,14 +289,14 @@
       fetchStats: getJson,
     });
 
-  let UI = [];
+  let UI = {};
 
   async function fetchUI() {
     try {
       const res = await fetch(window.location.href + "/layout");
-      UI = await res.json();
+      UI = (await res.json()) || {};
     } catch (e) {
-      UI = [];
+      UI = {};
     }
   }
 
@@ -432,7 +432,7 @@
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             m`
                               <option
@@ -501,7 +501,7 @@
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
                   return m`
                     <section class="analytics analytics--${statsSection.id}">
                       ${statsSection.menuName !== "" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hearald",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "A single server drop-in file system based metrics and analytics library.",
   "main": "src/index.js",
   "exports": {
@@ -9,7 +9,10 @@
   },
   "type": "module",
   "scripts": {
-    "build": "rollup --config"
+    "build": "rollup --config",
+    "test": "npm run test:express5 && npm run test:express4",
+    "test:express5": "HEARALD_EXPRESS=5 node --import ./test-support/register.js --test",
+    "test:express4": "HEARALD_EXPRESS=4 node --import ./test-support/register.js --test"
   },
   "keywords": [
     "herald",
@@ -21,10 +24,10 @@
   "license": "MIT",
   "dependencies": {
     "bussin-js": "^1.0.1",
-    "chalk": "^4.1.0",
-    "express": "^4.17.1"
+    "chalk": "^4.1.0"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.14.6",
     "@rollup/plugin-commonjs": "^15.1.0",
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.3.0",
@@ -35,6 +38,9 @@
     "eslint-plugin-jsx-a11y": "^6.6.1",
     "eslint-plugin-react": "^7.31.10",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "express": "^5.2.1",
+    "express4": "npm:express@^4.21.2",
+    "happy-dom": "^20.14.6",
     "htm": "^3.0.3",
     "preact": "^10.3.3",
     "prettier": "2.2.1",
@@ -45,5 +51,15 @@
     "rollup-plugin-postcss": "^4.0.2",
     "rollup-plugin-terser": "^7.0.2",
     "style-inject": "^0.3.0"
-  }
+  },
+  "peerDependencies": {
+    "express": ">=4"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
 }

package/src/client.js

@@ -20,8 +20,10 @@ const trackError = ({
   userId = null,
   payload: extraPayload = {},
 } = {}) => {
-  const errorEvent = error;
-  const errorObject = error.error;
+  // `error` is normally the ErrorEvent from window.onerror, whose `.error` can be null (for example
+  // for errors from other origins), or a plain Error.
+  const errorEvent = error || {};
+  const errorObject = errorEvent.error || (error instanceof Error ? error : {});
 
   let source;
   if (errorObject.stack) {
@@ -35,7 +37,7 @@ const trackError = ({
     eventName: "error",
     userId,
     payload: {
-      message: errorObject.message,
+      message: errorObject.message || errorEvent.message || String(error),
       source,
       file_name: errorEvent.filename || errorObject.fileName,
       line_number: errorEvent.lineno || errorObject.lineNumber,
@@ -73,30 +75,48 @@ function emitEventToServer({
   });
 }
 
+let activeListener = null;
+
 export default function hearald({
   endpoint = "/e",
-  fetchImpl = fetch,
+  fetchImpl = (...args) => globalThis.fetch(...args),
   getUserId = () => null,
   onError = () => {} /* err, eventName, userId, payload */,
 } = {}) {
-  eventBus.on("event", async (event) => {
+  // The event bus is shared, so a second call (a hot reload, say) replaces the first listener
+  // instead of sending every event twice.
+  if (activeListener) eventBus.off("event", activeListener);
+  const listener = async (event) => {
     const { eventName, userId: emittedUserId, payload } = event;
     const userId = emittedUserId || getUserId() || null;
 
     try {
-      await emitEventToServer({
+      const response = await emitEventToServer({
         endpoint,
         eventName,
         userId,
         payload,
         fetchImpl,
       });
+      // fetch only rejects on network failure; a 404 or 500 arrives as an ordinary response
+      if (response && response.ok === false) {
+        throw new Error(
+          `hearald: the server answered ${response.status} for "${eventName}"`
+        );
+      }
     } catch (err) {
       onError(err, eventName, userId, payload);
     }
-  });
+  };
+  activeListener = listener;
+  eventBus.on("event", listener);
 
   return {
+    // Removes only this instance's listener: an older instance's dispose() must not silence a newer one.
+    dispose() {
+      eventBus.off("event", listener);
+      if (activeListener === listener) activeListener = null;
+    },
     eventBus,
     trackEvent,
     trackError,

package/src/index.js

@@ -8,15 +8,27 @@ import {
   shutDown,
 } from "./server/server.js";
 import { createAnalyticsRouter } from "./server/analytics.js";
+import { purgeOldEvents } from "./server/serverEvents.js";
+import { basicAuth } from "./server/auth.js";
+
+export { basicAuth, purgeOldEvents };
 
 export default function hearald({
   /* singleton configuration options */
   logLevel,
   nowFn /* () => nowAsDateString */,
   getUserId /* (req) => userId */,
+  eventsDir /* where event logs are kept; default "events" */,
+  idleCloseMs /* how long an event file stays open after its last write; default 60000 */,
+  maxWindowBytes /* the most event-log bytes one dashboard request may read; default 64 MB */,
 
-  eventEndpoint: { url = "/e", parseBody } = {},
-  analytics: { enabled: analyticsEnabled = true, statDefinitions } = {},
+  eventEndpoint: { url = "/e", parseBody, schema } = {},
+  analytics: {
+    enabled: analyticsEnabled = true,
+    statDefinitions,
+    auth,
+    allowUnauthenticated,
+  } = {},
 } = {}) {
   if (logLevel) {
     hearaldConfiguration.setLogLevel(logLevel);
@@ -27,12 +39,23 @@ export default function hearald({
   if (getUserId) {
     hearaldConfiguration.setGetUserId(getUserId);
   }
+  if (eventsDir) {
+    hearaldConfiguration.setEventsDir(eventsDir);
+  }
+
+  if (idleCloseMs !== undefined) {
+    hearaldConfiguration.setIdleCloseMs(idleCloseMs);
+  }
+  if (maxWindowBytes !== undefined) {
+    hearaldConfiguration.setMaxWindowBytes(maxWindowBytes);
+  }
 
-  const eventMiddleware = eventEndpointMiddleware({ url, parseBody });
+  const eventMiddleware = eventEndpointMiddleware({ url, parseBody, schema });
 
-  const analyticsMiddleware = analyticsEnabled
-    ? createAnalyticsRouter({ statDefinitions })
-    : null;
+  const analyticsMiddleware =
+    analyticsEnabled && statDefinitions
+      ? createAnalyticsRouter({ statDefinitions, auth, allowUnauthenticated })
+      : null;
 
   const errorMiddlware = errorTrackingMiddleware({});
 
@@ -42,6 +65,7 @@ export default function hearald({
     analyticsMiddleware /* app.use('/analytics', analyticsMiddleware) */,
     trackServerEvent /* ({ event, time = null, userId, params = {} }) => Promise } */,
     trackServerError /* ({ error, userId = null, extraParams = {} }) => Promise } */,
+    purgeOldEvents /* ({ days }) => Promise<number of files removed> */,
     shutDown,
   };
 }

package/src/public/js/App.js

@@ -75,14 +75,14 @@ const getDataFn = ({ n, d, q }) =>
     fetchStats: getJson,
   });
 
-let UI = [];
+let UI = {};
 
 async function fetchUI() {
   try {
     const res = await fetch(window.location.href + "/layout");
-    UI = await res.json();
+    UI = (await res.json()) || {};
   } catch (e) {
-    UI = [];
+    UI = {};
   }
 }
 
@@ -218,7 +218,7 @@ class App extends Component {
                         name="context"
                         onchange=${(e) => this.changeChartContext(e)}
                       >
-                        ${UI.chartContexts.map(
+                        ${(UI.chartContexts || []).map(
                           ({ id, menuName }) =>
                             html`
                               <option
@@ -287,7 +287,7 @@ class App extends Component {
                     `}
                   </div>
                 </section>
-                ${UI.sections.map((statsSection) => {
+                ${(UI.sections || []).map((statsSection) => {
                   return html`
                     <section class="analytics analytics--${statsSection.id}">
                       ${statsSection.menuName !== "" &&

package/src/public/js/util.js

@@ -48,7 +48,7 @@ export async function fetchChartData({
     onLoadProgress(i, n);
 
     const json = await getDataFn({ n: 1, d: iso(day) });
-    const v = json.metrics[context][field] || 0;
+    const v = json?.metrics?.[context]?.[field] || 0;
 
     data.unshift({ date: iso(day), value: v });
     max = Math.max(max, v);