@knownagents/sdk 1.11.0 → 2.0.0

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
+/**
+ * ACP response details from a REST API call.
+ */
+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;
+    }[];
+}
+/**
+ * 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;
+}
+/**
+ * A normalized visit payload for the Known Agents API.
+ * Use this with `trackVisits()` when batching requests yourself.
+ */
+export interface VisitRequest {
+    /** The URL path and query string of the request (e.g. "/about?foo=bar") */
+    request_path: string;
+    /** The HTTP method (e.g. "GET", "POST") */
+    request_method: string;
+    /** The HTTP request headers. Sensitive headers are removed before sending. */
+    request_headers: IncomingHttpHeaders;
+    /** The HTTP response status code (e.g. 200, 404) */
+    response_status_code?: number;
+    /** The HTTP response headers. Sensitive headers are removed before sending. */
+    response_headers?: OutgoingHttpHeaders;
+    /** The response duration in milliseconds */
+    response_duration_in_milliseconds?: number;
+    /** The MCP JSON-RPC request method */
+    mcp_request_method?: string;
+    /** The MCP request tool name */
+    mcp_request_tool_name?: string;
+    /** The MCP request client name */
+    mcp_request_client_info_name?: string;
+    /** The MCP request client version */
+    mcp_request_client_info_version?: string;
+    /** Whether the MCP response result is an error */
+    mcp_response_result_is_error?: boolean;
+    /** The MCP response error code */
+    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 timestamp when the visit occurred (ISO 8601 format) */
+    created?: string;
+}
+/**
+ * An agent identification request for the Known Agents API.
+ * Used for batch agent identification with `identifyAgents()`.
+ */
+export interface IdentificationRequest {
+    /** An identifier that will be echoed back in the response to match requests with results */
+    id?: string;
+    /** The HTTP request headers. Sensitive headers are removed before sending. */
+    request_headers: IncomingHttpHeaders;
+}
+/**
+ * The result of an agent identification request.
+ */
+export interface IdentificationResult {
+    /** The identifier from the request (if provided) */
+    id?: string;
+    /**
+     * The identification result:
+     * - "verified": The agent was identified and verified
+     * - "verification_failed": The agent was identified but failed verification (spoofed)
+     * - "unknown_agent": The request is from an unrecognized agent or human
+     * - "not_verifiable": The agent was identified but cannot be verified
+     */
+    result: "verified" | "verification_failed" | "unknown_agent" | "not_verifiable";
+    /** The unique ID of the identified agent */
+    agent_id?: string;
+    /** The name of the identified agent (e.g. "Googlebot") */
+    agent_token?: string;
+    /** The documentation URL for the identified agent */
+    agent_url?: string;
+    /** The type of the identified agent (e.g. "AI Agent", "Search Engine Crawler") */
+    agent_type_name?: string;
+    /** The company behind the identified agent (e.g. "Google") */
+    operator_name?: string;
+}
+/**
+ * Agent types that can be controlled with robots.txt rules.
+ */
+export declare enum AgentType {
+    AIAgent = "AI Agent",
+    AIAssistant = "AI Assistant",
+    AICodingAgent = "AI Coding Agent",
+    AIDataProvider = "AI Data Provider",
+    AIDataScraper = "AI Data Scraper",
+    AISearchCrawler = "AI Search Crawler",
+    Archiver = "Archiver",
+    AutomatedAgent = "Automated Agent",
+    DeveloperHelper = "Developer Helper",
+    Fetcher = "Fetcher",
+    IntelligenceGatherer = "Intelligence Gatherer",
+    Scraper = "Scraper",
+    SEOCrawler = "SEO Crawler",
+    SearchEngineCrawler = "Search Engine Crawler",
+    SecurityScanner = "Security Scanner",
+    UndocumentedAIAgent = "Undocumented AI Agent"
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentType = void 0;
+/**
+ * Agent types that can be controlled with robots.txt rules.
+ */
+var AgentType;
+(function (AgentType) {
+    AgentType["AIAgent"] = "AI Agent";
+    AgentType["AIAssistant"] = "AI Assistant";
+    AgentType["AICodingAgent"] = "AI Coding Agent";
+    AgentType["AIDataProvider"] = "AI Data Provider";
+    AgentType["AIDataScraper"] = "AI Data Scraper";
+    AgentType["AISearchCrawler"] = "AI Search Crawler";
+    AgentType["Archiver"] = "Archiver";
+    AgentType["AutomatedAgent"] = "Automated Agent";
+    AgentType["DeveloperHelper"] = "Developer Helper";
+    AgentType["Fetcher"] = "Fetcher";
+    AgentType["IntelligenceGatherer"] = "Intelligence Gatherer";
+    AgentType["Scraper"] = "Scraper";
+    AgentType["SEOCrawler"] = "SEO Crawler";
+    AgentType["SearchEngineCrawler"] = "Search Engine Crawler";
+    AgentType["SecurityScanner"] = "Security Scanner";
+    AgentType["UndocumentedAIAgent"] = "Undocumented AI Agent";
+})(AgentType || (exports.AgentType = AgentType = {}));

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@knownagents/sdk",
-  "version": "1.11.0",
+  "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",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "keywords": [
     "ai analytics",
     "bot traffic",
@@ -16,6 +20,12 @@
     "bot detection",
     "crawler detection",
     "llm analytics",
+    "mcp analytics",
+    "mcp server analytics",
+    "model context protocol",
+    "agentic commerce protocol",
+    "universal commerce protocol",
+    "commerce analytics",
     "robots.txt",
     "automatic robots.txt",
     "robots.txt generator",
@@ -54,5 +64,8 @@
   "devDependencies": {
     "@types/node": "^22.19.17",
     "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
   }
 }

package/src/KnownAgents.ts

@@ -0,0 +1,324 @@
+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 { getIsPathExcluded } from "./paths"
+import type {
+    AgentType,
+    IdentificationRequest,
+    IdentificationResult,
+    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
+    }
+}
+
+/**
+ * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
+ */
+export class KnownAgents {
+    private readonly accessToken: string
+
+    /**
+     * Creates a new instance of the Known Agents client.
+     * 
+     * @param accessToken - Your project's access token.
+     */
+    constructor(accessToken: string) {
+        this.accessToken = accessToken
+    }
+
+    /**
+     * 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.
+     *
+     * @param request - The incoming Node.js HTTP request.
+     * @param response - The outgoing Node.js HTTP response.
+     * @param options - Optional ACP or UCP response metadata for REST API calls.
+     */
+    trackPageviewOrRESTCall(request: IncomingMessage, response: ServerResponse, options?: TrackPageviewOrRESTCallOptions): void {
+        const isMCPCall = getIsMCPCall(request.headers)
+        const path = request.url
+        const method = request.method
+
+        if (isMCPCall || !path || getIsPathExcluded(path) || !method) {
+            return
+        }
+
+        const created = new Date()
+
+        const sendVisit = () => {
+            const responseDurationInMilliseconds = Date.now() - created.getTime()
+
+            const visitRequest: VisitRequest = {
+                request_path: path,
+                request_method: method,
+                request_headers: request.headers,
+                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,
+                created: created.toISOString()
+            }
+
+            this.trackVisits([visitRequest])
+        }
+
+        if (response.writableEnded) {
+            sendVisit()
+        } else {
+            response.once("finish", sendVisit)
+        }
+    }
+
+    /**
+     * 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.
+     *
+     * @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) {
+            return
+        }
+
+        const created = new Date()
+
+        let mcpRequestBody: MCPRequestBody | undefined
+        let mcpResponseBody: MCPResponseBody | undefined
+
+        const originalTransportOnMessage = transport.onmessage
+        transport.onmessage = (message, extra): void => {
+            mcpRequestBody = message as MCPRequestBody
+            originalTransportOnMessage?.(message, extra)
+        }
+    
+        const originalTransportSend = transport.send
+        transport.send = async (message, options): Promise<void> => {
+            mcpResponseBody = message as MCPResponseBody
+            await originalTransportSend.call(transport, message, options)
+        }
+
+        const restoreTransport = () => {
+            transport.onmessage = originalTransportOnMessage
+            transport.send = originalTransportSend
+        }
+
+        const sendVisit = () => {
+            restoreTransport()
+
+            if (!mcpRequestBody || !mcpResponseBody) {
+                return
+            }
+
+            const responseDurationInMilliseconds = Date.now() - created.getTime()
+
+            const visitRequest: VisitRequest = {
+                request_path: path,
+                request_method: method,
+                request_headers: request.headers,
+                response_status_code: response?.statusCode,
+                response_headers: response.getHeaders(),
+                response_duration_in_milliseconds: responseDurationInMilliseconds,
+                mcp_request_method: mcpRequestBody.method,
+                mcp_request_tool_name: mcpRequestBody.params?.name,
+                mcp_request_client_info_name: mcpRequestBody.params?.clientInfo?.name,
+                mcp_request_client_info_version: mcpRequestBody.params?.clientInfo?.version,
+                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),
+                created: created.toISOString()
+            }
+
+            this.trackVisits([visitRequest])
+        }
+
+        if (response.writableEnded) {
+            sendVisit()
+        } else {
+            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).
+     *
+     * @param requests - An array of visits.
+     */
+    trackVisits(requests: VisitRequest[]): void {
+        const filteredRequests = requests
+            .filter((request) => {
+                return !getIsPathExcluded(request.request_path)
+            })
+            .map((request) => {
+                return {
+                    ...request,
+                    request_headers: getFilteredHeaders(request.request_headers),
+                    response_headers: request.response_headers ? getFilteredHeaders(request.response_headers) : undefined,
+                }
+            })
+
+        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}`)
+        })
+    }
+    
+    /**
+     * Generates a robots.txt file that disallows the specified agent types.
+     * The generated file stays up-to-date with all current and future agents in the specified categories.
+     * Cache and serve the result at your website's `/robots.txt` endpoint.
+     *
+     * @param agentTypes - An array of agent types to disallow.
+     * @param disallow - The path to disallow (default: "/" for all paths).
+     * @returns A promise that resolves to the generated robots.txt content as a string.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async generateRobotsTXT(agentTypes: AgentType[], disallow: string = "/"): Promise<string> {
+        const response = await fetch("https://api.knownagents.com/robots-txts", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                agent_types: agentTypes,
+                disallow: disallow
+            })
+        })
+
+        if (response.ok) {
+            return await response.text()
+        } else {
+            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.
+     *
+     * @param request - The incoming Node.js HTTP request.
+     * @returns A promise that resolves to the identification result.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgent(request: IncomingMessage): Promise<IdentificationResult> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                request_headers: getFilteredHeaders(request.headers)
+            })
+        })
+
+        if (response.ok) {
+            return await response.json()
+        } else {
+            throw new Error(`Known Agents failed to identify agent: ${response.status} ${response.statusText}`)
+        }
+    }
+
+    /**
+     * Identifies and verifies multiple agents from HTTP requests in a batch.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param requests - An array of identification requests.
+     * @returns A promise that resolves to an array of identification results.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(requests.map(request => {
+                return {
+                    ...request,
+                    request_headers: getFilteredHeaders(request.request_headers),
+                }
+            }))
+        })
+
+        if (response.ok) {
+            return await response.json()
+        } else {
+            throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`)
+        }
+    }
+
+}

package/src/commerce.ts

@@ -0,0 +1,68 @@
+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
+}

package/src/headers.ts

@@ -0,0 +1,56 @@
+import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http"
+
+const filteredHeaderNames = [
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-access-token",
+    "x-id-token",
+    "x-refresh-token",
+    "x-session-token",
+    "session-token",
+    "csrf-token",
+    "x-csrf-token",
+    "xsrf-token",
+    "x-xsrf-token",
+    "x-amz-security-token",
+    "x-goog-api-key",
+    "x-client-secret",
+    "client-secret",
+    "private-token"
+]
+
+export function getFilteredHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers {
+    const filteredHeaders = { ...headers }
+
+    Object.keys(filteredHeaders).forEach((key) => {
+        if (filteredHeaderNames.includes(key.toLowerCase())) {
+            delete filteredHeaders[key]
+        }
+    })
+
+    return filteredHeaders
+}
+
+export function getIsMCPCall(headers: IncomingHttpHeaders): boolean {
+    return Object.keys(headers).some((key) => {
+        return key.toLowerCase() === "mcp-protocol-version"
+    })
+}
+
+export function getIsUCPCall(headers: IncomingHttpHeaders): boolean {
+    return Object.keys(headers).some((key) => {
+        return key.toLowerCase() === "ucp-agent"
+    })
+}
+
+export function getIsProbablyACPCall(headers: IncomingHttpHeaders): boolean {
+    return Object.keys(headers).some((key) => {
+        return key.toLowerCase() === "api-version"
+    })
+}