diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1b1f146..4698da5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,7 +9,8 @@ on:
jobs:
terminal:
name: terminal wizard (no dependencies)
- runs-on: ubuntu-latest
+ # ubuntu-latest no longer offers Python 3.9, the oldest version the wizard supports
+ runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e806180..bef2e5b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,7 +1,7 @@
name: Release
# Bump VERSION in maplead/art.py, tag, push:
-# git tag v1.3.0 && git push origin v1.3.0
+# git tag v1.4.0 && git push origin v1.4.0
#
# A tag push builds the Linux AppImage only. The Windows job runs when the
# workflow is started by hand (workflow_dispatch).
@@ -67,20 +67,26 @@ jobs:
tag_name: ${{ github.event.inputs.tag || github.ref_name }}
name: ${{ steps.meta.outputs.name }}
body: |
- **MAPLEAD 1.3.1 — a social profile no longer counts as a website (Linux)**
-
- A lead whose website is only a social profile or link-in-bio page is now
- treated as having no website.
-
- **What's fixed**
-
- - **No website** now includes leads that only list a page such as Instagram,
- Facebook or Linktree, and **Has website** leaves them out. Their cards drop
- the *Website* chip, and the link button reads *Social*.
- - **Only leads with a website**, `--require-website` and the *with website*
- count follow the same rule, so a search with that option can return fewer
- leads than before.
- - **Bulk send** no longer crashes the AppImage on newer distros (e.g. Debian 13).
+ **MAPLEAD 1.4.0 — turbo mode (Linux)**
+
+ Turbo mode searches city by city and business by business, and sends your
+ WhatsApp message to every lead that passes your filter — with no clicks in
+ between.
+
+ **What's new**
+
+ - **Turbo mode** (under *Run search*, or `Ctrl+T`): tick the cities and the
+ business types, pick the filter (*No website* by default) and start. It
+ searches the first business type in the first city, messages the matching
+ leads through the bulk sender, moves to the next business type and, after
+ the last one, to the next city — until the lists end or you press **Stop**.
+ - The same safety pauses as **Bulk send**. Leads already messaged are never
+ messaged twice.
+ - Finished searches are remembered, so starting turbo mode again continues
+ where it stopped.
+ - Every search uses provider credits; the setup window shows how many
+ searches your lists add up to. Turbo mode does not run with the Demo
+ provider.
Full notes: https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md ·
guide: https://github.com/${{ github.repository }}/blob/main/docs/GUIDE.md
@@ -105,7 +111,7 @@ jobs:
windows:
name: build Windows x64
- # 1.3.0 ships for Linux only; build Windows by starting the workflow by hand
+ # 1.4.0 ships for Linux only; build Windows by starting the workflow by hand
if: github.event_name == 'workflow_dispatch'
runs-on: windows-latest
steps:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 810b1bc..b1ccf47 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,25 @@ All notable changes to MAPLEAD. Format follows [Keep a Changelog](https://keepac
## [Unreleased]
+## [1.4.0] — 2026-11-12
+
+Linux (AppImage) only — the Windows build and the terminal wizard are unchanged
+in this release.
+
+### Added
+- **Turbo mode** — a new **Turbo mode** button under *Run search* (`Ctrl+T`)
+ walks a list of cities and, in each one, a list of business types: it runs the
+ search, keeps the leads that pass the filter you chose (*No website* by
+ default), sends them your saved WhatsApp message through the bulk sender, then
+ moves to the next business type and, after the last one, to the next city —
+ until the lists end or you press **Stop**.
+ - Tick the cities and business types (or add your own), pick the filter, the
+ leads per search and the same safety pauses as **Bulk send**.
+ - Leads already messaged are never messaged twice, and finished searches are
+ remembered (`~/.local/share/maplead/turbo-progress.json`), so starting turbo
+ mode again continues where it stopped.
+ - Not available with the Demo provider: its phone numbers are made up.
+
## [1.3.1] — 2026-11-09
### Fixed
diff --git a/README.md b/README.md
index c79ba17..55540ed 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@ lead-scraper API and writes them to CSV / Excel / JSON / TXT / TSV / HTML.
| 🏷️ **68 business types · 35 fields** | you choose exactly which columns come out |
| 💬 **Leads panel + WhatsApp** | cards with one-click links and a first message built from the lead |
| 📨 **Bulk WhatsApp** | sends the message to a whole filter through WhatsApp Web, with safety pauses and a contact history |
+| ⚡ **Turbo mode** | searches city by city and business by business, and messages every lead that passes your filter |
| 📄 **6 export formats** | csv · xlsx · json · txt · tsv · html |
@@ -33,8 +34,8 @@ lead-scraper API and writes them to CSV / Excel / JSON / TXT / TSV / HTML.
**Linux x86_64, AppImage** — one file, no packages, no root:
```bash
-chmod +x MAPLEAD-1.3.1-x86_64.AppImage
-./MAPLEAD-1.3.1-x86_64.AppImage
+chmod +x MAPLEAD-1.4.0-x86_64.AppImage
+./MAPLEAD-1.4.0-x86_64.AppImage
```
Building it yourself (also fine for arm64/other distros with a rebuild):
@@ -132,6 +133,22 @@ Details and the safety settings: [docs/GUIDE.md › Bulk WhatsApp](docs/GUIDE.md
+## 6 · Turbo mode (Linux)
+
+**Turbo mode** (under *Run search*, or `Ctrl+T`) does the search and the bulk
+send by itself, for a whole list of cities and business types:
+
+1. tick the cities and the business types, pick the filter (*No website* by
+ default) and the safety pauses;
+2. it searches the first business type in the first city, sends your saved
+ message to every lead that passes the filter, then moves to the next business
+ type — and, after the last one, to the next city;
+3. it ends when the lists do, or when you press **Stop**. Starting it again
+ continues where it stopped, and nobody is messaged twice.
+
+Every search uses provider credits. Details:
+[docs/GUIDE.md › Turbo mode](docs/GUIDE.md#turbo-mode).
+
---
## Terminal wizard
@@ -183,9 +200,9 @@ On Linux the wizard is inside the AppImage — the same file as the desktop app,
nothing has to be installed first either:
```bash
-./MAPLEAD-1.3.1-x86_64.AppImage --cli --demo
-./MAPLEAD-1.3.1-x86_64.AppImage --cli --country DE --city Berlin --business dentist
-./MAPLEAD-1.3.1-x86_64.AppImage --cli --doctor
+./MAPLEAD-1.4.0-x86_64.AppImage --cli --demo
+./MAPLEAD-1.4.0-x86_64.AppImage --cli --country DE --city Berlin --business dentist
+./MAPLEAD-1.4.0-x86_64.AppImage --cli --doctor
```
You can add `~/.local/bin/maplead-cli` yourself (`#!/bin/sh` + `exec "$HOME/Apps"/MAPLEAD-*-x86_64.AppImage --cli "$@"`)
diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 2505bf1..2da9487 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -20,11 +20,11 @@ New here? Read this once, then the [README](../README.md) is just a reminder.
### Linux x86_64
-Download `MAPLEAD-1.3.1-x86_64.AppImage`, then:
+Download `MAPLEAD-1.4.0-x86_64.AppImage`, then:
```bash
-chmod +x MAPLEAD-1.3.1-x86_64.AppImage # first time only
-./MAPLEAD-1.3.1-x86_64.AppImage
+chmod +x MAPLEAD-1.4.0-x86_64.AppImage # first time only
+./MAPLEAD-1.4.0-x86_64.AppImage
```
After `./build-appimage.sh --install` you can also just type `maplead`, and the app
@@ -36,7 +36,7 @@ only things it expects from the system are a display and the usual C library.
The same file runs the terminal wizard too — no Python needed:
```bash
-./MAPLEAD-1.3.1-x86_64.AppImage --cli --demo
+./MAPLEAD-1.4.0-x86_64.AppImage --cli --demo
```
**No FUSE?** Older AppImages mount themselves through `libfuse.so.2`. If your system
@@ -216,6 +216,39 @@ Windows); contacted leads show a *Contacted* chip and are skipped by default.
> the risk of the number being restricted; they do not remove it. Use a number
> dedicated to prospecting.
+### Turbo mode
+
+**Turbo mode** (under *Run search*, or `Ctrl+T`) runs the search and the bulk
+send by itself for a list of cities and a list of business types. It uses the
+provider, country, region and fields of the search form, and the WhatsApp
+message saved in the leads panel. It needs a provider with an API key: the Demo
+provider returns made-up phone numbers, so turbo mode refuses it.
+
+1. Tick the **cities** and the **business types** to go through, in the order
+ listed. *Add* puts your own entry at the top of a list.
+2. Choose **who gets the message**: the *Lead filter* (*No website*, *Has
+ website*, *Has e-mail* or *Every lead with WhatsApp*) and the *Leads per
+ search*. The **Safety** settings are the ones Bulk WhatsApp uses.
+3. **Start turbo** opens WhatsApp Web inside MAPLEAD, then repeats: search one
+ business type in one city, keep the leads that pass the filter, send them the
+ message with the safety pauses, go to the next business type — and, after the
+ last one, to the next city. Each search also shows up in the results grid.
+4. It ends after the last business type of the last city, or when you press
+ **Stop**. **Pause** and **Skip lead** work as in Bulk WhatsApp.
+
+The footer of the setup window shows how many searches the lists add up to.
+Every search uses provider credits, so start with a few cities and business
+types.
+
+Leads already messaged are never messaged again. Finished searches are
+remembered in `turbo-progress.json` in the data folder, so starting turbo mode
+again continues where it stopped; *Forget* in the setup window clears that
+memory. With the default safety settings the run stops and asks every 25
+messages and at 50 messages a day — set *Ask after* and *Daily limit* to 0 to
+let it run unattended, at a higher risk of WhatsApp restricting the number.
+After three failed searches in a row (for example a rejected API key) the run
+stops by itself.
+
## 7 · The export file
A search **never writes a file by itself**. Results stay in the grid and in the
@@ -250,7 +283,7 @@ The original interface, still fully supported and dependency-free:
Without Python, the packaged builds carry the same wizard:
```bash
-./MAPLEAD-1.3.1-x86_64.AppImage --cli --demo # Linux: the AppImage is both
+./MAPLEAD-1.4.0-x86_64.AppImage --cli --demo # Linux: the AppImage is both
.\MAPLEAD-1.2.0-windows-x64.exe --cli --demo # Windows: same trick, one .exe
```
diff --git a/maplead/art.py b/maplead/art.py
index 7eec6d6..9f5b101 100644
--- a/maplead/art.py
+++ b/maplead/art.py
@@ -10,7 +10,7 @@
from . import host
-VERSION = "1.3.1"
+VERSION = "1.4.0"
# --------------------------------------------------------------------------- #
# colour plumbing
diff --git a/maplead/gui/bulk_sender.py b/maplead/gui/bulk_sender.py
index 0511add..e7a4d08 100644
--- a/maplead/gui/bulk_sender.py
+++ b/maplead/gui/bulk_sender.py
@@ -174,6 +174,74 @@ def _profile():
return profile
+# --------------------------------------------------------------------------- #
+# the safety settings card (shared by the bulk and the turbo setup dialogs)
+# --------------------------------------------------------------------------- #
+
+class SafetyForm(QFrame):
+ """The "Safety" card: pauses, rests, the "continue?" threshold, the daily cap."""
+
+ changed = Signal()
+
+ def __init__(self, settings: outreach.SafetySettings,
+ parent: Optional[QWidget] = None):
+ super().__init__(parent)
+ outer = QVBoxLayout(self)
+ outer.setContentsMargins(0, 0, 0, 0)
+ safety_card, sc = card("Safety")
+ grid = QGridLayout()
+ grid.setHorizontalSpacing(10)
+ grid.setVerticalSpacing(6)
+ s = settings
+ self.min_delay = self._spin(5, 3600, s.min_delay, " s")
+ self.max_delay = self._spin(5, 3600, s.max_delay, " s")
+ self.burst_size = self._spin(0, 500, s.burst_size, " msgs")
+ self.burst_rest = self._spin(0, 240, s.burst_rest // 60, " min")
+ self.warn_after = self._spin(0, 1000, s.warn_after, " msgs")
+ self.daily_limit = self._spin(0, 2000, s.daily_limit, " msgs")
+ rows = (
+ ("Pause from", self.min_delay, "Shortest random pause between two messages"),
+ ("Pause up to", self.max_delay, "Longest random pause between two messages"),
+ ("Rest every", self.burst_size, "After this many messages, take a longer rest (0 = never)"),
+ ("Rest for", self.burst_rest, "Length of that rest"),
+ ("Ask after", self.warn_after,
+ "Stop and ask whether to continue every time this many messages went out (0 = never)"),
+ ("Daily limit", self.daily_limit,
+ "Ask before going over this many messages today (0 = no limit)"),
+ )
+ for i, (label, spin, tip) in enumerate(rows):
+ grid.addWidget(field_label(label, tip), i // 2, (i % 2) * 2)
+ spin.setToolTip(tip)
+ spin.valueChanged.connect(lambda _=0: self.changed.emit())
+ grid.addWidget(spin, i // 2, (i % 2) * 2 + 1)
+ sc.addLayout(grid)
+ risk = QLabel("Automated messages go against WhatsApp's terms. The pauses "
+ "lower the risk of the number being restricted, they do not "
+ "remove it — prefer a number used only for prospecting.")
+ risk.setObjectName("hint")
+ risk.setWordWrap(True)
+ sc.addWidget(risk)
+ outer.addWidget(safety_card)
+
+ @staticmethod
+ def _spin(lo: int, hi: int, value: int, suffix: str) -> QSpinBox:
+ spin = QSpinBox()
+ spin.setRange(lo, hi)
+ spin.setValue(max(lo, min(hi, int(value))))
+ spin.setSuffix(suffix)
+ return spin
+
+ def value(self) -> outreach.SafetySettings:
+ return outreach.SafetySettings(
+ min_delay=self.min_delay.value(),
+ max_delay=self.max_delay.value(),
+ burst_size=self.burst_size.value(),
+ burst_rest=self.burst_rest.value() * 60,
+ warn_after=self.warn_after.value(),
+ daily_limit=self.daily_limit.value(),
+ ).normalized()
+
+
# --------------------------------------------------------------------------- #
# setup dialog: pick the leads and the safety settings
# --------------------------------------------------------------------------- #
@@ -272,40 +340,9 @@ def __init__(self, leads: Sequence[Dict[str, Any]], palette: Palette, *,
pc.addWidget(self.preview)
sl.addWidget(preview_card, 1)
- safety_card, sc = card("Safety")
- grid = QGridLayout()
- grid.setHorizontalSpacing(10)
- grid.setVerticalSpacing(6)
- s = self.safety
- self.min_delay = self._spin(5, 3600, s.min_delay, " s")
- self.max_delay = self._spin(5, 3600, s.max_delay, " s")
- self.burst_size = self._spin(0, 500, s.burst_size, " msgs")
- self.burst_rest = self._spin(0, 240, s.burst_rest // 60, " min")
- self.warn_after = self._spin(0, 1000, s.warn_after, " msgs")
- self.daily_limit = self._spin(0, 2000, s.daily_limit, " msgs")
- rows = (
- ("Pause from", self.min_delay, "Shortest random pause between two messages"),
- ("Pause up to", self.max_delay, "Longest random pause between two messages"),
- ("Rest every", self.burst_size, "After this many messages, take a longer rest (0 = never)"),
- ("Rest for", self.burst_rest, "Length of that rest"),
- ("Ask after", self.warn_after,
- "Stop and ask whether to continue every time this many messages went out (0 = never)"),
- ("Daily limit", self.daily_limit,
- "Ask before going over this many messages today (0 = no limit)"),
- )
- for i, (label, spin, tip) in enumerate(rows):
- grid.addWidget(field_label(label, tip), i // 2, (i % 2) * 2)
- spin.setToolTip(tip)
- spin.valueChanged.connect(self._sync_footer)
- grid.addWidget(spin, i // 2, (i % 2) * 2 + 1)
- sc.addLayout(grid)
- risk = QLabel("Automated messages go against WhatsApp's terms. The pauses "
- "lower the risk of the number being restricted, they do not "
- "remove it — prefer a number used only for prospecting.")
- risk.setObjectName("hint")
- risk.setWordWrap(True)
- sc.addWidget(risk)
- sl.addWidget(safety_card)
+ self.safety_form = SafetyForm(self.safety)
+ self.safety_form.changed.connect(self._sync_footer)
+ sl.addWidget(self.safety_form)
split.addWidget(side)
split.setStretchFactor(0, 3)
split.setStretchFactor(1, 2)
@@ -332,14 +369,6 @@ def __init__(self, leads: Sequence[Dict[str, Any]], palette: Palette, *,
self._fill()
# -- building -------------------------------------------------------------
- @staticmethod
- def _spin(lo: int, hi: int, value: int, suffix: str) -> QSpinBox:
- spin = QSpinBox()
- spin.setRange(lo, hi)
- spin.setValue(max(lo, min(hi, int(value))))
- spin.setSuffix(suffix)
- return spin
-
def _template(self) -> str:
from .lead_panel import load_message_template
return load_message_template()
@@ -417,14 +446,7 @@ def _sync_preview(self) -> None:
self.preview.setPlainText("No lead with a WhatsApp number in this filter.")
def current_safety(self) -> outreach.SafetySettings:
- return outreach.SafetySettings(
- min_delay=self.min_delay.value(),
- max_delay=self.max_delay.value(),
- burst_size=self.burst_size.value(),
- burst_rest=self.burst_rest.value() * 60,
- warn_after=self.warn_after.value(),
- daily_limit=self.daily_limit.value(),
- ).normalized()
+ return self.safety_form.value()
def _sync_footer(self, *_: Any) -> None:
chosen = self._checked()
@@ -580,11 +602,33 @@ def __init__(self, items: Sequence[outreach.OutreachItem],
self.timer.timeout.connect(self._tick)
self._sync_counts()
- self.log.write(f"{len(self.items)} lead(s) queued · pause "
- f"{self.safety.min_delay}-{self.safety.max_delay} s · rest "
- f"{self.safety.burst_rest // 60} min every "
- f"{self.safety.burst_size or '∞'} · ask after "
- f"{self.safety.warn_after or '∞'}", "info")
+ self._log_intro()
+
+ def _safety_summary(self) -> str:
+ return (f"pause {self.safety.min_delay}-{self.safety.max_delay} s · rest "
+ f"{self.safety.burst_rest // 60} min every "
+ f"{self.safety.burst_size or '∞'} · ask after "
+ f"{self.safety.warn_after or '∞'}")
+
+ def _log_intro(self) -> None:
+ self.log.write(f"{len(self.items)} lead(s) queued · "
+ + self._safety_summary(), "info")
+
+ # -- hooks for a sender whose queue grows while it runs (turbo mode) -------
+ def _more_coming(self) -> bool:
+ """True when more leads may be queued after the last one."""
+ return False
+
+ def _queue_exhausted(self) -> None:
+ """Called when it is time for the next lead and the queue is empty."""
+ self._done("All leads handled")
+
+ def _extend_items(self, items: Sequence[outreach.OutreachItem]) -> None:
+ for item in items:
+ item.status = ""
+ self.items.append(item)
+ self.progress.setRange(0, max(1, len(self.items)))
+ self._sync_counts()
# -- lifecycle ------------------------------------------------------------
def start(self) -> None:
@@ -628,7 +672,7 @@ def _tick(self) -> None:
return
self._remaining -= 1
nxt = self._next_index()
- who = self.items[nxt].name if nxt is not None else ""
+ who = self.items[nxt].name if nxt is not None else "new search"
self.detail_label.setText(
f"{self._wait_reason.capitalize()} · next: {who} in "
f"{outreach.format_duration(self._remaining)}")
@@ -716,7 +760,7 @@ def _next_index(self) -> Optional[int]:
def _open_next(self) -> None:
nxt = self._next_index()
if nxt is None:
- self._done("All leads handled")
+ self._queue_exhausted()
return
# daily cap: ask once per run before going over it
if (not self._daily_ok
@@ -766,8 +810,8 @@ def _finish(self, status: str, error: str = "") -> None:
self.log.write(f" {label}" + (f" — {error}" if error else ""), level)
self._sync_counts()
- if self._next_index() is None:
- self._done("All leads handled")
+ if self._next_index() is None and not self._more_coming():
+ self._queue_exhausted()
return
if status == outreach.SENT:
diff --git a/maplead/gui/icons.py b/maplead/gui/icons.py
index 11642f0..67f1f60 100644
--- a/maplead/gui/icons.py
+++ b/maplead/gui/icons.py
@@ -28,6 +28,7 @@
# --- navigation / actions -------------------------------------------- #
"play": _FILL.format(color="{color}", body=''),
"stop": _FILL.format(color="{color}", body=''),
+ "bolt": _FILL.format(color="{color}", body=''),
"search": _STROKE.format(color="{color}", body=''
''),
"refresh": _STROKE.format(color="{color}", body=''
diff --git a/maplead/gui/main_window.py b/maplead/gui/main_window.py
index 9eec34a..da17c4e 100644
--- a/maplead/gui/main_window.py
+++ b/maplead/gui/main_window.py
@@ -20,7 +20,7 @@
QSpinBox, QSplitter, QToolButton, QVBoxLayout,
QWidget)
-from .. import contacts, exporters, paths
+from .. import contacts, exporters, paths, turbo
from ..art import VERSION
from ..data import cities as CI
from ..data import countries as CO
@@ -71,6 +71,7 @@ def __init__(self, palette: Palette):
self._run_spec: Optional[SearchSpec] = None
self._last_result: Optional[RunResult] = None
self._panel: Optional[LeadsPanel] = None
+ self._turbo = None
self._build()
self._restore_state()
@@ -365,6 +366,14 @@ def _build_runbar(self) -> QWidget:
self.run_btn.setIcon(icons.icon("play", self.p.accent_text, 15))
self.run_btn.clicked.connect(self.toggle_run)
lay.addWidget(self.run_btn)
+
+ self.turbo_btn = QPushButton(" Turbo mode")
+ self.turbo_btn.setIcon(icons.icon("bolt", self.p.text_dim, 15))
+ self.turbo_btn.setToolTip(
+ "Search city by city and business by business, and send the saved "
+ "WhatsApp message to every lead that passes your filter (Ctrl+T)")
+ self.turbo_btn.clicked.connect(self.open_turbo)
+ lay.addWidget(self.turbo_btn)
bar.setMinimumHeight(bar.sizeHint().height())
return bar
@@ -744,9 +753,8 @@ def _on_landline_toggled(self, checked: bool) -> None:
def spec(self) -> SearchSpec:
country = self.country_combo.value()
- text = self.business_combo.currentText().strip()
- hits = VT.resolve(text)
- vertical = hits[0] if hits else None
+ business_label, terms = turbo.business_terms(
+ self.business_combo.currentText())
provider = self.provider_combo.value() or "demo"
fmt = self.format_combo.currentData() or "csv"
region = self.region_combo.currentText().strip()
@@ -758,8 +766,8 @@ def spec(self) -> SearchSpec:
country=country,
region=region,
city=city,
- business_label=vertical.label if vertical else text,
- terms=[vertical.query] + list(vertical.synonyms[:2]) if vertical else [text],
+ business_label=business_label,
+ terms=terms,
fields=list(self._fields),
limit=self.limit_spin.value(),
language=(country.lang if country else "en"),
@@ -821,6 +829,49 @@ def _sync_run_button(self) -> None:
self.run_btn.style().unpolish(self.run_btn)
self.run_btn.style().polish(self.run_btn)
+ # -- turbo mode ----------------------------------------------------------
+ def open_turbo(self) -> None:
+ """City by city, business by business: search, filter, message."""
+ if self._turbo is not None and self._turbo.is_running():
+ self._turbo.showNormal()
+ self._turbo.raise_()
+ self._turbo.activateWindow()
+ return
+ spec = self.spec()
+ if spec.country is None:
+ QMessageBox.warning(self, "Turbo mode", "Pick a country first.")
+ return
+ if spec.provider_name == "demo":
+ QMessageBox.warning(
+ self, "Turbo mode",
+ "Turbo mode sends real WhatsApp messages, and the Demo provider "
+ "returns made-up phone numbers that may belong to real people."
+ "\n\nPick a provider with an API key first.")
+ return
+ if not PROVIDERS[spec.provider_name].is_configured():
+ QMessageBox.warning(
+ self, "Turbo mode",
+ f"{PROVIDERS[spec.provider_name].label} has no API key — "
+ "open API keys first.")
+ return
+ from .turbo import open_turbo
+ window = open_turbo(spec, self.p, parent=self)
+ if window is None:
+ return
+ self._turbo = window
+ window.batch_ready.connect(self._on_turbo_batch)
+ window.destroyed.connect(lambda *_: setattr(self, "_turbo", None))
+ self.log.write(f"Turbo mode started — {len(window.steps)} searches queued.",
+ "ok")
+
+ def _on_turbo_batch(self, spec: SearchSpec, result: RunResult) -> None:
+ """Show each turbo search in the grid, unless a manual search is running."""
+ if self._thread is not None and self._thread.isRunning():
+ return
+ self._run_spec = spec
+ self.log.write(f"Turbo: {spec.business_label} in {spec.city}", "query")
+ self._on_finished(result)
+
# -- run / stop ----------------------------------------------------------
def toggle_run(self) -> None:
if self._thread is not None and self._thread.isRunning():
@@ -1102,6 +1153,10 @@ def _build_menu(self) -> None:
self.act_run.setShortcut(QKeySequence("Ctrl+R"))
self.act_run.triggered.connect(self.toggle_run)
+ self.act_turbo = QAction("T&urbo mode…", self)
+ self.act_turbo.setShortcut(QKeySequence("Ctrl+T"))
+ self.act_turbo.triggered.connect(self.open_turbo)
+
self.act_panel = QAction("&Leads panel", self)
self.act_panel.setShortcut(QKeySequence("Ctrl+P"))
self.act_panel.setEnabled(False)
@@ -1120,6 +1175,7 @@ def _build_menu(self) -> None:
menu = bar.addMenu("&MAPLEAD")
menu.addAction(self.act_run)
+ menu.addAction(self.act_turbo)
menu.addAction(self.act_panel)
menu.addAction(self.act_export)
menu.addSeparator()
diff --git a/maplead/gui/turbo.py b/maplead/gui/turbo.py
new file mode 100644
index 0000000..4267c5d
--- /dev/null
+++ b/maplead/gui/turbo.py
@@ -0,0 +1,607 @@
+"""
+Turbo mode: search city by city, business by business, and message every match.
+
+Two windows, built on the bulk sender (nothing about WhatsApp Web is redone here):
+
+* :class:`TurboSetupDialog` — tick the cities and the business types, pick the
+ lead filter (*No website* by default), the leads per search and the safety
+ settings. The message is the one saved in the leads panel.
+* :class:`TurboWindow` — a :class:`~maplead.gui.bulk_sender.WhatsAppSenderWindow`
+ whose queue refills itself: when the leads of one (city, business) search are
+ all handled it runs the next search, filters the result, queues the leads not
+ contacted yet and keeps sending. It ends after the last business of the last
+ city, or when the user stops it.
+
+The order of the steps, the filter and the "already done" memory are in
+``maplead/turbo.py``.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from PySide6.QtCore import QSettings, Qt, QThread, Signal
+from PySide6.QtWidgets import (QCheckBox, QComboBox, QDialog, QFrame,
+ QHBoxLayout, QLabel, QLineEdit, QListWidget,
+ QListWidgetItem, QMessageBox, QPlainTextEdit,
+ QPushButton, QSpinBox, QSplitter, QVBoxLayout,
+ QWidget)
+
+from .. import outreach, turbo
+from ..data import cities as CI
+from ..data import fields as FD
+from ..data import verticals as VT
+from ..providers import PROVIDERS
+from . import icons
+from .bulk_sender import (SafetyForm, WhatsAppSenderWindow, load_safety,
+ save_safety, webengine_available)
+from .theme import Palette
+from .widgets import card, field_label
+from .worker import HarvestWorker, RunResult, SearchSpec
+
+_SETTINGS_ORG = "maplead"
+_SETTINGS_APP = "maplead-desktop"
+_SETUP_KEY = "turbo/setup"
+
+# the columns a turbo search always asks for: the filter and the message need them
+_NEEDED_FIELDS = ("name", "category", "city", "phone", "website", "whatsapp", "email")
+
+MAX_SEARCH_FAILURES = 3 # in a row, before the run gives up
+
+
+def _load_setup() -> Dict[str, Any]:
+ value = QSettings(_SETTINGS_ORG, _SETTINGS_APP).value(_SETUP_KEY, "")
+ try:
+ data = json.loads(str(value)) if value else {}
+ except ValueError:
+ data = {}
+ return data if isinstance(data, dict) else {}
+
+
+def _save_setup(data: Dict[str, Any]) -> None:
+ store = QSettings(_SETTINGS_ORG, _SETTINGS_APP)
+ store.setValue(_SETUP_KEY, json.dumps(data))
+ store.sync()
+
+
+# --------------------------------------------------------------------------- #
+# a checklist with All / None and a box to add your own entry
+# --------------------------------------------------------------------------- #
+
+class _Checklist(QFrame):
+ changed = Signal()
+
+ def __init__(self, title: str, placeholder: str,
+ parent: Optional[QWidget] = None):
+ super().__init__(parent)
+ self._names: set = set()
+ outer = QVBoxLayout(self)
+ outer.setContentsMargins(0, 0, 0, 0)
+ frame, lay = card(title)
+
+ tools = QHBoxLayout()
+ tools.setSpacing(6)
+ for label, state in (("All", Qt.Checked), ("None", Qt.Unchecked)):
+ button = QPushButton(label)
+ button.setProperty("flat", True)
+ button.clicked.connect(lambda _=False, s=state: self._tick_all(s))
+ tools.addWidget(button)
+ tools.addStretch(1)
+ self.count_label = QLabel("")
+ self.count_label.setObjectName("hint")
+ tools.addWidget(self.count_label)
+ lay.addLayout(tools)
+
+ self.list = QListWidget()
+ self.list.itemChanged.connect(self._on_changed)
+ lay.addWidget(self.list, 1)
+
+ add_row = QHBoxLayout()
+ add_row.setSpacing(6)
+ self.add_edit = QLineEdit()
+ self.add_edit.setPlaceholderText(placeholder)
+ self.add_edit.returnPressed.connect(self._add_typed)
+ add_row.addWidget(self.add_edit, 1)
+ add_btn = QPushButton("Add")
+ add_btn.clicked.connect(self._add_typed)
+ add_row.addWidget(add_btn)
+ lay.addLayout(add_row)
+ outer.addWidget(frame)
+
+ def add(self, text: str, data: Any = None, checked: bool = True,
+ top: bool = False) -> bool:
+ """Append an entry; call :meth:`refresh` once the batch is in."""
+ text = (text or "").strip()
+ if not text or text.lower() in self._names:
+ return False
+ self._names.add(text.lower())
+ item = QListWidgetItem(text)
+ item.setFlags(Qt.ItemIsUserCheckable | Qt.ItemIsEnabled | Qt.ItemIsSelectable)
+ item.setData(Qt.UserRole, data)
+ self.list.blockSignals(True)
+ item.setCheckState(Qt.Checked if checked else Qt.Unchecked)
+ if top:
+ self.list.insertItem(0, item)
+ else:
+ self.list.addItem(item)
+ self.list.blockSignals(False)
+ return True
+
+ def refresh(self) -> None:
+ self._on_changed()
+
+ def entries(self, checked_only: bool = True) -> List[Tuple[str, Any]]:
+ out: List[Tuple[str, Any]] = []
+ for row in range(self.list.count()):
+ item = self.list.item(row)
+ if not checked_only or item.checkState() == Qt.Checked:
+ out.append((item.text(), item.data(Qt.UserRole)))
+ return out
+
+ def unchecked(self) -> List[str]:
+ return [self.list.item(r).text() for r in range(self.list.count())
+ if self.list.item(r).checkState() != Qt.Checked]
+
+ def _tick_all(self, state: Qt.CheckState) -> None:
+ self.list.blockSignals(True)
+ for row in range(self.list.count()):
+ self.list.item(row).setCheckState(state)
+ self.list.blockSignals(False)
+ self._on_changed()
+
+ def _add_typed(self) -> None:
+ text = self.add_edit.text().strip()
+ if text:
+ self.add(text, data="custom", top=True)
+ self.add_edit.clear()
+ self.refresh()
+
+ def _on_changed(self, *_: Any) -> None:
+ self.count_label.setText(
+ f"{len(self.entries())} of {self.list.count()} selected")
+ self.changed.emit()
+
+
+# --------------------------------------------------------------------------- #
+# setup dialog
+# --------------------------------------------------------------------------- #
+
+class TurboSetupDialog(QDialog):
+ """Choose the cities, the business types, the filter and the pacing."""
+
+ def __init__(self, base: SearchSpec, palette: Palette, *,
+ parent: Optional[QWidget] = None):
+ super().__init__(parent)
+ self.p = palette
+ self.base = base
+ self._iso = base.country.iso if base.country else ""
+ self.progress = turbo.Progress()
+ self.safety = load_safety()
+ self.steps: List[turbo.Step] = []
+ self.filter_key = turbo.DEFAULT_FILTER
+ self.limit = base.limit
+ saved = _load_setup()
+ per_country = saved.get("countries", {}).get(self._iso, {}) \
+ if isinstance(saved.get("countries"), dict) else {}
+
+ self.setWindowTitle("MAPLEAD — turbo mode")
+ self.setMinimumSize(900, 640)
+ self.resize(1120, 760)
+ self.setSizeGripEnabled(True)
+
+ root = QVBoxLayout(self)
+ root.setContentsMargins(16, 16, 16, 12)
+ root.setSpacing(12)
+
+ # header -------------------------------------------------------------
+ header = QFrame()
+ header.setObjectName("panelHeader")
+ hl = QHBoxLayout(header)
+ hl.setContentsMargins(16, 12, 16, 12)
+ titles = QVBoxLayout()
+ titles.setSpacing(1)
+ title = QLabel("TURBO MODE")
+ title.setObjectName("panelTitle")
+ titles.addWidget(title)
+ where = ", ".join(p for p in (base.region,
+ base.country.name if base.country else "") if p)
+ provider = PROVIDERS[base.provider_name].label \
+ if base.provider_name in PROVIDERS else base.provider_name
+ sub = QLabel(" · ".join(p for p in (where, provider) if p))
+ sub.setObjectName("panelSub")
+ titles.addWidget(sub)
+ hl.addLayout(titles)
+ hl.addStretch(1)
+ message_btn = QPushButton(" Edit message")
+ message_btn.setIcon(icons.icon("chat", self.p.text_dim, 15))
+ message_btn.clicked.connect(self._edit_template)
+ hl.addWidget(message_btn)
+ root.addWidget(header)
+
+ # lists + options ------------------------------------------------------
+ split = QSplitter(Qt.Horizontal)
+ split.setChildrenCollapsible(False)
+
+ self.cities = _Checklist("Cities, in this order", "add a city")
+ off = {str(c).lower() for c in per_country.get("cities_off", [])}
+ for city, region in CI.candidates(self._iso, base.region):
+ self.cities.add(city, data=region, checked=city.lower() not in off)
+ for city in per_country.get("custom_cities", []):
+ self.cities.add(str(city), data="custom", top=True,
+ checked=str(city).lower() not in off)
+ if base.city:
+ self.cities.add(base.city, data=base.region, top=True)
+ self.cities.refresh()
+ split.addWidget(self.cities)
+
+ self.businesses = _Checklist("Business types, in this order",
+ "add a business type")
+ off = {str(b).lower() for b in saved.get("businesses_off", [])}
+ for vertical in VT.VERTICALS:
+ self.businesses.add(vertical.label, checked=vertical.label.lower() not in off)
+ for business in saved.get("custom_businesses", []):
+ self.businesses.add(str(business), data="custom", top=True,
+ checked=str(business).lower() not in off)
+ self.businesses.refresh()
+ split.addWidget(self.businesses)
+
+ side = QWidget()
+ sl = QVBoxLayout(side)
+ sl.setContentsMargins(0, 0, 0, 0)
+ sl.setSpacing(12)
+
+ run_card, rc = card("Who gets the message")
+ tip = "Only the leads that pass this filter are messaged"
+ rc.addWidget(field_label("Lead filter", tip))
+ self.filter_combo = QComboBox()
+ self.filter_combo.setToolTip(tip)
+ for key, label in turbo.FILTERS:
+ self.filter_combo.addItem(label, key)
+ index = self.filter_combo.findData(saved.get("filter", turbo.DEFAULT_FILTER))
+ self.filter_combo.setCurrentIndex(max(0, index))
+ self.filter_combo.currentIndexChanged.connect(self._sync_footer)
+ rc.addWidget(self.filter_combo)
+ tip = "How many leads each search (one business type in one city) collects"
+ rc.addWidget(field_label("Leads per search", tip))
+ self.limit_spin = QSpinBox()
+ self.limit_spin.setRange(1, 100_000)
+ self.limit_spin.setSingleStep(10)
+ self.limit_spin.setSuffix(" leads")
+ self.limit_spin.setToolTip(tip)
+ try:
+ self.limit_spin.setValue(int(saved.get("limit", base.limit)))
+ except (TypeError, ValueError):
+ self.limit_spin.setValue(base.limit)
+ rc.addWidget(self.limit_spin)
+ resume = QHBoxLayout()
+ resume.setSpacing(6)
+ self.skip_done = QCheckBox("Skip searches already finished")
+ self.skip_done.setToolTip("Continue where the last turbo run stopped instead "
+ "of running the same searches again")
+ self.skip_done.setChecked(bool(saved.get("skip_done", True)))
+ self.skip_done.toggled.connect(self._sync_footer)
+ resume.addWidget(self.skip_done, 1)
+ reset = QPushButton("Forget")
+ reset.setProperty("flat", True)
+ reset.setToolTip("Forget which searches were already finished")
+ reset.clicked.connect(self._reset_progress)
+ resume.addWidget(reset)
+ rc.addLayout(resume)
+ note = QLabel("Leads already messaged are always skipped.")
+ note.setObjectName("hint")
+ note.setWordWrap(True)
+ rc.addWidget(note)
+ sl.addWidget(run_card)
+
+ preview_card, pc = card("Message")
+ self.preview = QPlainTextEdit()
+ self.preview.setReadOnly(True)
+ self.preview.setMinimumHeight(90)
+ pc.addWidget(self.preview)
+ sl.addWidget(preview_card, 1)
+
+ self.safety_form = SafetyForm(self.safety)
+ self.safety_form.changed.connect(self._sync_footer)
+ sl.addWidget(self.safety_form)
+ split.addWidget(side)
+ split.setStretchFactor(0, 2)
+ split.setStretchFactor(1, 2)
+ split.setStretchFactor(2, 3)
+ split.setSizes([310, 310, 440])
+ root.addWidget(split, 1)
+
+ # footer ---------------------------------------------------------------
+ footer = QHBoxLayout()
+ footer.setSpacing(10)
+ self.summary = QLabel("")
+ self.summary.setObjectName("hint")
+ self.summary.setWordWrap(True)
+ footer.addWidget(self.summary, 1)
+ cancel = QPushButton("Cancel")
+ cancel.clicked.connect(self.reject)
+ footer.addWidget(cancel)
+ self.start_btn = QPushButton(" Start turbo")
+ self.start_btn.setProperty("accent", True)
+ self.start_btn.setIcon(icons.icon("play", self.p.accent_text, 13))
+ self.start_btn.clicked.connect(self.accept)
+ footer.addWidget(self.start_btn)
+ root.addLayout(footer)
+
+ self.cities.changed.connect(self._sync_footer)
+ self.businesses.changed.connect(self._sync_footer)
+ self._sync_preview()
+ self._sync_footer()
+
+ # -- state ------------------------------------------------------------------
+ def _all_steps(self) -> List[turbo.Step]:
+ cities = [(name, "" if region == "custom" else (region or self.base.region))
+ for name, region in self.cities.entries()]
+ return turbo.build_steps(cities, [b for b, _ in self.businesses.entries()])
+
+ def _pending_steps(self) -> List[turbo.Step]:
+ steps = self._all_steps()
+ if self.skip_done.isChecked():
+ return self.progress.pending(self._iso, steps,
+ self.filter_combo.currentData())
+ return steps
+
+ def _sync_preview(self) -> None:
+ from .lead_panel import load_message_template
+ self.preview.setPlainText(load_message_template() or "(empty message)")
+
+ def _sync_footer(self, *_: Any) -> None:
+ cities = len(self.cities.entries())
+ businesses = len(self.businesses.entries())
+ total = len(self._all_steps())
+ pending = len(self._pending_steps())
+ text = (f"{cities} cities × {businesses} business types = "
+ f"{total} searches")
+ if pending != total:
+ text += f" · {total - pending} already finished, {pending} to run"
+ text += " · every search uses provider credits"
+ self.summary.setText(text)
+ self.start_btn.setEnabled(pending > 0)
+
+ def _reset_progress(self) -> None:
+ if not self.progress.done:
+ return
+ answer = QMessageBox.question(
+ self, "Forget finished searches?",
+ f"{len(self.progress.done)} finished searches are remembered. "
+ "Forget them, so turbo mode runs them again?\n\nLeads already "
+ "messaged stay in the contact history and are not messaged twice.",
+ QMessageBox.Yes | QMessageBox.No, QMessageBox.No)
+ if answer == QMessageBox.Yes:
+ try:
+ self.progress.clear()
+ except OSError as exc:
+ QMessageBox.warning(self, "Turbo mode",
+ f"Could not save the progress file: {exc}")
+ self._sync_footer()
+
+ def _edit_template(self) -> None:
+ from .lead_panel import WhatsAppTemplateDialog
+ if WhatsAppTemplateDialog([], self.p, parent=self).exec() == QDialog.Accepted:
+ self._sync_preview()
+
+ def accept(self) -> None: # noqa: D102 (Qt API)
+ self.steps = self._pending_steps()
+ if not self.steps:
+ return
+ self.filter_key = self.filter_combo.currentData()
+ self.limit = self.limit_spin.value()
+ self.safety = self.safety_form.value()
+ save_safety(self.safety)
+ saved = _load_setup()
+ countries = saved.get("countries")
+ if not isinstance(countries, dict):
+ countries = {}
+ countries[self._iso] = {
+ "cities_off": self.cities.unchecked(),
+ "custom_cities": [name for name, data in self.cities.entries(False)
+ if data == "custom"],
+ }
+ _save_setup({
+ "countries": countries,
+ "businesses_off": self.businesses.unchecked(),
+ "custom_businesses": [name for name, data in self.businesses.entries(False)
+ if data == "custom"],
+ "filter": self.filter_key,
+ "limit": self.limit,
+ "skip_done": self.skip_done.isChecked(),
+ })
+ super().accept()
+
+
+# --------------------------------------------------------------------------- #
+# the run
+# --------------------------------------------------------------------------- #
+
+class TurboWindow(WhatsAppSenderWindow):
+ """The bulk sender, refilling its queue from one search after another."""
+
+ batch_ready = Signal(object, object) # SearchSpec, RunResult
+
+ SEARCHING = "searching"
+
+ def __init__(self, steps: Sequence[turbo.Step], base: SearchSpec,
+ filter_key: str, safety: outreach.SafetySettings,
+ palette: Palette, *,
+ progress: Optional[turbo.Progress] = None,
+ history: Optional[outreach.History] = None,
+ parent: Optional[QWidget] = None):
+ self.steps: List[turbo.Step] = list(steps)
+ self.base = base
+ self.filter_key = filter_key
+ self.turbo_progress = progress or turbo.Progress()
+ self._step_index = -1
+ self._step_ok = False # the current step's search succeeded
+ self._failures = 0 # failed searches in a row
+ self._searches = 0
+ self._spec: Optional[SearchSpec] = None
+ self._worker: Optional[HarvestWorker] = None
+ self._thread: Optional[QThread] = None
+ super().__init__([], safety, palette, history=history, parent=parent)
+ self.setWindowTitle("MAPLEAD — turbo mode")
+
+ # -- queue hooks --------------------------------------------------------------
+ def _log_intro(self) -> None:
+ label = dict(turbo.FILTERS).get(self.filter_key, self.filter_key)
+ cities = len({s.city.lower() for s in self.steps})
+ self.log.write(f"Turbo: {len(self.steps)} searches in {cities} cities · "
+ f"filter “{label}” · " + self._safety_summary(), "info")
+
+ def _more_coming(self) -> bool:
+ return self._step_index < len(self.steps) - 1
+
+ def _queue_exhausted(self) -> None:
+ self._close_step()
+ self._start_next_step()
+
+ def _close_step(self) -> None:
+ """Remember the step whose leads were all handled."""
+ if not (0 <= self._step_index < len(self.steps)) or not self._step_ok:
+ return
+ self._step_ok = False
+ iso = self.base.country.iso if self.base.country else ""
+ try:
+ self.turbo_progress.mark(
+ turbo.step_key(iso, self.steps[self._step_index], self.filter_key))
+ except OSError as exc:
+ self.log.write(f"Could not save the turbo progress: {exc}", "error")
+
+ # -- searching ----------------------------------------------------------------
+ def _spec_for(self, step: turbo.Step) -> SearchSpec:
+ label, terms = turbo.business_terms(step.business)
+ region = step.region
+ if region and region.lower() == step.city.lower():
+ region = ""
+ fields = list(self.base.fields)
+ fields += [f for f in _NEEDED_FIELDS if f in FD.BY_KEY and f not in fields]
+ return dataclasses.replace(
+ self.base, city=step.city, region=region, business_label=label,
+ terms=terms, fields=fields, require_phone=True,
+ require_website=self.filter_key == "site")
+
+ def _start_next_step(self) -> None:
+ self._step_index += 1
+ if self._step_index >= len(self.steps):
+ self._done("Turbo finished — every city and business type handled")
+ return
+ step = self.steps[self._step_index]
+ new_city = (self._step_index == 0
+ or self.steps[self._step_index - 1].city != step.city)
+ if new_city:
+ self.log.write(f"City: {step.city}", "ok")
+ self._set_state(self.SEARCHING, f"Searching {step.label}",
+ f"Search {self._step_index + 1} of {len(self.steps)}")
+ self.log.write(f"Search {self._step_index + 1}/{len(self.steps)}: "
+ f"{step.label}", "query")
+ self._searches += 1
+ self._spec = self._spec_for(step)
+ worker = HarvestWorker(self._spec)
+ thread = QThread(self)
+ worker.moveToThread(thread)
+ thread.started.connect(worker.run)
+ worker.finished.connect(self._on_search_finished)
+ worker.failed.connect(self._on_search_failed)
+ worker.finished.connect(thread.quit)
+ worker.failed.connect(thread.quit)
+ thread.finished.connect(worker.deleteLater)
+ thread.finished.connect(thread.deleteLater)
+ self._worker, self._thread = worker, thread
+ thread.start()
+
+ def _wait_then_continue(self, seconds: int, reason: str) -> None:
+ """Go on through the one-second loop, so Pause keeps working."""
+ self._remaining = max(1, seconds)
+ self._wait_reason = reason
+ self._set_state(self.WAITING, "Paused" if self._paused else "Waiting", "")
+
+ def _on_search_finished(self, result: RunResult) -> None:
+ if self._state != self.SEARCHING:
+ return # the run was stopped meanwhile
+ self._worker = None
+ self._failures = 0
+ self._step_ok = not result.error
+ matches = turbo.filter_leads(result.leads, self.filter_key)
+ country = self.base.country
+ from .lead_panel import load_message_template
+ items = outreach.build_queue(
+ matches, load_message_template(),
+ dial=country.dial if country else "",
+ iso=country.iso if country else "",
+ history=self.history, skip_contacted=True)
+ queued = {item.number for item in self.items}
+ items = [item for item in items if item.number not in queued]
+ label = dict(turbo.FILTERS).get(self.filter_key, self.filter_key)
+ self.log.write(f" {len(result.leads)} leads · {len(matches)} pass "
+ f"“{label}” · {len(items)} to message",
+ "ok" if items else "info")
+ for error in result.report.errors[:2]:
+ self.log.write(f" {error}", "error")
+ self.batch_ready.emit(self._spec, result)
+ if items:
+ self._extend_items(items)
+ self._wait_then_continue(3, "search done")
+ else:
+ self._wait_then_continue(self.pacer.short_delay(), "nothing to send")
+
+ def _on_search_failed(self, message: str, hint_text: str) -> None:
+ if self._state != self.SEARCHING:
+ return
+ self._worker = None
+ self._step_ok = False
+ self._failures += 1
+ self.log.write(f" Search failed — {message}", "error")
+ if hint_text:
+ self.log.write(f" {hint_text}", "warn")
+ if self._failures >= MAX_SEARCH_FAILURES:
+ self._done(f"Stopped — {self._failures} searches failed in a row")
+ return
+ self._wait_then_continue(self.pacer.short_delay(), "search failed")
+
+ # -- ending -------------------------------------------------------------------
+ def _done(self, title: str) -> None:
+ if self._worker is not None:
+ self._worker.stop()
+ self._worker = None
+ super()._done(title)
+ left = max(0, len(self.steps) - self._step_index - 1)
+ self.log.write(f"{self._searches} searches run"
+ + (f" · {left} not reached — start turbo mode again to "
+ f"continue from there" if left else ""), "info")
+
+ def closeEvent(self, event) -> None: # noqa: N802 (Qt API)
+ super().closeEvent(event)
+ if event.isAccepted() and self._thread is not None:
+ try:
+ if self._thread.isRunning():
+ self._thread.quit()
+ self._thread.wait(4000)
+ except RuntimeError: # already deleted by Qt
+ pass
+
+
+def open_turbo(base: SearchSpec, palette: Palette, *,
+ parent: Optional[QWidget] = None) -> Optional[TurboWindow]:
+ """Setup dialog → turbo window. Returns the window (or None if cancelled)."""
+ if not webengine_available():
+ QMessageBox.warning(
+ parent, "Turbo mode",
+ "This build of MAPLEAD has no web engine (QtWebEngine), which turbo "
+ "mode needs to run WhatsApp Web.\n\nInstall PySide6-WebEngine or "
+ "use a release build that includes it.")
+ return None
+ dialog = TurboSetupDialog(base, palette, parent=parent)
+ if dialog.exec() != QDialog.Accepted or not dialog.steps:
+ return None
+ spec = dataclasses.replace(base, limit=dialog.limit)
+ window = TurboWindow(dialog.steps, spec, dialog.filter_key, dialog.safety,
+ palette, progress=dialog.progress, parent=parent)
+ window.setAttribute(Qt.WA_DeleteOnClose, True)
+ window.show()
+ window.start()
+ return window
diff --git a/maplead/turbo.py b/maplead/turbo.py
new file mode 100644
index 0000000..d616b48
--- /dev/null
+++ b/maplead/turbo.py
@@ -0,0 +1,159 @@
+"""
+Turbo mode: walk a list of cities and, in each one, a list of business types.
+
+For every (city, business) pair the GUI runs a search, keeps the leads that pass
+the chosen filter (for example *No website*) and hands them to the bulk WhatsApp
+sender; when that queue is empty it moves to the next business, and after the
+last business to the next city.
+
+Pure standard library, like ``outreach.py``: the order of the steps, the lead
+filter and the "already done" memory live here so they can be tested without a
+display. The GUI part is ``maplead/gui/turbo.py``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from . import contacts, paths
+from .data import verticals as VT
+
+PROGRESS_FILE = "turbo-progress.json"
+
+# lead filters the turbo run can apply (key, label) — the keys match the leads
+# panel's filters, so "No website" means the same thing in both places
+FILTERS: Tuple[Tuple[str, str], ...] = (
+ ("nos", "No website"),
+ ("site", "Has website"),
+ ("email", "Has e-mail"),
+ ("wa", "Every lead with WhatsApp"),
+)
+DEFAULT_FILTER = "nos"
+
+
+def business_terms(text: str) -> Tuple[str, List[str]]:
+ """The label and the search phrases for a business typed or picked."""
+ text = (text or "").strip()
+ hits = VT.resolve(text) if text else []
+ if hits:
+ vertical = hits[0]
+ return vertical.label, [vertical.query] + list(vertical.synonyms[:2])
+ return text, [text]
+
+
+def passes_filter(lead: Mapping[str, Any], key: str) -> bool:
+ if key == "nos":
+ return not contacts.has_real_website(lead)
+ if key == "site":
+ return contacts.has_real_website(lead)
+ if key == "email":
+ return bool(str(lead.get("email") or "").strip())
+ return True
+
+
+def filter_leads(leads: Iterable[Mapping[str, Any]], key: str) -> List[Mapping[str, Any]]:
+ return [lead for lead in leads if passes_filter(lead, key)]
+
+
+# --------------------------------------------------------------------------- #
+# steps
+# --------------------------------------------------------------------------- #
+
+@dataclass(frozen=True)
+class Step:
+ city: str
+ region: str
+ business: str
+
+ @property
+ def label(self) -> str:
+ return f"{self.business} in {self.city}"
+
+
+def build_steps(cities: Sequence[Tuple[str, str]],
+ businesses: Sequence[str]) -> List[Step]:
+ """City by city, every business in order: (city 1, biz 1), (city 1, biz 2)…"""
+ steps: List[Step] = []
+ seen = set()
+ for city, region in cities:
+ city = (city or "").strip()
+ if not city:
+ continue
+ for business in businesses:
+ business = (business or "").strip()
+ key = (city.lower(), business.lower())
+ if not business or key in seen:
+ continue
+ seen.add(key)
+ steps.append(Step(city=city, region=(region or "").strip(),
+ business=business))
+ return steps
+
+
+def step_key(iso: str, step: Step, filter_key: str) -> str:
+ return "|".join(part.strip().lower()
+ for part in (iso or "", step.city, step.business, filter_key))
+
+
+# --------------------------------------------------------------------------- #
+# progress memory
+# --------------------------------------------------------------------------- #
+
+class Progress:
+ """Which (country, city, business, filter) steps a turbo run already finished.
+
+ A step is recorded once its search ran and every lead it produced was
+ handled, so stopping and starting again continues where the run left off
+ instead of paying for the same searches twice.
+ """
+
+ def __init__(self, path: Optional[str] = None):
+ self.path = path or paths.state_file(PROGRESS_FILE)
+ self.done: Dict[str, str] = {}
+ self.load()
+
+ def load(self) -> None:
+ self.done = {}
+ try:
+ with open(self.path, "r", encoding="utf-8") as fh:
+ data = json.load(fh)
+ except (OSError, ValueError):
+ return
+ done = data.get("done") if isinstance(data, dict) else None
+ if isinstance(done, dict):
+ self.done = {str(k): str(v) for k, v in done.items()}
+
+ def save(self) -> None:
+ folder = os.path.dirname(self.path) or "."
+ os.makedirs(folder, exist_ok=True)
+ fd, tmp = tempfile.mkstemp(prefix=".turbo-", dir=folder)
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as fh:
+ json.dump({"version": 1, "done": self.done}, fh,
+ ensure_ascii=False, indent=1)
+ os.replace(tmp, self.path)
+ except OSError:
+ try:
+ os.unlink(tmp)
+ except OSError:
+ pass
+ raise
+
+ def is_done(self, key: str) -> bool:
+ return key in self.done
+
+ def mark(self, key: str) -> None:
+ self.done[key] = datetime.datetime.now().replace(microsecond=0).isoformat()
+ self.save()
+
+ def clear(self) -> None:
+ self.done = {}
+ self.save()
+
+ def pending(self, iso: str, steps: Sequence[Step], filter_key: str) -> List[Step]:
+ return [s for s in steps if not self.is_done(step_key(iso, s, filter_key))]
diff --git a/packaging/maplead.spec b/packaging/maplead.spec
index 61f5408..6447549 100644
--- a/packaging/maplead.spec
+++ b/packaging/maplead.spec
@@ -48,6 +48,8 @@ a = Analysis( # noqa: F821
"maplead.contacts",
"maplead.outreach",
"maplead.gui.bulk_sender",
+ "maplead.turbo",
+ "maplead.gui.turbo",
"PySide6.QtWebEngineCore",
"PySide6.QtWebEngineWidgets",
# `--cli` imports the wizard lazily, so PyInstaller cannot see it