npm package: @orionai/tracker
Description: Official Orion bot tracking middleware for Next.js, Nuxt, and Node.js applications
Author: Orion AI
Latest version: 1.0.0

# @orionai/tracker

Official Orion bot tracking middleware for Next.js, Nuxt.js, and Node.js applications.

Track AI crawler bots (GPTBot, ClaudeBot, PerplexityBot, etc.) server-side with 100% accuracy.

## Why Server-Side Tracking?

AI bots like GPTBot and ClaudeBot **don't execute JavaScript**, so traditional analytics snippets miss 70-90% of bot visits. This middleware tracks bots at the server level before any JavaScript runs.

## Installation

```bash
npm install @orionai/tracker
```

## Quick Start

### Next.js (App Router)

Create or update `middleware.ts` in your project root:

```typescript
import { NextResponse, type NextRequest } from 'next/server'
import { orionBotTracker } from '@orionai/tracker'

export async function middleware(request: NextRequest) {
  const response = NextResponse.next()
  
  await orionBotTracker(request, response, {
    trackingKey: 'your_orion_tracking_key_here',
    apiUrl: 'https://orion-backend-d7rs.onrender.com', // Optional
    debug: false, // Set to true for development
  })
  
  return response
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
  ],
}
```

### Next.js (Pages Router)

Create `pages/_middleware.ts`:

```typescript
import { NextResponse, type NextRequest } from 'next/server'
import { orionBotTracker } from '@orionai/tracker'

export async function middleware(request: NextRequest) {
  const response = NextResponse.next()
  
  await orionBotTracker(request, response, {
    trackingKey: 'your_orion_tracking_key_here',
  })
  
  return response
}
```

### Nuxt.js 3

Create `server/middleware/orion.ts`:

```typescript
import { orionBotTracker } from '@orionai/tracker'

export default defineEventHandler(async (event) => {
  await orionBotTracker(event.node.req, event.node.res, {
    trackingKey: 'your_orion_tracking_key_here',
  })
})
```

### Cloudflare Workers

```typescript
import { orionBotTracker } from '@orionai/tracker'

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = new Response('Hello World')
    
    await orionBotTracker(request, response, {
      trackingKey: env.ORION_TRACKING_KEY,
    })
    
    return response
  },
}
```

### Express.js

```typescript
import express from 'express'
import { orionBotTracker } from '@orionai/tracker'

const app = express()

app.use(async (req, res, next) => {
  await orionBotTracker(req, res, {
    trackingKey: process.env.ORION_TRACKING_KEY!,
  })
  next()
})
```

## Configuration

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `trackingKey` | string | ✅ Yes | - | Your Orion tracking key (find in dashboard) |
| `apiUrl` | string | No | Orion API | Custom API endpoint (for self-hosted) |
| `debug` | boolean | No | `false` | Enable console logging for debugging |
| `timeout` | number | No | `5000` | Request timeout in milliseconds |

## Getting Your Tracking Key

1. Log in to your [Orion dashboard](https://useorion.ai/dashboard)
2. Go to **Settings** → **Tracking Keys**
3. Copy your tracking key (starts with `ork_`)

## What Bots Are Tracked?

### AI Crawlers
- ✅ GPTBot (OpenAI)
- ✅ ChatGPT-User (OpenAI)
- ✅ ClaudeBot (Anthropic)
- ✅ Claude-Web (Anthropic)
- ✅ PerplexityBot (Perplexity)
- ✅ Google-Extended (Google Gemini)
- ✅ Cohere-Bot (Cohere)

### Search Engine Crawlers
- ✅ Googlebot
- ✅ Bingbot
- ✅ Applebot
- ✅ YandexBot
- ✅ DuckDuckBot

### Social Media Bots
- ✅ FacebookBot
- ✅ TwitterBot
- ✅ LinkedInBot
- ✅ SlackBot
- ✅ DiscordBot

**Total: 20+ bot types tracked**

## Verification

After installation, visit your site with a bot user agent to test:

```bash
# Test GPTBot detection
curl -A "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko) ChatGPT-User/1.0" https://yoursite.com

# Check Orion dashboard
# You should see the bot visit appear within 1-2 minutes
```

Or use the built-in verification in your Orion dashboard:
- Go to **Monitoring** → **Bot Activity**
- Click **"Test Installation"**

## Troubleshooting

### Not seeing bot visits?

1. **Check your tracking key is correct** (starts with `ork_`)
2. **Verify middleware is running**:
   ```typescript
   orionBotTracker(request, response, {
     trackingKey: 'your_key',
     debug: true, // Enable logging
   })
   ```
3. **Check the matcher config** (Next.js) - make sure it includes your routes
4. **Verify deployment** - middleware only runs in production/preview, not `localhost`

### Bot visits not appearing in real-time?

- Bot tracking data is processed asynchronously
- Allow 1-2 minutes for data to appear in your dashboard

### Getting rate limited?

- Default timeout is 5 seconds
- Tracking is fire-and-forget (won't block your site)
- If issues persist, contact support@useorion.ai

## Performance Impact

- **Latency:** < 5ms (fire-and-forget request)
- **Blocking:** No - tracking happens asynchronously
- **Bandwidth:** < 1 KB per bot visit

## Support

- 📧 Email: support@useorion.ai
- 📚 Docs: https://useorion.ai/docs
- 💬 Discord: https://discord.gg/orion (coming soon)

## License

MIT © Orion AI

---

**Made with ❤️ by the Orion team**