@snap-agent/middleware-ratelimit 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ViloTech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,158 @@
+# @snap-agent/middleware-ratelimit
+
+Rate limiting middleware for SnapAgent SDK. Per-user, per-agent, or global rate limiting to prevent abuse and control costs.
+
+## Installation
+
+```bash
+npm install @snap-agent/middleware-ratelimit
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@snap-agent/core';
+import { RateLimiter } from '@snap-agent/middleware-ratelimit';
+
+const rateLimiter = new RateLimiter({
+  maxRequests: 100,
+  windowMs: 60 * 1000, // 1 minute
+  keyBy: 'userId',
+  onLimit: 'reject',
+});
+
+const agent = await client.createAgent({
+  plugins: [rateLimiter],
+  // ...
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxRequests` | `number` | `100` | Max requests per window |
+| `windowMs` | `number` | `60000` | Window size in ms |
+| `keyBy` | `string` | `'userId'` | How to bucket limits |
+| `onLimit` | `string` | `'reject'` | Action when limited |
+| `limitMessage` | `string` | "Too many requests..." | Message when limited |
+
+## Key By Options
+
+- `userId` - Rate limit per user
+- `threadId` - Rate limit per thread
+- `agentId` - Rate limit per agent
+- `ip` - Rate limit per IP
+- `global` - Global rate limit
+- Custom function for advanced use cases
+
+## On Limit Actions
+
+- `reject` - Return error message immediately
+- `queue` - Queue request until rate limit resets
+- `throttle` - Allow but add delay
+
+## Examples
+
+### Per-User Rate Limiting
+
+```typescript
+new RateLimiter({
+  maxRequests: 50,
+  windowMs: 60000,
+  keyBy: 'userId',
+});
+```
+
+### Custom Key Function
+
+```typescript
+new RateLimiter({
+  maxRequests: 100,
+  windowMs: 60000,
+  keyBy: (context) => {
+    // Rate limit by organization
+    return `org:${context.metadata?.organizationId || 'unknown'}`;
+  },
+});
+```
+
+### Skip Certain Users
+
+```typescript
+new RateLimiter({
+  maxRequests: 100,
+  windowMs: 60000,
+  skip: (key, context) => {
+    // Skip rate limiting for admin users
+    return context.metadata?.role === 'admin';
+  },
+});
+```
+
+### Queue Mode
+
+```typescript
+new RateLimiter({
+  maxRequests: 10,
+  windowMs: 60000,
+  onLimit: 'queue',
+  queue: {
+    maxSize: 100,
+    timeout: 30000, // 30 second timeout
+  },
+});
+```
+
+### Distributed Rate Limiting (Redis)
+
+```typescript
+import { Redis } from 'ioredis';
+
+const redis = new Redis();
+
+new RateLimiter({
+  maxRequests: 100,
+  windowMs: 60000,
+  storage: {
+    async get(key) {
+      const data = await redis.get(`ratelimit:${key}`);
+      return data ? JSON.parse(data) : null;
+    },
+    async set(key, entry, ttlMs) {
+      await redis.set(`ratelimit:${key}`, JSON.stringify(entry), 'PX', ttlMs);
+    },
+    async increment(key, windowMs) {
+      const now = Date.now();
+      const multi = redis.multi();
+      multi.incr(`ratelimit:${key}:count`);
+      multi.pexpire(`ratelimit:${key}:count`, windowMs);
+      const [[, count]] = await multi.exec();
+      return {
+        count: count as number,
+        resetAt: now + windowMs,
+      };
+    },
+  },
+});
+```
+
+## Rate Limit Headers
+
+When `includeHeaders: true` (default), rate limit info is added to response metadata:
+
+```typescript
+// Available in response metadata
+{
+  headers: {
+    'X-RateLimit-Limit': 100,
+    'X-RateLimit-Remaining': 95,
+    'X-RateLimit-Reset': '2024-01-15T12:01:00.000Z'
+  }
+}
+```
+
+## License
+
+MIT
+

package/dist/index.d.mts

@@ -0,0 +1,175 @@
+import { MiddlewarePlugin } from '@snap-agent/core';
+
+/**
+ * How to identify rate limit buckets
+ */
+type RateLimitKey = 'userId' | 'threadId' | 'agentId' | 'ip' | 'global';
+/**
+ * Result of rate limit check
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetAt: Date;
+    retryAfter?: number;
+}
+/**
+ * Rate limit entry
+ */
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Configuration for rate limiter
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum requests allowed in the window
+     * @default 100
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs: number;
+    /**
+     * How to identify rate limit buckets
+     * @default 'userId'
+     */
+    keyBy: RateLimitKey | ((context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }) => string);
+    /**
+     * Action when rate limited
+     * @default 'reject'
+     */
+    onLimit: 'reject' | 'queue' | 'throttle';
+    /**
+     * Message to return when rate limited
+     * @default "Too many requests. Please try again later."
+     */
+    limitMessage?: string;
+    /**
+     * Include rate limit info in response metadata
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Skip rate limiting for certain keys (e.g., admin users)
+     */
+    skip?: (key: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }) => boolean;
+    /**
+     * Callback when rate limit is hit
+     */
+    onRateLimited?: (key: string, result: RateLimitResult, context: {
+        agentId: string;
+        threadId?: string;
+    }) => void;
+    /**
+     * Custom storage adapter (for distributed rate limiting)
+     * Default uses in-memory storage
+     */
+    storage?: {
+        get: (key: string) => Promise<RateLimitEntry | null>;
+        set: (key: string, entry: RateLimitEntry, ttlMs: number) => Promise<void>;
+        increment: (key: string, windowMs: number) => Promise<{
+            count: number;
+            resetAt: number;
+        }>;
+    };
+    /**
+     * Queue configuration (when onLimit is 'queue')
+     */
+    queue?: {
+        maxSize: number;
+        timeout: number;
+    };
+}
+/**
+ * Rate Limiter Middleware
+ *
+ * Implements per-user, per-agent, or global rate limiting to prevent abuse
+ * and control costs.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimiter } from '@snap-agent/middleware-ratelimit';
+ *
+ * const rateLimiter = new RateLimiter({
+ *   maxRequests: 100,
+ *   windowMs: 60 * 1000, // 1 minute
+ *   keyBy: 'userId',
+ *   onLimit: 'reject',
+ * });
+ * ```
+ */
+declare class RateLimiter implements MiddlewarePlugin {
+    name: string;
+    type: "middleware";
+    priority: number;
+    private config;
+    private limits;
+    private cleanupInterval;
+    private queues;
+    private processing;
+    constructor(config?: Partial<RateLimitConfig>);
+    beforeRequest(messages: any[], context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        messages: any[];
+        metadata?: any;
+    }>;
+    afterResponse(response: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        response: string;
+        metadata?: any;
+    }>;
+    /**
+     * Get the rate limit key for a context
+     */
+    private getKey;
+    /**
+     * Check and increment rate limit
+     */
+    private checkLimit;
+    /**
+     * Add request to queue
+     */
+    private enqueue;
+    /**
+     * Process queue for a key
+     */
+    private processQueue;
+    /**
+     * Cleanup expired entries
+     */
+    private cleanup;
+    /**
+     * Get current usage for a key
+     */
+    getUsage(key: string): Promise<RateLimitResult>;
+    /**
+     * Reset rate limit for a key
+     */
+    reset(key: string): void;
+    /**
+     * Destroy the rate limiter
+     */
+    destroy(): void;
+}
+
+export { type RateLimitConfig, type RateLimitKey, type RateLimitResult, RateLimiter };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import { MiddlewarePlugin } from '@snap-agent/core';
+
+/**
+ * How to identify rate limit buckets
+ */
+type RateLimitKey = 'userId' | 'threadId' | 'agentId' | 'ip' | 'global';
+/**
+ * Result of rate limit check
+ */
+interface RateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetAt: Date;
+    retryAfter?: number;
+}
+/**
+ * Rate limit entry
+ */
+interface RateLimitEntry {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Configuration for rate limiter
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum requests allowed in the window
+     * @default 100
+     */
+    maxRequests: number;
+    /**
+     * Time window in milliseconds
+     * @default 60000 (1 minute)
+     */
+    windowMs: number;
+    /**
+     * How to identify rate limit buckets
+     * @default 'userId'
+     */
+    keyBy: RateLimitKey | ((context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }) => string);
+    /**
+     * Action when rate limited
+     * @default 'reject'
+     */
+    onLimit: 'reject' | 'queue' | 'throttle';
+    /**
+     * Message to return when rate limited
+     * @default "Too many requests. Please try again later."
+     */
+    limitMessage?: string;
+    /**
+     * Include rate limit info in response metadata
+     * @default true
+     */
+    includeHeaders?: boolean;
+    /**
+     * Skip rate limiting for certain keys (e.g., admin users)
+     */
+    skip?: (key: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }) => boolean;
+    /**
+     * Callback when rate limit is hit
+     */
+    onRateLimited?: (key: string, result: RateLimitResult, context: {
+        agentId: string;
+        threadId?: string;
+    }) => void;
+    /**
+     * Custom storage adapter (for distributed rate limiting)
+     * Default uses in-memory storage
+     */
+    storage?: {
+        get: (key: string) => Promise<RateLimitEntry | null>;
+        set: (key: string, entry: RateLimitEntry, ttlMs: number) => Promise<void>;
+        increment: (key: string, windowMs: number) => Promise<{
+            count: number;
+            resetAt: number;
+        }>;
+    };
+    /**
+     * Queue configuration (when onLimit is 'queue')
+     */
+    queue?: {
+        maxSize: number;
+        timeout: number;
+    };
+}
+/**
+ * Rate Limiter Middleware
+ *
+ * Implements per-user, per-agent, or global rate limiting to prevent abuse
+ * and control costs.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimiter } from '@snap-agent/middleware-ratelimit';
+ *
+ * const rateLimiter = new RateLimiter({
+ *   maxRequests: 100,
+ *   windowMs: 60 * 1000, // 1 minute
+ *   keyBy: 'userId',
+ *   onLimit: 'reject',
+ * });
+ * ```
+ */
+declare class RateLimiter implements MiddlewarePlugin {
+    name: string;
+    type: "middleware";
+    priority: number;
+    private config;
+    private limits;
+    private cleanupInterval;
+    private queues;
+    private processing;
+    constructor(config?: Partial<RateLimitConfig>);
+    beforeRequest(messages: any[], context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        messages: any[];
+        metadata?: any;
+    }>;
+    afterResponse(response: string, context: {
+        agentId: string;
+        threadId?: string;
+        metadata?: any;
+    }): Promise<{
+        response: string;
+        metadata?: any;
+    }>;
+    /**
+     * Get the rate limit key for a context
+     */
+    private getKey;
+    /**
+     * Check and increment rate limit
+     */
+    private checkLimit;
+    /**
+     * Add request to queue
+     */
+    private enqueue;
+    /**
+     * Process queue for a key
+     */
+    private processQueue;
+    /**
+     * Cleanup expired entries
+     */
+    private cleanup;
+    /**
+     * Get current usage for a key
+     */
+    getUsage(key: string): Promise<RateLimitResult>;
+    /**
+     * Reset rate limit for a key
+     */
+    reset(key: string): void;
+    /**
+     * Destroy the rate limiter
+     */
+    destroy(): void;
+}
+
+export { type RateLimitConfig, type RateLimitKey, type RateLimitResult, RateLimiter };

package/dist/index.js

@@ -0,0 +1,295 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RateLimiter: () => RateLimiter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/RateLimiter.ts
+var RateLimiter = class {
+  constructor(config = {}) {
+    this.name = "rate-limiter";
+    this.type = "middleware";
+    this.priority = 5;
+    // In-memory storage
+    this.limits = /* @__PURE__ */ new Map();
+    this.cleanupInterval = null;
+    // Queue for 'queue' mode
+    this.queues = /* @__PURE__ */ new Map();
+    this.processing = /* @__PURE__ */ new Set();
+    this.config = {
+      maxRequests: config.maxRequests ?? 100,
+      windowMs: config.windowMs ?? 6e4,
+      keyBy: config.keyBy ?? "userId",
+      onLimit: config.onLimit ?? "reject",
+      limitMessage: config.limitMessage ?? "Too many requests. Please try again later.",
+      includeHeaders: config.includeHeaders !== false,
+      skip: config.skip,
+      onRateLimited: config.onRateLimited,
+      storage: config.storage,
+      queue: config.queue
+    };
+    if (!this.config.storage) {
+      this.cleanupInterval = setInterval(() => this.cleanup(), 6e4);
+    }
+  }
+  async beforeRequest(messages, context) {
+    const key = this.getKey(context);
+    if (this.config.skip?.(key, context)) {
+      return { messages, metadata: { rateLimit: { skipped: true } } };
+    }
+    const result = await this.checkLimit(key);
+    if (!result.allowed) {
+      this.config.onRateLimited?.(key, result, context);
+      if (this.config.onLimit === "reject") {
+        const limitedMessage = {
+          role: "system",
+          content: `[RATE_LIMITED] ${this.config.limitMessage}`
+        };
+        return {
+          messages: [limitedMessage],
+          metadata: {
+            rateLimit: {
+              limited: true,
+              ...result
+            },
+            _skipLLM: true
+            // Signal to skip LLM call
+          }
+        };
+      }
+      if (this.config.onLimit === "queue") {
+        await this.enqueue(key);
+      }
+    }
+    return {
+      messages,
+      metadata: {
+        rateLimit: {
+          ...result,
+          key
+        }
+      }
+    };
+  }
+  async afterResponse(response, context) {
+    if (context.metadata?._skipLLM) {
+      return {
+        response: this.config.limitMessage,
+        metadata: {
+          ...context.metadata,
+          rateLimited: true
+        }
+      };
+    }
+    const key = this.getKey(context);
+    this.processQueue(key);
+    if (this.config.includeHeaders && context.metadata?.rateLimit) {
+      return {
+        response,
+        metadata: {
+          ...context.metadata,
+          headers: {
+            "X-RateLimit-Limit": context.metadata.rateLimit.limit,
+            "X-RateLimit-Remaining": context.metadata.rateLimit.remaining,
+            "X-RateLimit-Reset": context.metadata.rateLimit.resetAt?.toISOString()
+          }
+        }
+      };
+    }
+    return { response, metadata: context.metadata };
+  }
+  /**
+   * Get the rate limit key for a context
+   */
+  getKey(context) {
+    if (typeof this.config.keyBy === "function") {
+      return this.config.keyBy(context);
+    }
+    switch (this.config.keyBy) {
+      case "userId":
+        return `user:${context.metadata?.userId || "anonymous"}`;
+      case "threadId":
+        return `thread:${context.threadId || "unknown"}`;
+      case "agentId":
+        return `agent:${context.agentId}`;
+      case "ip":
+        return `ip:${context.metadata?.ip || "unknown"}`;
+      case "global":
+        return "global";
+      default:
+        return `user:${context.metadata?.userId || "anonymous"}`;
+    }
+  }
+  /**
+   * Check and increment rate limit
+   */
+  async checkLimit(key) {
+    const now = Date.now();
+    if (this.config.storage) {
+      const { count, resetAt } = await this.config.storage.increment(key, this.config.windowMs);
+      const allowed2 = count <= this.config.maxRequests;
+      return {
+        allowed: allowed2,
+        limit: this.config.maxRequests,
+        remaining: Math.max(0, this.config.maxRequests - count),
+        resetAt: new Date(resetAt),
+        retryAfter: allowed2 ? void 0 : Math.ceil((resetAt - now) / 1e3)
+      };
+    }
+    let entry = this.limits.get(key);
+    if (!entry || now > entry.resetAt) {
+      entry = {
+        count: 1,
+        resetAt: now + this.config.windowMs
+      };
+      this.limits.set(key, entry);
+    } else {
+      entry.count++;
+    }
+    const allowed = entry.count <= this.config.maxRequests;
+    return {
+      allowed,
+      limit: this.config.maxRequests,
+      remaining: Math.max(0, this.config.maxRequests - entry.count),
+      resetAt: new Date(entry.resetAt),
+      retryAfter: allowed ? void 0 : Math.ceil((entry.resetAt - now) / 1e3)
+    };
+  }
+  /**
+   * Add request to queue
+   */
+  enqueue(key) {
+    const queue = this.queues.get(key) || [];
+    const maxSize = this.config.queue?.maxSize || 10;
+    const timeout = this.config.queue?.timeout || 3e4;
+    if (queue.length >= maxSize) {
+      return Promise.reject(new Error("Rate limit queue is full"));
+    }
+    return new Promise((resolve, reject) => {
+      queue.push({
+        resolve,
+        reject,
+        addedAt: Date.now()
+      });
+      this.queues.set(key, queue);
+      setTimeout(() => {
+        const idx = queue.findIndex((q) => q.resolve === resolve);
+        if (idx > -1) {
+          queue.splice(idx, 1);
+          reject(new Error("Queue timeout"));
+        }
+      }, timeout);
+      this.processQueue(key);
+    });
+  }
+  /**
+   * Process queue for a key
+   */
+  processQueue(key) {
+    if (this.processing.has(key)) return;
+    const queue = this.queues.get(key);
+    if (!queue || queue.length === 0) return;
+    this.processing.add(key);
+    const entry = this.limits.get(key);
+    const now = Date.now();
+    if (!entry || now > entry.resetAt || entry.count < this.config.maxRequests) {
+      const item = queue.shift();
+      if (item) {
+        item.resolve(void 0);
+      }
+    }
+    this.processing.delete(key);
+    if (queue.length > 0) {
+      const waitTime = entry ? Math.max(0, entry.resetAt - now) : 0;
+      setTimeout(() => this.processQueue(key), Math.min(waitTime, 1e3));
+    }
+  }
+  /**
+   * Cleanup expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.limits.entries()) {
+      if (now > entry.resetAt) {
+        this.limits.delete(key);
+      }
+    }
+  }
+  /**
+   * Get current usage for a key
+   */
+  async getUsage(key) {
+    if (this.config.storage) {
+      const entry2 = await this.config.storage.get(key);
+      if (!entry2) {
+        return {
+          allowed: true,
+          limit: this.config.maxRequests,
+          remaining: this.config.maxRequests,
+          resetAt: /* @__PURE__ */ new Date()
+        };
+      }
+      return {
+        allowed: entry2.count < this.config.maxRequests,
+        limit: this.config.maxRequests,
+        remaining: Math.max(0, this.config.maxRequests - entry2.count),
+        resetAt: new Date(entry2.resetAt)
+      };
+    }
+    const entry = this.limits.get(key);
+    if (!entry || Date.now() > entry.resetAt) {
+      return {
+        allowed: true,
+        limit: this.config.maxRequests,
+        remaining: this.config.maxRequests,
+        resetAt: /* @__PURE__ */ new Date()
+      };
+    }
+    return {
+      allowed: entry.count < this.config.maxRequests,
+      limit: this.config.maxRequests,
+      remaining: Math.max(0, this.config.maxRequests - entry.count),
+      resetAt: new Date(entry.resetAt)
+    };
+  }
+  /**
+   * Reset rate limit for a key
+   */
+  reset(key) {
+    this.limits.delete(key);
+  }
+  /**
+   * Destroy the rate limiter
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.limits.clear();
+    this.queues.clear();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RateLimiter
+});

package/dist/index.mjs

@@ -0,0 +1,268 @@
+// src/RateLimiter.ts
+var RateLimiter = class {
+  constructor(config = {}) {
+    this.name = "rate-limiter";
+    this.type = "middleware";
+    this.priority = 5;
+    // In-memory storage
+    this.limits = /* @__PURE__ */ new Map();
+    this.cleanupInterval = null;
+    // Queue for 'queue' mode
+    this.queues = /* @__PURE__ */ new Map();
+    this.processing = /* @__PURE__ */ new Set();
+    this.config = {
+      maxRequests: config.maxRequests ?? 100,
+      windowMs: config.windowMs ?? 6e4,
+      keyBy: config.keyBy ?? "userId",
+      onLimit: config.onLimit ?? "reject",
+      limitMessage: config.limitMessage ?? "Too many requests. Please try again later.",
+      includeHeaders: config.includeHeaders !== false,
+      skip: config.skip,
+      onRateLimited: config.onRateLimited,
+      storage: config.storage,
+      queue: config.queue
+    };
+    if (!this.config.storage) {
+      this.cleanupInterval = setInterval(() => this.cleanup(), 6e4);
+    }
+  }
+  async beforeRequest(messages, context) {
+    const key = this.getKey(context);
+    if (this.config.skip?.(key, context)) {
+      return { messages, metadata: { rateLimit: { skipped: true } } };
+    }
+    const result = await this.checkLimit(key);
+    if (!result.allowed) {
+      this.config.onRateLimited?.(key, result, context);
+      if (this.config.onLimit === "reject") {
+        const limitedMessage = {
+          role: "system",
+          content: `[RATE_LIMITED] ${this.config.limitMessage}`
+        };
+        return {
+          messages: [limitedMessage],
+          metadata: {
+            rateLimit: {
+              limited: true,
+              ...result
+            },
+            _skipLLM: true
+            // Signal to skip LLM call
+          }
+        };
+      }
+      if (this.config.onLimit === "queue") {
+        await this.enqueue(key);
+      }
+    }
+    return {
+      messages,
+      metadata: {
+        rateLimit: {
+          ...result,
+          key
+        }
+      }
+    };
+  }
+  async afterResponse(response, context) {
+    if (context.metadata?._skipLLM) {
+      return {
+        response: this.config.limitMessage,
+        metadata: {
+          ...context.metadata,
+          rateLimited: true
+        }
+      };
+    }
+    const key = this.getKey(context);
+    this.processQueue(key);
+    if (this.config.includeHeaders && context.metadata?.rateLimit) {
+      return {
+        response,
+        metadata: {
+          ...context.metadata,
+          headers: {
+            "X-RateLimit-Limit": context.metadata.rateLimit.limit,
+            "X-RateLimit-Remaining": context.metadata.rateLimit.remaining,
+            "X-RateLimit-Reset": context.metadata.rateLimit.resetAt?.toISOString()
+          }
+        }
+      };
+    }
+    return { response, metadata: context.metadata };
+  }
+  /**
+   * Get the rate limit key for a context
+   */
+  getKey(context) {
+    if (typeof this.config.keyBy === "function") {
+      return this.config.keyBy(context);
+    }
+    switch (this.config.keyBy) {
+      case "userId":
+        return `user:${context.metadata?.userId || "anonymous"}`;
+      case "threadId":
+        return `thread:${context.threadId || "unknown"}`;
+      case "agentId":
+        return `agent:${context.agentId}`;
+      case "ip":
+        return `ip:${context.metadata?.ip || "unknown"}`;
+      case "global":
+        return "global";
+      default:
+        return `user:${context.metadata?.userId || "anonymous"}`;
+    }
+  }
+  /**
+   * Check and increment rate limit
+   */
+  async checkLimit(key) {
+    const now = Date.now();
+    if (this.config.storage) {
+      const { count, resetAt } = await this.config.storage.increment(key, this.config.windowMs);
+      const allowed2 = count <= this.config.maxRequests;
+      return {
+        allowed: allowed2,
+        limit: this.config.maxRequests,
+        remaining: Math.max(0, this.config.maxRequests - count),
+        resetAt: new Date(resetAt),
+        retryAfter: allowed2 ? void 0 : Math.ceil((resetAt - now) / 1e3)
+      };
+    }
+    let entry = this.limits.get(key);
+    if (!entry || now > entry.resetAt) {
+      entry = {
+        count: 1,
+        resetAt: now + this.config.windowMs
+      };
+      this.limits.set(key, entry);
+    } else {
+      entry.count++;
+    }
+    const allowed = entry.count <= this.config.maxRequests;
+    return {
+      allowed,
+      limit: this.config.maxRequests,
+      remaining: Math.max(0, this.config.maxRequests - entry.count),
+      resetAt: new Date(entry.resetAt),
+      retryAfter: allowed ? void 0 : Math.ceil((entry.resetAt - now) / 1e3)
+    };
+  }
+  /**
+   * Add request to queue
+   */
+  enqueue(key) {
+    const queue = this.queues.get(key) || [];
+    const maxSize = this.config.queue?.maxSize || 10;
+    const timeout = this.config.queue?.timeout || 3e4;
+    if (queue.length >= maxSize) {
+      return Promise.reject(new Error("Rate limit queue is full"));
+    }
+    return new Promise((resolve, reject) => {
+      queue.push({
+        resolve,
+        reject,
+        addedAt: Date.now()
+      });
+      this.queues.set(key, queue);
+      setTimeout(() => {
+        const idx = queue.findIndex((q) => q.resolve === resolve);
+        if (idx > -1) {
+          queue.splice(idx, 1);
+          reject(new Error("Queue timeout"));
+        }
+      }, timeout);
+      this.processQueue(key);
+    });
+  }
+  /**
+   * Process queue for a key
+   */
+  processQueue(key) {
+    if (this.processing.has(key)) return;
+    const queue = this.queues.get(key);
+    if (!queue || queue.length === 0) return;
+    this.processing.add(key);
+    const entry = this.limits.get(key);
+    const now = Date.now();
+    if (!entry || now > entry.resetAt || entry.count < this.config.maxRequests) {
+      const item = queue.shift();
+      if (item) {
+        item.resolve(void 0);
+      }
+    }
+    this.processing.delete(key);
+    if (queue.length > 0) {
+      const waitTime = entry ? Math.max(0, entry.resetAt - now) : 0;
+      setTimeout(() => this.processQueue(key), Math.min(waitTime, 1e3));
+    }
+  }
+  /**
+   * Cleanup expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.limits.entries()) {
+      if (now > entry.resetAt) {
+        this.limits.delete(key);
+      }
+    }
+  }
+  /**
+   * Get current usage for a key
+   */
+  async getUsage(key) {
+    if (this.config.storage) {
+      const entry2 = await this.config.storage.get(key);
+      if (!entry2) {
+        return {
+          allowed: true,
+          limit: this.config.maxRequests,
+          remaining: this.config.maxRequests,
+          resetAt: /* @__PURE__ */ new Date()
+        };
+      }
+      return {
+        allowed: entry2.count < this.config.maxRequests,
+        limit: this.config.maxRequests,
+        remaining: Math.max(0, this.config.maxRequests - entry2.count),
+        resetAt: new Date(entry2.resetAt)
+      };
+    }
+    const entry = this.limits.get(key);
+    if (!entry || Date.now() > entry.resetAt) {
+      return {
+        allowed: true,
+        limit: this.config.maxRequests,
+        remaining: this.config.maxRequests,
+        resetAt: /* @__PURE__ */ new Date()
+      };
+    }
+    return {
+      allowed: entry.count < this.config.maxRequests,
+      limit: this.config.maxRequests,
+      remaining: Math.max(0, this.config.maxRequests - entry.count),
+      resetAt: new Date(entry.resetAt)
+    };
+  }
+  /**
+   * Reset rate limit for a key
+   */
+  reset(key) {
+    this.limits.delete(key);
+  }
+  /**
+   * Destroy the rate limiter
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+    this.limits.clear();
+    this.queues.clear();
+  }
+};
+export {
+  RateLimiter
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@snap-agent/middleware-ratelimit",
+  "version": "0.1.0",
+  "description": "Rate limiting middleware for SnapAgent SDK - Per-user rate limiting and abuse prevention.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "snap-agent",
+    "ai",
+    "agents",
+    "llm",
+    "middleware",
+    "rate-limit",
+    "throttle",
+    "abuse-prevention",
+    "typescript",
+    "plugin"
+  ],
+  "author": "ViloTech",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@snap-agent/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vilo-hq/snap-agent.git",
+    "directory": "middlewares/ratelimit"
+  },
+  "homepage": "https://github.com/vilo-hq/snap-agent/tree/main/middlewares/ratelimit",
+  "bugs": {
+    "url": "https://github.com/vilo-hq/snap-agent/issues"
+  }
+}
+