@wirecat/whatsapp-cli 0.4.0 → 0.7.0

package/dist/session.js

@@ -0,0 +1,136 @@
+import { existsSync, rmSync } from "node:fs";
+import { CliError, indent } from "@wirecat/cli-base";
+import { atTerminal, loginQr, readSecret } from "@wirecat/cli-core";
+import { asFirstWord, environmentOf, secretInputOf, } from "@wirecat/cli-core/cli";
+import { linkDevice } from "./messenger.js";
+import { privateStore } from "./paths.js";
+/**
+ * Shown once, before the code that links the device. It ignores `--quiet` the way the QR code does: it belongs to
+ * the prompt the person is answering, and after the link it is too late to read it.
+ */
+export const BAN_WARNING = [
+    "Before you link: wa is not an official WhatsApp app, and WhatsApp may ban an account that uses one.",
+    "It also bans accounts that send in bulk or write to people who do not know them.",
+    "wa writes only when a command asks, sends at most 30 messages an hour by default, and holds every",
+    "write when WhatsApp says to slow down or restricts the account. Never send in bulk or to strangers.",
+].join("\n");
+/** The phone pushes its history right after linking, once; how long to keep receiving it. */
+export const HISTORY_WAIT = { firstMs: 120_000, quietMs: 45_000, slowMs: 20_000 };
+/**
+ * Saves what the phone pushes until it goes quiet or `signal` aborts. Live messages that arrive meanwhile are saved
+ * too, through the same connection.
+ */
+export const receiveHistory = async (adapter, wait, onSlow, signal) => {
+    const received = { chats: 0, messages: 0, people: 0 };
+    const stop = new AbortController();
+    const end = () => stop.abort();
+    let timer = setTimeout(end, wait.firstMs);
+    const slow = wait.slowMs === undefined ? undefined : setTimeout(onSlow, wait.slowMs);
+    signal?.addEventListener("abort", end, { once: true });
+    try {
+        await Promise.all([
+            adapter.feed?.((batch) => {
+                received.chats += batch.chats?.length ?? 0;
+                received.messages += batch.messages?.length ?? 0;
+                received.people += batch.people?.length ?? 0;
+                clearTimeout(slow);
+                clearTimeout(timer);
+                timer = setTimeout(end, wait.quietMs);
+            }, stop.signal),
+            adapter.watch?.(() => { }, stop.signal),
+        ]);
+    }
+    finally {
+        clearTimeout(slow);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", end);
+    }
+    return received;
+};
+/** Links the profile's device unless it is linked already, then keeps the history the phone pushes once. */
+export const startSession = async (command, context, { method, command: typed = "wa session start", signal, indent: pad = 0, stopEndsWait = false }) => {
+    const input = context.stdin;
+    const terminal = atTerminal(input);
+    const unanswerable = () => new CliError("validation_error", `${typed} asks questions — run it in a terminal`, {
+        reason: "input.required",
+    });
+    // A device that is linked already asks nothing, so only a profile without one is refused before the engine starts.
+    if (!terminal && method === "phone" && !existsSync(privateStore(context.profile, context.env)))
+        throw unanswerable();
+    const qr = loginQr({
+        diagnostic: context.streams.diagnostic,
+        note: context.renderer.note,
+        indent: pad,
+        terminal,
+        json: context.format !== "pretty",
+    });
+    const environment = environmentOf(command);
+    const linked = await linkDevice(command, context, {
+        method,
+        beforeLink: () => {
+            signal?.throwIfAborted();
+            if (!terminal && method === "phone")
+                throw unanswerable();
+            context.streams.diagnostic(indent(BAN_WARNING, pad));
+        },
+        phone: async () => {
+            if (!terminal)
+                throw new CliError("validation_error", `${typed} phone needs a terminal to ask for the number`, {
+                    reason: "input.required",
+                });
+            const number = await readSecret(`${" ".repeat(pad)}phone number, international format: `, {
+                ...secretInputOf(command),
+                echo: true,
+                ...(signal === undefined ? {} : { signal }),
+            });
+            // WhatsApp reads the leading digits as the country code, so a number typed without one pairs someone else's.
+            if (!number.trim().startsWith("+"))
+                throw new CliError("validation_error", "write the phone number with + and the country code, such as +34", {
+                    param: "phone",
+                    reason: "input.invalid",
+                });
+            return number;
+        },
+        onCode: ({ login, code }) => {
+            if (login === "pair") {
+                context.renderer.note(`pairing code: ${code}\n` +
+                    "On the phone: tap the WhatsApp notification, or Settings > Linked devices > Link a device >\n" +
+                    "Link with phone number instead, and type the code. It expires in about two minutes.");
+                return;
+            }
+            qr.show(code, "scan in WhatsApp → Settings → Linked devices → Link a device");
+        },
+    });
+    signal?.throwIfAborted();
+    const session = { profile: context.profile, account: linked.account, alreadyLinked: linked.alreadyLinked };
+    if (!linked.alreadyLinked) {
+        context.renderer.note("receiving history from the phone; keep WhatsApp open on it. Ctrl+C stops — `serve` picks up the rest.");
+        const stop = stopEndsWait ? environment.untilStopped?.() : environment.signal;
+        const ended = AbortSignal.any([signal, stop].filter((one) => one !== undefined));
+        session.received = await context.withMessenger((adapter) => receiveHistory(adapter, environment.historyWait ?? HISTORY_WAIT, () => context.renderer.note("still waiting for the phone's history — keep WhatsApp open on the phone; it can take a minute"), ended), { listen: true });
+    }
+    return session;
+};
+export const endSession = async (context) => {
+    const store = privateStore(context.profile, context.env);
+    if (!existsSync(store)) {
+        return { profile: context.profile, ended: false };
+    }
+    let dropped = false;
+    try {
+        await context.withMessenger((adapter) => adapter.logout());
+    }
+    catch (error) {
+        if (error instanceof CliError && error.details.reason === "device.in-use")
+            throw new CliError("provider_unavailable", `${error.message} — stop it first (\`wa ${asFirstWord(context.profile)}server stop\` for serve, or Ctrl+C ` +
+                "where it runs), then end the session", { ...error.details, sent: false });
+        // The phone may have removed the device already; the keys here are then worth nothing, and still go.
+        if (!(error instanceof CliError && error.code === "authentication_error"))
+            throw error;
+        dropped = true;
+    }
+    for (const suffix of ["", "-wal", "-shm", ".lock"])
+        rmSync(`${store}${suffix}`, { force: true });
+    return { profile: context.profile, ended: true, ...(dropped ? { alreadyDropped: true } : {}) };
+};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.7.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.7.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/whatsapp-cli",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "A personal WhatsApp account from the terminal, as a linked device — built for agents and scripts",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -34,6 +34,9 @@
     "test:matrix": "vitest run >/dev/null && pnpm build >/dev/null && cli-dev test-matrix --program dist/program.js --untested scripts/test-matrix-untested.ts --name wa --check",
     "test:slow": "vitest run --reporter=json --outputFile=coverage/tests.json >/dev/null; cli-dev slow-tests",
     "engine:test": "cd engine && unformatted=$(\"$(go env GOROOT)/bin/gofmt\" -l .) && { test -z \"$unformatted\" || { echo \"not gofmt-formatted: $unformatted\" >&2; exit 1; }; } && go vet ./... && go test ./...",
+    "bot:spec:sync": "node --experimental-strip-types scripts/bot/sync-spec.ts",
+    "bot:generate": "node --experimental-strip-types scripts/bot/generate.ts",
+    "bot:generate:check": "node --experimental-strip-types scripts/bot/generate.ts --check",
     "generate": "pnpm build && node --experimental-strip-types scripts/commands.ts",
     "smoke:bun": "bun run scripts/smoke.ts",
     "release:check": "pnpm build && node --experimental-strip-types scripts/release-check.ts",
@@ -50,6 +53,7 @@
     "docs:lint": "markdownlint-cli2",
     "docs:spell": "cspell lint --config cspell.json --no-progress README.md",
     "ci:quick": "pnpm typecheck && pnpm build && pnpm lint:commands",
+    "contracts:upgrade": "pnpm --dir contracts/previous install --frozen-lockfile --ignore-scripts && cli-contract contracts/upgrade.json",
     "contracts:check": "cli-contract contracts/plan.json",
     "security:no-leak": "cli-testing security no-leak . contracts/no-leak.json",
     "lint:commands": "cli-dev lint --cli dist/bin/wa.js",
@@ -57,18 +61,18 @@
     "engine:packages": "node scripts/engine-packages.mjs build"
   },
   "dependencies": {
-    "@wirecat/cli-base": "0.49.0",
-    "@wirecat/cli-core": "0.385.0",
+    "@wirecat/cli-base": "0.50.2",
+    "@wirecat/cli-core": "0.406.0",
     "commander": "15.0.0",
     "valibot": "1.5.0"
   },
   "optionalDependencies": {
-    "@wirecat/whatsapp-engine-darwin-arm64": "0.4.0",
-    "@wirecat/whatsapp-engine-darwin-x64": "0.4.0",
-    "@wirecat/whatsapp-engine-linux-arm64": "0.4.0",
-    "@wirecat/whatsapp-engine-linux-x64": "0.4.0",
-    "@wirecat/whatsapp-engine-win32-arm64": "0.4.0",
-    "@wirecat/whatsapp-engine-win32-x64": "0.4.0"
+    "@wirecat/whatsapp-engine-darwin-arm64": "0.7.0",
+    "@wirecat/whatsapp-engine-darwin-x64": "0.7.0",
+    "@wirecat/whatsapp-engine-linux-arm64": "0.7.0",
+    "@wirecat/whatsapp-engine-linux-x64": "0.7.0",
+    "@wirecat/whatsapp-engine-win32-arm64": "0.7.0",
+    "@wirecat/whatsapp-engine-win32-x64": "0.7.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
@@ -77,13 +81,14 @@
     "@cspell/dict-ru_ru": "2.3.3",
     "@types/node": "^22.20.4",
     "@vitest/coverage-v8": "^5.0.3",
-    "@wirecat/cli-testing": "0.5.2",
+    "@wirecat/cli-testing": "0.5.3",
     "cspell": "10.3.6",
     "lefthook": "2.1.16",
     "markdownlint-cli2": "0.23.3",
     "rumdl": "^0.2.79",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.3",
+    "yaml": "^2.9.1"
   },
   "publishConfig": {
     "access": "public"

package/skills/whatsapp-cli/SKILL.md

@@ -32,11 +32,11 @@ account, older history of one chat (`messages sync`), sending text (with `--repl
 `messages forward`, `messages transcribe --local`, `messages star|unstar`, `messages pin|unpin` (every pin tells the chat; `--expire-time 24h|7d|30d`), `reactions add|remove`,
 `polls create|show|vote|voters`, `chats mark-read`, `chats mute|unmute`, `chats archive|unarchive|pin|unpin|mark-unread`,
 `chats delete|clear` (they ask first; not over MCP),
-`account update` (name, about and a square JPEG photo), `metadata refresh` (a group's title and description, for
-`tags auto`), group admin
+`account update` (name, about and a square JPEG photo), `metadata sync` (a group's title and description, for
+`tags rebuild`), group admin
 (`chats create|join|leave|update`, a group photo by `chats update --photo` (a square JPEG of 190 to 720 pixels a
-side) or `--remove-photo`, `chats link show|reset`, `chats members list|fetch|add|remove`,
-`chats admins add|remove`, `chats requests list|accept|decline`), `contacts profile|block|unblock|lookup|sync`, `account privacy show|set`,
+side) or `--remove-photo`, `chats links show|reset`, `chats members list|fetch|add|remove`,
+`chats admins add|remove`, `chats requests list|confirm|reject`), `contacts info|block|unblock|lookup|sync`, `account privacy show|set`,
 `doctor --online`, `serve` and `watch`. Everything that reads the local store works.
 `account privacy set` has WhatsApp's settings only (last seen, online, photo, about, read receipts, groups, calls);
 `--read-receipts off` also stops the owner seeing others' receipts, and `contacts_except` is shown, never set.
@@ -50,8 +50,8 @@ store: the joins, leaves, adds, removals, admin changes and titles the phone pus
 `stats chats show` counts in `members`; one from before the link the phone did not push is missing. `chats members
 history` shows who joined or left between member fetches. A group in a WhatsApp community names it in `parent_chat_id`, and the
 community itself is a group with `provider_metadata.community: true`, in the store (`chats list`, `chats show`) and
-in the answers of `chats create|join|update`. `chats mark-read` sends a read receipt only and may not clear a
-`chats mark-unread`.
+in the answers of `chats create|join|update`. `chats mark-read` clears the unread mark up to the chosen message
+and sends a read receipt.
 A channel (`…@newsletter`) is followed with `chats join <whatsapp.com/channel link>` and left with `chats leave`;
 `messages sync <channel>` reads its posts from WhatsApp's servers, and every post's sender is the channel.
 `messages send <channel> <text>` posts, with one file (`--photo`, `--file`, `--voice`) or none, only where the owner
@@ -61,7 +61,7 @@ edit or deletion in a channel.
 **Group changes are writes the members see**, and go through the profile's permissions like a send. `chats create`
 and `members add` refuse anyone the owner never wrote to and has not saved — WhatsApp bans accounts that add
 strangers; never work round it. `admins add` takes no `--can`: a WhatsApp admin has every right.
-`chats update --disappear-time` takes 24h, 7d, 90d or off, nothing else. A chat or person named by name is looked up
+`chats update --disappear-after` takes 24h, 7d, 90d or off, nothing else. A chat or person named by name is looked up
 in the store first (part of the name is enough; several matches are refused), then in WhatsApp's chat list; a group
 the store does not hold yet needs its `…@g.us` id.
 `contacts lookup` takes one number on stdin, at most one every 10 seconds per profile; never loop it.
@@ -109,7 +109,7 @@ the store does not hold yet needs its `…@g.us` id.
 
 ## Machine execution
 
-`wa commands schema messages list --json` describes one command's schemas and effects. Use `--json --no-input` for
+`wa commands info messages list --json` describes one command's schemas and effects. Use `--json --no-input` for
 headless work. `--json=id,text` keeps those fields of each list item, with the page and coverage around them. For
 ids use `--json=id`. `--max-output-bytes` and `--max-input-bytes` set byte budgets; one-shot actions default to 30
 seconds, changed with `--timeout`. Before a sensitive write, global `--dry-run` checks syntax and permissions; it
@@ -145,9 +145,8 @@ linking. If your process predates installation, refresh your shell PATH yourself
 - **A refusal with exit code `5`, `7` or `8` on a change is the owner's decision, not a fault.** Do not work around
   it: do not change settings, do not call `wa personal recipients add`, do not wait and retry. Tell the owner the
   send did not go, and why.
-- **Reading marks nothing read** and shows nobody that you looked. Read freely. `wa personal chats mark-read` and
-  `--mark-read` on `messages list`, `inbox` and `review` send a read receipt, and the other side sees it: only when
-  the owner asked. `wa` never sends presence ("online", "typing").
+- **Reading marks nothing read** and shows nobody that you looked. Read freely. `wa personal chats mark-read`
+  sends a read receipt, and the other side sees it: only when the owner asked. `wa` never sends presence ("online", "typing").
 - **Not for:** mass mailing, status posts, other people's accounts, or automatic replies. `wa` has no `replies`, and
   `serve` never answers by itself: WhatsApp bans accounts that answer like a bot, so nothing sends unless the owner
   asked for that message.
@@ -296,6 +295,10 @@ wa personal chats mark-read 100000000000001@lid    # the other side sees it: onl
 wa personal watch --jsonl                          # new messages as they arrive; holds the connection
 ```
 
+For `wa personal watch --jsonl`, read each message from the item record’s `data` field, using snake_case
+keys. With `--events`, `data.event` names the change. Wait for the final `type: "end"` record and check
+`complete`; an absent end means the stream was cut. A source failure also returns a nonzero exit code.
+
 An agent without a terminal (Claude Desktop, Cursor) uses the MCP server instead: `wa personal mcp`. The profile's
 `permissions` decide which commands it offers, through `wa_tools_search`, `wa_read` and `wa_write`; there is no
 confirmation form. `wa personal mcp config` prints the entry with full paths. `wa personal mcp --http --public-url
@@ -307,9 +310,9 @@ Never change permissions to get round a refusal. Guide:
 
 These work on what `wa` has stored and never connect:
 
-- **Conversations:** `wa personal conversations build --chat 120363000000000001@g.us --json` finds the threads in a
+- **Conversations:** `wa personal conversations links rebuild --chat 120363000000000001@g.us --json` finds the threads in a
   group, then `conversations list` and `conversations show`.
-- **People:** `contacts alias set|rm` is a local name, `contacts notes add|list|show|edit|remove` private notes;
+- **People:** `contacts aliases set|remove` is a local name, `contacts notes add|list|show|edit|remove` private notes;
   both stay on this computer and change nothing on WhatsApp. `contacts show --with-notes` includes the notes.
 - **Labels:** `wa personal tags add work --chat 120363000000000001@g.us` labels a chat, person, message or task;
   `tag:work` finds it in a search. `searches create` saves a search; `search messages --saved <name>` runs it.