@knownagents/sdk 2.0.0 → 2.2.0

package/README.md

@@ -22,131 +22,92 @@ import { KnownAgents } from "@knownagents/sdk"
 const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
 ```
 
-## How To Set Up Agent & LLM Analytics ([Full Docs](https://knownagents.com/docs/analytics))
-
-Get realtime insight into the hidden ecosystem of [AI agents and other bots](https://knownagents.com/agents) browsing your website, REST APIs, and [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers. Measure human traffic coming from AI chat and search platforms like ChatGPT, Perplexity, and Gemini.
-
-### Track Pageview and REST Calls
-
-To collect pageview and REST API analytics, call `trackPageviewOrRESTCall` with the incoming Node.js request and response.
-
-```ts
-knownAgents.trackPageviewOrRESTCall(request, response)
-```
-
-For REST APIs that return [ACP (Agentic Commerce Protocol)](https://www.agenticcommerce.dev/) or [UCP (Universal Commerce Protocol)](https://ucp.dev/) commerce metadata, include the response body:
-
-```ts
-knownAgents.trackPageviewOrRESTCall(request, response, {
-    restACPResponseBody: acpResponseBody
-})
-```
+To batch visits, set the visit event queue size and flush interval:
 
 ```ts
-knownAgents.trackPageviewOrRESTCall(request, response, {
-    restUCPResponseBody: ucpResponseBody
+const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN", {
+    flushQueueSize: 1000,
+    flushIntervalInMilliseconds: 10000
 })
 ```
 
-The SDK waits for the response to finish, then sends status, headers, duration, and any commerce metadata. Sensitive headers are filtered automatically.
+The entire visit event queue is uploaded when it reaches `flushQueueSize` or when the flush interval elapses after the first visit event enters an empty queue.
 
-#### Use Middleware if Possible
+## Send Visit Events ([Agent Analytics](https://knownagents.com/products/agent-analytics), [LLM Referral Tracking](https://knownagents.com/products/llm-referral-tracking))
 
-If your framework supports middleware, call `trackPageviewOrRESTCall` there so pageviews and REST calls are tracked from a single place. [MCP](https://modelcontextprotocol.io/) requests are skipped automatically.
+Get realtime insight into how [AI agents and other bots](https://knownagents.com/agents) browse your web pages, call your [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoints, and purchase products through your [ACP (Agentic Commerce Protocol)](https://www.agenticcommerce.dev/) and [UCP (Universal Commerce Protocol)](https://ucp.dev/) shopping flows. Measure human traffic from AI chat and search platforms like ChatGPT, Claude, and Gemini.
 
-```ts
-import express from "express"
-import { KnownAgents } from "@knownagents/sdk"
+### Pageviews and REST Calls
 
-const app = express()
-const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
+Call `trackPageviewOrRESTCall` with the incoming request and outgoing response. If you can, do this in middleware. This method skips MCP calls automatically.
 
-app.use((request, response, next) => {
-    knownAgents.trackPageviewOrRESTCall(request, response)
-    next()
-})
-
-app.get("/", (request, response) => {
-    response.send("Hello, world!")
-})
-
-app.listen(3000, () => console.log("Server running on port 3000"))
+```ts
+knownAgents.trackPageviewOrRESTCall(request, response)
 ```
 
-### Track MCP Calls
-
-For [MCP](https://modelcontextprotocol.io/) servers that use `StreamableHTTPServerTransport`, call `trackMCPCall` after connecting the transport and before the transport handles the request.
-
-For MCP calls that return [ACP](https://www.agenticcommerce.dev/) or [UCP](https://ucp.dev/) commerce metadata, the SDK captures the relevant currency and total amount automatically.
+### MCP Calls (Optional)
 
-Use this order in your MCP HTTP handler:
+For MCP servers that use `StreamableHTTPServerTransport`, call `trackMCPCall` after connecting the transport and before the transport handles the request.
 
 ```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
 
+// ...
+
+const mcpServer = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+})
+
 const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined
 })
 
+// ...
+
 await mcpServer.connect(transport)
+
 knownAgents.trackMCPCall(request, response, transport)
+
 await transport.handleRequest(request, response, parsedBody)
 ```
 
-Use `trackVisits` instead if the same transport instance handles concurrent requests.
+### Agentic Commerce Interactions (Optional)
 
-### Batching
-
-For high-traffic websites, batch multiple visits together and send them periodically (e.g. every 30 seconds) using `trackVisits`. `trackVisits` can also batch MCP visits; if you do that, include the MCP fields in each `VisitRequest` and do not also call `trackMCPCall` for the same requests. Here's an Express example:
+For REST implementations of ACP and UCP, include the response body in `trackPageviewOrRESTCall`.
 
 ```ts
-import express from "express"
-import { KnownAgents, type VisitRequest } from "@knownagents/sdk"
+// For ACP calls ...
 
-const app = express()
-const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
-const visits: VisitRequest[] = []
-
-app.use((request, response, next) => {
-    const created = new Date()
-
-    response.once("finish", () => {
-        visits.push({
-            request_path: request.url,
-            request_method: request.method,
-            request_headers: request.headers,
-            response_status_code: response.statusCode,
-            response_headers: response.getHeaders(),
-            response_duration_in_milliseconds: Date.now() - created.getTime(),
-            created: created.toISOString()
-        })
-    })
-
-    next()
+knownAgents.trackPageviewOrRESTCall(request, response, {
+    acpResponseBody: acpResponseBody
 })
+```
 
-setInterval(() => {
-    const batch = visits.splice(0)
+```ts
+// For UCP calls ...
 
-    if (batch.length > 0) {
-        knownAgents.trackVisits(batch)
-    }
-}, 30000)
+knownAgents.trackPageviewOrRESTCall(request, response, {
+    ucpResponseBody: ucpResponseBody
+})
 ```
 
+`trackMCPCall` will track MCP implementations of ACP and UCP automatically.
+
 ### Test Your Integration
 
 - Open your project's settings page
 - Click **Send a Test Visit**
 - Click **Realtime**
 
-If your website is correctly connected, you should see visits from the Known Agent in the realtime timeline within a few seconds.
+If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.
 
-## How To Set Up Automatic Robots.txt ([Full Docs](https://knownagents.com/docs/robots-txt))
+## Set Up Automatic Robots.txt ([Automatic Robots.txt](https://knownagents.com/products/automatic-robots-txt))
 
-Protect sensitive content from unwanted access and scraping. Generate a continuously updating robots.txt that stays up to date with [all current and future bots](https://knownagents.com/agents) in the specified categories automatically.
+Serve a robots.txt that continuously updates with rules for new [crawlers, scrapers, AI agents, and other bots](https://knownagents.com/agents) as they're discovered.
 
-Use the `generateRobotsTXT` function. Select which `AgentType`s you want to block, and a string specifying which URLs are disallowed (e.g. `"/"` to disallow all paths).
+Use the `generateRobotsTXT` method. Select which `AgentType`s you want to block, and a string specifying which URLs are disallowed (e.g. `"/"` to disallow all paths).
 
 ```ts
 import { AgentType } from "@knownagents/sdk"
@@ -159,29 +120,19 @@ 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 Identification ([Full Docs](https://knownagents.com/docs/identification))
+The return value is a plain text robots.txt string. Generate a `robotsTxt` periodically (e.g. once per day, using a cron job). Then, serve it from your website's `/robots.txt` endpoint.
 
-Use the `identifyAgent` and `identifyAgents` functions to identify and verify [AI agents and bots](https://knownagents.com/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.
+## Use the Agent Identification API ([Agent Identification API](https://knownagents.com/products/agent-identification-api))
 
-### Identify a Single Request
+Identify and verify [AI agents and other bots](https://knownagents.com/agents) in your own products, from incoming network requests. Authentication uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This API can be useful for implementing access policies based on verified agent identity or enriching your own datasets.
 
-Call `identifyAgent` with the incoming request.
+Call `identifyAgent` to identify a single incoming request:
 
 ```ts
 const identification = await knownAgents.identifyAgent(request)
-
-if (identification.result === "verified") {
-    handleVerifiedAgent(identification)
-} else if (identification.result === "verification_failed") {
-    handleFailedVerification(identification)
-}
 ```
 
-### Identify Multiple Requests
-
-Use `identifyAgents` to identify multiple requests at once:
+Call `identifyAgents` to identify multiple requests at once:
 
 ```ts
 const identifications = await knownAgents.identifyAgents([
@@ -196,19 +147,19 @@ const identifications = await knownAgents.identifyAgents([
 ])
 ```
 
-The functions return an object (or array of objects) with the following fields:
+These methods return an object (or array of objects) with the following fields:
 
 - `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
-  - `"not_verifiable"`: The agent cannot be verified (no verification method available)
+  - `"verified"`: The agent was identified and verified
+  - `"verification_failed"`: The agent was identified but failed verification (it was spoofed)
+  - `"not_verifiable"`: The agent was identified but could not be verified (no method available)
+  - `"unknown_agent"`: Not an agent, or the agent is not in the database
 - `agent_id`: The unique ID of the agent (if identified)
-- `agent_token`: The name of the agent (e.g. `"Googlebot"`) (if identified)
+- `agent_token`: The name of the agent (e.g. `"Claude-User"`) (if identified)
 - `agent_url`: The documentation URL of the agent (if identified)
-- `agent_type_name`: The type of agent (e.g. `"AI Agent"`) (if identified)
-- `operator_name`: The company behind the agent (e.g. `"Google"`) (if identified)
+- `agent_type_name`: The type of agent (e.g. `"AI Assistant"`) (if identified)
+- `operator_name`: The company operating the agent (e.g. `"Anthropic"`) (if identified)
 
 ## Requirements
 

package/dist/KnownAgents.d.ts

@@ -1,21 +1,27 @@
 import type { IncomingMessage, ServerResponse } from "http";
 import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import type { AgentType, IdentificationRequest, IdentificationResult, TrackPageviewOrRESTCallOptions, VisitRequest } from "./types";
+import type { AgentType, IdentificationRequest, IdentificationResult, KnownAgentsOptions, TrackPageviewOrRESTCallOptions, VisitRequest } from "./types";
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
  */
 export declare class KnownAgents {
     private readonly accessToken;
+    private readonly flushIntervalInMilliseconds;
+    private readonly flushQueueSize;
+    private readonly visitQueue;
+    private flushTimeout;
+    private pendingFlushPromise;
     /**
      * Creates a new instance of the Known Agents client.
      *
      * @param accessToken - Your project's access token.
+     * @param options - Optional batching configuration.
      */
-    constructor(accessToken: string);
+    constructor(accessToken: string, options?: KnownAgentsOptions);
     /**
      * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is sent after the response finishes so status, headers, and duration are included.
-     * This method is non-blocking and handles errors internally.
+     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
@@ -26,7 +32,7 @@ export declare class KnownAgents {
      * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
      * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
      * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles errors internally.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
@@ -34,13 +40,20 @@ export declare class KnownAgents {
      */
     trackMCPCall(request: IncomingMessage, response: ServerResponse, transport: StreamableHTTPServerTransport): void;
     /**
-     * Tracks multiple 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).
+     * Adds multiple visits to the visit event queue for analytics.
+     * This method is non-blocking and handles upload errors internally.
+     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
      *
      * @param requests - An array of visits.
      */
     trackVisits(requests: VisitRequest[]): void;
+    /**
+     * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
+     * This method handles upload errors internally.
+     *
+     * @returns A promise that resolves after all pending upload attempts finish.
+     */
+    flush(): Promise<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.
@@ -70,5 +83,7 @@ export declare class KnownAgents {
      * @throws {Error} If the API call fails or returns a non-200 status.
      */
     identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]>;
+    private scheduleFlush;
+    private sendVisits;
 }
 //# sourceMappingURL=KnownAgents.d.ts.map

package/dist/KnownAgents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KnownAgents.d.ts","sourceRoot":"","sources":["../src/KnownAgents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAA;AAavG,OAAO,KAAK,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,8BAA8B,EAC9B,YAAY,EACf,MAAM,SAAS,CAAA;AAqChB;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAEpC;;;;OAIG;gBACS,WAAW,EAAE,MAAM;IAI/B;;;;;;;;OAQG;IACH,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,8BAA8B,GAAG,IAAI;IAsC3H;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B,GAAG,IAAI;IAuEhH;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IA6B3C;;;;;;;;;OASG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBzF;;;;;;;OAOG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmB5E;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAsB3F"}
+{"version":3,"file":"KnownAgents.d.ts","sourceRoot":"","sources":["../src/KnownAgents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAA;AAGvG,OAAO,KAAK,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,8BAA8B,EAC9B,YAAY,EACf,MAAM,SAAS,CAAA;AAKhB;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAQ;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,mBAAmB,CAAmC;IAE9D;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAMjE;;;;;;;;OAQG;IACH,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,8BAA8B,GAAG,IAAI;IAoC3H;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B,GAAG,IAAI;IAoEhH;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IA2B3C;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtB;;;;;;;;;OASG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBzF;;;;;;;OAOG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmB5E;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAsBxF,OAAO,CAAC,aAAa;YAaP,UAAU;CAmB3B"}

package/dist/KnownAgents.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KnownAgents = void 0;
-const commerce_1 = require("./commerce");
 const headers_1 = require("./headers");
 const paths_1 = require("./paths");
+const DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS = 10000;
+const DEFAULT_FLUSH_QUEUE_SIZE = 1;
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
  */
@@ -12,14 +13,19 @@ class KnownAgents {
      * Creates a new instance of the Known Agents client.
      *
      * @param accessToken - Your project's access token.
+     * @param options - Optional batching configuration.
      */
-    constructor(accessToken) {
+    constructor(accessToken, options = {}) {
+        this.visitQueue = [];
+        this.pendingFlushPromise = Promise.resolve();
         this.accessToken = accessToken;
+        this.flushIntervalInMilliseconds = options.flushIntervalInMilliseconds ?? DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS;
+        this.flushQueueSize = options.flushQueueSize ?? DEFAULT_FLUSH_QUEUE_SIZE;
     }
     /**
      * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is sent after the response finishes so status, headers, and duration are included.
-     * This method is non-blocking and handles errors internally.
+     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
@@ -42,10 +48,8 @@ class KnownAgents {
                 response_status_code: response?.statusCode,
                 response_headers: response.getHeaders(),
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                acp_response_currency: options?.restACPResponseBody ? (0, commerce_1.getRESTACPCurrencyIfPossible)(options?.restACPResponseBody) : undefined,
-                acp_response_total_amount: options?.restACPResponseBody ? (0, commerce_1.getRESTACPTotalAmountIfPossible)(options?.restACPResponseBody) : undefined,
-                ucp_response_currency: options?.restUCPResponseBody ? (0, commerce_1.getRESTUCPCurrencyIfPossible)(options?.restUCPResponseBody) : undefined,
-                ucp_response_total_amount: options?.restUCPResponseBody ? (0, commerce_1.getRESTUCPTotalAmountIfPossible)(options?.restUCPResponseBody) : undefined,
+                acp_response_body: options?.acpResponseBody,
+                ucp_response_body: options?.ucpResponseBody,
                 created: created.toISOString()
             };
             this.trackVisits([visitRequest]);
@@ -61,17 +65,16 @@ class KnownAgents {
      * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
      * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
      * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles errors internally.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
      * @param transport - The MCP streamable HTTP transport handling the request.
      */
     trackMCPCall(request, response, transport) {
-        const isMCPCall = (0, headers_1.getIsMCPCall)(request.headers);
         const path = request.url;
         const method = request.method;
-        if (!isMCPCall || !path || (0, paths_1.getIsPathExcluded)(path) || !method) {
+        if (!path || (0, paths_1.getIsPathExcluded)(path) || !method) {
             return;
         }
         const created = new Date();
@@ -111,10 +114,8 @@ class KnownAgents {
                 mcp_response_result_is_error: mcpResponseBody.result?.isError,
                 mcp_response_error_code: mcpResponseBody.error?.code,
                 mcp_response_error_message: mcpResponseBody.error?.message,
-                acp_response_currency: (0, commerce_1.getMCPACPCurrencyIfPossible)(request, mcpResponseBody),
-                acp_response_total_amount: (0, commerce_1.getMCPACPTotalAmountIfPossible)(request, mcpResponseBody),
-                ucp_response_currency: (0, commerce_1.getMCPUCPCurrencyIfPossible)(request, mcpResponseBody),
-                ucp_response_total_amount: (0, commerce_1.getMCPUCPTotalAmountIfPossible)(request, mcpResponseBody),
+                acp_response_body: (0, headers_1.getIsACPCall)(request.headers) ? mcpResponseBody.result?.structuredContent ?? mcpResponseBody.result : undefined,
+                ucp_response_body: (0, headers_1.getIsUCPCall)(request.headers) ? mcpResponseBody.result?.structuredContent ?? mcpResponseBody.result : undefined,
                 created: created.toISOString()
             };
             this.trackVisits([visitRequest]);
@@ -127,9 +128,9 @@ class KnownAgents {
         }
     }
     /**
-     * Tracks multiple 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).
+     * Adds multiple visits to the visit event queue for analytics.
+     * This method is non-blocking and handles upload errors internally.
+     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
      *
      * @param requests - An array of visits.
      */
@@ -148,16 +149,32 @@ class KnownAgents {
         if (filteredRequests.length === 0) {
             return;
         }
-        fetch("https://api.knownagents.com/visits", {
-            method: "POST",
-            headers: {
-                "Authorization": `Bearer ${this.accessToken}`,
-                "Content-Type": "application/json"
-            },
-            body: JSON.stringify(filteredRequests)
-        }).catch(error => {
-            console.error(`Known Agents failed to track visits: ${error.message}`);
+        this.visitQueue.push(...filteredRequests);
+        if (this.visitQueue.length >= this.flushQueueSize) {
+            void this.flush();
+            return;
+        }
+        this.scheduleFlush();
+    }
+    /**
+     * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
+     * This method handles upload errors internally.
+     *
+     * @returns A promise that resolves after all pending upload attempts finish.
+     */
+    flush() {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout);
+            this.flushTimeout = undefined;
+        }
+        const requests = this.visitQueue.splice(0);
+        if (requests.length === 0) {
+            return this.pendingFlushPromise;
+        }
+        this.pendingFlushPromise = this.pendingFlushPromise.then(() => {
+            return this.sendVisits(requests);
         });
+        return this.pendingFlushPromise;
     }
     /**
      * Generates a robots.txt file that disallows the specified agent types.
@@ -243,5 +260,34 @@ class KnownAgents {
             throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`);
         }
     }
+    scheduleFlush() {
+        if (this.flushTimeout) {
+            return;
+        }
+        this.flushTimeout = setTimeout(() => {
+            this.flushTimeout = undefined;
+            void this.flush();
+        }, this.flushIntervalInMilliseconds);
+        this.flushTimeout.unref();
+    }
+    async sendVisits(requests) {
+        try {
+            const response = await fetch("https://api.knownagents.com/visits", {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${this.accessToken}`,
+                    "Content-Type": "application/json"
+                },
+                body: JSON.stringify(requests)
+            });
+            if (!response.ok) {
+                throw new Error(`${response.status} ${response.statusText}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Known Agents failed to track visits: ${message}`);
+        }
+    }
 }
 exports.KnownAgents = KnownAgents;

package/dist/headers.d.ts

@@ -2,5 +2,5 @@ import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
 export declare function getFilteredHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers;
 export declare function getIsMCPCall(headers: IncomingHttpHeaders): boolean;
 export declare function getIsUCPCall(headers: IncomingHttpHeaders): boolean;
-export declare function getIsProbablyACPCall(headers: IncomingHttpHeaders): boolean;
+export declare function getIsACPCall(headers: IncomingHttpHeaders): boolean;
 //# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AA2BpE,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUvH;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAI1E"}
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AA2BpE,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUvH;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE"}

package/dist/headers.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFilteredHeaders = getFilteredHeaders;
 exports.getIsMCPCall = getIsMCPCall;
 exports.getIsUCPCall = getIsUCPCall;
-exports.getIsProbablyACPCall = getIsProbablyACPCall;
+exports.getIsACPCall = getIsACPCall;
 const filteredHeaderNames = [
     "authorization",
     "proxy-authorization",
@@ -47,8 +47,8 @@ function getIsUCPCall(headers) {
         return key.toLowerCase() === "ucp-agent";
     });
 }
-function getIsProbablyACPCall(headers) {
-    return Object.keys(headers).some((key) => {
+function getIsACPCall(headers) {
+    return !getIsUCPCall(headers) && Object.keys(headers).some((key) => {
         return key.toLowerCase() === "api-version";
     });
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { KnownAgents } from "./KnownAgents";
-export { AgentType, type IdentificationRequest, type IdentificationResult, type RESTACPResponseBody, type RESTUCPResponseBody, type TrackPageviewOrRESTCallOptions, type VisitRequest } from "./types";
+export { AgentType, type IdentificationRequest, type IdentificationResult, type KnownAgentsOptions, type TrackPageviewOrRESTCallOptions, type VisitRequest } from "./types";
 //# 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,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACH,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,YAAY,EACpB,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACH,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,8BAA8B,EACnC,KAAK,YAAY,EACpB,MAAM,SAAS,CAAA"}

package/dist/types.d.ts

@@ -1,40 +1,25 @@
 import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
 /**
- * ACP response details from a REST API call.
+ * Batching configuration for the Known Agents client.
  */
-export interface RESTACPResponseBody {
-    /** The response currency, usually an ISO 4217 code. */
-    currency?: string;
-    /** ACP totals returned by the REST endpoint. The "total" item is sent to Known Agents. */
-    totals?: {
-        type?: string;
-        amount?: number;
-    }[];
-}
-/**
- * UCP response details from a REST API call.
- */
-export interface RESTUCPResponseBody {
-    /** The response currency, usually an ISO 4217 code. */
-    currency?: string;
-    /** UCP totals returned by the REST endpoint. The "total" item is sent to Known Agents. */
-    totals?: {
-        type?: string;
-        amount?: number;
-    }[];
+export interface KnownAgentsOptions {
+    /** The maximum time a partial visit event queue waits before upload. Defaults to 10,000 milliseconds. */
+    flushIntervalInMilliseconds?: number;
+    /** The number of visit events in the queue that triggers an upload. Defaults to 1. */
+    flushQueueSize?: number;
 }
 /**
  * Additional metadata to include when tracking a pageview or REST API call.
  */
 export interface TrackPageviewOrRESTCallOptions {
-    /** ACP response body from the REST endpoint. */
-    restACPResponseBody?: RESTACPResponseBody;
-    /** UCP response body from the REST endpoint. */
-    restUCPResponseBody?: RESTUCPResponseBody;
+    /** The ACP response body. */
+    acpResponseBody?: Record<string, unknown>;
+    /** The UCP response body. */
+    ucpResponseBody?: Record<string, unknown>;
 }
 /**
  * A normalized visit payload for the Known Agents API.
- * Use this with `trackVisits()` when batching requests yourself.
+ * Use this with `trackVisits()` to manually add visit events to the queue.
  */
 export interface VisitRequest {
     /** The URL path and query string of the request (e.g. "/about?foo=bar") */
@@ -63,14 +48,10 @@ export interface VisitRequest {
     mcp_response_error_code?: number;
     /** The MCP response error message */
     mcp_response_error_message?: string;
-    /** The ACP response currency */
-    acp_response_currency?: string;
-    /** The ACP response "total" amount */
-    acp_response_total_amount?: number;
-    /** The UCP response currency */
-    ucp_response_currency?: string;
-    /** The UCP response "total" amount */
-    ucp_response_total_amount?: number;
+    /** The ACP response body */
+    acp_response_body?: Record<string, unknown>;
+    /** The UCP response body */
+    ucp_response_body?: Record<string, unknown>;
     /** The timestamp when the visit occurred (ISO 8601 format) */
     created?: string;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AAEpE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,MAAM,CAAC,EAAE,MAAM,CAAA;KAClB,EAAE,CAAA;CACN;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0FAA0F;IAC1F,MAAM,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,MAAM,CAAC,EAAE,MAAM,CAAA;KAClB,EAAE,CAAA;CACN;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC3C,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC,gDAAgD;IAChD,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,8EAA8E;IAC9E,eAAe,EAAE,mBAAmB,CAAA;IACpC,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;IACtC,4CAA4C;IAC5C,iCAAiC,CAAC,EAAE,MAAM,CAAA;IAC1C,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gCAAgC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,kCAAkC;IAClC,4BAA4B,CAAC,EAAE,MAAM,CAAA;IACrC,qCAAqC;IACrC,+BAA+B,CAAC,EAAE,MAAM,CAAA;IACxC,kDAAkD;IAClD,4BAA4B,CAAC,EAAE,OAAO,CAAA;IACtC,kCAAkC;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,qCAAqC;IACrC,0BAA0B,CAAC,EAAE,MAAM,CAAA;IACnC,gCAAgC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,sCAAsC;IACtC,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,gCAAgC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,sCAAsC;IACtC,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,4FAA4F;IAC5F,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,eAAe,EAAE,mBAAmB,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,oDAAoD;IACpD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,eAAe,GAAG,gBAAgB,CAAA;IAC/E,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,oBAAY,SAAS;IACjB,OAAO,aAAa;IACpB,WAAW,iBAAiB;IAC5B,aAAa,oBAAoB;IACjC,cAAc,qBAAqB;IACnC,aAAa,oBAAoB;IACjC,eAAe,sBAAsB;IACrC,QAAQ,aAAa;IACrB,cAAc,oBAAoB;IAClC,eAAe,qBAAqB;IACpC,OAAO,YAAY;IACnB,oBAAoB,0BAA0B;IAC9C,OAAO,YAAY;IACnB,UAAU,gBAAgB;IAC1B,mBAAmB,0BAA0B;IAC7C,eAAe,qBAAqB;IACpC,mBAAmB,0BAA0B;CAChD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AAEpE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,yGAAyG;IACzG,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC3C,6BAA6B;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,6BAA6B;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,8EAA8E;IAC9E,eAAe,EAAE,mBAAmB,CAAA;IACpC,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;IACtC,4CAA4C;IAC5C,iCAAiC,CAAC,EAAE,MAAM,CAAA;IAC1C,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gCAAgC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,kCAAkC;IAClC,4BAA4B,CAAC,EAAE,MAAM,CAAA;IACrC,qCAAqC;IACrC,+BAA+B,CAAC,EAAE,MAAM,CAAA;IACxC,kDAAkD;IAClD,4BAA4B,CAAC,EAAE,OAAO,CAAA;IACtC,kCAAkC;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,qCAAqC;IACrC,0BAA0B,CAAC,EAAE,MAAM,CAAA;IACnC,4BAA4B;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,4BAA4B;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,4FAA4F;IAC5F,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,8EAA8E;IAC9E,eAAe,EAAE,mBAAmB,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,oDAAoD;IACpD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX;;;;;;OAMG;IACH,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,eAAe,GAAG,gBAAgB,CAAA;IAC/E,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,oBAAY,SAAS;IACjB,OAAO,aAAa;IACpB,WAAW,iBAAiB;IAC5B,aAAa,oBAAoB;IACjC,cAAc,qBAAqB;IACnC,aAAa,oBAAoB;IACjC,eAAe,sBAAsB;IACrC,QAAQ,aAAa;IACrB,cAAc,oBAAoB;IAClC,eAAe,qBAAqB;IACpC,OAAO,YAAY;IACnB,oBAAoB,0BAA0B;IAC9C,OAAO,YAAY;IACnB,UAAU,gBAAgB;IAC1B,mBAAmB,0BAA0B;IAC7C,eAAe,qBAAqB;IACpC,mBAAmB,0BAA0B;CAChD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knownagents/sdk",
-  "version": "2.0.0",
-  "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt, agent verification",
+  "version": "2.2.0",
+  "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt, agent identification",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
     "web scraping",
     "ai blocking",
     "bot blocking",
-    "agent verification",
+    "agent identification",
     "bot verification",
     "verify ai agents",
     "web bot auth",

package/src/KnownAgents.ts

@@ -1,79 +1,46 @@
 import type { IncomingMessage, ServerResponse } from "http"
 import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
-import {
-    getMCPACPCurrencyIfPossible,
-    getMCPACPTotalAmountIfPossible,
-    getMCPUCPCurrencyIfPossible,
-    getMCPUCPTotalAmountIfPossible,
-    getRESTACPCurrencyIfPossible,
-    getRESTACPTotalAmountIfPossible,
-    getRESTUCPCurrencyIfPossible,
-    getRESTUCPTotalAmountIfPossible
-} from "./commerce"
-import { getFilteredHeaders, getIsMCPCall } from "./headers"
+import { getFilteredHeaders, getIsACPCall, getIsMCPCall, getIsUCPCall } from "./headers"
 import { getIsPathExcluded } from "./paths"
 import type {
     AgentType,
     IdentificationRequest,
     IdentificationResult,
+    KnownAgentsOptions,
     TrackPageviewOrRESTCallOptions,
     VisitRequest
 } from "./types"
 
-interface MCPRequestBody {
-    jsonrpc: string
-    method: string
-    params?: {
-        name?: string
-        clientInfo?: {
-            name?: string
-            version?: string
-        }
-    }
-}
-
-interface MCPResponseBody {
-    jsonrpc: string
-    result?: {
-        isError?: boolean
-        currency?: string
-        totals?: {
-            type?: string
-            amount?: number
-        }[]
-        structuredContent?: {
-            currency?: string
-            totals?: {
-                type?: string
-                amount?: number
-            }[]
-        }
-    }
-    error?: {
-        code?: number
-        message?: string
-    }
-}
+const DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS = 10000
+const DEFAULT_FLUSH_QUEUE_SIZE = 1
 
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
  */
 export class KnownAgents {
     private readonly accessToken: string
+    private readonly flushIntervalInMilliseconds: number
+    private readonly flushQueueSize: number
+    private readonly visitQueue: VisitRequest[] = []
+    private flushTimeout: NodeJS.Timeout | undefined
+    private pendingFlushPromise: Promise<void> = Promise.resolve()
 
     /**
      * Creates a new instance of the Known Agents client.
-     * 
+     *
      * @param accessToken - Your project's access token.
+     * @param options - Optional batching configuration.
      */
-    constructor(accessToken: string) {
+    constructor(accessToken: string, options: KnownAgentsOptions = {}) {
         this.accessToken = accessToken
+        this.flushIntervalInMilliseconds = options.flushIntervalInMilliseconds ?? DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS
+        this.flushQueueSize = options.flushQueueSize ?? DEFAULT_FLUSH_QUEUE_SIZE
     }
 
     /**
      * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is sent after the response finishes so status, headers, and duration are included.
-     * This method is non-blocking and handles errors internally.
+     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
@@ -100,10 +67,8 @@ export class KnownAgents {
                 response_status_code: response?.statusCode,
                 response_headers: response.getHeaders(),
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                acp_response_currency: options?.restACPResponseBody ? getRESTACPCurrencyIfPossible(options?.restACPResponseBody) : undefined,
-                acp_response_total_amount: options?.restACPResponseBody ? getRESTACPTotalAmountIfPossible(options?.restACPResponseBody) : undefined,
-                ucp_response_currency: options?.restUCPResponseBody ? getRESTUCPCurrencyIfPossible(options?.restUCPResponseBody) : undefined,
-                ucp_response_total_amount: options?.restUCPResponseBody ? getRESTUCPTotalAmountIfPossible(options?.restUCPResponseBody) : undefined,
+                acp_response_body: options?.acpResponseBody,
+                ucp_response_body: options?.ucpResponseBody,
                 created: created.toISOString()
             }
 
@@ -121,35 +86,34 @@ export class KnownAgents {
      * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
      * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
      * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles errors internally.
+     * This method is non-blocking and handles upload errors internally.
      *
      * @param request - The incoming Node.js HTTP request.
      * @param response - The outgoing Node.js HTTP response.
      * @param transport - The MCP streamable HTTP transport handling the request.
      */
     trackMCPCall(request: IncomingMessage, response: ServerResponse, transport: StreamableHTTPServerTransport): void {
-        const isMCPCall = getIsMCPCall(request.headers)
         const path = request.url
         const method = request.method
 
-        if (!isMCPCall || !path || getIsPathExcluded(path) || !method) {
+        if (!path || getIsPathExcluded(path) || !method) {
             return
         }
 
         const created = new Date()
 
-        let mcpRequestBody: MCPRequestBody | undefined
-        let mcpResponseBody: MCPResponseBody | undefined
+        let mcpRequestBody: any
+        let mcpResponseBody: any
 
         const originalTransportOnMessage = transport.onmessage
         transport.onmessage = (message, extra): void => {
-            mcpRequestBody = message as MCPRequestBody
+            mcpRequestBody = message
             originalTransportOnMessage?.(message, extra)
         }
-    
+
         const originalTransportSend = transport.send
         transport.send = async (message, options): Promise<void> => {
-            mcpResponseBody = message as MCPResponseBody
+            mcpResponseBody = message
             await originalTransportSend.call(transport, message, options)
         }
 
@@ -181,10 +145,8 @@ export class KnownAgents {
                 mcp_response_result_is_error: mcpResponseBody.result?.isError,
                 mcp_response_error_code: mcpResponseBody.error?.code,
                 mcp_response_error_message: mcpResponseBody.error?.message,
-                acp_response_currency: getMCPACPCurrencyIfPossible(request, mcpResponseBody),
-                acp_response_total_amount: getMCPACPTotalAmountIfPossible(request, mcpResponseBody),
-                ucp_response_currency: getMCPUCPCurrencyIfPossible(request, mcpResponseBody),
-                ucp_response_total_amount: getMCPUCPTotalAmountIfPossible(request, mcpResponseBody),
+                acp_response_body: getIsACPCall(request.headers) ? mcpResponseBody.result?.structuredContent ?? mcpResponseBody.result : undefined,
+                ucp_response_body: getIsUCPCall(request.headers) ? mcpResponseBody.result?.structuredContent ?? mcpResponseBody.result : undefined,
                 created: created.toISOString()
             }
 
@@ -197,11 +159,11 @@ export class KnownAgents {
             response.once("finish", sendVisit)
         }
     }
-    
+
     /**
-     * Tracks multiple 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).
+     * Adds multiple visits to the visit event queue for analytics.
+     * This method is non-blocking and handles upload errors internally.
+     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
      *
      * @param requests - An array of visits.
      */
@@ -222,18 +184,41 @@ export class KnownAgents {
             return
         }
 
-        fetch("https://api.knownagents.com/visits", {
-            method: "POST",
-            headers: {
-                "Authorization": `Bearer ${this.accessToken}`,
-                "Content-Type": "application/json"
-            },
-            body: JSON.stringify(filteredRequests)
-        }).catch(error => {
-            console.error(`Known Agents failed to track visits: ${error.message}`)
+        this.visitQueue.push(...filteredRequests)
+
+        if (this.visitQueue.length >= this.flushQueueSize) {
+            void this.flush()
+            return
+        }
+
+        this.scheduleFlush()
+    }
+
+    /**
+     * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
+     * This method handles upload errors internally.
+     *
+     * @returns A promise that resolves after all pending upload attempts finish.
+     */
+    flush(): Promise<void> {
+        if (this.flushTimeout) {
+            clearTimeout(this.flushTimeout)
+            this.flushTimeout = undefined
+        }
+
+        const requests = this.visitQueue.splice(0)
+
+        if (requests.length === 0) {
+            return this.pendingFlushPromise
+        }
+
+        this.pendingFlushPromise = this.pendingFlushPromise.then(() => {
+            return this.sendVisits(requests)
         })
+
+        return this.pendingFlushPromise
     }
-    
+
     /**
      * 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.
@@ -263,7 +248,7 @@ export class KnownAgents {
             throw new Error(`Known Agents failed to generate robots.txt: ${response.status} ${response.statusText}`)
         }
     }
-    
+
     /**
      * Identifies and verifies a single agent from an HTTP request.
      * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
@@ -321,4 +306,36 @@ export class KnownAgents {
         }
     }
 
+    private scheduleFlush(): void {
+        if (this.flushTimeout) {
+            return
+        }
+
+        this.flushTimeout = setTimeout(() => {
+            this.flushTimeout = undefined
+            void this.flush()
+        }, this.flushIntervalInMilliseconds)
+
+        this.flushTimeout.unref()
+    }
+
+    private async sendVisits(requests: VisitRequest[]): Promise<void> {
+        try {
+            const response = await fetch("https://api.knownagents.com/visits", {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${this.accessToken}`,
+                    "Content-Type": "application/json"
+                },
+                body: JSON.stringify(requests)
+            })
+
+            if (!response.ok) {
+                throw new Error(`${response.status} ${response.statusText}`)
+            }
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            console.error(`Known Agents failed to track visits: ${message}`)
+        }
+    }
 }

package/src/headers.ts

@@ -49,8 +49,8 @@ export function getIsUCPCall(headers: IncomingHttpHeaders): boolean {
     })
 }
 
-export function getIsProbablyACPCall(headers: IncomingHttpHeaders): boolean {
-    return Object.keys(headers).some((key) => {
+export function getIsACPCall(headers: IncomingHttpHeaders): boolean {
+    return !getIsUCPCall(headers) && Object.keys(headers).some((key) => {
         return key.toLowerCase() === "api-version"
     })
 }

package/src/index.ts

@@ -3,8 +3,7 @@ export {
     AgentType,
     type IdentificationRequest,
     type IdentificationResult,
-    type RESTACPResponseBody,
-    type RESTUCPResponseBody,
+    type KnownAgentsOptions,
     type TrackPageviewOrRESTCallOptions,
     type VisitRequest
 } from "./types"

package/src/types.ts

@@ -1,44 +1,28 @@
 import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http"
 
 /**
- * ACP response details from a REST API call.
+ * Batching configuration for the Known Agents client.
  */
-export interface RESTACPResponseBody {
-    /** The response currency, usually an ISO 4217 code. */
-    currency?: string
-    /** ACP totals returned by the REST endpoint. The "total" item is sent to Known Agents. */
-    totals?: {
-        type?: string
-        amount?: number
-    }[]
-}
-
-/**
- * UCP response details from a REST API call.
- */
-export interface RESTUCPResponseBody {
-    /** The response currency, usually an ISO 4217 code. */
-    currency?: string
-    /** UCP totals returned by the REST endpoint. The "total" item is sent to Known Agents. */
-    totals?: {
-        type?: string
-        amount?: number
-    }[]
+export interface KnownAgentsOptions {
+    /** The maximum time a partial visit event queue waits before upload. Defaults to 10,000 milliseconds. */
+    flushIntervalInMilliseconds?: number
+    /** The number of visit events in the queue that triggers an upload. Defaults to 1. */
+    flushQueueSize?: number
 }
 
 /**
  * Additional metadata to include when tracking a pageview or REST API call.
  */
 export interface TrackPageviewOrRESTCallOptions {
-    /** ACP response body from the REST endpoint. */
-    restACPResponseBody?: RESTACPResponseBody
-    /** UCP response body from the REST endpoint. */
-    restUCPResponseBody?: RESTUCPResponseBody
+    /** The ACP response body. */
+    acpResponseBody?: Record<string, unknown>
+    /** The UCP response body. */
+    ucpResponseBody?: Record<string, unknown>
 }
 
 /**
  * A normalized visit payload for the Known Agents API.
- * Use this with `trackVisits()` when batching requests yourself.
+ * Use this with `trackVisits()` to manually add visit events to the queue.
  */
 export interface VisitRequest {
     /** The URL path and query string of the request (e.g. "/about?foo=bar") */
@@ -67,14 +51,10 @@ export interface VisitRequest {
     mcp_response_error_code?: number
     /** The MCP response error message */
     mcp_response_error_message?: string
-    /** The ACP response currency */
-    acp_response_currency?: string
-    /** The ACP response "total" amount */
-    acp_response_total_amount?: number
-    /** The UCP response currency */
-    ucp_response_currency?: string
-    /** The UCP response "total" amount */
-    ucp_response_total_amount?: number
+    /** The ACP response body */
+    acp_response_body?: Record<string, unknown>
+    /** The UCP response body */
+    ucp_response_body?: Record<string, unknown>
     /** The timestamp when the visit occurred (ISO 8601 format) */
     created?: string
 }

package/dist/commerce.d.ts

@@ -1,28 +0,0 @@
-import type { IncomingMessage } from "http";
-import type { RESTACPResponseBody, RESTUCPResponseBody } from "./types";
-interface MCPCommerceResponseBody {
-    result?: {
-        currency?: string;
-        totals?: {
-            type?: string;
-            amount?: number;
-        }[];
-        structuredContent?: {
-            currency?: string;
-            totals?: {
-                type?: string;
-                amount?: number;
-            }[];
-        };
-    };
-}
-export declare function getRESTACPCurrencyIfPossible(restACPResponseBody: RESTACPResponseBody): string | undefined;
-export declare function getRESTACPTotalAmountIfPossible(restACPResponseBody: RESTACPResponseBody): number | undefined;
-export declare function getMCPACPCurrencyIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): string | undefined;
-export declare function getMCPACPTotalAmountIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): number | undefined;
-export declare function getRESTUCPCurrencyIfPossible(restUCPResponseBody: RESTUCPResponseBody): string | undefined;
-export declare function getRESTUCPTotalAmountIfPossible(restUCPResponseBody: RESTUCPResponseBody): number | undefined;
-export declare function getMCPUCPCurrencyIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): string | undefined;
-export declare function getMCPUCPTotalAmountIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): number | undefined;
-export {};
-//# sourceMappingURL=commerce.d.ts.map

package/dist/commerce.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"commerce.d.ts","sourceRoot":"","sources":["../src/commerce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAE3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAEvE,UAAU,uBAAuB;IAC7B,MAAM,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,MAAM,CAAC,EAAE;YACL,IAAI,CAAC,EAAE,MAAM,CAAA;YACb,MAAM,CAAC,EAAE,MAAM,CAAA;SAClB,EAAE,CAAA;QACH,iBAAiB,CAAC,EAAE;YAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;YACjB,MAAM,CAAC,EAAE;gBACL,IAAI,CAAC,EAAE,MAAM,CAAA;gBACb,MAAM,CAAC,EAAE,MAAM,CAAA;aAClB,EAAE,CAAA;SACN,CAAA;KACJ,CAAA;CACJ;AAED,wBAAgB,4BAA4B,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAEzG;AAED,wBAAgB,+BAA+B,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAI5G;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAGlI;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAOrI;AAED,wBAAgB,4BAA4B,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAEzG;AAED,wBAAgB,+BAA+B,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAI5G;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAGlI;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAOrI"}

package/dist/commerce.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRESTACPCurrencyIfPossible = getRESTACPCurrencyIfPossible;
-exports.getRESTACPTotalAmountIfPossible = getRESTACPTotalAmountIfPossible;
-exports.getMCPACPCurrencyIfPossible = getMCPACPCurrencyIfPossible;
-exports.getMCPACPTotalAmountIfPossible = getMCPACPTotalAmountIfPossible;
-exports.getRESTUCPCurrencyIfPossible = getRESTUCPCurrencyIfPossible;
-exports.getRESTUCPTotalAmountIfPossible = getRESTUCPTotalAmountIfPossible;
-exports.getMCPUCPCurrencyIfPossible = getMCPUCPCurrencyIfPossible;
-exports.getMCPUCPTotalAmountIfPossible = getMCPUCPTotalAmountIfPossible;
-const headers_1 = require("./headers");
-function getRESTACPCurrencyIfPossible(restACPResponseBody) {
-    return restACPResponseBody?.currency;
-}
-function getRESTACPTotalAmountIfPossible(restACPResponseBody) {
-    return restACPResponseBody?.totals?.find((total) => {
-        return total.type == "total";
-    })?.amount;
-}
-function getMCPACPCurrencyIfPossible(request, mcpResponseBody) {
-    const isProbablyACP = !(0, headers_1.getIsUCPCall)(request.headers) && (0, headers_1.getIsProbablyACPCall)(request.headers);
-    return isProbablyACP ? mcpResponseBody.result?.currency : undefined;
-}
-function getMCPACPTotalAmountIfPossible(request, mcpResponseBody) {
-    const isProbablyACP = !(0, headers_1.getIsUCPCall)(request.headers) && (0, headers_1.getIsProbablyACPCall)(request.headers);
-    return isProbablyACP
-        ? mcpResponseBody.result?.totals?.find((total) => {
-            return total.type == "total";
-        })?.amount
-        : undefined;
-}
-function getRESTUCPCurrencyIfPossible(restUCPResponseBody) {
-    return restUCPResponseBody?.currency;
-}
-function getRESTUCPTotalAmountIfPossible(restUCPResponseBody) {
-    return restUCPResponseBody?.totals?.find((total) => {
-        return total.type == "total";
-    })?.amount;
-}
-function getMCPUCPCurrencyIfPossible(request, mcpResponseBody) {
-    const isUCP = (0, headers_1.getIsUCPCall)(request.headers);
-    return isUCP ? mcpResponseBody.result?.structuredContent?.currency : undefined;
-}
-function getMCPUCPTotalAmountIfPossible(request, mcpResponseBody) {
-    const isUCP = (0, headers_1.getIsUCPCall)(request.headers);
-    return isUCP
-        ? mcpResponseBody.result?.structuredContent?.totals?.find((total) => {
-            return total.type == "total";
-        })?.amount
-        : undefined;
-}

package/src/commerce.ts

@@ -1,68 +0,0 @@
-import type { IncomingMessage } from "http"
-import { getIsProbablyACPCall, getIsUCPCall } from "./headers"
-import type { RESTACPResponseBody, RESTUCPResponseBody } from "./types"
-
-interface MCPCommerceResponseBody {
-    result?: {
-        currency?: string
-        totals?: {
-            type?: string
-            amount?: number
-        }[]
-        structuredContent?: {
-            currency?: string
-            totals?: {
-                type?: string
-                amount?: number
-            }[]
-        }
-    }
-}
-
-export function getRESTACPCurrencyIfPossible(restACPResponseBody: RESTACPResponseBody): string | undefined {
-    return restACPResponseBody?.currency
-}
-
-export function getRESTACPTotalAmountIfPossible(restACPResponseBody: RESTACPResponseBody): number | undefined {
-    return restACPResponseBody?.totals?.find((total) => {
-        return total.type == "total"
-    })?.amount
-}
-
-export function getMCPACPCurrencyIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): string | undefined {
-    const isProbablyACP = !getIsUCPCall(request.headers) && getIsProbablyACPCall(request.headers)
-    return isProbablyACP ? mcpResponseBody.result?.currency : undefined
-}
-
-export function getMCPACPTotalAmountIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): number | undefined {
-    const isProbablyACP = !getIsUCPCall(request.headers) && getIsProbablyACPCall(request.headers)
-    return isProbablyACP
-        ? mcpResponseBody.result?.totals?.find((total) => {
-              return total.type == "total"
-          })?.amount
-        : undefined
-}
-
-export function getRESTUCPCurrencyIfPossible(restUCPResponseBody: RESTUCPResponseBody): string | undefined {
-    return restUCPResponseBody?.currency
-}
-
-export function getRESTUCPTotalAmountIfPossible(restUCPResponseBody: RESTUCPResponseBody): number | undefined {
-    return restUCPResponseBody?.totals?.find((total) => {
-        return total.type == "total"
-    })?.amount
-}
-
-export function getMCPUCPCurrencyIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): string | undefined {
-    const isUCP = getIsUCPCall(request.headers)
-    return isUCP ? mcpResponseBody.result?.structuredContent?.currency : undefined
-}
-
-export function getMCPUCPTotalAmountIfPossible(request: IncomingMessage, mcpResponseBody: MCPCommerceResponseBody): number | undefined {
-    const isUCP = getIsUCPCall(request.headers)
-    return isUCP
-        ? mcpResponseBody.result?.structuredContent?.totals?.find((total) => {
-              return total.type == "total"
-          })?.amount
-        : undefined
-}