lacspace-leads 0.3.0 → 1.2.1

package/dist/lib.cjs

@@ -30,10 +30,13 @@ __export(lib_exports, {
   cleanWebsite: () => cleanWebsite,
   columnsOf: () => columnsOf,
   composeQuery: () => composeQuery,
+  computeStats: () => computeStats,
   convertFile: () => convertFile,
   dedupeLeads: () => dedupeLeads,
   defaultFilename: () => defaultFilename,
   detectFormat: () => detectFormat,
+  emailDomain: () => emailDomain,
+  emailFormatValid: () => emailFormatValid,
   enrichContacts: () => enrichContacts,
   expandQueries: () => expandQueries,
   extractEmails: () => extractEmails,
@@ -47,14 +50,18 @@ __export(lib_exports, {
   parseReviewCount: () => parseReviewCount,
   readRows: () => readRows,
   resolvePreset: () => resolvePreset,
+  rowsToLeads: () => rowsToLeads,
   scrapeLeads: () => scrapeLeads,
   searchLeads: () => scrapeLeads,
   searchLeadsBatch: () => searchLeadsBatch,
+  searchLeadsDetailed: () => searchLeadsDetailed,
   searchLeadsMulti: () => searchLeadsMulti,
   serialize: () => serialize,
   serializeRows: () => serializeRows,
   sortLeads: () => sortLeads,
-  toRows: () => toRows
+  toRows: () => toRows,
+  verifyEmail: () => verifyEmail,
+  verifyEmails: () => verifyEmails
 });
 module.exports = __toCommonJS(lib_exports);
 
@@ -80,6 +87,7 @@ var ALL_FIELDS = [
   "youtube",
   "tiktok",
   "telegram",
+  "emailStatus",
   "plusCode",
   "latitude",
   "longitude",
@@ -95,7 +103,8 @@ var ENRICHED_FIELDS = [
   "twitter",
   "youtube",
   "tiktok",
-  "telegram"
+  "telegram",
+  "emailStatus"
 ];
 var FIELD_PRESETS = {
   /** Just enough to place a business: name, phone, website. */
@@ -283,6 +292,7 @@ function filterLeads(leads, filters = {}) {
     if (filters.hasPhone && !l.phone) return false;
     if (filters.hasWebsite && !l.website) return false;
     if (filters.hasEmail && !l.email) return false;
+    if (filters.hasValidEmail && l.emailStatus !== "valid") return false;
     return true;
   });
 }
@@ -290,7 +300,8 @@ function dedupeKey(lead, by) {
   if (by === "none") return void 0;
   if (by === "website") return normalizeHost(lead.website);
   if (by === "phone") return lead.phone?.replace(/[^0-9]/g, "") || void 0;
-  return lead.name?.trim().toLowerCase() || void 0;
+  if (by === "name") return lead.name?.trim().toLowerCase() || void 0;
+  return normalizeHost(lead.website) ?? (lead.phone?.replace(/[^0-9]/g, "") || void 0) ?? (lead.name?.trim().toLowerCase() || void 0);
 }
 function normalizeHost(url) {
   if (!url) return void 0;
@@ -447,6 +458,158 @@ function sortLeads(leads, by, dir) {
   }).map((x) => x.lead);
 }
 
+// src/verify.ts
+var import_promises = require("dns/promises");
+var EMAIL_SHAPE = /^[^\s@]+@([^\s@.]+\.)+[^\s@.]{2,}$/;
+function emailFormatValid(email) {
+  return !!email && EMAIL_SHAPE.test(email.trim());
+}
+function emailDomain(email) {
+  if (!email) return void 0;
+  const at = email.lastIndexOf("@");
+  return at >= 0 ? email.slice(at + 1).trim().toLowerCase() || void 0 : void 0;
+}
+async function domainHasMail(domain, cache, timeoutMs) {
+  const cached = cache.get(domain);
+  if (cached !== void 0) return cached;
+  const timer = new Promise((res) => setTimeout(() => res(false), timeoutMs));
+  const lookup = (0, import_promises.resolveMx)(domain).then((records) => Array.isArray(records) && records.length > 0).catch(() => false);
+  const ok = await Promise.race([lookup, timer]);
+  cache.set(domain, ok);
+  return ok;
+}
+async function verifyEmail(email, opts = {}) {
+  if (!email) return "unknown";
+  if (!emailFormatValid(email)) return "invalid-format";
+  const domain = emailDomain(email);
+  if (!domain) return "invalid-format";
+  const has = await domainHasMail(domain, opts.cache ?? /* @__PURE__ */ new Map(), opts.timeoutMs ?? 5e3);
+  return has ? "valid" : "no-mx";
+}
+async function verifyEmails(leads, opts = {}) {
+  const cache = /* @__PURE__ */ new Map();
+  const targets = leads.filter((l) => l.email);
+  const n = Math.max(1, Math.min(opts.concurrency ?? 5, targets.length || 1));
+  let next = 0;
+  let done = 0;
+  const verifyOpts = { cache };
+  if (opts.timeoutMs !== void 0) verifyOpts.timeoutMs = opts.timeoutMs;
+  const workers = Array.from({ length: n }, async () => {
+    for (; ; ) {
+      const i = next++;
+      if (i >= targets.length) return;
+      const lead = targets[i];
+      lead.emailStatus = await verifyEmail(lead.email, verifyOpts);
+      opts.onProgress?.(`verifying email ${++done}/${targets.length}: ${lead.email}\u2026`);
+    }
+  });
+  await Promise.all(workers);
+  return leads;
+}
+
+// src/export.ts
+var import_csv = require("@lacspace/csv");
+var import_xlsx = require("@lacspace/xlsx");
+var HEADERS = {
+  name: "Name",
+  category: "Category",
+  rating: "Rating",
+  reviews: "Reviews",
+  priceLevel: "Price",
+  address: "Address",
+  phone: "Phone",
+  website: "Website",
+  email: "Email",
+  facebook: "Facebook",
+  instagram: "Instagram",
+  whatsapp: "WhatsApp",
+  linkedin: "LinkedIn",
+  twitter: "Twitter/X",
+  youtube: "YouTube",
+  tiktok: "TikTok",
+  telegram: "Telegram",
+  emailStatus: "Email Status",
+  plusCode: "Plus Code",
+  latitude: "Latitude",
+  longitude: "Longitude",
+  hours: "Hours",
+  mapsUrl: "Maps URL"
+};
+function toRows(leads, fields = ALL_FIELDS) {
+  return leads.map((lead) => {
+    const row = {};
+    for (const f of fields) {
+      const v = lead[f];
+      row[HEADERS[f]] = v === void 0 || v === null ? "" : v;
+    }
+    return row;
+  });
+}
+function serialize(leads, format, fields = ALL_FIELDS, opts = {}) {
+  if (format === "json" || format === "ndjson") {
+    const picked = leads.map((lead) => {
+      const o = {};
+      for (const f of fields) if (lead[f] !== void 0) o[f] = lead[f];
+      return o;
+    });
+    const data = format === "ndjson" ? picked.map((o) => JSON.stringify(o)).join("\n") + (picked.length ? "\n" : "") : JSON.stringify(picked, null, 2);
+    return { data, binary: false };
+  }
+  const rows = toRows(leads, fields);
+  if (format === "csv") {
+    const csvRows = rows;
+    return { data: (0, import_csv.stringify)(csvRows, { escapeFormulas: true }), binary: false };
+  }
+  const columns = fields.map((f) => {
+    const header = HEADERS[f];
+    const widest = rows.reduce((m, r) => Math.max(m, String(r[header] ?? "").length), header.length);
+    return { header, width: Math.min(60, Math.max(8, widest + 2)) };
+  });
+  return {
+    data: (0, import_xlsx.jsonToXlsx)(rows, { sheetName: opts.sheetName ?? "Leads", columns }),
+    binary: true
+  };
+}
+function computeStats(leads) {
+  const socialKeys = ["facebook", "instagram", "whatsapp", "linkedin", "twitter", "youtube", "tiktok", "telegram"];
+  const ratings = leads.map((l) => l.rating).filter((r) => typeof r === "number");
+  const stats = {
+    total: leads.length,
+    withPhone: leads.filter((l) => l.phone).length,
+    withWebsite: leads.filter((l) => l.website).length,
+    withEmail: leads.filter((l) => l.email).length,
+    withValidEmail: leads.filter((l) => l.emailStatus === "valid").length,
+    withSocial: leads.filter((l) => socialKeys.some((k) => l[k])).length
+  };
+  if (ratings.length) stats.avgRating = Math.round(ratings.reduce((a, b) => a + b, 0) / ratings.length * 10) / 10;
+  return stats;
+}
+var FIELD_BY_KEY = (() => {
+  const m = /* @__PURE__ */ new Map();
+  for (const f of ALL_FIELDS) {
+    m.set(f.toLowerCase(), f);
+    m.set(HEADERS[f].toLowerCase(), f);
+  }
+  return m;
+})();
+var NUMERIC_FIELDS = /* @__PURE__ */ new Set(["rating", "reviews", "latitude", "longitude"]);
+function rowsToLeads(rows) {
+  return rows.map((row) => {
+    const lead = {};
+    for (const [key, raw] of Object.entries(row)) {
+      const field = FIELD_BY_KEY.get(key.trim().toLowerCase());
+      if (!field || raw === null || raw === void 0 || raw === "") continue;
+      if (NUMERIC_FIELDS.has(field)) {
+        const n = typeof raw === "number" ? raw : parseFloat(String(raw));
+        if (Number.isFinite(n)) lead[field] = n;
+      } else {
+        lead[field] = String(raw);
+      }
+    }
+    return lead;
+  });
+}
+
 // src/scrape.ts
 async function pool(items, n, fn, signal) {
   let next = 0;
@@ -496,17 +659,19 @@ function parseLatLng(url) {
   if (at) return { latitude: parseFloat(at[1]), longitude: parseFloat(at[2]) };
   return {};
 }
-async function launchBrowser(headless) {
+async function launchBrowser(headless, proxy) {
   let lastErr;
+  const base = { headless };
+  if (proxy) base.proxy = { server: proxy };
   for (const channel of ["chrome", "msedge"]) {
     try {
-      return await import_playwright_core.chromium.launch({ headless, channel });
+      return await import_playwright_core.chromium.launch({ ...base, channel });
     } catch (e) {
       lastErr = e;
     }
   }
   try {
-    return await import_playwright_core.chromium.launch({ headless });
+    return await import_playwright_core.chromium.launch(base);
   } catch (e) {
     lastErr = e;
   }
@@ -629,17 +794,21 @@ async function scrapeLeads(opts) {
   const fields = new Set(normalizeFields(opts.fields ?? DEFAULT_FIELDS));
   const delayMs = Math.max(0, Math.trunc(opts.delayMs ?? 700));
   const headless = opts.headless ?? false;
+  const retries = Math.max(0, Math.trunc(opts.retries ?? 1));
   const onProgress = opts.onProgress;
+  const onLead = opts.onLead;
   const signal = opts.signal;
   const startedAt = Date.now();
   const overBudget = () => opts.maxMs !== void 0 && Date.now() - startedAt > opts.maxMs;
-  const wantEnrich = Boolean(opts.enrich) || ENRICHED_FIELDS.some((f) => fields.has(f)) || Boolean(opts.filters?.hasEmail);
+  const pauseMs = () => opts.jitter ? Math.round(delayMs * (0.6 + Math.random() * 0.8)) : delayMs;
+  const wantVerify = Boolean(opts.verifyEmails) || Boolean(opts.filters?.hasValidEmail) || fields.has("emailStatus");
+  const wantEnrich = Boolean(opts.enrich) || ENRICHED_FIELDS.some((f) => fields.has(f)) || Boolean(opts.filters?.hasEmail) || wantVerify;
   const collect = new Set(fields);
   if (wantEnrich) collect.add("website");
   const detailOnly = ["name", "mapsUrl"];
   const wantDetails = (opts.details ?? true) && ([...collect].some((f) => !detailOnly.includes(f)) || wantEnrich);
   onProgress?.(`searching Google Maps for "${query}"\u2026`);
-  const browser = await launchBrowser(headless);
+  const browser = await launchBrowser(headless, opts.proxy);
   try {
     const locale = opts.locale ?? "en-US";
     const context = await browser.newContext({
@@ -677,25 +846,47 @@ async function scrapeLeads(opts) {
         }
         return lead;
       });
+      for (const lead of leads) {
+        try {
+          onLead?.(lead);
+        } catch {
+        }
+      }
     } else {
       for (let i = 0; i < cards.length; i++) {
         if (signal?.aborted || overBudget()) break;
         const card = cards[i];
         onProgress?.(`reading ${i + 1}/${cards.length}: ${card.name ?? "listing"}\u2026`);
-        try {
-          await page.goto(card.href, { waitUntil: "domcontentloaded", timeout: 3e4 });
-          await page.locator("h1.DUwDvf").first().waitFor({ timeout: 8e3 }).catch(() => {
-          });
-          leads.push(await extractDetail(page, collect, card.name));
-        } catch {
+        let lead;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+          try {
+            await page.goto(card.href, { waitUntil: "domcontentloaded", timeout: 3e4 });
+            await page.locator("h1.DUwDvf").first().waitFor({ timeout: 8e3 }).catch(() => {
+            });
+            lead = await extractDetail(page, collect, card.name);
+            break;
+          } catch {
+            if (attempt < retries && !signal?.aborted) {
+              onProgress?.(`  retrying ${i + 1}/${cards.length} (attempt ${attempt + 2})\u2026`);
+              if (delayMs) await page.waitForTimeout(pauseMs());
+            }
+          }
+        }
+        if (!lead) {
           if (card.name && (collect.has("name") || collect.has("mapsUrl"))) {
-            const partial = {};
-            if (collect.has("name")) partial.name = card.name;
-            if (collect.has("mapsUrl")) partial.mapsUrl = card.href;
-            leads.push(partial);
+            lead = {};
+            if (collect.has("name")) lead.name = card.name;
+            if (collect.has("mapsUrl")) lead.mapsUrl = card.href;
+          }
+        }
+        if (lead) {
+          leads.push(lead);
+          try {
+            onLead?.(lead);
+          } catch {
           }
         }
-        if (delayMs) await page.waitForTimeout(delayMs);
+        if (delayMs) await page.waitForTimeout(pauseMs());
       }
     }
     onProgress?.(`collected ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
@@ -728,6 +919,14 @@ async function scrapeLeads(opts) {
         signal
       );
     }
+    if (wantVerify && !signal?.aborted) {
+      onProgress?.("verifying email domains\u2026");
+      const vOpts = {
+        concurrency: Math.max(1, Math.trunc(opts.concurrency ?? 5))
+      };
+      if (onProgress) vOpts.onProgress = (m) => onProgress(m);
+      await verifyEmails(leads, vOpts);
+    }
     if (opts.country && fields.has("phone")) {
       for (const lead of leads) {
         if (lead.phone) lead.phone = normalizePhone(lead.phone, opts.country);
@@ -735,6 +934,7 @@ async function scrapeLeads(opts) {
     }
     if (opts.filters) leads = filterLeads(leads, opts.filters);
     if (opts.sort) leads = sortLeads(leads, opts.sort, opts.sortDir);
+    if (wantVerify && !fields.has("emailStatus")) for (const l of leads) delete l.emailStatus;
     onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
     return leads;
   } finally {
@@ -742,6 +942,11 @@ async function scrapeLeads(opts) {
     });
   }
 }
+async function searchLeadsDetailed(opts) {
+  const started = Date.now();
+  const leads = await scrapeLeads(opts);
+  return { leads, stats: computeStats(leads), elapsedMs: Date.now() - started };
+}
 
 // src/batch.ts
 async function searchLeadsBatch(queries, opts = {}) {
@@ -806,71 +1011,8 @@ async function searchLeadsMulti(opts) {
   return searchLeadsBatch(queries, opts);
 }
 
-// src/export.ts
-var import_csv = require("@lacspace/csv");
-var import_xlsx = require("@lacspace/xlsx");
-var HEADERS = {
-  name: "Name",
-  category: "Category",
-  rating: "Rating",
-  reviews: "Reviews",
-  priceLevel: "Price",
-  address: "Address",
-  phone: "Phone",
-  website: "Website",
-  email: "Email",
-  facebook: "Facebook",
-  instagram: "Instagram",
-  whatsapp: "WhatsApp",
-  linkedin: "LinkedIn",
-  twitter: "Twitter/X",
-  youtube: "YouTube",
-  tiktok: "TikTok",
-  telegram: "Telegram",
-  plusCode: "Plus Code",
-  latitude: "Latitude",
-  longitude: "Longitude",
-  hours: "Hours",
-  mapsUrl: "Maps URL"
-};
-function toRows(leads, fields = ALL_FIELDS) {
-  return leads.map((lead) => {
-    const row = {};
-    for (const f of fields) {
-      const v = lead[f];
-      row[HEADERS[f]] = v === void 0 || v === null ? "" : v;
-    }
-    return row;
-  });
-}
-function serialize(leads, format, fields = ALL_FIELDS, opts = {}) {
-  if (format === "json" || format === "ndjson") {
-    const picked = leads.map((lead) => {
-      const o = {};
-      for (const f of fields) if (lead[f] !== void 0) o[f] = lead[f];
-      return o;
-    });
-    const data = format === "ndjson" ? picked.map((o) => JSON.stringify(o)).join("\n") + (picked.length ? "\n" : "") : JSON.stringify(picked, null, 2);
-    return { data, binary: false };
-  }
-  const rows = toRows(leads, fields);
-  if (format === "csv") {
-    const csvRows = rows;
-    return { data: (0, import_csv.stringify)(csvRows, { escapeFormulas: true }), binary: false };
-  }
-  const columns = fields.map((f) => {
-    const header = HEADERS[f];
-    const widest = rows.reduce((m, r) => Math.max(m, String(r[header] ?? "").length), header.length);
-    return { header, width: Math.min(60, Math.max(8, widest + 2)) };
-  });
-  return {
-    data: (0, import_xlsx.jsonToXlsx)(rows, { sheetName: opts.sheetName ?? "Leads", columns }),
-    binary: true
-  };
-}
-
 // src/convert.ts
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
 var import_node_path = require("path");
 var import_csv2 = require("@lacspace/csv");
 var import_xlsx2 = require("@lacspace/xlsx");
@@ -884,10 +1026,10 @@ function detectFormat(file) {
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
   if (fmt === "xlsx") {
-    const bytes = await (0, import_promises.readFile)(file);
+    const bytes = await (0, import_promises2.readFile)(file);
     return await (0, import_xlsx2.xlsxToJson)(bytes);
   }
-  const text = await (0, import_promises.readFile)(file, "utf8");
+  const text = await (0, import_promises2.readFile)(file, "utf8");
   if (fmt === "csv") {
     return (0, import_csv2.parse)(text, { header: true });
   }
@@ -939,7 +1081,7 @@ async function convertFile(input, opts = {}) {
   const format = opts.format ?? (opts.out ? detectFormat(opts.out) : "json");
   const out = (0, import_node_path.resolve)(opts.out ?? input.replace(/\.[^.]+$/, "") + "." + format);
   const { data, binary } = serializeRows(rows, format, { sheetName: opts.sheetName ?? "Sheet1" });
-  await (0, import_promises.writeFile)(out, binary ? Buffer.from(data) : data);
+  await (0, import_promises2.writeFile)(out, binary ? Buffer.from(data) : data);
   return { out, format, count: rows.length };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -954,10 +1096,13 @@ async function convertFile(input, opts = {}) {
   cleanWebsite,
   columnsOf,
   composeQuery,
+  computeStats,
   convertFile,
   dedupeLeads,
   defaultFilename,
   detectFormat,
+  emailDomain,
+  emailFormatValid,
   enrichContacts,
   expandQueries,
   extractEmails,
@@ -971,12 +1116,16 @@ async function convertFile(input, opts = {}) {
   parseReviewCount,
   readRows,
   resolvePreset,
+  rowsToLeads,
   scrapeLeads,
   searchLeads,
   searchLeadsBatch,
+  searchLeadsDetailed,
   searchLeadsMulti,
   serialize,
   serializeRows,
   sortLeads,
-  toRows
+  toRows,
+  verifyEmail,
+  verifyEmails
 });

package/dist/lib.d.cts

@@ -1,5 +1,7 @@
 /** The fields a {@link Lead} can carry — request any subset via `fields`. */
-type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+/** Deliverability verdict for a discovered email (see `verifyEmails`). */
+type EmailStatus = "valid" | "no-mx" | "invalid-format" | "unknown";
 /** Every field, in a sensible column order for exports. */
 declare const ALL_FIELDS: LeadField[];
 /** Fields that require visiting the business website (via `enrich`). */
@@ -43,6 +45,8 @@ interface Lead {
     tiktok?: string;
     /** Telegram link, from the website (needs enrichment). */
     telegram?: string;
+    /** Email deliverability verdict (set by `verifyEmails`). */
+    emailStatus?: EmailStatus;
     /** Google Plus Code, when shown. */
     plusCode?: string;
     /** Latitude, parsed from the listing's Maps URL. */
@@ -66,6 +70,8 @@ interface LeadFilters {
     hasWebsite?: boolean;
     /** Keep only leads that have an email (implies enrichment). */
     hasEmail?: boolean;
+    /** Keep only leads whose email passed MX verification (implies `verifyEmails`). */
+    hasValidEmail?: boolean;
 }
 /** Output formats the tool can write. */
 type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
@@ -103,8 +109,12 @@ interface SearchOptions {
     enrich?: boolean;
     /** Drop leads that don't pass these filters. */
     filters?: LeadFilters;
-    /** Drop duplicate leads by this key. Default "website" when present else "name". */
-    dedupe?: "website" | "phone" | "name" | "none";
+    /**
+     * Drop duplicate leads by this key. `"smart"` uses the strongest identity
+     * available per lead (website → phone → name) and is best for accumulating
+     * across runs. Default "website".
+     */
+    dedupe?: "website" | "phone" | "name" | "smart" | "none";
     /** Sort the results by this key before returning. */
     sort?: SortKey$1;
     /** Sort direction. Defaults to "desc" for numbers, "asc" for name. */
@@ -122,17 +132,43 @@ interface SearchOptions {
     cleanUrls?: boolean;
     /** How many websites to enrich in parallel. Default 3. */
     concurrency?: number;
+    /**
+     * Verify each discovered email by checking its domain has MX records (DNS,
+     * no message is sent). Populates `emailStatus`. Implies `enrich`. Default off.
+     */
+    verifyEmails?: boolean;
     /** Browser/UI locale, e.g. "en-US", "ne-NP". Default "en-US". */
     locale?: string;
     /** Google region bias (ccTLD-style), e.g. "np", "us". Sets Maps `gl`. */
     region?: string;
+    /** Route the browser through this proxy, e.g. "http://user:pass@host:port". */
+    proxy?: string;
+    /** Retry a listing that fails to open, up to this many times. Default 1. */
+    retries?: number;
+    /** Randomise the delay between listings by ±40% to look more human. */
+    jitter?: boolean;
     /** Stop collecting after this many milliseconds (best-effort). */
     maxMs?: number;
     /** Called with a short progress message as the search runs. */
     onProgress?: (message: string) => void;
+    /**
+     * Called with each lead as it's collected (before enrichment), for live UIs
+     * or crash-safe incremental writing. Never throws into the run.
+     */
+    onLead?: (lead: Lead) => void;
     /** An AbortSignal to cancel a running search. */
     signal?: AbortSignal;
 }
+/** Aggregate counts over a lead list — see `computeStats`. */
+interface LeadStats {
+    total: number;
+    withPhone: number;
+    withWebsite: number;
+    withEmail: number;
+    withValidEmail: number;
+    withSocial: number;
+    avgRating?: number;
+}
 
 /** Error thrown by the scraper. Carries a machine `code` and optional cause. */
 declare class LeadsError extends Error {
@@ -162,6 +198,18 @@ declare function parseLatLng(url: string): {
  * @throws {LeadsError} when no browser can be launched, or the search is aborted.
  */
 declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
+/** A search result with aggregate stats and timing. */
+interface DetailedResult {
+    leads: Lead[];
+    stats: LeadStats;
+    /** Wall-clock time of the search, in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * Like {@link scrapeLeads}, but also returns aggregate {@link LeadStats} and the
+ * elapsed time — handy for dashboards, reports and CI summaries.
+ */
+declare function searchLeadsDetailed(opts: SearchOptions): Promise<DetailedResult>;
 
 /** One sub-search in a batch. */
 interface BatchQuery {
@@ -198,6 +246,37 @@ declare function serialize(leads: Lead[], format: OutputFormat, fields?: LeadFie
     data: string | Uint8Array;
     binary: boolean;
 };
+/** Aggregate counts over a lead list — for summaries and reports. Pure. */
+declare function computeStats(leads: Lead[]): LeadStats;
+/**
+ * Map arbitrary rows (as read back from a JSON/CSV/Excel export, keyed by field
+ * name or header label) into {@link Lead}s. Unknown columns are ignored, blanks
+ * dropped, and numeric fields coerced. Powers `--append` / resume. Pure.
+ */
+declare function rowsToLeads(rows: Record<string, unknown>[]): Lead[];
+
+/** True when `email` is a plausibly-valid address shape. Pure. */
+declare function emailFormatValid(email: string | undefined): boolean;
+/** The domain part of an email, lower-cased, or undefined. Pure. */
+declare function emailDomain(email: string | undefined): string | undefined;
+/**
+ * Classify a single email: `invalid-format` → `no-mx` → `valid`. `unknown` is
+ * reserved for a missing address. Never throws.
+ */
+declare function verifyEmail(email: string | undefined, opts?: {
+    cache?: Map<string, boolean>;
+    timeoutMs?: number;
+}): Promise<EmailStatus>;
+/**
+ * Verify the `email` on each lead in place, setting `emailStatus`. Domains are
+ * looked up once (shared cache) and checked a few in parallel. Leads without an
+ * email are left untouched. Node-only; never throws.
+ */
+declare function verifyEmails(leads: Lead[], opts?: {
+    concurrency?: number;
+    timeoutMs?: number;
+    onProgress?: (m: string) => void;
+}): Promise<Lead[]>;
 
 /**
  * Compose the human search query from options: an explicit `query` wins,
@@ -346,4 +425,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, ENRICHED_FIELDS, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, convertFile, dedupeLeads, defaultFilename, detectFormat, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails };