@fanbase_admin/fanbase-rate-limit

Shared rate-limit module for backend APIs.

The module enforces per-API-key quotas and request-rate controls, and is intended to be installed once during server bootstrap (Hapi server.ext hooks).

Installation

npm install @fanbase_admin/fanbase-rate-limit

Where to use this module

Use this package in backend services that must enforce API key access, usage limits, and rate limiting.

Do not use it directly in frontend clients.

Required env vars

• PAYMENT_PLAN_BACKEND_URL (example: https://payment-api.yourdomain.com)
• PAYMENT_CHAIN_ID (example: 137)

Quick start

import {
  installHapiRateLimit,
  InMemoryUsageStore,
  createPaymentBackendPlanResolver,
  createStakingOperationClassifier,
  createSwapOperationClassifier,
  extractApiKeyFromRequest
} from '@fanbase_admin/fanbase-rate-limit'

const planResolver = createPaymentBackendPlanResolver({
  baseUrl: process.env.PAYMENT_PLAN_BACKEND_URL!,
  chainId: Number(process.env.PAYMENT_CHAIN_ID || 137)
})

// Dev/local only. For production use a persistent UsageStore implementation.
const usageStore = new InMemoryUsageStore()

installHapiRateLimit(server, {
  planResolver,
  usageStore,
  classifyRequest: createStakingOperationClassifier(),
  // or: createSwapOperationClassifier()
  getApiKey: (request) =>
    extractApiKeyFromRequest(request, { headerName: 'authorization' }),
  getRequestDomain: (request) => {
    const origin = request.headers.origin as string | undefined
    return origin || request.info.host
  }
})

API key header behavior

extractApiKeyFromRequest(...) supports both:

• plain API key in header
• Authorization: Bearer <apiKey>

Use the mode that matches your backend and client integration.

Response headers added by limiter

• RateLimit-Limit
• RateLimit-Remaining
• RateLimit-Reset
• RateLimit-Used-Percent
• RateLimit-Policy
• X-Plan
• optional: X-RateLimit-Warning, X-RateLimit-Mode, Retry-After

Production note

InMemoryUsageStore is only for local/dev and resets counters on process restart.

In production, use a persistent shared UsageStore implementation suitable for multi-instance workloads.