@adwait12345/telemetry-next 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,153 @@
+# `@adwait12345/telemetry-next`
+
+Next.js middleware adapter for the Telemetry SDK. Detects bots and crawlers on every server-side request and sends tracking payloads to the Telemetry API — without slowing down your users.
+
+---
+
+## Requirements
+
+- Next.js **13.0.0 or later** (App Router or Pages Router)
+- A Telemetry account with a **Project ID** and **Server Secret**
+
+---
+
+## Installation
+
+```bash
+npm install @adwait12345/telemetry-next @adwait12345/telemetry-core
+# or
+pnpm add @adwait12345/telemetry-next @adwait12345/telemetry-core
+```
+
+---
+
+## Setup
+
+### 1. Create `middleware.ts` at the root of your project
+
+```typescript
+// middleware.ts  (next to your app/ or pages/ folder)
+import { telemetryMiddleware } from "@adwait12345/telemetry-next";
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+const telemetry = telemetryMiddleware({
+  projectId: "your-project-id",
+  apiUrl: "https://telemetry-uqd3.onrender.com",
+  serverSecret: "sk_...",
+  debug: false,
+});
+
+export async function middleware(req: NextRequest) {
+  await telemetry(req);
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    // Match all routes except Next.js internals and static files
+    "/((?!_next/static|_next/image|favicon.ico).*)",
+  ],
+};
+```
+
+### 2. Use environment variables (recommended)
+
+```typescript
+const telemetry = telemetryMiddleware({
+  projectId: process.env.TELEMETRY_PROJECT_ID!,
+  apiUrl: process.env.TELEMETRY_API_URL,
+  serverSecret: process.env.TELEMETRY_SERVER_SECRET!,
+});
+```
+
+```bash
+# .env.local
+TELEMETRY_PROJECT_ID=your-project-id
+TELEMETRY_API_URL=https://telemetry-uqd3.onrender.com
+TELEMETRY_SERVER_SECRET=sk_...
+```
+
+---
+
+## How it works
+
+1. **Every request** that passes the `matcher` runs through the middleware
+2. The request is normalized (UA, IP, headers) and passed to `detectBot()`
+3. If a bot is detected (or `trackAll: true`), a payload is sent to the Telemetry API
+4. On **Vercel Edge / Cloudflare Workers**, `waitUntil` is used so the send happens after the response is sent — zero latency impact
+5. On other runtimes, the send is `await`ed before `NextResponse.next()` is returned
+
+---
+
+## 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 API routes and health checks
+
+```typescript
+telemetryMiddleware({
+  projectId: "...",
+  serverSecret: "sk_...",
+  ignorePaths: ["/health", "/ping", /^\/api\//],
+});
+```
+
+### Track all visitors (not just bots)
+
+```typescript
+telemetryMiddleware({
+  projectId: "...",
+  serverSecret: "sk_...",
+  trackAll: true,
+});
+```
+
+### Add custom bot definitions
+
+```typescript
+telemetryMiddleware({
+  projectId: "...",
+  serverSecret: "sk_...",
+  customBots: [
+    { name: "MyInternalCrawler", pattern: /my-crawler\/\d+/i, category: "scraper" },
+  ],
+});
+```
+
+---
+
+## What gets tracked
+
+Each bot detection event sends:
+
+| Field | Description |
+|-------|-------------|
+| `projectId` | Your project ID |
+| `path` | Request path |
+| `method` | HTTP method |
+| `userAgent` | Full user-agent string |
+| `ip` | Client IP (from `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"` / `"automation-header"` / etc. |
+| `referrer` | Referrer header |
+| `timestamp` | ISO 8601 UTC |

package/package.json

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

package/src/index.ts

@@ -1,89 +0,0 @@
-import { ServerTrackPayload } from "@adwait12345/telemetry-core";
-import { type NextRequest, type NextResponse } from "next/server";
-import {
-  detectBot,
-  extractAutomationHeaders,
-  sendToTelemetry,
-  type TelemetryConfig,
-  type NormalizedRequest,
-} from "@adwait12345/telemetry-core";
-
-export function telemetryMiddleware(config: TelemetryConfig) {
-  return async function (req: NextRequest): Promise<void> {
-    const userAgent = req.headers.get("user-agent") || "";
-    const ip = req.ip || req.headers.get("x-forwarded-for") || "";
-    const url = new URL(req.url);
-    const path = url.pathname;
-
-    if (config.ignorePaths) {
-      for (const ignorePath of config.ignorePaths) {
-        if (typeof ignorePath === "string" && path === ignorePath) {
-          return;
-        } else if (ignorePath instanceof RegExp && ignorePath.test(path)) {
-          return;
-        }
-      }
-    }
-
-    // Convert headers to a standard object for extractAutomationHeaders
-    const headersObj: Record<string, string> = {};
-    req.headers.forEach((value, key) => {
-      headersObj[key] = value;
-    });
-
-    const normalizedReq: NormalizedRequest = {
-      userAgent,
-      ip: ip.split(",")[0],
-      path,
-      method: req.method,
-      referrer: req.headers.get("referer") || null,
-      acceptLanguage: req.headers.get("accept-language") || null,
-      acceptEncoding: req.headers.get("accept-encoding") || null,
-      secFetchSite: req.headers.get("sec-fetch-site") || null,
-      httpVersion: null, // Next.js middleware doesn't easily expose http version
-      automationHeaders: extractAutomationHeaders(headersObj),
-    };
-
-    const result = detectBot(normalizedReq, config.customBots);
-
-    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(),
-      };
-
-      // Use waitUntil if available (Vercel edge runtime), otherwise fire-and-forget
-      const sendPromise = sendToTelemetry(payload, config).catch((err: any) => {
-        if (config.debug) {
-          console.error(
-            "[Telemetry Middleware] Failed to send to telemetry:",
-            err,
-          );
-        }
-      });
-
-      // @ts-ignore — waitUntil is available on Vercel/Cloudflare edge runtimes
-      if (typeof globalThis !== "undefined" && (globalThis as any).waitUntil) {
-        // @ts-ignore
-        (globalThis as any).waitUntil(sendPromise);
-      } else {
-        await sendPromise;
-      }
-    }
-  };
-}

package/tsconfig.json

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