2027-track 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# 2027-track
+
+Track AI coding agents (Claude Code, Codex, OpenCode) visiting your documentation.
+
+## Installation
+
+```bash
+npm install 2027-track
+```
+
+## Usage with Next.js
+
+```ts
+// middleware.ts
+import { withAIAnalytics } from "2027-track/next";
+
+export default withAIAnalytics();
+
+// Or wrap your existing middleware:
+export default withAIAnalytics(yourExistingMiddleware);
+```
+
+## Usage (generic)
+
+```ts
+import { trackVisit } from "2027-track";
+
+await trackVisit({
+  host: "docs.example.com",
+  path: "/api/getting-started",
+  userAgent: request.headers.get("user-agent"),
+  accept: request.headers.get("accept"),
+  country: "US", // optional
+});
+```
+
+## Configuration
+
+### Kill switch
+
+Set `AI_ANALYTICS_ENDPOINT=""` to disable tracking entirely.
+
+### Custom endpoint
+
+Set `AI_ANALYTICS_ENDPOINT` to your own endpoint URL.
+
+## Privacy
+
+- 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
+
+## Detection
+
+| Agent | Signal |
+|-------|--------|
+| Claude Code | `axios` user-agent + `text/markdown` accept |
+| OpenCode | `text/markdown` accept with `q=` weights |
+| Codex | `ChatGPT-User` user-agent |
+
+Dashboard: https://ai-docs-analytics.vercel.app

package/dist/chunk-Z3U3YF4H.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 shouldTrack(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 (!shouldTrack(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.d.mts

@@ -0,0 +1,17 @@
+interface TrackOptions {
+    host: string;
+    path: string;
+    userAgent: string;
+    accept: string;
+    country?: string;
+}
+interface TrackResult {
+    ok: boolean;
+    category?: string;
+    agent?: string;
+    skipped?: string;
+    error?: string;
+}
+declare function trackVisit(options: TrackOptions): Promise<TrackResult>;
+
+export { type TrackOptions, type TrackResult, trackVisit };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+interface TrackOptions {
+    host: string;
+    path: string;
+    userAgent: string;
+    accept: string;
+    country?: string;
+}
+interface TrackResult {
+    ok: boolean;
+    category?: string;
+    agent?: string;
+    skipped?: string;
+    error?: string;
+}
+declare function trackVisit(options: TrackOptions): Promise<TrackResult>;
+
+export { type TrackOptions, type TrackResult, trackVisit };

package/dist/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  trackVisit: () => trackVisit
+});
+module.exports = __toCommonJS(index_exports);
+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 shouldTrack(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 (!shouldTrack(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" };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  trackVisit
+});

package/dist/index.mjs

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

package/dist/next.d.mts

@@ -0,0 +1,6 @@
+import { NextMiddleware } from 'next/server';
+export { trackVisit } from './index.mjs';
+
+declare function withAIAnalytics(middleware?: NextMiddleware): NextMiddleware;
+
+export { withAIAnalytics };

package/dist/next.d.ts

@@ -0,0 +1,6 @@
+import { NextMiddleware } from 'next/server';
+export { trackVisit } from './index.js';
+
+declare function withAIAnalytics(middleware?: NextMiddleware): NextMiddleware;
+
+export { withAIAnalytics };

package/dist/next.js

@@ -0,0 +1,91 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next.ts
+var next_exports = {};
+__export(next_exports, {
+  trackVisit: () => trackVisit,
+  withAIAnalytics: () => withAIAnalytics
+});
+module.exports = __toCommonJS(next_exports);
+var import_server = require("next/server");
+
+// 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 shouldTrack(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 (!shouldTrack(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" };
+  }
+}
+
+// src/next.ts
+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(() => {
+    });
+    return response;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  trackVisit,
+  withAIAnalytics
+});

package/dist/next.mjs

@@ -0,0 +1,24 @@
+import {
+  trackVisit
+} from "./chunk-Z3U3YF4H.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(() => {
+    });
+    return response;
+  };
+}
+export {
+  trackVisit,
+  withAIAnalytics
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "2027-track",
+  "version": "0.1.0",
+  "description": "Track AI coding agents visiting your documentation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caffeinum/ai-docs-analytics"
+  },
+  "homepage": "https://github.com/caffeinum/ai-docs-analytics#readme",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.mjs",
+      "require": "./dist/next.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/next.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/next.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "ai",
+    "analytics",
+    "middleware",
+    "nextjs",
+    "vercel",
+    "claude",
+    "codex",
+    "opencode"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.2.1",
+    "next": "^14.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}