@commandkit/ratelimit 0.0.0-dev.20260317060555

package/dist/storage/redis.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Redis storage.
+ *
+ * Uses Lua scripts for atomic fixed/sliding window operations.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisRateLimitStorage = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+const FIXED_WINDOW_SCRIPT = /* lua */ `
+  local key = KEYS[1]
+  local window = tonumber(ARGV[1])
+  local count = redis.call('INCR', key)
+  local ttl = redis.call('PTTL', key)
+  if ttl < 0 then
+    redis.call('PEXPIRE', key, window)
+    ttl = window
+  end
+  return {count, ttl}
+`;
+const SLIDING_WINDOW_SCRIPT = /* lua */ `
+  local key = KEYS[1]
+  local limit = tonumber(ARGV[1])
+  local window = tonumber(ARGV[2])
+  local now = tonumber(ARGV[3])
+  local member = ARGV[4]
+
+  redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
+  local count = redis.call('ZCARD', key)
+
+  if count >= limit then
+    local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+    local resetAt = now + window
+    if oldest[2] then
+      resetAt = tonumber(oldest[2]) + window
+    end
+    return {0, count, resetAt}
+  end
+
+  redis.call('ZADD', key, now, member)
+  redis.call('PEXPIRE', key, window)
+  count = count + 1
+  local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+  local resetAt = now + window
+  if oldest[2] then
+    resetAt = tonumber(oldest[2]) + window
+  end
+  return {1, count, resetAt}
+`;
+/**
+ * Redis-backed storage with Lua scripts for atomic window operations.
+ *
+ * @implements RateLimitStorage
+ */
+class RedisRateLimitStorage {
+    constructor(redis) {
+        this.redis = redis instanceof ioredis_1.default ? redis : new ioredis_1.default(redis ?? {});
+    }
+    /**
+     * Read a value from Redis and JSON-decode it.
+     *
+     * @param key - Storage key to read.
+     * @returns Parsed value or null when absent.
+     */
+    async get(key) {
+        const value = await this.redis.get(key);
+        if (value == null)
+            return null;
+        return JSON.parse(value);
+    }
+    /**
+     * Store a value in Redis with optional TTL.
+     *
+     * @param key - Storage key to write.
+     * @param value - Value to serialize and store.
+     * @param ttlMs - Optional TTL in milliseconds.
+     * @returns Resolves when the value is stored.
+     */
+    async set(key, value, ttlMs) {
+        const payload = JSON.stringify(value);
+        if (typeof ttlMs === 'number') {
+            await this.redis.set(key, payload, 'PX', ttlMs);
+            return;
+        }
+        await this.redis.set(key, payload);
+    }
+    /**
+     * Delete a key from Redis.
+     *
+     * @param key - Storage key to delete.
+     * @returns Resolves when the key is removed.
+     */
+    async delete(key) {
+        await this.redis.del(key);
+    }
+    /**
+     * Read the TTL for a key when present.
+     *
+     * @param key - Storage key to inspect.
+     * @returns Remaining TTL in ms or null when no TTL is set.
+     */
+    async ttl(key) {
+        const ttl = await this.redis.pttl(key);
+        if (ttl < 0)
+            return null;
+        return ttl;
+    }
+    /**
+     * Update the TTL for an existing key.
+     *
+     * @param key - Storage key to update.
+     * @param ttlMs - TTL in milliseconds.
+     * @returns Resolves after the TTL is updated.
+     */
+    async expire(key, ttlMs) {
+        await this.redis.pexpire(key, ttlMs);
+    }
+    /**
+     * Add a member to a sorted set with the given score.
+     *
+     * @param key - Sorted-set key.
+     * @param score - Score to associate with the member.
+     * @param member - Member identifier.
+     * @returns Resolves when the member is added.
+     */
+    async zAdd(key, score, member) {
+        await this.redis.zadd(key, score.toString(), member);
+    }
+    /**
+     * Remove sorted-set members with scores in the given range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Resolves when the range is removed.
+     */
+    async zRemRangeByScore(key, min, max) {
+        await this.redis.zremrangebyscore(key, min.toString(), max.toString());
+    }
+    /**
+     * Count members in a sorted set.
+     *
+     * @param key - Sorted-set key.
+     * @returns Number of members in the set.
+     */
+    async zCard(key) {
+        return Number(await this.redis.zcard(key));
+    }
+    /**
+     * Read sorted-set members in a score range.
+     *
+     * @param key - Sorted-set key.
+     * @param min - Minimum score (inclusive).
+     * @param max - Maximum score (inclusive).
+     * @returns Ordered members in the score range.
+     */
+    async zRangeByScore(key, min, max) {
+        return this.redis.zrangebyscore(key, min.toString(), max.toString());
+    }
+    /**
+     * Atomically consume a fixed-window counter via Lua.
+     *
+     * @param key - Storage key to consume.
+     * @param _limit - Limit (unused by the script).
+     * @param windowMs - Window size in milliseconds.
+     * @param _nowMs - Current time (unused by the script).
+     * @returns Fixed-window consume result.
+     */
+    async consumeFixedWindow(key, _limit, windowMs, _nowMs) {
+        const result = (await this.redis.eval(FIXED_WINDOW_SCRIPT, 1, key, windowMs.toString()));
+        return {
+            count: Number(result[0]),
+            ttlMs: Number(result[1]),
+        };
+    }
+    /**
+     * Atomically consume a sliding-window log via Lua.
+     *
+     * @param key - Storage key to consume.
+     * @param limit - Request limit for the window.
+     * @param windowMs - Window size in milliseconds.
+     * @param nowMs - Current timestamp in milliseconds.
+     * @param member - Member identifier for this request.
+     * @returns Sliding-window consume result.
+     */
+    async consumeSlidingWindowLog(key, limit, windowMs, nowMs, member) {
+        const result = (await this.redis.eval(SLIDING_WINDOW_SCRIPT, 1, key, limit.toString(), windowMs.toString(), nowMs.toString(), member));
+        return {
+            allowed: Number(result[0]) === 1,
+            count: Number(result[1]),
+            resetAt: Number(result[2]),
+        };
+    }
+    /**
+     * Delete keys with the given prefix.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Resolves after matching keys are deleted.
+     */
+    async deleteByPrefix(prefix) {
+        await this.deleteByPattern(`${prefix}*`);
+    }
+    /**
+     * Delete keys matching a glob pattern using SCAN to avoid blocking Redis.
+     *
+     * @param pattern - Glob pattern to match keys against.
+     * @returns Resolves after matching keys are deleted.
+     */
+    async deleteByPattern(pattern) {
+        let cursor = '0';
+        do {
+            const [nextCursor, keys] = (await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', '100'));
+            if (keys.length) {
+                await this.redis.del(...keys);
+            }
+            cursor = nextCursor;
+        } while (cursor !== '0');
+    }
+    /**
+     * List keys that match a prefix using SCAN.
+     *
+     * @param prefix - Prefix to match.
+     * @returns Matching keys.
+     */
+    async keysByPrefix(prefix) {
+        const pattern = `${prefix}*`;
+        const collected = new Set();
+        let cursor = '0';
+        do {
+            const [nextCursor, keys] = (await this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', '100'));
+            for (const key of keys) {
+                collected.add(key);
+            }
+            cursor = nextCursor;
+        } while (cursor !== '0');
+        return Array.from(collected);
+    }
+}
+exports.RedisRateLimitStorage = RedisRateLimitStorage;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVkaXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc3RvcmFnZS9yZWRpcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiO0FBQUE7Ozs7R0FJRzs7Ozs7O0FBRUgsc0RBQW1EO0FBT25ELE1BQU0sbUJBQW1CLEdBQUcsU0FBUyxDQUFDOzs7Ozs7Ozs7O0NBVXJDLENBQUM7QUFFRixNQUFNLHFCQUFxQixHQUFHLFNBQVMsQ0FBQzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztDQTRCdkMsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCxNQUFhLHFCQUFxQjtJQUdoQyxZQUFtQixLQUE0QjtRQUM3QyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssWUFBWSxpQkFBSyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLElBQUksaUJBQUssQ0FBQyxLQUFLLElBQUksRUFBRSxDQUFDLENBQUM7SUFDdkUsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0gsS0FBSyxDQUFDLEdBQUcsQ0FBYyxHQUFXO1FBQ2hDLE1BQU0sS0FBSyxHQUFHLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDeEMsSUFBSSxLQUFLLElBQUksSUFBSTtZQUFFLE9BQU8sSUFBSSxDQUFDO1FBQy9CLE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQU0sQ0FBQztJQUNoQyxDQUFDO0lBRUQ7Ozs7Ozs7T0FPRztJQUNILEtBQUssQ0FBQyxHQUFHLENBQWMsR0FBVyxFQUFFLEtBQVEsRUFBRSxLQUFjO1FBQzFELE1BQU0sT0FBTyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDdEMsSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLEVBQUUsQ0FBQztZQUM5QixNQUFNLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEdBQUcsRUFBRSxPQUFPLEVBQUUsSUFBSSxFQUFFLEtBQUssQ0FBQyxDQUFDO1lBQ2hELE9BQU87UUFDVCxDQUFDO1FBQ0QsTUFBTSxJQUFJLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFHLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0gsS0FBSyxDQUFDLE1BQU0sQ0FBQyxHQUFXO1FBQ3RCLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDNUIsQ0FBQztJQUVEOzs7OztPQUtHO0lBQ0gsS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFXO1FBQ25CLE1BQU0sR0FBRyxHQUFHLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDdkMsSUFBSSxHQUFHLEdBQUcsQ0FBQztZQUFFLE9BQU8sSUFBSSxDQUFDO1FBQ3pCLE9BQU8sR0FBRyxDQUFDO0lBQ2IsQ0FBQztJQUVEOzs7Ozs7T0FNRztJQUNILEtBQUssQ0FBQyxNQUFNLENBQUMsR0FBVyxFQUFFLEtBQWE7UUFDckMsTUFBTSxJQUFJLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxHQUFHLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDdkMsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQVcsRUFBRSxLQUFhLEVBQUUsTUFBYztRQUNuRCxNQUFNLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxLQUFLLENBQUMsUUFBUSxFQUFFLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDdkQsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxLQUFLLENBQUMsZ0JBQWdCLENBQUMsR0FBVyxFQUFFLEdBQVcsRUFBRSxHQUFXO1FBQzFELE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxnQkFBZ0IsQ0FBQyxHQUFHLEVBQUUsR0FBRyxDQUFDLFFBQVEsRUFBRSxFQUFFLEdBQUcsQ0FBQyxRQUFRLEVBQUUsQ0FBQyxDQUFDO0lBQ3pFLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILEtBQUssQ0FBQyxLQUFLLENBQUMsR0FBVztRQUNyQixPQUFPLE1BQU0sQ0FBQyxNQUFNLElBQUksQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUM7SUFDN0MsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxLQUFLLENBQUMsYUFBYSxDQUNqQixHQUFXLEVBQ1gsR0FBVyxFQUNYLEdBQVc7UUFFWCxPQUFPLElBQUksQ0FBQyxLQUFLLENBQUMsYUFBYSxDQUFDLEdBQUcsRUFBRSxHQUFHLENBQUMsUUFBUSxFQUFFLEVBQUUsR0FBRyxDQUFDLFFBQVEsRUFBRSxDQUFDLENBQUM7SUFDdkUsQ0FBQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0gsS0FBSyxDQUFDLGtCQUFrQixDQUN0QixHQUFXLEVBQ1gsTUFBYyxFQUNkLFFBQWdCLEVBQ2hCLE1BQWM7UUFFZCxNQUFNLE1BQU0sR0FBRyxDQUFDLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQ25DLG1CQUFtQixFQUNuQixDQUFDLEVBQ0QsR0FBRyxFQUNILFFBQVEsQ0FBQyxRQUFRLEVBQUUsQ0FDcEIsQ0FBcUIsQ0FBQztRQUV2QixPQUFPO1lBQ0wsS0FBSyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7WUFDeEIsS0FBSyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7U0FDekIsQ0FBQztJQUNKLENBQUM7SUFFRDs7Ozs7Ozs7O09BU0c7SUFDSCxLQUFLLENBQUMsdUJBQXVCLENBQzNCLEdBQVcsRUFDWCxLQUFhLEVBQ2IsUUFBZ0IsRUFDaEIsS0FBYSxFQUNiLE1BQWM7UUFFZCxNQUFNLE1BQU0sR0FBRyxDQUFDLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQ25DLHFCQUFxQixFQUNyQixDQUFDLEVBQ0QsR0FBRyxFQUNILEtBQUssQ0FBQyxRQUFRLEVBQUUsRUFDaEIsUUFBUSxDQUFDLFFBQVEsRUFBRSxFQUNuQixLQUFLLENBQUMsUUFBUSxFQUFFLEVBQ2hCLE1BQU0sQ0FDUCxDQUE2QixDQUFDO1FBRS9CLE9BQU87WUFDTCxPQUFPLEVBQUUsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUM7WUFDaEMsS0FBSyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7WUFDeEIsT0FBTyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxDQUFDLENBQUM7U0FDM0IsQ0FBQztJQUNKLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILEtBQUssQ0FBQyxjQUFjLENBQUMsTUFBYztRQUNqQyxNQUFNLElBQUksQ0FBQyxlQUFlLENBQUMsR0FBRyxNQUFNLEdBQUcsQ0FBQyxDQUFDO0lBQzNDLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILEtBQUssQ0FBQyxlQUFlLENBQUMsT0FBZTtRQUNuQyxJQUFJLE1BQU0sR0FBRyxHQUFHLENBQUM7UUFDakIsR0FBRyxDQUFDO1lBQ0YsTUFBTSxDQUFDLFVBQVUsRUFBRSxJQUFJLENBQUMsR0FBRyxDQUFDLE1BQU0sSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQy9DLE1BQU0sRUFDTixPQUFPLEVBQ1AsT0FBTyxFQUNQLE9BQU8sRUFDUCxLQUFLLENBQ04sQ0FBdUIsQ0FBQztZQUV6QixJQUFJLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztnQkFDaEIsTUFBTSxJQUFJLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxHQUFHLElBQUksQ0FBQyxDQUFDO1lBQ2hDLENBQUM7WUFDRCxNQUFNLEdBQUcsVUFBVSxDQUFDO1FBQ3RCLENBQUMsUUFBUSxNQUFNLEtBQUssR0FBRyxFQUFFO0lBQzNCLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILEtBQUssQ0FBQyxZQUFZLENBQUMsTUFBYztRQUMvQixNQUFNLE9BQU8sR0FBRyxHQUFHLE1BQU0sR0FBRyxDQUFDO1FBQzdCLE1BQU0sU0FBUyxHQUFHLElBQUksR0FBRyxFQUFVLENBQUM7UUFDcEMsSUFBSSxNQUFNLEdBQUcsR0FBRyxDQUFDO1FBQ2pCLEdBQUcsQ0FBQztZQUNGLE1BQU0sQ0FBQyxVQUFVLEVBQUUsSUFBSSxDQUFDLEdBQUcsQ0FBQyxNQUFNLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUMvQyxNQUFNLEVBQ04sT0FBTyxFQUNQLE9BQU8sRUFDUCxPQUFPLEVBQ1AsS0FBSyxDQUNOLENBQXVCLENBQUM7WUFFekIsS0FBSyxNQUFNLEdBQUcsSUFBSSxJQUFJLEVBQUUsQ0FBQztnQkFDdkIsU0FBUyxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztZQUNyQixDQUFDO1lBQ0QsTUFBTSxHQUFHLFVBQVUsQ0FBQztRQUN0QixDQUFDLFFBQVEsTUFBTSxLQUFLLEdBQUcsRUFBRTtRQUV6QixPQUFPLEtBQUssQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUM7SUFDL0IsQ0FBQztDQUNGO0FBbFBELHNEQWtQQyJ9

package/dist/types.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Rate limit type contracts.
+ *
+ * Shared config and result shapes for the plugin, engine, storage, and helpers.
+ * Keeping them in one place reduces drift between runtime behavior and docs.
+ */
+import type { Interaction, Message } from 'discord.js';
+import type { Context } from 'commandkit';
+import type { LoadedCommand } from 'commandkit';
+/**
+ * Scopes used to build rate limit keys and apply per-scope limits.
+ */
+export declare const RATE_LIMIT_SCOPES: readonly ["user", "guild", "channel", "global", "user-guild", "custom"];
+/**
+ * Literal union of supported key scopes.
+ */
+export type RateLimitScope = (typeof RATE_LIMIT_SCOPES)[number];
+/**
+ * Scopes eligible for temporary exemptions stored in rate limit storage.
+ */
+export declare const RATE_LIMIT_EXEMPTION_SCOPES: readonly ["user", "guild", "role", "channel", "category"];
+/**
+ * Literal union of exemption scopes.
+ */
+export type RateLimitExemptionScope = (typeof RATE_LIMIT_EXEMPTION_SCOPES)[number];
+/**
+ * Algorithm identifiers used to select the limiter implementation.
+ */
+export declare const RATE_LIMIT_ALGORITHMS: readonly ["fixed-window", "sliding-window", "token-bucket", "leaky-bucket"];
+/**
+ * Literal union of algorithm identifiers.
+ */
+export type RateLimitAlgorithmType = (typeof RATE_LIMIT_ALGORITHMS)[number];
+/**
+ * Duration input accepted by configs: milliseconds or a duration string.
+ */
+export type DurationLike = number | string;
+/**
+ * Queue behavior for delayed retries after a limit is hit.
+ */
+export interface RateLimitQueueOptions {
+    enabled?: boolean;
+    maxSize?: number;
+    timeout?: DurationLike;
+    deferInteraction?: boolean;
+    ephemeral?: boolean;
+    concurrency?: number;
+}
+/**
+ * Strategy for choosing among matching role-based overrides.
+ */
+export type RateLimitRoleLimitStrategy = 'highest' | 'lowest' | 'first';
+/**
+ * Result for a single limiter/window evaluation used for aggregation.
+ */
+export interface RateLimitResult {
+    key: string;
+    scope: RateLimitScope;
+    algorithm: RateLimitAlgorithmType;
+    windowId?: string;
+    limited: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfter: number;
+    limit: number;
+}
+/**
+ * Contract for rate limit algorithms used by the engine.
+ */
+export interface RateLimitAlgorithm {
+    readonly type: RateLimitAlgorithmType;
+    consume(key: string): Promise<RateLimitResult>;
+    reset(key: string): Promise<void>;
+}
+/**
+ * Storage result for fixed-window atomic consumes.
+ */
+export interface FixedWindowConsumeResult {
+    count: number;
+    ttlMs: number;
+}
+/**
+ * Storage result for sliding-window log consumes.
+ */
+export interface SlidingWindowConsumeResult {
+    allowed: boolean;
+    count: number;
+    resetAt: number;
+}
+/**
+ * Storage contract for rate limit state, with optional optimization hooks.
+ */
+export interface RateLimitStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    incr?(key: string, ttlMs: number): Promise<FixedWindowConsumeResult>;
+    ttl?(key: string): Promise<number | null>;
+    expire?(key: string, ttlMs: number): Promise<void>;
+    zAdd?(key: string, score: number, member: string): Promise<void>;
+    zRemRangeByScore?(key: string, min: number, max: number): Promise<void>;
+    zCard?(key: string): Promise<number>;
+    zRangeByScore?(key: string, min: number, max: number): Promise<string[]>;
+    consumeFixedWindow?(key: string, limit: number, windowMs: number, nowMs: number): Promise<FixedWindowConsumeResult>;
+    consumeSlidingWindowLog?(key: string, limit: number, windowMs: number, nowMs: number, member: string): Promise<SlidingWindowConsumeResult>;
+    deleteByPrefix?(prefix: string): Promise<void>;
+    deleteByPattern?(pattern: string): Promise<void>;
+    keysByPrefix?(prefix: string): Promise<string[]>;
+}
+/**
+ * Storage configuration: direct instance or `{ driver }` wrapper for parity.
+ */
+export type RateLimitStorageConfig = RateLimitStorage | {
+    driver: RateLimitStorage;
+};
+/**
+ * Escalation settings for repeated violations.
+ */
+export interface ViolationOptions {
+    escalate?: boolean;
+    maxViolations?: number;
+    escalationMultiplier?: number;
+    resetAfter?: DurationLike;
+}
+/**
+ * Per-window overrides when a limiter defines multiple windows.
+ */
+export interface RateLimitWindowConfig {
+    id?: string;
+    maxRequests?: number;
+    interval?: DurationLike;
+    algorithm?: RateLimitAlgorithmType;
+    burst?: number;
+    refillRate?: number;
+    leakRate?: number;
+    violations?: ViolationOptions;
+}
+/**
+ * Custom key builder for the `custom` scope.
+ */
+export type RateLimitKeyResolver = (ctx: Context, command: LoadedCommand, source: Interaction | Message) => string;
+/**
+ * Core limiter configuration used by plugin and directives.
+ */
+export interface RateLimitLimiterConfig {
+    maxRequests?: number;
+    interval?: DurationLike;
+    scope?: RateLimitScope | RateLimitScope[];
+    algorithm?: RateLimitAlgorithmType;
+    burst?: number;
+    refillRate?: number;
+    leakRate?: number;
+    keyResolver?: RateLimitKeyResolver;
+    keyPrefix?: string;
+    storage?: RateLimitStorageConfig;
+    violations?: ViolationOptions;
+    queue?: RateLimitQueueOptions;
+    windows?: RateLimitWindowConfig[];
+    roleLimits?: Record<string, RateLimitLimiterConfig>;
+    roleLimitStrategy?: RateLimitRoleLimitStrategy;
+}
+/**
+ * Per-command override stored in CommandKit metadata.
+ */
+export interface RateLimitCommandConfig extends RateLimitLimiterConfig {
+    limiter?: string;
+}
+/**
+ * Permanent allowlist rules for rate limiting.
+ */
+export interface RateLimitBypassOptions {
+    userIds?: string[];
+    roleIds?: string[];
+    guildIds?: string[];
+    check?: (source: Interaction | Message) => boolean | Promise<boolean>;
+}
+/**
+ * Parameters for granting a temporary exemption.
+ */
+export interface RateLimitExemptionGrantParams {
+    scope: RateLimitExemptionScope;
+    id: string;
+    duration: DurationLike;
+    keyPrefix?: string;
+}
+/**
+ * Parameters for revoking a temporary exemption.
+ */
+export interface RateLimitExemptionRevokeParams {
+    scope: RateLimitExemptionScope;
+    id: string;
+    keyPrefix?: string;
+}
+/**
+ * Filters for listing temporary exemptions.
+ */
+export interface RateLimitExemptionListParams {
+    scope?: RateLimitExemptionScope;
+    id?: string;
+    keyPrefix?: string;
+    limit?: number;
+}
+/**
+ * Listed exemption entry with key and expiry info.
+ */
+export interface RateLimitExemptionInfo {
+    key: string;
+    scope: RateLimitExemptionScope;
+    id: string;
+    expiresInMs: number | null;
+}
+/**
+ * Hook payload for rate limit lifecycle callbacks.
+ */
+export interface RateLimitHookContext {
+    key: string;
+    result: RateLimitResult;
+    source: Interaction | Message;
+}
+/**
+ * Optional lifecycle hooks used by the plugin to surface rate limit events.
+ */
+export interface RateLimitHooks {
+    onRateLimited?: (info: RateLimitHookContext) => void | Promise<void>;
+    onAllowed?: (info: RateLimitHookContext) => void | Promise<void>;
+    onReset?: (key: string) => void | Promise<void>;
+    onViolation?: (key: string, count: number) => void | Promise<void>;
+    onStorageError?: (error: unknown, fallbackUsed: boolean) => void | Promise<void>;
+}
+/**
+ * Override for responding when a command is rate-limited.
+ */
+export type RateLimitResponseHandler = (ctx: Context, info: RateLimitStoreValue) => Promise<void> | void;
+/**
+ * Runtime plugin options consumed by RateLimitPlugin.
+ * Configure these via configureRatelimit().
+ */
+export interface RateLimitPluginOptions {
+    defaultLimiter?: RateLimitLimiterConfig;
+    limiters?: Record<string, RateLimitLimiterConfig>;
+    storage?: RateLimitStorageConfig;
+    keyPrefix?: string;
+    keyResolver?: RateLimitKeyResolver;
+    bypass?: RateLimitBypassOptions;
+    hooks?: RateLimitHooks;
+    onRateLimited?: RateLimitResponseHandler;
+    queue?: RateLimitQueueOptions;
+    roleLimits?: Record<string, RateLimitLimiterConfig>;
+    roleLimitStrategy?: RateLimitRoleLimitStrategy;
+    /**
+     * Whether to initialize the default in-memory storage if no storage is configured.
+     *
+     * @default true
+     */
+    initializeDefaultStorage?: boolean;
+    /**
+     * Alias for initializeDefaultStorage, aligned with other packages.
+     *
+     * @default true
+     */
+    initializeDefaultDriver?: boolean;
+}
+/**
+ * Aggregate results stored on the environment store for downstream handlers.
+ */
+export interface RateLimitStoreValue {
+    limited: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfter: number;
+    results: RateLimitResult[];
+}
+/**
+ * Limiter configuration after defaults are applied.
+ */
+export interface ResolvedLimiterConfig {
+    maxRequests: number;
+    intervalMs: number;
+    algorithm: RateLimitAlgorithmType;
+    scope: RateLimitScope;
+    burst: number;
+    refillRate: number;
+    leakRate: number;
+    violations?: ViolationOptions;
+    windowId?: string;
+}
+/**
+ * Active runtime context shared with APIs and directives.
+ */
+export interface RateLimitRuntimeContext {
+    storage: RateLimitStorage;
+    keyPrefix?: string;
+    defaultLimiter: RateLimitLimiterConfig;
+    limiters?: Record<string, RateLimitLimiterConfig>;
+    hooks?: RateLimitHooks;
+}

package/dist/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Rate limit type contracts.
+ *
+ * Shared config and result shapes for the plugin, engine, storage, and helpers.
+ * Keeping them in one place reduces drift between runtime behavior and docs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RATE_LIMIT_ALGORITHMS = exports.RATE_LIMIT_EXEMPTION_SCOPES = exports.RATE_LIMIT_SCOPES = void 0;
+/**
+ * Scopes used to build rate limit keys and apply per-scope limits.
+ */
+exports.RATE_LIMIT_SCOPES = [
+    'user',
+    'guild',
+    'channel',
+    'global',
+    'user-guild',
+    'custom',
+];
+/**
+ * Scopes eligible for temporary exemptions stored in rate limit storage.
+ */
+exports.RATE_LIMIT_EXEMPTION_SCOPES = [
+    'user',
+    'guild',
+    'role',
+    'channel',
+    'category',
+];
+/**
+ * Algorithm identifiers used to select the limiter implementation.
+ */
+exports.RATE_LIMIT_ALGORITHMS = [
+    'fixed-window',
+    'sliding-window',
+    'token-bucket',
+    'leaky-bucket',
+];
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7OztHQUtHOzs7QUFNSDs7R0FFRztBQUNVLFFBQUEsaUJBQWlCLEdBQUc7SUFDL0IsTUFBTTtJQUNOLE9BQU87SUFDUCxTQUFTO0lBQ1QsUUFBUTtJQUNSLFlBQVk7SUFDWixRQUFRO0NBQ0EsQ0FBQztBQU9YOztHQUVHO0FBQ1UsUUFBQSwyQkFBMkIsR0FBRztJQUN6QyxNQUFNO0lBQ04sT0FBTztJQUNQLE1BQU07SUFDTixTQUFTO0lBQ1QsVUFBVTtDQUNGLENBQUM7QUFRWDs7R0FFRztBQUNVLFFBQUEscUJBQXFCLEdBQUc7SUFDbkMsY0FBYztJQUNkLGdCQUFnQjtJQUNoQixjQUFjO0lBQ2QsY0FBYztDQUNOLENBQUMifQ==

package/dist/utils/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Limiter config resolution.
+ *
+ * Applies defaults and merges overrides into concrete limiter settings
+ * used by the engine and plugin.
+ */
+import type { RateLimitLimiterConfig, RateLimitScope, ResolvedLimiterConfig } from '../types';
+/**
+ * Default limiter used when no explicit configuration is provided.
+ */
+export declare const DEFAULT_LIMITER: RateLimitLimiterConfig;
+/**
+ * Merge limiter configs; later values override earlier ones for layering.
+ *
+ * @param configs - Limiter configs ordered from lowest to highest priority.
+ * @returns Merged limiter config with later overrides applied.
+ */
+export declare function mergeLimiterConfigs(...configs: Array<RateLimitLimiterConfig | undefined>): RateLimitLimiterConfig;
+/**
+ * Resolve a limiter config for a single scope with defaults applied.
+ *
+ * @param config - Base limiter configuration.
+ * @param scope - Scope to resolve for the limiter.
+ * @returns Resolved limiter config with defaults and derived values.
+ */
+export declare function resolveLimiterConfig(config: RateLimitLimiterConfig, scope: RateLimitScope): ResolvedLimiterConfig;
+/**
+ * Resolve limiter configs for a scope across all configured windows.
+ *
+ * @param config - Base limiter configuration that may include windows.
+ * @param scope - Scope to resolve for the limiter.
+ * @returns Resolved limiter configs for each window (or a single config).
+ */
+export declare function resolveLimiterConfigs(config: RateLimitLimiterConfig, scope: RateLimitScope): ResolvedLimiterConfig[];