miaw-core 1.10.0 → 1.12.0

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,237 @@ 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.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
+
+- **`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.
+- 615 unit tests across 29 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.0)
 
-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.0 | **Baileys:** 7.0.0-rc14 | **Status:** Stable | **Updated:** 2026-09-02

package/bin/miaw-cli.ts

@@ -17,10 +17,15 @@ import { runRepl } from "../src/cli/repl.js";
 import { runCommand } from "../src/cli/commands/index.js";
 import { initializeCLICleanup } from "../src/cli/utils/cleanup.js";
 import { getErrorMessage } from "../src/utils/type-guards.js";
+import {
+  configFromResolved,
+  describeProxySource,
+  resolveProxyForInstance,
+  type ProxyResolutionBase,
+} from "../src/cli/utils/proxy-resolver.js";
 import { maskProxyUrl } from "../src/utils/proxy-agent.js";
 import {
   parseProxyStrategy,
-  selectProxyForInstance,
 } from "../src/cli/utils/proxy-config.js";
 
 // Initialize CLI cleanup handlers for graceful shutdown
@@ -38,6 +43,12 @@ const DEFAULT_PROXY = process.env.MIAW_PROXY || undefined;
 const DEFAULT_PROXY_FILE = process.env.MIAW_PROXY_FILE || undefined;
 const DEFAULT_PROXY_STRATEGY_ENV = process.env.MIAW_PROXY_STRATEGY || undefined;
 
+/**
+ * Global flags that never take a value. Listed explicitly because the parser is
+ * positional: without this an `--ip`-style flag consumes the command name.
+ */
+const BOOLEAN_FLAGS = new Set(["json", "debug", "help", "version", "ip", "from-file", "force"]);
+
 /**
  * Parse CLI arguments
  */
@@ -53,6 +64,14 @@ function parseArgs(args: string[]): {
     const arg = args[i];
     if (arg.startsWith("--")) {
       const flagName = arg.slice(2);
+      // Value-less flags must never swallow the next token. `--json instance ls`
+      // otherwise parsed as json="instance", leaving the command empty and
+      // reporting "Unknown command: ls" - even though --json is documented as a
+      // global option, i.e. valid before the command.
+      if (BOOLEAN_FLAGS.has(flagName)) {
+        flags[flagName] = true;
+        continue;
+      }
       const nextArg = args[i + 1];
       if (nextArg && !nextArg.startsWith("--")) {
         flags[flagName] = nextArg;
@@ -95,7 +114,8 @@ GLOBAL FLAGS:
   --debug                                     Enable verbose logging
 
 COMMANDS:
-  instance    Manage instances (ls, status, create, delete, connect, disconnect, logout)
+  instance    Manage instances (ls, status, create, delete, connect, disconnect,
+              logout, set-proxy, unset-proxy)
   get         Fetch data (profile, contacts, groups, chats, messages, labels)
   load        Load older messages from history
   send        Send messages (text, image, document)
@@ -118,6 +138,14 @@ EXAMPLES:
   miaw-cli contact add 6281234567890 "John Doe"
   miaw-cli proxy test socks5://proxy.example.com:1080
   miaw-cli --instance-id bot-3 --proxy-file ./proxies.txt get groups
+  miaw-cli instance set-proxy bot-3 --label eu     Pin a proxy, no credentials stored
+  miaw-cli --instance-id bot-3 get groups          Uses bot-3's pinned proxy, no flags
+
+PROXY PRECEDENCE (highest first):
+  --proxy / MIAW_PROXY  >  pinned in <session-path>/instances.json
+                        >  --proxy-file  >  direct
+  A pin applies on the instance's NEXT connect. Never change a live session's
+  egress IP - WhatsApp reads that as account takeover.
 
 REPL MODE:
   Run 'miaw-cli' without arguments to start interactive mode.
@@ -161,38 +189,55 @@ async function main() {
     process.exit(1);
   }
 
-  // Precedence: an explicit --proxy always wins; otherwise a --proxy-file
-  // selects one proxy for this process. The default strategy is
-  // deterministic so a given instanceId keeps a stable egress IP across
-  // invocations - round-robin here would silently rotate a live session's IP.
-  let proxyUrl = explicitProxy;
-  if (explicitProxy && proxyFile) {
-    console.log("⚠️  --proxy overrides --proxy-file");
-  } else if (!explicitProxy && proxyFile) {
-    try {
-      proxyUrl = await selectProxyForInstance(proxyFile, proxyStrategy, instanceId);
-    } catch (error: unknown) {
-      console.error(`❌ Failed to select a proxy from ${proxyFile}: ${getErrorMessage(error)}`);
-      process.exit(1);
-    }
-  }
-
-  // Create client configuration
-  const clientConfig = {
-    instanceId,
+  // Precedence lives in one place - see src/cli/utils/proxy-resolver.ts:
+  //   --proxy  >  pin in instances.json  >  --proxy-file  >  direct
+  // Selection is keyed on this instanceId, and commands targeting a *different*
+  // instance re-resolve rather than reusing what the process started with.
+  const proxyBase: ProxyResolutionBase = {
     sessionPath,
     debug: debugMode,
-    ...(proxyUrl && { proxy: proxyUrl }),
+    ...(explicitProxy && { explicitProxy }),
     ...(proxyFile && { proxyFile }),
     proxyStrategy,
   };
 
+  // A failure here is reported but does NOT exit. A bad pin would otherwise
+  // lock the operator out of `instance unset-proxy` and `instance ls` - the
+  // commands that repair it. The config instead carries `proxyError`, and
+  // createClient() refuses to build a client, so nothing connects direct.
+  let clientConfig;
+  let resolvedProxy;
+  try {
+    // Resolve once, then build the config from that result: resolving twice
+    // would print every override warning twice.
+    resolvedProxy = await resolveProxyForInstance(proxyBase, instanceId);
+    clientConfig = configFromResolved(proxyBase, instanceId, resolvedProxy);
+  } catch (error: unknown) {
+    const reason = getErrorMessage(error);
+    console.error(`❌ ${reason}`);
+    console.error(
+      `   Commands needing a connection will refuse until this is fixed; ` +
+        `"instance unset-proxy ${instanceId}" removes the pin.`
+    );
+    resolvedProxy = { source: "none" as const };
+    clientConfig = {
+      ...configFromResolved(proxyBase, instanceId, resolvedProxy),
+      proxyError: reason,
+    };
+  }
+
+  const proxyUrl = clientConfig.proxy;
+
   // No command provided - start REPL
   if (!command) {
     console.log(`\n🚀 Starting miaw-cli REPL...`);
     console.log(`📂 Instance: ${instanceId}`);
     console.log(`📂 Session: ${sessionPath}`);
-    if (proxyUrl) console.log(`🌐 Proxy: ${maskProxyUrl(proxyUrl)}`);
+    if (proxyUrl) {
+      console.log(
+        `🌐 Proxy: ${maskProxyUrl(proxyUrl)} (${describeProxySource(resolvedProxy.source)})`
+      );
+    }
     console.log(`🔧 Debug: ${debugMode ? "ON" : "OFF"}\n`);
 
     try {

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