2027-track 0.1.0 → 0.1.2

package/README.md

@@ -34,6 +34,37 @@ await trackVisit({
 });
 ```
 
+## Route Filtering
+
+**Important:** Only track public documentation routes. Exclude private endpoints to avoid leaking sensitive paths.
+
+### Next.js matcher (recommended)
+
+```ts
+// middleware.ts
+import { withAIAnalytics } from "2027-track/next";
+
+export default withAIAnalytics();
+
+export const config = {
+  matcher: [
+    // Exclude private routes, track everything else
+    "/((?!api|_next|app|admin|dashboard|auth|login|signup).*)",
+  ],
+};
+```
+
+### Manual filtering
+
+```ts
+import { trackVisit } from "2027-track";
+
+// Only track if path starts with /docs
+if (path.startsWith("/docs")) {
+  await trackVisit({ host, path, userAgent, accept });
+}
+```
+
 ## Configuration
 
 ### Kill switch
@@ -49,13 +80,12 @@ Set `AI_ANALYTICS_ENDPOINT` to your own endpoint URL.
 - Events are sent **server-side** from Vercel Edge (or your server)
 - Visitor IP addresses **never reach** the analytics endpoint
 - Only headers (user-agent, accept) and page info (host, path) are sent
+- **No cookies, no fingerprinting, no personal identifiers**
+
+This middleware collects no personally identifiable information (PII). Because there are no cookies, no IP forwarding, and no user identifiers, it generally does not trigger privacy policy or cookie-consent requirements under GDPR, CCPA, or similar regulations. That said, you should verify with your own legal counsel, especially under strict EU interpretations.
 
 ## Detection
 
-| Agent | Signal |
-|-------|--------|
-| Claude Code | `axios` user-agent + `text/markdown` accept |
-| OpenCode | `text/markdown` accept with `q=` weights |
-| Codex | `ChatGPT-User` user-agent |
+Agent classification (user-agent and accept header matching) happens server-side at the analytics endpoint — the middleware only forwards raw headers.
 
 Dashboard: https://ai-docs-analytics.vercel.app

package/dist/chunk-2UMSOEKA.mjs

@@ -0,0 +1,46 @@
+// src/index.ts
+var DEFAULT_ENDPOINT = "https://ai-docs-analytics-api.theisease.workers.dev/track";
+var TIMEOUT_MS = 2500;
+function getEndpoint() {
+  const env = typeof process !== "undefined" ? process.env.AI_ANALYTICS_ENDPOINT : void 0;
+  if (env === "") return null;
+  return env || DEFAULT_ENDPOINT;
+}
+function isPageView(accept) {
+  const a = accept.toLowerCase();
+  return a.includes("text/html") || a.includes("text/markdown");
+}
+async function trackVisit(options) {
+  const endpoint = getEndpoint();
+  if (!endpoint) {
+    return { ok: true, skipped: "disabled" };
+  }
+  if (!isPageView(options.accept)) {
+    return { ok: true, skipped: "not-page-view" };
+  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        host: options.host,
+        path: options.path,
+        user_agent: options.userAgent,
+        accept: options.accept,
+        country: options.country || "unknown"
+      }),
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    return await response.json();
+  } catch (e) {
+    clearTimeout(timeoutId);
+    return { ok: false, error: e instanceof Error ? e.message : "unknown error" };
+  }
+}
+
+export {
+  trackVisit
+};

package/dist/index.js

@@ -30,7 +30,7 @@ function getEndpoint() {
   if (env === "") return null;
   return env || DEFAULT_ENDPOINT;
 }
-function shouldTrack(accept) {
+function isPageView(accept) {
   const a = accept.toLowerCase();
   return a.includes("text/html") || a.includes("text/markdown");
 }
@@ -39,7 +39,7 @@ async function trackVisit(options) {
   if (!endpoint) {
     return { ok: true, skipped: "disabled" };
   }
-  if (!shouldTrack(options.accept)) {
+  if (!isPageView(options.accept)) {
     return { ok: true, skipped: "not-page-view" };
   }
   const controller = new AbortController();

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   trackVisit
-} from "./chunk-Z3U3YF4H.mjs";
+} from "./chunk-2UMSOEKA.mjs";
 export {
   trackVisit
 };

package/dist/next.js

@@ -34,7 +34,7 @@ function getEndpoint() {
   if (env === "") return null;
   return env || DEFAULT_ENDPOINT;
 }
-function shouldTrack(accept) {
+function isPageView(accept) {
   const a = accept.toLowerCase();
   return a.includes("text/html") || a.includes("text/markdown");
 }
@@ -43,7 +43,7 @@ async function trackVisit(options) {
   if (!endpoint) {
     return { ok: true, skipped: "disabled" };
   }
-  if (!shouldTrack(options.accept)) {
+  if (!isPageView(options.accept)) {
     return { ok: true, skipped: "not-page-view" };
   }
   const controller = new AbortController();
@@ -73,14 +73,16 @@ async function trackVisit(options) {
 function withAIAnalytics(middleware) {
   return async (request, event) => {
     const response = middleware ? await middleware(request, event) : import_server.NextResponse.next();
-    trackVisit({
-      host: request.headers.get("host") || request.nextUrl.host,
-      path: request.nextUrl.pathname,
-      userAgent: request.headers.get("user-agent") || "",
-      accept: request.headers.get("accept") || "",
-      country: request.geo?.country || "unknown"
-    }).catch(() => {
-    });
+    event.waitUntil(
+      trackVisit({
+        host: request.headers.get("host") || request.nextUrl.host,
+        path: request.nextUrl.pathname,
+        userAgent: request.headers.get("user-agent") || "",
+        accept: request.headers.get("accept") || "",
+        country: request.geo?.country || "unknown"
+      }).catch(() => {
+      })
+    );
     return response;
   };
 }

package/dist/next.mjs

@@ -1,20 +1,22 @@
 import {
   trackVisit
-} from "./chunk-Z3U3YF4H.mjs";
+} from "./chunk-2UMSOEKA.mjs";
 
 // src/next.ts
 import { NextResponse } from "next/server";
 function withAIAnalytics(middleware) {
   return async (request, event) => {
     const response = middleware ? await middleware(request, event) : NextResponse.next();
-    trackVisit({
-      host: request.headers.get("host") || request.nextUrl.host,
-      path: request.nextUrl.pathname,
-      userAgent: request.headers.get("user-agent") || "",
-      accept: request.headers.get("accept") || "",
-      country: request.geo?.country || "unknown"
-    }).catch(() => {
-    });
+    event.waitUntil(
+      trackVisit({
+        host: request.headers.get("host") || request.nextUrl.host,
+        path: request.nextUrl.pathname,
+        userAgent: request.headers.get("user-agent") || "",
+        accept: request.headers.get("accept") || "",
+        country: request.geo?.country || "unknown"
+      }).catch(() => {
+      })
+    );
     return response;
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "2027-track",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Track AI coding agents visiting your documentation",
   "repository": {
     "type": "git",