/**
 * State Store Types
 *
 * The StateStore provides scoped storage for session and user data,
 * with built-in helpers for common patterns like dismissals, cooldowns,
 * and frequency caps.
 */
/**
 * Scoped storage interface for reading/writing state.
 */
export interface ScopedStorage {
    /**
     * Get a value from storage.
     * @param key - Storage key
     * @returns The stored value or undefined
     */
    get<T>(key: string): T | undefined;
    /**
     * Set a value in storage.
     * @param key - Storage key
     * @param value - Value to store
     * @param ttlMs - Optional time-to-live in milliseconds
     */
    set<T>(key: string, value: T, ttlMs?: number): void;
    /**
     * Remove a value from storage.
     * @param key - Storage key
     */
    remove(key: string): void;
    /**
     * Check if a key exists in storage.
     * @param key - Storage key
     */
    has(key: string): boolean;
    /**
     * Get all keys in this storage scope.
     */
    keys(): string[];
    /**
     * Clear all values in this storage scope.
     */
    clear(): void;
}
/**
 * Dismissal store for tracking dismissed items.
 */
export interface DismissalStore {
    /**
     * Mark an item as dismissed.
     * @param key - Item identifier
     * @param permanent - If true, store in user storage (persistent). Default: session storage.
     */
    mark(key: string, permanent?: boolean): void;
    /**
     * Check if an item has been dismissed.
     * @param key - Item identifier
     */
    isDismissed(key: string): boolean;
    /**
     * Clear a dismissal.
     * @param key - Item identifier
     */
    clear(key: string): void;
    /**
     * Clear all dismissals.
     */
    clearAll(): void;
}
/**
 * Cooldown store for time-based restrictions.
 */
export interface CooldownStore {
    /**
     * Set a cooldown for an item.
     * @param key - Item identifier
     * @param durationMs - Cooldown duration in milliseconds
     */
    set(key: string, durationMs: number): void;
    /**
     * Check if a cooldown is active.
     * @param key - Item identifier
     */
    isActive(key: string): boolean;
    /**
     * Get remaining cooldown time in milliseconds.
     * @param key - Item identifier
     * @returns Remaining time, or 0 if not active
     */
    remaining(key: string): number;
    /**
     * Clear a cooldown.
     * @param key - Item identifier
     */
    clear(key: string): void;
}
/**
 * Frequency store for counting occurrences.
 */
export interface FrequencyStore {
    /**
     * Increment the count for an item.
     * @param key - Item identifier
     * @param resetAfterMs - Optional reset window in milliseconds
     * @returns The new count
     */
    increment(key: string, resetAfterMs?: number): number;
    /**
     * Get the current count for an item.
     * @param key - Item identifier
     */
    count(key: string): number;
    /**
     * Reset the count for an item.
     * @param key - Item identifier
     */
    reset(key: string): void;
    /**
     * Check if an item has reached a limit.
     * @param key - Item identifier
     * @param limit - Maximum count
     */
    hasReachedLimit(key: string, limit: number): boolean;
}
/**
 * Stored value with optional TTL metadata.
 */
export interface StoredValue<T = unknown> {
    value: T;
    expiresAt?: number;
}
/**
 * Frequency entry with count and reset metadata.
 */
export interface FrequencyEntry {
    count: number;
    resetAt?: number;
}
