@agentstats/sdk 0.5.0 → 0.5.1

package/dist/bots.d.cts

@@ -0,0 +1,265 @@
+/**
+ * `@agentstats/sdk/bots`: the bot catalogue behind `detectBot()`, for code that classifies user agents
+ * itself (log pipelines, dashboards): the same patterns, products and categories the server SDK uses.
+ * CURATED is the hand-checked list, matched first; CATCH_ALL the generic patterns ("bot", "crawler"…)
+ * that send unknown bots on to be classified.
+ */
+export type BotCategory = 'training' | 'search' | 'assistant' | 'agent' | 'search_engine' | 'other';
+/** Categories that count as "AI traffic". Search engines and other bots are shown separately. */
+export declare const AI_CATEGORIES: BotCategory[];
+export declare const isAiCategory: (c: string) => boolean;
+export interface BotProduct {
+  name: string;
+  operator: string;
+}
+/** Products group several bots from one vendor ("ChatGPT" = GPTBot + OAI-SearchBot + ChatGPT-User + ChatGPT agent). */
+export declare const BOT_PRODUCTS: {
+  chatgpt: {
+    name: string;
+    operator: string;
+  };
+  claude: {
+    name: string;
+    operator: string;
+  };
+  perplexity: {
+    name: string;
+    operator: string;
+  };
+  gemini: {
+    name: string;
+    operator: string;
+  };
+  copilot: {
+    name: string;
+    operator: string;
+  };
+  meta: {
+    name: string;
+    operator: string;
+  };
+  apple: {
+    name: string;
+    operator: string;
+  };
+  amazon: {
+    name: string;
+    operator: string;
+  };
+  mistral: {
+    name: string;
+    operator: string;
+  };
+  deepseek: {
+    name: string;
+    operator: string;
+  };
+  bytedance: {
+    name: string;
+    operator: string;
+  };
+  xai: {
+    name: string;
+    operator: string;
+  };
+  duckduckgo: {
+    name: string;
+    operator: string;
+  };
+  commoncrawl: {
+    name: string;
+    operator: string;
+  };
+  cohere: {
+    name: string;
+    operator: string;
+  };
+  you: {
+    name: string;
+    operator: string;
+  };
+  qwen: {
+    name: string;
+    operator: string;
+  };
+  kimi: {
+    name: string;
+    operator: string;
+  };
+  baidu: {
+    name: string;
+    operator: string;
+  };
+  yandex: {
+    name: string;
+    operator: string;
+  };
+  huawei: {
+    name: string;
+    operator: string;
+  };
+  ai2: {
+    name: string;
+    operator: string;
+  };
+  brave: {
+    name: string;
+    operator: string;
+  };
+  kagi: {
+    name: string;
+    operator: string;
+  };
+  phind: {
+    name: string;
+    operator: string;
+  };
+  poe: {
+    name: string;
+    operator: string;
+  };
+  manus: {
+    name: string;
+    operator: string;
+  };
+  ai: {
+    name: string;
+    operator: string;
+  };
+  coding: {
+    name: string;
+    operator: string;
+  };
+  aidata: {
+    name: string;
+    operator: string;
+  };
+  google: {
+    name: string;
+    operator: string;
+  };
+  searchengines: {
+    name: string;
+    operator: string;
+  };
+  automation: {
+    name: string;
+    operator: string;
+  };
+  seo: {
+    name: string;
+    operator: string;
+  };
+  social: {
+    name: string;
+    operator: string;
+  };
+  monitor: {
+    name: string;
+    operator: string;
+  };
+  feeds: {
+    name: string;
+    operator: string;
+  };
+  security: {
+    name: string;
+    operator: string;
+  };
+  archive: {
+    name: string;
+    operator: string;
+  };
+  research: {
+    name: string;
+    operator: string;
+  };
+  ads: {
+    name: string;
+    operator: string;
+  };
+  tools: {
+    name: string;
+    operator: string;
+  };
+  other: {
+    name: string;
+    operator: string;
+  };
+};
+export type BotProductId = keyof typeof BOT_PRODUCTS;
+export interface BotPattern {
+  id: string;
+  name: string;
+  product: BotProductId;
+  category: BotCategory;
+  /** Matched against the User-Agent header. `null` = only identified another way (signature). */
+  pattern: RegExp | null;
+  /** Who runs it, when its product groups several vendors ("Other AI bots"). Else the product's operator. */
+  operator?: string;
+}
+/** Every bot this SDK recognises, in the order they're tried: the first match wins, catch-alls last. */
+export declare const BOT_PATTERNS: BotPattern[];
+/** The first bot in `list` whose pattern matches `ua` (trimmed, non-empty). Shared with the server's bigger catalogue. */
+export declare function firstMatch(list: BotPattern[], s: string): BotPattern | null;
+/** Identify a bot from its User-Agent. Returns null for (what looks like) a normal browser. */
+export declare function classifyUserAgent(ua: string | null | undefined): BotPattern | null;
+/** Hostnames of AI assistants that send people to websites, and the `utm_source` values they add. */
+export declare const AI_REFERRERS: {
+  product: BotProductId;
+  hosts: RegExp;
+  utm?: RegExp;
+}[];
+/**
+ * Which AI assistant sent a human to this page, from the Referer header and/or
+ * the landing URL's `utm_source`. Returns the product id, or null.
+ */
+export declare function classifyReferral(referrer: string | null | undefined, url: string | null | undefined): BotProductId | null;
+export interface BotDetection {
+  /** Any automated client: AI crawlers and agents, search engines, scripts, monitors, link previews. */
+  isBot: boolean;
+  /** An AI crawler, assistant fetch or agent (categories training, search, assistant, agent). */
+  isAI: boolean;
+  /** Stable id, e.g. `gptbot`, `claude-user`, `google-agent`. */
+  id: string | null;
+  /** Display name, e.g. `GPTBot`. */
+  name: string | null;
+  category: BotCategory | null;
+  /** Product it belongs to, e.g. `ChatGPT`. */
+  product: string | null;
+  /** Who runs it, e.g. `OpenAI`. */
+  operator: string | null;
+  /** Loads pages in a real browser, so it runs JavaScript and can call your WebMCP tools. */
+  browser: boolean;
+  /** Sent Web Bot Auth signature headers. Not checked here: the dashboard verifies the signature. */
+  signed: boolean;
+  /** For people (not bots): the AI assistant that sent them here, e.g. `ChatGPT`, from the Referer or utm_source. */
+  referral: string | null;
+}
+type HeaderSource = {
+  get: (name: string) => string | null;
+} | Record<string, string | string[] | undefined>;
+/** A fetch `Request`, a `Headers` object, a Node `IncomingMessage`, or anything with `headers` (and optionally `url`). */
+export type DetectInput = Request | Headers | {
+  headers: HeaderSource;
+  url?: string;
+} | null | undefined;
+/**
+ * What kind of client sent this request, from its User-Agent, Web Bot Auth headers and referrer.
+ * Synchronous and dependency-free, so it works in any server, middleware or edge function.
+ *
+ * It reports who the client *claims* to be. Anyone can send `User-Agent: GPTBot`, so don't
+ * use it to grant access; your dashboard verifies each hit against the vendor's IP ranges,
+ * reverse DNS and signatures.
+ *
+ *   detectBot(request)           // fetch Request (Next, SvelteKit, Astro, Hono, Workers…)
+ *   detectBot(await headers())   // Next.js server components
+ *   detectBot(req)               // Node / Express IncomingMessage
+ */
+export declare function detectBot(input: DetectInput): BotDetection;
+/** `detectBot` over a header getter (used by the server adapters). */
+export declare function detectFromHeaders(header: (name: string) => string | null | undefined, url: string | null): BotDetection;
+export declare const CURATED: BotPattern[];
+/** Matched last, after the generated lists: anything that still calls itself a bot, and no User-Agent at all. */
+export declare const CATCH_ALL: BotPattern[];
+export {};

package/dist/bots.d.ts

@@ -0,0 +1,265 @@
+/**
+ * `@agentstats/sdk/bots`: the bot catalogue behind `detectBot()`, for code that classifies user agents
+ * itself (log pipelines, dashboards): the same patterns, products and categories the server SDK uses.
+ * CURATED is the hand-checked list, matched first; CATCH_ALL the generic patterns ("bot", "crawler"…)
+ * that send unknown bots on to be classified.
+ */
+export type BotCategory = 'training' | 'search' | 'assistant' | 'agent' | 'search_engine' | 'other';
+/** Categories that count as "AI traffic". Search engines and other bots are shown separately. */
+export declare const AI_CATEGORIES: BotCategory[];
+export declare const isAiCategory: (c: string) => boolean;
+export interface BotProduct {
+  name: string;
+  operator: string;
+}
+/** Products group several bots from one vendor ("ChatGPT" = GPTBot + OAI-SearchBot + ChatGPT-User + ChatGPT agent). */
+export declare const BOT_PRODUCTS: {
+  chatgpt: {
+    name: string;
+    operator: string;
+  };
+  claude: {
+    name: string;
+    operator: string;
+  };
+  perplexity: {
+    name: string;
+    operator: string;
+  };
+  gemini: {
+    name: string;
+    operator: string;
+  };
+  copilot: {
+    name: string;
+    operator: string;
+  };
+  meta: {
+    name: string;
+    operator: string;
+  };
+  apple: {
+    name: string;
+    operator: string;
+  };
+  amazon: {
+    name: string;
+    operator: string;
+  };
+  mistral: {
+    name: string;
+    operator: string;
+  };
+  deepseek: {
+    name: string;
+    operator: string;
+  };
+  bytedance: {
+    name: string;
+    operator: string;
+  };
+  xai: {
+    name: string;
+    operator: string;
+  };
+  duckduckgo: {
+    name: string;
+    operator: string;
+  };
+  commoncrawl: {
+    name: string;
+    operator: string;
+  };
+  cohere: {
+    name: string;
+    operator: string;
+  };
+  you: {
+    name: string;
+    operator: string;
+  };
+  qwen: {
+    name: string;
+    operator: string;
+  };
+  kimi: {
+    name: string;
+    operator: string;
+  };
+  baidu: {
+    name: string;
+    operator: string;
+  };
+  yandex: {
+    name: string;
+    operator: string;
+  };
+  huawei: {
+    name: string;
+    operator: string;
+  };
+  ai2: {
+    name: string;
+    operator: string;
+  };
+  brave: {
+    name: string;
+    operator: string;
+  };
+  kagi: {
+    name: string;
+    operator: string;
+  };
+  phind: {
+    name: string;
+    operator: string;
+  };
+  poe: {
+    name: string;
+    operator: string;
+  };
+  manus: {
+    name: string;
+    operator: string;
+  };
+  ai: {
+    name: string;
+    operator: string;
+  };
+  coding: {
+    name: string;
+    operator: string;
+  };
+  aidata: {
+    name: string;
+    operator: string;
+  };
+  google: {
+    name: string;
+    operator: string;
+  };
+  searchengines: {
+    name: string;
+    operator: string;
+  };
+  automation: {
+    name: string;
+    operator: string;
+  };
+  seo: {
+    name: string;
+    operator: string;
+  };
+  social: {
+    name: string;
+    operator: string;
+  };
+  monitor: {
+    name: string;
+    operator: string;
+  };
+  feeds: {
+    name: string;
+    operator: string;
+  };
+  security: {
+    name: string;
+    operator: string;
+  };
+  archive: {
+    name: string;
+    operator: string;
+  };
+  research: {
+    name: string;
+    operator: string;
+  };
+  ads: {
+    name: string;
+    operator: string;
+  };
+  tools: {
+    name: string;
+    operator: string;
+  };
+  other: {
+    name: string;
+    operator: string;
+  };
+};
+export type BotProductId = keyof typeof BOT_PRODUCTS;
+export interface BotPattern {
+  id: string;
+  name: string;
+  product: BotProductId;
+  category: BotCategory;
+  /** Matched against the User-Agent header. `null` = only identified another way (signature). */
+  pattern: RegExp | null;
+  /** Who runs it, when its product groups several vendors ("Other AI bots"). Else the product's operator. */
+  operator?: string;
+}
+/** Every bot this SDK recognises, in the order they're tried: the first match wins, catch-alls last. */
+export declare const BOT_PATTERNS: BotPattern[];
+/** The first bot in `list` whose pattern matches `ua` (trimmed, non-empty). Shared with the server's bigger catalogue. */
+export declare function firstMatch(list: BotPattern[], s: string): BotPattern | null;
+/** Identify a bot from its User-Agent. Returns null for (what looks like) a normal browser. */
+export declare function classifyUserAgent(ua: string | null | undefined): BotPattern | null;
+/** Hostnames of AI assistants that send people to websites, and the `utm_source` values they add. */
+export declare const AI_REFERRERS: {
+  product: BotProductId;
+  hosts: RegExp;
+  utm?: RegExp;
+}[];
+/**
+ * Which AI assistant sent a human to this page, from the Referer header and/or
+ * the landing URL's `utm_source`. Returns the product id, or null.
+ */
+export declare function classifyReferral(referrer: string | null | undefined, url: string | null | undefined): BotProductId | null;
+export interface BotDetection {
+  /** Any automated client: AI crawlers and agents, search engines, scripts, monitors, link previews. */
+  isBot: boolean;
+  /** An AI crawler, assistant fetch or agent (categories training, search, assistant, agent). */
+  isAI: boolean;
+  /** Stable id, e.g. `gptbot`, `claude-user`, `google-agent`. */
+  id: string | null;
+  /** Display name, e.g. `GPTBot`. */
+  name: string | null;
+  category: BotCategory | null;
+  /** Product it belongs to, e.g. `ChatGPT`. */
+  product: string | null;
+  /** Who runs it, e.g. `OpenAI`. */
+  operator: string | null;
+  /** Loads pages in a real browser, so it runs JavaScript and can call your WebMCP tools. */
+  browser: boolean;
+  /** Sent Web Bot Auth signature headers. Not checked here: the dashboard verifies the signature. */
+  signed: boolean;
+  /** For people (not bots): the AI assistant that sent them here, e.g. `ChatGPT`, from the Referer or utm_source. */
+  referral: string | null;
+}
+type HeaderSource = {
+  get: (name: string) => string | null;
+} | Record<string, string | string[] | undefined>;
+/** A fetch `Request`, a `Headers` object, a Node `IncomingMessage`, or anything with `headers` (and optionally `url`). */
+export type DetectInput = Request | Headers | {
+  headers: HeaderSource;
+  url?: string;
+} | null | undefined;
+/**
+ * What kind of client sent this request, from its User-Agent, Web Bot Auth headers and referrer.
+ * Synchronous and dependency-free, so it works in any server, middleware or edge function.
+ *
+ * It reports who the client *claims* to be. Anyone can send `User-Agent: GPTBot`, so don't
+ * use it to grant access; your dashboard verifies each hit against the vendor's IP ranges,
+ * reverse DNS and signatures.
+ *
+ *   detectBot(request)           // fetch Request (Next, SvelteKit, Astro, Hono, Workers…)
+ *   detectBot(await headers())   // Next.js server components
+ *   detectBot(req)               // Node / Express IncomingMessage
+ */
+export declare function detectBot(input: DetectInput): BotDetection;
+/** `detectBot` over a header getter (used by the server adapters). */
+export declare function detectFromHeaders(header: (name: string) => string | null | undefined, url: string | null): BotDetection;
+export declare const CURATED: BotPattern[];
+/** Matched last, after the generated lists: anything that still calls itself a bot, and no User-Agent at all. */
+export declare const CATCH_ALL: BotPattern[];
+export {};