lacspace-leads 0.2.0 → 0.3.0

package/dist/lib.d.cts

@@ -1,9 +1,17 @@
 /** The fields a {@link Lead} can carry — request any subset via `fields`. */
-type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
 /** Every field, in a sensible column order for exports. */
 declare const ALL_FIELDS: LeadField[];
 /** Fields that require visiting the business website (via `enrich`). */
 declare const ENRICHED_FIELDS: LeadField[];
+/** Named field bundles for common jobs — pass via `preset` / `--preset`. */
+declare const FIELD_PRESETS: Record<string, LeadField[]>;
+/**
+ * Fields collected by default — everything Google Maps shows directly, i.e.
+ * {@link ALL_FIELDS} minus the {@link ENRICHED_FIELDS} that need a website visit.
+ * Ask for the enriched ones explicitly (or via `enrich`) to opt into that work.
+ */
+declare const DEFAULT_FIELDS: LeadField[];
 /** A single collected business lead. Every field is optional — Maps listings vary. */
 interface Lead {
     name?: string;
@@ -25,6 +33,16 @@ interface Lead {
     instagram?: string;
     /** WhatsApp number/link, from the website (needs enrichment). */
     whatsapp?: string;
+    /** LinkedIn company/profile URL, from the website (needs enrichment). */
+    linkedin?: string;
+    /** Twitter / X URL, from the website (needs enrichment). */
+    twitter?: string;
+    /** YouTube channel URL, from the website (needs enrichment). */
+    youtube?: string;
+    /** TikTok URL, from the website (needs enrichment). */
+    tiktok?: string;
+    /** Telegram link, from the website (needs enrichment). */
+    telegram?: string;
     /** Google Plus Code, when shown. */
     plusCode?: string;
     /** Latitude, parsed from the listing's Maps URL. */
@@ -50,7 +68,9 @@ interface LeadFilters {
     hasEmail?: boolean;
 }
 /** Output formats the tool can write. */
-type OutputFormat = "json" | "csv" | "xlsx";
+type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
+/** How to sort collected leads before export. */
+type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel";
 /** Options for a lead search. */
 interface SearchOptions {
     /** City, e.g. "Kathmandu". */
@@ -85,6 +105,27 @@ interface SearchOptions {
     filters?: LeadFilters;
     /** Drop duplicate leads by this key. Default "website" when present else "name". */
     dedupe?: "website" | "phone" | "name" | "none";
+    /** Sort the results by this key before returning. */
+    sort?: SortKey$1;
+    /** Sort direction. Defaults to "desc" for numbers, "asc" for name. */
+    sortDir?: "asc" | "desc";
+    /**
+     * Normalise phone numbers to E.164 using this default country — an ISO-2 code
+     * (`"NP"`, `"US"`) or a raw calling code (`"977"`). Best-effort; numbers that
+     * can't be parsed are left as-is.
+     */
+    country?: string;
+    /**
+     * Tidy website URLs — unwrap Google redirects and strip tracking params.
+     * Default true.
+     */
+    cleanUrls?: boolean;
+    /** How many websites to enrich in parallel. Default 3. */
+    concurrency?: number;
+    /** Browser/UI locale, e.g. "en-US", "ne-NP". Default "en-US". */
+    locale?: string;
+    /** Google region bias (ccTLD-style), e.g. "np", "us". Sets Maps `gl`. */
+    region?: string;
     /** Stop collecting after this many milliseconds (best-effort). */
     maxMs?: number;
     /** Called with a short progress message as the search runs. */
@@ -122,6 +163,32 @@ declare function parseLatLng(url: string): {
  */
 declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
 
+/** One sub-search in a batch. */
+interface BatchQuery {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}
+/**
+ * Run each `{type, city, area}` search in turn and merge the results, applying
+ * a single cross-search dedupe and sort at the end. Per-search `limit` is the
+ * cap for *each* sub-search; `opts.total`, when set, caps the merged list.
+ *
+ * Filtering and sorting are applied once, globally, here — so pass them via
+ * `opts` rather than relying on the per-search pass.
+ */
+declare function searchLeadsBatch(queries: BatchQuery[], opts?: Omit<SearchOptions, "type" | "city" | "area" | "query"> & {
+    total?: number;
+}): Promise<Lead[]>;
+/**
+ * Convenience wrapper: expand a single request with comma-separated
+ * `type`/`city`/`area` into its cross-product and run it as a batch.
+ */
+declare function searchLeadsMulti(opts: SearchOptions & {
+    total?: number;
+}): 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. */
@@ -142,8 +209,32 @@ declare function composeQuery(opts: {
     area?: string;
     city?: string;
 }): string;
-/** The Google Maps search URL for a query. `hl=en` keeps labels predictable. */
-declare function mapsSearchUrl(query: string): string;
+/**
+ * The Google Maps search URL for a query. `hl` (interface language) keeps the
+ * scraped aria-labels predictable; `gl` biases results to a region.
+ */
+declare function mapsSearchUrl(query: string, opts?: {
+    hl?: string;
+    gl?: string;
+}): string;
+/**
+ * Expand a possibly-multi search request into individual `{type, city, area}`
+ * queries — the cross-product of comma-separated types × cities × areas. An
+ * explicit `query` short-circuits to a single verbatim search. Used for batch.
+ */
+declare function expandQueries(opts: {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}): {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}[];
+/** Resolve a preset name to its field list, case-insensitively. */
+declare function resolvePreset(name?: string): LeadField[] | undefined;
 /**
  * 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
@@ -161,6 +252,41 @@ declare function filterLeads(leads: Lead[], filters?: LeadFilters): Lead[];
  */
 declare function dedupeLeads(leads: Lead[], by?: NonNullable<SearchOptions["dedupe"]>): Lead[];
 
+/**
+ * Pure data-cleaning helpers — website tidy-up, best-effort E.164 phone
+ * normalisation, and lead sorting. All exported so they can be unit-tested and
+ * reused; none touch the network or the disk.
+ */
+
+/**
+ * Tidy a website URL: unwrap a Google `/url?q=…` redirect, drop tracking query
+ * params (utm_*, fbclid, gclid…) and any fragment, and lower-case the host.
+ * Returns `undefined` for empty input, and the original string if it can't be
+ * parsed as a URL. Pure.
+ */
+declare function cleanWebsite(url?: string): string | undefined;
+/**
+ * ISO-3166 alpha-2 → E.164 country calling code, for a curated set of common
+ * markets. Extend as needed; unknown codes fall through to best-effort.
+ */
+declare const CALLING_CODES: Record<string, string>;
+/** Resolve a country argument (ISO-2 code or a raw calling code) to digits. */
+declare function callingCode(country?: string): string | undefined;
+/**
+ * Best-effort E.164 normalisation of a phone string given a default country
+ * (an ISO-2 code like `"NP"` or a calling code like `"977"`). Numbers that
+ * already start with `+` are kept as international. When the result isn't a
+ * plausible 8–15-digit number, the original string is returned unchanged. Pure.
+ */
+declare function normalizePhone(raw?: string, country?: string): string | undefined;
+/** Keys a lead list can be sorted by. */
+type SortKey = "rating" | "reviews" | "name" | "priceLevel";
+/**
+ * Sort leads by a key, missing values always last. Stable, pure, new array.
+ * `dir` defaults to descending for numeric keys and ascending for `name`.
+ */
+declare function sortLeads(leads: Lead[], by?: SortKey, dir?: "asc" | "desc"): Lead[];
+
 /**
  * Website enrichment — visit a business's site and pull an email + social
  * links. Uses global `fetch` (Node 20+); every network call is guarded so a
@@ -172,10 +298,18 @@ interface Contacts {
     facebook?: string;
     instagram?: string;
     whatsapp?: string;
+    linkedin?: string;
+    twitter?: string;
+    youtube?: string;
+    tiktok?: string;
+    telegram?: string;
 }
 /** Extract the best contact email from HTML, or `undefined`. Pure. */
 declare function extractEmails(html: string): string | undefined;
-/** Extract Facebook / Instagram / WhatsApp links from HTML. Pure. */
+/**
+ * Extract social links (Facebook, Instagram, WhatsApp, LinkedIn, Twitter/X,
+ * YouTube, TikTok, Telegram) from HTML. Skips share/intent/widget links. Pure.
+ */
 declare function extractSocials(html: string): Omit<Contacts, "email">;
 /**
  * Fetch a website (home page, then a /contact page if needed) and pull an email
@@ -212,4 +346,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type Contacts, type DataRow, ENRICHED_FIELDS, type Lead, type LeadField, type LeadFilters, LeadsError, type OutputFormat, type SearchOptions, columnsOf, composeQuery, convertFile, dedupeLeads, defaultFilename, detectFormat, enrichContacts, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, parseLatLng, parseRating, parseReviewCount, readRows, scrapeLeads, scrapeLeads as searchLeads, serialize, serializeRows, toRows };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, ENRICHED_FIELDS, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, convertFile, dedupeLeads, defaultFilename, detectFormat, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows };

package/dist/lib.d.ts

@@ -1,9 +1,17 @@
 /** The fields a {@link Lead} can carry — request any subset via `fields`. */
-type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+type LeadField = "name" | "category" | "rating" | "reviews" | "priceLevel" | "address" | "phone" | "website" | "email" | "facebook" | "instagram" | "whatsapp" | "linkedin" | "twitter" | "youtube" | "tiktok" | "telegram" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
 /** Every field, in a sensible column order for exports. */
 declare const ALL_FIELDS: LeadField[];
 /** Fields that require visiting the business website (via `enrich`). */
 declare const ENRICHED_FIELDS: LeadField[];
+/** Named field bundles for common jobs — pass via `preset` / `--preset`. */
+declare const FIELD_PRESETS: Record<string, LeadField[]>;
+/**
+ * Fields collected by default — everything Google Maps shows directly, i.e.
+ * {@link ALL_FIELDS} minus the {@link ENRICHED_FIELDS} that need a website visit.
+ * Ask for the enriched ones explicitly (or via `enrich`) to opt into that work.
+ */
+declare const DEFAULT_FIELDS: LeadField[];
 /** A single collected business lead. Every field is optional — Maps listings vary. */
 interface Lead {
     name?: string;
@@ -25,6 +33,16 @@ interface Lead {
     instagram?: string;
     /** WhatsApp number/link, from the website (needs enrichment). */
     whatsapp?: string;
+    /** LinkedIn company/profile URL, from the website (needs enrichment). */
+    linkedin?: string;
+    /** Twitter / X URL, from the website (needs enrichment). */
+    twitter?: string;
+    /** YouTube channel URL, from the website (needs enrichment). */
+    youtube?: string;
+    /** TikTok URL, from the website (needs enrichment). */
+    tiktok?: string;
+    /** Telegram link, from the website (needs enrichment). */
+    telegram?: string;
     /** Google Plus Code, when shown. */
     plusCode?: string;
     /** Latitude, parsed from the listing's Maps URL. */
@@ -50,7 +68,9 @@ interface LeadFilters {
     hasEmail?: boolean;
 }
 /** Output formats the tool can write. */
-type OutputFormat = "json" | "csv" | "xlsx";
+type OutputFormat = "json" | "ndjson" | "csv" | "xlsx";
+/** How to sort collected leads before export. */
+type SortKey$1 = "rating" | "reviews" | "name" | "priceLevel";
 /** Options for a lead search. */
 interface SearchOptions {
     /** City, e.g. "Kathmandu". */
@@ -85,6 +105,27 @@ interface SearchOptions {
     filters?: LeadFilters;
     /** Drop duplicate leads by this key. Default "website" when present else "name". */
     dedupe?: "website" | "phone" | "name" | "none";
+    /** Sort the results by this key before returning. */
+    sort?: SortKey$1;
+    /** Sort direction. Defaults to "desc" for numbers, "asc" for name. */
+    sortDir?: "asc" | "desc";
+    /**
+     * Normalise phone numbers to E.164 using this default country — an ISO-2 code
+     * (`"NP"`, `"US"`) or a raw calling code (`"977"`). Best-effort; numbers that
+     * can't be parsed are left as-is.
+     */
+    country?: string;
+    /**
+     * Tidy website URLs — unwrap Google redirects and strip tracking params.
+     * Default true.
+     */
+    cleanUrls?: boolean;
+    /** How many websites to enrich in parallel. Default 3. */
+    concurrency?: number;
+    /** Browser/UI locale, e.g. "en-US", "ne-NP". Default "en-US". */
+    locale?: string;
+    /** Google region bias (ccTLD-style), e.g. "np", "us". Sets Maps `gl`. */
+    region?: string;
     /** Stop collecting after this many milliseconds (best-effort). */
     maxMs?: number;
     /** Called with a short progress message as the search runs. */
@@ -122,6 +163,32 @@ declare function parseLatLng(url: string): {
  */
 declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
 
+/** One sub-search in a batch. */
+interface BatchQuery {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}
+/**
+ * Run each `{type, city, area}` search in turn and merge the results, applying
+ * a single cross-search dedupe and sort at the end. Per-search `limit` is the
+ * cap for *each* sub-search; `opts.total`, when set, caps the merged list.
+ *
+ * Filtering and sorting are applied once, globally, here — so pass them via
+ * `opts` rather than relying on the per-search pass.
+ */
+declare function searchLeadsBatch(queries: BatchQuery[], opts?: Omit<SearchOptions, "type" | "city" | "area" | "query"> & {
+    total?: number;
+}): Promise<Lead[]>;
+/**
+ * Convenience wrapper: expand a single request with comma-separated
+ * `type`/`city`/`area` into its cross-product and run it as a batch.
+ */
+declare function searchLeadsMulti(opts: SearchOptions & {
+    total?: number;
+}): 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. */
@@ -142,8 +209,32 @@ declare function composeQuery(opts: {
     area?: string;
     city?: string;
 }): string;
-/** The Google Maps search URL for a query. `hl=en` keeps labels predictable. */
-declare function mapsSearchUrl(query: string): string;
+/**
+ * The Google Maps search URL for a query. `hl` (interface language) keeps the
+ * scraped aria-labels predictable; `gl` biases results to a region.
+ */
+declare function mapsSearchUrl(query: string, opts?: {
+    hl?: string;
+    gl?: string;
+}): string;
+/**
+ * Expand a possibly-multi search request into individual `{type, city, area}`
+ * queries — the cross-product of comma-separated types × cities × areas. An
+ * explicit `query` short-circuits to a single verbatim search. Used for batch.
+ */
+declare function expandQueries(opts: {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}): {
+    type?: string;
+    city?: string;
+    area?: string;
+    query?: string;
+}[];
+/** Resolve a preset name to its field list, case-insensitively. */
+declare function resolvePreset(name?: string): LeadField[] | undefined;
 /**
  * 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
@@ -161,6 +252,41 @@ declare function filterLeads(leads: Lead[], filters?: LeadFilters): Lead[];
  */
 declare function dedupeLeads(leads: Lead[], by?: NonNullable<SearchOptions["dedupe"]>): Lead[];
 
+/**
+ * Pure data-cleaning helpers — website tidy-up, best-effort E.164 phone
+ * normalisation, and lead sorting. All exported so they can be unit-tested and
+ * reused; none touch the network or the disk.
+ */
+
+/**
+ * Tidy a website URL: unwrap a Google `/url?q=…` redirect, drop tracking query
+ * params (utm_*, fbclid, gclid…) and any fragment, and lower-case the host.
+ * Returns `undefined` for empty input, and the original string if it can't be
+ * parsed as a URL. Pure.
+ */
+declare function cleanWebsite(url?: string): string | undefined;
+/**
+ * ISO-3166 alpha-2 → E.164 country calling code, for a curated set of common
+ * markets. Extend as needed; unknown codes fall through to best-effort.
+ */
+declare const CALLING_CODES: Record<string, string>;
+/** Resolve a country argument (ISO-2 code or a raw calling code) to digits. */
+declare function callingCode(country?: string): string | undefined;
+/**
+ * Best-effort E.164 normalisation of a phone string given a default country
+ * (an ISO-2 code like `"NP"` or a calling code like `"977"`). Numbers that
+ * already start with `+` are kept as international. When the result isn't a
+ * plausible 8–15-digit number, the original string is returned unchanged. Pure.
+ */
+declare function normalizePhone(raw?: string, country?: string): string | undefined;
+/** Keys a lead list can be sorted by. */
+type SortKey = "rating" | "reviews" | "name" | "priceLevel";
+/**
+ * Sort leads by a key, missing values always last. Stable, pure, new array.
+ * `dir` defaults to descending for numeric keys and ascending for `name`.
+ */
+declare function sortLeads(leads: Lead[], by?: SortKey, dir?: "asc" | "desc"): Lead[];
+
 /**
  * Website enrichment — visit a business's site and pull an email + social
  * links. Uses global `fetch` (Node 20+); every network call is guarded so a
@@ -172,10 +298,18 @@ interface Contacts {
     facebook?: string;
     instagram?: string;
     whatsapp?: string;
+    linkedin?: string;
+    twitter?: string;
+    youtube?: string;
+    tiktok?: string;
+    telegram?: string;
 }
 /** Extract the best contact email from HTML, or `undefined`. Pure. */
 declare function extractEmails(html: string): string | undefined;
-/** Extract Facebook / Instagram / WhatsApp links from HTML. Pure. */
+/**
+ * Extract social links (Facebook, Instagram, WhatsApp, LinkedIn, Twitter/X,
+ * YouTube, TikTok, Telegram) from HTML. Skips share/intent/widget links. Pure.
+ */
 declare function extractSocials(html: string): Omit<Contacts, "email">;
 /**
  * Fetch a website (home page, then a /contact page if needed) and pull an email
@@ -212,4 +346,4 @@ declare function convertFile(input: string, opts?: {
     count: number;
 }>;
 
-export { ALL_FIELDS, type Contacts, type DataRow, ENRICHED_FIELDS, type Lead, type LeadField, type LeadFilters, LeadsError, type OutputFormat, type SearchOptions, columnsOf, composeQuery, convertFile, dedupeLeads, defaultFilename, detectFormat, enrichContacts, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, parseLatLng, parseRating, parseReviewCount, readRows, scrapeLeads, scrapeLeads as searchLeads, serialize, serializeRows, toRows };
+export { ALL_FIELDS, type BatchQuery, CALLING_CODES, type Contacts, DEFAULT_FIELDS, type DataRow, ENRICHED_FIELDS, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, convertFile, dedupeLeads, defaultFilename, detectFormat, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows };