express-sequelize-traffic 0.1.0

package/src/dashboard-public/assets/index-iT93XJlh.css

@@ -0,0 +1 @@
+*,:before,:after{--tw-border-spacing-x: 0;--tw-border-spacing-y: 0;--tw-translate-x: 0;--tw-translate-y: 0;--tw-rotate: 0;--tw-skew-x: 0;--tw-skew-y: 0;--tw-scale-x: 1;--tw-scale-y: 1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness: proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width: 0px;--tw-ring-offset-color: #fff;--tw-ring-color: rgb(59 130 246 / .5);--tw-ring-offset-shadow: 0 0 #0000;--tw-ring-shadow: 0 0 #0000;--tw-shadow: 0 0 #0000;--tw-shadow-colored: 0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }::backdrop{--tw-border-spacing-x: 0;--tw-border-spacing-y: 0;--tw-translate-x: 0;--tw-translate-y: 0;--tw-rotate: 0;--tw-skew-x: 0;--tw-skew-y: 0;--tw-scale-x: 1;--tw-scale-y: 1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness: proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width: 0px;--tw-ring-offset-color: #fff;--tw-ring-color: rgb(59 130 246 / .5);--tw-ring-offset-shadow: 0 0 #0000;--tw-ring-shadow: 0 0 #0000;--tw-shadow: 0 0 #0000;--tw-shadow-colored: 0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }*,:before,:after{box-sizing:border-box;border-width:0;border-style:solid;border-color:#e5e7eb}:before,:after{--tw-content: ""}html,:host{line-height:1.5;-webkit-text-size-adjust:100%;-moz-tab-size:4;-o-tab-size:4;tab-size:4;font-family:Space Grotesk,Segoe UI,sans-serif;font-feature-settings:normal;font-variation-settings:normal;-webkit-tap-highlight-color:transparent}body{margin:0;line-height:inherit}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-feature-settings:normal;font-variation-settings:normal;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}button,input,optgroup,select,textarea{font-family:inherit;font-feature-settings:inherit;font-variation-settings:inherit;font-size:100%;font-weight:inherit;line-height:inherit;letter-spacing:inherit;color:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:transparent;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dl,dd,h1,h2,h3,h4,h5,h6,hr,figure,p,pre{margin:0}fieldset{margin:0;padding:0}legend{padding:0}ol,ul,menu{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::-moz-placeholder,textarea::-moz-placeholder{opacity:1;color:#9ca3af}input::placeholder,textarea::placeholder{opacity:1;color:#9ca3af}button,[role=button]{cursor:pointer}:disabled{cursor:default}img,svg,video,canvas,audio,iframe,embed,object{display:block;vertical-align:middle}img,video{max-width:100%;height:auto}[hidden]:where(:not([hidden=until-found])){display:none}:root{color:#0f172a;background:radial-gradient(circle at top left,rgba(38,64,168,.12),transparent 24rem),linear-gradient(180deg,#f6f9ff,#edf3ff)}*{box-sizing:border-box}body{margin:0;min-width:320px;min-height:100vh;font-family:Space Grotesk,Segoe UI,sans-serif;color:#0f172a;background:radial-gradient(circle at top left,rgba(38,64,168,.12),transparent 24rem),linear-gradient(180deg,#f6f9ff,#edf3ff)}#root{min-height:100vh}.absolute{position:absolute}.relative{position:relative}.inset-x-0{left:0;right:0}.top-0{top:0}.mx-auto{margin-left:auto;margin-right:auto}.mb-4{margin-bottom:1rem}.mt-2{margin-top:.5rem}.mt-3{margin-top:.75rem}.mt-4{margin-top:1rem}.mt-8{margin-top:2rem}.flex{display:flex}.table{display:table}.grid{display:grid}.h-11{height:2.75rem}.h-2\.5{height:.625rem}.h-4{height:1rem}.h-40{height:10rem}.h-5{height:1.25rem}.h-72{height:18rem}.h-80{height:20rem}.min-h-screen{min-height:100vh}.w-11{width:2.75rem}.w-2\.5{width:.625rem}.w-4{width:1rem}.w-5{width:1.25rem}.min-w-full{min-width:100%}.max-w-3xl{max-width:48rem}.max-w-7xl{max-width:80rem}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.place-items-center{place-items:center}.items-center{align-items:center}.justify-between{justify-content:space-between}.gap-2{gap:.5rem}.gap-3{gap:.75rem}.gap-4{gap:1rem}.gap-6{gap:1.5rem}.space-y-6>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(1.5rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(1.5rem * var(--tw-space-y-reverse))}.overflow-hidden{overflow:hidden}.overflow-x-auto{overflow-x:auto}.rounded-2xl{border-radius:1rem}.rounded-3xl{border-radius:1.5rem}.rounded-\[24px\]{border-radius:24px}.rounded-\[28px\]{border-radius:28px}.rounded-full{border-radius:9999px}.border{border-width:1px}.border-b{border-bottom-width:1px}.border-t{border-top-width:1px}.border-slate-200\/70{border-color:#e2e8f0b3}.border-white\/10{border-color:#ffffff1a}.bg-emerald-100{--tw-bg-opacity: 1;background-color:rgb(209 250 229 / var(--tw-bg-opacity, 1))}.bg-ink{--tw-bg-opacity: 1;background-color:rgb(9 17 31 / var(--tw-bg-opacity, 1))}.bg-rose-100{--tw-bg-opacity: 1;background-color:rgb(255 228 230 / var(--tw-bg-opacity, 1))}.bg-rose-50{--tw-bg-opacity: 1;background-color:rgb(255 241 242 / var(--tw-bg-opacity, 1))}.bg-slate-100{--tw-bg-opacity: 1;background-color:rgb(241 245 249 / var(--tw-bg-opacity, 1))}.bg-slate-50{--tw-bg-opacity: 1;background-color:rgb(248 250 252 / var(--tw-bg-opacity, 1))}.bg-white{--tw-bg-opacity: 1;background-color:rgb(255 255 255 / var(--tw-bg-opacity, 1))}.bg-white\/80{background-color:#fffc}.bg-gradient-to-br{background-image:linear-gradient(to bottom right,var(--tw-gradient-stops))}.from-slateBlue\/40{--tw-gradient-from: rgb(38 64 168 / .4) var(--tw-gradient-from-position);--tw-gradient-to: rgb(38 64 168 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-white{--tw-gradient-from: #fff var(--tw-gradient-from-position);--tw-gradient-to: rgb(255 255 255 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.to-emerald-50{--tw-gradient-to: #ecfdf5 var(--tw-gradient-to-position)}.to-mist{--tw-gradient-to: #eef4ff var(--tw-gradient-to-position)}.to-rose-50{--tw-gradient-to: #fff1f2 var(--tw-gradient-to-position)}.to-transparent{--tw-gradient-to: transparent var(--tw-gradient-to-position)}.p-5{padding:1.25rem}.px-2\.5{padding-left:.625rem;padding-right:.625rem}.px-4{padding-left:1rem;padding-right:1rem}.px-5{padding-left:1.25rem;padding-right:1.25rem}.py-1{padding-top:.25rem;padding-bottom:.25rem}.py-10{padding-top:2.5rem;padding-bottom:2.5rem}.py-2{padding-top:.5rem;padding-bottom:.5rem}.py-3{padding-top:.75rem;padding-bottom:.75rem}.py-4{padding-top:1rem;padding-bottom:1rem}.py-5{padding-top:1.25rem;padding-bottom:1.25rem}.py-6{padding-top:1.5rem;padding-bottom:1.5rem}.text-left{text-align:left}.text-3xl{font-size:1.875rem;line-height:2.25rem}.text-lg{font-size:1.125rem;line-height:1.75rem}.text-sm{font-size:.875rem;line-height:1.25rem}.text-xs{font-size:.75rem;line-height:1rem}.font-medium{font-weight:500}.font-semibold{font-weight:600}.uppercase{text-transform:uppercase}.leading-6{line-height:1.5rem}.tracking-\[0\.24em\]{letter-spacing:.24em}.tracking-tight{letter-spacing:-.025em}.text-emerald-700{--tw-text-opacity: 1;color:rgb(4 120 87 / var(--tw-text-opacity, 1))}.text-rose-700{--tw-text-opacity: 1;color:rgb(190 18 60 / var(--tw-text-opacity, 1))}.text-slate-200{--tw-text-opacity: 1;color:rgb(226 232 240 / var(--tw-text-opacity, 1))}.text-slate-300{--tw-text-opacity: 1;color:rgb(203 213 225 / var(--tw-text-opacity, 1))}.text-slate-400{--tw-text-opacity: 1;color:rgb(148 163 184 / var(--tw-text-opacity, 1))}.text-slate-500{--tw-text-opacity: 1;color:rgb(100 116 139 / var(--tw-text-opacity, 1))}.text-slate-600{--tw-text-opacity: 1;color:rgb(71 85 105 / var(--tw-text-opacity, 1))}.text-slate-700{--tw-text-opacity: 1;color:rgb(51 65 85 / var(--tw-text-opacity, 1))}.text-slate-900{--tw-text-opacity: 1;color:rgb(15 23 42 / var(--tw-text-opacity, 1))}.text-slate-950{--tw-text-opacity: 1;color:rgb(2 6 23 / var(--tw-text-opacity, 1))}.text-white{--tw-text-opacity: 1;color:rgb(255 255 255 / var(--tw-text-opacity, 1))}.shadow-lg{--tw-shadow: 0 10px 15px -3px rgb(0 0 0 / .1), 0 4px 6px -4px rgb(0 0 0 / .1);--tw-shadow-colored: 0 10px 15px -3px var(--tw-shadow-color), 0 4px 6px -4px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-sm{--tw-shadow: 0 1px 2px 0 rgb(0 0 0 / .05);--tw-shadow-colored: 0 1px 2px 0 var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-slate-950\/20{--tw-shadow-color: rgb(2 6 23 / .2);--tw-shadow: var(--tw-shadow-colored)}.ring-1{--tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(1px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow, 0 0 #0000)}.ring-white\/10{--tw-ring-color: rgb(255 255 255 / .1)}.blur-3xl{--tw-blur: blur(64px);filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.filter{filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.transition-all{transition-property:all;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.duration-200{transition-duration:.2s}.surface-border{border:1px solid rgba(148,163,184,.18)}.surface-glow{box-shadow:0 20px 45px #0f172a14,inset 0 1px #fff9}.hover\:text-white:hover{--tw-text-opacity: 1;color:rgb(255 255 255 / var(--tw-text-opacity, 1))}@media(min-width:640px){.sm\:flex-row{flex-direction:row}.sm\:items-end{align-items:flex-end}.sm\:justify-between{justify-content:space-between}.sm\:px-6{padding-left:1.5rem;padding-right:1.5rem}}@media(min-width:768px){.md\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}}@media(min-width:1024px){.lg\:grid{display:grid}.lg\:grid-cols-\[288px_minmax\(0\,1fr\)\]{grid-template-columns:288px minmax(0,1fr)}.lg\:px-6{padding-left:1.5rem;padding-right:1.5rem}.lg\:px-8{padding-left:2rem;padding-right:2rem}.lg\:py-8{padding-top:2rem;padding-bottom:2rem}}@media(min-width:1280px){.xl\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.xl\:grid-cols-\[minmax\(0\,1\.1fr\)_minmax\(0\,1fr\)\]{grid-template-columns:minmax(0,1.1fr) minmax(0,1fr)}.xl\:grid-cols-\[minmax\(0\,1\.5fr\)_minmax\(320px\,0\.9fr\)\]{grid-template-columns:minmax(0,1.5fr) minmax(320px,.9fr)}}

package/src/dashboard-public/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Express Sequelize Traffic</title>
+    <script type="module" crossorigin src="./assets/index-CaWHQ-tp.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-iT93XJlh.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/src/dashboard.js

@@ -0,0 +1,132 @@
+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

@@ -0,0 +1,67 @@
+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

@@ -0,0 +1,111 @@
+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

@@ -0,0 +1,83 @@
+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

@@ -0,0 +1,71 @@
+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

@@ -0,0 +1,83 @@
+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;
+}