/**
 * Progress indicator utilities using ora spinner.
 *
 * Per clig.dev guidelines:
 * - "Responsive is more important than fast - print something in <100ms"
 * - "Show progress if something takes a long time"
 * - "If your program displays no output for a while, it will look broken"
 *
 * Spinner behavior:
 * - Only shows after 100ms delay (avoid flicker for fast operations)
 * - Disabled when stderr is not a TTY (piped/redirected)
 * - Disabled in verbose mode (verbose output serves same purpose)
 * - Writes to stderr to keep stdout clean for pipeable data
 */
import { type Ora } from "ora";
/**
 * Options for the spinner.
 */
export interface SpinnerOptions {
    /** Message to display while operation is in progress */
    text: string;
    /** Message to display on success (optional) */
    successText?: string;
    /** Message to display on failure (optional) */
    failText?: string;
}
/**
 * Check if spinner should be shown.
 * Disabled when:
 * - stderr is not a TTY (output is piped/redirected)
 * - verbose mode is enabled (verbose output replaces spinner)
 */
export declare function shouldShowSpinner(): boolean;
/**
 * Execute an async operation with a spinner.
 *
 * The spinner only appears after 100ms delay to avoid flicker for fast operations.
 * If the operation completes before 100ms, no spinner is shown.
 *
 * @param options - Spinner options (text, successText, failText)
 * @param operation - Async operation to execute
 * @returns The result of the operation
 *
 * @example
 * const result = await withSpinner(
 *   { text: "Fetching bookmarks...", successText: "Done!" },
 *   () => client.getRaindrops(collectionId)
 * );
 */
export declare function withSpinner<T>(options: SpinnerOptions | string, operation: () => Promise<T>): Promise<T>;
/**
 * Create a manual spinner for operations that need progress updates.
 * Useful for batch operations where you want to update the message.
 *
 * Returns null if spinner shouldn't be shown (non-TTY, verbose mode).
 *
 * @param text - Initial spinner text
 * @returns Ora spinner instance or null
 *
 * @example
 * const spinner = createSpinner("Processing bookmarks...");
 * for (let i = 0; i < items.length; i++) {
 *   spinner?.text = `Processing ${i + 1}/${items.length}...`;
 *   await processItem(items[i]);
 * }
 * spinner?.succeed("Processed all bookmarks");
 */
export declare function createSpinner(text: string): Ora | null;
//# sourceMappingURL=spinner.d.ts.map