surfgeo Node.js SDK

Track AI bot traffic on your Node.js servers with surfgeo.

Installation

npm install @surfgeo/node

Quick Start

Express

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:

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:

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

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:

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

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 for complete working examples:

• Express Example
• Next.js Example
• Generic HTTP Server

Documentation

• API Reference
• Examples Guide
• Troubleshooting

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
• Documentation