Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.esperr.com/llms.txt

Use this file to discover all available pages before exploring further.

SDKs Versus IntegrationsUse the SDKs when the integration needs to call Esper from application code. If you want a stack-specific entry point first, start with the Integrations guides.

​
Available Client Libraries

​
Features

All SDKs provide:
  • Runtime decisions: Send request context and receive an allow, challenge, or block response
  • Mitigation Actions: Automatically handle allow, challenge, and block responses
  • Challenge Verification: Verify user responses to challenges
  • Beacon Events: Send telemetry data for analysis
  • Usage Statistics: Monitor API usage and performance
  • Retry Logic: Automatic retries with exponential backoff
  • Type Safety: Full type definitions (where applicable)

​
Installation

​
TypeScript/JavaScript

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

​
Python

pip install esper-py-client

​
Rust

[dependencies]
esper-rs-client = "0.1.0"

​
Quick Start

All SDKs follow a similar pattern:
  1. Initialize client with your API key
  2. Send traffic to beacon so Esper can analyze the request and update state
  3. Check mitigation for a later incoming request against active mitigation state
  4. Handle response based on action (allow/block/challenge)
Tenants with valid Esper API keys should be allowed to send traffic to the beacon server. That ingest path is how Esper learns from request activity before later mitigation checks enforce on subsequent requests. For practical deployment patterns on specific platforms, see: 
// TypeScript example
import { EsperClient, MitigationAction } from "esper-ts-client";

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

await client.sendBeaconEvent({
  type: "http_request",
  ip: "192.168.1.10",
  userAgent: "Mozilla/5.0...",
  path: "/login",
  method: "POST",
  sessionId: "session-123",
  data: {
    requestId: "req-1",
  },
});

const result = await client.checkMitigation({
  ip: "192.168.1.10",
  userAgent: "Mozilla/5.0...",
  path: "/checkout",
  method: "POST",
  metadata: {
    requestId: "req-2",
    sessionId: "session-123",
  },
});

if (result.action === MitigationAction.Block) {
  // Block or challenge this later request
} else if (result.action === MitigationAction.Challenge) {
  // Present challenge to user
} else {
  // Allow the request
}

​
Configuration

All SDKs support similar configuration options:
OptionDescriptionDefault
apiKeyYour Esper API keyRequired
apiUrlEsper API endpointhttps://api.esperr.com
timeoutRequest timeout30 seconds
maxRetriesMaximum retry attempts3
retryDelayBase delay between retries1 second

​
Error Handling

All SDKs provide structured error handling:
  • API Errors: When the API returns an error response
  • Connection Errors: Network connectivity issues
  • Timeout Errors: Request timeout exceeded
  • Validation Errors: Invalid request data

​
Support