/**
 * @module progress-callbacks
 * Enhanced progress tracking for xBind operations
 *
 * Provides domain-specific progress callbacks for long-running operations:
 * - Upload/download progress with bandwidth estimation
 * - Share distribution progress (XorIDA multi-channel delivery)
 * - Encryption/decryption progress
 * - Multi-stage operation tracking
 *
 * @example
 * ```typescript
 * const tracker = new OperationProgressTracker(onProgress);
 * tracker.startStage('encryption', 40); // 40% of total operation
 * // ... encryption work
 * tracker.updateStageProgress(50); // 50% of encryption stage
 * tracker.completeStage();
 * ```
 */
import type { ProgressCallback } from '@private.me/ux-helpers';
/**
 * Enhanced progress event with operation-specific metadata.
 */
export interface EnhancedProgressEvent {
    /** Current stage/operation name */
    readonly stage: string;
    /** Overall progress percentage (0-100) */
    readonly progress: number;
    /** Stage-specific progress percentage (0-100) */
    readonly stageProgress: number;
    /** Human-readable status message */
    readonly status: string;
    /** Operation-specific metadata */
    readonly metadata?: ProgressMetadata;
}
/**
 * Progress metadata for different operation types.
 */
export interface ProgressMetadata {
    /** Bytes transferred (for upload/download) */
    readonly bytesTransferred?: number;
    /** Total bytes (for upload/download) */
    readonly totalBytes?: number;
    /** Transfer rate in bytes/second */
    readonly bytesPerSecond?: number;
    /** Estimated time remaining in milliseconds */
    readonly estimatedTimeRemaining?: number;
    /** Number of shares distributed (for XorIDA operations) */
    readonly sharesDistributed?: number;
    /** Total shares to distribute */
    readonly totalShares?: number;
    /** Current encryption/decryption operation */
    readonly cryptoOperation?: 'encrypt' | 'decrypt' | 'sign' | 'verify';
    /** Number of items processed */
    readonly itemsProcessed?: number;
    /** Total items to process */
    readonly totalItems?: number;
}
/**
 * Enhanced progress callback with metadata.
 */
export type EnhancedProgressCallback = (event: EnhancedProgressEvent) => void;
/**
 * Stage definition for multi-stage operations.
 */
export interface OperationStage {
    /** Stage identifier */
    readonly name: string;
    /** Weight of this stage (percentage of total operation, 0-100) */
    readonly weight: number;
    /** Human-readable description */
    readonly description: string;
}
/**
 * Options for operation progress tracking.
 */
export interface OperationProgressOptions {
    /** Progress callback */
    readonly onProgress?: ProgressCallback | EnhancedProgressCallback;
    /** Enable bandwidth estimation for transfers */
    readonly estimateBandwidth?: boolean;
    /** Minimum interval between progress updates (ms) */
    readonly throttleMs?: number;
}
/**
 * Multi-stage operation progress tracker.
 *
 * Manages progress across multiple stages with weighted contributions
 * to overall progress. Useful for complex operations like:
 * - Message send: resolve DID (10%) → encrypt (30%) → split shares (20%) → distribute (40%)
 * - File transfer: prepare (5%) → encrypt (25%) → upload (70%)
 *
 * @example
 * ```typescript
 * const tracker = new OperationProgressTracker(onProgress);
 *
 * tracker.startStage('preparation', 10);
 * // ... prep work
 * tracker.completeStage();
 *
 * tracker.startStage('encryption', 40);
 * tracker.updateStageProgress(50); // Halfway through encryption
 * tracker.completeStage();
 *
 * tracker.startStage('distribution', 50);
 * // ... distribution work
 * tracker.complete();
 * ```
 */
export declare class OperationProgressTracker {
    private readonly callback?;
    private readonly throttleMs;
    private lastUpdateTime;
    private currentStage;
    private currentStageWeight;
    private currentStageProgress;
    private completedWeight;
    private metadata;
    /**
     * Create a new operation progress tracker.
     *
     * @param onProgress Progress callback (standard or enhanced)
     * @param options Tracking options
     */
    constructor(onProgress?: ProgressCallback | EnhancedProgressCallback, options?: Omit<OperationProgressOptions, 'onProgress'>);
    /**
     * Start a new stage.
     *
     * @param name Stage identifier
     * @param weight Weight of this stage (percentage of total, 0-100)
     * @param description Human-readable description
     */
    startStage(name: string, weight: number, description?: string): void;
    /**
     * Update progress within the current stage.
     *
     * @param stagePercent Progress percentage within current stage (0-100)
     * @param status Optional status message
     * @param metadata Optional progress metadata
     */
    updateStageProgress(stagePercent: number, status?: string, metadata?: Partial<ProgressMetadata>): void;
    /**
     * Complete the current stage and advance overall progress.
     */
    completeStage(): void;
    /**
     * Mark the entire operation as complete.
     */
    complete(): void;
    /**
     * Get current overall progress percentage.
     *
     * @returns Progress percentage (0-100)
     */
    getProgress(): number;
    /**
     * Update metadata without changing progress.
     *
     * @param metadata Metadata to merge
     */
    updateMetadata(metadata: Partial<ProgressMetadata>): void;
    /**
     * Report progress to callback (with throttling).
     *
     * @param status Status message
     */
    private reportProgress;
    /**
     * Check if callback expects enhanced events.
     *
     * @param callback Callback to check
     * @returns True if enhanced callback
     */
    private isEnhancedCallback;
}
/**
 * Transfer progress tracker with bandwidth estimation.
 *
 * Tracks upload/download progress with automatic bandwidth calculation
 * and estimated time remaining.
 *
 * @example
 * ```typescript
 * const tracker = new TransferProgressTracker(totalBytes, onProgress);
 *
 * for (const chunk of chunks) {
 *   await uploadChunk(chunk);
 *   tracker.addTransferred(chunk.length);
 * }
 *
 * tracker.complete();
 * ```
 */
export declare class TransferProgressTracker {
    private readonly totalBytes;
    private readonly callback?;
    private readonly reporter;
    private readonly throttleMs;
    private bytesTransferred;
    private startTime;
    private lastUpdateTime;
    private samples;
    private readonly maxSamples;
    /**
     * Create a new transfer progress tracker.
     *
     * @param totalBytes Total bytes to transfer
     * @param onProgress Progress callback
     * @param throttleMs Minimum interval between updates (default: 100ms)
     */
    constructor(totalBytes: number, onProgress?: ProgressCallback | EnhancedProgressCallback, throttleMs?: number);
    /**
     * Add transferred bytes and update progress.
     *
     * @param bytes Number of bytes transferred
     */
    addTransferred(bytes: number): void;
    /**
     * Mark transfer as complete.
     */
    complete(): void;
    /**
     * Get current progress percentage.
     *
     * @returns Progress percentage (0-100)
     */
    getProgress(): number;
    /**
     * Calculate current transfer rate.
     *
     * @returns Bytes per second
     */
    private calculateBytesPerSecond;
    /**
     * Estimate time remaining.
     *
     * @returns Estimated milliseconds remaining
     */
    private estimateTimeRemaining;
    /**
     * Report progress to callback.
     */
    private reportProgress;
    /**
     * Format status message with transfer details.
     *
     * @param progress Progress percentage
     * @param bytesPerSecond Transfer rate
     * @param estimatedTimeRemaining Time remaining in ms
     * @returns Formatted status string
     */
    private formatStatus;
    /**
     * Format bytes for display.
     *
     * @param bytes Number of bytes
     * @returns Formatted string (e.g., "1.5 MB")
     */
    private formatBytes;
    /**
     * Format time for display.
     *
     * @param ms Milliseconds
     * @returns Formatted string (e.g., "2m 30s")
     */
    private formatTime;
    /**
     * Check if callback expects enhanced events.
     *
     * @param callback Callback to check
     * @returns True if enhanced callback
     */
    private isEnhancedCallback;
}
/**
 * Share distribution progress tracker for XorIDA operations.
 *
 * Tracks progress of distributing shares across multiple channels.
 *
 * @example
 * ```typescript
 * const tracker = new ShareDistributionTracker(3, onProgress);
 *
 * await distributeShare(0);
 * tracker.markShareDistributed(0);
 *
 * await distributeShare(1);
 * tracker.markShareDistributed(1);
 *
 * await distributeShare(2);
 * tracker.markShareDistributed(2);
 *
 * tracker.complete();
 * ```
 */
export declare class ShareDistributionTracker {
    private readonly totalShares;
    private readonly callback?;
    private readonly reporter;
    private distributedShares;
    /**
     * Create a new share distribution tracker.
     *
     * @param totalShares Total number of shares to distribute
     * @param onProgress Progress callback
     */
    constructor(totalShares: number, onProgress?: ProgressCallback | EnhancedProgressCallback);
    /**
     * Mark a share as successfully distributed.
     *
     * @param shareIndex Zero-based share index
     */
    markShareDistributed(shareIndex: number): void;
    /**
     * Mark all shares as distributed and complete.
     */
    complete(): void;
    /**
     * Get current progress percentage.
     *
     * @returns Progress percentage (0-100)
     */
    getProgress(): number;
    /**
     * Report progress to callback.
     */
    private reportProgress;
    /**
     * Check if callback expects enhanced events.
     *
     * @param callback Callback to check
     * @returns True if enhanced callback
     */
    private isEnhancedCallback;
}
/**
 * Encryption progress tracker.
 *
 * Tracks progress of encryption/decryption operations on large data.
 *
 * @example
 * ```typescript
 * const tracker = new EncryptionProgressTracker('encrypt', totalChunks, onProgress);
 *
 * for (const chunk of chunks) {
 *   await encryptChunk(chunk);
 *   tracker.incrementProcessed();
 * }
 *
 * tracker.complete();
 * ```
 */
export declare class EncryptionProgressTracker {
    private readonly operation;
    private readonly totalItems;
    private readonly callback?;
    private readonly reporter;
    private itemsProcessed;
    /**
     * Create a new encryption progress tracker.
     *
     * @param operation Cryptographic operation type
     * @param totalItems Total number of items to process
     * @param onProgress Progress callback
     */
    constructor(operation: 'encrypt' | 'decrypt' | 'sign' | 'verify', totalItems: number, onProgress?: ProgressCallback | EnhancedProgressCallback);
    /**
     * Increment the number of processed items.
     *
     * @param count Number of items to add (default: 1)
     */
    incrementProcessed(count?: number): void;
    /**
     * Mark operation as complete.
     */
    complete(): void;
    /**
     * Get current progress percentage.
     *
     * @returns Progress percentage (0-100)
     */
    getProgress(): number;
    /**
     * Report progress to callback.
     */
    private reportProgress;
    /**
     * Check if callback expects enhanced events.
     *
     * @param callback Callback to check
     * @returns True if enhanced callback
     */
    private isEnhancedCallback;
}
