@metrone-io/server 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -4,7 +4,12 @@
  * These types mirror the Worker's RawEventPayload exactly so payloads pass
  * validation on the ingestion side without translation.
  */
-type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing';
+/**
+ * Canonical source values. Mirrors the analytics_events.source CHECK
+ * constraint (expanded in v1.1 by migration _069).
+ * v1.1 SPEC-01 adds: campaign, social, review, ad, agent_action.
+ */
+type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing' | 'campaign' | 'social' | 'review' | 'ad' | 'agent_action';
 interface MetroneServerConfig {
     /** API key (required). Format: metrone_live_* or metrone_test_* */
     apiKey: string;
@@ -52,6 +57,13 @@ interface EventPayload {
     agent_type?: string;
     /** Idempotency key to prevent duplicate processing */
     idempotency_key?: string;
+    /**
+     * Original visitor User-Agent, for middleware/edge senders forwarding
+     * traffic they observed. The worker parses it for device and visitor
+     * classification (human vs ai_agent vs bot) and then discards it — the
+     * raw UA is never stored. Without it, the ingest request's own UA is used.
+     */
+    user_agent?: string;
     properties?: Record<string, unknown>;
     timestamp?: string;
 }
@@ -271,6 +283,67 @@ declare class MetroneServer {
      * Track an AI session lifecycle event (start, end, timeout).
      */
     trackAISession(data: AISessionData): void;
+    /**
+     * Track a campaign lifecycle event (email / SMS sends, opens, clicks…).
+     * Recommended event_type values: email_sent | email_delivered |
+     * email_opened | email_clicked | email_bounced | email_unsubscribed |
+     * sms_sent | sms_delivered | sms_replied | sms_opt_out
+     */
+    trackCampaignEvent(data: {
+        event_type: string;
+        campaign_id: string;
+        recipient_id_hash: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a social media event. Recommended event_type values:
+     * post_published | impression | engagement | click | share
+     */
+    trackSocialEvent(data: {
+        event_type: string;
+        platform: string;
+        post_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a review event. Recommended event_type values: received | responded
+     */
+    trackReviewEvent(data: {
+        event_type: string;
+        platform: string;
+        review_id: string;
+        rating: number;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a paid-ad metrics event. Recommended event_type values:
+     * impression | click | spend_daily | conversion
+     */
+    trackAdEvent(data: {
+        event_type: string;
+        platform: string;
+        campaign_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track an SMS conversation event. Recommended event_type values:
+     * received | replied. agent_id is promoted to the top-level column so
+     * existing per-agent dashboard breakdowns keep working.
+     */
+    trackSmsEvent(data: {
+        event_type: string;
+        agent_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track an autonomous agent action (audit-log style). event_type is the
+     * action itself (free-form vocabulary). agent_type / agent_id are written
+     * BOTH to the top-level columns (for existing dashboard breakdowns) AND
+     * into properties (for the JSONB-first get_agent_activity_feed RPC) —
+     * decision B4 of the v1.1 build.
+     */
+    trackAgentAction(data: {
+        agent_type: string;
+        action_taken: string;
+        agent_id?: string;
+        target?: string;
+        outcome?: string;
+    } & Record<string, unknown>): void;
     /**
      * Get aggregated analytics stats for a time period.
      */
@@ -309,6 +382,98 @@ declare class MetroneServer {
     private buildDateParams;
 }
 
+/**
+ * agent-tracker.ts — server-side capture of AI agent traffic.
+ *
+ * AI agents (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot, …) fetch pages
+ * without executing JavaScript, so the browser tracker never sees them. This
+ * module runs where the request is actually served — an Express/Connect
+ * middleware, a fetch-style handler wrapper, or a manual call — and forwards
+ * matched requests to Metrone with the original User-Agent in the
+ * `user_agent` payload field. The ingestion worker performs the
+ * authoritative classification (visitor_type = 'ai_agent') and the raw UA
+ * is never stored.
+ *
+ * Only requests whose UA matches the AI-agent list are forwarded — normal
+ * human traffic is never sent from here (the browser tracker handles it),
+ * so this adds zero overhead and zero quota usage for regular visitors.
+ *
+ * Keep the UA list in sync with AI_AGENT_RULES in
+ * packages/worker/src/lib/device-parser.ts (the authoritative matcher).
+ */
+
+/**
+ * Returns the canonical AI agent name for a User-Agent, or undefined when
+ * the UA does not belong to a known AI agent.
+ */
+declare function matchAiAgent(userAgent: string | null | undefined): string | undefined;
+interface AgentHit {
+    /** Full request URL (or at minimum a path). */
+    url: string;
+    /** The visitor's User-Agent header. */
+    userAgent: string | null | undefined;
+    /** Optional Referer header. */
+    referrer?: string | null;
+    /** HTTP method — non-GET/HEAD requests are skipped. Defaults to 'GET'. */
+    method?: string;
+}
+interface AgentTrackerOptions {
+    /**
+     * Skip requests for static assets (css/js/images/fonts/…). Default: true.
+     */
+    skipStaticAssets?: boolean;
+    /**
+     * Extra paths to ignore (exact match or prefix ending with '*'),
+     * e.g. ['/health', '/api/*'].
+     */
+    ignorePaths?: string[];
+}
+/**
+ * Core capture: if the request comes from a known AI agent, forward it to
+ * Metrone as a pageview with the original UA. Fire-and-forget — never
+ * throws, never blocks the response.
+ *
+ * Returns the matched agent name, or undefined when the request was not an
+ * AI agent (or was filtered out).
+ *
+ * Serverless note: the SDK batches by default; in short-lived environments
+ * construct the client with `batchSize: 0` so hits are sent immediately.
+ */
+declare function captureAgentHit(metrone: MetroneServer, hit: AgentHit, options?: AgentTrackerOptions): string | undefined;
+/**
+ * Express / Connect middleware. Mount early, before routing:
+ *
+ * ```ts
+ * import { MetroneServer, agentMiddleware } from '@metrone-io/server'
+ *
+ * const metrone = new MetroneServer({ apiKey: process.env.METRONE_API_KEY! })
+ * app.use(agentMiddleware(metrone))
+ * ```
+ */
+declare function agentMiddleware(metrone: MetroneServer, options?: AgentTrackerOptions): (req: {
+    method?: string;
+    originalUrl?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    get?: (name: string) => string | undefined;
+}, _res: unknown, next: (err?: unknown) => void) => void;
+/**
+ * WHATWG-fetch helper for Hono, Next.js middleware/route handlers, Bun,
+ * Deno, and Cloudflare Workers:
+ *
+ * ```ts
+ * trackAgentRequest(metrone, request)
+ * ```
+ */
+declare function trackAgentRequest(metrone: MetroneServer, request: {
+    url: string;
+    method?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, options?: AgentTrackerOptions): string | undefined;
+
 /**
  * Structured error types for the Metrone server SDK.
  *
@@ -354,4 +519,4 @@ declare class MetroneServerError extends MetroneError {
     constructor(status: number, message?: string);
 }
 
-export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse };
+export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type AgentHit, type AgentTrackerOptions, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse, agentMiddleware, captureAgentHit, matchAiAgent, trackAgentRequest };

package/dist/index.d.ts

@@ -4,7 +4,12 @@
  * These types mirror the Worker's RawEventPayload exactly so payloads pass
  * validation on the ingestion side without translation.
  */
-type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing';
+/**
+ * Canonical source values. Mirrors the analytics_events.source CHECK
+ * constraint (expanded in v1.1 by migration _069).
+ * v1.1 SPEC-01 adds: campaign, social, review, ad, agent_action.
+ */
+type EventSource = 'web' | 'voice' | 'chat' | 'assistant' | 'sms' | 'listing' | 'campaign' | 'social' | 'review' | 'ad' | 'agent_action';
 interface MetroneServerConfig {
     /** API key (required). Format: metrone_live_* or metrone_test_* */
     apiKey: string;
@@ -52,6 +57,13 @@ interface EventPayload {
     agent_type?: string;
     /** Idempotency key to prevent duplicate processing */
     idempotency_key?: string;
+    /**
+     * Original visitor User-Agent, for middleware/edge senders forwarding
+     * traffic they observed. The worker parses it for device and visitor
+     * classification (human vs ai_agent vs bot) and then discards it — the
+     * raw UA is never stored. Without it, the ingest request's own UA is used.
+     */
+    user_agent?: string;
     properties?: Record<string, unknown>;
     timestamp?: string;
 }
@@ -271,6 +283,67 @@ declare class MetroneServer {
      * Track an AI session lifecycle event (start, end, timeout).
      */
     trackAISession(data: AISessionData): void;
+    /**
+     * Track a campaign lifecycle event (email / SMS sends, opens, clicks…).
+     * Recommended event_type values: email_sent | email_delivered |
+     * email_opened | email_clicked | email_bounced | email_unsubscribed |
+     * sms_sent | sms_delivered | sms_replied | sms_opt_out
+     */
+    trackCampaignEvent(data: {
+        event_type: string;
+        campaign_id: string;
+        recipient_id_hash: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a social media event. Recommended event_type values:
+     * post_published | impression | engagement | click | share
+     */
+    trackSocialEvent(data: {
+        event_type: string;
+        platform: string;
+        post_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a review event. Recommended event_type values: received | responded
+     */
+    trackReviewEvent(data: {
+        event_type: string;
+        platform: string;
+        review_id: string;
+        rating: number;
+    } & Record<string, unknown>): void;
+    /**
+     * Track a paid-ad metrics event. Recommended event_type values:
+     * impression | click | spend_daily | conversion
+     */
+    trackAdEvent(data: {
+        event_type: string;
+        platform: string;
+        campaign_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track an SMS conversation event. Recommended event_type values:
+     * received | replied. agent_id is promoted to the top-level column so
+     * existing per-agent dashboard breakdowns keep working.
+     */
+    trackSmsEvent(data: {
+        event_type: string;
+        agent_id: string;
+    } & Record<string, unknown>): void;
+    /**
+     * Track an autonomous agent action (audit-log style). event_type is the
+     * action itself (free-form vocabulary). agent_type / agent_id are written
+     * BOTH to the top-level columns (for existing dashboard breakdowns) AND
+     * into properties (for the JSONB-first get_agent_activity_feed RPC) —
+     * decision B4 of the v1.1 build.
+     */
+    trackAgentAction(data: {
+        agent_type: string;
+        action_taken: string;
+        agent_id?: string;
+        target?: string;
+        outcome?: string;
+    } & Record<string, unknown>): void;
     /**
      * Get aggregated analytics stats for a time period.
      */
@@ -309,6 +382,98 @@ declare class MetroneServer {
     private buildDateParams;
 }
 
+/**
+ * agent-tracker.ts — server-side capture of AI agent traffic.
+ *
+ * AI agents (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot, …) fetch pages
+ * without executing JavaScript, so the browser tracker never sees them. This
+ * module runs where the request is actually served — an Express/Connect
+ * middleware, a fetch-style handler wrapper, or a manual call — and forwards
+ * matched requests to Metrone with the original User-Agent in the
+ * `user_agent` payload field. The ingestion worker performs the
+ * authoritative classification (visitor_type = 'ai_agent') and the raw UA
+ * is never stored.
+ *
+ * Only requests whose UA matches the AI-agent list are forwarded — normal
+ * human traffic is never sent from here (the browser tracker handles it),
+ * so this adds zero overhead and zero quota usage for regular visitors.
+ *
+ * Keep the UA list in sync with AI_AGENT_RULES in
+ * packages/worker/src/lib/device-parser.ts (the authoritative matcher).
+ */
+
+/**
+ * Returns the canonical AI agent name for a User-Agent, or undefined when
+ * the UA does not belong to a known AI agent.
+ */
+declare function matchAiAgent(userAgent: string | null | undefined): string | undefined;
+interface AgentHit {
+    /** Full request URL (or at minimum a path). */
+    url: string;
+    /** The visitor's User-Agent header. */
+    userAgent: string | null | undefined;
+    /** Optional Referer header. */
+    referrer?: string | null;
+    /** HTTP method — non-GET/HEAD requests are skipped. Defaults to 'GET'. */
+    method?: string;
+}
+interface AgentTrackerOptions {
+    /**
+     * Skip requests for static assets (css/js/images/fonts/…). Default: true.
+     */
+    skipStaticAssets?: boolean;
+    /**
+     * Extra paths to ignore (exact match or prefix ending with '*'),
+     * e.g. ['/health', '/api/*'].
+     */
+    ignorePaths?: string[];
+}
+/**
+ * Core capture: if the request comes from a known AI agent, forward it to
+ * Metrone as a pageview with the original UA. Fire-and-forget — never
+ * throws, never blocks the response.
+ *
+ * Returns the matched agent name, or undefined when the request was not an
+ * AI agent (or was filtered out).
+ *
+ * Serverless note: the SDK batches by default; in short-lived environments
+ * construct the client with `batchSize: 0` so hits are sent immediately.
+ */
+declare function captureAgentHit(metrone: MetroneServer, hit: AgentHit, options?: AgentTrackerOptions): string | undefined;
+/**
+ * Express / Connect middleware. Mount early, before routing:
+ *
+ * ```ts
+ * import { MetroneServer, agentMiddleware } from '@metrone-io/server'
+ *
+ * const metrone = new MetroneServer({ apiKey: process.env.METRONE_API_KEY! })
+ * app.use(agentMiddleware(metrone))
+ * ```
+ */
+declare function agentMiddleware(metrone: MetroneServer, options?: AgentTrackerOptions): (req: {
+    method?: string;
+    originalUrl?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    get?: (name: string) => string | undefined;
+}, _res: unknown, next: (err?: unknown) => void) => void;
+/**
+ * WHATWG-fetch helper for Hono, Next.js middleware/route handlers, Bun,
+ * Deno, and Cloudflare Workers:
+ *
+ * ```ts
+ * trackAgentRequest(metrone, request)
+ * ```
+ */
+declare function trackAgentRequest(metrone: MetroneServer, request: {
+    url: string;
+    method?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, options?: AgentTrackerOptions): string | undefined;
+
 /**
  * Structured error types for the Metrone server SDK.
  *
@@ -354,4 +519,4 @@ declare class MetroneServerError extends MetroneError {
     constructor(status: number, message?: string);
 }
 
-export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse };
+export { type AICallData, type AIChatData, type AIIntentData, type AISessionData, type AgentHit, type AgentTrackerOptions, type ApiError, type ApiResponse, type ChannelRow, type ConversionData, type EventPayload, type EventRow, type EventSource, type EventsParams, type EventsResponse, type FlushResult, type LiveResponse, MetroneAuthError, MetroneConfigError, MetroneError, MetroneNetworkError, MetroneQuotaError, MetroneRateLimitError, MetroneServer, type MetroneServerConfig, MetroneServerError, MetroneTimeoutError, MetroneValidationError, type PageRow, type PagesParams, type PagesResponse, type ReferrerRow, type SourcesParams, type SourcesResponse, type StatsParams, type StatsResponse, agentMiddleware, captureAgentHit, matchAiAgent, trackAgentRequest };

package/dist/index.js

@@ -64,6 +64,12 @@ var MetroneServerError = class extends MetroneError {
     this.name = "MetroneServerError";
   }
 };
+var MetroneClientError = class extends MetroneError {
+  constructor(status, message = "Request rejected by server") {
+    super("CLIENT_ERROR", message, status, false);
+    this.name = "MetroneClientError";
+  }
+};
 
 // src/http.ts
 async function httpPost(config, path, body, headers) {
@@ -86,7 +92,7 @@ async function httpRequest(config, method, path, body, extraHeaders) {
   const fetchFn = config.fetch;
   const headers = {
     "X-Api-Key": config.apiKey,
-    "User-Agent": "metrone-server-sdk/1.0.0",
+    "User-Agent": "metrone-server-sdk/1.0.2",
     ...extraHeaders
   };
   if (body !== void 0) {
@@ -120,6 +126,9 @@ async function httpRequest(config, method, path, body, extraHeaders) {
       throw new MetroneRateLimitError(retryMs);
     }
     if (response.status >= 500) throw new MetroneServerError(response.status, errMsg);
+    if (response.status >= 400 && response.status < 500) {
+      throw new MetroneClientError(response.status, errMsg);
+    }
     return {
       ok: false,
       status: response.status,
@@ -130,6 +139,7 @@ async function httpRequest(config, method, path, body, extraHeaders) {
     if (err instanceof MetroneAuthError) throw err;
     if (err instanceof MetroneRateLimitError) throw err;
     if (err instanceof MetroneServerError) throw err;
+    if (err instanceof MetroneClientError) throw err;
     if (err instanceof DOMException && err.name === "AbortError") {
       throw new MetroneTimeoutError(config.timeoutMs);
     }
@@ -328,6 +338,68 @@ var MetroneServer = class {
       properties: data.properties
     });
   }
+  // ─── v1.1 source helpers (SPEC-01) ─────────────────────────────────────────
+  // Thin ergonomic wrappers over track(). Required fields are typed; any
+  // extra keys flow into the JSONB `properties` payload (storage acceptance
+  // is permissive — see @metrone/schemas per-source recommended shapes).
+  /**
+   * Track a campaign lifecycle event (email / SMS sends, opens, clicks…).
+   * Recommended event_type values: email_sent | email_delivered |
+   * email_opened | email_clicked | email_bounced | email_unsubscribed |
+   * sms_sent | sms_delivered | sms_replied | sms_opt_out
+   */
+  trackCampaignEvent(data) {
+    const { event_type, ...properties } = data;
+    this.track(event_type, { source: "campaign", properties });
+  }
+  /**
+   * Track a social media event. Recommended event_type values:
+   * post_published | impression | engagement | click | share
+   */
+  trackSocialEvent(data) {
+    const { event_type, ...properties } = data;
+    this.track(event_type, { source: "social", properties });
+  }
+  /**
+   * Track a review event. Recommended event_type values: received | responded
+   */
+  trackReviewEvent(data) {
+    const { event_type, ...properties } = data;
+    this.track(event_type, { source: "review", properties });
+  }
+  /**
+   * Track a paid-ad metrics event. Recommended event_type values:
+   * impression | click | spend_daily | conversion
+   */
+  trackAdEvent(data) {
+    const { event_type, ...properties } = data;
+    this.track(event_type, { source: "ad", properties });
+  }
+  /**
+   * Track an SMS conversation event. Recommended event_type values:
+   * received | replied. agent_id is promoted to the top-level column so
+   * existing per-agent dashboard breakdowns keep working.
+   */
+  trackSmsEvent(data) {
+    const { event_type, agent_id, ...properties } = data;
+    this.track(event_type, { source: "sms", agent_id, properties });
+  }
+  /**
+   * Track an autonomous agent action (audit-log style). event_type is the
+   * action itself (free-form vocabulary). agent_type / agent_id are written
+   * BOTH to the top-level columns (for existing dashboard breakdowns) AND
+   * into properties (for the JSONB-first get_agent_activity_feed RPC) —
+   * decision B4 of the v1.1 build.
+   */
+  trackAgentAction(data) {
+    const { agent_type, action_taken, agent_id, ...rest } = data;
+    this.track(action_taken, {
+      source: "agent_action",
+      agent_id,
+      agent_type,
+      properties: { agent_type, action_taken, ...rest }
+    });
+  }
   // ─── Read API ──────────────────────────────────────────────────────────────
   /**
    * Get aggregated analytics stats for a time period.
@@ -420,12 +492,26 @@ var MetroneServer = class {
       }
       return { sent: accepted, failed: batch.length - accepted, errors: [] };
     } catch (err) {
+      const isPermanent = err instanceof MetroneAuthError || err instanceof MetroneClientError || err instanceof MetroneError && err.retryable === false;
+      if (isPermanent) {
+        if (this.config.debug) {
+          console.error(
+            `[metrone] Dropping ${batch.length} events \u2014 server rejected them permanently:`,
+            err instanceof Error ? err.message : err
+          );
+        }
+        return {
+          sent: 0,
+          failed: batch.length,
+          errors: [{ index: -1, error: err instanceof Error ? err.message : String(err) }]
+        };
+      }
       this.queue.unshift(...batch);
       if (this.queue.length > this.config.maxQueueSize) {
         this.queue.length = this.config.maxQueueSize;
       }
       if (this.config.debug) {
-        console.error("[metrone] Flush failed, re-queued:", err);
+        console.error("[metrone] Flush failed (transient), re-queued:", err);
       }
       return {
         sent: 0,
@@ -479,6 +565,119 @@ var MetroneServer = class {
     return result;
   }
 };
+
+// src/agent-tracker.ts
+var AI_AGENT_RULES = [
+  // OpenAI
+  { pattern: /chatgpt-user/i, name: "ChatGPT-User" },
+  { pattern: /oai-searchbot/i, name: "OAI-SearchBot" },
+  { pattern: /gptbot/i, name: "GPTBot" },
+  // Anthropic
+  { pattern: /claude-user/i, name: "Claude-User" },
+  { pattern: /claude-searchbot/i, name: "Claude-SearchBot" },
+  { pattern: /claudebot/i, name: "ClaudeBot" },
+  { pattern: /claude-web/i, name: "Claude-Web" },
+  { pattern: /anthropic-ai/i, name: "anthropic-ai" },
+  // Perplexity
+  { pattern: /perplexity-user/i, name: "Perplexity-User" },
+  { pattern: /perplexitybot/i, name: "PerplexityBot" },
+  // Google AI
+  { pattern: /google-cloudvertexbot/i, name: "Google-CloudVertexBot" },
+  { pattern: /googleother/i, name: "GoogleOther" },
+  { pattern: /gemini-deep-research/i, name: "Gemini-Deep-Research" },
+  // Meta
+  { pattern: /meta-externalagent/i, name: "Meta-ExternalAgent" },
+  { pattern: /meta-externalfetcher/i, name: "Meta-ExternalFetcher" },
+  // Microsoft Copilot
+  { pattern: /bingpreview/i, name: "BingPreview" },
+  // xAI
+  { pattern: /grokbot/i, name: "GrokBot" },
+  { pattern: /xai-crawler/i, name: "xAI-Crawler" },
+  // Others
+  { pattern: /duckassistbot/i, name: "DuckAssistBot" },
+  { pattern: /mistralai-user/i, name: "MistralAI-User" },
+  { pattern: /cohere-training-data-crawler/i, name: "Cohere-Training-Crawler" },
+  { pattern: /cohere-ai/i, name: "cohere-ai" },
+  { pattern: /bytespider/i, name: "Bytespider" },
+  { pattern: /amazonbot/i, name: "Amazonbot" },
+  { pattern: /applebot-extended/i, name: "Applebot-Extended" },
+  { pattern: /ccbot/i, name: "CCBot" },
+  { pattern: /youbot/i, name: "YouBot" },
+  { pattern: /timpibot/i, name: "TimpiBot" },
+  { pattern: /diffbot/i, name: "Diffbot" }
+];
+var STATIC_ASSET_PATTERN = /\.(css|js|mjs|json|xml|txt|ico|png|jpe?g|gif|svg|webp|avif|woff2?|ttf|otf|eot|map|pdf|zip|gz|mp4|webm|mp3)$/i;
+function matchAiAgent(userAgent) {
+  if (!userAgent) return void 0;
+  for (const rule of AI_AGENT_RULES) {
+    if (rule.pattern.test(userAgent)) return rule.name;
+  }
+  return void 0;
+}
+function pathFromUrl(url) {
+  try {
+    return new URL(url, "http://localhost").pathname;
+  } catch {
+    return url.split("?")[0] ?? url;
+  }
+}
+function isIgnored(path, options) {
+  if (options?.skipStaticAssets !== false && STATIC_ASSET_PATTERN.test(path)) return true;
+  for (const rule of options?.ignorePaths ?? []) {
+    if (rule.endsWith("*") ? path.startsWith(rule.slice(0, -1)) : path === rule) return true;
+  }
+  return false;
+}
+function captureAgentHit(metrone, hit, options) {
+  try {
+    const method = (hit.method ?? "GET").toUpperCase();
+    if (method !== "GET" && method !== "HEAD") return void 0;
+    const agent = matchAiAgent(hit.userAgent);
+    if (!agent) return void 0;
+    const path = pathFromUrl(hit.url);
+    if (isIgnored(path, options)) return void 0;
+    metrone.track("pageview", {
+      source: "web",
+      page_url: hit.url,
+      page_path: path,
+      referrer: hit.referrer ?? void 0,
+      user_agent: hit.userAgent ?? void 0,
+      properties: { agent_capture: "server" }
+    });
+    return agent;
+  } catch {
+    return void 0;
+  }
+}
+function agentMiddleware(metrone, options) {
+  return function metroneAgentMiddleware(req, _res, next) {
+    try {
+      const header = (name) => {
+        const v = req.headers[name];
+        return Array.isArray(v) ? v[0] : v;
+      };
+      const host = header("host") ?? "localhost";
+      const proto = req.protocol ?? (header("x-forwarded-proto") ?? "https");
+      const rawPath = req.originalUrl ?? req.url ?? "/";
+      captureAgentHit(metrone, {
+        url: `${proto}://${host}${rawPath}`,
+        userAgent: header("user-agent"),
+        referrer: header("referer") ?? header("referrer"),
+        method: req.method
+      }, options);
+    } catch {
+    }
+    next();
+  };
+}
+function trackAgentRequest(metrone, request, options) {
+  return captureAgentHit(metrone, {
+    url: request.url,
+    userAgent: request.headers.get("user-agent"),
+    referrer: request.headers.get("referer"),
+    method: request.method
+  }, options);
+}
 export {
   MetroneAuthError,
   MetroneConfigError,
@@ -489,6 +688,10 @@ export {
   MetroneServer,
   MetroneServerError,
   MetroneTimeoutError,
-  MetroneValidationError
+  MetroneValidationError,
+  agentMiddleware,
+  captureAgentHit,
+  matchAiAgent,
+  trackAgentRequest
 };
 //# sourceMappingURL=index.js.map