@emailcheck/email-validator-js 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/types.d.ts

@@ -1,7 +1,5 @@
 import type { Cache } from './cache-interface';
-/**
- * Error codes for email verification failures
- */
+/** Error codes set on `VerificationResult.metadata.error` when `verifyEmail` cannot deliver a definitive verdict. */
 export declare enum VerificationErrorCode {
     invalidFormat = "INVALID_FORMAT",
     invalidDomain = "INVALID_DOMAIN",
@@ -9,14 +7,9 @@ export declare enum VerificationErrorCode {
     smtpConnectionFailed = "SMTP_CONNECTION_FAILED",
     smtpTimeout = "SMTP_TIMEOUT",
     mailboxNotFound = "MAILBOX_NOT_FOUND",
-    mailboxFull = "MAILBOX_FULL",
     networkError = "NETWORK_ERROR",
-    disposableEmail = "DISPOSABLE_EMAIL",
-    freeEmailProvider = "FREE_EMAIL_PROVIDER"
+    disposableEmail = "DISPOSABLE_EMAIL"
 }
-/**
- * Main verification result interface (flat structure)
- */
 /** Discriminator for `VerificationStep.kind`. */
 export type VerificationStepKind = 'syntax' | 'domain-validation' | 'name-detection' | 'domain-suggestion' | 'disposable' | 'free' | 'mx-lookup' | 'smtp-probe' | 'whois-age' | 'whois-registration';
 /**
@@ -55,10 +48,7 @@ export interface VerificationResult {
     isDeliverable?: boolean;
     /** Whether the email/account is disabled */
     isDisabled?: boolean;
-    /**
-     * Always populated by `verifyEmail`. Optional in older shapes is gone —
-     * callers can read it directly without optional chaining.
-     */
+    /** Always populated by `verifyEmail` — read directly without optional chaining. */
     metadata: {
         verificationTime: number;
         cached: boolean;
@@ -199,9 +189,14 @@ export interface SmtpVerificationResult {
     /**
      * Short reason key when `isDeliverable === false`. Vocabulary:
      *   `not_found` | `over_quota` | `temporary_failure` | `ambiguous` |
-     *   `connection_error` | `connection_timeout` | `tls_error` |
-     *   `ehlo_failed` | `helo_failed` | `mail_from_rejected` | `no_greeting` |
-     *   `no_mx_records` | `unrecognized_response` | `step_timeout`
+     *   `connection_error` | `connection_timeout` | `connection_closed` |
+     *   `tls_upgrade_failed` | `tls_handshake_failed` |
+     *   `ehlo_failed` | `helo_failed` | `mail_from_rejected` |
+     *   `no_greeting` | `no_mx_records` | `unrecognized_response` |
+     *   `step_timeout` | `socket_timeout`
+     *
+     * Pass to `refineReasonByEnhancedStatus(error, enhancedStatus)` for a
+     * richer (mailbox-status-aware) reason when the MX returned a DSN.
      */
     error?: string;
     /** Most recent 3-digit SMTP code observed during the probe. */
@@ -268,14 +263,16 @@ export interface SMTPTLSConfig {
     minVersion?: 'TLSv1.2' | 'TLSv1.3';
 }
 /**
- * SMTP protocol steps. Only the steps the verifier actually walks are listed —
- * STARTTLS upgrade, VRFY, and QUIT used to be separate enum members but were
- * never reachable from production callers.
+ * SMTP protocol steps walked by the verifier in order. `startTls` is a
+ * conditional step — it sends the STARTTLS command and upgrades the socket
+ * to TLS when the MX advertised support (controlled by
+ * `SMTPVerifyOptions.startTls`). On implicit-TLS ports (465) it's a no-op.
  */
 export declare enum SMTPStep {
     greeting = "GREETING",
     ehlo = "EHLO",
     helo = "HELO",
+    startTls = "STARTTLS",
     mailFrom = "MAIL_FROM",
     rcptTo = "RCPT_TO"
 }
@@ -323,6 +320,18 @@ export interface SMTPVerifyOptions {
      * - `'force'`: pipeline without checking — testing escape hatch.
      */
     pipelining?: 'auto' | 'never' | 'force';
+    /**
+     * Controls STARTTLS upgrade on plaintext ports (25, 587). Implicit-TLS
+     * ports (465) ignore this option — they're already TLS from the start.
+     *
+     * - `'auto'` (default): upgrade if the MX advertises STARTTLS in EHLO.
+     *   Submission-port (587) MXes typically require this — without it,
+     *   `MAIL FROM` is rejected with `530 Must issue STARTTLS first`.
+     * - `'never'`: never upgrade — send `MAIL FROM` / `RCPT TO` in plaintext.
+     * - `'force'`: send `STARTTLS` unconditionally. Fails with
+     *   `tls_upgrade_failed` when the MX doesn't support it. Testing only.
+     */
+    startTls?: 'auto' | 'never' | 'force';
 }
 export interface VerifyMailboxSMTPParams {
     local: string;

package/package.json

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