Prepare documented WhatsApp injector with portable Python bundle

2026-10-11 07:57:48 +02:00
commit d2b621bce7
@@ -0,0 +1,70 @@
+# WhatsApp Desktop Suite
+
+A Windows toolkit for reading, searching and exporting local WhatsApp Desktop data, with a portable single-file Python distribution and an editable source package.
+
+The core live commands execute JavaScript inside the signed-in Desktop WebView through a bundled native bridge. They require neither CDP nor UI automation. Separate optional research commands use CDP, Frida or process-memory inspection.
+
+## Features
+
+| Feature | Command | Scope |
+| --- | --- | --- |
+| Contact export | `contacts-export` | Local contact rows, including distinct PN/LID records |
+| Message ZIP export | `export-zip` | Local message rows, decoded text/captions and manifest; no media downloads |
+| Old message reading | `live --suite history-read` | Five oldest local records, including records outside loaded chats |
+| Desktop search | `desktop-search` | Bounded app search through the native bridge |
+| Saved export search | `search` | Unicode-aware literal search, filtering and optional redaction |
+| Self-message test | `send-self` | One fixed message to the signed-in account, with stored-text verification |
+| Inspection and diagnostics | `inventory`, `stats`, `live` | Storage inventory, export summaries and fixed probes |
+| Optional research tools | See [CLI reference](docs/CLI.md) | CDP history export, RAM tools, SQLite probes and pairing tools |
+
+## Quick start
+
+Copy `whatsapp.py` into a writable folder. Run with Python 3.11 or newer:
+
+```powershell
+python whatsapp.py --help
+python whatsapp.py test
+python whatsapp.py contacts-export --output contacts.json
+python whatsapp.py export-zip --output messages.zip
+python whatsapp.py live --suite history-read
+```
+
+Live bridge commands require **Windows x64, 64-bit Python and WhatsApp Desktop 2.2639.100.0** with the verified WebView component. This is a version-specific integration, not a general promise of compatibility with future WhatsApp releases. The core commands need only Python's standard library. Optional tools have [additional dependencies](docs/CLI.md#optional-dependencies); Node.js enables the JavaScript fixture tests.
+
+`send-self` actually sends a message. It is never part of the default tests and does not retry automatically. ZIP exports cover the local database, not necessarily every message ever received. Contacts are local table rows, not a deduplicated phone address book.
+
+## Development
+
+```powershell
+python -m whatsapp_suite --help
+python -m whatsapp_suite test
+python build_whatsapp_bundle.py
+python whatsapp.py test
+```
+
+The builder embeds the maintained modules, DLLs and fixtures. Modules load from memory; a verified DLL is extracted only when needed. The distribution is approximately 158 KiB. Keep source and bundle changes together.
+
+## Project layout
+
+```text
+whatsapp.py                       Portable generated distribution
+whatsapp_suite/                   Canonical Python implementations
+whatsapp_suite/assets/            Runtime DLLs and SQLite agent
+native/                           Native helper C++ source
+tests/                           Synthetic Python and JavaScript fixtures
+build_whatsapp_bundle.py          Deterministic bundle builder
+docs/                            Architecture, validation and publishing guide
+```
+
+## Documentation
+
+- [CLI and export behavior](docs/CLI.md)
+- [Architecture and native bridge](docs/ARCHITECTURE.md)
+- [Validation and limitations](docs/VALIDATION.md)
+- [Development and contributions](CONTRIBUTING.md)
+- [Publishing to tea.karlcom.de](docs/PUBLISHING.md)
+- [Handling private data](SECURITY.md)
+
+## Project status
+
+Repository: [karl/whatsapp_injector](https://tea.karlcom.de/karl/whatsapp_injector). It is independent of WhatsApp/Meta. No open-source license has been selected; see [licensing status](LICENSE.md).