utils/cooldown.py

# utils/cooldown.py
import time
from cachetools import TTLCache

# Stores up to 10,000 users. Entries auto-delete after 15 seconds.
GLOBAL_COOLDOWNS = TTLCache(maxsize=10000, ttl=15.0)

def check_and_apply_cooldown(user_id: int) -> float:
    """
    Checks if a user is on cooldown across the entire bot.
    Returns 0.0 if they are clear to proceed, otherwise returns remaining seconds.
    """
    current_time = time.time()
    
    if user_id in GLOBAL_COOLDOWNS:
        expiry_time = GLOBAL_COOLDOWNS[user_id]
        if current_time < expiry_time:
            return expiry_time - current_time
            
    # Apply the 15-second cooldown block
    GLOBAL_COOLDOWNS[user_id] = current_time + 15.0
    return 0.0