express-sequelize-traffic 0.1.0 → 0.2.0

package/package.json

@@ -1,25 +1,31 @@
 {
   "name": "express-sequelize-traffic",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Privacy-first, self-hosted Express request analytics with Sequelize storage and an optional realtime dashboard.",
   "type": "module",
-  "main": "./src/index.js",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "workspaces": [
     "dashboard-app"
   ],
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
-    "src",
-    "examples",
+    "dist",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "dev": "npm run example",
-    "build": "npm run build:dashboard",
+    "build": "npm run build:package && npm run build:dashboard",
+    "build:package": "node scripts/build-package.mjs",
     "build:dashboard": "npm run build --workspace dashboard-app",
+    "preexample": "npm run build",
     "example": "node examples/express-app.js",
     "prepack": "npm run build"
   },
@@ -42,6 +48,7 @@
     "socket.io": "^4.8.1"
   },
   "devDependencies": {
+    "esbuild": "^0.25.4",
     "express": "^4.21.2",
     "sequelize": "^6.37.5",
     "sqlite3": "^5.1.7"

package/examples/express-app.js

@@ -1,106 +0,0 @@
-import express from "express";
-import http from "node:http";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { Sequelize } from "sequelize";
-import { createTrafficTracker } from "../src/index.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const app = express();
-const server = http.createServer(app);
-
-const sequelize = new Sequelize({
-  dialect: "sqlite",
-  storage: path.join(__dirname, "traffic-demo.sqlite"),
-  logging: false,
-});
-
-const traffic = createTrafficTracker({
-  sequelize,
-  getUserId: (req) => req.user?.id || req.headers["x-user-id"] || null,
-  getSessionId: (req) => req.headers["x-session-id"] || null,
-  slowRouteThresholdMs: 700,
-  trackIp: false,
-  trackUserAgent: true,
-  ignoredRoutes: ["/health", "/favicon.ico"],
-  dashboard: {
-    enabled: true,
-    mountPath: "/traffic-dashboard",
-    username: process.env.TRAFFIC_ADMIN_USER || "admin",
-    password: process.env.TRAFFIC_ADMIN_PASS || "password",
-  },
-  debug: true,
-});
-
-function wait(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-app.use(express.json());
-
-app.use((req, _res, next) => {
-  const userId = req.headers["x-user-id"];
-
-  req.user = userId ? { id: String(userId) } : null;
-  next();
-});
-
-app.use(traffic.middleware);
-traffic.attachRealtime(server);
-app.use("/traffic-dashboard", traffic.dashboard);
-
-app.get("/health", (_req, res) => {
-  res.json({ ok: true });
-});
-
-app.get("/api/products", async (_req, res) => {
-  await wait(120);
-
-  res.json([
-    { id: 1, name: "Signal Desk" },
-    { id: 2, name: "Route Pulse" },
-    { id: 3, name: "Latency Watch" },
-  ]);
-});
-
-app.get("/api/slow", async (_req, res) => {
-  await wait(1200);
-  res.json({ ok: true, message: "This route should show up as slow." });
-});
-
-app.get("/api/error", async (_req, res) => {
-  await wait(320);
-  res.status(500).json({ error: "Synthetic example failure." });
-});
-
-app.get("/api/users/:id", async (req, res) => {
-  await wait(180);
-  res.json({
-    id: req.params.id,
-    name: `User ${req.params.id}`,
-    requestedAt: new Date().toISOString(),
-  });
-});
-
-async function start() {
-  await sequelize.authenticate();
-  await traffic.sync();
-
-  const port = Number(process.env.PORT || 3000);
-
-  server.listen(port, () => {
-    console.log(`Example app running on http://localhost:${port}`);
-    console.log(
-      `Dashboard available on http://localhost:${port}/traffic-dashboard/`,
-    );
-  });
-}
-
-start().catch((error) => {
-  console.error("Failed to start example app.", error);
-  process.exitCode = 1;
-});

package/src/dashboard.js

@@ -1,132 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import express from "express";
-import { fileURLToPath } from "node:url";
-import { createAnalyticsRouter } from "./routes/analyticsRoutes.js";
-import { createBasicAuthMiddleware } from "./utils/dashboardAuth.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const dashboardBuildDirectory = path.resolve(__dirname, "dashboard-public");
-const dashboardIndexFile = path.join(dashboardBuildDirectory, "index.html");
-
-function createMissingBuildPage() {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Traffic Dashboard Build Missing</title>
-    <style>
-      body {
-        margin: 0;
-        font-family: "Segoe UI", sans-serif;
-        background: linear-gradient(135deg, #0f172a, #1e293b);
-        color: #e2e8f0;
-        min-height: 100vh;
-        display: grid;
-        place-items: center;
-        padding: 24px;
-      }
-
-      .panel {
-        max-width: 640px;
-        background: rgba(15, 23, 42, 0.9);
-        border: 1px solid rgba(148, 163, 184, 0.2);
-        border-radius: 24px;
-        padding: 32px;
-        box-shadow: 0 24px 60px rgba(15, 23, 42, 0.45);
-      }
-
-      h1 {
-        margin-top: 0;
-        font-size: 2rem;
-      }
-
-      code {
-        background: rgba(148, 163, 184, 0.16);
-        padding: 2px 6px;
-        border-radius: 6px;
-      }
-    </style>
-  </head>
-  <body>
-    <div class="panel">
-      <h1>Dashboard build not found</h1>
-      <p>
-        The analytics APIs are available, but the Vite dashboard has not been built
-        into <code>src/dashboard-public</code> yet.
-      </p>
-      <p>Run <code>npm run build:dashboard</code> in this package to generate the static dashboard assets.</p>
-    </div>
-  </body>
-</html>`;
-}
-
-export function createDisabledDashboardRouter() {
-  const router = express.Router();
-
-  router.use("/api", (_req, res) => {
-    res.status(404).json({ error: "Dashboard is disabled." });
-  });
-
-  router.use((_req, res) => {
-    res
-      .status(404)
-      .send("The traffic dashboard is disabled for this tracker instance.");
-  });
-
-  return router;
-}
-
-export function createDashboardRouter({
-  analyticsService,
-  dashboard = {},
-  debug = false,
-}) {
-  const router = express.Router();
-
-  router.use(createBasicAuthMiddleware(dashboard));
-  router.use("/api", createAnalyticsRouter({ analyticsService, debug }));
-
-  const hasBuiltDashboard = fs.existsSync(dashboardIndexFile);
-
-  if (hasBuiltDashboard) {
-    router.get("/", (req, res, next) => {
-      if (!req.originalUrl.endsWith("/")) {
-        res.redirect(302, `${req.baseUrl}/`);
-        return;
-      }
-
-      next();
-    });
-
-    router.use(
-      express.static(dashboardBuildDirectory, {
-        index: false,
-      }),
-    );
-
-    router.get("*", (req, res, next) => {
-      if (req.path.startsWith("/api")) {
-        next();
-        return;
-      }
-
-      res.sendFile(dashboardIndexFile);
-    });
-
-    return router;
-  }
-
-  router.get("*", (req, res, next) => {
-    if (req.path.startsWith("/api")) {
-      next();
-      return;
-    }
-
-    res.status(503).send(createMissingBuildPage());
-  });
-
-  return router;
-}

package/src/index.js

@@ -1,67 +0,0 @@
-import { defineTrafficLogModel } from "./models/TrafficLog.js";
-import { createTrackingMiddleware } from "./middleware.js";
-import { createAnalyticsService } from "./services/analyticsService.js";
-import {
-  createDashboardRouter,
-  createDisabledDashboardRouter,
-} from "./dashboard.js";
-import { createRealtimeBridge } from "./realtime.js";
-
-export function createTrafficTracker(options = {}) {
-  const {
-    sequelize,
-    getUserId,
-    getSessionId,
-    slowRouteThresholdMs = 1000,
-    ignoredRoutes = [],
-    trackIp = false,
-    trackUserAgent = true,
-    dashboard = {},
-    debug = false,
-  } = options;
-
-  if (!sequelize) {
-    throw new Error(
-      "createTrafficTracker requires a Sequelize instance via options.sequelize.",
-    );
-  }
-
-  const TrafficLog = defineTrafficLogModel(sequelize);
-  const analyticsService = createAnalyticsService(TrafficLog);
-  const realtimeBridge = createRealtimeBridge({ dashboard, debug });
-
-  return {
-    middleware: createTrackingMiddleware({
-      TrafficLog,
-      getUserId,
-      getSessionId,
-      slowRouteThresholdMs,
-      ignoredRoutes,
-      trackIp,
-      trackUserAgent,
-      debug,
-      realtimeBridge,
-    }),
-    dashboard: dashboard.enabled
-      ? createDashboardRouter({
-          analyticsService,
-          dashboard,
-          debug,
-        })
-      : createDisabledDashboardRouter(),
-    attachRealtime(server) {
-      return realtimeBridge.attachRealtime(server);
-    },
-    async sync(syncOptions = {}) {
-      return TrafficLog.sync(syncOptions);
-    },
-    getModel() {
-      return TrafficLog;
-    },
-    getSocketPath() {
-      return realtimeBridge.getSocketPath();
-    },
-  };
-}
-
-export { defineTrafficLogModel };

package/src/middleware.js

@@ -1,111 +0,0 @@
-import { safeAsync } from "./utils/safeAsync.js";
-import { resolveTrackedRoute, shouldIgnoreRoute } from "./utils/routeMatcher.js";
-
-function resolveOptionalValue(getter, req, debug, label) {
-  if (typeof getter !== "function") {
-    return null;
-  }
-
-  try {
-    return getter(req) ?? null;
-  } catch (error) {
-    if (debug) {
-      console.error(
-        `[express-sequelize-traffic] Failed to resolve ${label}.`,
-        error,
-      );
-    }
-
-    return null;
-  }
-}
-
-function createLogPayload({
-  req,
-  res,
-  startedAt,
-  endedAt,
-  slowRouteThresholdMs,
-  trackIp,
-  trackUserAgent,
-  getUserId,
-  getSessionId,
-  debug,
-}) {
-  const route = resolveTrackedRoute(req);
-  const durationMs = Math.max(0, endedAt.getTime() - startedAt.getTime());
-
-  return {
-    userId: resolveOptionalValue(getUserId, req, debug, "userId"),
-    sessionId: resolveOptionalValue(getSessionId, req, debug, "sessionId"),
-    method: req.method,
-    route,
-    originalUrl: req.originalUrl || route,
-    statusCode: res.statusCode,
-    durationMs,
-    isSlow: durationMs >= slowRouteThresholdMs,
-    ip: trackIp ? req.ip || req.socket?.remoteAddress || null : null,
-    userAgent: trackUserAgent ? req.get("user-agent") || null : null,
-    startedAt,
-    endedAt,
-  };
-}
-
-export function createTrackingMiddleware({
-  TrafficLog,
-  getUserId,
-  getSessionId,
-  slowRouteThresholdMs = 1000,
-  ignoredRoutes = [],
-  trackIp = false,
-  trackUserAgent = true,
-  debug = false,
-  realtimeBridge,
-}) {
-  return (req, res, next) => {
-    const startedAt = new Date();
-
-    res.once("finish", () => {
-      const endedAt = new Date();
-      const route = resolveTrackedRoute(req);
-      const originalUrl = req.originalUrl || route;
-
-      if (shouldIgnoreRoute({ route, originalUrl, ignoredRoutes })) {
-        return;
-      }
-
-      void safeAsync(
-        async () => {
-          const payload = createLogPayload({
-            req,
-            res,
-            startedAt,
-            endedAt,
-            slowRouteThresholdMs,
-            trackIp,
-            trackUserAgent,
-            getUserId,
-            getSessionId,
-            debug,
-          });
-
-          const createdLog = await TrafficLog.create(payload);
-
-          realtimeBridge?.emitNewRequest(createdLog.get({ plain: true }));
-        },
-        {
-          onError: (error) => {
-            if (debug) {
-              console.error(
-                "[express-sequelize-traffic] Failed to persist traffic log.",
-                error,
-              );
-            }
-          },
-        },
-      );
-    });
-
-    next();
-  };
-}

package/src/models/TrafficLog.js

@@ -1,83 +0,0 @@
-import { DataTypes } from "sequelize";
-
-export function defineTrafficLogModel(sequelize) {
-  if (!sequelize) {
-    throw new Error("A Sequelize instance is required to define TrafficLog.");
-  }
-
-  if (sequelize.models.TrafficLog) {
-    return sequelize.models.TrafficLog;
-  }
-
-  return sequelize.define(
-    "TrafficLog",
-    {
-      id: {
-        type: DataTypes.BIGINT,
-        autoIncrement: true,
-        primaryKey: true,
-      },
-      userId: {
-        type: DataTypes.STRING,
-        allowNull: true,
-      },
-      sessionId: {
-        type: DataTypes.STRING,
-        allowNull: true,
-      },
-      method: {
-        type: DataTypes.STRING(16),
-        allowNull: false,
-      },
-      route: {
-        type: DataTypes.STRING,
-        allowNull: false,
-      },
-      originalUrl: {
-        type: DataTypes.STRING,
-        allowNull: false,
-      },
-      statusCode: {
-        type: DataTypes.INTEGER,
-        allowNull: false,
-      },
-      durationMs: {
-        type: DataTypes.INTEGER,
-        allowNull: false,
-      },
-      isSlow: {
-        type: DataTypes.BOOLEAN,
-        allowNull: false,
-        defaultValue: false,
-      },
-      ip: {
-        type: DataTypes.STRING,
-        allowNull: true,
-      },
-      userAgent: {
-        type: DataTypes.TEXT,
-        allowNull: true,
-      },
-      startedAt: {
-        type: DataTypes.DATE,
-        allowNull: false,
-      },
-      endedAt: {
-        type: DataTypes.DATE,
-        allowNull: false,
-      },
-    },
-    {
-      tableName: "traffic_logs",
-      indexes: [
-        { fields: ["userId"] },
-        { fields: ["sessionId"] },
-        { fields: ["route"] },
-        { fields: ["method"] },
-        { fields: ["statusCode"] },
-        { fields: ["durationMs"] },
-        { fields: ["createdAt"] },
-      ],
-    },
-  );
-}

package/src/realtime.js

@@ -1,71 +0,0 @@
-import { Server } from "socket.io";
-import { createSocketAuthMiddleware } from "./utils/dashboardAuth.js";
-
-function normalizeSocketPath(dashboard = {}) {
-  const mountPath = dashboard.mountPath || "/traffic-dashboard";
-  const sanitizedMountPath = mountPath.startsWith("/")
-    ? mountPath
-    : `/${mountPath}`;
-
-  return `${sanitizedMountPath.replace(/\/$/, "")}/socket.io`;
-}
-
-function buildRealtimePayload(log) {
-  return {
-    userId: log.userId,
-    sessionId: log.sessionId,
-    method: log.method,
-    route: log.route,
-    originalUrl: log.originalUrl,
-    statusCode: Number(log.statusCode),
-    durationMs: Number(log.durationMs),
-    isSlow: Boolean(log.isSlow),
-    createdAt: log.createdAt,
-  };
-}
-
-export function createRealtimeBridge({ dashboard = {}, debug = false } = {}) {
-  let io = null;
-  const socketPath = normalizeSocketPath(dashboard);
-
-  return {
-    attachRealtime(server) {
-      if (!server) {
-        throw new Error("An HTTP server instance is required for realtime.");
-      }
-
-      if (io) {
-        return io;
-      }
-
-      io = new Server(server, {
-        path: socketPath,
-        serveClient: false,
-      });
-
-      io.use(createSocketAuthMiddleware(dashboard));
-
-      if (debug) {
-        io.on("connection", (socket) => {
-          console.info(
-            `[express-sequelize-traffic] Dashboard realtime connected: ${socket.id}`,
-          );
-        });
-      }
-
-      return io;
-    },
-
-    emitNewRequest(log) {
-      if (!io) {
-        return;
-      }
-
-      io.emit("traffic:new-request", buildRealtimePayload(log));
-    },
-
-    getSocketPath() {
-      return socketPath;
-    },
-  };
-}

package/src/routes/analyticsRoutes.js

@@ -1,83 +0,0 @@
-import express from "express";
-import { safeAsync } from "../utils/safeAsync.js";
-
-function sendApiError(res, message) {
-  res.status(500).json({ error: message });
-}
-
-export function createAnalyticsRouter({ analyticsService, debug = false }) {
-  const router = express.Router();
-
-  const logApiError = (scope) => (error) => {
-    if (debug) {
-      console.error(`[express-sequelize-traffic] ${scope}`, error);
-    }
-  };
-
-  router.get("/overview", async (_req, res) => {
-    const data = await safeAsync(() => analyticsService.getOverview(), {
-      onError: logApiError("Failed to load overview analytics."),
-    });
-
-    if (!data) {
-      sendApiError(res, "Unable to load overview analytics.");
-      return;
-    }
-
-    res.json(data);
-  });
-
-  router.get("/live", async (_req, res) => {
-    const data = await safeAsync(() => analyticsService.getLive(), {
-      onError: logApiError("Failed to load live traffic logs."),
-    });
-
-    if (!data) {
-      sendApiError(res, "Unable to load live traffic logs.");
-      return;
-    }
-
-    res.json(data);
-  });
-
-  router.get("/routes", async (_req, res) => {
-    const data = await safeAsync(() => analyticsService.getRoutes(), {
-      onError: logApiError("Failed to load route analytics."),
-    });
-
-    if (!data) {
-      sendApiError(res, "Unable to load route analytics.");
-      return;
-    }
-
-    res.json(data);
-  });
-
-  router.get("/users", async (_req, res) => {
-    const data = await safeAsync(() => analyticsService.getUsers(), {
-      onError: logApiError("Failed to load user analytics."),
-    });
-
-    if (!data) {
-      sendApiError(res, "Unable to load user analytics.");
-      return;
-    }
-
-    res.json(data);
-  });
-
-  router.get("/errors", async (_req, res) => {
-    const data = await safeAsync(() => analyticsService.getErrors(), {
-      onError: logApiError("Failed to load error analytics."),
-    });
-
-    if (!data) {
-      sendApiError(res, "Unable to load error analytics.");
-      return;
-    }
-
-    res.json(data);
-  });
-
-  return router;
-}