zynor 0.0.68 → 0.0.73

package/dist/index.d.ts

@@ -2096,7 +2096,26 @@ declare const records: readonly [
 	}
 ];
 type ProviderName$1 = typeof records[number]["name"] | ProviderNames;
+/**
+ * Logger signature for debug output. Receives one preformatted line per event.
+ */
+export type DebugLogger = (line: string) => void;
 export interface ValidationConfig {
+	/**
+	 * Enable structured debug logging for every async boundary in the
+	 * validation flow (cache hits/misses, MX resolution, MX-record matches,
+	 * domain_check probes, deep-validation phases, IP-lookup cascade,
+	 * inflight enter/exit). Useful for diagnosing slow or stalled calls.
+	 *
+	 * - `true` — log to stderr via `console.error`
+	 * - `(line: string) => void` — receive each line as a string
+	 * - `false` / omitted — silent (no overhead)
+	 *
+	 * Each line is `[zynor HH:MM:SS.mmm] <scope>: <msg>`.
+	 *
+	 * @default false
+	 */
+	debug?: boolean | DebugLogger;
 	/**
 	 * @description This will enable deep validation of the email. slower than normal email validator as it triggers multiple dns requests, or travel to the ip address to get the domain name.
 	 * This is per request option, passing true to the getProvider without turning this ON, it wont work and vice versa.
@@ -2162,6 +2181,7 @@ export declare class EmailValidator {
 	private validateCache;
 	private ipCache;
 	private inflight;
+	private _logFn;
 	private validationConfig;
 	constructor(config?: {
 		options?: ValidationConfig;
@@ -2236,6 +2256,12 @@ export declare class EmailValidator {
 		deep?: boolean;
 		logo?: boolean;
 	}): Promise<EmailResponse>;
+	/**
+	 * Emit a debug line if `validationConfig.debug` is enabled.
+	 * Format: `[zynor HH:MM:SS.mmm] <scope>: <msg>`. No-op (and zero string
+	 * formatting cost) when logging is off.
+	 */
+	private _log;
 	/**
 	 * Build a Valid response with `websiteTitle` and optional `loginUrl`
 	 * populated from the provider maps in ./provider-webmail.