@apideck/agent-analytics 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -151,6 +151,588 @@ function classifyRequest(req) {
   return { ...base, kind, headless };
 }
 
+// src/bot-ranges.ts
+var BOT_RANGES_CAPTURED_AT = "2026-08-02T00:00:00Z";
+var BOT_IP_RANGES = {
+  ChatGPT: [
+    "104.208.184.192/28",
+    "104.208.184.208/28",
+    "104.210.139.192/28",
+    "104.210.139.224/28",
+    "104.210.140.128/28",
+    "128.85.198.32/28",
+    "13.65.138.112/28",
+    "13.65.138.96/28",
+    "13.67.72.16/28",
+    "13.70.107.160/28",
+    "13.71.2.208/28",
+    "13.76.115.224/28",
+    "13.76.115.240/28",
+    "13.76.116.80/28",
+    "13.76.32.208/28",
+    "13.83.167.128/28",
+    "13.83.237.176/28",
+    "132.196.82.48/28",
+    "132.196.86.0/24",
+    "134.149.233.80/28",
+    "135.116.136.160/28",
+    "135.13.64.240/28",
+    "135.220.73.208/28",
+    "135.220.73.240/28",
+    "135.234.64.0/24",
+    "135.237.131.208/28",
+    "135.237.133.48/28",
+    "137.135.191.176/28",
+    "138.91.30.48/28",
+    "138.91.46.96/28",
+    "145.132.1.32/28",
+    "145.132.136.96/28",
+    "145.133.0.176/28",
+    "158.158.5.32/28",
+    "168.63.252.240/28",
+    "172.162.248.64/28",
+    "172.170.1.80/28",
+    "172.170.225.0/28",
+    "172.170.241.80/28",
+    "172.170.8.208/28",
+    "172.171.4.176/28",
+    "172.175.152.224/28",
+    "172.178.140.144/28",
+    "172.178.141.112/28",
+    "172.178.141.128/28",
+    "172.182.193.224/28",
+    "172.182.193.80/28",
+    "172.182.194.144/28",
+    "172.182.194.32/28",
+    "172.182.195.48/28",
+    "172.182.202.0/25",
+    "172.182.204.0/24",
+    "172.182.207.0/25",
+    "172.182.209.208/28",
+    "172.182.211.192/28",
+    "172.182.213.192/28",
+    "172.182.214.0/24",
+    "172.182.215.0/24",
+    "172.182.224.0/28",
+    "172.183.143.224/28",
+    "172.183.222.128/28",
+    "172.192.112.208/28",
+    "172.192.88.192/28",
+    "172.192.97.32/28",
+    "172.197.160.192/28",
+    "172.197.161.208/28",
+    "172.197.170.80/28",
+    "172.197.203.16/28",
+    "172.199.137.80/28",
+    "172.202.102.112/28",
+    "172.203.190.128/28",
+    "172.204.27.16/28",
+    "172.204.28.224/28",
+    "172.204.96.32/28",
+    "172.204.96.48/28",
+    "172.204.96.80/28",
+    "172.205.189.192/28",
+    "172.207.1.32/28",
+    "172.208.128.32/28",
+    "172.208.128.48/28",
+    "172.212.159.64/28",
+    "172.212.172.160/28",
+    "172.213.21.16/28",
+    "172.215.215.32/28",
+    "172.215.218.96/28",
+    "191.233.1.112/28",
+    "191.233.1.128/28",
+    "191.233.194.32/28",
+    "191.233.196.112/28",
+    "191.233.199.160/28",
+    "191.233.2.0/28",
+    "191.235.66.16/28",
+    "191.235.99.80/28",
+    "191.237.249.64/28",
+    "191.239.245.16/28",
+    "20.102.212.144/28",
+    "20.113.211.112/28",
+    "20.113.225.112/28",
+    "20.125.112.224/28",
+    "20.125.144.144/28",
+    "20.125.66.80/28",
+    "20.14.99.96/28",
+    "20.161.75.208/28",
+    "20.168.18.32/28",
+    "20.168.7.192/28",
+    "20.168.7.240/28",
+    "20.169.6.224/28",
+    "20.169.7.48/28",
+    "20.169.72.112/28",
+    "20.169.73.176/28",
+    "20.169.73.32/28",
+    "20.169.73.64/28",
+    "20.169.77.0/25",
+    "20.169.78.112/28",
+    "20.169.78.128/28",
+    "20.169.78.144/28",
+    "20.169.78.160/28",
+    "20.169.78.176/28",
+    "20.169.78.192/28",
+    "20.169.78.208/28",
+    "20.169.78.48/28",
+    "20.169.78.64/28",
+    "20.169.78.80/28",
+    "20.169.78.96/28",
+    "20.169.86.224/28",
+    "20.169.86.240/28",
+    "20.169.87.112/28",
+    "20.17.108.96/28",
+    "20.170.184.16/28",
+    "20.170.184.32/28",
+    "20.170.184.48/28",
+    "20.170.184.64/28",
+    "20.170.184.80/28",
+    "20.171.123.64/28",
+    "20.171.206.0/24",
+    "20.171.207.0/24",
+    "20.171.53.224/28",
+    "20.172.29.32/28",
+    "20.193.233.240/28",
+    "20.193.50.32/28",
+    "20.194.0.208/28",
+    "20.194.1.0/28",
+    "20.198.67.96/28",
+    "20.199.211.160/28",
+    "20.199.242.0/28",
+    "20.200.212.240/28",
+    "20.204.24.240/28",
+    "20.210.154.128/28",
+    "20.210.174.208/28",
+    "20.210.211.192/28",
+    "20.215.187.208/28",
+    "20.215.188.192/28",
+    "20.215.214.16/28",
+    "20.215.219.128/28",
+    "20.215.219.160/28",
+    "20.215.219.208/28",
+    "20.215.220.112/28",
+    "20.215.220.128/28",
+    "20.215.220.144/28",
+    "20.215.220.160/28",
+    "20.215.220.176/28",
+    "20.215.220.192/28",
+    "20.215.220.208/28",
+    "20.215.220.64/28",
+    "20.215.220.80/28",
+    "20.215.220.96/28",
+    "20.218.30.240/28",
+    "20.219.71.192/28",
+    "20.222.36.192/28",
+    "20.226.32.80/28",
+    "20.227.140.32/28",
+    "20.228.106.176/28",
+    "20.235.75.208/28",
+    "20.235.87.224/28",
+    "20.249.63.208/28",
+    "20.25.151.224/28",
+    "20.250.136.64/28",
+    "20.250.136.80/28",
+    "20.250.6.128/28",
+    "20.27.94.128/28",
+    "20.42.10.176/28",
+    "20.45.178.144/28",
+    "20.48.120.208/28",
+    "20.52.125.160/28",
+    "20.55.129.0/28",
+    "20.55.229.144/28",
+    "20.57.199.192/28",
+    "20.63.180.96/28",
+    "20.63.221.64/28",
+    "20.79.59.112/28",
+    "20.81.183.64/28",
+    "20.83.243.176/28",
+    "20.97.189.96/28",
+    "23.102.140.144/28",
+    "23.102.141.32/28",
+    "23.98.142.176/28",
+    "23.98.179.16/28",
+    "23.98.186.176/28",
+    "23.98.186.192/28",
+    "23.98.186.64/28",
+    "23.98.186.96/28",
+    "4.151.119.48/28",
+    "4.151.241.240/28",
+    "4.151.71.176/28",
+    "4.189.118.208/28",
+    "4.189.119.48/28",
+    "4.196.118.112/28",
+    "4.197.115.112/28",
+    "4.197.19.176/28",
+    "4.197.22.112/28",
+    "4.197.64.0/28",
+    "4.197.64.16/28",
+    "4.197.64.48/28",
+    "4.197.64.64/28",
+    "4.198.72.16/28",
+    "4.198.96.112/28",
+    "4.201.232.64/28",
+    "4.201.232.80/28",
+    "4.203.96.80/28",
+    "4.205.128.176/28",
+    "4.218.24.64/28",
+    "4.226.200.16/28",
+    "4.226.226.32/28",
+    "4.227.36.0/25",
+    "40.116.73.208/28",
+    "40.122.235.112/28",
+    "40.67.175.0/25",
+    "40.67.183.160/28",
+    "40.67.183.176/28",
+    "40.78.161.48/28",
+    "40.81.134.128/28",
+    "40.81.134.144/28",
+    "40.81.234.144/28",
+    "40.81.67.96/28",
+    "40.84.181.32/28",
+    "40.84.221.208/28",
+    "40.84.221.224/28",
+    "40.90.214.16/28",
+    "48.193.44.32/28",
+    "48.221.184.112/28",
+    "48.221.184.80/28",
+    "48.221.184.96/28",
+    "48.221.40.176/28",
+    "51.107.70.192/28",
+    "51.116.2.80/28",
+    "51.116.221.96/28",
+    "51.56.40.80/28",
+    "51.57.0.96/28",
+    "51.59.24.64/28",
+    "51.59.24.80/28",
+    "51.59.40.80/28",
+    "51.59.40.96/28",
+    "51.59.48.80/28",
+    "51.59.48.96/28",
+    "51.8.102.0/24",
+    "51.8.155.112/28",
+    "51.8.155.48/28",
+    "51.8.155.64/28",
+    "51.8.187.224/28",
+    "52.148.129.32/28",
+    "52.153.130.64/28",
+    "52.154.22.48/28",
+    "52.156.77.144/28",
+    "52.159.227.32/28",
+    "52.159.249.96/28",
+    "52.161.49.224/28",
+    "52.161.49.96/28",
+    "52.165.212.16/28",
+    "52.165.212.32/28",
+    "52.165.212.48/28",
+    "52.172.129.160/28",
+    "52.172.251.112/28",
+    "52.173.219.112/28",
+    "52.173.219.96/28",
+    "52.173.221.16/28",
+    "52.173.221.176/28",
+    "52.173.221.208/28",
+    "52.173.234.16/28",
+    "52.173.234.80/28",
+    "52.173.235.80/28",
+    "52.183.217.240/28",
+    "52.187.246.128/28",
+    "52.190.137.144/28",
+    "52.190.137.16/28",
+    "52.190.139.48/28",
+    "52.190.142.64/28",
+    "52.190.190.16/28",
+    "52.225.75.208/28",
+    "52.230.152.0/24",
+    "52.230.163.32/28",
+    "52.230.164.176/28",
+    "52.231.30.48/28",
+    "52.231.34.176/28",
+    "52.231.39.144/28",
+    "52.231.39.192/28",
+    "52.231.49.48/28",
+    "52.231.50.64/28",
+    "52.236.94.144/28",
+    "52.241.146.208/28",
+    "52.242.132.224/28",
+    "52.242.132.240/28",
+    "52.242.245.208/28",
+    "52.252.113.240/28",
+    "52.255.109.112/28",
+    "52.255.109.128/28",
+    "52.255.109.144/28",
+    "52.255.109.80/28",
+    "52.255.109.96/28",
+    "52.255.111.0/28",
+    "52.255.111.112/28",
+    "52.255.111.32/28",
+    "52.255.111.48/28",
+    "52.255.111.80/28",
+    "57.154.174.112/28",
+    "57.154.175.0/28",
+    "57.154.187.32/28",
+    "68.154.28.96/28",
+    "68.218.30.112/28",
+    "68.220.57.64/28",
+    "68.221.67.192/28",
+    "68.221.67.224/28",
+    "68.221.67.240/28",
+    "70.153.139.208/28",
+    "70.153.189.192/28",
+    "70.153.190.16/28",
+    "70.153.76.16/28",
+    "70.153.87.224/28",
+    "70.156.144.64/28",
+    "70.156.152.80/28",
+    "70.156.152.96/28",
+    "74.161.200.96/28",
+    "74.224.217.64/28",
+    "74.226.253.160/28",
+    "74.249.86.176/28",
+    "74.7.175.128/25",
+    "74.7.227.0/25",
+    "74.7.227.128/25",
+    "74.7.228.0/25",
+    "74.7.228.128/25",
+    "74.7.229.0/25",
+    "74.7.229.128/25",
+    "74.7.230.0/25",
+    "74.7.241.0/25",
+    "74.7.241.128/25",
+    "74.7.242.0/25",
+    "74.7.242.128/25",
+    "74.7.243.0/25",
+    "74.7.243.128/25",
+    "74.7.244.0/25",
+    "74.7.35.112/28",
+    "74.7.35.48/28",
+    "74.7.36.64/28",
+    "74.7.36.80/28",
+    "74.7.36.96/28",
+    "85.211.241.128/28",
+    "9.129.0.0/17",
+    "9.160.128.16/28",
+    "9.160.128.32/28",
+    "9.160.128.64/28",
+    "9.160.163.128/28",
+    "9.160.164.128/28",
+    "9.160.34.144/28",
+    "9.160.36.16/28",
+    "9.160.96.16/28",
+    "9.163.101.48/28",
+    "9.205.25.128/28",
+    "9.205.8.48/28",
+    "9.223.181.208/28",
+    "9.234.96.192/28",
+    "9.234.97.128/28",
+    "9.234.97.96/28",
+    "9.235.40.32/28"
+  ],
+  Claude: [
+    "136.107.176.208/32",
+    "216.73.216.0/22",
+    "34.11.34.31/32",
+    "34.150.241.79/32",
+    "34.162.191.81/32",
+    "34.162.230.222/32",
+    "34.162.244.71/32",
+    "34.182.140.95/32",
+    "34.182.161.143/32",
+    "34.182.218.27/32",
+    "34.182.220.85/32",
+    "34.182.222.37/32",
+    "34.182.225.167/32",
+    "34.182.226.151/32",
+    "34.182.226.221/32",
+    "34.186.108.163/32",
+    "34.85.172.162/32",
+    "35.221.29.174/32",
+    "35.245.175.129/32",
+    "35.245.89.239/32"
+  ],
+  Perplexity: [
+    "107.20.236.150/32",
+    "18.210.92.235/32",
+    "18.97.1.228/30",
+    "18.97.9.96/29",
+    "3.211.124.183/32",
+    "3.222.232.239/32",
+    "3.224.62.45/32",
+    "3.231.139.107/32"
+  ],
+  Apple: [
+    "17.22.237.0/24",
+    "17.22.245.0/24",
+    "17.22.253.0/24",
+    "17.241.193.160/27",
+    "17.241.200.160/27",
+    "17.241.208.160/27",
+    "17.241.219.0/24",
+    "17.241.227.0/24",
+    "17.241.75.0/24",
+    "17.246.15.0/24",
+    "17.246.19.0/24",
+    "17.246.23.0/24"
+  ]
+};
+var VERIFIABLE_VENDORS = Object.keys(BOT_IP_RANGES);
+
+// src/cidr.ts
+function ipv4ToInt(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return null;
+  let out = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null;
+    if (part.length > 1 && part[0] === "0") return null;
+    const n = Number(part);
+    if (n > 255) return null;
+    out = out << 8 | n;
+  }
+  return out >>> 0;
+}
+function ipv6ToBigInt(ip) {
+  let text = ip;
+  const zone = text.indexOf("%");
+  if (zone !== -1) text = text.slice(0, zone);
+  if (!text || text.indexOf(":") === -1) return null;
+  let tail = null;
+  const lastColon = text.lastIndexOf(":");
+  const maybeV4 = text.slice(lastColon + 1);
+  if (maybeV4.indexOf(".") !== -1) {
+    tail = ipv4ToInt(maybeV4);
+    if (tail === null) return null;
+    text = text.slice(0, lastColon + 1) + "0:0";
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const rest = halves.length === 2 ? halves[1] ? halves[1].split(":") : [] : null;
+  let groups;
+  if (rest === null) {
+    groups = head;
+    if (groups.length !== 8) return null;
+  } else {
+    const fill = 8 - head.length - rest.length;
+    if (fill < 0) return null;
+    groups = [...head, ...Array(fill).fill("0"), ...rest];
+  }
+  let out = 0n;
+  for (const g of groups) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(g)) return null;
+    out = out << 16n | BigInt(parseInt(g, 16));
+  }
+  if (tail !== null) out = out >> 32n << 32n | BigInt(tail >>> 0);
+  return out;
+}
+function compileRanges(cidrs) {
+  const v4 = [];
+  const v6 = [];
+  for (const cidr of cidrs) {
+    const slash = cidr.lastIndexOf("/");
+    if (slash === -1) continue;
+    const addr = cidr.slice(0, slash);
+    const bits = Number(cidr.slice(slash + 1));
+    if (!Number.isInteger(bits) || bits < 0) continue;
+    if (addr.indexOf(":") !== -1) {
+      if (bits > 128) continue;
+      const net = ipv6ToBigInt(addr);
+      if (net === null) continue;
+      v6.push({ net: bits === 0 ? 0n : net >> BigInt(128 - bits) << BigInt(128 - bits), bits });
+    } else {
+      if (bits > 32) continue;
+      const net = ipv4ToInt(addr);
+      if (net === null) continue;
+      const mask = bits === 0 ? 0 : 4294967295 << 32 - bits >>> 0;
+      v4.push({ net: (net & mask) >>> 0, mask });
+    }
+  }
+  return { v4, v6 };
+}
+function ipInRanges(ip, ranges) {
+  if (!ip) return false;
+  const trimmed = ip.trim();
+  if (!trimmed) return false;
+  if (trimmed.indexOf(":") !== -1) {
+    const value2 = ipv6ToBigInt(trimmed);
+    if (value2 === null) return false;
+    const V4_MAPPED_PREFIX = 0xffffn << 32n;
+    if (value2 >> 32n === V4_MAPPED_PREFIX >> 32n) {
+      const low = Number(value2 & 0xffffffffn) >>> 0;
+      if (matchV4(low, ranges.v4)) return true;
+    }
+    for (const r of ranges.v6) {
+      if (r.bits === 0) return true;
+      if (value2 >> BigInt(128 - r.bits) << BigInt(128 - r.bits) === r.net) return true;
+    }
+    return false;
+  }
+  const value = ipv4ToInt(trimmed);
+  if (value === null) return false;
+  return matchV4(value, ranges.v4);
+}
+function matchV4(value, list) {
+  for (const r of list) {
+    if ((value & r.mask) >>> 0 === r.net) return true;
+  }
+  return false;
+}
+function ipInCidr(ip, cidr) {
+  return ipInRanges(ip, compileRanges([cidr]));
+}
+
+// src/verify.ts
+var CLIENT_SIDE_AGENT_PATTERN = /claude-code|perplexity-user|cursor|windsurf|cline|aider/i;
+var SERVER_SIDE_CRAWLER_PATTERN = /ClaudeBot|Claude-SearchBot|GPTBot|OAI-SearchBot|ChatGPT-User|PerplexityBot|Applebot/i;
+var COMPILED = {};
+for (const vendor of VERIFIABLE_VENDORS) {
+  COMPILED[vendor] = compileRanges(BOT_IP_RANGES[vendor] ?? []);
+}
+function verifiableVendors() {
+  return VERIFIABLE_VENDORS;
+}
+function verifyBotIdentity(userAgent, ip) {
+  const ua = userAgent ?? "";
+  const claimed = parseBotName(userAgent);
+  const ranges = COMPILED[claimed];
+  if (!ranges) {
+    const isKnownCrawler = claimed !== "Other" && claimed !== "Browser";
+    return {
+      verdict: isKnownCrawler ? "unverifiable" : "not-claimed",
+      ...isKnownCrawler ? { reason: "no-published-ranges" } : {},
+      claimed: isKnownCrawler ? claimed : null,
+      verified: null
+    };
+  }
+  if (CLIENT_SIDE_AGENT_PATTERN.test(ua) || !SERVER_SIDE_CRAWLER_PATTERN.test(ua)) {
+    return {
+      verdict: "unverifiable",
+      reason: "client-side-agent",
+      claimed,
+      verified: null
+    };
+  }
+  const trimmed = (ip ?? "").trim();
+  if (!trimmed) {
+    return { verdict: "unverifiable", reason: "no-client-ip", claimed, verified: null };
+  }
+  const inRange = ipInRanges(trimmed, ranges);
+  return {
+    verdict: inRange ? "verified" : "spoofed",
+    claimed,
+    verified: inRange
+  };
+}
+function clientIpFromRequest(req) {
+  const forwarded = req.headers.get("x-forwarded-for") || "";
+  const first = forwarded.split(",")[0]?.trim();
+  if (first) return first;
+  return (req.headers.get("cf-connecting-ip") || req.headers.get("x-real-ip") || "").trim();
+}
+function verifyRequest(req) {
+  return verifyBotIdentity(req.headers.get("user-agent"), clientIpFromRequest(req));
+}
+
 // src/hash.ts
 function hashId(input) {
   let h = 5381;
@@ -185,6 +767,7 @@ async function trackVisit(req, opts) {
   const country = opts.captureCountry ? req.headers.get("x-vercel-ip-country") || req.headers.get("cf-ipcountry") || req.headers.get("x-country-code") || null : null;
   const geo = opts.captureGeo ? extractGeo(req) : null;
   const classification = classifyRequest(req);
+  const verification = opts.verifyIdentity ? verifyBotIdentity(userAgent, ip) : null;
   const event = {
     event: opts.eventName ?? "agent_visit",
     distinctId: hashId(`${ip}:${userAgent}`),
@@ -204,6 +787,11 @@ async function trackVisit(req, opts) {
       coding_agent_hint: classification.codingAgentHint,
       headless_score: classification.headless?.score ?? 0,
       headless_likely: classification.headless?.likely ?? false,
+      ...verification ? {
+        bot_verified: verification.verified,
+        bot_verification: verification.verdict,
+        ...verification.reason ? { bot_verification_reason: verification.reason } : {}
+      } : {},
       referer,
       source: opts.source ?? null,
       ...opts.properties
@@ -286,18 +874,28 @@ function customAnalytics(capture) {
 }
 
 exports.AI_BOT_PATTERN = AI_BOT_PATTERN;
+exports.BOT_IP_RANGES = BOT_IP_RANGES;
+exports.BOT_RANGES_CAPTURED_AT = BOT_RANGES_CAPTURED_AT;
 exports.HTTP_CLIENT_PATTERN = HTTP_CLIENT_PATTERN;
+exports.VERIFIABLE_VENDORS = VERIFIABLE_VENDORS;
 exports.classifyAgent = classifyAgent;
 exports.classifyRequest = classifyRequest;
+exports.clientIpFromRequest = clientIpFromRequest;
+exports.compileRanges = compileRanges;
 exports.customAnalytics = customAnalytics;
 exports.detectHeadless = detectHeadless;
 exports.firstUserAgentProduct = firstUserAgentProduct;
 exports.hashId = hashId;
+exports.ipInCidr = ipInCidr;
+exports.ipInRanges = ipInRanges;
 exports.isAiBot = isAiBot;
 exports.isHttpClient = isHttpClient;
 exports.parseBotName = parseBotName;
 exports.posthogAnalytics = posthogAnalytics;
 exports.trackVisit = trackVisit;
+exports.verifiableVendors = verifiableVendors;
+exports.verifyBotIdentity = verifyBotIdentity;
+exports.verifyRequest = verifyRequest;
 exports.webhookAnalytics = webhookAnalytics;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map