express-sequelize-traffic 0.1.0 → 0.3.0

package/README.md

@@ -27,12 +27,12 @@ If you are working on this repository directly:
 
 ```bash
 npm install
-npm run build:dashboard
+npm run build
 ```
 
-## Sequelize Setup
+## Quick Setup
 
-The package defines a `TrafficLog` model for you. You can either manage the table through your own migrations or call `traffic.sync()` for quick setup.
+The package defines a `TrafficLog` model for you. You can either manage the table through your own migrations or call `traffic.sync()` for quick setup. `traffic.sync()` wraps Sequelize model sync and creates the `traffic_logs` table if it does not already exist.
 
 ```js
 import { Sequelize } from "sequelize";
@@ -46,7 +46,9 @@ await sequelize.authenticate();
 await traffic.sync();
 ```
 
-## Express Usage
+## ES Module Setup
+
+Use this form when the target app uses `"type": "module"` or native ESM imports.
 
 ```js
 import express from "express";
@@ -83,6 +85,155 @@ app.use("/traffic-dashboard", traffic.dashboard);
 server.listen(3000);
 ```
 
+## CommonJS Setup
+
+The package also publishes a CommonJS entry, so `require(...)` works directly.
+
+```js
+const express = require("express");
+const http = require("node:http");
+const { Sequelize } = require("sequelize");
+const { createTrafficTracker } = require("express-sequelize-traffic");
+
+const app = express();
+const server = http.createServer(app);
+
+const sequelize = new Sequelize(process.env.DB_URL, {
+  logging: false,
+});
+
+async function start() {
+  const traffic = createTrafficTracker({
+    sequelize,
+    getUserId: (req) => req.user?.id || req.headers["x-user-id"] || null,
+    getSessionId: (req) => req.sessionID || req.headers["x-session-id"] || null,
+    slowRouteThresholdMs: 1000,
+    ignoredRoutes: ["/health", "/favicon.ico"],
+    trackIp: false,
+    trackUserAgent: true,
+    dashboard: {
+      enabled: true,
+      mountPath: "/traffic-dashboard",
+      username: process.env.TRAFFIC_ADMIN_USER,
+      password: process.env.TRAFFIC_ADMIN_PASS,
+    },
+  });
+
+  await sequelize.authenticate();
+  await traffic.sync();
+
+  app.use(traffic.middleware);
+  traffic.attachRealtime(server);
+  app.use("/traffic-dashboard", traffic.dashboard);
+
+  app.get("/health", (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  server.listen(3000);
+}
+
+start().catch((error) => {
+  console.error("Startup failed:", error);
+  process.exit(1);
+});
+```
+
+## Passing User Details
+
+The package does not assume how authentication works in your app. You pass user and session details through resolver functions.
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  getUserId: (req) =>
+    req.user?.id || req.auth?.sub || req.headers["x-user-id"] || null,
+  getSessionId: (req) =>
+    req.sessionID || req.cookies?.sessionId || req.headers["x-session-id"] || null,
+});
+```
+
+Common sources are:
+
+- `req.user.id` from Passport or your own auth middleware
+- `req.auth.sub` from JWT middleware
+- `req.sessionID` from `express-session`
+- custom request headers in internal systems
+
+Rules to follow:
+
+- Register auth and session middleware before `traffic.middleware`
+- Return `null` when user or session data is unavailable
+- If you omit `getUserId` or `getSessionId`, those fields are stored as `NULL`
+
+## Why It Tracks More Than Application Routes
+
+This package is request middleware. If you mount it globally with:
+
+```js
+app.use(traffic.middleware);
+```
+
+it will see every request that reaches that point in the Express stack, not just your business endpoints.
+
+That includes:
+
+- API routes
+- page routes
+- health checks
+- static files
+- 404 requests
+- dashboard API requests
+- dashboard frontend asset requests
+
+Internally, the tracker records the route from `req.route?.path`, then falls back to `req.path`, then `req.originalUrl`. That is why it can still log requests even when Express does not resolve them to a named application route.
+
+## How To Track Only Application Routes
+
+If you want to limit tracking to business endpoints, use one or more of these patterns.
+
+Mount the tracker only on the route prefix you care about:
+
+```js
+app.use("/api", traffic.middleware);
+```
+
+Register static assets or health checks before the tracker:
+
+```js
+app.use("/public", express.static("public"));
+app.get("/health", (_req, res) => res.json({ ok: true }));
+
+app.use(traffic.middleware);
+```
+
+Ignore route groups with regex:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  ignoredRoutes: [
+    "/health",
+    "/favicon.ico",
+    /^\/traffic-dashboard(\/|$)/,
+    /^\/public(\/|$)/,
+  ],
+});
+```
+
+Use a function when the skip logic depends on route naming conventions:
+
+```js
+const traffic = createTrafficTracker({
+  sequelize,
+  ignoredRoutes: [
+    (route) => route.startsWith("/internal/"),
+  ],
+});
+```
+
+If you mount the tracker globally, global tracking is expected behavior.
+
 ## Dashboard Usage
 
 The dashboard is optional. Set `dashboard.enabled` to `true`, build the frontend assets, attach realtime support, and mount the provided router.