@adwait12345/telemetry-express 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,142 @@
+# `@adwait12345/telemetry-express`
+
+Express middleware adapter for the Telemetry SDK. Detects bots and crawlers on every incoming request and sends tracking payloads to the Telemetry API.
+
+---
+
+## Requirements
+
+- Express **4.x or later**
+- Node.js **18+** (uses native `fetch`)
+- A Telemetry account with a **Project ID** and **Server Secret**
+
+---
+
+## Installation
+
+```bash
+npm install @adwait12345/telemetry-express @adwait12345/telemetry-core
+# or
+pnpm add @adwait12345/telemetry-express @adwait12345/telemetry-core
+```
+
+---
+
+## Setup
+
+```typescript
+import express from "express";
+import { telemetryMiddleware } from "@adwait12345/telemetry-express";
+
+const app = express();
+
+app.use(
+  telemetryMiddleware({
+    projectId: process.env.TELEMETRY_PROJECT_ID!,
+    apiUrl: process.env.TELEMETRY_API_URL,
+    serverSecret: process.env.TELEMETRY_SERVER_SECRET!,
+    debug: false,
+  })
+);
+
+app.get("/", (req, res) => {
+  res.send("Hello world");
+});
+
+app.listen(3000);
+```
+
+```bash
+# .env
+TELEMETRY_PROJECT_ID=your-project-id
+TELEMETRY_API_URL=https://telemetry-uqd3.onrender.com
+TELEMETRY_SERVER_SECRET=sk_...
+```
+
+---
+
+## How it works
+
+1. The middleware runs synchronously on every request
+2. The request is normalized (UA, IP, headers, HTTP version) and passed to `detectBot()`
+3. Express exposes the real `httpVersion` from the raw request — this improves detection accuracy (HTTP/1.0 is flagged as a bot signal)
+4. If a bot is detected (or `trackAll: true`), a fire-and-forget send is triggered
+5. `next()` is called immediately — the send **does not block** the response
+
+---
+
+## Configuration options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `projectId` | `string` | **required** | Your Telemetry project ID |
+| `serverSecret` | `string` | **required** | Your server secret key for API auth |
+| `apiUrl` | `string` | hosted service | Override the API endpoint |
+| `trackAll` | `boolean` | `false` | Track all requests, not just bots |
+| `trackSearchBots` | `boolean` | `true` | Include Googlebot, Bingbot etc. |
+| `ignorePaths` | `(string \| RegExp)[]` | — | Paths to skip entirely |
+| `customBots` | `Array<{name, pattern, category?}>` | — | Add custom bot definitions |
+| `debug` | `boolean` | `false` | Log detection results to the console |
+| `authorizationHeader` | `string` | — | Fully custom `Authorization` header value |
+| `headers` | `Record<string, string>` | — | Extra headers on every telemetry request |
+
+---
+
+## Examples
+
+### Skip health check and static routes
+
+```typescript
+app.use(
+  telemetryMiddleware({
+    projectId: "...",
+    serverSecret: "sk_...",
+    ignorePaths: ["/health", "/ping", /^\/static\//],
+  })
+);
+```
+
+### Track all visitors
+
+```typescript
+app.use(
+  telemetryMiddleware({
+    projectId: "...",
+    serverSecret: "sk_...",
+    trackAll: true,
+  })
+);
+```
+
+### Add custom bot definitions
+
+```typescript
+app.use(
+  telemetryMiddleware({
+    projectId: "...",
+    serverSecret: "sk_...",
+    customBots: [
+      { name: "MyInternalCrawler", pattern: /my-crawler\/\d+/i, category: "scraper" },
+    ],
+  })
+);
+```
+
+---
+
+## What gets tracked
+
+| Field | Description |
+|-------|-------------|
+| `projectId` | Your project ID |
+| `path` | Request path (from `req.originalUrl`) |
+| `method` | HTTP method |
+| `userAgent` | Full user-agent string |
+| `ip` | Client IP (from `req.ip` or `x-forwarded-for`) |
+| `isBot` | `true` / `false` |
+| `botName` | Named bot e.g. `"GPTBot"`, or `null` |
+| `botCategory` | e.g. `"ai-crawler"`, `"search"`, `"scraper"` |
+| `confidence` | `"certain"` / `"high"` / `"medium"` / `"low"` |
+| `detectionMethod` | `"ua-match"` / `"header-anomaly"` / `"http10"` / `"automation-header"` |
+| `referrer` | Referrer header |
+| `timestamp` | ISO 8601 UTC |

package/dist/index.js

@@ -70,7 +70,10 @@ function telemetryMiddleware(config) {
       };
       (0, import_telemetry_core.sendToTelemetry)(payload, config).catch((err) => {
         if (config.debug) {
-          console.error("[Telemetry Middleware] Failed to send to telemetry:", err);
+          console.error(
+            "[Telemetry Middleware] Failed to send to telemetry:",
+            err
+          );
         }
       });
     }

package/dist/index.mjs

@@ -50,7 +50,10 @@ function telemetryMiddleware(config) {
       };
       sendToTelemetry(payload, config).catch((err) => {
         if (config.debug) {
-          console.error("[Telemetry Middleware] Failed to send to telemetry:", err);
+          console.error(
+            "[Telemetry Middleware] Failed to send to telemetry:",
+            err
+          );
         }
       });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adwait12345/telemetry-express",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Express middleware for Telemetry SDK - track AI bots and crawlers",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,8 +12,12 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "dependencies": {
-    "@adwait12345/telemetry-core": "0.1.0"
+    "@adwait12345/telemetry-core": ">=0.1.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",

package/src/index.ts

@@ -1,83 +0,0 @@
-import { ServerTrackPayload } from "@adwait12345/telemetry-core";
-
-// Mocking some request structures here just so we can write the package
-import type { Request, Response, NextFunction } from "express";
-import {
-  detectBot,
-  extractAutomationHeaders,
-  sendToTelemetry,
-  type TelemetryConfig,
-  type NormalizedRequest,
-} from "@adwait12345/telemetry-core";
-
-export function telemetryMiddleware(config: TelemetryConfig) {
-  return function (req: Request, res: Response, next: NextFunction) {
-    // 1. Normalize the request
-    const userAgent = req.get("user-agent") || "";
-    const ip = req.ip || (req.headers["x-forwarded-for"] as string) || "";
-    const path = req.originalUrl || req.url;
-
-    // Check ignore paths first
-    if (config.ignorePaths) {
-      for (const ignorePath of config.ignorePaths) {
-        if (typeof ignorePath === "string" && path === ignorePath) {
-          return next();
-        } else if (ignorePath instanceof RegExp && ignorePath.test(path)) {
-          return next();
-        }
-      }
-    }
-
-    const normalizedReq: NormalizedRequest = {
-      userAgent,
-      ip: Array.isArray(ip) ? ip[0] : ip.split(",")[0],
-      path,
-      method: req.method,
-      referrer: req.get("referrer") || null,
-      acceptLanguage: req.get("accept-language") || null,
-      acceptEncoding: req.get("accept-encoding") || null,
-      secFetchSite: req.get("sec-fetch-site") || null,
-      httpVersion: req.httpVersion || null,
-      automationHeaders: extractAutomationHeaders(req.headers as any),
-    };
-
-    // 2. Detect bots
-    const result = detectBot(normalizedReq, config.customBots);
-
-    // 3. Check if we should track
-    const shouldTrackBot =
-      result.isBot &&
-      (config.trackSearchBots !== false || result.botCategory !== "search");
-
-    if (config.trackAll || shouldTrackBot) {
-      const payload: ServerTrackPayload = {
-        projectId: config.projectId,
-        path: normalizedReq.path,
-        method: normalizedReq.method,
-        referrer: normalizedReq.referrer,
-        userAgent: normalizedReq.userAgent,
-        ip: normalizedReq.ip,
-        isBot: result.isBot,
-        botName: result.botName,
-        botCategory: result.botCategory,
-        confidence: result.confidence,
-        detectionMethod: result.method,
-        source: "server-middleware",
-        timestamp: new Date().toISOString(),
-      };
-
-      // Fire and forget
-      sendToTelemetry(payload, config).catch((err: any) => {
-        if (config.debug) {
-          console.error(
-            "[Telemetry Middleware] Failed to send to telemetry:",
-            err,
-          );
-        }
-      });
-    }
-
-    // Always continue the request
-    next();
-  };
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../packages/core/tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}