whatsapp-web-cli 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "whatsapp-web-cli",
+  "version": "0.1.0",
+  "description": "A local WhatsApp Web CLI for agents and scripts.",
+  "type": "module",
+  "bin": {
+    "wwa": "./dist/wwa.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "wwa": "node --no-deprecation ./dist/wwa.js",
+    "typecheck": "tsc --noEmit",
+    "build": "bun build ./bin/wwa.ts --target=node --outdir=dist --external @aws-sdk/client-s3",
+    "lint": "tsc --noEmit",
+    "prepack": "bun run typecheck && bun run build",
+    "pack:dry": "bun pm pack --dry-run"
+  },
+  "keywords": [
+    "whatsapp",
+    "whatsapp-web",
+    "cli",
+    "agent",
+    "codex"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "mime-types": "^3.0.2",
+    "qrcode": "^1.5.4",
+    "qrcode-terminal": "^0.12.0",
+    "whatsapp-web.js": "1.34.6",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.3",
+    "@types/mime-types": "^3.0.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/qrcode-terminal": "^0.12.2",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/whatsapp-cli/SKILL.md

@@ -0,0 +1,112 @@
+# WhatsApp CLI
+
+Use this skill when the user wants to inspect or send WhatsApp messages through the local `wwa` CLI.
+
+## Rules
+
+- Use `wwa` as the low-level WhatsApp control surface.
+- Treat the installed/built `wwa` binary as a Node runtime CLI. The project may use Bun for install/build, but `whatsapp-web.js` should run under Node.
+- Never bypass `wwa` or `whatsapp-web.js` by scraping WhatsApp Web DOM, reading browser IndexedDB/cache, using Chrome DevTools/CDP, or poking Puppeteer internals directly.
+- If the CLI gets stuck, reset with `wwa daemon stop --json`, then restart/login through `wwa`; fix the CLI wrapper if needed instead of creating a shortcut around it.
+- The daemon should run one headless browser session only. Do not set `WWA_HEADLESS=false` unless the user explicitly wants a visible browser for debugging.
+- Do not use MCP for this workflow unless the user explicitly asks for an MCP implementation.
+- Do not add classification or reply-generation behavior to the CLI; those are higher-level workflows.
+- `wwa transcribe` and `wwa tts` are available when `OPENAI_API_KEY` is configured. Classification and reply drafting still belong in the agent/workflow layer.
+- For voice notes, use `wwa send audio --voice` or `wwa reply audio --voice`. If the local audio is MP3, AIFF, WAV, or another non-OGG format, the CLI converts it to OGG/Opus with `ffmpeg` before sending.
+- For generated speech, prefer `wwa tts --text "..." --to <chatId> --json`. This command uses OpenAI `gpt-4o-mini-tts` with voice `nova`, then sends the generated MP3 as a WhatsApp voice note.
+- For transcription, prefer `wwa transcribe --message <messageId> --json`. It saves media through `wwa`, normalizes WhatsApp `.oga` voice notes to `.ogg`, and uses OpenAI `gpt-4o-mini-transcribe`.
+- For generated replies, draft first and ask for confirmation before sending unless the user explicitly requested auto-send.
+- Prefer `--json` for commands that return structured data.
+- Start with the user's actual data command, such as `wwa chat-search "<name>" --json`. Data commands auto-start the daemon and wait for readiness.
+- If a data command returns `ok: false` with `nextCommand`, run that command instead of manually guessing a recovery path. For login, this should usually be `wwa auth login --image --json`.
+- Prefer `wwa events next --chat <chatId> --incoming --timeout 120 --json` for turn-by-turn live conversation. It waits for one new matching event, prints it, and exits.
+- Use `wwa events tail --jsonl` only when the user explicitly wants a long-running stream. `tail` starts from new events by default, so do not replace it with repeated `events list --since ...` polling for realtime replies.
+- When several messages arrive quickly in the same chat, coalesce the newest burst and answer the latest user intent. Do not respond to each stale queued message one by one.
+- For auth, prefer `wwa auth qr --image --json` and render the returned `imagePath` for the user. This is easier to scan than terminal QR text.
+- QR image auth should not require opening a visible Chrome window; the CLI saves the image from the QR payload emitted by `whatsapp-web.js`.
+- `wwa auth qr` waits up to 30 seconds for a QR by default; do not manually retry immediately unless it times out.
+- Heavy WhatsApp accounts can have hundreds of unread chats. Use `wwa unread --limit 20 --json` for a quick first pass, then fetch messages for selected chats.
+- Chat listing can take a while on first sync after login. Wait for the command to finish instead of interrupting early.
+- If a stateful command says login is required, run `wwa auth login --image --json`, render the returned `imagePath`, let the user scan it, then retry the original command.
+- Do not require `wwa doctor` or `wwa ready` in normal usage; keep them for diagnostics only.
+- If `phase` is `failed`, `UNLAUNCHED`, or a browser profile lock is reported, run `wwa daemon stop --json`, then `wwa auth login --image --json`.
+
+## Common Commands
+
+```bash
+wwa daemon start --json
+wwa daemon status --json
+wwa auth login --image --json
+wwa auth qr --image --json
+wwa auth status --json
+wwa chat-search "<query>" --json
+wwa message-search "<query>" --limit-chats 20 --messages-per-chat 50 --json
+wwa message-search "<query>" --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 messages get --id <messageId> --json
+wwa events list --since 24h --json
+wwa events next --chat <chatId> --incoming --timeout 120 --json
+wwa events tail --jsonl
+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." --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
+```
+
+## Workflow Guidance
+
+To review unread messages, list a bounded set of unread chats, fetch recent messages per chat, and save media only when needed. If an audio attachment is saved, use `wwa transcribe --message <messageId> --json`.
+
+To find a person or conversation, prefer:
+
+```bash
+wwa chat-search "<name or phone fragment>" --json
+```
+
+To find text in recent messages, prefer:
+
+```bash
+wwa message-search "<text>" --limit-chats 20 --messages-per-chat 50 --json
+```
+
+If you already know the chat ID, narrow the message search:
+
+```bash
+wwa message-search "<text>" --chat <chatId> --json
+```
+
+Golden path for agents:
+
+```bash
+wwa chat-search "<name>" --json
+wwa auth login --image --json
+wwa chat-search "<name>" --json
+```
+
+Use the returned `nextCommand` when it is present. After `auth login`, render the returned `imagePath`, wait for the user to scan it, and retry the original command.
+
+Live conversation loop:
+
+```bash
+wwa events next --chat <chatId> --incoming --timeout 120 --json
+```
+
+For each turn, wait for `events next`, answer the returned event's newest user intent, then run `wwa reply text --message <messageId> --body "..." --json`. Do not use `--replay` unless the user explicitly wants to process stored history.
+
+When showing auth to the user in Codex, run:
+
+```bash
+wwa auth login --image --json
+```
+
+Then render the `imagePath` as an image in the response. If it reports `connected: true`, skip QR display and continue with `wwa auth status --json`.