/**
 * Adaptive Response Cache (P-001)
 *
 * Smart TTL optimization based on:
 * 1. Domain classification (static vs dynamic sites)
 * 2. Content volatility (learned from change history)
 * 3. HTTP Cache-Control headers
 * 4. Domain groups from heuristics config
 *
 * Goals:
 * - Longer TTL for stable content (gov, docs, wikis)
 * - Shorter TTL for dynamic content (social media, news)
 * - Learn from content change patterns
 * - Respect HTTP caching hints
 */
/** Default TTL for pages (15 minutes) */
declare const DEFAULT_PAGE_TTL_MS: number;
/** Default TTL for API responses (5 minutes) */
declare const DEFAULT_API_TTL_MS: number;
/** Minimum TTL to avoid excessive requests (30 seconds) */
declare const MIN_TTL_MS: number;
/** Maximum TTL for any content (24 hours) */
declare const MAX_TTL_MS: number;
/** TTL multipliers by domain type */
declare const TTL_MULTIPLIERS: {
    /** Government sites - very stable content */
    readonly static_gov: 4;
    /** Documentation sites - stable content */
    readonly static_docs: 3;
    /** Educational sites - stable content */
    readonly static_edu: 3;
    /** Wiki sites - moderately stable */
    readonly static_wiki: 2;
    /** General static sites */
    readonly static_default: 2;
    /** Social media - very dynamic */
    readonly dynamic_social: 0.25;
    /** News sites - dynamic */
    readonly dynamic_news: 0.5;
    /** E-commerce - moderately dynamic */
    readonly dynamic_commerce: 0.75;
    /** Unknown domain type */
    readonly default: 1;
};
/** Domain category for TTL calculation */
export type DomainCategory = 'static_gov' | 'static_docs' | 'static_edu' | 'static_wiki' | 'static_default' | 'dynamic_social' | 'dynamic_news' | 'dynamic_commerce' | 'default';
/**
 * Classify a domain into a category for TTL calculation.
 */
export declare function classifyDomain(domain: string): DomainCategory;
/**
 * Get the TTL multiplier for a domain category.
 */
export declare function getTTLMultiplier(category: DomainCategory): number;
/** Parsed Cache-Control directive values */
export interface CacheControlDirectives {
    /** max-age directive value in seconds */
    maxAge?: number;
    /** s-maxage directive value in seconds (shared cache) */
    sMaxAge?: number;
    /** Whether cache should be revalidated before use */
    mustRevalidate: boolean;
    /** Whether content should not be cached */
    noCache: boolean;
    /** Whether content should not be stored at all */
    noStore: boolean;
    /** Whether content is private (user-specific) */
    isPrivate: boolean;
    /** Whether content is public */
    isPublic: boolean;
    /** stale-while-revalidate value in seconds */
    staleWhileRevalidate?: number;
    /** stale-if-error value in seconds */
    staleIfError?: number;
}
/**
 * Parse Cache-Control header into structured directives.
 *
 * @param header - Cache-Control header value
 * @returns Parsed directives
 *
 * @example
 * ```ts
 * parseCacheControl('max-age=3600, must-revalidate')
 * // { maxAge: 3600, mustRevalidate: true, ... }
 * ```
 */
export declare function parseCacheControl(header: string | undefined): CacheControlDirectives;
/**
 * Clear all volatility data.
 * Useful for testing to ensure test isolation.
 */
export declare function clearVolatilityData(): void;
/**
 * Record a content check for volatility tracking.
 *
 * @param url - The URL that was checked
 * @param contentChanged - Whether the content changed since last check
 */
export declare function recordContentCheck(url: string, contentChanged: boolean): void;
/**
 * Get the volatility factor for a URL.
 *
 * @param url - The URL to check
 * @returns Volatility factor (0-1, where 0 = very stable, 1 = very volatile)
 */
export declare function getVolatilityFactor(url: string): number | null;
/**
 * Get volatility statistics for a domain.
 */
export declare function getDomainVolatilityStats(domain: string): {
    urlCount: number;
    avgChangeRate: number;
    mostVolatilePaths: Array<{
        path: string;
        changeRate: number;
    }>;
};
/** Options for calculating adaptive TTL */
export interface AdaptiveTTLOptions {
    /** URL being cached */
    url: string;
    /** Whether this is an API response (default: false for page) */
    isApiResponse?: boolean;
    /** Cache-Control header value from response */
    cacheControlHeader?: string;
    /** Custom base TTL in ms (overrides defaults) */
    baseTTL?: number;
    /** Freshness requirement hint */
    freshnessHint?: 'realtime' | 'cached' | 'any';
}
/** Result of TTL calculation */
export interface AdaptiveTTLResult {
    /** Calculated TTL in milliseconds */
    ttlMs: number;
    /** Domain category used for calculation */
    domainCategory: DomainCategory;
    /** TTL multiplier applied */
    multiplier: number;
    /** Whether HTTP cache headers were respected */
    respectedHeaders: boolean;
    /** Volatility factor if available */
    volatilityFactor: number | null;
    /** Explanation of how TTL was calculated */
    reason: string;
}
/**
 * Calculate an adaptive TTL based on multiple factors.
 *
 * @param options - Options for TTL calculation
 * @returns Calculated TTL and metadata
 *
 * @example
 * ```ts
 * const result = calculateAdaptiveTTL({
 *   url: 'https://docs.example.com/api/reference',
 *   cacheControlHeader: 'max-age=3600',
 * });
 * // result.ttlMs might be 3600000 (1 hour from header)
 *
 * const result2 = calculateAdaptiveTTL({
 *   url: 'https://twitter.com/user/status',
 * });
 * // result.ttlMs might be 225000 (3.75 minutes, social media penalty)
 * ```
 */
export declare function calculateAdaptiveTTL(options: AdaptiveTTLOptions): AdaptiveTTLResult;
/** Entry stored in the adaptive cache */
interface AdaptiveCacheEntry<T> {
    value: T;
    timestamp: number;
    expiresAt: number;
    ttlResult: AdaptiveTTLResult;
}
/** Statistics for cache performance */
export interface AdaptiveCacheStats {
    size: number;
    maxEntries: number;
    hits: number;
    misses: number;
    hitRate: number;
    entriesByCategory: Record<DomainCategory, number>;
    avgTTLMs: number;
    oldestEntry: number | null;
    newestEntry: number | null;
}
/**
 * Adaptive Response Cache with smart TTL.
 *
 * @typeParam T - Type of cached values
 */
export declare class AdaptiveCache<T = unknown> {
    protected cache: Map<string, AdaptiveCacheEntry<T>>;
    protected readonly maxEntries: number;
    private hits;
    private misses;
    constructor(maxEntries?: number);
    /**
     * Generate a cache key from URL and optional parameters.
     */
    protected generateKey(url: string, params?: Record<string, string>): string;
    /**
     * Get a cached value if it exists and hasn't expired.
     */
    get(url: string, params?: Record<string, string>): T | undefined;
    /**
     * Store a value in the cache with adaptive TTL.
     */
    set(url: string, value: T, options?: {
        params?: Record<string, string>;
        cacheControlHeader?: string;
        isApiResponse?: boolean;
        freshnessHint?: 'realtime' | 'cached' | 'any';
    }): AdaptiveTTLResult;
    /**
     * Check if a URL is cached (and not expired).
     */
    has(url: string, params?: Record<string, string>): boolean;
    /**
     * Remove a specific entry from the cache.
     */
    delete(url: string, params?: Record<string, string>): boolean;
    /**
     * Remove all expired entries.
     */
    cleanup(): number;
    /**
     * Evict the oldest entries to make room.
     * Uses FIFO eviction leveraging Map's insertion order for O(1) performance.
     */
    private evictOldest;
    /**
     * Clear the entire cache.
     */
    clear(): void;
    /**
     * Clear cache entries for a specific domain.
     */
    clearDomain(domain: string): number;
    /**
     * Get all unique domains in the cache.
     */
    getDomains(): string[];
    /**
     * Get cache statistics.
     */
    getStats(): AdaptiveCacheStats;
    /**
     * Get the TTL result for a cached entry.
     */
    getTTLResult(url: string, params?: Record<string, string>): AdaptiveTTLResult | undefined;
    /**
     * Wrap an async function with caching.
     */
    withCache<R extends T>(url: string, fn: () => Promise<R>, options?: {
        params?: Record<string, string>;
        cacheControlHeader?: string;
        isApiResponse?: boolean;
        freshnessHint?: 'realtime' | 'cached' | 'any';
    }): Promise<{
        value: R;
        fromCache: boolean;
        ttlResult?: AdaptiveTTLResult;
    }>;
}
/** Content entry with hash for change detection */
interface ContentEntry {
    html: string;
    contentHash: string;
    fetchedAt: number;
}
/**
 * Adaptive content cache with change detection.
 */
export declare class AdaptiveContentCache extends AdaptiveCache<ContentEntry> {
    constructor(maxEntries?: number);
    /**
     * Simple hash function for content comparison.
     */
    static hashContent(content: string): string;
    /**
     * Check if content has changed since last cache and record for volatility.
     */
    hasContentChanged(url: string, newContent: string): boolean;
    /**
     * Store content with adaptive TTL and change detection.
     */
    setContent(url: string, html: string, options?: {
        cacheControlHeader?: string;
        freshnessHint?: 'realtime' | 'cached' | 'any';
    }): AdaptiveTTLResult;
}
/** Default adaptive page cache */
export declare const adaptivePageCache: AdaptiveContentCache;
/** Default adaptive API cache */
export declare const adaptiveApiCache: AdaptiveCache<unknown>;
export { DEFAULT_PAGE_TTL_MS, DEFAULT_API_TTL_MS, MIN_TTL_MS, MAX_TTL_MS, TTL_MULTIPLIERS, };
//# sourceMappingURL=adaptive-cache.d.ts.map