npm package: @surfgeo/node
Description: Server-side AI bot tracking SDK for Node.js applications by surfgeo
Author: surfgeo
Latest version: 1.0.0

# surfgeo Node.js SDK

Track AI bot traffic on your Node.js servers with surfgeo.

## Installation

```bash
npm install @surfgeo/node
```

## Quick Start

### Express

```javascript
const express = require('express');
const { surfgeo } = require('@surfgeo/node');

const app = express();

app.use(surfgeo({
  scriptKey: 'sk_your_key_here'
}));

app.listen(3000);
```

### Next.js App Router

Create `middleware.ts` in your project root:

```typescript
import { createsurfgeoMiddleware } from '@surfgeo/node/nextjs';

export const middleware = createsurfgeoMiddleware({
  scriptKey: process.env.surfgeo_SCRIPT_KEY!
});

export const config = {
  matcher: '/api/:path*'
};
```

### Next.js Pages Router

Wrap your API routes:

```typescript
import { withsurfgeo } from '@surfgeo/node/nextjs';

async function handler(req, res) {
  res.status(200).json({ message: 'Hello' });
}

export default withsurfgeo(handler, {
  scriptKey: process.env.surfgeo_SCRIPT_KEY!
});
```

### Generic Node.js

```javascript
const http = require('http');
const { surfgeoTracker } = require('@surfgeo/node/generic');

const tracker = new surfgeoTracker({
  scriptKey: 'sk_your_key_here'
});

const server = http.createServer((req, res) => {
  tracker.trackRequest(req, res);
  res.writeHead(200);
  res.end('Hello World');
});

server.listen(3000);
```

## Configuration

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| scriptKey | string | Yes | - | Your surfgeo script key |
| endpoint | string | No | Production | Custom tracking endpoint |
| timeout | number | No | 50 | Request timeout in ms (10-100) |
| debug | boolean | No | false | Enable debug logging |
| enabled | boolean | No | true | Enable/disable tracking |

## Features

- ✅ Zero impact on app performance
- ✅ Non-blocking, fire-and-forget tracking
- ✅ Works with Express, Next.js, and more
- ✅ TypeScript support
- ✅ No dependencies (except node-fetch for Node <18)
- ✅ Automatic bot detection (handled by backend)

## How It Works

1. **Install the SDK** - Add the middleware to your app
2. **Track Requests** - SDK automatically captures request metadata
3. **Send to Backend** - Metadata is sent to surfgeo API (non-blocking)
4. **Bot Detection** - Backend detects AI bots and tracks them
5. **View Analytics** - See bot traffic in your surfgeo dashboard

## TypeScript Support

Full TypeScript support is included:

```typescript
import { surfgeo, surfgeoConfig } from '@surfgeo/node';

const config: surfgeoConfig = {
  scriptKey: process.env.surfgeo_SCRIPT_KEY!,
  debug: process.env.NODE_ENV === 'development'
};

app.use(surfgeo(config));
```

## Environment Variables

```bash
surfgeo_SCRIPT_KEY=sk_your_key_here
surfgeo_ENDPOINT=https://api.surfgeo.com/api/track  # Optional
surfgeo_DEBUG=true  # Optional
surfgeo_ENABLED=true  # Optional
```

## Performance

- **Overhead**: < 5ms per request
- **Non-blocking**: Never blocks your application
- **Timeout**: 50ms default (configurable)
- **No retries**: Single attempt, silent failure

## Examples

See the [examples directory](./examples) for complete working examples:
- [Express Example](./examples/express)
- [Next.js Example](./examples/nextjs)
- [Generic HTTP Server](./examples/generic)

## Documentation

- [API Reference](./docs/API.md)
- [Examples Guide](./docs/EXAMPLES.md)
- [Troubleshooting](./docs/TROUBLESHOOTING.md)

## Requirements

- Node.js >= 16.0.0
- Express >= 4.0.0 (optional, for Express middleware)
- Next.js >= 13.0.0 (optional, for Next.js middleware)

## License

MIT

## Support

- [GitHub Issues](https://github.com/thebisontech/surfgeo-node-aireferral-sdk/issues)
- [Documentation](https://docs.surfgeo.com)