@knownagents/sdk 2.2.0 → 2.4.0

package/README.md

@@ -137,29 +137,56 @@ Call `identifyAgents` to identify multiple requests at once:
 ```ts
 const identifications = await knownAgents.identifyAgents([
     {
-        id: "request-1",
-        request_headers: request1.headers
+        request_id: "request-1",
+        request_headers: request1.headers,
+        request_path: request1.url
     },
     {
-        id: "request-2",
-        request_headers: request2.headers
+        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"`: 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. `"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)
+  - `"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 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;IAmB5E;;;;;;;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

@@ -221,7 +221,9 @@ class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_headers: (0, headers_1.getFilteredHeaders)(request.headers)
+                request_headers: (0, headers_1.getFilteredHeaders)(request.headers),
+                request_ip: request.socket.remoteAddress,
+                request_path: request.url
             })
         });
         if (response.ok) {
@@ -246,7 +248,7 @@ class KnownAgents {
                 "Authorization": `Bearer ${this.accessToken}`,
                 "Content-Type": "application/json"
             },
-            body: JSON.stringify(requests.map(request => {
+            body: JSON.stringify(requests.map((request) => {
                 return {
                     ...request,
                     request_headers: (0, headers_1.getFilteredHeaders)(request.request_headers),

package/dist/types.d.ts

@@ -60,35 +60,65 @@ 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;
 }
 /**
  * The result of an agent identification request.
  */
 export interface IdentificationResult {
-    /** The identifier from the request (if provided) */
-    id?: string;
+    /** The identifier from the request (if provided). */
+    request_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
+     * - "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" | "unknown_agent" | "not_verifiable";
-    /** The unique ID of the identified agent */
+    result: "verified" | "verification_failed" | "not_verifiable" | "not_identified";
+    /** The unique ID of the identified agent. */
     agent_id?: string;
-    /** The name of the identified agent (e.g. "Googlebot") */
+    /** The name of the agent (e.g. `"Claude-User"`) (if identified). */
     agent_token?: string;
-    /** The documentation URL for the identified agent */
+    /** The documentation URL of the agent (if identified). */
     agent_url?: string;
-    /** The type of the identified agent (e.g. "AI Agent", "Search Engine Crawler") */
+    /** The type of agent (e.g. `"AI Assistant"`) (if identified). */
     agent_type_name?: string;
-    /** The company behind the identified agent (e.g. "Google") */
+    /** The company operating the agent (e.g. `"Anthropic"`) (if identified). */
     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 IP address. */
+    asn?: number;
+    /** 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 IP address:
+     * - "isp"
+     * - "hosting"
+     * - "business"
+     * - "education"
+     * - "government"
+     */
+    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":"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"}
+{"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.2.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

@@ -265,7 +265,9 @@ export class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_headers: getFilteredHeaders(request.headers)
+                request_headers: getFilteredHeaders(request.headers),
+                request_ip: request.socket.remoteAddress,
+                request_path: request.url
             })
         })
 
@@ -291,7 +293,7 @@ export class KnownAgents {
                 "Authorization": `Bearer ${this.accessToken}`,
                 "Content-Type": "application/json"
             },
-            body: JSON.stringify(requests.map(request => {
+            body: JSON.stringify(requests.map((request) => {
                 return {
                     ...request,
                     request_headers: getFilteredHeaders(request.request_headers),

package/src/types.ts

@@ -64,36 +64,72 @@ 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
 }
 
 /**
  * The result of an agent identification request.
  */
 export interface IdentificationResult {
-    /** The identifier from the request (if provided) */
-    id?: string
+    /** The identifier from the request (if provided). */
+    request_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
+     * - "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" | "unknown_agent" | "not_verifiable"
-    /** The unique ID of the identified agent */
+    result: "verified" | "verification_failed" | "not_verifiable" | "not_identified"
+    /** The unique ID of the identified agent. */
     agent_id?: string
-    /** The name of the identified agent (e.g. "Googlebot") */
+    /** The name of the agent (e.g. `"Claude-User"`) (if identified). */
     agent_token?: string
-    /** The documentation URL for the identified agent */
+    /** The documentation URL of the agent (if identified). */
     agent_url?: string
-    /** The type of the identified agent (e.g. "AI Agent", "Search Engine Crawler") */
+    /** The type of agent (e.g. `"AI Assistant"`) (if identified). */
     agent_type_name?: string
-    /** The company behind the identified agent (e.g. "Google") */
+    /** The company operating the agent (e.g. `"Anthropic"`) (if identified). */
     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 IP address. */
+    asn?: number
+    /** 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 IP address:
+     * - "isp"
+     * - "hosting"
+     * - "business"
+     * - "education"
+     * - "government"
+     */
+    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"
+    >
 }
 
 /**