# AI Growth Bot Analytics

Zero-code bot tracking for Node.js servers. Automatically detects and tracks bot traffic (Googlebot, ChatGPT, Claude, etc.) and sends events to your analytics dashboard.

## Installation

```bash
npm install aigrowth-bot-analytics
```

That's it! No code changes needed.

## Setup

1. Create a `.env` file in your project root with your API token:

```env
AIGROWTH_API_TOKEN=your_api_token_here
AIGROWTH_ACCOUNT_ID=optional_account_id
```

2. The package automatically injects itself into your npm scripts (`start`, `dev`, `serve`, `start:prod`, `preview`).

3. Start your application normally. The package will automatically begin tracking bot traffic.

## Supported Frameworks

- Express.js
- Fastify
- NestJS
- Next.js
- Pure Node.js HTTP servers

## How It Works

The package uses Node.js's `NODE_OPTIONS` environment variable to pre-load a module that intercepts HTTP requests at the Node.js core level. This means:

- No code changes required in your application
- Works with any HTTP framework
- Zero runtime overhead for non-bot requests
- Automatically detects over 50+ bot types

## Detected Bots

- Search engines: Googlebot, Bingbot, DuckDuckBot, BaiduSpider, Yandexbot, Slurp
- Social media: FacebookBot, TwitterBot, LinkedInBot, PinterestBot
- AI models: GPTBot, ChatGPT-User, ClaudeBot, PerplexityBot, AnthropicAI, CCBot
- Messaging: WhatsAppBot, TelegramBot
- Others: AppleBot, SpotifyBot, MSNBot, AhrefsBot, SemrushBot, and more

## Data Collected

For each bot request, the following is sent to `analytics.aigrowthagent.co/bot-track`:

```json
{
  "bot_name": "Googlebot",
  "bot_category": "Search Engines",
  "host": "example.com",
  "ip": "203.0.113.42",
  "page_url": "/robots.txt",
  "account_id": "optional"
}
```

**HTTP Headers:**
- `X-API-Key: {AIGROWTH_API_TOKEN}`
- `Content-Type: application/json`

## Environment Variables

- `AIGROWTH_API_TOKEN` (required) - Your API token for analytics
- `AIGROWTH_ACCOUNT_ID` (optional) - Your account ID for organization

## Security

- No sensitive data is collected
- Only bot requests are tracked
- The `.env` file is never committed (add to `.gitignore`)
- Network failures are handled gracefully and don't affect your app
- Requests have a 2-second timeout to prevent hanging

## Uninstall

```bash
npm uninstall aigrowth-bot-analytics
```

The package will clean up by removing itself from `package.json` scripts. If you need to restore the original scripts, a backup is created at `package.json.aigrowth.bak`.

## License

MIT