lacspace-leads 0.1.0

package/dist/lib.js

@@ -0,0 +1,309 @@
+// 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((c) => {
+        const lead = {};
+        if (fields.has("name")) lead.name = c.name;
+        if (fields.has("mapsUrl")) lead.mapsUrl = c.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 };
+}
+export {
+  ALL_FIELDS,
+  LeadsError,
+  composeQuery,
+  defaultFilename,
+  mapsSearchUrl,
+  normalizeFields,
+  parseRating,
+  parseReviewCount,
+  scrapeLeads,
+  scrapeLeads as searchLeads,
+  serialize,
+  toRows
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "lacspace-leads",
+  "version": "0.1.0",
+  "description": "Free, open-source local-business lead finder — name a city, area and business type, and it drives a real browser over Google Maps to collect names, phones, websites, ratings and addresses, then exports to JSON, CSV or Excel. No API keys.",
+  "type": "module",
+  "bin": {
+    "lacspace-leads": "dist/cli.js"
+  },
+  "main": "./dist/lib.cjs",
+  "module": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js",
+      "require": "./dist/lib.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "leads",
+    "lead-generation",
+    "google-maps",
+    "scraper",
+    "local-business",
+    "prospecting",
+    "b2b",
+    "csv",
+    "excel",
+    "playwright",
+    "cli",
+    "osint",
+    "nepal",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/lacspace-leads.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/lacspace-leads/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@lacspace/csv": "^1.1.1",
+    "@lacspace/xlsx": "^1.1.0",
+    "playwright-core": "^1.48.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}