@agentstats/sdk 0.0.0-stage → 0.4.0

package/dist/server.d.ts

@@ -0,0 +1,516 @@
+//#region src/bots.d.ts
+/**
+ * Known bots, AI crawlers and AI agents, recognised by their User-Agent. This is the
+ * table the AgentStats server classifies hits with, so what `detectBot()` says in your
+ * app is what your dashboard shows.
+ *
+ * Sources: vendor documentation (OpenAI, Anthropic, Perplexity, Google, Microsoft,
+ * Apple, Common Crawl, DuckDuckGo, Mistral) and the ai-robots-txt community list,
+ * checked September 2026.
+ */
+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;
+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;
+  };
+  coding: {
+    name: string;
+    operator: string;
+  };
+  aidata: {
+    name: string;
+    operator: string;
+  };
+  google: {
+    name: string;
+    operator: string;
+  };
+  automation: {
+    name: string;
+    operator: string;
+  };
+  seo: {
+    name: string;
+    operator: string;
+  };
+  social: {
+    name: string;
+    operator: string;
+  };
+  monitor: {
+    name: string;
+    operator: string;
+  };
+  tools: {
+    name: string;
+    operator: string;
+  };
+  other: {
+    name: string;
+    operator: string;
+  };
+};
+type BotProductId = keyof typeof BOT_PRODUCTS;
+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;
+}
+/**
+ * Order matters: the first matching pattern wins, so specific tokens come
+ * before the vendor's generic ones and the catch-all patterns come last.
+ */
+export declare const BOT_PATTERNS: BotPattern[];
+/** 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;
+/**
+ * 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;
+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`). */
+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;
+//#endregion
+//#region src/server.d.ts
+export declare const SERVER_SDK_VERSION = "0.3.0";
+export interface ServerOptions {
+  /**
+   * Secret server key from Site settings (`al_srv_…`). Never expose it to browsers.
+   * Without one, the adapters still detect bots but nothing is sent.
+   */
+  serverKey?: string | undefined;
+  /** Hits endpoint, e.g. `https://your-host/api/ingest/hits`. Defaults to `AGENTSTATS_ENDPOINT` or the build-time default. */
+  endpoint?: string;
+  /**
+   * Secret key of an API in your project (Project settings → APIs, `al_api_…`). Turns on API
+   * tracking for the requests `apiRoutes` matches. Works with or without `serverKey`.
+   */
+  apiKey?: string | undefined;
+  /** API ingest endpoint. Defaults to `endpoint` with `/hits` replaced by `/api`. */
+  apiEndpoint?: string;
+  /**
+   * Which requests are API calls. Default: every request when there's no `serverKey` (an
+   * API-only server), else paths under `/api` and `/v1`, `/v2`…
+   */
+  apiRoutes?: RegExp | ((path: string) => boolean);
+  /**
+   * Who made a call, so one agent's calls group into a session: the credential, or anything that
+   * identifies the caller (an API key id, an OAuth client and user). It's sent as an HMAC keyed
+   * with your API key, never as is. Return `{ id, agent }` to name the agent behind a credential
+   * you know, e.g. `{ id: clientId, agent: 'claude-ai' }` for your OAuth client for Claude.
+   * Default: the `Authorization`, `X-API-Key` or `API-Key` header. `false`: don't group by caller.
+   */
+  apiCaller?: false | ((header: (name: string) => string | null | undefined) => string | {
+    id: string;
+    agent?: string;
+  } | null | undefined);
+  /** Count human page views (a number per day, nothing else) so the dashboard can show AI share of traffic. Default true. */
+  countHumans?: boolean;
+  /**
+   * Set a short-lived `_al_v` cookie on responses to AI agents that browse with a real browser
+   * (ChatGPT agent, Google-Agent, headless browsers). The browser SDK reads it to link that visit
+   * to the WebMCP tool calls the agent makes. Never set for humans. Default true.
+   */
+  visitCookie?: boolean;
+  /**
+   * Express/Node only: read the client IP, protocol and host from proxy headers (CF-Connecting-IP,
+   * X-Real-IP, X-Forwarded-For, …). By default this is automatic: headers are trusted only when the
+   * connection comes from a private or loopback address, i.e. from your own proxy or load balancer.
+   * `true` always trusts them, `false` never does. The fetch adapter always reads platform headers.
+   */
+  trustProxy?: boolean;
+  /**
+   * Read the client IP from this header and nothing else, e.g. `cf-connecting-ip` behind Cloudflare.
+   * Only set it if your proxy or platform always overwrites that header, or clients can forge their IP.
+   * Without it, Vercel, Netlify, Fly and Cloudflare Workers are recognised and their header is used.
+   */
+  ipHeader?: string;
+  /** Skip requests whose path matches (health checks, internal APIs, …). */
+  ignore?: RegExp | ((path: string) => boolean);
+  /** Batch size / interval for long-running servers. Defaults 100 hits / 5000 ms. */
+  maxBatch?: number;
+  flushIntervalMs?: number;
+  debug?: boolean;
+  disabled?: boolean;
+  fetch?: typeof fetch;
+}
+export interface HitRecord {
+  ts: number;
+  method: string;
+  url: string;
+  status: number | null;
+  ua: string | null;
+  ip: string | null;
+  referrer: string | null;
+  headers?: Record<string, string>;
+  visit_id?: string;
+  /** Asked for Markdown (Accept: text/markdown, or a .md URL), and got it (the response's content type). */
+  accept_md?: boolean;
+  served_md?: boolean;
+}
+/** One API call by an agent, as sent to the API ingest. */
+export interface ApiRecord {
+  ts: number;
+  method: string;
+  /** Route pattern (`/v1/users/:id`): the framework's when known, else the path with values replaced. */
+  route: string;
+  status: number | null;
+  durationMs: number | null;
+  ua: string | null;
+  /** Only for signed requests and agent User-Agents, to verify them; discarded by the server. */
+  ip: string | null;
+  /** Only for signed requests, to verify the signature; discarded by the server. */
+  url: string | null;
+  headers: Record<string, string>;
+  agent: string | null;
+  run: string | null;
+  actor: string | null;
+  actorAgent: string | null;
+}
+type HeaderGetter = (name: string) => string | null | undefined;
+interface Decision {
+  /** `api`: a call by an agent; `api-other`: any other API call (only counted). */
+  kind: 'bot' | 'referral' | 'human' | 'api' | 'api-other' | 'ignore';
+  detection: BotDetection;
+  record?: HitRecord;
+  api?: ApiRecord;
+  /** The caller's credential (raw until the batch is sent, when it's replaced by its HMAC). */
+  caller?: string | null;
+  /** performance.now() when the request arrived, for the call's duration. */
+  started?: number;
+  visitId?: string;
+  /** Set-Cookie value to add to the response, if any. */
+  cookie?: string;
+}
+/** A path as a route pattern: values (ids, UUIDs, tokens, emails) replaced by `:id`. */
+export declare function routeFromPath(path: string): string;
+/** A framework route pattern as `/users/:id`: SvelteKit and Astro `[id]`/`[...rest]`, minus route groups. */
+export declare function normalizeRoutePattern(pattern: string): string;
+type WaitUntil = (p: Promise<unknown>) => void;
+/** Loopback, private (RFC 1918 / ULA), link-local and carrier-grade NAT addresses: never a crawler's real IP. */
+export declare function isPrivateIp(ip: string | null | undefined): boolean;
+export declare class AgentStatsServer {
+  readonly options: Required<Omit<ServerOptions, 'ignore' | 'fetch' | 'endpoint' | 'trustProxy' | 'ipHeader' | 'serverKey' | 'apiKey' | 'apiEndpoint' | 'apiRoutes' | 'apiCaller'>> & Pick<ServerOptions, 'ignore' | 'trustProxy' | 'ipHeader' | 'serverKey' | 'apiKey' | 'apiRoutes' | 'apiCaller'> & {
+    endpoint: string;
+    apiEndpoint: string;
+  };
+  private queue;
+  private humans;
+  private humanCount;
+  private apiQueue;
+  private apiOther;
+  private apiOtherCount;
+  private apiHmacKey;
+  /** HMACs of recent callers: an agent reuses its credential, so each is computed once. */
+  private apiHmacs;
+  /** Bot and AI traffic is sent (there's a serverKey). */
+  private readonly hitsOn;
+  /** API calls are tracked (there's an apiKey). */
+  private readonly apiOn;
+  private timer;
+  private lastFlush;
+  private inflight;
+  private _fetch;
+  constructor(opts: ServerOptions);
+  /** Express / Connect middleware: `app.use(lens.express())`. The detection is on `res.locals.bot`. */
+  express(): (req: NodeLikeRequest, res: NodeLikeResponse, next?: (err?: unknown) => void) => void;
+  /** Plain Node `http`. Call before the response is written. Returns what `detectBot` says about the request. */
+  node(req: NodeLikeRequest, res: NodeLikeResponse): BotDetection;
+  /**
+   * Fetch-API requests (Next.js proxy/middleware, Cloudflare Workers, Bun, Deno).
+   * Pass `response` to let AgentStats set the visit cookie on it, and `waitUntil` on serverless/edge
+   * so the hit is sent after the response. Returns what `detectBot` says about the request.
+   */
+  track(request: Request, init?: {
+    status?: number | null;
+    ip?: string | null;
+    response?: {
+      headers: Headers;
+    } | null;
+    waitUntil?: WaitUntil;
+    route?: string;
+  }): BotDetection;
+  /** Hono middleware: `app.use(lens.hono())`. The detection is on `c.get('bot')`. */
+  hono(): (c: {
+    req: {
+      raw: Request;
+      routePath?: string;
+      matchedRoutes?: {
+        path: string;
+        method: string;
+      }[];
+    };
+    res: Response;
+    env?: any;
+    set?(key: string, value: any): void;
+    executionCtx?: {
+      waitUntil: WaitUntil;
+    };
+  }, next: () => Promise<void>) => Promise<void>;
+  /** SvelteKit: `export const handle = lens.sveltekit()` in `src/hooks.server.ts` (or inside `sequence()`). The detection is on `event.locals.bot`. */
+  sveltekit(): <R extends Response>({ event, resolve }: {
+    event: SvelteKitEventLike;
+    resolve: (event: any) => R | Promise<R>;
+  }) => Promise<R>;
+  /** Astro: `export const onRequest = lens.astro()` in `src/middleware.ts` (or inside `sequence()`). The detection is on `Astro.locals.bot`. */
+  astro(): (context: AstroContextLike, next: () => Promise<Response>) => Promise<Response>;
+  /**
+   * Nuxt / Nitro plugin: `export default defineNitroPlugin(lens.nitro())` in `server/plugins/agentstats.ts`.
+   * The detection is on `event.context.bot` in server routes, and on `useRequestEvent()?.context.bot` in pages.
+   * Works on every Nitro preset (Node, Vercel, Netlify, Cloudflare…).
+   */
+  nitro(): (nitroApp: {
+    hooks: {
+      hook: (name: any, fn: (...args: any[]) => unknown) => unknown;
+    };
+  }) => void;
+  /**
+   * Wrap a `fetch(request, env, ctx)` handler (Cloudflare Workers, Bun.serve, Deno.serve), or a Next.js
+   * route handler. `route` names the handler's route pattern for API tracking, e.g. `/api/users/[id]`.
+   */
+  wrapFetch<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, opts?: {
+    route?: string;
+  }): (request: Request, ...rest: A) => Promise<Response>;
+  /** Send everything queued now. */
+  flush(): Promise<void>;
+  private flushHits;
+  private flushApi;
+  /** HMAC-SHA256 of a credential keyed with the API key (hex, 128 bits), or null without Web Crypto. */
+  private hmac;
+  private computeHmac;
+  /** Decide what a request is (synchronously, so the visit cookie can still be set). */
+  decide(method: string, url: string, header: HeaderGetter, ip: string | null): Decision;
+  private isApiPath;
+  /** An API call: by an agent (kept, with how we know) or not (only counted). */
+  private decideApi;
+  /** Note whether the response to a bot was Markdown, from its content type (when the adapter can see it). */
+  private setContentType;
+  /** Use the framework's route pattern for an API call when it fits the request's path. */
+  private setRoute;
+  /** Queue a decided request once its status is known. */
+  commit(d: Decision, status: number | null, waitUntil?: WaitUntil | undefined): void;
+  private fetchDecision;
+  private fetchFinish;
+  private h3Decision;
+  /** Client IP of a fetch-API request: the configured header, else the platform's, else the usual forwarding headers. */
+  private fetchIp;
+  /** Whether this request came through a proxy whose forwarding headers we should believe. */
+  private viaProxy;
+  private nodeUrl;
+  private nodeIp;
+  private log;
+}
+export interface NodeLikeRequest {
+  method?: string;
+  url?: string;
+  originalUrl?: string;
+  headers: Record<string, string | string[] | undefined>;
+  socket?: {
+    remoteAddress?: string;
+    encrypted?: boolean;
+  };
+  /** Express: the matched route and the mount path of its router. */
+  route?: {
+    path?: unknown;
+  };
+  baseUrl?: string;
+}
+export interface NodeLikeResponse {
+  statusCode?: number;
+  /** Express */
+  locals?: Record<string, unknown>;
+  headersSent?: boolean;
+  getHeader?: (name: string) => unknown;
+  setHeader?: (name: string, value: string | string[]) => unknown;
+  once?: (event: 'finish', cb: () => void) => unknown;
+}
+export interface SvelteKitEventLike {
+  request: Request;
+  locals: object;
+  platform?: unknown;
+  isSubRequest?: boolean;
+  getClientAddress: () => string;
+  route?: {
+    id: string | null;
+  };
+}
+export interface AstroContextLike {
+  request: Request;
+  locals: object;
+  clientAddress?: string;
+  isPrerendered?: boolean;
+  routePattern?: string;
+}
+export interface H3EventLike {
+  method?: string;
+  path?: string;
+  headers?: Headers;
+  context: Record<string | symbol, unknown>;
+  node?: {
+    req: NodeLikeRequest;
+    res: NodeLikeResponse;
+  };
+  web?: {
+    request?: Request;
+  };
+  waitUntil?: WaitUntil;
+}
+export declare function createAgentStats(options: ServerOptions): AgentStatsServer;
+//#endregion
+export { type BotCategory, type BotDetection, type BotPattern, type BotProduct, type BotProductId, type DetectInput, createAgentStats as default };