@agentstats/sdk 0.5.0 → 0.5.1

package/dist/server.d.cts

@@ -1,12 +1,35 @@
-//#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.
+ * AgentStats server integration — see which AI crawlers and agents visit your
+ * site (GPTBot, ClaudeBot, PerplexityBot, ChatGPT agent, Google-Agent, …),
+ * including the ones that never run JavaScript.
  *
- * Sources: vendor documentation (OpenAI, Anthropic, Perplexity, Google, Microsoft,
- * Apple, Common Crawl, DuckDuckGo, Mistral) and the ai-robots-txt community list,
- * checked September 2026.
+ * Runs on Node and on edge runtimes (no Node built-ins). What leaves your server:
+ *  - bot-like requests: method, URL, status, user agent, IP (used to verify the
+ *    bot against the vendor's published ranges, then discarded) and Web Bot Auth
+ *    signature headers;
+ *  - visits referred by an AI assistant (chatgpt.com, perplexity.ai, …): URL and
+ *    referrer host only;
+ *  - everything else: a per-day count of page views. Nothing about humans.
+ *
+ *   import { createAgentStats } from '@agentstats/sdk/server'
+ *   const lens = createAgentStats({ serverKey: process.env.AGENTSTATS_SERVER_KEY })
+ *   app.use(lens.express())                        // Express / Connect: res.locals.bot
+ *   export default defineNitroPlugin(lens.nitro()) // Nuxt / Nitro: event.context.bot
+ *   export const handle = lens.sveltekit()         // SvelteKit: event.locals.bot
+ *   export const onRequest = lens.astro()          // Astro: Astro.locals.bot
+ *   app.use(lens.hono())                           // Hono: c.get('bot')
+ *   lens.track(request, { waitUntil, response })   // Next.js proxy, Workers, Bun, Deno
+ *
+ * Every adapter also hands you `detectBot()`'s answer for the request, and `detectBot`
+ * works on its own (no key needed): `detectBot(request).isAI`.
+ *
+ * With an `apiKey` (an API's key, `al_api_…`), the same adapters also track your API: calls an
+ * AI agent made (a Web Bot Auth signature, an `X-AI-Agent` header, an agent's User-Agent, or a
+ * credential you name in `apiCaller`) with method, route pattern, status and duration, and a
+ * per-day count of every other call. Never bodies, query strings or credentials: the caller is
+ * sent as an HMAC of its credential, keyed with your API key.
+ *
+ *   const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY }) // API-only server
  */
 type BotCategory = 'training' | 'search' | 'assistant' | 'agent' | 'search_engine' | 'other';
 /** Categories that count as "AI traffic". Search engines and other bots are shown separately. */
@@ -126,6 +149,10 @@ export declare const BOT_PRODUCTS: {
     name: string;
     operator: string;
   };
+  ai: {
+    name: string;
+    operator: string;
+  };
   coding: {
     name: string;
     operator: string;
@@ -138,6 +165,10 @@ export declare const BOT_PRODUCTS: {
     name: string;
     operator: string;
   };
+  searchengines: {
+    name: string;
+    operator: string;
+  };
   automation: {
     name: string;
     operator: string;
@@ -154,6 +185,26 @@ export declare const BOT_PRODUCTS: {
     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;
@@ -171,11 +222,10 @@ interface BotPattern {
   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;
 }
-/**
- * Order matters: the first matching pattern wins, so specific tokens come
- * before the vendor's generic ones and the catch-all patterns come last.
- */
+/** Every bot this SDK recognises, in the order they're tried: the first match wins, catch-alls 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;
@@ -226,16 +276,14 @@ type DetectInput = Request | Headers | {
  *   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.1";
+export declare const SERVER_SDK_VERSION = "0.3.2";
 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. */
+  /** Hits endpoint. Defaults to `AGENTSTATS_ENDPOINT`, then `https://agentstats.io/api/ingest/hits`. */
   endpoint?: string;
   /**
    * Secret key of an API in your project (Project settings → APIs, `al_api_…`). Turns on API
@@ -380,6 +428,7 @@ export declare class AgentStatsServer {
   track(request: Request, init?: {
     status?: number | null;
     ip?: string | null;
+    remoteAddress?: string | null;
     response?: {
       headers: Headers;
     } | null;
@@ -411,9 +460,10 @@ export declare class AgentStatsServer {
   /** 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`.
+   * Nuxt / Nitro plugin: `export default defineNitroPlugin(lens.nitro())` in `server/plugins/agentstats.ts`
+   * (Nitro v3: `export default definePlugin(lens.nitro())`).
    * 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…).
+   * Works on every Nitro preset (Node, Vercel, Netlify, Cloudflare…), on Nitro v2 (h3 v1) and v3 (h3 v2).
    */
   nitro(): (nitroApp: {
     hooks: {
@@ -509,8 +559,16 @@ export interface H3EventLike {
   web?: {
     request?: Request;
   };
+  /** h3 v2 (Nitro v3): the request (srvx adds `ip`), its parsed URL and the response being prepared. */
+  req?: Request & {
+    ip?: string;
+  };
+  url?: URL;
+  res?: {
+    status?: number;
+    headers: Headers;
+  };
   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 };

package/dist/server.d.ts

@@ -1,12 +1,35 @@
-//#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.
+ * AgentStats server integration — see which AI crawlers and agents visit your
+ * site (GPTBot, ClaudeBot, PerplexityBot, ChatGPT agent, Google-Agent, …),
+ * including the ones that never run JavaScript.
  *
- * Sources: vendor documentation (OpenAI, Anthropic, Perplexity, Google, Microsoft,
- * Apple, Common Crawl, DuckDuckGo, Mistral) and the ai-robots-txt community list,
- * checked September 2026.
+ * Runs on Node and on edge runtimes (no Node built-ins). What leaves your server:
+ *  - bot-like requests: method, URL, status, user agent, IP (used to verify the
+ *    bot against the vendor's published ranges, then discarded) and Web Bot Auth
+ *    signature headers;
+ *  - visits referred by an AI assistant (chatgpt.com, perplexity.ai, …): URL and
+ *    referrer host only;
+ *  - everything else: a per-day count of page views. Nothing about humans.
+ *
+ *   import { createAgentStats } from '@agentstats/sdk/server'
+ *   const lens = createAgentStats({ serverKey: process.env.AGENTSTATS_SERVER_KEY })
+ *   app.use(lens.express())                        // Express / Connect: res.locals.bot
+ *   export default defineNitroPlugin(lens.nitro()) // Nuxt / Nitro: event.context.bot
+ *   export const handle = lens.sveltekit()         // SvelteKit: event.locals.bot
+ *   export const onRequest = lens.astro()          // Astro: Astro.locals.bot
+ *   app.use(lens.hono())                           // Hono: c.get('bot')
+ *   lens.track(request, { waitUntil, response })   // Next.js proxy, Workers, Bun, Deno
+ *
+ * Every adapter also hands you `detectBot()`'s answer for the request, and `detectBot`
+ * works on its own (no key needed): `detectBot(request).isAI`.
+ *
+ * With an `apiKey` (an API's key, `al_api_…`), the same adapters also track your API: calls an
+ * AI agent made (a Web Bot Auth signature, an `X-AI-Agent` header, an agent's User-Agent, or a
+ * credential you name in `apiCaller`) with method, route pattern, status and duration, and a
+ * per-day count of every other call. Never bodies, query strings or credentials: the caller is
+ * sent as an HMAC of its credential, keyed with your API key.
+ *
+ *   const lens = createAgentStats({ apiKey: process.env.AGENTSTATS_API_KEY }) // API-only server
  */
 type BotCategory = 'training' | 'search' | 'assistant' | 'agent' | 'search_engine' | 'other';
 /** Categories that count as "AI traffic". Search engines and other bots are shown separately. */
@@ -126,6 +149,10 @@ export declare const BOT_PRODUCTS: {
     name: string;
     operator: string;
   };
+  ai: {
+    name: string;
+    operator: string;
+  };
   coding: {
     name: string;
     operator: string;
@@ -138,6 +165,10 @@ export declare const BOT_PRODUCTS: {
     name: string;
     operator: string;
   };
+  searchengines: {
+    name: string;
+    operator: string;
+  };
   automation: {
     name: string;
     operator: string;
@@ -154,6 +185,26 @@ export declare const BOT_PRODUCTS: {
     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;
@@ -171,11 +222,10 @@ interface BotPattern {
   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;
 }
-/**
- * Order matters: the first matching pattern wins, so specific tokens come
- * before the vendor's generic ones and the catch-all patterns come last.
- */
+/** Every bot this SDK recognises, in the order they're tried: the first match wins, catch-alls 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;
@@ -226,16 +276,14 @@ type DetectInput = Request | Headers | {
  *   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.1";
+export declare const SERVER_SDK_VERSION = "0.3.2";
 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. */
+  /** Hits endpoint. Defaults to `AGENTSTATS_ENDPOINT`, then `https://agentstats.io/api/ingest/hits`. */
   endpoint?: string;
   /**
    * Secret key of an API in your project (Project settings → APIs, `al_api_…`). Turns on API
@@ -380,6 +428,7 @@ export declare class AgentStatsServer {
   track(request: Request, init?: {
     status?: number | null;
     ip?: string | null;
+    remoteAddress?: string | null;
     response?: {
       headers: Headers;
     } | null;
@@ -411,9 +460,10 @@ export declare class AgentStatsServer {
   /** 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`.
+   * Nuxt / Nitro plugin: `export default defineNitroPlugin(lens.nitro())` in `server/plugins/agentstats.ts`
+   * (Nitro v3: `export default definePlugin(lens.nitro())`).
    * 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…).
+   * Works on every Nitro preset (Node, Vercel, Netlify, Cloudflare…), on Nitro v2 (h3 v1) and v3 (h3 v2).
    */
   nitro(): (nitroApp: {
     hooks: {
@@ -509,8 +559,16 @@ export interface H3EventLike {
   web?: {
     request?: Request;
   };
+  /** h3 v2 (Nitro v3): the request (srvx adds `ip`), its parsed URL and the response being prepared. */
+  req?: Request & {
+    ip?: string;
+  };
+  url?: URL;
+  res?: {
+    status?: number;
+    headers: Headers;
+  };
   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 };