/**
 * @fileoverview Provides caching utilities for API responses and file attachments.
 * Uses LRU (Least Recently Used) eviction with configurable TTLs and memory limits.
 * Includes request deduplication to prevent duplicate concurrent API calls.
 * @module src/utils/cache/cacheService
 */
import { RequestContext } from "../internal/requestContext.js";
/**
 * Cache TTL configuration by query type.
 * Based on research: Perplexity API responses are NOT deterministic,
 * so TTLs are tuned per query volatility.
 */
export declare const CACHE_TTL: {
    /** 1 hour - stable technical information */
    readonly technical: number;
    /** 30 min - general knowledge queries */
    readonly general: number;
    /** 5 min - volatile data (news, prices) */
    readonly volatile: number;
    /** 2 hours - expensive deep research results */
    readonly deepResearch: number;
    /** 1 hour - file attachment content */
    readonly file: number;
};
/**
 * Structure for cached API responses.
 */
interface CachedResponse {
    /** The cached response data */
    data: unknown;
    /** Unix timestamp when cached */
    timestamp: number;
    /** The model used for this response */
    model: string;
}
/**
 * Structure for cached file content.
 */
interface CachedFile {
    /** Base64-encoded file content */
    base64: string;
    /** MIME type of the file */
    mimeType: string;
    /** Original source URL if fetched from URL */
    sourceUrl?: string;
    /** Size in bytes for cache size calculation */
    size: number;
}
/**
 * Generates a deterministic cache key from request parameters.
 * Uses stable JSON serialization + SHA256 hashing for collision resistance.
 *
 * @param params - The request parameters to hash
 * @returns A SHA256 hex digest cache key
 */
export declare function generateCacheKey(params: Record<string, unknown>): string;
/**
 * Retrieves a cached API response.
 *
 * @param key - The cache key (from generateCacheKey)
 * @returns The cached response or undefined if not found/expired
 */
export declare function getCachedResponse(key: string): CachedResponse | undefined;
/**
 * Stores an API response in the cache.
 *
 * @param key - The cache key
 * @param data - The response data to cache
 * @param model - The model name (for logging)
 * @param ttlMs - Optional custom TTL in milliseconds
 */
export declare function setCachedResponse(key: string, data: unknown, model: string, ttlMs?: number): void;
/**
 * Executes a request with deduplication.
 * If an identical request is already in-flight, returns the existing promise
 * instead of making a duplicate API call.
 *
 * @param key - The cache key for the request
 * @param fetcher - Async function that performs the actual request
 * @param context - Request context for logging
 * @returns The request result (shared if deduplicated)
 */
export declare function deduplicatedRequest<T>(key: string, fetcher: () => Promise<T>, context: RequestContext): Promise<T>;
/**
 * Computes a SHA256 hash of file content for deduplication.
 *
 * @param content - The file content (string or Buffer)
 * @returns SHA256 hex digest
 */
export declare function getFileContentHash(content: string | Buffer): string;
/**
 * Retrieves a cached file.
 *
 * @param hash - The file content hash
 * @returns The cached file or undefined if not found/expired
 */
export declare function getCachedFile(hash: string): CachedFile | undefined;
/**
 * Stores a file in the cache.
 *
 * @param hash - The file content hash
 * @param file - The file data to cache
 */
export declare function setCachedFile(hash: string, file: CachedFile): void;
/**
 * Returns current cache statistics for observability.
 *
 * @returns Object containing cache size and entry counts
 */
export declare function getCacheStats(): {
    responseCache: {
        size: number;
        calculatedSize: number | undefined;
    };
    fileCache: {
        size: number;
        calculatedSize: number | undefined;
    };
    inFlightRequests: number;
};
/**
 * Clears all caches. Useful for testing or manual cache invalidation.
 */
export declare function clearAllCaches(): void;
/**
 * Exported cache service object for convenient imports.
 */
export declare const cacheService: {
    generateCacheKey: typeof generateCacheKey;
    getCachedResponse: typeof getCachedResponse;
    setCachedResponse: typeof setCachedResponse;
    deduplicatedRequest: typeof deduplicatedRequest;
    getFileContentHash: typeof getFileContentHash;
    getCachedFile: typeof getCachedFile;
    setCachedFile: typeof setCachedFile;
    getCacheStats: typeof getCacheStats;
    clearAllCaches: typeof clearAllCaches;
    CACHE_TTL: {
        /** 1 hour - stable technical information */
        readonly technical: number;
        /** 30 min - general knowledge queries */
        readonly general: number;
        /** 5 min - volatile data (news, prices) */
        readonly volatile: number;
        /** 2 hours - expensive deep research results */
        readonly deepResearch: number;
        /** 1 hour - file attachment content */
        readonly file: number;
    };
};
export {};