everfound-tracker 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# everfound-tracker
+
+See which AI agents actually read your site — GPTBot, ClaudeBot, Perplexity, and friends — plus the human visitors AI assistants send you. Reports to your [Everfound](https://everfound.ai) dashboard.
+
+## Install
+
+```sh
+npm install everfound-tracker
+```
+
+## Use (Vercel, any framework)
+
+Create `middleware.ts` in your project root:
+
+```ts
+import { everfound } from "everfound-tracker";
+
+export default everfound({ key: "your-site-key" });
+export const config = { matcher: "/((?!_next/|.*\\.(?:js|css|png|jpg|svg|ico|woff2?)$).*)" };
+```
+
+Your site key is in the Everfound dashboard under **AI agents on your site → Install the tracker**. It's safe to commit — it only authorizes reporting traffic for your own site.
+
+Already have a `middleware.ts`? Call the tracker from it instead:
+
+```ts
+import { everfound } from "everfound-tracker";
+
+const track = everfound({ key: "your-site-key" });
+
+export default function middleware(request: Request, context: { waitUntil(p: Promise<unknown>): void }) {
+  track(request, context);
+  // ...your existing middleware logic
+}
+```
+
+## How it works
+
+- Fires only on AI/bot user agents and on human visits referred from AI surfaces (ChatGPT, Perplexity, Gemini, Copilot, …) — ordinary traffic never leaves your infrastructure.
+- Fire-and-forget: never blocks, never throws, never breaks a request.
+- The Everfound server does the authoritative classification and crawler-IP verification. New AI agents are added server-side — you don't need to update this package to track them.
+- The client IP is forwarded on bot hits only (to verify crawlers against their operators' published IP ranges) and never on human referral clicks.
+
+## License
+
+MIT © Digital Bar LLC

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export type EverfoundOptions = {
+    /** Per-site key from your Everfound dashboard. Safe to commit — it only authorizes reporting traffic for your own site. */
+    key: string;
+    /** Override the tracked host. Defaults to the request's hostname (www-stripped). */
+    host?: string;
+    /** Override the ingest endpoint. Defaults to the Everfound API. */
+    endpoint?: string;
+};
+type EdgeContext = {
+    waitUntil(promise: Promise<unknown>): void;
+};
+/**
+ * Create the Everfound tracking middleware.
+ *
+ * ```ts
+ * // middleware.ts
+ * import { everfound } from "everfound-tracker";
+ *
+ * export default everfound({ key: "your-site-key" });
+ * export const config = { matcher: "/((?!_next/|.*\\.(?:js|css|png|jpg|svg|ico|woff2?)$).*)" };
+ * ```
+ *
+ * Fire-and-forget by design: it never blocks or breaks a request, and it
+ * forwards the client IP on bot hits only (crawler verification) — never on
+ * human referral clicks.
+ */
+export declare function everfound(options: EverfoundOptions): (request: Request, context?: EdgeContext) => void;
+export {};

package/dist/index.js

@@ -0,0 +1,63 @@
+// everfound-tracker — drop-in middleware that reports AI crawler traffic and
+// AI referral clicks to your Everfound dashboard.
+//
+// The middleware is a thin forwarder: it pre-filters with broad, stable shape
+// patterns (bot-ish user agents, AI chat referrers) purely to avoid sending
+// ordinary human traffic, and the Everfound server does the authoritative
+// per-agent classification, crawler-IP verification, and quarantine of agents
+// it doesn't recognize yet. New AI agents are picked up by the server-side
+// catalog — sites do not need to update this package when the catalog grows.
+// Broad shapes, not an agent catalog: generic crawler tokens, AI vendor names,
+// and vendor prefixes. Deliberately over-inclusive — the server classifies and
+// quarantines; this only keeps ordinary human page views off the wire.
+const BOTISH = /bot\b|crawler|spider|scrape|fetch|agent\b|gpt|claude|gemini|mistral|llm|anthropic|perplexity|openai|google-|googleother|openclaw|moltbot|cohere|omgili|bytespider|petalbot|youbot|timpibot/i;
+// AI chat surfaces that send human visitors (referer header or utm_source).
+const AI_REFS = /chatgpt|chat\.openai\.com|perplexity|claude\.ai|gemini\.google|bard\.google|copilot\.microsoft|\bmeta\.ai|grok\.com|chat\.mistral\.ai|\byou\.com/i;
+// Static assets are never interesting — skipped even without a matcher.
+const ASSET = /\.(?:js|mjs|css|map|png|jpe?g|gif|svg|ico|webp|avif|woff2?|ttf|otf|mp4|webm|pdf)$/i;
+/**
+ * Create the Everfound tracking middleware.
+ *
+ * ```ts
+ * // middleware.ts
+ * import { everfound } from "everfound-tracker";
+ *
+ * export default everfound({ key: "your-site-key" });
+ * export const config = { matcher: "/((?!_next/|.*\\.(?:js|css|png|jpg|svg|ico|woff2?)$).*)" };
+ * ```
+ *
+ * Fire-and-forget by design: it never blocks or breaks a request, and it
+ * forwards the client IP on bot hits only (crawler verification) — never on
+ * human referral clicks.
+ */
+export function everfound(options) {
+    const endpoint = options.endpoint ?? "https://everfound.ai/api/track";
+    return function middleware(request, context) {
+        try {
+            const url = new URL(request.url);
+            if (url.pathname.startsWith("/_next/") || ASSET.test(url.pathname)) {
+                return;
+            }
+            const ua = request.headers.get("user-agent") ?? "";
+            const ref = request.headers.get("referer") ?? "";
+            const utm = url.searchParams.get("utm_source") ?? "";
+            const isBot = BOTISH.test(ua);
+            if (!isBot && !AI_REFS.test(`${ref} ${utm}`)) {
+                return;
+            }
+            const ip = isBot ? (request.headers.get("x-forwarded-for") ?? "").split(",")[0].trim() : "";
+            const host = options.host ?? url.hostname.replace(/^www\./, "");
+            const send = fetch(endpoint, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ host, key: options.key, path: url.pathname, ua, ref, utm, ip }),
+            }).then(() => undefined, () => undefined);
+            if (context && typeof context.waitUntil === "function") {
+                context.waitUntil(send);
+            }
+        }
+        catch {
+            // Tracking must never break the site.
+        }
+    };
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "everfound-tracker",
+  "version": "0.1.0",
+  "description": "See which AI agents read your site — drop-in middleware that reports AI crawler traffic and AI referral clicks to your Everfound dashboard.",
+  "keywords": ["ai", "analytics", "crawler", "gptbot", "claudebot", "middleware", "vercel", "everfound"],
+  "homepage": "https://everfound.ai",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}