enerthya.dev-antiflood 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# enerthya.dev-antiflood
+
+Rate limiter avançado para o bot Enerthya.
+
+Keyed por `commandName + userId + guildId`, com **burst window deslizante**, **penalidade progressiva** (aditiva ou exponencial) e **whitelist de cargos**.
+
+Depende de `enerthya.dev-common` para formatação de tempo — não reimplementa o que já existe.
+
+---
+
+## Instalação
+
+```bash
+npm install enerthya.dev-antiflood
+```
+
+---
+
+## Uso básico
+
+```js
+const { AntifloodManager, isBlocked, formatRetryAfter } = require("enerthya.dev-antiflood");
+
+const antiflood = new AntifloodManager({
+  globalRule: {
+    windowMs:    5000,     // janela deslizante de 5s
+    maxHits:     3,        // máximo de 3 usos nessa janela
+    penaltyMode: "ADDITIVE",
+    penaltyStep: 10000,    // +10s de penalidade por hit excedente
+    maxPenalty:  60000,    // teto de 60s de penalidade
+  },
+  whitelistRoleIds: ["ID_CARGO_ADMIN"],
+});
+
+// Dentro do handler de comando:
+const result = antiflood.check({
+  userId:        interaction.user.id,
+  guildId:       interaction.guildId,
+  commandName:   "ban",
+  memberRoleIds: interaction.member.roles.cache.map(r => r.id),
+});
+
+if (isBlocked(result)) {
+  return interaction.reply({
+    content: `Você está usando este comando rápido demais. Aguarde ${formatRetryAfter(result.retryAfterMs)}.`,
+    ephemeral: true,
+  });
+}
+```
+
+---
+
+## API
+
+### `new AntifloodManager(options?)`
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `globalRule` | `object` | veja DEFAULT_RULE | Regra aplicada quando não há regra por comando |
+| `whitelistRoleIds` | `string[]` | `[]` | Cargos que sempre passam sem checagem |
+| `enabled` | `boolean` | `true` | Master switch |
+
+#### `.setRule(commandName, ruleConfig)` → `this`
+Registra uma regra específica para um comando. Tem prioridade sobre a global.
+
+#### `.addWhitelist(...roleIds)` → `this`
+Adiciona cargos à whitelist em runtime.
+
+#### `.removeWhitelist(roleId)` → `this`
+Remove um cargo da whitelist.
+
+#### `.check({ userId, guildId?, commandName?, memberRoleIds? })`
+Retorna:
+```js
+{
+  result:       "ALLOWED" | "THROTTLED" | "PENALIZED" | "WHITELISTED",
+  retryAfterMs: number,   // ms até poder tentar de novo (0 se liberado)
+  hitsInWindow: number,   // hits acumulados na janela atual
+  penaltyUntil: number,   // timestamp fim da penalidade (0 se não há)
+  rule:         object,   // regra que foi aplicada
+}
+```
+
+#### `.reset({ userId, guildId?, commandName? })`
+Desbloqueia manualmente um usuário para um comando+guild.
+
+#### `.resetAll()`
+Limpa todo o estado (ex: restart do bot).
+
+#### `.disable()` / `.enable()`
+Liga/desliga o rate limiter globalmente.
+
+---
+
+### `createRule(config?)`
+Valida e retorna um objeto de regra frozen. Útil para criar regras de forma isolada.
+
+```js
+const { createRule, PENALTY_MODE } = require("enerthya.dev-antiflood");
+
+const strictRule = createRule({
+  windowMs:    3000,
+  maxHits:     1,
+  penaltyMode: PENALTY_MODE.EXPONENTIAL,
+  penaltyStep: 5000,
+  maxPenalty:  120000,
+});
+```
+
+---
+
+### `FLOOD_RESULT` (constantes)
+| Valor | Descrição |
+|---|---|
+| `ALLOWED` | Passou normalmente |
+| `THROTTLED` | Bloqueado até janela deslizar (sem penalidade progressiva) |
+| `PENALIZED` | Bloqueado com penalidade progressiva ativa |
+| `WHITELISTED` | Bypassed por cargo na whitelist |
+
+### `PENALTY_MODE` (constantes)
+| Valor | Comportamento |
+|---|---|
+| `NONE` | Bloqueia até a janela deslizar — sem penalidade extra |
+| `ADDITIVE` | Cada hit excedente adiciona `penaltyStep` ms à trava |
+| `EXPONENTIAL` | Cada hit excedente dobra a duração da trava (`2^n * penaltyStep`) |
+
+---
+
+### `formatRetryAfter(ms)` → `string`
+Converte ms em texto PT-BR legível. Delega para `enerthya.dev-common`.
+```
+formatRetryAfter(1500)  // "1 segundo"
+formatRetryAfter(65000) // "1 minuto, 5 segundos"
+```
+
+### `isBlocked(checkResult)` → `boolean`
+`true` se `result` é `THROTTLED` ou `PENALIZED`.
+
+---
+
+## Dependências
+
+| Pacote | Uso |
+|---|---|
+| `enerthya.dev-common` | `formatTime` para formatar retryAfterMs em PT-BR |

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "enerthya.dev-antiflood",
+  "version": "1.0.0",
+  "description": "Advanced per-user+command+guild rate limiter with burst window, progressive penalty and role whitelist.",
+  "main": "src/index.js",
+  "license": "MIT",
+  "keywords": ["ratelimit", "antiflood", "discord", "bot", "cooldown"],
+  "engines": { "node": ">=16.0.0" },
+  "dependencies": {
+    "enerthya.dev-common": "1.0.0"
+  }
+}

package/src/constants/index.js

@@ -0,0 +1,25 @@
+// Antiflood — constants
+
+const FLOOD_RESULT = Object.freeze({
+  ALLOWED:   "ALLOWED",   // request passed
+  THROTTLED: "THROTTLED", // rate limit exceeded — caller should reject
+  PENALIZED: "PENALIZED", // rate limit exceeded + progressive penalty applied
+  WHITELISTED: "WHITELISTED", // bypassed due to whitelist
+});
+
+const PENALTY_MODE = Object.freeze({
+  NONE:        "NONE",        // no progressive penalty — just block until window expires
+  ADDITIVE:    "ADDITIVE",    // each excess hit adds penaltyStep ms to the lock
+  EXPONENTIAL: "EXPONENTIAL", // each excess hit doubles the lock duration
+});
+
+// Default rule applied when no custom config is provided
+const DEFAULT_RULE = Object.freeze({
+  windowMs:    5000,  // sliding window size in ms
+  maxHits:     3,     // allowed hits per window
+  penaltyMode: PENALTY_MODE.ADDITIVE,
+  penaltyStep: 5000,  // ms added per excess hit (ADDITIVE) or base for EXPONENTIAL
+  maxPenalty:  60000, // hard cap on penalty duration (ms)
+});
+
+module.exports = { FLOOD_RESULT, PENALTY_MODE, DEFAULT_RULE };

package/src/core/AntifloodManager.js

@@ -0,0 +1,185 @@
+// AntifloodManager — central rate limiter.
+// Keyed by: commandName + userId + guildId  (any field can be wildcarded with "*")
+// Whitelisted roleIds bypass all checks.
+
+const { BucketStore } = require("./BucketStore");
+const { createRule }  = require("./AntifloodRule");
+const { FLOOD_RESULT, PENALTY_MODE, DEFAULT_RULE } = require("../constants");
+
+class AntifloodManager {
+  /**
+   * @param {object} [options]
+   * @param {object} [options.globalRule]  — default rule applied when no command-level rule matches
+   * @param {Set<string>|string[]} [options.whitelistRoleIds] — roleIds that always bypass flood checks
+   * @param {boolean} [options.enabled]   — master switch (default true)
+   */
+  constructor(options = {}) {
+    this._globalRule     = createRule(options.globalRule || {});
+    this._commandRules   = new Map(); // commandName → rule
+    this._store          = new BucketStore();
+    this._whitelist      = new Set(options.whitelistRoleIds || []);
+    this._enabled        = options.enabled !== false;
+  }
+
+  // ── Configuration ─────────────────────────────────────────────────────────
+
+  /**
+   * Register a per-command rule. Overrides the global rule for that command.
+   * @param {string} commandName
+   * @param {object} ruleConfig
+   */
+  setRule(commandName, ruleConfig) {
+    this._commandRules.set(commandName, createRule(ruleConfig));
+    return this;
+  }
+
+  /**
+   * Add one or more roleIds to the whitelist.
+   * @param {...string} roleIds
+   */
+  addWhitelist(...roleIds) {
+    for (const id of roleIds) this._whitelist.add(String(id));
+    return this;
+  }
+
+  /**
+   * Remove a roleId from the whitelist.
+   * @param {string} roleId
+   */
+  removeWhitelist(roleId) {
+    this._whitelist.delete(String(roleId));
+    return this;
+  }
+
+  /** Disable all flood checks (e.g. during maintenance). */
+  disable() { this._enabled = false; return this; }
+
+  /** Re-enable flood checks. */
+  enable()  { this._enabled = true;  return this; }
+
+  // ── Check ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if the given request should be allowed or throttled.
+   *
+   * @param {object} params
+   * @param {string} params.userId
+   * @param {string} [params.guildId]        — optional; included in key for guild isolation
+   * @param {string} [params.commandName]    — optional; used to look up per-command rule
+   * @param {string[]} [params.memberRoleIds] — user's current roles, checked against whitelist
+   *
+   * @returns {{
+   *   result: string,         // FLOOD_RESULT value
+   *   retryAfterMs: number,   // ms until the user can try again (0 if ALLOWED/WHITELISTED)
+   *   hitsInWindow: number,   // how many hits recorded in current window
+   *   penaltyUntil: number,   // timestamp when penalty expires (0 if none)
+   *   rule: object            // the rule that was applied
+   * }}
+   */
+  check({ userId, guildId = "*", commandName = "*", memberRoleIds = [] }) {
+    // Master switch
+    if (!this._enabled) {
+      return this._buildResult(FLOOD_RESULT.ALLOWED, 0, 0, 0, this._globalRule);
+    }
+
+    // Whitelist check — any matching roleId bypasses everything
+    for (const rid of memberRoleIds) {
+      if (this._whitelist.has(String(rid))) {
+        return this._buildResult(FLOOD_RESULT.WHITELISTED, 0, 0, 0, this._globalRule);
+      }
+    }
+
+    const rule = this._commandRules.get(commandName) || this._globalRule;
+    const key  = this._buildKey(commandName, userId, guildId);
+    const now  = Date.now();
+
+    // Try to reset expired penalty first
+    this._store.tryResetPenalty(key, now);
+
+    // Prune stale hits from the sliding window
+    this._store.prune(key, rule.windowMs, now);
+
+    const bucket = this._store.get(key);
+
+    // ── Active penalty lock ──────────────────────────────────────────────────
+    if (bucket.penaltyUntil > now) {
+      return this._buildResult(
+        FLOOD_RESULT.PENALIZED,
+        bucket.penaltyUntil - now,
+        bucket.hits.length,
+        bucket.penaltyUntil,
+        rule,
+      );
+    }
+
+    // ── Hit is within quota ──────────────────────────────────────────────────
+    if (bucket.hits.length < rule.maxHits) {
+      this._store.addHit(key, now);
+      return this._buildResult(FLOOD_RESULT.ALLOWED, 0, bucket.hits.length, 0, rule);
+    }
+
+    // ── Quota exceeded ───────────────────────────────────────────────────────
+    if (rule.penaltyMode === PENALTY_MODE.NONE) {
+      // No progressive penalty — just block until the window slides
+      const oldestHit    = bucket.hits[0];
+      const retryAfterMs = rule.windowMs - (now - oldestHit);
+      return this._buildResult(
+        FLOOD_RESULT.THROTTLED,
+        Math.max(retryAfterMs, 0),
+        bucket.hits.length,
+        0,
+        rule,
+      );
+    }
+
+    // Progressive penalty
+    this._store.addHit(key, now);
+    const penaltyUntil = this._store.applyPenalty(
+      key,
+      rule.penaltyMode,
+      rule.penaltyStep,
+      rule.maxPenalty,
+      now,
+    );
+
+    return this._buildResult(
+      FLOOD_RESULT.PENALIZED,
+      penaltyUntil - now,
+      bucket.hits.length,
+      penaltyUntil,
+      rule,
+    );
+  }
+
+  // ── Manual controls ───────────────────────────────────────────────────────
+
+  /**
+   * Manually reset a user's flood state for a given command + guild.
+   * Use this when a DEV/OWNER wants to unblock someone immediately.
+   */
+  reset({ userId, guildId = "*", commandName = "*" }) {
+    this._store.reset(this._buildKey(commandName, userId, guildId));
+  }
+
+  /** Reset all flood state (e.g. on bot restart). */
+  resetAll() {
+    this._store.clear();
+  }
+
+  /** @returns {number} number of active tracked buckets. */
+  get activeBuckets() {
+    return this._store.size;
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────────
+
+  _buildKey(commandName, userId, guildId) {
+    return `${commandName}|${userId}|${guildId}`;
+  }
+
+  _buildResult(result, retryAfterMs, hitsInWindow, penaltyUntil, rule) {
+    return { result, retryAfterMs: Math.ceil(retryAfterMs), hitsInWindow, penaltyUntil, rule };
+  }
+}
+
+module.exports = { AntifloodManager };

package/src/core/AntifloodRule.js

@@ -0,0 +1,39 @@
+// AntifloodRule — merges user-supplied config with defaults and validates it.
+
+const { DEFAULT_RULE, PENALTY_MODE } = require("../constants");
+
+/**
+ * Build a validated rule object from user-supplied partial config.
+ * All fields are optional — defaults are applied for missing ones.
+ *
+ * @param {object} [config]
+ * @param {number} [config.windowMs]
+ * @param {number} [config.maxHits]
+ * @param {string} [config.penaltyMode]
+ * @param {number} [config.penaltyStep]
+ * @param {number} [config.maxPenalty]
+ * @returns {{ windowMs: number, maxHits: number, penaltyMode: string, penaltyStep: number, maxPenalty: number }}
+ */
+function createRule(config = {}) {
+  const rule = Object.assign({}, DEFAULT_RULE, config);
+
+  if (typeof rule.windowMs !== "number" || rule.windowMs <= 0) {
+    throw new Error(`[antiflood] windowMs must be a positive number, got: ${rule.windowMs}`);
+  }
+  if (typeof rule.maxHits !== "number" || rule.maxHits < 1) {
+    throw new Error(`[antiflood] maxHits must be >= 1, got: ${rule.maxHits}`);
+  }
+  if (!Object.values(PENALTY_MODE).includes(rule.penaltyMode)) {
+    throw new Error(`[antiflood] penaltyMode must be one of ${Object.values(PENALTY_MODE).join(", ")}, got: ${rule.penaltyMode}`);
+  }
+  if (typeof rule.penaltyStep !== "number" || rule.penaltyStep < 0) {
+    throw new Error(`[antiflood] penaltyStep must be >= 0, got: ${rule.penaltyStep}`);
+  }
+  if (typeof rule.maxPenalty !== "number" || rule.maxPenalty < 0) {
+    throw new Error(`[antiflood] maxPenalty must be >= 0, got: ${rule.maxPenalty}`);
+  }
+
+  return Object.freeze(rule);
+}
+
+module.exports = { createRule };

package/src/core/BucketStore.js

@@ -0,0 +1,110 @@
+// BucketStore — stores sliding-window hit timestamps + penalty state per key.
+// Each bucket: { hits: number[], penaltyUntil: number, excessCount: number }
+
+class BucketStore {
+  constructor() {
+    /** @type {Map<string, { hits: number[], penaltyUntil: number, excessCount: number }>} */
+    this._store = new Map();
+  }
+
+  /**
+   * Get or create a bucket for the given key.
+   * @param {string} key
+   */
+  get(key) {
+    if (!this._store.has(key)) {
+      this._store.set(key, { hits: [], penaltyUntil: 0, excessCount: 0 });
+    }
+    return this._store.get(key);
+  }
+
+  /**
+   * Prune hits outside the sliding window and remove stale buckets.
+   * Should be called before every check to keep memory bounded.
+   * @param {string} key
+   * @param {number} windowMs
+   * @param {number} now
+   */
+  prune(key, windowMs, now) {
+    const bucket = this._store.get(key);
+    if (!bucket) return;
+
+    bucket.hits = bucket.hits.filter(ts => now - ts < windowMs);
+
+    // Remove bucket entirely if it has no hits and no active penalty
+    if (bucket.hits.length === 0 && bucket.penaltyUntil <= now) {
+      this._store.delete(key);
+    }
+  }
+
+  /**
+   * Add a hit timestamp to the bucket.
+   * @param {string} key
+   * @param {number} now
+   */
+  addHit(key, now) {
+    const bucket = this.get(key);
+    bucket.hits.push(now);
+  }
+
+  /**
+   * Apply progressive penalty based on excess hits.
+   * @param {string} key
+   * @param {"ADDITIVE"|"EXPONENTIAL"} mode
+   * @param {number} step  — ms per excess hit (ADDITIVE) or base ms (EXPONENTIAL)
+   * @param {number} max   — hard cap in ms
+   * @param {number} now
+   * @returns {number} penaltyUntil timestamp
+   */
+  applyPenalty(key, mode, step, max, now) {
+    const bucket = this.get(key);
+    bucket.excessCount += 1;
+
+    let addedMs;
+    if (mode === "EXPONENTIAL") {
+      // 2^(excessCount-1) * step, capped at max
+      addedMs = Math.min(Math.pow(2, bucket.excessCount - 1) * step, max);
+    } else {
+      // ADDITIVE: excessCount * step, capped at max
+      addedMs = Math.min(bucket.excessCount * step, max);
+    }
+
+    // Penalty stacks from current time, not from previous penaltyUntil
+    bucket.penaltyUntil = now + addedMs;
+    return bucket.penaltyUntil;
+  }
+
+  /**
+   * Reset excess counter after the penalty expires.
+   * @param {string} key
+   * @param {number} now
+   */
+  tryResetPenalty(key, now) {
+    const bucket = this._store.get(key);
+    if (!bucket) return;
+    if (bucket.penaltyUntil > 0 && bucket.penaltyUntil <= now) {
+      bucket.excessCount = 0;
+      bucket.penaltyUntil = 0;
+    }
+  }
+
+  /**
+   * Fully reset a key (e.g. when a DEV clears a user's flood state).
+   * @param {string} key
+   */
+  reset(key) {
+    this._store.delete(key);
+  }
+
+  /** @returns {number} total tracked buckets */
+  get size() {
+    return this._store.size;
+  }
+
+  /** Clear all buckets (for tests / restart). */
+  clear() {
+    this._store.clear();
+  }
+}
+
+module.exports = { BucketStore };

package/src/index.js

@@ -0,0 +1,28 @@
+// enerthya.dev-antiflood
+// Advanced per-user+command+guild rate limiter with burst window,
+// progressive penalty (additive or exponential) and role whitelist.
+// Zero dependencies. Node.js only.
+
+const { AntifloodManager } = require("./core/AntifloodManager");
+const { BucketStore }       = require("./core/BucketStore");
+const { createRule }         = require("./core/AntifloodRule");
+const { FLOOD_RESULT, PENALTY_MODE, DEFAULT_RULE } = require("./constants");
+const { formatRetryAfter, isBlocked } = require("./utils");
+
+module.exports = {
+  // Main class
+  AntifloodManager,
+
+  // Building blocks (for advanced usage / testing)
+  BucketStore,
+  createRule,
+
+  // Constants
+  FLOOD_RESULT,
+  PENALTY_MODE,
+  DEFAULT_RULE,
+
+  // Utilities
+  formatRetryAfter,
+  isBlocked,
+};

package/src/utils/index.js

@@ -0,0 +1,28 @@
+// Utility helpers for antiflood consumers.
+
+// formatTime is already implemented (and well-tested) in enerthya.dev-common.
+// We import from there instead of reimplementing — per rule P16a.
+const { formatTime } = require("enerthya.dev-common");
+
+/**
+ * Format retryAfterMs into a human-readable Portuguese string.
+ * Delegates to enerthya.dev-common's formatTime (seconds → PT-BR).
+ * e.g. 1500 → "1 segundo"  |  65000 → "1 minuto, 5 segundos"
+ *
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatRetryAfter(ms) {
+  return formatTime(Math.ceil(ms / 1000));
+}
+
+/**
+ * Return true when the check result means the request should be blocked.
+ * @param {{ result: string }} checkResult
+ * @returns {boolean}
+ */
+function isBlocked(checkResult) {
+  return checkResult.result === "THROTTLED" || checkResult.result === "PENALIZED";
+}
+
+module.exports = { formatRetryAfter, isBlocked };

package/test.js

@@ -0,0 +1,371 @@
+// enerthya.dev-antiflood — test suite
+// Run: node test.js
+// Uses only Node.js built-in assert. Zero external test runners.
+
+const assert = require("assert");
+
+const {
+  AntifloodManager,
+  BucketStore,
+  createRule,
+  FLOOD_RESULT,
+  PENALTY_MODE,
+  DEFAULT_RULE,
+  formatRetryAfter,
+  isBlocked,
+} = require("./src");
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  ✗ ${name}`);
+    console.error(`    ${err.message}`);
+    failed++;
+  }
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────
+
+console.log("\n[FLOOD_RESULT]");
+test("has ALLOWED",      () => assert.strictEqual(FLOOD_RESULT.ALLOWED,     "ALLOWED"));
+test("has THROTTLED",    () => assert.strictEqual(FLOOD_RESULT.THROTTLED,   "THROTTLED"));
+test("has PENALIZED",    () => assert.strictEqual(FLOOD_RESULT.PENALIZED,   "PENALIZED"));
+test("has WHITELISTED",  () => assert.strictEqual(FLOOD_RESULT.WHITELISTED, "WHITELISTED"));
+test("is frozen",        () => assert.ok(Object.isFrozen(FLOOD_RESULT)));
+
+console.log("\n[PENALTY_MODE]");
+test("has NONE",        () => assert.strictEqual(PENALTY_MODE.NONE,        "NONE"));
+test("has ADDITIVE",    () => assert.strictEqual(PENALTY_MODE.ADDITIVE,    "ADDITIVE"));
+test("has EXPONENTIAL", () => assert.strictEqual(PENALTY_MODE.EXPONENTIAL, "EXPONENTIAL"));
+
+// ── createRule ─────────────────────────────────────────────────────────────
+
+console.log("\n[createRule]");
+test("returns defaults when called with no args", () => {
+  const r = createRule();
+  assert.strictEqual(r.windowMs,    DEFAULT_RULE.windowMs);
+  assert.strictEqual(r.maxHits,     DEFAULT_RULE.maxHits);
+  assert.strictEqual(r.penaltyMode, DEFAULT_RULE.penaltyMode);
+});
+test("overrides specific fields", () => {
+  const r = createRule({ maxHits: 10, windowMs: 2000 });
+  assert.strictEqual(r.maxHits,  10);
+  assert.strictEqual(r.windowMs, 2000);
+  assert.strictEqual(r.penaltyMode, DEFAULT_RULE.penaltyMode); // kept default
+});
+test("throws on invalid windowMs", () => {
+  assert.throws(() => createRule({ windowMs: -1 }), /windowMs/);
+});
+test("throws on invalid maxHits", () => {
+  assert.throws(() => createRule({ maxHits: 0 }), /maxHits/);
+});
+test("throws on unknown penaltyMode", () => {
+  assert.throws(() => createRule({ penaltyMode: "INVALID" }), /penaltyMode/);
+});
+test("frozen result", () => assert.ok(Object.isFrozen(createRule())));
+
+// ── BucketStore ────────────────────────────────────────────────────────────
+
+console.log("\n[BucketStore]");
+test("creates empty bucket on first get", () => {
+  const s = new BucketStore();
+  const b = s.get("k");
+  assert.deepStrictEqual(b.hits, []);
+  assert.strictEqual(b.penaltyUntil, 0);
+  assert.strictEqual(b.excessCount, 0);
+});
+test("addHit pushes timestamp", () => {
+  const s = new BucketStore();
+  s.addHit("k", 1000);
+  s.addHit("k", 2000);
+  assert.strictEqual(s.get("k").hits.length, 2);
+});
+test("prune removes hits outside window", () => {
+  const s = new BucketStore();
+  s.addHit("k", 1000);
+  s.addHit("k", 2000);
+  s.prune("k", 500, 2100); // window=500ms, now=2100 → only hit at 2000 survives
+  assert.strictEqual(s.get("k").hits.length, 1);
+});
+test("prune deletes stale bucket entirely", () => {
+  const s = new BucketStore();
+  s.addHit("k", 1000);
+  s.prune("k", 100, 5000); // all hits expired, no penalty
+  assert.strictEqual(s.size, 0);
+});
+test("applyPenalty ADDITIVE increases by step * excessCount", () => {
+  const s = new BucketStore();
+  const now = Date.now();
+  s.applyPenalty("k", "ADDITIVE", 5000, 60000, now);
+  assert.ok(s.get("k").penaltyUntil > now);
+  assert.strictEqual(s.get("k").excessCount, 1);
+});
+test("applyPenalty EXPONENTIAL doubles each call", () => {
+  const s = new BucketStore();
+  const now = 10000;
+  s.applyPenalty("k", "EXPONENTIAL", 1000, 60000, now);
+  const p1 = s.get("k").penaltyUntil;
+  s.applyPenalty("k", "EXPONENTIAL", 1000, 60000, now);
+  const p2 = s.get("k").penaltyUntil;
+  // second call: 2^1 * 1000 = 2000ms added vs first 2^0 * 1000 = 1000ms
+  assert.ok(p2 - now > p1 - now);
+});
+test("applyPenalty respects maxPenalty cap", () => {
+  const s = new BucketStore();
+  const now = 0;
+  // 100 excess hits with step=100000, max=5000 — should be capped
+  for (let i = 0; i < 100; i++) s.applyPenalty("k", "ADDITIVE", 100000, 5000, now);
+  assert.ok(s.get("k").penaltyUntil <= now + 5000);
+});
+test("reset deletes key", () => {
+  const s = new BucketStore();
+  s.addHit("k", 1000);
+  s.reset("k");
+  assert.strictEqual(s.size, 0);
+});
+test("clear empties all buckets", () => {
+  const s = new BucketStore();
+  s.addHit("a", 1000);
+  s.addHit("b", 2000);
+  s.clear();
+  assert.strictEqual(s.size, 0);
+});
+test("tryResetPenalty clears excessCount when penalty expired", () => {
+  const s = new BucketStore();
+  const bucket = s.get("k");
+  bucket.penaltyUntil = 1000;
+  bucket.excessCount  = 5;
+  s.tryResetPenalty("k", 2000); // now > penaltyUntil
+  assert.strictEqual(s.get("k").excessCount, 0);
+});
+test("tryResetPenalty does not clear if penalty still active", () => {
+  const s = new BucketStore();
+  const bucket = s.get("k");
+  bucket.penaltyUntil = 9999999999;
+  bucket.excessCount  = 3;
+  s.tryResetPenalty("k", 1000);
+  assert.strictEqual(s.get("k").excessCount, 3);
+});
+
+// ── AntifloodManager — basic flow ──────────────────────────────────────────
+
+console.log("\n[AntifloodManager — basic flow]");
+test("allows hits within maxHits", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 3 } });
+  for (let i = 0; i < 3; i++) {
+    const r = af.check({ userId: "u1", commandName: "ping" });
+    assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED, `hit ${i + 1} should be ALLOWED`);
+  }
+});
+test("throttles on 4th hit with NONE penalty", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 3, penaltyMode: "NONE" } });
+  for (let i = 0; i < 3; i++) af.check({ userId: "u1" });
+  const r = af.check({ userId: "u1" });
+  assert.strictEqual(r.result, FLOOD_RESULT.THROTTLED);
+  assert.ok(r.retryAfterMs > 0);
+});
+test("penalizes on 4th hit with ADDITIVE penalty", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 3, penaltyMode: "ADDITIVE", penaltyStep: 5000 } });
+  for (let i = 0; i < 3; i++) af.check({ userId: "u1" });
+  const r = af.check({ userId: "u1" });
+  assert.strictEqual(r.result, FLOOD_RESULT.PENALIZED);
+  assert.ok(r.penaltyUntil > Date.now());
+});
+test("penalized user stays blocked on next check", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 2, penaltyMode: "ADDITIVE", penaltyStep: 60000 } });
+  for (let i = 0; i < 2; i++) af.check({ userId: "u1" });
+  af.check({ userId: "u1" }); // triggers penalty
+  const r = af.check({ userId: "u1" });
+  assert.strictEqual(r.result, FLOOD_RESULT.PENALIZED);
+});
+test("independent users don't affect each other", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 2 } });
+  af.check({ userId: "u1" });
+  af.check({ userId: "u1" });
+  af.check({ userId: "u1" }); // u1 gets throttled/penalized
+  const r = af.check({ userId: "u2" }); // u2 unaffected
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+});
+test("different guilds are isolated", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 2 } });
+  af.check({ userId: "u1", guildId: "g1" });
+  af.check({ userId: "u1", guildId: "g1" });
+  af.check({ userId: "u1", guildId: "g1" }); // g1 throttled
+  const r = af.check({ userId: "u1", guildId: "g2" });
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+});
+test("different commands are isolated", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 2 } });
+  af.check({ userId: "u1", commandName: "ban" });
+  af.check({ userId: "u1", commandName: "ban" });
+  af.check({ userId: "u1", commandName: "ban" }); // ban throttled
+  const r = af.check({ userId: "u1", commandName: "ping" });
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+});
+test("returns correct hitsInWindow count", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 5 } });
+  af.check({ userId: "u1" });
+  af.check({ userId: "u1" });
+  const r = af.check({ userId: "u1" });
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+  assert.ok(r.hitsInWindow >= 2);
+});
+
+// ── AntifloodManager — per-command rules ──────────────────────────────────
+
+console.log("\n[AntifloodManager — per-command rules]");
+test("per-command rule overrides global rule", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 10 } });
+  af.setRule("ban", { windowMs: 10000, maxHits: 1, penaltyMode: "NONE" });
+  af.check({ userId: "u1", commandName: "ban" });
+  const r = af.check({ userId: "u1", commandName: "ban" });
+  assert.strictEqual(r.result, FLOOD_RESULT.THROTTLED); // stricter rule applied
+});
+test("global rule unaffected by per-command rule", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 10 } });
+  af.setRule("ban", { windowMs: 10000, maxHits: 1, penaltyMode: "NONE" });
+  for (let i = 0; i < 9; i++) af.check({ userId: "u1", commandName: "ping" });
+  const r = af.check({ userId: "u1", commandName: "ping" }); // 10th hit — within maxHits: 10
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+});
+test("setRule returns manager (chainable)", () => {
+  const af = new AntifloodManager();
+  const ret = af.setRule("cmd", { maxHits: 5 });
+  assert.strictEqual(ret, af);
+});
+
+// ── AntifloodManager — whitelist ───────────────────────────────────────────
+
+console.log("\n[AntifloodManager — whitelist]");
+test("whitelisted role bypasses flood check", () => {
+  const af = new AntifloodManager({
+    globalRule: { windowMs: 10000, maxHits: 1 },
+    whitelistRoleIds: ["role_admin"],
+  });
+  for (let i = 0; i < 20; i++) {
+    const r = af.check({ userId: "u1", memberRoleIds: ["role_admin"] });
+    assert.strictEqual(r.result, FLOOD_RESULT.WHITELISTED);
+  }
+});
+test("non-whitelisted role is not bypassed", () => {
+  const af = new AntifloodManager({
+    globalRule: { windowMs: 10000, maxHits: 1, penaltyMode: "NONE" },
+    whitelistRoleIds: ["role_admin"],
+  });
+  af.check({ userId: "u1", memberRoleIds: ["role_member"] });
+  const r = af.check({ userId: "u1", memberRoleIds: ["role_member"] });
+  assert.strictEqual(r.result, FLOOD_RESULT.THROTTLED);
+});
+test("addWhitelist adds role at runtime", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 1 } });
+  af.addWhitelist("role_mod");
+  const r = af.check({ userId: "u1", memberRoleIds: ["role_mod"] });
+  assert.strictEqual(r.result, FLOOD_RESULT.WHITELISTED);
+});
+test("removeWhitelist removes role", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 1 }, whitelistRoleIds: ["role_x"] });
+  af.removeWhitelist("role_x");
+  af.check({ userId: "u1", memberRoleIds: ["role_x"] });
+  const r = af.check({ userId: "u1", memberRoleIds: ["role_x"] });
+  assert.notStrictEqual(r.result, FLOOD_RESULT.WHITELISTED);
+});
+test("addWhitelist is chainable", () => {
+  const af = new AntifloodManager();
+  const ret = af.addWhitelist("r1");
+  assert.strictEqual(ret, af);
+});
+
+// ── AntifloodManager — master switch ──────────────────────────────────────
+
+console.log("\n[AntifloodManager — master switch]");
+test("disabled manager always returns ALLOWED", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 1 } });
+  af.disable();
+  for (let i = 0; i < 10; i++) {
+    const r = af.check({ userId: "u1" });
+    assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+  }
+});
+test("re-enabling resumes checks", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 1, penaltyMode: "NONE" } });
+  af.disable();
+  af.check({ userId: "u1" }); // should not count
+  af.check({ userId: "u1" });
+  af.enable();
+  af.check({ userId: "u1" }); // hit 1
+  const r = af.check({ userId: "u1" }); // hit 2 → throttled
+  assert.strictEqual(r.result, FLOOD_RESULT.THROTTLED);
+});
+
+// ── AntifloodManager — manual reset ───────────────────────────────────────
+
+console.log("\n[AntifloodManager — manual reset]");
+test("reset unblocks a throttled user", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 1, penaltyMode: "NONE" } });
+  af.check({ userId: "u1", commandName: "ban" });
+  af.check({ userId: "u1", commandName: "ban" }); // throttled
+  af.reset({ userId: "u1", commandName: "ban" });
+  const r = af.check({ userId: "u1", commandName: "ban" });
+  assert.strictEqual(r.result, FLOOD_RESULT.ALLOWED);
+});
+test("resetAll clears all state", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 2 } });
+  af.check({ userId: "u1" });
+  af.check({ userId: "u2" });
+  af.resetAll();
+  assert.strictEqual(af.activeBuckets, 0);
+});
+test("activeBuckets reflects current state", () => {
+  const af = new AntifloodManager({ globalRule: { windowMs: 10000, maxHits: 5 } });
+  assert.strictEqual(af.activeBuckets, 0);
+  af.check({ userId: "u1" });
+  af.check({ userId: "u2" });
+  assert.ok(af.activeBuckets >= 2);
+});
+
+// ── EXPONENTIAL penalty ────────────────────────────────────────────────────
+
+console.log("\n[AntifloodManager — EXPONENTIAL penalty]");
+test("exponential penalty grows on repeated violations", () => {
+  const af = new AntifloodManager({
+    globalRule: { windowMs: 60000, maxHits: 2, penaltyMode: "EXPONENTIAL", penaltyStep: 1000, maxPenalty: 999999 },
+  });
+  af.check({ userId: "u1" });
+  af.check({ userId: "u1" });
+  const r1 = af.check({ userId: "u1" }); // 1st excess → penaltyUntil = now + 2^0*1000
+  const r2 = af.check({ userId: "u1" }); // 2nd excess → penaltyUntil = now + 2^1*1000
+  assert.strictEqual(r1.result, FLOOD_RESULT.PENALIZED);
+  assert.strictEqual(r2.result, FLOOD_RESULT.PENALIZED);
+  assert.ok(r2.penaltyUntil >= r1.penaltyUntil);
+});
+
+// ── Utilities ─────────────────────────────────────────────────────────────
+
+console.log("\n[formatRetryAfter — delegates to enerthya.dev-common]");
+test("formats 1000ms as 1 segundo",    () => assert.ok(formatRetryAfter(1000).includes("segundo")));
+test("formats 60000ms includes minuto",() => assert.ok(formatRetryAfter(60000).includes("minuto")));
+test("formats 0ms as 0 segundos",      () => assert.strictEqual(formatRetryAfter(0), "0 segundos"));
+test("rounds up fractional seconds",   () => assert.ok(formatRetryAfter(1500).includes("segundo")));
+
+console.log("\n[isBlocked]");
+test("THROTTLED → true",   () => assert.strictEqual(isBlocked({ result: "THROTTLED" }),   true));
+test("PENALIZED → true",   () => assert.strictEqual(isBlocked({ result: "PENALIZED" }),   true));
+test("ALLOWED → false",    () => assert.strictEqual(isBlocked({ result: "ALLOWED" }),     false));
+test("WHITELISTED → false",() => assert.strictEqual(isBlocked({ result: "WHITELISTED" }), false));
+
+// ── Summary ────────────────────────────────────────────────────────────────
+
+console.log(`\n${"─".repeat(45)}`);
+console.log(`  ${passed + failed} tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  console.error("  ❌ SOME TESTS FAILED");
+  process.exit(1);
+} else {
+  console.log("  ✅ ALL TESTS PASSED");
+}