@knownagents/sdk 2.3.0 → 2.4.0

package/README.md

@@ -137,41 +137,56 @@ Call `identifyAgents` to identify multiple requests at once:
 ```ts
 const identifications = await knownAgents.identifyAgents([
     {
-        id: "request-1",
+        request_id: "request-1",
         request_headers: request1.headers,
         request_path: request1.url
     },
     {
-        id: "request-2",
+        request_id: "request-2",
         request_headers: request2.headers,
         request_path: request2.url
     }
 ])
 ```
 
+Identification requests accept the following fields:
+
+- `request_id`: A string identifier that will be echoed back in the response. Include this when sending an array to match each result to its request.
+- `request_headers` (required): An object containing all available HTTP request headers, including `user-agent` when present, any IP-related headers like `x-forwarded-for` or `x-real-ip`, and HTTP message signature headers like `signature-input`, `signature`, and `signature-agent`.
+- `request_ip`: The transport-level IP address of the incoming request. Used as a fallback when a valid client IP address cannot be derived from `request_headers`.
+- `request_path`: The path of the incoming request (e.g. `"/products/123"`).
+
 These methods return an object (or array of objects) with the following fields:
 
-- `id`: The identifier from the request (if provided).
+- `request_id`: The identifier from the request (if provided).
 - `result`: The identification result:
-  - `"verified"`: A known agent was identified and verified
-  - `"verification_failed"`: A known agent was identified, but failed verification
-  - `"not_verifiable"`: A known agent was identified, but no verification method was available
-  - `"not_identified"`: No known agent was identified
+  - `"verified"`: A known agent was identified and verified (its identity was confirmed as authentic)
+  - `"verification_failed"`: A known agent was identified, but failed verification (its identity may have been spoofed)
+  - `"not_verifiable"`: A known agent was identified, but its operator does not provide a known verification method
+  - `"not_identified"`: No known agent was identified (the request may have come from a human)
 - `agent_id`: The unique ID of the identified agent.
 - `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 Assistant"`) (if identified).
 - `operator_name`: The company operating the agent (e.g. `"Anthropic"`) (if identified).
 - `is_disallowed_by_robots_txt`: Whether the identified agent is disallowed by robots.txt from accessing the `request_path`.
-- `asn`: The autonomous system number associated with the request's IPv4 address.
-- `asn_operator`: The operator of the recognized autonomous system associated with the request's IPv4 address.
-- `asn_type`: The type of the recognized autonomous system associated with the request's IPv4 address:
+- `asn`: The autonomous system number associated with the request's IP address.
+- `asn_operator`: The operator of the recognized autonomous system associated with the request's IP address.
+- `asn_type`: The type of the recognized autonomous system associated with the request's IP address:
   - `"isp"`
   - `"hosting"`
   - `"business"`
   - `"education"`
   - `"government"`
 - `automation_score`: An integer from `0` to `99` indicating the strength of heuristic evidence that the request was made by an automated client. Higher scores indicate stronger detected automation signals. A score of `0` means that no automation signals were detected, not that the client is certainly human.
+- `automation_signals`: Specific automation signals detected for the request. Available to Enterprise plans upon request:
+  - `"known_agent_ip"`: The request came from an IP address associated with a known agent, although no specific agent was identified
+  - `"inconsistency"`: The request contained inconsistent client or browser attributes
+  - `"non_browser"`: The request appears to have been made by a non-browser HTTP client
+  - `"automated_browser"`: The request contains indicators of browser automation
+  - `"cloud_service_provider"`: The request came from cloud or hosting infrastructure
+
+See the [Agent Identification REST API documentation](https://knownagents.com/docs/identification/rest-api) for the canonical API reference.
 
 ## Requirements
 

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;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;IAoB5E;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAsBxF,OAAO,CAAC,aAAa;YAaP,UAAU;CAmB3B"}
+{"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;IAqB5E;;;;;;;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

@@ -222,6 +222,7 @@ class KnownAgents {
             },
             body: JSON.stringify({
                 request_headers: (0, headers_1.getFilteredHeaders)(request.headers),
+                request_ip: request.socket.remoteAddress,
                 request_path: request.url
             })
         });

package/dist/types.d.ts

@@ -60,10 +60,12 @@ export interface VisitRequest {
  * 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. Sensitive headers are removed before sending. */
+    /** A string identifier that will be echoed back in the response. Include this when sending an array to match each result to its request. */
+    request_id?: string;
+    /** An object containing all available HTTP request headers, including `user-agent` when present, any IP-related headers like `x-forwarded-for` or `x-real-ip`, and HTTP message signature headers like `signature-input`, `signature`, and `signature-agent`. */
     request_headers: IncomingHttpHeaders;
+    /** The transport-level IP address of the incoming request. Used as a fallback when a valid client IP address cannot be derived from `request_headers`. */
+    request_ip?: string;
     /** The path of the incoming request (e.g. `"/products/123"`). */
     request_path?: string;
 }
@@ -72,13 +74,13 @@ export interface IdentificationRequest {
  */
 export interface IdentificationResult {
     /** The identifier from the request (if provided). */
-    id?: string;
+    request_id?: string;
     /**
      * The identification result:
-     * - "verified": A known agent was identified and verified
-     * - "verification_failed": A known agent was identified, but failed verification
-     * - "not_verifiable": A known agent was identified, but no verification method was available
-     * - "not_identified": No known agent was identified
+     * - "verified": A known agent was identified and verified (its identity was confirmed as authentic)
+     * - "verification_failed": A known agent was identified, but failed verification (its identity may have been spoofed)
+     * - "not_verifiable": A known agent was identified, but its operator does not provide a known verification method
+     * - "not_identified": No known agent was identified (the request may have come from a human)
      */
     result: "verified" | "verification_failed" | "not_verifiable" | "not_identified";
     /** The unique ID of the identified agent. */
@@ -93,12 +95,12 @@ export interface IdentificationResult {
     operator_name?: string;
     /** Whether the identified agent is disallowed by robots.txt from accessing the `request_path`. */
     is_disallowed_by_robots_txt?: boolean;
-    /** The autonomous system number associated with the request's IPv4 address. */
+    /** The autonomous system number associated with the request's IP address. */
     asn?: number;
-    /** The operator of the recognized autonomous system associated with the request's IPv4 address. */
+    /** The operator of the recognized autonomous system associated with the request's IP address. */
     asn_operator?: string;
     /**
-     * The type of the recognized autonomous system associated with the request's IPv4 address:
+     * The type of the recognized autonomous system associated with the request's IP address:
      * - "isp"
      * - "hosting"
      * - "business"
@@ -108,6 +110,15 @@ export interface IdentificationResult {
     asn_type?: "isp" | "hosting" | "business" | "education" | "government";
     /** An integer from `0` to `99` indicating the strength of heuristic evidence that the request was made by an automated client. Higher scores indicate stronger detected automation signals. A score of `0` means that no automation signals were detected, not that the client is certainly human. */
     automation_score?: number;
+    /**
+     * Specific automation signals detected for the request. Available to Enterprise plans upon request:
+     * - "known_agent_ip": The request came from an IP address associated with a known agent, although no specific agent was identified
+     * - "inconsistency": The request contained inconsistent client or browser attributes
+     * - "non_browser": The request appears to have been made by a non-browser HTTP client
+     * - "automated_browser": The request contains indicators of browser automation
+     * - "cloud_service_provider": The request came from cloud or hosting infrastructure
+     */
+    automation_signals?: Array<"known_agent_ip" | "inconsistency" | "non_browser" | "automated_browser" | "cloud_service_provider">;
 }
 /**
  * Agent types that can be controlled with robots.txt rules.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knownagents/sdk",
-  "version": "2.3.0",
+  "version": "2.4.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"

package/src/KnownAgents.ts

@@ -266,6 +266,7 @@ export class KnownAgents {
             },
             body: JSON.stringify({
                 request_headers: getFilteredHeaders(request.headers),
+                request_ip: request.socket.remoteAddress,
                 request_path: request.url
             })
         })

package/src/types.ts

@@ -64,10 +64,12 @@ export interface VisitRequest {
  * 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. Sensitive headers are removed before sending. */
+    /** A string identifier that will be echoed back in the response. Include this when sending an array to match each result to its request. */
+    request_id?: string
+    /** An object containing all available HTTP request headers, including `user-agent` when present, any IP-related headers like `x-forwarded-for` or `x-real-ip`, and HTTP message signature headers like `signature-input`, `signature`, and `signature-agent`. */
     request_headers: IncomingHttpHeaders
+    /** The transport-level IP address of the incoming request. Used as a fallback when a valid client IP address cannot be derived from `request_headers`. */
+    request_ip?: string
     /** The path of the incoming request (e.g. `"/products/123"`). */
     request_path?: string
 }
@@ -77,13 +79,13 @@ export interface IdentificationRequest {
  */
 export interface IdentificationResult {
     /** The identifier from the request (if provided). */
-    id?: string
+    request_id?: string
     /**
      * The identification result:
-     * - "verified": A known agent was identified and verified
-     * - "verification_failed": A known agent was identified, but failed verification
-     * - "not_verifiable": A known agent was identified, but no verification method was available
-     * - "not_identified": No known agent was identified
+     * - "verified": A known agent was identified and verified (its identity was confirmed as authentic)
+     * - "verification_failed": A known agent was identified, but failed verification (its identity may have been spoofed)
+     * - "not_verifiable": A known agent was identified, but its operator does not provide a known verification method
+     * - "not_identified": No known agent was identified (the request may have come from a human)
      */
     result: "verified" | "verification_failed" | "not_verifiable" | "not_identified"
     /** The unique ID of the identified agent. */
@@ -98,12 +100,12 @@ export interface IdentificationResult {
     operator_name?: string
     /** Whether the identified agent is disallowed by robots.txt from accessing the `request_path`. */
     is_disallowed_by_robots_txt?: boolean
-    /** The autonomous system number associated with the request's IPv4 address. */
+    /** The autonomous system number associated with the request's IP address. */
     asn?: number
-    /** The operator of the recognized autonomous system associated with the request's IPv4 address. */
+    /** The operator of the recognized autonomous system associated with the request's IP address. */
     asn_operator?: string
     /**
-     * The type of the recognized autonomous system associated with the request's IPv4 address:
+     * The type of the recognized autonomous system associated with the request's IP address:
      * - "isp"
      * - "hosting"
      * - "business"
@@ -113,6 +115,21 @@ export interface IdentificationResult {
     asn_type?: "isp" | "hosting" | "business" | "education" | "government"
     /** An integer from `0` to `99` indicating the strength of heuristic evidence that the request was made by an automated client. Higher scores indicate stronger detected automation signals. A score of `0` means that no automation signals were detected, not that the client is certainly human. */
     automation_score?: number
+    /**
+     * Specific automation signals detected for the request. Available to Enterprise plans upon request:
+     * - "known_agent_ip": The request came from an IP address associated with a known agent, although no specific agent was identified
+     * - "inconsistency": The request contained inconsistent client or browser attributes
+     * - "non_browser": The request appears to have been made by a non-browser HTTP client
+     * - "automated_browser": The request contains indicators of browser automation
+     * - "cloud_service_provider": The request came from cloud or hosting infrastructure
+     */
+    automation_signals?: Array<
+        "known_agent_ip"
+        | "inconsistency"
+        | "non_browser"
+        | "automated_browser"
+        | "cloud_service_provider"
+    >
 }
 
 /**