miaw-core 1.10.0 → 1.12.1

package/.env.example

@@ -19,6 +19,18 @@ MIAW_INSTANCE_ID=default
 MIAW_SESSION_PATH=./sessions-cli
 
 # ─── Proxy (all optional; added in v1.10.0) ──────────────────────────────────
+#
+# Precedence, highest first (v1.11.0):
+#   1. MIAW_PROXY / --proxy        always wins; warns when it shadows a pin
+#   2. a pin in <MIAW_SESSION_PATH>/instances.json, per instance
+#   3. MIAW_PROXY_FILE + strategy  hashed on the TARGET instanceId
+#   4. direct
+#
+# The pin store is written by `miaw-cli instance set-proxy <id> ...`, not by
+# env vars - it is per-instance state, so it belongs with the sessions rather
+# than with process config. It holds credentials when a URL is pinned, so it is
+# written 0600 and must live on the same persistent, secret-grade volume as the
+# session directories. See docs/DEPLOYMENT_INSTANCE_PROXY.md.
 
 # A single proxy for this instance. (flag: --proxy)
 # Schemes: http, https, socks4, socks4a, socks5, socks5h
@@ -33,8 +45,15 @@ MIAW_SESSION_PATH=./sessions-cli
 # MIAW_PROXY=socks5h://user:password@proxy.example.com:1080
 
 # A proxy list file instead of a single proxy — TXT (one per line) or JSON
-# array. One proxy is selected per process using MIAW_PROXY_STRATEGY.
-# Ignored when MIAW_PROXY is also set. (flag: --proxy-file)
+# array. A proxy is selected per instance using MIAW_PROXY_STRATEGY, keyed on
+# the instance the command targets (v1.11.0; before that, once per process
+# against the startup instance).
+# Ignored when MIAW_PROXY is also set, and outranked by a per-instance pin.
+# (flag: --proxy-file)
+#
+# Also required when an instance is pinned by label (`instance set-proxy <id>
+# --label eu`): the label names an entry in THIS file. A label pin that cannot
+# be resolved refuses to connect rather than silently going direct.
 #
 # See examples/proxies.example.txt for the format.
 #

package/CHANGELOG.md

@@ -5,6 +5,299 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.1] - 2026-09-02
+
+### Fixed
+
+Everything here was found by running the CLI integration suite against a
+**live** WhatsApp connection for the first time. All four predate v1.12.0;
+none is an rc14 regression. The suite goes from 15 failures to 0.
+
+- **`--json` emitted unparseable output on seven commands.** `check`,
+  `contact info`, `contact business`, `group info`, `group participants`,
+  `group invite info` and `load messages` printed a progress line to stdout
+  even under `--json`, so a consumer got
+  `SyntaxError: Unexpected token '🔍'`. `--json` exists only for machines, and
+  it was broken for every one of these — invisible interactively, which is why
+  it survived. `load messages` was worse: on failure it printed a human error
+  instead of JSON, so `--json` never produced parseable output there at all.
+  It now emits the result object on both paths.
+- **Catalog commands took 60s to fail on a personal account.** `getCatalog()`
+  and `getCollections()` are Business APIs; asked about a personal account's
+  own catalog, WhatsApp never answers and the call sat until Baileys' 60s
+  default query timeout. They now check the account type first and fail
+  immediately with a message that names the fix (`--phone` to read another
+  business's catalog). Only the own-account case is guarded — `--phone` may
+  legitimately target a business from a personal account. **The CLI suite
+  dropped from 745s to 189s as a result.**
+- **`profile status set` with no text always failed.** The router passed an
+  empty string through with the comment "status can be empty to clear it";
+  WhatsApp rejects an empty about-text, so the documented behaviour never
+  worked. It is now refused up front with an explanation.
+- **`isBlocked()` reported a blocked contact as not blocked.** See below —
+  fixed in the same live session.
+
+### Changed
+
+- `load messages` tests no longer assert success unconditionally. They could
+  not distinguish "this chat has no older history" (expected) from "history
+  loading is broken" (a defect), so they now accept either but require the
+  no-history case to say so.
+
+## [1.12.0] - 2026-09-02
+
+**Baileys 7.0.0-rc14, and the deferred feature backlog cleared.** All additive;
+no breaking changes.
+
+### Changed
+
+- **Operator notes:** [docs/DEPLOYMENT_V1.12.0.md](docs/DEPLOYMENT_V1.12.0.md) —
+  no env, migration or state-format changes; rollback does not require re-pairing.
+- **Upgraded `@whiskeysockets/baileys` from `7.0.0-rc13` to `7.0.0-rc14`** (pinned
+  exactly, as before). Four substantive upstream commits:
+  - WhatsApp Web version `2.3000.1035194821` → `2.3000.1043857760`. Low impact —
+    `resolveWAVersion()` already prefers the live version from `web.whatsapp.com`,
+    so the bundled constant is only the third-tier fallback — but a fresher
+    fallback is still worth having.
+  - **`profilePictureUrl` fix.** The privacy `tctoken` now nests under the
+    `picture` query node and carries a `t` attribute, matching WA Web. This
+    affects `getContactInfo()`, `getProfilePicture()` and `getChatInfo()` when
+    the target has profile-picture privacy enabled.
+  - New `Browsers.android()` identity (see below).
+  - An internal `Long` type import fix.
+
+  No public API changed; miaw-core's whole Baileys surface — including the
+  `updateBussinesProfile` typo, `signalRepository.lidMapping`, the hand-built
+  `remove-companion-device` node, `messaging-history.set` `lidPnMappings`, the
+  `resyncAppState` collection names, and the dispatcher passed into
+  `downloadMediaMessage` — is byte-identical between the two releases.
+
+### Added
+
+- **`BrowserPresets`** — `macOS`, `windows`, `ubuntu` and `android` browser
+  identities for the `browser` option, which was previously undocumented outside
+  its JSDoc. The default is unchanged (`macOS("Chrome")`).
+- **Android connection identity.** `BrowserPresets.android()` negotiates as an
+  Android client rather than a web one. Baileys reports this is required to
+  **receive view-once media**, which a web session is never sent
+  ([#2201](https://github.com/WhiskeySockets/Baileys/pull/2201)); miaw-core
+  already normalizes view-once messages, so if that holds,
+  `message.media.viewOnce` and `downloadMedia()` work with no further change.
+  The handshake is verified here; the view-once receipt itself is upstream's
+  claim and is **not** confirmed end-to-end — see `tests/verify-viewonce.ts` to
+  check it on your own account. Baileys marks the identity experimental; prefer
+  a dedicated `instanceId` over switching an established session.
+- **Group & community administration.** `setGroupAnnounceOnly`,
+  `setGroupRestrictInfo`, `setGroupMemberAddMode`, `setGroupJoinApproval`,
+  `setGroupEphemeral`, `getGroupJoinRequests`, `approveGroupJoinRequests`,
+  `rejectGroupJoinRequests`, and the eight `setCommunity*` /
+  `*CommunityJoinRequests` equivalents.
+- **Privacy settings.** `getPrivacySettings()` plus `setLastSeenPrivacy`,
+  `setOnlinePrivacy`, `setProfilePicturePrivacy`, `setStatusPrivacy`,
+  `setReadReceiptsPrivacy`, `setGroupAddPrivacy`, `setMessagesPrivacy`,
+  `setCallPrivacy`, `setDefaultDisappearingMode` and `setLinkPreviewsDisabled`.
+- **Blocklist.** `blockContact()`, `unblockContact()`, `getBlocklist()`,
+  `isBlocked()`.
+- **Calls.** A new `call` event carrying a normalized `MiawCall`, plus
+  `rejectCall()` and `createCallLink()`. A single call fires the event several
+  times as it progresses; `status === "offer"` is the only stage at which
+  `rejectCall()` still works.
+- **Disappearing messages.** `setChatEphemeral()` for 1:1 chats alongside the
+  group and community variants, with an `EphemeralDuration` constant for the four
+  durations the WhatsApp UI offers.
+- **Group invite cards.** `sendGroupInvite()` sends the rich "join my group" card
+  rather than a pasted link. Its payload type is `GroupInviteMessage` — distinct
+  from the existing `GroupInviteInfo`, which is the *preview* returned by
+  `getGroupInviteInfo()` before joining.
+- **Pin-in-chat.** `pinMessage()` / `unpinMessage()`, with a `PinDuration`
+  constant. WhatsApp accepts only 24h, 7d and 30d here — a different set from the
+  disappearing-message durations.
+- **CLI:** `group|community announce|restrict|add-mode|approval|ephemeral`,
+  `group|community requests list|approve|reject`, `privacy
+  show|set|disappearing|link-previews`, `block list|add|remove`, `call link`,
+  `chat ephemeral|pin-message|unpin-message`, and `send group-invite`. All with
+  tab completion and `help` topics.
+- **`tests/unit/baileys-export-surface.test.ts`** — imports Baileys unmocked and
+  asserts every symbol the two import sites destructure still exists. Seventeen
+  unit suites replace the module wholesale with hand-written factories, so
+  without this a renamed or removed upstream export stays invisible until
+  runtime.
+
+### Fixed
+
+- **`isBlocked()` reported a blocked contact as not blocked.** WhatsApp
+  returns the blocklist in whatever addressing mode it holds per contact, and
+  on a privacy-enabled account that is a `@lid` rather than a phone JID —
+  blocking `628…` produced a blocklist of `["270819297075205@lid"]`. The
+  original plain `includes(phoneJid)` therefore always missed. It now compares
+  both directions, using the LID this account knows for the number and, failing
+  that, resolving each blocked LID back to a phone JID. Found only by live
+  testing; every mock in the unit suite returned phone JIDs.
+- **`npx miaw-cli` was broken for every consumer, published or local.**
+  `bin.miaw-cli` pointed at `bin/miaw-cli.ts` — a TypeScript file carrying a
+  `#!/usr/bin/env node` shebang and importing from `../src/**`. A bin runs
+  under the user's plain `node`, which cannot resolve TypeScript's
+  `.js`-for-`.ts` specifiers; and `.npmignore` excludes `src/` from the
+  tarball, so the published package shipped an entry point that could not
+  find its own imports. The entry logic moved to `src/cli/main.ts` (so `tsc`
+  compiles it into `dist/`), `bin/miaw-cli.mjs` is the published executable,
+  and `bin/miaw-cli.ts` remains the tsx development shim behind
+  `npm run cli`.
+- **`dotenv` was a devDependency but is imported at runtime**, so an
+  installed package failed on startup with `ERR_MODULE_NOT_FOUND`. Moved to
+  `dependencies`. Found by `npm pack` + installing the tarball into a clean
+  directory — neither bug is visible from inside the repo, where `src/`
+  exists and devDependencies are installed.
+- **`community invite-link` was advertised but never worked.** The subcommand
+  list printed by `community` has named it since v1.9.0, but the dispatch
+  switch had no `case` for it, so it fell through to the unknown-command
+  branch and always errored. `group invite-link` has existed since v1.4.
+- **Five `help` topics tab-completed and then failed.** `help chat|story|
+  community|call|business` were offered by completion but had no case in
+  `showReplHelp()`, printing "Unknown help topic". The completion tree, the
+  dispatch and two "available topics" lines were four hand-maintained copies
+  of the same list; they are now all derived from one `HELP_TOPIC_HANDLERS`
+  map, and the five missing help screens were written.
+- **`test:manual:build` never worked and has been removed.** It ran
+  `node dist/tests/interactive-test.js`, but `tsconfig.json` sets
+  `rootDir: ./src` and excludes `tests/`, so `dist/tests/` is never emitted.
+- **`sendGroupInvite()` failed for any group without a profile picture.** Baileys
+  embeds a thumbnail on the invite card by calling `getProfilePicUrl(groupJid)`
+  and does not guard it; WhatsApp answers `item-not-found` for a pictureless
+  group, which throws and aborts the whole send. Since most groups have no
+  picture, the unguarded path failed more often than it worked. `sendGroupInvite`
+  now passes its own guarded hook — Baileys spreads caller options last, so it
+  wins — and sends the card without a thumbnail rather than not at all. Found by
+  live testing; it is invisible to unit tests because the mock never throws.
+- **Omitting a disappearing-message duration silently disabled it.**
+  `miaw-cli group ephemeral <jid>` with no duration turned disappearing messages
+  **off** for the whole group instead of printing a usage line — `Number("")` is
+  `0`, and `0` is a valid duration meaning "off", so the missing argument parsed
+  as a successful request to disable. Same for `community ephemeral`,
+  `chat ephemeral`, and `privacy disappearing` (which changed an account-wide
+  default). Found in review of this release, before any of it shipped.
+- **`--force` could swallow the following token.** It was missing from
+  `BOOLEAN_FLAGS` in `bin/miaw-cli.ts`, the same class of bug that `--json` hit
+  previously.
+- **CLI docs gap.** `chat` commands were entirely undocumented in
+  [CLI.md](docs/CLI.md) despite shipping in v1.7.0; they now have a section.
+
+### Verified live
+
+Against a real WhatsApp connection (Baileys rc14):
+
+- **`profilePictureUrl`** — the upstream tctoken-nesting fix. 2 of 5 real
+  contacts resolved to live URLs; the rest correctly returned `null`.
+- **`getPrivacySettings()`** — WhatsApp returned 16 categories; the 8 with
+  Baileys setters map onto typed fields and the other 8 survive under `raw`.
+- **All 19 v1.12.0 write paths** — every group setting toggled and restored with
+  a read-back confirming the change landed, plus 1:1 ephemeral, privacy
+  round-trips, `sendGroupInvite`, pin/unpin, and `createCallLink`. 19/19.
+- **`BrowserPresets.android()`** — WhatsApp issued a QR rather than a 428, so
+  the `Platform.ANDROID` handshake is accepted. End-to-end view-once *receipt*
+  is not yet confirmed; see [FOLLOW_UPS.md](docs/FOLLOW_UPS.md) section 7.
+- **No regressions from rc14.** The CLI integration suite has 15 pre-existing
+  failures, unrelated to this release — running the same six suites against
+  rc13 produced a byte-identical failure set. They are catalogued in
+  [FOLLOW_UPS.md](docs/FOLLOW_UPS.md) section 9.
+
+### Internal
+
+- `jest.config.js` sets `maxWorkers: 1`. The live-connection suites share a
+  single WhatsApp session, and forking one worker per core for a full run is
+  memory-hungry; `test:cli` already passed `--runInBand` for the first reason.
+- CLI integration teardown moved from `10-business-commands.test.ts` to the new
+  `13-privacy-call-commands.test.ts`. Files run in name order and 13 is now the
+  last one needing a connection (11 and 12 are deliberately offline), so
+  disconnecting at 10 would pull the socket out from under it.
+- 623 unit tests across 30 suites (up from 417), 105 CLI router tests (up from
+  26), 278 CLI integration tests across 13 files (up from 238).
+- New `tests/unit/cli-help-consistency.test.ts` and a dispatchability sweep in
+  `01-command-router.test.ts`, both verified to fail against the previous code.
+- The manual runner grew from 82 to 96 entries, and gained a `community` group:
+  all 19 community methods, v1.9.0's included, had been unreachable from it.
+
+## [1.11.0] - 2026-09-02
+
+### Added
+
+- **Per-instance proxy pins (CLI).** `miaw-cli instance set-proxy <id>` persists a
+  proxy assignment to `<session-path>/instances.json`, so
+  `miaw-cli --instance-id bot-3 <command>` uses bot-3's proxy with no flags.
+  Four sources: a positional URL, `--label <name>` (selects a `label=` entry from
+  the proxy file and stores **no credentials**), `--from-env <VAR>`, and
+  `--from-file` (materializes the current deterministic selection).
+  `instance unset-proxy <id>` removes it.
+- `instance ls` gains a Proxy column (masked) and lists instances that are pinned
+  but not yet created as `[not created]` — pinning before `instance create` is
+  supported, so the pairing itself comes from the final egress IP.
+- **`MiawClient.setProxy(proxy)`** — stages a proxy for the **next** `connect()`,
+  returning `{ success, proxy, reconnectRequired, error }`. It never touches a
+  live socket, validates eagerly, and is refused when the client was constructed
+  with a custom `agent`/`fetchAgent`.
+- `getProxyInfo()` gains `active` (is the open socket using this config?) and
+  `pending` (what it is using instead). The `{ url, protocol }` shape and the
+  `null`-for-custom-agent contract are unchanged.
+- New exported types `SetProxyResult` and `ProxyInfo`.
+- A complete, runnable dead-proxy failover recipe in docs/PROXY.md and
+  examples/10-proxy-rotation.ts, reusing a single client.
+- `docs/DEPLOYMENT_INSTANCE_PROXY.md` — operational notes for the new
+  persistent pin store, and `docs/FOLLOW_UPS.md` for deferred findings.
+
+### Behavior changes
+
+- **`ProxyRotator` now defaults to `deterministic`, not `round-robin`.** The docs
+  and CLAUDE.md have always said deterministic is the default; only the CLI
+  actually applied it. The mismatch was silent and severe: following the docs
+  (`new ProxyRotator(urls)` then `next(id)`) gave round-robin, which hands a
+  long-lived session a different egress IP on each call — read by WhatsApp as
+  account takeover. Code changed rather than docs, so the default fails safe.
+  `next()` with no `instanceId` on a defaulted rotator now throws a message
+  naming the fix; pass `{ strategy: "round-robin" }` explicitly to restore the
+  old behavior. Checked against the sibling `miaw-api`, which constructs with an
+  explicit strategy and always calls `next(instanceId)`: unaffected.
+
+### Fixed
+
+- **The CLI silently dropped the proxy.** `instance create`/`connect`/`disconnect`/
+  `logout` built clients from `{instanceId, sessionPath}` only, discarding both
+  `proxy` and `debug`. Since the client cache key ignored the proxy, REPL
+  `connect <id>` cached a proxy-less client that every later command reused —
+  traffic went direct with no indication.
+- **REPL `use <id>` carried the previous instance's proxy** to the next one: it
+  mutated `config.instanceId` in place without re-resolving.
+- **Proxy selection ignored the target instance.** `--proxy-file` was resolved once
+  per process against the *startup* instance id, so `instance connect bot-3` got
+  another instance's egress IP. Resolution is now per target.
+- `instance create` called `createClient()` directly, bypassing the cache, so the
+  freshly-paired live client was never registered and the next command built a
+  second `MiawClient` for the same account.
+- An explicit `disconnect()` emitted `disconnected` twice — once as `"unknown"`
+  from the `connection.update{close}` that Baileys' `end()` fires, then once as
+  `"intentional"`.
+- Console-filter reference leak: the filter was acquired only in the constructor
+  but released on every `disconnect()`/`logout()`, so a reconnect cycle lost this
+  client's reference and repeated cycles un-filtered other live clients' output.
+- Proxy transports leaked: `connect()` built fresh agents on every call, auto-
+  reconnects included, and never released the old ones.
+- `.cli_history` was written 0644 with every line verbatim, so an
+  `instance set-proxy` command turned it into a plaintext credential store. Now
+  redacted at entry and written 0600.
+- **Global boolean flags swallowed the command name.** The arg parser assumed
+  every `--flag` took a value, so `miaw-cli --json instance ls` parsed as
+  `json="instance"` and failed with "Unknown command: ls" — even though
+  `--json` is documented as a global option. Value-less flags (`--json`,
+  `--debug`, `--ip`, `--from-file`, `--help`, `--version`) are now recognised
+  as booleans in any position.
+- **`src/utils/proxy-rotator.ts` contained a literal NUL byte**, which made
+  `file(1)` classify the source as binary and caused `grep` to skip it in any
+  repo-wide search. Replaced with the equivalent escape sequence; verified
+  runtime-identical, so no instance is remapped to a different proxy.
+- **Docs: `fetchAgent` is an `http.Agent`, not an undici Dispatcher.** The JSDoc
+  and three doc sites claimed otherwise; the PROXY.md "Custom agents" snippet was
+  copy-pasteable and would silently break every media upload through the proxy.
+  Also corrects the `createProxyAgents` API-table row and two broken anchors.
+
 ## [1.10.0] - 2026-07-29
 
 **Proxy files, rotation, and CLI diagnostics** - builds on the v1.3.0 proxy core.

package/README.md

@@ -10,7 +10,7 @@ Miaw Core abstracts away the complexity of Baileys, providing a clean, simple AP
 
 | Aspect                 | Baileys (Direct)              | Miaw Core                          |
 | ---------------------- | ----------------------------- | ---------------------------------- |
-| **Learning Curve**     | Steep - 150+ methods to learn | Gentle - 92 focused methods        |
+| **Learning Curve**     | Steep - 150+ methods to learn | Gentle - ~200 focused methods      |
 | **Setup Code**         | 50-100 lines boilerplate      | 10 lines to start                  |
 | **Session Management** | Manual auth state handling    | Automatic file-based persistence   |
 | **Reconnection**       | DIY implementation            | Built-in with configurable retries |
@@ -30,6 +30,7 @@ For a detailed comparison, see [Baileys vs Miaw Core Comparison](./docs/BAILEYS_
 - **[Usage Guide](./docs/USAGE.md)** - Complete guide for all current features
 - **[Proxy Guide](./docs/PROXY.md)** - Proxies, proxy list files, and rotation strategies
 - **[Proxy Deployment Notes](./docs/DEPLOYMENT_PROXY.md)** - Operational guidance for deploying with proxies
+- **[Per-Instance Proxy Deployment](./docs/DEPLOYMENT_INSTANCE_PROXY.md)** - What v1.11.0 changes for operators
 - **[LID Resolution](./docs/LID_RESOLUTION.md)** - Working with privacy-masked (`@lid`) JIDs
 - **[Baileys Comparison](./docs/BAILEYS_VS_MIAW_COMPARISON.md)** - Feature comparison with raw Baileys
 - **[Migration Guide](./docs/MIGRATION.md)** - Upgrading between versions
@@ -44,7 +45,7 @@ For a detailed comparison, see [Baileys vs Miaw Core Comparison](./docs/BAILEYS_
 - **Auto-Reconnection** - Handles connection drops and reconnects automatically
 - **Session Management** - File-based session storage with automatic persistence
 - **Multiple Instances** - Run multiple WhatsApp connections in a single process
-- **Proxy Support** - HTTP/HTTPS/SOCKS proxies, proxy list files, and per-instance rotation
+- **Proxy Support** - HTTP/HTTPS/SOCKS proxies, proxy list files, and per-instance proxies (assigned or pinned)
 - **TypeScript Support** - Full type definitions for excellent IDE experience
 - **Event-Driven** - Easy-to-use event system for messages and connection states
 - **Normalized Messages** - Simplified message format, no more complex Baileys structures
@@ -132,7 +133,7 @@ For more examples and detailed usage, see the [Usage Guide](./docs/USAGE.md).
 
 ### Manual Interactive Testing
 
-Test all 92 API methods interactively:
+Drive the API interactively against a live connection:
 
 ```bash
 # Show available test groups
@@ -147,17 +148,34 @@ npm run test:manual business    # Business features only
 
 **Available test groups:**
 
-| Group        | Description                     | Methods |
-| ------------ | ------------------------------- | ------- |
-| `core`       | Connection, lifecycle           | 6       |
-| `get`        | Fetch contacts, groups, chats   | 6       |
-| `messaging`  | Send/receive, reactions, edit   | 12      |
-| `contacts`   | Check numbers, contact info     | 7       |
-| `group`      | Create, manage participants     | 13      |
-| `profile`    | Update picture, name, status    | 4       |
-| `business`   | Labels, catalog (Business only) | 10      |
-| `newsletter` | Channels, subscriptions         | 6       |
-| `ux`         | Typing, presence, read receipts | 5       |
+| Group        | Description                                     |
+| ------------ | ----------------------------------------------- |
+| `core`       | Connection, lifecycle                           |
+| `get`        | Fetch contacts, groups, chats                   |
+| `messaging`  | Send/receive, reactions, edit, pin, invites     |
+| `contacts`   | Check numbers, contact info                     |
+| `group`      | Create, manage participants, admin settings     |
+| `community`  | Communities, linked groups, admin, join requests|
+| `profile`    | Update picture, name, status                    |
+| `business`   | Labels, catalog (Business only)                 |
+| `newsletter` | Channels, subscriptions                         |
+| `ux`         | Typing, presence, read receipts                 |
+| `privacy`    | Privacy settings, block / unblock               |
+| `calls`      | Call event, reject, call links                  |
+
+Run `npm run test:manual` with no argument for this list with a live entry count
+per group — it is generated from the runner's own category map, so it cannot go
+stale.
+
+**Unattended mode:**
+
+```bash
+npm run test:manual:auto              # every group, no prompts, non-zero exit on failure
+npm run test:manual group -- --auto   # one group
+```
+
+Prompts resolve to their `.env.test` defaults. Entries needing a human are
+skipped; add `--destructive` to include the ones that change real state.
 
 **Features:**
 
@@ -165,25 +183,36 @@ npm run test:manual business    # Business features only
 - Tracks test results with pass/fail/skip status
 - Generates summary report with timestamps
 - Pre-loads test configuration from `.env.test`
-
-See [Test Coverage Analysis](./docs/TEST_COVERAGE_ANALYSIS.md) for detailed coverage report.
+- Warns when `.env.test` is configured in a way that silently invalidates
+  results (e.g. both contact numbers set to the bot's own number)
 
 ### Unit & Integration Tests
 
 ```bash
-# Run all tests
+# Unit suites only - the fast gate (615 tests, no connection needed)
+npm run test:unit
+
+# Everything, including the live-connection suites
 npm test
 
-# Run in watch mode
-npm run test:watch
+# CLI command tests against a real connection (13 files)
+npm run test:cli
+
+# Type-check src/ and tests/ together
+npm run typecheck
 
-# Generate coverage report
+# Watch mode / coverage
+npm run test:watch
 npm run test:coverage
 ```
 
-## Current Capabilities (v1.10.0)
+> Jest runs serially (`maxWorkers: 1`): the live suites share one WhatsApp
+> session, so a parallel run would have them fighting over it. For the same
+> reason, never run two test commands at once.
+
+## Current Capabilities (v1.12.1)
 
-Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementation.
+Built on **Baileys v7.0.0-rc14** - the latest WhatsApp Web protocol implementation.
 
 ### Core Features
 
@@ -200,11 +229,19 @@ Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementati
 ### Networking
 
 - ✅ HTTP / HTTPS / SOCKS4 / SOCKS5 proxies, per instance
+- ✅ Per-instance proxy pins that persist — `miaw-cli instance set-proxy <id> ...`, then no flags needed
+- ✅ `client.setProxy()` — stage a proxy for the next connect (never rotates a live session's IP)
 - ✅ Proxy list files (TXT / JSON) with validation and hot reload
 - ✅ Rotation strategies (round-robin, random, weighted, deterministic-per-instance)
 - ✅ `miaw-cli proxy test` connectivity diagnostics — no WhatsApp connection needed
 - ⚠️ SOCKS proxies: media *downloads* use a direct connection ([details](./docs/PROXY.md#️-socks-media-downloads-use-a-direct-connection))
 
+### Connection Identity
+
+- ✅ Configurable browser identity via `BrowserPresets` (macOS / Windows / Ubuntu / Android)
+- ✅ Android identity — Baileys reports this is required to **receive view-once media** ([details](./docs/USAGE.md#receiving-view-once-messages-android-identity))
+- ✅ Live WhatsApp Web version negotiation (avoids stale-version 428 rejections)
+
 ### Advanced Messaging
 
 - ✅ Reply/quote messages
@@ -212,6 +249,10 @@ Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementati
 - ✅ Delete messages
 - ✅ Message reactions
 - ✅ Forward messages
+- ✅ Location, contact cards, polls and stickers
+- ✅ Group invite cards — `sendGroupInvite()`
+- ✅ Pin / unpin a message in a chat — `pinMessage()` / `unpinMessage()`
+- ✅ Disappearing messages per chat — `setChatEphemeral()`
 
 ### Group Management
 
@@ -220,6 +261,39 @@ Built on **Baileys v7.0.0-rc13** - the latest WhatsApp Web protocol implementati
 - ✅ Promote/demote admins
 - ✅ Group invite links
 - ✅ Update group settings
+- ✅ Announce-only and info-edit locks
+- ✅ Member-add mode (admins only / all members)
+- ✅ Join approval, plus listing / approving / rejecting join requests
+- ✅ Group-wide disappearing messages
+
+### Communities
+
+- ✅ Create communities, link and unlink groups
+- ✅ Community members: add, remove, promote, demote
+- ✅ Community invite links
+- ✅ The same admin surface as groups — announce, restrict, add-mode,
+     join approval, join requests, disappearing messages
+
+### Privacy & Blocklist
+
+- ✅ Read all privacy settings, including categories Baileys has no setter for
+     (preserved under `raw`)
+- ✅ Eight setters — last seen, online, profile picture, status, read receipts,
+     group add, messages, calls
+- ✅ Default disappearing mode for new chats, and link-preview control
+- ✅ Block / unblock, list the blocklist, check whether a contact is blocked
+
+### Calls
+
+- ✅ `call` event for incoming calls (offer / accept / reject / timeout)
+- ✅ Reject an incoming call — `rejectCall()`
+- ✅ Create shareable call links — `createCallLink()`
+
+### Chat Management
+
+- ✅ Archive, pin, mute, mark read/unread
+- ✅ Clear or delete a chat
+- ✅ Star / unstar messages
 
 ### Profile Management
 
@@ -256,16 +330,20 @@ Miaw Core handles these Baileys complexities for you:
 
 ```text
 miaw-core/
+├── bin/
+│   └── miaw-cli.ts      # CLI entry point (one-shot + REPL)
 ├── src/
 │   ├── client/          # Main MiawClient class
 │   ├── handlers/        # Auth and message handlers
 │   ├── types/           # TypeScript definitions
-│   ├── utils/           # Storage utilities
+│   ├── constants/       # Shared constant tables
+│   ├── utils/           # Proxy agents, rotation, browser presets
+│   ├── cli/             # CLI subsystem (commands + utils)
 │   └── index.ts         # Public API exports
 ├── docs/                # Documentation
 ├── examples/            # Usage examples
-├── tests/               # Unit and integration tests
-└── README.md           # This file
+├── tests/               # Unit, integration and CLI integration tests
+└── README.md            # This file
 ```
 
 ## Contributing
@@ -290,8 +368,8 @@ MIT
 
 ## Credits
 
-Built on top of [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys) v7.0.0-rc13
+Built on top of [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys) v7.0.0-rc14
 
 ---
 
-**Version:** 1.4.1 | **Baileys:** 7.0.0-rc13 | **Status:** Stable | **Updated:** 2026-06-26
+**Version:** 1.12.1 | **Baileys:** 7.0.0-rc14 | **Status:** Stable | **Updated:** 2026-09-02

package/bin/miaw-cli.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * miaw-cli executable (published entry point).
+ *
+ * Plain JavaScript on purpose: `bin` entries are run by whatever `node` the
+ * user has, with no TypeScript loader. The previous entry was a .ts file with
+ * a `#!/usr/bin/env node` shebang that imported from ../src/**, so it failed
+ * twice over -- node cannot resolve TypeScript's `.js`-for-`.ts` specifiers,
+ * and .npmignore excludes src/ from the published package entirely.
+ *
+ * Requires a build: run `npm run build` first, or use `npm run cli` (tsx) for
+ * development against the sources.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, "..", "dist", "cli", "main.js");
+
+if (!existsSync(entry)) {
+  console.error("❌ miaw-cli: dist/ is missing — the package was not built.");
+  console.error("   Run `npm run build`, or use `npm run cli` to run from source.");
+  process.exit(1);
+}
+
+const { main } = await import(entry);
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/dist/cli/commands/call.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Call Commands (v1.12.0)
+ *
+ * Create shareable call links. Rejecting a call is an event-driven operation —
+ * it only works while a call is ringing — so it belongs in a bot's `call`
+ * handler rather than on the CLI.
+ */
+import { MiawClient } from "../../index.js";
+/**
+ * Create a shareable call link
+ */
+export declare function cmdCallLink(client: MiawClient, args: {
+    type: "audio" | "video";
+    startTime?: number;
+}): Promise<boolean>;
+//# sourceMappingURL=call.d.ts.map

package/dist/cli/commands/call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/call.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAI5C;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,OAAO,CAAC,OAAO,CAAC,CAmBlB"}

package/dist/cli/commands/call.js

@@ -0,0 +1,29 @@
+/**
+ * Call Commands (v1.12.0)
+ *
+ * Create shareable call links. Rejecting a call is an event-driven operation —
+ * it only works while a call is ringing — so it belongs in a bot's `call`
+ * handler rather than on the CLI.
+ */
+import { ensureConnected } from "../utils/session.js";
+import { formatMessage } from "../utils/formatter.js";
+/**
+ * Create a shareable call link
+ */
+export async function cmdCallLink(client, args) {
+    const conn = await ensureConnected(client);
+    if (!conn.success) {
+        console.log(`❌ Not connected: ${conn.reason}`);
+        return false;
+    }
+    console.log(`🔗 Creating ${args.type} call link...`);
+    const link = await client.createCallLink(args.type, args.startTime);
+    if (!link) {
+        console.log(formatMessage(false, "Failed to create call link"));
+        return false;
+    }
+    console.log(formatMessage(true, "Call link created"));
+    console.log(`\n${link}\n`);
+    return true;
+}
+//# sourceMappingURL=call.js.map

package/dist/cli/commands/call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call.js","sourceRoot":"","sources":["../../../src/cli/commands/call.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAkB,EAClB,IAAqD;IAErD,MAAM,IAAI,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,IAAI,eAAe,CAAC,CAAC;IAErD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAEpE,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAC,CAAC;QAChE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC"}