nextlimiter 1.0.6 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.6",
+  "version": "1.2.0",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/core/accessControl.js

@@ -21,14 +21,16 @@ const { ipMatchesList } = require('../utils/cidr');
  * checkAccess('1.2.3.4', {})
  * // → { action: 'allow', reason: 'proceed' }
  */
-function checkAccess(ip, config) {
+function checkAccess(ip, config, emitter) {
   // Blacklist wins — always checked first regardless of whitelist
   if (config.blacklist && ipMatchesList(ip, config.blacklist)) {
+    if (emitter) emitter.emit('blacklisted', ip);
     return { action: 'block', reason: 'blacklisted' };
   }
 
   // Whitelist — bypass all rate limiting
   if (config.whitelist && ipMatchesList(ip, config.whitelist)) {
+    if (emitter) emitter.emit('whitelisted', ip);
     return { action: 'skip', reason: 'whitelisted' };
   }
 

package/src/core/config.js

@@ -87,6 +87,16 @@ const DEFAULT_CONFIG = {
   keyGenerator: null,       // (req) => string — custom key fn
   whitelist:     null,       // string[] — IPs/CIDRs that bypass rate limiting
   blacklist:     null,       // string[] — IPs/CIDRs that always get 403
+  statsInterval: undefined,  // ms interval to emit 'stats' event
+
+  rules:         null,       // RuleConfig[] — multiple rate limit constraints
+  schedule:      null,       // ScheduleEntry[] — time-based config overrides
+
+  webhook:           null,
+  webhookRetries:    3,
+  webhookBackoff:    'exponential',
+  webhookTimeout:    5000,
+  webhookSecret:     null,
 };
 
 /**
@@ -97,13 +107,31 @@ const DEFAULT_CONFIG = {
 function resolveConfig(userOptions = {}) {
   let base = { ...DEFAULT_CONFIG };
 
-  // Apply named preset first (lowest priority)
-  if (userOptions.preset && PRESETS[userOptions.preset]) {
-    base = { ...base, ...PRESETS[userOptions.preset] };
+  // Apply preset
+  if (userOptions.preset) { // Use userOptions.preset here to ensure it's applied
+    const presetCfg = PRESETS[userOptions.preset];
+    if (!presetCfg) throw new Error(`[NextLimiter] Unknown preset: ${userOptions.preset}`);
+    // Merge preset config into base, allowing userOptions to override later
+    base = { ...base, ...presetCfg };
+  }
+
+  // Mutually exclusive core configurations
+  const hasRules = userOptions.rules !== undefined && userOptions.rules !== null;
+  const hasSchedule = userOptions.schedule !== undefined && userOptions.schedule !== null;
+  const hasMax = userOptions.max !== undefined && userOptions.max !== null;
+
+  if (hasRules && hasSchedule) {
+    throw new Error('[NextLimiter] config.rules and config.schedule are mutually exclusive.');
+  }
+  if (hasRules && hasMax) {
+    throw new Error('[NextLimiter] config.max/windowMs and config.rules are mutually exclusive.');
+  }
+  if (hasSchedule && hasMax) {
+    throw new Error('[NextLimiter] config.max/windowMs and config.schedule are mutually exclusive.');
   }
 
-  // Merge user options
-  base = { ...base, ...userOptions };
+  // Apply user overrides
+  Object.assign(base, userOptions);
 
   // Apply plan limits (overrides windowMs and max if plan is set)
   if (base.plan) {
@@ -119,9 +147,45 @@ function resolveConfig(userOptions = {}) {
     base._burstMax = planCfg.burstMax;
   }
 
-  // Validate
-  if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
-  if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  // Deep validate
+  if (base.rules) {
+    if (!Array.isArray(base.rules) || base.rules.length === 0) {
+      throw new Error('[NextLimiter] config.rules must be a non-empty array.');
+    }
+    for (const rule of base.rules) {
+      if (!rule.keyBy) throw new Error('[NextLimiter] Each rule must have a keyBy property.');
+      if (typeof rule.max !== 'number' || rule.max <= 0) throw new Error('[NextLimiter] Each rule must have a positive max integer.');
+      if (typeof rule.windowMs !== 'number' || rule.windowMs <= 0) throw new Error('[NextLimiter] Each rule must have a positive windowMs integer.');
+    }
+  } else if (base.schedule) {
+    if (!Array.isArray(base.schedule) || base.schedule.length === 0) {
+      throw new Error('[NextLimiter] config.schedule must be a non-empty array.');
+    }
+    let prevEnd = -1;
+    for (let i = 0; i < base.schedule.length; i++) {
+        const entry = base.schedule[i];
+        if (!entry.hours) throw new Error('[NextLimiter] Each schedule entry must have an hours string (e.g., "9-17").');
+        if (typeof entry.max !== 'number' || entry.max <= 0) throw new Error('[NextLimiter] Each schedule entry must have a positive max integer.');
+        
+        const match = /^\s*(\d{1,2})\s*-\s*(\d{1,2})\s*$/.exec(entry.hours);
+        if (!match) throw new Error(`[NextLimiter] Invalid hours format: ${entry.hours}`);
+        let s = parseInt(match[1], 10), e = parseInt(match[2], 10);
+        if (s < 0 || s > 23 || e < 0 || e > 23) throw new Error('[NextLimiter] Schedule hours must be between 0 and 23. Got: ' + entry.hours);
+        if (e < s) throw new Error(`[NextLimiter] Invalid schedule: end hour (${e}) cannot be less than start hour (${s}).`);
+        
+        // Basic overlap check
+        if (s <= prevEnd) console.warn(`[NextLimiter] Warning: Overlapping schedule entries detected.`);
+        prevEnd = e;
+    }
+    if (prevEnd < 23) console.warn(`[NextLimiter] Warning: Schedule entries do not cover a full 24-hr cycle.`);
+    // Base max/windowMs must still be valid for fallback
+    if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
+    if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  } else {
+    // Standard mode validation
+    if (base.max <= 0) throw new Error('[NextLimiter] config.max must be greater than 0');
+    if (base.windowMs <= 0) throw new Error('[NextLimiter] config.windowMs must be greater than 0');
+  }
 
   // Validate whitelist / blacklist (warn, never throw)
   for (const listName of ['whitelist', 'blacklist']) {
@@ -147,6 +211,29 @@ function resolveConfig(userOptions = {}) {
     base[listName] = valid.length > 0 ? valid : null;
   }
 
+  // Validate statsInterval
+  if (base.statsInterval !== undefined) {
+    if (typeof base.statsInterval !== 'number' || base.statsInterval <= 0) {
+      console.warn('[NextLimiter] config.statsInterval must be a positive number. Disabling.');
+      base.statsInterval = undefined;
+    } else if (base.statsInterval < 1000) {
+      console.warn('[NextLimiter] config.statsInterval must be at least 1000ms. Clamping to 1000ms.');
+      base.statsInterval = 1000;
+    }
+  }
+
+  // Validate webhook
+  if (base.webhook) {
+    if (!base.webhook.startsWith('http://') && !base.webhook.startsWith('https://')) {
+        throw new Error('[NextLimiter] config.webhook must be a valid URL starting with http:// or https://');
+    }
+    if (base.webhook.startsWith('http://')) {
+        console.warn('[NextLimiter] Warning: Webhook URL is using insecure http://. Consider switching to https://');
+    }
+    if (base.webhookRetries < 0 || base.webhookRetries > 10) base.webhookRetries = 3;
+    if (base.webhookTimeout < 500) base.webhookTimeout = 5000;
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const EventEmitter                = require('events');
 const { resolveConfig }           = require('./config');
 const { MemoryStore }             = require('../store/memoryStore');
 const { fixedWindowCheck }        = require('../strategies/fixedWindow');
@@ -13,6 +14,9 @@ const { SmartDetector }           = require('../smart/detector');
 const { setHeaders }              = require('../middleware/headers');
 const { checkAccess }             = require('./accessControl');
 const { PrometheusFormatter }     = require('../analytics/prometheus');
+const { RuleEngine }              = require('./ruleEngine');
+const { WebhookSender }           = require('../webhook/sender');
+const { Scheduler }               = require('./scheduler');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -33,11 +37,15 @@ const STRATEGY_MAP = {
  * // Programmatic check
  * const result = await limiter.check('user:42');
  */
-class Limiter {
+class Limiter extends EventEmitter {
   /**
    * @param {object} options - NextLimiter configuration (see config.js for defaults)
    */
   constructor(options = {}) {
+    super();
+    this.setMaxListeners(50);
+    this.on('error', () => {}); // default no-op handler prevents crashes
+
     this._config = resolveConfig(options);
 
     // Storage backend
@@ -64,7 +72,19 @@ class Limiter {
     this._analytics = new AnalyticsTracker();
 
     // Smart detector
-    this._smart = this._config.smart ? new SmartDetector(this._config) : null;
+    this._smart = this._config.smart ? new SmartDetector(this._config, this) : null;
+
+    // Stats event interval
+    if (this._config.statsInterval) {
+      this._statsTimer = setInterval(() => {
+        this.emit('stats', this.getStats());
+      }, this._config.statsInterval).unref();
+    }
+
+    // Engine, Scheduler & Webhook
+    this.ruleEngine = this._config.rules ? new RuleEngine(this._config.rules, this._store, this, this._config) : null;
+    this.scheduler = this._config.schedule ? new Scheduler(this._config.schedule, this._config) : null;
+    this.webhookSender = this._config.webhook ? new WebhookSender(this._config) : null;
   }
 
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -87,7 +107,7 @@ class Limiter {
 
         // ── Access control (whitelist / blacklist) ───────────────────────────
         const clientIp = extractIp(req);
-        const access   = checkAccess(clientIp, this._config);
+        const access   = checkAccess(clientIp, this._config, this);
 
         if (access.action === 'block') {
           return res.status(403).json({
@@ -102,17 +122,56 @@ class Limiter {
         }
         // ────────────────────────────────────────────────────────────────────
 
-        const rawKey = this._keyGenerator(req);
-        const key    = `${this._config.keyPrefix}${rawKey}`;
-
-        const result = await this._runCheck(key);
+        let result;
+        let rawKey;
+        let key;
+        let failedRuleName;
+
+        if (this.ruleEngine) {
+          const ruleResult = await this.ruleEngine.check(req);
+          result = ruleResult.mostRestrictive;
+          rawKey = ruleResult.key; // composite key
+          key = ruleResult.key;
+          failedRuleName = ruleResult.failedRule ? ruleResult.failedRule.name : undefined;
+
+          if (this._config.headers) {
+            res.setHeader('X-RateLimit-Rule-Count', ruleResult.results.length);
+            if (!ruleResult.allowed && failedRuleName) {
+              res.setHeader('X-RateLimit-Failed-Rule', failedRuleName);
+            }
+          }
+        } else {
+          rawKey = this._keyGenerator(req);
+          key    = `${this._config.keyPrefix}${rawKey}`;
+          result = await this._runCheck(key);
+        }
+        
+        // Emit events
+        if (result.allowed) {
+          this.emit('allowed', rawKey, result);
+        } else {
+          this.emit('blocked', rawKey, result);
+          if (this.webhookSender) {
+             this.webhookSender.send({
+               event: 'blocked',
+               key,
+               ip: clientIp,
+               limit: result.limit,
+               count: result.limit - result.remaining,
+               timestamp: new Date().toISOString(),
+               retryAfter: result.retryAfter,
+               strategy: result.strategy,
+               ...(failedRuleName ? { ruleName: failedRuleName } : {})
+             });
+          }
+        }
 
         // Record analytics
         this._analytics.record(key, result.allowed);
 
-        // Set headers
+        // Set headers (base headers overrides single rule headers if rule engine is active, that is fine)
         if (this._config.headers) {
-          setHeaders(res, result, !result.allowed);
+          setHeaders(res, result);
         }
 
         if (!result.allowed) {
@@ -140,8 +199,9 @@ class Limiter {
 
         next();
       } catch (err) {
+        this.emit('error', err);
         // Never let rate limiter errors take down the application
-        this._log.warn(`Error in rate limiter: ${err.message}. Failing open.`);
+        this._log.warn(`Middleware error: ${err.message}. Failing open.`);
         next();
       }
     };
@@ -196,7 +256,7 @@ class Limiter {
     // Apply access control if the key looks like a plain IP address
     const looksLikeIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(String(key).trim());
     if (looksLikeIp) {
-      const access = checkAccess(key, this._config);
+      const access = checkAccess(key, this._config, this);
       if (access.action === 'block') {
         return {
           allowed:      false,
@@ -229,9 +289,35 @@ class Limiter {
     const fullKey = `${this._config.keyPrefix}${key}`;
     const result  = await this._runCheck(fullKey);
     this._analytics.record(fullKey, result.allowed);
+
+    if (result.allowed) this.emit('allowed', key, result);
+    else this.emit('blocked', key, result);
+
     return result;
   }
 
+  /**
+   * Reset rate limit state for a key.
+   *
+   * @param {string} key
+   */
+  resetKey(key) {
+    const fullKey = `${this._config.keyPrefix}${key}`;
+    this._store.delete(fullKey);
+    this.emit('reset', key);
+  }
+
+  /**
+   * Cleanly dispose of stats cycles and store buffers.
+   */
+  destroy() {
+    if (this._statsTimer) clearInterval(this._statsTimer);
+    if (this._store && typeof this._store.destroy === 'function') {
+      this._store.destroy();
+    }
+    this.removeAllListeners();
+  }
+
   /**
    * Manually reset the rate limit for a specific key.
    * Useful after a user upgrades their plan, or for admin overrides.
@@ -264,6 +350,8 @@ class Limiter {
       };
     }
 
+    stats.activeSchedule = this.scheduler ? this.scheduler.resolve() : null;
+
     stats.config = {
       strategy: this._config.strategy,
       windowMs: this._config.windowMs,
@@ -299,14 +387,14 @@ class Limiter {
    * @returns {import('../core/result').RateLimitResult}
    */
   _runCheck(key) {
-    let effectiveConfig = this._config;
+    let effectiveConfig = this.scheduler ? this.scheduler.resolve() : this._config;
 
     // Apply smart penalty if relevant
     if (this._smart) {
       const { penalized, effectiveMax } = this._smart.check(key);
       if (penalized) {
         // Create a shallow config override with reduced max
-        effectiveConfig = { ...this._config, max: effectiveMax };
+        effectiveConfig = { ...effectiveConfig, max: effectiveMax };
       }
     }
 

package/src/core/ruleEngine.js

@@ -0,0 +1,89 @@
+'use strict';
+const { resolveKeyGenerator } = require('../utils/keyGenerator');
+const { fixedWindowCheck } = require('../strategies/fixedWindow');
+const { slidingWindowCheck } = require('../strategies/slidingWindow');
+const { tokenBucketCheck } = require('../strategies/tokenBucket');
+
+const STRATEGY_MAP = {
+  'fixed-window': fixedWindowCheck,
+  'sliding-window': slidingWindowCheck,
+  'token-bucket': tokenBucketCheck,
+};
+
+class RuleEngine {
+  constructor(rules, store, emitter, globalConfig) {
+    this._rules = rules.map((r, i) => {
+      const strategyName = r.strategy || 'sliding-window';
+      const strategyFn = STRATEGY_MAP[strategyName];
+      if (!strategyFn) throw new Error(`[NextLimiter] Unknown strategy in rule: ${strategyName}`);
+      return {
+        ...r,
+        name: r.name || `rule${i}`,
+        index: i,
+        keyGenerator: typeof r.keyBy === 'function' ? r.keyBy : resolveKeyGenerator(r.keyBy),
+        strategyFn
+      };
+    });
+    this._store = store;
+    this._emitter = emitter;
+    this._globalConfig = globalConfig;
+  }
+
+  async check(req) {
+    const promises = this._rules.map(rule => {
+      const rawKey = rule.keyGenerator(req);
+      const fullKey = `${this._globalConfig.keyPrefix}${rule.name}:${rule.keyBy}:${rawKey}`;
+      
+      const config = { max: rule.max, windowMs: rule.windowMs };
+      return Promise.resolve(rule.strategyFn(fullKey, config, this._store)).then(result => {
+        return {
+          ...result,
+          key: fullKey,
+          rawKey,
+          rule
+        };
+      });
+    });
+
+    const results = await Promise.all(promises);
+    
+    let allowed = true;
+    let failedRule = null;
+    let mostRestrictive = results[0];
+    let mostRestrictiveRemaining = Infinity;
+
+    // Find the most restrictive outcome and if any caused a block.
+    for (const res of results) {
+      if (!res.allowed) {
+        allowed = false;
+        if (!failedRule) failedRule = res.rule;
+      }
+      if (res.remaining < mostRestrictiveRemaining) {
+        mostRestrictiveRemaining = res.remaining;
+        mostRestrictive = res;
+      }
+    }
+
+    if (!allowed) {
+      let longestRetry = -1;
+      for (const res of results) {
+         if (!res.allowed && res.retryAfter > longestRetry) {
+             longestRetry = res.retryAfter;
+             mostRestrictive = res; // prioritize the one with highest retry limit to wait for
+         }
+      }
+    }
+
+    const compositeKey = results.map(r => r.key).join('|');
+
+    return {
+      allowed,
+      failedRule,
+      results,
+      mostRestrictive,
+      key: compositeKey
+    };
+  }
+}
+
+module.exports = { RuleEngine };

package/src/core/scheduler.js

@@ -0,0 +1,49 @@
+'use strict';
+
+class Scheduler {
+  constructor(schedule, baseConfig) {
+    this._schedule = schedule;
+    this._baseConfig = baseConfig;
+  }
+
+  resolve(now = new Date()) {
+    const currentHour = this._currentHourUTC(now);
+    
+    for (const entry of this._schedule) {
+      const { start, end } = this._parseHours(entry.hours);
+      if (currentHour >= start && currentHour <= end) {
+        return {
+          ...this._baseConfig,
+          max: entry.max,
+          windowMs: entry.windowMs !== undefined ? entry.windowMs : this._baseConfig.windowMs,
+          strategy: entry.strategy || this._baseConfig.strategy
+        };
+      }
+    }
+
+    return this._baseConfig;
+  }
+
+  _currentHourUTC(now) {
+    return now.getUTCHours();
+  }
+
+  _parseHours(rangeStr) {
+    const match = /^\s*(\d{1,2})\s*-\s*(\d{1,2})\s*$/.exec(rangeStr);
+    if (!match) throw new Error(`[NextLimiter] Invalid schedule hours format: "${rangeStr}" (expected "start-end" e.g. "9-17")`);
+    
+    const start = parseInt(match[1], 10);
+    const end = parseInt(match[2], 10);
+    
+    if (start < 0 || start > 23 || end < 0 || end > 23) {
+      throw new Error(`[NextLimiter] Schedule hours must be between 0 and 23. Got: ${rangeStr}`);
+    }
+    if (end < start) {
+      throw new Error(`[NextLimiter] Schedule end hour cannot be less than start hour. Got: ${rangeStr}`);
+    }
+
+    return { start, end };
+  }
+}
+
+module.exports = { Scheduler };

package/src/smart/detector.js

@@ -18,9 +18,12 @@
 class SmartDetector {
   /**
    * @param {object} config - Resolved NextLimiter config
+   * @param {import('events').EventEmitter} [emitter] - Optional event emitter
    */
-  constructor(config) {
+  constructor(config, emitter) {
     this._config = config;
+    this._emitter = emitter;
+    this._penalizedSet = new Set();
 
     // Map: key → { windowStart, count, penalized, penaltyExpires }
     /** @type {Map<string, object>} */
@@ -64,6 +67,17 @@ class SmartDetector {
       if (state.count > normalRatePerObsWindow * config.smartThreshold) {
         state.penalized      = true;
         state.penaltyExpires = now + config.smartCooldownMs;
+
+        if (this._emitter && !this._penalizedSet.has(key)) {
+          this._penalizedSet.add(key);
+          this._emitter.emit('penalized', key, {
+            key,
+            normalLimit: config.max,
+            reducedLimit: Math.floor(config.max * config.smartPenaltyFactor),
+            cooldownMs: config.smartCooldownMs,
+            detectedAt: new Date().toISOString()
+          });
+        }
       }
 
       // Reset observation window
@@ -84,6 +98,7 @@ class SmartDetector {
     // Penalty expired — lift it
     if (state.penalized && now >= state.penaltyExpires) {
       state.penalized = false;
+      this._penalizedSet.delete(key);
     }
 
     return { penalized: false, effectiveMax: config.max };
@@ -111,6 +126,7 @@ class SmartDetector {
   /** Clear all tracking state. */
   reset() {
     this._state.clear();
+    this._penalizedSet.clear();
   }
 }
 

package/src/webhook/sender.js

@@ -0,0 +1,93 @@
+'use strict';
+const https = require('https');
+const crypto = require('crypto');
+
+class WebhookSender {
+  constructor(config = {}) {
+    this.webhook = config.webhook;
+    this.webhookRetries = config.webhookRetries !== undefined ? config.webhookRetries : 3;
+    this.webhookBackoff = config.webhookBackoff || 'exponential';
+    this.webhookTimeout = config.webhookTimeout || 5000;
+    this.webhookSecret = config.webhookSecret;
+  }
+
+  async send(payload) {
+    // Fire-and-forget
+    this._sendWithRetry(payload, this.webhookRetries, this._getInitialDelay()).catch(() => {
+      // Intentionally swallow errors — background fire and forget
+    });
+  }
+
+  async _sendWithRetry(payload, attemptsLeft, delayMs) {
+    try {
+      await this._makeRequest(payload);
+    } catch (err) {
+      if (attemptsLeft > 0) {
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        const nextDelay = this._getNextDelay(delayMs);
+        await this._sendWithRetry(payload, attemptsLeft - 1, nextDelay);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  _getInitialDelay() {
+    if (this.webhookBackoff === 'linear' || this.webhookBackoff === 'fixed') return 1000;
+    return 100; // exponential
+  }
+
+  _getNextDelay(currentDelay) {
+    if (this.webhookBackoff === 'linear') return currentDelay + 1000;
+    if (this.webhookBackoff === 'exponential') return currentDelay * 2;
+    return currentDelay; // fixed
+  }
+
+  _makeRequest(payload) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(payload);
+      const urlObj = new URL(this.webhook);
+
+      const options = {
+        hostname: urlObj.hostname,
+        port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+        path: urlObj.pathname + urlObj.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body)
+        }
+      };
+
+      if (this.webhookSecret) {
+        const sig = crypto.createHmac('sha256', this.webhookSecret).update(body).digest('hex');
+        options.headers['X-nextlimiter-signature'] = `sha256=${sig}`;
+      }
+
+      // We only support https natively as per requirement, though http objects won't crash here they just might fail protocol
+      const req = https.request(options, (res) => {
+        let responseBody = '';
+        res.on('data', chunk => { responseBody += chunk; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve({ statusCode: res.statusCode, body: responseBody });
+          } else {
+            reject(new Error(`Webhook failed with status: ${res.statusCode}`));
+          }
+        });
+      });
+
+      req.on('error', (err) => reject(err));
+      
+      req.setTimeout(this.webhookTimeout, () => {
+        req.destroy();
+        reject(new Error(`Webhook timed out after ${this.webhookTimeout}ms`));
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = { WebhookSender };

package/types/index.d.ts

@@ -1,7 +1,7 @@
 // NextLimiter — TypeScript type definitions
 // Compatible with @types/node and @types/express
-
 import { Request, Response, NextFunction } from 'express';
+import { EventEmitter } from 'events';
 
 // ── Store interface ──────────────────────────────────────────────────────────
 
@@ -23,6 +23,41 @@ export interface PlanDefinition {
   description?: string;
 }
 
+export interface RuleConfig {
+  keyBy: 'ip' | 'api-key' | 'user-id' | string | ((req: Request) => string);
+  max: number;
+  windowMs: number;
+  strategy?: 'sliding-window' | 'token-bucket' | 'fixed-window';
+  name?: string;
+}
+
+export interface RuleEngineResult {
+  allowed: boolean;
+  failedRule: RuleConfig | null;
+  results: RateLimitResult[];
+  mostRestrictive: RateLimitResult;
+  key: string;
+}
+
+export interface ScheduleEntry {
+  hours: string;
+  max: number;
+  windowMs?: number;
+  strategy?: string;
+}
+
+export interface WebhookPayload {
+  event: string;
+  key: string;
+  ip: string;
+  limit: number;
+  count: number;
+  timestamp: string;
+  retryAfter: number;
+  strategy: string;
+  ruleName?: string;
+}
+
 export type BuiltInPlan = 'free' | 'pro' | 'enterprise';
 export type BuiltInPreset = 'strict' | 'relaxed' | 'api' | 'auth';
 export type Strategy = 'fixed-window' | 'sliding-window' | 'token-bucket';
@@ -102,6 +137,17 @@ export interface LimiterOptions {
 
   /** Array of IPs or CIDR ranges to block immediately (403) */
   blacklist?: string[];
+
+  /** ms interval to emit 'stats' event. undefined = disabled. */
+  statsInterval?: number;
+
+  rules?: RuleConfig[];
+  schedule?: ScheduleEntry[];
+  webhook?: string;
+  webhookRetries?: number;
+  webhookBackoff?: 'exponential' | 'linear' | 'fixed';
+  webhookTimeout?: number;
+  webhookSecret?: string;
 }
 
 // ── Rate limit result ────────────────────────────────────────────────────────
@@ -139,6 +185,14 @@ export interface RateLimitResult {
 
 // ── Analytics ────────────────────────────────────────────────────────────────
 
+export interface PenaltyInfo {
+  key: string;
+  normalLimit: number;
+  reducedLimit: number;
+  cooldownMs: number;
+  detectedAt: string;
+}
+
 export declare class PrometheusFormatter {
   constructor(limiter: Limiter);
   format(): string;
@@ -181,7 +235,7 @@ export interface LimiterStats {
 
 // ── Limiter class ────────────────────────────────────────────────────────────
 
-export declare class Limiter {
+export declare class Limiter extends EventEmitter {
   constructor(options?: LimiterOptions);
 
   /** Returns an Express-compatible middleware function */
@@ -205,6 +259,12 @@ export declare class Limiter {
   /** Reset rate limit state for a specific key */
   reset(key: string): Promise<void>;
 
+  /** Reset rate limit state and clear from store immediately */
+  resetKey(key: string): void;
+
+  /** Clean up stores and timers */
+  destroy(): void;
+
   /** Get analytics snapshot */
   getStats(): LimiterStats;
 
@@ -213,6 +273,25 @@ export declare class Limiter {
 
   /** Read-only resolved configuration */
   readonly config: Readonly<Required<LimiterOptions>>;
+
+  // Typed EventEmitter overloads
+  on(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  on(event: 'blacklisted', listener: (ip: string) => void): this;
+  on(event: 'whitelisted', listener: (ip: string) => void): this;
+  on(event: 'reset',       listener: (key: string) => void): this;
+  on(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  on(event: 'error',       listener: (err: Error) => void): this;
+
+  once(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  once(event: 'blacklisted', listener: (ip: string) => void): this;
+  once(event: 'whitelisted', listener: (ip: string) => void): this;
+  once(event: 'reset',       listener: (key: string) => void): this;
+  once(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  once(event: 'error',       listener: (err: Error) => void): this;
 }
 
 // ── Factory functions ────────────────────────────────────────────────────────