lacspace-leads 0.3.0 → 1.2.1

package/dist/lib.d.ts

@@ -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 };

package/dist/lib.js

@@ -20,6 +20,7 @@ var ALL_FIELDS = [
   "youtube",
   "tiktok",
   "telegram",
+  "emailStatus",
   "plusCode",
   "latitude",
   "longitude",
@@ -35,7 +36,8 @@ var ENRICHED_FIELDS = [
   "twitter",
   "youtube",
   "tiktok",
-  "telegram"
+  "telegram",
+  "emailStatus"
 ];
 var FIELD_PRESETS = {
   /** Just enough to place a business: name, phone, website. */
@@ -223,6 +225,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;
   });
 }
@@ -230,7 +233,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;
@@ -387,6 +391,158 @@ function sortLeads(leads, by, dir) {
   }).map((x) => x.lead);
 }
 
+// src/verify.ts
+import { resolveMx } from "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 = 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
+import { stringify as csvStringify } from "@lacspace/csv";
+import { jsonToXlsx } from "@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: csvStringify(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: 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;
@@ -436,17 +592,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 chromium.launch({ headless, channel });
+      return await chromium.launch({ ...base, channel });
     } catch (e) {
       lastErr = e;
     }
   }
   try {
-    return await chromium.launch({ headless });
+    return await chromium.launch(base);
   } catch (e) {
     lastErr = e;
   }
@@ -569,17 +727,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({
@@ -617,25 +779,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"}.`);
@@ -668,6 +852,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);
@@ -675,6 +867,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 {
@@ -682,6 +875,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 = {}) {
@@ -746,69 +944,6 @@ async function searchLeadsMulti(opts) {
   return searchLeadsBatch(queries, opts);
 }
 
-// src/export.ts
-import { stringify as csvStringify } from "@lacspace/csv";
-import { jsonToXlsx } from "@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: csvStringify(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: jsonToXlsx(rows, { sheetName: opts.sheetName ?? "Leads", columns }),
-    binary: true
-  };
-}
-
 // src/convert.ts
 import { readFile, writeFile } from "fs/promises";
 import { extname, resolve } from "path";
@@ -893,10 +1028,13 @@ export {
   cleanWebsite,
   columnsOf,
   composeQuery,
+  computeStats,
   convertFile,
   dedupeLeads,
   defaultFilename,
   detectFormat,
+  emailDomain,
+  emailFormatValid,
   enrichContacts,
   expandQueries,
   extractEmails,
@@ -910,12 +1048,16 @@ export {
   parseReviewCount,
   readRows,
   resolvePreset,
+  rowsToLeads,
   scrapeLeads,
   scrapeLeads as searchLeads,
   searchLeadsBatch,
+  searchLeadsDetailed,
   searchLeadsMulti,
   serialize,
   serializeRows,
   sortLeads,
-  toRows
+  toRows,
+  verifyEmail,
+  verifyEmails
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lacspace-leads",
-  "version": "0.3.0",
-  "description": "Free, open-source local-business lead finder — name a city, area and business type, and it drives a real browser over Google Maps to collect names, phones, websites, ratings, addresses, emails and social links, then exports to JSON, NDJSON, CSV or Excel. Sweep multiple areas at once, normalise phones to E.164, and enrich in parallel. No API keys.",
+  "version": "1.2.1",
+  "description": "Free, open-source local-business lead finder — name a city, area and business type, and it drives a real browser over Google Maps to collect names, phones, websites, ratings, addresses, emails and social links, then exports to JSON, NDJSON, CSV or Excel. Sweep multiple areas at once, verify emails by MX, normalise phones to E.164, accumulate into a master file, and enrich in parallel through an optional proxy. No API keys.",
   "type": "module",
   "bin": {
     "lacspace-leads": "dist/cli.js"
@@ -36,6 +36,8 @@
     "prospecting",
     "b2b",
     "email-finder",
+    "email-verification",
+    "mx-lookup",
     "csv",
     "excel",
     "ndjson",