export type UrlDownloadFailureKind = "cancelled" | "timeout" | "http_not_found" | "http_rejected" | "http_transient" | "network" | "empty_body" | "range_protocol" | "length_mismatch" | "hash_mismatch" | "invalid_payload" | "filesystem";
export type UrlDownloadTelemetryOutcome = "attempt_failed" | "cache_hit" | "published" | "race_reused" | "retrying";
export interface UrlDownloadTelemetry {
    urlFingerprint: string;
    initialHost?: string;
    finalHost?: string;
    attempt: number;
    outcome: UrlDownloadTelemetryOutcome;
    status?: number;
    expectedBytes?: number;
    receivedBytes?: number;
    rangeDisposition?: "none" | "malformed_206" | "unsolicited_206" | "content_range_on_200" | "full_object_200";
    etagFingerprint?: string;
    etagWeak?: boolean;
    localSize?: number;
    localSha256?: string;
    failureKind?: UrlDownloadFailureKind;
}
export interface UrlDownloadOptions {
    /** Optional strong checksum supplied by a trusted caller. */
    expectedSha256?: string;
    onTelemetry?: (event: UrlDownloadTelemetry) => void;
}
export interface PublicHttpsTextOptions {
    /** Maximum decoded response bytes retained in memory. */
    maxBytes: number;
    timeoutMs?: number;
    signal?: AbortSignal;
}
export interface SafeDownloadUrlIdentity {
    urlFingerprint: string;
    host?: string;
}
/** Query-free, non-reversible URL identity suitable for logs and metrics. */
export declare function safeDownloadUrlIdentity(url: string): SafeDownloadUrlIdentity;
/** Default safe structured sink for engine media call sites without a logger. */
export declare function writeUrlDownloadTelemetry(event: UrlDownloadTelemetry): void;
export declare class UrlDownloadError extends Error {
    readonly kind: UrlDownloadFailureKind;
    readonly retryable: boolean;
    readonly status?: number | undefined;
    readonly telemetry?: Partial<UrlDownloadTelemetry> | undefined;
    /** A bounded in-call refetch can be safe even when upstream retry is not. */
    readonly locallyRetryable: boolean;
    constructor(kind: UrlDownloadFailureKind, retryable: boolean, message: string, status?: number | undefined, telemetry?: Partial<UrlDownloadTelemetry> | undefined, 
    /** A bounded in-call refetch can be safe even when upstream retry is not. */
    locallyRetryable?: boolean);
}
/**
 * Validate that a URL is safe to fetch on behalf of customer-supplied
 * compositions. Throws if the URL is non-HTTPS or targets a private/reserved
 * address range (SSRF guard).
 */
export declare function assertPublicHttpsUrl(url: string): void;
/** Fetch bounded UTF-8 text while applying the downloader's redirect and SSRF policy to every hop. */
export declare function fetchPublicHttpsText(url: string, options: PublicHttpsTextOptions): Promise<string>;
export declare function downloadToTemp(url: string, destDir: string, timeoutMs?: number, signal?: AbortSignal, onTransientRetry?: (error: UrlDownloadError) => void, options?: UrlDownloadOptions): Promise<string>;
export declare function isHttpUrl(path: string): boolean;
//# sourceMappingURL=urlDownloader.d.ts.map