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