/**
 * Email validation options.
 */
interface EmailValidationOptions {
    /**
     * Whether to block known disposable email domains.
     * @default false
     */
    blockDisposable?: boolean;
}
/**
 * Detailed email validation result.
 */
interface EmailValidationResult {
    isValid: boolean;
    domain?: string;
    isDisposable?: boolean;
}
/**
 * Options for email masking.
 */
interface EmailMaskOptions {
    /**
     * Number of characters to keep visible at the start of the username.
     * @default 1
     */
    visibleStart?: number;
    /**
     * Number of characters to keep visible at the end of the username.
     * @default 1
     */
    visibleEnd?: number;
    /**
     * Character used for masking.
     * @default '*'
     */
    maskChar?: string;
}
/**
 * Detailed email information.
 */
interface EmailInfo {
    username: string;
    domain: string;
    isCommonProvider: boolean;
    isDisposable: boolean;
}

/**
 * Validates if a string is a properly formatted email address based on RFC 5322.
 *
 * Performs checks for:
 * - Proper email format (regex).
 * - RFC specific rules (no double dots, username length < 64).
 * - Maximum total length (254 characters).
 * - Optional: disposable email detection.
 *
 * @param email - The email string to validate.
 * @param options - Optional validation configuration.
 * @returns `true` if valid, `false` otherwise.
 *
 * @example
 * ```typescript
 * import { validateEmail } from '@indodev/toolkit/email-validator';
 *
 * validateEmail('user@example.com'); // true
 * validateEmail('invalid-email'); // false
 * validateEmail('spam@mailinator.com', { blockDisposable: true }); // false
 * ```
 */
declare function validateEmail(email: string, options?: EmailValidationOptions): boolean;
/**
 * Parses an email address to extract useful metadata.
 *
 * @param email - The email address to parse.
 * @returns `EmailInfo` object containing details or `null` if the email is invalid.
 *
 * @example
 * ```typescript
 * import { getEmailInfo } from '@indodev/toolkit/email-validator';
 *
 * const info = getEmailInfo('adam@gmail.com');
 * // { username: 'adam', domain: 'gmail.com', isCommonProvider: true, isDisposable: false }
 * ```
 */
declare function getEmailInfo(email: string): EmailInfo | null;
/**
 * Masks the username portion of an email for privacy protection.
 *
 * Falls back to a standard mask if the username is too short to respect visibleStart/visibleEnd.
 *
 * @param email - The email address to mask.
 * @param options - Optional masking configuration.
 * @returns Masked email string or original if invalid.
 *
 * @example
 * ```typescript
 * import { maskEmail } from '@indodev/toolkit/email-validator';
 *
 * maskEmail('user@example.com'); // 'u**r@example.com'
 * maskEmail('user@example.com', { maskChar: '#' }); // 'u##r@example.com'
 * ```
 */
declare function maskEmail(email: string, options?: EmailMaskOptions): string;
/**
 * Normalizes an email address by trimming whitespace and converting to lowercase.
 *
 * @param email - The email to normalize.
 * @returns Normalized email string.
 *
 * @example
 * ```typescript
 * import { normalizeEmail } from '@indodev/toolkit/email-validator';
 *
 * normalizeEmail('  USER@Example.COM  '); // 'user@example.com'
 * ```
 */
declare function normalizeEmail(email: string): string;

/**
 * Error thrown when an invalid email is provided to a function.
 * Extends native Error with a `code` property for programmatic error handling.
 *
 * @example
 * ```typescript
 * try {
 *   requireEmail('invalid');
 * } catch (error) {
 *   if (error instanceof InvalidEmailError) {
 *     console.log(error.code); // 'INVALID_EMAIL'
 *   }
 * }
 * ```
 *
 * @public
 */
declare class InvalidEmailError extends Error {
    readonly code: "INVALID_EMAIL";
    constructor(message?: string);
}

export { type EmailInfo, type EmailMaskOptions, type EmailValidationOptions, type EmailValidationResult, InvalidEmailError, getEmailInfo, maskEmail, normalizeEmail, validateEmail };