@smolcap/ai-tracker-nextjs 1.0.0

package/README.md

@@ -0,0 +1,39 @@
+# @smolcap/ai-tracker-nextjs
+
+Reports AI crawler visits to AI Tracker from a Next.js proxy. It never builds, awaits or
+changes a response: your pages are served exactly as before, and every tracking error is swallowed.
+
+```sh
+npm install @smolcap/ai-tracker-nextjs
+```
+
+`proxy.ts` on Next.js 16+, `middleware.ts` on Next.js 13–15, next to `app/` or `pages/`:
+
+```ts
+import { withAiTracker } from "@smolcap/ai-tracker-nextjs";
+
+export default withAiTracker({
+  siteKey: process.env.AI_TRACKER_KEY,
+  endpoint: "https://your-ai-tracker-dashboard.example",
+});
+
+export const config = {
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+};
+```
+
+Already have a proxy? Pass it as the second argument. It receives the same arguments and its
+return value (or thrown error) reaches Next.js untouched:
+
+```ts
+export default withAiTracker({ siteKey: process.env.AI_TRACKER_KEY, endpoint }, (request) => {
+  // your existing logic
+});
+```
+
+- Only `GET`/`HEAD` page requests whose user agent looks like a crawler are reported, in the
+  background through `event.waitUntil`, with a 1.5 s timeout. Everything else returns immediately.
+- A missing key or invalid endpoint turns tracking off with one warning; it never throws.
+- The proxy runs before rendering, so status codes are not recorded. Visitor IPs are read only from
+  headers set by Vercel (`x-vercel-forwarded-for`) or Cloudflare (`cf-connecting-ip`).
+- Remove it by deleting the file (or unwrapping your proxy) and redeploying.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type AiTrackerConfig = {
+    /** The site key for this exact hostname. Tracking is off while it is empty. */
+    siteKey: string | undefined;
+    /** Your AI Tracker dashboard origin, e.g. https://tracker.example */
+    endpoint: string;
+};
+type FetchEvent = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+export declare function withAiTracker(config: AiTrackerConfig): (request: Request, event: FetchEvent) => void;
+export declare function withAiTracker<R extends Request, E extends FetchEvent, T>(config: AiTrackerConfig, middleware: (request: R, event: E) => T): (request: R, event: E) => T;
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+// Wraps a Next.js proxy (middleware before Next.js 16). Your own function's return value, or nothing,
+// goes back to Next.js untouched; this package never builds, awaits or changes a response.
+// Classification and verification live on the tracker; this only forwards candidate visits.
+const BOT_HINTS = /bot|crawler|spider|crawl|gpt|claude|perplexity|bing|applebot|bytespider|ccbot|amazon|amzn|meta-|duckassist|mistral|google|copilot|grok|kimi|qwen|cohere|msnbot/i;
+const ASSET_PATH = /\.(?:js|mjs|cjs|css|map|png|jpe?g|gif|webp|avif|svg|ico|bmp|tiff?|woff2?|ttf|otf|eot|mp[34]|webm|ogg|wav|m4[av]|mov|wasm)$|^\/(?:api|_next|_vercel|cdn-cgi)(?:\/|$)/i;
+function track(request, event, ingest, siteKey) {
+    const userAgent = request.headers.get("user-agent") ?? "";
+    if ((request.method !== "GET" && request.method !== "HEAD") || !BOT_HINTS.test(userAgent))
+        return;
+    const url = new URL(request.url);
+    if (ASSET_PATH.test(url.pathname) || url.hostname === ingest.hostname)
+        return;
+    // Only headers the platform sets itself; x-forwarded-for is visitor-supplied on many hosts.
+    const ip = request.headers.get("cf-connecting-ip") ?? request.headers.get("x-vercel-forwarded-for")?.split(",", 1)[0].trim();
+    // Sent after the response is on its way; a slow or failing tracker never reaches the visitor.
+    event.waitUntil(fetch(ingest, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${siteKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ href: `${url.origin}${url.pathname}`, ai: { userAgent, ...(ip ? { ip } : {}), source: "nextjs" } }),
+        // Manual redirects never forward the site key.
+        redirect: "manual",
+        signal: AbortSignal.timeout(1500),
+    }).then((response) => response.body?.cancel()).catch(() => { }));
+}
+export function withAiTracker(config, middleware) {
+    // A throw while this module loads would take the whole site down, so bad configuration only disables tracking.
+    let ingest;
+    try {
+        const url = new URL("/api/ingest", config.endpoint);
+        if (url.protocol === "https:" && !url.username && !url.password)
+            ingest = url;
+    }
+    catch { }
+    if (!ingest || !config.siteKey)
+        console.warn("[ai-tracker] Tracking is off: set siteKey and an https endpoint.");
+    return (request, event) => {
+        try {
+            if (ingest && config.siteKey)
+                track(request, event, ingest, config.siteKey);
+        }
+        catch {
+            // Tracking must never fail a request.
+        }
+        return middleware?.(request, event);
+    };
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@smolcap/ai-tracker-nextjs",
+  "version": "1.0.0",
+  "description": "AI Tracker for Next.js: reports AI crawler visits from proxy.ts or middleware.ts without touching the response",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json", "prepublishOnly": "npm run build" },
+  "peerDependencies": { "next": ">=13.0.0" },
+  "publishConfig": { "access": "public" }
+}