@knownagents/sdk 1.6.0 → 1.7.0

package/README.md

@@ -29,7 +29,13 @@ Get realtime insight into the hidden ecosystem of [crawlers, scrapers, AI agents
 To collect this data, call `trackVisit` for each incoming request in the endpoints where you serve your pages.
 
 ```ts
-knownAgents.trackVisit(incomingRequest)
+knownAgents.trackVisit(request)
+```
+
+For richer analytics, include the response and duration:
+
+```ts
+knownAgents.trackVisit(request, response, responseDurationInMilliseconds)
 ```
 
 ### Use Middleware if Possible
@@ -46,7 +52,13 @@ const app = express()
 const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")
 
 app.use((req, res, next) => {
-    knownAgents.trackVisit(req)
+    const start = Date.now()
+    
+    res.on('finish', () => {
+        const duration = Date.now() - start
+        knownAgents.trackVisit(req, res, duration)
+    })
+    
     next()
 })
 
@@ -82,7 +94,7 @@ 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.
+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.
 
 ## Requirements
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { IncomingMessage } from "http";
+import { IncomingMessage, ServerResponse } from "http";
 export interface Request {
     /** The path of the request's URL (e.g. "/about") */
     path: string;
@@ -7,6 +7,10 @@ export interface Request {
     /** The request's HTTP headers */
     headers: Record<string, string | string[] | undefined>;
 }
+export interface Response {
+    /** The HTTP response status code */
+    statusCode: number;
+}
 /**
  * Agent types that can be controlled with robots.txt rules.
  */
@@ -38,9 +42,11 @@ export declare class KnownAgents {
      * Tracks an agent visit in Known Agents agent analytics.
      *
      * @param visitRequest - The incoming visit request.
+     * @param visitResponse - The outgoing visit response (optional).
+     * @param responseDurationInMilliseconds - The response duration in milliseconds (optional).
      */
-    trackVisit(request: Request): void;
-    trackVisit(request: IncomingMessage): void;
+    trackVisit(request: Request, response?: Response, responseDurationInMilliseconds?: number): void;
+    trackVisit(request: IncomingMessage, 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.

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,MAAM,MAAM,CAAA;AAItC,MAAM,WAAW,OAAO;IACpB,oDAAoD;IACpD,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;;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;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAClC,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAyB1C;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBzF,OAAO,CAAC,aAAa;CAcxB"}
+{"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,oDAAoD;IACpD,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,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,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,8BAA8B,CAAC,EAAE,MAAM,GAAG,IAAI;IAChG,UAAU,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,cAAc,EAAE,8BAA8B,CAAC,EAAE,MAAM,GAAG,IAAI;IA4B9G;;;;;;;;OAQG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBzF,OAAO,CAAC,aAAa;CAcxB"}

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.3.0";
+const NODE_PACKAGE_VERSION = "1.7.0";
 /**
  * Agent types that can be controlled with robots.txt rules.
  */
@@ -31,7 +31,7 @@ class KnownAgents {
     constructor(accessToken) {
         this.accessToken = accessToken;
     }
-    trackVisit(visitRequest) {
+    trackVisit(visitRequest, visitResponse, responseDurationInMilliseconds) {
         const request = "path" in visitRequest ? visitRequest : {
             path: visitRequest.url ? new URL(visitRequest.url, "https://example.org/").pathname : "/",
             method: visitRequest.method ?? "GET",
@@ -47,7 +47,10 @@ class KnownAgents {
                 request_path: request.path,
                 request_method: request.method,
                 request_headers: this.filterHeaders(request.headers),
-                node_package_version: NODE_PACKAGE_VERSION
+                response_status_code: visitResponse?.statusCode,
+                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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knownagents/sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt",
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -1,6 +1,6 @@
-import { IncomingMessage } from "http"
+import { IncomingMessage, ServerResponse } from "http"
 
-const NODE_PACKAGE_VERSION = "1.3.0"
+const NODE_PACKAGE_VERSION = "1.7.0"
 
 export interface Request {
     /** The path of the request's URL (e.g. "/about") */
@@ -11,6 +11,11 @@ export interface Request {
     headers: Record<string, string | string[] | undefined>
 }
 
+export interface Response {
+    /** The HTTP response status code */
+    statusCode: number
+}
+
 /**
  * Agent types that can be controlled with robots.txt rules.
  */
@@ -47,10 +52,12 @@ export class KnownAgents {
      * Tracks an agent visit in Known Agents agent analytics.
      *
      * @param visitRequest - The incoming visit request.
+     * @param visitResponse - The outgoing visit response (optional).
+     * @param responseDurationInMilliseconds - The response duration in milliseconds (optional).
      */
-    trackVisit(request: Request): void
-    trackVisit(request: IncomingMessage): void
-    trackVisit(visitRequest: Request | IncomingMessage): void {
+    trackVisit(request: Request, response?: Response, responseDurationInMilliseconds?: number): void
+    trackVisit(request: IncomingMessage, response?: ServerResponse, responseDurationInMilliseconds?: number): void
+    trackVisit(visitRequest: Request | IncomingMessage, visitResponse?: Response | ServerResponse, responseDurationInMilliseconds?: number): void {
         const request: Request = "path" in visitRequest ? visitRequest : {
             path: visitRequest.url ? new URL(visitRequest.url, "https://example.org/").pathname : "/",
             method: visitRequest.method ?? "GET",
@@ -67,7 +74,10 @@ export class KnownAgents {
                 request_path: request.path,
                 request_method: request.method,
                 request_headers: this.filterHeaders(request.headers),
-                node_package_version: NODE_PACKAGE_VERSION
+                response_status_code: visitResponse?.statusCode,
+                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}`)