whatsapp-web-cli 0.2.0 → 0.2.2

package/README.md

@@ -74,6 +74,28 @@ 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.
 
+If the first run fails before a QR appears because Puppeteer cannot find or
+launch Chrome-for-Testing, run the browser recovery command recommended by the
+CLI:
+
+```bash
+wwa recover browser --json
+```
+
+On macOS, if that reports a launch failure for the downloaded
+Chrome-for-Testing app, explicitly allow the CLI to clear quarantine metadata
+from that isolated test browser:
+
+```bash
+wwa recover browser --clear-quarantine --json
+```
+
+Then retry:
+
+```bash
+wwa auth login --image --json
+```
+
 ## Common Flow
 
 ```bash
@@ -95,6 +117,8 @@ wwa auth logout --json
 
 wwa ready --wait 120 --json
 wwa doctor --json
+wwa doctor --browser --json
+wwa recover browser --json
 
 wwa chat-search "name or text" --json
 wwa message-search "message text" --limit-chats 20 --messages-per-chat 50 --json

package/dist/wwa.js

@@ -326995,6 +326995,7 @@ import { copyFile as copyFile2, mkdir as mkdir5 } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname7, join as join2, resolve as resolve9 } from "node:path";
+import { createRequire as createRequire2 } from "node:module";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/daemon.ts
@@ -341287,7 +341288,6 @@ import { readFile as readFile2, writeFile as writeFile3 } from "node:fs/promises
 import { basename as basename2, resolve as resolve5 } from "node:path";
 import { promisify } from "node:util";
 var { Client, LocalAuth, MessageMedia } = import_whatsapp_web.default;
-var HEADLESS = process.env.WWA_HEADLESS !== "false";
 var execFileAsync = promisify(execFile);
 
 class WhatsAppClient {
@@ -341306,7 +341306,7 @@ class WhatsAppClient {
       authTimeoutMs: 120000,
       ...process.env.WWA_USER_AGENT ? { userAgent: process.env.WWA_USER_AGENT } : {},
       puppeteer: {
-        headless: HEADLESS,
+        headless: true,
         args: ["--no-sandbox", "--disable-setuid-sandbox"]
       }
     });
@@ -341421,6 +341421,35 @@ class WhatsAppClient {
     const messages = chat.messages;
     return messages.map((message) => this.serializeMessage(message, chatId));
   }
+  async listUnreadMessages() {
+    await this.assertReady();
+    const chats = (await this.client.getChats()).filter((chat) => chat.unreadCount > 0);
+    const results2 = [];
+    for (const chat of chats) {
+      const serializedChat = this.serializeChat(chat);
+      try {
+        const messages = await this.getUnreadMessagesFromPage(chat.id._serialized, chat.unreadCount);
+        results2.push({
+          chat: serializedChat,
+          messages,
+          unreadCount: chat.unreadCount,
+          returnedCount: messages.length,
+          complete: messages.length >= chat.unreadCount
+        });
+      } catch (error51) {
+        const fallback = chat.lastMessage && !chat.lastMessage.fromMe ? [this.serializeMessage(chat.lastMessage, chat.id._serialized)] : [];
+        results2.push({
+          chat: serializedChat,
+          messages: fallback,
+          unreadCount: chat.unreadCount,
+          returnedCount: fallback.length,
+          complete: fallback.length >= chat.unreadCount,
+          error: error51 instanceof Error ? error51.message : String(error51)
+        });
+      }
+    }
+    return results2;
+  }
   async getMessage(messageId) {
     await this.assertReady();
     const message = await this.client.getMessageById(messageId);
@@ -341570,6 +341599,70 @@ class WhatsAppClient {
       throw firstError;
     }
   }
+  async getUnreadMessagesFromPage(chatId, unreadCount) {
+    const client = this.client;
+    return client.pupPage.evaluate(async (rawChatId, rawUnreadCount) => {
+      const chatId2 = String(rawChatId);
+      const unreadCount2 = Number(rawUnreadCount);
+      const toSerialized = (value) => {
+        if (!value)
+          return null;
+        if (typeof value === "string")
+          return value;
+        if (typeof value === "object" && "_serialized" in value && typeof value._serialized === "string")
+          return value._serialized;
+        return null;
+      };
+      const messageId = (message) => {
+        if (message.id?._serialized)
+          return message.id._serialized;
+        const remote = toSerialized(message.id?.remote);
+        return `${message.id?.fromMe ? "true" : "false"}_${remote ?? chatId2}_${message.id?.id ?? ""}`;
+      };
+      const serializeMessage = (message) => {
+        const id = message.id;
+        const hasMedia = Boolean(message.directPath);
+        return {
+          id: messageId({ id }),
+          from: toSerialized(message.from) ?? "",
+          to: toSerialized(message.to) ?? "",
+          author: toSerialized(message.author),
+          body: String(hasMedia ? message.caption ?? "" : message.body ?? message.pollName ?? message.eventName ?? ""),
+          timestamp: Number(message.t ?? 0),
+          type: String(message.type ?? "unknown"),
+          fromMe: Boolean(id?.fromMe),
+          hasMedia,
+          duration: message.duration ?? null,
+          chatId: chatId2
+        };
+      };
+      const isIncomingUserMessage = (message) => {
+        return !message.isNotification && !message.id?.fromMe;
+      };
+      const readModels = (chat2) => {
+        return chat2.msgs?.getModelsArray?.() ?? [];
+      };
+      const store = window.Store;
+      const chatWid = store.WidFactory.createWid(chatId2);
+      const chat = store.Chat.get(chatWid) || store.Chat.get(chatId2) || await store.Chat.find(chatWid) || await store.Chat.find(chatId2);
+      if (!chat?.msgs)
+        throw new Error(`Chat messages are not available for ${chatId2}`);
+      let messages = readModels(chat).filter(isIncomingUserMessage);
+      let previousLength = -1;
+      while (messages.length < unreadCount2 && messages.length !== previousLength) {
+        previousLength = messages.length;
+        const loader = store.ConversationMsgs;
+        const loadEarlier = loader?.loadEarlierMsgs || loader?.loadEarlierMsgsFromChat || loader?.loadEarlierMessages || loader?.loadEarlier;
+        if (typeof loadEarlier !== "function")
+          break;
+        const loaded = await loadEarlier(chat, chat.msgs);
+        if (!loaded?.length)
+          break;
+        messages = readModels(chat).filter(isIncomingUserMessage);
+      }
+      return messages.sort((a, b) => Number(a.t ?? 0) - Number(b.t ?? 0)).slice(-unreadCount2).map(serializeMessage);
+    }, chatId, unreadCount);
+  }
   async findChat(chatId) {
     try {
       return await this.client.getChatById(chatId);
@@ -341636,12 +341729,17 @@ function recommendationFor(phase, lastError) {
     return "Authenticate with `wwa auth login --image --json` and render the returned imagePath.";
   if (phase === "authenticated_loading")
     return "Wait with `wwa ready --wait 120 --json` before reading chats or messages.";
+  if (phase === "failed" && isBrowserLaunchError(lastError))
+    return "Browser automation failed. Run `wwa recover browser --json`, then retry.";
   if (phase === "failed" && lastError?.includes("already running"))
     return "Browser profile lock detected. Run `wwa daemon stop --json`, then retry.";
   if (phase === "failed")
     return "Inspect `wwa doctor --json`, then restart with `wwa daemon stop --json && wwa daemon start --json`.";
   return "Starting. Wait with `wwa ready --wait 120 --json`.";
 }
+function isBrowserLaunchError(lastError) {
+  return Boolean(lastError && /Could not find Chrome|Browser was not found|Failed to launch|chrome-headless-shell|Chrome for Testing|executablePath|puppeteer/i.test(lastError));
+}
 async function mediaFromFile(filePath, options) {
   const resolved = options.asVoice ? await ensureVoiceNoteAudio(filePath) : resolve5(filePath);
   const data = await readFile2(resolved);
@@ -341798,6 +341896,9 @@ async function runDaemon() {
         const limit = Number(url2.searchParams.get("limit") ?? 50);
         return json2(await client.listMessages(chatId, Number.isFinite(limit) ? limit : 50));
       }
+      if (request.method === "GET" && url2.pathname === "/unread/messages") {
+        return json2(await client.listUnreadMessages());
+      }
       if (request.method === "GET" && url2.pathname === "/message-search") {
         const query = url2.searchParams.get("query");
         if (!query)
@@ -342084,7 +342185,7 @@ async function startDaemon() {
     const child = spawn(process.execPath, [...process.execArgv, process.argv[1] ?? "./bin/wwa.ts", "__daemon"], {
       detached: true,
       stdio: ["ignore", logFd, logFd],
-      env: process.env
+      env: daemonEnv()
     });
     child.unref();
     const deadline = Date.now() + START_TIMEOUT_MS;
@@ -342094,7 +342195,9 @@ async function startDaemon() {
         return status;
       await sleep(250);
     }
-    throw new Error(`Timed out starting daemon. See ${paths.logs}`);
+    const logTail = await readLogTail();
+    const recovery = isBrowserLaunchError2(logTail) ? " Run `wwa recover browser --json`, then retry." : "";
+    throw new Error(`Timed out starting daemon. See ${paths.logs}.${recovery}`);
   });
 }
 async function stopDaemon() {
@@ -342225,6 +342328,26 @@ async function removeStartLock() {
     await unlink2(paths.daemonLock);
   } catch {}
 }
+function daemonEnv() {
+  const env2 = { ...process.env };
+  if (env2.WWA_ALLOW_SYSTEM_CHROME !== "true") {
+    delete env2.PUPPETEER_EXECUTABLE_PATH;
+    delete env2.PUPPETEER_BROWSER_REVISION;
+  }
+  delete env2.WWA_HEADLESS;
+  return env2;
+}
+async function readLogTail() {
+  try {
+    const raw = await readFile4(paths.logs, "utf8");
+    return raw.slice(-8000);
+  } catch {
+    return "";
+  }
+}
+function isBrowserLaunchError2(text) {
+  return /Could not find Chrome|Browser was not found|Failed to launch|chrome-headless-shell|Chrome for Testing|executablePath|puppeteer/i.test(text);
+}
 function listRuntimeProcesses() {
   const output = spawnSync("ps", ["axo", "pid=,pgid=,command="], {
     encoding: "utf8"
@@ -342488,13 +342611,14 @@ async function generateSpeech(options) {
 }
 
 // src/cli.ts
+var requireFromHere = createRequire2(import.meta.url);
 async function main(argv) {
   if (argv[2] === "__daemon") {
     await runDaemon();
     return;
   }
   const program2 = new Command;
-  program2.name("wwa").description("Local WhatsApp Web CLI for agents and scripts.").version("0.1.0");
+  program2.name("wwa").description("Local WhatsApp Web CLI for agents and scripts.").version("0.2.2");
   const daemon = program2.command("daemon").description("Manage the local WhatsApp daemon.");
   daemon.command("start").description("Start the local daemon.").option("--json", "Print JSON output.").action(async (options) => {
     const status = await startDaemon();
@@ -342791,20 +342915,13 @@ async function main(argv) {
     const result = filterChats(chats2, options).map(summarizeChat);
     output(options, result, result);
   });
-  unread.command("messages").description("List recent messages for bounded unread chats.").option("--limit-chats <count>", "Maximum unread chats to inspect.", "10").option("--messages-per-chat <count>", "Maximum messages per chat.", "5").option("--groups", "Only inspect group chats.").option("--non-groups", "Only inspect direct chats.").option("--include-status", "Include status broadcast chats if present.").option("--json", "Print JSON output.").action(async (options) => {
+  unread.command("messages").description("List unread messages grouped by unread chat.").option("--limit-chats <count>", "Maximum unread chats to inspect.", "10").option("--groups", "Only inspect group chats.").option("--non-groups", "Only inspect direct chats.").option("--include-status", "Include status broadcast chats if present.").option("--json", "Print JSON output.").action(async (rawOptions, command2) => {
+    const options = mergeCommandOptions(rawOptions, command2);
     if (!await ensureReady(options))
       return;
-    const chats2 = await daemonRequestExisting("/chats?unread=true");
-    const selected = filterChats(chats2, { ...options, limit: options.limitChats });
-    const messagesPerChat = parseNumber(options.messagesPerChat, 5);
-    const result = [];
-    for (const chat of selected) {
-      const messages2 = await daemonRequestExisting(`/messages?chatId=${encodeURIComponent(chat.id)}&limit=${messagesPerChat}`);
-      result.push({
-        chat: summarizeChat(chat),
-        messages: messages2.map(summarizeMessage)
-      });
-    }
+    const unreadResults = await daemonRequestExisting("/unread/messages");
+    const selected = filterUnreadMessageResults(unreadResults, { ...options, limit: options.limitChats });
+    const result = selected.map(summarizeUnreadMessagesResult);
     output(options, result, result);
   });
   program2.command("ready").description("Wait until WhatsApp is connected and ready for chat/message commands.").option("--wait <seconds>", "Maximum seconds to wait.", "120").option("--json", "Print JSON output.").action(async (options) => {
@@ -342816,13 +342933,14 @@ async function main(argv) {
     if (!result.ready)
       process.exitCode = 1;
   });
-  program2.command("doctor").description("Diagnose daemon/auth readiness and recommend the next command.").option("--json", "Print JSON output.").action(async (options) => {
+  program2.command("doctor").description("Diagnose daemon/auth readiness and recommend the next command.").option("--browser", "Also check the Puppeteer Chrome-for-Testing setup.").option("--json", "Print JSON output.").action(async (options) => {
     const status = await daemonStatus();
     const browserLocks = listBrowserLocks();
     const result = {
       ok: Boolean(status?.ready),
       daemon: status ?? { running: false },
       browserLocks,
+      ...options.browser ? { browser: await browserDiagnostics(false) } : {},
       paths,
       nextCommand: nextCommand(status, browserLocks.length)
     };
@@ -342831,6 +342949,22 @@ async function main(argv) {
   program2.command("paths").description("Show local runtime paths.").option("--json", "Print JSON output.").action((options) => {
     output(options, paths, paths);
   });
+  const recover = program2.command("recover").description("Run targeted recovery steps after a wwa failure.");
+  recover.command("browser").description("Recover Puppeteer's Chrome-for-Testing install after a browser launch failure.").option("--clear-quarantine", "On macOS, clear quarantine metadata from the downloaded test browser before the smoke test.").option("--json", "Print JSON output.").action(async (options) => {
+    const install = installPuppeteerBrowser();
+    const quarantine = options.clearQuarantine ? clearBrowserQuarantine() : null;
+    const diagnostics = await browserDiagnostics(true);
+    const result = {
+      ok: install.ok && diagnostics.launch.ok,
+      install,
+      quarantine,
+      browser: diagnostics,
+      nextCommand: diagnostics.launch.ok ? "wwa auth login --image --json" : browserSetupNextCommand(diagnostics)
+    };
+    output(options, result, result);
+    if (!result.ok)
+      process.exitCode = 1;
+  });
   const skill = program2.command("skill").description("Install helper files for agent integrations.");
   skill.command("install").description("Install the bundled Codex skill into a local Codex skills directory.").option("--dir <path>", "Codex skills directory.", join2(homedir2(), ".codex", "skills")).option("--name <name>", "Installed skill directory name.", "whatsapp-cli").option("--json", "Print JSON output.").action(async (options) => {
     const result = await installCodexSkill(options);
@@ -342978,7 +343112,27 @@ function mediaCommandBody(options) {
 }
 function filterChats(chats, options) {
   const limit = options.limit ? parseNumber(options.limit, chats.length) : chats.length;
-  return chats.filter((chat) => options.includeStatus ? true : chat.id !== "status@broadcast").filter((chat) => options.groups ? chat.isGroup : true).filter((chat) => options.nonGroups ? !chat.isGroup : true).slice(0, limit);
+  const groups = booleanOption(options, "groups");
+  const nonGroups = booleanOption(options, "nonGroups");
+  const includeStatus = booleanOption(options, "includeStatus");
+  return chats.filter((chat) => includeStatus ? true : chat.id !== "status@broadcast").filter((chat) => groups ? chat.isGroup : true).filter((chat) => nonGroups ? !chat.isGroup : true).slice(0, limit);
+}
+function booleanOption(options, key2) {
+  return Boolean(options[key2] ?? options[key2.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)]);
+}
+function mergeCommandOptions(options, command2) {
+  return {
+    ...options.parent?.opts?.() ?? {},
+    ...command2?.parent?.opts?.() ?? {},
+    ...options.opts?.() ?? {},
+    ...command2?.opts?.() ?? {},
+    ...options
+  };
+}
+function filterUnreadMessageResults(results2, options) {
+  const chats = filterChats(results2.map((result) => result.chat), options);
+  const allowedChatIds = new Set(chats.map((chat) => chat.id));
+  return results2.filter((result) => allowedChatIds.has(result.chat.id));
 }
 function summarizeChat(chat) {
   return {
@@ -343007,6 +343161,16 @@ function summarizeMessage(message) {
     timestamp: message.timestamp
   };
 }
+function summarizeUnreadMessagesResult(result) {
+  return {
+    chat: summarizeChat(result.chat),
+    unreadCount: result.unreadCount,
+    returnedCount: result.returnedCount,
+    complete: result.complete,
+    ...result.error ? { error: result.error } : {},
+    messages: result.messages.map(summarizeMessage)
+  };
+}
 function summarizeMessageSearchResult(result) {
   return {
     chat: summarizeChat(result.chat),
@@ -343051,6 +343215,152 @@ function readinessMessage(status, browserLockCount) {
     return "WhatsApp is not healthy. Run `wwa daemon stop --json && wwa auth login --image --json`.";
   return "WhatsApp is still loading. Run the same wwa command again in a moment.";
 }
+function puppeteerChromeRevision() {
+  const puppeteer = getPuppeteer();
+  const revisions = puppeteer.PUPPETEER_REVISIONS;
+  return revisions?.chrome ?? revisionFromExecutablePath(puppeteerExecutablePath()) ?? "stable";
+}
+function puppeteerExecutablePath() {
+  try {
+    return withSanitizedPuppeteerEnv(() => getPuppeteer().executablePath());
+  } catch (error51) {
+    return error51 instanceof Error ? error51.message : String(error51);
+  }
+}
+function puppeteerCliPath() {
+  return requireFromHere.resolve("puppeteer/lib/cjs/puppeteer/node/cli.js");
+}
+function installPuppeteerBrowser() {
+  const revision = puppeteerChromeRevision();
+  const cliPath = puppeteerCliPath();
+  const result = spawnSync2(process.execPath, [cliPath, "browsers", "install", `chrome@${revision}`], {
+    encoding: "utf8",
+    env: sanitizedPuppeteerEnv()
+  });
+  return {
+    ok: result.status === 0,
+    revision,
+    command: `${process.execPath} ${cliPath} browsers install chrome@${revision}`,
+    stdout: trimOutput(result.stdout),
+    stderr: trimOutput(result.stderr),
+    exitCode: result.status
+  };
+}
+async function browserDiagnostics(smoke) {
+  const revision = puppeteerChromeRevision();
+  const executablePath = puppeteerExecutablePath();
+  const exists = typeof executablePath === "string" && existsSync(executablePath);
+  const appPath = typeof executablePath === "string" ? chromeAppPath(executablePath) : null;
+  return {
+    revision,
+    executablePath,
+    exists,
+    appPath,
+    platform: process.platform,
+    launch: smoke ? await smokeTestPuppeteerLaunch() : { ok: null, skipped: true }
+  };
+}
+async function smokeTestPuppeteerLaunch() {
+  const puppeteer = getPuppeteer();
+  let browser = null;
+  try {
+    browser = await withSanitizedPuppeteerEnv(() => puppeteer.launch({
+      headless: true,
+      args: ["--no-sandbox", "--disable-setuid-sandbox"]
+    }));
+    return { ok: true, error: null };
+  } catch (error51) {
+    return {
+      ok: false,
+      error: error51 instanceof Error ? error51.message : String(error51)
+    };
+  } finally {
+    await browser?.close().catch(() => {
+      return;
+    });
+  }
+}
+function getPuppeteer() {
+  return withSanitizedPuppeteerEnv(() => requireFromHere("puppeteer"));
+}
+function sanitizedPuppeteerEnv() {
+  const env2 = { ...process.env };
+  if (env2.WWA_ALLOW_SYSTEM_CHROME !== "true") {
+    delete env2.PUPPETEER_EXECUTABLE_PATH;
+    delete env2.PUPPETEER_BROWSER_REVISION;
+  }
+  delete env2.WWA_HEADLESS;
+  return env2;
+}
+function withSanitizedPuppeteerEnv(fn) {
+  if (process.env.WWA_ALLOW_SYSTEM_CHROME === "true")
+    return fn();
+  const executablePath = process.env.PUPPETEER_EXECUTABLE_PATH;
+  const browserRevision = process.env.PUPPETEER_BROWSER_REVISION;
+  const headless = process.env.WWA_HEADLESS;
+  delete process.env.PUPPETEER_EXECUTABLE_PATH;
+  delete process.env.PUPPETEER_BROWSER_REVISION;
+  delete process.env.WWA_HEADLESS;
+  try {
+    return fn();
+  } finally {
+    if (executablePath === undefined)
+      delete process.env.PUPPETEER_EXECUTABLE_PATH;
+    else
+      process.env.PUPPETEER_EXECUTABLE_PATH = executablePath;
+    if (browserRevision === undefined)
+      delete process.env.PUPPETEER_BROWSER_REVISION;
+    else
+      process.env.PUPPETEER_BROWSER_REVISION = browserRevision;
+    if (headless === undefined)
+      delete process.env.WWA_HEADLESS;
+    else
+      process.env.WWA_HEADLESS = headless;
+  }
+}
+function chromeAppPath(executablePath) {
+  const marker = ".app/Contents/MacOS/";
+  const index = executablePath.indexOf(marker);
+  if (index === -1)
+    return null;
+  return executablePath.slice(0, index + ".app".length);
+}
+function revisionFromExecutablePath(executablePath) {
+  const match = executablePath.match(/\/chrome\/[^/]+-(\d+\.\d+\.\d+\.\d+)\//);
+  return match?.[1] ?? null;
+}
+function clearBrowserQuarantine() {
+  if (process.platform !== "darwin") {
+    return { ok: false, skipped: true, reason: "Quarantine metadata is only a macOS concern." };
+  }
+  const executablePath = puppeteerExecutablePath();
+  const appPath = typeof executablePath === "string" ? chromeAppPath(executablePath) : null;
+  if (!appPath)
+    return { ok: false, skipped: true, reason: "Could not locate Chrome-for-Testing .app path.", executablePath };
+  const result = spawnSync2("xattr", ["-dr", "com.apple.quarantine", appPath], {
+    encoding: "utf8"
+  });
+  return {
+    ok: result.status === 0,
+    appPath,
+    command: `xattr -dr com.apple.quarantine ${JSON.stringify(appPath)}`,
+    stdout: trimOutput(result.stdout),
+    stderr: trimOutput(result.stderr),
+    exitCode: result.status
+  };
+}
+function browserSetupNextCommand(diagnostics) {
+  if (process.platform === "darwin" && diagnostics.appPath)
+    return "wwa recover browser --clear-quarantine --json";
+  return "wwa doctor --browser --json";
+}
+function trimOutput(value) {
+  const text = (value ?? "").trim();
+  if (text.length <= 4000)
+    return text;
+  return `${text.slice(0, 4000)}
+...truncated...`;
+}
 
 // bin/wwa.ts
 await main(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-web-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A local WhatsApp Web CLI for agents and scripts.",
   "type": "module",
   "bin": {
@@ -35,6 +35,7 @@
   "dependencies": {
     "commander": "^14.0.2",
     "mime-types": "^3.0.2",
+    "puppeteer": "^24.38.0",
     "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "whatsapp-web.js": "1.34.6",

package/skills/whatsapp-cli/SKILL.md

@@ -65,7 +65,7 @@ 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 review unread messages, use `wwa unread messages --json` so the CLI returns unread messages grouped by chat with `unreadCount`, `returnedCount`, and `complete`. If `complete` is false, WhatsApp Web did not expose every unread message to the local session; treat the row as partial instead of assuming the latest message is the whole unread burst. If an audio attachment is returned, use `wwa transcribe --message <messageId> --json`.
 
 To find a person or conversation, prefer: