lacspace-leads 1.3.0 → 1.4.0

package/README.md

@@ -154,29 +154,90 @@ 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)
+## Convert your leads to any format
 
-A general converter is built in — it works on any tabular file, not just leads:
+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 data.csv  -o data.json    # CSV → JSON
-npx lacspace-leads convert sheet.xlsx -f csv         # Excel → CSV
+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)
 ```
 
-Programmatically: `convertFile(input, { format, out, sheetName })`, or `readRows(file)` + `serializeRows(rows, format)`.
+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.
 
-### Examples
+**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
 
-# Fast name + URL sweep, no per-listing opening
+# 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
+
+# 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

@@ -1021,9 +1021,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 +1036,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 +1067,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 = {};
@@ -1186,7 +1199,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,
@@ -1277,6 +1290,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"))}
 `);

package/dist/lib.cjs

@@ -1098,9 +1098,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 +1113,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 +1144,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 = {};

package/dist/lib.d.cts

@@ -450,7 +450,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[];

package/dist/lib.d.ts

@@ -450,7 +450,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[];

package/dist/lib.js

@@ -1027,9 +1027,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 +1042,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 +1073,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 = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lacspace-leads",
-  "version": "1.3.0",
+  "version": "1.4.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": {