> ## 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 Overview

> Official SDKs for calling Esper decision APIs from Node, Python, or Rust.

<Info>
  **SDKs Versus Integrations**

  Use 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](../integrations) guides.
</Info>

## Available Client Libraries

* **[TypeScript/JavaScript Client](/sdks/typescript)** - Lightweight client for Node.js and browser applications
* **[Python Client](/sdks/python)** - Lightweight client for Python applications
* **[Rust Client](/sdks/rust)** - Lightweight client for high-performance Rust applications

## 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

```bash theme={null}
npm install esper-ts-client
# or
yarn add esper-ts-client
```

### Python

```bash theme={null}
pip install esper-py-client
```

### Rust

```toml theme={null}
[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.

If your SDK integration calls the synchronous runtime mitigation API, forward
the original request query parameters and cookies. Esper Cloud validates
`esper_challenge_proof` and the configured proof cookie before policy
evaluation, which prevents solved challenges from creating duplicate challenge
decisions, counts, or sessions.

For practical deployment patterns on specific platforms, see:

* [Vercel](../integrations/vercel)
* [Cloudflare Workers](../integrations/cloudflare)
* [AWS Lambda](../integrations/aws)
* [Heroku](../integrations/heroku)

```javascript theme={null}
// 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:

| Option       | Description                | Default                  |
| ------------ | -------------------------- | ------------------------ |
| `apiKey`     | Your Esper API key         | Required                 |
| `apiUrl`     | Esper API endpoint         | `https://api.esperr.com` |
| `timeout`    | Request timeout            | 30 seconds               |
| `maxRetries` | Maximum retry attempts     | 3                        |
| `retryDelay` | Base delay between retries | 1 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

* [GitHub Issues](https://github.com/stonehedgelabs/esper/issues)
* [API Documentation](https://docs.esperr.com)
* Email: [support@esperr.com](mailto:support@esperr.com)