/**
 * Generic HTTP fetch with caching and zip extraction utilities.
 *
 * Provides the download + cache + zip pattern used by lexicon codegen
 * pipelines that fetch schemas from remote sources.
 */
export interface FetchConfig {
    /** URL to fetch. */
    url: string;
    /** Local file path for caching the download. */
    cacheFile: string;
    /** Cache TTL in milliseconds (default: 24 hours). */
    cacheTtlMs?: number;
}
/**
 * Fetch a URL, retrying on transient failures (network errors and
 * retryable HTTP statuses) with exponential backoff.
 *
 * Permanent failures (e.g. 404, 403) are not retried — they throw on the
 * first response. The returned response is guaranteed `ok`.
 *
 * When a `Retry-After` header is present on a 429 or 503 response the delay
 * from that header is used instead of the exponential back-off for that
 * specific retry, capped at {@link MAX_RETRY_AFTER_MS}.
 *
 * `init` is passed through to `fetch` on every attempt, so callers that
 * need request headers (e.g. the GitHub API `Accept` header) or an abort
 * signal get retries without duplicating the loop.
 *
 * On exhaustion a descriptive {@link TransientFetchError} is thrown rather
 * than the raw last error so the caller can surface a human-readable message.
 */
export declare function fetchWithRetry(url: string, retries?: number, backoffMs?: number, init?: RequestInit, attemptTimeoutMs?: number): Promise<Response>;
/**
 * Thrown when {@link fetchWithRetry} exhausts all retry attempts on a
 * transient failure (429 / 5xx / network error).
 *
 * The message is human-readable and actionable: it names the URL, the number
 * of attempts made, and the last HTTP status (if any) so that an upstream Op
 * can route it to a report/issue without exposing a raw stack trace.
 */
export declare class TransientFetchError extends Error {
    readonly url: string;
    readonly retries: number;
    readonly lastStatus: number | undefined;
    readonly cause?: Error | undefined;
    constructor(url: string, retries: number, lastStatus: number | undefined, cause?: Error | undefined);
}
/**
 * Fetch a URL with local file caching.
 *
 * Returns cached data if the cache file exists and is younger than cacheTtlMs.
 * Otherwise downloads from the URL, caches the result, and returns it.
 */
export declare function fetchWithCache(config: FetchConfig, force?: boolean): Promise<Buffer>;
/**
 * Extract files from a zip buffer using fflate.
 *
 * @param filter - Optional predicate to select which files to include.
 *   Receives the file name (path within the zip). Defaults to all files.
 * @returns Map of filename → Buffer for each extracted file.
 */
export declare function extractFromZip(zipData: Buffer, filter?: (name: string) => boolean): Promise<Map<string, Buffer>>;
/**
 * Extract files from an uncompressed tar buffer.
 *
 * The caller handles gunzip (via `fflate.gunzipSync` or `zlib.gunzipSync`)
 * and any prefix stripping. Returns `Map<path, Buffer>`.
 *
 * @param filter - Optional predicate to select which files to include.
 *   Receives the full file name (path within the tar). Defaults to all regular files.
 */
export declare function extractFromTar(tarData: Uint8Array, filter?: (path: string) => boolean): Map<string, Buffer>;
export interface FetchTarConfig {
    /** URL of the gzipped tarball. */
    url: string;
    /** Local directory for extracted files. */
    destDir: string;
    /** Cache TTL in milliseconds (default: 7 days). */
    cacheTtlMs?: number;
}
/**
 * Fetch a gzipped tarball, extract files matching `tarPrefix`, and cache them
 * in `destDir`. Returns `destDir`.
 *
 * Checks `destDir` mtime against TTL. If fresh, returns immediately.
 * Otherwise downloads, gunzips, extracts matching files, and writes to `destDir`.
 *
 * @param tarPrefix - Only files whose path (after stripping the top-level directory)
 *   starts with this prefix will be extracted.
 * @param force - If true, ignore cache and re-download.
 */
export declare function fetchAndExtractTar(config: FetchTarConfig, tarPrefix: string, force?: boolean): Promise<string>;
/**
 * Clear a cache file. Ignores errors if the file doesn't exist.
 */
export declare function clearCacheFile(cacheFile: string): void;
//# sourceMappingURL=fetch.d.ts.map