Esper TypeScript Client

Lightweight TypeScript/JavaScript client library for Esper bot detection API.

Installation

npm install esper-ts-client
# or
yarn add esper-ts-client

Quick Start

import { EsperClient, MitigationAction } from 'esper-ts-client';

const client = new EsperClient({
  apiKey: 'your-api-key',
});

// Check if request should be mitigated
const result = await client.checkMitigation({
  ip: '192.168.1.1',
  userAgent: req.headers['user-agent'],
  path: req.path,
  method: req.method,
});

if (result.action === MitigationAction.Block) {
  res.status(403).json({ error: 'Access denied' });
} else if (result.action === MitigationAction.Challenge) {
  res.status(429).json({ challenge: result.challenge });
} else {
  // Allow request
  next();
}

Configuration

const client = new EsperClient({
  apiKey: 'your-api-key',               // Required
  apiUrl: 'https://api.esperr.com',     // Optional
  beaconUrl: 'https://beacon.esperr.com', // Optional
  timeout: 30000,                        // Optional (ms)
  retries: 3,                            // Optional
  retryDelay: 1000,                      // Optional (ms)
});

API Reference

checkMitigation(request)

Check if a request should be mitigated.

const result = await client.checkMitigation({
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  path: '/api/endpoint',
  method: 'POST',
  headers: { 'x-custom': 'value' },
  metadata: { userId: '123' },
});

verifyChallenge(token, response)

Verify a challenge response.

const isValid = await client.verifyChallenge(
  'challenge-token',
  'user-response'
);

sendBeaconEvent(event)

Send telemetry event to beacon.

await client.sendBeaconEvent({
  type: 'page_view',
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...',
  sessionId: 'session-123',
  data: { page: '/home' },
});

getUsage()

Get API usage statistics.

const usage = await client.getUsage();
console.log(`Requests: ${usage.requests}`);
console.log(`Blocked: ${usage.blocked}`);

Express Middleware Example

import express from 'express';
import { EsperClient } from 'esper-ts';

const app = express();
const esper = new EsperClient({ apiKey: process.env.ESPER_API_KEY });

app.use(async (req, res, next) => {
  try {
    const result = await esper.checkMitigation({
      ip: req.ip,
      userAgent: req.headers['user-agent'],
      path: req.path,
      method: req.method,
    });

    if (result.action === MitigationAction.Block) {
      return res.status(403).json({ error: 'Blocked' });
    }

    if (result.action === MitigationAction.Challenge) {
      return res.status(429).json({ challenge: result.challenge });
    }

    next();
  } catch (error) {
    console.error('Esper error:', error);
    next(); // Allow on error
  }
});

Testing

yarn test

License

MIT