@emailcheck/email-validator-js 5.0.0-beta.1 → 5.0.0

package/dist/presets.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emailcheck/email-validator-js",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0",
   "private": false,
   "description": "Advanced email validation with MX records, SMTP verification, disposable email detection, batch processing, and caching. Production-ready with TypeScript support.",
   "keywords": [