lacspace-leads 0.1.0

package/dist/lib.cjs

@@ -0,0 +1,347 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib.ts
+var lib_exports = {};
+__export(lib_exports, {
+  ALL_FIELDS: () => ALL_FIELDS,
+  LeadsError: () => LeadsError,
+  composeQuery: () => composeQuery,
+  defaultFilename: () => defaultFilename,
+  mapsSearchUrl: () => mapsSearchUrl,
+  normalizeFields: () => normalizeFields,
+  parseRating: () => parseRating,
+  parseReviewCount: () => parseReviewCount,
+  scrapeLeads: () => scrapeLeads,
+  searchLeads: () => scrapeLeads,
+  serialize: () => serialize,
+  toRows: () => toRows
+});
+module.exports = __toCommonJS(lib_exports);
+
+// src/scrape.ts
+var import_playwright_core = require("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 import_playwright_core.chromium.launch({ headless, channel });
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  try {
+    return await import_playwright_core.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
+var import_csv = require("@lacspace/csv");
+var import_xlsx = require("@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: (0, import_csv.stringify)(csvRows, { escapeFormulas: true }), binary: false };
+  }
+  return { data: (0, import_xlsx.jsonToXlsx)(rows, { sheetName: "Leads" }), binary: true };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ALL_FIELDS,
+  LeadsError,
+  composeQuery,
+  defaultFilename,
+  mapsSearchUrl,
+  normalizeFields,
+  parseRating,
+  parseReviewCount,
+  scrapeLeads,
+  searchLeads,
+  serialize,
+  toRows
+});

package/dist/lib.d.cts

@@ -0,0 +1,105 @@
+/** The fields a {@link Lead} can carry — request any subset via `fields`. */
+type LeadField = "name" | "category" | "rating" | "reviews" | "address" | "phone" | "website" | "plusCode" | "hours" | "mapsUrl";
+/** Every field, in a sensible column order for exports. */
+declare const ALL_FIELDS: LeadField[];
+/** A single collected business lead. Every field is optional — Maps listings vary. */
+interface Lead {
+    name?: string;
+    category?: string;
+    /** Star rating, 0–5. */
+    rating?: number;
+    /** Number of reviews. */
+    reviews?: number;
+    address?: string;
+    phone?: string;
+    website?: string;
+    /** Google Plus Code, when shown. */
+    plusCode?: string;
+    /** Opening-hours summary, when shown. */
+    hours?: string;
+    /** Canonical Google Maps URL for the listing. */
+    mapsUrl?: string;
+}
+/** Output formats the tool can write. */
+type OutputFormat = "json" | "csv" | "xlsx";
+/** Options for a lead search. */
+interface SearchOptions {
+    /** City, e.g. "Kathmandu". */
+    city?: string;
+    /** Area / neighbourhood, e.g. "Baneshwor". */
+    area?: string;
+    /** Business type / keyword, e.g. "restaurants", "dental clinic". */
+    type: string;
+    /** A ready-made query, used verbatim instead of composing city/area/type. */
+    query?: string;
+    /** Max number of leads to collect. Default 60. */
+    limit?: number;
+    /** Fields to collect. Default: all of {@link ALL_FIELDS}. */
+    fields?: LeadField[];
+    /** Run the browser without a visible window. Default false (visible). */
+    headless?: boolean;
+    /**
+     * Open each listing to pull phone/website/plus-code/hours (slower but far
+     * richer). When false, only what the results list shows is captured.
+     * Default true.
+     */
+    details?: boolean;
+    /** Milliseconds to pause between listing opens (politeness). Default 700. */
+    delayMs?: number;
+    /** Called with a short progress message as the search runs. */
+    onProgress?: (message: string) => void;
+    /** An AbortSignal to cancel a running search. */
+    signal?: AbortSignal;
+}
+
+/** Error thrown by the scraper. Carries a machine `code` and optional cause. */
+declare class LeadsError extends Error {
+    code?: string;
+    cause?: unknown;
+    constructor(message: string, code?: string, cause?: unknown);
+}
+/**
+ * Parse a "N reviews" / "N,234 reviews" aria-label into a count. Exported for
+ * testing the messy number formats Google uses.
+ */
+declare function parseReviewCount(label: string | null | undefined): number | undefined;
+/** Parse a rating like "4.5" or "4,5" into a number in 0–5. */
+declare function parseRating(text: string | null | undefined): number | undefined;
+/**
+ * Run the Google Maps search in a real browser and collect leads. This is the
+ * scraping engine behind {@link searchLeads}; prefer that wrapper.
+ *
+ * @throws {LeadsError} when no browser can be launched, or the search is aborted.
+ */
+declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
+
+/** 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. */
+declare function serialize(leads: Lead[], format: OutputFormat, fields?: LeadField[]): {
+    data: string | Uint8Array;
+    binary: boolean;
+};
+
+/**
+ * Compose the human search query from options: an explicit `query` wins,
+ * otherwise "<type> in <area>, <city>" with the empty parts dropped.
+ */
+declare function composeQuery(opts: {
+    query?: string;
+    type?: string;
+    area?: string;
+    city?: string;
+}): string;
+/** The Google Maps search URL for a query. `hl=en` keeps labels predictable. */
+declare function mapsSearchUrl(query: string): string;
+/**
+ * Normalise a fields request (array or comma string) into known {@link LeadField}s
+ * in canonical order, de-duplicated. Unknown names are ignored; an empty result
+ * falls back to all fields.
+ */
+declare function normalizeFields(input?: readonly string[] | string): LeadField[];
+/** A safe, timestamped default output filename for a query + format. */
+declare function defaultFilename(query: string, format: string): string;
+
+export { ALL_FIELDS, type Lead, type LeadField, LeadsError, type OutputFormat, type SearchOptions, composeQuery, defaultFilename, mapsSearchUrl, normalizeFields, parseRating, parseReviewCount, scrapeLeads, scrapeLeads as searchLeads, serialize, toRows };

package/dist/lib.d.ts

@@ -0,0 +1,105 @@
+/** The fields a {@link Lead} can carry — request any subset via `fields`. */
+type LeadField = "name" | "category" | "rating" | "reviews" | "address" | "phone" | "website" | "plusCode" | "hours" | "mapsUrl";
+/** Every field, in a sensible column order for exports. */
+declare const ALL_FIELDS: LeadField[];
+/** A single collected business lead. Every field is optional — Maps listings vary. */
+interface Lead {
+    name?: string;
+    category?: string;
+    /** Star rating, 0–5. */
+    rating?: number;
+    /** Number of reviews. */
+    reviews?: number;
+    address?: string;
+    phone?: string;
+    website?: string;
+    /** Google Plus Code, when shown. */
+    plusCode?: string;
+    /** Opening-hours summary, when shown. */
+    hours?: string;
+    /** Canonical Google Maps URL for the listing. */
+    mapsUrl?: string;
+}
+/** Output formats the tool can write. */
+type OutputFormat = "json" | "csv" | "xlsx";
+/** Options for a lead search. */
+interface SearchOptions {
+    /** City, e.g. "Kathmandu". */
+    city?: string;
+    /** Area / neighbourhood, e.g. "Baneshwor". */
+    area?: string;
+    /** Business type / keyword, e.g. "restaurants", "dental clinic". */
+    type: string;
+    /** A ready-made query, used verbatim instead of composing city/area/type. */
+    query?: string;
+    /** Max number of leads to collect. Default 60. */
+    limit?: number;
+    /** Fields to collect. Default: all of {@link ALL_FIELDS}. */
+    fields?: LeadField[];
+    /** Run the browser without a visible window. Default false (visible). */
+    headless?: boolean;
+    /**
+     * Open each listing to pull phone/website/plus-code/hours (slower but far
+     * richer). When false, only what the results list shows is captured.
+     * Default true.
+     */
+    details?: boolean;
+    /** Milliseconds to pause between listing opens (politeness). Default 700. */
+    delayMs?: number;
+    /** Called with a short progress message as the search runs. */
+    onProgress?: (message: string) => void;
+    /** An AbortSignal to cancel a running search. */
+    signal?: AbortSignal;
+}
+
+/** Error thrown by the scraper. Carries a machine `code` and optional cause. */
+declare class LeadsError extends Error {
+    code?: string;
+    cause?: unknown;
+    constructor(message: string, code?: string, cause?: unknown);
+}
+/**
+ * Parse a "N reviews" / "N,234 reviews" aria-label into a count. Exported for
+ * testing the messy number formats Google uses.
+ */
+declare function parseReviewCount(label: string | null | undefined): number | undefined;
+/** Parse a rating like "4.5" or "4,5" into a number in 0–5. */
+declare function parseRating(text: string | null | undefined): number | undefined;
+/**
+ * Run the Google Maps search in a real browser and collect leads. This is the
+ * scraping engine behind {@link searchLeads}; prefer that wrapper.
+ *
+ * @throws {LeadsError} when no browser can be launched, or the search is aborted.
+ */
+declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
+
+/** 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. */
+declare function serialize(leads: Lead[], format: OutputFormat, fields?: LeadField[]): {
+    data: string | Uint8Array;
+    binary: boolean;
+};
+
+/**
+ * Compose the human search query from options: an explicit `query` wins,
+ * otherwise "<type> in <area>, <city>" with the empty parts dropped.
+ */
+declare function composeQuery(opts: {
+    query?: string;
+    type?: string;
+    area?: string;
+    city?: string;
+}): string;
+/** The Google Maps search URL for a query. `hl=en` keeps labels predictable. */
+declare function mapsSearchUrl(query: string): string;
+/**
+ * Normalise a fields request (array or comma string) into known {@link LeadField}s
+ * in canonical order, de-duplicated. Unknown names are ignored; an empty result
+ * falls back to all fields.
+ */
+declare function normalizeFields(input?: readonly string[] | string): LeadField[];
+/** A safe, timestamped default output filename for a query + format. */
+declare function defaultFilename(query: string, format: string): string;
+
+export { ALL_FIELDS, type Lead, type LeadField, LeadsError, type OutputFormat, type SearchOptions, composeQuery, defaultFilename, mapsSearchUrl, normalizeFields, parseRating, parseReviewCount, scrapeLeads, scrapeLeads as searchLeads, serialize, toRows };