@apideck/agent-analytics 0.1.0

package/dist/markdown.d.cts

@@ -0,0 +1,63 @@
+type MarkdownServeReason = 'ua-rewrite' | 'md-suffix' | 'accept-header';
+interface MarkdownDecision {
+    /** Why this request should be served Markdown. */
+    reason: MarkdownServeReason;
+    /**
+     * The request's original logical path, with any trailing `.md` stripped.
+     * Use this when mapping to a mirror file.
+     */
+    strippedPath: string;
+}
+/**
+ * Decide whether the request should be served Markdown instead of HTML.
+ * Returns `null` when the request should go through your normal handler.
+ *
+ * Covers three triggers:
+ * - Known AI-bot UA on any URL (`ua-rewrite`)
+ * - Explicit `.md` suffix on the URL (`md-suffix`)
+ * - `Accept: text/markdown` header (`accept-header`)
+ *
+ * This helper intentionally does not perform the rewrite itself — routing is
+ * framework-specific (NextResponse.rewrite for Next.js, ctx.rewrite for
+ * Hono, etc.). Use the returned decision to build the appropriate response.
+ */
+declare function markdownServeDecision(req: Request): MarkdownDecision | null;
+interface MarkdownHeadersInput {
+    /**
+     * If provided, rendered as `x-markdown-tokens` so agents can budget context
+     * before parsing the body. Typically `Math.ceil(body.length / 4)`.
+     */
+    tokens?: number;
+    /**
+     * Content-Signal directive (see contentsignals.org). Defaults to
+     * `'search=yes, ai-input=yes, ai-train=no'` — change if you want to permit
+     * training or restrict indexing.
+     */
+    contentSignal?: string;
+}
+/**
+ * Build the set of response headers to attach to a Markdown response. Safe
+ * defaults: UTF-8 text/markdown, Vary: accept, and a Content-Signal directive
+ * that permits search + agent input but denies training.
+ */
+declare function markdownHeaders(input?: MarkdownHeadersInput): Record<string, string>;
+interface SynthesizePointerInput {
+    origin: string;
+    pathname: string;
+    /** URL of the site's curated index, usually `/llms.txt`. */
+    llmsTxtUrl?: string;
+    /** URL of the full enumerated index, usually `/llms-full.txt`. */
+    llmsFullTxtUrl?: string;
+    /** URL of the machine-readable path manifest, usually `/md/index.json`. */
+    markdownIndexUrl?: string;
+    /** Site name to title the pointer document. Defaults to the origin hostname. */
+    siteName?: string;
+}
+/**
+ * Generate a minimal pointer Markdown document for URLs that don't have a
+ * pre-built mirror. Keeps the `Accept: text/markdown` contract intact
+ * site-wide — agents always get *something* parseable, not a 404.
+ */
+declare function synthesizeMarkdownPointer(input: SynthesizePointerInput): string;
+
+export { type MarkdownDecision, type MarkdownHeadersInput, type MarkdownServeReason, type SynthesizePointerInput, markdownHeaders, markdownServeDecision, synthesizeMarkdownPointer };

package/dist/markdown.d.ts

@@ -0,0 +1,63 @@
+type MarkdownServeReason = 'ua-rewrite' | 'md-suffix' | 'accept-header';
+interface MarkdownDecision {
+    /** Why this request should be served Markdown. */
+    reason: MarkdownServeReason;
+    /**
+     * The request's original logical path, with any trailing `.md` stripped.
+     * Use this when mapping to a mirror file.
+     */
+    strippedPath: string;
+}
+/**
+ * Decide whether the request should be served Markdown instead of HTML.
+ * Returns `null` when the request should go through your normal handler.
+ *
+ * Covers three triggers:
+ * - Known AI-bot UA on any URL (`ua-rewrite`)
+ * - Explicit `.md` suffix on the URL (`md-suffix`)
+ * - `Accept: text/markdown` header (`accept-header`)
+ *
+ * This helper intentionally does not perform the rewrite itself — routing is
+ * framework-specific (NextResponse.rewrite for Next.js, ctx.rewrite for
+ * Hono, etc.). Use the returned decision to build the appropriate response.
+ */
+declare function markdownServeDecision(req: Request): MarkdownDecision | null;
+interface MarkdownHeadersInput {
+    /**
+     * If provided, rendered as `x-markdown-tokens` so agents can budget context
+     * before parsing the body. Typically `Math.ceil(body.length / 4)`.
+     */
+    tokens?: number;
+    /**
+     * Content-Signal directive (see contentsignals.org). Defaults to
+     * `'search=yes, ai-input=yes, ai-train=no'` — change if you want to permit
+     * training or restrict indexing.
+     */
+    contentSignal?: string;
+}
+/**
+ * Build the set of response headers to attach to a Markdown response. Safe
+ * defaults: UTF-8 text/markdown, Vary: accept, and a Content-Signal directive
+ * that permits search + agent input but denies training.
+ */
+declare function markdownHeaders(input?: MarkdownHeadersInput): Record<string, string>;
+interface SynthesizePointerInput {
+    origin: string;
+    pathname: string;
+    /** URL of the site's curated index, usually `/llms.txt`. */
+    llmsTxtUrl?: string;
+    /** URL of the full enumerated index, usually `/llms-full.txt`. */
+    llmsFullTxtUrl?: string;
+    /** URL of the machine-readable path manifest, usually `/md/index.json`. */
+    markdownIndexUrl?: string;
+    /** Site name to title the pointer document. Defaults to the origin hostname. */
+    siteName?: string;
+}
+/**
+ * Generate a minimal pointer Markdown document for URLs that don't have a
+ * pre-built mirror. Keeps the `Accept: text/markdown` contract intact
+ * site-wide — agents always get *something* parseable, not a 404.
+ */
+declare function synthesizeMarkdownPointer(input: SynthesizePointerInput): string;
+
+export { type MarkdownDecision, type MarkdownHeadersInput, type MarkdownServeReason, type SynthesizePointerInput, markdownHeaders, markdownServeDecision, synthesizeMarkdownPointer };

package/dist/markdown.js

@@ -0,0 +1,64 @@
+// src/bots.ts
+var AI_BOT_PATTERN = /ClaudeBot|Claude-User|Anthropic|ChatGPT-User|GPTBot|OAI-SearchBot|PerplexityBot|Perplexity-User|Google-Extended|Applebot-Extended|cohere-ai|Bytespider|CCBot|Amazonbot|Meta-ExternalAgent|FacebookBot|DuckAssistBot|MistralAI-User|YouBot|AI2Bot|Diffbot|Cursor|Windsurf/i;
+function isAiBot(userAgent) {
+  if (!userAgent) return false;
+  return AI_BOT_PATTERN.test(userAgent);
+}
+
+// src/markdown.ts
+function markdownServeDecision(req) {
+  let pathname = "/";
+  try {
+    pathname = new URL(req.url).pathname;
+  } catch {
+    pathname = req.url || "/";
+  }
+  const ua = req.headers.get("user-agent") || "";
+  if (isAiBot(ua)) {
+    return { reason: "ua-rewrite", strippedPath: pathname };
+  }
+  if (pathname.endsWith(".md")) {
+    return { reason: "md-suffix", strippedPath: pathname.replace(/\.md$/, "") };
+  }
+  const accept = req.headers.get("accept") || "";
+  if (accept.includes("text/markdown")) {
+    return { reason: "accept-header", strippedPath: pathname };
+  }
+  return null;
+}
+function markdownHeaders(input = {}) {
+  const headers = {
+    "Content-Type": "text/markdown; charset=utf-8",
+    "Content-Signal": input.contentSignal ?? "search=yes, ai-input=yes, ai-train=no",
+    Vary: "accept"
+  };
+  if (typeof input.tokens === "number" && input.tokens > 0) {
+    headers["x-markdown-tokens"] = Math.max(1, Math.ceil(input.tokens)).toString();
+  }
+  return headers;
+}
+function synthesizeMarkdownPointer(input) {
+  const site = input.siteName ?? (() => {
+    try {
+      return new URL(input.origin).hostname;
+    } catch {
+      return input.origin;
+    }
+  })();
+  const url = `${input.origin}${input.pathname}`;
+  const lines = [`# ${site}`, "", `This page (${url}) does not have a dedicated Markdown mirror yet.`, ""];
+  const links = [];
+  if (input.llmsTxtUrl) links.push(`- [${input.llmsTxtUrl}](${input.llmsTxtUrl}) \u2014 curated index of docs`);
+  if (input.llmsFullTxtUrl)
+    links.push(`- [${input.llmsFullTxtUrl}](${input.llmsFullTxtUrl}) \u2014 full enumerated index`);
+  if (input.markdownIndexUrl)
+    links.push(`- [${input.markdownIndexUrl}](${input.markdownIndexUrl}) \u2014 JSON index of all Markdown paths`);
+  if (links.length) {
+    lines.push("For machine-readable documentation, see:", "", ...links, "");
+  }
+  return lines.join("\n");
+}
+
+export { markdownHeaders, markdownServeDecision, synthesizeMarkdownPointer };
+//# sourceMappingURL=markdown.js.map
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bots.ts","../src/markdown.ts"],"names":[],"mappings":"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","file":"markdown.js","sourcesContent":["/**\n * User-agent substrings that identify known AI crawlers and coding agents.\n * Maintained by hand; add new entries as they appear in the wild.\n *\n * Sources consulted when updating: darkvisitors.com, official docs from OpenAI,\n * Anthropic, Google, Perplexity, Cohere, Apple, Bytedance, cursor, windsurf.\n */\nexport const AI_BOT_PATTERN =\n  /ClaudeBot|Claude-User|Anthropic|ChatGPT-User|GPTBot|OAI-SearchBot|PerplexityBot|Perplexity-User|Google-Extended|Applebot-Extended|cohere-ai|Bytespider|CCBot|Amazonbot|Meta-ExternalAgent|FacebookBot|DuckAssistBot|MistralAI-User|YouBot|AI2Bot|Diffbot|Cursor|Windsurf/i\n\nexport function isAiBot(userAgent: string | null | undefined): boolean {\n  if (!userAgent) return false\n  return AI_BOT_PATTERN.test(userAgent)\n}\n\n/**\n * Map a user-agent string to a coarse, human-readable bot label. Returns\n * `'Browser'` for typical desktop browsers and `'Other'` for anything we\n * don't recognise — don't treat a non-`'Other'` result as \"definitely a bot\";\n * pair with {@link isAiBot} when that distinction matters.\n */\nexport function parseBotName(userAgent: string | null | undefined): string {\n  if (!userAgent || typeof userAgent !== 'string') return 'Other'\n  const s = userAgent.toLowerCase()\n  if (s.includes('chatgpt-user') || s.includes('gptbot') || s.includes('oai-searchbot') || s.includes('openai'))\n    return 'ChatGPT'\n  if (s.includes('claudebot') || s.includes('claude-user') || s.includes('anthropic')) return 'Claude'\n  if (s.includes('perplexitybot') || s.includes('perplexity-user')) return 'Perplexity'\n  if (s.includes('ccbot')) return 'Common Crawl'\n  if (s.includes('google-extended') || s.includes('googlebot')) return 'Google'\n  if (s.includes('applebot-extended') || s.includes('applebot')) return 'Apple'\n  if (s.includes('bingbot')) return 'Bing'\n  if (s.includes('bytespider')) return 'Bytespider'\n  if (s.includes('amazonbot')) return 'Amazon'\n  if (s.includes('meta-externalagent') || s.includes('facebookbot')) return 'Meta'\n  if (s.includes('mistralai-user')) return 'Mistral'\n  if (s.includes('duckassistbot')) return 'DuckDuckGo'\n  if (s.includes('youbot')) return 'You.com'\n  if (s.includes('diffbot')) return 'Diffbot'\n  if (s.includes('ai2bot')) return 'AI2'\n  if (s.includes('cohere')) return 'Cohere'\n  if (s.includes('cursor')) return 'Cursor'\n  if (s.includes('windsurf')) return 'Windsurf'\n  if (s.includes('petalbot')) return 'PetalBot'\n  if (s.includes('mozilla') || s.includes('chrome') || s.includes('safari') || s.includes('firefox'))\n    return 'Browser'\n  return 'Other'\n}\n\n/**\n * Return the first product token from a UA header, useful for segmenting by\n * client without hard-coding every bot name. Falls back to `'Other'` for empty\n * input.\n */\nexport function firstUserAgentProduct(userAgent: string | null | undefined): string {\n  if (!userAgent || typeof userAgent !== 'string') return 'Other'\n  const compatibleMatch = userAgent.match(/compatible;\\s*([^/;\\s]+)(?:\\/[^\\s;]*)?/i)\n  if (compatibleMatch && compatibleMatch[1]) return compatibleMatch[1].trim()\n  const first = userAgent.trim().split('/')[0]?.trim().split(/\\s+/)[0]?.trim()\n  return first || 'Other'\n}\n","import { isAiBot } from './bots.js'\n\nexport type MarkdownServeReason =\n  | 'ua-rewrite'\n  | 'md-suffix'\n  | 'accept-header'\n\nexport interface MarkdownDecision {\n  /** Why this request should be served Markdown. */\n  reason: MarkdownServeReason\n  /**\n   * The request's original logical path, with any trailing `.md` stripped.\n   * Use this when mapping to a mirror file.\n   */\n  strippedPath: string\n}\n\n/**\n * Decide whether the request should be served Markdown instead of HTML.\n * Returns `null` when the request should go through your normal handler.\n *\n * Covers three triggers:\n * - Known AI-bot UA on any URL (`ua-rewrite`)\n * - Explicit `.md` suffix on the URL (`md-suffix`)\n * - `Accept: text/markdown` header (`accept-header`)\n *\n * This helper intentionally does not perform the rewrite itself — routing is\n * framework-specific (NextResponse.rewrite for Next.js, ctx.rewrite for\n * Hono, etc.). Use the returned decision to build the appropriate response.\n */\nexport function markdownServeDecision(req: Request): MarkdownDecision | null {\n  let pathname = '/'\n  try {\n    pathname = new URL(req.url).pathname\n  } catch {\n    pathname = req.url || '/'\n  }\n\n  const ua = req.headers.get('user-agent') || ''\n  if (isAiBot(ua)) {\n    return { reason: 'ua-rewrite', strippedPath: pathname }\n  }\n\n  if (pathname.endsWith('.md')) {\n    return { reason: 'md-suffix', strippedPath: pathname.replace(/\\.md$/, '') }\n  }\n\n  const accept = req.headers.get('accept') || ''\n  if (accept.includes('text/markdown')) {\n    return { reason: 'accept-header', strippedPath: pathname }\n  }\n\n  return null\n}\n\nexport interface MarkdownHeadersInput {\n  /**\n   * If provided, rendered as `x-markdown-tokens` so agents can budget context\n   * before parsing the body. Typically `Math.ceil(body.length / 4)`.\n   */\n  tokens?: number\n  /**\n   * Content-Signal directive (see contentsignals.org). Defaults to\n   * `'search=yes, ai-input=yes, ai-train=no'` — change if you want to permit\n   * training or restrict indexing.\n   */\n  contentSignal?: string\n}\n\n/**\n * Build the set of response headers to attach to a Markdown response. Safe\n * defaults: UTF-8 text/markdown, Vary: accept, and a Content-Signal directive\n * that permits search + agent input but denies training.\n */\nexport function markdownHeaders(input: MarkdownHeadersInput = {}): Record<string, string> {\n  const headers: Record<string, string> = {\n    'Content-Type': 'text/markdown; charset=utf-8',\n    'Content-Signal': input.contentSignal ?? 'search=yes, ai-input=yes, ai-train=no',\n    Vary: 'accept'\n  }\n  if (typeof input.tokens === 'number' && input.tokens > 0) {\n    headers['x-markdown-tokens'] = Math.max(1, Math.ceil(input.tokens)).toString()\n  }\n  return headers\n}\n\nexport interface SynthesizePointerInput {\n  origin: string\n  pathname: string\n  /** URL of the site's curated index, usually `/llms.txt`. */\n  llmsTxtUrl?: string\n  /** URL of the full enumerated index, usually `/llms-full.txt`. */\n  llmsFullTxtUrl?: string\n  /** URL of the machine-readable path manifest, usually `/md/index.json`. */\n  markdownIndexUrl?: string\n  /** Site name to title the pointer document. Defaults to the origin hostname. */\n  siteName?: string\n}\n\n/**\n * Generate a minimal pointer Markdown document for URLs that don't have a\n * pre-built mirror. Keeps the `Accept: text/markdown` contract intact\n * site-wide — agents always get *something* parseable, not a 404.\n */\nexport function synthesizeMarkdownPointer(input: SynthesizePointerInput): string {\n  const site =\n    input.siteName ??\n    (() => {\n      try {\n        return new URL(input.origin).hostname\n      } catch {\n        return input.origin\n      }\n    })()\n  const url = `${input.origin}${input.pathname}`\n  const lines: string[] = [`# ${site}`, '', `This page (${url}) does not have a dedicated Markdown mirror yet.`, '']\n  const links: string[] = []\n  if (input.llmsTxtUrl) links.push(`- [${input.llmsTxtUrl}](${input.llmsTxtUrl}) — curated index of docs`)\n  if (input.llmsFullTxtUrl)\n    links.push(`- [${input.llmsFullTxtUrl}](${input.llmsFullTxtUrl}) — full enumerated index`)\n  if (input.markdownIndexUrl)\n    links.push(`- [${input.markdownIndexUrl}](${input.markdownIndexUrl}) — JSON index of all Markdown paths`)\n  if (links.length) {\n    lines.push('For machine-readable documentation, see:', '', ...links, '')\n  }\n  return lines.join('\\n')\n}\n"]}

package/dist/types-DOy0kk0t.d.cts

@@ -0,0 +1,39 @@
+interface CaptureEvent {
+    event: string;
+    distinctId: string;
+    timestamp: string;
+    properties: Record<string, unknown>;
+}
+interface AnalyticsAdapter {
+    capture(event: CaptureEvent): Promise<void> | void;
+}
+interface TrackDocViewOptions {
+    analytics: AnalyticsAdapter;
+    /**
+     * Label describing how the request arrived (e.g. `'page-view'`, `'md-suffix'`,
+     * `'ua-rewrite'`). Emitted as a `source` property on the captured event so
+     * you can segment by channel.
+     */
+    source?: string;
+    /**
+     * Event name. Defaults to `'doc_view'`.
+     */
+    eventName?: string;
+    /**
+     * When `true` (default), skip capture unless the request UA matches the
+     * built-in AI bot pattern. Set to `false` to capture every request.
+     */
+    onlyBots?: boolean;
+    /**
+     * Extra properties merged into the captured event. Useful for tagging the
+     * site (`{ site: 'docs' }`) or any other dimension.
+     */
+    properties?: Record<string, unknown>;
+    /**
+     * Override the origin used for `$current_url`. Defaults to the request URL's
+     * origin.
+     */
+    origin?: string;
+}
+
+export type { AnalyticsAdapter as A, CaptureEvent as C, TrackDocViewOptions as T };

package/dist/types-DOy0kk0t.d.ts

@@ -0,0 +1,39 @@
+interface CaptureEvent {
+    event: string;
+    distinctId: string;
+    timestamp: string;
+    properties: Record<string, unknown>;
+}
+interface AnalyticsAdapter {
+    capture(event: CaptureEvent): Promise<void> | void;
+}
+interface TrackDocViewOptions {
+    analytics: AnalyticsAdapter;
+    /**
+     * Label describing how the request arrived (e.g. `'page-view'`, `'md-suffix'`,
+     * `'ua-rewrite'`). Emitted as a `source` property on the captured event so
+     * you can segment by channel.
+     */
+    source?: string;
+    /**
+     * Event name. Defaults to `'doc_view'`.
+     */
+    eventName?: string;
+    /**
+     * When `true` (default), skip capture unless the request UA matches the
+     * built-in AI bot pattern. Set to `false` to capture every request.
+     */
+    onlyBots?: boolean;
+    /**
+     * Extra properties merged into the captured event. Useful for tagging the
+     * site (`{ site: 'docs' }`) or any other dimension.
+     */
+    properties?: Record<string, unknown>;
+    /**
+     * Override the origin used for `$current_url`. Defaults to the request URL's
+     * origin.
+     */
+    origin?: string;
+}
+
+export type { AnalyticsAdapter as A, CaptureEvent as C, TrackDocViewOptions as T };

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@apideck/agent-analytics",
+  "version": "0.1.0",
+  "description": "Track AI agent and bot traffic to your Next.js / Vercel app — PostHog, webhooks, or any custom analytics backend. Detects Claude, ChatGPT, Perplexity, Google-Extended, and more.",
+  "keywords": [
+    "ai",
+    "agents",
+    "analytics",
+    "bot-detection",
+    "claude",
+    "chatgpt",
+    "perplexity",
+    "llm",
+    "posthog",
+    "nextjs",
+    "vercel",
+    "middleware"
+  ],
+  "homepage": "https://github.com/apideck-libraries/agent-analytics#readme",
+  "bugs": {
+    "url": "https://github.com/apideck-libraries/agent-analytics/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apideck-libraries/agent-analytics.git"
+  },
+  "license": "MIT",
+  "author": "Apideck",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js",
+      "require": "./dist/markdown.cjs"
+    },
+    "./posthog": {
+      "types": "./dist/adapters/posthog.d.ts",
+      "import": "./dist/adapters/posthog.js",
+      "require": "./dist/adapters/posthog.cjs"
+    },
+    "./webhook": {
+      "types": "./dist/adapters/webhook.d.ts",
+      "import": "./dist/adapters/webhook.js",
+      "require": "./dist/adapters/webhook.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}