whatsapp-web-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# WhatsApp Web CLI
+
+`wwa` is a local WhatsApp Web CLI for agents and scripts. It uses `whatsapp-web.js`, persists auth locally, exposes JSON-friendly commands, and keeps realtime state in a local daemon.
+
+## Requirements
+
+- Node.js 22+
+- Bun 1.3+ for local install/build tasks
+- ffmpeg for `wwa send audio --voice` / `wwa reply audio --voice` conversion when the input is not already OGG/Opus
+- macOS/Linux with a local Chromium/Puppeteer-compatible environment
+- A WhatsApp account that can link WhatsApp Web
+
+The package is managed and built with Bun, but the published `wwa` binary runs on Node. This keeps `whatsapp-web.js`/Puppeteer on the runtime they support best.
+
+## Install
+
+From a published package:
+
+```bash
+npm install -g whatsapp-web-cli
+```
+
+or:
+
+```bash
+bun install -g whatsapp-web-cli
+```
+
+From this local folder:
+
+```bash
+bun install
+bun run build
+bun link
+```
+
+Then run the command you actually need:
+
+```bash
+wwa chat-search "Name" --json
+```
+
+If WhatsApp is not logged in, data commands return a JSON object like:
+
+```json
+{
+  "ok": false,
+  "ready": false,
+  "message": "You need to login. Run `wwa auth login --image --json`.",
+  "nextCommand": "wwa auth login --image --json"
+}
+```
+
+Run that login command, render/open the returned `imagePath`, and scan it in
+WhatsApp > Linked Devices. After scanning, run the original command again:
+
+```bash
+wwa auth login --image --json
+wwa chat-search "Name" --json
+```
+
+There is no required `doctor` or `ready` step in normal usage. Data commands
+auto-start the daemon and wait for readiness after auth is scanned.
+
+## Common Flow
+
+```bash
+wwa chat-search "Gardelin" --json
+wwa message-search "Aaah" --chat <chatId> --json
+wwa unread --limit 20 --json
+```
+
+## Common Commands
+
+```bash
+wwa daemon start --json
+wwa daemon stop --json
+wwa daemon status --json
+
+wwa auth login --image --json
+wwa auth status --json
+wwa auth logout --json
+
+wwa ready --wait 120 --json
+wwa doctor --json
+
+wwa chat-search "name or text" --json
+wwa message-search "message text" --limit-chats 20 --messages-per-chat 50 --json
+wwa message-search "message text" --chat <chatId> --json
+
+wwa unread --limit 20 --json
+wwa unread messages --limit-chats 10 --messages-per-chat 5 --json
+wwa chats list --unread --limit 20 --json
+
+wwa messages list --chat <chatId> --limit 50 --json
+wwa events list --since 24h --json
+wwa events next --chat <chatId> --incoming --timeout 120 --json
+wwa events tail --chat <chatId> --incoming --jsonl
+wwa media save --message <messageId> --json
+wwa transcribe --message <messageId> --json
+wwa transcribe --file ./audio.oga --json
+wwa tts --text "Mensagem em voz natural." --out /tmp/voice.mp3 --json
+wwa tts --text "Mensagem em voz natural." --to <chatId> --json
+wwa send text --to <chatId> --body "..."
+wwa send media --to <chatId> --file ./image.png --caption "..."
+wwa send audio --to <chatId> --file ./note.ogg --voice
+wwa reply text --message <messageId> --body "..."
+wwa reply media --message <messageId> --file ./file.pdf --as-document
+wwa reply audio --message <messageId> --file ./note.ogg --voice
+```
+
+`events tail` follows new events from the end of the log by default. Use
+`--replay` only when you intentionally want to replay stored history before
+following new events.
+
+`events next` is the best primitive for agents that need to answer live
+messages. It waits for one matching event, prints it, and exits. It also starts
+from the end of the event log by default, so agents do not accidentally answer
+old messages unless `--replay` is explicitly provided.
+
+Media commands send existing local files only. Classification and reply drafting
+belong in a higher-level agent workflow.
+When `--voice` is used with an MP3, AIFF, WAV, or other non-OGG audio file,
+`wwa` converts it to OGG/Opus with `ffmpeg` before sending.
+
+## OpenAI TTS Workflow
+
+For higher-quality voice notes, use `wwa tts` instead of macOS `say`. It calls
+OpenAI text-to-speech with `gpt-4o-mini-tts` and voice `nova`, writes an MP3
+locally, then optionally sends it as a WhatsApp voice note.
+
+```bash
+wwa tts --text "Mensagem em voz natural." --out /tmp/voice.mp3 --voice nova --json
+wwa tts --text "Mensagem em voz natural." --to <chatId> --json
+```
+
+The command reads `OPENAI_API_KEY` from `.env.local`, `.env`, or the process
+environment.
+
+## OpenAI Transcription Workflow
+
+To transcribe WhatsApp audio without hand-normalizing file extensions:
+
+```bash
+wwa transcribe --message <messageId> --json
+wwa transcribe --file ~/.wwa/default/media/audio.oga --json
+wwa transcribe --message <messageId> --to <chatId> --json
+```
+
+The command saves media when given a message ID, renames WhatsApp `.oga` voice
+notes to `.ogg` for OpenAI compatibility, and uses `gpt-4o-mini-transcribe` by
+default.
+
+## Runtime Data
+
+The default profile stores runtime state under:
+
+```text
+~/.wwa/default/
+```
+
+Auth persists across daemon restarts in:
+
+```text
+~/.wwa/default/auth/
+```
+
+You should only need to scan a QR again if WhatsApp invalidates the linked device, you run `wwa auth logout`, or the auth folder is removed/corrupted.
+
+## Codex Skill
+
+The generic skill lives at:
+
+```text
+skills/whatsapp-cli/SKILL.md
+```
+
+It teaches agents to use the CLI directly, without MCP, and keeps transcription/classification workflows outside the low-level CLI.