@claria-analytics/server

Server-side bot detection and tracking for AI crawlers. Part of the Claria analytics platform.

What it does

@claria-analytics/server detects and tracks AI bot requests hitting your website. It identifies bots from OpenAI (ChatGPT, GPTBot, OAI-SearchBot), Perplexity, Anthropic (Claude), and Google, then forwards raw request metadata to the Claria backend for analysis.

Key characteristics:

• Runs in server middleware (Node.js, Edge Runtime)
• Non-blocking -- bot tracking runs via event.waitUntil(), never slowing down responses
• Framework-agnostic core with a ready-made Next.js adapter
• Captures raw headers for backend-side verification (HTTP signatures, IP validation)
• Requires a secret ingestKey -- never exposed to the browser

Installation

npm install @claria-analytics/server

pnpm add @claria-analytics/server

yarn add @claria-analytics/server

Quick Start (Next.js)

Wrap your existing middleware with withClariaBotTracking. It runs bot detection in the background without affecting your middleware's behavior or response times.

// middleware.ts
import { withClariaBotTracking } from "@claria-analytics/server/nextjs";
import { NextResponse } from "next/server";
import type { NextRequest, NextFetchEvent } from "next/server";

function myMiddleware(request: NextRequest, event: NextFetchEvent) {
  // Your existing middleware logic (auth, redirects, etc.)
  return NextResponse.next();
}

export default withClariaBotTracking(myMiddleware, {
  clientId: process.env.CLARIA_CLIENT_ID!,
  ingestKey: process.env.CLARIA_INGEST_KEY!,
});

export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

Environment Variables

| Variable | Required | Secret | Description | | ------------------- | -------- | ------- | ------------------------------------- | | CLARIA_CLIENT_ID | Yes | No | Your Claria client identifier | | CLARIA_INGEST_KEY | Yes | Yes | API key for authenticating bot events |

Important: CLARIA_INGEST_KEY is a secret. Never expose it in client-side code or public environment variables.

Configuration

| Field | Type | Required | Default | Description | | ----------- | --------- | -------- | ------------------------------------- | ------------------------------------------------- | | clientId | string | Yes | -- | Your Claria client identifier | | ingestKey | string | Yes | -- | Secret API key for bot event ingestion | | endpoint | string | No | https://claria-dashboard.vercel.app | Claria backend URL | | debug | boolean | No | false | Enable debug logging and permissive bot detection |

Exports

@claria-analytics/server (main entry)

| Export | Description | | ---------------------- | ------------------------------------------------------------------- | | detectBotKind | Detect bot type from a user-agent string. Returns BotKind \| null | | buildBotEventPayload | Build a bot event payload from a generic request descriptor | | sendBotEvent | Send a bot event payload to the Claria backend |

@claria-analytics/server/nextjs

| Export | Description | | ----------------------- | -------------------------------------------------------- | | withClariaBotTracking | Wrap a Next.js middleware with non-blocking bot tracking |

Types

• BotKind -- Union of detected bot identifiers
• BotEventPayload -- The full payload sent to the Claria backend
• ClariaRequestInfo -- Generic request descriptor (for custom framework adapters)
• ClariaServerConfig -- Configuration object shape

Detected Bots

| Bot Kind | User-Agent Pattern | | ---------------------- | -------------------------------------- | | openai_chatgpt_user | ChatGPT-User | | openai_oai_searchbot | OAI-SearchBot | | openai_gptbot | GPTBot | | perplexity | PerplexityBot, Perplexity | | anthropic | Anthropic, Claude-Web, ClaudeBot | | google_extended | Google-Extended | | google_bot | Googlebot | | other_ai_bot | Generic patterns (debug mode only) |

Advanced Usage

Direct bot detection (without sending)

import { detectBotKind } from "@claria-analytics/server";

const botKind = detectBotKind(request.headers.get("user-agent") ?? "");
if (botKind) {
  console.log("AI bot detected:", botKind);
}

Custom framework adapter

The core functions accept a generic ClariaRequestInfo object, so you can integrate with any server framework:

import { buildBotEventPayload, sendBotEvent } from "@claria-analytics/server";
import type {
  ClariaRequestInfo,
  ClariaServerConfig,
} from "@claria-analytics/server";

const config: ClariaServerConfig = {
  clientId: "your_client_id",
  ingestKey: "your_ingest_key",
};

// Adapt your framework's request to ClariaRequestInfo
const requestInfo: ClariaRequestInfo = {
  url: req.url,
  method: req.method,
  ip: req.socket.remoteAddress ?? "unknown",
  headers: new Headers(req.headers as Record<string, string>),
};

const payload = buildBotEventPayload(requestInfo, config);
if (payload) {
  await sendBotEvent(payload, config);
}

How It Works

1. On each incoming request, the middleware checks the User-Agent header against known AI bot patterns.
2. If a bot is detected, it builds a payload with raw request metadata (URL, method, IP, headers).
3. The payload is sent to {endpoint}/api/collect-bot with Bearer token authentication.
4. All verification (HTTP signature validation, IP checks) and analysis happens on the Claria backend.
5. Bot tracking runs in the background via waitUntil() -- it never blocks your response.

License

Proprietary. All rights reserved.