hearald 0.0.2 → 0.0.4

package/README.md

@@ -1,21 +1,11 @@
 # 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
+A single server drop-in file system based metrics and analytics library.
+
+## 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
 

package/dist/analytics.html

@@ -427,7 +427,6 @@ th {
     const endpoint = endpointBuilder
       ? endpointBuilder(n, d, q)
       : `/data/${n}/${d}${q ? "?" + q : ""}`;
-    console.log("endpoint", endpoint);
 
     const data = await fetchStats(endpoint);
     dataCache[key] = data;
@@ -931,8 +930,6 @@ th {
     }
   }
 
-  console.log("index.js loaded");
-
   G(m` <${App} /> `, document.getElementById("analytics-root"));
 
 })();

package/dist/index.js

@@ -29,7 +29,6 @@
     const endpoint = endpointBuilder
       ? endpointBuilder(n, d, q)
       : `/data/${n}/${d}${q ? "?" + q : ""}`;
-    console.log("endpoint", endpoint);
 
     const data = await fetchStats(endpoint);
     dataCache[key] = data;
@@ -533,8 +532,6 @@
     }
   }
 
-  console.log("index.js loaded");
-
   G(m` <${App} /> `, document.getElementById("analytics-root"));
 
 })();

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "hearald",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "A single server drop-in file system based metrics and analytics library.",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
   "type": "module",
   "scripts": {
     "build": "rollup --config"

package/rollup.config.js

@@ -40,7 +40,7 @@ function inlineAssetsPlugin({ htmlFile, outputFile }) {
 }
 
 export default {
-  input: "public/js/index.js", // Use JS entry point
+  input: "src/public/js/index.js", // Use JS entry point
   output: {
     dir: "dist",
     format: "iife",
@@ -52,7 +52,7 @@ export default {
       extract: true,
     }),
     inlineAssetsPlugin({
-      htmlFile: "public/analytics.html",
+      htmlFile: "src/public/analytics.html",
       outputFile: "analytics.html",
     }),
   ],

package/src/client.js

@@ -0,0 +1,105 @@
+import { EventBus } from "bussin-js";
+
+// Shared event bus for all tracking events
+export const eventBus = new EventBus([]);
+
+function trackEvent({ eventName, userId = null, payload = {} } = {}) {
+  eventBus.emit("event", { eventName, userId, payload });
+}
+
+const generateVisitorData = () => ({
+  user_agent: navigator.userAgent || "unknown",
+  referrer: document.referrer || "none",
+  url: window.location.toString(),
+  screen_resolution: `${screen.width}x${screen.height}`,
+  window_resolution: `${window.innerWidth}x${window.innerHeight}`,
+});
+
+const trackError = ({
+  error,
+  userId = null,
+  payload: extraPayload = {},
+} = {}) => {
+  const errorEvent = error;
+  const errorObject = error.error;
+
+  let source;
+  if (errorObject.stack) {
+    const splitStack = errorObject.stack.split("\n");
+    if (splitStack.length > 2) {
+      source = splitStack[1].trim();
+    }
+  }
+
+  trackEvent({
+    eventName: "error",
+    userId,
+    payload: {
+      message: errorObject.message,
+      source,
+      file_name: errorEvent.filename || errorObject.fileName,
+      line_number: errorEvent.lineno || errorObject.lineNumber,
+      column_number: errorEvent.colno || errorObject.columnNumber,
+      ...generateVisitorData(),
+      ...extraPayload,
+    },
+  });
+};
+
+const trackVisit = ({ userId, payload: extraPayload = {} } = {}) => {
+  trackEvent({
+    eventName: "visit",
+    userId,
+    payload: {
+      ...generateVisitorData(),
+      ...extraPayload,
+    },
+  });
+};
+
+function emitEventToServer({
+  endpoint = "/e",
+  eventName,
+  userId,
+  payload = {},
+  fetchImpl = fetch,
+}) {
+  return fetchImpl(endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ e: eventName, u: userId, p: payload }),
+  });
+}
+
+export default function hearald({
+  endpoint = "/e",
+  fetchImpl = fetch,
+  getUserId = () => null,
+  onError = () => {} /* err, eventName, userId, payload */,
+} = {}) {
+  eventBus.on("event", async (event) => {
+    const { eventName, userId: emittedUserId, payload } = event;
+    const userId = emittedUserId || getUserId() || null;
+
+    try {
+      await emitEventToServer({
+        endpoint,
+        eventName,
+        userId,
+        payload,
+        fetchImpl,
+      });
+    } catch (err) {
+      onError(err, eventName, userId, payload);
+    }
+  });
+
+  return {
+    eventBus,
+    trackEvent,
+    trackError,
+    trackVisit,
+  };
+}

package/src/index.js

@@ -0,0 +1,25 @@
+import log from "./server/logger.js";
+import { eventEndpointMiddleware, shutDown } from "./server/server.js";
+import { createAnalyticsRouter } from "./server/analytics.js";
+
+export default function hearald({
+  logLevel,
+  eventEndpoint: { url = "/e", parseBody } = {},
+  analytics: { enabled: analyticsEnabled = true, statDefinitions } = {},
+} = {}) {
+  if (logLevel) {
+    log.setLogLevel(logLevel);
+  }
+
+  const eventMiddleware = eventEndpointMiddleware({ url, parseBody });
+
+  const analyticsMiddleware = analyticsEnabled
+    ? createAnalyticsRouter({ statDefinitions })
+    : null;
+
+  return {
+    eventMiddleware,
+    analyticsMiddleware,
+    shutDown,
+  };
+}

package/{public → src/public}/js/.eslintrc

@@ -2,8 +2,5 @@
   "env": {
     "browser": true,
     "es2020": true
-  },
-  "globals": {
-    "INJECTED__DATE": "readonly"
   }
 }

package/{public → src/public}/js/App.js

@@ -8,7 +8,7 @@ import {
   fetchChartData,
   fetchData,
 } from "./util.js";
-import Tile from "./Tile";
+import Tile from "./Tile.js";
 
 const DATE = new Date().toISOString().split("T")[0];
 

package/{public → src/public}/js/index.js

@@ -1,7 +1,5 @@
 import "../css/analytics.css";
 
-console.log("index.js loaded");
-
 import { render, html } from "htm/preact";
 
 import App from "./App";

package/{public → src/public}/js/util.js

@@ -14,7 +14,6 @@ export async function getData({ n, d, q, endpointBuilder, fetchStats }) {
   const endpoint = endpointBuilder
     ? endpointBuilder(n, d, q)
     : `/data/${n}/${d}${q ? "?" + q : ""}`;
-  console.log("endpoint", endpoint);
 
   const data = await fetchStats(endpoint);
   dataCache[key] = data;

package/{server → src/server}/analytics.js

@@ -4,6 +4,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { readFile, writeFile } from "fs/promises";
 import express from "express";
+import log from "./logger.js";
 import {
   omitProperties,
   iso,
@@ -234,13 +235,13 @@ export async function handleAnalyticsDataRequest({
   }
   const dataFromFile = await readMetricsFromCache(endDateIso, timeWindow);
   if (dataFromFile) {
-    console.log(
+    log.info(
       `Analytics for ${timeWindow} days ending on ${endDateIso} returned from cache`
     );
     response.status(200).type("application/json").send(dataFromFile);
     return;
   }
-  console.log(
+  log.info(
     `Analytics for ${timeWindow} days ending on ${endDateIso} computing from events`
   );
   try {
@@ -256,7 +257,7 @@ export async function handleAnalyticsDataRequest({
     );
     response.status(200).type("application/json").send(JSON.stringify(stats));
   } catch (e) {
-    console.error("failed to compute analytics", e);
+    log.error("failed to compute analytics", e);
     response
       .status(500)
       .type("application/json")
@@ -267,22 +268,15 @@ export async function handleAnalyticsDataRequest({
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-console.log("filename is", __filename);
-console.log("dirname is", __dirname);
+log.info("filename is", __filename);
+log.info("dirname is", __dirname);
 
-export function createAnalyticsRouter({
-  statDefinitions,
-  loadEventsOverWindow,
-  templateReplaceMany,
-  analyticsHtmlPath,
-  enableLiveReload,
-  environment,
-}) {
-  console.log("statManifest", statDefinitions);
+export function createAnalyticsRouter({ statDefinitions }) {
+  log.info("statManifest", statDefinitions);
   const router = express.Router();
 
   router.get(`/data/:last/:date?`, async (request, response) => {
-    console.log(chalk.cyan("[API] GET /analytics/data/:last/:date?"));
+    log.info(chalk.cyan("[API] GET /analytics/data/:last/:date?"));
     await handleAnalyticsDataRequest({
       request,
       response,
@@ -297,23 +291,10 @@ export function createAnalyticsRouter({
   });
 
   router.get(`/`, async (request, response) => {
-    console.log(chalk.cyan("[Render] views/analytics.html loading"));
-    console.log(path.join(__dirname, "..", "dist", "analytics.html"));
     const fileContents = await readFile(
-      path.join(__dirname, "..", "dist", "analytics.html")
+      path.join(__dirname, "..", "..", "dist", "analytics.html")
     );
-    const analyticsHtmlRaw = fileContents.toString("utf-8");
-    console.log("analyticsHtmlRaw", analyticsHtmlRaw);
-    const yesterday = nowAsPstDate();
-    yesterday.setDate(yesterday.getDate() - 1);
-    const analyticsHtml = templateReplaceMany(analyticsHtmlRaw, {
-      date: yesterday.toISOString().split("T")[0],
-      devHeadExtras:
-        environment === "development" && enableLiveReload
-          ? '<script src="/liveReloading.js"></script>'
-          : "",
-    });
-    console.log("analyticsHtml", analyticsHtml);
+    const analyticsHtml = fileContents.toString("utf-8");
     response.send(analyticsHtml);
   });
 

package/src/server/logger.js

@@ -0,0 +1,33 @@
+class Logger {
+  constructor(level) {
+    this.level = level || "info";
+  }
+
+  setLogLevel(level) {
+    this.level = level;
+  }
+
+  debug(...args) {
+    if (this.level === "debug") {
+      console.log("[DEBUG]", ...args);
+    }
+  }
+
+  info(...args) {
+    if (this.level === "debug" || this.level === "info") {
+      console.log("[INFO]", ...args);
+    }
+  }
+
+  warn(...args) {
+    if (this.level !== "error") {
+      console.warn("[WARN]", ...args);
+    }
+  }
+
+  error(...args) {
+    console.error("[ERROR]", ...args);
+  }
+}
+
+export default new Logger("error");

package/{server → src/server}/server.js

@@ -1,5 +1,6 @@
 // Express middleware for hearald event tracking
 import express from "express";
+import log from "./logger.js";
 import { nowAsPstDate } from "../shared/utils.js";
 import { writeEvent, closeEventFiles } from "./serverEvents.js";
 import { createAnalyticsRouter } from "./analytics.js";
@@ -19,7 +20,7 @@ export async function shutDown() {
  * @param {function} [options.parseBody] - Custom request body parser (req => {e, u, p}).
  * @returns {function} Express middleware
  */
-export function createHearaldMiddleware({ url = "/e", parseBody } = {}) {
+export function eventEndpointMiddleware({ url = "/e", parseBody } = {}) {
   const router = express.Router();
   router.post(url, async (req, res) => {
     try {
@@ -35,14 +36,9 @@ export function createHearaldMiddleware({ url = "/e", parseBody } = {}) {
       await logEvent(nowAsPstDate(), { e, u, p });
     } catch (err) {
       // eslint-disable-next-line no-console
-      console.error("error writing event to event log", err);
+      log.error("error writing event to event log", err);
     }
     res.status(204).send();
   });
   return router;
 }
-
-export function createHearaldAnalyticsRouter(options = {}) {
-  // Pass statManifest to the analytics router so /analytics/layout.json is available
-  return createAnalyticsRouter({ ...options });
-}

package/{server → src/server}/serverEvents.js

@@ -1,5 +1,6 @@
 import { readFile, open as openFile, mkdir } from "fs/promises";
 
+import log from "./logger.js";
 import { iso } from "../shared/utils.js";
 
 const eventFilePromises = new Map();
@@ -81,10 +82,10 @@ export const readEventsFromFile = async (fileName) => {
   } catch (e) {
     if (e.message && e.message.indexOf("ENOENT") !== -1) {
       // eslint-disable-next-line no-console
-      console.warn(`file not found: events/${fileName}.log`);
+      log.warn(`file not found: events/${fileName}.log`);
     } else {
       // eslint-disable-next-line no-console
-      console.error(e);
+      log.error(e);
     }
     return [];
   }

package/shared/events.js

@@ -1,44 +0,0 @@
-// Usage:
-// 1. Register custom events with a schema
-// 2. Emit custom events by name
-
-import { EventBus } from "bussin-js";
-
-// Shared event bus for all tracking events
-export const eventBus = new EventBus([]);
-
-const registeredEvents = {};
-
-/**
- * Registers a custom event type and its schema.
- * @param {string} eventName - The name of the event.
- * @param {object} schema - The schema definition for the event payload.
- */
-export function registerEvent(eventName, schema) {
-  // Prevent duplicate registration
-  if (registeredEvents[eventName]) return;
-  registeredEvents[eventName] = schema;
-  // Add the event type to the tracking event bus if not already present
-  if (!eventBus.hasType(eventName)) {
-    eventBus.addType(eventName);
-  }
-}
-
-/**
- * Emits a custom event if registered and payload matches schema.
- * @param {string} eventName - The name of the event to emit.
- * @param {object} payload - The event payload.
- * @returns {boolean} - True if emitted, false if not registered or invalid payload.
- */
-export function emitEvent(eventName, payload) {
-  const schema = registeredEvents[eventName];
-  if (!schema) return false;
-  // Simple schema validation: check required keys and types
-  for (const key in schema) {
-    if (!(key in payload)) return false;
-    if (typeof payload[key] !== schema[key]) return false;
-  }
-  // Emit on the shared tracking event bus
-  eventBus.emit(eventName, payload);
-  return true;
-}