lacspace-leads 0.2.1 → 1.2.1

package/dist/lib.d.cts

@@ -1,9 +1,19 @@
 /** 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" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+/** Deliverability verdict for a discovered email (see `verifyEmails`). */
+type EmailStatus = "valid" | "no-mx" | "invalid-format" | "unknown";
 /** 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 +35,18 @@ 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;
+    /** Email deliverability verdict (set by `verifyEmails`). */
+    emailStatus?: EmailStatus;
     /** Google Plus Code, when shown. */
     plusCode?: string;
     /** Latitude, parsed from the listing's Maps URL. */
@@ -48,9 +70,13 @@ interface LeadFilters {
     hasWebsite?: boolean;
     /** Keep only leads that have an email (implies enrichment). */
     hasEmail?: boolean;
+    /** Keep only leads whose email passed MX verification (implies `verifyEmails`). */
+    hasValidEmail?: 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". */
@@ -83,15 +109,66 @@ interface SearchOptions {
     enrich?: boolean;
     /** Drop leads that don't pass these filters. */
     filters?: LeadFilters;
-    /** Drop duplicate leads by this key. Default "website" when present else "name". */
-    dedupe?: "website" | "phone" | "name" | "none";
+    /**
+     * Drop duplicate leads by this key. `"smart"` uses the strongest identity
+     * available per lead (website → phone → name) and is best for accumulating
+     * across runs. Default "website".
+     */
+    dedupe?: "website" | "phone" | "name" | "smart" | "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;
+    /**
+     * Verify each discovered email by checking its domain has MX records (DNS,
+     * no message is sent). Populates `emailStatus`. Implies `enrich`. Default off.
+     */
+    verifyEmails?: boolean;
+    /** 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;
+    /** Route the browser through this proxy, e.g. "http://user:pass@host:port". */
+    proxy?: string;
+    /** Retry a listing that fails to open, up to this many times. Default 1. */
+    retries?: number;
+    /** Randomise the delay between listings by ±40% to look more human. */
+    jitter?: boolean;
     /** Stop collecting after this many milliseconds (best-effort). */
     maxMs?: number;
     /** Called with a short progress message as the search runs. */
     onProgress?: (message: string) => void;
+    /**
+     * Called with each lead as it's collected (before enrichment), for live UIs
+     * or crash-safe incremental writing. Never throws into the run.
+     */
+    onLead?: (lead: Lead) => void;
     /** An AbortSignal to cancel a running search. */
     signal?: AbortSignal;
 }
+/** Aggregate counts over a lead list — see `computeStats`. */
+interface LeadStats {
+    total: number;
+    withPhone: number;
+    withWebsite: number;
+    withEmail: number;
+    withValidEmail: number;
+    withSocial: number;
+    avgRating?: number;
+}
 
 /** Error thrown by the scraper. Carries a machine `code` and optional cause. */
 declare class LeadsError extends Error {
@@ -121,6 +198,44 @@ declare function parseLatLng(url: string): {
  * @throws {LeadsError} when no browser can be launched, or the search is aborted.
  */
 declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
+/** A search result with aggregate stats and timing. */
+interface DetailedResult {
+    leads: Lead[];
+    stats: LeadStats;
+    /** Wall-clock time of the search, in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * Like {@link scrapeLeads}, but also returns aggregate {@link LeadStats} and the
+ * elapsed time — handy for dashboards, reports and CI summaries.
+ */
+declare function searchLeadsDetailed(opts: SearchOptions): Promise<DetailedResult>;
+
+/** 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>[];
@@ -131,6 +246,37 @@ declare function serialize(leads: Lead[], format: OutputFormat, fields?: LeadFie
     data: string | Uint8Array;
     binary: boolean;
 };
+/** Aggregate counts over a lead list — for summaries and reports. Pure. */
+declare function computeStats(leads: Lead[]): LeadStats;
+/**
+ * Map arbitrary rows (as read back from a JSON/CSV/Excel export, keyed by field
+ * name or header label) into {@link Lead}s. Unknown columns are ignored, blanks
+ * dropped, and numeric fields coerced. Powers `--append` / resume. Pure.
+ */
+declare function rowsToLeads(rows: Record<string, unknown>[]): Lead[];
+
+/** True when `email` is a plausibly-valid address shape. Pure. */
+declare function emailFormatValid(email: string | undefined): boolean;
+/** The domain part of an email, lower-cased, or undefined. Pure. */
+declare function emailDomain(email: string | undefined): string | undefined;
+/**
+ * Classify a single email: `invalid-format` → `no-mx` → `valid`. `unknown` is
+ * reserved for a missing address. Never throws.
+ */
+declare function verifyEmail(email: string | undefined, opts?: {
+    cache?: Map<string, boolean>;
+    timeoutMs?: number;
+}): Promise<EmailStatus>;
+/**
+ * Verify the `email` on each lead in place, setting `emailStatus`. Domains are
+ * looked up once (shared cache) and checked a few in parallel. Leads without an
+ * email are left untouched. Node-only; never throws.
+ */
+declare function verifyEmails(leads: Lead[], opts?: {
+    concurrency?: number;
+    timeoutMs?: number;
+    onProgress?: (m: string) => void;
+}): Promise<Lead[]>;
 
 /**
  * Compose the human search query from options: an explicit `query` wins,
@@ -142,8 +288,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 +331,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 +377,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 +425,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, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails };

package/dist/lib.d.ts

@@ -1,9 +1,19 @@
 /** 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" | "emailStatus" | "plusCode" | "latitude" | "longitude" | "hours" | "mapsUrl";
+/** Deliverability verdict for a discovered email (see `verifyEmails`). */
+type EmailStatus = "valid" | "no-mx" | "invalid-format" | "unknown";
 /** 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 +35,18 @@ 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;
+    /** Email deliverability verdict (set by `verifyEmails`). */
+    emailStatus?: EmailStatus;
     /** Google Plus Code, when shown. */
     plusCode?: string;
     /** Latitude, parsed from the listing's Maps URL. */
@@ -48,9 +70,13 @@ interface LeadFilters {
     hasWebsite?: boolean;
     /** Keep only leads that have an email (implies enrichment). */
     hasEmail?: boolean;
+    /** Keep only leads whose email passed MX verification (implies `verifyEmails`). */
+    hasValidEmail?: 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". */
@@ -83,15 +109,66 @@ interface SearchOptions {
     enrich?: boolean;
     /** Drop leads that don't pass these filters. */
     filters?: LeadFilters;
-    /** Drop duplicate leads by this key. Default "website" when present else "name". */
-    dedupe?: "website" | "phone" | "name" | "none";
+    /**
+     * Drop duplicate leads by this key. `"smart"` uses the strongest identity
+     * available per lead (website → phone → name) and is best for accumulating
+     * across runs. Default "website".
+     */
+    dedupe?: "website" | "phone" | "name" | "smart" | "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;
+    /**
+     * Verify each discovered email by checking its domain has MX records (DNS,
+     * no message is sent). Populates `emailStatus`. Implies `enrich`. Default off.
+     */
+    verifyEmails?: boolean;
+    /** 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;
+    /** Route the browser through this proxy, e.g. "http://user:pass@host:port". */
+    proxy?: string;
+    /** Retry a listing that fails to open, up to this many times. Default 1. */
+    retries?: number;
+    /** Randomise the delay between listings by ±40% to look more human. */
+    jitter?: boolean;
     /** Stop collecting after this many milliseconds (best-effort). */
     maxMs?: number;
     /** Called with a short progress message as the search runs. */
     onProgress?: (message: string) => void;
+    /**
+     * Called with each lead as it's collected (before enrichment), for live UIs
+     * or crash-safe incremental writing. Never throws into the run.
+     */
+    onLead?: (lead: Lead) => void;
     /** An AbortSignal to cancel a running search. */
     signal?: AbortSignal;
 }
+/** Aggregate counts over a lead list — see `computeStats`. */
+interface LeadStats {
+    total: number;
+    withPhone: number;
+    withWebsite: number;
+    withEmail: number;
+    withValidEmail: number;
+    withSocial: number;
+    avgRating?: number;
+}
 
 /** Error thrown by the scraper. Carries a machine `code` and optional cause. */
 declare class LeadsError extends Error {
@@ -121,6 +198,44 @@ declare function parseLatLng(url: string): {
  * @throws {LeadsError} when no browser can be launched, or the search is aborted.
  */
 declare function scrapeLeads(opts: SearchOptions): Promise<Lead[]>;
+/** A search result with aggregate stats and timing. */
+interface DetailedResult {
+    leads: Lead[];
+    stats: LeadStats;
+    /** Wall-clock time of the search, in milliseconds. */
+    elapsedMs: number;
+}
+/**
+ * Like {@link scrapeLeads}, but also returns aggregate {@link LeadStats} and the
+ * elapsed time — handy for dashboards, reports and CI summaries.
+ */
+declare function searchLeadsDetailed(opts: SearchOptions): Promise<DetailedResult>;
+
+/** 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>[];
@@ -131,6 +246,37 @@ declare function serialize(leads: Lead[], format: OutputFormat, fields?: LeadFie
     data: string | Uint8Array;
     binary: boolean;
 };
+/** Aggregate counts over a lead list — for summaries and reports. Pure. */
+declare function computeStats(leads: Lead[]): LeadStats;
+/**
+ * Map arbitrary rows (as read back from a JSON/CSV/Excel export, keyed by field
+ * name or header label) into {@link Lead}s. Unknown columns are ignored, blanks
+ * dropped, and numeric fields coerced. Powers `--append` / resume. Pure.
+ */
+declare function rowsToLeads(rows: Record<string, unknown>[]): Lead[];
+
+/** True when `email` is a plausibly-valid address shape. Pure. */
+declare function emailFormatValid(email: string | undefined): boolean;
+/** The domain part of an email, lower-cased, or undefined. Pure. */
+declare function emailDomain(email: string | undefined): string | undefined;
+/**
+ * Classify a single email: `invalid-format` → `no-mx` → `valid`. `unknown` is
+ * reserved for a missing address. Never throws.
+ */
+declare function verifyEmail(email: string | undefined, opts?: {
+    cache?: Map<string, boolean>;
+    timeoutMs?: number;
+}): Promise<EmailStatus>;
+/**
+ * Verify the `email` on each lead in place, setting `emailStatus`. Domains are
+ * looked up once (shared cache) and checked a few in parallel. Leads without an
+ * email are left untouched. Node-only; never throws.
+ */
+declare function verifyEmails(leads: Lead[], opts?: {
+    concurrency?: number;
+    timeoutMs?: number;
+    onProgress?: (m: string) => void;
+}): Promise<Lead[]>;
 
 /**
  * Compose the human search query from options: an explicit `query` wins,
@@ -142,8 +288,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 +331,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 +377,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 +425,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, type DetailedResult, ENRICHED_FIELDS, type EmailStatus, FIELD_PRESETS, type Lead, type LeadField, type LeadFilters, type LeadStats, LeadsError, type OutputFormat, type SearchOptions, type SortKey$1 as SortKey, callingCode, cleanWebsite, columnsOf, composeQuery, computeStats, convertFile, dedupeLeads, defaultFilename, detectFormat, emailDomain, emailFormatValid, enrichContacts, expandQueries, extractEmails, extractSocials, filterLeads, mapsSearchUrl, normalizeFields, normalizePhone, parseLatLng, parseRating, parseReviewCount, readRows, resolvePreset, rowsToLeads, scrapeLeads, scrapeLeads as searchLeads, searchLeadsBatch, searchLeadsDetailed, searchLeadsMulti, serialize, serializeRows, sortLeads, toRows, verifyEmail, verifyEmails };