@botpress/ratelimit

A rate limiting library for Botpress services and integrations.

Installation

npm install @botpress/ratelimit
pnpm install @botpress/ratelimit
bun install @botpress/ratelimit

Usage

Policy-Based API (Recommended for Integrations)

Create a client, define policies, and use them to limit requests:

import * as ratelimit from '@botpress/ratelimit'

// Create a client with a prefix (e.g., your integration name)
const client = new ratelimit.RateLimit({
  baseUrl: process.env.RATE_LIMIT_API_URL,
  apiKey: process.env.RATE_LIMIT_API_KEY,
  endpoint: process.env.RATE_LIMIT_API_ENDPOINT,
  prefix: 'integration-name', // Client-level prefix
})

// Create policies with their own prefixes
const limit = {
  apiCall: ratelimit.policy({
    client,
    prefix: 'api-call', // Policy-level prefix
    requests: 100, // Allow 100 requests
    duration: 60, // Per 60 seconds
  }),
}

// Use the policy to check and consume a rate limit token
const result = await limit.apiCall('user-123')

if (!result.success) {
  console.log(`Rate limit exceeded. Try again in ${result.reset} seconds`)
  return
}

// Request is allowed, proceed
console.log(`${result.remaining} requests remaining`)

You can create multiple policies for different rate limits:

const limit = {
  apiCall: ratelimit.policy({
    client,
    prefix: 'api-call', // Policy prefix
    requests: 100,
    duration: 60,
  }),
  webhook: ratelimit.policy({
    client,
    prefix: 'webhook', // Different policy prefix
    requests: 10,
    duration: 60,
  }),
}

// Use different policies for different operations
const apiResult = await limit.apiCall('user-123')
const webhookResult = await limit.webhook('user-123')

Rate Limit Key Format

Rate limit keys are automatically generated using the format:

${client.prefix}:${policy.prefix}:${hash(userId)}

Where:

• client.prefix is the prefix provided when creating the RateLimit client
• policy.prefix is the prefix provided when creating each policy
• hash(userId) is the SHA-256 hash of the user identifier

This ensures that rate limits are properly scoped and user IDs are hashed.

Rate Limit Result

All policy functions return the same result format:

interface RateLimitResult {
  success: boolean // Whether the request is allowed
  limit: number // Maximum requests allowed
  remaining: number // Remaining requests in current window
  reset: number // Seconds until rate limit resets
}