@knownagents/sdk 1.9.0 → 1.11.0

package/README.md

@@ -68,6 +68,33 @@ app.get("/", (req, res) => {
 app.listen(3000, () => console.log("Server running on port 3000"))
 ```
 
+### Batch Requests If Possible
+
+For high-traffic websites, batch multiple visits together and send them periodically (e.g. every 30 seconds) using `trackVisits`:
+
+```ts
+import { VisitRequest } from "@knownagents/sdk"
+
+const visits: VisitRequest[] = []
+
+// Collect visits
+visits.push({
+    request_path: req.url,
+    request_method: req.method,
+    request_headers: req.headers,
+    response_status_code: res.statusCode,
+    response_duration_in_milliseconds: duration,
+    created: new Date().toISOString()
+})
+
+// Send batch periodically
+setInterval(() => {
+    if (visits.length > 0) {
+        knownAgents.trackVisits(visits.splice(0))
+    }
+}, 30000)
+```
+
 ### Test Your Integration
 
 - Open your project's settings page
@@ -95,25 +122,45 @@ const robotsTxt = await knownAgents.generateRobotsTXT([
 
 The return value is a plain text robots.txt string. Generate a `robotsTxt` periodically (e.g. once per day), then cache and serve it from your website's `/robots.txt` endpoint.
 
-## How To Use Agent Verification ([Full Docs](https://knownagents.com/docs/verification))
+## How To Use Agent Identification ([Full Docs](https://knownagents.com/docs/identification))
 
-Use the `verifyAgent` function to [identify](https://knownagents.com/agents) and verify agents from network requests using Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This can be useful for implementing access policies based on verified agent identity.
+Use the `identifyAgent` and `identifyAgents` functions to [identify](https://knownagents.com/agents) and verify agents from network requests using Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This can be useful for implementing access policies based on verified agent identity or enriching your own datasets.
 
-Call `verifyAgent` with the incoming request.
+### Identify a Single Request
+
+Call `identifyAgent` with the incoming request.
 
 ```ts
-const verification = await knownAgents.verifyAgent(request)
+const identification = await knownAgents.identifyAgent(request)
 
-if (verification.result === "verified") {
+if (identification.result === "verified") {
     // Agent is legitimate
-} else if (verification.result === "verification_failed") {
+} else if (identification.result === "verification_failed") {
     // Agent is not legitimate
 }
 ```
 
-The function returns an object with the following fields:
+### Identify Multiple Requests
+
+Use `identifyAgents` to identify multiple requests at once:
+
+```ts
+const identifications = await knownAgents.identifyAgents([
+    {
+        id: "request-1",
+        request_headers: request1.headers
+    },
+    {
+        id: "request-2",
+        request_headers: request2.headers
+    }
+])
+```
+
+The functions return an object (or array of objects) with the following fields:
 
-- `result`: The verification result:
+- `id`: The identifier from the request (if provided)
+- `result`: The identification result:
   - `"verified"`: The agent is identified and verified
   - `"verification_failed"`: The agent was identified but could not be verified
   - `"unknown_agent"`: The agent is not in our database

package/dist/index.d.ts

@@ -1,31 +1,79 @@
 import { IncomingMessage, ServerResponse } from "http";
+/**
+ * A framework-agnostic HTTP request interface.
+ * Used as a convenience type for single-request methods.
+ */
 export interface Request {
-    /** The URL of the request, including the path and query string (e.g. "/about?foo=bar") */
+    /** The URL path and query string (e.g. "/about?foo=bar") */
     path: string;
-    /** The request's HTTP method (e.g. "GET", "POST") */
+    /** The HTTP method (e.g. "GET", "POST") */
     method: string;
-    /** The request's HTTP headers */
+    /** The HTTP request headers */
     headers: Record<string, string | string[] | undefined>;
 }
+/**
+ * A minimal HTTP response interface.
+ * Used as a convenience type for single-request methods.
+ */
 export interface Response {
-    /** The HTTP response status code */
+    /** The HTTP response status code (e.g. 200, 404) */
     statusCode: number;
+    /** The HTTP response headers */
+    headers?: Record<string, string | string[] | undefined>;
+}
+/**
+ * A visit tracking request for the Known Agents API.
+ * Used for batch visit tracking with `trackVisits()`.
+ */
+export interface VisitRequest {
+    /** The URL path of the request (e.g. "/about?foo=bar") */
+    request_path: string;
+    /** The HTTP method (e.g. "GET", "POST") */
+    request_method: string;
+    /** The HTTP request headers */
+    request_headers: Record<string, string | string[] | undefined>;
+    /** The HTTP response status code (e.g. 200, 404) */
+    response_status_code?: number;
+    /** The HTTP response headers */
+    response_headers?: Record<string, string | string[] | undefined>;
+    /** The response duration in milliseconds */
+    response_duration_in_milliseconds?: number;
+    /** The timestamp when the visit occurred (ISO 8601 format) */
+    created?: string;
+}
+/**
+ * An agent identification request for the Known Agents API.
+ * Used for batch agent identification with `identifyAgents()`.
+ */
+export interface IdentificationRequest {
+    /** An identifier that will be echoed back in the response to match requests with results */
+    id?: string;
+    /** The HTTP request headers */
+    request_headers: Record<string, string | string[] | undefined>;
 }
 /**
- * The result of an agent verification check.
+ * The result of an agent identification request.
  */
-export interface VerificationResult {
-    /** The verification result */
+export interface IdentificationResult {
+    /** The identifier from the request (if provided) */
+    id?: string;
+    /**
+     * The identification result:
+     * - "verified": The agent was identified and verified
+     * - "verification_failed": The agent was identified but failed verification (spoofed)
+     * - "unknown_agent": The request is from an unrecognized agent or human
+     * - "not_verifiable": The agent was identified but cannot be verified
+     */
     result: "verified" | "verification_failed" | "unknown_agent" | "not_verifiable";
-    /** The unique ID of the agent (if identified) */
+    /** The unique ID of the identified agent */
     agent_id?: string;
-    /** The name of the agent (e.g. "Googlebot") (if identified) */
+    /** The name of the identified agent (e.g. "Googlebot") */
     agent_token?: string;
-    /** The documentation URL of the agent (if identified) */
+    /** The documentation URL for the identified agent */
     agent_url?: string;
-    /** The type of agent (e.g. "AI Agent") (if identified) */
+    /** The type of the identified agent (e.g. "AI Agent", "Search Engine Crawler") */
     agent_type_name?: string;
-    /** The company behind the agent (e.g. "Google") (if identified) */
+    /** The company behind the identified agent (e.g. "Google") */
     operator_name?: string;
 }
 /**
@@ -34,6 +82,8 @@ export interface VerificationResult {
 export declare enum AgentType {
     AIAgent = "AI Agent",
     AIAssistant = "AI Assistant",
+    AICodingAgent = "AI Coding Agent",
+    AIDataProvider = "AI Data Provider",
     AIDataScraper = "AI Data Scraper",
     AISearchCrawler = "AI Search Crawler",
     Archiver = "Archiver",
@@ -56,31 +106,52 @@ export declare class KnownAgents {
      */
     constructor(accessToken: string);
     /**
-     * Tracks an agent visit in Known Agents agent analytics.
+     * Tracks a single agent visit for analytics.
+     * This method is non-blocking and handles errors internally.
      *
-     * @param request - The incoming request.
-     * @param response - The outgoing response (optional).
-     * @param responseDurationInMilliseconds - The response duration in milliseconds (optional).
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @param response - The outgoing HTTP response (optional).
+     * @param responseDurationInMilliseconds - The time taken to process the request in milliseconds (optional).
      */
     trackVisit(request: Request | IncomingMessage, response?: Response | ServerResponse, responseDurationInMilliseconds?: number): void;
     /**
-     * Generates a `robots.txt` file that disallows the specified agent types.
-     * Cache and serve this string at your website’s `/robots.txt` endpoint.
+     * Tracks multiple agent visits in a batch for analytics.
+     * This method is non-blocking and handles errors internally.
+     * Recommended for high-traffic websites - batch visits and send periodically (e.g. every 30 seconds).
      *
-     * @param agentTypes - A list of agent types to include.
-     * @param disallow - A path to disallow (default is "/" for all paths).
-     * @returns The generated `robots.txt` as a string.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param visits - An array of visit tracking requests.
+     */
+    trackVisits(visits: VisitRequest[]): void;
+    /**
+     * Generates a robots.txt file that disallows the specified agent types.
+     * The generated file stays up-to-date with all current and future agents in the specified categories.
+     * Cache and serve the result at your website's `/robots.txt` endpoint.
+     *
+     * @param agentTypes - An array of agent types to disallow.
+     * @param disallow - The path to disallow (default: "/" for all paths).
+     * @returns A promise that resolves to the generated robots.txt content as a string.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
     generateRobotsTXT(agentTypes: AgentType[], disallow?: string): Promise<string>;
     /**
-     * Verifies if an agent request is legitimate by checking it against Known Agents.
+     * Identifies and verifies a single agent from an HTTP request.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @returns A promise that resolves to the identification result.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    identifyAgent(request: Request | IncomingMessage): Promise<IdentificationResult>;
+    /**
+     * Identifies and verifies multiple agents from HTTP requests in a batch.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
      *
-     * @param request - The incoming request.
-     * @returns A promise that resolves to the verification result.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param requests - An array of identification requests.
+     * @returns A promise that resolves to an array of identification results.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    verifyAgent(request: Request | IncomingMessage): Promise<VerificationResult>;
+    identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]>;
+    private isPathExcluded;
     private filterHeaders;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAItD,MAAM,WAAW,OAAO;IACpB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAA;IACZ,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;CACzD;AAED,MAAM,WAAW,QAAQ;IACrB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,8BAA8B;IAC9B,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,eAAe,GAAG,gBAAgB,CAAA;IAC/E,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,oBAAY,SAAS;IACjB,OAAO,aAAa;IACpB,WAAW,iBAAiB;IAC5B,aAAa,oBAAoB;IACjC,eAAe,sBAAsB;IACrC,QAAQ,aAAa;IACrB,eAAe,qBAAqB;IACpC,OAAO,YAAY;IACnB,aAAa,mBAAmB;IAChC,oBAAoB,0BAA0B;IAC9C,OAAO,YAAY;IACnB,UAAU,gBAAgB;IAC1B,mBAAmB,0BAA0B;IAC7C,eAAe,qBAAqB;IACpC,mBAAmB,0BAA0B;CAChD;AAED,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC;;;;OAIG;gBACS,WAAW,EAAE,MAAM;IAI/B;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,cAAc,EAAE,8BAA8B,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBnI;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBzF;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAuBlF,OAAO,CAAC,aAAa;CAcxB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KnownAgents = exports.AgentType = void 0;
-const NODE_PACKAGE_VERSION = "1.9.0";
+const http_1 = require("http");
 /**
  * Agent types that can be controlled with robots.txt rules.
  */
@@ -9,6 +9,8 @@ var AgentType;
 (function (AgentType) {
     AgentType["AIAgent"] = "AI Agent";
     AgentType["AIAssistant"] = "AI Assistant";
+    AgentType["AICodingAgent"] = "AI Coding Agent";
+    AgentType["AIDataProvider"] = "AI Data Provider";
     AgentType["AIDataScraper"] = "AI Data Scraper";
     AgentType["AISearchCrawler"] = "AI Search Crawler";
     AgentType["Archiver"] = "Archiver";
@@ -32,13 +34,19 @@ class KnownAgents {
         this.accessToken = accessToken;
     }
     /**
-     * Tracks an agent visit in Known Agents agent analytics.
+     * Tracks a single agent visit for analytics.
+     * This method is non-blocking and handles errors internally.
      *
-     * @param request - The incoming request.
-     * @param response - The outgoing response (optional).
-     * @param responseDurationInMilliseconds - The response duration in milliseconds (optional).
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @param response - The outgoing HTTP response (optional).
+     * @param responseDurationInMilliseconds - The time taken to process the request in milliseconds (optional).
      */
     trackVisit(request, response, responseDurationInMilliseconds) {
+        const path = "path" in request ? request.path : request.url;
+        const responseHeaders = response instanceof http_1.ServerResponse ? response.getHeaders() : response?.headers;
+        if (!path || this.isPathExcluded(path)) {
+            return;
+        }
         fetch("https://api.knownagents.com/visits", {
             method: "POST",
             headers: {
@@ -46,12 +54,12 @@ class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_path: "path" in request ? request.path : request.url,
+                request_path: path,
                 request_method: request.method,
                 request_headers: this.filterHeaders(request.headers),
                 response_status_code: response?.statusCode,
+                response_headers: responseHeaders ? this.filterHeaders(responseHeaders) : undefined,
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                node_package_version: NODE_PACKAGE_VERSION,
                 created: new Date().toISOString()
             })
         }).catch(error => {
@@ -59,13 +67,47 @@ class KnownAgents {
         });
     }
     /**
-     * Generates a `robots.txt` file that disallows the specified agent types.
-     * Cache and serve this string at your website’s `/robots.txt` endpoint.
+     * Tracks multiple agent visits in a batch for analytics.
+     * This method is non-blocking and handles errors internally.
+     * Recommended for high-traffic websites - batch visits and send periodically (e.g. every 30 seconds).
      *
-     * @param agentTypes - A list of agent types to include.
-     * @param disallow - A path to disallow (default is "/" for all paths).
-     * @returns The generated `robots.txt` as a string.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param visits - An array of visit tracking requests.
+     */
+    trackVisits(visits) {
+        const filteredVisits = visits
+            .filter((visit) => {
+            return !this.isPathExcluded(visit.request_path);
+        })
+            .map((visit) => {
+            return {
+                ...visit,
+                request_headers: this.filterHeaders(visit.request_headers),
+                response_headers: visit.response_headers ? this.filterHeaders(visit.response_headers) : undefined,
+            };
+        });
+        if (filteredVisits.length === 0) {
+            return;
+        }
+        fetch("https://api.knownagents.com/visits", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(filteredVisits)
+        }).catch(error => {
+            console.error(`Known Agents failed to track visits: ${error.message}`);
+        });
+    }
+    /**
+     * Generates a robots.txt file that disallows the specified agent types.
+     * The generated file stays up-to-date with all current and future agents in the specified categories.
+     * Cache and serve the result at your website's `/robots.txt` endpoint.
+     *
+     * @param agentTypes - An array of agent types to disallow.
+     * @param disallow - The path to disallow (default: "/" for all paths).
+     * @returns A promise that resolves to the generated robots.txt content as a string.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
     async generateRobotsTXT(agentTypes, disallow = "/") {
         const response = await fetch("https://api.knownagents.com/robots-txts", {
@@ -76,8 +118,7 @@ class KnownAgents {
             },
             body: JSON.stringify({
                 agent_types: agentTypes,
-                disallow: disallow,
-                node_package_version: NODE_PACKAGE_VERSION
+                disallow: disallow
             })
         });
         if (response.ok) {
@@ -88,33 +129,117 @@ class KnownAgents {
         }
     }
     /**
-     * Verifies if an agent request is legitimate by checking it against Known Agents.
+     * Identifies and verifies a single agent from an HTTP request.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
      *
-     * @param request - The incoming request.
-     * @returns A promise that resolves to the verification result.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @returns A promise that resolves to the identification result.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    async verifyAgent(request) {
-        const response = await fetch("https://api.knownagents.com/agent-verifications", {
+    async identifyAgent(request) {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
             method: "POST",
             headers: {
                 "Authorization": `Bearer ${this.accessToken}`,
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_path: "path" in request ? request.path : request.url,
-                request_headers: this.filterHeaders(request.headers),
-                node_package_version: NODE_PACKAGE_VERSION
+                request_headers: this.filterHeaders(request.headers)
             })
         });
         if (response.ok) {
             return await response.json();
         }
         else {
-            throw new Error(`Known Agents failed to verify agent: ${response.status} ${response.statusText}`);
+            throw new Error(`Known Agents failed to identify agent: ${response.status} ${response.statusText}`);
+        }
+    }
+    /**
+     * Identifies and verifies multiple agents from HTTP requests in a batch.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param requests - An array of identification requests.
+     * @returns A promise that resolves to an array of identification results.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgents(requests) {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(requests.map(request => {
+                return {
+                    ...request,
+                    request_headers: this.filterHeaders(request.request_headers),
+                };
+            }))
+        });
+        if (response.ok) {
+            return await response.json();
+        }
+        else {
+            throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`);
         }
     }
     // Helpers
+    isPathExcluded(path) {
+        const excludedPrefixes = [
+            "/_next/",
+            "/_nuxt/",
+            "/_astro/",
+            "/_app/",
+            "/@vite/",
+            "/@fs/",
+            "/@id/",
+            "/node_modules/",
+            "/_vercel/",
+        ];
+        const excludedSuffixes = [
+            ".ico",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".webp",
+            ".svg",
+            ".bmp",
+            ".tiff",
+            ".avif",
+            ".css",
+            ".js",
+            ".mjs",
+            ".ts",
+            ".jsx",
+            ".tsx",
+            ".map",
+            ".woff",
+            ".woff2",
+            ".ttf",
+            ".otf",
+            ".eot",
+            ".mp3",
+            ".mp4",
+            ".webm",
+            ".wav",
+            ".ogg",
+            ".mov",
+            ".avi",
+            ".flv",
+            ".m4v",
+            ".rss",
+            ".json",
+            ".xml",
+            ".pdf",
+            ".zip",
+        ];
+        return excludedPrefixes.some((excludedPrefix) => {
+            return path.toLowerCase().startsWith(excludedPrefix.toLowerCase());
+        }) || excludedSuffixes.some((excludedSuffix) => {
+            return path.toLowerCase().endsWith(excludedSuffix.toLowerCase());
+        });
+    }
     filterHeaders(headers) {
         const excludedHeaders = new Set([
             "authorization",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knownagents/sdk",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt, agent verification",
   "publishConfig": {
     "access": "public"
@@ -52,7 +52,7 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/node": "^22.19.17",
     "typescript": "^5.8.2"
   }
 }

package/src/index.ts

@@ -1,36 +1,84 @@
 import { IncomingMessage, ServerResponse } from "http"
 
-const NODE_PACKAGE_VERSION = "1.9.0"
-
+/**
+ * A framework-agnostic HTTP request interface.
+ * Used as a convenience type for single-request methods.
+ */
 export interface Request {
-    /** The URL of the request, including the path and query string (e.g. "/about?foo=bar") */
+    /** The URL path and query string (e.g. "/about?foo=bar") */
     path: string
-    /** The request's HTTP method (e.g. "GET", "POST") */
+    /** The HTTP method (e.g. "GET", "POST") */
     method: string
-    /** The request's HTTP headers */
+    /** The HTTP request headers */
     headers: Record<string, string | string[] | undefined>
 }
 
+/**
+ * A minimal HTTP response interface.
+ * Used as a convenience type for single-request methods.
+ */
 export interface Response {
-    /** The HTTP response status code */
+    /** The HTTP response status code (e.g. 200, 404) */
     statusCode: number
+    /** The HTTP response headers */
+    headers?: Record<string, string | string[] | undefined>
 }
 
 /**
- * The result of an agent verification check.
+ * A visit tracking request for the Known Agents API.
+ * Used for batch visit tracking with `trackVisits()`.
  */
-export interface VerificationResult {
-    /** The verification result */
+export interface VisitRequest {
+    /** The URL path of the request (e.g. "/about?foo=bar") */
+    request_path: string
+    /** The HTTP method (e.g. "GET", "POST") */
+    request_method: string
+    /** The HTTP request headers */
+    request_headers: Record<string, string | string[] | undefined>
+    /** The HTTP response status code (e.g. 200, 404) */
+    response_status_code?: number
+    /** The HTTP response headers */
+    response_headers?: Record<string, string | string[] | undefined>
+    /** The response duration in milliseconds */
+    response_duration_in_milliseconds?: number
+    /** The timestamp when the visit occurred (ISO 8601 format) */
+    created?: string
+}
+
+/**
+ * An agent identification request for the Known Agents API.
+ * Used for batch agent identification with `identifyAgents()`.
+ */
+export interface IdentificationRequest {
+    /** An identifier that will be echoed back in the response to match requests with results */
+    id?: string
+    /** The HTTP request headers */
+    request_headers: Record<string, string | string[] | undefined>
+}
+
+/**
+ * The result of an agent identification request.
+ */
+export interface IdentificationResult {
+    /** The identifier from the request (if provided) */
+    id?: string
+    /** 
+     * The identification result:
+     * - "verified": The agent was identified and verified
+     * - "verification_failed": The agent was identified but failed verification (spoofed)
+     * - "unknown_agent": The request is from an unrecognized agent or human
+     * - "not_verifiable": The agent was identified but cannot be verified
+     */
     result: "verified" | "verification_failed" | "unknown_agent" | "not_verifiable"
-    /** The unique ID of the agent (if identified) */
+    /** The unique ID of the identified agent */
     agent_id?: string
-    /** The name of the agent (e.g. "Googlebot") (if identified) */
+    /** The name of the identified agent (e.g. "Googlebot") */
     agent_token?: string
-    /** The documentation URL of the agent (if identified) */
+    /** The documentation URL for the identified agent */
     agent_url?: string
-    /** The type of agent (e.g. "AI Agent") (if identified) */
+    /** The type of the identified agent (e.g. "AI Agent", "Search Engine Crawler") */
     agent_type_name?: string
-    /** The company behind the agent (e.g. "Google") (if identified) */
+    /** The company behind the identified agent (e.g. "Google") */
     operator_name?: string
 }
 
@@ -40,6 +88,8 @@ export interface VerificationResult {
 export enum AgentType {
     AIAgent = "AI Agent",
     AIAssistant = "AI Assistant",
+    AICodingAgent = "AI Coding Agent",
+    AIDataProvider = "AI Data Provider",
     AIDataScraper = "AI Data Scraper",
     AISearchCrawler = "AI Search Crawler",
     Archiver = "Archiver",
@@ -67,13 +117,21 @@ export class KnownAgents {
     }
 
     /**
-     * Tracks an agent visit in Known Agents agent analytics.
+     * Tracks a single agent visit for analytics.
+     * This method is non-blocking and handles errors internally.
      *
-     * @param request - The incoming request.
-     * @param response - The outgoing response (optional).
-     * @param responseDurationInMilliseconds - The response duration in milliseconds (optional).
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @param response - The outgoing HTTP response (optional).
+     * @param responseDurationInMilliseconds - The time taken to process the request in milliseconds (optional).
      */
     trackVisit(request: Request | IncomingMessage, response?: Response | ServerResponse, responseDurationInMilliseconds?: number): void {
+        const path = "path" in request ? request.path : request.url
+        const responseHeaders = response instanceof ServerResponse ? response.getHeaders() as Record<string, string | string[] | undefined> : response?.headers
+
+        if (!path || this.isPathExcluded(path)) {
+            return
+        }
+
         fetch("https://api.knownagents.com/visits", {
             method: "POST",
             headers: {
@@ -81,27 +139,64 @@ export class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_path: "path" in request ? request.path : request.url,
+                request_path: path,
                 request_method: request.method,
                 request_headers: this.filterHeaders(request.headers),
                 response_status_code: response?.statusCode,
+                response_headers: responseHeaders ? this.filterHeaders(responseHeaders) : undefined,
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                node_package_version: NODE_PACKAGE_VERSION,
                 created: new Date().toISOString()
             })
         }).catch(error => {
             console.error(`Known Agents failed to track visit: ${error.message}`)
         })
     }
+
+    /**
+     * Tracks multiple agent visits in a batch for analytics.
+     * This method is non-blocking and handles errors internally.
+     * Recommended for high-traffic websites - batch visits and send periodically (e.g. every 30 seconds).
+     *
+     * @param visits - An array of visit tracking requests.
+     */
+    trackVisits(visits: VisitRequest[]): void {
+        const filteredVisits = visits
+            .filter((visit) => {
+                return !this.isPathExcluded(visit.request_path)
+            })
+            .map((visit) => {
+                return {
+                    ...visit,
+                    request_headers: this.filterHeaders(visit.request_headers),
+                    response_headers: visit.response_headers ? this.filterHeaders(visit.response_headers) : undefined,
+                }
+            })
+
+        if (filteredVisits.length === 0) {
+            return
+        }
+
+        fetch("https://api.knownagents.com/visits", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(filteredVisits)
+        }).catch(error => {
+            console.error(`Known Agents failed to track visits: ${error.message}`)
+        })
+    }
     
     /**
-     * Generates a `robots.txt` file that disallows the specified agent types.
-     * Cache and serve this string at your website’s `/robots.txt` endpoint.
+     * Generates a robots.txt file that disallows the specified agent types.
+     * The generated file stays up-to-date with all current and future agents in the specified categories.
+     * Cache and serve the result at your website's `/robots.txt` endpoint.
      *
-     * @param agentTypes - A list of agent types to include.
-     * @param disallow - A path to disallow (default is "/" for all paths).
-     * @returns The generated `robots.txt` as a string.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param agentTypes - An array of agent types to disallow.
+     * @param disallow - The path to disallow (default: "/" for all paths).
+     * @returns A promise that resolves to the generated robots.txt content as a string.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
     async generateRobotsTXT(agentTypes: AgentType[], disallow: string = "/"): Promise<string> {
         const response = await fetch("https://api.knownagents.com/robots-txts", {
@@ -112,8 +207,7 @@ export class KnownAgents {
             },
             body: JSON.stringify({
                 agent_types: agentTypes,
-                disallow: disallow,
-                node_package_version: NODE_PACKAGE_VERSION
+                disallow: disallow
             })
         })
 
@@ -125,35 +219,123 @@ export class KnownAgents {
     }
     
     /**
-     * Verifies if an agent request is legitimate by checking it against Known Agents.
+     * Identifies and verifies a single agent from an HTTP request.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
      *
-     * @param request - The incoming request.
-     * @returns A promise that resolves to the verification result.
-     * @throws If the API call fails or returns a non-200 status.
+     * @param request - The incoming HTTP request (Request or Node.js IncomingMessage).
+     * @returns A promise that resolves to the identification result.
+     * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    async verifyAgent(request: Request | IncomingMessage): Promise<VerificationResult> {
-        const response = await fetch("https://api.knownagents.com/agent-verifications", {
+    async identifyAgent(request: Request | IncomingMessage): Promise<IdentificationResult> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
             method: "POST",
             headers: {
                 "Authorization": `Bearer ${this.accessToken}`,
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_path: "path" in request ? request.path : request.url,
-                request_headers: this.filterHeaders(request.headers),
-                node_package_version: NODE_PACKAGE_VERSION
+                request_headers: this.filterHeaders(request.headers)
             })
         })
 
         if (response.ok) {
             return await response.json()
         } else {
-            throw new Error(`Known Agents failed to verify agent: ${response.status} ${response.statusText}`)
+            throw new Error(`Known Agents failed to identify agent: ${response.status} ${response.statusText}`)
+        }
+    }
+
+    /**
+     * Identifies and verifies multiple agents from HTTP requests in a batch.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param requests - An array of identification requests.
+     * @returns A promise that resolves to an array of identification results.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(requests.map(request => {
+                return {
+                    ...request,
+                    request_headers: this.filterHeaders(request.request_headers),
+                }
+            }))
+        })
+
+        if (response.ok) {
+            return await response.json()
+        } else {
+            throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`)
         }
     }
 
     // Helpers
 
+    private isPathExcluded(path: string): boolean {
+        const excludedPrefixes = [
+            "/_next/",
+            "/_nuxt/",
+            "/_astro/",
+            "/_app/",
+            "/@vite/",
+            "/@fs/",
+            "/@id/",
+            "/node_modules/",
+            "/_vercel/",
+        ]
+
+        const excludedSuffixes = [
+            ".ico",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".webp",
+            ".svg",
+            ".bmp",
+            ".tiff",
+            ".avif",
+            ".css",
+            ".js",
+            ".mjs",
+            ".ts",
+            ".jsx",
+            ".tsx",
+            ".map",
+            ".woff",
+            ".woff2",
+            ".ttf",
+            ".otf",
+            ".eot",
+            ".mp3",
+            ".mp4",
+            ".webm",
+            ".wav",
+            ".ogg",
+            ".mov",
+            ".avi",
+            ".flv",
+            ".m4v",
+            ".rss",
+            ".json",
+            ".xml",
+            ".pdf",
+            ".zip",
+        ]
+
+        return excludedPrefixes.some((excludedPrefix) => {
+            return path.toLowerCase().startsWith(excludedPrefix.toLowerCase())
+        }) || excludedSuffixes.some((excludedSuffix) => {
+            return path.toLowerCase().endsWith(excludedSuffix.toLowerCase())
+        })
+    }
+
     private filterHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string | string[] | undefined> {
         const excludedHeaders = new Set([
             "authorization",

package/tsconfig.json

@@ -4,12 +4,13 @@
     "target": "ES2020",
     "module": "CommonJS",
     "outDir": "dist",
+    "rootDir": "src",
     "declaration": true,
     "declarationMap": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
-    "moduleResolution": "node"
+    "types": ["node"]
   }
 }