express-sequelize-traffic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c)
+
+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,190 @@
+# express-sequelize-traffic
+
+`express-sequelize-traffic` is a privacy-first, self-hosted npm package for Express.js applications. It records request analytics directly into your own Sequelize database and provides an optional realtime dashboard with REST APIs and Socket.IO updates.
+
+No traffic data is sent to Google Analytics, Prometheus, Segment, Sentry, or any external service. The package only writes to the Sequelize connection you provide.
+
+## Features
+
+- Express middleware that tracks every request without interrupting the main app on failure
+- Sequelize `TrafficLog` model stored in the `traffic_logs` table
+- Request tracking for user, session, route, status code, duration, slow routes, IP, user agent, start time, and end time
+- Analytics REST API under the dashboard router
+- Realtime `traffic:new-request` events over Socket.IO
+- Optional built-in dashboard served from Express
+- Simple HTTP basic authentication for the dashboard
+- SQLite-backed example app for local testing
+
+## Installation
+
+Install the package dependencies:
+
+```bash
+npm install express-sequelize-traffic
+```
+
+If you are working on this repository directly:
+
+```bash
+npm install
+npm run build:dashboard
+```
+
+## Sequelize 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.
+
+```js
+import { Sequelize } from "sequelize";
+import { createTrafficTracker } from "express-sequelize-traffic";
+
+const sequelize = new Sequelize(process.env.DB_URL);
+
+const traffic = createTrafficTracker({ sequelize });
+
+await sequelize.authenticate();
+await traffic.sync();
+```
+
+## Express Usage
+
+```js
+import express from "express";
+import http from "node:http";
+import { Sequelize } from "sequelize";
+import { createTrafficTracker } from "express-sequelize-traffic";
+
+const app = express();
+const server = http.createServer(app);
+const sequelize = new Sequelize(process.env.DB_URL);
+
+const traffic = createTrafficTracker({
+  sequelize,
+  getUserId: (req) => req.user?.id || req.headers["x-user-id"],
+  getSessionId: (req) => req.sessionID || req.headers["x-session-id"],
+  slowRouteThresholdMs: 1000,
+  trackIp: false,
+  trackUserAgent: true,
+  ignoredRoutes: ["/health", "/favicon.ico"],
+  dashboard: {
+    enabled: true,
+    mountPath: "/traffic-dashboard",
+    username: process.env.TRAFFIC_ADMIN_USER,
+    password: process.env.TRAFFIC_ADMIN_PASS,
+  },
+});
+
+await traffic.sync();
+
+app.use(traffic.middleware);
+traffic.attachRealtime(server);
+app.use("/traffic-dashboard", traffic.dashboard);
+
+server.listen(3000);
+```
+
+## Dashboard Usage
+
+The dashboard is optional. Set `dashboard.enabled` to `true`, build the frontend assets, attach realtime support, and mount the provided router.
+
+The dashboard expects the router mount path to match `dashboard.mountPath`. If you keep the default `/traffic-dashboard`, the client-side API and Socket.IO paths line up automatically.
+
+```bash
+npm run build:dashboard
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sequelize` | `Sequelize` | required | Sequelize instance used for the `TrafficLog` model |
+| `getUserId` | `(req) => string \| null` | `undefined` | Custom resolver for `userId` |
+| `getSessionId` | `(req) => string \| null` | `undefined` | Custom resolver for `sessionId` |
+| `slowRouteThresholdMs` | `number` | `1000` | Marks requests as slow when duration meets or exceeds this value |
+| `ignoredRoutes` | `Array<string \| RegExp \| Function>` | `[]` | Routes or URLs to skip |
+| `trackIp` | `boolean` | `false` | Persist `req.ip` when enabled |
+| `trackUserAgent` | `boolean` | `true` | Persist the request `user-agent` header when enabled |
+| `dashboard.enabled` | `boolean` | `false` | Enables dashboard APIs and static UI |
+| `dashboard.mountPath` | `string` | `"/traffic-dashboard"` | Mount path used by the dashboard UI and realtime socket |
+| `dashboard.username` | `string` | `undefined` | Basic auth username for the dashboard |
+| `dashboard.password` | `string` | `undefined` | Basic auth password for the dashboard |
+| `debug` | `boolean` | `false` | Logs tracking or analytics errors without throwing them |
+
+## API Routes
+
+When the dashboard router is mounted, these endpoints are available under `/<mountPath>/api`:
+
+- `GET /api/overview`
+- `GET /api/live`
+- `GET /api/routes`
+- `GET /api/users`
+- `GET /api/errors`
+
+`GET /api/overview` returns:
+
+- `totalRequests`
+- `averageDurationMs`
+- `slowRequestCount`
+- `errorRequestCount`
+- `uniqueUsers`
+- `topRoutes`
+- `slowestRoutes`
+- `statusCodeSummary`
+
+The implementation also includes `latestRequests` and `requestsTimeline` to support the dashboard overview page.
+
+## Realtime Events
+
+Call `traffic.attachRealtime(server)` with your Node HTTP server. Each stored request emits:
+
+- Event: `traffic:new-request`
+
+Payload:
+
+```json
+{
+  "userId": "123",
+  "sessionId": "session-1",
+  "method": "GET",
+  "route": "/api/products",
+  "originalUrl": "/api/products?page=1",
+  "statusCode": 200,
+  "durationMs": 187,
+  "isSlow": false,
+  "createdAt": "2026-05-07T12:00:00.000Z"
+}
+```
+
+## Example App
+
+Run the SQLite example:
+
+```bash
+npm run example
+```
+
+Example endpoints:
+
+- `GET /api/products`
+- `GET /api/slow`
+- `GET /api/error`
+- `GET /api/users/:id`
+- `GET /traffic-dashboard/`
+
+The example dashboard uses HTTP basic auth with:
+
+- username: `admin`
+- password: `password`
+
+Override them with `TRAFFIC_ADMIN_USER` and `TRAFFIC_ADMIN_PASS`.
+
+## Screenshot Placeholders
+
+- Overview dashboard screenshot placeholder
+- Live traffic dashboard screenshot placeholder
+
+Capture real screenshots after building and running the example app.
+
+## License
+
+MIT

package/examples/express-app.js

@@ -0,0 +1,106 @@
+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/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "express-sequelize-traffic",
+  "version": "0.1.0",
+  "description": "Privacy-first, self-hosted Express request analytics with Sequelize storage and an optional realtime dashboard.",
+  "type": "module",
+  "main": "./src/index.js",
+  "workspaces": [
+    "dashboard-app"
+  ],
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "npm run example",
+    "build": "npm run build:dashboard",
+    "build:dashboard": "npm run build --workspace dashboard-app",
+    "example": "node examples/express-app.js",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "express",
+    "sequelize",
+    "analytics",
+    "traffic",
+    "dashboard",
+    "socket.io",
+    "privacy-first"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "express": ">=4.18.0",
+    "sequelize": ">=6.0.0"
+  },
+  "dependencies": {
+    "socket.io": "^4.8.1"
+  },
+  "devDependencies": {
+    "express": "^4.21.2",
+    "sequelize": "^6.37.5",
+    "sqlite3": "^5.1.7"
+  }
+}