lacspace-leads 1.4.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,6 +156,33 @@ 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.
 
+## Saved campaigns (`--config`)
+
+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 --config campaign.json
+```
+
+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
 
 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:

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";
@@ -1130,6 +1157,7 @@ function parseArgs(list) {
     hasWebsite: false,
     hasEmail: false,
     hasValidEmail: false,
+    hasContact: false,
     cleanUrls: true,
     jitter: false,
     yes: false,
@@ -1176,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;
@@ -1236,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)
@@ -1315,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") {
@@ -1326,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")}
 `);
@@ -1400,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");
@@ -1184,6 +1213,7 @@ async function convertFile(input, opts = {}) {
   ENRICHED_FIELDS,
   FIELD_PRESETS,
   LeadsError,
+  assertConfig,
   callingCode,
   cleanWebsite,
   columnsOf,
@@ -1212,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. */
@@ -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. */
@@ -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";
@@ -1112,6 +1139,7 @@ export {
   ENRICHED_FIELDS,
   FIELD_PRESETS,
   LeadsError,
+  assertConfig,
   callingCode,
   cleanWebsite,
   columnsOf,
@@ -1140,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.4.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": {