ADR-0005's open item is closed: the installed Chrome or Edge first, a downloaded Chrome for Testing only when none is found. The v1 platform list is confirmed and leaves the pending table. ADR-0005 no longer mentions install.sh or an npm install on the user's machine.
64 lines
3.8 KiB
Markdown
64 lines
3.8 KiB
Markdown
# ADR-0005: The WhatsApp channel uses whatsapp-web.js
|
|
|
|
- Status: Accepted (browser source confirmed by the owner on 2026-11-04)
|
|
- Date: 2026-10-14
|
|
|
|
## Context
|
|
|
|
The WhatsApp channel (`packages/server/src/local/channels/whatsapp-adapter.ts`) uses Baileys.
|
|
Baileys itself is MIT, but it depends on `libsignal`, which is GPL-3.0. The sidecar build
|
|
bundles both, which would put GPL code into the shipped community edition.
|
|
|
|
## Decision
|
|
|
|
Replace Baileys with `whatsapp-web.js` (Apache-2.0) and remove Baileys from the dependencies
|
|
of `server` and `launcher`.
|
|
|
|
## Consequences
|
|
|
|
Implemented in P1.7 with `whatsapp-web.js` 1.34.7 (Puppeteer 24).
|
|
|
|
- The adapter keeps its public shape: start, stop, status with the pairing QR, send and
|
|
inbound text. `LocalAuth` keeps the session as a browser profile in
|
|
`<dataDir>/channels/whatsapp/session`, next to the WhatsApp Web page cache.
|
|
- The session is no longer encrypted at rest. Baileys state lived in the encrypted vault; the
|
|
browser profile is protected only by file permissions.
|
|
- Baileys pairings are not migrated: whatsapp-web.js cannot use them. The old vault entry and
|
|
`<dataDir>/channels/whatsapp-auth` are left untouched because the data directory may still
|
|
be shared with the commercial edition. Users scan the QR once more.
|
|
- Installing dependencies does not download a browser: the root `.puppeteerrc.cjs` sets
|
|
`skipDownload`. This covers `npm install` and `npm ci` in this repository (development and
|
|
the release staging). The server installer runs no npm install on the user's machine: it
|
|
unpacks the staged payload (ADR-0009).
|
|
- Browser source, confirmed by the owner on 2026-11-04. The order is `CHROME_PATH` or `PUPPETEER_EXECUTABLE_PATH`, an installed Chrome, Edge or Chromium
|
|
in the standard Windows, macOS and Linux locations, then a browser downloaded earlier.
|
|
Only when none is found does starting WhatsApp download the current stable Chrome for
|
|
Testing (about 170 MB) into `<dataDir>/browsers` with `@puppeteer/browsers`. Settings
|
|
shows the progress, or an error that asks the user to install Chrome or set `CHROME_PATH`.
|
|
Linux on ARM has no Chrome for Testing build, so users there install Chromium.
|
|
- The Tauri sidecar build keeps `whatsapp-web.js` and `@puppeteer/browsers` external.
|
|
Bundled into the ESM sidecar, whatsapp-web.js fails at runtime (`__dirname` is not defined).
|
|
- The channel handles text only. whatsapp-web.js needs ffmpeg only to turn videos into
|
|
stickers, which Waggle never sends, so ffmpeg is not bundled, downloaded or looked up.
|
|
Voice, video and other media messages are ignored and logged.
|
|
- New licenses: Apache-2.0 (`whatsapp-web.js`, `puppeteer`, `puppeteer-core`,
|
|
`@puppeteer/browsers`, `chromium-bidi`, `webdriver-bidi-protocol`), BSD (`devtools-protocol`,
|
|
`extract-zip`), MIT and ISC for the rest, and LGPL-3.0-or-later for `node-webpmux`, a
|
|
required dependency of whatsapp-web.js that it loads on startup for sticker metadata. It
|
|
ships as a separate, unmodified package. The licensing review has to accept it.
|
|
- The client is unofficial. Settings warns that WhatsApp may block the account and
|
|
recommends a secondary number.
|
|
- Risk: whatsapp-web.js awaits page work inside browser event listeners (for example
|
|
`inject()` after a navigation, which throws "auth timeout" when WhatsApp Web loads slowly).
|
|
Such a failure is an unhandled promise rejection, and the sidecar has no handler for those,
|
|
so Node stops the process.
|
|
|
|
## Alternatives considered
|
|
|
|
- whatsmeow (Go, MPL-2.0): no browser, but needs a separate Go binary per platform.
|
|
- WPPConnect (LGPL-3.0): also browser-based, stricter license.
|
|
- venom-bot: no npm release since November 2024.
|
|
- open-wa: Hippocratic license, not an open-source license in the OSI sense.
|
|
- WhatsApp Business Cloud API: needs a business account and a public webhook, so it does not
|
|
fit a local app.
|