lacspace-leads 0.3.0 → 1.2.1

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { writeFileSync } from "fs";
+import { writeFileSync, existsSync } from "fs";
 import { resolve as resolve2 } from "path";
 import { createInterface } from "readline/promises";
 import { stdin, stdout, stderr, argv, exit } from "process";
@@ -28,6 +28,7 @@ var ALL_FIELDS = [
   "youtube",
   "tiktok",
   "telegram",
+  "emailStatus",
   "plusCode",
   "latitude",
   "longitude",
@@ -43,7 +44,8 @@ var ENRICHED_FIELDS = [
   "twitter",
   "youtube",
   "tiktok",
-  "telegram"
+  "telegram",
+  "emailStatus"
 ];
 var FIELD_PRESETS = {
   /** Just enough to place a business: name, phone, website. */
@@ -231,6 +233,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;
   });
 }
@@ -238,7 +241,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;
@@ -395,6 +399,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;
@@ -444,17 +600,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;
   }
@@ -577,17 +735,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({
@@ -625,25 +787,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 (delayMs) await page.waitForTimeout(delayMs);
+        if (lead) {
+          leads.push(lead);
+          try {
+            onLead?.(lead);
+          } catch {
+          }
+        }
+        if (delayMs) await page.waitForTimeout(pauseMs());
       }
     }
     onProgress?.(`collected ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
@@ -676,6 +860,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);
@@ -683,6 +875,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 {
@@ -745,69 +938,6 @@ async function searchLeadsBatch(queries, opts = {}) {
   return merged;
 }
 
-// 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";
@@ -900,16 +1030,20 @@ var log = (s = "") => void stderr.write(s + "\n");
 function parseArgs(list) {
   const a = {
     format: "json",
+    append: false,
     limit: 60,
     headless: false,
     details: true,
     delay: 700,
     emails: false,
     socials: false,
+    verifyEmails: false,
     hasPhone: false,
     hasWebsite: false,
     hasEmail: false,
+    hasValidEmail: false,
     cleanUrls: true,
+    jitter: false,
     yes: false,
     help: false
   };
@@ -924,6 +1058,7 @@ function parseArgs(list) {
     else if (arg === "--preset") a.preset = next();
     else if (arg === "-f" || arg === "--format") a.format = next();
     else if (arg === "-o" || arg === "--out") a.out = next();
+    else if (arg === "--append") a.append = true;
     else if (arg === "-n" || arg === "--limit") a.limit = parseInt(next(), 10) || a.limit;
     else if (arg === "--total") a.total = parseInt(next(), 10) || a.total;
     else if (arg === "--headless") a.headless = true;
@@ -934,13 +1069,23 @@ function parseArgs(list) {
     else if (arg === "--enrich") {
       a.emails = true;
       a.socials = true;
-    } else if (arg === "--min-rating") a.minRating = parseFloat(next());
+    } else if (arg === "--verify-emails" || arg === "--verify") {
+      a.verifyEmails = true;
+      a.emails = true;
+    } else if (arg === "--proxy") a.proxy = next();
+    else if (arg === "--retries") a.retries = parseInt(next(), 10);
+    else if (arg === "--jitter") a.jitter = true;
+    else if (arg === "--min-rating") a.minRating = parseFloat(next());
     else if (arg === "--min-reviews") a.minReviews = parseInt(next(), 10);
     else if (arg === "--has-phone") a.hasPhone = true;
     else if (arg === "--has-website") a.hasWebsite = true;
     else if (arg === "--has-email") {
       a.hasEmail = true;
       a.emails = true;
+    } else if (arg === "--has-valid-email") {
+      a.hasValidEmail = true;
+      a.verifyEmails = true;
+      a.emails = true;
     } else if (arg === "--dedupe") a.dedupe = next();
     else if (arg === "--sort") a.sort = next();
     else if (arg === "--desc") a.desc = true;
@@ -984,6 +1129,7 @@ ${c("bold", "Enrichment (visits each website)")}
       --socials         Also find Facebook/Instagram/WhatsApp/LinkedIn/X/
                         YouTube/TikTok/Telegram
       --enrich          Both of the above
+      --verify-emails   Check each email's domain has MX records (implies --emails)
       --concurrency <n> Websites to enrich in parallel   (default 3)
 
 ${c("bold", "Clean-up")}
@@ -997,18 +1143,24 @@ ${c("bold", "Filters & order")}
       --has-phone       Keep only leads with a phone
       --has-website     Keep only leads with a website
       --has-email       Keep only leads with an email (implies --emails)
-      --dedupe <key>    website | phone | name | none   (default website)
+      --has-valid-email Keep only leads with an MX-verified email (implies --verify-emails)
+      --dedupe <key>    website | phone | name | smart | none   (default website;
+                        --append uses smart: website\u2192phone\u2192name)
       --sort <key>      rating | reviews | name | priceLevel
       --desc / --asc    Sort direction
 
 ${c("bold", "Output")}
   -f, --format <fmt>    json | ndjson | csv | xlsx      (default json)
   -o, --out <file>      Output file, or "-" for stdout (default: slug + date)
+      --append          Merge into an existing output file (accumulate + dedupe)
       --sheet <name>    Excel sheet name         (default "Leads")
 
 ${c("bold", "Runtime")}
       --delay <ms>      Pause between listings    (default 700)
+      --jitter          Randomise the delay \xB140% (more human)
+      --retries <n>     Retry a listing that fails to open   (default 1)
       --max-time <s>    Stop collecting after n seconds
+      --proxy <url>     Route the browser via a proxy (http://user:pass@host:port)
       --lang <locale>   Browser locale, e.g. en-US, ne-NP   (default en-US)
       --region <cc>     Region bias for results, e.g. np, us
       --headless        Run the browser without a window
@@ -1021,6 +1173,8 @@ ${c("bold", "Examples")}
   npx lacspace-leads gyms --city Lalitpur --min-rating 4 --sort reviews --desc
   npx lacspace-leads cafes --city Kathmandu --area "Thamel,Baneshwor,Patan" --country NP
   npx lacspace-leads salons --city Pokhara --preset outreach --country NP -f csv -o -
+  npx lacspace-leads dentists --city Pokhara --verify-emails --has-valid-email -f csv
+  npx lacspace-leads cafes --city Kathmandu -o master.csv --append   # accumulate daily
   npx lacspace-leads convert leads.json -f xlsx
 
 ${c("dim", "Please scrape responsibly: keep volumes small, respect Google's Terms of")}
@@ -1111,6 +1265,10 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   const wanted = new Set(base);
   if (args.emails) wanted.add("email");
   if (args.socials) for (const f of SOCIAL_FIELDS) wanted.add(f);
+  if (args.verifyEmails) {
+    wanted.add("email");
+    wanted.add("emailStatus");
+  }
   const fields = ALL_FIELDS.filter((f) => wanted.has(f));
   const toStdout = args.out === "-";
   const out = toStdout ? "-" : resolve2(args.out ?? defaultFilename(query, args.format));
@@ -1120,6 +1278,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   if (args.hasPhone) filters.hasPhone = true;
   if (args.hasWebsite) filters.hasWebsite = true;
   if (args.hasEmail) filters.hasEmail = true;
+  if (args.hasValidEmail) filters.hasValidEmail = true;
   const hasFilters = Object.keys(filters).length > 0;
   const queries = expandQueries({
     type: args.type ?? "",
@@ -1140,10 +1299,12 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   ${c("dim", "search")}  ${c("bold", query)}`);
   log(`  ${c("dim", "fields")}  ${fields.join(", ")}`);
   if (args.emails || args.socials) log(`  ${c("dim", "enrich")}  ${[args.emails && "emails", args.socials && "socials"].filter(Boolean).join(" + ")} ${c("dim", `(${args.concurrency ?? 3}\xD7 parallel, visits each website)`)}`);
+  if (args.verifyEmails) log(`  ${c("dim", "verify")}  email domains (MX lookup)`);
   if (hasFilters) log(`  ${c("dim", "filters")} ${Object.entries(filters).map(([k, v]) => `${k}=${v}`).join(", ")}`);
   if (args.sort) log(`  ${c("dim", "sort")}    ${args.sort} ${args.desc === false ? "asc" : "desc"}`);
   if (args.country) log(`  ${c("dim", "phones")}  E.164 for ${args.country}`);
-  log(`  ${c("dim", "limit")}   ${args.limit}${isBatch ? "/search" : ""}${args.total ? ` (cap ${args.total})` : ""}   ${c("dim", "format")} ${args.format}   ${c("dim", "\u2192")} ${toStdout ? "stdout" : out}`);
+  if (args.proxy) log(`  ${c("dim", "proxy")}   ${args.proxy.replace(/\/\/[^@]+@/, "//***@")}`);
+  log(`  ${c("dim", "limit")}   ${args.limit}${isBatch ? "/search" : ""}${args.total ? ` (cap ${args.total})` : ""}   ${c("dim", "format")} ${args.format}   ${c("dim", "\u2192")} ${toStdout ? "stdout" : out}${args.append ? c("dim", " (append)") : ""}`);
   if (!args.yes) {
     const ok = await prompt(`
 ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c("dim", "[y/N]")} `);
@@ -1170,6 +1331,8 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     delayMs: args.delay,
     cleanUrls: args.cleanUrls,
     enrich: args.emails || args.socials,
+    verifyEmails: args.verifyEmails,
+    jitter: args.jitter,
     signal: controller.signal,
     onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`)
   };
@@ -1181,6 +1344,8 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   if (args.locale) opts.locale = args.locale;
   if (args.region) opts.region = args.region;
   if (args.concurrency !== void 0) opts.concurrency = args.concurrency;
+  if (args.proxy) opts.proxy = args.proxy;
+  if (args.retries !== void 0) opts.retries = args.retries;
   if (args.maxTime !== void 0) opts.maxMs = args.maxTime * 1e3;
   let leads;
   try {
@@ -1203,6 +1368,19 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     log(c("yellow", "\n  No leads collected. Try a broader area, looser filters, or a smaller --limit.\n"));
     return;
   }
+  let fresh = leads.length;
+  if (args.append && !toStdout && existsSync(out)) {
+    try {
+      const existing = rowsToLeads(await readRows(out));
+      const before = existing.length;
+      const merged = dedupeLeads([...existing, ...leads], args.dedupe ?? "smart");
+      fresh = merged.length - before;
+      log(`  ${c("cyan", "\u25F7")} ${c("dim", `merged with ${before} existing \u2192 ${merged.length} total (${fresh} new)`)}`);
+      leads = merged;
+    } catch (err) {
+      log(c("yellow", `  ! couldn't read "${out}" to append (${err.message}); overwriting instead`));
+    }
+  }
   const serOpts = {};
   if (args.sheet) serOpts.sheetName = args.sheet;
   const { data, binary } = serialize(leads, args.format, fields, serOpts);
@@ -1215,16 +1393,15 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     return;
   }
   writeFileSync(out, binary ? Buffer.from(data) : data);
-  const withPhone = leads.filter((l) => l.phone).length;
-  const withSite = leads.filter((l) => l.website).length;
-  const withEmail = leads.filter((l) => l.email).length;
-  const withSocial = leads.filter((l) => l.facebook || l.instagram || l.linkedin || l.twitter).length;
+  const s = computeStats(leads);
   log(`
-  ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}`);
-  const stats = [`${withPhone} with a phone`, `${withSite} with a website`];
-  if (args.emails) stats.push(`${withEmail} with an email`);
-  if (args.socials) stats.push(`${withSocial} with a social link`);
-  log(`    ${c("dim", stats.join(" \xB7 "))}
+  ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}${args.append && fresh !== leads.length ? c("dim", ` (${fresh} new)`) : ""}`);
+  const parts = [`${s.withPhone} with a phone`, `${s.withWebsite} with a website`];
+  if (args.emails) parts.push(`${s.withEmail} with an email`);
+  if (args.verifyEmails) parts.push(`${s.withValidEmail} MX-valid`);
+  if (args.socials) parts.push(`${s.withSocial} with a social link`);
+  if (s.avgRating !== void 0) parts.push(`avg \u2605 ${s.avgRating}`);
+  log(`    ${c("dim", parts.join(" \xB7 "))}
 `);
 }
 main().catch((err) => {