diff --git a/CHANGELOG.md b/CHANGELOG.md index 3798370..65ba35e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ All notable changes to MAPLEAD. Format follows [Keep a Changelog](https://keepac ## [Unreleased] +### Added +- **Resume reminder** for **Turbo mode** and **Bulk send**. When a run stops, + the next setup window shows where it stopped: the city and business type being + searched (and how many searches are left) or the last lead handled and who + comes next. **Continue** / **Show unreached** picks the run up from there; + **Dismiss** forgets the reminder. The checkpoint is saved as the run goes, so + it also survives closing the app. + ## [1.4.1] — 2026-11-12 ### Fixed diff --git a/maplead/gui/bulk_sender.py b/maplead/gui/bulk_sender.py index c62955f..6a208b0 100644 --- a/maplead/gui/bulk_sender.py +++ b/maplead/gui/bulk_sender.py @@ -35,7 +35,7 @@ QSpinBox, QSplitter, QTableWidget, QTableWidgetItem, QVBoxLayout, QWidget) -from .. import contacts, outreach, paths +from .. import contacts, outreach, paths, resume from . import icons from .theme import Palette from .widgets import LogPane, card, field_label @@ -43,6 +43,7 @@ _SETTINGS_ORG = "maplead" _SETTINGS_APP = "maplead-desktop" _SAFETY_KEY = "whatsapp/bulk_safety" +_REMINDER_FILE = "whatsapp-last-run.json" WHATSAPP_WEB = "https://web.whatsapp.com/" WHATSAPP_SEND = WHATSAPP_WEB + "send" @@ -293,7 +294,9 @@ def __init__(self, leads: Sequence[Dict[str, Any]], palette: Palette, *, self._dial = dial self._iso = (country_code or "").lower() self._leads = list(leads) + self.filter_label = filter_label self.history = outreach.History() + self.reminder = resume.Reminder(_REMINDER_FILE) self.safety = load_safety() self.items: List[outreach.OutreachItem] = [] self.selected: List[outreach.OutreachItem] = [] @@ -327,7 +330,26 @@ def __init__(self, leads: Sequence[Dict[str, Any]], palette: Palette, *, message_btn.clicked.connect(self._edit_template) hl.addWidget(message_btn) root.addWidget(header) - self._filter_label = filter_label + + # where the last run stopped ------------------------------------------ + self.resume_card = QFrame() + self.resume_card.setObjectName("resumeCard") + rl = QHBoxLayout(self.resume_card) + rl.setContentsMargins(16, 10, 16, 10) + rl.setSpacing(10) + self.resume_label = QLabel("") + self.resume_label.setWordWrap(True) + rl.addWidget(self.resume_label, 1) + self.resume_btn = QPushButton("Show unreached") + self.resume_btn.setToolTip("Tick every lead that was not messaged yet") + self.resume_btn.clicked.connect(self._resume_last) + rl.addWidget(self.resume_btn) + resume_dismiss = QPushButton("Dismiss") + resume_dismiss.setProperty("flat", True) + resume_dismiss.setToolTip("Forget where the last bulk send stopped") + resume_dismiss.clicked.connect(self._forget_last) + rl.addWidget(resume_dismiss) + root.addWidget(self.resume_card) # leads + preview ------------------------------------------------------ split = QSplitter(Qt.Horizontal) @@ -441,7 +463,7 @@ def _fill(self) -> None: self.table.setCurrentCell(0, self.COL_NAME) skipped = len(self._leads) - len(self.items) contacted = sum(1 for i in self.items if i.contacted) - parts = [self._filter_label or "current filter", + parts = [self.filter_label or "current filter", f"{len(self.items)} with WhatsApp"] if contacted: parts.append(f"{contacted} already contacted") @@ -450,6 +472,47 @@ def _fill(self) -> None: self.sub_label.setText(" · ".join(parts)) self._sync_preview() self._sync_footer() + self._sync_reminder() + + # -- where the last run stopped --------------------------------------------- + def _sync_reminder(self) -> None: + last = self.reminder.last + total = resume.as_int(last.get("total")) if last else 0 + handled = resume.as_int(last.get("handled")) if last else 0 + if not last or total <= 0: + self.resume_card.setVisible(False) + return + when = resume.when_text(last.get("at")) + if str(last.get("status") or "") == "finished" or handled >= total: + text = (f"Last bulk send finished on {when} — " + f"{handled} of {total} leads handled.") + self.resume_btn.setVisible(False) + else: + left = max(0, total - handled) + name = str(last.get("next_name") or "").strip() + number = str(last.get("next_number") or "").strip() + where = f" Next: {name} (+{number})." if name else "" + reason = str(last.get("reason") or "").strip() + why = f" — {reason}" if reason else "" + text = (f"Last bulk send stopped on {when} after {handled} of " + f"{total} leads{why}.{where} {left} were still to reach — " + "leads already messaged are skipped and the rest are " + "ticked below. Start sending to resume.") + self.resume_btn.setVisible(left > 0) + self.resume_label.setText(text) + self.resume_card.setVisible(True) + + def _resume_last(self) -> None: + self._tick("new") + self._sync_footer() + + def _forget_last(self) -> None: + try: + self.reminder.clear() + except OSError as exc: + QMessageBox.warning(self, "Bulk WhatsApp", + f"Could not save the reminder: {exc}") + self.resume_card.setVisible(False) # -- interaction ------------------------------------------------------------ def _tick(self, mode: str) -> None: @@ -534,6 +597,8 @@ class WhatsAppSenderWindow(QDialog): def __init__(self, items: Sequence[outreach.OutreachItem], safety: outreach.SafetySettings, palette: Palette, *, history: Optional[outreach.History] = None, + reminder: Optional[resume.Reminder] = None, + filter_label: str = "", parent: Optional[QWidget] = None): super().__init__(parent) from PySide6.QtWebEngineCore import QWebEnginePage @@ -546,6 +611,8 @@ def __init__(self, items: Sequence[outreach.OutreachItem], self.safety = safety.normalized() self.pacer = outreach.Pacer(self.safety) self.history = history or outreach.History() + self.reminder = reminder + self.filter_label = filter_label self._state = self.IDLE self._index = -1 # item being handled @@ -665,6 +732,38 @@ def _extend_items(self, items: Sequence[outreach.OutreachItem]) -> None: self.progress.setRange(0, max(1, len(self.items))) self._sync_counts() + # -- resume reminder ------------------------------------------------------ + def _pending_index(self) -> Optional[int]: + """The lead to send next: the open one, or the one after it.""" + if 0 <= self._index < len(self.items) and not self.items[self._index].status: + return self._index + nxt = self._index + 1 + return nxt if nxt < len(self.items) else None + + def _remember_checkpoint(self, status: str, reason: str = "") -> None: + """Save where the run is, so the next bulk send shows the reminder.""" + if self.reminder is None: + return + c = outreach.counts(self.items) + pending = self._pending_index() + item = self.items[pending] if pending is not None else None + try: + self.reminder.remember( + status=status, + reason=reason, + filter_label=self.filter_label, + total=len(self.items), + handled=sum(c.values()), + sent=c[outreach.SENT], + invalid=c[outreach.INVALID], + failed=c[outreach.FAILED], + skipped=c[outreach.SKIPPED], + next_number=item.number if item else "", + next_name=item.name if item else "", + ) + except OSError as exc: + self.log.write(f"Could not save the resume reminder: {exc}", "error") + # -- lifecycle ------------------------------------------------------------ def start(self) -> None: self._set_state(self.LOGIN, "Opening WhatsApp Web…", @@ -672,6 +771,7 @@ def start(self) -> None: "phone (Linked devices). This is needed only once.") self.page.load(QUrl(WHATSAPP_WEB)) self.timer.start() + self._remember_checkpoint("running", "opening WhatsApp Web") def _set_state(self, state: str, title: str = "", detail: str = "") -> None: self._state = state @@ -833,6 +933,7 @@ def _open_next(self) -> None: self._index = nxt item = self.items[nxt] + self._remember_checkpoint("running", "opening the next lead") from .lead_panel import load_message_template # rendered now, so {saudacao} matches the time it is actually sent item.message = contacts.render_template(load_message_template(), item.lead) @@ -861,6 +962,7 @@ def _finish(self, status: str, error: str = "") -> None: outreach.SKIPPED: "info"}.get(status, "error") self.log.write(f" {label}" + (f" — {error}" if error else ""), level) self._sync_counts() + self._remember_checkpoint("running") if self._next_index() is None and not self._more_coming(): self._queue_exhausted() @@ -894,11 +996,20 @@ def _finish(self, status: str, error: str = "") -> None: def _done(self, title: str) -> None: self.timer.stop() c = outreach.counts(self.items) - self._set_state(self.DONE, title, - f"Sent {c[outreach.SENT]} · not on WhatsApp " - f"{c[outreach.INVALID]} · failed {c[outreach.FAILED]}. " - "The history is saved; these numbers are skipped next time.") + pending = self._pending_index() + detail = (f"Sent {c[outreach.SENT]} · not on WhatsApp " + f"{c[outreach.INVALID]} · failed {c[outreach.FAILED]}. " + "The history is saved; these numbers are skipped next time.") + if pending is not None: + nxt = self.items[pending] + detail += f" Next: {nxt.name} (+{nxt.number})." + self._set_state(self.DONE, title, detail) + self._remember_checkpoint("finished" if pending is None else "stopped", + title) self.log.write(title, "ok") + if pending is not None: + nxt = self.items[pending] + self.log.write(f" Resume from {nxt.name} (+{nxt.number})", "info") self.pause_btn.setText("Pause") self._paused = False @@ -973,7 +1084,10 @@ def open_bulk_sender(leads: Sequence[Dict[str, Any]], palette: Palette, *, if dialog.exec() != QDialog.Accepted or not dialog.selected: return None window = WhatsAppSenderWindow(dialog.selected, dialog.safety, palette, - history=dialog.history, parent=parent) + history=dialog.history, + reminder=dialog.reminder, + filter_label=dialog.filter_label, + parent=parent) window.setAttribute(Qt.WA_DeleteOnClose, True) window.show() window.start() diff --git a/maplead/gui/theme.py b/maplead/gui/theme.py index 2690fe9..07551a5 100644 --- a/maplead/gui/theme.py +++ b/maplead/gui/theme.py @@ -329,6 +329,11 @@ def component_qss(p: Palette) -> str: border: 1px solid {p.border}; border-radius: 12px; }} + QFrame#resumeCard {{ + background: {p.surface}; + border: 1px solid {p.warning}; + border-radius: 12px; + }} QLabel#panelTitle {{ font-size: 18px; font-weight: 700; color: {p.text}; }} QLabel#panelSub {{ color: {p.text_dim}; font-size: 12px; }} QFrame#leadCard {{ diff --git a/maplead/gui/turbo.py b/maplead/gui/turbo.py index 4267c5d..f3d9b4c 100644 --- a/maplead/gui/turbo.py +++ b/maplead/gui/turbo.py @@ -29,7 +29,7 @@ QPushButton, QSpinBox, QSplitter, QVBoxLayout, QWidget) -from .. import outreach, turbo +from .. import outreach, resume, turbo from ..data import cities as CI from ..data import fields as FD from ..data import verticals as VT @@ -220,6 +220,26 @@ def __init__(self, base: SearchSpec, palette: Palette, *, hl.addWidget(message_btn) root.addWidget(header) + # where the last run stopped ------------------------------------------ + self.resume_card = QFrame() + self.resume_card.setObjectName("resumeCard") + rl = QHBoxLayout(self.resume_card) + rl.setContentsMargins(16, 10, 16, 10) + rl.setSpacing(10) + self.resume_label = QLabel("") + self.resume_label.setWordWrap(True) + rl.addWidget(self.resume_label, 1) + self.resume_btn = QPushButton("Continue") + self.resume_btn.setProperty("accent", True) + self.resume_btn.clicked.connect(self._resume_last) + rl.addWidget(self.resume_btn) + resume_dismiss = QPushButton("Dismiss") + resume_dismiss.setProperty("flat", True) + resume_dismiss.setToolTip("Forget where the last turbo run stopped") + resume_dismiss.clicked.connect(self._forget_last) + rl.addWidget(resume_dismiss) + root.addWidget(self.resume_card) + # lists + options ------------------------------------------------------ split = QSplitter(Qt.Horizontal) split.setChildrenCollapsible(False) @@ -275,20 +295,20 @@ def __init__(self, base: SearchSpec, palette: Palette, *, except (TypeError, ValueError): self.limit_spin.setValue(base.limit) rc.addWidget(self.limit_spin) - resume = QHBoxLayout() - resume.setSpacing(6) + resume_row = QHBoxLayout() + resume_row.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) + resume_row.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) + resume_row.addWidget(reset) + rc.addLayout(resume_row) note = QLabel("Leads already messaged are always skipped.") note.setObjectName("hint") note.setWordWrap(True) @@ -333,6 +353,7 @@ def __init__(self, base: SearchSpec, palette: Palette, *, self.businesses.changed.connect(self._sync_footer) self._sync_preview() self._sync_footer() + self._sync_resume() # -- state ------------------------------------------------------------------ def _all_steps(self) -> List[turbo.Step]: @@ -364,6 +385,43 @@ def _sync_footer(self, *_: Any) -> None: self.summary.setText(text) self.start_btn.setEnabled(pending > 0) + # -- where the last run stopped --------------------------------------------- + def _sync_resume(self) -> None: + last = self.progress.last_run + if not last or str(last.get("iso") or "").lower() != self._iso.lower(): + self.resume_card.setVisible(False) + return + when = resume.when_text(last.get("at")) + total = resume.as_int(last.get("total")) + done = resume.as_int(last.get("completed")) + left = max(0, total - done) + label = str(last.get("label") or "").strip() + if str(last.get("status") or "") == "finished" or left == 0: + text = f"Last turbo run finished on {when} — every search handled." + self.resume_btn.setVisible(False) + else: + where = f" while at “{label}”" if label else "" + reason = str(last.get("reason") or "").strip() + why = f" {reason}." if reason else "" + text = (f"Last turbo run stopped on {when}{where}.{why} {left} " + "searches were still to run — Continue picks up from there.") + self.resume_btn.setVisible(True) + self.resume_label.setText(text) + self.resume_card.setVisible(True) + + def _resume_last(self) -> None: + self.skip_done.setChecked(True) + self._sync_footer() + self.resume_card.setVisible(False) + + def _forget_last(self) -> None: + try: + self.progress.forget_last() + except OSError as exc: + QMessageBox.warning(self, "Turbo mode", + f"Could not save the progress file: {exc}") + self.resume_card.setVisible(False) + def _reset_progress(self) -> None: if not self.progress.done: return @@ -376,9 +434,11 @@ def _reset_progress(self) -> None: if answer == QMessageBox.Yes: try: self.progress.clear() + self.progress.forget_last() except OSError as exc: QMessageBox.warning(self, "Turbo mode", f"Could not save the progress file: {exc}") + self.resume_card.setVisible(False) self._sync_footer() def _edit_template(self) -> None: @@ -438,6 +498,7 @@ def __init__(self, steps: Sequence[turbo.Step], base: SearchSpec, self.turbo_progress = progress or turbo.Progress() self._step_index = -1 self._step_ok = False # the current step's search succeeded + self._handled_steps = 0 # steps finished in this run self._failures = 0 # failed searches in a row self._searches = 0 self._spec: Optional[SearchSpec] = None @@ -471,6 +532,33 @@ def _close_step(self) -> None: 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") + self._handled_steps += 1 + + # -- resume reminder ---------------------------------------------------------- + def _completed(self) -> int: + """Steps this run finished (old progress marks do not count).""" + return self._handled_steps + + def _remember(self, status: str, reason: str = "") -> None: + step = (self.steps[self._step_index] + if 0 <= self._step_index < len(self.steps) else None) + iso = self.base.country.iso if self.base.country else "" + completed = self._completed() + try: + self.turbo_progress.remember( + status=status, + reason=reason, + iso=iso, + filter_key=self.filter_key, + label=step.label if step else "", + city=step.city if step else "", + business=step.business if step else "", + total=len(self.steps), + completed=completed, + remaining=max(0, len(self.steps) - completed), + ) + except OSError as exc: + self.log.write(f"Could not save the resume reminder: {exc}", "error") # -- searching ---------------------------------------------------------------- def _spec_for(self, step: turbo.Step) -> SearchSpec: @@ -491,6 +579,7 @@ def _start_next_step(self) -> None: self._done("Turbo finished — every city and business type handled") return step = self.steps[self._step_index] + self._remember("running") new_city = (self._step_index == 0 or self.steps[self._step_index - 1].city != step.city) if new_city: @@ -568,11 +657,13 @@ def _done(self, title: str) -> None: if self._worker is not None: self._worker.stop() self._worker = None + left = max(0, len(self.steps) - self._completed()) + self._remember("finished" if left == 0 else "stopped", title) 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") + f"continue from there" if left + else " · every search handled"), "info") def closeEvent(self, event) -> None: # noqa: N802 (Qt API) super().closeEvent(event) diff --git a/maplead/resume.py b/maplead/resume.py new file mode 100644 index 0000000..d024a08 --- /dev/null +++ b/maplead/resume.py @@ -0,0 +1,99 @@ +""" +Where a long run stopped, so it can be picked up again. + +Turbo mode and the bulk sender both write one small JSON record when they start, +stop or finish: when it happened, which search/lead was on screen and how much +is left. The setup dialogs read it back and show a reminder, so the user knows +where the last run stopped and can continue from there. + +Pure standard library, like ``turbo.py`` and ``outreach.py`` — no Qt here. +""" + +from __future__ import annotations + +import datetime +import json +import os +import tempfile +from typing import Any, Dict, Optional + +from . import paths + + +def now() -> str: + """The timestamp written into a reminder (seconds are enough).""" + return datetime.datetime.now().replace(microsecond=0).isoformat() + + +def when_text(value: Any) -> str: + """``13/11 14:32`` for an ISO timestamp; the raw text when it cannot be read.""" + raw = str(value or "").strip() + try: + moment = datetime.datetime.fromisoformat(raw) + except ValueError: + return raw + return moment.strftime("%d/%m %H:%M") + + +def as_int(value: Any, default: int = 0) -> int: + """``int(value)`` without letting a hand-edited file break the dialog.""" + try: + return int(value) + except (TypeError, ValueError): + return default + + +def _atomic_write(path: str, payload: Dict[str, Any]) -> None: + folder = os.path.dirname(path) or "." + os.makedirs(folder, exist_ok=True) + fd, tmp = tempfile.mkstemp(prefix=".reminder-", dir=folder) + try: + with os.fdopen(fd, "w", encoding="utf-8") as fh: + json.dump(payload, fh, ensure_ascii=False, indent=1) + os.replace(tmp, path) + except OSError: + try: + os.unlink(tmp) + except OSError: + pass + raise + + +class Reminder: + """One "last run" record, kept in its own file in the user data folder. + + ``last`` is an empty dict when there is nothing to show. Callers can store + whichever fields they need; the GUI reads them back with ``.get()``. + """ + + def __init__(self, filename: str, path: Optional[str] = None): + self.path = path or paths.state_file(filename) + self.last: Dict[str, Any] = {} + self.load() + + # -- storage ---------------------------------------------------------- + def load(self) -> None: + self.last = {} + try: + with open(self.path, "r", encoding="utf-8") as fh: + data = json.load(fh) + except (OSError, ValueError): + return + last = data.get("last") if isinstance(data, dict) else None + if isinstance(last, dict): + self.last = dict(last) + + def save(self) -> None: + _atomic_write(self.path, {"version": 1, "last": self.last or None}) + + # -- updates ---------------------------------------------------------- + def remember(self, **fields: Any) -> Dict[str, Any]: + """Replace the record with ``fields`` plus the current timestamp.""" + self.last = {"at": now()} + self.last.update(fields) + self.save() + return self.last + + def clear(self) -> None: + self.last = {} + self.save() diff --git a/maplead/turbo.py b/maplead/turbo.py index d616b48..5d68208 100644 --- a/maplead/turbo.py +++ b/maplead/turbo.py @@ -20,10 +20,11 @@ from dataclasses import dataclass from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple -from . import contacts, paths +from . import contacts, paths, resume from .data import verticals as VT PROGRESS_FILE = "turbo-progress.json" +REMINDER_FILE = "turbo-last-run.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 @@ -112,9 +113,12 @@ class Progress: instead of paying for the same searches twice. """ - def __init__(self, path: Optional[str] = None): + def __init__(self, path: Optional[str] = None, + reminder_path: Optional[str] = None): self.path = path or paths.state_file(PROGRESS_FILE) self.done: Dict[str, str] = {} + # where the last run stopped; shown by the setup dialog next time + self.reminder = resume.Reminder(REMINDER_FILE, reminder_path) self.load() def load(self) -> None: @@ -157,3 +161,14 @@ def clear(self) -> None: 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))] + + # -- where the last run stopped ---------------------------------------- + @property + def last_run(self) -> Dict[str, Any]: + return self.reminder.last + + def remember(self, **fields: Any) -> None: + self.reminder.remember(**fields) + + def forget_last(self) -> None: + self.reminder.clear() diff --git a/packaging/maplead.spec b/packaging/maplead.spec index 6447549..c356654 100644 --- a/packaging/maplead.spec +++ b/packaging/maplead.spec @@ -47,6 +47,7 @@ a = Analysis( # noqa: F821 "maplead.gui.theme", "maplead.contacts", "maplead.outreach", + "maplead.resume", "maplead.gui.bulk_sender", "maplead.turbo", "maplead.gui.turbo",