hearald 0.0.1

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+    "browser": true,
+    "node": true,
+    "es2020": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "globals": {
+    "Intl": "readonly"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Pariser
+
+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

@@ -0,0 +1,81 @@
+# hearald
+
+A whimsical event bus and evented utility for client and server, with event tracking, error logging, and analytics/statistics helpers.
+
+## Status (August 2025)
+
+- ✅ Event bus/evented logic fully extracted and modularized
+- ✅ Server-side event file logic (read/write/close/load) extracted
+- ✅ Client/server event emit logic and `/e` endpoint extracted
+- ✅ Admin stats endpoint and client fetch utility extracted
+- ✅ Analytics client helpers (iso, getData, fetchChartData, fetchData, numFormatter, dataCache) extracted
+- ✅ Client/server/shared subfolders created and migration in progress
+- ✅ Error tracking utilities and Express error middleware added
+- ✅ Integration examples and usage documentation provided
+- ✅ `.eslintrc` added to declare `Intl` as a global for linting
+- ✅ Lint passes and all functionality verified
+- ⏳ Migration of all helpers to client/server/shared nearly complete
+- ⏳ Custom event tracking, configurable stat definitions, embeddable admin UI, and further documentation/testing are next
+
+## Usage
+
+### Tracking User Visits (Client)
+
+```js
+import { trackVisit } from "hearald/client/trackVisit.js";
+trackVisit({ userId: "user-123" });
+```
+
+### Tracking Errors (Client)
+
+```js
+import { trackError } from "hearald/client/trackError.js";
+try {
+  // ...code...
+} catch (err) {
+  trackError(err);
+}
+```
+
+### Tracking Errors (Server)
+
+```js
+import {
+  trackServerError,
+  errorTrackingMiddleware,
+} from "hearald/server/serverTrackError.js";
+app.use(errorTrackingMiddleware);
+```
+
+### Analytics Helpers
+
+```js
+import {
+  iso,
+  getData,
+  fetchChartData,
+  fetchData,
+  numFormatter,
+} from "hearald/shared/analyticsClientHelpers.js";
+```
+
+### Admin Stats Endpoint
+
+The adminStatsEndpoint has been removed. For admin statistics, use the analytics router provided by hearald/server/analytics.js.
+Example:
+
+```js
+import { createAnalyticsRouter } from 'hearald/server/analytics.js';
+app.use('/admin/stats', createAnalyticsRouter({...}));
+```
+
+### Admin Stats Client Fetcher
+
+```js
+import { fetchAdminStats } from "hearald/client/adminStatsClient.js";
+const stats = await fetchAdminStats();
+```
+
+## Roadmap
+
+See TODO.md for next steps and roadmap.

package/TODO.md

@@ -0,0 +1,34 @@
+# hearald TODO
+
+## Status (August 2025)
+
+- Event bus/evented logic, event file helpers, emit logic, admin stats, analytics helpers, and error tracking utilities have all been extracted and modularized.
+- hearald now uses client/server/shared subfolders and has a working .eslintrc for Intl.
+- Lint passes and all functionality is verified.
+- Migration of all helpers to client/server/shared is nearly complete.
+
+## Next Steps for hearald
+
+1. **Tracking Custom Events**
+
+   - Make the event schema/config easy to extend (document how to define custom events)
+   - Provide a clear API for emitting custom events (e.g., `trackEvent('my_event', {...})`)
+
+2. **Generating Statistical Summary Views**
+
+   - Make stat definitions configurable (allow user to provide their own stat_definition.json)
+   - Expose a summary API (e.g., `generateStats(endDate, timeWindow)`)
+   - Document how to add new metrics and computed stats
+
+3. **Admin UI to See Stats**
+   - Provide a basic, embeddable React/Preact/Vue component for admin stats (or a template)
+   - Document how to use the endpoint and client fetcher in any admin UI
+   - Optionally, provide a standalone admin page as part of the package
+
+## General Improvements
+
+- Write clear documentation and usage examples
+- Add configuration options for stat definitions and event types
+- Provide ready-to-use middleware and client helpers for common event types
+- Package a basic admin UI or template
+- Test in a clean, new project to validate ease of adoption

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "hearald",
+  "version": "0.0.1",
+  "description": "A single server drop-in file system based metrics and analytics library.",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "rollup --config"
+  },
+  "keywords": [
+    "herald",
+    "analytics"
+  ],
+  "author": "pariser",
+  "homepage": "https://github.com/pariser/hearald",
+  "repository": "https://github.com/pariser/hearald",
+  "license": "MIT",
+  "dependencies": {
+    "bussin-js": "^1.0.1",
+    "chalk": "^4.1.0",
+    "express": "^4.17.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^15.1.0",
+    "@rollup/plugin-json": "^4.1.0",
+    "@rollup/plugin-node-resolve": "^13.3.0",
+    "@rollup/plugin-replace": "^2.3.3",
+    "@web/rollup-plugin-html": "^2.3.0",
+    "eslint": "^8.27.0",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jsx-a11y": "^6.6.1",
+    "eslint-plugin-react": "^7.31.10",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "htm": "^3.0.3",
+    "preact": "^10.3.3",
+    "prettier": "2.2.1",
+    "rollup": "^2.79.2",
+    "rollup-plugin-embed-css": "^1.0.26",
+    "rollup-plugin-generate-html-template": "^1.7.0",
+    "rollup-plugin-output-manifest": "^2.0.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "rollup-plugin-terser": "^7.0.2",
+    "style-inject": "^0.3.0"
+  }
+}

package/public/analytics.html

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Analytics</title>
+
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, viewport-fit=cover, user-scalable=no"
+    />
+
+    <link rel="stylesheet" href="./css/analytics.css" />
+  </head>
+
+  <body>
+    <div id="analytics-root"></div>
+    <script src="./js/index.js" defer></script>
+  </body>
+</html>

package/public/css/analytics.css

@@ -0,0 +1,381 @@
+:root {
+  --global-max-width: 480px;
+
+  --border-radius: 4px;
+
+  /* Fonts */
+  --font-sans-serif: Raleway, sans-serif;
+
+  /* Colors: start point https://color.adobe.com/Architecture-color-theme-20477657 */
+  --color-black: hsla(214, 94%, 7%, 1);
+  --color-dark: hsla(209, 37%, 18%, 1);
+  --color-mid: hsla(196, 34%, 48%, 1);
+  --color-light: hsla(191, 20%, 68%, 1);
+  --color-accent: hsla(38, 85%, 64%, 1);
+  --color-white: hsla(38, 38%, 90%, 1);
+
+  --color-text: var(--color-white);
+  --color-label: var(--color-light);
+
+  --color-link: var(--color-accent);
+  --color-link-hover: var(--color-light);
+  --color-title: var(--color-accent);
+
+  --color-bg: var(--color-black);
+  --color-menu: var(--color-dark);
+
+  --color-input-bg: var(--color-white);
+  --color-input-text: var(--color-dark);
+
+  --color-button-bg: var(--color-mid);
+  --color-button-bg-hover: var(--color-light);
+  --color-button-text: var(--color-black);
+
+  --color-logo-sign: var(--color-success);
+
+  --color-success: #127d44;
+  --color-error: #ad2e41;
+
+  --animation-plop: plop 300ms ease-out forwards;
+
+  --hero-box-shadow: 0 0 0.75em rgba(0, 0, 0, 0.75);
+
+  --carousel-hover-transition: 80ms ease-out transform;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    --color-text: var(--color-dark);
+    --color-label: hsla(196, 34%, 38%, 1);
+
+    --color-link: var(--color-mid);
+    --color-link-hover: var(--color-light);
+    --color-title: var(--color-dark);
+
+    --color-bg: #fff;
+    --color-menu: #fff;
+
+    --color-input-bg: var(--color-white);
+    --color-input-text: var(--color-dark);
+
+    --color-button-bg: var(--color-mid);
+    --color-button-bg-hover: var(--color-light);
+    --color-button-text: var(--color-black);
+
+    --color-logo-sign: var(--color-success);
+  }
+}
+
+html {
+  height: 100%;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  font-family: var(--font-sans-serif);
+  line-height: 1.6;
+  font-size: 14px;
+  background: var(--color-bg);
+  margin: 0;
+  height: 100%;
+  -webkit-text-size-adjust: none;
+  text-size-adjust: none;
+  color: var(--color-text);
+}
+
+/* need this to override the user style sheet in chrome, which has higher
+   specificity than inheriting the font style tag from the body */
+input {
+  font-family: var(--font-sans-serif);
+}
+
+body.lock-zoom {
+  touch-action: none;
+  overscroll-behavior-y: none;
+}
+
+h1 {
+  font-family: var(--font-sans-serif);
+  font-size: 2.5em;
+  margin: 0;
+}
+
+h2 {
+  font-family: var(--font-sans-serif);
+  font-size: 1.5em;
+  margin: 0;
+}
+
+td,
+th {
+  padding: 0 0.5em;
+}
+
+th {
+  text-align: left;
+  font-size: 0.8em;
+}
+
+@media screen and (max-width: 640px) {
+  body {
+    font-size: 12px;
+    font-feature-settings: 'lnum';
+  }
+}
+
+.hidden {
+  display: none !important;
+}
+
+.header__logo,
+.header__button {
+  width: 2rem;
+  height: 2rem;
+  font-size: 2rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  text-decoration: none;
+}
+
+.header__button:hover {
+  text-decoration: none;
+}
+
+.header__button--has-menu {
+  cursor: pointer;
+}
+
+/* ---- */
+
+.analytics__header {
+  grid-area: header;
+  padding: 2em;
+  background-color: var(--color-dark);
+  display: flex;
+  gap: 2em;
+  align-items: center;
+  grid-template-columns: auto auto auto auto 1fr;
+}
+
+.analytics {
+  --analytics-grid-columns: 4;
+
+  display: grid;
+  grid-template-columns: repeat(var(--analytics-grid-columns), 1fr);
+  grid-gap: 0.5em;
+  padding: 1em;
+}
+
+.analytics__title {
+  grid-column: span var(--analytics-grid-columns);
+}
+
+.analytics__tile {
+  display: flex;
+  /* flex: 1fr 5fr; */
+  flex: 1 1 auto;
+  flex-direction: column;
+  border: 1px solid var(--color-accent);
+}
+
+.analytics__tile--end-row {
+  border: 0;
+  grid-column: span var(--analytics-grid-columns);
+}
+
+.analytics__tile__header {
+  padding: 0.2em 0.5em;
+  border-bottom: 1px solid var(--color-accent);
+}
+.analytics__tile__value {
+  padding: 0.2em 0.5em;
+  margin: 0 auto;
+  font-size: 2.5em;
+  font-weight: 600;
+}
+
+.analytics__menu {
+  grid-column: 1 /1;
+  display: flex;
+  gap: 1em;
+  align-items: center;
+}
+
+.analytics__menu > label {
+  display: flex;
+  gap: 0.5em;
+  align-items: center;
+}
+
+.analytics__menu > button {
+  font-size: 9px;
+  line-height: 9px;
+  height: 18px;
+}
+
+.bar-chart {
+  grid-column: 1/-1;
+  height: 200px;
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  grid-template-columns: 1fr;
+  gap: 2px;
+  position: relative;
+  align-items: end;
+  margin-top: 1em;
+  padding: 0 1.5em 0 0;
+  border-bottom: 1px solid var(--color-light);
+}
+.bar-chart__bar {
+  background: var(--color-mid);
+  height: calc(var(--bar-height) * 100%);
+  position: relative;
+}
+.bar-chart__bar__label {
+  display: none;
+  position: absolute;
+  bottom: calc(100% + 0.75em);
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 2;
+  background: var(--color-label);
+  padding: 0.25em 0.5em;
+  border-radius: 0.25em;
+  text-align: center;
+  white-space: nowrap;
+  word-break: keep-all;
+}
+.bar-chart__bar__label:after {
+  content: '';
+  width: 12px;
+  height: 12px;
+  background: var(--color-label);
+  position: absolute;
+  margin: auto;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  transform: translateY(50%) rotate(45deg);
+  z-index: 1;
+}
+.bar-chart__bar:hover {
+  background: var(--color-light);
+}
+.bar-chart__bar:hover > .bar-chart__bar__label {
+  display: block;
+}
+.bar-chart__empty {
+  place-self: center;
+}
+.bar-chart__scale {
+  align-self: start;
+  border-top: 1px solid var(--color-light);
+  border-right: 1px solid var(--color-light);
+  height: 100%;
+  padding-right: 0.2em;
+  text-align: right;
+}
+
+.analytics__tile__histogram {
+  list-style-type: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 1em;
+  grid-column: 1/-1;
+  min-height: 10em;
+  max-height: 20em;
+  overflow: auto;
+  align-items: start;
+  grid-auto-rows: max-content;
+  padding: 0.5em 0.5em;
+}
+.analytics__tile__histogram__value {
+  text-align: right;
+}
+.analytics__tile__histogram__row {
+  display: grid;
+  grid-template-columns: subgrid;
+  grid-column: 1/-1;
+  align-self: start;
+}
+.analytics__tile__histogram__label {
+  position: relative;
+  background-image: linear-gradient(
+    to right,
+    var(--color-mid) calc(var(--bar-width) * 100%),
+    transparent calc(var(--bar-width) * 100%)
+  );
+  background-size: 100%;
+  padding: 0 0.5em;
+  min-width: 0;
+  min-height: 0;
+}
+
+.analytics__tile--span-2 {
+  grid-column: span 2;
+}
+
+@media screen and (max-width: 640px) {
+  .analytics {
+    --analytics-grid-columns: 2;
+  }
+
+  .analytics__tile--end-row {
+    display: none !important;
+  }
+
+  .analytics__tile--span-2 {
+    grid-column: span 1;
+  }
+}
+
+@media screen and (max-width: 380px) {
+  .analytics {
+    --analytics-grid-columns: 1;
+  }
+
+  .analytics__header__input {
+    width: 35%;
+  }
+
+  .analytics__menu > label {
+    display: grid;
+  }
+
+  .bar-chart {
+    grid-auto-flow: row;
+    height: auto;
+    border-bottom: 0;
+    border-left: 1px solid var(--color-light);
+    padding: 0;
+  }
+  .bar-chart__scale {
+    height: auto;
+    width: 100%;
+    border-top: 0;
+    border-bottom: 1px solid var(--color-light);
+    border-right: 1px solid var(--color-light);
+  }
+  .bar-chart__bar {
+    height: 0.5em;
+    width: calc(var(--bar-height) * 100%);
+  }
+  .bar-chart__bar__label {
+    left: 0.5em;
+    transform: translateX(0);
+  }
+  .bar-chart__bar__label:after {
+    left: 3px;
+    right: auto;
+    bottom: 0;
+    transform: translateY(50%) rotate(45deg);
+  }
+}

package/public/js/.eslintrc

@@ -0,0 +1,9 @@
+{
+  "env": {
+    "browser": true,
+    "es2020": true
+  },
+  "globals": {
+    "INJECTED__DATE": "readonly"
+  }
+}