From 64dfbbde303c75d39615fe492f20bf52ab6c3ae2 Mon Sep 17 00:00:00 2001 From: DariusDev16 Date: Thu, 12 Nov 2026 17:42:06 +0200 Subject: [PATCH 1/3] feat(turbo): search city by city and message every matching lead Turbo mode walks a list of cities and, in each one, a list of business types: it runs the search, keeps the leads that pass the chosen filter (No website by default) and sends them the saved WhatsApp message, then moves to the next business type and, after the last one, to the next city. It reuses the bulk sender: the sender window gets hooks for a queue that grows while it runs, and the Safety card is shared by both setup dialogs. Finished searches are remembered, so a new run continues where the last one stopped. The Demo provider is refused because its numbers are made up. Co-Authored-By: Claude Fable 5.2 --- maplead/gui/bulk_sender.py | 162 ++++++---- maplead/gui/icons.py | 1 + maplead/gui/main_window.py | 68 ++++- maplead/gui/turbo.py | 607 +++++++++++++++++++++++++++++++++++++ maplead/turbo.py | 159 ++++++++++ packaging/maplead.spec | 2 + 6 files changed, 934 insertions(+), 65 deletions(-) create mode 100644 maplead/gui/turbo.py create mode 100644 maplead/turbo.py 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 From 3720a527883170c174f54871f2d30280d71ab327 Mon Sep 17 00:00:00 2001 From: DariusDev16 Date: Thu, 12 Nov 2026 17:42:06 +0200 Subject: [PATCH 2/3] release: 1.4.0 - turbo mode Bump the version, add the changelog entry, document turbo mode in the README and the guide, update the AppImage file names in the docs and rewrite the release notes, which are fixed text in release.yml. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/release.yml | 38 ++++++++++++++++++------------- CHANGELOG.md | 19 ++++++++++++++++ README.md | 27 ++++++++++++++++++---- docs/GUIDE.md | 43 +++++++++++++++++++++++++++++++---- maplead/art.py | 2 +- 5 files changed, 102 insertions(+), 27 deletions(-) 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 bulk send: progress and activity log

+## 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 From 6e51ad52a9b131e706ab9d425d01aea4cd71ecfb Mon Sep 17 00:00:00 2001 From: DariusDev16 Date: Thu, 12 Nov 2026 18:18:36 +0200 Subject: [PATCH 3/3] ci: run the terminal wizard job on ubuntu-22.04 ubuntu-latest moved to Ubuntu 26.04, where setup-python has no Python 3.9, so the job failed before running anything. 22.04 still offers 3.9, the oldest version the wizard supports. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/ci.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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