/**
 * Binary downloads (`/documents/{id}`): streaming read under a byte cap
 * (issue #235), byte-level progress, and the two guards a document download
 * needs that a JSON request does not — the application-shell detection and
 * the `Content-Disposition` filename.
 */
import type { ProgressReporter } from "../progress.js";
/**
 * Parse the filename out of a `Content-Disposition` header. Handles the
 * common `filename="…"`/`filename=…` forms and the RFC 5987
 * `filename*=UTF-8''…` form. Returns undefined when absent. Exported for
 * unit testing.
 */
export declare function parseContentDispositionFilename(header: string | null): string | undefined;
/**
 * BoondManager writes the plain `filename="…"` form with UTF-8 bytes (often
 * NFD: `e` + combining acute), and `fetch` decodes header bytes as Latin-1 as
 * the spec says — so "Frédéric" arrives as "FreÌdeÌric" (observed live on
 * 2026-09-26, issue #311). Re-decode those bytes as UTF-8 when that yields a
 * clean string, and normalise to NFC so the name compares like a normal one.
 */
export declare function repairUtf8Filename(name: string): string;
export interface DownloadedDocument {
    data: Buffer;
    contentType: string;
    filename?: string;
}
/**
 * Thrown by `apiDownload` when the payload exceeds `maxBytes` — before the
 * body is read when the response announces its size, otherwise the moment the
 * running total crosses the cap (the stream is cancelled, nothing more is
 * buffered). `bytes` is the announced size in the first case and a lower
 * bound (bytes received so far) in the second; `announced` tells which.
 */
export declare class DownloadTooLargeError extends Error {
    readonly bytes: number;
    readonly maxBytes: number;
    readonly announced: boolean;
    constructor(path: string, bytes: number, maxBytes: number, announced: boolean);
}
/** Options for `apiDownload`. */
export interface DownloadOptions {
    /** Refuse payloads larger than this many bytes (see `DownloadTooLargeError`). */
    maxBytes?: number;
}
/**
 * Download a binary payload (documents, justificatifs…) from the BoondManager
 * API. Same pipeline as `apiRequest` (`send()`: auth, path guard, rate limit,
 * timeout, retry policy for a GET), but the body is streamed raw instead of
 * being parsed as JSON:API.
 *
 * `onProgress` reports bytes received when the client asked for progress and
 * the response carries a `Content-Length`; otherwise nothing is emitted.
 *
 * `options.maxBytes` bounds memory: a `Content-Length` above it is refused
 * before a single body byte is read, and a body without one is cancelled the
 * moment it crosses the cap (`DownloadTooLargeError` either way).
 */
export declare function apiDownload(path: string, onProgress?: ProgressReporter, options?: DownloadOptions): Promise<DownloadedDocument>;
//# sourceMappingURL=download.d.ts.map