lacspace-leads 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# lacspace-leads
+
+**Free, open-source local-business lead finder.** Name a city, area and business type — it drives a real browser over Google Maps and collects each listing's **name, category, rating, reviews, address, phone, website** and more, then exports to **JSON, CSV or Excel**. No API keys, no paid services.
+
+```bash
+npx lacspace-leads restaurants --city Kathmandu --area Baneshwor -f xlsx
+```
+
+That opens a browser, searches Maps for *"restaurants in Baneshwor, Kathmandu"*, reads the listings, and writes `restaurants-in-baneshwor-kathmandu-YYYY-MM-DD.xlsx`.
+
+## Why it's different
+
+- **Free & keyless** — uses a real browser (via [Playwright](https://playwright.dev)), not a paid Places API.
+- **Any format** — JSON, CSV or Excel out of the box (Excel/CSV via `@lacspace/xlsx` + `@lacspace/csv`).
+- **Pick your fields** — only collect what you need.
+- **Permission-first** — it tells you what it's about to do and asks before opening a browser.
+- **Library too** — `import { searchLeads } from "lacspace-leads"`.
+
+## Install
+
+Needs **Node 20+** and a Chromium-based browser. It uses your installed **Google Chrome** or **Microsoft Edge** automatically; if you have neither, run:
+
+```bash
+npx playwright install chromium
+```
+
+## CLI
+
+```bash
+npx lacspace-leads [type] [options]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `-t, --type <text>` | Business type / keyword, e.g. `"dental clinic"` |
+| `--city <text>` | City, e.g. `Kathmandu` |
+| `--area <text>` | Area / neighbourhood, e.g. `Baneshwor` |
+| `-q, --query <text>` | Raw query, used verbatim (overrides city/area/type) |
+| `--fields <list>` | Comma list: `name,category,rating,reviews,address,phone,website,plusCode,hours,mapsUrl` |
+| `-f, --format <fmt>` | `json` · `csv` · `xlsx` (default `json`) |
+| `-o, --out <file>` | Output file (default: a slug + date) |
+| `-n, --limit <n>` | Max listings to collect (default `60`) |
+| `--no-details` | Skip opening each listing — names + Maps URLs only, much faster |
+| `--delay <ms>` | Pause between listings (default `700`) |
+| `--headless` | Run the browser without a visible window |
+| `-y, --yes` | Skip prompts and the browser-open confirmation |
+
+Run with no arguments for an interactive walkthrough.
+
+### Examples
+
+```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
+
+# Fast name + URL sweep, no per-listing opening
+npx lacspace-leads gyms --city Lalitpur --no-details -n 100
+```
+
+## Library
+
+```ts
+import { searchLeads, serialize } from "lacspace-leads";
+import { writeFileSync } from "node:fs";
+
+const leads = await searchLeads({
+  city: "Kathmandu",
+  area: "Baneshwor",
+  type: "restaurants",
+  fields: ["name", "phone", "website", "rating"],
+  limit: 40,
+  headless: true,
+  onProgress: (m) => console.log(m),
+});
+
+const { data, binary } = serialize(leads, "xlsx");
+writeFileSync("leads.xlsx", binary ? Buffer.from(data as Uint8Array) : data);
+```
+
+| Export | Purpose |
+| --- | --- |
+| `searchLeads(options)` | Run the search, resolve to `Lead[]`. |
+| `serialize(leads, format, fields?)` | Serialize to `{ data, binary }` for `json` / `csv` / `xlsx`. |
+| `toRows(leads, fields?)` | Header-keyed rows, for your own exporter. |
+| `composeQuery` / `mapsSearchUrl` / `normalizeFields` / `defaultFilename` | Query + helper utilities. |
+
+## Please use it responsibly
+
+Automated scraping of Google Maps is **against Google's Terms of Service**, and heavy use can trigger CAPTCHAs or temporary blocks. This tool is meant for **small, human-scale** collection of **public business information**. You are responsible for how you use it: keep volumes modest, add delays, respect local data-protection law (and don't collect or contact people in ways that break it), and don't resell scraped data as your own. If you need high volume or guaranteed reliability, use the official Google Places API.
+
+## Licence
+
+Free under the **[Lacspace Free Licence](https://developer.lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms, personal and commercial use.
+
+Part of the [Lacspace developer platform](https://developer.lacspace.com).

package/dist/cli.js

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFileSync } from "fs";
+import { resolve } from "path";
+import { createInterface } from "readline/promises";
+import { stdin, stdout, stderr, argv, exit } from "process";
+
+// src/scrape.ts
+import { chromium } from "playwright-core";
+
+// src/types.ts
+var ALL_FIELDS = [
+  "name",
+  "category",
+  "rating",
+  "reviews",
+  "address",
+  "phone",
+  "website",
+  "plusCode",
+  "hours",
+  "mapsUrl"
+];
+
+// src/query.ts
+function composeQuery(opts) {
+  if (opts.query && opts.query.trim()) return opts.query.trim();
+  const type = (opts.type ?? "").trim();
+  const where = [opts.area, opts.city].map((s) => (s ?? "").trim()).filter(Boolean).join(", ");
+  if (!type) throw new Error("A business `type` (or an explicit `query`) is required.");
+  return where ? `${type} in ${where}` : type;
+}
+function mapsSearchUrl(query) {
+  return `https://www.google.com/maps/search/${encodeURIComponent(query)}?hl=en`;
+}
+function normalizeFields(input) {
+  if (!input) return [...ALL_FIELDS];
+  const raw = typeof input === "string" ? input.split(",") : input;
+  const want = new Set(
+    raw.map((f) => String(f).trim().toLowerCase()).filter(Boolean)
+  );
+  const picked = ALL_FIELDS.filter((f) => want.has(f.toLowerCase()));
+  return picked.length > 0 ? picked : [...ALL_FIELDS];
+}
+function defaultFilename(query, format) {
+  const slug = query.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "leads";
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  return `${slug}-${stamp}.${format}`;
+}
+
+// src/scrape.ts
+var LeadsError = class extends Error {
+  code;
+  cause;
+  constructor(message, code, cause) {
+    super(message);
+    this.name = "LeadsError";
+    if (code !== void 0) this.code = code;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+function stripPrefix(value, prefix) {
+  if (!value) return void 0;
+  const v = value.startsWith(prefix) ? value.slice(prefix.length) : value;
+  const trimmed = v.trim();
+  return trimmed || void 0;
+}
+function parseReviewCount(label) {
+  if (!label) return void 0;
+  const digits = label.replace(/[^0-9]/g, "");
+  if (!digits) return void 0;
+  const n = parseInt(digits, 10);
+  return Number.isFinite(n) ? n : void 0;
+}
+function parseRating(text) {
+  if (!text) return void 0;
+  const m = text.replace(",", ".").match(/\d+(\.\d+)?/);
+  if (!m) return void 0;
+  const n = parseFloat(m[0]);
+  return Number.isFinite(n) && n >= 0 && n <= 5 ? n : void 0;
+}
+async function launchBrowser(headless) {
+  let lastErr;
+  for (const channel of ["chrome", "msedge"]) {
+    try {
+      return await chromium.launch({ headless, channel });
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  try {
+    return await chromium.launch({ headless });
+  } catch (e) {
+    lastErr = e;
+  }
+  throw new LeadsError(
+    "Could not launch a browser. Install Google Chrome (or Microsoft Edge), or run `npx playwright install chromium`.",
+    "NO_BROWSER",
+    lastErr
+  );
+}
+async function dismissConsent(page) {
+  try {
+    const btn = page.locator(
+      'button[aria-label*="Accept all"], button[aria-label*="Accept the use"], form[action*="consent"] button, button:has-text("Accept all")'
+    ).first();
+    if (await btn.count()) {
+      await btn.click({ timeout: 3e3 }).catch(() => {
+      });
+      await page.waitForTimeout(500);
+    }
+  } catch {
+  }
+}
+async function loadResults(page, limit, delayMs, onProgress, signal) {
+  const feed = page.locator('div[role="feed"]');
+  await feed.waitFor({ timeout: 15e3 }).catch(() => {
+  });
+  let prev = 0;
+  let stable = 0;
+  for (let i = 0; i < 60; i++) {
+    if (signal?.aborted) return;
+    const count = await page.locator("a.hfpxzc").count();
+    onProgress?.(`loaded ${count} listing${count === 1 ? "" : "s"}\u2026`);
+    if (count >= limit) return;
+    if (await page.locator('span:has-text("reached the end")').count()) return;
+    if (count === prev) {
+      if (++stable >= 3) return;
+    } else {
+      stable = 0;
+    }
+    prev = count;
+    await feed.evaluate((el) => el.scrollBy(0, el.scrollHeight)).catch(() => {
+    });
+    await page.waitForTimeout(Math.max(400, delayMs));
+  }
+}
+async function extractDetail(page, fields, fallbackName) {
+  const lead = {};
+  const text = async (sel) => {
+    const loc = page.locator(sel).first();
+    if (await loc.count()) {
+      const t = (await loc.innerText().catch(() => "")).trim();
+      return t || void 0;
+    }
+    return void 0;
+  };
+  const aria = async (sel) => {
+    const loc = page.locator(sel).first();
+    if (await loc.count()) {
+      return await loc.getAttribute("aria-label").catch(() => null) ?? void 0;
+    }
+    return void 0;
+  };
+  if (fields.has("name")) lead.name = await text("h1.DUwDvf") ?? fallbackName;
+  else if (fallbackName) lead.name = fallbackName;
+  if (fields.has("category")) {
+    lead.category = await text('button[jsaction*="category"]') ?? void 0;
+  }
+  if (fields.has("rating") || fields.has("reviews")) {
+    const box = page.locator("div.F7nice").first();
+    if (await box.count()) {
+      if (fields.has("rating")) {
+        const rt = await box.locator('span[aria-hidden="true"]').first().innerText().catch(() => "");
+        lead.rating = parseRating(rt);
+      }
+      if (fields.has("reviews")) {
+        const rv = await box.locator('span[aria-label*="review"]').first().getAttribute("aria-label").catch(() => null);
+        lead.reviews = parseReviewCount(rv);
+      }
+    }
+  }
+  if (fields.has("address")) {
+    lead.address = stripPrefix(await aria('button[data-item-id="address"]'), "Address:");
+  }
+  if (fields.has("phone")) {
+    lead.phone = stripPrefix(await aria('button[data-item-id^="phone"]'), "Phone:");
+  }
+  if (fields.has("website")) {
+    const site = page.locator('a[data-item-id="authority"]').first();
+    if (await site.count()) {
+      lead.website = await site.getAttribute("href").catch(() => null) ?? void 0;
+    }
+  }
+  if (fields.has("plusCode")) {
+    lead.plusCode = stripPrefix(await aria('button[data-item-id="oloc"]'), "Plus code:");
+  }
+  if (fields.has("hours")) {
+    lead.hours = stripPrefix(await aria('div[jsaction*="openhours"]'), "") ?? await text('div[jsaction*="openhours"]');
+  }
+  if (fields.has("mapsUrl")) lead.mapsUrl = page.url();
+  return lead;
+}
+async function scrapeLeads(opts) {
+  const query = composeQuery(opts);
+  const limit = Math.max(1, Math.trunc(opts.limit ?? 60));
+  const fields = new Set(normalizeFields(opts.fields ?? ALL_FIELDS));
+  const wantDetails = opts.details ?? true;
+  const delayMs = Math.max(0, Math.trunc(opts.delayMs ?? 700));
+  const headless = opts.headless ?? false;
+  const onProgress = opts.onProgress;
+  const signal = opts.signal;
+  onProgress?.(`searching Google Maps for "${query}"\u2026`);
+  const browser = await launchBrowser(headless);
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 900 },
+      locale: "en-US"
+    });
+    const page = await context.newPage();
+    await page.goto(mapsSearchUrl(query), { waitUntil: "domcontentloaded", timeout: 45e3 });
+    await dismissConsent(page);
+    await loadResults(page, limit, delayMs, onProgress, signal);
+    if (signal?.aborted) throw new LeadsError("Search aborted.", "ABORTED");
+    const cards = await page.locator("a.hfpxzc").evaluateAll(
+      (els, lim) => els.slice(0, lim).map((a) => ({
+        href: a.href,
+        name: a.getAttribute("aria-label") ?? void 0
+      })),
+      limit
+    ).catch(() => []);
+    if (cards.length === 0) {
+      onProgress?.("no listings found (Google may have shown a CAPTCHA or an empty result).");
+      return [];
+    }
+    if (!wantDetails) {
+      return cards.map((c2) => {
+        const lead = {};
+        if (fields.has("name")) lead.name = c2.name;
+        if (fields.has("mapsUrl")) lead.mapsUrl = c2.href;
+        return lead;
+      });
+    }
+    const leads = [];
+    for (let i = 0; i < cards.length; i++) {
+      if (signal?.aborted) 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, fields, card.name));
+      } catch {
+        if (card.name && (fields.has("name") || fields.has("mapsUrl"))) {
+          const partial = {};
+          if (fields.has("name")) partial.name = card.name;
+          if (fields.has("mapsUrl")) partial.mapsUrl = card.href;
+          leads.push(partial);
+        }
+      }
+      if (delayMs) await page.waitForTimeout(delayMs);
+    }
+    onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
+    return leads;
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
+
+// 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",
+  address: "Address",
+  phone: "Phone",
+  website: "Website",
+  plusCode: "Plus Code",
+  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) {
+  if (format === "json") {
+    const picked = leads.map((lead) => {
+      const o = {};
+      for (const f of fields) if (lead[f] !== void 0) o[f] = lead[f];
+      return o;
+    });
+    return { data: JSON.stringify(picked, null, 2), binary: false };
+  }
+  const rows = toRows(leads, fields);
+  if (format === "csv") {
+    const csvRows = rows;
+    return { data: csvStringify(csvRows, { escapeFormulas: true }), binary: false };
+  }
+  return { data: jsonToXlsx(rows, { sheetName: "Leads" }), binary: true };
+}
+
+// src/cli.ts
+var C = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  cyan: "\x1B[36m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  magenta: "\x1B[35m"
+};
+var c = (k, s) => `${C[k]}${s}${C.reset}`;
+var log = (s = "") => void stderr.write(s + "\n");
+function parseArgs(list) {
+  const a = { format: "json", limit: 60, headless: false, details: true, delay: 700, yes: false, help: false };
+  for (let i = 0; i < list.length; i++) {
+    const arg = list[i];
+    const next = () => list[++i] ?? "";
+    if (arg === "--city") a.city = next();
+    else if (arg === "--area") a.area = next();
+    else if (arg === "-t" || arg === "--type") a.type = next();
+    else if (arg === "-q" || arg === "--query") a.query = next();
+    else if (arg === "--fields") a.fields = next();
+    else if (arg === "-f" || arg === "--format") a.format = next();
+    else if (arg === "-o" || arg === "--out") a.out = next();
+    else if (arg === "-n" || arg === "--limit") a.limit = parseInt(next(), 10) || a.limit;
+    else if (arg === "--headless") a.headless = true;
+    else if (arg === "--no-details") a.details = false;
+    else if (arg === "--delay") a.delay = parseInt(next(), 10) || a.delay;
+    else if (arg === "-y" || arg === "--yes") a.yes = true;
+    else if (arg === "-h" || arg === "--help") a.help = true;
+    else if (arg.startsWith("--")) {
+    } else if (!a.type && !a.query) a.type = arg;
+  }
+  return a;
+}
+var HELP = `
+${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 free local-business lead finder (Google Maps, no API keys)")}
+
+${c("bold", "Usage")}
+  npx lacspace-leads [type] [options]
+
+${c("bold", "Options")}
+  -t, --type <text>     Business type / keyword, e.g. "restaurants"
+      --city <text>     City, e.g. "Kathmandu"
+      --area <text>     Area / neighbourhood, e.g. "Baneshwor"
+  -q, --query <text>    Use a raw query verbatim (overrides city/area/type)
+      --fields <list>   Comma list: ${ALL_FIELDS.join(",")}
+  -f, --format <fmt>    json | csv | xlsx        (default json)
+  -o, --out <file>      Output file (default: a slug + date)
+  -n, --limit <n>       Max listings to collect   (default 60)
+      --no-details      Skip opening each listing (names + URLs only, fast)
+      --delay <ms>      Pause between listings     (default 700)
+      --headless        Run the browser without a window
+  -y, --yes             Skip prompts + the browser-open confirmation
+  -h, --help            Show this help
+
+${c("bold", "Examples")}
+  npx lacspace-leads restaurants --city Kathmandu --area Baneshwor -f xlsx
+  npx lacspace-leads --type "dental clinic" --city Pokhara --fields name,phone,website -n 40
+
+${c("dim", "Please scrape responsibly: keep volumes small, respect Google's Terms of")}
+${c("dim", "Service and local data-protection law, and only use public business data")}
+${c("dim", "you have a lawful basis to use.")}
+`;
+async function prompt(q, fallback = "") {
+  const rl = createInterface({ input: stdin, output: stderr });
+  try {
+    const ans = (await rl.question(q)).trim();
+    return ans || fallback;
+  } finally {
+    rl.close();
+  }
+}
+async function main() {
+  const args = parseArgs(argv.slice(2));
+  if (args.help) {
+    stdout.write(HELP + "\n");
+    return;
+  }
+  log(`
+${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Maps \u2192 JSON/CSV/Excel, free")}
+`);
+  if (!args.query && !args.type && !args.yes) {
+    args.type = await prompt(`${c("green", "?")} Business type ${c("dim", "(e.g. restaurants)")}: `);
+    args.city = args.city ?? await prompt(`${c("green", "?")} City ${c("dim", "(optional)")}: `);
+    args.area = args.area ?? await prompt(`${c("green", "?")} Area ${c("dim", "(optional)")}: `);
+    const fmt = await prompt(`${c("green", "?")} Format ${c("dim", "(json/csv/xlsx)")} ${c("dim", "[json]")}: `, "json");
+    if (fmt === "csv" || fmt === "xlsx" || fmt === "json") args.format = fmt;
+    const lim = await prompt(`${c("green", "?")} How many ${c("dim", "[60]")}: `, "60");
+    args.limit = parseInt(lim, 10) || args.limit;
+  }
+  let query;
+  try {
+    query = composeQuery(args);
+  } catch (err) {
+    log(c("red", `
+\u2717 ${err.message}`));
+    exit(1);
+    return;
+  }
+  const fields = normalizeFields(args.fields);
+  const out = resolve(args.out ?? defaultFilename(query, args.format));
+  log(`
+  ${c("dim", "search")}  ${c("bold", query)}`);
+  log(`  ${c("dim", "fields")}  ${fields.join(", ")}`);
+  log(`  ${c("dim", "limit")}   ${args.limit}   ${c("dim", "format")} ${args.format}   ${c("dim", "\u2192")} ${out}`);
+  if (!args.yes) {
+    const ok = await prompt(`
+${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c("dim", "[y/N]")} `);
+    if (!/^y(es)?$/i.test(ok)) {
+      log(c("dim", "\n  cancelled.\n"));
+      return;
+    }
+  }
+  log("");
+  const controller = new AbortController();
+  const onSig = () => {
+    controller.abort();
+  };
+  process.once("SIGINT", onSig);
+  const opts = {
+    type: args.type ?? "",
+    query: args.query ?? "",
+    city: args.city ?? "",
+    area: args.area ?? "",
+    limit: args.limit,
+    fields,
+    headless: args.headless,
+    details: args.details,
+    delayMs: args.delay,
+    signal: controller.signal,
+    onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`)
+  };
+  let leads;
+  try {
+    leads = await scrapeLeads(opts);
+  } catch (err) {
+    log(c("red", `
+\u2717 ${err.message}`));
+    exit(1);
+    return;
+  } finally {
+    process.removeListener("SIGINT", onSig);
+  }
+  if (leads.length === 0) {
+    log(c("yellow", "\n  No leads collected. Try a broader area, fewer fields, or a smaller --limit.\n"));
+    return;
+  }
+  const { data, binary } = serialize(leads, args.format, fields);
+  writeFileSync(out, binary ? Buffer.from(data) : data);
+  const withPhone = leads.filter((l) => l.phone).length;
+  const withSite = leads.filter((l) => l.website).length;
+  log(`
+  ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}`);
+  log(`    ${c("dim", `${withPhone} with a phone \xB7 ${withSite} with a website`)}
+`);
+}
+main().catch((err) => {
+  log(c("red", `
+\u2717 ${err instanceof Error ? err.message : String(err)}
+`));
+  exit(1);
+});