import type { B2CInstance } from '../../instance/index.js';
/** Progress info passed to the onProgress callback. */
export interface DownloadProgressInfo {
    /** Current operation phase */
    phase: 'zipping' | 'downloading' | 'cleanup' | 'extracting';
    /** Seconds elapsed since the current phase started */
    elapsedSeconds: number;
}
/**
 * Options for downloading cartridges.
 */
export interface DownloadOptions {
    /** Cartridge names to include (if empty/undefined, all are included) */
    include?: string[];
    /** Cartridge names to exclude */
    exclude?: string[];
    /** When provided, maps cartridge names to local paths for mirror extraction */
    mirror?: Map<string, string>;
    /** Callback for progress updates. Called when a phase starts (elapsedSeconds=0) and periodically thereafter. */
    onProgress?: (info: DownloadProgressInfo) => void;
}
/**
 * Result of a cartridge download.
 */
export interface DownloadResult {
    /** Cartridge names that were extracted */
    cartridges: string[];
    /** Code version downloaded from */
    codeVersion: string;
    /** Output directory where cartridges were extracted (empty string if mirror-only) */
    outputDirectory: string;
}
/**
 * Downloads a single cartridge from an instance via WebDAV.
 *
 * This is more efficient than downloading the entire code version when only
 * one cartridge is needed, as it ZIPs only the cartridge subdirectory on the server.
 *
 * @param instance - B2C instance to download from
 * @param codeVersion - Code version containing the cartridge
 * @param cartridgeName - Name of the cartridge to download
 * @param outputPath - Local path to extract the cartridge into
 * @param onProgress - Optional progress callback
 * @returns Promise that resolves when the cartridge has been successfully downloaded and extracted
 */
export declare function downloadSingleCartridge(instance: B2CInstance, codeVersion: string, cartridgeName: string, outputPath: string, onProgress?: (info: DownloadProgressInfo) => void): Promise<void>;
/**
 * Downloads cartridges from an instance via WebDAV.
 *
 * When `include` specifies cartridges, each is downloaded individually using
 * per-cartridge server-side zipping for efficiency. When downloading all
 * cartridges (no include filter), the entire code version is zipped at once.
 *
 * If `instance.config.codeVersion` is not set, attempts to discover the active
 * code version via OCAPI. If that also fails, throws an error.
 *
 * @param instance - B2C instance to download from
 * @param outputDirectory - Directory to extract cartridges into
 * @param options - Download options (filters, mirror)
 * @returns Download result with cartridge names and metadata
 * @throws Error if code version cannot be determined or download fails
 *
 * @example
 * ```typescript
 * // Download all cartridges
 * const result = await downloadCartridges(instance, './output');
 *
 * // Download specific cartridges (efficient per-cartridge download)
 * const result = await downloadCartridges(instance, './output', {
 *   include: ['app_storefront_base'],
 * });
 *
 * // Mirror to local project locations
 * const mirror = new Map([['app_storefront_base', '/project/cartridges/app_storefront_base']]);
 * const result = await downloadCartridges(instance, '.', { mirror });
 * ```
 */
export declare function downloadCartridges(instance: B2CInstance, outputDirectory: string, options?: DownloadOptions): Promise<DownloadResult>;