@emailcheck/email-validator-js/dist/presets.d.ts

Advanced email validation with MX records, SMTP verification, disposable email detection, batch processing, and caching. Production-ready with TypeScript support.

/**
 * Recommended `verifyEmail` / `verifyMailboxSMTP` configuration presets for
 * common deployment shapes.
 *
 * These are not magic — every value is just a `SMTPVerifyOptions` /
 * `VerifyEmailParams` field with a sensible default for that workload.
 * Use them directly, or spread + override:
 *
 *     await verifyEmail({
 *       emailAddress: 'foo@bar.com',
 *       ...VERIFY_EMAIL_PRESETS.serverless,
 *     });
 *
 *     // Or override one field:
 *     await verifyEmail({
 *       emailAddress: 'foo@bar.com',
 *       ...VERIFY_EMAIL_PRESETS.serverless,
 *       smtpTotalDeadlineMs: 3000,
 *     });
 *
 * Two parallel sets are exported:
 *
 *   - `SMTP_PRESETS`        — `SMTPVerifyOptions` shape, for callers using
 *                             `verifyMailboxSMTP` directly.
 *   - `VERIFY_EMAIL_PRESETS` — `VerifyEmailParams` shape, with the `smtp`-
 *                             prefixed field names that `verifyEmail` uses.
 *
 * Presets:
 *
 *   - `serverless` — tight latency budget. Cuts off bad MXes fast.
 *                    Suitable for Lambda / Vercel / Cloudflare-Workers
 *                    request handlers with sub-10s SLAs.
 *   - `dedicated`  — long-running server. Willing to retry once and wait
 *                    longer. Suitable for a dedicated worker / dyno that
 *                    isn't latency-bound.
 *   - `batch`      — running through millions of addresses, accuracy more
 *                    important than per-call latency. Multiple retries with
 *                    exponential backoff, generous timeouts.
 *   - `fast`       — favor speed over coverage. Single MX, single retry,
 *                    short deadlines. For autocomplete / form-validation
 *                    UX where the answer is needed in <2s.
 */
/**
 * Presets for `verifyMailboxSMTP`'s `options` field. Each preset is a
 * subset of `SMTPVerifyOptions` — spread it and override fields as needed.
 */
export declare const SMTP_PRESETS: {
    /**
     * **Serverless** — Lambda / Vercel / Cloudflare-Workers handlers.
     *
     * Tight latency budget; cuts off bad MXes fast. The total wall-clock
     * is bounded at 5 s so the probe finishes well inside a typical 10 s
     * handler SLA, leaving headroom for everything else the handler does.
     */
    readonly serverless: {
        readonly perAttemptTimeoutMs: 2500;
        readonly totalDeadlineMs: 5000;
        readonly maxConsecutiveFailures: 3;
        readonly maxMxHosts: 2;
    };
    /**
     * **Dedicated** — long-running server / worker.
     *
     * Not latency-bound. Tries every MX, retries connection-class failures
     * once with a 500 ms backoff. Suitable for an always-on backend that
     * processes verification requests as they arrive.
     */
    readonly dedicated: {
        readonly perAttemptTimeoutMs: 5000;
        readonly totalDeadlineMs: 30000;
        readonly retry: {
            readonly attempts: 1;
            readonly delayMs: 500;
            readonly backoff: "exponential";
        };
    };
    /**
     * **Batch** — bulk processing.
     *
     * Each address can take a while; what matters is correctness across
     * the whole batch. Multiple retries with exponential backoff to ride
     * out transient network blips. Generous per-attempt budget so slow
     * MXes get a fair shot.
     */
    readonly batch: {
        readonly perAttemptTimeoutMs: 10000;
        readonly totalDeadlineMs: 60000;
        readonly retry: {
            readonly attempts: 2;
            readonly delayMs: 1000;
            readonly backoff: "exponential";
        };
    };
    /**
     * **Fast** — UX-bound (form autocomplete / signup-form validation).
     *
     * Optimize for speed; accept that ambiguous results may be more common.
     * Tries the primary MX only, single retry, sub-3s wall-clock.
     */
    readonly fast: {
        readonly perAttemptTimeoutMs: 1500;
        readonly totalDeadlineMs: 3000;
        readonly maxConsecutiveFailures: 2;
        readonly maxMxHosts: 1;
    };
};
/**
 * Presets for `verifyEmail`'s top-level params. Each preset is a subset of
 * `VerifyEmailParams` — spread it and override fields as needed. The keys
 * use the `smtp`-prefixed names that `verifyEmail` accepts (matching the
 * unprefixed `SMTP_PRESETS` field-for-field).
 */
export declare const VERIFY_EMAIL_PRESETS: {
    /** See `SMTP_PRESETS.serverless`. */
    readonly serverless: {
        readonly smtpPerAttemptTimeoutMs: 2500;
        readonly smtpTotalDeadlineMs: 5000;
        readonly smtpMaxConsecutiveFailures: 3;
        readonly smtpMaxMxHosts: 2;
        readonly whoisTimeoutMs: 3000;
    };
    /** See `SMTP_PRESETS.dedicated`. */
    readonly dedicated: {
        readonly smtpPerAttemptTimeoutMs: 5000;
        readonly smtpTotalDeadlineMs: 30000;
        readonly smtpRetry: {
            readonly attempts: 1;
            readonly delayMs: 500;
            readonly backoff: "exponential";
        };
        readonly whoisTimeoutMs: 5000;
    };
    /** See `SMTP_PRESETS.batch`. */
    readonly batch: {
        readonly smtpPerAttemptTimeoutMs: 10000;
        readonly smtpTotalDeadlineMs: 60000;
        readonly smtpRetry: {
            readonly attempts: 2;
            readonly delayMs: 1000;
            readonly backoff: "exponential";
        };
        readonly whoisTimeoutMs: 8000;
    };
    /** See `SMTP_PRESETS.fast`. */
    readonly fast: {
        readonly smtpPerAttemptTimeoutMs: 1500;
        readonly smtpTotalDeadlineMs: 3000;
        readonly smtpMaxConsecutiveFailures: 2;
        readonly smtpMaxMxHosts: 1;
        readonly whoisTimeoutMs: 2000;
    };
};
/** Type-level sugar for picking a preset by name. */
export type SmtpPresetName = keyof typeof SMTP_PRESETS;
export type VerifyEmailPresetName = keyof typeof VERIFY_EMAIL_PRESETS;