@smolcap/ai-tracker-nextjs 1.0.0 → 1.1.0

package/README.md

@@ -1,39 +1,71 @@
 # @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.
+Track AI bot visits on your Next.js site with AI Tracker. The tracker runs in a fire-and-forget
+pattern inside Next.js proxy code: requests are not awaited and responses are never touched, so
+there is zero impact on page load times.
+
+## Setup
 
 ```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/`:
+Create or update `proxy.ts` in the root of your project (inside `src/` if you use it;
+`middleware.ts` before Next.js 16):
 
 ```ts
 import { withAiTracker } from "@smolcap/ai-tracker-nextjs";
 
 export default withAiTracker({
-  siteKey: process.env.AI_TRACKER_KEY,
-  endpoint: "https://your-ai-tracker-dashboard.example",
+  siteKey: process.env.AI_TRACKER_KEY!,
 });
 
 export const config = {
-  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
+  matcher: [
+    "/robots.txt",
+    "/sitemap.xml",
+    "/((?!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:
+Set `AI_TRACKER_KEY` to your site key, then deploy as usual.
+
+## Custom proxy logic
+
+Pass your existing proxy as the second argument. It is called with the same arguments and whatever
+it returns or throws reaches Next.js unchanged.
 
 ```ts
-export default withAiTracker({ siteKey: process.env.AI_TRACKER_KEY, endpoint }, (request) => {
-  // your existing logic
+import { type AiTrackerConfig, withAiTracker } from "@smolcap/ai-tracker-nextjs";
+import { NextResponse, type NextRequest } from "next/server";
+
+const aiTrackerConfig: AiTrackerConfig = {
+  siteKey: process.env.AI_TRACKER_KEY!,
+  debug: process.env.NODE_ENV === "development",
+};
+
+export default withAiTracker(aiTrackerConfig, (request: NextRequest) => {
+  const response = NextResponse.next();
+  response.headers.set("x-custom-header", "value");
+  return response;
 });
 ```
 
+## Configuration
+
+| Option | Type | |
+| --- | --- | --- |
+| `siteKey` | `string` | Your site key. Defaults to the `AI_TRACKER_KEY` environment variable. While empty, tracking is off. |
+| `endpoint` | `string` | Custom AI Tracker origin. Most sites can omit this. |
+| `debug` | `boolean` | Logs why a visit was not recorded. |
+
+## Behaviour
+
 - 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.
+- A missing key or invalid endpoint turns tracking off with one warning; nothing ever throws.
+- A site key only accepts visits for its own hostname; previews and other hostnames are rejected.
 - 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

@@ -1,12 +1,17 @@
+export declare const DEFAULT_ENDPOINT = "https://ai-tracker.smol.capital";
 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;
+    /** The site key for this exact hostname. Defaults to the AI_TRACKER_KEY environment variable; tracking is off while it is empty. */
+    siteKey?: string;
+    /** Custom AI Tracker origin. Most sites can omit this. */
+    endpoint?: string;
+    /** Logs why a visit was not recorded. Use only while developing or troubleshooting. */
+    debug?: boolean;
 };
 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;
+type Middleware<R extends Request, E extends FetchEvent, T> = (request: R, event: E) => T;
+export declare function withAiTracker(config?: AiTrackerConfig): Middleware<Request, FetchEvent, void>;
+export declare function withAiTracker<R extends Request, E extends FetchEvent, T>(middleware: Middleware<R, E, T>): Middleware<R, E, T>;
+export declare function withAiTracker<R extends Request, E extends FetchEvent, T>(config: AiTrackerConfig, middleware: Middleware<R, E, T>): Middleware<R, E, T>;
 export {};

package/dist/index.js

@@ -3,7 +3,8 @@
 // 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) {
+export const DEFAULT_ENDPOINT = "https://ai-tracker.smol.capital";
+function track(request, event, ingest, siteKey, debug) {
     const userAgent = request.headers.get("user-agent") ?? "";
     if ((request.method !== "GET" && request.method !== "HEAD") || !BOT_HINTS.test(userAgent))
         return;
@@ -20,23 +21,32 @@ function track(request, event, ingest, siteKey) {
         // Manual redirects never forward the site key.
         redirect: "manual",
         signal: AbortSignal.timeout(1500),
-    }).then((response) => response.body?.cancel()).catch(() => { }));
+    }).then((response) => {
+        if (debug && !response.ok)
+            console.warn(`[ai-tracker] Visit rejected: HTTP ${response.status}`);
+        return response.body?.cancel();
+    }).catch((error) => { if (debug)
+        console.warn("[ai-tracker] Visit not sent:", error instanceof Error ? error.message : error); }));
 }
-export function withAiTracker(config, middleware) {
+export function withAiTracker(first, second) {
+    const middleware = typeof first === "function" ? first : second;
     // A throw while this module loads would take the whole site down, so bad configuration only disables tracking.
-    let ingest;
+    let ingest, siteKey, debug = false;
     try {
-        const url = new URL("/api/ingest", config.endpoint);
+        const config = (typeof first === "function" ? undefined : first) ?? {};
+        siteKey = config.siteKey || process.env.AI_TRACKER_KEY;
+        debug = config.debug === true;
+        const url = new URL("/api/ingest", config.endpoint || DEFAULT_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.");
+    if (!ingest || !siteKey)
+        console.warn("[ai-tracker] Tracking is off: set AI_TRACKER_KEY (and use an https endpoint).");
     return (request, event) => {
         try {
-            if (ingest && config.siteKey)
-                track(request, event, ingest, config.siteKey);
+            if (ingest && siteKey)
+                track(request, event, ingest, siteKey, debug);
         }
         catch {
             // Tracking must never fail a request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smolcap/ai-tracker-nextjs",
-  "version": "1.0.0",
+  "version": "1.1.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",