lacspace-leads 1.8.0 → 1.9.0

package/README.md

@@ -208,6 +208,8 @@ npx lacspace-leads [type] [options]
 | `--region <cc>` | Region bias for results, e.g. `np`, `us` |
 | `--headless` | Run the browser without a visible window |
 | `-y, --yes` | Skip prompts and the browser-open confirmation |
+| `--push <url>` | Also stream finished leads to an https endpoint (CRM, Lacspace Mail) — the file is still written. See [Push leads](#push-leads-to-your-crm--lacspace-mail) |
+| `--push-token <t>` | Bearer token for `--push` (prefer the `LACSPACE_LEADS_PUSH_TOKEN` env var) |
 
 **Enrichment** (visits each business website — slower, opt-in):
 
@@ -381,6 +383,70 @@ Ask for 100 leads and the file gets row 1 as soon as the first business is read,
 
 When the run ends the file is rewritten once more in its final order (`--sort`, `--append` merges). Press **Ctrl-C** and it stops cleanly, saving everything collected. Then run the same command with `--resume`: it keeps the rows in the file, skips those listings and fills up to the `--target`. `--no-live` turns this off and writes only at the end.
 
+## Push leads to your CRM / Lacspace Mail
+
+Add `--push <url>` and every finished lead is also POSTed to that endpoint while the run goes on — for example straight into the **Leads board of [Lacspace Mail](https://mail.lacspace.com)**:
+
+```bash
+export LACSPACE_LEADS_PUSH_TOKEN="…your token…"
+npx lacspace-leads restaurants --city Kathmandu --target 300 --emails --verify-emails --push https://api.lacspace.com/api/webmail/leads/import
+```
+
+**The file is always written too.** `--push` is in addition to the normal output, never instead of it, so if the endpoint is down, slow or rejects the token you still have every lead on disk (and `--resume` works as usual).
+
+**Token.** Prefer the `LACSPACE_LEADS_PUSH_TOKEN` environment variable over `--push-token`, because a token on the command line can be seen in your shell history and in the process list (`ps`). Precedence is `--push-token`, then the config file, then the env var. The token is only ever sent in the `Authorization: Bearer …` header: it is never printed (echoes show `***`) and never written to the output or checkpoint files.
+
+**URL.** Only `https://` is accepted, except `http://localhost`, `http://127.0.0.1` and `http://[::1]` for local development. Anything else stops with a clear error before the browser opens.
+
+**In a campaign file** (`--config`), add a `push` block (CLI flags still win):
+
+```jsonc
+{
+  "searches": [{ "type": "cafes", "city": "Kathmandu" }],
+  "push": { "url": "https://api.lacspace.com/api/webmail/leads/import" }  // token: env var, or "token": "…"
+}
+```
+
+**How it sends.** Finished leads (after enrichment, verification and filters, the same rows the file gets) are batched and flushed **every 10 leads or every 3 seconds**, whichever comes first, in the background, with one request in flight at a time, so pushing never slows the scrape. If the endpoint is slow, waiting leads merge into the next request; at most 2,000 wait in memory, and any beyond that are skipped for the push (with one warning) but still saved to the file. Each request is a `POST` with `Content-Type: application/json`, `Authorization: Bearer <token>` (when a token is set), `User-Agent: lacspace-leads/<version>` and a 15-second timeout:
+
+```jsonc
+{
+  "leads": [ { "name": "Himalayan Java", "phone": "+97714422519", "website": "https://himalayanjava.com", … } ],
+  "search": { "type": "restaurants", "city": "Kathmandu", "area": null, "target": 300 },
+  "run": "6f1c…-…",   // one random UUID per run, the same on every request
+  "seq": 1,           // batch number, from 1
+  "done": false
+}
+```
+
+When the run ends (including a Ctrl-C), the rest is flushed and one final request is sent, bounded to a few seconds so Ctrl-C still exits quickly:
+
+```jsonc
+{ "leads": [], "search": { … }, "run": "6f1c…", "seq": 31, "done": true,
+  "stats": { "total": 300, "withPhone": 281, "withWebsite": 190, "withEmail": 122, "withValidEmail": 117, "withSocial": 0, "avgRating": 4.3 } }
+```
+
+**Failures never cost you the run:**
+
+| Endpoint answers | What happens |
+| --- | --- |
+| network error / timeout / `5xx` | retried 3 times, after 1s, 3s and 9s; then the batch is counted as failed and pushing carries on |
+| `429` | waits for `Retry-After` (seconds or an HTTP date, capped at 60s), still at most 3 retries |
+| `401` / `403` | one error, `push rejected: token invalid or expired, leads are still being saved to <file>`; pushing stops for the rest of the run, scraping and the file carry on |
+| any other `4xx` | one warning per status code, that batch is dropped, pushing carries on |
+
+The run ends with one line such as `push: sent 300 leads in 30 batches, failed 0, not rejected`.
+
+Programmatically, `createPusher({ url, token })` gives you `push(lead)`, `finish(stats)` and `stats()`. Wire it to `onResult`:
+
+```ts
+import { searchLeads, createPusher, computeStats, formatPushSummary } from "lacspace-leads";
+
+const pusher = createPusher({ url: "https://crm.example.com/leads", token: process.env.CRM_TOKEN, search: { type: "cafes", city: "Kathmandu" } });
+const leads = await searchLeads({ type: "cafes", city: "Kathmandu", onResult: (l) => pusher.push(l) });
+console.log(formatPushSummary(await pusher.finish(computeStats(leads))));
+```
+
 ## Resume a long sweep (`--resume`)
 
 Sweeping a whole city one neighbourhood at a time can take a while, and Google may throw a CAPTCHA halfway through. Add `--resume` and every completed sub-search is checkpointed to `<out>.checkpoint.json` — the leads gathered so far plus which searches are done. Re-run the exact same command and it **skips the areas already collected** and picks up where it stopped; when the sweep finishes cleanly the checkpoint is deleted.
@@ -587,6 +653,7 @@ const leads = await searchLeadsBatch(
 | `haversineMeters` / `parseLatLngPair` / `parseDistance` | Pure geo helpers for radius search. |
 | `filterLeads` / `dedupeLeads` / `subtractLeads` / `dedupeKey` | Pure post-processing — filter, in-list dedupe, and cross-file dedupe. |
 | `createLiveWriter(options)` | Write leads to csv / ndjson / json / xlsx (or stdout) one by one as they arrive. |
+| `createPusher(options)` / `validatePushUrl` / `resolvePush` / `parseRetryAfter` / `formatPushSummary` | Stream finished leads to an HTTP endpoint in batches, with retries (1.9.0). |
 | `summarize(leads)` / `formatSummary(s)` | Rating bands, contact coverage %, top categories — the `--summary` engine. |
 | `parsePriceLevel` / `priceLevelValue` / `parseBusinessStatus` / `parseClaimed` / `parseOpenNow` / `parseCategoryTags` | Pure field parsers (unit-tested against HTML/aria snippets). |
 | `pipeToEnrich(handler)` / `leadsToEnrichInput` / `leadDomains` / `leadDomain` | Bridge collected leads to `lacspace-enrich` (no hard dep). |

package/dist/cli.js

@@ -1234,16 +1234,18 @@ async function searchLeadsBatch(queries, opts = {}) {
 
 // src/config.ts
 async function runConfig(config, hooks = {}) {
-  const { searches, filters, total, out, format, append, sheet, ...shared } = config;
+  const { searches, filters, total, out, format, append, sheet, push, ...shared } = config;
   void out;
   void format;
   void append;
   void sheet;
+  void push;
   const opts = { ...shared };
   if (filters) opts.filters = filters;
   if (total !== void 0) opts.total = total;
   if (hooks.onProgress) opts.onProgress = hooks.onProgress;
   if (hooks.signal) opts.signal = hooks.signal;
+  if (hooks.onResult) opts.onResult = hooks.onResult;
   if (hooks.skip) opts.skip = hooks.skip;
   if (hooks.seedLeads) opts.seedLeads = hooks.seedLeads;
   if (hooks.onQueryDone) opts.onQueryDone = hooks.onQueryDone;
@@ -1255,6 +1257,12 @@ function assertConfig(value) {
   if (!Array.isArray(searches) || searches.length === 0) {
     throw new Error('Config needs a non-empty "searches" array, e.g. [{ "type": "cafes", "city": "Kathmandu" }].');
   }
+  const push = value.push;
+  if (push !== void 0) {
+    if (!push || typeof push !== "object" || Array.isArray(push)) throw new Error('Config "push" must be an object: { "url": "https://\u2026", "token": "\u2026" }.');
+    if (push.url !== void 0 && typeof push.url !== "string") throw new Error('Config "push.url" must be a string.');
+    if (push.token !== void 0 && typeof push.token !== "string") throw new Error('Config "push.token" must be a string.');
+  }
 }
 
 // src/convert.ts
@@ -1653,6 +1661,262 @@ function leadsToEnrichInput(leads) {
   return out;
 }
 
+// src/push.ts
+var VERSION = "1.9.0";
+var PUSH_TOKEN_ENV = "LACSPACE_LEADS_PUSH_TOKEN";
+var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+function validatePushUrl(raw) {
+  const s = (raw ?? "").trim();
+  if (!s) throw new Error("--push needs a URL, e.g. --push https://api.example.com/leads");
+  let u;
+  try {
+    u = new URL(s);
+  } catch {
+    throw new Error(`--push URL is not valid: "${maskUrl(s)}"`);
+  }
+  if (u.protocol === "https:") return u;
+  if (u.protocol === "http:" && LOCAL_HOSTS.has(u.hostname.toLowerCase())) return u;
+  if (u.protocol === "http:") throw new Error(`--push must use https:// (plain http is only allowed for localhost, 127.0.0.1 or [::1]): ${maskUrl(s)}`);
+  throw new Error(`--push must be an https:// URL, not ${u.protocol}`);
+}
+function maskUrl(raw) {
+  try {
+    const u = new URL(raw);
+    return `${u.protocol}//${u.host}${u.pathname}${u.search ? "?\u2026" : ""}`;
+  } catch {
+    return String(raw).replace(/\/\/[^@/]+@/, "//***@").replace(/\?.*$/, "?\u2026");
+  }
+}
+function resolvePush(input) {
+  const url = input.flagUrl ?? input.config?.url;
+  if (url === void 0) return void 0;
+  const token = input.flagToken || input.config?.token || input.env?.[PUSH_TOKEN_ENV] || void 0;
+  return token ? { url, token } : { url };
+}
+function parseRetryAfter(value, capMs = 6e4, now = Date.now()) {
+  if (value == null) return void 0;
+  const v = value.trim();
+  if (!v) return void 0;
+  let ms;
+  if (/^\d+(\.\d+)?$/.test(v)) ms = parseFloat(v) * 1e3;
+  else {
+    const t = Date.parse(v);
+    if (Number.isNaN(t)) return void 0;
+    ms = t - now;
+  }
+  return Math.min(Math.max(0, ms), capMs);
+}
+function formatPushSummary(s) {
+  const bits = [`sent ${s.sent} lead${s.sent === 1 ? "" : "s"} in ${s.batches} batch${s.batches === 1 ? "" : "es"}`, `failed ${s.failed}`];
+  if (s.dropped) bits.push(`dropped ${s.dropped} (queue full)`);
+  bits.push(s.rejected ? "REJECTED (401/403)" : "not rejected");
+  return `push: ${bits.join(", ")}`;
+}
+var randomId = () => {
+  const c2 = globalThis.crypto;
+  if (c2?.randomUUID) return c2.randomUUID();
+  const h = (n) => Array.from({ length: n }, () => Math.floor(Math.random() * 16).toString(16)).join("");
+  return `${h(8)}-${h(4)}-4${h(3)}-${"89ab"[Math.floor(Math.random() * 4)]}${h(3)}-${h(12)}`;
+};
+function createPusher(opts) {
+  const url = validatePushUrl(opts.url).toString();
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const batchSize = Math.max(1, opts.batchSize ?? 10);
+  const intervalMs = Math.max(1, opts.intervalMs ?? 3e3);
+  const maxQueue = Math.max(1, opts.maxQueue ?? 2e3);
+  const maxBatch = Math.max(batchSize, opts.maxBatch ?? 500);
+  const timeoutMs = opts.timeoutMs ?? 15e3;
+  const delays = opts.retryDelaysMs ?? [1e3, 3e3, 9e3];
+  const maxRetryAfterMs = opts.maxRetryAfterMs ?? 6e4;
+  const warn = (m) => {
+    try {
+      opts.onWarn?.(m);
+    } catch {
+    }
+  };
+  const run = opts.run ?? randomId();
+  const s = opts.search ?? {};
+  const search = {
+    type: s.type || null,
+    city: s.city || null,
+    area: s.area || null,
+    target: typeof s.target === "number" && Number.isFinite(s.target) ? s.target : null
+  };
+  const headers = {
+    "Content-Type": "application/json",
+    "User-Agent": `lacspace-leads/${VERSION}`
+  };
+  if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
+  const pending = [];
+  const st = { sent: 0, batches: 0, failed: 0, dropped: 0, rejected: false, doneSent: false };
+  let seq = 0;
+  let timer;
+  let due = false;
+  let finishing = false;
+  let finished = false;
+  let sending;
+  let warnedDrop = false;
+  const warned4xx = /* @__PURE__ */ new Set();
+  const stop = new AbortController();
+  const sleep = (ms) => new Promise((res) => {
+    if (stop.signal.aborted) return res();
+    const t = setTimeout(done, ms);
+    function done() {
+      clearTimeout(t);
+      stop.signal.removeEventListener("abort", done);
+      res();
+    }
+    stop.signal.addEventListener("abort", done);
+  });
+  const post = async (payload) => {
+    const body = JSON.stringify(payload);
+    for (let attempt = 0; ; attempt++) {
+      if (stop.signal.aborted) return "stopped";
+      const ac = new AbortController();
+      const onStop = () => ac.abort();
+      stop.signal.addEventListener("abort", onStop);
+      const to = setTimeout(() => ac.abort(), timeoutMs);
+      let status = 0;
+      let retryAfter = null;
+      try {
+        const res = await doFetch(url, { method: "POST", headers, body, signal: ac.signal });
+        status = res.status;
+        retryAfter = res.headers.get("retry-after");
+        try {
+          await res.arrayBuffer();
+        } catch {
+        }
+      } catch {
+        status = 0;
+      } finally {
+        clearTimeout(to);
+        stop.signal.removeEventListener("abort", onStop);
+      }
+      if (stop.signal.aborted) return status >= 200 && status < 300 ? "ok" : "stopped";
+      if (status >= 200 && status < 300) return "ok";
+      if (status === 401 || status === 403) return "rejected";
+      const retryable = status === 0 || status === 429 || status >= 500;
+      if (!retryable) {
+        if (!warned4xx.has(status)) {
+          warned4xx.add(status);
+          warn(`push: endpoint answered HTTP ${status}; dropping that batch and carrying on`);
+        }
+        return "dropped";
+      }
+      if (attempt >= delays.length) return "failed";
+      let wait = delays[attempt] ?? 1e3;
+      if (status === 429) wait = parseRetryAfter(retryAfter, maxRetryAfterMs) ?? wait;
+      await sleep(wait);
+    }
+  };
+  const reject = (lost) => {
+    st.rejected = true;
+    st.failed += lost + pending.length;
+    pending.length = 0;
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+    warn(`push rejected: token invalid or expired, leads are still being saved to ${opts.file ?? "the output file"}`);
+  };
+  const sendLeads = async (leads) => {
+    const outcome = await post({ leads, search, run, seq: ++seq, done: false });
+    if (outcome === "ok") {
+      st.sent += leads.length;
+      st.batches++;
+      return;
+    }
+    if (outcome === "rejected") {
+      reject(leads.length);
+      return;
+    }
+    st.failed += leads.length;
+    if (outcome === "failed") warn(`push: a batch of ${leads.length} lead${leads.length === 1 ? "" : "s"} could not be delivered after retries (still in the file)`);
+  };
+  const schedule = () => {
+    if (timer || !pending.length || st.rejected || finishing) return;
+    timer = setTimeout(() => {
+      timer = void 0;
+      due = true;
+      void drain();
+    }, intervalMs);
+    timer.unref?.();
+  };
+  const drain = () => {
+    if (sending) return sending;
+    sending = (async () => {
+      try {
+        while (!st.rejected && !stop.signal.aborted && pending.length && (due || finishing || pending.length >= batchSize)) {
+          due = false;
+          if (timer) {
+            clearTimeout(timer);
+            timer = void 0;
+          }
+          await sendLeads(pending.splice(0, maxBatch));
+        }
+      } catch {
+      } finally {
+        sending = void 0;
+      }
+      schedule();
+    })();
+    return sending;
+  };
+  const snapshot = () => ({ ...st, pending: pending.length });
+  return {
+    push(lead) {
+      if (st.rejected || finished || stop.signal.aborted) return;
+      if (pending.length >= maxQueue) {
+        st.dropped++;
+        if (!warnedDrop) {
+          warnedDrop = true;
+          warn(`push: the endpoint is too slow, ${maxQueue} leads are already waiting; extra leads are not pushed (they are still in the file)`);
+        }
+        return;
+      }
+      pending.push(lead);
+      if (pending.length >= batchSize) void drain();
+      else schedule();
+    },
+    async finish(stats, fopts) {
+      if (finished) return snapshot();
+      finishing = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      const limit = fopts?.timeoutMs ?? opts.finishTimeoutMs ?? 5e3;
+      let deadline;
+      const work = (async () => {
+        await drain();
+        await drain();
+        if (st.rejected || stop.signal.aborted) return;
+        const payload = { leads: [], search, run, seq: ++seq, done: true };
+        if (stats) payload.stats = stats;
+        const outcome = await post(payload);
+        if (outcome === "ok") st.doneSent = true;
+        else if (outcome === "rejected") reject(0);
+      })();
+      await Promise.race([
+        work.catch(() => void 0),
+        new Promise((res) => {
+          deadline = setTimeout(res, limit);
+        })
+      ]);
+      if (deadline) clearTimeout(deadline);
+      stop.abort();
+      await Promise.race([work.catch(() => void 0), new Promise((r) => setTimeout(r, 50))]);
+      if (pending.length) {
+        st.failed += pending.length;
+        pending.length = 0;
+      }
+      finished = true;
+      return snapshot();
+    },
+    stats: snapshot
+  };
+}
+
 // src/sweep.ts
 var MAX_PER_SEARCH = 120;
 var MIN_PER_STEP = 40;
@@ -1942,6 +2206,8 @@ function parseArgs(list) {
     else if (arg === "--dedupe-across") a.dedupeAcross = next();
     else if (arg === "--enrich-out") a.enrichOut = next();
     else if (arg === "--config") a.config = next();
+    else if (arg === "--push") a.push = next();
+    else if (arg === "--push-token") a.pushToken = next();
     else if (arg === "--dedupe") a.dedupe = next();
     else if (arg === "--sort") a.sort = next();
     else if (arg === "--desc") a.desc = true;
@@ -2040,6 +2306,12 @@ ${c("bold", "Output")}
                         append, json stays valid, xlsx is rewritten), so stopping
                         early never loses what was collected
 
+${c("bold", "Push to a CRM / Lacspace Mail")}
+      --push <url>      Also POST finished leads (batches of 10 / every 3s) to this
+                        https endpoint while the file is written as usual
+      --push-token <t>  Bearer token for --push. Prefer the env var
+                        LACSPACE_LEADS_PUSH_TOKEN (shell history can't see it)
+
 ${c("bold", "Runtime")}
       --delay <ms>      Pause between listings    (default 700)
       --jitter          Randomise the delay \xB140% (more human)
@@ -2066,6 +2338,7 @@ ${c("bold", "Examples")}
   npx lacspace-leads gyms --city Lalitpur --dedupe-across master.csv -o new.csv --append
   npx lacspace-leads clinics --city Pokhara --enrich-out sites.ndjson   # feed lacspace-enrich
   npx lacspace-leads convert leads.json -f xlsx
+  LACSPACE_LEADS_PUSH_TOKEN=\u2026 npx lacspace-leads restaurants --city Kathmandu --target 300 --push https://api.lacspace.com/api/webmail/leads/import
 
 ${c("dim", "Please scrape responsibly: keep volumes small, respect Google's Terms of")}
 ${c("dim", "Service and local data-protection law, and use only public business data.")}
@@ -2079,6 +2352,43 @@ async function prompt(q, fallback = "") {
     rl.close();
   }
 }
+function setupPush(args, config) {
+  const p = resolvePush({ flagUrl: args.push, flagToken: args.pushToken, config: config?.push, env: process.env });
+  if (!p) {
+    if (args.pushToken) log(c("yellow", "  ! --push-token given without --push; ignoring it."));
+    return void 0;
+  }
+  try {
+    validatePushUrl(p.url);
+  } catch (err) {
+    log(c("red", `
+\u2717 ${err.message}
+`));
+    exit(1);
+  }
+  if (args.pushToken) log(c("yellow", "  ! --push-token is visible in shell history and the process list; prefer LACSPACE_LEADS_PUSH_TOKEN."));
+  return p;
+}
+function startPusher(p, file, search) {
+  const s = {};
+  if (search.type) s.type = search.type;
+  if (search.city) s.city = search.city;
+  if (search.area) s.area = search.area;
+  if (search.target !== void 0) s.target = search.target;
+  return createPusher({
+    url: p.url,
+    ...p.token ? { token: p.token } : {},
+    search: s,
+    file,
+    onWarn: (m) => log(c("yellow", `  ! ${m}`))
+  });
+}
+async function endPush(pusher, stats, timeoutMs) {
+  if (!pusher) return;
+  const st = await pusher.finish(stats, timeoutMs !== void 0 ? { timeoutMs } : void 0);
+  log(`  ${st.rejected || st.failed || st.dropped ? c("yellow", "!") : c("green", "\u2714")} ${c("dim", formatPushSummary(st))}`);
+}
+var pushEcho = (p) => `${maskUrl(p.url)}${p.token ? c("dim", " (token ***)") : c("dim", " (no token)")}`;
 async function runConvert(rest) {
   const a = parseArgs(rest);
   const input = rest.find((x) => !x.startsWith("-") && x !== a.format && x !== a.out && x !== a.sheet);
@@ -2134,6 +2444,8 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
     exit(1);
     return;
   }
+  const pushCfg = setupPush(args, config);
+  if (pushCfg) log(`  ${c("dim", "push")}    ${pushEcho(pushCfg)}`);
   log(`  ${c("dim", "searches")} ${config.searches.length}   ${c("dim", "format")} ${format}${config.append ? c("dim", "  (append)") : ""}${args.resume ? c("dim", "  (resume)") : ""}
 `);
   const out = resolve2(args.out ?? config.out ?? defaultFilename("leads-campaign", format));
@@ -2153,15 +2465,28 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
       saveCheckpoint(file, cp);
     };
   }
+  const uniq = (xs) => [...new Set(xs.map((x) => x?.trim()).filter((x) => !!x))].join(", ") || void 0;
+  const pusher = pushCfg ? startPusher(pushCfg, out, {
+    type: uniq(config.searches.map((q) => q.type ?? q.query)),
+    city: uniq(config.searches.map((q) => q.city)),
+    area: uniq(config.searches.map((q) => q.area)),
+    ...config.total !== void 0 ? { target: config.total } : {}
+  }) : void 0;
   const controller = new AbortController();
   const onSig = () => controller.abort();
   process.once("SIGINT", onSig);
   let leads;
   try {
-    leads = await runConfig(config, { signal: controller.signal, onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`), ...resumeHooks });
+    leads = await runConfig(config, {
+      signal: controller.signal,
+      onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`),
+      ...pusher ? { onResult: (l) => pusher.push(l) } : {},
+      ...resumeHooks
+    });
   } catch (err) {
     log(c("red", `
 \u2717 ${err.message}`));
+    await endPush(pusher, computeStats([]), 3e3);
     exit(1);
     return;
   } finally {
@@ -2170,6 +2495,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
   if (!leads.length) {
     log(c("yellow", "\n  No leads collected.\n"));
     if (cpFile) clearCheckpoint(cpFile);
+    await endPush(pusher, computeStats([]));
     return;
   }
   const fields = config.fields ? normalizeFields(config.fields) : ALL_FIELDS.filter((f) => leads.some((l) => l[f] !== void 0));
@@ -2209,6 +2535,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
   log(`
   ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}`);
   log(`    ${c("dim", `${s.withPhone} with a phone \xB7 ${s.withWebsite} with a website \xB7 ${s.withEmail} with an email`)}`);
+  await endPush(pusher, s);
   if (args.summary) {
     log("");
     formatSummary(summarize(leads)).split("\n").forEach((line, i) => {
@@ -2273,6 +2600,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
     exit(1);
     return;
   }
+  const pushCfg = setupPush(args);
   const nearPoint = args.near ? parseLatLngPair(args.near) : void 0;
   const tileStepM = args.step ? parseDistance(args.step) : void 0;
   if (!args.details && (args.split || args.noWebsite)) {
@@ -2367,6 +2695,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads"))} ${c("dim", "\u2014 Google Ma
   else if (nearPoint) log(`  ${c("dim", "sort")}    distance (nearest first)`);
   if (args.country) log(`  ${c("dim", "phones")}  E.164 for ${args.country}`);
   if (args.proxy) log(`  ${c("dim", "proxy")}   ${args.proxy.replace(/\/\/[^@]+@/, "//***@")}`);
+  if (pushCfg) log(`  ${c("dim", "push")}    ${pushEcho(pushCfg)} ${c("dim", "(the file is written as well)")}`);
   log(`  ${c("dim", "limit")}   ${args.limit}${isBatch ? "/search" : ""}${args.total ? ` (cap ${args.total})` : ""}   ${c("dim", "format")} ${args.format}   ${c("dim", "\u2192")} ${toStdout ? "stdout" : out}${args.append ? c("dim", " (append)") : ""}`);
   if (!args.yes) {
     const ok = await prompt(`
@@ -2382,12 +2711,19 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     if (controller.signal.aborted) {
       writerRef.current?.flush();
       log(c("yellow", "\n  ! Quit. Rows already written stay in the file; --resume continues from them.\n"));
+      if (pusherRef.current) {
+        const p = pusherRef.current;
+        pusherRef.current = void 0;
+        void endPush(p, computeStats([...writerRef.current?.leads ?? []]), 2e3).finally(() => exit(130));
+        return;
+      }
       exit(130);
     }
     controller.abort();
     log(c("yellow", "\n  ! Stopping \u2014 finishing the leads in hand. Press Ctrl-C again to quit at once (rows already written stay in the file)."));
   };
   const writerRef = {};
+  const pusherRef = {};
   process.on("SIGINT", onSig);
   let existing = [];
   if ((args.append || args.resume) && !toStdout && existsSync3(out)) {
@@ -2442,11 +2778,24 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     }
   }
   const goal = args.target ?? (isBatch ? args.total : void 0) ?? (isBatch ? void 0 : args.limit);
+  const pusher = pushCfg ? startPusher(pushCfg, toStdout ? "stdout" : out, {
+    ...args.type ? { type: args.type } : args.query ? { type: args.query } : {},
+    ...args.city ? { city: args.city } : {},
+    ...args.area ? { area: args.area } : {},
+    ...goal !== void 0 ? { target: goal } : {}
+  }) : void 0;
+  pusherRef.current = pusher;
+  const finishPush = async (list, timeoutMs) => {
+    const p = pusherRef.current;
+    pusherRef.current = void 0;
+    await endPush(p, computeStats(list), timeoutMs);
+  };
   const startedAt = Date.now();
   let fresh0 = 0;
   const onResult = (lead) => {
     if (inMaster?.(lead)) return;
     if (writer && !writer.add(lead)) return;
+    pusher?.push(lead);
     fresh0++;
     const have = resumeRows.length + fresh0;
     const mins = (Date.now() - startedAt) / 6e4;
@@ -2547,11 +2896,13 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   ! ${err.message}`));
       log(`  ${c("green", "\u2714")} ${c("bold", String(writer.count))} leads are saved in ${c("cyan", out)}. Run the same command with ${c("bold", "--resume")} to continue.
 `);
+      await finishPush([...writer.leads], 3e3);
       exit(controller.signal.aborted ? 130 : 1);
       return;
     }
     log(c("red", `
 \u2717 ${err.message}`));
+    await finishPush([], 3e3);
     exit(1);
     return;
   } finally {
@@ -2572,6 +2923,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     log(c("yellow", "\n  No leads collected. Try a broader area, looser filters, or a smaller --limit.\n"));
     dropEmpty();
     if (cpFile) clearCheckpoint(cpFile);
+    await finishPush([]);
     return;
   }
   if (master) {
@@ -2582,6 +2934,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
       log(c("yellow", "\n  Nothing new \u2014 every lead was already in the master file.\n"));
       dropEmpty();
       if (cpFile) clearCheckpoint(cpFile);
+      await finishPush([]);
       return;
     }
   }
@@ -2619,6 +2972,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     log(`
   ${c("green", "\u2714")} ${c("bold", String(leads.length))} leads written to stdout ${c("dim", `(${args.format})`)}
 `);
+    await finishPush(leads);
     printSummary();
     return;
   }
@@ -2653,6 +3007,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   if (s.avgRating !== void 0) parts.push(`avg \u2605 ${s.avgRating}`);
   log(`    ${c("dim", parts.join(" \xB7 "))}`);
   if (stoppedEarly) log(c("yellow", `  ! Stopped early. Run the same command with --resume to carry on from these ${leads.length}.`));
+  await finishPush(leads);
   printSummary();
   log("");
 }