npm package: @mentionable/tracker
Description: Track AI bot crawls on your website. Monitor when GPTBot, ClaudeBot, PerplexityBot, Grok and others crawl your pages.
Latest version: 0.1.5

# @mentionable/tracker

Track AI bot crawls on your website. Monitor when GPTBot, ClaudeBot, PerplexityBot, Grok and others crawl your pages.

See which pages AI models are indexing, how often they come back, and correlate crawl data with your AI visibility on [Mentionable](https://mentionable.io).

## Install

```bash
npm install @mentionable/tracker
```

## Quick Start

### Next.js

```ts
// middleware.ts
import { withMentionable } from '@mentionable/tracker/next'

export default withMentionable({
  apiKey: process.env.MENTIONABLE_API_KEY!,
})

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}
```

That's it. Every AI bot crawl is now tracked in your [Mentionable dashboard](https://mentionable.io).

### Cloudflare Worker

```ts
// src/index.ts
import { withMentionable } from '@mentionable/tracker/cloudflare'

export default withMentionable({
  apiKey: 'mtbl_xxxxx', // or use env: true to read from MENTIONABLE_API_KEY env var
})
```

```bash
npx wrangler deploy
```

Works in front of any origin: Shopify, WordPress, custom backends. The Worker proxies the request and reports crawl data without adding any latency.

### Existing Middleware (Next.js)

If you already have a `middleware.ts`, use the handler directly:

```ts
// middleware.ts
import { NextResponse } from 'next/server'
import { createMentionable } from '@mentionable/tracker/next'

const mentionable = createMentionable({
  apiKey: process.env.MENTIONABLE_API_KEY!,
})

export async function middleware(req) {
  // your existing logic
  mentionable.track(req)

  return NextResponse.next()
}
```

### Existing Cloudflare Worker

```ts
import { createMentionable } from '@mentionable/tracker/cloudflare'

const mentionable = createMentionable({
  apiKey: 'mtbl_xxxxx',
})

export default {
  async fetch(request, env, ctx) {
    // your existing logic
    mentionable.track(request, ctx)

    return fetch(request)
  },
}
```

## What Gets Tracked

The tracker sends minimal, non-sensitive data to the Mentionable API:

| Field    | Description                  |
| -------- | ---------------------------- |
| `ua`     | User-Agent header            |
| `path`   | Request path (e.g. `/pricing`) |
| `host`   | Hostname                     |
| `method` | HTTP method                  |
| `ip`     | Client IP (for bot identification) |
| `status` | Response status code         |
| `t`      | Timestamp                    |

No cookies, no request bodies, no personal data.

## Configuration

```ts
withMentionable({
  // Required
  apiKey: 'mtbl_xxxxx',
})
```

## How It Works

1. The middleware intercepts incoming requests
2. It forwards the User-Agent + request metadata to the Mentionable API (fire-and-forget, zero latency impact)
3. Mentionable detects and classifies the bot server-side
4. Data appears in your dashboard within seconds

The detection logic lives on Mentionable's servers, not in the package. When new AI bots emerge, they're detected automatically without any update on your end.

## Performance

The tracker is designed to have zero impact on your site:

- **Non-blocking**: requests are sent with fire-and-forget (no `await`)
- **Cloudflare**: uses `ctx.waitUntil()` so the response is never delayed
- **Next.js**: runs on the Edge Runtime, adds < 1ms overhead
- **Tiny payload**: ~200 bytes per event

## Get Your API Key

1. Sign up at [mentionable.com](https://mentionable.io)
2. Go to Settings > API
3. Copy your API key (starts with `mtbl_`)

## Links

- [Mentionable Dashboard](https://mentionable.io)

## License

MIT