lacspace-leads 1.3.0 → 1.5.0

package/README.md

@@ -93,6 +93,8 @@ npx lacspace-leads [type] [options]
 | `--has-website` | Only leads with a website |
 | `--has-email` | Only leads with an email (implies `--emails`) |
 | `--has-valid-email` | Only leads whose email passed **MX verification** (implies `--verify-emails`) |
+| `--has-contact` | Only leads reachable by **phone, email or website** |
+| `--name-exclude <list>` | Drop leads whose name contains any of these terms (comma-separated) |
 | `--dedupe <key>` | `website` · `phone` · `name` · `smart` · `none` (default `website`; `--append` uses `smart` = website→phone→name) |
 
 Run with no arguments for an interactive walkthrough.
@@ -154,29 +156,117 @@ npx lacspace-leads cafes --city Kathmandu --area "Thamel,Baneshwor,Patan" \
 
 `--verify-emails` does a DNS **MX lookup** on each email's domain (no message is sent) and adds an `emailStatus` column of `valid` · `no-mx` · `invalid-format`. `--append` reads the existing file back, merges, and de-duplicates with the **`smart`** key (website → phone → name) so even website-less businesses don't pile up on re-runs.
 
-## Convert anything (JSON ↔ CSV ↔ Excel)
+## Saved campaigns (`--config`)
 
-A general converter is built in — it works on any tabular file, not just leads:
+Describe a repeatable set of searches plus shared options in one JSON file, and run them all with a single command — ideal for the same city sweeps every week (pair it with cron or CI):
+
+```jsonc
+// campaign.json
+{
+  "searches": [
+    { "type": "cafes", "city": "Kathmandu", "area": "Thamel,Baneshwor,Patan" },
+    { "type": "gyms",  "city": "Pokhara" }
+  ],
+  "country": "NP",
+  "verifyEmails": true,
+  "sort": "reviews",
+  "filters": { "hasContact": true, "excludeNames": ["closed"] },
+  "out": "master.xlsx",
+  "format": "xlsx",
+  "append": true
+}
+```
 
 ```bash
-npx lacspace-leads convert leads.json -f xlsx        # JSON → Excel
-npx lacspace-leads convert data.csv  -o data.json    # CSV → JSON
-npx lacspace-leads convert sheet.xlsx -f csv         # Excel → CSV
+npx lacspace-leads --config campaign.json
 ```
 
-Programmatically: `convertFile(input, { format, out, sheetName })`, or `readRows(file)` + `serializeRows(rows, format)`.
+Every search is run, merged and de-duplicated; the shared options, filters and output settings apply across the whole campaign. Programmatically: `runConfig(config)`.
+
+## Convert your leads to any format
 
-### Examples
+Collected leads as JSON and now need them in Excel? A general converter is built in — it reads and writes **JSON · NDJSON · CSV · Excel** in any direction, and works on *any* tabular file, not just leads:
+
+```bash
+npx lacspace-leads convert leads.json  -f xlsx          # JSON  → Excel
+npx lacspace-leads convert leads.json  -o leads.csv     # JSON  → CSV   (format from the -o extension)
+npx lacspace-leads convert data.csv    -o data.json     # CSV   → JSON
+npx lacspace-leads convert sheet.xlsx  -f csv           # Excel → CSV
+npx lacspace-leads convert leads.ndjson -f xlsx         # NDJSON → Excel
+npx lacspace-leads convert big.csv     -f ndjson        # CSV → NDJSON (stream-friendly)
+```
+
+The output format comes from `-f` (or is inferred from the `-o` filename's extension); if you give neither, it defaults to JSON. Use `--sheet "My Leads"` to name the Excel tab.
+
+**What converts to what** — every combination works, both ways:
+
+| From \ To | JSON | NDJSON | CSV | Excel |
+| --- | :---: | :---: | :---: | :---: |
+| **JSON** | – | ✓ | ✓ | ✓ |
+| **NDJSON** | ✓ | – | ✓ | ✓ |
+| **CSV** | ✓ | ✓ | – | ✓ |
+| **Excel** | ✓ | ✓ | ✓ | – |
+
+**Sample.** `leads.json` in:
+
+```json
+[
+  { "name": "Himalayan Java", "phone": "+9779801234567", "rating": 4.6, "website": "https://himalayanjava.com" },
+  { "name": "Cafe Soma", "phone": "+9779807654321", "rating": 4.4 }
+]
+```
+
+`npx lacspace-leads convert leads.json -o leads.csv` → `leads.csv` out (missing cells become blank; `+` is escaped so spreadsheets don't treat it as a formula):
+
+```csv
+name,phone,rating,website
+Himalayan Java,'+9779801234567,4.6,https://himalayanjava.com
+Cafe Soma,'+9779807654321,4.4,
+```
+
+**In code** — convert a file, or turn any `Lead[]` into a downloadable buffer:
+
+```ts
+import { convertFile, readRows, serializeRows, serialize } from "lacspace-leads";
+
+// 1. Convert a file on disk (returns { out, format, count }).
+await convertFile("leads.json", { format: "xlsx", sheetName: "Prospects" });
+
+// 2. Read rows from any format, transform, write to another.
+const rows = await readRows("leads.csv");                 // → array of objects
+const filtered = rows.filter((r) => Number(r.Rating) >= 4.5);
+const { data, binary } = serializeRows(filtered, "xlsx"); // → bytes for xlsx
+// (write `data` yourself, or in a server route send it as a download)
+
+// 3. Serialize Lead[] straight from a search — pick the columns and order.
+const { data: csv } = serialize(leads, "csv", ["name", "phone", "email"]);
+```
+
+## Recipes
 
 ```bash
 # Excel of restaurants in a specific area
 npx lacspace-leads restaurants --city Kathmandu --area Baneshwor -f xlsx
 
-# Just the essentials for outreach, as CSV
-npx lacspace-leads --type "dental clinic" --city Pokhara --fields name,phone,website -f csv -n 40
+# Outreach list: name/phone/email/website/address, MX-verified, deliverable only
+npx lacspace-leads "dental clinic" --city Pokhara --preset outreach \
+  --verify-emails --has-valid-email --country NP -f csv
+
+# Cover a whole city, sorted best-reviewed first, into one Excel file
+npx lacspace-leads cafes --city Kathmandu --area "Thamel,Baneshwor,Patan" \
+  --sort reviews --desc -f xlsx
 
-# Fast name + URL sweep, no per-listing opening
+# Everything within 1.5 km of a point, nearest first
+npx lacspace-leads salons --near "27.7172,85.3240" --radius 1.5km -f csv
+
+# Build a master list you top up daily (accumulate + dedupe)
+npx lacspace-leads gyms --city Lalitpur -o gyms-master.xlsx --append
+
+# Fast name + Maps-URL sweep, no per-listing opening
 npx lacspace-leads gyms --city Lalitpur --no-details -n 100
+
+# Pipe straight into jq (JSON on stdout, logs on stderr)
+npx lacspace-leads bakeries --city Pokhara -f json -o - -y | jq '.[].phone'
 ```
 
 ## Library

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { writeFileSync, existsSync } from "fs";
+import { writeFileSync, existsSync, readFileSync } from "fs";
 import { resolve as resolve2 } from "path";
 import { createInterface } from "readline/promises";
 import { stdin, stdout, stderr, argv, exit } from "process";
@@ -240,6 +240,11 @@ function filterLeads(leads, filters = {}) {
     if (filters.hasWebsite && !l.website) return false;
     if (filters.hasEmail && !l.email) return false;
     if (filters.hasValidEmail && l.emailStatus !== "valid") return false;
+    if (filters.hasContact && !(l.phone || l.email || l.website)) return false;
+    if (filters.excludeNames && filters.excludeNames.length) {
+      const name = (l.name ?? "").toLowerCase();
+      if (filters.excludeNames.some((t) => t && name.includes(t.toLowerCase()))) return false;
+    }
     return true;
   });
 }
@@ -1013,6 +1018,28 @@ async function searchLeadsBatch(queries, opts = {}) {
   return merged;
 }
 
+// src/config.ts
+async function runConfig(config, hooks = {}) {
+  const { searches, filters, total, out, format, append, sheet, ...shared } = config;
+  void out;
+  void format;
+  void append;
+  void sheet;
+  const opts = { ...shared };
+  if (filters) opts.filters = filters;
+  if (total !== void 0) opts.total = total;
+  if (hooks.onProgress) opts.onProgress = hooks.onProgress;
+  if (hooks.signal) opts.signal = hooks.signal;
+  return searchLeadsBatch(Array.isArray(searches) ? searches : [], opts);
+}
+function assertConfig(value) {
+  if (!value || typeof value !== "object") throw new Error("Config must be a JSON object.");
+  const searches = value.searches;
+  if (!Array.isArray(searches) || searches.length === 0) {
+    throw new Error('Config needs a non-empty "searches" array, e.g. [{ "type": "cafes", "city": "Kathmandu" }].');
+  }
+}
+
 // src/convert.ts
 import { readFile, writeFile } from "fs/promises";
 import { extname, resolve } from "path";
@@ -1021,9 +1048,10 @@ import { jsonToXlsx as jsonToXlsx2, xlsxToJson } from "@lacspace/xlsx";
 function detectFormat(file) {
   const ext = extname(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -1035,6 +1063,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return csvParse(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -1057,6 +1094,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1117,6 +1157,7 @@ function parseArgs(list) {
     hasWebsite: false,
     hasEmail: false,
     hasValidEmail: false,
+    hasContact: false,
     cleanUrls: true,
     jitter: false,
     yes: false,
@@ -1163,7 +1204,10 @@ function parseArgs(list) {
       a.hasValidEmail = true;
       a.verifyEmails = true;
       a.emails = true;
-    } else if (arg === "--dedupe") a.dedupe = next();
+    } else if (arg === "--has-contact") a.hasContact = true;
+    else if (arg === "--name-exclude" || arg === "--exclude-names") a.nameExclude = next();
+    else if (arg === "--config") a.config = next();
+    else if (arg === "--dedupe") a.dedupe = next();
     else if (arg === "--sort") a.sort = next();
     else if (arg === "--desc") a.desc = true;
     else if (arg === "--asc") a.desc = false;
@@ -1186,7 +1230,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 free loca
 
 ${c("bold", "Usage")}
   npx lacspace-leads [type] [options]
-  npx lacspace-leads convert <file> [-f json|csv|xlsx] [-o out]
+  npx lacspace-leads convert <file> [-f json|ndjson|csv|xlsx] [-o out]
 
 ${c("bold", "Search options")}
   -t, --type <text>     Business type/keyword. Comma-separate for several,
@@ -1223,11 +1267,17 @@ ${c("bold", "Filters & order")}
       --has-website     Keep only leads with a website
       --has-email       Keep only leads with an email (implies --emails)
       --has-valid-email Keep only leads with an MX-verified email (implies --verify-emails)
+      --has-contact     Keep only leads reachable by phone, email OR website
+      --name-exclude <list>  Drop leads whose name contains any of these terms
       --dedupe <key>    website | phone | name | smart | none   (default website;
                         --append uses smart: website\u2192phone\u2192name)
       --sort <key>      rating | reviews | name | priceLevel | distance
       --desc / --asc    Sort direction (distance defaults nearest-first)
 
+${c("bold", "Campaigns")}
+      --config <file>   Run a saved JSON campaign: { "searches":[\u2026], shared options,
+                        "out", "format", "append" }. Repeatable, schedulable.
+
 ${c("bold", "Output")}
   -f, --format <fmt>    json | ndjson | csv | xlsx      (default json)
   -o, --out <file>      Output file, or "-" for stdout (default: slug + date)
@@ -1277,6 +1327,13 @@ async function runConvert(rest) {
     exit(1);
     return;
   }
+  if ((rest.includes("-f") || rest.includes("--format")) && !OUTPUT_FORMATS.includes(a.format)) {
+    log(c("red", `
+\u2717 Unknown format "${a.format}". Use: ${OUTPUT_FORMATS.join(", ")}.
+`));
+    exit(1);
+    return;
+  }
   log(`
 ${c("bold", c("magenta", "\u25C6 lacspace-leads convert"))}
 `);
@@ -1295,6 +1352,70 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads convert"))}
     exit(1);
   }
 }
+async function runConfigFile(args) {
+  log(`
+${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 running a saved campaign")}
+`);
+  let config;
+  try {
+    config = JSON.parse(readFileSync(resolve2(args.config), "utf8"));
+    assertConfig(config);
+  } catch (err) {
+    log(c("red", `
+\u2717 Could not load --config: ${err.message}
+`));
+    exit(1);
+    return;
+  }
+  const format = config.format ?? args.format;
+  if (!OUTPUT_FORMATS.includes(format)) {
+    log(c("red", `
+\u2717 Unknown format "${format}".`));
+    exit(1);
+    return;
+  }
+  log(`  ${c("dim", "searches")} ${config.searches.length}   ${c("dim", "format")} ${format}${config.append ? c("dim", "  (append)") : ""}
+`);
+  const controller = new AbortController();
+  const onSig = () => controller.abort();
+  process.once("SIGINT", onSig);
+  let leads;
+  try {
+    leads = await runConfig(config, { signal: controller.signal, onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`) });
+  } catch (err) {
+    log(c("red", `
+\u2717 ${err.message}`));
+    exit(1);
+    return;
+  } finally {
+    process.removeListener("SIGINT", onSig);
+  }
+  if (!leads.length) {
+    log(c("yellow", "\n  No leads collected.\n"));
+    return;
+  }
+  const fields = config.fields ? normalizeFields(config.fields) : ALL_FIELDS.filter((f) => leads.some((l) => l[f] !== void 0));
+  let out = resolve2(args.out ?? config.out ?? defaultFilename("leads-campaign", format));
+  if ((args.append || config.append) && existsSync(out)) {
+    try {
+      const existing = rowsToLeads(await readRows(out));
+      const before = existing.length;
+      leads = dedupeLeads([...existing, ...leads], config.dedupe ?? "smart");
+      log(`  ${c("cyan", "\u25F7")} ${c("dim", `merged with ${before} existing \u2192 ${leads.length} total`)}`);
+    } catch (err) {
+      log(c("yellow", `  ! couldn't append (${err.message}); overwriting`));
+    }
+  }
+  const serOpts = {};
+  if (args.sheet ?? config.sheet) serOpts.sheetName = args.sheet ?? config.sheet;
+  const { data, binary } = serialize(leads, format, fields, serOpts);
+  writeFileSync(out, binary ? Buffer.from(data) : data);
+  const s = computeStats(leads);
+  log(`
+  ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}`);
+  log(`    ${c("dim", `${s.withPhone} with a phone \xB7 ${s.withWebsite} with a website \xB7 ${s.withEmail} with an email`)}
+`);
+}
 async function main() {
   const raw = argv.slice(2);
   if (raw[0] === "convert") {
@@ -1306,6 +1427,10 @@ async function main() {
     stdout.write(HELP + "\n");
     return;
   }
+  if (args.config) {
+    await runConfigFile(args);
+    return;
+  }
   log(`
 ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Maps \u2192 JSON/CSV/Excel, free")}
 `);
@@ -1380,6 +1505,8 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   if (args.hasWebsite) filters.hasWebsite = true;
   if (args.hasEmail) filters.hasEmail = true;
   if (args.hasValidEmail) filters.hasValidEmail = true;
+  if (args.hasContact) filters.hasContact = true;
+  if (args.nameExclude) filters.excludeNames = args.nameExclude.split(",").map((s2) => s2.trim()).filter(Boolean);
   const hasFilters = Object.keys(filters).length > 0;
   const queries = expandQueries({
     type: args.type ?? "",

package/dist/lib.cjs

@@ -26,6 +26,7 @@ __export(lib_exports, {
   ENRICHED_FIELDS: () => ENRICHED_FIELDS,
   FIELD_PRESETS: () => FIELD_PRESETS,
   LeadsError: () => LeadsError,
+  assertConfig: () => assertConfig,
   callingCode: () => callingCode,
   cleanWebsite: () => cleanWebsite,
   columnsOf: () => columnsOf,
@@ -54,6 +55,7 @@ __export(lib_exports, {
   readRows: () => readRows,
   resolvePreset: () => resolvePreset,
   rowsToLeads: () => rowsToLeads,
+  runConfig: () => runConfig,
   scrapeLeads: () => scrapeLeads,
   searchLeads: () => scrapeLeads,
   searchLeadsBatch: () => searchLeadsBatch,
@@ -303,6 +305,11 @@ function filterLeads(leads, filters = {}) {
     if (filters.hasWebsite && !l.website) return false;
     if (filters.hasEmail && !l.email) return false;
     if (filters.hasValidEmail && l.emailStatus !== "valid") return false;
+    if (filters.hasContact && !(l.phone || l.email || l.website)) return false;
+    if (filters.excludeNames && filters.excludeNames.length) {
+      const name = (l.name ?? "").toLowerCase();
+      if (filters.excludeNames.some((t) => t && name.includes(t.toLowerCase()))) return false;
+    }
     return true;
   });
 }
@@ -1090,6 +1097,28 @@ async function searchLeadsMulti(opts) {
   return searchLeadsBatch(queries, opts);
 }
 
+// src/config.ts
+async function runConfig(config, hooks = {}) {
+  const { searches, filters, total, out, format, append, sheet, ...shared } = config;
+  void out;
+  void format;
+  void append;
+  void sheet;
+  const opts = { ...shared };
+  if (filters) opts.filters = filters;
+  if (total !== void 0) opts.total = total;
+  if (hooks.onProgress) opts.onProgress = hooks.onProgress;
+  if (hooks.signal) opts.signal = hooks.signal;
+  return searchLeadsBatch(Array.isArray(searches) ? searches : [], opts);
+}
+function assertConfig(value) {
+  if (!value || typeof value !== "object") throw new Error("Config must be a JSON object.");
+  const searches = value.searches;
+  if (!Array.isArray(searches) || searches.length === 0) {
+    throw new Error('Config needs a non-empty "searches" array, e.g. [{ "type": "cafes", "city": "Kathmandu" }].');
+  }
+}
+
 // src/convert.ts
 var import_promises2 = require("fs/promises");
 var import_node_path = require("path");
@@ -1098,9 +1127,10 @@ var import_xlsx2 = require("@lacspace/xlsx");
 function detectFormat(file) {
   const ext = (0, import_node_path.extname)(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -1112,6 +1142,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return (0, import_csv2.parse)(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -1134,6 +1173,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1171,6 +1213,7 @@ async function convertFile(input, opts = {}) {
   ENRICHED_FIELDS,
   FIELD_PRESETS,
   LeadsError,
+  assertConfig,
   callingCode,
   cleanWebsite,
   columnsOf,
@@ -1199,6 +1242,7 @@ async function convertFile(input, opts = {}) {
   readRows,
   resolvePreset,
   rowsToLeads,
+  runConfig,
   scrapeLeads,
   searchLeads,
   searchLeadsBatch,

package/dist/lib.d.cts

@@ -74,6 +74,10 @@ interface LeadFilters {
     hasEmail?: boolean;
     /** Keep only leads whose email passed MX verification (implies `verifyEmails`). */
     hasValidEmail?: boolean;
+    /** Keep only leads reachable by at least one of phone, email or website. */
+    hasContact?: boolean;
+    /** Drop leads whose name contains any of these (case-insensitive) terms. */
+    excludeNames?: string[];
 }
 /** Output formats the tool can write. */
 type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
@@ -249,6 +253,53 @@ declare function searchLeadsMulti(opts: SearchOptions & {
     total?: number;
 }): Promise<Lead[]>;
 
+/**
+ * Config-file campaigns — describe a repeatable set of searches plus shared
+ * options in one JSON file and run them together. Ideal for agencies running
+ * the same city sweeps on a schedule.
+ *
+ * ```json
+ * {
+ *   "searches": [
+ *     { "type": "cafes", "city": "Kathmandu", "area": "Thamel,Baneshwor" },
+ *     { "type": "gyms",  "city": "Pokhara" }
+ *   ],
+ *   "country": "NP", "verifyEmails": true, "sort": "reviews",
+ *   "filters": { "hasContact": true },
+ *   "out": "master.xlsx", "format": "xlsx", "append": true
+ * }
+ * ```
+ */
+
+/** A leads campaign config (the JSON file passed to `--config`). */
+interface LeadsConfig extends Partial<Omit<SearchOptions, "type" | "city" | "area" | "query" | "onProgress" | "signal" | "filters">> {
+    /** The searches to run and merge. */
+    searches: BatchQuery[];
+    /** Post-collection filters applied across the merged set. */
+    filters?: LeadFilters;
+    /** Cap the merged result. */
+    total?: number;
+    /** Output file (used by the CLI). */
+    out?: string;
+    /** Output format (used by the CLI). */
+    format?: OutputFormat;
+    /** Append/merge into an existing `out` file (used by the CLI). */
+    append?: boolean;
+    /** Excel sheet name (used by the CLI). */
+    sheet?: string;
+}
+/**
+ * Run a {@link LeadsConfig}: expand its `searches`, apply the shared options and
+ * filters, and return the merged, de-duplicated leads. Output settings (`out`,
+ * `format`, `append`, `sheet`) are ignored here — the CLI uses them to write.
+ */
+declare function runConfig(config: LeadsConfig, hooks?: {
+    onProgress?: (m: string) => void;
+    signal?: AbortSignal;
+}): Promise<Lead[]>;
+/** Validate a parsed object is a usable config. Throws a helpful error if not. */
+declare function assertConfig(value: unknown): asserts value is LeadsConfig;
+
 /** Project leads onto exactly the requested fields, in order, as header-keyed rows. */
 declare function toRows(leads: Lead[], fields?: LeadField[]): Record<string, string | number>[];
 /** Serialize leads to a UTF-8 string or bytes in the chosen format. */
@@ -450,7 +501,7 @@ declare function zoomForRadius(radiusM: number, lat?: number): number;
 type DataRow = Record<string, unknown>;
 /** Infer the format from a filename extension. Throws on an unknown extension. */
 declare function detectFormat(file: string): OutputFormat;
-/** Read a JSON / CSV / Excel file into an array of rows. */
+/** Read a JSON / NDJSON / CSV / Excel file into an array of rows. */
 declare function readRows(file: string, format?: OutputFormat): Promise<DataRow[]>;
 /** The union of keys across all rows, in first-seen order — the column set. */
 declare function columnsOf(rows: DataRow[]): string[];
@@ -472,4 +523,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, 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, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, type Lead, type LeadField, type LeadFilters, type LeadStats, type LeadsConfig, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, assertConfig, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, runConfig, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };

package/dist/lib.d.ts

@@ -74,6 +74,10 @@ interface LeadFilters {
     hasEmail?: boolean;
     /** Keep only leads whose email passed MX verification (implies `verifyEmails`). */
     hasValidEmail?: boolean;
+    /** Keep only leads reachable by at least one of phone, email or website. */
+    hasContact?: boolean;
+    /** Drop leads whose name contains any of these (case-insensitive) terms. */
+    excludeNames?: string[];
 }
 /** Output formats the tool can write. */
 type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
@@ -249,6 +253,53 @@ declare function searchLeadsMulti(opts: SearchOptions & {
     total?: number;
 }): Promise<Lead[]>;
 
+/**
+ * Config-file campaigns — describe a repeatable set of searches plus shared
+ * options in one JSON file and run them together. Ideal for agencies running
+ * the same city sweeps on a schedule.
+ *
+ * ```json
+ * {
+ *   "searches": [
+ *     { "type": "cafes", "city": "Kathmandu", "area": "Thamel,Baneshwor" },
+ *     { "type": "gyms",  "city": "Pokhara" }
+ *   ],
+ *   "country": "NP", "verifyEmails": true, "sort": "reviews",
+ *   "filters": { "hasContact": true },
+ *   "out": "master.xlsx", "format": "xlsx", "append": true
+ * }
+ * ```
+ */
+
+/** A leads campaign config (the JSON file passed to `--config`). */
+interface LeadsConfig extends Partial<Omit<SearchOptions, "type" | "city" | "area" | "query" | "onProgress" | "signal" | "filters">> {
+    /** The searches to run and merge. */
+    searches: BatchQuery[];
+    /** Post-collection filters applied across the merged set. */
+    filters?: LeadFilters;
+    /** Cap the merged result. */
+    total?: number;
+    /** Output file (used by the CLI). */
+    out?: string;
+    /** Output format (used by the CLI). */
+    format?: OutputFormat;
+    /** Append/merge into an existing `out` file (used by the CLI). */
+    append?: boolean;
+    /** Excel sheet name (used by the CLI). */
+    sheet?: string;
+}
+/**
+ * Run a {@link LeadsConfig}: expand its `searches`, apply the shared options and
+ * filters, and return the merged, de-duplicated leads. Output settings (`out`,
+ * `format`, `append`, `sheet`) are ignored here — the CLI uses them to write.
+ */
+declare function runConfig(config: LeadsConfig, hooks?: {
+    onProgress?: (m: string) => void;
+    signal?: AbortSignal;
+}): Promise<Lead[]>;
+/** Validate a parsed object is a usable config. Throws a helpful error if not. */
+declare function assertConfig(value: unknown): asserts value is LeadsConfig;
+
 /** Project leads onto exactly the requested fields, in order, as header-keyed rows. */
 declare function toRows(leads: Lead[], fields?: LeadField[]): Record<string, string | number>[];
 /** Serialize leads to a UTF-8 string or bytes in the chosen format. */
@@ -450,7 +501,7 @@ declare function zoomForRadius(radiusM: number, lat?: number): number;
 type DataRow = Record<string, unknown>;
 /** Infer the format from a filename extension. Throws on an unknown extension. */
 declare function detectFormat(file: string): OutputFormat;
-/** Read a JSON / CSV / Excel file into an array of rows. */
+/** Read a JSON / NDJSON / CSV / Excel file into an array of rows. */
 declare function readRows(file: string, format?: OutputFormat): Promise<DataRow[]>;
 /** The union of keys across all rows, in first-seen order — the column set. */
 declare function columnsOf(rows: DataRow[]): string[];
@@ -472,4 +523,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, 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, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type LatLng, type Lead, type LeadField, type LeadFilters, type LeadStats, type LeadsConfig, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, assertConfig, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, haversineMeters, mapsSearchUrl, normalizeFields, normalizePhone, parseDistance, parseLatLng, parseLatLngPair, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, runConfig, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails, zoomForRadius };

package/dist/lib.js

@@ -232,6 +232,11 @@ function filterLeads(leads, filters = {}) {
     if (filters.hasWebsite && !l.website) return false;
     if (filters.hasEmail && !l.email) return false;
     if (filters.hasValidEmail && l.emailStatus !== "valid") return false;
+    if (filters.hasContact && !(l.phone || l.email || l.website)) return false;
+    if (filters.excludeNames && filters.excludeNames.length) {
+      const name = (l.name ?? "").toLowerCase();
+      if (filters.excludeNames.some((t) => t && name.includes(t.toLowerCase()))) return false;
+    }
     return true;
   });
 }
@@ -1019,6 +1024,28 @@ async function searchLeadsMulti(opts) {
   return searchLeadsBatch(queries, opts);
 }
 
+// src/config.ts
+async function runConfig(config, hooks = {}) {
+  const { searches, filters, total, out, format, append, sheet, ...shared } = config;
+  void out;
+  void format;
+  void append;
+  void sheet;
+  const opts = { ...shared };
+  if (filters) opts.filters = filters;
+  if (total !== void 0) opts.total = total;
+  if (hooks.onProgress) opts.onProgress = hooks.onProgress;
+  if (hooks.signal) opts.signal = hooks.signal;
+  return searchLeadsBatch(Array.isArray(searches) ? searches : [], opts);
+}
+function assertConfig(value) {
+  if (!value || typeof value !== "object") throw new Error("Config must be a JSON object.");
+  const searches = value.searches;
+  if (!Array.isArray(searches) || searches.length === 0) {
+    throw new Error('Config needs a non-empty "searches" array, e.g. [{ "type": "cafes", "city": "Kathmandu" }].');
+  }
+}
+
 // src/convert.ts
 import { readFile, writeFile } from "fs/promises";
 import { extname, resolve } from "path";
@@ -1027,9 +1054,10 @@ import { jsonToXlsx as jsonToXlsx2, xlsxToJson } from "@lacspace/xlsx";
 function detectFormat(file) {
   const ext = extname(file).toLowerCase().replace(/^\./, "");
   if (ext === "json") return "json";
+  if (ext === "ndjson" || ext === "jsonl") return "ndjson";
   if (ext === "csv" || ext === "tsv") return "csv";
   if (ext === "xlsx" || ext === "xls") return "xlsx";
-  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|csv|xlsx).`);
+  throw new Error(`Cannot infer a format from ".${ext}" \u2014 pass an explicit --format (json|ndjson|csv|xlsx).`);
 }
 async function readRows(file, format) {
   const fmt = format ?? detectFormat(file);
@@ -1041,6 +1069,15 @@ async function readRows(file, format) {
   if (fmt === "csv") {
     return csvParse(text, { header: true });
   }
+  if (fmt === "ndjson") {
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).map((l, i) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        throw new Error(`Invalid NDJSON on line ${i + 1}.`);
+      }
+    });
+  }
   const parsed = JSON.parse(text);
   if (Array.isArray(parsed)) return parsed;
   if (parsed && typeof parsed === "object") return [parsed];
@@ -1063,6 +1100,9 @@ function serializeRows(rows, format, opts = {}) {
   if (format === "json") {
     return { data: JSON.stringify(rows, null, 2), binary: false };
   }
+  if (format === "ndjson") {
+    return { data: rows.map((r) => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""), binary: false };
+  }
   const cols = columnsOf(rows);
   const flat = rows.map((row) => {
     const out = {};
@@ -1099,6 +1139,7 @@ export {
   ENRICHED_FIELDS,
   FIELD_PRESETS,
   LeadsError,
+  assertConfig,
   callingCode,
   cleanWebsite,
   columnsOf,
@@ -1127,6 +1168,7 @@ export {
   readRows,
   resolvePreset,
   rowsToLeads,
+  runConfig,
   scrapeLeads,
   scrapeLeads as searchLeads,
   searchLeadsBatch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lacspace-leads",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Free, open-source local-business lead finder — name a city/area/business type, or search by coordinates + radius, 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": {