@lleverage-ai/agent-sdk 0.0.1

package/dist/hooks/rate-limit.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Rate limiting hook utilities.
+ *
+ * Provides rate limiting hooks that track token usage and enforce limits
+ * using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+import type { HookCallback, PostGenerateInput } from "../types.js";
+/**
+ * Server-provided rate limit information from response headers.
+ *
+ * @category Hooks
+ */
+export interface ServerRateLimitInfo {
+    /**
+     * Maximum requests allowed in the current window.
+     * Typically from `x-ratelimit-limit` or `ratelimit-limit` header.
+     */
+    limit?: number;
+    /**
+     * Number of requests remaining in the current window.
+     * Typically from `x-ratelimit-remaining` or `ratelimit-remaining` header.
+     */
+    remaining?: number;
+    /**
+     * Timestamp when the rate limit window resets (Unix seconds).
+     * Typically from `x-ratelimit-reset` or `ratelimit-reset` header.
+     */
+    reset?: number;
+    /**
+     * Number of seconds until the rate limit window resets.
+     * Typically from `retry-after` header when rate limited.
+     */
+    retryAfter?: number;
+}
+/**
+ * Options for creating rate limit hooks.
+ *
+ * @category Hooks
+ */
+export interface RateLimitHooksOptions {
+    /**
+     * Maximum tokens per time window.
+     * @defaultValue 100000
+     */
+    maxTokensPerWindow?: number;
+    /**
+     * Time window in milliseconds for token counting.
+     * @defaultValue 60000 (1 minute)
+     */
+    windowMs?: number;
+    /**
+     * Message to show when rate limit is exceeded.
+     * @defaultValue "Rate limit exceeded. Please try again later."
+     */
+    limitMessage?: string;
+    /**
+     * Custom function to determine if a request should be rate limited.
+     * Return true to allow, false to deny.
+     * @defaultValue Check token count against limit
+     */
+    shouldAllow?: (tokensUsed: number, maxTokens: number) => boolean;
+    /**
+     * Enable server rate limit integration.
+     * When enabled, hooks will attempt to extract rate limit information
+     * from model response headers (e.g., x-ratelimit-* headers) and use
+     * server-provided limits in addition to client-side tracking.
+     *
+     * @defaultValue false
+     */
+    enableServerLimits?: boolean;
+    /**
+     * Custom function to extract server rate limit info from response metadata.
+     * Use this if your provider uses non-standard header names or formats.
+     *
+     * @param result - The generation result which may contain response metadata
+     * @returns Server rate limit information, or undefined if not available
+     *
+     * @example
+     * ```typescript
+     * extractServerLimits: (result) => {
+     *   const headers = result.rawResponse?.headers;
+     *   if (!headers) return undefined;
+     *   return {
+     *     limit: parseInt(headers['x-custom-limit'] || '0'),
+     *     remaining: parseInt(headers['x-custom-remaining'] || '0'),
+     *     reset: parseInt(headers['x-custom-reset'] || '0'),
+     *   };
+     * }
+     * ```
+     */
+    extractServerLimits?: (result: PostGenerateInput) => ServerRateLimitInfo | undefined;
+    /**
+     * Enable per-tool quota tracking.
+     * When enabled, tracks token usage separately for each tool,
+     * allowing different tools to have independent rate limits.
+     *
+     * **Note**: This feature is designed for future tool-based rate limiting hooks
+     * (PreToolUse/PostToolUse). The current generation-based hooks (PreGenerate/PostGenerate)
+     * track overall token usage, not per-tool usage.
+     *
+     * @defaultValue false
+     * @experimental
+     */
+    perToolQuota?: boolean;
+    /**
+     * Per-tool token limits when perToolQuota is enabled.
+     * Maps tool names to their maximum tokens per window.
+     *
+     * **Note**: This feature is designed for future tool-based rate limiting hooks.
+     * Current generation-based hooks do not use this configuration.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   'Write': 10000,    // Write tool limited to 10k tokens per window
+     *   'Bash': 5000,      // Bash tool limited to 5k tokens per window
+     *   'Read': 20000,     // Read tool limited to 20k tokens per window
+     * }
+     * ```
+     * @experimental
+     */
+    toolLimits?: Record<string, number>;
+}
+/**
+ * Token bucket rate limiter implementation.
+ *
+ * Tracks token usage in a sliding window with automatic cleanup of old entries.
+ * Supports per-tool quota tracking and server-provided rate limit integration.
+ *
+ * @category Hooks
+ */
+export declare class TokenBucketRateLimiter {
+    private usage;
+    private maxTokens;
+    private windowMs;
+    private serverLimitInfo?;
+    private perToolQuota;
+    private toolLimits;
+    constructor(maxTokensPerWindow: number, windowMs: number, perToolQuota?: boolean, toolLimits?: Record<string, number>);
+    /**
+     * Try to acquire tokens. Returns true if allowed, false if would exceed limit.
+     * If tool is provided and per-tool quotas are enabled, checks against tool-specific limit.
+     */
+    tryAcquire(tool?: string): boolean;
+    /**
+     * Record token usage for a tool.
+     */
+    recordUsage(tokens: number, tool?: string): void;
+    /**
+     * Get current token usage in the window.
+     * If tool is provided and per-tool quotas are enabled, returns usage for that tool only.
+     */
+    getCurrentUsage(tool?: string): number;
+    /**
+     * Get remaining tokens in current window.
+     * Uses server limits if available, otherwise falls back to client-side tracking.
+     */
+    getRemainingTokens(tool?: string): number;
+    /**
+     * Update with server-provided rate limit information.
+     * This information takes precedence over client-side tracking.
+     */
+    updateServerLimits(info: ServerRateLimitInfo): void;
+    /**
+     * Get current server limit information if available.
+     */
+    getServerLimits(): ServerRateLimitInfo | undefined;
+    /**
+     * Get the effective limit for a tool (tool-specific or global).
+     */
+    private getEffectiveLimit;
+    /**
+     * Remove entries outside the current window.
+     */
+    private cleanup;
+    /**
+     * Reset all usage data and server limit info.
+     */
+    reset(): void;
+}
+/**
+ * Default server rate limit extractor.
+ *
+ * Attempts to extract rate limit information from common response header patterns:
+ * - `x-ratelimit-*` (OpenAI, Anthropic, etc.)
+ * - `ratelimit-*` (standard format)
+ * - `retry-after` (when rate limited)
+ *
+ * @param result - PostGenerate hook input containing the generation result
+ * @returns Server rate limit info if headers are present, undefined otherwise
+ *
+ * @category Hooks
+ */
+export declare function extractStandardRateLimitHeaders(result: PostGenerateInput): ServerRateLimitInfo | undefined;
+/**
+ * Creates rate limiting hooks for PreGenerate and PostGenerate events.
+ *
+ * The PreGenerate hook checks if the rate limit would be exceeded and denies
+ * the request if so. The PostGenerate hook records actual token usage.
+ *
+ * This replaces rate limiting middleware with hook-based rate limiting that
+ * works correctly with the unified hook system.
+ *
+ * @param options - Configuration options
+ * @returns Array of two hooks: [PreGenerate rate check, PostGenerate usage tracking]
+ *
+ * @example
+ * ```typescript
+ * const [rateCheck, usageTracker] = createRateLimitHooks({
+ *   maxTokensPerWindow: 50000,  // 50k tokens
+ *   windowMs: 60000,             // per minute
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [rateCheck] }],
+ *     PostGenerate: [{ hooks: [usageTracker] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom rate limit logic
+ * const hooks = createRateLimitHooks({
+ *   shouldAllow: (tokensUsed, maxTokens) => {
+ *     // Allow if under 80% of limit
+ *     return tokensUsed < maxTokens * 0.8;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With server rate limit integration
+ * const hooks = createRateLimitHooks({
+ *   maxTokensPerWindow: 100000,
+ *   enableServerLimits: true,  // Parse x-ratelimit-* headers
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom server limit extraction for non-standard headers
+ * const hooks = createRateLimitHooks({
+ *   enableServerLimits: true,
+ *   extractServerLimits: (result) => {
+ *     const headers = result.response?.headers;
+ *     return {
+ *       remaining: parseInt(headers?.['x-custom-remaining'] || '0'),
+ *       reset: parseInt(headers?.['x-custom-reset'] || '0'),
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createRateLimitHooks(options?: RateLimitHooksOptions): [HookCallback, HookCallback];
+/**
+ * Creates managed rate limit hooks with programmatic control.
+ *
+ * Returns hooks along with functions to get current usage, reset limits,
+ * and check remaining capacity.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks and rate limit control functions
+ *
+ * @example
+ * ```typescript
+ * const { hooks, getCurrentUsage, getRemainingTokens, reset } = createManagedRateLimitHooks({
+ *   maxTokensPerWindow: 100000,
+ *   windowMs: 60000,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [hooks[0]] }],
+ *     PostGenerate: [{ hooks: [hooks[1]] }],
+ *   },
+ * });
+ *
+ * // Check current usage
+ * const used = getCurrentUsage();
+ * const remaining = getRemainingTokens();
+ * console.log(`Token usage: ${used} / ${maxTokensPerWindow} (${remaining} remaining)`);
+ *
+ * // Reset limits (e.g., for testing or manual override)
+ * reset();
+ * ```
+ *
+ * @category Hooks
+ */
+export declare function createManagedRateLimitHooks(options?: RateLimitHooksOptions): {
+    hooks: [HookCallback, HookCallback];
+    getCurrentUsage: () => number;
+    getRemainingTokens: () => number;
+    getServerLimits: () => ServerRateLimitInfo | undefined;
+    reset: () => void;
+};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/hooks/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/hooks/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/hooks/rate-limit.js

@@ -0,0 +1,372 @@
+/**
+ * Rate limiting hook utilities.
+ *
+ * Provides rate limiting hooks that track token usage and enforce limits
+ * using the unified hook system.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Token bucket rate limiter implementation.
+ *
+ * Tracks token usage in a sliding window with automatic cleanup of old entries.
+ * Supports per-tool quota tracking and server-provided rate limit integration.
+ *
+ * @category Hooks
+ */
+export class TokenBucketRateLimiter {
+    usage = [];
+    maxTokens;
+    windowMs;
+    serverLimitInfo;
+    perToolQuota;
+    toolLimits;
+    constructor(maxTokensPerWindow, windowMs, perToolQuota = false, toolLimits = {}) {
+        this.maxTokens = maxTokensPerWindow;
+        this.windowMs = windowMs;
+        this.perToolQuota = perToolQuota;
+        this.toolLimits = toolLimits;
+    }
+    /**
+     * Try to acquire tokens. Returns true if allowed, false if would exceed limit.
+     * If tool is provided and per-tool quotas are enabled, checks against tool-specific limit.
+     */
+    tryAcquire(tool) {
+        this.cleanup();
+        // Check server limits first if available
+        if (this.serverLimitInfo?.remaining !== undefined) {
+            if (this.serverLimitInfo.remaining <= 0) {
+                return false;
+            }
+        }
+        // Check client-side limits
+        const currentUsage = this.getCurrentUsage(tool);
+        const limit = this.getEffectiveLimit(tool);
+        return currentUsage < limit;
+    }
+    /**
+     * Record token usage for a tool.
+     */
+    recordUsage(tokens, tool) {
+        this.cleanup();
+        this.usage.push({
+            timestamp: Date.now(),
+            tokens,
+            tool,
+        });
+    }
+    /**
+     * Get current token usage in the window.
+     * If tool is provided and per-tool quotas are enabled, returns usage for that tool only.
+     */
+    getCurrentUsage(tool) {
+        this.cleanup();
+        if (this.perToolQuota && tool) {
+            return this.usage
+                .filter((entry) => entry.tool === tool)
+                .reduce((sum, entry) => sum + entry.tokens, 0);
+        }
+        return this.usage.reduce((sum, entry) => sum + entry.tokens, 0);
+    }
+    /**
+     * Get remaining tokens in current window.
+     * Uses server limits if available, otherwise falls back to client-side tracking.
+     */
+    getRemainingTokens(tool) {
+        // Prefer server-provided remaining count if available
+        if (this.serverLimitInfo?.remaining !== undefined) {
+            return Math.max(0, this.serverLimitInfo.remaining);
+        }
+        const current = this.getCurrentUsage(tool);
+        const limit = this.getEffectiveLimit(tool);
+        return Math.max(0, limit - current);
+    }
+    /**
+     * Update with server-provided rate limit information.
+     * This information takes precedence over client-side tracking.
+     */
+    updateServerLimits(info) {
+        this.serverLimitInfo = info;
+    }
+    /**
+     * Get current server limit information if available.
+     */
+    getServerLimits() {
+        return this.serverLimitInfo;
+    }
+    /**
+     * Get the effective limit for a tool (tool-specific or global).
+     */
+    getEffectiveLimit(tool) {
+        if (this.perToolQuota && tool && this.toolLimits[tool]) {
+            return this.toolLimits[tool];
+        }
+        return this.maxTokens;
+    }
+    /**
+     * Remove entries outside the current window.
+     */
+    cleanup() {
+        const cutoff = Date.now() - this.windowMs;
+        this.usage = this.usage.filter((entry) => entry.timestamp > cutoff);
+    }
+    /**
+     * Reset all usage data and server limit info.
+     */
+    reset() {
+        this.usage = [];
+        this.serverLimitInfo = undefined;
+    }
+}
+/**
+ * Default server rate limit extractor.
+ *
+ * Attempts to extract rate limit information from common response header patterns:
+ * - `x-ratelimit-*` (OpenAI, Anthropic, etc.)
+ * - `ratelimit-*` (standard format)
+ * - `retry-after` (when rate limited)
+ *
+ * @param result - PostGenerate hook input containing the generation result
+ * @returns Server rate limit info if headers are present, undefined otherwise
+ *
+ * @category Hooks
+ */
+export function extractStandardRateLimitHeaders(result) {
+    // AI SDK v6 may expose response metadata via result.response or result.rawResponse
+    // This is a best-effort extraction that handles common patterns
+    // biome-ignore lint/suspicious/noExplicitAny: AI SDK internal structure varies by version
+    const headers = result.response?.headers || result.rawResponse?.headers;
+    if (!headers)
+        return undefined;
+    // Normalize headers to lowercase for case-insensitive matching
+    const normalizedHeaders = {};
+    if (typeof headers === "object") {
+        for (const [key, value] of Object.entries(headers)) {
+            if (typeof value === "string") {
+                normalizedHeaders[key.toLowerCase()] = value;
+            }
+        }
+    }
+    // Try common header patterns
+    const limitStr = normalizedHeaders["x-ratelimit-limit"] || normalizedHeaders["ratelimit-limit"];
+    const remainingStr = normalizedHeaders["x-ratelimit-remaining"] || normalizedHeaders["ratelimit-remaining"];
+    const resetStr = normalizedHeaders["x-ratelimit-reset"] || normalizedHeaders["ratelimit-reset"];
+    const retryAfterStr = normalizedHeaders["retry-after"];
+    // Parse values
+    const limit = limitStr ? Number.parseInt(limitStr, 10) : undefined;
+    const remaining = remainingStr ? Number.parseInt(remainingStr, 10) : undefined;
+    const reset = resetStr ? Number.parseInt(resetStr, 10) : undefined;
+    const retryAfter = retryAfterStr ? Number.parseInt(retryAfterStr, 10) : undefined;
+    // Return undefined if no rate limit headers found
+    if (limit === undefined &&
+        remaining === undefined &&
+        reset === undefined &&
+        retryAfter === undefined) {
+        return undefined;
+    }
+    return {
+        limit: !Number.isNaN(limit) ? limit : undefined,
+        remaining: !Number.isNaN(remaining) ? remaining : undefined,
+        reset: !Number.isNaN(reset) ? reset : undefined,
+        retryAfter: !Number.isNaN(retryAfter) ? retryAfter : undefined,
+    };
+}
+/**
+ * Creates rate limiting hooks for PreGenerate and PostGenerate events.
+ *
+ * The PreGenerate hook checks if the rate limit would be exceeded and denies
+ * the request if so. The PostGenerate hook records actual token usage.
+ *
+ * This replaces rate limiting middleware with hook-based rate limiting that
+ * works correctly with the unified hook system.
+ *
+ * @param options - Configuration options
+ * @returns Array of two hooks: [PreGenerate rate check, PostGenerate usage tracking]
+ *
+ * @example
+ * ```typescript
+ * const [rateCheck, usageTracker] = createRateLimitHooks({
+ *   maxTokensPerWindow: 50000,  // 50k tokens
+ *   windowMs: 60000,             // per minute
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [rateCheck] }],
+ *     PostGenerate: [{ hooks: [usageTracker] }],
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom rate limit logic
+ * const hooks = createRateLimitHooks({
+ *   shouldAllow: (tokensUsed, maxTokens) => {
+ *     // Allow if under 80% of limit
+ *     return tokensUsed < maxTokens * 0.8;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With server rate limit integration
+ * const hooks = createRateLimitHooks({
+ *   maxTokensPerWindow: 100000,
+ *   enableServerLimits: true,  // Parse x-ratelimit-* headers
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom server limit extraction for non-standard headers
+ * const hooks = createRateLimitHooks({
+ *   enableServerLimits: true,
+ *   extractServerLimits: (result) => {
+ *     const headers = result.response?.headers;
+ *     return {
+ *       remaining: parseInt(headers?.['x-custom-remaining'] || '0'),
+ *       reset: parseInt(headers?.['x-custom-reset'] || '0'),
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @category Hooks
+ */
+export function createRateLimitHooks(options = {}) {
+    const { maxTokensPerWindow = 100000, windowMs = 60000, // 1 minute
+    limitMessage = "Rate limit exceeded. Please try again later.", shouldAllow = (tokensUsed, maxTokens) => tokensUsed < maxTokens, enableServerLimits = false, extractServerLimits = extractStandardRateLimitHeaders, perToolQuota = false, toolLimits = {}, } = options;
+    const rateLimiter = new TokenBucketRateLimiter(maxTokensPerWindow, windowMs, perToolQuota, toolLimits);
+    // PreGenerate: Check rate limit
+    const rateCheck = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        const currentUsage = rateLimiter.getCurrentUsage();
+        if (!shouldAllow(currentUsage, maxTokensPerWindow)) {
+            // Check if we have server reset time for better error message
+            const serverLimits = rateLimiter.getServerLimits();
+            let reason = limitMessage;
+            if (serverLimits?.reset) {
+                const resetDate = new Date(serverLimits.reset * 1000);
+                reason = `${limitMessage} Rate limit resets at ${resetDate.toISOString()}.`;
+            }
+            else if (serverLimits?.retryAfter) {
+                reason = `${limitMessage} Retry after ${serverLimits.retryAfter} seconds.`;
+            }
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreGenerate",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason,
+                },
+            };
+        }
+        return {};
+    };
+    // PostGenerate: Record usage and update server limits
+    const usageTracker = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        const postGenInput = input;
+        const tokens = postGenInput.result.usage?.totalTokens ?? 0;
+        // Record client-side usage
+        rateLimiter.recordUsage(tokens);
+        // Update with server-provided limits if enabled
+        if (enableServerLimits) {
+            const serverLimits = extractServerLimits(postGenInput);
+            if (serverLimits) {
+                rateLimiter.updateServerLimits(serverLimits);
+            }
+        }
+        return {};
+    };
+    return [rateCheck, usageTracker];
+}
+/**
+ * Creates managed rate limit hooks with programmatic control.
+ *
+ * Returns hooks along with functions to get current usage, reset limits,
+ * and check remaining capacity.
+ *
+ * @param options - Configuration options
+ * @returns Object with hooks and rate limit control functions
+ *
+ * @example
+ * ```typescript
+ * const { hooks, getCurrentUsage, getRemainingTokens, reset } = createManagedRateLimitHooks({
+ *   maxTokensPerWindow: 100000,
+ *   windowMs: 60000,
+ * });
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PreGenerate: [{ hooks: [hooks[0]] }],
+ *     PostGenerate: [{ hooks: [hooks[1]] }],
+ *   },
+ * });
+ *
+ * // Check current usage
+ * const used = getCurrentUsage();
+ * const remaining = getRemainingTokens();
+ * console.log(`Token usage: ${used} / ${maxTokensPerWindow} (${remaining} remaining)`);
+ *
+ * // Reset limits (e.g., for testing or manual override)
+ * reset();
+ * ```
+ *
+ * @category Hooks
+ */
+export function createManagedRateLimitHooks(options = {}) {
+    const { maxTokensPerWindow = 100000, windowMs = 60000, limitMessage = "Rate limit exceeded. Please try again later.", shouldAllow = (tokensUsed, maxTokens) => tokensUsed < maxTokens, enableServerLimits = false, extractServerLimits = extractStandardRateLimitHeaders, perToolQuota = false, toolLimits = {}, } = options;
+    const rateLimiter = new TokenBucketRateLimiter(maxTokensPerWindow, windowMs, perToolQuota, toolLimits);
+    const rateCheck = async (input) => {
+        if (input.hook_event_name !== "PreGenerate")
+            return {};
+        const currentUsage = rateLimiter.getCurrentUsage();
+        if (!shouldAllow(currentUsage, maxTokensPerWindow)) {
+            const serverLimits = rateLimiter.getServerLimits();
+            let reason = limitMessage;
+            if (serverLimits?.reset) {
+                const resetDate = new Date(serverLimits.reset * 1000);
+                reason = `${limitMessage} Rate limit resets at ${resetDate.toISOString()}.`;
+            }
+            else if (serverLimits?.retryAfter) {
+                reason = `${limitMessage} Retry after ${serverLimits.retryAfter} seconds.`;
+            }
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreGenerate",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason,
+                },
+            };
+        }
+        return {};
+    };
+    const usageTracker = async (input) => {
+        if (input.hook_event_name !== "PostGenerate")
+            return {};
+        const postGenInput = input;
+        const tokens = postGenInput.result.usage?.totalTokens ?? 0;
+        rateLimiter.recordUsage(tokens);
+        if (enableServerLimits) {
+            const serverLimits = extractServerLimits(postGenInput);
+            if (serverLimits) {
+                rateLimiter.updateServerLimits(serverLimits);
+            }
+        }
+        return {};
+    };
+    return {
+        hooks: [rateCheck, usageTracker],
+        getCurrentUsage: () => rateLimiter.getCurrentUsage(),
+        getRemainingTokens: () => rateLimiter.getRemainingTokens(),
+        getServerLimits: () => rateLimiter.getServerLimits(),
+        reset: () => rateLimiter.reset(),
+    };
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/hooks/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/hooks/rate-limit.ts"],"names":[],"mappings":"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"}