Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,39 @@ All notable changes to MAPLEAD. Format follows [Keep a Changelog](https://keepac

## [Unreleased]

## [1.3.0] — 2026-11-07

Linux (AppImage) only for now — the Windows build and the terminal wizard are
unchanged in this release.

### Added
- **Bulk WhatsApp sender** — a new **Bulk send** button in the leads panel sends
your saved WhatsApp message to every lead of the current filter (for example
*No website*) one by one, with no clicks per lead.
1. A checklist shows the leads that have a WhatsApp number. Untick anyone you
want to leave out and click a row to preview its message.
2. **Start sending** opens WhatsApp Web inside MAPLEAD. Scan the QR code once;
the session is saved for next time.
3. Each chat is opened with the message filled in and sent. Numbers that are
not on WhatsApp are detected and skipped. **Pause**, **Skip lead** and
**Stop** work at any time, and an activity log shows every step.
- **Safety pauses** against WhatsApp blocks, all editable before each run:
random 45–120 s pause between messages, a 10 min rest every 10 messages, a
*"WhatsApp may block the number after this many messages — continue? (Yes/No)"*
prompt every 25 messages, and a 50-a-day limit that asks before going over.
- **Contact history** — every number messaged is saved with its date and result
(sent / not on WhatsApp / failed / skipped) in
`~/.local/share/maplead/whatsapp-history.json`. Leads already contacted come
unticked, show a **Contacted** chip on their card, and the new
**Not contacted** filter hides them.
- `tools/bulk_test.py` — try the sender on your own numbers without a search
(`--forget` removes them from the history afterwards).

### Changed
- The AppImage now bundles QtWebEngine (the browser engine that runs WhatsApp
Web inside the app), so the file is bigger. `build-appimage.sh` installs the
full `PySide6` package instead of `PySide6-Essentials`.

## [1.2.0] — 2026-10-22

### Added
Expand Down
26 changes: 20 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ lead-scraper API and writes them to CSV / Excel / JSON / TXT / TSV / HTML.
| 🧭 **65 countries / 1044 cities** | typed, filtered, auto-completed — no spelling games |
| 🏷️ **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 |
| 📄 **6 export formats** | csv · xlsx · json · txt · tsv · html |

<p align="center">
Expand All @@ -32,8 +33,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.2.0-x86_64.AppImage
./MAPLEAD-1.2.0-x86_64.AppImage
chmod +x MAPLEAD-1.3.0-x86_64.AppImage
./MAPLEAD-1.3.0-x86_64.AppImage
```

Building it yourself (also fine for arm64/other distros with a rebuild):
Expand Down Expand Up @@ -114,6 +115,18 @@ folder — `~/Documents/maplead/` on Linux,

![harvest report](docs/screenshots/terminal-report.png)

## 5 · Message leads in bulk (Linux)

Open the **Leads panel**, pick a filter (e.g. *No website*) and press **Bulk send**:

1. untick the leads you want to skip — the message preview shows exactly what each one gets;
2. **Start sending** opens WhatsApp Web inside MAPLEAD (scan the QR code once);
3. it sends one message at a time, with random pauses, rests and a
*"may get blocked — continue?"* question every 25 messages.

Everyone you message is remembered, so the next search skips them.
Details and the safety settings: [docs/GUIDE.md › Bulk WhatsApp](docs/GUIDE.md#bulk-whatsapp).

---

## Terminal wizard
Expand Down Expand Up @@ -165,9 +178,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.2.0-x86_64.AppImage --cli --demo
./MAPLEAD-1.2.0-x86_64.AppImage --cli --country DE --city Berlin --business dentist
./MAPLEAD-1.2.0-x86_64.AppImage --cli --doctor
./MAPLEAD-1.3.0-x86_64.AppImage --cli --demo
./MAPLEAD-1.3.0-x86_64.AppImage --cli --country DE --city Berlin --business dentist
./MAPLEAD-1.3.0-x86_64.AppImage --cli --doctor
```

You can add `~/.local/bin/maplead-cli` yourself (`#!/bin/sh` + `exec "$HOME/Apps"/MAPLEAD-*-x86_64.AppImage --cli "$@"`)
Expand All @@ -194,7 +207,8 @@ The terminal wizard runs anywhere Python 3.9+ does. macOS packaging is on the ro

Lead data returned by these APIs is public business information. Respect each
provider's terms and rate limits, and your GDPR/LGPD/PCCB obligations before
cold-contacting anyone. MAPLEAD never edits Google Maps — it only reads what the
cold-contacting anyone. Automated WhatsApp messages go against WhatsApp's terms of
service: the bulk sender's pauses lower the risk of a ban, they do not remove it. MAPLEAD never edits Google Maps — it only reads what the
provider APIs already expose.

## License
Expand Down
5 changes: 3 additions & 2 deletions build-appimage.sh
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,10 @@ if [[ ! -x "$PY" ]]; then
rm -rf "$tmp"
fi
fi
if ! "$PY" -c "import PySide6" >/dev/null 2>&1; then
if ! "$PY" -c "import PyInstaller; from PySide6 import QtWebEngineWidgets" >/dev/null 2>&1; then
"$PY" -m pip install -q --upgrade pip
"$PY" -m pip install -q "PySide6-Essentials>=6.8" pyinstaller
# full PySide6: the bulk WhatsApp sender needs QtWebEngine
"$PY" -m pip install -q "PySide6>=6.8" pyinstaller
fi
"$PY" -c "import PySide6; from PySide6 import QtCore; print(' PySide6', QtCore.__version__)"

Expand Down
7 changes: 5 additions & 2 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,14 +70,17 @@ maplead/
app.py entry point, theme bootstrap, --selftest
main_window.py window: form, stats, table, activity log
lead_panel.py card view of the leads + WhatsApp message template
bulk_sender.py bulk WhatsApp: lead picker, safety settings, WhatsApp Web sender
widgets.py cards, searchable combo, field picker, table model
keys.py API key manager (paste · verify live · save)
worker.py harvest + key validation on a QThread
icons.py inline SVG icon set (no image files)
theme.py dark/light palettes and the stylesheet
contacts.py WhatsApp number normalisation + {placeholder} messages
outreach.py bulk-send queue, safety pacing, contact history (no Qt)
packaging/ icon (svg+png+ico), .desktop file, PyInstaller specs, launchers
tools/screenshots.py regenerates docs/screenshots/*
tools/bulk_test.py try the bulk WhatsApp sender on your own numbers
build-appimage.sh one-command AppImage build (+ optional --install)
build-windows.ps1 one-command Windows build: one portable .exe
docs/ user guide, development notes and screenshots
Expand All @@ -86,7 +89,7 @@ docs/ user guide, development notes and screenshots
## Running from source

```bash
python3 -m venv .venv-gui && .venv-gui/bin/python -m pip install PySide6-Essentials
python3 -m venv .venv-gui && .venv-gui/bin/python -m pip install PySide6 # full: QtWebEngine for the bulk sender

./maplead.py --demo # terminal wizard (needs no venv at all)
./maplead-gui.py # desktop
Expand Down Expand Up @@ -116,7 +119,7 @@ MAPLEAD_OUTDIR=~/bin ./build-appimage.sh # somewhere else

What it does, in order:

1. creates/updates `.venv-gui` (PySide6-Essentials + PyInstaller);
1. creates/updates `.venv-gui` (PySide6 with QtWebEngine + PyInstaller);
2. renders the PNG icons from `packaging/maplead.svg` (Qt does the rasterising — no
ImageMagick, no Pillow);
3. generates the `.desktop` entry (`Exec=AppRun`, replaced at install time);
Expand Down
41 changes: 35 additions & 6 deletions docs/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ New here? Read this once, then the [README](../README.md) is just a reminder.

### Linux x86_64

Download `MAPLEAD-1.2.0-x86_64.AppImage`, then:
Download `MAPLEAD-1.3.0-x86_64.AppImage`, then:

```bash
chmod +x MAPLEAD-1.2.0-x86_64.AppImage # first time only
./MAPLEAD-1.2.0-x86_64.AppImage
chmod +x MAPLEAD-1.3.0-x86_64.AppImage # first time only
./MAPLEAD-1.3.0-x86_64.AppImage
```

After `./build-appimage.sh --install` you can also just type `maplead`, and the app
Expand All @@ -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.2.0-x86_64.AppImage --cli --demo
./MAPLEAD-1.3.0-x86_64.AppImage --cli --demo
```

**No FUSE?** Older AppImages mount themselves through `libfuse.so.2`. If your system
Expand Down Expand Up @@ -169,12 +169,41 @@ reading rather than for a spreadsheet:
Unknown placeholders are highlighted in the preview instead of silently
disappearing. The template is remembered between launches.
- **Chips filter the list**: *Has WhatsApp*, *Has phone*, *Has website*,
*No website*, *Has e-mail*. The search box matches every visible field, and
*No website*, *Has e-mail*, *Not contacted*. The search box matches every visible field, and
the sort menu orders by rating, reviews or name.
- **Copy** on a card puts the whole row (TSV) on the clipboard.
- **Right-click a grid row** also has *Send WhatsApp message* and *Open in leads
panel*. The panel stays open while you work and refreshes after the next run.

### Bulk WhatsApp

**Bulk send** in the panel header sends the saved message to every lead of the
current filter and search (for example *No website*) that has a WhatsApp number.

1. A checklist opens: untick anyone you want to leave out (leads already
messaged come unticked), click a row to preview its message, and check the
**Safety** settings.
2. **Start sending** opens WhatsApp Web inside MAPLEAD. The first time, scan the
QR code (phone → WhatsApp → *Linked devices*); the session is kept for later.
3. Each lead is opened with the message filled in and sent; numbers without
WhatsApp are marked and skipped. **Pause**, **Skip lead** and **Stop** work at
any time. Keep the window open (minimising is fine).

| Safety setting | default | what it does |
|---|---|---|
| Pause from / up to | 45 – 120 s | random wait between two messages |
| Rest every / for | 10 msgs / 10 min | longer break after each burst |
| Ask after | 25 msgs | stops and asks *"WhatsApp may block the number — continue?"* |
| Daily limit | 50 msgs | asks before going over today's total |

Every number is saved with date and status in `whatsapp-history.json` in the
data folder (`~/.local/share/maplead/` on Linux, `%LOCALAPPDATA%\maplead\` on
Windows); contacted leads show a *Contacted* chip and are skipped by default.

> Automated messaging goes against WhatsApp's terms of service. The pauses lower
> the risk of the number being restricted; they do not remove it. Use a number
> dedicated to prospecting.

## 7 · The export file

A search **never writes a file by itself**. Results stay in the grid and in the
Expand Down Expand Up @@ -209,7 +238,7 @@ The original interface, still fully supported and dependency-free:
Without Python, the packaged builds carry the same wizard:

```bash
./MAPLEAD-1.2.0-x86_64.AppImage --cli --demo # Linux: the AppImage is both
./MAPLEAD-1.3.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
```

Expand Down
2 changes: 1 addition & 1 deletion maplead/art.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

from . import host

VERSION = "1.2.0"
VERSION = "1.3.0"

# --------------------------------------------------------------------------- #
# colour plumbing
Expand Down
5 changes: 5 additions & 0 deletions maplead/gui/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,11 @@ def create_app(argv: Optional[Sequence[str]] = None):
"""Boot QApplication and paint the first palette."""
args = build_parser().parse_args(argv)

if QApplication.instance() is None:
# QtWebEngine (bulk WhatsApp sender) needs shared GL contexts set
# before the application object exists
from PySide6.QtCore import Qt as _Qt
QApplication.setAttribute(_Qt.AA_ShareOpenGLContexts, True)
app = QApplication.instance() or QApplication(list(sys.argv[:1]))
app.setApplicationName("MAPLEAD")
app.setApplicationDisplayName("MAPLEAD")
Expand Down
Loading
Loading