@beignet/core/src/contracts/rate-limit.ts

Core framework primitives for Beignet

/**
 * Rate limit scope for identifying the rate limit key.
 *
 * - "user": keyed by authenticated user id
 * - "ip": keyed by client IP
 * - "global": single global key
 */
export type RateLimitScope = "user" | "ip" | "global";

/**
 * Rate limit configuration for a contract.
 *
 * This type is used in contract metadata to configure rate limiting behavior.
 *
 * @example
 * ```ts
 * const getTodoContract = c
 *   .get("/api/todos/:id", "getTodo")
 *   .pathParams(z.object({ id: z.string() }))
 *   .meta({
 *     auth: "required",
 *     rateLimit: {
 *       max: 60,
 *       windowSec: 60,
 *       scope: "user",
 *     },
 *   })
 *   .responses({ 200: z.object({ id: z.string(), name: z.string() }) });
 * ```
 */
export interface RateLimitMeta {
  /**
   * Maximum number of allowed hits within the window.
   */
  max: number;
  /**
   * Length of the window in seconds.
   */
  windowSec: number;
  /**
   * Scope for identifying the rate limit key.
   *
   * - "user": keyed by authenticated user id
   * - "ip": keyed by client IP
   * - "global": single global key
   *
   * Default: "global".
   */
  scope?: RateLimitScope;
}